@bitsocial/pubsub-voting 0.4.1 → 0.6.0

package/dist/client/voter.js

@@ -3,7 +3,6 @@ import { CriteriaSchema } from "../schema/criteria.js";
 import { VotesBundleSchema } from "../schema/votes.js";
 import { coalescingChainFactory } from "../chain/coalescer.js";
 import { makeBucketMath } from "../chain/bucket.js";
-import { tickerForRef } from "../chain/ticker.js";
 import { requireHeliaServices } from "../transport/helia.js";
 import { makeBlockstoreBundleStore } from "../transport/bundle-store.js";
 import { makeRateLimiter } from "../transport/rate-limit.js";
@@ -15,7 +14,7 @@ import { encodeBundle, decodeBundle, bundleCidForBytes } from "../crdt/codec.js"
 import { resolveRegistry, validateCriteriaRules } from "../rules/registry.js";
 import { makeVoteCrdt } from "../crdt/crdt.js";
 import { makePersistentRuleCache } from "../rules/cache.js";
-import { gateFailure, scoreOrZero } from "../rules/result.js";
+import { gateBlame, gateLeaves, gateReason, gateScore } from "../rules/gate.js";
 import { makeBundleVerifier } from "../verify/bundle.js";
 import { makeVerdictCache } from "../verify/cache.js";
 import { makeNameResolutionCache } from "../verify/name-resolution-cache.js";
@@ -32,7 +31,7 @@ import { CID } from "multiformats/cid";
 import { makeTally } from "../tally/tally.js";
 import { ballotTypedData } from "../signer/eip712.js";
 import { criteriaCid, TOPIC_PREFIX } from "../topic.js";
