@kudzujs/core 0.8.15 → 0.8.17

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

@@ -0,0 +1,72 @@
+# Current Compiler Architecture
+
+This maps the completed `0.8.17` command ModuleIR boundary. File and function names are the stable references; line numbers are intentionally omitted because Goal A moves 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. |
+| 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()` | Still owns component specialization, hooks/state, effects, keyed-list ownership, imports, reactive JSX, and many AST-identity side tables. This is the largest remaining coupling. |
+| Per-source descriptor registration | [`framework/compiler/descriptor-session.mjs`](../../framework/compiler/descriptor-session.mjs), `createSemanticArtifact()`, `createDescriptorSession()` | Registers deterministic native handler, effect handler, binding, list evaluator, and client-import descriptors into one source-local artifact. |
+| 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. |
+| Handler/evaluator codegen | [`framework/compiler/handler-codegen.mjs`](../../framework/compiler/handler-codegen.mjs) | Converts descriptor AST into browser ESM exports and rewrites state, setter, reducer, capture, and imported-helper reads. It does not discover features. |
+| Worker graph | [`framework/compiler/worker-compiler.mjs`](../../framework/compiler/worker-compiler.mjs) | Validates the exact effect-owned Worker form, validates its relative graph, 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. |
+| 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. |
+| 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/`. |
+
+## Current Data Flow
+
+```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
+  -> import page modules and execute renderPage()
+       -> complete HTML
+       -> serializable route plan
+       -> referenced handler URLs and route facts
+  -> remove unrendered handlers/effects/Workers
+  -> planRouteCapabilities(route plans, route facts)
+       -> aggregate capability manifest
+  -> specialize and emit only selected runtime/capability ESM
+  -> write route index.html, CSS/assets, Worker graphs, rewrites, and .kudzu/kudzu-plan.json
+  -> optional afterBuild()
+```
+
+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
+
+- `createKudzuTransformer()` combines discovery, validation, specialization, descriptor registration, and transformed-source emission.
+- Component/effect/list relationships remain in `WeakMap`/`WeakSet` tables keyed by AST identity; they cannot be moved safely until replaced by explicit 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.
+
+Goal A addresses these couplings without changing source support, output semantics, or browser architecture.
+
+## Continuation Checklist
+
+- [ ] Re-read every caller before moving a helper out of `framework/build.mjs`.
+- [ ] Keep analysis results serializable where AST identity is not required.
+- [ ] Keep AST-bearing descriptors source-local and consume them before render planning.
+- [ ] Do not move tightly coupled code behind a large context object merely to reduce file size.
+- [ ] Compare route plans and emitted artifacts before and after each extraction.

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

