@kudzujs/core 0.16.10 → 0.16.12

package/MIGRATION_ROADMAP.md

@@ -24,6 +24,12 @@ Apache Answer's first route-shell gate replaces `RouterProvider` and nested `Out
 
 Apache Answer authoring/admin intake now builds native question creation and keyed administration without form, editor, query, or state package runtimes. Constraint-backed title/markdown fields, controlled preview, markdown file import, local draft mutation, keyed admin rows, and deletion compile through existing handlers/lists while a legal sibling remains JavaScript-free. Rich CodeMirror ownership, server validation, upload progress, and destructive confirmation remain later acceptance gates.
 
+Apache Answer's reduced authentication, query, route, detail, create/edit, validation, refresh, administration, and logout paths now pass one connected deterministic browser journey. Existing layout-owned Zustand reduction, search signals, dependency effects, runtime parameters, native forms, keyed lists, enhanced navigation, and direct handlers preserve server-authoritative errors and mutations, edit persistence across reload, admin deletion refresh, accessible statuses, exact source retention, and a zero-JavaScript public sibling. No compiler, IR, runtime, package adapter, or public API changed; this remains a connected reduction rather than a whole-application migration claim.
+
+Memos now has a first durable connected slice derived from pinned upstream source: invalid and valid login, loading and server error, overlapping-key pagination, explicit refresh, native memo creation, editing, deletion, reaction, realtime refresh, reload persistence, and logout pass one deterministic browser journey. Existing layout state, dependency effects, keyed ownership, native forms and handlers, enhanced navigation, and effect-owned WebSocket lifecycle retain one memo DOM node through error recovery, feed mutations, duplicate and stale events, reconnect, and fresh route ownership. Listener, socket, and reconnect-timer counts return to zero on release, and the public sibling remains JavaScript-free. No query runtime, Connect RPC client, React runtime, compiler semantic, or public API is added, and this remains a reduced application slice rather than a whole-Memos claim.
+
+Actual Budget intake remains deferred at its pinned MIT revision. The available sparse acquisition omits required workspace tooling, component and backend packages, database and worker coordination, and spreadsheet implementation, so it cannot establish an executable user journey or honest whole-workspace retention denominator. No compatibility claim or speculative framework work is authorized until a complete pinned workspace is available.
+
 ## North Star
 
 An AI should be able to migrate ordinary React-shaped TypeScript and TSX to CDN-deployable static HTML, CSS, and only the route-specific ESM capabilities actually used, with minimal source restructuring.
@@ -51,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.19.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.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,29 @@
 
 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.
 
