@fadhilp/stateql 0.8.1 → 0.9.0

package/dist/src/adapters.d.ts

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

package/dist/src/adapters.js

@@ -96,8 +96,8 @@ class SQLiteAdapter {
     async read(sql, params) {
         return this.call("read", [sql, params], false, false);
     }
-    async write(sql, params) {
-        return this.call("write", [sql, params], true, false);
+    async write(sql, params, expectedRows) {
+        return this.call("write", [sql, params, expectedRows], true, false);
     }
     async writeBatch(operations, isolation) {
         return this.call("writeBatch", [operations, isolation], true, true);
@@ -251,7 +251,7 @@ class PostgresAdapter {
             throw error;
         }
     }
-    async write(sql, params) {
+    async write(sql, params, expectedRows) {
         if (this.readOnly)
             throw new Error("Connection is read-only.");
         try {
@@ -267,6 +267,8 @@ class PostgresAdapter {
         try {
             await this.setLocalDeadline();
             const result = await this.query(sql, postgresParams(params), true);
+            if (expectedRows === 1 && result.rowCount !== 1)
+                throw new Error("ROW_CONFLICT: The row changed or no longer has a unique identity.");
             committing = true;
             await this.query("COMMIT", [], true);
             return { affectedRows: result.rowCount ?? 0 };
@@ -358,6 +360,18 @@ class PostgresAdapter {
         const [schema, name] = table.includes(".")
             ? table.split(".", 2)
             : ["public", table];
+        if (kind === "editable") {
+            await this.setLocalDeadline();
+            const result = await this.query(`SELECT c.column_name AS name, c.data_type AS type, c.is_nullable = 'YES' AS nullable,
+          (c.is_generated = 'ALWAYS' OR c.is_identity = 'YES') AS generated,
+          COALESCE(k.ordinal_position, 0) AS key
+         FROM information_schema.columns c
+         LEFT JOIN information_schema.key_column_usage k ON k.table_schema = c.table_schema AND k.table_name = c.table_name AND k.column_name = c.column_name
+          AND EXISTS (SELECT 1 FROM information_schema.table_constraints t WHERE t.constraint_schema = k.constraint_schema AND t.constraint_name = k.constraint_name AND t.table_name = k.table_name AND t.constraint_type = 'PRIMARY KEY')
+         WHERE c.table_schema = $1 AND c.table_name = $2 ORDER BY c.ordinal_position`, [schema, name], false);
+            const objects = await this.query("SELECT table_type FROM information_schema.tables WHERE table_schema = $1 AND table_name = $2", [schema, name], false);
+            return { writable: objects.rows[0]?.table_type === "BASE TABLE", columns: result.rows.map(column => ({ ...column, key: Number(column.key) })) };
+        }
         await this.setLocalDeadline();
         const columns = await this.query(`SELECT column_name AS name, data_type AS type,
               is_nullable = 'YES' AS nullable
@@ -472,7 +486,7 @@ class MySqlAdapter {
             throw error;
         }
     }
-    async write(sql, params) {
+    async write(sql, params, expectedRows) {
         if (this.readOnly)
             throw new Error("Connection is read-only.");
         let values;
@@ -490,13 +504,22 @@ class MySqlAdapter {
                 throw error;
             throw new AdapterWriteError(errorText(error), false);
         }
+        let committing = false;
         try {
             const [result] = await this.query(sql, values, true, true);
+            if (expectedRows === 1 && mysqlAffectedRows(result) !== 1)
+                throw new Error("ROW_CONFLICT: The row changed or no longer has a unique identity.");
+            committing = true;
             await this.query("COMMIT", [], true, false);
             return { affectedRows: mysqlAffectedRows(result) };
         }
         catch (error) {
-            await this.rollbackQuietly();
+            const rolledBack = await this.rollbackQuietly();
+            if (!committing && rolledBack) {
+                if (error instanceof AdapterExecutionError)
+                    throw new AdapterExecutionError(error.message, error.reason, false);
+                throw new AdapterWriteError(errorText(error), false);
+            }
             if (error instanceof AdapterExecutionError)
                 throw error;
             throw new AdapterWriteError(errorText(error), true);
@@ -584,6 +607,16 @@ class MySqlAdapter {
         const name = separator === -1 ? table : table.slice(separator + 1);
         if (!schema || !name)
             throw new Error(`Invalid table name "${table}".`);
+        if (kind === "editable") {
+            const [result] = await this.query(`SELECT c.COLUMN_NAME AS name, c.DATA_TYPE AS type, c.IS_NULLABLE = 'YES' AS nullable,
+          c.EXTRA LIKE '%GENERATED%' AS \`generated\`, COALESCE(k.ORDINAL_POSITION, 0) AS \`key\`
+         FROM information_schema.columns c LEFT JOIN information_schema.key_column_usage k
+          ON k.TABLE_SCHEMA = c.TABLE_SCHEMA AND k.TABLE_NAME = c.TABLE_NAME AND k.COLUMN_NAME = c.COLUMN_NAME AND k.CONSTRAINT_NAME = 'PRIMARY'
+         WHERE c.TABLE_SCHEMA = ? AND c.TABLE_NAME = ? ORDER BY c.ORDINAL_POSITION`, [schema, name], false, true);
+            const [objects] = await this.query("SELECT ENGINE AS engine FROM information_schema.tables WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?", [schema, name], false, true);
+            return { writable: String(mysqlRows(objects)[0]?.engine).toLowerCase() === "innodb",
+                columns: mysqlRows(result).map(column => ({ ...column, nullable: Boolean(column.nullable), generated: Boolean(column.generated), key: Number(column.key) })) };
+        }
         const [columnResult] = await this.query(`SELECT COLUMN_NAME AS name, DATA_TYPE AS type,
               IS_NULLABLE = 'YES' AS nullable
        FROM information_schema.columns

package/dist/src/migrations.js

@@ -80,6 +80,11 @@ const MIGRATIONS = [
         apply: migrateCredentialRefs,
         validate: validateCredentialRefs,
     },
+    {
+        name: "history_target_v1",
+        apply(db) { addColumn(db, "history", "target", "TEXT"); },
+        validate(db) { requireColumns(db, "history", ["target"]); },
+    },
 ];
 export function runMigrations(db, now) {
     db.exec(`

package/dist/src/mongodb.d.ts

@@ -34,7 +34,7 @@ export declare class MongoAdapter {
     ping(): Promise<void>;
     signature(): Promise<string>;
     read(command: MongoReadCommand, maxRows: number): Promise<MongoReadResult>;
-    write(command: MongoWriteCommand): Promise<MongoWriteResult>;
+    write(command: MongoWriteCommand, expectedRows?: 1): Promise<MongoWriteResult>;
     writeBatch(commands: MongoWriteCommand[], isolation: string): Promise<MongoWriteResult[]>;
     inspect(kind: string, name?: string): Promise<unknown>;
     close(): Promise<void>;

package/dist/src/mongodb.js

@@ -221,7 +221,7 @@ export class MongoAdapter {
             await cursor?.close().catch(() => undefined);
         }
     }
-    async write(command) {
+    async write(command, expectedRows) {
         let value;
         try {
             value = validateMongoWriteCommand(command);
@@ -240,10 +240,17 @@ export class MongoAdapter {
                 throw error;
             throw new AdapterWriteError(errorText(error), false);
         }
+        if (expectedRows === 1 && (value.operation !== "updateOne" || value.options?.upsert))
+            throw new AdapterWriteError("Conditional edits require updateOne without upsert.", false);
         try {
-            return await withContext(this.executeWrite(value), this.context, () => this.stop(), true);
+            const result = await withContext(this.executeWrite(value), this.context, () => this.stop(), true);
+            if (expectedRows === 1 && result.outcome.matched_count !== 1)
+                throw new AdapterWriteError("ROW_CONFLICT: The document changed or was removed.", false);
+            return result;
         }
         catch (error) {
+            if (error instanceof AdapterWriteError)
+                throw error;
             const stopped = writeStoppedError(error, this.context, true);
             if (stopped)
                 throw stopped;
@@ -342,6 +349,10 @@ export class MongoAdapter {
             if (kind === "constraints") {
                 return { collection: collectionName, constraints: [] };
             }
+            if (kind === "editable") {
+                const objects = await this.client.db(this.databaseName).listCollections({ name: collectionName }, { nameOnly: true, signal: operationSignal(this.context), maxTimeMS: remainingMilliseconds(this.context) }).toArray();
+                return { writable: objects[0]?.type === "collection", columns: [] };
+            }
             const columns = await this.sampleColumns(collectionName);
             if (kind === "columns")
                 return { collection: collectionName, columns };

package/dist/src/sqlite-process.js

@@ -57,7 +57,7 @@ function execute(request) {
         case "write": {
             if (readOnly)
                 throw new Error("Connection is read-only.");
-            const [sql, params] = request.args;
+            const [sql, params, expectedRows] = request.args;
             try {
                 database.exec("BEGIN");
             }
@@ -66,6 +66,8 @@ function execute(request) {
             }
             try {
                 const result = bindRun(database.prepare(sql), params);
+                if (expectedRows === 1 && Number(result.changes) !== 1)
+                    throw new Error("ROW_CONFLICT: The row changed or no longer has a unique identity.");
                 database.exec("COMMIT");
                 return { affectedRows: Number(result.changes) };
             }
@@ -160,6 +162,11 @@ function inspect(database, kind, table) {
     if (!table)
         throw new Error(`Table is required for inspect ${kind}.`);
     const quoted = quoteSqliteLiteral(table);
+    if (kind === "editable") {
+        const object = database.prepare("SELECT type FROM sqlite_master WHERE name = ?").get(table);
+        const columns = database.prepare(`PRAGMA table_xinfo(${quoted})`).all();
+        return { writable: object?.type === "table", columns: columns.map(column => ({ name: String(column.name), type: String(column.type).toLowerCase(), nullable: !column.notnull && !column.pk, generated: Number(column.hidden) !== 0, key: Number(column.pk) })) };
+    }
     const columns = database
         .prepare(`PRAGMA table_info(${quoted})`)
         .all();

package/dist/src/stateql.d.ts

@@ -1,4 +1,5 @@
-import type { ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, BatchOptions, CapabilitiesData, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, StateQLActorOptions, StateQLOptions, StateQLSnapshot, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
+import { type TableChange } from "./table-editor.js";
+import type { ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, CommandOrigin, BatchOptions, CapabilitiesData, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, Column, StateQLActorOptions, StateQLOptions, StateQLSnapshot, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
 export declare class StateQL {
     static forActor(options: StateQLActorOptions): StateQL;
     private readonly store;
@@ -17,6 +18,9 @@ export declare class StateQL {
     private readonly credentialResolver?;
     private readonly now;
     private closed;
+    private readonly tableResults;
+    private readonly editTokens;
+    private panelRows?;
     constructor(options?: StateQLOptions);
     close(): void;
     [Symbol.dispose](): void;
@@ -47,6 +51,40 @@ export declare class StateQL {
     count(idOrAlias: string): Promise<Response<CountData>>;
     columns(idOrAlias: string): Promise<Response<ColumnsData>>;
     setAlias(name: string, id: string): Promise<Response<AliasData>>;
+    /** Owned, full-value pages for host UIs. Reading a page does not add a command to history. */
+    readMaterialized(id: string, options?: RowsOptions & {
+        signal?: AbortSignal;
+    }): RowsData & {
+        columns: Column[];
+        row_tokens: Array<string | null>;
+        writable_columns: string[];
+        editing_reason?: string;
+    };
+    /** No caller-selected filesystem paths. The host delivers these bounded attachment bytes. */
+    serializeResult(id: string, format: "json" | "jsonl" | "csv", signal?: AbortSignal, origin?: CommandOrigin): Promise<Response<{
+        content: string;
+        format: string;
+        rows: number;
+    }>>;
+    readTable(table: {
+        schema?: string;
+        name: string;
+    }, limit?: number, options?: QueryOptions & {
+        origin?: CommandOrigin;
+    }): Promise<Response<ResultData & {
+        table: {
+            schema?: string;
+            name: string;
+        };
+        sample_limit: number;
+        query: string;
+    }>>;
+    planTableUpdate(token: string, changes: TableChange, options?: ExecutionOptions & {
+        origin?: CommandOrigin;
+    }): Promise<Response<PlanData>>;
+    private editableMetadata;
+    private panelResult;
+    private fullResultRows;
     exportResult(idOrAlias: string, output: string, format?: "json" | "jsonl" | "csv"): Promise<Response<ExportData>>;
     exec(sql: string, options?: ExecOptions): Promise<Response<ExecData>>;
     mongoExec(command: MongoWriteCommand, options?: MongoExecOptions): Promise<Response<ExecData>>;

package/dist/src/stateql.js

@@ -1,4 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { compileTableUpdate, editableRow, parseTableUpdate } from "./table-editor.js";
 import { writeFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { env } from "node:process";
@@ -48,6 +50,10 @@ export class StateQL {
     credentialResolver;
     now;
     closed = false;
+    tableResults = new Map();
+    editTokens = new Map();
+    // ponytail: cache one bounded immutable result; use indexed result storage if larger results are needed.
+    panelRows;
     constructor(options = {}) {
         this.now = options.now ?? (() => new Date());
         this.sessionName = options.session ?? env.STQL_SESSION ?? "default";
@@ -83,6 +89,9 @@ export class StateQL {
         if (this.closed)
             return;
         this.closed = true;
+        this.panelRows = undefined;
+        this.tableResults.clear();
+        this.editTokens.clear();
         this.store.close();
     }
     [Symbol.dispose]() {
@@ -855,6 +864,193 @@ export class StateQL {
             };
         });
     }
+    /** Owned, full-value pages for host UIs. Reading a page does not add a command to history. */
+    readMaterialized(id, options = {}) {
+        options.signal?.throwIfAborted();
+        const result = this.panelResult(id);
+        const offset = nonNegativeInteger(options.offset ?? 0, "offset");
+        const limit = positiveInteger(options.limit ?? 100, "limit");
+        if (limit > 100 || offset > 10_000)
+            throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", "Page bounds exceeded.");
+        const all = this.fullResultRows(result);
+        const rows = [];
+        let bytes = 0;
+        for (const row of all.slice(offset, offset + limit)) {
+            const size = Buffer.byteLength(JSON.stringify(row), "utf8");
+            if (bytes + size > 200 * 1024) {
+                if (!rows.length)
+                    throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", "A row exceeds the browser page limit. Export this result instead.");
+                break;
+            }
+            rows.push(row);
+            bytes += size;
+        }
+        const next = offset + rows.length;
+        const metadata = this.tableResults.get(id);
+        const connection = this.store.activeConnection(this.store.ensureSession(this.sessionName));
+        const eligible = metadata && connection?.id === result.connection_id && !connection.read_only && version(connection) === result.state_version;
+        const rowTokens = rows.map(row => {
+            if (!eligible || !editableRow(metadata, row))
+                return null;
+            const token = randomUUID();
+            for (const [key, entry] of this.editTokens)
+                if (entry.expires <= this.now().getTime())
+                    this.editTokens.delete(key);
+            if (this.editTokens.size >= 1000)
+                this.editTokens.delete(this.editTokens.keys().next().value);
+            this.editTokens.set(token, { metadata, original: structuredClone(row), sessionId: result.session_id, connectionId: result.connection_id, stateVersion: result.state_version, expires: this.now().getTime() + 10 * 60_000 });
+            return token;
+        });
+        const writable = metadata?.driver === "mongodb" ? [...new Set(rows.flatMap(row => Object.keys(row)))].filter(name => name !== "_id")
+            : metadata?.columns.filter(column => !column.key && !column.generated).map(column => column.name) ?? [];
+        return { row_tokens: rowTokens, writable_columns: writable, ...(!metadata?.writable ? { editing_reason: metadata?.reason ?? "Query results are read-only." } : {}),
+            result_id: result.id, offset, limit, rows: structuredClone(rows), columns: this.store.resultColumns(result),
+            returned: rows.length, total: all.length, truncated: next < all.length, next_offset: next < all.length ? next : null };
+    }
+    /** No caller-selected filesystem paths. The host delivers these bounded attachment bytes. */
+    async serializeResult(id, format, signal, origin = "api") {
+        return this.commandContexts.run(mergeCommandExecutionContext(this.commandContexts.getStore(), { signal, origin }), () => this.run("export", async () => {
+            if (!["json", "jsonl", "csv"].includes(format))
+                throw new StateQLError("INVALID_COMMAND", "Unsupported export format.");
+            const result = this.panelResult(id);
+            const rows = this.fullResultRows(result);
+            const columns = this.store.resultColumns(result).map(column => column.name);
+            const chunks = [];
+            let bytes = 0;
+            const append = (chunk) => {
+                bytes += Buffer.byteLength(chunk, "utf8");
+                if (bytes > 32 * 1024 * 1024)
+                    throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", "Export exceeds 32 MiB.");
+                chunks.push(chunk);
+            };
+            const csvCell = (value) => {
+                let valueText = value === null || value === undefined ? "" : typeof value === "object" ? JSON.stringify(value) : String(value);
+                if (typeof value !== "number" && /^[\s\u0000-\u001f]*[=+@-]|^[\t\r\n]/u.test(valueText))
+                    valueText = "'" + valueText;
+                return /[",\r\n]/u.test(valueText) ? '"' + valueText.replaceAll('"', '""') + '"' : valueText;
+            };
+            if (format === "json")
+                append("[");
+            if (format === "csv")
+                append(columns.map(csvCell).join(",") + "\n");
+            const deadline = Date.now() + 30_000;
+            for (let index = 0; index < rows.length; index++) {
+                if (index % 100 === 0) {
+                    await new Promise(resolve => setImmediate(resolve));
+                    signal?.throwIfAborted();
+                    this.signal?.throwIfAborted();
+                    if (Date.now() > deadline)
+                        throw new StateQLError("DEADLINE_EXCEEDED", "Export preparation timed out.");
+                }
+                const row = rows[index];
+                append(format === "csv" ? columns.map(column => csvCell(row[column])).join(",") + "\n"
+                    : (format === "json" && index ? "," : "") + JSON.stringify(row) + (format === "jsonl" ? "\n" : ""));
+            }
+            signal?.throwIfAborted();
+            if (format === "json")
+                append("]\n");
+            this.panelResult(id);
+            return { data: { content: chunks.join(""), format, rows: rows.length }, handle: id };
+        }));
+    }
+    async readTable(table, limit = 1000, options = {}) {
+        return this.commandContexts.run(mergeCommandExecutionContext(this.commandContexts.getStore(), { signal: options.signal, origin: options.origin ?? "api" }), async () => {
+            if (!table || typeof table.name !== "string" || !table.name || table.name.length > 500 || table.name.includes("\0") ||
+                (table.schema !== undefined && (typeof table.schema !== "string" || !table.schema || table.schema.length > 500 || table.schema.includes("\0"))) ||
+                !Number.isSafeInteger(limit) || limit < 1 || limit > 10_000)
+                throw new StateQLError("INVALID_COMMAND", "Invalid table or sample limit.");
+            const snapshot = this.snapshot({ historyLimit: 1 });
+            const driver = snapshot.connection?.driver;
+            if (!driver)
+                throw new StateQLError("CONNECTION_NOT_FOUND", "Connect to a database first.");
+            if (driver === "sqlite" && table.schema && table.schema !== "main")
+                throw new StateQLError("INVALID_COMMAND", "Only the main SQLite schema is supported.");
+            if (driver === "mongodb" && table.schema)
+                throw new StateQLError("INVALID_COMMAND", "MongoDB collections do not accept a schema.");
+            const quote = (name) => driver === "mysql" ? "\`" + name.replaceAll("\`", "\`\`") + "\`" : '"' + name.replaceAll('"', '""') + '"';
+            const qualified = [table.schema, table.name].filter((part) => Boolean(part)).map(quote).join(".");
+            const query = driver === "mongodb" ? JSON.stringify({ operation: "find", collection: table.name, options: { limit } }, null, 2)
+                : "SELECT * FROM " + qualified + " LIMIT " + limit;
+            const metadata = await this.editableMetadata(table, options);
+            const response = driver === "mongodb"
+                ? await this.mongoQuery({ operation: "find", collection: table.name, options: { limit } }, options)
+                : await this.query(query, options);
+            if (!response.ok)
+                return response;
+            if (this.tableResults.size >= 20)
+                this.tableResults.delete(this.tableResults.keys().next().value);
+            this.tableResults.set(response.data.result_id, metadata);
+            return { ...response, data: { ...response.data, table, sample_limit: limit, query } };
+        });
+    }
+    async planTableUpdate(token, changes, options = {}) {
+        return this.commandContexts.run(mergeCommandExecutionContext(this.commandContexts.getStore(), { signal: options.signal, origin: options.origin ?? "api" }), () => this.run("table.plan", async (session) => {
+            this.rejectDuringStagedTransaction(session, "Table edits");
+            const connection = this.requireConnection(session);
+            const original = this.editTokens.get(token);
+            if (!original || original.sessionId !== session.id || original.connectionId !== connection.id ||
+                original.stateVersion !== version(connection) || original.expires <= this.now().getTime())
+                throw new StateQLError("STALE_PLAN", "Row identity expired or the connection changed. Reload the row.");
+            if (connection.read_only)
+                throw new StateQLError("READ_ONLY_CONNECTION", "This connection is read-only.");
+            const metadata = await this.editableMetadata(original.metadata.table, options);
+            if (JSON.stringify(metadata) !== JSON.stringify(original.metadata))
+                throw new StateQLError("STALE_PLAN", "Table metadata changed. Reload the table.");
+            const update = { metadata, original: original.original, changes };
+            const compiled = compileTableUpdate(update);
+            const context = this.executionContext(options);
+            const source = await this.resolveConnectionSource(connection, session, "plan", "read", context);
+            const adapter = connection.driver === "mongodb" ? await this.openMongoAdapter(connection, context, source) : await this.openAdapter(connection, context, source);
+            try {
+                const plan = this.store.savePlan({ sessionId: session.id, ownerActorId: this.actorId, connectionId: connection.id,
+                    sql: compiled.sql, parameters: [JSON.stringify(update)], statementType: "table.update", stateVersion: version(connection),
+                    stateSignature: await adapter.signature(), destructive: false, allowUnbounded: false, allowDestructive: false,
+                    expiresAt: new Date(original.expires).toISOString() });
+                return { data: { plan_id: plan.id, statement_type: plan.statement_type, destructive: false, requires_confirmation: true, required_overrides: [],
+                        state_version: plan.state_version, owner_actor_id: this.actorId, expires_at: plan.expires_at }, handle: plan.id };
+            }
+            finally {
+                await closeAdapterQuietly(adapter);
+            }
+        }));
+    }
+    async editableMetadata(table, options) {
+        const snapshot = this.snapshot({ historyLimit: 1 });
+        const driver = snapshot.connection.driver;
+        const unavailable = { table, driver, columns: [], writable: false, reason: "This table or its values cannot be edited safely." };
+        // The legacy inspection API splits qualified names. Fail closed for ambiguous names.
+        if (table.name.includes(".") || table.schema?.includes("."))
+            return { ...unavailable, reason: "Editing identifiers containing dots is not supported." };
+        const name = driver === "sqlite" || driver === "mongodb" ? table.name : [table.schema, table.name].filter(Boolean).join(".");
+        const response = await this.inspect("editable", name, options);
+        if (!response.ok)
+            return { ...unavailable, reason: response.error.code };
+        const value = response.data;
+        if (!value || !Array.isArray(value.columns) || value.columns.length > 100)
+            return unavailable;
+        return { table, driver, columns: value.columns, writable: value.writable === true && !snapshot.connection.read_only,
+            ...(value.writable ? {} : { reason: "Only ordinary tables with transactional writes and a primary key can be edited." }) };
+    }
+    panelResult(id) {
+        if (typeof id !== "string" || !id || id.length > 200)
+            throw new StateQLError("INVALID_COMMAND", "A result ID is required.");
+        const session = this.store.ensureSession(this.sessionName);
+        if (!this.store.isSessionMember(session.id, this.actorId))
+            this.throwMembershipDenied(session);
+        const result = this.requireResult(id, session);
+        if (result.id !== id)
+            throw new StateQLError("INVALID_COMMAND", "Use an immutable result ID, not an alias.");
+        if (Date.parse(result.expires_at) <= this.now().getTime())
+            throw new StateQLError("RESULT_EXPIRED", "Result expired. Run the query again.");
+        if (result.row_count > 10_000 || Buffer.byteLength(result.rows_json, "utf8") > 16 * 1024 * 1024)
+            throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", "Stored result exceeds browser limits.");
+        return result;
+    }
+    fullResultRows(result) {
+        if (this.panelRows?.id !== result.id || this.panelRows.json !== result.rows_json)
+            this.panelRows = { id: result.id, json: result.rows_json, rows: this.store.resultRows(result) };
+        return this.panelRows.rows;
+    }
     async exportResult(idOrAlias, output, format = "csv") {
         return this.withResult("export", idOrAlias, async (result) => {
             const rows = this.store.resultRows(result);
@@ -1104,7 +1300,7 @@ export class StateQL {
             finally {
                 await closeAdapterQuietly(adapter);
             }
-        });
+        }, undefined, table);
     }
     async plan(sql, options = {}) {
         return this.run("plan", async (session) => {
@@ -1257,14 +1453,18 @@ export class StateQL {
             if (Date.parse(plan.expires_at) <= this.now().getTime()) {
                 throw new StateQLError("STALE_PLAN", "Plan has expired.");
             }
-            const nativePlan = plan.statement_type.startsWith("mongo.");
+            const tableUpdate = plan.statement_type === "table.update" ? parseTableUpdate(plan.parameters) : undefined;
+            const compiled = tableUpdate ? compileTableUpdate(tableUpdate) : undefined;
+            if (compiled && compiled.sql !== plan.sql)
+                throw new StateQLError("STALE_PLAN", "Stored update does not match its plan.");
+            const nativePlan = tableUpdate?.metadata.driver === "mongodb" || plan.statement_type.startsWith("mongo.");
             historySql = nativePlan ? undefined : plan.sql;
-            const mongoCommand = nativePlan
+            const mongoCommand = compiled?.mongo ?? (nativePlan
                 ? storedMongoPlan(plan.parameters, plan.statement_type, plan.id)
-                : undefined;
-            const planParameters = nativePlan
+                : undefined);
+            const planParameters = compiled?.params ?? (nativePlan
                 ? undefined
-                : parseJson(plan.parameters, `plan "${plan.id}" parameters`, isSqlParameters);
+                : 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) {
@@ -1283,6 +1483,8 @@ export class StateQL {
                 if (!nativePlan && connection.driver === "mongodb") {
                     this.rejectMongoSql(connection, "mongoPlan");
                 }
+                if (tableUpdate && JSON.stringify(await this.editableMetadata(tableUpdate.metadata.table, options)) !== JSON.stringify(tableUpdate.metadata))
+                    throw new StateQLError("STALE_PLAN", "Table metadata changed. Reload and plan again.");
                 const context = this.executionContext(options);
                 const adapterSource = await this.resolveConnectionSource(connection, session, "apply", "write", context);
                 const adapter = nativePlan
@@ -1308,9 +1510,11 @@ export class StateQL {
                     ? await this.performMongoExec(session, connection, mongoCommand, {
                         allowUnbounded: Boolean(claimed.allow_unbounded),
                         allowDestructive: Boolean(claimed.allow_destructive),
+                        ...(tableUpdate ? { expectedRows: 1 } : {}),
                     }, context, { planId: claimed.id, claimToken }, adapterSource)
                     : await this.performExec(session, connection, claimed.sql, {
                         params: planParameters,
+                        ...(tableUpdate ? { expectedRows: 1 } : {}),
                         allowUnbounded: Boolean(claimed.allow_unbounded),
                         allowDestructive: Boolean(claimed.allow_destructive),
                     }, context, { planId: claimed.id, claimToken }, adapterSource);
@@ -1716,7 +1920,7 @@ export class StateQL {
             });
         }
         try {
-            const write = await adapter.write(sql, parameters);
+            const write = await adapter.write(sql, parameters, options.expectedRows);
             try {
                 const finalized = planClaim
                     ? this.store.finishPlannedOperation({
@@ -1764,6 +1968,8 @@ export class StateQL {
             }
             if (error instanceof AdapterWriteError && !error.outcomeUnknown) {
                 this.store.failOperation(operation.id);
+                if (error.message.startsWith("ROW_CONFLICT:"))
+                    throw new StateQLError("ROW_CONFLICT", "The row changed or no longer matches. Reload before editing.");
                 throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { executed: true });
             }
             this.store.markOperationOutcomeUnknown(operation.id);
@@ -1906,7 +2112,7 @@ export class StateQL {
             });
         }
         try {
-            const write = await adapter.write(value);
+            const write = await adapter.write(value, options.expectedRows);
             try {
                 const finalized = planClaim
                     ? this.store.finishPlannedOperation({
@@ -1955,6 +2161,8 @@ export class StateQL {
             }
             if (error instanceof AdapterWriteError && !error.outcomeUnknown) {
                 this.store.failOperation(operation.id);
+                if (error.message.startsWith("ROW_CONFLICT:"))
+                    throw new StateQLError("ROW_CONFLICT", "The document changed or was removed. Reload before editing.");
                 throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { executed: true });
             }
             this.store.markOperationOutcomeUnknown(operation.id);
@@ -2155,7 +2363,7 @@ export class StateQL {
             result.state_version === stateVersion &&
             result.state_signature === stateSignature);
     }
-    async run(command, action, historySql) {
+    async run(command, action, historySql, historyTarget) {
         const started = performance.now();
         const origin = this.commandContexts.getStore()?.origin ?? "legacy";
         let session = this.store.ensureSession(this.sessionName);
@@ -2182,6 +2390,7 @@ export class StateQL {
                 actorId: this.actorId,
                 origin,
                 command,
+                target: historyTarget,
                 ...(result.handle ? { handle: result.handle } : {}),
                 ...(sqlText !== undefined ? { sql: sqlText } : {}),
                 executed: result.executed ?? false,
@@ -2214,6 +2423,7 @@ export class StateQL {
                 actorId: this.actorId,
                 origin,
                 command,
+                target: historyTarget,
                 ...(sqlText !== undefined ? { sql: sqlText } : {}),
                 executed: stateqlError.details.executed,
                 cached: false,
@@ -2244,6 +2454,7 @@ function historyEntry(item) {
         origin: item.origin,
         command: item.command,
         sql: item.sql,
+        ...(item.target ? { target: item.target } : {}),
         handle: item.handle,
         executed: Boolean(item.executed),
         cached: Boolean(item.cached),

package/dist/src/store.d.ts

@@ -103,6 +103,7 @@ export interface HistoryRecord {
     origin: CommandOrigin;
     command: string;
     sql: string | null;
+    target: string | null;
     handle: string | null;
     executed: number;
     cached: number;
@@ -278,6 +279,7 @@ export declare class StateStore {
         origin?: CommandOrigin;
         command: string;
         sql?: string;
+        target?: string;
         handle?: string;
         executed: boolean;
         cached: boolean;

package/dist/src/store.js

@@ -797,10 +797,10 @@ export class StateStore {
         const id = input.id ?? this.nextId("cmd");
         this.db
             .prepare(`INSERT INTO history
-          (id, timestamp, session_id, actor_id, origin, command, sql, handle,
+          (id, timestamp, session_id, actor_id, origin, command, sql, target, handle,
            executed, cached, success, error_code)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-            .run(id, this.now().toISOString(), input.sessionId, input.actorId, input.origin ?? "legacy", input.command, boundedHistorySql(input.sql), 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.origin ?? "legacy", input.command, boundedHistorySql(input.sql), input.target?.slice(0, 1024) ?? null, 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 (

package/dist/src/table-editor.d.ts

@@ -0,0 +1,36 @@
+import type { Driver, MongoWriteCommand, Row, SqlParameters } from "./types.js";
+export interface TableIdentity {
+    schema?: string;
+    name: string;
+}
+export interface EditableColumn {
+    name: string;
+    type: string;
+    nullable: boolean;
+    generated: boolean;
+    key: number;
+}
+export interface EditableTable {
+    table: TableIdentity;
+    driver: Driver;
+    columns: EditableColumn[];
+    writable: boolean;
+    reason?: string;
+}
+export interface TableChange {
+    set?: Record<string, unknown>;
+    unset?: string[];
+}
+export interface TableUpdate {
+    metadata: EditableTable;
+    original: Row;
+    changes: TableChange;
+}
+export declare function quoteIdentifier(name: string, driver: Driver): string;
+export declare function editableRow(metadata: EditableTable, row: Row): boolean;
+export declare function compileTableUpdate(update: TableUpdate): {
+    sql: string;
+    params: SqlParameters;
+    mongo?: MongoWriteCommand;
+};
+export declare function parseTableUpdate(parameters: string): TableUpdate;

package/dist/src/table-editor.js

@@ -0,0 +1,115 @@
+import { BSON } from "mongodb";
+import { StateQLError } from "./errors.js";
+export function quoteIdentifier(name, driver) {
+    if (!name || name.length > 500 || name.includes("\0"))
+        throw new StateQLError("INVALID_COMMAND", "Invalid database identifier.");
+    return driver === "mysql" ? "`" + name.replaceAll("`", "``") + "`" : '"' + name.replaceAll('"', '""') + '"';
+}
+function comparable(value, column) {
+    if (value === null)
+        return column.nullable;
+    const type = column.type.toLowerCase();
+    if (/^(?:tinyint|smallint|mediumint|int|integer|bigint|int2|int4|int8)(?:\b|$)/u.test(type))
+        return typeof value === "number" ? Number.isSafeInteger(value) : typeof value === "string" && /^-?\d+$/u.test(value);
+    if (/^(?:numeric|decimal)(?:\b|$)/u.test(type))
+        return typeof value === "string" && /^-?\d+(?:\.\d+)?$/u.test(value);
+    if (/^(?:boolean|bool)$/u.test(type))
+        return typeof value === "boolean";
+    if (/^(?:text|varchar|character varying|nvarchar|ntext|longtext|mediumtext|tinytext)(?:\b|$)/u.test(type))
+        return typeof value === "string" && value.length <= 16_384;
+    return false;
+}
+function mongoScalarType(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "string")
+        return "string";
+    if (typeof value === "boolean")
+        return "bool";
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).length !== 1)
+        return undefined;
+    const types = { $oid: "objectId", $numberInt: "int", $numberLong: "long", $numberDecimal: "decimal", $date: "date" };
+    return types[Object.keys(value)[0]];
+}
+export function editableRow(metadata, row) {
+    if (!metadata.writable || Buffer.byteLength(JSON.stringify(row), "utf8") > 32 * 1024)
+        return false;
+    if (metadata.driver === "mongodb")
+        return Object.hasOwn(row, "_id") && Object.entries(row).every(([key, value]) => !key.startsWith("$") && !key.includes(".") && mongoScalarType(value) !== undefined);
+    const keys = metadata.columns.filter(column => column.key > 0);
+    return keys.length > 0 && keys.every(column => row[column.name] !== null && row[column.name] !== undefined) &&
+        metadata.columns.length === Object.keys(row).length && metadata.columns.every(column => Object.hasOwn(row, column.name) && comparable(row[column.name], column));
+}
+export function compileTableUpdate(update) {
+    const { metadata, original, changes } = update;
+    if (!editableRow(metadata, original))
+        throw new StateQLError("INVALID_COMMAND", "This row has no safe editable identity or comparison types.");
+    const entries = Object.entries(changes.set ?? {});
+    const unset = changes.unset ?? [];
+    if ((!entries.length && !unset.length) || entries.length + unset.length > 100 || Buffer.byteLength(JSON.stringify(changes), "utf8") > 32 * 1024)
+        throw new StateQLError("INVALID_COMMAND", "Provide bounded changed cells.");
+    if (metadata.driver === "mongodb") {
+        for (const name of [...entries.map(([name]) => name), ...unset]) {
+            if (name === "_id" || !Object.hasOwn(original, name) || name.startsWith("$") || name.includes("."))
+                throw new StateQLError("INVALID_COMMAND", "Only existing non-key fields can be changed.");
+        }
+        const document = BSON.EJSON.deserialize(original, { relaxed: false });
+        const mongo = {
+            operation: "updateOne", collection: metadata.table.name,
+            filter: { _id: document._id, $expr: { $and: [
+                        { $eq: ["$$ROOT", { $literal: document }] },
+                        ...Object.entries(original).map(([name, value]) => ({ $eq: [{ $type: "$" + name }, mongoScalarType(value)] })),
+                    ] } },
+            update: { ...(entries.length ? { $set: BSON.EJSON.deserialize(Object.fromEntries(entries), { relaxed: false }) } : {}), ...(unset.length ? { $unset: Object.fromEntries(unset.map(name => [name, ""])) } : {}) },
+            options: { upsert: false, collation: { locale: "simple" } },
+        };
+        return { sql: "MongoDB conditional row update", params: [], mongo };
+    }
+    if (unset.length)
+        throw new StateQLError("INVALID_COMMAND", "SQL columns cannot be unset; use null where allowed.");
+    const driver = metadata.driver;
+    const quote = (name) => quoteIdentifier(name, driver);
+    const params = [];
+    const parameter = (value) => { params.push(value); return driver === "postgres" ? "$" + params.length : "?"; };
+    const assignments = entries.map(([name, value]) => {
+        const column = metadata.columns.find(column => column.name === name);
+        if (!column || column.key || column.generated || !comparable(value, column))
+            throw new StateQLError("INVALID_COMMAND", "A changed column is generated, a key, or has an unsupported value.");
+        return quote(name) + " = " + parameter(value);
+    });
+    const predicates = metadata.columns.map(column => {
+        const name = quote(column.name);
+        if (original[column.name] === null)
+            return name + " IS NULL";
+        const placeholder = parameter(original[column.name]);
+        const isText = /text|varchar|character varying/u.test(column.type.toLowerCase());
+        if (driver === "postgres") {
+            const left = isText ? "convert_to(" + name + ", 'UTF8')" : name;
+            const right = isText ? "convert_to(" + placeholder + ", 'UTF8')" : placeholder;
+            return left + " = " + right;
+        }
+        if (driver === "mysql")
+            return isText ? "CAST(" + name + " AS BINARY) = CAST(" + placeholder + " AS BINARY)" : name + " = " + placeholder;
+        return isText ? "CAST(" + name + " AS BLOB) IS CAST(" + placeholder + " AS BLOB)" : name + " IS " + placeholder;
+    });
+    const table = [metadata.table.schema, metadata.table.name].filter((name) => Boolean(name)).map(quote).join(".");
+    return { sql: "UPDATE " + table + " SET " + assignments.join(", ") + " WHERE " + predicates.join(" AND "), params };
+}
+export function parseTableUpdate(parameters) {
+    try {
+        const outer = JSON.parse(parameters);
+        if (!Array.isArray(outer) || outer.length !== 1 || typeof outer[0] !== "string" || outer[0].length > 128 * 1024)
+            throw new Error();
+        const update = JSON.parse(outer[0]);
+        if (!update || !update.metadata || !["sqlite", "postgres", "mysql", "mongodb"].includes(update.metadata.driver) ||
+            !Array.isArray(update.metadata.columns) || update.metadata.columns.length > 100 ||
+            !update.metadata.columns.every(column => typeof column.name === "string" && typeof column.type === "string" && typeof column.nullable === "boolean" && typeof column.generated === "boolean" && Number.isSafeInteger(column.key)) ||
+            !update.original || !update.changes || typeof update.changes !== "object")
+            throw new Error();
+        compileTableUpdate(update);
+        return update;
+    }
+    catch {
+        throw new StateQLError("STALE_PLAN", "The stored table update is invalid. Reload the row and plan again.");
+    }
+}

package/dist/src/types.d.ts

@@ -80,6 +80,7 @@ export interface HistoryEntry {
     origin: CommandOrigin;
     command: string;
     sql: string | null;
+    target?: string | null;
     handle: string | null;
     executed: boolean;
     cached: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fadhilp/stateql",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Stateful, agent-oriented database CLI for safe result reuse",
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test dist/test/cli.test.js dist/test/credential.test.js dist/test/mongodb.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",
+    "test": "npm run build && node --test dist/test/cli.test.js dist/test/credential.test.js dist/test/mongodb.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 dist/test/panel.test.js",
     "release": "npm version",
     "version": "npm install",
     "prepack": "npm test"