@@ -0,0 +1,154 @@
+# Goal A: Compiler Foundation
+
+## Status
+
+The `0.8.17` command vertical slice is complete. Goal A continues with the planned `0.8.18` state/props/component analysis result while preserving accepted React-shaped syntax, diagnostics, complete HTML, emitted capability behavior, and current public APIs.
+
+## Target Boundaries
+
+```text
+project/build session
+  -> normalized source result
+  -> analyzed source result + transformed build module
+  -> rendered route plan
+  -> pure capability/artifact plan
+  -> generated artifact sources
+  -> filesystem emission
+```
+
+Each arrow needs a concrete input/output contract. A file split without a reduced dependency surface does not count.
+
+## Minimum Kudzu IR
+
+Goal A adds only the representation missing between normalized TypeScript AST and generated Kudzu core calls. It does not duplicate the existing serializable route plan or model a component tree.
+
+```js
+{
+  version: 1,
+  file: "src/pages/counter.tsx",
+  signals: [],
+  handlers: [],
+  bindings: [],
+  derived: [],
+  effects: [],
+  keyedBlocks: [],
+  clientImports: [],
+  sourceLocations: []
+}
+```
+
+The active IR boundary must be JSON-safe. No `ts.Node`, `Map`, `Set`, `WeakMap`, function, closure, or Symbol crosses from analysis into optimization/codegen. Temporary AST identity remains an analyzer implementation detail until a feature receives an explicit result.
+
+Existing representations are promoted rather than copied:
+
+| Required concept | Canonical direction |
+|---|---|
+| `KudzuProgram` | Module, route, capability, and reference closure assembled only after the parts are explicit. |
+| `RouteIR` | Version the existing `renderPage().plan`; do not add a second route plan. |
+| `SignalIR` | Type the existing state descriptor and add an internal numeric slot plus readable debug metadata. |
+| `HandlerIR` | Plain command data or a stable generated-module export reference. |
+| `BindingIR` | Promote existing binding descriptors. |
+| `DerivedIR` | Reuse the existing tagged Collection Expression IR. |
+| `EffectIR` | Replace effect AST side tables with one explicit result when that seam is ready. |
+| `KeyedBlockIR` | Promote the existing list descriptor after ownership analysis is explicit. |
+| `CapabilityIR` | Reuse the current pure route capability manifest. |
+
+A JSX tree, VDOM, component IR, retained component identity, or general expression VM is not part of Goal A.
+
+## First Vertical Slice
+
+The existing command fixture is the first real `TSX -> IR -> optimization -> existing codegen` path:
+
+```tsx
+const [count, setCount] = useState(0)
+return <button onClick={() => setCount(count + 1)}>{count}</button>
+```
+
+Analysis produces plain data:
+
+```js
+{
+  signals: [{ slot: 0, key: "state:0:count", debugName: "count" }],
+  handlers: [{
+    slot: 0,
+    kind: "commands",
+    commands: [{ operation: "add", signal: 0, value: 1 }]
+  }]
+}
+```
+
+The `0.8.17` slice intentionally records only lexical signal identity and command handlers. Initial values, state scope, bindings, derived values, effects, and keyed blocks join ModuleIR in their later planned patches; `core.mjs` remains authoritative for those values today.
+
+Source codegen lowers that data through the existing build ABI:
+
+```js
+__kBehavior([["add", count, 1]])
+```
+
+`core.mjs` remains responsible for final route/layout state IDs, complete HTML, `data-k-*` descriptors, and the route plan. The generated HTML, command runtime, plan, and asset set must remain byte-identical. The command route must not gain handler, native, effect, binding, list, or serialization modules.
+
+### Source Result
+
+One source-local result owns transformed source plus the sparse ModuleIR, generated handler/effect/binding/list evaluator source, client imports, Worker references, and explicit pass metadata. AST-bearing data is consumed inside analysis/codegen 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.
+
+### 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.
+
+## Generator Strategy
+
+Use the smallest generator that removes fragile source surgery:
+
+- Keep authored browser capability modules as readable JavaScript.
+- Give each generated artifact one focused generator function with an explicit manifest subset and deterministic output.
+- Prefer composing imports, constants, and named source sections over a general template engine or code-generation IR.
+- Move existing specialization in behavior-preserving slices; do not rewrite all runtimes at once.
+- Let esbuild perform syntax lowering, dead-code elimination, bundling, defines, and minification after Kudzu chooses the capability branches.
+- Preserve stable path names where they are public output behavior; preserve content-hashed Worker/chunk naming.
+- Assert that requested source sections exist before replacing/removing them during transition. The end state must not depend on incidental whitespace or entire function-body string matches.
+
+No generator may analyze TSX, invent runtime component abstractions, or broaden the capability contract.
+
+## Execution Rules
+
+- One patch, one boundary, with no migration feature mixed in.
+- Extract only code whose callers and outputs are understood.
+- Replace AST side tables only when an explicit keyed result can preserve ownership and source diagnostics.
+- Keep `build()` as orchestration; do not replace it with a service container or plugin framework.
+- 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.
+
+## Non-Goals
+
+- New React compatibility, hooks, routing, state, resource, or Worker forms.
+- A compiler plugin API, full JSX/component-tree IR, template framework, or dependency-injection layer.
+- Rewriting `framework/core.mjs` into a browser renderer.
+- Optimizing browser hot paths before Goal A establishes a comparable baseline.
+- React islands, hydration, or component serialization.
+
+## Continuation Checklist
+
+- [ ] Confirm the next planned version in [`versioning.md`](./versioning.md).
+- [ ] Write down the current producer, consumer, and artifact before changing the boundary.
+- [ ] Add or retain the smallest parity check that catches descriptor/plan/output drift.
+- [ ] Compare representative static, command, binding, list, effect, Worker, runtime-parameter, and navigation outputs.
+- [ ] Record raw/gzip and build measurements under the protocol in [`performance-gates.md`](./performance-gates.md).
+- [ ] Mark a patch complete only after behavior and output gates pass.
+- [ ] Delete the previous AST-valued representation when an IR path lands; never maintain both indefinitely.
+- [ ] Preserve descriptor allocation order and final state IDs unless a versioned output change is explicitly approved.

