alktunnels/docs/research/reverse-poc-summary.md

status, last_updated

status	last_updated
complete	2026-09-07

alktunnels: Reverse-Flow (-R) Tunnel POC Research Summary

Status: Research complete — the -R shape (the hub opens tunnel channels toward a connect-side worker that serves its own open op) validated end-to-end over alkcall 0.6.0 (2026-09-07 pass, 14 tests) and re-validated over alkcall 0.7.0 (16 tests) after the CF-005/CF-006 identity remediation landed — the W1 auth_token workaround is dead; the primary caller-identity path is transport identity. Clippy -D warnings clean; fmt clean. The review 007 non-finding trace ("no upstream mechanism is missing") is confirmed by execution — and the POC surfaced two real findings the forward POC could not (one an upstream sharpness question — F-1, documented upstream in 0.7.0; one a spec-mandate — F-2). Date: 2026-09-07 Scope: Validates the OQ-TN-10 #2 POC — the SSH tcpip-forward template (register → per-accept channel-open → cancel) mapped onto alkcall's both-sides serving semantics. Probes four wrinkles (W1..W4) selected from the mechanism trace; findings F-1/F-2 below.

---

Executive summary

A POC (alktunnels-reverse-poc, /workspace/alktunnels-reverse-poc) validated the reverse flow end-to-end over alkcall 0.6.0 (re-validated over 0.7.0 — see §W1):

1. The worker (connect side, serving side) — dials the transport, ChannelClient::from_connection_with_serving + ChannelOperations::register_on (generic channel ops on the serving registry, so the hub can channel/close) + post-hoc register_openable_with_establisher (W2). Its establisher dials the resource target and returns the handle via Establishment::new(plan) — R-01's plan flow, no handoff map. Its pump handler awaits alkcall::channels::pump_bidi inline (R-02/R-03). This is ADR-022 §2 both-sides semantics exercised for real: connect side AND serving side.
2. The hub (accept side, reverse-flow initiator) — ChannelsAdapter + install hook that captures the hub's channel-0 CallConnection and ChannelManager. Per local accept: call the worker's open op (call_with_payload — the caller identity rides the transport identity by default (0.7.0); the payload auth_token is the optional hub-forwarding path), adopt the worker-allocated channel ID, pump the accepted socket against the adopted halves via pump_bidi spawned locally.
3. The ADR-047 §5 orientation under test holds: the reverse channels are allocated by the worker (connect side — odd IDs) and adopted by the hub (accept side). "Connection owner allocates" exercised in the Pub-like orientation.
4. 16 tests (0.7.0 pass): TCP round trip, 1 MiB backpressure, half-close semantics, concurrent same-resource channels (the R-01 race-killer proven: two opens of one resource, distinct channels, distinct dialed handles), UDP round trip, TCP+UDP concurrent, typed establishment errors (unknown_resource, dial_failed), the identity precedence chain (transport identity alone / ServingConfig.identity override / token override / identity-less fail-closed), CF-006 per-call opener witness, out-of-band channel/close, worker outbound calls resolving while serving, late-registration visibility, and two finding-pinning tests (F-1 compiler-pinned, F-2 below).

Wrinkle probes (W1..W4) — results

