@kudzujs/core 0.16.14 → 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.20.5` 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,6 +2,133 @@
 
 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
+
+Measured 2026-09-01 on Linux x64 with Node 24.14.0, an Intel i5-9500, six
+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
+`[37.2, 37.9, 41.4]`, compile/transform `[2428.1, 2828.6, 2381.1]`, render
+`[516.7, 416.9, 456.5]`, write `[95.3, 53.1, 70.4]`, clean build
+`[7444.3, 7269.2, 8156.1]`, and incremental build
+`[1631.9, 1907.7, 1838.0]` ms. Clean-build RSS is
+`[672.3, 658.6, 675.1]` MiB and retained-session peak RSS is
+`[707.1, 673.9, 680.9]` MiB.
+
+The exact 1,000-route runs are source read `[296.7, 315.7, 271.2]`, graph
+`[12152.6, 12308.1, 10011.3]`, parse `[19099.5, 18717.6, 16398.2]`,
+normalize `[259.6, 302.9, 315.8]`, compile/transform
+`[27200.6, 23681.5, 21608.7]`, render `[4919.4, 4454.6, 5238.7]`, write
+`[748.6, 521.7, 487.8]`, clean build `[77515.9, 70196.9, 82980.2]`, and
+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
+provisional page materialization; write includes artifact finalization and
+staged-output promotion. Clean build is an end-to-end wall clock and is not the
+sum of the reported phase boundaries.
+
+Every incremental sample recompiles exactly 10 modules, renders one page,
+matches a clean build of the changed source byte-for-byte, rejects invalid
+source in the retained session without changing output, and recovers in that
+same session after source restoration.
+At 100 routes, clean output is 100 files / 21,980 B with digest
+`61525962c70c5e69a975a656781e598cf6665137d648be82f1c3d5e73f0b1b48`;
+the source change produces digest
+`4c7e0f098f3f3236b6e04fa96e8057341c3aa8bdb35a72fe701e78be06160154`.
+At 1,000 routes, clean output is 1,000 files / 221,780 B with digest
+`ccdd2630bcaf9fac4a481b64c69982c341e4798205bb9fbb4cac67d528246635`;
+the source change produces digest
+`024811a5f4598d5025abc57320695503b2d63d0fd6aa54bcf79efde848c2a94e`.
+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
+
+Measured 2026-09-01 on Linux x64 with Node 24.14.0 and required Chrome. The
+300-test suite passes the maintained content, authentication, forms, CRUD,
+shared-data, large-list, overlay, editor, lazy-load, realtime, error,
+accessibility, and navigation browser journeys. Greenfield `/help`, Apache
+Answer and Memos `/public`, editor `/static`, and the direct 10,000-row route
+remain the corresponding static exclusion controls.
+
+The previously benchmark-only 10,000-item pagination decision now runs once as
+ordinary browser acceptance. Enter advances the native control to rows 101-200,
+focus remains on the control, returning to rows 1-100 releases the old row and
+restores fresh input state, the DOM remains bounded to 100 rows, and no browser
+exception occurs. Its deploy contains 19 files totaling 1,900,048 raw / 242,968
+aggregate gzip B with digest
+`1bbaf3479ac90f923deb469c73eb93c0dd7364e7fe906919b167f2f854deda70`.
+The selected pagination route owns 30,143 raw / 11,193 gzip B JavaScript; the
+complete direct 10,000-row HTML control owns 0 B JavaScript. This freezes
+behavior rather than making a new timing claim.
+
+No fixture source, compiler, IR, normalization pass, runtime concept, public API,
+or browser artifact changed. One focused browser acceptance test and one
+artifact-baseline entry were added. `npm run check`, required-Chrome 300/300,
+package smoke, and the artifact inventory pass, so no release version is
+consumed.
+
+## 0.20.5 Tooling Cost Validation
+
+Measured 2026-09-01 on Linux x64 with Node 24.14.0, OpenCode 1.18.25, and
+`openai/gpt-5.6-sol`. Five interleaved attempts per condition repaired the same
+Apache Answer-derived static React Bootstrap breakpoint under one prompt,
+budget, public context, starter, and acceptance digest. Baseline exposed plain
+`build`; tool-assisted exposed structured `build`, `inspect`, and `explain`.
+Both conditions passed 5/5 with the same 234 raw / 181 gzip B HTML artifact,
+98.94% byte-identical source retention, and zero browser JavaScript.
+
+Baseline total-token samples were `[75485, 75459, 66141, 60644, 61570]`: a
+66,141 median, 60,644/75,485 range, and 67,860 failure-inclusive tokens per
+success. Tool-assisted samples were `[75983, 87615, 108588, 75828, 75950]`: a
+75,983 median, 75,828/108,588 range, and 84,793 tokens per success. Structured
+tools therefore cost 16,933 more tokens per success on this task. Monetary cost
+was reported as zero by the subscription provider in every attempt.
+
+Baseline versus tool-assisted medians and ranges were: file reads 2 (1/3)
+versus 2 (1/3), tool calls 8 (5/9) versus 9 (8/12), builds 2 (2/2) versus 2
+(2/3), correction cycles 1 (1/1) versus 1 (1/2), and completion time 45,811 ms
+(43,194/46,390) versus 60,736 ms (52,313/76,963). There were no failed
+attempts. This rejects an AI cost-reduction claim for the structured tool bundle
+on this task; it does not remove the independently useful machine-readable
+commands or claim results for other tasks.
+
 ## 0.16.14 Fair AI Delivery Evidence
 
 Measured 2026-09-01 on Linux x64 with Node 24.14.0. The deterministic protocol

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.14 - Fair AI delivery evidence.** The repository-owned AI delivery runner now pins equal Kudzu and React+Vite conditions, preserves successful and failed attempts, and records attribution, cost, source retention, acceptance, and browser artifacts without claiming a framework winner. Read the [release notes](./RELEASES.md#01614---fair-ai-delivery-evidence), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.16.14), 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,73 @@
 # 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
+into maintained executable evidence instead of release-time assumptions.
+
+### Changed in 0.16.15
+
+- Adds opt-in internal source-read, graph, TypeScript parse, normalization,
+  compile/transform, render, and write timing to the existing project session.
+- Extends `npm run benchmark:source-scale` with retained-session incremental
+  timing and RSS, clean changed-source equivalence, output digests, and clean
+  and retained-session failure recovery.
+- Records repeated 100-route / 1,000-module and 1,000-route / 10,000-module
+  measurements. Every incremental sample recompiles 10 modules and renders one
+  page while matching a clean changed-source build byte-for-byte.
+- Keeps the full 10,000-route / 100,000-module run explicitly pending a
+  separately provisioned host; no projection or reduced fixture is called a
+  pass.
+- Promotes the 10,000-item pagination decision to ordinary Chrome acceptance,
+  including Enter navigation, focus retention, bounded 100-row DOM, state
+  release, and a zero-JavaScript direct-list control.
+- Marks missing AI attribution traces incomplete and withholds token and cost
+  per-success claims instead of treating missing data as zero.
+- Records the equal-condition OpenCode tooling trial: both conditions passed
+  5/5, while structured tools used 16,933 more tokens per success, so no AI cost
+  reduction is claimed.
+- Adds no semantic primitive, compiler pass, runtime concept, application API,
+  dependency, deploy artifact, or browser byte.
+- Passes `npm run check`, required-Chrome 300/300, package smoke, tarball
+  inspection, and both npm publish dry-runs on the exact versioned tree.
+- Updates `create-kudzu@0.1.140` to generate projects on
+  `@kudzujs/core@^0.16.15`.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.16.15
+```
+
 ## 0.16.14 - Fair AI Delivery Evidence
 
 Kudzu 0.16.14 adds a repository-owned protocol and runner for equal-condition,

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.20.5`. 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

@@ -1931,6 +1931,19 @@ required-Chrome suites pass 297/297 tests, and package smoke passes.
 - **Done condition:** useful tools are retained and non-improving tools are
   removed or deferred.
 
+Measured on 2026-09-01 with five interleaved attempts per condition against one
+Apache Answer-derived static Bootstrap correction. Both conditions passed 5/5
+with identical accepted behavior, source retention, and browser artifacts, but
+plain-build baseline cost 67,860 tokens per success while structured
+build/inspect/explain cost 84,793. The structured bundle is therefore deferred
+as an AI default rather than credited with a cost reduction. Existing JSON,
+inspection, and explanation commands remain for their independently accepted
+machine-readable contracts; no speculative `fix` command, compiler pass,
+runtime concept, application API, dependency, or browser byte was added. Exact
+samples, medians, and ranges are recorded in `PERFORMANCE.md`, while the pinned
+protocol reproduces and retains raw attempt evidence under the ignored
+`test-results/ai-delivery/` path.
+
 ## `0.21.x`: Production-Scale Proof
 
 ### `0.21.0`: Functional Parity Matrix
@@ -1942,6 +1955,28 @@ required-Chrome suites pass 297/297 tests, and package smoke passes.
 - **Done condition:** every claimed capability has a browser journey and static
   exclusion control.
 
+**Result:** closed through existing application semantics without a release.
+The required-Chrome 300-test matrix passes content, authentication, forms, CRUD,
+shared data, large lists, overlays, editor ownership, lazy loading, realtime,
+errors, accessibility, and navigation across the maintained greenfield, Apache
+Answer, Memos, and focused package fixtures. The one material matrix gap was the
+10,000-item pagination decision: its release/remount behavior existed only in an
+optional benchmark. One ordinary browser acceptance now proves Enter-key page
+advance, focus retention, the 101-200 and restored 1-100 ranges, bounded 100-row
+DOM, fresh off-range input state, and no browser exceptions. Greenfield `/help`,
+Answer and Memos `/public`, package `/static` routes, and the complete direct
+10,000-row route provide zero-JavaScript controls.
+
+The artifact inventory now includes the large-list fixture: 19 files,
+1,900,048 raw / 242,968 aggregate gzip bytes, deploy SHA-256
+`1bbaf3479ac90f923deb469c73eb93c0dd7364e7fe906919b167f2f854deda70`.
+Pagination owns 30,143 raw / 11,193 gzip bytes of existing JavaScript while the
+direct static route owns zero. Semantic primitives, IR kinds, compiler passes,
+production compiler/runtime LOC, normalization rules, adapters, runtime
+concepts, public APIs, and browser artifacts change by zero. `npm run check`,
+required-Chrome 300/300, package smoke, focused acceptance, and artifact
+inventory pass. No production feature changed, so no release is consumed.
+
 ### `0.21.1`: Compiler And Route Scale
 
 - **Purpose:** measure clean/incremental compilation and artifact emission.
@@ -1952,6 +1987,44 @@ required-Chrome suites pass 297/297 tests, and package smoke passes.
 - **Done condition:** repeated measurements and all material regressions are
   explained or fixed.
 
+**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
+esbuild parse/transform for proven import-free modules. Render includes
+provisional page materialization, write includes finalization and staged-output
+promotion, and the end-to-end clean build is not their sum. The runner also proves that an
+incremental source edit matches a clean build of the changed source, compares
+paired incremental outputs when a baseline is supplied, names retained-session
+rather than incremental-only peak RSS, and fails the process when either clean
+or retained-session invalid-source recovery changes output. This adds no
+semantic primitive, compiler pass, runtime concept, public API, deploy artifact,
+or browser byte; production compiler/build instrumentation is 35 added and four
+removed lines.
+
+One warm-up and three fresh-process samples pass at 100 routes / 1,000 modules /
+101,100 lines and 1,000 routes / 10,000 modules / 1,011,000 lines. Clean-build
+medians are 7,444.3 and 77,515.9 ms with 672.3 and 3,182.3 MiB peak RSS;
+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 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
 
 - **Purpose:** protect interaction latency and long-running stability.
@@ -2122,3 +2195,6 @@ release transaction where possible or document and publish a forward-fix patch.
 | `0.20.2` | Released as `0.16.13` | Preserve exact emitted-route lookup, authored provenance, semantic ownership, capability/artifact byte reasons and hashes, bounded deterministic output, structured missing-route diagnostics, and zero-JavaScript explanation. | Patch release retained the `0.16.x` public version line |
 | `0.20.3` | Deferred by evidence gate | Resume only after recorded AI trials prove one repeated correction safe and useful with a stable diagnostic code and compiler-proven preconditions. | No recorded AI trials; no production change or release consumed |
 | `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` | 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.14` 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.20.5`; 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.20.5`. 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.20.5`; 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.20.5` tooling cost validation 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.20.5`; 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.139` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.16.14`.
+`create-kudzu@0.1.141` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.16.16`.
 
 ## Release Boundary
 

