@hyperdrive.bot/fleet-server 0.3.99

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

@@ -0,0 +1,76 @@
+// "Did somebody move this issue to Done without paseo?"
+//
+// Jira's status names are TENANT-CONFIGURABLE - "Done", "Concluído", "Shipped",
+// "Won't Fix" are all real - so matching on the name is matching on a string the
+// customer chose. The `statusCategory.key` is not configurable: Jira collapses
+// every workflow status onto `new`, `indeterminate` or `done`, and `done` is the
+// only one that means the work stopped needing anyone.
+//
+// So the gate is the CATEGORY, never the name. A reconciler that grepped for
+// "done" in a status name would close a Portuguese board's rows never and an
+// English board's "Done - pending review" wrongly.
+import { callMcpTool } from "./mcp-call.js";
+import { asBoolean, asRecord, asString, metaUrl, pickFirst } from "./payload.js";
+/** ONE round-trip. The issue and its status category. */
+const JIRA_ISSUE_TOOL = "JIRA_GET_ISSUE";
+/** Where the issue body might live, unwrapped path first. */
+const ISSUE_PATHS = ["issue", "data.issue", "data", "response_data"];
+/**
+ * `https://acme.atlassian.net/browse/ABC-123` -> `ABC-123`.
+ *
+ * `/browse/` is the canonical issue URL and the only form accepted. A key is
+ * uppercase letters/digits, a hyphen and a number; anything else is a URL this
+ * reconciler cannot address, which is `unreachable` rather than a guess.
+ */
+export function parseJiraIssueKey(url) {
+    if (url === null)
+        return null;
+    const match = /\/browse\/([A-Z][A-Z0-9_]*-\d+)/i.exec(url);
+    return match?.[1]?.toUpperCase() ?? null;
+}
+/**
+ * Signatures: `jira:done:<key>`, `jira:gone:<key>`.
+ *
+ * The issue key and nothing else. A summary is prose and would be the PII leak
+ * `assertSafeSignature` cannot catch, because a sentence is not credential-shaped.
+ */
+export const jiraReconciler = async (target, ref, signal) => {
+    try {
+        const key = parseJiraIssueKey(metaUrl(ref.meta));
+        if (key === null)
+            return { verdict: "unreachable", signature: null };
+        const payload = await callMcpTool(target, JIRA_ISSUE_TOOL, { issue_key: key }, signal);
+        if (payload === null)
+            return { verdict: "unreachable", signature: null };
+        // A DEFINITE 404 the server reported, not a read that failed to answer.
+        const notFound = asBoolean(pickFirst(payload, ["not_found", "data.not_found", "deleted"]));
+        if (notFound === true) {
+            return { verdict: "artifact-gone", signature: `jira:gone:${key}` };
+        }
+        const issue = asRecord(pickFirst(payload, [...ISSUE_PATHS]));
+        if (!issue)
+            return { verdict: "unreachable", signature: null };
+        const category = asString(pickFirst(issue, [
+            "fields.status.statusCategory.key",
+            "fields.status.status_category.key",
+            "status.statusCategory.key",
+            "statusCategory.key",
+            "status_category",
+        ]))?.toLowerCase();
+        // No category means the payload never told us where the issue stands. Not
+        // "it is still open" and certainly not "it is done".
+        if (!category)
+            return { verdict: "unreachable", signature: null };
+        if (category === "done") {
+            return { verdict: "handled-elsewhere", signature: `jira:done:${key}` };
+        }
+        if (category === "new" || category === "indeterminate" || category === "undefined") {
+            return { verdict: "pending", signature: null };
+        }
+        return { verdict: "unreachable", signature: null };
+    }
+    catch {
+        return { verdict: "unreachable", signature: null };
+    }
+};
+//# sourceMappingURL=jira.js.map

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

