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).

docs/architecture/decisions/042-hub-relay-translate-not-forward.md

@@ -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
 

docs/architecture/decisions/047-openable-alpns-are-operations.md

@@ -98,7 +98,8 @@ multi-segment `channels/custom/proto/sub`) round-trip byte-stable
 string without the boolean never marks; `op/register` announced
 flavor-form specs round-trip with the marker. Gate 2 (the hub-relay
 round trip) lands with the in-tree relay component (review 008
-remediation plan Unit 3, amending ADR-042).
+remediation plan Unit 3c, amending ADR-042 — the relay export is
+ADR-051).
 
 ## Amendment (§6 listing enrichment, 2026-09-06)
 

docs/architecture/decisions/051-channel-relay-and-hub-leg.md

@@ -0,0 +1,301 @@
+# ADR-051: In-Tree Channel Relay (`ChannelRelay`) and the Hub-Leg Assembly
+
+## Status
+
+Accepted (2026-09-17) — amends ADR-042 (the relay contract's
+implementation home moves into alkcall; the translate-not-forward
+contract is unchanged). Sequenced after review 008 remediation Units 1
+and 2 (both landed, alkcall 0.7.2): the relay's establisher projects
+the spoke reply's extra fields via `Establishment` reply fields
+(ADR-049 amendment 3), and the spoke's flavor-form open ops arrive
+reconstructed WITH the `channel_open` marker through discovery
+(ADR-047 amendment 3).
+
+## Context
+
+Review 008's remediation plan (Unit 3) pinned the in-tree relay as the
+implementation of the review's U-1 gate 2 — the hub-relay round trip
+that proves flavor-form marked ops survive discovery into a genuine
+relay. The as-filed ADR-042 §"Scope note" put the relay implementation
+in `alknet-hub`/downstream; the consumers that now exist (alktunnels'
+graduation, alkhttp's fallback hub, alknodes, and the hub/spoke family
+behind them) all need the same shape, so the implementation moves into
+alkcall as a reusable export.
+
+The consumer family the relay must serve is the hub/spoke composition:
+spokes connect to a hub and expose services; the hub re-exposes those
+services to other spokes (and consumers) based on ACL. Both a hub and
+a spoke can be a relay depending on the setup. A canonical example:
+spoke A exposes `channels/tunnel/direct`; the hub imports it via
+`from_call`, gates it with its own ACL, and re-exposes it on its
+consumer-leg channel-0 registries; spoke B opens through the hub and
+the hub relays the channel to spoke A. The hub performs no port
+binding and no protocol work on the data plane — the property that
+makes the hub-acl-relay role cheap (alktunnels' no-bind posture, the
+same property ADR-042 §What the hub runs pins: "the hub never runs a
+handler for `alk/tty`, `alk/ssh`, or `alk/tunnel`").
+
+Two implementation surfaces were evaluated for the data plane; the
+decision records why the wrapper-composition shape wins over
+byte-forward-with-rewrite.
+
+## Decision
+
+### 1. The relay is the wrapper composition — translate-not-forward, implemented with the existing open-op machinery
+
+ADR-042's two-layer contract is implemented as composition of pieces
+this crate already has:
+
+- **Layer 1 (call-protocol translate)** is the ADR-049 establisher:
+  the hub's consumer-leg open op resolves through the full open-op
+  wrapper (registry ACL → per-identity cap → allocation), then the
+  establisher calls the producer leg's open op, adopts the returned
+  spoke channel id into the producer-leg `ChannelManager`, and returns
+  `Establishment::new(plan)` whose plan carries the spoke-leg streams.
+  The hub allocates its own consumer-leg `channel_id`; the spoke
+  allocated its own producer-leg id; the two ids never appear in each
+  other's namespaces.
+- **Layer 2 (byte-forward)** is the ADR-050 `OpenHandler`:
+  `pump_bidi(consumer_leg_bistream, spoke_recv, spoke_send)` — the
+  pump's generic bounds already match the relay's two legs. The relay
+  never parses chunk framing on either leg; the mux/demux on each leg
+  absorbs the 8-byte header (ADR-034) and the channel-id namespaces
+  are per-connection, so no header rewrite exists. Awaited inline per
+  the R-02 lifetime contract; on completion both legs tear down (the
+  wrapper's handler-exit teardown covers the consumer leg; the pump's
+  send/recv drops EOF the spoke leg).
+
+**The relay map dissolves.** ADR-042 §`channel_id` mapping pinned a
+`HashMap<channel_id, channel_id>` per (browser, spoke) pair maintained
+by the hub. The implementation needs no map: each leg's `ChannelManager`
+already holds its own id → routing state, and the per-channel pump
+closure binds both legs' streams. The mapping is implicit-per-channel.
+This is a two-way-door implementation detail within ADR-042's contract
+(the ADR itself marked the mapping strategy two-way).
+
+**`channel/close` and `channel/control` need no translation surface.**
+Consumer-side close → wrapper teardown → pump abort → send-half drop →
+EOF chunk → spoke handler exits → spoke's own wrapper decrements its
+ledger. Close propagates through the EOF cascade with correct ledger
+accounting on both legs; the hub never sees a `channel/close` to
+translate. Control stays per-leg (`channel/control` is not implemented
+upstream, OQ-39 — a hub wanting cross-leg control translation composes
+it downstream). This supersedes the ADR-042 §mapping bullet's
+close-translation sentence as an implementation matter: the mapping
+entry the sentence's removal depended on does not exist.
+
+### 2. What the relay holds on the producer leg: `CallConnection` + `ChannelManager`
+
+The relay's producer-leg surface is `Arc<CallConnection>` (for the
+translate hop's open call) plus the producer-leg `ChannelManager` (for
+`adopt_channel` and teardown visibility) — not a `ChannelClient`.
+
+Rationale: `ChannelClient`'s calling surface detaches on
+`take_call_connection` (the hub needs the connection for `from_call`
+import AND for the relay's establisher AND possibly its own ops —
+three claimants), while `Arc<CallConnection>` is `Clone` and the
+client's manager accessor yields the same `ChannelManager` the relay
+needs. A hub that dials the spoke with `ChannelClient::from_connection`
+and then tears the client down after import keeps the relay alive on
+the `Arc`s. The establisher builds its forwarded payload directly
+(`build_forwarded_payload` semantics — the hub as caller, the consumer
+as `forwarded_for`, ADR-026 §3) rather than through
+`call_open_op`, which carries no payload variant.
+
+The spoke reply's `channel_id` is stripped before projection (the
+consumer-leg reply carries the hub-allocated id, not the spoke's);
+the spoke reply's other fields ride through `with_reply_fields` —
+`bound` flows end-to-end with per-hop truthfulness (a hub re-producing
+a listen resource binds its own listener and contributes its own
+`bound`; alktunnels ADR-008 §Hub re-produce).
+
+### 3. Reason-code mapping (spoke `CallError` → `EstablishmentError`)
+
+The spoke's open can fail with the full call-error vocabulary; the
+establisher maps it into `EstablishmentError` by class:
+
+| Spoke failure | `EstablishmentError` variant | Wire reason |
+|---|---|---|
+| `channel:open_failed` with a typed reason | the same class — `DialFailed` for `dial_failed`/`timeout`, `UnknownResource` for `unknown_resource`, `ResourceShortage` for `resource_shortage`, `HandlerError` for `handler_error` | the mapped reason |
+| `channel:open_failed` reason `timeout` | `DialFailed` (the spoke establishment exceeded the spoke bound — from the consumer's side it is unreachable-target-shaped) | `dial_failed`, spoke message preserved |
+| `NOT_FOUND` (spoke predates the op) | `HandlerError` carrying the code | `handler_error` |
+| `FORBIDDEN` (hub lacks the spoke grant) | `HandlerError` carrying the code | `handler_error` |
+| other `CallError` | `HandlerError` carrying the code | `handler_error` |
+
+The spoke's original code and message are preserved in the mapped
+variant's `message` (never discarded — a consumer debugging a
+FORBIDDEN-through-relay must see the spoke's grant failure, not a bare
+`handler_error`). The `timeout` mapping is the one non-1:1 case: the
+consumer-visible reason is `dial_failed` because establishment
+timeouts are wrapper-generated (ADR-049 §3) and not an establisher
+vocabulary word; the spoke's message carries the truth.
+
+### 4. The registration seam: two phases, fork-registry registration
+
+Openable ops register on a **per-connection fork of the hub's base
+registry** installed as the consumer leg's dispatch registry (the
+ADR-047 §4 amendment mechanism). Discovery of the producer leg's ops
+happens once (hub startup or reconnect); registration happens per
+consumer-leg connection inside the `install_channel_zero` hook. The
+one-call signature the review sketched cannot exist without adapter
+changes — the two phases are the API:
+
+1. **Discover/stash** — `from_call` against the producer leg returns
+   the imported `HandlerRegistration` bundles. Marked specs (rebuilt
+   WITH the `channel_open` marker, ADR-047 amendment 3) are separated
+   from plain bundles by the marker. The stash is a `Clone`able
+   template: `HandlerRegistration` and `HandlerKind` are `Clone`, and
+   `OperationRegistry::fork` deep-copies registrations, so one
+   discovered set serves any number of consumer legs.
+2. **Register per connection** — the hub-leg install hook forks the
+   base registry, registers the generic channel ops
+   (`ChannelOperations::register_on`), registers the stashed plain
+   bundles as-is (the existing forwarding handlers), and registers
+   each stashed marked spec via the relay's
+   `register_relay_openable` (the fork is the `consumer_registry`
+   argument), then dispatches channel 0 over the fork.
+
+Per-consumer ACL differentiation is a composition consequence, not a
+mechanism: the fork is per consumer leg, so a hub re-exposing
+different op subsets to different consumers filters the stash per
+fork. The imported spec's own `access_control` remains the gate for
+the re-exposed op; the hub composes additional ACL at its assembly
+layer.
+
+### 5. The hub-leg install hook is an in-tree export (the call-half support)
+
+Every existing test hand-rolls the hub-side install hook
+(`make_install_channel_zero`-shaped); the hub/spoke family all need
+the same composition. The relay lands with a documented hub-leg
+template — fork, generic ops, bootstrap discovery, stashed bundles
+(plain + relay), per-call identity resolution (`ServingConfig`-shaped),
+single-stream dispatch loop — as an in-tree composition (unit-scoped:
+Unit 3b). This is composition of existing pieces, not a new protocol
+surface; its exact API shape is a two-way-door implementation detail.
+The spoke side needs nothing new: a spoke serving ops through a hub is
+the existing connect-side serving shape (`from_connection_with_serving`)
+plus the producer-leg registration it already does.
+
+**ACL layering note (pinned, because it surprises):** the spoke's
+`AccessControl` sees only the hub's identity — the end consumer's
+identity rides `forwarded_for` as metadata and is never consulted by
+any `AccessControl::check` (ADR-024/ADR-026). "The hub re-exposes
+based on ACL" therefore means: the hub-side gate is the imported
+spec's ACL (+ hub policy) on the consumer leg; the spoke-side grant
+goes to the hub identity, which needs scopes on every spoke op it
+relays. The end consumer never authenticates to the spoke directly.
+
+### 6. Bounds: rejected shapes and residual notes
+
+- **Pub-typed open ops** — rejected loudly (`channel:pub_open_not_implemented`,
+  the C-08 blocker). The relay registers only `Query`/`Mutation`-typed
+  ops (plain forwarding) and `Sub`-typed marked ops (relay openables);
+  a discovered `Pub`-typed marked spec is an assembly error, not a
+  silent stub.
+- **Compounding establishment bounds** — each hop's establisher is
+  bounded independently (ADR-049 §2); an N-hop chain adds N bounds.
+  The consumer's dispatch deadline (`min(deadline, 10s)` per hop)
+  bounds each hop, not the chain. No fix — noted for capacity
+  planning.
+- **Mid-establishment consumer disconnect** — the one teardown window
+  with a delay: the spoke channel can exist briefly after the consumer
+  leg dies. Not a leak: once the wrapper spawns the pump, hub-leg
+  `clear_all` (transport EOF) EOFs the consumer recv, the pump exits,
+  the spoke leg EOFs, and both wrappers decrement their ledgers. The
+  e2e gate asserts this window explicitly.
+- **Multi-hop relays** — a chain of relays composes (each hop is a
+  hub leg pair), with the compounding-bound note above. No special
+  machinery.
+
+## Consequences
+
+**Positive:**
+
+- The relay is O(1) new machinery: an establisher closure, a
+  `pump_bidi` handler, and a registration entry point. No parallel
+  auth path (the consumer leg's full wrapper machinery applies), no
+  new wire surface (the relay speaks only already-stable ops), no
+  data-plane parsing (ADR-034's one-way door stays closed).
+- `from_call` gains a real in-tree consumer for the marker-branching
+  seam Gap C named (ADR-047 §Gap C): downstream crates compose
+  `ChannelRelay` instead of re-deriving the hub shape.
+- U-1's gate 2 (the review's silent-failure scenario — flavor-form ops
+  relaying as plain forwarding stubs) becomes a permanent e2e gate.
+
+**Negative:**
+
+- New pub API (`ChannelRelay`, the registration entry point, the
+  hub-leg template) — minor bump, one release with the review's other
+  units, review-007 precedent.
+- The two-phase discover/stash-then-register shape is more assembly
+  code for a trivial hub than a one-call import would be. The fork
+  mechanism forces it; the stash being `Clone` keeps the per-connection
+  work cheap.
+- The hub holds `Arc<CallConnection>` + `ChannelManager` per spoke leg
+  for the connection's lifetime — per-leg state, bounded by the spoke
+  count.
+
+## Door type
+
+**Two-way (implementation shape) within a one-way posture.** The
+translate-not-forward contract (ADR-042) and the ACL layering are
+unchanged one-way decisions; the in-tree export, the implicit-mapping
+implementation, and the two-phase registration shape are revisable
+implementation details — downstream crates compose the export, not the
+internals. The rejection posture for Pub-typed marked ops is loud (an
+assembly error), so a future implementation of the Pub path is
+additive.
+
+## Verification gates (implementation units)
+
+Unit 3a (the relay component):
+
+1. `register_relay_openable` on a forked consumer-leg registry
+   resolves the open op end-to-end; the establisher populates
+   `forwarded_for` from the consumer's per-call identity (ADR-026 §3)
+   and strips the spoke reply's `channel_id`.
+2. A spoke `channel:open_failed` maps to the consumer-leg
+   `channel:open_failed` with the mapped reason (the §3 table) and the
+   spoke's message preserved; the consumer leg tears down (ledger
+   decremented); no spoke channel leaks.
+3. `bound` (Unit 1's reply projection) survives the relay to the
+   consumer reply.
+4. Pub-typed marked specs are rejected at registration.
+
+Unit 3b (the hub-leg template):
+
+5. The template composes fork + generic ops + bootstrap discovery +
+   plain bundles + relay openables + serving identity and dispatches
+   channel 0; `services/list` on the consumer leg shows the
+   re-exposed ops.
+
+Unit 3c (the gate-2 e2e):
+
+6. The review's full harness: consumer → hub (forked channel-0
+   registry + relay) → producer, opening `channels/tunnel/direct` end
+   to end: the open resolves with the hub-allocated `channel_id`, the
+   establisher-contributed `bound` field survives to the consumer
+   reply, data flows both directions (the hub never parses it), and
+   hub-side disconnect / spoke-side close tears down both legs
+   (including the mid-establishment window from §6).
+7. A companion `channels/tty/sub` relay run pins no regression on
+   standard shapes.
+
+## References
+
+- ADR-042 (amended by this ADR — the implementation home; the
+  contract unchanged; the relay map and close-translation bullets
+  superseded by the implicit-per-channel shape)
+- ADR-047 amendment 3 (flavor-form ops reconstruct WITH the marker —
+  the discovery input this relay consumes), §Gap C (the
+  marker-branching seam), §4 amendment (the fork mechanism Unit 3b
+  composes)
+- ADR-049 amendments 2/3 (the plan payload the relay's establisher
+  carries; the reply projection `bound` rides through)
+- ADR-026 §3 (forwarded_for on the translate hop), ADR-050
+  (`pump_bidi` — the byte-forward hop), ADR-040/041 (the caps the
+  consumer leg keeps enforcing)
+- alktunnels ADR-007/008 (the first consumers: the direct op's relay
+  and the listen `bound` field's per-hop truthfulness)
+- Review 008 remediation plan Units 1–3 (the sequencing this ADR
+  lands inside)