alkcall/docs/architecture

status, last_updated

status	last_updated
draft	2026-08-12

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 unifies alknet-call and alknet-channels from the alknet mono-repo, plus the vendored core types formerly in alknet-core. The source architecture docs were ported from /workspace/@alkdev/alknet/docs/architecture/ and renumbered as alkcall ADRs (ADR-001..051). The ALPN strings (alk/call, alk/channels) are wire-stable and unchanged — see ADR-004.

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 in 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 — ADR-034..045

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

Relevant Open Questions

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

• OQ-01: Call protocol pub/sub primitive (partially resolved) — ADR-046 adds the Pub primitive (producer→consumer streaming). The fan-out/broker is deferred to channels (Gap B in ADR-047 is named out-of-scope for alkcall; the hub composes the broker on top).
• OQ-02: Full channel-level flow-control windowing (deferred(scope)) — bounded-buffer is decided (ADR-040); full windowing blocked on a real HOL-blocking deployment observation.
• OQ-03: Channels add/strip API shape (open) — whether the 8-byte header add/strip is built into the read/write path or a standalone utility.

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.

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

┌──────────────────────────────────────────────┐
│  alknet / alknode                            │
│  (networking + composition)                  │
│                                              │
│  • 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).

alk/alknode depends on alkcall + whichever protocol crates are needed. It's the composition layer — 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.

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 downstream alknet crate.

References

• @alkdev/alknet: docs/architecture/ — the source architecture docs these were ported from (renumbered from alknet ADR-001..094 to alkcall ADR-001..048; ADR-049 and later were authored in this crate)
• @alkdev/alktype — the binary struct engine; compiles BAST documents (e.g. chunk-header.bast.json) into readers/writers/validators
• @alkdev/pubsub — the TypeScript EventEnvelope prior art the call wire format was derived from

Note

: The source ADRs and spec docs were ported from the parent @alkdev/alknet workspace where this crate originated. They are preserved here as the authoritative spec for alkcall; the alknet mono-repo will consume alkcall's versions when it is reworked.

Cross-references to non-ported ADRs: Some spec docs and ADRs reference alknet ADRs by their original numbers (e.g., ADR-052 for TTY's wire format, ADR-082 for alknet-tls, ADR-086 for endpoint types). These are ADRs for sibling crates that are not part of alkcall. They retain their alknet numbering (052, 082, 086, etc.) — any ADR number outside the alkcall range 001..048 is an alknet source ADR, found at /workspace/@alkdev/alknet/docs/architecture/decisions/.