@fadhilp/stateql 0.4.2 → 0.4.4

package/README.md

@@ -1,20 +1,28 @@
 # StateQL
 
-StateQL is a stateful database CLI for AI agents and automation. It provides a
-safe interface for querying, changing, and inspecting databases while keeping
-results reusable and operations traceable across commands.
+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, and MySQL databases while keeping results reusable and
+operations traceable across commands.
+
+StateQL is built around durable handles:
+
+1. Run a query and receive a result handle such as `q_1`.
+2. Reuse, filter, page, count, alias, or export that stored result without
+   rerunning the original SQL.
+3. Use operation, plan, and transaction handles to inspect and control writes.
 
 Requires Node.js 22.5 or newer.
 
 ## Quick start
 
+Install the CLI:
+
 ```bash
 npm install -g @fadhilp/stateql
 ```
 
-Connect to an existing SQLite database, then run a filtered, parameterized
-query. Parameters keep values separate from SQL; `ORDER BY` makes paging
-stable, while `LIMIT` bounds work at the database.
+Connect to an existing SQLite database and run a bounded, parameterized query:
 
 ```bash
 export STQL_SESSION=audit
@@ -27,14 +35,16 @@ stql query \
   --param 2026-01-01
 ```
 
-Example output:
+Parameters keep values separate from SQL. `ORDER BY` makes paging stable, and
+`LIMIT` bounds work at the database. The default `agent` output is compact,
+one-line JSON:
 
 ```json
 {"ok":true,"handle":"q_1","rows":[{"id":7,"name":"Ada","email":"ada@example.com"},{"id":12,"name":"Grace","email":"grace@example.com"},{"id":18,"name":"Linus","email":"linus@kernel.org"}],"truncated":false,"cached":false,"total":3,"next_offset":null}
 ```
 
-`q_1` is a durable result handle. Filter its stored snapshot without querying
-the original database; the result becomes another durable handle:
+`q_1` is a durable snapshot. Filter it locally without accessing the original
+database:
 
 ```bash
 stql filter q_1 "email LIKE ?" --param "%@example.com"
@@ -44,8 +54,8 @@ stql filter q_1 "email LIKE ?" --param "%@example.com"
 {"ok":true,"handle":"q_2","rows":[{"id":7,"name":"Ada","email":"ada@example.com"},{"id":12,"name":"Grace","email":"grace@example.com"}],"truncated":false,"cached":false,"total":2,"next_offset":null}
 ```
 
-Give the derived result a readable alias, page through it, inspect its count,
-or export it—all without rerunning SQL:
+The filtered snapshot receives its own handle. Give it a readable alias, page
+through it, inspect its count, or export it without rerunning SQL:
 
 ```bash
 stql alias set example-users q_2
@@ -62,7 +72,22 @@ Example first page:
 ```
 
 Running the same normalized query with the same parameters reuses `q_1` while
-its cache is valid. Use `--cache bypass` when a fresh read is required.
+its cache entry is valid. Use `--cache bypass` when a fresh read is required.
+
+## Connections and profiles
+
+A connection accepts exactly one source: a direct target, `--env`, or
+`--profile`.
+
+```bash
+stql connect <sqlite-path|postgres-url|mysql-url> [--name NAME] [--read-write]
+stql connect --env ENV [--name NAME] [--read-write]
+stql connect --profile NAME
+stql disconnect
+stql status
+```
+
+### Environment-backed credentials
 
 PostgreSQL and MySQL credentials should come from environment variables. The
 variable must contain the complete connection URL, not only its password.
