@optimystic/db-core 1.0.0-beta.2 → 1.0.0

package/dist/src/transactor/transactor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transactor.d.ts","sourceRoot":"","sources":["../../../src/transactor/transactor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC9J,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,MAAM,MAAM,qBAAqB,GAAG;IACnC,uEAAuE;IACvE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACzB;;;;OAIG;IACH,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAEpD,oCAAoC;IACpC,SAAS,CAAC,UAAU,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAEpE;;;;OAIG;IACH,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAEpD;;;;;;;OAOG;IACH,MAAM,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEtD;;;OAGG;IACH,oBAAoB,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACxE,CAAA"}
+{"version":3,"file":"transactor.d.ts","sourceRoot":"","sources":["../../../src/transactor/transactor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC7K,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,MAAM,MAAM,qBAAqB,GAAG;IACnC,uEAAuE;IACvE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACzB;;;;OAIG;IACH,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAEpD,oCAAoC;IACpC,SAAS,CAAC,UAAU,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAEpE;;;;OAIG;IACH,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAEpD;;;;;;;OAOG;IACH,MAAM,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEtD;;;OAGG;IACH,oBAAoB,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAExE;;;;;;;;;OASG;IACH,UAAU,CAAC,CAAC,GAAG,EAAE,YAAY,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACzE,CAAA"}

package/dist/src/transform/atomic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atomic.d.ts","sourceRoot":"","sources":["../../../src/transform/atomic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGtD,qBAAa,MAAM,CAAC,MAAM,SAAS,MAAM,CAAE,SAAQ,OAAO,CAAC,MAAM,CAAC;aACrC,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC;gBAAzB,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC;IAIrD,MAAM;CAYN"}
+{"version":3,"file":"atomic.d.ts","sourceRoot":"","sources":["../../../src/transform/atomic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGtD,qBAAa,MAAM,CAAC,MAAM,SAAS,MAAM,CAAE,SAAQ,OAAO,CAAC,MAAM,CAAC;aACrC,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC;gBAAzB,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC;IAIrD,MAAM;CAeN"}

package/dist/src/transform/atomic.js

@@ -7,15 +7,18 @@ export class Atomic extends Tracker {
         this.store = store;
     }
     commit() {
-        // Hand the bases pinned inside this atomic to the parent tracker BEFORE reset() wipes this
-        // store — without this, a single act() carrying more actions than the read cache holds loses
-        // digest coverage, because by the flush below the cache has already evicted the early bases.
-        // The parent gets a COPY (adopt), not this store itself: sharing the store would let the
-        // reset() below wipe the parent's pins a line before flushing into it.
-        if (this.store instanceof Tracker)
-            this.store.pins.adopt(this.pins);
-        const transform = this.reset();
-        applyTransformToStore(transform, this.store);
+        // A parent tracker takes the staged transform AND the bases pinned inside this atomic
+        // (Tracker.absorb): without the pins, a single act() carrying more actions than the read
+        // cache holds would lose digest coverage, the cache having evicted the early bases by the
+        // flush; and without absorb keeping them as the bases of the flushed operations, a base the
+        // cache moved on from between the pin and the flush would be re-pinned at the newer revision.
+        // Any other store just receives the transform.
+        if (this.store instanceof Tracker) {
+            this.store.absorb(this);
+        }
+        else {
+            applyTransformToStore(this.reset(), this.store);
+        }
     }
 }
 //# sourceMappingURL=atomic.js.map

package/dist/src/transform/atomic.js.map

@@ -1 +1 @@
-{"version":3,"file":"atomic.js","sourceRoot":"","sources":["../../../src/transform/atomic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAErD,MAAM,OAAO,MAA8B,SAAQ,OAAe;IACrC;IAA5B,YAA4B,KAAyB;QACpD,KAAK,CAAC,KAAK,CAAC,CAAC;QADc,UAAK,GAAL,KAAK,CAAoB;IAErD,CAAC;IAED,MAAM;QACL,2FAA2F;QAC3F,6FAA6F;QAC7F,6FAA6F;QAC7F,yFAAyF;QACzF,uEAAuE;QACvE,IAAI,IAAI,CAAC,KAAK,YAAY,OAAO;YAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpE,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC/B,qBAAqB,CAAC,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9C,CAAC;CAGD"}
+{"version":3,"file":"atomic.js","sourceRoot":"","sources":["../../../src/transform/atomic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAErD,MAAM,OAAO,MAA8B,SAAQ,OAAe;IACrC;IAA5B,YAA4B,KAAyB;QACpD,KAAK,CAAC,KAAK,CAAC,CAAC;QADc,UAAK,GAAL,KAAK,CAAoB;IAErD,CAAC;IAED,MAAM;QACL,sFAAsF;QACtF,yFAAyF;QACzF,0FAA0F;QAC1F,4FAA4F;QAC5F,8FAA8F;QAC9F,+CAA+C;QAC/C,IAAI,IAAI,CAAC,KAAK,YAAY,OAAO,EAAE,CAAC;YACnC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;aAAM,CAAC;YACP,qBAAqB,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACjD,CAAC;IACF,CAAC;CAGD"}

package/dist/src/transform/base-pins.d.ts

@@ -1,24 +1,37 @@
 import type { BlockId, IBlock } from "../index.js";
-/** The committed base of one block, captured at the moment an update for it was staged. */
+/** The committed base of one block, fixed at the moment the FIRST update for it was staged in a
+ * tracker. `rev` is the number the staged operations were computed against, and it never changes
+ * while those operations remain staged: a later change to what the source holds for the id marks
+ * the pin {@link moved} rather than replacing it (see {@link Tracker.revalidatePin}). */
 export type PinnedBase = {
-    /** Cloned base content. Callers MUST clone again before applying a transform — applyTransform
-     *  mutates, and the same pin is re-used by every retry attempt's digest pass. */
-    block: IBlock;
-    /** Committed revision of that base (CacheSource.getCachedRevision at pin time). */
+    /** Cloned base content. Absent for a REV-ONLY pin: the block was evicted from the read cache
+     *  between the read that computed the update and the update itself, so the revision is known
+     *  (the cache's per-id revision outlives the block) but the content is not — the base can be
+     *  declared, its digest cannot. Filled in if the same revision is later re-read.
+     *  Callers MUST clone before applying a transform — applyTransform mutates, and the same pin is
+     *  re-used by every retry attempt's digest pass. */
+    block?: IBlock;
+    /** Committed revision of the base (CacheSource.getCachedRevision at pin time). */
     rev: number;
-    /** Source drift generation at pin time (CacheSource.getGeneration). A pin whose generation no
-     *  longer matches the source's is STALE and must not be used. */
+    /** Source drift generation at the last validation (CacheSource.getGeneration). A generation
+     *  that no longer matches the source's means the source's content for the id changed hands
+     *  since; whether the BASE moved is decided by comparing revisions, not generations. */
     gen: number;
+    /** The source no longer describes this id at `rev`: the staged operations were computed on
+     *  content that is not the content any commit would now apply them to. Never repaired in
+     *  place — only a re-stage (which resets the owning tracker) clears it. */
+    moved?: true;
 };
 /** Per-transaction map of block id -> {@link PinnedBase}. Owned by a {@link Tracker}, shared by
  * reference across the trackers of one transaction (the collection's live tracker and each
  * per-attempt snapshot tracker), so a base pinned when an update was staged is still available
  * when the digest pass runs — regardless of whether the read cache has since evicted it.
  *
- * NOTE: memory shape — one cloned base block per update-carrying block, held from the first
- * update staged for it until the owning tracker's next reset(). Peak retention is proportional
- * to the transaction's own write footprint (the same set of blocks whose ids and ops the commit
- * request already carries), and every transaction boundary reclaims it via reset(). */
+ * NOTE: memory shape — one cloned base block per update-carrying block (one number per block for
+ * a rev-only pin), held from the first update staged for it until the owning tracker's next
+ * reset(). Peak retention is proportional to the transaction's own write footprint (the same set
+ * of blocks whose ids and ops the commit request already carries), and every transaction boundary
+ * reclaims it via reset(). */
 export declare class BasePins {
     private pins;
     /** The base source every `rev`/`gen` in here was read from — see {@link bindAuthority}. */
@@ -32,17 +45,37 @@ export declare class BasePins {
      * mistake impossible to make quietly. */
     bindAuthority(source: unknown): void;
     get(id: BlockId): PinnedBase | undefined;
+    ids(): IterableIterator<BlockId>;
     set(id: BlockId, pin: PinnedBase): void;
     delete(id: BlockId): void;
+    /** Record that the base under `id`'s staged operations has moved (see {@link PinnedBase.moved}).
+     * No-op for an unpinned id: with no pin there is no base to have moved from. */
+    markMoved(id: BlockId): void;
     /** Drop every pin whose id is not in `keep`. Called from Tracker.reset with the ids still
-     * carried by the new transforms' `updates`, so a rollback keeps its pins and a plain reset
-     * clears them. */
+     * carried by the new transforms' `updates`, so a rollback keeps its pins — moved marks
+     * included, the operations being the same operations — and a plain reset clears them. */
     retainOnly(keep: Iterable<BlockId>): void;
-    /** Copy every entry of `other` in, overwriting. Called from Atomic.commit so pins captured
-     * inside the atomic survive into the parent tracker's store. Overwriting is deliberate: the
-     * atomic's pin is the later observation of the same base chain, and the use-time freshness
-     * check re-validates it anyway. */
+    /** Fold every entry of `other` in. Called from Tracker.absorb (Atomic.commit) so pins captured
+     * inside the atomic survive into the parent tracker's store.
+     *
+     * An id the parent does not pin takes the atomic's pin. An id it pins at the SAME revision takes
+     * the atomic's too — the later observation of the same committed content — except that a clone
+     * the parent holds is never traded for a rev-only pin (same revision, same content; the clone is
+     * what makes the digest declarable). An id it pins at a DIFFERENT revision is a base that MOVED
+     * between the two actions: the parent's operations were computed on one content and the
+     * atomic's on another, and the combined list has no single base. The parent's pin is kept (its
+     * revision is what the earlier operations were built on) and marked moved, and a mark on either
+     * side survives the fold. */
     adopt(other: BasePins): void;
+    /** A copy for a staged-state snapshot (Collection.snapshotPending): the same entries, bound to
+     * the same source, in a store of its own. Entries are shared, not cloned — a pin's content is
+     * never mutated in place (every consumer clones before applying), and a moved mark set on a
+     * shared entry after the copy is a fact about the same operations. */
+    copy(): BasePins;
+    /** Make this store hold exactly `other`'s entries — the restore half of {@link copy}
+     * (Collection.restorePending), applied in place because the live tracker's store is shared by
+     * reference with every per-attempt tracker of the transaction. */
+    replaceWith(other: BasePins): void;
     get size(): number;
 }
 //# sourceMappingURL=base-pins.d.ts.map

package/dist/src/transform/base-pins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-pins.d.ts","sourceRoot":"","sources":["../../../src/transform/base-pins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEnD,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG;IACxB;qFACiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IACZ;qEACiE;IACjE,GAAG,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF;;;;;;;;uFAQuF;AACvF,qBAAa,QAAQ;IACpB,OAAO,CAAC,IAAI,CAAkC;IAC9C,2FAA2F;IAC3F,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,KAAK,CAAS;IAEtB;;;;;6CAKyC;IACzC,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IASpC,GAAG,CAAC,EAAE,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS;IAIxC,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI;IAIvC,MAAM,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI;IAIzB;;sBAEkB;IAClB,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,IAAI;IAOzC;;;uCAGmC;IACnC,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAS5B,IAAI,IAAI,IAAI,MAAM,CAEjB;CACD"}
+{"version":3,"file":"base-pins.d.ts","sourceRoot":"","sources":["../../../src/transform/base-pins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEnD;;;yFAGyF;AACzF,MAAM,MAAM,UAAU,GAAG;IACxB;;;;;wDAKoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ;;4FAEwF;IACxF,GAAG,EAAE,MAAM,CAAC;IACZ;;+EAE2E;IAC3E,KAAK,CAAC,EAAE,IAAI,CAAC;CACb,CAAC;AAEF;;;;;;;;;8BAS8B;AAC9B,qBAAa,QAAQ;IACpB,OAAO,CAAC,IAAI,CAAkC;IAC9C,2FAA2F;IAC3F,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,KAAK,CAAS;IAEtB;;;;;6CAKyC;IACzC,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IASpC,GAAG,CAAC,EAAE,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS;IAIxC,GAAG,IAAI,gBAAgB,CAAC,OAAO,CAAC;IAIhC,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI;IAIvC,MAAM,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI;IAIzB;oFACgF;IAChF,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI;IAK5B;;6FAEyF;IACzF,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,IAAI;IAOzC;;;;;;;;;;iCAU6B;IAC7B,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAc5B;;;0EAGsE;IACtE,IAAI,IAAI,QAAQ;IAOhB;;sEAEkE;IAClE,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAQlC,IAAI,IAAI,IAAI,MAAM,CAEjB;CACD"}

package/dist/src/transform/base-pins.js

@@ -3,10 +3,11 @@
  * per-attempt snapshot tracker), so a base pinned when an update was staged is still available
  * when the digest pass runs — regardless of whether the read cache has since evicted it.
  *
- * NOTE: memory shape — one cloned base block per update-carrying block, held from the first
- * update staged for it until the owning tracker's next reset(). Peak retention is proportional
- * to the transaction's own write footprint (the same set of blocks whose ids and ops the commit
- * request already carries), and every transaction boundary reclaims it via reset(). */
+ * NOTE: memory shape — one cloned base block per update-carrying block (one number per block for
+ * a rev-only pin), held from the first update staged for it until the owning tracker's next
+ * reset(). Peak retention is proportional to the transaction's own write footprint (the same set
+ * of blocks whose ids and ops the commit request already carries), and every transaction boundary
+ * reclaims it via reset(). */
 export class BasePins {
     pins = new Map();
     /** The base source every `rev`/`gen` in here was read from — see {@link bindAuthority}. */
@@ -30,15 +31,25 @@ export class BasePins {
     get(id) {
         return this.pins.get(id);
     }
+    ids() {
+        return this.pins.keys();
+    }
     set(id, pin) {
         this.pins.set(id, pin);
     }
     delete(id) {
         this.pins.delete(id);
     }
+    /** Record that the base under `id`'s staged operations has moved (see {@link PinnedBase.moved}).
+     * No-op for an unpinned id: with no pin there is no base to have moved from. */
+    markMoved(id) {
+        const pin = this.pins.get(id);
+        if (pin)
+            pin.moved = true;
+    }
     /** Drop every pin whose id is not in `keep`. Called from Tracker.reset with the ids still
-     * carried by the new transforms' `updates`, so a rollback keeps its pins and a plain reset
-     * clears them. */
+     * carried by the new transforms' `updates`, so a rollback keeps its pins — moved marks
+     * included, the operations being the same operations — and a plain reset clears them. */
     retainOnly(keep) {
         const keepSet = new Set(keep);
         for (const id of this.pins.keys()) {
@@ -46,18 +57,54 @@ export class BasePins {
                 this.pins.delete(id);
         }
     }
-    /** Copy every entry of `other` in, overwriting. Called from Atomic.commit so pins captured
-     * inside the atomic survive into the parent tracker's store. Overwriting is deliberate: the
-     * atomic's pin is the later observation of the same base chain, and the use-time freshness
-     * check re-validates it anyway. */
+    /** Fold every entry of `other` in. Called from Tracker.absorb (Atomic.commit) so pins captured
+     * inside the atomic survive into the parent tracker's store.
+     *
+     * An id the parent does not pin takes the atomic's pin. An id it pins at the SAME revision takes
+     * the atomic's too — the later observation of the same committed content — except that a clone
+     * the parent holds is never traded for a rev-only pin (same revision, same content; the clone is
+     * what makes the digest declarable). An id it pins at a DIFFERENT revision is a base that MOVED
+     * between the two actions: the parent's operations were computed on one content and the
+     * atomic's on another, and the combined list has no single base. The parent's pin is kept (its
+     * revision is what the earlier operations were built on) and marked moved, and a mark on either
+     * side survives the fold. */
     adopt(other) {
         if (other.authority !== this.authority) {
             throw new Error('BasePins.adopt across different base sources: pin revisions and generations are not comparable across them.');
         }
         for (const [id, pin] of other.pins) {
-            this.pins.set(id, pin);
+            const existing = this.pins.get(id);
+            if (existing === undefined || (existing.rev === pin.rev && !existing.moved)) {
+                this.pins.set(id, pin.block === undefined && existing?.block !== undefined ? { ...pin, block: existing.block } : pin);
+            }
+            else {
+                existing.moved = true;
+            }
         }
     }
+    /** A copy for a staged-state snapshot (Collection.snapshotPending): the same entries, bound to
+     * the same source, in a store of its own. Entries are shared, not cloned — a pin's content is
+     * never mutated in place (every consumer clones before applying), and a moved mark set on a
+     * shared entry after the copy is a fact about the same operations. */
+    copy() {
+        const copy = new BasePins();
+        if (this.bound)
+            copy.bindAuthority(this.authority);
+        for (const [id, pin] of this.pins)
+            copy.pins.set(id, pin);
+        return copy;
+    }
+    /** Make this store hold exactly `other`'s entries — the restore half of {@link copy}
+     * (Collection.restorePending), applied in place because the live tracker's store is shared by
+     * reference with every per-attempt tracker of the transaction. */
+    replaceWith(other) {
+        if (other.bound && other.authority !== this.authority) {
+            throw new Error('BasePins.replaceWith across different base sources: pin revisions and generations are not comparable across them.');
+        }
+        this.pins.clear();
+        for (const [id, pin] of other.pins)
+            this.pins.set(id, pin);
+    }
     get size() {
         return this.pins.size;
     }

package/dist/src/transform/base-pins.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-pins.js","sourceRoot":"","sources":["../../../src/transform/base-pins.ts"],"names":[],"mappings":"AAcA;;;;;;;;uFAQuF;AACvF,MAAM,OAAO,QAAQ;IACZ,IAAI,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC9C,2FAA2F;IACnF,SAAS,CAAU;IACnB,KAAK,GAAG,KAAK,CAAC;IAEtB;;;;;6CAKyC;IACzC,aAAa,CAAC,MAAe;QAC5B,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YACjB,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC;YACxB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACnB,CAAC;aAAM,IAAI,IAAI,CAAC,SAAS,KAAK,MAAM,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,yJAAyJ,CAAC,CAAC;QAC5K,CAAC;IACF,CAAC;IAED,GAAG,CAAC,EAAW;QACd,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC;IAED,GAAG,CAAC,EAAW,EAAE,GAAe;QAC/B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,MAAM,CAAC,EAAW;QACjB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACtB,CAAC;IAED;;sBAEkB;IAClB,UAAU,CAAC,IAAuB;QACjC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9B,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YACnC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC5C,CAAC;IACF,CAAC;IAED;;;uCAGmC;IACnC,KAAK,CAAC,KAAe;QACpB,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,6GAA6G,CAAC,CAAC;QAChI,CAAC;QACD,KAAK,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACpC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QACxB,CAAC;IACF,CAAC;IAED,IAAI,IAAI;QACP,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACvB,CAAC;CACD"}
+{"version":3,"file":"base-pins.js","sourceRoot":"","sources":["../../../src/transform/base-pins.ts"],"names":[],"mappings":"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"}

package/dist/src/transform/cache-source.d.ts

@@ -19,6 +19,19 @@ export declare class CacheSource<T extends IBlock> implements BlockSource<T> {
      *  so a hit records a read dependency at the right revision — the whole point of this map, since
      *  the underlying source is never consulted on a hit. */
     private revisions;
+    /** The most recent answer per id that this cache returned to a reader but did not keep — a
+     *  below-floor answer, content older than a log entry the collection already walked says the
+     *  block is (see {@link sourceServed}), or an answer overtaken while in flight over an id nothing
+     *  is held for (see {@link admit}). NEVER served to a read: {@link tryGet} re-asks the source
+     *  every time such an id is read, which is the whole point. It exists for the base probes alone
+     *  ({@link peek} / {@link getCachedRevision}): a write staged over this content must declare the
+     *  base it was really built on, at the revision it was really served at, so that the storage-side
+     *  guard which refuses a transform whose declared base is not the one the member holds can fire
+     *  instead of abstaining and applying edits computed against the old content over newer content.
+     *  An id is never in both this map and `cache`/`revisions`. It leaves on its next keepable answer,
+     *  on {@link clear}, and on any {@link transformCache} that touches it, so the map is bounded by
+     *  the source's unmet floors plus the ids caught mid-flight by a clear or a fold. */
+    private unkept;
     constructor(source: BlockSource<T>, maxSize?: number, 
     /** Shared per-transaction read-dependency accumulator (same instance the collection's
      *  TransactorSource holds). Optional: log-walk caches that never form a transaction omit it. */
@@ -33,19 +46,70 @@ export declare class CacheSource<T extends IBlock> implements BlockSource<T> {
     /** The current generation for an id — advances every time this cache's content for
      * the id changes (miss-load, clear, or transformCache). Stable across pure cache hits. */
     getGeneration(id: BlockId): number;
+    /** INVARIANT: what a read returns for an id is what this cache then describes for it — the
+     *  block {@link peek} answers and the revision {@link getCachedRevision} answers, immediately
+     *  after, are the content the reader holds, on every path (hit, kept, handed through, evicted
+     *  since). A write staged over the returned content pins that revision as its base, so a read
+     *  that returned one thing while the cache described another would put a wrong base on the
+     *  commit — the one direction the storage-side guard cannot catch. {@link admit} is where the
+     *  two are decided together. */
     tryGet(id: BlockId, purpose?: ReadPurpose): Promise<T | undefined>;
-    /** The block currently cached for `id`, without consulting the source. Cloned (callers apply ops
-     *  to it) and recency-neutral ({@link LruMap.peek}) — an observation pass must neither pay a
-     *  network read nor reshape eviction order. Records no read dependency: the caller that peeks
-     *  already read the block through {@link tryGet} (that is how it got cached), so the dependency
-     *  exists; a digest pass merely re-describes it. */
+    /** Decide, for an answer the source just gave for `id`, what the reader gets and what this cache
+     *  describes for the id from now on — one decision, so the two cannot come apart.
+     *
+     *  A keepable answer that is {@link stillWanted} is kept and returned. Otherwise the answer is
+     *  either below its floor or was overtaken while in flight, and of two answers to one id the
+     *  higher revision is the truer — so if content is HELD for the id (a concurrent read answered
+     *  well, a folded commit, or content that met a floor this answer does not), the held content is
+     *  what the reader gets, exactly as a hit a moment later would get it; the answer leaves no trace.
+     *  Held content is never older than a below-floor answer: raising a floor forgets the id in the
+     *  same step, so anything held for it since met the floor. With nothing held, the answer is
+     *  handed through (see {@link handThrough}): returned, described, not kept. */
+    private admit;
+    /** Whether an answer at `rev`, asked for when this id's generation was `generationAtMiss`, is
+     *  still one to keep now that it has arrived.
+     *
+     *  A miss is decided before the `await` and acted on after it. If the generation has not moved,
+     *  nothing happened to the id meanwhile and the answer is kept. If it has — a second read of the
+     *  id landed first, a refresh cleared it, a commit folded in ({@link transformCache}) — this answer
+     *  was asked for in a world that has since changed, and keeping it blindly is how old content gets
+     *  remembered for good: nothing clears a block but a log entry naming it, and that entry may be
+     *  the very thing that moved the generation. So it is then kept only to REPLACE strictly older
+     *  content (every answer to one source is for one view, so of two the higher revision is the
+     *  truer, whichever arrives last); what an overtaken answer's reader gets is {@link admit}'s call.
+     *  Only a CACHED id is compared: `revisions` outlives an LRU-evicted block (see its NOTE). */
+    private stillWanted;
+    /** A keepable answer: cached, and served to every later read of `id` until something clears it. */
+    private keep;
+    /** An answer this cache will not keep, over an id it holds nothing for: returned to this one
+     *  reader and described to the base probes (see {@link unkept}), but the next read of `id` asks
+     *  the source again. Only {@link admit} calls this, after establishing that nothing is held —
+     *  a cached id is never also in {@link unkept}.
+     *
+     *  Bumped like a load: the answer changes what this cache can say about the id, and the bump is
+     *  what sends a base pin or a materialized memo built on the previous answer back to be
+     *  re-judged. */
+    private handThrough;
+    /** The base this cache can describe for `id`, without consulting the source: the cached block,
+     *  or the content last handed through unkept (see {@link unkept}) — either way the content the
+     *  most recent {@link tryGet} of the id returned, unless it has been evicted since. Cloned
+     *  (callers apply ops to it) and recency-neutral ({@link LruMap.peek}) — an observation pass must
+     *  neither pay a network read nor reshape eviction order. Records no read dependency: the caller
+     *  that peeks already read the block through {@link tryGet} (that is how this cache learned it),
+     *  so the dependency exists; a digest pass merely re-describes it. */
     peek(id: BlockId): T | undefined;
-    /** The committed revision of the content currently cached for `id` — the source-reported
-     *  materialized revision learned on miss-load (see {@link revisions}), NOT the block's own
-     *  `state.latest.rev`. An LRU-evicted id can leave a stale entry here (see the NOTE on
-     *  {@link revisions}); callers must therefore require BOTH {@link peek} and this to be present —
-     *  {@link peek} returns `undefined` for the evicted id, so a stale revision never pairs with a
-     *  peeked block. */
+    /** Whether a later {@link tryGet} of `id` is answered from memory with the content this cache
+     *  holds now. `false` for content handed through unkept, which {@link peek} still describes — so
+     *  a consumer that would FREEZE a read result ({@link Tracker}'s materialized memo) asks this, not
+     *  {@link peek}. Recency-neutral. */
+    retains(id: BlockId): boolean;
+    /** The committed revision of the content this cache last served for `id` — the source-reported
+     *  materialized revision learned on miss-load (see {@link revisions}) or handed through
+     *  ({@link unkept}), NOT the block's own `state.latest.rev`. Answers for an LRU-evicted id too
+     *  (see the NOTE on {@link revisions}): that is the revision a write staged over the evicted
+     *  read was computed against, and what a rev-only base pin carries. {@link peek} returns
+     *  `undefined` for the evicted id, so the revision never pairs with content it does not describe.
+     *  `undefined` once the id has been cleared or folded away, or if it was never served. */
     getCachedRevision(id: BlockId): number | undefined;
     /** Upgrade an already-captured read of `id` to a `value` read in the shared collector,
      *  retaining it in the conflict set. The B-tree point-lookup descent calls this (through the

package/dist/src/transform/cache-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache-source.d.ts","sourceRoot":"","sources":["../../../src/transform/cache-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEjH,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6CAA6C,CAAC;AAc3F,qBAAa,WAAW,CAAC,CAAC,SAAS,MAAM,CAAE,YAAW,WAAW,CAAC,CAAC,CAAC;IAuBlE,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAEzC;oGACgG;IAChG,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IA1B5B,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACpC;;;;4FAIwF;IAKxF,OAAO,CAAC,WAAW,CAA8B;IACjD;;;;6DAIyD;IAIzD,OAAO,CAAC,SAAS,CAA8B;gBAG3B,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EACzC,OAAO,SAAiB;IACxB;oGACgG;IAC/E,SAAS,CAAC,EAAE,uBAAuB,YAAA;IACpD;;;;oDAIgD;IAChD,IAAI,CAAC,EAAE,aAAa,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IAW3C,OAAO,CAAC,IAAI;IAIZ;8FAC0F;IAC1F,aAAa,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM;IAI5B,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,GAAE,WAAqB,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IA8BjF;;;;wDAIoD;IACpD,IAAI,CAAC,EAAE,EAAE,OAAO,GAAG,CAAC,GAAG,SAAS;IAKhC;;;;;wBAKoB;IACpB,iBAAiB,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAIlD;;;;iGAI6F;IAC7F,aAAa,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI;IAIhC,UAAU,IAAI,OAAO;IAIrB,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW;IAIhE,KAAK,CAAC,QAAQ,GAAE,OAAO,EAAE,GAAG,SAAqB;IAgBjD;;;;qEAIiE;IACjE,eAAe,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IAQ9C;;mGAE+F;IAC/F,cAAc,CAAC,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM;CAsBtD"}
+{"version":3,"file":"cache-source.d.ts","sourceRoot":"","sources":["../../../src/transform/cache-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEjH,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6CAA6C,CAAC;AA4B3F,qBAAa,WAAW,CAAC,CAAC,SAAS,MAAM,CAAE,YAAW,WAAW,CAAC,CAAC,CAAC;IAwClE,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAEzC;oGACgG;IAChG,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IA3C5B,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACpC;;;;4FAIwF;IAKxF,OAAO,CAAC,WAAW,CAA8B;IACjD;;;;6DAIyD;IAQzD,OAAO,CAAC,SAAS,CAA8B;IAC/C;;;;;;;;;;;yFAWqF;IACrF,OAAO,CAAC,MAAM,CAAiD;gBAG3C,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EACzC,OAAO,SAAiB;IACxB;oGACgG;IAC/E,SAAS,CAAC,EAAE,uBAAuB,YAAA;IACpD;;;;oDAIgD;IAChD,IAAI,CAAC,EAAE,aAAa,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IAW3C,OAAO,CAAC,IAAI;IAIZ;8FAC0F;IAC1F,aAAa,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM;IAIlC;;;;;;oCAMgC;IAC1B,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,GAAE,WAAqB,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IA4BjF;;;;;;;;;;mFAU+E;IAC/E,OAAO,CAAC,KAAK;IAeb;;;;;;;;;;;kGAW8F;IAC9F,OAAO,CAAC,WAAW;IAYnB,mGAAmG;IACnG,OAAO,CAAC,IAAI;IAQZ;;;;;;;qBAOiB;IACjB,OAAO,CAAC,WAAW;IAOnB;;;;;;0EAMsE;IACtE,IAAI,CAAC,EAAE,EAAE,OAAO,GAAG,CAAC,GAAG,SAAS;IAKhC;;;yCAGqC;IACrC,OAAO,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO;IAI7B;;;;;;8FAM0F;IAC1F,iBAAiB,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAIlD;;;;iGAI6F;IAC7F,aAAa,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI;IAIhC,UAAU,IAAI,OAAO;IAIrB,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW;IAIhE,KAAK,CAAC,QAAQ,GAAE,OAAO,EAAE,GAAG,SAAqB;IAqBjD;;;;qEAIiE;IACjE,eAAe,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IAQ9C;;mGAE+F;IAC/F,cAAc,CAAC,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM;CA6BtD"}