@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/adapters/sqliteCostlyReads.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The SQLite reads that could hold the whole server, and where they run.
+ *
+ * node:sqlite runs a statement on the thread that asked, to its end: a
+ * filtered list, a count or a breakdown over a million rows held every other
+ * request — a page of another table, the runtime check, a sign-in — for as
+ * long as it took (sqliteStatementProcess.ts says why a thread cannot help).
+ * Such a read runs in the statement process instead, on a read-only handle
+ * of its own on the same file, and the server goes on answering; its cap
+ * (30 seconds) stops one that would never finish.
+ *
+ * Which reads: those over a large relation that cannot stop after the page —
+ * an aggregate, a filter over a scan (one that matches rarely reads the whole
+ * table to fill twenty rows), or a plan that sorts everything it found
+ * (`USE TEMP B-TREE FOR ORDER BY`). A filter an index searches — an equality,
+ * or a keyset page's range (keysetPage.ts) — starts where its rows are and
+ * stays. A large relation is a table of
+ * PROCESS_ROWS or more, one whose size is unknown (a file past a quarter
+ * gigabyte that ANALYZE never read), or a SQL view, which may cost anything.
+ * An unfiltered page walked in an index's order stops at its LIMIT and stays
+ * in process: the child costs about 27 ms to start, which is more than that
+ * page ever took. An in-memory database has no second handle and never moves.
+ */
+import type { DatabaseSync, SQLInputValue } from 'node:sqlite';
+import type { DatabaseSchema } from '../shared/schema.js';
+/** Past this many rows a scan of a table is worth a process start: about 50 ms of filtering on one thread. */
+export declare const PROCESS_ROWS = 250000;
+/** The quoted names of the relations a read of which may stall: large, of unknown size, or a view. */
+export declare function heavyRelations(schema: DatabaseSchema | null): string[];
+/** Whether this statement may hold the thread: it reads a heavy relation and cannot stop at its page. */
+export declare function stalls(db: DatabaseSync, text: string, params: readonly SQLInputValue[], relations: readonly string[], aggregate: boolean): boolean;
+/** Run one compiled read in the statement process: its rows as objects, raw, as the in-process driver reads them. */
+export declare function readInProcess(file: string, text: string, params: readonly SQLInputValue[]): Promise<Array<Record<string, unknown>>>;

package/dist/adapters/sqliteCostlyReads.js

