alktunnels/tasks/tunnels/review-impl.md at 60c625899a5d8c4304f8b48f756fa14aff65b568

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

Review the v1 implementation against the architecture spec before any publish consideration. This is the phase-gate review (the SDD process's review-injection point at the end of the critical path): the wire surface (ADR-001/002/003) is a one-way door, and the API surface (ADR-005/006) becomes ABI-stable once a consumer exists.

Review checklist

Wire conformance (wire.md + ADR-001/002/003):
- params shape exact ({resource, substrate}, deny_unknown_fields, schema enum without unix until OQ-TN-14)
- op id channels/tunnel/sub, ALPN marker alk/tunnel, scope tunnel:open
- codec: [len: u16 BE], len=0 = legal empty datagram, Oversize at frame time, no sentinel in the codec
- typed errors: the five establishment reasons + FORBIDDEN + channel:too_many_channels surfaces
Producer conformance (producer.md):
- establisher = the awaited bounded phase; plan flow (R-01) — no side-channel handoff anywhere (grep for Mutex<HashMap> + poll-loop take patterns — the POC's dead shape)
- pump handler: pump_bidi inline, no substrate types, JoinHandle tracks the data plane (R-02)
- registration: post-hoc supported (W2); ChannelOperations:: register_on guidance correct
- listen variant: same op, no new wire surface, typed error mapping
Consumer conformance (consumer.md + ADR-005):
- TunnelSession: open/adopt/stream_halves/take_halves/ send_datagram/recv_datagram/pump_against/close/join/Drop
- teardown matrix sound (no leaks; pump-less join (0, 0, reaped))
- no Clone
Conventions sweep (AGENTS.md):
- no comments in code (doc comments fine); no unwrap/expect outside tests; thiserror everywhere; poisoned-lock unwrap_or_else(into_inner)
- substrate types confined to src/local/ (grep-verify: no tokio::net outside the feature gate + tests)
- wasm-clean default crate (the structural guard passed at every step, but re-verify)
- pump_bidi consumed, never hand-rolled (grep for hand-rolled two-pump loops)
Docs ↔ implementation sync: lib.rs doc comments match overview.md's module map; public API = lib.rs re-exports (convention 16); ADR statuses updated from Draft → Accepted where the implementation confirms them (or findings filed back to the OQ tracker).

Deliverables

Findings as a review doc (docs/reviews/001-implementation-review.md, the alkhttp/alkcall house pattern) with severity levels + concrete remediation tasks. Criticals block the phase; majors get remediation tasks; minors get a follow-up batch.

Acceptance Criteria

Review doc filed with severity-graded findings
Remediation tasks created for anything above trivial
The 5 checklist sections each covered with a verdict

References

docs/architecture/ (the full spec set)
House pattern: /workspace/@alkdev/alkcall/docs/reviews/ (the review numbering + severity legend)

Notes

Agent fills during implementation.

Summary

Agent fills this on completion.

3.3 KiB Raw Blame History