@@ -0,0 +1,16 @@
+/**
+ * The artifact kinds paseo can re-read at the source.
+ *
+ * THE ONE list on this axis. `registry.ts` keys `RECONCILERS` off it with
+ * `satisfies`, so a member added here without a reconciler fails `tsc`;
+ * `registry.test.ts` iterates it at runtime, so an extra reconciler key fails
+ * the suite. `artifact-kind.ts` maps opaque app slugs onto it and is the only
+ * file allowed to do so.
+ *
+ * `calendar` rather than `googlecalendar`: the kind is the artifact ("a calendar
+ * event ended"), not the vendor slug that happened to deliver it. The slug ->
+ * kind bridge, including every Google spelling, lives in `artifact-kind.ts`.
+ */
+export declare const RECONCILABLE_ARTIFACT_KINDS: readonly ["gmail", "gitlab", "github", "jira", "sentry", "calendar"];
+export type ReconcilableArtifactKind = (typeof RECONCILABLE_ARTIFACT_KINDS)[number];
+//# sourceMappingURL=kinds.d.ts.map

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

@@ -0,0 +1,59 @@
+// THE ARTIFACT AXIS. What was handled, never who we asked.
+//
+// Decision D-6.2-A, stated here rather than in a story file because the
+// correction has to survive being read out of context:
+//
+// The epic's Story 6.2 text says to key `RECONCILERS` off Epic 1's single
+// aggregator-kinds constant, and in the same sentence lists the reconciler files
+// as gmail / gitlab / github / jira / sentry / calendar. Those two halves cannot
+// both be true. That constant (declared in `../types.ts:18`, and deliberately
+// not named here - see the note at the foot of this comment) is
+// `["pipedream", "composio"]` - AGGREGATOR kinds - so keying a `Record` off it would
+// produce exactly two reconcilers, a `pipedreamReconciler` and a
+// `composioReconciler`, which is precisely what the epic's own D3 forbids:
+// "reconciliation is per source kind, not per aggregator. Whether an artifact
+// was handled is a Gmail question or a GitLab question; it is not a Pipedream
+// question."
+//
+// So D3 is the intent and the constant name in that sentence is the error.
+// There are TWO closed lists on TWO different axes, and neither derives from
+// the other:
+//
+//   `../types.ts`'s aggregator list      who paseo asks
+//   RECONCILABLE_ARTIFACT_KINDS          what was handled
+//
+// Widening either to cover the other is the mistake this comment exists to
+// prevent. A third aggregator does not add a reconciler; a seventh artifact
+// kind does not add an aggregator. Both lists are closed, both are iterated by
+// a test, and both fail the build when a member arrives without its partner.
+//
+// The aggregator constant is referred to BY FILE rather than by name anywhere
+// under `reconcile/`, and that is a deliberate, greppable invariant rather than
+// coyness: AC 2 greps this directory for that identifier and requires ZERO
+// lines back, so that the empty grep proves nothing here reaches for the wrong
+// axis. A mention in a comment - including in this one - would put a line in
+// that output that reads exactly like the mistake, which is why even the
+// sentence describing the rule does not spell the name. The cross-axis property
+// is asserted in `../axes.test.ts`, the one file allowed to import both.
+/**
+ * The artifact kinds paseo can re-read at the source.
+ *
+ * THE ONE list on this axis. `registry.ts` keys `RECONCILERS` off it with
+ * `satisfies`, so a member added here without a reconciler fails `tsc`;
+ * `registry.test.ts` iterates it at runtime, so an extra reconciler key fails
+ * the suite. `artifact-kind.ts` maps opaque app slugs onto it and is the only
+ * file allowed to do so.
+ *
+ * `calendar` rather than `googlecalendar`: the kind is the artifact ("a calendar
+ * event ended"), not the vendor slug that happened to deliver it. The slug ->
+ * kind bridge, including every Google spelling, lives in `artifact-kind.ts`.
+ */
+export const RECONCILABLE_ARTIFACT_KINDS = [
+    "gmail",
+    "gitlab",
+    "github",
+    "jira",
+    "sentry",
+    "calendar",
+];
+//# sourceMappingURL=kinds.js.map

package/dist/server/server/ingestion/reconcile/mcp-call.d.ts

@@ -0,0 +1,18 @@
+import type { McpTarget } from "../types.js";
+/**
+ * Call one tool on one MCP endpoint and hand back its payload, or `null`.
+ *
+ * `null` covers, on purpose and without distinction: a transport-level network
+ * error, any non-2xx status, a rejected handshake, an aborted signal, an
+ * `isError: true` tool result, a body that is not JSON, and a body that is JSON
+ * but carries no readable content. Every one of them means the same thing to a
+ * reconciler.
+ *
+ * The `signal` is honoured AND the transport is closed in a `finally`, so an
+ * abort mid-flight releases the socket rather than leaving it to the GC. The
+ * service races this against its own timeout regardless
+ * (`ReconciliationService.readOne`), because "honours AbortSignal" is not a
+ * property this function can promise on behalf of a remote server.
+ */
+export declare function callMcpTool(target: McpTarget, toolName: string, args: Record<string, unknown>, signal: AbortSignal): Promise<unknown | null>;
+//# sourceMappingURL=mcp-call.d.ts.map

