@minnowdb/core 0.0.1 → 0.1.0

package/dist/storage/types.d.ts

@@ -0,0 +1,895 @@
+export declare const storeNames: readonly ["catalog", "manifests", "segments", "blocks", "transactions", "leases", "statistics", "temp", "gc"];
+/** The manifest fields every commit publishes; `Manifest` adds the resolved block list. */
+export interface ManifestSummary {
+    version: number;
+    previousVersion: number | null;
+    createdAt: string;
+    /**
+     * Table IDs whose logical content this commit changed; empty means a logical no-change such as
+     * compaction. Absent on manifests written before change tracking, which readers treat as
+     * potentially changing every table.
+     */
+    changedTableIds?: string[];
+    /** A pruned descriptor remains readable for commit reconciliation but cannot be pinned. */
+    prunedAt?: string;
+}
+export interface Manifest extends ManifestSummary {
+    blockIds: string[];
+}
+/**
+ * The stored manifest shape: a checkpoint carries the complete sorted block list; a delta
+ * carries only this commit's added and removed ids plus its distance from the checkpoint below
+ * it. Reads resolve a version by walking back to the nearest checkpoint and applying deltas
+ * forward, so publishing a commit writes O(changed blocks) instead of rewriting every live
+ * block id. Records are never physically deleted (pruning tombstones them via `prunedAt`), so a
+ * chain below any readable version always resolves.
+ */
+export interface StoredManifestRecord extends ManifestSummary {
+    blockIds?: string[];
+    addedBlockIds?: string[];
+    removedBlockIds?: string[];
+    /** Deltas since the checkpoint below; 0 on checkpoints. */
+    deltaDepth?: number;
+}
+/** Every this-many commits the store writes a full checkpoint instead of a delta. */
+export declare const MANIFEST_CHECKPOINT_INTERVAL = 32;
+/** Applies one stored record to a running block set (checkpoint replaces, delta mutates). */
+export declare function applyManifestRecord(blockIds: Set<string>, record: StoredManifestRecord): void;
+export interface PublishManifestInput {
+    changedTableIds?: readonly string[];
+    expectedVersion: number | null;
+    blockIds: readonly string[];
+    createdAt?: string;
+}
+export declare const simpleDataTypes: readonly ["boolean", "number", "string", "datetime"];
+export type SimpleDataType = (typeof simpleDataTypes)[number];
+/**
+ * Declarative write-time default. Plain structured-clone-safe data: the spec crosses the
+ * worker postMessage boundary and persists in the catalog, so function defaults are
+ * unrepresentable by design — the schema DSL carries those separately (`ColumnBuilder.defaultFn`)
+ * and the typed facade fills them before a batch reaches the engine.
+ */
+export type ColumnDefault = {
+    kind: "now";
+} | {
+    kind: "literal";
+    value: boolean | number | string;
+} | {
+    kind: "autoincrement";
+};
+export interface TableColumnRecord {
+    id: string;
+    name: string;
+    type: SimpleDataType;
+    nullable: boolean;
+    /** Fills null-or-absent slots at insert time; never applied at read time. */
+    defaultValue?: ColumnDefault;
+    /**
+     * What rows written before this column existed read as, instead of NULL.
+     *
+     * A column added by a migration has no blocks in older segments. Those rows would otherwise
+     * read NULL forever, which is why adding a non-nullable column was impossible. Substituting
+     * this value at read time makes the addition meaningful without rewriting a single stored
+     * byte — the segments are untouched, and compaction folds the value in whenever it next
+     * rewrites them. It is frozen when the column is added: a generator runs once, at migration
+     * time, so every reader of a given row agrees.
+     *
+     * Spelled out rather than imported: storage sits below the engine, and NULL is the absence
+     * this replaces, so it is not one of the options.
+     */
+    backfill?: boolean | number | string | Date;
+    /**
+     * String columns only: the closed set of values writes must draw from. Physically the column
+     * stays a plain string column; the set is write-time validation metadata, so widening it (or
+     * dropping it) is catalog-only while narrowing it is rejected by migration planning.
+     */
+    enumValues?: string[];
+}
+/**
+ * The single authority on which enum declarations are legal, shared by the schema DSL's
+ * `column.enum()` and the engine's `createTable`: at least one value, every value a non-empty
+ * string, no duplicates. Returns a defensive copy.
+ */
+export declare function validateEnumValues(values: readonly string[], context: string): string[];
+/**
+ * The single authority on which default declarations are legal, shared by the schema DSL's
+ * `table()` and the engine's `createTable` so the two entry points (and the wire path between
+ * them) can never drift: defaults require non-nullable columns, "now" is datetime-only,
+ * auto-increment is the number unique key, and the unique key never defaults to a constant.
+ */
+export declare function validateColumnDefault(column: {
+    name: string;
+    type: SimpleDataType;
+    nullable: boolean;
+    isUniqueKey: boolean;
+    enumValues?: readonly string[];
+}, defaultValue: ColumnDefault): void;
+export type FtsColumnIndexState = "building" | "ready" | "invalid";
+/**
+ * One column's persisted full-text index declaration. The index is a pruning accelerator, never
+ * ground truth: readers use it only in state "ready" with a matching tokenizer version, and the
+ * scan re-verifies every candidate, so a stale or missing index costs speed, not correctness.
+ */
+export interface FtsColumnIndexRecord {
+    storage: "fts-chunks-v1";
+    tokenizerVersion: number;
+    state: FtsColumnIndexState;
+    /** Manifest version the base build covers; commit deltas above it merge at read time. */
+    buildFromVersion: number;
+}
+export interface TableRecord {
+    id: string;
+    name: string;
+    columns: TableColumnRecord[];
+    uniqueKeyColumnId?: string;
+    uniqueKeyLookupReady?: boolean;
+    uniqueKeyStorage?: "chunks-v1" | "chunks-v2";
+    /** Full-text index state per column ID. Writers that see this emit commit deltas. */
+    ftsColumns?: Record<string, FtsColumnIndexRecord>;
+    /** AFTER triggers on this table, fired by the committing writer inside its transaction. */
+    triggers?: TriggerRecord[];
+    /**
+     * Single-column FOREIGN KEY constraints (E141-04). The referenced column is the parent's
+     * unique key, which is what the engine can probe for existence and what its keyed write paths
+     * address rows by; a parent key never changes, so only ON DELETE has an action to take.
+     */
+    foreignKeys?: Array<{
+        name: string;
+        column: string;
+        parentTable: string;
+        parentColumn: string;
+        onDelete: "restrict" | "cascade" | "set null";
+    }>;
+    /**
+     * Row-level CHECK constraints (E141-06), each the text of a boolean expression over this
+     * table's own columns. Text rather than a compiled form because the record crosses the worker
+     * boundary and IndexedDB; the writer compiles it and evaluates it against every row it writes.
+     */
+    checks?: Array<{
+        name: string;
+        sql: string;
+    }>;
+    /**
+     * True when `migrate()` created this table from a schema declaration, which makes the schema
+     * authoritative over it: dropping the declaration may drop the table. A table created with
+     * `CREATE TABLE`, or one written before this field existed, is absent-or-false and no
+     * migration removes it — the same rule views follow, and it matters more here because a
+     * table holds rows.
+     */
+    managed?: boolean;
+    /**
+     * A view rather than a table: the query text it stands for, and no segments of its own. The
+     * `columns` are the query's inferred output schema, so a view answers the same catalog
+     * questions a table does — what a reader can select, and of what type.
+     */
+    view?: {
+        sql: string;
+        /**
+         * True when `migrate()` created this view from a schema declaration, which makes the schema
+         * authoritative over it: dropping the declaration drops the view. A view created with
+         * `CREATE VIEW`, or one written before this field existed, is absent-or-false and no
+         * migration will remove it.
+         */
+        managed?: boolean;
+    };
+    createdAt: string;
+    /** Compare-and-swap revision for catalog evolution; records written before it read as 0. */
+    revision?: number;
+}
+/**
+ * One AFTER trigger: catalog-persisted on its table record so the catalog epoch makes it
+ * visible to every tab immediately, and executed by the committing writer inside the same
+ * transaction as the triggering write — the write and its derivations publish atomically.
+ */
+export interface TriggerRecord {
+    name: string;
+    event: "insert" | "update" | "delete";
+    /**
+     * BEFORE and AFTER differ only in body staging order here: both fire in the committing
+     * writer inside the triggering commit, so the pair exists for SQL portability, with
+     * identical atomicity.
+     */
+    timing: "before" | "after";
+    /** Body statements in order; each fires once per affected row. */
+    statements: TriggerStatementRecord[];
+    createdAt: string;
+}
+export interface TriggerStatementRecord {
+    /** The body statement with every NEW.col / OLD.col reference rewritten to a placeholder. */
+    sql: string;
+    /** Placeholder bindings in order: which pseudo-row and column fills each parameter. */
+    bindings: Array<{
+        source: "new" | "old";
+        column: string;
+    }>;
+}
+export declare class TableRecordConflictError extends Error {
+    readonly tableId: string;
+    readonly expectedRevision: number;
+    readonly actualRevision: number | null;
+    readonly name = "TableRecordConflictError";
+    constructor(tableId: string, expectedRevision: number, actualRevision: number | null);
+}
+export type SegmentKind = "insert" | "upsert" | "update" | "delete" | "base";
+/** Maps a contiguous segment-row run to its immutable hidden row IDs. */
+export interface RowIdSpan {
+    readonly rowStart: number;
+    readonly rowCount: number;
+    readonly rowIdStart: bigint;
+}
+export interface SegmentRecord {
+    id: string;
+    tableId: string;
+    transactionId: string;
+    rowCount: number;
+    rowIdStart: bigint;
+    rowIdEndExclusive: bigint;
+    columnBlockIds: Record<string, string[]>;
+    kind?: SegmentKind;
+    keyColumnId?: string;
+    /** Missing on legacy records, which are interpreted as level zero. */
+    level?: number;
+    /** Missing on legacy records, where commit order supplies the logical order. */
+    logicalOrder?: number;
+    /**
+     * Staging position inside the owning transaction. Orders segments of one commit relative
+     * to each other (an in-scope update must fold after the in-scope insert it patches);
+     * missing on legacy records, which never shared a key within one commit.
+     */
+    commitOrdinal?: number;
+    /** Missing on legacy insert/upsert records, which imply one contiguous row-ID span. */
+    rowIdSpans?: readonly RowIdSpan[];
+    /** Monotone policy ordinal for an immutable append-row-range level-two partition. */
+    readonly partitionOrdinal?: number;
+    createdAt: string;
+}
+export interface RowIdRange {
+    start: bigint;
+    endExclusive: bigint;
+}
+export type LeaseKind = "reader" | "backup";
+export interface LeaseRecord {
+    id: string;
+    kind: LeaseKind;
+    manifestVersion: number | null;
+    ownerId: string;
+    expiresAt: string;
+    revision: number;
+}
+export declare const compactionJobStates: readonly ["planned", "running", "ready", "published", "cancelled", "aborted"];
+export type CompactionJobState = (typeof compactionJobStates)[number];
+export interface CompactionJobCursor {
+    sourceSegmentIndex: number;
+    sourceBlockIndex: number;
+}
+export declare const compactionRewritePlanKinds: readonly ["copy-v1", "rechunk-v1", "merge-v1"];
+export type CompactionRewritePlanKind = (typeof compactionRewritePlanKinds)[number];
+export interface CopyCompactionRewritePlan {
+    readonly kind: "copy-v1";
+}
+export interface RechunkCompactionSourceBlock {
+    readonly blockId: string;
+    readonly rowStart: number;
+    readonly rowCount: number;
+    /** Full persisted block byteLength, including the envelope and stored payload. */
+    readonly storedBytes: number;
+    /** Uncompressed encoded payload length from the immutable block header. */
+    readonly encodedBytes: number;
+    readonly checksum: number;
+}
+export interface RechunkCompactionSourceColumn {
+    readonly columnId: string;
+    readonly type: SimpleDataType;
+    readonly sourceBlocks: readonly RechunkCompactionSourceBlock[];
+}
+export interface RechunkCompactionOutputWindow {
+    readonly rowStart: number;
+    readonly rowCount: number;
+}
+export declare const compactionOutputCompressions: readonly ["raw", "gzip"];
+export type CompactionOutputCompression = (typeof compactionOutputCompressions)[number];
+export interface RechunkCompactionRewritePlan {
+    readonly kind: "rechunk-v1";
+    readonly targetBlockBytes: number;
+    readonly outputCompression: CompactionOutputCompression;
+    readonly totalRows: number;
+    readonly rowIdStart: bigint;
+    readonly rowIdEndExclusive: bigint;
+    readonly logicalOrder: number;
+    readonly columns: readonly RechunkCompactionSourceColumn[];
+    /** Shared row windows, emitted in output-window-major then column order. */
+    readonly outputs: readonly RechunkCompactionOutputWindow[];
+}
+export interface MergeCompactionSourceBlock {
+    readonly blockId: string;
+    /** Row offset within the source segment column. */
+    readonly rowStart: number;
+    readonly rowCount: number;
+    readonly storedBytes: number;
+    readonly encodedBytes: number;
+    readonly checksum: number;
+}
+export interface MergeCompactionSourceColumn {
+    readonly columnId: string;
+    readonly type: SimpleDataType;
+    readonly sourceBlocks: readonly MergeCompactionSourceBlock[];
+}
+export interface MergeCompactionSourceSegment {
+    readonly segmentId: string;
+    readonly transactionId: string;
+    readonly committedVersion: number;
+    readonly kind: SegmentKind;
+    readonly keyColumnId: string | null;
+    readonly level: number;
+    readonly logicalOrder: number;
+    readonly rowCount: number;
+    readonly rowIdStart: bigint;
+    readonly rowIdEndExclusive: bigint;
+    readonly rowIdSpans: readonly RowIdSpan[];
+    readonly columns: readonly MergeCompactionSourceColumn[];
+}
+export interface MergeCompactionOutputSourceRange {
+    /** Row offset within the canonical merged output. */
+    readonly outputRowStart: number;
+    readonly sourceBlockId: string;
+    /** Row offset within sourceBlockId. */
+    readonly sourceRowStart: number;
+    readonly rowCount: number;
+}
+export interface MergeCompactionOutputColumn {
+    readonly columnId: string;
+    readonly type: SimpleDataType;
+    readonly sourceRanges: readonly MergeCompactionOutputSourceRange[];
+}
+/** An immutable logical replay result followed by a physical, output-driven rewrite. */
+export interface MergeCompactionRewritePlan {
+    readonly kind: "merge-v1";
+    readonly targetBlockBytes: number;
+    readonly outputCompression: CompactionOutputCompression;
+    readonly keyColumnId: string;
+    readonly totalRows: number;
+    /** Bounding row-ID envelope; spans preserve gaps and output order. */
+    readonly rowIdStart: bigint;
+    readonly rowIdEndExclusive: bigint;
+    readonly rowIdSpans: readonly RowIdSpan[];
+    readonly logicalOrder: number;
+    readonly sourceSegments: readonly MergeCompactionSourceSegment[];
+    readonly columns: readonly MergeCompactionOutputColumn[];
+    readonly outputs: readonly RechunkCompactionOutputWindow[];
+}
+export type CompactionRewritePlan = CopyCompactionRewritePlan | RechunkCompactionRewritePlan | MergeCompactionRewritePlan;
+/**
+ * The next rechunk output to emit, ordered by output window and then column. A completed cursor
+ * has outputIndex === outputs.length, columnIndex zero, and rowStart === totalRows.
+ */
+export interface CompactionOutputCursor {
+    outputIndex: number;
+    columnIndex: number;
+    rowStart: number;
+}
+export interface CompactionJobRecord {
+    id: string;
+    tableId: string;
+    sourceManifestVersion: number;
+    sourceSegmentIds: string[];
+    sourceBlockIds: string[];
+    outputBlockIds: string[];
+    cursor: CompactionJobCursor;
+    processedRows: number;
+    sourceStoredBytes: number;
+    outputStoredBytes: number;
+    logicalBytes: number;
+    /** Missing on Phase 6A records, which normalize to copy-v1. */
+    readonly rewritePlan?: CompactionRewritePlan;
+    /** Null for copy-v1; points at the next output for rechunk-v1. */
+    outputCursor?: CompactionOutputCursor | null;
+    /** Immutable execution budget. Zero for copy-v1 jobs. */
+    readonly memoryBudgetBytes?: number;
+    /** Immutable planner estimate. Zero for copy-v1 jobs. */
+    readonly minimumMemoryBytes?: number;
+    /** Immutable stored bytes from newly promoted level-zero sources. Missing on legacy jobs. */
+    readonly level0SourceStoredBytes?: number;
+    /** Immutable stored bytes from the retained level-one anchor. Missing on legacy jobs. */
+    readonly anchorSourceStoredBytes?: number;
+    /** Output partition assigned by the append-row-range L2 policy. Missing on legacy jobs. */
+    readonly outputPartitionOrdinal?: number;
+    /** Immutable maximum compaction output bytes per newly promoted L0 byte. */
+    readonly maxWriteAmplification?: number;
+    /** Immutable exact ceiling for all stored output blocks produced by this job. */
+    readonly maximumOutputStoredBytes?: number;
+    /** Immutable conservative full-block upper bound for the planned output. */
+    readonly plannedOutputStoredBytesUpperBound?: number;
+    /**
+     * Immutable stored bytes already written by cancelled or aborted attempts at these same
+     * sources. The persisted ceiling is reduced by this amount, so attempts share one lifetime
+     * write-amplification budget.
+     */
+    readonly priorAttemptOutputStoredBytes?: number;
+    peakWorkingBytes?: number;
+    outputLogicalBytes?: number;
+    targetLevel: number;
+    state: CompactionJobState;
+    transactionId: string | null;
+    outputSegmentId: string | null;
+    publishedVersion: number | null;
+    revision: number;
+    createdAt: string;
+    updatedAt: string;
+    error?: string;
+}
+export interface CompactionJobRecordUpdate {
+    outputBlockIds?: readonly string[];
+    cursor?: CompactionJobCursor;
+    processedRows?: number;
+    sourceStoredBytes?: number;
+    outputStoredBytes?: number;
+    logicalBytes?: number;
+    outputCursor?: CompactionOutputCursor | null;
+    peakWorkingBytes?: number;
+    outputLogicalBytes?: number;
+    state?: CompactionJobState;
+    transactionId?: string | null;
+    outputSegmentId?: string | null;
+    publishedVersion?: number | null;
+    updatedAt: string;
+    error?: string | null;
+}
+export declare class CompactionJobConflictError extends Error {
+    readonly jobId: string;
+    readonly expectedRevision: number;
+    readonly actualRevision: number | null;
+    readonly name = "CompactionJobConflictError";
+    constructor(jobId: string, expectedRevision: number, actualRevision: number | null);
+}
+export declare const garbageCollectionJobStates: readonly ["planned", "running", "completed"];
+export type GarbageCollectionJobState = (typeof garbageCollectionJobStates)[number];
+export interface GarbageCollectionCursor {
+    manifestIndex: number;
+    segmentIndex: number;
+    blockIndex: number;
+}
+export interface CreateGarbageCollectionJobInput {
+    id: string;
+    candidateManifestVersions: readonly number[];
+    candidateSegmentIds: readonly string[];
+    candidateBlockIds: readonly string[];
+    /** Fixed cutoff used to decide which persisted leases protect a manifest for this job. */
+    leaseCutoff: string;
+    createdAt: string;
+}
+export interface GarbageCollectionJobRecord {
+    id: string;
+    candidateManifestVersions: number[];
+    candidateSegmentIds: string[];
+    candidateBlockIds: string[];
+    cursor: GarbageCollectionCursor;
+    prunedManifestCount: number;
+    alreadyPrunedManifestCount: number;
+    retainedManifestCount: number;
+    missingManifestCount: number;
+    reclaimedSegmentCount: number;
+    retainedSegmentCount: number;
+    missingSegmentCount: number;
+    reclaimedBlockCount: number;
+    retainedBlockCount: number;
+    missingBlockCount: number;
+    reclaimedBlockBytes: number;
+    state: GarbageCollectionJobState;
+    revision: number;
+    leaseCutoff: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface RunGarbageCollectionStepInput {
+    jobId: string;
+    expectedRevision: number;
+    maxItems: number;
+    updatedAt: string;
+}
+export interface GarbageCollectionStepResult {
+    job: GarbageCollectionJobRecord;
+    prunedManifestVersions: number[];
+    alreadyPrunedManifestVersions: number[];
+    retainedManifestVersions: number[];
+    missingManifestVersions: number[];
+    reclaimedSegmentIds: string[];
+    retainedSegmentIds: string[];
+    missingSegmentIds: string[];
+    reclaimedBlockIds: string[];
+    retainedBlockIds: string[];
+    missingBlockIds: string[];
+    reclaimedBlockBytes: number;
+}
+export interface StoragePage<T, Cursor> {
+    records: T[];
+    nextCursor: Cursor | null;
+}
+export declare class GarbageCollectionJobConflictError extends Error {
+    readonly jobId: string;
+    readonly expectedRevision: number;
+    readonly actualRevision: number | null;
+    readonly name = "GarbageCollectionJobConflictError";
+    constructor(jobId: string, expectedRevision: number, actualRevision: number | null);
+}
+export declare class SnapshotManifestMissingError extends Error {
+    readonly version: number;
+    readonly name = "SnapshotManifestMissingError";
+    constructor(version: number);
+}
+export interface GarbageCollectionStepAccounting {
+    examinedManifestCount: number;
+    prunedManifestCount: number;
+    alreadyPrunedManifestCount: number;
+    retainedManifestCount: number;
+    missingManifestCount: number;
+    examinedSegmentCount: number;
+    reclaimedSegmentCount: number;
+    retainedSegmentCount: number;
+    missingSegmentCount: number;
+    examinedBlockCount: number;
+    reclaimedBlockCount: number;
+    retainedBlockCount: number;
+    missingBlockCount: number;
+    reclaimedBlockBytes: number;
+    updatedAt: string;
+}
+export declare class LeaseConflictError extends Error {
+    readonly leaseId: string;
+    readonly expectedRevision: number;
+    readonly actualRevision: number | null;
+    readonly name = "LeaseConflictError";
+    constructor(leaseId: string, expectedRevision: number, actualRevision: number | null);
+}
+export type TransactionStatus = "active" | "committed" | "aborted";
+export interface TransactionRecord {
+    id: string;
+    snapshotVersion: number | null;
+    pendingBlockIds: string[];
+    pendingSegmentIds: string[];
+    status: TransactionStatus;
+    revision: number;
+    startedAt: string;
+    updatedAt: string;
+    committedVersion: number | null;
+}
+export interface TransactionRecordUpdate {
+    snapshotVersion?: number | null;
+    pendingBlockIds?: readonly string[];
+    pendingSegmentIds?: readonly string[];
+    status?: TransactionStatus;
+    updatedAt: string;
+    committedVersion?: number | null;
+}
+export interface BeginTransactionInput {
+    /** Record to create; the store stamps `snapshotVersion` with the current manifest version. */
+    record: Omit<TransactionRecord, "snapshotVersion">;
+    /** Reserve this many row ids for the table in the same atomic step. */
+    reserveRowIds?: {
+        tableId: string;
+        count: number;
+    };
+    /**
+     * Reserve auto-increment values for the column in the same atomic step, first bumping the
+     * counter to at least `atLeast`. `count` may be 0 for a pure bump past explicit values.
+     */
+    reserveAutoIncrement?: {
+        tableId: string;
+        columnId: string;
+        count: number;
+        atLeast?: bigint;
+    };
+}
+export interface BeginTransactionResult {
+    record: TransactionRecord;
+    rowIds?: RowIdRange;
+    autoIncrementValues?: RowIdRange;
+}
+export interface StageTransactionArtifactsInput {
+    transactionId: string;
+    expectedRevision: number;
+    blocks: readonly BlockWrite[];
+    segments: readonly SegmentRecord[];
+    updatedAt: string;
+}
+/**
+ * The commit input carries only the change: added blocks are the transaction's journaled pending
+ * blocks, removals are the superseded ids. The store derives the published manifest from its
+ * stored base, so commit cost scales with the delta rather than the database's total block count.
+ */
+export interface CommitTransactionInput {
+    transactionId: string;
+    changedTableIds?: readonly string[];
+    expectedTransactionRevision: number;
+    expectedManifestVersion: number | null;
+    removedBlockIds?: readonly string[];
+    /**
+     * Per-table unique-key changes, in operation order. Multi-entry commits come from atomic
+     * write scopes; entries for the same table apply sequentially, so in-scope conflicts
+     * (inserting one key twice) fail exactly like cross-commit conflicts.
+     */
+    uniqueKeyChanges?: readonly UniqueKeyChanges[];
+    /** Per-table full-text deltas; at most one entry per table. */
+    ftsChanges?: readonly FtsChanges[];
+    committedAt: string;
+}
+export interface UniqueKeyChanges {
+    tableId: string;
+    keyTokens: readonly string[];
+    requireAbsent: boolean;
+    remove?: boolean;
+    storageMode?: "chunks-v1" | "chunks-v2";
+}
+/** One term's postings within a commit delta or base chunk: parallel rowId/tf arrays. */
+export interface FtsPosting {
+    term: string;
+    rowIds: bigint[];
+    tf: number[];
+}
+/** One indexed column's contribution from one commit: postings for the commit's new rows. */
+export interface FtsColumnDelta {
+    columnId: string;
+    /** Term-sorted postings; rowIds ascending within each term. */
+    postings: FtsPosting[];
+    /** Total tokens the commit's rows contribute to this column — feeds exact BM25 statistics. */
+    totalTokens: number;
+}
+/**
+ * A commit's full-text index deltas, applied atomically with the manifest publish. The store
+ * also closes the stale-writer race here: a commit that adds segments to a table whose record
+ * indexes a column in state "building" or "ready" without carrying that column's delta flips
+ * the column to "invalid" (self-healing rebuild) rather than rejecting the data commit.
+ */
+export interface FtsChanges {
+    tableId: string;
+    columns: readonly FtsColumnDelta[];
+}
+/** The per-term candidate row IDs a full-text index lookup returns, aligned with the query. */
+export interface FtsCandidates {
+    /** Per requested term: ascending unique row IDs whose indexed column contained the term. */
+    rowIdsByTerm: bigint[][];
+}
+/**
+ * Shared candidate-merge core for both stores: fetching chunks is store-specific, but the
+ * term-match rule (exact, or prefix as a term range) and the sorted-unique row-id shape must
+ * never drift between backends — pruning would silently differ per store.
+ */
+export declare function collectFtsCandidates(chunkLists: Iterable<readonly FtsPosting[]>, terms: ReadonlyArray<{
+    term: string;
+    prefix: boolean;
+}>): FtsCandidates;
+/**
+ * Shared stale-writer policy for both stores' commit steps: a commit that adds segments to a
+ * table with active full-text columns but no covering delta flips the uncovered columns to
+ * "invalid" (the index self-heals through a rebuild; the data commit itself always proceeds).
+ * Returns the updated record, or undefined when nothing changes.
+ */
+export declare function invalidateUncoveredFtsColumns(record: TableRecord, coveredColumnIds: ReadonlySet<string>): TableRecord | undefined;
+export declare class UniqueKeyConflictError extends Error {
+    readonly tableId: string;
+    readonly keyToken: string;
+    readonly name = "UniqueKeyConflictError";
+    constructor(tableId: string, keyToken: string);
+}
+export declare class WriteConflictError extends Error {
+    readonly expectedVersion: number | null;
+    readonly actualVersion: number | null;
+    readonly name = "WriteConflictError";
+    constructor(expectedVersion: number | null, actualVersion: number | null);
+}
+export declare class TransactionRecordConflictError extends Error {
+    readonly transactionId: string;
+    readonly expectedRevision: number;
+    readonly actualRevision: number | null;
+    readonly name = "TransactionRecordConflictError";
+    constructor(transactionId: string, expectedRevision: number, actualRevision: number | null);
+}
+export interface BlockWrite {
+    id: string;
+    bytes: Uint8Array;
+}
+export interface TempRunPage {
+    ownerId: string;
+    runId: string;
+    pageIndex: number;
+    bytes: Uint8Array;
+}
+export interface TempOwnerRecord {
+    ownerId: string;
+    expiresAt: string;
+    revision: number;
+}
+export declare class TempOwnerConflictError extends Error {
+    readonly ownerId: string;
+    readonly expectedRevision: number;
+    readonly actualRevision: number | null;
+    readonly name = "TempOwnerConflictError";
+    constructor(ownerId: string, expectedRevision: number, actualRevision: number | null);
+}
+/**
+ * One coherent read of everything query preparation needs before touching blocks: the
+ * current manifest version, the named table records, every segment of the found tables,
+ * and the transaction records those segments reference. Stores that can produce this in
+ * one atomic read collapse the sequential per-record round trips a prepare would
+ * otherwise issue.
+ */
+export interface QueryCatalogState {
+    manifestVersion: number | null;
+    /** Positional per requested name; undefined where the table does not exist. */
+    tables: Array<TableRecord | undefined>;
+    /** Segments of the found tables, sorted by id like listSegments. */
+    segments: SegmentRecord[];
+    /** Records for the segments' transaction ids; missing records are omitted. */
+    transactions: TransactionRecord[];
+    /**
+     * The catalog epoch this state was read at, read in the same atomic storage transaction.
+     * Present when the store maintains an epoch (see `getCatalogProbe`); callers may cache the
+     * state and reuse it while a probe returns the same epoch.
+     */
+    catalogEpoch?: number;
+}
+/**
+ * The two change counters a reader needs to know whether anything it may have cached is
+ * still current, read together in one atomic storage transaction. `manifestVersion` moves on
+ * every data commit. `catalogEpoch` moves on every catalog mutation — table creation, table
+ * record updates (schema migration, full-text index stamps), and every manifest publish —
+ * so an unchanged epoch proves cached catalog state is byte-identical to a fresh read.
+ * Physical garbage collection does not move the epoch: it only deletes records that are
+ * already invisible at every leased version, so cached state stays result-equivalent.
+ */
+export interface CatalogProbe {
+    manifestVersion: number | null;
+    catalogEpoch: number;
+}
+export interface BlockStore {
+    addBlock(id: string, bytes: Uint8Array): Promise<void>;
+    addBlocks(blocks: readonly BlockWrite[]): Promise<void>;
+    getBlock(id: string): Promise<Uint8Array | undefined>;
+    getBlocks(ids: readonly string[]): Promise<Array<Uint8Array | undefined>>;
+    removeBlock(id: string): Promise<void>;
+    listBlockIds(): Promise<string[]>;
+    addTable(record: TableRecord): Promise<void>;
+    getTable(id: string): Promise<TableRecord | undefined>;
+    getTableByName(name: string): Promise<TableRecord | undefined>;
+    listTables(): Promise<TableRecord[]>;
+    updateTable(id: string, expectedRevision: number, update: {
+        columns?: TableColumnRecord[];
+        /** Replaces the full-text index state map; null clears it. */
+        ftsColumns?: Record<string, FtsColumnIndexRecord> | null;
+        /** Replaces the trigger list; null clears it. */
+        triggers?: TriggerRecord[] | null;
+    }): Promise<TableRecord>;
+    /**
+     * Removes a table's catalog record together with everything else keyed to it: its segments,
+     * its full-text base chunks and commit deltas, its unique-key membership, and its row-id and
+     * autoincrement counters. One step, so a crash cannot leave a segment pointing at a table
+     * that no longer exists. Advances the catalog epoch, and fails with a
+     * `TableRecordConflictError` on a revision mismatch, like `updateTable`.
+     *
+     * The table's blocks are the caller's business: they are retired by superseding them in a
+     * commit, which leaves the bytes for the lease-aware collector rather than deleting data a
+     * pinned reader may still be reading.
+     */
+    removeTable(id: string, expectedRevision: number): Promise<void>;
+    /**
+     * Replaces one column's full-text base chunks (term-range partitioned, term-sorted within
+     * each chunk) and deletes commit deltas the new base covers. The caller flips the catalog
+     * state separately via updateTable; orphaned chunks from a lost race are overwritten by the
+     * next build.
+     */
+    writeFtsBase(tableId: string, columnId: string, input: {
+        coversVersion: number;
+        chunks: FtsPosting[][];
+        totalTokens: number;
+    }): Promise<void>;
+    /**
+     * Per-term candidate row IDs from the base chunks plus every commit delta at or below
+     * `upToVersion`, with the column's merged token total for exact BM25 statistics. Prefix
+     * terms match the term range [term, term + "￿"). Reports the merged delta-chunk count so
+     * callers can schedule a rebuild when the tail grows, and the base's covered version —
+     * a concurrent rebuild can publish a base ahead of a reader's snapshot, and a caller
+     * needing snapshot-exact statistics must detect `coversVersion > upToVersion` and fall
+     * back (candidates stay a safe superset either way).
+     */
+    readFtsCandidates(tableId: string, columnId: string, terms: ReadonlyArray<{
+        term: string;
+        prefix: boolean;
+    }>, upToVersion: number): Promise<FtsCandidates & {
+        deltaChunkCount: number;
+        totalTokens: number;
+        coversVersion: number;
+    }>;
+    addSegment(record: SegmentRecord): Promise<void>;
+    getSegment(id: string): Promise<SegmentRecord | undefined>;
+    listSegments(tableId?: string): Promise<SegmentRecord[]>;
+    removeSegment(id: string): Promise<void>;
+    reserveRowIds(tableId: string, count: number): Promise<RowIdRange>;
+    /**
+     * Atomically reserves `count` auto-increment values for the column, first bumping the
+     * counter to at least `atLeast`. `count` may be 0 for a pure bump past explicit values.
+     * Reservations are never returned; aborted transactions leave gaps.
+     */
+    reserveAutoIncrement(tableId: string, columnId: string, count: number, atLeast?: bigint): Promise<RowIdRange>;
+    getExistingUniqueKeys(tableId: string, keyTokens: readonly string[]): Promise<string[]>;
+    getCurrentManifest(): Promise<Manifest | undefined>;
+    /** The current version alone, without materializing the manifest's block list. */
+    getCurrentManifestVersion(): Promise<number | null>;
+    /**
+     * Optional: the current manifest version and catalog epoch in one atomic read. This is the
+     * freshness probe: an unchanged pair proves any cached catalog state is still exactly what
+     * a fresh read would return. Callers that find this absent must not cache catalog state.
+     */
+    getCatalogProbe?(): Promise<CatalogProbe>;
+    /**
+     * Optional: one atomic catalog read for query preparation. Implementations must return
+     * the same records the individual getTableByName/listSegments/getTransactions calls
+     * would; callers fall back to those calls when this is absent.
+     */
+    getQueryCatalogState?(tableNames: readonly string[]): Promise<QueryCatalogState>;
+    getManifest(version: number): Promise<Manifest | undefined>;
+    listManifests(): Promise<Manifest[]>;
+    listManifestPage(afterVersion: number | null, limit: number): Promise<StoragePage<Manifest, number>>;
+    publishManifest(input: PublishManifestInput): Promise<Manifest>;
+    createTransaction(record: TransactionRecord): Promise<void>;
+    /**
+     * Optional: reads the current manifest version, creates the transaction record pinned to it,
+     * and optionally reserves row ids, all in one atomic storage transaction — one round trip
+     * instead of three. Callers fall back to the individual calls when this is absent.
+     */
+    beginTransaction?(input: BeginTransactionInput): Promise<BeginTransactionResult>;
+    getTransaction(id: string): Promise<TransactionRecord | undefined>;
+    getTransactions(ids: readonly string[]): Promise<Array<TransactionRecord | undefined>>;
+    listTransactions(): Promise<TransactionRecord[]>;
+    listTransactionPage(afterId: string | null, limit: number): Promise<StoragePage<TransactionRecord, string>>;
+    updateTransaction(id: string, expectedRevision: number, update: TransactionRecordUpdate): Promise<TransactionRecord>;
+    /**
+     * Optional: stages blocks and segments and journals them on the transaction record in one
+     * atomic storage transaction. Must be equivalent to addBlocks + addSegment(s) + one
+     * updateTransaction appending the new ids, with no intermediate state observable after a
+     * crash. Callers fall back to those calls when this is absent.
+     */
+    stageTransactionArtifacts?(input: StageTransactionArtifactsInput): Promise<TransactionRecord>;
+    /** Publishes the next version; the summary omits the block list, which commits never need. */
+    commitTransaction(input: CommitTransactionInput): Promise<ManifestSummary>;
+    createLease(record: LeaseRecord): Promise<void>;
+    getLease(id: string): Promise<LeaseRecord | undefined>;
+    listLeases(): Promise<LeaseRecord[]>;
+    renewLease(id: string, expectedRevision: number, expiresAt: string): Promise<LeaseRecord>;
+    removeLeaseIfExpired(id: string, expectedRevision: number, expiresAtCutoff: string): Promise<boolean>;
+    removeLease(id: string): Promise<void>;
+    createCompactionJob(record: CompactionJobRecord): Promise<void>;
+    getCompactionJob(id: string): Promise<CompactionJobRecord | undefined>;
+    listCompactionJobs(tableId?: string): Promise<CompactionJobRecord[]>;
+    listCompactionJobPage(afterId: string | null, limit: number): Promise<StoragePage<CompactionJobRecord, string>>;
+    updateCompactionJob(id: string, expectedRevision: number, update: CompactionJobRecordUpdate): Promise<CompactionJobRecord>;
+    cancelCompactionJob(id: string, expectedRevision: number, cancelledAt: string): Promise<CompactionJobRecord>;
+    removeCompactionJob(id: string): Promise<void>;
+    createGarbageCollectionJob(input: CreateGarbageCollectionJobInput): Promise<GarbageCollectionJobRecord>;
+    getGarbageCollectionJob(id: string): Promise<GarbageCollectionJobRecord | undefined>;
+    listGarbageCollectionJobs(): Promise<GarbageCollectionJobRecord[]>;
+    runGarbageCollectionStep(input: RunGarbageCollectionStepInput): Promise<GarbageCollectionStepResult>;
+    removeGarbageCollectionJob(id: string): Promise<void>;
+    putTempRunPage(page: TempRunPage): Promise<void>;
+    getTempRunPage(ownerId: string, runId: string, pageIndex: number): Promise<Uint8Array | undefined>;
+    removeTempRun(ownerId: string, runId: string): Promise<void>;
+    removeTempOwner(ownerId: string): Promise<void>;
+    createTempOwner(record: TempOwnerRecord): Promise<void>;
+    getTempOwner(ownerId: string): Promise<TempOwnerRecord | undefined>;
+    renewTempOwner(ownerId: string, expectedRevision: number, expiresAt: string): Promise<TempOwnerRecord>;
+    removeTempOwnerIfExpired(ownerId: string, expiresAtCutoff: string): Promise<boolean>;
+    listTempOwnerIdsPage(afterOwnerId: string | null, limit: number): Promise<StoragePage<string, string>>;
+    close(): void;
+}
+export declare function createManifest(input: PublishManifestInput): Manifest;
+/**
+ * Normalizes the additive L2 partition metadata while preserving legacy segment records verbatim.
+ */
+export declare function normalizeSegmentRecord(record: SegmentRecord): SegmentRecord;
+export declare function updateTransactionRecord(record: TransactionRecord, update: TransactionRecordUpdate): TransactionRecord;
+export declare function createGarbageCollectionJobRecord(input: CreateGarbageCollectionJobInput): GarbageCollectionJobRecord;
+export declare function normalizeGarbageCollectionJobRecord(record: GarbageCollectionJobRecord): GarbageCollectionJobRecord;
+export declare function advanceGarbageCollectionJobRecord(record: GarbageCollectionJobRecord, accounting: GarbageCollectionStepAccounting): GarbageCollectionJobRecord;
+export declare function normalizeCompactionJobRecord(record: CompactionJobRecord): CompactionJobRecord;
+export declare function updateCompactionJobRecord(record: CompactionJobRecord, update: CompactionJobRecordUpdate): CompactionJobRecord;
+/** Floors an integer-times-double product without rounding the binary double upward. */
+export declare function floorWholeNumberProduct(left: number, right: number, label: string): number;
+//# sourceMappingURL=types.d.ts.map