package/docs/next-architecture/goal-b-optimization-benchmarks.md

@@ -0,0 +1,59 @@
+# Goal B: Optimization Benchmarks
+
+## Status
+
+Deferred until Goal A is complete. Do not combine optimization with the compiler-boundary patches: structural movement would invalidate attribution and make output drift harder to review.
+
+## Purpose
+
+Use matched fixtures to identify measured build, output, or browser losses after the new boundaries are stable. Goal B is evidence-led optimization, not an architecture rewrite or a framework leaderboard.
+
+## Baseline
+
+At Goal A completion, record one source revision and the current maintained fixtures for:
+
+- clean build time;
+- emitted file list and deterministic hashes where applicable;
+- HTML, CSS, raw/gzip JavaScript, and Worker bytes;
+- static zero-JavaScript routes;
+- command update, reactive binding, keyed list update/reorder/removal, dependency effect, and enhanced navigation;
+- repeated ownership cycles and heap trend.
+
+Historical figures in [`PERFORMANCE.md`](../../PERFORMANCE.md) and the top-level Goal records are provenance, not an automatic current baseline. Reproduce a fixture before using it to approve work.
+
+## Candidate Order
+
+1. Profile the largest measured loss in a maintained fixture.
+2. Separate analysis/build cost, transfer bytes, startup, selector evaluation, DOM mutation, and ownership cleanup.
+3. Change the narrowest shared path responsible for the loss.
+4. Keep the change only if repeated measurements clear the materiality rule and correctness gates.
+
+Known historical pressure points include large keyed-list removal/reconciliation and broad runtime specialization, but neither is authorized without a reproduced current loss.
+
+## Benchmark Contract
+
+- Match visible content, behavior, errors, accessibility, and navigation semantics.
+- Disclose static HTML versus CSR/SSR architecture differences.
+- Use one warm-up and at least seven interleaved production builds.
+- Use rotating fresh browser profiles and more runs when ranges overlap.
+- Record environment, source revision, raw arrays, medians, min/max or distributions, artifacts, and limitations.
+- A repeatable browser median change above 5% is material; deterministic byte growth is always reviewed.
+
+## Rejection Rules
+
+Reject an optimization that:
+
+- removes complete initial HTML or zero-JavaScript exclusion;
+- changes DOM identity, state lifetime, cleanup, stale-write, focus, history, or native fallback semantics;
+- introduces a retained tree, scheduler, cache, generalized runtime, or public API;
+- wins by omitting matched behavior or accessibility;
+- cannot be reproduced outside profiler instrumentation.
+
+## Continuation Checklist
+
+- [ ] Verify Goal A acceptance is complete.
+- [ ] Freeze and record the post-Goal-A baseline revision.
+- [ ] Select one measured loss, not a speculative hotspot.
+- [ ] Add one minimal benchmark or reuse a maintained one.
+- [ ] Record before/after raw arrays and artifacts.
+- [ ] Revert experiments that do not clear correctness and materiality gates.

package/docs/next-architecture/goal-c-state-resource-research.md

