@kudzujs/core 0.16.12 → 0.16.14

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.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.
+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.
 
 ### 0.10.0 Through 0.21.x: Application Capability Release Train
 

package/PERFORMANCE.md

@@ -1,6 +1,33 @@
 # Performance Records
 
-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`, and `npm run benchmark:source-scale` 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.
+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.16.14 Fair AI Delivery Evidence
+
+Measured 2026-09-01 on Linux x64 with Node 24.14.0. The deterministic protocol
+fixture records two interleaved attempts per variant, including one success and
+one retained failure each. Both variants therefore report a 50% fixture success
+rate, 50 nanos median successful cost, and 100 nanos total cost per success when
+failed attempts remain in the numerator. Successful artifacts are one 63 raw /
+66 gzip B HTML file with digest
+`0d22f579d793d0034c967c7ffa08e0b2c377bc36c959c7b4bafab587fd5dda60`.
+This validates evidence accounting only and is not a model-driven framework
+comparison. Compiler passes, runtime concepts, representative deploy output, and
+browser bytes are unchanged. Browser-disabled and required-Chrome suites pass
+297/297 tests, package smoke passes, and the runner adds no dependency.
+
+## 0.16.13 Route Artifact Explanations
+
+Measured 2026-09-01 on Linux x64 with Node 24.14.0. Route explanation is a
+build-time projection over existing route, source, compatibility, ownership,
+capability, and artifact records. Representative deploy manifests and hashes
+remain unchanged. The maintained Worker graph remains 907 raw / 477 gzip B and
+the window graph remains 14,456 raw / 6,160 gzip B. Seven clean builds record a
+605 ms median on this host without a timing comparison. Browser-disabled and
+required-Chrome suites pass 296/296 tests, package smoke passes, and focused CLI
+coverage includes an effect-owned Worker route, configured base, exact missing
+route diagnostic, deterministic output, artifact hashes, and zero-JavaScript
+static exclusion.
 
 ## 0.16.12 Bounded Application Inspection
 

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.12 - Bounded application inspection.** `kudzu inspect --json` now projects reachable modules, routes, packages, capabilities, semantic owners, and first blockers from the existing build graph in deterministic bounded output without dumping raw IR. Read the [release notes](./RELEASES.md#01612---bounded-application-inspection), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.16.12), or follow the [architecture packet](./docs/next-architecture/README.md).
+**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).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)

package/RELEASES.md

@@ -1,5 +1,66 @@
 # Kudzu Releases
 
+## 0.16.14 - Fair AI Delivery Evidence
+
+Kudzu 0.16.14 adds a repository-owned protocol and runner for equal-condition,
+fully retained Kudzu and React+Vite delivery attempts.
+
+### Changed in 0.16.14
+
+- Adds `npm run benchmark:ai-delivery`, backed only by Node standard-library
+  process, hash, filesystem, timing, and compression APIs.
+- Pins model revision, pricing, tool permissions, prompt, budgets, adapter,
+  acceptance command, starter trees, public context, and paired attempt order.
+- Runs every attempt in an isolated starter copy, then independently reruns the
+  declared build and framework-neutral acceptance command.
+- Preserves raw adapter/build/acceptance output, final authored source, browser
+  artifacts, hashes, token/cost/tool/file/build metrics, and source retention.
+- Includes deliberate failures in the evidence and total cost-per-success
+  numerator rather than cherry-picking successful attempts.
+- Adds no compiler pass, semantic primitive, runtime concept, application API,
+  dependency, or browser byte.
+- Uses a deterministic fixture only to validate the protocol. It does not claim
+  that Kudzu outperforms React+Vite; measured tooling-cost validation remains the
+  next packet.
+- Updates `create-kudzu@0.1.139` to generate projects on
+  `@kudzujs/core@^0.16.14`.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.16.14
+```
+
+## 0.16.13 - Route Artifact Explanations
+
+Kudzu 0.16.13 lets tools ask why one exact emitted route owns its browser bytes
+without reading raw semantic records or reconstructing an artifact graph.
+
+### Changed in 0.16.13
+
+- Adds `kudzu explain --route <route> --json`, which runs the authoritative build
+  and projects authored source, normalization provenance, semantic owners,
+  capability facts, selected artifacts, and byte reasons for one emitted route.
+- Reports raw and gzip byte totals plus SHA-256 hashes for runtime, handler,
+  transitive chunk, stylesheet, and Worker artifacts already selected by the
+  existing route artifact report.
+- Explains zero-JavaScript routes from an absent behavior runtime family and an
+  empty compiler-selected JavaScript closure.
+- Uses exact configured-base route matching and returns the structured
+  `explain.route.not-found` diagnostic for missing routes.
+- Sorts every bounded section before truncation and excludes HTML, generated
+  code, RouteIR, ModuleIR, captures, and state values.
+- Adds no analyzer, semantic primitive, compiler pass, runtime concept, public
+  application API, or browser byte.
+- Updates `create-kudzu@0.1.138` to generate projects on
+  `@kudzujs/core@^0.16.13`.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.16.13
+```
+
 ## 0.16.12 - Bounded Application Inspection
 
 Kudzu 0.16.12 lets tools select the first migration blocker from a compact

package/bin/kudzu.mjs

@@ -6,27 +6,34 @@ import { fileURLToPath } from "node:url"
 
 const command = process.argv[2] ?? "dev"
 
-if ((command === "build" || command === "inspect") && !process.env.KUDZU_BUILD_CHILD) {
+if ((command === "build" || command === "inspect" || command === "explain") && !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" || command === "inspect") {
+} else if (command === "build" || command === "dev" || command === "inspect" || command === "explain") {
   module.enableCompileCache?.()
-  const { build, dev, inspect } = await import("../framework/build.mjs")
-  const json = command === "build" && process.argv.includes("--json")
+  const { build, dev, explain, inspect } = await import("../framework/build.mjs")
+  const json = (command === "build" || command === "explain") && process.argv.includes("--json")
   try {
-    if (command === "inspect") {
+    if (command === "inspect" || command === "explain") {
+      const args = process.argv.slice(3)
+      const routeIndex = args.indexOf("--route")
+      const route = routeIndex === -1 ? undefined : args[routeIndex + 1]
+      const validExplain = command !== "explain" || args.length === 3 && args.filter(arg => arg === "--json").length === 1 && args.filter(arg => arg === "--route").length === 1 && route && !route.startsWith("--") && args.every((arg, index) => arg === "--json" || arg === "--route" || index === routeIndex + 1)
       if (!process.argv.includes("--json")) {
-        console.error("Use: kudzu inspect --json")
+        console.error(command === "inspect" ? "Use: kudzu inspect --json" : "Use: kudzu explain --route <route> --json")
+        process.exitCode = 1
+      } else if (!validExplain) {
+        console.error("Use: kudzu explain --route <route> --json")
         process.exitCode = 1
       } else {
         const log = console.log
         console.log = console.error
         try {
-          process.stdout.write(`${JSON.stringify(await inspect())}\n`)
+          process.stdout.write(`${JSON.stringify(await (command === "inspect" ? inspect() : explain({ route })))}\n`)
         } finally {
           console.log = log
         }
@@ -40,6 +47,6 @@ if ((command === "build" || command === "inspect") && !process.env.KUDZU_BUILD_C
     process.exitCode = 1
   }
 } else {
-  console.error(`Unknown command: ${command}\nUse: kudzu <build|dev|inspect>`)
+  console.error(`Unknown command: ${command}\nUse: kudzu <build|dev|inspect|explain>`)
   process.exitCode = 1
 }

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.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.
+[`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.
 
 ## Required Invariants
 

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

