@kudzujs/core 0.8.61 → 0.9.0

package/docs/next-architecture/0.9-compression-ledger.md

@@ -0,0 +1,227 @@
+# Kudzu 0.9 Semantic Compression Ledger
+
+## Status
+
+This ledger completes `0.9.0-06 / Session 06A` at revision `ef5c991` and
+records the first independently verified Session 06B deletion.
+
+```text
+Core semantic LOC before 06B:  5,296
+0.8.62 baseline:               4,961
+Ordered normalization entries: 15 page / 14 imported
+```
+
+## Candidate Decisions
+
+### Component Effect Helper Materialization
+
+- Producers: `attachStateBackedEffects()` and the setter-callback helper block
+  in `source-compiler.mjs`.
+- Consumers: specialized effect analysis, helper insertion, ComponentAnalysis
+  ownership, and EffectIR registration.
+- Duplicate decision: both rewrite `__kComponentUseEffect`, preserve authored
+  source, install specialization/state links, create one compiler helper, and
+  register capability flags.
+- Required diagnostics: object-property no-state/ref/ID and every setter-callback
+  hook/callback diagnostic remain source-owned.
+- Enabled deletion: Work Item 05 proved the same helper ABI and OwnerRef.
+- Expected delta: -14 to -22 core LOC; zero passes/runtime concepts/bytes.
+- Regression fixtures: WorkLedger object props, array-prop effect sync, callback
+  and ref ownership, and object-property negatives.
+- Decision: selected first; actual delta is -25 core LOC.
+
+### Serializable Initializer Declaration Lookup
+
+- Producers: `componentHasDirectPrimitiveState()`,
+  `componentHasDirectArrayState()`, and `directStateInitializer()`.
+- Consumers: debounce, setter-effect pairing, and child/row state seeding.
+- Duplicate decision: each rescans one direct `useState()` declaration before
+  applying a caller-specific primitive/object/array restriction.
+- Required diagnostics: debounce, setter-child, keyed-row, reducer, and Zustand
+  messages remain caller-owned.
+- Enabled deletion: ComponentAnalysis and the shared literal grammar.
+- Expected delta: -6 to -12 core LOC; zero passes.
+- Regression fixtures: debounce, reducer, lazy-state, keyed-row hooks,
+  setter-child object/array, and Zustand fixtures.
+- Decision: selected second; actual delta is -7 core LOC.
+
+### Imported Calculation And Derived Production
+
+- Producers: imported-calculation validators, binding/list discovery, and
+  selected-effect Derived registration.
+- Consumers: BindingIR, DerivedIR, EffectIR, and binding-backed lists.
+- Duplicate decision: source purity/static fields are inspected from multiple
+  authored roles.
+- Required diagnostics: binding/list wording and stronger effect-only wording.
+- Enabled deletion: canonical Derived identity removes one repeated async check.
+- Expected delta: -1 core LOC now; broader work needs producer redesign.
+- Regression fixtures: Medusa, Mercury, and imported-calculation negatives.
+- Decision: reject broad work; one line is too small for this slice.
+
+### Context And Zustand Shared Actions
+
+- Producers: Context discovery and Zustand normalization.
+- Consumers: generic descriptor, handler-lowering, and ModuleIR paths.
+- Duplicate decision: generic action/state ownership was duplicated before 03.
+- Required diagnostics: Provider exposure/capture and Zustand store shape.
+- Enabled deletion: Work Item 03 already removed generic consumer branches.
+- Expected delta: 0; remaining code is adapter-specific.
+- Regression fixtures: Context/shared-action and Zustand suites.
+- Decision: evidence-closed.
+
+### Listener Pair Validation
+
+- Producers: outside-click and media-query normalizers.
+- Consumers: ordinary EffectIR analysis/codegen.
+- Duplicate decision: add/remove identity is shared, but targets and proof differ.
+- Required diagnostics: outside-click containment and media snapshot wording.
+- Enabled deletion: only `isNodeWithin()` was identical and was removed in 04.
+- Expected delta: 0; a generic matcher would move code.
+- Regression fixtures: outside-click and Cal.com media-query suites.
+- Decision: reject.
+
+### Animation Cancellation Validation
+
+- Producers: effect-private ref normalization and general effect resource proof.
+- Consumers: existing EffectIR ownership.
+- Duplicate decision: `.current` coalescing/reset differs from a local identifier.
+- Required diagnostics: ref write-count/reset and local loop cancellation.
+- Enabled deletion: none.
+- Expected delta: 0.
+- Regression fixtures: Memos outline and canvas/frame negatives.
+- Decision: reject.
+
+### Specialization Discovery Loops
+
+- Producers: setter, reducer, keyed/state-backed, and object-property loops.
+- Consumers: shared `specialize()` plus distinct callback/list owners.
+- Duplicate decision: resolution/iteration looks similar, but source boundaries,
+  ordering, and diagnostics differ.
+- Required diagnostics: every specialization label and callback depth.
+- Enabled deletion: only the helper materializer selected above.
+- Expected delta: 0 for broader unification; mostly code movement.
+- Regression fixtures: the complete setter/reducer/keyed/component matrix.
+- Decision: reject broader consolidation.
+
+### Derived Diagnostic Rewording
+
+- Producers: `collectionExpression()` and caller string rewrites.
+- Consumers: reactive JSX/imported-calculation diagnostics.
+- Duplicate decision: presentation wording, not semantic analysis.
+- Required diagnostics: authored role plus exact parser reason.
+- Enabled deletion: none without adding a formatter API.
+- Expected delta: 0 to +5 LOC.
+- Regression fixtures: reactive JSX, Derived, and selector negatives.
+- Decision: defer to 06C only if diagnostics require it.
+
+### Route Dependency Denormalization
+
+- Producers: EffectIR analysis, transformed effect ABI, and route rendering.
+- Consumers: RouteIR, effect codegen, and capability planning.
+- Duplicate decision: source references become route IDs only after repeated and
+  conditional execution; these are different authority levels.
+- Required diagnostics: authored dependency and concrete route ownership errors.
+- Enabled deletion: none without a new ownership projection.
+- Expected delta: 0 or positive; architecture risk is high.
+- Regression fixtures: every dependency, keyed, conditional, and navigation suite.
+- Decision: reject.
+
+## First 06B Result
+
+One `materializeComponentHelper()` now owns the shared compiler-only effect
+rewrite, source retention, helper registration, setter/state-owner maps, and
+capability flags. Object-property and setter callers retain distinct diagnostics
+and prepend-versus-replace render shapes.
+
+```text
+Production files changed:       1
+Core semantic LOC:              5,296 -> 5,271 (-25)
+Passes / normalization entries: 0 / 0
+IR kinds / runtime concepts:    0 / 0
+Accepted source / diagnostics:  unchanged
+```
+
+Artifact comparisons are byte-identical:
+
+| Fixture | Files | Deploy SHA-256 | JS raw / gzip |
+|---|---:|---|---:|
+| WorkLedger object prop | 13 | `31886797161a33150afb3bcbf697545afd9d2041a4968decd33146e68d4b7595` | 37,302 / 14,083 B |
+| Array prop effect sync | 10 | `5e3bd8413e3d42c54e5c50d7098aa5c383e73846f7ad80201c663eae92393ec5` | 21,172 / 8,251 B |
+
+Verification passes `npm run check`, all 245 Node tests, all 245 required-Chrome tests, and fresh-install package smoke. The maintained Worker/effect benchmark remains 907 raw / 477 gzip B for Worker and 13,786 raw / 5,931 gzip B for the window graph; seven same-target builds have a 444.7 ms median, with no timing claim.
+
+## Second 06B Result
+
+The primitive debounce and array setter-effect checks now consume the existing
+`directStateInitializer()` lookup and retain their caller-owned primitive/array
+restrictions. The two duplicate component-body scans are deleted. The shared
+lookup still accepts only one direct `useState()` declaration with a serializable
+literal, so source acceptance and diagnostics are unchanged.
+
+```text
+Production files changed:       1
+Core semantic LOC:              5,271 -> 5,264 (-7)
+Total 06B deletion:             5,296 -> 5,264 (-32)
+Core LOC above 0.8.62:          +303
+Passes / normalization entries: 0 / 0
+IR kinds / runtime concepts:    0 / 0
+```
+
+| Fixture | Files | Baseline and candidate deploy SHA-256 | Baseline and candidate JS raw / gzip |
+|---|---:|---|---:|
+| Parameterized debounce | 13 | `b7106651c6a619b01a3e98101df4ac68f9262803e6729451ef03ed3971b36dc7` | 16,053 / 7,735 B |
+| Array prop effect sync | 10 | `5e3bd8413e3d42c54e5c50d7098aa5c383e73846f7ad80201c663eae92393ec5` | 21,172 / 8,251 B |
+
+Verification again passes `npm run check`, all 245 Node tests, all 245
+required-Chrome tests, and package smoke. The maintained Worker/effect graph
+remains 907 raw / 477 gzip B for Worker and 13,786 raw / 5,931 gzip B for the
+window graph. Seven same-target builds have a 507.7 ms median; this is a
+completion diagnostic, not a timing comparison.
+
+## Diagnostic Audit
+
+The preceding commit and final candidate were built against six invalid
+fixtures. All six fail with the same authored relative file, line, column, and
+message after path normalization; only internal stack-frame line numbers move:
+
+| Fixture | Stable authored diagnostic |
+|---|---|
+| Object property dynamic path | `src/DynamicView.tsx:4:24 useEffect() object property dependencies require a direct static property path` |
+| Object property alias | `src/AliasView.tsx:4:17 Object-property component property aliases are not supported; read the static prop.field path directly at each consumer` |
+| Object property mutation | `src/MutationView.tsx:3:28 Object-property component props must remain immutable` |
+| Setter effect indirect call | `src/Dropdown.tsx:6:5 Setter-callback prop "setSelectedItems" must be called directly inside an intrinsic event handler` |
+| Setter effect mismatched pair | `src/pages/index.tsx:7:50 Setter-callback effect prop "setSelectedItems" must target the same direct array state passed through "selectedItems"` |
+| Parameterized debounce delay | `src/pages/index.tsx:7:45 Parameterized debounce hook delays must be numeric literals` |
+
+No generated `.kudzu` path is primary, no fallback is added, and no diagnostic
+formatter or abstraction is justified.
+
+## Final Complexity Review
+
+The 0.9 candidate retains ten Semantic Kernel concepts, ten indexed ModuleIR
+record kinds, five post-normalization compiler stages, fifteen page/fourteen
+imported normalization entries, and ten browser runtime concepts. Compatibility
+LOC falls by 9. Session 06 closes at 5,264 core semantic lines after removing 32
+lines. The later Work Item 07 scaling paths add 53 lines, so the current
+candidate is 5,317 lines, up 356 from 0.8.62. Existing capability families gain
+bounded lifecycle specialization; the semantic-codegen/browser-runtime file set
+is 2,854 lines and the frozen C2 graph is 1,705 raw / 589 gzip B
+above its first complete acceptance run and adds no runtime concept.
+
+The increase is bounded to existing records and consumers: zero semantic
+concepts, IR kinds, passes, normalization entries, runtime concepts, public APIs,
+or generic browser runtimes were added. The candidate ledger found no further
+deletion that does not move source-specific proof or weaken ownership. This
+closes Work Item 06 without authorizing another abstraction.
+
+The maintained public storefront completes the scaling gate against preceding
+commit `bb7fdc5` with one warm-up and seven alternating clean builds per size:
+
+| Products | Pages / files | Output bytes | Baseline / candidate median |
+|---:|---:|---:|---:|
+| 100 | 111 / 148 | 1,368,823 | 2,767.3 / 2,755.4 ms |
+| 1,000 | 1,011 / 1,048 | 10,164,835 | 8,407.7 / 8,190.3 ms |
+| 10,000 | 10,011 / 10,048 | 97,521,905 | 63,966.5 / 64,217.4 ms |
+
+Every baseline/candidate manifest and byte count is identical. Distributions
+overlap, so no timing change is claimed; raw samples are in `PERFORMANCE.md`.

