@hyperdrive.bot/fleet-server 0.3.99

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

@@ -0,0 +1,38 @@
+import type { SourceStatus, StoredSource } from "@hyperdrive.bot/fleet-protocol/ingestion/types";
+import type { SourceGateway, SourceKind } from "./types.js";
+/**
+ * What `checkSource` needs from the world.
+ *
+ * `now` is injected rather than read from the clock so a caller's tests are
+ * hermetic; the gateway is resolved through a function rather than passed
+ * directly so one sweep can span sources of different kinds without the caller
+ * pre-grouping them.
+ */
+export interface HealthDeps {
+    resolveGateway(kind: SourceKind): SourceGateway;
+    externalUserId: string;
+    now(): Date;
+}
+/** The decision returned by a health check. Deliberately not a StoredSource patch. */
+export interface SourceHealth {
+    status: SourceStatus;
+    lastError: string | null;
+}
+/**
+ * The ONE health implementation for a connected source.
+ *
+ * It is a pure decision function: it asks the gateway what accounts exist and
+ * maps the answer onto a status. It performs NO writes. Both the `source/check`
+ * RPC and the background sweep call this and then persist through the single
+ * private method on IngestionService, so there is exactly one notion of what
+ * "healthy" means and exactly one place that records it. A second liveness
+ * check added elsewhere is a defect, not an optimization.
+ *
+ * `lastError` always carries an error CODE, never a thrown message. That field
+ * is persisted to disk and returned on the wire, and an aggregator's error body
+ * is text we did not write which can echo request context, so interpolating it
+ * is the exact mechanism by which a header value ends up in a JSON file nobody
+ * can trace back to a commit.
+ */
+export declare function checkSource(source: StoredSource, deps: HealthDeps): Promise<SourceHealth>;
+//# sourceMappingURL=health.d.ts.map

package/dist/server/server/ingestion/health.js