@@ -1856,6 +1856,23 @@ ships as `@kudzujs/core@0.16.12` with `create-kudzu@0.1.137`.
 - **Done condition:** existing route records and artifact reports answer the
   query with bounded output.
 
+Completed by `@kudzujs/core@0.16.13` and `create-kudzu@0.1.138`. The
+`worker-effects` fixture proves exact configured-base lookup for an effect-owned
+Worker route, authored source closure, `Dashboard` ownership, capability family,
+runtime/handler/Worker byte reasons, raw/gzip totals, hashes, deterministic
+output, structured missing-route diagnostics, and a static sibling with an empty
+JavaScript closure. The implementation is one 137-line bounded projection over
+existing source results, compatibility sites, route records, and the sole route
+artifact report plus the existing build/CLI seam. It adds no analyzer, semantic
+primitive, compiler pass, normalization entry, runtime concept, or browser
+module. Representative deploy manifests and hashes remain unchanged. Worker and
+window graphs remain 907 raw / 477 gzip and 14,456 raw / 6,160 gzip bytes; seven
+clean builds record a 605 ms median without a timing comparison. Browser-disabled
+and required-Chrome suites pass 296/296 tests, and package smoke and artifact
+accounting pass. Fixed 100-record section limits expose totals and omitted counts;
+the command requires one exact emitted route and intentionally excludes raw IR,
+HTML, generated code, captures, and state values.
+
 ### `0.20.3`: Deterministic Normalize And Fix
 
 - **Purpose:** automate only edits proven safe and useful by recorded AI trials.
