glm-5.3-flash
69498b79cc
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
91 lines
3.3 KiB
Markdown
91 lines
3.3 KiB
Markdown
---
|
|
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. |