@bitsocial/pubsub-voting 0.2.1 → 0.4.0

package/dist/rules/nft-balance.js

@@ -28,27 +28,42 @@ const CHUNK_RETRY_DELAY_MS = CHAIN_CHUNK_RETRY_DELAY_MS;
 export function scoreOf(balance, min) {
     return balance >= BigInt(min) ? balance : 0n;
 }
+/**
+ * The voter-facing wording for a token-count shortfall ({@link RuleResult.error}), shared by
+ * every balance-scored rule so they explain themselves identically.
+ *
+ * Deliberately generic: a rule knows a contract address and a threshold, not that the deployment
+ * calls this token a "5chan Pass". A client renders it verbatim, which is the point — it then
+ * needs to know nothing about which block the rule read or what `min` is.
+ */
+export function shortfallError(balance, min, contract) {
+    return balance === 0n
+        ? `this wallet holds none of the gate token (${contract})`
+        : `this wallet holds ${balance} of the gate token (${contract}), but ${min} are required`;
+}
 /**
  * True when the client can run multicall3 `aggregate3` batches — it needs both the action and
  * its chain's multicall3 deployment. A client built without a `chain` (or on a chain without
  * multicall3) takes the per-wallet path instead.
  */
-export function canBatch(ctx) {
-    return typeof ctx.chain.multicall === "function" && Boolean(ctx.chain.chain?.contracts?.multicall3);
+export function canBatch(args) {
+    const { ctx } = args;
+    return { batchable: typeof ctx.chain.multicall === "function" && Boolean(ctx.chain.chain?.contracts?.multicall3) };
 }
-/** One wallet's `balanceOf` at the bundle's sampled block. */
-export function balanceOf(contract, walletAddress, ctx) {
-    return ctx.chain.readContract({
-        address: contract,
+/** One wallet's `balanceOf` at `block` (the caller's choice — a pinned block or the head). */
+export async function balanceOf(args) {
+    const balance = await args.ctx.chain.readContract({
+        address: args.contract,
         abi: erc721Abi,
         functionName: "balanceOf",
-        args: [getAddress(walletAddress)],
-        blockNumber: BigInt(ctx.blockNumber)
+        args: [getAddress(args.wallet)],
+        blockNumber: BigInt(args.block)
     });
+    return { balance };
 }
 /**
- * Many wallets' `balanceOf` at ONE sampled block — the path the background chain verifier rides
- * on a cold join. Requires {@link canBatch}; callers fall back to mapping {@link balanceOf}.
+ * Many wallets' `balanceOf` at ONE block — the path the background chain verifier rides on a
+ * cold join. Requires {@link canBatch}; callers fall back to mapping {@link balanceOf}.
  *
  * The wallets are chunked HERE (`READS_PER_MULTICALL` per aggregate3, `batchSize: 0` disables
  * viem's own 1KB re-chunking) and the chunks are sent with bounded concurrency plus one retry
@@ -57,7 +72,8 @@ export function balanceOf(contract, walletAddress, ctx) {
  * completed one (viem's own whole-batch retry re-fired the entire burst). A chunk that fails
  * twice still fails the whole call: the caller gets one rejection, not partial results.
  */
-export async function balancesOfBatched(contract, walletAddresses, ctx) {
+export async function balancesOfBatched(args) {
+    const { contract, wallets: walletAddresses, block, ctx } = args;
     const chunks = [];
     for (let at = 0; at < walletAddresses.length; at += READS_PER_MULTICALL) {
         chunks.push(walletAddresses.slice(at, at + READS_PER_MULTICALL));
@@ -72,7 +88,7 @@ export async function balancesOfBatched(contract, walletAddresses, ctx) {
         })),
         allowFailure: false,
         batchSize: 0,
-        blockNumber: BigInt(ctx.blockNumber)
+        blockNumber: BigInt(block)
     });
     let nextChunk = 0;
     const worker = async () => {
@@ -93,5 +109,5 @@ export async function balancesOfBatched(contract, walletAddresses, ctx) {
         }
     };
     await Promise.all(Array.from({ length: Math.min(MULTICALL_CONCURRENCY, chunks.length) }, worker));
-    return balances;
+    return { balances };
 }

package/dist/rules/result.d.ts

@@ -0,0 +1,16 @@
+import type { RuleResult } from "./types.js";
+/**
+ * `undefined` when the wallet is admitted, else why it was not and whether the sender may be
+ * blamed for it.
+ *
+ * `penalize` is normalised here (defaulting to `true`) so callers never repeat the
+ * `!== false` dance, and a `success: true, score: 0n` — impossible per the contract, but not
+ * expressible in the type — is treated as a failure rather than silently admitting a
+ * zero-weight vote.
+ */
+export declare function gateFailure(result: RuleResult): {
+    error: string;
+    penalize: boolean;
+} | undefined;
+/** The weight slot's reading: a failure contributes nothing rather than dropping the vote. */
+export declare function scoreOrZero(result: RuleResult): bigint;

package/dist/rules/result.js

@@ -0,0 +1,30 @@
+/**
+ * The two things the pipeline does with a {@link RuleResult}, in one place so the gate path and
+ * the background verifier cannot drift apart.
+ *
+ * Neither helper looks at which rule produced the result — that is the standing rule of this
+ * codebase (AGENTS.md, "What a rule owns, and what the pipeline owns"). They read the discriminant
+ * and nothing else.
+ */
+/** A rule that says `success: true` but scores nothing has a bug; refuse rather than admit. */
+const NON_POSITIVE_SUCCESS = "the contest's rule reported success without a score, which is a bug in that rule";
+/**
+ * `undefined` when the wallet is admitted, else why it was not and whether the sender may be
+ * blamed for it.
+ *
+ * `penalize` is normalised here (defaulting to `true`) so callers never repeat the
+ * `!== false` dance, and a `success: true, score: 0n` — impossible per the contract, but not
+ * expressible in the type — is treated as a failure rather than silently admitting a
+ * zero-weight vote.
+ */
+export function gateFailure(result) {
+    if (!result.success)
+        return { error: result.error, penalize: result.penalize !== false };
+    if (result.score <= 0n)
+        return { error: NON_POSITIVE_SUCCESS, penalize: true };
+    return undefined;
+}
+/** The weight slot's reading: a failure contributes nothing rather than dropping the vote. */
+export function scoreOrZero(result) {
+    return result.success && result.score > 0n ? result.score : 0n;
+}

package/dist/rules/types.d.ts

@@ -1,70 +1,166 @@
 import type { z } from "zod";
 import type { ChainClient } from "../chain/types.js";
+import type { RuleCache } from "./cache.js";
 /**
  * Rule interface, design + leaves implemented.
  *
  * A rule turns a criteria `{ type, ...options }` reference into a non-negative
- * score for one wallet, evaluated at the bundle's bucket block. There is a SINGLE kind
+ * score for one wallet, at whichever block the rule itself decides to read — the pinned block
+ * the bundle names ({@link RuleWallet.sampleBlock}) or this verifier's current head
+ * ({@link ChainReadContext.head}). There is a SINGLE kind
  * (mirroring the flat pkc-js challenge registry: `Record<string, rule>`, user
  * entries shadow builtins). The criteria still has two slots that draw from this one
  * registry:
  *
- *   - rule slot:   the score is a GATE. `> 0n` admits the wallet, `0n` rejects it.
- *   - weight slot: the score is the vote's MAGNITUDE.
+ *   - rule slot:   the result is a GATE. `success: true` admits the wallet, `success: false`
+ *                  rejects it and must say why ({@link RuleResult.error}).
+ *   - weight slot: a successful result's `score` is the vote's MAGNITUDE; a failure is zero
+ *                  weight.
  *
- * Final vote value = `evaluate(rule).score === 0n ? 0n : evaluate(weight).score`.
- *
- * A single numeric return covers both roles: a rule that needs a threshold
- * (min Passes, min balance) bakes it in by returning 0n when the wallet falls short.
- * That is why the gate slot does not need a separate boolean kind.
+ * One return shape covers both roles: a rule that needs a threshold (min Passes, min balance)
+ * bakes it in by failing when the wallet falls short, so the gate slot needs no separate kind.
  */
 /**
- * The result of one evaluation. `score` is a non-negative `bigint`; `0n` means "does not
- * qualify" (rejected in the rule slot, no weight in the weight slot). It is an
- * object, not a bare `bigint`, so slot-specific fields can be added without changing the
- * signature again — e.g. a self-declared `ceiling` for balance-derived weight, which the
- * lazy tally needs as a wire-side upper bound (see DESIGN.md "Open questions").
+ * The result of one evaluation: a wallet either qualifies with a score, or it does not and the
+ * rule says why.
+ *
+ * Modelled on pkc-js's `ChallengeResult` (community/schema.ts) — a `success` discriminant, with
+ * `error` REQUIRED on the failing branch. Making it required is the whole point: only the rule
+ * knows why a wallet fell short, and if that reason is optional it will simply be omitted, which
+ * leaves the pipeline with one undifferentiated "score is 0n" and forces every UI to re-derive
+ * the rule's thresholds and block choice to say anything useful. That duplication is exactly what
+ * {@link ChainReadContext} and {@link RuleCache} exist to prevent everywhere else, and it is what
+ * broke when the gate moved from a pinned block to the head: a client's hand-rolled explanation
+ * kept telling voters to wait for a window that no longer gated anything.
+ *
+ *   - rule slot:   `success: true` admits the wallet; `success: false` rejects it.
+ *   - weight slot: `success: true` carries the vote's MAGNITUDE; `success: false` is zero weight.
+ *
+ * Final vote value = gate `success: false` ? `0n` : weight `success` ? weight `score` : `0n`.
+ *
+ * `score` MUST be `> 0n` on the success branch — "qualifies, with no weight" is not a state this
+ * models, and the pipeline treats a non-positive success score as a rule bug and refuses the
+ * wallet rather than silently admitting a zero-weight vote.
  */
-export interface RuleResult {
+export type RuleResult = {
+    success: true;
+    /** The wallet's magnitude. MUST be `> 0n`. */
     score: bigint;
-}
-/** Everything a rule needs to read chain state for one evaluation. */
+} | {
+    success: false;
+    /**
+     * Why this wallet does not qualify, phrased for the person who cast (or is about to
+     * cast) the vote. Surfaces on `VerifyFail.reason`, on `VoteEvictedError.verdict`, and
+     * from `Contest.checkEligibility`, so a client renders it verbatim and stays correct
+     * across rule changes it knows nothing about.
+     *
+     * Write it as a statement about the wallet, not about the library: "this wallet holds
+     * none of the gate token", not "gate rule returned 0". Do not cite block numbers unless
+     * they are actionable — a voter can do nothing with a sample block.
+     */
+    error: string;
+    /**
+     * May this failure be blamed on the peer that sent the vote? Default `true`.
+     *
+     * The pipeline has two decisions the rule cannot make for it — whether the gossip
+     * forward-gate `reject`s the message (penalizing the delivering peer through
+     * gossipsub's invalid-message score, eventually pruning and graylisting it) or merely
+     * `ignore`s it, and whether the background verifier evicts the bundle at once or holds
+     * it for a grace window. Both hinge on one thing only the rule knows: is this failure
+     * attributable?
+     *
+     * `true` (the default) says every honest verifier necessarily computes this same
+     * failure — true of a read pinned to a historical block, since the block is named by
+     * the bundle and the chain's history does not move. The bundle is dropped, the sender
+     * penalized, the verdict cached as terminal.
+     *
+     * `false` says an honest peer could legitimately disagree, so nobody may be blamed. The
+     * bundle is still dropped, but `ignore`-class — no penalty, verdict uncached, and the
+     * background verifier re-examines it for a grace window before giving up. This is what
+     * a rule scoring the chain head must return: the peer that forwarded the vote verified
+     * it against ITS head, and any peer ahead of us can legitimately see an acquisition we
+     * have not. Penalizing there punishes honest relayers for being current — and does so
+     * exactly when a wallet has just acquired the gate asset, which is when peer heads
+     * straddle.
+     */
+    penalize?: boolean;
+};
+/** Everything a rule needs to read chain state and remember what it read. */
 export interface ChainReadContext {
     /**
-     * The viem `PublicClient` for the rule's `options.chain`. Use the full viem
-     * read surface directly (`readContract`, `getBalance`, ...), pinning every call to
-     * the sampled block with `blockNumber: BigInt(ctx.blockNumber)`.
+     * The viem `PublicClient` for the rule's `options.chain`. Use the full viem read surface
+     * directly (`readContract`, `getBalance`, ...). ALWAYS pin each call to an explicit
+     * `blockNumber: BigInt(...)`: the read coalescer (src/chain/coalescer.ts) only folds reads
+     * carrying an explicit block into one multicall3, so a `blockTag` or an omitted block
+     * silently drops out of batching and back to one HTTP round trip per read.
      */
     chain: ChainClient;
-    /** The single sampled block for the bundle's bucket. */
-    blockNumber: number;
+    /**
+     * This verifier's current head on {@link chain}. A rule scoring historical state never calls
+     * it and never pays for it; a rule scoring "now" resolves it ONCE per evaluation and pins
+     * its reads to that number, so a batch still lands in a single multicall.
+     *
+     * Shared and coalesced by the voter, because the gate runs on the verify path — one call per
+     * incoming vote — so an unshared head read would be one `eth_blockNumber` per bundle per
+     * contest.
+     */
+    head: () => Promise<{
+        block: number;
+    }>;
+    /**
+     * This rule's memo (see rules/cache.ts). A chain-reading rule MUST compute through it: it is
+     * what turns "one chain read per unique bundle" into "one read per key per epoch", which is
+     * the bound that stops an ineligible wallet from making every peer on the topic pay an RPC
+     * round trip per fresh-signed bundle.
+     */
+    cache: RuleCache;
+}
+/** One wallet to score, and the pinned block the bundle it came from names. */
+export interface RuleWallet {
+    /** The voting wallet (the address recovered from the bundle's signature). */
+    address: string;
+    /**
+     * The bundle's bucketized sample block, already floored to the bucket boundary — the
+     * historical block every verifier agrees this ballot names. A rule scoring pinned state
+     * reads here (and its answer is then identical on every verifier, forever); a rule scoring
+     * current state ignores it and uses {@link ChainReadContext.head} instead. It is NOT a
+     * claim about when the ballot was signed: it is floored to the bucket, so it can trail the
+     * actual signing moment by up to `blocksPerBucket`.
+     */
+    sampleBlock: number;
 }
 /**
  * The one rule kind. `O` is the validated options type (from its `optionsSchema`).
- * `evaluate` returns a `RuleResult` whose `score` is a non-negative `bigint`; `0n`
- * means "does not qualify" (rejected in the rule slot, no weight in the weight slot).
+ * `evaluate` returns a {@link RuleResult}: either `{ success: true, score }` with `score > 0n`,
+ * or `{ success: false, error }` — "does not qualify", with the reason the voter is shown.
  */
 export interface Rule<O = unknown> {
     readonly type: string;
     readonly optionsSchema: z.ZodType<O>;
     evaluate(args: {
         options: O;
-        walletAddress: string;
+        wallet: RuleWallet;
         ctx: ChainReadContext;
     }): Promise<RuleResult>;
     /**
-     * Optional batched form of {@link evaluate}: score many wallets at the SAME sampled block in
-     * as few RPC round trips as the rule can manage (e.g. one multicall3 `aggregate3` for a whole
-     * checkpoint's wallets). Returns one result per input wallet, in order. Semantics MUST equal
-     * mapping `evaluate` over the wallets — this is a transport optimization, never a different
-     * answer. The background chain verifier prefers it when present and falls back to per-wallet
-     * `evaluate` calls otherwise (see verify/background.ts).
+     * Optional batched form of {@link evaluate}: score many wallets in as few RPC round trips as
+     * the rule can manage (e.g. one multicall3 `aggregate3` for a whole checkpoint's wallets).
+     * Returns one result per input wallet, in order. Semantics MUST equal mapping `evaluate` over
+     * the wallets — this is a transport optimization, never a different answer. The background
+     * chain verifier prefers it when present and falls back to per-wallet `evaluate` otherwise.
+     *
+     * The wallets are NOT guaranteed to share a `sampleBlock`: the pipeline no longer groups them
+     * (it cannot, since which block a rule reads at is the rule's own business), so a batch is
+     * whatever was pending. A rule scoring the head reads once for the whole batch; a rule
+     * scoring pinned state groups by `sampleBlock` itself.
      */
     evaluateMany?(args: {
         options: O;
-        walletAddresses: string[];
+        wallets: RuleWallet[];
         ctx: ChainReadContext;
-    }): Promise<RuleResult[]>;
+    }): Promise<{
+        results: RuleResult[];
+    }>;
 }
 /**
  * The registry: a flat `type -> rule` map. Built-ins are provided by this

package/dist/tally/tally.d.ts

@@ -3,6 +3,7 @@ import type { VotesBundle } from "../schema/votes.js";
 import type { RuleRegistry } from "../rules/types.js";
 import type { ChainClient, BucketMath } from "../chain/types.js";
 import type { BundleChecks } from "../verify/types.js";
+import { type RuleCache } from "../rules/cache.js";
 import type { Tally } from "./types.js";
 /**
  * Deterministic per-contest aggregation over the CRDT's current bundles. Every aggregated
@@ -34,6 +35,19 @@ export interface TallyDeps {
         bundle: VotesBundle;
         checks: BundleChecks;
     }>;
+    /**
+     * This verifier's current head, handed to the weight rule as `ctx.head`. Never called by a
+     * weight rule that scores pinned historical state — including `constant`, which reads no
+     * chain at all — so the "an idle contest does zero chain reads" property is untouched.
+     * Defaults to the weight chain's own `getBlockNumber()`.
+     */
+    readHead?: (args: {
+        chain: ChainClient;
+    }) => Promise<{
+        block: number;
+    }>;
+    /** The weight rule's memo, handed to it as `ctx.cache` (rules/cache.ts). */
+    ruleCache?: RuleCache;
     /**
      * Hash of the current bucket boundary block on the criteria's chain, for the rolling tie
      * seed. Invoked at most once per `compute`, and only when a tie must actually be broken —

package/dist/tally/tally.js

@@ -1,6 +1,8 @@
 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";
 /** Byte-lexicographic compare of two byte arrays (returns <0, 0, >0). */
 function compareBytes(x, y) {
@@ -15,20 +17,34 @@ function compareBytes(x, y) {
 }
 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 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).
