@cello-protocol/daemon 0.0.229 → 0.0.231

package/dist/channel-admin-lookup.d.ts

@@ -0,0 +1,54 @@
+/**
+ * M16 020-CHANADMIN — asking a directory who administers a channel.
+ *
+ * A subscriber that has been handed a group key must check the agent that handed it over against
+ * what the directory says about the channel. The session proves who the counterparty IS; it says
+ * nothing about whether they have any authority over this channel. Without the check, any agent that
+ * can open a session with you becomes your channel.
+ *
+ * 019 built the check and it could not run: the answer lives in the directory's profile and no
+ * client-facing frame carried it. `channel_admin_query` (020, directory side) does, on the
+ * authenticated signaling stream. This is the client half.
+ *
+ * ⚠️ **"NOT A CHANNEL" AND "I COULD NOT FIND OUT" ARE DIFFERENT ANSWERS, and the whole value of this
+ * module is keeping them apart.** A negative is authoritative — the subscriber acts on it. A
+ * timeout, a down stream, a malformed reply or a directory-side `lookup_failed` are all the absence
+ * of an answer, and they leave the join refused. Collapsed into the negative, a directory outage
+ * would read as a verdict about the channel, and the step after that is accepting a key from
+ * whoever happened to answer.
+ */
+import type { Logger } from "./types.js";
+/**
+ * The part of a `SignalingManager` this needs. Structural rather than the class, so the lookup can
+ * be exercised without standing up a directory connection.
+ */
+export interface SignalingLike {
+    registerInboundHandler(handler: (frame: Record<string, unknown>) => void): () => void;
+    sendRaw(frame: unknown): Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+}
+export type ChannelAdminOutcome = 
+/** A registered channel, and the agent the directory says administers it. */
+{
+    kind: "admin";
+    adminPubkeyHex: string;
+}
+/** The directory answered, and this pubkey is not a channel — unregistered, or an ordinary agent. */
+ | {
+    kind: "not_a_channel";
+}
+/** No answer. NOT a verdict about the channel. */
+ | {
+    kind: "unavailable";
+    reason: string;
+};
+export interface ChannelAdminLookupDeps {
+    /** The asking agent's directory connection, or null when it has none. */
+    signalingFor: (agentId: string) => SignalingLike | null;
+    logger: Logger;
+    timeoutMs?: number;
+}
+export declare function createChannelAdminLookup(deps: ChannelAdminLookupDeps): (agentId: string, channelHex: string) => Promise<ChannelAdminOutcome>;
+//# sourceMappingURL=channel-admin-lookup.d.ts.map

package/dist/channel-admin-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-admin-lookup.d.ts","sourceRoot":"","sources":["../src/channel-admin-lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,sBAAsB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACtF,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpE;AAED,MAAM,MAAM,mBAAmB;AAC7B,6EAA6E;AAC3E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE;AAC3C,qGAAqG;GACnG;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE;AAC3B,kDAAkD;GAChD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5C,MAAM,WAAW,sBAAsB;IACrC,yEAAyE;IACzE,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,aAAa,GAAG,IAAI,CAAC;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAmBD,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,sBAAsB,GAC3B,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CA0GvE"}

package/dist/channel-admin-lookup.js

