alktunnels/tasks/tunnels/review-002-doc-sync.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
tunnels/review-002-doc-sync	D-1 + D-2 — sync wire.md's schema bounds + ADR-007's oneOf→if/then + the establisher-time→registry-gate sentence	completed		narrow	low	project	implementation	docs wire-format adr-007 review-002 review-remediation

Description

Two doc-only review 002 findings (docs/reviews/002-graduation-implementation-review.md §D-1, §D-2) batched: the shipped code is the wire-stable side and is correct; the docs lag it. Wire-contract-adjacent — do this before the first consumer (alksocks) ships.

D-1 — wire.md omits the port bounds the shipped schema enforces

The shipped direct-op and forwarded-op schemas pin "port": {"minimum": 0, "maximum": 65535} plus "additionalProperties": false on the target/peer objects (src/params.rs:208-222, 453-467), and listen with "minimum": 1 (src/params.rs:442). wire.md (the normative WHAT) says only port: <u16> and "integer > 0" in prose — it does not record the bounds as schema properties, nor the additionalProperties: false gate that makes cross-shape targets fail the registry's INVALID_INPUT class BEFORE the establisher (the behavior malformed_target_is_schema_class_and_leaves_no_channel pins on the wire). The BAST doc (bast.md) covers only the data-plane codec, not the params schemas — no second source records these bounds.

Fix: record the exact schema constraints in wire.md's §The Direct Op and §The Forwarded Op (the port bounds, additionalProperties: false per branch, the listen minimum: 1, and the gate-ordering sentence). The risk addressed: a future consumer implementing from wire.md alone accepting a shape the reference producer rejects (or vice versa).

D-2 — ADR-007's oneOf wording is stale; the "validated at establisher time" sentence contradicts the shipped design

1. ADR-007 §2 (line ~82) says "the target sub-schema is per-substrate (oneOf on the sibling substrate value, validated at establisher time — see Consequences)". The shipped schema (and wire.md §The Forwarded Op, and the unit tests pinning it) use allOf of two if/then branches instead. oneOf of full-target-schemas would actually be WRONG here (a unix-substrate open would need to fail the tcp branch — plain oneOf on sibling-conditioned subschemas is awkward; if/then composes correctly with the base properties/required). The code is right; the ADR's one-word schema-structure reference is stale.
2. The same line's "validated at establisher time" contradicts the shipped design and wire.md's own text: the test (malformed_target_is_schema_class_and_leaves_no_channel) proves the REGISTRY gate fires first (the establisher's dial never runs). The ADR/wire.md sentence should read "validated registry-side (the schema gate), before the establisher; re-checked by serde at establisher time as the backstop" — which is exactly what src/params.rs's doc comments already say.

Fix: a one-line ADR-007 erratum (or an amendment note — house style has precedent: ADR-008 carries numbered amendments) replacing oneOf with the shipped allOf-of-if/then structure, plus the corrected gate-ordering sentence; mirror the same gate-ordering correction in wire.md §The Direct Op's "validated at establisher time" sentence if it says the same thing (verify both files while in there). No code changes.

Acceptance Criteria

• wire.md records the shipped schema bounds (port min/max, additionalProperties: false, listen minimum: 1) in both op sections
• ADR-007 §2 corrected: oneOf → the shipped allOf/ if/then structure (erratum or amendment, house style)
• The "validated at establisher time" sentence corrected to "registry-side schema gate first; serde backstop at establisher time" in ADR-007 (and wire.md if it repeats it)
• cargo doc --no-deps clean (docs changed — the verification battery's doc gate)

References

• docs/reviews/002-graduation-implementation-review.md §D-1, §D-2
• docs/architecture/wire.md (§The Direct Op, §The Forwarded Op)
• docs/architecture/decisions/007-direct-open-op.md (§2, line ~82)
• src/params.rs:208-222, 442, 453-467 (the shipped schemas the docs must match)

Notes

Agent fills during implementation.

Implementation Notes (2026-09-20)

• D-1 (wire.md §The Direct Op + §The Forwarded Op): both sections now record the exact shipped schema constraints — the per-branch target/peer objects (type: object, additionalProperties: false, port bounds minimum: 0/maximum: 65535, the unix path branch) and the forwarded listen minimum: 1 + its serde-pin backstop — with the gate-ordering sentence (registry-side schema gate before the establisher, serde backstop) and the cross-shape-INVALID_INPUT behavior the integration test pins. No second source existed for these bounds (bast.md covers only the data-plane codec); wire.md now is the complete record.
• D-2 (ADR-007 §2): the stale sentence corrected in place (oneOf → the shipped allOf of two if/then branches; "validated at establisher time" → registry-side gate + serde backstop), plus a dated Erratum section documenting why oneOf would actually be wrong (exactly-one-branch-matches does not compose with the base properties/required) and citing the pinning test. wire.md §The Direct Op's mirrored sentence corrected in the same edit. ADR-008 was checked and needs no change (it never stated the oneOf/establisher-time claim).
• Verification: cargo doc --no-deps clean (0 warnings); cargo fmt --check clean.