@kudzujs/core 0.8.21 → 0.8.23

package/MIGRATION_ROADMAP.md

@@ -223,6 +223,26 @@ This queue orders the next investigations by general migration value. Start only
 - Previous transformer-wide keyed value, condition, event, nested-list, effect, and rendered-list AST side tables were removed. AST remains private only inside immediate source-local validation and lowering.
 - `core.mjs` remains authoritative for final list IDs, key paths, route descriptors, complete HTML, DOM identity, and exact state/effect/ref release; accepted syntax and browser output are unchanged.
 
+### Completed In 0.8.21
+
+- Every supported effect finalizes into JSON-safe EffectIR with setup HandlerIR, cleanup, ordered signal/DerivedIR dependencies, component/keyed ownership, source provenance, and Worker edges.
+- Effect dependency/resource analysis and Worker rewriting return explicit results; transformer-wide effect AST side tables and build-wide mutable Worker references were removed.
+- Existing route/layout/conditional/keyed lifetime allocation, stale-write invalidation, cleanup order, accepted syntax, and browser output remain unchanged.
+
+### Completed In 0.8.22
+
+- The existing rendered route plan is RouteIR v1, with route-local numeric state slots beside unchanged browser IDs and readable state names; it is not duplicated in ModuleIR.
+- The existing pure capability projection is CapabilityIR v1 and every runtime/list codegen consumer rejects unsupported versions.
+- List, parameter, core, effect, binding, native, and navigation source generation moved out of `build.mjs` behind focused fail-closed generators; `build.mjs` decreased by 267 lines and coordinates stage outputs.
+- Complete-site and representative deploy artifacts remain byte-identical to `v0.8.21`; only additive RouteIR version/slot metadata changes build plans.
+
+### Completed In 0.8.23
+
+- Source normalization, TSX semantic analysis, ModuleIR finalization, handler generation, and build-module generation now belong to one no-write source compiler boundary.
+- `compileSource()` returns JSON-safe, project-relative source results; `build.mjs` consumes them without TypeScript traversal or feature analysis.
+- Source graph resolution and shared path conversion have focused owners, while Worker compilation directly owns Worker graph emission.
+- Complete-site and representative deploy artifacts remain byte-identical to `v0.8.22`; diagnostics, RouteIR, CapabilityIR, browser ownership, and accepted syntax are unchanged.
+
 ## Cross-Cutting Performance Gates
 
 Every migration feature must preserve:

package/PERFORMANCE.md

@@ -1,5 +1,53 @@
 # Performance Records
 
+## 0.8.23 Source Compiler Boundary
+
+Measured UTC 2026-08-09 on Apple M3, 8 logical CPUs, 8 GiB RAM, macOS 26.5.2 / Darwin 25.5.0, Node 22.23.2, and npm 11.18.0. Baseline tag `v0.8.22` at `60b9bff` and the current `0.8.23` compiler candidate used the same local volume and identical installed dependencies.
+
+The candidate implementation patch over `v0.8.22` had SHA-256 `cfa25426f630f3d5d75a788f9ef8c63c48531c74ffc58727437890c47c511945`, produced by:
+
+```bash
+git diff --binary v0.8.22 -- framework/build.mjs framework/compiler/source-compiler.mjs framework/compiler/source-graph.mjs framework/compiler/path-helpers.mjs framework/compiler/worker-compiler.mjs framework/dev-server.mjs test/compiler-passes.test.mjs test/framework.test.mjs | shasum -a 256
+```
+
+Both targets received one warm-up followed by seven clean `worker-effects` production builds in alternating round-robin order. Cleanup remained outside timing. The ranges overlap; the 0.24% lower candidate median does not establish a material change.
+
+| Target | Build median | Worker raw / gzip | Window raw / gzip |
+|---|---:|---:|---:|
+| 0.8.22 baseline | 287.7 ms | 907 B / 477 B | 12,148 B / 5,411 B |
+| 0.8.23 candidate | 287.0 ms | 907 B / 477 B | 12,148 B / 5,411 B |
+
+```text
+0.8.22: [287.3,288.1,287.7,289.3,285.7,286.8,289.1]
+0.8.23: [289.2,283.7,287.4,287.0,293.8,287.0,285.4]
+```
+
+Before release-content updates, the complete 135-page site and the `bindings`, `keyed-row-hooks`, `effect-dependencies`, `worker-effects`, `runtime-params`, `navigation`, `config-authoring`, and `event-package` deploy trees had identical file lists and bytes. Their `.kudzu` trees also matched after replacing only each checkout root in existing source-location strings. The invalid-reducer fixture retained the same source file, line, column, and diagnostic text. `build.mjs` decreased from 3,732 to 744 lines; this source-organization metric is not a runtime performance claim.
+
+## 0.8.22 Versioned Compiler Foundation
+
+Measured UTC 2026-08-09 on Apple M3, 8 logical CPUs, 8 GiB RAM, macOS 26.5.2 / Darwin 25.5.0, Node 25.6.1, and npm 11.18.0. Baseline tag `v0.8.21` at `ff38092` and the current `0.8.22` compiler candidate used the same local volume and identical installed dependencies.
+
+The candidate implementation patch over `v0.8.21` had SHA-256 `e1d89c97dd8dfb60d41ae9c14ac64dfbb50466e024f80076f430ae9e725fb28f`, produced by:
+
+```bash
+git diff --binary v0.8.21 -- framework/build.mjs framework/compiler/list-runtime-codegen.mjs framework/compiler/param-codegen.mjs framework/compiler/route-capability-planner.mjs framework/compiler/runtime-codegen.mjs framework/core.mjs framework/core.d.ts | shasum -a 256
+```
+
+Both targets received one warm-up followed by seven clean `worker-effects` production builds in alternating round-robin order. Cleanup remained outside timing. Both medians were exactly 250.1 ms; the distributions overlap and establish no material change.
+
+| Target | Build median | Worker raw / gzip | Window raw / gzip |
+|---|---:|---:|---:|
+| 0.8.21 baseline | 250.1 ms | 907 B / 475 B | 12,148 B / 5,427 B |
+| 0.8.22 candidate | 250.1 ms | 907 B / 475 B | 12,148 B / 5,427 B |
+
+```text
+0.8.21: [249.7,252.0,250.1,251.2,250.0,254.8,249.1]
+0.8.22: [250.1,247.3,255.1,249.3,253.1,250.3,248.7]
+```
+
+Before release-content updates, the complete 135-page site and the `bindings`, `keyed-row-hooks`, `effect-dependencies`, `worker-effects`, `runtime-params`, and `navigation` deploy trees had identical file lists and bytes. Their build plans were equivalent after removing the intentional additive RouteIR `version` and state `slot` fields. Every measured Worker/window artifact name, raw byte count, and gzip byte count was identical. `build.mjs` decreased from 3,999 to 3,732 lines; this source-organization metric is not a runtime performance claim.
+
 ## 0.8.21 Explicit Effect Ownership
 
 Measured UTC 2026-08-09 on Apple M3, 8 logical CPUs, 8 GiB RAM, macOS 26.5.2 / Darwin 25.5.0, Node 25.6.1, and npm 11.18.0. Baseline tag `v0.8.20` at `7fb6e37` and the current `0.8.21` compiler candidate used the same local volume and identical installed dependencies.

