@lazily-hub/lazily-js 0.9.0 → 0.11.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

@@ -40,6 +40,9 @@ notes and platform carve-outs lives in
 | --------- | :----: | :------: | :------: | :--: | :----: | :---: | :--: | :---: |
 | 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 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -549,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.9.0",
+  "version": "0.11.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": {
@@ -84,6 +84,7 @@
     "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 ---

package/src/distributed.js

@@ -20,7 +20,7 @@
 //   localUpdate→CrdtOp, ingest→count (op-log dedup by (node, stamp)), and the
 //   sync-frame pull protocol.
 
-import { CrdtOp, CrdtSync, IpcMessage, WireStamp } from "./index.js";
+import { CrdtOp, CrdtSync, IpcMessage, IpcValue, WireStamp } from "./index.js";
 import { Hlc } from "./seq-crdt.js";
 
 // Lexicographic (wall_time, logical, peer) order over two WireStamps.
@@ -255,6 +255,12 @@ function dedupKey(node, stamp) {
   return `${node}|${stamp.wallTime}|${stamp.logical}|${stamp.peer}`;
 }
 
+// Base node id for entries a family materializes on first remote observation
+// (#lzfamilysync). Family entry nodes are locally-private — keyed ops resolve by
+// key string, never by raw node id — so this only needs to avoid colliding with
+// application-assigned node ids; the runtime skips any id already in use.
+const FAMILY_NODE_BASE = 2 ** 48;
+
 /**
  * The live runtime that folds distributed CRDT anti-entropy frames into a set of
  * replicated root cells (port of lazily-rs `CrdtPlaneRuntime`). One runtime per
@@ -283,6 +289,12 @@ export class CrdtPlaneRuntime {
   #frontier = new Map();
   #membership = new Set();
 
+  // -- Family sync (#lzfamilysync) -----------------------------------------
+  #families = new Set();
+  #familyMembers = new Map();
+  #familyEpoch = 0;
+  #nextFamilyNode = FAMILY_NODE_BASE;
+
   constructor(peer) {
     this.#peer = assertPeerId(peer);
     this.#hlc = new Hlc(this.#peer);
@@ -348,6 +360,90 @@ export class CrdtPlaneRuntime {
     return this.#cells.get(node)?.value;
   }
 
+  // -- Family sync (#lzfamilysync) -----------------------------------------
+
+  // Register a last-writer-wins family under `namespace`. An inbound keyed op whose
+  // first key segment matches materializes a fresh entry on `ingest` (instead of
+  // being dropped/mis-addressed), so membership propagates and a derived aggregate
+  // over the family converges.
+  registerFamilyLww(namespace) {
+    this.#families.add(namespace);
+    if (!this.#familyMembers.has(namespace)) this.#familyMembers.set(namespace, []);
+    return this;
+  }
+
+  // The membership signal (#lzfamilysync), bumped whenever a family entry
+  // materializes — a derived aggregate over the family reads it so a remote-added
+  // key forces a recompute. A monotonically-increasing counter.
+  membershipEpoch() {
+    return this.#familyEpoch;
+  }
+
+  // The materialized keys of family `namespace`, in first-materialization order.
+  familyKeys(namespace) {
+    return [...(this.#familyMembers.get(namespace) ?? [])];
+  }
+
+  // The current converged boolean value of family entry `namespace/keySuffix`.
+  familyValueLww(namespace, keySuffix) {
+    const node = this.#keyToNode.get(`${namespace}/${keySuffix}`);
+    if (node === undefined) return undefined;
+    const iv = this.value(node);
+    if (iv === undefined || iv.bytes === undefined) return undefined;
+    return iv.bytes.length > 0 && iv.bytes[0] !== 0;
+  }
+
+  // Insert or update local LWW family entry `namespace/keySuffix` to boolean
+  // `value`, returning the CrdtOp to broadcast (or null for a value-preserving
+  // update). Materializes the entry (and bumps membership) on first insert.
+  familySetLww(namespace, keySuffix, value, nowMicros) {
+    const key = `${namespace}/${keySuffix}`;
+    let node = this.#keyToNode.get(key);
+    if (node === undefined) {
+      node = this.#mintFamilyNode();
+      this.register(node, key);
+      this.#recordFamilyMember(namespace, key);
+      this.#bumpFamilyEpoch();
+    }
+    return this.localUpdate(node, nowMicros, IpcValue.inline(Uint8Array.of(value ? 1 : 0)));
+  }
+
+  #mintFamilyNode() {
+    for (;;) {
+      const candidate = this.#nextFamilyNode;
+      this.#nextFamilyNode += 1;
+      if (!this.#cells.has(candidate)) return candidate;
+    }
+  }
+
+  #recordFamilyMember(namespace, key) {
+    const members = this.#familyMembers.get(namespace) ?? [];
+    if (!members.includes(key)) members.push(key);
+    this.#familyMembers.set(namespace, members);
+  }
+
+  #bumpFamilyEpoch() {
+    this.#familyEpoch += 1;
+  }
+
+  // If `op` is a keyed op for a registered family whose entry is not yet known,
+  // materialize it under a fresh locally-private node (indexed by the wire key) and
+  // return that node; otherwise fall back to the normal node resolution.
+  #resolveNodeForFamily(op) {
+    if (op.key !== null && op.key !== undefined && !this.#keyToNode.has(op.key)) {
+      const namespace = String(op.key).split("/")[0];
+      if (this.#families.has(namespace)) {
+        const node = this.#mintFamilyNode();
+        this.#keyToNode.set(op.key, node);
+        this.#nodeToKey.set(node, op.key);
+        this.#recordFamilyMember(namespace, op.key);
+        this.#bumpFamilyEpoch();
+        return node;
+      }
+    }
+    return this.#resolveNode(op);
+  }
+
   // The winning CrdtOp at `node`, or undefined.
   winningOp(node) {
     const cell = this.#cells.get(node);
@@ -420,7 +516,10 @@ export class CrdtPlaneRuntime {
         this.#hlc.recv(op.stamp, nowMicros);
       }
       this.#observeStamp(op.stamp);
-      const node = this.#resolveNode(op);
+      // Materialize-on-ingest (#lzfamilysync): a keyed op for a registered family
+      // whose entry is not yet known materializes it under a fresh local node
+      // instead of being mis-addressed to a colliding local family node.
+      const node = this.#resolveNodeForFamily(op);
       this.#cellFor(node).merge(op);
     }
     return applied;