@kudzujs/core 0.16.24 → 0.16.26

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

@@ -1,95 +0,0 @@
-# Current Compiler Architecture
-
-This maps the current `0.16.24` architecture, built on the completed `0.9.0` semantic-compression release and `0.8.23` Goal A compiler foundation. The `0.21.4` AI delivery gate is measured and blocked; file and function names are the stable references, while line numbers are intentionally omitted because later work may still move code.
-
-## Responsibility Map
-
-| Responsibility | Current owner | Current contract |
-|---|---|---|
-| CLI entry | [`bin/kudzu.mjs`](../../bin/kudzu.mjs) | Dispatches build, development, inspection, and exact-route explanation commands. |
-| Project session | [`framework/compiler/project-session.mjs`](../../framework/compiler/project-session.mjs), `createProjectSession()` | Owns one absolute root, standard project paths, source records, bound graph operations, and Worker compiler. Production builds use one session; development retains it across rebuilds. Omitted roots resolve from call-time CWD. |
-| Parsed module cache and symbols | [`framework/compiler/project-session.mjs`](../../framework/compiler/project-session.mjs) | Parses each unchanged source module once per ProjectSession and records source-local declaration/import/re-export sites. Stable ModuleSymbol records resolve direct, aliased, barrel, and `export *` exports with cycle and ambiguity checks; repeated resolutions are cached against their source dependencies, and normalization consumers locate the resolved SiteId in a fresh clone with independent parent links. |
-| Build orchestration | [`framework/build.mjs`](../../framework/build.mjs), `build()`, `buildWithSession()` | Coordinates config, discovery, source compilation, RouteBuildRecord collection, CapabilityIR projection, generator invocation, artifact emission, and `afterBuild`. A retained session caches source results and pre-family route renders by page graph; successful builds alone replace that cache. |
-| 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. A lazy package edge must resolve lexically to a named React or Kudzu `useEffect` import. |
-| Compatibility inventory | [`framework/compiler/compatibility-registry.mjs`](../../framework/compiler/compatibility-registry.mjs), `createCompatibilityReport()` | Classifies package/API sites in reachable original source as Native, Compiled, Normalized, Adapter, Owned External UI, Partial, or Unsupported and writes deterministic source ranges to `.kudzu/kudzu-compatibility.json`. Package provenance ends here and never enters semantic IR or browser output. |
-| Structured diagnostics | [`framework/compiler/diagnostics.mjs`](../../framework/compiler/diagnostics.mjs), `KudzuDiagnosticError`, `diagnosticEnvelope()` | Carries versioned stable codes, semantic stages, severity, authored source ranges, messages, nullable compatibility classes, and safe suggestions through programmatic builds. Build-boundary path normalization keeps JSON project-relative; human compiler and development messages retain their existing source context. Internal IR and artifact invariants remain ordinary errors. |
-| 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, inclusive ancestry, effect-return, and source-location analysis. |
-| Source-local binding index | [`framework/compiler/analysis/binding-index.mjs`](../../framework/compiler/analysis/binding-index.mjs) | After normalization, assigns deterministic lexical slots and classifies local, parameter, import, capture, global, and unresolved references. Native handler, effect, binding, list evaluator, optimized-command, and effect-resource consumers use complete index-owned AST; synthesized expressions retain the existing fallback. |
-| Pure collection language | [`framework/compiler/collection-analysis.mjs`](../../framework/compiler/collection-analysis.mjs) | Analyzes collection roots/selectors, including one direct array field of a proven object-state component prop, and serializes the allowed pure expression language used by lists and derived dependencies. |
-| Main semantic analysis | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `createKudzuTransformer()` | Produces transformed source plus explicit component, shared-state/action, handler, binding, derived, keyed, and effect ownership results. Zustand package syntax and reduced Context actions resolve to package-neutral shared-state/action records before generic consumers. |
-| Component ownership analysis | [`framework/compiler/analysis/component-analysis.mjs`](../../framework/compiler/analysis/component-analysis.mjs) | Produces ComponentAnalysis v2 with ordered JSON-safe owner and specialization slots for state, setters, props, refs, IDs, direct SignalIR links, direct static property/consumer links, structural OwnerRefs, source-local SiteIds, and source provenance. Three direct callback/ref component boundaries specialize into the same parent signal and intrinsic ownership; Context action-private setters may remain compiler-only and receive collision-free consumer-local aliases; AST identity remains private to its source-local session. |
-| Per-source descriptor registration | [`framework/compiler/descriptor-session.mjs`](../../framework/compiler/descriptor-session.mjs), `createSemanticArtifact()`, `createDescriptorSession()` | Keeps AST descriptors private during analysis, then finalizes ModuleIR v2 with deterministic SymbolRef, SharedStateIR, SharedActionIR, SignalIR, HandlerIR, BindingIR, DerivedIR, EffectIR, KeyedBlockIR, and ImportIR slots. One fail-closed boundary validates every source-local and component ownership edge before build-module generation. |
-| Route artifact graph | [`framework/compiler/route-build-record.mjs`](../../framework/compiler/route-build-record.mjs), `createRouteBuildRecord()`, `planRouteArtifacts()`; [`framework/compiler/route-artifact-report.mjs`](../../framework/compiler/route-artifact-report.mjs), `createRouteArtifactReport()` | Validates each rendered route's RouteIR, capabilities, entry paths, styles, and exact handler/effect references. Handler and Worker esbuild metafiles project transitive output edges back through those records into deterministic per-route capability signatures and runtime requirements plus emitted handler, Worker, stylesheet, and shared-chunk closure. |
-| Tool projections | [`framework/compiler/inspection-report.mjs`](../../framework/compiler/inspection-report.mjs), `createInspectionReport()`; [`framework/compiler/explanation-report.mjs`](../../framework/compiler/explanation-report.mjs), `createExplanationReport()` | Projects bounded deterministic reachable-application inventory and one exact route's authored provenance, ownership, capability, artifact byte reasons, hashes, and zero-JavaScript explanation from existing build records. Raw semantic IR, generated code, HTML, captures, and state values remain private. |
-| Route contract validation | [`framework/compiler/route-ir.mjs`](../../framework/compiler/route-ir.mjs), `assertRouteIR()` | Fails before artifact selection for invalid state/parameter identity, commands, native/effect captures and dependencies, reactive descriptors, conditions, keyed-list identity/ownership, marker fields, or JSON safety. Immutable in-memory contracts validate once by identity. |
-| Command IR and codegen | [`framework/compiler/optimize/command-specialization.mjs`](../../framework/compiler/optimize/command-specialization.mjs), [`framework/compiler/ir/module-ir.mjs`](../../framework/compiler/ir/module-ir.mjs), [`framework/compiler/codegen/command-codegen.mjs`](../../framework/compiler/codegen/command-codegen.mjs) | Direct commands use the existing fast path; proven immutable state aliases and one-call local helpers specialize to the same JSON-safe command ModuleIR. Recursion, escape, mutation, and dynamic helper dispatch fail explicitly, while unrelated handlers retain native ESM. Codegen emits the existing `__kBehavior` AST and command ABI. |
-| Source compilation | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `compileSource()` | Runs TypeScript with the Kudzu transformer, rejects surviving React/Router references, and returns a JSON-safe project-relative build module, component analysis, ModuleIR, optional handler module, and imported assets without filesystem writes. |
-| Handler/evaluator lowering | [`framework/compiler/handler-lowering.mjs`](../../framework/compiler/handler-lowering.mjs) | Completes source-local callback, package-neutral Context/Zustand shared-action, binding, and list AST rewriting and diagnostics before the JSON-safe IR boundary. Provider/store implementation AST remains transient and final handlers retain shared-action edges. |
-| Handler module codegen | [`framework/compiler/handler-codegen.mjs`](../../framework/compiler/handler-codegen.mjs) | Renders finalized ordered imports and concatenates generated module-export source without TypeScript AST or semantic discovery. |
-| Effect analysis | [`framework/compiler/effect-analysis.mjs`](../../framework/compiler/effect-analysis.mjs) | Classifies ordered signal, ordinary or specialized object-property DerivedIR, and keyed-item dependencies and validates cleanup-owned browser resources before EffectIR registration. Object sources keep one signal subscription while the existing tagged evaluator and `Object.is` compare the selected primitive or authorized array value. |
-| Worker graph | [`framework/compiler/worker-compiler.mjs`](../../framework/compiler/worker-compiler.mjs) | Returns functional Worker rewrite results and JSON-safe EffectIR edges, validates relative graphs, emits content-hashed ESM, and resolves placeholders only for rendered effects. |
-| Shared path conversion | [`framework/compiler/path-helpers.mjs`](../../framework/compiler/path-helpers.mjs) | Converts project-relative module, browser, asset, and base paths for build and development serving. |
-| Build-time JSX execution | [`framework/core.mjs`](../../framework/core.mjs), `renderPage()` | Executes compiled pages/layouts, allocates deterministic route/layout ownership IDs, emits complete HTML, and returns RouteIR v1 plus capability facts and exact retained handler references. |
-| Route capability projection | [`framework/compiler/route-capability-planner.mjs`](../../framework/compiler/route-capability-planner.mjs), `planRouteCapabilities()`; [`framework/compiler/runtime-family-planner.mjs`](../../framework/compiler/runtime-family-planner.mjs), `planRuntimeFamilies()` | Validates RouteBuildRecord and RouteIR v1, projects exact route CapabilityIR, deduplicates equal standalone signatures, and unions each enhanced-navigation group at one required ESM singleton boundary. |
-| 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 route artifacts from RouteBuildRecord edges, emits each distinct runtime family under `assets/runtime/<family>/`, writes route HTML in bounded batches, bundles in a project-local staging sibling, copies public subtrees without replacing generated paths, runs `afterBuild`, then promotes with rollback. Byte-identical native, parameter, and effect entries share one file only when their family imports also match. |
-| 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) | Watches and batches changed source paths, recompiles and rerenders intersecting page graphs, then performs the existing complete staged artifact emission and SSE reload. Navigation groups invalidate together to retain one layout-function identity. Failed rebuilds preserve both prior output and pending invalidations while showing the existing error overlay. |
-
-## Current Data Flow
-
-```text
-src/pages entries + config
-  -> ProjectSession(root) with project paths, source records, parsed/symbol caches, graph, and Worker compiler
-  -> project discovery and reachable relative graph
-       -> classify original package sites into the scratch compatibility report
-       -> in development, intersect changed paths with current and prior per-page graphs
-       -> reuse unaffected SourceResult and pre-family route render records
-  -> compileSource()
-       -> ordered normalization and parent repair
-       -> source-local binding index
-       -> main transformer semantic analysis
-       -> TypeScript transpilation
-       -> JSON-safe build module, ModuleIR, handler module, and imported assets
-  -> build orchestration writes .kudzu executable and handler modules
-  -> import page modules and execute renderPage()
-       -> complete HTML
-       -> RouteIR v1 and exact handler references
-  -> validated RouteBuildRecord per emitted route
-       -> capability facts, route entries, styles, handler/effect artifact edges
-  -> remove unrendered handlers/effects/Workers
-    -> planRuntimeFamilies(RouteBuildRecord[], navigation groups)
-        -> exact route signatures plus deduplicated standalone/group CapabilityIR families
-  -> specialize and emit each selected runtime family under assets/runtime/<family>/
-       -> reuse exact generated route-entry transforms within this build
-  -> write route index.html, CSS/assets, Worker graphs, rewrites, and per-route artifact closure into staging/scratch
-  -> copy public paths only where they do not replace generated artifacts
-  -> optional afterBuild() against staging
-  -> rollback-safe promotion to dist; recover an interrupted backup on the next admitted build after stale-lock removal
-```
-
-The browser consumes static HTML first. State seeds and descriptors in that HTML connect only to emitted command, binding, list, native-handler, effect, parameter, or navigation modules. Browser execution patches owned DOM directly; it does not invoke component functions or reconstruct a component tree.
-
-## Residual Coupling
-
-- `createKudzuTransformer()` remains one large source-local analysis unit combining validation, specialization, descriptor registration, and transformed-source emission.
-- Transient component rewrite indexes remain source-local AST indexes; finalized handler, binding, derived, keyed, effect, signal, import, and component ownership edges use explicit JSON-safe slots or stable symbols.
-- `build()` still owns filesystem writes after structural route artifact selection and generator results are produced.
-- Runtime generators intentionally specialize readable authored sources through exact anchors; every required anchor fails closed, but a future generator format may remove this transitional dependency.
-- Source reachability and source compilation remain in one session-bound compiler factory because both consume the same normalization and import graph contracts. ModuleSymbol resolution is stable across canonical and cloned trees; unsupported export syntax remains intentionally narrow.
-- Incremental development still reads the source tree, rebuilds graph closure, and emits a complete rollback-safe staging directory. It avoids unaffected compilation and build-time JSX execution; finer filesystem and artifact-write invalidation is not yet justified.
-- Imported declarations resolve by ModuleSymbol and source-local SiteId. Specialized and compiler-synthesized trees still use conservative name/scope fallback where the source-local binding index does not own the complete AST.
-
-These are future simplification opportunities, not incomplete Goal A contracts. Goal A changed no source support, browser output semantics, or browser architecture.
-
-## Continuation Checklist
-
-- [ ] Re-read every caller before moving a helper out of `framework/build.mjs`.
-- [ ] Keep analysis results serializable where AST identity is not required.
-- [ ] Keep AST-bearing descriptors source-local and consume them before render planning.
-- [ ] Do not move tightly coupled code behind a large context object merely to reduce file size.
-- [ ] Compare route plans and emitted artifacts before and after each extraction.

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

