@bitsocial/pubsub-voting 0.4.1 → 0.5.0

package/dist/schema/criteria.d.ts

@@ -19,7 +19,7 @@ import { z } from "zod";
 export declare const VoteRangeSchema: z.ZodObject<{
     min: z.ZodNumber;
     max: z.ZodNumber;
-}, z.core.$strip>;
+}, z.core.$strict>;
 /**
  * A reference to a rule by `type`, plus rule-specific options.
  * Kept loose on purpose: each rule owns and validates its own option schema
@@ -31,60 +31,89 @@ export declare const RuleRefSchema: z.ZodObject<{
     type: z.ZodString;
 }, z.core.$loose>;
 /**
- * One chain the contest reads, by ticker. Part of the dependency manifest.
+ * The gate: a boolean tree over rule references, deciding who may vote.
+ *
+ * A leaf wraps one {@link RuleRefSchema}; `all` and `any` compose leaves into conjunction and
+ * disjunction, so a contest can require "holds the Pass AND is not on the deny list", or "holds
+ * the Pass OR is a moderator", without either rule knowing the other exists. Composition is the
+ * document's business, never a rule's: a rule still answers exactly one question about one wallet
+ * (see rules/types.ts), and `rules/gate.ts` folds the answers.
  *
- * Only the `chainId` is here — it is consensus-critical (bound into every EIP-712 ballot
- * domain and defining which chain the rules read). RPC endpoints are deliberately NOT part
- * of the criteria: which gateway a client trusts is client-local transport configuration
- * (`PubsubVoterOptions.chains` maps ticker/chainId to a client), and two honest verifiers
- * reading the same pinned block through different gateways compute identical results. Keeping
- * URLs out means an operator can swap a dead RPC provider without changing the document's
- * bytes — i.e. without forking the topic and orphaning the contest's votes.
+ * The leaf is WRAPPED (`{ rule: { type, ... } }`) rather than bare because {@link RuleRefSchema}
+ * is loose by design — a custom rule may carry an option named `all` or `any`, which would make a
+ * bare leaf structurally ambiguous with a branch exactly when someone writes such a rule.
  *
- * Strict on purpose: the topic is derived from the PARSED document, so an unknown key must
- * fail loudly here — a plain (stripping) object would silently drop it and derive a different
- * topic than the author's raw document implies. This also makes pre-v1 documents that still
- * carry `rpcUrls` a loud error instead of a silent re-topic.
+ * Canonicity constraints, all of them load-bearing rather than stylistic. The topic is the CID of
+ * these bytes, so any document that differs in bytes but not in meaning is a silent topic FORK —
+ * two peers running identical rules on two topics, each invisible to the other:
+ *   - a branch needs at least TWO children, so `{ all: [X] }` cannot exist alongside `X`;
+ *   - a branch may not REPEAT a child (compared by canonical bytes, so two leaves of one rule type
+ *     on different options stay distinct requirements) — a repeat among siblings says nothing the
+ *     shorter tree does not. Across BRANCHES a rule may repeat, deliberately: that is how a gate
+ *     expresses a requirement no repetition-free tree can ("any two of these three" is
+ *     `{ any: [{ all: [A, B] }, { all: [A, C] }, { all: [B, C] }] }`). The price is that some
+ *     redundant spellings survive — `{ all: [{ any: [A, B] }, A] }` is `A` by absorption — so a
+ *     leaf's identity is NOT unique within a gate, and its position is what identifies it
+ *     (`EligibilityCheck.leaf`);
+ *   - a branch may not nest a branch of its OWN kind: `{ all: [{ all: [A, B] }, C] }` admits,
+ *     scores, blames and penalizes exactly as `{ all: [A, B, C] }` does, since min and `some` are
+ *     associative, so the nesting carries no meaning and only new bytes;
+ *   - depth is capped at {@link MAX_GATE_DEPTH} and leaves at {@link MAX_GATE_LEAVES}, because a
+ *     criteria document is attacker-supplied input that every peer parses and evaluates.
+ *
+ * Child ORDER is deliberately significant rather than normalized away: it is what the lazy forward
+ * gate evaluates in, so it decides which rule's chain read is paid first and the order failures are
+ * reported. Two orderings are two documents, and an author picks the one that reads best.
  */
