@carllee1983/dbcli 1.52.1 → 1.54.0

package/.cursor/rules/dbcli.mdc

@@ -110,8 +110,8 @@ still stop where those gates require human confirmation.
 term, or relationship/join intent instead of a physical table or field name, first run
 `dbcli skill context --format json`. If it includes `semantic`, treat that reviewed
 section as the governed vocabulary; use `dbcli semantic search <terms> --format json`
-to look up a specific term. If no semantic section exists or search returns no result,
-fall back to `blacklist` → `schema` mapping and tell the user that optional
+to look up a specific term. If `contracts` is present, use only its approved terms and
+their descriptive evidence policy; it never authorizes an assertion or query. If no semantic section exists or search returns no result, fall back to `blacklist` → `schema` mapping and tell the user that optional
 `dbcli.semantic.json` can make future requests consistent. Never create, update, or
 migrate that file without an explicit human request; semantic vocabulary never replaces
 schema confirmation or the normal query/write safety gates.
@@ -159,6 +159,7 @@ in **How to use dbcli** still applies.
 | ORM or migration work | `schema --format json` → `diff --against-orm <orm-schema>` → review error-level drift → proposals via `migrate` (dry-run) → `migration-review` task pack → `diff --against <snapshot>` after applying. |
 | Schema design, no database yet | `design init --output ./dbcli.design.json` → edit → `design validate` → `design render --format mermaid`. With existing ORM models, reconcile via `design diff --against-orm <path>` first. |
 | Design drift on a live database | `blacklist list` → `schema --format json` → `design diff --against-cache` → `design propose --against-cache`, then hand the plan to a human before any migration. |
+| PR schema-change review | `blacklist list` → `impact assess --design ./dbcli.design.json --against-cache --output ./impact.json --fail-on warn`; optionally add explicit `--events ./.dbcli/proxy/events.jsonl` for advisory redacted workload table evidence (never SQL/log rendering or a blocker), then review declared findings, coverage gaps, and the optional reviewed `dbcli.data-access.json` (declared operations only; never source parsing). |
 | PR database review | Review changed persistence paths, then propose concrete `schema` / `plan` / `dry-run` / `report` / `guide` commands per material claim. |
 | Slow endpoint or query | `report --section perf` → task pack `analyze-table-perf` → `lint "<query>"` → `guide missing-index-for "<query>"`; use `proxy analyze` when logs exist. |
 | Safe data backfill | `blacklist list` → `schema <object>` → count/scope query → `update … --dry-run` → read-back or snippet `--verify`. |
@@ -201,7 +202,9 @@ Guardrails:
 - Durable evidence: `assert … --write-verification-artifact --verification-subject <kind:name>`;
   inspect with `verification summary` / `list` / `show <id>`. The `verify safe-backfill` /
   `migration` / `rollback --kind <ddl|dml>` / `constraint --check <fk|not-null|unique|custom>`
