alkgen/docs/research/phase-0.md

status, last_updated

status	last_updated
draft	2026-11-06

alkgen: Phase 0 Research Findings

This document captures Phase 0 (Exploration) findings and open design questions for the alkgen crate. The objective of Phase 0 per docs/sdd_process.md is: "Capture vision and guiding principles; research options; validate approaches; converge on a recommended approach." It is the input to Phase 1 (Architecture).

Drafted 2026-09-08 from the initial setup discussion and a survey of the relevant references (below). Updated 2026-11-06 at the unpause (see §"The 2026-11-06 unpause (alkforge SSR)"). The crate is the codegen engine of the alk* stack: a dev tool generating static files into downstream projects from schema documents, i.e. handlebars-rust templates rendered over alktype BAST documents (branch 1) or jsonschema/openapi documents (branch 2), producing code artifacts. Plus, since the unpause, plain HTML generation for alkforge's server-side rendering (branch 0). Four branches; the branch numbering below keeps the original order (branch 0 = the unpause addition, then branches 1-3 in their historical order), so every "branch 1" / "branch 2" / "branch 3" reference in this doc and in the POC summary keeps its original meaning:

0. HTML generation for alkforge (SSR) from 2026-11-06: alkforge's web view (family ADR-002, the gitea replacement) needs server-side HTML generation, and alkgen provides it: templates rendered over page/data contexts, emitting HTML fragments or pages. Simpler than the code branches and needed before them, so it jumps the queue as the first real consumer.
1. BAST readers/writers/validators: from alktype BAST documents, generate static binary read/write/validate code integrating with alkcall's channels. The originally planned v1 target.
2. Call-protocol handlers: generate the boilerplate for call-protocol (JSON RPC) integration, from jsonschema/openapi (or BAST) inputs, i.e. the static counterpart of alkhttp's from_openapi / from_jsonschema adapters. Second.
3. Template-JIT core: an alkminer-v1-shaped render-then-compile cache with partials. Far down the timeline; influences only how general the core template layer must be. Not a v1 requirement.

The 2026-11-06 unpause (alkforge SSR)

The project paused 2026-09-08 with the reader POC complete. It unpaused 2026-11-06 because alkforge arrived: family ADR-002 (/workspace/@alkdev/alkfamily/docs/architecture/decisions/002-alkforge-gitea-replacement.md) records the decision to replace the self-hosted gitea deployment with a family crate, and alkforge's web view needs server-side HTML generation. alkforge files that ask upstream rather than forking around it (ADR-002's no-deformation rule), so the SSR need flows into alkgen's design.

What this adds, and what it changes about the framing:

