@wjarka/cezarion 0.15.1 → 0.16.0

package/dist/runs/run-database.d.ts

@@ -0,0 +1,385 @@
+/**
+ * The transactional run store underneath `RunStore` (#779, plan step 2).
+ *
+ * One SQLite file per project, `<dataDir>/runs.db`, holding every run as a complete JSON record
+ * plus the handful of columns the store has to query without decoding that record. The module is
+ * deliberately schema-agnostic: it never imports `RunRecord`, never parses `data` or `summary`,
+ * and never decides what a column's value should be. The caller (RunStore's codec) computes them
+ * and hands over strings, so the record schema can change without this file noticing.
+ *
+ * Everything is synchronous, like the store it serves. Writes go through ONE entry point,
+ * `transaction()`, which commits a whole change set or nothing — the property `runs.json`'s
+ * debounced whole-file rewrite only approximated.
+ *
+ * Failure policy: every SQLite error leaves as a typed `RunDatabaseError` (`toRunDatabaseError`),
+ * and nothing here ever deletes, truncates or "repairs" a file. A corrupt database, WAL or SHM
+ * stays exactly where it is for the user (or a later recovery step) to inspect.
+ */
+export declare const RUNS_DB_FILE = "runs.db";
+/** `meta` key whose presence means the legacy `runs.json` import committed (or there was nothing
+ *  to import): from then on this database is authoritative and `runs.json` is history. Written in
+ *  the same transaction as the imported rows, so it can never describe a half-finished import. */
+export declare const RUNS_IMPORT_COMPLETE_KEY = "import-complete";
+/** `PRAGMA user_version` of a database this build created. A higher number means a newer cezar
+ *  wrote it; that is refused rather than read, because a newer schema may store what this one
+ *  would silently drop on its next write. */
+export declare const RUN_DATABASE_SCHEMA_VERSION = 2;
+/**
+ * The oldest `user_version` the READ-ONLY reader can read as it stands (`openReadOnly`). It never
+ * migrates, so a project this build has not opened yet is still at the version an earlier build
+ * left; while every migration since only adds what readers can do without (indexes), that
+ * database stays readable rather than reading as empty. Raise it with any migration that changes
+ * a table or column a reader queries.
+ */
+export declare const RUN_DATABASE_READABLE_FROM = 1;
+/** What the caller writes for one run. Optional columns may be omitted or null. */
+export interface RunRowInput {
+    id: string;
+    createdAt: string;
+    finishedAt?: string | null;
+    status: string;
+    archived: boolean;
+    live: boolean;
+    parentRunId?: string | null;
+    clientRequestId?: string | null;
+    groupId?: string | null;
+    worktreePath?: string | null;
+    branch?: string | null;
+    baseBranch?: string | null;
+    /** The complete record, serialized. */
+    data: string;
+    /** The record's summary projection, serialized. */
+    summary: string;
+}
+export interface RunRow {
+    /** Insertion order: assigned by the row's first insert, never changed (see the schema). */
+    seq: number;
+    id: string;
+    createdAt: string;
+    finishedAt: string | null;
+    status: string;
+    archived: boolean;
+    live: boolean;
+    parentRunId: string | null;
+    clientRequestId: string | null;
+    groupId: string | null;
+    worktreePath: string | null;
+    branch: string | null;
+    baseBranch: string | null;
+    revision: number;
+    data: string;
+    summary: string;
+}
+export interface RunSummaryRow {
+    seq: number;
+    id: string;
+    createdAt: string;
+    revision: number;
+    summary: string;
+}
+/** What branch cleanup and git-log attribution read about one run, without its record. */
+export interface BranchOwnerRow {
+    id: string;
+    createdAt: string;
+    status: string;
+    archived: boolean;
+    branch: string | null;
+    baseBranch: string | null;
+    summary: string;
+}
+export interface RunRevision {
+    id: string;
+    revision: number;
+}
+export interface RunDatabaseChanges {
+    upserts: readonly RunRowInput[];
+    deletes: readonly string[];
+    /** Private metadata in the same commit; `null` deletes the key. */
+    meta?: Readonly<Record<string, string | null>>;
+    /** What must still hold for this writer to commit (#779, plan step 3), checked inside the
+     *  transaction before anything is written. A violation throws `RunConflictError`. */
+    fence?: RunWriteFence;
+    /** Write nothing if this `meta` key is present when the transaction holds the write lock: the
+     *  commit comes back `skipped`. How exactly one of two concurrent importers imports (#779, plan
+     *  step 4) — a check made before the lock is only a hint. */
+    onlyIfMetaAbsent?: string;
+    /** Runs inside the transaction after every write, just before COMMIT; throwing rolls it all
+     *  back. The last moment a caller can still refuse what it wrote. What it returns is more
+     *  private metadata, written in the same commit. */
+    beforeCommit?: () => Readonly<Record<string, string>> | void;
+}
+/** A family a fenced write touches: held at `generation`, or to `take` in that same transaction if
+ *  its claim is still exactly as the writer judged it (absent, or a dead owner's) — the claim a
+ *  busy database kept the writer from taking before. */
+export type RunFenceClaim = {
+    generation: number;
+} | {
+    take: {
+        session: string;
+        generation: number;
+    } | null;
+};
+export interface RunWriteFence {
+    owner: {
+        session: string;
+        pid: number;
+        startToken: string | null;
+    };
+    /** Each family this change set writes. */
+    claims: ReadonlyMap<string, RunFenceClaim>;
+    /** Each row it writes or deletes: the revision the writer last saw (`null`: it expects no row),
+     *  and the family the row belongs to. */
+    rows: ReadonlyMap<string, {
+        revision: number | null;
+        family: string;
+    }>;
+}
+export interface RunDatabaseCommit {
+    /** The revision each upserted row now has. */
+    revisions: Map<string, number>;
+    /** The insertion order (`seq`) of each upserted row: new for a row this commit inserted. */
+    seqs: Map<string, number>;
+    /** The generation of each claim the fence took. */
+    claims: Map<string, number>;
+    /** Nothing was written: the `onlyIfMetaAbsent` key was present. */
+    skipped: boolean;
+}
+/** One family's owner in `run_claims`. */
+export interface RunClaim {
+    family: string;
+    session: string;
+    pid: number;
+    startToken: string | null;
+    generation: number;
+}
+/** A row a fenced write found other than its writer last saw it. */
+export interface RunRowConflict {
+    id: string;
+    reason: 'changed' | 'created' | 'deleted' | 'claim-lost';
+    /** The row as it stands, or undefined when another writer deleted it. */
+    current: RunRow | undefined;
+}
+/** One `run_conflicts` row: the original, local and current versions of a conflicted run. */
+export interface RunConflictEvidence {
+    runId: string;
+    reason: RunRowConflict['reason'];
+    baseRevision: number | null;
+    baseData: string | null;
+    localData: string | null;
+    localDeleted: boolean;
+    currentRevision: number | null;
+    currentData: string | null;
+}
+export type RunDatabaseErrorKind = 'busy' | 'permission' | 'disk-full' | 'corrupt' | 'unsupported-schema' | 'conflict' | 'other';
+/** Every failure this module reports. `kind` is the discriminant; the subclasses exist so a
+ *  caller can also `instanceof` the one case it handles. */
+export declare class RunDatabaseError extends Error {
+    readonly kind: RunDatabaseErrorKind;
+    /** SQLite's primary result code, when the failure came from SQLite. */
+    readonly sqliteCode: number | undefined;
+    constructor(kind: RunDatabaseErrorKind, message: string, options?: {
+        sqliteCode?: number;
+        cause?: unknown;
+    });
+}
+/** Another connection holds the lock past the busy timeout. Transient: retry later. */
+export declare class RunDatabaseBusyError extends RunDatabaseError {
+}
+/** The file or its directory cannot be opened or written by this user. */
+export declare class RunDatabasePermissionError extends RunDatabaseError {
+}
+/** The disk (or a page-count limit) has no room for the write. */
+export declare class RunDatabaseDiskFullError extends RunDatabaseError {
+}
+/** The file is not a database, or a page is malformed. Never reset by this module. */
+export declare class RunDatabaseCorruptError extends RunDatabaseError {
+}
+/** The database was written by a newer cezar whose schema this build does not know. */
+export declare class RunDatabaseUnsupportedSchemaError extends RunDatabaseError {
+    readonly found: number;
+    readonly supported: number;
+    constructor(found: number, supported: number);
+}
+/** A fenced write found rows changed, created or deleted under it, or its claim gone. Nothing was
+ *  written. `conflicts` names every such row of the change set, each with its current row. */
+export declare class RunConflictError extends RunDatabaseError {
+    readonly conflicts: readonly RunRowConflict[];
+    constructor(conflicts: readonly RunRowConflict[]);
+}
+/**
+ * Map a node:sqlite error (`code: 'ERR_SQLITE_ERROR'`, numeric `errcode`) to its typed class.
+ * Anything that is not a SQLite error — a closed connection, a bad argument — passes through
+ * unchanged, because wrapping it would claim a database failure that did not happen.
+ *
+ * `path`, when given, lets SQLITE_CANTOPEN be told apart: it is a permission problem only when
+ * the directory, or the file itself, refuses this user. A missing directory, or a directory where
+ * the file should be, is not — and "check your permissions" would send the user the wrong way.
+ */
+export declare function toRunDatabaseError(error: unknown, path?: string): unknown;
+/** An archived run that is not an owned worker: what the run lists' archived window counts (#864). */
+export declare const ARCHIVED_ROOT = "archived = 1 AND parent_run_id IS NULL";
+export declare class RunDatabase {
+    private readonly db;
+    private readonly path;
+    /** Set by the first statement that reports the file damaged (SQLITE_CORRUPT or NOTADB). */
+    private damaged;
+    private readonly statements;
+    private constructor();
+    /**
+     * Open (creating if absent) the database at `path` and bring its schema up to date. The
+     * directory must already exist; creating it is the caller's decision. On any failure the
+     * connection is closed and no existing data is deleted or rewritten — but a fresh path may be
+     * left holding an empty database (and its WAL), which the next open migrates. A reader that must
+     * create nothing uses `openReadOnly`.
+     */
+    static open(path: string): RunDatabase;
+    /**
+     * Open an existing database for reading only: never creates the file, never migrates it, never
+     * changes journal mode. Answers `null` when there is nothing this build can read yet — no file,
+     * or a file below `RUN_DATABASE_READABLE_FROM` (schema 0 is what a failed first open leaves) —
+     * so the caller can fall back to whatever it read before the database existed. A database from
+     * `RUN_DATABASE_READABLE_FROM` up to this build's schema is read as it stands. A newer schema is
+     * still refused.
+     *
+     * SQLite may create the `-wal`/`-shm` coordination files beside the database; that is the price
+     * of seeing a live writer's commits. In a read-only directory with neither file present it
+     * cannot, and the open fails as permission denied — deliberately not worked around with
+     * `immutable=1`, which would read a stale snapshot without saying so.
+     */
+    static openReadOnly(path: string): RunDatabase | null;
+    get(id: string): RunRow | undefined;
+    /** The rows for `ids` that exist, in no particular order. */
+    getMany(ids: readonly string[]): RunRow[];
+    /** Summaries newest first (`created_at` descending, then insertion order). Archived runs are included,
+     *  as every list route includes them. Without a limit, every row. */
+    listSummaries(options?: {
+        limit?: number;
+    }): RunSummaryRow[];
+    /**
+     * The run lists' window (#864), newest first: every unarchived row, plus the newest
+     * `archivedLimit` archived roots. Archived workers are never in it — no list renders them, and
+     * counting them is what let them push an older live root out of a newest-N window.
+     */
+    listWindowSummaries(archivedLimit: number, options?: {
+        roots?: boolean;
+    }): RunSummaryRow[];
+    /** The summary rows of `ids` that exist, in no particular order. */
+    getSummaries(ids: readonly string[]): RunSummaryRow[];
+    /** Every root row (archived or not) whose stored summary contains each `prefilter` token,
+     *  lowercased, newest first: the candidates of a run search (#864), which the caller still
+     *  checks with `matchesRunQuery`. No tokens, every root. */
+    searchRootSummaries(prefilter: readonly string[]): RunSummaryRow[];
+    /** The rows `searchRootSummaries` answers, one at a time, until `visit` answers false: a search
+     *  that needs only its first matches stops reading there. */
+    visitRootSummaries(prefilter: readonly string[], visit: (row: RunSummaryRow) => boolean): void;
+    /** Every row, newest first (`created_at` descending, then insertion order). */
+    listAll(): RunRow[];
+    /** The rows `RunStore.open` holds in memory: those whose `live` column is set, in insertion order. */
+    listLive(): RunRow[];
+    /** The workers of one parent, newest first. */
+    listByParent(parentId: string): RunRow[];
+    /** The ids of one parent's workers, in no particular order, without reading their records. */
+    listIdsByParent(parentId: string): string[];
+    /** The id of every worker row, in no particular order. */
+    listWorkerIds(): string[];
+    findByClientRequestId(clientRequestId: string): RunRow | undefined;
+    /** The members of one variant group, in no particular order. */
+    listByGroup(groupId: string): RunRow[];
+    /** Rows with a materialized worktree, most recently finished (else created) first, then newest first. */
+    listWithWorktree(): RunRow[];
+    /** The rows matching `where` (by default, every row that owns a branch) as branch owners,
+     *  with their summary, in no particular order. Same contract for `where` as `listWhere`. */
+    listBranchOwners(where?: string): BranchOwnerRow[];
+    /** The ids of the rows that own `branch` or hold a worktree at `worktreePath`. */
+    findResourceHolders(resource: {
+        branch: string;
+        worktreePath: string;
+    }): string[];
+    /** Every id, in no particular order. */
+    listIds(): string[];
+    has(id: string): boolean;
+    /**
+     * Rows matching `where`, newest first — the store's candidate filters (mark all read, archive
+     * finished, retention, the reference heal), which combine these columns with `json_extract`
+     * over `summary`. `where` is the caller's constant SQL; values go in `params`, never into it.
+     * `offset` skips the newest rows first (retention keeps the newest N).
+     */
+    listWhere(where: string, params?: readonly (string | number)[], options?: {
+        offset?: number;
+    }): RunRow[];
+    /** The id and creation time of each row matching `where`, newest first, read off the
+     *  `created_at` index without touching `data` or `summary` (history retention's ranking).
+     *  Same contract for `where` as `listWhere`. */
+    listKeysWhere(where: string, params?: readonly (string | number)[]): Array<{
+        id: string;
+        createdAt: string;
+        seq: number;
+    }>;
+    /** Every id with its revision, ordered by id. */
+    listRevisions(): RunRevision[];
+    getMeta(key: string): string | undefined;
+    /**
+     * The only write of run rows. Deletes, upserts and metadata commit together or not at all: on
+     * any failure the transaction is rolled back and the error is rethrown typed, with the database
+     * exactly as it was. Every upserted row gets this commit's revision from the database-wide
+     * sequence. With a `fence`, nothing is written unless every claim and row is still as the writer
+     * last saw it (`RunConflictError` otherwise).
+     */
+    transaction(changes: RunDatabaseChanges): RunDatabaseCommit;
+    /** Inside a write transaction: take the claims the fence asks for, then throw `RunConflictError`
+     *  naming every row of the fence that is not as its writer last saw it, before anything is
+     *  written (the claims taken roll back with it). Returns the claims taken. */
+    private checkFence;
+    /** Inside a write transaction: the next value of a database-wide sequence kept in `meta`. */
+    private nextSequence;
+    /** The family a stored run belongs to (`parent_run_id`, else its own id), or undefined. */
+    familyOf(id: string): string | undefined;
+    /** Whether any row of `family` (its root or a direct worker) is live. */
+    familyHasLive(family: string): boolean;
+    getClaim(family: string): RunClaim | undefined;
+    /** The claims on `families` that exist, by family. */
+    getClaims(families: readonly string[]): Map<string, RunClaim>;
+    listClaims(): RunClaim[];
+    /**
+     * Take the claims in `take` for `owner`, in one transaction. Each is taken only when its claim
+     * is still exactly what the caller judged it to be: absent (`expect: null`) or held by the dead
+     * owner it read (same session and generation) — so two takers racing for one family cannot both
+     * win. Returns the generation of each claim taken.
+     */
+    takeClaims(owner: {
+        session: string;
+        pid: number;
+        startToken: string | null;
+    }, take: ReadonlyArray<{
+        family: string;
+        expect: {
+            session: string;
+            generation: number;
+        } | null;
+    }>): Map<string, number>;
+    /** Drop `session`'s claims on `families`, or on everything it holds when omitted. */
+    releaseClaims(session: string, families?: readonly string[]): void;
+    /** Every row whose family a session other than `session` claims, live or not, with that family. */
+    listForeignClaimedIds(session: string): Array<{
+        id: string;
+        family: string;
+    }>;
+    /** Store conflict evidence in one transaction; returns each entry's `seq`. */
+    recordConflicts(session: string, entries: readonly RunConflictEvidence[]): number[];
+    /** Every stored conflict, oldest first (diagnostics and tests). */
+    listConflicts(): Array<RunConflictEvidence & {
+        seq: number;
+        session: string;
+        detectedAt: string;
+    }>;
+    /** The connection's effective settings, for diagnostics. */
+    pragmas(): {
+        journalMode: string;
+        synchronous: number;
+        busyTimeoutMs: number;
+    };
+    /** Idempotent: closing a closed database does nothing. Once any statement found the file
+     *  damaged, the close leaves every file exactly as it is (`closeLeavingFiles`). */
+    close(): void;
+    private run;
+}