@fadhilp/stateql 0.9.0 → 0.10.0

package/dist/src/stateql.js

@@ -1,13 +1,14 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
-import { compileTableUpdate, editableRow, parseTableUpdate } from "./table-editor.js";
+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";
@@ -172,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,
@@ -188,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();
             }
@@ -236,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 {
@@ -273,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) },
@@ -331,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,
@@ -371,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() {
@@ -748,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),
@@ -954,7 +1028,7 @@ export class StateQL {
         }));
     }
     async readTable(table, limit = 1000, options = {}) {
-        return this.commandContexts.run(mergeCommandExecutionContext(this.commandContexts.getStore(), { signal: options.signal, origin: options.origin ?? "api" }), async () => {
+        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)
@@ -967,6 +1041,8 @@ export class StateQL {
                 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)
@@ -1014,6 +1090,68 @@ export class StateQL {
             }
         }));
     }
+    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;
@@ -1086,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);
@@ -1102,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.");
             }
@@ -1276,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);
@@ -1302,6 +1452,56 @@ export class StateQL {
             }
         }, 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 = {}) {
         return this.run("plan", async (session) => {
             const connection = this.requireConnection(session);
@@ -1434,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) => {
@@ -1454,15 +1691,20 @@ export class StateQL {
                 throw new StateQLError("STALE_PLAN", "Plan has expired.");
             }
             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 nativePlan = tableUpdate?.metadata.driver === "mongodb" || plan.statement_type.startsWith("mongo.");
-            historySql = nativePlan ? undefined : plan.sql;
-            const mongoCommand = compiled?.mongo ?? (nativePlan
+            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 = compiled?.params ?? (nativePlan
+            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));
             const claimToken = this.store.nextId("claim");
@@ -1477,19 +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.");
@@ -1506,18 +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),
-                        ...(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);
+                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 },
@@ -1537,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) => ({
@@ -1569,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,
@@ -1584,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: {
@@ -1595,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,
+                    },
                 },
             },
         }));
@@ -1632,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":
@@ -1681,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)
@@ -1711,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":
@@ -1728,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":
@@ -1751,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,
@@ -1758,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"));
@@ -2180,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);
@@ -2223,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;
@@ -2334,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));
     }
@@ -2342,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,
@@ -2349,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",
@@ -2365,7 +2835,10 @@ export class StateQL {
     }
     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)) {
@@ -2389,6 +2862,8 @@ export class StateQL {
                 sessionId: session.id,
                 actorId: this.actorId,
                 origin,
+                category,
+                internal,
                 command,
                 target: historyTarget,
                 ...(result.handle ? { handle: result.handle } : {}),
@@ -2422,6 +2897,8 @@ export class StateQL {
                 sessionId: session.id,
                 actorId: this.actorId,
                 origin,
+                category,
+                internal,
                 command,
                 target: historyTarget,
                 ...(sqlText !== undefined ? { sql: sqlText } : {}),
@@ -2452,6 +2929,8 @@ 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 } : {}),
@@ -2482,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) {
@@ -2525,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}`;
 }
@@ -2566,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;
@@ -2670,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);
 }