+    const weightCtx = {
+        chain: weightChain,
+        head: () => readHead({ chain: weightChain }),
+        cache: deps.ruleCache ?? makeMemoryRuleCache()
+    };
     const weightFor = async (wallet, blockNumber) => {
         const sampleBlock = bucketMath.sampleBlockForBucket(bucketMath.bucketForBlock(blockNumber));
-        const { score } = await weight.evaluate({
+        // A weight rule that fails a wallet contributes nothing; it does NOT drop the vote —
+        // admission was the gate's decision, already made (see rules/result.ts).
+        return scoreOrZero(await weight.evaluate({
             options: weightOptions,
-            walletAddress: wallet,
-            ctx: { chain: weightChain, blockNumber: sampleBlock }
-        });
-        return score;
+            wallet: { address: wallet, sampleBlock },
+            ctx: weightCtx
+        }));
     };
     /** The rolling tie seed for a community: sha256(bucketBlockHash ‖ publicKey bytes). */
     const tieSeed = async (blockHash, publicKey) => {

package/dist/transport/integration/harness.js

@@ -116,7 +116,10 @@ export async function makeVoteNode(topic, options = {}) {
     let verifyImpl = async () => okVerifier();
     const verifier = {
         verify: (bundle) => verifyImpl(bundle),
-        verifyOffline: (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 })
     };
     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 { GateResultCache } from "./gate-result-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";
@@ -16,16 +16,25 @@ import type { VerifyFail } from "./types.js";
  * `chainVerified: false` rows, and this verifier confirms or evicts in the background (see
  * DESIGN.md "Background chain verification").
  *
- * Batched, not sequential: a checkpoint's bundles share one bucket sample block, so the gate
- * stage groups pending wallets per sample block and prefers the rule's `evaluateMany` (one
- * multicall3 round trip for N wallets) over N serial `readContract` calls, falling back to
- * `limit`-bounded per-wallet reads for rules without a batched form. Results feed the shared
- * `(wallet, sampleBlock)` gate-result cache, and a settled bundle's terminal verdict feeds the
- * shared per-CID verdict cache — so a later re-publish of the same bundle short-circuits at
- * the gossip gate with zero chain work.
+ * Batched, not sequential: the gate stage hands a whole round's pending wallets to the rule's
+ * `evaluateMany` (one multicall3 round trip for N wallets) rather than making N serial
+ * `readContract` calls, falling back to `limit`-bounded per-wallet `evaluate` for rules without
+ * a batched form. It does NOT group them by block — which block each wallet is read at is the
+ * rule's business now, and a rule that needs grouping does it itself (see rules/types.ts).
+ * Deduping and memoizing reads is likewise the rule's, through the cache it is handed
+ * (rules/cache.ts), so a wallet settled by the forward gate costs nothing here; what this stage
+ * still owns is the per-CID verdict cache, so a later re-publish of a settled bundle
+ * short-circuits at the gossip gate with zero chain work.
  *
  * Failure classes are kept apart, mirroring the forward-gate's `reject`/`ignore` split:
