diff --git a/docs/research/phase-0.md b/docs/research/phase-0.md index 3aaa1e7..687bd67 100644 --- a/docs/research/phase-0.md +++ b/docs/research/phase-0.md @@ -80,6 +80,48 @@ What this adds, and what it changes about the framing: 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 / the wasm JIT idea (branch 3 territory)**: alkminer-v1's + `ShaderBuilder` is the precedent. Since 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. + +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 (plan-driven + projection vs page/data views vs shader contexts), and the emit + posture (static files at build time vs in-library render vs + render-then-compile feed). +- **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 "template rendering over alk-type documents + and arbitrary 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. + ## What is already settled - **The stack shape**: handlebars-rust renders templates; alktype @@ -511,4 +553,7 @@ is a place the compiled path stays interpreter-shaped. - [ ] 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 + 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