@@ -0,0 +1,90 @@
+import { IngestionError } from "./errors.js";
+/**
+ * How each aggregator failure maps onto a source status.
+ *
+ * A `Record<IngestionErrorCode, ...>` rather than a switch, matching
+ * `SOURCE_ADAPTERS` in adapters.ts and for the same reason: a code added to
+ * INGESTION_ERROR_CODES without a mapping here fails to satisfy the record and
+ * breaks the build, instead of silently falling through to a default that
+ * quietly mislabels a revoked source as degraded.
+ *
+ * The split is "can the user fix this by re-authorizing?". A rejected platform
+ * credential and a resource deleted upstream are terminal for this source, so
+ * they read `revoked`. Everything else is a transient or operator-side fault
+ * the next sweep may clear, so it reads `degraded`.
+ */
+const ERROR_CODE_STATUS = {
+    PIPEDREAM_OFF: "degraded",
+    COMPOSIO_OFF: "degraded",
+    COMPOSIO_NEEDS_SETUP: "degraded",
+    PIPEDREAM_OFFLINE: "degraded",
+    PIPEDREAM_AUTH: "revoked",
+    COMPOSIO_OFFLINE: "degraded",
+    COMPOSIO_AUTH: "revoked",
+    COMPOSIO_ERROR: "degraded",
+    SOURCE_GONE: "revoked",
+    SOURCE_ERROR: "degraded",
+    // The 404 pair cannot arise from a health check: `checkSource` is only ever
+    // called with a source record that was just read off disk, so "no such
+    // source" and "no such filter" are unreachable here. They are mapped anyway
+    // rather than excluded from the type, because the record's whole job is to
+    // make the code set exhaustive at compile time - an exclusion would reopen
+    // the hole it exists to close. `degraded` and not `revoked`: if one ever did
+    // arrive, it would mean a local record went missing, which re-authorizing
+    // cannot fix and which the next sweep may well find restored.
+    FILTER_MISSING: "degraded",
+    SOURCE_MISSING: "degraded",
+};
+/**
+ * The ONE health implementation for a connected source.
+ *
+ * It is a pure decision function: it asks the gateway what accounts exist and
+ * maps the answer onto a status. It performs NO writes. Both the `source/check`
+ * RPC and the background sweep call this and then persist through the single
+ * private method on IngestionService, so there is exactly one notion of what
+ * "healthy" means and exactly one place that records it. A second liveness
+ * check added elsewhere is a defect, not an optimization.
+ *
+ * `lastError` always carries an error CODE, never a thrown message. That field
+ * is persisted to disk and returned on the wire, and an aggregator's error body
+ * is text we did not write which can echo request context, so interpolating it
+ * is the exact mechanism by which a header value ends up in a JSON file nobody
+ * can trace back to a commit.
+ */
+export async function checkSource(source, deps) {
+    // Resolved OUTSIDE the try on purpose. The resolver is a local synchronous
+    // factory, so a throw here is a wiring fault in this daemon, not an
+    // aggregator fault. Classifying it as "the source is degraded" would be a
+    // false diagnosis that sends the next reader to debug Gmail. Letting it
+    // propagate is what gives the sweep's Promise.allSettled a rejected entry to
+    // log and skip.
+    const gateway = deps.resolveGateway(source.kind);
+    try {
+        const accounts = await gateway.listAccounts(deps.externalUserId, source.appSlug);
+        if (accounts.length === 0) {
+            return { status: "revoked", lastError: "account_not_found" };
+        }
+        if (source.externalAccountId !== null) {
+            const known = accounts.find((account) => account.id === source.externalAccountId);
+            if (!known) {
+                // The account we recorded is gone upstream, even though others remain.
+                return { status: "revoked", lastError: "account_not_found" };
+            }
+            return known.status === "active"
+                ? { status: "active", lastError: null }
+                : { status: "degraded", lastError: "account_inactive" };
+        }
+        return accounts.some((account) => account.status === "active")
+            ? { status: "active", lastError: null }
+            : { status: "degraded", lastError: "account_inactive" };
+    }
+    catch (error) {
+        if (error instanceof IngestionError) {
+            return { status: ERROR_CODE_STATUS[error.code], lastError: error.code };
+        }
+        // Not an IngestionError, so the message is unclassified text of unknown
+        // provenance. Record a sentinel and drop the message on the floor.
+        return { status: "degraded", lastError: "check_failed" };
+    }
+}
+//# sourceMappingURL=health.js.map

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

