@kudzujs/core 0.8.62 → 0.9.1

package/MIGRATION_ROADMAP.md

@@ -2,7 +2,7 @@
 
 This document is the source of truth for Kudzu's product direction, architecture invariants, and future development order. Read it before extending React-shaped syntax or browser capabilities.
 
-The executable post-`0.8.62` compiler and large-application sequence is maintained in [`docs/next-architecture/large-application-ai-native-roadmap.md`](./docs/next-architecture/large-application-ai-native-roadmap.md). Follow its PR dependencies for implementation work; this document remains authoritative when selecting or accepting a migration capability.
+The active `0.9.0` execution sequence is maintained in [`docs/next-architecture/0.9-semantic-compression.md`](./docs/next-architecture/0.9-semantic-compression.md), with session-level implementation packets in [`docs/next-architecture/0.9-implementation-plan.md`](./docs/next-architecture/0.9-implementation-plan.md). Follow its ordered work queue and evidence gates for implementation work. The completed compiler foundation and longer-term sequence remain in [`docs/next-architecture/large-application-ai-native-roadmap.md`](./docs/next-architecture/large-application-ai-native-roadmap.md); this document remains authoritative when selecting or accepting a migration capability.
 
 [`GOAL_A.md`](./GOAL_A.md) and [`GOAL_B.md`](./GOAL_B.md) are completed capability-validation records. Their commerce and realtime dashboard fixtures prove general lifecycle, navigation, async-workflow, and Worker capabilities; they are not separate product verticals or future priority lists.
 
@@ -20,6 +20,40 @@ Kudzu is a general migration compiler. Shops, dashboards, documentation, blogs,
 
 Syntax compatibility does not mean reproducing React wholesale. Kudzu accepts the statically analyzable subset it can lower to build-time output and direct browser capabilities. Unsupported nearby patterns must fail at build time with a file, line, and actionable explanation.
 
+## Version Outcomes
+
+### 0.9.0: Proven Browser Advantage
+
+`0.9.0` is not complete when Semantic Compression merely works internally. On behavior-, content-, accessibility-, and environment-matched applications, Kudzu must prove its intended advantage against React + Vite and representative Vue, Svelte, and Astro baselines:
+
+- the least initial and session browser JavaScript;
+- no hydration and complete initial HTML;
+- fastest or statistically tied-fastest interaction readiness, event, and navigation results;
+- no material CPU or memory loss;
+- stronger JavaScript failure resilience;
+- no remaining material large-route build-scaling weakness.
+
+The active 0.9 plan defines the exact comparison and release gate. Benchmark-only feature omission, unmatched accessibility, weighted scores that hide losses, and unrecorded environment differences do not count as proof.
+
+### 1.0.0: Best Framework For AI-Assisted Delivery
+
+`1.0.0` means Kudzu Semantic IR v1 is stable and Kudzu is demonstrably the best framework in the maintained AI delivery benchmark, not merely the framework with the smallest runtime.
+
+Use the same agent model, system constraints, tools, starting application requirements, context budget, time budget, and acceptance suite for every framework. Agents receive public framework documentation and normal diagnostics; Kudzu must not receive private compiler knowledge or framework-specific prompt help unavailable to competitors.
+
+Evaluate complete production-representative tasks across at least content, forms, CRUD/shared state, commerce-derived state, and resource/realtime ownership. Each result must pass behavior, accessibility, build, browser, and output checks before it counts as successful.
+
+Kudzu qualifies for `1.0.0` only when repeated trials show:
+
+- success rate is highest or statistically tied for highest against the maintained framework set;
+- median cost per successful task is lowest;
+- completion time, correction cycles, tool calls, compiler attempts, and context consumption are lowest or statistically tied for lowest;
+- ordinary source abstraction and maintainability are not sacrificed to win;
+- the resulting browser output still passes the complete `0.9.0` performance advantage gate;
+- most new ecosystem coverage is delivered through normalization, adapters, diagnostics, and optimization rather than Semantic Kernel growth.
+
+Publish task definitions, prompts, framework versions, raw attempts including failures, acceptance results, token/cost accounting, source retention, artifacts, and browser measurements. A build-only success, cherry-picked successful run, or toy-only benchmark cannot authorize `1.0.0`.
+
 ## Product Invariants
 
 - Never add React as a runtime or production dependency.
