@mmstack/primitives 21.6.1 → 21.7.0

package/README.md

@@ -183,6 +183,8 @@ The fork is a full store (`draft.store.user.name(...)`, `extendStore`, deep read
 
 > The fork inherits the base's `vivify` / `noUnionLeaves` and its injector-scoped proxy cache automatically, so its write semantics match the base. Pass them explicitly only to override (advanced).
 
+When the base is a synced store from `@mmstack/mesh`, a fork is also how an agent proposes a change for review. The agent writes to the fork, `ops()` is the staged change to render for a person, and `commit()` merges the approved change into the synced store. See the `@mmstack/mesh` README for the pattern.
+
 ### `toWritable`
 
 Turn any read-only `Signal<T>` into a `WritableSignal<T>` by providing custom `set` / `update` implementations. Powers `derived` internally; use it directly when you have a `computed` you want to expose as writable.

package/fesm2022/mmstack-primitives.mjs

@@ -4960,7 +4960,7 @@ const lww = (_ancestor, mine) => mine;
 const mergeThree = (ancestor, mine, theirs) => merge3(ancestor, mine, theirs);
 const preserve = (ancestor, mine, theirs) => ({ [CONFLICT_BRAND]: true, mine, theirs, ancestor });
 /**
- * Identity-aware array merge (op-protocol RFC §12 v0): reconciles two concurrent versions of
+ * Identity-aware array merge: reconciles two concurrent versions of
  * an array item-wise by a user-provided identity, instead of last-writer-wins on the whole
  * array. Items are matched by key; per-item fields merge via `merge3` against the ancestor
  * item; items added on either side survive; an item removed on either side and unedited on
@@ -4991,9 +4991,7 @@ function keyedArray(identity, opt) {
             const other = theirsMap.get(key);
             const base = ancMap.get(key);
             if (theirsMap.has(key)) {
-                out.push(structuralEq(item, other)
-                    ? item
-                    : mergeItem(base, item, other, ctx));
+                out.push(structuralEq(item, other) ? item : mergeItem(base, item, other, ctx));
             }
             else if (!ancMap.has(key) || !structuralEq(item, base)) {
                 out.push(item); // added by mine, or edited by mine while theirs removed it → keep
@@ -5064,7 +5062,7 @@ const compareStamp = (a, b) => {
 };
 const beats = (a, b) => compareStamp(a, b) > 0;
 /**
- * The unsequenced-topology convergence core (op-protocol RFC §4): a per-path last-writer-wins
+ * The unsequenced-topology convergence core: a per-path last-writer-wins
  * register map over the total order (hlc, writer), with subtree dominance. Order-independent:
  * any arrival order of the same envelope set yields the same state.
  */
@@ -5081,9 +5079,6 @@ function createConvergingApply(opt) {
             return winner;
         return { kind: 'set', path, next: resolved, prev: winner.next };
     };
-    // a sequential edit carries the value it overwrote; a mismatch means neither saw the other.
-    // Structural, not referential: identity never survives the wire, so a peer that built on
-    // the replicated copy of a value must still count as sequential.
     const concurrentWith = (incoming, registered) => {
         if (incoming.kind === 'delete' || registered.kind === 'delete')
             return false;
@@ -5093,7 +5088,11 @@ function createConvergingApply(opt) {
     };
     return {
         ingest: (env, o) => {
-            const stamp = { hlc: env.hlc, writer: env.writer, origin: env.origin };
+            const stamp = {
+                hlc: env.hlc,
+                writer: env.writer,
+                origin: env.origin,
+            };
             const out = [];
             for (const op of env.ops) {
                 const key = keyOf$1(op.path);
@@ -5140,7 +5139,12 @@ function createConvergingApply(opt) {
                         replays.push(reg);
                 }
                 replays.sort(compareStamp);
-                registers.set(key, { hlc: env.hlc, writer: env.writer, origin: env.origin, op: accepted });
+                registers.set(key, {
+                    hlc: env.hlc,
+                    writer: env.writer,
+                    origin: env.origin,
+                    op: accepted,
+                });
                 if (!o?.local) {
                     out.push(accepted);
                     for (const r of replays)
@@ -5162,7 +5166,7 @@ function getAtPath(root, path) {
     return cur;
 }
 /**
- * The shared rebase routine (op-protocol RFC §5): invert pending, apply remote, re-apply
+ * The shared rebase routine: invert pending, apply remote, re-apply
  * pending through the merge policies. Pure — branching's `rebase()` and the sequenced relay
  * client both call this.
  */
@@ -5224,31 +5228,75 @@ function opSync(source, opt) {
     const clock = opt.clock ?? createHlcClock();
     const conv = createConvergingApply({ policies: opt.policies });
     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 = [];
-    let version = 0;
+    const resolvedInjector = opt.driver
+        ? null
+        : (opt.injector ?? inject(Injector));
     const log = opLog(source, opt.driver
         ? { origin, driver: opt.driver }
-        : { origin, injector: opt.injector ?? inject(Injector) });
+        : { 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;
+    // a signal the drain reaction tracks; bumping it schedules an outbox drain for the next tick
+    const drainTick = signal(0, ...(ngDevMode ? [{ debugName: "drainTick" }] : /* istanbul ignore next */ []));
+    const scheduleDrain = () => drainTick.update((v) => v + 1);
+    const notify = (env) => {
+        for (const cb of [...subscribers])
+            cb(env);
+    };
+    const drainOutbox = () => {
+        for (const env of outbox.splice(0))
+            notify(env);
+    };
     const emitLocal = (ops) => {
+        const nextVersion = (versions.get(origin) ?? 0) + 1;
         const env = {
             proto: OP_PROTO_VERSION,
             origin,
             writer: opt.writer,
-            version: ++version,
+            version: nextVersion,
             hlc: clock.next(),
             policyVersion: opt.policyVersion ?? 0,
             ops,
         };
-        versions.set(origin, env.version);
+        versions.set(origin, nextVersion);
         conv.ingest(env, { local: true });
         recentLocal.push(env);
         if (recentLocal.length > RECENT_LOCAL_CAP)
             recentLocal.shift();
-        for (const cb of [...subscribers])
-            cb(env);
+        // mid-receive, or a drain still owed → queue (frozen stamp verbatim) instead of emitting now
+        if (canDefer && (receiving || outbox.length)) {
+            outbox.push(env);
+            scheduleDrain();
+            return;
+        }
+        notify(env);
     };
     const unsub = log.subscribe((batch) => emitLocal(batch.ops));
+    // fires on the tick after `scheduleDrain`: emits frozen local envelopes outside any receive frame
+    const drainRun = () => {
+        drainTick();
+        untracked(drainOutbox);
+    };
+    const drainRef = canDefer
+        ? effect(drainRun, { injector: resolvedInjector })
+        : null;
     return {
         origin,
         subscribe: (cb) => {
@@ -5264,7 +5312,6 @@ function opSync(source, opt) {
                 }
                 return;
             }
-            clock.observe(env.hlc);
             const known = versions.get(env.origin);
             if (known !== undefined && env.version <= known)
                 return; // duplicate/covered — idempotent
@@ -5272,12 +5319,27 @@ function opSync(source, opt) {
                 opt.onGap?.(env.origin, known + 1, env.version);
             }
             versions.set(env.origin, env.version);
+            receiving = true;
+            try {
+                // Freeze pending local FIRST — stamped by a clock that has NOT yet observed this remote, so
+                // the local write keeps its causally-independent (original) stamp rather than being lifted
+                // above the remote and always winning. Emission is deferred to a tick via the outbox; this
+                // only registers + stamps.
+                log.flush();
+                clock.observe(env.hlc);
+                const ops = conv.ingest(env);
+                // apply the converged result — a local write that LOST its path rolls back visibly here
+                if (ops.length)
+                    log.apply(ops);
+            }
+            finally {
+                receiving = false;
+            }
+        },
+        flush: () => {
+            drainOutbox();
             log.flush();
-            const ops = conv.ingest(env);
-            if (ops.length)
-                log.apply(ops);
         },
-        flush: () => log.flush(),
         watermark: () => Object.fromEntries(versions),
         snapshot: () => {
             log.flush();
@@ -5302,9 +5364,27 @@ function opSync(source, opt) {
             for (const e of pending)
                 conv.ingest(e, { local: true });
         },
+        restore: (envs, highWater) => {
+            let maxV = versions.get(origin) ?? 0;
+            for (const env of envs) {
+                if (env.origin !== origin)
+                    continue; // only this origin's own durable outbox
+                clock.observe(env.hlc); // keep the clock ≥ restored stamps before any future mint
+                log.apply(env.ops); // reflect the offline edit in the store, echo-free
+                conv.ingest(env, { local: true }); // register as a local winner (survives a reconnect merge)
+                recentLocal.push(env);
+                if (recentLocal.length > RECENT_LOCAL_CAP)
+                    recentLocal.shift();
+                maxV = Math.max(maxV, env.version);
+                notify(env); // hand to the transport to resend the unacknowledged tail
+            }
+            versions.set(origin, Math.max(maxV, highWater ?? 0));
+        },
         destroy: () => {
+            drainOutbox(); // don't silently drop frozen-but-unsent local writes
             unsub();
             subscribers.clear();
+            drainRef?.destroy();
             log.destroy();
         },
     };
@@ -5850,7 +5930,7 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
     return writable;
 }
 
-/** Op-mode sync for a writable store: hello exchange, then live envelopes (RFC §6 tab flavor). */
+/** Op-mode sync for a writable store: hello exchange, then live envelopes. */
 function storeTabSync(sig, opt, bus, injector) {
     const sync = opSync(sig, {
         writer: opt.writer ?? 'local',
@@ -5932,6 +6012,12 @@ function storeTabSync(sig, opt, bus, injector) {
 class MessageBus {
     channel = new BroadcastChannel('mmstack-tab-sync-bus');
     listeners = new Map();
+    constructor() {
+        inject(DestroyRef).onDestroy(() => {
+            this.channel.close();
+            this.listeners.clear();
+        });
+    }
     subscribe(id, listener) {
         const wrapped = (ev) => {
             try {
@@ -5962,10 +6048,6 @@ class MessageBus {
             post: (value) => this.channel.postMessage({ id, value }),
         };
     }
-    ngOnDestroy() {
-        this.channel.close();
-        this.listeners.clear();
-    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.12", ngImport: i0, type: MessageBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.12", ngImport: i0, type: MessageBus, providedIn: 'root' });
 }
@@ -5974,7 +6056,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.12", ngImpo
             args: [{
                     providedIn: 'root',
                 }]
-        }] });
+        }], ctorParameters: () => [] });
 /**
  * @deprecated The generated id hashes the call-site stack line, which collides when a shared
  * helper calls {@link tabSync} for multiple signals and diverges across minified builds during
@@ -6039,7 +6121,7 @@ function tabSync(sig, opt) {
     if (isPlatformServer(injector.get(PLATFORM_ID)))
         return sig;
     const id = typeof opt === 'string' ? opt : (opt?.id ?? generateDeterministicID());
-    const bus = injector.get(MessageBus);
+    const bus = optObj?.bus ?? injector.get(MessageBus);
     const storeKind = sig[STORE_KIND];
     if (storeKind === 'writable') {
         storeTabSync(sig, { ...optObj, id }, bus, injector);