@kudzujs/core 0.16.24 → 0.16.26

package/docs/next-architecture/1.0-large-application-compatibility-audit.md

@@ -1,372 +0,0 @@
-# Kudzu 1.0 Large-Application Compatibility Audit
-
-## Status
-
-This 2026-08-21 local discovery audit measures source compatibility after
-`0.9.0`; it does not authorize a new runtime, replace the 1.0 AI delivery
-protocol, or claim whole-application migration success. The probes used Kudzu
-`0.9.2` at `f69722032a3790dfb13151e17e1ab0f60c8280d3` on Node 24.14.0.
-Original repositories and Kudzu remained unchanged.
-
-The result is a compatibility gap: Kudzu builds reduced public slices from all
-three applications, but meaningful source retention is too low for a React-like
-large-application migration claim.
-
-## Pinned Applications
-
-| Application | Revision | License | Frontend scope | Original build |
-|---|---|---|---:|---|
-| [Memos](https://github.com/usememos/memos) | `e5ed6e7ec60e141d6e354f3ab59906c2c47dccac` | MIT | 393 TS/TSX modules, 43,099 LOC, 19 leaf routes | Pass: 5,089 modules, 292 files |
-| [Apache Answer](https://github.com/apache/answer) | `3b9f1370612e690a0b7f230f05e688930db4c6d3` | Apache-2.0 | 377 TS/TSX modules, 48,091 LOC, 88 explicit paths | Pass: 681 files |
-| [Actual Budget](https://github.com/actualbudget/actual) | `87e33e49eb4d666c33e0c0f172faf340d1b7aa0a` | MIT | sparse desktop client: 810 TS/TSX modules, 163,344 LOC, 80 route declarations | Not established: acquisition lacks workspace tooling and core packages |
-
-The Actual Budget result is diagnostic only. Its sparse checkout contains the
-selected desktop components but not the component library, core backend, Yarn
-release, database, worker coordinator, or spreadsheet implementation.
-
-The migrated adapters, copied source, detailed diagnostic logs, and line-diff
-inputs remain local under `/tmp/opencode/kudzu-large-apps`; they are not durable
-tracked evidence. The pinned upstream commits and original build commands are
-reproducible, but retention and migrated-output values remain discovery results
-until an external fixture repository pins the adapters and acceptance harness.
-
-## Migration Results
-
-### Memos
-
-The probe selected `/about`, `/explore`, and `/auth` from the real route and
-component closures. The reduced Kudzu app builds three pages and one interactive
-page. `/about` and `/explore` emit zero JavaScript; `/auth` emits 12,374 raw /
-5,956 gzip bytes of route JavaScript.
-
-| Measure | Result |
-|---|---:|
-| Direct corresponding source retained | 163 / 640 lines (25.5%) |
-| Retention including omitted feed/auth closure | 163 / 996 lines (16.4%) |
-| Final migrated TS/TSX | 12 files, 408 LOC |
-| Deploy | 14 files |
-
-The passing output is not behavior-equivalent. Live instance data, Connect RPC,
-TanStack Query, pagination, privacy filtering, markdown, reactions, SSE refresh,
-authentication, token storage, SSO discovery, and post-auth navigation are
-absent. The public feed is a build-known snapshot.
-
-### Apache Answer
-
-The probe selected questions list/detail and tags list/detail. It preserves all
-six selected component roles, but replaces the browser router, React Bootstrap,
-i18next, SWR/axios, Zustand-backed globals, guards, and live API data. Four Kudzu
-pages build; the questions list is zero JavaScript and the tags list uses the
-existing keyed-filter capabilities.
-
-| Measure | Result |
-|---|---:|
-| Exact selected source retained | 22 / 1,103 lines (2.0%) |
-| Final migrated TS/TSX | 8 files, 257 LOC |
-| Deploy | 17 files, 48,389 raw bytes |
-| JavaScript | 33,384 raw / 13,641 gzip bytes |
-
-The result has no Answer API, auth, mutations, loading/error state, pagination,
-editor, cache invalidation, or route guards. Runtime detail paths render one
-representative snapshot rather than the requested entity.
-
-### Actual Budget
-
-The probe selected the grouped report-table workflow and retained five imported
-component boundaries. It produces one complete static report page with 0 bytes
-of JavaScript.
-
-| Measure | Result |
-|---|---:|
-| Exact selected source retained | 22 / 906 lines (2.4%) |
-| Final authored probe | 268 LOC |
-| Output | 2,810 B HTML, 1,990 B CSS, 0 B JavaScript |
-
-This is an exported report, not Actual Budget. Database opening, query execution,
-spreadsheet bindings, Redux and query state, synchronization, undo, preferences,
-privacy formatting, Worker/SharedWorker ownership, synchronized scrolling, and
-transaction drill-down are absent.
-
-## Repeated Blockers
-
-| Blocker | Memos | Answer | Actual | Decision |
-|---|---|---|---|---|
-| Package components used during render | Lucide, Base UI | React Bootstrap | Actual component library, React Aria | Record separate package shapes; this broad grouping does not prove one shared semantic concept. |
-| Browser data/query ownership | TanStack Query, Connect RPC, SSE | SWR, axios | TanStack Query, worker-backed database | Define build-time snapshot and owned-effect migration contracts before considering an adapter. Do not add a query cache runtime. |
-| Router/layout semantics | RouterProvider, guards, lazy routes | nested guarded routes, outlets, `useMatch` | React Router screens and drill-down state | Keep native/file routing as the default; inventory nested layout and guard source shapes separately. |
-| Provider/global state | auth, instance, view/filter contexts | Zustand site/session/UI stores | Redux, preferences, non-serializable state | Continue package-neutral action/state reductions only from executable behavior fixtures. |
-| Localization and formatting | i18next | i18next | i18next, locale/currency/privacy preferences | Prefer build-known locale routes; browser-switchable locale ownership needs independent evidence. |
-| Dynamic presentation | markdown/editor/media/map | editor, Markdown, package widgets | grids, charts, spreadsheets | Treat imperative leaves and package adapters independently; no generic component runtime. |
-
-These broad blocker families recur, but they do not establish one shared missing
-semantic concept. Each package, query/data, router/layout, provider, localization,
-or imperative-leaf shape still needs an independent executable reduction before
-architecture review. Fixture count does not authorize a semantic primitive. The
-first implementation must stop at native behavior, existing semantics,
-normalization, or a bounded internal adapter before considering kernel growth.
-
-## Compatibility Conclusion
-
-Kudzu `0.9.2` supports large output and selected ordinary TSX, but not low-change
-migration of these large React applications. The reported retention denominators
-are not directly comparable: Memos includes an omitted feed/auth closure, Answer
-counts six selected modules, and Actual counts five retained component files from
-an incomplete sparse checkout. Every method still reports substantial rewriting.
-
-Current viable use is narrower:
-
-- static public pages and build-known read-only exports;
-- bounded forms and keyed interactions that already match Kudzu ownership;
-- separately accepted imperative leaves owned by effects;
-- native navigation to an existing application for unsupported workflows.
-
-Do not describe Memos, Answer, or Actual Budget as migrated applications. The
-passing probes are reductions that identify compatibility work.
-
-## Authorized Handoff
-
-The authoritative next milestone remains the equal-condition 1.0 AI delivery
-protocol in `0.9-implementation-plan.md`; this audit is candidate-selection input
-only. If that protocol selects an Apache Answer task, its first unsupported source
-shape is `useMatch` in the questions route. The implementation process must:
-
-1. preserve that exact failing source and reduce only the first unsupported shape;
-2. identify existing IR producers, consumers, ownership, nearby rejected forms,
-   and expected browser-byte impact before editing the compiler;
-3. run behavior and accessibility acceptance rather than build checks alone;
-4. report source retention as a diagnostic with an explicit denominator, not an
-   unapproved pass threshold;
-5. keep package-component, query/data, router/layout, localization, and provider
-   work as separate evidence packets.
-
-Combining these blockers into one compatibility runtime is not approved.
-
-## First Reduction Completion
-
-The user selected the Apache Answer routing probe under the authorized protocol.
-The first unsupported source shape, direct `const isIndexPage = useMatch("/")`,
-now lowers through the existing router normalization pass to one compiler-internal
-build-time route comparison. The same relative `Questions` component renders the
-Answer title at `/` and the Questions title at `/questions`.
-
-| Measure | Result |
-|---|---:|
-| Upstream-derived positive fixtures | 1 |
-| Nearby negative fixtures | 2 |
-| Semantic primitives | 0 |
-| ModuleIR/RouteIR records | 0 |
-| Compiler passes | 0 new |
-| Browser runtime concepts | 0 |
-| Browser JavaScript | 0 B on both routes |
-
-The producer is `compiler/router-pass.mjs`; the only consumer is a build-time
-helper in `core.mjs` reading the invocation's application route. No SPA router,
-path matcher, route signal, state, effect, handler, or browser module is added.
-Layout and runtime-parameter use fail before output; dynamic patterns and
-parameterized/wildcard/query/hash/trailing-slash forms fail with source
-diagnostics. Matching follows React Router's default case-insensitive behavior.
-Broader nested layouts, guards, outlets, and dynamic matching remain separate
-evidence packets.
-
-## Second Reduction Completion
-
-The next repeated Apache Answer blocker, direct
-`const curPage = Number(urlSearchParams.get("page")) || 1`, now separates the
-nullable query signal into a compiler-owned local and reuses the existing pure
-primitive binding evaluator. Query removal through `popstate` restores the
-finite authored fallback.
-
-| Measure | Result |
-|---|---:|
-| Upstream-derived positive fixtures | 1 |
-| Nearby negative fixtures | 1 |
-| Semantic primitives | 0 |
-| ModuleIR/RouteIR records | 0 |
-| Existing core files changed | 3 |
-| Core LOC delta | +39 |
-| Compiler passes | 0 new |
-| Browser runtime concepts | 0 |
-| Raw browser ESM | 11,211 B |
-| Build benchmark delta | Not measured; route-local compatibility slice |
-
-The producer remains `compiler/router-pass.mjs`; generic reactive-local
-substitution and binding consumers handle the result. `param-codegen.mjs` now
-applies its existing `popstate` synchronization to read-only query routes as
-well as writable routes. `Math.max`, `parseInt`, dynamic names, aliases, and
-other composed query expressions remain unsupported pending independent source
-evidence.
-
-## Third Reduction Completion
-
-Apache Answer's adjacent
-`(urlSearchParams.get("order") || QUESTION_ORDER_KEYS[0]) as QuestionOrderBy`
-now follows the same compiler-owned query signal path. The fallback is accepted
-only when it is a static numeric element of a named relative JSON-safe immutable
-array. The selected string is folded before binding/effect analysis, so the
-browser handler retains neither the array nor its source module.
-
-| Measure | Result |
-|---|---:|
-| Upstream-derived positive fixtures | 1 |
-| Nearby negative fixtures | 1 |
-| Semantic primitives | 0 |
-| ModuleIR/RouteIR records | 0 |
-| Existing core files changed | 2 |
-| Core LOC delta | +7 |
-| Compiler passes | 0 new |
-| Browser runtime concepts | 0 |
-| Raw browser ESM | 11,210 B |
-| Build benchmark delta | Not measured; route-local compatibility slice |
-
-Static output uses `newest`, `?order=active` updates both the attribute and text,
-and query removal through `popstate` restores `newest`. Dynamic indexes, local
-fallback arrays, package imports, calls, and arbitrary expressions remain
-unsupported.
-
-## Fourth Reduction Completion
-
-Apache Answer's Questions page uses React Bootstrap `Row` and `Col` only as
-declarative layout wrappers with static classes and children. The existing React
-migration normalization pass now erases those named package imports and emits
-native `div.row` and `div.col` markup. Bootstrap CSS remains an ordinary
-application stylesheet dependency rather than a Kudzu runtime.
-
-| Measure | Result |
-|---|---:|
-| Upstream-derived positive fixtures | 1 |
-| Nearby negative fixtures | 1 |
-| Semantic primitives | 0 |
-| ModuleIR/RouteIR records | 0 |
-| Existing core files changed | 1 |
-| Core LOC delta | +48 |
-| Compiler passes | 0 new |
-| Browser runtime concepts | 0 |
-| Browser JavaScript | 0 B |
-| Build benchmark delta | Not measured; static normalization slice |
-
-The generated document preserves the Questions heading, complementary sidebar,
-children order, and Bootstrap class contract without scripts or behavior
-markers. Breakpoint/grid props such as `md={6}`, dynamic classes, spreads,
-subpath/default/namespace imports, and other React Bootstrap components remain
-unsupported.
-
-## Runtime Translation Boundary
-
-Apache Answer's next Questions-page failure is `react-i18next`
-`useTranslation()`. Its values are not build-known: initialization uses the
-repository's English YAML fallback, while storage and server responses can add
-or replace the active resource bundle. Folding English would lose behavior and
-shipping i18next would add a forbidden package runtime.
-
-Kudzu now reports that boundary at the hook reference and directs migration to
-the existing static-locale treatment: `getStaticPaths()` plus locale props when
-resources are build-known, or an owned browser effect when selection only exists
-in the browser. This diagnostic adds no semantic primitive, pass, runtime
-concept, browser byte, or successful migration claim.
-
-The following Questions-page store reads are not the same reduced Zustand shape:
-`loggedUserInfoStore`, `siteInfoStore`, and `loginSettingStore` own multiple data
-fields, server-fed replacement actions, and storage side effects. Their values
-are not build-known and cannot be preserved by folding initial literals. They
-remain an application data-ownership migration packet; this audit does not
-authorize a Zustand runtime or broaden `SharedStateIR` around one application's
-store graph.
-
-## Fifth Reduction Completion
-
-Apache Answer's `useQuestionList()` and `useQuestionRecommendList()` wrappers
-compose SWR, axios, and `qs` around browser-only data. The executable reduction
-keeps the Questions page's URL-derived page/order semantics but moves ownership
-to one native fetch effect with application-owned loading, error, and keyed data
-state. The existing dependency replacement contract prevents a delayed old
-response from overwriting a newer query.
-
-| Measure | Result |
-|---|---:|
-| Upstream-derived positive fixtures | 1 |
-| Static exclusion fixtures | 1 |
-| Semantic primitives | 0 |
-| ModuleIR/RouteIR records | 0 new |
-| Existing core files changed | 2 |
-| Core LOC delta | +6 |
-| Compiler passes | 0 new |
-| Browser runtime concepts | 0 new |
-| Raw interactive browser ESM | 32,005 B |
-| Static sibling JavaScript | 0 B |
-| Build benchmark delta | Not measured; browser-data compatibility slice |
-
-Chrome acceptance starts from `?page=2&order=active`, replaces it with the
-recommendation endpoint, rejects the delayed stale response, renders nested
-keyed tags, reports HTTP 500 through `role="alert"`, and recovers on the next
-query. SWR, axios, `qs`, caches, Providers, retries, deduplication, and background
-refetch remain absent. The only compiler adjustment folds the already validated
-imported immutable string fallback before generic effect dependency analysis.
-
-## Sixth Reduction Completion
-
-The full Answer source contains 94 direct `Col` elements; 63 use only static
-numeric spans across `xs`, `sm`, `md`, `lg`, `xl`, and `xxl`. The existing React
-Bootstrap normalization now maps integer literals 1 through 12 to native
-Bootstrap classes, omits bare `col` when spans exist, and preserves static
-authored classes. All 98 observed breakpoint props fit this shape.
-
-| Measure | Result |
-|---|---:|
-| Upstream-derived positive fixtures | 1 |
-| Nearby negative fixtures | 1 |
-| Observed Col sites covered | 63 / 94 |
-| Semantic primitives | 0 |
-| ModuleIR/RouteIR records | 0 |
-| Existing core files changed | 1 |
-| Core LOC delta | +14 |
-| Compiler passes | 0 new |
-| Browser runtime concepts | 0 |
-| Browser JavaScript | 0 B |
-| Build benchmark delta | Not measured; static normalization slice |
-
-Chrome is unnecessary for this static mapping: emitted HTML exactly carries
-`col-md-6`, multi-breakpoint login classes, and the five-span tag grid without
-scripts or behavior markers. Dynamic, boolean, object, offset/order, style,
-spread, and polymorphic forms remain separate evidence packets.
-
-## Seventh Reduction Intake
-
-The first authentication fixture now builds one layout-owned session record from
-the Answer login/current-user/401 shapes. Native `FormData`, token storage,
-current-user fetch, shared header/settings reads, clear, and replacement
-navigation compile without Zustand, axios, React Router, or React in output; a
-public sibling remains static. One compiler correction prevents shared-state
-identifiers such as `session.token` from being misclassified as imported
-calculation results during effect dependency analysis. This adds no IR kind,
-pass, or runtime concept. Required Chrome now proves anonymous, invalid and
-valid login, token restore after reload, shared header/settings reads, 401
-storage/state clearing, and replacement navigation against a deterministic
-server. The authentication reduction is complete without a production change.
-
-## Route Shell Intake
-
-The first route-shell fixture builds seven representative Answer paths: home,
-questions, runtime question detail, tags, runtime tag detail, admin dashboard,
-and legal. `Layout`/`SideNavLayout` become one ordinary composed shell, links are
-native anchors, and bracket pages reuse the existing pathname reader and rewrite
-metadata. No RouterProvider, Outlet, SPA router, semantic primitive, pass, or new
-runtime concept is added; the legal sibling remains zero-JavaScript. Expanding
-the same manifest/composition treatment across all 88 upstream paths remains the
-next route migration gate.
-
-Chrome acceptance directly enters `/questions/42/example-question`, verifies
-both runtime pathname fields and the composed primary/section navigation, then
-performs native document navigation to `/tags/kudzu` and verifies the tag field
-in the destination document. No hydration or browser router participates.
-
-## Authoring And Admin Intake
-
-A backend-independent Answer authoring/admin fixture now builds three routes.
-Question creation uses native constraints, `FormData`, a controlled markdown
-textarea, file text import, preview, and browser-owned persistence. The admin
-route restores that data into a keyed table and deletes rows through existing
-list and handler semantics. React Hook Form, CodeMirror, axios, Zustand, and
-React are absent from deploy handlers, and the legal sibling remains static.
-This intake adds no compiler or runtime concept; rich editor lifecycle, server
-validation, upload progress, dialogs, and complete admin browser journeys remain
-separate gates.

package/docs/next-architecture/README.md

@@ -1,56 +0,0 @@
-# Kudzu Architecture Continuation
-
-This directory is the compiler continuation packet. Planned versions remain plans until package metadata and release records mark them complete.
-
-The top-level [`GOAL_A.md`](../../GOAL_A.md) and [`GOAL_B.md`](../../GOAL_B.md) are historical completed capability records. Do not overwrite or reinterpret them. The Goal A/B/C/D names in this directory refer to the next architecture discussion:
-
-| Goal | Decision | Start condition |
-|---|---|---|
-| A: compiler foundation | Complete in `0.8.23` | The no-write source compiler, RouteIR v1, CapabilityIR v1, generator boundaries, and output baseline are recorded. |
-| B: optimization benchmarks | Maintained gate | Keyed restoration, no-op normalization, exact route-entry transform reuse, and identical route-entry file sharing are retained; continue only when another current fixture reproduces a material loss. |
-| C: state/resource model | Research only | Reduced fixtures expose a limitation |
-| D: routing compatibility | Current behavior preserved | Revisit only with migration evidence and invariant review |
-
-The completed `0.9.0` milestone is recorded in [`0.9-semantic-compression.md`](./0.9-semantic-compression.md) and [`0.9-implementation-plan.md`](./0.9-implementation-plan.md). It freezes the `0.8.62` baseline, then closes evidence-backed work on Derived, shared state/actions, resource ownership, component ownership, pass reduction, and final cross-framework proof. [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md) remains the completed foundation and longer-term plan. Model-driven delivery is separately gated for 1.0. ResourceIR remains unapproved; range ownership, virtualization, optimistic transactions, public adapters, and generic runtimes still require independent evidence and architecture review.
-
-[`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. Its `0.21.4` AI delivery proof is measured at Kudzu 11/25 versus React + Vite 24/25 and blocks `1.0.0`; the next packet must be selected from those measured failures. The plan 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
-
-- Every route remains a complete static HTML document.
-- Build-known static routes emit zero JavaScript.
-- Interactive routes emit only capabilities they use.
-- React, hydration, a VDOM, retained browser components, and React islands remain forbidden.
-- Native anchors are the default; same-document navigation remains explicit and route-group scoped.
-- Compiler specialization preserves ordinary React-shaped TSX where it can be analyzed safely.
-- Unsupported nearby forms fail with source-located diagnostics.
-
-## Reading Order
-
-1. [`application-capability-release-plan.md`](./application-capability-release-plan.md): active minor/patch execution queue through `1.0.0`.
-2. [`0.9-semantic-compression.md`](./0.9-semantic-compression.md): completed scope, evidence, and release gates.
-3. [`0.9-implementation-plan.md`](./0.9-implementation-plan.md): detailed historical session packets, benchmark plan, reports, and release procedure.
-4. [`0.9-baseline.md`](./0.9-baseline.md): dated architecture, pass, IR, runtime-concept, LOC, and test baseline.
-5. [`0.9-benchmark-contracts.md`](./0.9-benchmark-contracts.md): frozen matched-content, stateful, commerce, scale, resource, and anti-gaming contracts.
-6. [`1.0-large-application-compatibility-audit.md`](./1.0-large-application-compatibility-audit.md): local large-application migration probes, retention caveats, blockers, and authorized-protocol handoff.
-7. [`compiler-current-architecture.md`](./compiler-current-architecture.md): exact current responsibilities and data flow.
-8. [`performance-gates.md`](./performance-gates.md): output, build, and browser gates.
-9. [`large-application-ai-native-roadmap.md`](./large-application-ai-native-roadmap.md): completed foundation, longer-term direction, and completion evidence.
-10. [`goal-a-compiler-foundation.md`](./goal-a-compiler-foundation.md): completed extraction and generator foundation.
-11. [`versioning.md`](./versioning.md): completed patch sequence and future sequencing rules.
-12. [`goal-b-optimization-benchmarks.md`](./goal-b-optimization-benchmarks.md): active measurements, retained optimizations, and continuation rules.
-13. [`goal-c-state-resource-research.md`](./goal-c-state-resource-research.md): research boundary only.
-14. [`goal-d-routing-compatibility-decisions.md`](./goal-d-routing-compatibility-decisions.md): routing and islands decisions.
-
-## Resume Checklist
-
-- [ ] Read [`MIGRATION_ROADMAP.md`](../../MIGRATION_ROADMAP.md), [`0.9-semantic-compression.md`](./0.9-semantic-compression.md), and [`0.9-implementation-plan.md`](./0.9-implementation-plan.md) before planning migration work.
-- [ ] Follow the active patch in [`application-capability-release-plan.md`](./application-capability-release-plan.md); treat compatibility audits as candidate-selection input, not replacement work queues.
-- [ ] Confirm `package.json` still reports the actual current version; never infer release status from this plan.
-- [ ] Inspect the worktree and preserve unrelated or uncommitted changes.
-- [ ] Start later architecture work only by an explicit decision from the completed Goal A baseline.
-- [ ] Preserve accepted syntax, diagnostics, route plans, HTML, asset selection, and browser ownership behavior.
-- [ ] Run the repository checks required by that implementation patch and record output deltas.
-- [ ] Update this packet when a planned boundary changes; update release records only when a release actually occurs.