@bitsocial/pubsub-votes 0.0.2

package/dist/transport/announce/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Provider-record announcer types (see DESIGN.md "Deferred pkc-js work", provider-record
+ * announces). The announcer is the write side of the delegated-routing seam: querying rides the
+ * injected node's `libp2p.contentRouting` (the host wires its routers into `libp2p.services`), but
+ * the pinned js stack has NO working announce path — `@helia/delegated-routing-v1-http-api-client`'s
+ * `provide()` is a literal noop — so provider records only get written by a direct
+ * `PUT /routing/v1/providers` to each router. This library is the node that actually holds the
+ * state (topic membership, fetch responder, blockstore), so its records are always truthful and
+ * current; `PubsubVoterOptions.httpRouterUrls` exists ONLY because announcing cannot ride the
+ * `contentRouting` seam.
+ *
+ * The implementation is Node-only: the browser build swaps `node.js` for the inert `browser.js`
+ * stub via the package.json `browser` field (the same remap as `src/storage/`), because a browser
+ * peer is not dialable and must never announce.
+ */
+/**
+ * The slice of the injected node's libp2p the announcer reads, declared structurally (a running
+ * `Libp2p` satisfies it). `self:peer:update` fires when the node's address set changes — an
+ * AutoTLS certificate landing, a WebRTC-Direct certhash rotation — and triggers a re-announce so
+ * records never carry stale addresses for more than a debounce window.
+ */
+export interface AnnouncerLibp2p {
+    peerId: {
+        toString(): string;
+    };
+    getMultiaddrs(): Array<{
+        toString(): string;
+    }>;
+    addEventListener(type: "self:peer:update", listener: () => void): void;
+    removeEventListener(type: "self:peer:update", listener: () => void): void;
+}
+export interface AnnouncerOptions {
+    /** Delegated Routing V1 base URLs to PUT provider records to. Empty means never announce. */
+    routerUrls: readonly string[];
+    /** The injected node's libp2p (peer id, current addresses, address-change events). */
+    libp2p: AnnouncerLibp2p;
+    /**
+     * The CIDs to announce, collected fresh per tick: every joined contest's criteria CID plus its
+     * current checkpoint root + chunk CIDs, batched into ONE record (`Keys` is an array) so a
+     * directory host costs one request per router per tick. An empty list skips the tick.
+     */
+    keys(): Promise<string[]>;
+    /** Re-announce cadence (ms). Test seam; defaults to hourly (see `ANNOUNCE_INTERVAL_MS`). */
+    intervalMs?: number;
+    /** Change-coalescing window (ms). Test seam; defaults to `ANNOUNCE_DEBOUNCE_MS`. */
+    debounceMs?: number;
+    /** Per-router PUT deadline (ms). Test seam; defaults to `ANNOUNCE_ROUTER_TIMEOUT_MS`. */
+    timeoutMs?: number;
+    /**
+     * Per-router failure hook (timeout, non-2xx, network error). Purely observational — a failing
+     * router never throws into the voter and is not retried; the next tick covers it.
+     */
+    onError?(url: string, error: unknown): void;
+}
+/** The voter-facing announcer handle. All methods are synchronous and idempotent. */
+export interface Announcer {
+    /**
+     * Begin announcing: subscribe to address changes and arm the periodic re-announce. Called when
+     * the voter's first topic joins (symmetric with the lazy fetch-responder lifecycle). Does not
+     * announce by itself — the join that triggered it also calls {@link notifyChange}.
+     */
+    start(): void;
+    /**
+     * Stop announcing and drop timers/listeners. Called when the last topic is left. Records
+     * already written age out by the router's TTL; there is no un-announce.
+     */
+    stop(): void;
+    /**
+     * Coalesced re-announce trigger: a contest joined, a checkpoint root changed, or the address
+     * set changed. The first call arms one debounce timer; further calls within the window ride
+     * it, so a gossip burst (or a directory-wide join) costs one announce.
+     */
+    notifyChange(): void;
+}

package/dist/transport/announce/types.js

