@hyperdrive.bot/fleet-server 0.3.147 → 0.3.149

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

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

@@ -0,0 +1,168 @@
+import { scanMatchedSourceItems, windowStartFor } from "../backfill.js";
+/** How often the poller reads its sources. */
+export 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 const POLL_WINDOW_DAYS = 1;
+/**
+ * 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 class SubscriptionPoller {
+    constructor(options) {
+        this.timer = null;
+        /** Single-flight. A slow aggregator must not let two ticks overlap. */
+        this.running = false;
+        this.options = options;
+        this.intervalMs = options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.now = options.now ?? (() => Date.now());
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            void this.tick().catch((error) => {
+                this.options.logger.warn({ err: error }, "Subscription poll tick failed");
+            });
+        }, this.intervalMs);
+        // Never keep the process alive for a poll.
+        this.timer.unref?.();
+        this.options.logger.info({ intervalMs: this.intervalMs }, "Subscription poller started");
+    }
+    stop() {
+        if (!this.timer)
+            return;
+        clearInterval(this.timer);
+        this.timer = null;
+    }
+    /**
+     * 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.
+     */
+    async tick() {
+        if (this.running) {
+            return { sourcesRead: 0, filtersMatched: 0, notified: 0 };
+        }
+        this.running = true;
+        try {
+            return await this.runTick();
+        }
+        finally {
+            this.running = false;
+        }
+    }
+    async runTick() {
+        const { subscriptions, filterResolver, sourceStore, gatewayResolver, logger } = this.options;
+        const armed = (await subscriptions.list()).filter((s) => s.status === "armed");
+        const summary = { sourcesRead: 0, filtersMatched: 0, notified: 0 };
+        if (armed.length === 0) {
+            return summary;
+        }
+        // Resolve the distinct filters once. Several subscribers commonly share one.
+        const filters = new Map();
+        for (const subscription of armed) {
+            if (filters.has(subscription.filterId))
+                continue;
+            const filter = await filterResolver(subscription.filterId);
+            if (!filter) {
+                logger.warn({ subscriptionId: subscription.id, filterId: subscription.filterId }, "Subscription points at a filter that no longer exists");
+                continue;
+            }
+            if (filter.status !== "armed")
+                continue;
+            filters.set(filter.id, filter);
+        }
+        // Group by source: this is the line that turns N reads into one.
+        const bySource = new Map();
+        for (const filter of filters.values()) {
+            const list = bySource.get(filter.sourceId);
+            if (list)
+                list.push(filter);
+            else
+                bySource.set(filter.sourceId, [filter]);
+        }
+        const now = this.now();
+        for (const [sourceId, sourceFilters] of bySource) {
+            const source = await sourceStore.get(sourceId);
+            if (!source) {
+                logger.warn({ sourceId }, "Subscribed filter points at a source that no longer exists");
+                continue;
+            }
+            let gateway;
+            try {
+                gateway = gatewayResolver(source.kind);
+            }
+            catch (error) {
+                logger.warn({ err: error, sourceId, kind: source.kind }, "No gateway for source kind");
+                continue;
+            }
+            for (const filter of sourceFilters) {
+                try {
+                    const { matched } = await scanMatchedSourceItems({
+                        filter,
+                        gateway,
+                        externalUserId: source.externalUserId,
+                        accountId: source.externalAccountId ?? "",
+                        // Freshness is the pending store's job, keyed per subscriber, so
+                        // this read deliberately answers "already handled?" with null for
+                        // everything. Asking the shared ledger here would be a second,
+                        // filter-wide answer to a question that is per subscription.
+                        ledger: { get: () => Promise.resolve(null) },
+                        sinceMs: windowStartFor(now, POLL_WINDOW_DAYS),
+                        now: () => now,
+                    });
+                    summary.filtersMatched += 1;
+                    if (matched.length === 0)
+                        continue;
+                    const results = await this.options.notifier.notifyForFilter(filter, matched);
+                    summary.notified += results.filter((result) => result.outcome === "sent").length;
+                }
+                catch (error) {
+                    // A failing filter must not abandon its siblings on the same read.
+                    logger.warn({ err: error, filterId: filter.id, sourceId }, "Subscription scan failed");
+                }
+            }
+            summary.sourcesRead += 1;
+        }
+        const drained = await this.options.notifier.deliverAllPending();
+        summary.notified += drained.filter((result) => result.outcome === "sent").length;
+        // Retention runs on the TICK, not only at boot. Sweeping only at startup
+        // makes real retention `max(uptime, ttl)`, so a daemon up for forty days
+        // holds forty days of payloads while the docstring promises seven. That
+        // TTL is one of the three things containing a credential at rest, so it
+        // cannot depend on how often the process restarts. `IngestionService` does
+        // the same on its own health timer.
+        await this.sweep().catch((error) => {
+            this.options.logger.warn({ err: error }, "Subscription payload sweep failed");
+        });
+        return summary;
+    }
+    /** Delete pending payloads past their TTL. Called at boot, beside the other sweeps. */
+    async sweep() {
+        const removed = await this.options.pending.sweepExpired(this.now());
+        if (removed > 0) {
+            this.options.logger.info({ removed }, "Swept expired subscription payloads");
+        }
+        return removed;
+    }
+}
+//# sourceMappingURL=poller.js.map

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

