@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/ingestion/reconcile/signature-guard.js

@@ -0,0 +1,82 @@
+// THE LAST LINE OF DEFENCE between a reconciler and a persisted column.
+//
+// A reconciler is the only code in this epic that ever holds `{ url, headers }`
+// - an MCP endpoint and its bearer token. It is handed that target as an
+// argument precisely so it has no store to write to and no config to mutate
+// (see `types.ts`), but it CAN still return a string, and that string is
+// written to `ingestion_items.verified_signature` where it survives restarts
+// and is read back onto a screen.
+//
+// So the write boundary refuses, loudly, rather than trusting six files to be
+// written carefully. That is what makes NFR1 ("no credential ever reaches a
+// persisted column") hold by construction even if one reconciler is written
+// carelessly later, in a story nobody has read yet.
+//
+// This throws rather than sanitizing. A truncated or redacted credential is
+// still evidence a credential was on that code path, and silently storing a
+// scrubbed version would hide the bug that produced it. The exception names
+// the failure at the moment it is cheapest to fix.
+/**
+ * Longest signature this column will accept.
+ *
+ * A signature is meant to be a short human-readable fact - `mr:merged:abc123def`,
+ * `pr:closed:42`. Nothing legitimate is 200 characters, and a long one is the
+ * shape of a pasted blob: a JWT, a response body, a header dump. The cap is a
+ * blast-radius limit AND a smell detector, and it fires before the pattern
+ * checks so an enormous input is rejected without regexing it.
+ */
+export const MAX_SIGNATURE_LEN = 200;
+/**
+ * Shapes that must never be persisted, in one place.
+ *
+ * Read it as "what a credential looks like when it leaks", not "what a
+ * credential is": each branch is a real thing that ends up in a signature when
+ * somebody echoes a header, a query string or a raw token.
+ *
+ *   `bearer\s`      an `Authorization: Bearer ...` value, header name stripped
+ *   `authorization` the header name itself, in any casing
+ *   `x-api-key`     the second header both aggregators send
+ *   `x-pd-`         Pipedream's own header family (`x-pd-environment`, ...)
+ *   `_authToken`    the npm/registry token key, and the shape of a config echo
+ *   `token=`        a token pasted into a query string
+ *   `secret`        the word, wherever it appears
+ *   `^[\w-]{40,}$`   an opaque high-entropy blob with no structure -
+ *                   the shape of a raw API key that carries none of the words
+ *                   above. Anchored, so a legitimate signature that merely
+ *                   CONTAINS a long sha (`mr:merged:<40-char-sha>`) still
+ *                   passes: the prefix and colons break the anchor.
+ */
+const UNSAFE_SIGNATURE_PATTERN = /bearer\s|authorization|x-api-key|x-pd-|_authToken|token=|secret|^[\w-]{40,}$/i;
+/**
+ * A reconciler tried to persist something that looks like a credential.
+ *
+ * Deliberately carries NO copy of the offending value. Attaching it would move
+ * the leak from the database into the log file, which is the same leak with a
+ * different retention policy. The `reason` is a closed set this module wrote.
+ */
+export class UnsafeSignatureError extends Error {
+    constructor(reason) {
+        super(reason === "too-long"
+            ? `Reconcile signature exceeds ${MAX_SIGNATURE_LEN} characters and was refused.`
+            : "Reconcile signature is credential-shaped and was refused.");
+        this.name = "UnsafeSignatureError";
+        this.reason = reason;
+    }
+}
+/**
+ * Throw unless `signature` is safe to write to a durable column.
+ *
+ * `null` is always safe and is the common case: every verdict except the two
+ * closing ones ships a null signature, and this story's stubs ship nothing else.
+ */
+export function assertSafeSignature(signature) {
+    if (signature === null)
+        return;
+    if (signature.length > MAX_SIGNATURE_LEN) {
+        throw new UnsafeSignatureError("too-long");
+    }
+    if (UNSAFE_SIGNATURE_PATTERN.test(signature)) {
+        throw new UnsafeSignatureError("credential-shaped");
+    }
+}
+//# sourceMappingURL=signature-guard.js.map

package/dist/server/server/ingestion/reconcile/testing/fake-mcp-server.d.ts

