From 9d57d1612ea637477d38c93fd68f03b6cc4e013e Mon Sep 17 00:00:00 2001 From: "glm-5.3-flash" Date: Fri, 6 Nov 2026 10:33:43 +0000 Subject: [PATCH] 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 --- docs/architecture/README.md | 25 +++++----- docs/architecture/core.md | 41 ++++++++++------ .../decisions/008-template-set-ownership.md | 10 ++-- docs/architecture/emit.md | 16 +++--- docs/architecture/open-questions.md | 31 +++++++++++- docs/architecture/overview.md | 2 +- docs/architecture/targets.md | 14 +++--- tasks/architecture/oq-05-wgsl-requirements.md | 20 +++++--- .../oq-09-bast-codec-spec-residue.md | 49 +++++++++++++++++++ 9 files changed, 156 insertions(+), 52 deletions(-) create mode 100644 tasks/architecture/oq-09-bast-codec-spec-residue.md diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 845df8a..766013e 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -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). diff --git a/docs/architecture/core.md b/docs/architecture/core.md index ad509d4..8bce60c 100644 --- a/docs/architecture/core.md +++ b/docs/architecture/core.md @@ -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 diff --git a/docs/architecture/decisions/008-template-set-ownership.md b/docs/architecture/decisions/008-template-set-ownership.md index fdc747d..a8a22d3 100644 --- a/docs/architecture/decisions/008-template-set-ownership.md +++ b/docs/architecture/decisions/008-template-set-ownership.md @@ -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 diff --git a/docs/architecture/emit.md b/docs/architecture/emit.md index 3bfe4b3..b1bf2ea 100644 --- a/docs/architecture/emit.md +++ b/docs/architecture/emit.md @@ -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 diff --git a/docs/architecture/open-questions.md b/docs/architecture/open-questions.md index b53d270..d841672 100644 --- a/docs/architecture/open-questions.md +++ b/docs/architecture/open-questions.md @@ -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 diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 2ba728e..65952e0 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -1,5 +1,5 @@ --- -status: draft +status: reviewed last_updated: 2026-11-06 --- diff --git a/docs/architecture/targets.md b/docs/architecture/targets.md index 5557c4b..88e8e47 100644 --- a/docs/architecture/targets.md +++ b/docs/architecture/targets.md @@ -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)) diff --git a/tasks/architecture/oq-05-wgsl-requirements.md b/tasks/architecture/oq-05-wgsl-requirements.md index a5e0883..657ccad 100644 --- a/tasks/architecture/oq-05-wgsl-requirements.md +++ b/tasks/architecture/oq-05-wgsl-requirements.md @@ -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 diff --git a/tasks/architecture/oq-09-bast-codec-spec-residue.md b/tasks/architecture/oq-09-bast-codec-spec-residue.md new file mode 100644 index 0000000..0cef239 --- /dev/null +++ b/tasks/architecture/oq-09-bast-codec-spec-residue.md @@ -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.