@@ -0,0 +1,122 @@
+import { extractErrorMessage } from "./error-message.js";
+const DEFAULT_TIMEOUT_MS = 10_000;
+/** 64 lowercase hex characters, or nothing. A partial admin key must not reach a comparison. */
+function adminPubkeyOf(frame) {
+    const raw = frame["admin_pubkey"];
+    if (typeof raw !== "string" || !/^[0-9a-fA-F]{64}$/.test(raw))
+        return null;
+    return raw.toLowerCase();
+}
+function echoedChannelHex(frame) {
+    const raw = frame["channel_pubkey"];
+    if (raw instanceof Uint8Array)
+        return Buffer.from(raw).toString("hex");
+    if (Buffer.isBuffer(raw))
+        return raw.toString("hex");
+    if (typeof raw === "string" && /^[0-9a-fA-F]{64}$/.test(raw))
+        return raw.toLowerCase();
+    return null;
+}
+export function createChannelAdminLookup(deps) {
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return async function lookup(agentId, channelHexRaw) {
+        const channelHex = channelHexRaw.toLowerCase();
+        const signaling = deps.signalingFor(agentId);
+        if (!signaling) {
+            // Answer now rather than waiting out the timeout for a reply that was never coming — this runs
+            // on the inbound join path, once per frame.
+            return { kind: "unavailable", reason: "signaling_unavailable" };
+        }
+        let resolveFrame;
+        const pending = new Promise((r) => { resolveFrame = r; });
+        /**
+         * ⚠️ **MATCHED ON THE ECHOED PUBKEY, not on the frame type alone.** The signaling stream is one
+         * multiplexed stream shared by every lookup this agent has in flight. Taking the first
+         * `channel_admin_result` that arrives would let two concurrent joins each accept the other's
+         * answer — and then the admin check runs against a different channel's administrator, where a
+         * match proves nothing.
+         */
+        const unregister = signaling.registerInboundHandler((frame) => {
+            const t = frame["type"];
+            if (t !== "channel_admin_result" && t !== "channel_admin_error")
+                return;
+            /**
+             * ⚠️ **THE ERROR IS MATCHED THE SAME WAY, and it was not at first.** An unmatched error
+             * resolved whichever lookup happened to be waiting: two joins in flight, a database fault on
+             * the first channel, and the second was refused although the directory had answered it
+             * perfectly. It fails closed, so nothing unsafe — it just turns one channel's outage into
+             * every concurrent join's refusal, which is a bad trade for a field.
+             */
+            if (echoedChannelHex(frame) !== channelHex)
+                return;
+            resolveFrame(frame);
+        });
+        let timer;
+        try {
+            const sent = await signaling.sendRaw({
+                type: "channel_admin_query",
+                channel_pubkey: new Uint8Array(Buffer.from(channelHex, "hex")),
+            });
+            if (!sent.ok) {
+                // The transport's own reason, never a guess about the directory or the channel.
+                return { kind: "unavailable", reason: sent.reason ?? "signaling_unavailable" };
+            }
+            const timeoutP = new Promise((r) => {
+                timer = setTimeout(() => r({ type: "__timeout__" }), timeoutMs);
+            });
+            const frame = await Promise.race([pending, timeoutP]);
+            if (frame["type"] === "__timeout__") {
+                deps.logger.warn("directory.channel.admin.lookup.failed", { channel: channelHex.slice(0, 16), reason: "timeout" });
+                return { kind: "unavailable", reason: "timeout" };
+            }
+            if (frame["type"] === "channel_admin_error") {
+                const reason = typeof frame["reason"] === "string" ? frame["reason"] : "lookup_failed";
+                deps.logger.warn("directory.channel.admin.lookup.failed", { channel: channelHex.slice(0, 16), reason });
+                return { kind: "unavailable", reason };
+            }
+            /**
+             * ⚠️ **SHAPE FIRST, AND THIS WAS A DEFECT THE TEST CAUGHT.** `registered !== true` is true for
+             * a field that is ABSENT as well as one that is `false` — so a reply missing the field
+             * entirely read as an authoritative "not a channel", which is precisely the collapse this
+             * module exists to prevent. A frame that does not carry both booleans is a directory that
+             * replied with something we cannot read, and that is not knowing.
+             */
+            if (typeof frame["registered"] !== "boolean" || typeof frame["channel"] !== "boolean") {
+                deps.logger.warn("directory.channel.admin.lookup.failed", { channel: channelHex.slice(0, 16), reason: "malformed_reply" });
+                return { kind: "unavailable", reason: "malformed_reply" };
+            }
+            if (frame["registered"] !== true || frame["channel"] !== true) {
+                // An answer, and a settled one: the subscriber is looking at something that is not a channel.
+                deps.logger.info("directory.channel.admin.lookup", { channel: channelHex.slice(0, 16), answered: "not_a_channel" });
+                return { kind: "not_a_channel" };
+            }
+            const adminPubkeyHex = adminPubkeyOf(frame);
+            if (adminPubkeyHex === null) {
+                /**
+                 * A registered channel whose answer carries no usable admin key. Reading a missing or
+                 * malformed field as `""` would put an empty key into the comparison against whoever
+                 * answered — which either matches nothing for ever or, worse, matches an empty counterparty.
+                 * So it is `unavailable`: there is no admin to check against, and that is not knowing.
+                 *
+                 * ⚠️ **NAMED FOR THE REGISTRATION, NOT THE WIRE.** Calling this `malformed_reply` sent the
+                 * operator to debug the protocol, when the directory answered exactly as designed about a
+                 * channel that was registered without an administrator. The reason has to point at the
+                 * thing that is actually wrong.
+                 */
+                deps.logger.warn("directory.channel.admin.lookup.failed", { channel: channelHex.slice(0, 16), reason: "channel_without_admin" });
+                return { kind: "unavailable", reason: "channel_without_admin" };
+            }
+            deps.logger.info("directory.channel.admin.lookup", { channel: channelHex.slice(0, 16), answered: "admin" });
+            return { kind: "admin", adminPubkeyHex };
+        }
+        catch (err) {
+            return { kind: "unavailable", reason: extractErrorMessage(err) };
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            unregister();
+        }
+    };
+}
+//# sourceMappingURL=channel-admin-lookup.js.map

