@bitsocial/pubsub-voting 0.3.0 → 0.4.0

package/README.md

@@ -87,6 +87,31 @@ await contest.update();                                   // join the topic, col
 // await contest.stop();                                  // leave the topic
 ```
 
+### Will this wallet's vote count?
+
+Ask the contest before signing. `checkEligibility` runs the contest's **real gate rule** through
+the same chain client, head reader and memo the forward gate uses, so it reads at whatever block
+that rule reads at and applies whatever threshold it applies. When it refuses, the `error` is the
+rule's own wording — render it verbatim:
+
+```ts
+const check = await contest.checkEligibility({ address: wallet });
+if (check.eligible) {
+    show(`eligible — holds ${check.score}`);
+} else {
+    show(check.error);   // e.g. "this wallet holds none of the gate token (0x13d4…91b9)"
+}
+```
+
+Do **not** reimplement this by reading balances yourself: which block counts is the rule's
+business and changes when the rule changes. A client that hard-codes "peers verify at the bucket
+boundary" keeps telling voters to wait for a window that a head-reading gate no longer imposes.
+
+It is a courtesy check, not a promise — eligibility can change between the check and the publish,
+and each peer verifies against its own chain view. `publish()` deliberately does not call it: the
+gate is the network's decision, and a rejection still surfaces after the fact as
+`VoteEvictedError`, carrying the same kind of reason.
+
 Each ranking row carries one flag **per deferred verification operation** (mirroring pkc-js's
 `nameResolved`), and every background settlement re-fires `update` — so a leaderboard can render
 provisional rows immediately and refine them in place:
@@ -196,7 +221,7 @@ Full, type-checked call patterns for a pkc-js host, a plebbit/seedit host, and a
 
 ### Custom rules
 
-The gate and weight are a single flat registry of rules, one `type` per file, mirroring the pkc-js challenge registry. Each rule owns its option schema, its own reads (`readContract`, `getBalance`, ... through `ctx.chain`, the viem `PublicClient` for its `options.chain`), which block it reads at, and what it memoizes — see [What a rule owns](#what-a-rule-owns-its-block-and-its-cache) below. There is **one kind**: `evaluate → { score: bigint }`, a non-negative score where `0n` means "does not qualify" (a result object, not a bare `bigint`, so slot-specific fields can be added later). The criteria has two *slots* drawing from the one registry — the **rule** slot treats the score as a gate (`> 0n` admits), the **weight** slot as the vote's magnitude. A wallet's vote counts as `rule.score > 0n ? weight.score : 0n`. A rule that needs a threshold returns `0n` below it (so `erc5192-min-balance`'s optional `min` gates), which lets the same rule serve either slot. A chain-reading rule may also implement the optional `evaluateMany({ options, wallets, ctx })` batch hook (`wallets` in place of `wallet`, returning `{ results }` — one per input wallet, in order) — its semantics MUST equal mapping `evaluate` — which the background verifier uses to batch a cold join's gate reads. The batch is simply everything pending, so its wallets need not share a `sampleBlock`: a rule reading the head scores them all at once, a rule reading pinned blocks groups them itself. (`erc5192-min-balance` implements it over multicall3, hoisting its one lock assertion out of the per-wallet reads; see [DESIGN.md, Background chain verification](./DESIGN.md#background-chain-verification).)
+The gate and weight are a single flat registry of rules, one `type` per file, mirroring the pkc-js challenge registry. Each rule owns its option schema, its own reads (`readContract`, `getBalance`, ... through `ctx.chain`, the viem `PublicClient` for its `options.chain`), which block it reads at, and what it memoizes — see [What a rule owns](#what-a-rule-owns-its-block-and-its-cache) below. There is **one kind**: `evaluate → RuleResult`, either `{ success: true, score }` with a positive score or `{ success: false, error }` — where `error` is the voter-facing reason the rule refused. The criteria has two *slots* drawing from the one registry — the **rule** slot treats the score as a gate (`> 0n` admits), the **weight** slot as the vote's magnitude. A wallet's vote counts as `rule.success ? weight.score : 0n`. A rule that needs a threshold fails below it (so `erc5192-min-balance`'s optional `min` gates), which lets the same rule serve either slot. A chain-reading rule may also implement the optional `evaluateMany({ options, wallets, ctx })` batch hook (`wallets` in place of `wallet`, returning `{ results }` — one per input wallet, in order) — its semantics MUST equal mapping `evaluate` — which the background verifier uses to batch a cold join's gate reads. The batch is simply everything pending, so its wallets need not share a `sampleBlock`: a rule reading the head scores them all at once, a rule reading pinned blocks groups them itself. (`erc5192-min-balance` implements it over multicall3, hoisting its one lock assertion out of the per-wallet reads; see [DESIGN.md, Background chain verification](./DESIGN.md#background-chain-verification).)
 
 Built-ins: `erc5192-min-balance` (v1) and `constant` (v1).
 
@@ -217,7 +242,9 @@ const seeditModAllowlist: Rule<{ type: "seedit-mod-allowlist"; allow: string[] }
   type: "seedit-mod-allowlist",
   optionsSchema: z.object({ type: z.literal("seedit-mod-allowlist"), allow: z.array(z.string()) }),
   async evaluate({ options, wallet }) {
-    return { score: options.allow.includes(wallet.address) ? 1n : 0n }; // gate: 1n admits, 0n rejects
+    return options.allow.includes(wallet.address)
+      ? { success: true, score: 1n }
+      : { success: false, error: "this wallet is not on the moderator allowlist" }; // shown to the voter
   }
 };
 
@@ -255,15 +282,19 @@ const { values } = await ctx.cache.memoMany({
 });
 ```
 