@@ -0,0 +1,16 @@
+/**
+ * Provider-record announcer types (see DESIGN.md "Deferred pkc-js work", provider-record
+ * announces). The announcer is the write side of the delegated-routing seam: querying rides the
+ * injected node's `libp2p.contentRouting` (the host wires its routers into `libp2p.services`), but
+ * the pinned js stack has NO working announce path — `@helia/delegated-routing-v1-http-api-client`'s
+ * `provide()` is a literal noop — so provider records only get written by a direct
+ * `PUT /routing/v1/providers` to each router. This library is the node that actually holds the
+ * state (topic membership, fetch responder, blockstore), so its records are always truthful and
+ * current; `PubsubVoterOptions.httpRouterUrls` exists ONLY because announcing cannot ride the
+ * `contentRouting` seam.
+ *
+ * The implementation is Node-only: the browser build swaps `node.js` for the inert `browser.js`
+ * stub via the package.json `browser` field (the same remap as `src/storage/`), because a browser
+ * peer is not dialable and must never announce.
+ */
+export {};

package/dist/transport/bundle-store.d.ts

@@ -0,0 +1,11 @@
+import type { BundleStore } from "../crdt/types.js";
+import type { BlockstoreLike } from "./types.js";
+/**
+ * A {@link BundleStore} backed by the host's Helia blockstore. `put` writes a bundle as a
+ * dag-cbor block locally; `get` reads by CID — and because bitswap retrieves through the
+ * blockstore, an unknown CID is fetched from peers. A fetch that fails or times out surfaces
+ * as `undefined` (not a throw), which the forward-gate reads as "unfetchable -> ignore"
+ * rather than a provable fault. Lives in transport/ (not crdt/) because it touches the
+ * blockstore; the CRDT stays libp2p-free.
+ */
+export declare function makeBlockstoreBundleStore(blockstore: BlockstoreLike): BundleStore;

package/dist/transport/bundle-store.js

@@ -0,0 +1,34 @@
+import { encodeBundle, decodeBundle, bundleCid } from "../crdt/codec.js";
+/**
+ * A {@link BundleStore} backed by the host's Helia blockstore. `put` writes a bundle as a
+ * dag-cbor block locally; `get` reads by CID — and because bitswap retrieves through the
+ * blockstore, an unknown CID is fetched from peers. A fetch that fails or times out surfaces
+ * as `undefined` (not a throw), which the forward-gate reads as "unfetchable -> ignore"
+ * rather than a provable fault. Lives in transport/ (not crdt/) because it touches the
+ * blockstore; the CRDT stays libp2p-free.
+ */
+export function makeBlockstoreBundleStore(blockstore) {
+    return {
+        async put(bundle) {
+            const cid = await bundleCid(bundle);
+            await blockstore.put(cid, encodeBundle(bundle));
+            return cid;
+        },
+        async get(cid, options) {
+            try {
+                return decodeBundle(await blockstore.get(cid, options));
+            }
+            catch {
+                return undefined; // unfetchable / undecodable / aborted — gate treats as ignore
+            }
+        },
+        async has(cid) {
+            try {
+                return await blockstore.has(cid);
+            }
+            catch {
+                return false;
+            }
+        }
+    };
+}

package/dist/transport/chase.d.ts

