alkcall/docs/architecture/README.md

status, last_updated

status	last_updated
draft	2026-10-13 (composition re-key, ADR-054, alkcall reframing of ported docs)

alkcall

The call + channels RPC crate. Structured JSON RPC (operations, streaming subscriptions, service discovery) and N-channel multiplexing over one transport stream (channel 0 pre-negotiated as alk/call).

This crate is the extraction and unification of the former alknet-call and alknet-channels crates plus the vendored core types formerly in alknet-core (see ADR-031). It is a pure protocol crate: no networking, no transport dependencies — dial, TLS config, and composition live in downstream crates. The ALPN strings (alk/call, alk/channels) are wire-stable — see ADR-004. (Historical origin and cross-repo citation conventions: see the provenance note at the end of this document.)

Documents

Document	Status	Description
call-README.md	draft	Call protocol index — adapter, stream model, registry, client (ported from alknet call/README.md)
call-protocol.md	draft	CallAdapter, hand-rolled EventEnvelope framing (ADR-014), stream model, PendingRequestMap, bidirectional calls
operation-registry.md	draft	OperationSpec, Handler, OperationRegistry, AccessControl, service discovery
client-and-adapters.md	draft	CallClient (transport-agnostic spawn_dispatch), from_call, OperationAdapter trait, no-env-vars invariant
channels-README.md	draft	Channels protocol index — wire format, adapter, lifecycle, client (ported from alknet channels/README.md)
channels-overview.md	draft	The multiplexing collapse, crate dependencies, transport agnosticism, WASM
channels-wire.md	draft	The 8-byte chunk format, sentinels, wire-level invariants (REQ-CH-01..05)
channels-connection.md	draft	ChannelBidiStreamSource, accept_bi yields one BiStream per channel
channels-adapter.md	draft	ChannelsAdapter, ChannelManager, demux/mux contracts
channel-operations.md	draft	channel/open, channel/close, channel/control, channel/resources/subscribe
channel-client.md	draft	ChannelClient — transport-agnostic from_connection primary

Applicable ADRs

Core (vendored types) — ADR-001..012

ADR	Title	Relevance
001	ALPN-Based Protocol Dispatch	HandlerRegistry, ALPN routing
002	ProtocolHandler Trait	The trait every handler implements
003	Auth as Shared Core	IdentityProvider, Identity, AuthToken
004	ALPN String Convention	alk/ prefix, one ALPN per connection
005	BiStream Type Definition	BiStream, handlers receive Connection
006	AuthContext Structure	AuthContext fields, hybrid resolution
007	Connection::from_stream	Generic single-stream connections
008	BidiStreamSource Trait	Connection extension point
009	BiStream as the Handler Leaf	accept_bi returns BiStream (concrete)
010	Secret Material Flow	No secrets on wire; Capabilities
011	Dynamic Resource Ownership	OwnershipProvider, resource_id_path
012	ConnectionCredentials	Transport-level credentials, auth_token is per-request

Call protocol — ADR-013..030

ADR	Title	Relevance
013	irpc as Call Protocol Foundation	Superseded by ADR-014
014	Hand-Rolled EventEnvelope Framing	The call wire format ADR; supersedes ADR-013
015	Call Protocol Stream Model	Bidi streams, EventEnvelope, ID correlation
016	Operation Error Schemas	call.error with typed details
017	Privilege Model	internal = authority switch; Visibility
018	Handler Registration	Registration bundle, provenance, composition authority
019	Operation Registry Layering	Curated + session + connection overlays; OperationEnv trait
020	Abort Cascade	call.aborted cascades; abort-dependents default
021	Streaming Handler	StreamingHandler, invoke_streaming()
022	Client and Adapter Contract	CallClient, from_call, OperationAdapter
023	Peer-Scoped Registry Filtering	Superseded by ADR-024
024	Peer-Graph Routing Model	PeerCompositeEnv, PeerRef, AccessControl peer auth
025	PeerEntry and Identity.id Decoupling	PeerId = Identity.id (stable)
026	Forwarded-For Identity	Metadata only, never used by ACL
027	from_jsonschema as HTTP Adapter	FromJsonSchema provenance stays; impl moved to alkhttp (ex-alknet-http)
028	from_call Is a Manual Free Function	Assembly layer calls it after dial
029	Aggregated Peer-Environment Wiring	Dispatcher hub wiring
030	PeerCompositeEnv::peer_operations	OperationEnv::peer_operations override

Shared — ADR-031..033

ADR	Title	Relevance
031	Crate Decomposition	alkcall unifies core+call+channels
032	One-Way Door Decision Framework	Reversal cost classification
033	Rust as Canonical Implementation Language	Rust canonical, TS reference

