@optimystic/db-p2p 0.24.2 → 0.25.0

package/dist/src/storage/block-storage.js

@@ -1,5 +1,6 @@
-import { Latches, applyTransform, hashString } from "@optimystic/db-core";
+import { applyTransform, canonicalJson, hashString } from "@optimystic/db-core";
 import { mergeRanges } from "./helpers.js";
+import { RevisionNotCoveredError } from "./i-block-storage.js";
 import { createLogger } from "../logger.js";
 const log = createLogger('block-storage');
 /**
@@ -29,13 +30,34 @@ export class BlockStorage {
         const meta = await this.storage.getMetadata(this.blockId);
         return meta?.latest;
     }
+    /**
+     * Guard every write: the token must have been minted for THIS block and must still be live. The
+     * type already proves the caller went through `acquireBlockWriteLatch`; this catches the two
+     * things the type cannot — a token for block A presented to block B's storage, and a token
+     * stashed by a callback and used after its scope released the latch.
+     */
+    assertLatch(latch) {
+        if (latch.blockId !== this.blockId) {
+            throw new Error(`Block ${this.blockId}: write latch was acquired for block ${latch.blockId}`);
+        }
+        if (!latch.live) {
+            throw new Error(`Block ${this.blockId}: write latch has already been released`);
+        }
+    }
+    /**
+     * LOCAL-ONLY read — never fetches from a peer. A revision outside `meta.ranges` throws
+     * {@link RevisionNotCoveredError}; the one caller allowed to heal that (`StorageRepo.get`) does so
+     * with {@link restoreRevision} under the block's write latch and re-reads. Keeping the fetch out of
+     * here is what lets the commit path hold N block latches with no network I/O inside them.
+     */
     async getBlock(rev) {
         const meta = await this.storage.getMetadata(this.blockId);
         if (!meta) {
             // No metadata at all ⇒ this node has never seen the block, and reads report it absent
             // WITHOUT consulting `restoreCallback`. That is deliberate, not an oversight: `restoreCallback`
-            // is reachable only from ensureRevision below, so a never-seen block is never fetched HERE.
-            // Attempting a fetch at this layer would turn every read of a genuinely non-existent block —
+            // is reachable only from restoreRevision, which a caller invokes only after THIS method has
+            // reported a coverage gap on a block that has metadata — so a never-seen block is never fetched.
+            // Attempting a fetch for it would turn every read of a genuinely non-existent block —
             // the common case for an insert probing for a collision — into a network round trip, because
             // storage cannot tell "nobody has this" from "I don't have this".
             //
@@ -45,56 +67,71 @@ export class BlockStorage {
             // nothing beyond the latest-query it already performed. Keep this early return as-is.
             return undefined;
         }
-        // Pending-only state: metadata was seeded by savePendingTransaction but no revision has been
-        // committed yet. "No committed base here" is an ABSENCE, not a fault — nothing is being
-        // FAILED to reconstruct — so both arms below answer `undefined` rather than throwing, whether
-        // or not the caller named a revision. StorageRepo.get then applies any pending overlay over
-        // that absent base; a throw here would instead be caught into `unavailable: 'unmaterializable'`
-        // and a writer reading back its own not-yet-committed insert would be told it is unreadable.
-        // `unmaterializable` must keep its one meaning: records prove the block exists and this node
-        // cannot reconstruct it.
-        if (meta.latest === undefined) {
-            if (rev === undefined) {
-                return undefined;
-            }
-            // A named rev still ATTEMPTS the restore: `restoreCallback` may be able to supply that
-            // revision even though nothing is committed locally, and a successful restore serves real
-            // content with `latest` still undefined. That capability is pinned by the 'getBlock for an
-            // absent revision fires restoreCallback (restore not short-circuited)' test in
-            // test/block-storage.spec.ts — do not short-circuit it away.
-            //
-            // Only ensureRevision's FAILURE is swallowed (no callback wired, or restore could not
-            // supply the rev): that is precisely the "no committed base here" absence. materializeBlock
-            // below is deliberately OUTSIDE the try — a throw from there means revision records exist
-            // with no materialization anywhere under them, which is genuine corruption and must keep
-            // reading as `unmaterializable`.
-            //
-            // NOTE: a contextful read of a pending-only block still attempts a network restore before
-            // falling back to absent (same cost as the pre-fix throw path); if pending-only read-backs
-            // ever show as hot, short-circuit when ranges are empty.
-            try {
-                await this.ensureRevision(meta, rev);
-            }
-            catch (err) {
-                log('getBlock:no-committed-base blockId=%s rev=%d error=%s', this.blockId, rev, err instanceof Error ? err.message : String(err));
-                return undefined;
-            }
-            return await this.materializeBlock(meta, rev);
+        // Pending-only state (metadata seeded by savePendingTransaction, nothing committed) with no
+        // revision named: "no committed base here" is an ABSENCE, not a fault — answer `undefined`.
+        // StorageRepo.get then applies any pending overlay over that absent base. A NAMED rev on a
+        // pending-only block falls through: it is covered only if an earlier restore brought it in
+        // (a restore can serve real content with `latest` still undefined), otherwise it reports the
+        // gap below and StorageRepo.get decides whether the failed restore reads as absent.
+        if (meta.latest === undefined && rev === undefined) {
+            return undefined;
         }
         const targetRev = rev ?? meta.latest.rev;
-        await this.ensureRevision(meta, targetRev);
+        if (!this.inRanges(targetRev, meta.ranges)) {
+            throw new RevisionNotCoveredError(this.blockId, targetRev);
+        }
+        // A throw from here means revision records exist with no materialization anywhere under them —
+        // genuine corruption, which StorageRepo.get reports as `unmaterializable`.
         return await this.materializeBlock(meta, targetRev);
     }
+    async restoreRevision(rev, latch) {
+        this.assertLatch(latch);
+        // One metadata read, under the held latch: the caller's earlier `getBlock` observed a gap, but
+        // a queued-ahead restore or replica may have filled it before this latch was granted.
+        const meta = await this.storage.getMetadata(this.blockId);
+        if (!meta) {
+            // Same reasoning as getBlock's early return: a never-seen block is not restored here.
+            throw new Error(`Block ${this.blockId} has no metadata; a never-seen block is not restored here.`);
+        }
+        if (this.inRanges(rev, meta.ranges)) {
+            return;
+        }
+        const restored = await this.restoreBlock(rev);
+        // An archive off this wire is a peer's UNVERIFIED answer (see {@link saveRestored}), so it
+        // is vetted before a byte of it reaches storage. A rejected archive is indistinguishable to
+        // the caller from an absent one — same throw — because both mean the same thing: this node
+        // still cannot serve `rev`. The specific reason is logged rather than thrown so that
+        // `StorageRepo.get`'s healing helper keeps one rule for every restore failure.
+        const coverage = restored ? await this.vetRestoredArchive(restored, rev) : undefined;
+        if (!restored || !coverage) {
+            throw new Error(`Block ${this.blockId} revision ${rev} not found during restore attempt.`);
+        }
+        await this.saveRestored(restored);
+        // The vetted coverage, NOT `restored.range`. The declared range is checked for internal
+        // consistency above but is not what gets recorded — see {@link vetRestoredArchive} for why
+        // the pin has to be folded in, or the same restore repeats on every read forever.
+        meta.ranges.unshift(coverage);
+        meta.ranges = mergeRanges(meta.ranges);
+        await this.storage.saveMetadata(this.blockId, meta);
+    }
     async getTransaction(actionId) {
         return await this.storage.getTransaction(this.blockId, actionId);
     }
+    async getBlockProof(rev) {
+        return await this.storage.getBlockProof(this.blockId, rev);
+    }
+    async saveBlockProof(rev, proof, latch) {
+        this.assertLatch(latch);
+        await this.storage.saveBlockProof(this.blockId, rev, proof);
+    }
     async getPendingTransaction(actionId) {
         return await this.storage.getPendingTransaction(this.blockId, actionId);
     }
     async *listPendingTransactions() {
         yield* this.storage.listPendingTransactions(this.blockId);
     }
-    async savePendingTransaction(actionId, transform) {
+    async savePendingTransaction(actionId, transform, latch) {
+        this.assertLatch(latch);
         log('pend blockId=%s actionId=%s', this.blockId, actionId);
         let meta = await this.storage.getMetadata(this.blockId);
         if (!meta) {
@@ -102,23 +139,29 @@ export class BlockStorage {
             // nothing yet: seed empty ranges. The first commit anchors an OPEN-ENDED span at
             // the earliest held rev E ([E, +inf)); later commits/recover merge into it via
             // setLatest/recover. Seeding open-ended `[[0]]` would falsely claim coverage of the
-            // un-held revs below E and disable ensureRevision's restore path.
+            // un-held revs below E and disable restoreRevision's restore path.
+            //
+            // This read-then-seed is exactly the window a concurrent replica used to land in (the
+            // seed then erased its `latest`); the latch the caller holds is what closes it.
             meta = { latest: undefined, ranges: [] };
             await this.storage.saveMetadata(this.blockId, meta);
         }
         await this.storage.savePendingTransaction(this.blockId, actionId, transform);
     }
-    async deletePendingTransaction(actionId) {
+    async deletePendingTransaction(actionId, latch) {
+        this.assertLatch(latch);
         log('cancel blockId=%s actionId=%s', this.blockId, actionId);
         await this.storage.deletePendingTransaction(this.blockId, actionId);
     }
     async *listRevisions(startRev, endRev) {
         yield* this.storage.listRevisions(this.blockId, startRev, endRev);
     }
-    async saveMaterializedBlock(actionId, block) {
+    async saveMaterializedBlock(actionId, block, latch) {
+        this.assertLatch(latch);
         await this.storage.saveMaterializedBlock(this.blockId, actionId, block);
     }
-    async pruneSupersededMaterialization(prior) {
+    async pruneSupersededMaterialization(prior, latch) {
+        this.assertLatch(latch);
         const meta = await this.storage.getMetadata(this.blockId);
         // No metadata / no committed tip yet ⇒ nothing has superseded `prior`; leave it.
         if (!meta || meta.latest === undefined) {
@@ -136,14 +179,17 @@ export class BlockStorage {
         await this.storage.saveMaterializedBlock(this.blockId, prior.actionId, undefined);
         log('prune blockId=%s rev=%d actionId=%s', this.blockId, prior.rev, prior.actionId);
     }
-    async saveRevision(rev, actionId) {
+    async saveRevision(rev, actionId, latch) {
+        this.assertLatch(latch);
         await this.storage.saveRevision(this.blockId, rev, actionId);
     }
-    async promotePendingTransaction(actionId) {
+    async promotePendingTransaction(actionId, latch) {
+        this.assertLatch(latch);
         log('commit blockId=%s actionId=%s', this.blockId, actionId);
         await this.storage.promotePendingTransaction(this.blockId, actionId);
     }
-    async setLatest(latest) {
+    async setLatest(latest, latch) {
+        this.assertLatch(latch);
         const meta = await this.storage.getMetadata(this.blockId);
         if (!meta) {
             throw new Error(`Block ${this.blockId} not found`);
@@ -162,13 +208,14 @@ export class BlockStorage {
         // the un-held revs below E). Claim open-ended from the prior latest (>= E via merge); the first
         // commit (prevRev undefined) anchors the span at E = L. mergeRanges folds it into the existing
         // [E, +inf). Only revs BELOW E miss inRanges, which is exactly the genuine-gap/restore case.
-        // Range + latest advance in one saveMetadata write (atomic under the commit latch), so a crash
+        // Range + latest advance in one saveMetadata write (atomic under the block write latch), so a crash
         // before this call advances neither.
         meta.ranges.unshift([prevRev ?? latest.rev]);
         meta.ranges = mergeRanges(meta.ranges);
         await this.storage.saveMetadata(this.blockId, meta);
     }
-    async recover() {
+    async recover(latch) {
+        this.assertLatch(latch);
         const meta = await this.storage.getMetadata(this.blockId);
         if (!meta) {
             return { reconciled: false };
@@ -204,7 +251,8 @@ export class BlockStorage {
         }
         return { reconciled: false, latest: meta.latest };
     }
-    async saveReplica(block, source) {
+    async saveReplica(block, source, proof, latch) {
+        this.assertLatch(latch);
         const rev = source?.rev ?? 1;
         // Deterministic fallback id when the sender carried no revision metadata, so a
         // re-push of the same block resolves to the same (rev, actionId) and stays
@@ -213,9 +261,10 @@ export class BlockStorage {
         // Replica revision carries the materialized block. `{ insert: block }` satisfies saveRestored's
         // write invariants; on the serving path materializeBlock returns the materialized block directly
         // (single rev), so this transform is never applied — see ticket notes.
-        return await this.saveForwardRevision(rev, actionId, { action: { actionId, rev, transform: { insert: block } }, block }, 'replica');
+        return await this.saveForwardRevision(rev, actionId, { action: { actionId, rev, transform: { insert: block } }, block }, 'replica', proof);
     }
-    async saveDeletion(source) {
+    async saveDeletion(source, latch) {
+        this.assertLatch(latch);
         const { rev, actionId } = source;
         // Forward tombstone: a `{ delete: true }` transform and NO materialized block. saveRestored
         // skips materialization when `block` is absent, so the reverse-apply in materializeBlock
@@ -231,102 +280,84 @@ export class BlockStorage {
      * plus the materialized `block`; a deletion carries `{ delete: true }` and no block. `rev` and
      * `actionId` are passed alongside `body` because the guard and the `latest` advance need them
      * independently of the archive body.
+     *
+     * `verifiedProof` travels OUTSIDE `body` on purpose — see {@link saveRestored}: it is the one
+     * channel that persists a proof, and only {@link saveReplica} (whose caller verified the proof
+     * against `body.block`) supplies it.
      */
-    async saveForwardRevision(rev, actionId, body, logLabel) {
-        // Serialize the read-modify-write on this block's metadata (mirrors ensureRevision). saveReplica
-        // and saveDeletion deliberately SHARE this one lock id (keyed `saveReplica`, NOT per-method):
-        // both do a read-modify-write of `meta.latest`, so they must be mutually exclusive on this block
-        // to keep the monotonic guard sound against a concurrent replica+deletion.
-        const lockId = `BlockStorage.saveReplica:${this.blockId}`;
-        const release = await Latches.acquire(lockId);
-        try {
-            let meta = await this.storage.getMetadata(this.blockId);
-            // Monotonic guard: an equal-or-newer revision is already held. The block (or tombstone) is
-            // durably present; do not downgrade `latest` or rewrite the metadata.
-            if (meta?.latest && meta.latest.rev >= rev) {
-                log('%s:skip blockId=%s rev=%d held=%d', logLabel, this.blockId, rev, meta.latest.rev);
-                return meta.latest;
-            }
-            // One-revision archive. A replica's body carries the materialized block; a deletion's body
-            // omits it (forward tombstone). saveRestored skips materialization when `block` is absent,
-            // so a tombstone reverse-applies to an absent block (read back as undefined).
-            const archive = {
-                blockId: this.blockId,
-                revisions: {
-                    [rev]: body
-                },
-                range: [rev, rev + 1]
-            };
-            await this.saveRestored(archive);
-            // INVARIANT P: a block never holds a pending record AND a committed record for the same
-            // action id. On the commit path `promotePendingTransaction` maintains it by MOVING the
-            // record atomically; this forward path writes the committed transform directly (via
-            // saveRestored above), so it owes the deletion itself. Without it, a node that pended the
-            // action but diverged before committing keeps a record nothing can ever promote — reported
-            // as a phantom conflicting action by every later `pend` on the block, which under
-            // `policy: 'f'` refuses that node's participation in the block's writes permanently.
-            //
-            // Deliberately on the WRITE path only: the monotonic guard above returns before here, and
-            // that early return must stay a true no-op (the earlier call that wrote the revision is the
-            // one that owed the deletion). Deliberately here rather than in `saveRestored`, which is
-            // also reached from ensureRevision's historical restore under a different latch, where a
-            // deletion could race a concurrent promotePendingTransaction; this path holds
-            // `BlockStorage.saveReplica:<id>` and (via StorageRepo.saveReplicatedBlock) the per-block
-            // commit latch, so it is already mutually exclusive with a live commit.
-            //
-            // NOTE: deletes only this revision's actionId, not every pending whose action is already
-            // committed. A broader sweep would repair records orphaned by routes that do not carry the
-            // committing actionId; if orphaned pendings ever show up in the field on blocks whose
-            // committing action id differs, widen to a sweep over listPendingTransactions filtered by
-            // getTransaction.
-            await this.storage.deletePendingTransaction(this.blockId, actionId);
-            // Seed metadata when absent, advance latest, and merge the covered range.
-            const prevRev = meta?.latest?.rev;
-            if (!meta) {
-                meta = { latest: undefined, ranges: [] };
-            }
-            meta.latest = { rev, actionId };
-            // Open-ended coverage from the earliest held rev (see setLatest): the descending walk serves
-            // any rev >= the anchor. A prior latest at prevRev (< rev per the monotonic guard) is a
-            // materialized point, so anchor at prevRev; the first write (prevRev undefined) anchors at
-            // rev. Freshness of a stale replica is a separate (replication-lag) concern from what this
-            // node can locally reconstruct, which is exactly what ranges records.
-            meta.ranges.unshift([prevRev ?? rev]);
-            meta.ranges = mergeRanges(meta.ranges);
-            await this.storage.saveMetadata(this.blockId, meta);
-            log('%s:save blockId=%s rev=%d actionId=%s', logLabel, this.blockId, rev, actionId);
+    async saveForwardRevision(rev, actionId, body, logLabel, verifiedProof) {
+        // The read-modify-write of this block's metadata below is serialized by the write latch the
+        // caller already holds (asserted in saveReplica / saveDeletion) — the same latch every other
+        // writer of this block holds, so a concurrent replica, deletion, restore, commit, or pend
+        // cannot land inside the window between the read and the saveMetadata.
+        let meta = await this.storage.getMetadata(this.blockId);
+        // Monotonic guard: an equal-or-newer revision is already held. The block (or tombstone) is
+        // durably present; do not downgrade `latest` or rewrite the metadata.
+        //
+        // This skip returns before persisting anything, INCLUDING `verifiedProof` — deliberately.
+        // The proof was verified against the PUSHED bytes; persisting it here would attach it to
+        // this node's HELD materialization, whose bytes at the same `(rev, actionId)` may differ if
+        // this holder diverged. A stored proof whose declared digest contradicts local content makes
+        // this node serve content that fails its own proof, and `digest-mismatch` is ATTRIBUTABLE in
+        // `cluster/certified-claims.ts` — every receiver would penalize it.
+        //
+        // Back-filling a proof onto an already-held revision therefore happens one layer up, in
+        // `StorageRepo.saveReplicatedBlock`'s non-advancing branch, which routes it through
+        // `backFillProof` → `persistProofIfContentMatches` — the rule that persists only when the
+        // LOCAL materialization matches the digest the commit op declared. Keep this guard a true
+        // no-op; the digest check is what makes the back-fill safe, and it does not belong here.
+        if (meta?.latest && meta.latest.rev >= rev) {
+            log('%s:skip blockId=%s rev=%d held=%d', logLabel, this.blockId, rev, meta.latest.rev);
             return meta.latest;
         }
-        finally {
-            release();
-        }
-    }
-    async ensureRevision(meta, rev) {
-        if (this.inRanges(rev, meta.ranges)) {
-            return;
-        }
-        const lockId = `BlockStorage.ensureRevision:${this.blockId}`;
-        const release = await Latches.acquire(lockId);
-        try {
-            const currentMeta = await this.storage.getMetadata(this.blockId);
-            if (!currentMeta) {
-                throw new Error(`Block ${this.blockId} metadata disappeared unexpectedly.`);
-            }
-            if (this.inRanges(rev, currentMeta.ranges)) {
-                return;
-            }
-            const restored = await this.restoreBlock(rev);
-            if (!restored) {
-                throw new Error(`Block ${this.blockId} revision ${rev} not found during restore attempt.`);
-            }
-            await this.saveRestored(restored);
-            currentMeta.ranges.unshift(restored.range);
-            currentMeta.ranges = mergeRanges(currentMeta.ranges);
-            await this.storage.saveMetadata(this.blockId, currentMeta);
-        }
-        finally {
-            release();
+        // One-revision archive. A replica's body carries the materialized block; a deletion's body
+        // omits it (forward tombstone). saveRestored skips materialization when `block` is absent,
+        // so a tombstone reverse-applies to an absent block (read back as undefined).
+        const archive = {
+            blockId: this.blockId,
+            revisions: {
+                [rev]: body
+            },
+            range: [rev, rev + 1]
+        };
+        await this.saveRestored(archive, verifiedProof ? { rev, proof: verifiedProof } : undefined);
+        // INVARIANT P: a block never holds a pending record AND a committed record for the same
+        // action id. On the commit path `promotePendingTransaction` maintains it by MOVING the
+        // record atomically; this forward path writes the committed transform directly (via
+        // saveRestored above), so it owes the deletion itself. Without it, a node that pended the
+        // action but diverged before committing keeps a record nothing can ever promote — reported
+        // as a phantom conflicting action by every later `pend` on the block, which under
+        // `policy: 'f'` refuses that node's participation in the block's writes permanently.
+        //
+        // Deliberately on the WRITE path only: the monotonic guard above returns before here, and
+        // that early return must stay a true no-op (the earlier call that wrote the revision is the
+        // one that owed the deletion). Deliberately here rather than in `saveRestored`, which is
+        // also reached from restoreRevision's historical restore, where a held revision's pending
+        // record is not this writer's to delete. Both paths run under the block's write latch, so
+        // this deletion is already mutually exclusive with a live commit.
+        //
+        // NOTE: deletes only this revision's actionId, not every pending whose action is already
+        // committed. A broader sweep would repair records orphaned by routes that do not carry the
+        // committing actionId; if orphaned pendings ever show up in the field on blocks whose
+        // committing action id differs, widen to a sweep over listPendingTransactions filtered by
+        // getTransaction.
+        await this.storage.deletePendingTransaction(this.blockId, actionId);
+        // Seed metadata when absent, advance latest, and merge the covered range.
+        const prevRev = meta?.latest?.rev;
+        if (!meta) {
+            meta = { latest: undefined, ranges: [] };
         }
+        meta.latest = { rev, actionId };
+        // Open-ended coverage from the earliest held rev (see setLatest): the descending walk serves
+        // any rev >= the anchor. A prior latest at prevRev (< rev per the monotonic guard) is a
+        // materialized point, so anchor at prevRev; the first write (prevRev undefined) anchors at
+        // rev. Freshness of a stale replica is a separate (replication-lag) concern from what this
+        // node can locally reconstruct, which is exactly what ranges records.
+        meta.ranges.unshift([prevRev ?? rev]);
+        meta.ranges = mergeRanges(meta.ranges);
+        await this.storage.saveMetadata(this.blockId, meta);
+        log('%s:save blockId=%s rev=%d actionId=%s', logLabel, this.blockId, rev, actionId);
+        return meta.latest;
     }
     async materializeBlock(meta, targetRev) {
         let block;
@@ -373,11 +404,30 @@ export class BlockStorage {
             // NOTE: cold non-checkpoint historical reads re-replay every time (up to `checkpointInterval`
             // forward transforms). Acceptable — historical reads are rare and replay is depth-bounded. If
             // they ever show as hot, cache at the nearest checkpoint below the target instead of skipping.
-            // Read metadata FRESH for the retention decision: the `meta` passed in was captured by getBlock
-            // BEFORE ensureRevision, which may have restored the containing range during this same read
-            // (ensureRevision mutates its own re-read, not this snapshot). A stale `meta.ranges` would send
-            // rangeFloorOf into its fallback (treats the target as its own floor ⇒ wrongly "retained"),
-            // re-caching a rev the sweep means to prune — regrowing storage via reads of restored ranges.
+            // NOTE: this `saveMaterializedBlock` is the ONE named exclusion from the storage invariant that
+            // every write to a block holds `blockWriteLatchKey(blockId)` (see block-latch.ts). It runs on the
+            // READ path, unlatched, and that is safe for CONTENT because it is not a read-modify-write of
+            // anything: the key is `(blockId, actionId)` and the value is a deterministic replay of
+            // transforms this node has already retained, so a concurrent SAVE of the same key writes the
+            // same bytes. It touches neither the metadata blob nor any revision record, so it cannot
+            // clobber `latest`. Taking the latch here would put a lock acquisition on every cold historical
+            // read and would deadlock the callers that already hold it. Dropping the re-cache entirely is
+            // the other way to close the exclusion, and is out of scope until someone measures the cold
+            // historical-read cost of doing without it.
+            //
+            // NOTE: the one racer that does NOT write the same bytes at this key is
+            // `pruneSupersededMaterialization`, which DELETES it (saveMaterializedBlock(..., undefined)).
+            // Losing that race resurrects a materialization the sweep just removed — a bounded storage
+            // leak, never wrong content, since the resurrected bytes are a correct materialization of that
+            // rev. The fresh `retentionMeta` read below narrows the window but cannot close it: a commit
+            // can land and prune between that read and this save. If materialization storage is ever seen
+            // to grow under read load, close it by having the prune win — e.g. re-check retention inside
+            // the raw driver's save, or have the sweep re-run after the read.
+            //
+            // Read metadata FRESH for the retention decision: because this runs outside the block's write
+            // latch, a concurrent restore or commit may have moved `ranges` since `meta` was captured. A stale
+            // `meta.ranges` would send rangeFloorOf into its fallback (treats the target as its own floor
+            // ⇒ wrongly "retained"), re-caching a rev the sweep means to prune — regrowing storage via reads.
             const retentionMeta = (await this.storage.getMetadata(this.blockId)) ?? meta;
             const cacheRev = actions[0].rev;
             const latestRev = retentionMeta.latest?.rev ?? cacheRev;
@@ -394,15 +444,228 @@ export class BlockStorage {
             return undefined;
         return await this.restoreCallback(this.blockId, rev);
     }
-    async saveRestored(archive) {
+    /**
+     * Vet an archive fetched for a PINNED restore of `rev`, returning the revision coverage to record
+     * for it — or `undefined` when the archive must be refused, in which case nothing is written at
+     * all and the reason is logged.
+     *
+     * This is the whole trust boundary for the restore wire. `restoreBlock`'s
+     * `RestorationCoordinator` verifies nothing about a response (`queryPeer` returns
+     * `response.archive` straight through), so every field below is a remote peer's assertion, and
+     * `saveRestored` writes keyed by REVISION and by ACTION ID — meaning an archive naming a
+     * revision or action id this node already holds would otherwise overwrite content that was never
+     * in question. The checks, in order:
+     *
+     *  - **The archive is about this block.** `saveRestored` writes under `this.blockId` and ignores
+     *    `archive.blockId`, so an answer about a different block would land as this block's history.
+     *  - **Every revision key is a real revision.** Keys arrive as JSON strings; a non-numeric key
+     *    coerces to `NaN` and would be stored as a garbage revision number. Min/max are folded rather
+     *    than spread through `Math.min`/`Math.max`, which throws `RangeError` past ~125k arguments —
+     *    reachable inside the 8 MiB sync-response cap (see `maxArchiveRevision`, same hazard).
+     *  - **Each entry's own `rev`, when it declares one, agrees with the key it is filed under.**
+     *    That disagreement IS the mislabel this ticket's family of bugs is about, in miniature.
+     *  - **The archive answers the pin.** NOT "carries revision `rev`" — `ActionContext.rev` is a
+     *    COLLECTION-wide revision, so it routinely sits above the revision at which this particular
+     *    block last changed. A peer answering a pin at 9 for a block whose last commit was rev 2
+     *    correctly serves rev 2, labelled as rev 2 (pinned in `test/block-archive-proof.spec.ts`).
+     *    So the rule is that the archive's LOWEST revision is at or below the pin: `materializeBlock`
+     *    descends from `rev`, so an archive entirely above the pin answers a different question and
+     *    is exactly the "old bytes under a newer label" shape that overwrites good local data.
+     *  - **The declared `range` agrees with the revisions actually carried** — it starts at the
+     *    lowest (the floor must be present, or the descending walk has nothing to land on) and ends
+     *    past the highest. An OPEN-ENDED range is refused outright: it would claim infinite coverage
+     *    and permanently disable restore for this block on one unverified peer's say-so.
+     *    (`RestoreCallback` allows open-ended for the UNPINNED call; `restoreRevision` never makes one.)
+     *  - **Nothing already held is overwritten with different content** — see
+     *    {@link noDivergentRewrite}.
+     *
+     * ## What gets recorded, and the one thing taken on trust
+     *
+     * The coverage returned is `[lowest, rev + 1)` — the archive's floor, up to the PIN and no
+     * further. Both halves of that are deliberate.
+     *
+     * Extending UP to the pin is an INFERENCE, and the only one here: a peer
+     * answering a pinned fetch with revision M ≤ N means "M is my highest committed revision of this
+     * block at or below N", i.e. nothing changed in (M, N]. This node cannot verify that locally.
+     *
+     * It is recorded anyway because the alternative is worse. `meta.ranges` is what
+     * {@link restoreRevision} consults to decide whether to fetch at all, so recording only the
+     * archive's literal `[M, M+1)` leaves `inRanges(N)` false and re-runs the ENTIRE restore — network
+     * round trip plus a full `saveRestored` write — on every later read at that pin, forever, never
+     * converging. The inference is also unavoidable rather than merely convenient: having the peer
+     * state the claim on the wire instead would not make it verifiable, only explicit, while breaking
+     * repair against every peer running an older build.
+     *
+     * Stopping AT the pin, on the other hand, discards coverage for any revision the archive
+     * volunteered ABOVE it. Those entries are still WRITTEN — an honest peer serves a contiguous
+     * span, so an archive of `{2, 3, 4}` answering a pin at 3 is normal, not hostile — they are
+     * merely not CLAIMED. `rev` is the one number in the exchange this node chose, so it is as far as
+     * its trust in the answer should reach; recording `highest + 1` instead would let the peer set
+     * the width of its own credibility by padding the archive with fabricated high revisions, and
+     * reads across that padded span would then be served from local content without ever re-asking.
+     * The cost is one redundant fetch the first time a revision above the pin is read; that fetch is
+     * idempotent (identical content is not a conflict, see {@link noDivergentRewrite}) and the
+     * coverage converges.
+     *
+     * NOTE: accepted tradeoff — a lying peer's answer is therefore STICKY across the whole span it
+     * was asked about: reads between M and N are served locally from M's content and never re-ask, so
+     * a later honest peer is never consulted for them. Weighed against an unbounded re-fetch loop and
+     * kept; that is the same "ranges records what this node can locally reconstruct, freshness is a
+     * separate concern" position `setLatest` and `saveForwardRevision` already take. Revisit if a
+     * restore ever gains a way to verify an archive (a commit proof chain over the served revision
+     * would do it) — at that point record only what verifies.
+     */
+    async vetRestoredArchive(archive, rev) {
+        const refuse = (why, ...args) => {
+            log(`restore:refused blockId=%s rev=%d ${why}`, this.blockId, rev, ...args);
+            return undefined;
+        };
+        if (archive.blockId !== this.blockId) {
+            return refuse('archive is for blockId=%s', archive.blockId);
+        }
+        const entries = [];
+        let lowest;
+        let highest;
+        for (const [key, entry] of Object.entries(archive.revisions ?? {})) {
+            const entryRev = Number(key);
+            // `String(entryRev) === key`, not merely "parses as an integer". `saveRestored` re-derives
+            // the number with its own `Number(key)`, so any key with a second spelling (`"02"`, `" 2"`,
+            // `"2e1"`) lets ONE archive file two entries under one revision: the vet checks both, the
+            // write keeps whichever `Object.entries` yields last, and which one that is was never the
+            // question either check answered.
+            if (!Number.isInteger(entryRev) || entryRev < 1 || String(entryRev) !== key) {
+                return refuse('revision key %s is not a revision', key);
+            }
+            const action = entry?.action;
+            if (!action?.actionId) {
+                return refuse('revision %d carries no action', entryRev);
+            }
+            if (action.rev !== undefined && action.rev !== entryRev) {
+                return refuse('revision %d is filed under an action declaring rev=%d', entryRev, action.rev);
+            }
+            entries.push({ rev: entryRev, action, block: entry.block });
+            if (lowest === undefined || entryRev < lowest)
+                lowest = entryRev;
+            if (highest === undefined || entryRev > highest)
+                highest = entryRev;
+        }
+        if (lowest === undefined || highest === undefined) {
+            return refuse('carries no revisions');
+        }
+        if (lowest > rev) {
+            return refuse('lowest revision %d is above the pin', lowest);
+        }
+        const range = archive.range;
+        if (!Array.isArray(range)) {
+            return refuse('declares no range');
+        }
+        const [start, end] = range;
+        if (start !== lowest) {
+            return refuse('range starts at %o but revisions start at %d', start, lowest);
+        }
+        if (end === undefined || !Number.isInteger(end) || end <= highest) {
+            return refuse('range ends at %o but revisions end at %d', end, highest);
+        }
+        if (!await this.noDivergentRewrite(entries, refuse)) {
+            return undefined;
+        }
+        return [lowest, rev + 1];
+    }
+    /**
+     * True when none of `entries` would overwrite content this node ALREADY holds with different
+     * content. False (having logged which entry, via `refuse`) when any would.
+     *
+     * The refusal is all-or-nothing: one divergent entry rejects the WHOLE archive rather than
+     * landing the entries this node happens to lack. Two reasons. An archive that contradicts locally
+     * held content is evidence the peer is wrong or hostile about this block, which makes the rest of
+     * it no more trustworthy than the part that was caught; and a partial apply would leave
+     * {@link vetRestoredArchive}'s coverage claiming a span the applied subset may not support.
+     *
+     * Identical content is NOT a conflict — a re-restore of the same archive must stay idempotent,
+     * which it has to be for the pin-extended coverage above to converge.
+     *
+     * NOTE: accepted tradeoff — first writer wins, permanently. Once a revision record is held, no
+     * later archive can replace it, so a lying peer that answers a gap FIRST makes every honest
+     * archive restating that revision refuse forever: the revision becomes unreadable rather than
+     * wrong. That is the deliberate direction — this guard exists precisely so a peer cannot rewrite
+     * held history, and it cannot tell "the held copy is the lie" from "the incoming copy is". Repair
+     * from that state is an operator action (drop the block's local records and re-fetch). Revisit
+     * only alongside a way to verify an archive, which would let the guard prefer the provable copy
+     * instead of the earlier one.
+     *
+     * Comparison is by `canonicalJson`, db-core's one deterministic encoding, so key ORDER across a
+     * JSON round trip over the wire never reads as divergence.
+     *
+     * The three keys mirror {@link saveRestored}'s three writes exactly; an entry that carries no
+     * `block` writes no materialization, so it cannot clobber one and is not checked for it.
+     *
+     * NOTE: costs up to three raw-storage reads per revision entry, on the restore path only — which
+     * has already paid for a network round trip, so it is not the term that matters. If a restore
+     * ever carries thousands of revisions and this shows up, check `getRevision` first and skip the
+     * other two for a revision this node does not hold at all.
+     */
+    async noDivergentRewrite(entries, refuse) {
+        for (const { rev, action, block } of entries) {
+            const heldActionId = await this.storage.getRevision(this.blockId, rev);
+            if (heldActionId !== undefined && heldActionId !== action.actionId) {
+                refuse('revision %d is already held as action %s, archive names %s', rev, heldActionId, action.actionId);
+                return false;
+            }
+            const heldTransform = await this.storage.getTransaction(this.blockId, action.actionId);
+            if (heldTransform !== undefined && canonicalJson(heldTransform) !== canonicalJson(action.transform)) {
+                refuse('action %s (revision %d) is already held with a different transform', action.actionId, rev);
+                return false;
+            }
+            if (block) {
+                const heldBlock = await this.storage.getMaterializedBlock(this.blockId, action.actionId);
+                if (heldBlock !== undefined && canonicalJson(heldBlock) !== canonicalJson(block)) {
+                    refuse('action %s (revision %d) is already materialized with different content', action.actionId, rev);
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    /**
+     * Persist a fetched archive's revisions locally.
+     *
+     * A revision entry's own `proof` is deliberately IGNORED. An archive is remote wire data —
+     * {@link restoreBlock}'s `RestorationCoordinator` fetch verifies nothing, and a peer chooses
+     * what to attach — so persisting a proof read out of the archive body would re-serve a hostile
+     * peer's artifact as evidence this node retained itself. A proof reaches storage only through
+     * `verified`, passed out-of-band alongside the archive, which exactly one caller chain supplies:
+     * `cluster/reconcile-block.ts` → `StorageRepo.saveReplicatedBlock` → {@link saveReplica} →
+     * {@link saveForwardRevision}, where `certifyContent` had already bound the proof to these exact
+     * bytes. A separate parameter rather than a caller obligation to strip is what makes "an
+     * unverified proof reached `saveBlockProof`" unrepresentable instead of merely documented.
+     *
+     * This is a WRITER, not a gate: it trusts what it is handed, and each of its two callers is
+     * responsible for having earned that on its own terms.
+     *
+     *  - {@link restoreRevision} — the unverified restore wire — runs {@link vetRestoredArchive}
+     *    first. Those checks are ABOUT the pinned request (does the archive answer the revision that
+     *    was asked for?), and this function has no pin to check against, so they cannot live here.
+     *  - {@link saveForwardRevision} — reached by `saveReplica`/`saveDeletion` through
+     *    `StorageRepo.saveReplicatedBlock` — builds the archive it passes from local arguments, and
+     *    on the replica path `cluster/reconcile-block.ts` has already bound those bytes to a verified
+     *    proof. It writes strictly ABOVE its own `latest` (the monotonic guard returns first
+     *    otherwise), so it cannot rewrite held history, and it deliberately pays nothing for the
+     *    restore wire's checks.
+     *
+     * A THIRD caller would not inherit either argument. Any future one that takes an archive off a
+     * network must route through `vetRestoredArchive` (or an equivalent for its own trust model)
+     * before reaching here.
+     */
+    async saveRestored(archive, verified) {
         const revisions = Object.entries(archive.revisions)
             .map(([rev, data]) => ({ rev: Number(rev), data }));
-        // Save all revisions, actions, and materializations
+        // Save all revisions, actions, materializations, and the caller-verified proof (if any).
         for (const { rev, data: { action, block } } of revisions) {
             await Promise.all([
                 this.storage.saveRevision(this.blockId, rev, action.actionId),
                 this.storage.saveTransaction(this.blockId, action.actionId, action.transform),
-                block ? this.storage.saveMaterializedBlock(this.blockId, action.actionId, block) : Promise.resolve()
+                block ? this.storage.saveMaterializedBlock(this.blockId, action.actionId, block) : Promise.resolve(),
+                verified?.rev === rev ? this.storage.saveBlockProof(this.blockId, rev, verified.proof) : Promise.resolve()
             ]);
         }
     }