@bitsocial/pubsub-voting 0.7.2 → 0.7.4

package/README.md

@@ -94,7 +94,7 @@ Construction throws `MissingPubsubError`, `MissingBlockstoreError`, or `MissingF
 ```ts
 const contest = await voter.createContest({ criteria });  // criteria: the contest's full document (strictly validated here)
 contest.on("update", () => render(contest.tally));        // tally rides the object; recomputed before each emit
-contest.on("error", (err) => showConnectivityWarning(err)); // tally chain read failed, the background verifier's RPC/resolver is down (retrying), or a deferred check evicted THIS wallet's own vote (VoteEvictedError)
+contest.on("error", (err) => showConnectivityWarning(err)); // tally chain read failed, the background verifier's RPC/resolver is down (retrying), a deferred check evicted THIS wallet's own vote (VoteEvictedError), or this node's persisted checkpoint could not be kept (SnapshotError)
 await contest.update();                                   // join the topic, cold-start, begin emitting
 // const fresh = await contest.getTally();                // or force a fresh read, bypassing the cache
 // await contest.stop();                                  // leave the topic

package/dist/client/voter.js

@@ -31,7 +31,7 @@ import { CID } from "multiformats/cid";
 import { makeTally } from "../tally/tally.js";
 import { ballotTypedData } from "../signer/eip712.js";
 import { criteriaCid, TOPIC_PREFIX } from "../topic.js";
-import { InvalidCommunityNameError, MissingChainClientError, UnknownRuleError, VoteEvictedError, VoterDestroyedError } from "../errors.js";
+import { InvalidCommunityNameError, MissingChainClientError, SnapshotError, UnknownRuleError, VoteEvictedError, VoterDestroyedError } from "../errors.js";
 /**
  * The recommended cadence, in buckets, at which a client should re-publish a live vote to keep
  * it alive: half its expiry window, rounded up. A bundle is valid for `voteExpiryBuckets` after
@@ -147,6 +147,22 @@ const COLD_START_REPULL_WINDOW_MS = HEARTBEAT_INTERVAL_MS;
  * `leave()` flushes whatever is still pending so a clean shutdown never loses the tail.
  */
 const SNAPSHOT_DEBOUNCE_MS = 10_000;
+/**
+ * How long to wait before re-attempting the bundles a snapshot restore could not admit for a
+ * TRANSIENT reason — an RPC outage during a seeder's boot burst, or a gating-chain head that has
+ * not yet reached a bundle's sample bucket (see {@link ContestEngine.#restoreSnapshot}). Backs off
+ * exponentially to {@link RESTORE_RETRY_CAP_MS} and keeps retrying while joined: giving up would
+ * mean either abandoning those votes or suppressing this topic's snapshot writes forever, and a
+ * retry costs one head read against a memoized bucket, so the patient option is also the cheap one.
+ */
+const RESTORE_RETRY_MS = 30_000;
+const RESTORE_RETRY_CAP_MS = 600_000;
+/**
+ * Snapshot write attempts (one per debounce window) before leaving it to the next winner-set
+ * change. A store that fails every write must not spin, but a topic quiet enough to never change
+ * again must not keep a stale snapshot forever because ONE write failed (issue #45).
+ */
+const SNAPSHOT_WRITE_ATTEMPTS = 3;
 /** Per-root chase deadline (ms): a multi-block directed-bitswap pull, coarser than one message. */
 const CHASE_TIMEOUT_MS = 30_000;
 /** Concurrent root chases; a spray of divergent roots queues, never floods. */
