@fadhilp/stateql 0.1.2 → 0.2.2

package/dist/src/stateql.js

@@ -1,12 +1,16 @@
 import { writeFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
-import { DatabaseSync } from "node:sqlite";
 import { env } from "node:process";
-import { BatchWriteError, createAdapter, } from "./adapters.js";
+import { AdapterExecutionError, AdapterWriteError, BatchWriteError, createAdapter, createAdapterContext, } from "./adapters.js";
+import { confidence, databaseIdentity, databaseUrlHasSecret, detectDriver, isEnvironmentName, normalizeSqliteSource, validateProfileName, version, } from "./connection.js";
 import { asStateQLError, StateQLError } from "./errors.js";
+import { filterMaterializedRows, prepareFilterStatement, validateFilterParameters, } from "./filter.js";
+import { operationData, paginationWarnings, profileData, rowsToCsv, sessionData, transactionData, } from "./response-data.js";
 import { analyzeSql } from "./sql.js";
 import { StateStore, } from "./store.js";
 import { compactRows, defaultHome, hash, parseJson, redact, } from "./util.js";
+const DEFAULT_SNAPSHOT_HISTORY_LIMIT = 50;
+const MAX_SNAPSHOT_HISTORY_LIMIT = 100;
 export class StateQL {
     store;
     sessionName;
@@ -15,6 +19,9 @@ export class StateQL {
     resultTtlSeconds;
     maxCellCharacters;
     maxResultRows;
+    maxResultBytes;
+    timeoutMs;
+    signal;
     now;
     constructor(options = {}) {
         this.now = options.now ?? (() => new Date());
@@ -24,6 +31,9 @@ export class StateQL {
         this.resultTtlSeconds = options.resultTtlSeconds ?? 86_400;
         this.maxCellCharacters = options.maxCellCharacters ?? 200;
         this.maxResultRows = positiveInteger(options.maxResultRows ?? 10_000, "maxResultRows");
+        this.maxResultBytes = positiveInteger(options.maxResultBytes ?? 16 * 1024 * 1024, "maxResultBytes");
+        this.timeoutMs = executionTimeout(options.timeoutMs ?? 30_000);
+        this.signal = options.signal;
         if (this.maxResultRows >= Number.MAX_SAFE_INTEGER) {
             throw new StateQLError("INVALID_COMMAND", "maxResultRows is too large.");
         }
@@ -59,10 +69,10 @@ export class StateQL {
                     : "Connection target is required.");
             }
             const driver = detectDriver(secret);
-            if (driver === "postgres" &&
+            if (driver !== "sqlite" &&
                 !secretEnv &&
-                postgresUrlHasSecret(secret)) {
-                throw new StateQLError("PERMISSION_DENIED", "Credential-bearing PostgreSQL URLs must use --env.", {
+                databaseUrlHasSecret(secret)) {
+                throw new StateQLError("PERMISSION_DENIED", `Credential-bearing ${databaseDisplayName(driver)} URLs must use --env.`, {
                     suggestedAction: "Set the URL in an environment variable and reconnect with --env NAME.",
                 });
             }
@@ -73,7 +83,7 @@ export class StateQL {
                     : secret;
             const databaseName = driver === "sqlite"
                 ? basename(source)
-                : new URL(secret).pathname.replace(/^\//, "") || "postgres";
+                : new URL(secret).pathname.replace(/^\//, "") || driver;
             const readOnly = options.readOnly ??
                 (profile ? Boolean(profile.read_only) : true);
             const draft = {
@@ -88,11 +98,14 @@ export class StateQL {
                 version: 0,
                 created_at: this.now().toISOString(),
             };
-            const adapter = await createAdapter(draft);
+            const adapter = await createAdapter(draft, this.executionContext(options));
             try {
                 await adapter.read("SELECT 1", []);
             }
             catch (error) {
+                if (error instanceof AdapterExecutionError) {
+                    throw stoppedStateQLError(error, false);
+                }
                 throw new StateQLError("CONNECTION_FAILED", errorMessage(error), { retryable: true });
             }
             finally {
@@ -140,8 +153,8 @@ export class StateQL {
             let storedTarget = target;
             if (target) {
                 const driver = detectDriver(target);
-                if (driver === "postgres" && postgresUrlHasSecret(target)) {
-                    throw new StateQLError("PERMISSION_DENIED", "Credential-bearing PostgreSQL URLs must use --env.");
+                if (driver !== "sqlite" && databaseUrlHasSecret(target)) {
+                    throw new StateQLError("PERMISSION_DENIED", `Credential-bearing ${databaseDisplayName(driver)} URLs must use --env.`);
                 }
                 if (driver === "sqlite")
                     storedTarget = normalizeSqliteSource(target);
@@ -197,6 +210,58 @@ export class StateQL {
             return { data: { disconnected: true }, executed: true };
         });
     }
+    snapshot(options = {}) {
+        const session = this.store
+            .listSessions()
+            .find((candidate) => candidate.name === this.sessionName);
+        if (!session) {
+            throw new StateQLError("INVALID_COMMAND", "The active session was not found.");
+        }
+        const connection = this.store.activeConnection(session);
+        const transaction = session.active_transaction_id
+            ? this.store.getTransaction(session.active_transaction_id)
+            : undefined;
+        const historyLimit = positiveInteger(options.historyLimit ?? DEFAULT_SNAPSHOT_HISTORY_LIMIT, "historyLimit");
+        if (historyLimit > MAX_SNAPSHOT_HISTORY_LIMIT) {
+            throw new StateQLError("INVALID_COMMAND", `historyLimit cannot exceed ${MAX_SNAPSHOT_HISTORY_LIMIT}.`);
+        }
+        return {
+            session: {
+                session_id: session.id,
+                name: session.name,
+                status: session.status,
+            },
+            connection: connection
+                ? {
+                    connection_id: connection.id,
+                    name: connection.name,
+                    status: "connected",
+                    driver: connection.driver,
+                    database: connection.database_name,
+                    read_only: Boolean(connection.read_only),
+                }
+                : null,
+            transaction: transaction
+                ? { transaction_id: transaction.id, state: transaction.state }
+                : null,
+            state_version: connection ? version(connection) : null,
+            state_confidence: connection ? confidence(connection) : null,
+            recent_results: this.store.knownResults(session.id, 10).map((result) => ({
+                alias: result.alias,
+                handle: result.id,
+                rows: result.row_count,
+            })),
+            recent_operations: this.store
+                .recentOperations(session.id, 10)
+                .map((operation) => ({
+                handle: operation.id,
+                type: operation.statement_type,
+                affected_rows: operation.affected_rows,
+                status: operation.status,
+            })),
+            history: this.store.history(session.id, historyLimit).map(historyEntry),
+        };
+    }
     async status() {
         return this.run("status", async (session) => {
             const connection = this.store.activeConnection(session);
@@ -231,10 +296,10 @@ export class StateQL {
             if (!name.trim()) {
                 throw new StateQLError("INVALID_COMMAND", "Session name is required.");
             }
-            if (this.store.getSession(name)) {
+            if (this.store.getSessionByName(name)) {
                 throw new StateQLError("INVALID_COMMAND", `Active session "${name}" already exists.`);
             }
-            const session = this.store.createSession(name);
+            const session = this.store.ensureSession(name);
             return {
                 data: sessionData(session),
                 handle: session.id,
@@ -310,12 +375,13 @@ export class StateQL {
     async query(sql, options = {}) {
         return this.run("query", async (session) => {
             const connection = this.requireConnection(session);
+            this.rejectDuringStagedTransaction(session, "Queries");
             const analysis = analyzeSql(sql, connection.driver);
             if (!analysis.read) {
                 throw new StateQLError("INVALID_SQL", "query accepts read statements only; use exec for writes.");
             }
             const parameters = options.params ?? [];
-            const adapter = await createAdapter(connection);
+            const adapter = await createAdapter(connection, this.executionContext(options));
             try {
                 const stateVersion = version(connection);
                 const stateSignature = await adapter.signature();
@@ -353,6 +419,12 @@ export class StateQL {
                 if (result.rows.length > this.maxResultRows) {
                     throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", `Query exceeds the ${this.maxResultRows}-row materialization limit.`, { suggestedAction: "Add a narrower WHERE clause or LIMIT." });
                 }
+                const resultBytes = Buffer.byteLength(JSON.stringify(parameters), "utf8") +
+                    Buffer.byteLength(JSON.stringify(result.rows), "utf8") +
+                    Buffer.byteLength(JSON.stringify(result.columns), "utf8");
+                if (resultBytes > this.maxResultBytes) {
+                    throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", `Query exceeds the ${this.maxResultBytes}-byte materialization limit.`, { suggestedAction: "Select fewer rows or smaller columns." });
+                }
                 const expiresAt = new Date(this.now().getTime() + this.resultTtlSeconds * 1000).toISOString();
                 const saved = this.store.saveResult({
                     sessionId: session.id,
@@ -379,6 +451,9 @@ export class StateQL {
             catch (error) {
                 if (error instanceof StateQLError)
                     throw error;
+                if (error instanceof AdapterExecutionError) {
+                    throw stoppedStateQLError(error, true);
+                }
                 throw new StateQLError("QUERY_FAILED", errorMessage(error), {
                     retryable: true,
                     executed: true,
@@ -529,7 +604,7 @@ export class StateQL {
     async exec(sql, options = {}) {
         return this.run("exec", async (session) => {
             const connection = this.requireConnection(session);
-            return this.performExec(session, connection, sql, options);
+            return this.performExec(session, connection, sql, options, this.executionContext(options));
         });
     }
     async receipt(id) {
@@ -587,7 +662,7 @@ export class StateQL {
             };
         });
     }
-    async commitTransaction(id) {
+    async commitTransaction(id, options = {}) {
         return this.run("transaction.commit", async (session) => {
             const transaction = this.requireActiveTransaction(session, id);
             const connection = this.store.getConnection(transaction.connection_id);
@@ -601,7 +676,7 @@ export class StateQL {
             if (operations.some((operation) => operation.connection_id !== connection.id)) {
                 throw new StateQLError("TRANSACTION_FAILED", "Transaction contains writes staged for another connection.", { suggestedAction: "Roll back the transaction." });
             }
-            const adapter = await createAdapter(connection);
+            const adapter = await createAdapter(connection, this.executionContext(options));
             try {
                 if (!this.store.markTransactionCommitting(transaction.id)) {
                     throw new StateQLError("TRANSACTION_FAILED", "Transaction is no longer active.");
@@ -611,8 +686,12 @@ export class StateQL {
                     results = await adapter.writeBatch(operations, transaction.isolation_level);
                 }
                 catch (error) {
-                    if (error instanceof BatchWriteError && !error.outcomeUnknown) {
+                    if ((error instanceof BatchWriteError && !error.outcomeUnknown) ||
+                        (error instanceof AdapterExecutionError && !error.outcomeUnknown)) {
                         this.store.finishTransaction(transaction.id, session.id, "failed");
+                        if (error instanceof AdapterExecutionError) {
+                            throw stoppedStateQLError(error, false);
+                        }
                         throw new StateQLError("TRANSACTION_FAILED", error.message, {
                             retryable: true,
                         });
@@ -690,10 +769,11 @@ export class StateQL {
             };
         });
     }
-    async inspect(kind, table) {
+    async inspect(kind, table, options = {}) {
         return this.run(`inspect.${kind}`, async (session) => {
             const connection = this.requireConnection(session);
-            const adapter = await createAdapter(connection);
+            this.rejectDuringStagedTransaction(session, "Schema inspection");
+            const adapter = await createAdapter(connection, this.executionContext(options));
             try {
                 const data = await adapter.inspect(kind, table);
                 return {
@@ -704,6 +784,9 @@ export class StateQL {
                 };
             }
             catch (error) {
+                if (error instanceof AdapterExecutionError) {
+                    throw stoppedStateQLError(error, true);
+                }
                 throw new StateQLError("QUERY_FAILED", errorMessage(error), {
                     retryable: false,
                     executed: true,
@@ -717,11 +800,12 @@ export class StateQL {
     async plan(sql, options = {}) {
         return this.run("plan", async (session) => {
             const connection = this.requireConnection(session);
+            this.rejectDuringStagedTransaction(session, "Plans");
             const analysis = analyzeSql(sql, connection.driver);
             if (analysis.read) {
                 throw new StateQLError("INVALID_SQL", "plan accepts write statements only.");
             }
-            const adapter = await createAdapter(connection);
+            const adapter = await createAdapter(connection, this.executionContext(options));
             try {
                 const stateSignature = await adapter.signature();
                 const expiresAt = new Date(this.now().getTime() + 10 * 60_000).toISOString();
@@ -762,13 +846,20 @@ export class StateQL {
                     confidence: adapter.confidence,
                 };
             }
+            catch (error) {
+                if (error instanceof AdapterExecutionError) {
+                    throw stoppedStateQLError(error, true);
+                }
+                throw error;
+            }
             finally {
                 await adapter.close();
             }
         });
     }
-    async apply(planId) {
+    async apply(planId, options = {}) {
         return this.run("apply", async (session) => {
+            this.rejectDuringStagedTransaction(session, "Plans");
             const plan = this.store.getPlan(planId);
             if (!plan || plan.session_id !== session.id) {
                 throw new StateQLError("STALE_PLAN", `Plan "${planId}" was not found.`);
@@ -786,12 +877,19 @@ export class StateQL {
                 version(connection) !== plan.state_version) {
                 throw new StateQLError("STALE_PLAN", "Database state changed after this plan was created.");
             }
-            const adapter = await createAdapter(connection);
+            const context = this.executionContext(options);
+            const adapter = await createAdapter(connection, context);
             try {
                 if ((await adapter.signature()) !== plan.state_signature) {
                     throw new StateQLError("STALE_PLAN", "Database state changed after this plan was created.");
                 }
             }
+            catch (error) {
+                if (error instanceof AdapterExecutionError) {
+                    throw stoppedStateQLError(error, true);
+                }
+                throw error;
+            }
             finally {
                 await adapter.close();
             }
@@ -799,7 +897,7 @@ export class StateQL {
                 params: parseJson(plan.parameters, []),
                 allowUnbounded: Boolean(plan.allow_unbounded),
                 allowDestructive: Boolean(plan.allow_destructive),
-            });
+            }, context);
             const operationId = String(result.data.operation_id);
             this.store.markPlanApplied(plan.id, operationId);
             return {
@@ -813,24 +911,14 @@ export class StateQL {
             data: {
                 history: this.store
                     .history(session.id, positiveInteger(limit, "limit"))
-                    .map((item) => ({
-                    command_id: item.id,
-                    timestamp: item.timestamp,
-                    session_id: item.session_id,
-                    command: item.command,
-                    handle: item.handle,
-                    executed: Boolean(item.executed),
-                    cached: Boolean(item.cached),
-                    success: Boolean(item.success),
-                    error_code: item.error_code,
-                })),
+                    .map(historyEntry),
             },
         }));
     }
     async capabilities() {
         return this.run("capabilities", async () => ({
             data: {
-                drivers: ["postgres", "sqlite"],
+                drivers: ["mysql", "postgres", "sqlite"],
                 features: {
                     result_handles: true,
                     write_deduplication: true,
@@ -839,6 +927,8 @@ export class StateQL {
                     persistent_sessions: true,
                     result_filtering: true,
                     schema_inspection: true,
+                    deadlines: true,
+                    cancellation: true,
                 },
             },
         }));
@@ -855,6 +945,7 @@ export class StateQL {
                         readOnly: command.read_only,
                         secretEnv: command.secret_env,
                         profile: command.profile,
+                        timeoutMs: command.timeout_ms,
                     });
                 case "disconnect":
                     return this.disconnect();
@@ -885,6 +976,7 @@ export class StateQL {
                     const response = await this.query(batchString(command.sql, "sql"), {
                         params: command.params ?? [],
                         cache: command.cache ?? "auto",
+                        timeoutMs: command.timeout_ms,
                     });
                     if (!response.ok || !command.as)
                         return response;
@@ -917,6 +1009,7 @@ export class StateQL {
                         idempotencyKey: command.idempotency_key,
                         allowUnbounded: command.allow_unbounded ?? false,
                         allowDestructive: command.allow_destructive ?? false,
+                        timeoutMs: command.timeout_ms,
                     });
                 case "show":
                     return this.show(batchString(command.handle, "handle"));
@@ -932,13 +1025,17 @@ export class StateQL {
                 case "alias.set":
                     return this.setAlias(batchString(command.name, "name"), batchString(command.handle, "handle"));
                 case "inspect":
-                    return this.inspect(batchString(command.kind, "kind"), command.table);
+                    return this.inspect(batchString(command.kind, "kind"), command.table, {
+                        timeoutMs: command.timeout_ms,
+                    });
                 case "transaction.begin":
                     return this.beginTransaction(command.isolation);
                 case "transaction.status":
                     return this.transactionStatus(command.handle);
                 case "transaction.commit":
-                    return this.commitTransaction(command.handle);
+                    return this.commitTransaction(command.handle, {
+                        timeoutMs: command.timeout_ms,
+                    });
                 case "transaction.rollback":
                     return this.rollbackTransaction(command.handle);
                 case "plan":
@@ -946,9 +1043,12 @@ export class StateQL {
                         params: command.params ?? [],
                         allowUnbounded: command.allow_unbounded ?? false,
                         allowDestructive: command.allow_destructive,
+                        timeoutMs: command.timeout_ms,
                     });
                 case "apply":
-                    return this.apply(batchString(command.handle, "handle"));
+                    return this.apply(batchString(command.handle, "handle"), {
+                        timeoutMs: command.timeout_ms,
+                    });
                 case "history":
                     return this.history(command.limit ?? 20);
                 case "receipt":
@@ -982,7 +1082,7 @@ export class StateQL {
                 return;
         }
     }
-    async performExec(session, connection, sql, options) {
+    async performExec(session, connection, sql, options, context) {
         if (connection.read_only) {
             throw new StateQLError("READ_ONLY_CONNECTION", "Connection is read-only.", { suggestedAction: "Reconnect with --read-write." });
         }
@@ -996,6 +1096,10 @@ export class StateQL {
         if (analysis.destructive && !options.allowDestructive) {
             throw new StateQLError("DESTRUCTIVE_OPERATION_BLOCKED", "Destructive operation requires an explicit override.", { extra: { override_flag: "--allow-destructive" } });
         }
+        if (options.idempotencyKey !== undefined &&
+            !options.idempotencyKey.trim()) {
+            throw new StateQLError("INVALID_COMMAND", "Idempotency key cannot be empty.");
+        }
         const parameters = options.params ?? [];
         const fingerprint = hash({
             sql: analysis.normalized,
@@ -1026,6 +1130,12 @@ export class StateQL {
             stateVersionBefore: version(connection),
         });
         const previous = reservation.previous;
+        if (previous &&
+            options.idempotencyKey &&
+            !options.replay &&
+            previous.fingerprint !== fingerprint) {
+            throw new StateQLError("IDEMPOTENCY_CONFLICT", "Idempotency key was already used for a different write.", { extra: { previous_operation_id: previous.id } });
+        }
         if (previous && !reservation.operation) {
             if (previous.status === "executing" ||
                 previous.status === "outcome_unknown") {
@@ -1066,7 +1176,7 @@ export class StateQL {
         }
         let adapter;
         try {
-            adapter = await createAdapter(connection);
+            adapter = await createAdapter(connection, context);
         }
         catch (error) {
             this.store.failOperation(operation.id);
@@ -1102,6 +1212,16 @@ export class StateQL {
         catch (error) {
             if (error instanceof StateQLError)
                 throw error;
+            if (error instanceof AdapterExecutionError && !error.outcomeUnknown) {
+                this.store.failOperation(operation.id);
+                throw stoppedStateQLError(error, false);
+            }
+            if (error instanceof AdapterWriteError && !error.outcomeUnknown) {
+                this.store.failOperation(operation.id);
+                throw new StateQLError("QUERY_FAILED", error.message, {
+                    executed: true,
+                });
+            }
             this.store.markOperationOutcomeUnknown(operation.id);
             throw new StateQLError("OUTCOME_UNKNOWN", errorMessage(error), {
                 executed: true,
@@ -1134,6 +1254,11 @@ export class StateQL {
             return action(result, session);
         });
     }
+    rejectDuringStagedTransaction(session, operation) {
+        if (!session.active_transaction_id)
+            return;
+        throw new StateQLError("TRANSACTION_FAILED", `${operation} cannot run while a staged transaction is active.`, { suggestedAction: "Commit or roll back the transaction first." });
+    }
     requireResult(idOrAlias, session) {
         const result = this.store.getResult(idOrAlias, session.id);
         if (!result) {
@@ -1162,6 +1287,9 @@ export class StateQL {
         }
         return transaction;
     }
+    executionContext(options) {
+        return createAdapterContext(executionTimeout(options.timeoutMs ?? this.timeoutMs), options.signal ?? this.signal);
+    }
     resultData(result, cached) {
         const rows = this.store.resultRows(result);
         const preview = compactRows(rows.slice(0, this.previewRows), this.maxCellCharacters);
@@ -1244,255 +1372,18 @@ export class StateQL {
         }
     }
 }
-function prepareFilterStatement(columns, predicate) {
-    const text = predicate.trim();
-    if (!text) {
-        throw new StateQLError("INVALID_SQL", "Filter predicate is required.");
-    }
-    const columnNames = columns.map((column) => column.name);
-    if (columnNames.length === 0) {
-        throw new StateQLError("INVALID_SQL", "Filter requires at least one result column.");
-    }
-    const names = new Set();
-    for (const name of columnNames) {
-        const normalized = name.toLowerCase();
-        if (!name || name.includes("\0") || names.has(normalized)) {
-            throw new StateQLError("INVALID_SQL", "Filter requires unique, non-empty result column names.");
-        }
-        names.add(normalized);
-    }
-    const tableName = "__stateql_filter_source";
-    let indexColumn = "__stateql_row_index";
-    while (names.has(indexColumn.toLowerCase()))
-        indexColumn += "_";
-    const sql = `SELECT ${quoteIdentifier(indexColumn)} ` +
-        `FROM ${quoteIdentifier(tableName)} WHERE (${text})`;
-    const analysis = analyzeSql(sql, "sqlite");
-    const details = analysis.ast;
-    const from = details.from;
-    const source = Array.isArray(from)
-        ? from[0]
-        : undefined;
-    if (!analysis.read ||
-        !Array.isArray(from) ||
-        from.length !== 1 ||
-        source?.table !== tableName ||
-        details.with ||
-        details.groupby ||
-        details.having ||
-        details.orderby ||
-        details.limit ||
-        details.for_update ||
-        details._next ||
-        details.set_op ||
-        containsSelect(details.where)) {
-        throw new StateQLError("INVALID_SQL", "Filter accepts one scalar predicate only.");
-    }
-    validateFilterExpression(details.where, names, tableName);
-    const bindings = filterBindings(details.where);
+function historyEntry(item) {
     return {
-        sql,
-        normalized: analysis.normalized,
-        tableName,
-        indexColumn,
-        columnNames,
-        positionalParameters: bindings.positional,
-        namedParameters: [...bindings.named],
-    };
-}
-function filterMaterializedRows(rows, filter, parameters) {
-    const db = new DatabaseSync(":memory:");
-    try {
-        const definitions = [
-            `${quoteIdentifier(filter.indexColumn)} INTEGER PRIMARY KEY`,
-            ...filter.columnNames.map(quoteIdentifier),
-        ];
-        db.exec(`CREATE TABLE ${quoteIdentifier(filter.tableName)} ` +
-            `(${definitions.join(", ")})`);
-        const placeholders = filter.columnNames.map(() => "?").join(", ");
-        const insert = db.prepare(`INSERT INTO ${quoteIdentifier(filter.tableName)} (` +
-            `${quoteIdentifier(filter.indexColumn)}, ` +
-            `${filter.columnNames.map(quoteIdentifier).join(", ")}) ` +
-            `VALUES (?, ${placeholders})`);
-        db.exec("BEGIN");
-        try {
-            rows.forEach((row, index) => {
-                const values = filter.columnNames.map((name) => sqliteFilterValue(row[name]));
-                insert.run(index, ...values);
-            });
-            db.exec("COMMIT");
-        }
-        catch (error) {
-            db.exec("ROLLBACK");
-            throw error;
-        }
-        const statement = db.prepare(`${filter.sql}\nORDER BY ${quoteIdentifier(filter.indexColumn)}`);
-        const selected = filterAll(statement, parameters);
-        return selected.map((row) => {
-            const index = Number(row[filter.indexColumn]);
-            if (!Number.isInteger(index) || !rows[index]) {
-                throw new StateQLError("INVALID_SQL", "Filter produced an invalid source row index.");
-            }
-            return rows[index];
-        });
-    }
-    catch (error) {
-        if (error instanceof StateQLError)
-            throw error;
-        throw new StateQLError("INVALID_SQL", errorMessage(error));
-    }
-    finally {
-        db.close();
-    }
-}
-function filterAll(statement, parameters) {
-    if (Array.isArray(parameters)) {
-        return statement.all(...parameters);
-    }
-    return statement.all(parameters);
-}
-function sqliteFilterValue(value) {
-    if (value === null || value === undefined)
-        return null;
-    if (typeof value === "string" ||
-        typeof value === "number" ||
-        typeof value === "bigint") {
-        return value;
-    }
-    if (typeof value === "boolean")
-        return value ? 1 : 0;
-    if (value instanceof Uint8Array)
-        return value;
-    try {
-        return JSON.stringify(value) ?? null;
-    }
-    catch {
-        return String(value);
-    }
-}
-function quoteIdentifier(value) {
-    return `"${value.replaceAll('"', '""')}"`;
-}
-function containsSelect(value) {
-    if (!value || typeof value !== "object")
-        return false;
-    const record = value;
-    if (record.type === "select")
-        return true;
-    return Object.values(record).some(containsSelect);
-}
-const FILTER_FUNCTIONS = new Set([
-    "abs",
-    "coalesce",
-    "ifnull",
-    "instr",
-    "json_extract",
-    "json_type",
-    "json_valid",
-    "length",
-    "lower",
-    "ltrim",
-    "nullif",
-    "round",
-    "rtrim",
-    "substr",
-    "substring",
-    "trim",
-    "typeof",
-    "upper",
-]);
-function validateFilterExpression(value, columns, tableName) {
-    if (!value || typeof value !== "object")
-        return;
-    const record = value;
-    if (record.type === "column_ref") {
-        const column = record.column;
-        const table = record.table;
-        if (typeof column !== "string" ||
-            !columns.has(column.toLowerCase()) ||
-            (table !== null && table !== undefined && table !== tableName)) {
-            throw new StateQLError("INVALID_SQL", `Unknown filter column "${String(column)}".`);
-        }
-    }
-    else if (record.type === "double_quote_string") {
-        const column = String(record.value);
-        if (!columns.has(column.toLowerCase())) {
-            throw new StateQLError("INVALID_SQL", `Unknown filter column "${column}".`);
-        }
-    }
-    else if (record.type === "function") {
-        const name = filterFunctionName(record);
-        if (!name || !FILTER_FUNCTIONS.has(name)) {
-            throw new StateQLError("INVALID_SQL", `Filter function "${name ?? "unknown"}" is not allowed.`);
-        }
-    }
-    Object.values(record).forEach((item) => validateFilterExpression(item, columns, tableName));
-}
-function filterFunctionName(record) {
-    const name = record.name;
-    const parts = name?.name;
-    if (!Array.isArray(parts))
-        return undefined;
-    const last = parts.at(-1);
-    return typeof last?.value === "string" ? last.value.toLowerCase() : undefined;
-}
-function filterBindings(value) {
-    const named = new Set();
-    const prefixes = new Map();
-    let positional = 0;
-    const visit = (item) => {
-        if (!item || typeof item !== "object")
-            return;
-        const record = item;
-        if (record.type === "origin" && record.value === "?")
-            positional += 1;
-        if (record.type === "param" && typeof record.value === "string") {
-            addNamed(String(record.value), `:${String(record.value)}`);
-        }
-        if (record.type === "var" &&
-            typeof record.name === "string" &&
-            (record.prefix === "$" || record.prefix === "@")) {
-            addNamed(record.name, `${String(record.prefix)}${record.name}`);
-        }
-        Object.values(record).forEach(visit);
-    };
-    const addNamed = (name, token) => {
-        const previous = prefixes.get(name);
-        if (previous && previous !== token) {
-            throw new StateQLError("INVALID_SQL", `Filter parameter "${name}" uses conflicting prefixes.`);
-        }
-        prefixes.set(name, token);
-        named.add(name);
+        command_id: item.id,
+        timestamp: item.timestamp,
+        session_id: item.session_id,
+        command: item.command,
+        handle: item.handle,
+        executed: Boolean(item.executed),
+        cached: Boolean(item.cached),
+        success: Boolean(item.success),
+        error_code: item.error_code,
     };
-    visit(value);
-    if (positional && named.size) {
-        throw new StateQLError("INVALID_SQL", "Filter cannot mix positional and named parameters.");
-    }
-    return { positional, named };
-}
-function validateFilterParameters(filter, parameters) {
-    if (filter.positionalParameters) {
-        if (!Array.isArray(parameters) ||
-            parameters.length !== filter.positionalParameters) {
-            throw new StateQLError("INVALID_SQL", `Filter requires exactly ${filter.positionalParameters} positional parameters.`);
-        }
-        return;
-    }
-    if (filter.namedParameters.length) {
-        if (Array.isArray(parameters)) {
-            throw new StateQLError("INVALID_SQL", "Filter requires named parameters.");
-        }
-        const supplied = Object.keys(parameters).sort();
-        const expected = [...filter.namedParameters].sort();
-        if (JSON.stringify(supplied) !== JSON.stringify(expected)) {
-            throw new StateQLError("INVALID_SQL", `Filter requires named parameters: ${expected.join(", ")}.`);
-        }
-        return;
-    }
-    if ((Array.isArray(parameters) && parameters.length) ||
-        (!Array.isArray(parameters) && Object.keys(parameters).length)) {
-        throw new StateQLError("INVALID_SQL", "Filter predicate has no parameters.");
-    }
 }
 function markTransactionOutcomeUnknown(store, transactionId, sessionId) {
     try {
@@ -1506,6 +1397,9 @@ function boundedReadSql(sql, limit) {
     const statement = sql.trim().replace(/;\s*$/, "");
     return `SELECT * FROM (${statement}) AS _stateql_bounded LIMIT ${limit}`;
 }
+function databaseDisplayName(driver) {
+    return driver === "postgres" ? "PostgreSQL" : "MySQL";
+}
 function normalizeIsolation(isolation, driver) {
     const normalized = isolation.trim().toLowerCase().replace(/[_-]+/g, " ")
         .replace(/\s+/g, " ");
@@ -1523,104 +1417,6 @@ function normalizeIsolation(isolation, driver) {
     }
     return normalized;
 }
-function databaseIdentity(connection) {
-    return {
-        driver: connection.driver,
-        database: connection.database_name,
-        source: connection.source,
-        secretEnvironment: connection.secret_env,
-    };
-}
-function detectDriver(target) {
-    if (/^postgres(?:ql)?:\/\//i.test(target))
-        return "postgres";
-    if (/^[a-z][a-z\d+.-]*:\/\//i.test(target)) {
-        throw new StateQLError("UNSUPPORTED_DRIVER", "Only PostgreSQL and SQLite are supported.");
-    }
-    return "sqlite";
-}
-function normalizeSqliteSource(target) {
-    const source = target.startsWith("sqlite:") ? target.slice(7) : target;
-    if (source === ":memory:")
-        return source;
-    return resolve(source);
-}
-function postgresUrlHasSecret(target) {
-    try {
-        const url = new URL(target);
-        return (Boolean(url.password) ||
-            [...url.searchParams.keys()].some((key) => /pass|token|secret|private[_-]?key|api[_-]?key/i.test(key)));
-    }
-    catch {
-        throw new StateQLError("INVALID_COMMAND", "Invalid PostgreSQL URL.");
-    }
-}
-function version(connection) {
-    return `sv_${connection.version}`;
-}
-function confidence(connection) {
-    return connection.driver === "sqlite" ? "database_reported" : "ttl_based";
-}
-function sessionData(session) {
-    return {
-        session_id: session.id,
-        name: session.name,
-        state: session.status,
-        active_connection: session.active_connection_id,
-        active_transaction: session.active_transaction_id,
-    };
-}
-function profileData(profile) {
-    return {
-        profile: profile.name,
-        target: profile.target,
-        secret_env: profile.secret_env,
-        read_only: Boolean(profile.read_only),
-    };
-}
-function validateProfileName(name) {
-    if (/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(name))
-        return;
-    throw new StateQLError("INVALID_COMMAND", "Profile name must be 1-64 letters, numbers, dots, underscores, or hyphens.");
-}
-function isEnvironmentName(name) {
-    return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name);
-}
-function operationData(operation) {
-    return {
-        operation_id: operation.id,
-        statement_type: operation.statement_type,
-        affected_rows: operation.affected_rows,
-        status: operation.status,
-        committed: operation.status === "committed",
-        transaction_id: operation.transaction_id,
-        state_version_before: operation.state_version_before,
-        state_version_after: operation.state_version_after,
-        ...(operation.replay_of ? { replay_of: operation.replay_of } : {}),
-    };
-}
-function transactionData(transaction, statements) {
-    return {
-        transaction_id: transaction.id,
-        state: transaction.state,
-        connection_id: transaction.connection_id,
-        statements,
-        pending_writes: transaction.state === "active" ? statements : 0,
-        start_state_version: transaction.start_version,
-        isolation_level: transaction.isolation_level,
-        age_ms: Date.now() - Date.parse(transaction.created_at),
-    };
-}
-function paginationWarnings(ordered) {
-    if (ordered)
-        return [];
-    return [
-        {
-            code: "NON_DETERMINISTIC_PAGINATION",
-            message: "Result has no explicit ORDER BY clause.",
-        },
-    ];
-}
 function batchString(value, name) {
     if (value?.trim())
         return value;
@@ -1636,19 +1432,15 @@ function positiveInteger(value, name) {
         return value;
     throw new StateQLError("INVALID_COMMAND", `${name} must be a positive integer.`);
 }
-function rowsToCsv(rows, columns) {
-    const encode = (value) => {
-        const text = value === null || value === undefined
-            ? ""
-            : typeof value === "object"
-                ? JSON.stringify(value)
-                : String(value);
-        return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
-    };
-    return [
-        columns.map(encode).join(","),
-        ...rows.map((row) => columns.map((column) => encode(row[column])).join(",")),
-    ].join("\n") + "\n";
+function executionTimeout(value) {
+    const timeout = positiveInteger(value, "timeoutMs");
+    if (timeout > 2_147_483_647) {
+        throw new StateQLError("INVALID_COMMAND", "timeoutMs cannot exceed 2147483647 milliseconds.");
+    }
+    return timeout;
+}
+function stoppedStateQLError(error, executed) {
+    return new StateQLError(error.reason === "timeout" ? "DEADLINE_EXCEEDED" : "OPERATION_CANCELLED", error.message, { retryable: true, executed });
 }
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);