@bitsocial/pubsub-voting 0.2.1 → 0.3.0

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. */

package/dist/verify/background.js

@@ -1,12 +1,16 @@
 import { tickerForRef } from "../chain/ticker.js";
+import { makeMemoryRuleCache } from "../rules/cache.js";
+import { GATE_GRACE_MS, GATE_RETRY_MS } from "./gate-grace.js";
 import { UnknownRuleError } from "../errors.js";
 import { resolveNameThroughCache } from "./name-resolution-cache.js";
 const RETRY_BASE_MS = 2_000;
 const RETRY_CAP_MS = 60_000;
 export function makeBackgroundVerifier(deps) {
-    const { criteria, registry, chainFor, bucketMath, nameResolvers, gateResultCache, nameResolutionCache, cache, limit } = deps;
+    const { criteria, registry, chainFor, bucketMath, nameResolvers, nameResolutionCache, cache, limit } = deps;
     const retryBaseMs = deps.retryBaseMs ?? RETRY_BASE_MS;
     const retryCapMs = deps.retryCapMs ?? RETRY_CAP_MS;
+    const gateGraceMs = deps.gateGraceMs ?? GATE_GRACE_MS;
+    const gateRetryMs = deps.gateRetryMs ?? GATE_RETRY_MS;
     // Resolve the gate `rule`, its options, and its chain once (same shape as verify/bundle.ts).
     // The re-binding after the guard keeps the non-undefined narrowing inside the closures below.
     const maybeRule = registry[criteria.rule.type];
@@ -15,6 +19,12 @@ export function makeBackgroundVerifier(deps) {
     const rule = maybeRule;
     const ruleOptions = rule.optionsSchema.parse(criteria.rule);
     const ruleChain = chainFor(tickerForRef(criteria, criteria.rule, ruleOptions));
+    const readHead = deps.readHead ?? (async ({ chain }) => ({ block: Number(await chain.getBlockNumber()) }));
+    const ctx = {
+        chain: ruleChain,
+        head: () => readHead({ chain: ruleChain }),
+        cache: deps.ruleCache ?? makeMemoryRuleCache()
+    };
     const queue = [];
     /** CIDs queued or in-flight, so a re-chased root cannot double-verify a bundle. */
     const inFlight = new Set();
@@ -38,38 +48,39 @@ export function makeBackgroundVerifier(deps) {
         return bucketMath.sampleBlockForBucket(bucketMath.bucketForBlock(bundle.blockNumber));
     }
     /**
-     * Gate stage for one round's batch: group the not-yet-gated items per sample block, read the
-     * distinct uncached wallets — `evaluateMany` when the rule has it, `limit`-bounded singles
-     * otherwise — and feed every score into the shared gate-result cache. Throws on the FIRST
-     * infra failure: the round's unfinished items are re-queued by the caller.
+     * Gate stage for one round's batch: hand every not-yet-gated wallet to the rule at once —
+     * `evaluateMany` when it has one, `limit`-bounded per-wallet `evaluate` otherwise — and
+     * record each score with the rule's own verdict on whether a `0n` is attributable.
+     *
+     * No grouping and no cache lookups here any more: which block each wallet is read at, and
+     * what may be memoized under which key, are the rule's decisions (rules/types.ts,
+     * rules/cache.ts). Duplicate wallets are still collapsed before the call, because that is a
+     * property of THIS batch rather than of any rule. Throws on the FIRST infra failure: the
+     * round's unfinished items are re-queued by the caller.
      */
     async function gateStage(items) {
-        const groups = new Map();
-        for (const item of items) {
-            if (item.gateDone)
+        const pending = items.filter((item) => !item.gateDone);
+        if (pending.length === 0)
+            return;
+        const wallets = [];
+        const at = new Map();
+        for (const item of pending) {
+            const wallet = { address: item.bundle.address, sampleBlock: sampleBlockFor(item.bundle) };
+            const key = `${wallet.address.toLowerCase()}:${wallet.sampleBlock}`;
+            if (at.has(key))
                 continue;
-            const block = sampleBlockFor(item.bundle);
-            groups.set(block, [...(groups.get(block) ?? []), item]);
+            at.set(key, wallets.length);
+            wallets.push(wallet);
         }
-        for (const [sampleBlock, group] of groups) {
-            const wallets = [];
-            for (const item of group) {
-                const wallet = item.bundle.address;
-                if ((await gateResultCache.get(wallet, sampleBlock)) === undefined && !wallets.includes(wallet)) {
-                    wallets.push(wallet);
-                }
-            }
-            if (wallets.length > 0) {
-                const ctx = { chain: ruleChain, blockNumber: sampleBlock };
-                const results = rule.evaluateMany
-                    ? await rule.evaluateMany({ options: ruleOptions, walletAddresses: wallets, ctx })
-                    : await Promise.all(wallets.map((walletAddress) => limit(() => rule.evaluate({ options: ruleOptions, walletAddress, ctx }))));
-                wallets.forEach((wallet, i) => gateResultCache.set(wallet, sampleBlock, results[i].score));
-            }
-            for (const item of group) {
-                item.ruleScore = (await gateResultCache.get(item.bundle.address, sampleBlock));
-                item.gateDone = true;
-            }
+        const results = rule.evaluateMany
+            ? (await rule.evaluateMany({ options: ruleOptions, wallets, ctx })).results
+            : await Promise.all(wallets.map((wallet) => limit(() => rule.evaluate({ options: ruleOptions, wallet, ctx }))));
+        for (const item of pending) {
+            const key = `${item.bundle.address.toLowerCase()}:${sampleBlockFor(item.bundle)}`;
+            const result = results[at.get(key)];
+            item.ruleScore = result.score;
+            item.gatePenalize = result.penalize !== false;
+            item.gateDone = true;
         }
     }
     /**
@@ -115,6 +126,8 @@ export function makeBackgroundVerifier(deps) {
     async function round() {
         const batch = queue.splice(0);
         const requeue = [];
+        /** Unattributable `0n` items still inside their grace window: re-examined, not a failure. */
+        const notYet = [];
         let infraError;
         // Gate stage first, whole batch: this is where batching wins (one multicall per sample
         // block instead of one read per wallet). An infra throw leaves every un-gated item intact.
@@ -131,13 +144,37 @@ export function makeBackgroundVerifier(deps) {
                 continue;
             }
             if (item.ruleScore === 0n) {
-                // Provable, deterministic reject — safe to cache so a re-publish short-circuits.
+                if (item.gatePenalize) {
+                    // Provable, deterministic reject — safe to cache so a re-publish short-circuits.
+                    const verdict = {
+                        valid: false,
+                        disposition: "reject",
+                        reason: `not admitted: rule score is 0n`
+                    };
+                    cache.set(item.cid, verdict);
+                    deps.onEvict(item.cid, verdict);
+                    settle(item);
+                    continue;
+                }
+                // The rule declined to blame anyone (see rules/types.ts, RuleResult.penalize):
+                // `0n` means "not yet", not "no". The wallet may have acquired the gate asset in
+                // a block this verifier has not seen, or may acquire it a moment from now — a
+                // client that signs the instant it mints races its own transaction. Evicting here
+                // would make whether a vote counts depend on whose RPC was a few blocks ahead, so
+                // the item is re-examined until the grace window closes; only then is it dropped,
+                // `ignore`-class and UNCACHED, so a later re-publish is judged fresh.
+                // Re-examining is nearly free: while the rule's own memo holds, its re-read comes
+                // straight from that cache and touches no chain (see verify/gate-grace.ts).
+                if (Date.now() - item.queuedAt < gateGraceMs) {
+                    item.gateDone = false;
+                    notYet.push(item);
+                    continue;
+                }
                 const verdict = {
                     valid: false,
-                    disposition: "reject",
-                    reason: `not admitted: rule score is 0n at block ${sampleBlockFor(item.bundle)}`
+                    disposition: "ignore",
+                    reason: `not admitted: rule score is 0n, and still 0n after the grace window`
                 };
-                cache.set(item.cid, verdict);
                 deps.onEvict(item.cid, verdict);
                 settle(item);
                 continue;
@@ -164,23 +201,32 @@ export function makeBackgroundVerifier(deps) {
             settle(item);
         }
         if (requeue.length > 0) {
-            queue.push(...requeue);
+            queue.push(...requeue, ...notYet);
             failedRounds += 1;
             deps.onError(infraError);
             armRetry();
         }
+        else if (notYet.length > 0) {
+            // "Not yet" is nobody's failure: no `onError`, no backoff escalation, just a fixed
+            // re-examination interval until the grace window closes or the wallet's holding
+            // shows up. Counting it as a failed round would exponentially back off the ONE
+            // thing that needs a steady cadence.
+            queue.push(...notYet);
+            failedRounds = 0;
+            armRetry(gateRetryMs);
+        }
         else {
             failedRounds = 0;
         }
     }
-    function armRetry() {
+    function armRetry(fixedDelayMs) {
         if (stopped || retryTimer !== undefined)
             return;
         const ceiling = Math.min(retryCapMs, retryBaseMs * 2 ** (failedRounds - 1));
         const timer = setTimeout(() => {
             retryTimer = undefined;
             kickDrain();
-        }, Math.random() * ceiling);
+        }, fixedDelayMs ?? Math.random() * ceiling);
         timer.unref?.();
         retryTimer = timer;
     }
@@ -209,7 +255,15 @@ export function makeBackgroundVerifier(deps) {
                 if (inFlight.has(key))
                     continue;
                 inFlight.add(key);
-                queue.push({ ...entry, gateDone: false, gateNotified: false, ruleScore: 0n, resolvedNames: {} });
+                queue.push({
+                    ...entry,
+                    gateDone: false,
+                    gateNotified: false,
+                    ruleScore: 0n,
+                    gatePenalize: true,
+                    resolvedNames: {},
+                    queuedAt: Date.now()
+                });
             }
             kickDrain();
         },

package/dist/verify/bundle.d.ts

@@ -1,7 +1,7 @@
 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 { BundleVerifier } from "./types.js";
 /**
@@ -11,8 +11,10 @@ import type { BundleVerifier } from "./types.js";
  *
  *   1. signature   (local, µs): recover the EIP-712 signer, must equal `bundle.address`.
  *   2. constraints (local, µs): `votes.length <= maxVotesPerAddress`, each vote in range.
- *   3. gate        (chain):     the `rule` scores the wallet `> 0n` at the bucket block.
- *                               `0n` -> not admitted -> drop.
+ *   3. gate        (chain):     the `rule` scores the wallet `> 0n`, at whichever block the rule
+ *                               itself reads (rules/types.ts). `0n` -> not admitted -> drop, as
+ *                               a `reject` when the rule blames the sender for it and an
+ *                               `ignore` when it does not.
  *   4. name        (network):   each vote's `community.name` (if any) must resolve to the
  *                               claimed `publicKey`; a squatted/absent name drops the bundle.
  *
@@ -40,13 +42,25 @@ export interface BundleVerifierDeps {
     /** Host-injected community-name resolvers (`PubsubVoterOptions.nameResolvers`). */
     nameResolvers: NameResolver[];
     /**
-     * Optional cache of gate results, keyed by `(wallet, sampleBlock)`. When present, a wallet's
-     * score at a bucket's sample block is read from chain at most once — a `0n` miss short-circuits
-     * a flood of fresh-signed bundles from an ineligible wallet, and a `> 0n` hit short-circuits an
-     * *eligible* wallet re-signing or cycling choices within a bucket. Both are deterministic,
-     * historical reads. Omitted ⇒ every novel bundle pays its own gate read (prior behaviour).
+     * This verifier's current head, handed to the rule as `ctx.head`. A rule scoring pinned
+     * historical state never calls it, so a pinned-only deployment does no head read at all.
+     * Defaults to a direct `getBlockNumber()` on the rule's own client; the voter injects its
+     * coalesced reader instead, so a directory-wide burst shares one read per chain (see
+     * client/voter.ts `makeHeadReader`).
      */
-    gateResultCache?: GateResultCache;
+    readHead?: (args: {
+        chain: ChainClient;
+    }) => Promise<{
+        block: number;
+    }>;
+    /**
+     * The gate rule's memo (see rules/cache.ts), handed to it as `ctx.cache`. This is what keeps
+     * a wallet's gate read from repeating per bundle — an ineligible wallet minting fresh-signed
+     * bundles, or an eligible one cycling choices, costs one read per key per rule epoch rather
+     * than one per bundle. Defaults to a private in-memory cache (unit tests); the voter injects
+     * the persistent, contest-shared one.
+     */
+    ruleCache?: RuleCache;
     /**
      * Optional persistent cache of name resolutions (the pkc-js rule — see
      * verify/name-resolution-cache.ts). When present, a carried name is resolved live at most

package/dist/verify/bundle.js

@@ -1,18 +1,26 @@
 import { tickerForRef } from "../chain/ticker.js";
+import { makeMemoryRuleCache } from "../rules/cache.js";
 import { UnknownRuleError } from "../errors.js";
 import { verifyBundleSignature } from "./signature.js";
 import { checkBundleConstraints } from "./constraints.js";
 import { resolveNameThroughCache } from "./name-resolution-cache.js";
 export function makeBundleVerifier(deps) {
-    const { criteria, criteriaCid, chainId, registry, chainFor, bucketMath, nameResolvers, gateResultCache, nameResolutionCache } = deps;
-    // Resolve the gate `rule`, its options, and its chain client once. The rule reads at the
-    // bundle's bucket block, but which rule/chain to use is fixed by the criteria, so it need
-    // not be recomputed per bundle.
+    const { criteria, criteriaCid, chainId, registry, chainFor, bucketMath, nameResolvers, nameResolutionCache } = deps;
+    // Resolve the gate `rule`, its options and its chain client once: they are fixed by the
+    // criteria, so none of it is recomputed per bundle.
     const rule = registry[criteria.rule.type];
     if (!rule)
         throw new UnknownRuleError("rule", criteria.rule.type);
     const ruleOptions = rule.optionsSchema.parse(criteria.rule);
     const ruleChain = chainFor(tickerForRef(criteria, criteria.rule, ruleOptions));
+    const readHead = deps.readHead ?? (async ({ chain }) => ({ block: Number(await chain.getBlockNumber()) }));
+    // The rule's whole world: its chain, this verifier's head (lazy — never read for a rule that
+    // does not want it), and its own memo. Which block it actually reads at is its business.
+    const ctx = {
+        chain: ruleChain,
+        head: () => readHead({ chain: ruleChain }),
+        cache: deps.ruleCache ?? makeMemoryRuleCache()
+    };
     // Stage 1, shared by `verify` and `verifyOffline`: signature + constraints, local and µs.
     const verifyOffline = async (bundle) => {
         // 1. Signature (free) — a forged/tampered bundle drops before any chain/network read.
@@ -28,23 +36,29 @@ export function makeBundleVerifier(deps) {
             const offline = await verifyOffline(bundle);
             if (!offline.valid)
                 return offline;
-            // 3. Gate (chain) — read the `rule` at the bucket's sample block. The score is a pure
-            //    function of a pinned historical block, so it is memoized per `(wallet, sampleBlock)`:
-            //    a cache hit short-circuits the chain read for a flood of fresh-signed bundles from
-            //    the same wallet, whether it is ineligible (`0n`, a `reject`) or eligible (`> 0n`,
-            //    re-signing / cycling choices within one bucket).
+            // 3. Gate (chain) — the rule scores this wallet, reading and memoizing however it
+            //    sees fit. The bundle's bucketized sample block is handed over as the pinned
+            //    block the ballot names; a rule scoring current state ignores it for `ctx.head`.
             const sampleBlock = bucketMath.sampleBlockForBucket(bucketMath.bucketForBlock(bundle.blockNumber));
-            let score = await gateResultCache?.get(bundle.address, sampleBlock);
-            if (score === undefined) {
-                ({ score } = await rule.evaluate({
-                    options: ruleOptions,
-                    walletAddress: bundle.address,
-                    ctx: { chain: ruleChain, blockNumber: sampleBlock }
-                }));
-                gateResultCache?.set(bundle.address, sampleBlock, score);
-            }
+            const { score, penalize } = await rule.evaluate({
+                options: ruleOptions,
+                wallet: { address: bundle.address, sampleBlock },
+                ctx
+            });
             if (score === 0n) {
-                return { valid: false, disposition: "reject", reason: `not admitted: rule score is 0n at block ${sampleBlock}` };
+                // Disposition comes from the rule's own answer, never from the rule's identity.
+                // A `0n` the rule stands behind is identical on every honest verifier, so it is a
+                // `reject`: the sender is penalized and the verdict cached as terminal. A `0n` it
+                // will not blame anyone for — the rule read this verifier's head, where my view
+                // and yours legitimately differ — drops the bundle just the same but stays
+                // `ignore`-class: no penalty for a relayer that saw a fresher chain, and
+                // uncached, so it is re-judged rather than frozen (the same treatment community
+                // name resolution has always had, step 4 below).
+                return {
+                    valid: false,
+                    disposition: penalize === false ? "ignore" : "reject",
+                    reason: `not admitted: rule score is 0n`
+                };
             }
             // 4. Community-name resolution (network) — a carried name is a claim, verified against
             //    the registry. A name that has no resolver, does not resolve, or resolves to a

package/dist/verify/gate-grace.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What the pipeline does with a gate score of `0n` that the rule declined to blame on anyone
+ * (`RuleResult.penalize: false` — see rules/types.ts).
+ *
+ * These two numbers are pipeline policy, not rule policy, which is why they live here: they are
+ * about how long the library is willing to hold an unsettled bundle in its own working set, not
+ * about how any rule reads the chain. What the rule owns — which block it scores at and how long
+ * it memoizes the answer — lives in the rule (see rules/cache.ts).
+ */
+/**
+ * How long the background verifier keeps a provisionally-admitted bundle whose gate scored `0n`
+ * without blaming anyone, before giving up on it.
+ *
+ * An unattributable `0n` means "not yet", not "no": the wallet may have acquired the gate asset
+ * in a block this verifier has not seen, or may acquire it seconds from now (a client that signs
+ * its ballot the instant it mints races its own transaction). Evicting immediately would make
+ * whether a vote counts depend on whose RPC was a few blocks ahead. Retrying forever is the other
+ * failure — a never-holder's bundles would pend until they expire, which is memory a spammer
+ * chooses. So: re-examine within a grace window, then evict `ignore`-class (uncached, so a later
+ * re-publish is judged fresh rather than inheriting this verdict).
+ */
+export declare const GATE_GRACE_MS = 120000;
+/**
+ * How often a still-`0n` bundle is re-examined inside the grace window.
+ *
+ * Cheap by design: the rule memoizes its own reads under its own epoch (rules/cache.ts), so a
+ * re-examination whose epoch has not rolled costs no chain work at all. The real cost is one
+ * batched read per rule epoch, no matter how many bundles are pending or how often this fires —
+ * which is also why the grace window must be comfortably longer than the rule's epoch, or the
+ * retries would never see a fresh read.
+ */
+export declare const GATE_RETRY_MS = 10000;

package/dist/verify/gate-grace.js

@@ -0,0 +1,32 @@
+/**
+ * What the pipeline does with a gate score of `0n` that the rule declined to blame on anyone
+ * (`RuleResult.penalize: false` — see rules/types.ts).
+ *
+ * These two numbers are pipeline policy, not rule policy, which is why they live here: they are
+ * about how long the library is willing to hold an unsettled bundle in its own working set, not
+ * about how any rule reads the chain. What the rule owns — which block it scores at and how long
+ * it memoizes the answer — lives in the rule (see rules/cache.ts).
+ */
+/**
+ * How long the background verifier keeps a provisionally-admitted bundle whose gate scored `0n`
+ * without blaming anyone, before giving up on it.
+ *
+ * An unattributable `0n` means "not yet", not "no": the wallet may have acquired the gate asset
+ * in a block this verifier has not seen, or may acquire it seconds from now (a client that signs
+ * its ballot the instant it mints races its own transaction). Evicting immediately would make
+ * whether a vote counts depend on whose RPC was a few blocks ahead. Retrying forever is the other
+ * failure — a never-holder's bundles would pend until they expire, which is memory a spammer
+ * chooses. So: re-examine within a grace window, then evict `ignore`-class (uncached, so a later
+ * re-publish is judged fresh rather than inheriting this verdict).
+ */
+export const GATE_GRACE_MS = 120_000;
+/**
+ * How often a still-`0n` bundle is re-examined inside the grace window.
+ *
+ * Cheap by design: the rule memoizes its own reads under its own epoch (rules/cache.ts), so a
+ * re-examination whose epoch has not rolled costs no chain work at all. The real cost is one
+ * batched read per rule epoch, no matter how many bundles are pending or how often this fires —
+ * which is also why the grace window must be comfortably longer than the rule's epoch, or the
+ * retries would never see a fresh read.
+ */
+export const GATE_RETRY_MS = 10_000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitsocial/pubsub-voting",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Trustless pubsub voting over a shared libp2p/Helia node.",
   "type": "module",
   "license": "GPL-3.0-or-later",
@@ -25,6 +25,7 @@
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "typecheck:examples": "tsc -p tsconfig.examples.json --noEmit",
+    "typecheck:bench": "npm run build && tsc -p benchmark/tsconfig.json --noEmit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",

package/dist/verify/gate-result-cache.d.ts

@@ -1,65 +0,0 @@
-import type { LruStorage } from "../storage/types.js";
-/**
- * A bounded cache of gate `rule` results, keyed by `(wallet, sampleBlock)`.
- *
- * The gate score is a pure function of *historical* chain state — a past, pinned block that never
- * changes — so a novel bundle CID from the same wallet at the same sample block scores identically
- * and need not repeat the chain read. Memoizing the score (a `bigint`, where `0n` is the "not
- * admitted" case) bounds the "one gate read per unique bundle" RPC amplifier (see DESIGN.md
- * "Transport", resource-exhaustion residual) for BOTH directions:
- *
- *   - an ineligible wallet minting fresh-signed bundles pays a single chain read per bucket, not
- *     one per bundle (the `0n` case — the former negative cache); and
- *   - an *eligible* wallet re-signing / cycling vote choices within a bucket likewise pays one read
- *     per bucket, not one per fresh CID (the `> 0n` case).
- *
- * Keyed on `(wallet, sampleBlock)` — NOT wallet alone — so a wallet whose holding *changes* in a
- * later bucket is re-read at that bucket's sample block rather than being pinned to a stale score.
- *
- * `get` is async because the cache may be backed by the voter's persistent store (sqlite /
- * IndexedDB — see {@link makePersistentGateResultCache}); `set` returns immediately and lets any
- * persistence settle in the background, so the verify hot path never waits on a cache write.
- *
- * This is the per-CID verdict cache's complement: the verdict cache dedupes *re-announcements of the
- * same bundle*; this dedupes *distinct bundles that share a `(wallet, bucket)` gate result*.
- */
-export interface GateResultCache {
-    /** The memoized gate score for `(wallet, sampleBlock)`, or `undefined` if not yet read. */
-    get(wallet: string, sampleBlock: number): Promise<bigint | undefined>;
-    /** Memoize `(wallet, sampleBlock) -> score` (idempotent; evicts oldest past the cap). */
-    set(wallet: string, sampleBlock: number, score: bigint): void;
-}
-/**
- * An in-memory {@link GateResultCache} bounded to `maxEntries` with FIFO eviction. Eviction is
- * safe because a score is deterministic — an evicted entry only ever costs a re-read, never a
- * wrong answer; without a bound, a flood of fresh wallets is a memory-exhaustion vector (see
- * DESIGN.md "Can valid votes clog the topic?").
- */
-export declare function makeGateResultCache(maxEntries?: number): GateResultCache;
-/**
- * A {@link GateResultCache} layered over the voter's persistent store: an in-memory FIFO front
- * (the hot path — steady-state gossip hits it synchronously) with read-through to the store on
- * a miss and fire-and-forget write-through on `set`. Scores travel as decimal strings (JSON has
- * no bigint). A broken store read or write degrades to a live chain read — never an error into
- * the verify pipeline — because everything here is a pure function of pinned historical state.
- */
-export declare function makePersistentGateResultCache(opts: {
-    store: LruStorage;
-    /** Identifies the gate rule (hash of the canonical criteria `rule` + chainId — see voter.ts). */
-    ruleHash: string;
-    maxMemEntries?: number;
-}): GateResultCache;
-/**
- * Deterministic expiry purge for one rule's persisted gate results — better than LRU here
- * because staleness is *provable*: a score at bucket B's sample block is only ever consulted
- * while bundles from B are admissible (within `voteExpiryBuckets` of head), so anything older
- * than the oldest admissible sample block can never be read again. Run per contest whenever a
- * head read advances the expiry boundary (see the engine's `#maybePurgeGateResults`); the
- * store's LRU bound stays as the backstop for rules never purged.
- */
-export declare function purgeExpiredGateResults(opts: {
-    store: LruStorage;
-    ruleHash: string;
-    /** The oldest admissible bucket's sample block; strictly older entries are dead. */
-    oldestSampleBlock: number;
-}): Promise<void>;