glm-5.2
8066d08395
A channel-open op could not be registered or invoked (C-02):
ChannelCore::register_openable did not exist, and resolve_channel_manager
(C-03) was a stub returning None — the ADR-047 §4 dynamic-resolution
shape (downcast context.env to &dyn ChannelOperationEnv) was unworkable
as written: context.env is a PeerCompositeEnv, not a single concrete
type that can be downcast to a channels-backed env.
The fix is per-connection registration (ADR-047 §4 amendment,
2026-08-13): a ChannelCore is constructed per channels connection (in
the install_channel_zero hook, which already runs per-connection and
already receives the ChannelManager), and register_openable is called on
that connection's overlay OperationRegistry (Layer 2 per ADR-019). The
wrapper closes over the per-connection ChannelCore and uses
ChannelCore::manager() directly — no context.env downcast. This
preserves every invariant ADR-047 §4 was written to protect (layering,
per-connection resolution) without adding as_any() to OperationEnv
(which would close the session/connection overlay patterns from
ADR-024, AGENTS.md §6).
Changes:
- ChannelCore::register_openable wraps the ALPN's OpenHandler with the
ACL→check_open→open_channel→spawn→respond flow (ADR-047 §3). Branches
on spec.op_type: Query/Mutation→Once, Sub→Stream (emits { channel_id }
and completes; data plane on the channel's BiStream), Pub→Sink (stub:
channel:pub_open_not_implemented — requires the channel-adoption path,
C-08/Unit 5). The OpenHandler receives (input, Connection, AuthContext)
and spawns the ALPN's protocol on the channel's BiStream, returning a
JoinHandle for teardown.
- ChannelManager::set_handler_task installs the spawned OpenHandler's
JoinHandle after open_channel (which allocates the channel first to
get the BiStream halves, then the handler is spawned, then the task is
recorded for abort on channel/close / connection drop).
- channel:too_many_channels / channel:allocation_failed error codes
mapped to CallError with details (channel:forbidden is the ACL's
FORBIDDEN, already handled by the registry before the wrapper).
- resolve_channel_manager stub removed (C-03); ChannelOperationEnv trait
and ChannelsSessionEnv retained as a two-way-door implementation detail
for future per-connection routing (not on the open-op path). The
tautology filler test (C-22 env.rs) removed.
- ADR-047 §4 amendment records the per-connection-registration decision
(two-way door: the ADR's door-type section explicitly marks the wrapper
shape as a two-way-door implementation detail; the one-way decisions
— per-ALPN op names, channel_open marker, removal of channel/open —
are unchanged).
Acceptance gate (C-02/C-03): one end-to-end test wires ChannelClient ↔
ChannelsAdapter over a real tokio::io::duplex carrying the channels
8-byte chunk header wire format. The accept side's install_channel_zero
hook builds a per-connection ChannelCore, registers a no-op open op
(channels/tty/sub) via register_openable, and runs the dispatch loop.
The client calls call_open_op("channels/tty/sub") on channel 0; the
wrapper does check_open→open_channel→spawn→respond. Asserts the
response carries a non-zero channel_id and that the per-identity quota
was reserved (policy count for the caller incremented to 1).
Verification: 438 tests pass (was 437; +1 e2e), clippy clean, fmt clean,
doc warnings 2 (was 4; fixed the 2 register_openable broken-link
warnings — C-09; the remaining default_policy and env module/macro
warnings are Unit 6 long-tail items).
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 alknet/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..045). The ALPN strings (alknet/call, alknet/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 | alknet/ 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 | 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 | 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 = alknet/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 (client→server 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 |
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
Pubprimitive (client→server 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
- One connection, full access: An
alknet/callconnection gives access to the entire operation registry. - Protocol is symmetric: Both sides can initiate calls. Producer/ consumer, not server/client.
- Hand-rolled framing (no irpc): EventEnvelope is hand-rolled length-prefixed JSON. See ADR-014.
- Operation registry is layered: Curated (static) + session + connection overlays. OperationEnv is a trait. See ADR-019.
- No secret material on the wire: Capabilities injected at assembly layer. See ADR-010.
- Abort cascades to descendants: Default abort-dependents. See ADR-020.
- Peer authorization via AccessControl: No remote_safe flag. See ADR-024.
- Streams are streams: Every channel is a BiStream. The handler owns its sub-stream multiplexing. See ADR-035.
- Channel 0 is alknet/call: Channel lifecycle is call operations on channel 0. See ADR-036, ADR-037.
- Wire formats are stable: EventEnvelope shape and the 8-byte chunk header are one-way doors. See ADR-014, ADR-034.
References
@alkdev/alknet: docs/architecture/— the source architecture docs these were ported from (renumbered from alknet ADR-001..094 to alkcall ADR-001..045)@alkdev/alktype— the binary struct engine, used for channels chunk header layout and JSON payload schema validation@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/alknetworkspace 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..045 is an alknet source ADR, found at
/workspace/@alkdev/alknet/docs/architecture/decisions/.