@@ -0,0 +1,83 @@
+import type { CID } from "multiformats/cid";
+import type { VotesBundle } from "../schema/votes.js";
+import type { VerdictCache } from "../verify/cache.js";
+import type { VerifyResult } from "../verify/types.js";
+import type { PendingBundle } from "../verify/background.js";
+/**
+ * The divergence chase: act on an advertised checkpoint root that differs from our own (a
+ * heartbeat or fetch-protocol hint — see DESIGN.md "Checkpoints", "Block pull"). Pull the
+ * blocks behind the root by CID (directed bitswap at the connected advertisers, through the
+ * injected `getBlock`) and admit each inlined bundle in two stages:
+ *
+ *   1. **Offline, synchronous, before admit** (µs each): signature + criteria constraints via
+ *      `verifyOffline` — a forged or malformed bundle dies here and is never admitted.
+ *   2. **Network, deferred**: the on-chain gate read and name resolution run in the background
+ *      chain verifier (`deferVerify`, one batch per chased root so the gate reads batch into
+ *      as few RPC round trips as the rule allows), which confirms or evicts each bundle after
+ *      the fact. This is what keeps a cold join non-blocking: a 100-vote checkpoint admits in
+ *      milliseconds instead of serializing 100 chain reads (see DESIGN.md "Background chain
+ *      verification").
+ *
+ * So a single liar cannot inject a forged vote (offline check) nor hide an honest one
+ * (union-only merge); an *ineligible-wallet* bundle it injects is admitted provisionally,
+ * surfaces only as a `chainVerified: false` tally row, is never re-served in our checkpoint,
+ * and is evicted as soon as its batched gate read lands.
+ *
+ * Bounded like everything at the gate: a shared concurrency cap (`limit`), a per-root
+ * deadline whose `AbortSignal` cancels in-flight block wants, and in-flight dedup so a spray
+ * of the same root queues one chase, not many. A failed chase (unfetchable blocks, malformed
+ * chunks, all-invalid bundles) contributes nothing and throws nothing — the hint was never
+ * trusted. No libp2p import; pure seams, unit-testable offline.
+ */
+export interface RootChaserDeps {
+    /**
+     * Fetch one checkpoint block by CID (blockstore + directed bitswap); `undefined` or a
+     * throw means unavailable. `signal` aborts the want when the per-root deadline fires.
+     */
+    getBlock: (cid: CID, signal: AbortSignal) => Promise<Uint8Array | undefined>;
+    /** Stage 1 only — signature + constraints, local and synchronous (the gate's same stage). */
+    verifyOffline: (bundle: VotesBundle) => Promise<VerifyResult>;
+    /** The gate's per-CID verdict cache, shared so chased bundles reuse (and feed) it. */
+    cache: VerdictCache;
+    /** The gate's freshness guard (see gossip-validator.ts); omitted ⇒ no check. */
+    isEvaluableNow?: (bundle: VotesBundle) => Promise<boolean>;
+    /** Skip bundles we already hold (their CID is in the store) without re-verifying. */
+    hasBundle: (cid: CID) => Promise<boolean>;
+    /**
+     * Store an offline-valid bundle's block bytes and admit its CID into the CRDT (idempotent).
+     * `verified: true` means a cached terminal verdict already covers the FULL pipeline (the
+     * bundle was verified before, e.g. by the forward-gate); `verified: false` is a provisional
+     * admit whose deferred checks ride `deferVerify`.
+     */
+    admit: (args: {
+        cid: CID;
+        bytes: Uint8Array;
+        bundle: VotesBundle;
+        verified: boolean;
+    }) => Promise<void>;
+    /** Hand one chased root's provisionally admitted bundles to the background chain verifier. */
+    deferVerify: (entries: PendingBundle[]) => void;
+    /** Called once per chase that admitted at least one bundle (drives tally updates). */
+    onMerged?: () => void;
+    /** Concurrency limiter shared across chases (a root spray queues, never floods). */
+    limit: <T>(fn: () => Promise<T>) => Promise<T>;
+    /** Per-root deadline (ms); on expiry the abort signal fires and the chase yields nothing. */
+    timeoutMs: number;
+}
+export interface RootChaser {
+    /**
+     * Chase one advertised root, fire-and-forget: never throws, never blocks the caller
+     * (the validator hands hints here without awaiting). A root already being chased is
+     * dropped — the in-flight run covers it.
+     *
+     * `chunks` is the optional piggybacked chunk-CID index from a fetch-protocol root record
+     * (see DESIGN.md "Block pull"): when supplied and it re-derives to `root`, the chase skips
+     * the root-manifest bitswap round-trip and pulls the chunks directly. A heartbeat hint (no
+     * index) omits it and takes the manifest-fetch path. The index is verified against `root`,
+     * so a bad one simply falls back — never a trust vector.
+     */
+    chase(root: CID, chunks?: CID[]): void;
+    /** Roots currently being chased (for tests/introspection). */
+    inFlight(): number;
+}
+export declare function makeRootChaser(deps: RootChaserDeps): RootChaser;

