@kudzujs/core 0.8.61 → 0.9.0

package/docs/next-architecture/0.9-resource-lifecycle.md

@@ -0,0 +1,118 @@
+# Kudzu 0.9 Resource Lifecycle Matrix
+
+## Status
+
+This is the evidence ledger for `0.9.0-04 / Session 04A`. It inventories the
+resource-shaped fixtures present at revision `98508ff` before any 04B test or
+semantic change.
+
+Current conclusion: every represented lifetime fits existing `EffectIR`,
+effect-invocation-private values, and document/layout/route/conditional/keyed
+ownership. No fixture proves a cross-owner lifetime or authorizes `ResourceIR`.
+
+## Lifecycle Matrix
+
+| Fixture/family | Acquire | Dependencies | Owner | Invalidation and exact cleanup | Late completion | BFCache | Static exclusion / evidence |
+|---|---|---|---|---|---|---|---|
+| [`worker-effects`](../../test/fixtures/worker-effects) | Route effect creates a chart, module Worker, and message/error listeners. The Worker owns a 10 ms interval. | `[]`; route release/remount replaces the complete graph. | `/dash/dashboard` route inside a retained navigation layout. | Route disposal invalidates the effect, sets authored `active = false`, removes both listeners, calls `worker.terminate()`, and calls `chart.dispose()`. | Required Chrome manually invokes a removed message callback after cleanup and verifies no detached-canvas update. Thirty mount/dispose cycles balance starts, terminations, adds, and removes. | No focused persisted hide/restore journey. | Real and fake Worker Chrome journeys pass. `/dash/static` has zero JS; `/dash/plain` excludes the dashboard effect; unreachable Workers emit no graph. |
+| [`goal-c-route-websocket`](../../test/fixtures/goal-c-route-websocket) | Dependency effect creates `new WebSocket(room)` and open/error listeners. | `[room]`; `general` cleanup precedes `support` setup. | Route effect inside a retained navigation layout. | Generation and ref identity invalidate the old invocation; cleanup increments generation, removes listeners, clears the matching ref, and closes once. Route release and final disposal use the same path. | Required Chrome invokes stale callbacks after dependency replacement and route release; neither can update status or recreate the route. | Non-persisted disposal is executable; persisted restore is not part of this fixture. | Node fake and required-Chrome journeys pass; `/static` is script-free. The graph is 15,872 raw / 7,163 aggregate gzip JS bytes. |
+| [`goal-c-e2b-terminal`](../../test/fixtures/goal-c-e2b-terminal) | Mount effect starts async `openTerminal()` and installs pagehide/pageshow listeners. | `[]`; fresh mount reacquires. | Route/effect invocation. | `active` and generation reject old acquisition. Cleanup removes listeners, closes the current handle, and clears the ref. Non-persisted pagehide also invalidates and closes. | Required Chrome resolves acquisition after disposal and proves the late handle closes once without changing status. | Synthetic persisted hide retains the accepted handle and persisted show resumes once; non-persisted hide closes once and repeated disposal is inert. | Two required-Chrome scenarios pass; `/static` is script-free. The graph is 2,634 raw / 1,495 aggregate gzip JS bytes. |
+| [`parameterized-debounce-hook`](../../test/fixtures/parameterized-debounce-hook) and direct debounce in [`react-vite-app`](../../test/fixtures/react-vite-app) | Dependency effect schedules one timeout. | Primitive source state; every change replaces the invocation. | Conditional child. | Prior token invalidates before direct `clearTimeout`; conditional removal releases setter authority and cleanup cancels pending work. | Chrome proves latest-only commit, unmount cancellation, and fresh remount. | No focused lifecycle event. | Static siblings have zero JS and no timer runtime. |
+| Private callback timers in [`react-vite-app`](../../test/fixtures/react-vite-app) | Returned action clears the previous handle and assigns a literal-delay timeout; empty-dependency effect owns final cleanup. | Handler-driven replacement. | Conditional custom-hook owner. | Compiler-owned private timer state is cleared on replacement and unmount; owner invalidation blocks late setters. | Chrome proves replacement, latest-only firing, removal cancellation, and fresh remount. | No focused lifecycle event. | Static sibling has zero JS; no timer runtime. |
+| [`memos-outline-migration`](../../test/fixtures/memos-outline-migration) | Scroll/resize listeners schedule one coalesced animation frame. | `[]`; event-driven scheduling. | Document/page effect. | Non-persisted disposal removes both listeners and cancels the pending frame. Post-disposal resize schedules nothing. | Fake scheduler proves pending-frame cancellation; saved callback is not manually invoked. | Non-persisted hide only. | Required Chrome passes; `/static` has zero JS. |
+| [`colonni-blog-migration`](../../test/fixtures/colonni-blog-migration) canvas | Effect acquires canvas context, recursive frame loop, `IntersectionObserver`, keyboard listener, and canvas click listener. | `[]`; route mount owns one graph. | Locale route/document effect. | Cleanup cancels the frame, disconnects the observer, and removes both listeners. Post-disposal events and frame flush draw nothing. | Listener/frame silence is executable; a saved observer callback is not manually invoked. | Non-persisted hide only. | Required Chrome passes; `/static` has zero JS and no canvas runtime. |
+| [`outside-click-hook`](../../test/fixtures/outside-click-hook) | Conditional dropdown adds one document `mousedown` listener. | Authored `[ref, callback]`, normalized to proven stable scope. | Conditional dropdown. | Removal invalidates ref/setter ownership and removes the same listener; remount installs one fresh listener. | Chrome proves removal and remount behavior; removed callback is not manually invoked. | No focused lifecycle event. | Required Chrome passes; `/static` has zero JS and no listener runtime. |
+| [`calcom-media-query-migration`](../../test/fixtures/calcom-media-query-migration) | Two static `matchMedia()` subscriptions add matching `change` listeners. | `[]`; media changes invoke state setters. | Document/page effects. | Non-persisted disposal removes both matching listeners and invalidates setter authority. Post-disposal media changes are ignored. | Required Chrome dispatches changes after disposal and observes no update. | Non-persisted hide only. | False static snapshots preserve complete HTML; `/static` has zero JS and no external-store runtime. |
+| [`navigation`](../../test/fixtures/navigation) interval and EventTarget listeners | Layout starts a telemetry interval/EventTarget; routes subscribe chart/product listeners. | Layout and route effects use `[]`; navigation changes owners. | Shared layout plus independently released routes. | Route listeners dispose on departure while layout telemetry persists. Non-persisted pagehide releases route before layout and reaches `clearInterval`; cleanup is idempotent. | Chrome proves no chart updates while unmounted, no duplicate listeners, and stale async/native writes cannot revive departed/disposed owners. | Synthetic persisted pagehide retains ownership; non-persisted hide disposes in route-layout order. No genuine browser BFCache traversal. | Outside route remains zero-capability; repeated navigation ownership passes in Chrome. |
+| [`effect-package`](../../test/fixtures/effect-package) | Route effect reads bundled `typescript` during setup; it does not acquire a handle. | `[]`. | Route effect. | Non-persisted disposal executes one package-backed cleanup assignment exactly once; no resource close/destroy exists. | Not applicable. | Persisted restore remains untested. | Required Chrome executes setup and cleanup. Package code exists only in interactive effect ESM, `/static` has zero JS, and the graph is 3,562,795 raw / 1,025,300 aggregate gzip JS bytes. |
+
+## Cross-Cutting Evidence
+
+Existing generic ownership already proves behavior beyond individual resource
+fixtures:
+
+- [`conditional-effects`](../../test/fixtures/conditional-effects) and
+  [`keyed-effects`](../../test/fixtures/keyed-effects) prove dependency
+  replacement, stale setter rejection, conditional/keyed release, and fresh
+  remount.
+- [`navigation-owned-effects`](../../test/fixtures/navigation-owned-effects)
+  combines dependency, conditional, keyed, route, layout, persisted hide, final
+  disposal, and late completion ownership.
+- [`tanstack-query-migration`](../../test/fixtures/tanstack-query-migration)
+  proves a delayed superseded response cannot overwrite the current invocation.
+- [`effect-cleanup`](../../test/fixtures/effect-cleanup) proves persisted hide
+  retention, non-persisted cleanup, repeated-disposal idempotence, and cleanup
+  failure isolation in generated effect ESM.
+
+These fixtures prove the ownership machinery. They do not turn promises,
+queries, or arbitrary event targets into resource primitives.
+
+## Recognition Inventory
+
+| Pairing proof | Current compiler owner | 04A finding |
+|---|---|---|
+| Timeout schedule/cancel | Generic effect analysis, parameterized debounce normalization, custom-hook timer normalization | Same runtime lifecycle, different validated source reachability. Review in 04C only if extraction deletes code and preserves diagnostics. |
+| Animation schedule/cancel | `effect-private-ref-pass.mjs` and `validateEffectOwnedBrowserResources()` | Repeated lexical proof exists, but accepted source shapes differ. |
+| Listener add/remove | Outside-click and media-query adapters; ordinary authored effects | Adapter-specific pairs are exact. Ordinary listeners rely on effect ownership and browser tests rather than a generic pair language. |
+| Observer observe/disconnect | `validateEffectOwnedBrowserResources()` | One focused generic proof; no second identical compiler pass yet. |
+| Handle close/terminate/dispose | Authored effect cleanup | Worker, socket, and terminal implementation details remain in route-owned handler ESM. |
+| Async generation invalidation | Authored guards plus effect token authority | Existing effect ownership blocks stale writes without a scheduler or resource registry. |
+
+## Evidence Gaps For 04B
+
+1. Exercise cleanup for an actual route-owned package-created handle when a real
+   fixture exists; the current package fixture now executes package-backed cleanup
+   but still acquires no handle.
+2. Distinguish synthetic persisted lifecycle events from a genuine browser BFCache
+   traversal; current evidence does not claim the latter.
+
+These are test and evidence gaps. They do not authorize `ResourceIR`, a resource
+registry, or a shared browser runtime.
+
+## Session 04B Closure
+
+Session 04B closes the executable gaps that current fixtures can honestly prove:
+
+- terminal normal acquisition, persisted resume, non-persisted discard, repeated
+  disposal, and late-resolution close run in two fresh Chrome profiles;
+- WebSocket dependency replacement, stale callback suppression, enhanced route
+  release, retained layout identity, remount, and final disposal run in one Chrome
+  journey;
+- package-backed setup and cleanup execute in Chrome while the static sibling
+  remains package- and script-free;
+- terminal, WebSocket, and package graphs have exact raw/gzip records above.
+
+The package fixture is not relabeled as a resource: it creates no package handle.
+A real package-created handle and genuine browser BFCache traversal remain evidence
+gaps rather than reasons to add framework machinery.
+
+## Sessions 04C-04E Decision
+
+Four compiler locations implemented the same inclusive AST ancestry walk. Session
+04C extracts only `isNodeWithin(node, root)` into `ast-helpers.mjs` and reuses it
+from effect-private refs, generic effect resource validation, media-query
+normalization, and command-helper recursion checks.
+
+```text
+Changed compiler files net LOC:  -12
+Core semantic file-set delta:     -3
+Semantic passes:                  +0 / -0
+Runtime concepts:                 +0
+Browser bytes:                    +0
+```
+
+No listener, timer, frame, observer, close/terminate, or generation abstraction
+was extracted. Those recognizers prove different authored graphs and own different
+diagnostics; a configurable generic matcher would add rather than remove semantic
+machinery.
+
+Session 04D finds zero qualifying cross-owner fixtures. The closest case is the
+navigation telemetry graph: its interval/EventTarget belongs to one layout effect,
+while each chart listener belongs to one route effect. Each acquire and cleanup
+obligation already has one exact owner. Existing terminal, WebSocket, Worker,
+canvas, timer, observer, media, and package fixtures are likewise invocation
+private.
+
+Session 04E therefore closes with expected outcome A: existing `EffectIR` is
+sufficient. No `ResourceIR`, registry, subscription runtime, public API, or browser
+capability was added.

