@kudzujs/core 0.8.26 → 0.8.27

package/MIGRATION_ROADMAP.md

@@ -2,6 +2,8 @@
 
 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.27` 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.
 
 ## North Star
@@ -262,6 +264,12 @@ This queue orders the next investigations by general migration value. Start only
 - The standard suite counts exact route-entry transforms across repeated, distinct, and new-build sources and protects the safe keyed bulk-mount guard plus its per-root fallback.
 - Goal B records which build, output, keyed, Worker, integration, and heap evidence exists; no new optimization is authorized without another reproduced material loss.
 
+### Characterized In 0.8.27
+
+- A reduced E2B Dashboard terminal fixture establishes callback-shared mutable browser resources, asynchronous generation invalidation, and BFCache retain/resume/discard behavior as a concrete Goal C boundary.
+- Unsupported page-level mutable value refs fail during source analysis with a source location and the existing effect-owned animation-frame exception; no resource API or runtime is added.
+- The large-application and AI-native execution plan orders symbol resolution, semantic operations, project/module analysis, IR authority, application foundations, ecosystem compatibility, AI tooling, and scale validation before broad feature work.
+
 ## Cross-Cutting Performance Gates
 
 Every migration feature must preserve:

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.26 - Goal B benchmark hardening.** Commerce comparisons now require byte-identical output by default, and the standard suite protects exact route-entry transform reuse plus safe keyed bulk-mount selection. Read the [release notes](./RELEASES.md#0826---goal-b-benchmark-hardening), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.26), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.8.27 - Large-application compiler roadmap.** A reduced E2B terminal fixture now establishes the first Goal C resource boundary with a source-located diagnostic, while the architecture packet fixes the ordered semantic-compiler, application-scale, compatibility, AI-tooling, and production-validation program. Read the [release notes](./RELEASES.md#0827---large-application-compiler-roadmap), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.27), 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,35 @@
 # Kudzu Releases
 
+## 0.8.27 - Large-application compiler roadmap
+
+Kudzu 0.8.27 records the evidence-backed path from the current static-first compiler to large production applications without adding a React runtime, generic client framework, or speculative resource API.
+
+### Changed in 0.8.27
+
+- A reduced fixture from E2B Dashboard preserves a callback-shared terminal handle, asynchronous generation token, BFCache retention, resume, and discard cleanup as the first concrete Goal C resource-ownership boundary.
+- Unsupported page-level mutable value refs now fail during source analysis with the source location and the existing effect-owned animation-frame exception instead of reaching the build-time DOM-ref runtime error.
+- Goal C records independent WebSocket/SSE, shared request, and optimistic transaction candidates while explicitly withholding store, resource, query, cache, Provider, subscription, and scheduler APIs.
+- The new large-application and AI-native execution plan audits the current compiler, IR, runtime, navigation, package, build, fixture, and benchmark boundaries and orders the next twelve independently verifiable PRs.
+- The next implementation is fixed as a source-local binding index followed by symbol-aware descriptor discovery; ecosystem features cannot skip those semantic dependencies.
+
+### Architecture Boundary
+
+- Existing ComponentAnalysis, ModuleIR, RouteIR, CapabilityIR, complete HTML, direct DOM ownership, native navigation, and capability runtimes remain the incremental foundation.
+- The plan generalizes symbol identity, semantic state operations, component/module dataflow, resource/range ownership, artifact references, code splitting, diagnostics, migration analysis, and application-scale evidence without introducing a browser component tree.
+- React ecosystem support is classified as Native, Compiled, Migrated, Adapter, Partial, or Unsupported so package-specific knowledge can move behind a compatibility boundary instead of accumulating in the core compiler.
+
+### Validation
+
+- `npm run check`, `npm run test:package`, and all 176 tests pass.
+- The E2B fixture remains an expected failure at its proven source boundary; no browser resource runtime or public API is emitted.
+- Static-route zero JavaScript, existing animation-frame support, keyed-row diagnostics, setter-child diagnostics, and all current browser ownership behavior remain covered.
+
+### Upgrade
+
+```bash
+npm install @kudzujs/core@^0.8.27
+```
+
 ## 0.8.26 - Goal B benchmark hardening
 
 Kudzu 0.8.26 makes the retained Goal B optimizations reproducible and directly regression-tested without changing generated runtime behavior or authoring support.

package/docs/next-architecture/README.md

@@ -11,6 +11,8 @@ 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.27` 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.
+
 ## Required Invariants
 
 - Every route remains a complete static HTML document.
@@ -24,16 +26,18 @@ The top-level [`GOAL_A.md`](../../GOAL_A.md) and [`GOAL_B.md`](../../GOAL_B.md)
 ## Reading Order
 
 1. [`compiler-current-architecture.md`](./compiler-current-architecture.md): exact current responsibilities and data flow.