package/dist/server/server/ingestion/reconcile/mcp-call.js

@@ -0,0 +1,105 @@
+// ONE MCP round-trip, and every way it can fail collapses to `null`.
+//
+// Six reconcilers need the same six lines - construct a transport, connect, call
+// one tool, close in a `finally` - and six copies of those lines are six chances
+// for one of them to leak a `throw` into `Promise.allSettled`, where a thrown
+// reconciler is indistinguishable from a rejected sibling. So the round-trip
+// lives here once and its contract is total: it returns the tool's payload, or
+// it returns `null`. It never throws and it never returns a partial answer.
+//
+// `null` means "this read told you nothing" and the caller's only correct
+// response is `unreachable`. It deliberately does NOT distinguish a 401 from a
+// 500 from a timeout from a malformed body, because the caller must treat all
+// four identically: an absence is not evidence the artifact is gone
+// (`archive-if-safe.ts:78-82` has been shipping exactly this for merged PRs).
+//
+// Nothing here logs. The target carries a live bearer token and the tool
+// arguments carry a native artifact id; a log line at this depth is how both end
+// up in a file that outlives the request. `ReconciliationService.readOne` logs
+// the failure with `{ appSlug, sourceId, itemKey }` and nothing else.
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+/** Identifies paseo to the MCP endpoint. Carries no user, host or workspace identity. */
+const CLIENT_INFO = { name: "paseo-reconcile", version: "1.0.0" };
+/**
+ * Call one tool on one MCP endpoint and hand back its payload, or `null`.
+ *
+ * `null` covers, on purpose and without distinction: a transport-level network
+ * error, any non-2xx status, a rejected handshake, an aborted signal, an
+ * `isError: true` tool result, a body that is not JSON, and a body that is JSON
+ * but carries no readable content. Every one of them means the same thing to a
+ * reconciler.
+ *
+ * The `signal` is honoured AND the transport is closed in a `finally`, so an
+ * abort mid-flight releases the socket rather than leaving it to the GC. The
+ * service races this against its own timeout regardless
+ * (`ReconciliationService.readOne`), because "honours AbortSignal" is not a
+ * property this function can promise on behalf of a remote server.
+ */
+export async function callMcpTool(target, toolName, args, signal) {
+    let client = null;
+    try {
+        if (signal.aborted)
+            return null;
+        const transport = new StreamableHTTPClientTransport(new URL(target.url), {
+            requestInit: { headers: target.headers },
+        });
+        client = new Client(CLIENT_INFO);
+        await client.connect(transport, { signal });
+        const result = await client.callTool({ name: toolName, arguments: args }, undefined, {
+            signal,
+        });
+        // An MCP tool reports its own failures in-band rather than by rejecting, so
+        // this branch is a real failure path and not defensive padding.
+        if (result.isError === true)
+            return null;
+        return extractPayload(result);
+    }
+    catch {
+        // Swallowed on purpose, and the swallow is the contract rather than
+        // laziness: an exception escaping a reconciler lands in the service's
+        // `Promise.allSettled` and reads as a rejected sibling, which is exactly the
+        // ambiguity this epic exists to remove. The caller turns `null` into
+        // `unreachable`, which can never close a row.
+        return null;
+    }
+    finally {
+        // `close()` can itself reject on an already-broken transport. Losing the
+        // socket is not worth losing the verdict.
+        await client?.close().catch(() => undefined);
+    }
+}
+/**
+ * The tool's payload, from whichever of the three places the SDK put it.
+ *
+ * `structuredContent` first because it is already an object; then a single
+ * `text` content block parsed as JSON, which is what most aggregator MCP servers
+ * actually emit. Anything else - an image block, an empty content array, a text
+ * block that is not JSON - is `null`, because a payload this function cannot
+ * read is a payload the reconciler must not guess at.
+ */
+function extractPayload(result) {
+    if (typeof result !== "object" || result === null)
+        return null;
+    const record = result;
+    const structured = record.structuredContent;
+    if (typeof structured === "object" && structured !== null)
+        return structured;
+    const content = record.content;
+    if (!Array.isArray(content) || content.length === 0)
+        return null;
+    const first = content[0];
+    if (typeof first !== "object" || first === null)
+        return null;
+    const block = first;
+    if (typeof block.text !== "string")
+        return null;
+    try {
+        return JSON.parse(block.text);
+    }
+    catch {
+        // Valid MCP envelope, unreadable body. Still nothing learned.
+        return null;
+    }
+}
+//# sourceMappingURL=mcp-call.js.map

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

