@bitsocial/pubsub-voting 0.4.1 → 0.6.0

package/README.md

@@ -24,7 +24,7 @@ This library does not start its own node. It consumes the host's running Helia n
 
 - **Settings live in the topic.** `topic = "bitsocial-votes/" + CID(dag-cbor(criteria))`. Two peers on the same topic provably ran identical rules, so the network validates itself with no intermediary.
 - **Votes are a state-based grow-only CRDT.** A signed `Votes` bundle is a standalone dag-cbor block (no parent links); each wallet gossips its own bundle **inline as a live delta**, validated straight from the message bytes — no fetch toward the publisher. State is a last-write-wins set keyed by wallet, so aggregation is a monotonic union: a peer can omit a vote but can never subtract one that an honest peer serves. Cold start and gap-fill exchange a tiny **root record** (libp2p-fetch pull + a slow topic heartbeat) and pull the checkpoint blocks behind it via directed bitswap from its advertisers.
-- **The gate and weight are data, not code.** A fixed rule registry (mirroring pkc-js's challenge registry) maps a `type` string to a verifier. v1 ships exactly the soulbound-NFT path — an `erc5192-min-balance` gate `rule` (the 5chan Pass: `balanceOf` **plus** an on-chain assertion that the contract declares its tokens locked, read at the verifier's head so a freshly-acquired Pass votes immediately) and `constant` weight (1 pass = 1 vote). A gate on a *transferable* asset would let one Pass back several concurrent votes, so the plain `erc721-min-balance` rule ships unregistered; balance-derived (token-weighted) voting is deferred. See [DESIGN.md, Does one Pass mean one vote?](./DESIGN.md#does-one-pass-mean-one-vote) and [ROADMAP.md](./ROADMAP.md).
+- **The gate and weight are data, not code.** A fixed rule registry (mirroring pkc-js's challenge registry) maps a `type` string to a verifier, and the criteria's `gate` composes those rules with `all` / `any` — so "the Pass, or a moderator, and not banned" is a document, not a custom rule. v1 ships exactly the soulbound-NFT path — an `erc5192-min-balance` gate (the 5chan Pass: `balanceOf` **plus** an on-chain assertion that the contract declares its tokens locked, read at the verifier's head so a freshly-acquired Pass votes immediately) and `constant` weight (1 pass = 1 vote). A gate on a *transferable* asset would let one Pass back several concurrent votes, so the plain `erc721-min-balance` rule ships unregistered; balance-derived (token-weighted) voting is deferred. See [DESIGN.md, Does one Pass mean one vote?](./DESIGN.md#does-one-pass-mean-one-vote) and [ROADMAP.md](./ROADMAP.md).
 
 See [DESIGN.md](./DESIGN.md) for the full rationale, including how this resists vote-dropping and how criteria upgrades fork cleanly.
 
@@ -34,18 +34,28 @@ See [DESIGN.md](./DESIGN.md) for the full rationale, including how this resists
 
 ## Usage
 
-The library never starts a node and never takes a host SDK (there is no `pkc` argument). A host passes its own running Helia node in directly and injects its seams into a single `PubsubVoter`:
+The library never starts a node and never takes a host SDK (there is no `pkc` argument). A host passes its own running Helia node in directly and injects its seams into a single `PubsubVoter`. **Identity is not one of the seams**: the voting wallet (`VoteSigner`) belongs to each ballot, passed to `createContestVote`, so one voter on the host's shared node publishes for as many wallets as the host holds keys for — and a client that only renders tallies never touches key material.
 
 | Seam | Type | Required | Purpose |
 |---|---|---|---|
 | `helia` | `HeliaInstance` | yes | the host's running Helia node; must carry a gossipsub service at `libp2p.services.pubsub` (else `MissingPubsubError`), a `blockstore` (else `MissingBlockstoreError`), and a libp2p fetch service at `libp2p.services.fetch` (else `MissingFetchError`) |
-| `chains` | `ChainClientFactory` | yes | resolves each chain a contest's criteria requires (`{ chain, chainId }`) to a viem `PublicClient`; rules read through it for the gate and weight. **RPC endpoints are this client's own settings, never part of the criteria document** — return one shared (memoized) client per chain, pointed at a gateway that carries a multicall3 deployment in its viem `chain` config and serves **historical state at least `voteExpiryBuckets × blocksPerBucket` blocks behind head** (the v1 gate reads the head first, but falls back to the block a ballot names — see [Custom rules](#custom-rules)); return `undefined` for a chain with no RPC configured, and `createContest`/`createContestVote` throws `MissingChainClientError` (recuse, don't miscount) |
-| `signer` | `VoteSigner` | no | the voting wallet's address + EIP-712 ballot signing; omit for a read-only voter |
+| `chains` | `ChainClientFactory` | yes | resolves the chain a contest counts in (`{ chainId }`, from `criteria.bucketChainId`) to a viem `PublicClient`; every gate rule and the weight rule read through it. **RPC endpoints are this client's own settings, never part of the criteria document** — return one shared (memoized) client per chain, pointed at a gateway that carries a multicall3 deployment in its viem `chain` config and serves **historical state at least `voteExpiryBuckets × blocksPerBucket` blocks behind head** (the v1 gate reads the head first, but falls back to the block a ballot names — see [Custom rules](#custom-rules)); return `undefined` for a chain with no RPC configured, and `createContest`/`createContestVote` throws `MissingChainClientError` (recuse, don't miscount) |
 | `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 state (gate-result + name-resolution caches, and each joined contest's **checkpoint snapshot** — its last fully-verified winner-set, reloaded at join so a restart with no other peer online keeps the tally), the pkc-js `dataPath` equivalent. Node default: `{cwd}/.bitsocial-pubsub-voting` (better-sqlite3 under `{dataPath}/lru-storage/` + `{dataPath}/checkpoints.db`); in the browser the path is ignored and everything lives in IndexedDB. Pass `false` for in-memory-only (the pkc-js `noData` equivalent). A restart re-serves settled gate reads and fresh name resolutions from the store instead of the RPC, and restores each contest's checkpoint before the cold-start pull. A seeder should always set a stable path |
 | `httpRouterUrls` | `string[]` | no | Delegated Routing V1 router base URLs to **announce provider records to** (one unsigned `PUT /routing/v1/providers` per router; `Keys` batches every joined contest's criteria CID + current checkpoint root + chunk CIDs — hourly, debounced on root changes, and on address changes). **Seeders only**: absent/empty means never announce (the default — plain clients are not dialable), and the browser build never announces regardless. The node must be publicly **reachable** (its listening port open/forwarded/published), but it does not need to know its own public IP: private, loopback, and link-local addrs are filtered client-side, and when nothing survives — the normal zero-config case behind NAT or a Docker bridge, and even on public-IP hosts, since libp2p withholds unconfirmed public addrs pending AutoNAT — the announcer sends the wildcard sentinels (`/ip4/0.0.0.0/...`, `/ip6/::/...`) that the router rewrites to the PUT's observed source IP, exactly as kubo announces work. Configured `addresses.announce` values (concrete public addrs, DNS/AutoTLS, or a kubo-style wildcard) are used as-is. Only a loopback-only node announces nothing. *Querying* needs no URLs here — cold-join discovery uses the injected node's `libp2p.contentRouting`, which the host wires its routers into |
 
-A contest is addressed by its **full criteria document**, passed to `createContest` / `createContestVote`. The document is strictly validated there (`CriteriaSchema` + the rule registry + the `chains` factory: an unimplemented rule throws `UnknownRuleError`, an unresolvable required chain throws `MissingChainClientError` — recuse, don't miscount), and its canonical bytes derive the topic — so the exact document every participant shares is the only contest configuration that exists. The document names each required chain only by ticker + `chainId`; RPC endpoints stay out of it, so operators can swap gateways without forking the topic.
+A contest is addressed by its **full criteria document**, passed to `createContest` / `createContestVote`. The document is strictly validated there (`CriteriaSchema` + the rule registry + the `chains` factory: an unimplemented rule throws `UnknownRuleError`, an unresolvable required chain throws `MissingChainClientError` — recuse, don't miscount), and its canonical bytes derive the topic — so the exact document every participant shares is the only contest configuration that exists. The document names its chain only by `bucketChainId`; RPC endpoints stay out of it, so operators can swap gateways without forking the topic.
+
+Who may vote is the document's `gate` — one rule, or a boolean tree of them:
+
+```ts
+gate: { rule: { type: "erc5192-min-balance", contract: "0x13d4…91b9", min: 1 } }
+gate: { all: [{ rule: passRule }, { rule: notBannedRule }] }          // every rule must admit
+gate: { any: [{ rule: passRule }, { rule: moderatorRule }] }          // any one of them admits
+gate: { all: [{ any: [{ rule: passRule }, { rule: moderatorRule }] }, { rule: notBannedRule }] }
+```
+
+Each rule still answers one question about one wallet and knows nothing about the others; the document composes them. Because the topic is the CID of these bytes, the schema rejects the spellings that would mean the same as a shorter tree — a branch needs **at least two** children, may not repeat a child, and may not nest a branch of its own kind (`{ all: [{ all: [A, B] }, C] }` is just `{ all: [A, B, C] }`) — since each would put one contest on two topics. A rule may appear in two different branches, which is how a gate says "any two of these three": `{ any: [{ all: [A, B] }, { all: [A, C] }, { all: [B, C] }] }`. Trees nest at most 4 deep with at most 8 rules in total. No rule names a chain: every one of them reads the chain the contest counts in (`bucketChainId`), which is the chain the block each rule is handed comes from. Child order is significant and is the order the forward gate evaluates in, so put the cheapest or most discriminating rule first.
 
 ### Construct a voter
 
@@ -61,13 +71,12 @@ const viemChainFactory = (): ChainClientFactory => {
   const clients: Record<number, ReturnType<typeof createPublicClient>> = {
     [base.id]: createPublicClient({ chain: base, transport: http("https://my-trusted-base-rpc.example") })
   };
-  return ({ chainId }) => clients[chainId]; // undefined → recuse contests requiring that chain
+  return ({ chainId }) => clients[chainId]; // undefined → recuse contests counting in that chain
 };
 
 const voter = new PubsubVoter({
   helia,                        // the host's Helia node; needs a gossipsub service at libp2p.services.pubsub + a blockstore
-  chains: viemChainFactory(),   // ({ chain, chainId }) => viem PublicClient | undefined
-  signer: mySigner,             // optional; omit → read-only voter
+  chains: viemChainFactory(),   // ({ chainId }) => viem PublicClient | undefined
   nameResolvers: [bsoResolver], // optional; verifies community-name claims (e.g. @bitsocial/bso-resolver)
   dataPath: "/path/to/data",    // optional; persistent state: caches + checkpoint snapshots (default {cwd}/.bitsocial-pubsub-voting; false → in-memory)
   httpRouterUrls: [             // optional, SEEDERS ONLY (publicly reachable node): announce provider
@@ -78,7 +87,7 @@ const voter = new PubsubVoter({
 
 Construction throws `MissingPubsubError`, `MissingBlockstoreError`, or `MissingFetchError` if the node lacks a usable pubsub service, blockstore, or libp2p fetch service — the library fails fast rather than letting a later `publish`/`subscribe`/`fetch` fail obscurely. ("Bitswap" is not a separately checkable property — it is a block broker wired beneath `blockstore` — so the validated guarantee is a well-formed blockstore, the surface bitswap retrieves through. The fetch service carries the checkpoint root-record pull; the library registers its own responder on it.)
 
-### Read a tally reactively (no signer needed)
+### Read a tally reactively
 
 `createContest` mints a per-contest read object; `update()` starts syncing and it emits `update` (carrying a fresh `tally`) and `error`, just like a pkc-js `community`:
 
@@ -93,20 +102,47 @@ await contest.update();                                   // join the topic, col
 
 ### Will this wallet's vote count?
 
-Ask the contest before signing. `checkEligibility` runs the contest's **real gate rule** through
-the same chain client, head reader and memo the forward gate uses, so it reads at whatever block
-that rule reads at and applies whatever threshold it applies. When it refuses, the `error` is the
-rule's own wording — render it verbatim:
+Ask the contest before signing. `checkEligibility` runs the contest's **real gate rules** through
+the same chain clients, head reader and memos the forward gate uses, so each reads at whatever
+block it reads at and applies whatever threshold it applies. When the gate refuses, the wording is
+the rules' own — render it verbatim:
 
 ```ts
 const check = await contest.checkEligibility({ address: wallet });
 if (check.eligible) {
     show(`eligible — holds ${check.score}`);
 } else {
-    show(check.error);   // e.g. "this wallet holds none of the gate token (0x13d4…91b9)"
+    for (const failure of check.failures) show(failure.error); // e.g. "this wallet holds none of the gate token (0x13d4…91b9)"
 }
 ```
 
+With a composite gate you get one entry per rule, so a client can show a checklist rather than a
+single verdict:
+
+| field | what it is |
+| --- | --- |
+| `checks` | every rule in the gate, in document order: `{ leaf, ruleId, type, satisfied, score, error? }` |
+| `failures` | the rules whose failure **explains** the refusal — render these |
+| `gate` | the same tree as `criteria.gate`, each node carrying its `satisfied`, for rendering the real requirement |
+| `error` | `failures` joined into one sentence, for a caller that only wants a string |
+
+`failures` is deliberately **not** `checks.filter(c => !c.satisfied)`. Under `any`, a wallet that
+qualifies as a moderator also "fails" the Pass rule — telling it to go and buy a Pass would be
+worse than saying nothing.
+
+Key rows by **`leaf`** — the rule's position in the gate, and the only field guaranteed unique in
+one result. `type` is not (a gate may name one rule twice on different options) and neither is
+`ruleId` (a gate may name the same rule in two branches). Use `ruleId` to compare *across* results
+instead: equal ids are one question, so a directory of 63 boards gated on one Pass shows the same
+id everywhere, and shares one chain read behind it.
+
+A check's `satisfied` is `true`, `false`, or **`undefined`** — the last meaning that rule's chain
+read failed and the gate was decided without it. Render it as unknown, never as a requirement the
+wallet is missing: nothing was learned about them. A wallet admitted by a branch that did answer
+still gets `eligible: true` while an unrelated contract's RPC is down; the call throws only when
+the gate cannot be decided without the rule that failed, because at that point there is no honest
+answer to give.
+
 Do **not** reimplement this by reading balances yourself: which block counts is the rule's
 business and changes when the rule changes. A client that hard-codes "peers verify at the bucket
 boundary" keeps telling voters to wait for a window that a head-reading gate no longer imposes.
@@ -138,31 +174,56 @@ A cold join **renders fast and refines**: checkpoint bundles are admitted after
 
 Repeated `createContest` calls with byte-identical criteria return the same `Contest` (engines are keyed by topic, the criteria CID).
 
-### Publish or withdraw a vote (needs a signer)
+### Publish or withdraw a vote
 
-`createContestVote` mints a publishable ballot; `publish()` signs and broadcasts it once and emits `publishingstatechange`, like a pkc-js publication:
+`createContestVote` mints a publishable ballot; `publish()` signs and broadcasts it once and emits `publishingstatechange`, like a pkc-js publication. The `signer` is the ballot's — the wallet that holds the Pass and whose recovered address *is* the voter:
 
 ```ts
-const vote = await voter.createContestVote({ criteria, votes: [{ community: { publicKey: "12D3KooW..." }, vote: 1 }] });
-vote.on("publishingstatechange", (state) => console.log(state)); // stopped → signing → publishing → succeeded (or failed)
-const { bundle, recipientCount } = await vote.publish();          // the signed VotesBundle + how many peers gossipsub sent it directly to
+const vote = await voter.createContestVote({
+  criteria,
+  votes: [{ community: { publicKey: "12D3KooW..." }, vote: 1 }],
+  signer: mySigner                                                // VoteSigner: address() + signBallot()
+});
+vote.on("publishingstatechange", (state) => console.log(state)); // stopped → signing → publishing → published, then verified-locally and/or verified-by-peer (or failed)
+const { bundle, cid, recipientCount } = await vote.publish();     // the signed VotesBundle, its CID, and how many peers gossipsub sent it directly to
+vote.signer === mySigner;                                         // the ballot carries the wallet it was minted with
 
 // Withdraw (active): publish an empty ballot; it supersedes the prior vote under LWW.
-await (await voter.createContestVote({ criteria, votes: [] })).publish();
+await (await voter.createContestVote({ criteria, votes: [], signer: mySigner })).publish();
 ```
 
+A ballot is required to name its wallet, so a client that holds no key simply never mints one — there is no read-only mode to check, and nothing on an unpublished ballot to render. Two wallets on one voter are two `createContestVote` calls with two signers; the CRDT keys them apart by recovered address, so both land in the tally.
+
 A community's identity is its `publicKey`. The optional `name` is the community's resolvable domain (e.g. `memes.bso`) — unique per community, never a free label: the schema requires a TLD, the name is resolved through the injected `nameResolvers` (inline at the forward-gate for live votes, in the background verifier for cold-join admits), and any bundle whose name resolves to a different `publicKey` than claimed is dropped/evicted. Bundles must also name pairwise-distinct `community.publicKey`s. See [DESIGN.md, Votes wire](./DESIGN.md#votes-wire).
 
 `recipientCount` is the peer-reach hint gossipsub reports: how many peers it sent the vote *directly* to at publish time (first-hop fan-out, filtered for send failures) — **not** total network reach, and **not** an acceptance confirmation, since each recipient still runs the forward-gate before re-forwarding. Treat it as a coarse "did this reach anyone?" signal. Note that gossipsub *rejects* the publish with `NoPeersSubscribedToTopic` when it would reach zero peers (common right after joining, before the mesh grafts), unless the host enables `allowPublishToZeroTopicPeers` — so a resolved `recipientCount === 0` only occurs under that host setting; otherwise a no-reach publish surfaces as a thrown error (and a `failed` state).
 
-`publish()` on a voter built without a `signer` throws `ReadOnlyError` (and emits an `error`).
-
 #### Rejection feedback
 
 Gossipsub gives a publisher **no acceptance or rejection feedback** — a peer that drops a bundle does so silently. Since every honest peer runs the same checks this node runs, the library turns its own local verdict into the feedback the protocol can't provide, in two places:
 
 - **At `publish()`**: each vote's `community.name` is preflighted through the shared resolution cache first — a name that definitively fails (no resolver for its TLD, no record, or it resolves to a **different** `publicKey` than the vote claims) throws `InvalidCommunityNameError` before signing or joining the topic, since every verifier would silently drop that bundle anyway. A resolver that merely *throws* (registry outage) never blocks the publish — the check stays deferred to the background verifier.
-- **After `publish()` resolved**: `"succeeded"` means signed and broadcast, **not** accepted by the network. The deferred checks (the on-chain gate read, and any name resolution a preflight outage skipped) run in the background; if one evicts the bundle, the vote emits a `VoteEvictedError` on its `error` event — carrying the evicted `bundle` and the exact `verdict` any verifier would produce — and its `publishingState` flips to `"failed"` post hoc. The same error fires on the contest's `error` event, for long-lived views.
+- **After `publish()` resolved**: `"published"` means signed and broadcast, **not** accepted by the network. The deferred checks (the on-chain gate read, and any name resolution a preflight outage skipped) run in the background; if one evicts the bundle, the vote emits a `VoteEvictedError` on its `error` event — carrying the evicted `bundle` and the exact `verdict` any verifier would produce — and its `publishingState` flips to `"failed"` post hoc. The same error fires on the contest's `error` event, for long-lived views.
+
+The positive verdicts are states too, so a client never has to infer "it counted" from the absence of an error:
+
+- `"verified-locally"` — our own deferred checks came back clean for this bundle. Still our verdict, but every honest peer runs byte-identical checks, so it is the strongest inference available without hearing from anyone.
+- `"verified-by-peer"` — a peer advertised a checkpoint containing this bundle. A node serves only fully verified bundles in its own checkpoint, so an honest peer including it implies that peer verified it too; what is *observed* is that somebody other than us is keeping the vote.
+
+The two are independent outcomes of two asynchronous races, not a sequence: a peer can serve our bundle back before our own gate read returns, in which case `"verified-by-peer"` is reached directly and `"verified-locally"` is never emitted. Peer evidence is the stronger of the two, so it is never walked back to the local verdict arriving late. Treat both as terminal-positive; do not wait for `"verified-locally"` before `"verified-by-peer"`.
+
+Both are readable from the contest by bundle CID, which is how a restored vote asks after a reload — the publishing `ContestVote` is long gone by then, but the vote lives for `voteExpiryBuckets`. Persist `PublishOutcome.cid` and ask with it:
+
+```ts
+contest.checksFor(cid);          // { chainVerified, nameResolved? } — or undefined if not held (never admitted, evicted, expired)
+contest.checkpointPeersFor(cid); // peer ids seen serving OUR bundle back in their checkpoint (own bundles only; a lower bound)
+```
+
+`checksFor` needs nothing extra: the checks are recorded on every admit path, including the snapshot restore. **`checkpointPeersFor` does**, because the engine cannot recognise a bundle it did not sign — the signer belongs to the publication, not the contest, so a restored bundle looks like any other wallet's. A client that persisted the CID re-arms attribution once, after `update()`:
+
+```ts
+contest.trackOwnBundle(cid); // idempotent; attribution runs from here forward, not backwards
+```
 
 ```ts
 vote.on("error", (err) => {
@@ -173,7 +234,7 @@ await vote.publish(); // throws InvalidCommunityNameError if a carried name can'
 
 ### Republishing is the client's job
 
-A vote is not permanent: a bundle is valid only for `voteExpiryBuckets` after its `blockNumber`, so a live vote must be re-published before it decays. **This library does not do that automatically** — it publishes each vote once and the consuming client decides when (or whether) to refresh. To refresh, just `createContestVote(...).publish()` again; a new bundle at the current bucket supersedes the old one. To stop, simply stop refreshing and let the vote lapse. The library gives you what you need to schedule it — all pure, no chain reads:
+A vote is not permanent: a bundle is valid only for `voteExpiryBuckets` after its `blockNumber`, so a live vote must be re-published before it decays. **This library does not do that automatically** — it publishes each vote once and the consuming client decides when (or whether) to refresh. To refresh, just `createContestVote(...).publish()` again (with the same signer); a new bundle at the current bucket supersedes the old one. To stop, simply stop refreshing and let the vote lapse. The library gives you what you need to schedule it — all pure, no chain reads:
 
 ```ts
 import { republishIntervalBuckets } from "@bitsocial/pubsub-voting";
@@ -207,7 +268,7 @@ There is no separate seeder API: a node that joins a topic (via `update()` or `p
 `stop()` leaves every joined topic but keeps the voter **reusable** — each `Contest` can `update()` again and you can `createContest` afterward. `destroy()` is **terminal** (like pkc-js): it leaves every topic, unregisters the fetch responder, and marks the voter and its contests dead — any later `createContest`/`createContestVote`, or a pre-existing `Contest.update()`/`ContestVote.publish()`, throws `VoterDestroyedError`. Construct a new `PubsubVoter` to participate again. (There is no store to dispose — republishing is the client's concern.)
 
 ```ts
-const voter = new PubsubVoter({ helia, chains, signer });
+const voter = new PubsubVoter({ helia, chains });
 // … create + update contests, app runs …
 await voter.destroy();   // terminal: leave all topics, unregister the responder, forbid reuse
 ```
@@ -225,7 +286,7 @@ Full, type-checked call patterns for a pkc-js host, a plebbit/seedit host, and a
 
 ### Custom rules
 
-The gate and weight are a single flat registry of rules, one `type` per file, mirroring the pkc-js challenge registry. Each rule owns its option schema, its own reads (`readContract`, `getBalance`, ... through `ctx.chain`, the viem `PublicClient` for its `options.chain`), which block it reads at, and what it memoizes — see [What a rule owns](#what-a-rule-owns-its-block-and-its-cache) below. There is **one kind**: `evaluate → RuleResult`, either `{ success: true, score }` with a positive score or `{ success: false, error }` — where `error` is the voter-facing reason the rule refused. The criteria has two *slots* drawing from the one registry — the **rule** slot treats the score as a gate (`> 0n` admits), the **weight** slot as the vote's magnitude. A wallet's vote counts as `rule.success ? weight.score : 0n`. A rule that needs a threshold fails below it (so `erc5192-min-balance`'s optional `min` gates), which lets the same rule serve either slot. A chain-reading rule may also implement the optional `evaluateMany({ options, wallets, ctx })` batch hook (`wallets` in place of `wallet`, returning `{ results }` — one per input wallet, in order) — its semantics MUST equal mapping `evaluate` — which the background verifier uses to batch a cold join's gate reads. The batch is simply everything pending, so its wallets need not share a `sampleBlock`: a rule reading the head scores them all at once, a rule reading pinned blocks groups them itself. (`erc5192-min-balance` implements it over multicall3, hoisting its one lock assertion out of the per-wallet reads; see [DESIGN.md, Background chain verification](./DESIGN.md#background-chain-verification).)
+The gate and weight are a single flat registry of rules, one `type` per file, mirroring the pkc-js challenge registry. Each rule owns its option schema, its own reads (`readContract`, `getBalance`, ... through `ctx.chain`, the viem `PublicClient` for its `options.chain`), which block it reads at, and what it memoizes — see [What a rule owns](#what-a-rule-owns-its-block-and-its-cache) below. There is **one kind**: `evaluate → RuleResult`, either `{ success: true, score }` with a positive score or `{ success: false, error }` — where `error` is the voter-facing reason the rule refused. The criteria has two *slots* drawing from the one registry — the **gate** slot treats the score as admission (`> 0n` admits), the **weight** slot as the vote's magnitude. A wallet's vote counts as `gate admits ? weight.score : 0n`. A rule never sees the gate it sits in: composition (`all` / `any`), which failures a voter is shown, and whether a refusal may be blamed on the sender are all folded by the library from what each rule returned. A rule that needs a threshold fails below it (so `erc5192-min-balance`'s optional `min` gates), which lets the same rule serve either slot. A chain-reading rule may also implement the optional `evaluateMany({ options, wallets, ctx })` batch hook (`wallets` in place of `wallet`, returning `{ results }` — one per input wallet, in order) — its semantics MUST equal mapping `evaluate` — which the background verifier uses to batch a cold join's gate reads. The batch is simply everything pending, so its wallets need not share a `sampleBlock`: a rule reading the head scores them all at once, a rule reading pinned blocks groups them itself. (`erc5192-min-balance` implements it over multicall3, hoisting its one lock assertion out of the per-wallet reads; see [DESIGN.md, Background chain verification](./DESIGN.md#background-chain-verification).)
 
 Built-ins: `erc5192-min-balance` (v1) and `constant` (v1).
 
@@ -298,6 +359,8 @@ type RuleResult =
 
 **`penalize`** answers the one thing the library cannot: may the failure be blamed on the sender? `true` (the default) says every honest verifier computes this same failure — true of a read pinned to the block the bundle names — so the forward gate `reject`s the message (penalizing the delivering peer in gossipsub's scoring) and the verdict is cached as terminal. `false` says an honest peer could legitimately disagree, so the bundle is dropped `ignore`-class instead: no penalty, verdict uncached, and the background verifier re-examines it for a grace window before giving up.
 
+Across a composite gate the library folds those answers, and the fold is not a simple OR. An `all` fails as soon as one child does, so **one** attributable failure makes the whole refusal attributable — that rule alone closes the gate identically everywhere. An `any` fails only when every alternative does, so it is attributable only if **every** one of them is: a single unprovable failure means a peer on a fresher chain may be looking at a wallet this gate would admit, and penalizing it would punish honest relaying.
+
 `erc5192-min-balance` reads the head first — so a freshly-acquired Pass counts immediately — falls back to `wallet.sampleBlock` when the head refuses (ERC-5192 does not forbid burning, and without the fallback a burn would erase votes retroactively for peers that had not verified them yet), memoizes each leg under its own epoch, and returns `penalize: false`, because at validation time it cannot attribute a failure to anyone: the peer that forwarded the vote verified it against *its* head. Every other rule in the tree reads `wallet.sampleBlock` and leaves `penalize` at its default — a transferable or fungible balance can decrease, so reading it at the head would silently invalidate votes already counted. See [DESIGN.md, What a rule owns](./DESIGN.md#what-a-rule-owns-and-what-the-pipeline-owns).
 
 ### Weighted voting (deferred)

package/dist/chain/types.d.ts

@@ -18,16 +18,18 @@ import type { PublicClient } from "viem";
  * balance reads or chainTicker-to-RPC mapping. All of this is net-new here.
  */
 export type ChainClient = PublicClient;
-/** chainTicker -> client, built from `criteria.requires.chains`. */
-export type ChainClients = Record<string, ChainClient>;
 /**
- * Factory the host provides: resolve a chain named by the criteria (`requires.chains`,
- * ticker + chainId) to a viem `PublicClient`. The RPC endpoint is the HOST's setting —
- * deliberately not part of the criteria document (see schema/criteria.ts,
- * `ChainConfigSchema`) — so this factory is where ticker/chainId meets the gateways this
- * client trusts (typically `createPublicClient({ chain, transport: http(myRpcUrl) })`).
+ * Factory the host provides: resolve the chain a contest counts in (`criteria.bucketChainId`)
+ * to a viem `PublicClient`. The RPC endpoint is the HOST's setting — deliberately not part of
+ * the criteria document (see schema/criteria.ts, `bucketChainId`) — so this factory is where a
+ * chain id meets the gateways this client trusts (typically
+ * `createPublicClient({ chain, transport: http(myRpcUrl) })`).
  *
- * Return `undefined` (or throw) when no RPC is configured for the named chain: the voter
+ * Keyed by chain ID alone, because that is the identity the criteria carries and the EIP-712
+ * ballot domain is signed over. A contest reads exactly one chain: every gate rule and the
+ * weight rule are handed this client (see DESIGN.md "One clock").
+ *
+ * Return `undefined` (or throw) when no RPC is configured for that chain: the voter
  * then throws `MissingChainClientError` at the create seam (`createContest` /
  * `createContestVote`) — this client must recuse the contest rather than miscount.
  *
@@ -39,7 +41,6 @@ export type ChainClients = Record<string, ChainClient>;
  * to bucket sample blocks) and carries a multicall3 deployment in its viem `chain` config.
  */
 export type ChainClientFactory = (args: {
-    chain: string;
     chainId: number;
 }) => ChainClient | undefined;
 /**

package/dist/client/voter.d.ts

@@ -3,6 +3,8 @@ import { type Vote, type VotesBundle } from "../schema/votes.js";
 import type { ChainClient, ChainClientFactory, NameResolver } from "../chain/types.js";
 import type { HeliaInstance } from "../transport/types.js";
 import type { RuleRegistry } from "../rules/types.js";
+import type { BundleChecks } from "../verify/types.js";
+import { CID } from "multiformats/cid";
 import type { ContestTally } from "../tally/types.js";
 import type { VoteSigner } from "../signer/types.js";
 /**
@@ -17,7 +19,7 @@ import type { VoteSigner } from "../signer/types.js";
  * `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 declare function republishIntervalBuckets(criteria: Criteria): number;
 /**
@@ -42,18 +44,41 @@ export declare function republishIntervalBuckets(criteria: Criteria): number;
  * {@link republishIntervalBuckets} and DESIGN.md "Republishing is the client's job").
  */
 /**
- * A vote publication's lifecycle, walked by {@link ContestVote.publish}. `"succeeded"` means
- * signed, admitted locally, and broadcast — NOT accepted by the network (gossipsub gives a
- * publisher no acceptance/rejection feedback). It can therefore still flip to `"failed"`
- * afterwards: if this node's own deferred checks — the same checks every peer runs — evict the
- * bundle, the vote emits a `VoteEvictedError` and fails post hoc (see DESIGN.md "Background
- * chain verification", publisher feedback).
+ * A vote publication's lifecycle, walked by {@link ContestVote.publish}, then continued by the
+ * deferred checks that settle after it resolves. Three states describe a bundle that is on the
+ * wire, and they are deliberately not synonyms:
+ *
+ *   - `"published"` — signed, admitted to our OWN local set, and broadcast. It says what we did,
+ *     and nothing about anyone else: gossipsub gives a publisher no acceptance feedback, so an
+ *     ineligible wallet reaches this state exactly like an eligible one. (This state was called
+ *     `"succeeded"` before 0.6.0, a name borrowed from pkc-js — where a publish really is
+ *     acknowledged, by the challenge exchange. Nothing acknowledges a vote here.)
+ *   - `"verified-locally"` — OUR deferred checks came back clean for this bundle: the gate rule
+ *     scored the wallet `> 0n` at its bucket block, and every carried `community.name` resolved
+ *     to the key it claimed. Still our own verdict — but every honest peer runs byte-identical
+ *     checks, so it is the strongest inference a publisher can draw without hearing from anyone.
+ *   - `"verified-by-peer"` — a peer advertised a checkpoint that contained this bundle. Since a
+ *     node serves only fully verified bundles in its own checkpoint, an honest peer including it
+ *     implies that peer verified it too; what we OBSERVE is that somebody other than us kept the
+ *     vote. See {@link Contest.checkpointPeersFor} for who, and its caveats.
+ *
+ * `"failed"` is the counterpart of `"verified-locally"`: if the deferred checks EVICT the bundle
+ * the vote emits a `VoteEvictedError` and fails post hoc (see DESIGN.md "Background chain
+ * verification", publisher feedback). The two verified states are reached in order and neither is
+ * reached after `"failed"` — an evicted bundle is gone from the set that checkpoints are cut from.
  */
-export type PublishingState = "stopped" | "signing" | "publishing" | "succeeded" | "failed";
+export type PublishingState = "stopped" | "signing" | "publishing" | "published" | "verified-locally" | "verified-by-peer" | "failed";
 /** What {@link ContestVote.publish} resolves: the signed bundle plus a peer-reach hint. */
 export interface PublishOutcome {
     /** The signed bundle; its `blockNumber` drives the client's own refresh schedule. */
     readonly bundle: VotesBundle;
+    /**
+     * The bundle's CID — the key its deferred-check state and peer attribution are tracked
+     * under. Worth persisting alongside a stored vote: after a reload the `ContestVote` that
+     * published it is gone, and this is what {@link Contest.checksFor} /
+     * {@link Contest.checkpointPeersFor} are asked with.
+     */
+    readonly cid: CID;
     /**
      * How many peers gossipsub sent this vote *directly* to — first-hop fan-out, not total network
      * reach and not an acceptance confirmation (each recipient still runs the forward-gate before
@@ -64,19 +89,73 @@ export interface PublishOutcome {
      */
     readonly recipientCount: number;
 }
-/** One contest's reactive read view: subscribe, keep the tally in sync, read it. */
 /**
- * What {@link Contest.checkEligibility} found. Shaped like {@link RuleResult} on purpose — it is
- * that result, surfaced — so the failing branch always carries a reason a client can display.
+ * One rule's answer about one wallet, as {@link Contest.checkEligibility} reports it.
+ * Shaped like {@link RuleResult} on purpose — it is that result, surfaced — so a failure always
+ * carries a sentence a client can display.
+ */
+export interface EligibilityCheck {
+    /**
+     * This leaf's position in the gate, depth-first in document order — the render key, and the
+     * only field guaranteed unique within one result. `type` is not (a gate may name one rule
+     * twice on different options) and neither is `ruleId` (a gate may name the SAME rule in two
+     * branches, which is how "any two of these three" is written).
+     */
+    readonly leaf: number;
+    /**
+     * Stable identity of this rule INSTANCE — the hash of its canonical criteria reference plus
+     * the id of the chain it reads, which is also the namespace of its memo. Equal ids mean one
+     * question, so they are what to compare ACROSS results: two contests of a 63-board directory
+     * gated on one Pass share this id, and share every chain read behind it. Within one gate two
+     * leaves may share it; use {@link leaf} to tell them apart.
+     */
+    readonly ruleId: string;
+    /** The rule `type` this leaf names, for grouping and labelling. */
+    readonly type: string;
+    /**
+     * `undefined` when this rule has no answer: its chain read failed and the gate was decided
+     * without it. Render it as unknown, never as a failure — nothing was learned about the wallet.
+     */
+    readonly satisfied: boolean | undefined;
+    /** This rule's score for the wallet; `0n` unless it passed. */
+    readonly score: bigint;
+    /** The rule's own explanation, written for the voter. Render it verbatim. */
+    readonly error?: string;
+}
+/**
+ * The gate tree with each node's verdict — the same shape as `criteria.gate`, so a client can
+ * render the real requirement ("the Pass AND not banned", "the Pass OR moderator") instead of a
+ * flat list that cannot express it.
+ */
+export type EligibilityNode = ({
+    kind: "leaf";
+} & EligibilityCheck) | {
+    kind: "all" | "any";
+    satisfied: boolean | undefined;
+    children: EligibilityNode[];
+};
+/**
+ * What {@link Contest.checkEligibility} found.
+ *
+ * `checks` is every rule in the gate, in document order. `failures` is the subset that EXPLAINS a
+ * refusal, which is not the same thing: a rule that failed inside a satisfied `any` branch cost
+ * the wallet nothing, and telling someone to go acquire an asset they do not need is worse than
+ * saying nothing. Render `failures`; use `gate` when the shape of the requirement matters.
  */
 export type EligibilityResult = {
     eligible: true;
-    /** The wallet's gate score, `> 0n`. For a balance gate this is the holding itself. */
+    /** The gate's folded score (min across an `all`, max across an `any`), always `> 0n`. */
     score: bigint;
+    readonly checks: readonly EligibilityCheck[];
+    readonly gate: EligibilityNode;
 } | {
     eligible: false;
-    /** The rule's own explanation, written for the voter. Render it verbatim. */
+    /** The blame set's reasons joined — the one-string form, for a caller that wants one. */
     error: string;
+    /** The rules whose failure explains the refusal. Never empty on this branch. */
+    readonly failures: readonly EligibilityCheck[];
+    readonly checks: readonly EligibilityCheck[];
+    readonly gate: EligibilityNode;
 };
 export interface Contest {
     /** The criteria document this contest runs (already validated). */
@@ -100,28 +179,75 @@ export interface Contest {
     getTally(): Promise<ContestTally>;
     /**
      * Would this contest's gate admit `address` right now? Ask before signing, to tell a voter
-     * whether their ballot will count — and, when it will not, exactly why.
+     * whether their ballot will count — and, when it will not, exactly which rules refused.
      *
-     * This runs the contest's REAL gate rule through the same context the forward-gate and the
-     * background verifier use: the same chain client, the same coalesced head reader, the same
-     * memo. So it reads at whatever block the rule reads at, applies whatever threshold the rule
-     * applies, and returns the rule's own {@link RuleResult.error} wording verbatim. A client
-     * renders `error` and needs to know nothing about blocks, buckets or thresholds — which is
+     * This runs the contest's REAL gate rules through the same context the forward-gate and the
+     * background verifier use: the same chain clients, the same coalesced head reader, the same
+     * memos. So it reads at whatever block each rule reads at, applies whatever thresholds they
+     * apply, and returns their own {@link RuleResult.error} wording verbatim. A client renders
+     * those sentences and needs to know nothing about blocks, buckets or thresholds — which is
      * the point: re-deriving any of that outside the rule is how a UI ends up confidently
      * telling voters to wait for a window that no longer gates anything.
      *
+     * Every leaf is evaluated, even once the outcome is settled, because naming each failure is
+     * what this call is for (the forward gate, which only needs the verdict, stops early instead).
+     * A rule whose chain read fails comes back `satisfied: undefined` rather than sinking the
+     * whole answer — a wallet admitted by a branch that did answer is still told so. It throws
+     * only when the gate cannot be decided without the rule that failed.
+     *
      * It is a courtesy check, not a promise. Eligibility is a fact about the chain and can change
      * between this call and the publish, and each peer verifies against its own view — so a
      * `true` here can still be followed by a `VoteEvictedError` (which carries the same kind of
      * reason). `publish()` deliberately does NOT call this: the gate is the network's decision,
      * and refusing locally would only hide a vote the rest of the topic would have accepted.
      *
-     * Costs one gate evaluation, usually served from the shared memo — the same read the verifier
-     * would do anyway, not an extra one.
+     * Costs one evaluation per gate rule, usually served from the shared memos — the same reads
+     * the verifier would do anyway, not extra ones.
      */
     checkEligibility(args: {
         address: string;
     }): Promise<EligibilityResult>;
+    /**
+     * The deferred-check state of one bundle by CID, or `undefined` if this contest is not
+     * holding that bundle (never admitted, evicted, or expired — the three are not
+     * distinguishable here, and none of them means "counted").
+     *
+     * The publisher's question after a reload. A `ContestVote` reports its own bundle's progress
+     * through `publishingstatechange`, but that object dies with the page, while a vote lives for
+     * `voteExpiryBuckets` — so a tab that restored a vote from its own storage asks here instead,
+     * with the CID from {@link PublishOutcome.cid}.
+     *
+     * `{ chainVerified: true, nameResolved: true | undefined }` is the fully settled state (the
+     * same condition that drives `"verified-locally"`). `chainVerified: false` means NOT YET
+     * READ, never "failed" — a failed gate evicts the bundle, and this returns `undefined`.
+     */
+    checksFor(cid: CID): BundleChecks | undefined;
+    /**
+     * The peers seen advertising a checkpoint that contained `cid` — for THIS wallet's own
+     * published bundles only (see DESIGN.md "Checkpoints"). Empty for anything else, including
+     * other wallets' bundles, which this node deliberately does not index.
+     *
+     * What it proves, exactly: a node serves only fully verified bundles in its own checkpoint,
+     * so an honest peer including ours implies that peer verified it too — but honesty is not
+     * provable, and a peer may serve whatever it likes. So read this as evidence of RETENTION
+     * and propagation ("somebody other than us is keeping this vote"), and only inferentially of
+     * verification. It is also a lower bound in a second way: it counts peers whose checkpoints
+     * we happened to chase, not every peer holding the vote.
+     */
+    checkpointPeersFor(cid: CID): string[];
+    /**
+     * Declare that `cid` is one of THIS client's own published bundles, so peer-checkpoint
+     * attribution starts tracking it. Only needed after a restart: within one session
+     * `publish()` registers its own bundle, but the engine cannot recognise a bundle it did not
+     * sign — the signer belongs to the publication, not to the contest, and a restored bundle
+     * arrives through the snapshot like any other wallet's.
+     *
+     * So a client that persisted {@link PublishOutcome.cid} calls this after `update()` to
+     * re-arm {@link checkpointPeersFor}. Attribution runs from the call forward, not backwards:
+     * the first peer credited is the next one seen advertising a checkpoint that holds the
+     * bundle — at most one heartbeat interval away on a live topic. Idempotent.
+     */
+    trackOwnBundle(cid: CID): void;
     /**
      * Fired when incoming votes change the state; `tally` carries the freshly recomputed
      * ranking. Background check settlements fire it too: a cold join emits a first tally with
@@ -146,21 +272,34 @@ export interface ContestVote {
     readonly topic: string;
     /** The votes this ballot will sign and broadcast (empty array = a withdrawal). */
     readonly votes: readonly Vote[];
+    /**
+     * The wallet that signs this ballot. Identity is per-ballot, not per-voter: one
+     * `PubsubVoter` on the host's shared node publishes for as many wallets as the host holds
+     * keys for, and the address recovered from the signature is the only voter identity there
+     * is (see DESIGN.md "Identity: the voting wallet, nothing else").
+     */
+    readonly signer: VoteSigner;
     /** Where in the publish lifecycle this ballot is. */
     readonly publishingState: PublishingState;
     /** The signed bundle, once `publish()` has produced it (`undefined` before then). */
     readonly bundle: VotesBundle | undefined;
+    /**
+     * This ballot's deferred-check state — which of the two network checks have settled — or
+     * `undefined` before it is signed, and once the bundle has left the working set (evicted or
+     * expired). The detail behind `"verified-locally"`, for a UI that wants to say WHICH check is
+     * still outstanding rather than just "pending".
+     */
+    readonly checks: BundleChecks | undefined;
     /**
      * Sign the votes into a bundle for the current bucket, add it to the local CRDT, and broadcast
      * it once as a live delta. Joins the topic first if needed. Resolves a {@link PublishOutcome}:
      * the `VotesBundle` (whose `blockNumber` the client uses to schedule its own refresh — see
      * {@link republishIntervalBuckets}) plus `recipientCount`, the number of peers gossipsub sent
      * the vote directly to. Emits `publishingstatechange` as it goes; throws (and emits `error`) on
-     * failure: `ReadOnlyError` with no signer, and `InvalidCommunityNameError` when a vote's
-     * carried `community.name` definitively does not resolve to its claimed `publicKey` (checked
-     * BEFORE signing or joining — every verifier drops such a bundle silently, so it is refused
-     * here instead of published into a network-wide silent drop; a resolver outage does not block
-     * the publish). This library does not re-publish: to keep the vote alive, call `publish()`
+     * failure: `InvalidCommunityNameError` when a vote's carried `community.name` definitively does
+     * not resolve to its claimed `publicKey` (checked BEFORE signing or joining — every verifier
+     * drops such a bundle silently, so it is refused here instead of published into a network-wide
+     * silent drop; a resolver outage does not block the publish). This library does not re-publish: to keep the vote alive, call `publish()`
      * again before it expires.
      */
     publish(): Promise<PublishOutcome>;
@@ -177,8 +316,6 @@ export interface ContestVote {
 }
 /** The factory: one set of injected dependencies, many contests. */
 export interface VoteClient {
-    /** True when constructed without a signer: every contest is read-only. */
-    readonly readOnly: boolean;
     /**
      * Create the reactive read view for one contest from its full criteria document. The document
      * is strictly validated (`CriteriaSchema` + the rule registry — an unimplemented rule throws
@@ -193,10 +330,16 @@ export interface VoteClient {
      * Create a publishable ballot for one contest, validated and addressed exactly like
      * `createContest`. Each call returns a fresh `ContestVote` over the shared per-topic engine;
      * pass `votes: []` to build a withdrawal.
+     *
+     * The `signer` is per-ballot, and required. Identity belongs to the vote rather than to the
+     * client, so one voter on the host's shared node can publish for several wallets; and a
+     * ballot that cannot be signed has nothing to show (every other field on it is
+     * publish-derived), so reading a contest is `createContest`'s job, not this one's.
      */
     createContestVote(args: {
         criteria: Criteria;
         votes: Vote[];
+        signer: VoteSigner;
     }): Promise<ContestVote>;
     /**
      * Leave every topic this client joined, resetting each read view so it can `update()` again.
@@ -228,17 +371,15 @@ export interface PubsubVoterOptions {
      */
     helia: HeliaInstance;
     /**
-     * Resolves a chain named by a contest's criteria (`requires.chains`, ticker + chainId)
-     * to a viem `PublicClient`. Which RPC gateway to use is THIS client's setting — RPC URLs
+     * Resolves the chain a contest counts in (`criteria.bucketChainId`) to a viem
+     * `PublicClient`. Which RPC gateway to use is THIS client's setting — RPC URLs
      * are deliberately not part of the criteria document, so this factory is where the host
-     * maps chains to the endpoints it trusts. Return one shared client per chain (memoized),
+     * maps chain ids to the endpoints it trusts. Return one shared client per chain (memoized),
      * and `undefined` for a chain with no RPC configured — `createContest` /
      * `createContestVote` then throws `MissingChainClientError` (recuse, don't miscount).
      * See `ChainClientFactory` (src/chain/types.ts) for the full contract.
      */
     chains: ChainClientFactory;
-    /** Identity. Omit for a read-only voter (renders tallies, cannot publish). */
-    signer?: VoteSigner;
     /** Rule overrides that shadow built-ins by `type` (a flat `type -> rule` map). */
     rules?: RuleRegistry;
     /**
@@ -319,13 +460,13 @@ export declare function makeHeadReader(): (chain: ChainClient) => Promise<bigint
 export declare class PubsubVoter implements VoteClient {
     #private;
     constructor(options: PubsubVoterOptions);
-    get readOnly(): boolean;
     createContest(args: {
         criteria: Criteria;
     }): Promise<Contest>;
     createContestVote(args: {
         criteria: Criteria;
         votes: Vote[];
+        signer: VoteSigner;
     }): Promise<ContestVote>;
     stop(): Promise<void>;
     destroy(): Promise<void>;