alktunnels/tasks/tunnels/producer-open-op.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
tunnels/producer-open-op	Producer half — establisher (dial shape) + pump handler + register_tunnel_openable	completed	tunnels/params tunnels/wire-codec	broad	high	phase	implementation	producer establisher open-op pump

Description

Implement src/producer.rs per producer.md: the dial-shape establisher, the substrate-agnostic pump handler, and the registration surface. This is the crate's core — the open op that both POCs validated (the forward POC's producer on the accept side; the reverse POC's worker on the connect side). Port from the REVERSE POC first (/workspace/alktunnels-reverse-poc/src/producer.rs) — it is the 0.6/0.7 idiomatic shape (plan flow, no handoff) and its 16 tests are the reference suite.

The establisher (dial shape — the listen shape is a separate task)

pub type DialFn = Arc<
    dyn Fn(Substrate, &str) -> BoxFuture<'static, Result<TargetHandle, TunnelEstablishError>>
        + Send + Sync,
>;
// TargetHandle: boxed halves (read: Box<dyn AsyncRead + Send + Sync + Unpin>, write: ...),
// or the framed UDP adapter (the establisher wraps BEFORE returning the plan —
// ADR-003's placement; the pump stays substrate-agnostic)

• tunnel_establisher(registry: ResourceRegistry, dial: DialFn, identity_witness: Option<...>) -> OpenEstablisher — the assembly layer injects the substrate dial function (ADR-004); the establisher:
  1. Parses params (TunnelParams — schema-validated upstream, semantic parse here).
  2. Registry lookup (resource, substrate) → backing address — unknown_resource on miss (typed reason mapping per ADR-001's table).
  3. dial(substrate, backing) → the handle (the closure owns real socket code — behind local or assembly-constructed).
  4. UDP: wrap in the framed adapter (ADR-003) — UdpHalf + codec, truncation fail-loud (OQ-TN-13).
  5. Return Ok(Establishment::new(Arc::new(handle))) (R-01 plan flow).
• ResourceRegistry: the assembly-owned HashMap<(String, Substrate), String> (POC shape; OQ-TN-11's collision domain) with register/lookup async methods.

The pump handler

pub fn make_tunnel_pump_handler() -> OpenHandler

1. Downcast the plan to TargetHandle (Arc::downcast — error path: log + return; the birth-teardown telemetry catches it).
2. conn.accept_bi() (yield-once).
3. pump_bidi(bidi, t_read, t_write) — awaited inline (R-02: the returned JoinHandle tracks the data-plane lifetime; early return = teardown-at-birth). The handler is substrate-agnostic by construction — it must not know what the halves came from (ADR-004).

Registration

pub fn register_tunnel_openable(
    core: &ChannelCore,
    registry: &ResourceRegistry,
    on_registry: &Arc<OperationRegistry>,   // the session's dispatch registry (ADR-047 §4 fork)
    auth: AuthContext,
    dial: DialFn,
) -> Result<(), String>

• Wires tunnel_open_spec() + the establisher + the pump via register_openable_with_establisher (timeout None = the 10s default).
• Post-hoc registration is supported (W2): the dispatcher reads through the shared Arc per dispatch.

Integration tests (the POC suite, ported)

Port the reverse POC's test topology (harness.rs: worker = from_connection_with_serving + ChannelOperations::register_on + post-hoc openable; hub = adapter + capturing install hook) into tests/ with the dial closure standing in for real sockets (in-process duplex halves — no local feature needed). Cover: establishment success + typed errors (unknown_resource / dial_failed / FORBIDDEN / timeout-adjacent), the plan flow under same-resource concurrency, per-call opener identity (CF-006 witness), late-registration visibility, pump round-trip through pump_bidi.

Acceptance Criteria

• Establisher: typed reason mapping exact (ADR-001's table)
• Pump handler: pump_bidi inline; no spawn-and-forget; no substrate types leak into the handler
• register_tunnel_openable wires spec + establisher + pump + dial injection
• Integration tests: forward AND reverse topology (the harness shapes from both POCs), ≥8 tests covering the above
• Clippy/fmt clean; wasm32 check passes (dial closures are runtime-injected — the crate compiles without local)
• cargo test green

References

• docs/architecture/producer.md (the normative shapes)
• docs/architecture/decisions/001/003/004 (params, codec placement, no trait)
• POC reference: /workspace/alktunnels-reverse-poc/src/producer.rs + harness.rs + tests/tunnel_poc.rs (the 0.7.0-idiomatic shapes)

Notes

• Ported from the reverse POC's producer.rs (the 0.7.0-idiomatic plan flow, R-01) with the crate generalizations:
  • The dial closure is INJECTED (DialFn) — the POC had real socket code inline (tokio TCP/UDP); the crate's establisher is substrate-agnostic and the local feature (or the assembly layer) supplies the closure (ADR-004's inversion point, tested via in-process duplex echo + failing dials).
  • register_tunnel_openable takes dial + identity_witness (the CF-006 probe seam) — the POC's registration closure had no dial injection.
  • ResourceRegistry keys on (String, Substrate) (the enum, not a &'static str — Hash added to Substrate).
  • TargetHandle carries + Sync halves (the F-1 plan-payload bound).
• Harness (tests/harness.rs): the reverse POC's topology (producer = from_connection_with_serving on the connect side, consumer = ChannelsAdapter + capturing install hook) with the dial closure standing in for sockets. The consumer drives the open op via call_with_payload on channel 0 and adopts the producer-allocated ID.
• 11 integration tests: round-trip through pump_bidi (wrapper reaps the producer channel on pump completion — R-02), unknown_resource + dial_failed typed errors (no phantom channel either side), FORBIDDEN identity-less (fails closed), transport-identity open (CF-005 (b)), token precedence (CF-005 (a) + the CF-006 witness), same-resource concurrency (no plan race), late registration (W2), unknown substrate schema rejection (INVALID_INPUT — the registry's schema-validation runs before the establisher), outbound-calls- resolve-while-serving (ADR-022 §2), substrate-keyed registry lookups.
• alkcall 0.7.0 note: the establisher's per-call auth carries the dispatch-resolved identity (CF-005 corollary) — the witness proves the overlay; INVALID_INPUT is the wire code for a schema failure (distinct from channel:open_failed establishment failures).
• futures crate used for BoxFuture in DialFn (already a dep).

Summary

Producer half complete: dial-shape establisher (registry lookup → injected dial → Establishment::new(plan)), the substrate-agnostic pump handler (pump_bidi awaited inline, R-02), and register_tunnel_openable (spec + establisher + pump + dial injection + witness). 14 unit tests (params + codec) + 11 integration tests over the duplex harness pass. Verified: cargo test, clippy --all-targets -D warnings (native + wasm32), fmt --check, wasm32 check — all clean. The listen establisher variant lands with tunnels/producer-listen.