@bitsocial/pubsub-votes 0.0.2

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>;

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

@@ -0,0 +1,91 @@
+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
+    }
+}

package/dist/verify/name-resolution-cache.d.ts

@@ -0,0 +1,59 @@
+import type { NameResolver } from "../chain/types.js";
+import type { LruStorage } from "../storage/types.js";
+/**
+ * Persistent cache of community-name resolutions, a port of pkc-js's `NameResolutionCache`
+ * (clients/name-resolution-cache.ts) — the SAME rule, so a host reasons about one caching
+ * policy across both libraries:
+ *
+ *   - LRU-bounded persistent store, no stored TTL: an entry lives until evicted.
+ *   - Freshness is a per-CALL max-age, modeled on HTTP `Cache-Control: max-age` (RFC 9111
+ *     §5.2.1.1): `maxAgeSeconds: 0` bypasses the cache, `N` serves an entry only while
+ *     `Date.now() - resolvedAtMs <= N * 1000`, `undefined` serves whatever is cached.
+ *   - Only SUCCESSFUL resolutions are stored; a name that fails to resolve is retried by the
+ *     caller, never negatively cached. No stale-while-revalidate.
+ *   - Keyed `{name}::{resolverKey}::{sha256(provider)}` — per resolver identity, because two
+ *     resolvers (or providers) may legitimately disagree during a migration.
+ *
+ * This cache exists because the host's own pkc-js instance caches at ITS call sites, not
+ * inside the injected resolver — so without this layer every verify here pays a live
+ * registry read that pkc-js would have served from cache.
+ */
+export interface NameResolutionCacheEntry {
+    publicKey: string;
+    resolverKey: string;
+    provider: string;
+    resolvedAtMs: number;
+}
+export interface NameResolutionCache {
+    get(args: {
+        name: string;
+        resolverKey: string;
+        provider: string;
+        maxAgeSeconds?: number;
+    }): Promise<NameResolutionCacheEntry | undefined>;
+    set(args: {
+        name: string;
+        resolverKey: string;
+        provider: string;
+        publicKey: string;
+    }): Promise<void>;
+}
+/**
+ * The verify pipeline's freshness bound, matching pkc-js's background resolution call site
+ * (`cache: { maxAge: 3600 }`): a re-pointed name is honored here within at most one hour.
+ * Names gate vote validity, so this is the staleness ceiling a community re-point can see.
+ */
+export declare const NAME_RESOLUTION_MAX_AGE_SECONDS = 3600;
+export declare function makeNameResolutionCache(store: LruStorage): NameResolutionCache;
+/**
+ * The verify pipeline's single resolution path (inline forward-gate AND background verifier):
+ * serve from the cache within {@link NAME_RESOLUTION_MAX_AGE_SECONDS}, otherwise resolve live
+ * and persist a success. `undefined` (no record) is returned uncached — the pkc-js rule.
+ */
+export declare function resolveNameThroughCache(opts: {
+    resolver: NameResolver;
+    name: string;
+    cache: NameResolutionCache | undefined;
+}): Promise<{
+    publicKey: string;
+} | undefined>;

package/dist/verify/name-resolution-cache.js

@@ -0,0 +1,64 @@
+import { sha256, stringToHex } from "viem";
+/**
+ * The verify pipeline's freshness bound, matching pkc-js's background resolution call site
+ * (`cache: { maxAge: 3600 }`): a re-pointed name is honored here within at most one hour.
+ * Names gate vote validity, so this is the staleness ceiling a community re-point can see.
+ */
+export const NAME_RESOLUTION_MAX_AGE_SECONDS = 3600;
+const keyFor = (args) => `${args.name}::${args.resolverKey}::${sha256(stringToHex(args.provider))}`;
+export function makeNameResolutionCache(store) {
+    return {
+        async get(args) {
+            if (args.maxAgeSeconds === 0)
+                return undefined;
+            let entry;
+            try {
+                entry = await store.getItem(keyFor(args));
+            }
+            catch {
+                return undefined; // a broken cache read degrades to a live resolution, never a failure
+            }
+            if (entry === null ||
+                typeof entry !== "object" ||
+                typeof entry.publicKey !== "string" ||
+                typeof entry.resolvedAtMs !== "number") {
+                return undefined;
+            }
+            const cached = entry;
+            if (typeof args.maxAgeSeconds === "number" && Date.now() - cached.resolvedAtMs > args.maxAgeSeconds * 1000) {
+                return undefined;
+            }
+            return cached;
+        },
+        async set(args) {
+            const entry = {
+                publicKey: args.publicKey,
+                resolverKey: args.resolverKey,
+                provider: args.provider,
+                resolvedAtMs: Date.now()
+            };
+            try {
+                await store.setItem(keyFor(args), entry);
+            }
+            catch {
+                // a failed cache write costs a future re-resolution, never a wrong answer
+            }
+        }
+    };
+}
+/**
+ * The verify pipeline's single resolution path (inline forward-gate AND background verifier):
+ * serve from the cache within {@link NAME_RESOLUTION_MAX_AGE_SECONDS}, otherwise resolve live
+ * and persist a success. `undefined` (no record) is returned uncached — the pkc-js rule.
+ */
+export async function resolveNameThroughCache(opts) {
+    const { resolver, name, cache } = opts;
+    const identity = { name, resolverKey: resolver.key, provider: resolver.provider };
+    const cached = await cache?.get({ ...identity, maxAgeSeconds: NAME_RESOLUTION_MAX_AGE_SECONDS });
+    if (cached)
+        return { publicKey: cached.publicKey };
+    const record = await resolver.resolve({ name });
+    if (record && cache)
+        await cache.set({ ...identity, publicKey: record.publicKey });
+    return record;
+}

