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:
1 parent
65a8c3e379
commit
bbd7d8164b
1 file changed
+46
-1
@@ -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
|
||||
Reference in new issue
Block a user