@bitsocial/pubsub-voting 0.0.6 → 0.0.7

package/README.md

@@ -39,7 +39,7 @@ The library never starts a node and never takes a host SDK (there is no `pkc` ar
 | `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 |
-| `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 dialable, with its dialable addresses in `libp2p` (listen/announce/AutoTLS): private, loopback, and link-local addrs are filtered client-side, and an announce with no surviving address is skipped. *Querying* needs no URLs here — cold-join discovery uses the injected node's `libp2p.contentRouting`, which the host wires its routers into |
+| `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.
 
@@ -54,7 +54,7 @@ const voter = new PubsubVoter({
   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)
-  httpRouterUrls: [             // optional, SEEDERS ONLY (publicly dialable node): announce provider
+  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/client/voter.js

@@ -392,6 +392,10 @@ class ContestEngine {
         for (const cb of [...this.#errorListeners])
             cb(error);
     }
+    /** Surface a voter-level failure (e.g. a provider announce) through this contest's error event. */
+    emitError(error) {
+        this.#emitError(error);
+    }
     #chainFor(ticker) {
         const client = this.#chainClients[ticker];
         if (!client)
@@ -1180,7 +1184,18 @@ export class PubsubVoter {
             this.#announcer = makeAnnouncer({
                 routerUrls: [...options.httpRouterUrls],
                 libp2p: options.helia.libp2p,
-                keys: this.#announceKeys
+                keys: this.#announceKeys,
+                // An announce failure is a discoverability degradation for every joined contest,
+                // so it surfaces through each one's error event (observational, like the announce
+                // itself: never retried, never thrown) — a silent announce failure otherwise looks
+                // exactly like a healthy seeder that nobody can find.
+                onError: (url, error) => {
+                    const announceError = new Error(`provider announce to router ${url} failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+                    for (const engine of this.#engines.values()) {
+                        if (engine.joined)
+                            engine.emitError(announceError);
+                    }
+                }
             });
         }
     }

package/dist/transport/announce/node.d.ts

@@ -9,6 +9,17 @@ import type { Announcer, AnnouncerOptions } from "./types.js";
  * exists), and its anti-spoofing keeps `/ip4`/`/ip6` addrs only when the IP matches the PUT's
  * source IP — which a seeder announcing its own addresses passes naturally.
  *