@@ -593,6 +609,19 @@ class ContestEngine {
     #heartbeatTimer;
     /** The armed (debounced) snapshot-write timer; flushed by `leave()`. See {@link #writeSnapshot}. */
     #snapshotTimer;
+    /** Consecutive failed snapshot writes in the current run (see {@link SNAPSHOT_WRITE_ATTEMPTS}). */
+    #snapshotWriteFailures = 0;
+    /**
+     * Bundles a restore decoded but could not admit for a TRANSIENT reason, awaiting
+     * {@link #restoreTimer}. Non-empty means the restore is INCOMPLETE, which suppresses the
+     * snapshot write: our view is missing votes the blob holds, and persisting it would overwrite
+     * the good blob with the partial one — the loss the retry exists to prevent (issue #45).
+     */
+    #restoreBacklog = [];
+    /** The armed restore-retry timer; cleared by `leave()`. */
+    #restoreTimer;
+    /** Consecutive restore retries, driving the backoff (reset by a complete restore). */
+    #restoreAttempts = 0;
     /**
      * Tears down the per-join `subscription-change` re-pull (listener + window timer); set by
      * {@link #armSubscriptionRepull}, cleared by `leave()` or by the window expiring.
@@ -662,9 +691,8 @@ class ContestEngine {
             nameResolutionCache: deps.nameResolutionCache,
             readHead: ({ chain }) => this.#readHead({ chain })
         });
-        // The gate/transport are (re)built on join(); the store, crdt, caches, verifier, and
-        // background verifier are stable per contest, so they survive re-joins of the topic.
-        this.#store = store;
+        // The gate/transport are (re)built on join(); the crdt, caches, verifier, and background
+        // verifier are stable per contest, so they survive re-joins of the topic.
         this.#cache = makeVerdictCache();
         this.#acceptedDedup = makeAcceptedDedup(this.#bucketMath);
         this.#verifier = verifier;
@@ -697,7 +725,6 @@ class ContestEngine {
             bucketBlockHash: () => this.#bucketBlockHash()
         });
     }
-    #store;
     /** Per gate leaf: hash of its canonical rule ref + chainId — its keyspace in the shared gate store. */
     #ruleIds;
     /** The gate's leaf refs in document order, aligned with {@link #ruleIds}. */
@@ -997,6 +1024,23 @@ class ContestEngine {
         if (i >= 0)
             this.#errorListeners.splice(i, 1);
     }
+    /**
+     * Drop decayed and superseded bundles from the CRDT **and** the per-bundle state keyed by
+     * their CIDs — one method because the two must not drift. `#checks` is not bookkeeping: it is
+     * what {@link #hasUnsettledChecks} reads (a leaked pending entry suppresses this contest's
+     * snapshot writes for a bundle that is no longer in the winner-set) and what the chase's
+     * `isAdmitted` reads (a leaked entry makes it skip a bundle we no longer hold). The join-time
+     * prune used to discard the removed CIDs — reachable in one restart: `verifyOffline` is
+     * deliberately expiry-blind (verify/bundle.ts), so a snapshot older than the expiry window
+     * restores its bundles and this prune removes them again moments later.
+     */
+    async #pruneDecayed() {
+        for (const removed of await this.#crdt.prune(this.#currentBucketCache)) {
+            const key = removed.toString();
+            this.#checks.delete(key);
+            this.#forgetOwnBundle(key); // expiry is decay, not an eviction — no error
+        }
+    }
     /** Compute the current ranking fresh (refreshing the bucket + pruning when state is present). */
     async computeTally() {
         // With state present, refresh the bucket so the tally's `current()` filters expiry against
@@ -1005,11 +1049,7 @@ class ContestEngine {
         // chain reads" property).
         if (this.#crdt.nodeCount() > 0) {
             await this.#refreshBucket();
-            for (const removed of await this.#crdt.prune(this.#currentBucketCache)) {
-                const key = removed.toString();
-                this.#checks.delete(key);
-                this.#forgetOwnBundle(key); // expiry is decay, not an eviction — no error
-            }
+            await this.#pruneDecayed();
         }
         return this.#tally.compute();
     }
@@ -1132,7 +1172,12 @@ class ContestEngine {
             verifyOffline: (bundle) => this.#verifier.verifyOffline(bundle),
             cache: this.#cache,
             isEvaluableNow: (bundle) => this.#isEvaluableNow(bundle),
-            hasBundle: (cid) => this.#store.has(cid),
+            // ADMISSION, not block presence (issue #44): our blockstore may hold a bundle's block
+            // while the winner-set does not know it — after a restart that lost the snapshot, an
+            // eviction, or a prune. Keyed on the blockstore, such a node skipped that bundle on
+            // every chase and never converged; `#checks` is the same admission map
+            // `#restoreSnapshot` consults, and it is dropped in lockstep with the CRDT's membership.
+            isAdmitted: async (cid) => this.#checks.has(cid.toString()),
             // `verified: false` is a provisional admit (offline checks only) whose deferred gate
             // read + name resolution ride `deferVerify`; `true` means a cached terminal verdict
             // already covers the full pipeline.
@@ -1181,7 +1226,7 @@ class ContestEngine {
         // constant-weight tally" property.
         if (this.#crdt.nodeCount() > 0) {
             await this.#refreshBucket();
-            await this.#crdt.prune(this.#currentBucketCache);
+            await this.#pruneDecayed();
         }
     }
     /**
@@ -1366,12 +1411,22 @@ class ContestEngine {
             clearTimeout(this.#heartbeatTimer);
         this.#heartbeatTimer = undefined;
         // Flush the debounced snapshot write so a clean shutdown persists the latest state
-        // (still skipped if checks are pending — the stale-but-good snapshot stays put).
+        // (still skipped if checks are pending, or a restore backlog is outstanding — the
+        // stale-but-good snapshot stays put). `retry: false`: a failed flush must not arm a
+        // timer that outlives the join.
         if (this.#snapshotTimer !== undefined) {
             clearTimeout(this.#snapshotTimer);
             this.#snapshotTimer = undefined;
-            await this.#writeSnapshot();
+            await this.#writeSnapshot({ retry: false });
         }
+        // Drop the restore backlog with its timer: a re-join re-reads the blob (still on disk,
+        // since the backlog suppressed every write that could have thinned it) and starts over.
+        if (this.#restoreTimer !== undefined)
+            clearTimeout(this.#restoreTimer);
+        this.#restoreTimer = undefined;
+        this.#restoreBacklog = [];
+        this.#restoreAttempts = 0;
+        this.#snapshotWriteFailures = 0;
         // Pause the background verifier's retry timer; pending state survives for a re-join.
         this.#background.stop();
         this.#disarmSubscriptionRepull();
@@ -1490,17 +1545,25 @@ class ContestEngine {
      * wire bytes plus the blocks it references (just re-put by the encode, read back from the
      * blockstore so no second copy is held in memory). Best-effort like every persistent-cache
      * write — a broken store degrades to the pre-persistence behavior (the cold-start pull),
-     * never an error.
+     * never an error — but not silent: a write that keeps failing surfaces as a `SnapshotError`
+     * on the contest's `error` event, because the state it fails to keep is invisible otherwise.
+     *
+     * Skipped while our view is knowably INCOMPLETE, in either of the two ways it can be, because
+     * a write in that window overwrites a good blob with a lossy one:
      *
-     * Skipped while ANY admitted bundle has a deferred check pending: the encoder serves only
-     * fully verified bundles, so writing mid-settlement would persist a snapshot that OMITS the
-     * pending ones — right after a restore (where every reloaded bundle is provisional) that
-     * would clobber a good snapshot with a near-empty one, and a crash in that window would lose
-     * the very votes persistence exists to keep. Every settlement and eviction re-marks the
-     * state changed, so the write that was skipped here is re-armed by the last one to land.
+     *   - ANY admitted bundle has a deferred check pending — the encoder serves only fully
+     *     verified bundles, so writing mid-settlement persists a snapshot that OMITS the pending
+     *     ones (right after a restore, where every reloaded bundle is provisional, that is a
+     *     near-empty snapshot). Every settlement and eviction re-marks the state changed, so the
+     *     skipped write is re-armed by the last one to land.
+     *   - a restore is still carrying a backlog ({@link #restoreBacklog}) — the blob holds votes
+     *     a transient failure kept us from admitting, and the retry owns them until it lands.
+     *
+     * `retry` is false on the `leave()` flush: a failed write there must not arm a timer that
+     * outlives the join.
      */
-    async #writeSnapshot() {
-        if (this.#hasUnsettledChecks())
+    async #writeSnapshot({ retry = true } = {}) {
+        if (this.#hasUnsettledChecks() || this.#restoreBacklog.length > 0)
             return;
         try {
             await this.rootRecord(); // (re-)encode so the cache reflects the current winner-set
@@ -1510,10 +1573,19 @@ class ContestEngine {
             if (cached === undefined)
                 return;
             await this.#deps.snapshots.set(this.topic, encodeSnapshot({ record: encodeRootRecord(cached.record), blocks: cached.blocks.map((block) => block.bytes) }));
+            this.#snapshotWriteFailures = 0;
         }
-        catch {
-            // Best-effort: a failed write leaves the previous snapshot in place; the next
-            // state change re-arms the debounce and retries.
+        catch (error) {
+            // The previous snapshot stays in place (a restart restores older state, never none).
+            // Retry on the debounce a couple of times rather than waiting for a winner-set change
+            // that a quiet topic may never see — then report and stop, so a dead store cannot spin.
+            this.#snapshotWriteFailures += 1;
+            if (retry && this.#snapshotWriteFailures < SNAPSHOT_WRITE_ATTEMPTS) {
+                this.#scheduleSnapshotWrite();
+                return;
+            }
+            this.#snapshotWriteFailures = 0;
+            this.#emitError(new SnapshotError("write-failed", this.topic, error));
         }
     }
     /**
@@ -1524,9 +1596,18 @@ class ContestEngine {
      * bundle re-passes the offline signature/constraint checks, and the deferred gate read +
      * name resolution ride the background verifier (mostly persisted-gate-cache hits on a
      * restart) — so the trust model is unchanged: this is the node's own previously-validated
-     * state, re-validated on load. A corrupt or version-mismatched blob is removed and the join
-     * proceeds empty, exactly as before persistence; the cold-start pull then still runs, so a
-     * stale snapshot self-heals by union with the live topic.
+     * state, re-validated on load. The cold-start pull still runs afterwards, so a stale snapshot
+     * self-heals by union with the live topic.
+     *
+     * **Only a provably bad blob is discarded** (issue #45). The decode is the whole of the
+     * corruption test, so it is the whole of what this catch covers: a truncated, mangled or
+     * version-mismatched blob is removed and the join proceeds empty, exactly as before
+     * persistence. Everything after it — the per-bundle admission, which reads the gating chain —
+     * runs under {@link #admitRestored}, where a transient failure yields a RETRY and never a
+     * delete. The distinction is the incident: the two catches used to be one, so a momentary RPC
+     * failure during a seeder's boot burst (64 topics restoring at once, one rate-limit window)
+     * permanently discarded a topic's persisted votes and the node came up empty on a topic every
+     * other peer still served.
      */
     async #restoreSnapshot() {
         let blob;
@@ -1538,43 +1619,108 @@ class ContestEngine {
         }
         if (blob === undefined)
             return;
+        let winners;
         try {
             const snapshot = decodeSnapshot(blob);
             const record = decodeRootRecord(snapshot.record);
             const byCid = new Map();
             for (const bytes of snapshot.blocks)
                 byCid.set((await blockForBytes(bytes)).cid.toString(), bytes);
-            const winners = await decodeCheckpoint(record.root, async (cid) => byCid.get(cid.toString()), record.chunks);
-            const pending = [];
-            for (const bundle of winners) {
-                // Same two-stage admit as the chase (see transport/chase.ts): offline checks
-                // synchronously before admit, chain/name checks deferred and batched. Admission
-                // goes through `crdt.add` (which stores the block AND registers the bundle) — a
-                // merge-by-CID would re-read through the blockstore, which the restore must not
-                // depend on: it may be fresh (the incident's in-memory case) or hold the block
-                // already (a persistent one), neither of which says the CRDT knows the bundle.
+            winners = await decodeCheckpoint(record.root, async (cid) => byCid.get(cid.toString()), record.chunks);
+        }
+        catch (error) {
+            // Corrupt, truncated, or version-mismatched blob: discard it and join empty — the
+            // pre-persistence behavior. Never let a bad snapshot block the join.
+            void this.#deps.snapshots.remove(this.topic).catch(() => { });
+            this.#emitError(new SnapshotError("discarded", this.topic, error));
+            return;
+        }
+        this.#restoreAttempts = 0;
+        await this.#admitRestored(winners);
+    }
+    /**
+     * Admit a decoded snapshot's bundles, one independently of the next. Three outcomes per
+     * bundle, and the whole point of the method is that they stay distinct:
+     *
+     *   - **admitted** — the same two-stage admit as the chase (transport/chase.ts): offline
+     *     checks synchronously before admit, chain/name checks deferred and batched. Admission
+     *     goes through `crdt.add` (which stores the block AND registers the bundle) — a
+     *     merge-by-CID would re-read through the blockstore, which the restore must not depend
+     *     on: it may be fresh (the incident's in-memory case) or hold the block already (a
+     *     persistent one), neither of which says the CRDT knows the bundle.
+     *   - **dropped** — the offline checks REFUSED it. That is a verdict on the bundle, not on
+     *     the environment, and no retry changes it.
+     *   - **backlogged** — a transient failure: the read that decides evaluability threw (an RPC
+     *     outage), or our gating-chain head has not yet reached the bundle's sample bucket. Those
+     *     go to {@link #restoreBacklog}, which suppresses the snapshot write and arms a retry;
+     *     dropping them silently is how a restart's ballots disappeared with the blob intact.
+     */
+    async #admitRestored(winners) {
+        const pending = [];
+        const backlog = [];
+        for (const bundle of winners) {
+            try {
                 const cid = await bundleCidForBytes(encodeBundle(bundle));
                 if (this.#checks.has(cid.toString()))
                     continue; // already admitted (a re-join)
-                if (!(await this.#isEvaluableNow(bundle)))
+                if (!(await this.#isEvaluableNow(bundle))) {
+                    backlog.push(bundle); // our head is behind the ballot: retry, do not forget it
                     continue;
+                }
                 const offline = await this.#verifier.verifyOffline(bundle);
                 if (!offline.valid)
-                    continue;
+                    continue; // the bundle's own fault — a sibling's admit stands
                 await this.#crdt.add(bundle);
                 this.#recordChecks(cid, bundle, false);
                 pending.push({ cid, bundle });
             }
-            if (pending.length > 0) {
-                this.#background.enqueue(pending);
-                this.#onStateChanged();
+            catch {
+                // Infrastructure, not the bundle (a chain read, a blockstore write): keep it.
+                backlog.push(bundle);
             }
         }
-        catch {
-            // Corrupt, truncated, or version-mismatched blob: discard it and join empty — the
-            // pre-persistence behavior. Never let a bad snapshot block the join.
-            void this.#deps.snapshots.remove(this.topic).catch(() => { });
+        const wasIncomplete = this.#restoreBacklog.length > 0;
+        this.#restoreBacklog = backlog;
+        if (pending.length > 0) {
+            this.#background.enqueue(pending);
+            this.#onStateChanged();
         }
+        if (backlog.length === 0) {
+            // The backlog just drained: re-arm the write it was suppressing, so the now-complete
+            // view reaches disk even if the retry admitted nothing new (a re-join that raced us).
+            if (wasIncomplete)
+                this.#scheduleSnapshotWrite();
+            return;
+        }
+        // Report the incompleteness once per restore (not once per retry): an operator needs to
+        // know this topic's tally is missing persisted votes, not a line every backoff window.
+        if (!wasIncomplete)
+            this.#emitError(new SnapshotError("restore-incomplete", this.topic));
+        this.#armRestoreRetry();
+    }
+    /**
+     * Arm the next backlog retry (exponential backoff, capped). Kept armed for as long as the
+     * backlog is non-empty and we stay joined: the alternative — giving up — means either
+     * discarding the votes or suppressing this topic's snapshot writes forever.
+     */
+    #armRestoreRetry() {
+        if (this.#restoreTimer !== undefined || !this.#joined)
+            return;
+        const delay = Math.min(RESTORE_RETRY_MS * 2 ** this.#restoreAttempts, RESTORE_RETRY_CAP_MS);
+        this.#restoreAttempts += 1;
+        const timer = setTimeout(() => {
+            this.#restoreTimer = undefined;
+            const backlog = this.#restoreBacklog;
+            if (backlog.length === 0 || !this.#joined)
+                return;
+            void this.#admitRestored(backlog).catch(() => {
+                // #admitRestored never throws; re-arm defensively so a backlog cannot strand.
+                this.#armRestoreRetry();
+            });
+        }, delay);
+        // Don't hold a Node process open; no-op in the browser.
+        timer.unref?.();
+        this.#restoreTimer = timer;
     }
     /**
      * The contest's current root record, encoded **on demand** and cached until the winner-set
@@ -1900,10 +2046,23 @@ class ContestView {
     async update() {
         if (this.#subscribed)
             return;
-        await this.#engine.join();
+        // Registered BEFORE the join, not after: the join restores this contest's persisted
+        // snapshot, and every way that can go wrong (a blob discarded as corrupt, a restore an
+        // RPC outage left incomplete — `SnapshotError`) is reported on the `error` event from
+        // inside `join()`. Attaching afterwards made exactly those reports unobservable.
         this.#engine.addUpdateListener(this.#onEngineUpdate);
         this.#engine.addErrorListener(this.#onEngineError);
         this.#subscribed = true;
+        try {
+            await this.#engine.join();
+        }
+        catch (error) {
+            // A failed join leaves no subscription behind (a retry must be able to re-arm).
+            this.#engine.removeUpdateListener(this.#onEngineUpdate);
+            this.#engine.removeErrorListener(this.#onEngineError);
+            this.#subscribed = false;
+            throw error;
+        }
         // Populate `tally` and fire an initial `update` for the current state.
         await this.#engine.refreshTallyNow();
     }

package/dist/errors.d.ts

@@ -146,3 +146,43 @@ export declare class VoteEvictedError extends Error {
     /** The failing verdict, with the same `reason` wording every verifier produces. */
     verdict: VerifyFail);
 }
+/**
+ * Emitted (never thrown) on a contest's `error` event when this node's OWN persisted checkpoint
+ * snapshot could not be kept ({@link SnapshotFailure} says which way): a blob discarded as
+ * unreadable, a restore left incomplete by a transient failure, or a write that kept failing.
+ *
+ * Persistence is best-effort by design — every one of these degrades to the pre-persistence
+ * behaviour (the cold-start pull), never to a broken join — but "best-effort" used to mean
+ * "silent", and silent state loss is exactly how a seeder served a divergent tally for 13 days
+ * without anyone noticing (issue #45). Operators get a fact and a topic instead of an unexplained
+ * gap; there is nothing for a client to do about it beyond logging or alerting.
+ */
+export declare class SnapshotError extends Error {
+    /** Which snapshot operation failed. */
+    readonly failure: SnapshotFailure;
+    /** The topic whose snapshot is affected. */
+    readonly topic: string;
+    /** The underlying throw, when there was one (a `restore-incomplete` may have none). */
+    readonly cause?: unknown | undefined;
+    constructor(
+    /** Which snapshot operation failed. */
+    failure: SnapshotFailure, 
+    /** The topic whose snapshot is affected. */
+    topic: string, 
+    /** The underlying throw, when there was one (a `restore-incomplete` may have none). */
+    cause?: unknown | undefined);
+}
+/**
+ * What went wrong with a persisted checkpoint snapshot:
+ *
+ * - `discarded` — the blob did not decode (corrupt, truncated, version-mismatched) and was
+ *   removed. The votes it held are gone from disk; the topic joins empty and re-converges from
+ *   peers.
+ * - `restore-incomplete` — the blob decoded, but a transient failure (an RPC outage during the
+ *   boot burst, a head that has not reached a bundle's sample bucket) left some of its bundles
+ *   un-admitted. The blob is KEPT and the restore retries; snapshot writes are suppressed for
+ *   this topic meanwhile, so a partial view can never overwrite the good blob.
+ * - `write-failed` — the store rejected the snapshot write repeatedly. The previous snapshot
+ *   stays in place, so a restart restores an older state rather than none.
+ */
+export type SnapshotFailure = "discarded" | "restore-incomplete" | "write-failed";

package/dist/errors.js

@@ -213,3 +213,32 @@ export class VoteEvictedError extends Error {
         this.name = "VoteEvictedError";
     }
 }
+/**
+ * Emitted (never thrown) on a contest's `error` event when this node's OWN persisted checkpoint
+ * snapshot could not be kept ({@link SnapshotFailure} says which way): a blob discarded as
+ * unreadable, a restore left incomplete by a transient failure, or a write that kept failing.
+ *
+ * Persistence is best-effort by design — every one of these degrades to the pre-persistence
+ * behaviour (the cold-start pull), never to a broken join — but "best-effort" used to mean
+ * "silent", and silent state loss is exactly how a seeder served a divergent tally for 13 days
+ * without anyone noticing (issue #45). Operators get a fact and a topic instead of an unexplained
+ * gap; there is nothing for a client to do about it beyond logging or alerting.
+ */
+export class SnapshotError extends Error {
+    failure;
+    topic;
+    cause;
+    constructor(
+    /** Which snapshot operation failed. */
+    failure, 
+    /** The topic whose snapshot is affected. */
+    topic, 
+    /** The underlying throw, when there was one (a `restore-incomplete` may have none). */
+    cause) {
+        super(`Checkpoint snapshot ${failure} for topic ${topic}${cause === undefined ? "" : `: ${String(cause)}`}`);
+        this.failure = failure;
+        this.topic = topic;
+        this.cause = cause;
+        this.name = "SnapshotError";
+    }
+}

package/dist/transport/chase.d.ts

@@ -77,8 +77,18 @@ export interface RootChaserDeps {
     cache: VerdictCache;
     /** The gate's freshness guard (see gossip-validator.ts); omitted ⇒ no check. */
     isEvaluableNow?: (bundle: VotesBundle) => Promise<boolean>;
-    /** Skip bundles we already hold (their CID is in the store) without re-verifying. */
-    hasBundle: (cid: CID) => Promise<boolean>;
+    /**
+     * Have we already ADMITTED this bundle (is it in the CRDT / winner-set)? Admitted bundles are
+     * skipped without re-verifying.
+     *
+     * Admission, never block presence: this was wired to the blockstore once, and the two disagree
+     * exactly when it matters (issue #44). A node whose persistent blockstore holds a bundle's
+     * block but whose admission state was lost — a restart that dropped the snapshot, an eviction,
+     * a prune — skipped that bundle on EVERY chase and could never converge again, silently, while
+     * every peer served it. Re-verifying a locally-held block costs no network (the bytes are the
+     * ones we just decoded), so the safe side of the disagreement is cheap.
+     */
+    isAdmitted: (cid: CID) => Promise<boolean>;
     /**
      * Store an offline-valid bundle's block bytes and admit its CID into the CRDT (idempotent).
      * `verified: true` means a cached terminal verdict already covers the FULL pipeline (the

package/dist/transport/chase.js

@@ -41,7 +41,7 @@ export function toChaseSession(session) {
     };
 }
 export function makeRootChaser(deps) {
-    const { getBlock, openSession, verifyOffline, cache, isEvaluableNow, hasBundle, admit, deferVerify, onMerged, onCheckpointContents, limit, timeoutMs } = deps;
+    const { getBlock, openSession, verifyOffline, cache, isEvaluableNow, isAdmitted, admit, deferVerify, onMerged, onCheckpointContents, limit, timeoutMs } = deps;
     const inFlight = new Map();
     function addProviders(flight, providers) {
         for (const peer of providers) {
@@ -121,8 +121,8 @@ export function makeRootChaser(deps) {
                 const bytes = encodeBundle(bundle);
                 const cid = await bundleCidForBytes(bytes);
                 contained.push(cid); // recorded BEFORE the skip below — see onCheckpointContents
-                if (await hasBundle(cid))
-                    continue; // already held — nothing to verify
+                if (await isAdmitted(cid))
+                    continue; // already in the winner-set — nothing to verify
                 const cached = cache.get(cid);
                 if (cached) {
                     if (!cached.valid)

package/dist/transport/integration/harness.js

@@ -129,9 +129,13 @@ export async function makeVoteNode(topic, options = {}) {
         // calls checkGates, so it admits rather than pretending to model a gate.
         checkGates: async () => ({ kind: "leaf", leaf: 0, satisfied: true, score: 1n, penalize: false })
     };
+    // Mirrors the voter's admission map (`#checks`): what the CRDT knows, NOT what the blockstore
+    // holds — the chase's skip predicate must be admission (voter.ts `isAdmitted`, issue #44).
+    const admitted = new Set();
     const admit = async ({ cid, bytes }) => {
         await blockstore.put(cid, bytes);
         await crdt.merge([cid]);
+        admitted.add(cid.toString());
     };
     const acceptedBundles = [];
     const heardRoots = [];
@@ -185,7 +189,7 @@ export async function makeVoteNode(topic, options = {}) {
         },
         verifyOffline: (bundle) => verifier.verifyOffline(bundle),
         cache,
-        hasBundle: (cid) => store.has(cid),
+        isAdmitted: async (cid) => admitted.has(cid.toString()),
         admit,
         // The harness runs the whole swapped pipeline in `verifyOffline` above, so nothing is
         // left deferred; the background verifier has its own unit tests.
@@ -275,6 +279,7 @@ export async function makeVoteNode(topic, options = {}) {
             const cid = await bundleCidForBytes(bytes);
             await blockstore.put(cid, bytes);
             await crdt.merge([cid]);
+            admitted.add(cid.toString());
         },
         stop: async () => {
             await transport.stop();

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@bitsocial/pubsub-voting",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Trustless pubsub voting over a shared libp2p/Helia node.",
   "type": "module",
   "license": "GPL-3.0-or-later",
+  "packageManager": "npm@11.13.0",
+  "engines": {
+    "npm": ">=11"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/bitsocialnet/pubsub-voting.git"