@mmstack/primitives 21.9.3 → 21.10.0

package/README.md

@@ -766,7 +766,8 @@ const profile = persistedStore({ first: '', last: '' }, {
 `persistedStore` is `store()` + `persist()`. Reach for `persist(store, opt)` directly to add durability to a store you already have — one you also `meshSync`, or a worker-owned store's replica. Persistence is a reader over the op-log, so it composes with the other readers on the same store.
 
 ```typescript
-import { store, persist, meshSync } from '@mmstack/primitives';
+import { store, persist } from '@mmstack/primitives';
+import { meshSync } from '@mmstack/mesh';
 
 const doc = store({ title: '', body: '' });
 persist(doc, { key: 'draft', store: idbKeyval });     // durable to IndexedDB

package/fesm2022/mmstack-primitives.mjs

@@ -4286,7 +4286,7 @@ function generateOrigin$1() {
         return globalThis.crypto.randomUUID();
     return Math.random().toString(36).substring(2);
 }
-const isPlainArray$1 = (v) => Array.isArray(v) && !isOpaque(v);
+const isPlainArray$2 = (v) => Array.isArray(v) && !isOpaque(v);
 /**
  * Reference-identity-pruned structural diff — the same short-circuit discipline as `merge3`:
  * an untouched subtree kept its reference (the store's copy-on-write contract), so the walk
@@ -4311,7 +4311,7 @@ function diffNode(prev, next, path, ops) {
         }
         return;
     }
-    if (isPlainArray$1(prev) && isPlainArray$1(next)) {
+    if (isPlainArray$2(prev) && isPlainArray$2(next)) {
         // same length → per-index descent (matches `arr[i].x.set(...)` writes); a length
         // change is a whole unit — index attribution lies under insert/remove/reorder
         if (prev.length === next.length) {
@@ -4330,7 +4330,7 @@ function applyAt(container, path, idx, op) {
     const seg = path[idx];
     if (seg === '__proto__')
         return container;
-    const base = isPlainArray$1(container)
+    const base = isPlainArray$2(container)
         ? container.slice()
         : isRecord$1(container)
             ? { ...container }
@@ -5024,12 +5024,15 @@ function createHlcClock(now = Date.now) {
 }
 
 /**
- * Wire protocol version. Version 2 ops carry `cites` + `epoch` (the dot-citation register);
- * envelopes from other versions are dropped loudly: an op without citations cannot be merged
- * soundly (it would supersede nothing and its siblings would accumulate forever), so versions
- * are never silently mixed.
+ * Wire protocol version. Version 2 ops carry `cites` + `epoch` (the dot-citation register).
+ * Version 3 changes MATERIALIZATION semantics, not shape: grafts descend through plain arrays
+ * (per-index ops materialize instead of silently dropping) and the documented drop rule is
+ * enforced for non-plain ancestors — so a v2 replica and a v3 replica CANNOT converge on the
+ * same op set, which is exactly what the version fence exists to make loud. Envelopes from
+ * other versions are dropped loudly, and the tab-sync join protocol refuses to pair mismatched
+ * peers: versions are never silently mixed, in shape OR in meaning.
  */
-const OP_PROTO_VERSION = 2;
+const OP_PROTO_VERSION = 3;
 const CONFLICT_BRAND = '~mmstackConflict';
 function isConflicted(value) {
     return typeof value === 'object' && value !== null && CONFLICT_BRAND in value;
@@ -5286,7 +5289,14 @@ const mergeFold = (merge) => {
         return { kind: 'set', value: acc };
     };
 };
-const isContainer = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isPlainArray$1 = (v) => Array.isArray(v) && !isOpaque(v);
+/**
+ * The graft-side container admission. MUST equal `diffNode`'s descent set (plain records and
+ * plain non-opaque arrays) and `applyAt`'s copy set: emission, incremental apply and
+ * checkpoint materialization decide "container or leaf" identically, or a checkpoint-seeded
+ * replica and an incrementally-applied one disagree about the same op set.
+ */
+const isContainer = (v) => isPlainArray$1(v) || isRecord$1(v);
 /**
  * The unsequenced-topology convergence core: a dot-citation multi-value register per path.
  * An op supersedes exactly the sibling dots it cites; uncited concurrent writes stay live; a
@@ -5345,8 +5355,6 @@ function createConvergingApply(opt) {
         }
         return out.sort((a, b) => a.origin < b.origin ? -1 : a.origin > b.origin ? 1 : 0);
     };
-    // The live siblings a frontier had observed: those that arrived at or below its captured seq.
-    // Used by a fork commit so it supersedes only what it saw when it forked, not later writes.
     const liveObserved = (reg, frontier) => {
         const live = liveOf(reg);
         if (!frontier)
@@ -5354,11 +5362,6 @@ function createConvergingApply(opt) {
         const sm = seqs.get(keyOf$1(reg.path));
         return live.filter((s) => (sm?.get(s.origin) ?? 0) <= frontier.seq);
     };
-    // JSON of a tuple array, not a separator-joined string: `origin` is a caller-supplied value on a
-    // P2P peer, so a naive `origin@p.l#epoch` join lets a crafted origin collide the signatures of two
-    // distinct live sets. A collision makes refresh() skip a fold update, and since that skip is
-    // arrival-order-sensitive it breaks convergence. JSON.stringify escapes the strings and the array
-    // structure is unambiguous, so the signature is injective in the live set.
     const sigOf = (live) => JSON.stringify(live.map((s) => [s.origin, s.hlc.p, s.hlc.l, s.epoch, s.kind]));
     /** Recompute the fold cache; true iff the materialized result meaningfully changed. */
     const refresh = (reg) => {
@@ -5408,9 +5411,6 @@ function createConvergingApply(opt) {
         }
         return true;
     };
-    // A lone tombstone is droppable only if nothing else still materializes its key: no live
-    // descendant register would resurface, and no live ancestor `set` value still holds it. Mirrors
-    // the relay's retention twin so a client that prunes converges with a joiner seeded from the relay.
     const tombstoneDroppable = (key, reg) => {
         for (const [k, other] of registers) {
             if (k === key)
@@ -5438,31 +5438,37 @@ function createConvergingApply(opt) {
         }
         return undefined;
     };
-    // graft with the deterministic type-change rule: a graft whose parent location is not a plain
-    // record is DROPPED (the register stays intact and resurfaces if the container is restored)
     const graft = (tree, rel, res) => {
         if (!isContainer(tree))
             return tree;
         const head = String(rel[0]);
+        if (head === '__proto__')
+            return tree;
+        const copyOf = () => (isPlainArray$1(tree) ? tree.slice() : { ...tree });
         if (rel.length === 1) {
             if (res.kind === 'delete') {
                 if (!Object.hasOwn(tree, head))
                     return tree;
-                const copy = { ...tree };
+                const copy = copyOf();
                 delete copy[head];
                 return copy;
             }
-            return { ...tree, [head]: res.value };
+            const copy = copyOf();
+            copy[head] = res.value;
+            return copy;
         }
         if (!Object.hasOwn(tree, head)) {
-            // vivify an absent middle container so a checkpoint-seeded materialization matches a peer that
-            // applied the ops incrementally (incremental apply creates missing parents). A numeric next
-            // segment vivifies an array, else an object, mirroring the incremental apply path.
             const vivified = typeof rel[1] === 'number' ? [] : {};
-            return { ...tree, [head]: graft(vivified, rel.slice(1), res) };
+            const copy = copyOf();
+            copy[head] = graft(vivified, rel.slice(1), res);
+            return copy;
         }
         const child = graft(tree[head], rel.slice(1), res);
-        return child === tree[head] ? tree : { ...tree, [head]: child };
+        if (child === tree[head])
+            return tree;
+        const copy = copyOf();
+        copy[head] = child;
+        return copy;
     };
     /** Would a value at `rel` under `value` materialize, per the graft rules? */
     const graftable = (value, rel) => {
@@ -5564,9 +5570,7 @@ function createConvergingApply(opt) {
             const seq = ++ingestSeq;
             for (const op of env.ops) {
                 if (o?.frontier && compareHlc(env.hlc, o.frontier) <= 0)
-                    continue; // below the pruned horizon
-                // a delete or clear at the root has no parent register to abstain to; it can only blank the
-                // whole document, and materialize would then disagree with the delta path, so drop it
+                    continue;
                 if (!op.path.length && op.kind !== 'set')
                     continue;
                 const reg = regAt(op.path);
@@ -5831,15 +5835,8 @@ function opSync(source, opt) {
         origin,
     });
     const subscribers = new Set();
-    // per-origin high-watermark; `versions.get(origin)` IS the local emit counter, so a hydrate/restore
-    // that raises our own watermark also advances the next mint — no separate counter to drift out of
-    // sync and collide with a version acked before a reboot but dropped from a debounced outbox.
     const versions = new Map();
     const recentLocal = [];
-    // highest stability frontier this peer has pruned to. A remote envelope at or below it is a settled
-    // straggler (its state is compacted away); re-admitting one could resurrect a value below the
-    // frontier, and per-origin version dedup cannot catch a FIRST-CONTACT straggler (no prior entry),
-    // so the frontier is the admission gate that closes that hole on the receive path.
     let prunedFrontier;
     const resolvedInjector = opt.driver
         ? null
@@ -5847,17 +5844,6 @@ function opSync(source, opt) {
     const log = opLog(source, opt.driver
         ? { origin, driver: opt.driver }
         : { origin, injector: resolvedInjector });
-    // Local envelopes stamped + registered but not yet handed to the transport. A `receive` freezes
-    // this peer's pending writes here so it can ingest the remote WITHOUT emitting mid-receive — the
-    // synchronous re-entrant emission that used to scramble the relay's commit order. The outbox
-    // drains on a LATER tick, so emission always lands outside any receive callstack. Writes made
-    // while a drain is still owed queue here too, keeping wire order == version order (else a receiver
-    // would dedup the older, still-frozen envelope).
-    //
-    // Deferral rides an Angular effect, so it arms only on the injector path — the transport
-    // topologies (`tabSync`, `meshSync`) that actually re-enter through a relay. A custom `driver`
-    // (worker mirror, pure sim, multi-reader) owns its own scheduling and has no such re-entrancy, so
-    // it emits synchronously; the freeze-before-observe STAMPING fix below is identical either way.
     const canDefer = !opt.driver;
     const outbox = [];
     let receiving = false;
@@ -5942,11 +5928,6 @@ function opSync(source, opt) {
                 opt.onReject?.(env, reason);
                 return;
             }
-            // a settled straggler at or below the pruned stability frontier: reject it (its state is
-            // compacted, re-admitting could resurrect a below-frontier value). All ops in an envelope share
-            // its stamp, so the envelope hlc is the dot for every op. The live relay path never delivers a
-            // below-frontier op (a lagging client gets a snapshot, not a delta), so this only fires on a
-            // stray re-broadcast, e.g. over a P2P/multi-path topology.
             if (prunedFrontier && compareHlc(env.hlc, prunedFrontier) <= 0)
                 return;
             const known = versions.get(env.origin);
@@ -6019,10 +6000,6 @@ function opSync(source, opt) {
         },
         hydrate: (state, pending) => {
             log.flush();
-            // rebase this origin's uncovered local writes on top. A caller that keeps a durable outbox
-            // (meshSync, the worker replica) passes its full unacked set, so a long offline burst larger
-            // than the in-memory `recentLocal` cap is never dropped from the rebase; without it, fall back
-            // to the recent-local ring.
             const source = pending ?? recentLocal;
             const toReplay = source.filter((e) => e.version > (state.wm?.[e.origin] ?? 0));
             conv.reset();
@@ -6883,6 +6860,9 @@ function storeTabSync(sig, opt, bus, injector) {
     const { unsub, post } = bus.subscribe(opt.id, (msg) => {
         if (!msg || typeof msg !== 'object')
             return;
+        // the envelope lane has its own loud guard in `receive`; join messages are fenced here
+        if (msg.t !== 'env' && msg.proto !== OP_PROTO_VERSION)
+            return;
         switch (msg.t) {
             case 'env':
                 if (phase === 'joining')
@@ -6899,8 +6879,8 @@ function storeTabSync(sig, opt, bus, injector) {
                     const snap = sync.snapshot();
                     const covered = Object.entries(snap.wm).every(([origin, v]) => (msg.wm[origin] ?? 0) >= v);
                     post(covered
-                        ? { t: 'uptodate', to: msg.from }
-                        : { t: 'state', to: msg.from, state: snap });
+                        ? { t: 'uptodate', proto: OP_PROTO_VERSION, to: msg.from }
+                        : { t: 'state', proto: OP_PROTO_VERSION, to: msg.from, state: snap });
                 }, Math.random() * jitterMs);
                 responseTimers.set(msg.from, timer);
                 return;
@@ -6922,7 +6902,7 @@ function storeTabSync(sig, opt, bus, injector) {
         }
     });
     const unsubEnv = sync.subscribe((env) => post({ t: 'env', env }));
-    post({ t: 'hello', from: sync.origin, wm: sync.watermark() });
+    post({ t: 'hello', proto: OP_PROTO_VERSION, from: sync.origin, wm: sync.watermark() });
     helloTimer = setTimeout(goLive, helloTimeoutMs);
     injector.get(DestroyRef).onDestroy(() => {
         if (helloTimer !== undefined)