package/framework/build.mjs

@@ -60,7 +60,9 @@ export async function buildWithSession(project, { changedFiles, quiet = false, m
     await recoverOutput(outputDirectory, backupOutput)
     await rm(stagedOutput, { recursive: true, force: true })
     const { result, pageCount, behaviorCount, cache, inspectionData, explanation } = await buildInto(project, stagedOutput, { changedFiles, minify, quiet, retainCache, explanationRoute })
+    const promoteStarted = project.timings ? performance.now() : 0
     await promoteOutput(stagedOutput, outputDirectory, backupOutput)
+    addTiming(project.timings, "writeMs", promoteStarted)
     project.buildCache = retainCache ? cache : undefined
     if (!quiet) console.log(`Built ${pageCount} page(s), ${behaviorCount} interactive page(s) into dist/`)
     return explanationRoute ? explanation : inspection ? createInspectionReport(inspectionData) : result
@@ -110,6 +112,7 @@ async function buildInto(project, outputDirectory, { changedFiles, minify, quiet
   await mkdir(workDirectory, { recursive: true })
   await mkdir(outputDirectory, { recursive: true })
 
+  const sourceReadStarted = project.timings ? performance.now() : 0
   const projectFiles = await walk(sourceDirectory)
   const allSourceFiles = projectFiles.filter(file => /\.(?:ts|tsx)$/.test(file) && !file.endsWith(".d.ts")).sort()
   const configuredStyleSources = new Set(configuredStyles.sources.map(style => style.source))
@@ -118,10 +121,13 @@ async function buildInto(project, outputDirectory, { changedFiles, minify, quiet
   const sourceIndex = project.sourceIndex
   for (const file of sourceIndex.keys()) if (file.startsWith(`${sourceDirectory}${sep}`) && !allSourceFileSet.has(file)) sourceIndex.delete(file)
   for (const [file, source] of await Promise.all(allSourceFiles.map(async file => [file, await readFile(file, "utf8")]))) sourceIndex.set(file, source)
+  addTiming(project.timings, "sourceReadMs", sourceReadStarted)
   const pageFiles = allSourceFiles.filter(file => file.startsWith(`${pagesDirectory}${sep}`) && file.endsWith(".tsx"))
   if (!pageFiles.length) throw new Error("No pages found in src/pages/")
+  const graphStarted = project.timings ? performance.now() : 0
   const pageSources = new Map(pageFiles.map(file => [file, new Set(reachableSourceFiles([file], allSourceFileSet, sourceIndex))]))
   const sourceFiles = [...new Set([...pageSources.values()].flatMap(files => [...files]))].sort()
+  addTiming(project.timings, "graphMs", graphStarted)
   const compatibility = createCompatibilityReport(sourceFiles.map(file => ({ file: relative(root, file).replaceAll(sep, "/"), source: sourceIndex.get(file) })))
   await writePrettyJson(join(workDirectory, "kudzu-compatibility.json"), compatibility)
   const sourceFileSet = project.sourceFiles
@@ -193,6 +199,7 @@ async function buildInto(project, outputDirectory, { changedFiles, minify, quiet
   const routePageFiles = new Map()
   let renderedPages = 0
 
+  const renderStarted = project.timings ? performance.now() : 0
   for (const pageFile of pageFiles) {
     const cached = !affectedPages.has(pageFile) ? previous?.pageRenders.get(pageFile) : undefined
     if (cached) {
@@ -328,7 +335,9 @@ async function buildInto(project, outputDirectory, { changedFiles, minify, quiet
       rewrites: rewrites.slice(rewriteOffset)
     })
   }
+  addTiming(project.timings, "renderMs", renderStarted)
 
+  const writeStarted = project.timings ? performance.now() : 0
   for (const group of navigationGroups) for (const route of group.routes) if (!emittedApplicationRoutes.has(route)) throw new Error(`${group.label} route ${JSON.stringify(route)} is not an emitted route`)
   rejectNavigationOverlap(navigationGroups)
   for (const group of navigationGroups) {
@@ -541,6 +550,7 @@ async function buildInto(project, outputDirectory, { changedFiles, minify, quiet
     if (typeof config.afterBuild !== "function") throw new Error("kudzu.config afterBuild must be a function")
     await config.afterBuild({ root, outDir: outputDirectory, sourceDir: sourceDirectory, base, routes: plans.map(plan => plan.route), plans, rewrites: sortedRewrites, artifacts })
   }
+  addTiming(project.timings, "writeMs", writeStarted)
 
   let explanation
   if (explanationRoute) {
@@ -563,6 +573,10 @@ async function buildInto(project, outputDirectory, { changedFiles, minify, quiet
   }
 }
 
+function addTiming(timings, name, started) {
+  if (timings) timings[name] = (timings[name] ?? 0) + performance.now() - started
+}
+
 function affectedPageFiles({ changedFiles, pageFiles, pageSources, previous, sourceDirectory }) {
   if (!previous || changedFiles === undefined) return new Set(pageFiles)
   if (changedFiles.some(file => typeof file !== "string")) return new Set(pageFiles)

package/framework/compiler/project-session.mjs

@@ -5,13 +5,15 @@ import { assetPath } from "./path-helpers.mjs"
 import { createSourceGraph } from "./source-graph.mjs"
 import { createWorkerCompiler } from "./worker-compiler.mjs"
 
-export function createProjectSession(projectRoot = process.cwd(), { counters, sourceIndex = new Map() } = {}) {
+export function createProjectSession(projectRoot = process.cwd(), { counters, sourceIndex = new Map(), timings } = {}) {
   const root = resolve(projectRoot)
   const sourceDirectory = join(root, "src")
   const graph = createSourceGraph(root)
-  const modules = createModuleCache(root, sourceIndex, graph, counters)
+  if (timings && !ts.performance.isEnabled()) ts.performance.enable()
+  const modules = createModuleCache(root, sourceIndex, graph, counters, timings)
   return {
     counters,
+    timings,
     root,
     sourceDirectory,
     pagesDirectory: join(sourceDirectory, "pages"),
@@ -25,7 +27,8 @@ export function createProjectSession(projectRoot = process.cwd(), { counters, so
   }
 }
 
-function createModuleCache(root, sourceIndex, graph, counters) {
+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, "/")
@@ -44,13 +47,21 @@ function createModuleCache(root, sourceIndex, graph, counters) {
   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
     increment("parsedModules")
     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/framework/compiler/source-compiler.mjs

@@ -28,7 +28,7 @@ import { ownedLazyPackageImport } from "./source-graph.mjs"
 import { createZustandPass } from "./zustand-pass.mjs"
 
 export function createSourceCompiler(project) {
-const { root, sourceDirectory, pagesDirectory, workDirectory, workerCompiler, modules, counters } = project
+const { root, sourceDirectory, pagesDirectory, workDirectory, workerCompiler, modules, counters, timings } = project
 const buildDirectory = project.buildDirectory ?? workDirectory
 const { ordinaryRuntimeDependencies, resolveSourceImport, runtimeModuleReference } = project.graph
 const parseSourceFile = (file, source) => modules.read(file, source).sourceFile
@@ -42,6 +42,13 @@ async function compileSourceAsync(file, sourceFiles, sourceIndex, staticFiles, c
 }
 
 function compileSource(file, sourceFiles, sourceIndex, staticFiles, cssModules, base, importFreeOutput) {
+  const parseBefore = timings?.parseMs ?? 0
+  const typeScriptParseBefore = timings ? ts.performance.getDuration("Parse") : 0
+  const finishTiming = () => {
+    if (!timings) return
+    const recordedParse = (timings.parseMs ?? 0) - parseBefore
+    timings.parseMs = (timings.parseMs ?? 0) + Math.max(0, ts.performance.getDuration("Parse") - typeScriptParseBefore - recordedParse)
+  }
   const importedAssets = new Set()
   const source = sourceIndex.get(file)
   const semantic = createSemanticArtifact(relative(root, file).replaceAll(sep, "/"))
@@ -74,6 +81,7 @@ function compileSource(file, sourceFiles, sourceIndex, staticFiles, cssModules,
   const moduleHandlers = moduleIR.handlers.filter(handler => handler.kind === "module-export")
   if (!moduleHandlers.length && !moduleIR.bindings.length) {
     normalizeModulePaths(moduleIR)
+    finishTiming()
     return sourceResult
   }
   const moduleSource = printHandlerModule({ moduleIR, handlerPath })
@@ -85,6 +93,7 @@ function compileSource(file, sourceFiles, sourceIndex, staticFiles, cssModules,
   if (moduleErrors.length) throw new Error(moduleErrors.map(error => ts.flattenDiagnosticMessageText(error.messageText, "\n")).join("\n"))
   normalizeModulePaths(moduleIR)
   sourceResult.handlerModule = { path: handlerPath, code: moduleResult.outputText, hasNativeHandlers: moduleHandlers.some(handler => handler.role === "native"), hasEffects: moduleHandlers.some(handler => handler.role === "effect"), clientImports: moduleIR.clientModules, hasPackageImports: moduleIR.imports.some(entry => entry.package) }
+  finishTiming()
   return sourceResult
 }
 
@@ -358,7 +367,9 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     const importedStaticCollections = importedSerializableCollections(sourceFile, file, sourceFiles, sourceIndex, true)
     const importedCollections = new Set(importedStaticCollections.keys())
     const importedFallbackCollections = importedSerializableCollections(sourceFile, file, sourceFiles, sourceIndex)
+    const normalizeStarted = timings ? performance.now() : 0
     const normalized = normalizeCompilerSource(sourceFile, { base, context, file, importedCollections, importedFallbackCollections, importedStaticCollections, sourceFiles, sourceIndex })
+    if (timings) timings.normalizeMs = (timings.normalizeMs ?? 0) + performance.now() - normalizeStarted
     sourceFile = normalized.sourceFile
     const { customHookTimerStates } = normalized
     const bindingIndex = createBindingIndex(sourceFile)
@@ -417,7 +428,9 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     const importedSource = target => {
       let result = importedSourceCache.get(target)
       if (!result) {
+        const normalizeStarted = timings ? performance.now() : 0
         result = normalizeCompilerSource(modules.clone(target, context.factory, context), { base, context, file: target, sourceFiles, sourceIndex })
+        if (timings) timings.normalizeMs = (timings.normalizeMs ?? 0) + performance.now() - normalizeStarted
         importedSourceCache.set(target, result)
       }
       return result.sourceFile

package/package.json

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