@kudzujs/core 0.8.37 → 0.8.38

package/MIGRATION_ROADMAP.md

@@ -2,7 +2,7 @@
 
 This document is the source of truth for Kudzu's product direction, architecture invariants, and future development order. Read it before extending React-shaped syntax or browser capabilities.
 
-The executable post-`0.8.37` compiler and large-application sequence is maintained in [`docs/next-architecture/large-application-ai-native-roadmap.md`](./docs/next-architecture/large-application-ai-native-roadmap.md). Follow its PR dependencies for implementation work; this document remains authoritative when selecting or accepting a migration capability.
+The executable post-`0.8.38` compiler and large-application sequence is maintained in [`docs/next-architecture/large-application-ai-native-roadmap.md`](./docs/next-architecture/large-application-ai-native-roadmap.md). Follow its PR dependencies for implementation work; this document remains authoritative when selecting or accepting a migration capability.
 
 [`GOAL_A.md`](./GOAL_A.md) and [`GOAL_B.md`](./GOAL_B.md) are completed capability-validation records. Their commerce and realtime dashboard fixtures prove general lifecycle, navigation, async-workflow, and Worker capabilities; they are not separate product verticals or future priority lists.
 

package/PERFORMANCE.md

@@ -2,6 +2,31 @@
 
 Reproducibility classes: `npm run benchmark`, `npm run benchmark:keyed`, `npm run benchmark:native`, and `npm run benchmark:module-cache` are maintained in this repository; `npm run benchmark:commerce` is a maintained paired runner over the public external storefront; older excluded-workspace sections are historical provenance only and are not current framework rankings.
 
