@bitsocial/pubsub-voting 0.0.6

package/dist/verify/background.js

@@ -0,0 +1,236 @@
+import { tickerForRef } from "../chain/ticker.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 retryBaseMs = deps.retryBaseMs ?? RETRY_BASE_MS;
+    const retryCapMs = deps.retryCapMs ?? RETRY_CAP_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];
+    if (!maybeRule)
+        throw new UnknownRuleError("rule", criteria.rule.type);
+    const rule = maybeRule;
+    const ruleOptions = rule.optionsSchema.parse(criteria.rule);
+    const ruleChain = chainFor(tickerForRef(criteria, criteria.rule, ruleOptions));
+    const queue = [];
+    /** CIDs queued or in-flight, so a re-chased root cannot double-verify a bundle. */
+    const inFlight = new Set();
+    let draining = false;
+    let stopped = false;
+    /** Consecutive infra-failed rounds, driving the backoff exponent. */
+    let failedRounds = 0;
+    let retryTimer;
+    const idleResolvers = [];
+    function settle(item) {
+        inFlight.delete(item.cid.toString());
+    }
+    function maybeResolveIdle() {
+        if (queue.length === 0 && !draining && retryTimer === undefined) {
+            for (const resolve of idleResolvers.splice(0))
+                resolve();
+        }
+    }
+    /** The wallet's gate score at its bundle's bucket sample block. */
+    function sampleBlockFor(bundle) {
+        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.
+     */
+    async function gateStage(items) {
+        const groups = new Map();
+        for (const item of items) {
+            if (item.gateDone)
+                continue;
+            const block = sampleBlockFor(item.bundle);
+            groups.set(block, [...(groups.get(block) ?? []), item]);
+        }
+        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;
+            }
+        }
+    }
+    /**
+     * Settle one gate-passed item's name checks. Resolutions are deduped per round via
+     * `resolutions`. Returns "verified" | "evicted"; throws on a resolver infra failure
+     * (the caller re-queues the item — its `gateDone` survives, so only names re-run).
+     */
+    async function nameStage(item, resolutions) {
+        for (const v of item.bundle.votes) {
+            const name = v.community.name;
+            if (!name || item.resolvedNames[name])
+                continue;
+            const resolver = nameResolvers.find((r) => r.canResolve({ name }));
+            if (!resolver) {
+                // `ignore`-class, view-dependent (a missing resolver differs per verifier) — evict,
+                // never cache (see verify/bundle.ts step 4).
+                deps.onEvict(item.cid, { valid: false, disposition: "ignore", reason: `no resolver handles community name "${name}"` });
+                return "evicted";
+            }
+            let resolution = resolutions.get(name);
+            if (!resolution) {
+                resolution = limit(() => resolveNameThroughCache({ resolver, name, cache: nameResolutionCache }));
+                resolutions.set(name, resolution);
+            }
+            const record = await resolution;
+            if (!record) {
+                deps.onEvict(item.cid, { valid: false, disposition: "ignore", reason: `community name "${name}" does not resolve` });
+                return "evicted";
+            }
+            if (record.publicKey !== v.community.publicKey) {
+                deps.onEvict(item.cid, {
+                    valid: false,
+                    disposition: "ignore",
+                    reason: `community name "${name}" resolves to ${record.publicKey}, not the claimed ${v.community.publicKey}`
+                });
+                return "evicted";
+            }
+            item.resolvedNames[name] = record.publicKey;
+        }
+        return "verified";
+    }
+    /** One drain round over everything currently queued. Re-queues + backs off on infra failure. */
+    async function round() {
+        const batch = queue.splice(0);
+        const requeue = [];
+        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.
+        try {
+            await gateStage(batch);
+        }
+        catch (error) {
+            infraError = error;
+        }
+        const resolutions = new Map();
+        for (const item of batch) {
+            if (!item.gateDone) {
+                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.
+                const verdict = {
+                    valid: false,
+                    disposition: "reject",
+                    reason: `not admitted: rule score is 0n at block ${sampleBlockFor(item.bundle)}`
+                };
+                cache.set(item.cid, verdict);
+                deps.onEvict(item.cid, verdict);
+                settle(item);
+                continue;
+            }
+            if (!item.gateNotified) {
+                item.gateNotified = true;
+                deps.onGateVerified(item.cid);
+            }
+            try {
+                if ((await nameStage(item, resolutions)) === "evicted") {
+                    settle(item);
+                    continue;
+                }
+            }
+            catch (error) {
+                infraError = error;
+                requeue.push(item); // gateDone survives — the retry only re-runs names
+                continue;
+            }
+            if (item.bundle.votes.some((v) => v.community.name))
+                deps.onNameResolved(item.cid);
+            // Fully settled: store the terminal valid verdict (same shape the forward-gate caches).
+            cache.set(item.cid, { valid: true, ruleScore: item.ruleScore, resolvedNames: item.resolvedNames });
+            settle(item);
+        }
+        if (requeue.length > 0) {
+            queue.push(...requeue);
+            failedRounds += 1;
+            deps.onError(infraError);
+            armRetry();
+        }
+        else {
+            failedRounds = 0;
+        }
+    }
+    function armRetry() {
+        if (stopped || retryTimer !== undefined)
+            return;
+        const ceiling = Math.min(retryCapMs, retryBaseMs * 2 ** (failedRounds - 1));
+        const timer = setTimeout(() => {
+            retryTimer = undefined;
+            kickDrain();
+        }, Math.random() * ceiling);
+        timer.unref?.();
+        retryTimer = timer;
+    }
+    function kickDrain() {
+        if (draining || stopped || queue.length === 0) {
+            maybeResolveIdle();
+            return;
+        }
+        draining = true;
+        void (async () => {
+            try {
+                // A round that infra-fails re-queues and arms the retry timer instead of spinning.
+                while (queue.length > 0 && !stopped && retryTimer === undefined)
+                    await round();
+            }
+            finally {
+                draining = false;
+                maybeResolveIdle();
+            }
+        })();
+    }
+    return {
+        enqueue(entries) {
+            for (const entry of entries) {
+                const key = entry.cid.toString();
+                if (inFlight.has(key))
+                    continue;
+                inFlight.add(key);
+                queue.push({ ...entry, gateDone: false, gateNotified: false, ruleScore: 0n, resolvedNames: {} });
+            }
+            kickDrain();
+        },
+        pendingCount() {
+            return inFlight.size;
+        },
+        idle() {
+            if (queue.length === 0 && !draining && retryTimer === undefined)
+                return Promise.resolve();
+            return new Promise((resolve) => idleResolvers.push(resolve));
+        },
+        stop() {
+            stopped = true;
+            if (retryTimer !== undefined)
+                clearTimeout(retryTimer);
+            retryTimer = undefined;
+            maybeResolveIdle();
+        },
+        resume() {
+            stopped = false;
+            kickDrain();
+        }
+    };
+}

