@fadhilp/stateql 0.11.1 → 0.13.0

package/dist/src/sqlite-process.js

@@ -83,6 +83,22 @@ function execute(request) {
                 }
             }
         }
+        case "writeAutocommit": {
+            if (readOnly)
+                throw new SQLiteBatchError("Connection is read-only.", false);
+            const [sql, params] = request.args;
+            if ((Array.isArray(params) && params.length > 0) ||
+                (!Array.isArray(params) && Object.keys(params).length > 0)) {
+                throw new SQLiteBatchError("SQLite maintenance statements do not accept parameters.", false);
+            }
+            try {
+                database.exec(sql);
+                return { affectedRows: 0 };
+            }
+            catch (error) {
+                throw new SQLiteBatchError(errorText(error), true);
+            }
+        }
         case "writeBatch": {
             if (readOnly)
                 throw new Error("Connection is read-only.");

package/dist/src/stateql.js

@@ -672,7 +672,17 @@ export class StateQL {
             if (!analysis.read) {
                 throw new StateQLError("INVALID_SQL", "query accepts read statements only; use exec for writes.");
             }
+            const cacheMode = options.cache ?? "auto";
+            if (!analysis.cacheable && cacheMode === "require") {
+                throw new StateQLError("CACHE_MISS", "This statement is not cacheable.", {
+                    retryable: true,
+                    suggestedAction: "Run with --cache auto or --cache bypass.",
+                });
+            }
             const parameters = options.params ?? [];
+            if (analysis.requiresAutocommit && sqlParametersLength(parameters) > 0) {
+                throw new StateQLError("INVALID_SQL", "Autocommit diagnostic statements do not accept StateQL parameters.");
+            }
             const context = this.executionContext(options);
             const adapterSource = await this.resolveConnectionSource(connection, session, "query", "read", context);
             const adapter = await this.openAdapter(connection, context, adapterSource);
@@ -689,8 +699,8 @@ export class StateQL {
                     stateVersion,
                 });
                 const cached = this.store.findResult(fingerprint);
-                const cacheMode = options.cache ?? "auto";
-                if (cacheMode !== "bypass" &&
+                if (analysis.cacheable &&
+                    cacheMode !== "bypass" &&
                     cached &&
                     cached.row_count <= this.maxResultRows &&
                     this.cacheValid(cached, stateVersion, stateSignature)) {
@@ -709,7 +719,15 @@ export class StateQL {
                         suggestedAction: "Run with --cache auto or --cache bypass.",
                     });
                 }
-                const result = await adapter.read(boundedReadSql(sql, this.maxResultRows + 1), parameters);
+                const executionSql = analysis.wrapForLimit
+                    ? boundedReadSql(analysis.limitSql ?? sql, this.maxResultRows + 1)
+                    : sql;
+                if (analysis.requiresAutocommit && !adapter.readAutocommit) {
+                    throw new StateQLError("UNSUPPORTED_DRIVER", `${analysis.statementType.toUpperCase()} requires adapter autocommit reads.`);
+                }
+                const result = analysis.requiresAutocommit
+                    ? await adapter.readAutocommit(executionSql, parameters)
+                    : await adapter.read(executionSql, parameters);
                 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." });
                 }
@@ -2200,12 +2218,19 @@ export class StateQL {
             throw new StateQLError("INVALID_COMMAND", "Idempotency key cannot be empty.");
         }
         const parameters = options.params ?? [];
+        if (analysis.requiresAutocommit &&
+            (options.expectedRows !== undefined || sqlParametersLength(parameters) > 0)) {
+            throw new StateQLError("INVALID_SQL", "Autocommit maintenance statements do not accept StateQL parameters or row-count preconditions.");
+        }
+        const transactionId = session.active_transaction_id ?? undefined;
+        if (analysis.requiresAutocommit && transactionId) {
+            throw new StateQLError("TRANSACTION_FAILED", `${analysis.statementType.toUpperCase()} cannot be staged in a transaction.`, { suggestedAction: "Rollback or commit the staged transaction, then run the maintenance statement separately." });
+        }
         const fingerprint = hash({
             sql: analysis.normalized,
             parameters,
             database: databaseIdentity(connection),
         });
-        const transactionId = session.active_transaction_id ?? undefined;
         if (transactionId) {
             const transaction = this.store.getTransaction(transactionId);
             if (!transaction ||
@@ -2305,7 +2330,12 @@ export class StateQL {
             });
         }
         try {
-            const write = await adapter.write(sql, parameters, options.expectedRows);
+            if (analysis.requiresAutocommit && !adapter.writeAutocommit) {
+                throw new AdapterWriteError(`${analysis.statementType.toUpperCase()} requires adapter autocommit execution.`, false);
+            }
+            const write = analysis.requiresAutocommit
+                ? await adapter.writeAutocommit(sql, parameters)
+                : await adapter.write(sql, parameters, options.expectedRows);
             try {
                 const finalized = planClaim
                     ? this.store.finishPlannedOperation({
@@ -3083,6 +3113,11 @@ function markTransactionOutcomeUnknown(store, transactionId, sessionId, actorId)
         // A stale committing transaction is recovered as unknown after five minutes.
     }
 }
+function sqlParametersLength(parameters) {
+    return Array.isArray(parameters)
+        ? parameters.length
+        : Object.keys(parameters).length;
+}
 function boundedReadSql(sql, limit) {
     const statement = sql.trim().replace(/;\s*$/, "");
     return `SELECT * FROM (${statement}) AS _stateql_bounded LIMIT ${limit}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fadhilp/stateql",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "Stateful, agent-oriented database CLI for safe result reuse",
   "repository": {
     "type": "git",
@@ -21,6 +21,7 @@
   "files": [
     "dist/src",
     "README.md",
+    "SQL_COMMAND_ROADMAP.md",
     "LICENSE"
   ],
   "scripts": {