@fadhilp/stateql 0.8.1 → 0.10.0

package/README.md

@@ -2,8 +2,8 @@
 
 StateQL is a stateful database CLI and TypeScript library for AI agents and
 automation. It provides a safe interface for querying, changing, and inspecting
-SQLite, PostgreSQL, MySQL, and MongoDB databases while keeping results reusable
-and operations traceable across commands.
+SQLite, PostgreSQL, MySQL, MongoDB, and Redis databases while keeping results
+reusable and operations traceable across commands.
 
 StateQL is built around durable handles:
 
@@ -527,8 +527,8 @@ safety and duplicate checks. Requests contain actor and session identity, the
 operation's effective read/write access, an abort signal, and sanitized
 connection metadata.
 
-Returned values must be complete PostgreSQL, MySQL, or MongoDB URLs, or explicit
-`sqlite:` sources. StateQL validates the source and its stored driver before
+Returned values must be complete PostgreSQL, MySQL, MongoDB, or Redis URLs, or
+explicit `sqlite:` sources. StateQL validates the source and its stored driver before
 adapter construction and normalizes SQLite paths. Credential-bearing database
 URLs are redacted before connection metadata is persisted and never enter
 history, snapshots, cache keys, or responses. SQLite paths remain persisted
@@ -540,4 +540,139 @@ and keeping values out of their own logs and model-visible data.
 For writes, credential resolution happens after StateQL atomically reserves the
 operation for duplicate protection. A resolution failure keeps a non-executed
 `failed` audit record, does not consume the idempotency key, and permits a safe