@@ -0,0 +1,50 @@
+# Goal C: State And Resource Research
+
+## Status
+
+Research only. There is no approved public store API, resource API, cache API, query API, scheduler, or runtime proposal.
+
+## Existing Model
+
+Kudzu already has compiler-owned state slots and explicit ownership:
+
+| Owner | Lifetime | Existing examples |
+|---|---|---|
+| Document | Full non-persisted document | global disposal and document listeners |
+| Layout | One enhanced-navigation group session | explicitly shared state/effects |
+| Route | Current complete-document route range | parameters, requests, route effects/state |
+| DOM range/key path | Conditional or keyed ownership | row state/effects/refs and nested resources |
+
+`framework/core.mjs` allocates ownership IDs and serializable plans at build time. Browser runtimes hold only logical state and direct DOM/lifecycle registrations needed by emitted capabilities. Effects own browser resources and cleanup; stale invocations are invalidated before replacement.
+
+## Research Questions
+
+- Which real migration cannot be expressed with build-time data, ordinary state, layout ownership, route ownership, or one effect-owned browser resource?
+- Is the missing behavior compile-time specialization, lifetime declaration, deduplication, persistence, or request coordination?
+- Can a reduced conventional React fixture retain familiar source without shipping a public resource abstraction?
+- What exact cancellation, stale-result, error, retry, disposal, navigation, and BFCache semantics are required?
+- Can the capability be absent from unrelated routes and avoid a shared cache/scheduler?
+
+## Required Evidence
+
+Before any proposal, provide:
+
+- a real application or reduced conventional React fixture that fails today;
+- the smallest unsupported source shape and current diagnostic;
+- data timing and required owner lifetime;
+- behavior for success, empty, failure, retry, replacement, unmount, navigation, and late completion;
+- output and ownership costs;
+- an explanation of why existing async build rendering, state/effects, layout ownership, native platform storage, or effect-owned resources are insufficient.
+
+## Decision Boundary
+
+Research may produce notes, fixtures, measurements, or a narrow compiler-specialization proposal. It must not publish `createStore`, `resource`, `query`, cache, Provider, subscription, or scheduler APIs. A public API requires separate approval after at least two independent migration fixtures establish the same semantics and after zero-cost exclusion is demonstrated.
+
+## Continuation Checklist
+
+- [ ] Keep Goal C out of Goal A implementation patches.
+- [ ] Start with a failing migration fixture, not API design.
+- [ ] Classify build-known, browser-only, layout-owned, route-owned, and DOM-owned data.
+- [ ] Test existing compiler capabilities before proposing a new one.
+- [ ] Record unresolved semantics instead of filling them with a generic runtime.
+- [ ] Stop at research unless a separate implementation decision is approved.

package/docs/next-architecture/goal-d-routing-compatibility-decisions.md

@@ -0,0 +1,51 @@
+# Goal D: Routing Compatibility Decisions
+
+## Status
+
+Preserve the current model. Goal D records decisions; it does not authorize a new router.
+
+## Current Decision
+
+Every emitted route is a complete HTML document. Native document navigation is the default. `kudzu.config` may explicitly group emitted routes sharing one layout identity for same-document enhancement; routes outside a group, cross-group links, unsupported matches, modified clicks, downloads, external links, failures, and redirects retain or fall back to native behavior.
+
+Supported React Router-shaped migration remains narrow:
+
+- static root-relative `Link` lowers to a base-prefixed native `<a>`;
+- bracket runtime routes may lower direct `useParams()` to the pathname reader;
+- top-level direct `useSearchParams()` reads/writes lower to URL signals and native history;
+- direct nested `useNavigate()` calls lower to native `location.assign()` or `location.replace()`;
+- no React Router package executes in build output or the browser.
+
+## Enhanced Navigation Contract
+
+[`framework/navigation-runtime.js`](../../framework/navigation-runtime.js) receives one generated record set per configured group. It:
+
+- intercepts only eligible same-origin group anchors;
+- prefetches complete HTML into a finite link-derived cache;
+- validates application, layout, route markers, and same-origin capability assets;
+- disposes route ownership before replacing the marked route range;
+- retains layout ownership for the group session;
+- initializes pathname/search state before route effects mount;
+- updates history, managed head elements, focus, scroll, and live status;
+- aborts/suppresses superseded transitions and falls back to native navigation on failure.
+
+No fragment protocol, route component registry, browser route render, or application-wide router is implied.
+
+## React Islands Decision
+
+React islands remain blocked under current invariants. An island requires React execution, hydration or client rendering, a retained component tree, duplicated ownership semantics, and non-capability-specific runtime bytes. That conflicts with zero JavaScript for static routes, direct DOM ownership, compiler-specialized handlers/effects, and the prohibition on React/VDOM/hydration.
+
+Do not add an `island`, `client:*`, hydration boundary, serialized props protocol, or React package exception. Reconsideration requires an explicit product-invariant change, not a routing compatibility patch.
+
+## Revisit Evidence
+
+Routing behavior may be reconsidered only when a real migration fixture proves that complete documents plus native anchors and current opt-in groups cannot meet required behavior. The proposal must cover direct entry, reload, back/forward, base paths, query/hash, accessibility, failure fallback, ownership cleanup, static-route output, and route-specific bytes.
+
+## Continuation Checklist
+
+- [ ] Preserve complete route HTML during Goal A.
+- [ ] Keep navigation group configuration explicit and validated.
+- [ ] Compare exact/runtime route matching and overlap diagnostics after generator changes.
+- [ ] Verify ungrouped and cross-group links remain native.
+- [ ] Verify route cleanup precedes replacement and layout cleanup occurs on non-persisted exit.
+- [ ] Reject islands or SPA routing unless product invariants are explicitly changed first.