package/dist/transport/chase.js

@@ -0,0 +1,88 @@
+import { decodeCheckpoint } from "../checkpoint/codec.js";
+import { encodeBundle, bundleCidForBytes } from "../crdt/codec.js";
+export function makeRootChaser(deps) {
+    const { getBlock, verifyOffline, cache, isEvaluableNow, hasBundle, admit, deferVerify, onMerged, limit, timeoutMs } = deps;
+    const inFlight = new Set();
+    async function runChase(root, chunks) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            // Race the decode against the deadline so even a `getBlock` that ignores its abort
+            // signal cannot pin this chase slot past `timeoutMs` — the slot is always freed.
+            const winners = await Promise.race([
+                decodeCheckpoint(root, async (cid) => {
+                    if (controller.signal.aborted)
+                        return undefined;
+                    try {
+                        return await getBlock(cid, controller.signal);
+                    }
+                    catch {
+                        return undefined; // unfetchable/aborted — decode throws "unavailable", chase yields nothing
+                    }
+                }, chunks),
+                new Promise((resolve) => {
+                    controller.signal.addEventListener("abort", () => resolve(undefined), { once: true });
+                })
+            ]);
+            if (winners === undefined)
+                return; // deadline hit — the hint contributed nothing
+            let merged = false;
+            const pending = [];
+            for (const bundle of winners) {
+                if (controller.signal.aborted)
+                    break;
+                // Re-encoding the decoded bundle reproduces the exact block bytes (the codec is
+                // canonical), so the CID matches the advertiser's block and dedups everywhere.
+                const bytes = encodeBundle(bundle);
+                const cid = await bundleCidForBytes(bytes);
+                if (await hasBundle(cid))
+                    continue; // already held — nothing to verify
+                const cached = cache.get(cid);
+                if (cached) {
+                    if (!cached.valid)
+                        continue; // known bad — skip
+                    await admit({ cid, bytes, bundle, verified: true }); // full pipeline already passed
+                    merged = true;
+                    continue;
+                }
+                if (isEvaluableNow && !(await isEvaluableNow(bundle)))
+                    continue; // transient, uncached
+                const offline = await verifyOffline(bundle);
+                if (!offline.valid) {
+                    // A liar's forged/malformed bundle dies here, before admit. A provable
+                    // offline reject (bad signature, constraints) is terminal — cache it so a
+                    // re-served copy short-circuits; a transient `ignore` stays uncached.
+                    if (offline.disposition === "reject")
+                        cache.set(cid, offline);
+                    continue;
+                }
+                await admit({ cid, bytes, bundle, verified: false });
+                pending.push({ cid, bundle });
+                merged = true;
+            }
+            // One batch per chased root: the background verifier groups these by sample block
+            // and batches the gate reads (see verify/background.ts).
+            if (pending.length > 0)
+                deferVerify(pending);
+            if (merged)
+                onMerged?.();
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return {
+        chase(root, chunks) {
+            const key = root.toString();
+            if (inFlight.has(key))
+                return; // the in-flight run covers this hint (chunks derive from root)
+            inFlight.add(key);
+            void limit(() => runChase(root, chunks))
+                .catch(() => { }) // a failed chase contributes nothing; the hint was never trusted
+                .finally(() => inFlight.delete(key));
+        },
+        inFlight() {
+            return inFlight.size;
+        }
+    };
+}

package/dist/transport/gossip-validator.d.ts

