@fadhilp/stateql 0.11.0 → 0.12.0

package/README.md

@@ -216,6 +216,37 @@ Use `--params JSON` for a JSON array or named parameters. Use
 `--params-file FILE` when JSON is awkward to quote; `--params-file -` reads
 JSON from standard input.
 
+### PostgreSQL diagnostics and maintenance
+
+Run PostgreSQL plans through `query`:
+
+```bash
+stql query "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) SELECT * FROM jobs WHERE id = 42"
+```
+
+Plain `EXPLAIN` may plan a structurally validated `SELECT`, `INSERT`, `UPDATE`,
+or `DELETE`. Because `EXPLAIN ANALYZE` executes its inner statement, StateQL
+accepts only a validated read-only `SELECT`; `SELECT INTO`, writing CTEs, and
+mutations are rejected. Diagnostics execute inside PostgreSQL `BEGIN READ ONLY`
+and are never reused from cache. `--cache require` therefore returns
+`CACHE_MISS` without executing the diagnostic.
+
+`VACUUM`, `ANALYZE`, `REINDEX`, and `CLUSTER` are PostgreSQL maintenance writes:
+
+```bash
+stql exec "VACUUM (ANALYZE) public.jobs" --allow-destructive
+stql plan "REINDEX TABLE public.jobs" --allow-destructive
+```
+
+They require a read-write connection and `--allow-destructive`, reject StateQL
+parameters, and run as individually tracked autocommit operations. They cannot
+be staged in a StateQL transaction. A timeout or cancellation after dispatch is
+reported as `OUTCOME_UNKNOWN`; inspect database state before replaying it. Raw
+`BEGIN`, `COMMIT`, `ROLLBACK`, savepoint, and other transaction-control SQL
+remain unsupported—use `stql transaction` commands instead. See
+[`SQL_COMMAND_ROADMAP.md`](SQL_COMMAND_ROADMAP.md) for the exact implemented
+boundary and deferred command categories.
+
 ### Native MongoDB
 
 MongoDB commands use official Extended JSON (EJSON), so BSON values survive the
@@ -479,16 +510,40 @@ context as `options.executionContext` for all commands in that batch.
 
 ### Actor workspaces
 
-`StateQL.forActor(...)` resolves the actor's attached session directly from
-StateQL storage, avoiding a duplicate actor-to-session mapping in integrations.
-On first use, it creates a legacy-compatible session named after the actor. Use
-`new StateQL({ session, actor })` when the session is already known.
+`StateQL.forWorkspace(...)` is a trusted-host primitive that atomically creates
+or reopens a durable workspace, attaches the requested actor, and returns a
+client bound to that actor:
+
+```ts
+const stateql = StateQL.forWorkspace({
+  home: "./.stql",
+  workspace: "pylon-global",
+  actor: "pylon-session:abc123",
+  credentialResolver,
+  signal,
+});
+```
 
-Membership is managed only through the library API, not batch commands:
-`linkActor(session, actorId)`, `unlinkActor(session, actorId)`,
-`listActors(session)`, and `resolveActor(actorId)`. An existing member must link
-an actor before that actor opens an existing workspace. Integrations should ask
-for user confirmation before changing membership or the shared connection.
+Repeated opens of the same actor and workspace are idempotent. An actor already
+attached elsewhere fails with a `StateQLError` whose code is
+`PERMISSION_DENIED`; StateQL never moves or merges it. All actor options,
+including limits, credential resolution, cancellation, `home`, and `now`, are
+preserved. The workspace name also reserves a same-named actor identity for
+legacy compatibility, so workspace and actor identifiers must be globally
+collision-free. The returned client is still bound only to `actor`, preserving
+plan, transaction, operation, and history ownership.
+
+`StateQL.forActor(...)` retains its existing behavior: it resolves the actor's
+attached session directly from StateQL storage and creates a legacy-compatible
+session named after the actor on first use. Use `new StateQL({ session, actor })`
+when the session and membership are already known.
+
+Membership management and `forWorkspace` are library-only host capabilities,
+not batch or CLI commands. Existing member-authorized management remains
+available through `linkActor(session, actorId)`, `unlinkActor(session, actorId)`,
+`listActors(session)`, and `resolveActor(actorId)`. Integrations should ask for
+user confirmation before changing membership or the shared connection; a host
+calling `forWorkspace` is responsible for authorizing that workspace access.
 
 ### Harness credential resolution
 

package/dist/src/adapters.d.ts

@@ -33,6 +33,7 @@ export interface Adapter {
     ping(): Promise<void>;
     read(sql: string, params: SqlParameters): Promise<ReadResult>;
     write(sql: string, params: SqlParameters, expectedRows?: 1): Promise<WriteResult>;
+    writeAutocommit?(sql: string, params: SqlParameters): Promise<WriteResult>;
     writeBatch(operations: BatchWriteOperation[], isolation: string): Promise<WriteResult[]>;
     signature(): Promise<string>;
     inspect(kind: string, table?: string): Promise<unknown>;

package/dist/src/adapters.js

@@ -218,6 +218,12 @@ export function normalizePostgresConnectionString(source) {
         return source;
     }
 }
