@bitsocial/pubsub-voting 0.1.0 → 0.1.2

package/README.md

@@ -81,7 +81,7 @@ Construction throws `MissingPubsubError`, `MissingBlockstoreError`, or `MissingF
 ```ts
 const contest = await voter.createContest({ criteria });  // criteria: the contest's full document (strictly validated here)
 contest.on("update", () => render(contest.tally));        // tally rides the object; recomputed before each emit
-contest.on("error", (err) => showConnectivityWarning(err)); // tally chain read failed, or the background verifier's RPC/resolver is down (retrying)
+contest.on("error", (err) => showConnectivityWarning(err)); // tally chain read failed, the background verifier's RPC/resolver is down (retrying), or a deferred check evicted THIS wallet's own vote (VoteEvictedError)
 await contest.update();                                   // join the topic, cold-start, begin emitting
 // const fresh = await contest.getTally();                // or force a fresh read, bypassing the cache
 // await contest.stop();                                  // leave the topic
@@ -128,6 +128,20 @@ A community's identity is its `publicKey`. The optional `name` is the community'
 
 `publish()` on a voter built without a `signer` throws `ReadOnlyError` (and emits an `error`).
 
+#### Rejection feedback
+
+Gossipsub gives a publisher **no acceptance or rejection feedback** — a peer that drops a bundle does so silently. Since every honest peer runs the same checks this node runs, the library turns its own local verdict into the feedback the protocol can't provide, in two places:
+
+- **At `publish()`**: each vote's `community.name` is preflighted through the shared resolution cache first — a name that definitively fails (no resolver for its TLD, no record, or it resolves to a **different** `publicKey` than the vote claims) throws `InvalidCommunityNameError` before signing or joining the topic, since every verifier would silently drop that bundle anyway. A resolver that merely *throws* (registry outage) never blocks the publish — the check stays deferred to the background verifier.
+- **After `publish()` resolved**: `"succeeded"` means signed and broadcast, **not** accepted by the network. The deferred checks (the on-chain gate read, and any name resolution a preflight outage skipped) run in the background; if one evicts the bundle, the vote emits a `VoteEvictedError` on its `error` event — carrying the evicted `bundle` and the exact `verdict` any verifier would produce — and its `publishingState` flips to `"failed"` post hoc. The same error fires on the contest's `error` event, for long-lived views.
+
+```ts
+vote.on("error", (err) => {
+    if (err instanceof VoteEvictedError) console.log(err.verdict.reason); // e.g. "not admitted: rule score is 0n at block …"
+});
+await vote.publish(); // throws InvalidCommunityNameError if a carried name can't back the vote
+```
+
 ### Republishing is the client's job
 
 A vote is not permanent: a bundle is valid only for `voteExpiryBuckets` after its `blockNumber`, so a live vote must be re-published before it decays. **This library does not do that automatically** — it publishes each vote once and the consuming client decides when (or whether) to refresh. To refresh, just `createContestVote(...).publish()` again; a new bundle at the current bucket supersedes the old one. To stop, simply stop refreshing and let the vote lapse. The library gives you what you need to schedule it — all pure, no chain reads:

package/dist/client/voter.d.ts

@@ -41,7 +41,14 @@ export declare function republishIntervalBuckets(criteria: Criteria): number;
  * publishes each vote once and the client decides when to refresh (see
  * {@link republishIntervalBuckets} and DESIGN.md "Republishing is the client's job").
  */