-retry.
+retry.
+
+## Pylon database integration API (0.9.0)
+
+### Result identities and aliases
+
+Every materialized SQL, MongoDB, Redis, table, or derived result keeps its
+immutable `q_*` `result_id` and receives a cryptographically random 10-character
+lowercase base32 `display_alias`. `ResultData.alias` normally equals that alias.
+When a batch command supplies `as`, `alias` remains the caller alias for backward
+compatibility while `display_alias` remains canonical. Generated aliases are
+session-scoped, allocated atomically with the result, stable on cache reuse, and
+cannot be reassigned by `setAlias`; explicit aliases and all old handles continue
+to resolve.
+
+### Safe profile updates
+
+```ts
+updateProfile(name, {
+  target?: string | null,
+  secretEnv?: string | null,
+  credentialRef?: string | null,
+  readOnly?: boolean,
+})
+```
+
+Omitting all source fields keeps the existing source. Supplying any source field
+replaces the source atomically: exactly one non-null source is required and the
+other source columns are cleared. Direct non-SQLite URLs containing credentials
+or secret-like query parameters are rejected. `profile.list/show/update` return
+only `{profile,target,secret_env,credential_ref,read_only}`. `target` is therefore
+a normalized SQLite path or a secret-free URL; reference-backed profiles expose
+only the environment-variable name or opaque credential reference, never a
+resolved value. Profile changes affect subsequent `connect` calls and do not
+silently mutate an already-open connection.
+
+### Bounded catalog
+
+```ts
+listObjects(
+  { kind?, schema?, search?, offset?, limit? },
+  { timeoutMs?, signal? },
+) -> { objects, next_offset, supported_kinds }
+
+describeObject(
+  { kind, schema?, name, identity? },
+  { timeoutMs?, signal? },
+) -> { object, definition? }
+```
+
+SQL/MongoDB offsets are non-negative numbers; limits default to 50 and are at
+most 200. Redis `offset` and `next_offset` are opaque numeric SCAN cursor strings;
+its limit is a SCAN `COUNT` hint with a hard 200-item response bound. Redis pages
+are not snapshots and can be empty or contain duplicates while keys change.
+Search is a case-insensitive name substring for SQL/MongoDB and escaped glob
+substring matching for Redis. No exact counts are forced.
+
+Supported kinds are returned on every page: SQLite `table,view,trigger`;
+PostgreSQL `table,view,function,trigger,enum`; MySQL
+`table,view,function,trigger`; MongoDB `collection,view`; Redis `key`.
+PostgreSQL function identities include identity arguments, so overloads remain
+distinct. `describeObject` is read-only and requires the structured identity;
+legacy `inspect` behavior is unchanged (and intentionally unavailable for Redis).
+
+### Reviewed multi-row table edits
+
+```ts
+planTableUpdates(
+  Array<{ row_token: string; changes: { set?: object; unset?: string[] } }>,
+  options?,
+) -> PlanData
+```
+
+Batches contain 1-100 distinct row identities and at most 256 KiB. All tokens,
+connection/state versions, expiries, metadata, editable columns, and values are
+validated before one plan is stored; expiry is the earliest token expiry.
+`apply(plan_id)` executes all conditional row updates in one SQLite/PostgreSQL/
+MySQL transaction and requires every row predicate to match, otherwise all are
+rolled back. MongoDB uses one snapshot transaction and rejects deployments that
+do not support transactions. Redis and active staged StateQL transactions are
+rejected. The existing `planTableUpdate` and `apply` APIs remain supported.
+Plans are actor-owned, claimed once, and retained as non-replayable when the
+remote commit outcome is uncertain.
+
+### Redis native commands
+
+Redis/Rediss URLs support URL database selection, password or ACL username,
+and TLS (`rediss`). Credential-bearing URLs must come from `secretEnv` or
+`credentialRef`. Native methods accept `{command: string, args?: string[]}`:
+
+- `redisQuery`: `GET`, `MGET`, `TYPE`, `EXISTS`, `TTL`, `PTTL`, `HGET`, `HMGET`,
+  bounded `LRANGE`, and bounded `SCAN`/`HSCAN`/`SSCAN`/`ZSCAN`.
+- `redisExec` and `redisPlan`: one-key `SET`, `DEL`, `HSET`, `HDEL`, `LPUSH`,
+  `RPUSH`, `SADD`, `SREM`, `ZADD`, or `ZREM` mutation.
+- `describeObject({kind:"key",name})`: bounded string/hash/list/set/zset value
+  inspection with TTL and continuation metadata where applicable.
+
+Arguments are UTF-8 strings, at most 100 values/256 KiB; materialized replies are
+at most 1 MiB. `KEYS`, scripts, modules, pub/sub, blocking commands, admin/flush,
+and arbitrary commands are rejected. Key discovery always uses SCAN. A Redis
+plan snapshots one bounded key and `apply` uses an isolated `WATCH` + one-command
+`MULTI/EXEC`; a pre-apply content or expiry change returns `ROW_CONFLICT` and is
+never retried automatically. Direct `redisExec` has Redis single-command
+atomicity only. Redis has no SQL rollback or StateQL staged transaction support;
+a lost write/EXEC reply is reported as `OUTCOME_UNKNOWN` and remains blocked.
+
+### Lean history
+
+```ts
+history(limit?, {
+  origin?,
+  category?: "statement" | "introspection" | "management",
+  internal?: boolean,
+  offset?: number,
+})
+```
+
+`category` and trusted-host `internal` filters are applied in SQLite before
+`ORDER BY`, `LIMIT`, and `OFFSET`, so introspection cannot starve statement
+history. `CommandExecutionContext.internal` is trusted host metadata and cannot
+be supplied inside a batch command. Existing calls and origin filtering remain
+compatible; old rows are classified from their command name and migrate as `internal: false`.
+
+The synchronous, non-mutating snapshot bridge accepts the same classification
+filters without entering the command queue or writing a history row:
+
+```ts
+stateql.snapshot({
+  historyLimit: 50,
+  historyCategory: "statement",
+  historyInternal: false,
+});
+```
+
+Both snapshot filters are applied by the store before `historyLimit`. Calling
+`snapshot()` with no options preserves the legacy 50-entry CLI snapshot.

package/dist/src/adapters.d.ts