@@ -0,0 +1,107 @@
+import type { CID } from "multiformats/cid";
+import type { VotesBundle } from "../schema/votes.js";
+import { type VerdictCache } from "../verify/cache.js";
+import type { BundleVerifier } from "../verify/types.js";
+import type { AcceptedDedup } from "./accepted-dedup.js";
+import type { RootRecord, VoteMessage } from "./messages.js";
+/**
+ * The forward-gate: the async gossipsub topic validator's decision core, written as a pure
+ * function over injected seams (no libp2p import) so it is fully unit-testable. It runs the
+ * FULL validity pipeline on the bundle INLINED in a received message BEFORE the message is
+ * re-forwarded, so an invalid bundle never crosses an honest hop and gossipsub's `reject`
+ * scores the sender for semantic — not just byte-level — badness. See DESIGN.md "Transport".
+ *
+ * The payload is a two-kind discriminated union (see transport/messages.ts):
+ *   - a **bundle delta** — the wallet's own bundle as exact block bytes, validated straight
+ *     from the message (no fetch toward the publisher exists on this path);
+ *   - a **root record** — the checkpoint heartbeat, a fixed-shape unverifiable *hint* that
+ *     short-circuits at layer 1: forwarded within its own per-peer rate and handed to the
+ *     chase logic, never verified here (only equality with our own root is checkable) and
+ *     never trusted.
+ *
+ * Verdicts (who gets blamed):
+ *   - "accept": the inlined bundle verified (or is a known-valid re-publish), or a
+ *     well-formed within-rate root record — deliver, merge (bundles), forward.
+ *   - "reject": something is PROVABLY invalid (malformed message, over the derived size cap,
+ *     a bundle that fails verification) — drop, do not forward, penalize the sender.
+ *   - "ignore": no verdict reachable through no provable fault of the sender — either a
+ *     transient/local condition (over the per-peer rate, internal error, deadline) or a
+ *     view-/clock-dependent verdict two honest peers can disagree on right now: a bundle
+ *     bucketed ahead of our chain head (`isEvaluableNow`), or a `community.name` resolved at
+ *     head during a re-point window. Drop, do not forward, do NOT penalize, and do NOT cache
+ *     (it can change) — using `reject` here would punish honest relayers for transient
+ *     conditions and hand attackers a grief vector.
+ *
+ * Cheap-to-expensive with early exit: size/decode/rate first, then hash + caches, then the
+ * verify pipeline — so a re-published known bundle costs one hash and zero chain work.
+ */
+export type MessageVerdict = "accept" | "reject" | "ignore";
+export interface GossipGateDeps {
+    /** Decode a payload to its message kind; throws on malformed (see transport/messages.ts). */
+    decodeMessage: (data: Uint8Array) => VoteMessage;
+    /**
+     * Decode inlined bundle-block bytes and hash them to the bundle CID (the verdict-cache
+     * key). Throws on malformed block bytes — provable layer-1 badness.
+     */
+    parseBundle: (blockBytes: Uint8Array) => Promise<{
+        cid: CID;
+        bundle: VotesBundle;
+    }>;
+    /** The full validity pipeline for one bundle (see verify/bundle.ts). */
+    verifier: BundleVerifier;
+    /**
+     * Clock-aware freshness guard, kept OUT of the pure (cacheable) verifier: is this bundle's
+     * bucket sample block already reachable from our chain head? A bundle dated to a future
+     * bucket (the voter's head ahead of ours, clock skew, or an absurd `blockNumber`) is not
+     * yet evaluable — transient, so the gate `ignore`s it (no penalty, uncached) until our head
+     * catches up. Omitted ⇒ no freshness check. Steady-state votes resolve `true` with no chain
+     * read; only a look-ahead bundle costs a (memoized) head read.
+     */
+    isEvaluableNow?: (bundle: VotesBundle) => Promise<boolean>;
+    /** Per-CID verdict cache — dedups re-published bundles and known-bad blocks. */
+    cache: VerdictCache;
+    /**
+     * Optional dedup of already-accepted votes by `(wallet, bucket, votes)`. A same-bucket,
+     * same-choice re-sign under fresh bytes is dropped — not verified, not merged, not
+     * forwarded — so a re-sign flood costs no gate read and does not amplify. Omitted ⇒ every
+     * fresh bundle is verified on its own.
+     */
+    acceptedDedup?: AcceptedDedup;
+    /**
+     * Store the verified bundle's exact block bytes and admit its CID into the CRDT
+     * (idempotent). Exact bytes preserve byte-identity with the sender's block.
+     */
+    admit: (args: {
+        cid: CID;
+        bytes: Uint8Array;
+        bundle: VotesBundle;
+    }) => Promise<void>;
+    /**
+     * Concurrency limiter (p-limit) shared across in-flight verifications — the gate chain
+     * read and name resolution are network calls, so concurrent RPC work stays bounded.
+     */
+    limit: <T>(fn: () => Promise<T>) => Promise<T>;
+    /** Per-peer rate gate for bundle-kind messages; `false` means over-rate this window. */
+    allowBundlePeer: (peer: string) => boolean;
+    /** Per-peer rate gate for root-kind messages (heartbeats are ~1 per 10 min when honest). */
+    allowRootPeer: (peer: string) => boolean;
+    /** Called after a fresh bundle is verified and merged (drives tally-update notifications). */
+    onAccept?: (cid: CID, bundle: VotesBundle, from: string) => void;
+    /**
+     * Called with every well-formed, within-rate root record (an unverifiable hint). NOT
+     * awaited — acting on a hint (the directed-bitswap chase) is lazy and bounded elsewhere,
+     * never on the validator's critical path.
+     */
+    onRootRecord?: (record: RootRecord, from: string) => void;
+    /** The criteria-derived cap for a bundle-kind message (see messages.ts). Over ⇒ reject. */
+    maxBundleMessageBytes: number;
+    /** The fixed cap for a root-kind message (~100 B record). Over ⇒ reject. */
+    maxRootMessageBytes: number;
+    /** Hard per-message validation deadline; on expiry the verdict is `ignore`. */
+    timeoutMs: number;
+}
+export interface GossipGate {
+    /** Validate one received message; the returned verdict maps to gossipsub accept/reject/ignore. */
+    validate(data: Uint8Array, from: string): Promise<MessageVerdict>;
+}
+export declare function makeGossipGate(deps: GossipGateDeps): GossipGate;