package/docs/next-architecture/0.9-semantic-compression.md

@@ -0,0 +1,384 @@
+# Kudzu 0.9.0 Semantic Compression Plan
+
+## Status And Authority
+
+This is the completed execution record after `0.8.62`. Every release gate in this document is satisfied by `0.9.0`; follow-on model-driven delivery work remains separately gated for 1.0.
+
+The executable session-by-session decomposition, current implementation seams, benchmark restoration work, report templates, and release procedure are maintained in [`0.9-implementation-plan.md`](./0.9-implementation-plan.md). This document remains authoritative for direction, order, and release gates; the detailed plan is authoritative for execution within each ordered item.
+
+Read documents in this order before 0.9 work:
+
+1. [`MIGRATION_ROADMAP.md`](../../MIGRATION_ROADMAP.md) for product invariants and feature selection.
+2. This document for the active 0.9 scope and work order.
+3. [`0.9-implementation-plan.md`](./0.9-implementation-plan.md) for executable session packets and evidence.
+4. [`compiler-current-architecture.md`](./compiler-current-architecture.md) for current owners and data flow.
+5. [`performance-gates.md`](./performance-gates.md) for required measurements.
+6. [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md) for the completed foundation and longer-term work.
+
+If these documents conflict, preserve the stricter runtime, ownership, performance, and fail-closed boundary and update the documents before implementation.
+
+## Mission
+
+Kudzu 0.9.0 makes more realistic React-shaped programs reducible to the existing semantic model without making the browser heavier.
+
+```text
+React and ecosystem source
+  -> migration and internal normalization
+  -> narrow canonical Kudzu source
+  -> small deterministic semantic compiler
+  -> complete HTML + minimum route capability ESM
+```
+
+The compiler proves ownership, state transitions, dependencies, resources, ranges, and DOM effects. It does not interpret arbitrary JavaScript.
+
+The 0.9 success shape is:
+
+```text
+fixture coverage              increases
+Semantic Kernel concepts      unchanged
+core semantic pass count      unchanged or lower
+core compiler LOC             unchanged or lower
+browser JavaScript            unchanged or lower
+interaction latency           unchanged or lower
+```
+
+Internal improvement alone is insufficient for `0.9.0`. The milestone must prove Kudzu's architectural advantage against matched React and representative competing-framework applications under the cross-framework gate below.
+
+## Non-Negotiable Invariants
+
+1. Runtime performance and existing benchmark strengths are preserved before compatibility grows.
+2. Static routes emit complete HTML and zero JavaScript.
+3. Interactive routes emit only capabilities proven necessary for that route or explicit layout lifetime.
+4. React, hydration, a VDOM, retained browser components, generic rerendering, and generic client runtimes remain forbidden.
+5. Native HTML and browser APIs are preferred when they preserve behavior and accessibility.
+6. Package-specific knowledge ends at normalization or an internal adapter boundary.
+7. Unsupported semantics fail with a source location and an actionable migration path. There is no generic fallback.
+8. Build-known work stays at build time. Compatibility work must not transfer compiler cost to the browser.
+9. Native document navigation remains the default. `0.9.0` does not add a universal SPA router.
+10. New support begins with a real application or a reduced executable fixture derived from one.
+
+## Semantic Kernel Boundary
+
+The stable conceptual vocabulary for 0.9 is:
+
+```text
+Value
+State
+Derived
+Operation
+Event
+Effect
+Resource
+Range
+Navigation
+Ownership
+```
+
+These are semantic concepts, not a requirement to create ten public IR record types. Current records already cover much of the kernel:
+
+| Concept | Current representation | 0.9 direction |
+|---|---|---|
+| Value and State | `SignalIR`, state slots, serializable captures | Keep direct and ownership-scoped. |
+| Derived | Existing tagged `DerivedIR` collection and expression records | Generalize pure multi-state dependency and result use; do not add syntax-specific derived records. |
+| Operation | Command `HandlerIR`, `SharedActionIR`, native handler ESM | Normalize proven equivalent transitions into existing structured operations. |
+| Event | Route events and owned native handlers | Keep route and DOM-owner scoped. |
+| Effect | `EffectIR` and existing setup/cleanup codegen | Preserve invalidation, dependency comparison, and exact cleanup. |
+| Resource | Effect-owned lifecycle and invocation-private closures | Generalize lifecycle proof first; `ResourceIR` is not pre-approved. |
+| Range | Existing route, conditional, keyed, and navigation ownership | Reuse existing ownership; do not add generic range or virtualization machinery without evidence. |
+| Navigation | Native links plus explicit route-group capability | Keep native by default. |
+| Ownership | `OwnerRef`, component/keyed/route/layout identities | Make ownership edges more explicit and less syntax-dependent. |
+
+Before adding a semantic primitive:
+
+```text
+one fixture                  -> normalization or specialization
+two unrelated fixtures      -> document the repeated semantics
+three or more real fixtures -> architecture review may consider a primitive
+```
+
+Even at the third fixture, prefer an existing record or a stricter adapter. Fixture count permits a review; it does not authorize a new primitive.
+
+## 0.9 Scope
+
+### In Scope
+
+- Stronger pure `Derived` semantics for realistic multi-state application logic.
+- Package-neutral shared state and action semantics reused by more than one source model.
+- Resource lifetime proof based on acquire, dependencies, owner, invalidation, and cleanup.
+- Stronger compile-time component ownership, object/structural prop specialization, and property-level dependencies.
+- Consolidation or deletion of syntax-specific analysis after it lowers to existing semantics.
+- Exact complexity, output, build, and browser accounting for every slice.
+- Actionable diagnostics for the supported boundary and nearby unsafe forms.
+
+### Explicitly Deferred
+
+- The public `kudzu normalize` command belongs to 0.10. Internal deterministic normalization remains allowed in 0.9.
+- `kudzu explain`, `kudzu check --json`, `kudzu fix`, and `kudzu migrate --analyze` belong to 0.11 unless a small internal inspection tool is required to validate 0.9.
+- Broad ecosystem adapters belong to 0.12. A 0.9 fixture may add only the narrow adapter needed to prove package-neutral semantics.
+- Semantic IR freeze belongs to 1.0.
+- Public store, query, form, resource, adapter, or router APIs are not part of 0.9.
+- Generic `ResourceIR`, generic `RangeIR`, virtualization, optimistic transactions, arbitrary callback graphs, and arbitrary JavaScript evaluation remain unapproved.
+
+## Feature Decision Ladder
+
+Every proposed 0.9 slice must stop at the first applicable step:
+
+1. Use native HTML or a native browser API.
+2. Lower to the existing Semantic Kernel and current IR records.
+3. Normalize deterministically into supported canonical source.
+4. Add a package-specific internal adapter whose output is package-neutral.
+5. Request an architecture review only after at least three unrelated real fixtures prove one missing semantic concept.
+6. Otherwise reject with an actionable diagnostic.
+
+A generic browser runtime is not a step in this ladder.
+
+If one ecosystem feature requires changes in three or more unrelated core compiler subsystems, stop. Record the proposed producer/consumer edges and perform an architecture review before editing those subsystems.
+
+## Ordered Work Queue
+
+Only one item may be active. Complete its evidence and update this document before starting the next item. A semantic slice without a real failing fixture remains blocked rather than becoming speculative framework work.
+
+### 0.9.0-01: Freeze The Baseline
+
+**Status:** complete; Sessions 01A through 01G are signed off in [`0.9-baseline.md`](./0.9-baseline.md) and [`0.9-benchmark-contracts.md`](./0.9-benchmark-contracts.md).
+
+Record the current `0.8.62` baseline before changing semantics:
+
+- map every normalization pass to the canonical concept or diagnostic it produces;
+- count focused normalization passes and core semantic compiler LOC using a documented, repeatable file set;
+- record ModuleIR concepts and browser runtime concepts;
+- record standard test count, representative deploy files, raw/gzip JavaScript, and static-route zero-JavaScript output;
+- record current build measurements for the maintained source-scale fixture and available 100, 1,000, and 10,000 route catalog fixtures;
+- record the current matched React + Vite, Vue, Svelte, and Astro benchmark revisions, supported scenarios, known behavior gaps, and results;
+- record unavailable benchmark sizes as gaps instead of fabricating results or adding an unmeasured cache.
+
+**Deliverable:** add a dated baseline section to this document with commands, environment, file set, raw results or links to `PERFORMANCE.md`, and known gaps.
+
+**Done when:** `npm run check` and `npm test` pass, the baseline is reproducible, and no production source or output changed.
+
+### 0.9.0-02: Strengthen Derived
+
+**Dependency:** 0.9.0-01 and at least one real failing fixture with multi-state pure derived logic.
+
+**Status:** complete; Sessions 02A through 02I are signed off for the Medusa Product Actions and Mercury Agent Profit Sharing reductions. Medusa proves selected binding/effect fields, while Mercury reuses the same calculation identity for scalar bindings and an adjustable keyed array field. The closure adds no semantic primitive, pass, runtime concept, normalization rule, or adapter.
+
+Target semantics:
+
+```text
+explicit State/Static dependencies
+  -> pure deterministic computation
+  -> one Derived identity
+  -> property-level Binding/Effect/List consumers
+```
+
+Prefer extending the existing tagged `DerivedIR` evaluator and dependency edges. Do not add `.find()`-specific, commerce-specific, or component-specific runtime behavior.
+
+Required evidence:
+
+- at least two unrelated fixture shapes use the same derived representation before the milestone closes;
+- multiple primitive state inputs and serializable static captures are explicit;
+- unchanged selected results do not trigger unrelated effect work;
+- deterministic object/primitive result fields update known DOM targets directly;
+- impure calls, dynamic fields, mutation, cycles, opaque captures, and nondeterministic results fail closed;
+- static siblings and build-folded derived values add zero JavaScript.
+
+### 0.9.0-03: Unify Shared State And Actions
+
+**Dependency:** 0.9.0-02 and a real fixture exposing duplicated Context/Zustand/other source handling.
+
+**Status:** complete; Sessions 03A through 03G are signed off. Equivalent Context and Zustand-shaped carts now produce package-neutral shared-state/action records and generic handler edges while preserving byte-identical deploy output, layout ownership, same-turn updates, navigation, effect cleanup, and zero-JavaScript static siblings. No semantic primitive, ModuleIR kind, pass, runtime concept, or normalization entry was added.
+
+Make package-neutral `SharedStateIR` and `SharedActionIR` authoritative before generic handler, dependency, and ownership consumers. Context and Zustand-shaped source should differ at the compatibility boundary, not in browser state machinery.
+
+Required evidence:
+
+- at least two unrelated source models lower to the same generic operation and dependency consumers;
+- direct same-turn state semantics, layout lifetime, navigation persistence, and cleanup remain unchanged;
+- no generic store, subscription runtime, Context tree, or public adapter API is emitted;
+- hidden or dynamically addressed store behavior remains rejected.
+
+### 0.9.0-04: Generalize Resource Ownership
+
+**Dependency:** 0.9.0-03 and a fixture that cannot be represented by the current effect-private closure model.
+
+**Status:** complete; Sessions 04A through 04E are signed off. Existing `EffectIR` represents every maintained resource fixture, required-Chrome evidence now covers the identified executable gaps, and one shared ancestry helper removes 12 lines of duplicate lexical proof. Zero fixtures qualify for `ResourceIR`; no resource primitive, pass, runtime concept, public API, or browser bytes were added.
+
+First attempt to express the fixture as existing `EffectIR` plus explicit ownership and cleanup validation:
+
+```text
+Acquire
+Dependencies
+Owner
+Invalidation
+Cleanup
+```
+
+WebSocket, Worker, observers, timers, animation frames, canvas, and SDK instances are examples, not separate semantic primitives. Understand lifetime, not library internals.
+
+Required evidence:
+
+- exact acquire/replacement/cleanup behavior is proven under dependency change, owner release, navigation, and late async completion;
+- direct browser-only package imports remain route-owned and absent from static siblings;
+- package or resource implementation details do not enter generic runtime code;
+- `ResourceIR` is considered only under the three-fixture rule when existing `EffectIR` ownership cannot represent the shared lifetime.
+
+If no qualifying fixture exists, close this item by recording that existing effect ownership remains sufficient. Do not invent ResourceIR to complete the milestone.
+
+### 0.9.0-05: Strengthen Component Ownership And Dependencies
+
+**Dependency:** 0.9.0-04 and a real fixture that currently requires component flattening or artificial primitive-state decomposition.
+
+**Status:** complete. WorkLedger revision `3d8bf2130ec1d7698bff07fb00726b2bb94d20d4` authorizes one direct object-state prop whose direct static fields feed bindings, a selected effect dependency, and a keyed collection. ComponentAnalysis records source SignalIR/property/consumer links; existing BindingIR, expression DerivedIR, EffectIR, and binding-backed KeyedBlockIR consumers preserve repeated and conditional ownership. Dynamic paths, aliases, and mutation fail closed. No ModuleIR kind, pass, runtime concept, callback extension, cache, or browser component was added.
+
+Improve compile-time specialization of immutable object props, stable semantic callback operations, repeated components, and property-level dependency propagation. Components remain an authoring abstraction and disappear from browser output.
+
+Required evidence:
+
+- retained component boundaries compile to HTML, existing state/operation edges, and owned effects without browser component instances;
+- repeated and conditional owners remain independent and clean up exactly once;
+- prop dependency analysis subscribes only to proven source state;
+- arbitrary callbacks, dynamic prop spreads, opaque mutation, and unproven ownership still fail closed;
+- specialization caching is added only if a maintained benchmark proves repeated semantic analysis is material.
+
+### 0.9.0-06: Delete Duplication And Close The Milestone
+
+**Status:** complete. A nine-candidate ledger selects two independent deletions that remove 32 core semantic lines. Source diagnostics remain stable, all focused/full/package/browser gates pass, maintained 100/1,000/10,000-product scaling emits byte-identical output, and the final architecture review records zero new concepts, IR kinds, passes, normalization entries, runtime concepts, public APIs, or browser bytes.
+
+**Dependency:** prior items complete or explicitly closed for lack of evidence.
+
+- remove obsolete syntax-specific branches made redundant by canonical semantic lowering;
+- consolidate passes only where ownership and diagnostics remain clear;
+- compare the final semantic-core LOC and pass count with 0.9.0-01;
+- run maintained build scaling at 100, 1,000, and 10,000 routes where fixtures exist;
+- run browser and output gates for every affected capability family;
+- publish no performance claim without the protocol and raw evidence in `PERFORMANCE.md`.
+
+This item must not add compatibility solely to improve the fixture count.
+
+### 0.9.0-07: Final Cross-Framework Proof
+
+**Status:** complete. Local benchmark source remains ignored by policy. Native C1 reaches the 0 B route/session JavaScript floor across five targets, and the C2/C5 stateful, Worker, navigation, ownership, static-exclusion, resilience, and uniform metric matrices pass behavior acceptance. The final 21-profile C2 medians pass: row filter is faster than Vue, while row restore and search restore are within 3.5% and 1.8% of their nearest comparators. Flattened generated commerce input plus one-shot plan streaming, release, and staged HTML spooling makes Kudzu 2.5%/5.5% faster than Astro cold/warm at 10,000 products and cuts peak RSS 71.0% to 542,484 KiB, 11.4% below Astro. Model-driven AI delivery remains a 1.0 gate. See [`0.9-final-proof-audit.md`](./0.9-final-proof-audit.md).
+
+**Dependency:** 0.9.0-01 through 0.9.0-06 complete or explicitly evidence-closed, and the maintained comparison harness restored.
+
+Run the complete pinned content, stateful, commerce-scale, and resource comparison matrix defined in the detailed implementation plan. Behavior and accessibility acceptance must pass before timing. Record initial and session JavaScript, interaction and navigation readiness, event latency, CPU, heap, failure resilience, and 100/1,000/10,000-route build scaling with raw samples and exact framework revisions.
+
+Any material primary-metric loss blocks `0.9.0`. Do not hide a loss in a weighted score, omit failed comparator runs, or replace application proof with a synthetic microbenchmark.
+
+## Per-Slice Contract
+
+Before implementation, write the following in the PR or active work note:
+
+```text
+Authorizing fixture:
+First unsupported source location:
+Canonical semantic reduction:
+Existing IR producer:
+Existing IR consumers:
+Owner and release boundary:
+Nearby rejected forms:
+Expected browser capability delta:
+```
+
+After implementation, report:
+
+```text
+Semantic primitives added:
+Core compiler passes added/removed:
+Core compiler LOC delta:
+Runtime concepts added:
+Browser raw/gzip byte delta:
+Normalization rules added/removed:
+Adapter rules added/removed:
+Positive/negative fixtures added:
+Build and browser benchmark delta:
+```
+
+The expected result for an ecosystem-facing slice is normally:
+
+```text
+Semantic primitives       +0
+Core passes               +0 or fewer
+Runtime concepts          +0
+Normalization/adapter     +N
+Fixtures                  +N
+```
+
+## Test And Performance Gates
+
+Every semantic slice must:
+
+- add the smallest focused positive and negative fixture that proves the boundary;
+- preserve complete HTML and zero JavaScript for a static sibling;
+- prove direct DOM behavior, identity, dependency comparison, cleanup, invalidation, and remount where affected;
+- compare representative ModuleIR, RouteIR, capability signatures, emitted file lists, and raw/gzip bytes;
+- run `npm run check` and `npm test`;
+- run package smoke when package output changes;
+- apply [`performance-gates.md`](./performance-gates.md);
+- use `kudzu-based-bench` as an architectural gate when the affected scenario exists there, while recording its exact revision and commands.
+
+Test JS-disabled, delayed-JS, missing-chunk, slow-network, and slow-CPU behavior when the feature changes progressive enhancement or loading. Do not claim coverage for a scenario that is not automated or manually recorded.
+
+## Cross-Framework Proof Gate
+
+`0.9.0` must demonstrate that Kudzu produces a better user-facing result for the same application behavior, not merely that its internal architecture is smaller.
+
+The maintained comparison set is:
+
+1. React + Vite as the primary migration and authoring baseline.
+2. Vue and Svelte as representative client/compiler framework baselines.
+3. Astro as a representative HTML-first/static framework baseline.
+4. Next.js, Nuxt, SvelteKit, or another production framework when the tested scenario depends on a capability absent from the smaller baseline.
+
+Every result must pin framework versions and compare the same:
+
+- rendered content and route count;
+- user-visible behavior and data;
+- accessibility semantics and keyboard journeys;
+- production mode, compression, cache state, and hosting assumptions;
+- browser, hardware, network, CPU, and measurement protocol;
+- successful acceptance tests before performance is counted.
+
+Kudzu qualifies for `0.9.0` only when the maintained matched suite shows:
+
+- strictly lower initial and total-session browser JavaScript than every applicable comparator;
+- no hydration and stronger JS-disabled, delayed-JS, and missing-chunk behavior;
+- interaction readiness, event latency, and navigation latency that are fastest or statistically tied for fastest under the recorded protocol;
+- no material CPU or memory loss on the same journeys;
+- no remaining material 100, 1,000, or 10,000-route build-scaling weakness against the best applicable static-output comparator;
+- complete HTML and feature parity rather than benchmark-only omission;
+- the advantage persists across at least one content application and one stateful interactive application, not only microbenchmarks.
+
+A material loss blocks `0.9.0` until it is fixed, the benchmark is shown to be invalid, or the compared capability is explicitly removed from the release claim. Results may not be combined into a weighted score that hides a primary-metric loss. Raw samples, failures, output bytes, and limitations must be published in `PERFORMANCE.md`.
+
+## 0.9.0 Release Gate
+
+`0.9.0` is ready only when:
+
+- 0.9.0-01 through 0.9.0-07 are complete or explicitly closed with evidence that no semantic change is needed;
+- realistic multi-state Derived behavior is represented by existing kernel concepts;
+- shared-state package syntax is contained at compatibility boundaries;
+- resource-heavy fixtures use explicit, proven ownership without a generic resource runtime;
+- component abstraction coverage improves without retained browser components;
+- final core semantic pass count and measured core compiler LOC are no higher than the recorded baseline, unless an explicit architecture review documents why a small increase is necessary and what duplication was removed;
+- unchanged benchmark scenarios show no material runtime, browser-byte, interaction-readiness, session-transfer, or build-scaling regression;
+- the Cross-Framework Proof Gate passes against the pinned maintained comparison set;
+- all static-route and progressive-enhancement guarantees remain intact;
+- diagnostics describe every newly supported boundary and nearby rejection;
+- `npm run check`, `npm test`, package smoke, required browser journeys, and release verification pass;
+- `package.json`, `create-kudzu`, README, architecture mapping, performance records, and release notes are updated together only for the actual release.
+
+## Session Resume Protocol
+
+At the start of every new implementation session:
+
+1. Read the required documents listed above.
+2. Inspect `package.json`, `git status`, and the current work item status here.
+3. Select only the first incomplete queue item whose dependencies and fixture evidence exist.
+4. Reproduce the fixture failure before changing compiler code.
+5. Fill in the per-slice contract and choose the first valid feature-decision step.
+6. Implement the smallest semantic reduction; do not broaden neighboring syntax.
+7. Run focused checks, `npm run check`, `npm test`, output comparison, and affected benchmarks.
+8. Update this document with completion evidence and the next exact item. Update release records only for a real release.
+
+If the required fixture or benchmark is absent, document the gap and stop that slice. Do not replace evidence with speculative infrastructure.

