@minnowdb/core 0.2.1 → 0.4.0

package/dist/testing/sqllogictest.js

@@ -0,0 +1,434 @@
+export class SqlLogicParseError extends Error {
+    location;
+    constructor(message, location) {
+        super(`${location.file}:${String(location.line)}: ${message}`);
+        this.location = location;
+        this.name = "SqlLogicParseError";
+    }
+}
+export class SqlLogicFailure extends Error {
+    location;
+    sql;
+    constructor(message, location, sql, options) {
+        super(`${location.file}:${String(location.line)}: ${message}${sql === undefined ? "" : `\n${sql}`}`, options);
+        this.location = location;
+        this.sql = sql;
+        this.name = "SqlLogicFailure";
+    }
+}
+/** Parses the original SQLite SQLLogicTest format, rejecting unknown extensions. */
+export function parseSqlLogicTest(source, file = "<memory>") {
+    const groups = splitRecordGroups(source);
+    return groups.map((group) => parseRecord(group, file));
+}
+/**
+ * Parses a line source one record at a time. The full upstream corpus contains very large files;
+ * this form bounds parser memory to the largest individual record instead of the largest file.
+ */
+export async function* parseSqlLogicTestLines(lines, file = "<stream>") {
+    let current = [];
+    let lineNumber = 0;
+    const finish = () => {
+        if (current.length === 0)
+            return undefined;
+        const record = parseRecord({ lines: current }, file);
+        current = [];
+        return record;
+    };
+    for await (const original of lines) {
+        lineNumber++;
+        const text = original.endsWith("\r") ? original.slice(0, -1) : original;
+        if (text.startsWith("#"))
+            continue;
+        if (text.trim().length === 0) {
+            const record = finish();
+            if (record !== undefined)
+                yield record;
+            continue;
+        }
+        current.push({ text, number: lineNumber });
+    }
+    const record = finish();
+    if (record !== undefined)
+        yield record;
+}
+function splitRecordGroups(source) {
+    const lines = source.replaceAll("\r\n", "\n").replaceAll("\r", "\n").split("\n");
+    const groups = [];
+    let current = [];
+    const finish = () => {
+        if (current.length > 0)
+            groups.push({ lines: current });
+        current = [];
+    };
+    for (const [index, text] of lines.entries()) {
+        if (text.startsWith("#"))
+            continue;
+        if (text.trim().length === 0) {
+            finish();
+            continue;
+        }
+        current.push({ text, number: index + 1 });
+    }
+    finish();
+    return groups;
+}
+function parseRecord(group, file) {
+    let index = 0;
+    const conditions = [];
+    while (index < group.lines.length) {
+        const line = requireLine(group, index, file);
+        const tokens = tokenizeDirective(line.text);
+        if (tokens[0] !== "skipif" && tokens[0] !== "onlyif")
+            break;
+        if (tokens.length !== 2)
+            fail("conditional must name exactly one engine", file, line.number);
+        conditions.push({
+            kind: tokens[0],
+            engine: tokens[1] ?? "",
+            location: { file, line: line.number },
+        });
+        index++;
+    }
+    const header = requireLine(group, index, file);
+    const tokens = tokenizeDirective(header.text);
+    const location = { file, line: header.number };
+    if (tokens[0] === "statement") {
+        if (tokens.length !== 2 || (tokens[1] !== "ok" && tokens[1] !== "error")) {
+            fail("statement must be 'statement ok' or 'statement error'", file, header.number);
+        }
+        const sql = sqlLines(group.lines.slice(index + 1));
+        if (sql.length === 0)
+            fail("statement has no SQL", file, header.number);
+        return {
+            kind: "statement",
+            expectation: tokens[1],
+            sql,
+            conditions,
+            location,
+        };
+    }
+    if (tokens[0] === "query") {
+        if (tokens.length < 2 || tokens.length > 4) {
+            fail("query must be 'query <types> [sort-mode] [label]'", file, header.number);
+        }
+        const typeString = tokens[1] ?? "";
+        const types = [];
+        for (const type of typeString)
+            types.push(type);
+        if (types.length === 0 || types.some((type) => type !== "I" && type !== "R" && type !== "T")) {
+            fail("query type string must contain only I, R, and T", file, header.number);
+        }
+        const sortMode = tokens[2] ?? "nosort";
+        if (sortMode !== "nosort" && sortMode !== "rowsort" && sortMode !== "valuesort") {
+            fail(`unknown query sort mode '${sortMode}'`, file, header.number);
+        }
+        const body = group.lines.slice(index + 1);
+        const separator = body.findIndex((line) => line.text === "----");
+        const queryLines = separator < 0 ? body : body.slice(0, separator);
+        const sql = sqlLines(queryLines);
+        if (sql.length === 0)
+            fail("query has no SQL", file, header.number);
+        const expectedLines = separator < 0 ? [] : body.slice(separator + 1).map((line) => line.text);
+        return {
+            kind: "query",
+            types: types,
+            sortMode,
+            ...(tokens[3] === undefined ? {} : { label: tokens[3] }),
+            sql,
+            expected: parseExpected(expectedLines, file, header.number),
+            conditions,
+            location,
+        };
+    }
+    if (conditions.length > 0) {
+        fail("conditionals may prefix only a statement or query", file, header.number);
+    }
+    if (tokens[0] === "hash-threshold") {
+        if (tokens.length !== 2 || !isNonNegativeInteger(tokens[1])) {
+            fail("hash-threshold must be a non-negative whole number", file, header.number);
+        }
+        return { kind: "hash-threshold", valueCount: Number(tokens[1]), location };
+    }
+    if (tokens[0] === "halt") {
+        if (tokens.length !== 1 || group.lines.length !== 1) {
+            fail("halt does not accept arguments", file, header.number);
+        }
+        return { kind: "halt", location };
+    }
+    fail(`unknown SQLLogicTest directive '${tokens[0] ?? ""}'`, file, header.number);
+}
+function parseExpected(lines, file, line) {
+    if (lines.length !== 1)
+        return { kind: "values", values: lines };
+    const match = /^(\d+) values hashing to ([0-9a-fA-F]{32})$/.exec(lines[0] ?? "");
+    if (match === null)
+        return { kind: "values", values: lines };
+    const valueCount = Number(match[1]);
+    if (!Number.isSafeInteger(valueCount))
+        fail("hashed value count is too large", file, line);
+    return { kind: "hash", valueCount, hash: (match[2] ?? "").toLowerCase() };
+}
+function tokenizeDirective(line) {
+    return line.trim().split(/\s+/u);
+}
+function sqlLines(lines) {
+    return lines.map((line) => line.text).join("\n");
+}
+function requireLine(group, index, file) {
+    const line = group.lines[index];
+    if (line === undefined) {
+        const last = group.lines.at(-1)?.number ?? 1;
+        fail("conditional is missing its statement or query", file, last);
+    }
+    return line;
+}
+function isNonNegativeInteger(value) {
+    return value !== undefined && /^\d+$/u.test(value) && Number.isSafeInteger(Number(value));
+}
+function fail(message, file, line) {
+    throw new SqlLogicParseError(message, { file, line });
+}
+/** Runs already-parsed records against one empty database connection. */
+export async function runSqlLogicTest(records, database, options = {}) {
+    let statements = 0;
+    let queries = 0;
+    let values = 0;
+    let skipped = 0;
+    let hashThreshold = 8;
+    let halted = false;
+    const labels = new Map();
+    try {
+        for await (const record of records) {
+            if (record.kind === "hash-threshold") {
+                hashThreshold = record.valueCount;
+                continue;
+            }
+            if (record.kind === "halt") {
+                halted = true;
+                break;
+            }
+            if (shouldSkip(record.conditions, database.engineName)) {
+                skipped++;
+                if (record.kind === "query" && record.label !== undefined) {
+                    rememberExpectedLabel(record, labels);
+                }
+                continue;
+            }
+            try {
+                if (record.kind === "statement") {
+                    statements++;
+                    await runStatement(record, database);
+                    continue;
+                }
+                queries++;
+                const actual = await runQuery(record, database);
+                values += actual.length;
+                compareExpected(record, actual, hashThreshold);
+                rememberActualLabel(record, actual, labels);
+            }
+            catch (error) {
+                if (error instanceof SqlLogicFailure && options.onFailure?.(error, record) === "continue") {
+                    continue;
+                }
+                throw error;
+            }
+        }
+    }
+    finally {
+        await database.close();
+    }
+    return { files: 1, statements, queries, values, skipped, halted, hashThreshold };
+}
+function shouldSkip(conditions, engineName) {
+    const engine = engineName.toLowerCase();
+    return conditions.some((condition) => {
+        const matches = condition.engine.toLowerCase() === engine;
+        return condition.kind === "skipif" ? matches : !matches;
+    });
+}
+async function runStatement(record, database) {
+    let failure;
+    try {
+        await database.execute(record.sql);
+    }
+    catch (error) {
+        failure = error;
+    }
+    if (record.expectation === "error") {
+        if (failure !== undefined)
+            return;
+        throw new SqlLogicFailure("statement succeeded; expected an error", record.location, record.sql);
+    }
+    if (failure !== undefined) {
+        throw new SqlLogicFailure("statement failed; expected success", record.location, record.sql, {
+            cause: failure,
+        });
+    }
+}
+async function runQuery(record, database) {
+    let result;
+    try {
+        result = await database.query(record.sql);
+    }
+    catch (cause) {
+        throw new SqlLogicFailure("query failed", record.location, record.sql, { cause });
+    }
+    if (result.columns.length !== record.types.length) {
+        throw new SqlLogicFailure(`wrong column count: expected ${String(record.types.length)}, received ${String(result.columns.length)}`, record.location, record.sql);
+    }
+    const rows = result.rows.map((row) => result.columns.map((column, index) => renderSqlLogicValue(row[column] ?? null, record.types[index])));
+    if (record.sortMode === "rowsort")
+        rows.sort(compareRows);
+    const flattened = rows.flat();
+    if (record.sortMode === "valuesort")
+        flattened.sort(compareText);
+    return flattened;
+}
+function compareRows(left, right) {
+    for (let index = 0; index < left.length; index++) {
+        const comparison = compareText(left[index] ?? "", right[index] ?? "");
+        if (comparison !== 0)
+            return comparison;
+    }
+    return 0;
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/** Renders one value with the original SQLite SQLLogicTest adapter rules. */
+export function renderSqlLogicValue(value, type) {
+    if (value === null)
+        return "NULL";
+    if (type === "I") {
+        const numeric = typeof value === "boolean" ? Number(value) : Number(value);
+        if (!Number.isFinite(numeric))
+            return "0";
+        return String(Math.trunc(numeric));
+    }
+    if (type === "R") {
+        const numeric = typeof value === "boolean" ? Number(value) : Number(value);
+        return Number.isFinite(numeric) ? numeric.toFixed(3) : "0.000";
+    }
+    const rendered = value instanceof Date ? value.toISOString() : String(value);
+    if (rendered.length === 0)
+        return "(empty)";
+    return rendered.replaceAll(/[^ -~]/gu, "@");
+}
+function compareExpected(record, actual, hashThreshold) {
+    const hashed = hashThreshold > 0 && actual.length > hashThreshold;
+    if (hashed) {
+        if (record.expected.kind !== "hash") {
+            throw new SqlLogicFailure(`result exceeds hash-threshold ${String(hashThreshold)} but the expected result is not hashed`, record.location, record.sql);
+        }
+        const hash = md5Hex(withTrailingNewlines(actual));
+        if (record.expected.valueCount !== actual.length || record.expected.hash !== hash) {
+            throw new SqlLogicFailure(`wrong result hash: expected ${String(record.expected.valueCount)} values hashing to ${record.expected.hash}, received ${String(actual.length)} values hashing to ${hash}`, record.location, record.sql);
+        }
+        return;
+    }
+    if (record.expected.kind === "hash") {
+        throw new SqlLogicFailure(`expected result is hashed but ${String(actual.length)} values do not exceed hash-threshold ${String(hashThreshold)}`, record.location, record.sql);
+    }
+    if (!equalValues(record.expected.values, actual)) {
+        const expected = describeValues(record.expected.values, hashThreshold);
+        const received = describeValues(actual, hashThreshold);
+        throw new SqlLogicFailure(`wrong result:\nexpected ${expected}\nreceived ${received}`, record.location, record.sql);
+    }
+}
+function equalValues(expected, actual) {
+    return (expected.length === actual.length && expected.every((value, index) => value === actual[index]));
+}
+function describeValues(values, hashThreshold) {
+    if (hashThreshold > 0 && values.length > hashThreshold) {
+        return `${String(values.length)} values hashing to ${md5Hex(withTrailingNewlines(values))}`;
+    }
+    return JSON.stringify(values);
+}
+function rememberExpectedLabel(record, labels) {
+    if (record.label === undefined)
+        return;
+    const hash = record.expected.kind === "hash"
+        ? record.expected.hash
+        : md5Hex(withTrailingNewlines(record.expected.values));
+    rememberLabel(record.label, hash, record.location, labels);
+}
+function rememberActualLabel(record, values, labels) {
+    if (record.label === undefined)
+        return;
+    rememberLabel(record.label, md5Hex(withTrailingNewlines(values)), record.location, labels);
+}
+function rememberLabel(label, hash, location, labels) {
+    const previous = labels.get(label);
+    if (previous !== undefined && previous.hash !== hash) {
+        throw new SqlLogicFailure(`labeled result '${label}' differs from ${previous.location.file}:${String(previous.location.line)}`, location);
+    }
+    labels.set(label, { hash, location });
+}
+function withTrailingNewlines(values) {
+    return values.map((value) => `${value}\n`).join("");
+}
+/** Small browser-safe MD5 implementation for compatibility with the original corpus hashes. */
+export function md5Hex(input) {
+    const bytes = new TextEncoder().encode(input);
+    const paddedLength = Math.ceil((bytes.length + 9) / 64) * 64;
+    const padded = new Uint8Array(paddedLength);
+    padded.set(bytes);
+    padded[bytes.length] = 0x80;
+    const bitLength = BigInt(bytes.length) * 8n;
+    const view = new DataView(padded.buffer);
+    view.setUint32(paddedLength - 8, Number(bitLength & 0xffffffffn), true);
+    view.setUint32(paddedLength - 4, Number((bitLength >> 32n) & 0xffffffffn), true);
+    let a0 = 0x67452301;
+    let b0 = 0xefcdab89;
+    let c0 = 0x98badcfe;
+    let d0 = 0x10325476;
+    const words = new Uint32Array(16);
+    for (let offset = 0; offset < paddedLength; offset += 64) {
+        for (let index = 0; index < 16; index++)
+            words[index] = view.getUint32(offset + index * 4, true);
+        let a = a0;
+        let b = b0;
+        let c = c0;
+        let d = d0;
+        for (let index = 0; index < 64; index++) {
+            const { mix, word } = md5Round(index, b, c, d);
+            const rotated = rotateLeft((a + mix + (MD5_CONSTANTS[index] ?? 0) + (words[word] ?? 0)) >>> 0, MD5_SHIFTS[index]);
+            a = d;
+            d = c;
+            c = b;
+            b = (b + rotated) >>> 0;
+        }
+        a0 = (a0 + a) >>> 0;
+        b0 = (b0 + b) >>> 0;
+        c0 = (c0 + c) >>> 0;
+        d0 = (d0 + d) >>> 0;
+    }
+    return [a0, b0, c0, d0].map(littleEndianHex).join("");
+}
+function md5Round(index, b, c, d) {
+    if (index < 16)
+        return { mix: (b & c) | (~b & d), word: index };
+    if (index < 32)
+        return { mix: (d & b) | (~d & c), word: (5 * index + 1) % 16 };
+    if (index < 48)
+        return { mix: b ^ c ^ d, word: (3 * index + 5) % 16 };
+    return { mix: c ^ (b | ~d), word: (7 * index) % 16 };
+}
+function rotateLeft(value, shift) {
+    const bits = shift ?? 0;
+    return ((value << bits) | (value >>> (32 - bits))) >>> 0;
+}
+function littleEndianHex(value) {
+    let output = "";
+    for (let index = 0; index < 4; index++) {
+        output += ((value >>> (index * 8)) & 0xff).toString(16).padStart(2, "0");
+    }
+    return output;
+}
+const MD5_SHIFTS = [
+    7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14,
+    20, 5, 9, 14, 20, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 6, 10, 15, 21, 6,
+    10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21,
+];
+const MD5_CONSTANTS = Array.from({ length: 64 }, (_, index) => Math.floor(Math.abs(Math.sin(index + 1)) * 2 ** 32));

package/dist/transactions/index.d.ts

@@ -1,8 +1,16 @@
-import { type BlockStore, type BlockWrite, type LeaseKind, type LeaseRecord, type ManifestSummary, type RowIdRange, type SegmentRecord, type TransactionRecord, type FtsChanges, type UniqueKeyChanges } from "../storage/index.js";
+import { type BlockStore, type BlockWrite, type LeaseKind, type LeaseRecord, MAX_LEASE_TTL_MS, type ManifestSummary, type RowIdRange, type SegmentRecord, type TableRecord, type TransactionRecord, type FtsChanges, type UniqueKeyChanges } from "../storage/types.js";
 export interface TransactionManagerOptions {
     now?: () => Date;
     createId?: () => string;
+    /** Durable writer deadline; live transactions renew every third of this interval. */
+    transactionTtlMs?: number;
+    /** Test seam for deterministic collection of an abandoned transaction reference. */
+    createWeakRef?: (transaction: DatabaseTransaction) => {
+        deref(): DatabaseTransaction | undefined;
+    };
 }
+export declare const DEFAULT_TRANSACTION_TTL_MS = 30000;
+export { MAX_LEASE_TTL_MS };
 export interface RecoveryOptions {
     staleBefore: Date;
     removePendingBlocks?: boolean;
@@ -23,24 +31,47 @@ export interface OpenLeasedSnapshotOptions {
     kind?: LeaseKind;
     version?: number | null;
 }
+export interface BeginDeferredOptions {
+    /**
+     * Pins the captured snapshot with a renewable durable reader lease until this transaction
+     * either persists its own durable owner or finishes. Enabled by default; tightly bounded
+     * internal statements that cannot idle may opt out to retain the one-write fast path.
+     */
+    durableSnapshot?: boolean;
+}
 export declare class TransactionClosedError extends Error {
     readonly transactionId: string;
     readonly name = "TransactionClosedError";
     constructor(transactionId: string);
 }
+/** Opaque staged-state marker used by SQL SAVEPOINT. */
+export interface TransactionCheckpoint {
+    readonly transactionId: string;
+    readonly pendingBlockIds: readonly string[];
+    readonly pendingSegmentIds: readonly string[];
+    readonly uniqueKeyChanges: readonly UniqueKeyChanges[];
+    readonly ftsChanges: readonly FtsChanges[];
+    readonly compactionJobId: string | null;
+    readonly compactionSourceBlockIds: readonly string[];
+    readonly levelZeroSegmentLimits: ReadonlyArray<{
+        tableId: string;
+        limit: number;
+    }>;
+    readonly changedTableIds: readonly string[];
+    readonly logicallyUnchanged: boolean;
+}
 export declare class Snapshot {
-    #private;
     private readonly store;
     readonly version: number | null;
-    constructor(store: BlockStore, version: number | null, blockIds: readonly string[]);
-    listBlockIds(): string[];
-    hasBlock(id: string): boolean;
+    constructor(store: BlockStore, version: number | null);
+    hasBlock(id: string): Promise<boolean>;
+    hasBlocks(ids: readonly string[]): Promise<boolean[]>;
     getBlock(id: string): Promise<Uint8Array | undefined>;
 }
 export declare class LeasedSnapshot extends Snapshot {
     #private;
     private readonly now;
-    constructor(store: BlockStore, version: number | null, blockIds: readonly string[], record: LeaseRecord, now: () => Date);
+    constructor(store: BlockStore, version: number | null, record: LeaseRecord, now: () => Date);
     get leaseId(): string;
     get expiresAt(): Date;
     getBlock(id: string): Promise<Uint8Array | undefined>;
@@ -61,15 +92,44 @@ export declare class DatabaseTransaction {
     #private;
     private readonly store;
     private readonly now;
-    constructor(store: BlockStore, record: TransactionRecord, now: () => Date, options?: {
+    private readonly ttlMs;
+    constructor(store: BlockStore, record: TransactionRecord, now: () => Date, ttlMs: number, createWeakRef: (transaction: DatabaseTransaction) => {
+        deref(): DatabaseTransaction | undefined;
+    }, options?: {
         persisted?: boolean;
+        initialCatalogProbe?: {
+            catalogEpoch: number;
+            manifestVersion: number | null;
+            schemaEpoch: number;
+        };
+        snapshotLease?: LeasedSnapshot;
     });
     get id(): string;
     get status(): TransactionRecord["status"];
     get snapshotVersion(): number | null;
     get pendingBlockIds(): string[];
     get pendingSegmentIds(): string[];
-    get supersededBlockIds(): string[];
+    /** Process-local segments retained for a bounded single-shot commit. */
+    get deferredSegments(): SegmentRecord[];
+    get pendingTableNextRowId(): bigint | undefined;
+    get initialCatalogProbe(): {
+        catalogEpoch: number;
+        manifestVersion: number | null;
+        schemaEpoch: number;
+    } | undefined;
+    /** Exact local commit contribution; undefined until this transaction commits. */
+    get committedCatalogContribution(): {
+        transaction: TransactionRecord;
+        segments: SegmentRecord[];
+        initialCatalogProbe?: {
+            catalogEpoch: number;
+            manifestVersion: number | null;
+            schemaEpoch: number;
+        };
+    } | undefined;
+    get compactionSourceBlockIds(): string[];
+    /** Extends durable ownership; scope owners call this while user code is legitimately waiting. */
+    renew(): Promise<void>;
     /**
      * Counts every registration this transaction carries: staged blocks and segments, unique-key
      * entries, full-text entries, and supersessions. A caller that fails part-way through a
@@ -78,6 +138,12 @@ export declare class DatabaseTransaction {
      * since there is no statement-level rollback inside a transaction.
      */
     get stagedWorkCount(): number;
+    /** Captures all publish-relevant state; row-id/autoincrement reservations deliberately burn. */
+    checkpoint(): TransactionCheckpoint;
+    /** Conservative retained-size estimate used to refuse savepoint clones before allocating. */
+    checkpointRetainedBytes(): number;
+    /** Rewinds staged artifacts and every in-memory commit delta to one earlier checkpoint. */
+    rollbackTo(checkpoint: TransactionCheckpoint): Promise<void>;
     snapshot(): Promise<Snapshot>;
     getBlock(id: string): Promise<Uint8Array | undefined>;
     stageBlock(id: string, bytes: Uint8Array): Promise<void>;
@@ -110,6 +176,8 @@ export declare class DatabaseTransaction {
     stageSegment(record: SegmentRecord): Promise<void>;
     /** Reconciles a persisted segment whose journal update was interrupted. */
     stageExistingSegment(segmentId: string): Promise<void>;
+    /** Atomically adopts an exact unpublished output left by an aborted attempt of this job. */
+    adoptAbortedCompactionSegment(record: SegmentRecord, abortedOwner: TransactionRecord): Promise<void>;
     /**
      * Records that this commit changes a table's logical content without staging a segment for
      * it — dropping the table, for instance, whose only publish is the retirement of its blocks.
@@ -132,7 +200,14 @@ export declare class DatabaseTransaction {
      * and token totals summed — so a scope can insert into one FTS table any number of times.
      */
     setFtsChanges(changes: FtsChanges): void;
-    supersedeBlocks(blockIds: readonly string[]): void;
+    /**
+     * Binds a physical retirement to one persisted compaction job. Stores revalidate the job,
+     * source segments, current manifest, and aliases atomically with publication; this in-memory
+     * declaration is intent, never authority to hide arbitrary blocks.
+     */
+    setCompactionIntent(compactionJobId: string, sourceBlockIds: readonly string[]): void;
+    /** Adds an adapter-enforced post-commit level-zero ceiling for one table. */
+    limitLevelZeroSegments(tableId: string, limit: number): void;
     commit(): Promise<ManifestSummary>;
     rebase(): Promise<Snapshot>;
     abort(): Promise<void>;
@@ -142,14 +217,16 @@ export declare class TransactionManager {
     private readonly store;
     constructor(store: BlockStore, options?: TransactionManagerOptions);
     begin(): Promise<DatabaseTransaction>;
+    /** Atomically reserves an invisible catalog table for a create-and-populate transaction. */
+    beginWithPendingTable(record: TableRecord, expectedCatalogEpoch: number): Promise<DatabaseTransaction>;
     /**
-     * Begins a transaction without a storage write: the record is pinned at the current manifest
-     * version (one read) and written only when something is staged through the two-step methods
-     * — or never, when the whole write goes through `stageArtifactsAndCommit` on a store with
-     * the single-shot `writeTransaction`, or the transaction aborts untouched. For writes whose
-     * artifacts need no prior reservation; `beginWithReservation` is the shape for the rest.
+     * Begins without a transaction record. By default a renewable reader lease durably pins the
+     * probed manifest until the first two-step stage hands ownership to a transaction record. The
+     * record and lease are both omitted only for internal, uninterrupted single-shot writes that
+     * opt out and publish through `writeTransaction`. For writes whose artifacts need no prior
+     * reservation; `beginWithReservation` is the shape for the rest.
      */
-    beginDeferred(): Promise<DatabaseTransaction>;
+    beginDeferred(options?: BeginDeferredOptions): Promise<DatabaseTransaction>;
     /**
      * Begins a transaction at the current manifest version and optionally reserves row ids and
      * auto-increment values in the same step. Stores implementing the atomic `beginTransaction`
@@ -186,4 +263,3 @@ export declare class TransactionManager {
     removeExpiredLeases(at?: Date): Promise<string[]>;
     recover(options: RecoveryOptions): Promise<RecoveryReport>;
 }
-//# sourceMappingURL=index.d.ts.map