alknet/docs/architecture

status, last_updated

status	last_updated
draft	2026-07-02

Alknet Architecture

Current State

Pre-implementation of the storage/repo pattern. The project has completed a pivot from a three-layer model to an ALPN-as-service model. The greenfield workspace contains alknet-vault (stable — implementation complete and verified, local-only by construction per ADR-025, HD-derivation key model per ADR-026) and research/reference material. Foundational ADRs (001–035) are in place, with the call crate implemented and reviewed.

The storage and auth strategy research (docs/research/alknet-storage-strategy/findings.md) surfaced the repo/adapter pattern as the answer to cross-node state (peer identity, credentials). This has now landed as four ADRs:

• ADR-030 (PeerEntry and Identity.id decoupling): authorized_fingerprints: HashSet<String> → peers: Vec<PeerEntry>; Identity.id becomes the stable peer_id (not the fingerprint); key rotation changes the fingerprint, not the identity. Supersedes ADR-029's v1 UUID source (the one-way door — PeerId is logical, not crypto — is preserved; the source changes from UUID to Identity.id from PeerEntry). Resolves OQ-33 and the storage-boundary half of OQ-34.
• ADR-031 (CredentialStore repo trait): the second repo trait in core (alongside IdentityProvider), with InMemoryCredentialStore default adapter. Establishes the credential-persistence abstraction.
• ADR-032 (Forwarded-for identity): forwarded_for field on call.requested and OperationContext; metadata only — AccessControl::check never reads it; the from_call handler populates it. Wire-format one-way door, included with the ADR-029 migration window.
• ADR-033 (Storage boundary and repo/adapter pattern): core defines repo traits + in-memory defaults; persistence adapters are separate crates; the assembly layer wires the adapter. Resolves OQ-34's storage-boundary question. Concrete adapter shapes now committed by ADR-035 (was OQ-36).

The alknet-call crate is implemented and reviewed — both the server-side core and the client/adapter surface (207 lib + 2 integration tests passing). The alknet-core and alknet-call crate specs are in draft; the alknet-vault crate specs are stable.