@@ -0,0 +1,38 @@
+export declare function asRecord(value: unknown): Record<string, unknown> | null;
+export declare function asArray(value: unknown): unknown[] | null;
+/** A non-empty trimmed string, or null. An empty string is an absent field, not a value. */
+export declare function asString(value: unknown): string | null;
+export declare function asBoolean(value: unknown): boolean | null;
+/** A finite number, or null. `NaN` and `Infinity` are unreadable, not values. */
+export declare function asNumber(value: unknown): number | null;
+/**
+ * Walk a dotted path through nested records.
+ *
+ * Aggregators wrap their payloads differently - Composio nests the vendor body
+ * under `data`, Pipedream sometimes does not - so every reconciler reads its
+ * field through a small list of candidate paths rather than one. That keeps the
+ * "unwrap the envelope" logic out of six files and, more importantly, keeps it
+ * from being written as "try the field, else try `data.field`, else give up" in
+ * six subtly different ways.
+ */
+export declare function pick(source: unknown, path: string): unknown;
+/**
+ * The first candidate path that resolves to something, or `undefined`.
+ *
+ * Order matters and the caller owns it: the unwrapped path goes first so a body
+ * that carries the field directly is never shadowed by a same-named field on an
+ * envelope.
+ */
+export declare function pickFirst(source: unknown, paths: readonly string[]): unknown;
+/**
+ * The artifact's own URL from the ledger's `meta`, or null.
+ *
+ * `meta.url` is the ONLY native-id carrier a reconciler is allowed to read.
+ * `SourceItemRef.itemKey` cannot serve: it is a `fingerprint()` digest
+ * (`../fingerprint.ts`), deliberately not the vendor's id, so parsing it would
+ * yield twelve hex characters and nothing else. `subject` is the other field
+ * that looks useful and is forbidden for the opposite reason - it is the user's
+ * prose, and prose must never reach a signature.
+ */
+export declare function metaUrl(meta: Record<string, unknown>): string | null;
+//# sourceMappingURL=payload.d.ts.map

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

@@ -0,0 +1,82 @@
+// Narrowing an OPAQUE aggregator body, without an `as any` anywhere.
+//
+// A reconciler receives `unknown` from `callMcpTool` and must not assume a
+// shape: the body is whatever a third-party MCP server chose to emit today.
+// `.oxlintrc.json` runs `typescript/no-explicit-any` at error precisely so the
+// tempting shortcut is unavailable, and these five helpers are what replaces it.
+//
+// Every one of them returns `null` rather than throwing or coercing. That is the
+// same rule as `mcp-call.ts` one layer up: a field the reconciler could not read
+// is a field it must not guess at, and a `null` here becomes an `unreachable`
+// verdict rather than a close built on a coerced empty string.
+export function asRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    return value;
+}
+export function asArray(value) {
+    return Array.isArray(value) ? value : null;
+}
+/** A non-empty trimmed string, or null. An empty string is an absent field, not a value. */
+export function asString(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? null : trimmed;
+}
+export function asBoolean(value) {
+    return typeof value === "boolean" ? value : null;
+}
+/** A finite number, or null. `NaN` and `Infinity` are unreadable, not values. */
+export function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * Walk a dotted path through nested records.
+ *
+ * Aggregators wrap their payloads differently - Composio nests the vendor body
+ * under `data`, Pipedream sometimes does not - so every reconciler reads its
+ * field through a small list of candidate paths rather than one. That keeps the
+ * "unwrap the envelope" logic out of six files and, more importantly, keeps it
+ * from being written as "try the field, else try `data.field`, else give up" in
+ * six subtly different ways.
+ */
+export function pick(source, path) {
+    let cursor = source;
+    for (const segment of path.split(".")) {
+        const record = asRecord(cursor);
+        if (!record)
+            return undefined;
+        cursor = record[segment];
+    }
+    return cursor;
+}
+/**
+ * The first candidate path that resolves to something, or `undefined`.
+ *
+ * Order matters and the caller owns it: the unwrapped path goes first so a body
+ * that carries the field directly is never shadowed by a same-named field on an
+ * envelope.
+ */
+export function pickFirst(source, paths) {
+    for (const path of paths) {
+        const value = pick(source, path);
+        if (value !== undefined && value !== null)
+            return value;
+    }
+    return undefined;
+}
+/**
+ * The artifact's own URL from the ledger's `meta`, or null.
+ *
+ * `meta.url` is the ONLY native-id carrier a reconciler is allowed to read.
+ * `SourceItemRef.itemKey` cannot serve: it is a `fingerprint()` digest
+ * (`../fingerprint.ts`), deliberately not the vendor's id, so parsing it would
+ * yield twelve hex characters and nothing else. `subject` is the other field
+ * that looks useful and is forbidden for the opposite reason - it is the user's
+ * prose, and prose must never reach a signature.
+ */
+export function metaUrl(meta) {
+    return asString(meta.url);
+}
+//# sourceMappingURL=payload.js.map

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

