@fadhilp/stateql 0.5.0 → 0.5.3

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
 
@@ -454,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

@@ -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);

package/dist/src/migrations.js

@@ -46,6 +46,15 @@ const MIGRATIONS = [
         apply: migrateSharedSessionActors,
         validate: validateSharedSessionActors,
     },
+    {
+        name: "history_sql_v1",
+        apply(db) {
+            addColumn(db, "history", "sql", "TEXT");
+        },
+        validate(db) {
+            requireColumns(db, "history", ["sql"]);
+        },
+    },
 ];
 export function runMigrations(db, now) {
     db.exec(`
@@ -202,6 +211,7 @@ function createInitialSchema(db) {
       session_id TEXT NOT NULL,
       actor_id TEXT NOT NULL,
       command TEXT NOT NULL,
+      sql TEXT,
       handle TEXT,
       executed INTEGER NOT NULL,
       cached INTEGER NOT NULL,

package/dist/src/stateql.js

@@ -613,7 +613,7 @@ export class StateQL {
             finally {
                 await closeAdapterQuietly(adapter);
             }
-        });
+        }, sql);
     }
     async show(idOrAlias) {
         return this.withResult("show", idOrAlias, async (result) => ({
@@ -756,7 +756,7 @@ export class StateQL {
         return this.run("exec", async (session) => {
             const connection = this.requireConnection(session);
             return this.performExec(session, connection, sql, options, this.executionContext(options));
-        });
+        }, sql);
     }
     async receipt(id) {
         return this.run("receipt", async (session) => {
@@ -1023,9 +1023,10 @@ export class StateQL {
             finally {
                 await closeAdapterQuietly(adapter);
             }
-        });
+        }, sql);
     }
     async apply(planId, options = {}) {
+        let historySql;
         return this.run("apply", async (session) => {
             this.rejectDuringStagedTransaction(session, "Plans");
             const plan = this.store.getPlan(planId);
@@ -1043,6 +1044,7 @@ export class StateQL {
             if (Date.parse(plan.expires_at) <= this.now().getTime()) {
                 throw new StateQLError("STALE_PLAN", "Plan has expired.");
             }
+            historySql = plan.sql;
             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);
@@ -1096,7 +1098,7 @@ export class StateQL {
                 if (!retainClaim)
                     this.store.releasePlanClaim(plan.id, claimToken);
             }
-        });
+        }, () => historySql);
     }
     async history(limit = 20) {
         return this.run("history", async (session) => ({
@@ -1642,7 +1644,7 @@ export class StateQL {
             result.state_version === stateVersion &&
             result.state_signature === stateSignature);
     }
-    async run(command, action) {
+    async run(command, action, historySql) {
         const started = performance.now();
         let session = this.store.ensureSession(this.sessionName);
         const commandId = this.store.nextId("cmd");
@@ -1661,12 +1663,14 @@ export class StateQL {
         try {
             const result = await action(session);
             const responseSession = result.session ?? session;
+            const sqlText = resolveHistorySql(historySql);
             this.store.addHistory({
                 id: commandId,
                 sessionId: session.id,
                 actorId: this.actorId,
                 command,
                 ...(result.handle ? { handle: result.handle } : {}),
+                ...(sqlText !== undefined ? { sql: sqlText } : {}),
                 executed: result.executed ?? false,
                 cached: result.cached ?? false,
                 success: true,
@@ -1690,11 +1694,13 @@ export class StateQL {
         }
         catch (error) {
             const stateqlError = asStateQLError(error);
+            const sqlText = resolveHistorySql(historySql);
             this.store.addHistory({
                 id: commandId,
                 sessionId: session.id,
                 actorId: this.actorId,
                 command,
+                ...(sqlText !== undefined ? { sql: sqlText } : {}),
                 executed: stateqlError.details.executed,
                 cached: false,
                 success: false,
@@ -1712,6 +1718,9 @@ export class StateQL {
         }
     }
 }
+function resolveHistorySql(sql) {
+    return typeof sql === "function" ? sql() : sql;
+}
 function historyEntry(item) {
     return {
         command_id: item.id,
@@ -1719,6 +1728,7 @@ function historyEntry(item) {
         session_id: item.session_id,
         actor_id: item.actor_id,
         command: item.command,
+        sql: item.sql,
         handle: item.handle,
         executed: Boolean(item.executed),
         cached: Boolean(item.cached),
@@ -1800,7 +1810,6 @@ async function resolveCredentialBeforeDeadline(resolver, request, context) {
         };
         const abort = () => finish(() => reject(new CredentialResolutionError("cancelled")));
         const timer = setTimeout(() => finish(() => reject(new CredentialResolutionError("timeout"))), remaining);
-        timer.unref?.();
         context.signal?.addEventListener("abort", abort, { once: true });
         Promise.resolve()
             .then(() => resolver(request))

package/dist/src/store.d.ts

@@ -98,6 +98,7 @@ export interface HistoryRecord {
     session_id: string;
     actor_id: string;
     command: string;
+    sql: string | null;
     handle: string | null;
     executed: number;
     cached: number;
@@ -267,6 +268,7 @@ export declare class StateStore {
         sessionId: string;
         actorId: string;
         command: string;
+        sql?: string;
         handle?: string;
         executed: boolean;
         cached: boolean;

package/dist/src/store.js

@@ -6,6 +6,7 @@ import { runMigrations } from "./migrations.js";
 import { StateQLError } from "./errors.js";
 import { isColumns, isRows, isSqlParameters, parseJson, toJsonSafe, } from "./util.js";
 const HISTORY_LIMIT_PER_SESSION = 10_000;
+const MAX_HISTORY_SQL_BYTES = 4_096;
 const DEFAULT_MAX_STATE_BYTES = 256 * 1024 * 1024;
 export class StateStore {
     now;
@@ -791,10 +792,10 @@ export class StateStore {
         const id = input.id ?? this.nextId("cmd");
         this.db
             .prepare(`INSERT INTO history
-          (id, timestamp, session_id, actor_id, command, handle, executed,
+          (id, timestamp, session_id, actor_id, command, sql, handle, executed,
            cached, success, error_code)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-            .run(id, this.now().toISOString(), input.sessionId, input.actorId, input.command, input.handle ?? null, input.executed ? 1 : 0, input.cached ? 1 : 0, input.success ? 1 : 0, input.errorCode ?? null);
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, this.now().toISOString(), input.sessionId, input.actorId, input.command, boundedHistorySql(input.sql), input.handle ?? null, input.executed ? 1 : 0, input.cached ? 1 : 0, input.success ? 1 : 0, input.errorCode ?? null);
         this.db
             .prepare(`DELETE FROM history
          WHERE rowid IN (
@@ -1010,6 +1011,22 @@ export class StateStore {
         }
     }
 }
+function boundedHistorySql(sql) {
+    if (sql === undefined)
+        return null;
+    if (Buffer.byteLength(sql, "utf8") <= MAX_HISTORY_SQL_BYTES)
+        return sql;
+    const suffix = "…";
+    let prefix = "";
+    for (const character of sql) {
+        if (Buffer.byteLength(`${prefix}${character}${suffix}`, "utf8") >
+            MAX_HISTORY_SQL_BYTES) {
+            break;
+        }
+        prefix += character;
+    }
+    return `${prefix}${suffix}`;
+}
 function restrictMode(path, allowed) {
     chmodSync(path, statSync(path).mode & allowed);
 }

package/dist/src/types.d.ts

@@ -64,6 +64,7 @@ export interface HistoryEntry {
     session_id: string;
     actor_id: string;
     command: string;
+    sql: string | null;
     handle: string | null;
     executed: boolean;
     cached: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fadhilp/stateql",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "description": "Stateful, agent-oriented database CLI for safe result reuse",
   "repository": {
     "type": "git",
@@ -26,6 +26,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "npm run build && node --test dist/test/cli.test.js dist/test/credential.test.js dist/test/mysql.test.js dist/test/postgres.test.js dist/test/query.test.js dist/test/sqlite.test.js dist/test/store.test.js dist/test/terminal.test.js dist/test/transaction.test.js dist/test/write.test.js",
+    "release": "npm version",
+    "version": "npm install",
     "prepack": "npm test"
   },
   "keywords": [
@@ -39,7 +41,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=22.5"
+    "node": ">=22.16"
   },
   "dependencies": {
     "mysql2": "^3.23.1",