@fadhilp/stateql 0.4.4 → 0.5.2

package/README.md

@@ -12,7 +12,7 @@ StateQL is built around durable handles:
    rerunning the original SQL.
 3. Use operation, plan, and transaction handles to inspect and control writes.
 
-Requires Node.js 22.5 or newer.
+Requires Node.js 22.16 or newer for the required `node:sqlite` APIs.
 
 ## Quick start
 
@@ -160,6 +160,8 @@ stql plan <sql> [--allow-unbounded] [--allow-destructive]
 stql apply <plan-handle>
 stql history [--limit N]
 stql receipt <operation-handle>
+stql doctor
+stql purge [expired|results|history|all]
 stql capabilities
 stql batch [commands.json|commands.jsonl|-] [--continue-on-error]
 stql pipe [--continue-on-error]
@@ -244,6 +246,20 @@ Command history keeps the latest 10,000 entries per session. SQLite cache reuse
 also checks the database file signature. PostgreSQL and MySQL cache reuse is
 labeled `ttl_based` and is never authoritative.
 
+StateQL limits persisted result payloads to 256 MiB by default. When that quota
+is reached it removes the oldest unaliased results; aliases remain protected. A
+single result that cannot fit fails with `STATE_QUOTA_EXCEEDED`. Configure the
+limit with `maxStateBytes` in the library or `--max-state-bytes` in the CLI.
+Cache and result retention can be configured with `cacheTtlSeconds` and
+`resultTtlSeconds`, or their `--cache-ttl-seconds` and
+`--result-ttl-seconds` CLI equivalents.
+
+`stql doctor` checks SQLite integrity and stored payload shapes without printing
+SQL, parameters, or result values. `stql purge` removes expired data by default;
+use `results`, `history`, or `all` for explicit session cleanup. On POSIX
+systems, StateQL removes group and world access from its state directory,
+database, and SQLite sidecar files.
+
 ### Local filtering
 
 `filter` evaluates one scalar SQLite predicate against a stored result. It
@@ -347,6 +363,7 @@ const stateql = StateQL.forActor({
   actor: "pi-session-id",
   timeoutMs: 30_000,
   maxResultBytes: 16 * 1024 * 1024,
+  maxStateBytes: 256 * 1024 * 1024,
 });
 
 const controller = new AbortController();
@@ -437,4 +454,4 @@ and keeping values out of their own logs and model-visible data.
 For writes, credential resolution happens after StateQL atomically reserves the
 operation for duplicate protection. A resolution failure keeps a non-executed
 `failed` audit record, does not consume the idempotency key, and permits a safe
-retry.
+retry.

package/dist/src/adapters.js

@@ -1,7 +1,7 @@
 import { fork } from "node:child_process";
 import { createConnection as createMySqlConnection, } from "mysql2";
 import { Client, types as pgTypes } from "pg";