-2. [`goal-a-compiler-foundation.md`](./goal-a-compiler-foundation.md): approved extraction and generator work.
-3. [`versioning.md`](./versioning.md): planned patch sequence and completion rules.
-4. [`performance-gates.md`](./performance-gates.md): output, build, and browser gates.
-5. [`goal-b-optimization-benchmarks.md`](./goal-b-optimization-benchmarks.md): active measurements, retained optimizations, and continuation rules.
-6. [`goal-c-state-resource-research.md`](./goal-c-state-resource-research.md): research boundary only.
-7. [`goal-d-routing-compatibility-decisions.md`](./goal-d-routing-compatibility-decisions.md): routing and islands decisions.
+2. [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md): active direction, priorities, PR queue, and completion evidence.
+3. [`goal-a-compiler-foundation.md`](./goal-a-compiler-foundation.md): completed extraction and generator foundation.
+4. [`versioning.md`](./versioning.md): completed patch sequence and future sequencing rules.
+5. [`performance-gates.md`](./performance-gates.md): output, build, and browser gates.
+6. [`goal-b-optimization-benchmarks.md`](./goal-b-optimization-benchmarks.md): active measurements, retained optimizations, and continuation rules.
+7. [`goal-c-state-resource-research.md`](./goal-c-state-resource-research.md): research boundary only.
+8. [`goal-d-routing-compatibility-decisions.md`](./goal-d-routing-compatibility-decisions.md): routing and islands decisions.
 
 ## Resume Checklist
 
 - [ ] Read [`MIGRATION_ROADMAP.md`](../../MIGRATION_ROADMAP.md) and this directory before planning migration work.
+- [ ] Follow the PR dependency order in [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md); update it before broadening or reordering a patch.
 - [ ] Confirm `package.json` still reports the actual current version; never infer release status from this plan.
 - [ ] Inspect the worktree and preserve unrelated or uncommitted changes.
 - [ ] Start later architecture work only by an explicit decision from the completed Goal A baseline.

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

@@ -1,6 +1,6 @@
 # Current Compiler Architecture
 
