@bitsocial/pubsub-voting 0.4.1 → 0.5.0

package/dist/verify/bundle.d.ts

@@ -1,7 +1,7 @@
 import type { Criteria } from "../schema/criteria.js";
 import type { RuleRegistry } from "../rules/types.js";
 import type { ChainClient, BucketMath, NameResolver } from "../chain/types.js";
-import { type RuleCache } from "../rules/cache.js";
+import type { RuleCache } from "../rules/cache.js";
 import { type NameResolutionCache } from "./name-resolution-cache.js";
 import type { BundleVerifier } from "./types.js";
 /**
@@ -32,12 +32,12 @@ 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). */
+    /** The contest's numeric chainId (`criteria.bucketChainId`, 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;
+    /** The contest's one chain client — every rule reads it (DESIGN.md "One clock"). */
+    chain: ChainClient;
     /** Bucket math for `criteria.blocksPerBucket`. */
     bucketMath: BucketMath;
     /** Host-injected community-name resolvers (`PubsubVoterOptions.nameResolvers`). */
@@ -55,13 +55,15 @@ export interface BundleVerifierDeps {
         block: number;
     }>;
     /**
-     * The gate rule's memo (see rules/cache.ts), handed to it as `ctx.cache`. This is what keeps
-     * a wallet's gate read from repeating per bundle — an ineligible wallet minting fresh-signed
-     * bundles, or an eligible one cycling choices, costs one read per key per rule epoch rather
-     * than one per bundle. Defaults to a private in-memory cache (unit tests); the voter injects
-     * the persistent, contest-shared one.
+     * One memo per gate leaf (see rules/cache.ts), in `gateLeaves` order, handed to each rule as
+     * its `ctx.cache`. This is what keeps a wallet's gate read from repeating per bundle — an
+     * ineligible wallet minting fresh-signed bundles, or an eligible one cycling choices, costs
+     * one read per key per rule epoch rather than one per bundle. Each leaf gets its OWN
+     * namespace, so two leaves of the same rule `type` on different options can never read each
+     * other's answers. Defaults to private in-memory caches (unit tests); the voter injects the
+     * persistent, contest-shared ones.
      */
