docs: complete oq-promotion-sync — AGENTS.md current with Phase 1, add TN-12 tracker

- AGENTS.md architecture bullet: spec exists (present tense), OQ tracker
  authoritative; convention 16 de-hedged (shape pinned by ADR-004/005);
  alkcall version drift fixed (v0.4.x/v0.5.x -> v0.7.x per Cargo.toml);
  Phase 1-work bullet -> Phase 1 complete, Phase 2 in tasks/
- phase-0-findings.md: promotion note atop the Open Questions section
  pointing at docs/architecture/open-questions.md; convergence
  checklist's final item checked
- tasks: add architecture/oq-tn-12-tracker (external-trigger tracker for
  OQ-TN-12 deferred(scope), per sdd_process.md deferred-OQ two-halves
  rule); OQ-TN-12 Blocked-on text now references the tracker id
- tasks: oq-promotion-sync completed (scope grew: 3 folded stale
  AGENTS.md refs found during review + the TN-12 tracker)

Verified: taskgraph validate (13 tasks), grep sweep clean for stale
'not exist yet'/version-drift language, cargo test + cargo fmt --check
This commit is contained in:
2026-09-08 06:18:55 +00:00
parent 3a447273a8
commit 508fc6fc28
5 changed files with 141 additions and 19 deletions

View File

@@ -165,7 +165,7 @@ just spawned implementation agents.
`Identity`, `IdentityProvider`, `AccessControl`,
`OwnershipProvider`, `HandlerError`, `StreamError` come from
`alkcall::core`. Do not vendor copies into this crate. alkcall is
v0.5.x — breaking changes are expected at this major-zero stage;
v0.7.x — breaking changes are expected at this major-zero stage;
this is an early consumer, so we find and fix issues upstream
rather than working around them. Pin `alkcall = "0.7.0"` and bump
deliberately. The 0.6.0 establishment surface (ADR-049 + amendment
@@ -218,7 +218,7 @@ just spawned implementation agents.
16. **Module structure** — one module per file under `src/`, re-exported
from `src/lib.rs`. Public API surface is `lib.rs` re-exports. The
expected shape (to be finalized in the architecture docs): a
shape is pinned by the architecture spec (ADR-004, ADR-005): a
producer half (adapter / open-handler for `alk/tunnel`-family
ALPNs), a consumer half (a typed session/client that opens tunnel
channels), and shared wire/target-addressing modules. Backend
@@ -252,16 +252,19 @@ non-backend module changes.
## Architecture Context
- `docs/architecture/` — will hold the authoritative spec (Phase 1 of
the SDD process). It does not exist yet; Phase 0 research lives in
`docs/research/`. Read it before non-trivial changes once it exists.
- `docs/architecture/` — the authoritative spec (Phase 1 of the SDD
process, complete): overview/producer/consumer/wire spec docs, ADRs
001..006 (all Accepted), the wire-format BAST document, and
`open-questions.md` (the authoritative OQ tracker). Read it before
non-trivial changes. Phase 0 research remains in `docs/research/`
(its OQ ledger is superseded by the tracker).
- The prior art for this crate:
- **alknet-channels POC** —
`/workspace/@alkdev/alknet/docs/research/alknet-channels/poc-summary.md`
(§POC Target 3: tunnel handler). Validates the demux→Connection→
handler→mux path and the two-pump tunnel shape over a stand-in
transport. POC code at `/workspace/alknet-channels-poc/`.
- **alkcall** — `/workspace/@alkdev/alkcall` (v0.4.x, crates.io).
- **alkcall** — `/workspace/@alkdev/alkcall` (v0.7.x, crates.io).
The substrate: call protocol + channels multiplexing. The tunnel
crate consumes `alkcall::core` types and the channels
`ChannelCore`/`ChannelClient`/`register_openable` surface.
@@ -303,11 +306,11 @@ non-backend module changes.
is that spec
- What the POCs settled (Phase 0 complete — 2026-09-07): both POCs
ran clean (forward UDP POC + reverse-flow POC; see
`docs/research/poc-summary.md` and `reverse-poc-summary.md`). The
remaining Phase 1 work is the spec: OQ promotion, params JSON ADR,
ALPN ADR, codec ADR (UDP framing mandatory per F-2), and the
producer/consumer API surface (the consumer session type owns
teardown — reverse POC W3).
`docs/research/poc-summary.md` and `reverse-poc-summary.md`). Phase 1
is complete (2026-09-07): the OQ ledger is promoted, and the params,
ALPN, codec, and API-surface decisions are pinned by ADR-001..006
(including consumer-session teardown ownership — reverse POC W3).
Phase 2 (implementation) is decomposed in `tasks/`.
- If a TODO references a design direction that an ADR has since decided
against, the TODO is stale — remove it and align with the ADR. Do not
implement the rejected design.

