@kudzujs/core 0.8.61 → 0.9.0

package/docs/next-architecture/0.9-benchmark-contracts.md

@@ -0,0 +1,507 @@
+# Kudzu 0.9 Cross-Framework Benchmark Contracts
+
+## Status
+
+This document completes `0.9.0-01 / Session 01F`. It freezes comparison semantics before additional competitive timing is accepted.
+
+```text
+Contract revision: 1
+Production baseline: bada14585d112de8debf75a2bf914e9d5e0769ed
+External commerce fixture: f2d5be1a516c539e30f7125f6870d42b1dd02ecd
+Status: active contract; implementation gaps are explicit below
+```
+
+A benchmark implementation may improve, but changing required content, behavior, accessibility, routes, or degradation expectations requires updating this contract before collecting replacement results.
+
+## Governing Rule
+
+A timing or byte sample counts only after that variant passes the scenario's acceptance checks.
+
+```text
+same content
++ same data
++ same routes
++ same behavior
++ same accessibility
++ same hosting assumptions
++ same browser conditions
+= comparable sample
+```
+
+A framework may use its idiomatic production configuration. It may not remove behavior, data, validation, accessibility, error handling, navigation steps, or resource cleanup to reduce cost.
+
+## Shared Environment Contract
+
+| Field | Requirement |
+|---|---|
+| Source revision | Exact immutable Git commit per fixture and framework variant |
+| Package versions | Exact lockfile resolution, not package ranges alone |
+| Node/package manager | Exact versions recorded with raw results |
+| Browser | Exact Chrome/Chromium version and launch flags |
+| Hardware | CPU model, logical CPUs, memory, OS, and architecture |
+| Server | Same local static-server implementation and headers per scenario |
+| Compression | Raw, per-file gzip, and actual browser transfer where applicable |
+| Cache | Explicit fresh-context, cold-cache, or in-session warm-cache state |
+| Network | No throttle, Fast 4G, or Slow 4G profile recorded exactly |
+| CPU | No throttle or exact CDP throttle rate |
+| Viewport | Fixed per scenario; default commerce viewport is 1280 x 900 |
+| Build cleanup | Exact output and framework-cache deletion rules |
+| Sample order | Rotating or interleaved across variants |
+| Warm-up | At least one discarded warm-up per target/size |
+| Runs | At least seven; at least twenty-one when evidence overlaps or remains unstable |
+| Failures | Recorded as failures; never dropped from the denominator silently |
+
+## Shared Success Rules
+
+Every variant must pass before timing:
+
+- production build exits successfully;
+- expected route count or documented route set exists;
+- direct entry returns complete expected content;
+- browser reports no uncaught exception;
+- required JavaScript and asset requests return expected statuses in the ordinary run;
+- accessible names, roles, states, labels, errors, focus, and keyboard behavior pass;
+- every required interaction changes the specified observable result;
+- back/forward and native fallback behavior match the scenario contract;
+- resource acquisition and cleanup balance where applicable;
+- deterministic fixture data and expected values match.
+
+## Shared Measurement Contract
+
+### Artifacts
+
+- complete deploy file count;
+- emitted HTML page count;
+- HTML raw and gzip bytes;
+- CSS raw and gzip bytes;
+- JavaScript raw and gzip bytes;
+- other non-image artifact bytes;
+- actual browser-fetched JavaScript by route;
+- unique JavaScript transferred during the full session;
+- output path manifest and deterministic digest where architecture permits;
+- hydration/runtime bootstrap markers;
+- static-route JavaScript count and bytes.
+
+### Browser
+
+- content readiness from navigation start;
+- action readiness proven by a successful action;
+- event-to-next-paint latency;
+- navigation content and action readiness;
+- impatient interaction loss by delay after first paint;
+- script parse/execute time;
+- main-thread work where trace collection is available;
+- heap after load, after journey, and after repeated navigation/disposal;
+- browser exceptions and failed requests.
+
+### Build
+
+- cold build raw samples and median;
+- warm-cache build raw samples and median;
+- incremental development build where supported;
+- peak RSS;
+- actual emitted route count;
+- milliseconds per emitted route;
+- output files and bytes;
+- source-read, graph, compile, render, and emit phases where instrumentation exists.
+
+### Resilience
+
+- JavaScript fully blocked;
+- JavaScript responses delayed two seconds;
+- one required JavaScript response returns 404;
+- Slow 4G;
+- 4x CPU throttle;
+- navigation request failure where the application has enhanced navigation.
+
+## Statistical Contract
+
+Deterministic bytes have no statistical tie. Fewer bytes wins.
+
+Timing conclusions require:
+
+- rotating or interleaved target order;
+- raw samples published;
+- median and range published;
+- paired differences when targets are measured in paired rounds;
+- at least seven samples;
+- at least twenty-one samples when ranges overlap or the conclusion is unstable;
+- no established median loss greater than the 5% materiality threshold for a claimed tie;
+- an uncertainty method stated before final release claims.
+
+No weighted aggregate may hide a primary-metric loss.
+
+## Comparator Set
+
+| Class | Required framework |
+|---|---|
+| Primary migration baseline | React + Vite |
+| Client framework | Vue |
+| Compiler framework | Svelte |
+| HTML-first/static framework | Astro |
+| Production route framework | Capability-appropriate Next.js, React Router, TanStack, Nuxt, or SvelteKit variant |
+
+Not every framework must appear in every scenario when the scenario is inapplicable, but React + Vite, Vue, Svelte, and Astro must each appear in at least one content or stateful matched scenario before `0.9.0`.
+
+## Contract C1: Content Application
+
+### Purpose
+
+Prove complete HTML, static-route zero JavaScript, route-specific CSS/assets, metadata, native links, one small enhancement, and failure resilience without using a state-heavy benchmark.
+
+### Status
+
+```text
+Contract: frozen
+Local multi-framework acceptance: passes for Kudzu, React, Vue, Svelte, and Astro
+Release use: native disclosure reaches the zero-byte JavaScript floor; scale/timing evidence remains incomplete
+```
+
+### Required Variants
+
+```text
+Kudzu
+React + Vite with matched static/SSR delivery
+Vue
+Svelte
+Astro
+```
+
+### Required Route Set
+
+```text
+/
+/article/example
+/category/example
+/about
+/static
+```
+
+Equivalent paths may be used only if every variant uses the same paths.
+
+### Required Content
+
+- site header and native navigation;
+- metadata title and description;
+- route-owned stylesheet plus shared global stylesheet;
+- local image/font assets;
+- article headings, paragraphs, code, links, and one accessible SVG;
+- one locale or route parameter known at build time;
+- one clipboard, tab, disclosure, or similarly small enhancement;
+- one completely static sibling route.
+
+### Acceptance
+
+- every route has complete meaningful HTML before JavaScript;
+- heading hierarchy and landmarks match;
+- native links work with JavaScript blocked;
+- article and static sibling remain readable with missing JavaScript;
+- enhancement has an accessible label and status result;
+- route-specific CSS does not leak into unrelated routes;
+- static sibling fetches zero JavaScript in Kudzu;
+- metadata and canonical route content match.
+
+### Measurements
+
+- route HTML/CSS/JS and session JavaScript;
+- content readiness;
+- enhancement action readiness and latency;
+- native navigation under ordinary/blocked/delayed JavaScript;
+- cold/warm build for 100, 1,000, and 10,000 generated articles where practical;
+- peak RSS and output bytes.
+
+## Contract C2: Stateful Runtime Matrix
+
+### Purpose
+
+Compare direct state, derived values, keyed ownership, effects, component boundaries, forms, and cleanup without the scale noise of a full catalog.
+
+### Status
+
+```text
+Contract: frozen
+Historical runtime matrix evidence: documented
+Maintained tracked harness in this checkout: missing
+Vue/Svelte/Astro current variants: missing
+Release use: blocked until restored
+```
+
+### Required Variants
+
+```text
+Kudzu
+React + Vite
+Vue + Vite
+Svelte + Vite
+Astro with the minimum framework integration required for matched behavior
+```
+
+### Required UI
+
+- two primitive state controls;
+- one immutable object state value;
+- one multi-state derived display;
+- one keyed 1,000-row collection with local row state;
+- filter, append, reverse, remove, and restore actions;
+- one controlled form property;
+- one conditional child with mount effect and cleanup;
+- one accessible SVG conditional or keyed row;
+- one static sibling route.
+
+### Acceptance
+
+- state setters/actions preserve each framework's documented semantics while observable results match;
+- retained keyed rows preserve DOM identity;
+- removed rows release local state/effects/refs;
+- restored rows initialize fresh state;
+- derived output matches after every operation;
+- effect cleanup precedes replacement setup;
+- conditional removal cleans up once and remount initializes fresh ownership;
+- keyboard and accessible-state behavior match;
+- static sibling content and zero-JavaScript Kudzu result pass;
+- no uncaught errors.
+
+### Measurements
+
+- initial and session JavaScript;
+- content/action readiness;
+- append/filter/restore/reverse event-to-next-paint;
+- CPU trace and heap before/after repeated operations;
+- build time and output bytes;
+- blocked/delayed/missing-JavaScript behavior.
+
+## Contract C3: Stateful Commerce Journey
+
+### Purpose
+
+Measure realistic content, navigation, filtering, sorting, multi-state variant selection, shared cart behavior, and checkout under one deterministic storefront.
+
+### Pinned Fixture
+
+```text
+Repository: SimYunSup/kudzu-based-bench
+Revision: f2d5be1a516c539e30f7125f6870d42b1dd02ecd
+Current status: reproducible baseline; protocol updates require a new pinned revision
+```
+
+### Current Variants
+
+```text
+shop-kudzu
+shop-astro
+shop-react-router
+shop-tanstack
+shop-next-app
+```
+
+### Required Routes
+
+```text
+/
+/search/
+/search/outerwear/
+/product/p-00000/
+/product/p-00002/
+/shipping/
+/checkout/
+```
+
+### Required Data
+
+- deterministic product IDs and handles;
+- deterministic title, price, collection, variant, availability, image, tag, and update data;
+- identical catalog size per run;
+- same listing limit and displayed products;
+- same base path and local assets.
+
+### Required Session
+
+1. Direct product entry with an empty browser cache.
+2. Navigate to listing.
+3. Sort by price and verify ascending semantic result.
+4. Filter by the fixed Korean query and verify every retained title.
+5. Navigate to a second product.
+6. Select an available variant and verify price/selected state.
+7. Add to cart and verify visible confirmation/shared state.
+8. Navigate to checkout and verify content.
+
+### Accessibility Acceptance
+
+- one visible `h1` per route;
+- product options grouped and named;
+- selected option exposes a semantic selected/pressed state;
+- unavailable options are disabled;
+- filter and sort controls have labels;
+- add-to-cart control has an accessible name;
+- confirmation is available to assistive technology;
+- focus remains usable after interaction and navigation;
+- native links remain traversable under blocked JavaScript.
+
+### Progressive Enhancement Acceptance
+
+| Condition | Required minimum |
+|---|---|
+| JavaScript blocked | Product content, category navigation, product detail entry, policy, and checkout content remain available |
+| JavaScript delayed two seconds | Complete content and native navigation remain available; interactions eventually activate without lost state corruption |
+| One JavaScript response missing | Content and unrelated native navigation remain available; failed enhancement is observable and does not corrupt later pages |
+
+The final comparison reports each capability separately rather than converting resilience into one opaque score.
+
+### Measurements
+
+- browser-fetched JS on home, search, collection, product, policy, and checkout;
+- unique session JS;
+- content readiness at entry/list/detail/checkout;
+- action readiness and latency for sort/filter/variant/cart;
+- impatient-click loss from first paint plus 0–5,000 ms;
+- CPU/heap across the full session;
+- navigation timing;
+- degradation capability matrix;
+- output files/bytes and build scaling.
+
+## Contract C4: Catalog Build Scaling
+
+### Purpose
+
+Prove that static specialization scales without transferring route work to the browser.
+
+### Sizes
+
+```text
+100 products
+1,000 products
+10,000 products
+```
+
+### Required Variants
+
+```text
+Kudzu
+Astro
+best applicable production static exporter from the commerce matrix
+```
+
+All five commerce variants should run when the host and build architecture support the size. Unsupported size/variant pairs remain explicit failures or inapplicable results.
+
+### Required Protocol Upgrade
+
+The current external `shop:scale` script must be updated in a new pinned revision to provide:
+
+- actual emitted route count;
+- one warm-up per target and size;
+- at least seven rotating samples;
+- cold and warm-cache builds;
+- peak RSS;
+- files, pages, and artifact-class bytes;
+- deterministic manifest/digest where possible;
+- correctness acceptance before timing;
+- milliseconds per emitted route rather than requested product count;
+- raw samples and failures.
+
+### Acceptance
+
+- every expected product route exists;
+- representative first/middle/last product content matches input data;
+- listing and policy routes exist;
+- JavaScript bytes do not scale with static product count except where route-specific files are independently requested;
+- complete HTML remains emitted;
+- no client fetch replaces build-known catalog generation.
+
+## Contract C5: Resource Ownership
+
+### Purpose
+
+Compare imperative resource behavior and cleanup without creating a generic resource runtime.
+
+### Status
+
+```text
+Contract: frozen
+Kudzu Worker/effect fixture: available
+Matched React/Vue/Svelte/Astro resource variants: missing
+Release use: blocked until fixture family exists
+```
+
+### Required Resource Scenario
+
+- one Worker or WebSocket-like transport;
+- one route or conditional owner;
+- one dependency replacement or reconnect;
+- one listener/subscription;
+- one bounded result collection or canvas update;
+- one exact cleanup path;
+- one late callback after owner release;
+- one static sibling.
+
+### Acceptance
+
+- resource starts only after its owner mounts;
+- replacement invalidates the prior owner before cleanup;
+- listener removal and terminate/close/disconnect happen exactly once;
+- late callback cannot mutate replacement ownership;
+- repeated navigation/mount cycles do not increase active handles/listeners;
+- static sibling requests no resource code;
+- application output and accessibility remain usable.
+
+### Measurements
+
+- initial and route-specific JavaScript;
+- Worker/resource graph bytes;
+- action/content readiness;
+- message-to-paint latency;
+- CPU and heap over at least 30 mount/dispose cycles;
+- active listener/handle balance;
+- build and output cost.
+
+## Current Contract Implementation Matrix
+
+| Contract | Kudzu | React | Vue | Svelte | Astro | Production router set |
+|---|---|---|---|---|---|---|
+| C1 Content | Application candidates exist; matched harness missing | Missing current matched variant | Missing | Missing | Candidate exists | Optional |
+| C2 Stateful runtime | Historical/current fixtures exist; tracked matrix missing | Historical evidence | Historical evidence | Historical evidence | Missing | Not required |
+| C3 Commerce | Reproduced | Through React Router/Next/TanStack | Not required in this contract | Not required in this contract | Reproduced | Reproduced |
+| C4 Scale | 100/1,000 baseline paths available | Production variants available | Not required | Not required | Available | Available |
+| C5 Resource | Worker/effect fixture available | Missing matched variant | Missing | Missing | Missing | Optional |
+
+This matrix prevents the 100-product commerce asset result from being presented as the complete 0.9 cross-framework proof.
+
+## Raw Result Publication Contract
+
+Final result storage must include:
+
+```text
+scenario contract revision
+fixture repository and commit
+framework lockfile
+environment JSON
+acceptance result per variant
+raw timing samples
+failed attempts
+artifact manifest
+browser request log or summarized raw response data
+CPU/heap trace references
+resilience result per capability
+known limitations
+```
+
+Summary tables may be generated from raw data. Raw failures and primary metrics cannot be deleted because they make a summary unfavorable.
+
+## 01F Completion Record
+
+| Deliverable | Result |
+|---|---|
+| Shared environment contract | Frozen |
+| Shared acceptance contract | Frozen |
+| Artifact/browser/build/resilience metrics | Frozen |
+| Statistical rules | Frozen |
+| Content contract | Frozen; implementation gap explicit |
+| Stateful runtime contract | Frozen; tracked harness gap explicit |
+| Commerce contract | Frozen against pinned external fixture |
+| Scale contract | Frozen; protocol upgrade required |
+| Resource contract | Frozen; comparator fixture gap explicit |
+| Anti-gaming rules | Frozen |
+| Raw result contract | Frozen |
+
+## Next Step
+
+`0.9.0-01` remains the signed baseline and every explicit harness gap carries forward. `0.9.0-02` closed the Derived slice with pinned Medusa Product Actions and Mercury Profit Sharing reductions; `0.9.0-03` unified reduced Context and Zustand action semantics without changing deploy bytes. Session 04A is next. Final cross-framework use of these contracts remains blocked on the tracked harness gaps above.