@@ -1864,6 +1881,21 @@ ships as `@kudzujs/core@0.16.12` with `create-kudzu@0.1.137`.
 - **Stop condition:** canonical compiler source replaces ordinary authored TSX.
 - **Done condition:** each fix has one diagnostic code and explicit preconditions.
 
+Deferred by the evidence gate without production changes or a release. A complete
+repository inventory found no recorded model prompt, model/tool version, raw
+attempt, correction cycle, token/cost trace, or repeated source edit proving any
+automatic fix useful. Existing diagnostics offer migration guidance but do not
+identify a uniquely safe edit; replacing a non-null ref initializer would change
+authored behavior. The existing lazy-state-literal normalization could support a
+narrow exact-range rewrite while preserving comments and output bytes, but no AI
+trial records it as a correction or cost reduction. Adding check/preview/write
+infrastructure now would therefore be speculative and violate the packet purpose.
+Resume this packet only after `0.20.4` records a repeated correction with one
+stable diagnostic code, a unique semantics-preserving replacement, and
+compiler-proven preconditions. No fixture, analyzer, fix command, formatter,
+compiler pass, runtime concept, browser module, package version, or release was
+added.
+
 ### `0.20.4`: AI Delivery Protocol And Runner
 
 - **Purpose:** track fair Kudzu and React+Vite delivery attempts.
@@ -1874,6 +1906,20 @@ ships as `@kudzujs/core@0.16.12` with `create-kudzu@0.1.137`.
   comparator.
 - **Done condition:** every attempt is reproducible or fully attributable.
 
+Completed by `@kudzujs/core@0.16.14` and `create-kudzu@0.1.139`. The
+repository-owned Node standard-library runner pins the model revision, pricing,
+tools, prompt, budgets, adapter, acceptance command, starter digests, optional
+public context, and paired schedule before creating isolated workspaces. It
+retains raw adapter/build/acceptance streams, final source, browser artifacts,
+hashes, attribution, token/cost/tool/file/build metrics, source retention, and
+both successful and failed attempts. The deterministic two-attempt-per-variant
+fixture proves equal ordering, one retained failure per variant, independent
+final builds, framework-neutral acceptance, and failure-inclusive cost per
+success. It is protocol evidence only and makes no Kudzu versus React+Vite
+delivery claim. No dependency, compiler pass, semantic primitive, runtime
+concept, application API, or browser byte was added. Browser-disabled and
+required-Chrome suites pass 297/297 tests, and package smoke passes.
+
 ### `0.20.5`: Tooling Cost Validation
 
 - **Purpose:** prove that diagnostics/inspect/explain/fix lower total cost per
