@hyperdrive.bot/fleet-server 0.3.148 → 0.3.150

package/dist/server/server/ingestion/subscriptions/notifier.js

@@ -0,0 +1,209 @@
+import { buildSubscriptionNotificationPrompt, toNotificationItem } from "./notification-prompt.js";
+/**
+ * Turns a filter's matches into notifications for every session subscribed to it.
+ *
+ * The whole delivery policy lives here, and it exists because neither of the
+ * two policies already in the daemon is usable for a notification:
+ *
+ * - A schedule fire REFUSES when the target is busy (`schedule/service.ts`
+ *   throws on `hasInFlightRun`), and the refusal is recorded as a failed run
+ *   whose cadence then advances, so the event is dropped rather than delayed.
+ * - `sendPromptToAgent` PREEMPTS, passing `replaceRunning: true`, which cancels
+ *   the turn in flight. For an unbidden "by the way" message that is the worst
+ *   of the three: it destroys work to deliver something explicitly optional.
+ *
+ * So this one waits. Items accumulate in the pending store and go out whole,
+ * coalesced, the next time the subscriber is idle and outside its debounce.
+ */
+export class SubscriptionNotifier {
+    constructor(options) {
+        this.subscriptions = options.subscriptions;
+        this.pending = options.pending;
+        this.agentManager = options.agentManager;
+        this.filterResolver = options.filterResolver;
+        this.send = options.send;
+        this.logger = options.logger;
+        this.now = options.now ?? (() => Date.now());
+    }
+    /**
+     * Record a filter's matches against every armed subscriber, then try to deliver.
+     *
+     * Recording is unconditional and delivery is not: an item is never lost
+     * because the subscriber happened to be mid-turn when it arrived.
+     */
+    async notifyForFilter(filter, matched) {
+        if (matched.length === 0) {
+            return [];
+        }
+        const subscribers = await this.subscriptions.listArmedForFilter(filter.id);
+        if (subscribers.length === 0) {
+            return [];
+        }
+        const detectedAt = this.now();
+        const results = [];
+        for (const subscription of subscribers) {
+            // Nothing that predates the subscription. Arming must never replay
+            // history: the poll reads a window wide enough to survive a sleeping
+            // daemon, so without this a brand new subscriber's FIRST notification
+            // would be everything already sitting in the aggregator's buffer. The
+            // schedule cadence states the same rule at `schedule/types.ts:19`, and
+            // backfill is the deliberate way to reach backwards.
+            const since = Date.parse(subscription.createdAt);
+            if (!Number.isFinite(since)) {
+                // Fail CLOSED. A guard whose failure mode is the exact thing it guards
+                // against is not a guard: falling back to "announce everything" would
+                // replay the whole poll window on one bad timestamp.
+                this.logger.warn({ subscriptionId: subscription.id, createdAt: subscription.createdAt }, "Subscription has an unparseable createdAt; announcing nothing until it is fixed");
+                results.push({ subscriptionId: subscription.id, outcome: "error", announced: 0 });
+                continue;
+            }
+            const eligible = matched.filter((entry) => entry.item.timestampMs >= since);
+            const skipped = matched.length - eligible.length;
+            if (skipped > 0) {
+                // Said out loud. An adapter that cannot date an item reports 0, which
+                // is before every subscription, so silence here would make a source
+                // that never delivers look exactly like a source that is simply quiet.
+                this.logger.info({ subscriptionId: subscription.id, filterId: filter.id, skipped }, "Items predating the subscription were not announced");
+            }
+            if (eligible.length === 0) {
+                results.push(await this.deliver(subscription, filter));
+                continue;
+            }
+            // Each subscriber gets its OWN pending rows for the same items. That
+            // duplication is the point: the ledger claims by (filter, item), so a
+            // shared row would let the first subscriber's claim silence the second,
+            // which is the opposite of what a subscription is for.
+            // A loop rather than `map` with a spread, per `no-map-spread`.
+            const rows = [];
+            for (const entry of eligible) {
+                rows.push(Object.assign(toNotificationItem(entry), {
+                    detectedAt,
+                    notifiedAt: null,
+                    payload: entry.item.payload,
+                }));
+            }
+            try {
+                await this.pending.append(subscription.id, rows);
+                results.push(await this.deliver(subscription, filter));
+            }
+            catch (error) {
+                // One broken subscriber must not stop the others. Swallowing without a
+                // reason would make a real bug look like a legitimate quiet tick, so
+                // the reason is always logged.
+                this.logger.warn({ err: error, subscriptionId: subscription.id, filterId: filter.id }, "Subscription notification failed");
+                results.push({ subscriptionId: subscription.id, outcome: "error", announced: 0 });
+            }
+        }
+        return results;
+    }
+    /**
+     * Try to announce whatever is pending for one subscription.
+     *
+     * Safe to call at any time, including from a sweep that has no new items:
+     * that is how a notice held back by a busy session eventually goes out.
+     */
+    async deliverPending(subscriptionId) {
+        const subscription = await this.subscriptions.get(subscriptionId);
+        if (!subscription) {
+            return { subscriptionId, outcome: "nothing-pending", announced: 0 };
+        }
+        const filter = await this.filterResolver(subscription.filterId);
+        if (!filter) {
+            return { subscriptionId, outcome: "filter-missing", announced: 0 };
+        }
+        return this.deliver(subscription, filter);
+    }
+    async deliver(subscription, filter) {
+        const id = subscription.id;
+        if (subscription.status !== "armed") {
+            return { subscriptionId: id, outcome: "paused", announced: 0 };
+        }
+        const waiting = await this.pending.listUnnotified(id);
+        if (waiting.length === 0) {
+            return { subscriptionId: id, outcome: "nothing-pending", announced: 0 };
+        }
+        // Debounce before the idle check, deliberately. Both hold the items back,
+        // but the debounce is a policy the user set and the idle check is a fact
+        // about the world, and checking the cheap declared policy first keeps a
+        // tight poll from hammering `hasInFlightRun` for every subscriber.
+        const now = this.now();
+        if (subscription.lastNotifiedAt !== null) {
+            const since = now - Date.parse(subscription.lastNotifiedAt);
+            if (Number.isFinite(since) && since < subscription.debounceMs) {
+                return { subscriptionId: id, outcome: "debounced", announced: 0 };
+            }
+        }
+        // The one policy that matters: a busy session is left alone. Nothing is
+        // cancelled and nothing is dropped; the items keep waiting.
+        if (this.agentManager.hasInFlightRun(subscription.agentId)) {
+            return { subscriptionId: id, outcome: "busy", announced: 0 };
+        }
+        const { body, announcedKeys } = buildSubscriptionNotificationPrompt({
+            subscription,
+            filter,
+            items: waiting,
+        });
+        const { route } = await this.send({ agentId: subscription.agentId, body });
+        if (route === "no-route") {
+            // Loaded, detached, and nothing on disk to resume from. The caller was
+            // told the truth rather than `accepted: true`, which is what the RPC
+            // handler does today, so the subscription can pause itself instead of
+            // marking items announced that nobody read.
+            this.logger.warn({ subscriptionId: id, agentId: subscription.agentId }, "Subscription target has no route; pausing rather than dropping items");
+            await this.subscriptions.put({
+                ...subscription,
+                status: "paused",
+                updatedAt: new Date(now).toISOString(),
+            });
+            return { subscriptionId: id, outcome: "no-route", announced: 0 };
+        }
+        const notifiedAt = new Date(now).toISOString();
+        // Mark AFTER the send returns a live route, never before: marking on
+        // dispatch is how a pipeline starts recording intent as fact.
+        // ONLY the keys the notice named. A notification caps its list, and an
+        // item announced merely as part of a count has no key anywhere the agent
+        // can reach: `get_subscription_items` takes keys. Marking it would strand
+        // it until the TTL sweep.
+        // Rows, not bare keys: the hash is what stops a version appended during
+        // the send from being stamped as if it were the one just announced.
+        const announcedRows = waiting.filter((item) => announcedKeys.includes(item.itemKey));
+        await this.pending.markNotified(id, announcedRows, notifiedAt);
+        await this.subscriptions.put({
+            ...subscription,
+            lastNotifiedAt: notifiedAt,
+            updatedAt: notifiedAt,
+        });
+        this.logger.info({
+            subscriptionId: id,
+            agentId: subscription.agentId,
+            announced: announcedKeys.length,
+            stillWaiting: waiting.length - announcedKeys.length,
+            route,
+        }, "Subscription notification delivered");
+        return { subscriptionId: id, outcome: "sent", announced: announcedKeys.length };
+    }
+    /**
+     * Try every armed subscription once.
+     *
+     * The drain. Without it a notice held back by `busy` or `debounced` would
+     * wait for the next item to arrive before anyone looked at it again, which
+     * on a quiet source can be hours.
+     */
+    async deliverAllPending() {
+        const all = await this.subscriptions.list();
+        const results = [];
+        for (const subscription of all) {
+            if (subscription.status !== "armed")
+                continue;
+            try {
+                results.push(await this.deliverPending(subscription.id));
+            }
+            catch (error) {
+                this.logger.warn({ err: error, subscriptionId: subscription.id }, "Subscription drain failed");
+                results.push({ subscriptionId: subscription.id, outcome: "error", announced: 0 });
+            }
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=notifier.js.map

package/dist/server/server/ingestion/subscriptions/pending-store.d.ts

@@ -0,0 +1,111 @@
+import { z } from "zod";
+/**
+ * One detected item, held until the subscriber has been told about it.
+ *
+ * This record does two jobs that look separate and are not:
+ *
+ * 1. **The coalescing accumulator.** A subscriber that is mid-turn, or inside
+ *    its debounce window, must not lose the event. The schedule engine's own
+ *    failure path is the cautionary tale: `finishRun` has no branch reading
+ *    `params.status`, so a run that failed because the agent was busy still
+ *    advances `nextRunAt` a whole cadence period, which turns "deliver later"
+ *    into "never". Holding the item here is the memory that path lacks.
+ * 2. **The payload for the fetch.** `ingestion_items` stores no payload and
+ *    cohort rows store fingerprints, so without this the `get_subscription_items`
+ *    tool would be a live network read that can come back empty for an item
+ *    that left the window between the notice and the question.
+ */
+export declare const PendingItemSchema: z.ZodObject<{
+    itemKey: z.ZodString;
+    contentHash: z.ZodString;
+    title: z.ZodString;
+    subtitle: z.ZodString;
+    timestampMs: z.ZodNumber;
+    detectedAt: z.ZodNumber;
+    notifiedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    payload: z.ZodUnknown;
+}, z.core.$strict>;
+export type PendingItem = z.infer<typeof PendingItemSchema>;
+/** How long a detected item is kept before the sweep deletes it. 7 days. */
+export declare const DEFAULT_PENDING_TTL_MS: number;
+/**
+ * Per-subscription pending items, one JSON file each under `dir`.
+ *
+ * Deliberately NOT a sqlite table. `ledger-schema.ts` creates its tables with
+ * bare `CREATE TABLE IF NOT EXISTS` and carries no migration step, so adding a
+ * column there is a change every existing `paseo.sqlite` silently does not get.
+ * A JSON file per subscription has the store convention the rest of ingestion
+ * already uses, and its failure mode is one unreadable subscription rather than
+ * a schema the database disagrees with.
+ */
+export declare class PendingItemStore {
+    private readonly dir;
+    constructor(dir: string);
+    /**
+     * One serialization chain per subscription.
+     *
+     * Every mutation here is read-modify-write over a whole JSON file, so two
+     * overlapping calls for the same subscription would each read the pre-state
+     * and the second write would erase the first. Today the only caller is the
+     * poller, whose tick is single-flight and sequential, so the race cannot
+     * happen by accident. That is exactly the kind of safety that stops being
+     * true the first time someone calls `deliverPending` from an RPC handler,
+     * and the failure it produces is a silently dropped notification rather than
+     * an error. Keyed by id, so two different subscriptions still run in
+     * parallel.
+     */
+    private readonly chains;
+    private withLock;
+    private filePath;
+    private ensureDir;
+    read(subscriptionId: string): Promise<PendingItem[]>;
+    private write;
+    /**
+     * Record newly detected items, keyed by `itemKey`.
+     *
+     * An item whose `contentHash` CHANGED replaces the stored one and is
+     * announced again, which mirrors the ledger's own rule (`contentChanged` at
+     * `ledger.ts:368-373`): a changed item is a new event, not a duplicate. An
+     * item whose hash is identical is left exactly as it is, including its
+     * `notifiedAt`, so re-detecting it does not re-announce it.
+     *
+     * Returns the items that are genuinely new or changed, which is what the
+     * caller announces.
+     */
+    append(subscriptionId: string, incoming: readonly PendingItem[]): Promise<PendingItem[]>;
+    private appendLocked;
+    /** Everything detected but not yet announced. The coalescing read. */
+    listUnnotified(subscriptionId: string): Promise<PendingItem[]>;
+    /** Stamp `notifiedAt` on the keys just announced, so they are not repeated. */
+    /**
+     * Stamp the rows just announced, matched on `(itemKey, contentHash)`.
+     *
+     * The hash is load-bearing, not belt and braces. The caller reads the
+     * waiting rows, awaits a network send, and only then marks: if an append
+     * lands in that gap carrying the SAME key with CHANGED content, the row on
+     * disk is a different event from the one the notice described. Matching on
+     * the key alone would stamp the new version as announced and it would never
+     * go out. This is the same rule the ledger states as "a changed item is a
+     * new event".
+     */
+    markNotified(subscriptionId: string, announced: readonly {
+        itemKey: string;
+        contentHash: string;
+    }[], notifiedAt: string): Promise<void>;
+    private markNotifiedLocked;
+    /** Resolve keys to their stored items. Absent keys are simply not returned. */
+    resolve(subscriptionId: string, itemKeys: readonly string[]): Promise<PendingItem[]>;
+    /**
+     * Delete items older than `ttlMs`, and the file itself once it is empty.
+     *
+     * This is the retention half of the credential-at-rest trade. It runs at
+     * boot beside the other sweeps rather than on a timer of its own: a payload
+     * that outlives its usefulness is the part of this design that ages badly.
+     */
+    sweepExpired(now: number, ttlMs?: number): Promise<number>;
+    /** Drop everything for a subscription that no longer exists. */
+    drop(subscriptionId: string): Promise<void>;
+    /** Whether the backing directory exists yet. Used only by diagnostics. */
+    exists(): Promise<boolean>;
+}
+//# sourceMappingURL=pending-store.d.ts.map

package/dist/server/server/ingestion/subscriptions/pending-store.js

@@ -0,0 +1,254 @@
+import { readFile, readdir, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { writeJsonFileAtomic } from "../../atomic-file.js";
+import { ensurePrivateDirectory, ensurePrivateFile } from "../../private-files.js";
+/**
+ * One detected item, held until the subscriber has been told about it.
+ *
+ * This record does two jobs that look separate and are not:
+ *
+ * 1. **The coalescing accumulator.** A subscriber that is mid-turn, or inside
+ *    its debounce window, must not lose the event. The schedule engine's own
+ *    failure path is the cautionary tale: `finishRun` has no branch reading
+ *    `params.status`, so a run that failed because the agent was busy still
+ *    advances `nextRunAt` a whole cadence period, which turns "deliver later"
+ *    into "never". Holding the item here is the memory that path lacks.
+ * 2. **The payload for the fetch.** `ingestion_items` stores no payload and
+ *    cohort rows store fingerprints, so without this the `get_subscription_items`
+ *    tool would be a live network read that can come back empty for an item
+ *    that left the window between the notice and the question.
+ */
+export const PendingItemSchema = z.strictObject({
+    itemKey: z.string(),
+    contentHash: z.string(),
+    title: z.string(),
+    subtitle: z.string(),
+    timestampMs: z.number(),
+    /** Epoch ms the daemon detected it. Drives the TTL sweep, never freshness. */
+    detectedAt: z.number(),
+    /** ISO 8601, or null while the item is still waiting to be announced. */
+    notifiedAt: z.string().nullable().default(null),
+    /**
+     * The raw aggregator event body.
+     *
+     * Stored because the user chose reliable fetch over a live re-read. The cost
+     * is real and is not hidden: an event body can contain a credential, so this
+     * file is the one place in ingestion that holds one at rest. Three things
+     * contain it, and none of them is optional: `$PASEO_HOME` is 0700, the value
+     * leaves the daemon ONLY through a local MCP tool and never through a client
+     * RPC, and `sweepExpired` deletes it on a TTL.
+     */
+    payload: z.unknown(),
+});
+const PendingFileSchema = z.strictObject({
+    subscriptionId: z.string(),
+    items: z.array(PendingItemSchema).default([]),
+});
+/** How long a detected item is kept before the sweep deletes it. 7 days. */
+export const DEFAULT_PENDING_TTL_MS = 7 * 86400000;
+/**
+ * Per-subscription pending items, one JSON file each under `dir`.
+ *
+ * Deliberately NOT a sqlite table. `ledger-schema.ts` creates its tables with
+ * bare `CREATE TABLE IF NOT EXISTS` and carries no migration step, so adding a
+ * column there is a change every existing `paseo.sqlite` silently does not get.
+ * A JSON file per subscription has the store convention the rest of ingestion
+ * already uses, and its failure mode is one unreadable subscription rather than
+ * a schema the database disagrees with.
+ */
+export class PendingItemStore {
+    constructor(dir) {
+        this.dir = dir;
+        /**
+         * One serialization chain per subscription.
+         *
+         * Every mutation here is read-modify-write over a whole JSON file, so two
+         * overlapping calls for the same subscription would each read the pre-state
+         * and the second write would erase the first. Today the only caller is the
+         * poller, whose tick is single-flight and sequential, so the race cannot
+         * happen by accident. That is exactly the kind of safety that stops being
+         * true the first time someone calls `deliverPending` from an RPC handler,
+         * and the failure it produces is a silently dropped notification rather than
+         * an error. Keyed by id, so two different subscriptions still run in
+         * parallel.
+         */
+        this.chains = new Map();
+    }
+    withLock(subscriptionId, work) {
+        const previous = this.chains.get(subscriptionId) ?? Promise.resolve();
+        // `catch` before chaining: one failed operation must not poison every
+        // later one on the same subscription.
+        const next = previous.then(work, work);
+        this.chains.set(subscriptionId, next.catch(() => undefined));
+        return next;
+    }
+    filePath(subscriptionId) {
+        return join(this.dir, `${subscriptionId}.json`);
+    }
+    async ensureDir() {
+        // 0700, not the default 0755.
+        //
+        // This is the one directory in ingestion that holds a raw aggregator event
+        // body at rest, and such a body can carry an OAuth token. `$PASEO_HOME` is
+        // already 0700, so a 0755 child is unreachable to another user by path
+        // anyway - which is exactly the argument `SourceStore` makes for using a
+        // plain mkdir. That argument is correct and still leaves this directory
+        // one misplaced `$PASEO_HOME` away from being world readable, and unlike a
+        // source record the contents here are secret. Defence in depth, measured:
+        // a bare recursive mkdir under umask 0022 produces 0755.
+        ensurePrivateDirectory(this.dir);
+    }
+    async read(subscriptionId) {
+        await this.ensureDir();
+        try {
+            const content = await readFile(this.filePath(subscriptionId), "utf-8");
+            return PendingFileSchema.parse(JSON.parse(content)).items;
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return [];
+            }
+            throw error;
+        }
+    }
+    async write(subscriptionId, items) {
+        await this.ensureDir();
+        const target = this.filePath(subscriptionId);
+        await writeJsonFileAtomic(target, { subscriptionId, items });
+        // 0600 on the file too, for the same reason and after the write, because
+        // the atomic write renames a fresh temp file into place each time.
+        ensurePrivateFile(target);
+    }
+    /**
+     * Record newly detected items, keyed by `itemKey`.
+     *
+     * An item whose `contentHash` CHANGED replaces the stored one and is
+     * announced again, which mirrors the ledger's own rule (`contentChanged` at
+     * `ledger.ts:368-373`): a changed item is a new event, not a duplicate. An
+     * item whose hash is identical is left exactly as it is, including its
+     * `notifiedAt`, so re-detecting it does not re-announce it.
+     *
+     * Returns the items that are genuinely new or changed, which is what the
+     * caller announces.
+     */
+    async append(subscriptionId, incoming) {
+        return this.withLock(subscriptionId, () => this.appendLocked(subscriptionId, incoming));
+    }
+    async appendLocked(subscriptionId, incoming) {
+        const existing = await this.read(subscriptionId);
+        const byKey = new Map(existing.map((item) => [item.itemKey, item]));
+        const fresh = [];
+        for (const item of incoming) {
+            const previous = byKey.get(item.itemKey);
+            if (previous && previous.contentHash === item.contentHash) {
+                continue;
+            }
+            byKey.set(item.itemKey, item);
+            fresh.push(item);
+        }
+        if (fresh.length > 0) {
+            await this.write(subscriptionId, [...byKey.values()]);
+        }
+        return fresh;
+    }
+    /** Everything detected but not yet announced. The coalescing read. */
+    async listUnnotified(subscriptionId) {
+        const items = await this.read(subscriptionId);
+        return items.filter((item) => item.notifiedAt === null);
+    }
+    /** Stamp `notifiedAt` on the keys just announced, so they are not repeated. */
+    /**
+     * Stamp the rows just announced, matched on `(itemKey, contentHash)`.
+     *
+     * The hash is load-bearing, not belt and braces. The caller reads the
+     * waiting rows, awaits a network send, and only then marks: if an append
+     * lands in that gap carrying the SAME key with CHANGED content, the row on
+     * disk is a different event from the one the notice described. Matching on
+     * the key alone would stamp the new version as announced and it would never
+     * go out. This is the same rule the ledger states as "a changed item is a
+     * new event".
+     */
+    async markNotified(subscriptionId, announced, notifiedAt) {
+        return this.withLock(subscriptionId, () => this.markNotifiedLocked(subscriptionId, announced, notifiedAt));
+    }
+    async markNotifiedLocked(subscriptionId, announced, notifiedAt) {
+        const wanted = new Set(announced.map((row) => `${row.itemKey}\u0000${row.contentHash}`));
+        const items = await this.read(subscriptionId);
+        // A loop rather than `map` with a spread: `no-map-spread` is on, and the
+        // rewritten row is built once per match instead of once per element.
+        const next = [];
+        for (const item of items) {
+            if (wanted.has(`${item.itemKey}\u0000${item.contentHash}`) && item.notifiedAt === null) {
+                next.push(Object.assign({}, item, { notifiedAt }));
+                continue;
+            }
+            next.push(item);
+        }
+        await this.write(subscriptionId, next);
+    }
+    /** Resolve keys to their stored items. Absent keys are simply not returned. */
+    async resolve(subscriptionId, itemKeys) {
+        const wanted = new Set(itemKeys);
+        const items = await this.read(subscriptionId);
+        return items.filter((item) => wanted.has(item.itemKey));
+    }
+    /**
+     * Delete items older than `ttlMs`, and the file itself once it is empty.
+     *
+     * This is the retention half of the credential-at-rest trade. It runs at
+     * boot beside the other sweeps rather than on a timer of its own: a payload
+     * that outlives its usefulness is the part of this design that ages badly.
+     */
+    async sweepExpired(now, ttlMs = DEFAULT_PENDING_TTL_MS) {
+        await this.ensureDir();
+        const entries = await readdir(this.dir, { withFileTypes: true });
+        let removed = 0;
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith(".json"))
+                continue;
+            const subscriptionId = entry.name.slice(0, -".json".length);
+            const items = await this.read(subscriptionId);
+            const kept = items.filter((item) => now - item.detectedAt < ttlMs);
+            removed += items.length - kept.length;
+            if (kept.length === items.length)
+                continue;
+            // Inside the lock: this is a read-modify-write like every other mutator,
+            // and an append landing between the read above and the write below would
+            // be erased with no error and no log. Safe today only because the caller
+            // awaits the sweep before starting the timer, which is exactly the kind
+            // of caller-sequencing guarantee this class refuses to rely on.
+            await this.withLock(subscriptionId, async () => {
+                const current = await this.read(subscriptionId);
+                const survivors = current.filter((item) => now - item.detectedAt < ttlMs);
+                if (survivors.length === 0) {
+                    await rm(this.filePath(subscriptionId), { force: true });
+                    return;
+                }
+                await this.write(subscriptionId, survivors);
+            });
+        }
+        return removed;
+    }
+    /** Drop everything for a subscription that no longer exists. */
+    async drop(subscriptionId) {
+        await this.withLock(subscriptionId, async () => {
+            await this.ensureDir();
+            await rm(this.filePath(subscriptionId), { force: true });
+            // The chain entry itself is dropped, so a deleted subscription does not
+            // leave a settled promise in the map for the life of the daemon.
+            this.chains.delete(subscriptionId);
+        });
+    }
+    /** Whether the backing directory exists yet. Used only by diagnostics. */
+    async exists() {
+        try {
+            await stat(this.dir);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=pending-store.js.map

package/dist/server/server/ingestion/subscriptions/poller.d.ts

@@ -0,0 +1,73 @@
+import type { StoredFilter } from "@hyperdrive.bot/fleet-protocol/ingestion/filter-types";
+import type { Logger } from "pino";
+import type { SourceStore } from "../sources/store.js";
+import type { SourceGateway, SourceKind } from "../types.js";
+import type { SubscriptionNotifier } from "./notifier.js";
+import type { PendingItemStore } from "./pending-store.js";
+import type { SubscriptionStore } from "./store.js";
+/** How often the poller reads its sources. */
+export declare const DEFAULT_POLL_INTERVAL_MS = 300000;
+/**
+ * How far back each poll reads.
+ *
+ * Wider than the interval on purpose: a daemon that was asleep, or a source
+ * whose aggregator buffer filled late, would otherwise leave a hole no later
+ * poll ever covers. Re-reading an item is free, because `PendingItemStore.append`
+ * ignores one whose `contentHash` is unchanged.
+ */
+export declare const POLL_WINDOW_DAYS = 1;
+export interface SubscriptionPollerOptions {
+    subscriptions: SubscriptionStore;
+    pending: PendingItemStore;
+    notifier: SubscriptionNotifier;
+    sourceStore: SourceStore;
+    filterResolver: (filterId: string) => Promise<StoredFilter | null>;
+    gatewayResolver: (kind: SourceKind) => SourceGateway;
+    logger: Logger;
+    intervalMs?: number;
+    now?: () => number;
+}
+export interface PollSummary {
+    /** Sources actually read. The number of NETWORK reads this tick cost. */
+    sourcesRead: number;
+    /** Filters evaluated against those reads, which costs CPU and not network. */
+    filtersMatched: number;
+    notified: number;
+}
+/**
+ * Reads each subscribed source ONCE per tick and fans the result out to every
+ * filter, and through them to every subscriber.
+ *
+ * The shape exists because of a measured cost: today two filters armed on one
+ * source cause two independent `listItems` walks, with no cache and no shared
+ * scan. With N subscribers that is N reads of the same aggregator buffer per
+ * window. Matching is pure string comparison over a dotted path, so fanning out
+ * in memory costs CPU while reading costs network, rate limit and latency.
+ * One read, many matches.
+ *
+ * It owns its own timer and touches the schedule engine not at all. A
+ * subscription is not a schedule: it must survive its target being archived,
+ * and `sweepOrphanedSchedules` would complete it terminally at the next boot.
+ */
+export declare class SubscriptionPoller {
+    private readonly options;
+    private readonly intervalMs;
+    private readonly now;
+    private timer;
+    /** Single-flight. A slow aggregator must not let two ticks overlap. */
+    private running;
+    constructor(options: SubscriptionPollerOptions);
+    start(): void;
+    stop(): void;
+    /**
+     * One pass: read every subscribed source once, match, notify, then drain.
+     *
+     * The drain at the end is what makes a notice held back by `busy` or
+     * `debounced` eventually go out even when the source has gone quiet.
+     */
+    tick(): Promise<PollSummary>;
+    private runTick;
+    /** Delete pending payloads past their TTL. Called at boot, beside the other sweeps. */
+    sweep(): Promise<number>;
+}
+//# sourceMappingURL=poller.d.ts.map