@esportsplus/reactivity 0.31.3 → 0.32.0

package/.claude/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## Completed
+- [relocate-benchmarks] 567bd82. Relocate 7 benches to bench/ mirror + config, delete tests/ — landed by direct-implement after blocked run 36ee71d0 (harness gate false-block: depless worktrees, issue 20260720T141515Z). Gate: pnpm agent:test green (tsc --noEmit + 369 tests), benches discover 7. · spec: spec-coding-standards
+- [relocate-test-suites] 26fa1017. Relocate 23 suites to test/ mirror + config — landed by direct-implement after blocked run 36ee71d0 (harness gate false-block: depless worktrees, issue 20260720T141515Z). Gate: pnpm agent:test green (tsc --noEmit + 369 tests), benches discover 7. · spec: spec-coding-standards
+- [waitfor-test-helper] fa0a934a. waitFor/tick helper replacing 50 fixed-sleep sync sites — landed by direct-implement after blocked run 36ee71d0 (harness gate false-block: depless worktrees, issue 20260720T141515Z). Gate: pnpm agent:test green (tsc --noEmit + 369 tests), benches discover 7. · spec: spec-coding-standards
+- [compiler-import-order] 2610d50d. Normalize import order across compiler modules — landed by direct-implement after blocked run 36ee71d0 (harness gate false-block: depless worktrees, issue 20260720T141515Z). Gate: pnpm agent:test green (tsc --noEmit + 369 tests), benches discover 7. · spec: spec-coding-standards
+- [reactive-index-cleanup] 00b21810. reactive() facade unknown-bridges + import order — landed by direct-implement after blocked run 36ee71d0 (harness gate false-block: depless worktrees, issue 20260720T141515Z). Gate: pnpm agent:test green (tsc --noEmit + 369 tests), benches discover 7. · spec: spec-coding-standards
+- [reactive-array-cleanup] e0aa8b86. ReactiveArray listener typing, sort map, accessor order, imports — landed by direct-implement after blocked run 36ee71d0 (harness gate false-block: depless worktrees, issue 20260720T141515Z). Gate: pnpm agent:test green (tsc --noEmit + 369 tests), benches discover 7. · spec: spec-coding-standards
+- [system-any-casts] b890f047. Eliminate any casts in system.ts (unknown-bridged pool sentinels) — landed by direct-implement after blocked run 36ee71d0 (harness gate false-block: depless worktrees, issue 20260720T141515Z). Gate: pnpm agent:test green (tsc --noEmit + 369 tests), benches discover 7. · spec: spec-coding-standards
+- abandoned spend: ~$199.51 equivalent API cost across 7 terminal non-COMPLETED item(s) (system-any-casts, reactive-array-cleanup, reactive-index-cleanup, compiler-import-order, waitfor-test-helper, relocate-test-suites, relocate-benchmarks); recorded, not divided into per-item costs (run 36ee71d0)
+- run-level spend: ~$0.98 equivalent API cost (warm implementer runs + unit-scoped + boundary seats; never divided across items; blended rate = mean(input, output, cache_read, cache_creation) per million tokens) (run 36ee71d0)
+- [constants-export-order] 84f0b3613de0076e070ba4ddcd69c3e0d68a9f3a. Deviations: none; ladder: 3 attempts (critic → replanner completed → critic), completed. Cost: ~$20.03 equivalent API cost (blended-rate approximation). · spec: spec-coding-standards
+- [compiler-const-enum] 1b252cd2180063eefc04bf2b221ce4e9eff969a5. Deviations: none; ladder: 3 attempts (critic → replanner completed → critic), completed. Cost: ~$34.13 equivalent API cost (blended-rate approximation). · spec: spec-coding-standards
+- [types-variadic-any] da6b4873d4238db26d0d75f19a67f8c966a01b83. Deviations: none; ladder: 3 attempts (critic → replanner completed → critic), completed. Cost: ~$47.04 equivalent API cost (blended-rate approximation). · spec: spec-coding-standards
+- [reactive-object-cleanup] 769d007e46a9f6b0b299c2c3d48fa55dffe29628. Deviations: none; ladder: 3 attempts (critic → replanner completed → critic), completed. Cost: ~$32.61 equivalent API cost (blended-rate approximation). · spec: spec-coding-standards
+- cost source of truth: ccusage per-model breakdown (local transcripts carry the input/output/cache split the run journal does not) — figures above are a blended-rate approximation per contracts/models.json pricing (run 36ee71d0)
+- [recursion-free-walks] 143d5591. Recursion-free notify(), update(), and dispose()/unlink() walks — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next-2
+- [unobserved-hooks] b7a93aa4. onUnobserved() — last-subscriber lifecycle hook — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next-2
+- [invalidate] 60df87ae. invalidate() — standalone re-derivation of any computed — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next-2
+- [custom-equals] a4cb4e04. Custom equals on signal() and computed() — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next-2
+- follow-up discharged (completed) from spec-signals-next: pending-only-writes: complete full shape — selector recursive fan-out + nextPend… — evidence: 6a9b8e6
+- abandoned spend: ~$206.41 equivalent API cost across 4 terminal non-COMPLETED item(s) (custom-equals, invalidate, unobserved-hooks, recursion-free-walks); recorded, not divided into per-item costs (run 3306873d)
+- run-level spend: ~$2.11 equivalent API cost (warm implementer runs + unit-scoped + boundary seats; never divided across items; blended rate = mean(input, output, cache_read, cache_creation) per million tokens) (run 3306873d)
+- [async-iterable-resolve] 17b3878753d238869fdf6723dff468705d2795f8. Deviations: deviated — resolve()'s 'rejects when the tracked expression throws' was split into its own it() rather than combined into one test with the resolve-success case, matching the file's one-scenario-per-it convention from tests/async-hardening.ts; both scenarios from Design test 6 are covered.; added — Verified async generator .return() timing empirically (a queued return() on a generator suspended mid an unresolved internal await does not settle until that await resolves) via a throwaway Node script before writing tests 1-3, since the Design's prose doesn't spell out that an abandoned generator's pending gate must be released for its finally to run; tests 1-3 release the old generation's gate to observe closure, consistent with test 3's own description.; added — Added a gate()/tick() test-local helper pair (not in Design) to keep the generator-gating boilerplate readable across tests 1-5; mirrors async-hardening.ts's resolver-array convention.; ladder: 1 attempt (critic), completed. Cost: ~$16.19 equivalent API cost (blended-rate approximation). · spec: spec-signals-next-2
+- cost source of truth: ccusage per-model breakdown (local transcripts carry the input/output/cache split the run journal does not) — figures above are a blended-rate approximation per contracts/models.json pricing (run 3306873d)
+- abandoned spend: ~$229.74 equivalent API cost across 5 terminal non-COMPLETED item(s) (custom-equals, invalidate, unobserved-hooks, async-iterable-resolve, recursion-free-walks); recorded, not divided into per-item costs (run 2f191933)
+- run-level spend: ~$0.56 equivalent API cost (warm implementer runs + unit-scoped + boundary seats; never divided across items; blended rate = mean(input, output, cache_read, cache_creation) per million tokens) (run 2f191933)
+- [untrack-peek] 5d2a577c2b941bdc6fe869951c770ed3c12a82f8. Deviations: deviated — pull(node) extracted only the notified-broadcast + observer-nulled update() call (matching design's literal extraction target); drainPending() and the height>=heap_i||NOTIFY_MASK gate stay inline in read() exactly as before for byte-identical behavior.; deviated — peek() has no separate explicit NOTIFY_MASK pre-check before calling pull() — it always drains pending writes then calls pull(node) unconditionally for a STATE_COMPUTED node, relying on pull()'s internal notify-broadcast (which sets DIRTY/CHECK bits) plus update()'s own gv/CHECK/DIRTY branching to no-op cheaply when nothing changed. A literal external NOTIFY_MASK gate in peek() would check the bit *before* the broadcast that sets it, which never fires on a freshly-written-but-undrained dependency and would make peek() return stale values, contradicting Acceptance clause 3's 'up-to-date value for a dirty computed'. Verified via a dedicated test that peek() sees a fresh value synchronously right after write(), with 0 regressions across the full 343-test suite.; ladder: 1 attempt (critic), completed. Cost: ~$20.51 equivalent API cost (blended-rate approximation). · spec: spec-signals-next
+- [flush-batch] 3bc415d5568da53154f59a32069afaebfc381d04. Deviations: deviated — flush() implemented as `while (stabilizer === STABILIZER_SCHEDULED) stabilize();` instead of the Design's single `if`. Traced the RESCHEDULE path: a write() during an effect's recompute only flips stabilizer to RESCHEDULE and queues the *next* microtask when its subscriber's height is at or below the current heap_i already scanned in this pass (drain-before-scan only re-triggers on a later height iteration reached within the same for-loop) — a single stabilize() call leaves that tail unsettled until the next microtask, violating Acceptance clause 1's 'settles before flush() returns'. The while-loop drains it synchronously while still satisfying the no-op cases (RUNNING/RESCHEDULE/IDLE never equal SCHEDULED) and clause 4 (any stray queued microtask fires against an already-empty/IDLE state and no-ops).; ladder: 1 attempt (critic), completed. Cost: ~$11.27 equivalent API cost (blended-rate approximation). · spec: spec-signals-next
+- cost source of truth: ccusage per-model breakdown (local transcripts carry the input/output/cache split the run journal does not) — figures above are a blended-rate approximation per contracts/models.json pricing (run 2f191933)
+- follow-up discharged (completed) from spec-signals-next: read-version-dedup + pending-only-writes: stamp rv (+ nextPending on Signal entr… — evidence: 6a9b8e6
+- [cleanup-hardening] 14a40dd7. cleanup() hardening — run every disposer, never abort the batch — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next
+- [async-computed-hardening] 033b205f. asyncComputed hardening — dirty-gap guard, isPending, leak test, ReactiveObject reuse — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next
+- [async-error-propagation] bf8ad5c0. asyncComputed error propagation (rejections surface, ownership fixed) — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next
+- [computed-error-caching] 79224d08. Computed error caching + propagation (errors never vanish) — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next
+- [benchmark-harness] 9d6d7b2c. Canonical reactivity benchmark suite + glitch-freedom regression tests — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next
+- [test-bench-scripts] 524d07bc. Add test/bench script aliases (agent:test, agent:bench) — reconciled (killed-run recovery). Deviations: unrecorded (the run died before its boundary). Cost: ~$UNMEASURED (manual pre-run, no journal)~ · spec: spec-signals-next
+- [read-version-dedup] dcbaae90. O(1) interleaved repeat-read dedup (read-version stamp) — landed by hand (combined perf integration, bench-gated vs main: 0 regressions). Deviations: SelectorSignal entry-literal rv stamp deferred until signal-is-selector lands (superset-shape rule, follow-up); computed object-size assertion reconciled to 15. Cost: ~$UNMEASURED (manual integration, no journal)~ · spec: spec-signals-next
+- [global-version-fast-path] dcbaae90. globalVersion fast path for clean-graph reads — landed by hand (combined perf integration, bench-gated vs main: 0 regressions). Deviations: computed object-size assertion reconciled to 15 (shared bump with read-version-dedup + pending-only-writes). Cost: ~$UNMEASURED (manual integration, no journal)~ · spec: spec-signals-next
+- [pending-only-writes] dcbaae90. Pending-only writes — defer fan-out off the write hot path (reduced-shape core) — landed by hand (combined perf integration, bench-gated vs main: 0 regressions). Deviations: reduced-shape core only (intrusive nextPending queue, drainPending, per-height + read()-preamble drain); full shape (lazy mark-don't-schedule, selector recursive fan-out + nextPending on the SelectorSignal entry, tests/flush.ts invariant 2) deferred to follow-up pending flush-batch + lazy-computeds + signal-is-selector; SelectorSignal entry-literal nextPending/rv stamp deferred until signal-is-selector; computed object-size assertion reconciled to 15. Cost: ~$UNMEASURED (manual integration, no journal)~ · spec: spec-signals-next
+- [signal-is-selector] 6a9b8e63. signal.selector() per-key selector primitive — O(2) write-path fan-out, lazy per-key entries, eviction on last unsub — landed by hand off main (dcbaae9). Deviations: SelectorSignal entry literal pre-declares nextPending + rv (perf superset-shape, discharges follow-up #1); write-path bench informal (feature, not perf) — one predicted-not-taken keys null-check, write-neutral; suite 328→336 (+8 acceptance tests incl. SameValueZero NaN/object-ref caveats); glitch-freedom green. Cost: ~$UNMEASURED (manual, no journal)~ · spec: spec-signals-next
+- [lazy-computeds] REVERTED (no landing sha). Lazy computeds — compute on first read, sleep while unobserved — removed from scope by user decision 2026-07-19: lazy-by-default was implemented + A/B benchmarked and REGRESSED (full-suite ABBA geomean 1.04; read-class 0.77–0.88× eager; steady-read parity disproven by isolation bench). Do not re-attempt lazy-by-default naively; a non-regressing opt-in approach would be a fresh design. Patch preserved at ~/.claude/storage/lazy-bench/lazy-by-default-full.patch. Feature file removed from the spec per user request. Cost: ~$UNMEASURED (manual, no journal)~ · spec: spec-signals-next

package/README.md

@@ -221,22 +221,27 @@ let user = new ReactiveObject_1();
 | `reactive(() => expr)` | Creates a computed value (compile-time only) |
 | `reactive({...})` | Creates a reactive object with signals and computeds |
 | `reactive([...])` | Creates a reactive array |
-| `effect(fn)` | Runs a function that re-executes when dependencies change. Returns a dispose function |
+| `effect(fn, onError?)` | Runs a function that re-executes when dependencies change. Returns a dispose function. Optional `onError` receives thrown or rejected errors |
 | `root(fn)` | Creates an untracked scope. If `fn` accepts an argument, a dispose function is provided |
 | `onCleanup(fn)` | Registers a cleanup function for the current effect/computed |
 
 ### Low-Level Functions
 
-These are typically only used by the transformer output:
+These operate directly on signal/computed nodes — the transformer emits them, and they can be called by hand:
 
 | Function | Description |
 |----------|-------------|
-| `signal(value)` | Creates a raw signal |
-| `computed(fn)` | Creates a raw computed |
-| `read(node)` | Reads a signal or computed value |
+| `signal(value, equals?)` | Creates a raw signal. Optional `equals` comparator suppresses writes it deems equal (default `===`) |
+| `computed(fn, equals?)` | Creates a raw computed. A `fn` returning a `Promise` or `AsyncIterable` becomes an async computed automatically (initial value `undefined`, unwrapped to `Settled<T>`). Optional `equals` comparator |
+| `read(node)` | Reads a signal or computed value, subscribing the current scope |
 | `write(signal, value)` | Sets a signal value |
-| `asyncComputed(fn)` | Creates a signal that resolves an async computed. Initial value is `undefined` |
+| `peek(node)` | Reads a signal/computed's current value **without** subscribing (returns an up-to-date value even for a dirty computed) |
+| `untrack(fn)` | Runs `fn` without tracking dependencies; returns `fn`'s result |
+| `batch(fn)` | Groups writes so dependent effects defer until `fn` returns; pair with `flush()` for a synchronous transaction |
+| `flush()` | Synchronously settles all pending computed/effect updates |
 | `dispose(computed)` | Disposes a computed and its dependencies |
+| `computed.invalidate(computed)` | Forces re-derivation of a computed on next read (re-dispatches an async computed's promise for a refetch) |
+| `signal.selector(signal, key)` | Per-key selector: within a tracking scope, subscribes to whether `signal`'s value equals `key`, so only key-matching observers re-run on write (O(1) fan-out) |
 
 ### Type Guards
 
@@ -272,6 +277,8 @@ Symbol constants for type identification:
 |------|-------------|
 | `Signal<T>` | Signal node type |
 | `Computed<T>` | Computed node type |
+| `Settled<T>` | Resolved value type of a computed (unwraps `Promise<T>`/`AsyncIterable<T>` to `T`) |
+| `SelectorSignal<T>` | Signal variant backing `signal.selector` per-key subscriptions |
 | `Link` | Dependency graph link between nodes |
 | `Reactive<T>` | Utility type for inferring reactive object/array types |
 | `TransformResult` | Compiler transform output metadata |

package/bench/cellx.bench.ts

@@ -0,0 +1,61 @@
+import { bench, describe } from 'vitest';
+import { assert, framework, ReactiveComputed } from './lib/reactive-adapter';
+
+
+// Ported from milomg/js-reactivity-benchmark packages/core/src/benches/cellxBench.ts (MIT)
+
+interface Layer {
+    prop1: ReactiveComputed<number>;
+    prop2: ReactiveComputed<number>;
+    prop3: ReactiveComputed<number>;
+    prop4: ReactiveComputed<number>;
+}
+
+
+function cellx(layers: number, before: readonly number[], after: readonly number[]) {
+    let start = {
+        prop1: framework.signal(1),
+        prop2: framework.signal(2),
+        prop3: framework.signal(3),
+        prop4: framework.signal(4)
+    };
+
+    let layer: Layer = start;
+
+    for (let i = layers; i > 0; i--) {
+        let m = layer;
+
+        layer = {
+            prop1: framework.computed(() => m.prop2.read()),
+            prop2: framework.computed(() => m.prop1.read() - m.prop3.read()),
+            prop3: framework.computed(() => m.prop2.read() + m.prop4.read()),
+            prop4: framework.computed(() => m.prop3.read())
+        };
+    }
+
+    let end = layer;
+
+    assert(end.prop1.read() === before[0], 'cellx: unexpected initial prop1');
+    assert(end.prop2.read() === before[1], 'cellx: unexpected initial prop2');
+    assert(end.prop3.read() === before[2], 'cellx: unexpected initial prop3');
+    assert(end.prop4.read() === before[3], 'cellx: unexpected initial prop4');
+
+    return framework.withBatch(() => {
+        start.prop1.write(4);
+        start.prop2.write(3);
+        start.prop3.write(2);
+        start.prop4.write(1);
+    }).then(() => {
+        assert(end.prop1.read() === after[0], 'cellx: unexpected final prop1');
+        assert(end.prop2.read() === after[1], 'cellx: unexpected final prop2');
+        assert(end.prop3.read() === after[2], 'cellx: unexpected final prop3');
+        assert(end.prop4.read() === after[3], 'cellx: unexpected final prop4');
+    });
+}
+
+
+describe('cellx', () => {
+    bench('cellx1000', async () => {
+        await framework.withBuild(() => cellx(1000, [-3, -6, -2, 2], [-2, -4, 2, 3]));
+    });
+});

package/bench/dynamic.bench.ts

@@ -0,0 +1,103 @@
+import { bench, describe } from 'vitest';
+import { assert, framework, ReactiveComputed } from './lib/reactive-adapter';
+
+
+// Dynamic-graph workloads: dependency SETS change between runs (branch on a control
+// signal), exercising link/unlink churn and the link pool
+
+function dependencySwap() {
+    let a = [],
+        b = [],
+        computeds: ReactiveComputed<number>[] = [],
+        control = framework.signal(true);
+
+    for (let i = 0; i < 10; i++) {
+        a.push(framework.signal(i));
+        b.push(framework.signal(i * 2));
+    }
+
+    for (let i = 0; i < 20; i++) {
+        computeds.push(framework.computed(() => {
+            let source = control.read() ? a : b,
+                sum = 0;
+
+            for (let j = 0, n = source.length; j < n; j++) {
+                sum += source[j].read();
+            }
+
+            return sum;
+        }));
+    }
+
+    for (let i = 0, n = computeds.length; i < n; i++) {
+        let c = computeds[i];
+
+        framework.effect(() => c.read());
+    }
+
+    let flip = true;
+
+    return async () => {
+        flip = !flip;
+
+        await framework.withBatch(() => {
+            control.write(flip);
+        });
+
+        let expected = flip ? 45 : 90;
+
+        for (let i = 0, n = computeds.length; i < n; i++) {
+            assert(computeds[i].read() === expected, 'dynamic swap: unexpected sum');
+        }
+    };
+}
+
+function movingBranchPoint() {
+    let base = framework.signal(100),
+        chain: ReactiveComputed<number>[] = [],
+        cut = framework.signal(0),
+        depth = 30,
+        source = framework.signal(1);
+
+    // Each node conditionally links `base` (a signal — safe to drop, signals never
+    // auto-dispose) while ALWAYS reading its predecessor so the chain stays alive
+    chain.push(framework.computed(() => (cut.read() > 0 ? base.read() : 0) + source.read()));
+
+    for (let i = 1; i < depth; i++) {
+        let prev = chain[i - 1];
+
+        chain.push(framework.computed(() => (cut.read() > i ? base.read() : 0) + prev.read() + 1));
+    }
+
+    let tail = chain[depth - 1];
+
+    framework.effect(() => tail.read());
+
+    return async () => {
+        await framework.withBatch(() => {
+            cut.write(15);
+        });
+
+        assert(tail.read() === 15 * 100 + 1 + (depth - 1), 'dynamic branch: unexpected tail after cut');
+
+        await framework.withBatch(() => {
+            cut.write(0);
+        });
+
+        assert(tail.read() === 1 + (depth - 1), 'dynamic branch: unexpected tail after restore');
+    };
+}
+
+
+describe('dynamic graphs', () => {
+    let branchRun = framework.withBuild(movingBranchPoint),
+        swapRun = framework.withBuild(dependencySwap);
+
+    bench('dependency set swap (20 computeds x 10 deps)', async () => {
+        await swapRun();
+    });
+
+    bench('moving branch point (30-deep chain re-link)', async () => {
+        await branchRun();
+    });
+});

package/bench/kairo.bench.ts

@@ -0,0 +1,368 @@
+import { bench, describe } from 'vitest';
+import { assert, framework, ReactiveComputed } from './lib/reactive-adapter';
+
+
+// Ported from milomg/js-reactivity-benchmark packages/core/src/benches/kairo/* (MIT)
+
+function avoidablePropagation() {
+    let head = framework.signal(0),
+        computed1 = framework.computed(() => head.read()),
+        computed2 = framework.computed(() => (computed1.read(), 0)),
+        computed3 = framework.computed(() => (busy(), computed2.read() + 1)),
+        computed4 = framework.computed(() => computed3.read() + 2),
+        computed5 = framework.computed(() => computed4.read() + 3);
+
+    framework.effect(() => {
+        computed5.read();
+        busy();
+    });
+
+    return async () => {
+        await framework.withBatch(() => {
+            head.write(1);
+        });
+
+        assert(computed5.read() === 6, 'kairo avoidable: unexpected terminal value');
+
+        for (let i = 0; i < 1000; i++) {
+            await framework.withBatch(() => {
+                head.write(i);
+            });
+
+            assert(computed5.read() === 6, 'kairo avoidable: propagation was not avoided');
+        }
+    };
+}
+
+function broadPropagation() {
+    let counter = { count: 0 },
+        head = framework.signal(0),
+        last: ReactiveComputed<number> = head;
+
+    for (let i = 0; i < 50; i++) {
+        let current = framework.computed(() => head.read() + i),
+            current2 = framework.computed(() => current.read() + 1);
+
+        framework.effect(() => {
+            current2.read();
+            counter.count++;
+        });
+
+        last = current2;
+    }
+
+    return async () => {
+        await framework.withBatch(() => {
+            head.write(1);
+        });
+
+        counter.count = 0;
+
+        for (let i = 0; i < 50; i++) {
+            await framework.withBatch(() => {
+                head.write(i);
+            });
+
+            assert(last.read() === i + 50, 'kairo broad: unexpected tail value');
+        }
+
+        assert(counter.count === 50 * 50, 'kairo broad: unexpected effect run count');
+    };
+}
+
+function busy() {
+    let a = 0;
+
+    for (let i = 0; i < 100; i++) {
+        a++;
+    }
+
+    return a;
+}
+
+function deepPropagation() {
+    let counter = { count: 0 },
+        head = framework.signal(0),
+        len = 50,
+        current: ReactiveComputed<number> = head;
+
+    for (let i = 0; i < len; i++) {
+        let c = current;
+
+        current = framework.computed(() => c.read() + 1);
+    }
+
+    framework.effect(() => {
+        current.read();
+        counter.count++;
+    });
+
+    return async () => {
+        let iter = 50;
+
+        await framework.withBatch(() => {
+            head.write(1);
+        });
+
+        counter.count = 0;
+
+        for (let i = 0; i < iter; i++) {
+            await framework.withBatch(() => {
+                head.write(i);
+            });
+
+            assert(current.read() === len + i, 'kairo deep: unexpected tail value');
+        }
+
+        assert(counter.count === iter, 'kairo deep: unexpected effect run count');
+    };
+}
+
+function diamond() {
+    let counter = { count: 0 },
+        current: ReactiveComputed<number>[] = [],
+        head = framework.signal(0),
+        width = 5;
+
+    for (let i = 0; i < width; i++) {
+        current.push(framework.computed(() => head.read() + 1));
+    }
+
+    let sum = framework.computed(() => current.map((x) => x.read()).reduce((a, b) => a + b, 0));
+
+    framework.effect(() => {
+        sum.read();
+        counter.count++;
+    });
+
+    return async () => {
+        await framework.withBatch(() => {
+            head.write(1);
+        });
+
+        assert(sum.read() === 2 * width, 'kairo diamond: unexpected initial sum');
+
+        counter.count = 0;
+
+        for (let i = 0; i < 500; i++) {
+            await framework.withBatch(() => {
+                head.write(i);
+            });
+
+            assert(sum.read() === (i + 1) * width, 'kairo diamond: unexpected sum');
+        }
+
+        assert(counter.count === 500, 'kairo diamond: unexpected effect run count');
+    };
+}
+
+function mux() {
+    let heads = new Array(100).fill(null).map(() => framework.signal(0));
+
+    let muxed = framework.computed(() => Object.fromEntries(heads.map((h) => h.read()).entries()));
+
+    let splited = heads
+        .map((_, index) => framework.computed(() => muxed.read()[index]))
+        .map((x) => framework.computed(() => x.read() + 1));
+
+    for (let i = 0, n = splited.length; i < n; i++) {
+        let x = splited[i];
+
+        framework.effect(() => x.read());
+    }
+
+    return async () => {
+        for (let i = 0; i < 10; i++) {
+            await framework.withBatch(() => {
+                heads[i].write(i);
+            });
+
+            assert(splited[i].read() === i + 1, 'kairo mux: unexpected split value');
+        }
+
+        for (let i = 0; i < 10; i++) {
+            await framework.withBatch(() => {
+                heads[i].write(i * 2);
+            });
+
+            assert(splited[i].read() === i * 2 + 1, 'kairo mux: unexpected split value');
+        }
+    };
+}
+
+function repeatedObservers() {
+    let counter = { count: 0 },
+        head = framework.signal(0),
+        size = 30;
+
+    let current = framework.computed(() => {
+        let result = 0;
+
+        for (let i = 0; i < size; i++) {
+            result += head.read();
+        }
+
+        return result;
+    });
+
+    framework.effect(() => {
+        current.read();
+        counter.count++;
+    });
+
+    return async () => {
+        await framework.withBatch(() => {
+            head.write(1);
+        });
+
+        assert(current.read() === size, 'kairo repeated: unexpected initial value');
+
+        counter.count = 0;
+
+        for (let i = 0; i < 100; i++) {
+            await framework.withBatch(() => {
+                head.write(i);
+            });
+
+            assert(current.read() === i * size, 'kairo repeated: unexpected value');
+        }
+
+        assert(counter.count === 100, 'kairo repeated: unexpected effect run count');
+    };
+}
+
+function triangle() {
+    let counter = { count: 0 },
+        head = framework.signal(0),
+        list: ReactiveComputed<number>[] = [],
+        width = 10,
+        current: ReactiveComputed<number> = head;
+
+    for (let i = 0; i < width; i++) {
+        let c = current;
+
+        list.push(current);
+        current = framework.computed(() => c.read() + 1);
+    }
+
+    let sum = framework.computed(() => list.map((x) => x.read()).reduce((a, b) => a + b, 0));
+
+    framework.effect(() => {
+        sum.read();
+        counter.count++;
+    });
+
+    return async () => {
+        let constant = (width * (width + 1)) / 2;
+
+        await framework.withBatch(() => {
+            head.write(1);
+        });
+
+        assert(sum.read() === constant, 'kairo triangle: unexpected initial sum');
+
+        counter.count = 0;
+
+        for (let i = 0; i < 100; i++) {
+            await framework.withBatch(() => {
+                head.write(i);
+            });
+
+            assert(sum.read() === constant - width + i * width, 'kairo triangle: unexpected sum');
+        }
+
+        assert(counter.count === 100, 'kairo triangle: unexpected effect run count');
+    };
+}
+
+function unstable() {
+    let counter = { count: 0 },
+        head = framework.signal(0);
+
+    let double = framework.computed(() => head.read() * 2);
+
+    let inverse = framework.computed(() => -head.read());
+
+    let current = framework.computed(() => {
+        let result = 0;
+
+        for (let i = 0; i < 20; i++) {
+            result += head.read() % 2 ? double.read() : inverse.read();
+        }
+
+        return result;
+    });
+
+    // Keepers: this system auto-disposes a computed on last-sub unlink, so the
+    // inactive branch would go permanently stale without a live subscriber
+    framework.effect(() => double.read());
+
+    framework.effect(() => inverse.read());
+
+    framework.effect(() => {
+        current.read();
+        counter.count++;
+    });
+
+    return async () => {
+        await framework.withBatch(() => {
+            head.write(1);
+        });
+
+        assert(current.read() === 40, 'kairo unstable: unexpected initial value');
+
+        counter.count = 0;
+
+        for (let i = 0; i < 100; i++) {
+            await framework.withBatch(() => {
+                head.write(i);
+            });
+        }
+
+        assert(counter.count === 100, 'kairo unstable: unexpected effect run count');
+    };
+}
+
+
+describe('kairo', () => {
+    let avoidableRun = framework.withBuild(avoidablePropagation),
+        broadRun = framework.withBuild(broadPropagation),
+        deepRun = framework.withBuild(deepPropagation),
+        diamondRun = framework.withBuild(diamond),
+        muxRun = framework.withBuild(mux),
+        repeatedRun = framework.withBuild(repeatedObservers),
+        triangleRun = framework.withBuild(triangle),
+        unstableRun = framework.withBuild(unstable);
+
+    bench('avoidablePropagation', async () => {
+        await avoidableRun();
+    });
+
+    bench('broad', async () => {
+        await broadRun();
+    });
+
+    bench('deep', async () => {
+        await deepRun();
+    });
+
+    bench('diamond', async () => {
+        await diamondRun();
+    });
+
+    bench('mux', async () => {
+        await muxRun();
+    });
+
+    bench('repeatedObservers', async () => {
+        await repeatedRun();
+    });
+
+    bench('triangle', async () => {
+        await triangleRun();
+    });
+
+    bench('unstable', async () => {
+        await unstableRun();
+    });
+});

package/bench/lib/reactive-adapter.ts

@@ -0,0 +1,51 @@
+import { computed, effect, read, root, signal, write } from '~/system';
+
+import type { Settled } from '~/types';
+
+
+interface ReactiveComputed<T> {
+    read: () => T;
+}
+
+interface ReactiveSignal<T> extends ReactiveComputed<T> {
+    write: (value: T) => void;
+}
+
+
+// Mirrors js-reactivity-benchmark's ReactiveFramework so a future external-package swap is mechanical
+const framework = {
+    computed: <T>(fn: () => T): ReactiveComputed<Settled<T>> => {
+        let node = computed(fn);
+
+        return {
+            read: () => read(node)
+        };
+    },
+    effect: (fn: () => void): VoidFunction => effect(fn),
+    signal: <T>(value: T): ReactiveSignal<T> => {
+        let node = signal(value);
+
+        return {
+            read: () => read(node),
+            write: (v: T) => write(node, v)
+        };
+    },
+    withBatch: async (fn: () => void): Promise<void> => {
+        fn();
+
+        // Propagation is microtask-scheduled (schedule/stabilize) — two ticks cover a reschedule
+        await Promise.resolve();
+        await Promise.resolve();
+    },
+    withBuild: <T>(fn: () => T): T => root(fn)
+};
+
+const assert = (condition: boolean, message: string): void => {
+    if (!condition) {
+        throw new Error(`bench: ${message}`);
+    }
+};
+
+
+export { assert, framework };
+export type { ReactiveComputed, ReactiveSignal };