@bitsocial/pubsub-voting 0.0.8 → 0.0.10

package/README.md

@@ -38,7 +38,7 @@ The library never starts a node and never takes a host SDK (there is no `pkc` ar
 | `chains` | `ChainClientFactory` | yes | builds a viem `PublicClient` per chain; rules read through it for the gate and weight |
 | `signer` | `VoteSigner` | no | the voting wallet's address + EIP-712 ballot signing; omit for a read-only voter |
 | `nameResolvers` | `NameResolver[]` | no | community-name resolvers (same interface and instances as pkc-js's `nameResolvers`, e.g. `@bitsocial/bso-resolver` for `name.bso`); each vote's `community.name` claim is verified through them — inline at the forward-gate for live votes, in the background verifier for cold-join admits — and a bundle whose name resolves to a different `publicKey` than claimed is dropped/evicted |
-| `dataPath` | `string \| false` | no | directory for the voter's persistent caches (gate results + name resolutions), the pkc-js `dataPath` equivalent. Node default: `{cwd}/.bitsocial-pubsub-voting` (better-sqlite3 under `{dataPath}/lru-storage/`); in the browser the path is ignored and the caches live in IndexedDB. Pass `false` for in-memory-only (the pkc-js `noData` equivalent). A restart re-serves settled gate reads and fresh name resolutions from the store instead of the RPC |
+| `dataPath` | `string \| false` | no | directory for the voter's persistent state (gate-result + name-resolution caches, and each joined contest's **checkpoint snapshot** — its last fully-verified winner-set, reloaded at join so a restart with no other peer online keeps the tally), the pkc-js `dataPath` equivalent. Node default: `{cwd}/.bitsocial-pubsub-voting` (better-sqlite3 under `{dataPath}/lru-storage/` + `{dataPath}/checkpoints.db`); in the browser the path is ignored and everything lives in IndexedDB. Pass `false` for in-memory-only (the pkc-js `noData` equivalent). A restart re-serves settled gate reads and fresh name resolutions from the store instead of the RPC, and restores each contest's checkpoint before the cold-start pull. A seeder should always set a stable path |
 | `httpRouterUrls` | `string[]` | no | Delegated Routing V1 router base URLs to **announce provider records to** (one unsigned `PUT /routing/v1/providers` per router; `Keys` batches every joined contest's criteria CID + current checkpoint root + chunk CIDs — hourly, debounced on root changes, and on address changes). **Seeders only**: absent/empty means never announce (the default — plain clients are not dialable), and the browser build never announces regardless. The node must be publicly **reachable** (its listening port open/forwarded/published), but it does not need to know its own public IP: private, loopback, and link-local addrs are filtered client-side, and when nothing survives — the normal zero-config case behind NAT or a Docker bridge, and even on public-IP hosts, since libp2p withholds unconfirmed public addrs pending AutoNAT — the announcer sends the wildcard sentinels (`/ip4/0.0.0.0/...`, `/ip6/::/...`) that the router rewrites to the PUT's observed source IP, exactly as kubo announces work. Configured `addresses.announce` values (concrete public addrs, DNS/AutoTLS, or a kubo-style wildcard) are used as-is. Only a loopback-only node announces nothing. *Querying* needs no URLs here — cold-join discovery uses the injected node's `libp2p.contentRouting`, which the host wires its routers into |
 
 A contest is addressed by its **full criteria document**, passed to `createContest` / `createContestVote`. The document is strictly validated there (`CriteriaSchema` + the rule registry), and its canonical bytes derive the topic — so the exact document every participant shares is the only contest configuration that exists.
@@ -53,7 +53,7 @@ const voter = new PubsubVoter({
   chains: viemChainFactory(),   // ({ chain, config }) => viem PublicClient
   signer: mySigner,             // optional; omit → read-only voter
   nameResolvers: [bsoResolver], // optional; verifies community-name claims (e.g. @bitsocial/bso-resolver)
-  dataPath: "/path/to/data",    // optional; persistent-cache directory (default {cwd}/.bitsocial-pubsub-voting; false → in-memory)
+  dataPath: "/path/to/data",    // optional; persistent state: caches + checkpoint snapshots (default {cwd}/.bitsocial-pubsub-voting; false → in-memory)
   httpRouterUrls: [             // optional, SEEDERS ONLY (publicly reachable node): announce provider
     "https://routing.example"   // records (criteria CID + checkpoint root + chunks) so cold joiners
   ]                             // can discover this node via the routers; clients omit this

package/dist/checkpoint/codec.d.ts

@@ -38,6 +38,12 @@ export interface EncodedCheckpoint {
 }
 /** Default chunk ceiling (bytes of inlined bundles per chunk), just under a 1 MiB block. */
 export declare const DEFAULT_MAX_CHUNK_BYTES: number;
+/**
+ * The content address of one checkpoint block's bytes (dag-cbor + sha256). Exported for the
+ * snapshot restore path (see client/voter.ts): re-deriving each persisted block's CID is what
+ * lets the restore self-verify the blob against its root instead of trusting stored CIDs.
+ */
+export declare function blockForBytes(bytes: Uint8Array): Promise<CheckpointBlock>;
 /**
  * Encode a winner set into checkpoint blocks. `winners` should be the CRDT's current (non-expired)
  * LWW winners; order does not matter (they are sorted here). Returns the root CID and every block to

package/dist/checkpoint/codec.js

@@ -5,7 +5,12 @@ import { encodeCanonical, dagCborCode } from "../encoding/canonical.js";
 import { encodeBundle, toWireBundle, fromWireBundle } from "../crdt/codec.js";
 /** Default chunk ceiling (bytes of inlined bundles per chunk), just under a 1 MiB block. */
 export const DEFAULT_MAX_CHUNK_BYTES = 1 << 20;
-async function blockFor(bytes) {
+/**
+ * The content address of one checkpoint block's bytes (dag-cbor + sha256). Exported for the
+ * snapshot restore path (see client/voter.ts): re-deriving each persisted block's CID is what
+ * lets the restore self-verify the blob against its root instead of trusting stored CIDs.
+ */
+export async function blockForBytes(bytes) {
     const digest = await sha256.digest(bytes);
     return { cid: CID.createV1(dagCborCode, digest), bytes };
 }
@@ -17,7 +22,7 @@ async function blockFor(bytes) {
  */
 async function checkpointRootBlock(chunks) {
     const root = { chunks };
-    return blockFor(encodeCanonical(root));
+    return blockForBytes(encodeCanonical(root));
 }
 /**
  * Encode a winner set into checkpoint blocks. `winners` should be the CRDT's current (non-expired)
@@ -53,7 +58,7 @@ export async function encodeCheckpoint(winners, maxChunkBytes = DEFAULT_MAX_CHUN
     for (const chunk of chunks) {
         // Chunks inline the same binary wire objects the bundle block uses (see crdt/codec.ts),
         // so the binary-field byte saving multiplies across every inlined winner.
-        const block = await blockFor(encodeCanonical(chunk.map(toWireBundle)));
+        const block = await blockForBytes(encodeCanonical(chunk.map(toWireBundle)));
         blocks.push(block);
         chunkCids.push(block.cid);
     }

package/dist/checkpoint/snapshot.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Checkpoint-snapshot container — the blob a voter persists per topic so its own last
+ * fully-verified checkpoint survives a restart (see DESIGN.md "Persistent caches", checkpoint
+ * snapshots). It wraps the two existing codecs rather than defining new state: `record` is the
+ * fetch-protocol root record's exact wire bytes (`encodeRootRecord` — root CID, chunk index,
+ * counts), and `blocks` are the checkpoint blocks those CIDs address (chunks + root manifest,
+ * bytes only — CIDs are re-derived on load, so a corrupted block self-invalidates instead of
+ * being trusted).
+ *
+ * This is a LOCAL format, not wire: nothing remote ever sees a snapshot blob, so a version bump
+ * only invalidates on-disk snapshots (discarded gracefully at load) and needs no pinned vector.
+ * Pure and network-free, like the rest of `src/checkpoint/`.
+ */
+/** Bumped on any layout change; a mismatched blob is discarded at load, never migrated. */
+export declare const SNAPSHOT_VERSION = 1;
+/** The decoded container: root-record wire bytes plus the checkpoint block bytes it references. */
+export interface CheckpointSnapshot {
+    record: Uint8Array;
+    blocks: Uint8Array[];
+}
+/** Encode a snapshot blob (canonical dag-cbor, like every other byte layout in the library). */
+export declare function encodeSnapshot(snapshot: CheckpointSnapshot): Uint8Array;
+/** Decode and shape-check a snapshot blob; throws on garbage or a version mismatch. */
+export declare function decodeSnapshot(bytes: Uint8Array): CheckpointSnapshot;

package/dist/checkpoint/snapshot.js

@@ -0,0 +1,36 @@
+import * as dagCbor from "@ipld/dag-cbor";
+import { encodeCanonical } from "../encoding/canonical.js";
+/**
+ * Checkpoint-snapshot container — the blob a voter persists per topic so its own last
+ * fully-verified checkpoint survives a restart (see DESIGN.md "Persistent caches", checkpoint
+ * snapshots). It wraps the two existing codecs rather than defining new state: `record` is the
+ * fetch-protocol root record's exact wire bytes (`encodeRootRecord` — root CID, chunk index,
+ * counts), and `blocks` are the checkpoint blocks those CIDs address (chunks + root manifest,
+ * bytes only — CIDs are re-derived on load, so a corrupted block self-invalidates instead of
+ * being trusted).
+ *
+ * This is a LOCAL format, not wire: nothing remote ever sees a snapshot blob, so a version bump
+ * only invalidates on-disk snapshots (discarded gracefully at load) and needs no pinned vector.
+ * Pure and network-free, like the rest of `src/checkpoint/`.
+ */
+/** Bumped on any layout change; a mismatched blob is discarded at load, never migrated. */
+export const SNAPSHOT_VERSION = 1;
+/** Encode a snapshot blob (canonical dag-cbor, like every other byte layout in the library). */
+export function encodeSnapshot(snapshot) {
+    return encodeCanonical({ v: SNAPSHOT_VERSION, record: snapshot.record, blocks: snapshot.blocks });
+}
+/** Decode and shape-check a snapshot blob; throws on garbage or a version mismatch. */
+export function decodeSnapshot(bytes) {
+    const decoded = dagCbor.decode(bytes);
+    if (typeof decoded !== "object" || decoded === null)
+        throw new Error("snapshot is not a map");
+    const { v, record, blocks } = decoded;
+    if (v !== SNAPSHOT_VERSION)
+        throw new Error(`unsupported snapshot version ${String(v)}`);
+    if (!(record instanceof Uint8Array))
+        throw new Error("snapshot record is not bytes");
+    if (!Array.isArray(blocks) || blocks.some((block) => !(block instanceof Uint8Array))) {
+        throw new Error("snapshot blocks are not a bytes array");
+    }
+    return { record, blocks };
+}

package/dist/client/voter.d.ts

@@ -205,12 +205,16 @@ export interface PubsubVoterOptions {
      */
     httpRouterUrls?: string[];
     /**
-     * Directory for the voter's persistent caches (gate results, name resolutions), the
-     * pkc-js `dataPath` equivalent. On Node the caches are better-sqlite3 databases under
-     * `{dataPath}/lru-storage/`; in the browser the path is ignored and the caches live in
-     * IndexedDB (via localforage) either way. Defaults to `{cwd}/.bitsocial-pubsub-voting`
-     * on Node. Pass `false` for in-memory-only caches (no disk, no IndexedDB — the pkc-js
-     * `noData` equivalent): nothing survives the process, but nothing is written either.
+     * Directory for the voter's persistent state, the pkc-js `dataPath` equivalent: the
+     * gate-result and name-resolution caches, plus each joined contest's **checkpoint
+     * snapshot** — the node's own last fully-verified winner-set, written debounced on
+     * changes and reloaded at join, so a seeder restarting with no other peer online does
+     * not lose the tally. On Node this is better-sqlite3 databases under
+     * `{dataPath}/lru-storage/` plus `{dataPath}/checkpoints.db`; in the browser the path
+     * is ignored and everything lives in IndexedDB (via localforage) either way. Defaults
+     * to `{cwd}/.bitsocial-pubsub-voting` on Node. Pass `false` for in-memory-only (no
+     * disk, no IndexedDB — the pkc-js `noData` equivalent): nothing survives the process,
+     * but nothing is written either. A seeder should ALWAYS set a stable path.
      */
     dataPath?: string | false;
 }

package/dist/client/voter.js

@@ -24,7 +24,8 @@ import { encode as encodeDagCbor } from "@ipld/dag-cbor";
 import { sha256 } from "viem";
 import { makeBackgroundVerifier } from "../verify/background.js";
 import { makeAcceptedDedup } from "../transport/accepted-dedup.js";
-import { encodeCheckpoint } from "../checkpoint/codec.js";
+import { blockForBytes, decodeCheckpoint, encodeCheckpoint } from "../checkpoint/codec.js";
+import { decodeSnapshot, encodeSnapshot } from "../checkpoint/snapshot.js";
 import { CID } from "multiformats/cid";
 import { makeTally } from "../tally/tally.js";
 import { ballotTypedData } from "../signer/eip712.js";
@@ -120,6 +121,20 @@ const COLD_START_FETCH_BACKOFF_CAP_MS = 4_000;
  * others idle.
  */
 const COLD_START_PEER_FETCH_LIMIT = 24;
+/**
+ * How long after `join()` the cold-start pull stays armed on gossipsub's `subscription-change`
+ * (see `#armSubscriptionRepull`). One heartbeat interval: the window exists to close the
+ * join-races-subscription-gossip gap (issue #15), and past the first heartbeat the passive
+ * root-record heartbeat covers divergence detection anyway — an unbounded listener would
+ * instead pay one root fetch per churning subscriber for the node's whole lifetime.
+ */
+const COLD_START_REPULL_WINDOW_MS = HEARTBEAT_INTERVAL_MS;
+/**
+ * Debounce (ms) for persisting the checkpoint snapshot after a winner-set change, mirroring the
+ * announcer's cadence on the same transition: a gossip burst costs one write per window, and
+ * `leave()` flushes whatever is still pending so a clean shutdown never loses the tail.
+ */
+const SNAPSHOT_DEBOUNCE_MS = 10_000;
 /** 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. */
@@ -232,8 +247,10 @@ class ContestEngine {
      */
     #currentBucketCache = 0;
     /**
-     * The on-demand checkpoint cache: the last encoded root record and the bucket it was encoded
-     * at. Invalidated by {@link #markStateChanged} (any merge/publish/chase admit) and by a bucket
+     * The on-demand checkpoint cache: the last encoded root record, the bucket it was encoded
+     * at, and the encoded blocks themselves (also in the blockstore; kept here so the snapshot
+     * writer never has to read them back through a seam that can fall back to a network want).
+     * Invalidated by {@link #markStateChanged} (any merge/publish/chase admit) and by a bucket
      * advance (expiry changes the winner set without any message). See DESIGN.md "Checkpoints".
      */
     #rootRecordCache = undefined;
@@ -250,6 +267,13 @@ class ContestEngine {
     #peerRoots = new Map();
     /** The armed heartbeat timer (jittered; see {@link #armHeartbeat}), cleared by `leave()`. */
     #heartbeatTimer;
+    /** The armed (debounced) snapshot-write timer; flushed by `leave()`. See {@link #writeSnapshot}. */
+    #snapshotTimer;
+    /**
+     * Tears down the per-join `subscription-change` re-pull (listener + window timer); set by
+     * {@link #armSubscriptionRepull}, cleared by `leave()` or by the window expiring.
+     */
+    #subscriptionRepullDisarm;
     /** True when a heartbeat matching our own root was heard this interval (suppression). */
     #heardMatchingRoot = false;
     /** True once we published our record this interval (heartbeat OR divergence response). */
@@ -649,13 +673,21 @@ class ContestEngine {
         // heartbeat it broadcasts there.
         this.#deps.onTopicJoined();
         this.#armHeartbeat();
+        // Reload our own persisted checkpoint BEFORE any network activity, and awaited — so a
+        // seeder restarting with no other peer online serves its restored state immediately
+        // (the initial tally after `update()` already carries it), and the cold-start pull
+        // below compares peers' roots against the restored root instead of an empty one.
+        // No snapshot ⇒ no cost (one store miss); a non-empty one costs one head read (the
+        // bucket-admissibility check), consistent with the state-present rule below.
+        await this.#restoreSnapshot();
         // Cold-start / reconnect pull: ask connected topic peers for their root records and
         // chase any divergence. Fire-and-forget — joining must not block on slow peers, and
         // live gossip plus the heartbeat converge regardless; this only shortens the gap.
         void this.#coldStart().catch(() => { });
-        // If a re-join left state behind, refresh the bucket and prune the decayed nodes. Gated
-        // on non-empty state so an empty join stays network-free (no getBlockNumber read),
-        // preserving the "zero chain reads for a constant-weight tally" property.
+        // If a re-join left state behind (or the snapshot restore just reloaded some), refresh
+        // the bucket and prune the decayed nodes. Gated on non-empty state so an empty join
+        // stays network-free (no getBlockNumber read), preserving the "zero chain reads for a
+        // constant-weight tally" property.
         if (this.#crdt.nodeCount() > 0) {
             await this.#refreshBucket();
             await this.#crdt.prune(this.#currentBucketCache);
@@ -669,6 +701,14 @@ class ContestEngine {
      * the providers of the criteria CID from the host's HTTP content router. Roots are **unioned,
      * never quorum'd** — a record served by a single peer is still chased, so a colluding majority
      * cannot hide a vote.
+     *
+     * The `getSubscribers` source is an instantaneous snapshot, and a joiner that dials a seeder
+     * and joins immediately (the normal browser boot order) races subscription gossip: at the
+     * instant of `join()` it sees zero subscribers, pulls nothing, and would idle until the topic
+     * heartbeat (issue #15 — measured 90+ s vs ~4 s). So the pull closure (and its `seen` dedup)
+     * stays armed on gossipsub's `subscription-change` for {@link COLD_START_REPULL_WINDOW_MS}:
+     * each peer whose subscription to this topic becomes visible inside the window is asked once,
+     * closing the race for router-less clients too. See {@link #armSubscriptionRepull}.
      */
     async #coldStart() {
         const seen = new Set();
@@ -700,12 +740,45 @@ class ContestEngine {
                 // live gossip still converge.
             }
         };
+        // Arm the re-pull BEFORE the initial fan-out so no subscriber can land in the gap
+        // between the snapshot below and the listener; `seen` dedups any overlap.
+        this.#armSubscriptionRepull(pull);
         // Shuffle before slicing: a deterministic first-N pick would funnel a whole directory
         // join through the same peers' stream caps while other subscribers idle; a random N
         // spreads contests across the topic's serving peers (see COLD_START_PEER_FETCH_LIMIT).
         const fromSubscribers = shuffled(this.#deps.pubsub.getSubscribers(this.topic)).slice(0, COLD_START_PEERS).map(pull);
         await Promise.allSettled([...fromSubscribers, this.#discoverProviders(pull)]);
     }
+    /**
+     * Keep the cold-start pull live on gossipsub's `subscription-change` for one re-pull window:
+     * a peer whose subscription to this topic becomes visible after `join()`'s instantaneous
+     * `getSubscribers` snapshot is pulled the moment it appears (once — the shared `seen` set
+     * dedups), instead of waiting for the heartbeat. Bounded by {@link COLD_START_REPULL_WINDOW_MS}:
+     * past the first heartbeat interval the passive heartbeat already covers divergence detection,
+     * so a long-lived node does not pay one fetch per churning subscriber forever. Disarmed by
+     * `leave()`; a re-join arms a fresh window.
+     */
+    #armSubscriptionRepull(pull) {
+        this.#disarmSubscriptionRepull(); // a stale listener from a prior join must not leak
+        const pubsub = this.#deps.pubsub;
+        const listener = (evt) => {
+            if (!evt.detail.subscriptions.some((s) => s.topic === this.topic && s.subscribe))
+                return;
+            void pull(evt.detail.peerId).catch(() => { });
+        };
+        pubsub.addEventListener("subscription-change", listener);
+        const timer = setTimeout(() => this.#disarmSubscriptionRepull(), COLD_START_REPULL_WINDOW_MS);
+        // Don't hold a Node process open; no-op in the browser.
+        timer.unref?.();
+        this.#subscriptionRepullDisarm = () => {
+            clearTimeout(timer);
+            pubsub.removeEventListener("subscription-change", listener);
+        };
+    }
+    #disarmSubscriptionRepull() {
+        this.#subscriptionRepullDisarm?.();
+        this.#subscriptionRepullDisarm = undefined;
+    }
     /**
      * Pull one peer's root record over the fetch protocol, retrying a THROWN fetch with full-jittered
      * exponential backoff until {@link COLD_START_FETCH_DEADLINE_MS} (see the constant's note for the
@@ -793,8 +866,16 @@ class ContestEngine {
         if (this.#heartbeatTimer !== undefined)
             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).
+        if (this.#snapshotTimer !== undefined) {
+            clearTimeout(this.#snapshotTimer);
+            this.#snapshotTimer = undefined;
+            await this.#writeSnapshot();
+        }
         // Pause the background verifier's retry timer; pending state survives for a re-join.
         this.#background.stop();
+        this.#disarmSubscriptionRepull();
         this.#heardMatchingRoot = false;
         this.#publishedRootThisInterval = false;
         this.#chaser = undefined;
@@ -847,8 +928,126 @@ class ContestEngine {
     #markStateChanged() {
         this.#checkpointDirty = true;
         // The same transition the encode cache invalidates on is what makes router provider
-        // records stale, so the announcer's debounced re-announce rides it (see ResolvedDeps).
+        // records stale, so the announcer's debounced re-announce rides it (see ResolvedDeps),
+        // and what makes the persisted snapshot stale, so the debounced write rides it too.
         this.#deps.onCheckpointChanged();
+        this.#scheduleSnapshotWrite();
+    }
+    /**
+     * Arm the debounced snapshot write (announcer-style: the first change in a window arms the
+     * timer, the rest coalesce into it). Only while joined — a never-joined engine (a ballot
+     * created but never published) holds no view worth persisting, and `leave()` flushes the
+     * armed timer so nothing fires after teardown.
+     */
+    #scheduleSnapshotWrite() {
+        if (!this.#joined || this.#snapshotTimer !== undefined)
+            return;
+        const timer = setTimeout(() => {
+            this.#snapshotTimer = undefined;
+            void this.#writeSnapshot();
+        }, SNAPSHOT_DEBOUNCE_MS);
+        // Don't hold a Node process open; no-op in the browser.
+        timer.unref?.();
+        this.#snapshotTimer = timer;
+    }
+    /** Any admitted bundle with a deferred check still pending (same predicate as {@link #isPending}). */
+    #hasUnsettledChecks() {
+        for (const checks of this.#checks.values()) {
+            if (!checks.chainVerified || checks.nameResolved === false)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Persist this contest's current checkpoint under the voter's `dataPath`: the root record's
+     * 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.
+     *
+     * 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.
+     */
+    async #writeSnapshot() {
+        if (this.#hasUnsettledChecks())
+            return;
+        try {
+            await this.rootRecord(); // (re-)encode so the cache reflects the current winner-set
+            // Read record + blocks from the cache as one unit: a state change racing the encode
+            // above can only leave a NEWER consistent pair here, never a torn one.
+            const cached = this.#rootRecordCache;
+            if (cached === undefined)
+                return;
+            await this.#deps.snapshots.set(this.topic, encodeSnapshot({ record: encodeRootRecord(cached.record), blocks: cached.blocks.map((block) => block.bytes) }));
+        }
+        catch {
+            // Best-effort: a failed write leaves the previous snapshot in place; the next
+            // state change re-arms the debounce and retries.
+        }
+    }
+    /**
+     * Reload this node's own persisted checkpoint at `join()`, before any network activity: the
+     * fix for the seeder-restart vote loss (issue #14). The blob is decoded through the SAME
+     * pipeline as a chased remote checkpoint — block CIDs re-derived (a corrupted block
+     * self-invalidates), `decodeCheckpoint` re-derives the chunk index against the root, each
+     * 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.
+     */
+    async #restoreSnapshot() {
+        let blob;
+        try {
+            blob = await this.#deps.snapshots.get(this.topic);
+        }
+        catch {
+            return; // unreadable store — degrade to a plain cold join
+        }
+        if (blob === undefined)
+            return;
+        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.
+                const cid = await bundleCidForBytes(encodeBundle(bundle));
+                if (this.#checks.has(cid.toString()))
+                    continue; // already admitted (a re-join)
+                if (!(await this.#isEvaluableNow(bundle)))
+                    continue;
+                const offline = await this.#verifier.verifyOffline(bundle);
+                if (!offline.valid)
+                    continue;
+                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 {
+            // 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(() => { });
+        }
     }
     /**
      * The contest's current root record, encoded **on demand** and cached until the winner-set
@@ -886,7 +1085,7 @@ class ContestEngine {
             count: winners.length,
             sizeBytes: blocks.reduce((total, block) => total + block.bytes.length, 0)
         };
-        this.#rootRecordCache = { record, bucket };
+        this.#rootRecordCache = { record, bucket, blocks };
         return record;
     }
     /**
@@ -1176,7 +1375,8 @@ export class PubsubVoter {
             onCheckpointChanged: () => this.#announcer?.notifyChange(),
             fetchBudget: makePerPeerBudget(COLD_START_PEER_FETCH_LIMIT),
             gateStore: this.#storage.openLru({ cacheName: "gate-results", maxItems: GATE_RESULTS_MAX_ITEMS }),
-            nameResolutionCache: makeNameResolutionCache(this.#storage.openLru({ cacheName: "name-resolutions", maxItems: NAME_RESOLUTIONS_MAX_ITEMS }))
+            nameResolutionCache: makeNameResolutionCache(this.#storage.openLru({ cacheName: "name-resolutions", maxItems: NAME_RESOLUTIONS_MAX_ITEMS })),
+            snapshots: this.#storage.openSnapshots()
         };
         // The announcer touches libp2p (peer id, addresses, address events) only when routers are
         // configured, so a host that never announces pays nothing and injects nothing extra.

package/dist/storage/browser.js

@@ -88,11 +88,38 @@ class LocalForageLruStorage {
         await Promise.all([db.active().clear(), db.inactive().clear()]);
     }
 }
+/**
+ * The browser checkpoint-snapshot store: a single localforage (IndexedDB) database, no
+ * dual-instance eviction — a snapshot must never be evicted (see types.ts). localforage
+ * round-trips typed arrays natively under its IndexedDB driver; an `ArrayBuffer` coming
+ * back from an older driver is re-wrapped.
+ */
+class LocalForageSnapshotStorage {
+    #db;
+    #init() {
+        return (this.#db ??= localForage.createInstance({ name: "pubsub-voting-checkpoints" }));
+    }
+    async get(key) {
+        const value = await this.#init().getItem(key);
+        if (value instanceof Uint8Array)
+            return value;
+        if (value instanceof ArrayBuffer)
+            return new Uint8Array(value);
+        return undefined;
+    }
+    async set(key, bytes) {
+        await this.#init().setItem(key, bytes);
+    }
+    async remove(key) {
+        await this.#init().removeItem(key);
+    }
+}
 /** Build the browser {@link VoteStorage}: IndexedDB via localforage, or in-memory for `false`. */
 export function makeStorage(options) {
     if (options.dataPath === false)
         return makeMemoryStorage();
     const stores = new Map();
+    let snapshots;
     return {
         openLru({ cacheName, maxItems }) {
             let store = stores.get(cacheName);
@@ -102,9 +129,13 @@ export function makeStorage(options) {
             }
             return store;
         },
+        openSnapshots() {
+            return (snapshots ??= new LocalForageSnapshotStorage());
+        },
         // localforage holds no closeable handles; dropping the references is the whole teardown.
         async destroy() {
             stores.clear();
+            snapshots = undefined;
         }
     };
 }

package/dist/storage/memory.d.ts

@@ -1,4 +1,4 @@
-import type { LruStorage, VoteStorage } from "./types.js";
+import type { LruStorage, SnapshotStorage, VoteStorage } from "./types.js";
 /**
  * The `dataPath: false` backend on both platforms (pkc-js's `noData` equivalent): a true-LRU
  * `Map` — a `get` hit re-inserts the key so insertion order IS recency order, and eviction
@@ -6,5 +6,7 @@ import type { LruStorage, VoteStorage } from "./types.js";
  * match the persistent backends so tests and no-disk hosts exercise the same code paths.
  */
 export declare function makeMemoryLruStorage(maxItems: number): LruStorage;
+/** The `dataPath: false` snapshot store: a plain `Map`, no eviction (see types.ts). */
+export declare function makeMemorySnapshotStorage(): SnapshotStorage;
 /** An all-in-memory {@link VoteStorage}; `destroy()` only drops the references. */
 export declare function makeMemoryStorage(): VoteStorage;

package/dist/storage/memory.js

@@ -37,9 +37,25 @@ export function makeMemoryLruStorage(maxItems) {
         }
     };
 }
+/** The `dataPath: false` snapshot store: a plain `Map`, no eviction (see types.ts). */
+export function makeMemorySnapshotStorage() {
+    const blobs = new Map();
+    return {
+        async get(key) {
+            return blobs.get(key);
+        },
+        async set(key, bytes) {
+            blobs.set(key, bytes);
+        },
+        async remove(key) {
+            blobs.delete(key);
+        }
+    };
+}
 /** An all-in-memory {@link VoteStorage}; `destroy()` only drops the references. */
 export function makeMemoryStorage() {
     const stores = new Map();
+    let snapshots;
     return {
         openLru({ cacheName, maxItems }) {
             let store = stores.get(cacheName);
@@ -49,8 +65,12 @@ export function makeMemoryStorage() {
             }
             return store;
         },
+        openSnapshots() {
+            return (snapshots ??= makeMemorySnapshotStorage());
+        },
         async destroy() {
             stores.clear();
+            snapshots = undefined;
         }
     };
 }

package/dist/storage/node.js

@@ -37,21 +37,31 @@ class SqliteLruStorage {
         if (this.#closed)
             throw new Error("storage is closed");
         mkdirSync(this.#dir, { recursive: true });
+        // A corrupt file fails on the first statement, not the constructor (SQLite reads the
+        // header lazily), so close the never-assigned handle or every caller retry leaks an fd.
         const db = new Database(this.#file);
-        db.pragma("journal_mode = WAL");
-        db.prepare(`CREATE TABLE IF NOT EXISTS cache (key TEXT PRIMARY KEY, value TEXT, lastAccess INT)`).run();
-        db.prepare(`CREATE INDEX IF NOT EXISTS lastAccess ON cache (lastAccess)`).run();
-        this.#db = db;
-        this.#statements = {
-            get: db.prepare(`UPDATE OR IGNORE cache SET lastAccess = @now WHERE key = @key RETURNING value`),
-            set: db.prepare(`INSERT OR REPLACE INTO cache (key, value, lastAccess) VALUES (@key, @value, @now)`),
-            remove: db.prepare(`DELETE FROM cache WHERE key = @key`),
-            keys: db.prepare(`SELECT key FROM cache`),
-            clear: db.prepare(`DELETE FROM cache`),
-            evict: db.prepare(`WITH lru AS (SELECT key FROM cache ORDER BY lastAccess DESC LIMIT -1 OFFSET @maxItems)
-                 DELETE FROM cache WHERE key IN lru`)
-        };
-        return this.#statements;
+        try {
+            db.pragma("journal_mode = WAL");
+            db.prepare(`CREATE TABLE IF NOT EXISTS cache (key TEXT PRIMARY KEY, value TEXT, lastAccess INT)`).run();
+            db.prepare(`CREATE INDEX IF NOT EXISTS lastAccess ON cache (lastAccess)`).run();
+            this.#db = db;
+            this.#statements = {
+                get: db.prepare(`UPDATE OR IGNORE cache SET lastAccess = @now WHERE key = @key RETURNING value`),
+                set: db.prepare(`INSERT OR REPLACE INTO cache (key, value, lastAccess) VALUES (@key, @value, @now)`),
+                remove: db.prepare(`DELETE FROM cache WHERE key = @key`),
+                keys: db.prepare(`SELECT key FROM cache`),
+                clear: db.prepare(`DELETE FROM cache`),
+                evict: db.prepare(`WITH lru AS (SELECT key FROM cache ORDER BY lastAccess DESC LIMIT -1 OFFSET @maxItems)
+                     DELETE FROM cache WHERE key IN lru`)
+            };
+            return this.#statements;
+        }
+        catch (error) {
+            this.#db = undefined;
+            this.#statements = undefined;
+            db.close();
+            throw error;
+        }
     }
     async getItem(key) {
         const row = this.#open().get.get({ key, now: Date.now() });
@@ -78,6 +88,67 @@ class SqliteLruStorage {
         this.#statements = undefined;
     }
 }
+/**
+ * The Node checkpoint-snapshot store: one better-sqlite3 database at
+ * `{dataPath}/checkpoints.db`, one BLOB row per topic. Same lazy open / WAL / closed-flag
+ * discipline as {@link SqliteLruStorage}, but no LRU machinery: a snapshot must never be
+ * evicted (see types.ts). A single `INSERT OR REPLACE` per `set` makes each write atomic —
+ * a crash mid-write leaves the previous blob, never a torn one.
+ */
+class SqliteSnapshotStorage {
+    #db;
+    #file;
+    #dir;
+    #closed = false;
+    #statements;
+    constructor(opts) {
+        this.#dir = opts.dir;
+        this.#file = join(opts.dir, "checkpoints.db");
+    }
+    #open() {
+        if (this.#statements)
+            return this.#statements;
+        if (this.#closed)
+            throw new Error("storage is closed");
+        mkdirSync(this.#dir, { recursive: true });
+        // Same handle-leak guard as SqliteLruStorage.#open: the debounced snapshot write
+        // retries on every state change, so an unclosed handle per attempt is an EMFILE.
+        const db = new Database(this.#file);
+        try {
+            db.pragma("journal_mode = WAL");
+            db.prepare(`CREATE TABLE IF NOT EXISTS snapshot (key TEXT PRIMARY KEY, value BLOB)`).run();
+            this.#db = db;
+            this.#statements = {
+                get: db.prepare(`SELECT value FROM snapshot WHERE key = @key`),
+                set: db.prepare(`INSERT OR REPLACE INTO snapshot (key, value) VALUES (@key, @value)`),
+                remove: db.prepare(`DELETE FROM snapshot WHERE key = @key`)
+            };
+            return this.#statements;
+        }
+        catch (error) {
+            this.#db = undefined;
+            this.#statements = undefined;
+            db.close();
+            throw error;
+        }
+    }
+    async get(key) {
+        const row = this.#open().get.get({ key });
+        return row === undefined ? undefined : new Uint8Array(row.value);
+    }
+    async set(key, bytes) {
+        this.#open().set.run({ key, value: Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength) });
+    }
+    async remove(key) {
+        this.#open().remove.run({ key });
+    }
+    close() {
+        this.#closed = true;
+        this.#db?.close();
+        this.#db = undefined;
+        this.#statements = undefined;
+    }
+}
 /** Node's default data path when the host passes none (see {@link StorageOptions.dataPath}). */
 export function defaultDataPath() {
     return join(process.cwd(), ".bitsocial-pubsub-voting");
@@ -86,8 +157,10 @@ export function defaultDataPath() {
 export function makeStorage(options) {
     if (options.dataPath === false)
         return makeMemoryStorage();
-    const dir = join(options.dataPath ?? defaultDataPath(), "lru-storage");
+    const dataPath = options.dataPath ?? defaultDataPath();
+    const dir = join(dataPath, "lru-storage");
     const stores = new Map();
+    let snapshots;
     return {
         openLru({ cacheName, maxItems }) {
             let store = stores.get(cacheName);
@@ -97,10 +170,15 @@ export function makeStorage(options) {
             }
             return store;
         },
+        openSnapshots() {
+            return (snapshots ??= new SqliteSnapshotStorage({ dir: dataPath }));
+        },
         async destroy() {
             for (const store of stores.values())
                 store.close();
             stores.clear();
+            snapshots?.close();
+            snapshots = undefined;
         }
     };
 }

package/dist/storage/types.d.ts

@@ -22,6 +22,21 @@ export interface LruStorage {
     keys(): Promise<string[]>;
     clear(): Promise<void>;
 }
+/**
+ * The checkpoint-snapshot store: one binary blob per topic, holding the node's own last
+ * fully-verified checkpoint so a restart with no other peer online does not lose the tally
+ * (see DESIGN.md "Persistent caches", checkpoint snapshots). Deliberately NOT an
+ * {@link LruStorage}: values are binary (no JSON round-trip for ~half-MB block sets) and
+ * eviction would silently corrupt a snapshot — a topic's blob lives until overwritten or
+ * removed. Each `set` replaces the whole blob in one write, so a snapshot is never torn.
+ */
+export interface SnapshotStorage {
+    /** The stored blob, or `undefined` on a miss. */
+    get(key: string): Promise<Uint8Array | undefined>;
+    /** Insert or replace the blob atomically. */
+    set(key: string, bytes: Uint8Array): Promise<void>;
+    remove(key: string): Promise<void>;
+}
 /** One voter's persistent-cache root: opens named LRU stores, closed as a unit on `destroy()`. */
 export interface VoteStorage {
     /**
@@ -32,6 +47,8 @@ export interface VoteStorage {
         cacheName: string;
         maxItems: number;
     }): LruStorage;
+    /** Open (or return the already-open) checkpoint-snapshot store (one per voter). */
+    openSnapshots(): SnapshotStorage;
     /** Close every open store (Node: close the sqlite handles). Terminal, like `PubsubVoter.destroy`. */
     destroy(): Promise<void>;
 }

package/dist/transport/types.d.ts

@@ -75,6 +75,15 @@ export interface PubsubService {
             from?: PeerId;
         };
     }) => void): void;
+    /**
+     * gossipsub's "a peer's subscription set changed" notification. The cold-start pull
+     * re-runs off it (see client/voter.ts `#armSubscriptionRepull`): a joiner that dials a
+     * seeder and joins immediately sees zero subscribers at the instant of `join()` — the
+     * seeder only appears here once subscription gossip lands — so without this trigger it
+     * would idle until the topic heartbeat.
+     */
+    addEventListener(type: "subscription-change", listener: SubscriptionChangeListener): void;
+    removeEventListener(type: "subscription-change", listener: SubscriptionChangeListener): void;
     /**
      * gossipsub's per-topic validator map. The transport installs the async forward-gate
      * here (`topicValidators.set(topic, gate)`); gossipsub awaits the returned promise
@@ -85,6 +94,16 @@ export interface PubsubService {
      */
     topicValidators?: Map<string, GossipTopicValidator>;
 }
+/** Listener for gossipsub's `subscription-change` (the libp2p `SubscriptionChangeData` shape). */
+export type SubscriptionChangeListener = (evt: {
+    detail: {
+        peerId: PeerId;
+        subscriptions: Array<{
+            topic: string;
+            subscribe: boolean;
+        }>;
+    };
+}) => void;
 /** A received pubsub message, as passed to a gossipsub topic validator. */
 export interface GossipMessage {
     topic: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitsocial/pubsub-voting",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "Trustless pubsub voting over a shared libp2p/Helia node.",
   "type": "module",
   "license": "GPL-3.0-or-later",
@@ -31,6 +31,7 @@
     "build:bench": "tsc -p benchmark/tsconfig.json",
     "bench:cold-join": "node benchmark/run.mjs",
     "bench:directory-load": "node benchmark/run-directory.mjs",
+    "bench:warm-restart": "npm run build && npm run build:bench && node benchmark/warm-restart.js",
     "release": "HUSKY=0 release-it --config config/.release-it.json",
     "prepare": "husky",
     "prepublishOnly": "npm run build",