--- status: draft last_updated: 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](call-README.md) | draft | Call protocol index — adapter, stream model, registry, client (ported from alknet call/README.md) | | [call-protocol.md](call-protocol.md) | draft | CallAdapter, hand-rolled EventEnvelope framing (ADR-014), stream model, PendingRequestMap, bidirectional calls | | [operation-registry.md](operation-registry.md) | draft | OperationSpec, Handler, OperationRegistry, AccessControl, service discovery | | [client-and-adapters.md](client-and-adapters.md) | draft | CallClient (transport-agnostic spawn_dispatch), from_call, OperationAdapter trait, no-env-vars invariant | | [channels-README.md](channels-README.md) | draft | Channels protocol index — wire format, adapter, lifecycle, client (ported from alknet channels/README.md) | | [channels-overview.md](channels-overview.md) | draft | The multiplexing collapse, crate dependencies, transport agnosticism, WASM | | [channels-wire.md](channels-wire.md) | draft | The 8-byte chunk format, sentinels, wire-level invariants (REQ-CH-01..05) | | [channels-connection.md](channels-connection.md) | draft | ChannelBidiStreamSource, accept_bi yields one BiStream per channel | | [channels-adapter.md](channels-adapter.md) | draft | ChannelsAdapter, ChannelManager, demux/mux contracts | | [channel-operations.md](channel-operations.md) | draft | channel/open, channel/close, channel/control, channel/resources/subscribe | | [channel-client.md](channel-client.md) | draft | ChannelClient — transport-agnostic from_connection primary | ## Applicable ADRs ### Core (vendored types) — ADR-001..012 | ADR | Title | Relevance | |-----|-------|-----------| | [001](decisions/001-alpn-protocol-dispatch.md) | ALPN-Based Protocol Dispatch | HandlerRegistry, ALPN routing | | [002](decisions/002-protocol-handler-trait.md) | ProtocolHandler Trait | The trait every handler implements | | [003](decisions/003-auth-as-shared-core.md) | Auth as Shared Core | IdentityProvider, Identity, AuthToken | | [004](decisions/004-alpn-convention-and-connection-model.md) | ALPN String Convention | `alk/` prefix, one ALPN per connection | | [005](decisions/005-bistream-type-definition.md) | BiStream Type Definition | BiStream, handlers receive Connection | | [006](decisions/006-authcontext-structure.md) | AuthContext Structure | AuthContext fields, hybrid resolution | | [007](decisions/007-connection-from-stream-generic-single-stream.md) | Connection::from_stream | Generic single-stream connections | | [008](decisions/008-bidistreamsource-trait.md) | BidiStreamSource Trait | Connection extension point | | [009](decisions/009-bistream-as-the-handler-leaf.md) | BiStream as the Handler Leaf | accept_bi returns BiStream (concrete) | | [010](decisions/010-secret-material-flow-and-capability-injection.md) | Secret Material Flow | No secrets on wire; Capabilities | | [011](decisions/011-dynamic-resource-ownership-for-runtime-spawned-resources.md) | Dynamic Resource Ownership | OwnershipProvider, resource_id_path | | [012](decisions/012-connectioncredentials-decouple-dial-from-call.md) | ConnectionCredentials | Transport-level credentials, auth_token is per-request | ### Call protocol — ADR-013..030 | ADR | Title | Relevance | |-----|-------|-----------| | [013](decisions/013-irpc-as-call-protocol-foundation.md) | ~~irpc as Call Protocol Foundation~~ | **Superseded** by ADR-014 | | [014](decisions/014-irpc-never-integrated-hand-rolled-framing.md) | Hand-Rolled EventEnvelope Framing | The call wire format ADR; supersedes ADR-013 | | [015](decisions/015-call-protocol-stream-model.md) | Call Protocol Stream Model | Bidi streams, EventEnvelope, ID correlation | | [016](decisions/016-operation-error-schemas.md) | Operation Error Schemas | call.error with typed details | | [017](decisions/017-privilege-model-and-authority-context.md) | Privilege Model | internal = authority switch; Visibility | | [018](decisions/018-handler-registration-provenance-and-composition-authority.md) | Handler Registration | Registration bundle, provenance, composition authority | | [019](decisions/019-operation-registry-layering.md) | Operation Registry Layering | Curated + session + connection overlays; OperationEnv trait | | [020](decisions/020-abort-cascade-for-nested-calls.md) | Abort Cascade | call.aborted cascades; abort-dependents default | | [021](decisions/021-streaming-handler-for-subscriptions.md) | Streaming Handler | StreamingHandler, invoke_streaming() | | [022](decisions/022-call-protocol-client-and-adapter-contract.md) | Client and Adapter Contract | CallClient, from_call, OperationAdapter | | [023](decisions/023-callclient-peer-scoped-registry-filtering.md) | ~~Peer-Scoped Registry Filtering~~ | **Superseded** by ADR-024 | | [024](decisions/024-peer-graph-routing-model.md) | Peer-Graph Routing Model | PeerCompositeEnv, PeerRef, AccessControl peer auth | | [025](decisions/025-peerentry-and-identity-id-decoupling.md) | PeerEntry and Identity.id Decoupling | PeerId = Identity.id (stable) | | [026](decisions/026-forwarded-for-identity.md) | Forwarded-For Identity | Metadata only, never used by ACL | | [027](decisions/027-from-jsonschema-as-http-adapter.md) | from_jsonschema as HTTP Adapter | FromJsonSchema provenance stays; impl in alknet-http | | [028](decisions/028-from-call-manual-free-function.md) | from_call Is a Manual Free Function | Assembly layer calls it after dial | | [029](decisions/029-aggregated-peer-env-wiring.md) | Aggregated Peer-Environment Wiring | Dispatcher hub wiring | | [030](decisions/030-peer-composite-env-peer-operations.md) | PeerCompositeEnv::peer_operations | OperationEnv::peer_operations override | ### Shared — ADR-031..033 | ADR | Title | Relevance | |-----|-------|-----------| | [031](decisions/031-crate-decomposition.md) | Crate Decomposition | alkcall unifies core+call+channels | | [032](decisions/032-one-way-door-decision-framework.md) | One-Way Door Decision Framework | Reversal cost classification | | [033](decisions/033-rust-canonical-implementation.md) | Rust as Canonical Implementation Language | Rust canonical, TS reference | ### Channels — ADR-034..045 | ADR | Title | Relevance | |-----|-------|-----------| | [034](decisions/034-channels-wire-format.md) | Channels Wire Format | 8-byte chunk header; one-way door | | [035](decisions/035-channels-pure-channel-multiplexing.md) | Pure Channel Multiplexing | No stream_type; BiStream-only; handler owns sub-mux | | [036](decisions/036-channel-0-pre-negotiated-call.md) | Channel 0 Pre-Negotiated | Channel 0 = alk/call | | [037](decisions/037-channel-lifecycle-operations.md) | Channel Lifecycle Operations | channel/open, close, control, resources/subscribe | | [038](decisions/038-channelconnection-bidistreamsource.md) | ChannelConnection | Per-channel BidiStreamSource; yield-once accept_bi | | [039](decisions/039-channelsadapter-and-channelmanager.md) | ChannelsAdapter and ChannelManager | Demux/mux; ALPN-blind, auth-blind | | [040](decisions/040-backpressure-channel-limits-id-reuse.md) | Backpressure, Limits, ID Reuse | Bounded-buffer; 256-channel memory bound | | [041](decisions/041-per-identity-channel-cap.md) | Per-Identity Channel Cap | ChannelLifecyclePolicy; 256 per PeerId | | [042](decisions/042-hub-relay-translate-not-forward.md) | Hub Relay | Translate channel 0, byte-forward data channels | | [043](decisions/043-channelclient.md) | ChannelClient | Transport-agnostic from_connection | | [044](decisions/044-channels-subcrate-decomposition.md) | Channels Sub-Crate Decomposition | channels-core / channels-call (modules in alkcall) | | [045](decisions/045-alknetclient-native-dial-seam.md) | AlknetClient Dial Seam | spawn_dispatch / from_connection take-over; dial in consumer | | [046](decisions/046-publish-operation-type-and-handler-kind-sink.md) | 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](decisions/047-openable-alpns-are-operations.md) | Openable ALPNs Are Operations | `channel/open` dissolves into per-ALPN ops `channels//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](decisions/048-dispatch-spine-gateway-module.md) | 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](decisions/049-channel-open-establishment-phase.md) | 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](decisions/050-pump-bidi-two-pump-helper.md) | `pump_bidi` Two-Pump Helper | `channels::pump_bidi` — shutdown-on-completion two-pump data plane pinned in one place (alknet ADR-078) | | [051](decisions/051-channel-relay-and-hub-leg.md) | 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](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 `CallConnection`s to spokes for ops it consumes. Relays calls via `OperationEnv` peer routing | Both: runs a `ChannelsAdapter` for inbound connections, holds `ChannelClient`s 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/`.