@@ -2073,3 +2119,6 @@ release transaction where possible or document and publish a forward-fix patch.
 | `0.19.5` | Deferred by stop condition | Resume only from a complete pinned Actual Budget workspace with an executable dependency graph and honest retention denominator. | Sparse acquisition omits required workspace and core packages; no compatibility claim |
 | `0.20.0` | Released as `0.16.11` | Preserve stable diagnostic schema/codes, authored ranges, human errors, compatibility reuse, and zero browser/output delta. | Patch release retained the `0.16.x` public version line |
 | `0.20.1` | Released as `0.16.12` | Preserve bounded deterministic reachable inventory, first-blocker retention, existing-record reuse, and zero browser/output delta. | Patch release retained the `0.16.x` public version line |
+| `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 |

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

@@ -1,12 +1,12 @@
 # Current Compiler Architecture
 
-This maps the current `0.16.12` 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.2`; 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.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.
 
 ## Responsibility Map
 
 | Responsibility | Current owner | Current contract |
 |---|---|---|
-| CLI entry | [`bin/kudzu.mjs`](../../bin/kudzu.mjs) | Dispatches build and development commands. |
+| CLI entry | [`bin/kudzu.mjs`](../../bin/kudzu.mjs) | Dispatches build, development, inspection, and exact-route explanation commands. |
 | Project session | [`framework/compiler/project-session.mjs`](../../framework/compiler/project-session.mjs), `createProjectSession()` | Owns one absolute root, standard project paths, source records, bound graph operations, and Worker compiler. Production builds use one session; development retains it across rebuilds. Omitted roots resolve from call-time CWD. |
 | Parsed module cache and symbols | [`framework/compiler/project-session.mjs`](../../framework/compiler/project-session.mjs) | Parses each unchanged source module once per ProjectSession and records source-local declaration/import/re-export sites. Stable ModuleSymbol records resolve direct, aliased, barrel, and `export *` exports with cycle and ambiguity checks; repeated resolutions are cached against their source dependencies, and normalization consumers locate the resolved SiteId in a fresh clone with independent parent links. |
 | Build orchestration | [`framework/build.mjs`](../../framework/build.mjs), `build()`, `buildWithSession()` | Coordinates config, discovery, source compilation, RouteBuildRecord collection, CapabilityIR projection, generator invocation, artifact emission, and `afterBuild`. A retained session caches source results and pre-family route renders by page graph; successful builds alone replace that cache. |
@@ -22,6 +22,7 @@ This maps the current `0.16.12` architecture, built on the completed `0.9.0` sem
 | Component ownership analysis | [`framework/compiler/analysis/component-analysis.mjs`](../../framework/compiler/analysis/component-analysis.mjs) | Produces ComponentAnalysis v2 with ordered JSON-safe owner and specialization slots for state, setters, props, refs, IDs, direct SignalIR links, direct static property/consumer links, structural OwnerRefs, source-local SiteIds, and source provenance. Three direct callback/ref component boundaries specialize into the same parent signal and intrinsic ownership; Context action-private setters may remain compiler-only and receive collision-free consumer-local aliases; AST identity remains private to its source-local session. |
 | Per-source descriptor registration | [`framework/compiler/descriptor-session.mjs`](../../framework/compiler/descriptor-session.mjs), `createSemanticArtifact()`, `createDescriptorSession()` | Keeps AST descriptors private during analysis, then finalizes ModuleIR v2 with deterministic SymbolRef, SharedStateIR, SharedActionIR, SignalIR, HandlerIR, BindingIR, DerivedIR, EffectIR, KeyedBlockIR, and ImportIR slots. One fail-closed boundary validates every source-local and component ownership edge before build-module generation. |
 | Route artifact graph | [`framework/compiler/route-build-record.mjs`](../../framework/compiler/route-build-record.mjs), `createRouteBuildRecord()`, `planRouteArtifacts()`; [`framework/compiler/route-artifact-report.mjs`](../../framework/compiler/route-artifact-report.mjs), `createRouteArtifactReport()` | Validates each rendered route's RouteIR, capabilities, entry paths, styles, and exact handler/effect references. Handler and Worker esbuild metafiles project transitive output edges back through those records into deterministic per-route capability signatures and runtime requirements plus emitted handler, Worker, stylesheet, and shared-chunk closure. |
