@fadhilp/stateql 0.8.1 → 0.10.0

package/dist/src/stateql.js

@@ -1,11 +1,14 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { compileTableUpdate, editableRow, parseTableUpdate, parseTableUpdates } from "./table-editor.js";
 import { writeFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { env } from "node:process";
 import { AdapterExecutionError, AdapterWriteError, BatchWriteError, createAdapter, createAdapterContext, } from "./adapters.js";
-import { confidence, credentialSource, databaseIdentity, databaseUrlHasSecret, detectDriver, isEnvironmentName, mongoDatabaseName, normalizeSqliteSource, validateCredentialRef, validateProfileName, version, } from "./connection.js";
+import { confidence, credentialSource, databaseIdentity, databaseUrlHasSecret, detectDriver, isEnvironmentName, mongoDatabaseName, redisDatabaseName, normalizeSqliteSource, validateCredentialRef, validateProfileName, version, } from "./connection.js";
 import { asStateQLError, CredentialResolutionError, StateQLError, } from "./errors.js";
 import { analyzeMongoWriteSafety, deserializeMongoWriteCommand, serializeMongoCommand, validateMongoReadCommand, validateMongoWriteCommand, MongoAdapter, } from "./mongodb.js";
+import { deserializeRedisCommand, RedisAdapter, serializeRedisCommand, validateRedisReadCommand, validateRedisWriteCommand, } from "./redis.js";
 import { filterMaterializedRows, prepareFilterStatement, validateFilterParameters, } from "./filter.js";
 import { operationData, paginationWarnings, profileData, rowsToCsv, sessionData, transactionData, } from "./response-data.js";
 import { analyzeSql } from "./sql.js";
@@ -48,6 +51,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 +90,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]() {
@@ -163,7 +173,9 @@ export class StateQL {
                 ? basename(adapterSource)
                 : driver === "mongodb"
                     ? mongoDatabaseName(adapterSource)
-                    : new URL(secret).pathname.replace(/^\//, "") || driver;
+                    : driver === "redis"
+                        ? redisDatabaseName(adapterSource)
+                        : new URL(secret).pathname.replace(/^\//, "") || driver;
             const draft = {
                 id: "pending",
                 session_id: session.id,
@@ -179,7 +191,9 @@ export class StateQL {
             };
             const adapter = driver === "mongodb"
                 ? await this.openMongoAdapter(draft, context, adapterSource)
-                : await this.openAdapter(draft, context, adapterSource);
+                : driver === "redis"
+                    ? await this.openRedisAdapter(draft, context, adapterSource)
+                    : await this.openAdapter(draft, context, adapterSource);
             try {
                 await adapter.ping();
             }
@@ -227,34 +241,19 @@ export class StateQL {
     async addProfile(name, target, options = {}) {
         return this.run("profile.add", async () => {
             validateProfileName(name);
-            const sourceCount = [target, options.secretEnv, options.credentialRef]
-                .filter((value) => value !== undefined).length;
-            if (sourceCount !== 1 || target === "") {
-                throw new StateQLError("INVALID_COMMAND", "Profile requires exactly one target, secret environment variable, or credential reference.");
-            }
             if (this.store.getProfile(name)) {
                 throw new StateQLError("INVALID_COMMAND", `Profile "${name}" already exists.`);
             }
-            if (options.secretEnv !== undefined && !isEnvironmentName(options.secretEnv)) {
-                throw new StateQLError("INVALID_COMMAND", "Secret environment variable name is invalid.");
-            }
-            if (options.credentialRef !== undefined) {
-                validateCredentialRef(options.credentialRef);
-            }
-            let storedTarget = target;
-            if (target) {
-                const driver = detectDriver(target);
-                if (driver !== "sqlite" && databaseUrlHasSecret(target)) {
-                    throw new StateQLError("PERMISSION_DENIED", `Credential-bearing ${databaseDisplayName(driver)} URLs must use --env or --credential-ref.`);
-                }
-                if (driver === "sqlite")
-                    storedTarget = normalizeSqliteSource(target);
-            }
-            const profile = this.store.addProfile({
-                name,
-                target: storedTarget,
+            const source = validatedProfileSource({
+                target,
                 secretEnv: options.secretEnv,
                 credentialRef: options.credentialRef,
+            });
+            const profile = this.store.addProfile({
+                name,
+                target: source.target ?? undefined,
+                secretEnv: source.secretEnv ?? undefined,
+                credentialRef: source.credentialRef ?? undefined,
                 readOnly: options.readOnly ?? true,
             });
             return {
@@ -264,6 +263,36 @@ export class StateQL {
             };
         });
     }
+    async updateProfile(name, changes) {
+        return this.run("profile.update", async () => {
+            validateProfileName(name);
+            const existing = this.store.getProfile(name);
+            if (!existing)
+                throw new StateQLError("CONNECTION_NOT_FOUND", `Profile "${name}" was not found.`);
+            if (!changes || typeof changes !== "object" || Array.isArray(changes) ||
+                Object.keys(changes).some((key) => !["target", "secretEnv", "credentialRef", "readOnly"].includes(key))) {
+                throw new StateQLError("INVALID_COMMAND", "Profile update contains unknown fields.");
+            }
+            if (changes.readOnly !== undefined && typeof changes.readOnly !== "boolean")
+                throw new StateQLError("INVALID_COMMAND", "Profile readOnly must be boolean.");
+            const changesSource = Object.hasOwn(changes, "target") || Object.hasOwn(changes, "secretEnv") || Object.hasOwn(changes, "credentialRef");
+            if (!changesSource && changes.readOnly === undefined)
+                throw new StateQLError("INVALID_COMMAND", "Profile update has no changes.");
+            const source = changesSource
+                ? validatedProfileSource({ target: changes.target ?? undefined, secretEnv: changes.secretEnv ?? undefined, credentialRef: changes.credentialRef ?? undefined })
+                : { target: existing.target, secretEnv: existing.secret_env, credentialRef: existing.credential_ref };
+            const profile = this.store.updateProfile({
+                name,
+                target: source.target,
+                secretEnv: source.secretEnv,
+                credentialRef: source.credentialRef,
+                readOnly: changes.readOnly ?? Boolean(existing.read_only),
+            });
+            if (!profile)
+                throw new StateQLError("CONNECTION_NOT_FOUND", `Profile "${name}" was not found.`);
+            return { data: profileData(profile), handle: `profile:${name}`, executed: true };
+        });
+    }
     async listProfiles() {
         return this.run("profile.list", async () => ({
             data: { profiles: this.store.listProfiles().map(profileData) },
@@ -322,6 +351,13 @@ export class StateQL {
         if (historyLimit > MAX_SNAPSHOT_HISTORY_LIMIT) {
             throw new StateQLError("INVALID_COMMAND", `historyLimit cannot exceed ${MAX_SNAPSHOT_HISTORY_LIMIT}.`);
         }
+        if (options.historyInternal !== undefined && typeof options.historyInternal !== "boolean") {
+            throw new StateQLError("INVALID_COMMAND", "Snapshot historyInternal filter must be boolean.");
+        }
+        const historyOptions = {
+            ...(options.historyCategory === undefined ? {} : { category: parseHistoryCategory(options.historyCategory) }),
+            ...(options.historyInternal === undefined ? {} : { internal: options.historyInternal }),
+        };
         return {
             session: {
                 session_id: session.id,
@@ -362,7 +398,9 @@ export class StateQL {
                 affected_rows: operation.affected_rows,
                 status: operation.status,
             })),
-            history: this.store.history(session.id, historyLimit).map(historyEntry),
+            history: this.store
+                .history(session.id, historyLimit, historyOptions)
+                .map(historyEntry),
         };
     }
     async status() {
@@ -739,6 +777,51 @@ export class StateQL {
             }
         });
     }
+    async redisQuery(command, options = {}) {
+        return this.run("redis.query", async (session) => {
+            const value = validatedRedisRead(command);
+            const serialized = serializeRedisCommand(value);
+            const connection = this.requireRedisConnection(session, "redisQuery");
+            this.rejectDuringStagedTransaction(session, "Redis queries");
+            const context = this.executionContext(options);
+            const source = await this.resolveConnectionSource(connection, session, "query", "read", context);
+            const adapter = await this.openRedisAdapter(connection, context, source);
+            try {
+                const stateVersion = version(connection);
+                const stateSignature = await adapter.signature();
+                const fingerprint = hash({ command: serialized, connection: connection.id, database: connection.database_name, stateVersion });
+                const cached = this.store.findResult(fingerprint);
+                const cacheMode = options.cache ?? "auto";
+                if (cacheMode !== "bypass" && cached && cached.row_count <= this.maxResultRows && this.cacheValid(cached, stateVersion, stateSignature)) {
+                    return { data: this.resultData(cached, true), handle: cached.id, cached: true, stateVersion, confidence: cached.state_confidence };
+                }
+                if (cacheMode === "require")
+                    throw new StateQLError("CACHE_MISS", "No valid cached Redis result exists.", { retryable: true });
+                const result = await adapter.read(value);
+                const parameters = [serialized, result.nextCursor ?? null];
+                const resultBytes = Buffer.byteLength(JSON.stringify(parameters), "utf8") + Buffer.byteLength(JSON.stringify(result.rows), "utf8") + Buffer.byteLength(JSON.stringify(result.columns), "utf8");
+                if (result.rows.length > this.maxResultRows || resultBytes > this.maxResultBytes)
+                    throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", "Redis response exceeds materialization limits.");
+                const saved = this.store.saveResult({
+                    sessionId: session.id, connectionId: connection.id, fingerprint,
+                    sql: `Redis native ${value.command}`, parameters, rows: result.rows, columns: result.columns,
+                    stateVersion, stateSignature, stateConfidence: adapter.confidence,
+                    expiresAt: new Date(this.now().getTime() + this.resultTtlSeconds * 1000).toISOString(),
+                });
+                return { data: this.resultData(saved, false), handle: saved.id, executed: true, stateVersion, confidence: adapter.confidence };
+            }
+            catch (error) {
+                if (error instanceof StateQLError)
+                    throw error;
+                if (error instanceof AdapterExecutionError)
+                    throw stoppedStateQLError(error, true);
+                throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, source), { retryable: true, executed: true });
+            }
+            finally {
+                await closeAdapterQuietly(adapter);
+            }
+        });
+    }
     async show(idOrAlias) {
         return this.withResult("show", idOrAlias, async (result) => ({
             data: this.resultData(result, true),
@@ -855,6 +938,257 @@ 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", internal: true }), 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.");
+            if (driver === "redis")
+                throw new StateQLError("INVALID_COMMAND", "Redis keys are not SQL tables; use redisQuery and describeObject.");
+            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 planTableUpdates(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");
+            if (!Array.isArray(changes) || changes.length < 1 || changes.length > 100 || Buffer.byteLength(JSON.stringify(changes), "utf8") > 256 * 1024) {
+                throw new StateQLError("INVALID_COMMAND", "Table edit batch must contain 1-100 bounded rows.");
+            }
+            const connection = this.requireConnection(session);
+            if (connection.read_only)
+                throw new StateQLError("READ_ONLY_CONNECTION", "This connection is read-only.");
+            if (connection.driver === "redis")
+                throw new StateQLError("UNSUPPORTED_DRIVER", "Redis does not support table edits.");
+            const now = this.now().getTime();
+            const tokens = new Set();
+            const identities = new Set();
+            const updates = [];
+            let expires = Number.MAX_SAFE_INTEGER;
+            const metadataByTable = new Map();
+            for (const item of changes) {
+                if (!item || typeof item.row_token !== "string" || tokens.has(item.row_token))
+                    throw new StateQLError("INVALID_COMMAND", "Table edit row tokens must be unique.");
+                tokens.add(item.row_token);
+                const original = this.editTokens.get(item.row_token);
+                if (!original || original.sessionId !== session.id || original.connectionId !== connection.id || original.stateVersion !== version(connection) || original.expires <= now) {
+                    throw new StateQLError("STALE_PLAN", "A row identity expired or the connection changed. Reload the rows.");
+                }
+                const tableKey = JSON.stringify(original.metadata.table);
+                let metadata = metadataByTable.get(tableKey);
+                if (!metadata) {
+                    metadata = await this.editableMetadata(original.metadata.table, options);
+                    metadataByTable.set(tableKey, metadata);
+                }
+                if (JSON.stringify(metadata) !== JSON.stringify(original.metadata))
+                    throw new StateQLError("STALE_PLAN", "Table metadata changed. Reload the table.");
+                const identity = tableUpdateIdentity(metadata, original.original);
+                if (identities.has(identity))
+                    throw new StateQLError("INVALID_COMMAND", "The same row cannot appear twice in one edit batch.");
+                identities.add(identity);
+                const update = { metadata, original: original.original, changes: item.changes };
+                compileTableUpdate(update);
+                updates.push(update);
+                expires = Math.min(expires, original.expires);
+            }
+            const payload = JSON.stringify({ version: 1, updates });
+            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: `Conditional table update batch (${updates.length} rows)`, parameters: [payload], statementType: "table.updates",
+                    stateVersion: version(connection), stateSignature: await adapter.signature(), destructive: false,
+                    allowUnbounded: false, allowDestructive: false, expiresAt: new Date(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: plan.owner_actor_id, expires_at: plan.expires_at },
+                    handle: plan.id, executed: true, stateVersion: plan.state_version, confidence: adapter.confidence };
+            }
+            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);
@@ -890,6 +1224,14 @@ export class StateQL {
             return this.performMongoExec(session, connection, value, options, this.executionContext(options));
         });
     }
+    async redisExec(command, options = {}) {
+        return this.run("redis.exec", async (session) => {
+            const value = validatedRedisWrite(command);
+            const connection = this.requireRedisConnection(session, "redisExec");
+            this.rejectDuringStagedTransaction(session, "Redis writes");
+            return this.performRedisExec(session, connection, value, options, this.executionContext(options));
+        });
+    }
     async receipt(id) {
         return this.run("receipt", async (session) => {
             const operation = this.store.getOperation(id);
@@ -906,6 +1248,8 @@ export class StateQL {
     async beginTransaction(isolation) {
         return this.run("transaction.begin", async (session) => {
             const connection = this.requireConnection(session);
+            if (connection.driver === "redis")
+                throw new StateQLError("UNSUPPORTED_DRIVER", "Redis does not support staged StateQL transactions; use redisPlan/apply for one guarded mutation.");
             if (connection.read_only) {
                 throw new StateQLError("READ_ONLY_CONNECTION", "Cannot begin a write transaction on a read-only connection.");
             }
@@ -1080,6 +1424,8 @@ export class StateQL {
             this.rejectDuringStagedTransaction(session, "Schema inspection");
             const context = this.executionContext(options);
             const adapterSource = await this.resolveConnectionSource(connection, session, "inspect", "read", context);
+            if (connection.driver === "redis")
+                throw new StateQLError("INVALID_COMMAND", "Legacy inspect is not supported for Redis; use listObjects or describeObject.");
             const adapter = connection.driver === "mongodb"
                 ? await this.openMongoAdapter(connection, context, adapterSource)
                 : await this.openAdapter(connection, context, adapterSource);
@@ -1104,6 +1450,56 @@ export class StateQL {
             finally {
                 await closeAdapterQuietly(adapter);
             }
+        }, undefined, table);
+    }
+    async listObjects(filter = {}, options = {}) {
+        return this.run("objects.list", async (session) => {
+            validateCatalogFilter(filter);
+            const connection = this.requireConnection(session);
+            this.rejectDuringStagedTransaction(session, "Catalog discovery");
+            const context = this.executionContext(options);
+            const source = await this.resolveConnectionSource(connection, session, "inspect", "read", context);
+            const adapter = connection.driver === "mongodb"
+                ? await this.openMongoAdapter(connection, context, source)
+                : connection.driver === "redis"
+                    ? await this.openRedisAdapter(connection, context, source)
+                    : await this.openAdapter(connection, context, source);
+            try {
+                return { data: await adapter.listObjects(filter), executed: true, stateVersion: version(connection), confidence: adapter.confidence };
+            }
+            catch (error) {
+                if (error instanceof AdapterExecutionError)
+                    throw stoppedStateQLError(error, true);
+                throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, source), { executed: true });
+            }
+            finally {
+                await closeAdapterQuietly(adapter);
+            }
+        });
+    }
+    async describeObject(object, options = {}) {
+        return this.run("object.describe", async (session) => {
+            validateCatalogObject(object);
+            const connection = this.requireConnection(session);
+            this.rejectDuringStagedTransaction(session, "Catalog description");
+            const context = this.executionContext(options);
+            const source = await this.resolveConnectionSource(connection, session, "inspect", "read", context);
+            const adapter = connection.driver === "mongodb"
+                ? await this.openMongoAdapter(connection, context, source)
+                : connection.driver === "redis"
+                    ? await this.openRedisAdapter(connection, context, source)
+                    : await this.openAdapter(connection, context, source);
+            try {
+                return { data: await adapter.describeObject(object), executed: true, stateVersion: version(connection), confidence: adapter.confidence };
+            }
+            catch (error) {
+                if (error instanceof AdapterExecutionError)
+                    throw stoppedStateQLError(error, true);
+                throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, source), { executed: true });
+            }
+            finally {
+                await closeAdapterQuietly(adapter);
+            }
         });
     }
     async plan(sql, options = {}) {
@@ -1238,6 +1634,43 @@ export class StateQL {
             }
         });
     }
+    async redisPlan(command, options = {}) {
+        return this.run("redis.plan", async (session) => {
+            const value = validatedRedisWrite(command);
+            const connection = this.requireRedisConnection(session, "redisPlan");
+            this.rejectDuringStagedTransaction(session, "Plans");
+            if (connection.read_only)
+                throw new StateQLError("READ_ONLY_CONNECTION", "Connection is read-only.");
+            const context = this.executionContext(options);
+            const source = await this.resolveConnectionSource(connection, session, "plan", "read", context);
+            const adapter = await this.openRedisAdapter(connection, context, source);
+            try {
+                const precondition = await adapter.precondition(value);
+                const payload = JSON.stringify({ command: serializeRedisCommand(value), precondition });
+                const plan = this.store.savePlan({
+                    sessionId: session.id, ownerActorId: this.actorId, connectionId: connection.id,
+                    sql: `Redis native ${value.command}`, parameters: [payload], statementType: `redis.${value.command.toLowerCase()}`,
+                    stateVersion: version(connection), stateSignature: await adapter.signature(), destructive: value.command === "DEL",
+                    allowUnbounded: false, allowDestructive: true,
+                    expiresAt: new Date(this.now().getTime() + 10 * 60_000).toISOString(),
+                });
+                return { data: { plan_id: plan.id, statement_type: plan.statement_type, destructive: Boolean(plan.destructive),
+                        requires_confirmation: true, required_overrides: [], state_version: plan.state_version,
+                        owner_actor_id: plan.owner_actor_id, expires_at: plan.expires_at }, handle: plan.id, executed: true,
+                    stateVersion: plan.state_version, confidence: adapter.confidence };
+            }
+            catch (error) {
+                if (error instanceof StateQLError)
+                    throw error;
+                if (error instanceof AdapterExecutionError)
+                    throw stoppedStateQLError(error, true);
+                throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, source), { executed: true });
+            }
+            finally {
+                await closeAdapterQuietly(adapter);
+            }
+        });
+    }
     async apply(planId, options = {}) {
         let historySql;
         return this.run("apply", async (session) => {
@@ -1257,14 +1690,23 @@ 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.");
-            historySql = nativePlan ? undefined : plan.sql;
-            const mongoCommand = nativePlan
+            const tableUpdate = plan.statement_type === "table.update" ? parseTableUpdate(plan.parameters) : undefined;
+            const tableUpdates = plan.statement_type === "table.updates" ? parseTableUpdates(plan.parameters) : undefined;
+            const compiled = tableUpdate ? compileTableUpdate(tableUpdate) : undefined;
+            const compiledUpdates = tableUpdates?.map(compileTableUpdate);
+            if (compiled && compiled.sql !== plan.sql)
+                throw new StateQLError("STALE_PLAN", "Stored update does not match its plan.");
+            const mongoPlan = tableUpdate?.metadata.driver === "mongodb" || tableUpdates?.[0]?.metadata.driver === "mongodb" || plan.statement_type.startsWith("mongo.");
+            const redisPlan = plan.statement_type.startsWith("redis.");
+            const nativePlan = Boolean(mongoPlan || redisPlan);
+            historySql = nativePlan || tableUpdates ? undefined : plan.sql;
+            const mongoCommand = compiled?.mongo ?? (plan.statement_type.startsWith("mongo.")
                 ? storedMongoPlan(plan.parameters, plan.statement_type, plan.id)
-                : undefined;
-            const planParameters = nativePlan
+                : undefined);
+            const redisStored = redisPlan ? storedRedisPlan(plan.parameters, plan.statement_type, plan.id) : undefined;
+            const planParameters = compiled?.params ?? (nativePlan || tableUpdates
                 ? 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) {
@@ -1277,17 +1719,30 @@ export class StateQL {
                     version(connection) !== claimed.state_version) {
                     throw new StateQLError("STALE_PLAN", "Database state changed after this plan was created.");
                 }
-                if (nativePlan && connection.driver !== "mongodb") {
+                if (mongoPlan && connection.driver !== "mongodb") {
                     throw new StateQLError("STALE_PLAN", "MongoDB plan is not attached to a MongoDB connection.");
                 }
-                if (!nativePlan && connection.driver === "mongodb") {
+                if (redisPlan && connection.driver !== "redis") {
+                    throw new StateQLError("STALE_PLAN", "Redis plan is not attached to a Redis connection.");
+                }
+                if (!nativePlan && (connection.driver === "mongodb" || connection.driver === "redis")) {
                     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.");
+                if (tableUpdates) {
+                    for (const update of tableUpdates) {
+                        if (JSON.stringify(await this.editableMetadata(update.metadata.table, options)) !== JSON.stringify(update.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
+                const adapter = mongoPlan
                     ? await this.openMongoAdapter(connection, context, adapterSource)
-                    : await this.openAdapter(connection, context, adapterSource);
+                    : redisPlan
+                        ? await this.openRedisAdapter(connection, context, adapterSource)
+                        : await this.openAdapter(connection, context, adapterSource);
                 try {
                     if ((await adapter.signature()) !== claimed.state_signature) {
                         throw new StateQLError("STALE_PLAN", "Database state changed after this plan was created.");
@@ -1304,16 +1759,22 @@ export class StateQL {
                 finally {
                     await closeAdapterQuietly(adapter);
                 }
-                const result = mongoCommand
-                    ? await this.performMongoExec(session, connection, mongoCommand, {
-                        allowUnbounded: Boolean(claimed.allow_unbounded),
-                        allowDestructive: Boolean(claimed.allow_destructive),
-                    }, context, { planId: claimed.id, claimToken }, adapterSource)
-                    : await this.performExec(session, connection, claimed.sql, {
-                        params: planParameters,
-                        allowUnbounded: Boolean(claimed.allow_unbounded),
-                        allowDestructive: Boolean(claimed.allow_destructive),
-                    }, context, { planId: claimed.id, claimToken }, adapterSource);
+                const result = tableUpdates && compiledUpdates
+                    ? await this.performTableBatch(session, connection, tableUpdates, compiledUpdates, context, { planId: claimed.id, claimToken }, adapterSource)
+                    : redisStored
+                        ? await this.performRedisExec(session, connection, redisStored.command, {}, context, { planId: claimed.id, claimToken }, adapterSource, redisStored.precondition)
+                        : mongoCommand
+                            ? 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);
                 return {
                     ...result,
                     data: { plan_id: claimed.id, ...result.data },
@@ -1333,15 +1794,22 @@ export class StateQL {
         }, () => historySql);
     }
     async history(limit = 20, options = {}) {
-        return this.run("history", async (session) => ({
-            data: {
-                history: this.store
-                    .history(session.id, positiveInteger(limit, "limit"), options.origin === undefined
-                    ? undefined
-                    : parseCommandOrigin(options.origin))
-                    .map(historyEntry),
-            },
-        }));
+        return this.run("history", async (session) => {
+            if (options.internal !== undefined && typeof options.internal !== "boolean")
+                throw new StateQLError("INVALID_COMMAND", "History internal filter must be boolean.");
+            return {
+                data: {
+                    history: this.store
+                        .history(session.id, positiveInteger(limit, "limit"), {
+                        ...(options.origin === undefined ? {} : { origin: parseCommandOrigin(options.origin) }),
+                        ...(options.category === undefined ? {} : { category: parseHistoryCategory(options.category) }),
+                        ...(options.internal === undefined ? {} : { internal: options.internal }),
+                        offset: nonNegativeInteger(options.offset ?? 0, "offset"),
+                    })
+                        .map(historyEntry),
+                },
+            };
+        });
     }
     async doctor() {
         return this.run("doctor", async (session) => ({
@@ -1365,7 +1833,7 @@ export class StateQL {
     async capabilities() {
         return this.run("capabilities", async () => ({
             data: {
-                drivers: ["mongodb", "mysql", "postgres", "sqlite"],
+                drivers: ["mongodb", "mysql", "postgres", "redis", "sqlite"],
                 features: {
                     result_handles: true,
                     write_deduplication: true,
@@ -1380,6 +1848,10 @@ export class StateQL {
                     state_diagnostics: true,
                     state_purge: true,
                     state_quota: true,
+                    bounded_catalog: true,
+                    generated_aliases: true,
+                    multi_row_table_plans: true,
+                    history_classification: true,
                 },
                 driver_features: {
                     mongodb: {
@@ -1391,6 +1863,15 @@ export class StateQL {
                         transactions_require_replica_set: true,
                         inspection: true,
                     },
+                    redis: {
+                        sql: false,
+                        native_read: true,
+                        native_write: true,
+                        plans: true,
+                        transactions: false,
+                        guarded_single_key_writes: true,
+                        inspection: true,
+                    },
                 },
             },
         }));
@@ -1428,6 +1909,13 @@ export class StateQL {
                             secretEnv: command.secret_env,
                             credentialRef: command.credential_ref,
                         });
+                    case "profile.update":
+                        return this.updateProfile(batchString(command.name, "name"), {
+                            ...(command.target !== undefined ? { target: command.target } : {}),
+                            ...(command.secret_env !== undefined ? { secretEnv: command.secret_env } : {}),
+                            ...(command.credential_ref !== undefined ? { credentialRef: command.credential_ref } : {}),
+                            ...(command.read_only !== undefined ? { readOnly: command.read_only } : {}),
+                        });
                     case "profile.list":
                         return this.listProfiles();
                     case "profile.show":
@@ -1477,6 +1965,13 @@ export class StateQL {
                             data: { ...response.data, alias: command.as },
                         };
                     }
+                    case "redis.query": {
+                        const response = await this.redisQuery(command.redis, { cache: command.cache ?? "auto", timeoutMs: command.timeout_ms });
+                        if (!response.ok || !command.as)
+                            return response;
+                        this.store.setAlias(response.session_id, command.as, response.data.result_id);
+                        return { ...response, data: { ...response.data, alias: command.as } };
+                    }
                     case "filter": {
                         const response = await this.filter(batchString(command.handle, "handle"), batchString(command.where, "where"), { params: command.params ?? [] });
                         if (!response.ok || !command.as)
@@ -1507,6 +2002,12 @@ export class StateQL {
                             allowDestructive: command.allow_destructive ?? false,
                             timeoutMs: command.timeout_ms,
                         });
+                    case "redis.exec":
+                        return this.redisExec(command.redis, {
+                            replay: command.replay ?? false,
+                            idempotencyKey: command.idempotency_key,
+                            timeoutMs: command.timeout_ms,
+                        });
                     case "show":
                         return this.show(batchString(command.handle, "handle"));
                     case "rows":
@@ -1524,6 +2025,16 @@ export class StateQL {
                         return this.inspect(batchString(command.kind, "kind"), command.table, {
                             timeoutMs: command.timeout_ms,
                         });
+                    case "objects.list":
+                        return this.listObjects({
+                            ...(command.kind ? { kind: command.kind } : {}),
+                            ...(command.table ? { schema: command.table } : {}),
+                            ...(command.where ? { search: command.where } : {}),
+                            offset: command.cursor ?? command.offset ?? 0,
+                            limit: command.limit ?? 50,
+                        }, { timeoutMs: command.timeout_ms });
+                    case "object.describe":
+                        return this.describeObject(command.object, { timeoutMs: command.timeout_ms });
                     case "transaction.begin":
                         return this.beginTransaction(command.isolation);
                     case "transaction.status":
@@ -1547,6 +2058,8 @@ export class StateQL {
                             allowDestructive: command.allow_destructive,
                             timeoutMs: command.timeout_ms,
                         });
+                    case "redis.plan":
+                        return this.redisPlan(command.redis, { timeoutMs: command.timeout_ms });
                     case "apply":
                         return this.apply(batchString(command.handle, "handle"), {
                             timeoutMs: command.timeout_ms,
@@ -1554,6 +2067,9 @@ export class StateQL {
                     case "history":
                         return this.history(command.limit ?? 20, {
                             origin: command.history_origin,
+                            category: command.history_category,
+                            internal: command.history_internal,
+                            offset: command.offset,
                         });
                     case "receipt":
                         return this.receipt(batchString(command.handle, "handle"));
@@ -1716,7 +2232,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 +2280,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 +2424,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 +2473,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);
@@ -1972,6 +2492,139 @@ export class StateQL {
             }
         }
     }
+    async performRedisExec(session, connection, command, options, context, planClaim, resolvedSource, precondition) {
+        const value = validatedRedisWrite(command);
+        if (connection.driver !== "redis")
+            throw new StateQLError("INVALID_COMMAND", "redisExec requires an active Redis connection.");
+        if (connection.read_only)
+            throw new StateQLError("READ_ONLY_CONNECTION", "Connection is read-only.");
+        if (options.idempotencyKey !== undefined && !options.idempotencyKey.trim())
+            throw new StateQLError("INVALID_COMMAND", "Idempotency key cannot be empty.");
+        const serialized = serializeRedisCommand(value);
+        const fingerprint = hash({ command: serialized, database: databaseIdentity(connection) });
+        const reservation = this.store.reserveOperation({
+            sessionId: session.id, actorId: this.actorId, connectionId: connection.id, fingerprint,
+            sql: `Redis native ${value.command}`, parameters: [serialized], statementType: `redis.${value.command.toLowerCase()}`,
+            status: "executing", replay: options.replay ?? false, idempotencyKey: options.idempotencyKey,
+            stateVersionBefore: version(connection),
+        });
+        if (reservation.denied)
+            throw new StateQLError(reservation.denied === "membership" ? "PERMISSION_DENIED" : "TRANSACTION_FAILED", "Redis write reservation was denied.");
+        const previous = reservation.previous;
+        if (previous && options.idempotencyKey && !options.replay && previous.fingerprint !== fingerprint) {
+            throw new StateQLError("IDEMPOTENCY_CONFLICT", "Idempotency key was already used for a different write.");
+        }
+        if (previous && !reservation.operation) {
+            if (previous.status === "executing" || previous.status === "outcome_unknown")
+                throw new StateQLError("OUTCOME_UNKNOWN", "A matching Redis write has an unknown outcome.", { executed: true });
+            if (options.idempotencyKey)
+                return { data: { ...operationData(previous), duplicate: true, duplicate_of: previous.id, idempotency_key: options.idempotencyKey }, handle: previous.id, cached: true, stateVersion: previous.state_version_after ?? previous.state_version_before };
+            throw new StateQLError("POTENTIAL_DUPLICATE_WRITE", "An equivalent Redis operation was previously applied.", { extra: { previous_operation_id: previous.id, replay_required: true } });
+        }
+        const operation = reservation.operation;
+        let adapter;
+        let source;
+        try {
+            source = resolvedSource ?? await this.resolveConnectionSource(connection, session, "exec", "write", context);
+            adapter = await this.openRedisAdapter(connection, context, source);
+        }
+        catch (error) {
+            this.store.failOperation(operation.id);
+            if (error instanceof StateQLError)
+                throw error;
+            throw new StateQLError("CONNECTION_FAILED", "Redis connection failed.", { retryable: true });
+        }
+        try {
+            const write = await adapter.write(value, precondition);
+            try {
+                const finalized = planClaim
+                    ? this.store.finishPlannedOperation({ planId: planClaim.planId, claimToken: planClaim.claimToken, operationId: operation.id,
+                        connectionId: connection.id, affectedRows: write.affectedRows, outcome: write.outcome })
+                    : (() => { const stateVersion = this.store.bumpVersion(connection.id); return { operation: this.store.finishOperation(operation.id, write.affectedRows, stateVersion, write.outcome), stateVersion }; })();
+                return { data: { ...operationData(finalized.operation), duplicate: Boolean(previous), duplicate_override: Boolean(previous) },
+                    handle: finalized.operation.id, executed: true, stateVersion: finalized.stateVersion, confidence: adapter.confidence };
+            }
+            catch (error) {
+                this.store.markOperationOutcomeUnknown(operation.id);
+                throw new StateQLError("OUTCOME_UNKNOWN", errorMessage(error), { executed: true, suggestedAction: "Inspect Redis state before issuing a replacement write." });
+            }
+        }
+        catch (error) {
+            if (error instanceof StateQLError)
+                throw error;
+            if ((error instanceof AdapterExecutionError || error instanceof AdapterWriteError) && !error.outcomeUnknown) {
+                this.store.failOperation(operation.id);
+                if (error.message.startsWith("ROW_CONFLICT:"))
+                    throw new StateQLError("ROW_CONFLICT", "The Redis key changed. Reload and plan again.");
+                throw error instanceof AdapterExecutionError ? stoppedStateQLError(error, false) : new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, source), { executed: true });
+            }
+            this.store.markOperationOutcomeUnknown(operation.id);
+            throw new StateQLError("OUTCOME_UNKNOWN", safeCredentialErrorMessage(error, source), { executed: true, suggestedAction: "Inspect Redis state before issuing a replacement write." });
+        }
+        finally {
+            await closeAdapterQuietly(adapter);
+        }
+    }
+    async performTableBatch(session, connection, updates, compiled, context, planClaim, source) {
+        if (connection.driver === "redis")
+            throw new StateQLError("UNSUPPORTED_DRIVER", "Redis does not support table edit batches.");
+        const reservation = this.store.reserveOperation({
+            sessionId: session.id, actorId: this.actorId, connectionId: connection.id,
+            fingerprint: hash({ plan: planClaim.planId, updates }), sql: `Conditional table update batch (${updates.length} rows)`,
+            parameters: [JSON.stringify({ version: 1, updates })], statementType: "table.updates", status: "executing",
+            replay: true, stateVersionBefore: version(connection),
+        });
+        if (!reservation.operation)
+            throw new StateQLError("STALE_PLAN", "Table edit batch could not be reserved.");
+        const operation = reservation.operation;
+        const adapter = connection.driver === "mongodb"
+            ? await this.openMongoAdapter(connection, context, source)
+            : await this.openAdapter(connection, context, source);
+        try {
+            let affectedRows;
+            if (connection.driver === "mongodb") {
+                const commands = compiled.map((item) => {
+                    if (!item.mongo)
+                        throw new StateQLError("STALE_PLAN", "Table edit batch contains mixed drivers.");
+                    return item.mongo;
+                });
+                const results = await adapter.writeBatch(commands, "snapshot", true);
+                affectedRows = results.reduce((sum, item) => sum + item.affectedRows, 0);
+            }
+            else {
+                const operations = compiled.map((item, index) => ({
+                    ...operation, id: `${operation.id}:${index}`, sql: item.sql, parameters: JSON.stringify(item.params), statement_type: "update", expectedRows: 1,
+                }));
+                const results = await adapter.writeBatch(operations, "serializable");
+                affectedRows = results.reduce((sum, item) => sum + item.affectedRows, 0);
+            }
+            try {
+                const finalized = this.store.finishPlannedOperation({ planId: planClaim.planId, claimToken: planClaim.claimToken,
+                    operationId: operation.id, connectionId: connection.id, affectedRows });
+                return { data: operationData(finalized.operation), handle: finalized.operation.id, executed: true,
+                    stateVersion: finalized.stateVersion, confidence: adapter.confidence };
+            }
+            catch (error) {
+                this.store.markOperationOutcomeUnknown(operation.id);
+                throw new StateQLError("OUTCOME_UNKNOWN", errorMessage(error), { executed: true, suggestedAction: "Inspect every edited row before retrying." });
+            }
+        }
+        catch (error) {
+            if (error instanceof StateQLError)
+                throw error;
+            if ((error instanceof BatchWriteError || error instanceof AdapterExecutionError) && !error.outcomeUnknown) {
+                this.store.failOperation(operation.id);
+                if (error.message.startsWith("ROW_CONFLICT:"))
+                    throw new StateQLError("ROW_CONFLICT", "At least one row changed; the entire edit batch was rolled back.");
+                throw error instanceof AdapterExecutionError ? stoppedStateQLError(error, false) : new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, source), { executed: true });
+            }
+            this.store.markOperationOutcomeUnknown(operation.id);
+            throw new StateQLError("OUTCOME_UNKNOWN", safeCredentialErrorMessage(error, source), { executed: true, suggestedAction: "Inspect every edited row before retrying." });
+        }
+        finally {
+            await closeAdapterQuietly(adapter);
+        }
+    }
     batchFailure(message) {
         return this.run("batch", async () => {
             throw new StateQLError("INVALID_COMMAND", message);
@@ -2015,10 +2668,20 @@ export class StateQL {
         }
         return connection;
     }
+    requireRedisConnection(session, method) {
+        const connection = this.requireConnection(session);
+        if (connection.driver !== "redis")
+            throw new StateQLError("INVALID_COMMAND", `${method} requires an active Redis connection.`);
+        return connection;
+    }
     rejectMongoSql(connection, nativeMethod) {
-        if (connection.driver !== "mongodb")
+        if (connection.driver !== "mongodb" && connection.driver !== "redis")
             return;
-        throw new StateQLError("INVALID_COMMAND", `SQL is not supported for MongoDB connections; use ${nativeMethod} instead.`, { suggestedAction: `Use ${nativeMethod} with a native MongoDB command.` });
+        const method = connection.driver === "redis"
+            ? nativeMethod === "mongoQuery" ? "redisQuery" : nativeMethod === "mongoExec" ? "redisExec" : "redisPlan"
+            : nativeMethod;
+        const name = connection.driver === "redis" ? "Redis" : "MongoDB";
+        throw new StateQLError("INVALID_COMMAND", `SQL is not supported for ${name} connections; use ${method} instead.`, { suggestedAction: `Use ${method} with a native ${name} command.` });
     }
     requireActiveTransaction(session, id) {
         const transactionId = id ?? session.active_transaction_id;
@@ -2126,6 +2789,18 @@ export class StateQL {
             throw new StateQLError("CONNECTION_FAILED", safeCredentialErrorMessage(error, source), { retryable: true });
         }
     }
+    async openRedisAdapter(connection, context, source) {
+        try {
+            if (connection.driver !== "redis")
+                throw new Error("Redis adapter requires a Redis connection.");
+            return new RedisAdapter(source, Boolean(connection.read_only), context);
+        }
+        catch (error) {
+            if (error instanceof StateQLError)
+                throw error;
+            throw new StateQLError("CONNECTION_FAILED", safeCredentialErrorMessage(error, source), { retryable: true });
+        }
+    }
     executionContext(options) {
         return createAdapterContext(executionTimeout(options.timeoutMs ?? this.timeoutMs), combineAbortSignals(options.signal, this.commandContexts.getStore()?.signal, this.signal));
     }
@@ -2134,6 +2809,8 @@ export class StateQL {
         const preview = compactRows(rows.slice(0, this.previewRows), this.maxCellCharacters);
         return {
             result_id: result.id,
+            alias: result.alias ?? this.store.generatedAlias(result.id),
+            display_alias: result.alias ?? this.store.generatedAlias(result.id),
             rows: result.row_count,
             columns: this.store.resultColumns(result),
             preview,
@@ -2141,6 +2818,7 @@ export class StateQL {
             truncated: preview.length < result.row_count,
             cached,
             ...(cached ? { duplicate_of: result.id } : {}),
+            ...(result.sql.startsWith("Redis native ") ? { next_cursor: redisResultCursor(result.parameters) } : {}),
             state_version: result.state_version,
             storage: {
                 mode: "materialized",
@@ -2155,9 +2833,12 @@ 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";
+        const commandContext = this.commandContexts.getStore();
+        const origin = commandContext?.origin ?? "legacy";
+        const category = historyCategory(command);
+        const internal = commandContext?.internal ?? false;
         let session = this.store.ensureSession(this.sessionName);
         const commandId = this.store.nextId("cmd");
         if (!this.store.isSessionMember(session.id, this.actorId)) {
@@ -2181,7 +2862,10 @@ export class StateQL {
                 sessionId: session.id,
                 actorId: this.actorId,
                 origin,
+                category,
+                internal,
                 command,
+                target: historyTarget,
                 ...(result.handle ? { handle: result.handle } : {}),
                 ...(sqlText !== undefined ? { sql: sqlText } : {}),
                 executed: result.executed ?? false,
@@ -2213,7 +2897,10 @@ export class StateQL {
                 sessionId: session.id,
                 actorId: this.actorId,
                 origin,
+                category,
+                internal,
                 command,
+                target: historyTarget,
                 ...(sqlText !== undefined ? { sql: sqlText } : {}),
                 executed: stateqlError.details.executed,
                 cached: false,
@@ -2242,8 +2929,11 @@ function historyEntry(item) {
         session_id: item.session_id,
         actor_id: item.actor_id,
         origin: item.origin,
+        category: item.category,
+        internal: Boolean(item.internal),
         command: item.command,
         sql: item.sql,
+        ...(item.target ? { target: item.target } : {}),
         handle: item.handle,
         executed: Boolean(item.executed),
         cached: Boolean(item.cached),
@@ -2271,11 +2961,15 @@ function mergeCommandExecutionContext(inherited, supplied) {
     if (supplied.signal !== undefined && !(supplied.signal instanceof AbortSignal)) {
         throw new StateQLError("INVALID_COMMAND", "Command execution context signal must be an AbortSignal.");
     }
+    if (supplied.internal !== undefined && typeof supplied.internal !== "boolean") {
+        throw new StateQLError("INVALID_COMMAND", "Command execution context internal must be boolean.");
+    }
     return {
         signal: combineAbortSignals(inherited?.signal, supplied.signal),
         origin: supplied.origin === undefined
             ? inherited?.origin
             : parseCommandOrigin(supplied.origin),
+        internal: supplied.internal ?? inherited?.internal,
     };
 }
 function combineAbortSignals(...signals) {
@@ -2314,6 +3008,22 @@ function validatedMongoWrite(command) {
         throw new StateQLError("INVALID_COMMAND", errorMessage(error));
     }
 }
+function validatedRedisRead(command) {
+    try {
+        return validateRedisReadCommand(command);
+    }
+    catch (error) {
+        throw new StateQLError("INVALID_COMMAND", errorMessage(error));
+    }
+}
+function validatedRedisWrite(command) {
+    try {
+        return validateRedisWriteCommand(command);
+    }
+    catch (error) {
+        throw new StateQLError("INVALID_COMMAND", errorMessage(error));
+    }
+}
 function mongoDescriptor(operation) {
     return `MongoDB native ${operation}`;
 }
@@ -2355,14 +3065,68 @@ function storedMongoWrite(parameters, statementType, label, errorCode) {
         throw new StateQLError(errorCode, `Stored MongoDB ${label} payload is invalid.`);
     }
 }
+function storedRedisPlan(parameters, statementType, planId) {
+    try {
+        const outer = JSON.parse(parameters);
+        if (!Array.isArray(outer) || outer.length !== 1 || typeof outer[0] !== "string")
+            throw new Error();
+        const payload = JSON.parse(outer[0]);
+        if (typeof payload.command !== "string" || !payload.precondition || typeof payload.precondition !== "object")
+            throw new Error();
+        const command = deserializeRedisCommand(payload.command);
+        const precondition = payload.precondition;
+        if (typeof precondition.key !== "string" || typeof precondition.fingerprint !== "string" || typeof precondition.expiresAt !== "number" || !Number.isFinite(precondition.expiresAt) || statementType !== `redis.${command.command.toLowerCase()}`)
+            throw new Error();
+        return { command, precondition };
+    }
+    catch {
+        throw new StateQLError("STALE_PLAN", `Stored Redis plan "${planId}" payload is invalid.`);
+    }
+}
+function redisResultCursor(parameters) {
+    try {
+        const value = JSON.parse(parameters);
+        return Array.isArray(value) && (typeof value[1] === "string" || value[1] === null) ? value[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+function tableUpdateIdentity(metadata, row) {
+    const identity = metadata.driver === "mongodb"
+        ? { table: metadata.table, id: row._id }
+        : { table: metadata.table, keys: metadata.columns.filter((column) => column.key > 0).sort((a, b) => a.key - b.key).map((column) => [column.name, row[column.name]]) };
+    return hash(identity);
+}
+function validateCatalogFilter(filter) {
+    if (!filter || typeof filter !== "object" || Array.isArray(filter) || Object.keys(filter).some((key) => !["kind", "schema", "search", "offset", "limit"].includes(key)))
+        throw new StateQLError("INVALID_COMMAND", "Catalog filter contains unknown fields.");
+    if (filter.kind !== undefined && !["table", "view", "collection", "function", "trigger", "enum", "key"].includes(filter.kind))
+        throw new StateQLError("INVALID_COMMAND", "Unknown catalog object kind.");
+    for (const [name, value] of [["schema", filter.schema], ["search", filter.search]])
+        if (value !== undefined && (typeof value !== "string" || !value || value.length > 200 || value.includes("\0")))
+            throw new StateQLError("INVALID_COMMAND", `Catalog ${name} is invalid.`);
+    if (filter.offset !== undefined && !((typeof filter.offset === "number" && Number.isSafeInteger(filter.offset) && filter.offset >= 0) || (typeof filter.offset === "string" && /^\d+$/.test(filter.offset))))
+        throw new StateQLError("INVALID_COMMAND", "Catalog offset is invalid.");
+    if (filter.limit !== undefined && (!Number.isSafeInteger(filter.limit) || filter.limit < 1 || filter.limit > 200))
+        throw new StateQLError("INVALID_COMMAND", "Catalog limit must be 1-200.");
+}
+function validateCatalogObject(object) {
+    if (!object || typeof object !== "object" || Array.isArray(object) || !["table", "view", "collection", "function", "trigger", "enum", "key"].includes(object.kind) || typeof object.name !== "string" || !object.name || object.name.length > 500 || object.name.includes("\0") || (object.schema !== undefined && (typeof object.schema !== "string" || !object.schema || object.schema.length > 500 || object.schema.includes("\0"))) || (object.identity !== undefined && (typeof object.identity !== "string" || !object.identity || object.identity.length > 1000 || object.identity.includes("\0"))))
+        throw new StateQLError("INVALID_COMMAND", "Catalog object identity is invalid.");
+}
 function databaseDisplayName(driver) {
     if (driver === "mongodb")
         return "MongoDB";
+    if (driver === "redis")
+        return "Redis";
     return driver === "postgres" ? "PostgreSQL" : "MySQL";
 }
 function normalizeIsolation(isolation, driver) {
     const normalized = isolation.trim().toLowerCase().replace(/[_-]+/g, " ")
         .replace(/\s+/g, " ");
+    if (driver === "redis")
+        throw new StateQLError("UNSUPPORTED_DRIVER", "Redis does not support staged SQL-style transactions.");
     if (driver === "mongodb") {
         if (normalized === "snapshot")
             return normalized;
@@ -2459,6 +3223,37 @@ function executionTimeout(value, name = "timeoutMs") {
 function stoppedStateQLError(error, executed) {
     return new StateQLError(error.reason === "timeout" ? "DEADLINE_EXCEEDED" : "OPERATION_CANCELLED", error.message, { retryable: true, executed });
 }
+function validatedProfileSource(input) {
+    const sourceCount = [input.target, input.secretEnv, input.credentialRef].filter((value) => value !== undefined).length;
+    if (sourceCount !== 1 || input.target === "" || input.secretEnv === "" || input.credentialRef === "") {
+        throw new StateQLError("INVALID_COMMAND", "Profile requires exactly one target, secret environment variable, or credential reference.");
+    }
+    if (input.secretEnv !== undefined && !isEnvironmentName(input.secretEnv))
+        throw new StateQLError("INVALID_COMMAND", "Secret environment variable name is invalid.");
+    if (input.credentialRef !== undefined)
+        validateCredentialRef(input.credentialRef);
+    let target = input.target ?? null;
+    if (target) {
+        const driver = detectDriver(target);
+        if (driver !== "sqlite" && databaseUrlHasSecret(target))
+            throw new StateQLError("PERMISSION_DENIED", `Credential-bearing ${databaseDisplayName(driver)} URLs must use --env or --credential-ref.`);
+        if (driver === "sqlite")
+            target = normalizeSqliteSource(target);
+    }
+    return { target, secretEnv: input.secretEnv ?? null, credentialRef: input.credentialRef ?? null };
+}
+function historyCategory(command) {
+    if (["query", "exec", "plan", "apply", "mongo.query", "mongo.exec", "mongo.plan", "redis.query", "redis.exec", "redis.plan", "filter"].includes(command))
+        return "statement";
+    if (command.startsWith("inspect.") || ["objects.list", "object.describe", "table.read"].includes(command))
+        return "introspection";
+    return "management";
+}
+function parseHistoryCategory(value) {
+    if (value === "statement" || value === "introspection" || value === "management")
+        return value;
+    throw new StateQLError("INVALID_COMMAND", `Unknown history category "${String(value)}".`);
+}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }