@bitsocial/pubsub-voting 0.0.6

package/dist/transport/messages.js

@@ -0,0 +1,117 @@
+import { CID } from "multiformats/cid";
+import * as dagCbor from "@ipld/dag-cbor";
+import { z } from "zod";
+import { encodeCanonical } from "../encoding/canonical.js";
+/**
+ * The pubsub message payload: a two-kind discriminated union (see DESIGN.md "Transport").
+ *
+ *   - `bundle`: one wallet's own bundle as a **live delta** — the exact binary bundle-block
+ *     bytes (crdt/codec.ts) inlined, so the receiver validates straight from the message,
+ *     hashing the embedded bytes yields the bundle CID (the verdict-cache key), and the
+ *     blockstore put is byte-identical. No fetch toward the publisher exists on this path.
+ *   - `root`: the constant-size **root record** `{ version, root, count, sizeBytes }` — the
+ *     checkpoint heartbeat (see DESIGN.md "Checkpoints"). An unverifiable *hint*, never
+ *     trusted; the same record also travels over the libp2p fetch protocol, so its codec is
+ *     standalone (`encodeRootRecord`/`decodeRootRecord`).
+ *
+ * A message carries **no authority** either way: all trust comes from re-verifying the
+ * self-authenticating bundle (or the self-verifying blocks behind a root) before acting.
+ * Encoding is the same canonical dag-cbor as the rest of the protocol; the layout is pinned
+ * by fixed test vectors in `messages.test.ts` — any change is a breaking wire change.
+ */
+/** Envelope wire version (the root record carries its own `version` for the fetch path). */
+export const MESSAGE_VERSION = 1;
+export const ROOT_RECORD_VERSION = 1;
+/** See `z.custom` note in crdt/codec.ts — `z.instanceof(Uint8Array)` over-narrows the buffer type. */
+const BytesSchema = z.custom((value) => value instanceof Uint8Array, "expected bytes");
+const CidSchema = z.custom((value) => CID.asCID(value) !== null, "expected a CID link");
+const RootRecordSchema = z.strictObject({
+    version: z.number().int().positive(),
+    // Points to a `CheckpointRoot` block (`{ chunks: CID[] }`, checkpoint/codec.ts).
+    root: CidSchema,
+    count: z.number().int().nonnegative(),
+    sizeBytes: z.number().int().nonnegative()
+});
+const FetchRootRecordSchema = z.strictObject({
+    version: z.number().int().positive(),
+    root: CidSchema,
+    chunks: z.array(CidSchema),
+    count: z.number().int().nonnegative(),
+    sizeBytes: z.number().int().nonnegative()
+});
+const MessageSchema = z.discriminatedUnion("kind", [
+    z.strictObject({ v: z.literal(MESSAGE_VERSION), kind: z.literal("bundle"), bundle: BytesSchema }),
+    z.strictObject({ v: z.literal(MESSAGE_VERSION), kind: z.literal("root"), record: RootRecordSchema })
+]);
+/** Project any root record (possibly a {@link FetchRootRecord}) to the bare advertisement fields. */
+function toRootRecord(record) {
+    return { version: record.version, root: record.root, count: record.count, sizeBytes: record.sizeBytes };
+}
+/** Encode one bundle's binary block bytes as a live-delta message. */
+export function encodeBundleMessage(blockBytes) {
+    return encodeCanonical({ v: MESSAGE_VERSION, kind: "bundle", bundle: blockBytes });
+}
+/**
+ * Encode a root record as a heartbeat message. The broadcast heartbeat carries only the bare
+ * advertisement (never the fetch response's chunk index), so its size stays a tiny fixed
+ * constant — accepts a {@link FetchRootRecord} and drops the index (see {@link FetchRootRecord}).
+ */
+export function encodeRootMessage(record) {
+    return encodeCanonical({ v: MESSAGE_VERSION, kind: "root", record: RootRecordSchema.parse(toRootRecord(record)) });
+}
+/**
+ * Decode a pubsub payload to its message kind, throwing on anything malformed. The gate
+ * treats a throw as layer-1 badness (`reject`) — the cheapest, pre-verify check.
+ */
+export function decodeVoteMessage(data) {
+    const parsed = MessageSchema.parse(dagCbor.decode(data));
+    return parsed.kind === "bundle" ? { kind: "bundle", bundle: parsed.bundle } : { kind: "root", record: parsed.record };
+}
+/**
+ * The libp2p fetch-protocol key suffix for a topic's root record: the full key is
+ * `topic + "/root"` (the topic prefix only namespaces *which* contest a multi-contest
+ * responder is asked about — it is not a pubsub topic). See DESIGN.md "Checkpoints".
+ */
+export const ROOT_FETCH_KEY_SUFFIX = "/root";
+/** The fetch-protocol key for one contest's root record. */
+export function rootFetchKey(topic) {
+    return `${topic}${ROOT_FETCH_KEY_SUFFIX}`;
+}
+/**
+ * Standalone root-record codec — the record served over the libp2p fetch protocol, carrying the
+ * chunk-CID index so a cold joiner can skip the root-manifest round-trip (see {@link FetchRootRecord}).
+ */
+export function encodeRootRecord(record) {
+    return encodeCanonical(FetchRootRecordSchema.parse(record));
+}
+/** Decode a fetch-protocol root-record value (with its chunk index); throws on malformed. */
+export function decodeRootRecord(bytes) {
+    return FetchRootRecordSchema.parse(dagCbor.decode(bytes));
+}
+/**
+ * The fixed byte cap for a root-kind message. The record is ~100 B by construction (version +
+ * CID link + two small ints + envelope), so this is a generous constant — anything larger is
+ * provably not a well-formed root message.
+ */
+export const MAX_ROOT_MESSAGE_BYTES = 256;
+/** Envelope + fixed bundle fields (address, blockNumber, signature, structure), generously. */
+const BUNDLE_MESSAGE_OVERHEAD_BYTES = 256;
+/**
+ * One vote entry's ceiling: a 253-byte name (the schema's DNS bound), a raw-multihash
+ * publicKey (≲64 B for any realistic key hash), a small int vote, and map structure —
+ * rounded up generously. Generosity is safe: the cap exists to bound *adversarial* payloads,
+ * and what matters is that every peer derives the identical number from the criteria.
+ */
+const MAX_VOTE_ENTRY_BYTES = 512;
+/**
+ * The derived per-message cap for a bundle-kind message — a pure function of the criteria
+ * (see DESIGN.md "Message size cap"): the criteria's own `maxVotesPerAddress` bounds the
+ * entry count, the schema's fixed field bounds (253-byte name, binary crypto fields) bound
+ * the entry size, so every peer computes the same cap from the same criteria bytes and an
+ * over-cap `reject` stays deterministic, penalizable, and cacheable. Deliberately NOT a
+ * criteria field: a raw byte knob could contradict `maxVotesPerAddress` and reject valid
+ * bundles.
+ */
+export function maxBundleMessageBytes(criteria) {
+    return BUNDLE_MESSAGE_OVERHEAD_BYTES + MAX_VOTE_ENTRY_BYTES * criteria.maxVotesPerAddress;
+}

