docs(review 008 Unit 3 planning): ADR-051 — in-tree ChannelRelay + hub-leg assembly; plan split into 3a/3b/3c

Design session outcome for the relay unit. The hub/spoke family (hub
or spoke may relay; the hub re-exposes spoke services by ACL without
binding ports) needs the call-half support too, so the unit's scope
grew beyond the as-pinned sketch and is now three sub-units.

- ADR-051 (new): the relay is the wrapper composition — translate hop
  = the ADR-049 establisher shape, byte-forward hop = pump_bidi per
  ADR-050; the relay holds Arc<CallConnection> + ChannelManager per
  producer leg (not a ChannelClient — take_call_connection's detach
  is wrong for a hub with three CallConnection claimants); the reason
  mapping preserves the spoke's code+message (timeout is the one
  non-1:1 case, mapping to dial_failed); the registration seam is
  two-phase (discover/stash → per-connection fork-register — the
  ADR-047 §4 fork mechanism makes a one-call import impossible); the
  ADR-042 relay map dissolves (implicit per-channel mapping) and
  channel/close needs no translation surface (EOF cascade propagates
  with correct ledger accounting on both legs); Pub-typed marked
  specs are a loud assembly error; establishment bounds compound per
  hop (noted, no fix); the ACL layering note is pinned (the spoke's
  AccessControl sees only the hub identity; forwarded_for is never
  checked).
- ADR-042 amended: the §Scope note is revised (implementation is an
  alkcall export; hub crates compose it) and the two mechanism
  supersessions are recorded — the contract and auth-model rationale
  unchanged.
- ADR-047 amendment 3's forward reference and the README ADR index
  updated (001..051).
- Review 008 remediation plan: Unit 3 split into 3a (ChannelRelay
  component + gates), 3b (hub-leg install template — the call-half
  support), 3c (gate-2 e2e incl. the mid-establishment disconnect
  window); sequencing note updated; adoption note records the
  session's decisions.

Verified: cargo doc --no-deps (markdown-only change).
This commit is contained in:
glm-5.3-flash committed 2026-09-17 06:47:48 +00:00
1 parent 620180d615
commit 91765446b7
5 files changed
+505 -69

No files matched your search

@@ -2,7 +2,52 @@
## Status
Accepted
Accepted (amended 2026-09-17, ADR-051 — the relay implementation is an
alkcall export (`ChannelRelay`), not downstream-only code; the §"Scope
note" below is revised, and the §`channel_id` mapping / close-translation
mechanism is superseded by an implicit-per-channel shape — see
"Amendment (ADR-051, in-tree relay export, 2026-09-17)" below;
the translate-not-forward contract and the auth-model rationale are
unchanged)
## Amendment (ADR-051, in-tree relay export, 2026-09-17)
The relay implementation moved into alkcall as a reusable export
(`ChannelRelay`, ADR-051) — consumers that exist (alktunnels'
graduation, alkhttp's fallback hub, alknodes) all need the same shape,
so the §"Scope note" decision ("the relay implementation lives in
`alknet-hub`/downstream") is revised: hub crates COMPOSE the export.
Two implementation findings supersede mechanism text above, both
within the two-way door this ADR already marked:
1. **The `channel_id` mapping dissolves.** §`channel_id` mapping
pinned a `HashMap<channel_id, channel_id>` per (browser, spoke)
pair. The implementation needs no map: each leg's `ChannelManager`
holds its own id → routing state, and the per-channel pump closure
binds both legs. The mapping is implicit-per-channel — a
`channel_id` never crosses legs, so the translate hop produces
per-leg-truthful ids (this also refines alktunnels ADR-008 §Hub
re-produce's "re-map the id at their re-produce hop naturally":
the re-map is two independent allocations, not a rewrite).
2. **`channel/close` needs no translation surface.** The §mapping
bullet's "On `channel/close` (translated the same way), the mapping
is removed" assumed the map; without it, close propagates through
the EOF cascade (consumer-side close → open-op wrapper teardown →
pump abort → send-half drop → EOF chunk → spoke handler exits →
spoke's own wrapper decrements its ledger) with correct accounting
on both legs. The hub never sees a `channel/close` to translate.
`channel/control` stays per-leg (OQ-39 — a hub wanting cross-leg
control translation composes it downstream), unchanged.
The byte-forward layer is ADR-050's `pump_bidi` per channel (the
hub never parses chunk framing — stronger than §"Data-channel layer"'s
rewrite phrasing, which assumed the map-based rewrite shape). The
translate layer is the ADR-049 establisher shape
(`register_relay_openable`), keeping the consumer leg's full wrapper
machinery (registry ACL, per-identity cap/ledger, establishment bound,
teardown-on-failure) — the auth-model rationale above is unchanged and
now has a concrete in-tree carrier.
## Context