package/dist/verify/bundle.d.ts

@@ -0,0 +1,58 @@
+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 NameResolutionCache } from "./name-resolution-cache.js";
+import type { BundleVerifier } from "./types.js";
+/**
+ * The full validity pipeline for one bundle — the work the gossip forward-gate runs before
+ * re-forwarding (see DESIGN.md "Transport"). Cheap-to-expensive with early exit so the
+ * costly network/chain steps only run for genuinely-new, signature-valid bundles:
+ *
+ *   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.
+ *   4. name        (network):   each vote's `community.name` (if any) must resolve to the
+ *                               claimed `publicKey`; a squatted/absent name drops the bundle.
+ *
+ * Every step only ever SUBTRACTS trust (a bundle is valid or dropped), which is what lets the
+ * gate reject without forwarding. Weight *magnitude* is not computed here — it is a ranking
+ * concern the tally derives lazily, not a validity concern (see DESIGN.md "Tally").
+ *
+ * Expiry is deliberately out of scope here: it depends on the current bucket (a clock), so it
+ * is enforced by the CRDT's read-time filter (`current` drops decayed votes given the
+ * current bucket; `prune` bounds memory), not by this time-independent verifier.
+ */
+/** Everything the verifier needs, resolved once per contest. */
+export interface BundleVerifierDeps {
+    criteria: Criteria;
+    /** The criteria document's CID bytes (`(await criteriaCid(criteria)).bytes`) — signature binding. */
+    criteriaCid: Uint8Array;
+    /** The rule chain's numeric chainId (bound in the ballot domain). */
+    chainId: number;
+    /** Resolved rule registry (built-ins + host overrides). */
+    registry: RuleRegistry;
+    /** Resolve a chain ticker (e.g. "base") to its viem client. */
+    chainFor: (ticker: string) => ChainClient;
+    /** Bucket math for `criteria.blocksPerBucket`. */
+    bucketMath: BucketMath;
+    /** 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).
+     */
+    gateResultCache?: GateResultCache;
+    /**
+     * 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
+     * once per {@link NAME_RESOLUTION_MAX_AGE_SECONDS} per resolver. Omitted ⇒ every verify
+     * resolves live (prior behaviour; unit tests).
+     */
+    nameResolutionCache?: NameResolutionCache;
+}
+export declare function makeBundleVerifier(deps: BundleVerifierDeps): BundleVerifier;

