@kudzujs/core 0.16.15 → 0.16.16

package/MIGRATION_ROADMAP.md

@@ -57,7 +57,7 @@ Syntax compatibility does not mean reproducing React wholesale. Kudzu accepts th
 - stronger JavaScript failure resilience;
 - no remaining material large-route build-scaling weakness.
 
-The completed 0.9 plan defines the cross-framework comparison and release gate. The active application packet is `0.21.1` in the capability release plan below. Benchmark-only feature omission, unmatched accessibility, weighted scores that hide losses, and unrecorded environment differences do not count as proof.
+The completed 0.9 plan defines the cross-framework comparison and release gate. The active application packet is `0.21.2` in the capability release plan below. Benchmark-only feature omission, unmatched accessibility, weighted scores that hide losses, and unrecorded environment differences do not count as proof.
 
 ### 0.10.0 Through 0.21.x: Application Capability Release Train
 

package/PERFORMANCE.md

@@ -2,18 +2,22 @@
 
 Reproducibility classes: `npm run benchmark`, `npm run benchmark:keyed`, `npm run benchmark:native`, `npm run benchmark:module-cache`, `npm run benchmark:project-navigation`, `npm run benchmark:project-state`, `npm run benchmark:source-scale`, and `npm run benchmark:ai-delivery` are maintained in this repository; `npm run benchmark:commerce` is a maintained paired runner over the public external storefront; older excluded-workspace sections are historical provenance only and are not current framework rankings.
 
-## 0.21.1 Compiler And Route Scale (Partial)
+## 0.21.1 Compiler And Route Scale
 
 Measured 2026-09-01 on Linux x64 with Node 24.14.0, an Intel i5-9500, six
-logical CPUs, and 31.2 GiB RAM. Each recorded scale uses one warm-up and three
-measured fresh-process samples. The generated topology contains nine imported
-modules plus one page per route and 1,011 lines per route. Fixture generation is
-excluded. These are absolute candidate measurements, not regression claims.
+logical CPUs, and 31.2 GiB RAM. The 100- and 1,000-route scales use one warm-up
+and three measured fresh-process samples. The 10,000-route scale records one
+complete full-contract run with no warm-up after two diagnostic runs completed
+the measured stages but exposed cleanup and recovery-timeout harness defects.
+The generated topology contains nine imported modules plus one page per route
+and 1,011 lines per route. Fixture generation is excluded. These are absolute
+candidate measurements, not cross-framework claims.
 
 | Routes | Modules / lines | Graph median | TypeScript parse median | Normalize median | Compile/transform median | Render median | Write median | Clean median / RSS | Incremental median / retained-session peak RSS |
 |---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
 | 100 | 1,000 / 101,100 | 1,184.4 ms | 1,796.7 ms | 37.9 ms | 2,428.1 ms | 456.5 ms | 70.4 ms | 7,444.3 ms / 672.3 MiB | 1,838.0 ms / 680.9 MiB |
 | 1,000 | 10,000 / 1,011,000 | 12,152.6 ms | 18,717.6 ms | 302.9 ms | 23,681.5 ms | 4,919.4 ms | 521.7 ms | 77,515.9 ms / 3,182.3 MiB | 18,132.1 ms / 3,281.1 MiB |
+| 10,000 | 100,000 / 10,110,000 | 103,200.9 ms | 232,840.3 ms | 2,350.3 ms | 244,578.3 ms | 44,885.7 ms | 6,690.1 ms | 1,117,753.0 ms / 5,461.0 MiB | 643,697.2 ms / 8,266.9 MiB |
 
 The exact 100-route runs are source read `[30.5, 30.3, 24.7]`, graph
 `[1273.8, 1138.8, 1184.4]`, parse `[1749.8, 1911.6, 1796.7]`, normalize
@@ -33,6 +37,13 @@ incremental build `[22359.7, 18132.1, 17097.2]` ms. Clean-build RSS is
 `[3181.5, 3182.3, 3188.5]` MiB and retained-session peak RSS is
 `[3281.0, 3281.1, 3284.5]` MiB.
 
