glm-5.3-flash
5f019c02f1
The ported docs still framed alknet siblings (alknet-core/-call/-channels/
-http/-tls/-client) as live load-bearing context of this crate. With the
extraction complete and alknet headed for glue-level replacement, the docs
now speak as alkcall and cite the real sibling crates (alkhttp, alktls,
alktty, alktunnels, alktrader).
- ADR-054 (new): re-own the verifier-selection rule in-crate — three
remote roles (public X.509 endpoint / transport relay / hub),
ServerCertVerifier by PeerEntry presence, RemoteIdentity None
load-bearing. Provenance: alknet ADR-034 (never ported), demoted to
footnote. Resolves OQ-21's cross-repo authority gap.
- OQ-43 (new, 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, ADR-045 dial
seam). README layering diagram redrawn with the composition layer as
TBD-ownership instead of "alknet / alknode" in concrete.
- Spec docs reframed: titles, self-references, dial/TLS/from_jsonschema
homes, malformed legacy cite rows removed; dead relative research
paths qualified as source-repo paths.
- ADR amendments (append-only): 027 (alknet-http -> alkhttp), 031 (post-
extraction state), 044 (split landed as modules in alkcall), 045
(name normalization; citation-space note).
- Citation hygiene: unprefixed/colliding source-repo cites prefixed
("alknet ADR-NNN (provenance)") across 009/011/022/034/035/038/040/
043/044/045; stale OQ cites corrected (session registries OQ-04, batch
semantics OQ-03, verifier rule ADR-054); stale anchors fixed.
- README provenance note consolidated; citation conventions documented.
Verification: markdown link check (all local links resolve, all in-crate
ADR cites point at existing decisions/ files); table integrity check
(uniform row widths across open-questions.md and edited tables); residual
alknet-mention sweep (only provenance/historical/intentional framing
remains); architecture review subagent pass with zero remaining criticals.
Docs-only change — no code paths touched.
333 lines
24 KiB
Markdown
333 lines
24 KiB
Markdown
---
|
|
status: draft
|
|
last_updated: 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](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 moved to alkhttp (ex-`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, pub/sub, and later amendments — ADR-034..054
|
|
|
|
| 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/<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](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 |
|
|
| [052](decisions/052-channel-control-surface.md) | `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](decisions/053-resource-enumerators.md) | Live Resource Enumerators | `ResourceEnumerators` (peer-shared registry); snapshot-then-changes enumerator contract; scan-once aggregation; empty seed; resolves OQ-40 |
|
|
| [054](decisions/054-outgoing-only-x509-three-remote-roles.md) | 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](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 `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
|
|
|
|
```
|
|
┌──────────────────────────────────────────────┐
|
|
│ 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](open-questions.md)). |