glm-5.3-flash
a91ea2ec89
- overview.md, core.md, emit.md, targets.md: modular spec set for the generalized engine (contexts + templates + partials -> text), with the three targets (ssr-html, bast-rust-codecs, call-handlers, wgsl-jit) as template sets plus emit postures - ADRs 001-010: one core/template-set split, handlebars 6.4 strict substrate, sync/wasm/deterministic posture, typed contexts with builders, per-registry escaper, SSR library posture, typed direct codecs output contract, template-set ownership, feature gating, library-only v1 - open-questions.md: OQ-01..OQ-08 centralized tracker carrying phase-0 residue (GN-01/02/07/09) with three deferred(scope) entries plus a resolved disposition for phase-0 OQ-GN-04 - tasks/architecture/: external-trigger tracker tasks paired with the deferred OQs (taskgraph validate passes) - phase-0.md checklist dispositioned for OQ-GN-04; AGENTS.md lifecycle updated to phase 1 Verification: taskgraph validate (4 tasks OK), cargo fmt --check, cargo test, em-dash grep clean; architecture-reviewer pass returned zero critical issues
status, last_updated
| status | last_updated |
|---|---|
| draft | 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. 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 | draft |
| core.md | Shared text-generation core: registry, contexts, rendering, errors | draft |
| emit.md | How rendered text is consumed: the three emit postures | draft |
| targets.md | Per-target template sets, context shapes, validity pinning | draft |
| open-questions.md | Centralized OQ tracker | draft |
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 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/).