import { DatabaseSync } from 'node:sqlite';
/** The ordered migration list. Index `i` is migration version `i + 1`; the db's
 *  `user_version` tracks how many have been applied. Append only. */
export declare const MIGRATIONS: ReadonlyArray<(db: DatabaseSync) => void>;
/** Bring `db` up to the latest schema version. Reads `user_version`, runs each
 *  pending migration in order, and bumps `user_version` after each so the work
 *  is gated and idempotent: re-running is a no-op once `user_version` reaches
 *  `MIGRATIONS.length`. Forward-only.
 *
 *  ATOMIC AND RESTARTABLE: each step AND its `user_version` bump run inside one
 *  `BEGIN IMMEDIATE`/`COMMIT` (SQLite journals `user_version` with the
 *  transaction, so a rollback restores it too). An interrupted or failing step
 *  therefore leaves the db exactly at the previous version with none of its
 *  writes committed — a half-applied step can never wedge every later open. The
 *  write lock also serializes concurrent openers; the version is re-read after
 *  acquiring it so a step another process just applied is skipped rather than
 *  re-run. */
export declare function migrate(db: DatabaseSync): void;
/** Open (or reuse) the canvas db at the current `CRTR_HOME`, initializing the
 *  schema and WAL on first open. Keyed by path so tests with distinct homes get
 *  independent handles. */
export declare function openDb(): DatabaseSync;
/** Run `body` under the canvas SQLite write lock, joining an outer transaction
 *  when the shared connection already owns one. This is the common boundary for
 *  multi-statement mutations whose reads and writes must linearize as one unit;
 *  `node:sqlite` rejects nested BEGINs, so only the outermost call commits.
 */
export declare function withCanvasWrite<T>(body: (db: DatabaseSync) => T): T;
/** Close and forget the handle for the current home. Mainly for tests. */
export declare function closeDb(): void;