@@ -79,21 +104,45 @@ export SQLITE_DATABASE='sqlite:./app.sqlite'
 stql connect --env SQLITE_DATABASE --name local --read-only
 ```
 
-A connection accepts exactly one direct target, `--env`, or `--profile` source.
-For PostgreSQL, StateQL preserves strict TLS verification by normalizing
-`sslmode=prefer`, `require`, and `verify-ca` to `verify-full` before opening the
-adapter. Use `sslmode=verify-full` explicitly for clarity. Setting
-`uselibpqcompat=true` opts out and keeps libpq-compatible SSL semantics.
+StateQL stores no PostgreSQL or MySQL password. Credential-bearing URLs must be
+supplied through `--env`. SQLite paths remain persisted as connection metadata.
+
+### Local profiles
+
+Profiles store connection targets, read-only policy, and environment-variable
+names. Credential values are never stored. Profiles persist under `STQL_HOME`
+with other StateQL metadata.
+
+```bash
+stql profile add local ./app.sqlite --read-write
+stql profile add production --env PROD_DATABASE_URL --read-only
+stql profile list
+stql profile show production
+stql connect local
+stql connect --profile production
+```
+
+A bare connection target matching a profile name resolves to that profile;
+otherwise it remains a path or database URL.
+
+### Driver notes
 
-MySQL uses positional `?` parameters. MariaDB compatibility is not currently
-claimed.
+- **SQLite:** use a filesystem path for direct connections or `sqlite:` for an
+  environment-backed path.
+- **PostgreSQL:** StateQL preserves strict TLS verification by normalizing
+  `sslmode=prefer`, `require`, and `verify-ca` to `verify-full` before opening
+  the adapter. Use `sslmode=verify-full` explicitly for clarity. Setting
+  `uselibpqcompat=true` opts out and keeps libpq-compatible SSL semantics.
+- **MySQL:** uses positional `?` parameters. MariaDB compatibility is not
+  currently claimed.
 
-## Commands
+## CLI reference
 
 ```text
 stql connect <sqlite-path|postgres-url|mysql-url> [--name NAME] [--read-write]
 stql connect --env ENV [--name NAME] [--read-write]
 stql connect --profile NAME
+stql disconnect
 stql status
 stql profile add|list|show|remove
 stql session start|list|show|summary|close
