@bitsocial/pubsub-voting 0.4.1 → 0.5.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.
 
@@ -39,13 +39,24 @@ The library never starts a node and never takes a host SDK (there is no `pkc` ar
 | 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) |
+| `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) |
 | `signer` | `VoteSigner` | no | the voting wallet's address + EIP-712 ballot signing; omit for a read-only voter |
 | `nameResolvers` | `NameResolver[]` | no | community-name resolvers (same interface and instances as pkc-js's `nameResolvers`, e.g. `@bitsocial/bso-resolver` for `name.bso`); each vote's `community.name` claim is verified through them — inline at the forward-gate for live votes, in the background verifier for cold-join admits — and a bundle whose name resolves to a different `publicKey` than claimed is dropped/evicted |
 | `dataPath` | `string \| false` | no | directory for the voter's persistent 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,12 +72,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
+  chains: viemChainFactory(),   // ({ chainId }) => viem PublicClient | undefined
   signer: mySigner,             // optional; omit → read-only voter
   nameResolvers: [bsoResolver], // optional; verifies community-name claims (e.g. @bitsocial/bso-resolver)
   dataPath: "/path/to/data",    // optional; persistent state: caches + checkpoint snapshots (default {cwd}/.bitsocial-pubsub-voting; false → in-memory)
@@ -93,20 +104,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.
@@ -225,7 +263,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 +336,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

@@ -64,19 +64,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,24 +154,30 @@ 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;
@@ -228,10 +288,10 @@ 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.

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";
@@ -533,12 +532,10 @@ class ContestEngine {
     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;
@@ -604,24 +601,16 @@ class ContestEngine {
         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 +621,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 +665,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 +681,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 +692,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;
@@ -805,12 +794,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 +856,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
+        };
+    }
+    /** 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 gating (`rule`) chain (rolling tie seed). */
+    /** 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)));

package/dist/errors.d.ts

@@ -15,26 +15,24 @@ export declare class NotImplementedError extends Error {
 }
 /**
  * Thrown when a criteria document names a rule `type` this client does not
- * implement (in the `rule`/`weight` slot or in `requires.rules`). A
+ * implement (in a `gate` leaf, the `weight` slot, or in `requires.rules`). A
  * client that hits this is too old (or missing a host override) and must recuse
  * itself from the contest rather than miscount. See DESIGN.md "Rules".
  */
 export declare class UnknownRuleError extends Error {
-    readonly slot: "rule" | "weight" | "requires";
+    readonly slot: "gate" | "weight" | "requires";
     readonly type: string;
-    constructor(slot: "rule" | "weight" | "requires", type: string);
+    constructor(slot: "gate" | "weight" | "requires", type: string);
 }
 /**
- * Thrown by `createContest` / `createContestVote` when the criteria's dependency manifest
- * names a chain (`requires.chains`) the host's `ChainClientFactory` cannot resolve to a
- * client (it returned `undefined`). RPC endpoints are client-local settings, not part of
+ * Thrown by `createContest` / `createContestVote` when the host's `ChainClientFactory` cannot
+ * resolve the contest's `bucketChainId` to a client (it returned `undefined`). RPC endpoints are client-local settings, not part of
  * the criteria document, so a client with no gateway configured for a required chain must
  * recuse the contest rather than miscount — the chain-side twin of `UnknownRuleError`.
  */
 export declare class MissingChainClientError extends Error {
-    readonly chain: string;
     readonly chainId: number;
-    constructor(chain: string, chainId: number);
+    constructor(chainId: number);
 }
 /**
  * Thrown at construction when the injected Helia node's libp2p has no usable pubsub

package/dist/errors.js

@@ -16,7 +16,7 @@ export class NotImplementedError extends Error {
 }
 /**
  * Thrown when a criteria document names a rule `type` this client does not
- * implement (in the `rule`/`weight` slot or in `requires.rules`). A
+ * implement (in a `gate` leaf, the `weight` slot, or in `requires.rules`). A
  * client that hits this is too old (or missing a host override) and must recuse
  * itself from the contest rather than miscount. See DESIGN.md "Rules".
  */
@@ -33,21 +33,18 @@ export class UnknownRuleError extends Error {
     }
 }
 /**
- * Thrown by `createContest` / `createContestVote` when the criteria's dependency manifest
- * names a chain (`requires.chains`) the host's `ChainClientFactory` cannot resolve to a
- * client (it returned `undefined`). RPC endpoints are client-local settings, not part of
+ * Thrown by `createContest` / `createContestVote` when the host's `ChainClientFactory` cannot
+ * resolve the contest's `bucketChainId` to a client (it returned `undefined`). RPC endpoints are client-local settings, not part of
  * the criteria document, so a client with no gateway configured for a required chain must
  * recuse the contest rather than miscount — the chain-side twin of `UnknownRuleError`.
  */
 export class MissingChainClientError extends Error {
-    chain;
     chainId;
-    constructor(chain, chainId) {
-        super(`No chain client for "${chain}" (chainId ${chainId}), which this contest's criteria ` +
-            `requires. RPC endpoints are client settings, not part of the criteria document: ` +
-            `configure the \`chains\` factory (PubsubVoterOptions.chains) to return a viem ` +
-            `PublicClient for this chain, or recuse this contest.`);
-        this.chain = chain;
+    constructor(chainId) {
+        super(`No chain client for chainId ${chainId}, which this contest counts its buckets in ` +
+            `(\`criteria.bucketChainId\`). RPC endpoints are client settings, not part of the ` +
+            `criteria document: configure the \`chains\` factory (PubsubVoterOptions.chains) to ` +
+            `return a viem PublicClient for this chain, or recuse this contest.`);
         this.chainId = chainId;
         this.name = "MissingChainClientError";
     }