+## P0.11 Structural Route Artifact Graph
+
+Measured UTC 2026-08-11 on the Intel Core i5-9500 Linux x64 host with 6 physical cores, Node 24.14.0, and npm 11.9.0. The baseline was clean tag `v0.8.37` at `8b4e8850c40f2856216e43f23ad02ada8434eb37`. The focused implementation files had SHA-256 `1a93b7fff5d80f271c588f89486a47dc262427195a6a768fe392be949eb99b5e`, produced by:
+
+```bash
+sha256sum framework/build.mjs framework/compiler/route-build-record.mjs framework/compiler/route-capability-planner.mjs framework/core.mjs framework/core.d.ts test/compiler-passes.test.mjs | sha256sum
+```
+
+The repository's 152-page build used one warm-up and seven alternating clean fresh-process samples. Every sample produced the same 173-file deploy graph, 3,835,970 raw bytes, 1,979,875 aggregate gzip bytes, and SHA-256 `c1f95f25d43589b61d1abe7ecf256e5b5e9dddd5647fbcf6368c08cc5ae3ee20`. Baseline and candidate `kudzu-plan.json` files are byte-identical.
+
+| Target | Clean build median | Range | Peak RSS median | Deploy bytes |
+|---|---:|---:|---:|---:|
+| `v0.8.37` | 1,820.186 ms | 1,769.592-1,910.670 ms | 351.6 MiB | 3,835,970 B |
+| P0.11 candidate | 1,804.568 ms | 1,756.849-1,843.941 ms | 351.4 MiB | 3,835,970 B |
+
+The candidate's unpaired median is 0.86% lower. Round-paired candidate-minus-baseline differences had a -20.933 ms median, with the candidate faster in five of seven pairs and the baseline faster in two. Timing ranges overlap, so no material improvement is claimed; peak-RSS medians differ by 0.3 MiB.
+
+```text
+v0.8.37: [1786.548,1834.792,1910.670,1853.493,1820.186,1769.592,1778.201]
+candidate: [1756.849,1804.568,1843.941,1832.560,1811.390,1798.756,1782.132]
+paired candidate-baseline: [-29.698,-30.225,-66.729,-20.933,-8.796,29.164,3.930]
+```
+
+RouteBuildRecord now owns each rendered route's RouteIR, capabilities, entry paths, styles, and exact handler/effect edges. Handler, Worker, package-client, and chunk closure starts from those structural edges instead of serialized HTML/plan searches or formatted effect keys. This changes build-scratch orchestration only; browser runtime source, RouteIR v1, CapabilityIR v1, emitted files, and deploy bytes remain unchanged.
+
 ## P0.10 Structural ModuleIR References
 
 Measured UTC 2026-08-11 on an Apple M4 macOS arm64 host with 10 logical CPUs, 16 GiB RAM, Node 24.14.0, and npm 11.9.0. The baseline was clean tag `v0.8.36` at `268cd9023c9f47a912601f298963a9ffe9c00da2`. The compiler and focused-check patch had SHA-256 `f684c79027b290bc8c7d549667ef0d7f21a9d0057b5d6291fcce18b91947eff2`, produced by:

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.37 - Structural ModuleIR references.** Compiler ownership and dependency edges now use validated source-local slots and stable symbols instead of formatted names. Read the [release notes](./RELEASES.md#0837---structural-moduleir-references), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.37), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.8.38 - Structural route artifacts.** Handler, effect, Worker, CSS, package-client, and chunk retention now follows validated per-route artifact edges instead of serialized output searches. Read the [release notes](./RELEASES.md#0838---structural-route-artifacts), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.38), 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,36 @@
 # Kudzu Releases
 
+## 0.8.38 - Structural route artifacts
+
+Kudzu 0.8.38 completes P0.11 by replacing serialized route-output searches and parallel route facts with one validated RouteBuildRecord artifact graph.
+
+### Changed in 0.8.38
+
+- Each emitted route records its RouteIR, capability facts, route-entry paths, styles, and exact handler/effect references.
+- Final event, effect, binding, conditional, and keyed-list descriptors retain handler references only when they are rendered.
+- Handler modules resolve by exact module URL, and Worker references resolve by structural module/handler pairs instead of formatted keys.
+- CSS output, package-client compilation, and bundle entry/chunk closure derive from retained route edges.
+- CapabilityIR now folds RouteBuildRecord values directly; serialized HTML/plan `includes()` searches and parallel route capability/entry arrays are removed.
+
+### Performance
+
+- Seven alternating clean 152-page builds measured `v0.8.37` and candidate medians of 1,820.186 ms and 1,804.568 ms. The -20.933 ms paired median and overlapping ranges establish no material speedup or regression.
+- Peak RSS medians were 351.6 MiB and 351.4 MiB.
+- Both targets emit the same 173 files, 3,835,970 raw bytes, 1,979,875 aggregate gzip bytes, deploy digest, and byte-identical `kudzu-plan.json`.
+
+### Validation
+
+- `npm run check`, `npm test`, and `npm run test:package` pass with all 200 tests and 153 generated pages.
+- Focused checks reject unsupported versions, malformed and duplicate references, missing handler modules, inconsistent route entries, and invalid JSON round trips.
+- Existing static, command, binding, keyed, effect, Worker, package-import, navigation, and migration fixtures retain their browser behavior and zero-unused-runtime checks.
+- P0.12 deep RouteIR and CapabilityIR validation is next.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.38
+```
+
 ## 0.8.37 - Structural ModuleIR references
 
 Kudzu 0.8.37 completes P0.10 by replacing mixed state names, export strings, formatted owner keys, and partial slots with one validated structural reference graph.

package/docs/next-architecture/README.md

@@ -11,7 +11,7 @@ The top-level [`GOAL_A.md`](../../GOAL_A.md) and [`GOAL_B.md`](../../GOAL_B.md)
 | 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 |
 
-The active post-`0.8.37` implementation sequence is [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md). P0.10 ModuleIR reference unification is complete; P0.11 explicit route artifact graph is next. The plan orders compiler semantic generalization, large-application foundations, compatibility boundaries, AI tooling, and production validation without changing the invariants below.
+The active post-`0.8.38` implementation sequence is [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md). P0.11 explicit route artifact graph is complete; P0.12 deep RouteIR and CapabilityIR validation is next. The plan orders compiler semantic generalization, large-application foundations, compatibility boundaries, AI tooling, and production validation without changing the invariants below.
 
 ## Required Invariants
 

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

@@ -1,6 +1,6 @@
 # Current Compiler Architecture
 
-This maps the current `0.8.37` architecture, built on 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.
+This maps the current `0.8.38` architecture, built on 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
 
@@ -9,7 +9,7 @@ This maps the current `0.8.37` architecture, built on the completed `0.8.23` Goa
 | CLI entry | [`bin/kudzu.mjs`](../../bin/kudzu.mjs) | Dispatches build and development commands. |
 | Project session | [`framework/compiler/project-session.mjs`](../../framework/compiler/project-session.mjs), `createProjectSession()` | Owns one absolute root, standard project paths, source records, bound graph operations, and Worker compiler for a build. Omitted roots resolve from call-time CWD. |
 | Parsed module cache and symbols | [`framework/compiler/project-session.mjs`](../../framework/compiler/project-session.mjs) | Parses each unchanged source module once per ProjectSession and records source-local declaration/import/re-export sites. Stable ModuleSymbol records resolve direct, aliased, barrel, and `export *` exports with cycle and ambiguity checks; repeated resolutions are cached against their source dependencies, and normalization consumers locate the resolved SiteId in a fresh clone with independent parent links. |
-| Build orchestration | [`framework/build.mjs`](../../framework/build.mjs), `build()` | Coordinates config, discovery, source compilation, RouteIR rendering, CapabilityIR projection, generator invocation, artifact emission, and `afterBuild`. |
+| Build orchestration | [`framework/build.mjs`](../../framework/build.mjs), `build()` | Coordinates config, discovery, source compilation, RouteBuildRecord collection, 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), `ordinaryRuntimeDependencies()`, `resolveSourceImport()` | Starts from page entries, follows relative runtime imports/re-exports and validated Worker references, excludes unreachable migration source, and fails unresolved ordinary edges or dynamic imports at the importer source location before code generation. |
 | 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 structural change. 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. |
@@ -19,6 +19,7 @@ This maps the current `0.8.37` architecture, built on the completed `0.8.23` Goa
 | 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) | Produces ComponentAnalysis v2 with ordered JSON-safe owner and specialization slots for state, setters, props, refs, IDs, direct SignalIR links, structural OwnerRefs, source-local SiteIds, 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 ModuleIR v2 with deterministic SymbolRef, SignalIR, HandlerIR, BindingIR, DerivedIR, EffectIR, KeyedBlockIR, and ImportIR slots. One fail-closed boundary validates every source-local and component ownership edge before build-module generation. |
+| Route artifact graph | [`framework/compiler/route-build-record.mjs`](../../framework/compiler/route-build-record.mjs), `createRouteBuildRecord()`, `planRouteArtifacts()` | Validates each rendered route's RouteIR, capabilities, entry paths, styles, and exact handler/effect references. Handler modules, Workers, package-client modules, and bundle entry/chunk closure derive from structural edges without serialized output searches or formatted composite keys. |
 | 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) | Direct commands use the existing fast path; proven immutable state aliases and one-call local helpers specialize to the same JSON-safe command ModuleIR. Recursion, escape, mutation, and dynamic helper dispatch fail explicitly, while unrelated handlers retain native ESM. Codegen emits the existing `__kBehavior` AST and command ABI. |
 | 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. |
@@ -26,11 +27,11 @@ This maps the current `0.8.37` architecture, built on the completed `0.8.23` Goa
 | 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. |
 | 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. |
+| 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 and exact retained handler references. |
+| Route capability projection | [`framework/compiler/route-capability-planner.mjs`](../../framework/compiler/route-capability-planner.mjs), `planRouteCapabilities()` | Validates RouteBuildRecord and RouteIR v1, then purely folds their plans and capability 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 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, writes route HTML in bounded batches, writes and bundles the complete generation in a project-local staging sibling, copies public subtrees without replacing generated paths, runs `afterBuild`, then promotes with rollback so failed builds preserve the prior `dist`. Byte-identical native, parameter, and effect route entries reuse one exact-source transform result within the current build only. |
+| Artifact emission | `framework/build.mjs` | Selects route artifacts from RouteBuildRecord edges and shared runtimes from CapabilityIR, writes route HTML in bounded batches, writes and bundles the complete generation in a project-local staging sibling, copies public subtrees without replacing generated paths, runs `afterBuild`, then promotes with rollback so failed builds preserve the prior `dist`. Byte-identical native, parameter, and effect route entries reuse one exact-source transform result within the current build only. |
 | Browser capabilities | [`framework/*.js`](../../framework/) | Small optional modules for commands, bindings, lists, effects, native handlers, serialization, parameters, and navigation; native contexts invalidate writes and refs at DOM ownership release, with 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; failed rebuilds show the existing error overlay while preserving the previous on-disk output. |
@@ -50,10 +51,11 @@ src/pages entries + config
   -> build orchestration writes .kudzu executable and handler modules
   -> import page modules and execute renderPage()
        -> complete HTML
-       -> RouteIR v1
-       -> referenced handler URLs and route facts
+       -> RouteIR v1 and exact handler references
+  -> validated RouteBuildRecord per emitted route
+       -> capability facts, route entries, styles, handler/effect artifact edges
   -> remove unrendered handlers/effects/Workers
-   -> planRouteCapabilities(RouteIR records, route facts)
+   -> planRouteCapabilities(RouteBuildRecord[])
        -> CapabilityIR v1
   -> specialize and emit only selected runtime/capability ESM
        -> reuse exact generated route-entry transforms within this build
@@ -69,7 +71,7 @@ The browser consumes static HTML first. State seeds and descriptors in that HTML
 
 - `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; finalized handler, binding, derived, keyed, effect, signal, import, and component ownership edges use explicit JSON-safe slots or stable symbols.
-- `build()` still owns explicit artifact selection and filesystem writes after generator results are produced.
+- `build()` still owns filesystem writes after structural route artifact selection and 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 remain in one session-bound compiler factory because both consume the same normalization and import graph contracts. ModuleSymbol resolution is stable across canonical and cloned trees; unsupported export syntax remains intentionally narrow.
 - Imported declarations resolve by ModuleSymbol and source-local SiteId. Specialized and compiler-synthesized trees still use conservative name/scope fallback where the source-local binding index does not own the complete AST.

package/docs/next-architecture/large-application-ai-native-roadmap.md

@@ -139,6 +139,7 @@ This is an incremental evolution of the current repository:
 - [x] P0.8 Stable ModuleSymbol and SiteId is complete in `0.8.35`. ProjectSession records source-local declaration, import, and re-export sites and resolves stable ModuleSymbol records through default/named exports, aliases, barrel chains, `export *`, ambiguity, and cycles. Cross-module compiler consumers locate resolved declarations by SiteId in their private normalized clones, while component calls, hooks, keyed blocks, effects, and ownership records expose deterministic source-local SiteIds. Repeated sessions and compilations preserve IDs, and symbol-only barrel traversal avoids cloning intermediate modules without changing browser artifacts or source syntax.
 - [x] P0.9 Semantic State Operations is complete in `0.8.36`. Direct setters, one immutable state-value alias, one synchronous zero-argument arrow helper, and one synchronous one-parameter function helper lower to identical existing command HandlerIR. Binding identity proves state/setter/helper/parameter ownership; recursion, escape, mutation, and dynamic helper dispatch fail at authored source locations. Existing direct command specialization remains first, unrelated safe handlers retain native ESM, and no command ABI, runtime, JavaScript VM, or general expression IR is added.
 - [x] P0.10 ModuleIR Reference Unification is complete in `0.8.37`. ModuleIR and ComponentAnalysis v2 assign deterministic slots to symbols, signals, handlers, bindings, derived values, effects, keyed blocks, imports, owners, specializations, states, refs, and IDs. State, capture, import, effect, collection, parent/child, specialization, and row edges use structural slots or ModuleSymbol records while readable names remain codegen/debug metadata. A fail-closed pre-codegen validator rejects malformed slots, unsupported versions, duplicate exports, broken reciprocity, and ownership cycles; focused JSON round-trip checks and all 198 tests pass without changing browser runtime behavior.
+- [x] P0.11 RouteBuildRecord and Artifact Graph is complete in `0.8.38`. Each rendered route records RouteIR, capability facts, route-entry paths, styles, and exact handler/effect references. Build orchestration derives Handler ESM, Worker, package-client, and chunk closure from those edges; serialized HTML/plan `includes()` searches, formatted effect keys, and parallel route-fact/entry arrays are removed. Focused malformed-reference and JSON round-trip checks plus the standard suite preserve the exact 173-file deploy digest and bytes.
 
 ### P0: Semantic Correctness And Compiler Foundation
 
@@ -361,6 +362,8 @@ function increment(value) { setCount(value + 1) }; increment(count)
 
 **Done condition:** handler, effect, Worker, CSS, package, and chunk reachability derives from explicit route edges; serialized `includes()` searches and parallel route-fact maps are removed.
 
+**Completed in `0.8.38`:** `renderPage()` retains exact handler references only when final event, effect, binding, conditional, or keyed-list descriptors are emitted. RouteBuildRecord validates those references with RouteIR, capability facts, route-entry paths, and styles before `build.mjs` projects runtime entries and artifact closure. Handler modules resolve by exact URL, Worker references resolve by structural module/handler pairs, and package-client/chunk roots derive from retained modules. The clean 152-page baseline and candidate builds produce byte-identical `kudzu-plan.json`, 173 deploy files, raw/gzip bytes, and deploy digest with no material build-time regression.
+
 ### PR 12: Deep RouteIR And CapabilityIR Validation
 
 **Objective:** fail before codegen for invalid concrete route references and capability projections.
@@ -474,4 +477,4 @@ The first comparison is Kudzu versus React + Vite using the same agent, model, t
 
 ## Immediate Decision
 
-PR 1 through PR 10 are complete. The next PR is **PR 11: RouteBuildRecord And Artifact Graph**. Do not skip directly to a store, resource, router, virtualization, or ecosystem package feature.
+PR 1 through PR 11 are complete. The next PR is **PR 12: Deep RouteIR And CapabilityIR Validation**. Do not skip directly to a store, resource, router, virtualization, or ecosystem package feature.

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.37` are completed scopes represented by package/release records.
+This is an execution sequence, not release history. `0.8.16` through `0.8.38` 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.
 
@@ -28,6 +28,7 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 | `0.8.35` | Resolve cross-module declarations through stable ModuleSymbol and source-local SiteId records. | Default/named exports, aliases, barrel chains, `export *`, cycles, ambiguity, repeated compilation, source invalidation, private clones, and measured build behavior remain deterministic. |
 | `0.8.36` | Lower equivalent direct, aliased, and local-helper state updates through existing command HandlerIR. | The four required forms emit identical commands and no native handler module; recursion, escape, mutation, and dynamic dispatch fail at authored source locations. |
 | `0.8.37` | Unify ModuleIR and ComponentAnalysis references through deterministic source-local slots and stable symbols. | Every handler, binding, derived, effect, keyed, specialization, state, ref, capture, and import edge validates before build-module generation. |
+| `0.8.38` | Replace serialized route artifact discovery with validated RouteBuildRecord edges. | Handler, effect, Worker, CSS, package-client, and chunk retention is structural while deploy files, bytes, plans, and browser behavior remain unchanged. |
 
 ## Sequence Rules
 

package/framework/README.md

@@ -68,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 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.
+Compiler ownership follows explicit stages. `build.mjs` coordinates project discovery, source compilation, RouteIR rendering, RouteBuildRecord collection, 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, RouteIR v1, and exact handler references: route-local state `slot` is an internal array reference, `id` remains the browser/DOM identity, and `name` remains readable development metadata. `compiler/route-build-record.mjs` validates structural artifact edges, and `compiler/route-capability-planner.mjs` projects CapabilityIR v1 from those records. 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.
 

package/framework/build.mjs

@@ -7,6 +7,7 @@ import { createEffectCodegen } from "./compiler/effect-codegen.mjs"
 import { generateListRuntime } from "./compiler/list-runtime-codegen.mjs"
 import { assetPath, browserPath, relativeModulePath, withBase } from "./compiler/path-helpers.mjs"
 import { createProjectSession } from "./compiler/project-session.mjs"
+import { createRouteBuildRecord, planRouteArtifacts } from "./compiler/route-build-record.mjs"
 import { createSourceCompiler } from "./compiler/source-compiler.mjs"
 import { createParamCodegen } from "./compiler/param-codegen.mjs"
 import { planRouteCapabilities, usesRouteDependencyRuntime } from "./compiler/route-capability-planner.mjs"
@@ -113,18 +114,12 @@ async function buildInto(project, outputDirectory, { minify }) {
     return effect.workers.map(worker => ({ ...worker, module: assetPath(base, `assets/${result.handlerModule.path}`), handler: handler.exportName }))
   }))
 
-  const plans = []
-  const routeCapabilities = new Map()
-  const pageEntries = []
-  const effectEntries = []
-  const nativeEntries = []
-  const paramEntries = []
+  const routeRecords = []
   const routeEntryTransforms = new Map()
   const rewrites = []
   const emittedRoutes = new Set()
   const emittedApplicationRoutes = new Set()
   const emittedNavigationRecords = []
-  const renderedHandlerUrls = new Set()
   const styleUrls = [...new Set([
     ...cssFiles.map(file => assetPath(base, `assets/${relative(sourceDirectory, file).replaceAll(sep, "/")}`)),
     ...configuredStyles.urls
@@ -190,30 +185,37 @@ async function buildInto(project, outputDirectory, { minify }) {
         runtimeParams: runtimeSchema?.params,
         ...(navigable ? { navigationAsset: navigationGroup.assetPath, applicationId: navigationGroup.applicationId, layoutId: navigationGroup.layoutId, routeId: applicationRoute } : {})
       }, props, module.layout)
-      const renderedOutput = `${JSON.stringify(result.plan)}\n${result.html}`
-      for (const url of result.handlerModules) if (renderedOutput.includes(JSON.stringify(url))) renderedHandlerUrls.add(url)
       if (navigationGroup) {
         navigationGroup.hasEffects ||= result.hasEffects
         navigationGroup.hasParams ||= result.hasParams
       }
       const usesDependencyRuntime = usesRouteDependencyRuntime({ plan: result.plan, navigable, hasBindings: result.hasBindings, hasLists: result.hasLists })
-      pageEntries.push({ route, html: result.html, usesDependencyRuntime })
-      plans.push({ route: routePath, ...result.plan })
-      routeCapabilities.set(routePath, {
-        navigable,
-        usesDependencyRuntime,
-        hasBehaviors: result.hasBehaviors,
-        hasBindings: result.hasBindings,
-        hasLists: result.hasLists,
-        hasListStyles: result.hasListStyles,
-        hasStateSeed: result.hasStateSeed
-      })
-      if (result.hasParams) paramEntries.push({ path: paramPath, schema: runtimeSchema, params: result.plan.params, searchParams: result.plan.searchParams, searchParamsWritable: result.plan.searchParamsWritable, usesDependencyRuntime, navigable })
-      if (result.hasEffects) effectEntries.push({ path: effectPath, effects: runtimeEffects(result.plan.effects, navigable), paramPath: result.hasParams ? paramPath : undefined, usesDependencyRuntime, navigable })
-      if (result.plan.events.some(event => event.native)) nativeEntries.push({
-        path: nativePath,
-        modules: [...new Set(result.plan.events.filter(event => event.native).map(event => event.native.module))]
-      })
+      const plan = { route: routePath, ...result.plan }
+      routeRecords.push(createRouteBuildRecord({
+        route: routePath,
+        output: route,
+        html: result.html,
+        plan,
+        handlerReferences: result.handlerReferences,
+        styles: styleUrls,
+        capabilities: {
+          navigable,
+          usesDependencyRuntime,
+          hasBehaviors: result.hasBehaviors,
+          hasBindings: result.hasBindings,
+          hasLists: result.hasLists,
+          hasListStyles: result.hasListStyles,
+          hasStateSeed: result.hasStateSeed,
+          hasParams: result.hasParams,
+          hasEffects: result.hasEffects
+        },
+        entries: {
+          ...(result.hasParams ? { param: paramPath } : {}),
+          ...(result.hasEffects ? { effect: effectPath } : {}),
+          ...(result.plan.events.some(event => event.native) ? { native: nativePath } : {})
+        },
+        runtimeSchema
+      }))
     }
   }
 
@@ -227,9 +229,8 @@ async function buildInto(project, outputDirectory, { minify }) {
 
   const assetsDirectory = join(outputDirectory, "assets")
   await mkdir(assetsDirectory, { recursive: true })
-  const emittedHandlerModules = handlerModules.filter(module => renderedHandlerUrls.has(assetPath(base, `assets/${module.path}`)))
-  const renderedEffects = new Set(plans.flatMap(plan => plan.effects.map(effect => `${effect.module}:${effect.handler}`)))
-  const renderedWorkerReferences = workerReferences.filter(reference => renderedEffects.has(`${reference.module}:${reference.handler}`))
+  const { handlerModules: emittedHandlerModules, workerReferences: renderedWorkerReferences, styles: renderedStyles } = planRouteArtifacts(routeRecords, handlerModules, workerReferences, module => assetPath(base, `assets/${module.path}`))
+  const renderedStyleUrls = new Set(renderedStyles)
   if (renderedWorkerReferences.length && await exists(join(publicDirectory, "assets", "workers"))) throw new Error("public/assets/workers collides with Kudzu's generated Worker asset namespace")
   const workerAssets = await project.workerCompiler.emit(renderedWorkerReferences, sourceFileSet, assetsDirectory, base, minify)
   for (const module of emittedHandlerModules) {
@@ -240,7 +241,8 @@ async function buildInto(project, outputDirectory, { minify }) {
     }
     if (module.code.includes("/__kudzu_worker_")) throw new Error(`Worker URL placeholder survived in ${module.path}`)
   }
-  const capabilityIR = planRouteCapabilities(plans, { routes: routeCapabilities, navigationRouteCount: navigationRoutes.length })
+  const plans = routeRecords.map(record => record.plan)
+  const capabilityIR = planRouteCapabilities(routeRecords, { navigationRouteCount: navigationRoutes.length })
   const {
     routes: { behaviors: behaviorCount, regularBehaviors: regularBehaviorCount, dependencyStateSeeds: dependencyStateSeedCount },
     events: { command: commandEvents, hasNativeHandlers },
@@ -251,11 +253,11 @@ async function buildInto(project, outputDirectory, { minify }) {
     runtime: { shared: hasSharedRuntime, dependency: hasDependencyRuntime }
   } = capabilityIR
   const runtimeName = usesDependencyRuntime => usesDependencyRuntime ? "kudzu-deps.js" : "kudzu.js"
-  for (let offset = 0; offset < pageEntries.length; offset += 64) {
-    await Promise.all(pageEntries.slice(offset, offset + 64).map(async entry => {
-      const routeDirectory = join(outputDirectory, entry.route)
+  for (let offset = 0; offset < routeRecords.length; offset += 64) {
+    await Promise.all(routeRecords.slice(offset, offset + 64).map(async record => {
+      const routeDirectory = join(outputDirectory, record.output)
       await mkdir(routeDirectory, { recursive: true })
-      const html = preloadModules(entry.html.replace(runtimePlaceholder, escapeAttribute(assetPath(base, `assets/${runtimeName(entry.usesDependencyRuntime)}`))))
+      const html = preloadModules(record.html.replace(runtimePlaceholder, escapeAttribute(assetPath(base, `assets/${runtimeName(record.capabilities.usesDependencyRuntime)}`))))
       await writeFile(join(routeDirectory, "index.html"), html)
     }))
   }
@@ -291,7 +293,10 @@ async function buildInto(project, outputDirectory, { minify }) {
   if (hasNativeHandlers) {
     const generated = generateNativeRuntime(await readFile(new URL("./native-runtime.js", import.meta.url), "utf8"), capabilityIR)
     await writeJavaScript(join(assetsDirectory, "kudzu-native.js"), generated.source, minify, generated.define)
-    for (const entry of nativeEntries) await printNativeEntry(entry, assetsDirectory, base, minify, routeEntryTransforms)
+    for (const record of routeRecords) if (record.entries.native) await printNativeEntry({
+      path: record.entries.native,
+      modules: [...new Set(record.plan.events.filter(event => event.native).map(event => event.native.module))]
+    }, assetsDirectory, base, minify, routeEntryTransforms)
   }
   if (navigationGroups.length) {
     const navigationSource = await readFile(new URL("./navigation-runtime.js", import.meta.url), "utf8")
@@ -304,15 +309,15 @@ async function buildInto(project, outputDirectory, { minify }) {
     await mkdir(resolve(output, ".."), { recursive: true })
     await writeJavaScript(output, handlerModule.code, minify)
   }
-  for (const entry of paramEntries) {
-    const output = join(assetsDirectory, entry.path)
+  for (const record of routeRecords) if (record.entries.param) {
+    const output = join(assetsDirectory, record.entries.param)
     await mkdir(dirname(output), { recursive: true })
-    await writeRouteEntry(output, printParamEntry(entry.schema, entry.params, entry.searchParams, entry.searchParamsWritable, output, assetsDirectory, base, runtimeName(entry.usesDependencyRuntime), entry.navigable), minify, routeEntryTransforms)
+    await writeRouteEntry(output, printParamEntry(record.runtimeSchema, record.plan.params, record.plan.searchParams, record.plan.searchParamsWritable, output, assetsDirectory, base, runtimeName(record.capabilities.usesDependencyRuntime), record.capabilities.navigable), minify, routeEntryTransforms)
   }
-  for (const entry of effectEntries) {
-    const output = join(assetsDirectory, entry.path)
+  for (const record of routeRecords) if (record.entries.effect) {
+    const output = join(assetsDirectory, record.entries.effect)
     await mkdir(dirname(output), { recursive: true })
-    await writeRouteEntry(output, printEffectEntry(entry.effects, output, emittedHandlerModules, assetsDirectory, base, entry.paramPath, runtimeName(entry.usesDependencyRuntime), entry.navigable), minify, routeEntryTransforms)
+    await writeRouteEntry(output, printEffectEntry(runtimeEffects(record.plan.effects, record.capabilities.navigable), output, emittedHandlerModules, assetsDirectory, base, record.entries.param, runtimeName(record.capabilities.usesDependencyRuntime), record.capabilities.navigable), minify, routeEntryTransforms)
   }
   const clientModules = await collectClientModules(emittedHandlerModules.flatMap(module => module.clientImports).map(file => resolve(root, file)), sourceFileSet)
   for (const file of clientModules) {
@@ -342,7 +347,7 @@ async function buildInto(project, outputDirectory, { minify }) {
   }
   const sortedRewrites = rewrites.sort((left, right) => runtimeSpecificity(right) - runtimeSpecificity(left) || left.pattern.localeCompare(right.pattern))
   await writeFile(join(workDirectory, "kudzu-plan.json"), JSON.stringify({ routes: plans, rewrites: sortedRewrites }, null, 2))
-  for (const file of cssFiles) {
+  for (const file of cssFiles.filter(file => renderedStyleUrls.has(assetPath(base, `assets/${relative(sourceDirectory, file).replaceAll(sep, "/")}`)))) {
     const output = join(assetsDirectory, relative(sourceDirectory, file))
     await mkdir(dirname(output), { recursive: true })
     await writeFile(output, cssOutputs.get(file))
@@ -353,7 +358,7 @@ async function buildInto(project, outputDirectory, { minify }) {
     await mkdir(dirname(output), { recursive: true })
     await writeFile(output, await readFile(file))
   }
-  for (const style of configuredStyles.sources) {
+  for (const style of configuredStyles.sources.filter(style => renderedStyleUrls.has(withBase(base, style.output)))) {
     let css = await readFile(style.source, "utf8")
     if (style.transform) {
       const result = await style.transform(css, { source: style.source, output: style.output })

package/framework/compiler/route-build-record.mjs

@@ -0,0 +1,81 @@
+export function createRouteBuildRecord(input) {
+  const record = {
+    version: input.version ?? 1,
+    route: input.route,
+    output: input.output,
+    html: input.html,
+    plan: input.plan,
+    capabilities: input.capabilities,
+    artifacts: {
+      handlers: input.handlerReferences ?? [],
+      effects: (input.plan?.effects ?? []).map(({ module, handler }) => ({ module, handler })),
+      styles: [...new Set(input.styles ?? [])]
+    },
+    entries: input.entries ?? {},
+    ...(input.runtimeSchema ? { runtimeSchema: input.runtimeSchema } : {})
+  }
+  return assertRouteBuildRecord(record)
+}
+
+export function assertRouteBuildRecord(record) {
+  if (record?.version !== 1) throw new Error(`Unsupported RouteBuildRecord version: ${JSON.stringify(record?.version)}`)
+  if (typeof record.route !== "string" || typeof record.output !== "string" || typeof record.html !== "string" || !isRecord(record.plan)) throw new Error("Invalid RouteBuildRecord v1 structure")
+  if (record.plan.route !== record.route) throw new Error(`RouteBuildRecord route ${JSON.stringify(record.route)} does not match RouteIR route ${JSON.stringify(record.plan.route)}`)
+  const capabilityNames = ["navigable", "usesDependencyRuntime", "hasBehaviors", "hasBindings", "hasLists", "hasListStyles", "hasStateSeed", "hasParams", "hasEffects"]
+  if (!isRecord(record.capabilities) || !capabilityNames.every(name => typeof record.capabilities[name] === "boolean")) throw new Error("Invalid RouteBuildRecord v1 capabilities")
+  if (!isRecord(record.artifacts) || !Array.isArray(record.artifacts.handlers) || !Array.isArray(record.artifacts.effects) || !Array.isArray(record.artifacts.styles) || !isRecord(record.entries)) throw new Error("Invalid RouteBuildRecord v1 artifacts")
+  const handlers = new Set()
+  for (const reference of record.artifacts.handlers) {
+    assertHandlerReference(reference)
+    const key = referenceKey(reference)
+    if (handlers.has(key)) throw new Error(`RouteBuildRecord ${JSON.stringify(record.route)} has duplicate handler reference ${key}`)
+    handlers.add(key)
+  }
+  for (const effect of record.artifacts.effects) {
+    assertHandlerReference(effect)
+    if (!handlers.has(referenceKey(effect))) throw new Error(`RouteBuildRecord ${JSON.stringify(record.route)} effect references an unretained handler ${referenceKey(effect)}`)
+  }
+  for (const event of record.plan.events ?? []) if (event.native && !handlers.has(referenceKey(event.native))) throw new Error(`RouteBuildRecord ${JSON.stringify(record.route)} event references an unretained handler ${referenceKey(event.native)}`)
+  for (const descriptor of [...(record.plan.bindings ?? []), ...(record.plan.conditions ?? []), ...(record.plan.lists ?? []).map(list => list.source).filter(Boolean)]) {
+    if (descriptor.module && !handlers.has(referenceKey(descriptor))) throw new Error(`RouteBuildRecord ${JSON.stringify(record.route)} descriptor references an unretained handler ${referenceKey(descriptor)}`)
+  }
+  if (record.artifacts.styles.some(style => typeof style !== "string")) throw new Error("RouteBuildRecord styles must be strings")
+  for (const [kind, path] of Object.entries(record.entries)) if (!["effect", "native", "param"].includes(kind) || typeof path !== "string") throw new Error(`Invalid RouteBuildRecord entry ${JSON.stringify(kind)}`)
+  if (record.runtimeSchema !== undefined && !isRecord(record.runtimeSchema)) throw new Error("Invalid RouteBuildRecord runtime schema")
+  const hasNative = (record.plan.events ?? []).some(event => event.native)
+  if (Boolean(record.entries.effect) !== record.capabilities.hasEffects || record.capabilities.hasEffects !== Boolean(record.plan.effects?.length)) throw new Error(`RouteBuildRecord ${JSON.stringify(record.route)} has inconsistent effect artifacts`)
+  if (Boolean(record.entries.native) !== hasNative) throw new Error(`RouteBuildRecord ${JSON.stringify(record.route)} has inconsistent native artifacts`)
+  if (Boolean(record.entries.param) !== record.capabilities.hasParams) throw new Error(`RouteBuildRecord ${JSON.stringify(record.route)} has inconsistent parameter artifacts`)
+  return record
+}
+
+export function planRouteArtifacts(records, handlerModules, workerReferences, moduleUrl) {
+  for (const record of records) assertRouteBuildRecord(record)
+  const modules = new Map()
+  for (const module of handlerModules) {
+    const url = moduleUrl(module)
+    if (modules.has(url)) throw new Error(`Duplicate compiled handler module: ${url}`)
+    modules.set(url, module)
+  }
+  const retainedUrls = new Set(records.flatMap(record => record.artifacts.handlers.map(reference => reference.module)))
+  for (const url of retainedUrls) if (!modules.has(url)) throw new Error(`Handler module was not compiled: ${url}`)
+  const effects = new Map()
+  for (const reference of records.flatMap(record => record.artifacts.effects)) {
+    const handlers = effects.get(reference.module) ?? new Set()
+    handlers.add(reference.handler)
+    effects.set(reference.module, handlers)
+  }
+  return {
+    handlerModules: handlerModules.filter(module => retainedUrls.has(moduleUrl(module))),
+    workerReferences: workerReferences.filter(reference => effects.get(reference.module)?.has(reference.handler)),
+    styles: [...new Set(records.flatMap(record => record.artifacts.styles))]
+  }
+}
+
+const isRecord = value => value !== null && typeof value === "object" && !Array.isArray(value)
+
+function assertHandlerReference(reference) {
+  if (!isRecord(reference) || typeof reference.module !== "string" || !reference.module || typeof reference.handler !== "string" || !reference.handler) throw new Error("RouteBuildRecord handler references require module and handler strings")
+}
+
+const referenceKey = reference => `${JSON.stringify(reference.module)}#${JSON.stringify(reference.handler)}`

package/framework/compiler/route-capability-planner.mjs

@@ -4,7 +4,9 @@ export function usesRouteDependencyRuntime({ plan, navigable, hasBindings, hasLi
   return !navigable && hasDependencies && !plan.effects.some(effect => effect.owner) && !hasBindings && !hasLists && !plan.events.some(event => event.native)
 }
 
-export function planRouteCapabilities(plans, { routes = new Map(), navigationRouteCount = 0 } = {}) {
+export function planRouteCapabilities(records, { navigationRouteCount = 0 } = {}) {
+  for (const record of records) assertRouteBuildRecord(record)
+  const plans = records.map(record => record.plan)
   for (const plan of plans) assertRouteIR(plan)
   const commandEvents = new Set()
   const nativeEvents = new Set()
@@ -39,7 +41,7 @@ export function planRouteCapabilities(plans, { routes = new Map(), navigationRou
 
   for (let index = 0; index < plans.length; index++) {
     const plan = plans[index]
-    const route = routes.get(plan.route)
+    const route = records[index].capabilities
     for (const event of plan.events) {
       if (event.commands) commandEvents.add(event.event)
       if (event.native) nativeEvents.add(event.event)
@@ -77,7 +79,7 @@ export function planRouteCapabilities(plans, { routes = new Map(), navigationRou
     }
   }
 
-  const routeEntries = [...routes.values()]
+  const routeEntries = records.map(record => record.capabilities)
   const routeCounts = {
     behaviors: routeEntries.filter(route => route.hasBehaviors).length,
     regularBehaviors: routeEntries.filter(route => route.hasBehaviors && !route.usesDependencyRuntime).length,
@@ -151,3 +153,4 @@ function hasNestedCaptureState(value, insideCapture = false) {
   if (value.type === "object") return value.value.some(([, entry]) => hasNestedCaptureState(entry, true))
   return (Array.isArray(value) ? value : Object.values(value)).some(entry => hasNestedCaptureState(entry, false))
 }
+import { assertRouteBuildRecord } from "./route-build-record.mjs"

package/framework/core.d.ts

@@ -185,6 +185,6 @@ export function renderPage<Props = Record<string, never>>(
   hasLists: boolean
   hasListStyles: boolean
   hasStateSeed: boolean
-  handlerModules: string[]
+  handlerReferences: Array<{ module: string; handler: string }>
   plan: RouteIR
 }>

package/framework/core.mjs

@@ -207,8 +207,10 @@ export function useEffect(callback, dependencies, module, handler, states, scope
     owner = nextRenderId("e")
     owners.push(owner)
   }
-  if (!renderContext.listDepth || list) renderContext.effects.push({ module, handler, states, scope, source, renderScope: renderContext.renderScope, ...(dependencyIds.length ? { dependencies: dependencyIds } : {}), ...(dependencyExpressions.length ? { dependencyExpressions, dependencyStates: dependencyStateIds } : {}), ...(itemDependencies.length ? { itemDependencies, listState: renderContext.listRoot.state } : {}), ...(cleanup ? { cleanup: true } : {}), ...(owner ? { owner } : {}), ...(list ? { list: true } : {}) })
-  renderContext.handlerModules.add(module)
+  if (!renderContext.listDepth || list) {
+    renderContext.effects.push({ module, handler, states, scope, source, renderScope: renderContext.renderScope, ...(dependencyIds.length ? { dependencies: dependencyIds } : {}), ...(dependencyExpressions.length ? { dependencyExpressions, dependencyStates: dependencyStateIds } : {}), ...(itemDependencies.length ? { itemDependencies, listState: renderContext.listRoot.state } : {}), ...(cleanup ? { cleanup: true } : {}), ...(owner ? { owner } : {}), ...(list ? { list: true } : {}) })
+    retainHandlerReference(module, handler)
+  }
   renderContext.hasBehaviors = true
   renderContext.hasEffects = true
 }
@@ -254,7 +256,6 @@ export function behavior(commands) {
 }
 
 export function nativeBehavior(module, handler, states, scope) {
-  renderContext?.handlerModules.add(module)
   return {
     [nativeBehaviorMarker]: true,
     module,
@@ -325,7 +326,6 @@ export function listField(read, field) {
 }
 
 export function listExpression(read, module, handler, states = []) {
-  renderContext?.handlerModules.add(module)
   const stateMap = Object.fromEntries(states.map(([name, state]) => {
     if (!state?.[signalMarker] || !validEffectDependency(state.value)) throw new Error(`Derived keyed list item expression state ${JSON.stringify(name)} must be primitive Kudzu state`)
     return [name, state.id]
@@ -346,7 +346,6 @@ export function listIndex() {
 }
 
 export function listConditional(kind, read, truthy, falsy, module, handler) {
-  renderContext?.handlerModules.add(module)
   return { [listConditionalMarker]: true, kind, value: renderContext?.listTemplate ? undefined : read(), truthy, falsy, module, handler }
 }
 
@@ -380,7 +379,6 @@ function assertListValue(value, seen) {
 }
 
 function reactiveDescriptor(module, handler, states, scope) {
-  renderContext?.handlerModules.add(module)
   const scopeStates = {}
   const serializedScope = {}
   const scopeBindings = {}
@@ -402,6 +400,16 @@ function reactiveDescriptor(module, handler, states, scope) {
   }
 }
 
+function retainHandlerReference(module, handler) {
+  const reference = { module, handler }
+  renderContext?.handlerReferences.set(JSON.stringify([module, handler]), reference)
+}
+
+function retainDescriptorHandlers(descriptor) {
+  if (descriptor?.module && descriptor.handler) retainHandlerReference(descriptor.module, descriptor.handler)
+  for (const nested of Object.values(descriptor?.scopeBindings ?? {})) retainDescriptorHandlers(nested)
+}
+
 export function bindingValue(value) {
   return value?.[signalMarker] || value?.[bindingMarker] ? value.value : value
 }
@@ -449,7 +457,7 @@ function serializeCapture(name, value, seen) {
 }
 
 export async function renderPage(component, metadata = {}, props = {}, layout) {
-  renderContext = { scoped: Boolean(layout), renderScope: layout ? "layout" : "route", counters: { layout: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0, i: 0 }, route: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0, i: 0 } }, nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, nextEffect: 0, nextParam: 0, nextId: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listRowRoot: undefined, listTemplate: false, listInitialMarkers: false, listConditionalBranch: false, listFields: undefined, listEffectOwners: [], listRowStates: [], listRowRefs: [], listRowConditions: [], listRowLists: [], effectOwners: [], contexts: [], stores: new Map(), states: {}, textStates: new Set(), conditionStates: new Set(), conditionOwnedStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], handlerModules: new Set(), runtimeParamNames: metadata.runtimeParams, paramEntries: [], params: undefined, searchParams: new Map(), searchParamEntries: [], searchParamsWritable: false, hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasParams: false, hasBindings: false, hasLists: false, hasListStyles: false }
+  renderContext = { scoped: Boolean(layout), renderScope: layout ? "layout" : "route", counters: { layout: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0, i: 0 }, route: { s: 0, r: 0, c: 0, l: 0, e: 0, p: 0, i: 0 } }, nextState: 0, nextRef: 0, nextCondition: 0, nextList: 0, nextEffect: 0, nextParam: 0, nextId: 0, conditionDepth: 0, listDepth: 0, listRoot: undefined, listRowRoot: undefined, listTemplate: false, listInitialMarkers: false, listConditionalBranch: false, listFields: undefined, listEffectOwners: [], listRowStates: [], listRowRefs: [], listRowConditions: [], listRowLists: [], effectOwners: [], contexts: [], stores: new Map(), states: {}, textStates: new Set(), conditionStates: new Set(), conditionOwnedStates: new Set(), events: [], effects: [], bindings: [], textBindings: [], conditions: [], lists: [], handlerReferences: new Map(), runtimeParamNames: metadata.runtimeParams, paramEntries: [], params: undefined, searchParams: new Map(), searchParamEntries: [], searchParamsWritable: false, hasBehaviors: false, hasNativeBehaviors: false, hasEffects: false, hasParams: false, hasBindings: false, hasLists: false, hasListStyles: false }
 
   try {
     const page = { [routeScopeMarker]: true, component, props }
@@ -525,7 +533,7 @@ export async function renderPage(component, metadata = {}, props = {}, layout) {
       hasLists: renderContext.hasLists,
       hasListStyles: renderContext.hasListStyles,
       hasStateSeed: initialState.length > 0,
-      handlerModules: [...renderContext.handlerModules],
+      handlerReferences: [...renderContext.handlerReferences.values()],
       plan: {
         version: 1,
         states: Object.entries(renderContext.states).map(([id, state], slot) => ({ slot, id, ...state })),
@@ -648,6 +656,7 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
     const metadata = { id, kind: node.kind, initial: node.value, ...descriptor, ...(namespace === "svg" ? { svg: true } : {}), ...(owned ? { owned } : {}), ...(mount ? { mount: true } : {}) }
     for (const stateId of stateIds) renderContext.conditionStates.add(stateId)
     renderContext.conditions.push(metadata)
+    retainDescriptorHandlers(metadata)
     renderContext.hasBehaviors = true
     renderContext.hasBindings = true
     const encoded = escapeJsonAttribute(metadata)
@@ -667,7 +676,9 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   }
   if (node?.[listExpressionMarker]) {
     const descriptor = { module: node.module, handler: node.handler, ...(Object.keys(node.states).length ? { states: node.states } : {}) }
-    const marker = renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch ? ` data-k-list-expression='${escapeJsonAttribute(descriptor)}'` : ""
+    const retained = renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch
+    if (retained) retainDescriptorHandlers(descriptor)
+    const marker = retained ? ` data-k-list-expression='${escapeJsonAttribute(descriptor)}'` : ""
     return `<template${marker}></template>${escapeHtml(node.value ?? "")}<template data-k-list-expression-end></template>`
   }
   if (node?.[bindingMarker]) {
@@ -675,6 +686,7 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
     const reactive = reactiveStateIds(descriptor).size > 0
     if (!reactive) return renderNode(node.value, namespace, selectValue)
     renderContext.bindings.push({ target: "text", ...descriptor })
+    retainDescriptorHandlers(descriptor)
     if (renderContext.conditionDepth || renderContext.listDepth) for (const stateId of reactiveStateIds(descriptor)) renderContext.conditionStates.add(stateId)
     renderContext.hasBehaviors = true
     renderContext.hasBindings = true
@@ -685,6 +697,7 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
   if (node?.[listConditionalMarker]) {
     if (namespace === "svg") throw new Error("Keyed row conditions are not supported inside svg")
     const descriptor = { kind: node.kind, module: node.module, handler: node.handler }
+    retainDescriptorHandlers(descriptor)
     const owner = renderContext.listRoot ?? renderContext.listRowRoot
     if (owner) owner.conditions = true
     const previousBranch = renderContext.listConditionalBranch
@@ -800,6 +813,7 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
         const native = template
         attributes += ` data-k-native-${event}='${escapeJsonAttribute(native)}'`
         renderContext.events.push({ event, native })
+        retainDescriptorHandlers(native)
         if (renderContext.listDepth && Object.values(template.scope).some(entry => entry?.type === "list-item" || entry?.type === "list-index")) listEvents.push([event, template])
         renderContext.hasNativeBehaviors = true
       } else {
@@ -817,9 +831,10 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
       if (name === "style") renderContext.hasListStyles = true
       continue
     }
-    if (value?.[listExpressionMarker]) {
+      if (value?.[listExpressionMarker]) {
       attributes += renderAttribute(name, value.value)
-      listExpressionAttributes.push([name, value.module, value.handler, ...(Object.keys(value.states).length ? [value.states] : [])])
+        listExpressionAttributes.push([name, value.module, value.handler, ...(Object.keys(value.states).length ? [value.states] : [])])
+        if (renderContext.listTemplate || renderContext.listInitialMarkers || renderContext.listConditionalBranch) retainHandlerReference(value.module, value.handler)
       if (name === "style") renderContext.hasListStyles = true
       continue
     }
@@ -837,6 +852,7 @@ async function renderNode(node, namespace, selectValue = noSelectValue) {
       if (propertyTarget) attributes += ` data-k-bind-${name}='${escapeJsonAttribute(descriptor)}'`
       else attributeBindings.push({ target: name, ...descriptor })
       renderContext.bindings.push({ target: name, ...descriptor })
+      retainDescriptorHandlers(descriptor)
       if (renderContext.conditionDepth || renderContext.listDepth) for (const stateId of reactiveStateIds(descriptor)) renderContext.conditionStates.add(stateId)
       renderContext.hasBehaviors = true
       renderContext.hasBindings = true
@@ -944,6 +960,7 @@ async function renderList(node, namespace, selectValue) {
     }
     if (!node.ownerField || ownerTemplate && !rowList.planned) {
       renderContext.lists.push(descriptor)
+      retainDescriptorHandlers(descriptor.source)
       if (rowList) rowList.planned = true
     }
     renderContext.hasBehaviors = true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.8.37",
+  "version": "0.8.38",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",