package/dist/transport/rate-limit.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A per-peer fixed-window rate gate for the forward-gate. Bounds how many messages one peer
+ * can make us validate per window, capping the resource cost of a flood of plausible-looking
+ * announcements (the residual "resource exhaustion, not incorrectness" concern in DESIGN.md
+ * "Transport"). Over-rate returns `false`, which the gate maps to `ignore` — dropped without
+ * a peer-score penalty, since being briefly over a local rate is not provable misbehavior.
+ */
+export declare function makeRateLimiter(opts: {
+    limit: number;
+    intervalMs: number;
+}): (peer: string) => boolean;

package/dist/transport/rate-limit.js

@@ -0,0 +1,20 @@
+/**
+ * A per-peer fixed-window rate gate for the forward-gate. Bounds how many messages one peer
+ * can make us validate per window, capping the resource cost of a flood of plausible-looking
+ * announcements (the residual "resource exhaustion, not incorrectness" concern in DESIGN.md
+ * "Transport"). Over-rate returns `false`, which the gate maps to `ignore` — dropped without
+ * a peer-score penalty, since being briefly over a local rate is not provable misbehavior.
+ */
+export function makeRateLimiter(opts) {
+    const windows = new Map();
+    return (peer) => {
+        const now = Date.now();
+        const window = windows.get(peer);
+        if (!window || now - window.start >= opts.intervalMs) {
+            windows.set(peer, { count: 1, start: now });
+            return true;
+        }
+        window.count += 1;
+        return window.count <= opts.limit;
+    };
+}

package/dist/transport/transport.d.ts