package/docs/next-architecture/performance-gates.md

@@ -0,0 +1,50 @@
+# Performance And Output Gates
+
+These gates apply to every Goal A patch and later optimization work.
+
+## Output Parity
+
+- Unaffected static routes emit complete HTML and zero JavaScript.
+- Build-known route content remains in HTML rather than moving behind browser execution.
+- Unused command, binding, list, effect, native, parameter, navigation, package-helper, and Worker capabilities remain absent.
+- Route plans and `.kudzu/kudzu-plan.json` rewrites retain equivalent serializable meaning and deterministic ordering.
+- Worker entries remain content-hashed, deterministic across unchanged builds, base-aware, and absent unless a rendered effect references them.
+- Generated module paths, preload closure, CSS/assets, and navigation group assets change only deliberately.
+- React and `react-router-dom` references never survive in build-executable or browser output.
+
+## Behavioral Parity
+
+- State setters remain logically synchronous with DOM commits batched at synchronous-turn boundaries.
+- Bindings and conditions patch direct DOM without rerendering components.
+- Keyed rows preserve retained identity and release state/effects/refs on removal.
+- Dependency effects compare with `Object.is`, clean up before rerun, and reject stale writes.
+- Document, layout, route, conditional, and keyed ownership dispose exactly once.
+- Enhanced navigation preserves direct entry, reload, back/forward, base, query/hash, focus, scroll, head updates, native fallback, and stale-transition suppression.
+
+## Measurement Protocol
+
+For each planned patch:
+
+1. Record source revision, OS/hardware, Node/npm, browser when applicable, fixture, and command.
+2. Run one clean production warm-up followed by at least seven interleaved measured builds when comparing revisions.
+3. Use rotating fresh browser profiles; increase samples when ranges overlap.
+4. Record raw arrays, medians, raw/gzip bytes by artifact class, complete emitted file lists, and known limitations.
+5. Compare representative static, command-only, binding/conditional, keyed-list, effect, Worker, runtime-parameter, and navigation routes.
+
+## Review Thresholds
+
+- Any unexpected deterministic byte or file-list change requires explanation.
+- A repeatable browser median regression above 5% is material.
+- Build-time changes above 5% are material when interleaved ranges establish the difference.
+- Smaller changes still block when they violate zero-cost exclusion, determinism, identity, cleanup, or complete-HTML behavior.
+- Cross-framework claims require matched content, behavior, accessibility, and explicit architecture caveats.
+
+## Patch Gate
+
+- [ ] Relevant focused tests pass.
+- [ ] `npm run check` passes.
+- [ ] `npm test` passes.
+- [ ] Representative emitted file lists are compared.
+- [ ] Raw/gzip deltas are recorded and explained.
+- [ ] Browser ownership/navigation checks run when affected.
+- [ ] No result is presented as a release until package version, release notes, and release process actually establish it.

package/docs/next-architecture/versioning.md

