@hyperdrive.bot/fleet-server 0.3.99

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

@@ -0,0 +1,20 @@
+import type { Reconciler } from "./types.js";
+/**
+ * `https://sentry.io/organizations/acme/issues/4567/` -> `4567`.
+ *
+ * Both the `/organizations/<org>/issues/<id>` and the newer
+ * `/issues/<id>` shapes carry the numeric id in the same position, so one
+ * pattern covers both. A short id (`ACME-1AB`) appearing in the URL instead is
+ * accepted too: it is what the API echoes back and what the signature prefers.
+ */
+export declare function parseSentryIssueId(url: string | null): string | null;
+/**
+ * Signatures: `sentry:resolved:<shortId>`, `sentry:ignored:<shortId>`,
+ * `sentry:gone:<shortId>`.
+ *
+ * The short id is Sentry's own human-readable handle (`ACME-1AB`). The error
+ * message and the culprit stay out: a stack frame is a file path from somebody's
+ * machine.
+ */
+export declare const sentryReconciler: Reconciler;
+//# sourceMappingURL=sentry.d.ts.map

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

@@ -0,0 +1,85 @@
+// "Did somebody resolve or ignore this issue without paseo?"
+//
+// Sentry has a fourth state the other five apps do not: an issue can be MERGED
+// into another issue, at which point its own id still resolves but its status is
+// no longer about itself. That is `artifact-gone` rather than
+// `handled-elsewhere`, because nobody handled this issue - it stopped existing
+// as a separate obligation.
+//
+// `ignored` closes alongside `resolved`, and that is a deliberate product call
+// rather than an oversight: an ignored issue is one a human looked at and
+// decided not to act on, which is the same "this no longer needs you" that the
+// Inbox exists to respect. `unresolved` is the only status that keeps the row.
+import { callMcpTool } from "./mcp-call.js";
+import { asBoolean, asRecord, asString, metaUrl, pickFirst } from "./payload.js";
+/** ONE round-trip. The issue, its status and its short id. */
+const SENTRY_ISSUE_TOOL = "SENTRY_GET_ISSUE";
+/** Where the issue body might live, unwrapped path first. */
+const ISSUE_PATHS = ["issue", "data.issue", "data", "response_data"];
+/**
+ * `https://sentry.io/organizations/acme/issues/4567/` -> `4567`.
+ *
+ * Both the `/organizations/<org>/issues/<id>` and the newer
+ * `/issues/<id>` shapes carry the numeric id in the same position, so one
+ * pattern covers both. A short id (`ACME-1AB`) appearing in the URL instead is
+ * accepted too: it is what the API echoes back and what the signature prefers.
+ */
+export function parseSentryIssueId(url) {
+    if (url === null)
+        return null;
+    const match = /\/issues\/([A-Za-z0-9_-]+)/.exec(url);
+    return match?.[1] ?? null;
+}
+/**
+ * Signatures: `sentry:resolved:<shortId>`, `sentry:ignored:<shortId>`,
+ * `sentry:gone:<shortId>`.
+ *
+ * The short id is Sentry's own human-readable handle (`ACME-1AB`). The error
+ * message and the culprit stay out: a stack frame is a file path from somebody's
+ * machine.
+ */
+export const sentryReconciler = async (target, ref, signal) => {
+    try {
+        const issueId = parseSentryIssueId(metaUrl(ref.meta));
+        if (issueId === null)
+            return { verdict: "unreachable", signature: null };
+        const payload = await callMcpTool(target, SENTRY_ISSUE_TOOL, { issue_id: issueId }, 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: `sentry:gone:${issueId}` };
+        }
+        const issue = asRecord(pickFirst(payload, [...ISSUE_PATHS]));
+        if (!issue)
+            return { verdict: "unreachable", signature: null };
+        // Prefer the short id the API returns; fall back to the id off the URL so a
+        // payload without one still produces a citable signature.
+        const shortId = asString(pickFirst(issue, ["shortId", "short_id"])) ?? issueId;
+        // MERGED AWAY: the id resolves but the obligation moved. Checked before the
+        // status, because a merged issue inherits the parent's status and reading it
+        // would attribute the parent's resolution to this row.
+        const mergedInto = asString(pickFirst(issue, ["mergedInto", "merged_into", "parent_id"]));
+        if (mergedInto !== null) {
+            return { verdict: "artifact-gone", signature: `sentry:gone:${shortId}` };
+        }
+        const status = asString(pickFirst(issue, ["status", "state"]))?.toLowerCase() ?? null;
+        if (status === null)
+            return { verdict: "unreachable", signature: null };
+        if (status === "resolved") {
+            return { verdict: "handled-elsewhere", signature: `sentry:resolved:${shortId}` };
+        }
+        if (status === "ignored" || status === "muted" || status === "archived") {
+            return { verdict: "handled-elsewhere", signature: `sentry:ignored:${shortId}` };
+        }
+        if (status === "unresolved") {
+            return { verdict: "pending", signature: null };
+        }
+        return { verdict: "unreachable", signature: null };
+    }
+    catch {
+        return { verdict: "unreachable", signature: null };
+    }
+};
+//# sourceMappingURL=sentry.js.map

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

