@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/ingestion/ledger.d.ts

@@ -0,0 +1,562 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { IngestionItemState } from "@hyperdrive.bot/fleet-protocol/ingestion/types";
+import { type ReconcileVerdict } from "@hyperdrive.bot/fleet-protocol/ingestion/run-view";
+/**
+ * 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 declare class IngestionLedgerUnavailableError extends Error {
+    /** The path that could not be opened, carried structurally so a caller never regexes the message. */
+    readonly dbPath: string;
+    constructor(dbPath: string, options?: {
+        cause?: unknown;
+    });
+}
+/** One `ingestion_items` row, narrowed from sqlite's `Record<string, unknown>`. */
+export interface LedgerEntry {
+    filterId: string;
+    itemKey: string;
+    contentHash: string | null;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    handledAt: number | null;
+    outcome: string | null;
+    failCount: number;
+    lastFailAt: number | null;
+    failSig: string | null;
+    alertedOn: string | null;
+    claimedAt: number | null;
+    claimRunId: string | null;
+    agentId: string | null;
+    meta: string | null;
+}
+/** The freshness inputs for one item on one pass. */
+export interface FreshnessInput {
+    /** Did the filter's own predicate say this item is worth acting on at all? */
+    actionable: boolean;
+    /** Hash of the item's current content. `null` when the source gave us nothing to hash. */
+    contentHash: string | null;
+}
+/**
+ * The non-credential metadata worth remembering about an item.
+ *
+ * This is an ALLOW-LIST, and the allow-list is the security control: `touch()`
+ * copies these five keys by name and nothing else, so an aggregator payload
+ * that happens to carry `access_token` or an `authorization` header cannot ride
+ * into the ledger by being spread into it. Widening this interface is a
+ * deliberate act; spreading a caller's object never is.
+ */
+export interface LedgerItemMeta {
+    sourceId?: string;
+    subject?: string;
+    url?: string;
+    groupKey?: string;
+    receivedAt?: string;
+}
+export interface IngestionLedgerOptions {
+    /** Injected, never re-derived. The caller owns where the home directory is. */
+    paseoHome: string;
+    /** Mirrors `ScheduleService.now` so tests can pin the clock. */
+    now?: () => Date;
+    /**
+     * Where the "this column holds something I cannot parse" warning goes.
+     *
+     * A sink rather than a pino logger, following `spawn-config-writer.ts:271`:
+     * this class is constructed in tests that have no logger and in a bootstrap
+     * path that does, and the one line it ever emits does not justify threading
+     * pino through either. Defaults to `console.warn`.
+     */
+    warn?: (message: string) => void;
+}
+/**
+ * Options for `claim()`.
+ *
+ * A claim is ITEM-level dedupe. It is NOT a process lock:
+ * `ScheduleService.runningScheduleIds` and `agentManager.hasInFlightRun` remain
+ * the process-level single-flight and are unchanged by this file.
+ */
+export interface ClaimOptions {
+    /** The `ScheduleRun` id this dispatch belongs to (the `randomUUID()` minted in `schedule/service.ts`). */
+    runId: string;
+    agentId?: string | null;
+}
+/** Options for `mark()`. Deliberately closed: there is no `meta` here (see `mark`). */
+export interface MarkOptions {
+    /**
+     * Required, with no default on purpose: the dispatch site must never be able
+     * to record an item as handled without saying what happened to it.
+     */
+    outcome: string;
+    /** `undefined` PRESERVES the stored hash, matching `ledger.mjs:52`'s `if (contentHash != null)`. */
+    contentHash?: string | null;
+    agentId?: string | null;
+}
+/** Options for `recordFailure()`. */
+export interface RecordFailureOptions {
+    /**
+     * The failure's short signature, normally `hardFailureSig(log)`.
+     *
+     * `null` or `undefined` PRESERVES the stored signature rather than clearing
+     * it, matching `ledger.mjs:66`'s `if (sig) e.failSig = sig`. Only a
+     * successful `mark()` clears it.
+     */
+    sig?: string | null;
+}
+/**
+ * What one recorded failure means for the item and for the rest of the tick.
+ *
+ * Returned rather than `void` so the dispatch loop never has to re-read the row
+ * and re-derive the window: everything a caller needs to decide "skip this
+ * item" and "stop this tick" is here, computed once, from the state that was
+ * actually committed.
+ */
+export interface FailureOutcome {
+    /** Post-increment, so the first failure of a never-seen item reports 1. */
+    failCount: number;
+    /** Epoch ms of this failure, from the injected clock. */
+    lastFailAt: number;
+    /** The signature now stored - this failure's, or a prior one's when `sig` was null. */
+    failSig: string | null;
+    /** Epoch ms the backoff window expires, or null while below the threshold. */
+    backoffUntil: number | null;
+    /** Did THIS failure carry one of the eight hard-failure signatures? */
+    hardFailure: boolean;
+    /** True only when this call actually CLAIMED today for (filterId, sig) in the database. */
+    shouldAlert: boolean;
+    /**
+     * Stop dispatching the remaining items in this tick.
+     *
+     * Always `=== hardFailure`, including for a hard failure whose alert was
+     * suppressed because the day was already claimed. `inbox-watcher/run.sh:113`
+     * dedupes `alert_once` and never dedupes the `break`; suppressing the alert
+     * must never suppress the abort.
+     */
+    abortTick: boolean;
+}
+export interface ReleaseStaleClaimsOptions {
+    /**
+     * Run ids still executing, which must keep their claims. Empty at daemon
+     * boot, by definition - nothing is in flight in a process that just started.
+     */
+    inFlightRunIds?: ReadonlySet<string>;
+}
+/**
+ * Epic 6's verification columns for one item, read back.
+ *
+ * Every field is independently nullable and none of them is defaulted on read.
+ * `verdict: null` means NOBODY HAS LOOKED - it is not "pending". Collapsing the
+ * two would be the exact "record intent as fact" mistake this epic exists to
+ * fix, one level down: a row nobody verified would render identically to a row
+ * somebody verified and found still open.
+ *
+ * `reconcileFailCount` is the one non-nullable member, because a counter's
+ * identity is zero rather than unknown (see `RECONCILE_COLUMNS_V3`).
+ */
+export interface VerificationState {
+    /** Epoch ms of the last verdict allowed to STAMP. An `unreachable` read never advances it. */
+    verifiedAt: number | null;
+    verdict: ReconcileVerdict | null;
+    verifiedSignature: string | null;
+    /** Epoch ms of the last read ATTEMPT, successful or not. Advanced by every verdict. */
+    reconcileAttemptedAt: number | null;
+    reconcileFailCount: number;
+}
+/**
+ * One ledger row as the `ingestion/runs` projection needs it: the verification
+ * columns plus the Epic 3 fields the run view carries.
+ *
+ * `backoffUntil` here is Epic 3's DISPATCH window, derived through the one
+ * `backoffUntil(entry)` helper above and never re-derived. It is NOT the
+ * reconcile backoff - see decision D-6.1-D. The two counters travel side by
+ * side (`failCount` vs `reconcileFailCount`) precisely so a consumer cannot
+ * read one and believe it is the other.
+ */
+export interface RunViewRow extends VerificationState {
+    itemKey: string;
+    /**
+     * `last_run_id`: the run that produced this row, for as long as the row lives.
+     *
+     * NOT `claim_run_id`, and the distinction is the whole reason v4 exists.
+     * `claim_run_id` means "the run holding the claim right now", so `mark()`
+     * nulls it the moment the agent finishes and `releaseStaleClaims()` nulls it
+     * on the next boot. Joining the Inbox on it meant a HANDLED item - the only
+     * kind the Inbox is about - never matched a run, and a restart emptied the
+     * list outright.
+     */
+    lastRunId: string | null;
+    agentId: string | null;
+    /** Epic 3's DISPATCH failure counter. Never touched by a reconcile read (epic D5). */
+    failCount: number;
+    backoffUntil: number | null;
+}
+/**
+ * The narrow view of the ledger that `ScheduleService` depends on.
+ *
+ * Kept structural so `schedule/service.ts` imports a TYPE and never the
+ * concrete class: a `node:sqlite` failure therefore cannot break `service.ts`
+ * module resolution, and clock schedules keep ticking on a host where the
+ * ledger cannot open at all.
+ */
+export interface IngestionLedgerMaintenance {
+    releaseStaleClaims(options?: ReleaseStaleClaimsOptions): number;
+    prune(days?: number): number;
+}
+/**
+ * The day's dispatch budget, as `CapLimiter` sees it.
+ *
+ * Structural on purpose, and narrow on purpose: `CapLimiter` holds one of these
+ * and nothing else, which is what keeps `cap-limiter.ts` free of `node:sqlite`,
+ * of `DatabaseSync`, and of any knowledge of where the home directory is. All
+ * three methods take an already-computed `day` key rather than a clock, because
+ * the limiter owns the clock and calls it exactly once per admit - a store that
+ * re-derived the day could straddle a midnight the limiter had already resolved.
+ */
+export interface CapBudgetStore {
+    readDispatched(filterId: string, day: string): number;
+    reserveDispatches(filterId: string, day: string, requested: number, capPerDay: number): number;
+    releaseDispatches(filterId: string, day: string, count: number): void;
+}
+/**
+ * `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 declare const DAEMON_RESTART_FAIL_SIG = "daemon-restart";
+/**
+ * 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 declare function contentChanged(entry: LedgerEntry | undefined, contentHash: string | null): boolean;
+/**
+ * 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 declare function inBackoff(entry: LedgerEntry | undefined, now: number): boolean;
+export declare function backoffUntil(entry: LedgerEntry): number | null;
+export declare class IngestionLedger implements CapBudgetStore {
+    private readonly db;
+    private readonly now;
+    private readonly warn;
+    /** Values already complained about, so a corrupted column is loud once, not once per row. */
+    private readonly warnedVerdicts;
+    /** The resolved absolute path, surfaced for diagnostics and asserted by tests. */
+    readonly dbPath: string;
+    private getStmt;
+    private touchStmt;
+    private listStmt;
+    private claimInsertStmt;
+    private claimUpdateStmt;
+    private markInsertStmt;
+    private markUpdateStmt;
+    private recordFailureStmt;
+    private alertClaimedStmt;
+    private claimAlertStmt;
+    private selectClaimedStmt;
+    private releaseClaimStmt;
+    private pruneStmt;
+    private pruneBudgetStmt;
+    private readBudgetStmt;
+    private reserveBudgetStmt;
+    private releaseBudgetStmt;
+    /** `pending`: stamps, resets the counter, and never names `verified_signature`. */
+    private stampVerificationStmt;
+    /** The two CLOSING verdicts: the only statement that names `verified_signature`. */
+    private closeVerificationStmt;
+    /** `unreachable`: names neither `verified_at` nor `verified_verdict`, by construction. */
+    private unreachableVerificationStmt;
+    private getVerificationStmt;
+    private runViewStmt;
+    constructor(options: IngestionLedgerOptions);
+    /**
+     * 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(): DatabaseSync;
+    /** One row, or undefined when this (filter, item) has never been seen. */
+    get(filterId: string, itemKey: string): LedgerEntry | 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: LedgerEntry | undefined, input: FreshnessInput): boolean;
+    /**
+     * 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: string, itemKey: string, meta?: LedgerItemMeta): void;
+    /**
+     * 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: string, limit: number): IngestionItemState[];
+    /**
+     * 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: string, itemKey: string, options: ClaimOptions): boolean;
+    /**
+     * 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: string, itemKey: string, options: MarkOptions): void;
+    /**
+     * 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: string, sig: string, now: Date): boolean;
+    /**
+     * 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: string, itemKey: string, options?: RecordFailureOptions): FailureOutcome;
+    /**
+     * 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?: ReleaseStaleClaimsOptions): number;
+    /**
+     * 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?: number): number;
+    /**
+     * 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: string, day: string): number;
+    /**
+     * 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: string, day: string, requested: number, capPerDay: number): number;
+    /**
+     * 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: string, day: string, count: number): void;
+    /**
+     * 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: string, itemKey: string, input: {
+        verdict: ReconcileVerdict;
+        signature: string | null;
+    }): void;
+    /** The five verification columns for one item, or undefined when the row is absent. */
+    getVerification(filterId: string, itemKey: string): VerificationState | 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: string, limit: number): RunViewRow[];
+    /**
+     * 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`.
+     */
+    private toVerificationState;
+    private warnUnknownVerdictOnce;
+    /** Close the connection so WAL sidecars are checkpointed away. */
+    close(): void;
+}
+//# sourceMappingURL=ledger.d.ts.map