@lazily-hub/lazily-js 0.7.0 → 0.10.0

package/BENCHMARKS.md

@@ -89,3 +89,118 @@ node scripts/run-benchmarks.mjs            # record "before" baseline in BENCHMA
 # apply the performance patch
 node scripts/run-benchmarks.mjs            # compare against the new numbers
 ```
+
+## Scale (≥1M cells) — spreadsheet-shaped graph
+
+A second suite ([`bench/scale.bench.mjs`](bench/scale.bench.mjs)) replicates the
+lazily-rs [`scale`](https://github.com/lazily-hub/lazily-rs/blob/main/benches/scale.rs)
+group, the lazily-go `scale` group, and lazily-py's
+[`scale_bench.py`](https://github.com/lazily-hub/lazily-py/blob/main/src/lazily/scale_bench.py)
+on a **spreadsheet-shaped** graph: `N` input cells + `N` formula slots where
+`formula[i] = input[i] + input[i - 1]` (local fan-in, like a column of
+`=A_i + A_{i-1}`). With the default `N = 1,000,000` that is **~2,000,000
+reactive nodes**. Four scenarios cover the spreadsheet lifecycle:
+
+- `build` — construct all `2N` nodes (formulas lazy, not yet computed).
+- `cold_full_recalc` — first read of every formula (forces every compute + edge-tracking).
+- `viewport_recalc` — edit one input, read only a 1,000-cell viewport (the
+  lazy-pull win: off-viewport formulas stay dirty and never recompute).
+- `full_recalc_invalidate_all` — re-set every input, then read every formula
+  (worst-case full-sheet edit).
+
+> **A "cell count" here counts two cells per row** — the graph models a column of
+> formulas `=A_i + A_{i-1}`, so each row is **one input cell `A_i` plus one
+> formula cell**. `N` rows ⇒ `N` inputs + `N` formulas = `2N` cells.
+
+Timings use `performance.now()` (`node:perf_hooks`); single wall-clock run per
+scenario. Lower is better. Treat the absolute numbers as indicative — the shapes
+(relative costs, size-scaling behavior) are what transfer across runs and hosts.
+
+### Reproduce
+
+```bash
+make bench-scale                                    # scale suite at N = 1,000,000
+node bench/scale.bench.mjs                          # same, directly
+
+# scale at a specific size / viewport:
+LAZILY_SCALE_N=1000000 node bench/scale.bench.mjs
+LAZILY_SCALE_N=5000000 node bench/scale.bench.mjs   # Google Sheets 10M-cell workbook
+LAZILY_SCALE_VIEWPORT=1000 node bench/scale.bench.mjs
+BENCH_FORMAT=json node bench/scale.bench.mjs        # machine-readable output
+```
+
+Large `N` needs headroom for the V8 heap — run with
+`node --max-old-space-size=8192 bench/scale.bench.mjs` at 1M and `16384` at 5M.
+
+### Hardware / environment
+
+| | |
+|---|---|
+| CPU | AMD Ryzen 9 9950X3D (16 cores / 32 threads) |
+| RAM | 186 GiB |
+| OS | Linux 7.1.3 (CachyOS), x86-64 |
+| Node.js | 26.4.0 (V8) |
+
+### 1,000,000 rows (~2M cells / nodes)
+
+Peak RSS ~1.0 GiB (~550 B/node).
+
+| Benchmark | Time | Per cell | What it measures |
+|-----------|-----:|---------:|------------------|
+| `build` | ~0.90 s | ~450 ns | Construct all 2N nodes (each `Cell`/`Slot` allocates its own dependency structures — allocation- and GC-bound under V8). |
+| `cold_full_recalc` | ~0.65 s | ~650 ns | First read of every formula — forces every compute + edge-tracking. |
+| `viewport_recalc` | **~100 µs** | — | Edit one input, read only a 1,000-cell viewport. ~6,500× cheaper than a full cold recalc. |
+| `full_recalc_invalidate_all` | ~1.30 s | ~1.30 µs | Re-set every input, then recompute the whole sheet (worst-case full-sheet edit). |
+
+### 5,000,000 rows (10M cells — a full Google Sheets workbook)
+
+Google Sheets caps a workbook at **10,000,000 cells**. Modeled as 5,000,000
+input cells + 5,000,000 formula cells (`LAZILY_SCALE_N=5000000`). This is the
+**largest size actually measured** — no extrapolation. Peak RSS ~5.0 GiB.
+
+| Benchmark | Time | Per cell | What it measures |
+|-----------|-----:|---------:|------------------|
+| `build` | ~6.56 s | ~656 ns | Build the full 10M-node workbook (allocation/GC-bound). |
+| `cold_full_recalc` | ~3.37 s | ~674 ns | Compute all 5M formulas cold. |
+| `viewport_recalc` | **~106 µs** | — | Edit one input, read a 1,000-cell viewport. ~31,800× cheaper than a full cold recalc. |
+| `full_recalc_invalidate_all` | ~7.38 s | ~1.48 µs | Re-set every input, recompute the whole workbook. |
+
+So lazily-js backs a **full-capacity Google Sheets workbook** on V8: building it
+is the expensive part (~6.6 s, allocation/GC-bound — one JS object graph per
+node), but once built, a full cold recompute is ~3.4 s, and a one-cell edit +
+bounded-viewport read stays in the **~100 µs range**. The lazy pull-based model
+leaves off-viewport formulas dirty and never recomputes them — only ~2 formulas
+actually recompute per edit (the two that read the edited input), regardless of
+sheet size, which is exactly the property a viewport-rendered spreadsheet needs.
+
+### Spreadsheet cell-count context
+
+| Spreadsheet | Documented limit | Cells |
+|-------------|------------------|------:|
+| Google Sheets | 10,000,000 cells per workbook (18,278 columns max) | 10,000,000 |
+| Microsoft Excel | 1,048,576 rows × 16,384 columns per worksheet | 17,179,869,184 |
+
+The `LAZILY_SCALE_N=5000000` run above covers a full Google Sheets workbook. A
+grid-complete Excel worksheet (17 billion cells) is unrepresentative — real
+sheets populate a tiny fraction of the grid, and lazily only stores the cells you
+create, so the `scale` group measures the populated-cell path that matters.
+
+### Viewport scaling — flat
+
+lazily-js's viewport recalc is **effectively size-independent** (~100 µs at 2M
+nodes, ~106 µs at 10M nodes). The value cache is keyed by node identity, so both
+the ~1,000 viewport cache-hit reads and the ~2 actual recomputes are O(1) map
+operations that don't scale with total sheet size. This matches lazily-rs's and
+lazily-py's flat curves. At 10M cells a one-cell edit + 1,000-cell viewport read
+is ~31,800× cheaper than a full cold recalc and never touches off-viewport
+formulas.
+
+### Cross-language honesty
+
+V8 is heavier per node than compiled Rust (lazily-rs builds the same 2M-node
+graph in ~0.1 s vs ~0.9 s here) but far lighter than CPython (lazily-py's build
+is ~10.6 s at 1M). The recompute paths (`cold_full_recalc` ~650 ns/formula) are
+JIT-compiled and closer to the compiled bindings. These numbers are reported
+honestly, not to claim parity — the transferable result is the **shape**: the
+lazy-pull viewport property holds identically across all bindings (a one-cell
+edit + bounded-viewport read is microseconds, independent of sheet size).

package/README.md

@@ -39,6 +39,10 @@ notes and platform carve-outs lives in
 | Feature | Rust | Python | Kotlin | JS | Dart | Zig | Go | C++ |
 | --------- | :----: | :------: | :------: | :--: | :----: | :---: | :--: | :---: |
 | Reactive graph — `Cell` / `Slot` / `Signal` / `Effect` / memo / batch | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Reactive family (`ReactiveFamily`) — keyed cell/slot family + materialization mode (`#lzmatmode`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Thread-safe reactive family (`ThreadSafeReactiveFamily`) — `Send + Sync` keyed family + materialization confluence (`#lzmatmode`) | ✅ | — | — | — | — | — | — | — |