package/dist/transport/gossip-validator.js

@@ -0,0 +1,99 @@
+import { isCacheableVerdict } from "../verify/cache.js";
+/** Resolve `p`, or `onTimeout` if it does not settle within `ms`; a rejection also yields `onTimeout`. */
+function withDeadline(p, ms, onTimeout) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                resolve(onTimeout);
+            }
+        }, ms);
+        p.then((v) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolve(v);
+            }
+        }, () => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolve(onTimeout);
+            }
+        });
+    });
+}
+export function makeGossipGate(deps) {
+    const { decodeMessage, parseBundle, verifier, isEvaluableNow, cache, acceptedDedup, admit, limit, allowBundlePeer, allowRootPeer, onAccept, onRootRecord, maxBundleMessageBytes, maxRootMessageBytes, timeoutMs } = deps;
+    async function doValidate(data, from) {
+        // Layer 1: size and decode — the cheapest, pre-verify checks.
+        if (data.length > Math.max(maxBundleMessageBytes, maxRootMessageBytes))
+            return "reject";
+        let message;
+        try {
+            message = decodeMessage(data);
+        }
+        catch {
+            return "reject"; // malformed bytes / not one of the two kinds — provable layer-1 badness
+        }
+        if (message.kind === "root") {
+            if (data.length > maxRootMessageBytes)
+                return "reject";
+            if (!allowRootPeer(from))
+                return "ignore";
+            // An unverifiable hint: forward within rate, hand to the (lazy, bounded) chase.
+            // Never `reject`ed on content — only equality with our own root is checkable.
+            onRootRecord?.(message.record, from);
+            return "accept";
+        }
+        if (data.length > maxBundleMessageBytes)
+            return "reject";
+        if (!allowBundlePeer(from))
+            return "ignore";
+        let cid;
+        let bundle;
+        try {
+            ({ cid, bundle } = await parseBundle(message.bundle));
+        }
+        catch {
+            return "reject"; // malformed bundle block bytes — provable
+        }
+        // A known bundle short-circuits on the verdict cache for the cost of one hash: a
+        // re-published valid bundle (e.g. a client refreshing its vote or re-announcing a
+        // withdrawal) is forwarded so late peers converge, without re-verifying or re-merging;
+        // a known-bad one rejects without work.
+        const cached = cache.get(cid);
+        if (cached)
+            return cached.valid ? "accept" : cached.disposition;
+        // Freshness guard (transient, so it runs here — not in the cacheable verifier — and
+        // its verdict is never cached): a bundle bucketed ahead of our head is not yet
+        // evaluable, so `ignore` it without penalty until our head advances. Also defuses an
+        // absurd-future `blockNumber` (e.g. uint256.max) — it never merges into the set.
+        if (isEvaluableNow && !(await isEvaluableNow(bundle)))
+            return "ignore";
+        // Re-sign flood guard: a same-bucket, same-choice re-sign of a vote we already accepted
+        // is inert under LWW, so drop it WITHOUT verifying (no gate read), merging, or
+        // forwarding — the anti-amplification win. Safe on the untrusted `address` because a
+        // hit only ever suppresses something an honest peer already forwarded.
+        if (acceptedDedup?.isResignDuplicate(bundle))
+            return "ignore";
+        const verdict = await limit(() => verifier.verify(bundle));
+        if (isCacheableVerdict(verdict))
+            cache.set(cid, verdict); // only terminal verdicts (accept / provable reject)
+        if (!verdict.valid)
+            return verdict.disposition;
+        await admit({ cid, bytes: message.bundle, bundle });
+        acceptedDedup?.record(bundle);
+        onAccept?.(cid, bundle, from);
+        return "accept";
+    }
+    return {
+        validate(data, from) {
+            // Whole-message deadline: an internal hang or slow RPC/name resolution yields
+            // `ignore`, never a stuck validator (which would strand the message in gossipsub's
+            // mcache).
+            return withDeadline(doValidate(data, from), timeoutMs, "ignore");
+        }
+    };
+}

