---
id: tunnels/crate-init
name: Initialize the alktunnels module skeleton (params, wire, producer, consumer, error)
status: completed
depends_on: [architecture/oq-promotion-sync]
scope: narrow
risk: low
impact: project
level: implementation
tags: [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

```rust
// 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

- [x] `src/lib.rs` declares `error`, `params`, `wire`, `producer`,
      `consumer` with doc comments; public API re-exports listed (empty
      bodies fine)
- [x] Every skeleton module compiles (`cargo check` clean)
- [x] `cargo clippy --all-targets -- -D warnings` clean
- [x] `cargo fmt --check` clean
- [x] `cargo check --target wasm32-unknown-unknown` passes
- [x] 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.