- *   - gate scores `0n`            → EVICT + cache the provable `reject` (deterministic).
+ *   - gate `0n`, blamed on the sender → EVICT + cache the `reject` (the rule stands behind it:
+ *                                   every honest verifier computes the same score, so terminal).
+ *   - gate `0n`, blamed on nobody → "not yet", NOT "no": the item is re-examined until a grace
+ *                                   window closes (verify/gate-grace.ts), then evicted
+ *                                   `ignore`-class and uncached. A wallet that acquired the gate
+ *                                   asset seconds ago scores `0n` only for whoever's head lags,
+ *                                   so evicting on the spot would let RPC lag decide whether a
+ *                                   vote counts.
  *   - name missing/mismatched     → EVICT, NOT cached (view-dependent `ignore`-class: v1
  *                                   resolves at head — see verify/bundle.ts step 4).
  *   - RPC / resolver THREW        → infra, nobody's verdict: the bundle STAYS pending, the
@@ -46,8 +55,22 @@ export interface BackgroundVerifierDeps {
     chainFor: (ticker: string) => ChainClient;
     bucketMath: BucketMath;
     nameResolvers: NameResolver[];
-    /** Shared `(wallet, sampleBlock)` gate scores — batch results land here, hits skip the read. */
-    gateResultCache: GateResultCache;
+    /**
+     * 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.
+     */
+    ruleCache?: 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
+     * its coalesced reader.
+     */
+    readHead?: (args: {
+        chain: ChainClient;
+    }) => Promise<{
+        block: number;
+    }>;
     /** Shared persistent name-resolution cache (pkc-js rule, 1h max-age); omitted ⇒ resolve live. */
     nameResolutionCache?: NameResolutionCache;
     /** The gate's per-CID verdict cache — a settled bundle's terminal verdict is stored here. */
@@ -65,6 +88,14 @@ export interface BackgroundVerifierDeps {
     /** Infra-retry backoff base / cap (ms). Full-jittered exponential between rounds. */
     retryBaseMs?: number;
     retryCapMs?: number;
+    /**
+     * Grace / re-examination interval (ms) — how long a `0n` the rule blamed on nobody is
+     * treated as "not yet" before the bundle is dropped, and how often it is looked at in the
+     * meantime. Defaults to {@link GATE_GRACE_MS} / {@link GATE_RETRY_MS}; overridable so tests
+     * do not sit through the real window. Unused when the rule blames the sender.
+     */
+    gateGraceMs?: number;
+    gateRetryMs?: number;
 }
 export interface BackgroundChainVerifier {
     /** Queue provisionally admitted bundles and return immediately; the drain runs detached. */