@carllee1983/dbcli 1.52.1 → 1.54.0

package/skills/dbcli/reference.md

@@ -38,6 +38,7 @@ never the right move.
 [check](#check) ·
 [diff](#diff) ·
 [design](#design) ·
+[impact assess](#impact-assess) ·
 [snapshot](#snapshot) ·
 [assert](#assert) ·
 [proxy](#proxy) ·
@@ -51,12 +52,14 @@ never the right move.
 [verify](#verify) ·
 [verification](#verification) ·
 [backfill](#backfill) ·
+[evidence](#evidence) ·
 [doctor](#doctor) ·
 [completion](#completion) ·
 [upgrade](#upgrade) ·
 [shell](#dbcli-shell) ·
 [migrate](#migrate) ·
 [semantic](#semantic) ·
+[contract](#contract) ·
 [skill](#skill) ·
 [skill context](#skill-context) ·
 [skill tasks](#skill-tasks-agent-task-packs)
@@ -80,13 +83,16 @@ command-level option is only valid after the command that declares it.
 | `--global` | Select the user-global registry at `~/.config/dbcli/config.json` instead of the current project's `.dbcli` config. Place it before the command path. |
 | `--use <connection>` | Select a named connection for this invocation; place it before the command path unless that command explicitly lists a command-level `--use`. |
 | `--timeout <ms>` | Connection timeout in milliseconds (integer, 100–600000), overriding the connection config's `timeout` field for this invocation. Applies to every engine adapter. Without either the flag or the config field, adapters fall back to their built-in 5000ms default. |
+| `--statement-timeout <ms>` | How long a single statement may run, in milliseconds (integer, 0–3600000; `0` removes the limit), overriding the connection config's `statementTimeout` field. Independent of the connection timeout — raising it does not slow down detection of an unreachable host. Falls back to `--timeout` when unset, and to the server's own setting when neither is given. |
 
 `--timeout` is applied only when the adapter is constructed for this invocation — it is
 never written back to `config.json`. Set the connection's `timeout` field instead for a
-value that persists across runs. On PostgreSQL, the same value is also used as the
-session's `statement_timeout` (not just the connection timeout), so a low value can cut
-off a long-running query with an error that looks like a connection timeout; the 100ms
-floor exists specifically to keep that failure mode from being too easy to trigger.
+value that persists across runs. `--timeout` caps statement time as well as connection time, so a
+low value cuts off a long-running query with an error that reads like a connection
+problem; the 100ms floor exists specifically to keep that failure mode from being too
+easy to trigger. Use `--statement-timeout` when only the statement limit should change.
+With neither flag, dbcli sets no statement limit at all — the server's setting decides,
+so a query that runs longer than the connection timeout is no longer cut off.
 Elasticsearch applies its timeout per request rather than once for the whole connection.
 The `timeout` field itself always takes a literal number — unlike other connection
 fields, it does not accept an `{"$env": "..."}` reference.
@@ -217,8 +223,8 @@ dbcli list --include-system        # Elasticsearch: include `.system` indices
 **Permission:** query-only+
 
 > **MongoDB:** Lists collections with estimated document count.
-> **Redis:** Returns up to 100 000 keys via `SCAN MATCH * COUNT 1000`. The header reads `Keys in db <n> (redis):` where `<n>` is the logical DB index.
-> **Elasticsearch:** Returns indices with `documentCount` from `/_stats/docs`; aliases are tagged separately. System indices (names starting with `.`) are hidden unless `--include-system` is passed.
+> **Redis:** Samples the first 1 000 keys scanned via `SCAN MATCH * COUNT 1000`, applying the blacklist during the scan. When the keyspace is larger, table output adds a `Sampled the first 1000 keys scanned` line and JSON output carries `sampled: true` with `sampleLimit`. The header reads `Keys in db <n> (redis):` where `<n>` is the logical DB index.
+> **Elasticsearch:** Returns indices with `documentCount` from one `/_cat/indices?h=index,docs.count&expand_wildcards=all` request (open and closed indices alike). The count is primaries-only, so a replicated index no longer reports its replica copies as extra documents. Aliases are tagged separately. System indices (names starting with `.`) are hidden unless `--include-system` is passed.
 
 ### schema
 
@@ -240,6 +246,13 @@ dbcli schema --use prod             # Scan prod DB; saves to .dbcli/schemas/prod
 **Options:** `--format <table|json>`, `--refresh`, `--reset`, `--force`, `--use <connection>`, `--sample-size <n>` (mongo only), `--sample-method <random|natural>` (mongo only)
 **Permission:** query-only+
 
+> **Row counts on a full scan:** scanning every table records
+> `rowCountIsEstimate: true` and reports the engine's row *estimate* (`information_schema.TABLES.TABLE_ROWS` on MySQL/MariaDB,
+> `pg_class.reltuples` on PostgreSQL) rather than running `COUNT(*)` per table —
+> a hundred full-table counts is what made scanning a large database unusable.
+> `dbcli schema <table>` on a single table still reports the exact count. Tables
+> are scanned with bounded parallelism (4 at a time).
+
 **Schema storage (v1.4+):** Schema is persisted as layered files under `.dbcli/schemas/`. With v2 multi-connection config each connection gets its own subdirectory (`.dbcli/schemas/<connection>/`). Run `dbcli schema --use <connection>` once per connection before querying it — otherwise `schema <table>` may return data from the wrong connection's cache.
 
 > **PostgreSQL:** Introspection uses the exact `public` catalog identity throughout. Full catalog/schema/table joins prevent a reused constraint name from contaminating another table; enum lookup includes its namespace; composite primary-key order comes from the exact table OID and index ordinality; and row estimates are scoped to the exact `public` relation. Row-count SQL qualifies and quotes both `"public"` and the exact table identifier, escaping embedded quotes so mixed-case or punctuation-bearing names remain distinct and safe.
@@ -283,6 +296,12 @@ dbcli query "SELECT * FROM orders" --format html > orders.html   # pipe to stdou
 **Options:** `--format <table|json|csv|html>`, `--ui` (open the dashboard in the system browser; implies `--format html`), `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`), `--fields <list>`, `--truncate <number>` / `--no-truncate`, `-f, --query-file <path>`, `--use <name[,name]>`, `--slow-ms <number>`, `--recovery`
 **Permission:** query-only+ (Redis: per-command; Elasticsearch: per HTTP method/path)
 
+> **Server-side scripts are rejected on every path.** MongoDB `$where`,
+> `$function`, and `$accumulator`, and Elasticsearch `script` / `script_fields`,
+> execute code on the database server. The adapters reject them anywhere in a
+> filter, pipeline, or DSL body — before the request is sent — so `query`, `q`,
+> saved snippets, and DML planning all behave the same way.
+
 #### Passive slow-query hint (`--slow-ms`)
 
 `query` and `q` read the execution time they already measured for a finished
@@ -1189,6 +1208,7 @@ dbcli design validate [--file <path>] [--format <format>]
 dbcli design render [--file <path>] [--format <format>]
 dbcli design diff (--against-cache | --against-orm <paths>) [options]
 dbcli design propose (--against-cache | --against-orm <paths>) [options]
+dbcli impact assess --design <path> (--against-cache | --against-orm <paths>) --output <path> [options]
 ```
 
 ```bash
@@ -1200,6 +1220,7 @@ dbcli design render --format mermaid
 dbcli design diff --against-cache --format markdown
 dbcli design diff --against-orm ./prisma/schema.prisma --format markdown
 dbcli design propose --against-orm ./prisma/schema.prisma --format markdown
+dbcli impact assess --design ./dbcli.design.json --against-cache --output ./impact.json --fail-on warn
 ```
 
 | Option | Applies to | Default | Meaning |
@@ -1216,6 +1237,10 @@ dbcli design propose --against-orm ./prisma/schema.prisma --format markdown
 `diff` and `propose` require **exactly one** comparison target; passing both or
 neither is an error.
 
+### impact assess
+
+Writes an offline JSON or Markdown report for the known declared impact of a design change. It requires `--design`, exactly one baseline (`--against-cache` or `--against-orm`), and an explicit workspace-contained `--output`. `--format` is `json` (default) or `markdown`; `--fail-on` is `error`, `warn`, or `never` (default). The threshold changes only the successful command exit code after the report is written. The report is limited to declared/partial coverage and never claims complete coverage. It may join the optional reviewed `dbcli.data-access.json` manifest only after validating its canonical semantic references and existing workspace-relative source paths; it never reads those sources. An optional explicit `--events <path>` is bounded and streamed through a redaction-first projection that retains recent safe table metadata only. It never starts a proxy, reads a rotated log, renders SQL/literals/errors/sessions/paths, or makes the command fail solely because workload evidence is absent or advisory. It reads no database, executes no SQL, and never reads saved-query bodies.
+
 #### Artifact shape
 
 This example validates clean (0 errors, 0 warnings):
@@ -1939,7 +1964,7 @@ Output reports: writer enabled/disabled, last write result, file-lock state, rot
 ### verify
 
 Run a verification scenario. `verify` **runs** verification scenarios (safe-backfill,
-migration, rollback) and never executes writes/DDL. `verification` **inspects and manages**
+migration, rollback, constraint) and never executes writes/DDL. `verification` **inspects and manages**
 the local result artifacts those scenarios produce under `.dbcli/verification/`.
 
 ```bash
@@ -1951,7 +1976,8 @@ dbcli verify safe-backfill \
   --expect "value == 0"
 
 # After-write: re-run guards, run the read-back assertion, write a v1 artifact.
-dbcli verify safe-backfill ... --after-write
+# An optional receipt is provenance only, never approval to execute a write.
+dbcli verify safe-backfill ... --after-write --evidence-receipt .dbcli/evidence/verify-receipt.json
 
 # JSON for agents.
 dbcli verify safe-backfill ... --format json
@@ -1959,7 +1985,11 @@ dbcli verify safe-backfill ... --format json
 
 Options: `--table` (req), `--query` (req, analyzed not executed), `--verify-query`
 (req, **plain SELECT only**), `--expect` (req), `--after-write`, `--format <table|json>`,
-`--subject-name <name>`, `--summary <text>`.
+`--subject-name <name>`, `--summary <text>`, `--evidence-receipt <workspace-relative-path>`
+(after-write only). A receipt is safe provenance for the already-executed verification,
+not approval to execute a write. Its `succeeded`/`failed` outcome remains distinct from
+the artifact status (`verified`, `not_verified`, `indeterminate`, or `blocked`); task-pack
+`planned` evidence stays plan-only.
 
 Guard constraints (fail closed): `--verify-query` must be a **plain `SELECT`** —
 `EXPLAIN`/`EXPLAIN ANALYZE`, `SHOW`, `DESCRIBE`, and data-modifying CTEs are rejected
@@ -2464,6 +2494,66 @@ dbcli migrate drop-enum status --execute --force
 
 **AI agent note:** Always use dry-run first (no `--execute`) to preview generated SQL. Only add `--execute` after confirming the SQL is correct. For DROP operations, both `--execute` and `--force` are required.
 
+### evidence
+
+Compose a canonical, offline **Evidence Pack** from existing verification artifacts
+and audit entries. This command never opens a database connection. A pack retains only
+safe pointers and outcome fields: it excludes SQL, targets, audit metadata, verification
+summaries, result data, and credentials. Claims are external statements, never dbcli
+verification verdicts.
+
+#### `evidence compose`
+
+```bash
+dbcli evidence compose --claims ./claims.json --verification ver_abcd --audit 1a2b \
+  --receipt .dbcli/evidence/verify-receipt.json \
+  --output .dbcli/evidence/review.json --format json
+```
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--claims <file>` | Required JSON file with exactly `subject` and `claims`; every claim has an `id` and plain-language `text`. SQL-shaped text, credentials, error content, and blacklisted identifiers are rejected. | — |
+| `--verification <selector...>` | One or more verification artifact ids, unique prefixes, filenames, or in-bounds paths. | none |
+| `--audit <selector...>` | One or more audit ids or unique prefixes (minimum four characters) from the active connection. | none |
+| `--receipt <path...>` | Explicit workspace-relative receipt path(s). Receipts contribute safe provenance only; they are not execution approval. | none |
+| `--output <path>` | Required new JSON path under the current workspace. Existing files and paths outside the workspace are refused. | — |
+| `--format <json\|markdown>` | Compose receipt format printed to stdout. | `json` |
+
+At least one `--verification`, `--audit`, or `--receipt` reference is required. The resulting pack
+contains a canonical SHA-256 integrity digest and `coverage.completeForDeclaredEvidence:
+true` for its explicitly selected references.
+
+#### `evidence validate`
+
+```bash
+dbcli evidence validate --file .dbcli/evidence/review.json --format json
+```
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--file <path>` | Required evidence-pack JSON file. | — |
+| `--format <json\|markdown>` | Validation report format. | `json` |
+
+Exit `0` when digest and all selected sources are valid. If a referenced audit or
+verification artifact later rotates, is cleared, disappears, or belongs to a different
+active connection, output stays parseable with `integrity: "valid"` and
+`references: "source-expired"`, then exits `1`.
+
+#### `evidence render`
+
+```bash
+dbcli evidence render --file .dbcli/evidence/review.json --format markdown
+```
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--file <path>` | Required evidence-pack JSON file. | — |
+| `--format <json\|markdown>` | Render format. | `markdown` |
+
+`render` validates the pack digest and active blacklist policy but does not resolve its
+original references. It is therefore available for historical review after `validate`
+reports `source-expired`, unless an exposed pack field is now blacklisted.
+
 ### semantic
 
 Validate or print the optional, version-controlled `dbcli.semantic.json` in the
@@ -2590,6 +2680,39 @@ limits, audit, and recovery safeguards remain in force.
 
 **Permission:** n/a (local files only; no database connection).
 
+### contract
+
+Inspect the optional, version-controlled `dbcli.contracts.json` without opening a
+database connection. A contract adds a reviewed owner and descriptive evidence policy
+to canonical semantic references; it is not an executable data contract, assertion,
+query, or verification scenario.
+
+```bash
+dbcli contract validate --format json
+dbcli contract context --format json
+dbcli contract context --format markdown
+dbcli contract search customer --format json
+dbcli contract drift --format json
+```
+
+The strict v1 artifact contains `version` and `contracts`. Each contract has a unique
+canonical `name`, `status` (`draft`, `approved`, or `deprecated`), bounded plain-text
+`description` and `owner`, one or more canonical semantic `subjects`, optional aliases,
+and an `evidencePolicy` of `none`, `receipt-required`, or `verification-required`.
+Subjects must remain in the existing visible semantic registry; protected identifiers,
+unknown keys, duplicate names or subjects, SQL-like text, credentials, and stale
+references fail closed without exposing protected names.
+
+`contract validate` requires an explicit valid artifact. `contract context` and
+`contract search` return only valid approved contracts; draft and deprecated contracts
+remain local review artifacts. `contract drift` reports `valid`, `stale`, `invalid`, or
+`unavailable` evidence offline and exits non-zero except for `valid`. A missing default
+file is allowed by `skill context` and leaves ordinary semantic context unchanged; a
+present invalid file fails closed. No contract command writes a file, opens a database
+connection, widens a `QueryDraft`, or changes permission/blacklist behavior.
+
+**Permission:** n/a (local files only; no database connection).
+
 ### skill
 
 Emit `SKILL.md` (and the companion `reference.md`) to stdout, a file, or an