-This maps the current `0.8.26` 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.27` 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
 

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

@@ -36,6 +36,40 @@ Before any proposal, provide:
 - output and ownership costs;
 - an explanation of why existing async build rendering, state/effects, layout ownership, native platform storage, or effect-owned resources are insufficient.
 
+## First Application Survey
+
+The first GitHub survey used active licensed React/TypeScript applications rather than library demos. It found four distinct pressure families:
+
+| Application evidence | Ownership pressure | Research disposition |
+|---|---|---|
+| [E2B Dashboard terminal](https://github.com/e2b-dev/dashboard/blob/97164c9cbc8ced05b9039415318550f4e4df3874/src/features/dashboard/terminal/dashboard-terminal.tsx) | Mutable remote handle and generation tokens survive callbacks; BFCache entry retains the handle, real discard closes it, and restore resumes it | First reduced fixture because it is the smallest precise lifetime |
+| [Mattermost WebSocket client](https://github.com/mattermost/mattermost/blob/53373e3752c6e8d7979b787f342fea4c56e68472/webapp/platform/client/src/websocket.ts) and [Twenty SSE provider](https://github.com/twentyhq/twenty/blob/cd288d84470503ba897c0823a9d98701fa9986ab/packages/twenty-front/src/modules/sse-db-event/components/SSEProvider.tsx) | One document/layout transport has many independently mounted route subscribers plus reconnect and replay state | Strong cross-owner subscription research; too broad for the first fixture |
+| [Actual Budget queries](https://github.com/actualbudget/actual/blob/87e33e49eb4d666c33e0c0f172faf340d1b7aa0a/packages/desktop-client/src/payees/queries.ts) and [Plane workspace wrapper](https://github.com/makeplane/plane/blob/31853ab2b8b7810c59dc30d22e52c8f4b5a71a47/apps/web/core/layouts/auth-layout/workspace-wrapper.tsx) | Shared keyed request results outlive route consumers and are invalidated by external events or owner changes | Candidate for keyed layout/document ownership, not authorization for a query API |
+| [InstantDB optimistic update](https://github.com/instantdb/instant/blob/30561b01ea850514dd4e0270bdd6ff3ed159bbb1/client/www/lib/auth.ts) and [Raven reaction update](https://github.com/The-Commit-Company/raven/blob/a29a274466b7a060754839b3c8e29bbee012a61d/packages/lib/hooks/useReactToMessage.ts) | Multiple consumers observe one optimistic snapshot that must commit or roll back atomically | Two independent examples of shared optimistic transactions; still research only |
+
+### E2B Reduced Fixture
+
+The repository-owned fixture at `test/fixtures/goal-c-e2b-terminal` preserves the relevant conventional React shape without E2B's UI, SDK, or `useEffectEvent` dependency:
+
+- one `null`-initialized remote handle ref;
+- one numeric generation ref invalidating late asynchronous opens;
+- `pagehide.persisted` retaining the handle for BFCache;
+- non-persisted `pagehide` and effect cleanup closing it;
+- `pageshow.persisted` resuming the retained handle;
+- one unrelated static sibling route.
+
+The build fails before BFCache behavior can be evaluated:
+
+```text
+src/pages/index.tsx:7:25 Mutable value useRef() is unsupported except for an effect-owned useRef(0) animation-frame handle; otherwise keep resource-private mutable values inside the owning effect
+```
+
+The failure is triggered by the ordinary `useRef(0)` generation token during source analysis. Existing animation-frame specialization cannot safely cover this shape: the generation token has different writes and callback ownership, while the remote handle is a browser-only non-serializable value rather than a DOM ref. Supporting only the token would expose incorrect DOM-ref semantics for the handle.
+
+The remaining question before any state/resource API discussion is whether independent fixtures justify a narrow specialization for callback-shared effect resources with document and BFCache ownership. Until then, the source-located diagnostic preserves the current boundary.
+
+An effect-local rewrite is a useful control, but requiring applications to restructure ordinary callback-shared refs is not automatically an acceptable migration solution. The fixture remains an expected failure until research answers that boundary.
+
 ## Decision Boundary
 
 Research may produce notes, fixtures, measurements, or a narrow compiler-specialization proposal. It must not publish `createStore`, `resource`, `query`, cache, Provider, subscription, or scheduler APIs. A public API requires separate approval after at least two independent migration fixtures establish the same semantics and after zero-cost exclusion is demonstrated.

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

@@ -0,0 +1,452 @@
+# Large Application And AI-Native Development Plan
+
+## Status
+
+Active execution plan after `0.8.27`. 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.
+
+## Product Outcome
+
+Kudzu must support ordinary React-shaped TypeScript and TSX from small static sites through production SaaS, dashboards, CRUD, commerce, authenticated applications, realtime collaboration, data-heavy interfaces, and large module graphs. The browser should receive complete HTML and only the capabilities required by each route or application lifetime.
+
+The differentiating KPI is `cost per successful task`, not source line count alone. A successful task includes build, browser behavior, accessibility, output, and ownership checks. Track input/output/reasoning tokens, files read and modified, tool calls, compiler attempts, failed attempts, correction cycles, completion time, source retention, and final client bytes.
+
+The governing principle is:
+
+> Write what AI already knows. Compile away what AI should not need to reason about.
+
+## Audited Baseline
+
+The current implementation already provides:
+
+- complete route HTML and zero JavaScript for static routes;
+- synchronous logical state with direct DOM commits;
+- route, layout, conditional, keyed, effect, ref, and Worker ownership;
+- stable keyed row identity with nested lists, state, refs, effects, and SVG;
+- stale effect-invocation isolation and explicit cleanup;
+- narrow React, React Router, and Zustand-shaped normalization;
+- JSON-safe ComponentAnalysis, ModuleIR, RouteIR v1, and CapabilityIR v1;
+- no-write source compilation and capability-specific runtime emission;
+- source-located fail-closed diagnostics and broad reduced-fixture coverage.
+
+The current limiting architecture is observable in these files:
+
+| Concern | Current owner | Limitation to remove |
+|---|---|---|
+| Project graph | `framework/compiler/source-graph.mjs`, `framework/build.mjs` | Global root, repeated parsing, narrow export resolution, no incremental project session |
+| Normalization | `framework/compiler/source-compiler.mjs`, focused passes | Pass order and package ownership are implicit; semantically equal source often follows different shape-specific paths |
+| Component/state analysis | `framework/compiler/source-compiler.mjs`, `analysis/component-analysis.mjs` | AST identity, identifier text, source offsets, and caller-side AST specialization remain central |
+| Handler/binding analysis | `framework/compiler/descriptor-session.mjs`, `handler-lowering.mjs` | Capture/import/state discovery is name-based and arbitrary handlers become code before IR finalization |
+| Effect/resource analysis | `effect-analysis.mjs`, resource-specific passes | Selected browser APIs have exact-shape ownership checks; there is no package-neutral resource model |
+| Lists/ranges | `source-compiler.mjs`, `list-runtime.js` | Strong keyed ownership, but syntax recognition and runtime branches are list-specific and not a general range/window primitive |
+| 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 |
+| 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 |
+
+## Architecture Direction
+
+```text
+ProjectSession
+  -> parsed module and package graph
+  -> compatibility adapter registry
+  -> normalized modules with stable declaration/site identities
+  -> binding and symbol resolution
+  -> source semantic analysis
+       component and prop edges
+       state, derived, event, and operation edges
+       effect and resource ownership
+       collection and range ownership
+  -> strengthened existing ModuleIR
+  -> build-time render instantiation
+  -> RouteBuildRecord with RouteIR and artifact edges
+  -> per-route capability signature and chunk closure
+  -> HTML, CSS, and capability-specific ESM
+```
+
+This is an incremental evolution of the current repository:
+
+- Keep ComponentAnalysis and ModuleIR; make their references stable and their records authoritative.
+- Keep `renderPage()` for build-known execution and concrete route ownership IDs; stop using it to rediscover source semantics already present in ModuleIR.
+- Keep RouteIR and CapabilityIR; deepen validation and replace parallel route facts with one RouteBuildRecord.
+- Keep existing browser runtimes; extract package-neutral semantic primitives only after fixtures prove repeated ownership needs.
+- Do not introduce a general JavaScript bytecode VM or model the complete TypeScript language in a new IR.
+
+## Required Invariants
+
+- Static routes remain zero JavaScript.
+- Interactive routes add no capability unrelated to their source and route lifetime.
+- Complete HTML remains the initial document.
+- Native navigation remains the fallback and default.
+- React and ecosystem package source may be accepted, normalized, migrated, or adapted without executing React.
+- Package-specific knowledge must not leak beyond the compatibility boundary into generic ownership, dataflow, IR, or browser runtime code.
+- New semantic support starts from a real or reduced failing application fixture.
+- Every patch is independently reviewable, fail-closed, and measured against representative output.
+- A compiler refactor must preserve accepted source, diagnostics, RouteIR, HTML, assets, and browser ownership unless its scope explicitly changes one contract.
+
+## Preserve, Refactor, Avoid
+
+### Preserve
+
+- Build-known execution and complete static output.
+- Direct DOM ownership and synchronous logical state.
+- Route/layout/key-path lifetime semantics.
+- Keyed identity and exact state/effect/ref release.
+- Effect invalidation and cleanup.
+- JSON-safe, versioned stage boundaries.
+- Source-located diagnostics.
+- Rendered Worker exclusion and content hashing.
+- Capability-specific output with no React runtime.
+
+### Refactor
+
+- Identifier text into resolved SymbolRef records.
+- AST identity and `pos:end` keys into stable source-local declaration/site IDs.
+- Exact setter syntax into semantic value and state-operation analysis.
+- Caller-side component AST copying into a component/prop/callback graph.
+- Manual export discovery into a project module-symbol graph.
+- Primitive-only dependencies into property-path and derived dependencies.
+- Resource-specific ownership passes into a package-neutral ResourceIR when evidence permits.
+- Serialized handler URL searches into explicit artifact references.
+- Site-wide capability unions into route capability signatures.
+- Full destructive development builds into project-session invalidation and atomic output.
+- String-only diagnostics into structured diagnostics suitable for machines and AI agents.
+
+### Avoid
+
+- React runtime fallback, hydration, islands, or a browser component tree.
+- Public Kudzu-specific router, query, store, form, or scheduler APIs before migration evidence.
+- One core pass per ecosystem package.
+- A generic rerender engine or general callback registry.
+- Incomplete dynamic import support.
+- Speculative cache, virtualization, portal, stream, or resource runtimes.
+- File splitting that does not reduce semantic coupling.
+
+## Priority Program
+
+### P0: Semantic Correctness And Compiler Foundation
+
+P0 creates the semantic base required by every later large-application capability. Do not begin broad ecosystem or application features before the relevant P0 dependencies are complete.
+
+| Order | Objective | Dependency | Completion evidence |
+|---|---|---|---|
+| P0.1 | Source-local binding index | None | Local, parameter, import, capture, global, and unresolved references are classified consistently |
+| P0.2 | Descriptor consumers use SymbolRef | P0.1 | Handler/effect/binding capture and import discovery no longer depends only on text names |
+| P0.3 | Graph diagnostics | P0.1 | Relative dynamic imports and unresolved runtime edges fail at the source location |
+| P0.4 | Async native handler ownership | None | Pending handlers cannot write after route or DOM ownership is released |
+| P0.5 | Atomic collision-safe build | None | Failed builds preserve prior output and public files cannot overwrite generated artifacts |
+| P0.6 | Explicit ProjectSession | P0.1 | Root and caches are build-scoped; two projects can compile safely in one process |
+| P0.7 | Parsed module/export cache | P0.6 | Shared modules are parsed and summarized once per build |
+| P0.8 | Stable ModuleSymbol and SiteId | P0.6-P0.7 | Imports, re-exports, aliases, owners, and call sites use stable identities outside a pass |
+| P0.9 | Semantic state-operation analysis | P0.1, P0.8 | Equivalent setter/helper forms lower to the same state operation |
+| P0.10 | ModuleIR reference unification | P0.8-P0.9 | Signals, bindings, effects, keyed blocks, handlers, and owners use validated slots/symbols |
+| P0.11 | Explicit route artifact graph | P0.10 | Handler/Worker/CSS/chunk retention uses structural references, not serialized string searches |
+| P0.12 | Deep RouteIR and CapabilityIR validation | P0.10-P0.11 | Invalid state, effect, binding, list, ownership, and artifact references fail before codegen |
+
+### P1: Large Application Foundations
+
+| Objective | Required result |
+|---|---|
+| Cross-module component and prop dataflow | Deep composition, callbacks, setters, refs, context, and children retain semantic links without repeated AST inlining |
+| Property-level derived dependencies | Object state can expose path-level dependencies without splitting application state into artificial primitives |
+| Package-neutral shared state and actions | Existing Zustand support lowers through generic signal/action records; Redux-shaped research has a reusable target |
+| Resource ownership | WebSocket, SSE, subscriptions, timers, observers, Workers, and imperative SDKs can share acquire/owner/dependency/cleanup semantics |
+| Browser-only package modules | Native JS packages may be bundled only into effect/handler/resource chunks without build-time execution |
+| Range ownership | Conditional, keyed, overlay, and future virtualized DOM ranges share release and identity primitives where semantics match |
+| Route/layout graph | Nested persistent layouts and route lifetimes remain complete-document based and recoverable through native navigation |
+| Route capability and chunk closure | Every route reports exact runtime, handler, package, Worker, and shared chunk edges |
+| Route/layout CSS closure | Unrelated feature CSS is absent from a route unless configured global |
+| Incremental development build | A source change recompiles and rerenders only affected modules/routes while preserving full reload correctness |
+| Source-scale benchmark | At least 500 reachable modules, 50,000 TS/TSX lines, 50 routes, phase timings, and peak RSS |
+
+### P2: Compatibility And Migration
+
+- Add an internal compatibility adapter registry.
+- Consolidate React compatibility ownership behind one adapter contract.
+- Register React Router ownership without changing native navigation semantics.
+- Move Zustand-specific logic out of generic core, handler, and state paths onto package-neutral shared-state/action IR.
+- Characterize Redux/RTK, TanStack Query, React Hook Form, Zod, Radix/Headless UI/MUI, CSS-in-JS, animation, chart, drag/drop, virtualization, auth, REST, and GraphQL against real application fixtures.
+- Prefer native packages and Web APIs, then compilation, deterministic migration, adapters, partial support, or explicit unsupported status in that order.
+- Publish no public adapter API until an external adapter requires independent versioning.
+
+### P3: AI Compiler Interface
+
+- `kudzu check --json` with stable code, stage, file/range, symbols, module/component/ownership paths, compatibility status, suggestions, and safe fixes.
+- `kudzu explain [route|symbol] --json` from the semantic and artifact graphs.
+- `kudzu fix` only for deterministic changes whose preconditions the compiler proves.
+- `kudzu migrate --analyze` for module, component, route, package, state, effect, resource, and blocker inventory.
+- Migration readiness percentages must be calculated from actual classified modules/use sites, never estimated.
+
+### P4: Production And Scale Validation
+
+- Maintain Tier 1 reduced fixtures, Tier 2 complete small/medium apps, Tier 3 large production slices, and Tier 4 whole existing React applications.
+- Require Chrome, Firefox, and WebKit journeys for production candidates.
+- Add source maps, accessibility automation, keyboard journeys, security checks, output manifests, long-navigation heap tests, and deployment/cache guidance.
+- Compare Kudzu and React + Vite first with the same agent, model, tools, task, and acceptance checks; expand only after the protocol is stable.
+- Report median and range for tokens, cost, file reads, tool calls, builds, failures, completion time, source retention, output bytes, and accepted behavior.
+
+## PR Execution Queue
+
+### PR 1: Source-Local Binding Index
+
+**Objective:** establish one correct reference classifier before further compiler generalization.
+
+**Current problem:** `descriptor-session.mjs`, migration passes, and source analysis use identifier text plus separate shadow walkers. A local named like a browser global or import can be classified incorrectly, and later cross-module work has no stable foundation.
+
+**Files:**
+
+- Add `framework/compiler/analysis/binding-index.mjs`.
+- Add `test/binding-index.test.mjs`.
+- Update `framework/compiler/ast-helpers.mjs` only for shared scope primitives proven necessary.
+- Update a narrow capture/import consumer in `framework/compiler/descriptor-session.mjs`.
+
+**Internal contract:**
+
+```text
+resolveReference(identifier)
+  -> local declaration
+  -> parameter
+  -> import
+  -> outer lexical capture
+  -> known global
+  -> unresolved
+```
+
+Every result carries a stable source-local binding slot, debug name, declaration range when present, and reference range. AST nodes remain source-session-local and do not enter JSON-safe IR.
+
+**Not in scope:**
+
+- Cross-module TypeScript Program.
+- Component graph changes.
+- New accepted React syntax.
+- Handler operation IR.
+- Public API or runtime changes.
+
+**Tests:**
+
+- Shadowed `document`, `location`, `history`, `navigator`, and `console`.
+- Imported name shadowed by callback parameter or local declaration.
+- Outer component capture versus callback-local binding.
+- State/setter name collision across owners.
+- Existing Router, React, binding, native handler, and effect fixtures.
+
+**Performance check:** create a focused synthetic source with at least 1,000 references and record index construction and lookup time. The purpose is a regression guard, not an optimization claim.
+
+**Done condition:** capture/import classification uses the binding index for the selected consumer, all existing tests pass, representative generated artifacts remain byte-identical except for an explicitly corrected shadowing case, and no browser bytes are added.
+
+### PR 2: Symbol-Aware Descriptor Discovery
+
+**Objective:** move native handler, effect, and binding capture/import discovery onto the P0.1 binding index.
+
+**Files:** `descriptor-session.mjs`, `handler-lowering.mjs`, `effect-analysis.mjs`, compiler tests.
+
+**Tests:** shadowed imports/globals in native handlers, effects, bindings, and list evaluators; JSON-safe HandlerIR/BindingIR round trips.
+
+**Done condition:** these analyses no longer decide identity from identifier text alone; output and diagnostics remain equivalent for existing accepted source.
+
+### PR 3: Graph Failure Diagnostics
+
+**Objective:** fail early for runtime graph edges the compiler cannot emit safely.
+
+**Files:** `source-graph.mjs`, `source-compiler.mjs`; add page/helper/re-export invalid fixtures.
+
+**Done condition:** unresolved relative imports/re-exports and ordinary dynamic imports report importer, source range, and specifier; no generated `.kudzu` path is the primary diagnostic.
+
+### PR 4: Async Native Handler Invalidation
+
+**Objective:** prevent late async event work from mutating released route/keyed ownership.
+
+**Files:** `native-runtime.js`, navigation/list ownership integration, browser test fixture.
+
+**Performance check:** compare synchronous event dispatch before and after; no material regression.
+
+**Done condition:** a handler resolving after enhanced navigation or row removal cannot recreate or mutate released state, refs, or DOM.
+
+### PR 5: Atomic And Collision-Safe Output
+
+**Objective:** make production builds safe before scaling the build graph.
+
+**Files:** `build.mjs`, build integration tests.
+
+**Tests:** public collisions with route HTML, core runtime, handler entry, chunk, Worker namespace, source CSS, and configured CSS; failed build preserves prior `dist`.
+
+**Done condition:** output is staged, validated, and atomically promoted; public content cannot silently replace generated artifacts.
+
+### PR 6: ProjectSession And Explicit Root
+
+**Objective:** remove import-time project globals and establish build-scoped graph/cache ownership.
+
+**Files:** add `compiler/project-session.mjs`; update build, source graph, source compiler, and tests.
+
+**Done condition:** two independent roots compile in one process, current CLI behavior and artifacts remain unchanged, and source caches cannot leak between projects.
+
+### PR 7: Parsed Module And Export Summary Cache
+
+**Objective:** make work proportional to unique modules instead of importer edges.
+
+**Dependency:** PR 6.
+
+**Test fixture:** at least 100 importers sharing component/helper modules; expose parse/summary counters in tests without production logging.
+
+**Done condition:** each unchanged module is parsed and summarized once per project session; transformed mutable AST is not shared across transformer contexts.
+
+### PR 8: Stable ModuleSymbol And SiteId
+
+**Objective:** represent declarations, imports, re-exports, component calls, hooks, and ownership sites independently of transformed AST identity.
+
+**Tests:** default/named exports, aliases, barrel chains, `export *`, cycles, and deterministic IDs after repeated compilation.
+
+**Done condition:** cross-module semantic consumers use ModuleSymbol records and source-local SiteId values; readable names remain diagnostic metadata.
+
+### PR 9: Semantic State Operations
+
+**Objective:** lower semantically equivalent state updates to the existing structured HandlerIR path.
+
+**Required source equivalence:**
+
+```tsx
+setCount(count + 1)
+const next = count + 1; setCount(next)
+const increment = () => setCount(count + 1); increment()
+function increment(value) { setCount(value + 1) }; increment(count)
+```
+
+**Internal scope:** extend existing command/value representation only for proven pure state operations. Keep arbitrary safe browser handlers as generated ESM; do not invent a general JavaScript IR.
+
+**Done condition:** the equivalent forms produce the same StateWrite semantics, browser result, ownership references, and zero-unused-runtime behavior; recursion, escape, mutation, and dynamic dispatch fail with explicit diagnostics.
+
+### PR 10: ModuleIR Reference Unification
+
+**Objective:** replace mixed state names, export strings, formatted owner strings, and slots with validated source-local slots and SymbolRef records.
+
+**Tests:** malformed references, duplicate exports, parent/child reciprocity, cycles, version rejection, and JSON round trips.
+
+**Done condition:** every HandlerIR, BindingIR, DerivedIR, EffectIR, KeyedBlockIR, and component specialization edge validates before build-module generation.
+
+### PR 11: RouteBuildRecord And Artifact Graph
+
+**Objective:** make route artifact selection structural.
+
+**Files:** add a focused route-artifact module; update `build.mjs` and capability planning.
+
+**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.
+
+### PR 12: Deep RouteIR And CapabilityIR Validation
+
+**Objective:** fail before codegen for invalid concrete route references and capability projections.
+
+**Done condition:** duplicate/missing state IDs, invalid event/effect dependencies, broken list ownership, invalid binding descriptors, and artifact mismatches have focused tests and deterministic diagnostics.
+
+## Large Application Capability Order
+
+After the relevant P0 foundations, investigate capabilities in this order:
+
+1. Property-level derived dependencies over ordinary object state.
+2. Multi-boundary component/prop/callback/ref/context dataflow.
+3. Package-neutral shared state/actions and migration of current Zustand internals.
+4. Browser-only package imports in owned effect/resource modules.
+5. ResourceIR from at least two independent WebSocket/SSE/SDK fixtures with the same semantics.
+6. Route/layout capability and CSS chunk closure.
+7. Incremental source and affected-route builds.
+8. Range ownership and virtualization only after a real data-heavy fixture establishes direct DOM limits.
+9. Optimistic shared transactions only after independent mutation fixtures establish commit/rollback semantics.
+
+## Compatibility Strategy
+
+Classify every package or category as one of:
+
+- Native: ordinary JS/TS/Web package; use it directly in an allowed build or browser module.
+- Compiled: package-shaped source lowers to package-neutral semantics and the import is erased.
+- Migrated: deterministic source transformation replaces a React runtime implementation with native/Kudzu source.
+- Adapter: repeated package semantics justify an internal compatibility adapter.
+- Partial: only an explicit API subset is supported.
+- Unsupported: safe transformation is not proven; report the reason and migration path.
+
+Current factual baseline:
+
+| Ecosystem | Current classification |
+|---|---|
+| React source | Compiled, partial |
+| React Router | Compiled, partial |
+| Zustand | Compiled, partial, insufficiently isolated |
+| Redux/RTK | Unsupported |
+| TanStack Query | Migrated recipe, partial |
+| React Hook Form | Migrated recipe, partial |
+| Zod | Unsupported in ordinary shared schema placement; native-package candidate after module work |
+| Radix dialog | Migrated to native dialog, partial |
+| Headless UI/MUI | Unsupported |
+| Plain CSS | Native |
+| CSS Modules | Compiled, partial |
+| Tailwind | Application-owned CSS adapter boundary |
+| CSS-in-JS | Unsupported |
+| Native SVG/canvas charts | Native/compiled |
+| React chart, animation, drag/drop, virtualization packages | Unsupported or migration candidates |
+| REST `fetch` | Native/compiled, partial async model |
+| GraphQL/auth/browser SDKs | Unsupported until browser package/resource ownership exists |
+
+## Application Corpus
+
+| Tier | Required evidence |
+|---|---|
+| Tier 1 | Existing reduced positive/negative fixtures with exact semantic boundaries |
+| Tier 2 | Complete small/medium React applications such as CRUD, forms, commerce, admin, chat, and calendar |
+| Tier 3 | Production slices with 100-500 modules, shared state, routing, packages, forms, server state, charts, auth, and resources |
+| Tier 4 | At least two whole existing React applications, including one stateful/realtime app, with 500+ modules and 100,000+ reachable lines where available |
+
+Every corpus entry records upstream URL/commit/license, acquisition hash, original source, migration patch, retained-source percentage, package classification, unsupported census, route/module/component counts, browser/a11y journeys, artifact bytes, build/rebuild/RSS metrics, and AI task traces.
+
+## AI Cost And Tooling Gates
+
+Architecture work must connect to measurable AI cost reduction:
+
+| Compiler capability | Expected cost reduction |
+|---|---|
+| Symbol graph | Fewer file searches, alias mistakes, and capture debugging cycles |
+| Semantic operations | Fewer rewrites into exact compiler-recognized syntax |
+| Component dataflow | Less component flattening and callback forwarding surgery |
+| Property dependencies | Less artificial primitive-state decomposition |
+| Compatibility registry | Less Kudzu-specific package knowledge and documentation lookup |
+| Structured diagnostics | Fewer log-parsing and source-location tool calls |
+| Explain graph | Fewer files read to understand a route or mutation |
+| Deterministic fixes | Fewer repetitive source edits and retries |
+| Incremental build | Lower feedback time per compiler attempt |
+| Artifact graph | Faster runtime/chunk/debugging attribution |
+
+The first comparison is Kudzu versus React + Vite using the same agent, model, tools, prompt, task, and acceptance suite. Record at least five attempts per task and report medians and ranges. A build-only result is not success.
+
+## Production Gates Before 1.0
+
+- Async native and effect work cannot write after ownership release.
+- Build output is atomic and collision-safe.
+- Source maps connect generated route code to TS/TSX diagnostics.
+- Chrome, Firefox, and WebKit pass required journeys.
+- Accessibility automation and keyboard checks cover forms, navigation, dialogs, menus, charts, and errors.
+- Route, module, package, CSS, Worker, and chunk closures are inspectable.
+- Clean build, one-file rebuild, peak RSS, long-navigation heap, and mixed keyed ownership benchmarks have maintained baselines.
+- Package compatibility status and version guarantees are public and machine-readable.
+- Deployment cache, CSP, authentication, private-data, upload, and error-handling guidance is explicit.
+- At least one complete content application and one complete stateful/realtime application pass production gates.
+- AI benchmark results report cost per successful task and context surface area per successful task.
+
+## Per-PR Required Evidence
+
+- [ ] State the exact producer and consumer boundary changed.
+- [ ] Name the real fixture or correctness failure authorizing the patch.
+- [ ] Add a focused check that fails before the implementation.
+- [ ] Preserve unrelated source support and diagnostics.
+- [ ] Compare representative ModuleIR, RouteIR, HTML, emitted paths, and bytes.
+- [ ] Prove static sibling routes remain zero JavaScript.
+- [ ] Prove identity, cleanup, cancellation, and late-completion behavior where ownership changes.
+- [ ] Record build/runtime measurements for nontrivial paths.
+- [ ] Run `npm run check`, `npm test`, and package smoke when package output changes.
+- [ ] Update this plan before combining or reordering scopes.
+- [ ] Update release notes only after the implementation is complete and published.
+
+## 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 2: Symbol-Aware Descriptor Discovery**. 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.26` are completed scopes represented by package/release records.
+This is an execution sequence, not release history. `0.8.16` through `0.8.27` 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.
 