package/dist/verify/signature.d.ts

@@ -0,0 +1,9 @@
+import type { VotesBundle } from "../schema/votes.js";
+import type { OfflineBundleVerifier, VerifyResult } from "./types.js";
+export declare function verifyBundleSignature(args: {
+    bundle: VotesBundle;
+    criteriaCid: Uint8Array;
+    chainId: number;
+}): Promise<VerifyResult>;
+/** The {@link OfflineBundleVerifier} seam, backed by {@link verifyBundleSignature}. */
+export declare const offlineBundleVerifier: OfflineBundleVerifier;

package/dist/verify/signature.js

@@ -0,0 +1,55 @@
+import { recoverTypedDataAddress } from "viem";
+import { ballotTypedData, EIP712_SIGNATURE_TYPE } from "../signer/eip712.js";
+/**
+ * Offline verify stage 1, signature half: recover the EIP-712 ballot signer and check it
+ * equals `bundle.address`. Pure and cheap (no chain read), so it runs first in the gate —
+ * a bad signature drops a vote before any fetch or chain work (see DESIGN.md "Transport").
+ *
+ * The recovered signer *is* the voter (there is no pkc-js author, no author->wallet
+ * binding). Rebuilding the typed data from the criteria CID bytes + chainId + the bundle's
+ * `votes`/`blockNumber` means a signature gathered for one contest, chain, or block cannot
+ * validate on another — the binding is in the hash, not in a trusted `address` field, so a
+ * forged `address` simply fails the recovery check here.
+ */
+/** True when `s` is `0x`-hex, narrowing it to viem's `Hex` without an `any` cast. */
+function isHex(s) {
+    return s.startsWith("0x");
+}
+export async function verifyBundleSignature(args) {
+    const { bundle, criteriaCid, chainId } = args;
+    if (bundle.signature.type !== EIP712_SIGNATURE_TYPE) {
+        return {
+            valid: false,
+            disposition: "reject",
+            reason: `unsupported signature type "${bundle.signature.type}" (expected "${EIP712_SIGNATURE_TYPE}")`
+        };
+    }
+    if (!isHex(bundle.signature.signature)) {
+        return { valid: false, disposition: "reject", reason: "signature is not 0x-hex" };
+    }
+    const typedData = ballotTypedData({
+        criteriaCid,
+        chainId,
+        votes: bundle.votes,
+        blockNumber: bundle.blockNumber
+    });
+    let recovered;
+    try {
+        recovered = await recoverTypedDataAddress({ ...typedData, signature: bundle.signature.signature });
+    }
+    catch (err) {
+        return { valid: false, disposition: "reject", reason: `signature does not recover: ${err.message}` };
+    }
+    // The recovered address is EIP-55 checksummed; `bundle.address` may be lowercase or
+    // differently cased. Compare case-insensitively.
+    if (recovered.toLowerCase() !== bundle.address.toLowerCase()) {
+        return {
+            valid: false,
+            disposition: "reject",
+            reason: `recovered signer ${recovered} does not match bundle.address ${bundle.address}`
+        };
+    }
+    return { valid: true };
+}
+/** The {@link OfflineBundleVerifier} seam, backed by {@link verifyBundleSignature}. */
+export const offlineBundleVerifier = { verifyBundleSignature };

package/dist/verify/types.d.ts