package/dist/channel-admin-lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-admin-lookup.js","sourceRoot":"","sources":["../src/channel-admin-lookup.ts"],"names":[],"mappings":"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"}

package/dist/channel-collect-tick.d.ts

@@ -0,0 +1,36 @@
+import type { Logger } from "./types.js";
+import type { ChannelCollector } from "./channel-collector.js";
+import type { ChannelSubscriptionStore } from "./channel-subscription-store.js";
+/** See the header: bounded by the shortest retention any channel may configure. */
+export declare const COLLECT_TICK_INTERVAL_MS: number;
+/** The widest the pubkey-derived offset can push a channel's tick. */
+export declare const COLLECT_JITTER_MS = 60000;
+/** A failing channel is backed off to at most this, then stays there until it succeeds. */
+export declare const COLLECT_MAX_BACKOFF_MS: number;
+export interface ChannelCollectTickDeps {
+    logger: Logger;
+    collector: ChannelCollector;
+    subscriptions: ChannelSubscriptionStore;
+    /**
+     * Whether this agent is ONLINE. Collecting for an agent the operator switched off is the kill
+     * switch failing to switch something off — the same rule the trust-signal tick follows.
+     */
+    isAgentOnline: (agentId: string) => boolean;
+    intervalMs?: number;
+    jitterMs?: number;
+    maxBackoffMs?: number;
+}
+export interface ChannelCollectTicker {
+    /** Begin collecting. Idempotent: a second call does not stack a second timer. */
+    start: () => void;
+    /** One pass over every active subscription. Exposed so a test drives it without a clock. */
+    collectAllDue: (now: number) => Promise<void>;
+    stop: () => void;
+}
+/**
+ * A stable offset in [0, jitterMs) for a channel, from its public key. Same channel, same
+ * subscriber, same offset every time — see the header for why that beats a fresh random each tick.
+ */
+export declare function jitterForChannel(channelHex: string, agentId: string, jitterMs: number): number;
+export declare function createChannelCollectTicker(deps: ChannelCollectTickDeps): ChannelCollectTicker;
+//# sourceMappingURL=channel-collect-tick.d.ts.map

package/dist/channel-collect-tick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-collect-tick.d.ts","sourceRoot":"","sources":["../src/channel-collect-tick.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAGhF,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,QAAa,CAAC;AACnD,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,QAAS,CAAC;AACxC,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAc,CAAC;AAElD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,gBAAgB,CAAC;IAC5B,aAAa,EAAE,wBAAwB,CAAC;IACxC;;;OAGG;IACH,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,4FAA4F;IAC5F,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI9F;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,sBAAsB,GAAG,oBAAoB,CAgF7F"}

package/dist/channel-collect-tick.js