package/docs/next-architecture/README.md

@@ -1,6 +1,6 @@
 # Kudzu Architecture Continuation
 
-This directory is the continuation packet after `0.8.15`. Planned versions remain plans until package metadata and release records mark them complete.
+This directory is the compiler continuation packet. Planned versions remain plans until package metadata and release records mark them complete.
 
 The top-level [`GOAL_A.md`](../../GOAL_A.md) and [`GOAL_B.md`](../../GOAL_B.md) are historical completed capability records. Do not overwrite or reinterpret them. The Goal A/B/C/D names in this directory refer to the next architecture discussion:
 
@@ -11,7 +11,7 @@ The top-level [`GOAL_A.md`](../../GOAL_A.md) and [`GOAL_B.md`](../../GOAL_B.md)
 | C: state/resource model | Research only | Reduced fixtures expose a limitation |
 | D: routing compatibility | Current behavior preserved | Revisit only with migration evidence and invariant review |
 
-The active post-`0.8.61` implementation sequence is [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md). P0.12 validation, property-level object-state dependencies, direct three-boundary callback/ref ownership, direct primitive, plain-object, array-prop, keyed-item draft state initialization, matching array-draft setter effects, parameterized primitive debounce hooks, repeated direct leaf-handler callback use, direct child callback fan-out, collision-free and private Context action setters, package-neutral shared-state/action IR, browser-only package imports and private mutable refs in owned effects, route/layout CSS closure, structural per-route capability/chunk reporting, signature-keyed runtime families, incremental source and affected-route development builds, measured route-entry output optimization, and the plain TypeScript source-scale fast path are complete. ResourceIR remains research for cross-owner transports and subscriptions; range ownership, virtualization, and optimistic transactions still require independent fixtures. The plan orders compiler semantic generalization, large-application foundations, compatibility boundaries, AI tooling, and production validation without changing the invariants below.
+The completed `0.9.0` milestone is recorded in [`0.9-semantic-compression.md`](./0.9-semantic-compression.md) and [`0.9-implementation-plan.md`](./0.9-implementation-plan.md). It freezes the `0.8.62` baseline, then closes evidence-backed work on Derived, shared state/actions, resource ownership, component ownership, pass reduction, and final cross-framework proof. [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md) remains the completed foundation and longer-term plan. Model-driven delivery is separately gated for 1.0. ResourceIR remains unapproved; range ownership, virtualization, optimistic transactions, public adapters, and generic runtimes still require independent evidence and architecture review.
 
 ## Required Invariants
 