@@ -0,0 +1,39 @@
+import type { StoredSubscription } from "@hyperdrive.bot/fleet-protocol/ingestion/subscription-types";
+import type { PendingItem, PendingItemStore } from "./pending-store.js";
+import type { SubscriptionStore } from "./store.js";
+/**
+ * The READ half of subscriptions, and the only half a model ever holds.
+ *
+ * Deliberately not the notifier and not the stores themselves. A tool catalog
+ * that could arm a subscription, or trigger a delivery, would put the delivery
+ * policy inside a model's reach; this interface cannot do either. It exists as
+ * an interface rather than a concrete class so the tool layer depends on three
+ * methods instead of on the ingestion module.
+ */
+export interface SubscriptionReader {
+    /**
+     * Subscriptions the CALLER owns, never the daemon's whole set.
+     *
+     * `callerAgentId` is not decoration. Without it this is an enumeration step:
+     * one session lists every subscription on the box, reads another session's
+     * agent id, and then reads that session's stored payloads, credentials
+     * included. "A local MCP tool" means every agent on this daemon, which is
+     * not the same thing as the owner.
+     */
+    list(callerAgentId: string | undefined): Promise<StoredSubscription[]>;
+    get(subscriptionId: string, callerAgentId: string | undefined): Promise<StoredSubscription | null>;
+    /**
+     * Stored items for the given keys, payload included.
+     *
+     * This is the ONLY path by which a persisted payload leaves the daemon, and
+     * it is a local MCP call: no client RPC exposes it. Keys that are not held
+     * are simply absent from the result, the same contract `resolveMatchedItems`
+     * already has, so a caller sees a shorter list rather than an exception.
+     */
+    resolveItems(subscriptionId: string, itemKeys: readonly string[], callerAgentId: string | undefined): Promise<PendingItem[]>;
+}
+export declare function createSubscriptionReader(deps: {
+    subscriptions: SubscriptionStore;
+    pending: PendingItemStore;
+}): SubscriptionReader;
+//# sourceMappingURL=reader.d.ts.map

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

@@ -0,0 +1,30 @@
+export function createSubscriptionReader(deps) {
+    /**
+     * Fails CLOSED when the caller is unknown.
+     *
+     * An absent `callerAgentId` means the tool catalog was built without a
+     * caller identity, and the safe reading of "I do not know who is asking" is
+     * "you own nothing", not "you own everything".
+     */
+    const owns = (subscription, callerAgentId) => callerAgentId !== undefined && subscription.agentId === callerAgentId;
+    return {
+        list: async (callerAgentId) => (await deps.subscriptions.list()).filter((subscription) => owns(subscription, callerAgentId)),
+        get: async (subscriptionId, callerAgentId) => {
+            const subscription = await deps.subscriptions.get(subscriptionId);
+            if (!subscription || !owns(subscription, callerAgentId))
+                return null;
+            return subscription;
+        },
+        resolveItems: async (subscriptionId, itemKeys, callerAgentId) => {
+            // A subscription that no longer exists, or that belongs to someone else,
+            // resolves to nothing. Both answer the same way on purpose: a caller
+            // must not be able to tell "no such subscription" from "not yours" and
+            // use the difference to enumerate.
+            const subscription = await deps.subscriptions.get(subscriptionId);
+            if (!subscription || !owns(subscription, callerAgentId))
+                return [];
+            return deps.pending.resolve(subscriptionId, itemKeys);
+        },
+    };
+}
+//# sourceMappingURL=reader.js.map

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

@@ -0,0 +1,35 @@
+import { type StoredSubscription } from "@hyperdrive.bot/fleet-protocol/ingestion/subscription-types";
+/**
+ * File-backed persistence for session subscriptions, one JSON file per
+ * subscription under `dir` (the caller supplies `join(paseoHome, "subscriptions")`).
+ *
+ * Structurally identical to `SourceStore` and `ScheduleStore`, deliberately: a
+ * third shape here would be a third set of atomicity and parse bugs to find.
+ *
+ * `StoredSubscriptionSchema` is strict and `list()` is readdir + Promise.all, so
+ * ONE unparseable file rejects the whole array. That is the same trade the
+ * source store makes, and it carries the same obligation: every field added to
+ * the schema later must carry `.default(...)`, or records written before it
+ * existed stop parsing and every subscription silently disappears. There is no
+ * migration step. `accountLabel` on `StoredSourceSchema` is the precedent.
+ */
+export declare class SubscriptionStore {
+    private readonly dir;
+    constructor(dir: string);
+    private filePath;
+    private ensureDir;
+    list(): Promise<StoredSubscription[]>;
+    get(id: string): Promise<StoredSubscription | null>;
+    /**
+     * Every armed subscription pointing at `filterId`.
+     *
+     * The fan-out read. A filter with three armed subscribers returns three
+     * records here, and each one is notified on its own budget: this is the
+     * function that makes one filter serve many sessions.
+     */
+    listArmedForFilter(filterId: string): Promise<StoredSubscription[]>;
+    create(subscription: Omit<StoredSubscription, "id">): Promise<StoredSubscription>;
+    put(subscription: StoredSubscription): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map