@minnowdb/core 0.2.1 → 0.4.0

package/dist/testing/simulator.js

@@ -0,0 +1,591 @@
+import { MinnowDatabase } from "../engine/database.js";
+import { MemoryBlockStore } from "../storage/index.js";
+import { FaultInjectingBlockStore } from "./index.js";
+import { md5Hex } from "./sqllogictest.js";
+async function collectStoragePages(read) {
+    const records = [];
+    let cursor = null;
+    for (;;) {
+        const page = await read(cursor);
+        records.push(...page.records);
+        if (page.nextCursor === null)
+            return records;
+        cursor = page.nextCursor;
+    }
+}
+/** Chooses every storage completion from a seeded queue and keeps only a bounded trace tail. */
+export class DeterministicScheduler {
+    #random;
+    #traceLimit;
+    #pending = [];
+    #trace = [];
+    #sequence = 0;
+    #highWater = 0;
+    constructor(seed, traceLimit = 256) {
+        if (!Number.isSafeInteger(traceLimit) || traceLimit < 0) {
+            throw new RangeError("Simulator trace limit must be a non-negative whole number");
+        }
+        this.#random = mulberry32(seed);
+        this.#traceLimit = traceLimit;
+    }
+    get highWater() {
+        return this.#highWater;
+    }
+    get trace() {
+        return this.#trace;
+    }
+    schedule(label, run) {
+        return new Promise((resolve, reject) => {
+            this.#pending.push({ label, run, resolve, reject });
+            this.#highWater = Math.max(this.#highWater, this.#pending.length);
+        });
+    }
+    async settle(promises) {
+        const state = { complete: false };
+        const settled = Promise.allSettled(promises).then((results) => {
+            state.complete = true;
+            return results;
+        });
+        let emptyTurns = 0;
+        while (!state.complete) {
+            await Promise.resolve();
+            const pending = this.#pending.length;
+            if (pending === 0) {
+                // Production maintenance deliberately yields through a timer between bounded pages.
+                // A microtask-only poll can therefore declare deadlock while the next scheduled store
+                // call is merely waiting for its event-loop turn. Let timers advance before counting an
+                // empty turn; the chosen storage completion order remains seeded and deterministic.
+                await nextEventLoopTurn();
+                if (this.#pending.length > 0) {
+                    emptyTurns = 0;
+                    continue;
+                }
+                emptyTurns++;
+                if (emptyTurns > 100) {
+                    throw new Error("Deterministic simulator deadlocked with no scheduled storage operation");
+                }
+                continue;
+            }
+            emptyTurns = 0;
+            const index = Math.floor(this.#random() * pending);
+            const operation = this.#pending.splice(index, 1)[0];
+            if (operation === undefined)
+                continue;
+            try {
+                const value = await operation.run();
+                operation.resolve(value);
+                this.#record(operation.label, "resolved");
+            }
+            catch (error) {
+                operation.reject(error);
+                this.#record(operation.label, "rejected");
+            }
+        }
+        return settled;
+    }
+    #record(operation, outcome) {
+        this.#sequence++;
+        if (this.#traceLimit === 0)
+            return;
+        this.#trace.push({ sequence: this.#sequence, operation, outcome });
+        if (this.#trace.length > this.#traceLimit)
+            this.#trace.shift();
+    }
+}
+function nextEventLoopTurn() {
+    if (typeof MessageChannel === "undefined") {
+        return new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    return new Promise((resolve) => {
+        const channel = new MessageChannel();
+        channel.port1.onmessage = () => {
+            channel.port1.close();
+            channel.port2.close();
+            resolve();
+        };
+        channel.port2.postMessage(undefined);
+    });
+}
+/** Wraps every asynchronous BlockStore entry point in the deterministic completion scheduler. */
+export function scheduledBlockStore(store, scheduler) {
+    return new Proxy(store, {
+        get(target, property) {
+            const value = Reflect.get(target, property, target);
+            if (typeof value !== "function")
+                return value;
+            const method = value;
+            if (property === "close")
+                return (...arguments_) => method.apply(target, arguments_);
+            return (...arguments_) => scheduler.schedule(String(property), async () => method.apply(target, arguments_));
+        },
+    });
+}
+export function generateSimulationPlan(seed, options = {}) {
+    if (!Number.isSafeInteger(seed)) {
+        throw new RangeError("Simulator seed must be a whole number");
+    }
+    const rounds = options.rounds ?? 48;
+    const clients = options.clients ?? 4;
+    const keySpace = options.keySpace ?? 32;
+    if (!Number.isSafeInteger(rounds) || rounds < 1 || rounds > 100_000) {
+        throw new RangeError("Simulator rounds must be between 1 and 100,000");
+    }
+    if (!Number.isSafeInteger(clients) || clients < 1 || clients > 32) {
+        throw new RangeError("Simulator clients must be between 1 and 32");
+    }
+    if (!Number.isSafeInteger(keySpace) || keySpace < 1 || keySpace > 10_000) {
+        throw new RangeError("Simulator key space must be between 1 and 10,000");
+    }
+    if (keySpace < clients) {
+        throw new RangeError("Simulator key space must be at least the client count");
+    }
+    const random = mulberry32(seed);
+    const steps = [];
+    const faultPoints = [
+        "beforeBlockWrite",
+        "afterBlockWrite",
+        "beforeTransactionCommit",
+        "afterTransactionCommit",
+    ];
+    for (let round = 0; round < rounds; round++) {
+        const operations = [];
+        const start = Math.floor(random() * keySpace);
+        let stride = Math.floor(random() * keySpace) + 1;
+        while (greatestCommonDivisor(stride, keySpace) !== 1)
+            stride++;
+        for (let client = 0; client < clients; client++) {
+            // A round is a genuinely concurrent commit race, but its row mutations commute. That gives
+            // the reference model one exact answer instead of guessing which same-key promise linearized
+            // last. Contention still happens at the shared manifest/transaction boundary.
+            const key = ((start + client * stride) % keySpace) + 1;
+            if (random() < 0.18)
+                operations.push({ kind: "delete", client, key });
+            else
+                operations.push({ kind: "put", client, key, amount: Math.floor(random() * 1_000_000) });
+        }
+        steps.push({ kind: "concurrent", operations });
+        if (round % 4 === 3)
+            steps.push({ kind: "checkpoint" });
+        if (round % 12 === 11)
+            steps.push({ kind: "maintenance" });
+        if (round % 20 === 19) {
+            const point = faultPoints[Math.floor(random() * faultPoints.length)] ?? "beforeBlockWrite";
+            steps.push({
+                kind: "fault",
+                point,
+                occurrence: 1,
+                operation: {
+                    kind: "put",
+                    client: Math.floor(random() * clients),
+                    key: Math.floor(random() * keySpace) + 1,
+                    amount: Math.floor(random() * 1_000_000),
+                },
+            });
+        }
+    }
+    steps.push({ kind: "checkpoint" }, { kind: "maintenance" }, { kind: "checkpoint" });
+    return { version: 1, seed, clients, keySpace, steps };
+}
+export function parseSimulationPlan(source) {
+    const value = JSON.parse(source);
+    if (typeof value !== "object" || value === null)
+        throw new TypeError("Simulation plan must be an object");
+    const plan = value;
+    if (plan.version !== 1)
+        throw new TypeError("Simulation plan version must be 1");
+    if (!Number.isSafeInteger(plan.seed))
+        throw new TypeError("Simulation seed must be a whole number");
+    if (!Number.isSafeInteger(plan.clients) || (plan.clients ?? 0) < 1 || (plan.clients ?? 0) > 32) {
+        throw new TypeError("Simulation client count is invalid");
+    }
+    if (!Number.isSafeInteger(plan.keySpace) ||
+        (plan.keySpace ?? 0) < 1 ||
+        (plan.keySpace ?? 0) > 10_000) {
+        throw new TypeError("Simulation key space is invalid");
+    }
+    if ((plan.keySpace ?? 0) < (plan.clients ?? 0)) {
+        throw new TypeError("Simulation key space must be at least the client count");
+    }
+    if (!Array.isArray(plan.steps) || plan.steps.length > 200_000) {
+        throw new TypeError("Simulation steps must be a bounded array");
+    }
+    validateSteps(plan.steps, plan.clients ?? 0, plan.keySpace ?? 0);
+    return plan;
+}
+/** Runs a replayable state-machine plan through production SQL, transactions, and block storage. */
+export async function runSimulation(plan, options = {}) {
+    parseSimulationPlan(JSON.stringify(plan));
+    const base = new MemoryBlockStore();
+    const faults = new FaultController();
+    const scheduler = new DeterministicScheduler(plan.seed ^ 0x5f3759df, options.traceEvents ?? 256);
+    const store = scheduledBlockStore(new FaultInjectingBlockStore(base, (point) => faults.inject(point)), scheduler);
+    let clock = Date.parse("2026-01-01T00:00:00.000Z");
+    let id = 0;
+    const createDatabase = () => new MinnowDatabase(store, {
+        compression: "raw",
+        rowsPerBlock: 8,
+        maxCommitRetries: 16,
+        now: () => new Date(clock),
+        createId: () => `sim-${String(id++)}`,
+        bufferPoolBytes: 0,
+        autoCompact: false,
+        autoCollect: false,
+    });
+    const setup = createDatabase();
+    await drive(scheduler, setup.execute("CREATE TABLE items (id INTEGER PRIMARY KEY, client INTEGER NOT NULL, amount INTEGER NOT NULL)"));
+    await drive(scheduler, setup.close());
+    const clients = Array.from({ length: plan.clients }, createDatabase);
+    const model = new Map();
+    let acceptedMutations = 0;
+    let rejectedConflicts = 0;
+    let injectedFaults = 0;
+    let checkpoints = 0;
+    for (const step of plan.steps) {
+        clock += 1_000;
+        if (step.kind === "concurrent") {
+            const operations = step.operations.map((operation) => executeMutation(requireClient(clients, operation.client), operation)
+                .then(() => {
+                applyMutation(model, operation);
+                acceptedMutations++;
+            })
+                .catch((error) => {
+                if (/manifest changed|conflict/iu.test(errorMessage(error))) {
+                    rejectedConflicts++;
+                    return;
+                }
+                throw error;
+            }));
+            assertSettled(await scheduler.settle(operations));
+            continue;
+        }
+        if (step.kind === "checkpoint") {
+            await assertModel(scheduler, clients[0] ?? setup, model);
+            checkpoints++;
+            continue;
+        }
+        if (step.kind === "maintenance") {
+            const database = clients[0] ?? setup;
+            await drive(scheduler, database.compactTable("items"));
+            // One pass can remove obsolete manifests/segments while their transaction journals are
+            // still provenance roots. The next pass can reclaim those now-unreferenced journals.
+            await drive(scheduler, database.collectGarbage());
+            await drive(scheduler, database.collectGarbage());
+            continue;
+        }
+        const before = new Map(model);
+        const after = new Map(model);
+        applyMutation(after, step.operation);
+        faults.arm(step.point, step.occurrence);
+        const result = await scheduler.settle([
+            executeMutation(requireClient(clients, step.operation.client), step.operation),
+        ]);
+        if (!faults.fired)
+            throw new Error(`Simulation fault was not reached: ${step.point}`);
+        injectedFaults++;
+        faults.disarm();
+        const failedClient = requireClient(clients, step.operation.client);
+        await drive(scheduler, failedClient.close());
+        const replacement = createDatabase();
+        clients[step.operation.client] = replacement;
+        const actual = await readRows(scheduler, replacement);
+        if (sameRows(actual, before)) {
+            if (result[0]?.status === "fulfilled") {
+                throw new Error(`Fault ${step.point} returned success but did not persist its mutation`);
+            }
+            replaceModel(model, before);
+        }
+        else if (sameRows(actual, after))
+            replaceModel(model, after);
+        else
+            throw new Error(`Fault ${step.point} left a state that was neither before nor after the mutation`);
+    }
+    await assertModel(scheduler, clients[0] ?? setup, model);
+    const closeResults = await scheduler.settle(clients.map((client) => client.close()));
+    assertSettled(closeResults);
+    // Measure eventual storage after the simulated tabs release their deliberately cached reader
+    // leases. A fresh maintenance client can then collapse history without an artificial pin from
+    // the workload whose final state has already been checked.
+    const maintenance = createDatabase();
+    const compacted = await compactToFixedPoint(scheduler, maintenance, plan.steps.length);
+    const maintenanceCompactions = compacted.passes;
+    const compactionStop = compacted.stop;
+    const collected = await collectToFixedPoint(scheduler, maintenance, plan.steps.length);
+    let collectionPasses = collected.passes;
+    const collectionTail = [...collected.tail];
+    await assertModel(scheduler, maintenance, model);
+    await drive(scheduler, maintenance.close());
+    const sweeper = createDatabase();
+    const swept = await collectToFixedPoint(scheduler, sweeper, plan.steps.length);
+    collectionPasses += swept.passes;
+    collectionTail.push(...swept.tail);
+    if (collectionTail.length > 8)
+        collectionTail.splice(0, collectionTail.length - 8);
+    await drive(scheduler, sweeper.close());
+    const rows = sortedRows(model);
+    const [segments, transactions, manifests, currentManifest, leases, compactions, storageBytes] = await Promise.all([
+        collectStoragePages((cursor) => base.listSegmentPage(cursor, 256)),
+        collectStoragePages((cursor) => base.listTransactionPage(cursor, 256)),
+        collectStoragePages((cursor) => base.listManifestPage(cursor, 256)),
+        base.getCurrentManifest(),
+        base.listLeases(),
+        base.listCompactionJobs(),
+        base.getLogicalStorageBytes(),
+    ]);
+    const blockCount = currentManifest?.liveBlockCount ?? 0;
+    const blockLimit = plan.keySpace * 16 + 64;
+    const segmentLimit = plan.keySpace + 16;
+    const transactionLimit = segmentLimit + 16;
+    if (blockCount > blockLimit ||
+        segments.length > segmentLimit ||
+        transactions.length > transactionLimit) {
+        const transactionStates = transactions.reduce((counts, transaction) => {
+            counts[transaction.status] = (counts[transaction.status] ?? 0) + 1;
+            return counts;
+        }, {});
+        const compactionStates = compactions.reduce((counts, compaction) => {
+            counts[compaction.state] = (counts[compaction.state] ?? 0) + 1;
+            return counts;
+        }, {});
+        throw new Error(`Storage did not compact to a bound: ${String(blockCount)}/${String(blockLimit)} live blocks, ` +
+            `${String(segments.length)}/${String(segmentLimit)} segments, ` +
+            `${String(transactions.length)}/${String(transactionLimit)} transactions; ` +
+            `${JSON.stringify(transactionStates)} transaction states, ` +
+            `${JSON.stringify(compactionStates)} compaction states, ` +
+            `${String(currentManifest?.liveBlockCount ?? 0)} current blocks, compaction stopped at ${compactionStop}, ` +
+            `${String(manifests.length)} manifests (${String(manifests.filter((manifest) => manifest.prunedAt !== undefined).length)} pruned) remain after ${String(maintenanceCompactions)} compactions ` +
+            `and ${String(collectionPasses)} collection passes; collection tail ${JSON.stringify(collectionTail)}`);
+    }
+    if (manifests.length > 2) {
+        throw new Error(`Garbage collection left ${String(manifests.length)} manifests and ${String(leases.length)} leases`);
+    }
+    if (leases.length !== 0) {
+        throw new Error(`Simulation clients leaked ${String(leases.length)} leases`);
+    }
+    const trace = [...scheduler.trace];
+    return {
+        seed: plan.seed,
+        acceptedMutations,
+        rejectedConflicts,
+        injectedFaults,
+        checkpoints,
+        maintenanceCompactions,
+        compactionStop,
+        collectionPasses,
+        collectionTail,
+        rows,
+        blockCount,
+        segmentCount: segments.length,
+        transactionCount: transactions.length,
+        manifestCount: manifests.length,
+        leaseCount: leases.length,
+        storageBytes,
+        schedulerHighWater: scheduler.highWater,
+        trace,
+        traceDigest: md5Hex(JSON.stringify(trace)),
+    };
+}
+class FaultController {
+    #point;
+    #occurrence = 0;
+    #seen = 0;
+    fired = false;
+    arm(point, occurrence) {
+        this.#point = point;
+        this.#occurrence = occurrence;
+        this.#seen = 0;
+        this.fired = false;
+    }
+    disarm() {
+        this.#point = undefined;
+    }
+    inject(point) {
+        if (point !== this.#point || this.fired)
+            return;
+        this.#seen++;
+        if (this.#seen !== this.#occurrence)
+            return;
+        this.fired = true;
+        throw new Error(`injected ${point} #${String(this.#occurrence)}`);
+    }
+}
+async function drive(scheduler, promise) {
+    const result = (await scheduler.settle([promise]))[0];
+    if (result?.status === "fulfilled")
+        return result.value;
+    throw result?.reason ?? new Error("Scheduled operation did not settle");
+}
+function assertSettled(results) {
+    const failed = results.find((result) => result.status === "rejected");
+    if (failed?.status === "rejected")
+        throw failed.reason;
+}
+function executeMutation(database, operation) {
+    if (operation.kind === "delete") {
+        return database.execute("DELETE FROM items WHERE id = ?", [operation.key]);
+    }
+    return database.execute("INSERT INTO items (id, client, amount) VALUES (?, ?, ?) " +
+        "ON CONFLICT (id) DO UPDATE SET client = excluded.client, amount = excluded.amount", [operation.key, operation.client, operation.amount]);
+}
+function applyMutation(model, operation) {
+    if (operation.kind === "delete")
+        model.delete(operation.key);
+    else
+        model.set(operation.key, {
+            id: operation.key,
+            client: operation.client,
+            amount: operation.amount,
+        });
+}
+async function assertModel(scheduler, database, model) {
+    const actual = await readRows(scheduler, database);
+    if (!sameRows(actual, model)) {
+        throw new Error(`Model mismatch:\nexpected ${JSON.stringify(sortedRows(model))}\nreceived ${JSON.stringify(actual)}`);
+    }
+}
+async function readRows(scheduler, database) {
+    const result = await drive(scheduler, database.query("SELECT id, client, amount FROM items ORDER BY id", { memoize: false }));
+    return result.rows;
+}
+function sameRows(rows, model) {
+    return JSON.stringify(rows) === JSON.stringify(sortedRows(model));
+}
+function sortedRows(model) {
+    return [...model.values()].sort((left, right) => left.id - right.id);
+}
+function replaceModel(target, source) {
+    target.clear();
+    for (const [key, value] of source)
+        target.set(key, value);
+}
+function requireClient(clients, index) {
+    const client = clients[index];
+    if (client === undefined)
+        throw new RangeError(`Simulation client is out of range: ${String(index)}`);
+    return client;
+}
+function validateSteps(steps, clients, keySpace) {
+    const validPoint = new Set([
+        "beforeBlockWrite",
+        "afterBlockWrite",
+        "beforeBlockRead",
+        "afterBlockRead",
+        "beforeTransactionCommit",
+        "afterTransactionCommit",
+    ]);
+    const validateMutation = (value) => {
+        if (typeof value !== "object" || value === null) {
+            throw new TypeError("Simulation mutation must be an object");
+        }
+        const operation = value;
+        if (operation.kind !== "put" && operation.kind !== "delete") {
+            throw new TypeError("Simulation mutation kind is invalid");
+        }
+        const client = operation.client;
+        if (typeof client !== "number" ||
+            !Number.isSafeInteger(client) ||
+            client < 0 ||
+            client >= clients) {
+            throw new TypeError("Simulation mutation has an invalid client");
+        }
+        const key = operation.key;
+        if (typeof key !== "number" || !Number.isSafeInteger(key) || key < 1 || key > keySpace) {
+            throw new TypeError("Simulation mutation has an invalid key");
+        }
+        if (operation.kind === "put" &&
+            (typeof operation.amount !== "number" || !Number.isSafeInteger(operation.amount))) {
+            throw new TypeError("Simulation put has an invalid amount");
+        }
+    };
+    for (const value of steps) {
+        if (typeof value !== "object" || value === null) {
+            throw new TypeError("Simulation step must be an object");
+        }
+        const step = value;
+        if (step.kind === "concurrent") {
+            if (!Array.isArray(step.operations) || step.operations.length > clients * 4) {
+                throw new TypeError("Simulation concurrent step is unbounded");
+            }
+            step.operations.forEach(validateMutation);
+        }
+        else if (step.kind === "fault") {
+            if (typeof step.point !== "string" || !validPoint.has(step.point)) {
+                throw new TypeError("Simulation fault point is invalid");
+            }
+            const occurrence = step.occurrence;
+            if (typeof occurrence !== "number" || !Number.isSafeInteger(occurrence) || occurrence < 1) {
+                throw new TypeError("Simulation fault occurrence is invalid");
+            }
+            validateMutation(step.operation);
+        }
+        else if (step.kind !== "checkpoint" && step.kind !== "maintenance") {
+            throw new TypeError("Simulation step kind is invalid");
+        }
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function compactToFixedPoint(scheduler, database, workloadSteps) {
+    const maximumPasses = Math.min(10_000, workloadSteps + 128);
+    for (let pass = 0; pass < maximumPasses; pass++) {
+        const result = await drive(scheduler, database.compactTable("items"));
+        if (!result.compacted)
+            return { passes: pass, stop: result.skipReason ?? "unknown" };
+    }
+    throw new Error(`Compaction did not converge within ${String(maximumPasses)} passes`);
+}
+async function collectToFixedPoint(scheduler, database, workloadSteps) {
+    const maximumPasses = Math.min(10_000, workloadSteps + 128);
+    let emptyPasses = 0;
+    const tail = [];
+    for (let pass = 1; pass <= maximumPasses; pass++) {
+        const result = await drive(scheduler, database.collectGarbage());
+        tail.push(summarizeCollection(result));
+        if (tail.length > 8)
+            tail.shift();
+        const changed = result.prunedManifestCount +
+            result.reclaimedSegmentCount +
+            result.reclaimedBlockCount +
+            result.reclaimedTransactionCount;
+        // collectGarbage also prunes finished maintenance records after returning its counters. A
+        // zero-artifact pass can therefore remove the final provenance root that lets the next pass
+        // reclaim bytes. Two consecutive empty passes prove both layers have settled.
+        if (changed === 0) {
+            emptyPasses++;
+            if (emptyPasses === 2)
+                return { passes: pass, tail };
+        }
+        else
+            emptyPasses = 0;
+    }
+    throw new Error(`Garbage collection did not converge within ${String(maximumPasses)} passes`);
+}
+function summarizeCollection(result) {
+    return {
+        prunedManifests: result.prunedManifestCount,
+        retainedManifests: result.retainedManifestCount,
+        reclaimedSegments: result.reclaimedSegmentCount,
+        retainedSegments: result.retainedSegmentCount,
+        reclaimedBlocks: result.reclaimedBlockCount,
+        retainedBlocks: result.retainedBlockCount,
+        reclaimedTransactions: result.reclaimedTransactionCount,
+        retainedTransactions: result.retainedTransactionCount,
+    };
+}
+function mulberry32(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let mixed = state;
+        mixed = Math.imul(mixed ^ (mixed >>> 15), mixed | 1);
+        mixed ^= mixed + Math.imul(mixed ^ (mixed >>> 7), mixed | 61);
+        return ((mixed ^ (mixed >>> 14)) >>> 0) / 4_294_967_296;
+    };
+}
+function greatestCommonDivisor(left, right) {
+    let a = left;
+    let b = right;
+    while (b !== 0)
+        [a, b] = [b, a % b];
+    return a;
+}

package/dist/testing/sqllogictest.d.ts

@@ -0,0 +1,89 @@
+import type { QueryResult, QueryValue } from "../engine/index.js";
+export type SqlLogicType = "I" | "R" | "T";
+export type SqlLogicSortMode = "nosort" | "rowsort" | "valuesort";
+export interface SqlLogicLocation {
+    readonly file: string;
+    readonly line: number;
+}
+export interface SqlLogicCondition {
+    readonly kind: "onlyif" | "skipif";
+    readonly engine: string;
+    readonly location: SqlLogicLocation;
+}
+interface LocatedRecord {
+    readonly location: SqlLogicLocation;
+}
+export interface SqlLogicStatement extends LocatedRecord {
+    readonly kind: "statement";
+    readonly expectation: "ok" | "error";
+    readonly sql: string;
+    readonly conditions: readonly SqlLogicCondition[];
+}
+export interface SqlLogicExpectedValues {
+    readonly kind: "values";
+    readonly values: readonly string[];
+}
+export interface SqlLogicExpectedHash {
+    readonly kind: "hash";
+    readonly valueCount: number;
+    readonly hash: string;
+}
+export interface SqlLogicQuery extends LocatedRecord {
+    readonly kind: "query";
+    readonly types: readonly SqlLogicType[];
+    readonly sortMode: SqlLogicSortMode;
+    readonly label?: string;
+    readonly sql: string;
+    readonly expected: SqlLogicExpectedValues | SqlLogicExpectedHash;
+    readonly conditions: readonly SqlLogicCondition[];
+}
+export interface SqlLogicHashThreshold extends LocatedRecord {
+    readonly kind: "hash-threshold";
+    readonly valueCount: number;
+}
+export interface SqlLogicHalt extends LocatedRecord {
+    readonly kind: "halt";
+}
+export type SqlLogicRecord = SqlLogicStatement | SqlLogicQuery | SqlLogicHashThreshold | SqlLogicHalt;
+export interface SqlLogicDatabase {
+    readonly engineName: string;
+    execute(sql: string): Promise<unknown>;
+    query(sql: string): Promise<QueryResult>;
+    close(): void | Promise<void>;
+}
+export interface SqlLogicRunStatistics {
+    readonly files: number;
+    readonly statements: number;
+    readonly queries: number;
+    readonly values: number;
+    readonly skipped: number;
+    readonly halted: boolean;
+    readonly hashThreshold: number;
+}
+export interface SqlLogicRunOptions {
+    /** Audit hook. Returning "continue" records the failure externally and runs the next record. */
+    readonly onFailure?: (failure: SqlLogicFailure, record: SqlLogicStatement | SqlLogicQuery) => "continue" | undefined;
+}
+export declare class SqlLogicParseError extends Error {
+    readonly location: SqlLogicLocation;
+    constructor(message: string, location: SqlLogicLocation);
+}
+export declare class SqlLogicFailure extends Error {
+    readonly location: SqlLogicLocation;
+    readonly sql?: string | undefined;
+    constructor(message: string, location: SqlLogicLocation, sql?: string | undefined, options?: ErrorOptions);
+}
+/** Parses the original SQLite SQLLogicTest format, rejecting unknown extensions. */
+export declare function parseSqlLogicTest(source: string, file?: string): SqlLogicRecord[];
+/**
+ * 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 declare function parseSqlLogicTestLines(lines: Iterable<string> | AsyncIterable<string>, file?: string): AsyncGenerator<SqlLogicRecord>;
+/** Runs already-parsed records against one empty database connection. */
+export declare function runSqlLogicTest(records: Iterable<SqlLogicRecord> | AsyncIterable<SqlLogicRecord>, database: SqlLogicDatabase, options?: SqlLogicRunOptions): Promise<SqlLogicRunStatistics>;
+/** Renders one value with the original SQLite SQLLogicTest adapter rules. */
+export declare function renderSqlLogicValue(value: QueryValue, type: SqlLogicType | undefined): string;
+/** Small browser-safe MD5 implementation for compatibility with the original corpus hashes. */
+export declare function md5Hex(input: string): string;
+export {};