-import { parseJson, toJsonSafe } from "./util.js";
+import { isSqlParameters, parseJson, toJsonSafe } from "./util.js";
 export class AdapterExecutionError extends Error {
     reason;
     outcomeUnknown;
@@ -53,6 +53,7 @@ class SQLiteAdapter {
     pending = new Map();
     nextId = 1;
     closed = false;
+    closePromise;
     constructor(source, readOnly, context) {
         this.source = source;
         this.readOnly = readOnly;
@@ -100,12 +101,12 @@ class SQLiteAdapter {
         return this.call("inspect", [kind, table], false, false);
     }
     async close() {
-        if (this.closed)
-            return;
+        if (this.closePromise)
+            return this.closePromise;
         this.closed = true;
         if (this.child.exitCode !== null || this.child.signalCode !== null)
             return;
-        await new Promise((resolve) => {
+        this.closePromise = new Promise((resolve) => {
             const done = () => {
                 clearTimeout(timer);
                 resolve();
@@ -117,7 +118,6 @@ class SQLiteAdapter {
                 catch {
                     // Process already exited.
                 }
-                resolve();
             }, 1_000);
             timer.unref();
             this.child.once("exit", done);
@@ -133,6 +133,7 @@ class SQLiteAdapter {
                 }
             }
         });
+        return this.closePromise;
     }
     async call(operation, args, outcomeUnknown, batch) {
         throwIfStopped(this.context, false);
@@ -148,7 +149,9 @@ class SQLiteAdapter {
                     readOnly: this.readOnly,
                     operation,
                     args,
-                    busyTimeoutMs: Math.min(5_000, remainingMilliseconds(this.context)),
+                    // Let the client deadline terminate the worker before SQLite's
+                    // lock timeout races it and reports a known, non-executed failure.
+                    busyTimeoutMs: Math.min(5_000, remainingMilliseconds(this.context) + 250),
                 }, (error) => {
                     if (error)
                         reject(error);
@@ -288,7 +291,7 @@ class PostgresAdapter {
         try {
             for (const operation of operations) {
                 await this.setLocalDeadline();
-                const result = await this.query(operation.sql, postgresParams(parseJson(operation.parameters, [])), true);
+                const result = await this.query(operation.sql, postgresParams(parseJson(operation.parameters, `operation "${operation.id}" parameters`, isSqlParameters)), true);
                 results.push({ affectedRows: result.rowCount ?? 0 });
             }
         }
@@ -506,7 +509,7 @@ class MySqlAdapter {
         const results = [];
         try {
             for (const operation of operations) {
-                const [result] = await this.query(operation.sql, mysqlParams(parseJson(operation.parameters, [])), true, true);
+                const [result] = await this.query(operation.sql, mysqlParams(parseJson(operation.parameters, `operation "${operation.id}" parameters`, isSqlParameters)), true, true);
                 results.push({ affectedRows: mysqlAffectedRows(result) });
             }
         }

package/dist/src/cli.js

@@ -25,6 +25,9 @@ const parsed = parseArgs({
         offset: { type: "string" },
         limit: { type: "string" },
         "timeout-ms": { type: "string" },
+        "max-state-bytes": { type: "string" },
+        "cache-ttl-seconds": { type: "string" },
+        "result-ttl-seconds": { type: "string" },
         format: { type: "string" },
         output: { type: "string" },
         isolation: { type: "string" },
@@ -50,6 +53,15 @@ const stateql = new StateQL({
         ? {}
         : { timeoutMs: Number(values["timeout-ms"]) }),
     ...(process.env.STQL_ACTOR ? { actor: process.env.STQL_ACTOR } : {}),
+    ...(values["max-state-bytes"] === undefined
+        ? {}
+        : { maxStateBytes: Number(values["max-state-bytes"]) }),
+    ...(values["cache-ttl-seconds"] === undefined
+        ? {}
+        : { cacheTtlSeconds: Number(values["cache-ttl-seconds"]) }),
+    ...(values["result-ttl-seconds"] === undefined
+        ? {}
+        : { resultTtlSeconds: Number(values["result-ttl-seconds"]) }),
     signal: abortController.signal,
 });
 try {
@@ -195,6 +207,10 @@ async function dispatch() {
             return stateql.history(numberOption(values.limit, 20));
         case "receipt":
             return stateql.receipt(requireValue(subcommand, "operation handle"));
+        case "doctor":
+            return stateql.doctor();
+        case "purge":
+            return stateql.purge(purgeScope(subcommand));
         case "capabilities":
             return stateql.capabilities();
         default:
@@ -325,6 +341,13 @@ function parseBatchJson(value, location) {
 function numberOption(value, fallback) {
     return value === undefined ? fallback : Number(value);
 }
+function purgeScope(value) {
+    if (!value || value === "expired")
+        return "expired";
+    if (value === "results" || value === "history" || value === "all")
+        return value;
+    throw new Error("purge scope must be expired, results, history, or all.");
+}
 function cacheMode(value) {
     if (!value || value === "auto")
         return "auto";
@@ -515,12 +538,13 @@ Commands:
   alias set
   inspect schema|table|columns|indexes|constraints
   transaction begin|status|commit|rollback
-  plan, apply, history, receipt, capabilities
+  plan, apply, history, receipt, doctor, purge, capabilities
   batch [file.json|file.jsonl|-]
   pipe
 
 SQL parameters: --params JSON, repeated --param VALUE, or --params-file FILE.
 Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
+State: --max-state-bytes N, --cache-ttl-seconds N, --result-ttl-seconds N.
 Output: --output agent|json|jsonl|text|silent (default: agent).
 Batch/pipe accept JSON array files or JSONL streams. Stop on first error.`;
 }

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
 export { StateQL } from "./stateql.js";
 export { CredentialResolutionError, StateQLError, exitCodeFor, } from "./errors.js";
 export type { CredentialResolutionFailure } from "./errors.js";
-export type { BatchCommand, BatchCommandName, BatchOptions, ConnectOptions, CredentialAccess, CredentialOperation, CredentialRequest, CredentialResolver, ExecOptions, ExecutionOptions, Failure, FilterOptions, HistoryEntry, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, SqlParameters, StateQLActorOptions, StateQLOptions, StateQLSnapshot, Success, } from "./types.js";
+export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CapabilitiesData, CloseSessionData, Column, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfilesData, PurgeData, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StatusConnectionData, StatusData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";

package/dist/src/migrations.d.ts

@@ -0,0 +1,2 @@
+import { DatabaseSync } from "node:sqlite";
+export declare function runMigrations(db: DatabaseSync, now: () => Date): void;

package/dist/src/migrations.js

@@ -0,0 +1,305 @@
+const CORE_TABLES = [
+    "aliases",
+    "connections",
+    "counters",
+    "history",
+    "operations",
+    "plans",
+    "profiles",
+    "results",
+    "sessions",
+    "transactions",
+];
+const CORE_COLUMNS = {
+    counters: ["prefix", "value"],
+    sessions: ["id", "name", "status", "active_connection_id", "active_transaction_id", "created_at", "updated_at"],
+    profiles: ["name", "target", "secret_env", "read_only", "created_at", "updated_at"],
+    connections: ["id", "session_id", "name", "driver", "database_name", "source", "secret_env", "read_only", "version", "created_at"],
+    results: ["id", "session_id", "connection_id", "fingerprint", "sql", "parameters", "rows_json", "columns_json", "row_count", "state_version", "state_signature", "state_confidence", "expires_at", "created_at"],
+    aliases: ["session_id", "name", "result_id"],
+    operations: ["id", "session_id", "connection_id", "fingerprint", "sql", "parameters", "statement_type", "affected_rows", "status", "transaction_id", "replay_of", "idempotency_key", "state_version_before", "state_version_after", "created_at"],
+    transactions: ["id", "session_id", "connection_id", "state", "isolation_level", "start_version", "created_at", "ended_at"],
+    plans: ["id", "session_id", "connection_id", "sql", "parameters", "statement_type", "state_version", "state_signature", "destructive", "allow_unbounded", "allow_destructive", "expires_at", "applied_operation_id", "created_at"],
+    history: ["id", "timestamp", "session_id", "command", "handle", "executed", "cached", "success", "error_code"],
+};
+const MIGRATIONS = [
+    {
+        name: "initial_schema_v1",
+        apply: createInitialSchema,
+        validate(db) {
+            requireTables(db, CORE_TABLES);
+            for (const [table, columns] of Object.entries(CORE_COLUMNS)) {
+                requireColumns(db, table, columns);
+            }
+            requireIndexes(db, [
+                "history_session",
+                "operations_fingerprint",
+                "operations_idempotency",
+                "results_fingerprint",
+            ]);
+            requireForeignKey(db, "connections", "session_id", "sessions", "id");
+            requireForeignKey(db, "aliases", "result_id", "results", "id");
+        },
+    },
+    {
+        name: "shared_session_actors_v1",
+        apply: migrateSharedSessionActors,
+        validate: validateSharedSessionActors,
+    },
+];
+export function runMigrations(db, now) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      name TEXT PRIMARY KEY,
+      applied_at TEXT NOT NULL
+    )
+  `);
+    for (const migration of MIGRATIONS) {
+        db.exec("BEGIN IMMEDIATE");
+        try {
+            // Always reapply idempotently: a migration row is not proof that its
+            // schema changes survived a manually modified or partially copied store.
+            migration.apply(db);
+            migration.validate(db);
+            db.prepare(`INSERT OR IGNORE INTO schema_migrations(name, applied_at)
+         VALUES (?, ?)`).run(migration.name, now().toISOString());
+            db.exec("COMMIT");
+        }
+        catch (error) {
+            db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    const violations = db.prepare("PRAGMA foreign_key_check").all();
+    if (violations.length) {
+        throw new Error("State store failed its foreign-key integrity check.");
+    }
+}
+function createInitialSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS counters (
+      prefix TEXT PRIMARY KEY,
+      value INTEGER NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL UNIQUE,
+      status TEXT NOT NULL,
+      active_connection_id TEXT,
+      active_transaction_id TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS session_members (
+      session_id TEXT NOT NULL,
+      actor_id TEXT NOT NULL UNIQUE,
+      attached_at TEXT NOT NULL,
+      PRIMARY KEY(session_id, actor_id),
+      FOREIGN KEY(session_id) REFERENCES sessions(id)
+    );
+    CREATE TABLE IF NOT EXISTS profiles (
+      name TEXT PRIMARY KEY,
+      target TEXT,
+      secret_env TEXT,
+      read_only INTEGER NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      CHECK(target IS NOT NULL OR secret_env IS NOT NULL)
+    );
+    CREATE TABLE IF NOT EXISTS connections (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      name TEXT NOT NULL,
+      driver TEXT NOT NULL,
+      database_name TEXT NOT NULL,
+      source TEXT NOT NULL,
+      secret_env TEXT,
+      read_only INTEGER NOT NULL,
+      version INTEGER NOT NULL,
+      created_at TEXT NOT NULL,
+      FOREIGN KEY(session_id) REFERENCES sessions(id)
+    );
+    CREATE TABLE IF NOT EXISTS results (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      connection_id TEXT NOT NULL,
+      fingerprint TEXT NOT NULL,
+      sql TEXT NOT NULL,
+      parameters TEXT NOT NULL,
+      rows_json TEXT NOT NULL,
+      columns_json TEXT NOT NULL,
+      row_count INTEGER NOT NULL,
+      state_version TEXT NOT NULL,
+      state_signature TEXT NOT NULL,
+      state_confidence TEXT NOT NULL,
+      expires_at TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS results_fingerprint
+      ON results(fingerprint, created_at);
+    CREATE TABLE IF NOT EXISTS aliases (
+      session_id TEXT NOT NULL,
+      name TEXT NOT NULL,
+      result_id TEXT NOT NULL,
+      PRIMARY KEY(session_id, name),
+      FOREIGN KEY(result_id) REFERENCES results(id)
+    );
+    CREATE TABLE IF NOT EXISTS operations (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      actor_id TEXT NOT NULL,
+      connection_id TEXT NOT NULL,
+      fingerprint TEXT NOT NULL,
+      sql TEXT NOT NULL,
+      parameters TEXT NOT NULL,
+      statement_type TEXT NOT NULL,
+      affected_rows INTEGER,
+      status TEXT NOT NULL,
+      transaction_id TEXT,
+      replay_of TEXT,
+      idempotency_key TEXT,
+      state_version_before TEXT NOT NULL,
+      state_version_after TEXT,
+      created_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS operations_fingerprint
+      ON operations(connection_id, fingerprint, status);
+    CREATE UNIQUE INDEX IF NOT EXISTS operations_idempotency
+      ON operations(connection_id, idempotency_key)
+      WHERE idempotency_key IS NOT NULL AND status IN ('committed', 'pending');
+    CREATE TABLE IF NOT EXISTS transactions (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      owner_actor_id TEXT NOT NULL,
+      connection_id TEXT NOT NULL,
+      state TEXT NOT NULL,
+      isolation_level TEXT NOT NULL,
+      start_version TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      ended_at TEXT
+    );
+    CREATE TABLE IF NOT EXISTS plans (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      owner_actor_id TEXT NOT NULL,
+      connection_id TEXT NOT NULL,
+      sql TEXT NOT NULL,
+      parameters TEXT NOT NULL,
+      statement_type TEXT NOT NULL,
+      state_version TEXT NOT NULL,
+      state_signature TEXT NOT NULL,
+      destructive INTEGER NOT NULL,
+      allow_unbounded INTEGER NOT NULL,
+      allow_destructive INTEGER NOT NULL,
+      expires_at TEXT NOT NULL,
+      applied_operation_id TEXT,
+      claim_token TEXT,
+      created_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS history (
+      id TEXT PRIMARY KEY,
+      timestamp TEXT NOT NULL,
+      session_id TEXT NOT NULL,
+      actor_id TEXT NOT NULL,
+      command TEXT NOT NULL,
+      handle TEXT,
+      executed INTEGER NOT NULL,
+      cached INTEGER NOT NULL,
+      success INTEGER NOT NULL,
+      error_code TEXT
+    );
+    CREATE INDEX IF NOT EXISTS history_session ON history(session_id);
+  `);
+}
+function migrateSharedSessionActors(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS session_members (
+      session_id TEXT NOT NULL,
+      actor_id TEXT NOT NULL UNIQUE,
+      attached_at TEXT NOT NULL,
+      PRIMARY KEY(session_id, actor_id),
+      FOREIGN KEY(session_id) REFERENCES sessions(id)
+    )
+  `);
+    addColumn(db, "operations", "actor_id", "TEXT");
+    addColumn(db, "transactions", "owner_actor_id", "TEXT");
+    addColumn(db, "plans", "owner_actor_id", "TEXT");
+    addColumn(db, "plans", "claim_token", "TEXT");
+    addColumn(db, "history", "actor_id", "TEXT");
+    db.exec(`
+    INSERT OR IGNORE INTO session_members(session_id, actor_id, attached_at)
+    SELECT id, name, created_at FROM sessions;
+    UPDATE operations SET actor_id = (
+      SELECT name FROM sessions WHERE sessions.id = operations.session_id
+    ) WHERE actor_id IS NULL;
+    UPDATE transactions SET owner_actor_id = (
+      SELECT name FROM sessions WHERE sessions.id = transactions.session_id
+    ) WHERE owner_actor_id IS NULL;
+    UPDATE plans SET owner_actor_id = (
+      SELECT name FROM sessions WHERE sessions.id = plans.session_id
+    ) WHERE owner_actor_id IS NULL;
+    UPDATE history SET actor_id = (
+      SELECT name FROM sessions WHERE sessions.id = history.session_id
+    ) WHERE actor_id IS NULL;
+  `);
+}
+function validateSharedSessionActors(db) {
+    requireTables(db, [...CORE_TABLES, "session_members"]);
+    requireColumns(db, "operations", ["actor_id"]);
+    requireColumns(db, "transactions", ["owner_actor_id"]);
+    requireColumns(db, "plans", ["owner_actor_id", "claim_token"]);
+    requireColumns(db, "history", ["actor_id"]);
+    requireForeignKey(db, "session_members", "session_id", "sessions", "id");
+    const invalidMemberships = db.prepare(`SELECT COUNT(*) AS count FROM sessions
+     LEFT JOIN session_members
+       ON session_members.actor_id = sessions.name
+      AND session_members.session_id = sessions.id
+     WHERE session_members.actor_id IS NULL`).get();
+    if (invalidMemberships.count) {
+        throw new Error("State migration could not establish legacy session membership.");
+    }
+    for (const [table, column] of [
+        ["operations", "actor_id"],
+        ["transactions", "owner_actor_id"],
+        ["plans", "owner_actor_id"],
+        ["history", "actor_id"],
+    ]) {
+        const row = db.prepare(`SELECT COUNT(*) AS count FROM ${table} WHERE ${column} IS NULL`).get();
+        if (row.count)
+            throw new Error(`State migration left ${table}.${column} empty.`);
+    }
+}
+function addColumn(db, table, column, definition) {
+    const columns = db.prepare(`PRAGMA table_info(${table})`).all();
+    if (!columns.some((candidate) => candidate.name === column)) {
+        db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
+    }
+}
+function requireTables(db, tables) {
+    const found = new Set(db.prepare("SELECT name FROM sqlite_schema WHERE type = 'table'").all().map((row) => row.name));
+    for (const table of tables) {
+        if (!found.has(table))
+            throw new Error(`State migration did not create table "${table}".`);
+    }
+}
+function requireIndexes(db, required) {
+    const indexes = new Set(db.prepare("SELECT name FROM sqlite_schema WHERE type = 'index'").all().map((index) => index.name));
+    for (const index of required) {
+        if (!indexes.has(index))
+            throw new Error(`State migration did not create index "${index}".`);
+    }
+}
+function requireForeignKey(db, table, from, target, to) {
+    const keys = db.prepare(`PRAGMA foreign_key_list(${table})`).all();
+    if (!keys.some((key) => key.table === target && key.from === from && key.to === to)) {
+        throw new Error(`State migration requires ${table}.${from} to reference ${target}.${to}.`);
+    }
+}
+function requireColumns(db, table, required) {
+    const columns = new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((column) => column.name));
+    for (const column of required) {
+        if (!columns.has(column)) {
+            throw new Error(`State migration did not create ${table}.${column}.`);
+        }
+    }
+}

package/dist/src/response-data.d.ts

@@ -1,8 +1,8 @@
 import type { OperationRecord, ProfileRecord, SessionRecord, TransactionRecord } from "./store.js";
-import type { Row, Warning } from "./types.js";
-export declare function sessionData(session: SessionRecord): unknown;
-export declare function profileData(profile: ProfileRecord): Record<string, unknown>;
-export declare function operationData(operation: OperationRecord): Record<string, unknown>;
-export declare function transactionData(transaction: TransactionRecord, statements: number): unknown;
+import type { OperationData, ProfileData, Row, SessionData, TransactionData, Warning } from "./types.js";
+export declare function sessionData(session: SessionRecord): SessionData;
+export declare function profileData(profile: ProfileRecord): ProfileData;
+export declare function operationData(operation: OperationRecord): OperationData;
+export declare function transactionData(transaction: TransactionRecord, statements: number): TransactionData;
 export declare function paginationWarnings(ordered: boolean): Warning[];
 export declare function rowsToCsv(rows: Row[], columns: string[]): string;

package/dist/src/sqlite-process.js

@@ -1,6 +1,6 @@
 import { existsSync, statSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
-import { hash, parseJson, toJsonSafe } from "./util.js";
+import { hash, isSqlParameters, parseJson, toJsonSafe } from "./util.js";
 let db;
 let source;
 let readOnly = true;
@@ -97,7 +97,7 @@ function execute(request) {
             }
             try {
                 for (const operation of operations) {
-                    const result = bindRun(database.prepare(operation.sql), parseJson(operation.parameters, []));
+                    const result = bindRun(database.prepare(operation.sql), parseJson(operation.parameters, `operation "${operation.id}" parameters`, isSqlParameters));
                     results.push({ affectedRows: Number(result.changes) });
                 }
             }

package/dist/src/stateql.d.ts

@@ -1,4 +1,4 @@
-import type { BatchCommand, BatchOptions, ConnectOptions, ExecOptions, ExecutionOptions, FilterOptions, HistoryEntry, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, StateQLActorOptions, StateQLOptions, StateQLSnapshot } from "./types.js";
+import type { ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchOptions, CapabilitiesData, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, StateQLActorOptions, StateQLOptions, StateQLSnapshot, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
 export declare class StateQL {
     static forActor(options: StateQLActorOptions): StateQL;
     private readonly store;
@@ -14,48 +14,50 @@ export declare class StateQL {
     private readonly signal?;
     private readonly credentialResolver?;
     private readonly now;
+    private closed;
     constructor(options?: StateQLOptions);
     close(): void;
-    connect(target?: string, options?: ConnectOptions): Promise<Response<unknown>>;
-    addProfile(name: string, target?: string, options?: ProfileOptions): Promise<Response<unknown>>;
-    listProfiles(): Promise<Response<unknown>>;
-    showProfile(name: string): Promise<Response<unknown>>;
-    removeProfile(name: string): Promise<Response<unknown>>;
-    disconnect(): Promise<Response<unknown>>;
+    [Symbol.dispose](): void;
+    connect(target?: string, options?: ConnectOptions): Promise<Response<ConnectionData>>;
+    addProfile(name: string, target?: string, options?: ProfileOptions): Promise<Response<ProfileData>>;
+    listProfiles(): Promise<Response<ProfilesData>>;
+    showProfile(name: string): Promise<Response<ProfileData>>;
+    removeProfile(name: string): Promise<Response<RemovedProfileData>>;
+    disconnect(): Promise<Response<DisconnectData>>;
     snapshot(options?: {
         historyLimit?: number;
     }): StateQLSnapshot;
-    status(): Promise<Response<unknown>>;
-    linkActor(session: string, actorId: string): Promise<Response<unknown>>;
-    unlinkActor(session: string, actorId: string): Promise<Response<unknown>>;
-    listActors(session: string): Promise<Response<unknown>>;
-    resolveActor(actorId: string): Promise<Response<unknown>>;
-    startSession(name: string): Promise<Response<unknown>>;
-    listSessions(): Promise<Response<unknown>>;
-    showSession(idOrName?: string): Promise<Response<unknown>>;
-    sessionSummary(): Promise<Response<unknown>>;
-    closeSession(): Promise<Response<unknown>>;
-    query(sql: string, options?: QueryOptions): Promise<Response<unknown>>;
-    show(idOrAlias: string): Promise<Response<unknown>>;
-    filter(idOrAlias: string, predicate: string, options?: FilterOptions): Promise<Response<unknown>>;
-    rows(idOrAlias: string, options?: RowsOptions): Promise<Response<unknown>>;
-    count(idOrAlias: string): Promise<Response<unknown>>;
-    columns(idOrAlias: string): Promise<Response<unknown>>;
-    setAlias(name: string, id: string): Promise<Response<unknown>>;
-    exportResult(idOrAlias: string, output: string, format?: "json" | "jsonl" | "csv"): Promise<Response<unknown>>;
-    exec(sql: string, options?: ExecOptions): Promise<Response<unknown>>;
-    receipt(id: string): Promise<Response<unknown>>;
-    beginTransaction(isolation?: string): Promise<Response<unknown>>;
-    transactionStatus(id?: string): Promise<Response<unknown>>;
-    commitTransaction(id?: string, options?: ExecutionOptions): Promise<Response<unknown>>;
-    rollbackTransaction(id?: string): Promise<Response<unknown>>;
+    status(): Promise<Response<StatusData>>;
+    linkActor(session: string, actorId: string): Promise<Response<ActorLinkData>>;
+    unlinkActor(session: string, actorId: string): Promise<Response<ActorUnlinkData>>;
+    listActors(session: string): Promise<Response<ActorsData>>;
+    resolveActor(actorId: string): Promise<Response<ActorResolutionData>>;
+    startSession(name: string): Promise<Response<SessionData>>;
+    listSessions(): Promise<Response<SessionsData>>;
+    showSession(idOrName?: string): Promise<Response<SessionData>>;
+    sessionSummary(): Promise<Response<SessionSummaryData>>;
+    closeSession(): Promise<Response<CloseSessionData>>;
+    query(sql: string, options?: QueryOptions): Promise<Response<ResultData>>;
+    show(idOrAlias: string): Promise<Response<ResultData>>;
+    filter(idOrAlias: string, predicate: string, options?: FilterOptions): Promise<Response<ResultData>>;
+    rows(idOrAlias: string, options?: RowsOptions): Promise<Response<RowsData>>;
+    count(idOrAlias: string): Promise<Response<CountData>>;
+    columns(idOrAlias: string): Promise<Response<ColumnsData>>;
+    setAlias(name: string, id: string): Promise<Response<AliasData>>;
+    exportResult(idOrAlias: string, output: string, format?: "json" | "jsonl" | "csv"): Promise<Response<ExportData>>;
+    exec(sql: string, options?: ExecOptions): Promise<Response<ExecData>>;
+    receipt(id: string): Promise<Response<OperationData>>;
+    beginTransaction(isolation?: string): Promise<Response<TransactionData>>;
+    transactionStatus(id?: string): Promise<Response<TransactionData>>;
+    commitTransaction(id?: string, options?: ExecutionOptions): Promise<Response<CommitTransactionData>>;
+    rollbackTransaction(id?: string): Promise<Response<RollbackTransactionData>>;
     inspect(kind: string, table?: string, options?: ExecutionOptions): Promise<Response<unknown>>;
-    plan(sql: string, options?: PlanOptions): Promise<Response<unknown>>;
-    apply(planId: string, options?: ExecutionOptions): Promise<Response<unknown>>;
-    history(limit?: number): Promise<Response<{
-        history: HistoryEntry[];
-    }>>;
-    capabilities(): Promise<Response<unknown>>;
+    plan(sql: string, options?: PlanOptions): Promise<Response<PlanData>>;
+    apply(planId: string, options?: ExecutionOptions): Promise<Response<ApplyData>>;
+    history(limit?: number): Promise<Response<HistoryData>>;
+    doctor(): Promise<Response<DoctorData>>;
+    purge(scope?: "expired" | "results" | "history" | "all"): Promise<Response<PurgeData>>;
+    capabilities(): Promise<Response<CapabilitiesData>>;
     executeCommand(command: BatchCommand): Promise<Response<unknown>>;
     batch(commands: Iterable<BatchCommand> | AsyncIterable<BatchCommand>, options?: BatchOptions): AsyncGenerator<Response<unknown>>;
     private performExec;