@@ -1,4 +1,4 @@
-import type { Column, Row, SqlParameters, StateConfidence } from "./types.js";
+import type { CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, Column, Row, SqlParameters, StateConfidence } from "./types.js";
 import type { ConnectionRecord, OperationRecord } from "./store.js";
 export interface ReadResult {
     rows: Row[];
@@ -7,6 +7,9 @@ export interface ReadResult {
 export interface WriteResult {
     affectedRows: number;
 }
+export type BatchWriteOperation = OperationRecord & {
+    expectedRows?: 1;
+};
 export interface AdapterContext {
     deadline: number;
     timeoutMs?: number;
@@ -29,10 +32,12 @@ export interface Adapter {
     readonly confidence: StateConfidence;
     ping(): Promise<void>;
     read(sql: string, params: SqlParameters): Promise<ReadResult>;
-    write(sql: string, params: SqlParameters): Promise<WriteResult>;
-    writeBatch(operations: OperationRecord[], isolation: string): Promise<WriteResult[]>;
+    write(sql: string, params: SqlParameters, expectedRows?: 1): Promise<WriteResult>;
+    writeBatch(operations: BatchWriteOperation[], isolation: string): Promise<WriteResult[]>;
     signature(): Promise<string>;
     inspect(kind: string, table?: string): Promise<unknown>;
+    listObjects(filter: ListObjectsFilter): Promise<ListObjectsData>;
+    describeObject(object: CatalogObject): Promise<DescribeObjectData>;
     close(): Promise<void>;
 }
 export declare function createAdapterContext(timeoutMs: number, signal?: AbortSignal): AdapterContext;

package/dist/src/adapters.js

@@ -47,6 +47,8 @@ export async function createAdapter(connection, context, input) {
             return new MySqlAdapter(source, Boolean(connection.read_only), context);
         case "mongodb":
             throw new StateQLError("UNSUPPORTED_DRIVER", "MongoDB uses the native MongoDB adapter.");
+        case "redis":
+            throw new StateQLError("UNSUPPORTED_DRIVER", "Redis uses the native Redis adapter.");
     }
 }
 class SQLiteAdapter {
@@ -96,8 +98,8 @@ class SQLiteAdapter {
     async read(sql, params) {
         return this.call("read", [sql, params], false, false);
     }
-    async write(sql, params) {
-        return this.call("write", [sql, params], true, false);
+    async write(sql, params, expectedRows) {
+        return this.call("write", [sql, params, expectedRows], true, false);
     }
     async writeBatch(operations, isolation) {
         return this.call("writeBatch", [operations, isolation], true, true);
@@ -108,6 +110,12 @@ class SQLiteAdapter {
     async inspect(kind, table) {
         return this.call("inspect", [kind, table], false, false);
     }
+    async listObjects(filter) {
+        return this.call("listObjects", [filter], false, false);
+    }
+    async describeObject(object) {
+        return this.call("describeObject", [object], false, false);
+    }
     async close() {
         if (this.closePromise)
             return this.closePromise;
@@ -251,7 +259,7 @@ class PostgresAdapter {
             throw error;
         }
     }
-    async write(sql, params) {
+    async write(sql, params, expectedRows) {
         if (this.readOnly)
             throw new Error("Connection is read-only.");
         try {
@@ -267,6 +275,8 @@ class PostgresAdapter {
         try {
             await this.setLocalDeadline();
             const result = await this.query(sql, postgresParams(params), true);
+            if (expectedRows === 1 && result.rowCount !== 1)
+                throw new Error("ROW_CONFLICT: The row changed or no longer has a unique identity.");
             committing = true;
             await this.query("COMMIT", [], true);
             return { affectedRows: result.rowCount ?? 0 };
@@ -304,6 +314,8 @@ class PostgresAdapter {
                 await this.setLocalDeadline();
                 const result = await this.query(operation.sql, postgresParams(parseJson(operation.parameters, `operation "${operation.id}" parameters`, isSqlParameters)), true);
                 results.push({ affectedRows: result.rowCount ?? 0 });
+                if (operation.expectedRows === 1 && result.rowCount !== 1)
+                    throw new Error("ROW_CONFLICT: The row changed or no longer has a unique identity.");
             }
         }
         catch (error) {
@@ -338,6 +350,67 @@ class PostgresAdapter {
             throw error;
         }
     }
+    async listObjects(filter) {
+        if (filter.kind && !["table", "view", "function", "trigger", "enum"].includes(filter.kind))
+            throw new Error(`PostgreSQL does not support catalog kind "${filter.kind}".`);
+        const { where, params } = postgresCatalogFilter(filter);
+        const limit = catalogLimit(filter.limit);
+        const offset = catalogOffset(filter.offset);
+        const result = await this.read(`SELECT * FROM (
+        SELECT CASE WHEN table_type = 'VIEW' THEN 'view' ELSE 'table' END AS kind,
+               table_schema AS schema, table_name AS name,
+               table_schema || '.' || table_name AS identity
+        FROM information_schema.tables
+        WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
+        UNION ALL
+        SELECT 'function', n.nspname, p.proname,
+               n.nspname || '.' || p.proname || '(' || pg_get_function_identity_arguments(p.oid) || ')'
+        FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+        WHERE n.nspname NOT IN ('pg_catalog', 'information_schema') AND p.prokind = 'f'
+        UNION ALL
+        SELECT DISTINCT 'trigger', event_object_schema, trigger_name,
+               event_object_schema || '.' || event_object_table || '.' || trigger_name
+        FROM information_schema.triggers
+        UNION ALL
+        SELECT 'enum', n.nspname, t.typname, n.nspname || '.' || t.typname
+        FROM pg_type t JOIN pg_namespace n ON n.oid = t.typnamespace WHERE t.typtype = 'e'
+      ) objects ${where} ORDER BY schema, kind, name, identity LIMIT $${params.length + 1} OFFSET $${params.length + 2}`, [...params, limit + 1, offset]);
+        return catalogPage(result.rows, limit, offset, ["table", "view", "function", "trigger", "enum"]);
+    }
+    async describeObject(object) {
+        const schema = object.schema ?? "public";
+        if (object.kind === "function") {
+            const result = await this.read(`SELECT pg_get_functiondef(p.oid) AS definition FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+         WHERE n.nspname = $1 AND p.proname = $2
+           AND n.nspname || '.' || p.proname || '(' || pg_get_function_identity_arguments(p.oid) || ')' = $3`, [schema, object.name, object.identity ?? ""]);
+            if (!result.rows[0])
+                throw new Error("Catalog object was not found.");
+            return { object, definition: String(result.rows[0].definition) };
+        }
+        if (object.kind === "trigger") {
+            const result = await this.read(`SELECT pg_get_triggerdef(t.oid, true) AS definition FROM pg_trigger t
+         JOIN pg_class c ON c.oid=t.tgrelid JOIN pg_namespace n ON n.oid=c.relnamespace
+         WHERE NOT t.tgisinternal AND n.nspname=$1 AND t.tgname=$2
+           AND n.nspname || '.' || c.relname || '.' || t.tgname=$3`, [schema, object.name, object.identity ?? ""]);
+            if (!result.rows[0])
+                throw new Error("Catalog object was not found.");
+            return { object, definition: String(result.rows[0].definition) };
+        }
+        if (object.kind === "enum") {
+            const result = await this.read(`SELECT e.enumlabel AS value FROM pg_enum e JOIN pg_type t ON t.oid=e.enumtypid JOIN pg_namespace n ON n.oid=t.typnamespace
+         WHERE n.nspname=$1 AND t.typname=$2 ORDER BY e.enumsortorder`, [schema, object.name]);
+            return { object, definition: result.rows };
+        }
+        if (object.kind === "view") {
+            const result = await this.read("SELECT view_definition AS definition FROM information_schema.views WHERE table_schema=$1 AND table_name=$2", [schema, object.name]);
+            if (!result.rows[0])
+                throw new Error("Catalog object was not found.");
+            return { object, definition: String(result.rows[0].definition) };
+        }
+        if (object.kind === "table")
+            return { object, definition: await this.inspect("table", `${schema}.${object.name}`) };
+        throw new Error(`PostgreSQL does not support catalog kind "${object.kind}".`);
+    }
     async close() {
         if (!this.ending) {
             this.ending = this.client.end().catch(() => undefined);
@@ -358,6 +431,18 @@ class PostgresAdapter {
         const [schema, name] = table.includes(".")
             ? table.split(".", 2)
             : ["public", table];
+        if (kind === "editable") {
+            await this.setLocalDeadline();
+            const result = await this.query(`SELECT c.column_name AS name, c.data_type AS type, c.is_nullable = 'YES' AS nullable,
+          (c.is_generated = 'ALWAYS' OR c.is_identity = 'YES') AS generated,
+          COALESCE(k.ordinal_position, 0) AS key
+         FROM information_schema.columns c
+         LEFT JOIN information_schema.key_column_usage k ON k.table_schema = c.table_schema AND k.table_name = c.table_name AND k.column_name = c.column_name
+          AND EXISTS (SELECT 1 FROM information_schema.table_constraints t WHERE t.constraint_schema = k.constraint_schema AND t.constraint_name = k.constraint_name AND t.table_name = k.table_name AND t.constraint_type = 'PRIMARY KEY')
+         WHERE c.table_schema = $1 AND c.table_name = $2 ORDER BY c.ordinal_position`, [schema, name], false);
+            const objects = await this.query("SELECT table_type FROM information_schema.tables WHERE table_schema = $1 AND table_name = $2", [schema, name], false);
+            return { writable: objects.rows[0]?.table_type === "BASE TABLE", columns: result.rows.map(column => ({ ...column, key: Number(column.key) })) };
+        }
         await this.setLocalDeadline();
         const columns = await this.query(`SELECT column_name AS name, data_type AS type,
               is_nullable = 'YES' AS nullable
@@ -472,7 +557,7 @@ class MySqlAdapter {
             throw error;
         }
     }
-    async write(sql, params) {
+    async write(sql, params, expectedRows) {
         if (this.readOnly)
             throw new Error("Connection is read-only.");
         let values;
@@ -490,13 +575,22 @@ class MySqlAdapter {
                 throw error;
             throw new AdapterWriteError(errorText(error), false);
         }
+        let committing = false;
         try {
             const [result] = await this.query(sql, values, true, true);
+            if (expectedRows === 1 && mysqlAffectedRows(result) !== 1)
+                throw new Error("ROW_CONFLICT: The row changed or no longer has a unique identity.");
+            committing = true;
             await this.query("COMMIT", [], true, false);
             return { affectedRows: mysqlAffectedRows(result) };
         }
         catch (error) {
-            await this.rollbackQuietly();
+            const rolledBack = await this.rollbackQuietly();
+            if (!committing && rolledBack) {
+                if (error instanceof AdapterExecutionError)
+                    throw new AdapterExecutionError(error.message, error.reason, false);
+                throw new AdapterWriteError(errorText(error), false);
+            }
             if (error instanceof AdapterExecutionError)
                 throw error;
             throw new AdapterWriteError(errorText(error), true);
@@ -525,6 +619,8 @@ class MySqlAdapter {
             for (const operation of operations) {
                 const [result] = await this.query(operation.sql, mysqlParams(parseJson(operation.parameters, `operation "${operation.id}" parameters`, isSqlParameters)), true, true);
                 results.push({ affectedRows: mysqlAffectedRows(result) });
+                if (operation.expectedRows === 1 && mysqlAffectedRows(result) !== 1)
+                    throw new Error("ROW_CONFLICT: The row changed or no longer has a unique identity.");
             }
         }
         catch (error) {
@@ -558,6 +654,62 @@ class MySqlAdapter {
             throw error;
         }
     }
+    async listObjects(filter) {
+        if (filter.kind && !["table", "view", "function", "trigger"].includes(filter.kind))
+            throw new Error(`MySQL does not support catalog kind "${filter.kind}".`);
+        const limit = catalogLimit(filter.limit);
+        const offset = catalogOffset(filter.offset);
+        const predicates = ["1=1"];
+        const params = [];
+        if (filter.kind) {
+            predicates.push("kind = ?");
+            params.push(filter.kind);
+        }
+        if (filter.schema) {
+            predicates.push("schema_name = ?");
+            params.push(filter.schema);
+        }
+        if (filter.search) {
+            predicates.push("name LIKE ? ESCAPE '\\\\'");
+            params.push(`%${escapeLike(filter.search)}%`);
+        }
+        const result = await this.read(`SELECT kind, schema_name AS schema, name, identity FROM (
+        SELECT CASE WHEN TABLE_TYPE='VIEW' THEN 'view' ELSE 'table' END AS kind, TABLE_SCHEMA AS schema_name,
+               TABLE_NAME AS name, CONCAT(TABLE_SCHEMA, '.', TABLE_NAME) AS identity
+        FROM information_schema.tables WHERE TABLE_SCHEMA=DATABASE()
+        UNION ALL
+        SELECT 'function', ROUTINE_SCHEMA, ROUTINE_NAME, CONCAT(ROUTINE_SCHEMA, '.', ROUTINE_NAME)
+        FROM information_schema.routines WHERE ROUTINE_SCHEMA=DATABASE() AND ROUTINE_TYPE='FUNCTION'
+        UNION ALL
+        SELECT 'trigger', TRIGGER_SCHEMA, TRIGGER_NAME, CONCAT(TRIGGER_SCHEMA, '.', EVENT_OBJECT_TABLE, '.', TRIGGER_NAME)
+        FROM information_schema.triggers WHERE TRIGGER_SCHEMA=DATABASE()
+      ) objects WHERE ${predicates.join(" AND ")} ORDER BY schema_name, kind, name, identity LIMIT ? OFFSET ?`, [...params, limit + 1, offset]);
+        return catalogPage(result.rows, limit, offset, ["table", "view", "function", "trigger"]);
+    }
+    async describeObject(object) {
+        const schema = object.schema ?? await this.databaseName();
+        if (object.kind === "function") {
+            const result = await this.read("SELECT ROUTINE_DEFINITION AS definition FROM information_schema.routines WHERE ROUTINE_SCHEMA=? AND ROUTINE_NAME=? AND ROUTINE_TYPE='FUNCTION'", [schema, object.name]);
+            if (!result.rows[0])
+                throw new Error("Catalog object was not found.");
+            return { object, definition: String(result.rows[0].definition ?? "") };
+        }
+        if (object.kind === "trigger") {
+            const result = await this.read("SELECT ACTION_STATEMENT AS definition FROM information_schema.triggers WHERE TRIGGER_SCHEMA=? AND TRIGGER_NAME=?", [schema, object.name]);
+            if (!result.rows[0])
+                throw new Error("Catalog object was not found.");
+            return { object, definition: String(result.rows[0].definition ?? "") };
+        }
+        if (object.kind === "view") {
+            const result = await this.read("SELECT VIEW_DEFINITION AS definition FROM information_schema.views WHERE TABLE_SCHEMA=? AND TABLE_NAME=?", [schema, object.name]);
+            if (!result.rows[0])
+                throw new Error("Catalog object was not found.");
+            return { object, definition: String(result.rows[0].definition ?? "") };
+        }
+        if (object.kind === "table")
+            return { object, definition: await this.inspect("table", `${schema}.${object.name}`) };
+        throw new Error(`MySQL does not support catalog kind "${object.kind}".`);
+    }
     async close() {
         if (this.closed)
             return;
@@ -584,6 +736,16 @@ class MySqlAdapter {
         const name = separator === -1 ? table : table.slice(separator + 1);
         if (!schema || !name)
             throw new Error(`Invalid table name "${table}".`);
+        if (kind === "editable") {
+            const [result] = await this.query(`SELECT c.COLUMN_NAME AS name, c.DATA_TYPE AS type, c.IS_NULLABLE = 'YES' AS nullable,
+          c.EXTRA LIKE '%GENERATED%' AS \`generated\`, COALESCE(k.ORDINAL_POSITION, 0) AS \`key\`
+         FROM information_schema.columns c LEFT JOIN information_schema.key_column_usage k
+          ON k.TABLE_SCHEMA = c.TABLE_SCHEMA AND k.TABLE_NAME = c.TABLE_NAME AND k.COLUMN_NAME = c.COLUMN_NAME AND k.CONSTRAINT_NAME = 'PRIMARY'
+         WHERE c.TABLE_SCHEMA = ? AND c.TABLE_NAME = ? ORDER BY c.ORDINAL_POSITION`, [schema, name], false, true);
+            const [objects] = await this.query("SELECT ENGINE AS engine FROM information_schema.tables WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?", [schema, name], false, true);
+            return { writable: String(mysqlRows(objects)[0]?.engine).toLowerCase() === "innodb",
+                columns: mysqlRows(result).map(column => ({ ...column, nullable: Boolean(column.nullable), generated: Boolean(column.generated), key: Number(column.key) })) };
+        }
         const [columnResult] = await this.query(`SELECT COLUMN_NAME AS name, DATA_TYPE AS type,
               IS_NULLABLE = 'YES' AS nullable
        FROM information_schema.columns
@@ -752,6 +914,44 @@ function postgresParams(params) {
         return params;
     throw new Error("PostgreSQL parameters must be a JSON array.");
 }
+function catalogLimit(value) {
+    const limit = value ?? 50;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 200)
+        throw new Error("Catalog limit must be 1-200.");
+    return limit;
+}
+function catalogOffset(value) {
+    const offset = value ?? 0;
+    if (typeof offset !== "number" || !Number.isSafeInteger(offset) || offset < 0 || offset > 1_000_000)
+        throw new Error("SQL catalog offset must be a non-negative integer at most 1000000.");
+    return offset;
+}
+function catalogPage(objects, limit, offset, supportedKinds) {
+    const more = objects.length > limit;
+    return { objects: objects.slice(0, limit), next_offset: more ? offset + limit : null, supported_kinds: supportedKinds };
+}
+function escapeLike(value) {
+    if (!value || value.length > 200 || value.includes("\0"))
+        throw new Error("Catalog search must be 1-200 characters.");
+    return value.replace(/[\\%_]/g, "\\$&");
+}
+function postgresCatalogFilter(filter) {
+    const predicates = [];
+    const params = [];
+    if (filter.kind) {
+        params.push(filter.kind);
+        predicates.push(`kind = $${params.length}`);
+    }
+    if (filter.schema) {
+        params.push(filter.schema);
+        predicates.push(`schema = $${params.length}`);
+    }
+    if (filter.search) {
+        params.push(`%${escapeLike(filter.search)}%`);
+        predicates.push(`name ILIKE $${params.length} ESCAPE '\\'`);
+    }
+    return { where: predicates.length ? `WHERE ${predicates.join(" AND ")}` : "", params };
+}
 function remainingMilliseconds(context) {
     return Math.max(1, Math.ceil(context.deadline - Date.now()));
 }

package/dist/src/cli.js

@@ -26,6 +26,12 @@ const parsed = parseArgs({
         "allow-destructive": { type: "boolean" },
         offset: { type: "string" },
         limit: { type: "string" },
+        cursor: { type: "string" },
+        schema: { type: "string" },
+        search: { type: "string" },
+        category: { type: "string" },
+        internal: { type: "boolean" },
+        external: { type: "boolean" },
         "timeout-ms": { type: "string" },
         "max-state-bytes": { type: "string" },
         "cache-ttl-seconds": { type: "string" },
@@ -163,6 +169,8 @@ async function dispatch() {
             return dispatchSession(subcommand, rest);
         case "mongo":
             return dispatchMongo(subcommand, rest);
+        case "redis":
+            return dispatchRedis(subcommand, rest);
         case "query":
             return stateql.query(sql, {
                 params,
@@ -199,6 +207,23 @@ async function dispatch() {
             return stateql.setAlias(requireValue(rest[0], "alias"), requireValue(rest[1], "result handle"));
         case "inspect":
             return stateql.inspect(normalizeInspectKind(requireValue(subcommand, "inspection kind")), rest[0]);
+        case "objects":
+            return stateql.listObjects({
+                ...(subcommand ? { kind: subcommand } : {}),
+                ...(values.schema ? { schema: values.schema } : {}),
+                ...(values.search ? { search: values.search } : {}),
+                offset: values.cursor ?? numberOption(values.offset, 0),
+                limit: numberOption(values.limit, 50),
+            });
+        case "object": {
+            const object = {
+                kind: requireValue(subcommand, "object kind"),
+                name: requireValue(rest[0], "object name"),
+                ...(values.schema ? { schema: values.schema } : {}),
+                ...(rest[1] ? { identity: rest[1] } : {}),
+            };
+            return stateql.describeObject(object);
+        }
         case "transaction":
             return dispatchTransaction(subcommand, rest[0]);
         case "plan":
@@ -212,7 +237,13 @@ async function dispatch() {
         case "apply":
             return stateql.apply(requireValue(subcommand, "plan handle"));
         case "history":
-            return stateql.history(numberOption(values.limit, 20));
+            if (values.internal && values.external)
+                throw new Error("--internal and --external are mutually exclusive.");
+            return stateql.history(numberOption(values.limit, 20), {
+                ...(values.category ? { category: values.category } : {}),
+                ...(values.internal ? { internal: true } : values.external ? { internal: false } : {}),
+                offset: numberOption(values.offset, 0),
+            });
         case "receipt":
             return stateql.receipt(requireValue(subcommand, "operation handle"));
         case "doctor":
@@ -252,6 +283,26 @@ async function dispatchMongo(action, args) {
             throw new Error(`Unknown MongoDB command "${action ?? ""}".`);
     }
 }
+async function dispatchRedis(action, args) {
+    const payload = parseRedisCommand(requireValue(args.join(" ").trim(), "Redis JSON command"));
+    switch (action) {
+        case "query": return stateql.redisQuery(payload, { cache: cacheMode(values.cache) });
+        case "exec": return stateql.redisExec(payload, { replay: values.replay ?? false, ...(values["idempotency-key"] ? { idempotencyKey: values["idempotency-key"] } : {}) });
+        case "plan": return stateql.redisPlan(payload);
+        default: throw new Error(`Unknown Redis command "${action ?? ""}".`);
+    }
+}
+function parseRedisCommand(value) {
+    try {
+        const parsed = JSON.parse(value);
+        if (!parsed || typeof parsed !== "object")
+            throw new Error();
+        return parsed;
+    }
+    catch {
+        throw new Error("Invalid Redis JSON command.");
+    }
+}
 function parseMongoCommand(value) {
     try {
         return BSON.EJSON.parse(value, { relaxed: false });
@@ -287,6 +338,15 @@ async function dispatchProfile(action, args) {
                 ...(values["credential-ref"] ? { credentialRef: values["credential-ref"] } : {}),
                 readOnly: !values["read-write"],
             });
+        case "update":
+            if (values["read-only"] && values["read-write"])
+                throw new Error("--read-only and --read-write are mutually exclusive.");
+            return stateql.updateProfile(requireValue(args[0], "profile name"), {
+                ...(args[1] !== undefined ? { target: args[1] } : {}),
+                ...(values.env ? { secretEnv: values.env } : {}),
+                ...(values["credential-ref"] ? { credentialRef: values["credential-ref"] } : {}),
+                ...(values["read-only"] ? { readOnly: true } : values["read-write"] ? { readOnly: false } : {}),
+            });
         case "list":
             return stateql.listProfiles();
         case "show":
@@ -581,14 +641,17 @@ Usage: stql <command> [arguments] [options]
 Commands:
   connect TARGET | --env ENV | --credential-ref REF | --profile NAME
   disconnect, status
-  profile add NAME [TARGET | --env ENV | --credential-ref REF]
+  profile add|update NAME [TARGET | --env ENV | --credential-ref REF]
   profile list|show|remove
   query, filter, exec, show, rows, count, columns, export
   mongo query|exec|plan '<EJSON command>'
+  redis query|exec|plan '<JSON command>'
   alias set
   inspect schema|table|collection|collections|columns|indexes|constraints
+  objects [KIND] [--schema NAME] [--search TEXT] [--offset N|--cursor CURSOR]
+  object KIND NAME [IDENTITY] [--schema NAME]
   transaction begin|status|commit|rollback
-  plan, apply, history, receipt, doctor, purge, capabilities
+  plan, apply, history [--category CATEGORY] [--internal|--external], receipt, doctor, purge, capabilities
   batch [file.json|file.jsonl|-]
   pipe
 

package/dist/src/connection.d.ts

@@ -3,6 +3,7 @@ import type { CredentialSource, Driver, StateConfidence } from "./types.js";
 export declare function databaseIdentity(connection: ConnectionRecord): unknown;
 export declare function detectDriver(target: string): Driver;
 export declare function mongoDatabaseName(target: string): string;
+export declare function redisDatabaseName(target: string): string;
 export declare function credentialSource(value: string, expectedDriver?: Driver, referenceSource?: CredentialSource): {
     driver: Driver;
     source: string;