@@ -25,19 +25,23 @@ The active post-`0.8.61` implementation sequence is [`large-application-ai-nativ
 
 ## Reading Order
 
-1. [`compiler-current-architecture.md`](./compiler-current-architecture.md): exact current responsibilities and data flow.
-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.
+1. [`0.9-semantic-compression.md`](./0.9-semantic-compression.md): completed scope, evidence, and release gates.
+2. [`0.9-implementation-plan.md`](./0.9-implementation-plan.md): detailed session packets, benchmark plan, reports, and release procedure.
+3. [`0.9-baseline.md`](./0.9-baseline.md): dated architecture, pass, IR, runtime-concept, LOC, and test baseline.
+4. [`0.9-benchmark-contracts.md`](./0.9-benchmark-contracts.md): frozen matched-content, stateful, commerce, scale, resource, and anti-gaming contracts.
+5. [`compiler-current-architecture.md`](./compiler-current-architecture.md): exact current responsibilities and data flow.
+6. [`performance-gates.md`](./performance-gates.md): output, build, and browser gates.
+7. [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md): completed foundation, longer-term direction, and completion evidence.
+8. [`goal-a-compiler-foundation.md`](./goal-a-compiler-foundation.md): completed extraction and generator foundation.
+9. [`versioning.md`](./versioning.md): completed patch sequence and future sequencing rules.
+10. [`goal-b-optimization-benchmarks.md`](./goal-b-optimization-benchmarks.md): active measurements, retained optimizations, and continuation rules.
+11. [`goal-c-state-resource-research.md`](./goal-c-state-resource-research.md): research boundary only.
+12. [`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.
+- [ ] Read [`MIGRATION_ROADMAP.md`](../../MIGRATION_ROADMAP.md), [`0.9-semantic-compression.md`](./0.9-semantic-compression.md), and [`0.9-implementation-plan.md`](./0.9-implementation-plan.md) before planning migration work.
+- [ ] Follow the first evidence-ready incomplete item in the 0.9 ordered queue; 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.61` 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.9.0` 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
 
@@ -13,19 +13,19 @@ This maps the current `0.8.61` architecture, built on the completed `0.8.23` Goa
 | Reachability/import resolution | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `reachableSourceFiles()`; [`framework/compiler/source-graph.mjs`](../../framework/compiler/source-graph.mjs), `ordinaryRuntimeDependencies()`, `resolveSourceImport()` | Starts from page entries, follows relative runtime imports/re-exports and validated Worker references, excludes unreachable migration source, and fails unresolved ordinary edges or dynamic imports at the importer source location before code generation. |
 | Ordered normalization | [`framework/compiler/normalization-pipeline.mjs`](../../framework/compiler/normalization-pipeline.mjs), `applyNormalizationPasses()`; [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `normalizeCompilerSource()` | Applies migration/resource passes in order and repairs TypeScript parent pointers after every structural change. Imported source uses the same pipeline. |
 | Focused normalization passes | [`framework/compiler/`](../../framework/compiler/) | React, Router, browser signals, animation-frame refs, custom-hook timers, Zustand, and render control each validate and lower a narrow source shape. |
-| Shared AST/scope helpers | [`framework/compiler/ast-helpers.mjs`](../../framework/compiler/ast-helpers.mjs) | Binding, scope, reference, effect-return, and source-location analysis. |
+| 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 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 is resolved by its adapter before generic shared-state 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, 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. |
+| 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. |
 | 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 shared-action, binding, and list AST rewriting and diagnostics before the JSON-safe IR boundary. |
+| 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 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 value. |
+| 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. |