-  family runs preflight + `--after-write` checks and **never executes the write**. Full flags
+  family runs preflight + `--after-write` checks and **never executes the write**. Add
+  `--evidence-receipt <workspace-relative-path>` only after after-write for a safe provenance
+  receipt; it is never approval to execute a write. Full flags
   and the per-command blocks are in [reference.md](../skills/dbcli/reference.md#commands).
 
 ## Audit log
@@ -415,6 +418,7 @@ Full flags and edge cases: see [reference.md](../skills/dbcli/reference.md#init)
 | `shell` | (same as query+) | Interactive REPL. SQL engines, MongoDB, and Redis (single-line; `.no-limit on/off`). Elasticsearch opens a Kibana Dev Tools-style REPL (`<METHOD> /<path>` + optional JSON body, blank line submits). |
 | `skill` | n/a | Generate / install AI skill docs (`--install <claude\|gemini\|antigravity\|copilot\|cursor\|codex\|windsurf>`); `skill tasks list/show/plan` for Agent Task Packs; `skill context` for an LLM prompt-context payload (for injecting into another LLM, not needed for normal operation). |
 | `semantic` | n/a | Validate, search, inspect drift, migrate to v2, or print the optional project-root `dbcli.semantic.json`. Give its reviewed context to an external agent, but keep provider credentials, prompts, and agent context outside dbcli. `semantic draft validate --input <file|-> [--format text\|json]` validates only the explicit untrusted `QueryDraft` offline against local semantic/schema/saved-query metadata; it returns safe hashes/references/violation codes, never executes or echoes candidate SQL. Review the original draft, then invoke `explain` or `query` separately if intended. |
+| `contract` | n/a | Validate, inspect approved context, search, or inspect drift for optional project-root `dbcli.contracts.json`. Contracts add ownership and a descriptive evidence policy to canonical semantic references; they are offline, never execute SQL, and cannot create verification or query authority. `skill context` includes only valid approved contracts. |
 | `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`. |
 
 Use root-level `dbcli --use <name> <command>` for any command; `query`, `schema`, `list`,
@@ -601,4 +605,4 @@ schema. Raw `query` / `export` invocations render a sortable table only.
 - Blacklisted tables and columns are redacted from query output.
 - `schema` reports `estimatedRowCount` and `sizeCategory` (small / medium / large / huge). For large/huge tables add `WHERE` or `LIMIT` — bands in [reference.md](../skills/dbcli/reference.md#schema).
 - `doctor` on `mongodb+srv://` reports whether SRV resolves natively or through the DoH fallback — useful when the runtime restricts DNS.
-- **Global flags:** `--version`, `--config <path>`, `--global`, `--use <name>`, `--timeout <ms>`, `-v` / `--verbose` / `-vv`, `-q` / `--quiet`, `--no-color` (also honours `NO_COLOR`). Root-level flags must precede the command unless the command explicitly declares a command-level option.
+- **Global flags:** `--version`, `--config <path>`, `--global`, `--use <name>`, `--timeout <ms>`, `--statement-timeout <ms>`, `-v` / `--verbose` / `-vv`, `-q` / `--quiet`, `--no-color` (also honours `NO_COLOR`). Root-level flags must precede the command unless the command explicitly declares a command-level option.

package/.cursor/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

package/.github/skills/dbcli/SKILL.md

@@ -110,8 +110,8 @@ still stop where those gates require human confirmation.
 term, or relationship/join intent instead of a physical table or field name, first run
 `dbcli skill context --format json`. If it includes `semantic`, treat that reviewed
 section as the governed vocabulary; use `dbcli semantic search <terms> --format json`
-to look up a specific term. If no semantic section exists or search returns no result,
-fall back to `blacklist` → `schema` mapping and tell the user that optional
+to look up a specific term. If `contracts` is present, use only its approved terms and
+their descriptive evidence policy; it never authorizes an assertion or query. If no semantic section exists or search returns no result, fall back to `blacklist` → `schema` mapping and tell the user that optional
 `dbcli.semantic.json` can make future requests consistent. Never create, update, or
 migrate that file without an explicit human request; semantic vocabulary never replaces
 schema confirmation or the normal query/write safety gates.
@@ -159,6 +159,7 @@ in **How to use dbcli** still applies.
 | ORM or migration work | `schema --format json` → `diff --against-orm <orm-schema>` → review error-level drift → proposals via `migrate` (dry-run) → `migration-review` task pack → `diff --against <snapshot>` after applying. |
 | Schema design, no database yet | `design init --output ./dbcli.design.json` → edit → `design validate` → `design render --format mermaid`. With existing ORM models, reconcile via `design diff --against-orm <path>` first. |
 | Design drift on a live database | `blacklist list` → `schema --format json` → `design diff --against-cache` → `design propose --against-cache`, then hand the plan to a human before any migration. |
+| PR schema-change review | `blacklist list` → `impact assess --design ./dbcli.design.json --against-cache --output ./impact.json --fail-on warn`; optionally add explicit `--events ./.dbcli/proxy/events.jsonl` for advisory redacted workload table evidence (never SQL/log rendering or a blocker), then review declared findings, coverage gaps, and the optional reviewed `dbcli.data-access.json` (declared operations only; never source parsing). |
 | PR database review | Review changed persistence paths, then propose concrete `schema` / `plan` / `dry-run` / `report` / `guide` commands per material claim. |
 | Slow endpoint or query | `report --section perf` → task pack `analyze-table-perf` → `lint "<query>"` → `guide missing-index-for "<query>"`; use `proxy analyze` when logs exist. |
 | Safe data backfill | `blacklist list` → `schema <object>` → count/scope query → `update … --dry-run` → read-back or snippet `--verify`. |
@@ -201,7 +202,9 @@ Guardrails:
 - Durable evidence: `assert … --write-verification-artifact --verification-subject <kind:name>`;
   inspect with `verification summary` / `list` / `show <id>`. The `verify safe-backfill` /
   `migration` / `rollback --kind <ddl|dml>` / `constraint --check <fk|not-null|unique|custom>`
-  family runs preflight + `--after-write` checks and **never executes the write**. Full flags
+  family runs preflight + `--after-write` checks and **never executes the write**. Add
+  `--evidence-receipt <workspace-relative-path>` only after after-write for a safe provenance
+  receipt; it is never approval to execute a write. Full flags
   and the per-command blocks are in [reference.md](reference.md#commands).
 
 ## Audit log
@@ -415,6 +418,7 @@ Full flags and edge cases: see [reference.md](reference.md#init).
 | `shell` | (same as query+) | Interactive REPL. SQL engines, MongoDB, and Redis (single-line; `.no-limit on/off`). Elasticsearch opens a Kibana Dev Tools-style REPL (`<METHOD> /<path>` + optional JSON body, blank line submits). |
 | `skill` | n/a | Generate / install AI skill docs (`--install <claude\|gemini\|antigravity\|copilot\|cursor\|codex\|windsurf>`); `skill tasks list/show/plan` for Agent Task Packs; `skill context` for an LLM prompt-context payload (for injecting into another LLM, not needed for normal operation). |
 | `semantic` | n/a | Validate, search, inspect drift, migrate to v2, or print the optional project-root `dbcli.semantic.json`. Give its reviewed context to an external agent, but keep provider credentials, prompts, and agent context outside dbcli. `semantic draft validate --input <file|-> [--format text\|json]` validates only the explicit untrusted `QueryDraft` offline against local semantic/schema/saved-query metadata; it returns safe hashes/references/violation codes, never executes or echoes candidate SQL. Review the original draft, then invoke `explain` or `query` separately if intended. |
+| `contract` | n/a | Validate, inspect approved context, search, or inspect drift for optional project-root `dbcli.contracts.json`. Contracts add ownership and a descriptive evidence policy to canonical semantic references; they are offline, never execute SQL, and cannot create verification or query authority. `skill context` includes only valid approved contracts. |
 | `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`. |
 
 Use root-level `dbcli --use <name> <command>` for any command; `query`, `schema`, `list`,
@@ -601,4 +605,4 @@ schema. Raw `query` / `export` invocations render a sortable table only.
 - Blacklisted tables and columns are redacted from query output.
 - `schema` reports `estimatedRowCount` and `sizeCategory` (small / medium / large / huge). For large/huge tables add `WHERE` or `LIMIT` — bands in [reference.md](reference.md#schema).
 - `doctor` on `mongodb+srv://` reports whether SRV resolves natively or through the DoH fallback — useful when the runtime restricts DNS.
-- **Global flags:** `--version`, `--config <path>`, `--global`, `--use <name>`, `--timeout <ms>`, `-v` / `--verbose` / `-vv`, `-q` / `--quiet`, `--no-color` (also honours `NO_COLOR`). Root-level flags must precede the command unless the command explicitly declares a command-level option.
+- **Global flags:** `--version`, `--config <path>`, `--global`, `--use <name>`, `--timeout <ms>`, `--statement-timeout <ms>`, `-v` / `--verbose` / `-vv`, `-q` / `--quiet`, `--no-color` (also honours `NO_COLOR`). Root-level flags must precede the command unless the command explicitly declares a command-level option.

package/.github/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