-/** A vote publication's lifecycle, walked by {@link ContestVote.publish}. */
+/**
+ * A vote publication's lifecycle, walked by {@link ContestVote.publish}. `"succeeded"` means
+ * signed, admitted locally, and broadcast — NOT accepted by the network (gossipsub gives a
+ * publisher no acceptance/rejection feedback). It can therefore still flip to `"failed"`
+ * afterwards: if this node's own deferred checks — the same checks every peer runs — evict the
+ * bundle, the vote emits a `VoteEvictedError` and fails post hoc (see DESIGN.md "Background
+ * chain verification", publisher feedback).
+ */
 export type PublishingState = "stopped" | "signing" | "publishing" | "succeeded" | "failed";
 /** What {@link ContestVote.publish} resolves: the signed bundle plus a peer-reach hint. */
 export interface PublishOutcome {
@@ -86,9 +93,11 @@ export interface Contest {
      */
     on(event: "update", cb: () => void): void;
     /**
-     * Fired on a contest-level failure: the tally's chain read throws, or the background chain
+     * Fired on a contest-level failure: the tally's chain read throws, the background chain
      * verifier hits an infra-class failure (RPC/resolver down — its bundles stay pending and
-     * retry, but the degradation is surfaced here instead of silently stalling).
+     * retry, but the degradation is surfaced here instead of silently stalling), or a deferred
+     * check evicts THIS wallet's own published vote (`VoteEvictedError` — the same error the
+     * publishing `ContestVote` emits; here so a long-lived view hears it too).
      */
     on(event: "error", cb: (error: unknown) => void): void;
 }
@@ -110,13 +119,23 @@ export interface ContestVote {
      * the `VotesBundle` (whose `blockNumber` the client uses to schedule its own refresh — see
      * {@link republishIntervalBuckets}) plus `recipientCount`, the number of peers gossipsub sent
      * the vote directly to. Emits `publishingstatechange` as it goes; throws (and emits `error`) on
-     * failure, and `ReadOnlyError` with no signer. This library does not re-publish: to keep the
-     * vote alive, call `publish()` again before it expires.
+     * failure: `ReadOnlyError` with no signer, and `InvalidCommunityNameError` when a vote's
+     * carried `community.name` definitively does not resolve to its claimed `publicKey` (checked
+     * BEFORE signing or joining — every verifier drops such a bundle silently, so it is refused
+     * here instead of published into a network-wide silent drop; a resolver outage does not block
+     * the publish). This library does not re-publish: to keep the vote alive, call `publish()`
+     * again before it expires.
      */
     publish(): Promise<PublishOutcome>;
     /** Fired on each `publishingState` transition. */
     on(event: "publishingstatechange", cb: (state: PublishingState) => void): void;
-    /** Fired if publishing fails. */
+    /**
+     * Fired if publishing fails — including POST HOC, after `publish()` resolved: gossipsub
+     * peers reject a bad bundle silently, but this node runs the same deferred checks (gate
+     * chain read, name resolution) on its own publish, and if they evict it a `VoteEvictedError`
+     * fires here (and `publishingState` flips to `"failed"`) carrying the exact verdict every
+     * honest verifier would produce. See DESIGN.md "Background chain verification".
+     */
     on(event: "error", cb: (error: unknown) => void): void;
 }
 /** The factory: one set of injected dependencies, many contests. */

package/dist/client/voter.js

@@ -23,6 +23,7 @@ import { makeAnnouncer } from "../transport/announce/node.js";
 import { encode as encodeDagCbor } from "@ipld/dag-cbor";
 import { sha256 } from "viem";
 import { makeBackgroundVerifier } from "../verify/background.js";
+import { preflightCommunityNames } from "../verify/name-preflight.js";
 import { makeAcceptedDedup } from "../transport/accepted-dedup.js";
 import { blockForBytes, decodeCheckpoint, encodeCheckpoint } from "../checkpoint/codec.js";
 import { decodeSnapshot, encodeSnapshot } from "../checkpoint/snapshot.js";
@@ -30,7 +31,7 @@ import { CID } from "multiformats/cid";
 import { makeTally } from "../tally/tally.js";
 import { ballotTypedData } from "../signer/eip712.js";
 import { criteriaCid, TOPIC_PREFIX } from "../topic.js";
-import { MissingChainClientError, ReadOnlyError, UnknownRuleError, VoterDestroyedError } from "../errors.js";
+import { InvalidCommunityNameError, MissingChainClientError, ReadOnlyError, UnknownRuleError, VoteEvictedError, VoterDestroyedError } from "../errors.js";
 /**
  * The recommended cadence, in buckets, at which a client should re-publish a live vote to keep
  * it alive: half its expiry window, rounded up. A bundle is valid for `voteExpiryBuckets` after
@@ -348,7 +349,7 @@ class ContestEngine {
             cache: this.#cache,
             onGateVerified: (cid) => this.#settleCheck(cid, "chainVerified"),
             onNameResolved: (cid) => this.#settleCheck(cid, "nameResolved"),
-            onEvict: (cid) => this.#evictBundle(cid),
+            onEvict: (cid, verdict) => this.#evictBundle(cid, verdict),
             onError: (error) => this.#emitError(error),
             limit: (fn) => this.#backgroundLimit(fn)
         });
@@ -382,13 +383,26 @@ class ContestEngine {
      * settled bundles (never re-serve what we have not verified).
      */
     #checks = new Map();
+    /**
+     * This wallet's own published bundles still awaiting their deferred checks, keyed by CID
+     * string — the bundles whose background EVICTION must be reported instead of silent (see
+     * {@link #evictBundle} / `VoteEvictedError`; remote evictions are normal operation). An
+     * entry is dropped once its checks settle, on evict (after reporting), and on expiry prune.
+     */
+    #ownPublishes = new Map();
+    /** Per-own-CID eviction callbacks: the publishing `ContestVote` registers one at sign time. */
+    #ownEvictionCbs = new Map();
     /** Does any vote in the bundle carry a `community.name` claim (needing resolution)? */
     #carriesName(bundle) {
         return bundle.votes.some((v) => v.community.name !== undefined);
     }