@@ -0,0 +1,40 @@
+import type { Reconciler } from "./types.js";
+/**
+ * One reconciler per artifact kind. A missing entry is a COMPILE error.
+ *
+ * `satisfies Record<ReconcilableArtifactKind, Reconciler>` is what makes that
+ * true, and the choice is load-bearing rather than stylistic: an `as const`
+ * array plus a `switch` compiles perfectly well with a missing case, so the gap
+ * would only surface at runtime as an item that silently never gets verified.
+ * The `satisfies` turns the same gap into `tsc` output while keeping the literal
+ * key type, so `RECONCILERS` cannot be indexed with an arbitrary string either.
+ *
+ * `registry.test.ts` iterates `RECONCILABLE_ARTIFACT_KINDS` at runtime as well,
+ * because `satisfies` catches a MISSING key and the test catches an EXTRA one.
+ */
+export declare const RECONCILERS: {
+    readonly gmail: Reconciler;
+    readonly gitlab: Reconciler;
+    readonly github: Reconciler;
+    readonly jira: Reconciler;
+    readonly sentry: Reconciler;
+    readonly calendar: Reconciler;
+};
+/**
+ * The reconciler for an OPEN-WORLD app slug, or null when paseo has none.
+ *
+ * Two steps, and the first one is where the open world ends: `resolveArtifactKind`
+ * turns an arbitrary catalogue string into a closed-set member or `null`, so this
+ * function never indexes `RECONCILERS` with anything the type system has not
+ * already vouched for. `"__proto__"`, `"constructor"` and `"toString"` all die at
+ * the bridge rather than resolving to an inherited member of `Object.prototype`
+ * and being handed to the service as a "reconciler".
+ *
+ * `null` does NOT mean `unreachable`. See D-6.1-B: `verifyIfStale` skips such a
+ * candidate entirely rather than marking it unreachable, because "paseo has no
+ * reconciler for this app" is PERMANENT while `unreachable` is the transient
+ * verdict that feeds a retry counter and a backoff. Marking it unreachable would
+ * burn a retry budget on a network condition that never happened.
+ */
+export declare function resolveReconciler(appSlug: string): Reconciler | null;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1,72 @@
+// THE CLOSED SET, keyed on the ARTIFACT axis.
+//
+// Story 6.1 shipped this keyed on `RECONCILABLE_APP_SLUGS`, a list that mixed
+// the two axes into one: `googlecalendar` is a vendor slug, `github` is both a
+// slug and an artifact kind, and the coincidence hid the fact that they are
+// different things. Story 6.2 splits them (decision D-6.2-A):
+//
+//   kinds.ts          the ARTIFACT axis  - what was handled
+//   artifact-kind.ts  the BRIDGE         - one opaque app slug -> one kind
+//   registry.ts       the REGISTRY       - one kind -> one reconciler
+//
+// Splitting them is what lets three vendor spellings of Google Calendar share
+// one reconciler without three registry entries, and what stops a seventh
+// aggregator from implying a seventh reconciler.
+//
+// Epic 1's aggregator-kinds constant (`../types.ts:18`) is not read, not
+// imported and not modified by anything in this directory. It is the AGGREGATOR
+// axis and lives on the other side of a wall this comment is part of - which is
+// why it is named by file rather than by identifier: the invariant is a grep
+// that must come back empty, and a comment mentioning it would spoil the grep.
+// See `kinds.ts` for the full statement of D-6.2-A.
+import { calendarReconciler } from "./calendar.js";
+import { githubReconciler } from "./github.js";
+import { gitlabReconciler } from "./gitlab.js";
+import { gmailReconciler } from "./gmail.js";
+import { jiraReconciler } from "./jira.js";
+import { resolveArtifactKind } from "./artifact-kind.js";
+import { sentryReconciler } from "./sentry.js";
+/**
+ * One reconciler per artifact kind. A missing entry is a COMPILE error.
+ *
+ * `satisfies Record<ReconcilableArtifactKind, Reconciler>` is what makes that
+ * true, and the choice is load-bearing rather than stylistic: an `as const`
+ * array plus a `switch` compiles perfectly well with a missing case, so the gap
+ * would only surface at runtime as an item that silently never gets verified.
+ * The `satisfies` turns the same gap into `tsc` output while keeping the literal
+ * key type, so `RECONCILERS` cannot be indexed with an arbitrary string either.
+ *
+ * `registry.test.ts` iterates `RECONCILABLE_ARTIFACT_KINDS` at runtime as well,
+ * because `satisfies` catches a MISSING key and the test catches an EXTRA one.
+ */
+export const RECONCILERS = {
+    gmail: gmailReconciler,
+    gitlab: gitlabReconciler,
+    github: githubReconciler,
+    jira: jiraReconciler,
+    sentry: sentryReconciler,
+    calendar: calendarReconciler,
+};
+/**
+ * The reconciler for an OPEN-WORLD app slug, or null when paseo has none.
+ *
+ * Two steps, and the first one is where the open world ends: `resolveArtifactKind`
+ * turns an arbitrary catalogue string into a closed-set member or `null`, so this
+ * function never indexes `RECONCILERS` with anything the type system has not
+ * already vouched for. `"__proto__"`, `"constructor"` and `"toString"` all die at
+ * the bridge rather than resolving to an inherited member of `Object.prototype`
+ * and being handed to the service as a "reconciler".
+ *
+ * `null` does NOT mean `unreachable`. See D-6.1-B: `verifyIfStale` skips such a
+ * candidate entirely rather than marking it unreachable, because "paseo has no
+ * reconciler for this app" is PERMANENT while `unreachable` is the transient
+ * verdict that feeds a retry counter and a backoff. Marking it unreachable would
+ * burn a retry budget on a network condition that never happened.
+ */
+export function resolveReconciler(appSlug) {
+    const kind = resolveArtifactKind(appSlug);
+    if (kind === null)
+        return null;
+    return RECONCILERS[kind];
+}
+//# sourceMappingURL=registry.js.map

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