@@ -0,0 +1,49 @@
+import { ANSI_STYLE, MAX_LIMIT } from './adapter.js';
+import { scaleRows, scalesOf } from './sqliteDecimals.js';
+import { runInStatementProcess } from './sqliteStatementProcess.js';
+import { cancellation, STATEMENT_TIMEOUT_MS } from './statementControl.js';
+/** Past this many rows a scan of a table is worth a process start: about 50 ms of filtering on one thread. */
+export const PROCESS_ROWS = 250_000;
+const heavy = new WeakMap();
+/** The quoted names of the relations a read of which may stall: large, of unknown size, or a view. */
+export function heavyRelations(schema) {
+    if (!schema)
+        return [];
+    let names = heavy.get(schema);
+    if (!names) {
+        names = schema.tables
+            .filter((table) => table.isView || table.approxRows === undefined || table.approxRows >= PROCESS_ROWS)
+            .map((table) => ANSI_STYLE.quote(table.name));
+        heavy.set(schema, names);
+    }
+    return names;
+}
+/** Whether this statement may hold the thread: it reads a heavy relation and cannot stop at its page. */
+export function stalls(db, text, params, relations, aggregate) {
+    if (!relations.some((name) => text.includes(name)))
+        return false;
+    if (aggregate)
+        return true;
+    try {
+        const plan = db.prepare(`EXPLAIN QUERY PLAN ${text}`).all(...params).map((row) => row.detail);
+        /* A sort of everything found; a sort of ties within an index's order
+           ("LAST TERM", "RIGHT PART") only reads as far as the page. */
+        if (plan.some((detail) => /TEMP B-TREE FOR (ORDER BY|GROUP BY|DISTINCT)/.test(detail)))
+            return true;
+        /* A filter over a scan may read the whole table to fill its page. An
+           index search (an equality, or a range such as a keyset page's bound)
+           starts where the rows are and reads in the list's order. */
+        return /\bWHERE\b/i.test(text) && plan.some((detail) => /^SCAN (?!CONSTANT ROW|\()/.test(detail));
+    }
+    catch {
+        /* A statement that cannot be planned will not prepare either; it fails
+           in process with the engine's own words. */
+        return false;
+    }
+}
+/** Run one compiled read in the statement process: its rows as objects, raw, as the in-process driver reads them. */
+export async function readInProcess(file, text, params) {
+    const signal = cancellation() ?? new AbortController().signal;
+    const answer = await runInStatementProcess({ file, text, fallback: text, bounded: false, limit: MAX_LIMIT + 1, refuseReserved: false, params: [...params] }, STATEMENT_TIMEOUT_MS, signal);
+    return scaleRows(answer.rows.map((row) => Object.fromEntries(answer.columns.map((column, at) => [column, row[at]]))), answer.columns, scalesOf(answer.types.map((type) => ({ type }))));
+}

package/dist/adapters/sqliteDecimals.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A decimal column keeps its scale, as it does on Postgres.
+ *
+ * SQLite stores `numeric(12,2)` 38 as the integer 38 and 19.9 as the float
+ * 19.9, so the scale the column was declared with is gone by the time a row is
+ * read. `pg` returns the same column as the text "38.00" and "19.90", and the
+ * money display depends on that text to show cents. This reads the declared
+ * type the driver reports for each result column (once per statement, not per
+ * cell) and says a number the way Postgres says a numeric. A column with no
+ * declared scale, an integer column and an expression (no declared type) are
+ * left exactly as they were.
+ */
+/** The scale a declared type asks for, when it is a DECIMAL/NUMERIC with one above zero. */
+export declare function declaredScale(type: string | null | undefined): number;
+/** Per output position, the scale to apply, or undefined when no column needs one. */
+export declare function scalesOf(columns: ReadonlyArray<{
+    type?: string | null;
+}>): number[] | undefined;
+/** Rows read as objects: apply the scales of the columns named by `names` (positional, as `scalesOf`). */
+export declare function scaleRows(rows: Array<Record<string, unknown>>, names: ReadonlyArray<string | null | undefined>, scales: number[] | undefined): Array<Record<string, unknown>>;
+/** Rows read as arrays. */
+export declare function scaleArrays(rows: unknown[][], scales: number[] | undefined): unknown[][];

package/dist/adapters/sqliteDecimals.js

@@ -0,0 +1,57 @@
+/**
+ * A decimal column keeps its scale, as it does on Postgres.
+ *
+ * SQLite stores `numeric(12,2)` 38 as the integer 38 and 19.9 as the float
+ * 19.9, so the scale the column was declared with is gone by the time a row is
+ * read. `pg` returns the same column as the text "38.00" and "19.90", and the
+ * money display depends on that text to show cents. This reads the declared
+ * type the driver reports for each result column (once per statement, not per
+ * cell) and says a number the way Postgres says a numeric. A column with no
+ * declared scale, an integer column and an expression (no declared type) are
+ * left exactly as they were.
+ */
+const DECLARED_SCALE = /^\s*(?:decimal|numeric)\s*\(\s*\d+\s*,\s*(\d+)\s*\)\s*$/i;
+/** The scale a declared type asks for, when it is a DECIMAL/NUMERIC with one above zero. */
+export function declaredScale(type) {
+    if (!type)
+        return 0;
+    const scale = Number(DECLARED_SCALE.exec(type)?.[1] ?? 0);
+    return scale > 0 ? scale : 0;
+}
+/** Per output position, the scale to apply, or undefined when no column needs one. */
+export function scalesOf(columns) {
+    let scales;
+    columns.forEach((column, at) => {
+        const scale = declaredScale(column.type);
+        if (scale > 0)
+            (scales ??= Array.from({ length: columns.length }, () => 0))[at] = scale;
+    });
+    return scales;
+}
+/** One stored value, said with `scale` places. Text, null and bytes pass through. */
+function withScale(value, scale) {
+    if (typeof value === 'bigint')
+        return `${value}.${'0'.repeat(scale)}`;
+    if (typeof value === 'number' && Number.isFinite(value) && Math.abs(value) < 1e15)
+        return value.toFixed(scale);
+    return value;
+}
+/** Rows read as objects: apply the scales of the columns named by `names` (positional, as `scalesOf`). */
+export function scaleRows(rows, names, scales) {
+    if (!scales)
+        return rows;
+    const apply = names.flatMap((name, at) => (name != null && scales[at] > 0 ? [[name, scales[at]]] : []));
+    for (const row of rows)
+        for (const [name, scale] of apply)
+            if (row && name in row)
+                row[name] = withScale(row[name], scale);
+    return rows;
+}
+/** Rows read as arrays. */
+export function scaleArrays(rows, scales) {
+    if (!scales)
+        return rows;
+    for (const row of rows)
+        scales.forEach((scale, at) => scale > 0 && at < row.length && (row[at] = withScale(row[at], scale)));
+    return rows;
+}

package/dist/adapters/sqliteHandles.d.ts

@@ -0,0 +1,43 @@
+import type { DatabaseSync, StatementSync } from 'node:sqlite';
+/**
+ * Wait rather than fail when someone else holds the file.
+ *
+ * A SQLite database is usually a file another process is also using — the
+ * application whose data this is, a migration, a test — and one writer at a
+ * time is the whole locking model. Without a busy timeout the very next read
+ * during someone else's write comes back "database is locked", which reads
+ * as a broken tool rather than as a lock that would have cleared in
+ * milliseconds. Five seconds is long enough to outlast an ordinary write and
+ * short enough that a genuinely stuck writer still surfaces.
+ */
+export declare function waitForLocks(db: DatabaseSync): void;
+export declare function assertIndependentWrite(): void;
+export declare function writeToFile<T>(identity: string | symbol, work: () => Promise<T>): Promise<T>;
+/**
+ * Prepare with SQLite's authorizer listening: preparing names every table the
+ * statement reads — views expanded, CTEs and subqueries included — which is
+ * the engine's half of the reserved-relation guard (reservedSql.ts). A build
+ * without the authorizer keeps the lexical half alone.
+ */
+export declare function prepareGuarded(db: DatabaseSync, sql: string): StatementSync;
+/**
+ * The epoch a SQLite write transaction trusts, in one statement: the schema
+ * (SCHEMA_EPOCH) and the handle's foreign-key switch, which the scope catalog
+ * requires. `journal` also asks whether a journal's meta row says its
+ * version (a data fact: deleting the row changes no schema); the store that
+ * rides in the transaction names its row, so the engine knows no store's
+ * tables. A statement that cannot run — no journal table — is a miss, and the
+ * full attestation then says why.
+ */
+export declare function transactionEpoch(db: DatabaseSync, journal?: {
+    table: string;
+    version: number;
+}): {
+    epoch?: string;
+    journal: boolean;
+};
+/** The schema and whether a store's meta row says its version, in one statement; undefined when the store is not there. */
+export declare function storeEpoch(db: DatabaseSync, meta: {
+    table: string;
+    version: number;
+}): string | undefined;

package/dist/adapters/sqliteHandles.js

@@ -0,0 +1,143 @@
+/** SQLite handle guards, per-file write coordination, and schema epoch probes. */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { Refusal, Serial } from './adapter.js';
+import { isRuntimeTable } from '../shared/runtimeTables.js';
+import { reservedRefusal } from './reservedSql.js';
+/**
+ * Wait rather than fail when someone else holds the file.
+ *
+ * A SQLite database is usually a file another process is also using — the
+ * application whose data this is, a migration, a test — and one writer at a
+ * time is the whole locking model. Without a busy timeout the very next read
+ * during someone else's write comes back "database is locked", which reads
+ * as a broken tool rather than as a lock that would have cleared in
+ * milliseconds. Five seconds is long enough to outlast an ordinary write and
+ * short enough that a genuinely stuck writer still surfaces.
+ */
+export function waitForLocks(db) {
+    try {
+        db.exec('PRAGMA busy_timeout = 5000');
+    }
+    catch {
+        /* An old build without the pragma is not a reason to refuse the
+           database; it is a reason to be no worse than before. */
+    }
+}
+// Native busy_timeout cannot yield to another owner in this JS isolate. While
+// its transaction awaits verification, a second synchronous BEGIN would block
+// the first owner's continuation until timeout. Serialize by actual file, not
+// connection alias. SQLite still owns cross-process locking and atomicity.
+const fileWrites = new Map();
+const fileWriteContext = new AsyncLocalStorage();
+export function assertIndependentWrite() {
+    for (let context = fileWriteContext.getStore(); context; context = context.parent) {
+        if (context.active) {
+            // Independent A->B and B->A transactions can deadlock even when neither
+            // repeats its own ancestry. Cross-source nesting is not a transaction
+            // capability: callbacks must use their supplied writer, not an adapter.
+            throw new Refusal('Use the active transaction writer; nested SQLite adapter writes are unavailable.');
+        }
+    }
+}
+export function writeToFile(identity, work) {
+    let entry = fileWrites.get(identity);
+    if (!entry) {
+        entry = { queue: new Serial(), pending: 0 };
+        fileWrites.set(identity, entry);
+    }
+    const owned = entry;
+    owned.pending++;
+    return owned.queue
+        .run(async () => {
+        const context = { identity, active: true, parent: fileWriteContext.getStore() };
+        try {
+            return await fileWriteContext.run(context, work);
+        }
+        finally {
+            context.active = false;
+        }
+    })
+        .finally(() => {
+        if (--owned.pending === 0)
+            fileWrites.delete(identity);
+    });
+}
+/* SQLite's authorizer action codes, from its C API: @types/node does not
+   declare node:sqlite's `constants` or `setAuthorizer` yet. */
+const SQLITE_OK = 0;
+const SQLITE_READ = 20;
+/**
+ * Prepare with SQLite's authorizer listening: preparing names every table the
+ * statement reads — views expanded, CTEs and subqueries included — which is
+ * the engine's half of the reserved-relation guard (reservedSql.ts). A build
+ * without the authorizer keeps the lexical half alone.
+ */
+export function prepareGuarded(db, sql) {
+    const listen = db.setAuthorizer?.bind(db);
+    if (!listen)
+        return db.prepare(sql);
+    let reserved;
+    listen((action, table) => {
+        if (action === SQLITE_READ && typeof table === 'string' && isRuntimeTable(table))
+            reserved ??= table;
+        return SQLITE_OK;
+    });
+    let statement;
+    try {
+        statement = db.prepare(sql);
+    }
+    finally {
+        listen(null);
+    }
+    if (reserved !== undefined)
+        throw reservedRefusal(reserved);
+    return statement;
+}
+/*
+ * The schema a connection sees, as one statement's columns: the main file's
+ * `schema_version`, which SQLite bumps on every schema change from any
+ * connection, and the connection's own TEMP schema, word for word. The TEMP
+ * schema has no version a query can read — `temp.pragma_schema_version`
+ * answers main's — so its definitions are the version: a TEMP table, view,
+ * trigger or index that shadows or hooks a reserved store changes them. It
+ * is empty on nearly every connection, so reading it costs nothing.
+ */
+const SCHEMA_EPOCH = `(SELECT schema_version FROM main.pragma_schema_version) AS main,
+        (SELECT coalesce(group_concat(type || ':' || name || ':' || tbl_name || ':' || coalesce(sql, ''), char(10)), '') FROM temp.sqlite_schema) AS temp`;
+/**
+ * The epoch a SQLite write transaction trusts, in one statement: the schema
+ * (SCHEMA_EPOCH) and the handle's foreign-key switch, which the scope catalog
+ * requires. `journal` also asks whether a journal's meta row says its
+ * version (a data fact: deleting the row changes no schema); the store that
+ * rides in the transaction names its row, so the engine knows no store's
+ * tables. A statement that cannot run — no journal table — is a miss, and the
+ * full attestation then says why.
+ */
+export function transactionEpoch(db, journal) {
+    try {
+        const row = db
+            .prepare(`SELECT ${SCHEMA_EPOCH}, (SELECT foreign_keys FROM pragma_foreign_keys) AS fk${journal
+            ? `, (SELECT count(*) FROM main."${journal.table}" WHERE singleton = 1 AND version = ${Number(journal.version)}) AS journal`
+            : ''}`)
+            .get();
+        if (!row || typeof row.main !== 'number' || typeof row.temp !== 'string')
+            return { journal: false };
+        return { epoch: `${row.main}.${row.fk}\n${row.temp}`, journal: row.journal === 1 };
+    }
+    catch {
+        return { journal: false };
+    }
+}
+/** The schema and whether a store's meta row says its version, in one statement; undefined when the store is not there. */
+export function storeEpoch(db, meta) {
+    try {
+        const row = db
+            .prepare(`SELECT ${SCHEMA_EPOCH},
+        (SELECT count(*) FROM main."${meta.table}" WHERE singleton = 1 AND version = ?) AS meta`)
+            .get(meta.version);
+        return row && row.meta === 1 && typeof row.main === 'number' && typeof row.temp === 'string' ? `${row.main}\n${row.temp}` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/adapters/sqliteStatementProcess.d.ts

@@ -0,0 +1,29 @@
+interface ProcessStatement {
+    file: string;
+    /** The statement to prepare: the bounded wrap, when `bounded`. */
+    text: string;
+    /** What runs when the wrapped text does not prepare. */
+    fallback: string;
+    bounded: boolean;
+    limit: number;
+    /** Listen with SQLite's authorizer and answer `reserved` instead of rows. */
+    refuseReserved: boolean;
+    /** The statement's bound values, for one the adapter compiled (sqliteCostlyReads.ts). */
+    params?: unknown[];
+}
+interface ProcessAnswer {
+    columns: string[];
+    /** Each column's declared type, null for an expression (see sqliteDecimals.ts). */
+    types: Array<string | null>;
+    rows: unknown[][];
+    wrapped: boolean;
+    /** Set instead of rows when the statement reads one of tablewalk's own tables. */
+    reserved?: string;
+}
+/**
+ * Run one read in a child process, stopped when `capMs` runs out or when
+ * `signal` aborts. The engine's own errors come back as errors with the
+ * engine's words, as they would in-process.
+ */
+export declare function runInStatementProcess(job: ProcessStatement, capMs: number, signal: AbortSignal): Promise<ProcessAnswer>;
+export {};

package/dist/adapters/sqliteStatementProcess.js

@@ -0,0 +1,131 @@
+/**
+ * A raw SQLite read, run in a process of its own so that it can be stopped.
+ *
+ * node:sqlite runs a statement synchronously on the thread that asked and
+ * offers neither an interrupt nor a progress handler, so an aggregate over a
+ * cross join holds the whole server until it finishes — its cancel included,
+ * which cannot even be read while the thread is busy. A worker thread would
+ * not help: terminating one waits for the native call to return. A process
+ * can be killed. So a read whose caller may stop it is handed to a child
+ * with its own read-only handle on the same file, and killed at its cap or
+ * on cancel. The cost is a process start per statement, which a statement
+ * someone typed can afford; the cap counts from when the child is ready.
+ *
+ * The child's program is plain JavaScript run with `node -e`, so it needs no
+ * build step and no loader, under tsx or from dist alike. It answers raw rows
+ * (BigInts, bytes) over an advanced-serialization channel, and the adapter
+ * makes them JSON-safe the way it does its own.
+ */
+import { spawn } from 'node:child_process';
+import { RUNTIME_TABLE_PREFIXES } from '../shared/runtimeTables.js';
+import { onCancel, StatementStopped } from './statementControl.js';
+/* How long the child may take to start before the statement's own cap. */
+const STARTUP_MS = 10_000;
+/* The child. SQLITE_OK and SQLITE_READ are the C API's authorizer codes. The
+   rows stop one past the limit, so an unwrapped statement is not read whole
+   to learn that there was more. */
+const CHILD = `
+const { DatabaseSync } = process.getBuiltinModule('node:sqlite');
+const SQLITE_OK = 0, SQLITE_READ = 20;
+process.once('message', (job) => {
+  let answer;
+  try {
+    const db = new DatabaseSync(job.file, { readOnly: true });
+    try { db.exec('PRAGMA busy_timeout = 5000'); } catch {}
+    let reserved;
+    const prepare = (text) => {
+      if (!job.refuseReserved || typeof db.setAuthorizer !== 'function') return db.prepare(text);
+      db.setAuthorizer((action, table) => {
+        if (action === SQLITE_READ && typeof table === 'string' && job.prefixes.some((prefix) => table.toLowerCase().startsWith(prefix))) reserved ??= table;
+        return SQLITE_OK;
+      });
+      try { return db.prepare(text); } finally { db.setAuthorizer(null); }
+    };
+    let wrapped = job.bounded;
+    let statement;
+    try { statement = prepare(job.text); }
+    catch (error) {
+      if (!job.bounded) throw error;
+      wrapped = false;
+      statement = prepare(job.fallback);
+    }
+    if (reserved !== undefined) answer = { reserved };
+    else {
+      statement.setReturnArrays(true);
+      statement.setReadBigInts(true);
+      const described = statement.columns();
+      const columns = described.map((c) => c.name ?? c.column ?? '?');
+      const types = described.map((c) => c.type ?? null);
+      const rows = [];
+      for (const row of statement.iterate(...(job.params || []))) {
+        rows.push(row);
+        if (rows.length > job.limit) break;
+      }
+      answer = { columns, types, rows, wrapped };
+    }
+  } catch (error) {
+    answer = { error: String((error && error.message) || error) };
+  }
+  process.send(answer, () => process.exit(0));
+});
+process.send({ ready: true });
+`;
+/**
+ * Run one read in a child process, stopped when `capMs` runs out or when
+ * `signal` aborts. The engine's own errors come back as errors with the
+ * engine's words, as they would in-process.
+ */
+export function runInStatementProcess(job, capMs, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(new StatementStopped('cancelled'));
+            return;
+        }
+        const child = spawn(process.execPath, ['-e', CHILD], {
+            stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+            serialization: 'advanced',
+            /* Electron's binary is Node only when told so; plain Node ignores it. */
+            env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+            windowsHide: true,
+        });
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => {
+            stderr = (stderr + chunk.toString()).slice(-2_000);
+        });
+        let settled = false;
+        let timer;
+        let disarm = () => { };
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            disarm();
+            outcome();
+        };
+        const stop = (reason) => settle(() => {
+            child.kill('SIGKILL');
+            reject(new StatementStopped(reason, capMs));
+        });
+        timer = setTimeout(() => stop('timeout'), STARTUP_MS + capMs);
+        disarm = onCancel(signal, () => stop('cancelled'));
+        child.on('message', (message) => {
+            if (message.ready) {
+                /* The cap is the statement's, not the process start's. */
+                clearTimeout(timer);
+                timer = setTimeout(() => stop('timeout'), capMs);
+                child.send({ ...job, prefixes: RUNTIME_TABLE_PREFIXES });
+                return;
+            }
+            settle(() => {
+                if (message.error !== undefined)
+                    reject(new Error(message.error));
+                else
+                    resolve(message);
+            });
+        });
+        child.once('error', (error) => settle(() => reject(error)));
+        child.once('exit', (code, killedBy) => settle(() => reject(new Error(`The SQLite statement process ended without an answer (${killedBy ?? `exit ${code}`}).` +
+            (stderr.trim() ? ` ${stderr.trim()}` : '')))));
+    });
+}