@@ -0,0 +1,20 @@
+import type { PubsubService, VoteTransport } from "./types.js";
+import type { GossipGate } from "./gossip-validator.js";
+/**
+ * The live transport: wires the host's gossipsub to the forward-gate. This is the only place
+ * the async validator is installed on a real topic; the decision logic lives in the pure
+ * {@link GossipGate} (gossip-validator.ts), so this module is thin glue.
+ *
+ * On `start` it installs the gate as the topic validator (gossipsub awaits it before
+ * re-forwarding — see DESIGN.md "Transport") and subscribes. Publishing is the live-delta
+ * model: one inline bundle per message (a new vote, a client re-publish, or a withdrawal), or a
+ * root-record heartbeat. Cold-start root pulls ride the libp2p fetch protocol, not pubsub
+ * (see DESIGN.md "Checkpoints").
+ */
+export interface VoteTransportDeps {
+    pubsub: PubsubService;
+    topic: string;
+    /** The forward-gate; validates + merges accepted bundles, surfaces root records. */
+    gate: GossipGate;
+}
+export declare function makeVoteTransport(deps: VoteTransportDeps): VoteTransport;

package/dist/transport/transport.js

@@ -0,0 +1,35 @@
+import { encodeBundleMessage, encodeRootMessage } from "./messages.js";
+export function makeVoteTransport(deps) {
+    const { pubsub, topic, gate } = deps;
+    // The installed gossipsub validator: filter to our topic and run the gate. Returning a
+    // promise makes gossipsub await the full pipeline before forwarding. Accepted bundles are
+    // merged (and root records surfaced) by the gate's own callbacks.
+    const validator = async (peer, message) => {
+        if (message.topic !== topic)
+            return "ignore";
+        return gate.validate(message.data, peer.toString());
+    };
+    return {
+        async start() {
+            if (!pubsub.topicValidators) {
+                throw new Error("the injected pubsub has no `topicValidators` map; a gossipsub service is required to " +
+                    "install the validate-before-forward gate. See DESIGN.md \"Transport\".");
+            }
+            pubsub.topicValidators.set(topic, validator);
+            pubsub.subscribe(topic);
+        },
+        async stop() {
+            pubsub.topicValidators?.delete(topic);
+            pubsub.unsubscribe(topic);
+        },
+        async publishBundle(blockBytes) {
+            // gossipsub resolves `{ recipients }`; a non-gossipsub pubsub may resolve nothing —
+            // fall back to 0 rather than assume the shape.
+            const result = await pubsub.publish(topic, encodeBundleMessage(blockBytes));
+            return { recipientCount: result?.recipients?.length ?? 0 };
+        },
+        async publishRootRecord(record) {
+            await pubsub.publish(topic, encodeRootMessage(record));
+        }
+    };
+}

package/dist/transport/types.d.ts

