glm-5.3-flash
9d57d1612e
- 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
status, last_updated
| status | last_updated |
|---|---|
| reviewed | 2026-11-06 |
alkgen Architecture
This directory is the authoritative architecture specification for the
alkgen crate. It was created at the start of Phase 1 (2026-11-06) from
the Phase 0 findings in docs/research/phase-0.md and
docs/research/reader-poc-summary.md.
Current State
Phase 1 (architecture) has started; Phase 0 is complete. The project
was paused 2026-09-08 after the reader POC and unpaused 2026-11-06
because alkforge (family ADR-002) needs server-side HTML generation,
which alkgen provides. alkforge's SSR research evaluated a
handlebars-based rendering approach against a Preact-based one and
selected handlebars on safety, speed, and resource grounds; handlebars
is the recorded substrate for that reason (ADR-002, ADR-006). No
implementation exists on main yet; src/ holds the validated
dependency skeleton only.
The crate is a text-generation engine: typed contexts plus
templates plus partials produce text. Targets (HTML SSR, Rust codecs,
WGSL) are template sets plus emit layers over one shared core. The
generalization is enforced by the consumers themselves, not asserted:
HTML is handlebars' native case, Rust codecs were validated end-to-end
by the reader POC, and WGSL is proven by alkminer-v1's ShaderBuilder.
Branch numbering below follows Phase 0 conventions: branch 0 is the
SSR addition from the unpause; branches 1, 2, 3 retain their historical
meanings. Target names (ssr-html, bast-rust-codecs, call-handlers,
wgsl-jit) are preferred in these documents; historical branch numbers
may appear alongside them, and the mapping lives in targets.md.
Architecture Documents
| Document | Scope | Status |
|---|---|---|
| overview.md | Purpose, engine model, dependencies, constraints | reviewed |
| core.md | Shared text-generation core: registry, contexts, rendering, errors | reviewed |
| emit.md | How rendered text is consumed: the three emit postures | reviewed |
| targets.md | Per-target template sets, context shapes, validity pinning | reviewed |
| open-questions.md | Centralized OQ tracker | reviewed |
ADR Table
ADRs live in decisions/.
| ADR | Title | Status |
|---|---|---|
| 001 | One text-generation core; targets are template sets plus emit layers | Accepted |
| 002 | handlebars-rust 6.4 substrate: strict mode, typed errors, embedded templates | Accepted |
| 003 | Core posture: synchronous, wasm-clean, deterministic | Accepted |
| 004 | Contexts are typed Rust structs built by context builders; kind mapping in Rust | Accepted |
| 005 | Escape strategy is a per-registry policy | Accepted |
| 006 | SSR: alkgen is an in-process rendering library for alkforge | Accepted |
| 007 | BAST codec template set: typed direct codecs, zero-dependency output | Accepted |
| 008 | Engine-owned template sets ship in alkgen; consumer page templates live in the consumer | Accepted |
| 009 | Template sets are feature-gated; default features ship the core only | Accepted |
| 010 | alkgen is library-only; build-script integration is a documented pattern, no CLI | Accepted |
Open Questions
All open questions are tracked in open-questions.md with stable OQ-IDs. Spec documents reference OQs by number and ADRs by number; rationale and unresolved questions are not inlined.
Document Lifecycle
| Status | Meaning |
|---|---|
draft |
Under active development; may change significantly |
reviewed |
Architecture final; implementation may begin; changes require review |
stable |
Implementation complete and verified; changes warrant an ADR |
deprecated |
Superseded; kept for reference |
Docs carry YAML frontmatter (status, last_updated). A doc moves to
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).