docs(architecture): review pass: flip specs to reviewed; fix review findings

- Define the fragment-rendering convention: render targets are registered templates composing partials; partials are composition units (core.md, emit.md posture B) - Define template kind; trim/restage inline rationale with ADR citations (core.md) - Amend ADR-008: wgsl set ownership resolved engine-owned via OQ-05's 2026-11-06 resolution - Add OQ-09: consolidate the untracked bast-rust-codecs detailed-spec residue (projection, error shape, writer survey) with paired tracker task - Fix oq-05 tracker name to match the corrected unblocking condition - Add reviewed-transition rule: deferred OQs with tracker tasks do not block reviewed; flip six spec docs draft -> reviewed Verification: taskgraph validate (8 tasks valid), em-dash grep zero hits, cargo doc --no-deps clean
2026-11-06 10:33:43 +00:00
1 parent 077e52c003
commit 9d57d1612e
@@ -1,5 +1,5 @@
 ---
-status: draft
+status: reviewed
 last_updated: 2026-11-06
 ---

@@ -39,11 +39,11 @@ may appear alongside them, and the mapping lives in `targets.md`.

 | Document | Scope | Status |
 |---|---|---|
-| [overview.md](overview.md) | Purpose, engine model, dependencies, constraints | draft |
-| [core.md](core.md) | Shared text-generation core: registry, contexts, rendering, errors | draft |
-| [emit.md](emit.md) | How rendered text is consumed: the three emit postures | draft |
-| [targets.md](targets.md) | Per-target template sets, context shapes, validity pinning | draft |
-| [open-questions.md](open-questions.md) | Centralized OQ tracker | draft |
+| [overview.md](overview.md) | Purpose, engine model, dependencies, constraints | reviewed |
+| [core.md](core.md) | Shared text-generation core: registry, contexts, rendering, errors | reviewed |
+| [emit.md](emit.md) | How rendered text is consumed: the three emit postures | reviewed |
+| [targets.md](targets.md) | Per-target template sets, context shapes, validity pinning | reviewed |
+| [open-questions.md](open-questions.md) | Centralized OQ tracker | reviewed |

 ## ADR Table

@@ -78,8 +78,11 @@ number; rationale and unresolved questions are not inlined.
 | `deprecated` | Superseded; kept for reference |

 Docs carry YAML frontmatter (`status`, `last_updated`). A doc moves to
-`reviewed` when its open questions are resolved and review passes.
-The centralized tracker is `open-questions.md`; deferred questions
-follow the two-half convention in `docs/sdd_process.md` (visible OQ
-entry here plus an external-trigger tracker task under
-`tasks/architecture/`).
+`reviewed` when no `open` open questions affect it and review passes:
+deferred questions (`deferred(scope)` / `deferred(unclear)`) paired
+with external-trigger tracker tasks under `tasks/architecture/` do not
+block `reviewed`, since their unblocking conditions are downstream
+activations, not spec gaps. The centralized tracker is
+`open-questions.md`; deferred questions follow the two-half convention
+in `docs/sdd_process.md` (visible OQ entry here plus an
+external-trigger tracker task).
@@ -1,5 +1,5 @@
 ---
-status: draft
+status: reviewed
 last_updated: 2026-11-06
 ---

@@ -41,9 +41,7 @@ deterministic (ADR-003).
  templates across sets; cross-set reuse is a source-level include,
  not registry surgery.
 - **Strict mode is always on** (ADR-002, AGENTS.md convention 6). A
-  missing context variable is a render error. The reader POC caught a
-  stale context key through strict mode at build time; silent gaps in
-  SSR would surface as blank page regions.
+  missing context variable is a render error, not silent empty output.
 - **Registration is data, not side effects.** Registering a template,
  partial, or helper is fallible (malformed templates produce a typed
  error) and happens at set-construction time. This applies to
@@ -60,13 +58,19 @@ deterministic (ADR-003).
  render tests asserting golden output (AGENTS.md convention 7).
  Changing a template is a source change.
 - **Naming**: lowercase kebab or snake; one name per template kind
-  (convention 9). Generated file naming conventions are per-emit
-  posture and live in emit.md.
+  (convention 9). A template kind is a named top-level artifact
+  category within a template set (a rendered unit: `reader`, `writer`,
+  `validator` for the codec set; `page`, `fragment` for SSR) and is
+  distinct from partials, which are composition units. Generated file
+  naming conventions are per-emit posture and live in emit.md.
 - **Partials are first-class.** Registration supports partials