View File

@@ -191,7 +191,8 @@ OQ-TN numbering. Format per `docs/sdd_process.md`.
the seed shape (consumer + `register_openable` on the same
connection) but does not exercise re-export; if one materializes,
decide whether a composition helper belongs in this crate or is
assembly-layer wiring of the existing surface.
assembly-layer wiring of the existing surface. Tracker task:
`architecture/oq-tn-12-tracker` (tasks/architecture/).
- **Cross-references**: OQ-TN-05, ADR-004, alkcall ADR-042 (relay)
### OQ-TN-13: UDP truncation semantics at the codec boundary

View File

@@ -290,6 +290,12 @@ referenced, tracked, and promoted into `docs/architecture/open-questions.md`
in Phase 1. Half-answers and hunches are marked as such — the point of this
document is to hold them without forcing premature decisions.
> **Promoted 2026-09-07 (Phase 1):** OQ-TN-01..10 now live in
> [`docs/architecture/open-questions.md`](../architecture/open-questions.md)
> as OQ-TN-01..14 (statuses current as of the Phase 1 spec; OQ-TN-11..14
> are the Phase 1 residues). The statuses below are the Phase 0 record and
> are not maintained; treat the architecture tracker as authoritative.
### OQ-TN-01: Target addressing format
What does the tunnel `params` on `channel/open` look like? alknet ADR-071
@@ -905,5 +911,7 @@ Candidate reading for the research specialist (to be expanded):
adapter); "produce halves for a resource" is a function. The
hub re-produce composition question is the only remaining
OQ-TN-05 thread
- [ ] Open questions promoted to Phase 1
`docs/architecture/open-questions.md` with statuses
- [x] Open questions promoted to Phase 1
`docs/architecture/open-questions.md` with statuses — DONE
2026-09-07 (OQ-TN-01..10 promoted as OQ-TN-01..14, including the
Phase 1 residues; the convergence checklist is complete)

View File