package/dist/verify/bundle.js

@@ -0,0 +1,84 @@
+import { tickerForRef } from "../chain/ticker.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 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));
+    // 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.
+        const signature = await verifyBundleSignature({ bundle, criteriaCid, chainId });
+        if (!signature.valid)
+            return signature;
+        // 2. Criteria constraints (free) — cap + vote range.
+        return checkBundleConstraints(bundle, criteria);
+    };
+    return {
+        verifyOffline,
+        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).
+            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}` };
+            }
+            // 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
+            //    different publicKey than the vote claims drops the whole bundle. These failures
+            //    are `ignore`, not `reject`: v1 resolves at head, so they are view-/clock-dependent
+            //    (a missing resolver differs per verifier; a re-point produces a transient window
+            //    where honest peers disagree — see DESIGN.md "Tally"/"Open questions"). Penalizing
+            //    the sender for that would punish honest relayers; the drop still stops propagation.
+            //    (Once pinned-block resolution lands, a steady-state mismatch becomes provable
+            //    `reject`.) The gossip gate therefore does NOT cache these verdicts. Successful
+            //    resolutions DO go through the shared name-resolution cache (the pkc-js rule,
+            //    1-hour max-age) — bounding the RPC cost, while a re-point is still honored
+            //    within the hour and a failed resolution is never negatively cached.
+            const resolvedNames = {};
+            for (const v of bundle.votes) {
+                const name = v.community.name;
+                if (!name)
+                    continue;
+                const resolver = nameResolvers.find((r) => r.canResolve({ name }));
+                if (!resolver)
+                    return { valid: false, disposition: "ignore", reason: `no resolver handles community name "${name}"` };
+                const record = await resolveNameThroughCache({ resolver, name, cache: nameResolutionCache });
+                if (!record)
+                    return { valid: false, disposition: "ignore", reason: `community name "${name}" does not resolve` };
+                if (record.publicKey !== v.community.publicKey) {
+                    return {
+                        valid: false,
+                        disposition: "ignore",
+                        reason: `community name "${name}" resolves to ${record.publicKey}, not the claimed ${v.community.publicKey}`
+                    };
+                }
+                resolvedNames[name] = record.publicKey;
+            }
+            return { valid: true, ruleScore: score, resolvedNames };
+        }
+    };
+}

package/dist/verify/cache.d.ts

@@ -0,0 +1,48 @@
+import type { CID } from "multiformats/cid";
+import type { VotesBundle } from "../schema/votes.js";
+import type { BundleVerifier, BundleVerdict } from "./types.js";
+/**
+ * Per-CID verdict cache. A bundle is immutable and content-addressed, and its verdict
+ * (signature + constraints + gate-at-bucket-block + name resolution) is deterministic,
+ * so it is computed once and reused. This is the lever that keeps the forward-gate cheap:
+ * steady-state gossip re-announces already-known bundle CIDs, so the same bundle CID would
+ * otherwise be re-verified once per gossiping peer. See DESIGN.md "Transport" ("verdict cache").
+ */
+export interface VerdictCache {
+    get(cid: CID): BundleVerdict | undefined;
+    set(cid: CID, verdict: BundleVerdict): void;
+    has(cid: CID): boolean;
+}
+/**
+ * Only *terminal* verdicts may be cached: an `accept`, or a `reject` that is a pure function
+ * of the bundle bytes + pinned historical chain state (bad signature, gate miss, ...). A
+ * transient `ignore` (name resolved at head during a re-point window, a `blockNumber` bucket
+ * ahead of this verifier's head) is view-/clock-dependent and can change as heads/records
+ * converge, so caching it would wrongly pin a stale verdict. See DESIGN.md "Transport"
+ * ("verdict cache") and verify/types.ts `VerdictDisposition`.
+ */
+export declare function isCacheableVerdict(verdict: BundleVerdict): boolean;
+/**
+ * An in-memory verdict cache keyed by the CID's canonical string, bounded to `maxEntries` with
+ * FIFO eviction (same pattern as `makeGateResultCache` / `makeAcceptedDedup`). Without a bound the
+ * `Map` grows one entry per novel CID forever: an ineligible wallet (or a flood of fresh wallets)
+ * minting fresh-signed bundles yields a distinct provable-`reject` per CID, so an unbounded cache is
+ * a memory-exhaustion vector (see DESIGN.md "Can valid votes clog the topic?"). Eviction is safe
+ * because a cached verdict is *terminal* and deterministic — an evicted entry only costs a re-fetch
+ * + re-verify on the next re-announce, never a wrong answer, and the `(wallet, sampleBlock)`
+ * gate-result cache still short-circuits the chain read so that recomputation stays cheap.
+ */
+export declare function makeVerdictCache(maxEntries?: number): VerdictCache;
+/** A verifier addressed by CID, memoizing verdicts through a {@link VerdictCache}. */
+export interface CachingBundleVerifier {
+    verify(cid: CID, bundle: VotesBundle): Promise<BundleVerdict>;
+}
+/**
+ * Wrap a {@link BundleVerifier} with a {@link VerdictCache}: a CID already seen returns its
+ * cached verdict without touching the chain or the network; a new CID runs the full pipeline
+ * once and stores the result — but only if it is terminal ({@link isCacheableVerdict}): a
+ * valid bundle or a provable `reject` is remembered (a known-bad bundle is not re-fetched or
+ * re-checked), while a transient `ignore` is re-evaluated next time so a stale head/record
+ * cannot pin it.
+ */
+export declare function makeCachingVerifier(verifier: BundleVerifier, cache: VerdictCache): CachingBundleVerifier;

package/dist/verify/cache.js

@@ -0,0 +1,62 @@
+/**
+ * Only *terminal* verdicts may be cached: an `accept`, or a `reject` that is a pure function
+ * of the bundle bytes + pinned historical chain state (bad signature, gate miss, ...). A
+ * transient `ignore` (name resolved at head during a re-point window, a `blockNumber` bucket
+ * ahead of this verifier's head) is view-/clock-dependent and can change as heads/records
+ * converge, so caching it would wrongly pin a stale verdict. See DESIGN.md "Transport"
+ * ("verdict cache") and verify/types.ts `VerdictDisposition`.
+ */
+export function isCacheableVerdict(verdict) {
+    return verdict.valid || verdict.disposition === "reject";
+}
+/**
+ * An in-memory verdict cache keyed by the CID's canonical string, bounded to `maxEntries` with
+ * FIFO eviction (same pattern as `makeGateResultCache` / `makeAcceptedDedup`). Without a bound the
+ * `Map` grows one entry per novel CID forever: an ineligible wallet (or a flood of fresh wallets)
+ * minting fresh-signed bundles yields a distinct provable-`reject` per CID, so an unbounded cache is
+ * a memory-exhaustion vector (see DESIGN.md "Can valid votes clog the topic?"). Eviction is safe
+ * because a cached verdict is *terminal* and deterministic — an evicted entry only costs a re-fetch
+ * + re-verify on the next re-announce, never a wrong answer, and the `(wallet, sampleBlock)`
+ * gate-result cache still short-circuits the chain read so that recomputation stays cheap.
+ */
+export function makeVerdictCache(maxEntries = 4096) {
+    const byCid = new Map();
+    const order = [];
+    return {
+        get: (cid) => byCid.get(cid.toString()),
+        set: (cid, verdict) => {
+            const k = cid.toString();
+            if (byCid.has(k))
+                return; // idempotent: a terminal verdict never changes, so keep FIFO position
+            byCid.set(k, verdict);
+            order.push(k);
+            if (order.length > maxEntries) {
+                const evicted = order.shift();
+                if (evicted !== undefined)
+                    byCid.delete(evicted);
+            }
+        },
+        has: (cid) => byCid.has(cid.toString())
+    };
+}
+/**
+ * Wrap a {@link BundleVerifier} with a {@link VerdictCache}: a CID already seen returns its
+ * cached verdict without touching the chain or the network; a new CID runs the full pipeline
+ * once and stores the result — but only if it is terminal ({@link isCacheableVerdict}): a
+ * valid bundle or a provable `reject` is remembered (a known-bad bundle is not re-fetched or
+ * re-checked), while a transient `ignore` is re-evaluated next time so a stale head/record
+ * cannot pin it.
+ */
+export function makeCachingVerifier(verifier, cache) {
+    return {
+        async verify(cid, bundle) {
+            const cached = cache.get(cid);
+            if (cached)
+                return cached;
+            const verdict = await verifier.verify(bundle);
+            if (isCacheableVerdict(verdict))
+                cache.set(cid, verdict);
+            return verdict;
+        }
+    };
+}

package/dist/verify/constraints.d.ts

@@ -0,0 +1,16 @@
+import type { VotesBundle } from "../schema/votes.js";
+import type { Criteria } from "../schema/criteria.js";
+import type { VerifyResult } from "./types.js";
+/**
+ * Offline verify stage 1, constraints half: the criteria-bound checks that gate a bundle
+ * before any signature recovery or chain read — `votes.length <= criteria.maxVotesPerAddress`
+ * and each `vote` within `criteria.voteSchema` (see verify/types.ts stage 1).
+ *
+ * Pure and synchronous: no signature recovery, no chain. These bounds live in the
+ * *criteria*, not in the wire type, which is exactly why `VotesBundleSchema` does NOT
+ * enforce them — the schema owns only criteria-independent wire shape (pairwise-distinct
+ * communities). This runtime check is where the cap belongs. See DESIGN.md "Votes wire".
+ *
+ * An empty `votes` array (withdrawal/abstention) is always valid regardless of the cap.
+ */
+export declare function checkBundleConstraints(bundle: VotesBundle, criteria: Criteria): VerifyResult;

package/dist/verify/constraints.js

@@ -0,0 +1,35 @@
+/**
+ * Offline verify stage 1, constraints half: the criteria-bound checks that gate a bundle
+ * before any signature recovery or chain read — `votes.length <= criteria.maxVotesPerAddress`
+ * and each `vote` within `criteria.voteSchema` (see verify/types.ts stage 1).
+ *
+ * Pure and synchronous: no signature recovery, no chain. These bounds live in the
+ * *criteria*, not in the wire type, which is exactly why `VotesBundleSchema` does NOT
+ * enforce them — the schema owns only criteria-independent wire shape (pairwise-distinct
+ * communities). This runtime check is where the cap belongs. See DESIGN.md "Votes wire".
+ *
+ * An empty `votes` array (withdrawal/abstention) is always valid regardless of the cap.
+ */
+export function checkBundleConstraints(bundle, criteria) {
+    // Withdrawal/abstention: the empty bundle is always legal, cap and range notwithstanding.
+    if (bundle.votes.length === 0)
+        return { valid: true };
+    if (bundle.votes.length > criteria.maxVotesPerAddress) {
+        return {
+            valid: false,
+            disposition: "reject",
+            reason: `votes.length ${bundle.votes.length} exceeds maxVotesPerAddress ${criteria.maxVotesPerAddress}`
+        };
+    }
+    const { min, max } = criteria.voteSchema;
+    for (const v of bundle.votes) {
+        if (v.vote < min || v.vote > max) {
+            return {
+                valid: false,
+                disposition: "reject",
+                reason: `vote ${v.vote} for community ${v.community.publicKey} is outside voteSchema [${min}, ${max}]`
+            };
+        }
+    }
+    return { valid: true };
+}

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

@@ -0,0 +1,65 @@
+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>;