package/docs/next-architecture/0.9-final-proof-audit.md

@@ -0,0 +1,176 @@
+# Kudzu 0.9 Final Proof Audit
+
+## Status
+
+Work Item `0.9.0-07` is complete as of 2026-08-20. The measured candidate is
+the release commit containing this audit.
+
+Benchmark source remains local and ignored by project policy. The final audit
+therefore records commands, versions, acceptance, artifacts, and candidate
+revision in tracked documentation rather than committing benchmark fixtures.
+The complete comparison passes.
+
+## Local Harness Policy
+
+`.gitignore` intentionally excludes the complete `benchmarks/` tree. Benchmark
+source, dependencies, generated output, and raw local files must not be committed.
+Only accepted protocol, environment, candidate revision, and results belong in
+tracked architecture/performance records.
+
+The current local dependency set resolves React 19.2.8, Vue 3.5.40, Svelte
+5.56.7, Astro 7.1.3, Vite 8.1.5, Next.js 16.2.11, Nuxt 4.5.0, and SvelteKit
+2.70.1. Final evidence must restate these exact versions.
+
+The public commerce repository is independently pinned at
+`f2d5be1a516c539e30f7125f6870d42b1dd02ecd`, but its package lock references
+Kudzu 0.8.15 and candidate testing depends on an untracked manual symlink. Its
+three-sample sequential scale command also does not meet the final seven-sample
+rotating protocol. The repository-owned paired runner compares Kudzu revisions,
+not frameworks.
+
+## Matrix Gaps
+
+| Required application | Available local evidence | Release blocker |
+|---|---|---|
+| Content | Local Kudzu/React/Vue/Svelte/Astro five-route C1 acceptance passes | None; native disclosure reaches 0 B route/session JavaScript for every target. |
+| Stateful | Local five-target matrix passes seven rotating builds/browser profiles, complete frozen C2 acceptance, and uniform artifact/CPU/heap/transfer/build-RSS fields | None; final row filter/restore and search restore medians pass. |
+| Commerce | Kudzu/Astro generated storefront passes acceptance and seven rotating 10,000-product cold/warm runs | None; build time and peak RSS pass. |
+| Resource | Local five-target Worker/navigation matrix passes seven rotating builds/browser profiles, complete frozen C5 acceptance, and uniform artifact/CPU/heap/transfer/build-RSS fields | No acceptance or metric-field gap remains; timing conclusions still follow the statistical gate. |
+
+The C2/C5 suites now collect actual transferred and unique session JavaScript,
+preload graphs, fresh-process peak RSS, script execution cost, post-journey and
+repeated-disposal heap, deterministic digests, and interleaved builds. Chrome's
+`V8CompileDuration` remains zero for most targets, so separately attributable
+parse CPU would require a trace; `ScriptDuration` remains the uniform execution
+measure.
+
+## C1 Content Acceptance
+
+The local C1 suite builds `/`, `/article/example`, `/category/example`, `/about`,
+and `/static` for Kudzu, React, Vue, Svelte, and Astro. Every target passes:
+
+- complete initial HTML, metadata, landmarks, headings, native links, code, and accessible SVG;
+- build-known `example` route content, local image/font assets, and article-only CSS;
+- labelled disclosure behavior and observable state;
+- JavaScript-disabled content plus native `/about` navigation;
+- readable article content when the required script is missing;
+- zero JavaScript on `/static`.
+
+Environment: Node 24.14.0, Chrome 142.0.7444.175, Linux x64. This was one
+acceptance build per target, not a timing benchmark.
+
+The first version used state-backed disclosure and exposed an 11,348 B Kudzu
+route graph versus 410 B inline Astro JavaScript. Replacing every implementation
+with native `<details>/<summary>` preserves acceptance and reaches 0 B route and
+session JavaScript for every target.
+
+| Target | Files | Total bytes | Deployed / session JS | Deploy SHA-256 |
+|---|---:|---:|---:|---|
+| Kudzu | 9 | 8,441 | 0 / 0 B | `49d1fa4e9c46e7e960e38d07130aa1f0d488f2d8c350ebec05d53ab78941d755` |
+| React | 10 | 197,444 | 191,123 / 0 B | `95638a81350d5a3fa1fb1329e3c0d7e9cec5267f6fa2ac0ff5b54006f280d319` |
+| Vue | 10 | 70,840 | 64,519 / 0 B | `96be755a12e6c733d20679043b0387353f3d9d3f873a57136f5f93e194e891ce` |
+| Svelte | 10 | 32,768 | 26,447 / 0 B | `447d186ac55eba9fd6f9b20f75608e83ebd757f840dc19de99fa7ba2ab366375` |
+| Astro | 7 | 8,680 | 0 / 0 B | `e75073eb394393aa636c6efab17c26fe8995113f1c9d79d4e02357990834940b` |
+
+## Stateful And Capability Runs
+
+Astro 7.1.3 React-island variants join React 19.2.8, Vue 3.5.40, Svelte 5.56.7,
+and Kudzu in the local runtime and capability matrices. One warm-up, seven
+rotating builds, and seven fresh rotating Chrome profiles pass for all five
+targets.
+
+The C2 matrix now proves immutable object replacement, multi-state derived
+output, keyed 1,000-row local state/effect/ref ownership, filter/restore,
+conditional child cleanup and fresh remount, accessible SVG keyboard state, a
+zero-JavaScript static sibling, and blocked/delayed/missing-JavaScript behavior.
+Kudzu emits 41,862 raw / 15,819 gzip B JavaScript versus 196,089 / 60,661 B
+React and 197,771 / 61,994 B Astro+React. All 19 operations and ownership checks
+pass in every profile.
+
+The C5 matrix now proves dependency replacement, invalidation before cleanup,
+late-callback suppression, 30 conditional mount/dispose cycles, exact listener
+removal and Worker termination, flat final active handles, accessible output,
+zero-resource-JavaScript static siblings, and blocked/delayed/missing-JavaScript
+behavior. Every target records 32 balanced starts, invalidations, listener
+removals, terminations, and ignored stale callbacks with zero stale mutations.
+Kudzu's Worker graph is 17,639 raw / 8,189 gzip B versus 193,422 / 60,159 B
+React and 195,108 / 61,493 B Astro+React. Uniform artifact, transfer, preload,
+build-RSS, script CPU, heap, digest, and environment fields are recorded.
+
+The final 21-profile C2 measurements close the browser release gate. Row-local
+ref resolution, synchronous cleanup, per-list lifecycle gating, shared
+list-item and ownership-path maps, item-dependency transport gating, structural
+row fill/ID plans, row-state release cleanup, and boolean-toggle specialization
+reduce row filter from 34.6 to 12.0 ms, ownership-heavy row restore from 208.6
+to 62.6 ms, and search restore from 77.5 to 51.6 ms. Row filter is faster than
+Vue's 13.3 ms; row restore and search restore are within 3.5% and 1.8% of their
+nearest comparator medians of 60.5 and 50.7 ms. C5 repeated Worker processing, reconnect, 30-cycle
+ownership, cleanup, heap, and active-handle measurements have no comparable
+acceptance gap.
+
+This optimization adds no semantic primitive, ModuleIR kind, compiler pass,
+normalization entry, runtime concept, or public API, and changes zero measured
+core semantic concepts or passes. Core semantic LOC grows from 5,311 to 5,317
+for async production compilation, while the semantic-codegen/browser-runtime
+file set grows from 2,771 to 2,854 lines. C2 deploy JavaScript is 43,567 raw /
+16,408 gzip B while generated row command HTML and measured ownership work fall;
+the frozen fixture count is unchanged.
+
+## Commerce Scaling
+
+The public storefront was linked to the current candidate and compared with
+Astro using acceptance before timing, generated source/assets outside the timed
+interval, one warm-up, 21 rotating cold builds, 21 rotating warm builds, peak
+RSS, actual route counts, output bytes, and deterministic manifests.
+
+| Products | Target | Routes | Cold / warm median | Peak RSS median | Output bytes |
+|---:|---|---:|---:|---:|---:|
+| 100 | Kudzu | 111 | 3,317 / 3,552 ms | 363,492 KiB | 1,368,823 |
+| 100 | Astro | 111 | 3,558 / 3,710 ms | 330,252 KiB | 2,070,726 |
+| 1,000 | Kudzu flattened input | 1,011 | 2,949 / 2,964 ms | 264,600 KiB | 10,057,806 |
+| 1,000 | Astro | 1,011 | 3,835 / 3,845 ms | 408,100 KiB | 14,896,056 |
+| 10,000 | Kudzu flattened input | 10,011 | 22,614 / 22,151 ms | 542,484 KiB | 96,379,876 |
+| 10,000 | Astro | 10,011 | 23,198 / 23,438 ms | 612,412 KiB | 142,543,510 |
+
+The fixture's preparation phase emits flattened page props and bounded collection
+rows instead of compiling an unused 37 MiB nested catalog literal. Kudzu is
+23.1%/22.9% faster cold/warm than Astro at 1,000 products and 2.5%/5.5%
+faster at 10,000 products. The 10,000-product output digest is
+`811234693329ebd61eeceb6cd05e5d52473e5c81972a820253bf1aea664a0910`.
+One-shot CLI builds intern repeated RouteIR descriptors, update validated records
+in place, spool rendered HTML to staging until runtime families are known, stream
+the unchanged pretty plan, and release standalone plans after serialization.
+Peak RSS falls 71.0% to 542,484 KiB, 11.4% below Astro's 612,412 KiB. Dev,
+incremental, navigation, `afterBuild`,
+the 135 MiB plan, and the 31 MiB artifact report retain their evidence contracts.
+The retained-render and staged-HTML changes add no
+semantic primitive, pass, runtime concept, public API, browser byte, or fixture;
+the commerce output digest is unchanged by that deletion.
+
+## Stale Results
+
+The runtime raw file identifies revision `468372b` with the production changes
+uncommitted, while the capability raw file identifies `f213e73`; both record
+their exact ignored benchmark source hashes. Other ignored result files still
+identify older candidates:
+
+| Suite | Recorded Kudzu |
+|---|---:|
+| Calculated SVG | 0.8.1 |
+| Commerce desktop | 0.6.13 |
+| Commerce mobile | 0.5.10 |
+
+They cannot establish the 0.9 candidate or be presented as checked-in evidence.
+
+## AI Migration Handoff
+
+Model-driven success rate and cost belong to the 1.0 AI Delivery Protocol Seed,
+not the 0.9 browser/build release gate. No model result is fabricated for 0.9.
+
+## Completion
+
+1. The 10,000-route peak-RSS loss is closed without dropping route-plan or artifact evidence.
+2. Seven rotating 10,000-product cold and warm samples pass build-time, RSS, acceptance, and deterministic-output gates.
+3. Model-driven AI migration measurement remains in the 1.0 work item.
+
+The 0.9 final-proof gates are closed.