@@ -0,0 +1,99 @@
+import type { DatabaseSync } from "node:sqlite";
+/**
+ * Bump when the DDL below changes in a way an existing file cannot satisfy.
+ * Mirrors `INDEX_SCHEMA_VERSION` in `search/index-store.ts`, but the handling
+ * differs: the search index is a derived cache that can be rebuilt, whereas
+ * this ledger is the daemon's only memory of what it already dispatched. A
+ * future version bump must MIGRATE, never `DELETE FROM`.
+ *
+ * Version history:
+ *   v1 (Story 3.1) `ingestion_items` + `ingestion_dispatch_budget`
+ *   v2 (Story 5.4) `ingestion_cohorts` + `ingestion_cohort_groups`
+ *   v3 (Story 6.1) the five RECONCILE columns on `ingestion_items` -
+ *                  `verified_at`, `verified_verdict`, `verified_signature`,
+ *                  `reconcile_attempted_at`, `reconcile_fail_count`
+ *
+ * v1 and v2 are additive `CREATE TABLE IF NOT EXISTS`. v3 is the first version
+ * that has to ALTER an existing populated table, which is why it gets its own
+ * `migrateToV3` step with a `table_info` guard rather than a bare `ALTER`.
+ */
+export declare const LEDGER_SCHEMA_VERSION = 4;
+/** Consecutive failures before an item is parked. Written by Story 3.3. */
+export declare const BACKOFF_THRESHOLD = 3;
+/** How long a parked item stays parked: 6h, so a bad item gets ~4 shots a day, not 116. */
+export declare const BACKOFF_COOLDOWN_MS = 21600000;
+/** Rows untouched for this long are prunable. The pruner itself is Story 3.2. */
+export declare const LEDGER_PRUNE_DAYS = 30;
+/**
+ * THE v3 COLUMN SET - reconciliation's five columns on `ingestion_items`.
+ *
+ * Additive `ALTER TABLE ... ADD COLUMN` only. Nothing in this file drops a
+ * table or a column, builds a shadow table to copy rows into, or deletes from
+ * `ingestion_items`: the ledger is the daemon's only memory of what it already
+ * dispatched, so a migration that rewrote it would trade a schema change for a
+ * night of duplicate outward artifacts. `ledger-schema.test.ts` asserts that
+ * STATICALLY, by scanning this file's own source for the five destructive SQL
+ * forms - which is why this comment describes them in prose rather than
+ * spelling them, since a grep gate cannot tell a warning from an instruction.
+ *
+ * `reconcile_fail_count` carries `NOT NULL DEFAULT 0` while the other four are
+ * nullable, for two independent reasons that happen to agree:
+ *   - sqlite REQUIRES a non-null default to add a `NOT NULL` column to a table
+ *     that already has rows; without it the ALTER throws
+ *   - a counter's identity IS zero. "This item has failed no reconcile reads"
+ *     is a fact, not an absence. A timestamp's absence is genuinely unknown -
+ *     `verified_at NULL` means "never verified", which must never render as
+ *     "verified at the epoch".
+ *
+ * Named as data rather than inlined so `migrateToV3` can diff it against
+ * `PRAGMA table_info` and add only what is missing: sqlite has no
+ * `ADD COLUMN IF NOT EXISTS`, so re-running a bare ALTER throws
+ * `duplicate column name`.
+ */
+export declare const RECONCILE_COLUMNS_V3: readonly [{
+    readonly name: "verified_at";
+    readonly ddl: "ALTER TABLE ingestion_items ADD COLUMN verified_at INTEGER";
+}, {
+    readonly name: "verified_verdict";
+    readonly ddl: "ALTER TABLE ingestion_items ADD COLUMN verified_verdict TEXT";
+}, {
+    readonly name: "verified_signature";
+    readonly ddl: "ALTER TABLE ingestion_items ADD COLUMN verified_signature TEXT";
+}, {
+    readonly name: "reconcile_attempted_at";
+    readonly ddl: "ALTER TABLE ingestion_items ADD COLUMN reconcile_attempted_at INTEGER";
+}, {
+    readonly name: "reconcile_fail_count";
+    readonly ddl: "ALTER TABLE ingestion_items ADD COLUMN reconcile_fail_count INTEGER NOT NULL DEFAULT 0";
+}];
+/**
+ * The v4 column, added by Story 6.2 because the v3 join did not survive contact
+ * with the item lifecycle.
+ *
+ * `claim_run_id` names the run CURRENTLY holding the claim, so `mark()` and
+ * `releaseStaleClaims()` both null it - correctly, for what that column means.
+ * But the `ingestion/runs` projection joined on it, and the population the Inbox
+ * is actually about is HANDLED items: an item whose agent finished has
+ * `claim_run_id IS NULL`, so it never joined, so it was never reconciled, and
+ * after any daemon restart `releaseStaleClaims()` nulled the rest. The Inbox
+ * could only ever have shown rows whose dispatch was still in flight in this
+ * process.
+ *
+ * `last_run_id` is the same value with a different lifetime: written beside
+ * `claim_run_id` on `claim()`, and never cleared by anything. The two are
+ * deliberately separate columns rather than one repurposed column, because they
+ * answer different questions - "who holds this now?" drives release, "which run
+ * produced this row?" drives the projection - and collapsing them would make
+ * `releaseStaleClaims()` unable to tell a live claim from a finished one.
+ */
+export declare const RUN_ID_COLUMNS_V4: readonly [{
+    readonly name: "last_run_id";
+    readonly ddl: "ALTER TABLE ingestion_items ADD COLUMN last_run_id TEXT";
+}];
+/**
+ * Bring `db` up to `LEDGER_SCHEMA_VERSION`. Idempotent: every statement is
+ * `IF NOT EXISTS` or guarded by a `PRAGMA table_info` diff, so a second call
+ * against an already-provisioned database is a no-op that destroys no rows.
+ */
+export declare function ensureSchema(db: DatabaseSync): void;
+//# sourceMappingURL=ledger-schema.d.ts.map

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