@@ -1,151 +0,0 @@
-# Goal A: Compiler Foundation
-
-## Status
-
-Goal A is complete in `0.8.23`. The no-write source compiler, ModuleIR source seams, RouteIR v1, CapabilityIR v1, focused runtime generators, and the architecture/output baseline preserve accepted React-shaped syntax, diagnostics, complete HTML, emitted capability behavior, and current public APIs.
-
-## Target Boundaries
-
-```text
-project/build session
-  -> normalized source result
-  -> analyzed source result + transformed build module
-  -> rendered route plan
-  -> pure capability/artifact plan
-  -> generated artifact sources
-  -> filesystem emission
-```
-
-Each arrow needs a concrete input/output contract. A file split without a reduced dependency surface does not count.
-
-## Minimum Kudzu IR
-
-Goal A adds only the representation missing between normalized TypeScript AST and generated Kudzu core calls. It does not duplicate the existing serializable route plan or model a component tree.
-
-```js
-{
-  version: 1,
-  file: "src/pages/counter.tsx",
-  signals: [],
-  handlers: [],
-  bindings: [],
-  derived: [],
-  effects: [],
-  keyedBlocks: [],
-  clientImports: [],
-  sourceLocations: []
-}
-```
-
-The active IR boundary must be JSON-safe. No `ts.Node`, `Map`, `Set`, `WeakMap`, function, closure, or Symbol crosses from analysis into optimization/codegen. Temporary AST identity remains an analyzer implementation detail until a feature receives an explicit result.
-
-Existing representations are promoted rather than copied:
-
-| Required concept | Canonical direction |
-|---|---|
-| `KudzuProgram` | Module, route, capability, and reference closure assembled only after the parts are explicit. |
-| `RouteIR` | Version the existing `renderPage().plan`; do not add a second route plan. |
-| `SignalIR` | Type the existing state descriptor and add an internal numeric slot plus readable debug metadata. |
-| `HandlerIR` | Plain command data or a stable generated-module export reference. |
-| `BindingIR` | Promote existing binding descriptors. |
-| `DerivedIR` | Reuse the existing tagged Collection Expression IR. |
-| `EffectIR` | Records setup HandlerIR, cleanup, ordered signal/DerivedIR dependencies and subscriptions, component/keyed ownership, source provenance, and Worker edges. |
-| `KeyedBlockIR` | Promote the existing list descriptor after ownership analysis is explicit. |
-| `CapabilityIR` | Reuse the current pure route capability manifest. |
-
-A JSX tree, VDOM, component IR, retained component identity, or general expression VM is not part of Goal A.
-
-## First Vertical Slice
-
-The existing command fixture is the first real `TSX -> IR -> optimization -> existing codegen` path:
-
-```tsx
-const [count, setCount] = useState(0)
-return <button onClick={() => setCount(count + 1)}>{count}</button>
-```
-
-Analysis produces plain data:
-
-```js
-{
-  signals: [{ slot: 0, key: "state:0:count", debugName: "count" }],
-  handlers: [{
-    slot: 0,
-    kind: "commands",
-    commands: [{ operation: "add", signal: 0, value: 1 }]
-  }]
-}
-```
-
-The completed source result contains deterministic command, component, HandlerIR, BindingIR, DerivedIR, KeyedBlockIR, and EffectIR records. Source-local AST analysis is consumed during lowering and does not cross this boundary. Final route/layout/conditional/keyed IDs and lifetime allocation remain authoritative in `core.mjs`; no component tree or duplicate route plan exists.
-
-Source codegen lowers that data through the existing build ABI:
-
-```js
-__kBehavior([["add", count, 1]])
-```
-
-`core.mjs` remains responsible for final route/layout state IDs, complete HTML, `data-k-*` descriptors, and the route plan. The generated HTML, command runtime, plan, and asset set must remain byte-identical. The command route must not gain handler, native, effect, binding, list, or serialization modules.
-
-### Source Result
-
-`compileSource()` returns one JSON-safe source-local result containing the project-relative build module, component analysis, sparse ModuleIR, optional generated handler/effect/binding/list evaluator module, and imported assets. It writes no files. Worker ownership is recorded as EffectIR edges; AST-bearing data is consumed inside analysis/lowering and does not become IR or cross-build state.
-
-### Route Result
-
-`renderPage()` remains the build-time authority for complete HTML and ownership IDs. Its existing plan is RouteIR v1, the behavioral source for states, events, effects, bindings, conditions, lists, parameters, and search parameters. Each state has a route-local numeric `slot`, its unchanged browser/DOM `id`, and readable `name` metadata used by development restoration. RouteIR slots are not ModuleIR signal slots or persistent browser identities. Route-level facts such as navigability and dependency-runtime selection accompany rather than mutate the plan.
-
-### Artifact Plan
-
-CapabilityIR v1 determines shared runtime families and optional branches. Rendered RouteIR descriptors and ModuleIR references independently retain route entries, handler modules, and Worker reachability. Runtime, list, parameter, effect, and handler generators consume those explicit results; they do not rediscover TSX semantics or inspect application AST.
-
-## Generator Strategy
-
-Use the smallest generator that removes fragile source surgery:
-
-- Keep authored browser capability modules as readable JavaScript.
-- Give each generated artifact one focused generator function with an explicit manifest subset and deterministic output.
-- Prefer composing imports, constants, and named source sections over a general template engine or code-generation IR.
-- Move existing specialization in behavior-preserving slices; do not rewrite all runtimes at once.
-- Let esbuild perform syntax lowering, dead-code elimination, bundling, defines, and minification after Kudzu chooses the capability branches.
-- Preserve stable path names where they are public output behavior; preserve content-hashed Worker/chunk naming.
-- Assert that requested source sections exist before replacing/removing them during transition. The end state must not depend on incidental whitespace or entire function-body string matches.
-
-No generator may analyze TSX, invent runtime component abstractions, or broaden the capability contract.
-
-## Execution Rules
-
-- One patch, one boundary, with no migration feature mixed in.
-- Extract only code whose callers and outputs are understood.
-- Replace AST side tables only when an explicit feature result can preserve ownership and source diagnostics.
-- Keep `build()` as orchestration; do not replace it with a service container or plugin framework.
-- Preserve current runtime files until their corresponding generator has artifact parity.
-- Treat deterministic byte changes as review items even when tests pass.
-
-## Acceptance Record
-
-- `build.mjs` decreased from 3,999 to 744 lines and coordinates discovery, JSON-safe source results, RouteIR rendering, CapabilityIR projection, generation, and writing without TSX feature analysis.
-- Source normalization, semantic analysis, ModuleIR and build-module generation, RouteIR rendering, CapabilityIR projection, generation, and writing have explicit ownership without a broad context object.
-- RouteIR and CapabilityIR reject unsupported versions; required runtime source anchors fail closed.
-- Static routes retain complete HTML and zero JavaScript; deploy output across the complete site and representative binding, list, effect, Worker, parameter, navigation, config, and package-handler fixtures is byte-identical to `v0.8.22`.
-- Interactive and navigation routes preserve capability selection, ownership, stale-write, and cleanup behavior; unreachable handlers, effects, package helpers, and Workers remain absent.
-- Diagnostics retain source file and location, and [`performance-gates.md`](./performance-gates.md) records no build or artifact-size regression.
-
-## Non-Goals
-
-- New React compatibility, hooks, routing, state, resource, or Worker forms.
-- A compiler plugin API, full JSX/component-tree IR, template framework, or dependency-injection layer.
-- Rewriting `framework/core.mjs` into a browser renderer.
-- Optimizing browser hot paths before Goal A establishes a comparable baseline.
-- React islands, hydration, or component serialization.
-
-## Continuation Checklist
-
-- [ ] Confirm the next planned version in [`versioning.md`](./versioning.md).
-- [ ] Write down the current producer, consumer, and artifact before changing the boundary.
-- [ ] Add or retain the smallest parity check that catches descriptor/plan/output drift.
-- [ ] Compare representative static, command, binding, list, effect, Worker, runtime-parameter, and navigation outputs.
-- [ ] Record raw/gzip and build measurements under the protocol in [`performance-gates.md`](./performance-gates.md).
-- [ ] Mark a patch complete only after behavior and output gates pass.
-- [ ] Delete the previous AST-valued representation when an IR path lands; never maintain both indefinitely.
-- [ ] Preserve descriptor allocation order and final state IDs unless a versioned output change is explicitly approved.

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

