alktunnels/tasks/tunnels/crate-init.md at 3a447273a824258ed549af16dbb25398869bf4cb

Files

T

glm-5.3-flash 69498b79cc tasks: Phase 2 decomposition — 12-task dependency graph for v1

tasks/architecture/:
- oq-promotion-sync (planning): back-pointers from the phase-0 ledger
  + AGENTS.md to the promoted OQ tracker (the convergence checklist's
  final half)
- oq-tn-14-tracker: the Safe-Exit external-trigger tracker task for
  OQ-TN-14 (unix/stdio placement; [external-trigger, deferred-oq],
  risk trivial, level research per the two-halves rule)

tasks/tunnels/ (the implementation graph, 8 generations):
- crate-init: module skeleton per overview.md's module map
- params: TunnelParams + open-op spec (ADR-001 wire-stable surface)
- wire-codec: frame_datagram/DatagramReader + the 8 POC-pinned test
  families (ADR-003)
- producer-open-op: establisher (dial, plan flow R-01) + pump handler
  (pump_bidi inline R-02) + registration; POC-ported integration tests
- consumer-session: TunnelSession (open/adopt, data planes, teardown
  matrix — ADR-005); generalizes the reverse POC's ReverseTunnel
- producer-listen: the listen establisher + AcceptQueue contract
  (ADR-004 shape 2)
- local-socket-halves: the local feature (TCP/UDP/unix halves
  functions; truncation fail-loud per OQ-TN-13; unix ships per
  OQ-TN-14's lean-yes, stdio deferred)
- review-core-crates: review-injection point before the downstream
  tasks build on the high-risk producer/consumer shapes
- end-to-end-suite: 6 suites / >=20 tests consolidating both POC
  suites against the public API (the spec's executable form)
- review-impl: the phase-gate review (wire/API/conventions/docs sync;
  findings doc per the alkhttp/alkcall house pattern)

Graph verified with taskgraph: 12 tasks valid, no cycles, 8
generations; critical path = oq-promotion-sync -> crate-init ->
params -> wire-codec -> producer-open-op -> consumer-session ->
review-core-crates -> review-impl; risk concentrated in the two
session tasks (both POC-validated); parallel groups available at
generations 1 and 6

2026-09-07 19:07:20 +00:00

3.3 KiB

Raw Blame History

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

name

status

depends_on

scope

risk

impact

level

Description

Convert the alktunnels scaffold crate into the real module skeleton per docs/architecture/overview.md §Module Map. The crate already exists (Cargo.toml with alkcall 0.7.0, the wasm-clean tokio subset, licenses, lib.rs stub); this task adds the module structure the subsequent tasks fill in.

Module skeleton

// src/lib.rs
//! alktunnels — arbitrary bidirectional tunnels over alkcall channels.
//! (crate docs per overview.md §What — the two-paragraph shape)

pub mod error;
pub mod params;
pub mod wire;

pub mod producer;
pub mod consumer;

// Public API surface: re-exports filled in by subsequent tasks (convention 16).

src/error.rs — TunnelError (thiserror; convention 2) + the typed open-error surface re-exported from alkcall (ChannelOpenError, establishment_reason-shaped helper). Skeleton only; filled by tunnels/params and tunnels/consumer-session.
src/params.rs — TunnelParams {resource, substrate} + Substrate enum (tcp | udp | unix) + tunnel_open_spec() builder + TUNNEL_OPEN_SCOPE/OP_TUNNEL_OPEN/TUNNEL_ALPN constants. Skeleton with type definitions; the schema builder + tests land in tunnels/params.
src/wire.rs — the codec module doc (ADR-003 summary + bast.md pointer); skeleton for frame_datagram/DatagramReader/ DatagramCodecError, filled by tunnels/wire-codec.
src/producer.rs — module doc (producer.md summary); skeleton for tunnel_open_spec wiring, register_tunnel_openable, the establisher shape, the pump handler — filled by tunnels/producer-open-op + tunnels/producer-listen.
src/consumer.rs — module doc (consumer.md summary); skeleton for TunnelSession — filled by tunnels/consumer-session.

Keep in place / verify

Cargo.toml: alkcall 0.7.0 pin, the wasm-clean tokio subset, the empty [features] table (the local feature is added by tunnels/local-socket-halves).
bytes, serde, serde_json, thiserror, tracing, futures stay; drop async-trait IF the skeleton confirms no trait is needed (ADR-004 — it likely is not; note the decision in Summary if dropped).
The default crate stays wasm-clean: cargo check --target wasm32-unknown-unknown must pass at every task in this graph (convention 4; the structural guard).

Acceptance Criteria

src/lib.rs declares error, params, wire, producer, consumer with doc comments; public API re-exports listed (empty bodies fine)
Every skeleton module compiles (cargo check clean)
cargo clippy --all-targets -- -D warnings clean
cargo fmt --check clean
cargo check --target wasm32-unknown-unknown passes
No comments in code beyond doc comments (convention 1)

References

docs/architecture/overview.md (module map, feature gates)
docs/architecture/decisions/004-no-backend-trait.md (module placement)
AGENTS.md conventions 1/2/4/15/16

Notes

Agent fills during implementation.

Summary

Agent fills this on completion.

3.3 KiB Raw Blame History