@minnowdb/core 0.0.1 → 0.1.1

package/dist/engine/database.d.ts

@@ -0,0 +1,661 @@
+import { type BatchRow, type BatchValue, type InsertBatchInput } from "./batch.js";
+import { BufferedTableWriter, type BufferedWriterOptions } from "./buffered-writer.js";
+export { attachLifecycleFlush, BufferedTableWriter, type BufferedFlushResult, type BufferedWriterOptions, type LifecycleDocumentTarget, type LifecycleFlushOptions, type LifecycleFlushRequester, type LifecyclePageTarget, } from "./buffered-writer.js";
+import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MissingKeyError, SqlCompileError, UniqueConstraintError } from "./errors.js";
+import { type Compression } from "../block-format/index.js";
+import { type BlockStore, type ColumnDefault, type CompactionJobRecord, type CompactionJobState, type GarbageCollectionJobRecord, type GarbageCollectionJobState, type SimpleDataType, type SnapshotExportProgress, type SnapshotLoadProgress } from "../storage/index.js";
+import { type CompiledQuery, type CompiledStatement, type ForeignKeyDefinition, type QueryResult, type QueryRow, type QueryValue } from "./query.js";
+import { LiveQuerySet, type LiveQuerySetOptions } from "./live.js";
+import { type Catalog } from "./catalog.js";
+import { type AnyTable, type MigrationStep, type SchemaDefinition } from "./schema.js";
+export interface ColumnDefinition {
+    name: string;
+    type: SimpleDataType;
+    nullable?: boolean;
+    /** Fills null-or-absent slots at insert time; never applied at read time. */
+    defaultValue?: ColumnDefault;
+    /** String columns only: the closed set of values writes must draw from. */
+    enumValues?: readonly string[];
+    /** What rows written before this column existed read as, instead of NULL. */
+    backfill?: boolean | number | string | Date;
+}
+export interface MigrateOptions {
+    /**
+     * Allows steps that destroy data — dropping a column or a table. Off by default: a migration
+     * runs when an application opens, with nobody to review it.
+     */
+    readonly allowDestructive?: boolean;
+    /**
+     * Treats the schema as the whole database, so a table it created and no longer declares is
+     * dropped. Off by default: an application may migrate feature by feature, and each call
+     * declaring only its own tables must not mean "drop the others". Needs `allowDestructive`
+     * as well, since dropping a table destroys its rows.
+     */
+    readonly schemaOwnsDatabase?: boolean;
+}
+export interface CreateTableInput {
+    name: string;
+    columns: readonly ColumnDefinition[];
+    /** Row conditions every written row must satisfy (E141-06); each is a boolean SQL expression. */
+    checks?: ReadonlyArray<{
+        name: string;
+        sql: string;
+    }>;
+    /** Marks the table as created from a schema, which lets a later migration drop it. */
+    managed?: boolean;
+    /** Single-column references to another table's unique key (E141-04). */
+    foreignKeys?: readonly ForeignKeyDefinition[];
+    uniqueKey?: string;
+}
+export type { BatchRow, BatchValue, ColumnarBatch, InsertBatchInput } from "./batch.js";
+export interface InsertBatchResult {
+    tableName: string;
+    segmentId: string;
+    rowCount: number;
+    blockCount: number;
+    storedBytes: number;
+    version: number;
+    metrics: WriteMetrics;
+    /**
+     * Full written vectors, input row order, for every column where the engine filled at least
+     * one default or generated slot. Absent when the batch was written exactly as provided.
+     */
+    generatedColumns?: Record<string, BatchValue[]>;
+}
+export interface UpsertBatchResult extends InsertBatchResult {
+    insertedRowCount: number;
+    updatedRowCount: number;
+}
+export interface UpdateBatchInput {
+    keys: readonly BatchValue[];
+    changes: Readonly<Record<string, readonly BatchValue[]>>;
+}
+export interface UpdateBatchResult {
+    tableName: string;
+    segmentId: string;
+    requestedRowCount: number;
+    updatedRowCount: number;
+    changedColumns: string[];
+    blockCount: number;
+    storedBytes: number;
+    version: number;
+    metrics: WriteMetrics;
+}
+export interface WriteMetrics {
+    logicalBytes: number;
+    storedBytes: number;
+    writeAmplification: number;
+    encodeMs: number;
+    stageMs: number;
+    commitMs: number;
+    totalMs: number;
+    retries: number;
+    rowsPerSecond: number;
+}
+export interface ReadTableOptions {
+    version?: number;
+    columns?: readonly string[];
+}
+/**
+ * The scope handed to `snapshot()`: queries pinned to one manifest version, consistent with
+ * each other for the lifetime of the callback.
+ */
+export interface SnapshotSession {
+    /** The pinned manifest version; null only on a database with no commits yet. */
+    readonly version: number | null;
+    query(sql: string, options?: QueryOptions): Promise<QueryResult>;
+}
+/** Lifetime buffer pool counters; see MinnowDatabase.bufferPoolStats(). */
+export interface BufferPoolStats {
+    limitBytes: number;
+    usedBytes: number;
+    entries: number;
+    hits: number;
+    misses: number;
+    evictions: number;
+}
+/** One staged mutation inside a write scope; the commit version arrives on the scope. */
+export interface StagedWriteResult {
+    tableName: string;
+    segmentId: string | null;
+    rowCount: number;
+}
+/**
+ * The scope handed to `write()`: every mutation stages into one transaction and publishes
+ * as one commit — all of it or none of it, in every tab. Reads observe the pre-scope snapshot
+ * plus everything the scope has staged, so later statements (and trigger bodies) see earlier
+ * ones; AFTER triggers fire per staged operation exactly as they do for standalone writes.
+ *
+ * A mutation that fails after registering part of its work ends the scope: the registration
+ * cannot be undone in place, so later statements and the commit both reject even if the caller
+ * caught the original error. A mutation that fails validation before registering anything
+ * leaves the scope usable.
+ */
+export interface WriteSession {
+    /**
+     * Read-your-writes: the query observes the pre-scope snapshot PLUS everything this scope
+     * has staged so far, ordered after all committed data — without publishing anything.
+     */
+    query(sql: string, options?: {
+        params?: QueryOptions["params"];
+    }): Promise<QueryResult>;
+    insertBatch(tableName: string, input: InsertBatchInput): Promise<StagedWriteResult>;
+    upsertBatch(tableName: string, input: InsertBatchInput): Promise<StagedWriteResult>;
+    updateBatch(tableName: string, input: UpdateBatchInput): Promise<StagedWriteResult>;
+    deleteBatch(tableName: string, input: DeleteBatchInput): Promise<StagedWriteResult>;
+}
+/** What one statement's execution cost, reported by the engine that ran it. */
+export interface QueryExecutionStats {
+    /**
+     * Peak modeled execution memory for this statement, in bytes: the documented vector,
+     * row-index, group/result payload, and ordering buffers, which is the same model
+     * `executionMemoryBudgetBytes` bounds. Boxed snapshot preparation, JavaScript container
+     * overhead, and allocator overhead are outside it. Not reported for a memo hit — nothing ran.
+     */
+    readonly peakMemoryBytes: number;
+}
+export interface QueryOptions {
+    /**
+     * Called once with what this execution cost, before the result is returned. Additive and
+     * optional: the engine can report its own memory because it reserves before it allocates,
+     * which is not something the storage layer or a caller could measure from outside.
+     */
+    readonly onStats?: (stats: QueryExecutionStats) => void;
+    /**
+     * false makes this statement compute its results instead of reusing any it has cached: the
+     * probe-validated result memo, cached block results, and the columnar forms of derived and
+     * windowed sources are all bypassed (the default true serves provably-fresh cached results
+     * from each). Block and vector caches stay warm — those cache storage reads, not results.
+     *
+     * Useful for benchmarking execution itself, and for callers that re-run one statement in a
+     * tight loop over changing external state. Note that replaying one statement over unchanging
+     * data with the default on measures cache lookups, not query execution.
+     */
+    memoize?: boolean;
+    readonly version?: number;
+    /**
+     * Values for the statement's `?`/`$n` placeholders, in order. Required exactly when the
+     * statement has placeholders; the compiled plan is cached on the SQL text and re-bound per
+     * execution, so parameterized queries skip re-parsing.
+     */
+    readonly params?: readonly QueryValue[];
+    /**
+     * Budget for the documented modeled vector, row-index, group/result payload, and ordering buffers.
+     * Boxed snapshot preparation, JavaScript container overhead, returned-result lifetime, and browser
+     * allocator overhead are not included in this Phase 7B-B model.
+     */
+    readonly executionMemoryBudgetBytes?: number;
+    /** Forces durable temp pages; with an explicit budget, spill otherwise retries only after exhaustion. */
+    readonly spillToStorage?: boolean;
+    /** Maximum rows encoded in each merged spill page. */
+    readonly spillPageRows?: number;
+}
+export interface DeleteBatchInput {
+    keys: readonly BatchValue[];
+}
+export interface DeleteBatchResult {
+    tableName: string;
+    segmentId: string | null;
+    requestedKeyCount: number;
+    deletedRowCount: number;
+    blockCount: number;
+    storedBytes: number;
+    version: number | null;
+    metrics: WriteMetrics;
+}
+export interface CompactTableOptions {
+    /** @deprecated Use minimumLevel0Segments. */
+    minimumSegments?: number;
+    /** Minimum L0 segments promoted; one also permits a direct L0 -> L2 promotion. */
+    minimumLevel0Segments?: number;
+    /** Target maximum L0 segments promoted by one job. Equal-order groups remain indivisible. */
+    maxLevel0Segments?: number;
+    /** Target maximum stored L0 bytes promoted by one job. The L1 anchor is excluded. */
+    maxLevel0StoredBytes?: number;
+    /** Number of immutable output blocks processed before yielding and checkpointing. */
+    maxBlocksPerStep?: number;
+    /** Output level. L2 is the append-only row-range partition policy. */
+    targetLevel?: number;
+    /** Hard L2 output-byte limit as a multiple of newly promoted L0 stored bytes. */
+    maxWriteAmplification?: number;
+    /** Estimated uncompressed physical bytes per output column block. */
+    targetBlockBytes?: number;
+    /** Compression used for rewritten output blocks. */
+    outputCompression?: Compression;
+    /** Upper bound for accounted JavaScript-owned executor buffers. */
+    memoryBudgetBytes?: number;
+}
+export interface CompactTableStepOptions extends CompactTableOptions {
+    maxBlocks?: number;
+}
+export type CompactionSkipReason = "below-segment-threshold" | "contains-mutation-segments" | "keys-outside-selected-sources" | "non-contiguous-row-ids" | "unsupported-level-layout" | "write-amplification-budget";
+export interface CompactTableResult {
+    jobId?: string;
+    tableName: string;
+    compacted: boolean;
+    skipReason?: CompactionSkipReason;
+    sourceSegmentCount: number;
+    sourceBlockCount: number;
+    outputSegmentId: string | null;
+    outputBlockCount: number;
+    rowCount: number;
+    sourceStoredBytes: number;
+    outputStoredBytes: number;
+    level0SourceStoredBytes?: number;
+    anchorSourceStoredBytes?: number;
+    compactionWriteAmplification?: number;
+    outputPartitionOrdinal?: number;
+    maxWriteAmplification?: number;
+    maximumOutputStoredBytes?: number;
+    plannedOutputStoredBytesUpperBound?: number;
+    /** Stored bytes cancelled or aborted attempts at these sources already wrote. */
+    priorAttemptOutputStoredBytes?: number;
+    /** This attempt's output plus every prior failed attempt's, sharing one lifetime ceiling. */
+    lifetimeOutputStoredBytes?: number;
+    outputLogicalBytes?: number;
+    targetBlockBytes?: number;
+    outputCompression?: Compression;
+    memoryBudgetBytes?: number;
+    minimumMemoryBytes?: number;
+    peakWorkingBytes?: number;
+    supersededBlockCount: number;
+    physicallyReclaimedBytes: 0;
+    version: number | null;
+    metrics: WriteMetrics | null;
+}
+export interface CompactionJobProgress {
+    jobId: string | null;
+    tableName: string;
+    state: CompactionJobState | "skipped";
+    processedRows: number;
+    sourceSegmentCount: number;
+    sourceBlockCount: number;
+    outputBlockCount: number;
+    level0SourceStoredBytes?: number;
+    anchorSourceStoredBytes?: number;
+    outputPartitionOrdinal?: number;
+    maxWriteAmplification?: number;
+    maximumOutputStoredBytes?: number;
+    plannedOutputStoredBytesUpperBound?: number;
+    memoryBudgetBytes?: number;
+    minimumMemoryBytes?: number;
+    peakWorkingBytes?: number;
+    result: CompactTableResult | null;
+}
+export interface CancelCompactionJobResult {
+    jobId: string;
+    state: "cancelled" | "published" | "aborted";
+    publishedVersion: number | null;
+}
+export interface CollectGarbageOptions {
+    /** Maximum candidates examined and checkpointed by each durable reclamation step. */
+    maxItemsPerStep?: number;
+    /** Maximum block/segment candidates copied into one durable planning record. */
+    maxPlanningItems?: number;
+}
+export interface CollectGarbageStepOptions {
+    /** Maximum candidates examined and checkpointed by this durable reclamation step. */
+    maxItems?: number;
+    /** Maximum block/segment candidates copied into a newly planned job. */
+    maxPlanningItems?: number;
+}
+export interface GarbageCollectionResult {
+    jobId: string;
+    prunedManifestCount: number;
+    alreadyPrunedManifestCount: number;
+    retainedManifestCount: number;
+    missingManifestCount: number;
+    reclaimedSegmentCount: number;
+    retainedSegmentCount: number;
+    missingSegmentCount: number;
+    reclaimedBlockCount: number;
+    retainedBlockCount: number;
+    missingBlockCount: number;
+    physicallyReclaimedBytes: number;
+}
+export interface GarbageCollectionProgress {
+    jobId: string;
+    state: GarbageCollectionJobState;
+    examinedManifestCount: number;
+    examinedSegmentCount: number;
+    examinedBlockCount: number;
+    result: GarbageCollectionResult | null;
+}
+export interface TableDefinition {
+    name: string;
+    columns: ColumnDefinition[];
+    uniqueKey?: string;
+}
+export type DatabaseRow = Record<string, Exclude<BatchValue, null> | null>;
+export { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MissingKeyError, SqlCompileError, UniqueConstraintError, };
+export interface MinnowDatabaseOptions {
+    /**
+     * Block codec for newly written blocks; defaults to "gzip", which is also what compaction
+     * rewrites to, so a table's blocks are encoded the same way however they got there.
+     *
+     * Measured over 200k rows on IndexedDB, gzip against raw: about half the stored bytes
+     * (4.9 MiB vs 10.0 MiB) and a *faster* cold scan (13.3 ms vs 17.9 ms) — reading half the
+     * bytes out of IndexedDB more than pays for decompressing them — at the cost of roughly
+     * 2.2x on bulk ingest (413 ms vs 184 ms). Warm scans are identical either way, because the
+     * buffer pool caches decoded blocks. Choose "raw" when ingest throughput matters more than
+     * storage quota; the browser usually makes the opposite trade worth it.
+     */
+    compression?: Compression;
+    rowsPerBlock?: number;
+    maxCommitRetries?: number;
+    now?: () => Date;
+    createId?: () => string;
+    /** Durable spill-owner lease lifetime; renewed while a spilling query runs. */
+    spillOwnerLeaseMs?: number;
+    /**
+     * How long a statement-level transaction (`BEGIN` … `COMMIT`) may sit untouched before it
+     * rolls itself back; 30 seconds by default. A scope nobody ever closes would otherwise hold
+     * its staged blocks and transaction record against the collector forever.
+     */
+    transactionIdleTimeoutMs?: number;
+    /**
+     * Retained bytes for the block buffer pool: decoded physical blocks, their vectorized
+     * per-block column forms, zone-map block descriptions, and derived/subquery block
+     * results. Every entry is keyed by an immutable identity (a block id, or an exact
+     * visible-segment-id fingerprint), so a cached entry can never serve stale data;
+     * superseded entries simply stop being referenced and age out of the byte-bounded
+     * LRU. 0 disables the pool. Defaults to 64 MiB.
+     */
+    bufferPoolBytes?: number;
+    /**
+     * Visible-row threshold at which a full-text MATCH on an unindexed append-only column
+     * schedules a background index build (fire-and-forget; correctness never waits on it).
+     * Defaults to 4096.
+     */
+    ftsAutoIndexRows?: number;
+    /**
+     * Read-triggered compaction: when a streamed scan observes a table fragmented past
+     * 48 visible segments, one incremental compaction step is scheduled fire-and-forget —
+     * the same self-maintenance pattern as the full-text auto index. Correctness never waits
+     * on it; repeated scans advance further steps. false disables.
+     */
+    autoCompact?: boolean;
+}
+export interface QuerySpillCleanupOptions {
+    /** Maximum owners examined in this pass. */
+    maxOwners?: number;
+}
+export interface QuerySpillCleanupResult {
+    ownersExamined: number;
+    ownersReclaimed: number;
+    ownersRetained: number;
+}
+export type ExecuteResult = {
+    kind: "rows";
+    result: QueryResult;
+} | {
+    kind: "create-table";
+    table: string;
+} | {
+    kind: "add-column";
+    table: string;
+    column: string;
+} | {
+    kind: "drop-table";
+    table: string;
+    dropped: boolean;
+} | {
+    kind: "merge";
+    table: string;
+    rowCount: number;
+    version?: number;
+} | {
+    kind: "transaction";
+    action: "begin" | "commit" | "rollback";
+    version?: number;
+} | {
+    kind: "create-view";
+    view: string;
+} | {
+    kind: "drop-view";
+    view: string;
+    dropped: boolean;
+} | {
+    kind: "create-trigger";
+    table: string;
+    name: string;
+} | {
+    kind: "drop-trigger";
+    name: string;
+} | {
+    kind: "insert";
+    table: string;
+    rowCount: number;
+    /** Absent when the statement affected no rows (an INSERT ... SELECT of an empty set). */
+    version?: number;
+    returnedRows?: QueryRow[];
+} | {
+    kind: "update";
+    table: string;
+    rowCount: number;
+    version?: number;
+    returnedRows?: QueryRow[];
+} | {
+    kind: "delete";
+    table: string;
+    rowCount: number;
+    version?: number | null;
+    returnedRows?: QueryRow[];
+};
+export interface RunStatementOptions {
+    /**
+     * Projects the affected rows back: column names, or "*" for every table column. Inserts echo
+     * the written values; updates return post-update values; deletes return the rows as read.
+     */
+    readonly returning?: readonly string[] | "*";
+    /**
+     * Where the statement's writes go. Absent means the database itself — one commit per
+     * statement. A write scope routes them into that scope instead, which is how a statement-level
+     * transaction makes several statements publish together.
+     */
+    readonly writer?: StatementWriter;
+}
+/**
+ * A write scope seen as somewhere statements can run: the batch operations, plus the reads the
+ * keyed mutation paths need — by SQL for subqueries, by plan for the rows an UPDATE or DELETE
+ * is about to touch. Both reads observe the scope's own staged writes.
+ */
+export interface StatementWriter extends WriteSession {
+    queryPlan(plan: CompiledQuery): Promise<QueryResult>;
+}
+export interface VisibleSegment {
+    id: string;
+    rowCount: number;
+    columnBlockIds: Readonly<Record<string, readonly string[]>>;
+}
+export interface SnapshotExportOptions {
+    /** Called as the export moves through its phases; see SnapshotExportProgress. */
+    onProgress?: (progress: SnapshotExportProgress) => void;
+}
+export interface SnapshotImportOptions {
+    /** Called as blocks land, for a progress bar over a multi-megabyte file. */
+    onProgress?: (progress: SnapshotLoadProgress) => void;
+}
+export declare class MinnowDatabase {
+    #private;
+    private readonly store;
+    constructor(store: BlockStore, options?: MinnowDatabaseOptions);
+    createTable(input: CreateTableInput): Promise<void>;
+    /**
+     * The published catalog: stable column IDs, key identity, constraints, triggers, and view
+     * bodies. This is the introspection surface schema tooling builds on — `listTables()` answers
+     * what a reader can select, this answers what a planner needs to diff.
+     */
+    introspect(): Promise<Catalog>;
+    listTables(): Promise<TableDefinition[]>;
+    /**
+     * Defines a view: a query the catalog answers to by name (F031-02). The stored record carries
+     * the query's inferred output schema, so a view answers the same questions a table does —
+     * what a reader can select, and of what type — and the devtools rail lists it beside them.
+     * Reads expand it into the query it stands for; writes to it are refused.
+     */
+    createView(name: string, sql: string, options?: {
+        orReplace?: boolean;
+        managed?: boolean;
+    }): Promise<void>;
+    /** Removes a view. Returns whether one was dropped; `ifExists` makes a missing one no error. */
+    dropView(name: string, options?: {
+        ifExists?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Drops a table: its rows, its catalog record, its full-text index, and its triggers. The
+     * blocks are retired through an ordinary commit rather than deleted, so a reader pinned to an
+     * older version keeps resolving the bytes it already holds and the lease-aware collector
+     * reclaims them when nobody can reach them. What a pinned reader does lose is the table
+     * itself — the catalog has one present tense, so a snapshot open across a drop sees the table
+     * disappear rather than a frozen copy of it.
+     *
+     * Returns whether a table was dropped; with `ifExists`, a missing table is not an error.
+     */
+    dropTable(tableName: string, options?: {
+        ifExists?: boolean;
+    }): Promise<boolean>;
+    insertBatch(tableName: string, input: InsertBatchInput): Promise<InsertBatchResult>;
+    insert(tableName: string, row: BatchRow): Promise<InsertBatchResult>;
+    upsertBatch(tableName: string, input: InsertBatchInput): Promise<UpsertBatchResult>;
+    upsert(tableName: string, row: BatchRow): Promise<UpsertBatchResult>;
+    updateBatch(tableName: string, input: UpdateBatchInput): Promise<UpdateBatchResult>;
+    update(tableName: string, key: Exclude<BatchValue, null>, changes: Readonly<Record<string, BatchValue>>): Promise<UpdateBatchResult>;
+    deleteBatch(tableName: string, input: DeleteBatchInput): Promise<DeleteBatchResult>;
+    bufferedWriter(tableName: string, options?: BufferedWriterOptions): BufferedTableWriter;
+    readTable(tableName: string, versionOrOptions?: number | ReadTableOptions): Promise<DatabaseRow[]>;
+    /**
+     * Runs the callback against one pinned manifest version: every query inside the scope
+     * observes the same committed state, however many commits land meanwhile. This is the
+     * only pinning primitive — it cannot leak, because the pin is the scope. The version's
+     * blocks stay protected by an internal reader lease for the scope's duration, renewed
+     * while queries run; keep scopes short so garbage collection is not held back.
+     *
+     * On a database with no commits yet the session has no version to pin; its queries run
+     * fresh, which is indistinguishable until the first commit.
+     */
+    snapshot<T>(action: (session: SnapshotSession) => Promise<T>): Promise<T>;
+    /** Executes a read-only SELECT statement through the public query API. */
+    query(sql: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Reclaims temp spill pages whose owner lease is expired or missing at a cutoff fixed when the
+     * pass starts. Owners with an unexpired lease are retained; each owner is removed atomically
+     * against a concurrent renewal.
+     */
+    cleanupQuerySpill(options?: QuerySpillCleanupOptions): Promise<QuerySpillCleanupResult>;
+    /**
+     * Creates a live-query set over this database. Local commits hint it directly, an optional
+     * channel carries cross-tab hints, and an optional poll interval bounds staleness without any
+     * hint; every hint path converges on the durable manifest version, so missed messages delay a
+     * refresh but never produce a stale result. Subscriptions retain a result digest, not rows.
+     */
+    liveQueries(options?: LiveQuerySetOptions): LiveQuerySet;
+    /**
+     * Runs the callback against one shared write transaction: every staged mutation — across
+     * any number of keyed or keyless tables, with their AFTER triggers — publishes as one
+     * atomic commit. A concurrent *write* surfaces as a WriteConflictError from the scope
+     * (nothing published); retry the whole scope. Background self-maintenance is not a
+     * concurrent write: the scope rebases over data-neutral manifests and commits anyway, so
+     * compaction landing mid-scope never fails it. An error thrown by the callback aborts the
+     * scope with nothing published. A scope that stages nothing publishes nothing.
+     */
+    write<T>(action: (session: WriteSession) => Promise<T>): Promise<{
+        result: T;
+        version: number | null;
+    }>;
+    /** Executes a built ORM query through the same streaming-first pipeline as compiled SQL. */
+    run<TRow>(query: {
+        kind: "typed-query";
+        plan: CompiledQuery;
+        __row?: TRow;
+    }): Promise<TRow[]>;
+    /**
+     * Applies a schema definition to the catalog through metadata-only steps: creating missing
+     * tables, adding nullable columns, renaming columns via their stable IDs, and widening
+     * nullability. The pass is idempotent — re-running after a crash completes the remaining
+     * steps — and every catalog alteration is one atomic compare-and-swap, so a concurrent
+     * migrator fails explicitly with a conflict instead of interleaving.
+     */
+    migrate(definition: SchemaDefinition<readonly AnyTable[]>, options?: MigrateOptions): Promise<{
+        createdTables: string[];
+        alteredTables: string[];
+        droppedTables: string[];
+        replacedViews: string[];
+        droppedViews: string[];
+        steps: MigrationStep[];
+    }>;
+    /**
+     * Renders the optimized logical plan for a SELECT statement plus the physical strategy notes
+     * the prepared execution would choose, without executing it.
+     */
+    explain(sql: string): Promise<string>;
+    /**
+     * Executes one SQL statement. SELECT statements run through the read-only query pipeline;
+     * INSERT ... VALUES maps onto a column batch insert, and UPDATE/DELETE on a unique-key table
+     * read the matching keys at one snapshot and then apply the keyed mutation. The read and the
+     * mutation are two steps, not one serializable transaction: a key changed by a competing writer
+     * in between fails the statement explicitly rather than silently mutating other rows.
+     */
+    execute(sql: string, params?: readonly QueryValue[]): Promise<ExecuteResult>;
+    /**
+     * Executes an already-compiled statement — the typed mutation builders call this directly with
+     * the same statement structures SQL parses into, sharing every validation and conflict rule.
+     * With `returning`, the affected rows project back: inserts echo the written values, deletes
+     * return the rows as read at the statement's snapshot, and updates return post-update values
+     * (the snapshot row with assignments applied — the exact values the mutation wrote).
+     */
+    runStatement(statement: CompiledStatement, options?: RunStatementOptions): Promise<ExecuteResult>;
+    listVisibleSegments(tableName: string, version?: number): Promise<VisibleSegment[]>;
+    /**
+     * Copies the current committed version out as a portable snapshot file — the byte array
+     * `../storage/snapshot.ts` describes, which `importSnapshot()` loads back into any store.
+     *
+     * The bytes are the unit here rather than the structured `DatabaseSnapshot` the store returns,
+     * because that is what a caller does with a snapshot: write it to disk, hand it to a colleague,
+     * ship it as an asset. Reach for `store.exportSnapshot()` directly when you want the records
+     * instead. Either way the whole snapshot is materialized in memory, so a database of hundreds
+     * of megabytes needs the headroom for a copy of itself.
+     *
+     * Stores differ in how they hold still while this runs: see the note on exporting safely in the
+     * snapshots guide.
+     */
+    exportSnapshot(options?: SnapshotExportOptions): Promise<Uint8Array>;
+    /**
+     * Loads a snapshot file into this database's store, which must be empty. Every block is
+     * authenticated while decoding, so a corrupt file fails here rather than mid-query, and a store
+     * that already holds a database throws rather than merging two histories.
+     */
+    importSnapshot(bytes: Uint8Array, options?: SnapshotImportOptions): Promise<void>;
+    compactTable(tableName: string, options?: CompactTableOptions): Promise<CompactTableResult>;
+    /** Plans or advances one restart-safe physical compaction job. */
+    compactTableStep(tableName: string, options?: CompactTableStepOptions): Promise<CompactionJobProgress>;
+    /** Continues a persisted compaction job after a cooperative yield or restart. */
+    resumeCompactionJob(jobId: string, options?: {
+        maxBlocks?: number;
+    }): Promise<CompactionJobProgress>;
+    listCompactionJobs(tableName?: string): Promise<CompactionJobRecord[]>;
+    /** Atomically prevents an unpublished compaction job from committing its transaction. */
+    cancelCompactionJob(jobId: string): Promise<CancelCompactionJobResult>;
+    /** Runs restart-safe lease-aware reclamation to completion in bounded durable steps. */
+    collectGarbage(options?: CollectGarbageOptions): Promise<GarbageCollectionResult>;
+    /** Plans or advances one durable garbage-collection pass. */
+    collectGarbageStep(options?: CollectGarbageStepOptions): Promise<GarbageCollectionProgress>;
+    /** Continues a persisted reclamation pass after a cooperative yield or restart. */
+    resumeGarbageCollectionJob(jobId: string, options?: CollectGarbageStepOptions): Promise<GarbageCollectionProgress>;
+    listGarbageCollectionJobs(): Promise<GarbageCollectionJobRecord[]>;
+    /**
+     * Buffer pool observability: byte budget and residency plus lifetime hit/miss/eviction
+     * counters across every entry family (decoded blocks, block vectors, zone descriptions,
+     * derived results, memoized results). Use it to size bufferPoolBytes from real workloads.
+     */
+    bufferPoolStats(): BufferPoolStats;
+    /**
+     * Builds (or rebuilds) the persisted full-text pruning index for one column from the current
+     * snapshot. Append-only tables only. The planner consults the index when the column is
+     * "ready" with a matching tokenizer version and re-verifies every candidate row, so a stale,
+     * missing, or lost index costs speed, never correctness. Searches schedule this lazily once
+     * a table crosses the auto-index threshold; calling it directly is just a warm-up.
+     */
+    buildFtsIndex(tableName: string, columnName: string): Promise<void>;
+}
+//# sourceMappingURL=database.d.ts.map