@@ -0,0 +1,134 @@
+import type pino from "pino";
+import type { IngestionLedger } from "../ledger.js";
+import { resolveReconciler as defaultResolveReconciler } from "./registry.js";
+import type { ReconcileCandidate, ReconcileOutcome, ResolveMcpTarget } from "./types.js";
+/** The subset of daemon config this service reads. Structural, so a test needs no store. */
+export interface ReconcileConfigReader {
+    get(): {
+        ingestionReconcileEnabled?: boolean;
+        ingestionReconcileStaleMs?: number;
+    };
+}
+export interface ReconciliationServiceOptions {
+    ledger: IngestionLedger;
+    resolveMcpTarget: ResolveMcpTarget;
+    daemonConfigStore: ReconcileConfigReader;
+    logger: pino.Logger;
+    /** Mirrors `ScheduleService.now` (`service.ts:213`) so no test reads the wall clock. */
+    now?: () => Date;
+    /** Injectable so a test registers a fake without mutating the module-level `RECONCILERS`. */
+    resolveReconciler?: typeof defaultResolveReconciler;
+}
+export interface ReadLatencySnapshot {
+    count: number;
+    p50: number;
+    p95: number;
+    max: number;
+}
+export declare class ReconciliationService {
+    private readonly ledger;
+    private readonly resolveMcpTarget;
+    private readonly daemonConfigStore;
+    private readonly logger;
+    private readonly now;
+    private readonly resolveReconciler;
+    /**
+     * In-flight reads, keyed `${filterId}:${itemKey}`.
+     *
+     * A `Map`, not a `Set`, and the difference is the whole point: the `Set` in
+     * `setupAutoArchiveOnMerge` can afford to SKIP a duplicate because its work
+     * has no return value, whereas a second caller here needs the first caller's
+     * verdict. Storing the promise lets the loser await the winner's outcome
+     * instead of getting a hole in its result map.
+     */
+    private readonly inFlight;
+    /** Slugs already complained about, so an unknown app is loud once per process. */
+    private readonly warnedSlugs;
+    /** Per-slug read round-trips in ms, bounded at `LATENCY_RING_SIZE`. */
+    private readonly latency;
+    private lastTelemetryAt;
+    constructor(options: ReconciliationServiceOptions);
+    /**
+     * Verify every candidate whose stamp is stale, and return an outcome for
+     * EVERY candidate - including the ones that were skipped.
+     *
+     * The returned map is total over the input on purpose. A caller that got a
+     * partial map would have to decide what a missing key meant, and the two
+     * plausible readings ("not stale" and "the read blew up") are exactly the two
+     * this epic exists to keep apart.
+     */
+    verifyIfStale(candidates: readonly ReconcileCandidate[]): Promise<Map<string, ReconcileOutcome>>;
+    /**
+     * Per-app read latency, for re-picking `RECONCILE_STALE_MS` and
+     * `RECONCILE_TIMEOUT_MS` off real data rather than off the guesses those
+     * constants currently hold.
+     */
+    snapshotReadLatency(): Record<string, ReadLatencySnapshot>;
+    /**
+     * A misconfigured tunable falls back to the default rather than failing.
+     *
+     * The daemon must start even when reconciliation is misconfigured (epic
+     * Compatibility Requirement), and a zero or negative staleness window would
+     * make every candidate stale on every call - a read storm dressed as a
+     * config value.
+     */
+    private resolveStaleMs;
+    /**
+     * Group by `sourceId`, then run ALL groups through ONE worker pool.
+     *
+     * The grouping is about isolation (NFR7): each group is awaited with
+     * `Promise.allSettled`, so a source that throws synchronously on every read
+     * cannot reject the settlement of a healthy source's group. The pool is about
+     * load: it is global to the call rather than per group, because four groups
+     * each capped at four would be sixteen concurrent reads against aggregators
+     * that rate-limit.
+     */
+    private runGroupedBySource;
+    /**
+     * One candidate, through the single-flight map so a concurrent caller shares
+     * this exact promise rather than issuing a second read.
+     */
+    private verifyOne;
+    private readAndRecord;
+    /**
+     * THE D4 BOUNDARY. Every path out of this function that is not a real answer
+     * from a reconciler returns `unreachable`.
+     *
+     * There are four such paths and all four are covered: `resolveMcpTarget`
+     * rejects, the reconciler throws synchronously, the reconciler rejects, the
+     * reconciler never settles. None of them can produce a closing verdict, which
+     * is why this story ships with a STRUCTURAL zero-false-close property rather
+     * than merely an untested one.
+     */
+    private readOne;
+    /**
+     * A reconciler returned something the ledger must never store.
+     *
+     * The guard also lives at the ledger's write boundary, where it THROWS - that
+     * is the last line of defence for any caller. Here, one layer up, the throw is
+     * converted into `unreachable` for two reasons that both point the same way:
+     * the outcome map must stay total, and one carelessly written reconciler must
+     * not be able to blank the results of every healthy source in the same batch
+     * (NFR7).
+     *
+     * Logged at ERROR with its own message, not at `warn` alongside network
+     * failures. This is a DEFECT IN PASEO'S OWN CODE, not a source being
+     * unavailable, and burying it among transient read failures is how it would
+     * survive to the next release. The offending value is never logged.
+     */
+    private guardSignature;
+    private recordLatency;
+    private maybeEmitTelemetry;
+    /**
+     * Loud ONCE per slug per process.
+     *
+     * "Enumerate what you silence" applied to the open-world edge of a closed
+     * registry: an unknown app slug is the one case this design cannot decide
+     * statically, so it is never dropped - but a filter with 400 items would
+     * otherwise emit 400 identical lines per pass and become its own noise floor.
+     */
+    private warnUnknownSlugOnce;
+    private storedOutcome;
+    private outcomeFrom;
+}
+//# sourceMappingURL=service.d.ts.map

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

