@lazily-hub/lazily-js 0.5.0 → 0.6.1

package/BENCHMARKS.md

@@ -0,0 +1,91 @@
+# lazily-js Benchmark Results
+
+Generated benchmark data for the
+[`@lazily-hub/lazily-js`](https://www.npmjs.com/package/@lazily-hub/lazily-js)
+reactive primitives library.
+
+## Benchmark Results
+
+The suite is a 1:1 port of the single-threaded `Context` benchmarks in
+lazily-rs's `benches/context.rs` — the same group/case names and the same
+widths/depths (`FAN_OUT_WIDTHS=[32,256]`, `MEMO_CHAIN_DEPTH=32`,
+`BATCH_STORM_CELLS=64`, `SET_CELL_INVALIDATION_FAN_OUT=512`) so JS and Rust
+numbers are directly comparable.
+
+JS runs on a single event-loop thread, so the lazily-rs `ThreadSafeContext`
+multi-worker contention benchmarks (`thread_safe_contention`,
+`thread_safe_effect_contention`, `thread_safe_graph_propagation`) have no
+like-for-like single-process counterpart here and are intentionally omitted.
+
+<!-- benchmark-results:start -->
+
+Generated for package `@lazily-hub/lazily-js` version `0.6.0`.
+
+Environment: Node.js `26.4.0` on `linux x64`.
+
+Refresh command:
+
+```bash
+node scripts/run-benchmarks.mjs
+```
+
+Mean wall-clock time per iteration; 95% CI half-width from the standard error.
+
+| Group | Case | Mean | 95% CI | p75 | p99 | Samples |
+|---|---|---:|---:|---:|---:|---:|
+| cached_reads | context | 57.798 ns | ± 20.941 ns | 46.398 ns | 124.744 ns | 100 |
+| cold_first_get | context | 669.220 ns | ± 8.630 ns | 670.000 ns | 802.610 ns | 100 |
+| dependency_fan_out | context / 32 | 7.448 us | ± 824.968 ns | 6.783 us | 34.205 us | 100 |
+| dependency_fan_out | context / 256 | 43.766 us | ± 1.064 us | 43.270 us | 49.513 us | 100 |
+| set_cell_invalidation | high_fan_out / 512 | 10.737 us | ± 376.524 ns | 10.113 us | 17.141 us | 100 |
+| memo_equality_suppression | context | 2.387 us | ± 193.801 ns | 2.310 us | 2.864 us | 100 |
+| effect_flushing | context | 211.187 ns | ± 20.150 ns | 221.482 ns | 524.491 ns | 100 |
+| batch_storms | context / 64 | 30.430 us | ± 1.295 us | 30.815 us | 49.775 us | 99 |
+| typed_cache_reads | context_cell | 31.325 ns | ± 1.052 ns | 30.255 ns | 58.102 ns | 100 |
+| typed_cache_reads | context_slot | 120.262 ns | ± 4.805 ns | 118.099 ns | 220.409 ns | 100 |
+
+<!-- benchmark-results:end -->
+
+## Suite
+
+| Group | Case | Parity with lazily-rs | What it measures |
+|-------|------|-----------------------|------------------|
+| `cached_reads` | `context` | `bench_cached_reads` / context | Steady-state cached `ctx.get(slot)` (no recompute). |
+| `cold_first_get` | `context` | `bench_cold_first_get` / context | First (uncached) read of a freshly built slot. |
+| `dependency_fan_out` | `context / {32,256}` | `bench_dependency_fan_out` / context | One root cell invalidates N dependents, then all are re-read. |
+| `set_cell_invalidation` | `high_fan_out / 512` | `bench_set_cell_invalidation` / high_fan_out | Cost of `setCell` invalidating a 512-wide fan-out (no recompute). |
+| `memo_equality_suppression` | `context` | `bench_memo_equality_suppression` / context | Memo chain that stays equal downstream (guard suppresses recompute). |
+| `effect_flushing` | `context` | `bench_effect_flushing` / context | Effect re-runs on every cell change. |
+| `batch_storms` | `context / 64` | `bench_batch_storms` / context | Coalesced batched writes to 64 cells (one effect flush). |
+| `typed_cache_reads` | `context_slot`, `context_cell` | `bench_typed_cache_reads` / context_* | Direct `ctx.get(slot)` vs `ctx.getCell(cell)`. |
+
+### Running
+
+```bash
+npm run bench                 # run the suite, print a markdown table
+node scripts/run-benchmarks.mjs        # run + refresh this file
+node scripts/run-benchmarks.mjs --check # CI gate: exit 1 if stale
+make bench                   # via the Makefile
+```
+
+### Harness
+
+`bench/harness.mjs` is a zero-dependency criterion-style harness
+(`node:perf_hooks` only). It offers two measurement modes:
+
+- **`bench(group, case, fn)`** — auto-batched timing for *idempotent* routines
+  (each sample times N calls, N auto-scaled so one sample lasts ~5 ms). Use for
+  steady-state reads / repeated-equal-cost work.
+- **`bench.batched(group, case, setup, routine)`** — `iter_batched` timing
+  (criterion `BatchSize::SmallInput`): fresh `setup()` before every single
+  measured call, setup excluded from timing. Use when the operation mutates graph
+  state a second call would skip — e.g. the `==` guard on `setCell`, or a cold
+  first read that caches on first access.
+
+### Regression workflow
+
+```bash
+node scripts/run-benchmarks.mjs            # record "before" baseline in BENCHMARKS.md
+# apply the performance patch
+node scripts/run-benchmarks.mjs            # compare against the new numbers
+```

package/README.md

@@ -35,29 +35,37 @@ The full `lazily` capability set across every binding. Legend: ✅ shipped ·
 notes and platform carve-outs lives in
 [`lazily-spec` § Cross-Language Coverage](../lazily-spec/docs/coverage.md).
 
-| Feature | Rust | Python | Kotlin | JS | Dart | Zig |
-|---------|:----:|:------:|:------:|:--:|:----:|:---:|
-| Reactive graph — `Cell` / `Slot` / `Signal` / `Effect` / memo / batch | ✅ | ~ | ✅ | ✅ | ~ | ~ |
-| Thread-safe context (lock-backed) | ✅ | ✅ | ✅ | — | — | ✅ |
-| Async reactive context | ✅ | ✅ | ✅ | ✅ | ✅ | — |
-| Flat state machine | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Harel state charts | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Keyed cell collections (`CellMap` / `CellTree`) + reconcile | ✅ | ✅ | ✅ | ✅ | ✅ | ~ |
-| Memoized semantic tree (`SemTree`) | ✅ | — | ✅ | ✅ | — | — |
-| Stable-id alignment (manufactured identity) | ✅ | — | ✅ | ✅ | — | — |
-| Free-text character CRDT (`TextCrdt`) | ✅ | — | ✅ | ✅ | — | — |
-| `TextCrdt` delta sync (`version_vector` / `delta_since` / `apply_delta`) | ✅ | — | ✅ | ✅ | — | — |
-| Move-aware sequence CRDT (`SeqCrdt`) | ✅ | — | ✅ | ✅ | — | — |
-| Registers (LWW / MV) + `PnCounter` + `CellCrdt` | ✅ | — | ✅ | ✅ | — | — |
-| IPC wire — `Snapshot` + `Delta` + `CrdtSync` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Shared-memory blob path (`ShmBlobArena`) | ✅ | ✅ | ✅ | ~ | ~ | ✅ |
-| Distributed CRDT plane (`CrdtPlaneRuntime` / anti-entropy) | ✅ | — | ✅ | ✅ | ~ | — |
-| Distributed plane — WebRTC transport + signaling | ✅ | — | ✅ | ✅ | — | — |
-| State projection / mirror | ✅ | — | ✅ | ✅ | — | — |
-| C-ABI FFI boundary | ✅ | ✅ | ✅ | — | ✅ | ✅ |
-| Permission boundary (`PeerPermissions` / `RemoteOp`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Capability negotiation (`SessionHandshake`) | ✅ | — | ✅ | ✅ | ✅ | ✅ |
-| Instrumentation / benchmarks | ✅ | — | — | — | — | — |
+<!-- coverage-table:start -->
+| Feature | Rust | Python | Kotlin | JS | Dart | Zig | Go | C++ |
+| --------- | :----: | :------: | :------: | :--: | :----: | :---: | :--: | :---: |
+| Reactive graph — `Cell` / `Slot` / `Signal` / `Effect` / memo / batch | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Thread-safe context (lock-backed) | ✅ | ✅ | ✅ | — | — | ✅ | ✅ | ✅ |
+| Async reactive context | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Flat state machine | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Harel state charts | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Keyed cell collections (`CellMap` / `CellTree`) + reconcile | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Memoized semantic tree (`SemTree`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Stable-id alignment (manufactured identity) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Reactive queue (`QueueCell` SPSC/MPSC + `QueueStorage` adapter) | — | — | — | — | — | — | — | — |
+| Free-text character CRDT (`TextCrdt`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `TextCrdt` delta sync (`version_vector` / `delta_since` / `apply_delta`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Move-aware sequence CRDT (`SeqCrdt`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Lossless tree CRDT core (`LosslessTreeCrdt`, M1) | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
+| Lossless tree — dotted-frontier anti-entropy | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
+| Lossless tree — concurrent merge convergence | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
+| Registers (LWW / MV) + `PnCounter` + `CellCrdt` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| IPC wire — `Snapshot` + `Delta` + `CrdtSync` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Shared-memory blob path (`ShmBlobArena`) | ✅ | ✅ | ✅ | ~ | ~ | ✅ | ✅ | ✅ |
+| Distributed CRDT plane (`CrdtPlaneRuntime` / anti-entropy) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Distributed plane — WebRTC transport + signaling | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| State projection / mirror | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Causal receipts (`CausalReceipts` outcome projection) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Message-passing + RPC command plane (`command-plane-v1`) | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
+| C-ABI FFI boundary | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ |
+| Permission boundary (`PeerPermissions` / `RemoteOp`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Capability negotiation (`SessionHandshake`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Instrumentation / benchmarks | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ |
+<!-- coverage-table:end -->
 
 CRDT convergence and the wire protocol are pinned by the shared conformance fixtures
 and JSON Schemas in `lazily-spec` and the Lean models in `lazily-formal`.
@@ -374,11 +382,12 @@ bob.ingest(alice.syncFrame(), Date.now() * 1000); // 1 op applied; re-ingest app
 
 lazily-js replays the shared `lazily-spec` fixtures for IPC, agent-doc state,
 keyed collections (`CellMap`, `CellTree`, LIS reconciliation), semantic tree,
-sequence and text CRDTs, manufactured text identity, Harel state charts, the
-signaling protocol (`signaling/frames.json`, `signaling/anti_spoof_session.json`),
-and the distributed CRDT plane (`distributed/crdt_sync_frames.json`,
-`distributed/anti_entropy_converge.json`). It also validates generated wire
-values against the canonical JSON Schemas.
+sequence and text CRDTs (incl. `TextCrdt` delta sync, `#lztextsync`:
+`textcrdt_convergence.json` + `textcrdt_delta_sync.json`), manufactured text
+identity, Harel state charts, the signaling protocol (`signaling/frames.json`,
+`signaling/anti_spoof_session.json`), and the distributed CRDT plane
+(`distributed/crdt_sync_frames.json`, `distributed/anti_entropy_converge.json`).
+It also validates generated wire values against the canonical JSON Schemas.
 
 `npm test` builds the [`lazily-formal`][formal] Lean 4 model when that sibling
 checkout and the `lake` toolchain are present. The script exits successfully

package/bench/context.bench.mjs

@@ -0,0 +1,179 @@
+// Reactive-graph benchmarks for lazily-js — parity port of lazily-rs
+// `benches/context.rs` (the single-threaded `Context` variants).
+//
+// JS runs on a single event-loop thread, so the lazily-rs `ThreadSafeContext`
+// multi-worker contention benchmarks (thread_safe_contention,
+// thread_safe_effect_contention, thread_safe_graph_propagation) have no
+// like-for-like single-process counterpart here and are intentionally omitted.
+// Every group/case below is a 1:1 port of the matching `context`-variant in
+// lazily-rs, using the same widths/depths so numbers are cross-language
+// comparable. Constants mirror `benches/context.rs` exactly.
+
+import { bench, blackBox, run } from "./harness.mjs";
+import { Context } from "../src/reactive.js";
+
+const FAN_OUT_WIDTHS = [32, 256];
+const MEMO_CHAIN_DEPTH = 32;
+const BATCH_STORM_CELLS = 64;
+const SET_CELL_INVALIDATION_FAN_OUT = 512;
+
+// --- setup helpers (ports of setup_context_* in benches/context.rs) ---------
+
+function setupFanOut(width) {
+  const ctx = new Context();
+  const root = ctx.cell(0);
+  const slots = [];
+  for (let offset = 0; offset < width; offset++) {
+    slots.push(ctx.computed(() => (ctx.getCell(root) + offset) >>> 0));
+  }
+  for (const slot of slots) blackBox(ctx.get(slot));
+  return { ctx, root, slots };
+}
+
+function setupMemoChain(depth) {
+  const ctx = new Context();
+  const root = ctx.cell(0);
+  let tail = ctx.memo(() => ctx.getCell(root) % 2);
+  for (let i = 0; i < depth; i++) {
+    const previous = tail;
+    tail = ctx.computed(() => (ctx.get(previous) + 1) >>> 0);
+  }
+  blackBox(ctx.get(tail));
+  return { ctx, root, tail };
+}
+
+function setupBatchStorm(cellsLen) {
+  const ctx = new Context();
+  const cells = [];
+  for (let idx = 0; idx < cellsLen; idx++) cells.push(ctx.cell(idx));
+  let sink = 0;
+  const effectCells = cells.slice();
+  ctx.effect(() => {
+    let total = 0;
+    for (const cell of effectCells) total = (total + ctx.getCell(cell)) >>> 0;
+    sink = total;
+  });
+  return { ctx, cells, getSink: () => sink };
+}
+
+// --- cached_reads: steady-state cached slot read ----------------------------
+// Parity: bench_cached_reads "context" in lazily-rs/context.rs.
+// Setup runs once before registration; only the cached `get` is timed.
+{
+  const ctx = new Context();
+  const root = ctx.cell(21);
+  const doubled = ctx.computed(() => ctx.getCell(root) * 2);
+  blackBox(ctx.get(doubled)); // prime the cache
+  bench("cached_reads", "context", () => blackBox(ctx.get(blackBox(doubled))));
+}
+
+// --- cold_first_get: first (uncached) read of a freshly built slot ---------
+// Parity: bench_cold_first_get "context" (iter_batched — fresh ctx each call).
+bench.batched(
+  "cold_first_get",
+  "context",
+  () => {
+    const ctx = new Context();
+    const root = ctx.cell(21);
+    const doubled = ctx.computed(() => ctx.getCell(root) * 2);
+    return { ctx, doubled };
+  },
+  ({ ctx, doubled }) => blackBox(ctx.get(blackBox(doubled))),
+);
+
+// --- dependency_fan_out: one root cell invalidates N dependents ------------
+// Parity: bench_dependency_fan_out "context / {32,256}" (iter_batched).
+for (const width of FAN_OUT_WIDTHS) {
+  bench.batched(
+    "dependency_fan_out",
+    `context / ${width}`,
+    () => setupFanOut(width),
+    ({ ctx, root, slots }) => {
+      ctx.setCell(root, blackBox(1));
+      let total = 0;
+      for (const slot of slots) total = (total + ctx.get(slot)) >>> 0;
+      blackBox(total);
+    },
+  );
+}
+
+// --- set_cell_invalidation: cost of invalidating a wide fan-out ------------
+// Parity: bench_set_cell_invalidation "high_fan_out / 512" (iter_batched).
+// Only the setCell invalidation is timed (not the downstream recompute) —
+// matches the lazily-rs routine which times `set_cell` + `black_box(slots.len())`.
+bench.batched(
+  "set_cell_invalidation",
+  "high_fan_out / 512",
+  () => setupFanOut(SET_CELL_INVALIDATION_FAN_OUT),
+  ({ ctx, root, slots }) => {
+    ctx.setCell(root, blackBox(1));
+    blackBox(slots.length);
+  },
+);
+
+// --- memo_equality_suppression: memo chain that stays equal downstream -----
+// Parity: bench_memo_equality_suppression "context" (iter_batched).
+// root%2 memo head; setting root to an even value keeps the head's value equal
+// (0) so downstream caches survive — the memo guard path.
+bench.batched(
+  "memo_equality_suppression",
+  "context",
+  () => setupMemoChain(MEMO_CHAIN_DEPTH),
+  ({ ctx, root, tail }) => {
+    ctx.setCell(root, blackBox(2));
+    blackBox(ctx.get(blackBox(tail)));
+  },
+);
+
+// --- effect_flushing: effect re-runs on every cell change ------------------
+// Parity: bench_effect_flushing "context" (idempotent: advances next each call
+// so each setCell is a real 1->2->3 ... change, not a ==-guarded no-op).
+{
+  const ctx = new Context();
+  const root = ctx.cell(0);
+  let seen = 0;
+  ctx.effect(() => {
+    seen = (seen + ctx.getCell(root)) >>> 0;
+  });
+  let next = 0;
+  bench("effect_flushing", "context", () => {
+    next = (next + 1) >>> 0;
+    ctx.setCell(root, blackBox(next));
+    blackBox(seen);
+  });
+}
+
+// --- batch_storms: coalesced batched writes to many cells -----------------
+// Parity: bench_batch_storms "context / 64".
+{
+  const { ctx, cells, getSink } = setupBatchStorm(BATCH_STORM_CELLS);
+  let base = BATCH_STORM_CELLS;
+  bench("batch_storms", `context / ${BATCH_STORM_CELLS}`, () => {
+    base = (base + BATCH_STORM_CELLS) >>> 0;
+    ctx.batch(() => {
+      for (let i = 0; i < cells.length; i++) {
+        ctx.setCell(cells[i], blackBox((base + i) >>> 0));
+      }
+    });
+    blackBox(getSink());
+  });
+}
+
+// --- typed_cache_reads: direct slot/cell reads ----------------------------
+// Parity: bench_typed_cache_reads "context_slot" / "context_cell".
+{
+  const ctx = new Context();
+  const cell = ctx.cell(42);
+  const slot = ctx.computed(() => ctx.getCell(cell));
+  blackBox(ctx.get(slot)); // prime
+  bench("typed_cache_reads", "context_slot", () => blackBox(ctx.get(blackBox(slot))));
+}
+{
+  const ctx = new Context();
+  const cell = ctx.cell(99);
+  bench("typed_cache_reads", "context_cell", () => blackBox(ctx.getCell(blackBox(cell))));
+}
+
+await run({
+  format: process.env.BENCH_FORMAT === "json" ? "json" : "markdown",
+});

package/bench/harness.mjs

@@ -0,0 +1,144 @@
+// Criterion-style micro-benchmark harness for lazily-js.
+//
+// Mirrors the lazily-rs `benches/context.rs` measurement model (criterion 0.8):
+//   - auto-batched timing for *idempotent* routines (each sample times N calls,
+//     N auto-scaled so one sample lasts ~TARGET_SAMPLE_MS), and
+//   - iter_batched timing for *non-idempotent* routines (fresh `setup()` before
+//     every single measured call, setup excluded from the timed region), so a
+//     case like `setCell(root, 1)` is always a real 0->1 invalidation rather
+//     than a `==`-guarded no-op on the second call.
+//
+// Zero dependencies (node:perf_hooks only) — keeps the published package lean.
+// Emits a Group/Case/Mean/95% CI/p75/p99/Samples markdown table matching
+// lazily-rs's BENCHMARKS.md so cross-language numbers are directly comparable.
+
+import { performance } from "node:perf_hooks";
+
+// Sink the optimizer cannot eliminate — black_box analog (force a read+write
+// through a module-level mutable captured by an exported function).
+let __blackHole = undefined;
+export function blackBox(value) {
+  __blackHole = value;
+  return value;
+}
+export function doNotOptimize(value) {
+  return blackBox(value);
+}
+
+const TARGET_SAMPLE_MS = 5; // ~criterion measurement_time per sample
+const MIN_SAMPLES = 20;
+const MAX_SAMPLES = 100;
+const WARMUP_ITERS = 64;
+const NS_PER_MS = 1e6;
+const MIN_RUN_MS = 500;
+
+function quantile(sorted, q) {
+  if (sorted.length === 0) return 0;
+  const pos = q * (sorted.length - 1);
+  const lo = Math.floor(pos);
+  const hi = Math.ceil(pos);
+  if (lo === hi) return sorted[lo];
+  const frac = pos - lo;
+  return sorted[lo] * (1 - frac) + sorted[hi] * frac;
+}
+
+function summarize(samplesNs) {
+  const sorted = [...samplesNs].sort((a, b) => a - b);
+  const mean = sorted.reduce((a, v) => a + v, 0) / sorted.length;
+  const variance =
+    sorted.reduce((a, v) => a + (v - mean) ** 2, 0) / sorted.length;
+  const sem = Math.sqrt(variance / sorted.length);
+  return {
+    mean,
+    p50: quantile(sorted, 0.5),
+    p75: quantile(sorted, 0.75),
+    p99: quantile(sorted, 0.99),
+    samples: sorted.length,
+    ci: 1.96 * sem, // 95% CI half-width (t≈1.96 for n≥20)
+  };
+}
+
+export function format(ns) {
+  if (ns >= 1e6) return `${(ns / 1e6).toFixed(3)} ms`;
+  if (ns >= 1e3) return `${(ns / 1e3).toFixed(3)} us`;
+  return `${ns.toFixed(3)} ns`;
+}
+
+// Auto-batched measurement for an idempotent routine (criterion `iter`).
+function measure(fn, { minMs = MIN_RUN_MS } = {}) {
+  for (let i = 0; i < WARMUP_ITERS; i++) fn();
+  // Calibrate iteration count so one sample hits TARGET_SAMPLE_MS.
+  const t0 = performance.now();
+  fn();
+  const oneNs = (performance.now() - t0) * NS_PER_MS;
+  let iters = oneNs > 0 ? Math.max(1, Math.ceil((TARGET_SAMPLE_MS * NS_PER_MS) / oneNs)) : 1;
+
+  const samples = [];
+  let elapsed = 0;
+  while ((samples.length < MIN_SAMPLES || elapsed < minMs) && samples.length < MAX_SAMPLES) {
+    const start = performance.now();
+    for (let i = 0; i < iters; i++) fn();
+    const dtMs = performance.now() - start;
+    samples.push((dtMs * NS_PER_MS) / iters);
+    elapsed += dtMs;
+  }
+  return summarize(samples);
+}
+
+// iter_batched measurement: fresh setup() before every single measured call,
+// setup excluded from timing (criterion `iter_batched`, BatchSize::SmallInput).
+function measureBatched(setup, routine, { minMs = MIN_RUN_MS, minSamples = MIN_SAMPLES } = {}) {
+  for (let i = 0; i < WARMUP_ITERS; i++) routine(setup());
+  const samples = [];
+  let elapsed = 0;
+  while ((samples.length < minSamples || elapsed < minMs) && samples.length < MAX_SAMPLES) {
+    const ctx = setup();
+    const start = performance.now();
+    routine(ctx);
+    const ns = (performance.now() - start) * NS_PER_MS;
+    samples.push(ns);
+    elapsed += ns / NS_PER_MS;
+  }
+  return summarize(samples);
+}
+
+const registry = [];
+
+// Idempotent routine: the function is called many times per sample, so it must
+// be safe to repeat (each call performs the same amount of real work).
+export function bench(group, caseLabel, fn, opts = {}) {
+  registry.push({ group, case: caseLabel, kind: "fn", fn, opts });
+}
+
+// Non-idempotent routine: setup() runs before every single measured call and is
+// excluded from timing; routine(ctx) runs once per sample. Use this whenever the
+// operation mutates graph state that a second call would skip (e.g. the `==`
+// guard on setCell, or a cold first read that caches on first access).
+bench.batched = function batched(group, caseLabel, setup, routine, opts = {}) {
+  registry.push({ group, case: caseLabel, kind: "batched", setup, routine, opts });
+};
+
+export async function run({ print = true, format = "markdown" } = {}) {
+  const results = [];
+  for (const entry of registry) {
+    let stats;
+    if (entry.kind === "fn") stats = measure(entry.fn, entry.opts);
+    else stats = measureBatched(entry.setup, entry.routine, entry.opts);
+    results.push({ group: entry.group, case: entry.case, ...stats });
+  }
+  if (print) {
+    if (format === "json") console.log(JSON.stringify({ results }, null, 2));
+    else printMarkdown(results);
+  }
+  return results;
+}
+
+function printMarkdown(results) {
+  console.log("| Group | Case | Mean | 95% CI | p75 | p99 | Samples |");
+  console.log("|---|---|---:|---:|---:|---:|---:|");
+  for (const r of results) {
+    console.log(
+      `| ${r.group} | ${r.case} | ${format(r.mean)} | ± ${format(r.ci)} | ${format(r.p75)} | ${format(r.p99)} | ${r.samples} |`,
+    );
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazily-hub/lazily-js",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Native JavaScript port of the lazily reactive core: a full reactive graph (Cell/Slot/Signal/Effect), the lazily-spec IPC wire types, keyed cell collections + LIS reconciliation, the memoized semantic tree, the move-aware sequence CRDT, the Fugue/RGA text CRDT, manufactured text identity, full-Harel state charts, and an FFI state-projection consumer.",
   "type": "module",
   "main": "src/index.js",
@@ -46,6 +46,10 @@
       "types": "./src/text-crdt.d.ts",
       "default": "./src/text-crdt.js"
     },
+    "./lossless-tree-crdt": {
+      "types": "./src/lossless-tree-crdt.d.ts",
+      "default": "./src/lossless-tree-crdt.js"
+    },
     "./state-projection": {
       "types": "./src/state-projection.d.ts",
       "default": "./src/state-projection.js"
@@ -60,8 +64,11 @@
     }
   },
   "scripts": {
-    "build": "node --check src/index.js && node --check src/reactive.js && node --check src/reactive-async.js && node --check src/state-machine.js && node --check src/statechart.js && node --check src/collections.js && node --check src/sem-tree.js && node --check src/stable-id.js && node --check src/seq-crdt.js && node --check src/text-crdt.js && node --check src/state-projection.js && node --check src/signaling.js && node --check src/distributed.js",
+    "build": "node --check src/index.js && node --check src/reactive.js && node --check src/reactive-async.js && node --check src/state-machine.js && node --check src/statechart.js && node --check src/collections.js && node --check src/sem-tree.js && node --check src/stable-id.js && node --check src/seq-crdt.js && node --check src/text-crdt.js && node --check src/utf8-offsets.js && node --check src/lossless-tree-crdt.js && node --check src/state-projection.js && node --check src/signaling.js && node --check src/distributed.js",
     "test:formal": "node scripts/formal-check.mjs",
+    "bench": "node bench/context.bench.mjs",
+    "benchmark-update": "node scripts/run-benchmarks.mjs",
+    "benchmark-check": "node scripts/run-benchmarks.mjs --check",
     "test": "npm run test:formal && node --test test/*.test.js"
   },
   "dependencies": {