@@ -0,0 +1,43 @@
+import type pino from "pino";
+import type { IngestionRunView } from "@hyperdrive.bot/fleet-protocol/ingestion/run-view";
+import type { StoredFilter } from "@hyperdrive.bot/fleet-protocol/ingestion/filter-types";
+import type { ReconciliationService } from "./service.js";
+/** The one method `ChatIngestionSession` needs. A port, so a test needs no service. */
+export interface ReconciliationPort {
+    verify(filterId: string, views: readonly IngestionRunView[]): Promise<void>;
+}
+/** The one filter-store method this needs. Read-only by shape. */
+export interface FilterReader {
+    get(id: string): Promise<StoredFilter | null>;
+}
+/** The one ledger method this needs beyond what the handler already read. */
+export interface ItemMetaReader {
+    get(filterId: string, itemKey: string): {
+        meta: string | null;
+    } | undefined;
+}
+export interface IngestionReconciliationRunnerOptions {
+    filters: FilterReader;
+    ledger: ItemMetaReader;
+    service: Pick<ReconciliationService, "verifyIfStale">;
+    logger: pino.Logger;
+}
+export declare class IngestionReconciliationRunner implements ReconciliationPort {
+    private readonly filters;
+    private readonly ledger;
+    private readonly service;
+    private readonly logger;
+    constructor(options: IngestionReconciliationRunnerOptions);
+    /**
+     * Turn one filter's rendered views into candidates and hand them to the
+     * service.
+     *
+     * A filter that no longer exists, or one whose match carries no `appSlug`,
+     * produces zero candidates and issues zero reads. Both are ordinary states -
+     * a filter can be deleted between the render and this call - and neither is
+     * worth a verdict, because "the filter is gone" says nothing about whether the
+     * artifact was handled.
+     */
+    verify(filterId: string, views: readonly IngestionRunView[]): Promise<void>;
+}
+//# sourceMappingURL=runner.d.ts.map

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