-    ruleCache?: RuleCache;
+    ruleCaches?: readonly RuleCache[];
     /**
      * Optional persistent cache of name resolutions (the pkc-js rule — see
      * verify/name-resolution-cache.ts). When present, a carried name is resolved live at most

package/dist/verify/bundle.js

@@ -1,26 +1,32 @@
-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 { dedupeLeaves, evaluateGate, gateBlame, gatePenalize, gateReason, resolveGate } from "../rules/gate.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, nameResolutionCache } = deps;
-    // Resolve the gate `rule`, its options and its chain client once: they are fixed by the
-    // criteria, so none of it is recomputed per bundle.
-    const rule = registry[criteria.rule.type];
-    if (!rule)
-        throw new UnknownRuleError("rule", criteria.rule.type);
-    const ruleOptions = rule.optionsSchema.parse(criteria.rule);
-    const ruleChain = chainFor(tickerForRef(criteria, criteria.rule, ruleOptions));
-    const readHead = deps.readHead ?? (async ({ chain }) => ({ block: Number(await chain.getBlockNumber()) }));
-    // The rule's whole world: its chain, this verifier's head (lazy — never read for a rule that
-    // does not want it), and its own memo. Which block it actually reads at is its business.
-    const ctx = {
-        chain: ruleChain,
-        head: () => readHead({ chain: ruleChain }),
-        cache: deps.ruleCache ?? makeMemoryRuleCache()
+    const { criteria, criteriaCid, chainId, registry, chain, bucketMath, nameResolvers, nameResolutionCache } = deps;
+    // Resolve every gate leaf — rule, options, memo — once: they are fixed by the criteria, so
+    // none of it is recomputed per bundle. Same for which leaves ask the same question.
+    const readHead = deps.readHead ?? (async ({ chain: client }) => ({ block: Number(await client.getBlockNumber()) }));
+    const leaves = resolveGate({ criteria, registry, chain, readHead, caches: deps.ruleCaches });
+    const { ofLeaf } = dedupeLeaves(leaves);
+    /**
+     * Score one leaf for one wallet, sharing one answer between leaves that ask the same question
+     * (`dedupeLeaves`). The per-wallet map is what makes the sharing real: the fold evaluates
+     * leaves concurrently, so two positions of one rule would otherwise both miss its memo before
+     * either wrote to it.
+     */
+    const scoreLeaf = (wallet) => {
+        const asked = new Map();
+        return (leaf) => {
+            const question = ofLeaf[leaf];
+            const already = asked.get(question);
+            if (already)
+                return already;
+            const { rule, options, ctx } = leaves[leaf];
+            const answer = rule.evaluate({ options, wallet, ctx });
+            asked.set(question, answer);
+            return answer;
+        };
     };
     // Stage 1, shared by `verify` and `verifyOffline`: signature + constraints, local and µs.
     const verifyOffline = async (bundle) => {
@@ -33,25 +39,47 @@ 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 }),
+        // The gate step on its own, against the SAME leaves/options/ctxs `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. Every leaf is scored here
+        // (`collectAll`), because naming each failure is what this call is for.
+        async checkGates({ address, sampleBlock }) {
+            // A leaf whose read FAILED is not a leaf that said no. Under an `any`, refusing the
+            // whole check because one rule's RPC timed out would tell a wallet that qualifies
+            // through another branch that it is ineligible — over an outage it cannot act on. So
+            // a failed read is folded as unknown, and only if the tree cannot be decided without
+            // it does the original error surface (never a verdict invented from a missing read).
+            let firstError;
+            let failed = false;
+            const gate = await evaluateGate({
+                node: criteria.gate,
+                evaluate: scoreLeaf({ address, sampleBlock }),
+                collectAll: true,
+                tolerateLeafErrors: true,
+                onLeafError: (_leaf, error) => {
+                    if (!failed)
+                        [failed, firstError] = [true, error];
+                }
+            });
+            if (gate.satisfied === undefined)
+                throw firstError;
+            return gate;
+        },
         async verify(bundle) {
             const offline = await verifyOffline(bundle);
             if (!offline.valid)
                 return offline;
-            // 3. Gate (chain) — the rule scores this wallet, reading and memoizing however it
-            //    sees fit. The bundle's bucketized sample block is handed over as the pinned
-            //    block the ballot names; a rule scoring current state ignores it for `ctx.head`.
+            // 3. Gate (chain) — each leaf rule scores this wallet, reading and memoizing however
+            //    it sees fit, and `all`/`any` fold the answers (rules/gate.ts). 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`. Lazy on this path: a
+            //    determined tree stops, so a composite gate costs only the leaves it needed.
             const sampleBlock = bucketMath.sampleBlockForBucket(bucketMath.bucketForBlock(bundle.blockNumber));
-            const gate = await rule.evaluate({
-                options: ruleOptions,
-                wallet: { address: bundle.address, sampleBlock },
-                ctx
+            const gate = await evaluateGate({
+                node: criteria.gate,
+                evaluate: scoreLeaf({ address: bundle.address, sampleBlock })
             });
-            const gateFailed = gateFailure(gate);
-            if (gateFailed) {
+            if (gate.satisfied !== true) {
                 // Disposition comes from the rule's own answer, never from the rule's identity.
                 // A failure the rule stands behind is identical on every honest verifier, so it is
                 // a `reject`: the sender is penalized and the verdict cached as terminal. One it
@@ -61,13 +89,16 @@ export function makeBundleVerifier(deps) {
                 // 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`.
+                // The reason is the RULES' wording, verbatim: only they know whether this wallet
+                // holds too few, holds none, or faces a contract that gates nothing, and those
+                // sentences are what reach the voter through `VoteEvictedError` — narrowed to the
+                // failures that actually explain the refusal (`gateBlame`), so a wallet is never
+                // told to go acquire something a satisfied `any` branch never needed.
                 return {
                     valid: false,
-                    disposition: gateFailed.penalize ? "reject" : "ignore",
-                    reason: `not admitted: ${gateFailed.error}`
+                    disposition: gatePenalize(gate) ? "reject" : "ignore",
+                    reason: `not admitted: ${gateReason(gate)}`,
+                    failures: gateBlame(gate).map((leaf) => ({ type: leaves[leaf.leaf].ref.type, error: leaf.error ?? "" }))
                 };
             }
             // 4. Community-name resolution (network) — a carried name is a claim, verified against
@@ -102,7 +133,7 @@ export function makeBundleVerifier(deps) {
                 }
                 resolvedNames[name] = record.publicKey;
             }
-            return { valid: true, ruleScore: scoreOrZero(gate), resolvedNames };
+            return { valid: true, resolvedNames };
         }
     };
 }

package/dist/verify/types.d.ts

@@ -1,5 +1,5 @@
 import type { VotesBundle } from "../schema/votes.js";
-import type { RuleResult } from "../rules/types.js";
+import type { GateResult } from "../rules/gate.js";
 /**
  * Verification interfaces, design only.
  *
@@ -36,6 +36,17 @@ export type VerifyFail = {
     valid: false;
     disposition: VerdictDisposition;
     reason: string;
+    /**
+     * Present when the GATE refused: one entry per rule whose failure explains the refusal
+     * (rules/gate.ts `gateBlame` — not every failed leaf, since one inside a satisfied `any`
+     * cost the wallet nothing). `reason` is these same sentences joined, kept so a caller that
+     * only renders a string needs no change; this is the structured form, so a client listing
+     * "what you are missing" never has to split one.
+     */
+    failures?: readonly {
+        type: string;
+        error: string;
+    }[];
 };
 export type VerifyResult = VerifyOk | VerifyFail;
 /** Stage 1: ballot signature only. No chain access. */
