alktunnels/tasks/tunnels/crate-init.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
tunnels/crate-init	Initialize the alktunnels module skeleton (params, wire, producer, consumer, error)	completed	architecture/oq-promotion-sync	narrow	low	project	implementation	scaffold crate-init

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

• All five skeleton modules created per the task's shapes, with module docs pointing at the spec docs + ADRs and tunnels/* tasks that fill them in.
• Constants placed early (OP_TUNNEL_OPEN, TUNNEL_ALPN, TUNNEL_OPEN_SCOPE in params.rs — they are part of the wire surface, not producer-only, so they live in the shared module per the module map's "params.rs … + open-op input schema").
• establishment_reason is a thin delegation to ChannelOpenError::establishment_reason (alkcall 0.7.0 has the method upstream); the crate-level helper keeps the POC's free-fn shape for consumers and re-exports the typed error.
• MAX_DATAGRAM_LEN (65535) placed in wire.rs — the one codec constant ADR-003 pins regardless of the codec functions landing later.
• async-trait dropped per the task's IF: the skeleton confirms no trait is needed (ADR-004 — halves functions, not traits); cargo check passes without it.

Summary

Module skeleton landed (error/params/wire/producer/consumer + lib.rs docs + re-exports); Cargo.toml unchanged except async-trait dropped (ADR-004 confirmation). Verified: cargo check, cargo clippy --all-targets -- -D warnings, cargo fmt --check, cargo test, cargo check --target wasm32-unknown-unknown, cargo clippy --target wasm32-unknown-unknown -- -D warnings — all clean.