@bitsocial/pubsub-voting 0.2.1 → 0.4.0

package/dist/verify/background.js

@@ -1,12 +1,17 @@
 import { tickerForRef } from "../chain/ticker.js";
+import { makeMemoryRuleCache } from "../rules/cache.js";
+import { GATE_GRACE_MS, GATE_RETRY_MS } from "./gate-grace.js";
+import { gateFailure, scoreOrZero } from "../rules/result.js";
 import { UnknownRuleError } from "../errors.js";
 import { 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 +20,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 +49,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.gateFailed = gateFailure(result);
+            item.ruleScore = scoreOrZero(result);
+            item.gateDone = true;
         }
     }
     /**
@@ -115,6 +127,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.
@@ -130,14 +144,38 @@ export function makeBackgroundVerifier(deps) {
                 requeue.push(item); // gate read never happened (infra) — retry the whole item
                 continue;
             }
-            if (item.ruleScore === 0n) {
-                // Provable, deterministic reject — safe to cache so a re-publish short-circuits.
+            if (item.gateFailed) {
+                if (item.gateFailed.penalize) {
+                    // Provable, deterministic reject — safe to cache so a re-publish short-circuits.
+                    const verdict = {
+                        valid: false,
+                        disposition: "reject",
+                        reason: `not admitted: ${item.gateFailed.error}`
+                    };
+                    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):
+                // the failure means "not yet", not "no". The wallet may have acquired the asset in
+                // a block this verifier has not seen, or may acquire it a moment from now — a
+                // client that signs the instant it mints races its own transaction. Evicting here
+                // 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: ${item.gateFailed.error} (still true after the grace window)`
                 };
-                cache.set(item.cid, verdict);
                 deps.onEvict(item.cid, verdict);
                 settle(item);
                 continue;
@@ -164,23 +202,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 +256,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,
+                    gateFailed: undefined,
+                    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,11 @@ 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` must return `success: true`, at whichever block the
+ *                               rule itself reads (rules/types.ts). A failure -> not admitted ->
+ *                               drop, as a `reject` when the rule blames the sender for it and an
+ *                               `ignore` when it does not, carrying the rule's own `error` text
+ *                               as the verdict reason so the voter is told what actually failed.
  *   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 +43,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,27 @@
 import { tickerForRef } from "../chain/ticker.js";
+import { makeMemoryRuleCache } from "../rules/cache.js";
+import { gateFailure, scoreOrZero } from "../rules/result.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.
@@ -24,27 +33,42 @@ export function makeBundleVerifier(deps) {
     };
     return {
         verifyOffline,
+        // The gate step on its own, against the SAME rule/options/ctx `verify` uses below — which
+        // is the entire value of exposing it: a caller asking "would this wallet's vote count?"
+        // can never drift from what the gate actually does.
+        checkGate: ({ address, sampleBlock }) => rule.evaluate({ options: ruleOptions, wallet: { address, sampleBlock }, ctx }),
         async verify(bundle) {
             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);
-            }
-            if (score === 0n) {
-                return { valid: false, disposition: "reject", reason: `not admitted: rule score is 0n at block ${sampleBlock}` };
+            const gate = await rule.evaluate({
+                options: ruleOptions,
+                wallet: { address: bundle.address, sampleBlock },
+                ctx
+            });
+            const gateFailed = gateFailure(gate);
+            if (gateFailed) {
+                // Disposition comes from the rule's own answer, never from the rule's identity.
+                // A failure 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. One 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).
+                //
+                // The reason is the RULE's wording, verbatim: only it knows whether this wallet
+                // holds too few, holds none, or faces a contract that gates nothing, and that
+                // sentence is what reaches the voter through `VoteEvictedError`.
+                return {
+                    valid: false,
+                    disposition: gateFailed.penalize ? "reject" : "ignore",
+                    reason: `not admitted: ${gateFailed.error}`
+                };
             }
             // 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
@@ -78,7 +102,7 @@ export function makeBundleVerifier(deps) {
                 }
                 resolvedNames[name] = record.publicKey;
             }
-            return { valid: true, ruleScore: score, resolvedNames };
+            return { valid: true, ruleScore: scoreOrZero(gate), resolvedNames };
         }
     };
 }

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/dist/verify/types.d.ts

@@ -1,4 +1,5 @@
 import type { VotesBundle } from "../schema/votes.js";
+import type { RuleResult } from "../rules/types.js";
 /**
  * Verification interfaces, design only.
  *
@@ -83,6 +84,19 @@ export interface BundleVerifier {
      * DESIGN.md "Background chain verification").
      */
     verifyOffline(bundle: VotesBundle): Promise<VerifyResult>;
