alkdev/alknet
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6219a323b6a855335f08f3c1d51740a544863c62
alknet/docs/architecture/README.md
glm-5.1 6219a323b6 docs(architecture): untangle TLS identity use cases, remove phase framing, add ADR-013 Rust canonical + agent crate 
- Rewrite OQ-12: separate two distinct TLS identity use cases (RFC 7250
  raw keys as default for P2P, X.509 for domain-hosted/browsers) instead
  of conflating them as 'file paths now, ACME later'. ACME is a proven
  pattern from the reverse-proxy project, not speculative future work.

- Resolve OQ-13 and OQ-14: remove 'Phase 1' framing from core crate
  specs. /{service}/{op} is the correct design for alknet-call, not a
  simplification. Batch as correlated call.requested events is the correct
  protocol design. Core crates need to be done right from the start.

- Add ADR-013: Rust as canonical implementation language. TypeScript
  @alkdev/operations is a reference that informed the design, not a
  parallel implementation. The only JS use case is browser SDK adaptation.
  Five reasons: memory safety, LLM competence, supply chain attacks,
  performance, browser-only JS.

- Add alknet-agent crate to the crate graph (depends on alknet-call, not
  alknet-core). Agent service uses call protocol client for tool dispatch
  and vault/derive for provider keys — no env vars for secrets. ALPN
  alknet/agent added to the registry.

- Add OQ-15: call protocol client and adapter contract. alknet-call needs
  both server (CallAdapter) and client (remote invocation over QUIC), plus
  the adapter traits (from_*, to_*) that enable composition.

- Clarify alknet-napi as thin NAPI projection layer, not business logic.

- Fix bugs: ProtocolController → ProtocolHandler typo, OperationEnv
  invoke() path format inconsistency, RateLimitConfig comment confusion.

- Update endpoint.md TLS section: comprehensive identity model comparison
  table, RFC 7250 as default mode, ACME as proven pattern.
2026-06-17 09:32:44 +00:00

5.9 KiB
Raw Blame History

status, last_updated
status last_updated
draft 2026-06-17

Alknet Architecture

Current State

Pre-implementation. The project has completed a pivot from a three-layer model to an ALPN-as-service model. The greenfield workspace contains only alknet-vault (stable) and research/reference material. Foundational ADRs (001–013) are in place, including the BiStream type definition (ADR-007), vault integration (ADR-008), ALPN router/endpoint (ADR-010), AuthContext structure (ADR-011), call protocol stream model (ADR-012), and Rust as canonical implementation language (ADR-013). The alknet-core and alknet-call crate specs are in draft.

Next step: Review alknet-call spec documents, then begin implementation. OQ-11 (handler-level auth resolution observability) will be resolved during implementation.

Architecture Documents

Document Status Description
overview.md draft Workspace-level overview, crate graph, shared types, design principles
open-questions.md draft Centralized OQ tracker with door-type classifications
crates/core/README.md draft alknet-core crate index
crates/core/core-types.md draft ProtocolHandler, HandlerError, Connection, BiStream, StreamError
crates/core/endpoint.md draft ALPN router, HandlerRegistry, accept loop, shutdown
crates/core/auth.md draft AuthContext, Identity, IdentityProvider, AuthToken, resolution flow
crates/core/config.md draft StaticConfig, DynamicConfig, ArcSwap, ConfigReloadHandle
crates/call/README.md draft alknet-call crate index
crates/call/call-protocol.md draft CallAdapter, EventEnvelope framing, stream model, PendingRequestMap, bidirectional calls
crates/call/operation-registry.md draft OperationSpec, Handler, OperationRegistry, AccessControl, service discovery, irpc integration

ADR Table

ADR Title Status
001 ALPN-Based Protocol Dispatch Accepted
002 ProtocolHandler Trait Accepted
003 Crate Decomposition Accepted
004 Auth as Shared Core (IdentityProvider) Accepted
005 irpc as Call Protocol Foundation Accepted
006 ALPN String Convention and Connection Model Accepted
007 BiStream Type Definition Accepted
008 Vault Integration Point Accepted
009 One-Way Door Decision Framework Accepted
010 ALPN Router and Endpoint Accepted
011 AuthContext Structure and Resolution Flow Accepted
012 Call Protocol Stream Model Accepted
013 Rust as Canonical Implementation Language Accepted

Open Questions

See open-questions.md for the full tracker.

Resolved one-way doors:

  • OQ-01: BiStream type — trait with Connection parameter (ADR-007)
  • OQ-02: AuthContext timing — hybrid model (ADR-004)
  • OQ-03: ALPN naming — alknet/ prefix, no version (ADR-006)
  • OQ-05: Multi-connectivity endpoint — quinn + iroh, both feature-gated (ADR-010)
  • OQ-06: ALPN per connection, not per stream (ADR-006)
  • OQ-08: Vault integration — CLI-embedded via call protocol (ADR-008)

Resolved two-way doors:

  • OQ-04: Dynamic handler registration — static at startup (ADR-010)
  • OQ-07: Call protocol scope — bidirectional streams, EventEnvelope, ID-based correlation (ADR-012)
  • OQ-12: TLS identity provisioning — two use cases: RFC 7250 raw keys (default, P2P) and X.509 certs (domain-hosted, browsers). ACME is a proven pattern.
  • OQ-13: Operation path format — /{service}/{op} is the correct design for alknet-call, not a simplification
  • OQ-14: Batch operation semantics — multiple correlated call.requested events is the correct protocol design, not a simplification

Open two-way doors (resolved during implementation):

  • OQ-11: Handler-level auth resolution observability — decide during implementation

Open one-way doors (need ADR before implementation):

  • OQ-15: Call protocol client and adapter contract — alknet-call needs both the server (CallAdapter) and client (call invocation over QUIC), plus the adapter contract traits (from_, to_) that enable composition

Deferred (not active):

  • OQ-09: WASM target boundaries — design constraint, not deliverable
  • OQ-10: Git adapter scope — start with smart protocol, add ERC721 later

Document Lifecycle

Status Meaning Transitions
draft Under active development. May change significantly. → reviewed when open questions are resolved
reviewed Architecture is final. Implementation may begin. Changes require review. → stable when implementation is complete and verified
stable Locked. Changes require review and may warrant an ADR. → deprecated when superseded
deprecated Superseded. Kept for reference. Removed when no longer referenced

References

  • Pivot proposal: docs/research/pivot/alpn-service-architecture.md
  • Cleanup plan: docs/research/pivot/cleanup-plan.md
  • SDD process: docs/sdd_process.md
  • Reference implementation: /workspace/@alkdev/alknet-main/
Reference in New Issue View Git Blame Copy Permalink