@@ -52,17 +63,20 @@ export interface OfflineBundleVerifier {
     }): 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.
+ * A passing full-bundle verdict. Beyond `valid: true` it carries the work the gate already did so
+ * downstream stages need not redo it: `resolvedNames` maps each vote that carried a
+ * `community.name` to 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.
+ *
+ * The gate's folded SCORE is deliberately not here. Nothing downstream reads it — a vote's
+ * magnitude comes from `criteria.weight`, never from the gate — and a number no one consumes grows
+ * semantics by accident, which a min-across-`all` fold over unrelated rules ("holds 5" and "not
+ * banned = 1") cannot survive. A client that wants per-rule scores asks `checkEligibility`, which
+ * reports each leaf's own.
  */
 export interface BundleVerdictValid {
     valid: true;
-    ruleScore: bigint;
     resolvedNames: Record<string, string>;
 }
 /**
@@ -85,25 +99,32 @@ export interface BundleVerifier {
      */
     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.
+     * Step 3 alone, for a wallet rather than a bundle: score EVERY leaf of the gate tree and hand
+     * back the folded {@link GateResult}. Backs `Contest.checkEligibility`, so a client can ask
+     * "would this vote count?" through the very same rule instances, options, chain clients, head
+     * reader and memos the forward gate uses — never a reimplementation of them.
+     *
+     * Unlike `verify`, this never short-circuits: a caller asking which rules a wallet fails needs
+     * all of their answers, not just the first one that settled the outcome.
+     *
+     * Also unlike `verify`, a leaf whose chain read THROWS does not fail the call outright — it is
+     * folded as unknown, so a wallet admitted by a branch that did answer still gets its answer.
+     * The error is re-thrown only when the tree cannot be decided without that leaf.
      *
      * `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: {
+    checkGates(args: {
         address: string;
         sampleBlock: number;
-    }): Promise<RuleResult>;
+    }): Promise<GateResult>;
 }
 /**
  * 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`
+ *   - `chainVerified`: the gate admitted the wallet 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitsocial/pubsub-voting",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Trustless pubsub voting over a shared libp2p/Helia node.",
   "type": "module",
   "license": "GPL-3.0-or-later",

package/dist/chain/ticker.d.ts

@@ -1,15 +0,0 @@
-import type { Criteria, RuleRef } from "../schema/criteria.js";
-/**
- * Resolve which chain a rule reads. A rule's parsed options may name a
- * `chain` ticker (e.g. `erc5192-min-balance` -> "base"); a chainless rule (e.g.
- * `constant`) names none, so callers fall back to the first configured chain. Shared by the
- * verifier, the tally, and the facade so the fallback rule stays identical everywhere.
- */
-/** The `chain` ticker named in a rule's parsed options, or `undefined` if none. */
-export declare function chainTickerOf(options: unknown): string | undefined;
-/**
- * The chain ticker a rule ref uses: its own `chain` option, else the first chain in
- * `requires.chains`. Throws if neither exists (a chainless rule with no configured
- * chains cannot be read).
- */
-export declare function tickerForRef(criteria: Criteria, ref: RuleRef, options: unknown): string;

package/dist/chain/ticker.js

@@ -1,25 +0,0 @@
-import { z } from "zod";
-/**
- * Resolve which chain a rule reads. A rule's parsed options may name a
- * `chain` ticker (e.g. `erc5192-min-balance` -> "base"); a chainless rule (e.g.
- * `constant`) names none, so callers fall back to the first configured chain. Shared by the
- * verifier, the tally, and the facade so the fallback rule stays identical everywhere.
- */
-/** The `chain` ticker named in a rule's parsed options, or `undefined` if none. */
-export function chainTickerOf(options) {
-    const parsed = z.object({ chain: z.string().min(1) }).safeParse(options);
-    return parsed.success ? parsed.data.chain : undefined;
-}
-/**
- * The chain ticker a rule ref uses: its own `chain` option, else the first chain in
- * `requires.chains`. Throws if neither exists (a chainless rule with no configured
- * chains cannot be read).
- */
-export function tickerForRef(criteria, ref, options) {
-    const ticker = chainTickerOf(options) ?? Object.keys(criteria.requires.chains)[0];
-    if (!ticker) {
-        throw new Error(`criteria rule "${ref.type}" names no chain and requires.chains is empty; ` +
-            `cannot resolve a chain client to read it`);
-    }
-    return ticker;
-}