package/dist/adapters/statementControl.d.ts

@@ -0,0 +1,34 @@
+/** The cap every read statement runs under unless a caller lowers it. */
+export declare const STATEMENT_TIMEOUT_MS = 30000;
+/**
+ * The cap for one statement: the caller's, when it gave one, held between
+ * the floor and the default. Politeness only lowers.
+ */
+export declare function statementCap(asked?: number): number;
+/** A read stopped before it finished: the caller cancelled it, or its cap ran out. */
+export declare class StatementStopped extends Error {
+    readonly reason: 'cancelled' | 'timeout';
+    readonly capMs?: number | undefined;
+    constructor(reason: 'cancelled' | 'timeout', capMs?: number | undefined, options?: ErrorOptions);
+}
+/** Run `work` so that every read it starts can be stopped by `signal`. */
+export declare function withCancellation<T>(signal: AbortSignal, work: () => Promise<T>): Promise<T>;
+/** Shared acquisition belongs to its host, not the first request that opens
+ * it. Explicitly detach inherited cancellation, including async descendants. */
+export declare function withoutCancellation<T>(work: () => T): T;
+/** The stop signal of the call this code runs for, when there is one. */
+export declare function cancellation(): AbortSignal | undefined;
+/** @throws StatementStopped when the call has been cancelled. */
+export declare function throwIfCancelled(signal?: AbortSignal | undefined): void;
+/**
+ * Run `stop` once if `signal` aborts before the returned disarm is called:
+ * an adapter's "cancel the statement I just started". An already aborted
+ * signal stops at once.
+ */
+export declare function onCancel(signal: AbortSignal | undefined, stop: () => void): () => void;
+/**
+ * Whether a failure is a stopped statement, and why: a StatementStopped, or
+ * an engine saying its own cap ran out, in the words each one uses —
+ * Postgres's statement_timeout.
+ */
+export declare function stoppedReason(error: unknown): 'cancelled' | 'timeout' | undefined;