+const POSTGRES_AUTOCOMMIT_STATEMENTS = new Set([
+    "vacuum",
+    "analyze",
+    "reindex",
+    "cluster",
+]);
 class PostgresAdapter {
     readOnly;
     context;
@@ -294,9 +300,36 @@ class PostgresAdapter {
             throw new AdapterWriteError(errorText(error), true);
         }
     }
+    async writeAutocommit(sql, params) {
+        if (this.readOnly)
+            throw new Error("Connection is read-only.");
+        let values;
+        try {
+            values = postgresParams(params);
+            await this.connect();
+        }
+        catch (error) {
+            if (error instanceof AdapterExecutionError)
+                throw error;
+            throw new AdapterWriteError(errorText(error), false);
+        }
+        try {
+            const result = await this.query(sql, values, true, false);
+            return { affectedRows: result.rowCount ?? 0 };
+        }
+        catch (error) {
+            if (error instanceof AdapterExecutionError)
+                throw error;
+            throw new AdapterWriteError(errorText(error), true);
+        }
+    }
     async writeBatch(operations, isolation) {
         if (this.readOnly)
             throw new Error("Connection is read-only.");
+        const unsupported = operations.find((operation) => POSTGRES_AUTOCOMMIT_STATEMENTS.has(operation.statement_type));
+        if (unsupported) {
+            throw new BatchWriteError(`PostgreSQL transactions cannot include ${unsupported.statement_type.toUpperCase()} maintenance statements.`, false);
+        }
         await this.connect();
         const level = isolation.toUpperCase();
         if (!POSTGRES_ISOLATION_LEVELS.has(level)) {
@@ -491,8 +524,8 @@ class PostgresAdapter {
     async setLocalDeadline() {
         await this.query(`SET LOCAL statement_timeout = ${remainingMilliseconds(this.context)}`, [], false);
     }
-    async query(sql, params, outcomeUnknown) {
-        throwIfStopped(this.context, outcomeUnknown);
+    async query(sql, params, outcomeUnknown, preDispatchOutcomeUnknown = outcomeUnknown) {
+        throwIfStopped(this.context, preDispatchOutcomeUnknown);
         try {
             return await withContext(this.client.query(sql, params), this.context, () => this.stop(), outcomeUnknown);
         }

package/dist/src/index.d.ts

@@ -2,4 +2,4 @@ export { StateQL } from "./stateql.js";
 export { CredentialResolutionError, StateQLError, exitCodeFor, } from "./errors.js";
 export type { CredentialResolutionFailure } from "./errors.js";
 export type { TableChange, TableIdentity, TableUpdate } from "./table-editor.js";
-export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CatalogObject, CatalogObjectKind, DescribeObjectData, ListObjectsData, ListObjectsFilter, CapabilitiesData, CommandExecutionContext, CommandOrigin, CloseSessionData, Column, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialSource, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, HistoryCategory, HistoryOptions, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfileUpdateOptions, ProfilesData, PurgeData, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, RedisWriteOutcome, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StateQLSnapshotOptions, StatusConnectionData, StatusData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";
+export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CatalogObject, CatalogObjectKind, DescribeObjectData, ListObjectsData, ListObjectsFilter, CapabilitiesData, CommandExecutionContext, CommandOrigin, CloseSessionData, Column, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialSource, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, HistoryCategory, HistoryOptions, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfileUpdateOptions, ProfilesData, PurgeData, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, RedisWriteOutcome, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StateQLSnapshotOptions, StateQLWorkspaceOptions, StatusConnectionData, StatusData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";

package/dist/src/sql.d.ts

@@ -1,6 +1,6 @@
 import type { AST } from "node-sql-parser";
 import type { Driver, SqlDriver } from "./types.js";
-export type StatementType = "select" | "insert" | "replace" | "update" | "delete" | "create" | "alter" | "drop" | "truncate";
+export type StatementType = "select" | "insert" | "replace" | "update" | "delete" | "create" | "alter" | "drop" | "truncate" | "explain" | "vacuum" | "analyze" | "reindex" | "cluster";
 export interface SqlAnalysis {
     ast: AST;
     normalized: string;
@@ -9,6 +9,9 @@ export interface SqlAnalysis {
     unboundedMutation: boolean;
     destructive: boolean;
     ordered: boolean;
+    wrapForLimit: boolean;
+    cacheable: boolean;
+    requiresAutocommit: boolean;
 }
 export declare function analyzeSql(sql: string, driver: SqlDriver): SqlAnalysis;
 /** @internal Compatibility for existing connection records during Mongo rollout. */

package/dist/src/sql.js

@@ -14,68 +14,19 @@ const SUPPORTED_STATEMENTS = new Set([
     "truncate",
 ]);
 export function analyzeSql(sql, driver) {
-    if (driver === "mongodb") {
-        throw new StateQLError("INVALID_SQL", "SQL is not supported for MongoDB connections.");
+    if (driver === "mongodb" || driver === "redis") {
+        throw new StateQLError("INVALID_SQL", `SQL is not supported for ${driver} connections.`);
     }
     const trimmed = sql.trim();
     if (!trimmed)
         throw new StateQLError("INVALID_SQL", "SQL is empty.");
     try {
-        const database = driver === "postgres"
-            ? "Postgresql"
-            : driver === "mysql"
-                ? "MySQL"
-                : "Sqlite";
-        const parserSql = driver === "postgres"
-            ? postgresParserSql(trimmed)
-            : trimmed;
-        const parsed = parser.astify(parserSql, { database });
-        if (Array.isArray(parsed)) {
-            if (parsed.length !== 1) {
-                throw new StateQLError("INVALID_SQL", "Exactly one SQL statement is required.");
-            }
+        if (driver === "postgres") {
+            const postgresCommand = analyzePostgresCommand(trimmed);
+            if (postgresCommand)
+                return postgresCommand;
         }
-        const ast = (Array.isArray(parsed) ? parsed[0] : parsed);
-        if (!ast)
-            throw new StateQLError("INVALID_SQL", "SQL is empty.");
-        const rawType = String(ast.type);
-        if (!SUPPORTED_STATEMENTS.has(rawType)) {
-            throw new StateQLError("INVALID_SQL", `Unsupported SQL statement type "${rawType}".`);
-        }
-        const statementType = rawType;
-        if (statementType === "select" && selectContainsWrite(ast)) {
-            throw new StateQLError("INVALID_SQL", "Read statements cannot contain writes or SELECT INTO.");
-        }
-        const normalized = parserSql === trimmed
-            ? parser
-                .sqlify(ast, { database })
-                .replace(/;\s*$/, "")
-                .replace(/\s+/g, " ")
-                .trim()
-            // Keep the exact ordering modifiers in cache and idempotency fingerprints.
-            // The parser copy is analysis-only; adapters execute the original SQL.
-            : trimmed.replace(/;\s*$/, "");
-        const details = ast;
-        const read = statementType === "select";
-        const mutation = statementType === "update" ||
-            statementType === "delete" ||
-            statementType === "truncate";
-        const destructive = statementType === "drop" ||
-            statementType === "alter" ||
-            statementType === "delete" ||
-            statementType === "replace" ||
-            statementType === "truncate" ||
-            (driver === "sqlite" &&
-                /^(?:INSERT|UPDATE) OR REPLACE\b/i.test(normalized));
-        return {
-            ast,
-            normalized,
-            statementType,
-            read,
-            unboundedMutation: statementType === "truncate" || (mutation && !details.where),
-            destructive,
-            ordered: read && Boolean(details.orderby),
-        };
+        return analyzeParsedSql(trimmed, driver);
     }
     catch (error) {
         if (error instanceof StateQLError)
@@ -84,6 +35,542 @@ export function analyzeSql(sql, driver) {
         throw new StateQLError("INVALID_SQL", message);
     }
 }
+function analyzeParsedSql(sql, driver) {
+    const database = driver === "postgres"
+        ? "Postgresql"
+        : driver === "mysql"
+            ? "MySQL"
+            : "Sqlite";
+    const parserSql = driver === "postgres" ? postgresParserSql(sql) : sql;
+    const parsed = parser.astify(parserSql, { database });
+    if (Array.isArray(parsed) && parsed.length !== 1) {
+        throw new StateQLError("INVALID_SQL", "Exactly one SQL statement is required.");
+    }
+    const ast = (Array.isArray(parsed) ? parsed[0] : parsed);
+    if (!ast)
+        throw new StateQLError("INVALID_SQL", "SQL is empty.");
+    const rawType = String(ast.type);
+    if (!SUPPORTED_STATEMENTS.has(rawType)) {
+        throw new StateQLError("INVALID_SQL", `Unsupported SQL statement type "${rawType}".`);
+    }
+    const statementType = rawType;
+    if (statementType === "select" && selectContainsWrite(ast)) {
+        throw new StateQLError("INVALID_SQL", "Read statements cannot contain writes or SELECT INTO.");
+    }
+    const normalized = parserSql === sql
+        ? parser
+            .sqlify(ast, { database })
+            .replace(/;\s*$/, "")
+            .replace(/\s+/g, " ")
+            .trim()
+        // Keep the exact ordering modifiers in cache and idempotency fingerprints.
+        // The parser copy is analysis-only; adapters execute the original SQL.
+        : sql.replace(/;\s*$/, "");
+    const details = ast;
+    const read = statementType === "select";
+    const mutation = statementType === "update" ||
+        statementType === "delete" ||
+        statementType === "truncate";
+    const destructive = statementType === "drop" ||
+        statementType === "alter" ||
+        statementType === "delete" ||
+        statementType === "replace" ||
+        statementType === "truncate" ||
+        (driver === "sqlite" &&
+            /^(?:INSERT|UPDATE) OR REPLACE\b/i.test(normalized));
+    return {
+        ast,
+        normalized,
+        statementType,
+        read,
+        unboundedMutation: statementType === "truncate" || (mutation && !details.where),
+        destructive,
+        ordered: read && Boolean(details.orderby),
+        wrapForLimit: read,
+        cacheable: true,
+        requiresAutocommit: false,
+    };
+}
+const EXPLAIN_INNER_STATEMENTS = new Set([
+    "select",
+    "insert",
+    "update",
+    "delete",
+]);
+const EXPLAIN_BOOLEAN_OPTIONS = new Set([
+    "ANALYZE",
+    "VERBOSE",
+    "COSTS",
+    "SETTINGS",
+    "GENERIC_PLAN",
+    "BUFFERS",
+    "WAL",
+    "TIMING",
+    "SUMMARY",
+    "MEMORY",
+]);
+const EXPLAIN_FORMATS = new Set(["TEXT", "XML", "JSON", "YAML"]);
+const EXPLAIN_SERIALIZE = new Set(["NONE", "TEXT", "BINARY"]);
+const BOOLEAN_VALUES = new Set(["TRUE", "FALSE", "ON", "OFF"]);
+function analyzePostgresCommand(sql) {
+    const scanner = new PostgresPrefixScanner(sql);
+    const command = scanner.readWord();
+    if (!command)
+        return undefined;
+    switch (command.value) {
+        case "EXPLAIN":
+            return analyzePostgresExplain(sql, scanner);
+        case "VACUUM":
+        case "ANALYZE":
+        case "REINDEX":
+        case "CLUSTER":
+            return analyzePostgresMaintenance(sql, command.value);
+        default:
+            return undefined;
+    }
+}
+function analyzePostgresExplain(sql, scanner) {
+    let analyze = false;
+    const seen = new Set();
+    if (scanner.consume("(")) {
+        while (true) {
+            const option = scanner.readWord();
+            if (!option || seen.has(option.value))
+                invalidPostgresSyntax("EXPLAIN");
+            seen.add(option.value);
+            const next = scanner.peek();
+            let value;
+            if (next !== "," && next !== ")") {
+                value = scanner.readWord()?.value;
+                if (!value)
+                    invalidPostgresSyntax("EXPLAIN");
+            }
+            validateExplainOption(option.value, value);
+            if (option.value === "ANALYZE") {
+                analyze = value === undefined || value === "TRUE" || value === "ON";
+            }
+            if (scanner.consume(")"))
+                break;
+            if (!scanner.consume(","))
+                invalidPostgresSyntax("EXPLAIN");
+        }
+    }
+    else {
+        while (true) {
+            const option = scanner.peekWord();
+            if (option !== "ANALYZE" && option !== "VERBOSE")
+                break;
+            scanner.readWord();
+            if (seen.has(option))
+                invalidPostgresSyntax("EXPLAIN");
+            seen.add(option);
+            if (option === "ANALYZE")
+                analyze = true;
+        }
+    }
+    const innerSql = sql.slice(scanner.triviaEnd());
+    if (!innerSql)
+        invalidPostgresSyntax("EXPLAIN");
+    const inner = analyzeParsedSql(innerSql, "postgres");
+    if (!EXPLAIN_INNER_STATEMENTS.has(inner.statementType)) {
+        throw new StateQLError("INVALID_SQL", `EXPLAIN does not support ${inner.statementType.toUpperCase()} statements.`);
+    }
+    if (analyze && inner.statementType !== "select") {
+        throw new StateQLError("INVALID_SQL", "EXPLAIN ANALYZE accepts read-only SELECT statements only.");
+    }
+    return {
+        ast: inner.ast,
+        normalized: sql.replace(/;\s*$/, ""),
+        statementType: "explain",
+        read: true,
+        unboundedMutation: false,
+        destructive: false,
+        ordered: false,
+        wrapForLimit: false,
+        cacheable: false,
+        requiresAutocommit: false,
+    };
+}
+function validateExplainOption(option, value) {
+    if (EXPLAIN_BOOLEAN_OPTIONS.has(option)) {
+        if (value !== undefined && !BOOLEAN_VALUES.has(value))
+            invalidPostgresSyntax("EXPLAIN");
+        return;
+    }
+    if (option === "FORMAT" && value && EXPLAIN_FORMATS.has(value))
+        return;
+    if (option === "SERIALIZE" && value && EXPLAIN_SERIALIZE.has(value))
+        return;
+    invalidPostgresSyntax("EXPLAIN");
+}
+const VACUUM_OPTIONS = new Map([
+    ["FULL", "boolean"],
+    ["FREEZE", "boolean"],
+    ["VERBOSE", "boolean"],
+    ["ANALYZE", "boolean"],
+    ["DISABLE_PAGE_SKIPPING", "boolean"],
+    ["SKIP_LOCKED", "boolean"],
+    ["INDEX_CLEANUP", new Set(["AUTO", "ON", "OFF"])],
+    ["PROCESS_MAIN", "boolean"],
+    ["PROCESS_TOAST", "boolean"],
+    ["TRUNCATE", "boolean"],
+    ["PARALLEL", "number"],
+    ["SKIP_DATABASE_STATS", "boolean"],
+    ["ONLY_DATABASE_STATS", "boolean"],
+]);
+const ANALYZE_OPTIONS = new Map([
+    ["VERBOSE", "boolean"],
+    ["SKIP_LOCKED", "boolean"],
+]);
+const REINDEX_OPTIONS = new Map([
+    ["VERBOSE", "boolean"],
+    ["TABLESPACE", "identifier"],
+]);
+const CLUSTER_OPTIONS = new Map([
+    ["VERBOSE", "boolean"],
+]);
+function analyzePostgresMaintenance(sql, command) {
+    const parser = new UtilityParser(tokenizePostgresMaintenance(sql), command);
+    parser.expectWord(command);
+    switch (command) {
+        case "VACUUM":
+            parser.options(VACUUM_OPTIONS, ["FULL", "FREEZE", "VERBOSE", "ANALYZE"]);
+            parser.optionalTargets();
+            break;
+        case "ANALYZE":
+            parser.options(ANALYZE_OPTIONS, ["VERBOSE"]);
+            parser.optionalTargets();
+            break;
+        case "REINDEX": {
+            parser.options(REINDEX_OPTIONS);
+            const target = parser.expectOneOf([
+                "INDEX",
+                "TABLE",
+                "SCHEMA",
+                "DATABASE",
+                "SYSTEM",
+            ]);
+            if (target !== "SYSTEM")
+                parser.consumeWord("CONCURRENTLY");
+            if (target === "INDEX" || target === "TABLE") {
+                parser.qualifiedIdentifier();
+            }
+            else {
+                parser.identifier();
+            }
+            break;
+        }
+        case "CLUSTER":
+            parser.options(CLUSTER_OPTIONS, ["VERBOSE"]);
+            if (!parser.done()) {
+                parser.qualifiedIdentifier();
+                if (parser.consumeWord("USING"))
+                    parser.identifier();
+            }
+            break;
+    }
+    parser.expectDone();
+    return {
+        ast: { type: command.toLowerCase() },
+        normalized: sql.replace(/;\s*$/, ""),
+        statementType: command.toLowerCase(),
+        read: false,
+        unboundedMutation: false,
+        destructive: true,
+        ordered: false,
+        wrapForLimit: false,
+        cacheable: false,
+        requiresAutocommit: true,
+    };
+}
+function tokenizePostgresMaintenance(sql) {
+    const scanner = new PostgresPrefixScanner(sql);
+    const tokens = [];
+    while (scanner.triviaEnd() < sql.length) {
+        const character = sql[scanner.position];
+        if (character === ";") {
+            scanner.position += 1;
+            if (scanner.triviaEnd() !== sql.length) {
+                throw new StateQLError("INVALID_SQL", "Exactly one SQL statement is required.");
+            }
+            break;
+        }
+        const word = scanner.readWord(false);
+        if (word) {
+            tokens.push({ kind: "word", value: word.value });
+            continue;
+        }
+        if (character === '"') {
+            const end = postgresQuotedIdentifierEnd(sql, scanner.position);
+            if (end === undefined)
+                invalidPostgresSyntax("maintenance");
+            tokens.push({ kind: "identifier", value: sql.slice(scanner.position, end) });
+            scanner.position = end;
+            continue;
+        }
+        if (/[0-9]/u.test(character)) {
+            const start = scanner.position;
+            scanner.position += 1;
+            while (/[0-9]/u.test(sql[scanner.position] ?? ""))
+                scanner.position += 1;
+            tokens.push({ kind: "number", value: sql.slice(start, scanner.position) });
+            continue;
+        }
+        if (["(", ")", ",", "."].includes(character)) {
+            tokens.push({ kind: "punctuation", value: character });
+            scanner.position += 1;
+            continue;
+        }
+        invalidPostgresSyntax("maintenance");
+    }
+    return tokens;
+}
+class UtilityParser {
+    tokens;
+    command;
+    index = 0;
+    constructor(tokens, command) {
+        this.tokens = tokens;
+        this.command = command;
+    }
+    done() {
+        return this.index >= this.tokens.length;
+    }
+    expectDone() {
+        if (!this.done())
+            invalidPostgresSyntax(this.command);
+    }
+    expectWord(word) {
+        if (!this.consumeWord(word))
+            invalidPostgresSyntax(this.command);
+    }
+    consumeWord(word) {
+        const token = this.tokens[this.index];
+        if (token?.kind !== "word" || token.value !== word)
+            return false;
+        this.index += 1;
+        return true;
+    }
+    expectOneOf(words) {
+        const token = this.tokens[this.index];
+        if (token?.kind !== "word" || !words.includes(token.value)) {
+            invalidPostgresSyntax(this.command);
+        }
+        this.index += 1;
+        return token.value;
+    }
+    options(options, legacy = []) {
+        if (this.consumePunctuation("(")) {
+            const seen = new Set();
+            while (true) {
+                const option = this.tokens[this.index];
+                if (option?.kind !== "word" || seen.has(option.value)) {
+                    invalidPostgresSyntax(this.command);
+                }
+                const kind = options.get(option.value);
+                if (!kind)
+                    invalidPostgresSyntax(this.command);
+                seen.add(option.value);
+                this.index += 1;
+                const next = this.tokens[this.index];
+                if (next?.value !== "," && next?.value !== ")") {
+                    this.optionValue(kind);
+                }
+                else if (kind !== "boolean") {
+                    invalidPostgresSyntax(this.command);
+                }
+                if (this.consumePunctuation(")"))
+                    return seen;
+                if (!this.consumePunctuation(","))
+                    invalidPostgresSyntax(this.command);
+            }
+        }
+        const seen = new Set();
+        while (true) {
+            const option = this.tokens[this.index];
+            if (option?.kind !== "word" || !legacy.includes(option.value))
+                return seen;
+            if (seen.has(option.value))
+                invalidPostgresSyntax(this.command);
+            seen.add(option.value);
+            this.index += 1;
+        }
+    }
+    optionalTargets() {
+        if (this.done())
+            return;
+        while (true) {
+            this.qualifiedIdentifier();
+            if (this.consumePunctuation("(")) {
+                this.identifier();
+                while (this.consumePunctuation(","))
+                    this.identifier();
+                if (!this.consumePunctuation(")"))
+                    invalidPostgresSyntax(this.command);
+            }
+            if (!this.consumePunctuation(","))
+                return;
+        }
+    }
+    qualifiedIdentifier() {
+        this.identifier();
+        while (this.consumePunctuation("."))
+            this.identifier();
+    }
+    identifier() {
+        const token = this.tokens[this.index];
+        if (token?.kind !== "word" && token?.kind !== "identifier") {
+            invalidPostgresSyntax(this.command);
+        }
+        this.index += 1;
+    }
+    optionValue(kind) {
+        const token = this.tokens[this.index];
+        if (!token)
+            invalidPostgresSyntax(this.command);
+        if (kind === "boolean") {
+            if (token.kind !== "word" || !BOOLEAN_VALUES.has(token.value)) {
+                invalidPostgresSyntax(this.command);
+            }
+        }
+        else if (kind === "number") {
+            if (token.kind !== "number")
+                invalidPostgresSyntax(this.command);
+        }
+        else if (kind === "identifier") {
+            if (token.kind !== "word" && token.kind !== "identifier") {
+                invalidPostgresSyntax(this.command);
+            }
+        }
+        else if (token.kind !== "word" || !kind.has(token.value)) {
+            invalidPostgresSyntax(this.command);
+        }
+        this.index += 1;
+    }
+    consumePunctuation(value) {
+        const token = this.tokens[this.index];
+        if (token?.kind !== "punctuation" || token.value !== value)
+            return false;
+        this.index += 1;
+        return true;
+    }
+}
+class PostgresPrefixScanner {
+    sql;
+    position = 0;
+    constructor(sql) {
+        this.sql = sql;
+    }
+    triviaEnd() {
+        while (this.position < this.sql.length) {
+            if (/\s/u.test(this.sql[this.position])) {
+                this.position += 1;
+            }
+            else if (this.sql.startsWith("--", this.position)) {
+                this.position = lineCommentEnd(this.sql, this.position + 2);
+            }
+            else if (this.sql.startsWith("/*", this.position)) {
+                const end = postgresBlockCommentEnd(this.sql, this.position + 2);
+                if (end === undefined) {
+                    throw new StateQLError("INVALID_SQL", "Unterminated SQL comment.");
+                }
+                this.position = end;
+            }
+            else {
+                break;
+            }
+        }
+        return this.position;
+    }
+    readWord(skipTrivia = true) {
+        if (skipTrivia)
+            this.triviaEnd();
+        const start = this.position;
+        if (!identifierStart(this.sql[start]))
+            return undefined;
+        this.position += 1;
+        while (identifierPart(this.sql[this.position]))
+            this.position += 1;
+        return {
+            value: this.sql.slice(start, this.position).toUpperCase(),
+            start,
+            end: this.position,
+        };
+    }
+    peekWord() {
+        const position = this.position;
+        const value = this.readWord()?.value;
+        this.position = position;
+        return value;
+    }
+    peek() {
+        this.triviaEnd();
+        return this.sql[this.position];
+    }
+    consume(value) {
+        this.triviaEnd();
+        if (!this.sql.startsWith(value, this.position))
+            return false;
+        this.position += value.length;
+        return true;
+    }
+}
+function invalidPostgresSyntax(command) {
+    throw new StateQLError("INVALID_SQL", `Unsupported or invalid PostgreSQL ${command} syntax.`);
+}
+function postgresQuotedIdentifierEnd(sql, start) {
+    let index = start + 1;
+    while (index < sql.length) {
+        if (sql[index] !== '"') {
+            index += 1;
+        }
+        else if (sql[index + 1] === '"') {
+            index += 2;
+        }
+        else {
+            return index + 1;
+        }
+    }
+    return undefined;
+}
+function postgresQuotedStringScanEnd(sql, start) {
+    let index = start + 1;
+    while (index < sql.length) {
+        if (sql[index] === "\\") {
+            index += 2;
+        }
+        else if (sql[index] !== "'") {
+            index += 1;
+        }
+        else if (sql[index + 1] === "'") {
+            index += 2;
+        }
+        else {
+            return index + 1;
+        }
+    }
+    return index;
+}
+function postgresBlockCommentEnd(sql, start) {
+    let depth = 1;
+    let index = start;
+    while (index < sql.length) {
+        if (sql.startsWith("/*", index)) {
+            depth += 1;
+            index += 2;
+        }
+        else if (sql.startsWith("*/", index)) {
+            depth -= 1;
+            index += 2;
+            if (depth === 0)
+                return index;
+        }
+        else {
+            index += 1;
+        }
+    }
+    return undefined;
+}
 function postgresParserSql(sql) {
     const output = sql.split("");
     const orderDepths = new Set();
@@ -97,13 +584,26 @@ function postgresParserSql(sql) {
             continue;
         }
         if (sql.startsWith("/*", index)) {
-            index = blockCommentEnd(sql, index + 2);
+            const end = postgresBlockCommentEnd(sql, index + 2);
+            if (end === undefined) {
+                throw new StateQLError("INVALID_SQL", "Unterminated SQL comment.");
+            }
+            index = end;
             continue;
         }
         const character = sql[index];
-        if (character === "'" || character === '"') {
+        if (character === "'") {
             previousWord = undefined;
-            index = quotedEnd(sql, index + 1, character);
+            index = postgresQuotedStringScanEnd(sql, index);
+            continue;
+        }
+        if (character === '"') {
+            previousWord = undefined;
+            const end = postgresQuotedIdentifierEnd(sql, index);
+            if (end === undefined) {
+                throw new StateQLError("INVALID_SQL", "Unterminated quoted SQL identifier.");
+            }
+            index = end;
             continue;
         }
         if (character === "$") {
@@ -111,7 +611,10 @@ function postgresParserSql(sql) {
             if (delimiter) {
                 previousWord = undefined;
                 const end = sql.indexOf(delimiter, index + delimiter.length);
-                index = end < 0 ? sql.length : end + delimiter.length;
+                if (end < 0) {
+                    throw new StateQLError("INVALID_SQL", "Unterminated dollar-quoted SQL value.");
+                }
+                index = end + delimiter.length;
                 continue;
             }
         }
@@ -205,24 +708,6 @@ function blockCommentEnd(sql, start) {
     }
     return index;
 }
-function quotedEnd(sql, start, quote) {
-    let index = start;
-    while (index < sql.length) {
-        if (sql[index] === "\\" && quote === "'") {
-            index += 2;
-        }
-        else if (sql[index] !== quote) {
-            index += 1;
-        }
-        else if (sql[index + 1] === quote) {
-            index += 2;
-        }
-        else {
-            return index + 1;
-        }
-    }
-    return index;
-}
 function identifierStart(value) {
     return value !== undefined && /[A-Za-z_\u0080-\uFFFF]/u.test(value);
 }
@@ -230,23 +715,35 @@ function identifierPart(value) {
     return value !== undefined && /[A-Za-z0-9_$\u0080-\uFFFF]/u.test(value);
 }
 function selectContainsWrite(ast) {
-    const details = ast;
-    const into = details.into;
-    if (into?.type === "into" || into?.expr)
-        return true;
-    const withStatements = details.with;
-    if (!Array.isArray(withStatements))
-        return false;
-    return withStatements.some((entry) => {
-        if (!entry || typeof entry !== "object")
+    const visited = new Set();
+    const writeTypes = new Set([
+        "insert",
+        "replace",
+        "update",
+        "delete",
+        "create",
+        "alter",
+        "drop",
+        "truncate",
+    ]);
+    const visit = (value) => {
+        if (!value || typeof value !== "object")
             return false;
-        const statement = entry.stmt;
-        if (!statement || typeof statement !== "object")
+        if (visited.has(value))
             return false;
-        const wrapper = statement;
-        const child = (wrapper.ast ?? statement);
-        if (child.type !== "select")
+        visited.add(value);
+        if (Array.isArray(value))
+            return value.some(visit);
+        const details = value;
+        const type = typeof details.type === "string" ? details.type : undefined;
+        if (type && writeTypes.has(type))
             return true;
-        return selectContainsWrite(child);
-    });
+        if (type === "select") {
+            const into = details.into;
+            if (into?.type === "into" || into?.expr)
+                return true;
+        }
+        return Object.values(details).some(visit);
+    };
+    return visit(ast);
 }

package/dist/src/stateql.d.ts

@@ -1,9 +1,11 @@
 import { type TableChange } from "./table-editor.js";
-import type { ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, CommandOrigin, BatchOptions, CapabilitiesData, CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, ProfileUpdateOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, Column, StateQLActorOptions, StateQLOptions, StateQLSnapshot, StateQLSnapshotOptions, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
+import type { ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, CommandOrigin, BatchOptions, CapabilitiesData, CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, ProfileUpdateOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, Column, StateQLActorOptions, StateQLOptions, StateQLWorkspaceOptions, StateQLSnapshot, StateQLSnapshotOptions, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
 export declare class StateQL {
     /** Runtime contract marker for passwordRef/password_ref support. */
     static readonly passwordReferenceVersion: 1;
     static forActor(options: StateQLActorOptions): StateQL;
+    /** Opens one actor in a named shared workspace for a trusted library host. */
+    static forWorkspace(options: StateQLWorkspaceOptions): StateQL;
     private readonly store;
     private readonly sessionName;
     private readonly actorId;

package/dist/src/stateql.js

@@ -17,6 +17,7 @@ import { compactRows, defaultHome, hash, isSqlParameters, parseJson, redact, } f
 const DEFAULT_SNAPSHOT_HISTORY_LIMIT = 50;
 const MAX_SNAPSHOT_HISTORY_LIMIT = 100;
 const DEFAULT_CREDENTIAL_RESOLUTION_TIMEOUT_MS = 120_000;
+const WORKSPACE_BOOTSTRAP = Symbol("StateQL.workspaceBootstrap");
 export class StateQL {
     /** Runtime contract marker for passwordRef/password_ref support. */
     static passwordReferenceVersion = 1;
@@ -37,6 +38,21 @@ export class StateQL {
             store.close();
         }
     }
+    /** Opens one actor in a named shared workspace for a trusted library host. */
+    static forWorkspace(options) {
+        if (!options.workspace.trim()) {
+            throw new StateQLError("INVALID_COMMAND", "Workspace name is required.");
+        }
+        if (!options.actor.trim()) {
+            throw new StateQLError("INVALID_COMMAND", "Actor ID is required.");
+        }
+        const { workspace, ...actorOptions } = options;
+        return new StateQL({
+            ...actorOptions,
+            session: workspace,
+            [WORKSPACE_BOOTSTRAP]: true,
+        });
+    }
     store;
     sessionName;
     actorId;
@@ -80,7 +96,12 @@ export class StateQL {
         }
         const store = new StateStore(options.home ?? defaultHome(), this.now, maxStateBytes);
         try {
-            store.bootstrapSession(this.sessionName, this.actorId, options.actor === undefined);
+            if (options[WORKSPACE_BOOTSTRAP]) {
+                store.bootstrapWorkspace(this.sessionName, this.actorId);
+            }
+            else {
+                store.bootstrapSession(this.sessionName, this.actorId, options.actor === undefined);
+            }
         }
         catch (error) {
             store.close();
@@ -651,6 +672,13 @@ 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 ?? [];
             const context = this.executionContext(options);
             const adapterSource = await this.resolveConnectionSource(connection, session, "query", "read", context);
@@ -668,8 +696,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)) {
@@ -688,7 +716,9 @@ export class StateQL {
                         suggestedAction: "Run with --cache auto or --cache bypass.",
                     });
                 }
-                const result = await adapter.read(boundedReadSql(sql, this.maxResultRows + 1), parameters);
+                const result = await adapter.read(analysis.wrapForLimit
+                    ? boundedReadSql(sql, this.maxResultRows + 1)
+                    : sql, 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." });
                 }
@@ -2179,12 +2209,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", "PostgreSQL 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 ||
@@ -2284,7 +2321,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 PostgreSQL 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({
@@ -3062,6 +3104,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/dist/src/store.d.ts

@@ -132,6 +132,7 @@ export declare class StateStore {
     private insertWithRandomId;
     ensureSession(name?: string): SessionRecord;
     bootstrapSession(name: string, actorId: string, ensureLegacyMembership: boolean): SessionRecord;
+    bootstrapWorkspace(name: string, actorId: string): SessionRecord;
     createSession(name: string): SessionRecord;
     isSessionMember(sessionId: string, actorId: string): boolean;
     linkActor(sessionId: string, requestingActorId: string, actorId: string): "linked" | "already_linked" | "actor_conflict" | "denied";

package/dist/src/store.js

@@ -132,6 +132,56 @@ export class StateStore {
             throw error;
         }
     }
+    bootstrapWorkspace(name, actorId) {
+        const timestamp = this.now().toISOString();
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            let row = this.db
+                .prepare("SELECT id, status FROM sessions WHERE name = ? LIMIT 1")
+                .get(name);
+            const identities = actorId === name ? [actorId] : [name, actorId];
+            for (const identity of identities) {
+                const existing = this.resolveActor(identity);
+                if (existing && existing.id !== row?.id) {
+                    throw new StateQLError("PERMISSION_DENIED", `Actor "${identity}" is already attached to workspace "${existing.name}" and cannot be attached to workspace "${name}".`);
+                }
+            }
+            if (!row) {
+                const id = this.insertWithRandomId("s", "sessions", (candidate) => {
+                    this.db
+                        .prepare(`INSERT INTO sessions
+                (id, name, status, created_at, updated_at)
+               VALUES (?, ?, 'active', ?, ?)`)
+                        .run(candidate, name, timestamp, timestamp);
+                });
+                row = { id, status: "active" };
+            }
+            else if (row.status !== "active") {
+                this.db
+                    .prepare(`UPDATE sessions
+             SET status = 'active', updated_at = ?
+             WHERE id = ?`)
+                    .run(timestamp, row.id);
+            }
+            for (const identity of identities) {
+                if (this.isSessionMember(row.id, identity))
+                    continue;
+                this.db
+                    .prepare(`INSERT INTO session_members(session_id, actor_id, attached_at)
+             VALUES (?, ?, ?)`)
+                    .run(row.id, identity, timestamp);
+            }
+            const session = this.getSessionByName(name);
+            if (!session)
+                throw new Error(`Could not open workspace "${name}".`);
+            this.db.exec("COMMIT");
+            return session;
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
     createSession(name) {
         return this.bootstrapSession(name, name, true);
     }

package/dist/src/types.d.ts

@@ -274,6 +274,10 @@ export interface StateQLOptions extends ExecutionOptions {
 export type StateQLActorOptions = Omit<StateQLOptions, "session" | "actor"> & {
     actor: string;
 };
+/** Trusted-host options for opening one actor in a named shared workspace. */
+export type StateQLWorkspaceOptions = StateQLActorOptions & {
+    workspace: string;
+};
 export interface QueryOptions extends ExecutionOptions {
     params?: SqlParameters;
     cache?: "auto" | "bypass" | "require";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fadhilp/stateql",
-  "version": "0.11.0",
+  "version": "0.12.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": {