@bitsocial/pubsub-votes 0.0.2

package/dist/client/root-puller.js

@@ -0,0 +1,140 @@
+import pLimit from "p-limit";
+import { batchRootsFetchKey, decodeBatchRootsResponse, decodeRootRecord, rootFetchKey, MAX_BATCH_ROOT_KEYS } from "../transport/messages.js";
+/** See the budget note on {@link RootPuller}. */
+export const COLD_START_PEER_FETCH_LIMIT = 24;
+/** See the retry note on {@link RootPuller}. */
+export const COLD_START_FETCH_DEADLINE_MS = 30_000;
+const COLD_START_FETCH_BACKOFF_MS = 400;
+const COLD_START_FETCH_BACKOFF_CAP_MS = 4_000;
+/**
+ * How long a peer's first pending pull waits for same-peer company before its batch flushes.
+ * A directory join fires all its cold starts in one synchronous burst, so one tick would
+ * usually do; a few ms of slack covers joins interleaved with per-contest async work (topic
+ * hashing, chain-client setup) without adding perceptible latency to a lone join.
+ */
+const BATCH_WINDOW_MS = 20;
+/**
+ * One `pLimit(limitPerPeer)` per peer id, created on first use and dropped once its queue
+ * drains, so a long-lived voter does not accumulate limiters for every peer it ever
+ * cold-started against.
+ */
+function makePerPeerBudget(limitPerPeer) {
+    const limiters = new Map();
+    return async (peerId, task) => {
+        let limiter = limiters.get(peerId);
+        if (limiter === undefined) {
+            limiter = pLimit(limitPerPeer);
+            limiters.set(peerId, limiter);
+        }
+        try {
+            return await limiter(task);
+        }
+        finally {
+            if (limiter.activeCount === 0 && limiter.pendingCount === 0)
+                limiters.delete(peerId);
+        }
+    };
+}
+/** Build the voter-wide puller over the host's fetch service. */
+export function makeRootPuller(fetch) {
+    const budget = makePerPeerBudget(COLD_START_PEER_FETCH_LIMIT);
+    const pending = new Map();
+    /** One budgeted+retried fetch of one key (see the retry note on {@link RootPuller}). */
+    const fetchWithRetry = async (peer, key, isLive) => {
+        const deadline = Date.now() + COLD_START_FETCH_DEADLINE_MS;
+        let lastError;
+        for (let attempt = 0;; attempt++) {
+            if (attempt > 0) {
+                if (!isLive() || Date.now() >= deadline)
+                    break; // left or out of time
+                const ceiling = Math.min(COLD_START_FETCH_BACKOFF_CAP_MS, COLD_START_FETCH_BACKOFF_MS * 2 ** (attempt - 1));
+                await new Promise((resolve) => setTimeout(resolve, Math.random() * ceiling));
+                if (!isLive())
+                    return undefined; // left mid-backoff — abandon quietly
+            }
+            try {
+                return await budget(peer.toString(), () => fetch.fetch(peer, key));
+            }
+            catch (error) {
+                lastError = error; // transient (e.g. responder over its inbound-stream cap) — back off and retry
+            }
+        }
+        throw lastError;
+    };
+    /** The per-topic path: today's `<topic>/root` key; a garbage answer rejects the waiters. */
+    const pullSingle = async (peer, topic, waiters) => {
+        try {
+            const value = await fetchWithRetry(peer, rootFetchKey(topic), () => waiters.some((w) => w.isLive()));
+            const record = value === undefined || value === null ? value : decodeRootRecord(value);
+            waiters.forEach((w) => w.resolve(record));
+        }
+        catch (error) {
+            waiters.forEach((w) => w.reject(error));
+        }
+    };
+    /**
+     * The batch path: one stream, one key carrying every pending topic, answers distributed by
+     * request order. NOT_FOUND (a responder without the batch key), a malformed response, or a
+     * length mismatch all degrade to the per-topic path — never to silence.
+     */
+    const pullBatch = async (peer, topics) => {
+        const order = [...topics.keys()];
+        const isLive = () => [...topics.values()].some((waiters) => waiters.some((w) => w.isLive()));
+        try {
+            const value = await fetchWithRetry(peer, batchRootsFetchKey(order), isLive);
+            if (value !== undefined && value !== null) {
+                let records;
+                try {
+                    records = decodeBatchRootsResponse(value);
+                }
+                catch {
+                    records = undefined; // hostile/buggy answer — fall through to per-topic
+                }
+                if (records !== undefined && records.length === order.length) {
+                    order.forEach((topic, i) => topics.get(topic).forEach((w) => w.resolve(records[i] ?? null)));
+                    return;
+                }
+            }
+            // Old responder (NOT_FOUND) or malformed batch answer: degrade to per-topic keys.
+            await Promise.all([...topics.entries()].map(([topic, waiters]) => pullSingle(peer, topic, waiters)));
+        }
+        catch (error) {
+            for (const waiters of topics.values())
+                waiters.forEach((w) => w.reject(error));
+        }
+    };
+    const flush = (peerId) => {
+        const batch = pending.get(peerId);
+        if (batch === undefined)
+            return;
+        pending.delete(peerId);
+        clearTimeout(batch.timer);
+        // A lone topic keeps today's per-topic key — no batch envelope for the common
+        // single-board join; two or more ride one batch stream.
+        if (batch.topics.size === 1) {
+            for (const [topic, waiters] of batch.topics)
+                void pullSingle(batch.peer, topic, waiters);
+        }
+        else {
+            void pullBatch(batch.peer, batch.topics);
+        }
+    };
+    return {
+        pull: (peer, topic, isLive) => new Promise((resolve, reject) => {
+            const peerId = peer.toString();
+            let batch = pending.get(peerId);
+            if (batch === undefined) {
+                const timer = setTimeout(() => flush(peerId), BATCH_WINDOW_MS);
+                timer.unref?.();
+                batch = { peer, topics: new Map(), timer };
+                pending.set(peerId, batch);
+            }
+            const waiters = batch.topics.get(topic) ?? [];
+            waiters.push({ isLive, resolve, reject });
+            batch.topics.set(topic, waiters);
+            // A full batch flushes immediately; the next pull opens a fresh window.
+            if (batch.topics.size >= MAX_BATCH_ROOT_KEYS)
+                flush(peerId);
+        })
+    };
+}