-`RuleResult` carries one field beyond the score:
+`RuleResult` is a discriminated union, shaped like pkc-js's `ChallengeResult`:
 
 ```ts
-interface RuleResult { score: bigint; penalize?: boolean }   // default true
+type RuleResult =
+  | { success: true;  score: bigint }                          // score MUST be > 0n
+  | { success: false; error: string; penalize?: boolean };     // penalize default true
 ```
 
-**`penalize`** answers the one thing the library cannot: may a `0n` be blamed on the sender? `true` (the default) says every honest verifier computes this same `0n` — true of a read pinned to the block the bundle names — so the forward gate `reject`s the message (penalizing the delivering peer in gossipsub's scoring) and the verdict is cached as terminal. `false` says an honest peer could legitimately disagree, so the bundle is dropped `ignore`-class instead: no penalty, verdict uncached, and the background verifier re-examines it for a grace window before giving up.
+**`error` is required on the failing branch**, because only the rule knows why a wallet fell short — it holds none, it holds too few, the contract gates nothing. That sentence is what the library shows the voter: it becomes the verdict reason, so it reaches the publisher on `VoteEvictedError.verdict.reason`, and it is what `contest.checkEligibility()` returns. Write it about the wallet ("this wallet holds none of the gate token"), not about the library, and leave block numbers out unless a voter can act on them. Making it optional would mean every UI re-deriving the rule's thresholds and block choice to say anything useful — which is exactly the coupling `ctx` and `RuleCache` exist to remove.
+
+**`penalize`** answers the one thing the library cannot: may the failure be blamed on the sender? `true` (the default) says every honest verifier computes this same failure — true of a read pinned to the block the bundle names — so the forward gate `reject`s the message (penalizing the delivering peer in gossipsub's scoring) and the verdict is cached as terminal. `false` says an honest peer could legitimately disagree, so the bundle is dropped `ignore`-class instead: no penalty, verdict uncached, and the background verifier re-examines it for a grace window before giving up.
 
-`erc5192-min-balance` reads the head first — so a freshly-acquired Pass counts immediately — falls back to `wallet.sampleBlock` when the head refuses (ERC-5192 does not forbid burning, and without the fallback a burn would erase votes retroactively for peers that had not verified them yet), memoizes each leg under its own epoch, and returns `penalize: false`, because at validation time it cannot attribute a `0n` to anyone: the peer that forwarded the vote verified it against *its* head. Every other rule in the tree reads `wallet.sampleBlock` and leaves `penalize` at its default — a transferable or fungible balance can decrease, so reading it at the head would silently invalidate votes already counted. See [DESIGN.md, What a rule owns](./DESIGN.md#what-a-rule-owns-and-what-the-pipeline-owns).
+`erc5192-min-balance` reads the head first — so a freshly-acquired Pass counts immediately — falls back to `wallet.sampleBlock` when the head refuses (ERC-5192 does not forbid burning, and without the fallback a burn would erase votes retroactively for peers that had not verified them yet), memoizes each leg under its own epoch, and returns `penalize: false`, because at validation time it cannot attribute a failure to anyone: the peer that forwarded the vote verified it against *its* head. Every other rule in the tree reads `wallet.sampleBlock` and leaves `penalize` at its default — a transferable or fungible balance can decrease, so reading it at the head would silently invalidate votes already counted. See [DESIGN.md, What a rule owns](./DESIGN.md#what-a-rule-owns-and-what-the-pipeline-owns).
 
 ### Weighted voting (deferred)
 

package/dist/client/voter.d.ts

@@ -65,6 +65,19 @@ export interface PublishOutcome {
     readonly recipientCount: number;
 }
 /** One contest's reactive read view: subscribe, keep the tally in sync, read it. */
+/**
+ * What {@link Contest.checkEligibility} found. Shaped like {@link RuleResult} on purpose — it is
+ * that result, surfaced — so the failing branch always carries a reason a client can display.
+ */
+export type EligibilityResult = {
+    eligible: true;
+    /** The wallet's gate score, `> 0n`. For a balance gate this is the holding itself. */
+    score: bigint;
+} | {
+    eligible: false;
+    /** The rule's own explanation, written for the voter. Render it verbatim. */
+    error: string;
+};
 export interface Contest {
     /** The criteria document this contest runs (already validated). */
     readonly criteria: Criteria;
@@ -85,6 +98,30 @@ export interface Contest {
     stop(): Promise<void>;
     /** Compute the current contest ranking fresh, bypassing the cache. */
     getTally(): Promise<ContestTally>;
+    /**
+     * Would this contest's gate admit `address` right now? Ask before signing, to tell a voter
+     * whether their ballot will count — and, when it will not, exactly why.
+     *
+     * This runs the contest's REAL gate rule through the same context the forward-gate and the
+     * background verifier use: the same chain client, the same coalesced head reader, the same
+     * memo. So it reads at whatever block the rule reads at, applies whatever threshold the rule
+     * applies, and returns the rule's own {@link RuleResult.error} wording verbatim. A client
+     * renders `error` and needs to know nothing about blocks, buckets or thresholds — which is
+     * the point: re-deriving any of that outside the rule is how a UI ends up confidently
+     * telling voters to wait for a window that no longer gates anything.
+     *
+     * It is a courtesy check, not a promise. Eligibility is a fact about the chain and can change
+     * between this call and the publish, and each peer verifies against its own view — so a
+     * `true` here can still be followed by a `VoteEvictedError` (which carries the same kind of
+     * reason). `publish()` deliberately does NOT call this: the gate is the network's decision,
+     * and refusing locally would only hide a vote the rest of the topic would have accepted.
+     *
+     * Costs one gate evaluation, usually served from the shared memo — the same read the verifier
+     * would do anyway, not an extra one.
+     */
+    checkEligibility(args: {
+        address: string;
+    }): Promise<EligibilityResult>;
     /**
      * Fired when incoming votes change the state; `tally` carries the freshly recomputed
      * ranking. Background check settlements fire it too: a cold join emits a first tally with

package/dist/client/voter.js

@@ -15,6 +15,7 @@ import { encodeBundle, decodeBundle, bundleCidForBytes } from "../crdt/codec.js"
 import { resolveRegistry, validateCriteriaRules } from "../rules/registry.js";
 import { makeVoteCrdt } from "../crdt/crdt.js";
 import { makePersistentRuleCache } from "../rules/cache.js";
+import { gateFailure, scoreOrZero } from "../rules/result.js";
 import { makeBundleVerifier } from "../verify/bundle.js";
 import { makeVerdictCache } from "../verify/cache.js";
 import { makeNameResolutionCache } from "../verify/name-resolution-cache.js";
@@ -871,6 +872,21 @@ class ContestEngine {
             return true;
         return sampleBucket <= (await this.#nowBucket());
     }
+    /**
+     * Run the gate rule for one wallet, against the ballot block a vote published NOW would carry
+     * — the engine half of {@link Contest.checkEligibility}.
+     *
+     * All the interesting decisions belong to the rule: this resolves the current bucket's sample
+     * block, hands it over, and translates the rule's own answer. It never looks at what kind of
+     * rule it is holding, so it stays correct for a head-scoring gate, a pinned one, or anything
+     * a host registers later.
+     */
+    async checkEligibility({ address }) {
+        const sampleBlock = this.#bucketMath.sampleBlockForBucket(await this.#nowBucket());
+        const result = await this.#verifier.checkGate({ address, sampleBlock });
+        const failed = gateFailure(result);
+        return failed ? { eligible: false, error: failed.error } : { eligible: true, score: scoreOrZero(result) };
+    }
     /** Hash of the current bucket boundary block on the gating (`rule`) chain (rolling tie seed). */
     async #bucketBlockHash() {
         const head = await this.#ruleChain.getBlockNumber();
@@ -1696,6 +1712,9 @@ class ContestView {
     getTally() {
         return this.#engine.computeTally();
     }
+    checkEligibility(args) {
+        return this.#engine.checkEligibility(args);
+    }
     /**
      * Internal hook (not part of the {@link Contest} interface): this contest's current checkpoint
      * root record, encoded on demand. The fetch responder and heartbeat use the engine directly;

package/dist/rules/constant.js

@@ -13,6 +13,8 @@ export const constant = {
     type: "constant",
     optionsSchema: ConstantOptionsSchema,
     async evaluate({ options }) {
-        return { score: BigInt(options.value) };
+        // `value` is schema-constrained positive, so this rule has no failing branch at all —
+        // in the rule slot it is the no-op gate that admits everyone.
+        return { success: true, score: BigInt(options.value) };
     }
 };

package/dist/rules/erc20-balance.js

@@ -1,4 +1,4 @@
-import { erc20Abi, getAddress, parseUnits } from "viem";
+import { erc20Abi, formatUnits, getAddress, parseUnits } from "viem";
 import { z } from "zod";
 import { ChainTickerSchema } from "../schema/common.js";
 /**
@@ -50,6 +50,12 @@ export const erc20Balance = {
             blockNumber: BigInt(wallet.sampleBlock)
         });
         const minUnits = parseUnits(options.min.toString(), options.decimals);
-        return { score: raw >= minUnits ? raw : 0n };
+        if (raw >= minUnits)
+            return { success: true, score: raw };
+        return {
+            success: false,
+            error: `this wallet holds ${formatUnits(raw, options.decimals)} of the gate token ` +
+                `(${getAddress(options.contract)}), but ${options.min} is required`
+        };
     }
 };

package/dist/rules/erc5192-min-balance.js

@@ -1,7 +1,7 @@
 import { BaseError, ContractFunctionRevertedError, ContractFunctionZeroDataError, getAddress } from "viem";
 import { z } from "zod";
 import { ChainTickerSchema } from "../schema/common.js";
-import { balanceOf, balancesOfBatched, canBatch, scoreOf } from "./nft-balance.js";
+import { balanceOf, balancesOfBatched, canBatch, scoreOf, shortfallError } from "./nft-balance.js";
 /**
  * Hold at least `min` of a **soulbound** ERC-721 (the 5chan Pass). The v1 gate.
  *
@@ -89,6 +89,15 @@ const HEAD_EPOCH_BLOCKS = 30;
 /** Cache-key prefixes: head-scored entries expire with the head, pinned ones never do. */
 const HEAD_PREFIX = "head/";
 const PINNED_PREFIX = "pin/";
+/**
+ * The voter-facing wording for every way this rule reaches `0n` ({@link RuleResult.error}).
+ *
+ * Deliberately generic and self-contained: the rule knows a contract address and a threshold, not
+ * that the deployment calls this token a "5chan Pass". A client renders these verbatim, which is
+ * the point — it then needs to know nothing about which block the rule read or what `min` is.
+ */
+const undeclaredError = (contract) => `the gate contract ${contract} does not declare ERC-5192, so it gates nothing and no wallet can qualify ` +
+    `— this contest's criteria name a contract that is not soulbound`;
 /** One `supportsInterface(0xb45a3c0e)` at `block`. Revert/zero-data ⇒ "does not declare". */
 async function declaresErc5192(args) {
     try {
@@ -120,7 +129,7 @@ async function declaresErc5192(args) {
 async function scoreAt(args) {
     const { contract, min, wallets, block, epoch, prefix, ctx } = args;
     if (wallets.length === 0)
-        return { scores: [] };
+        return { scores: [], errors: [] };
     const [declared] = (await ctx.cache.memoMany({
         keys: [`${prefix}lock/${contract.toLowerCase()}`],
         epoch,
@@ -132,7 +141,7 @@ async function scoreAt(args) {
     // A contract that does not claim its tokens are locked gates nothing: admit nobody rather
     // than gate on something transferable (see the rule doc above).
     if (declared !== "1")
-        return { scores: wallets.map(() => 0n) };
+        return { scores: wallets.map(() => 0n), errors: wallets.map(() => undeclaredError(contract)) };
     const { values } = await ctx.cache.memoMany({
         keys: wallets.map((wallet) => `${prefix}bal/${wallet.toLowerCase()}`),
         epoch,
@@ -146,8 +155,22 @@ async function scoreAt(args) {
             return { values: balances.map((balance) => balance.toString()) };
         }
     });
-    return { scores: values.map((balance) => scoreOf(BigInt(balance), min)) };
+    const scores = values.map((balance) => scoreOf(BigInt(balance), min));
+    return {
+        scores,
+        errors: scores.map((score, i) => (score > 0n ? undefined : shortfallError(BigInt(values[i]), min, contract)))
+    };
 }
+/** `{ success: true, score }` when the leg admitted, else the failing branch with its reason. */
+function resultOf(score, error) {
+    // `penalize: false` on every failure: neither leg makes one attributable. The peer that
+    // forwarded a vote verified it against ITS head, and any peer ahead of us may legitimately
+    // see an acquisition we have not — and with burning possible, holding at neither block does
+    // not even prove the wallet never held.
+    return score > 0n ? { success: true, score } : { success: false, error: error ?? UNKNOWN_ERROR, penalize: false };
+}
+/** Unreachable: `scoreAt` pairs every non-positive score with a reason. Kept total, not thrown. */
+const UNKNOWN_ERROR = "this wallet does not qualify for this contest's gate";
 export const erc5192MinBalance = {
     type: "erc5192-min-balance",
     optionsSchema: Erc5192MinBalanceOptionsSchema,
@@ -184,10 +207,15 @@ export const erc5192MinBalance = {
      * head (a stale `0n` must not outlive {@link HEAD_EPOCH_BLOCKS}), while the pinned leg is a
      * historical read that is true forever and is keyed by the block itself.
      *
-     * **`penalize: false`** on every result: neither leg makes a `0n` attributable. The peer that
+     * **`penalize: false`** on every failure: neither leg makes one attributable. The peer that
      * forwarded a vote verified it against ITS head, and any peer ahead of us may legitimately
      * see an acquisition we have not — and with burning possible, not holding at either block
      * does not even prove the wallet never held.
+     *
+     * **Three distinct failures**, each with its own {@link RuleResult.error}: the contract does
+     * not declare ERC-5192 (so it gates nothing and no wallet can ever qualify), the wallet holds
+     * none, or it holds some but fewer than `min`. The fallback leg has the last word on a
+     * wallet's score, so it owns that wallet's reason too.
      */
     async evaluateMany({ options, wallets, ctx }) {
         const contract = getAddress(options.contract);
@@ -196,7 +224,7 @@ export const erc5192MinBalance = {
         // Everything behind the current window is unreachable — nothing will look it up again.
         // Scoped to the head keys, so the permanently-valid pinned entries are left alone.
         ctx.cache.purgeBelow({ epoch, keyPrefix: HEAD_PREFIX });
-        const { scores } = await scoreAt({
+        const { scores, errors } = await scoreAt({
             contract,
             min: options.min,
             wallets: wallets.map((wallet) => wallet.address),
@@ -226,8 +254,12 @@ export const erc5192MinBalance = {
             });
             indexes.forEach((at, i) => {
                 scores[at] = fallback.scores[i];
+                // The fallback leg had the last word on the score, so it owns the reason too:
+                // a wallet that holds none at the head but held some at its ballot's block is
+                // admitted, and one that holds none at either gets the pinned leg's wording.
+                errors[at] = fallback.errors[i];
             });
         }));
-        return { results: scores.map((score) => ({ score, penalize: false })) };
+        return { results: scores.map((score, i) => resultOf(score, errors[i])) };
     }
 };

package/dist/rules/erc721-min-balance.js

@@ -1,7 +1,7 @@
 import { getAddress } from "viem";
 import { z } from "zod";
 import { ChainTickerSchema } from "../schema/common.js";
-import { balanceOf, balancesOfBatched, canBatch, scoreOf } from "./nft-balance.js";
+import { balanceOf, balancesOfBatched, canBatch, scoreOf, shortfallError } from "./nft-balance.js";
 /**
  * Hold at least `min` of a **plain** ERC-721.
  *
@@ -28,6 +28,15 @@ export const Erc721MinBalanceOptionsSchema = z.object({
     contract: z.string(),
     min: z.number().int().positive().default(1)
 });
+/**
+ * One pinned-block balance as a {@link RuleResult}. `penalize` is left at its default `true`:
+ * this rule reads the block the bundle itself names, so every honest verifier computes the same
+ * answer forever and a failure IS attributable to whoever sent it.
+ */
+function pinnedResult(balance, min, contract) {
+    const score = scoreOf(balance, min);
+    return score > 0n ? { success: true, score } : { success: false, error: shortfallError(balance, min, contract) };
+}
 export const erc721MinBalance = {
     type: "erc721-min-balance",
     optionsSchema: Erc721MinBalanceOptionsSchema,
@@ -45,7 +54,7 @@ export const erc721MinBalance = {
             block: wallet.sampleBlock,
             ctx
         });
-        return { score: scoreOf(balance, options.min) };
+        return pinnedResult(balance, options.min, getAddress(options.contract));
     },
     async evaluateMany({ options, wallets, ctx }) {
         const contract = getAddress(options.contract);
@@ -54,7 +63,7 @@ export const erc721MinBalance = {
         // a group it is multicall3 `aggregate3` batching (chunking policy in nft-balance.ts) —
         // the path the background chain verifier rides on a cold join; a client that cannot
         // batch takes the per-wallet fallback.
-        const scores = new Array(wallets.length);
+        const results = new Array(wallets.length);
         const byBlock = new Map();
         wallets.forEach((wallet, i) => byBlock.set(wallet.sampleBlock, [...(byBlock.get(wallet.sampleBlock) ?? []), i]));
         await Promise.all([...byBlock].map(async ([block, indexes]) => {
@@ -65,9 +74,9 @@ export const erc721MinBalance = {
                     balances: await Promise.all(group.map(async (wallet) => (await balanceOf({ contract, wallet, block, ctx })).balance))
                 };
             indexes.forEach((at, i) => {
-                scores[at] = scoreOf(balances[i], options.min);
+                results[at] = pinnedResult(balances[i], options.min, contract);
             });
         }));
-        return { results: scores.map((score) => ({ score })) };
+        return { results: results.map((result) => result) };
     }
 };

package/dist/rules/nft-balance.d.ts

@@ -1,6 +1,15 @@
 import type { ChainReadContext } from "./types.js";
 /** Score from one balance: the holding when it meets `min`, else `0n` (does not qualify). */
 export declare function scoreOf(balance: bigint, min: number): bigint;
+/**
+ * The voter-facing wording for a token-count shortfall ({@link RuleResult.error}), shared by
+ * every balance-scored rule so they explain themselves identically.
+ *
+ * Deliberately generic: a rule knows a contract address and a threshold, not that the deployment
+ * calls this token a "5chan Pass". A client renders it verbatim, which is the point — it then
+ * needs to know nothing about which block the rule read or what `min` is.
+ */
+export declare function shortfallError(balance: bigint, min: number, contract: string): string;
 /**
  * True when the client can run multicall3 `aggregate3` batches — it needs both the action and
  * its chain's multicall3 deployment. A client built without a `chain` (or on a chain without

package/dist/rules/nft-balance.js

@@ -28,6 +28,19 @@ const CHUNK_RETRY_DELAY_MS = CHAIN_CHUNK_RETRY_DELAY_MS;
 export function scoreOf(balance, min) {
     return balance >= BigInt(min) ? balance : 0n;
 }
+/**
+ * The voter-facing wording for a token-count shortfall ({@link RuleResult.error}), shared by
+ * every balance-scored rule so they explain themselves identically.
+ *
+ * Deliberately generic: a rule knows a contract address and a threshold, not that the deployment
+ * calls this token a "5chan Pass". A client renders it verbatim, which is the point — it then
+ * needs to know nothing about which block the rule read or what `min` is.
+ */
+export function shortfallError(balance, min, contract) {
+    return balance === 0n
+        ? `this wallet holds none of the gate token (${contract})`
+        : `this wallet holds ${balance} of the gate token (${contract}), but ${min} are required`;
+}
 /**
  * True when the client can run multicall3 `aggregate3` batches — it needs both the action and
  * its chain's multicall3 deployment. A client built without a `chain` (or on a chain without

package/dist/rules/result.d.ts

@@ -0,0 +1,16 @@
+import type { RuleResult } from "./types.js";
+/**
+ * `undefined` when the wallet is admitted, else why it was not and whether the sender may be
+ * blamed for it.
+ *
+ * `penalize` is normalised here (defaulting to `true`) so callers never repeat the
+ * `!== false` dance, and a `success: true, score: 0n` — impossible per the contract, but not
+ * expressible in the type — is treated as a failure rather than silently admitting a
+ * zero-weight vote.
+ */
+export declare function gateFailure(result: RuleResult): {
+    error: string;
+    penalize: boolean;
+} | undefined;
+/** The weight slot's reading: a failure contributes nothing rather than dropping the vote. */
+export declare function scoreOrZero(result: RuleResult): bigint;

package/dist/rules/result.js

@@ -0,0 +1,30 @@
+/**
+ * The two things the pipeline does with a {@link RuleResult}, in one place so the gate path and
+ * the background verifier cannot drift apart.
+ *
+ * Neither helper looks at which rule produced the result — that is the standing rule of this
+ * codebase (AGENTS.md, "What a rule owns, and what the pipeline owns"). They read the discriminant
+ * and nothing else.
+ */
+/** A rule that says `success: true` but scores nothing has a bug; refuse rather than admit. */
+const NON_POSITIVE_SUCCESS = "the contest's rule reported success without a score, which is a bug in that rule";
+/**
+ * `undefined` when the wallet is admitted, else why it was not and whether the sender may be
+ * blamed for it.
+ *
+ * `penalize` is normalised here (defaulting to `true`) so callers never repeat the
+ * `!== false` dance, and a `success: true, score: 0n` — impossible per the contract, but not
+ * expressible in the type — is treated as a failure rather than silently admitting a
+ * zero-weight vote.
+ */
+export function gateFailure(result) {
+    if (!result.success)
+        return { error: result.error, penalize: result.penalize !== false };
+    if (result.score <= 0n)
+        return { error: NON_POSITIVE_SUCCESS, penalize: true };
+    return undefined;
+}
+/** The weight slot's reading: a failure contributes nothing rather than dropping the vote. */
+export function scoreOrZero(result) {
+    return result.success && result.score > 0n ? result.score : 0n;
+}

package/dist/rules/types.d.ts

@@ -12,49 +12,79 @@ import type { RuleCache } from "./cache.js";
  * entries shadow builtins). The criteria still has two slots that draw from this one
  * registry:
  *
- *   - rule slot:   the score is a GATE. `> 0n` admits the wallet, `0n` rejects it.
- *   - weight slot: the score is the vote's MAGNITUDE.
+ *   - rule slot:   the result is a GATE. `success: true` admits the wallet, `success: false`
+ *                  rejects it and must say why ({@link RuleResult.error}).
+ *   - weight slot: a successful result's `score` is the vote's MAGNITUDE; a failure is zero
+ *                  weight.
  *
- * Final vote value = `evaluate(rule).score === 0n ? 0n : evaluate(weight).score`.
- *
- * A single numeric return covers both roles: a rule that needs a threshold
- * (min Passes, min balance) bakes it in by returning 0n when the wallet falls short.
- * That is why the gate slot does not need a separate boolean kind.
+ * One return shape covers both roles: a rule that needs a threshold (min Passes, min balance)
+ * bakes it in by failing when the wallet falls short, so the gate slot needs no separate kind.
  */
 /**
- * The result of one evaluation. `score` is a non-negative `bigint`; `0n` means "does not
- * qualify" (rejected in the rule slot, no weight in the weight slot). It is an
- * object, not a bare `bigint`, so slot-specific fields can be added without changing the
- * signature again — e.g. a self-declared `ceiling` for balance-derived weight, which the
- * lazy tally needs as a wire-side upper bound (see DESIGN.md "Open questions").
+ * The result of one evaluation: a wallet either qualifies with a score, or it does not and the
+ * rule says why.
+ *
+ * Modelled on pkc-js's `ChallengeResult` (community/schema.ts) — a `success` discriminant, with
+ * `error` REQUIRED on the failing branch. Making it required is the whole point: only the rule
+ * knows why a wallet fell short, and if that reason is optional it will simply be omitted, which
+ * leaves the pipeline with one undifferentiated "score is 0n" and forces every UI to re-derive
+ * the rule's thresholds and block choice to say anything useful. That duplication is exactly what
+ * {@link ChainReadContext} and {@link RuleCache} exist to prevent everywhere else, and it is what
+ * broke when the gate moved from a pinned block to the head: a client's hand-rolled explanation
+ * kept telling voters to wait for a window that no longer gated anything.
+ *
+ *   - rule slot:   `success: true` admits the wallet; `success: false` rejects it.
+ *   - weight slot: `success: true` carries the vote's MAGNITUDE; `success: false` is zero weight.
+ *
+ * Final vote value = gate `success: false` ? `0n` : weight `success` ? weight `score` : `0n`.
+ *
+ * `score` MUST be `> 0n` on the success branch — "qualifies, with no weight" is not a state this
+ * models, and the pipeline treats a non-positive success score as a rule bug and refuses the
+ * wallet rather than silently admitting a zero-weight vote.
  */
-export interface RuleResult {
+export type RuleResult = {
+    success: true;
+    /** The wallet's magnitude. MUST be `> 0n`. */
     score: bigint;
+} | {
+    success: false;
     /**
-     * May a `0n` be blamed on the sender? Default `true`.
+     * Why this wallet does not qualify, phrased for the person who cast (or is about to
+     * cast) the vote. Surfaces on `VerifyFail.reason`, on `VoteEvictedError.verdict`, and
+     * from `Contest.checkEligibility`, so a client renders it verbatim and stays correct
+     * across rule changes it knows nothing about.
      *
-     * The pipeline has two decisions to make about a `0n` that the rule cannot make for it —
-     * whether the gossip forward-gate `reject`s the message (which penalizes the delivering peer
-     * through gossipsub's invalid-message score, eventually pruning and graylisting it) or
-     * merely `ignore`s it, and whether the background verifier evicts the bundle at once or
-     * holds it for a grace window. Both hinge on one thing only the rule knows: is this `0n`
+     * Write it as a statement about the wallet, not about the library: "this wallet holds
+     * none of the gate token", not "gate rule returned 0". Do not cite block numbers unless
+     * they are actionable — a voter can do nothing with a sample block.
+     */
+    error: string;
+    /**
+     * May this failure be blamed on the peer that sent the vote? Default `true`.
+     *
+     * The pipeline has two decisions the rule cannot make for it — whether the gossip
+     * forward-gate `reject`s the message (penalizing the delivering peer through
+     * gossipsub's invalid-message score, eventually pruning and graylisting it) or merely
+     * `ignore`s it, and whether the background verifier evicts the bundle at once or holds
+     * it for a grace window. Both hinge on one thing only the rule knows: is this failure
      * attributable?
      *
-     * `true` (the default) says every honest verifier necessarily computes this same `0n` — true
-     * of a read pinned to a historical block, since the block is named by the bundle and the
-     * chain's history does not move. The bundle is dropped, the sender penalized, the verdict
-     * cached as terminal.
+     * `true` (the default) says every honest verifier necessarily computes this same
+     * failure — true of a read pinned to a historical block, since the block is named by
+     * the bundle and the chain's history does not move. The bundle is dropped, the sender
+     * penalized, the verdict cached as terminal.
      *
      * `false` says an honest peer could legitimately disagree, so nobody may be blamed. The
      * bundle is still dropped, but `ignore`-class — no penalty, verdict uncached, and the
-     * background verifier re-examines it for a grace window before giving up. This is what a
-     * rule scoring the chain head must return: the peer that forwarded the vote verified it
-     * against ITS head, and any peer ahead of us can legitimately see an acquisition we have
-     * not. Penalizing there punishes honest relayers for being current — and does so exactly
-     * when a wallet has just acquired the gate asset, which is when peer heads straddle.
+     * background verifier re-examines it for a grace window before giving up. This is what
+     * a rule scoring the chain head must return: the peer that forwarded the vote verified
+     * it against ITS head, and any peer ahead of us can legitimately see an acquisition we
+     * have not. Penalizing there punishes honest relayers for being current — and does so
+     * exactly when a wallet has just acquired the gate asset, which is when peer heads
+     * straddle.
      */
     penalize?: boolean;
-}
+};
 /** Everything a rule needs to read chain state and remember what it read. */
 export interface ChainReadContext {
     /**
@@ -101,8 +131,8 @@ export interface RuleWallet {
 }
 /**
  * The one rule kind. `O` is the validated options type (from its `optionsSchema`).
- * `evaluate` returns a `RuleResult` whose `score` is a non-negative `bigint`; `0n`
- * means "does not qualify" (rejected in the rule slot, no weight in the weight slot).
+ * `evaluate` returns a {@link RuleResult}: either `{ success: true, score }` with `score > 0n`,
+ * or `{ success: false, error }` — "does not qualify", with the reason the voter is shown.
  */
 export interface Rule<O = unknown> {
     readonly type: string;

package/dist/tally/tally.js

@@ -2,6 +2,7 @@ import { base58btc } from "multiformats/bases/base58";
 import { sha256 } from "multiformats/hashes/sha2";
 import { tickerForRef } from "../chain/ticker.js";
 import { makeMemoryRuleCache } from "../rules/cache.js";
+import { scoreOrZero } from "../rules/result.js";
 import { UnknownRuleError } from "../errors.js";
 /** Byte-lexicographic compare of two byte arrays (returns <0, 0, >0). */
 function compareBytes(x, y) {
@@ -37,12 +38,13 @@ export function makeTally(deps) {
     };
     const weightFor = async (wallet, blockNumber) => {
         const sampleBlock = bucketMath.sampleBlockForBucket(bucketMath.bucketForBlock(blockNumber));
-        const { score } = await weight.evaluate({
+        // A weight rule that fails a wallet contributes nothing; it does NOT drop the vote —
+        // admission was the gate's decision, already made (see rules/result.ts).
+        return scoreOrZero(await weight.evaluate({
             options: weightOptions,
             wallet: { address: wallet, sampleBlock },
             ctx: weightCtx
-        });
-        return score;
+        }));
     };
     /** The rolling tie seed for a community: sha256(bucketBlockHash ‖ publicKey bytes). */
     const tieSeed = async (blockHash, publicKey) => {

package/dist/transport/integration/harness.js

@@ -116,7 +116,10 @@ export async function makeVoteNode(topic, options = {}) {
     let verifyImpl = async () => okVerifier();
     const verifier = {
         verify: (bundle) => verifyImpl(bundle),
-        verifyOffline: (bundle) => verifyImpl(bundle)
+        verifyOffline: (bundle) => verifyImpl(bundle),
+        // These harness nodes drive the transport, not the eligibility surface; nothing here
+        // calls checkGate, so it admits rather than pretending to model a gate.
+        checkGate: async () => ({ success: true, score: 1n })
     };
     const admit = async ({ cid, bytes }) => {
         await blockstore.put(cid, bytes);

package/dist/verify/background.js

@@ -1,6 +1,7 @@
 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;
@@ -78,8 +79,8 @@ export function makeBackgroundVerifier(deps) {
         for (const item of pending) {
             const key = `${item.bundle.address.toLowerCase()}:${sampleBlockFor(item.bundle)}`;
             const result = results[at.get(key)];
-            item.ruleScore = result.score;
-            item.gatePenalize = result.penalize !== false;
+            item.gateFailed = gateFailure(result);
+            item.ruleScore = scoreOrZero(result);
             item.gateDone = true;
         }
     }
@@ -143,13 +144,13 @@ export function makeBackgroundVerifier(deps) {
                 requeue.push(item); // gate read never happened (infra) — retry the whole item
                 continue;
             }
-            if (item.ruleScore === 0n) {
-                if (item.gatePenalize) {
+            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: rule score is 0n`
+                        reason: `not admitted: ${item.gateFailed.error}`
                     };
                     cache.set(item.cid, verdict);
                     deps.onEvict(item.cid, verdict);
@@ -157,7 +158,7 @@ export function makeBackgroundVerifier(deps) {
                     continue;
                 }
                 // The rule declined to blame anyone (see rules/types.ts, RuleResult.penalize):
-                // `0n` means "not yet", not "no". The wallet may have acquired the gate asset in
+                // 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
@@ -173,7 +174,7 @@ export function makeBackgroundVerifier(deps) {
                 const verdict = {
                     valid: false,
                     disposition: "ignore",
-                    reason: `not admitted: rule score is 0n, and still 0n after the grace window`
+                    reason: `not admitted: ${item.gateFailed.error} (still true after the grace window)`
                 };
                 deps.onEvict(item.cid, verdict);
                 settle(item);
@@ -260,7 +261,7 @@ export function makeBackgroundVerifier(deps) {
                     gateDone: false,
                     gateNotified: false,
                     ruleScore: 0n,
-                    gatePenalize: true,
+                    gateFailed: undefined,
                     resolvedNames: {},
                     queuedAt: Date.now()
                 });

package/dist/verify/bundle.d.ts

@@ -11,10 +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 whichever block the rule
- *                               itself reads (rules/types.ts). `0n` -> not admitted -> drop, as
- *                               a `reject` when the rule blames the sender for it and an
- *                               `ignore` when it does not.
+ *   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.
  *

package/dist/verify/bundle.js

@@ -1,5 +1,6 @@
 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";
@@ -32,6 +33,10 @@ 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)
@@ -40,24 +45,29 @@ export function makeBundleVerifier(deps) {
             //    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));
-            const { score, penalize } = await rule.evaluate({
+            const gate = await rule.evaluate({
                 options: ruleOptions,
                 wallet: { address: bundle.address, sampleBlock },
                 ctx
             });
-            if (score === 0n) {
+            const gateFailed = gateFailure(gate);
+            if (gateFailed) {
                 // Disposition comes from the rule's own answer, never from the rule's identity.
-                // A `0n` the rule stands behind is identical on every honest verifier, so it is a
-                // `reject`: the sender is penalized and the verdict cached as terminal. A `0n` it
+                // 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: penalize === false ? "ignore" : "reject",
-                    reason: `not admitted: rule score is 0n`
+                    disposition: gateFailed.penalize ? "reject" : "ignore",
+                    reason: `not admitted: ${gateFailed.error}`
                 };
             }
             // 4. Community-name resolution (network) — a carried name is a claim, verified against
@@ -92,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/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.3.0",
+  "version": "0.4.0",
   "description": "Trustless pubsub voting over a shared libp2p/Helia node.",
   "type": "module",
   "license": "GPL-3.0-or-later",