package/dist/adapters/statementControl.js

@@ -0,0 +1,90 @@
+/**
+ * How long one read statement may run, and how the caller of a read stops it.
+ *
+ * The cap is one number for every engine: the Postgres pools
+ * open with it, `sql` may lower it for a single statement, and
+ * nothing raises it. The stop is a signal the caller owns — an MCP client's
+ * cancel — and it reaches the adapters ambiently, through
+ * AsyncLocalStorage, because a tool call gets to the driver through shared
+ * read services (readRecords, readCount, readView) whose signatures are
+ * about rows, not about who may abandon them. Each adapter decides what
+ * stopping means for its engine: Postgres cancels the backend, SQLite kills the process a raw statement runs in and checks
+ * between the statements it runs itself.
+ *
+ * Only reads are stopped. A write that has started runs to its end, so its
+ * outcome is known rather than guessed.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** The cap every read statement runs under unless a caller lowers it. */
+export const STATEMENT_TIMEOUT_MS = 30_000;
+/** Below this a cap loses races to the fast path, so a caller cannot ask for less. */
+const STATEMENT_TIMEOUT_FLOOR_MS = 100;
+/**
+ * The cap for one statement: the caller's, when it gave one, held between
+ * the floor and the default. Politeness only lowers.
+ */
+export function statementCap(asked) {
+    if (asked === undefined || !Number.isFinite(asked))
+        return STATEMENT_TIMEOUT_MS;
+    return Math.max(STATEMENT_TIMEOUT_FLOOR_MS, Math.min(STATEMENT_TIMEOUT_MS, Math.floor(asked)));
+}
+/** A read stopped before it finished: the caller cancelled it, or its cap ran out. */
+export class StatementStopped extends Error {
+    reason;
+    capMs;
+    constructor(reason, capMs, options) {
+        super(reason === 'cancelled'
+            ? 'The statement was cancelled and stopped.'
+            : `The statement ran past its ${capMs ?? STATEMENT_TIMEOUT_MS} ms cap and was stopped.`, options);
+        this.reason = reason;
+        this.capMs = capMs;
+        this.name = 'StatementStopped';
+    }
+}
+const calls = new AsyncLocalStorage();
+/** Run `work` so that every read it starts can be stopped by `signal`. */
+export function withCancellation(signal, work) {
+    return calls.run(signal, work);
+}
+/** Shared acquisition belongs to its host, not the first request that opens
+ * it. Explicitly detach inherited cancellation, including async descendants. */
+export function withoutCancellation(work) {
+    return calls.exit(work);
+}
+/** The stop signal of the call this code runs for, when there is one. */
+export function cancellation() {
+    return calls.getStore();
+}
+/** @throws StatementStopped when the call has been cancelled. */
+export function throwIfCancelled(signal = cancellation()) {
+    if (signal?.aborted)
+        throw new StatementStopped('cancelled');
+}
+/**
+ * Run `stop` once if `signal` aborts before the returned disarm is called:
+ * an adapter's "cancel the statement I just started". An already aborted
+ * signal stops at once.
+ */
+export function onCancel(signal, stop) {
+    if (!signal)
+        return () => { };
+    if (signal.aborted) {
+        stop();
+        return () => { };
+    }
+    signal.addEventListener('abort', stop, { once: true });
+    return () => signal.removeEventListener('abort', stop);
+}
+/**
+ * Whether a failure is a stopped statement, and why: a StatementStopped, or
+ * an engine saying its own cap ran out, in the words each one uses —
+ * Postgres's statement_timeout.
+ */
+export function stoppedReason(error) {
+    if (error instanceof StatementStopped)
+        return error.reason;
+    const message = error instanceof Error ? error.message : '';
+    return /canceling statement due to statement timeout|maximum statement execution time exceeded|max_statement_time exceeded/i.test(message)
+        ? 'timeout'
+        : undefined;
+}