package/dist/client/voter.d.ts

@@ -0,0 +1,225 @@
+import { type Criteria } from "../schema/criteria.js";
+import { type Vote, type VotesBundle } from "../schema/votes.js";
+import type { ChainClientFactory, NameResolver } from "../chain/types.js";
+import type { HeliaInstance } from "../transport/types.js";
+import type { RuleRegistry } from "../rules/types.js";
+import type { ContestTally } from "../tally/types.js";
+import type { VoteSigner } from "../signer/types.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
+ * its `blockNumber` (see DESIGN.md "Passive expiry"), so re-signing at the halfway point leaves
+ * one full missed cycle of slack before the vote decays. Derived per-contest from the criteria —
+ * there is no global interval.
+ *
+ * This library does NOT re-publish on its own: deciding when (or whether) to refresh a vote is
+ * the consuming client's job (see DESIGN.md "Republishing is the client's job"). This helper, the
+ * `blockNumber` on a published `VotesBundle`, and `criteria.voteExpiryBuckets` /
+ * `criteria.blocksPerBucket` are what a client uses to schedule its own refreshes: a vote sampled
+ * at bucket `b` expires once the current bucket exceeds `b + voteExpiryBuckets`; refresh by
+ * calling `createContestVote({ criteria, votes }).publish()` again before then.
+ */
+export declare function republishIntervalBuckets(criteria: Criteria): number;
+/**
+ * Public facade — three objects, mirroring pkc-js / plebbit-js:
+ *   - {@link PubsubVoter} (`VoteClient`): the factory. Holds the host-injected dependencies once
+ *     and owns one engine per contest, keyed by topic. A contest is addressed by its full criteria
+ *     document — `createContest({ criteria })` validates it and derives the topic — so a directory
+ *     host like 5chan authors its 63 documents however it likes (e.g. merged from a local
+ *     manifest) and creates each contest, without wiring dependencies 63 times.
+ *   - {@link Contest} (`createContest`): one contest's reactive **read** view. `update()` starts
+ *     syncing and emits `update` (carrying a fresh `tally`) / `error`, like `subplebbit.update()`.
+ *   - {@link ContestVote} (`createContestVote`): one publishable **ballot**. `publish()` signs and
+ *     broadcasts it once, emitting `publishingstatechange` / `error`, like a plebbit publication.
+ *
+ * The injected seams (helia, chains, signer, nameResolvers) are the ONLY host contact surface, so
+ * the same core runs under pkc-js, plebbit, or a raw node. The host passes its running Helia node
+ * directly — no adapter — and the library drives that node's gossipsub service and blockstore
+ * itself. A voter built without a `signer` is read-only (tallies readable, publishing disabled).
+ *
+ * Republishing a live vote so it does not decay is deliberately NOT this library's job — it
+ * 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}. */
+export type PublishingState = "stopped" | "signing" | "publishing" | "succeeded" | "failed";
+/** What {@link ContestVote.publish} resolves: the signed bundle plus a peer-reach hint. */
+export interface PublishOutcome {
+    /** The signed bundle; its `blockNumber` drives the client's own refresh schedule. */
+    readonly bundle: VotesBundle;
+    /**
+     * How many peers gossipsub sent this vote *directly* to — first-hop fan-out, not total network
+     * reach and not an acceptance confirmation (each recipient still runs the forward-gate before
+     * re-forwarding). Handy as a coarse "did this reach anyone?" signal: `0` means the message went
+     * nowhere. Note gossipsub instead *rejects* the publish with `NoPeersSubscribedToTopic` when it
+     * would reach zero peers, unless the host enables `allowPublishToZeroTopicPeers` — so a
+     * resolved `recipientCount === 0` only happens under that host setting.
+     */
+    readonly recipientCount: number;
+}
+/** One contest's reactive read view: subscribe, keep the tally in sync, read it. */
+export interface Contest {
+    /** The criteria document this contest runs (already validated). */
+    readonly criteria: Criteria;
+    /** The gossipsub topic = "bitsocial-votes/" + CID(dag-cbor(criteria)). */
+    readonly topic: string;
+    /**
+     * The last computed tally, refreshed before each `update` event; `undefined` until the first
+     * compute (i.e. before `update()` resolves). For a forced fresh read use {@link getTally}.
+     */
+    readonly tally: ContestTally | undefined;
+    /**
+     * Join the topic behind the validate-before-forward gate, pull the cold-start checkpoint, and
+     * begin emitting `update` events as incoming votes change the state. Resolves once the initial
+     * tally is computed (so {@link tally} is populated). Idempotent.
+     */
+    update(): Promise<void>;
+    /** Stop syncing and leave the topic. Does not stop the host node. Idempotent. */
+    stop(): Promise<void>;
+    /** Compute the current contest ranking fresh, bypassing the cache. */
+    getTally(): Promise<ContestTally>;
+    /**
+     * 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
+     * `chainVerified: false` rows immediately, then re-emits as the batched gate reads and name
+     * resolutions land (see DESIGN.md "Background chain verification").
+     */
+    on(event: "update", cb: () => void): void;
+    /**
+     * Fired on a contest-level failure: the tally's chain read throws, or 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).
+     */
+    on(event: "error", cb: (error: unknown) => void): void;
+}
+/** One publishable ballot for a contest. Create it, then `publish()`. */
+export interface ContestVote {
+    /** The `contestId` this ballot targets. */
+    readonly contestId: string;
+    /** The gossipsub topic the bundle publishes to. */
+    readonly topic: string;
+    /** The votes this ballot will sign and broadcast (empty array = a withdrawal). */
+    readonly votes: readonly Vote[];
+    /** Where in the publish lifecycle this ballot is. */
+    readonly publishingState: PublishingState;
+    /** The signed bundle, once `publish()` has produced it (`undefined` before then). */
+    readonly bundle: VotesBundle | undefined;
+    /**
+     * Sign the votes into a bundle for the current bucket, add it to the local CRDT, and broadcast
+     * it once as a live delta. Joins the topic first if needed. Resolves a {@link PublishOutcome}:
+     * 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.
+     */
+    publish(): Promise<PublishOutcome>;
+    /** Fired on each `publishingState` transition. */
+    on(event: "publishingstatechange", cb: (state: PublishingState) => void): void;
+    /** Fired if publishing fails. */
+    on(event: "error", cb: (error: unknown) => void): void;
+}
+/** The factory: one set of injected dependencies, many contests. */
+export interface VoteClient {
+    /** True when constructed without a signer: every contest is read-only. */
+    readonly readOnly: boolean;
+    /**
+     * Create the reactive read view for one contest from its full criteria document. The document
+     * is strictly validated (`CriteriaSchema` + the rule registry — an unimplemented rule throws
+     * `UnknownRuleError`) and its topic derived (`topic = CID(dag-cbor(criteria))`). Returns the
+     * stable per-topic object (one CRDT/engine per topic per node), so repeated calls with
+     * byte-identical criteria return the same `Contest`.
+     */
+    createContest(args: {
+        criteria: Criteria;
+    }): Promise<Contest>;
+    /**
+     * Create a publishable ballot for one contest, validated and addressed exactly like
+     * `createContest`. Each call returns a fresh `ContestVote` over the shared per-topic engine;
+     * pass `votes: []` to build a withdrawal.
+     */
+    createContestVote(args: {
+        criteria: Criteria;
+        votes: Vote[];
+    }): Promise<ContestVote>;
+    /**
+     * Leave every topic this client joined, resetting each read view so it can `update()` again.
+     * The checkpoint fetch responder unregisters itself once the last topic is left (see
+     * `PubsubVoter`'s lazy responder lifecycle). The client stays fully reusable — call
+     * `createContest` / `update()` after.
+     */
+    stop(): Promise<void>;
+    /**
+     * Terminal teardown (mirrors pkc-js `destroy`): leave every topic, unregister the fetch
+     * responder, and mark the voter and all its contests destroyed. Unlike `stop`, this is NOT
+     * reusable — every subsequent `createContest` / `createContestVote`, and any pre-existing
+     * `Contest.update()` / `ContestVote.publish()`, throws `VoterDestroyedError`. Construct a new
+     * `PubsubVoter` to participate again. There is no store to dispose (republishing / persistence
+     * is the client's concern).
+     */
+    destroy(): Promise<void>;
+}
+/** Construction options for {@link PubsubVoter}. */
+export interface PubsubVoterOptions {
+    /**
+     * The host's running Helia node (the value `createHelia` returns; for pkc-js it is
+     * `pkc.clients.libp2pJsClients[key]._helia`). The only host-node seam, passed
+     * directly with no adapter. It MUST carry a gossipsub service at
+     * `libp2p.services.pubsub`, a usable `blockstore`, and a libp2p fetch service at
+     * `libp2p.services.fetch`; the constructor throws `MissingPubsubError` /
+     * `MissingBlockstoreError` / `MissingFetchError` otherwise (a plain Helia node has
+     * no pubsub). The library never starts or stops this node.
+     */
+    helia: HeliaInstance;
+    /**
+     * Builds a chain client from a `{ chain, config }` pair. Each contest builds its
+     * own clients from `criteria.requires.chains` via this factory, so chains are
+     * per-contest data, not a global injection.
+     */
+    chains: ChainClientFactory;
+    /** Identity. Omit for a read-only voter (renders tallies, cannot publish). */
+    signer?: VoteSigner;
+    /** Rule overrides that shadow built-ins by `type` (a flat `type -> rule` map). */
+    rules?: RuleRegistry;
+    /**
+     * Community-name resolvers, same instances a host gives pkc-js (e.g.
+     * `@bitsocial/bso-resolver` for `name.bso`). The tally resolves each vote's
+     * `community.name` claim through the first resolver whose `canResolve` matches and
+     * drops bundles whose name does not resolve to the claimed `publicKey`. Omit only
+     * if no contest's votes carry names — with no resolver for a carried name's TLD,
+     * the claim cannot be verified and the bundle is dropped (never counted unchecked).
+     */
+    nameResolvers?: NameResolver[];
+    /**
+     * Directory for the voter's persistent caches (gate results, name resolutions), the
+     * pkc-js `dataPath` equivalent. On Node the caches are better-sqlite3 databases under
+     * `{dataPath}/lru-storage/`; in the browser the path is ignored and the caches live in
+     * IndexedDB (via localforage) either way. Defaults to `{cwd}/.bitsocial-pubsub-votes`
+     * on Node. Pass `false` for in-memory-only caches (no disk, no IndexedDB — the pkc-js
+     * `noData` equivalent): nothing survives the process, but nothing is written either.
+     */
+    dataPath?: string | false;
+}
+/**
+ * The default `VoteClient`. Construct with the host-injected seams: a `helia` node (must carry a
+ * gossipsub service, a blockstore, and a libp2p fetch service), a `chains` factory, an optional
+ * `signer`, and optional `nameResolvers` (needed once votes carry community names). Contests are
+ * addressed by their full criteria document at `createContest` / `createContestVote`; the library
+ * has no knowledge of pkc-js or any other host: a host passes its own running Helia node in
+ * directly. Republishing a live vote is the client's concern — see
+ * {@link republishIntervalBuckets} and DESIGN.md "Republishing is the client's job".
+ */
+export declare class PubsubVoter implements VoteClient {
+    #private;
+    constructor(options: PubsubVoterOptions);
+    get readOnly(): boolean;
+    createContest(args: {
+        criteria: Criteria;
+    }): Promise<Contest>;
+    createContestVote(args: {
+        criteria: Criteria;
+        votes: Vote[];
+    }): Promise<ContestVote>;
+    stop(): Promise<void>;
+    destroy(): Promise<void>;
+}