-    /** Record a bundle's deferred-check state at admit: fully settled, or pending both checks. */
-    #recordChecks(cid, bundle, settled) {
-        this.#checks.set(cid.toString(), this.#carriesName(bundle) ? { chainVerified: settled, nameResolved: settled } : { chainVerified: settled });
+    /**
+     * Record a bundle's deferred-check state at admit: fully settled, pending both checks, or —
+     * for an own publish whose name preflight already resolved every carried name — pending the
+     * gate read only (`nameSettled`).
+     */
+    #recordChecks(cid, bundle, settled, nameSettled = settled) {
+        this.#checks.set(cid.toString(), this.#carriesName(bundle) ? { chainVerified: settled, nameResolved: nameSettled } : { chainVerified: settled });
     }
     /** The bundle's check state, pessimistic (all pending) if somehow unrecorded. */
     #checksFor(cid, bundle) {
@@ -411,14 +425,38 @@ class ContestEngine {
         if (!checks)
             return; // evicted or pruned while its check was in flight
         checks[key] = true;
+        // A fully settled own publish can no longer be evicted — its verdict is terminal — so
+        // its eviction-reporting entries are done (see #ownPublishes).
+        if (this.#isFullyVerified(cid))
+            this.#dropOwnTracking(cid.toString());
         this.#onStateChanged();
     }
-    /** A deferred check failed: drop the bundle (its verified predecessor, if any, wins again). */
-    #evictBundle(cid) {
+    /**
+     * A deferred check failed: drop the bundle (its verified predecessor, if any, wins again).
+     * Evicting this wallet's OWN publish is the one rejection a publisher can ever hear about —
+     * gossipsub peers drop a bad bundle silently, but this node runs the same checks (see
+     * DESIGN.md "Background chain verification") — so it is reported as a `VoteEvictedError`
+     * through the publishing `ContestVote` and the contest `error` event instead of silent.
+     */
+    #evictBundle(cid, verdict) {
         this.#crdt.remove(cid);
-        this.#checks.delete(cid.toString());
+        const key = cid.toString();
+        this.#checks.delete(key);
+        const own = this.#ownPublishes.get(key);
+        if (own) {
+            const error = new VoteEvictedError(own, verdict);
+            const notifyVote = this.#ownEvictionCbs.get(key);
+            this.#dropOwnTracking(key);
+            notifyVote?.(error);
+            this.#emitError(error);
+        }
         this.#onStateChanged();
     }
