@bitsocial/pubsub-voting 0.4.0 → 0.5.0

package/dist/schema/common.js

@@ -5,14 +5,14 @@ import { z } from "zod";
  * There is no pkc-js author in this library: a vote is signed directly by the
  * gating-chain wallet that holds the Pass/ERC-20 (see DESIGN.md "Identity: the
  * voting wallet, nothing else"). What survives from the old author/wallet schema is
- * two small, identity-agnostic primitives reused across the wire:
- *   - `ChainTickerSchema`: the chain identifier ("base", "eth", ...) used by criteria
- *     and chain-reading rules.
+ * one small, identity-agnostic primitive reused across the wire:
  *   - `SignatureSchema`: the detached `{ signature, type }` shape (kept from pkc-js),
  *     here carrying the wallet's EIP-712 ballot signature.
+ *
+ * Chains are named by numeric `chainId` (`criteria.bucketChainId`), never by ticker: a ticker is
+ * a label local to a document, and two documents spelling one chain differently would be two
+ * topics for one contest.
  */
-/** Chain ticker is unrestricted ("base", "eth", ...), matching pkc-js. */
-export const ChainTickerSchema = z.string().min(1);
 /**
  * A detached signature with an explicit scheme tag. For a Votes bundle the `type` is
  * the EIP-712 scheme ({@link EIP712_SIGNATURE_TYPE}) and `signature` is the hex

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: {