+| Async reactive family (`AsyncReactiveFamily`) — keyed family + eventual transparency (`#lzmatmode`) | ✅ | — | — | — | — | — | — | — |
+| Reactive family sync — membership propagation + materialize-on-ingest + derived-aggregate transparency (`#lzfamilysync`) | ✅ | — | ✅ | ✅ | — | — | — | — |
 | Thread-safe context (lock-backed) | ✅ | ✅ | ✅ | — | — | ✅ | ✅ | ✅ |
 | Async reactive context | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Flat state machine | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -46,21 +50,22 @@ notes and platform carve-outs lives in
 | Keyed cell collections (`CellMap` / `CellTree`) + reconcile | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Memoized semantic tree (`SemTree`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Stable-id alignment (manufactured identity) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Reactive queue (`QueueCell` SPSC/MPSC + `QueueStorage` adapter) | ✅ | — | ✅ | ✅ | — | ✅ | — | ✅ |
+| 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 | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
+| 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`) | ✅ | ✅ | ✅ | ~ | ~ | ✅ | ✅ | ✅ |
+| Shared-memory blob path (`ShmBlobArena`) | ✅ | ✅ | ✅ | ✅ | ~ | ✅ | ✅ | ✅ |
+| Cross-process zero-copy transport (`BlobBackend` / shm / arrow) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | 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`) | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
+| Message-passing + RPC command plane (`command-plane-v1`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | C-ABI FFI boundary | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ |
 | Permission boundary (`PeerPermissions` / `RemoteOp`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Capability negotiation (`SessionHandshake`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -74,8 +79,10 @@ and JSON Schemas in `lazily-spec` and the Lean models in `lazily-formal`.
 | Import | What it is |
 |--------|------------|
 | `@lazily-hub/lazily-js` | `lazily-spec` IPC wire types: `Snapshot`, `Delta`, `DeltaOp`, `IpcMessage` (`Snapshot` / `Delta` / `CrdtSync`), `NodeState`, `IpcValue`, `PeerPermissions`, `SessionHandshake`, `BINDING_CAPABILITIES` |
+| `@lazily-hub/lazily-js/transport` | Cross-process zero-copy transport (`#lzzcpy`): `ShmBlobArena`, `InProcessBackend` / `ArrowBackend`, `BlobRouter`, `spillMessage` / `resolveValue`, and the FFI-gated `createShmBackend` (Node/Bun/Deno). Isomorphic — no FFI import; browser-safe |
 | `@lazily-hub/lazily-js/reactive` | Reactive dependency graph: `Context`, `Cell`, `Slot`, `Signal`, `Effect` |
 | `@lazily-hub/lazily-js/reactive-async` | Async reactive graph: `AsyncContext` — Promise-driven slots/effects with revision-guarded stale-completion discard, in-flight dedup, and cancellation |
+| `@lazily-hub/lazily-js/reactive-family` | Unified keyed reactive family: `ReactiveFamily` (`EntryKind` cell/slot × `MaterializationMode` eager/lazy) + `cellFamily` input-cell specialization (`#lzmatmode`) |
 | `@lazily-hub/lazily-js/state-machine` | Flat finite-state-machine kernel backed by a reactive `Cell` |
 | `@lazily-hub/lazily-js/statechart` | Harel/SCXML chart interpreter plus `ChartBuilder`, `StateBuilder`, `TransitionBuilder` |
 | `@lazily-hub/lazily-js/collections` | `CellMap`, `CellTree`, keyed reconciliation, and LIS move minimization |
@@ -155,6 +162,44 @@ ctx.setCell(userId, 2); // supersedes any in-flight compute; slot re-resolves
 await ctx.getAsync(profile); // the profile for user 2
 ```
 
+## Reactive family and materialization mode
+
+`ReactiveFamily` (from `@lazily-hub/lazily-js/reactive-family`) is the unified
+**keyed reactive family** (`#lzmatmode`): it maps keys to per-entry reactive
+nodes and abstracts over the entry's handle kind. Two orthogonal axes:
+
+- **Entry kind** — `EntryKind.Cell` entries are input cells (**always
+  materialized**, any mode); `EntryKind.Slot` entries are derived slots (what
+  materialization governs). `cellFamily(...)` is the input-cell specialization.
+- **Materialization mode** — `MaterializationMode.Eager` (**default**) allocates
+  every derived node up front; `MaterializationMode.Lazy` (opt-in) allocates a
+  derived node on its **first read** ("materialize on pull") and caches it.
+
+Mode is **observationally transparent**: a read returns the same value under
+either mode — it changes allocation timing and memory, never results. Lazy pays
+off only for sparsely-touched large keyed address spaces.
+
+```js
+import { Context } from "@lazily-hub/lazily-js/reactive";
+import { ReactiveFamily } from "@lazily-hub/lazily-js/reactive-family";
+
+const ctx = new Context();
+
+// A derived (slot) family of key*3 over a large address space, built lazily:
+// nothing is allocated until a key is read.
+const fam = ReactiveFamily.lazy(ctx, range(0, 1_000_000), (k) => k * 3);
+fam.presentCount(); // 0
+
+fam.observe(5); // 15 — first read materializes just this entry
+fam.presentCount(); // 1
+fam.isPresent(5); // true
+fam.isPresent(6); // false
+
+// Eager builds the same values up front — observationally identical.
+const eager = ReactiveFamily.eager(ctx, [0, 1, 2, 3], (k) => k * 3);
+eager.observe(2) === fam.observe(2); // true
+```
+
 ## State machine and state charts
 
 `StateMachine` is the flat finite-state-machine kernel: a pure
@@ -344,6 +389,69 @@ signaling, and the WebRTC transport are shipped; C-ABI FFI is `none` because
 browser/Worker JS cannot host a native in-process ABI. The same payload types
 can still be carried by any transport a host application owns.
 
+## Cross-process zero-copy transport
+
+`@lazily-hub/lazily-js/transport` implements the pluggable blob-backend
+transport (`#lzzcpy`). A large payload is not copied through the wire codec: the
+producer **spills** it to a backend (which mints a `ShmBlobRef` descriptor) and
+ships only the descriptor; the receiver **routes** the descriptor by its
+`backend` discriminator and **resolves** it zero-copy — reading the backend's own
+bytes in place. `ShmBlobRef` gained an optional `backend` field (`shm` | `arrow`
+| `in_process`) that defaults to `shm` and is omitted from the wire, so every
+pre-transport descriptor round-trips byte-for-byte.
+
+The module is **isomorphic**: it imports no FFI, so it bundles and runs in the
+browser. `InProcessBackend`, `ArrowBackend`, the `BlobRouter`, and the
+spill/resolve policy are pure JS and available everywhere (including a
+main-thread ↔ Web Worker deployment).
+
+```js
+import {
+  BlobRouter,
+  InProcessBackend,
+  ArrowBackend,
+  spillMessage,
+} from "@lazily-hub/lazily-js/transport";
+import { Delta, DeltaOp, IpcMessage, IpcValue } from "@lazily-hub/lazily-js";
+
+const backend = new InProcessBackend(); // or ArrowBackend for columnar payloads
+const big = IpcValue.inline(new Uint8Array(4096));
+const { message, spilledBytes } = spillMessage(
+  IpcMessage.delta(new Delta({ baseEpoch: 0, epoch: 1, ops: [DeltaOp.slotValue(7, big)] })),
+  backend,
+); // message now carries a small SharedBlob descriptor; spilledBytes === 4096
+
+const router = new BlobRouter().register(backend);
+router.resolve(message.delta.ops[0].payload); // Uint8Array view, zero copy
+```
+
+The genuine **cross-process** `shm` backend (POSIX `shm_open` + `mmap`) is loaded
+lazily and only where a runtime provides FFI — Node (via `koffi`), Bun (`bun:ffi`),
+or Deno (`Deno.dlopen`, needs `--allow-ffi --unstable-ffi`). A peer process on the
+same host that attaches the same name resolves the descriptor without copying
+across the process boundary. In the browser (or any runtime without FFI)
+`createShmBackend` rejects with `ShmUnavailableError`; guard with `shmSupported()`
+and fall back to `InProcessBackend` / `ArrowBackend`.
+
+```js
+import { createShmBackend, shmSupported } from "@lazily-hub/lazily-js/transport";
+
+if (shmSupported()) {
+  const shm = await createShmBackend("my-session", { capacity: 1 << 20 });
+  const ref = shm.write(new Uint8Array([1, 2, 3])); // ref.backend === "shm"
+  // ...ship `ref` to a peer; the peer attaches `createShmBackend("my-session",
+  // { capacity: 1 << 20, create: false })` and calls `shm.readView(ref)`.
+  shm.close();
+}
+```
+
+All three runtimes are verified end-to-end, including cross-runtime interop: a
+Node process writes a region that a separate Deno process attaches and resolves,
+proving the layout is byte-identical across FFI implementations. The `shm` region
+is a bump-allocated arena with a fixed header (magic / version / capacity / epoch
+/ generation / cursor) and per-entry `{ generation, epoch, len, checksum }`
+validation.
+
 ## Distributed plane
 
 The `@lazily-hub/lazily-js/signaling` and `@lazily-hub/lazily-js/distributed`
@@ -384,7 +492,11 @@ 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 (incl. `TextCrdt` delta sync, `#lztextsync`:
 `textcrdt_convergence.json` + `textcrdt_delta_sync.json`), manufactured text
-identity, Harel state charts, the signaling protocol (`signaling/frames.json`,
+identity, the reactive family / materialization mode (`#lzmatmode`:
+`materialization/observational_transparency.json`,
+`materialization/deferral_not_deallocation.json`,
+`materialization/entry_kind_orthogonal_to_mode.json`), 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.
@@ -404,6 +516,7 @@ names the Lean theorems it mirrors:
 | `Reactive` | `reactive-properties.test.js` | `setCell_equal_preserves_graph`, `setCell_different_invalidates_dependents`, `recomputeSlot_equal_preserves_dependents`, `recomputeSlot_different_invalidates_dependents`, `signal_materialized_after_recompute` |
 | `Collection` | `collection-properties.test.js` | `setEntryValue_preserves_{membership,order,siblings}`, `moveKey_preserves_{membership,values}`, `moveKey_advances_order`, `addKey_advances_membership_and_order`, `Family.get_idempotent_after_first` |
 | `Tree` | `tree-properties.test.js` | `setNodeValue_preserves_{other_nodes,node_signals}`, `moveChild_preserves_{non_parent,parent_value}`, `moveChild_advances_order_signal_only` |
+| `Materialization` | `reactive-family.test.js` | `observe_canonical`, `eager_lazy_observationally_equivalent`, `eager_materializes_all`, `lazy_defers_slots`, `materialize_present_monotone`, `lazy_present_subset_eager`, `materialize_preserves_observe`, `cell_entries_materialized_in_every_mode`, `slot_entries_deferred_under_lazy` |
 | `Reconciliation` | `reconciliation-properties.test.js` | `lisBy_longest`, `reconcile_move_minimized`, `reconcile_stable_not_invalidated` |
 | `AsyncSlotState` | `reactive-async.test.js` | `stale_completeOk_discarded`, `current_completeOk_publishes`, `current_completeErr_to_error` |
 | `AsyncEffect` | `reactive-async.test.js` | `fire_blocked_during_cleanup`, `invalidate_from_idle_schedules`, `cleanupDone_resumes_deferred`, `dispose_absorbing`, `disposed_terminal` |
@@ -439,6 +552,31 @@ make check   # npm run build && npm test
   `lake` are present.
 - `npm test` runs the formal check and the Node test suite.
 
+## Benchmarks
+
+Wall-clock benchmarks live in [`BENCHMARKS.md`](BENCHMARKS.md), with two suites
+built on a zero-dependency `node:perf_hooks` harness:
+
+- **Micro-benchmarks** ([`bench/context.bench.mjs`](bench/context.bench.mjs)) — a
+  1:1 port of the single-threaded `Context` cases in lazily-rs's
+  `benches/context.rs` (cached reads, cold first get, dependency fan-out,
+  set-cell invalidation, memo equality suppression, effect flushing, batch
+  storms, typed cache reads) so JS and Rust numbers are directly comparable.
+- **Scale** ([`bench/scale.bench.mjs`](bench/scale.bench.mjs)) — a
+  spreadsheet-shaped graph (`N` input cells + `N` formula slots,
+  `formula[i] = input[i] + input[i - 1]`) mirroring the lazily-rs/-go/-py `scale`
+  groups. At the default `N = 1,000,000` that is ~2M reactive nodes; the
+  `LAZILY_SCALE_N=5000000` run covers a full 10M-cell Google Sheets workbook. A
+  one-cell edit + 1,000-cell viewport read stays ~100 µs **independent of sheet
+  size** — the lazy-pull property a viewport-rendered spreadsheet needs.
+
+```bash
+make bench          # micro-suite (prints a markdown table)
+make bench-scale    # scale suite at N = 1,000,000
+npm run benchmark-update   # refresh BENCHMARKS.md's generated micro-bench table
+npm run benchmark-check    # CI gate: exit 1 if the micro-bench row set is stale
+```
+
 ## See also
 
 - [`lazily-spec`][spec] - language-agnostic wire protocol, schemas, and

package/bench/scale.bench.mjs

@@ -0,0 +1,176 @@
+// Large-graph scale benchmark for lazily-js.
+//
+// Replicates the lazily-rs `scale` group (`benches/scale.rs`), the lazily-go
+// `scale` group, and lazily-py's `scale_bench.py` on a spreadsheet-shaped
+// graph: `N` input cells plus `N` formula slots, where
+// `formula[i] = input[i] + input[i - 1]` (local fan-in, like a column of
+// `=A_i + A_{i-1}`). With the default `N = 1_000_000` that is
+// ~2,000,000 reactive nodes. Four scenarios cover the spreadsheet lifecycle:
+//
+//   - build                     — construct all 2N nodes (formulas lazy, not yet computed).
+//   - cold_full_recalc          — first read of every formula (forces every compute + edge-tracking).
+//   - viewport_recalc           — edit one input, read only a bounded viewport (the lazy-pull win:
+//                                 off-viewport formulas stay dirty and never recompute).
+//   - full_recalc_invalidate_all — touch every input, then read every formula (worst-case full edit).
+//
+// Run as a script:
+//
+//   node bench/scale.bench.mjs
+//   LAZILY_SCALE_N=1000000 node bench/scale.bench.mjs
+//   LAZILY_SCALE_N=5000000 node bench/scale.bench.mjs   # Google Sheets 10M-cell workbook
+//   LAZILY_SCALE_VIEWPORT=1000 node bench/scale.bench.mjs
+//   BENCH_FORMAT=json node bench/scale.bench.mjs        # machine-readable output
+//
+// JS runs on a single event-loop thread; this is a single-threaded benchmark
+// (the concurrency surfaces are correctness-tested, not benchmarked here).
+
+import { performance } from "node:perf_hooks";
+import { Context } from "../src/reactive.js";
+import { blackBox } from "./harness.mjs";
+
+export function scaleN() {
+  const raw = Number(process.env.LAZILY_SCALE_N);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 1_000_000;
+}
+
+export function scaleViewport(n) {
+  const raw = Number(process.env.LAZILY_SCALE_VIEWPORT);
+  const vp = Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 1_000;
+  return Math.min(vp, n);
+}
+
+// Construct N input cells + N formula slots (formulas lazy, not yet computed).
+// formula[i] = input[i] + input[i - 1]; each read goes through ctx.getCell so
+// the running slot is auto-tracked as a dependent (dynamic edge discovery).
+export function buildScaleGraph(n) {
+  const ctx = new Context();
+  const inputs = new Array(n);
+  for (let i = 0; i < n; i++) inputs[i] = ctx.cell(i);
+  const formulas = new Array(n);
+  for (let i = 0; i < n; i++) {
+    const a = inputs[i];
+    const b = i > 0 ? inputs[i - 1] : inputs[0];
+    formulas[i] = ctx.computed(() => (ctx.getCell(a) + ctx.getCell(b)) >>> 0);
+  }
+  return { ctx, inputs, formulas };
+}
+
+function readAllFormulas(g) {
+  const { ctx, formulas } = g;
+  let acc = 0;
+  for (let i = 0; i < formulas.length; i++) acc = (acc + ctx.get(formulas[i])) >>> 0;
+  return acc;
+}
+
+function benchBuild(n) {
+  const start = performance.now();
+  const g = buildScaleGraph(n);
+  const elapsed = (performance.now() - start) / 1000;
+  const cells = 2 * n;
+  blackBox(g.formulas.length);
+  return {
+    name: "build",
+    n,
+    seconds: elapsed,
+    cells,
+    perCellNs: (elapsed / cells) * 1e9,
+    detail: `${cells.toLocaleString("en-US")} nodes`,
+  };
+}
+
+function benchColdFullRecalc(n) {
+  const g = buildScaleGraph(n);
+  const start = performance.now();
+  const sink = readAllFormulas(g);
+  const elapsed = (performance.now() - start) / 1000;
+  blackBox(sink);
+  return {
+    name: "cold_full_recalc",
+    n,
+    seconds: elapsed,
+    cells: n,
+    perCellNs: (elapsed / n) * 1e9,
+    detail: `${n.toLocaleString("en-US")} formulas`,
+  };
+}
+
+function benchViewportRecalc(n, samples = 1_000) {
+  const vp = scaleViewport(n);
+  const g = buildScaleGraph(n);
+  readAllFormulas(g); // warm the whole sheet once
+  const { ctx, inputs, formulas } = g;
+  const mid = Math.floor(n / 2);
+  const lo = Math.max(0, mid - Math.floor(vp / 2));
+  const hi = Math.min(n, lo + vp);
+  const window = formulas.slice(lo, hi);
+  const midInput = inputs[mid];
+  let acc = 0;
+  const start = performance.now();
+  for (let i = 0; i < samples; i++) {
+    ctx.setCell(midInput, i + 1); // edit one input (monotonic → passes PartialEq guard)
+    for (let j = 0; j < window.length; j++) acc = (acc + ctx.get(window[j])) >>> 0;
+  }
+  const elapsed = performance.now() - start; // ms total
+  blackBox(acc); // defeat dead-code elimination of the viewport reads
+  const perOpUs = (elapsed / samples) * 1000;
+  return {
+    name: "viewport_recalc",
+    n,
+    seconds: elapsed / 1000 / samples,
+    cells: vp,
+    perCellNs: null,
+    detail: `${perOpUs.toFixed(2)} us/edit, viewport=${vp}, ${samples} edits`,
+  };
+}
+
+function benchFullRecalcInvalidateAll(n) {
+  const g = buildScaleGraph(n);
+  readAllFormulas(g); // warm once
+  const { ctx, inputs } = g;
+  const start = performance.now();
+  for (let j = 0; j < inputs.length; j++) ctx.setCell(inputs[j], j + 1); // touch every input
+  const sink = readAllFormulas(g);
+  const elapsed = (performance.now() - start) / 1000;
+  blackBox(sink);
+  return {
+    name: "full_recalc_invalidate_all",
+    n,
+    seconds: elapsed,
+    cells: n,
+    perCellNs: (elapsed / n) * 1e9,
+    detail: `${n.toLocaleString("en-US")} inputs re-set + ${n.toLocaleString("en-US")} formulas recomputed`,
+  };
+}
+
+export function runScaleBenchmarks(n = scaleN()) {
+  return [
+    benchBuild(n),
+    benchColdFullRecalc(n),
+    benchViewportRecalc(n),
+    benchFullRecalcInvalidateAll(n),
+  ];
+}
+
+function fmtCell(perCellNs) {
+  return perCellNs == null ? "—" : `${perCellNs.toFixed(1).padStart(8)} ns/cell`;
+}
+
+function main() {
+  const n = scaleN();
+  const results = runScaleBenchmarks(n);
+  if (process.env.BENCH_FORMAT === "json") {
+    console.log(JSON.stringify({ n, nodes: 2 * n, results }, null, 2));
+    return;
+  }
+  console.log(
+    `lazily-js scale benchmarks (N=${n.toLocaleString("en-US")}, ${(2 * n).toLocaleString("en-US")} reactive nodes)`,
+  );
+  for (const r of results) {
+    const name = r.name.padEnd(28);
+    const size = `N=${n.toLocaleString("en-US").padStart(13)}`;
+    const ms = `${(r.seconds * 1000).toFixed(3).padStart(12)} ms`;
+    console.log(`${name} ${size}  ${ms}  ${fmtCell(r.perCellNs)}  ${r.detail}`);
+  }
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazily-hub/lazily-js",
-  "version": "0.7.0",
+  "version": "0.10.0",
   "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.",
   "license": "MIT",
   "repository": {
@@ -15,6 +15,10 @@
       "types": "./src/index.d.ts",
       "default": "./src/index.js"
     },
+    "./transport": {
+      "types": "./src/transport.d.ts",
+      "default": "./src/transport.js"
+    },
     "./reactive": {
       "types": "./src/reactive.d.ts",
       "default": "./src/reactive.js"
@@ -23,6 +27,10 @@
       "types": "./src/reactive-async.d.ts",
       "default": "./src/reactive-async.js"
     },
+    "./reactive-family": {
+      "types": "./src/reactive-family.d.ts",
+      "default": "./src/reactive-family.js"
+    },
     "./state-machine": {
       "types": "./src/state-machine.d.ts",
       "default": "./src/state-machine.js"
@@ -73,9 +81,10 @@
     }
   },
   "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/queue.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",
+    "build": "node --check src/index.js && node --check src/transport.js && node --check src/shm-backend.js && node --check src/reactive.js && node --check src/reactive-async.js && node --check src/reactive-family.js && node --check src/state-machine.js && node --check src/statechart.js && node --check src/collections.js && node --check src/queue.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",
+    "bench:scale": "node --max-old-space-size=8192 bench/scale.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"

package/src/distributed.d.ts

@@ -103,6 +103,17 @@ export class CrdtPlaneRuntime {
     since: Iterable<FrontierEntry | [PeerId, WireStamp | unknown]>,
   ): CrdtSync;
   syncReply(request: CrdtSync): CrdtSync;
+  // Family sync (#lzfamilysync)
+  registerFamilyLww(namespace: string): this;
+  membershipEpoch(): number;
+  familyKeys(namespace: string): string[];
+  familyValueLww(namespace: string, keySuffix: string): boolean | undefined;
+  familySetLww(
+    namespace: string,
+    keySuffix: string,
+    value: boolean,
+    nowMicros: number,
+  ): CrdtOp | null;
 }
 
 // --- Browser WebRTC platform adapter ---