@@ -0,0 +1,409 @@
+// RE-READ THE SOURCE, and never let the re-read hurt anything.
+//
+// The whole design pressure on this file is one sentence from the epic: a row's
+// pending-ness must be derived from the source payload, not from what the
+// pipeline recorded about its own attempt. That means issuing real network reads
+// from something an Inbox will eventually call - so every gate here exists to
+// make that safe:
+//
+//   kill switch    -> the feature can be turned off without a deploy
+//   registry gate  -> an unknown app is skipped, loudly, not marked failed
+//   backoff gate   -> a source down three reads running is left alone for 15min
+//   staleness gate -> a fresh stamp costs zero reads
+//   single-flight  -> two callers for one item issue one read and share it
+//   timeout race   -> a reconciler that hangs cannot hang the pool
+//   concurrency    -> at most four reads in flight per call, globally
+//   per-source     -> one dead source cannot blank another's results
+//   failure sweep  -> EVERY failure maps to `unreachable`, which can never close
+//
+// Story 6.1 built the gates and constructed nothing. Story 6.2 wires this into
+// the Inbox read path - AFTER the emit, never before it, via a deliberate `void`
+// in `ChatIngestionSession.handleIngestionRunsRequest` - and adds the backoff
+// gate that reads the counter Story 6.1 could only increment.
+import { RECONCILE_MAX_CONCURRENCY, RECONCILE_STALE_MS, RECONCILE_TELEMETRY_INTERVAL_MS, RECONCILE_TIMEOUT_MS, RECONCILE_UNREACHABLE_BACKOFF_MS, RECONCILE_UNREACHABLE_THRESHOLD, } from "./constants.js";
+import { resolveReconciler as defaultResolveReconciler } from "./registry.js";
+import { assertSafeSignature, UnsafeSignatureError } from "./signature-guard.js";
+/** The failure verdict, shared so no call site can typo one into a closing verdict. */
+const UNREACHABLE = { verdict: "unreachable", signature: null };
+/** Samples kept per app slug. Bounded so a long-running daemon's telemetry cannot grow. */
+const LATENCY_RING_SIZE = 200;
+/** Neutral state for an item the ledger has never seen. */
+const NEVER_VERIFIED = {
+    verifiedAt: null,
+    verdict: null,
+    verifiedSignature: null,
+    reconcileAttemptedAt: null,
+    reconcileFailCount: 0,
+};
+/** `${filterId}:${itemKey}` - the ledger's primary key, flattened. */
+function keyOf(candidate) {
+    return `${candidate.filterId}:${candidate.itemKey}`;
+}
+/** Nearest-rank percentile over an already-sorted ascending array. */
+function percentile(sorted, fraction) {
+    if (sorted.length === 0)
+        return 0;
+    const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(fraction * sorted.length) - 1));
+    return sorted[index] ?? 0;
+}
+export class ReconciliationService {
+    constructor(options) {
+        /**
+         * In-flight reads, keyed `${filterId}:${itemKey}`.
+         *
+         * A `Map`, not a `Set`, and the difference is the whole point: the `Set` in
+         * `setupAutoArchiveOnMerge` can afford to SKIP a duplicate because its work
+         * has no return value, whereas a second caller here needs the first caller's
+         * verdict. Storing the promise lets the loser await the winner's outcome
+         * instead of getting a hole in its result map.
+         */
+        this.inFlight = new Map();
+        /** Slugs already complained about, so an unknown app is loud once per process. */
+        this.warnedSlugs = new Set();
+        /** Per-slug read round-trips in ms, bounded at `LATENCY_RING_SIZE`. */
+        this.latency = new Map();
+        this.lastTelemetryAt = 0;
+        this.ledger = options.ledger;
+        this.resolveMcpTarget = options.resolveMcpTarget;
+        this.daemonConfigStore = options.daemonConfigStore;
+        this.logger = options.logger;
+        this.now = options.now ?? (() => new Date());
+        this.resolveReconciler = options.resolveReconciler ?? defaultResolveReconciler;
+    }
+    /**
+     * Verify every candidate whose stamp is stale, and return an outcome for
+     * EVERY candidate - including the ones that were skipped.
+     *
+     * The returned map is total over the input on purpose. A caller that got a
+     * partial map would have to decide what a missing key meant, and the two
+     * plausible readings ("not stale" and "the read blew up") are exactly the two
+     * this epic exists to keep apart.
+     */
+    async verifyIfStale(candidates) {
+        const outcomes = new Map();
+        if (candidates.length === 0)
+            return outcomes;
+        const config = this.daemonConfigStore.get();
+        // 1. KILL SWITCH. Zero reads, zero writes, stored verdicts for everybody.
+        // Shaped after `archive-if-safe.ts:65`: an explicit `=== false` rather than
+        // a falsy check, so an absent key means "on" (the default) and only a
+        // deliberate `false` turns it off.
+        if (config.ingestionReconcileEnabled === false) {
+            for (const candidate of candidates) {
+                outcomes.set(keyOf(candidate), this.storedOutcome(candidate, false));
+            }
+            return outcomes;
+        }
+        const staleMs = this.resolveStaleMs(config.ingestionReconcileStaleMs);
+        const now = this.now().getTime();
+        const stale = [];
+        for (const candidate of candidates) {
+            const key = keyOf(candidate);
+            // 2. REGISTRY GATE (D-6.1-B). No reconciler is PERMANENT, not transient:
+            // no read, no verdict, no counter, `verified_at` untouched. The row stands
+            // - the safe direction - and the gap is loud in the logs rather than
+            // invisible.
+            if (this.resolveReconciler(candidate.appSlug) === null) {
+                this.warnUnknownSlugOnce(candidate.appSlug);
+                outcomes.set(key, { ...this.storedOutcome(candidate, false), skippedNoReconciler: true });
+                continue;
+            }
+            const stored = this.ledger.getVerification(candidate.filterId, candidate.itemKey);
+            // 3. UNREACHABLE BACKOFF GATE, and it runs BEFORE the staleness gate on
+            // purpose. An item that has been unreachable three times running is stale
+            // by definition - `unreachable` never advances `verified_at` (epic D4) -
+            // so a staleness check would wave it through on every single call and this
+            // gate would never be reached. Ordering is the whole mechanism.
+            //
+            // What it pauses is RECONCILIATION, not dispatch: Epic 3's `fail_count`
+            // and its cooldown are untouched (epic D5), and the row keeps rendering.
+            // The only thing that stops is paseo asking a source that is not
+            // answering. A single `pending` read resets the counter to zero per the
+            // verdict table; either closing verdict ends the item's Inbox life.
+            if (stored &&
+                stored.reconcileFailCount >= RECONCILE_UNREACHABLE_THRESHOLD &&
+                stored.reconcileAttemptedAt !== null &&
+                now < stored.reconcileAttemptedAt + RECONCILE_UNREACHABLE_BACKOFF_MS) {
+                outcomes.set(key, this.outcomeFrom(candidate, stored, false));
+                continue;
+            }
+            // 4. STALENESS GATE. A stamp inside the window is trusted as-is.
+            if (stored && stored.verifiedAt !== null && now - stored.verifiedAt < staleMs) {
+                outcomes.set(key, this.outcomeFrom(candidate, stored, false));
+                continue;
+            }
+            // 5. SINGLE-FLIGHT. Reuse the in-flight read rather than issuing a second.
+            const existing = this.inFlight.get(key);
+            if (existing) {
+                outcomes.set(key, await existing);
+                continue;
+            }
+            stale.push(candidate);
+        }
+        if (stale.length > 0) {
+            await this.runGroupedBySource(stale, outcomes);
+            this.maybeEmitTelemetry();
+        }
+        return outcomes;
+    }
+    /**
+     * Per-app read latency, for re-picking `RECONCILE_STALE_MS` and
+     * `RECONCILE_TIMEOUT_MS` off real data rather than off the guesses those
+     * constants currently hold.
+     */
+    snapshotReadLatency() {
+        const snapshot = {};
+        for (const [slug, samples] of this.latency) {
+            const sorted = [...samples].sort((a, b) => a - b);
+            snapshot[slug] = {
+                count: sorted.length,
+                p50: percentile(sorted, 0.5),
+                p95: percentile(sorted, 0.95),
+                max: sorted.length > 0 ? (sorted[sorted.length - 1] ?? 0) : 0,
+            };
+        }
+        return snapshot;
+    }
+    /**
+     * A misconfigured tunable falls back to the default rather than failing.
+     *
+     * The daemon must start even when reconciliation is misconfigured (epic
+     * Compatibility Requirement), and a zero or negative staleness window would
+     * make every candidate stale on every call - a read storm dressed as a
+     * config value.
+     */
+    resolveStaleMs(configured) {
+        if (typeof configured !== "number" || !Number.isInteger(configured) || configured <= 0) {
+            return RECONCILE_STALE_MS;
+        }
+        return configured;
+    }
+    /**
+     * Group by `sourceId`, then run ALL groups through ONE worker pool.
+     *
+     * The grouping is about isolation (NFR7): each group is awaited with
+     * `Promise.allSettled`, so a source that throws synchronously on every read
+     * cannot reject the settlement of a healthy source's group. The pool is about
+     * load: it is global to the call rather than per group, because four groups
+     * each capped at four would be sixteen concurrent reads against aggregators
+     * that rate-limit.
+     */
+    async runGroupedBySource(stale, outcomes) {
+        const groups = new Map();
+        for (const candidate of stale) {
+            const group = groups.get(candidate.sourceId);
+            if (group)
+                group.push(candidate);
+            else
+                groups.set(candidate.sourceId, [candidate]);
+        }
+        // One shared index cursor across the flattened list. Workers pull the next
+        // candidate rather than owning a slice, so a group of slow reads cannot
+        // leave three workers idle.
+        const flat = [...groups.values()].flat();
+        let cursor = 0;
+        const results = new Map();
+        const worker = async () => {
+            for (;;) {
+                const index = cursor;
+                cursor += 1;
+                const candidate = flat[index];
+                if (!candidate)
+                    return;
+                results.set(keyOf(candidate), await this.verifyOne(candidate));
+            }
+        };
+        const workerCount = Math.min(RECONCILE_MAX_CONCURRENCY, flat.length);
+        // `allSettled`, not `all`: `verifyOne` already maps every failure to
+        // `unreachable`, so a rejection here would be a defect in this file rather
+        // than a source failure - and taking the whole call down for it would blank
+        // the healthy sources too.
+        await Promise.allSettled(Array.from({ length: workerCount }, () => worker()));
+        for (const [key, outcome] of results)
+            outcomes.set(key, outcome);
+    }
+    /**
+     * One candidate, through the single-flight map so a concurrent caller shares
+     * this exact promise rather than issuing a second read.
+     */
+    verifyOne(candidate) {
+        const key = keyOf(candidate);
+        const existing = this.inFlight.get(key);
+        if (existing)
+            return existing;
+        const pending = this.readAndRecord(candidate)
+            .catch((error) => {
+            // The map `verifyIfStale` returns is TOTAL over its input, and that is a
+            // contract rather than a convenience: a caller handed a partial map has
+            // to guess what a missing key meant, and the two plausible readings
+            // ("not stale" and "the read blew up") are exactly the two this epic
+            // exists to keep apart. So a residual throw here - a sqlite write
+            // failure, say - still produces an entry rather than a hole.
+            this.logger.error({
+                err: error,
+                appSlug: candidate.appSlug,
+                sourceId: candidate.sourceId,
+                itemKey: candidate.itemKey,
+            }, "Ingestion reconcile could not record a verdict");
+            return this.storedOutcome(candidate, false);
+        })
+            .finally(() => {
+            this.inFlight.delete(key);
+        });
+        this.inFlight.set(key, pending);
+        return pending;
+    }
+    async readAndRecord(candidate) {
+        const result = await this.readOne(candidate);
+        this.ledger.recordVerification(candidate.filterId, candidate.itemKey, result);
+        const stored = this.ledger.getVerification(candidate.filterId, candidate.itemKey);
+        return {
+            ...this.outcomeFrom(candidate, stored ?? NEVER_VERIFIED, true),
+            // The verdict THIS read produced, which is not always what the row now
+            // holds: an `unreachable` read leaves `verified_verdict` at whatever the
+            // last successful read wrote, and a caller asking "what did we just
+            // learn?" must get `unreachable`, not the stale answer underneath it.
+            verdict: result.verdict,
+            signature: result.signature,
+        };
+    }
+    /**
+     * THE D4 BOUNDARY. Every path out of this function that is not a real answer
+     * from a reconciler returns `unreachable`.
+     *
+     * There are four such paths and all four are covered: `resolveMcpTarget`
+     * rejects, the reconciler throws synchronously, the reconciler rejects, the
+     * reconciler never settles. None of them can produce a closing verdict, which
+     * is why this story ships with a STRUCTURAL zero-false-close property rather
+     * than merely an untested one.
+     */
+    async readOne(candidate) {
+        const reconciler = this.resolveReconciler(candidate.appSlug);
+        if (!reconciler)
+            return UNREACHABLE;
+        const startedAt = performance.now();
+        try {
+            // A LOCAL CONST. Never a field, never part of a returned object, never
+            // logged. This is the only place in the epic where a bearer token is in
+            // scope, and it leaves scope when this function returns.
+            const target = await this.resolveMcpTarget(candidate.sourceId, candidate.appSlug);
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), RECONCILE_TIMEOUT_MS);
+            try {
+                // RACE, DO NOT TRUST. The timeout resolves `unreachable` on its own
+                // rather than depending on the reconciler noticing its signal: a
+                // reconciler that ignores the signal must not be able to hang a pool
+                // worker forever, and "honours AbortSignal" is not a property this
+                // service can verify about code Story 6.2 has not written yet.
+                const result = await Promise.race([
+                    reconciler(target, candidate.ref, controller.signal),
+                    new Promise((resolve) => {
+                        controller.signal.addEventListener("abort", () => resolve(UNREACHABLE), {
+                            once: true,
+                        });
+                    }),
+                ]);
+                return this.guardSignature(candidate, result);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        catch (error) {
+            // `{ appSlug, sourceId, itemKey }` and NEVER the target. The whole reason
+            // the target is a local const is undone by one careless log line.
+            this.logger.warn({
+                err: error,
+                appSlug: candidate.appSlug,
+                sourceId: candidate.sourceId,
+                itemKey: candidate.itemKey,
+            }, "Ingestion reconcile read failed; recording unreachable");
+            return UNREACHABLE;
+        }
+        finally {
+            this.recordLatency(candidate.appSlug, performance.now() - startedAt);
+        }
+    }
+    /**
+     * A reconciler returned something the ledger must never store.
+     *
+     * The guard also lives at the ledger's write boundary, where it THROWS - that
+     * is the last line of defence for any caller. Here, one layer up, the throw is
+     * converted into `unreachable` for two reasons that both point the same way:
+     * the outcome map must stay total, and one carelessly written reconciler must
+     * not be able to blank the results of every healthy source in the same batch
+     * (NFR7).
+     *
+     * Logged at ERROR with its own message, not at `warn` alongside network
+     * failures. This is a DEFECT IN PASEO'S OWN CODE, not a source being
+     * unavailable, and burying it among transient read failures is how it would
+     * survive to the next release. The offending value is never logged.
+     */
+    guardSignature(candidate, result) {
+        try {
+            assertSafeSignature(result.signature);
+            return result;
+        }
+        catch (error) {
+            if (!(error instanceof UnsafeSignatureError))
+                throw error;
+            this.logger.error({
+                reason: error.reason,
+                appSlug: candidate.appSlug,
+                sourceId: candidate.sourceId,
+                itemKey: candidate.itemKey,
+            }, "Reconciler returned an unsafe signature; discarding the verdict");
+            // The whole verdict is discarded, not just the signature. A closing
+            // verdict whose evidence had to be thrown away is not evidence.
+            return UNREACHABLE;
+        }
+    }
+    recordLatency(appSlug, ms) {
+        let ring = this.latency.get(appSlug);
+        if (!ring) {
+            ring = [];
+            this.latency.set(appSlug, ring);
+        }
+        ring.push(ms);
+        if (ring.length > LATENCY_RING_SIZE)
+            ring.splice(0, ring.length - LATENCY_RING_SIZE);
+    }
+    maybeEmitTelemetry() {
+        const now = this.now().getTime();
+        if (now - this.lastTelemetryAt < RECONCILE_TELEMETRY_INTERVAL_MS)
+            return;
+        this.lastTelemetryAt = now;
+        this.logger.info({ readLatency: this.snapshotReadLatency() }, "Ingestion reconcile read latency");
+    }
+    /**
+     * Loud ONCE per slug per process.
+     *
+     * "Enumerate what you silence" applied to the open-world edge of a closed
+     * registry: an unknown app slug is the one case this design cannot decide
+     * statically, so it is never dropped - but a filter with 400 items would
+     * otherwise emit 400 identical lines per pass and become its own noise floor.
+     */
+    warnUnknownSlugOnce(appSlug) {
+        if (this.warnedSlugs.has(appSlug))
+            return;
+        this.warnedSlugs.add(appSlug);
+        this.logger.warn({ appSlug }, `No ingestion reconciler for app slug "${appSlug}"; its items are left unverified.`);
+    }
+    storedOutcome(candidate, read) {
+        const stored = this.ledger.getVerification(candidate.filterId, candidate.itemKey);
+        return this.outcomeFrom(candidate, stored ?? NEVER_VERIFIED, read);
+    }
+    outcomeFrom(candidate, state, read) {
+        return {
+            filterId: candidate.filterId,
+            itemKey: candidate.itemKey,
+            verdict: state.verdict,
+            signature: state.verifiedSignature,
+            verifiedAt: state.verifiedAt,
+            reconcileFailCount: state.reconcileFailCount,
+            read,
+            skippedNoReconciler: false,
+        };
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/server/server/ingestion/reconcile/signature-guard.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare const MAX_SIGNATURE_LEN = 200;
+/**
+ * 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 declare class UnsafeSignatureError extends Error {
+    /** `"too-long"` or `"credential-shaped"`. A closed set, safe to log. */
+    readonly reason: "too-long" | "credential-shaped";
+    constructor(reason: "too-long" | "credential-shaped");
+}
+/**
+ * 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 declare function assertSafeSignature(signature: string | null): void;
+//# sourceMappingURL=signature-guard.d.ts.map