@@ -0,0 +1,42 @@
+# Planned Version Sequence
+
+This is an execution sequence, not release history. `0.8.16` and `0.8.17` are completed scopes represented by package/release records; later rows remain planned until their package version and release record exist.
+
+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.
+
+| Planned patch | Scope | Completion evidence |
+|---|---|---|
+| `0.8.16` | Finish source-local descriptor, collection, command, capability, and Zustand analysis boundaries; publish the current architecture and continuation packet. | Existing descriptor order, diagnostics, transformed modules, route plans, output bytes, and benchmark graphs remain equivalent. |
+| `0.8.17` | Add the sparse JSON-safe ModuleIR and move the Counter command fast path from generated AST to plain Command IR before lowering through existing codegen. | Exact command IR round-trip and byte-identical Counter module, HTML, plan, and asset set. |
+| `0.8.18` | Produce explicit state, setter, props, ref, ID, and component-specialization results without changing final state allocation. | Repeated, conditional, imported, setter-adapter, Context, and reducer component ownership remains identical. |
+| `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. |
+
+## Sequence Rules
+
+- Do not start Goal B optimization before `0.8.22` Goal A acceptance and baseline recording.
+- 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.
+- Release notes describe completed facts; this file continues to describe future work.
+- Internal decomposition alone does not require `0.9.0`; use a minor only for a public compiler/tooling or compatibility boundary.
+
+## Generator Versions
+
+Keep `create-kudzu@0.1.101` while its template remains unchanged. Its `@kudzujs/core` range `^0.8.15` already accepts every planned Goal A patch. Publish `0.1.102` only when the template or minimum core range changes; a future `0.9.0` template must use `^0.9.0`.
+
+## Release Boundary
+
+Every patch is independently revertible before publication. After npm publication, never repoint its tag; forward-fix with the next patch. Require the exact commit to pass CI, package smoke installation, registry verification, and the performance gates before starting the next ownership seam.
+
+## Per-Patch Continuation Checklist
+
+- [ ] Confirm all earlier planned patches are complete or explicitly replanned.
+- [ ] Inspect current uncommitted changes and preserve unrelated work.
+- [ ] Name the exact producer/consumer boundary being changed.
+- [ ] Keep source support and public runtime behavior unchanged.
+- [ ] Apply [`performance-gates.md`](./performance-gates.md).
+- [ ] Update current architecture mapping when responsibility actually moves.
+- [ ] Update `RELEASES.md` only as part of a real release, never from this plan alone.

package/framework/README.md

@@ -34,14 +34,19 @@ Reduced Zustand migration stores lower to one ordinary layout-lifetime state slo
 - `compiler/ast-helpers.mjs`: shared TypeScript AST traversal, scope, binding, effect-return, and source-location helpers used by compiler passes.
 - `compiler/animation-frame-pass.mjs`: effect-owned animation-frame ref validation and plain mutable effect-scope lowering.
 - `compiler/browser-signal-passes.mjs`: static media-query external-store and navigator capability-condition normalization.
+- `compiler/collection-analysis.mjs`: pure collection expression IR, selector pipeline, alias, and imported-transform analysis.
+- `compiler/descriptor-session.mjs`: per-source semantic artifact creation and deterministic command, handler, effect, binding, and list evaluator descriptor registration.
 - `compiler/normalization-pipeline.mjs`: ordered source normalization with parent-pointer repair after every compiler pass.
 - `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.
+- `compiler/optimize/command-specialization.mjs`, `compiler/ir/module-ir.mjs`, and `compiler/codegen/command-codegen.mjs`: JSON-safe command analysis, sparse per-source ModuleIR, and source-analysis-free existing behavior-call generation.
 - `compiler/handler-codegen.mjs`: route-specific native handler, reactive binding, keyed-list evaluator, and client-import module source generation.
 - `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/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.
 - `core.mjs`: server-side JSX rendering, state slots, context providers, behavior metadata, and serializable capture validation.
 - `jsx-runtime.mjs`: automatic JSX runtime used by TypeScript.
@@ -57,7 +62,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, capability selection, 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 into handler, effect, binding, and list descriptors. The codegen modules turn those descriptors into route-specific ESM without participating in source analysis.
+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 handler, effect, binding, list, and client-import descriptors. `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.
 
 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.