@@ -0,0 +1,68 @@
+/** What a fake tool hands back. Exactly one of the three, never two. */
+export interface FakeToolReply {
+    /** Serialized to a JSON text content block, the shape aggregator servers emit. */
+    payload?: unknown;
+    /** An in-band MCP tool failure: `isError: true` with no usable content. */
+    isError?: boolean;
+    /** A raw text block that is NOT JSON, for the malformed-body case. */
+    rawText?: string;
+    /** Content array left empty, for the "a read that told you nothing" case. */
+    emptyContent?: boolean;
+}
+export type FakeTool = (args: Record<string, unknown>) => FakeToolReply;
+export interface FakeMcpServerHandle {
+    url: string;
+    /** Every header set the endpoint actually received, in arrival order. */
+    receivedHeaders: Array<Record<string, string>>;
+    /** Every tool call the endpoint actually received, in arrival order. */
+    calls: Array<{
+        name: string;
+        args: Record<string, unknown>;
+    }>;
+    close(): Promise<void>;
+}
+/**
+ * Start an MCP endpoint that answers `tools/call` from a plain lookup table.
+ *
+ * STATELESS (`sessionIdGenerator: undefined`) and one transport per POST, so
+ * concurrent reads from the worker pool cannot interleave on one session. That
+ * is not test hygiene for its own sake: the service runs four reads at once by
+ * design, and a shared-session fake would serialise them and hide any
+ * concurrency bug this harness exists to expose.
+ */
+export declare function startFakeMcpServer(tools: Record<string, FakeTool>): Promise<FakeMcpServerHandle>;
+/** Every way an HTTP endpoint can refuse to be an MCP server. */
+export interface BrokenHttpOptions {
+    /** The status to answer with. Ignored when `destroySocket` is true. */
+    status?: number;
+    headers?: Record<string, string>;
+    body?: string;
+    /** Cut the connection without a response: a transport-level network error. */
+    destroySocket?: boolean;
+    /** Answer nothing at all, so the caller's timeout or abort is what ends it. */
+    hang?: boolean;
+}
+export interface BrokenHttpHandle {
+    url: string;
+    /** How many requests actually arrived. Zero after a backoff gate is asserted. */
+    requestCount(): number;
+    close(): Promise<void>;
+}
+/**
+ * An HTTP endpoint that fails in exactly one named way.
+ *
+ * `hang` keeps the socket open and answers nothing, which is the only honest way
+ * to test the timeout: a fast 504 exercises the non-2xx path instead, and the
+ * two failures reach the reconciler through different code.
+ */
+export declare function startBrokenHttpServer(options: BrokenHttpOptions): Promise<BrokenHttpHandle>;
+/**
+ * A URL nothing is listening on.
+ *
+ * Bind, read the port, close, hand back the dead address. Picking a number by
+ * hand would race whatever else on this machine happens to own it, and a test
+ * that fails because port 9999 was busy teaches the next reader to distrust the
+ * suite.
+ */
+export declare function unusedLocalUrl(): Promise<string>;
+//# sourceMappingURL=fake-mcp-server.d.ts.map

package/dist/server/server/ingestion/reconcile/testing/fake-mcp-server.js

