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:
25
AGENTS.md
25
AGENTS.md
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
@@ -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.
|
||||
66
tasks/architecture/oq-tn-12-tracker.md
Normal file
66
tasks/architecture/oq-tn-12-tracker.md
Normal 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.
|
||||
Reference in New Issue
Block a user