Channels, pub/sub, and later amendments — ADR-034..054

ADR	Title	Relevance
034	Channels Wire Format	8-byte chunk header; one-way door
035	Pure Channel Multiplexing	No stream_type; BiStream-only; handler owns sub-mux
036	Channel 0 Pre-Negotiated	Channel 0 = alk/call
037	Channel Lifecycle Operations	channel/open, close, control, resources/subscribe
038	ChannelConnection	Per-channel BidiStreamSource; yield-once accept_bi
039	ChannelsAdapter and ChannelManager	Demux/mux; ALPN-blind, auth-blind
040	Backpressure, Limits, ID Reuse	Bounded-buffer; 256-channel memory bound
041	Per-Identity Channel Cap	ChannelLifecyclePolicy; 256 per PeerId
042	Hub Relay	Translate channel 0, byte-forward data channels
043	ChannelClient	Transport-agnostic from_connection
044	Channels Sub-Crate Decomposition	channels-core / channels-call (modules in alkcall)
045	AlknetClient Dial Seam	spawn_dispatch / from_connection take-over; dial in consumer
046	Publish Operation Type and HandlerKind::Sink	OperationType::Pub (producer→consumer streaming); SinkHandler + HandlerKind::Sink; call.published wire event; invoke_sink() dispatch; Subscription renamed to Sub
047	Openable ALPNs Are Operations	channel/open dissolves into per-ALPN ops channels/<alpn>/sub/pub; channel_open marker on OperationSpec; ChannelCore wrapper; extension-trait ChannelOperationEnv; connection-owner allocates channel_id; opener ledger (Gap 2 fix); ALPNs are call apps
048	Dispatch Spine (feature-gated gateway module)	alkcall::gateway behind the gateway feature; GatewayDispatch invoke spine (deadline knob, re-rooted context) + schema_disclosure_denial (FORBIDDEN for ACL deny, spec-404 for Internal); promoted from alkhttp for hub/spoke reuse
049	Channel-Open Establishment Phase	OpenEstablisher + register_openable_with_establisher (awaited, bounded); typed channel:open_failed with details.reason; Establishment.plan (ChannelPlan) threaded to the OpenHandler (amendment 2); the JoinHandle data-plane lifetime contract
050	pump_bidi Two-Pump Helper	channels::pump_bidi — shutdown-on-completion two-pump data plane pinned in one place (alknet ADR-078)
051	In-Tree Channel Relay (ChannelRelay) and the Hub-Leg Assembly	ADR-042 amended — the relay implementation is an alkcall export; translate hop = ADR-049 establisher (register_relay_openable), byte-forward hop = pump_bidi; implicit per-channel id mapping; two-phase registration (discover/stash → fork-register); hub-leg install template; ACL layering note
052	channel/control Control-Handle Surface	Establisher-contributed ChannelControl (Establishment::with_control), wrapper-installed/teardown-removed in the manager; channel:no_control_handle capability answer; resolves OQ-39
053	Live Resource Enumerators	ResourceEnumerators (peer-shared registry); snapshot-then-changes enumerator contract; scan-once aggregation; empty seed; resolves OQ-40
054	Outgoing-Only X.509 and the Three Remote Roles (Re-Owned)	Verifier-selection by PeerEntry presence; three remote roles; RemoteIdentity None semantics — re-owned in-crate (provenance: alknet ADR-034); resolves OQ-21's cross-repo authority gap

Relevant Open Questions

See open-questions.md for the full tracker. Key questions affecting this crate:

• OQ-22 (resolved) / OQ-42 (deferred(scope)): The call-protocol pub/sub primitive is delivered (ADR-046); the fan-out/message broker is placed out of scope for alkcall — the hub composes it on the Pub/Sub primitives — and its design remains deferred downstream, blocked on a concrete producing-crate consumer (Gap B in ADR-047).
• OQ-23 (deferred(scope)): Full channel-level flow-control windowing — bounded-buffer is decided (ADR-040); full windowing blocked on a real HOL-blocking deployment observation.
• OQ-24 (resolved): Channels add/strip API shape — integral to the read/write path (handlers never see headers); low-level header primitives stay in channels::wire for tooling.
• OQ-37 (resolved): No from_call relay wrapper for marked ops — marked announcements and marked-spec imports are refused (ADR-022 amendment 2026-10-13, ADR-047 amendment 4 §4.8); the sanctioned compositions are ChannelRelay::register_relay_openable (ADR-051) and ChannelClient.
• OQ-43 (deferred(scope)): Composition-layer ownership and shape after the alknet replacement — the named receiver for the downstream-side deferrals (OQ-33 endpoint layer, OQ-41 QUIC-native substrate, OQ-42 hub broker, OQ-19 persistence adapters). Not blocking any alkcall API surface.

