@bitsocial/pubsub-voting 0.2.1 → 0.4.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) 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. 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).
 
 See [DESIGN.md](./DESIGN.md) for the full rationale, including how this resists vote-dropping and how criteria upgrades fork cleanly.
 
@@ -35,7 +35,7 @@ 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 serves historical state at least `voteExpiryBuckets × blocksPerBucket` blocks behind head and carries a multicall3 deployment in its viem `chain` config; return `undefined` for a chain with no RPC configured, and `createContest`/`createContestVote` throws `MissingChainClientError` (recuse, don't miscount) |
+| `chains` | `ChainClientFactory` | yes | resolves each chain a contest's criteria requires (`{ chain, chainId }`) to a viem `PublicClient`; rules read through it for the gate and weight. **RPC endpoints are this client's own settings, never part of the criteria document** — return one shared (memoized) client per chain, pointed at a gateway that carries a multicall3 deployment in its viem `chain` config and serves **historical state at least `voteExpiryBuckets × blocksPerBucket` blocks behind head** (the v1 gate reads the head first, but falls back to the block a ballot names — see [Custom rules](#custom-rules)); return `undefined` for a chain with no RPC configured, and `createContest`/`createContestVote` throws `MissingChainClientError` (recuse, don't miscount) |
 | `signer` | `VoteSigner` | no | the voting wallet's address + EIP-712 ballot signing; omit for a read-only voter |
 | `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 |
@@ -87,6 +87,31 @@ await contest.update();                                   // join the topic, col
 // await contest.stop();                                  // leave the topic
 ```
 
+### 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:
+
+```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)"
+}
+```
+
+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.
+
+It is a courtesy check, not a promise — eligibility can change between the check and the publish,
+and each peer verifies against its own chain view. `publish()` deliberately does not call it: the
+gate is the network's decision, and a rejection still surfaces after the fact as
+`VoteEvictedError`, carrying the same kind of reason.
+
 Each ranking row carries one flag **per deferred verification operation** (mirroring pkc-js's
 `nameResolved`), and every background settlement re-fires `update` — so a leaderboard can render
 provisional rows immediately and refine them in place:
@@ -196,13 +221,13 @@ 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 and is evaluated at the bundle's bucket block. Chain-reading rules get `ctx.chain` — the viem `PublicClient` for their `options.chain` — and write their own reads (`readContract`, `getBalance`, ...), pinning each call to the sampled block with `blockNumber: BigInt(ctx.blockNumber)`. There is **one kind**: `evaluate → { score: bigint }`, a non-negative score where `0n` means "does not qualify" (a result object, not a bare `bigint`, so slot-specific fields can be added later). 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.score > 0n ? weight.score : 0n`. A rule that needs a threshold returns `0n` 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, walletAddresses, ctx })` batch hook (same argument object as `evaluate`, with `walletAddresses` in place of `walletAddress`, returning one `RuleResult` per input wallet in order) — its semantics MUST equal mapping `evaluate` — which the background verifier uses to batch a cold join's gate reads (`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 **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).)
 
 Built-ins: `erc5192-min-balance` (v1) and `constant` (v1).
 
 Two chain-reading rules ship in the tree but are deliberately **not** built in, so a criteria naming either recuses via `UnknownRuleError` instead of silently gating on an asset that does not bound Sybils:
 
-- **`erc721-min-balance`** (exported) — a bare `balanceOf` on a *transferable* token. One token walked A → B → C inside one expiry window backs three concurrent live votes, since every bundle is verified at its own pinned block and the winner set is LWW-keyed per wallet. `erc5192-min-balance` is this rule plus `supportsInterface(0xb45a3c0e)`, which refuses a contract that does not declare its tokens locked.
+- **`erc721-min-balance`** (exported) — a bare `balanceOf` on a *transferable* token. One token walked A → B → C inside one expiry window backs three concurrent live votes, since each bundle is verified once, when it is merged, and the winner set is LWW-keyed per wallet. `erc5192-min-balance` is this rule plus `supportsInterface(0xb45a3c0e)`, which refuses a contract that does not declare its tokens locked.
 - **`erc20-balance`** (not exported) — the same amplification, reopened by fungibility, plus the open lazy-tally ceiling question for balance-derived weight.
 
 A host that wants a transferable gate anyway registers `erc721MinBalance` explicitly through the `rules` option below — the library stops blessing the configuration, it does not forbid it. `erc20-balance` is not exported at all, so a host that wants balance-weighting supplies its own rule of that `type`. See [DESIGN.md, Does one Pass mean one vote?](./DESIGN.md#does-one-pass-mean-one-vote).
@@ -216,8 +241,10 @@ import { z } from "zod";
 const seeditModAllowlist: Rule<{ type: "seedit-mod-allowlist"; allow: string[] }> = {
   type: "seedit-mod-allowlist",
   optionsSchema: z.object({ type: z.literal("seedit-mod-allowlist"), allow: z.array(z.string()) }),
-  async evaluate({ options, walletAddress }) {
-    return { score: options.allow.includes(walletAddress) ? 1n : 0n }; // gate: 1n admits, 0n rejects
+  async evaluate({ options, wallet }) {
+    return options.allow.includes(wallet.address)
+      ? { success: true, score: 1n }
+      : { success: false, error: "this wallet is not on the moderator allowlist" }; // shown to the voter
   }
 };
 
@@ -229,6 +256,46 @@ const voter = new PubsubVoter({
 
 A custom `type` becomes part of `dag-cbor(criteria)`, so it is provably pinned to the topic it runs on, and a client that does not implement a `type` named in `criteria.requires.rules` throws `UnknownRuleError` and recuses itself rather than miscounting.
 
+#### What a rule owns: its block, and its cache
+
+A rule is handed the pinned block its ballot names, a lazy head reader, and its own memo, and decides for itself which to read and what to remember:
+
+```ts
+evaluate(args: { options: O; wallet: { address: string; sampleBlock: number }; ctx: ChainReadContext }): Promise<RuleResult>
+
+interface ChainReadContext {
+  chain: ChainClient;                        // the viem PublicClient for options.chain
+  head: () => Promise<{ block: number }>;    // this verifier's current block — lazy, coalesced
+  cache: RuleCache;                          // this rule's memo, persistent and shared across contests
+}
+```
+
+- **`wallet.sampleBlock`** is the bundle's bucketized block, already floored — the historical block every verifier agrees the ballot names. Read there and your score is identical on every verifier forever. It is *not* a claim about when the ballot was signed (it trails by up to `blocksPerBucket`).
+- **`ctx.head()`** is this verifier's current block. Read there and a wallet qualifies the moment it acquires the gating asset, instead of waiting for the next bucket boundary. Resolve it once per evaluation and pin your reads to that number — always pass an explicit `blockNumber: BigInt(...)`, or the read coalescer cannot batch you.
+- **`ctx.cache`** memoizes under a `key` you choose and an `epoch` that says when the answer stops being true (a moved epoch is how an entry expires; `purgeBelow` drops what is behind). **Chain-reading rules must use it** — it is what turns "one chain read per unique bundle" into "one read per key per epoch", so without it an ineligible wallet can make every peer on the topic pay an RPC round trip per fresh-signed bundle. `memoMany` reads only the misses, in one batched call.
+
+```ts
+const { values } = await ctx.cache.memoMany({
+  keys: wallets.map((w) => `bal/${w.toLowerCase()}`),
+  epoch: block,                                   // e.g. the pinned block, or a coarse head window
+  read: async ({ keys }) => ({ values: await readOnChain(keys) })
+});
+```
+
+`RuleResult` is a discriminated union, shaped like pkc-js's `ChallengeResult`:
+
+```ts
+type RuleResult =
+  | { success: true;  score: bigint }                          // score MUST be > 0n
+  | { success: false; error: string; penalize?: boolean };     // penalize default true
+```
+
+**`error` is required on the failing branch**, because only the rule knows why a wallet fell short — it holds none, it holds too few, the contract gates nothing. That sentence is what the library shows the voter: it becomes the verdict reason, so it reaches the publisher on `VoteEvictedError.verdict.reason`, and it is what `contest.checkEligibility()` returns. Write it about the wallet ("this wallet holds none of the gate token"), not about the library, and leave block numbers out unless a voter can act on them. Making it optional would mean every UI re-deriving the rule's thresholds and block choice to say anything useful — which is exactly the coupling `ctx` and `RuleCache` exist to remove.
+
+**`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.
+
+`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)
 
 v1 ships `constant` weight (one Pass, one vote) **on purpose** — it resists whale dominance and downvote weaponization. Balance-derived, token-weighted voting (Pass gate + BSO weight via `erc20-balance`) is a designed-but-unshipped capability: the rule path and result shape leave room for it with no engine change, but it is not in the v1 built-ins and carries open governance/abuse and lazy-tally questions — plus the Sybil amplification a fungible gate reopens, which the soulbound gate's fix cannot close for a balance (it needs a hold-duration guard instead). See [ROADMAP.md](./ROADMAP.md), [DESIGN.md, Does one Pass mean one vote?](./DESIGN.md#does-one-pass-mean-one-vote), and [DESIGN.md, Future improvements](./DESIGN.md#future-improvements).

package/dist/client/voter.d.ts

@@ -65,6 +65,19 @@ 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.
+ */
+export type EligibilityResult = {
+    eligible: true;
+    /** The wallet's gate score, `> 0n`. For a balance gate this is the holding itself. */
+    score: bigint;
+} | {
+    eligible: false;
+    /** The rule's own explanation, written for the voter. Render it verbatim. */
+    error: string;
+};
 export interface Contest {
     /** The criteria document this contest runs (already validated). */
     readonly criteria: Criteria;
@@ -85,6 +98,30 @@ export interface Contest {
     stop(): Promise<void>;
     /** Compute the current contest ranking fresh, bypassing the cache. */
     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.
+     *
+     * 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
+     * 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.
+     *
+     * 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.
+     */
+    checkEligibility(args: {
+        address: string;
+    }): Promise<EligibilityResult>;
     /**
      * Fired when incoming votes change the state; `tally` carries the freshly recomputed
      * ranking. Background check settlements fire it too: a cold join emits a first tally with

package/dist/client/voter.js

@@ -14,9 +14,10 @@ import { makeRootChaser, toChaseSession } from "../transport/chase.js";
 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 { makeBundleVerifier } from "../verify/bundle.js";
 import { makeVerdictCache } from "../verify/cache.js";
-import { makePersistentGateResultCache, purgeExpiredGateResults } from "../verify/gate-result-cache.js";
 import { makeNameResolutionCache } from "../verify/name-resolution-cache.js";
 import { makeStorage } from "../storage/node.js";
 import { makeAnnouncer } from "../transport/announce/node.js";
@@ -631,14 +632,31 @@ class ContestEngine {
             voteExpiryBuckets: criteria.voteExpiryBuckets,
             isProvisional: (cid) => this.#isPending(cid)
         });
-        // One gate-result cache shared between the inline forward-gate verifier and the
-        // background chain verifier, so neither re-reads a (wallet, sampleBlock) the other
-        // settled — layered over the voter's persistent store, keyed under this contest's rule
-        // hash: the gate score is a pure function of (rule, chainId, wallet, sampleBlock), so
-        // hashing the canonical rule document + chainId is exactly the sharing boundary (two
-        // contests over one gate share reads; different gates cannot collide).
+        // 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 gateResultCache = makePersistentGateResultCache({ store: deps.gateStore, ruleHash: this.#ruleHash });
+        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.
+        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 }))
+        });
         const verifier = makeBundleVerifier({
             criteria,
             criteriaCid: criteriaCidBytes,
@@ -647,8 +665,9 @@ class ContestEngine {
             chainFor: (ticker) => this.#chainFor(ticker),
             bucketMath: this.#bucketMath,
             nameResolvers: deps.nameResolvers,
-            gateResultCache,
-            nameResolutionCache: deps.nameResolutionCache
+            ruleCache: gateCache,
+            nameResolutionCache: deps.nameResolutionCache,
+            readHead: ({ chain }) => this.#readHead({ chain })
         });
         // The gate/transport are (re)built on join(); the store, crdt, caches, verifier, and
         // background verifier are stable per contest, so they survive re-joins of the topic.
@@ -662,8 +681,9 @@ class ContestEngine {
             chainFor: (ticker) => this.#chainFor(ticker),
             bucketMath: this.#bucketMath,
             nameResolvers: deps.nameResolvers,
-            gateResultCache,
+            ruleCache: gateCache,
             nameResolutionCache: deps.nameResolutionCache,
+            readHead: ({ chain }) => this.#readHead({ chain }),
             cache: this.#cache,
             onGateVerified: (cid) => this.#settleCheck(cid, "chainVerified"),
             onNameResolved: (cid) => this.#settleCheck(cid, "nameResolved"),
@@ -676,6 +696,8 @@ class ContestEngine {
             registry: deps.registry,
             chainFor: (ticker) => this.#chainFor(ticker),
             bucketMath: this.#bucketMath,
+            readHead: ({ chain }) => this.#readHead({ chain }),
+            ruleCache: weightCache,
             current: () => this.#crdt
                 .currentEntries(this.#currentBucketCache)
                 .map(({ cid, bundle }) => ({ bundle, checks: this.#checksFor(cid, bundle) })),
@@ -808,35 +830,27 @@ class ContestEngine {
         const head = await this.#deps.readHead(this.#ruleChain);
         this.#currentBucketCache = this.#bucketMath.bucketForBlock(Number(head));
         this.#headReadMs = Date.now();
-        this.#maybePurgeGateResults();
         return this.#currentBucketCache;
     }
-    /** The last purge's expiry boundary (oldest admissible sample block); 0 = never purged. */
-    #purgedSampleBlock = 0;
     /**
-     * Drop this rule's persisted gate results older than the oldest admissible sample block —
-     * provably dead: a score at bucket B is only ever consulted while bundles from B are within
-     * `voteExpiryBuckets` of head (see verify/gate-result-cache.ts `purgeExpiredGateResults`).
-     * Piggybacks on the head reads the engine does anyway (join-with-state, publish, tally)
-     * and re-runs only when the boundary advances past the last purged one — so an idle
-     * engine costs no chain read and no purge, and a steady head costs no key scan, but a
-     * long-lived engine still sheds entries as they expire instead of leaving them to the
-     * LRU backstop. Fire-and-forget by design.
+     * The current head on `chain`, handed to every rule as `ctx.head` (verify/bundle.ts,
+     * verify/background.ts, tally/tally.ts all take this seam). It goes through the voter-wide
+     * {@link ResolvedDeps.readHead} coalescer for the same reason {@link #refreshBucket} does:
+     * a rule that scores current state puts this on the verify path, so a directory-wide gossip
+     * burst would otherwise fire one `eth_blockNumber` per contest per message instead of
+     * sharing one in-flight read per chain.
      */
-    #maybePurgeGateResults() {
-        const oldestBucket = this.#currentBucketCache - this.criteria.voteExpiryBuckets;
-        if (oldestBucket <= 0)
-            return;
-        const oldestSampleBlock = this.#bucketMath.sampleBlockForBucket(oldestBucket);
-        if (oldestSampleBlock <= this.#purgedSampleBlock)
-            return;
-        this.#purgedSampleBlock = oldestSampleBlock;
-        void purgeExpiredGateResults({
-            store: this.#deps.gateStore,
-            ruleHash: this.#ruleHash,
-            oldestSampleBlock
-        });
+    async #readHead(args) {
+        return { block: Number(await this.#deps.readHead(args.chain)) };
     }
+    /**
+     * PURGE REMOVED — kept as a note because the old behaviour was load-bearing and its
+     * replacement lives elsewhere. Persisted gate entries used to be purged here, at the oldest
+     * admissible bucket sample block, because the engine knew every entry was keyed by one. It
+     * no longer knows: a rule chooses its own keys and epochs (rules/cache.ts), so only the rule
+     * can say what is dead — `erc5192-min-balance` purges its head-keyed entries as the head
+     * window rolls, and its pinned entries stay valid until the store's LRU bound reclaims them.
+     */
     /** `Date.now()` of the last gating-chain head read, memoizing {@link #nowBucket}. */
     #headReadMs = 0;
     /** The current gating-chain head bucket, memoized for {@link HEAD_BUCKET_TTL_MS}. */
@@ -858,6 +872,21 @@ class ContestEngine {
             return true;
         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}.
+     *
+     * 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.
+     */
+    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) };
+    }
     /** Hash of the current bucket boundary block on the gating (`rule`) chain (rolling tie seed). */
     async #bucketBlockHash() {
         const head = await this.#ruleChain.getBlockNumber();
@@ -1683,6 +1712,9 @@ class ContestView {
     getTally() {
         return this.#engine.computeTally();
     }
+    checkEligibility(args) {
+        return this.#engine.checkEligibility(args);
+    }
     /**
      * Internal hook (not part of the {@link Contest} interface): this contest's current checkpoint
      * root record, encoded on demand. The fetch responder and heartbeat use the engine directly;

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export * from "./rules/erc5192-min-balance.js";
 export * from "./rules/erc721-min-balance.js";
 export * from "./rules/constant.js";
 export * from "./rules/registry.js";
+export { makeMemoryRuleCache, makePersistentRuleCache, type RuleCache } from "./rules/cache.js";
 export * from "./encoding/canonical.js";
 export * from "./topic.js";
 export * from "./errors.js";

package/dist/index.js

@@ -34,6 +34,10 @@ export * from "./rules/erc5192-min-balance.js";
 export * from "./rules/erc721-min-balance.js";
 export * from "./rules/constant.js";
 export * from "./rules/registry.js";
+// The cache a rule computes through (`ctx.cache`): a rule owns its keys and epochs, the library
+// owns the store, the bound and the purge. A custom chain-reading rule MUST memoize through it —
+// see rules/cache.ts and README "Custom rules".
+export { makeMemoryRuleCache, makePersistentRuleCache } from "./rules/cache.js";
 // Implemented runtime: encoding, topic, errors, identity seam, facade.
 export * from "./encoding/canonical.js";
 export * from "./topic.js";

package/dist/rules/cache.d.ts

@@ -0,0 +1,107 @@
+import type { LruStorage } from "../storage/types.js";
+/**
+ * The cache a rule computes through.
+ *
+ * A rule decides *what* it reads and *when* the answer stops being true; the library decides
+ * where that answer is stored, how it is bounded, and how it is shared. This seam is that split.
+ * It exists because cache validity is the thing that genuinely differs between rules and cannot
+ * be expressed generically:
+ *
+ *   - a score read at a pinned historical block is true forever, so it should never expire;
+ *   - a score read at the chain head stops being true almost immediately — a wallet that failed
+ *     a moment ago may hold the gate asset now — so it must expire, and how fast is a judgement
+ *     only the rule can make;
+ *   - some reads are not per-wallet at all (`erc5192-min-balance` probes `supportsInterface`
+ *     once per contract), which no per-wallet key can express.
+ *
+ * The library still owns the mechanics, because they are not rule-specific and are easy to get
+ * wrong: persistence under the voter's `dataPath`, the bounded in-memory front, and the
+ * namespace. Every rule instance gets its own keyspace, namespaced by the rule's `type`, its
+ * canonical options and the id of the chain IT reads (which for the weight rule need not be the
+ * gating chain) — so two contests running the same gate share each other's reads (a 5chan-style
+ * directory of 63 boards on one Pass is one read per wallet, not 63), while two different gates,
+ * or the same gate on a different contract or chain, can never collide.
+ *
+ * **Caching is not optional for a chain-reading rule.** It is what bounds the "one chain read per
+ * unique bundle" amplifier: without it, an ineligible wallet can mint fresh-signed bundles and
+ * make every peer on the topic pay an RPC round trip for each one (DESIGN.md "Can valid votes
+ * clog the topic?"). {@link RuleCache.memoMany} exists so the correct behaviour is one call.
+ *
+ * Values are strings because the persistent tier is JSON-backed — a `bigint` score travels as a
+ * decimal string, a boolean as `"1"`/`"0"`.
+ */
+export interface RuleCache {
+    /** The memoized value for `key` within `epoch`, or `{ value: undefined }` on a miss. */
+    get(args: {
+        key: string;
+        epoch: number;
+    }): Promise<{
+        value: string | undefined;
+    }>;
+    /**
+     * Memoize `value` for `key` within `epoch`. Idempotent: an existing entry is never
+     * overwritten, so a score cannot be silently replaced under a key that still applies.
+     * Returns immediately — any persistence settles in the background, so the verify hot path
+     * never waits on a cache write.
+     */
+    set(args: {
+        key: string;
+        epoch: number;
+        value: string;
+    }): void;
+    /**
+     * Look up many keys at once and read only the misses — the batched path a rule should use
+     * for a cold join's wallets, where `read` becomes one multicall instead of N round trips.
+     * `read` is called at most once, with the missing keys in order, and MUST return one value
+     * per key it was given. Skipped entirely when everything hits.
+     */
+    memoMany(args: {
+        keys: string[];
+        epoch: number;
+        read: (args: {
+            keys: string[];
+        }) => Promise<{
+            values: string[];
+        }>;
+    }): Promise<{
+        values: string[];
+    }>;
+    /**
+     * Drop persisted entries below `epoch` — the rule's own statement that they are dead.
+     *
+     * This is on the rule because only the rule knows what an epoch means. A rule keying by the
+     * chain head knows everything behind the current window is unreachable; a rule keying by a
+     * bundle's pinned block knows nothing expires until the vote itself does. Optionally
+     * restricted to keys starting with `keyPrefix`, so a rule that mixes both — as the v1 gate
+     * does — can purge its head-keyed entries without touching its permanently-valid ones.
+     *
+     * Best-effort and fire-and-forget: the store's LRU bound is the backstop for a rule that
+     * never calls it. Repeat calls at or below the last purged epoch are free.
+     */
+    purgeBelow(args: {
+        epoch: number;
+        keyPrefix?: string;
+    }): void;
+}
+/**
+ * An in-memory {@link RuleCache}, FIFO-bounded. Used on its own by unit tests and as the hot
+ * front of the persistent cache. Eviction is safe: an evicted entry costs a re-read, never a
+ * wrong answer — and without a bound, a flood of fresh wallets would be a memory-exhaustion
+ * vector (DESIGN.md "Can valid votes clog the topic?").
+ */
+export declare function makeMemoryRuleCache(args?: {
+    maxEntries?: number;
+}): RuleCache;
+/**
+ * A {@link RuleCache} over the voter's persistent store: the in-memory FIFO front above, with
+ * read-through on a miss and fire-and-forget write-through. A broken store read or write
+ * degrades to a live chain read — never an error into the verify pipeline.
+ *
+ * `namespace` is the rule's keyspace (see {@link RuleCache}); the voter derives it from the
+ * canonical rule reference + chain id.
+ */
+export declare function makePersistentRuleCache(args: {
+    store: LruStorage;
+    namespace: string;
+    maxMemEntries?: number;
+}): RuleCache;