+| Tool projections | [`framework/compiler/inspection-report.mjs`](../../framework/compiler/inspection-report.mjs), `createInspectionReport()`; [`framework/compiler/explanation-report.mjs`](../../framework/compiler/explanation-report.mjs), `createExplanationReport()` | Projects bounded deterministic reachable-application inventory and one exact route's authored provenance, ownership, capability, artifact byte reasons, hashes, and zero-JavaScript explanation from existing build records. Raw semantic IR, generated code, HTML, captures, and state values remain private. |
 | Route contract validation | [`framework/compiler/route-ir.mjs`](../../framework/compiler/route-ir.mjs), `assertRouteIR()` | Fails before artifact selection for invalid state/parameter identity, commands, native/effect captures and dependencies, reactive descriptors, conditions, keyed-list identity/ownership, marker fields, or JSON safety. Immutable in-memory contracts validate once by identity. |
 | Command IR and codegen | [`framework/compiler/optimize/command-specialization.mjs`](../../framework/compiler/optimize/command-specialization.mjs), [`framework/compiler/ir/module-ir.mjs`](../../framework/compiler/ir/module-ir.mjs), [`framework/compiler/codegen/command-codegen.mjs`](../../framework/compiler/codegen/command-codegen.mjs) | Direct commands use the existing fast path; proven immutable state aliases and one-call local helpers specialize to the same JSON-safe command ModuleIR. Recursion, escape, mutation, and dynamic helper dispatch fail explicitly, while unrelated handlers retain native ESM. Codegen emits the existing `__kBehavior` AST and command ABI. |
 | Source compilation | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `compileSource()` | Runs TypeScript with the Kudzu transformer, rejects surviving React/Router references, and returns a JSON-safe project-relative build module, component analysis, ModuleIR, optional handler module, and imported assets without filesystem writes. |

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.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.
+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.
 