package/dist/transport/helia.d.ts

@@ -0,0 +1,41 @@
+import type { CID } from "multiformats/cid";
+import type { BlockstoreLike, FetchServiceLike, HeliaInstance, PubsubService } from "./types.js";
+/**
+ * The host's raw blockstore surface. `get` may return EITHER a `Promise<Uint8Array>` (a plain
+ * `interface-blockstore`) OR an async generator yielding the block's bytes — Helia's real
+ * `BlockStorage` implements the streaming `Blocks` interface and yields the block (one chunk in
+ * practice), not a bare promise. The library works against the simpler {@link BlockstoreLike}
+ * contract, so {@link adaptBlockstore} normalises either shape at this one boundary.
+ */
+interface RawBlockstore {
+    get(cid: CID, options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<Uint8Array> | Promise<Uint8Array>;
+    put(cid: CID, block: Uint8Array, options?: {
+        signal?: AbortSignal;
+    }): Promise<CID>;
+    has(cid: CID, options?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+}
+/**
+ * Adapt a raw blockstore to the library's {@link BlockstoreLike} contract: normalise `get` to a
+ * single `Uint8Array`. Helia's `BlockStorage.get` yields the block over an async generator (a
+ * single chunk for the sub-1 MiB blocks this library stores; chunks are concatenated defensively),
+ * while a plain blockstore returns a promise — both are handled. `put`/`has` already return
+ * promises, so they pass through. Exported so the transport (and the integration harness) adapt the
+ * injected node the same way.
+ */
+export declare function adaptBlockstore(raw: RawBlockstore): BlockstoreLike;
+/**
+ * Resolve and validate the gossipsub service, blockstore, and fetch service on an injected
+ * Helia node, throwing {@link MissingPubsubError} / {@link MissingBlockstoreError} /
+ * {@link MissingFetchError} if any is absent or malformed. Returns the narrowed handles so
+ * callers do not re-check.
+ */
+export declare function requireHeliaServices(helia: HeliaInstance): {
+    pubsub: PubsubService;
+    blockstore: BlockstoreLike;
+    fetch: FetchServiceLike;
+};
+export {};

package/dist/transport/helia.js

@@ -0,0 +1,98 @@
+import { MissingBlockstoreError, MissingFetchError, MissingPubsubError } from "../errors.js";
+/**
+ * The helia/libp2p-touching glue. Like the rest of `transport/`, this is the only place
+ * that reaches into the host node; the core never imports it.
+ *
+ * `requireHeliaServices` is the one piece live today: the host injects its running Helia
+ * node directly (no adapter), and we cannot trust the type — `libp2p.services.pubsub` is
+ * `unknown`, a plain Helia node has none, and a malformed object may lack a blockstore —
+ * so we validate both at construction and fail fast (`MissingPubsubError` /
+ * `MissingBlockstoreError`) instead of letting a later publish/subscribe/fetch throw
+ * obscurely.
+ *
+ * Note "bitswap" is not separately checkable: it is a block broker wired *beneath*
+ * `blockstore`, not a property of the Helia node, so validating the blockstore (the
+ * surface bitswap retrieves through) is the closest honest guarantee.
+ */
+/** Does `value` look like a pubsub service we can drive (the methods we depend on)? */
+function isPubsubService(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return (typeof candidate.publish === "function" &&
+        typeof candidate.subscribe === "function" &&
+        typeof candidate.unsubscribe === "function");
+}
+/** Does `value` look like a blockstore we can fetch/store blocks through? */
+function isRawBlockstore(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return (typeof candidate.get === "function" &&
+        typeof candidate.put === "function" &&
+        typeof candidate.has === "function");
+}
+function isAsyncIterable(value) {
+    return value !== null && typeof value === "object" && Symbol.asyncIterator in value;
+}
+/**
+ * Adapt a raw blockstore to the library's {@link BlockstoreLike} contract: normalise `get` to a
+ * single `Uint8Array`. Helia's `BlockStorage.get` yields the block over an async generator (a
+ * single chunk for the sub-1 MiB blocks this library stores; chunks are concatenated defensively),
+ * while a plain blockstore returns a promise — both are handled. `put`/`has` already return
+ * promises, so they pass through. Exported so the transport (and the integration harness) adapt the
+ * injected node the same way.
+ */
+export function adaptBlockstore(raw) {
+    return {
+        async get(cid, options) {
+            const result = raw.get(cid, options);
+            if (!isAsyncIterable(result))
+                return result; // a plain Promise<Uint8Array> blockstore
+            const chunks = [];
+            for await (const chunk of result)
+                chunks.push(chunk);
+            if (chunks.length === 1)
+                return chunks[0];
+            if (chunks.length === 0)
+                throw new Error(`block ${cid.toString()} yielded no bytes`);
+            const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+            const out = new Uint8Array(total);
+            let offset = 0;
+            for (const chunk of chunks) {
+                out.set(chunk, offset);
+                offset += chunk.length;
+            }
+            return out;
+        },
+        put: (cid, block) => raw.put(cid, block),
+        has: (cid) => raw.has(cid)
+    };
+}
+/** Does `value` look like a libp2p fetch service (the request + responder registration)? */
+function isFetchService(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return (typeof candidate.fetch === "function" &&
+        typeof candidate.registerLookupFunction === "function" &&
+        typeof candidate.unregisterLookupFunction === "function");
+}
+/**
+ * Resolve and validate the gossipsub service, blockstore, and fetch service on an injected
+ * Helia node, throwing {@link MissingPubsubError} / {@link MissingBlockstoreError} /
+ * {@link MissingFetchError} if any is absent or malformed. Returns the narrowed handles so
+ * callers do not re-check.
+ */
+export function requireHeliaServices(helia) {
+    const pubsub = helia.libp2p?.services?.pubsub;
+    if (!isPubsubService(pubsub))
+        throw new MissingPubsubError();
+    const blockstore = helia.blockstore;
+    if (!isRawBlockstore(blockstore))
+        throw new MissingBlockstoreError();
+    const fetch = helia.libp2p?.services?.fetch;
+    if (!isFetchService(fetch))
+        throw new MissingFetchError();
+    return { pubsub, blockstore: adaptBlockstore(blockstore), fetch };
+}