-  alongside templates from day one (alkminer-v1 precedent). This is
-  the only branch-3 (template-JIT) requirement that reaches v1, and it
-  is also the natural SSR unit: header, footer, and nav fragments are
-  partials (ADR-006).
+  alongside templates from day one (alkminer-v1 precedent). Partials
+  are composition units, not primary render targets: anything a
+  consumer renders by name (a full page, a reusable fragment such as
+  header, footer, or nav) is registered as a template that may compose
+  partials via includes. This is the only branch-3 (template-JIT)
+  requirement that reaches v1, and it is also the natural SSR unit
+  (ADR-006).
 - **Consumers register their own assets.** The registry construction
  API accepts externally supplied template and partial text so that
  consumer-owned sets (alkforge pages) need no alkgen source access
@@ -76,7 +80,9 @@ deterministic (ADR-003).

 - **Contexts are typed Rust structs** (`serde::Serialize`, usually
  derived) built by Rust context builders (ADR-004). This is the
-  typebox-rs shape with its weaknesses removed. Free-form
+  typebox-rs shape with its weaknesses removed (typebox-rs: the older
+  handlebars codegen precedent at
+  `/workspace/@alkimiadev/typebox-rs/src/codegen`). Free-form
  `serde_json::Value` contexts are not the convention; where a
  document tree is passed through (schema fragments), it is passed as
  a value inside a typed context.
@@ -92,10 +98,10 @@ deterministic (ADR-003).
  context arrays in insertion order. Sort only where a template
  explicitly requires sorted output (convention 5).
 - **Plan semantics, document names** (branch-1 refined rule, carried
-  from the reader POC): semantic content (offsets, strides, dispatch
-  tables) comes from alktype plans; names, docs, and descriptive
-  metadata come from the source document, because plans eagerly
-  resolve `$ref`s and lose def names. Whether a branch-1-style
+  from the reader POC; ADR-004 decision 4, finding F-6): semantic
+  content (offsets, strides, dispatch tables) comes from alktype
+  plans; names, docs, and descriptive metadata come from the source
+  document. Whether a branch-1-style
  projection exists at all is a template-set property, and the core
  imposes nothing about it (ADR-001).
 - **Pure-cursor model for code contexts.** Where a codec context
@@ -120,6 +126,11 @@ deterministic (ADR-003).
  Same registry contents plus same context produces byte-identical
  text (ADR-003). Rendering performs no I/O, no time reads, no
  ordering that depends on hash maps leaking into output.
+- **Templates are the render targets.** The name argument resolves to
+  a registered template, never a bare partial: whatever a consumer
+  renders directly (a page or a fragment) must be registered as a
+  template; partials exist to be composed inside one (see Template
+  assets; ADR-006).
 - **Two sinks**: render into a String, or into an `io::Write` target
  (both wasm-clean; streaming a large page or a large generated file
  should not force intermediate allocation). Which is exposed first
@@ -19,10 +19,12 @@ which it is not (overview.md).
 1. **Engine-owned template sets ship in alkgen** (behind features per
   ADR-009): bast-rust-codecs now, call-handlers on its deferral path
   (OQ-04), and any future set whose ownership resolves to
-   engine-owned. The wgsl set's ownership (alkjs vs alkgen) is
-   explicitly open under OQ-05; this ADR decides only where
-   engine-owned sets live when they exist. Their assets, builders,
-   and golden tests are alkgen's, versioned and pinned like source.
+   engine-owned. The wgsl set's ownership resolved to engine-owned on
+   2026-11-06, when OQ-05's resolution applied this ADR's principle to
+   the third code target (engine-owned, feature-gated, consumed via
+   posture C); this amend note records that application. The assets,
+   builders, and golden tests of engine-owned sets are alkgen's,
+   versioned and pinned like source.
 2. **Consumer-owned template sets live in the consumer**: alkforge's
   page templates, partials, and helpers are alkforge assets
   registered into a core-built registry via the alkgen API. alkgen
@@ -1,5 +1,5 @@
 ---
-status: draft
+status: reviewed
 last_updated: 2026-11-06
 ---