-[`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.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.
+[`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.
 
 ## 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.2` `kudzu explain --route` 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.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.

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.2`; 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.20.5`; 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.137` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.16.12`.
+`create-kudzu@0.1.139` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.16.14`.
 
 ## Release Boundary
 

package/framework/build.mjs

@@ -5,7 +5,8 @@ import { pathToFileURL } from "node:url"
 import { build as bundle, transform } from "esbuild"
 import { createEffectCodegen } from "./compiler/effect-codegen.mjs"
 import { createCompatibilityReport } from "./compiler/compatibility-registry.mjs"
-import { diagnosticEnvelope, normalizeDiagnosticError } from "./compiler/diagnostics.mjs"
+import { createDiagnosticError, diagnosticEnvelope, normalizeDiagnosticError } from "./compiler/diagnostics.mjs"
+import { createExplanationReport } from "./compiler/explanation-report.mjs"
 import { createInspectionReport } from "./compiler/inspection-report.mjs"
 import { generateListRuntime } from "./compiler/list-runtime-codegen.mjs"
 import { assetPath, browserPath, relativeModulePath, withBase } from "./compiler/path-helpers.mjs"
@@ -44,7 +45,12 @@ export async function inspect({ minify = true, root: projectRoot = process.cwd()
   return buildWithSession(project, { quiet: true, minify, retainCache: false, inspection: true })
 }
 
-export async function buildWithSession(project, { changedFiles, quiet = false, minify = true, retainCache = true, inspection = false } = {}) {
+export async function explain({ route, minify = true, root: projectRoot = process.cwd() } = {}) {
+  const project = createProjectSession(projectRoot)
+  return buildWithSession(project, { quiet: true, minify, retainCache: false, explanationRoute: route })
+}
+
+export async function buildWithSession(project, { changedFiles, quiet = false, minify = true, retainCache = true, inspection = false, explanationRoute } = {}) {
   const { root, outputDirectory } = project
   const stagedOutput = join(root, ".kudzu-dist-staging")
   const backupOutput = join(root, ".kudzu-dist-backup")
@@ -53,11 +59,11 @@ export async function buildWithSession(project, { changedFiles, quiet = false, m
   try {
     await recoverOutput(outputDirectory, backupOutput)
     await rm(stagedOutput, { recursive: true, force: true })
-    const { result, pageCount, behaviorCount, cache, inspectionData } = await buildInto(project, stagedOutput, { changedFiles, minify, quiet, retainCache })
+    const { result, pageCount, behaviorCount, cache, inspectionData, explanation } = await buildInto(project, stagedOutput, { changedFiles, minify, quiet, retainCache, explanationRoute })
     await promoteOutput(stagedOutput, outputDirectory, backupOutput)
     project.buildCache = retainCache ? cache : undefined
     if (!quiet) console.log(`Built ${pageCount} page(s), ${behaviorCount} interactive page(s) into dist/`)
-    return inspection ? createInspectionReport(inspectionData) : result
+    return explanationRoute ? explanation : inspection ? createInspectionReport(inspectionData) : result
   } catch (error) {
     const normalized = normalizeDiagnosticError(error, root)
     const envelope = inspection && diagnosticEnvelope(normalized)
@@ -76,7 +82,7 @@ export async function buildWithSession(project, { changedFiles, quiet = false, m
   }
 }
 
-async function buildInto(project, outputDirectory, { changedFiles, minify, quiet, retainCache }) {
+async function buildInto(project, outputDirectory, { changedFiles, minify, quiet, retainCache, explanationRoute }) {
   const { root, sourceDirectory, pagesDirectory, workDirectory } = project
   const previous = retainCache ? project.buildCache : undefined
   project.buildGeneration = (project.buildGeneration ?? 0) + 1
@@ -184,6 +190,7 @@ async function buildInto(project, outputDirectory, { changedFiles, minify, quiet
   const bindingPlaceholder = placeholders.binding
   const listPlaceholder = placeholders.list
   const pageRenders = new Map()
+  const routePageFiles = new Map()
   let renderedPages = 0
 
   for (const pageFile of pageFiles) {
@@ -304,6 +311,7 @@ async function buildInto(project, outputDirectory, { changedFiles, minify, quiet
         runtimeSchema
       })
       routeRecords.push(record)
+      routePageFiles.set(record, pageFile)
       if (navigationGroup) navigationGroup.buildRecords.push(record)
       routeDrafts.push({ record, runtimeSchema, navigationGroup, applicationRoute, effectPath, nativePath, paramPath })
       if (!retainCache && config.afterBuild === undefined) {
@@ -534,10 +542,21 @@ async function buildInto(project, outputDirectory, { changedFiles, minify, quiet
     await config.afterBuild({ root, outDir: outputDirectory, sourceDir: sourceDirectory, base, routes: plans.map(plan => plan.route), plans, rewrites: sortedRewrites, artifacts })
   }
 
+  let explanation
+  if (explanationRoute) {
+    const artifact = artifacts.routes.find(entry => entry.route === explanationRoute)
+    const record = routeRecords.find(entry => entry.route === explanationRoute)
+    if (!artifact || !record) throw createDiagnosticError({ code: "explain.route.not-found", stage: "explain", message: `No emitted route exactly matches ${JSON.stringify(explanationRoute)}.`, suggestion: "Use an exact emitted route listed by kudzu inspect --json." })
+    const pageFile = routePageFiles.get(record)
+    const sourceFiles = [...pageSources.get(pageFile)].map(file => relative(root, file).replaceAll(sep, "/"))
+    explanation = await createExplanationReport({ route: explanationRoute, record, artifact, entrySource: relative(root, pageFile).replaceAll(sep, "/"), sourceFiles, sourceResults, compatibility, outputDirectory, base })
+  }
+
   const incremental = { compiledModules, renderedPages }
   return {
     result: { sourceResults, incremental },
     inspectionData: { sourceFiles: sourceFiles.map(file => relative(root, file).replaceAll(sep, "/")), sourceResults, compatibility, artifacts },
+    explanation,
     pageCount: routeRecords.length,
     behaviorCount,
     cache: { pageRenders, pageSources, placeholders, sourceResults: sourceResultsByFile }

package/framework/compiler/explanation-report.mjs

@@ -0,0 +1,137 @@
+import { createHash } from "node:crypto"
+import { readFile } from "node:fs/promises"
+import { join } from "node:path"
+import { gzipSync } from "node:zlib"
+
+const limits = Object.freeze({ sources: 100, normalization: 100, owners: 100, effects: 100, artifacts: 100 })
+
+export async function createExplanationReport({ route, record, artifact, entrySource, sourceFiles, sourceResults, compatibility, outputDirectory, base }) {
+  const sources = [...sourceFiles].sort(compareText)
+  const sourceSet = new Set(sources)
+  const results = sourceResults.filter(result => sourceSet.has(result.file))
+  const normalization = compatibility.sites.filter(site => sourceSet.has(site.file)).map(site => ({ ...site, provenance: "reachable-source" }))
+  const owners = results.flatMap(result => [
+    ...result.componentAnalysis.owners.map(owner => ownerFact(result.file, "component", owner)),
+    ...result.componentAnalysis.specializations.map(owner => ownerFact(result.file, "specialization", owner)),
+  ]).sort((left, right) => compareText(left.module, right.module) || compareText(left.kind, right.kind) || left.slot - right.slot)
+  const effects = effectFacts(record, results, sources)
+  const artifacts = await artifactFacts(artifact, outputDirectory, base)
+  const eager = artifacts.filter(entry => !entry.reasons.includes("lazy-handler-chunk") && !entry.external)
+  const lazy = artifacts.filter(entry => entry.reasons.includes("lazy-handler-chunk") && !entry.external)
+  const javascript = artifacts.filter(entry => entry.path.endsWith(".js") && !entry.external)
+  const zeroJavaScript = artifact.runtime.family === null && javascript.length === 0
+  const sections = { sources, normalization, owners, effects, artifacts }
+  return {
+    version: 1,
+    status: "ready",
+    route,
+    entrySource,
+    runtimeRoute: Boolean(record.runtimeSchema),
+    capability: { signature: artifact.capability.signature, family: artifact.runtime.family, facts: enabledFacts(artifact.capability.manifest) },
+    ...Object.fromEntries(Object.entries(sections).map(([name, entries]) => [name, entries.slice(0, limits[name])])),
+    bytes: {
+      eagerRawBytes: sum(eager, "rawBytes"),
+      eagerGzipBytes: sum(eager, "gzipBytes"),
+      lazyRawBytes: sum(lazy, "rawBytes"),
+      lazyGzipBytes: sum(lazy, "gzipBytes"),
+      javascriptRawBytes: sum(javascript, "rawBytes"),
+      javascriptGzipBytes: sum(javascript, "gzipBytes"),
+    },
+    zeroJavaScript: {
+      value: zeroJavaScript,
+      scope: "compiler-selected-capability-artifacts",
+      reasons: zeroJavaScript
+        ? ["no behavior runtime family", "no runtime or handler entry", "no Worker graph"]
+        : ["route selects one or more browser capability artifacts"],
+    },
+    limits,
+    summary: Object.fromEntries(Object.entries(sections).map(([name, entries]) => [name, entries.length])),
+    omitted: Object.fromEntries(Object.entries(sections).map(([name, entries]) => [name, Math.max(0, entries.length - limits[name])])),
+  }
+}
+
+function effectFacts(record, results, sources) {
+  const facts = []
+  for (const reference of record.artifacts.effects) {
+    const result = results.find(entry => entry.handlerModule && reference.module.endsWith(`/assets/${entry.handlerModule.path}`))
+    if (!result) continue
+    const handler = result.moduleIR.handlers.find(entry => entry.exportName === reference.handler)
+    const effect = result.moduleIR.effects.find(entry => entry.setup?.handler === handler?.slot)
+    if (!handler || !effect) continue
+    const owner = effect.ownership?.owner
+    const descriptor = owner?.kind === "component" ? result.componentAnalysis.owners[owner.slot] : owner?.kind === "specialization" ? result.componentAnalysis.specializations[owner.slot] : undefined
+    facts.push({
+      module: result.file,
+      handler: reference.handler,
+      ...(handler.source ? { source: handler.source } : {}),
+      owner: descriptor?.name ?? descriptor?.component?.name ?? owner?.kind ?? "module",
+      cleanup: Boolean(effect.cleanup),
+      dependencies: effect.dependencies?.length ?? 0,
+      workers: effect.workers.map(worker => {
+        const matches = sources.filter(file => file === worker.root || file.endsWith(`/${worker.root}`))
+        return matches.length === 1 ? matches[0] : worker.root
+      }).sort(compareText),
+    })
+  }
+  return facts.sort((left, right) => compareText(left.module, right.module) || compareText(left.handler, right.handler))
+}
+
+async function artifactFacts(route, outputDirectory, base) {
+  const edges = [
+    ...route.runtime.entries.map(path => [path, "runtime-entry"]),
+    ...route.runtime.requirements.map(path => [path, "runtime-requirement"]),
+    ...route.handlers.entries.map(path => [path, "handler-entry"]),
+    ...route.handlers.chunks.map(path => [path, "handler-chunk"]),
+    ...route.handlers.lazyChunks.map(path => [path, "lazy-handler-chunk"]),
+    ...route.workers.flatMap(worker => [[worker.entry, `worker:${worker.source}`], ...worker.chunks.map(path => [path, `worker-chunk:${worker.source}`])]),
+    ...route.styles.map(path => [path, "style"]),
+  ]
+  const selected = new Map()
+  for (const [url, reason] of edges) {
+    const reasons = selected.get(url) ?? new Set()
+    reasons.add(reason)
+    selected.set(url, reasons)
+  }
+  return Promise.all([...selected].sort(([left], [right]) => compareText(left, right)).map(async ([url, reasons]) => {
+    if (/^https?:\/\//.test(url)) return { path: url, reasons: [...reasons].sort(compareText), external: true }
+    const pathname = new URL(url, "https://kudzu.invalid").pathname
+    const deployed = base && pathname.startsWith(`${base}/`) ? pathname.slice(base.length + 1) : pathname.slice(1)
+    const contents = await readFile(join(outputDirectory, deployed))
+    return {
+      path: deployed,
+      reasons: [...reasons].sort(compareText),
+      rawBytes: contents.byteLength,
+      gzipBytes: gzipSync(contents).byteLength,
+      sha256: createHash("sha256").update(contents).digest("hex"),
+    }
+  }))
+}
+
+function ownerFact(module, kind, owner) {
+  return {
+    module,
+    kind,
+    slot: owner.slot,
+    name: owner.name ?? owner.component?.name ?? "anonymous",
+    states: owner.states?.length ?? 0,
+    refs: owner.refs?.length ?? 0,
+    ids: owner.ids?.length ?? 0,
+    provenance: "reachable-source",
+  }
+}
+
+function enabledFacts(value, prefix = "") {
+  const facts = []
+  for (const [key, entry] of Object.entries(value ?? {}).sort(([left], [right]) => compareText(left, right))) {
+    if (key === "version") continue
+    const path = prefix ? `${prefix}.${key}` : key
+    if (entry === true) facts.push(path)
+    else if (typeof entry === "number" && entry > 0) facts.push(`${path}=${entry}`)
+    else if (Array.isArray(entry)) for (const item of entry) facts.push(`${path}=${item}`)
+    else if (entry && typeof entry === "object") facts.push(...enabledFacts(entry, path))
+  }
+  return facts
+}
+
+const sum = (entries, field) => entries.reduce((total, entry) => total + entry[field], 0)
+const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudzujs/core",
-  "version": "0.16.12",
+  "version": "0.16.14",
   "description": "HTML-first TSX framework with synchronous state semantics and no virtual DOM",
   "type": "module",
   "license": "MIT",
@@ -65,6 +65,7 @@
     "benchmark:project-list-decision": "node test/project-list-decision-performance.mjs",
     "benchmark:project-state": "node test/project-state-performance.mjs",
     "benchmark:source-scale": "node test/source-scale-performance.mjs",
+    "benchmark:ai-delivery": "node test/ai-delivery-runner.mjs",
     "prepublishOnly": "npm run check && npm test",
     "deploy": "wrangler deploy",
     "preview": "wrangler dev"