• The SSR branch is a runtime rendering use, not a dev-tool use. The code branches (1 and 2) run at a consumer's build time and emit static files into its source tree (OQ-GN-01). The SSR branch means alkgen is linked into alkforge as a library and renders HTML on demand: same template/registry/context machinery, different deployment posture. The settled answer for the code branches stands; it just no longer covers the whole crate.
• The core is a text-generation engine, target classes are template sets. HTML comes free (handlebars' native case), Rust codegen is proven (reader POC), WGSL is proven (alkminer's kernel builder); the shape is identical. The constraint with a real consumer behind it: do not bake reader/writer assumptions into shared core types (OQ-GN-09).
• Queue order: SSR first (alkforge needs it before the codegen branches matter to it), then BAST readers (branch 1), then call-protocol handlers (branch 2), then the template-JIT core (branch 3). The reader POC findings carry over unchanged: they constrain the core's strict-registry/partials/context shape, which SSR shares.
• Dependency refresh: the unpause came after several months of dependency drift. alktype is now 0.4.0 (reservation read/write API, maxLength reserved encoding); the skeleton and the reader POC were revalidated against it (see OQ resolution notes and reader-poc-summary.md's re-validation note).

Core generalization steer (2026-11-06, setup discussion)

Principal steer after the unpause: the shared core should generalize across three real targets, with the dev tool (static files into downstream projects) demoted from "the product" to a nice-to-have projection of the same machinery:

• HTML generation (branch 0): the first and simplest customer. Its value is structural: no plan projection, no layout math, no typed-output machinery. If the core renders HTML cleanly without target-specific exceptions, the codegen paths are not overfitted.
• Rust codecs (branch 1): the reader POC already showed the branch-specific complexity lives in the context builder (plan projection, OQ-GN-02), not the registry/render layer. That is evidence this split works.
• WGSL (confirmed coming; branch 3 territory): alkminer-v1's ShaderBuilder is the precedent, and the JS runtime will require codegen that generates the WGSL. There is prior research in that direction in the family. Because alktype + handlebars are already wasm-clean, a wasm build can carry the render-then-compile cache itself (render as the JIT step at runtime). Far down the timeline, but it fixes one design requirement today: keep partials first-class and keep rendering pure, synchronous, and deterministic so the render step can be cached and compiled downstream. Retrofit cost would be high later, preservation cost now is near zero.

Framing correction (2026-11-06, same discussion, second steer): the "document generation vs code generation" split above carries a false distinction. The core is a text-generation engine: contexts + templates + partials → text. HTML is what handlebars was designed for, Rust codecs are proven by the reader POC, and WGSL is proven by alkminer's kernel builder; three data points, one shape. Neither the registry/layout/render machinery nor the context interface changes because the output text happens to be code: if the core can generate valid HTML, it can generate valid code. What genuinely differs per target is only:

• the template set and context shape (plan-driven projection vs page data views vs shader contexts);
• the emit posture (static files at build time vs in-library render vs render-then-compile feed);
• the validity pinning (each template set's render tests pin its notion of valid output; the core cannot know what "valid" means for WGSL vs HTML vs Rust and should not pretend to).

Concretely, the working split for Phase 1:

• Shared core: registry construction (strict mode, first-class partials), context conventions, deterministic render entry point, typed errors. Everything wasm-clean, synchronous, allocation-lean.
• Per target: the template set, the context shape, the emit posture, and the validity pinning.
• Demoted, not dead: the dev-tool emit model (OQ-GN-01) stays the shape of branches 1/2's output but is no longer the definition of the crate; the crate is "text generation from templates and partials over typed contexts", with targets as template sets plus emit layers.

This refines OQ-GN-09: the SSR branch is not a special case to be accommodated; it is the first instantiation and the generality test. WGSL is the third instantiation and needs nothing from the core that the first two do not already require.

What is already settled

• The stack shape: handlebars-rust renders templates; alktype provides the BAST document model (Schema/Definitions builder types, AlkTypeKind, OffsetMap, PackedLayout, read_plan, validation_plan); alkgen owns template assets, context building, registry construction, and rendering. Output is static code files generated into downstream projects (dev-tool model, OQ-GN-01) for the code branches; in-library HTML rendering for the SSR branch (see §unpause).
• wasm-clean is validated, not assumed. The skeleton (alktype
  • handlebars 6.4 + serde_json preserve_order + thiserror) compiles to wasm32-unknown-unknown release as-is; re-verified 2026-11-06 with alktype 0.4.0. handlebars-rust ships its own wasm playground (wasm/ + build-wasm.sh), so keeping the constraint costs nothing. Only the optional handlebars features are platform-bound (dir_source → walkdir/fs, script_helper → rhai); the crate avoids both.
• The handlebars version: latest stable is 6.4.4 (crates.io); the vendored /workspace/handlebars-rust is head, exactly one commit past the release tag. Pin 6.4 from crates.io; the vendored checkout serves as reading material / emergency patch source only.
• Strict mode is the default posture: alkminer-v1's ShaderBuilder (the closest prior art for a multi-template strict registry) sets set_strict_mode(true); for codegen, a missing variable must be a render error, not silently-empty output (silent gaps surface as compile bugs in the consumer's build, far from the cause). This is AGENTS.md convention 6. For the SSR branch the same posture applies (a missing variable in a page template is a render error, not silently-blank HTML).
• Templates are code: inline const &str or include_str!, versioned in-repo, render tests pinning golden output (typebox-rs precedent, strengthened into AGENTS.md convention 7). Applies to HTML templates too: a page render's golden output is pinned the same way.
• Determinism and hygiene: generated artifacts carry the "Auto-generated by alkgen. DO NOT EDIT." banner; same BAST + same templates + same options → byte-identical output (AGENTS.md convention 8). Note the interaction with preserve_order: alktype depends on schema-JSON key order (packed byte order), so contexts must preserve document order; sort only where a template explicitly requires it. For the SSR branch the banner does not apply to rendered HTML, but determinism still does (same BAST + templates + options → byte-identical HTML; alkforge caching and tests both lean on it).

Prior art

typebox-rs src/codegen, the direct ancestor

/workspace/@alkimiadev/typebox-rs/src/codegen/rust.rs is the older, simpler version of this idea, and it validates the basic shape:

• Handlebars<'static> registry, templates registered from inline const &str, per-schema-kind context structs (#[derive(Serialize)]) built in Rust, one mapping function (schema_to_rust_type) turning schema kinds into target-language type strings.
• Weaknesses to not inherit (it predates the alk* conventions): templates registered with .unwrap() (lib convention: typed errors), no strict mode (silently-empty output possible), no generated-code banner on fragments, no determinism discipline (type_refs: HashMap in context), template tests assert only contains(...) rather than pinning golden output.
• What it lacks entirely: partials, layout awareness (it generated serde-derive structs, not wire readers/writers), multi-branch output (readers + writers + validators from one document).

alkminer-v1 compute/kernel.rs: handlebars as JIT

ShaderBuilder = strict registry + register_partial / register_template / render, followed by render-then-compile with caching downstream. Branch 3 (the codegen JIT) is literally this shape with compile targets other than wgpu pipelines. Structural takeaway for the core layer: build the registry so partials are first-class (registerable, composable) from the start; that is the only branch-3 requirement that leaks back into v1, and it is cheap. The same structure serves the SSR branch: alkforge's page templates will want partials (header/footer/nav) as first-class registerable assets.

alktype, the interpreter that implies the compiler

alktype ships runtime plans (OffsetMap, PackedLayout, read_plan::ReadPlan, validation_plan::ValidationPlan): it walks BAST documents at runtime, per schema load. Branch 1 is the compile-time counterpart: the same walks, but emitting code instead of executing plans. The plans are therefore the best available spec for what generated readers/writers/validators must do; they encode the semantics (bounds checks, endianness, variable-length encoding, TUnion dispatch, alignment) that templates must reproduce as literal code. Key question thread: how much of the plan structure should drive template context, and where does the interpreter/compiler duplication get cut (see OQ-GN-02, OQ-GN-03).

alkhttp adapters, the handler shape for branch 2

from_openapi / from_jsonschema build operation tables from external schema documents. Branch 2 generates such adapters (or the code they'd hand-write) from BAST/JSON documents. Farther out; mainly a reminder that the core should not bake reader/writer assumptions into shared types.

Open Questions

Numbered OQ--NN.. for reference and promotion to docs/architecture/open-questions.md in Phase 1.

OQ-GN-09 (new, 2026-11-06): What does the SSR branch require of the shared core?

alkforge needs server-side HTML generation before the code branches matter to it (see §unpause). Opened by the unpause; this is the queue entry point for Phase 1.

Half-hunch (to be validated): the shared core is the same in both target classes, namely registry construction (strict mode, partials as first-class assets), context building, and a rendering entry point, all synchronous and wasm-clean (alkforge wants SSR without platform surprises). What differs per target class is the template set and the context shape: HTML contexts (page/data views, no layout math, no plan projection) vs code contexts (plan-driven projection per the reader POC). Candidates for what must be decided early:

• Library posture for SSR: alkgen in-process (linked into alkforge; render-per-request or render-per-build) vs pre-rendered static assets. In-process rendering with deterministic output enables hashing/caching; pre-rendering reuses the dev-tool shape directly. Affects alkgen's dependency weight inside alkforge (wasm-clean matters less in-process; strict sync API matters everywhere).
• Output unit for HTML: full page vs fragment vs both (partials make fragments natural; OQ-GN-01's fragment exclusion was scoped to the code branches).
• Whether the DO-NOT-EDIT banner and generated-code hygiene rules apply (they were written for code artifacts; rendered HTML is a runtime consumer product, not checked-in generated code, unless alkforge pre-renders).
• Error posture in the SSR path: render failure → typed error → alkforge's error page; no panics (same convention 2 rationale: alkforge serves arbitrary git/HTTP traffic).

Residue for Phase 1: the exact shared-core split (what is template-set-agnostic vs per-target), and the alkforge SSR library/API shape.

OQ-GN-01: What is alkgen's primary unit of output: a crate, a module, a fragment?

Resolved 2026-09-08 (setup discussion): static files generated into a consumer project. The clarification that resolved it: alkcall is a library others build on, and branches 1 and 2 are a dev tool consuming it; it generates boilerplate into some downstream project (protocol crates like alktty/alktunnels/sftp, cloud-provider integrations like vast.ai/runpod), not into alkcall itself. Both branches take a provided schema document (BAST or jsonschema/ openapi) and emit static files.

• Fragment is out; the consumer assembling fragments by hand defeats the dev-tool purpose.
• Crate is out for v1; generating a whole Cargo project is trivially composed from modules later if a consumer asks, and would bake build-layout decisions (workspace placement, dep versions) into the generator prematurely.
• Module-level output is the v1 shape: one document → one or more self-contained .rs files (banner + use statements + impls), dropped into the consumer's src/ tree. Matches typebox-rs generate_module and how generated protocol files would sit in e.g. an alktunnels-style crate.

2026-11-06 scope note: the fragment exclusion was written for the code branches. The SSR branch (OQ-GN-09) may want fragment-level HTML output; that question does not reopen this resolution.

Residue for Phase 1: file partitioning policy (one file per document vs per-type files; where the reader/writer/validator split lands), and whether generated files are regenerated wholesale (overwrite) or support partial regeneration. These are spec-shape tasks, not research questions.

OQ-GN-02: Interpretation depth: render from BAST directly, or from alktype's plans?

Templates need a context. Two candidate sources:

• BAST document (serde_json::Value schema + Definitions): closest to the source of truth; templates/contexts do their own walking (typebox-rs did this).
• alktype plans (OffsetMap, ReadPlan, ValidationPlan): pre-digested semantics; offsets, sizes, bounds-check shapes, dispatch structure are already computed and validated; the template context becomes a projection of the plan rather than a re-derivation.

The plan-driven path risks baking alktype internals into template contexts (plans are public API but evolve); the BAST-driven path re-duplicates the layout math alktype already owns (drift risk: generated readers disagreeing with the engine's own interpretation). Half-hunch: plans as the semantic source for offsets/sizes, BAST for descriptive metadata (names, docs), with the exact projection decided in Phase 1. This decision shapes the whole context-builder layer.

Direction set 2026-09-08 (setup discussion): plan-driven, with BAST for descriptive metadata. Supporting rationale:

• The layout math (offsets, sizes, dispatch structure) is already computed and validated by the engine; re-deriving it in the template layer would reintroduce exactly the drift OQ-GN-03 flags as the standing risk, by construction.
• alktype is already a dependency; plan computation at generation time costs nothing extra.
• The residual risk inverts: instead of drifting from engine semantics, contexts now track alktype's public plan API. If a plan shape evolves, context builders evolve with it, an ordinary dependency-upgrade concern, not a correctness risk.

Refined by the reader POC (finding F-6): for typed output, names come from the BAST doc (the plan eagerly resolves $refs and loses def names), while the plan remains the semantic source. Net: plan for semantics, BAST doc for names.

Residue for Phase 1 (spec-shape, not research): the exact projection (which plan structures (OffsetMap entries, ReadPlan nodes, ValidationPlan fields) map to which template-context shapes) and where BAST metadata (names, docs, annotations) joins the projection. This is the context-builder layer's spec task.

OQ-GN-03: Where does the interpreter/compiler duplication get cut?

Resolved as posture, 2026-09-08 (setup discussion): the duplication is the point; two deployment profiles, complements not competitors.

• alktype (interpreter) serves the dynamic case: schemas arrive at runtime from arbitrary peers (alkcall hub/spoke, binary rpc); the plan-walk cost is the price of not trusting the schema. It is near the performance floor for a schema-driven method, but sits roughly 20x worse than hand-rolled code in several paths.
• alkgen (compiler) serves the static case: schema known at build time, dispatch compiled to native code. The ~20x gap is the value proposition; recovering most of it is branch 1's success metric (OQ-GN-08's three-way benchmark). "Static is faster" applies to branch 2 the same way: generated handlers with dispatch compiled in vs alkhttp adapters interpreting a spec document at runtime.
• This is also why the crate starts now, before the JIT-ish branch 3: the static path already has a consumer (alkcall channels).

The reader POC sharpened this: at the Value-materializing output contract the generated path is already near the hand-written ceiling (only ~10-20% below); the interpreter win is ~1.9x, and the 20x-scale gains live at the typed output contract (resolved for branch 1 by the POC's second render, typed direct codecs).

Residue (kept open): the semantic single-source question. The plans (ReadPlan, ValidationPlan, OffsetMap) remain the spec generated code must mirror; engine/generated-code drift is the standing risk, tracked via OQ-GN-02 (context source). "alktype consumes alkgen's tables" is not on the table for v1; revisit only if drift bites.

OQ-GN-04: Target-language scope for v1

Branch 1 output is Rust (alkcall is Rust). Does alkgen need a target-language abstraction (template sets per language, typebox-rs had rust.rs + typescript.rs) from day one, or is "Rust-only templates" acceptable with the core kept language-agnostic? Half- hunch: keep the core (context building, registry, rendering) target- agnostic; make v1 templates Rust-only; defer any TS/WASM template set until a consumer asks. Cost of retrofit is low if contexts stay language-neutral. The 2026-11-06 unpause adds a non-Rust-output data point for this hunch: the SSR branch emits HTML with the same core, which is exactly the "contexts stay language-neutral, template sets differ" pattern working out in practice.

OQ-GN-05: Reader/writer code style: raw bytes or alktype-delegating?

Generated readers can be (a) self-contained byte manipulation (offsets + as casts + bounds checks, fully compiled), (b) thin callers into alktype's runtime (SequentialReader with plans), or (c) a middle shape (compile-time offset tables, runtime calls for variable-length/union paths). (a) maximizes compile-time value but duplicates the most semantics; (b) is nearly pointless (just calls alktype); (c) is the likely landing zone but the boundary is undecided. Interacts with OQ-GN-02/03. Needs a POC-quality answer before Phase 1 ADR.

Resolved 2026-09-08 (reader POC, see reader-poc-summary.md): option (a), self-contained generated code. The POC built a reader with zero alktype runtime dependency, byte-parity-exact against the interpreter, ~1.9x faster. Uniform cursor addressing (not source offset folding) is the right model; LLVM folds constant cursor chains (finding F-1). The (c) middle shape is moot: compiled dispatch wins without runtime delegation.

OQ-GN-06: Does branch 1 output depend on alktype at all?

Resolved 2026-09-08 (reader POC): generated output depends only on serde_json (the Value output contract). alktype appears only in the generator (build script); consumers' generated code is alktype-free. The POC's second render (typed output) went further: zero dependencies at all, not even serde_json. Caveat carried to Phase 1: if the output contract changes shape again, the dependency list moves with it (typed with serde bridges would reintroduce a serde derive dep; see the POC summary's (a) vs (b) resolution).

Original framing (retained for context): generated files land in downstream projects which do not currently depend on alktype, so a self-contained (a) output makes the generated module dependency-free, while a delegating (b/c) output adds alktype as a runtime dep of the consumer project.

OQ-GN-07: Validation strategy in generated code

alktype's validate_bytes materializes a Value from bytes then runs jsonschema, a heavyweight runtime path. Generated validators could instead emit checks derived from validation_plan (no materialization, no jsonschema dep in generated code), but then generated validation must track alktype's validation semantics exactly (drift risk, same as OQ-GN-02). Unresolved; affects whether generated code needs a jsonschema dependency.

Partially resolved 2026-09-08 (reader POC): the read path's validation (bounds checks, UTF-8 validation, union dispatch limits) is proven generatable as error-returning code with no jsonschema dependency. The full BAST-validation question (jsonschema-derived semantic checks) remains open; see the POC summary's follow-up #5.

OQ-GN-08: POC scope

Candidate POCs (in rough priority order), per the SDD "validate promising approaches":

1. Reader POC (OQ-GN-05/06/07): take one small BAST document (a flat struct + one variable-length field + one TUnion), render a reader via handlebars from an OffsetMap/ReadPlan-derived context, compile it, and check byte-level agreement against alktype's own SequentialReader on a fixed corpus. This answers the biggest cluster (context source, delegation boundary, dependency question) in one executable artifact.
2. Strict-registry + partials core POC: cheap; validates the alkminer-shaped core against branch-1 needs (probably just folded into POC 1).
3. Handler-adapter POC (branch 2): deferred until branch 1 converges.

Resolved 2026-09-08 (reader POC, see reader-poc-summary.md): POC 1 ran as the standalone-crate precedent (/workspace/alkgen- reader-poc, self-contained, findings written back here). Results: plan-driven handlebars codegen validated end-to-end; parity-exact, ~1.9x faster than the interpreter, and a decomposition finding: the ~20x-vs-hand-rolled gap is Value-allocation cost, not dispatch overhead (output-parity hand-rolled baseline is only ~10-20% faster than generated). Biggest Phase 1 ADR: the output contract (Value-materializing vs typed structs), resolved for branch 1 by the typed second render (direct codecs). POC 2 folded into POC 1 (strict registry + partials exercised); POC 3 deferred.

Calibration input, 2026-09-08 (setup discussion): the interpreter sits ~20x worse than hand-rolled code on several paths; branch 1's success metric is recovering most of that gap. POC 1 should add a three-way benchmark (alktype plan-walk vs generated reader vs a hand-rolled baseline); it doubles as the drift check and the performance validation, and gives the "how much of the 20x do we recover" answer with numbers instead of vibes. This raises POC 1's value: the delegation boundary (OQ-GN-05) is now a performance trade, not just a structural one; every runtime call into alktype is a place the compiled path stays interpreter-shaped.

Survey / prior-art list

• /workspace/@alkimiadev/typebox-rs/src/codegen/rust.rs: context structs, inline templates, per-kind type mapping (§Prior art).
• /workspace/@alkminer/reference/alkminer-v1/src/compute/kernel.rs: strict registry, partials-first core, render-then-compile (§ Prior art).
• /workspace/@alkdev/alktype/src/: read_plan.rs, validation_plan.rs, offset_map.rs, layout_builder.rs; the runtime semantics generated code must mirror. docs/architecture/ there (layout-engine.md, data-access.md, validation.md) is the authoritative behavior spec. Now at 0.4.0.
• /workspace/@alkdev/alkhttp/src/adapters/from_openapi.rs / from_jsonschema.rs: the handler shape branch 2 targets.
• /workspace/@alkdev/alkcall: the consumer for branch 1 output (channels readers/writers/validators); its AGENTS.md encodes the no-panics/no-unsafe posture generated code must satisfy.
• /workspace/@alkdev/alkforge (docs-stage) + family ADR-002: /workspace/@alkdev/alkfamily/docs/architecture/decisions/002-alkforge-gitea-replacement.md; the SSR consumer that drove the unpause; its no-deformation rule routes its asks into alkgen's design (OQ-GN-09).
• /workspace/handlebars-rust: vendored head checkout (1 commit past v6.4.4); crates.io 6.4 is the pinned dep. wasm playground under wasm/ proves the wasm-clean story.
• /workspace/alkgen-reader-poc: the reader POC crate (2026-09-08; re-validated on alktype 0.4.0, 2026-11-06): plan→context→render→ parity→bench end-to-end; docs/research/reader-poc-summary.md here carries the findings.

Convergence checklist (what Phase 0 must produce)

• Stack validated: skeleton builds wasm-clean (alktype 0.3.0 + handlebars 6.4, 2026-09-08; re-verified on alktype 0.4.0, 2026-11-06)
• Prior art surveyed: typebox-rs, alkminer-v1, alktype plans, alkhttp adapters (§Prior art)
• Branch scope framed: initially readers/writers/validators first, handlers second, JIT later (§opening); reshaped 2026-11-06 by the unpause: alkforge SSR (branch 0) jumps the queue
• OQ-GN-01 (output unit): resolved 2026-09-08: static files generated into downstream projects (dev-tool model); module- level output for v1, fragments and crate-generation out. Residue: file partitioning policy (Phase 1 spec task). 2026-11-06 note: fragment exclusion is code-branch-scoped; see OQ-GN-09 for the SSR branch's output unit.
• OQ-GN-02/03 (context source, duplication cut): direction set 2026-09-08: plan-driven contexts (plans for offsets/sizes, BAST for descriptive metadata); duplication resolved as posture; refined by the POC (names from BAST, typed output resolved to direct codecs). Residue: exact plan→context projection (Phase 1 spec task)
• OQ-GN-04 (language scope): dispositioned 2026-11-06 at Phase 1 start: core language-agnostic by construction (architecture ADR-001/ADR-004), template sets written per consumer need (SSR HTML first, Rust codecs second, WGSL deferred); tracker entry OQ-08 in docs/architecture/open-questions.md records the adoption. The SSR branch arriving with no core change is the hunch's predicted data point
• OQ-GN-05/06 (delegation boundary, dependency shape): resolved 2026-09-08 by reader POC: self-contained generated code, serde_json-only dependency for the Value contract, zero-dep for the typed contract; uniform cursor addressing (F-1)
• OQ-GN-07 (validation strategy): read-path validation proven generatable; full BAST-validation strategy still open
• OQ-GN-08 (POC decision): DONE 2026-09-08: reader-poc-summary.md; three-way benchmark + parity corpus; Phase 1 input list in the POC summary's follow-ups. Re-validated 2026-11-06 on alktype 0.4.0 (tests + bench unchanged)
• OQ-GN-09 (SSR branch scope, opened 2026-11-06): needs a scope/library-posture answer (in-process rendering vs pre-rendered, shared-core split) before Phase 1's ADRs; alkforge is the consumer waiting on it. Refined by the core generalization steer (§"Core generalization steer"): the core split proposal is recorded; the remaining decision is the SSR library posture and the exact core/emit boundary