@@ -1,86 +0,0 @@
-# Goal B: Optimization Benchmarks
-
-## Status
-
-Active from the completed Goal A baseline at `0.8.23` commit `39a065b`. Maintained keyed restoration and external 1,000-product build measurements authorized the first two narrow optimizations.
-
-## Purpose
-
-Use matched fixtures to identify measured build, output, or browser losses after the new boundaries are stable. Goal B is evidence-led optimization, not an architecture rewrite or a framework leaderboard.
-
-## Baseline
-
-At Goal A completion, record one source revision and the current maintained fixtures for:
-
-- clean build time;
-- emitted file list and deterministic hashes where applicable;
-- HTML, CSS, raw/gzip JavaScript, and Worker bytes;
-- static zero-JavaScript routes;
-- command update, reactive binding, keyed list update/reorder/removal, dependency effect, and enhanced navigation;
-- repeated ownership cycles and heap trend.
-
-Historical figures in [`PERFORMANCE.md`](../../PERFORMANCE.md) and the top-level Goal records are provenance, not an automatic current baseline. Reproduce a fixture before using it to approve work.
-
-### First Baseline Pass
-
-The maintained Worker benchmark measured a 289.9 ms clean-build median, 907 B raw / 477 B gzip Worker graph, and 12,148 B raw / 5,411 B gzip window graph on Node 22. Its Chrome throughput, cadence, stale-write, bounded-history, and repeated ownership gate passed.
-
-The preserved external 1,000-row keyed fixture was used only to find a candidate, not as a maintained approval benchmark. Its operations were fast, so a repository-owned benchmark was added for 2,000 rows with local state and reactive search. It measures filtering to one retained row, restoring 1,999 fresh rows, and reversing all rows in fresh Chrome profiles while checking retained identity, released identity, reset state, and restored handlers.
-
-The maintained benchmark measured a 26.3 ms restoration median. For top-level flat lists where more than 32 additions are a majority of both the next rows and their parent children, mounting the connected list parent once rather than invoking every mount hook for every new row reduced the median to 21.1 ms (19.77%). A retained-heavy 33-row append stayed on the per-root path and showed no material change at 2.7 ms versus 2.6 ms. The route added 127 B raw / 35 B aggregate gzip JavaScript.
-
-[`SimYunSup/kudzu-based-bench`](https://github.com/SimYunSup/kudzu-based-bench) then supplied a 1,000-product, 1,011-page build fixture. Twenty-one alternating clean builds measured 6,684.7 ms for clean `0.8.23` and 6,266.5 ms after skipping parent-pointer repair for normalization passes that return the unchanged AST, a 6.26% improvement. The output retained 3,056 files and only the separately optimized `kudzu-list.js` changed. Full raw arrays and limitations are recorded in [`PERFORMANCE.md`](../../PERFORMANCE.md).
-
-The `0.8.25` investigation isolated repeated esbuild work by comparing ordinary transformation with build-local reuse keyed by the complete generated route-entry source. Seven alternating 1,011-page builds measured 13,851.0 ms and 12,581.4 ms medians, a 9.17% improvement, with identical emitted paths and hashes. The retained implementation applies only to native, parameter, and effect route entries and keeps no data beyond one build.
-
-### Baseline Coverage Status
-
-| Area | Current evidence | Status |
-|---|---|---|
-| Build and artifact graph | Worker and commerce clean builds, emitted manifests, deterministic hashes, raw/gzip JavaScript and Worker bytes | Recorded |
-| Static exclusion | Complete-site and representative fixture comparisons plus static zero-JavaScript assertions | Recorded |
-| Keyed operations | Append, filter, bulk restoration, reverse, retained/released identity, state reset, and handler checks | Recorded |
-| Worker ownership | Throughput, cadence, bounded history, stale writes, and repeated start/termination/listener ownership | Recorded |
-| Command, binding, effect, and navigation semantics | Maintained integration and Chrome behavior tests | Correctness recorded; no standalone timing baseline because no material loss is currently reproduced |
-| Heap trend | Repeated ownership counters and bounded fixture data | No general heap series; add one only when a reproduced ownership or memory loss requires it |
-
-The broad baseline list is an investigation inventory, not a requirement to manufacture timings without a candidate. New timing or heap work begins only when a current fixture reproduces the corresponding loss.
-
-## Candidate Order
-
-1. Profile the largest measured loss in a maintained fixture.
-2. Separate analysis/build cost, transfer bytes, startup, selector evaluation, DOM mutation, and ownership cleanup.
-3. Change the narrowest shared path responsible for the loss.
-4. Keep the change only if repeated measurements clear the materiality rule and correctness gates.
-
-Known historical pressure points include large keyed-list removal/reconciliation and broad runtime specialization, but neither is authorized without a reproduced current loss.
-
-Repeated esbuild transformation of byte-identical generated route entries cleared the materiality and output gates. The later maintained 1,000-product fixture isolated filesystem scaling from 2,022 byte-identical native/effect route-entry files, authorizing build-local source deduplication to the first existing route path. This remains limited to generated route entries and is not a generalized cache.
-
-## Benchmark Contract
-
-- Match visible content, behavior, errors, accessibility, and navigation semantics.
-- Disclose static HTML versus CSR/SSR architecture differences.
-- Use one warm-up and at least seven interleaved production builds.
-- Use rotating fresh browser profiles and more runs when ranges overlap.
-- Record environment, source revision, raw arrays, medians, min/max or distributions, artifacts, and limitations.
-- A repeatable browser median change above 5% is material; deterministic byte growth is always reviewed.
-
-## Rejection Rules
-
-Reject an optimization that:
-
-- removes complete initial HTML or zero-JavaScript exclusion;
-- changes DOM identity, state lifetime, cleanup, stale-write, focus, history, or native fallback semantics;
-- introduces a retained tree, scheduler, cache, generalized runtime, or public API;
-- wins by omitting matched behavior or accessibility;
-- cannot be reproduced outside profiler instrumentation.
-
-## Continuation Checklist
-
-- [x] Verify Goal A acceptance is complete.
-- [x] Freeze and record the post-Goal-A baseline revision.
-- [x] Select one measured loss, not a speculative hotspot.
-- [x] Add one minimal benchmark or reuse a maintained one.
-- [x] Record before/after raw arrays and artifacts.
-- [x] Keep no experiment that fails correctness or materiality gates in the release tree.

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

@@ -1,88 +0,0 @@
-# Goal C: State And Resource Research
-
-## Status
-
-Research only. There is no approved public store API, resource API, cache API, query API, scheduler, or runtime proposal.
-
-## Existing Model
-
-Kudzu already has compiler-owned state slots and explicit ownership:
-
-| Owner | Lifetime | Existing examples |
-|---|---|---|
-| Document | Full non-persisted document | global disposal and document listeners |
-| Layout | One enhanced-navigation group session | explicitly shared state/effects |
-| Route | Current complete-document route range | parameters, requests, route effects/state |
-| DOM range/key path | Conditional or keyed ownership | row state/effects/refs and nested resources |
-
-`framework/core.mjs` allocates ownership IDs and serializable plans at build time. Browser runtimes hold only logical state and direct DOM/lifecycle registrations needed by emitted capabilities. Effects own browser resources and cleanup; stale invocations are invalidated before replacement.
-
-## Research Questions
-
-- Which real migration cannot be expressed with build-time data, ordinary state, layout ownership, route ownership, or one effect-owned browser resource?
-- Is the missing behavior compile-time specialization, lifetime declaration, deduplication, persistence, or request coordination?
-- Can a reduced conventional React fixture retain familiar source without shipping a public resource abstraction?
-- What exact cancellation, stale-result, error, retry, disposal, navigation, and BFCache semantics are required?
-- Can the capability be absent from unrelated routes and avoid a shared cache/scheduler?
-
-## Required Evidence
-
-Before any proposal, provide:
-
-- a real application or reduced conventional React fixture that fails today;
-- the smallest unsupported source shape and current diagnostic;
-- data timing and required owner lifetime;
-- behavior for success, empty, failure, retry, replacement, unmount, navigation, and late completion;
-- output and ownership costs;
-- an explanation of why existing async build rendering, state/effects, layout ownership, native platform storage, or effect-owned resources are insufficient.
-
-## 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 fixture now compiles through a narrow effect-private ref specialization. Because both refs are initialized with `null` or `0` and every direct `.current` reference belongs to one inline effect graph, the compiler removes their component declarations and recreates them inside each setup invocation. Promise continuations, page lifecycle listeners, and cleanup share the same ordinary JavaScript closure. Persisted `pagehide` retains that invocation; non-persisted disposal invalidates late setters and runs the authored close path. No ref capture, ResourceIR record, or resource runtime is emitted, and the static sibling remains JavaScript-free.
-
-### Route-Owned WebSocket Reduced Fixture
-
-The repository-owned fixture at `test/fixtures/goal-c-route-websocket` adds an independent native WebSocket case with a narrower route lifetime:
-
-- one `null`-initialized socket handle ref shared by setup and cleanup;
-- one numeric generation ref invalidating callbacks from replaced connections;
-- a primitive room dependency that replaces the connection;
-- exact listener removal and socket closure on replacement or route unmount;
-- one unrelated static sibling route.
-
-This fixture uses the same effect-private lowering. On dependency replacement, the previous invocation is invalidated and cleaned before a new closure and socket are created. The regression test executes the bundled effect handler with a fake WebSocket and verifies listener removal, stale callback rejection, one close per connection, and distinct replacement sockets. Its static sibling remains JavaScript-free.
-
-Both fixtures therefore resolve without ResourceIR: their mutable handles are private implementation details of one effect invocation, while existing effect ownership already supplies replacement, cleanup, navigation, and BFCache disposal. The remaining Goal C pressure is cross-owner sharing: document/layout transports with independently mounted subscribers, reconnect/replay state, or handles intentionally shared with event handlers cannot use this specialization.
-
-## Decision Boundary
-
-Research may produce notes, fixtures, measurements, or a narrow compiler-specialization proposal. It must not publish `createStore`, `resource`, `query`, cache, Provider, subscription, or scheduler APIs. A public API requires separate approval after at least two independent migration fixtures establish the same semantics and after zero-cost exclusion is demonstrated.
-
-## Continuation Checklist
-
-- [ ] Keep Goal C out of Goal A implementation patches.
-- [ ] Start with a failing migration fixture, not API design.
-- [ ] Classify build-known, browser-only, layout-owned, route-owned, and DOM-owned data.
-- [ ] Test existing compiler capabilities before proposing a new one.
-- [ ] Record unresolved semantics instead of filling them with a generic runtime.
-- [x] Stop at research unless a separate implementation decision is approved; the effect-private specialization was explicitly approved without approving ResourceIR.

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

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