alknet-http specs drafted and consistency-reviewed. The alknet-http crate (HTTP interface — h2/http/1.1 server + WebSocket browser path + from_openapi/to_openapi/from_mcp/to_mcp adapters) now has architecture specs: crates/http/ (overview, http-server, websocket, http-adapters, http-mcp, webtransport) and thirteen ADRs — ADR-036 (HTTP-to-call mapping; direct-call surface — routing superseded by ADR-047, non-routing clauses survive), ADR-037 (MCP stdio exclusion), ADR-038 (HTTP/3 + WebTransport as first-class — superseded by ADR-044; its correction of the two-way-door-as-deferral anti-pattern stands, its specific decision is reversed by the scope deferral), ADR-039 (HTTP server + client host colocated in one crate), ADR-040 (WebTransport ALPN-stream-proxy — parked per ADR-044; revives unchanged when WebTransport revives), ADR-041 (to_mcp tool-gateway pattern — 4 fixed gateway tools instead of one tool per operation, addressing LLM context tool-bloat), ADR-042 (to_openapi gateway pattern — 5 fixed gateway endpoints instead of one path per operation; per-caller AccessControl-filtered API surface; supersedes ADR-036's original to_openapi clause), ADR-043 (WebTransport as a bidirectional ALPN transport substrate — parked per ADR-044; §2/§3 transfer to WebSocket for v1), ADR-044 (defer h3/WebTransport; browsers use WebSocket for the bidirectional call-protocol path; a scope decision per ADR-009 §"What this framework is NOT"; reversal trigger = a concrete ALPN-stream-proxy use case; states the "browser is not a peer" rationale — addressability vs. bidirectionality — that amends ADR-034 §4), and ADR-045 (to_openapi published-spec versioning — info.version semver tracks the gateway endpoint contract, not the operation set; resolves OQ-39), and ADR-046 (assembly-layer custom HTTP routes on HttpAdapter — extra_routes: Option<Router> for deployment-specific endpoints like an OAI-compatible proxy; default surface unchanged, takes precedence on collision), and ADR-047 (remove the direct-call POST /{service}/{op} surface — the gateway /call is the sole invoke path; the simplified contract is the few-fixed-endpoints model, not a per-operation REST tree; ADR-036's non-routing clauses survive), and ADR-048 (WebSocket carries the native EventEnvelope call-protocol session, not the HTTP gateway shape — the gateway endpoints are HTTP-only; discovery via services/list/services/schema as call-protocol ops; clarifies the WS-path shape ADR-044 committed). ADR-003 Amendment 1 clarifies that alknet-call is a protocol-foundation crate (the alknet-http → alknet-call dependency edge). A consistency review pass corrected drift from the mid-spec pivot (the to_openapi gateway pattern landed in the prose but not in cross-references; the WebTransport specs inherited the OpenAPI/MCP direction assumption that doesn't hold for the call protocol) — ADR-036's to_openapi clause is now amended as superseded by ADR-042, ADR-034 §5's "deferral bucket" wording is corrected (the decision stands), and the http specs now name the one-directional HTTP projection vs. the bidirectional WebSocket (and, when revived, WebTransport) substrate. The WebSocket path is promoted to its own spec (websocket.md) with the native-session-vs-gateway distinction made explicit (ADR-048). The specs are in draft; implementation has not started. Two open questions carried: OQ-38 (WebTransport standalone relay service scope — distinct from the in-process ALPN-stream-proxy resolved by ADR-040) and OQ-40 (reqwest client config — since resolved by the ClientWithMiddleware + middleware stack design). OQ-39 (to_openapi published-spec versioning) is resolved by ADR-045.

Next step: The storage/repo-pattern ADRs (030–033) are accepted and amend the core and call specs. The next implementation phase is the ADR-029 migration (peer-keyed overlays, PeerRef routing, retire remote_safe/trusted_peer) with the ADR-030 PeerEntry change and the ADR-032 forwarded_for field folded in — the OperationContext, from_call handler, and AuthPolicy are all under edit, making this the cheapest window. After that: alknet-http implementation (specs drafted; h3/WebTransport deferred per ADR-044, browser bidirectional path uses WebSocket), which consumes the CredentialStore trait and the OperationAdapter contract. The alknet-ssh crate (the other post-core crate, specced in parallel) proceeds independently — it depends on alknet-core, not alknet-call.

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, streaming subscribe example
crates/call/operation-registry.md	draft	OperationSpec, Handler, OperationRegistry, AccessControl, capability injection, service discovery, irpc integration
crates/call/client-and-adapters.md	draft	CallClient (outbound connection opener), from_call / from_jsonschema, OperationAdapter trait, adapter location map, no-env-vars invariant, exchange-of-operations pattern
crates/http/README.md	draft	alknet-http crate index
crates/http/overview.md	draft	Crate purpose, two roles (server + client host), dependencies, adapter location map
crates/http/http-server.md	draft	HttpAdapter for h2/http1.1 + WebSocket upgrade route, axum over QUIC, Bearer auth, stealth, /healthz
crates/http/websocket.md	draft	WebSocket browser bidirectional path — native EventEnvelope call-protocol session (not the gateway shape); framing, dispatch, bidirectionality, connection-local overlay, browsers-are-not-peers, deferred from_wss
crates/http/http-adapters.md	draft	from_openapi (reqwest) and to_openapi (projection); no-env-vars injection point
crates/http/http-mcp.md	draft	from_mcp / to_mcp (feature-gated), streamable-HTTP-only, stdio exclusion
crates/http/webtransport.md	deferred	h3/WebTransport handler — deferred per ADR-044; browser bidirectional path uses WebSocket (see http-server.md). Spec kept intact for revival.
crates/vault/README.md	stable	alknet-vault crate index
crates/vault/mnemonic-derivation.md	stable	BIP39, SLIP-0010, BIP-0032, derivation paths, key types
crates/vault/encryption.md	stable	AES-256-GCM, EncryptedData, key versioning, salt (Phase B reserved)
crates/vault/service.md	stable	VaultServiceHandle lifecycle, direct dispatch, cache, error model
crates/vault/protocol.md	stable	DerivedKey redaction, KeyType, serialization behavior

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
014	Secret Material Flow and Capability Injection	Accepted
015	Privilege Model and Authority Context	Accepted
016	Abort Cascade for Nested Calls	Accepted
017	Call Protocol Client and Adapter Contract	Accepted
018	Vault as Standalone Crate	Accepted
019	Vault Assembly-Layer-Only Access	Accepted
020	HD Derivation for Encryption Keys	Accepted
021	Key Rotation via Version-Indexed Paths	Accepted
022	Handler Registration, Provenance, and Composition Authority	Accepted
023	Operation Error Schemas	Accepted
024	Operation Registry Layering	Accepted
025	Vault Local-Only Dispatch	Accepted
026	Vault Key Model — HD Derivation	Accepted
027	TLS Identity Redesign — ACME + RawKey Decoupling	Accepted
028	Peer-Scoped Registry Filtering for CallClient Inbound Dispatch	Accepted → Superseded by ADR-029
029	Peer-Graph Routing Model for alknet-call Composition	Accepted (Assumption 1's PeerId source superseded by ADR-030)
030	PeerEntry and Identity.id Decoupling	Accepted (supersedes ADR-029 Assumption 1's UUID source)
031	CredentialStore Repo Trait	Accepted
032	Forwarded-For Identity (Metadata, Not Authority)	Accepted
033	Storage Boundary and Repo/Adapter Pattern	Accepted
034	Outgoing-Only X.509 and the Three Peer Roles	Accepted
035	Concrete Persistence Adapter Shapes — Read/Write Split, honker+SQLite	Accepted
036	HTTP-to-Call Operation Mapping	Proposed — routing decision superseded by ADR-047 (non-routing clauses survive: SSE, auth, /healthz, stealth, error mapping)
037	MCP Stdio Transport Exclusion	Proposed
038	HTTP/3 and WebTransport as First-Class HTTP Transports	Proposed → Superseded by ADR-044
039	HTTP Server and Client Host Colocated in alknet-http	Proposed
040	WebTransport ALPN-Stream-Proxy	Proposed — parked (implementation deferred per ADR-044)
041	MCP Tool-Gateway Pattern for to_mcp	Proposed
042	OpenAPI Gateway Pattern for to_openapi	Proposed
043	WebTransport as a Bidirectional ALPN Transport Substrate	Proposed — parked (implementation deferred per ADR-044; §2/§3 transfer to WebSocket)
044	Defer h3/WebTransport; Browsers Use WebSocket	Accepted
045	to_openapi Gateway-Spec Versioning	Proposed
046	Assembly-Layer Custom HTTP Routes on HttpAdapter	Proposed
047	Remove the Direct-Call HTTP Surface; Gateway Is the Sole Invoke Path	Proposed
048	WebSocket Carries the Native Call-Protocol Session, Not the Gateway Shape	Accepted
049	Streaming Handler for Subscription Operations	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, assembly-layer only (ADR-008, ADR-014)
• OQ-16: Safe vault operations for call protocol exposure — none for now (ADR-014)
• OQ-18: Privilege model — internal = authority switch, External/Internal visibility, handler identity + scoped env (ADR-015)
• OQ-17: Abort cascade — call.aborted cascades to descendants; default abort-dependents, continue-running opt-in (ADR-016)
• OQ-15: Call protocol client and adapter contract — CallClient opens connections; from_call imports remote ops; connection direction independent of call direction (ADR-017)

Resolved two-way doors:

• OQ-04: Dynamic handler registration — static at startup (ADR-010); scoped to the HandlerRegistry (ALPN-level) by ADR-024, which governs OperationRegistry mutability separately
• OQ-07: Call protocol scope — bidirectional streams, EventEnvelope, ID-based correlation (ADR-012)
• OQ-11: Handler-level auth resolution observability — handlers store resolved identity on Connection (Option B); two identity scopes: connection-level (observability) and per-request (ACL)
• OQ-12: TLS identity provisioning — two use cases: RFC 7250 raw keys (default, P2P) and X.509 certs (domain-hosted, browsers). ACME designed in ADR-027; RawKey decoupled from iroh feature.
• 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
• OQ-19: Session-scoped registries — agent-written operations via OperationEnv trait layering; protocol doesn't need changes; OperationEnv must remain a trait. Generalized by ADR-024 to cover connection-scoped overlays as well.
• OQ-20: Encryption key derivation — HD derivation from BIP39 seed, not PBKDF2; salt field unused in v2 (wire-format compat) (ADR-020)
• OQ-21: Remote vault access — resolved (ADR-025): vault is local-only by construction; remote access requires a separate vault-server crate with its own ADR
• OQ-22: Key rotation — version-indexed derivation paths; rotate method re-encrypts (ADR-021)
• OQ-23: Handler identity registration path — registration bundle with provenance, composition authority, scoped env, capabilities (ADR-022)
• OQ-24: Operation error schemas — declared domain errors with typed details payload; adapter fidelity for from_openapi/to_openapi (ADR-023)
• OQ-40: reqwest client config and connection pooling — ClientWithMiddleware + RetryTransientMiddleware + inlined RetryAfterMiddleware; rebuild-and-swap hot-reload; per-request credential injection; agent-crate SSE normalization sits on top of the client, doesn't replace it

Resolved by the storage/repo-pattern ADRs (ADR-030–033):

• OQ-33: PeerId stability — resolved by ADR-030 (logical id; source is Identity.id = PeerEntry.peer_id, stable across key rotation; UUID workaround removed)
• OQ-34: Persistent peer registry — resolved by ADR-030 + ADR-031 + ADR-033 (storage boundary: core defines repo traits + in-memory defaults; persistence adapters are separate crates)
• OQ-35: API key asymmetry — dissolved (the framing was wrong; PeerEntry supports multiple credential paths)

Resolved by the call-completion / ADR-029 work:

• OQ-27: from_call re-import trigger — resolved (auto-re-import on connection establishment; refresh() is a feature addition)
• OQ-28: from_call namespace collision — resolved (same-peer collision = error; cross-peer dissolved by ADR-029)
• OQ-29: CallClient TLS client-auth — resolved (wire quinn client-auth; key-type-aware server cert verification; fingerprint normalization to ed25519: across quinn/iroh)
• OQ-30: PeerRef::Any routing policy — resolved (insertion-order first-match; richer routing is a feature extension)
• OQ-31: services/list-peers re-export semantics — resolved (opt-in services/list-peers; services/list is "own ops only")

Open (feature extensions, not blocking):

• OQ-32: Multi-hop federation — the one-hop model is the architectural commitment; multi-hop is a feature extension that doesn't break downstream
• OQ-36: Concrete persistence adapter shapes — resolved by ADR-035 (read-sync / write-async / honker-NOTIFY cache invalidation; alknet-store-sqlite crate; IdentityStore write trait; CredentialStore::put/delete async)
• OQ-37: X.509 outgoing-only case — resolved by ADR-034 (three remote roles named: public X.509 endpoint, transport relay, hub; PeerEntry asymmetry is correct; client-side verifier selection by PeerEntry presence)
• OQ-38: WebTransport standalone relay service scope — the standalone relay (future alknet-relay, fork of iroh-relay with WebTransport proxy fallback) is distinct from the in-process ALPN-stream-proxy (ADR-040); scope question, not deferral
• OQ-39: to_openapi published-spec versioning — resolved by ADR-045 (info.version semver tracks the gateway endpoint contract, not the operation set; per-caller operations discovered via /search)
• OQ-41: Stream operators library — a handler-level utility library (filter, map, batch, dedupe, window, etc. on BoxStream<T>), prior art in @alkdev/pubsub/operators.ts; feature extension, not an architectural decision (the architecture decision — stream composition is handler-level, not protocol-level — is made in ADR-049)

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/