+## 0.16.12 Bounded Application Inspection
+
+Measured 2026-08-31 on Linux x64 with Node 24.14.0. Inspection is a build-time
+projection over existing 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 648.7 ms median
+on this host without a timing comparison. Browser-disabled and required-Chrome
+suites pass 295/295 tests, package smoke passes, and bounded deterministic CLI
+coverage includes reachable-source filtering and structured blocker output.
+
+## 0.16.11 Structured Compiler Diagnostics
+
+Measured 2026-08-31 on Linux x64 with Node 24.14.0. Structured diagnostics are
+compiler and CLI output only; all representative deploy manifests, route bytes,
+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
+release-candidate builds record a 1,034.4 ms median on this loaded host; timing is
+not compared.
+The complete browser-disabled and required-Chrome suites pass 293/293 tests,
+focused JSON CLI and human diagnostic tests pass, and package smoke builds one
+static page with zero interactive pages.
+
 ## 0.16.10 Apache Answer Authentication Journey
 
 Measured 2026-08-31 on Linux x64 with Node 24.14.0 and required Chrome. The

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.10 - Apache Answer authentication journey.** The existing layout-owned session reduction now passes anonymous, invalid and valid login, reload restoration, shared settings, and 401 replacement navigation against a deterministic server without compiler or browser-output changes. Read the [release notes](./RELEASES.md#01610---apache-answer-authentication-journey), open the [release page](https://github.com/kudzujs/kudzu/releases/tag/v0.16.10), or follow the [architecture packet](./docs/next-architecture/README.md).
+**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).
 
 - [Documentation](https://kudzujs.cloud/docs)
 - [Installation guide](https://kudzujs.cloud/docs#install)

package/RELEASES.md

@@ -1,5 +1,66 @@
 # Kudzu Releases
 
+## 0.16.12 - Bounded Application Inspection
+
+Kudzu 0.16.12 lets tools select the first migration blocker from a compact
+reachable-application inventory instead of reading the compiler's raw semantic
+records or scanning an entire source tree.
+
+### Changed in 0.16.12
+
+- Adds `kudzu inspect --json`, which runs the authoritative build graph and emits
+  one versioned report of reachable modules, routes, package compatibility,
+  capability families, semantic owners, and blocker candidates.
+- Sorts every section before applying fixed limits and reports total and omitted
+  counts so large applications retain bounded deterministic context.
+- Distinguishes confirmed structured diagnostic blockers from unsupported
+  compatibility sites and partial-package review candidates.
+- Excludes unreachable source, generated module code, HTML, RouteIR, ModuleIR,
+  captures, state values, and complete artifact closures from inspection output.
+- Reuses existing source, compatibility, ownership, capability, and artifact
+  records; it adds no analyzer, semantic primitive, runtime concept, public
+  application API, or browser byte.
+- Updates `create-kudzu@0.1.137` to generate projects on
+  `@kudzujs/core@^0.16.12`.
+
+`inspect` performs the ordinary authoritative build, including configured
+`afterBuild()` behavior. A structured compiler failure returns a bounded blocked
+report with incomplete inventory rather than pretending that later facts exist.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.16.12
+```
+
+## 0.16.11 - Structured Compiler Diagnostics
+
+Kudzu 0.16.11 gives tools and agents stable machine-readable authored-source
+errors without replacing concise human diagnostics or exposing compiler internals.
+
+### Changed in 0.16.11
+
+- Adds `kudzu build --json`, which emits one versioned diagnostic envelope with
+  stable semantic code, stage, severity, project-relative source range, message,
+  nullable compatibility class, and nullable safe suggestion.
+- Preserves readable source-located build and development errors; agents no
+  longer need to parse maintained error-message substrings.
+- Covers unresolved imports and re-exports, unsupported dynamic imports,
+  TypeScript syntax errors, runtime-locale `react-i18next`, and invalid keyed-row
+  ref initializers through the shared diagnostic transport.
+- Reuses the existing compatibility registry and keeps pass filenames, generated
+  source, IR slots, runtime records, and stack traces out of machine output.
+- Adds no semantic primitive, compiler pass, runtime concept, browser module, or
+  deploy byte. Representative artifact manifests and hashes remain unchanged.
+- Updates `create-kudzu@0.1.136` to generate projects on
+  `@kudzujs/core@^0.16.11`.
+
+### Upgrade
+
+```sh
+npm install @kudzujs/core@^0.16.11
+```
+
 ## 0.16.10 - Apache Answer Authentication Journey
 
 Kudzu 0.16.10 promotes the existing Apache Answer authentication reduction from

package/bin/kudzu.mjs

@@ -6,18 +6,40 @@ import { fileURLToPath } from "node:url"
 
 const command = process.argv[2] ?? "dev"
 
-if (command === "build" && !process.env.KUDZU_BUILD_CHILD) {
+if ((command === "build" || command === "inspect") && !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") {
+} else if (command === "build" || command === "dev" || command === "inspect") {
   module.enableCompileCache?.()
-  const { build, dev } = await import("../framework/build.mjs")
-  await (command === "build" ? build : dev)()
+  const { build, dev, inspect } = await import("../framework/build.mjs")
+  const json = command === "build" && process.argv.includes("--json")
+  try {
+    if (command === "inspect") {
+      if (!process.argv.includes("--json")) {
+        console.error("Use: kudzu inspect --json")
+        process.exitCode = 1
+      } else {
+        const log = console.log
+        console.log = console.error
+        try {
+          process.stdout.write(`${JSON.stringify(await inspect())}\n`)
+        } finally {
+          console.log = log
+        }
+      }
+    } else await (command === "build" ? build({ quiet: json }) : dev())
+  } catch (error) {
+    const { diagnosticEnvelope } = await import("../framework/compiler/diagnostics.mjs")
+    const envelope = diagnosticEnvelope(error)
+    if (!envelope) throw error
+    console.error(json ? JSON.stringify(envelope) : error.message)
+    process.exitCode = 1
+  }
 } else {
-  console.error(`Unknown command: ${command}\nUse: kudzu <build|dev>`)
+  console.error(`Unknown command: ${command}\nUse: kudzu <build|dev|inspect>`)
   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.19.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.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

@@ -1679,6 +1679,27 @@ retain the public `0.16.x` line.
   introduced.
 - **Done condition:** this is a connected browser journey, not a whole-app claim.
 
+Complete. One Apache Answer-derived fixture now connects invalid and valid login,
+layout-shared authentication, page/order query loading, explicit refresh, native
+creation with server validation and retained draft, runtime detail routing,
+editing, reload persistence, keyed administration, delete-and-refetch, and
+logout against one deterministic server. Native controls and status/alert
+regions preserve the accessibility boundary, every retained source file is
+checked, and the public sibling remains complete HTML with zero JavaScript.
+
+The packet reuses existing Zustand normalization, search signals, dependency
+effects, runtime parameters, native handlers, bindings, keyed ownership, and
+enhanced navigation. It adds zero semantic primitives, ModuleIR kinds, compiler
+passes or core LOC, runtime concepts, package adapters, and public APIs. The new
+fixture emits 33 deploy files and 88,198 raw / 33,173 gzip bytes; `/` owns 27,196
+raw / 11,968 gzip bytes, `/questions` owns 51,577 raw / 19,801 gzip bytes,
+`/questions/add` owns 27,109 raw / 11,893 gzip bytes, runtime detail owns 32,783
+raw / 14,056 gzip bytes, admin owns 50,861 raw / 19,426 gzip bytes, and `/public`
+owns zero JavaScript. Worker and window graphs remain 907 raw / 477 gzip and
+14,456 raw / 6,160 gzip bytes; seven clean Linux x64 builds record a 640.5 ms
+median without a timing comparison. No production logic changed, so the public
+version remains `0.16.10` and no release is consumed.
+
 ### `0.19.3`: Memos Feed And CRUD Journey
 
 - **Purpose:** establish the first durable Memos application slice.
@@ -1689,6 +1710,26 @@ retain the public `0.16.x` line.
 - **Done condition:** pinned upstream provenance and exact retained source are
   recorded.
 
+Complete. A fixture pinned to Memos revision
+`e5ed6e7ec60e141d6e354f3ab59906c2c47dccac` now runs invalid and valid login,
+initial loading, a server pagination failure, explicit recovery, overlapping-key
+pagination, create, edit, delete, reload persistence, and logout against one
+deterministic server. The retained memo row keeps DOM identity through the
+failed request, successful pagination, and every CRUD refetch. Native labels,
+status and alert regions preserve the accessibility boundary, every authored
+source file is retained, and the public sibling emits zero JavaScript.
+
+The packet reuses existing Zustand normalization, dependency effects, keyed
+ownership, native forms and handlers, and enhanced navigation. It adds zero
+semantic primitives, ModuleIR kinds, compiler passes or core LOC, runtime
+concepts, package adapters, and public APIs. The fixture emits 19 deploy files
+and 56,167 raw / 21,634 gzip bytes; `/` owns 25,856 raw / 11,396 gzip bytes,
+`/feed` owns 45,690 raw / 17,836 gzip bytes, and `/public` owns zero JavaScript.
+Worker and window graphs remain 907 raw / 477 gzip and 14,456 raw / 6,160 gzip
+bytes; seven clean Linux x64 builds record a 761.8 ms median without a timing
+comparison. No production logic changed, so the public version remains
+`0.16.10` and no release is consumed.
+
 ### `0.19.4`: Memos Realtime Journey
 
 - **Purpose:** add reaction and realtime refresh using the accepted long-lived
@@ -1698,6 +1739,27 @@ retain the public `0.16.x` line.
 - **Stop condition:** a query or SSE package runtime is copied wholesale.
 - **Done condition:** browser and endurance acceptance pass.
 
+Complete. The connected Memos fixture now adds a native reaction mutation and
+an effect-owned WebSocket that refreshes the keyed feed from versioned server
+events. Required Chrome proves duplicate and stale version rejection, old-socket
+callback rejection after reconnect, retained memo DOM identity, exact route
+cleanup, and fresh ownership after re-entry and reload. Active sockets,
+listeners, and reconnect timers remain bounded and return to zero after each
+owner release. The public sibling remains complete HTML with zero JavaScript.
+
+The packet reuses existing native handlers, keyed ownership, effect-private
+lifecycle, invalidation, timers, and route release. It adds zero semantic
+primitives, ModuleIR kinds, compiler passes or core LOC, runtime concepts,
+normalization or adapter rules, and public APIs. The fixture emits 19 deploy
+files and 57,811 raw / 22,069 gzip bytes; `/` owns 25,856 raw / 11,396 gzip
+bytes, `/feed` owns 46,740 raw / 18,184 gzip bytes, and `/public` owns zero
+JavaScript. Worker and window graphs remain 907 raw / 477 gzip and 14,456 raw /
+6,160 gzip bytes; seven clean Linux x64 builds record a 620.7 ms median without
+a timing comparison. Browser-disabled tests pass 292/292, required-Chrome
+focused acceptance, package smoke, and artifact accounting pass. No production
+logic changed, so the public version remains `0.16.10` and no release is
+consumed.
+
 ### `0.19.5`: Actual Budget Intake Decision
 
 - **Purpose:** determine whether a complete, legally and technically usable
@@ -1708,6 +1770,18 @@ retain the public `0.16.x` line.
 - **Done condition:** a later packet is authorized, or deferral is recorded with
   no compatibility claim.
 
+Deferred by the stop condition. The pinned MIT revision
+`87e33e49eb4d666c33e0c0f172faf340d1b7aa0a` remains only a sparse desktop-client
+acquisition: 810 TS/TSX modules, 163,344 LOC, and 80 route declarations without
+the workspace tooling, component library, core backend, Yarn release, database,
+worker coordinator, or spreadsheet implementation needed to install and run an
+honest user journey. The prior static report probe is an exported report, not
+Actual Budget, and its 22/906 retained-line result is not a whole-workspace
+denominator. No later application packet, compatibility claim, compiler work,
+runtime, package adapter, public API, version, or release is authorized. Intake
+may resume only from a complete pinned workspace and executable dependency
+graph.
+
 ## `0.20.x`: AI Tooling And Delivery Cost
 
 ### `0.20.0`: Structured Diagnostics
@@ -1719,6 +1793,30 @@ retain the public `0.16.x` line.
 - **Done condition:** agents no longer parse message substrings for maintained
   fixtures.
 
+Complete. Authored
+source failures now propagate as one versioned diagnostic envelope with stable
+semantic code, stage, severity, project-relative source range, human message,
+nullable compatibility class, and nullable safe suggestion. `kudzu build
+--json` emits only that deterministic envelope for structured failures, while
+ordinary builds and the development overlay retain readable source-located
+messages. Unresolved imports and re-exports, unsupported dynamic imports,
+TypeScript syntax errors, runtime-locale `react-i18next`, and keyed-row ref
+initializers prove the maintained boundary without parsing message text.
+
+The implementation centralizes 72 lines in `diagnostics.mjs`, reuses the
+existing compatibility classification function, and normalizes paths only at
+the project build boundary. It adds zero semantic primitives, ModuleIR kinds,
+compiler passes, normalization entries, runtime concepts, browser modules, or
+public application APIs. Production source is +111 net lines, including +8 in
+the measured core semantic file set; the increase is compiler/tooling error
+transport rather than semantic analysis. All 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 Linux x64 release-candidate builds
+record a 1,034.4 ms median without a timing comparison. `npm run check`, 293/293
+browser-disabled and required-Chrome tests, focused CLI JSON tests, development error recovery, package smoke,
+artifact accounting, and `git diff --check` pass. The packet ships as
+`@kudzujs/core@0.16.11` with `create-kudzu@0.1.136`.
+
 ### `0.20.1`: `kudzu inspect --json`
 
 - **Purpose:** expose reachable application and compatibility inventory.
@@ -1728,6 +1826,27 @@ retain the public `0.16.x` line.
 - **Done condition:** the first blocker can be selected without reading hundreds
   of source or dependency files.
 
+Complete. `kudzu inspect --json` now runs the authoritative build and projects
+the existing reachable source, compatibility, ComponentAnalysis, ModuleIR,
+CapabilityIR, and route-artifact records into one versioned report. Modules,
+routes, packages, compatibility sites, capability families, semantic owners,
+and blockers sort before fixed section limits; totals and omitted counts keep
+large-project context explicit. Unreachable source, generated code, HTML, raw
+IR, captures, state values, and full artifact closures remain excluded.
+
+One real CLI fixture proves reachable filtering, static and interactive route
+facts, native package classification, state ownership, project-relative paths,
+deterministic output, and structured blocked inventory. A synthetic 101-module
+and 51-blocker check proves sort-before-truncation and first-blocker retention.
+The implementation is one 154-line projection over existing records 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 648.7 ms
+median without a timing comparison. Browser-disabled and required-Chrome suites
+pass 295/295 tests, package smoke and artifact accounting pass, and the packet
+ships as `@kudzujs/core@0.16.12` with `create-kudzu@0.1.137`.
+
 ### `0.20.2`: `kudzu explain --route`
 
 - **Purpose:** trace one authored route to its selected browser artifacts.
@@ -1948,3 +2067,9 @@ release transaction where possible or document and publish a forward-fix patch.
 | `0.18.3` | Released as `0.16.8` | Preserve shared deferred ownership, interaction-only loading, native document module-map deduplication, exact owner cleanup, binding-aware import validation, and static exclusion. | Patch release retained the `0.16.x` public version line |
 | `0.19.0` | Released as `0.16.9` | Preserve the compatibility registry, reachable source inventory, exact ranges, and package-neutral output boundary. | Patch release retained the `0.16.x` public version line |
 | `0.19.1` | Released as `0.16.10` | Preserve anonymous, invalid/valid login, token restore, layout-shared session reads, 401 clear, replacement navigation, and public zero-JavaScript output. | Patch release retained the `0.16.x` public version line |
+| `0.19.2` | Closed by existing semantics | Preserve connected auth, query, route, create/edit validation, refresh, persistence, admin deletion, logout, source retention, accessibility, and public zero-JavaScript output. | No production change; no release consumed |
+| `0.19.3` | Closed by existing semantics | Preserve connected Memos login, loading/error, feed, overlapping-key pagination, refresh, CRUD, reload persistence, logout, source retention, accessibility, and public zero-JavaScript output. | No production change; no release consumed |
+| `0.19.4` | Closed by existing effect ownership | Preserve reaction mutation, version deduplication, stale-socket rejection, reconnect, keyed identity, exact route cleanup, fresh ownership, bounded handles/listeners/timers, and public zero-JavaScript output. | No production change; no release consumed |
+| `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 |

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

@@ -1,6 +1,6 @@
 # Current Compiler Architecture
 
-This maps the current `0.16.10` 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.19.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.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.
 
 ## Responsibility Map
 
@@ -12,6 +12,7 @@ This maps the current `0.16.10` architecture, built on the completed `0.9.0` sem
 | 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. |
 | Reachability/import resolution | [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `reachableSourceFiles()`; [`framework/compiler/source-graph.mjs`](../../framework/compiler/source-graph.mjs), `ordinaryRuntimeDependencies()`, `resolveSourceImport()` | Starts from page entries, follows relative runtime imports/re-exports and validated Worker references, excludes unreachable migration source, and fails unresolved ordinary edges or dynamic imports at the importer source location before code generation. A lazy package edge must resolve lexically to a named React or Kudzu `useEffect` import. |
 | Compatibility inventory | [`framework/compiler/compatibility-registry.mjs`](../../framework/compiler/compatibility-registry.mjs), `createCompatibilityReport()` | Classifies package/API sites in reachable original source as Native, Compiled, Normalized, Adapter, Owned External UI, Partial, or Unsupported and writes deterministic source ranges to `.kudzu/kudzu-compatibility.json`. Package provenance ends here and never enters semantic IR or browser output. |
+| Structured diagnostics | [`framework/compiler/diagnostics.mjs`](../../framework/compiler/diagnostics.mjs), `KudzuDiagnosticError`, `diagnosticEnvelope()` | Carries versioned stable codes, semantic stages, severity, authored source ranges, messages, nullable compatibility classes, and safe suggestions through programmatic builds. Build-boundary path normalization keeps JSON project-relative; human compiler and development messages retain their existing source context. Internal IR and artifact invariants remain ordinary errors. |
 | Ordered normalization | [`framework/compiler/normalization-pipeline.mjs`](../../framework/compiler/normalization-pipeline.mjs), `applyNormalizationPasses()`; [`framework/compiler/source-compiler.mjs`](../../framework/compiler/source-compiler.mjs), `normalizeCompilerSource()` | Applies migration/resource passes in order and repairs TypeScript parent pointers after every structural change. Imported source uses the same pipeline. |
 | Focused normalization passes | [`framework/compiler/`](../../framework/compiler/) | React, Router, browser signals, animation-frame refs, custom-hook timers, Zustand, and render control each validate and lower a narrow source shape. |
 | Shared AST/scope helpers | [`framework/compiler/ast-helpers.mjs`](../../framework/compiler/ast-helpers.mjs) | Binding, scope, reference, inclusive ancestry, effect-return, and source-location analysis. |

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.19.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.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.19.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.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.19.2` Apache Answer Connected Authoring Journey 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.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.

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.19.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.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.135` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.16.10`.
+`create-kudzu@0.1.137` retains the explicit install instructions and generates projects with `@kudzujs/core@^0.16.12`.
 
 ## Release Boundary
 

package/framework/build.mjs

@@ -5,6 +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 { createInspectionReport } from "./compiler/inspection-report.mjs"
 import { generateListRuntime } from "./compiler/list-runtime-codegen.mjs"
 import { assetPath, browserPath, relativeModulePath, withBase } from "./compiler/path-helpers.mjs"
 import { createProjectSession } from "./compiler/project-session.mjs"
@@ -37,7 +39,12 @@ export async function build({ quiet = false, minify = true, root: projectRoot =
   return buildWithSession(project, { quiet, minify, retainCache: false })
 }
 
-export async function buildWithSession(project, { changedFiles, quiet = false, minify = true, retainCache = true } = {}) {
+export async function inspect({ minify = true, root: projectRoot = process.cwd() } = {}) {
+  const project = createProjectSession(projectRoot)
+  return buildWithSession(project, { quiet: true, minify, retainCache: false, inspection: true })
+}
+
+export async function buildWithSession(project, { changedFiles, quiet = false, minify = true, retainCache = true, inspection = false } = {}) {
   const { root, outputDirectory } = project
   const stagedOutput = join(root, ".kudzu-dist-staging")
   const backupOutput = join(root, ".kudzu-dist-backup")
@@ -46,11 +53,16 @@ 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 } = await buildInto(project, stagedOutput, { changedFiles, minify, quiet, retainCache })
+    const { result, pageCount, behaviorCount, cache, inspectionData } = await buildInto(project, stagedOutput, { changedFiles, minify, quiet, retainCache })
     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 result
+    return inspection ? createInspectionReport(inspectionData) : result
+  } catch (error) {
+    const normalized = normalizeDiagnosticError(error, root)
+    const envelope = inspection && diagnosticEnvelope(normalized)
+    if (envelope) return createInspectionReport({ diagnostics: envelope.diagnostics })
+    throw normalized
   } finally {
     try {
       await rm(stagedOutput, { recursive: true, force: true })
@@ -104,7 +116,8 @@ async function buildInto(project, outputDirectory, { changedFiles, minify, quiet
   if (!pageFiles.length) throw new Error("No pages found in src/pages/")
   const pageSources = new Map(pageFiles.map(file => [file, new Set(reachableSourceFiles([file], allSourceFileSet, sourceIndex))]))
   const sourceFiles = [...new Set([...pageSources.values()].flatMap(files => [...files]))].sort()
-  await writePrettyJson(join(workDirectory, "kudzu-compatibility.json"), createCompatibilityReport(sourceFiles.map(file => ({ file: relative(root, file).replaceAll(sep, "/"), source: sourceIndex.get(file) }))))
+  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
   sourceFileSet.clear()
   for (const file of sourceFiles) sourceFileSet.add(file)
@@ -524,6 +537,7 @@ async function buildInto(project, outputDirectory, { changedFiles, minify, quiet
   const incremental = { compiledModules, renderedPages }
   return {
     result: { sourceResults, incremental },
+    inspectionData: { sourceFiles: sourceFiles.map(file => relative(root, file).replaceAll(sep, "/")), sourceResults, compatibility, artifacts },
     pageCount: routeRecords.length,
     behaviorCount,
     cache: { pageRenders, pageSources, placeholders, sourceResults: sourceResultsByFile }

package/framework/compiler/ast-helpers.mjs

@@ -1,4 +1,5 @@
 import ts from "typescript"
+import { createDiagnosticError } from "./diagnostics.mjs"
 
 export function importDeclarationNames(statement) {
   const names = []
@@ -146,11 +147,22 @@ export function functionVarDeclaresName(fn, name) {
   return found
 }
 
-export function sourceNodeError(node, fallbackSource, message) {
+export function sourceNodeError(node, fallbackSource, message, metadata = {}) {
   const original = ts.getOriginalNode(node)
   const sourceFile = original.getSourceFile?.()?.fileName ? original.getSourceFile() : fallbackSource
-  const position = sourceFile.getLineAndCharacterOfPosition(original.getStart(sourceFile))
-  return new Error(`${sourceFile.fileName}:${position.line + 1}:${position.character + 1} ${message}`)
+  const startOffset = original.getStart(sourceFile)
+  const endOffset = original.getEnd()
+  const start = sourceFile.getLineAndCharacterOfPosition(startOffset)
+  const end = sourceFile.getLineAndCharacterOfPosition(endOffset)
+  return createDiagnosticError({
+    message,
+    source: {
+      file: sourceFile.fileName,
+      start: { line: start.line + 1, column: start.character + 1, offset: startOffset },
+      end: { line: end.line + 1, column: end.character + 1, offset: endOffset },
+    },
+    ...metadata,
+  })
 }
 
 export function sourceLocation(node, fallbackSource) {

package/framework/compiler/compatibility-registry.mjs

@@ -46,7 +46,7 @@ function compatibilitySites(file, source) {
   const sites = []
   const add = (target, imported, local, kind, node) => {
     if (!isBarePackage(target) || target === "@kudzujs/core" || target.startsWith("@kudzujs/core/")) return
-    const rule = classify(target, imported, kind)
+    const rule = classifyCompatibility(target, imported, kind)
     const start = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile))
     const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd())
     sites.push({
@@ -94,7 +94,7 @@ function compatibilitySites(file, source) {
   return sites
 }
 
-function classify(target, imported, kind) {
+export function classifyCompatibility(target, imported, kind) {
   if (kind === "re-export") return { id: "package.re-export.unsupported", classification: "Unsupported" }
   if (kind === "side-effect-import") return { id: "package.side-effect.unsupported", classification: "Unsupported" }
   const root = packageRoot(target)

package/framework/compiler/diagnostics.mjs

@@ -0,0 +1,72 @@
+import { isAbsolute, relative, sep } from "node:path"
+
+export class KudzuDiagnosticError extends Error {
+  constructor(diagnostics) {
+    super(diagnostics.map(formatDiagnostic).join("\n"))
+    this.diagnostics = diagnostics
+  }
+}
+
+export function createDiagnosticError(diagnostic) {
+  return new KudzuDiagnosticError([{
+    code: "source.unsupported",
+    stage: "analyze",
+    severity: "error",
+    compatibilityClass: null,
+    suggestion: null,
+    ...diagnostic,
+  }])
+}
+
+export function createTypeScriptDiagnosticError(errors, flattenMessage) {
+  return new KudzuDiagnosticError(errors.map(error => {
+    const sourceFile = error.file
+    const startOffset = error.start ?? 0
+    const endOffset = startOffset + (error.length ?? 0)
+    const start = sourceFile?.getLineAndCharacterOfPosition(startOffset)
+    const end = sourceFile?.getLineAndCharacterOfPosition(endOffset)
+    return {
+      code: "source.syntax.invalid",
+      stage: "analyze",
+      severity: "error",
+      compatibilityClass: null,
+      suggestion: null,
+      message: flattenMessage(error.messageText),
+      ...(sourceFile && start && end ? { source: {
+        file: sourceFile.fileName,
+        start: { line: start.line + 1, column: start.character + 1, offset: startOffset },
+        end: { line: end.line + 1, column: end.character + 1, offset: endOffset },
+      } } : {}),
+    }
+  }))
+}
+
+export function normalizeDiagnosticError(error, root) {
+  if (!(error instanceof KudzuDiagnosticError)) return error
+  const normalized = new KudzuDiagnosticError(error.diagnostics.map(diagnostic => ({
+    ...diagnostic,
+    source: diagnostic.source && {
+      ...diagnostic.source,
+      file: normalizeFile(diagnostic.source.file, root),
+    },
+  })))
+  normalized.message = error.message
+  return normalized
+}
+
+export function diagnosticEnvelope(error) {
+  if (!(error instanceof KudzuDiagnosticError)) return undefined
+  return { version: 1, diagnostics: error.diagnostics }
+}
+
+function normalizeFile(file, root) {
+  if (!isAbsolute(file)) return file.replaceAll(sep, "/")
+  const path = relative(root, file)
+  return (path.startsWith("..") ? file : path).replaceAll(sep, "/")
+}
+
+function formatDiagnostic(diagnostic) {
+  const start = diagnostic.source?.start
+  const location = diagnostic.source ? `${diagnostic.source.file}${start ? `:${start.line}:${start.column}` : ""} ` : ""
+  return `${location}${diagnostic.message}`
+}

package/framework/compiler/inspection-report.mjs

@@ -0,0 +1,156 @@
+const limits = Object.freeze({ modules: 100, routes: 100, packages: 100, compatibilitySites: 100, capabilities: 50, owners: 100, blockers: 50 })
+
+export function createInspectionReport({ sourceFiles = [], sourceResults = [], compatibility, artifacts, diagnostics = [] } = {}) {
+  const complete = diagnostics.length === 0
+  const modules = complete ? moduleFacts(sourceFiles, sourceResults) : []
+  const routes = complete ? routeFacts(artifacts?.routes ?? []) : []
+  const packages = complete ? [...(compatibility?.packages ?? [])] : []
+  const compatibilitySites = complete ? [...(compatibility?.sites ?? [])] : []
+  const capabilities = complete ? capabilityFacts(artifacts?.runtimeFamilies ?? []) : []
+  const owners = complete ? ownerFacts(sourceResults) : []
+  const blockers = complete ? compatibilityBlockers(compatibilitySites) : diagnosticBlockers(diagnostics)
+  const sections = { modules, routes, packages, compatibilitySites, capabilities, owners, blockers }
+
+  return {
+    version: 1,
+    status: blockers.some(blocker => blocker.severity === "error") ? "blocked" : "ready",
+    inventoryComplete: complete,
+    limits,
+    summary: Object.fromEntries(Object.entries(sections).map(([name, entries]) => [name, entries.length])),
+    ...Object.fromEntries(Object.entries(sections).map(([name, entries]) => [name, entries.slice(0, limits[name])])),
+    omitted: Object.fromEntries(Object.entries(sections).map(([name, entries]) => [name, Math.max(0, entries.length - limits[name])])),
+  }
+}
+
+function moduleFacts(sourceFiles, sourceResults) {
+  const results = new Map(sourceResults.map(result => [result.file, result]))
+  return [...sourceFiles].sort(compareText).map(file => {
+    const result = results.get(file)
+    const moduleIR = result?.moduleIR
+    return compact({
+      file,
+      kind: file.endsWith(".worker.ts") ? "worker" : file.startsWith("src/pages/") && file.endsWith(".tsx") ? "page" : "module",
+      owners: result?.componentAnalysis.owners.length ?? 0,
+      specializations: result?.componentAnalysis.specializations.length ?? 0,
+      signals: moduleIR?.signals.length ?? 0,
+      sharedStates: moduleIR?.sharedStates.length ?? 0,
+      sharedActions: moduleIR?.sharedActions.length ?? 0,
+      handlers: moduleIR?.handlers.length ?? 0,
+      bindings: moduleIR?.bindings.length ?? 0,
+      derived: moduleIR?.derived.length ?? 0,
+      effects: moduleIR?.effects.length ?? 0,
+      keyedBlocks: moduleIR?.keyedBlocks.length ?? 0,
+      imports: moduleIR?.imports.length ?? 0,
+    })
+  })
+}
+
+function routeFacts(routes) {
+  return [...routes].sort((left, right) => compareText(left.route, right.route)).map(route => ({
+    route: route.route,
+    runtimeFamily: route.runtime.family,
+    static: route.runtime.family === null && route.runtime.entries.length === 0 && route.handlers.entries.length === 0 && route.handlers.chunks.length === 0 && route.handlers.lazyChunks.length === 0 && route.workers.length === 0,
+    capabilities: enabledFacts(route.capability.manifest),
+    artifacts: {
+      runtimeEntries: route.runtime.entries.length,
+      runtimeRequirements: route.runtime.requirements.length,
+      handlerEntries: route.handlers.entries.length,
+      chunks: route.handlers.chunks.length,
+      lazyChunks: route.handlers.lazyChunks.length,
+      workers: route.workers.length,
+      styles: route.styles.length,
+    },
+  }))
+}
+
+function capabilityFacts(families) {
+  return [...families].sort((left, right) => compareText(left.id, right.id)).map(family => ({
+    id: family.id,
+    navigation: family.navigation,
+    routes: family.routes.length,
+    facts: enabledFacts(family.manifest),
+    requirements: family.requirements.length,
+  }))
+}
+
+function ownerFacts(sourceResults) {
+  const owners = []
+  for (const result of sourceResults) {
+    const effects = result.moduleIR.effects
+    const blocks = result.moduleIR.keyedBlocks
+    for (const owner of result.componentAnalysis.owners) owners.push(ownerFact(result.file, "component", owner, effects, blocks))
+    for (const owner of result.componentAnalysis.specializations) owners.push(ownerFact(result.file, "specialization", owner, effects, blocks))
+  }
+  return owners.sort((left, right) => compareText(left.module, right.module) || compareText(left.kind, right.kind) || left.slot - right.slot)
+}
+
+function ownerFact(module, kind, owner, effects, blocks) {
+  return {
+    module,
+    kind,
+    slot: owner.slot,
+    name: typeof owner.name === "string" ? owner.name : typeof owner.component === "string" ? owner.component : owner.component?.name ?? "anonymous",
+    ...compact({
+      stateCount: owner.states?.length ?? 0,
+      refCount: owner.refs?.length ?? 0,
+      idCount: owner.ids?.length ?? 0,
+      effectCount: effects.filter(effect => effect.ownership?.owner?.kind === kind && effect.ownership.owner.slot === owner.slot).length,
+      keyedBlockCount: kind === "specialization" ? blocks.filter(block => block.specializations?.includes(owner.slot)).length : 0,
+    }),
+  }
+}
+
+function compatibilityBlockers(sites) {
+  return sites.filter(site => site.classification === "Unsupported" || site.classification === "Partial").map(site => ({
+    kind: "compatibility",
+    severity: site.classification === "Unsupported" ? "error" : "review",
+    code: site.rule,
+    file: site.file,
+    location: site.location,
+    package: site.package,
+    imported: site.imported,
+    classification: site.classification,
+  })).sort(compareBlockers)
+}
+
+function diagnosticBlockers(diagnostics) {
+  return diagnostics.map(diagnostic => ({
+    kind: "diagnostic",
+    severity: diagnostic.severity,
+    code: diagnostic.code,
+    stage: diagnostic.stage,
+    message: diagnostic.message,
+    ...(diagnostic.source ? { source: diagnostic.source } : {}),
+    compatibilityClass: diagnostic.compatibilityClass,
+    suggestion: diagnostic.suggestion,
+  })).sort(compareBlockers)
+}
+
+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
+}
+
+function compact(record) {
+  return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== 0))
+}
+
+function compareBlockers(left, right) {
+  const leftFile = left.file ?? left.source?.file ?? ""
+  const rightFile = right.file ?? right.source?.file ?? ""
+  const leftLocation = left.location ?? left.source?.start ?? {}
+  const rightLocation = right.location ?? right.source?.start ?? {}
+  return compareText(leftFile, rightFile) || (leftLocation.line ?? 0) - (rightLocation.line ?? 0) || (leftLocation.column ?? 0) - (rightLocation.column ?? 0) || compareText(left.code, right.code)
+}
+
+function compareText(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0
+}

package/framework/compiler/source-compiler.mjs

@@ -11,6 +11,7 @@ import { analyzeCollectionPipeline, collectionExpression, collectionParameters,
 import { compatibilityPackages } from "./compatibility-registry.mjs"
 import { normalizeCustomHookTimerRefs } from "./custom-hook-timer-pass.mjs"
 import { captureNames, createDescriptorSession, createSemanticArtifact, nativeCaptureNames, referencedReducerDispatches, referencedStateNames } from "./descriptor-session.mjs"
+import { createTypeScriptDiagnosticError } from "./diagnostics.mjs"
 import { analyzeEffectDependencies, validateEffectOwnedBrowserResources } from "./effect-analysis.mjs"
 import { createHandlerCodegen } from "./handler-codegen.mjs"
 import { createHandlerLowering } from "./handler-lowering.mjs"
@@ -62,7 +63,7 @@ function compileSource(file, sourceFiles, sourceIndex, staticFiles, cssModules,
 
   const errors = result.diagnostics?.filter(diagnostic => diagnostic.category === ts.DiagnosticCategory.Error) ?? []
   if (errors.length) {
-    throw new Error(errors.map(error => ts.flattenDiagnosticMessageText(error.messageText, "\n")).join("\n"))
+    throw createTypeScriptDiagnosticError(errors, message => ts.flattenDiagnosticMessageText(message, "\n"))
   }
   const packageReference = emittedPackageReference(result.outputText, file, new Set(["react", "react-router-dom"]))
   if (packageReference) throw new Error(`${relative(root, file)} Runtime ${packageReference} module references are not supported`)
@@ -404,7 +405,11 @@ function createKudzuTransformer({ semantic, handlerUrl, file, sourceFiles, sourc
     for (const [name, binding] of packageBindings) {
       const references = referenceIdentifiers(sourceFile, name)
       const invalid = references.find(reference => !insideJsxEventHandler(reference, sourceFile) && !insideOwnedEffectCallback(reference, sourceFile))
-      if (invalid && binding.target === compatibilityPackages.reactI18next && binding.imported === "useTranslation") throw sourceNodeError(invalid, sourceFile, "React i18next useTranslation() depends on runtime locale resources; migrate build-known locales through getStaticPaths() and props, or browser-only locale reads through an owned effect")
+      if (invalid && binding.target === compatibilityPackages.reactI18next && binding.imported === "useTranslation") throw sourceNodeError(invalid, sourceFile, "React i18next useTranslation() depends on runtime locale resources; migrate build-known locales through getStaticPaths() and props, or browser-only locale reads through an owned effect", {
+        code: "react-i18next.runtime-locale.unsupported",
+        compatibilityClass: "Unsupported",
+        suggestion: "Use getStaticPaths() and props for build-known locales, or read browser-only locale state in an owned effect.",
+      })
       if (invalid) throw sourceNodeError(invalid, sourceFile, `Package import ${JSON.stringify(name)} may only be referenced directly inside JSX event handlers or owned effect setup/cleanup callbacks`)
     }
     const hasUseEffectImport = sourceFile.statements.some(statement => ts.isImportDeclaration(statement) && ["@kudzujs/core", "react"].includes(statement.moduleSpecifier.text) && statement.importClause?.namedBindings && ts.isNamedImports(statement.importClause.namedBindings) && statement.importClause.namedBindings.elements.some(entry => !entry.propertyName && entry.name.text === "useEffect"))
@@ -3028,7 +3033,10 @@ function specializeComponentCall(call, component, sourceFile, factory, context,
       }
       if (declaration.initializer && ts.isCallExpression(declaration.initializer) && ts.isIdentifier(declaration.initializer.expression) && declaration.initializer.expression.text === "useRef") {
         const hookLabel = ordinaryHooks ? "Setter-callback component" : "Keyed row"
-        if (declaration.initializer.arguments.length !== 1 || declaration.initializer.arguments[0].kind !== ts.SyntaxKind.NullKeyword) throw sourceNodeError(declaration.initializer, component.getSourceFile(), `${hookLabel} useRef() must use the direct initial value null`)
+        if (declaration.initializer.arguments.length !== 1 || declaration.initializer.arguments[0].kind !== ts.SyntaxKind.NullKeyword) throw sourceNodeError(declaration.initializer, component.getSourceFile(), `${hookLabel} useRef() must use the direct initial value null`, {
+          code: "keyed.ref.initializer.unsupported",
+          suggestion: "Initialize the object ref directly with null.",
+        })
         if (!ts.isIdentifier(declaration.name)) throw sourceNodeError(declaration.name, component.getSourceFile(), `${hookLabel} useRef() must be assigned to one identifier`)
         const refs = ordinaryHooks ? ordinaryRefs : rowRefs
         const name = `${ordinaryHooks ? "__kComponentRef" : "__kRowRef"}${Math.max(0, call.pos)}_${refs.length}`
@@ -3573,7 +3581,7 @@ async function compileClientModule(file, sourceFiles, staticFiles, cssModules, b
     reportDiagnostics: true
   })
   const errors = result.diagnostics?.filter(diagnostic => diagnostic.category === ts.DiagnosticCategory.Error) ?? []
-  if (errors.length) throw new Error(errors.map(error => ts.flattenDiagnosticMessageText(error.messageText, "\n")).join("\n"))
+  if (errors.length) throw createTypeScriptDiagnosticError(errors, message => ts.flattenDiagnosticMessageText(message, "\n"))
   return { file: relative(root, file).replaceAll(sep, "/"), path: clientModulePath(file), code: result.outputText, importedAssets: [...importedAssets].map(file => relative(root, file).replaceAll(sep, "/")).sort() }
 }
 

package/framework/compiler/source-graph.mjs

@@ -24,7 +24,11 @@ export function createSourceGraph(root) {
         const argument = node.arguments[0]
         const specifier = node.arguments.length === 1 && ts.isStringLiteralLike(argument) ? JSON.stringify(argument.text) : argument?.getText(sourceFile) ?? "<missing>"
         if (ownedLazyPackageImport(node, bindingIndex)) return
-        throw sourceNodeError(node, sourceFile, `Dynamic import ${specifier} is not supported in ordinary source modules`)
+        throw sourceNodeError(node, sourceFile, `Dynamic import ${specifier} is not supported in ordinary source modules`, {
+          code: "source.dynamic-import.unsupported",
+          stage: "graph",
+          suggestion: "Use a reachable static import, or the supported guarded package import inside an owned effect.",
+        })
       }
       ts.forEachChild(node, rejectDynamicImports)
     }
@@ -38,7 +42,11 @@ export function createSourceGraph(root) {
       } catch (error) {
         const detail = error.message.slice(error.message.indexOf("Relative import"))
         const edge = ts.isExportDeclaration(node) ? "re-export" : "import"
-        throw sourceNodeError(specifier, sourceFile, detail.replace("Relative import", `Relative runtime ${edge}`))
+        throw sourceNodeError(specifier, sourceFile, detail.replace("Relative import", `Relative runtime ${edge}`), {
+          code: edge === "import" ? "source.import.unresolved" : "source.reexport.unresolved",
+          stage: "graph",
+          suggestion: "Point the relative runtime edge to exactly one .ts or .tsx source file under src/.",
+        })
       }
     }
     return dependencies

package/package.json

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