@@ -0,0 +1,158 @@
+// A REAL local MCP endpoint, and a real broken one beside it.
+//
+// The reconciler tests could have mocked `callMcpTool` and asserted the verdict
+// mapping in isolation. They deliberately do not, because three of the five ways
+// this story can lose data live BELOW that mock:
+//
+//   a non-2xx status      only an HTTP server can produce one
+//   a malformed body      only a real transport tries to parse it
+//   an aborted request    only a real socket can be cut mid-flight
+//
+// A mocked transport asserts that the code we wrote does what we wrote. A real
+// server on 127.0.0.1 asserts that a 429 from Composio does not close a row.
+//
+// Two servers, because they answer different questions:
+//   `startFakeMcpServer`     speaks MCP correctly and returns the payload you gave it
+//   `startBrokenHttpServer`  answers every request with the failure you asked for
+//
+// Both bind to 127.0.0.1 on an EPHEMERAL port. Nothing in this file can reach a
+// real Gmail, GitLab, GitHub, Jira, Sentry or Calendar account.
+import { createServer } from "node:http";
+import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Start an MCP endpoint that answers `tools/call` from a plain lookup table.
+ *
+ * STATELESS (`sessionIdGenerator: undefined`) and one transport per POST, so
+ * concurrent reads from the worker pool cannot interleave on one session. That
+ * is not test hygiene for its own sake: the service runs four reads at once by
+ * design, and a shared-session fake would serialise them and hide any
+ * concurrency bug this harness exists to expose.
+ */
+export async function startFakeMcpServer(tools) {
+    const receivedHeaders = [];
+    const calls = [];
+    const http = createServer((req, res) => {
+        void handle(req, res).catch(() => {
+            if (!res.headersSent)
+                res.writeHead(500).end();
+        });
+    });
+    async function handle(req, res) {
+        const headers = {};
+        for (const [name, value] of Object.entries(req.headers)) {
+            if (typeof value === "string")
+                headers[name] = value;
+        }
+        receivedHeaders.push(headers);
+        const mcp = new McpServer({ name: "fake-source", version: "0.0.0" }, { capabilities: { tools: {} } });
+        mcp.setRequestHandler(ListToolsRequestSchema, () => ({
+            tools: Object.keys(tools).map((name) => ({
+                name,
+                inputSchema: { type: "object" },
+            })),
+        }));
+        mcp.setRequestHandler(CallToolRequestSchema, (request) => {
+            const args = (request.params.arguments ?? {});
+            calls.push({ name: request.params.name, args });
+            const tool = tools[request.params.name];
+            if (!tool)
+                return { content: [], isError: true };
+            const reply = tool(args);
+            if (reply.isError === true)
+                return { content: [], isError: true };
+            if (reply.emptyContent === true)
+                return { content: [] };
+            if (typeof reply.rawText === "string") {
+                return { content: [{ type: "text", text: reply.rawText }] };
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(reply.payload ?? null) }],
+            };
+        });
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true,
+        });
+        res.on("close", () => {
+            void transport.close();
+            void mcp.close();
+        });
+        await mcp.connect(transport);
+        await transport.handleRequest(req, res);
+    }
+    await new Promise((resolve) => http.listen(0, "127.0.0.1", resolve));
+    const port = http.address().port;
+    return {
+        url: `http://127.0.0.1:${port}/mcp`,
+        receivedHeaders,
+        calls,
+        close: () => closeServer(http),
+    };
+}
+/**
+ * An HTTP endpoint that fails in exactly one named way.
+ *
+ * `hang` keeps the socket open and answers nothing, which is the only honest way
+ * to test the timeout: a fast 504 exercises the non-2xx path instead, and the
+ * two failures reach the reconciler through different code.
+ */
+export async function startBrokenHttpServer(options) {
+    let requests = 0;
+    const sockets = new Set();
+    const http = createServer((req, res) => {
+        requests += 1;
+        // The body must be drained or Node holds the request open and the
+        // "hang" case becomes indistinguishable from a slow upload.
+        req.resume();
+        if (options.destroySocket === true) {
+            res.destroy();
+            return;
+        }
+        if (options.hang === true) {
+            sockets.add(res);
+            res.on("close", () => sockets.delete(res));
+            return;
+        }
+        res.writeHead(options.status ?? 500, {
+            "content-type": "application/json",
+            ...options.headers,
+        });
+        res.end(options.body ?? '{"error":"nope"}');
+    });
+    await new Promise((resolve) => http.listen(0, "127.0.0.1", resolve));
+    const port = http.address().port;
+    return {
+        url: `http://127.0.0.1:${port}/mcp`,
+        requestCount: () => requests,
+        close: async () => {
+            for (const res of sockets)
+                res.destroy();
+            sockets.clear();
+            await closeServer(http);
+        },
+    };
+}
+/**
+ * A URL nothing is listening on.
+ *
+ * Bind, read the port, close, hand back the dead address. Picking a number by
+ * hand would race whatever else on this machine happens to own it, and a test
+ * that fails because port 9999 was busy teaches the next reader to distrust the
+ * suite.
+ */
+export async function unusedLocalUrl() {
+    const http = createServer();
+    await new Promise((resolve) => http.listen(0, "127.0.0.1", resolve));
+    const port = http.address().port;
+    await closeServer(http);
+    return `http://127.0.0.1:${port}/mcp`;
+}
+function closeServer(server) {
+    return new Promise((resolve) => {
+        server.closeAllConnections();
+        server.close(() => resolve());
+    });
+}
+//# sourceMappingURL=fake-mcp-server.js.map

