@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5685

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

@@ -0,0 +1,39 @@
+import type { RunClaim } from './run-database.ts';
+import type { StatementSync } from 'node:sqlite';
+import type { RunDatabaseChanges, RunRow, RunRowInput } from './run-database.ts';
+type SqlRow = Record<string, unknown>;
+export declare function toRunRow(row: SqlRow): RunRow;
+/** Both metadata batches keep their order inside RunDatabase.transaction. */
+export declare function writeMetadata(statements: {
+    deleteMeta: StatementSync;
+    setMeta: StatementSync;
+}, values: Readonly<Record<string, string | null>>): void;
+/** Convert the input row to the named SQLite bindings without changing optional-column defaults. */
+export declare function toRunBindings(row: RunRowInput, revision: number): {
+    id: string;
+    createdAt: string;
+    finishedAt: string | null;
+    status: string;
+    archived: number;
+    live: number;
+    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 declare function toRunClaim(row: Record<string, unknown>): RunClaim;
+export declare function validateChanges(changes: RunDatabaseChanges): void;
+/**
+ * What a read-only open opens. `quiescent` (a project migration's dry run, which must leave no
+ * trace) also requires this build's exact schema, and reads a database with no WAL file (no
+ * connection is open and every commit is in the main file) as immutable, so no -wal or -shm is
+ * created. With a WAL file present it coordinates as any reader does, which writes shared-memory
+ * state: a caller that must write nothing reads a private copy (the migration planner does).
+ */
+export declare function readOnlyTarget(path: string, quiescent: boolean): string;
+export {};

package/dist/runs/run-database-row.js

@@ -0,0 +1,83 @@
+import { existsSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+export function toRunRow(row) {
+    return {
+        seq: row.seq,
+        id: row.id,
+        createdAt: row.created_at,
+        finishedAt: row.finished_at,
+        status: row.status,
+        archived: row.archived === 1,
+        live: row.live === 1,
+        parentRunId: row.parent_run_id,
+        clientRequestId: row.client_request_id,
+        groupId: row.group_id,
+        worktreePath: row.worktree_path,
+        branch: row.branch,
+        baseBranch: row.base_branch,
+        revision: row.revision,
+        data: row.data,
+        summary: row.summary,
+    };
+}
+/** Both metadata batches keep their order inside RunDatabase.transaction. */
+export function writeMetadata(statements, values) {
+    for (const [key, value] of Object.entries(values)) {
+        if (value === null)
+            statements.deleteMeta.run(key);
+        else
+            statements.setMeta.run(key, value);
+    }
+}
+/** Convert the input row to the named SQLite bindings without changing optional-column defaults. */
+export function toRunBindings(row, revision) {
+    return {
+        id: row.id,
+        createdAt: row.createdAt,
+        finishedAt: row.finishedAt ?? null,
+        status: row.status,
+        archived: row.archived ? 1 : 0,
+        live: row.live ? 1 : 0,
+        parentRunId: row.parentRunId ?? null,
+        clientRequestId: row.clientRequestId ?? null,
+        groupId: row.groupId ?? null,
+        worktreePath: row.worktreePath ?? null,
+        branch: row.branch ?? null,
+        baseBranch: row.baseBranch ?? null,
+        revision,
+        data: row.data,
+        summary: row.summary,
+    };
+}
+export function toRunClaim(row) {
+    return {
+        family: row.family,
+        session: row.session,
+        pid: row.pid,
+        startToken: row.start_token,
+        generation: row.generation,
+    };
+}
+export function validateChanges(changes) {
+    const upserted = new Set();
+    for (const row of changes.upserts) {
+        if (upserted.has(row.id))
+            throw new TypeError(`run ${row.id} is upserted twice in one transaction`);
+        upserted.add(row.id);
+    }
+    for (const id of changes.deletes) {
+        if (upserted.has(id))
+            throw new TypeError(`run ${id} is both upserted and deleted in one transaction`);
+    }
+}
+/**
+ * What a read-only open opens. `quiescent` (a project migration's dry run, which must leave no
+ * trace) also requires this build's exact schema, and reads a database with no WAL file (no
+ * connection is open and every commit is in the main file) as immutable, so no -wal or -shm is
+ * created. With a WAL file present it coordinates as any reader does, which writes shared-memory
+ * state: a caller that must write nothing reads a private copy (the migration planner does).
+ */
+export function readOnlyTarget(path, quiescent) {
+    return quiescent && !existsSync(`${path}-wal`) ? `${pathToFileURL(path).href}?immutable=1` : path;
+}
+//# sourceMappingURL=run-database-row.js.map

package/dist/runs/run-database-row.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-database-row.js","sourceRoot":"","sources":["../../src/runs/run-database-row.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,14 @@
+/** `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 = 11;
+/**
+ * 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;
+/** A format guard for new wait enum values; no table or row rewrite. */
+export declare const MERGE_WAIT_MIGRATION = "\n  -- Schema 11 changes no table: PR waits can carry until 'merge_or_blocked' and outcome 'blocked'\n  -- (hearsay-tools/cezarion#2712). Older readers cannot parse these enum values and must refuse\n  -- the store rather than recover a run without its accepted wait. Upgrade again to recover.\n  ";

package/dist/runs/run-database-version.js

@@ -0,0 +1,19 @@
+/** `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 const RUN_DATABASE_SCHEMA_VERSION = 11;
+/**
+ * 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 const RUN_DATABASE_READABLE_FROM = 1;
+/** A format guard for new wait enum values; no table or row rewrite. */
+export const MERGE_WAIT_MIGRATION = `
+  -- Schema 11 changes no table: PR waits can carry until 'merge_or_blocked' and outcome 'blocked'
+  -- (hearsay-tools/cezarion#2712). Older readers cannot parse these enum values and must refuse
+  -- the store rather than recover a run without its accepted wait. Upgrade again to recover.
+  `;
+//# sourceMappingURL=run-database-version.js.map

package/dist/runs/run-database-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-database-version.js","sourceRoot":"","sources":["../../src/runs/run-database-version.ts"],"names":[],"mappings":"AAAA;;6CAE6C;AAC7C,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC;AAE5C,wEAAwE;AACxE,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;GAIjC,CAAC"}

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

@@ -0,0 +1,389 @@
+export { RUN_DATABASE_READABLE_FROM, RUN_DATABASE_SCHEMA_VERSION } from './run-database-version.ts';
+import { type IndexedArtifact } from './report-rows.ts';
+import { type PeerSummaryPageQuery } from './run-database-peer-page.ts';
+/**
+ * Synchronous SQLite storage for opaque run JSON, summaries and query columns. All writes use
+ * transaction(); failures leave database files intact and return typed errors.
+ */
+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";
+/** 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;
+    /** Whether originating-issue attribution was verified for this write. */
+    issueAttributionCurrent?: boolean;
+    /** 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;
+    /** Explicit adoption only (`RunStore.adoptFallbackFamily`): fallback families to copy in first. */
+    adoptFallback?: readonly string[];
+}
+/** 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' | 'fallback';
+    /** 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 project?;
+    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`.
+     *
+     * `supported` is the newest schema this open accepts. Only a test passes it, to stand in for an
+     * older build's bound and prove that build refuses the store.
+     */
+    static open(path: string, supported?: number): RunDatabase;
+    /**
+     * Open an existing readable database without creating it, migrating it or changing journal mode.
+     * Return null before a readable schema exists; refuse newer schemas. WAL/SHM coordination may
+     * need writes; do not bypass it with immutable mode.
+     */
+    static openReadOnly(path: string, supported?: number, options?: {
+        quiescent?: boolean;
+    }): RunDatabase | null;
+    /** Add a read-only source; a read-only (cold) projection never switches its primary to disk. */
+    static withProjectSource(primary: RunDatabase, target: string, source: string, jsonRows?: readonly RunRowInput[], readOnly?: boolean): RunDatabase;
+    isFallback(id: string): boolean;
+    get hasProjectSource(): boolean;
+    hasFallback(id: string): boolean;
+    familyHasFallback(family: string): boolean;
+    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[];
+    /** A bounded root-only page, with exclusions applied before SQL offset/limit. */
+    listPeerSummaries(options: PeerSummaryPageQuery): 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 | undefined;
+    }): 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 `matchesRunSearch`. 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, opts?: {
+        includeIssueMarked?: 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;
+    /** 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;
+    /** The row's revision, read without its `data`; undefined when there is no row. */
+    revisionOf(id: string): number | undefined;
+    /**
+     * 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;
+    }>;
+    /** Bounded keyset walk. Include worker-only PR roots without decoding history. */
+    listArchiveOnMergeCandidates(afterSeq: number, limit: number): Array<{
+        id: string;
+        seq: number;
+    }>;
+    listCompletionCandidates(afterSeq: number, limit: number): Array<{
+        id: string;
+        seq: number;
+    }>;
+    /** Indexed point/family lookup, after the bounded root page has been selected. */
+    archiveFamilyHasPullRequests(id: string): boolean;
+    /** Every id with its revision, ordered by id. */
+    listRevisions(): RunRevision[];
+    get reports(): import("./report-rows.ts").ReportRows;
+    replaceArtifacts(id: string, artifacts: readonly IndexedArtifact[], revision?: number): void;
+    listArtifacts(): IndexedArtifact[];
+    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(physical?: boolean): 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;
+}