-export declare const ChainConfigSchema: z.ZodObject<{
-    chainId: z.ZodNumber;
-}, z.core.$strict>;
+export interface GateLeaf {
+    rule: RuleRef;
+}
+export interface GateAll {
+    all: GateNode[];
+}
+export interface GateAny {
+    any: GateNode[];
+}
+export type GateNode = GateLeaf | GateAll | GateAny;
+/** Maximum nesting depth of the gate tree (a leaf alone is depth 1). */
+export declare const MAX_GATE_DEPTH = 4;
+/** Maximum number of rule references in one gate tree. */
+export declare const MAX_GATE_LEAVES = 8;
+export declare const GateSchema: z.ZodPipe<z.ZodUnknown, z.ZodType<GateNode, unknown, z.core.$ZodTypeInternals<GateNode, unknown>>>;
 /**
  * The dependency manifest. A client reads this on join and checks that it
  * implements every named rule; if not, it is too old and must recuse
  * itself rather than miscount. This is how criteria upgrades fork cleanly.
+ *
+ * Strict for the same reason the top level is: the topic is derived from the PARSED document, so
+ * an unknown key must fail loudly rather than be stripped — a stripping schema would drop it and
+ * derive a different topic from the one the author's bytes imply. That is what makes a document
+ * still carrying the pre-`bucketChainId` `chains` map (or the even older `rpcUrls`) an error
+ * instead of a silent re-topic.
  */
 export declare const RequiresSchema: z.ZodObject<{
     rules: z.ZodArray<z.ZodString>;
-    chains: z.ZodRecord<z.ZodString, z.ZodObject<{
-        chainId: z.ZodNumber;
-    }, z.core.$strict>>;
-}, z.core.$strip>;
+}, z.core.$strict>;
 export declare const CriteriaSchema: z.ZodObject<{
     name: z.ZodString;
     contestId: z.ZodString;
     voteSchema: z.ZodObject<{
         min: z.ZodNumber;
         max: z.ZodNumber;
-    }, z.core.$strip>;
+    }, z.core.$strict>;
     maxVotesPerAddress: z.ZodNumber;
+    bucketChainId: z.ZodNumber;
     blocksPerBucket: z.ZodNumber;
     voteExpiryBuckets: z.ZodNumber;
-    rule: z.ZodObject<{
-        type: z.ZodString;
-    }, z.core.$loose>;
+    gate: z.ZodPipe<z.ZodUnknown, z.ZodType<GateNode, unknown, z.core.$ZodTypeInternals<GateNode, unknown>>>;
     weight: z.ZodObject<{
         type: z.ZodString;
     }, z.core.$loose>;
     requires: z.ZodObject<{
         rules: z.ZodArray<z.ZodString>;
-        chains: z.ZodRecord<z.ZodString, z.ZodObject<{
-            chainId: z.ZodNumber;
-        }, z.core.$strict>>;
-    }, z.core.$strip>;
+    }, z.core.$strict>;
 }, z.core.$strict>;
 export type VoteRange = z.infer<typeof VoteRangeSchema>;
 export type RuleRef = z.infer<typeof RuleRefSchema>;
-export type ChainConfig = z.infer<typeof ChainConfigSchema>;
 export type Requires = z.infer<typeof RequiresSchema>;
 export type Criteria = z.infer<typeof CriteriaSchema>;

package/dist/schema/criteria.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ChainTickerSchema } from "./common.js";
+import { encodeCanonical } from "../encoding/canonical.js";
 /**
  * The criteria document.
  *
@@ -17,7 +17,7 @@ import { ChainTickerSchema } from "./common.js";
  * a non-canonical change silently changes the topic.
  */
 /** Inclusive numeric bounds for a single `vote` value. v1 is { min: 1, max: 1 }. */