@@ -35,9 +35,9 @@ Used by the BAST codec template set and its future siblings
  per-target decisions (OQ-01, OQ-02, OQ-03), not core or
  posture-A-wide policy (ADR-001); posture A fixes only the invariants
  above: banner, determinism, convention-conformant generated code,
-  and the wasm-clean rule that alkgen returns rendered text and no
-  filesystem writing happens inside the library (the consumer's build
-  script owns file placement).
+  and the no-filesystem-in-library rule that makes the core
+  wasm-clean (ADR-003, convention 4): rendering returns text and the
+  consumer's build script owns file placement.
 - **Output hygiene, because files get checked in** (AGENTS.md
  convention 8):
  - every artifact starts with the "Auto-generated by alkgen.
@@ -61,9 +61,11 @@ Used by SSR consumers, currently alkforge (ADR-006).
  render-per-request is alkforge's; determinism of rendering is what
  makes consumer-side caching safe to build (ADR-003).
 - **Output unit**: fragments and full pages. Partials make fragments
-  natural; pages compose fragments (ADR-006). The phase-0 fragment
-  exclusion (OQ-GN-01) was scoped to posture A and does not apply
-  here.
+  natural; pages compose fragments (ADR-006). Render targets are
+  registered templates composing partials (core.md); a fragment a
+  consumer serves directly is registered as its own template. The
+  phase-0 fragment exclusion (OQ-GN-01) was scoped to posture A and
+  does not apply here.
 - **Output hygiene**: rendered HTML is the product, not a checked-in
  generated artifact, so the DO-NOT-EDIT banner does not apply.
  Determinism still applies (caching, hashing, and alkforge's render
@@ -1,5 +1,5 @@
 ---
-status: draft
+status: reviewed
 last_updated: 2026-11-06
 ---

@@ -105,6 +105,35 @@ architect action, not a default.
  strategy cannot be a posture-A-wide or core rule.
 - **Cross-references**: targets.md bast-rust-codecs, ADR-007, OQ-04

+## Theme: bast-rust-codecs detail
+
+### OQ-09: plan-to-context projection, generated-error shape, writer survey
+
+- **Origin**: targets.md (bast-rust-codecs remaining phase-1 residue,
+  consolidated from inline items 2026-11-06)
+- **Status**: deferred(scope)
+- **Door type**: two-way
+- **Priority**: medium
+- **Impacts**: blocks only the branch-1 detailed spec when its target
+  activates: the exact plan-to-context projection (which alktype plan
+  structures become which context shapes), the concrete shape of the
+  generated code's error type (ADR-007 fixes the constraints:
+  error-returning end to end, zero dependencies; the concrete
+  per-arm error taxonomy is the residue), and the writer-side plan
+  survey. Nothing in v1, since bast-rust-codecs activation is queued
+  behind ssr-html and wgsl-jit (2026-11-06 consumer steer).
+- **Blocked on**: bast-rust-codecs activation (branch-1 detailed spec
+  being written), which needs the alkcall channels consumer's
+  integration story; same trigger as OQ-01 (tracker task
+  `architecture/oq-09-bast-codec-spec-residue`).
+- **Resolution**: Not yet decidable, per ADR-001 (emit and
+  projection policy is per-target, not core policy); the content is
+  consumer-readable only from the branch-1 detailed spec session,
+  with the reader POC's parity findings (F-1, F-2, F-6) as the
+  recorded analysis inputs.
+- **Cross-references**: targets.md bast-rust-codecs, ADR-001, ADR-004,
+  ADR-007, OQ-01, OQ-03
+
 ## Theme: Future targets

 ### OQ-04: call-handlers template set scope
@@ -1,5 +1,5 @@
 ---
-status: draft
+status: reviewed
 last_updated: 2026-11-06
 ---

@@ -1,5 +1,5 @@
 ---
-status: draft
+status: reviewed
 last_updated: 2026-11-06
 ---

@@ -90,12 +90,13 @@ code, typed output at 291 to 322 ns versus the interpreter's 5.4 us
  field-disc unions, offset-indirect, big-endian, maxLength
  reservations, writers; reader POC follow-ups 3 and 4; phase-0
  OQ-GN-05 POC coverage).
