@kudzujs/core 0.8.29 → 0.8.31

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.29` 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.31` 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.
 
@@ -28,6 +28,7 @@ Syntax compatibility does not mean reproducing React wholesale. Kudzu accepts th
 - Interactive routes ship only the capabilities they use.
 - Prefer build-time execution whenever all inputs are available during the build.
 - State setters update logical state immediately and batch direct DOM writes at synchronous-turn boundaries.
+- Async handler state writes, queued commits, and captured ref resolution end when its mounted DOM owner is released; application promises and ordinary reads may finish without reviving that ownership.
 - Preserve familiar function components, props, children, JSX, hooks, conditions, collections, and event handlers where Kudzu can compile them safely.
 - Prefer compiler specialization over asking migrated applications to replace ordinary declarative React UI with imperative DOM code.
 - Unknown browser-only data receives a static shell plus only the ESM needed to obtain and patch it.
@@ -282,6 +283,19 @@ This queue orders the next investigations by general migration value. Start only
 - Same-named callback parameters, locals, imports, browser globals, state values, setters, reducers, observer handles, and animation-frame handles no longer alias through identifier spelling alone.
 - Imported, specialized, and compiler-synthesized trees retain the existing conservative fallback; no public API, source syntax, ModuleIR contract, browser runtime, or capability bytes were added.
 
+### Completed In 0.8.30
+
+- Reachable ordinary source validates relative runtime imports and re-exports before compilation and reports unresolved edges at the original importer file, line, column, and specifier.
+- Ordinary dynamic `import()` fails during graph discovery rather than surviving into generated `.kudzu` modules; relative, package, template, and computed forms share one source-located boundary.
+- Ordinary and Worker graph ownership remain separate, while type-only and unreachable source stay excluded. Export-name validation, ProjectSession, runtime behavior, and public APIs remain unchanged.
+
+### Completed In 0.8.31
+
+- Pending async native handlers lose state-write, queued-commit, and captured-ref authority when enhanced navigation, keyed removal, conditional removal, or document disposal releases their mounted DOM owner.
+- Direct and captured setters cannot recreate released state, queued commits clear without touching replacement DOM, and captured object refs resolve to `null` after release.
+- Chrome coverage removes and recreates the same route and keyed row before old work resolves, proving replacement ownership stays fresh without cancelling application promises or adding a scheduler.
+- The focused 5,000-event Chrome dispatch median remains 6.4 ms; the native fixture retains its emitted paths with a measured 209 B raw / 94 B aggregate gzip correctness cost.
+
 ## Cross-Cutting Performance Gates
 
 Every migration feature must preserve:

package/PERFORMANCE.md

@@ -1,6 +1,41 @@
 # Performance Records
 