@@ -1,7 +1,7 @@
---
id: architecture/oq-promotion-sync
name: Sync AGENTS.md + phase-0 ledger pointers to the promoted OQ ledger (planning)
status: pending
status: completed
depends_on: []
scope: single
risk: trivial
@@ -25,7 +25,17 @@ The older ledgers still describe pre-Phase-1 states in two places:
"will hold the authoritative spec (Phase 1 of the SDD process)... It does not
exist yet". That is now stale: the spec exists (ADR-001..006 + 4 spec docs +
BAST + OQ tracker). Update the paragraph to point at the real directory and
adjust the "read it before non-trivial changes once it exists" line.
adjust the "read it before non-trivial changes once it exists" line. Three
adjacent stale references in the same file fold in (same staleness class,
one pass — found during task review 2026-09-08):
- Convention 16 (module structure): "expected shape (to be finalized in
the architecture docs)" — the docs now exist and pin the module shape;
state it as decided (producer half / consumer half / shared wire).
- Convention 11: "alkcall is v0.5.x" — Cargo.toml pins `0.7.0` and the
convention's own later text describes the 0.6.0/0.7.0 surfaces; the
version sentence is self-contradicting.
- Architecture Context alkcall bullet: "alkcall (v0.4.x, crates.io)" —
same version drift.
## Work
@@ -34,13 +44,20 @@ The older ledgers still describe pre-Phase-1 states in two places:
at `docs/architecture/open-questions.md`; mark the checklist item done.
- AGENTS.md: rewrite the `docs/architecture/` bullet to the present tense
(spec exists; read it before non-trivial changes; ADRs 001..006 are
Accepted; the OQ tracker is authoritative for open questions).
Accepted; the OQ tracker is authoritative for open questions). Also fix
the three folded stale references: convention 16's "to be finalized"
hedge, and the two alkcall version mentions (v0.5.x in convention 11,
v0.4.x in the Architecture Context bullet → 0.7.0).
## Verification
- [ ] phase-0-findings.md has the promotion pointer; the checklist's final
item is checked
- [ ] AGENTS.md architecture-context paragraph reflects the existing spec
- [ ] Convention 16 states the module shape as decided; no "to be finalized"
hedge remains
- [ ] No alkcall version drift in AGENTS.md (convention 11 + Architecture
Context bullet both say 0.7.0, matching Cargo.toml)
- [ ] No other stale "does not exist yet" language anywhere in AGENTS.md or
docs/
@@ -55,8 +72,35 @@ The older ledgers still describe pre-Phase-1 states in two places:
## Notes
> Agent fills during implementation.
- Executed together with `architecture/oq-tn-12-tracker` creation
(process-gap fix found during task review — OQ-TN-12's Blocked-on text
now references its tracker task id per `sdd_process.md` §Deferred OQs
and the blocker-task half).
- While rewriting the Architecture Context bullet, a fourth same-class
stale line surfaced and folded in: "The remaining Phase 1 work is the
spec" → Phase 1 complete, Phase 2 decomposed in `tasks/`.
- phase-0-findings.md: promotion note added at the top of the Open
Questions section (pointer to `docs/architecture/open-questions.md`,
Phase 0 statuses marked as non-maintained record); the convergence
checklist's final item checked with the promotion details.
- AGENTS.md: architecture bullet rewritten to present tense; convention
16 de-hedged (shape pinned by ADR-004/ADR-005); convention 11 v0.5.x →
v0.7.x; Architecture Context alkcall bullet v0.4.x → v0.7.x; Phase 1
work bullet updated to complete.
- Grep sweep for "does not exist / not exist yet / will hold the / once
it exists / to be finalized / v0.4.x / v0.5.x / remaining Phase 1
work is the spec" over AGENTS.md + docs/ is clean (only the task's own
description and phase-0-findings.md's unrelated "Sentinel collision
does not exist" line match).
## Summary
> Agent fills this on completion.
Phase-0 OQ ledger back-pointers landed
(`docs/research/phase-0-findings.md` promotion note + checked-out
convergence checklist) and AGENTS.md is current with the completed
Phase 1 spec (architecture bullet, convention 16, convention 11,
alkcall version mentions, Phase 1-work bullet). Scope grew from the
task's three folded stale references + the TN-12 tracker (added as
`architecture/oq-tn-12-tracker`, referenced from OQ-TN-12's Blocked-on
text). taskgraph validates 13 tasks; all verification checklist items
pass.

View File

@@ -0,0 +1,66 @@
---
id: architecture/oq-tn-12-tracker
name: "OQ-TN-12 follow-through: hub re-produce composition helper (deferred scope)"
status: pending
depends_on: []
scope: single
risk: trivial
impact: isolated
level: research
tags: [architecture, external-trigger, deferred-oq, hub, producer, consumer]
---
## Description
OQ-TN-12 is `deferred(scope)` (open-questions.md): the hub re-produce
composition helper — whether a crate that re-produces a tunnel resource it
consumes (a hub proxy: consumer + `register_openable` on the same
connection) needs a composition helper from this crate, or assembles from
the public producer/consumer surface as-is. ADR-004 resolved the substrate
inversion point to "no trait, halves functions"; the re-produce half has no
concrete consumer yet, so the decision is deferred until one exists.
This task is the machine-readable half of the deferral (per
`docs/sdd_process.md` §Deferred OQs and the blocker-task half): it tracks
whether the unblocking condition has arrived. It is not implementation
work and blocks nothing.
The unblocking condition: a concrete hub-proxy consumer — a crate that
re-produces a consumed tunnel resource (the reverse POC's hub is the seed
shape minus re-export: consumer + `register_openable` on the same
connection, without exercising re-export).
## Work
- Re-read OQ-TN-12 + ADR-004 at triage; confirm no hub-proxy consumer has
materialized (if one has, the OQ transitions deferred(scope) → open and
the composition-helper decision runs as its own task).
## Verification
- [ ] Tracked (this file existing and being reviewed at triage time IS
the tracking mechanism — no code or doc change is expected unless
the unblocking condition above arrives)
## Out of scope
- Deciding the composition-helper question itself (runs as a new
architecture task once the condition arrives)
- Building a hub proxy (the condition is a consumer existing, not us
building one)
## References
- docs/architecture/open-questions.md OQ-TN-12 (the deferral + Blocked-on
condition)
- docs/architecture/decisions/004-no-backend-trait.md (the no-trait
resolution this deferral rides on)
- docs/sdd_process.md §Deferred OQs and the blocker-task half
## Notes
> Agent fills during implementation.
## Summary
> Agent fills this on completion.