-export const VoteRangeSchema = z.object({
+export const VoteRangeSchema = z.strictObject({
     min: z.number().int(),
     max: z.number().int()
 });
@@ -31,33 +31,108 @@ export const VoteRangeSchema = z.object({
 export const RuleRefSchema = z.looseObject({
     type: z.string().min(1)
 });
+/** Maximum nesting depth of the gate tree (a leaf alone is depth 1). */
+export const MAX_GATE_DEPTH = 4;
+/** Maximum number of rule references in one gate tree. */
+export const MAX_GATE_LEAVES = 8;
+const GateNodeSchema = z.lazy(() => z.union([
+    z.strictObject({ rule: RuleRefSchema }),
+    z.strictObject({ all: z.array(GateNodeSchema).min(2) }),
+    z.strictObject({ any: z.array(GateNodeSchema).min(2) })
+]));
+/** Depth (a leaf is 1), leaf count, and the redundant spellings, in one walk. */
+function gateShape(node) {
+    if ("rule" in node)
+        return { depth: 1, leaves: 1, redundant: undefined };
+    const kind = "all" in node ? "all" : "any";
+    const children = "all" in node ? node.all : node.any;
+    let depth = 0;
+    let leaves = 0;
+    let redundant;
+    // Canonical bytes are the identity: two children that encode identically ARE the same
+    // requirement, however differently they were written. Siblings only — a rule repeated in
+    // another branch is how a gate expresses "any two of these three".
+    const seen = new Set();
+    for (const child of children) {
+        const shape = gateShape(child);
+        depth = Math.max(depth, shape.depth);
+        leaves += shape.leaves;
+        redundant ??= shape.redundant;
+        if (kind in child) {
+            redundant ??= `a \`${kind}\` nested directly inside an \`${kind}\` says nothing its parent does not; inline its children`;
+        }
+        const bytes = bytesToHex(encodeCanonical(child));
+        if (seen.has(bytes))
+            redundant ??= `a \`${kind}\` repeats one of its children; drop the duplicate`;
+        seen.add(bytes);
+    }
+    return { depth: depth + 1, leaves, redundant };
+}
+const bytesToHex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
 /**
- * One chain the contest reads, by ticker. Part of the dependency manifest.
- *
- * Only the `chainId` is here — it is consensus-critical (bound into every EIP-712 ballot
- * domain and defining which chain the rules read). RPC endpoints are deliberately NOT part
- * of the criteria: which gateway a client trusts is client-local transport configuration
- * (`PubsubVoterOptions.chains` maps ticker/chainId to a client), and two honest verifiers
- * reading the same pinned block through different gateways compute identical results. Keeping
- * URLs out means an operator can swap a dead RPC provider without changing the document's
- * bytes — i.e. without forking the topic and orphaning the contest's votes.
- *
- * Strict on purpose: the topic is derived from the PARSED document, so an unknown key must
- * fail loudly here — a plain (stripping) object would silently drop it and derive a different
- * topic than the author's raw document implies. This also makes pre-v1 documents that still
- * carry `rpcUrls` a loud error instead of a silent re-topic.
+ * Structural bounds, checked on the RAW value before the recursive schema ever descends into it.
+ * {@link GateNodeSchema} is `z.lazy` and {@link gateShape} recurses, so a pathological document
+ * overflows the stack long before any cap can fire — and a `RangeError` escaping `safeParse`
+ * breaks the one guarantee that call makes. This walk is iterative and stops at the first node
+ * past a bound; anything within them it passes through untouched, so the real schema still
+ * produces the precise error for an ordinary authoring mistake.
  */
-export const ChainConfigSchema = z.strictObject({
-    chainId: z.number().int().positive()
+const MAX_GATE_NODES = MAX_GATE_LEAVES * 2;
+function checkGateBounds(raw, ctx) {
+    const stack = [{ node: raw, depth: 1 }];
+    let nodes = 0;
+    while (stack.length > 0) {
+        const { node, depth } = stack.pop();
+        if (depth > MAX_GATE_DEPTH) {
+            ctx.addIssue({ code: "custom", message: `gate tree is more than ${MAX_GATE_DEPTH} levels deep` });
+            return;
+        }
+        nodes += 1;
+        if (nodes > MAX_GATE_NODES) {
+            ctx.addIssue({ code: "custom", message: `gate tree has more than ${MAX_GATE_NODES} nodes` });
+            return;
+        }
+        if (typeof node !== "object" || node === null)
+            continue; // not a node; the schema says so
+        const branch = node;
+        const children = Array.isArray(branch.all) ? branch.all : branch.any;
+        if (!Array.isArray(children))
+            continue;
+        for (const child of children)
+            stack.push({ node: child, depth: depth + 1 });
+    }
+}
+export const GateSchema = z
+    .unknown()
+    .superRefine(checkGateBounds)
+    .pipe(GateNodeSchema)
+    .superRefine((node, ctx) => {
+    const { depth, leaves, redundant } = gateShape(node);
+    if (depth > MAX_GATE_DEPTH) {
+        ctx.addIssue({ code: "custom", message: `gate tree is ${depth} levels deep; the maximum is ${MAX_GATE_DEPTH}` });
+    }
+    if (leaves > MAX_GATE_LEAVES) {
+        ctx.addIssue({ code: "custom", message: `gate tree names ${leaves} rules; the maximum is ${MAX_GATE_LEAVES}` });
+    }
+    // Every redundant spelling is a topic fork waiting to happen: it means the same thing as a
+    // shorter tree while encoding to different bytes, so two authors expressing one contest can
+    // land on two topics. Same reason a branch may not have a single child.
+    if (redundant !== undefined)
+        ctx.addIssue({ code: "custom", message: `gate tree has a redundant spelling: ${redundant}` });
 });
 /**
  * The dependency manifest. A client reads this on join and checks that it
  * implements every named rule; if not, it is too old and must recuse
  * itself rather than miscount. This is how criteria upgrades fork cleanly.
+ *
+ * Strict for the same reason the top level is: the topic is derived from the PARSED document, so
+ * an unknown key must fail loudly rather than be stripped — a stripping schema would drop it and
+ * derive a different topic from the one the author's bytes imply. That is what makes a document
+ * still carrying the pre-`bucketChainId` `chains` map (or the even older `rpcUrls`) an error
+ * instead of a silent re-topic.
  */
-export const RequiresSchema = z.object({
-    rules: z.array(z.string().min(1)).nonempty(),
-    chains: z.record(ChainTickerSchema, ChainConfigSchema)
+export const RequiresSchema = z.strictObject({
+    rules: z.array(z.string().min(1)).nonempty()
 });
 export const CriteriaSchema = z
     .object({
@@ -76,12 +151,37 @@ export const CriteriaSchema = z
      * always allowed as withdrawal/abstention regardless of this cap.
      */
     maxVotesPerAddress: z.number().int().positive(),
+    /**
+     * The chain whose blocks this contest counts in, by numeric chain id.
+     *
+     * The contest has exactly ONE clock, and this names it: `blocksPerBucket` and
+     * `voteExpiryBuckets` are measured in its blocks, a ballot's `blockNumber` and the
+     * `sampleBlock` every rule is handed are numbers on it, the tie-break seed is the hash of
+     * its bucket boundary block, and its id is bound into every EIP-712 ballot domain.
+     *
+     * It is a chain ID rather than a ticker because that is the identity the signature domain
+     * already carries — a ticker is a label local to a document, and two documents spelling
+     * one chain differently would be two topics for one contest. Rules do not name a chain at
+     * all: they read this one. Gating across several chains is future work, and needs an
+     * answer for what block a rule on a SECOND chain is handed before it can ship — see
+     * DESIGN.md "Open questions".
+     *
+     * RPC endpoints are deliberately not part of the criteria: which gateway a client trusts
+     * is client-local configuration (`PubsubVoterOptions.chains` maps this id to a client),
+     * and two honest verifiers reading the same pinned block through different gateways
+     * compute identical results. That keeps an operator's dead-RPC swap from forking the
+     * topic and orphaning the contest's votes.
+     */
+    bucketChainId: z.number().int().positive(),
     /** Block bucket size; all verifiers price the same block per bucket. */
     blocksPerBucket: z.number().int().positive(),
     /** How many buckets a bundle stays valid after its blockNumber. */
     voteExpiryBuckets: z.number().int().positive(),
-    /** Who may vote (gates a wallet in or out). */
-    rule: RuleRefSchema,
+    /**
+     * Who may vote (gates a wallet in or out): one rule, or a boolean tree of them.
+     * A single-rule gate is spelled `{ rule: { type, ... } }` — see {@link GateSchema}.
+     */
+    gate: GateSchema,
     /** How much an eligible vote counts. */
     weight: RuleRefSchema,
     /** Dependency manifest + version negotiation. */

package/dist/signer/eip712.d.ts

@@ -17,7 +17,7 @@ import type { Vote } from "../schema/votes.js";
  *   - `votes`: each community (`{ name, publicKey }`) + numeric vote.
  *   - `blockNumber`: the LWW key and the bucketized block every verifier reads at.
  *
- * The `domain.chainId` is the gating (`rule`) chain, giving cross-chain/cross-app domain
+ * The `domain.chainId` is the contest's `bucketChainId`, giving cross-chain/cross-app domain
  * separation for free. This module is pure: no key material, no network, no viem import
  * — it only shapes the object both sides feed to viem.
  */
@@ -96,7 +96,7 @@ export interface BallotTypedData {
 export declare function ballotTypedData(args: {
     /** The criteria CID's raw binary bytes (`(await criteriaCid(criteria)).bytes`). */
     criteriaCid: Uint8Array;
-    /** The gating (`rule`) chain's numeric chainId (`criteria.requires.chains[chain].chainId`). */
+    /** The chain the contest counts in (`criteria.bucketChainId`). */
     chainId: number;
     votes: Vote[];
     blockNumber: number;

package/dist/signer/eip712.js

@@ -16,7 +16,7 @@
  *   - `votes`: each community (`{ name, publicKey }`) + numeric vote.
  *   - `blockNumber`: the LWW key and the bucketized block every verifier reads at.
  *
- * The `domain.chainId` is the gating (`rule`) chain, giving cross-chain/cross-app domain
+ * The `domain.chainId` is the contest's `bucketChainId`, giving cross-chain/cross-app domain
  * separation for free. This module is pure: no key material, no network, no viem import
  * — it only shapes the object both sides feed to viem.
  */

package/dist/tally/tally.d.ts

@@ -25,7 +25,8 @@ import type { Tally } from "./types.js";
 export interface TallyDeps {
     criteria: Criteria;
     registry: RuleRegistry;
-    chainFor: (ticker: string) => ChainClient;
+    /** The contest's one chain client — the weight rule reads it too (DESIGN.md "One clock"). */
+    chain: ChainClient;
     bucketMath: BucketMath;
     /**
      * The CRDT's current bundles (one per wallet, LWW-resolved; empty-votes bundles are

package/dist/tally/tally.js

@@ -1,6 +1,5 @@
 import { base58btc } from "multiformats/bases/base58";
 import { sha256 } from "multiformats/hashes/sha2";
-import { tickerForRef } from "../chain/ticker.js";
 import { makeMemoryRuleCache } from "../rules/cache.js";
 import { scoreOrZero } from "../rules/result.js";
 import { UnknownRuleError } from "../errors.js";
@@ -16,24 +15,21 @@ function compareBytes(x, y) {
     return x.length - y.length;
 }
 export function makeTally(deps) {
-    const { criteria, registry, chainFor, bucketMath, current, bucketBlockHash } = deps;
-    const readHead = deps.readHead ?? (async ({ chain }) => ({ block: Number(await chain.getBlockNumber()) }));
-    // Resolve the weight rule, its options, and its chain once (see verify/bundle.ts).
+    const { criteria, registry, chain, bucketMath, current, bucketBlockHash } = deps;
+    const readHead = deps.readHead ?? (async ({ chain: client }) => ({ block: Number(await client.getBlockNumber()) }));
+    // Resolve the weight rule and its options once (see verify/bundle.ts).
     const weight = registry[criteria.weight.type];
     if (!weight)
         throw new UnknownRuleError("weight", criteria.weight.type);
     const weightOptions = weight.optionsSchema.parse(criteria.weight);
-    const weightChain = chainFor(tickerForRef(criteria, criteria.weight, weightOptions));
-    // The weight rule picks its own block exactly as the gate rule does (see rules/types.ts):
-    // it is handed the bundle's pinned sample block and this verifier's head, and reads whichever
-    // it needs. The tally never asks what kind of rule it is holding.
-    //
-    // `deps.ruleCache` MUST be namespaced by the weight rule's OWN chain, not the gating chain —
-    // `weightChain` here resolves through `criteria.weight`'s ticker, which may name a different
-    // entry of `requires.chains` (the voter derives it that way; see client/voter.ts).
+    // The weight rule picks its own block exactly as a gate rule does (see rules/types.ts): it is
+    // handed the bundle's pinned sample block and this verifier's head, and reads whichever it
+    // needs. The tally never asks what kind of rule it is holding. It reads the contest's one
+    // chain — a weight rule on a second chain is the same open question as a gate leaf on one
+    // (DESIGN.md "Open questions").
     const weightCtx = {
-        chain: weightChain,
-        head: () => readHead({ chain: weightChain }),
+        chain,
+        head: () => readHead({ chain }),
         cache: deps.ruleCache ?? makeMemoryRuleCache()
     };
     const weightFor = async (wallet, blockNumber) => {

package/dist/tally/types.d.ts

@@ -25,7 +25,7 @@ export interface CommunityTally {
     /** Summed weight of upvotes counted so far, in rule score units (`bigint`). */
     weight: bigint;
     /**
-     * True once every bundle contributing to this row has had its gate `rule` confirmed `> 0n`
+     * True once every bundle contributing to this row has had its gate confirmed
      * by an on-chain read at its bucket block. `false` means at least one contribution is still
      * awaiting its background gate read — never that one failed (a failed gate evicts the
      * bundle and recounts the row).

package/dist/transport/integration/harness.js

@@ -37,7 +37,7 @@ const CURRENT_BUCKET = 0;
 const BLOCKS_PER_BUCKET = 43_200;
 const VOTE_EXPIRY_BUCKETS = 30;
 /** A permissive default verifier; individual tests swap it via {@link VoteNode.setVerifier}. */
-const okVerifier = () => ({ valid: true, ruleScore: 1n, resolvedNames: {} });
+const okVerifier = () => ({ valid: true, resolvedNames: {} });
 /**
  * One real loopback libp2p + Helia node carrying gossipsub (topic-scoped score params) and
  * `@libp2p/fetch` — the raw host node with nothing else wired. {@link makeVoteNode} builds the
@@ -118,8 +118,8 @@ export async function makeVoteNode(topic, options = {}) {
         verify: (bundle) => verifyImpl(bundle),
         verifyOffline: (bundle) => verifyImpl(bundle),
         // These harness nodes drive the transport, not the eligibility surface; nothing here
-        // calls checkGate, so it admits rather than pretending to model a gate.
-        checkGate: async () => ({ success: true, score: 1n })
+        // calls checkGates, so it admits rather than pretending to model a gate.
+        checkGates: async () => ({ kind: "leaf", leaf: 0, satisfied: true, score: 1n, penalize: false })
     };
     const admit = async ({ cid, bytes }) => {
         await blockstore.put(cid, bytes);

package/dist/verify/background.d.ts

@@ -3,7 +3,7 @@ import type { VotesBundle } from "../schema/votes.js";
 import type { Criteria } from "../schema/criteria.js";
 import type { RuleRegistry } from "../rules/types.js";
 import type { ChainClient, BucketMath, NameResolver } from "../chain/types.js";
-import { type RuleCache } from "../rules/cache.js";
+import type { RuleCache } from "../rules/cache.js";
 import { type NameResolutionCache } from "./name-resolution-cache.js";
 import type { VerdictCache } from "./cache.js";
 import type { VerifyFail } from "./types.js";
@@ -52,18 +52,20 @@ export interface PendingBundle {
 export interface BackgroundVerifierDeps {
     criteria: Criteria;
     registry: RuleRegistry;
-    chainFor: (ticker: string) => ChainClient;
+    /** The contest's one chain client — every rule reads it (DESIGN.md "One clock"). */
+    chain: ChainClient;
     bucketMath: BucketMath;
     nameResolvers: NameResolver[];
     /**
-     * The gate rule's memo, handed to it as `ctx.cache` (rules/cache.ts). Shared with the inline
-     * forward-gate verifier, so neither re-reads what the other settled.
+     * One memo per gate leaf, in `gateLeaves` order, handed to each rule as `ctx.cache`
+     * (rules/cache.ts). Shared with the inline forward-gate verifier, so neither re-reads what
+     * the other settled.
      */
-    ruleCache?: RuleCache;
+    ruleCaches?: readonly RuleCache[];
     /**
      * This verifier's current head, handed to the rule as `ctx.head`. Resolved by the rule at
      * most once per batch, so a round stays batchable. Never called by a rule that scores pinned
-     * historical state. Defaults to the rule chain's own `getBlockNumber()`; the voter injects
+     * historical state. Defaults to the contest chain's own `getBlockNumber()`; the voter injects
      * its coalesced reader.
      */
     readHead?: (args: {

package/dist/verify/background.js

@@ -1,31 +1,20 @@
-import { tickerForRef } from "../chain/ticker.js";
-import { makeMemoryRuleCache } from "../rules/cache.js";
 import { GATE_GRACE_MS, GATE_RETRY_MS } from "./gate-grace.js";
-import { gateFailure, scoreOrZero } from "../rules/result.js";
-import { UnknownRuleError } from "../errors.js";
+import { dedupeLeaves, evaluateGate, gateBlame, gatePenalize, gateReason, resolveGate } from "../rules/gate.js";
 import { resolveNameThroughCache } from "./name-resolution-cache.js";
 const RETRY_BASE_MS = 2_000;
 const RETRY_CAP_MS = 60_000;
 export function makeBackgroundVerifier(deps) {
-    const { criteria, registry, chainFor, bucketMath, nameResolvers, nameResolutionCache, cache, limit } = deps;
+    const { criteria, registry, chain, bucketMath, nameResolvers, nameResolutionCache, cache, limit } = deps;
     const retryBaseMs = deps.retryBaseMs ?? RETRY_BASE_MS;
     const retryCapMs = deps.retryCapMs ?? RETRY_CAP_MS;
     const gateGraceMs = deps.gateGraceMs ?? GATE_GRACE_MS;
     const gateRetryMs = deps.gateRetryMs ?? GATE_RETRY_MS;
-    // Resolve the gate `rule`, its options, and its chain once (same shape as verify/bundle.ts).
-    // The re-binding after the guard keeps the non-undefined narrowing inside the closures below.
-    const maybeRule = registry[criteria.rule.type];
-    if (!maybeRule)
-        throw new UnknownRuleError("rule", criteria.rule.type);
-    const rule = maybeRule;
-    const ruleOptions = rule.optionsSchema.parse(criteria.rule);
-    const ruleChain = chainFor(tickerForRef(criteria, criteria.rule, ruleOptions));
-    const readHead = deps.readHead ?? (async ({ chain }) => ({ block: Number(await chain.getBlockNumber()) }));
-    const ctx = {
-        chain: ruleChain,
-        head: () => readHead({ chain: ruleChain }),
-        cache: deps.ruleCache ?? makeMemoryRuleCache()
-    };
+    // Resolve every gate leaf — rule, options, chain, memo — once (same call as verify/bundle.ts,
+    // so the two verifiers cannot resolve a gate differently).
+    const readHead = deps.readHead ?? (async ({ chain: client }) => ({ block: Number(await client.getBlockNumber()) }));
+    const leaves = resolveGate({ criteria, registry, chain, readHead, caches: deps.ruleCaches });
+    // Which leaves ask the same question: a rule named twice in one gate is batched once.
+    const { representatives, ofLeaf } = dedupeLeaves(leaves);
     const queue = [];
     /** CIDs queued or in-flight, so a re-chased root cannot double-verify a bundle. */
     const inFlight = new Set();
@@ -49,15 +38,22 @@ export function makeBackgroundVerifier(deps) {
         return bucketMath.sampleBlockForBucket(bucketMath.bucketForBlock(bundle.blockNumber));
     }
     /**
-     * Gate stage for one round's batch: hand every not-yet-gated wallet to the rule at once —
-     * `evaluateMany` when it has one, `limit`-bounded per-wallet `evaluate` otherwise — and
-     * record each score with the rule's own verdict on whether a `0n` is attributable.
+     * Gate stage for one round's batch: hand every not-yet-gated wallet to EACH gate leaf at once
+     * — `evaluateMany` when the rule has one, `limit`-bounded per-wallet `evaluate` otherwise —
+     * then fold each item's leaf answers into its verdict.
+     *
+     * Note this deliberately does NOT short-circuit the tree the way the inline gate does. Here
+     * the axis of batching is the rule, not the wallet: one `evaluateMany` per leaf covers the
+     * whole round, so scoring every leaf costs one round trip per leaf no matter how many wallets
+     * are pending, while short-circuiting per wallet would fragment those batches into
+     * per-wallet reads. Collecting all is the cheaper shape on this path, and it is also what
+     * gives every item a complete blame set.
      *
-     * No grouping and no cache lookups here any more: which block each wallet is read at, and
-     * what may be memoized under which key, are the rule's decisions (rules/types.ts,
-     * rules/cache.ts). Duplicate wallets are still collapsed before the call, because that is a
-     * property of THIS batch rather than of any rule. Throws on the FIRST infra failure: the
-     * round's unfinished items are re-queued by the caller.
+     * No grouping and no cache lookups here: which block each wallet is read at, and what may be
+     * memoized under which key, are the rule's decisions (rules/types.ts, rules/cache.ts).
+     * Duplicate wallets are still collapsed before the calls, because that is a property of THIS
+     * batch rather than of any rule. Throws on the FIRST infra failure: the round's unfinished
+     * items are re-queued by the caller.
      */
     async function gateStage(items) {
         const pending = items.filter((item) => !item.gateDone);
@@ -73,14 +69,24 @@ export function makeBackgroundVerifier(deps) {
             at.set(key, wallets.length);
             wallets.push(wallet);
         }
-        const results = rule.evaluateMany
-            ? (await rule.evaluateMany({ options: ruleOptions, wallets, ctx })).results
-            : await Promise.all(wallets.map((wallet) => limit(() => rule.evaluate({ options: ruleOptions, wallet, ctx }))));
+        // One batched call per distinct QUESTION, those in parallel: each is a single multicall
+        // for the whole round, and the voter's per-client in-flight budget still bounds what
+        // reaches an RPC. A rule named twice in one gate ("any two of these three") is asked once
+        // and its answer fanned back out to both positions.
+        const byQuestion = await Promise.all(representatives.map((leaf) => {
+            const { rule, options, ctx } = leaves[leaf];
+            return rule.evaluateMany
+                ? rule.evaluateMany({ options, wallets, ctx }).then(({ results }) => results)
+                : Promise.all(wallets.map((wallet) => limit(() => rule.evaluate({ options, wallet, ctx }))));
+        }));
         for (const item of pending) {
-            const key = `${item.bundle.address.toLowerCase()}:${sampleBlockFor(item.bundle)}`;
-            const result = results[at.get(key)];
-            item.gateFailed = gateFailure(result);
-            item.ruleScore = scoreOrZero(result);
+            const wallet = at.get(`${item.bundle.address.toLowerCase()}:${sampleBlockFor(item.bundle)}`);
+            // Every leaf is already scored, so this "evaluation" reads the batch — no chain work.
+            item.gate = await evaluateGate({
+                node: criteria.gate,
+                evaluate: async (leaf) => byQuestion[ofLeaf[leaf]][wallet],
+                collectAll: true
+            });
             item.gateDone = true;
         }
     }
@@ -144,20 +150,29 @@ export function makeBackgroundVerifier(deps) {
                 requeue.push(item); // gate read never happened (infra) — retry the whole item
                 continue;
             }
-            if (item.gateFailed) {
-                if (item.gateFailed.penalize) {
+            if (item.gate !== undefined && item.gate.satisfied !== true) {
+                // The rules' own wording, narrowed to the failures that explain the refusal, plus
+                // the recursive answer to "may this be blamed on the sender" (rules/gate.ts).
+                const failures = gateBlame(item.gate).map((leaf) => ({
+                    type: leaves[leaf.leaf].ref.type,
+                    error: leaf.error ?? ""
+                }));
+                const reason = gateReason(item.gate);
+                if (gatePenalize(item.gate)) {
                     // Provable, deterministic reject — safe to cache so a re-publish short-circuits.
                     const verdict = {
                         valid: false,
                         disposition: "reject",
-                        reason: `not admitted: ${item.gateFailed.error}`
+                        reason: `not admitted: ${reason}`,
+                        failures
                     };
                     cache.set(item.cid, verdict);
                     deps.onEvict(item.cid, verdict);
                     settle(item);
                     continue;
                 }
-                // The rule declined to blame anyone (see rules/types.ts, RuleResult.penalize):
+                // No failure the gate will blame anyone for (see rules/types.ts, RuleResult.penalize,
+                // and rules/gate.ts for how that folds through `all`/`any`):
                 // the failure means "not yet", not "no". The wallet may have acquired the asset in
                 // a block this verifier has not seen, or may acquire it a moment from now — a
                 // client that signs the instant it mints races its own transaction. Evicting here
@@ -174,7 +189,8 @@ export function makeBackgroundVerifier(deps) {
                 const verdict = {
                     valid: false,
                     disposition: "ignore",
-                    reason: `not admitted: ${item.gateFailed.error} (still true after the grace window)`
+                    reason: `not admitted: ${reason} (still true after the grace window)`,
+                    failures
                 };
                 deps.onEvict(item.cid, verdict);
                 settle(item);
@@ -198,7 +214,7 @@ export function makeBackgroundVerifier(deps) {
             if (item.bundle.votes.some((v) => v.community.name))
                 deps.onNameResolved(item.cid);
             // Fully settled: store the terminal valid verdict (same shape the forward-gate caches).
-            cache.set(item.cid, { valid: true, ruleScore: item.ruleScore, resolvedNames: item.resolvedNames });
+            cache.set(item.cid, { valid: true, resolvedNames: item.resolvedNames });
             settle(item);
         }
         if (requeue.length > 0) {
@@ -260,8 +276,7 @@ export function makeBackgroundVerifier(deps) {
                     ...entry,
                     gateDone: false,
                     gateNotified: false,
-                    ruleScore: 0n,
-                    gateFailed: undefined,
+                    gate: undefined,
                     resolvedNames: {},
                     queuedAt: Date.now()
                 });