@@ -67,6 +101,7 @@ The following are available building blocks, not future vertical roadmaps:
 - Mount and dependency effects with cleanup, route/layout lifetimes, conditional/keyed ownership, stale-write isolation, and relative TypeScript Workers.
 - Direct browser-only package references in inline effect setup/cleanup callbacks bundle into route-owned effect ESM without entering build-time component execution or static sibling output.
 - Keyed local-state and imported static collections, pure selectors, nested direct-property lists, recursive and directly exported row specialization, static/keyed component reuse, analyzable specialized prop spreads, serializable literal defaults, direct intrinsic rest forwarding, forwarded JSX children, latest-item handlers, row state/effects/refs, and stable keyed identity.
+- Direct object-state props with one-segment binding/effect/list consumers when the child directly maps an array field; ComponentAnalysis links every consumer to the parent SignalIR without authored field state or a browser component.
 - Complete-document native fallback and optional shared-layout navigation groups with parameter initialization, finite prefetch caching, focus, history, cleanup, and independent capability output.
 - React-shaped SVG presentation attributes, direct `clsx` lowering, fixed-locale reactive `Intl.NumberFormat` display formatting, relative TypeScript handler helpers, and source-located diagnostics.
 

package/PERFORMANCE.md

@@ -6,7 +6,85 @@ Reproducibility classes: `npm run benchmark`, `npm run benchmark:keyed`, `npm ru
 
 The maintained 2026-08-13 comparison used Node 24.14.0 and an Intel Core i5-9500 Linux x64 host, one warm-up, and seven alternating fresh-process samples against clean `v0.8.44`. A narrow fast path skips Kudzu semantic transformation for 450 plain `.ts` modules whose runtime edges are exclusively resolvable relative TypeScript imports or exports; all other modules retain the existing transformer. Compile median fell from 2,323.9 ms to 1,413.2 ms (39.2%) and clean-build median from 3,325.3 ms to 2,382.4 ms (28.4%); every paired sample improved. Compile peak-RSS median fell from 571.2 MiB to 552.6 MiB, while build peak RSS was 570.9 MiB versus 568.8 MiB. Compiler scratch fell from 7,328,390 to 1,971,061 bytes. Both targets emitted the same 50 static HTML files, 10,980 bytes, and deploy SHA-256 `e107d78a7f55bc8a1af0ea6e53efeffa19b3d44d21c892484d103fa346e7ba7b`. This is a source-scale compiler comparison, not a cross-framework result.
 
-## Current 0.8.59 Release Snapshot
+## 0.9 Shared State And Actions
+
+Measured 2026-08-19 on Linux x64 with Node 24.14.0 and Chrome 142.0.7444.175. Baseline `abe87ceafbf70ed8eb2618976e2d1e18c378126f` and the candidate built identical final Context/Zustand cart source.
+
+| Fixture | Deploy files | Baseline and candidate JS raw / gzip | Baseline and candidate digest |
+|---|---:|---:|---|
+| Context cart | 18 | 29,951 / 13,065 B | `66897dce8fffd9e6bfb8b6a65ffba922a9f19d47dbb12c2a613dfb4b5685ee93` |
+| Zustand cart | 18 | 30,291 / 13,193 B | `9c157adc2ff9afef1c282d50cecf77f6c0d8be2251d996298155ffb396e50211` |
+
+The maintained Worker/effect graph also remains byte-identical at 907 raw / 477 gzip B for the Worker and 13,786 raw / 5,931 gzip B for the window graph. One warm-up and seven clean builds measured `[651.6,643.9,596.7,631.5,613.3,634.0,555.0]` for the baseline and `[456.6,441.3,450.2,461.8,445.7,466.8,457.5]` for the final candidate, with medians 631.5 and 456.6 ms. Targets ran sequentially at different times rather than interleaved, so this is only an artifact-size and build-completion diagnostic, not a timing comparison or claim. Required Chrome proves same-turn updates, dependency cleanup, navigation persistence, and exact layout disposal for both source models; static siblings remain zero JavaScript.
+
+## 0.9 Resource Lifecycle Evidence
+
+Measured 2026-08-19 on Linux x64 with Node 24.14.0 and Chrome 142.0.7444.175. Required-Chrome journeys execute terminal async acquisition/discard/late resolution, WebSocket dependency replacement/navigation release/stale callbacks, and package-backed effect cleanup. These are correctness journeys, not browser timing benchmarks.
+
+| Fixture graph | JavaScript raw / aggregate gzip | Static sibling |
+|---|---:|---:|
+| E2B-shaped terminal | 2,634 / 1,495 B | 0 B |
+| Route WebSocket with navigation | 15,872 / 7,163 B | 0 B |
+| Package-owned effect | 3,562,795 / 1,025,300 B | 0 B |
+
+No resource runtime, registry, or shared capability bytes were added. The package graph intentionally bundles TypeScript as isolation evidence; it is not a recommended payload and creates no package resource handle.
+
+The maintained Worker/effect benchmark remains 907 raw / 477 gzip B for the Worker graph and 13,786 raw / 5,931 gzip B for the window graph. One warm-up and seven final-candidate builds measured `[686.6,606.6,707.7,615.3,512.8,504.2,536.7]`, median 606.6 ms. This is a same-target completion diagnostic, not a revision comparison or timing claim.
+
+## 0.9 Component Object Properties
+
+Measured 2026-08-19 on Linux x64 with Node 24.14.0 and Chrome 142.0.7444.175. The WorkLedger-derived route emits 11 JavaScript files totaling 37,302 raw / 14,083 aggregate gzip B; its static sibling emits zero JavaScript. The route composes existing binding, list, native-handler, and effect families. No runtime family, browser component function, field state, or shared browser bytes were added.
+
+Required Chrome proves three repeated/conditional owners, selected array `Object.is` effect suppression, keyed identity, exact replacement cleanup/setup, conditional release/remount, and idempotent disposal. The maintained Worker/effect graph remains 907 raw / 477 gzip B for Worker and 13,786 raw / 5,931 gzip B for window output. One warm-up and seven same-target completion builds measured `[1162.6,1505.3,1140.8,938.0,758.9,753.8,717.3]`, median 938.0 ms; no comparative timing claim is made.
+
+## 0.9 Semantic Compression
+
+Measured 2026-08-19 on Linux x64 with Node 24.14.0 and Chrome 142.0.7444.175. The first 06B deletion replaces duplicated object-property and setter-callback compiler helper materialization with one internal function. Core semantic source falls from 5,296 to 5,271 lines. It adds no pass, IR kind, runtime concept, accepted source, or browser bytes.
+
+The WorkLedger deploy remains 13 files with digest `31886797161a33150afb3bcbf697545afd9d2041a4968decd33146e68d4b7595` and 37,302 raw / 14,083 aggregate gzip JavaScript bytes. The array-prop effect-sync deploy remains 10 files with digest `5e3bd8413e3d42c54e5c50d7098aa5c383e73846f7ad80201c663eae92393ec5` and 21,172 raw / 8,251 aggregate gzip JavaScript bytes.
+
+The maintained Worker/effect graph remains 907 raw / 477 gzip B for Worker and 13,786 raw / 5,931 gzip B for window output. One warm-up and seven same-target completion builds measured `[439.4,438.7,438.6,464.9,491.6,479.7,444.7]`, median 444.7 ms. No comparative timing claim is made.
+
+The second independent deletion removes primitive- and array-specific component-body scans in favor of the existing direct serializable state initializer lookup. Core semantic source falls another 7 lines to 5,264, for 32 lines removed in Session 06B. Parameterized-debounce output remains 13 files, 16,053 raw / 7,735 aggregate gzip JavaScript bytes, and deploy SHA-256 `b7106651c6a619b01a3e98101df4ac68f9262803e6729451ef03ed3971b36dc7`. Array-prop effect-sync output remains unchanged at the values above.
+
+The maintained Worker/effect graph again remains byte-identical. One warm-up and seven same-target completion builds measured `[584.0,521.7,552.6,496.7,481.4,507.7,494.2]`, median 507.7 ms. Host load differs from the first run, so no timing comparison is made.
+
+### 0.9 Final-Proof Candidate Diagnostics
+
+Measured 2026-08-19 on Linux x64, Node 24.14.0, Chrome 142.0.7444.175, and an Intel Core i5-9500. Local benchmark source and raw files remain ignored; accepted medians, artifact values, environment, candidate revision, and deploy digests are recorded in the final-proof audit.
+
+The five-target content application first exposed an 11,348 B Kudzu state-backed disclosure versus 410 B Astro inline JavaScript. Native `<details>/<summary>` preserves accessibility, disabled-JavaScript, native-navigation, and missing-script acceptance while reducing every target's route/session JavaScript to 0 B. Kudzu emits 8,441 total bytes and no deployed JavaScript; Astro emits 8,680 total bytes and no deployed JavaScript.
+
+Five-target runtime and capability matrices each used one warm-up, seven rotating clean builds, and seven fresh rotating Chrome profiles. Kudzu emits 33,831 raw / 13,236 gzip B JavaScript for the stateful matrix versus 193,685 / 60,035 B React, 64,023 / 24,772 B Vue, 40,726 / 15,659 B Svelte, and 195,371 / 61,352 B Astro+React. Median Kudzu scalar, row update, append, effect, and async operations are 0.9, 2.4, 3.2, 1.2, and 0.6 ms. Worker and navigation medians plus limitations are in the final-proof audit.
+
+The completed frozen C2 rerun expands that stateful matrix to immutable object replacement, multi-state derived output, keyed row-local state/effect/ref ownership, filter/restore, conditional cleanup/fresh remount, accessible SVG keyboard state, a static sibling, and blocked/delayed/missing-JavaScript acceptance. Across 21 fresh rotating profiles every target passes all 19 operations and ownership checks. Kudzu emits 43,567 raw / 16,408 gzip B deploy JavaScript and transfers 45,721 B in the session versus 196,089 / 60,661 B and 196,287 B React, 66,620 / 25,624 B and 66,817 B Vue, 44,046 / 16,818 B and 44,243 B Svelte, and 197,771 / 61,994 B and 198,361 B Astro+React. Fresh-process build RSS, deterministic digests, preload graphs, script CPU, and load/journey heap are recorded. Row-local ref resolution, synchronous cleanup, per-list lifecycle gating, shared list-item and ownership-path maps, item-dependency transport gating, structural row fill/ID plans, row-state release cleanup, and boolean-toggle specialization reduce Kudzu's row filter, row restore, and search restore medians from 34.6, 208.6, and 77.5 ms to 12.0, 62.6, and 51.6 ms. Row filter is faster than Vue's 13.3 ms; row restore and search restore are within 3.5% and 1.8% of their nearest comparator medians of 60.5 and 50.7 ms. C2 passes.
+
+The completed C5 rerun records 32 balanced Worker starts, invalidations, listener removals, terminations, and ignored late callbacks after replacement plus 30 mount/dispose cycles for every target, with zero stale mutations and zero final active handles. Kudzu emits 17,639 raw / 8,189 gzip B and transfers 19,402 B for that Worker session versus 193,422 / 60,159 B and 193,607 B React and 195,108 / 61,493 B and 195,685 B Astro+React. Uniform build RSS, deterministic digests, preload graphs, script CPU, load/journey/disposal heap, and active balances are recorded. Chrome reports zero `V8CompileDuration` for most targets, so `ScriptDuration` is the maintained uniform execution measure unless a later trace separates parse cost.
+
+The public commerce fixture prepares generated source and identical assets once per size outside the timed framework interval, then compares Kudzu and Astro with acceptance before timing and rotating cold/warm samples. Its Kudzu adapter now emits only the flattened page props and bounded collection rows actually compiled instead of a 37 MiB nested catalog literal. At 1,000 products and seven rotating runs, Kudzu cold/warm medians are 2,948.9 / 2,964.3 ms and peak RSS is 264,600 KiB versus Astro 3,835.3 / 3,845.0 ms and 408,100 KiB. Kudzu is 23.1% / 22.9% faster and uses 35.2% less peak RSS; it emits 1,011 pages, 10,057,806 B, and digest `468800762dd6977644e9d3f2bf018bd951cf08487fe42f99360d3b55db567cc9`.
+
+At 10,000 products, both targets pass sampled-product acceptance and emit 10,011 pages. Kudzu cold/warm medians are 22,614.0 / 22,150.6 ms versus Astro 23,198.1 / 23,438.2 ms, so Kudzu is 2.5% / 5.5% faster. One-shot CLI builds intern repeated RouteIR descriptors, update validated records in place, spool rendered HTML to staging until runtime families are known, stream the unchanged pretty plan in 64-route batches, and release standalone route plans after serialization; dev, incremental, navigation, and `afterBuild` retain their plans. Peak RSS falls 71.0% from 1,870,904 to 542,484 KiB, 11.4% below Astro's 612,412 KiB, while output remains 96,379,876 B with digest `811234693329ebd61eeceb6cd05e5d52473e5c81972a820253bf1aea664a0910`. The 10,000-route build-time and RSS gates pass.
+
+The final 2026-08-20 completion run passes `npm run check`, all 246 required-Chrome tests, fresh-install package smoke, and the maintained Worker benchmark. The Worker graph is 907 raw / 477 gzip B and the window graph is 14,093 raw / 6,037 gzip B; seven clean builds after one warm-up have a 535.9 ms median. This is a same-target completion diagnostic, not a revision timing claim.
+
+The public `kudzu-based-bench` storefront then received one warm-up and seven alternating clean builds at 100, 1,000, and 10,000 generated products against the preceding `bb7fdc5` commit. Baseline and candidate output is byte-identical at every size. Timing distributions overlap and no build improvement or regression is claimed.
+
+| Products | Pages / files | Output bytes | Baseline median | Candidate median |
+|---:|---:|---:|---:|---:|
+| 100 | 111 / 148 | 1,368,823 | 2,767.3 ms | 2,755.4 ms |
+| 1,000 | 1,011 / 1,048 | 10,164,835 | 8,407.7 ms | 8,190.3 ms |
+| 10,000 | 10,011 / 10,048 | 97,521,905 | 63,966.5 ms | 64,217.4 ms |
+
+```text
+100 baseline: [2671.0,2768.9,2881.5,2845.5,2767.3,2561.2,2705.8]
+100 candidate: [2746.4,2796.4,2755.4,2812.7,2590.6,2494.1,2767.2]
+1000 baseline: [8733.3,8059.4,8444.8,7923.9,7947.1,8407.7,8666.0]
+1000 candidate: [8048.9,7927.7,8711.0,8640.6,8190.3,8171.3,8746.9]
+10000 baseline: [65514.0,62738.0,64195.7,63610.6,63966.5,66885.2,63434.2]
+10000 candidate: [62222.9,63710.3,64217.4,64236.1,63288.2,65652.3,64977.8]
+```
+
+## Historical 0.8.59 Release Snapshot
 
 Kudzu 0.8.59 broadens existing compile-time setter-child specialization to one direct parent array-state prop and one direct `set*` setter prop in that prop-derived state shape. It adds no browser runtime code and makes no timing claim.
 

package/README.md

@@ -12,9 +12,9 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 *Watch: React-shaped TSX to static HTML and route-specific ESM in 22 seconds.*
 
-> Experimental `0.8.x`: the compiler API and supported TSX surface may change.
+> Experimental `0.9.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.8.62 - Outside-click hook ownership.** React `createRef()` and one parameterized relative outside-click hook compile through existing DOM-ref, effect capture, and cleanup ownership without a listener runtime. Read the [release notes](./RELEASES.md#0862---outside-click-hook-ownership), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.8.62), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.9.1 - Positional primitive lists.** JSON-safe primitive values now render in position-keyed collections while property-keyed rows retain their plain-object boundary. Read the [release notes](./RELEASES.md#091---positional-primitive-lists), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.9.1), or follow the [architecture packet](./docs/next-architecture/README.md).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)

package/RELEASES.md

@@ -1,5 +1,59 @@
 # Kudzu Releases
 
+## 0.9.1 - Positional primitive lists
+
+Kudzu 0.9.1 allows JSON-safe primitive values in lists keyed by their authored
+position while retaining the plain-object requirement for property-keyed rows.
+
+### Changed in 0.9.1
+
+- Build and browser list validation now accept primitive positional rows.
+- Compact object-row serialization ignores primitive arrays instead of treating
+  their values as object records.
+- Lupin-derived fixtures prove realtime rooms, lobby and private-room entry,
+  stopwatch ownership, chat and spectator replacement, Canvas/RAF input,
+  IME handling, panic shortcuts, and exact cleanup without a game runtime.
+
+### Validation
+
+- Static sibling routes remain complete HTML with zero JavaScript.
+- `npm run check`, `npm test`, and `npm run test:package` pass with 253 tests.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.9.1
+```
+
+## 0.9.0 - Semantic compression
+
+Kudzu 0.9.0 consolidates evidence-backed React migration shapes onto the existing signal, handler, effect, component-ownership, and keyed-list semantics without adding React, hydration, a VDOM, or a retained browser component tree.
+
+### Changed in 0.9.0
+
+- Relative calculated result fields, Context and reduced Zustand actions, object-property component consumers, custom hooks, refs, and multi-boundary callbacks specialize through existing package-neutral IR and ownership.
+- Keyed row state, effects, refs, conditions, nested collections, SVG, and reactive selectors preserve identity and cleanup with route-specific capabilities only.
+- One-shot production builds intern repeated route descriptors, stream plan evidence, release standalone plans, and stage rendered HTML until runtime families are known.
+- `create-kudzu@0.1.103` generates projects on the `@kudzujs/core@^0.9.0` line.
+
+### Performance
+
+- The frozen 21-profile C2 matrix passes all 19 behavior and ownership checks; row filter is faster than Vue, while row restore and search restore are within 3.5% and 1.8% of their nearest comparators.
+- At 10,000 products Kudzu emits 10,011 accepted pages with cold/warm medians of 22,614.0 / 22,150.6 ms and 542,484 KiB peak RSS, versus Astro's 23,198.1 / 23,438.2 ms and 612,412 KiB.
+- Static C1 routes ship zero JavaScript, and C5 Worker replacement/disposal finishes with balanced ownership and zero stale mutations or active handles.
+
+### Validation
+
+- `npm run check` and all 246 required-Chrome tests pass.
+- Fresh-install package smoke and maintained production benchmarks pass.
+- The 10,000-product deploy remains 96,379,876 B with SHA-256 `811234693329ebd61eeceb6cd05e5d52473e5c81972a820253bf1aea664a0910`.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.9.0
+```
+
 ## 0.8.62 - Outside-click hook ownership
 
 Kudzu 0.8.62 compiles the ClimateCompatibleGrowth `createRef()` and parameterized outside-click custom-hook shape through existing DOM-ref, effect-capture, and cleanup ownership.

package/bin/kudzu.mjs

@@ -1,10 +1,19 @@
 #!/usr/bin/env node
 
 import * as module from "node:module"
+import { spawnSync } from "node:child_process"
+import { fileURLToPath } from "node:url"
 
 const command = process.argv[2] ?? "dev"
 
-if (command === "build" || command === "dev") {
+if (command === "build" && !process.env.KUDZU_BUILD_CHILD) {
+  const child = spawnSync(process.execPath, ["--expose-gc", "--max-semi-space-size=8", fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+    stdio: "inherit",
+    env: { ...process.env, KUDZU_BUILD_CHILD: "1" }
+  })
+  if (child.error) throw child.error
+  process.exitCode = child.status ?? 1
+} else if (command === "build" || command === "dev") {
   module.enableCompileCache?.()
   const { build, dev } = await import("../framework/build.mjs")
   await (command === "build" ? build : dev)()