@@ -0,0 +1,359 @@
+// Schema for the ingestion ledger: one row per (filter, item) the daemon has
+// ever laid eyes on, in the `paseo.sqlite` file under the daemon's home
+// directory (injected by the caller, never re-derived here).
+//
+// The whole point of this table is a single question - "is this item fresh?" -
+// answered from durable storage rather than process memory, so a daemon restart
+// does not re-dispatch a night's worth of already-handled items.
+//
+// Ownership of the columns is split across three stories on purpose, and the
+// full table is created here so neither later story needs a migration:
+//   Story 3.1 (this one) WRITES first_seen_at, last_seen_at, content_hash, meta
+//   Story 3.2            WRITES handled_at, outcome, claimed_at, claim_run_id, agent_id
+//   Story 3.3            WRITES fail_count, last_fail_at, fail_sig, alerted_on
+// Writing handled_at/outcome here would silently defeat 3.2's "mark only after
+// success" guarantee, so this story leaves them null.
+/**
+ * Bump when the DDL below changes in a way an existing file cannot satisfy.
+ * Mirrors `INDEX_SCHEMA_VERSION` in `search/index-store.ts`, but the handling
+ * differs: the search index is a derived cache that can be rebuilt, whereas
+ * this ledger is the daemon's only memory of what it already dispatched. A
+ * future version bump must MIGRATE, never `DELETE FROM`.
+ *
+ * Version history:
+ *   v1 (Story 3.1) `ingestion_items` + `ingestion_dispatch_budget`
+ *   v2 (Story 5.4) `ingestion_cohorts` + `ingestion_cohort_groups`
+ *   v3 (Story 6.1) the five RECONCILE columns on `ingestion_items` -
+ *                  `verified_at`, `verified_verdict`, `verified_signature`,
+ *                  `reconcile_attempted_at`, `reconcile_fail_count`
+ *
+ * v1 and v2 are additive `CREATE TABLE IF NOT EXISTS`. v3 is the first version
+ * that has to ALTER an existing populated table, which is why it gets its own
+ * `migrateToV3` step with a `table_info` guard rather than a bare `ALTER`.
+ */
+export const LEDGER_SCHEMA_VERSION = 4;
+/** Consecutive failures before an item is parked. Written by Story 3.3. */
+export const BACKOFF_THRESHOLD = 3;
+/** How long a parked item stays parked: 6h, so a bad item gets ~4 shots a day, not 116. */
+export const BACKOFF_COOLDOWN_MS = 21600000;
+/** Rows untouched for this long are prunable. The pruner itself is Story 3.2. */
+export const LEDGER_PRUNE_DAYS = 30;
+/**
+ * THE v3 COLUMN SET - reconciliation's five columns on `ingestion_items`.
+ *
+ * Additive `ALTER TABLE ... ADD COLUMN` only. Nothing in this file drops a
+ * table or a column, builds a shadow table to copy rows into, or deletes from
+ * `ingestion_items`: the ledger is the daemon's only memory of what it already
+ * dispatched, so a migration that rewrote it would trade a schema change for a
+ * night of duplicate outward artifacts. `ledger-schema.test.ts` asserts that
+ * STATICALLY, by scanning this file's own source for the five destructive SQL
+ * forms - which is why this comment describes them in prose rather than
+ * spelling them, since a grep gate cannot tell a warning from an instruction.
+ *
+ * `reconcile_fail_count` carries `NOT NULL DEFAULT 0` while the other four are
+ * nullable, for two independent reasons that happen to agree:
+ *   - sqlite REQUIRES a non-null default to add a `NOT NULL` column to a table
+ *     that already has rows; without it the ALTER throws
+ *   - a counter's identity IS zero. "This item has failed no reconcile reads"
+ *     is a fact, not an absence. A timestamp's absence is genuinely unknown -
+ *     `verified_at NULL` means "never verified", which must never render as
+ *     "verified at the epoch".
+ *
+ * Named as data rather than inlined so `migrateToV3` can diff it against
+ * `PRAGMA table_info` and add only what is missing: sqlite has no
+ * `ADD COLUMN IF NOT EXISTS`, so re-running a bare ALTER throws
+ * `duplicate column name`.
+ */
+export const RECONCILE_COLUMNS_V3 = [
+    { name: "verified_at", ddl: "ALTER TABLE ingestion_items ADD COLUMN verified_at INTEGER" },
+    {
+        name: "verified_verdict",
+        ddl: "ALTER TABLE ingestion_items ADD COLUMN verified_verdict TEXT",
+    },
+    {
+        name: "verified_signature",
+        ddl: "ALTER TABLE ingestion_items ADD COLUMN verified_signature TEXT",
+    },
+    {
+        name: "reconcile_attempted_at",
+        ddl: "ALTER TABLE ingestion_items ADD COLUMN reconcile_attempted_at INTEGER",
+    },
+    {
+        name: "reconcile_fail_count",
+        ddl: "ALTER TABLE ingestion_items ADD COLUMN reconcile_fail_count INTEGER NOT NULL DEFAULT 0",
+    },
+];
+/**
+ * The v4 column, added by Story 6.2 because the v3 join did not survive contact
+ * with the item lifecycle.
+ *
+ * `claim_run_id` names the run CURRENTLY holding the claim, so `mark()` and
+ * `releaseStaleClaims()` both null it - correctly, for what that column means.
+ * But the `ingestion/runs` projection joined on it, and the population the Inbox
+ * is actually about is HANDLED items: an item whose agent finished has
+ * `claim_run_id IS NULL`, so it never joined, so it was never reconciled, and
+ * after any daemon restart `releaseStaleClaims()` nulled the rest. The Inbox
+ * could only ever have shown rows whose dispatch was still in flight in this
+ * process.
+ *
+ * `last_run_id` is the same value with a different lifetime: written beside
+ * `claim_run_id` on `claim()`, and never cleared by anything. The two are
+ * deliberately separate columns rather than one repurposed column, because they
+ * answer different questions - "who holds this now?" drives release, "which run
+ * produced this row?" drives the projection - and collapsing them would make
+ * `releaseStaleClaims()` unable to tell a live claim from a finished one.
+ */
+export const RUN_ID_COLUMNS_V4 = [
+    { name: "last_run_id", ddl: "ALTER TABLE ingestion_items ADD COLUMN last_run_id TEXT" },
+];
+/**
+ * `STRICT` is load-bearing, not decoration: every bound value must match its
+ * declared type, so a `Date` or a float accidentally bound to an INTEGER column
+ * throws at write time instead of silently storing a value that later reads
+ * back as the wrong type and skews a freshness verdict. Always bind
+ * `now().getTime()`.
+ */
+const CREATE_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS ingestion_items (
+  filter_id     TEXT    NOT NULL,
+  item_key      TEXT    NOT NULL,
+  content_hash  TEXT,
+  first_seen_at INTEGER NOT NULL,
+  last_seen_at  INTEGER NOT NULL,
+  handled_at    INTEGER,
+  outcome       TEXT,
+  fail_count    INTEGER NOT NULL DEFAULT 0,
+  last_fail_at  INTEGER,
+  fail_sig      TEXT,
+  alerted_on    TEXT,
+  claimed_at    INTEGER,
+  claim_run_id  TEXT,
+  agent_id      TEXT,
+  meta          TEXT,
+  PRIMARY KEY (filter_id, item_key)
+) STRICT;
+`;
+/**
+ * Serves the list path (`WHERE filter_id = ? ORDER BY last_seen_at DESC`).
+ * The point lookup rides the composite PRIMARY KEY's implicit
+ * `sqlite_autoindex_ingestion_items_1` instead, which is why no second index
+ * on (filter_id, item_key) exists here.
+ */
+const CREATE_INDEX_SQL = `
+CREATE INDEX IF NOT EXISTS idx_ingestion_items_filter_seen
+  ON ingestion_items (filter_id, last_seen_at DESC);
+`;
+/**
+ * THE DAY'S DISPATCH BUDGET - one row per (filter, UTC day), holding how many
+ * dispatches that filter has been GRANTED today. Story 3.4.
+ *
+ * It is a counter table and deliberately NOT a query over `ingestion_items`
+ * (decision D-3.4-A). `ingestion_items` is keyed `(filter_id, item_key)`, so
+ * any `COUNT(*)` over it counts DISTINCT ITEMS, never attempts - a retry
+ * overwrites the same row. Story 3.3 admits up to 7 attempts per item per UTC
+ * day (3 before the threshold, then one per 6h cooldown), so a cap of 10
+ * enforced per distinct item would permit up to 70 minted sessions in a day.
+ * That is the disaster the cap exists to prevent, arrived at THROUGH the
+ * mitigation. This table counts attempts.
+ *
+ * `day` is a zero-padded `YYYY-MM-DD` UTC string precisely so lexicographic
+ * comparison equals chronological comparison - that is what `prune()`'s
+ * `day < ?` clause depends on, and why the key is an ISO date string rather
+ * than a number.
+ *
+ * Three columns and no free-text payload column, on purpose: there is nowhere
+ * for an item's content (and therefore a credential) to land. `CapLimiter`
+ * persists a count and nothing else.
+ *
+ * `PRIMARY KEY (filter_id, day)` is the only index this table gets; the
+ * implicit `sqlite_autoindex` already serves the one query shape (a point
+ * lookup on both columns), which a test asserts with `EXPLAIN QUERY PLAN`.
+ */
+const CREATE_BUDGET_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS ingestion_dispatch_budget (
+  filter_id  TEXT    NOT NULL,
+  day        TEXT    NOT NULL,
+  dispatched INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (filter_id, day)
+) STRICT;
+`;
+/**
+ * A COHORT - one batch apply, however many sessions it collapsed to. Story 5.4.
+ *
+ * Forty selected items are not forty rows on screen; they are one cohort whose
+ * progress line has to stay honest while it moves. The counter columns here are
+ * DENORMALIZED on purpose and are never what `inspect` returns: `markGroup`
+ * maintains them inside the same transaction that moves a group row, and
+ * `inspect` derives its counts by `GROUP BY status` over the group rows, so the
+ * two are a live consistency check on the transaction boundary rather than two
+ * places a number can rot.
+ *
+ * `dispatched` means DISPATCHED. It increments on `pending -> running` and on
+ * nothing else. A cohort that dispatched six sessions and finished none reads
+ * `dispatched = 6, succeeded = 0`, because recording intent as fact here would
+ * put "6 done" on a screen above six sessions that have not written anything.
+ *
+ * There is no payload column. `item_keys` on the groups table holds `fingerprint()`
+ * item keys - short opaque hashes - so there is nowhere for a Gmail body or an
+ * `authorization` header to land, exactly as `ingestion_dispatch_budget` has
+ * nowhere for a count to become content.
+ *
+ * `cancelled_at` on the cohort, not a status column: a cancelled cohort still has
+ * running groups finishing normally, so "this cohort was cancelled" and "this
+ * group did not run" are two different facts and are stored as two.
+ */
+const CREATE_COHORTS_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS ingestion_cohorts (
+  cohort_id    TEXT PRIMARY KEY,
+  filter_id    TEXT    NOT NULL,
+  mode         TEXT    NOT NULL,
+  created_at   INTEGER NOT NULL,
+  updated_at   INTEGER NOT NULL,
+  requested    INTEGER NOT NULL,
+  groups_total INTEGER NOT NULL,
+  dispatched   INTEGER NOT NULL DEFAULT 0,
+  succeeded    INTEGER NOT NULL DEFAULT 0,
+  failed       INTEGER NOT NULL DEFAULT 0,
+  cancelled    INTEGER NOT NULL DEFAULT 0,
+  truncated    INTEGER NOT NULL DEFAULT 0,
+  cap_per_day  INTEGER,
+  cancelled_at INTEGER
+) STRICT;
+`;
+/**
+ * One group of a cohort: the unit that becomes one session and therefore one
+ * outward artifact.
+ *
+ * `run_id` and `agent_id` are null until dispatch and are what the restart proof
+ * asserts on - "this group was dispatched exactly once" is only checkable
+ * because a second dispatch would have to write a second, different `run_id`.
+ */
+const CREATE_COHORT_GROUPS_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS ingestion_cohort_groups (
+  cohort_id  TEXT NOT NULL,
+  group_key  TEXT NOT NULL,
+  item_keys  TEXT NOT NULL,
+  status     TEXT NOT NULL,
+  run_id     TEXT,
+  agent_id   TEXT,
+  PRIMARY KEY (cohort_id, group_key)
+) STRICT;
+`;
+/**
+ * Serves the two queries that decide what a cohort row says and what a restart
+ * finishes: `GROUP BY status` for one cohort (`inspect`), and the `status =
+ * 'pending'` scan (`cancelRemaining`, `resumePending`).
+ */
+const CREATE_COHORT_GROUPS_INDEX_SQL = `
+CREATE INDEX IF NOT EXISTS idx_cohort_groups_status
+  ON ingestion_cohort_groups (cohort_id, status);
+`;
+/** Read `PRAGMA user_version`, defaulting an unreadable value to 0. */
+function readUserVersion(db) {
+    const row = db.prepare("PRAGMA user_version").get();
+    return typeof row?.user_version === "number" ? row.user_version : 0;
+}
+/**
+ * Add the v3 reconcile columns to an existing `ingestion_items`, in place.
+ *
+ * Two gates, and BOTH are load-bearing:
+ *   - the `user_version` gate makes the common path (an already-current file
+ *     opened on every daemon boot) cost one PRAGMA read and nothing else
+ *   - the `table_info` diff is what makes it IDEMPOTENT even when
+ *     `user_version` is out of sync with reality - a hand-edited file, a
+ *     restored backup, or a crash between the ALTERs and the version stamp.
+ *     sqlite has no `ADD COLUMN IF NOT EXISTS`, so without this diff a second
+ *     run throws `duplicate column name` and takes the daemon down at boot.
+ *
+ * Nothing is dropped, nothing is rewritten, no row is touched. A column added
+ * by `ALTER TABLE` reads
+ * back as its default (NULL, or 0 for the counter) on every pre-existing row,
+ * which is exactly the semantics the reconciler wants: "never verified".
+ */
+function migrateToV3(db) {
+    if (readUserVersion(db) >= 3)
+        return;
+    const existing = new Set();
+    for (const row of db.prepare("PRAGMA table_info(ingestion_items)").all()) {
+        const name = row.name;
+        if (typeof name === "string")
+            existing.add(name);
+    }
+    for (const column of RECONCILE_COLUMNS_V3) {
+        if (existing.has(column.name))
+            continue;
+        db.exec(column.ddl);
+    }
+}
+/**
+ * Add the v4 non-clearing run id, in place.
+ *
+ * Same two gates and the same reasoning as `migrateToV3`: the `user_version`
+ * check keeps the boot path to one PRAGMA read, and the `table_info` diff is
+ * what survives a `user_version` that is out of sync with the file.
+ *
+ * Pre-existing rows get `last_run_id = NULL`, which reads as "this row predates
+ * v4" and simply keeps them out of the projection - the same place they already
+ * were. Nothing is backfilled from `claim_run_id`: for every row that matters
+ * that column is already NULL, so a backfill would copy nothing while looking
+ * like it had done something.
+ */
+function migrateToV4(db) {
+    if (readUserVersion(db) >= 4)
+        return;
+    const existing = new Set();
+    for (const row of db.prepare("PRAGMA table_info(ingestion_items)").all()) {
+        const name = row.name;
+        if (typeof name === "string")
+            existing.add(name);
+    }
+    for (const column of RUN_ID_COLUMNS_V4) {
+        if (existing.has(column.name))
+            continue;
+        db.exec(column.ddl);
+    }
+}
+/**
+ * Bring `db` up to `LEDGER_SCHEMA_VERSION`. Idempotent: every statement is
+ * `IF NOT EXISTS` or guarded by a `PRAGMA table_info` diff, so a second call
+ * against an already-provisioned database is a no-op that destroys no rows.
+ */
+export function ensureSchema(db) {
+    // WAL so a reader (the client listing items) never blocks the writer (the
+    // ingestion pass), and survives an unclean exit.
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA foreign_keys = ON");
+    db.exec(CREATE_TABLE_SQL);
+    db.exec(CREATE_INDEX_SQL);
+    db.exec(CREATE_BUDGET_TABLE_SQL);
+    // v2 (Story 5.4). Additive `IF NOT EXISTS` DDL, so a v1 file gains the two
+    // cohort tables in place: no migration step, no rewrite, and every existing
+    // `ingestion_items` row is left byte-identical.
+    db.exec(CREATE_COHORTS_TABLE_SQL);
+    db.exec(CREATE_COHORT_GROUPS_TABLE_SQL);
+    db.exec(CREATE_COHORT_GROUPS_INDEX_SQL);
+    // v3 (Story 6.1). Runs AFTER the v1 `CREATE TABLE IF NOT EXISTS` above, so a
+    // brand-new file gets the base table and then the five reconcile columns in
+    // the same call, and an existing v1/v2 file gets only the columns.
+    //
+    // No index is added for them on purpose: every new column is read either
+    // through the composite PRIMARY KEY (a point lookup on
+    // `(filter_id, item_key)`) or through `idx_ingestion_items_filter_seen`
+    // (`WHERE filter_id = ? ORDER BY last_seen_at DESC`). A sixth index would be
+    // write cost on the ingestion hot path for a read that already has a plan.
+    migrateToV3(db);
+    // v4 (Story 6.2). Additive, and for the same reason v3 needs no index: the
+    // column is read through `idx_ingestion_items_filter_seen` on a query that
+    // already has a plan, and the join it feeds happens in memory over one
+    // filter's page of rows.
+    migrateToV4(db);
+    // Stamp the version so a future migration has something to read. Left
+    // unchanged when already current - `PRAGMA user_version` is not
+    // parameterizable, hence the interpolation of a module-private integer
+    // constant (never caller input).
+    const current = readUserVersion(db);
+    if (current !== LEDGER_SCHEMA_VERSION) {
+        db.exec(`PRAGMA user_version = ${LEDGER_SCHEMA_VERSION}`);
+    }
+}
+//# sourceMappingURL=ledger-schema.js.map