@@ -0,0 +1,133 @@
+/**
+ * M16 018-PUBCOLLECT — what actually RUNS the collector.
+ *
+ * ⚠️ **WITHOUT THIS, SUBSCRIBING DOES NOTHING.** `ChannelCollector` fetches when it is called, and
+ * a subscriber has nobody to call it: there is no inbound event for a channel post — the relay holds
+ * a queue and waits to be asked. A collector nobody schedules is a subscriber who never receives
+ * anything, with every component reporting healthy. The publishing half shipped wired and this half
+ * did not, which is the same hole twice in one milestone.
+ *
+ * ─── The interval, and why it is bounded by retention ────────────────────────────────────────
+ *
+ * A relay drops posts on its own schedule. If the gap between collections is longer than a channel's
+ * retention, a subscriber can miss a post that was delivered, held for its full life and swept —
+ * never seeing it, and never recording a gap either, because the number is below the floor by the
+ * time anyone looks. The interval therefore has to stay well under the shortest retention any
+ * channel uses, and the default retention is seven days. Five minutes is three orders of magnitude
+ * inside that, which is the margin this needs to be safe against a channel configured far shorter.
+ *
+ * ─── Jitter is derived from the channel key, not random ──────────────────────────────────────
+ *
+ * Every subscriber to a popular channel would otherwise poll its two relays at the same moment —
+ * the relays see the entire audience arrive at once, every interval, for ever. The offset is
+ * derived from the channel's public key so it is STABLE for a given subscriber: a random offset
+ * re-rolled each tick spreads the load just as well but makes the cadence unpredictable to the
+ * operator watching it, and makes a slow channel impossible to distinguish from a jittery one.
+ *
+ * ─── Backoff is per channel, and only on FAILURE ─────────────────────────────────────────────
+ *
+ * A channel whose relays are both down is asked less and less often, up to a ceiling, so a dead
+ * channel costs little. Any success resets it immediately: the point is to stop hammering something
+ * broken, not to punish a channel for a bad afternoon.
+ */
+import { createHash } from "node:crypto";
+import { extractErrorMessage } from "./error-message.js";
+/** See the header: bounded by the shortest retention any channel may configure. */
+export const COLLECT_TICK_INTERVAL_MS = 5 * 60_000;
+/** The widest the pubkey-derived offset can push a channel's tick. */
+export const COLLECT_JITTER_MS = 60_000;
+/** A failing channel is backed off to at most this, then stays there until it succeeds. */
+export const COLLECT_MAX_BACKOFF_MS = 30 * 60_000;
+/**
+ * A stable offset in [0, jitterMs) for a channel, from its public key. Same channel, same
+ * subscriber, same offset every time — see the header for why that beats a fresh random each tick.
+ */
+export function jitterForChannel(channelHex, agentId, jitterMs) {
+    if (jitterMs <= 0)
+        return 0;
+    const digest = createHash("sha256").update(`${agentId}:${channelHex}`, "utf8").digest();
+    return digest.readUInt32BE(0) % jitterMs;
+}
+export function createChannelCollectTicker(deps) {
+    const { logger, collector, subscriptions, isAgentOnline } = deps;
+    const intervalMs = deps.intervalMs ?? COLLECT_TICK_INTERVAL_MS;
+    const jitterMs = deps.jitterMs ?? COLLECT_JITTER_MS;
+    const maxBackoffMs = deps.maxBackoffMs ?? COLLECT_MAX_BACKOFF_MS;
+    /** When each subscription is next due, and how far it has been backed off. */
+    const nextDue = new Map();
+    const backoff = new Map();
+    /**
+     * Subscriptions with a pass still running. A tick that lands on one is SKIPPED rather than
+     * queued: a slow relay would otherwise stack passes that all fetch the same posts, and each one
+     * holds a database write.
+     */
+    const inFlight = new Set();
+    let timer = null;
+    const keyOf = (agentId, channelHex) => `${agentId}:${channelHex}`;
+    async function collectAllDue(now) {
+        for (const sub of subscriptions.active()) {
+            const key = keyOf(sub.agent_id, sub.channel_pubkey);
+            if (inFlight.has(key))
+                continue;
+            // Checked PER SUBSCRIPTION, not once for the pass: one agent being offline must not stop
+            // another agent's channels from collecting.
+            if (!isAgentOnline(sub.agent_id))
+                continue;
+            const due = nextDue.get(key);
+            if (due === undefined) {
+                // First sight of this subscription: collect now, then settle into the jittered cadence. A
+                // new subscriber waiting a full interval for its first post looks broken and is.
+                nextDue.set(key, now);
+            }
+            else if (now < due) {
+                continue;
+            }
+            inFlight.add(key);
+            try {
+                await collector.collectOnce(sub.agent_id, sub.channel_pubkey);
+                await collector.repairGaps(sub.agent_id, sub.channel_pubkey);
+                backoff.delete(key);
+                nextDue.set(key, now + intervalMs + jitterForChannel(sub.channel_pubkey, sub.agent_id, jitterMs));
+            }
+            catch (err) {
+                // ⚠️ LOGGED, never swallowed and never fatal to the loop. A background collection that fails
+                // in silence is a subscriber who simply stops receiving, with nothing anywhere saying why —
+                // and one channel's bad relay must not stop every other channel on this daemon.
+                const next = Math.min(maxBackoffMs, (backoff.get(key) ?? intervalMs) * 2);
+                backoff.set(key, next);
+                nextDue.set(key, now + next + jitterForChannel(sub.channel_pubkey, sub.agent_id, jitterMs));
+                logger.warn("channel.collect.tick_failed", {
+                    channel_pubkey: sub.channel_pubkey,
+                    reason: extractErrorMessage(err),
+                    next_attempt_in_ms: next,
+                });
+            }
+            finally {
+                inFlight.delete(key);
+            }
+        }
+    }
+    return {
+        start() {
+            if (timer !== null)
+                return;
+            // The pass runs every interval and decides per subscription what is due; the jitter lives in
+            // the due times rather than in the timer, so one slow channel cannot drag the others.
+            timer = setInterval(() => {
+                void collectAllDue(Date.now()).catch((err) => {
+                    logger.warn("channel.collect.pass_failed", { reason: extractErrorMessage(err) });
+                });
+            }, intervalMs);
+            // Never hold the process open for a background poll.
+            timer.unref?.();
+            logger.info("channel.collect.started", { interval_ms: intervalMs, jitter_ms: jitterMs });
+        },
+        collectAllDue,
+        stop() {
+            if (timer !== null)
+                clearInterval(timer);
+            timer = null;
+        },
+    };
+}
+//# sourceMappingURL=channel-collect-tick.js.map

