docs: re-key architecture docs off the alknet mono-repo — speak as alkcall
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.
This commit is contained in:
1 parent
7b8a3e7558
commit
5f019c02f1
26 files changed
+670
-383
No files matched your search
@@ -76,7 +76,7 @@ on the `BiStream` the channels layer gives them.
|
||||
framing byte, carried transparently.
|
||||
- **The control channel is handler-internal.** TTY sub-demuxes control
|
||||
from its io `BiStream` using its 5-byte format (`STREAM_CTRL_IN = 3`,
|
||||
`STREAM_CTRL_OUT = 4` — ADR-052 amended by Phase 7). The channels layer
|
||||
`STREAM_CTRL_OUT = 4` — alknet ADR-052 (provenance), amended by Phase 7). The channels layer
|
||||
doesn't carry control. The "control isn't actually bidirectional" flaw
|
||||
is fixed at the TTY layer, not the channels layer.
|
||||
- **Recursive composition is literal.** A channel with ALPN
|
||||
@@ -165,7 +165,7 @@ Three things changed since ADR-034/074/077 were accepted:
|
||||
handler boundary — but there may be a generalized reason to expose it
|
||||
(recursive composition, test helpers, the hub relay's `channel_id`
|
||||
rewrite). The exact API shape is an implementation detail for the
|
||||
channels crate, tracked as OQ-68. The *contract* — the channels layer
|
||||
channels crate, tracked as alknet OQ-68 (source-repo space, provenance; in-crate: OQ-24). The *contract* — the channels layer
|
||||
strips its 8-byte header on read and the handler parses its own framing
|
||||
from the payload — is decided here; the *function surface* is not.
|
||||
- **TTY's `wire.rs` adaptation:** TTY's `ChunkReader` currently reads from
|
||||
@@ -174,10 +174,10 @@ Three things changed since ADR-034/074/077 were accepted:
|
||||
stream_type constants, length validation, control message parsing — is
|
||||
unchanged). This is an implementation concern for the channels + TTY
|
||||
integration, not an architecture decision.
|
||||
- **Full channel-level flow-control windowing (OQ-56):** unchanged. The
|
||||
- **Full channel-level flow-control windowing (alknet OQ-56, provenance; in-crate: OQ-23):** unchanged. The
|
||||
bounded-buffer backpressure (ADR-040) is the v1 mechanism; full
|
||||
windowing is an additive extension that doesn't change the wire
|
||||
format. OQ-56 stays deferred(scope).
|
||||
format. alknet OQ-56 stays deferred(scope) in the source repo; this crate tracks it as OQ-23.
|
||||
|
||||
## Decision
|
||||
|
||||
@@ -194,7 +194,7 @@ handler's framing, carried transparently.
|
||||
| field | offset | width | meaning |
|
||||
|-------|--------|-------|---------|
|
||||
| `channel_id` | 0 | 4 (BE) | The logical channel this chunk belongs to. Channel 0 is pre-negotiated as `alk/call` (ADR-036). Channels 1..N are opened dynamically via `channel/open` (ADR-037). |
|
||||
| `length` | 4 | 4 (BE) | The payload length in bytes. 0 = EOF sentinel. Max `MAX_CHUNK_LEN` (16 MiB, matching TTY's cap — ADR-052 §5). |
|
||||
| `length` | 4 | 4 (BE) | The payload length in bytes. 0 = EOF sentinel. Max `MAX_CHUNK_LEN` (16 MiB, matching TTY's cap — alknet ADR-052 §5 (provenance)). |
|
||||
|
||||
The `stream_type` byte is **removed** from the channels header. The
|
||||
channels layer has no `stream_type` concept — not in its header, not in
|
||||
@@ -206,7 +206,7 @@ tunnel's raw bytes, SSH's channel protocol).
|
||||
This amends ADR-034: the wire format is 8 bytes, not 9; the
|
||||
`stream_type` decomposition (mod 3, unidirectional halves, 85 groups) is
|
||||
removed from the channels layer. The stream_type concept survives in
|
||||
TTY's 5-byte format (ADR-052, amended by Phase 7), which the channels
|
||||
TTY's 5-byte format (alknet ADR-052, provenance — amended by Phase 7), which the channels
|
||||
layer carries transparently.
|
||||
|
||||
### 2. `into_sub_streams()` is removed; `accept_bi` is the only accessor
|
||||
@@ -430,7 +430,7 @@ inside-channels), re-introducing a separate inside-channels mode would be
|
||||
a rewrite of TTY's session driver. The trade is one unified session
|
||||
driver now vs. two-mode maintenance forever.
|
||||
|
||||
The add/strip API shape (OQ-68) is a **two-way door** — whether the
|
||||
The add/strip API shape (alknet OQ-68, provenance; in-crate: OQ-24) is a **two-way door** — whether the
|
||||
header add/strip is built into the read/write path or exposed as a
|
||||
standalone utility is an implementation detail that can change without
|
||||
breaking the wire format or the handler contract.
|
||||
@@ -472,7 +472,7 @@ breaking the wire format or the handler contract.
|
||||
`open_channel` and `Channel`)
|
||||
- ADR-044: sub-crate decomposition (unchanged — 8-byte wire format in
|
||||
`channels-core`; call-protocol coupling in `channels-call`)
|
||||
- ADR-052: alknet-tty wire format (the 5-byte format carried
|
||||
- Source-repo provenance (not ported): alknet ADR-052 — alknet-tty wire format (the 5-byte format carried
|
||||
transparently in the channels payload; the control channel split
|
||||
from Phase 7 is TTY-internal)
|
||||
- `docs/research/stream-unification/findings.md` — the research that
|
||||
|
||||
Reference in new issue
Block a user