alkdev/alkgen

0 Fork 0

Files

T

glm-5.3-flash 9d57d1612e 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

2.8 KiB

Raw Permalink Blame History

ADR-008: Template set ownership: engine-owned sets ship in alkgen; consumer page templates live in the consumer

Status

Accepted

Context

A target is a template set, but who owns the assets? The codegen branches made this obvious: the BAST codec templates are alkgen's intellectual content (they encode the plan-to-code translation), and consumers should not copy them. The SSR branch made it non-obvious: alkforge's page templates are application UI. If alkgen ever became a home for application layouts, it would drift into a web framework, which it is not (overview.md).

Decision

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 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.
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 ships no application HTML assets in v1; whether generic layout primitives ever join the engine is deliberately unresolved (OQ-07) and starts empty.
The registration API is the same machinery for both: consumer assets register through the same typed, strict, policy-bearing construction path as engine sets (no second-class registry; ADR-002).

Consequences

Positive: clear supply chain and pinning story (consumers upgrade engine sets by dependency version; their own templates by git); clear review boundaries (template edits touching parity-pinned output are gated by the codegen templates' golden tests).
Positive: alkgen does not accrete an application-layer UI vocabulary.
Negative: alkforge re-inventing layout structure that another consumer might also want is possible; that is what OQ-07 tracks, and the remedy path (file the ask upstream; ADR if shared assets become real) is pre-decided.
Negative: the registration API must be ergonomic enough that owning templates externally is pleasant; a bad API here would push consumers toward requesting in-crate placement for convenience. The API shape is an implementation-time concern constrained by this ADR's machinery-equality rule.

References

targets.md (owner column of the target summary)
core.md (registration machinery)
ADR-006 (SSR consumer posture), ADR-009 (feature gating)

2.8 KiB Raw Permalink Blame History