package/dist/channel-collect-tick.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-collect-tick.js","sourceRoot":"","sources":["../src/channel-collect-tick.ts"],"names":[],"mappings":"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"}

package/dist/channel-collector.d.ts

@@ -0,0 +1,99 @@
+/**
+ * ChannelCollector — M16 018-PUBCOLLECT, the subscriber half.
+ *
+ * A channel's two relays are **not coordinated**. Each holds its own queue, they disagree by design
+ * — different `first_held_seq`, different `last_seq`, different subsets — and none of that is an
+ * error. The subscriber fetches from both and takes the union.
+ *
+ * ⚠️ **EVERYTHING IS VERIFIED HERE.** Both signatures, the title rules, the size, and that the
+ * publishing agent is the admin THIS SUBSCRIBER knows for the channel. A relay's word that a post is
+ * good is worth nothing: the relay is a witness, not an authority, and the whole design assumes it
+ * may be hostile.
+ *
+ * ─── Two positions, and why a fetch may only move one ────────────────────────────────────────
+ *
+ *   delivered_through  how far the daemon has fetched and verified — moved here
+ *   processed_through  how far the AGENT has read — never touched here
+ *
+ * ─── The contiguous run ──────────────────────────────────────────────────────────────────────
+ *
+ * `delivered_through` advances only across an unbroken run. Holding 1, 2 and 4 leaves it at 2 —
+ * because advancing to 4 would mean post 3 is never delivered when it finally arrives, the position
+ * having already passed it. The gap is reported instead.
+ *
+ * ─── Forks ───────────────────────────────────────────────────────────────────────────────────
+ *
+ * Two different posts at one number means the channel signed both. Both are kept, the fork is
+ * reported with both hashes, and the position stops below it. Nothing is resolved automatically:
+ * picking one would make whichever relay answered first the arbiter of what the channel said.
+ */
+import type { Logger } from "./types.js";
+import { type ChannelAccess } from "@cello-protocol/protocol-types";
+import { ChannelInboxStore } from "./channel-inbox-store.js";
+import { ChannelSubscriptionStore } from "./channel-subscription-store.js";
+export type RelayFetchSeam = (relay: string, req: {
+    channel_pubkey: Uint8Array;
+    since_seq: number;
+    max_bytes: number;
+    auth?: {
+        signature: Uint8Array;
+        time_ms: number;
+    };
+    agent_pubkeys?: Uint8Array[];
+}) => Promise<{
+    ok: true;
+    posts: Array<{
+        seq: number;
+        post_cbor: Uint8Array;
+        receipt_cbor?: Uint8Array;
+    }>;
+    first_held_seq: number | null;
+    last_seq: number | null;
+} | {
+    ok: false;
+    reason: string;
+}>;
+export interface ChannelCollectorOptions {
+    logger: Logger;
+    subscriptions: ChannelSubscriptionStore;
+    inbox: ChannelInboxStore;
+    fetch: RelayFetchSeam;
+    /** The fetch-key signature for a non-public channel. 019 owns the key; `undefined` means public. */
+    fetchAuth: (access: ChannelAccess, channelHex: string, sinceSeq: number) => Promise<{
+        signature: Uint8Array;
+        time_ms: number;
+    } | undefined>;
+    /** Local agent keys to declare for the reader count. Best-effort, and never affects delivery. */
+    localAgentKeys: (channelHex: string) => Uint8Array[];
+    /** Ask the PUBLISHER to re-deposit a range. It answers by re-depositing, never by sending posts. */
+    requestRepair: (agentId: string, channelHex: string, from: number, to: number) => Promise<void>;
+    now?: () => number;
+    maxBytesPerFetch?: number;
+}
+export interface GapReport {
+    missing: number[];
+    first_held_seq: number;
+}
+export declare class ChannelCollector {
+    #private;
+    constructor(opts: ChannelCollectorOptions);
+    /** One pass over one channel: fetch both relays, verify, store, advance. */
+    collectOnce(agentId: string, channelHex: string, correlationId?: string): Promise<void>;
+    /**
+     * What is missing between the relays' floor and the highest post seen.
+     *
+     * ⚠️ **BELOW `first_held_seq` IS NEVER A GAP.** Those posts were pruned or aged out on purpose.
+     * Reporting them would have every subscriber demand content that no longer exists, for ever.
+     */
+    gapsFor(agentId: string, channelHex: string): GapReport;
+    /**
+     * Repair what is still missing: the OTHER relay first, then the publisher.
+     *
+     * The other relay is asked first because it costs nothing and usually has it — the two queues
+     * disagree by design. The publisher is a last resort and is asked ONCE per gap: a gap that
+     * survives both is reported, not re-requested every tick, or a permanently pruned post becomes a
+     * permanent request loop.
+     */
+    repairGaps(agentId: string, channelHex: string, correlationId?: string): Promise<void>;
+}
+//# sourceMappingURL=channel-collector.d.ts.map

package/dist/channel-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-collector.d.ts","sourceRoot":"","sources":["../src/channel-collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAK3E,MAAM,MAAM,cAAc,GAAG,CAC3B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE;IACH,cAAc,EAAE,UAAU,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE;QAAE,SAAS,EAAE,UAAU,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAClD,aAAa,CAAC,EAAE,UAAU,EAAE,CAAC;CAC9B,KACE,OAAO,CACR;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,UAAU,CAAC;QAAC,YAAY,CAAC,EAAE,UAAU,CAAA;KAAE,CAAC,CAAC;IAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACrJ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAChC,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,wBAAwB,CAAC;IACxC,KAAK,EAAE,iBAAiB,CAAC;IACzB,KAAK,EAAE,cAAc,CAAC;IACtB,oGAAoG;IACpG,SAAS,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,SAAS,EAAE,UAAU,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;IAC5I,iGAAiG;IACjG,cAAc,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,UAAU,EAAE,CAAC;IACrD,oGAAoG;IACpG,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChG,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,gBAAgB;;gBAmBf,IAAI,EAAE,uBAAuB;IAKzC,4EAA4E;IACtE,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyI7F;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS;IAyCvD;;;;;;;OAOG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA6B7F"}