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
7.3 KiB
status, last_updated
| status | last_updated |
|---|---|
| reviewed | 2026-11-06 |
alkgen Architecture: Targets
What a target is
A target is a concrete instantiation of the engine (ADR-001): a template set (templates, partials, helper registrations, escaper choice), a context shape, an emit posture, and a validity-pinning strategy. The core knows nothing about targets; this document is the registry of instances and the place each target's remaining decisions are named.
Branch numbering follows phase-0 conventions (branch 0 = SSR addition from the 2026-11-06 unpause; 1, 2, 3 historical). The table gives the mapping; everything else in this doc uses names.
| Branch | Target | Status |
|---|---|---|
| 0 | ssr-html | active, first consumer |
| 1 | bast-rust-codecs | POC-validated; template set not yet in-crate |
| 2 | call-handlers | deferred(scope) |
| 3 | wgsl-jit | deferred(scope) |
Activation order follows the 2026-11-06 consumer steer: ssr-html first (alkforge SSR), then wgsl-jit (alkjs WGSL generation, OQ-05), with bast-rust-codecs and call-handlers queued behind them as lower-volume codegen asks. Branch numbers above are retained for traceability with the phase-0 records; they are not the ordering.
Target summary
| Target | Template set owner | Escaper (ADR-005) | Context shape | Emit posture | Feature (ADR-009) |
|---|---|---|---|---|---|
| ssr-html | consumer (alkforge) | HTML | page/data views | B (in-process render) | none (core) |
| bast-rust-codecs | alkgen | none (no-op) | plan projection + document names | A (build-time emit) | bast-codegen |
| call-handlers | alkgen | none (no-op) | deferred (OQ-04) | A | bast-codegen or own |
| wgsl-jit | alkgen | none (no-op) | shader contexts | C (render-to-compile) | OQ-05 |
ssr-html
alkforge's server-side web view. The engine's first consumer and the generality test: if this target needs no core exceptions, the core is not overfitted to codegen (ADR-001, ADR-006).
- Posture: alkforge links alkgen; pages render in-process, on demand or cached by alkforge (ADR-006).
- Contexts: page/data views defined by alkforge; no layout math, no plan projection. The simplest context shape of the three, which is the point.
- Escaper: handlebars' HTML escaping as the registry default (ADR-005).
- Validity pinning: alkforge pins page and fragment renders with golden tests in alkforge; rendered HTML is served, not checked in as generated code, so no banner (emit.md posture B).
- Ownership: all page templates, partials, and helpers live in alkforge and register through the core API (ADR-008). Whether alkgen should ever ship generic HTML layout primitives is OQ-07.
- Remaining decisions: minimal; this target is where decomposition into implementation tasks starts when alkforge's web view design names its pages.
bast-rust-codecs
Binary reader/writer/validator modules generated from alktype BAST documents for alkcall channels consumers. The branch the reader POC validated end-to-end: plan-driven contexts, parity-exact generated code, typed output at 291 to 322 ns versus the interpreter's 5.4 us (re-validated 2026-11-06 on alktype 0.4.0).
- Posture: build-time emit into the consumer's source tree (emit.md posture A); build-script integration (ADR-010).
- Contexts: plan-driven projection (ADR-004). The plan is the
semantic source (offsets, strides, dispatch tables); the source
document is the name source, since plans eagerly resolve
$refs and drop def names (phase-0 OQ-GN-02 refined by reader POC finding F-6). - Output contract: typed direct codecs over plain structs, zero dependencies in generated code, self-contained (no alktype runtime calls), pure cursor addressing, error-returning end to end (ADR-007; reader POC findings F-1, F-2, F-6; phase-0 OQ-GN-05/06 resolutions).
- Escaper: no-op; generated Rust must not be HTML-escaped (ADR-005).
- Validity pinning: parity discipline against the alktype interpreter plus compilation of the generated modules; template inventory enumerates the full kind arm surface (records, 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, tracked: the exact plan-to-context projection (which plan structures become which 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
The static counterpart of alkhttp's from_openapi /
from_jsonschema adapters: generated handler tables and types from
schema documents (BAST or JSON Schema/OpenAPI inputs).
Status: deferred(scope). The consumer asks that would pin its shape (the specific protocol surfaces to generate against) have not arrived; branch 1 converges first. See OQ-04. No template set, context shape, or feature decision is made here beyond the constraint that the core must not assume it (ADR-001).
wgsl-jit
WGSL generation for alkjs, the quickjs-based wgpu runtime, feeding a render-then-compile cache: the alkminer-v1 ShaderBuilder shape.
Status: engine-owned template set shipping in alkgen (ADR-008 applied to a third code target), feature-gated (ADR-009), consumed through posture C. Second in the activation queue per the 2026-11-06 consumer steer, after ssr-html. The deferred half (OQ-05) is only the consumer-readable content: shader inventory, context shape, feature name, all read from alkjs's GPU-layer work when it starts. alkjs's GPU end builds on the alkgen core rather than preceding it, so the core is not waiting on any of this. See OQ-05 and OQ-06.
Design Decisions
All design decisions are documented as ADRs in decisions/.
| ADR | Decision | Summary |
|---|---|---|
| 001 | One core, targets as template sets | The instantiation model |
| 005 | Escaper per registry | HTML for ssr-html; no-op for code sets |
| 006 | In-process SSR library | ssr-html posture |
| 007 | Typed direct codecs, zero-dep output | bast-rust-codecs output contract |
| 008 | Template set ownership | alkforge owns its page templates; codec set ships in-crate |
| 009 | Feature-gated template sets | alktype and engine-owned sets behind features |
Open Questions
Open questions are tracked in open-questions.md. Key questions affecting this document:
- OQ-01: posture-A file partitioning policy (deferred(scope), per-target)
- OQ-03: full BAST validation strategy for generated validators (deferred(scope), per-target)
- OQ-04: call-handlers scope (deferred(scope))
- OQ-05: wgsl template set requirements (deferred(scope))
- OQ-06: template-JIT core requirements (deferred(scope))
- 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))