+    /** Forget an own publish's eviction-reporting entries (settled, evicted, or expired). */
+    #dropOwnTracking(key) {
+        this.#ownPublishes.delete(key);
+        this.#ownEvictionCbs.delete(key);
+    }
     #emitError(error) {
         for (const cb of [...this.#errorListeners])
             cb(error);
@@ -527,7 +565,9 @@ class ContestEngine {
         if (this.#crdt.nodeCount() > 0) {
             await this.#refreshBucket();
             for (const removed of await this.#crdt.prune(this.#currentBucketCache)) {
-                this.#checks.delete(removed.toString());
+                const key = removed.toString();
+                this.#checks.delete(key);
+                this.#dropOwnTracking(key); // expiry is decay, not an eviction — no error
             }
         }
         return this.#tally.compute();
@@ -897,12 +937,33 @@ class ContestEngine {
         if (wasJoined)
             this.#deps.onTopicLeft();
     }
+    /**
+     * Publish-time community-name preflight (see verify/name-preflight.ts): throws
+     * `InvalidCommunityNameError` when a carried name definitively fails to resolve to its
+     * vote's claimed key — before signing, before the caller joins the topic — because every
+     * verifier would silently drop such a bundle. Returns whether every carried name settled
+     * (false = a resolver outage skipped one; the background verifier still owns that check).
+     */
+    async preflightNames(votes) {
+        const result = await preflightCommunityNames({
+            votes,
+            nameResolvers: this.#deps.nameResolvers,
+            cache: this.#deps.nameResolutionCache
+        });
+        if (!result.ok) {
+            throw new InvalidCommunityNameError(result.communityName, result.claimedPublicKey, result.resolvedPublicKey, result.reason);
+        }
+        return result.settled;
+    }
     /**
      * Sign the votes into a bundle for the current bucket boundary block (the block every verifier
      * reads at), add it to the CRDT, and return the bundle plus its encoded block bytes for
-     * broadcast. Throws `ReadOnlyError` with no signer.
+     * broadcast. Throws `ReadOnlyError` with no signer. `namesSettled` carries the
+     * {@link preflightNames} outcome (default false: name checks still owed to the background
+     * verifier); `onEvicted` is told if a deferred check later evicts THIS bundle — registered
+     * here, before the background verifier can possibly settle, so the report cannot be missed.
      */
-    async signVote(votes) {
+    async signVote(votes, opts = {}) {
         const signer = this.#deps.signer;
         if (signer === undefined)
             throw new ReadOnlyError();
@@ -918,8 +979,12 @@ class ContestEngine {
         // Own bundles take the same deferred path as a chased checkpoint's: admitted
         // provisionally, then confirmed (or evicted) by the background gate read — so an
         // ineligible wallet's local tally does not silently disagree with the network's, and
-        // our checkpoint never serves a vote we have not verified (even our own).
-        this.#recordChecks(cid, bundle, false);
+        // our checkpoint never serves a vote we have not verified (even our own). A name the
+        // preflight already resolved is recorded settled, so it renders verified immediately.
+        this.#recordChecks(cid, bundle, false, opts.namesSettled ?? false);
+        this.#ownPublishes.set(cid.toString(), bundle);
+        if (opts.onEvicted)
+            this.#ownEvictionCbs.set(cid.toString(), opts.onEvicted);
         this.#background.enqueue([{ cid, bundle }]);
         this.#onStateChanged();
         return { bundle, encoded: encodeBundle(bundle) };
@@ -1266,6 +1331,13 @@ class ContestVotePublication {
     #errorCbs = [];
     #state = "stopped";
     #bundle;
+    /**
+     * True once the background verifier evicted the current publish's bundle. The eviction can
+     * land WHILE `publish()` is still broadcasting (the deferred checks run concurrently), and
+     * its `"failed"` is terminal for this attempt — the in-flight publish must not stomp it
+     * with `"publishing"`/`"succeeded"`. Reset by the next `publish()` call.
+     */
+    #evicted = false;
     constructor(engine, votes) {
         this.#engine = engine;
         this.contestId = engine.criteria.contestId;
@@ -1298,13 +1370,33 @@ class ContestVotePublication {
             throw error;
         }
         try {
+            // Name preflight, also before joining: a vote whose carried community name
+            // definitively fails to resolve to its claimed key would be silently dropped by
+            // every verifier, so it is refused here (`InvalidCommunityNameError`) instead of
+            // broadcast. A resolver outage does not block the publish (namesSettled: false —
+            // the background verifier owns the deferred check).
+            const namesSettled = await this.#engine.preflightNames(this.votes);
             await this.#engine.join();
+            this.#evicted = false;
             this.#setState("signing");
-            const { bundle, encoded } = await this.#engine.signVote([...this.votes]);
+            const { bundle, encoded } = await this.#engine.signVote([...this.votes], {
+                namesSettled,
+                // The one rejection a publisher can hear about (peers drop silently): our own
+                // node's deferred checks evicting this bundle. Usually post hoc — publish() has
+                // already resolved — so it surfaces as `error` + `publishingState: "failed"`.
+                onEvicted: (error) => {
+                    this.#evicted = true;
+                    this.#fail(error);
+                }
+            });
             this.#bundle = bundle;
-            this.#setState("publishing");
+            if (!this.#evicted)
+                this.#setState("publishing");
             const { recipientCount } = await this.#engine.broadcastBundle(encoded);
-            this.#setState("succeeded");
+            // An eviction that landed mid-broadcast already failed this attempt; the outcome
+            // still resolves (the bundle DID hit the wire) but the state stays "failed".
+            if (!this.#evicted)
+                this.#setState("succeeded");
             return { bundle, recipientCount };
         }
         catch (error) {

package/dist/errors.d.ts

@@ -1,3 +1,5 @@
+import type { VotesBundle } from "./schema/votes.js";
+import type { VerifyFail } from "./verify/types.js";
 /**
  * Library error types.
  *
@@ -91,3 +93,51 @@ export declare class DuplicateContestIdError extends Error {
 export declare class ReadOnlyError extends Error {
     constructor();
 }
+/**
+ * Thrown by `ContestVote.publish()` when a vote carries a `community.name` that definitively
+ * fails the publish-time preflight (see verify/name-preflight.ts): no configured resolver
+ * handles it, it resolves to no record, or it resolves to a DIFFERENT key than the vote
+ * claims. Every honest verifier runs the same check and drops such a bundle without telling
+ * the publisher (gossipsub has no rejection feedback), so the vote is refused here — before
+ * signing, before joining the topic — instead of being published into a silent network-wide
+ * drop. Fix the name (or the claimed `publicKey`) and publish again. A resolver that merely
+ * THREW (registry outage) does not throw this: the vote publishes and the background verifier
+ * settles the check, surfacing a `VoteEvictedError` if it turns out bad.
+ */
+export declare class InvalidCommunityNameError extends Error {
+    /** The offending `community.name`. */
+    readonly communityName: string;
+    /** The `community.publicKey` the vote claims the name points at. */
+    readonly claimedPublicKey: string;
+    /** What the registry resolved the name to; `undefined` for no-resolver / no-record. */
+    readonly resolvedPublicKey: string | undefined;
+    constructor(
+    /** The offending `community.name`. */
+    communityName: string, 
+    /** The `community.publicKey` the vote claims the name points at. */
+    claimedPublicKey: string, 
+    /** What the registry resolved the name to; `undefined` for no-resolver / no-record. */
+    resolvedPublicKey: string | undefined, reason: string);
+}
+/**
+ * Emitted (never thrown) when a deferred network check EVICTS this wallet's own published
+ * vote: the background verifier read the gate rule as `0n` at the vote's sample block, or its
+ * carried community name did not check out (see DESIGN.md "Background chain verification").
+ * `publish()` resolves on the offline checks, so an own vote that fails a deferred check
+ * would otherwise just silently vanish from the local tally — while every honest peer,
+ * running the same checks, drops it with no feedback (gossipsub has no rejection channel).
+ * This error is that missing feedback, built from the local verdict: it fires on the
+ * publishing `ContestVote`'s `error` event (flipping its `publishingState` to `"failed"`)
+ * and on the contest's `error` event. Carries the evicted bundle and the exact verdict.
+ */
+export declare class VoteEvictedError extends Error {
+    /** The signed bundle that was evicted (the one `publish()` resolved with). */
+    readonly bundle: VotesBundle;
+    /** The failing verdict, with the same `reason` wording every verifier produces. */
+    readonly verdict: VerifyFail;
+    constructor(
+    /** The signed bundle that was evicted (the one `publish()` resolved with). */
+    bundle: VotesBundle, 
+    /** The failing verdict, with the same `reason` wording every verifier produces. */
+    verdict: VerifyFail);
+}

package/dist/errors.js

@@ -144,3 +144,64 @@ export class ReadOnlyError extends Error {
         this.name = "ReadOnlyError";
     }
 }
+/**
+ * Thrown by `ContestVote.publish()` when a vote carries a `community.name` that definitively
+ * fails the publish-time preflight (see verify/name-preflight.ts): no configured resolver
+ * handles it, it resolves to no record, or it resolves to a DIFFERENT key than the vote
+ * claims. Every honest verifier runs the same check and drops such a bundle without telling
+ * the publisher (gossipsub has no rejection feedback), so the vote is refused here — before
+ * signing, before joining the topic — instead of being published into a silent network-wide
+ * drop. Fix the name (or the claimed `publicKey`) and publish again. A resolver that merely
+ * THREW (registry outage) does not throw this: the vote publishes and the background verifier
+ * settles the check, surfacing a `VoteEvictedError` if it turns out bad.
+ */
+export class InvalidCommunityNameError extends Error {
+    communityName;
+    claimedPublicKey;
+    resolvedPublicKey;
+    constructor(
+    /** The offending `community.name`. */
+    communityName, 
+    /** The `community.publicKey` the vote claims the name points at. */
+    claimedPublicKey, 
+    /** What the registry resolved the name to; `undefined` for no-resolver / no-record. */
+    resolvedPublicKey, reason) {
+        super(`Cannot publish this vote: ${reason}. Every verifier checks a carried community ` +
+            `name against its registry and silently drops a bundle whose name does not ` +
+            `resolve to the claimed publicKey, so this vote would never be counted. Fix ` +
+            `the name (or the claimed publicKey), or drop the name from the vote, and ` +
+            `publish again.`);
+        this.communityName = communityName;
+        this.claimedPublicKey = claimedPublicKey;
+        this.resolvedPublicKey = resolvedPublicKey;
+        this.name = "InvalidCommunityNameError";
+    }
+}
+/**
+ * Emitted (never thrown) when a deferred network check EVICTS this wallet's own published
+ * vote: the background verifier read the gate rule as `0n` at the vote's sample block, or its
+ * carried community name did not check out (see DESIGN.md "Background chain verification").
+ * `publish()` resolves on the offline checks, so an own vote that fails a deferred check
+ * would otherwise just silently vanish from the local tally — while every honest peer,
+ * running the same checks, drops it with no feedback (gossipsub has no rejection channel).
+ * This error is that missing feedback, built from the local verdict: it fires on the
+ * publishing `ContestVote`'s `error` event (flipping its `publishingState` to `"failed"`)
+ * and on the contest's `error` event. Carries the evicted bundle and the exact verdict.
+ */
+export class VoteEvictedError extends Error {
+    bundle;
+    verdict;
+    constructor(
+    /** The signed bundle that was evicted (the one `publish()` resolved with). */
+    bundle, 
+    /** The failing verdict, with the same `reason` wording every verifier produces. */
+    verdict) {
+        super(`This wallet's published vote failed a deferred verification check and was ` +
+            `evicted from the local tally: ${verdict.reason}. Honest peers run the same ` +
+            `checks, so the network will not count this vote either. Fix the cause and ` +
+            `publish again.`);
+        this.bundle = bundle;
+        this.verdict = verdict;
+        this.name = "VoteEvictedError";
+    }
+}

package/dist/transport/integration/harness.d.ts

@@ -6,7 +6,7 @@ import type { VoteCrdt } from "../../crdt/types.js";
 import { type VerdictCache } from "../../verify/cache.js";
 import { type RootChaser } from "../chase.js";
 import type { PubsubService, VoteTransport } from "../types.js";
-import { type RootRecord } from "../messages.js";
+import { type FetchRootRecord, type RootRecord } from "../messages.js";
 /** The gossipsub peer-score methods used for assertions — on the concrete class, not the interface. */
 interface ScoreOps {
     getScore(peer: string): number;
@@ -41,7 +41,13 @@ export interface VoteNode {
     /** Replace the injected verifier (e.g. a rejecter, or a slow one, for a specific assertion). */
     setVerifier(verify: (bundle: VotesBundle) => Promise<BundleVerdict>): void;
     /** Encode this node's current winner-set to a checkpoint (blocks written to its blockstore). */
-    checkpointRootRecord(): Promise<RootRecord>;
+    checkpointRootRecord(): Promise<FetchRootRecord>;
+    /**
+     * Pull `from`'s root record over the REAL libp2p fetch protocol — the cold-start pull a
+     * joiner makes before chasing (voter.ts `#fetchRootWithRetry`). `undefined` when the peer
+     * serves nothing for the key.
+     */
+    fetchRootRecord(from: VoteNode): Promise<FetchRootRecord | undefined>;
     /** Publish this node's own root record on the topic (a heartbeat). */
     publishOwnRoot(): Promise<void>;
     /** Seed a bundle straight into this node's state (store block + CRDT merge), no network. */

package/dist/transport/integration/harness.js

@@ -17,7 +17,7 @@ import { encodeCheckpoint } from "../../checkpoint/codec.js";
 import { makeGossipGate } from "../gossip-validator.js";
 import { makeRootChaser, toChaseSession } from "../chase.js";
 import { makeVoteTransport } from "../transport.js";
-import { decodeVoteMessage, maxBundleMessageBytes, MAX_ROOT_MESSAGE_BYTES, ROOT_RECORD_VERSION } from "../messages.js";
+import { decodeVoteMessage, decodeRootRecord, encodeRootRecord, maxBundleMessageBytes, rootFetchKey, MAX_ROOT_MESSAGE_BYTES, ROOT_RECORD_VERSION } from "../messages.js";
 /**
  * Test harness for the two-node gossipsub integration test. It stands up ONE real libp2p +
  * Helia node carrying `@libp2p/gossipsub` (>= 15.0.23, the CVE-2026-46679 floor) and
@@ -117,16 +117,30 @@ export async function makeVoteNode(topic, options = {}) {
     let matchedOwnRoot = false;
     async function checkpointRootRecord() {
         const winners = crdt.current(CURRENT_BUCKET);
-        const { root, blocks } = await encodeCheckpoint(winners);
+        const { root, chunks, blocks } = await encodeCheckpoint(winners);
         for (const block of blocks)
             await blockstore.put(block.cid, block.bytes);
         return {
             version: ROOT_RECORD_VERSION,
             root,
+            chunks,
             count: winners.length,
             sizeBytes: blocks.reduce((total, block) => total + block.bytes.length, 0)
         };
     }
+    // Mirror the production fetch responder (voter.ts `#rootLookup`): answer `<topic>/root` with
+    // this node's current root record, encoded on demand — the surface a cold joiner pulls
+    // before chasing. `@libp2p/fetch` hands the lookup the requested key as raw bytes.
+    libp2p.services.fetch.registerLookupFunction(topic, async (keyBytes) => {
+        if (new TextDecoder().decode(keyBytes) !== rootFetchKey(topic))
+            return undefined;
+        try {
+            return encodeRootRecord(await checkpointRootRecord());
+        }
+        catch {
+            return undefined;
+        }
+    });
     const openedSessions = [];
     const chaseLimit = pLimit(2);
     const chaser = makeRootChaser({
@@ -228,6 +242,10 @@ export async function makeVoteNode(topic, options = {}) {
             verifyImpl = verify;
         },
         checkpointRootRecord,
+        fetchRootRecord: async (from) => {
+            const bytes = await libp2p.services.fetch.fetch(from.libp2p.peerId, rootFetchKey(topic));
+            return bytes == null ? undefined : decodeRootRecord(bytes);
+        },
         publishOwnRoot: async () => {
             await transport.publishRootRecord(await checkpointRootRecord());
         },

package/dist/verify/name-preflight.d.ts

@@ -0,0 +1,60 @@
+import type { Vote } from "../schema/votes.js";
+import type { NameResolver } from "../chain/types.js";
+import { type NameResolutionCache } from "./name-resolution-cache.js";
+/**
+ * Publish-time community-name preflight — the publisher-side twin of the verify pipeline's
+ * step 4 (see bundle.ts). Gossipsub has no rejection-feedback channel: a peer that drops a
+ * bundle never tells the publisher why (or that it dropped it at all), so the only "clear
+ * error" a publisher can ever get is from running the same checks locally BEFORE the vote
+ * hits the wire. A vote naming a community whose name does not check out is guaranteed to be
+ * dropped by every honest verifier, so publishing it is pure waste; failing fast here turns
+ * that silent network-wide drop into an immediate, explainable publish error.
+ *
+ * The failure split mirrors the pipeline's `reject`/`ignore` philosophy, adapted to the
+ * publisher (who, unlike a relayer, can always just fix the vote and retry):
+ *   - definitive from this node's view — no resolver handles the TLD, the name has no record,
+ *     or it resolves to a DIFFERENT key than the vote claims — fails the preflight; every
+ *     verifier sharing this node's view would drop the bundle the same way.
+ *   - transient — the resolver THREW (registry RPC down) — passes the preflight with
+ *     `settled: false`: a resolver outage must not block voting (the same reason the
+ *     background verifier retries instead of evicting on a throw), and the deferred check
+ *     settles or evicts the bundle once the resolver recovers.
+ *
+ * Resolutions ride the shared {@link NameResolutionCache} (the pkc-js rule, 1-hour max-age),
+ * so a preflight-resolved name is a cache hit for the background verifier's own pass — the
+ * preflight adds at most one live registry read per name per hour, not a second read path.
+ */
+/** One name that definitively failed the preflight (the first failure aborts the scan). */
+export interface NamePreflightFailure {
+    ok: false;
+    communityName: string;
+    /** The `community.publicKey` the vote claims the name points at. */
+    claimedPublicKey: string;
+    /** What the registry actually resolved the name to; absent for no-resolver / no-record. */
+    resolvedPublicKey?: string;
+    /** Human-readable cause, same wording as the verify pipeline's step-4 verdicts. */
+    reason: string;
+}
+export type NamePreflightResult = {
+    ok: true;
+    /**
+     * True when every carried name resolved to its claimed key right now; false when at
+     * least one resolution was SKIPPED on a resolver throw (transient outage) and is
+     * still owed to the background verifier. Feeds the publisher's own
+     * `nameResolved` check state, so a preflight-settled vote renders verified
+     * immediately instead of flashing a pending row.
+     */
+    settled: boolean;
+} | NamePreflightFailure;
+/**
+ * Resolve every distinct `community.name` carried by `votes` and check each against its
+ * vote's claimed `publicKey`. Returns the first definitive failure, or `ok` with whether
+ * every name settled (see module doc for the definitive/transient split). Votes carrying no
+ * name are free: no resolver is consulted and `{ ok: true, settled: true }` returns
+ * synchronously.
+ */
+export declare function preflightCommunityNames(opts: {
+    votes: readonly Vote[];
+    nameResolvers: NameResolver[];
+    cache: NameResolutionCache | undefined;
+}): Promise<NamePreflightResult>;

package/dist/verify/name-preflight.js

@@ -0,0 +1,52 @@
+import { resolveNameThroughCache } from "./name-resolution-cache.js";
+/**
+ * Resolve every distinct `community.name` carried by `votes` and check each against its
+ * vote's claimed `publicKey`. Returns the first definitive failure, or `ok` with whether
+ * every name settled (see module doc for the definitive/transient split). Votes carrying no
+ * name are free: no resolver is consulted and `{ ok: true, settled: true }` returns
+ * synchronously.
+ */
+export async function preflightCommunityNames(opts) {
+    const { votes, nameResolvers, cache } = opts;
+    let settled = true;
+    for (const v of votes) {
+        const name = v.community.name;
+        if (!name)
+            continue;
+        const resolver = nameResolvers.find((r) => r.canResolve({ name }));
+        if (!resolver) {
+            return {
+                ok: false,
+                communityName: name,
+                claimedPublicKey: v.community.publicKey,
+                reason: `no resolver handles community name "${name}"`
+            };
+        }
+        let record;
+        try {
+            record = await resolveNameThroughCache({ resolver, name, cache });
+        }
+        catch {
+            settled = false; // transient registry outage — never blocks a publish
+            continue;
+        }
+        if (!record) {
+            return {
+                ok: false,
+                communityName: name,
+                claimedPublicKey: v.community.publicKey,
+                reason: `community name "${name}" does not resolve`
+            };
+        }
+        if (record.publicKey !== v.community.publicKey) {
+            return {
+                ok: false,
+                communityName: name,
+                claimedPublicKey: v.community.publicKey,
+                resolvedPublicKey: record.publicKey,
+                reason: `community name "${name}" resolves to ${record.publicKey}, not the claimed ${v.community.publicKey}`
+            };
+        }
+    }
+    return { ok: true, settled };
+}

package/package.json

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