-Reproducibility classes: `npm run benchmark` and `npm run benchmark:keyed` 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.
+Reproducibility classes: `npm run benchmark`, `npm run benchmark:keyed`, and `npm run benchmark:native` 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.
+
+## 0.8.31 Async Native Handler Ownership
+
+Measured UTC 2026-08-10 on Apple M3, 8 logical CPUs, 8 GiB RAM, macOS 26.5.2 / Darwin 25.5.0, Node 25.6.1, npm 11.18.0, and Chrome 151.0.7922.76. The baseline was clean tag `v0.8.30` at `9bb5ce8`; baseline and candidate used the same installed dependencies.
+
+The implementation and maintained-check patch over `v0.8.30` had SHA-256 `c67956b67b558052885dd48a9dbe35f238b8ce042876537952355aa05b8cdc10`, produced by:
+
+```bash
+git diff --binary v0.8.30 -- framework/native-runtime.js framework/serialization.js test/fixtures/navigation/src/Shell.tsx test/fixtures/navigation/src/pages/product.tsx test/fixtures/navigation/public/browser-test.js test/framework.test.mjs test/native-performance.mjs package.json | shasum -a 256
+```
+
+The maintained browser runner built the same `test/fixtures/native-bubbling` source with each framework root. After one warm-up, 21 alternating headless Chrome processes dispatched 5,000 synchronous clicks through the real DOM listener, handler-module lookup, generated handler, state context, and queued-flush scheduling path. Both medians were 6.4 ms; the 6.1-6.8 ms baseline and 6.2-6.7 ms candidate ranges overlap, so no dispatch regression is established.
+
+```bash
+git worktree add --detach /tmp/kudzu-v0.8.30 v0.8.30
+ln -s "$PWD/node_modules" /tmp/kudzu-v0.8.30/node_modules
+BASELINE_ROOT=/tmp/kudzu-v0.8.30 RUNS=21 ITERATIONS=5000 \
+CHROME_BIN="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+npm run benchmark:native
+```
+
+```text
+0.8.30: [6.6,6.3,6.4,6.3,6.3,6.8,6.3,6.6,6.3,6.4,6.5,6.4,6.5,6.5,6.4,6.1,6.3,6.2,6.5,6.4,6.4]
+0.8.31: [6.4,6.7,6.2,6.4,6.6,6.6,6.5,6.4,6.5,6.4,6.4,6.4,6.6,6.5,6.4,6.3,6.4,6.4,6.6,6.2,6.4]
+```
+
+The maintained `native-bubbling` fixture retained the same eight JavaScript paths. The browser runner hashes every file and permits only the ownership-bearing native and capture-deserialization runtimes to change:
+
+| Artifact | 0.8.30 raw / gzip | 0.8.31 raw / gzip | Delta raw / gzip |
+|---|---:|---:|---:|
+| `assets/kudzu-native.js` | 1,528 B / 842 B | 1,715 B / 925 B | +187 B / +83 B |
+| `assets/kudzu-serialization.js` | 675 B / 381 B | 697 B / 392 B | +22 B / +11 B |
+| Complete native fixture JavaScript | 13,629 B / 6,177 B | 13,838 B / 6,271 B | +209 B / +94 B |
+
+The timing is a focused synchronous event-dispatch measurement, not a general interaction or asynchronous task benchmark. The runtime does not cancel application promises or arbitrary browser API work; it invalidates Kudzu state writes, queued commits, and captured ref resolution after the listener's DOM ownership is released.
 
 ## 0.8.26 Goal B Benchmark Hardening
 

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.29 - Symbol-aware descriptor discovery.** Native handlers, effects, reactive bindings, keyed evaluators, optimized commands, and effect-resource validation now use source-local lexical identity when the binding index owns the complete AST, while synthesized trees retain the established fail-safe path. Read the [release notes](./RELEASES.md#0829---symbol-aware-descriptor-discovery), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.29), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.8.31 - Async native-handler ownership.** Pending async handlers lose state-write, queued-commit, and captured-ref authority when enhanced navigation or keyed/conditional removal releases their DOM owner. The focused synchronous native event-dispatch benchmark shows no material regression. Read the [release notes](./RELEASES.md#0831---async-native-handler-ownership), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.31), 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,66 @@
 # Kudzu Releases
 
+## 0.8.31 - Async native-handler ownership
+
+Kudzu 0.8.31 completes P0.4 by tying every mounted native-handler context to its DOM registration lifetime. Async work may finish after route, keyed, or conditional removal, but it cannot write through ownership that no longer exists.
+
+### Changed in 0.8.31
+
+- Native registrations expose one active lifetime to direct setters, captured setters, queued commits, and captured object refs.
+- `unmountNative()` invalidates the registration before removing its listener. Enhanced navigation, keyed removal, and conditional removal use the shared unmount hook; non-persisted `pagehide` directly releases document registrations.
+- Late state writes become no-ops instead of recreating released state IDs; already queued commits clear without touching replacement DOM.
+- Captured object refs resolve to `null` after release, so a late handler cannot find a replacement node that reused the same compiler-owned ref ID.
+- Application promises are not cancelled, and no scheduler, task registry, component runtime, or public API is added.
+
+### Performance
+
+- Twenty-one alternating headless Chrome processes measured 5,000 synchronous native event dispatches at a 6.4 ms median for both `0.8.30` and `0.8.31`; the recorded ranges overlap.
+- The maintained `native-bubbling` fixture keeps the same eight JavaScript paths. `kudzu-native.js` and `kudzu-serialization.js` add 209 B raw / 94 B aggregate gzip; the runner rejects any other artifact change.
+- Environment, raw arrays, artifact bytes, methodology, and limitations are recorded in `PERFORMANCE.md`.
+
+### Validation
+
+- `npm run check`, `npm test`, `npm run test:package`, and all 189 tests pass.
+- Chrome starts async route and keyed-row handlers, releases and recreates their owners, and proves late state writes and refs cannot mutate replacement ownership. A persistent layout handler also proves non-persisted document disposal invalidates pending work.
+- Focused context checks cover queued direct commits and captured setters. The browser suite retains normal synchronous native event semantics; unaffected static routes remain zero JavaScript.
+- P0.5 atomic and collision-safe output is next.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.31
+```
+
+## 0.8.30 - Graph failure diagnostics
+
+Kudzu 0.8.30 completes P0.3 by making ordinary source-graph failures stop at the original importer before compilation, generated module loading, or `.kudzu` paths can obscure the source error.
+
+### Changed in 0.8.30
+
+- Reachability validates every relative runtime import and re-export in an ordinary reachable module instead of silently dropping unresolved edges.
+- Missing bound imports, side-effect imports, reachable helper imports, named/default forwarding, and `export *` report the importer file, line, column, and written specifier.
+- Every ordinary dynamic `import()` form is rejected during graph discovery, including relative, package, template-literal, and computed specifiers.
+- Ordinary and Worker traversal retain separate ownership, so Worker-only modules continue through Worker-specific graph diagnostics and cleanup rules.
+- Type-only edges and unreachable migration source remain excluded and cannot block a build.
+
+### Compiler Boundary
+
+- `ordinaryRuntimeDependencies()` is the single pre-codegen validator for ordinary runtime graph edges; downstream import rewriting remains a fail-closed assertion.
+- This release validates whether a relative runtime edge resolves to exactly one TypeScript file. Whether an existing target exports a requested name remains deferred to the planned module-symbol graph.
+- P0.3 adds no accepted source syntax, ProjectSession, export cache, public API, browser runtime, or generated capability bytes. P0.4 async native-handler invalidation is next.
+
+### Validation
+
+- `npm run check`, `npm test`, `npm run test:package`, and all 189 tests pass.
+- Focused in-memory and build fixtures cover missing page imports, reachable helper imports, re-exports, relative/package/computed dynamic imports, type-only exclusion, unreachable exclusion, and absence of generated `.kudzu` paths.
+- Existing Worker graph diagnostics, React/Router/Zustand migrations, keyed ownership, effects, navigation, and static-route zero-JavaScript behavior remain covered.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.30
+```
+
 ## 0.8.29 - Symbol-aware descriptor discovery
 
 Kudzu 0.8.29 completes P0.2 by moving native handler, effect, binding, and list descriptor decisions from identifier spelling onto the source-local binding index introduced in 0.8.28.

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.29` implementation sequence is [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md). It orders compiler semantic generalization, large-application foundations, compatibility boundaries, AI tooling, and production validation without changing the invariants below.
+The active post-`0.8.31` implementation sequence is [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md). P0.4 native-handler ownership is complete; P0.5 atomic and collision-safe output 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.29` 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.31` 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
 
@@ -8,7 +8,7 @@ This maps the current `0.8.29` architecture built on the completed `0.8.23` Goal
 |---|---|---|
 | CLI entry | [`bin/kudzu.mjs`](../../bin/kudzu.mjs) | Dispatches build and development commands. |
 | Build orchestration | [`framework/build.mjs`](../../framework/build.mjs), `build()` | Coordinates config, discovery, source compilation, RouteIR rendering, CapabilityIR projection, generator invocation, artifact emission, and `afterBuild`. |
-| Reachability/import resolution | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `reachableSourceFiles()`; [`framework/compiler/source-graph.mjs`](../../framework/compiler/source-graph.mjs), `resolveSourceImport()` | Starts from page entries, follows relative runtime imports/re-exports and validated Worker references, and excludes unreachable migration source. |
+| 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. |
 | Shared AST/scope helpers | [`framework/compiler/ast-helpers.mjs`](../../framework/compiler/ast-helpers.mjs) | Binding, scope, reference, effect-return, and source-location analysis. |
@@ -29,7 +29,7 @@ This maps the current `0.8.29` architecture built on the completed `0.8.23` Goal
 | 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 and writes or bundles generated sources with esbuild. 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; no component runtime. |
+| 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; never changes production `dist/`. |
 
@@ -67,7 +67,7 @@ The browser consumes static HTML first. State seeds and descriptors in that HTML
 - `build()` still owns explicit artifact selection and filesystem writes after generator results are produced.
 - Runtime generators intentionally specialize readable authored sources through exact anchors; every required anchor fails closed, but a future generator format may remove this transitional dependency.
 - Source reachability and source compilation share one module because both consume the same normalization and import graph contracts.
-- Native handler, effect, state/setter, list, Router, React, and Zustand discovery still contains name-based analysis. The binding index is intentionally adopted one consumer family at a time; P0.2 moves the next descriptor consumers without changing cross-module semantics.
+- Imported, specialized, and compiler-synthesized trees still use conservative name/scope fallback where the source-local binding index does not own the complete AST; cross-module semantics remain deferred to stable ModuleSymbol and SiteId work.
 
 These are future simplification opportunities, not incomplete Goal A contracts. Goal A changed no source support, browser output semantics, or browser architecture.
 

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

@@ -2,7 +2,7 @@
 
 ## Status
 
-Active execution plan after `0.8.29`. This document turns the current compiler audit into an ordered implementation program. It does not mark any planned capability as supported and does not authorize a React runtime, VDOM, hydration, retained browser component tree, generic rerenderer, public store/query/resource API, SPA router, or islands.
+Active execution plan after `0.8.31`. This document turns the current compiler audit into an ordered implementation program. It does not mark any planned capability as supported and does not authorize a React runtime, VDOM, hydration, retained browser component tree, generic rerenderer, public store/query/resource API, SPA router, or islands.
 
 [`MIGRATION_ROADMAP.md`](../../MIGRATION_ROADMAP.md) remains authoritative for product invariants and fixture-driven feature selection. This plan is authoritative for the order and completion evidence of compiler generalization, large-application foundations, compatibility boundaries, AI tooling, and scale validation. If implementation evidence changes a boundary, update this document before broadening a patch.
 
@@ -43,7 +43,7 @@ The current limiting architecture is observable in these files:
 | ModuleIR | `compiler/ir/module-ir.mjs` | Numeric slots, names, export strings, and formatted owner strings coexist; several sections are descriptive rather than authoritative inputs |
 | RouteIR/CapabilityIR | `route-capability-planner.mjs` | Validation is shallow and capability selection is site-wide across interactive routes |
 | Build/codegen | `framework/build.mjs`, runtime generators | Full destructive builds, serialized-string handler reachability, source-text runtime surgery, no route chunk/CSS closure report |
-| Browser lifetime | `native-runtime.js`, `effect-runtime.js`, `navigation-runtime.js` | Effects invalidate stale work, but pending native handlers can write after route unmount |
+| Browser lifetime | `native-runtime.js`, `effect-runtime.js`, `navigation-runtime.js` | Effects and native handlers invalidate stale writes at their existing effect or DOM ownership boundary |
 | Compatibility | React/Router/Zustand passes plus core branches | Package-specific knowledge is not contained behind one adapter boundary |
 | AI interface | CLI and string diagnostics | No stable diagnostic codes, semantic index, explain, fix, or migration analysis output |
 
@@ -131,7 +131,9 @@ This is an incremental evolution of the current repository:
 
 - [x] P0.1 Source-local binding index is complete in `0.8.28`. Reactive binding capture/import discovery and lowering use the index only when the complete expression is indexed; synthesized keyed expressions retain the existing fail-safe path. Focused scope tests, a 1,000-reference guard, browser integration, all 185 tests, and packed-package smoke pass.
 - [x] P0.2 Symbol-aware descriptor discovery is complete in `0.8.29`. Native handler, effect, remaining binding, list evaluator, optimized-command, and effect-resource discovery/lowering use the source-local binding index when it owns the complete AST; synthesized trees retain the existing fail-safe path. Focused lexical-shadow, JSON-safe IR, resource-ownership checks, all 187 tests, and packed-package smoke pass.
-- [ ] P0.3 Graph diagnostics is next. It must fail unresolved relative imports/re-exports and ordinary dynamic imports at the importer source location without broadening into ProjectSession or cross-module symbol work.
+- [x] P0.3 Graph diagnostics is complete in `0.8.30`. Reachable ordinary modules validate relative runtime imports/re-exports and reject every dynamic `import()` at the importer source location before compilation or generated module loading. Ordinary and Worker traversal retain separate ownership, type-only and unreachable edges remain excluded, focused page/helper/re-export/dynamic fixtures pass with all 189 tests and packed-package smoke, and no export-symbol graph, ProjectSession, runtime, or public API is added.
+- [x] P0.4 Async native handler ownership is complete in `0.8.31`. Mounted native registrations invalidate direct/captured setters, queued commits, and captured refs before listener removal. Chrome route, keyed-row, document-disposal, and synchronous event-dispatch checks, all 189 tests, and packed-package smoke pass without cancelling application promises or adding a scheduler.
+- [ ] P0.5 Atomic and collision-safe output is next. Failed builds must preserve prior output and public content must not overwrite generated artifacts.
 
 ### P0: Semantic Correctness And Compiler Foundation
 
@@ -271,6 +273,8 @@ Every result carries a stable source-local binding slot, debug name, declaration
 
 **Done condition:** a handler resolving after enhanced navigation or row removal cannot recreate or mutate released state, refs, or DOM.
 
+**Completed in `0.8.31`:** the existing native registration lifetime now guards state mutation, queued commits, and captured ref lookup. Route and keyed-row browser checks recreate the same ownership IDs before old work resolves, and document disposal invalidates a pending layout handler. Replacement state and DOM remain fresh. Both 5,000-event Chrome dispatch medians are 6.4 ms, and the 209 B raw / 94 B aggregate gzip runtime cost is recorded in `PERFORMANCE.md`.
+
 ### PR 5: Atomic And Collision-Safe Output
 
 **Objective:** make production builds safe before scaling the build graph.
@@ -453,6 +457,4 @@ The first comparison is Kudzu versus React + Vite using the same agent, model, t
 
 ## Immediate Decision
 
-The first implementation PR is **PR 1: Source-Local Binding Index**. It is compile-time only, adds no browser bytes or public API, fixes an existing correctness class, and creates the stable semantic foundation required by component graphs, state operations, cross-module analysis, compatibility adapters, structured diagnostics, and AI explanation tooling.
-
-The next PR is **PR 3: Graph Failure Diagnostics**. Do not skip directly to a store, resource, router, virtualization, or ecosystem package feature.
+PR 1 through PR 4 are complete. The next PR is **PR 5: Atomic And Collision-Safe Output**. 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.29` are completed scopes represented by package/release records.
+This is an execution sequence, not release history. `0.8.16` through `0.8.31` 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.
 
@@ -20,6 +20,8 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 | `0.8.27` | Characterize the first Goal C browser-resource boundary and publish the ordered large-application and AI-native compiler execution plan. | The E2B-derived fixture fails with a source-located diagnostic, no resource runtime or API is added, and the next PR dependencies and completion evidence are explicit. |
 | `0.8.28` | Add the source-local binding index and adopt it for reactive binding capture/import discovery and lowering. | Lexical shadowing is identity-based for complete indexed bindings, synthesized keyed expressions retain their fallback, the 1,000-reference guard passes, and no browser bytes or public API are added. |
 | `0.8.29` | Move native handler, effect, remaining binding, list evaluator, optimized-command, and effect-resource discovery/lowering onto source-local lexical identity. | Shadowed imports/globals/state/resources remain distinct, HandlerIR/BindingIR round trips pass, synthesized trees retain the fallback, and no runtime or public API is added. |
+| `0.8.30` | Validate ordinary runtime graph edges before code generation and reject dynamic imports at the importer source. | Page/helper/re-export/dynamic fixtures report original file/range/specifier without `.kudzu` paths; Worker, type-only, unreachable, output, and runtime behavior remain unchanged. |
+| `0.8.31` | Invalidate pending native-handler contexts when their route, keyed, conditional, or document DOM owner is released. | Late setters, queued commits, and captured refs cannot mutate replacement ownership; synchronous dispatch remains within the performance gate and runtime bytes are recorded. |
 
 ## Sequence Rules
 

package/framework/README.md

@@ -63,7 +63,7 @@ Reduced Zustand migration stores lower to one ordinary layout-lifetime state slo
 - `list-runtime.js`: optional keyed list validation, external item-expression evaluation, item-local conditional ranges, dynamic styles, item handler/effect scopes, moves, and cleanup.
 - `serialization.js`: capture deserialization shared by binding and native handlers.
 - `effect-runtime.js`: optional state and capture context for route-specific mount-effect entries.
-- `native-runtime.js`: optional runtime for normal synchronous and asynchronous ESM handlers.
+- `native-runtime.js`: optional runtime for normal synchronous and asynchronous ESM handlers; DOM unmount invalidates late state writes, queued commits, and captured refs.
 - `navigation-runtime.js`: optional emitted-route complete-document prefetch, runtime segment matching, validation, finite memory caching, route-range replacement, history, focus, and native fallback, specialized once per configured shared-layout group.
 - `dev-state.js`: dev-only, short-lived logical-state snapshot validation and restoration.
 - `*.d.ts`: public TypeScript and JSX declarations.
@@ -90,4 +90,4 @@ A direct setter may cross one same-file or relative-imported component boundary
 
 `kudzu.config` may opt one emitted shared-layout group into same-document navigation with legacy `navigation: { routes: ["/product", "/items/[id]"] }`, or multiple groups with `navigation: { groups: [{ routes: [...] }, { routes: [...] }] }`. The forms are mutually exclusive. Identities are globally unique emitted exact paths or `runtimeParams` patterns; each group uses one page-exported layout function identity. Runtime records securely match concrete pathnames under `base`, and their cache-safe parameter initializer runs before route DOM/effects mount on every transition. Each group receives a deterministic route-hashed asset specialized to only its records, pattern decoder, and effect/parameter lifecycle needs. Cross-group and ungrouped anchors remain native and are not prefetched; overlapping path domains across groups fail the build. Route effect entries export cache-safe layout and route mount functions: layout effects, including conditional/keyed DOM-owned effects, persist for the group session; route effects receive a fresh owner registry after each route insertion; and non-persisted page disposal cleans route before layout. Direct primitive state, runtime parameter, and keyed-item property dependencies and cleanup are supported. Fragment payloads and coordinated View Transitions are not implemented.
 
-Cross-framework performance tables are historical snapshots from excluded workspaces and are not current rankings. `npm run benchmark` tracks the Worker build/graph fixture; `RUNS=21 npm run benchmark:keyed` tracks large keyed restoration with fresh Chrome profiles. Current methodology, raw arrays, external-fixture limits, and artifact deltas live in `PERFORMANCE.md` and the web docs.
+Cross-framework performance tables are historical snapshots from excluded workspaces and are not current rankings. `npm run benchmark` tracks the Worker build/graph fixture; `RUNS=21 npm run benchmark:keyed` tracks large keyed restoration; `BASELINE_ROOT=... npm run benchmark:native` tracks native dispatch and exact artifact changes. Current methodology, raw arrays, external-fixture limits, and artifact deltas live in `PERFORMANCE.md` and the web docs.

package/framework/compiler/source-compiler.mjs

@@ -18,7 +18,7 @@ import { assetPath, relativeModulePath, withBase } from "./path-helpers.mjs"
 import { createReactMigrationPass, reactMemoExpression } from "./react-migration-pass.mjs"
 import { normalizeRenderControlFlow } from "./render-control-pass.mjs"
 import { createRouterPass } from "./router-pass.mjs"
-import { parseSourceFile, resolveSourceImport, runtimeModuleReference } from "./source-graph.mjs"
+import { ordinaryRuntimeDependencies, parseSourceFile, resolveSourceImport, runtimeModuleReference } from "./source-graph.mjs"
 import { createWorkerCompiler } from "./worker-compiler.mjs"
 import { createZustandPass } from "./zustand-pass.mjs"
 
@@ -92,20 +92,27 @@ function emittedPackageReference(source, file, packages) {
 
 export function reachableSourceFiles(entries, sourceFiles, sourceIndex) {
   const reachable = new Set()
-  const queue = [...entries]
+  const ordinary = new Set()
+  const workers = new Set()
+  const queue = entries.map(file => ({ file, owner: "ordinary" }))
   while (queue.length) {
-    const file = queue.pop()
-    if (reachable.has(file)) continue
+    const { file, owner } = queue.pop()
+    const visited = owner === "ordinary" ? ordinary : workers
+    if (visited.has(file)) continue
+    visited.add(file)
     reachable.add(file)
     const sourceFile = parseSourceFile(file, sourceIndex.get(file))
+    if (owner === "ordinary") for (const target of ordinaryRuntimeDependencies(file, sourceFile, sourceFiles, isStaticImport)) queue.push({ file: target, owner: target.endsWith(".worker.ts") ? "worker" : owner })
     const visit = node => {
-      const specifier = (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && runtimeModuleReference(node) && node.moduleSpecifier
-      if (specifier && ts.isStringLiteral(specifier) && specifier.text.startsWith(".") && !isStaticImport(specifier.text)) {
-        try { queue.push(resolveSourceImport(file, specifier.text, sourceFiles)) } catch {}
+      if (owner === "worker") {
+        const specifier = (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && runtimeModuleReference(node) && node.moduleSpecifier
+        if (specifier && ts.isStringLiteral(specifier) && specifier.text.startsWith(".") && !isStaticImport(specifier.text)) {
+          try { queue.push({ file: resolveSourceImport(file, specifier.text, sourceFiles), owner }) } catch {}
+        }
       }
       const worker = workerCompiler.candidate(node, sourceFile)
       if (worker && ts.isStringLiteral(worker.url.arguments[0]) && worker.url.arguments[0].text.endsWith(".worker.ts")) {
-        try { queue.push(resolveSourceImport(file, worker.url.arguments[0].text, sourceFiles)) } catch {}
+        try { queue.push({ file: resolveSourceImport(file, worker.url.arguments[0].text, sourceFiles), owner: "worker" }) } catch {}
       }
       ts.forEachChild(node, visit)
     }
@@ -2667,15 +2674,6 @@ function hasFrameworkImport(sourceFile, name) {
 
 function packageImportBindings(sourceFile) {
   const bindings = new Map()
-  const rejectDynamic = node => {
-    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
-      const specifier = node.arguments.length === 1 && ts.isStringLiteralLike(node.arguments[0]) ? node.arguments[0].text : null
-      if (specifier === null) throw sourceNodeError(node, sourceFile, "Dynamic import specifiers are not supported")
-      if (!specifier.startsWith(".")) throw sourceNodeError(node, sourceFile, `Dynamic package import ${JSON.stringify(specifier)} is not supported`)
-    }
-    ts.forEachChild(node, rejectDynamic)
-  }
-  rejectDynamic(sourceFile)
   for (const node of sourceFile.statements) {
     if (!ts.isImportDeclaration(node) || !ts.isStringLiteral(node.moduleSpecifier)) continue
     const target = node.moduleSpecifier.text

package/framework/compiler/source-graph.mjs

@@ -1,5 +1,6 @@
 import { dirname, extname, join, relative, resolve } from "node:path"
 import ts from "typescript"
+import { sourceNodeError } from "./ast-helpers.mjs"
 
 const root = process.cwd()
 
@@ -24,6 +25,32 @@ export function runtimeModuleReference(node) {
   return clause.namedBindings?.elements.some(entry => !entry.isTypeOnly) ?? false
 }
 
+export function ordinaryRuntimeDependencies(file, sourceFile, sourceFiles, isStaticImport) {
+  const dependencies = []
+  const rejectDynamicImports = node => {
+    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+      const argument = node.arguments[0]
+      const specifier = node.arguments.length === 1 && ts.isStringLiteralLike(argument) ? JSON.stringify(argument.text) : argument?.getText(sourceFile) ?? "<missing>"
+      throw sourceNodeError(node, sourceFile, `Dynamic import ${specifier} is not supported in ordinary source modules`)
+    }
+    ts.forEachChild(node, rejectDynamicImports)
+  }
+  rejectDynamicImports(sourceFile)
+  for (const node of sourceFile.statements) {
+    if ((!ts.isImportDeclaration(node) && !ts.isExportDeclaration(node)) || !runtimeModuleReference(node) || !node.moduleSpecifier || !ts.isStringLiteral(node.moduleSpecifier)) continue
+    const specifier = node.moduleSpecifier
+    if (!specifier.text.startsWith(".") || isStaticImport(specifier.text)) continue
+    try {
+      dependencies.push(resolveSourceImport(file, specifier.text, sourceFiles))
+    } catch (error) {
+      const detail = error.message.slice(error.message.indexOf("Relative import"))
+      const edge = ts.isExportDeclaration(node) ? "re-export" : "import"
+      throw sourceNodeError(specifier, sourceFile, detail.replace("Relative import", `Relative runtime ${edge}`))
+    }
+  }
+  return dependencies
+}
+
 export function parseSourceFile(file, source) {
   return ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true, file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS)
 }

package/framework/native-runtime.js

@@ -8,18 +8,20 @@ export function registerNativeModules(entries) {
   for (const [url, module] of entries) modules.set(url, module)
 }
 
-export function createNativeContext(state, stateIds, commit, serializedScope = {}) {
+export function createNativeContext(state, stateIds, commit, serializedScope = {}, active = () => true) {
   const changed = new Set()
   let scheduled = false
 
   const flush = () => {
     scheduled = false
+    if (!active()) return changed.clear()
     const ids = [...changed]
     changed.clear()
     for (const id of ids) commit(id, state.get(id))
   }
 
   const setId = globalThis.__KUDZU_CAPTURE_SETTER__ ? (id, value) => {
+    if (!active()) return
     const current = state.get(id)
     state.set(id, typeof value === "function" ? value(current) : value)
     changed.add(id)
@@ -29,7 +31,7 @@ export function createNativeContext(state, stateIds, commit, serializedScope = {
     }
   } : undefined
 
-  const scope = Object.fromEntries(Object.entries(serializedScope).map(([name, value]) => [name, deserialize(value, id => state.get(id), globalThis.__KUDZU_CAPTURE_SETTER__ ? setId : undefined)]))
+  const scope = Object.fromEntries(Object.entries(serializedScope).map(([name, value]) => [name, deserialize(value, id => state.get(id), globalThis.__KUDZU_CAPTURE_SETTER__ ? setId : undefined, active)]))
 
   return {
     get(name) {
@@ -43,6 +45,7 @@ export function createNativeContext(state, stateIds, commit, serializedScope = {
         setId(stateIds[name], value)
         return
       }
+      if (!active()) return
       const id = stateIds[name]
       const current = state.get(id)
       state.set(id, typeof value === "function" ? value(current) : value)
@@ -61,6 +64,9 @@ if (typeof document !== "undefined") {
   registerMountHook(mount)
   registerUnmountHook(unmountNative)
   mount(document)
+  addEventListener("pagehide", event => {
+    if (!event.persisted) unmountNative(document)
+  })
 }
 
 function mountNative(root, eventNames, modules) {
@@ -71,14 +77,16 @@ function mountNative(root, eventNames, modules) {
       let encoded = node.dataset[`kNative${capitalize(eventName)}`]
       let native = JSON.parse(encoded)
       let handler
-      let context = createNativeContext(browserState, native.states, commitDom, native.scope)
+      const registration = { active: true }
+      const active = () => registration.active
+      let context = createNativeContext(browserState, native.states, commitDom, native.scope, active)
       const listener = event => {
         try {
           const current = node.dataset[`kNative${capitalize(eventName)}`]
           if (current !== encoded) {
             native = JSON.parse(current)
             encoded = current
-            context = createNativeContext(browserState, native.states, commitDom, native.scope)
+            context = createNativeContext(browserState, native.states, commitDom, native.scope, active)
             handler = undefined
           }
           handler ??= modules.get(native.module)[native.handler]
@@ -88,8 +96,9 @@ function mountNative(root, eventNames, modules) {
           console.error(error)
         }
       }
+      registration.listener = listener
       node.addEventListener(eventName, listener)
-      listeners.set(eventName, listener)
+      listeners.set(eventName, registration)
       registrations.set(node, listeners)
     }
   }
@@ -97,7 +106,10 @@ function mountNative(root, eventNames, modules) {
 
 function unmountNative(root) {
   for (const node of matching(root, "*")) {
-    for (const [eventName, listener] of registrations.get(node) ?? []) node.removeEventListener(eventName, listener)
+    for (const [eventName, registration] of registrations.get(node) ?? []) {
+      registration.active = false
+      node.removeEventListener(eventName, registration.listener)
+    }
     registrations.delete(node)
   }
 }

package/framework/serialization.js

@@ -1,8 +1,8 @@
-export function deserialize(value, getState, setState) {
+export function deserialize(value, getState, setState, active) {
   if (!value || typeof value !== "object") return value
   if (value.type === "undefined") return undefined
   if (value.type === "number") return value.value === "NaN" ? NaN : value.value === "Infinity" ? Infinity : value.value === "-Infinity" ? -Infinity : -0
-  if (value.type === "ref") return { get current() { return typeof document === "undefined" ? null : document.querySelector(`[data-k-ref="${value.id}"]`) } }
+  if (value.type === "ref") return { get current() { return typeof document === "undefined" || active?.() === false ? null : document.querySelector(`[data-k-ref="${value.id}"]`) } }
   if (globalThis.__KUDZU_CAPTURE_STATE__ && value.type === "state") return getState?.(value.id)
   if (globalThis.__KUDZU_CAPTURE_SETTER__ && value.type === "setter") return next => {
     if (!setState) throw new Error("Captured state setter is not available in this context")
@@ -10,20 +10,20 @@ export function deserialize(value, getState, setState) {
   }
   if (value.type === "array") {
     const array = []
-    for (const [index, entry] of value.value.entries()) defineCapture(array, String(index), entry, getState, setState)
+    for (const [index, entry] of value.value.entries()) defineCapture(array, String(index), entry, getState, setState, active)
     return array
   }
   if (value.type === "object") {
     const object = value.nullPrototype ? Object.create(null) : {}
-    for (const [key, entry] of value.value) defineCapture(object, key, entry, getState, setState)
+    for (const [key, entry] of value.value) defineCapture(object, key, entry, getState, setState, active)
     return object
   }
   return value
 }
 
-function defineCapture(target, key, entry, getState, setState) {
+function defineCapture(target, key, entry, getState, setState, active) {
   const descriptor = globalThis.__KUDZU_CAPTURE_STATE__ && entry?.type === "state" && getState
     ? { get: () => getState(entry.id) }
-    : { value: deserialize(entry, getState, setState), writable: true }
+    : { value: deserialize(entry, getState, setState, active), writable: true }
   Object.defineProperty(target, key, { ...descriptor, enumerable: true, configurable: true })
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.8.29",
+  "version": "0.8.31",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",
@@ -58,6 +58,7 @@
     "benchmark": "node test/performance.mjs",
     "benchmark:keyed": "node test/keyed-performance.mjs",
     "benchmark:commerce": "node test/commerce-build-performance.mjs",
+    "benchmark:native": "node test/native-performance.mjs",
     "prepublishOnly": "npm run check && npm test",
     "deploy": "wrangler deploy",
     "preview": "wrangler dev"