+    /**
+     * Step 3 alone, for a wallet rather than a bundle: run the gate rule and hand back its raw
+     * {@link RuleResult}. Backs `Contest.checkEligibility`, so a client can ask "would this vote
+     * count?" through the very same rule instance, options, chain client, head reader and memo
+     * the forward gate uses — never a reimplementation of them.
+     *
+     * `sampleBlock` is the pinned block the prospective ballot would name (the caller's current
+     * bucket). A head-scoring rule ignores it exactly as it does during verification.
+     */
+    checkGate(args: {
+        address: string;
+        sampleBlock: number;
+    }): Promise<RuleResult>;
 }
 /**
  * The per-bundle record of the two deferred *network* checks. The offline checks (signature,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitsocial/pubsub-voting",
-  "version": "0.2.1",
+  "version": "0.4.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>;

package/dist/verify/gate-result-cache.js

@@ -1,91 +0,0 @@
-const memKeyFor = (wallet, sampleBlock) => `${wallet.toLowerCase()}:${sampleBlock}`;
-/**
- * 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 function makeGateResultCache(maxEntries = 4096) {
-    const byKey = new Map();
-    const order = [];
-    return {
-        get: async (wallet, sampleBlock) => byKey.get(memKeyFor(wallet, sampleBlock)),
-        set: (wallet, sampleBlock, score) => {
-            const k = memKeyFor(wallet, sampleBlock);
-            if (byKey.has(k))
-                return; // idempotent: never refresh position or overwrite a pinned score
-            byKey.set(k, score);
-            order.push(k);
-            if (order.length > maxEntries) {
-                const evicted = order.shift();
-                if (evicted !== undefined)
-                    byKey.delete(evicted);
-            }
-        }
-    };
-}
-/** The persistent gate store's key. `ruleHash` disambiguates: the shared store spans every
- * contest on the voter, and one wallet can hold different scores under different gate rules
- * (or the same rule at different chainIds). Same score under the same rule is what lets two
- * contests over one gate (a 5chan-style directory) share each other's reads. */
-const storeKeyFor = (ruleHash, wallet, sampleBlock) => `${ruleHash}:${wallet.toLowerCase()}:${sampleBlock}`;
-/**
- * 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 function makePersistentGateResultCache(opts) {
-    const { store, ruleHash } = opts;
-    const mem = makeGateResultCache(opts.maxMemEntries);
-    return {
-        async get(wallet, sampleBlock) {
-            const cached = await mem.get(wallet, sampleBlock);
-            if (cached !== undefined)
-                return cached;
-            let persisted;
-            try {
-                persisted = await store.getItem(storeKeyFor(ruleHash, wallet, sampleBlock));
-            }
-            catch {
-                return undefined;
-            }
-            if (typeof persisted !== "string" || !/^\d+$/.test(persisted))
-                return undefined;
-            const score = BigInt(persisted);
-            mem.set(wallet, sampleBlock, score);
-            return score;
-        },
-        set(wallet, sampleBlock, score) {
-            mem.set(wallet, sampleBlock, score);
-            void store.setItem(storeKeyFor(ruleHash, wallet, sampleBlock), score.toString()).catch(() => {
-                // a failed persist costs a future re-read, never a wrong answer
-            });
-        }
-    };
-}
-/**
- * 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 async function purgeExpiredGateResults(opts) {
-    const prefix = `${opts.ruleHash}:`;
-    try {
-        for (const key of await opts.store.keys()) {
-            if (!key.startsWith(prefix))
-                continue;
-            const sampleBlock = Number(key.slice(key.lastIndexOf(":") + 1));
-            if (Number.isFinite(sampleBlock) && sampleBlock < opts.oldestSampleBlock) {
-                await opts.store.removeItem(key);
-            }
-        }
-    }
-    catch {
-        // purge is best-effort; the store's LRU bound is the correctness-free backstop
-    }
-}