@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/ingestion/ledger.js

@@ -0,0 +1,881 @@
+// THE INGESTION LEDGER - the daemon's durable memory of what it has already
+// dispatched, so an unattended overnight run does not re-fire the same item
+// every tick.
+//
+// It answers exactly one question, `isFresh()`, and that question is keyed on
+// the item's CONTENT, not its id: an item whose content has not changed is
+// never dispatched twice, while an item whose content DID change re-fires
+// exactly once. Keying on the id instead would permanently silence an item
+// after its first sighting, which is the bug this table exists to prevent.
+//
+// Semantics ported from `~/super-repo/tooling/loops/lib/ledger.mjs`:
+//   contentChanged :38, touch :42, inBackoff :73.
+//
+// SCOPE: `touch()` writes first_seen_at / last_seen_at / content_hash / meta
+// only. `handled_at` and `outcome` are written by `mark()` and by nothing else,
+// because pre-writing them anywhere earlier would record INTENT as fact - it
+// would mark an item handled before anything actually handled it, silently
+// defeating the "mark only after success" guarantee this ledger exists for.
+//
+// The claim/mark pair (Story 3.2) is what makes a crash survivable: `claim()`
+// runs at dispatch, `mark()` only once the action reported success, and
+// `releaseStaleClaims()` at daemon boot turns whatever was left claimed-but-
+// unmarked back into an eligible item - exactly once, not once per boot.
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { ReconcileVerdictSchema, } from "@hyperdrive.bot/fleet-protocol/ingestion/run-view";
+import { FAIL_SIG_MAX_LENGTH, isHardFailureSig } from "./hard-failure.js";
+import { assertSafeSignature } from "./reconcile/signature-guard.js";
+import { mapVerdict } from "./reconcile/verdict-mapping.js";
+import { BACKOFF_COOLDOWN_MS, BACKOFF_THRESHOLD, ensureSchema, LEDGER_PRUNE_DAYS, } from "./ledger-schema.js";
+import { utcDateKey } from "./utc-day.js";
+/**
+ * The ledger file's basename inside the injected home directory.
+ *
+ * This module deliberately holds NO knowledge of where that directory is: the
+ * OS home dir and the env var that overrides it are the caller's business, and
+ * a test asserts this file never mentions either. That is what keeps a test run
+ * from ever writing into a developer's real home.
+ */
+const LEDGER_FILENAME = "paseo.sqlite";
+/**
+ * The ledger could not be opened: `node:sqlite` is missing from this runtime,
+ * or the database file itself refused to open.
+ *
+ * This is thrown, never swallowed (epic decision D1). A ledger that degrades to
+ * a no-op is strictly worse than no ledger at all: every item would read as
+ * fresh forever, so an armed filter would re-dispatch its whole backlog on
+ * every single tick, unattended, with nothing in the logs saying why.
+ *
+ * Follows `ScheduleTargetGoneError` in `schedule/service.ts`.
+ */
+export class IngestionLedgerUnavailableError extends Error {
+    constructor(dbPath, options) {
+        super(`Ingestion ledger could not open ${dbPath}. The daemon has no durable dedupe memory, so an armed filter would re-dispatch every item on every tick.`, options);
+        this.name = "IngestionLedgerUnavailableError";
+        this.dbPath = dbPath;
+    }
+}
+const META_ALLOWED_KEYS = ["sourceId", "subject", "url", "groupKey", "receivedAt"];
+/**
+ * `fail_sig` stamped on a claim that a daemon restart released.
+ *
+ * Decision D2: a crash is not an action failure in principle, but it is one for
+ * the purpose of not repeating it. An item that wedges the daemon
+ * `BACKOFF_THRESHOLD` times lands in the ordinary backoff window instead of
+ * crash-looping the daemon on every boot.
+ */
+export const DAEMON_RESTART_FAIL_SIG = "daemon-restart";
+/** Shared empty default so `releaseStaleClaims()` allocates nothing on the common path. */
+const NO_RUNS_IN_FLIGHT = new Set();
+/** Milliseconds in a day, for `prune()`'s cutoff arithmetic. */
+const MS_PER_DAY = 86400000;
+/**
+ * Resolve `node:sqlite` LAZILY.
+ *
+ * A static top-level `import { DatabaseSync } from "node:sqlite"` (the
+ * `search/index-store.ts` style) would be uncatchable on a runtime that lacks
+ * the module - importing this file would crash the daemon at load. `createRequire`
+ * moves that failure inside a `try`, so importing the module is always safe and
+ * CONSTRUCTING the ledger is what fails.
+ *
+ * Unlike `meetings-http.ts:getDatabaseSyncCtor()`, nothing is cached and a
+ * failure is not memoized as `null`: there is no degrade path here to memoize.
+ */
+function loadDatabaseSyncCtor() {
+    const req = createRequire(import.meta.url);
+    return req("node:sqlite").DatabaseSync;
+}
+function asString(value) {
+    return typeof value === "string" ? value : null;
+}
+function asNumber(value) {
+    return typeof value === "number" ? value : null;
+}
+/** Narrow one sqlite row. Kept flat: `no-explicit-any` is error-level here. */
+function toEntry(row) {
+    return {
+        filterId: asString(row.filter_id) ?? "",
+        itemKey: asString(row.item_key) ?? "",
+        contentHash: asString(row.content_hash),
+        firstSeenAt: asNumber(row.first_seen_at) ?? 0,
+        lastSeenAt: asNumber(row.last_seen_at) ?? 0,
+        handledAt: asNumber(row.handled_at),
+        outcome: asString(row.outcome),
+        failCount: asNumber(row.fail_count) ?? 0,
+        lastFailAt: asNumber(row.last_fail_at),
+        failSig: asString(row.fail_sig),
+        alertedOn: asString(row.alerted_on),
+        claimedAt: asNumber(row.claimed_at),
+        claimRunId: asString(row.claim_run_id),
+        agentId: asString(row.agent_id),
+        meta: asString(row.meta),
+    };
+}
+/**
+ * CONTENT strategy, ported from `ledger.mjs:38`. An unknown key is always
+ * changed, which is what makes a never-before-seen item fresh.
+ *
+ * Exported for testing. Production callers go through `isFresh`.
+ */
+export function contentChanged(entry, contentHash) {
+    return !entry || entry.contentHash !== contentHash;
+}
+/**
+ * Retry-storm guard, ported from `ledger.mjs:73`. An item that has failed
+ * `BACKOFF_THRESHOLD` times in a row is parked until `BACKOFF_COOLDOWN_MS` has
+ * elapsed since its last failure, then gets ONE retry; if that fails,
+ * `last_fail_at` resets and it parks again - roughly one attempt per window
+ * instead of one per tick.
+ *
+ * `fail_count` is written by `recordFailure()` and by `releaseStaleClaims()`,
+ * and cleared by `mark()`. Those three are its only writers.
+ *
+ * Exported for testing. Production callers go through `isFresh`.
+ */
+export function inBackoff(entry, now) {
+    if (!entry || entry.failCount < BACKOFF_THRESHOLD)
+        return false;
+    return now - (entry.lastFailAt ?? 0) < BACKOFF_COOLDOWN_MS;
+}
+/**
+ * Epoch ms this entry's backoff window expires, or null when not parked.
+ * Derived, never stored.
+ *
+ * The ONE place the window is computed. `listForFilter` renders it onto the
+ * wire and `recordFailure` returns it; neither re-derives
+ * `lastFailAt + BACKOFF_COOLDOWN_MS` locally, so the wire value and the
+ * suppression decision can never disagree about when an item wakes up.
+ *
+ * Exported for testing. Production callers read it off the wire shape or off
+ * `FailureOutcome`.
+ */
+/**
+ * A zero-valued `LedgerEntry` so `listRunViewRows` can call `backoffUntil` with
+ * only the two fields it reads, instead of re-deriving the window locally.
+ *
+ * Spreading over this rather than casting keeps `no-explicit-any` satisfied and,
+ * more usefully, means a field ADDED to `LedgerEntry` fails to compile here
+ * until somebody decides what its neutral value is.
+ */
+const EMPTY_ENTRY = {
+    filterId: "",
+    itemKey: "",
+    contentHash: null,
+    firstSeenAt: 0,
+    lastSeenAt: 0,
+    handledAt: null,
+    outcome: null,
+    failCount: 0,
+    lastFailAt: null,
+    failSig: null,
+    alertedOn: null,
+    claimedAt: null,
+    claimRunId: null,
+    agentId: null,
+    meta: null,
+};
+export function backoffUntil(entry) {
+    if (entry.failCount < BACKOFF_THRESHOLD || entry.lastFailAt === null)
+        return null;
+    return entry.lastFailAt + BACKOFF_COOLDOWN_MS;
+}
+/**
+ * Clamp a caller-supplied signature to what this table will store.
+ *
+ * Two jobs, both at the WRITE boundary rather than only in `hardFailureSig`,
+ * because a caller can pass a signature this module did not produce:
+ *   - a falsy signature becomes SQL NULL, which `COALESCE` then reads as
+ *     "leave the stored one alone" (`ledger.mjs:66`)
+ *   - a long one is truncated at 64 characters
+ *
+ * Be precise about what the cap is: a BLAST-RADIUS limit, not a sanitizer. It
+ * bounds how much of a mistaken input can land in the column; it cannot make a
+ * 64-character prefix of a raw log safe. The actual control is upstream and is
+ * a closed set: `fail_sig` is only ever `hardFailureSig()`'s output (eight
+ * literal phrases) or `DAEMON_RESTART_FAIL_SIG`. Passing a raw log line here is
+ * a call-site bug, and the cap only limits what it costs.
+ */
+function normalizeFailSig(sig) {
+    if (!sig)
+        return null;
+    return sig.slice(0, FAIL_SIG_MAX_LENGTH);
+}
+/**
+ * Copy only the allow-listed keys, dropping undefined ones so the stored JSON
+ * stays small. Returns null when nothing survives, so the column reads as SQL
+ * NULL rather than the string `"{}"`.
+ */
+function serializeMeta(meta) {
+    if (!meta)
+        return null;
+    const safe = {};
+    for (const key of META_ALLOWED_KEYS) {
+        const value = meta[key];
+        if (typeof value === "string")
+            safe[key] = value;
+    }
+    return Object.keys(safe).length > 0 ? JSON.stringify(safe) : null;
+}
+export class IngestionLedger {
+    constructor(options) {
+        /** Values already complained about, so a corrupted column is loud once, not once per row. */
+        this.warnedVerdicts = new Set();
+        // Prepared once and reused, following `SessionIndexStore`. The ingestion pass
+        // calls get/touch once per item per tick, so re-preparing would re-plan the
+        // same two statements thousands of times a night.
+        this.getStmt = null;
+        this.touchStmt = null;
+        this.listStmt = null;
+        this.claimInsertStmt = null;
+        this.claimUpdateStmt = null;
+        this.markInsertStmt = null;
+        this.markUpdateStmt = null;
+        this.recordFailureStmt = null;
+        this.alertClaimedStmt = null;
+        this.claimAlertStmt = null;
+        this.selectClaimedStmt = null;
+        this.releaseClaimStmt = null;
+        this.pruneStmt = null;
+        this.pruneBudgetStmt = null;
+        this.readBudgetStmt = null;
+        this.reserveBudgetStmt = null;
+        this.releaseBudgetStmt = null;
+        /** `pending`: stamps, resets the counter, and never names `verified_signature`. */
+        this.stampVerificationStmt = null;
+        /** The two CLOSING verdicts: the only statement that names `verified_signature`. */
+        this.closeVerificationStmt = null;
+        /** `unreachable`: names neither `verified_at` nor `verified_verdict`, by construction. */
+        this.unreachableVerificationStmt = null;
+        this.getVerificationStmt = null;
+        this.runViewStmt = null;
+        this.now = options.now ?? (() => new Date());
+        this.warn = options.warn ?? ((message) => console.warn(message));
+        this.dbPath = join(options.paseoHome, LEDGER_FILENAME);
+        let db;
+        try {
+            const DatabaseSyncCtor = loadDatabaseSyncCtor();
+            db = new DatabaseSyncCtor(this.dbPath);
+            ensureSchema(db);
+        }
+        catch (error) {
+            throw new IngestionLedgerUnavailableError(this.dbPath, { cause: error });
+        }
+        this.db = db;
+    }
+    /**
+     * THE one database handle, for collaborators that must write to the same file.
+     *
+     * Exposed for Story 5.4's `CohortStore`, and read-only on purpose: a caller
+     * gets the handle, never the right to replace it. The alternative - having the
+     * cohort store open its own `DatabaseSync` on the same path - would put two
+     * connections and two WAL readers on a file this daemon deliberately keeps to
+     * one, and would make a cohort write invisible to a ledger read inside the
+     * same transaction.
+     *
+     * `close()` stays this class's job. Nothing that borrows the handle may close it.
+     */
+    get database() {
+        return this.db;
+    }
+    /** One row, or undefined when this (filter, item) has never been seen. */
+    get(filterId, itemKey) {
+        this.getStmt ?? (this.getStmt = this.db.prepare("SELECT * FROM ingestion_items WHERE filter_id = ? AND item_key = ?"));
+        const row = this.getStmt.get(filterId, itemKey);
+        return row ? toEntry(row) : undefined;
+    }
+    /**
+     * THE question, and the only place it is answered.
+     *
+     * `actionable && contentChanged && !inBackoff` - one expression, one place.
+     * No other module re-derives freshness from these parts; `contentChanged` and
+     * `inBackoff` are exported for their own tests, not for callers to recombine.
+     */
+    isFresh(entry, input) {
+        // A live claim short-circuits EVERYTHING, ahead of actionable, contentChanged
+        // and inBackoff: an item somebody is already acting on is not eligible, even
+        // if its content changed since the claim was taken.
+        //
+        // Decision D4 - there is deliberately NO claim TTL. A claim is cleared by
+        // exactly one mechanism, `releaseStaleClaims()` at daemon boot, so an orphan
+        // claim cannot outlive a daemon lifetime. A TTL would be a second, competing
+        // reaper that fires while the run is still going and re-dispatches a live
+        // item, which is the precise duplicate-artifact failure this ledger exists to
+        // prevent. Do not add one "for safety".
+        if (entry && entry.claimedAt !== null)
+            return false;
+        return (input.actionable &&
+            contentChanged(entry, input.contentHash) &&
+            !inBackoff(entry, this.now().getTime()));
+    }
+    /**
+     * Record that an item was SEEN this pass. Deliberately suppresses nothing:
+     * `isFresh` returns the same verdict before and after any number of `touch`
+     * calls. Only a content hash written by a successful handling (Story 3.2)
+     * suppresses an item.
+     *
+     * On a known key this updates `last_seen_at` and `meta` ONLY - `first_seen_at`,
+     * `content_hash`, `handled_at` and `outcome` are left exactly as they were.
+     */
+    touch(filterId, itemKey, meta) {
+        this.touchStmt ?? (this.touchStmt = this.db.prepare(`INSERT INTO ingestion_items (filter_id, item_key, first_seen_at, last_seen_at, fail_count, meta)
+       VALUES (?, ?, ?, ?, 0, ?)
+       ON CONFLICT(filter_id, item_key) DO UPDATE SET
+         last_seen_at = excluded.last_seen_at,
+         meta = COALESCE(excluded.meta, ingestion_items.meta)`));
+        // STRICT table: bind an integer, never a Date and never a float.
+        const timestamp = this.now().getTime();
+        this.touchStmt.run(filterId, itemKey, timestamp, timestamp, serializeMeta(meta));
+    }
+    /**
+     * Recent items for one filter, newest first - the ordering that lets this
+     * ride `idx_ingestion_items_filter_seen` instead of sorting a scan.
+     */
+    listForFilter(filterId, limit) {
+        this.listStmt ?? (this.listStmt = this.db.prepare(`SELECT * FROM ingestion_items
+       WHERE filter_id = ?
+       ORDER BY last_seen_at DESC
+       LIMIT ?`));
+        return this.listStmt.all(filterId, limit).map((row) => {
+            const entry = toEntry(row);
+            return {
+                itemKey: entry.itemKey,
+                contentHash: entry.contentHash,
+                outcome: entry.outcome,
+                failCount: entry.failCount,
+                backoffUntil: backoffUntil(entry),
+                failSig: entry.failSig,
+                agentId: entry.agentId,
+            };
+        });
+    }
+    /**
+     * CLAIM one item for one dispatch. Compare-and-set, not a blind write.
+     *
+     * Upserts the row if this (filter, item) has never been seen, then takes the
+     * claim ONLY where `claimed_at IS NULL`. Returns `true` when this dispatch won
+     * the claim; `false` when another dispatch already holds it, in which case the
+     * caller must skip the item rather than act on it.
+     *
+     * The compare-and-set (decision D3) is a strict superset of a blind
+     * `UPDATE ... SET claimed_at = ?`: two dispatch paths evaluating freshness in
+     * the same millisecond would both write a claim, the second silently
+     * overwriting the first's `claim_run_id`, and `releaseStaleClaims()` would then
+     * strand one run forever. The CAS makes the loser observable.
+     *
+     * This is ITEM-level dedupe and is NOT a substitute for
+     * `ScheduleService.runningScheduleIds` or `agentManager.hasInFlightRun` - those
+     * remain the process-level single-flight and are untouched by this file.
+     *
+     * Both statements run inside one transaction, so a crash between them cannot
+     * leave a seeded row that nobody ever claimed or released.
+     */
+    claim(filterId, itemKey, options) {
+        this.claimInsertStmt ?? (this.claimInsertStmt = this.db.prepare(`INSERT OR IGNORE INTO ingestion_items (filter_id, item_key, first_seen_at, last_seen_at, fail_count)
+       VALUES (?, ?, ?, ?, 0)`));
+        this.claimUpdateStmt ?? (this.claimUpdateStmt = this.db.prepare(
+        // `last_run_id` is written from the SAME `options.runId` in the SAME
+        // statement as `claim_run_id`, so the two can never disagree about which
+        // run this was. They differ only in lifetime: `mark()` and
+        // `releaseStaleClaims()` clear the claim, and neither touches this one.
+        `UPDATE ingestion_items
+          SET claimed_at = ?, claim_run_id = ?, last_run_id = ?, agent_id = ?, last_seen_at = ?
+        WHERE filter_id = ? AND item_key = ? AND claimed_at IS NULL`));
+        // STRICT table: bind an integer, never a Date and never a float.
+        const timestamp = this.now().getTime();
+        this.db.exec("BEGIN");
+        try {
+            this.claimInsertStmt.run(filterId, itemKey, timestamp, timestamp);
+            const result = this.claimUpdateStmt.run(timestamp, options.runId, options.runId, options.agentId ?? null, timestamp, filterId, itemKey);
+            this.db.exec("COMMIT");
+            return result.changes === 1;
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    /**
+     * MARK one item handled. Called ONLY after the action reported success -
+     * never at dispatch, which is the whole reason `claim()` and `mark()` are two
+     * methods and not one.
+     *
+     * A terminal outcome means the item succeeded, so the same single `UPDATE`
+     * clears every failure and backoff column alongside the claim
+     * (`ledger.mjs:53-54`). `alerted_on` is this table's name for `ledger.mjs`'s
+     * `alertedAt`, and holds a `YYYY-MM-DD` UTC string rather than an epoch.
+     *
+     * `contentHash: undefined` PRESERVES the stored hash via `COALESCE`, exactly
+     * as `ledger.mjs:52` does with `if (contentHash != null)`; the same is true of
+     * `agentId`. Passing an explicit value overwrites.
+     *
+     * `MarkOptions` carries no `meta` field, and must not grow one "for symmetry
+     * with `touch()`": its absence is what keeps an aggregator payload from
+     * smuggling a credential into `ingestion_items.meta` through this path.
+     */
+    mark(filterId, itemKey, options) {
+        this.markInsertStmt ?? (this.markInsertStmt = this.db.prepare(`INSERT OR IGNORE INTO ingestion_items (filter_id, item_key, first_seen_at, last_seen_at, fail_count)
+       VALUES (?, ?, ?, ?, 0)`));
+        this.markUpdateStmt ?? (this.markUpdateStmt = this.db.prepare(`UPDATE ingestion_items
+          SET handled_at    = ?,
+              outcome       = ?,
+              last_seen_at  = ?,
+              content_hash  = COALESCE(?, content_hash),
+              agent_id      = COALESCE(?, agent_id),
+              fail_count    = 0,
+              last_fail_at  = NULL,
+              fail_sig      = NULL,
+              alerted_on    = NULL,
+              claimed_at    = NULL,
+              claim_run_id  = NULL
+        WHERE filter_id = ? AND item_key = ?`));
+        const timestamp = this.now().getTime();
+        this.db.exec("BEGIN");
+        try {
+            this.markInsertStmt.run(filterId, itemKey, timestamp, timestamp);
+            this.markUpdateStmt.run(timestamp, options.outcome, timestamp, options.contentHash ?? null, options.agentId ?? null, filterId, itemKey);
+            this.db.exec("COMMIT");
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    /**
+     * Has nothing alerted yet TODAY for this `(filterId, sig)` pair?
+     *
+     * Keyed on the FILTER and the signature, never on the item. One dead
+     * credential fails every item of a filter; keying on the item would turn one
+     * expired key into one alert per item, which is the retry-storm this whole
+     * mechanism exists to end, merely relocated to the notification channel.
+     *
+     * Names exactly what it silences - the `(filter_id, fail_sig, alerted_on)`
+     * triple - rather than listing signatures it is willing to report. A
+     * signature nobody anticipated therefore comes out noisy, not invisible.
+     *
+     * Pure read: it reports whether the day is claimed, it does NOT claim it.
+     * `recordFailure` does the claiming, and only then reports `shouldAlert`.
+     */
+    shouldAlertToday(filterId, sig, now) {
+        this.alertClaimedStmt ?? (this.alertClaimedStmt = this.db.prepare(`SELECT 1 AS claimed FROM ingestion_items
+        WHERE filter_id = ? AND fail_sig = ? AND alerted_on = ?
+        LIMIT 1`));
+        return this.alertClaimedStmt.get(filterId, sig, utcDateKey(now)) === undefined;
+    }
+    /**
+     * Record that acting on an item FAILED. The write half of the retry-storm
+     * guard, ported from `ledger.mjs:62`.
+     *
+     * One upsert does both cases: an unknown `(filter, item)` is created with
+     * `fail_count = 1`, a known one is incremented. `fail_sig` goes through
+     * `COALESCE`, so a failure that carries no signature leaves an earlier one
+     * standing instead of erasing it.
+     *
+     * Failures 1 and 2 leave the item eligible on the very next tick. Failure 3
+     * parks it for `BACKOFF_COOLDOWN_MS`; the retry that the expired window
+     * admits, if it fails, lands back here, re-stamps `last_fail_at` and parks it
+     * again - so the steady state is at most one attempt per 6h window, never one
+     * per tick.
+     *
+     * Everything runs in ONE transaction, and the ordering inside it is
+     * load-bearing. The upsert comes first, which takes the write lock, so the
+     * read-then-claim of today's alert that follows cannot interleave with
+     * another caller doing the same: two concurrent hard failures cannot both
+     * come away believing they alerted. `shouldAlert` is returned only after the
+     * day was actually claimed in the database - never on the strength of having
+     * intended to claim it.
+     *
+     * Note there is no `try/catch` around the query itself. A `SELECT` that fails
+     * must surface, not degrade into "no alert today": an empty result and a
+     * broken database would otherwise look identical, and the broken one would
+     * stay silent forever.
+     */
+    recordFailure(filterId, itemKey, options = {}) {
+        this.recordFailureStmt ?? (this.recordFailureStmt = this.db.prepare(
+        // `excluded.*` rather than re-binding the same two values, matching
+        // `touch()` above; identical semantics, half the binds.
+        `INSERT INTO ingestion_items (filter_id, item_key, first_seen_at, last_seen_at, fail_count, last_fail_at, fail_sig)
+       VALUES (?, ?, ?, ?, 1, ?, ?)
+       ON CONFLICT(filter_id, item_key) DO UPDATE SET
+         fail_count   = fail_count + 1,
+         last_fail_at = excluded.last_fail_at,
+         fail_sig     = COALESCE(excluded.fail_sig, ingestion_items.fail_sig)`));
+        this.claimAlertStmt ?? (this.claimAlertStmt = this.db.prepare("UPDATE ingestion_items SET alerted_on = ? WHERE filter_id = ? AND item_key = ?"));
+        const nowDate = this.now();
+        // STRICT table: bind an integer, never a Date and never a float.
+        const timestamp = nowDate.getTime();
+        const sig = normalizeFailSig(options.sig);
+        // Derived from THIS failure's signature, not from the row's stored one. A
+        // plain error following an earlier `rate-limit` leaves `rate-limit` in the
+        // column via COALESCE, and must not inherit its abort: the shell aborts on
+        // `$SIG` from the run it just made, not on history.
+        const hardFailure = isHardFailureSig(sig);
+        this.db.exec("BEGIN");
+        try {
+            this.recordFailureStmt.run(filterId, itemKey, timestamp, timestamp, timestamp, sig);
+            let shouldAlert = false;
+            if (hardFailure && sig !== null && this.shouldAlertToday(filterId, sig, nowDate)) {
+                this.claimAlertStmt.run(utcDateKey(nowDate), filterId, itemKey);
+                shouldAlert = true;
+            }
+            const entry = this.get(filterId, itemKey);
+            this.db.exec("COMMIT");
+            return {
+                failCount: entry?.failCount ?? 1,
+                lastFailAt: entry?.lastFailAt ?? timestamp,
+                failSig: entry?.failSig ?? null,
+                backoffUntil: entry ? backoffUntil(entry) : null,
+                hardFailure,
+                shouldAlert,
+                // Not `shouldAlert && hardFailure`. See `FailureOutcome.abortTick`.
+                abortTick: hardFailure,
+            };
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    /**
+     * Release every claim whose run is not still in flight, and record one failure
+     * against each. Called once at daemon boot, where nothing is in flight by
+     * definition, which is why `inFlightRunIds` defaults to empty.
+     *
+     * The select names what it SILENCES (`inFlightRunIds`), not what it wants: it
+     * takes every `claimed_at IS NOT NULL` row and then skips the one set it is
+     * told to spare, so a claim in a state nobody anticipated comes out noisy
+     * rather than invisible.
+     *
+     * Decision D2 - the `fail_count + 1` is deliberate. A crash is not an action
+     * failure in principle, but it is one for the purpose of not repeating it: an
+     * item that wedges the daemon `BACKOFF_THRESHOLD` times enters the ordinary
+     * backoff window instead of crash-looping the daemon on every boot. The
+     * increment happens once per release, not once per boot - a second call with
+     * nothing claimed releases nothing and increments nothing.
+     *
+     * Returns the number of rows released. All releases share one transaction.
+     */
+    releaseStaleClaims(options) {
+        const inFlightRunIds = options?.inFlightRunIds ?? NO_RUNS_IN_FLIGHT;
+        this.selectClaimedStmt ?? (this.selectClaimedStmt = this.db.prepare("SELECT filter_id, item_key, claim_run_id FROM ingestion_items WHERE claimed_at IS NOT NULL"));
+        this.releaseClaimStmt ?? (this.releaseClaimStmt = this.db.prepare(`UPDATE ingestion_items
+          SET claimed_at   = NULL,
+              claim_run_id = NULL,
+              fail_count   = fail_count + 1,
+              last_fail_at = ?,
+              fail_sig     = ?
+        WHERE filter_id = ? AND item_key = ? AND claimed_at IS NOT NULL`));
+        const claimed = this.selectClaimedStmt.all();
+        const stale = claimed.filter((row) => {
+            const runId = asString(row.claim_run_id);
+            return runId === null || !inFlightRunIds.has(runId);
+        });
+        if (stale.length === 0)
+            return 0;
+        const timestamp = this.now().getTime();
+        this.db.exec("BEGIN");
+        try {
+            let released = 0;
+            for (const row of stale) {
+                const result = this.releaseClaimStmt.run(timestamp, DAEMON_RESTART_FAIL_SIG, asString(row.filter_id) ?? "", asString(row.item_key) ?? "");
+                released += result.changes;
+            }
+            this.db.exec("COMMIT");
+            return released;
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    /**
+     * Drop rows nothing has touched in `days`, returning how many were deleted.
+     *
+     * Two details are load-bearing:
+     *
+     * 1. `max(a, b, c)` with more than one argument is sqlite's SCALAR max, not
+     *    the aggregate, so this compares the NEWEST of the three timestamps. That
+     *    is a deliberate refinement over `ledger.mjs:81`'s first-truthy
+     *    `handledAt || lastSeen || firstSeen` chain (decision D5): a row handled 40
+     *    days ago but seen yesterday is live, and the first-truthy version would
+     *    prune it. Do not "fix" this back.
+     * 2. `claimed_at IS NULL` never deletes a live claim. At boot this is defence
+     *    in depth - `releaseStaleClaims()` already ran one line earlier - but it
+     *    keeps `prune()` correct if the two calls are ever reordered, or if a
+     *    future caller invokes it mid-run with claims outstanding.
+     */
+    prune(days = LEDGER_PRUNE_DAYS) {
+        this.pruneStmt ?? (this.pruneStmt = this.db.prepare(`DELETE FROM ingestion_items
+        WHERE claimed_at IS NULL
+          AND max(coalesce(handled_at, 0), coalesce(last_seen_at, 0), coalesce(first_seen_at, 0)) < ?`));
+        this.pruneBudgetStmt ?? (this.pruneBudgetStmt = this.db.prepare("DELETE FROM ingestion_dispatch_budget WHERE day < ?"));
+        const now = this.now().getTime();
+        const cutoff = now - days * MS_PER_DAY;
+        // The budget cutoff is a `YYYY-MM-DD` STRING compared with `<`, which is
+        // only correct because the key is zero-padded ISO - lexicographic order
+        // equals chronological order for that format and for no other. See the DDL
+        // comment in `ledger-schema.ts`.
+        const budgetCutoffDay = utcDateKey(new Date(cutoff));
+        this.db.exec("BEGIN");
+        try {
+            const deletedItems = this.pruneStmt.run(cutoff).changes;
+            this.pruneBudgetStmt.run(budgetCutoffDay);
+            this.db.exec("COMMIT");
+            // Deliberately ITEM rows only. Story 3.2's callers and tests pin this
+            // number; a budget count silently folded in would make "pruned 4" mean
+            // two different things depending on which day it was read.
+            return deletedItems;
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    // ---- CapBudgetStore (Story 3.4) -----------------------------------------
+    //
+    // The budget is a COUNT OF ATTEMPTS, held in its own table. It is never
+    // inferred from `ingestion_items`: that table is keyed per item, so counting
+    // it would count distinct items instead of dispatches and let a cap of 10
+    // mint up to 70 sessions across a day of retries (decision D-3.4-A).
+    /**
+     * How many dispatches `filterId` has been granted on `day`. `0` when the
+     * filter has no row for that day - which is indistinguishable from a row
+     * holding `0`, on purpose, since `reserveDispatches` never writes one.
+     *
+     * Returns `0` only after a SUCCESSFUL query. An open failure throws out of the
+     * constructor (epic D1); it never degrades into a zero here.
+     */
+    readDispatched(filterId, day) {
+        this.readBudgetStmt ?? (this.readBudgetStmt = this.db.prepare("SELECT dispatched FROM ingestion_dispatch_budget WHERE filter_id = ? AND day = ?"));
+        const row = this.readBudgetStmt.get(filterId, day);
+        if (row === undefined)
+            return 0;
+        return asNumber(row.dispatched) ?? 0;
+    }
+    /**
+     * Spend up to `requested` of the day's remaining budget and return how much
+     * was actually granted.
+     *
+     * The clamp lives INSIDE the transaction, not in `CapLimiter`. `node:sqlite`
+     * is synchronous and Node is single-threaded, so a same-process read-then-write
+     * race is not reachable today - but the e2e spec opens a second connection to
+     * the same file, and "correct only because of a runtime property nobody wrote
+     * down" is how the next reader gets bitten. `BEGIN IMMEDIATE` takes the write
+     * lock at the read, so two writers serialize instead of both seeing the same
+     * `dispatched` and both granting.
+     *
+     * When `granted === 0` it commits without writing, so a filter that asked at a
+     * full cap does not leave behind a row that a later reader could mistake for
+     * spend (AC #7).
+     */
+    reserveDispatches(filterId, day, requested, capPerDay) {
+        this.reserveBudgetStmt ?? (this.reserveBudgetStmt = this.db.prepare(`INSERT INTO ingestion_dispatch_budget (filter_id, day, dispatched)
+       VALUES (?, ?, ?)
+       ON CONFLICT(filter_id, day) DO UPDATE SET
+         dispatched = dispatched + excluded.dispatched`));
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            const used = this.readDispatched(filterId, day);
+            const granted = Math.max(0, Math.min(Math.trunc(requested), Math.trunc(capPerDay) - used));
+            if (granted > 0) {
+                // STRICT table: bind an integer, never a float. `Math.trunc` above is
+                // the boundary guard; `CapLimiter` has already rejected a fractional
+                // `capPerDay` outright (AC #13).
+                this.reserveBudgetStmt.run(filterId, day, granted);
+            }
+            this.db.exec("COMMIT");
+            return granted;
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    /**
+     * Hand `count` of the day's spend back, clamped at zero.
+     *
+     * `UPDATE` and never `INSERT`: releasing against a filter with no row today is
+     * a no-op, because a refund of budget that was never reserved is a caller bug,
+     * and materializing a `dispatched = 0` row to record it would make the absent
+     * row and the zero row distinguishable to a later reader for no gain.
+     */
+    releaseDispatches(filterId, day, count) {
+        if (!Number.isFinite(count) || count <= 0)
+            return;
+        this.releaseBudgetStmt ?? (this.releaseBudgetStmt = this.db.prepare(`UPDATE ingestion_dispatch_budget
+          SET dispatched = max(0, dispatched - ?)
+        WHERE filter_id = ? AND day = ?`));
+        this.releaseBudgetStmt.run(Math.trunc(count), filterId, day);
+    }
+    /**
+     * Record what a source read found, on the ONE row that already exists.
+     *
+     * THREE prepared statements, and which one runs is decided by `mapVerdict`
+     * rather than by a `switch` written here. That indirection is the point:
+     * `verdict-mapping.ts` is the single place that says what a verdict may do to
+     * a row, and a second opinion expressed as a `case` in this file is exactly
+     * how the two would come to disagree - quietly, in the direction of closing
+     * something nobody handled.
+     *
+     * The split across three statements is a safety property rather than an
+     * optimisation, because each statement's SQL TEXT enforces one invariant:
+     *
+     *   - `pending` names `verified_at`, `verified_verdict`,
+     *     `reconcile_attempted_at` and `reconcile_fail_count = 0`. It does NOT
+     *     name `verified_signature`, so a successful read that found the artifact
+     *     still open cannot blank the evidence of an earlier close. There is no
+     *     signature to write: nothing happened.
+     *   - the CLOSING statement (`handled-elsewhere`, `artifact-gone`) is the only
+     *     one that names `verified_signature`, because a close is the only outcome
+     *     that carries evidence.
+     *   - the `unreachable` statement names ONLY `reconcile_attempted_at` and
+     *     `reconcile_fail_count`. It cannot advance `verified_at` because
+     *     `verified_at` is not in its SQL. That is epic D4's "leaves untouched"
+     *     enforced by construction, not by a test remembering to check, and not by
+     *     a runtime branch somebody can later reorder.
+     *
+     * Why the last one matters: `unreachable` means paseo could not look. Letting
+     * a failed read refresh the verification 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.
+     *
+     * `reconcile_fail_count = reconcile_fail_count + 1` in SQL rather than a
+     * read-modify-write in TypeScript, so two concurrent unreachable reads for the
+     * same item cannot lose an increment. The service's single-flight map makes
+     * that unlikely; the SQL makes it impossible.
+     *
+     * No statement touches `fail_count`, `last_fail_at` or `fail_sig` - Epic 3's
+     * DISPATCH counters. A source paseo cannot read is not an item that failed to
+     * dispatch, and burning the dispatch backoff on a network condition would park
+     * a perfectly good item (epic D5).
+     *
+     * An unknown `(filterId, itemKey)` updates ZERO rows and does not insert.
+     * Verification decorates an item the ledger already ingested; minting a row
+     * here would create an item nobody ever saw.
+     */
+    recordVerification(filterId, itemKey, input) {
+        // Before anything is bound. A credential-shaped signature must never reach
+        // the driver, let alone the file.
+        assertSafeSignature(input.signature);
+        // STRICT table: bind an integer, never a Date and never a float.
+        const now = this.now().getTime();
+        const policy = mapVerdict(input.verdict);
+        if (policy.incrementsReconcileFailCount) {
+            this.unreachableVerificationStmt ?? (this.unreachableVerificationStmt = this.db.prepare(`UPDATE ingestion_items
+            SET reconcile_attempted_at = ?,
+                reconcile_fail_count = reconcile_fail_count + 1
+          WHERE filter_id = ? AND item_key = ?`));
+            this.unreachableVerificationStmt.run(now, filterId, itemKey);
+            return;
+        }
+        if (policy.writesSignature) {
+            this.closeVerificationStmt ?? (this.closeVerificationStmt = this.db.prepare(`UPDATE ingestion_items
+            SET verified_at = ?,
+                verified_verdict = ?,
+                verified_signature = ?,
+                reconcile_attempted_at = ?
+          WHERE filter_id = ? AND item_key = ?`));
+            this.closeVerificationStmt.run(now, input.verdict, input.signature, now, filterId, itemKey);
+            return;
+        }
+        this.stampVerificationStmt ?? (this.stampVerificationStmt = this.db.prepare(`UPDATE ingestion_items
+          SET verified_at = ?,
+              verified_verdict = ?,
+              reconcile_attempted_at = ?,
+              reconcile_fail_count = 0
+        WHERE filter_id = ? AND item_key = ?`));
+        this.stampVerificationStmt.run(now, input.verdict, now, filterId, itemKey);
+    }
+    /** The five verification columns for one item, or undefined when the row is absent. */
+    getVerification(filterId, itemKey) {
+        this.getVerificationStmt ?? (this.getVerificationStmt = this.db.prepare(`SELECT verified_at, verified_verdict, verified_signature,
+              reconcile_attempted_at, reconcile_fail_count
+         FROM ingestion_items
+        WHERE filter_id = ? AND item_key = ?`));
+        const row = this.getVerificationStmt.get(filterId, itemKey);
+        return row ? this.toVerificationState(row) : undefined;
+    }
+    /**
+     * Recent rows for one filter with their verification state, newest first.
+     *
+     * Same `ORDER BY last_seen_at DESC` as `listForFilter` and for the same
+     * reason: it rides `idx_ingestion_items_filter_seen` instead of sorting a
+     * scan. This is the read half of the `ingestion/runs` RPC; the join against
+     * `ScheduleRun` happens in `run-projection.ts`, which is pure.
+     */
+    listRunViewRows(filterId, limit) {
+        this.runViewStmt ?? (this.runViewStmt = this.db.prepare(`SELECT item_key, last_run_id, agent_id, fail_count, last_fail_at,
+              verified_at, verified_verdict, verified_signature,
+              reconcile_attempted_at, reconcile_fail_count
+         FROM ingestion_items
+        WHERE filter_id = ?
+        ORDER BY last_seen_at DESC
+        LIMIT ?`));
+        const rows = [];
+        for (const row of this.runViewStmt.all(filterId, limit)) {
+            const failCount = asNumber(row.fail_count) ?? 0;
+            const lastFailAt = asNumber(row.last_fail_at);
+            const verification = this.toVerificationState(row);
+            rows.push({
+                verifiedAt: verification.verifiedAt,
+                verdict: verification.verdict,
+                verifiedSignature: verification.verifiedSignature,
+                reconcileAttemptedAt: verification.reconcileAttemptedAt,
+                reconcileFailCount: verification.reconcileFailCount,
+                itemKey: asString(row.item_key) ?? "",
+                lastRunId: asString(row.last_run_id),
+                agentId: asString(row.agent_id),
+                failCount,
+                // Through the ONE helper, never a second derivation. `backoffUntil`
+                // needs a full LedgerEntry, so the two fields it actually reads are
+                // handed to it on a minimal object rather than re-implementing
+                // `lastFailAt + BACKOFF_COOLDOWN_MS` here, where it could drift.
+                backoffUntil: backoffUntil({ ...EMPTY_ENTRY, failCount, lastFailAt }),
+            });
+        }
+        return rows;
+    }
+    /**
+     * Narrow one row's verification columns.
+     *
+     * `verified_verdict` is re-validated against the protocol enum on the way OUT
+     * of the database, not just on the way in. A hand-edited file, a restored
+     * backup, or a database written by a FUTURE paseo that added a fifth verdict
+     * would otherwise put an unknown string on the wire and fail the client's own
+     * parse - turning a stale row into a blank screen. An unparseable value reads
+     * as `null` ("nobody has looked") and says so once at `warn`.
+     */
+    toVerificationState(row) {
+        const raw = asString(row.verified_verdict);
+        let verdict = null;
+        if (raw !== null) {
+            const parsed = ReconcileVerdictSchema.safeParse(raw);
+            if (parsed.success) {
+                verdict = parsed.data;
+            }
+            else {
+                // Loud once per process per value, quiet after: a corrupted column would
+                // otherwise emit one line per row per render.
+                this.warnUnknownVerdictOnce(raw);
+            }
+        }
+        return {
+            verifiedAt: asNumber(row.verified_at),
+            verdict,
+            verifiedSignature: asString(row.verified_signature),
+            reconcileAttemptedAt: asNumber(row.reconcile_attempted_at),
+            reconcileFailCount: asNumber(row.reconcile_fail_count) ?? 0,
+        };
+    }
+    warnUnknownVerdictOnce(raw) {
+        if (this.warnedVerdicts.has(raw))
+            return;
+        this.warnedVerdicts.add(raw);
+        this.warn(`[ingestion-ledger] ${this.dbPath} holds an unrecognised verified_verdict; reading it as null.`);
+    }
+    /** Close the connection so WAL sidecars are checkpointed away. */
+    close() {
+        this.db.close();
+    }
+}
+//# sourceMappingURL=ledger.js.map