+ * Addresses: the announceable set is `getMultiaddrs()` filtered to public/DNS addrs plus
+ * exactly-unspecified addrs (`0.0.0.0`/`::`), which the production router rewrites to the PUT's
+ * observed source IP (`cleanAddrs` — how kubo's announces work). When the filter comes up EMPTY,
+ * the announcer synthesizes those wildcard sentinels itself from the node's listen ports
+ * ({@link sentinelAddrs}), because libp2p never reports one: a wildcard listen is expanded to
+ * concrete interface addrs, and a PUBLIC interface addr is withheld from `getMultiaddrs()` until
+ * AutoNAT confirms it — which a seeder with no inbound peers yet can never pass (the announce is
+ * what brings the first peer). So the zero-config seeder — NAT'd, Docker-bridged, or a bare
+ * public-IP host without AutoNAT — announces the sentinel and the router fills in the IP it can
+ * actually see.
+ *
  * Ticks: the debounced change trigger ({@link Announcer.notifyChange} — contest joins, checkpoint
  * root changes, `self:peer:update` address changes) plus an hourly re-announce (pkc-js's
  * `providePubsubTopicRoutingCidsIfNeeded` cadence; the production router's record TTL is 24h, so
@@ -27,12 +38,28 @@ export declare const ANNOUNCE_DEBOUNCE_MS = 10000;
 export declare const ANNOUNCE_ROUTER_TIMEOUT_MS = 10000;
 /**
  * Filter a node's multiaddrs down to what belongs in a public provider record: public `/ip4` /
- * `/ip6` addrs and DNS addrs (`/dns4`/`/dns6`/`/dnsaddr` — the AutoTLS `<peerId>.libp2p.direct`
- * WSS addrs travel this way, and the production router passes DNS through unvalidated). Private,
- * loopback, link-local, CGNAT, and unspecified IPs are dropped CLIENT-side rather than trusting
- * the router to drop them; a `p2p-circuit` addr is judged by its relay's leading component like
- * any other. Exported for the announcer's unit tests.
+ * `/ip6` addrs, DNS addrs (`/dns4`/`/dns6`/`/dnsaddr` — the AutoTLS `<peerId>.libp2p.direct`
+ * WSS addrs travel this way, and the production router passes DNS through unvalidated), and
+ * EXACTLY-unspecified addrs (`/ip4/0.0.0.0/...`, `/ip6/::/...`) — the router rewrites those to
+ * the PUT's observed source IP (`cleanAddrs`, the same mechanism kubo's announces rely on), so
+ * they are how a node that cannot see its own public IP still announces a dialable record.
+ * Private, loopback, link-local, and CGNAT IPs are dropped CLIENT-side rather than trusting the
+ * router to drop them; a `p2p-circuit` addr is judged by its relay's leading component like any
+ * other. Exported for the announcer's unit tests.
  */
 export declare function announceableAddrs(addrs: readonly string[]): string[];
+/**
+ * Synthesize the router's "rewrite me" wildcard sentinels for a node with NO announceable addr:
+ * every non-loopback `/ip4`/`/ip6` interface addr, with its IP swapped for the unspecified addr
+ * of its family and the rest of the multiaddr (port, transport, `/p2p/` suffix) kept, deduped.
+ * libp2p never reports a wildcard itself — a `0.0.0.0` listen is expanded to concrete interface
+ * addrs, and a public interface addr is withheld until AutoNAT confirms it — so behind NAT, on a
+ * Docker bridge, or on a public-IP host without AutoNAT the whole set filters away and the listen
+ * ports here are the only truthful thing left to announce; the router substitutes the source IP
+ * it observed (dropping the family it did not see the PUT from). Loopback addrs are excluded as
+ * synthesis sources: a loopback-only node deliberately isn't listening on any interface a rewrite
+ * could make dialable, and it must keep announcing nothing. Exported for the announcer's tests.
+ */
+export declare function sentinelAddrs(addrs: readonly string[]): string[];
 /** Build the Node announcer. The browser build never sees this file (package.json `browser` remap). */
 export declare function makeAnnouncer(options: AnnouncerOptions): Announcer;

package/dist/transport/announce/node.js

@@ -8,6 +8,17 @@
  * exists), and its anti-spoofing keeps `/ip4`/`/ip6` addrs only when the IP matches the PUT's
  * source IP — which a seeder announcing its own addresses passes naturally.
  *
+ * Addresses: the announceable set is `getMultiaddrs()` filtered to public/DNS addrs plus
+ * exactly-unspecified addrs (`0.0.0.0`/`::`), which the production router rewrites to the PUT's
+ * observed source IP (`cleanAddrs` — how kubo's announces work). When the filter comes up EMPTY,
+ * the announcer synthesizes those wildcard sentinels itself from the node's listen ports
+ * ({@link sentinelAddrs}), because libp2p never reports one: a wildcard listen is expanded to
+ * concrete interface addrs, and a PUBLIC interface addr is withheld from `getMultiaddrs()` until
+ * AutoNAT confirms it — which a seeder with no inbound peers yet can never pass (the announce is
+ * what brings the first peer). So the zero-config seeder — NAT'd, Docker-bridged, or a bare
+ * public-IP host without AutoNAT — announces the sentinel and the router fills in the IP it can
+ * actually see.
+ *
  * Ticks: the debounced change trigger ({@link Announcer.notifyChange} — contest joins, checkpoint
  * root changes, `self:peer:update` address changes) plus an hourly re-announce (pkc-js's
  * `providePubsubTopicRoutingCidsIfNeeded` cadence; the production router's record TTL is 24h, so
@@ -24,13 +35,16 @@ export const ANNOUNCE_INTERVAL_MS = 3_600_000;
 export const ANNOUNCE_DEBOUNCE_MS = 10_000;
 /** Per-router PUT deadline — same order as the cold-join router lookup deadline. */
 export const ANNOUNCE_ROUTER_TIMEOUT_MS = 10_000;
-/** RFC1918/loopback/link-local/CGNAT/unspecified IPv4 — never announceable. */
+/** The exactly-unspecified IPs — the production router's "rewrite me to the PUT's source IP" sentinels. */
+const UNSPECIFIED_IP4 = "0.0.0.0";
+const UNSPECIFIED_IP6 = "::";
+/** RFC1918/loopback/link-local/CGNAT/"this network" IPv4 — never dialable as announced. */
 function isPrivateIp4(ip) {
     const parts = ip.split(".").map(Number);
     if (parts.length !== 4 || parts.some((p) => !Number.isInteger(p) || p < 0 || p > 255))
         return true;
     const [a, b] = parts;
-    return (a === 0 || // unspecified / "this network"
+    return (a === 0 || // "this network" 0.0.0.0/8 (the exact unspecified addr is special-cased by callers)
         a === 10 ||
         a === 127 || // loopback
         (a === 100 && b >= 64 && b < 128) || // CGNAT 100.64/10
@@ -38,21 +52,24 @@ function isPrivateIp4(ip) {
         (a === 172 && b >= 16 && b < 32) ||
         (a === 192 && b === 168));
 }
-/** Loopback/link-local/ULA/unspecified IPv6 — never announceable. */
+/** Loopback/link-local/ULA IPv6 — never dialable as announced. */
 function isPrivateIp6(ip) {
     const lower = ip.toLowerCase();
-    if (lower === "::" || lower === "::1")
+    if (lower === UNSPECIFIED_IP6 || lower === "::1")
         return true;
     // fe80::/10 link-local (fe8x..febx), fc00::/7 unique-local (fcxx/fdxx).
     return /^fe[89ab]/.test(lower) || /^f[cd]/.test(lower);
 }
 /**
  * Filter a node's multiaddrs down to what belongs in a public provider record: public `/ip4` /
- * `/ip6` addrs and DNS addrs (`/dns4`/`/dns6`/`/dnsaddr` — the AutoTLS `<peerId>.libp2p.direct`
- * WSS addrs travel this way, and the production router passes DNS through unvalidated). Private,
- * loopback, link-local, CGNAT, and unspecified IPs are dropped CLIENT-side rather than trusting
- * the router to drop them; a `p2p-circuit` addr is judged by its relay's leading component like
- * any other. Exported for the announcer's unit tests.
+ * `/ip6` addrs, DNS addrs (`/dns4`/`/dns6`/`/dnsaddr` — the AutoTLS `<peerId>.libp2p.direct`
+ * WSS addrs travel this way, and the production router passes DNS through unvalidated), and
+ * EXACTLY-unspecified addrs (`/ip4/0.0.0.0/...`, `/ip6/::/...`) — the router rewrites those to
+ * the PUT's observed source IP (`cleanAddrs`, the same mechanism kubo's announces rely on), so
+ * they are how a node that cannot see its own public IP still announces a dialable record.
+ * Private, loopback, link-local, and CGNAT IPs are dropped CLIENT-side rather than trusting the
+ * router to drop them; a `p2p-circuit` addr is judged by its relay's leading component like any
+ * other. Exported for the announcer's unit tests.
  */
 export function announceableAddrs(addrs) {
     return addrs.filter((addr) => {
@@ -62,12 +79,40 @@ export function announceableAddrs(addrs) {
         if (proto === "dns4" || proto === "dns6" || proto === "dnsaddr" || proto === "dns")
             return true;
         if (proto === "ip4")
-            return !isPrivateIp4(value);
+            return value === UNSPECIFIED_IP4 || !isPrivateIp4(value);
         if (proto === "ip6")
-            return !isPrivateIp6(value);
+            return value.toLowerCase() === UNSPECIFIED_IP6 || !isPrivateIp6(value);
         return false;
     });
 }
+/**
+ * Synthesize the router's "rewrite me" wildcard sentinels for a node with NO announceable addr:
+ * every non-loopback `/ip4`/`/ip6` interface addr, with its IP swapped for the unspecified addr
+ * of its family and the rest of the multiaddr (port, transport, `/p2p/` suffix) kept, deduped.
+ * libp2p never reports a wildcard itself — a `0.0.0.0` listen is expanded to concrete interface
+ * addrs, and a public interface addr is withheld until AutoNAT confirms it — so behind NAT, on a
+ * Docker bridge, or on a public-IP host without AutoNAT the whole set filters away and the listen
+ * ports here are the only truthful thing left to announce; the router substitutes the source IP
+ * it observed (dropping the family it did not see the PUT from). Loopback addrs are excluded as
+ * synthesis sources: a loopback-only node deliberately isn't listening on any interface a rewrite
+ * could make dialable, and it must keep announcing nothing. Exported for the announcer's tests.
+ */
+export function sentinelAddrs(addrs) {
+    const sentinels = new Set();
+    for (const addr of addrs) {
+        const parts = addr.split("/");
+        const [, proto, value] = parts;
+        if (proto === undefined || value === undefined)
+            continue;
+        if (proto === "ip4" && value !== UNSPECIFIED_IP4 && value.split(".")[0] !== "127") {
+            sentinels.add(["", proto, UNSPECIFIED_IP4, ...parts.slice(3)].join("/"));
+        }
+        else if (proto === "ip6" && !["::", "::1"].includes(value.toLowerCase())) {
+            sentinels.add(["", proto, UNSPECIFIED_IP6, ...parts.slice(3)].join("/"));
+        }
+    }
+    return [...sentinels];
+}
 /** One unsigned kubo-shape provider PUT; throws on timeout or a non-2xx answer. */
 async function putProviders(baseUrl, body, timeoutMs) {
     const endpoint = `${baseUrl.replace(/\/+$/, "")}/routing/v1/providers`;
@@ -103,10 +148,15 @@ export function makeAnnouncer(options) {
             do {
                 rerun = false;
                 const keys = await options.keys();
-                const addrs = announceableAddrs(options.libp2p.getMultiaddrs().map((a) => a.toString()));
-                // Nothing joined, or no publicly dialable address: announce nothing. The production
-                // router drops a provider whose addrs come up empty anyway — an undialable node
-                // (plain client, NATed box with no configured announce addrs) must not announce.
+                const all = options.libp2p.getMultiaddrs().map((a) => a.toString());
+                let addrs = announceableAddrs(all);
+                // No announceable addr — behind NAT/Docker-bridge, or a public interface addr
+                // libp2p is still withholding pending AutoNAT — announce the wildcard sentinels
+                // and let the router substitute the source IP it observes (see sentinelAddrs).
+                if (addrs.length === 0)
+                    addrs = sentinelAddrs(all);
+                // Nothing joined, or loopback-only (not listening on any rewritable interface):
+                // announce nothing — the production router drops addr-less providers anyway.
                 if (keys.length === 0 || addrs.length === 0)
                     continue;
                 const body = JSON.stringify({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitsocial/pubsub-voting",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Trustless pubsub voting over a shared libp2p/Helia node.",
   "type": "module",
   "license": "GPL-3.0-or-later",

package/dist/client/root-puller.d.ts

@@ -1,49 +0,0 @@
-import type { PeerId } from "@libp2p/interface";
-import type { FetchServiceLike } from "../transport/types.js";
-import { type FetchRootRecord } from "../transport/messages.js";
-/**
- * The cold-start root puller: the voter-wide seam every engine's cold-join pull goes through
- * (see DESIGN.md "Checkpoints"). One instance per voter, because everything it guards is
- * per-PEER, not per-topic:
- *
- *   - **Batching.** Pulls to the same peer that arrive within {@link BATCH_WINDOW_MS} coalesce
- *     into ONE fetch stream carrying a batch key ({@link batchRootsFetchKey}), so a directory-
- *     scale join pays the ~2-RTT multistream-select negotiation once per peer instead of once
- *     per contest. A single pending topic skips the batch key entirely (the common single-board
- *     case has zero new wire surface). A responder that predates the batch key answers
- *     NOT_FOUND (or garbage), and the puller falls back to today's per-topic keys.
- *   - **Budget.** At most {@link COLD_START_PEER_FETCH_LIMIT} concurrent fetch streams per peer
- *     across ALL contests, under libp2p's default per-protocol caps (32 inbound on the
- *     responder, 64 outbound on us — both enforced PER CONNECTION per direction, so one
- *     connection's budget is exactly the scope of the remote cap; other users of a shared
- *     seeder arrive on their own connections and do not eat these slots). 24 rather than the
- *     full 32 because running at the cliff still resets: our slot frees when the response
- *     lands, but the responder only decrements its count when it sees the stream *close*, so
- *     back-to-back reuse races that bookkeeping — and the same connection can carry fetch
- *     streams the budget cannot see (the host's own IPNS-over-pubsub record fetches ride the
- *     same protocol; so would a second voter on the shared node).
- *   - **Retry.** A THROWN fetch retries with full-jittered exponential backoff until
- *     {@link COLD_START_FETCH_DEADLINE_MS} — the safety net for a responder saturated by
- *     streams the budget cannot see. While the cap is saturated every freed slot is instantly
- *     retaken, so a fixed attempt count can lose the race and strand a board (measured: no
- *     retry → 32/63 boards converge; 5 fixed retries → 53/63; retry-to-deadline → 63/63). Only
- *     a throw retries — a definitive `undefined`/`null` ("no record") returns as-is — and a
- *     pull whose contest was torn down (`isLive()` false) abandons quietly. Each attempt (not
- *     the whole loop, so a backoff sleep never holds a slot) passes through the budget; queue
- *     wait counts against the same deadline.
- */
-export interface RootPuller {
-    /**
-     * Pull one topic's root record from one peer: the decoded record, or `null`/`undefined`
-     * ("no record", definitive), or a rejection (unreachable peer past the deadline, or a
-     * garbage answer). `isLive` is polled between retries and before resolving, so a contest
-     * left mid-pull abandons instead of holding work alive.
-     */
-    pull(peer: PeerId, topic: string, isLive: () => boolean): Promise<FetchRootRecord | null | undefined>;
-}
-/** See the budget note on {@link RootPuller}. */
-export declare const COLD_START_PEER_FETCH_LIMIT = 24;
-/** See the retry note on {@link RootPuller}. */
-export declare const COLD_START_FETCH_DEADLINE_MS = 30000;
-/** Build the voter-wide puller over the host's fetch service. */
-export declare function makeRootPuller(fetch: FetchServiceLike): RootPuller;

package/dist/client/root-puller.js

@@ -1,140 +0,0 @@
-import pLimit from "p-limit";
-import { batchRootsFetchKey, decodeBatchRootsResponse, decodeRootRecord, rootFetchKey, MAX_BATCH_ROOT_KEYS } from "../transport/messages.js";
-/** See the budget note on {@link RootPuller}. */
-export const COLD_START_PEER_FETCH_LIMIT = 24;
-/** See the retry note on {@link RootPuller}. */
-export const COLD_START_FETCH_DEADLINE_MS = 30_000;
-const COLD_START_FETCH_BACKOFF_MS = 400;
-const COLD_START_FETCH_BACKOFF_CAP_MS = 4_000;
-/**
- * How long a peer's first pending pull waits for same-peer company before its batch flushes.
- * A directory join fires all its cold starts in one synchronous burst, so one tick would
- * usually do; a few ms of slack covers joins interleaved with per-contest async work (topic
- * hashing, chain-client setup) without adding perceptible latency to a lone join.
- */
-const BATCH_WINDOW_MS = 20;
-/**
- * One `pLimit(limitPerPeer)` per peer id, created on first use and dropped once its queue
- * drains, so a long-lived voter does not accumulate limiters for every peer it ever
- * cold-started against.
- */
-function makePerPeerBudget(limitPerPeer) {
-    const limiters = new Map();
-    return async (peerId, task) => {
-        let limiter = limiters.get(peerId);
-        if (limiter === undefined) {
-            limiter = pLimit(limitPerPeer);
-            limiters.set(peerId, limiter);
-        }
-        try {
-            return await limiter(task);
-        }
-        finally {
-            if (limiter.activeCount === 0 && limiter.pendingCount === 0)
-                limiters.delete(peerId);
-        }
-    };
-}
-/** Build the voter-wide puller over the host's fetch service. */
-export function makeRootPuller(fetch) {
-    const budget = makePerPeerBudget(COLD_START_PEER_FETCH_LIMIT);
-    const pending = new Map();
-    /** One budgeted+retried fetch of one key (see the retry note on {@link RootPuller}). */
-    const fetchWithRetry = async (peer, key, isLive) => {
-        const deadline = Date.now() + COLD_START_FETCH_DEADLINE_MS;
-        let lastError;
-        for (let attempt = 0;; attempt++) {
-            if (attempt > 0) {
-                if (!isLive() || Date.now() >= deadline)
-                    break; // left or out of time
-                const ceiling = Math.min(COLD_START_FETCH_BACKOFF_CAP_MS, COLD_START_FETCH_BACKOFF_MS * 2 ** (attempt - 1));
-                await new Promise((resolve) => setTimeout(resolve, Math.random() * ceiling));
-                if (!isLive())
-                    return undefined; // left mid-backoff — abandon quietly
-            }
-            try {
-                return await budget(peer.toString(), () => fetch.fetch(peer, key));
-            }
-            catch (error) {
-                lastError = error; // transient (e.g. responder over its inbound-stream cap) — back off and retry
-            }
-        }
-        throw lastError;
-    };
-    /** The per-topic path: today's `<topic>/root` key; a garbage answer rejects the waiters. */
-    const pullSingle = async (peer, topic, waiters) => {
-        try {
-            const value = await fetchWithRetry(peer, rootFetchKey(topic), () => waiters.some((w) => w.isLive()));
-            const record = value === undefined || value === null ? value : decodeRootRecord(value);
-            waiters.forEach((w) => w.resolve(record));
-        }
-        catch (error) {
-            waiters.forEach((w) => w.reject(error));
-        }
-    };
-    /**
-     * The batch path: one stream, one key carrying every pending topic, answers distributed by
-     * request order. NOT_FOUND (a responder without the batch key), a malformed response, or a
-     * length mismatch all degrade to the per-topic path — never to silence.
-     */
-    const pullBatch = async (peer, topics) => {
-        const order = [...topics.keys()];
-        const isLive = () => [...topics.values()].some((waiters) => waiters.some((w) => w.isLive()));
-        try {
-            const value = await fetchWithRetry(peer, batchRootsFetchKey(order), isLive);
-            if (value !== undefined && value !== null) {
-                let records;
-                try {
-                    records = decodeBatchRootsResponse(value);
-                }
-                catch {
-                    records = undefined; // hostile/buggy answer — fall through to per-topic
-                }
-                if (records !== undefined && records.length === order.length) {
-                    order.forEach((topic, i) => topics.get(topic).forEach((w) => w.resolve(records[i] ?? null)));
-                    return;
-                }
-            }
-            // Old responder (NOT_FOUND) or malformed batch answer: degrade to per-topic keys.
-            await Promise.all([...topics.entries()].map(([topic, waiters]) => pullSingle(peer, topic, waiters)));
-        }
-        catch (error) {
-            for (const waiters of topics.values())
-                waiters.forEach((w) => w.reject(error));
-        }
-    };
-    const flush = (peerId) => {
-        const batch = pending.get(peerId);
-        if (batch === undefined)
-            return;
-        pending.delete(peerId);
-        clearTimeout(batch.timer);
-        // A lone topic keeps today's per-topic key — no batch envelope for the common
-        // single-board join; two or more ride one batch stream.
-        if (batch.topics.size === 1) {
-            for (const [topic, waiters] of batch.topics)
-                void pullSingle(batch.peer, topic, waiters);
-        }
-        else {
-            void pullBatch(batch.peer, batch.topics);
-        }
-    };
-    return {
-        pull: (peer, topic, isLive) => new Promise((resolve, reject) => {
-            const peerId = peer.toString();
-            let batch = pending.get(peerId);
-            if (batch === undefined) {
-                const timer = setTimeout(() => flush(peerId), BATCH_WINDOW_MS);
-                timer.unref?.();
-                batch = { peer, topics: new Map(), timer };
-                pending.set(peerId, batch);
-            }
-            const waiters = batch.topics.get(topic) ?? [];
-            waiters.push({ isLive, resolve, reject });
-            batch.topics.set(topic, waiters);
-            // A full batch flushes immediately; the next pull opens a fresh window.
-            if (batch.topics.size >= MAX_BATCH_ROOT_KEYS)
-                flush(peerId);
-        })
-    };
-}

package/dist/store/indexeddb.d.ts

@@ -1,9 +0,0 @@
-import type { VoteIntent, VoteStore } from "./types.js";
-export declare class IndexedDbVoteStore implements VoteStore {
-    #private;
-    list(): Promise<VoteIntent[]>;
-    get(topic: string): Promise<VoteIntent | undefined>;
-    put(intent: VoteIntent): Promise<void>;
-    delete(topic: string): Promise<void>;
-    destroy(): Promise<void>;
-}

package/dist/store/indexeddb.js

@@ -1,72 +0,0 @@
-import { z } from "zod";
-import { VoteSchema } from "../schema/votes.js";
-/**
- * The browser {@link VoteStore} backend: this wallet's re-signable vote intents in an
- * IndexedDB object store, so republishing survives a page reload (see DESIGN.md "Persistence").
- * It holds only *this* voter's choices — never the CRDT of everyone's bundles.
- *
- * Selected by `selectVoteStore` when a global `indexedDB` is present (the browser); Node uses
- * the SQLite backend instead. No third-party dependency — plain IndexedDB behind small
- * promise wrappers. One record per contest, keyed by `topic`; each record is re-validated
- * through {@link VoteSchema} on read so a corrupt entry cannot smuggle a malformed vote back
- * into the signer.
- */
-const DB_NAME = "bitsocial-pubsub-votes";
-const STORE_NAME = "vote_intents";
-/** The persisted intent shape, re-validated on read (IndexedDB returns `any`). */
-const StoredIntentSchema = z.object({
-    topic: z.string(),
-    address: z.string(),
-    votes: z.array(VoteSchema),
-    lastBucket: z.number()
-});
-/** Wrap an IndexedDB request as a promise. */
-function promisify(request) {
-    return new Promise((resolve, reject) => {
-        request.onsuccess = () => resolve(request.result);
-        request.onerror = () => reject(request.error);
-    });
-}
-export class IndexedDbVoteStore {
-    #db;
-    /** Open (creating the object store on first use) the vote-intents database. */
-    async #open() {
-        if (this.#db !== undefined)
-            return this.#db;
-        const db = await new Promise((resolve, reject) => {
-            const request = indexedDB.open(DB_NAME, 1);
-            request.onupgradeneeded = () => {
-                if (!request.result.objectStoreNames.contains(STORE_NAME)) {
-                    request.result.createObjectStore(STORE_NAME, { keyPath: "topic" });
-                }
-            };
-            request.onsuccess = () => resolve(request.result);
-            request.onerror = () => reject(request.error);
-        });
-        this.#db = db;
-        return db;
-    }
-    async #tx(mode, run) {
-        const db = await this.#open();
-        const store = db.transaction(STORE_NAME, mode).objectStore(STORE_NAME);
-        return run(store);
-    }
-    async list() {
-        const rows = await this.#tx("readonly", (store) => promisify(store.getAll()));
-        return rows.map((row) => StoredIntentSchema.parse(row));
-    }
-    async get(topic) {
-        const row = await this.#tx("readonly", (store) => promisify(store.get(topic)));
-        return row === undefined ? undefined : StoredIntentSchema.parse(row);
-    }
-    async put(intent) {
-        await this.#tx("readwrite", (store) => promisify(store.put(intent)));
-    }
-    async delete(topic) {
-        await this.#tx("readwrite", (store) => promisify(store.delete(topic)));
-    }
-    async destroy() {
-        this.#db?.close();
-        this.#db = undefined;
-    }
-}

package/dist/store/memory.d.ts

@@ -1,15 +0,0 @@
-import type { VoteIntent, VoteStore } from "./types.js";
-/**
- * In-memory {@link VoteStore}: the fallback used on Node when no `dataPath` is given (the
- * durable backends are the browser's IndexedDB and Node's SQLite-under-`dataPath` — see
- * `selectVoteStore` and DESIGN.md "Persistence"). Intents live only for the lifetime of the
- * process, so republishing does NOT survive a restart with this backend. It exists so the
- * voter's lifecycle works with no configured persistence and so unit tests run with no I/O.
- */
-export declare class MemoryVoteStore implements VoteStore {
-    #private;
-    list(): Promise<VoteIntent[]>;
-    get(topic: string): Promise<VoteIntent | undefined>;
-    put(intent: VoteIntent): Promise<void>;
-    delete(topic: string): Promise<void>;
-}

package/dist/store/memory.js

@@ -1,22 +0,0 @@
-/**
- * In-memory {@link VoteStore}: the fallback used on Node when no `dataPath` is given (the
- * durable backends are the browser's IndexedDB and Node's SQLite-under-`dataPath` — see
- * `selectVoteStore` and DESIGN.md "Persistence"). Intents live only for the lifetime of the
- * process, so republishing does NOT survive a restart with this backend. It exists so the
- * voter's lifecycle works with no configured persistence and so unit tests run with no I/O.
- */
-export class MemoryVoteStore {
-    #byTopic = new Map();
-    async list() {
-        return [...this.#byTopic.values()];
-    }
-    async get(topic) {
-        return this.#byTopic.get(topic);
-    }
-    async put(intent) {
-        this.#byTopic.set(intent.topic, intent);
-    }
-    async delete(topic) {
-        this.#byTopic.delete(topic);
-    }
-}

package/dist/store/select.d.ts

@@ -1,15 +0,0 @@
-import type { VoteStore } from "./types.js";
-/**
- * Pick the vote store for a voter by environment:
- *   - a global `indexedDB` (the browser) → the IndexedDB backend;
- *   - otherwise Node with a `dataPath` → a **SQLite file under `dataPath`** (WAL mode, the same
- *     `dataPath` convention pkc-js and `@bitsocial/bso-resolver` use);
- *   - otherwise (Node, no `dataPath`) → in-memory (intents lost on restart).
- *
- * The concrete backends are imported **lazily** (dynamic `import()` inside {@link LazyVoteStore}):
- * the Node backend pulls in the native `better-sqlite3`, which must never enter a browser bundle,
- * and the browser backend touches `indexedDB`, absent on Node. Deferring the import to first use
- * keeps each out of the other environment's module graph while leaving this function synchronous
- * (the `PubsubVoter` constructor stays sync). See DESIGN.md "Persistence".
- */
-export declare function selectVoteStore(dataPath: string | undefined): VoteStore;

package/dist/store/select.js

@@ -1,64 +0,0 @@
-import { MemoryVoteStore } from "./memory.js";
-/**
- * Pick the vote store for a voter by environment:
- *   - a global `indexedDB` (the browser) → the IndexedDB backend;
- *   - otherwise Node with a `dataPath` → a **SQLite file under `dataPath`** (WAL mode, the same
- *     `dataPath` convention pkc-js and `@bitsocial/bso-resolver` use);
- *   - otherwise (Node, no `dataPath`) → in-memory (intents lost on restart).
- *
- * The concrete backends are imported **lazily** (dynamic `import()` inside {@link LazyVoteStore}):
- * the Node backend pulls in the native `better-sqlite3`, which must never enter a browser bundle,
- * and the browser backend touches `indexedDB`, absent on Node. Deferring the import to first use
- * keeps each out of the other environment's module graph while leaving this function synchronous
- * (the `PubsubVoter` constructor stays sync). See DESIGN.md "Persistence".
- */
-export function selectVoteStore(dataPath) {
-    if (typeof indexedDB !== "undefined") {
-        return new LazyVoteStore(async () => {
-            const { IndexedDbVoteStore } = await import("./indexeddb.js");
-            return new IndexedDbVoteStore();
-        });
-    }
-    if (dataPath !== undefined) {
-        return new LazyVoteStore(async () => {
-            const { SqliteVoteStore } = await import("./sqlite.js");
-            return new SqliteVoteStore(dataPath);
-        });
-    }
-    return new MemoryVoteStore();
-}
-/**
- * A {@link VoteStore} that defers constructing its backend until the first method call, so the
- * backend module (and its environment-specific dependency) is only `import()`ed when actually
- * used. The factory runs at most once; every method delegates to the resolved backend.
- */
-class LazyVoteStore {
-    factory;
-    #backend;
-    constructor(factory) {
-        this.factory = factory;
-    }
-    #resolve() {
-        if (this.#backend === undefined)
-            this.#backend = this.factory();
-        return this.#backend;
-    }
-    async list() {
-        return (await this.#resolve()).list();
-    }
-    async get(topic) {
-        return (await this.#resolve()).get(topic);
-    }
-    async put(intent) {
-        return (await this.#resolve()).put(intent);
-    }
-    async delete(topic) {
-        return (await this.#resolve()).delete(topic);
-    }
-    async destroy() {
-        // Nothing to release if the backend was never opened.
-        if (this.#backend === undefined)
-            return;
-        await (await this.#backend).destroy?.();
-    }
-}

package/dist/store/sqlite.d.ts

@@ -1,11 +0,0 @@
-import type { VoteIntent, VoteStore } from "./types.js";
-export declare class SqliteVoteStore implements VoteStore {
-    #private;
-    /** Open (creating if absent) the vote-intents DB inside the `dataPath` directory. */
-    constructor(dataPath: string);
-    list(): Promise<VoteIntent[]>;
-    get(topic: string): Promise<VoteIntent | undefined>;
-    put(intent: VoteIntent): Promise<void>;
-    delete(topic: string): Promise<void>;
-    destroy(): Promise<void>;
-}

package/dist/store/sqlite.js

@@ -1,68 +0,0 @@
-import { mkdirSync } from "node:fs";
-import { join } from "node:path";
-import Database from "better-sqlite3";
-import { z } from "zod";
-import { VoteSchema } from "../schema/votes.js";
-/**
- * The Node {@link VoteStore} backend: this wallet's re-signable vote intents in a SQLite file
- * under the constructor's `dataPath` directory (WAL mode), so republishing survives a process
- * restart (see DESIGN.md "Persistence"). It holds only *this* voter's choices — never the CRDT
- * of everyone's bundles, which lives in the host's Helia blockstore.
- *
- * `better-sqlite3` is a native Node module, so this file is imported **only dynamically** (via
- * `selectVoteStore`), keeping it out of any browser bundle — the browser uses IndexedDB. One
- * row per contest, keyed by `topic`; `votes` is stored as JSON and re-validated through
- * {@link VoteSchema} on read so a hand-edited or corrupt row cannot smuggle a malformed vote
- * back into the signer.
- */
-/** The persisted `votes` column shape, re-validated on read (no `any` from `JSON.parse`). */
-const StoredVotesSchema = z.array(VoteSchema);
-/** The SQLite file name kept inside the `dataPath` directory. */
-const DB_FILENAME = "pubsub-votes.sqlite";
-export class SqliteVoteStore {
-    #db;
-    #listStmt;
-    #getStmt;
-    #putStmt;
-    #deleteStmt;
-    /** Open (creating if absent) the vote-intents DB inside the `dataPath` directory. */
-    constructor(dataPath) {
-        mkdirSync(dataPath, { recursive: true });
-        this.#db = new Database(join(dataPath, DB_FILENAME));
-        this.#db.pragma("journal_mode = WAL");
-        this.#db.exec(`CREATE TABLE IF NOT EXISTS vote_intents (
-                topic TEXT PRIMARY KEY,
-                address TEXT NOT NULL,
-                votes TEXT NOT NULL,
-                last_bucket INTEGER NOT NULL
-            )`);
-        this.#listStmt = this.#db.prepare("SELECT topic, address, votes, last_bucket FROM vote_intents");
-        this.#getStmt = this.#db.prepare("SELECT topic, address, votes, last_bucket FROM vote_intents WHERE topic = ?");
-        this.#putStmt = this.#db.prepare("INSERT OR REPLACE INTO vote_intents (topic, address, votes, last_bucket) VALUES (?, ?, ?, ?)");
-        this.#deleteStmt = this.#db.prepare("DELETE FROM vote_intents WHERE topic = ?");
-    }
-    #rowToIntent(row) {
-        return {
-            topic: row.topic,
-            address: row.address,
-            votes: StoredVotesSchema.parse(JSON.parse(row.votes)),
-            lastBucket: row.last_bucket
-        };
-    }
-    async list() {
-        return this.#listStmt.all().map((row) => this.#rowToIntent(row));
-    }
-    async get(topic) {
-        const row = this.#getStmt.get(topic);
-        return row === undefined ? undefined : this.#rowToIntent(row);
-    }
-    async put(intent) {
-        this.#putStmt.run(intent.topic, intent.address, JSON.stringify(intent.votes), intent.lastBucket);
-    }
-    async delete(topic) {
-        this.#deleteStmt.run(topic);
-    }
-    async destroy() {
-        this.#db.close();
-    }
-}

package/dist/store/types.d.ts

@@ -1,57 +0,0 @@
-import type { Vote } from "../schema/votes.js";
-/**
- * Vote-intent persistence.
- *
- * A live vote decays on its own: a bundle is valid for only `voteExpiryBuckets` after its
- * `blockNumber` (see DESIGN.md "Passive expiry"). Keeping a vote alive means periodically
- * re-signing the *same choice* with a fresh `blockNumber` and re-broadcasting it. To do
- * that across a process restart the voter must remember what it chose — but not the signed
- * bundles (those are immutable, content-addressed, and live in the host's Helia blockstore;
- * a stale `blockNumber` makes an old bundle useless). What it persists is the re-signable
- * *intent*: which communities this wallet picked in which contest. On `start()` the voter loads
- * every stored intent and republishes it; the republish scheduler re-signs each on the
- * liveness cadence (`ceil(voteExpiryBuckets / 2)` buckets — see DESIGN.md "Lifecycle").
- *
- * This is a plain key-value contract, keyed by `topic` (one intent per contest per wallet).
- * It is internal: the library picks the backend by environment — IndexedDB in the browser,
- * a SQLite file under the constructor's `dataPath` on Node — with no host-facing store seam.
- * Declared as its own interface (like `BundleStore` in crdt/types.ts) so the voter can be
- * tested against an in-memory store with no I/O.
- */
-/** One contest's re-signable (or, when empty, re-announceable) choice for this wallet. */
-export interface VoteIntent {
-    /** The gossipsub topic this intent votes in = "bitsocial-votes/" + CID(dag-cbor(criteria)). */
-    topic: string;
-    /** The voting wallet address (recovered from the bundle signature). One intent per topic per address. */
-    address: string;
-    /**
-     * The communities this wallet chose. A non-empty intent is an active vote the scheduler re-signs
-     * (fresh `blockNumber`) each cadence to keep alive. An **empty array is a withdrawal
-     * tombstone**: the empty bundle supersedes the prior vote under LWW, and the scheduler
-     * re-announces its existing CID (never re-signing it) each cadence until it expires, then
-     * deletes the intent — the bundle decays on its own via expiry + prune. See DESIGN.md
-     * "Cancelling a vote".
-     */
-    votes: Vote[];
-    /** The bucket of the last successful republish, so the scheduler knows when the next is due. */
-    lastBucket: number;
-}
-/**
- * Where the voter keeps its own vote intents. Only ever holds *this* voter's choices, not
- * the CRDT of everyone's bundles. `list` feeds the republish loop on `start()`; `put` is
- * written on every cast and every successful republish; `delete` drops an intent that has
- * expired or been explicitly cancelled. `destroy` releases backend handles (close the DB
- * or file) and is called by `PubsubVoter.destroy()`.
- */
-export interface VoteStore {
-    /** Every intent to keep alive. Called once on `start()` to seed the republish scheduler. */
-    list(): Promise<VoteIntent[]>;
-    /** The intent for one contest, or `undefined` if this wallet has not voted there. */
-    get(topic: string): Promise<VoteIntent | undefined>;
-    /** Insert or replace one contest's intent (last write wins, mirroring the CRDT). */
-    put(intent: VoteIntent): Promise<void>;
-    /** Drop one contest's intent (expiry or explicit cancel). Idempotent. */
-    delete(topic: string): Promise<void>;
-    /** Release backend handles. Optional: the in-memory store has nothing to release. */
-    destroy?(): Promise<void>;
-}

package/dist/store/types.js

@@ -1 +0,0 @@
-export {};