- **Remaining phase-1 residue, not yet specced**: the exact
+- **Remaining phase-1 residue, not yet specced, tracked**: the exact
  plan-to-context projection (which plan structures become which
-  context shapes), generated-code error type shape, writer-side plan
-  survey, and full-validation strategy (OQ-03). These are the branch's
-  detailed spec, to be written when this target activates; the
-  decisions above are the constraints it cannot violate.
+  context shapes), the generated-code error type shape, and the
+  writer-side plan survey (OQ-09), plus the full-validation strategy
+  (OQ-03). These are the branch's detailed spec, to be written when
+  this target activates; the decisions above are the constraints it
+  cannot violate.

 ## call-handlers

@@ -152,3 +153,4 @@ Key questions affecting this document:
 - **OQ-07**: generic HTML layout primitives in alkgen
  (deferred(scope))
 - **OQ-08**: target-language scope for v1 template sets (resolved)
+- **OQ-09**: bast-rust-codecs detailed-spec residue (deferred(scope))
@@ -1,6 +1,6 @@
 ---
 id: architecture/oq-05-wgsl-requirements
-name: "External trigger: alkjs crate spec arrives"
+name: "External trigger: alkjs GPU-layer work names its shader codegen requirements"
 status: pending
 depends_on: []
 scope: single
@@ -13,15 +13,21 @@ level: research

 [external-trigger, deferred-oq] Tracker for OQ-05 (wgsl template set
 requirements, `deferred(scope)` in `docs/architecture/open-questions.md`).
-This task is not actionable work. Mark `completed` when the alkjs
-crate spec exists and names the shaders to generate and its wgpu
-pipeline shape; then re-open OQ-05 (or resolve directly).
+This task is not actionable work. Template-set ownership is already
+decided (ADR-008: engine-owned, ships in alkgen, feature-gated per
+ADR-009, consumed via posture C); only the shader inventory, context
+shape, and feature name wait. Mark `completed` when alkjs's GPU-layer
+work is underway and names the shaders, parameters, and compile-cache
+shape it needs; then re-open OQ-05 (or resolve directly). The
+sequencing runs alkgen v1 before alkjs (alkjs's GPU end builds on the
+core), so this is not a blocker on the core.

 ## Acceptance Criteria

- [ ] alkjs crate spec exists
- [ ] Shader set and pipeline shape named (the codegen requirements
-      can be read from the spec)
+- [ ] alkjs GPU-layer work is underway (builds on the alkgen core, so
+      this follows alkgen v1, not the reverse)
+- [ ] Shader set, parameters, and pipeline shape named (the codegen
+      requirements can be read from the work)
 - [ ] OQ-05 transitioned out of `deferred(scope)`

 ## References
@@ -0,0 +1,49 @@
+---
+id: architecture/oq-09-bast-codec-spec-residue
+name: "External trigger: bast-rust-codecs activates"
+status: pending
+depends_on: []
+scope: single
+risk: trivial
+impact: isolated
+level: research
+---
+
+## Description
+
+[external-trigger, deferred-oq] Tracker for OQ-09 (bast-rust-codecs
+detailed-spec residue: plan-to-context projection, generated-code
+error type shape, writer-side plan survey, `deferred(scope)` in
+`docs/architecture/open-questions.md`). This task is not actionable
+work; it exists so the task graph can represent the unblocking
+condition. Its trigger is the same activation event as OQ-01's
+(`architecture/oq-01-file-partitioning`). Mark `completed` when
+bast-rust-codecs activates and its branch-1 detailed spec session
+produces the three residue answers; then re-open OQ-09 (or resolve it
+directly in the detailed spec).
+
+## Acceptance Criteria
+
+- [ ] bast-rust-codecs activation is underway (ssr-html and wgsl-jit
+      consumers ahead of it per the 2026-11-06 steer)
+- [ ] The branch-1 detailed spec names the plan-to-context projection,
+      the generated-code error type shape, and the writer-side plan
+      survey result
+- [ ] OQ-09 transitioned out of `deferred(scope)`
+
+## References
+
+- docs/architecture/open-questions.md (OQ-09)
+- docs/architecture/targets.md (bast-rust-codecs)
+- docs/research/reader-poc-summary.md (findings F-1, F-2, F-6)
+- docs/architecture/decisions/007-bast-codec-output-contract.md
+- tasks/architecture/oq-01-file-partitioning.md (same trigger)
+- docs/sdd_process.md, "Deferred OQs and the blocker-task half"
+
+## Notes
+
+> Agent fills this during implementation.
+
+## Summary
+
+> Agent fills this on completion.