@@ -17,6 +17,7 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 | `0.8.24` | Start Goal B with measured large keyed restoration and no-op normalization optimizations. | Fresh-profile keyed restoration improves materially; alternating 1,000-product builds improve materially; correctness, output, and byte deltas are recorded. |
 | `0.8.25` | Reuse byte-identical generated native, parameter, and effect route-entry transforms within one build and strengthen compiler/release boundaries. | Alternating 1,011-page builds improve materially with identical deploy hashes; normalization and ModuleIR fail closed; Node, Chrome, package, and registry gates pass. |
 | `0.8.26` | Harden Goal B benchmark reproducibility and ordinary regression coverage without changing runtime behavior. | Commerce comparison defaults to exact output; route transform counts and keyed bulk/fallback guards are protected by the standard suite; baseline coverage and limits are explicit. |
+| `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. |
 
 ## Sequence Rules
 

package/framework/compiler/source-compiler.mjs

@@ -629,9 +629,13 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
       }
       if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && ts.isCallExpression(node.initializer) && ts.isIdentifier(node.initializer.expression)) {
         const owner = nearestFunction(node)
-        if (owner && node.initializer.expression.text === "useRef" && node.initializer.arguments.length === 1 && node.initializer.arguments[0].kind === ts.SyntaxKind.NullKeyword) {
-          ensureOwner(owner)
-          componentAnalysis.registerRef(owner, { name: node.name.text, source: analysisSource(node) })
+        if (owner && node.initializer.expression.text === "useRef") {
+          const nullInitializer = node.initializer.arguments.length === 1 && node.initializer.arguments[0].kind === ts.SyntaxKind.NullKeyword
+          if (!nullInitializer && owner.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.DefaultKeyword)) throw sourceNodeError(node.initializer, sourceFile, "Mutable value useRef() is unsupported except for an effect-owned useRef(0) animation-frame handle; otherwise keep resource-private mutable values inside the owning effect")
+          if (nullInitializer) {
+            ensureOwner(owner)
+            componentAnalysis.registerRef(owner, { name: node.name.text, source: analysisSource(node) })
+          }
         }
         if (owner && node.initializer.expression.text === "useId" && node.initializer.arguments.length === 0) {
           ensureOwner(owner)

package/package.json

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