@@ -0,0 +1,101 @@
+import type { VotesBundle } from "../schema/votes.js";
+/**
+ * Verification interfaces, design only.
+ *
+ * Verification has one cheap, offline stage (no chain reads) and one chain stage:
+ *   1. offline: recover the EIP-712 signer and check it equals bundle.address, and the
+ *      criteria-bound constraints (votes.length <= maxVotesPerAddress, vote in range).
+ *      Pairwise-distinct community.publicKeys is enforced even earlier, by
+ *      VotesBundleSchema at parse time (see DESIGN.md "Votes wire")
+ *   2. chain: the `rule` (gate) + weight rules read state at the bucket block, and
+ *      each vote's community.name claim is resolved through the injected nameResolvers
+ *      (a name that does not resolve to the claimed publicKey drops the bundle)
+ *
+ * The tally runs stage 2 lazily (only where it can change the visible ranking), so the
+ * cheap offline check is split out and runs first — a bad signature drops a vote for zero
+ * chain reads. There is no separate wallet-binding stage: the single wallet signature is
+ * the identity. See DESIGN.md "Identity: the voting wallet, nothing else" and "Tally".
+ */
+/**
+ * How a failing verdict should be blamed, mirroring the gossip gate's `reject`/`ignore`
+ * split (see DESIGN.md "Transport"):
+ *   - "reject": PROVABLY invalid — a pure function of the bundle bytes and pinned historical
+ *     chain state (bad signature, out-of-range vote, wallet the gate rejects at the bucket
+ *     block). Deterministic and stable, so it is safe to penalize the sender AND to cache.
+ *   - "ignore": not provably the sender's fault because the check is view- or clock-dependent
+ *     and two honest peers can legitimately disagree right now (a `community.name` resolved *at
+ *     head* during a re-point window; a `blockNumber` bucket ahead of this verifier's chain
+ *     head). No penalty, and NOT cached — the verdict can change as heads/records converge.
+ */
+export type VerdictDisposition = "reject" | "ignore";
+export type VerifyOk = {
+    valid: true;
+};
+export type VerifyFail = {
+    valid: false;
+    disposition: VerdictDisposition;
+    reason: string;
+};
+export type VerifyResult = VerifyOk | VerifyFail;
+/** Stage 1: ballot signature only. No chain access. */
+export interface OfflineBundleVerifier {
+    /**
+     * Rebuild the EIP-712 ballot typed data from the criteria CID bytes + chainId + the
+     * bundle's `votes` and `blockNumber` (see signer/eip712.ts), recover the signer with
+     * `viem.recoverTypedDataAddress`, and check it equals `bundle.address`. No chain read.
+     */
+    verifyBundleSignature(args: {
+        bundle: VotesBundle;
+        criteriaCid: Uint8Array;
+        chainId: number;
+    }): Promise<VerifyResult>;
+}
+/**
+ * A passing full-bundle verdict. Beyond `valid: true` it carries the work the gate already
+ * did so downstream stages need not redo it:
+ *   - `ruleScore`: the gate `rule`'s score for the voting wallet at the bucket block
+ *     (always `> 0n` here — `0n` would have failed the gate).
+ *   - `resolvedNames`: for each vote that carried a `community.name`, the `publicKey` the name
+ *     resolved to (equal to the claimed key, since a mismatch fails the gate). Votes with no
+ *     name are absent. Lets a UI show a verified name without re-resolving.
+ */
+export interface BundleVerdictValid {
+    valid: true;
+    ruleScore: bigint;
+    resolvedNames: Record<string, string>;
+}
+/**
+ * The full validity verdict for one bundle: signature + criteria constraints + on-chain
+ * gate (`rule`) + community-name resolution, in cheap-to-expensive order with early exit. This is
+ * what the gossip forward-gate runs *before* re-forwarding (see DESIGN.md "Transport"): a
+ * failing verdict is dropped and never forwarded, stored, or counted. Weight *magnitude*
+ * (ranking, not validity) is deliberately NOT computed here — the tally derives it lazily.
+ */
+export type BundleVerdict = BundleVerdictValid | VerifyFail;
+/** Runs the full validity pipeline for one already-fetched, schema-parsed bundle. */
+export interface BundleVerifier {
+    verify(bundle: VotesBundle): Promise<BundleVerdict>;
+    /**
+     * Stage 1 only: signature + criteria constraints — local, µs, no chain read and no name
+     * resolution. This is what admits a bundle *provisionally* on the cold-join chase path; the
+     * deferred network checks (gate chain read, name resolution) then run in the background
+     * chain verifier and either confirm the bundle or evict it (see verify/background.ts and
+     * DESIGN.md "Background chain verification").
+     */
+    verifyOffline(bundle: VotesBundle): Promise<VerifyResult>;
+}
+/**
+ * The per-bundle record of the two deferred *network* checks. The offline checks (signature,
+ * constraints) are never recorded here — they are synchronous preconditions for admission, so
+ * an admitted bundle has always passed them.
+ *
+ *   - `chainVerified`: the gate `rule` scored the wallet `> 0n` at the bucket block. `false`
+ *     means "not yet read", never "failed" — a failed gate evicts the bundle instead.
+ *   - `nameResolved`: `undefined` when the bundle carries no `community.name`; `false` while
+ *     the carried name is unresolved; `true` once it resolved to the claimed `publicKey`. A
+ *     name that resolves to a DIFFERENT key evicts the bundle (it is never counted unchecked).
+ */
+export interface BundleChecks {
+    chainVerified: boolean;
+    nameResolved?: boolean;
+}

package/dist/verify/types.js

@@ -0,0 +1 @@
+export {};