package/README.md

@@ -14,7 +14,7 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 > Experimental `0.8.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.8.21 - Explicit effect ownership.** Effects now retain deterministic JSON-safe setup, cleanup, dependency, component/keyed ownership, source, and Worker-edge records while final route lifecycle allocation remains unchanged. Read the [release notes](./RELEASES.md#0821---explicit-effect-ownership), open the [release page](https://kudzujs.cloud/releases/0.8.21), or follow the [next architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.8.23 - Source compiler boundary.** Source normalization, TSX analysis, ModuleIR finalization, handler generation, and build-module generation now belong to a no-write source compiler. `build.mjs` coordinates discovery, source results, RouteIR, CapabilityIR, and artifact emission without analyzing TSX. Read the [release notes](./RELEASES.md#0823---source-compiler-boundary), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.23), or follow the [architecture packet](./docs/next-architecture/README.md).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)

package/RELEASES.md

@@ -1,5 +1,76 @@
 # Kudzu Releases
 
+## 0.8.23 - Source compiler boundary
+
+Kudzu 0.8.23 completes the Goal A compiler foundation by moving source normalization, TSX semantic analysis, ModuleIR finalization, handler generation, and build-module generation behind one explicit no-write source compiler result.
+
+### Changed in 0.8.23
+
+- `compileSource()` returns a JSON-safe source result containing the project-relative build module, component analysis, ModuleIR, optional handler module, and imported assets without writing to `.kudzu` or `dist`.
+- `createKudzuTransformer()` and all TypeScript AST feature analysis moved from `framework/build.mjs` to `framework/compiler/source-compiler.mjs`.
+- Shared source resolution moved to `source-graph.mjs`; shared URL and filesystem path conversion moved to `path-helpers.mjs` and is reused by the development server.
+- Worker graph emission is owned and exported directly by `worker-compiler.mjs`; the source result retains only JSON-safe Worker edges and rewritten source.
+- `build.mjs` decreased from 3,732 to 744 lines and now coordinates discovery, source results, RouteIR, CapabilityIR, and artifact emission.
+
+### Goal A boundary
+
+- Source analysis consumes all AST-bearing state before returning its result. No `ts.Node`, `Map`, `Set`, function, closure, or Symbol crosses into build orchestration.
+- `compileSource()` returns project-relative generated paths and client import roots. Existing absolute paths remain only in source-located diagnostics and are normalized when comparing detached worktrees.
+- RouteIR v1 and CapabilityIR v1 remain unchanged, and `core.mjs` remains authoritative for complete HTML and browser ownership IDs.
+- Goal B optimization remains deferred; `0.8.23` is the corrected Goal A completion baseline.
+- No accepted syntax, public API behavior, runtime capability, VDOM, hydration, component rerender, or retained browser component tree was added.
+
+### Validation
+
+- The complete suite passes 171/171 tests, including a direct no-write, project-relative, JSON-round-trippable `compileSource()` boundary check.
+- Node 22 type checks, the 135-page complete-site build, and all 171 tests pass.
+- The complete site and eight representative binding, keyed-row, effect, Worker, parameter, navigation, config, and package-handler deploy trees are byte-identical to `v0.8.22`; their `.kudzu` trees match after normalizing only checkout-root source locations.
+- An invalid reducer fixture retains the same source file, line, column, and diagnostic text.
+- Worker and window graph files remain byte-identical. Seven interleaved clean Node 22 builds measured a 287.0 ms candidate median against 287.7 ms for `v0.8.22`; raw arrays and provenance are recorded in `PERFORMANCE.md`.
+- `create-kudzu` remains 0.1.101 because its unchanged template already accepts `@kudzujs/core@^0.8.15`.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.23
+```
+
+## 0.8.22 - Versioned compiler foundation
+
+Kudzu 0.8.22 versions the rendered route plan as RouteIR v1 and the pure capability projection as CapabilityIR v1 while source-local ModuleIR seams and focused artifact generators preserve existing output.
+
+### Changed in 0.8.22
+
+- The existing `renderPage().plan` is RouteIR v1 rather than a duplicated route representation.
+- Route states add a deterministic route-local numeric `slot`; existing string `id` values remain authoritative browser/DOM identities and `name` remains readable development metadata.
+- The existing pure capability manifest is CapabilityIR v1. Route and capability consumers reject unsupported versions.
+- List, parameter, core, effect, binding, native, and navigation runtime generation moved from `build.mjs` into focused generator modules with narrow inputs and no filesystem ownership.
+- Required authored-runtime source anchors fail closed instead of silently retaining stale branches.
+- `build.mjs` decreased from 3,999 to 3,732 lines and now coordinates generator results and artifact emission rather than containing those feature semantics.
+
+### Goal A boundary
+
+- ModuleIR slots identify source-local compiler records; RouteIR state slots identify positions in one rendered plan; browser IDs continue to own DOM/runtime behavior. The namespaces are deliberately independent.
+- `core.mjs` remains authoritative for complete HTML, route/layout IDs, conditions, keyed paths, effect lifetimes, and exact cleanup.
+- CapabilityIR selects shared runtime families and branches; RouteIR and ModuleIR references retain route entries, handlers, and Workers. Static pages remain complete documents with zero JavaScript.
+- Goal B optimization remains deferred; the final source compiler boundary and corrected Goal A completion baseline follow in `0.8.23`.
+- No accepted syntax, public API behavior, runtime capability, VDOM, hydration, component rerender, or retained browser component tree was added.
+
+### Validation
+
+- The complete suite passes 170/170 tests, including RouteIR JSON round-trip and slots, CapabilityIR JSON round-trip/version rejection, fail-closed generator contracts, list/parameter/navigation generation, lifecycle cleanup, and development restoration by readable state name.
+- `npm run check`, focused Node 22 compiler tests, and a Node 22 complete-site build pass.
+- The complete site plus six representative binding, list, effect, Worker, runtime-parameter, and navigation deploy trees are byte-identical to `v0.8.21`; normalized RouteIR meaning is identical in all seven comparisons.
+- Worker and window graph files remain byte-identical. Seven interleaved clean builds measured equal 250.1 ms medians; raw arrays and provenance are recorded in `PERFORMANCE.md`.
+- Release-blocking architecture audits drove full IR schema validation, accurate reachability ownership, and fail-closed source contracts before publication.
+- `create-kudzu` remains 0.1.101 because its unchanged template already accepts `@kudzujs/core@^0.8.15`.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.22
+```
+
 ## 0.8.21 - Explicit effect ownership
 
 Kudzu 0.8.21 completes the next Goal A source-analysis seam: every supported effect now registers deterministic JSON-safe setup, cleanup, dependency, ownership, source, and Worker-edge data before existing build-time rendering allocates concrete lifecycle IDs.

package/docs/next-architecture/README.md

@@ -6,8 +6,8 @@ The top-level [`GOAL_A.md`](../../GOAL_A.md) and [`GOAL_B.md`](../../GOAL_B.md)
 
 | Goal | Decision | Start condition |
 |---|---|---|
-| A: compiler foundation | `0.8.21` EffectIR source-analysis seam complete | Continue with `0.8.22` RouteIR, CapabilityIR, and the architecture/output audit after the release boundary. |
-| B: optimization benchmarks | Deferred | Goal A complete and its output baseline recorded |
+| A: compiler foundation | Complete in `0.8.23` | The no-write source compiler, RouteIR v1, CapabilityIR v1, generator boundaries, and output baseline are recorded. |
+| B: optimization benchmarks | Deferred | Start only by explicit decision from the recorded `0.8.23` baseline. |
 | C: state/resource model | Research only | Reduced fixtures expose a limitation |
 | D: routing compatibility | Current behavior preserved | Revisit only with migration evidence and invariant review |
 
@@ -36,7 +36,7 @@ The top-level [`GOAL_A.md`](../../GOAL_A.md) and [`GOAL_B.md`](../../GOAL_B.md)
 - [ ] Read [`MIGRATION_ROADMAP.md`](../../MIGRATION_ROADMAP.md) and this directory before planning migration work.
 - [ ] Confirm `package.json` still reports the actual current version; never infer release status from this plan.
 - [ ] Inspect the worktree and preserve unrelated or uncommitted changes.
-- [ ] Start only the next incomplete Goal A patch in [`versioning.md`](./versioning.md).
+- [ ] Start later architecture work only by an explicit decision from the completed Goal A baseline.
 - [ ] Preserve accepted syntax, diagnostics, route plans, HTML, asset selection, and browser ownership behavior.
 - [ ] Run the repository checks required by that implementation patch and record output deltas.
 - [ ] Update this packet when a planned boundary changes; update release records only when a release actually occurs.

package/docs/next-architecture/compiler-current-architecture.md

@@ -1,31 +1,33 @@
 # Current Compiler Architecture
 
-This maps the EffectIR boundary prepared for `0.8.21`. File and function names are the stable references; line numbers are intentionally omitted because Goal A moves code.
+This maps the completed `0.8.23` Goal A compiler foundation. File and function names are the stable references; line numbers are intentionally omitted because later work may still move code.
 
 ## Responsibility Map
 
 | Responsibility | Current owner | Current contract |
 |---|---|---|
 | CLI entry | [`bin/kudzu.mjs`](../../bin/kudzu.mjs) | Dispatches build and development commands. |
-| Build orchestration | [`framework/build.mjs`](../../framework/build.mjs), `build()` | Loads config; discovers reachable source, CSS, and assets; compiles sources; renders routes; plans capabilities; emits `dist/`; invokes `afterBuild`. |
-| Reachability/import resolution | `framework/build.mjs`, `reachableSourceFiles()`, `resolveSourceImport()` | Starts from page entries, follows relative runtime imports/re-exports and validated Worker references, and excludes unreachable migration source. |
-| Ordered normalization | [`framework/compiler/normalization-pipeline.mjs`](../../framework/compiler/normalization-pipeline.mjs), `applyNormalizationPasses()`; `framework/build.mjs`, `normalizeCompilerSource()` | Applies migration/resource passes in order and repairs TypeScript parent pointers after every pass. Imported source uses the same pipeline. |
+| Build orchestration | [`framework/build.mjs`](../../framework/build.mjs), `build()` | Coordinates config, discovery, source compilation, RouteIR rendering, CapabilityIR projection, generator invocation, artifact emission, and `afterBuild`. |
+| Reachability/import resolution | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `reachableSourceFiles()`; [`framework/compiler/source-graph.mjs`](../../framework/compiler/source-graph.mjs), `resolveSourceImport()` | Starts from page entries, follows relative runtime imports/re-exports and validated Worker references, and excludes unreachable migration source. |
+| Ordered normalization | [`framework/compiler/normalization-pipeline.mjs`](../../framework/compiler/normalization-pipeline.mjs), `applyNormalizationPasses()`; [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `normalizeCompilerSource()` | Applies migration/resource passes in order and repairs TypeScript parent pointers after every pass. Imported source uses the same pipeline. |
 | Focused normalization passes | [`framework/compiler/`](../../framework/compiler/) | React, Router, browser signals, animation-frame refs, custom-hook timers, Zustand, and render control each validate and lower a narrow source shape. |
 | Shared AST/scope helpers | [`framework/compiler/ast-helpers.mjs`](../../framework/compiler/ast-helpers.mjs) | Binding, scope, reference, effect-return, and source-location analysis. |
 | Pure collection language | [`framework/compiler/collection-analysis.mjs`](../../framework/compiler/collection-analysis.mjs) | Analyzes collection roots/selectors and serializes the allowed pure expression language used by lists and derived dependencies. |
-| Main semantic analysis | `framework/build.mjs`, `createKudzuTransformer()` | Produces transformed source plus explicit component, handler, binding, derived, keyed, and effect ownership results. |
+| Main semantic analysis | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `createKudzuTransformer()` | Produces transformed source plus explicit component, handler, binding, derived, keyed, and effect ownership results. |
 | Component ownership analysis | [`framework/compiler/analysis/component-analysis.mjs`](../../framework/compiler/analysis/component-analysis.mjs) | Retains ordered JSON-safe owner and specialization records for state, setters, props, refs, IDs, direct signal links, and source provenance; AST identity remains private to its source-local session. |
 | Per-source descriptor registration | [`framework/compiler/descriptor-session.mjs`](../../framework/compiler/descriptor-session.mjs), `createSemanticArtifact()`, `createDescriptorSession()` | Keeps AST descriptors private during analysis, then finalizes deterministic JSON-safe HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, EffectIR, imports, and client roots into ModuleIR. |
 | Command IR and codegen | [`framework/compiler/optimize/command-specialization.mjs`](../../framework/compiler/optimize/command-specialization.mjs), [`framework/compiler/ir/module-ir.mjs`](../../framework/compiler/ir/module-ir.mjs), [`framework/compiler/codegen/command-codegen.mjs`](../../framework/compiler/codegen/command-codegen.mjs) | Supported command handlers specialize to JSON-safe ModuleIR, then emit the existing `__kBehavior` AST without changing route plans. |
-| Build module generation | `framework/build.mjs`, `compile()` | Runs TypeScript with the Kudzu transformer, writes build-executable modules to `.kudzu`, rejects surviving React/Router runtime references, and generates handler source when descriptors exist. |
+| Source compilation | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `compileSource()` | Runs TypeScript with the Kudzu transformer, rejects surviving React/Router references, and returns a JSON-safe project-relative build module, component analysis, ModuleIR, optional handler module, and imported assets without filesystem writes. |
 | Handler/evaluator lowering | [`framework/compiler/handler-lowering.mjs`](../../framework/compiler/handler-lowering.mjs) | Completes source-local callback/binding/list AST rewriting and diagnostics before the JSON-safe IR boundary. |
 | Handler module codegen | [`framework/compiler/handler-codegen.mjs`](../../framework/compiler/handler-codegen.mjs) | Renders finalized ordered imports and concatenates generated module-export source without TypeScript AST or semantic discovery. |
 | Effect analysis | [`framework/compiler/effect-analysis.mjs`](../../framework/compiler/effect-analysis.mjs) | Classifies ordered signal, derived, and keyed-item dependencies and validates cleanup-owned browser resources before EffectIR registration. |
 | Worker graph | [`framework/compiler/worker-compiler.mjs`](../../framework/compiler/worker-compiler.mjs) | Returns functional Worker rewrite results and JSON-safe EffectIR edges, validates relative graphs, emits content-hashed ESM, and resolves placeholders only for rendered effects. |
-| Build-time JSX execution | [`framework/core.mjs`](../../framework/core.mjs), `renderPage()` | Executes compiled pages/layouts, allocates deterministic route/layout ownership IDs, emits complete HTML, and returns the serializable route plan and capability booleans. |
-| Route capability projection | [`framework/compiler/route-capability-planner.mjs`](../../framework/compiler/route-capability-planner.mjs), `planRouteCapabilities()` | Purely folds rendered route plans and route facts into aggregate runtime/artifact requirements. |
+| Shared path conversion | [`framework/compiler/path-helpers.mjs`](../../framework/compiler/path-helpers.mjs) | Converts project-relative module, browser, asset, and base paths for build and development serving. |
+| Build-time JSX execution | [`framework/core.mjs`](../../framework/core.mjs), `renderPage()` | Executes compiled pages/layouts, allocates deterministic route/layout ownership IDs, emits complete HTML, and returns RouteIR v1 plus capability facts. |
+| Route capability projection | [`framework/compiler/route-capability-planner.mjs`](../../framework/compiler/route-capability-planner.mjs), `planRouteCapabilities()` | Validates RouteIR v1 and purely folds rendered plans and route facts into CapabilityIR v1. |
 | Effect entry generation | [`framework/compiler/effect-codegen.mjs`](../../framework/compiler/effect-codegen.mjs) | Generates ordinary, dependency, owned, and navigable effect entries from rendered descriptors. |
-| Runtime specialization/emission | `framework/build.mjs` | Selects runtime files and currently removes branches through feature booleans, string replacement, compile-time defines, and esbuild. |
+| Runtime generation | [`framework/compiler/runtime-codegen.mjs`](../../framework/compiler/runtime-codegen.mjs), [`framework/compiler/list-runtime-codegen.mjs`](../../framework/compiler/list-runtime-codegen.mjs), [`framework/compiler/param-codegen.mjs`](../../framework/compiler/param-codegen.mjs) | Consumes versioned contracts, specializes authored capability sources with fail-closed anchors, and returns source/define results without filesystem ownership. |
+| Artifact emission | `framework/build.mjs` | Selects required files from CapabilityIR and writes or bundles generated sources with esbuild. |
 | Browser capabilities | [`framework/*.js`](../../framework/) | Small optional modules for commands, bindings, lists, effects, native handlers, serialization, parameters, and navigation; no component runtime. |
 | Opt-in navigation | [`framework/navigation-runtime.js`](../../framework/navigation-runtime.js) plus `framework/build.mjs` navigation configuration/emission | Fetches and validates complete same-origin documents, replaces only the marked route range, manages route/layout disposal, history, focus, finite prefetch retention, and native fallback. |
 | Development serving | [`framework/dev-server.mjs`](../../framework/dev-server.mjs) and [`framework/dev-state.js`](../../framework/dev-state.js) | Rebuild/watch/SSE and response-only short-lived state restoration; never changes production `dist/`. |
@@ -35,20 +37,18 @@ This maps the EffectIR boundary prepared for `0.8.21`. File and function names a
 ```text
 src/pages entries + config
   -> project discovery and reachable relative graph
-  -> shared ordered source normalization
-  -> main transformer semantic analysis
-       -> transformed build-time TS/TSX
-       -> per-source semantic artifact
-  -> TypeScript transpilation
-       -> .kudzu executable modules
-       -> generated handler/effect/binding/list-evaluator modules
+  -> compileSource()
+       -> ordered normalization and main transformer semantic analysis
+       -> TypeScript transpilation
+       -> JSON-safe build module, ModuleIR, handler module, and imported assets
+  -> build orchestration writes .kudzu executable and handler modules
   -> import page modules and execute renderPage()
        -> complete HTML
-       -> serializable route plan
+       -> RouteIR v1
        -> referenced handler URLs and route facts
   -> remove unrendered handlers/effects/Workers
-  -> planRouteCapabilities(route plans, route facts)
-       -> aggregate capability manifest
+   -> planRouteCapabilities(RouteIR records, route facts)
+       -> CapabilityIR v1
   -> specialize and emit only selected runtime/capability ESM
   -> write route index.html, CSS/assets, Worker graphs, rewrites, and .kudzu/kudzu-plan.json
   -> optional afterBuild()
@@ -56,15 +56,15 @@ src/pages entries + config
 
 The browser consumes static HTML first. State seeds and descriptors in that HTML connect only to emitted command, binding, list, native-handler, effect, parameter, or navigation modules. Browser execution patches owned DOM directly; it does not invoke component functions or reconstruct a component tree.
 
-## Current Coupling To Remove
+## Residual Coupling
 
-- `createKudzuTransformer()` combines discovery, validation, specialization, descriptor registration, and transformed-source emission.
+- `createKudzuTransformer()` remains one large source-local analysis unit combining validation, specialization, descriptor registration, and transformed-source emission.
 - Transient component rewrite indexes remain source-local AST indexes; handler, binding, derived, keyed, effect, and component ownership now have explicit JSON-safe source results.
-- `build()` destructures a broad capability manifest into many booleans and performs artifact-specific source surgery.
-- Runtime specialization relies on exact source-string and regular-expression replacements in `framework/build.mjs`.
-- Route facts, rendered plans, artifact requirements, and emitted-file decisions are represented at adjacent but not fully explicit boundaries.
+- `build()` still owns explicit artifact selection and filesystem writes after generator results are produced.
+- Runtime generators intentionally specialize readable authored sources through exact anchors; every required anchor fails closed, but a future generator format may remove this transitional dependency.
+- Source reachability and source compilation share one module because both consume the same normalization and import graph contracts.
 
-Goal A addresses these couplings without changing source support, output semantics, or browser architecture.
+These are future simplification opportunities, not incomplete Goal A contracts. Goal A changed no source support, browser output semantics, or browser architecture.
 
 ## Continuation Checklist
 

package/docs/next-architecture/goal-a-compiler-foundation.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-The `0.8.21` EffectIR source-analysis seam is complete. Goal A continues with the planned `0.8.22` RouteIR, CapabilityIR, and architecture/output audit while preserving accepted React-shaped syntax, diagnostics, complete HTML, emitted capability behavior, and current public APIs.
+Goal A is complete in `0.8.23`. The no-write source compiler, ModuleIR source seams, RouteIR v1, CapabilityIR v1, focused runtime generators, and the architecture/output baseline preserve accepted React-shaped syntax, diagnostics, complete HTML, emitted capability behavior, and current public APIs.
 
 ## Target Boundaries
 
@@ -77,7 +77,7 @@ Analysis produces plain data:
 }
 ```
 
-The `0.8.21` source result adds deterministic EffectIR setup HandlerIR links, cleanup, ordered dependencies and subscriptions, DerivedIR references, component/keyed ownership, source provenance, and Worker edges beside the existing command, component, handler, binding, derived, and KeyedBlockIR results. Source-local effect AST analysis is consumed during lowering and does not cross this boundary. Final route/layout/conditional/keyed effect IDs and lifetime allocation remain authoritative in `core.mjs`; the existing route plan is not duplicated in ModuleIR.
+The completed source result contains deterministic command, component, HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, and EffectIR records. Source-local AST analysis is consumed during lowering and does not cross this boundary. Final route/layout/conditional/keyed IDs and lifetime allocation remain authoritative in `core.mjs`; no component tree or duplicate route plan exists.
 
 Source codegen lowers that data through the existing build ABI:
 
@@ -89,15 +89,15 @@ __kBehavior([["add", count, 1]])
 
 ### Source Result
 
-One source-local result owns transformed source plus the sparse ModuleIR, generated handler/effect/binding/list evaluator source, client imports, and explicit pass metadata. Worker ownership is recorded as EffectIR edges; AST-bearing data is consumed inside analysis/lowering and does not become IR or cross-build state.
+`compileSource()` returns one JSON-safe source-local result containing the project-relative build module, component analysis, sparse ModuleIR, optional generated handler/effect/binding/list evaluator module, and imported assets. It writes no files. Worker ownership is recorded as EffectIR edges; AST-bearing data is consumed inside analysis/lowering and does not become IR or cross-build state.
 
 ### Route Result
 
-`renderPage()` remains the build-time authority for complete HTML and ownership IDs. Its serializable plan remains the behavioral source for states, events, effects, bindings, conditions, lists, parameters, and search parameters. Route-level facts such as navigability and dependency-runtime selection accompany rather than mutate that plan.
+`renderPage()` remains the build-time authority for complete HTML and ownership IDs. Its existing plan is RouteIR v1, the behavioral source for states, events, effects, bindings, conditions, lists, parameters, and search parameters. Each state has a route-local numeric `slot`, its unchanged browser/DOM `id`, and readable `name` metadata used by development restoration. RouteIR slots are not ModuleIR signal slots or persistent browser identities. Route-level facts such as navigability and dependency-runtime selection accompany rather than mutate the plan.
 
 ### Artifact Plan
 
-A pure projection determines which shared runtimes, route entries, handler modules, Worker roots, and optional branches are required. Artifact generators consume that projection; they do not rediscover syntax or inspect application AST.
+CapabilityIR v1 determines shared runtime families and optional branches. Rendered RouteIR descriptors and ModuleIR references independently retain route entries, handler modules, and Worker reachability. Runtime, list, parameter, effect, and handler generators consume those explicit results; they do not rediscover TSX semantics or inspect application AST.
 
 ## Generator Strategy
 
@@ -122,17 +122,14 @@ No generator may analyze TSX, invent runtime component abstractions, or broaden
 - Preserve current runtime files until their corresponding generator has artifact parity.
 - Treat deterministic byte changes as review items even when tests pass.
 
-## Acceptance
-
-- Build orchestration reads as stage coordination rather than feature analysis or source generation.
-- Source normalization, semantic analysis, route planning, artifact planning, generation, and writing have explicit ownership.
-- Codegen consumes descriptors/manifests and does not discover compiler semantics.
-- No module-global mutable analysis state or new broad context object is added.
-- Static routes still emit complete HTML and zero JavaScript.
-- Interactive and navigation routes preserve capability selection, ownership, stale-write, and cleanup behavior.
-- Unreachable handlers, effects, package helpers, and Workers remain absent.
-- Diagnostics retain source file and location.
-- [`performance-gates.md`](./performance-gates.md) passes for every patch.
+## Acceptance Record
+
+- `build.mjs` decreased from 3,999 to 744 lines and coordinates discovery, JSON-safe source results, RouteIR rendering, CapabilityIR projection, generation, and writing without TSX feature analysis.
+- Source normalization, semantic analysis, ModuleIR and build-module generation, RouteIR rendering, CapabilityIR projection, generation, and writing have explicit ownership without a broad context object.
+- RouteIR and CapabilityIR reject unsupported versions; required runtime source anchors fail closed.
+- Static routes retain complete HTML and zero JavaScript; deploy output across the complete site and representative binding, list, effect, Worker, parameter, navigation, config, and package-handler fixtures is byte-identical to `v0.8.22`.
+- Interactive and navigation routes preserve capability selection, ownership, stale-write, and cleanup behavior; unreachable handlers, effects, package helpers, and Workers remain absent.
+- Diagnostics retain source file and location, and [`performance-gates.md`](./performance-gates.md) records no build or artifact-size regression.
 
 ## Non-Goals
 

package/docs/next-architecture/versioning.md

@@ -1,6 +1,6 @@
 # Planned Version Sequence
 
-This is an execution sequence, not release history. `0.8.16` through `0.8.21` are completed scopes represented by package/release records; later rows remain planned until their package version and release record exist.
+This is an execution sequence, not release history. `0.8.16` through `0.8.23` are completed scopes represented by package/release records.
 
 Keep each patch behavior-preserving and independently reviewable. If a boundary proves inseparable, revise this plan before combining releases; do not silently broaden a patch.
 
@@ -12,11 +12,12 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 | `0.8.19` | Promote native HandlerIR, BindingIR, and DerivedIR; codegen consumes results without rediscovering captures, states, reducers, imports, or pure expressions. | Command-only routes retain zero handler ESM; native/binding/package/reducer fixtures preserve output and diagnostics. |
 | `0.8.20` | Replace keyed-list AST side tables with an explicit KeyedBlock ownership result and typed existing list descriptor. | Insert/update/reorder/remove/nested/SVG identity and exact state/effect/ref release remain unchanged. |
 | `0.8.21` | Replace effect AST side tables with EffectIR covering setup, cleanup, dependencies, ownership, source, and Worker edges. | Route/layout/conditional/list lifetime, stale-write isolation, and exact resource cleanup remain unchanged. |
-| `0.8.22` | Version the existing RouteIR and CapabilityIR, formalize numeric slots plus readable debug metadata, and complete the Goal A architecture/output audit. | `build.mjs` coordinates stages rather than feature semantics; all fixtures, output gates, Chrome checks, and recorded baseline pass. |
+| `0.8.22` | Version the existing RouteIR and CapabilityIR, formalize numeric slots plus readable debug metadata, and extract focused runtime generators. | RouteIR and CapabilityIR reject unsupported versions; runtime generator contracts, output gates, and the recorded benchmark pass. |
+| `0.8.23` | Forward-fix Goal A by moving source normalization, semantic analysis, ModuleIR finalization, handler generation, and build-module generation behind one no-write source compiler result. | `build.mjs` contains no TSX feature analysis; source results are JSON-safe and project-relative; diagnostics, deploy bytes, tests, and build performance remain equivalent. |
 
 ## Sequence Rules
 
-- Do not start Goal B optimization before `0.8.22` Goal A acceptance and baseline recording.
+- Goal A is complete. Goal B optimization remains deferred until explicitly started from the recorded `0.8.23` baseline.
 - Keep Goal C research out of these patches and publish no store/resource API.
 - Keep Goal D behavior unchanged: complete HTML, native default, opt-in groups, no islands.
 - A planned patch may ship under a different actual version only if this table and release-facing documentation are updated before release.

package/framework/README.md

@@ -39,6 +39,7 @@ Reduced Zustand migration stores lower to one ordinary layout-lifetime state slo
 - `compiler/descriptor-session.mjs`: private source-local descriptor registration and deterministic JSON-safe HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, EffectIR, import, and client-root finalization.
 - `compiler/effect-analysis.mjs`: ordered effect dependency classification and cleanup-owned browser resource validation before EffectIR registration.
 - `compiler/normalization-pipeline.mjs`: ordered source normalization with parent-pointer repair after every compiler pass.
+- `compiler/param-codegen.mjs`: runtime pathname and search-parameter entry generation from rendered route descriptors.
 - `compiler/react-migration-pass.mjs`: React import, memo, callback, `forwardRef`, and `useId` migration validation and lowering.
 - `compiler/custom-hook-timer-pass.mjs`: private custom-hook timeout-ref validation and compiler-owned timer-state lowering.
 - `compiler/effect-codegen.mjs`: route-specific ordinary, owned, and navigable effect entry generation.
@@ -47,7 +48,9 @@ Reduced Zustand migration stores lower to one ordinary layout-lifetime state slo
 - `compiler/handler-codegen.mjs`: AST-free ordered import rendering and finalized handler/binding export-source assembly.
 - `compiler/render-control-pass.mjs`: render-function early-return and exhaustive adjacent-assignment normalization.
 - `compiler/router-pass.mjs`: React Router import validation and native Link, pathname parameter, search parameter, and imperative navigation lowering.
-- `compiler/route-capability-planner.mjs`: pure route-plan projection into runtime and artifact capability requirements.
+- `compiler/route-capability-planner.mjs`: RouteIR v1 validation and pure CapabilityIR v1 projection into runtime and artifact requirements.
+- `compiler/runtime-codegen.mjs`: fail-closed core, effect, binding, native, and navigation runtime generation from CapabilityIR.
+- `compiler/list-runtime-codegen.mjs`: fail-closed keyed-list runtime generation from CapabilityIR list/effect sections.
 - `compiler/worker-compiler.mjs`: relative TypeScript Worker candidate validation, effect rewriting, graph validation, and content-hashed ESM emission.
 - `compiler/zustand-pass.mjs`: reduced Zustand store analysis, diagnostics, and migration normalization.
 - `dev-server.mjs`: development HTTP server, source watching, rebuild serialization, SSE reloads, runtime-route fallback serving, and response-only state restoration injection.
@@ -65,7 +68,7 @@ Reduced Zustand migration stores lower to one ordinary layout-lifetime state slo
 - `dev-state.js`: dev-only, short-lived logical-state snapshot validation and restoration.
 - `*.d.ts`: public TypeScript and JSX declarations.
 
-Compiler ownership follows four explicit stages. `build.mjs` owns project discovery, route planning, and artifact emission. `compiler/normalization-pipeline.mjs` owns pass order and repairs parent pointers after every source transform; migration passes keep per-file state local and return additional metadata explicitly. The main transformer analyzes normalized source while `compiler/descriptor-session.mjs` owns one per-source semantic artifact containing HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, EffectIR, and client imports. Keyed blocks link deterministic parent/child sites, component specializations, row states/refs, and generated handlers/bindings without replacing `core.mjs` final DOM ownership. Effects link setup handlers, dependencies, cleanup, lexical/keyed ownership, provenance, and Worker edges without duplicating the rendered route plan. `compiler/collection-analysis.mjs` owns the shared pure collection language used by React migration, reactive expressions, effects, and keyed lists. After build-time rendering, `compiler/route-capability-planner.mjs` projects serializable route plans into one capability manifest consumed by runtime specialization and artifact emission. Codegen modules turn descriptors into route-specific ESM without participating in source analysis. The versioned continuation plan lives in `docs/next-architecture`; it adds no runtime or accepted syntax by itself.
+Compiler ownership follows explicit stages. `build.mjs` coordinates project discovery, source compilation, RouteIR rendering, CapabilityIR planning, generator calls, and artifact emission. `compiler/normalization-pipeline.mjs` owns pass order and parent repair. The main transformer analyzes normalized source while `compiler/descriptor-session.mjs` owns one per-source semantic artifact containing HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, EffectIR, and client imports. `core.mjs` emits complete HTML and RouteIR v1: route-local state `slot` is an internal array reference, `id` remains the browser/DOM identity, and `name` remains readable development metadata. `compiler/route-capability-planner.mjs` validates those plans and projects CapabilityIR v1. Focused codegen modules consume IR/descriptors and return route-specific source without source analysis or filesystem ownership. The completed architecture record lives in `docs/next-architecture`; it adds no runtime or accepted syntax by itself.
 
 New syntax support belongs in an existing pass or a focused new pass only when a reduced migration fixture proves it. Passes must preserve source-located diagnostics, avoid module-global analysis state, and expose metadata through return values rather than AST-identity side channels. Build orchestration stays in `build.mjs`; feature-specific graph validation or code generation moves under `compiler/` when it has a stable input/output boundary.