Key Design Principles

1. One connection, full access: An alk/call connection gives access to the entire operation registry.
2. Protocol is symmetric: Both sides can initiate calls. Producer/ consumer, not server/client.
3. Hand-rolled framing (no irpc): EventEnvelope is hand-rolled length-prefixed JSON. See ADR-014.
4. Operation registry is layered: Curated (static) + session + connection overlays. OperationEnv is a trait. See ADR-019.
5. No secret material on the wire: Capabilities injected at assembly layer. See ADR-010.
6. Abort cascades to descendants: Default abort-dependents. See ADR-020.
7. Peer authorization via AccessControl: No remote_safe flag. See ADR-024.
8. Streams are streams: Every channel is a BiStream. The handler owns its sub-stream multiplexing. See ADR-035.
9. Channel 0 is alk/call: Channel lifecycle is call operations on channel 0. See ADR-036, ADR-037.
10. Wire formats are stable: EventEnvelope shape and the 8-byte chunk header are one-way doors. See ADR-014, ADR-034.
11. Implement-or-stop-advertising: every registration on a discoverable surface must be capable of succeeding — no advertised-always-failing bodies, no deferral buckets ("not this session" is the only permitted deferral statement). Marked (channel_open) specs refuse the generic registration paths (ADR-047 amendment 4 §4.8); the not_implemented guard test is release-blocking (tests/stub_guard.rs). See reviews 010/011 for the incident that pinned this.

Roles and Composition

alkcall is a pure protocol crate — no networking, no transport dependencies. It provides the call and channels protocols as a library. Downstream crates compose on top of it in a layered dependency chain.

The four roles

Role	Definition	Call protocol	Channels protocol
Producer	Provides a resource consumers can use (often called "server")	Registers ops on an OperationRegistry, runs a Dispatcher to handle incoming call.requested	Runs a ChannelsAdapter, registers openable ALPNs via ChannelCore::register_openable
Consumer	Consumes a resource from a producer (often called "client")	Uses CallConnection to call ops, uses from_call to discover/import remote ops	Uses ChannelClient to open channels via call_open_op + open_channel
Hub	Central location spokes connect to; relays and routes between them	Both: runs a Dispatcher for ops it produces, holds CallConnections to spokes for ops it consumes. Relays calls via OperationEnv peer routing	Both: runs a ChannelsAdapter for inbound connections, holds ChannelClients to spokes. Relays data channels with channel_id rewrite (ADR-042)
Spoke / Worker	Connects to a hub; provides and consumes resources	Both: produces ops (its own services), consumes hub ops (e.g. services/list to discover peers)	Both: produces channels (TTY, tunnel), may consume hub channels

A single process can be a producer of some ops, a consumer of others, a channel opener for TTY, and a channel acceptor for tunnels — all on the same alk/channels connection. The types don't encode the system role; they just don't prevent any combination.

Within a single connection, direction is independent of role:

• Call initiator / call responder — who sent call.requested vs who handles it. Either side can initiate on any connection.
• Channel opener / channel acceptor — who called the per-ALPN open op vs who allocated the channel_id. The connection owner allocates (ADR-047 §5); either side can open.

Dependency layering

┌──────────────────────────────────────────────┐
│  Composition layer                           │
│  (today: the alknet glue — being replaced;   │
│   future owner and shape → OQ-43)            │
│                                              │
│  • QUIC / TCP+TLS dial and accept            │
│  • Hub: ChannelsAdapter + Dispatcher +       │
│    peer routing (PeerCompositeEnv)           │
│  • Spoke: ChannelClient + CallConnection +   │
│    from_call                                  │
│  • Wires protocol crates' producers into     │
│    registries, consumers into clients        │
└──────────────────┬───────────────────────────┘
                   │ depends on
    ┌──────────────┼──────────────┐
    │              │              │
┌───┴───────┐ ┌────┴─────┐ ┌─────┴──────────┐
│ alktty    │ │alktunnels│ │ alktrader       │
│ (protocol)│ │(protocol)│ │ (protocol)      │
│           │ │          │ │                 │
│ • Session │ │ • Tunnel │ │ • Backend trait │
│ • Backend │ │ • Backend│ │ • register_ops()│
│ • 5-byte  │ │ • bytes  │ │ • TypedClient   │
│   wire    │ │ • OpenH. │ │                 │
│ • OpenH.  │ │ • reg_*()│ │                 │
│ • reg_*() │ │          │ │                 │
└───┬───────┘ └────┬─────┘ └─────┬───────────┘
    │              │              │
    └──────────────┼──────────────┘
                   │ depends on
