---
id: tunnels/crate-init
name: Initialize the alktunnels module skeleton (params, wire, producer, consumer, error)
status: pending
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

- [ ] `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.