+The complete 10,000-route run records source read `17077.4`, graph `103200.9`,
+TypeScript parse `232840.3`, normalize `2350.3`, compile/transform `244578.3`,
+render `44885.7`, write `6690.1`, clean build `1117753.0`, and incremental
+build `643697.2` ms. Compile-only RSS is 5,561.4 MiB, clean-build RSS is
+5,461.0 MiB, and retained-session peak RSS is 8,266.9 MiB under
+`--max-old-space-size=10240`.
+
 Graph time excludes measured TypeScript parsing. Compile/transform excludes
 measured TypeScript parse and Kudzu normalization, but includes the indivisible
 esbuild parse/transform call for proven import-free modules. Render includes
@@ -52,14 +63,19 @@ At 1,000 routes, clean output is 1,000 files / 221,780 B with digest
 `ccdd2630bcaf9fac4a481b64c69982c341e4798205bb9fbb4cac67d528246635`;
 the source change produces digest
 `024811a5f4598d5025abc57320695503b2d63d0fd6aa54bcf79efde848c2a94e`.
-Both failure probes reject invalid source without changing the prior deploy and
-recover to the clean digest after source restoration.
-
-The default 10,000-route topology would contain 100,000 modules and 10,110,000
-lines. Extrapolating from the measured 1,000-route RSS is not acceptance
-evidence, and this 31.2 GiB host is not used for an unsafe or reduced substitute.
-The packet remains incomplete until the full topology runs on a separately
-provisioned host. Opt-in internal timing adds no semantic primitive, compiler
+At 10,000 routes, clean output is 10,000 files / 2,237,780 B with digest
+`7a48bc40ff33c4faaef8a01ab90fcfe611a4bada5364a6fedca42f80ad5070d3`;
+the source change emits 2,237,788 B with digest
+`09a42f84b4ce16c994a8bd55b92e5b645c716168f9290d241cfe27903ccfe98f`.
+Both clean and retained-session failure probes reject invalid source without
+changing the prior deploy and recover to the expected digest.
+
+The first full 10,000-route attempt exhausted a 10,240 MiB V8 heap while the
+unbounded canonical module cache retained roughly 90,000 parent-linked
+TypeScript ASTs. Bounding complete canonical records to 1,024 retains stable
+position-based symbols while allowing old ASTs to be collected. The identical
+100,000-module / 10,110,000-line topology then completed under the same heap cap.
+This adds eight net production compiler lines, no semantic primitive, compiler
 pass, runtime concept, public API, deploy file, or browser byte.
 
 ## 0.21.0 Functional Parity Matrix

package/README.md

@@ -14,7 +14,7 @@ Kudzu compiles ordinary React-shaped TypeScript and TSX into complete static HTM
 
 > Experimental `0.16.x`: the compiler API and supported TSX surface may change.
 
