@fadhilp/stateql 0.4.2 → 0.5.0

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;

package/dist/src/stateql.js

@@ -8,7 +8,7 @@ import { filterMaterializedRows, prepareFilterStatement, validateFilterParameter
 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";
+import { compactRows, defaultHome, hash, isSqlParameters, parseJson, redact, } from "./util.js";
 const DEFAULT_SNAPSHOT_HISTORY_LIMIT = 50;
 const MAX_SNAPSHOT_HISTORY_LIMIT = 100;
 export class StateQL {
@@ -42,6 +42,7 @@ export class StateQL {
     signal;
     credentialResolver;
     now;
+    closed = false;
     constructor(options = {}) {
         this.now = options.now ?? (() => new Date());
         this.sessionName = options.session ?? env.STQL_SESSION ?? "default";
@@ -49,24 +50,38 @@ export class StateQL {
         if (!this.actorId.trim()) {
             throw new StateQLError("INVALID_COMMAND", "Actor ID is required.");
         }
-        this.previewRows = options.previewRows ?? 5;
-        this.cacheTtlSeconds = options.cacheTtlSeconds ?? 300;
-        this.resultTtlSeconds = options.resultTtlSeconds ?? 86_400;
-        this.maxCellCharacters = options.maxCellCharacters ?? 200;
+        this.previewRows = nonNegativeInteger(options.previewRows ?? 5, "previewRows");
+        this.cacheTtlSeconds = nonNegativeInteger(options.cacheTtlSeconds ?? 300, "cacheTtlSeconds");
+        this.resultTtlSeconds = positiveInteger(options.resultTtlSeconds ?? 86_400, "resultTtlSeconds");
+        this.maxCellCharacters = positiveInteger(options.maxCellCharacters ?? 200, "maxCellCharacters");
         this.maxResultRows = positiveInteger(options.maxResultRows ?? 10_000, "maxResultRows");
         this.maxResultBytes = positiveInteger(options.maxResultBytes ?? 16 * 1024 * 1024, "maxResultBytes");
         this.timeoutMs = executionTimeout(options.timeoutMs ?? 30_000);
+        const maxStateBytes = positiveInteger(options.maxStateBytes ?? 256 * 1024 * 1024, "maxStateBytes");
         this.signal = options.signal;
         this.credentialResolver = options.credentialResolver;
         if (this.maxResultRows >= Number.MAX_SAFE_INTEGER) {
             throw new StateQLError("INVALID_COMMAND", "maxResultRows is too large.");
         }
-        this.store = new StateStore(options.home ?? defaultHome(), this.now);
-        this.store.bootstrapSession(this.sessionName, this.actorId, options.actor === undefined);
+        const store = new StateStore(options.home ?? defaultHome(), this.now, maxStateBytes);
+        try {
+            store.bootstrapSession(this.sessionName, this.actorId, options.actor === undefined);
+        }
+        catch (error) {
+            store.close();
+            throw error;
+        }
+        this.store = store;
     }
     close() {
+        if (this.closed)
+            return;
+        this.closed = true;
         this.store.close();
     }
+    [Symbol.dispose]() {
+        this.close();
+    }
     async connect(target, options = {}) {
         return this.run("connect", async (session) => {
             if (session.active_transaction_id) {
@@ -811,14 +826,16 @@ export class StateQL {
             if (version(connection) !== transaction.start_version) {
                 throw new StateQLError("TRANSACTION_FAILED", "Connection state changed after the transaction began.", { suggestedAction: "Roll back and begin a new transaction." });
             }
+            // Validate durable payloads before opening a database adapter or changing
+            // the transaction state.
+            const operations = this.store.validatedTransactionOperations(transaction.id);
             const context = this.executionContext(options);
             const adapterSource = await this.resolveConnectionSource(connection, session, "transaction.commit", "write", context);
             const adapter = await this.openAdapter(connection, context, adapterSource);
             try {
-                if (!this.store.markTransactionCommitting(transaction.id, session.id, this.actorId)) {
+                if (!this.store.claimTransactionForCommit(transaction.id, session.id, this.actorId, operations)) {
                     throw new StateQLError("TRANSACTION_FAILED", "Transaction is no longer active.");
                 }
-                const operations = this.store.transactionOperations(transaction.id);
                 if (operations.some((operation) => operation.connection_id !== connection.id)) {
                     this.store.finishTransaction(transaction.id, session.id, this.actorId, "failed");
                     throw new StateQLError("TRANSACTION_FAILED", "Transaction contains writes staged for another connection.");
@@ -1026,6 +1043,7 @@ export class StateQL {
             if (Date.parse(plan.expires_at) <= this.now().getTime()) {
                 throw new StateQLError("STALE_PLAN", "Plan has expired.");
             }
+            const planParameters = parseJson(plan.parameters, `plan "${plan.id}" parameters`, isSqlParameters);
             const claimToken = this.store.nextId("claim");
             const claimed = this.store.claimPlan(plan.id, session.id, this.actorId, claimToken);
             if (!claimed) {
@@ -1058,7 +1076,7 @@ export class StateQL {
                     await closeAdapterQuietly(adapter);
                 }
                 const result = await this.performExec(session, connection, claimed.sql, {
-                    params: parseJson(claimed.parameters, []),
+                    params: planParameters,
                     allowUnbounded: Boolean(claimed.allow_unbounded),
                     allowDestructive: Boolean(claimed.allow_destructive),
                 }, context, { planId: claimed.id, claimToken }, adapterSource);
@@ -1089,6 +1107,25 @@ export class StateQL {
             },
         }));
     }
+    async doctor() {
+        return this.run("doctor", async (session) => ({
+            data: this.store.diagnostics(session.id),
+        }));
+    }
+    async purge(scope = "expired") {
+        return this.run("purge", async (session) => {
+            if (!["expired", "results", "history", "all"].includes(scope)) {
+                throw new StateQLError("INVALID_COMMAND", `Unknown purge scope "${scope}".`);
+            }
+            if (scope === "all" && session.active_transaction_id) {
+                throw new StateQLError("TRANSACTION_FAILED", "Commit or roll back the active transaction before purging all data.");
+            }
+            return {
+                data: { scope, deleted: this.store.purge(session.id, scope) },
+                executed: true,
+            };
+        });
+    }
     async capabilities() {
         return this.run("capabilities", async () => ({
             data: {
@@ -1104,6 +1141,9 @@ export class StateQL {
                     credential_resolver: true,
                     deadlines: true,
                     cancellation: true,
+                    state_diagnostics: true,
+                    state_purge: true,
+                    state_quota: true,
                 },
             },
         }));
@@ -1228,6 +1268,10 @@ export class StateQL {
                     return this.history(command.limit ?? 20);
                 case "receipt":
                     return this.receipt(batchString(command.handle, "handle"));
+                case "doctor":
+                    return this.doctor();
+                case "purge":
+                    return this.purge(command.scope ?? "expired");
                 case "capabilities":
                     return this.capabilities();
                 default:

package/dist/src/store.d.ts

@@ -111,8 +111,10 @@ export interface SessionMemberRecord {
 }
 export declare class StateStore {
     private readonly now;
+    private readonly maxStateBytes;
     readonly db: DatabaseSync;
-    constructor(home: string, now: () => Date);
+    private closed;
+    constructor(home: string, now: () => Date, maxStateBytes?: number);
     close(): void;
     nextId(prefix: string): string;
     ensureSession(name?: string): SessionRecord;
@@ -219,6 +221,8 @@ export declare class StateStore {
     }): TransactionRecord | undefined;
     getTransaction(id: string): TransactionRecord | undefined;
     transactionOperations(transactionId: string): OperationRecord[];
+    validatedTransactionOperations(transactionId: string): OperationRecord[];
+    claimTransactionForCommit(transactionId: string, sessionId: string, actorId: string, expectedOperations: OperationRecord[]): boolean;
     markTransactionCommitting(transactionId: string, sessionId: string, actorId: string): boolean;
     markTransactionOutcomeUnknown(transactionId: string, sessionId: string, actorId: string): void;
     finishTransaction(transactionId: string, sessionId: string, actorId: string, state: "rolled_back" | "failed"): boolean;
@@ -275,8 +279,22 @@ export declare class StateStore {
     knownResults(sessionId: string, limit: number): Array<ResultRecord & {
         alias: string | null;
     }>;
+    diagnostics(sessionId: string): {
+        integrity: "ok" | "issues";
+        issues: Array<{
+            code: string;
+            record?: string;
+        }>;
+        migrations: string[];
+        storage: {
+            result_bytes: number;
+            results: number;
+            history: number;
+        };
+    };
+    purge(sessionId: string, scope: "expired" | "results" | "history" | "all"): number;
+    private enforceResultQuota;
+    private resultBytes;
     private deleteExpiredData;
     private recoverStaleCommittingTransactions;
-    private migrate;
-    private addColumn;
 }