-import { InvalidCommunityNameError, MissingChainClientError, ReadOnlyError, UnknownRuleError, VoteEvictedError, VoterDestroyedError } from "../errors.js";
+import { InvalidCommunityNameError, MissingChainClientError, UnknownRuleError, VoteEvictedError, VoterDestroyedError } from "../errors.js";
 /**
  * The recommended cadence, in buckets, at which a client should re-publish a live vote to keep
  * it alive: half its expiry window, rounded up. A bundle is valid for `voteExpiryBuckets` after
@@ -45,7 +44,7 @@ import { InvalidCommunityNameError, MissingChainClientError, ReadOnlyError, Unkn
  * `blockNumber` on a published `VotesBundle`, and `criteria.voteExpiryBuckets` /
  * `criteria.blocksPerBucket` are what a client uses to schedule its own refreshes: a vote sampled
  * at bucket `b` expires once the current bucket exceeds `b + voteExpiryBuckets`; refresh by
- * calling `createContestVote({ criteria, votes }).publish()` again before then.
+ * calling `createContestVote({ criteria, votes, signer }).publish()` again before then.
  */
 export function republishIntervalBuckets(criteria) {
     return Math.ceil(criteria.voteExpiryBuckets / 2);
@@ -166,6 +165,14 @@ const CHASE_SESSION_PROVIDER_HEADROOM = 1;
  * cannot grow memory.
  */
 const PEER_ROOTS_MAX = 256;
+/**
+ * How many distinct chased roots we remember the contents of, for peer-checkpoint attribution
+ * ({@link ContestEngine.checkpointPeersFor}). Bounded for the same reason as {@link PEER_ROOTS_MAX}:
+ * a busy topic mints a new root on every admitted vote, so an unbounded index would grow with
+ * traffic forever. Forgetting a root only costs attribution for peers still advertising it — the
+ * next chase of a newer root re-establishes it.
+ */
+const DECODED_ROOTS_MAX = 64;
 /**
  * How long a gating-chain head read stays fresh (ms) for the gate's freshness guard. Steady-
  * state votes cost no read (they resolve against the cached bucket); only a look-ahead bundle
@@ -531,14 +538,11 @@ function hexToBytes(hex) {
 class ContestEngine {
     criteria;
     topic;
-    readOnly;
     #deps;
-    /** Chain clients for this contest, built from `criteria.requires.chains` via the factory. */
-    #chainClients;
     #criteriaCid;
-    /** The gating (`rule`) chain's numeric chainId, bound into every ballot signature. */
+    /** The contest's chain id (`criteria.bucketChainId`), bound into every ballot signature. */
     #chainId;
-    /** The gating (`rule`) chain client, also the seed chain for the tally's tie-break block hash. */
+    /** The contest's one chain client, also the seed chain for the tally's tie-break block hash. */
     #ruleChain;
     #bucketMath;
     #crdt;
@@ -601,27 +605,18 @@ class ContestEngine {
     constructor(criteria, topic, criteriaCidBytes, deps) {
         this.criteria = criteria;
         this.topic = topic;
-        this.readOnly = deps.signer === undefined;
         this.#deps = deps;
         this.#criteriaCid = criteriaCidBytes;
-        // Resolve every chain the manifest requires, eagerly: a client with no RPC configured
-        // for one of them must find out at the create seam (recuse), not on its first verify.
-        this.#chainClients = Object.fromEntries(Object.entries(criteria.requires.chains).map(([chain, config]) => {
-            const client = deps.chains({ chain, chainId: config.chainId });
-            if (client === undefined)
-                throw new MissingChainClientError(chain, config.chainId);
-            return [chain, client];
-        }));
-        // The gating (`rule`) chain fixes the ballot's chainId and the tie-break seed chain.
-        const rule = deps.registry[criteria.rule.type];
-        if (!rule)
-            throw new UnknownRuleError("rule", criteria.rule.type);
-        const ruleTicker = tickerForRef(criteria, criteria.rule, rule.optionsSchema.parse(criteria.rule));
-        const ruleChain = this.#chainClients[ruleTicker];
-        if (!ruleChain)
-            throw new Error(`no chain client for gating (\`rule\`) chain "${ruleTicker}"`);
-        this.#ruleChain = ruleChain;
-        this.#chainId = criteria.requires.chains[ruleTicker].chainId;
+        // The contest's ONE chain (`bucketChainId`): it fixes the ballot's chainId, the blocks the
+        // buckets count, the block every rule is handed, and the tie-break seed. Resolved eagerly,
+        // so a client with no RPC configured for it finds out at the create seam (and recuses)
+        // rather than on its first verify.
+        this.#chainId = criteria.bucketChainId;
+        const chain = deps.chains({ chainId: this.#chainId });
+        if (chain === undefined)
+            throw new MissingChainClientError(this.#chainId);
+        this.#ruleChain = chain;
+        const gateRefs = gateLeaves(criteria.gate);
         this.#bucketMath = makeBucketMath(criteria.blocksPerBucket);
         const store = makeBlockstoreBundleStore(deps.blockstore);
         // The CRDT keeps a superseded bundle alive while its superseder's deferred checks are
@@ -632,40 +627,38 @@ class ContestEngine {
             voteExpiryBuckets: criteria.voteExpiryBuckets,
             isProvisional: (cid) => this.#isPending(cid)
         });
-        // The gate rule's memo (rules/cache.ts), shared between the inline forward-gate verifier
-        // and the background chain verifier so neither re-reads what the other settled — layered
-        // over the voter's persistent store and namespaced by the hash of the canonical rule
-        // reference + chainId. That hash is exactly the sharing boundary: two contests over one
-        // gate (a directory of boards on the same Pass) share each other's reads, while
-        // different gates, or one gate on different options, can never collide. What is stored
-        // under it, and for how long, is the rule's business, not the engine's.
-        this.#ruleHash = sha256(encodeDagCbor({ chainId: this.#chainId, rule: criteria.rule }));
-        const gateCache = makePersistentRuleCache({ store: deps.gateStore, namespace: this.#ruleHash });
-        // The weight rule gets its own namespace on the SAME terms — its canonical reference plus
-        // the id of the chain IT reads, which is not necessarily the gating chain. A ticker is
-        // just a name local to the criteria document, so two contests can spell the same weight
-        // ref while `requires.chains` binds that ticker to different chains; keying on the gate's
-        // chainId would let one serve the other's scores from the wrong chain.
+        // One memo per gate leaf (rules/cache.ts), each shared between the inline forward-gate
+        // verifier and the background chain verifier so neither re-reads what the other settled —
+        // layered over the voter's persistent store and namespaced by the hash of that leaf's
+        // canonical rule reference + chainId. That hash is exactly the sharing boundary: two
+        // contests over one gate rule (a directory of boards on the same Pass) share each other's
+        // reads, while different rules, or one rule on different options, can never collide. What
+        // is stored under it, and for how long, is the rule's business, not the engine's. The same
+        // hash is each leaf's public `ruleId` in `checkEligibility` — NOT unique within one gate,
+        // because a rule may be named in two branches, and two positions of one question SHOULD
+        // share a keyspace (see `dedupeLeaves`).
+        this.#gateRefs = gateRefs;
+        this.#ruleIds = gateRefs.map((ref) => sha256(encodeDagCbor({ chainId: this.#chainId, rule: ref })));
+        const gateCaches = this.#ruleIds.map((namespace) => makePersistentRuleCache({ store: deps.gateStore, namespace }));
+        // The weight rule gets its own namespace on the same terms: its canonical reference plus
+        // this contest's chain id. It reads the same chain as everything else here — a weight rule
+        // on a second chain is the same open question as a gate leaf on one.
         const weight = deps.registry[criteria.weight.type];
         if (!weight)
             throw new UnknownRuleError("weight", criteria.weight.type);
-        const weightTicker = tickerForRef(criteria, criteria.weight, weight.optionsSchema.parse(criteria.weight));
-        const weightChainId = criteria.requires.chains[weightTicker]?.chainId;
-        if (weightChainId === undefined)
-            throw new Error(`no chain client for weight chain "${weightTicker}"`);
         const weightCache = makePersistentRuleCache({
             store: deps.gateStore,
-            namespace: sha256(encodeDagCbor({ chainId: weightChainId, rule: criteria.weight }))
+            namespace: sha256(encodeDagCbor({ chainId: this.#chainId, rule: criteria.weight }))
         });
         const verifier = makeBundleVerifier({
             criteria,
             criteriaCid: criteriaCidBytes,
             chainId: this.#chainId,
             registry: deps.registry,
-            chainFor: (ticker) => this.#chainFor(ticker),
+            chain: this.#ruleChain,
             bucketMath: this.#bucketMath,
             nameResolvers: deps.nameResolvers,
-            ruleCache: gateCache,
+            ruleCaches: gateCaches,
             nameResolutionCache: deps.nameResolutionCache,
             readHead: ({ chain }) => this.#readHead({ chain })
         });
@@ -678,10 +671,10 @@ class ContestEngine {
         this.#background = makeBackgroundVerifier({
             criteria,
             registry: deps.registry,
-            chainFor: (ticker) => this.#chainFor(ticker),
+            chain: this.#ruleChain,
             bucketMath: this.#bucketMath,
             nameResolvers: deps.nameResolvers,
-            ruleCache: gateCache,
+            ruleCaches: gateCaches,
             nameResolutionCache: deps.nameResolutionCache,
             readHead: ({ chain }) => this.#readHead({ chain }),
             cache: this.#cache,
@@ -694,7 +687,7 @@ class ContestEngine {
         this.#tally = makeTally({
             criteria,
             registry: deps.registry,
-            chainFor: (ticker) => this.#chainFor(ticker),
+            chain: this.#ruleChain,
             bucketMath: this.#bucketMath,
             readHead: ({ chain }) => this.#readHead({ chain }),
             ruleCache: weightCache,
@@ -705,8 +698,10 @@ class ContestEngine {
         });
     }
     #store;
-    /** Hash of the canonical gate rule + chainId — this contest's keyspace in the shared gate store. */
-    #ruleHash;
+    /** Per gate leaf: hash of its canonical rule ref + chainId — its keyspace in the shared gate store. */
+    #ruleIds;
+    /** The gate's leaf refs in document order, aligned with {@link #ruleIds}. */
+    #gateRefs;
     #cache;
     #acceptedDedup;
     #verifier;
@@ -732,6 +727,45 @@ class ContestEngine {
     #ownPublishes = new Map();
     /** Per-own-CID eviction callbacks: the publishing `ContestVote` registers one at sign time. */
     #ownEvictionCbs = new Map();
+    /**
+     * Per-own-CID verification callbacks — the positive counterpart of {@link #ownEvictionCbs},
+     * registered by the publishing `ContestVote` at sign time and fired once every deferred check
+     * on that bundle has settled clean.
+     */
+    #ownVerifiedCbs = new Map();
+    /**
+     * Per-own-CID first-peer-checkpoint callbacks. Fires once — the state it drives has no
+     * degrees, and a second peer holding the vote is not a new fact about the publish.
+     */
+    #ownCheckpointCbs = new Map();
+    /**
+     * Every bundle CID this wallet published that is still in the working set. Unlike
+     * {@link #ownPublishes} — which exists only to report an eviction and is dropped the moment
+     * the checks settle — this outlives verification, because peer-checkpoint attribution keeps
+     * mattering afterwards: a bundle stays live for `voteExpiryBuckets` and peers go on
+     * re-serving it, so "who else kept my vote" is a longer-lived question than "is it valid".
+     * Dropped on eviction and on expiry prune.
+     */
+    #ownCids = new Set();
+    /**
+     * Roots we decoded → which of OUR CIDs that checkpoint contained. Kept so a peer that
+     * advertises an ALREADY-decoded root is attributed without re-chasing it (the common case:
+     * many peers converge on one root). Bounded by {@link DECODED_ROOTS_MAX}, oldest evicted first.
+     */
+    #decodedRoots = new Map();
+    /**
+     * Own CID → the peers seen advertising a checkpoint that contained it. Bounded twice over:
+     * one entry per own bundle (one per wallet per contest), and the peers can only ever come
+     * from {@link #peerRoots}, itself capped at {@link PEER_ROOTS_MAX}.
+     */
+    #ownCheckpointPeers = new Map();
+    /**
+     * Cap on {@link #ownCids}. A wallet holds one live bundle per contest and a re-publish
+     * supersedes it, so real use sits far below this; the cap exists because
+     * {@link ContestEngine.trackOwnBundle} lets a caller add CIDs, and no public entry point
+     * should be able to grow a map without bound.
+     */
+    static #OWN_CIDS_MAX = 64;
     /** Does any vote in the bundle carry a `community.name` claim (needing resolution)? */
     #carriesName(bundle) {
         return bundle.votes.some((v) => v.community.name !== undefined);
@@ -766,9 +800,13 @@ class ContestEngine {
             return; // evicted or pruned while its check was in flight
         checks[key] = true;
         // A fully settled own publish can no longer be evicted — its verdict is terminal — so
-        // its eviction-reporting entries are done (see #ownPublishes).
-        if (this.#isFullyVerified(cid))
-            this.#dropOwnTracking(cid.toString());
+        // its eviction-reporting entries are done (see #ownPublishes). Tell the publishing
+        // ContestVote first: this is the positive verdict it has no other way to hear.
+        if (this.#isFullyVerified(cid)) {
+            const key = cid.toString();
+            this.#ownVerifiedCbs.get(key)?.(cid);
+            this.#dropOwnTracking(key);
+        }
         this.#onStateChanged();
     }
     /**
@@ -782,11 +820,13 @@ class ContestEngine {
         this.#crdt.remove(cid);
         const key = cid.toString();
         this.#checks.delete(key);
+        this.#ownCids.delete(key);
+        this.#ownCheckpointPeers.delete(key);
         const own = this.#ownPublishes.get(key);
         if (own) {
             const error = new VoteEvictedError(own, verdict);
             const notifyVote = this.#ownEvictionCbs.get(key);
-            this.#dropOwnTracking(key);
+            this.#forgetOwnBundle(key);
             notifyVote?.(error);
             this.#emitError(error);
         }
@@ -796,6 +836,19 @@ class ContestEngine {
     #dropOwnTracking(key) {
         this.#ownPublishes.delete(key);
         this.#ownEvictionCbs.delete(key);
+        this.#ownVerifiedCbs.delete(key);
+    }
+    /**
+     * Forget an own bundle entirely — its verdict-reporting entries AND its peer-checkpoint
+     * attribution. Only for a bundle that has LEFT the working set (evicted or expired):
+     * settlement alone must not reach this, because attribution goes on accruing for a bundle
+     * that is verified and live (see {@link #ownCids}).
+     */
+    #forgetOwnBundle(key) {
+        this.#dropOwnTracking(key);
+        this.#ownCheckpointCbs.delete(key);
+        this.#ownCids.delete(key);
+        this.#ownCheckpointPeers.delete(key);
     }
     #emitError(error) {
         for (const cb of [...this.#errorListeners])
@@ -805,12 +858,6 @@ class ContestEngine {
     emitError(error) {
         this.#emitError(error);
     }
-    #chainFor(ticker) {
-        const client = this.#chainClients[ticker];
-        if (!client)
-            throw new Error(`no chain client configured for chain "${ticker}"`);
-        return client;
-    }
     /**
      * Read the gating-chain head and update {@link #currentBucketCache}; returns the bucket.
      *
@@ -873,21 +920,54 @@ class ContestEngine {
         return sampleBucket <= (await this.#nowBucket());
     }
     /**
-     * Run the gate rule for one wallet, against the ballot block a vote published NOW would carry
-     * — the engine half of {@link Contest.checkEligibility}.
+     * Run the gate for one wallet, against the ballot block a vote published NOW would carry —
+     * the engine half of {@link Contest.checkEligibility}.
      *
-     * All the interesting decisions belong to the rule: this resolves the current bucket's sample
-     * block, hands it over, and translates the rule's own answer. It never looks at what kind of
-     * rule it is holding, so it stays correct for a head-scoring gate, a pinned one, or anything
-     * a host registers later.
+     * All the interesting decisions belong to the rules: this resolves the current bucket's sample
+     * block, hands it over, and translates their own answers. It never looks at what kind of rules
+     * it is holding, so it stays correct for a head-scoring gate, a pinned one, a composite of
+     * both, or anything a host registers later.
      */
     async checkEligibility({ address }) {
         const sampleBlock = this.#bucketMath.sampleBlockForBucket(await this.#nowBucket());
-        const result = await this.#verifier.checkGate({ address, sampleBlock });
-        const failed = gateFailure(result);
-        return failed ? { eligible: false, error: failed.error } : { eligible: true, score: scoreOrZero(result) };
+        const gate = await this.#verifier.checkGates({ address, sampleBlock });
+        const checks = new Map();
+        const node = this.#toEligibilityNode(gate, checks);
+        // Document order, not evaluation order: the leaves as the criteria lists them.
+        const ordered = [...checks.entries()].sort(([a], [b]) => a - b).map(([, check]) => check);
+        if (gate.satisfied === true)
+            return { eligible: true, score: gateScore(gate), checks: ordered, gate: node };
+        return {
+            eligible: false,
+            error: gateReason(gate),
+            // The blame set, not every failed leaf: a failure inside a satisfied `any` explains
+            // nothing the voter can act on (rules/gate.ts `gateBlame`).
+            failures: gateBlame(gate).map((leaf) => checks.get(leaf.leaf)),
+            checks: ordered,
+            gate: node
+        };
     }
-    /** Hash of the current bucket boundary block on the gating (`rule`) chain (rolling tie seed). */
+    /** Project one evaluated gate node onto the public shape, collecting its leaves by index. */
+    #toEligibilityNode(result, checks) {
+        if (result.kind !== "leaf") {
+            return {
+                kind: result.kind,
+                satisfied: result.satisfied,
+                children: result.children.map((child) => this.#toEligibilityNode(child, checks))
+            };
+        }
+        const check = {
+            leaf: result.leaf,
+            ruleId: this.#ruleIds[result.leaf],
+            type: this.#gateRefs[result.leaf].type,
+            satisfied: result.satisfied,
+            score: result.score,
+            ...(result.error === undefined ? {} : { error: result.error })
+        };
+        checks.set(result.leaf, check);
+        return { kind: "leaf", ...check };
+    }
+    /** Hash of the current bucket boundary block on the contest's chain (rolling tie seed). */
     async #bucketBlockHash() {
         const head = await this.#ruleChain.getBlockNumber();
         const boundary = this.#bucketMath.sampleBlockForBucket(this.#bucketMath.bucketForBlock(Number(head)));
@@ -928,7 +1008,7 @@ class ContestEngine {
             for (const removed of await this.#crdt.prune(this.#currentBucketCache)) {
                 const key = removed.toString();
                 this.#checks.delete(key);
-                this.#dropOwnTracking(key); // expiry is decay, not an eviction — no error
+                this.#forgetOwnBundle(key); // expiry is decay, not an eviction — no error
             }
         }
         return this.#tally.compute();
@@ -1063,6 +1143,9 @@ class ContestEngine {
                 this.#markStateChanged();
             },
             deferVerify: (entries) => this.#background.enqueue(entries),
+            // Every CID the checkpoint referenced, admitted or skipped — the skipped ones are
+            // what tier-3 attribution is made of (see #noteCheckpointContents).
+            onCheckpointContents: (root, cids) => this.#noteCheckpointContents(root, cids),
             onMerged: () => this.#onStateChanged(),
             limit: (fn) => chaseLimit(fn),
             timeoutMs: CHASE_TIMEOUT_MS
@@ -1327,15 +1410,13 @@ class ContestEngine {
     /**
      * Sign the votes into a bundle for the current bucket boundary block (the block every verifier
      * reads at), add it to the CRDT, and return the bundle plus its encoded block bytes for
-     * broadcast. Throws `ReadOnlyError` with no signer. `namesSettled` carries the
-     * {@link preflightNames} outcome (default false: name checks still owed to the background
-     * verifier); `onEvicted` is told if a deferred check later evicts THIS bundle — registered
-     * here, before the background verifier can possibly settle, so the report cannot be missed.
+     * broadcast with the wallet the caller hands it (identity is the ballot's, see
+     * {@link VoteClient.createContestVote}). `namesSettled` carries the {@link preflightNames}
+     * outcome (default false: name checks still owed to the background verifier); `onEvicted` is
+     * told if a deferred check later evicts THIS bundle — registered here, before the background
+     * verifier can possibly settle, so the report cannot be missed.
      */
-    async signVote(votes, opts = {}) {
-        const signer = this.#deps.signer;
-        if (signer === undefined)
-            throw new ReadOnlyError();
+    async signVote(votes, signer, opts = {}) {
         const head = await this.#ruleChain.getBlockNumber();
         const bucket = this.#bucketMath.bucketForBlock(Number(head));
         this.#currentBucketCache = bucket;
@@ -1352,11 +1433,16 @@ class ContestEngine {
         // preflight already resolved is recorded settled, so it renders verified immediately.
         this.#recordChecks(cid, bundle, false, opts.namesSettled ?? false);
         this.#ownPublishes.set(cid.toString(), bundle);
+        this.#ownCids.add(cid.toString());
         if (opts.onEvicted)
             this.#ownEvictionCbs.set(cid.toString(), opts.onEvicted);
+        if (opts.onVerified)
+            this.#ownVerifiedCbs.set(cid.toString(), opts.onVerified);
+        if (opts.onCheckpointedByPeer)
+            this.#ownCheckpointCbs.set(cid.toString(), opts.onCheckpointedByPeer);
         this.#background.enqueue([{ cid, bundle }]);
         this.#onStateChanged();
-        return { bundle, encoded: encodeBundle(bundle) };
+        return { bundle, encoded: encodeBundle(bundle), cid };
     }
     /**
      * Broadcast an encoded bundle inline as a live delta (this wallet's own delta, never the set).
@@ -1587,6 +1673,12 @@ class ContestEngine {
         const own = await this.rootRecord();
         if (own.root.equals(record.root)) {
             this.#heardMatchingRoot = true;
+            // Their checkpoint is ours byte for byte, so it demonstrably contains every bundle
+            // ours does — including our own. Nothing is chased here (there is no divergence to
+            // chase), so without this the ONE case tier-3 attribution most wants to catch — a
+            // healthy topic where we and the seeder have converged — would be the one case it
+            // never saw.
+            this.#indexRootContents(record.root, this.#ownVerifiedCids());
             return;
         }
         this.#chaser?.chase(record.root, undefined, this.#sessionProvidersFor(record.root));
@@ -1605,7 +1697,112 @@ class ContestEngine {
             if (oldest !== undefined)
                 this.#peerRoots.delete(oldest);
         }
-        this.#peerRoots.set(peerId, root.toString());
+        const key = root.toString();
+        this.#peerRoots.set(peerId, key);
+        // Many peers converge on one root, and most of them advertise it AFTER we chased it —
+        // so attribution cannot wait for a decode that already happened. #decodedRoots is what
+        // makes that retroactive.
+        this.#attributeRoot(peerId, key);
+    }
+    /**
+     * Record which of OUR bundles a decoded checkpoint contained, and credit every peer already
+     * known to advertise that root. Called once per successful chase decode, with every bundle
+     * CID the checkpoint referenced — INCLUDING ones we already hold, which is the whole point:
+     * our own bundle is always already held, so the chase skips admitting it and would otherwise
+     * never mention it.
+     */
+    #noteCheckpointContents(root, cids) {
+        const mine = new Set();
+        for (const cid of cids) {
+            const key = cid.toString();
+            if (this.#ownCids.has(key))
+                mine.add(key);
+        }
+        this.#indexRootContents(root, mine);
+    }
+    /**
+     * Our own bundles that are in our OWN checkpoint right now — i.e. fully verified ones. A
+     * pending bundle is deliberately excluded: the encoder does not serve it, so a peer holding
+     * our root is not thereby holding it.
+     */
+    #ownVerifiedCids() {
+        const mine = new Set();
+        for (const key of this.#ownCids) {
+            if (this.#isFullyVerified(CID.parse(key)))
+                mine.add(key);
+        }
+        return mine;
+    }
+    /** Index `mine` under `root` (bounded, LRU) and credit every peer already at that root. */
+    #indexRootContents(root, mine) {
+        if (mine.size === 0)
+            return; // nothing of ours in it — not worth an index entry
+        const rootKey = root.toString();
+        if (this.#decodedRoots.has(rootKey))
+            this.#decodedRoots.delete(rootKey); // refresh LRU slot
+        else if (this.#decodedRoots.size >= DECODED_ROOTS_MAX) {
+            const oldest = this.#decodedRoots.keys().next().value;
+            if (oldest !== undefined)
+                this.#decodedRoots.delete(oldest);
+        }
+        this.#decodedRoots.set(rootKey, mine);
+        let credited = false;
+        for (const [peerId, peerRoot] of this.#peerRoots) {
+            if (peerRoot === rootKey)
+                credited = this.#creditPeer(peerId, mine) || credited;
+        }
+        if (credited)
+            this.#onStateChanged();
+    }
+    /** Credit `peerId` with every own CID in a root it advertises, if we decoded that root. */
+    #attributeRoot(peerId, rootKey) {
+        const mine = this.#decodedRoots.get(rootKey);
+        if (mine !== undefined && this.#creditPeer(peerId, mine))
+            this.#onStateChanged();
+    }
+    /** Add `peerId` to each own CID's attribution set; true if anything was new. */
+    #creditPeer(peerId, ownCids) {
+        let added = false;
+        for (const key of ownCids) {
+            if (!this.#ownCids.has(key))
+                continue; // evicted or expired since the decode
+            let peers = this.#ownCheckpointPeers.get(key);
+            if (peers === undefined) {
+                peers = new Set();
+                this.#ownCheckpointPeers.set(key, peers);
+            }
+            if (!peers.has(peerId)) {
+                const first = peers.size === 0;
+                peers.add(peerId);
+                added = true;
+                if (first) {
+                    this.#ownCheckpointCbs.get(key)?.(CID.parse(key));
+                    this.#ownCheckpointCbs.delete(key);
+                }
+            }
+        }
+        return added;
+    }
+    /** {@link Contest.trackOwnBundle}. */
+    trackOwnBundle(cid) {
+        const key = cid.toString();
+        if (this.#ownCids.has(key))
+            return;
+        if (this.#ownCids.size >= ContestEngine.#OWN_CIDS_MAX) {
+            const oldest = this.#ownCids.values().next().value;
+            if (oldest !== undefined)
+                this.#forgetOwnBundle(oldest);
+        }
+        this.#ownCids.add(key);
+    }
+    /** {@link Contest.checksFor}. */
+    checksFor(cid) {
+        const checks = this.#checks.get(cid.toString());
+        return checks === undefined ? undefined : { ...checks };
+    }
+    /** {@link Contest.checkpointPeersFor}. */
+    checkpointPeersFor(cid) {
+        return [...(this.#ownCheckpointPeers.get(cid.toString()) ?? [])];
     }
     /**
      * The session seeds for chasing `root`: every still-connected peer whose last advertised
@@ -1691,6 +1888,15 @@ class ContestView {
     get tally() {
         return this.#engine.cachedTally;
     }
+    checksFor(cid) {
+        return this.#engine.checksFor(cid);
+    }
+    checkpointPeersFor(cid) {
+        return this.#engine.checkpointPeersFor(cid);
+    }
+    trackOwnBundle(cid) {
+        this.#engine.trackOwnBundle(cid);
+    }
     async update() {
         if (this.#subscribed)
             return;
@@ -1738,22 +1944,62 @@ class ContestView {
 class ContestVotePublication {
     contestId;
     votes;
+    signer;
     #engine;
     #stateCbs = [];
     #errorCbs = [];
     #state = "stopped";
     #bundle;
+    #cid;
+    /**
+     * Which `publish()` call owns the state machine. Incremented synchronously at the top of
+     * `publish()`, BEFORE any await, and captured by every callback that attempt registers.
+     *
+     * A re-publish in a later window signs new bytes, so the previous attempt's bundle keeps its
+     * own CID, stays live in the CRDT (a superseded bundle outlives its superseder's deferred
+     * checks) and can still be verified, served by a peer, or evicted — long after a newer
+     * attempt owns this object. Matching on the CID cannot separate the two: `#cid` still holds
+     * the PREVIOUS attempt's value until the new `signVote()` resolves, so an old verdict landing
+     * in that window passes a CID check and moves the wrong attempt. The token is established
+     * before that window opens, so it does not. It also decouples the check from `#cid` entirely,
+     * which is what lets a verdict that settles BEFORE `#cid` is assigned still be delivered
+     * (the engine delivers each callback once and then drops it — a settlement ignored here is
+     * lost for good).
+     */
+    #attempt = 0;
     /**
      * True once the background verifier evicted the current publish's bundle. The eviction can
      * land WHILE `publish()` is still broadcasting (the deferred checks run concurrently), and
      * its `"failed"` is terminal for this attempt — the in-flight publish must not stomp it
-     * with `"publishing"`/`"succeeded"`. Reset by the next `publish()` call.
+     * with `"publishing"`/`"published"`. Reset by the next `publish()` call.
      */
     #evicted = false;
-    constructor(engine, votes) {
+    /** Is this callback's attempt still the one that owns the object? (see {@link #attempt}) */
+    #isCurrent(attempt) {
+        return attempt === this.#attempt;
+    }
+    /**
+     * Advance to a settled state, unless this attempt is already finished or further along.
+     * Two orderings have to be tolerated, not just one: the deferred checks race the broadcast,
+     * so a verdict can land before `publish()` resolves, and a peer can serve our bundle back to
+     * us before our OWN gate read returns — peer evidence is strictly stronger (a peer
+     * checkpoints only fully verified bundles), so it must never be overwritten by the weaker
+     * local one arriving late.
+     */
+    #settle(attempt, state) {
+        if (!this.#isCurrent(attempt))
+            return;
+        if (this.#evicted || this.#state === "failed" || this.#state === "verified-by-peer")
+            return;
+        if (state === "verified-locally" && this.#state === "verified-locally")
+            return;
+        this.#setState(state);
+    }
+    constructor(engine, votes, signer) {
         this.#engine = engine;
         this.contestId = engine.criteria.contestId;
         this.votes = votes;
+        this.signer = signer;
     }
     get topic() {
         return this.#engine.topic;
@@ -1764,6 +2010,9 @@ class ContestVotePublication {
     get bundle() {
         return this.#bundle;
     }
+    get checks() {
+        return this.#cid === undefined ? undefined : this.#engine.checksFor(this.#cid);
+    }
     #setState(state) {
         this.#state = state;
         for (const cb of [...this.#stateCbs])
@@ -1775,12 +2024,11 @@ class ContestVotePublication {
             cb(error);
     }
     async publish() {
-        // Fail before joining a read-only voter needlessly to the topic.
-        if (this.#engine.readOnly) {
-            const error = new ReadOnlyError();
-            this.#fail(error);
-            throw error;
-        }
+        // Before the first await: every callback below is bound to THIS attempt, and the
+        // previous attempt's callbacks stop being able to move this object the moment the
+        // counter ticks — even though its bundle is still live and still verifiable.
+        const attempt = ++this.#attempt;
+        this.#evicted = false;
         try {
             // Name preflight, also before joining: a vote whose carried community name
             // definitively fails to resolve to its claimed key would be silently dropped by
@@ -1789,30 +2037,48 @@ class ContestVotePublication {
             // the background verifier owns the deferred check).
             const namesSettled = await this.#engine.preflightNames(this.votes);
             await this.#engine.join();
-            this.#evicted = false;
             this.#setState("signing");
-            const { bundle, encoded } = await this.#engine.signVote([...this.votes], {
+            const { bundle, encoded, cid } = await this.#engine.signVote([...this.votes], this.signer, {
                 namesSettled,
+                // The positive counterparts of `onEvicted`: our own deferred checks settling
+                // clean, then a peer serving the bundle back to us in its checkpoint. Both
+                // normally land after publish() has resolved.
+                onVerified: () => this.#settle(attempt, "verified-locally"),
+                onCheckpointedByPeer: () => this.#settle(attempt, "verified-by-peer"),
                 // The one rejection a publisher can hear about (peers drop silently): our own
                 // node's deferred checks evicting this bundle. Usually post hoc — publish() has
                 // already resolved — so it surfaces as `error` + `publishingState: "failed"`.
                 onEvicted: (error) => {
+                    // Attempt-scoped like the positive verdicts: a superseded bundle is kept
+                    // alive while its superseder's checks are pending, so an eviction of the
+                    // PREVIOUS attempt's bytes must not fail the attempt that replaced it.
+                    if (!this.#isCurrent(attempt))
+                        return;
                     this.#evicted = true;
                     this.#fail(error);
                 }
             });
             this.#bundle = bundle;
-            if (!this.#evicted)
+            this.#cid = cid;
+            // Only from "signing": a deferred check can settle before this line runs (a cached
+            // verdict needs no round trip), and "publishing" would walk that verdict backwards.
+            if (this.#state === "signing")
                 this.#setState("publishing");
             const { recipientCount } = await this.#engine.broadcastBundle(encoded);
             // An eviction that landed mid-broadcast already failed this attempt; the outcome
-            // still resolves (the bundle DID hit the wire) but the state stays "failed".
-            if (!this.#evicted)
-                this.#setState("succeeded");
-            return { bundle, recipientCount };
+            // still resolves (the bundle DID hit the wire) but the state stays "failed". A
+            // check that SETTLED mid-broadcast is not stomped either: "published" describes
+            // the broadcast, and a verdict already in hand is further along than that.
+            if (!this.#evicted && this.#state === "publishing")
+                this.#setState("published");
+            return { bundle, recipientCount, cid };
         }
         catch (error) {
-            this.#fail(error);
+            // Same scoping: two overlapping `publish()` calls are a misuse, but the loser's
+            // rejection belongs to ITS caller (it is rethrown), not to the state machine a
+            // later attempt now owns.
+            if (this.#isCurrent(attempt))
+                this.#fail(error);
             throw error;
         }
     }
@@ -1878,7 +2144,6 @@ export class PubsubVoter {
             // the background verifier) merge into shared multicall3 round trips under one
             // per-client in-flight budget — see src/chain/coalescer.ts.
             chains: coalescingChainFactory(options.chains),
-            signer: options.signer,
             registry: resolveRegistry(options.rules),
             nameResolvers: options.nameResolvers ?? [],
             onTopicJoined: this.#onTopicJoined,
@@ -1958,9 +2223,6 @@ export class PubsubVoter {
         // Contests can share CIDs (e.g. two vote-less contests share the empty-checkpoint root).
         return [...new Set(keys)];
     };
-    get readOnly() {
-        return this.#deps.signer === undefined;
-    }
     /** Guard the create paths after {@link destroy}: a destroyed voter is terminal. */
     #assertLive() {
         if (this.#destroyed)
@@ -1979,7 +2241,7 @@ export class PubsubVoter {
     async createContestVote(args) {
         this.#assertLive();
         const engine = await this.#engineFor(this.#validateCriteria(args.criteria));
-        return new ContestVotePublication(engine, args.votes);
+        return new ContestVotePublication(engine, args.votes, args.signer);
     }
     /**
      * Strictly validate one criteria document at the create seam: `CriteriaSchema` (shape,