┌──────────────────┴───────────────────────────┐
│  alkcall                                      │
│  (call + channels protocols, no networking)   │
│                                               │
│  • Connection, BiStream, ProtocolHandler      │
│  • OperationRegistry, OperationSpec, Handler  │
│  • CallConnection, Dispatcher, from_call      │
│  • ChannelClient, ChannelsAdapter,            │
│    ChannelManager, ChannelCore                │
└───────────────────────────────────────────────┘

Protocol crates (alktty, alktunnels, alktrader) depend only on alkcall. They provide two halves:

1. Producer half — a register_*() function that takes an &mut OperationRegistry and registers ops with their handlers. For channels-based protocols, an OpenHandler factory. The crate doesn't know whether it's running on a hub, a spoke, or a standalone process.

2. Consumer half — a typed client wrapper around CallConnection (or ChannelClient) that exposes the crate's ops as async methods (e.g. trader_client.status().await instead of call_connection.call("trader/status", ...).await).

The composition layer depends on alkcall + whichever protocol crates are needed. It's the only place that knows about network topology, peer routing, and which protocol crates are wired in. Protocol crates never import a QUIC or TLS dependency. Today this layer is the alknet glue; its post-replacement owner and shape is tracked as OQ-43.

Pattern for protocol crates

A protocol crate that uses channels (e.g. alktty) follows this pattern:

┌─────────────────────────────────────────┐
│  alktty (protocol crate, no network)     │
│                                          │
│  TtySession {                            │
│    drive(send, recv, backend) -> ExitCode │  ← pure protocol, takes
│  }                                        │     AsyncRead + AsyncWrite
│                                          │
│  TtyBackend trait                         │
│  NegotiateRequest / ControlMessage        │
│  ChunkReader / ChunkWriter (5-byte)       │
└─────────────────────────────────────────┘
         ▲                    ▲
         │                    │
┌────────┴────────┐  ┌───────┴──────────────┐
│  Direct ALPN     │  │  Through channels     │
│  (alk/tty)    │  │  (alk/channels)    │
│                  │  │                       │
│  TtyAdapter      │  │  OpenHandler          │
│  impl Protocol   │  │  (registered via      │
│  Handler          │  │   ChannelCore::        │
│                  │  │   register_openable)   │
│  Gets Connection │  │                       │
│  loops accept_bi │  │  Gets BiStream per    │
│                  │  │  session              │
└─────────────────┘  └───────────────────────┘

The protocol crate doesn't know which path it's on. It takes a BiStream (or AsyncRead + AsyncWrite) and drives the session. The two adapters are thin and live either in the protocol crate (behind feature flags) or in the composition layer.

References

• @alkdev/alktype — the binary struct engine; compiles BAST documents (e.g. chunk-header.bast.json) into readers/writers/validators
• @alkdev/alkhttp, @alkdev/alktls, @alkdev/alktty, @alkdev/alktunnels, @alkdev/alktrader — sibling crates; the live homes of the surfaces older docs call alknet-http, alknet-tls, alknet-tty, alknet-tunnels, alknet-trader
• @alkdev/pubsub — the TypeScript EventEnvelope prior art the call wire format was derived from

Provenance and cross-repo citations. The source ADRs and spec docs were ported from the parent @alkdev/alknet workspace where this crate originated, and renumbered to alkcall ADR-001..048 (ADR-049 and later were authored in this crate). They are the authoritative spec here; the alknet mono-repo is being replaced by thin glue over alkcall and its siblings, so alknet-specific citations are expected to decay into footnotes over time, and anything that genuinely constrains alkcall's surface gets re-owned by an in-crate ADR (e.g. ADR-054 re-owns alknet ADR-034's verifier-selection rule).

Citation conventions: alkcall's own ADRs are decisions/001..054 in this directory. Some ported docs also cite source-repo ADRs that were not ported (e.g. alknet ADR-052 for TTY's wire format). The alknet number space collides with alkcall's (alknet ADR-052 has nothing to do with alkcall's channel/control ADR-052), so unambiguous references carry the alknet prefix (e.g. "alknet ADR-052") and link to the alknet repo: /workspace/@alkdev/alknet/docs/architecture/ (a few legacy cites without the prefix still mean the alknet ADR — check the link target). Dead relative paths like docs/research/alknet-channels/... live in the alknet repo, not this one. Similarly, alknet OQ-NN citations refer to the alknet repo's question tracker — this crate's OQ tracker runs its own numbering (OQ-01..43, see open-questions.md).