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

---
status: complete
last_updated: 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. 14 tests pass; 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, one a spec-mandate).
**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:

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` + `auth_token`), 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. **14 tests:** 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`,
   `FORBIDDEN` ×2), 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, upstream question.**
  `from_connection_with_serving` builds channel 0 internally; its
  `Connection::identity()` is empty and `ServingConfig` has no auth
  capture point. The serving dispatcher resolves the caller identity
  ONLY from the payload `auth_token` →
  `ServingConfig.identity_provider` (verified: scoped token → open
  proceeds; absent/foreign token → `FORBIDDEN`). The establisher and
  pump handler receive the connection-establishment-time `AuthContext`
  closed over at `register_openable` — NOT the per-call opener.
  Consequences: (a) a scope-gated reverse-flow open op is satisfiable
  today only via payload tokens (hub-side: attach
  `auth_token` to `call_with_payload`); (b) transport-level
  authentication (mTLS/QUIC peer identity) never reaches the
  open-op ACL on the connect-side serving path. This is the same
  asymmetry the accept side resolved with the install hook's
  `channel0_conn.set_identity`. Candidate follow-ups: `ServingConfig`
  gaining an identity capture, or documented token-only posture.
  → alkcall review ledger (W1).
- **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. The spec should pin "plan payloads are
`Send + Sync`" as a documented constraint of the establisher API.
No upstream change 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), 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
                      + auth_token — W1), ReverseTunnel::open_and_pump
                      (adopt + pump_bidi), join_and_reap/close (W3),
                      bi_stream_from_halves
    harness.rs      — wire(): worker = from_connection_with_serving
                      (TokenIdProvider — W1) + ChannelOperations::
                      register_on + post-hoc openable; hub = adapter +
                      capturing install hook (manager + CallConnection)
  tests/
    tunnel_poc.rs   — 14 tests (see Executive summary)
```

## 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).
4. **W1 remediation** — only the token path is exercised; whether
   alkcall should grow a serving-side identity capture is an upstream
   question (W1), not resolved here.
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

```
14 tests pass; clippy --all-targets -D warnings clean; fmt clean.
Repeat-run stable (3× clean).
```

## 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`.