-**Latest release: 0.16.15 - Production evidence gates.** Kudzu now records compiler phase and retained-session scale evidence, rejects incomplete AI attribution, and runs the 10,000-item pagination decision as ordinary browser acceptance. Read the [release notes](./RELEASES.md#01615---production-evidence-gates), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.16.15), or follow the [architecture packet](./docs/next-architecture/README.md).
+**Latest release: 0.16.16 - Bounded compiler module cache.** Kudzu now completes the full 10,000-route, 100,000-module source-scale contract under a 10 GiB V8 heap by bounding retained canonical TypeScript AST records. Read the [release notes](./RELEASES.md#01616---bounded-compiler-module-cache), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.16.16), 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,34 @@
 # Kudzu Releases
 
+## 0.16.16 - Bounded Compiler Module Cache
+
+Kudzu 0.16.16 bounds canonical TypeScript AST retention so the complete
+10,000-route production-scale contract runs under a 10 GiB V8 heap.
+
+### Changed in 0.16.16
+
+- Bounds complete canonical module records to a 1,024-entry LRU while preserving
+  stable position-based module symbols and reparsing evicted source on demand.
+- Fixes the measured 10,000-route failure where roughly 90,000 retained
+  parent-linked TypeScript ASTs exhausted a 10,240 MiB heap.
+- Completes the identical 100,000-module / 10,110,000-line topology with 5,461.0
+  MiB clean-build RSS and 8,266.9 MiB retained-session peak RSS.
+- Verifies 10-module / one-page incremental scope, byte-identical changed-clean
+  output, deterministic digests, and clean and retained-session recovery.
+- Adds scale-aware recovery timeout, diagnostic stage progress, and bounded
+  temporary-fixture cleanup retries to the maintained benchmark harness.
+- Adds eight net production compiler lines, no semantic primitive, compiler
+  pass, runtime concept, application API, dependency, deploy artifact, or
+  browser byte.
+- Updates `create-kudzu@0.1.141` to generate projects on
+  `@kudzujs/core@^0.16.16`.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.16.16
+```
+
 ## 0.16.15 - Production Evidence Gates
 
 Kudzu 0.16.15 turns compiler scale, large-list parity, and AI attribution gaps

package/docs/next-architecture/README.md

@@ -15,7 +15,7 @@ The completed `0.9.0` milestone is recorded in [`0.9-semantic-compression.md`](.
 
 [`1.0-large-application-compatibility-audit.md`](./1.0-large-application-compatibility-audit.md) records the first post-0.9 probes against Memos, Apache Answer, and Actual Budget. The audit finds that reduced slices build but whole-application source retention and behavior parity do not yet pass.
 
-[`application-capability-release-plan.md`](./application-capability-release-plan.md) is the authoritative post-0.9 execution queue, currently at `0.21.1`. It assigns one application-capability section to each minor release and one independently accepted evidence packet to each patch release from `0.10.0` through the `1.0.0` gate. It supersedes the provisional 0.10/0.11/0.12 tool-first ordering in the completed 0.9 handoff without rewriting that historical record.
+[`application-capability-release-plan.md`](./application-capability-release-plan.md) is the authoritative post-0.9 execution queue, currently at `0.21.2`. It assigns one application-capability section to each minor release and one independently accepted evidence packet to each patch release from `0.10.0` through the `1.0.0` gate. It supersedes the provisional 0.10/0.11/0.12 tool-first ordering in the completed 0.9 handoff without rewriting that historical record.
 
 ## Required Invariants
 

package/docs/next-architecture/application-capability-release-plan.md

@@ -1987,7 +1987,7 @@ inventory pass. No production feature changed, so no release is consumed.
 - **Done condition:** repeated measurements and all material regressions are
   explained or fixed.
 
-**Progress:** opt-in internal telemetry now records source reads, reachable
+**Result:** opt-in internal telemetry records source reads, reachable
 graph discovery, TypeScript parse, normalize, compile/transform, render, and
 write boundaries without changing deploy output. Compile/transform excludes
 the measured TypeScript parse and Kudzu normalization but includes indivisible
@@ -2009,10 +2009,21 @@ incremental medians are 1,838.0 and 18,132.1 ms, recompiling exactly 10 modules
 and rendering one page in every sample. Clean and changed digests differ,
 incremental output equals a clean changed-source build, and clean and retained
 failure probes preserve then recover the expected digest. Exact phase samples,
-bytes, and digests are recorded in `PERFORMANCE.md`. The full 10,000-route,
-100,000-module, 10,110,000-line run remains explicitly incomplete pending a
-separately provisioned host; no projection or reduced topology is counted as a
-pass, so this packet does not yet authorize a version or release.
+bytes, and digests are recorded in `PERFORMANCE.md`.
+
+The full 10,000-route / 100,000-module / 10,110,000-line topology initially
+exhausted a 10,240 MiB V8 heap because the canonical module cache retained about
+90,000 complete TypeScript ASTs. A 1,024-record LRU bounds that existing cache
+without changing stable position-based symbols. The identical topology then
+completed under the same heap cap with 5,461.0 MiB clean-build RSS and 8,266.9
+MiB retained-session peak RSS. It emits 10,000 files / 2,237,780 B with clean
+digest `7a48bc40ff33c4faaef8a01ab90fcfe611a4bada5364a6fedca42f80ad5070d3`;
+incremental output matches a clean changed-source build, recompiles 10 modules,
+renders one page, and clean and retained recovery pass. One complete measured
+run is retained after two diagnostic runs completed measured stages but exposed
+cleanup and timeout defects; no projection or reduced topology is counted.
+The memory fix adds eight net production lines, no semantic primitive, pass,
+runtime concept, public API, deploy artifact, or browser byte.
 
 ### `0.21.2`: Browser Performance And Memory
 
@@ -2186,4 +2197,4 @@ release transaction where possible or document and publish a forward-fix patch.
 | `0.20.4` | Released as `0.16.14` | Preserve pinned equal conditions, isolated paired attempts, raw failures, independent acceptance, attribution, failure-inclusive costs, source retention, and browser artifact evidence. | Deterministic fixture validates the protocol only; no framework ranking claimed |
 | `0.20.5` | Closed by measured stop condition | Preserve the negative tooling-cost result and do not present structured tools as an AI cost reduction. | Tool-assisted attempts cost 16,933 more tokens per success; no release consumed |
 | `0.21.0` | Closed by existing semantics | Preserve the complete browser parity matrix, large-list keyboard/release acceptance, and static exclusion controls. | No production change; no release consumed |
-| `0.21.1` | Active; telemetry released as `0.16.15` | Preserve the 100/1,000-route phase, RSS, output, digest, incremental-equivalence, and recovery evidence, then run the full separately provisioned 10,000-route topology. | 10,000-route / 100,000-module run remains pending; no projection is accepted |
+| `0.21.1` | Released as `0.16.16` | Preserve 100/1,000/10,000-route phase, RSS, output, digest, incremental-equivalence, recovery, and bounded canonical-AST retention evidence. | Full 10,000-route report has one complete measured run after two measured-stage diagnostics; no projection used |

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

@@ -1,6 +1,6 @@
 # Current Compiler Architecture
 
-This maps the current `0.16.15` architecture, built on the completed `0.9.0` semantic-compression release and `0.8.23` Goal A compiler foundation. The active application packet is `0.21.1`; file and function names are the stable references, while line numbers are intentionally omitted because later work may still move code.
+This maps the current `0.16.16` architecture, built on the completed `0.9.0` semantic-compression release and `0.8.23` Goal A compiler foundation. The active application packet is `0.21.2`; file and function names are the stable references, while line numbers are intentionally omitted because later work may still move code.
 
 ## Responsibility Map
 

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

@@ -2,9 +2,9 @@
 
 ## Status
 
-Completed compiler-foundation record and longer-term plan after `0.8.35`. The [`0.9-semantic-compression.md`](./0.9-semantic-compression.md) execution queue is complete. The active queue for current work is [`application-capability-release-plan.md`](./application-capability-release-plan.md) at packet `0.21.1`. This document does not mark any remaining planned capability as supported and does not authorize a React runtime, VDOM, hydration, retained browser component tree, generic rerenderer, public store/query/resource API, SPA router, or islands.
+Completed compiler-foundation record and longer-term plan after `0.8.35`. The [`0.9-semantic-compression.md`](./0.9-semantic-compression.md) execution queue is complete. The active queue for current work is [`application-capability-release-plan.md`](./application-capability-release-plan.md) at packet `0.21.2`. This document does not mark any remaining planned capability as supported and does not authorize a React runtime, VDOM, hydration, retained browser component tree, generic rerenderer, public store/query/resource API, SPA router, or islands.
 
-[`MIGRATION_ROADMAP.md`](../../MIGRATION_ROADMAP.md) remains the product authority for product invariants and fixture-driven feature selection. [`application-capability-release-plan.md`](./application-capability-release-plan.md) is authoritative for current work order and evidence at packet `0.21.1`; this plan retains the completed foundation, deferred program, and long-term production gates. If implementation evidence changes either boundary, update the relevant document before broadening a patch.
+[`MIGRATION_ROADMAP.md`](../../MIGRATION_ROADMAP.md) remains the product authority for product invariants and fixture-driven feature selection. [`application-capability-release-plan.md`](./application-capability-release-plan.md) is authoritative for current work order and evidence at packet `0.21.2`; this plan retains the completed foundation, deferred program, and long-term production gates. If implementation evidence changes either boundary, update the relevant document before broadening a patch.
 
 ## Product Outcome
 
@@ -483,4 +483,4 @@ The first comparison is Kudzu versus React + Vite using the same agent, model, t
 
 ## Immediate Decision
 
-All listed foundation and `0.9` slices are complete. Current work continues at `0.21.1` compiler and route scale under the [`application-capability-release-plan.md`](./application-capability-release-plan.md); keep ResourceIR limited to qualifying independent fixtures, and do not add range ownership, virtualization, optimistic transactions, a public adapter/store API, or a router before evidence justifies them.
+All listed foundation and `0.9` slices are complete. Current work continues at `0.21.2` browser performance and memory under the [`application-capability-release-plan.md`](./application-capability-release-plan.md); keep ResourceIR limited to qualifying independent fixtures, and do not add range ownership, virtualization, optimistic transactions, a public adapter/store API, or a router before evidence justifies them.

package/docs/next-architecture/versioning.md

@@ -1,6 +1,6 @@
 # Planned Version Sequence
 
-This is an execution sequence, not release history. `0.8.16` through `0.8.62` are completed scopes represented by package/release records. The `0.10.0` through `1.0.0` minor/patch sequence is maintained in [`application-capability-release-plan.md`](./application-capability-release-plan.md), currently at `0.21.1`; that plan supersedes the provisional tool-first 0.10/0.11/0.12 ordering in the completed 0.9 handoff.
+This is an execution sequence, not release history. `0.8.16` through `0.8.62` are completed scopes represented by package/release records. The `0.10.0` through `1.0.0` minor/patch sequence is maintained in [`application-capability-release-plan.md`](./application-capability-release-plan.md), currently at `0.21.2`; that plan supersedes the provisional tool-first 0.10/0.11/0.12 ordering in the completed 0.9 handoff.
 
 Keep each patch behavior-preserving and independently reviewable. If a boundary proves inseparable, revise this plan before combining releases; do not silently broaden a patch.
 
@@ -66,7 +66,7 @@ Keep each patch behavior-preserving and independently reviewable. If a boundary
 
 ## Generator Versions
 
-`create-kudzu@0.1.140` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.16.15`.
+`create-kudzu@0.1.141` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.16.16`.
 
 ## Release Boundary
 

package/framework/compiler/project-session.mjs

@@ -28,6 +28,7 @@ export function createProjectSession(projectRoot = process.cwd(), { counters, so
 }
 
 function createModuleCache(root, sourceIndex, graph, counters, timings) {
+  const recordLimit = 1024
   const records = new Map()
   let resolvedExports = new WeakMap()
   const moduleName = file => relative(root, file).replaceAll(sep, "/")
@@ -46,7 +47,11 @@ function createModuleCache(root, sourceIndex, graph, counters, timings) {
   const read = (file, source = sourceIndex.get(file)) => {
     if (typeof source !== "string") throw new Error(`Source text is unavailable for ${file}`)
     const cached = records.get(file)
-    if (cached?.source === source) return cached
+    if (cached?.source === source) {
+      records.delete(file)
+      records.set(file, cached)
+      return cached
+    }
     const parseBefore = timings ? ts.performance.getDuration("Parse") : 0
     const sourceFile = graph.parseSourceFile(file, source)
     if (timings) timings.parseMs = (timings.parseMs ?? 0) + ts.performance.getDuration("Parse") - parseBefore
@@ -54,7 +59,9 @@ function createModuleCache(root, sourceIndex, graph, counters, timings) {
     const summary = summarizeModule(file, sourceFile, moduleSymbol, siteId)
     increment("exportSummaries")
     const record = { source, sourceFile, ...summary }
+    records.delete(file)
     records.set(file, record)
+    if (records.size > recordLimit) records.delete(records.keys().next().value)
     resolvedExports = new WeakMap()
     return record
   }

package/package.json

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