@fadhilp/stateql 0.9.0 → 0.10.1

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,148 @@ 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.
+
+Connections likewise retain canonical `conn_*` IDs and receive persistent random
+10-character lowercase base32 aliases, exposed as `alias` and `display_alias` by
+`connect()` and `snapshot().connection` (optional in snapshot types for older
+producers). Connection aliases are unique within the state store, allocated
+atomically with the connection, and backfilled for existing records on startup.
+They survive reopening; reconnecting creates a new ID and alias. They are display
+identities only, separate from result aliases; internal references and lookups
+continue to use canonical connection IDs.
+
+### 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;
@@ -30,9 +33,11 @@ export interface Adapter {
     ping(): Promise<void>;
     read(sql: string, params: SqlParameters): Promise<ReadResult>;
     write(sql: string, params: SqlParameters, expectedRows?: 1): Promise<WriteResult>;
-    writeBatch(operations: OperationRecord[], isolation: string): 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 {
@@ -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;
@@ -306,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) {
@@ -340,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);
@@ -548,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) {
@@ -581,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;
@@ -785,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;

package/dist/src/connection.js

@@ -16,8 +16,10 @@ export function detectDriver(target) {
         return "mysql";
     if (/^mongodb(?:\+srv)?:\/\//i.test(target))
         return "mongodb";
+    if (/^rediss?:\/\//i.test(target))
+        return "redis";
     if (/^[a-z][a-z\d+.-]*:\/\//i.test(target)) {
-        throw new StateQLError("UNSUPPORTED_DRIVER", "Only MongoDB, MySQL, PostgreSQL, and SQLite are supported.");
+        throw new StateQLError("UNSUPPORTED_DRIVER", "Only MongoDB, MySQL, PostgreSQL, Redis, and SQLite are supported.");
     }
     return "sqlite";
 }
@@ -44,6 +46,20 @@ export function mongoDatabaseName(target) {
     }
     throw new StateQLError("INVALID_COMMAND", "MongoDB URL must include an explicit database name.");
 }
+export function redisDatabaseName(target) {
+    try {
+        const url = new URL(target);
+        if (!url.hostname || !["redis:", "rediss:"].includes(url.protocol.toLowerCase()))
+            throw new Error();
+        const path = url.pathname.replace(/^\//, "");
+        if (path && !/^\d+$/.test(path))
+            throw new Error();
+        return `db${path || "0"}`;
+    }
+    catch {
+        throw new StateQLError("INVALID_COMMAND", "Invalid Redis URL or database number.");
+    }
+}
 export function credentialSource(value, expectedDriver, referenceSource = "secret_env") {
     const sourceLabel = referenceSource === "credential_ref"
         ? "Credential reference"
@@ -51,7 +67,7 @@ export function credentialSource(value, expectedDriver, referenceSource = "secre
     const explicitSqlite = /^sqlite:(?!\/\/)/i.test(value);
     const driver = explicitSqlite ? "sqlite" : detectDriver(value);
     if (driver === "sqlite" && (!explicitSqlite || value.length === 7)) {
-        throw new StateQLError("INVALID_COMMAND", `${sourceLabel} must contain a complete PostgreSQL/MySQL URL or an explicit sqlite: source; MongoDB URLs are also supported.`, {
+        throw new StateQLError("INVALID_COMMAND", `${sourceLabel} must contain a complete PostgreSQL/MySQL/Redis URL or an explicit sqlite: source; MongoDB URLs are also supported.`, {
             suggestedAction: "Store the full database URL, or prefix an SQLite path with sqlite:.",
         });
     }

package/dist/src/index.d.ts

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

package/dist/src/migrations.js

@@ -85,6 +85,47 @@ const MIGRATIONS = [
         apply(db) { addColumn(db, "history", "target", "TEXT"); },
         validate(db) { requireColumns(db, "history", ["target"]); },
     },
+    {
+        name: "generated_aliases_v1",
+        apply(db) {
+            addColumn(db, "aliases", "generated", "INTEGER NOT NULL DEFAULT 0");
+            db.exec("CREATE UNIQUE INDEX IF NOT EXISTS aliases_generated_result ON aliases(result_id) WHERE generated = 1");
+        },
+        validate(db) {
+            requireColumns(db, "aliases", ["generated"]);
+            requireIndexes(db, ["aliases_generated_result"]);
+        },
+    },
+    {
+        name: "history_classification_v1",
+        apply(db) {
+            addColumn(db, "history", "category", "TEXT NOT NULL DEFAULT 'management'");
+            addColumn(db, "history", "internal", "INTEGER NOT NULL DEFAULT 0");
+            db.exec(`
+        UPDATE history SET category = 'statement'
+        WHERE category = 'management' AND command IN
+          ('query','exec','plan','apply','filter','mongo.query','mongo.exec','mongo.plan','redis.query','redis.exec','redis.plan');
+        UPDATE history SET category = 'introspection'
+        WHERE category = 'management' AND (command LIKE 'inspect.%' OR command IN ('objects.list','object.describe','table.read'));
+      `);
+            db.exec("CREATE INDEX IF NOT EXISTS history_session_category ON history(session_id, category, internal)");
+        },
+        validate(db) {
+            requireColumns(db, "history", ["category", "internal"]);
+            requireIndexes(db, ["history_session_category"]);
+        },
+    },
+    {
+        name: "connection_aliases_v1",
+        apply(db) {
+            addColumn(db, "connections", "alias", "TEXT");
+            db.exec("CREATE UNIQUE INDEX IF NOT EXISTS connections_alias ON connections(alias)");
+        },
+        validate(db) {
+            requireColumns(db, "connections", ["alias"]);
+            requireIndexes(db, ["connections_alias"]);
+        },
+    },
 ];
 export function runMigrations(db, now) {
     db.exec(`
@@ -186,6 +227,7 @@ function createInitialSchema(db) {
       session_id TEXT NOT NULL,
       name TEXT NOT NULL,
       result_id TEXT NOT NULL,
+      generated INTEGER NOT NULL DEFAULT 0,
       PRIMARY KEY(session_id, name),
       FOREIGN KEY(result_id) REFERENCES results(id)
     );
@@ -249,6 +291,8 @@ function createInitialSchema(db) {
       actor_id TEXT NOT NULL,
       command TEXT NOT NULL,
       origin TEXT NOT NULL DEFAULT 'legacy',
+      category TEXT NOT NULL DEFAULT 'management',
+      internal INTEGER NOT NULL DEFAULT 0,
       sql TEXT,
       handle TEXT,
       executed INTEGER NOT NULL,