@@ -0,0 +1,189 @@
+import type { CID } from "multiformats/cid";
+import type { PeerId } from "@libp2p/interface";
+import type { Helia } from "helia";
+import type { RootRecord } from "./messages.js";
+/**
+ * Transport interfaces. This is the ONLY part of the library that
+ * touches libp2p/helia. The core (schema/verify/crdt/tally) does not import it, so the
+ * engine is testable without a network.
+ *
+ * Three exchanges (see DESIGN.md "Transport"):
+ *   - pubsub: broadcast and receive **inline bundle deltas** and **root-record heartbeats**
+ *     (gossipsub), with a topic validator that drops invalid messages before the mesh
+ *     re-forwards them.
+ *   - fetch protocol: pull a connected peer's current root record on cold start / reconnect,
+ *     then union across peers so a single liar cannot hide a vote.
+ *   - directed bitswap: pull the checkpoint blocks behind an advertised root from the
+ *     connected peers that advertised it (through the blockstore) — the only bitswap use.
+ *
+ * The library does not start a node and does not take a host SDK. It receives the
+ * host's already-running **Helia node** directly (e.g. the value `createHelia` returns,
+ * which for a pkc-js host is `pkc.clients.libp2pJsClients[key]._helia`) and drives its
+ * libp2p pubsub + blockstore itself — there is no host-written adapter. The node must
+ * carry a gossipsub service at `libp2p.services.pubsub` and a usable `blockstore`;
+ * construction enforces both (see `requireHeliaServices` / `MissingPubsubError` /
+ * `MissingBlockstoreError`).
+ */
+/**
+ * Verdict from a gossipsub topic validator. Mirrors the semantics of libp2p's
+ * `TopicValidatorResult` (accept / reject / ignore) but is declared locally:
+ * `@libp2p/interface` 3.x no longer re-exports the pubsub types, so the
+ * implementation maps these onto whatever enum the host's gossipsub uses.
+ *   - "accept": valid; deliver to subscribers and let the mesh re-forward it.
+ *   - "reject": invalid; drop, do not forward, and penalize the sender's peer score.
+ *   - "ignore": drop and do not forward, without penalizing (well-formed but not useful).
+ */
+export type TopicValidatorResult = "accept" | "reject" | "ignore";
+/**
+ * The subset of a libp2p pubsub (gossipsub) service this library drives, declared
+ * structurally because `@libp2p/interface` 3.x no longer re-exports `PubSub`. Any
+ * gossipsub implementation the host registers at `services.pubsub` satisfies this
+ * (e.g. `@chainsafe/libp2p-gossipsub`). Kept minimal on purpose; the full transport
+ * (topic validators, fetch protocol) is design-only and may widen this as it lands.
+ */
+export interface PubsubService {
+    /**
+     * Broadcast bytes to a topic mesh. gossipsub resolves to `{ recipients }` — the peers it
+     * *directly sent the RPC to* at publish time (first-hop fan-out, filtered for send failures),
+     * NOT total network reach and NOT an acceptance confirmation (each recipient still runs the
+     * forward-gate). With the host's default `floodPublish`, that's every connected topic peer
+     * above the publish score threshold. Typed loosely (`recipients` optional) so a non-gossipsub
+     * pubsub still satisfies it; the transport reads `recipients?.length ?? 0`. Note gossipsub
+     * *rejects* with `NoPeersSubscribedToTopic` when it would send to zero peers unless the host
+     * sets `allowPublishToZeroTopicPeers`.
+     */
+    publish(topic: string, data: Uint8Array): Promise<{
+        recipients?: readonly PeerId[];
+    }>;
+    /** Join a topic; received messages arrive via the "message" event. */
+    subscribe(topic: string): void;
+    /** Leave a topic. */
+    unsubscribe(topic: string): void;
+    /** Peers we currently see subscribed to a topic, used to pick fetch targets. */
+    getSubscribers(topic: string): PeerId[];
+    addEventListener(type: "message", listener: (evt: {
+        detail: {
+            topic: string;
+            data: Uint8Array;
+            from?: PeerId;
+        };
+    }) => void): void;
+    removeEventListener(type: "message", listener: (evt: {
+        detail: {
+            topic: string;
+            data: Uint8Array;
+            from?: PeerId;
+        };
+    }) => void): void;
+    /**
+     * gossipsub's per-topic validator map. The transport installs the async forward-gate
+     * here (`topicValidators.set(topic, gate)`); gossipsub awaits the returned promise
+     * before re-forwarding the message to the mesh, which is what makes `reject` land on the
+     * sender for semantic invalidity. Optional because a non-gossipsub pubsub lacks it — the
+     * transport checks for it at `start()` and throws if absent. `@libp2p/gossipsub` exposes
+     * it as a mutable `Map`. See DESIGN.md "Transport".
+     */
+    topicValidators?: Map<string, GossipTopicValidator>;
+}
+/** A received pubsub message, as passed to a gossipsub topic validator. */
+export interface GossipMessage {
+    topic: string;
+    data: Uint8Array;
+    from?: PeerId;
+}
+/**
+ * A gossipsub topic validator: run on every received message BEFORE re-forwarding, returning
+ * (or resolving to) a {@link TopicValidatorResult}. Returning a promise makes the gate async —
+ * gossipsub awaits it, so the full fetch + verify pipeline can run before the message is
+ * forwarded (see DESIGN.md "Transport"). Declared structurally so the library imports no
+ * gossipsub package; `@libp2p/gossipsub`'s `TopicValidatorFn` satisfies it.
+ */
+export type GossipTopicValidator = (peer: PeerId, message: GossipMessage) => TopicValidatorResult | Promise<TopicValidatorResult>;
+/**
+ * The subset of the libp2p **fetch service** (`@libp2p/fetch`) this library drives,
+ * declared structurally so no runtime dependency on the package is needed. The host MUST
+ * register it at `libp2p.services.fetch`; construction throws `MissingFetchError`
+ * otherwise. Used for the root-record pull (see DESIGN.md "Checkpoints"): this library
+ * registers a lookup for its own key prefix (the responder) and fetches connected topic
+ * peers' records on cold start (the requester).
+ */
+export interface FetchServiceLike {
+    /** Request the value for `key` from a connected peer; nullish when the peer has none. */
+    fetch(peer: PeerId, key: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Uint8Array | undefined | null>;
+    /**
+     * Register the responder for every key starting with `prefix`. `@libp2p/fetch` invokes the
+     * lookup with the requested key as **raw bytes** (`Uint8Array`), not a string — it matches the
+     * `prefix` against the utf8-decoded key but hands the callback the identifier bytes. The
+     * responder decodes them itself (see `PubsubVoter.#rootLookup`).
+     */
+    registerLookupFunction(prefix: string, lookup: (key: Uint8Array) => Promise<Uint8Array | undefined>): void;
+    /** Remove a registered responder (all of the prefix's, when `lookup` is omitted). */
+    unregisterLookupFunction(prefix: string, lookup?: (key: Uint8Array) => Promise<Uint8Array | undefined>): void;
+}
+/**
+ * The subset of a Helia blockstore this library drives, declared structurally. Vote
+ * bundles are content-addressed blocks fetched/stored by CID through it (bitswap
+ * retrieves through the blockstore). The full `Blocks` type carries progress-event
+ * generics we do not need here.
+ */
+export interface BlockstoreLike {
+    /** `options.signal` cancels an in-flight bitswap fetch — see the chase deadline (DESIGN.md "Checkpoints"). */
+    get(cid: CID, options?: {
+        signal?: AbortSignal;
+    }): Promise<Uint8Array>;
+    put(cid: CID, block: Uint8Array): Promise<CID>;
+    has(cid: CID): Promise<boolean>;
+    /**
+     * Open a provider-scoped bitswap session rooted at `root`: wants go to the session's
+     * providers as targeted session wants instead of a broadcast to every connected peer, and
+     * provider discovery runs once per session instead of once per block (see DESIGN.md "Block
+     * pull"). Optional — plain blockstores (and the unit tests' mocks) lack it; callers MUST
+     * feature-detect and fall back to the broadcast `get`.
+     */
+    createSession?(root: CID, options: {
+        providers: PeerId[];
+        maxProviders?: number;
+    }): BlockSessionLike;
+}
+/**
+ * A session-scoped view of {@link BlockstoreLike.get}, mirroring Helia's `SessionBlockstore`.
+ * Blocks fetched through it still land in the underlying blockstore.
+ */
+export interface BlockSessionLike {
+    get(cid: CID, options?: {
+        signal?: AbortSignal;
+    }): Promise<Uint8Array>;
+    /** Add a late-arriving provider to the running session (rejections are the caller's to swallow). */
+    addPeer(peer: PeerId): Promise<void> | void;
+    /** Abort the session's in-flight wants and release it. */
+    close(): void;
+}
+/**
+ * The host's running Helia node, as injected into {@link PubsubVoter}. Typed with the
+ * default libp2p `ServiceMap`, so `libp2p.services.pubsub` is `unknown` and cannot be
+ * trusted at compile time (a plain Helia node has no pubsub) — `requireHeliaServices`
+ * validates the gossipsub service and the blockstore at construction and narrows them.
+ */
+export type HeliaInstance = Helia;
+/** Live-delta propagation over pubsub (one inline bundle per message + root heartbeats). */
+export interface VoteTransport {
+    /**
+     * Subscribe to the topic and install the async validate-before-forward gate as the
+     * topic validator. See DESIGN.md "Transport: gossipsub topic + validation".
+     */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Publish one bundle's exact binary block bytes as a live delta (a new vote, a client
+     * re-publish, or a withdrawal). Resolves `recipientCount`: how many peers gossipsub sent the
+     * message directly to (see {@link PubsubService.publish} for what that number does and does not
+     * mean).
+     */
+    publishBundle(blockBytes: Uint8Array): Promise<{
+        recipientCount: number;
+    }>;
+    /** Publish a root-record heartbeat (see DESIGN.md "Checkpoints"). */
+    publishRootRecord(record: RootRecord): Promise<void>;
+}