@@ -103,6 +152,7 @@ stql exec <sql> [--params JSON | --param VALUE...] [--idempotency-key KEY] [--re
               [--allow-unbounded] [--allow-destructive]
 stql show|count|columns <result-handle>
 stql rows <result-handle> [--offset N] [--limit N]
+stql alias set <name> <result-handle>
 stql export <result-handle> --output FILE [--format json|jsonl|csv]
 stql inspect schema|table|columns|indexes|constraints [table]
 stql transaction begin|status|commit|rollback [--isolation LEVEL]
@@ -115,56 +165,128 @@ stql batch [commands.json|commands.jsonl|-] [--continue-on-error]
 stql pipe [--continue-on-error]
 ```
 
-Database commands accept `--timeout-ms N`; default is 30,000 ms. `Ctrl+C`
-cancels active work. SQLite runs in a killable child process so long synchronous
-statements cannot block StateQL's event loop. PostgreSQL uses server-side
-`statement_timeout` plus client deadlines. MySQL deadlines destroy the active
-connection. A timed-out write may return `OUTCOME_UNKNOWN` when commit status
-cannot be proven.
+### SQL parameters
 
-## Output modes
+For shell-safe positional parameters, repeat `--param`. JSON scalars become
+their native types; other values remain strings.
 
-CLI output defaults to compact, one-line `agent` JSON. Successes flatten useful
-data and expose the primary durable ID as `handle`; errors retain their complete
-error object. Empty warnings and tracing metadata are omitted.
+```powershell
+stql exec "INSERT INTO users (name, status) VALUES (?, ?)" `
+  --param Ada --param trial
+```
+
+Use `--params JSON` for a JSON array or named parameters. Use
+`--params-file FILE` when JSON is awkward to quote; `--params-file -` reads
+JSON from standard input.
+
+### Output modes
+
+CLI output defaults to compact, one-line `agent` JSON. Successful responses
+flatten useful data and expose the primary durable ID as `handle`. Errors retain
+their complete error object. Empty warnings and tracing metadata are omitted.
 
 ```json
 {"ok":false,"error":{"code":"UNBOUNDED_MUTATION","message":"Mutation has no WHERE clause.","retryable":false,"executed":false,"override_flag":"--allow-unbounded"}}
 ```
 
-Use `--output json` for the original pretty, verbose envelope, or
-`--output jsonl` for that envelope on one line. `--output text` prints a short
-human status; `--output silent` prints only a successful handle. Set
-`STQL_OUTPUT` to choose a mode globally. For `export`, `--output` names the
-file, so use `STQL_OUTPUT` to choose its response mode. Library responses keep
-the full envelope regardless of CLI mode.
+Other modes are:
 
-For shell-safe positional parameters, repeat `--param`. JSON scalars become
-their native types; other values remain strings.
+- `--output json`: original pretty, verbose envelope.
+- `--output jsonl`: verbose envelope on one line.
+- `--output text`: short human-readable status.
+- `--output silent`: only a successful handle.
 
-```powershell
-stql exec "INSERT INTO users (name, status) VALUES (?, ?)" `
-  --param Ada --param trial
-```
+Set `STQL_OUTPUT` to choose a mode globally. For `export`, `--output` names the
+file, so use `STQL_OUTPUT` to choose the command's response mode. Library
+responses always keep the full envelope.
+
+### Deadlines and cancellation
+
+Database commands accept `--timeout-ms N`; the default is 30,000 ms. `Ctrl+C`
+cancels active work.
+
+- SQLite runs in a killable child process so long synchronous statements cannot
+  block StateQL's event loop.
+- PostgreSQL combines server-side `statement_timeout` with client deadlines.
+- MySQL deadlines destroy the active connection.
+
+A timed-out write may return `OUTCOME_UNKNOWN` when its commit status cannot be
+proven.
+
+## Durable state and result reuse
+
+State metadata lives under `STQL_HOME`, or the platform data directory when
+unset. StateQL keeps connections, sessions, handles, aliases, cache entries,
+plans, transactions, history, and receipts available across CLI invocations.
+
+### Sessions and actors
+
+Set `STQL_SESSION` to select a named session and `STQL_ACTOR` to select an
+attached actor. A session is a shared workspace: attached actors reuse its
+connection, handles, aliases, cache, and state version. Plans and staged
+transactions remain owned by the actor that created them.
+
+Callers that omit `actor` keep the legacy behavior where the actor ID is the
+session name.
 
-Use `--params-file FILE` for arrays or named parameters that are awkward to
-quote. `--params-file -` reads JSON from standard input.
+### Result lifetime and limits
 
-## Local profiles
+SQLite result rows are materialized locally for durable access. Read cache
+entries expire after five minutes, and materialized handles expire after 24
+hours. Expired results and plans are deleted the next time StateQL opens.
 
-Profiles persist under `STQL_HOME` with other StateQL metadata.
+Queries exceeding 10,000 rows or 16 MiB of serialized row data fail before
+persistence. Narrow the `WHERE` clause, add `LIMIT`, or select fewer columns.
+These caps bound persisted materialization; the independent deadline bounds
+execution time.
+
+Command history keeps the latest 10,000 entries per session. SQLite cache reuse
+also checks the database file signature. PostgreSQL and MySQL cache reuse is
+labeled `ttl_based` and is never authoritative.
+
+### Local filtering
+
+`filter` evaluates one scalar SQLite predicate against a stored result. It
+preserves source order, state metadata, and expiry, and never accesses the
+original database.
+
+Use parameters for values. Subqueries, query-shaping clauses, and
+non-allowlisted functions are rejected. Common deterministic functions such as
+`lower`, `upper`, `length`, and `coalesce` are supported.
+
+## Write safety
+
+Destructive and unbounded operations require `--allow-destructive` and
+`--allow-unbounded`, respectively. The flags are independent.
+
+`plan` validates and stores a write for later application. A plan persists only
+the flags explicitly supplied when it is created; `apply` never adds
+authorization.
+
+Use an idempotency key to protect retryable writes from duplicate execution:
 
 ```bash
-stql profile add local ./app.sqlite --read-write
-stql profile add production --env PROD_DATABASE_URL --read-only
-stql profile list
-stql connect local
-stql connect --profile production
+stql exec "UPDATE jobs SET claimed = 1 WHERE id = ?" \
+  --param 42 \
+  --idempotency-key claim-job-42
 ```
 
-A bare connection target matching a profile name resolves to that profile;
-otherwise it remains a path or database URL. Profiles store targets, read-only
-policy, and environment-variable names. Credential values are never stored.
+If a write starts but StateQL cannot safely record its final outcome, it returns
+`OUTCOME_UNKNOWN` and blocks automatic replay. Inspect database state before
+using `--replay`. Interrupted commits remain fail-closed; stale `committing`
+records become `outcome_unknown` after five minutes.
+
+### Transactions
+
+Transactions are staged in local state so they survive CLI invocations, then
+executed atomically on commit. While a transaction is active, StateQL rejects
+database reads, plans, connection changes, and disconnects. Commit or roll back
+first.
+
+SQLite supports `serializable`. PostgreSQL and MySQL also support
+`repeatable read`, `read committed`, and `read uncommitted`. Server reads run
+inside database-enforced read-only transactions. MySQL staged transactions
+reject DDL because MySQL implicitly commits those statements.
 
 ## Batch and pipes
 
@@ -173,6 +295,8 @@ policy, and environment-variable names. Credential values are never stored.
 the first error unless `--continue-on-error` is set. Output defaults to one
 compact `agent` JSON object per line.
 
+Pipe commands directly:
+
 ```bash
 printf '%s\n' \
   '{"command":"query","sql":"SELECT id, email FROM users ORDER BY id","as":"users"}' \
@@ -181,6 +305,8 @@ printf '%s\n' \
   stql pipe
 ```
 
+Or save a JSON array as `commands.json`:
+
 ```json
 [
   {
@@ -197,55 +323,21 @@ printf '%s\n' \
 ]
 ```
 
-Run the array with `stql batch commands.json`. Batch fields use snake case;
-supported command names match CLI paths, such as `filter`,
-`transaction.begin`, `session.summary`, `alias.set`, `plan`, and `apply`.
-Batch filters use `where` for the predicate and may assign the derived result
-with `as`. Database commands may set `timeout_ms`; otherwise they use the
-30-second default.
-
-State metadata lives under `STQL_HOME`, or the platform data directory when
-unset. Set `STQL_SESSION` to select a named session and `STQL_ACTOR` to select
-an attached actor for CLI invocations. A session is a shared workspace:
-attached actors reuse its connection, handles, aliases, cache, and
-state version, while plans and staged transactions remain owned by their
-creating actor. Callers that omit `actor` keep the legacy behavior where the
-actor ID is the session name.
-
-Read cache entries expire after five minutes; materialized handles expire after
-24 hours. Expired results and plans are deleted when StateQL next opens. Queries
-exceeding 10,000 rows or 16 MiB of serialized row data fail before persistence;
-add a narrower `WHERE` clause, `LIMIT`, or smaller column selection. These caps
-bound persisted materialization, while the independent deadline bounds execution
-time. Command history keeps the latest 10,000 entries per session. SQLite cache reuse also checks
-the database file signature; PostgreSQL and MySQL reuse is labeled `ttl_based`,
-never authoritative. Transactions are staged in local state so they survive CLI
-invocations, then executed atomically on commit. Database reads, plans,
-connection changes, and disconnects are rejected while a transaction is active;
-commit or roll back first. SQLite supports `serializable`;
-PostgreSQL and MySQL also support `repeatable read`, `read committed`, and
-`read uncommitted`. Server reads run inside database-enforced read-only
-transactions. MySQL staged transactions reject DDL because MySQL implicitly
-commits those statements.
+```bash
+stql batch commands.json
+```
 
-StateQL stores no PostgreSQL or MySQL password. Credential-bearing URLs must be
-supplied through `--env`. SQLite result rows are materialized locally for
-durable access.
-`filter` evaluates one scalar SQLite predicate against those stored rows, keeps
-source order, state metadata, and expiry, and never accesses the original
-database. Use parameters for values. Subqueries, query-shaping clauses, and
-non-allowlisted functions are rejected; common deterministic functions such as
-`lower`, `upper`, `length`, and `coalesce` are supported.
+Batch fields use snake case. Supported command names match CLI paths, such as
+`filter`, `transaction.begin`, `session.summary`, `alias.set`, `plan`, and
+`apply`. Batch filters use `where` for the predicate and may assign the derived
+result with `as`. Database commands may set `timeout_ms`; otherwise they use the
+30-second default.
 
-Destructive and unbounded operations require their respective flags
-independently. Plans persist only flags explicitly supplied when the plan is
-created; `apply` never adds authorization. If a database write starts but its
-final outcome cannot be recorded safely, StateQL returns `OUTCOME_UNKNOWN` and
-blocks automatic replay. Inspect database state before using `--replay`.
-Interrupted commits remain fail-closed; stale `committing` records become
-`outcome_unknown` after five minutes.
+## TypeScript library
 
-## Library
+The package exports the same stateful operations for programmatic use. Library
+responses retain the full response envelope regardless of the configured CLI
+output mode.
 
 ```ts
 import { StateQL } from "@fadhilp/stateql";
@@ -256,11 +348,13 @@ const stateql = StateQL.forActor({
   timeoutMs: 30_000,
   maxResultBytes: 16 * 1024 * 1024,
 });
+
 const controller = new AbortController();
 const response = await stateql.query("SELECT * FROM users", {
   signal: controller.signal,
   timeoutMs: 5_000,
 });
+
 if (response.ok) {
   const handle = (response.data as { result_id: string }).result_id;
   await stateql.filter(handle, "email LIKE ?", {
@@ -269,6 +363,19 @@ if (response.ok) {
 }
 ```
 
+### Actor workspaces
+
+`StateQL.forActor(...)` resolves the actor's attached session directly from
+StateQL storage, avoiding a duplicate actor-to-session mapping in integrations.
+On first use, it creates a legacy-compatible session named after the actor. Use
+`new StateQL({ session, actor })` when the session is already known.
+
+Membership is managed only through the library API, not batch commands:
+`linkActor(session, actorId)`, `unlinkActor(session, actorId)`,
+`listActors(session)`, and `resolveActor(actorId)`. An existing member must link
+an actor before that actor opens an existing workspace. Integrations should ask
+for user confirmation before changing membership or the shared connection.
+
 ### Harness credential resolution
 
 Library integrations can resolve a profile's credential reference through a
@@ -292,6 +399,7 @@ async function resolveCredential(
     access: request.access,
     signal: request.signal,
   });
+
   if (approved.denied) throw new CredentialResolutionError("denied");
   return approved.value;
 }
@@ -302,39 +410,31 @@ const stateql = StateQL.forActor({
 });
 ```
 
-When no custom resolver is configured, StateQL continues to read references
-from `process.env`. A configured resolver is authoritative: returning
-`undefined` produces `CREDENTIAL_UNAVAILABLE` and never falls back to the
-process environment. Resolvers may throw `CredentialResolutionError` with
-`denied`, `cancelled`, `timeout`, or `unavailable` to produce controlled,
-secret-free failures. Unknown resolver errors are replaced with a generic
+When no custom resolver is configured, StateQL reads references from
+`process.env`. A configured resolver is authoritative: returning `undefined`
+produces `CREDENTIAL_UNAVAILABLE` and never falls back to the process
+environment. Resolvers may throw `CredentialResolutionError` with `denied`,
+`cancelled`, `timeout`, or `unavailable` to produce controlled, secret-free
+failures. Unknown resolver errors are replaced with a generic
 `CREDENTIAL_RESOLUTION_FAILED` response.
 
 StateQL calls the resolver only immediately before database access, after SQL
-safety and duplicate checks. Requests contain actor/session identity, the
+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 URLs or
-explicit `sqlite:` sources. StateQL validates the source and its stored driver
-before adapter construction, and normalizes SQLite paths. Credential-bearing
-PostgreSQL and MySQL URLs are redacted before connection
-metadata is persisted and never enter history, snapshots, cache keys, or
-responses. SQLite paths remain persisted connection metadata, as they are for
-direct SQLite connections. Harnesses remain responsible for approval policy,
-binding lifetime, revocation, and keeping values out of their own logs and
-model-visible data.
+connection metadata.
+
+Returned values must be complete PostgreSQL or MySQL URLs, or explicit
+`sqlite:` sources. StateQL validates the source and its stored driver before
+adapter construction and normalizes SQLite paths. Credential-bearing
+PostgreSQL and MySQL URLs are redacted before connection metadata is persisted
+and never enter history, snapshots, cache keys, or responses. SQLite paths
+remain persisted connection metadata, as they are for direct SQLite
+connections.
+
+Harnesses remain responsible for approval policy, binding lifetime, revocation,
+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.
-
-`StateQL.forActor(...)` resolves the actor's attached session directly from
-StateQL storage, avoiding a duplicate actor-to-session mapping in integrations.
-On first use, it creates a legacy-compatible session named after the actor.
-Use `new StateQL({ session, actor })` when the session is already known.
-
-Membership is managed only through the library API, not batch commands:
-`linkActor(session, actorId)`, `unlinkActor(session, actorId)`,
-`listActors(session)`, and `resolveActor(actorId)`. An existing member must link
-an actor before that actor opens an existing workspace. Integrations should ask
-for user confirmation before changing membership or the shared connection.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fadhilp/stateql",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Stateful, agent-oriented database CLI for safe result reuse",
   "repository": {
     "type": "git",