package/dist/server/server/ingestion/reconcile/types.d.ts

@@ -0,0 +1,65 @@
+import type { McpTarget } from "../types.js";
+import type { ReconcileVerdict } from "@hyperdrive.bot/fleet-protocol/ingestion/run-view";
+/** Re-exported, never re-declared. The protocol enum is the single definition. */
+export type { ReconcileVerdict };
+/**
+ * Everything a reconciler is allowed to know about an item.
+ *
+ * `meta` is the Epic 3 ledger allow-list ONLY - `sourceId`, `subject`, `url`,
+ * `groupKey`, `receivedAt`. Do not enumerate beyond those five keys: the source
+ * payload is opaque by Epic 1's rule, and a reconciler that reached for a sixth
+ * would be reading a field the ledger never promised to store.
+ */
+export interface SourceItemRef {
+    itemKey: string;
+    meta: Record<string, unknown>;
+}
+export interface ReconcileResult {
+    verdict: ReconcileVerdict;
+    /** Human-readable, non-PII, never a credential. Guarded by `assertSafeSignature`. */
+    signature: string | null;
+}
+/**
+ * One app's answer to "is this item still open at the source?".
+ *
+ * Receives `{ url, headers }` as an ARGUMENT, per turn. It is handed no store,
+ * no config and no `sourceId`, so it has no write path to `~/.paseo/sources/`
+ * and NFR1 holds by construction rather than by review.
+ *
+ * The signal is ADVISORY. `ReconciliationService` races it against a timeout and
+ * does not trust a reconciler to honour it - a reconciler that ignores its
+ * signal delays nothing but itself.
+ */
+export type Reconciler = (target: McpTarget, ref: SourceItemRef, signal: AbortSignal) => Promise<ReconcileResult>;
+/**
+ * Resolve the MCP endpoint for one source and app.
+ *
+ * A PORT, not `SourceGateway` (decision D-6.1-J). Story 6.2 supplies the real
+ * implementation, which is one line over `SourceGateway.mcpTarget`. Keeping it
+ * a function type keeps the credential surface to a single argument that the
+ * service assigns to a local `const` and never to a field.
+ */
+export type ResolveMcpTarget = (sourceId: string, appSlug: string) => Promise<McpTarget>;
+export interface ReconcileCandidate {
+    filterId: string;
+    itemKey: string;
+    /** `StoredFilter.match.appSlug`. Opaque runtime string; the registry is the only enumeration. */
+    appSlug: string;
+    /** `StoredFilter.sourceId`. Groups reads so one dead source cannot blank another (NFR7). */
+    sourceId: string;
+    ref: SourceItemRef;
+}
+export interface ReconcileOutcome {
+    filterId: string;
+    itemKey: string;
+    /** Null when the item has never been verified AND this call issued no read. */
+    verdict: ReconcileVerdict | null;
+    signature: string | null;
+    verifiedAt: number | null;
+    reconcileFailCount: number;
+    /** True only when a source read actually happened during THIS call. */
+    read: boolean;
+    /** True when the candidate was skipped because no reconciler exists for its slug (D-6.1-B). */
+    skippedNoReconciler: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/server/server/ingestion/reconcile/types.js

@@ -0,0 +1,11 @@
+// THE RECONCILE CONTRACT - what a reconciler is allowed to know, and what it is
+// allowed to say.
+//
+// Both halves are deliberately small. A reconciler answers one question about
+// one item ("does the source still think this is open?") and returns one of four
+// verdicts. It is handed the MCP target as an ARGUMENT rather than a store, a
+// config or a sourceId, which is what makes NFR1 hold by construction: there is
+// no object in scope through which it could write to `~/.paseo/sources/`, and
+// nothing it returns can carry a credential past `assertSafeSignature`.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/server/server/ingestion/reconcile/verdict-mapping.d.ts

@@ -0,0 +1,54 @@
+import type { ReconcileVerdict } from "@hyperdrive.bot/fleet-protocol/ingestion/run-view";
+/**
+ * The five independent effects one verdict has on one row.
+ *
+ * Booleans rather than a single enum because the effects are genuinely
+ * independent: `pending` stamps AND clears the counter AND stays in the Inbox,
+ * and no single label covers that. An enum here would need one member per
+ * combination, which is the truth table with worse names.
+ */
+export interface VerdictRowState {
+    /** Does a run carrying this verdict belong in the Inbox at all? */
+    inInbox: boolean;
+    /**
+     * Does this outcome earn a fresh `verified_at`?
+     *
+     * `unreachable` never does (epic D4). Letting a failed read refresh the stamp
+     * would let a source that has been down for a week read as freshly verified,
+     * and the staleness gate would then stop retrying it. A failed read must age,
+     * not reset.
+     */
+    advancesVerifiedAt: boolean;
+    /** Only a CLOSING verdict carries evidence, so only a closing verdict writes one. */
+    writesSignature: boolean;
+    /**
+     * Reconciliation's OWN counter (`reconcile_fail_count`).
+     *
+     * NEVER Epic 3's dispatch `fail_count` (epic D5). A source paseo could not
+     * read is not an item that failed to dispatch, and burning the dispatch
+     * backoff on a network condition would park a perfectly good item.
+     */
+    clearsFailCount: boolean;
+    incrementsReconcileFailCount: boolean;
+}
+/**
+ * One verdict to its row policy. Total over the union, by construction.
+ *
+ * `handled-elsewhere` and `artifact-gone` REMOVE a row; they never label one.
+ * There is no sixth wall type and this function must never grow a field that
+ * would imply one (epic cross-dependency with Epic 4).
+ */
+export declare function mapVerdict(verdict: ReconcileVerdict): VerdictRowState;
+/**
+ * Does a run carrying this verdict belong in the Inbox?
+ *
+ * `null` - NOBODY HAS LOOKED - is `true`, and that default is the whole reason
+ * this wrapper exists rather than every caller writing
+ * `view.verdict === null || mapVerdict(view.verdict).inInbox` for itself. An
+ * unverified row is an OPEN obligation until a source says otherwise; treating
+ * "no verdict yet" as a close would hide every row on a daemon whose
+ * reconciliation is disabled, whose ledger just migrated, or whose first pass
+ * has not run.
+ */
+export declare function isInInbox(verdict: ReconcileVerdict | null): boolean;
+//# sourceMappingURL=verdict-mapping.d.ts.map

package/dist/server/server/ingestion/reconcile/verdict-mapping.js

@@ -0,0 +1,82 @@
+// WHAT A VERDICT IS ALLOWED TO DO TO A ROW, in one place with no `default`.
+//
+// Every consumer of a verdict - the ledger write, the `ingestion/runs` filter,
+// the backoff counter - reads its policy from here rather than re-deriving it
+// from a string comparison. That is the point: three `verdict === "unreachable"`
+// checks in three files are three chances to disagree, and the one that
+// disagrees quietly is the one that closes a row nobody handled.
+//
+// The switch has NO `default` branch and a `const _exhaustive: never` tail, so
+// a fifth verdict added to `ReconcileVerdictSchema` fails `tsc` here rather than
+// falling through to whatever the default happened to say. `verdict-mapping.test.ts`
+// iterates `ReconcileVerdictSchema.options`, so it fails the suite too.
+//
+// Deliberately NOT here: any user-facing English. `pending -> "Waiting"`,
+// `unreachable -> "Could not verify"` and their two siblings are Story 6.3's
+// second exhaustive switch, on the client where the i18n keys live. A daemon
+// that ships label text ships it in one language.
+/**
+ * One verdict to its row policy. Total over the union, by construction.
+ *
+ * `handled-elsewhere` and `artifact-gone` REMOVE a row; they never label one.
+ * There is no sixth wall type and this function must never grow a field that
+ * would imply one (epic cross-dependency with Epic 4).
+ */
+export function mapVerdict(verdict) {
+    switch (verdict) {
+        case "pending":
+            // A successful read that found the artifact still open. It stamps (paseo
+            // now knows something) and clears the reconcile counter (the source is
+            // reachable again), but writes no signature: there is no event to cite.
+            return {
+                inInbox: true,
+                advancesVerifiedAt: true,
+                writesSignature: false,
+                clearsFailCount: true,
+                incrementsReconcileFailCount: false,
+            };
+        case "handled-elsewhere":
+        case "artifact-gone":
+            // The two closing verdicts. Both stamp and both write the signature that
+            // is the evidence for the close - which is why `assertSafeSignature` runs
+            // before the bind, not after.
+            return {
+                inInbox: false,
+                advancesVerifiedAt: true,
+                writesSignature: true,
+                clearsFailCount: false,
+                incrementsReconcileFailCount: false,
+            };
+        case "unreachable":
+            // Paseo could not look. The row STAYS, nothing is stamped, and the
+            // reconcile counter advances toward the backoff window. This single row of
+            // the table is the whole epic.
+            return {
+                inInbox: true,
+                advancesVerifiedAt: false,
+                writesSignature: false,
+                clearsFailCount: false,
+                incrementsReconcileFailCount: true,
+            };
+    }
+    // No `default`. A fifth verdict fails tsc here rather than rendering as pending.
+    const _exhaustive = verdict;
+    return _exhaustive;
+}
+/**
+ * Does a run carrying this verdict belong in the Inbox?
+ *
+ * `null` - NOBODY HAS LOOKED - is `true`, and that default is the whole reason
+ * this wrapper exists rather than every caller writing
+ * `view.verdict === null || mapVerdict(view.verdict).inInbox` for itself. An
+ * unverified row is an OPEN obligation until a source says otherwise; treating
+ * "no verdict yet" as a close would hide every row on a daemon whose
+ * reconciliation is disabled, whose ledger just migrated, or whose first pass
+ * has not run.
+ */
+export function isInInbox(verdict) {
+    if (verdict === null)
+        return true;
+    return mapVerdict(verdict).inInbox;
+}
+//# sourceMappingURL=verdict-mapping.js.map

package/dist/server/server/ingestion/resolve-items.d.ts

@@ -0,0 +1,23 @@
+import type { SourceStore } from "./sources/store.js";
+import type { StoredFilter } from "@hyperdrive.bot/fleet-protocol/ingestion/filter-types";
+import type { MatchedItem, SourceGateway, SourceKind } from "./types.js";
+export interface ResolveMatchedItemsParams {
+    filter: StoredFilter;
+    sourceStore: SourceStore;
+    gatewayResolver: (kind: SourceKind) => SourceGateway;
+    itemKeys: readonly string[];
+    /** How far back to read. The caller owns the window; this function never guesses one. */
+    windowDays: number;
+    /** Epoch ms. Injected so a resolution is reproducible. */
+    now: () => number;
+}
+/**
+ * Resolve `itemKeys` to items, stopping as soon as every requested key is in hand.
+ *
+ * Keys that do not resolve are simply ABSENT from the result. An item that left
+ * the window, or that no longer matches, is an ordinary consequence of the world
+ * moving between the preview and the apply, and it shows up honestly as a
+ * smaller selection rather than as an exception.
+ */
+export declare function resolveMatchedItems(params: ResolveMatchedItemsParams): Promise<MatchedItem[]>;
+//# sourceMappingURL=resolve-items.d.ts.map

package/dist/server/server/ingestion/resolve-items.js

@@ -0,0 +1,54 @@
+// Item keys back into payload-bearing items, through the same read and the same
+// matcher the preview used.
+//
+// Extracted from `chat-ingestion-session.ts` (Story 5.1) rather than copied,
+// because Story 5.4's restart resume needs the identical resolution and a second
+// implementation is how the manual path and the resumed path quietly start
+// dispatching different item sets for the same group. There is one function; the
+// session delegates to it and so does the resumer.
+import { scanMatchedSourceItems, windowStartFor } from "./backfill.js";
+import { IngestionError } from "./errors.js";
+/**
+ * Resolve `itemKeys` to items, stopping as soon as every requested key is in hand.
+ *
+ * Keys that do not resolve are simply ABSENT from the result. An item that left
+ * the window, or that no longer matches, is an ordinary consequence of the world
+ * moving between the preview and the apply, and it shows up honestly as a
+ * smaller selection rather than as an exception.
+ */
+export async function resolveMatchedItems(params) {
+    const { filter, itemKeys } = params;
+    const source = await params.sourceStore.get(filter.sourceId);
+    if (!source) {
+        throw new IngestionError("SOURCE_MISSING", `Filter ${filter.id} points at source ${filter.sourceId}, which no longer exists.`, 404);
+    }
+    const wanted = new Set(itemKeys);
+    const now = params.now();
+    const { matched } = await scanMatchedSourceItems({
+        filter,
+        gateway: params.gatewayResolver(source.kind),
+        externalUserId: source.externalUserId,
+        accountId: source.externalAccountId ?? "",
+        // A one-method port that answers `null` for everything: resolution is not a
+        // freshness question. Whether an item was already handled is the ledger's
+        // business at CLAIM time, inside `applySelection`, where the compare-and-set
+        // makes the answer race-safe. Asking it here would be a second, staler
+        // answer to the same question.
+        ledger: { get: () => Promise.resolve(null) },
+        sinceMs: windowStartFor(now, params.windowDays),
+        now: () => now,
+        stopWhen: (found) => found.filter((entry) => wanted.has(entry.item.key)).length >= wanted.size,
+    });
+    return matched
+        .filter((entry) => wanted.has(entry.item.key))
+        .map(({ item }) => ({
+        key: item.key,
+        contentHash: item.contentHash,
+        // ISO 8601 UTC, which is what grouping orders on. Derived from the
+        // adapter's timestamp rather than from this daemon's clock, so two
+        // resolutions of the same item order identically.
+        observedAt: new Date(item.timestampMs).toISOString(),
+        payload: item.payload,
+    }));
+}
+//# sourceMappingURL=resolve-items.js.map

package/dist/server/server/ingestion/run-projection.d.ts

@@ -0,0 +1,35 @@
+import type { ScheduleRun } from "@hyperdrive.bot/fleet-protocol/schedule/types";
+import type { IngestionRunView } from "@hyperdrive.bot/fleet-protocol/ingestion/run-view";
+import type { RunViewRow } from "./ledger.js";
+/**
+ * Join runs to ledger rows on `lastRunId`, newest first.
+ *
+ * ORDERING DEPENDENCY, carried here because it is the reason the join works at
+ * all: Story 3.2's `claim()` writes the run id BEFORE dispatch, so by the time a
+ * `ScheduleRun` exists its ledger row already names it. The arrow only ever
+ * points row -> run, never the other way, which is why the row is the index and
+ * the run is the lookup.
+ *
+ * `lastRunId` (ledger schema v4) and NOT `claimRunId`, which is the defect this
+ * projection shipped with. `claim_run_id` names the run holding the claim right
+ * now, so `mark()` nulls it when the agent finishes and `releaseStaleClaims()`
+ * nulls it on the next boot. Joining on it meant the join matched ONLY items
+ * whose dispatch was still in flight in this process - so a handled item, which
+ * is precisely what an Inbox row represents, never matched, and a restart
+ * emptied the list. `last_run_id` carries the same value with no clearing path.
+ *
+ * A run with NO matching ledger row is EXCLUDED rather than emitted with null
+ * verification fields. Such a run is not an ingestion item - it is a clock
+ * schedule's ordinary run that happens to live in the same document - and
+ * emitting it with `verdict: null` would put a row on the Inbox that has no
+ * item behind it and can never be verified. A ledger row whose `lastRunId` is
+ * null is likewise excluded: it was seen but never dispatched, so there is no
+ * run to show.
+ *
+ * Sorted by `startedAt` descending, tie-broken by `id` ascending. The tiebreak
+ * is not decoration: two runs minted in the same millisecond would otherwise
+ * order by whatever `Array.prototype.sort` happened to do, and the test would
+ * be a coin flip.
+ */
+export declare function buildIngestionRunViews(runs: readonly ScheduleRun[], rows: readonly RunViewRow[]): IngestionRunView[];
+//# sourceMappingURL=run-projection.d.ts.map