package/dist/transport/types.js

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

package/dist/verify/background.d.ts

@@ -0,0 +1,81 @@
+import type { CID } from "multiformats/cid";
+import type { VotesBundle } from "../schema/votes.js";
+import type { Criteria } from "../schema/criteria.js";
+import type { RuleRegistry } from "../rules/types.js";
+import type { ChainClient, BucketMath, NameResolver } from "../chain/types.js";
+import type { GateResultCache } from "./gate-result-cache.js";
+import { type NameResolutionCache } from "./name-resolution-cache.js";
+import type { VerdictCache } from "./cache.js";
+import type { VerifyFail } from "./types.js";
+/**
+ * The background chain verifier: runs the two deferred NETWORK checks — the on-chain gate
+ * (`rule` scores the wallet `> 0n` at the bucket block) and community-name resolution — for
+ * bundles that were admitted *provisionally* after the synchronous offline checks (signature +
+ * constraints). This is what makes a cold join non-blocking: the chase admits a checkpoint's
+ * bundles on offline validity alone (µs each), the first tally renders immediately with
+ * `chainVerified: false` rows, and this verifier confirms or evicts in the background (see
+ * DESIGN.md "Background chain verification").
+ *
+ * Batched, not sequential: a checkpoint's bundles share one bucket sample block, so the gate
+ * stage groups pending wallets per sample block and prefers the rule's `evaluateMany` (one
+ * multicall3 round trip for N wallets) over N serial `readContract` calls, falling back to
+ * `limit`-bounded per-wallet reads for rules without a batched form. Results feed the shared
+ * `(wallet, sampleBlock)` gate-result cache, and a settled bundle's terminal verdict feeds the
+ * shared per-CID verdict cache — so a later re-publish of the same bundle short-circuits at
+ * the gossip gate with zero chain work.
+ *
+ * Failure classes are kept apart, mirroring the forward-gate's `reject`/`ignore` split:
+ *   - gate scores `0n`            → EVICT + cache the provable `reject` (deterministic).
+ *   - name missing/mismatched     → EVICT, NOT cached (view-dependent `ignore`-class: v1
+ *                                   resolves at head — see verify/bundle.ts step 4).
+ *   - RPC / resolver THREW        → infra, nobody's verdict: the bundle STAYS pending, the
+ *                                   round retries with capped full-jitter backoff, and
+ *                                   `onError` surfaces the degraded state to the host
+ *                                   (Contest `error`) so "RPC down" is not silent.
+ *
+ * Pure seams, no libp2p import — unit-testable offline like the rest of the engine.
+ */
+/** One provisionally admitted bundle awaiting its deferred checks. */
+export interface PendingBundle {
+    cid: CID;
+    bundle: VotesBundle;
+}
+export interface BackgroundVerifierDeps {
+    criteria: Criteria;
+    registry: RuleRegistry;
+    chainFor: (ticker: string) => ChainClient;
+    bucketMath: BucketMath;
+    nameResolvers: NameResolver[];
+    /** Shared `(wallet, sampleBlock)` gate scores — batch results land here, hits skip the read. */
+    gateResultCache: GateResultCache;
+    /** Shared persistent name-resolution cache (pkc-js rule, 1h max-age); omitted ⇒ resolve live. */
+    nameResolutionCache?: NameResolutionCache;
+    /** The gate's per-CID verdict cache — a settled bundle's terminal verdict is stored here. */
+    cache: VerdictCache;
+    /** The bundle's gate read confirmed `> 0n` (flip `chainVerified`, kick the tally). */
+    onGateVerified: (cid: CID) => void;
+    /** The bundle's carried name resolved to its claimed publicKey (flip `nameResolved`). */
+    onNameResolved: (cid: CID) => void;
+    /** Remove a failed bundle from the working set (gate `0n`, or a name that did not check out). */
+    onEvict: (cid: CID, verdict: VerifyFail) => void;
+    /** An infra-class failure (RPC/resolver threw): the round will retry; surface the degradation. */
+    onError: (error: unknown) => void;
+    /** Concurrency cap for the un-batched fallbacks (per-wallet reads, name resolutions). */
+    limit: <T>(fn: () => Promise<T>) => Promise<T>;
+    /** Infra-retry backoff base / cap (ms). Full-jittered exponential between rounds. */
+    retryBaseMs?: number;
+    retryCapMs?: number;
+}
+export interface BackgroundChainVerifier {
+    /** Queue provisionally admitted bundles and return immediately; the drain runs detached. */
+    enqueue(entries: PendingBundle[]): void;
+    /** Bundles whose deferred checks have not settled yet (queued, in-flight, or awaiting retry). */
+    pendingCount(): number;
+    /** Resolves once every queued bundle has settled and no retry is armed (tests/introspection). */
+    idle(): Promise<void>;
+    /** Clear the retry timer (topic leave / voter destroy). Pending state is kept for `resume`. */
+    stop(): void;
+    /** Re-kick the drain after `stop()` if anything is still pending (topic re-join). */
+    resume(): void;
+}
+export declare function makeBackgroundVerifier(deps: BackgroundVerifierDeps): BackgroundChainVerifier;