package/docs/next-architecture/0.9-component-property-contract.md

@@ -0,0 +1,89 @@
+# Kudzu 0.9 Component Property Contract
+
+## Status
+
+This contract completes `0.9.0-05 / Session 05B` for the pinned WorkLedger
+conversation fixture. It defines analysis authority before producer or consumer
+changes.
+
+## Authorizing Edge
+
+```text
+parent Conversation SignalIR
+  -> direct conversation prop
+     -> static label binding
+     -> static messages effect dependency
+     -> static messages keyed collection
+```
+
+The parent object remains one logical state value. A property link is analysis
+metadata, not a mutable field signal.
+
+## ComponentAnalysis Record
+
+Each directly supplied state prop may record property links inside its existing
+specialization prop entry:
+
+```json
+{
+  "name": "conversation",
+  "local": "conversation",
+  "signals": [0],
+  "properties": [
+    {
+      "signal": 0,
+      "path": ["label"],
+      "consumers": ["binding"],
+      "equality": "object-is"
+    },
+    {
+      "signal": 0,
+      "path": ["messages"],
+      "consumers": ["effect", "list"],
+      "equality": "object-is"
+    }
+  ]
+}
+```
+
+The containing specialization is the owner. `signal` must reference the same
+parent `SignalIR` already recorded in `signals`. `path` contains exactly one
+static segment and excludes `__proto__`, `prototype`, and `constructor`. Consumers are limited
+to `binding`, `effect`, and `list`.
+
+## Consumer Contract
+
+- Binding: reuse `BindingIR` and its source-signal evaluator. No component
+  rerender or field state is created.
+- Effect: encode the selected path as existing expression `DerivedIR`, subscribe
+  to the parent signal, and compare the selected value with `Object.is`.
+- List: reuse a binding-backed `KeyedBlockIR` collection and its existing
+  compiler-owned array anchor. Skip reconciliation when the selected array is
+  `Object.is`-equal to the previous value.
+- Ownership: repeated and conditional calls retain their existing
+  specialization, conditional, effect, and keyed owners. Property links do not
+  own browser lifetime.
+
+Array-valued selected dependencies are allowed for this immutable collection
+case. Calculation-result dependencies remain primitive-only. A selected list
+value must remain an array on every update.
+
+## Rejected Boundary
+
+- computed or dynamic property names;
+- unsafe property names;
+- property aliases used as collection or dependency roots;
+- whole-object effect dependencies mixed with selected properties;
+- object or array mutation;
+- object expressions or opaque spreads at the component call site;
+- property links from a prop that is not one direct parent state identifier;
+- arbitrary callbacks or a browser component runtime.
+
+## Cost
+
+```text
+Semantic primitives added:       0
+ModuleIR record kinds added:      0
+Runtime concepts added:           0
+Authored field states added:      0
+```