/**
 * SQLite schema versioning for every store the platform writes.
 *
 * Each store carries its schema version in `PRAGMA user_version`:
 * - opening a store at the current version is a no-op;
 * - an older store runs ordered migrations up to the target, with an
 *   automatic snapshot of the store file taken BEFORE any migration runs;
 * - a failed migration auto-restores the store from that pre-migration
 *   snapshot and reports honestly what happened and where the snapshot is;
 * - an older binary refuses a newer schema with an honest message instead
 *   of corrupting data it does not understand (the downgrade guard).
 *
 * Engine-agnostic: bun:sqlite and sql.js handles both adapt to the same
 * two-method interface.
 */
export interface VersionedSqliteHandle {
    getUserVersion(): number;
    setUserVersion(version: number): void;
}
/** Adapt a bun:sqlite Database to the version handle. */
export declare function bunSqliteVersionHandle(db: {
    query(sql: string): {
        get(): unknown;
    };
    run(sql: string): unknown;
}): VersionedSqliteHandle;
/** Adapt a sql.js Database to the version handle. */
export declare function sqlJsVersionHandle(db: {
    exec(sql: string): Array<{
        columns: string[];
        values: unknown[][];
    }>;
    run(sql: string): unknown;
}): VersionedSqliteHandle;
export interface StoreMigration {
    /** The schema version this migration produces. */
    readonly toVersion: number;
    readonly migrate: () => void;
}
/** An older binary refusing a newer store, data is left untouched. */
export declare class StoreSchemaDowngradeError extends Error {
    readonly storeName: string;
    readonly dbPath: string;
    readonly storeVersion: number;
    readonly supportedVersion: number;
    constructor(storeName: string, dbPath: string, storeVersion: number, supportedVersion: number);
}
/** A migration failed; the store was restored from its pre-migration snapshot. */
export declare class StoreMigrationError extends Error {
    readonly storeName: string;
    readonly fromVersion: number;
    readonly toVersion: number;
    readonly snapshotPath: string | null;
    readonly restored: boolean;
    constructor(storeName: string, fromVersion: number, toVersion: number, snapshotPath: string | null, restored: boolean, cause: unknown);
}
export interface OpenVersionedSchemaOptions {
    /** Human store name for honest messages ("memory store", "code index"). */
    readonly storeName: string;
    /** On-disk path for messages/snapshots; '' or ':memory:' skips snapshots. */
    readonly dbPath: string;
    readonly handle: VersionedSqliteHandle;
    readonly targetVersion: number;
    /** Ascending by toVersion; must reach exactly targetVersion. */
    readonly migrations: readonly StoreMigration[];
    /** Take a snapshot of the store file; returns its path or null when there is nothing to snapshot. */
    readonly snapshot?: ((reason: string) => string | null) | undefined;
    /** Restore the store file from a snapshot (the caller closes/reopens handles around it). */
    readonly restore?: ((snapshotPath: string) => void) | undefined;
}
export interface OpenVersionedSchemaResult {
    /** The version the store had before this open (equals target when current). */
    readonly fromVersion: number;
    /** Migrations that ran (empty when the store was already current). */
    readonly applied: readonly number[];
    /** Pre-migration snapshot path when one was taken. */
    readonly snapshotPath: string | null;
}
/**
 * The version contract for a bun:sqlite store, with snapshot/restore wired
 * to the store's on-disk file: pre-migration snapshot, auto-restore (the
 * live handle is closed first via `closeDb`), downgrade guard. In-memory
 * stores version without snapshots.
 */
export declare function openVersionedBunSqliteStore(input: {
    storeName: string;
    dbPath: string;
    db: {
        query(sql: string): {
            get(): unknown;
        };
        run(sql: string): unknown;
    };
    targetVersion: number;
    migrations: readonly StoreMigration[];
    /** Close (and null out) the live handle before a restore rewrites the file. */
    closeDb: () => void;
}): OpenVersionedSchemaResult;
/**
 * Enforce the schema-version contract on an opened store: no-op when
 * current, migrate forward with a pre-migration snapshot, refuse downgrade,
 * auto-restore on migration failure.
 */
export declare function openVersionedSchema(options: OpenVersionedSchemaOptions): OpenVersionedSchemaResult;
//# sourceMappingURL=store-versioning.d.ts.map