docs(phase0): core generalization steer: one core, three targets

Principal steer: generalize the shared core across HTML generation
(branch 0), Rust codecs (branch 1), and WGSL/wasm-JIT (branch 3
territory); dev-tool emit demoted from the crate's definition to one
projection. Records the core/per-target split and the render-purity
requirement the wasm JIT fixes for Phase 1; refines OQ-GN-09.
This commit is contained in:
glm-5.3-flash committed 2026-11-06 07:51:12 +00:00
1 parent 65a8c3e379
commit bbd7d8164b
1 file changed
+46 -1
+46 -1
View File
@@ -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