@@ -0,0 +1,91 @@
+// FROM A RENDERED VIEW BACK TO A READABLE CANDIDATE.
+//
+// `ReconciliationService` takes `ReconcileCandidate`s - filter, item, app slug,
+// source, and the item's `meta`. The `ingestion/runs` handler has
+// `IngestionRunView`s, which carry `itemKey` and nothing else about where the
+// item came from. Something has to bridge them, and this is it.
+//
+// It is a separate file rather than three more methods on `ChatIngestionSession`
+// because of what it has to hold: the filter store, the ledger AND the service.
+// Putting that on the session would give a class whose safety argument is "it
+// holds no write path" three more collaborators to be audited against, and the
+// bridge itself is pure lookup that deserves its own test.
+//
+// The whole class is best-effort. Every method that can fail returns early
+// rather than throwing, because its one caller has ALREADY emitted a response:
+// a throw here would surface as an unhandled rejection attached to a request the
+// client was told succeeded.
+/**
+ * The item's stored `meta`, parsed, or an empty object.
+ *
+ * `meta` is a TEXT column holding JSON the ledger itself wrote through its
+ * five-key allow-list, so it should always parse - but "should always" is not a
+ * reason to let a hand-edited row take down a background pass. An unparseable
+ * value yields `{}`, which makes every reconciler return `unreachable` (no URL,
+ * no read), which leaves the row standing. The safe direction, again.
+ */
+function parseMeta(raw) {
+    if (raw === null)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+export class IngestionReconciliationRunner {
+    constructor(options) {
+        this.filters = options.filters;
+        this.ledger = options.ledger;
+        this.service = options.service;
+        this.logger = options.logger;
+    }
+    /**
+     * Turn one filter's rendered views into candidates and hand them to the
+     * service.
+     *
+     * A filter that no longer exists, or one whose match carries no `appSlug`,
+     * produces zero candidates and issues zero reads. Both are ordinary states -
+     * a filter can be deleted between the render and this call - and neither is
+     * worth a verdict, because "the filter is gone" says nothing about whether the
+     * artifact was handled.
+     */
+    async verify(filterId, views) {
+        if (views.length === 0)
+            return;
+        const filter = await this.filters.get(filterId);
+        if (!filter)
+            return;
+        const appSlug = filter.match.appSlug;
+        // `appSlug` is an opaque runtime string; the registry decides whether paseo
+        // can read it, and it decides that inside the service (gate 2), not here.
+        // Pre-filtering here would duplicate that judgement in a second place.
+        if (typeof appSlug !== "string" || appSlug.trim().length === 0)
+            return;
+        const candidates = [];
+        for (const view of views) {
+            const entry = this.ledger.get(filterId, view.itemKey);
+            candidates.push({
+                filterId,
+                itemKey: view.itemKey,
+                appSlug,
+                sourceId: filter.sourceId,
+                ref: { itemKey: view.itemKey, meta: parseMeta(entry?.meta ?? null) },
+            });
+        }
+        const outcomes = await this.service.verifyIfStale(candidates);
+        const read = [...outcomes.values()].filter((outcome) => outcome.read).length;
+        if (read > 0) {
+            // Debug rather than info: this fires on every Inbox poll whose stamps went
+            // stale, which on an open Inbox is every minute. The per-slug LATENCY
+            // snapshot is the line worth reading, and the service emits that one on
+            // its own interval.
+            this.logger.debug({ filterId, appSlug, candidates: candidates.length, read }, "Ingestion reconcile pass complete");
+        }
+    }
+}
+//# sourceMappingURL=runner.js.map