• W1 identity on the serving path — CONFIRMED 2026-09-07 against 0.6.0; RESOLVED by alkcall 0.7.0 (ledger CF-005 + CF-006). Original finding: from_connection_with_serving built channel 0 internally; its Connection::identity() was empty and ServingConfig had no auth capture point — the serving dispatcher resolved the caller identity ONLY from the payload auth_token → ServingConfig.identity_provider, and the establisher/pump handler received the install-time AuthContext, never the per-call opener. The 0.7.0 remediation (validated from this POC's topology, 16 tests):
  • ServingConfig.identity: Option<Identity> — the explicit override (remediation (a)).
  • The transport Connection::identity() (set before dialing — the mTLS/QUIC posture) propagates to channel 0 automatically (remediation (b)). Validated: the POC's default harness now authorizes the scope-gated open on transport identity ALONE — no token payload.
  • Precedence (alkcall cf005 tests + POC probes): payload token > ServingConfig.identity > transport identity; none → fail-closed FORBIDDEN (validated).
  • CF-006 corollary: the establisher/pump handler now receive the per-call opener identity (validated via an identity witness — the establisher saw hub, and the override identity under (a)). On hub-forwarded opens the establisher sees the end client, not the hub. Status: resolved — the POC's auth_token workaround is dead code; the primary path is transport identity.
• W2 post-hoc openable registration — works. The worker registers its openable AFTER from_connection_with_serving returns; the dispatcher reads through the shared Arc<OperationRegistry> per dispatch. Proven by every open succeeding + a direct registration() assertion. No finding — the assembly order (construct client → register ops → serve) is viable as-is.
• W3 adopter self-reaping — confirmed asymmetry, POC-local fix. The serving side's channel is wrapper-managed (teardown cascades on pump completion or out-of-band close). The ADOPTING side has no such machinery: adopt_channel installs routing state nothing awaits. The hub must hold its pump handle and reap (teardown_channel) itself — ReverseTunnel::join_and_reap/close in the POC. Spec note: the real crate's consumer half needs a session type with the same ownership (the adopted channel + pump handle + reaper). Not an upstream gap (the hub's lifecycle is assembly-layer by design, OQ-TN-04) — but it is the reason TunnelSession in the spec must own teardown explicitly.
• W4 EOF sentinel propagation — works both ways. Half-close semantics test: local shutdown() → EOF sentinel into the mux → worker pump sees the zero-length read → shuts the target write down; the target's echo still flows back before the reverse leg completes. pump_bidi's shutdown-on-completion contract holds across the reverse path unchanged.

Findings

F-1 — ChannelPlan's Send + Sync bound constrains plan payloads (compiler-pinned)

ChannelPlan = Arc<dyn Any + Send + Sync> (ADR-049 amendment 2). A dialed-socket handle whose halves are Box<dyn AsyncRead + Send + Unpin> does NOT satisfy the bound — Arc<T> requires T: Send + Sync, and dyn AsyncRead is not Sync by default. The POC widened the halves to + Sync (socket halves are Sync, so dial-shaped payloads are unaffected). Implications for Phase 1: tunnel plan payloads (target handles) must be Sync, which is fine for socket-backed substrates but would exclude non-Sync handles (e.g. process pipes as boxed trait objects) without a wrapper. Documented upstream 2026-09-07 (alkcall 0.7.0): the ChannelPlan type doc now carries the Send + Sync payload constraint. No further action needed — the bound is correct (the plan crosses the wrapper task boundary).

F-2 — empty UDP datagrams collide with the EOF sentinel in raw pass-through (spec-mandate)

The raw pass-through pump shape (tokio::io::copy between the UdpHalf adapter and the channel) cannot carry an empty datagram: poll_recv returning zero bytes is Ok(0) from the adapter — indistinguishable from EOF for copy, which treats it as end-of-stream and shuts the pump down. An empty datagram and the zero-length EOF sentinel are the SAME wire shape at the pump level. Pinned by test (reverse_udp_empty_datagram_finding asserts the non-round-trip so the conclusion is executable, not anecdotal). Consequence: the forward POC's codec decision — [len: u16 BE] framing for UDP — is now validated from a SECOND angle: not only does it preserve boundaries, it is MANDATORY for correctness (an empty datagram is 2 bytes under the codec, unambiguous with EOF). The Phase 1 spec must state: UDP rides the length-framed codec, never raw pass-through. Stream substrates (TCP, unix) keep raw pass-through — a zero-length read there is genuinely EOF.

The -R registration template (SSH tcpip-forward analogue)

SSH: global request tcpip-forward → per-accept forwarded-tcpip channel opens toward the forwarder → cancel-tcpip-forward.

Mapped onto the validated surface (OQ-TN-03's role-follows-resource model — no protocol-level direction):

SSH	alktunnels reverse shape (validated)
tcpip-forward registration	hub binds the listener locally (OQ-TN-04: binding is assembly-layer; no advertisement op needed for the hub's OWN listeners)
server-side accept loop	hub accept loop (assembly layer)
per-accept forwarded-tcpip open	hub calls the worker's served open op per accept (call_with_payload) + adopt_channel
target dial	worker's establisher dials the resource (establishment phase — typed errors)
cancel-tcpip-forward	hub closes: pump teardown + teardown_channel (and/or channel/close out-of-band on the worker)
originator pair (informational)	not needed — ACL rides the channels open-op machinery

Key validation: no advertisement surface is needed in the base crate. The "please listen on your side" step of SSH's template dissolves when the listener is the hub's own local resource — the hub does not ask the worker to listen; the worker serves open ops, and the hub opens channels whenever its own accepts fire. An advertisement op only becomes necessary if the LISTENER lives on the far side ("worker, expose port 8080 on your end") — which is the worker exposing a produced resource = the forward shape with the listener as the resource (producer-side listen is an establisher variant, not a new mechanism). This closes the last open thread of OQ-TN-03's original question set (the -R advertisement/lifecycle surface).

What was built

alktunnels-reverse-poc/
  Cargo.toml        — alkcall 0.6.0; tokio wasm-clean subset + net (POC-local)
  src/
    lib.rs          — module docs; wrinkle overview
    producer.rs     — worker half: tunnel_open_spec, tunnel_establisher
                      (Establishment::new(plan) — R-01; per-call
                      identity witness — CF-006), make_tunnel_
                      pump_handler (pump_bidi inline — R-02/03),
                      register_tunnel_openable (post-hoc, W2)
    producer/
      params.rs     — TunnelParams {resource, substrate} + the UdpHalf
                      adapter (Send + Sync — F-1)
    consumer.rs     — hub half: open_reverse_channel (call_with_payload
                      with optional auth_token — now the fallback
                      path; primary is transport identity, 0.7.0),
                      ReverseTunnel::open_and_pump (adopt +
                      pump_bidi), join_and_reap/close (W3),
                      bi_stream_from_halves
    harness.rs      — wire()/wire_with(): worker =
                      from_connection_with_serving (transport identity
                      + ServingConfig identity/provider — the 0.7.0
                      precedence chain) + ChannelOperations::
                      register_on + post-hoc openable; hub = adapter +
                      capturing install hook (manager + CallConnection)
  tests/
    tunnel_poc.rs   — 16 tests (see Executive summary + §W1)

What the POC does NOT validate

1. A real transport — tokio::io::duplex stands in for TCP/TLS/QUIC (unchanged from the forward POC scope).
2. The advertisement op for far-side listeners — resolved as "not needed" (see the template table); if a deploy mode ever wants "worker, expose a port on YOUR side," that is a producer-side listen establisher over the same open op — spec-shaped, not POC- shaped.
3. Unix socket + stdio substrates — OQ-TN-10 #3 (cheap; the pump is substrate-agnostic and both POCs now confirm it). Phase 1 resolution: unix in via the local feature; stdio OUT — alktty's pipe mode owns process stdio (OQ-TN-14).
4. W1 remediation — resolved 2026-09-07 (alkcall 0.7.0): the remediation IS now exercised from this POC's topology (transport identity, ServingConfig.identity override, precedence, fail-closed, CF-006 witness). Remaining un-exercised: fingerprint- based identity resolution (resolve_from_fingerprint — the POC's duplex transport has no TLS layer to fingerprint).
5. Multi-hop (hub relay traversal) — single hop; relay forwarding (alkcall ADR-042) is transparent per leg.
6. Wasm — POC-local tokio/net; the real crate's protocol-only core stays wasm-clean (unchanged conclusion).

Verification

0.6.0 pass:  14 tests; clippy -D warnings clean; fmt clean.
0.7.0 pass:  16 tests (W1 remediation probes added, foreign-token
             probe obsoleted by the precedence chain); clippy -D
             warnings clean; fmt clean; repeat-run stable (3×).

References

• alkcall 0.6.0 — review 007 remediation as consumed here: ADR-049 amendment 2 (Establishment::new(plan), R-01), ADR-050 (channels::pump_bidi, R-03), R-02 JoinHandle contract.
• alkcall review 007 §Part B — the reverse-flow non-finding trace (from_connection_with_serving + register_on + serving-side allocation) — confirmed by execution.
• alkcall ADR-022 §2 — both-sides serving semantics (the worker's shape). ADR-047 §5 — connection-owner allocation (the odd-ID orientation). ADR-037/ADR-042 — channel ops, relay.
• alktunnels docs/research/phase-0-findings.md — OQ-TN-03 (direction semantics — the advertisement thread this POC closes), OQ-TN-04 (no forced binding — the hub binds, the worker never does), OQ-TN-09 (half-open residual — validated W4), OQ-TN-10 #2 (this POC).
• alktunnels docs/research/ssh-socks5-survey.md §RFC 4254 §7.1 — the tcpip-forward template mapped in the table above.
• forward POC (poc-summary.md) — the codec decision F-2 strengthens; the UdpHalf adapter reused; the plan flow replaces HandleHandoff.