safegres 1.16.0 → 1.18.0

package/README.md

@@ -12,248 +12,432 @@
    <a href="https://www.npmjs.com/package/safegres"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=packages%2Fsafegres%2Fpackage.json"/></a>
 </p>
 
-Pure-Postgres Row-Level Security auditor. No app framework required. Drop it on any PostgreSQL database and get a structured report on grants, RLS enforcement, policy coverage, and risky SQL policy patterns.
+<p align="center"><strong>Safe <em>and</em> fast Postgres. Graded.</strong></p>
 
-safegres audits Row-Level Security from inside Postgres. It checks whether tables with grants are protected by RLS, whether policies actually cover the granted operations, and whether policy bodies contain risky patterns like permissive `true` checks, volatile functions, or role/session-based bypass logic.
+safegres is a static analyzer for a live PostgreSQL database. It reads the system catalog and
+parses every policy predicate and function body into an AST, then answers two questions the
+catalog already contains the answers to — *who can actually reach this row*, and *what does
+checking that cost per row* — and scores them on **two independent axes**.
 
-```bash
-npm install -g safegres
+Two scores, never mixed. Hardening a table can't show up as a performance regression; adding an
+index can't show up as a security win. That is the whole design: the trade you make between them
+becomes visible instead of netting out to a single number.
 
-# Standard libpq env vars (PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE)
-export PGHOST=localhost PGUSER=postgres PGPASSWORD=password PGDATABASE=mydb
-safegres audit
+```bash
+npm i -D safegres
+npx safegres doctor          # connection, catalog visibility, and what's missing
+npx safegres audit --perf    # two scores, from the catalog
 ```
 
-Per-field overrides (`--host`, `--port`, `--user`, `--password`, `--database`) and a full `--connection <url>` flag are also supported. See `safegres audit --help`.
+Standard libpq environment (`PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`), a full
+`--connection <url>`, or per-field flags. No agent, no traffic, no application framework, nothing
+executed and nothing written — safe to point at a production replica.
 
-### Output & verbosity
+*No database handy? See [CI](#ci-in-one-job): one service container plus the migration command you
+already have.*
 
-Pretty output prints the exposure line, score, and the exposed findings. Internal (non-exposed) advisories are collapsed to a one-line count by default so a large database's report stays readable.
+## Features
 
-- `--summary`, `-q` — print only the exposure line, score/grade, and severity counts (no per-finding lines). Ideal for CI job summaries.
-- `--verbose` — expand the internal advisories instead of collapsing them to a count.
-- `--exposed-only` — drop internal findings entirely.
-- `--format json` / `--format json-pretty` — machine-readable output (always carries every finding).
-- `--format markdown` — the same report as GitHub-flavoured markdown, for a job summary or a PR comment (see [CI](#ci)).
-- `--format sarif` — SARIF 2.1.0 for GitHub code scanning (see [CI](#ci)).
+* 🛡️ **Complete RLS Auditing** – Grants, RLS enforcement, policy coverage and policy behavior, across every schema and role in the database
+* 🎯 **Operation-Level Coverage** – Every granted `SELECT`/`INSERT`/`UPDATE`/`DELETE` checked against the policies that actually cover it, per role
+* 🔍 **Risky Policy Detection** – Permissive checks, volatile and session-dependent predicates, definer escalation and role bypass, found in the parsed AST rather than by regex
+* ⚡ **Performance on Its Own Axis** – Policy predicates that no index can serve, per-row function calls, missing foreign-key indexes — scored separately, so hardening never reads as a regression
+* 🧭 **Exposure Planes** – The declared API surface is the headline grade; direct-connection and per-role planes are graded beside it, so "what can an anonymous caller reach?" is a number
+* 📊 **Security Scoring & Grades** – Scores, grades, severity counts and per-rule deductions with the payoff of fixing each one
+* 🐘 **Pure PostgreSQL Analysis** – Reads the catalog and parses SQL; no agent, no traffic, no ORM, no application changes, nothing executed
+* ⚙️ **Built for CI** – Summaries, Markdown, JSON and SARIF, GitHub job summaries, annotations and a sticky PR comment, with configurable failure thresholds
+* Δ **Change-Aware Audits** – Compare two reports to show exactly what a branch introduced, fixed or worsened; baselines accept inherited debt and gate only what's new
+* 🧪 **Graded Against a Corpus** – `safegres eval` scores the auditor itself on fixtures with known answers, sealed against config that could game the number
+* 📦 **CLI and Library APIs** – Run it from the command line, or import the analysis, report and renderers into your own tooling
 
-### CI
+## What you get
 
-A plain audit is one command and one gate; `--format markdown` writes the report where a reviewer will actually see it:
-
-```yaml
-- name: Audit RLS
-  run: |
-    npx safegres audit --format markdown >> "$GITHUB_STEP_SUMMARY"
-    npx safegres audit --fail-on-grade B --summary
-  env:
-    PGHOST: localhost
-    PGUSER: postgres
-    PGPASSWORD: postgres
 ```
+safegres 1.16.1  (2026-02-14T09:31:07.884Z)
 
-Scores lead, then the severity counts, then a table per dimension; internal (non-exposed) advisories and accepted baseline debt fold into `<details>` so the summary stays skimmable. To post it as a PR comment instead, pipe it to `gh pr comment --body-file -`. The same renderer is available to library callers as `renderMarkdown(report)`.
+exposure: 2 schema(s) via config  — 41/318 tables exposed
 
-#### What changed (`--compare`)
+score: 91.4 (A)  — model: density
+  top deductions: A2 −10 (×1)  R3 −4 (×1)
+  by rule: A2 B (+8.4)  R3 A (+3.5)
+  unscored: A4 (×3)  A6 (×7)  — zero-weight, fixing these cannot move the score
 
-A report says what the database *is*; on a pull request the only question is what the branch *did* to it. `--compare` diffs this run against a previous one and renders the movement — a Δ column in the score table, the severity counts that moved, and every rule whose finding count changed:
+perf score: 78.1 (C)  — model: density
+  top deductions: X2 −12 (×3)  X1 −8 (×2)  X9 −4 (×1)
+  by rule: X2 C (+11.2)  X1 D (+7.6)  X9 B (+3.8)
 
-```bash
-safegres audit --perf --compare main-report.json --compare-ref main --format markdown
-```
+summary: 0 critical  1 high  4 medium  3 low  7 info
 
-```
-| Dimension   | Score      | Grade | Δ vs main                                | Top deductions   |
-| Security    | **99.3**   | **A+**| 🟢 ▲ +1.2 (from 98.1)                    | `A3` −4 (×2)     |
-| Performance | **72.4**   | **C** | 🔴 ▼ −2.6 (from 75.0) · B → C · 40 → 46 findings | `X1` −18 (×46) |
+[HIGH] A2  app_public.webhook_deliveries
+    Roles [authenticated] have grants on app_public.webhook_deliveries but RLS is disabled
+[MED ] X2  app_public.posts  (posts_tenant)
+    Policy "posts_tenant" on app_public.posts filters by tenant_id, which is not the
+    leading column of any index
 ```
 
-The previous run is a file, not something safegres remembers: a scanner has no memory and shouldn't acquire one, so CI decides what "previous" means (the report artifact from the base branch, a committed scoreboard, last night's nightly) and hands it over. Any earlier `--format json` output works as input. When keeping whole reports is too much, `--write-snapshot <file>` writes just the aggregates the comparison reads — scores, grades, severity counts, per-rule counts — and `--compare` accepts either. `--compare-ref` labels the previous run in the output.
+Also available as `--format json`, `json-pretty`, `markdown` (job summaries and PR comments) and
+`sarif` (GitHub code scanning).
 
-Library callers get the same thing as `compareReports(previous, report)`, with `toSnapshot` / `parseSnapshot` / `serializeSnapshot` for the file side; the result is carried in JSON output as `comparison`.
+## How it works
 
-#### Code scanning (SARIF)
+Three analyses over three different representations. None of them run your queries.
 
-`--format sarif` emits SARIF 2.1.0, so findings become GitHub code-scanning alerts — Security tab, inline PR annotations, dismissals that stick:
+**1. The catalog, as a relation.** `pg_class`, `pg_namespace`, `pg_policy`, `pg_roles`,
+`pg_auth_members`, `pg_index` and `aclexplode()` are joined into one snapshot per relation:
+grants, RLS flags, policies with their expressions, indexes, ownership.
 
-```yaml
-- run: npx safegres audit --perf --format sarif --sarif-sources ./deploy > safegres.sarif
-- uses: github/codeql-action/upload-sarif@v3
-  with: { sarif_file: safegres.sarif }
-```
+**2. Policy predicates, as ASTs.** Every `USING` / `WITH CHECK` expression is parsed with
+[`pgsql-parser`](https://github.com/launchql/pgsql-parser) (libpg_query — the *actual* PostgreSQL
+grammar, not a regex) and traversed. That is what makes the interesting rules possible: a literal
+`true` in a write policy (A7), a cast wrapping the policy's own column so no plain index can serve
+it (X3), a non-`IMMUTABLE` call whose arguments reference no column of the row and which sits
+outside an uncorrelated scalar sub-select — i.e. a per-row call the planner will not hoist into an
+InitPlan (X9). Structural detection, not a list of known function names: a GUC-reading helper
+somebody adds next year is caught without configuration.
+
+**3. Effective access, as a lattice.** ACL rows are not access. A privilege also arrives via
+`GRANT … TO PUBLIC` and via role inheritance (`pg_auth_members`, INHERIT-following), and it is
+only *reachable* if the role also holds `USAGE` on the schema. safegres computes the effective
+cell each `(relation, role, privilege)` triple lands in, with `pg_has_role` membership semantics,
+and reports the ones that are inconsistent in either direction:
+
+| grant | RLS | policy | verdict |
+| --- | --- | --- | --- |
+| yes | on | yes | normal — policy-mediated access |
+| yes | on | no | dead grant (L1 indirect; A4/A5 direct) |
+| yes | off | — | unmediated (A2 table-level; L5 per untrusted role, indirect) |
+| no | — | yes | dead policy (L2) |
 
-An alert needs a file and a line, but safegres reads the catalog — a live database has no source location. `--sarif-sources <dir>` scans that directory's `.sql` for the `CREATE TABLE` / `CREATE POLICY` that defines each object, so a finding on `app_public.widgets` points at the migration that created it (policy findings resolve to the `CREATE POLICY` line). Findings that don't resolve are still emitted, without a location — GitHub drops those, other SARIF consumers keep them.
+The same closure answers the direct question — *what can role X actually reach?* — as
+`report.roleAccess`, with provenance (`direct`, `PUBLIC`, `member of <role>`) per relation.
 
-Results are fingerprinted by finding *identity* (code + relation + policy + subject, the same key the [perf baseline](#perf-baseline-the-ratchet) uses), never by message text, so rewording a rule in a later release doesn't close and reopen every alert. Perf rules are tagged `performance`, security rules `security`.
+Two optional analyses go further: `--explain` plans each finding's query shape with
+`EXPLAIN (GENERIC_PLAN)` and lets the planner **refute** the tool's own static claim; `--call-graph`
+computes the transitive closure of function calls from the exposed entry points and enumerates the
+trust boundaries on the way.
 
 ## What it checks
 
-| Code | Severity | Direction | Category | Check |
-| --- | --- | --- | --- | --- |
-| A1 | low | fail-closed | flags | RLS enabled but **0 policies** (deny-all — confirm the lock is intended) |
-| A2 | high | fail-open | flags | Grants exist on a table with **RLS disabled** |
-| A3 | low | fail-open | flags | RLS enabled but **`FORCE ROW LEVEL SECURITY` not set** (table owner bypass) |
-| A4 | low | fail-closed | coverage | INSERT / UPDATE / DELETE grant with **no covering policy** — writes are denied at runtime |
-| A5 | low | fail-closed | coverage | SELECT grant with **no policy** — queries silently return 0 rows |
-| A6 | info | fail-closed | coverage | UPDATE has `USING` but **no `WITH CHECK`** (row-smuggling surface) |
-| A7 | critical | fail-open | anti-pattern | Trivially-permissive **WRITE** policy (INSERT/UPDATE/DELETE/ALL with literal `true`) |
-| A8 | low | fail-open | anti-pattern | Trivially-permissive **SELECT** policy (`USING (true)` — confirm public-read is intended) |
-| P1 | high | neutral | anti-pattern | Policy body calls a **VOLATILE function** (per-row evaluation) — *scored on the [perf axis](#performance-dimension---perf)* |
-| P5 | high | fail-open | anti-pattern | Policy body references **`session_user`** / `current_user` / `pg_has_role(...)` |
-| R1 | critical | fail-open | anti-pattern | An **untrusted role** (options: `{ roles: [...] }`) holds a write privilege |
-| R2 | high | fail-open | anti-pattern | A permissive write policy applies to an untrusted role or PUBLIC |
-| R3 | medium | fail-open | anti-pattern | An RLS table has grants **TO PUBLIC** (includes all current/future roles) |
-| W1 | medium | — | meta | No exposure surface configured — whole database assumed reachable, score capped |
-
-**Direction matters**: `fail-open` findings are actual exposure (the untrusted side can reach more than intended). `fail-closed` findings are denied at runtime — an availability/hygiene concern, not a leak — and contribute **nothing to the score** by default (tune with `scoring.failClosedWeight`).
-
-Coverage is aggregated `(table, role) → { hasUsing, hasWithCheck }` across every applicable permissive policy (FOR ALL + PUBLIC-role policies considered). Roles with `BYPASSRLS` are suppressed.
-
-R1/R2 are no-ops until a role list is configured — e.g. `"R1": ["critical", { "roles": ["anonymous"] }]` — so they cost nothing on databases without an untrusted-role model. The `safegres:constructive` preset configures them for `anonymous`.
+34 rules across two dimensions, plus a source-level convention linter. The prefix letter is a
+family, **not** the dimension: `P1`/`P1b` are performance, `P5` is security.
+
+### Security (19 rules)
+
+| Code | Severity | Direction | Check |
+| --- | --- | --- | --- |
+| A1 | low | fail-closed | RLS enabled but **0 policies** (deny-all — confirm the lock is intended) |
+| A2 | high | fail-open | Grants exist on a table with **RLS disabled** |
+| A3 | low | fail-open | RLS enabled but **`FORCE ROW LEVEL SECURITY` not set** (table-owner bypass) |
+| A4 | low | fail-closed | INSERT/UPDATE/DELETE grant with **no covering policy** — writes denied at runtime |
+| A5 | low | fail-closed | SELECT grant with **no policy** — queries silently return 0 rows |
+| A6 | info | fail-closed | UPDATE has `USING` but **no `WITH CHECK`** (row-smuggling surface) |
+| A7 | critical | fail-open | Trivially-permissive **write** policy (literal `true`) |
+| A8 | low | fail-open | Trivially-permissive **SELECT** policy (`USING (true)`) |
+| P5 | high | fail-open | Policy references **`session_user`** / `current_user` / `pg_has_role(...)` |
+| R1 | critical | fail-open | An **untrusted role** holds a write privilege † |
+| R2 | high | fail-open | A permissive write policy applies to an untrusted role or PUBLIC † |
+| R3 | medium | fail-open | An RLS table has grants **TO PUBLIC** |
+| L1 | low | fail-closed | **Dead indirect grant** — arrives via PUBLIC/inheritance, no policy admits it |
+| L2 | low | fail-closed | **Dead policy** — applies to a role holding no corresponding grant |
+| L3 | low | fail-closed | **Unreachable grant** — object privilege without schema `USAGE` |
+| L4 | info | neutral | **Dead schema `USAGE`** — reaches no relation and no function |
+| L5 | info | fail-open | An untrusted role reaches an **RLS-off table** via PUBLIC/inheritance † |
+| L6 | info | neutral | **Unaddressable grant** — an API role holds privileges on a relation its API cannot name ‡ |
+| L8 | info | fail-open | **DEFINER view bypass** — an untrusted role reads a base relation as the view's owner † |
+| L9 | info | fail-open | **DEFINER view write** — an auto-updatable definer view writes a base relation as its owner † |
+| L10 | info | fail-open | **Rewrite-rule bypass** — a rule on a view writes a relation as the view's owner, `security_invoker` notwithstanding † |
+| L11 | info | fail-open | **Materialized-view snapshot** — stored rows serve an untrusted role what the base relation's grants and policies would not † |
+| L12 | info | fail-open | **Non-barrier filtering view** — a view is an untrusted role's only path to a relation, but its row filter is not a boundary † |
+| W1 | medium | — | **No exposure surface configured** — whole database assumed reachable, score capped |
+
+† R1/R2/L5 are no-ops until you name the untrusted roles:
+`"R1": ["critical", { "roles": ["anonymous"] }]`. They cost nothing on databases without an
+untrusted-role model; the `safegres:constructive` preset configures them for `anonymous`.
+
+‡ L6 needs an adapter that can compute [API reach](#api-reach--the-relations-the-api-can-actually-name);
+without one nothing is unaddressable and it never fires.
+
+**Direction is the load-bearing idea.** `fail-open` findings are exposure — the untrusted side
+reaches more than intended. `fail-closed` findings are *denied by Postgres at runtime*: an
+availability and hygiene concern, not a leak. They contribute **zero** to the score by default
+(`scoring.failClosedWeight`). safegres does not cry wolf about a grant the database already refuses.
+
+### Convention (source-level lint, 4 rules — `safegres:constructive`)
+
+House-style rules that read function **definitions** (`pg_get_functiondef`), not the catalog. They
+are pure `source → findings` — no `pg` dependency in the lint module — and are **off outside the
+`safegres:constructive` preset**, which enables them. A function on a non-exposed schema costs
+nothing, like every other rule.
+
+| Code | Severity | Direction | Check |
+| --- | --- | --- | --- |
+| C1 | high | fail-open | Function **sets `search_path`** (house rule: never set it — fully-qualify instead) |
+| C2 | medium | neutral | Function uses a **`#variable_conflict`** directive |
+| C3 | low | neutral | Function has an **unqualified relation reference** (relies on `search_path`) |
+| C4 | high | fail-open | Function uses **dynamic SQL** (`EXECUTE` / `EXECUTE … USING` / `FOR … IN EXECUTE`) |
+
+C3 ships at `low` (adoption severity — ratchet to error once the tree is clean). C4 cannot be
+statically proven read-only, so every dynamic-SQL site is flagged and must be **waived inline with a
+categorized reason** (`lookup-only`, `codegen`); a reasonless waiver does not suppress it.
+
+**Inline suppressions** (ESLint/Prettier style), written as SQL comments inside the body:
+
+```sql
+-- safegres-disable-next-line no-dynamic-sql -- lookup-only: building an IN-list of integers
+EXECUTE format('SELECT ... WHERE id = ANY(%L)', ids);
+
+EXECUTE 'REFRESH MATERIALIZED VIEW app.mv';  -- safegres-disable-line no-dynamic-sql -- codegen: fixed DDL
+
+-- safegres-disable no-dynamic-sql -- lookup-only: this whole block probes the catalog
+...
+-- safegres-enable no-dynamic-sql
+
+-- safegres-disable-file no-set-search-path -- vendored extension shim
+```
+
+A directive with no rule id applies to every convention rule. Waived findings are **not dropped** —
+they surface as `acknowledged` (accepted-risk) findings carrying their reason, off the score.
+
+### Performance (11 rules, `--perf`)
+
+| Code | Severity | Check |
+| --- | --- | --- |
+| X1 | medium | **Foreign key with no covering index** — joins and cascading deletes seq-scan the child |
+| X2 | medium | **RLS policy filters on a column that leads no index** — the security qual seq-scans, for every caller |
+| X3 | medium | **Policy casts or wraps its own column** (`tenant_id::text = …`) with no matching expression index |
+| X4 | low | **Policy calls a non-LEAKPROOF function** — the qual can't be pushed below joins or subquery scans |
+| X5 | low | **Redundant index** — exact duplicate of, or leading-column prefix of, another |
+| X6 | low | **No primary key** and no usable replica identity |
+| X7 | medium | **Search column with no index the search can use** — `tsvector` without GIN/GiST, `vector` without HNSW/IVFFlat |
+| X8 | info | **Sort-shaped column leads no index** (`timestamptz`/`date`) — heuristic, scores 0 |
+| X9 | medium | **Policy calls a STABLE function per row** — not wrapped in a scalar sub-select, so no InitPlan |
+| P1 | high | Policy body calls a **VOLATILE function** — re-evaluated per row |
+| P1b | medium | Policy body calls a **STABLE function** in a per-row position |
+
+X2/X3/X4/X9 are the checks a generic index linter structurally cannot make, because they require
+the policy predicate's AST. RLS quals are evaluated **before** user quals, on every candidate row,
+for every caller — so an unindexed or cast-wrapped policy column is a whole-table tax rather than
+one slow query. This is where the two dimensions physically intersect, and why they belong in one
+tool.
+
+X9, measured on 200k rows with a policy function that counts its own invocations:
+
+| Policy qual | Calls | Time |
+| --- | --- | --- |
+| `other_id = current_principal_id()` (Filter) | 200,000 | 424 ms |
+| `other_id = (SELECT current_principal_id())` (InitPlan) | 1 | 22 ms |
+
+Four more rules (`S1`–`S4`) read runtime counters rather than the schema and are opt-in with
+`--stats`. Full rationale for every rule, including the access-path signals behind X1 and the
+plan-dependence caveat on X9: **[docs/rules.md](https://github.com/constructive-io/constructive/blob/main/packages/safegres/docs/rules.md)**.
 
 ## Exposure surface
 
-A database-wide score is meaningless if most of the database isn't reachable through the app's APIs. Declare (or auto-resolve) the **exposure surface** and safegres partitions findings:
+A database-wide score is meaningless if most of the database isn't reachable. Declare the
+**exposure surface** and safegres partitions every finding:
 
 - **Exposed** findings (on API-reachable schemas) drive the score.
-- **Internal** findings are reported as unscored *internal advisories* (hide entirely with `--exposed-only`).
-- **No exposure configured** → a `W1` warning is emitted and the score is capped at 80/B (`scoring.unknownExposureCap`).
+- **Internal** findings are reported as unscored advisories (`--exposed-only` hides them).
+- **No exposure configured** → `W1`, and the score is capped at 80/B (`scoring.unknownExposureCap`).
 
 ```jsonc
 {
   "exposure": {
-    "schemas": ["app_public", "app_hidden"]      // static surface
+    "schemas": ["app_public", "app_hidden"]   // static surface
     // or, on a Constructive database:
-    // "resolver": "constructive"                 // introspects routing_public.apis → api_schemas
+    // "resolver": "constructive"             // introspects routing_public.apis → api_schemas
   }
 }
 ```
 
-CLI: `--exposure-schemas <csv>`, `--exposed-only`. The `safegres:constructive` preset sets `exposure.resolver: "constructive"` so the surface is discovered automatically from the routing plane (including API roles from `role_name`/`anon_role`).
+The score improves by being **explicit** (declaring exposure and intent) or by **fixing** a leak —
+never by renaming. A `*_public` schema name is not a declaration; the config is.
+CLI: `--exposure-schemas <csv>`, `--exposed-only`.
 
-## Extension objects
+Two related declarations, both of which mark findings *acknowledged* (reported as info, excluded
+from the score): `public.read` for deliberately open reads (pricing tables, a public directory)
+and `perf.ignore` for accepted performance debt. Extension-owned relations are skipped by default,
+and an extension that creates objects at runtime can be skipped wholesale with
+`extensions.ignore` — see [docs/rules.md](https://github.com/constructive-io/constructive/blob/main/packages/safegres/docs/rules.md#extension-objects).
 
-An extension's tables are the `node_modules` of a database: they live in the same catalog, scan like anything else, and are not yours to alter — `ALTER TABLE` on one breaks `pg_dump` and upgrades. safegres skips relations an extension owns (`pg_depend.deptype = 'e'`), and their partitions, by default.
+### Planes: the other ways in
 
-Ownership alone is not enough. An extension that creates objects *at runtime* never registers them as dependencies: on one Constructive database only 2 of `pg_partman`'s 32 relations were owned, leaving 30 template tables looking like unsecured application tables (30 of the report's 39 criticals). Naming the extension skips its schema wholesale:
+An API is one way into a database, not the only one. Declare the others as **planes** and each
+gets its own grade — while the headline score stays exactly what it was:
 
 ```jsonc
 {
-  "extensions": {
-    "ignore": ["pg_partman"],   // skip everything in the extension's schema
-    "skipOwned": true           // default; false audits extension-owned relations too
+  "exposure": {
+    "schemas": ["app_public"],
+    "planes": [
+      { "name": "direct:reporting", "kind": "role", "roles": ["reporting"] },
+      { "name": "internal", "kind": "schema", "schemas": ["app_private"] }
+    ]
   }
 }
 ```
 
-CLI: `--ignore-extensions <csv>`, `--audit-extension-owned`. Unknown or uninstalled names are ignored, so one config works across environments. The `safegres:constructive` preset ships `ignore: ["pg_partman"]`.
+```
+score  87  (B)   security      ← still the declared API surface, unchanged
+other access planes — advisory, not part of the score above:
+  direct:reporting [role] (reporting): 41 (F)  — 12 relation(s), reached via grant
+  internal [schema] (app_private): 63 (D)  — 9 relation(s)
+```
 
-## Declared public surface
+A role plane is resolved through the same effective-access lattice the `L*` rules use — direct
+grants, `PUBLIC`, and role inheritance — so it answers the question a reviewer actually asks: *if
+this connection string leaks, what does it reach?* Roles with `BYPASSRLS` or superuser are
+reported as not graded rather than given a meaningless F.
 
-Some open reads are deliberate — pricing tables, reference data, a public user directory. Declare them and safegres treats them as intent instead of findings:
+Secondary planes never move the headline and never touch finding identity, so adding one cannot
+invalidate a baseline. They gate nothing unless you ask — `failOn.planes` takes a name or glob:
 
 ```jsonc
-{
-  "public": {
-    "read": [
-      "app_public.plans*",        // schema.table globs
-      "app_public.event_types",
-      "app_public.users"          // deliberate public directory
-    ]
-  }
-}
+{ "failOn": { "grade": "B", "planes": { "direct:*": { "grade": "D" } } } }
 ```
 
-- An open SELECT policy (`USING (true)` — rule A8) on a declared table is **acknowledged**: reported as info, excluded from the score.
-- An open read on any *undeclared* table stays a scored finding — even in a `*_public`-named schema. Naming is never treated as intent; the config declaration is.
-- `safegres doctor` warns about stale `public.read` patterns that no longer match any table.
-
-## Performance dimension (`--perf`)
-
-A slow database is a different problem from an unsafe one, so safegres scores them separately: `safegres perf` (or `safegres audit --perf`) adds `report.perf` with its own findings, summary, and 0-100 score. It is **off by default** — a plain `audit` behaves exactly as before, and no perf finding ever touches the security score.
-
-| Code | Severity | Category | Check |
-| --- | --- | --- | --- |
-| X1 | medium | index | **Foreign key with no covering index** — joins and cascading deletes seq-scan the child table |
-| X2 | medium | index | **RLS policy filters on an unindexed column** — the security qual seq-scans on every query against the table |
-| X3 | medium | index | **Policy casts or wraps its own column** (`tenant_id::text = …`, `lower(email) = …`) with no matching expression index |
-| X4 | low | index | **Policy calls a non-LEAKPROOF function** — the qual can't be pushed below joins or subquery scans |
-| X5 | low | index | **Redundant index** — an exact duplicate of, or a leading-column prefix of, another index |
-| X6 | low | index | **No primary key** and no usable replica identity — rows cannot be addressed by updates, deletes, or logical replication |
-| X7 | medium | index | **Search column with no index the search can use** — a `tsvector` without GIN/GiST, a `vector` without HNSW/IVFFlat |
-| X8 | info | index | **Sort-shaped column leads no index** (`timestamptz`/`date`) — ordering or cursor-paginating a connection by it sorts the whole table |
-| X9 | medium | index | **Policy calls a STABLE function per row** — the call isn't wrapped in a scalar sub-select, so the planner can't hoist it into an InitPlan |
-| P1 | high | anti-pattern | Policy body calls a **VOLATILE function** — re-evaluated per row |
-| P1b | medium | anti-pattern | Policy body calls a **STABLE function** in a per-row position |
+`--plane direct:reporting` (or `--plane '*'`) expands one in the terminal and markdown output;
+`--format json` always carries them all in `report.planes`.
 
-Every check is pure catalog + AST analysis: deterministic, workload-free, and safe to run against an empty CI database. An index covers a foreign key only when its *leading* columns are the FK's columns and it covers every row — partial and expression indexes don't count, because the planner can't use them for the referential-integrity lookup. Constraint-backed, unique, partial, and expression indexes are never reported as redundant.
+### Adapters
 
-X7 exists because the column type *is* the API declaration: `graphile-search` exposes a full-text filter for every `tsvector` column and a similarity search for every `vector` column, purely from the codec — so an unindexed one is a first-class API field backed by a sequential scan plus a per-row match or distance computation. BM25 and pg_trgm are deliberately not checked: those adapters are discovered *from* their indexes, so a missing index means the feature was never exposed. X8 is the one heuristic in the set — any column is orderable over a connection, but timestamps are what feeds are actually sorted and keyset-paginated by — so it defaults to `info`, contributes 0 to the score, and is meant to be read, not gated on (`perf.rules: { "X8": "off" }` to silence it). Trailing-position and partial indexes don't count for either rule: neither can serve the sort or the search on its own.
+Where the exposed surface comes from is an interface, not a hard-coded integration. An adapter is
+an object — no plugin resolution, nothing load-bearing about a package name:
 
-### Access paths: the evidence behind X1
+```ts
+// safegres.config.ts
+import type { SafegresConfig } from 'safegres';
+import { constructiveAdapter } from 'safegres/adapters';
 
-X1 is right about the mechanics — a `DELETE` on the parent really does scan the child — but it assumes the child is a relation somebody traverses. On a provisioning-config table, one whose keys are written once at setup and never looked rows up by, the index it asks for is a write on every insert in exchange for speeding up a scan of one row. Acting on X1 across such a schema makes the database measurably worse while the grade goes up.
+import { myGatewayAdapter } from './my-gateway-adapter';
 
-The tempting gate, `pg_class.reltuples`, doesn't work here: safegres grades an ephemeral CI database that has never held data, so every row estimate is 0 at exactly the moment it grades. And row count is the wrong question anyway — a huge append-only log nobody joins on wants no FK index, while a tiny lookup table every request hits does. The property that matters is whether anything reads the key, which is structural, so it survives an empty database.
+const config: SafegresConfig = {
+  exposure: { adapters: [constructiveAdapter, myGatewayAdapter] }
+};
+export default config;
+```
 
-So safegres collects **signals** about every foreign key, each pointing one way and saying why, and reports them on the finding (`context.pathSignals`) and in aggregate (`report.perf.paths`):
+```ts
+interface ExposureAdapter {
+  name: string;
+  detect(exec: QueryExecutor): Promise<boolean>;      // is this stack present?
+  resolve(exec: QueryExecutor): Promise<PlaneInput[]>; // one or more planes
+  reach?(exec: QueryExecutor, ctx: ReachContext): Promise<ApiReach>; // optional precision
+}
+```
 
-| Signal | Direction | Fires when |
-| --- | --- | --- |
-| `policy-read` | read | an RLS policy predicate names one of the key's columns |
-| `view-read` | read | a view or materialized view names one of them |
-| `write-once-pointer` | shape | every column of the key has a constant default (`uuid_nil()`, a literal) |
-| `config-record` | shape | the table carries two or more write-once pointers (`perf.paths.minPointers`) |
+Built-ins ship for `constructive`, `postgrest`, `supabase`, `hasura` and `graphile` — each reading
+the signal its stack actually leaves in the catalog (see [Configuration](#configuration)), and
+each emitting a primary `api` plane plus whatever secondary planes it can prove: one `api:<name>`
+per API for Constructive, a `direct:<authenticator>` role plane for PostgREST, `app_private` as an
+internal plane for graphile-starter. `postgraphile` is the exception: it contributes no plane at
+all and only supplies [reach](#api-reach--the-relations-the-api-can-actually-name). JSON configs may name a built-in
+(`"adapters": ["supabase"]`); anything else is an error rather than a silent no-op — a typo'd
+adapter would otherwise present as an unexposed database. The old `"resolver": "constructive"`
+still works.
 
-A **read** signal is decisive — the database itself traverses the column, so the key is a query path and X1 applies as written. That is what keeps the tenant key out of trouble with no special case: `database_id` appears in essentially every policy. A **shape** signal is not: a `NOT NULL` key defaulting to the nil UUID looks like a slot a provisioner fills in, but a generated API can expose a reverse relation over any foreign key regardless of how its default is written, and if it does, the index is wanted after all.
+### API reach — the relations the API can actually name
 
-So by default the shape **changes nothing** — no finding is removed, no severity moves, no score shifts. What it does is tell you where to look, and `perf.paths.onWriteOncePointer` decides what X1 does about it:
+A plane made of schemas answers *is this relation in the API's schemas?*, which over-counts: a
+generated API exposes fields, and a schema routinely holds relations it deliberately does not
+surface — join tables, denormalized shadows, machine-only back-pointers. `reach()` is where an
+adapter narrows a plane from its schemas to its **relations**. The built-in `postgraphile` adapter
+reads the `@behavior` / `@forwardBehavior` / `@backwardBehavior` smart tags to do it, and both
+`graphile` and `constructive` delegate to it — those two answer *which schemas are served*, which
+is a different question from *what the served schemas expose*:
 
-- `report` (default) — the finding stands, with the signals attached to it;
-- `demote` — write-once-shaped keys drop to `info`, so they are read rather than gated on and contribute nothing to the score;
-- `suppress` — no finding. Only defensible once you know the generated API does not expose these relations; a shape is not a proof.
+```jsonc
+{ "exposure": { "schemas": ["app_public"], "adapters": ["postgraphile"] } }
+```
 
-The signal that *would* settle it is the one that isn't here yet: whether the generated GraphQL surface still contains the field. It slots in as another signal, and only then does "nothing can reach this key" become a conclusion anything should act on. `perf.paths.infer: false` skips the collection entirely.
+Three properties keep it from quietly deleting findings:
 
-X2–X4 and X9 are the checks a generic index linter can't make, because they read the policy predicate. RLS quals are evaluated *before* user quals, on every candidate row, for every caller — so an unindexed or cast-wrapped policy column is a whole-table tax rather than a slow query. X2 requires the policy column to be the *leading* column of some index (a trailing position can't serve the qual alone); X3 looks for an expression index matching the exact wrapped shape; X4 skips built-ins, whose leakproofness is a property of the server rather than a schema choice.
+- **Only an explicit denial counts.** Presets grant most behaviors by default, so the *absence* of
+  `+list` says nothing. Silence is never read as denial.
+- **Unreachable means unreachable by every route.** A relation with no root entry is still
+  addressable by traversing a relation field from one that has, so reach is graph traversal over
+  foreign keys, not a per-table test. Hiding one reverse relation is one missing path, not proof.
+- **A role plane is never narrowed.** The API not exposing a table says nothing about a role
+  holding a direct connection. Behavior only ever refines `api`/`schema` planes.
 
-X9 is the one that costs the most and looks the most innocent. `STABLE` promises a function's result won't change within the statement; it does **not** make the planner evaluate it once. Measured on 200k rows with a policy function that counts its own invocations:
+Anything subtracted is listed in `report.exposure.unaddressable` rather than silently dropped, and
+`"reach": false` turns the whole thing off. Where an API-edge role still holds privileges on a
+relation its own API cannot name, **L6** reports the grant — unless some RLS policy predicate
+references the relation, since a grant a policy subqueries under the querying role is load-bearing
+however invisible it is to the API.
 
-| Policy qual | Calls | Time |
-| --- | --- | --- |
-| `other_id = current_principal_id()` (Filter) | 200,000 | 424 ms |
-| `other_id = (SELECT current_principal_id())` (InitPlan) | 1 | 22 ms |
+## CI in one job
 
-The honest caveat: the penalty is **plan-dependent**. When the planner can turn the qual into an index condition it evaluates the function once per scan even unwrapped — so the same policy costs one call on an indexed column and 200,000 on a Filter (unindexed column, a join, an OR branch, a plan change after `ANALYZE`). Wrapping removes the dependence: `(SELECT f())` references no column, so it is hoisted into an **InitPlan** and evaluated once per query whatever plan is chosen, and the result is a constant the index can be probed with. X9 is structural, not a name list — it fires on any non-IMMUTABLE call whose arguments reference no column of the row and that isn't already inside an uncorrelated scalar sub-select, so a GUC-reading helper added next year is caught without configuration. `current_setting()` itself is STABLE and is flagged too: removing the wrapper function doesn't avoid the per-row call. VOLATILE calls are deliberately excluded — per-row evaluation is their defined behaviour, and hoisting one would change semantics (that's P1's job). Being inside an `EXISTS` sub-select is not a defence: that subquery is correlated with the outer row, so it runs per row and takes the call with it.
+One service container, your existing migration command, one audit:
 
-```bash
-safegres perf --database mydb
-safegres audit --database mydb --perf --fail-on-perf-grade B
-```
+```yaml
+jobs:
+  database-audit:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env: { POSTGRES_PASSWORD: postgres }
+        options: --health-cmd pg_isready --health-interval 5s --health-retries 10
+        ports: ['5432:5432']
+    env:
+      PGHOST: localhost
+      PGUSER: postgres
+      PGPASSWORD: postgres
+      PGDATABASE: app_audit
+    steps:
+      - uses: actions/checkout@v4
+      # …install deps, then apply your schema with whatever already builds it:
+      #   rails db:schema:load · manage.py migrate · prisma migrate deploy
+      #   drizzle-kit push · sqitch deploy · pgpm deploy · psql -f schema.sql
+      - run: npx safegres audit --perf --format markdown >> "$GITHUB_STEP_SUMMARY"
+      - run: |
+          npx safegres audit --perf --summary \
+            --fail-on-grade B \
+            --perf-baseline ci/safegres-perf-baseline.json --fail-on-new-perf
+```
+
+Everything a job repeats every run belongs in the config file instead, so the job is one word. A
+repository whose schema is a pgpm workspace does not need a database at all — `source.pgpm`
+deploys it into an ephemeral one:
 
 ```jsonc
+// .safegresrc.json — paths are relative to this file
 {
-  "perf": {
-    "enabled": true,
-    "rules": { "X6": "off" },          // perf-dimension codes only
-    "ignore": ["app_public.audit_*"],  // declared-intentional perf debt
-    "paths": { "onWriteOncePointer": "report" }, // signals are reported, not acted on (default)
-    "scoring": { "densityK": 0.17 }
-  },
-  "failOn": { "perfGrade": "B" }
+  "extends": "safegres:constructive",
+  "source":  { "pgpm": "application/app" },
+  "perf":    { "enabled": true, "baseline": "ci/perf-baseline.json", "failOnNew": true },
+  "outputs": { "dir": "safegres-reports" },
+  "failOn":  { "grade": "B" }
 }
 ```
 
-Tables matched by `perf.ignore` are acknowledged — reported as info, excluded from the perf score — the same way `public.read` works for open reads. Perf findings live in `report.findings` alongside the security ones (so `--fail-on <severity>` still sees them), but only they feed `report.perf.score`, and only security findings feed `report.score`.
+```yaml
+      - run: npx safegres audit   # or: "audit": "safegres lint" in package.json
+```
+
+`outputs.dir` writes `safegres.json`, `safegres.md` and `safegres.sarif` into one directory — name
+an individual file (`outputs.json`) only when the name matters. Directories are created as needed,
+and a flag still wins over the file for a one-off run (`safegres audit --out reports`). Naming a
+connection wins too, so the same config audits a database you already have:
+`safegres audit --database staging`.
+
+Scores lead the markdown, then severity counts, then a table per dimension; internal advisories
+and accepted baseline debt fold into `<details>`. Pipe it to `gh pr comment --body-file -` to post
+it on the pull request instead. Library callers get the same renderer as `renderMarkdown(report)`.
 
-### Perf baseline (the ratchet)
+`--format sarif` turns findings into GitHub code-scanning alerts, and `--compare` renders the
+delta against a previous run's JSON. Both in **[docs/reporting.md](https://github.com/constructive-io/constructive/blob/main/packages/safegres/docs/reporting.md)**.
 
-An established schema will not reach a clean perf report in one pass — but it can refuse to get worse. Commit today's findings as accepted debt, then gate CI on findings that are *not* in the baseline:
+## The ratchet
+
+An established schema will not be clean on the first run — but it can refuse to get worse. Commit
+today's performance findings as accepted debt and gate on what is *not* in the baseline:
 
 ```bash
-safegres audit --write-perf-baseline .safegres-perf.json          # snapshot (implies --perf)
-safegres audit --perf-baseline .safegres-perf.json                # diff: new vs accepted vs fixed
-safegres audit --perf-baseline .safegres-perf.json --fail-on-new-perf   # gate: exit 1 on new debt
+safegres audit --write-perf-baseline ci/safegres-perf-baseline.json   # snapshot (implies --perf)
+safegres audit --perf-baseline ci/safegres-perf-baseline.json         # diff: new / accepted / fixed
+safegres audit --perf-baseline ci/safegres-perf-baseline.json --fail-on-new-perf   # gate
 ```
 
 ```
@@ -264,171 +448,254 @@ performance vs baseline:
   (14 accepted, 2 fixed)
 ```
 
-Entries are identified by `code` + relation + policy + subject (the constraint, index, expression, column, or function the finding is about), so rewording a message or retuning a severity between safegres versions never invalidates a committed baseline, and two findings of the same code on the same table stay distinct. Findings that disappear are reported as fixed — re-run `--write-perf-baseline` to lock the win in and stop them regressing silently. The diff is also carried in JSON output as `perf.diff`, and available to library callers as `diffPerf(findings, baseline)`.
+Entries are keyed by finding *identity* — `code` + relation + policy + subject (the constraint,
+index, expression, column or function it is about) — never by message text, so rewording a rule or
+retuning a severity in a later release cannot invalidate a committed baseline. Findings that
+disappear are reported as fixed; re-baseline to lock the win in.
 
-### Runtime statistics (`--stats`)
+On an established schema this is the enforceable gate, and a perf *grade* gate is not: a score
+dominated by inherited debt either fails forever or means nothing. Security has no baseline —
+gate it on a grade you can hold today and raise it as the score climbs.
 
-The `X*` rules read the schema; the `S*` rules read what the workload actually did to it. They come from `pg_stat_user_tables`, `pg_stat_user_indexes` and — when the extension is installed — `pg_stat_statements`, so they only mean something against a database that has served representative traffic. Opt in with `--stats` (which implies `--perf`):
+The same mechanism exists for call-graph trust boundaries (`--write-baseline`, `--baseline`,
+`--fail-on-new-boundaries`).
 
-| Code | Severity | Check |
-| --- | --- | --- |
-| S1 | medium | **Sequential-scan-dominant table** — seq scans outnumber index scans 10:1 on a table with indexes and ≥ 1000 live rows |
-| S2 | low | **Index the planner has never chosen** (`idx_scan = 0`) and larger than 1 MiB — pure write cost, unless it's there for a rare report |
-| S3 | low | **Dead-tuple bloat** — dead tuples ≥ 20% of live rows; autovacuum is not keeping up |
-| S4 | info | **Statement hotspot** — a statement taking ≥ 5% of sampled execution time whose relations are in scope |
+## Sealed runs
+
+Every knob above is deliberate when a team declares its intent in CI, and is the cheapest possible
+cheat when a *score* is the thing being evaluated — of an agent's migration, of a template, of a
+submission. Turning off the rule and re-baselining the debt both raise the number without touching
+the database.
 
-Every threshold is a floor, and every floor is configurable, because a counter is only evidence if there is enough of it:
+So every report carries the ruler it was measured with:
 
 ```jsonc
-{
-  "perf": {
-    "stats": {
-      "minRows": 1000,          // S1/S3: below this a scan is the right plan
-      "seqScanRatio": 10,       // S1: seq:idx scan ratio that counts as dominant
-      "minIndexBytes": 1048576, // S2: ignore indexes too small to be worth dropping
-      "deadTupleRatio": 0.2,    // S3
-      "minTimeShare": 0.05,     // S4: share of total sampled time
-      "topStatements": 5        // S4: cap
-    },
-    "scoring": { "includeStats": false }   // demote S* to advisories
-  }
+"provenance": {
+  "version": "1.17.0",
+  "fingerprint": "sha256:8f14e45fceea167a…",   // over the *resolved* rules, overrides,
+  "sealed": true,                              // scoring weights, exposure and ignores
+  "preset": "strict"
 }
 ```
 
-`S*` findings are **scored** on the perf axis — asking for `--stats` is the opt-in — but `perf.scoring.includeStats: false` demotes them to advisories if you want the grade to stay purely deterministic. The report carries its own provenance in `perf.stats`: how many tables were read, when the counters were last reset (the window the numbers describe), whether they were scored, and a note when `pg_stat_statements` isn't installed. Absent statistics are never an error; the audit just says so.
-
-### Planner proof (`--explain`)
-
-The `X*` rules *infer* from the catalog that nothing can serve a query shape. `--explain` asks the database instead: for each probeable finding it plans the query the finding is a claim about with `EXPLAIN (GENERIC_PLAN, FORMAT JSON)` — nothing is executed, and parameters stay parameters, so no value has to be invented for a column — and attaches the plan as `finding.evidence`.
-
-The interesting outcome is disagreement. A finding whose probe plans as an index scan is **refuted**: some index the catalog rules didn't credit (a hash index on an FK column, say) does serve it, so the finding is acknowledged, reported as info, and dropped from the perf score. The reverse is deliberately not symmetrical — an empty or unanalyzed table always seq-scans, so a seq scan **confirms** a finding only above a planner row estimate of 1000 (`perf.explain.minRows`); below that the probe is `inconclusive` and the finding is left exactly as the static rule made it.
+`--sealed` grades under a built-in preset alone: no config-file discovery, and `--config`,
+`--rule`, `--exposure-schemas` and every baseline flag are *refused* rather than ignored — a run
+that silently dropped a flag would report a number for rules nobody chose. A harness pins the
+answer it expects:
 
 ```bash
-safegres audit --perf --explain --database mydb
+safegres audit --sealed --preset strict --verify-fingerprint sha256:8f14e45fceea167a… --format json
 ```
 
-```
-[medium] X1  app_public.posts
-    foreign key posts_author_id_fkey has no covering index
-    plan (confirmed): Seq Scan
-[info] X1  app_public.notes
-    foreign key notes_author_id_fkey has no covering index — refuted by EXPLAIN (the planner serves this shape with an index)
-    plan (refuted): Bitmap Heap Scan → Bitmap Index Scan
-  planner proof: 1 confirmed, 1 refuted, 1 inconclusive of 3 probed
-```
-
-Probes exist for X1, X2, X7 and X8 — the rules that name a query shape. X5, X6, `P*` and `S*` are claims about the schema or the workload rather than a plan, so nothing is planned speculatively on their behalf. `GENERIC_PLAN` requires PostgreSQL 16+; on older servers the audit reports `perf.explain.unavailable` and leaves the findings untouched.
+The fingerprint covers the resolved rule set rather than the config text, so it is invariant to how
+a posture was spelled (preset vs. explicit rules, key order) and sensitive to anything that changes
+it — including the safegres version, because a rule's meaning can change without its configuration
+changing. Reports whose fingerprints differ are not comparable, and `--verify-fingerprint` exits
+non-zero rather than let one be read as if it were.
 
-## Call graph (`--call-graph`)
+None of this constrains ordinary use: an unsealed run still gets a fingerprint, and `sealed: false`
+is simply the honest statement that local configuration participated.
 
-RLS findings tell you what the *tables* allow. The call graph tells you what the *functions* reach: starting from the exposed entry points (functions the API roles can `EXECUTE`), safegres statically walks each body and lists every **trust boundary** on the way — unscored, because a public `SECURITY DEFINER` calling private functions is the intended pattern (that's how `sign_in` works). The output is a deterministic checklist for human review:
+## The evaluation corpus
 
-| Code | Boundary |
-|------|----------|
-| CF1 | `SECURITY DEFINER` without a pinned `search_path` (CWE-426) — provable misconfiguration, fix these |
-| CF2 | `SECURITY DEFINER` executable by `anonymous`/PUBLIC — widest blast radius, confirm intent |
-| CG2 | RLS-bypass path — a DEFINER's owner owns (or bypasses RLS on) a table it touches, so RLS does not protect that table on this path |
-| CG3 | Auth-context mutation — a reachable function writes `jwt.claims.*` / `role` |
-| CG1 | Trust hop — execution crosses into a `SECURITY DEFINER` (you are trusting its author's authorization logic) |
-| CG4 | Internal reach — a non-exposed table is reached from a public entry via a DEFINER path |
-| CG5 | Opaque node — dynamic SQL (`EXECUTE`) or an unparseable body; static analysis ends here, audit manually |
+A sealed score says the ruler did not move. It does not say the ruler is right. That is what the
+corpus in [`corpus/`](corpus/README.md) is for: ~20 small schemas, each with one deliberate flaw
+and a written-down answer — the findings a correct audit must produce, the false positives it must
+not, and the one-sentence fix.
 
-```bash
-safegres audit --database mydb --call-graph
-```
+`safegres eval` is the whole loop in one command: it deploys each case into the connected
+database, audits it under a sealed preset, grades the report against the answer key, drops the
+case's schemas again, and exits non-zero if any case fails.
 
-```
-call graph — trust boundaries reachable from the exposed surface (unscored; human review)
-  2 entry point(s) → 4 reachable function(s)  |  3 trust hop(s)  1 RLS-bypass  1 auth-context  1 internal-reach  1 opaque
+```console
+$ safegres eval --database scratch
+  PASS  01-anon-write-grant              security 1.2 (F )  R1
+  PASS  17-foreign-key-without-index     perf    71.2 (C )  X1
+  FAIL  18-policy-column-unindexed       perf     100 (A+)  missed X2
 
-CG2 — RLS-bypass paths (RLS does not protect the table on this path) (1)
-  • fx_cg_private.verify_password → fx_cg_private.users
-      RLS on fx_cg_private.users does not apply on this path — fx_cg_private.verify_password is SECURITY DEFINER running as postgres (BYPASSRLS/superuser)
-      via: fx_cg_public.sign_in → fx_cg_private.verify_password
+25/26 cases passed · recall 98% · precision 100%
 ```
 
-Bodies are analyzed for `sql` and `plpgsql` functions (via the PL/pgSQL parser); overloads collapse into one node per `schema.name`; unqualified calls resolve to every user function with that name (a conservative over-approximation). JSON output (`--format json`) carries the full graph — nodes, edges, and checklist — sorted stably so it can be snapshotted and diffed in CI.
-
-### Baseline diffing (CI gate for new trust boundaries)
+| Flag | |
+| --- | --- |
+| `--preset <name>` | the preset every case is graded under (default `recommended`) |
+| `--corpus <dir>` | your own corpus of `<id>/{case.json,schema.sql}` |
+| `--case <id>` | run one case, or an id prefix — comma-separated |
+| `--list` | print the corpus without touching a database |
+| `--json` | the `EvalReport`: per-case recall, precision, score, fingerprint |
+| `--keep` | leave the case schemas behind, to poke at one by hand |
 
-Snapshot the checklist once, commit it, and let CI report anything **new**:
+A config file may set `eval.corpus`, `eval.preset` and `eval.cases` — *what* to run. It cannot
+retune the rules for a run: cases are always graded by the named preset alone, or the corpus would
+be grading itself. The same loop is a library call (`runEval`), and its pieces are public:
 
-```bash
-safegres audit --write-baseline .safegres-callgraph.json   # snapshot (implies --call-graph)
-safegres audit --baseline .safegres-callgraph.json         # diff: report new/resolved boundaries
-safegres audit --baseline .safegres-callgraph.json --fail-on-new-boundaries   # gate: exit 1 on new
-```
+```ts
+import { audit, gradeCase, loadConfig, loadCorpus } from 'safegres';
 
-```
-baseline: 1 NEW trust boundary — review and re-baseline to accept:
-  + [CF2] app_public.new_fn
-        SECURITY DEFINER executable by PUBLIC, anonymous — widest blast radius; confirm this is intended
+const { config } = loadConfig({ sealed: true, preset: 'recommended' });
+for (const c of loadCorpus()) {
+  await client.query(c.sql);
+  const { missed, falsePositives } = gradeCase(await audit(client, { config, ...c }), c);
+}
 ```
 
-The baseline stores only boundary *identity* (`code` + entry + function + table), so message rewording and path changes between safegres versions never invalidate it. A boundary that disappears is reported as resolved; re-run `--write-baseline` to accept either direction. The diff is also carried in JSON output (`callGraphDiff`).
+Cases are data — `schema.sql` plus a `case.json` answer key — so a harness that never runs safegres
+can still use them. Three uses: safegres's own regression suite, worked examples short enough to
+read, and an agent evaluation — hand the agent a case, ask for a fix, and require the expected
+findings to be *gone* with the dimension back at 100 rather than merely a better number.
 
 ## Configuration
 
-safegres is configurable like a linter. Config is discovered by walking up from the current directory: `safegres.config.{ts,js,mjs,cjs}`, `.safegresrc{,.json,.yaml,.yml,.js}`, `safegres.json`, or a `"safegres"` key in package.json (via [confstash](https://github.com/constructive-io/dev-utils/tree/main/packages/confstash)).
+Configured like a linter. Discovered by walking up from the current directory:
+`safegres.config.{ts,js,mjs,cjs}`, `.safegresrc{,.json,.yaml,.yml,.js}`, `safegres.json`, or a
+`"safegres"` key in `package.json` (via
+[confstash](https://github.com/constructive-io/dev-utils/tree/main/packages/confstash)).
+Precedence: **CLI > project config > preset > built-in defaults**.
 
 ```jsonc
 // .safegresrc.json
 {
   "extends": "safegres:recommended",
-  "excludeSchemas": ["archive"],
+  "exposure": { "schemas": ["app_public"], "roles": ["anonymous", "authenticated"] },
+  "public": { "read": ["app_public.plans*", "app_public.event_types"] },
+  "extensions": { "ignore": ["pg_partman"] },
   "rules": {
-    "A3": "off",            // disable a rule
-    "A5": "high",           // retune a severity
-    "P*": "medium"          // prefix wildcards
+    "A3": "info",         // demote — still reported, contributes nothing
+    "A5": "high",         // retune a severity
+    "A7": "off",          // disable outright
+    "P*": "medium"        // prefix wildcard (exact codes win)
   },
   "overrides": [
-    { "tables": ["public.audit_*"], "rules": { "A2": "off" } }
+    { "tables": ["app_public.audit_*"], "rules": { "A2": "off" } }
   ],
-  "scoring": { "weights": { "medium": 2 } },
-  "failOn": { "severity": "high", "grade": "B" }
+  "perf": { "enabled": true, "ignore": ["app_public.audit_*"], "rules": { "X6": "off" } },
+  "scoring": { "densityK": 0.17, "unknownExposureCap": 80 },
+  "failOn": { "grade": "B", "perfGrade": "B" }
 }
 ```
 
-Or typed:
+A typed `safegres.config.ts` with `defineConfig` from `confstash` works identically.
 
-```ts
-// safegres.config.ts
-import { defineConfig } from 'confstash';
+Presets come in three kinds, and they compose. A **stack** preset knows how your framework
+declares exposure and what its role names mean; a **posture** preset says how harshly to read
+what it finds; both are just partial configs, so `extends` takes an array:
 
-export default defineConfig({
-  extends: 'safegres:constructive',
-  rules: { A6: 'low' }
-});
+```jsonc
+{ "extends": ["safegres:supabase", "safegres:multi-tenant"] }
 ```
 
-### Presets
+| Stack | Resolves exposure from | Treats as untrusted |
+| --- | --- | --- |
+| `safegres:constructive` | `routing_public.apis` → `api_schemas` → `metaschema_public.schema` | `anonymous` |
+| `safegres:postgrest` | `pgrst.db_schemas` in `pg_db_role_setting` | `pgrst.db_anon_role` |
+| `safegres:supabase` | the GUCs if self-hosted, else Supabase's fixed surface | `anon`, `authenticated` |
+| `safegres:hasura` | tracked tables in `hdb_catalog` | `anonymous`, `public` |
+| `safegres:graphile` | the `graphile-starter` layout (`app_public` + `app_hidden`) | `<app>_visitor` |
+
+Each reads a real catalog signal — not a schema name. Two carry a caveat worth knowing:
+
+- **`graphile`** — PostGraphile's schema list is a process argument that leaves no trace in the
+  database, so this preset resolves the starter layout by convention. Naming it *is* the
+  declaration that the convention holds; when it doesn't, `exposure.schemas` still wins.
+- **`supabase`** — Supabase configures PostgREST outside the database, so the GUCs are usually
+  absent. Its adapter falls back to the platform's fixed surface, but only after proving it is
+  looking at Supabase (`auth.users` plus the `anon`/`authenticated`/`service_role` trio). The
+  fallback lives in that adapter alone: plain `postgrest` never guesses, and an unconfigured
+  PostgREST resolves nothing — reported as unknown exposure, not as a surface.
+
+Untrusted roles are usually *resolved*, not named. `pgrst.db_anon_role` and graphile's
+`<app>_visitor` are per-deployment, so those presets point the rules at the surface instead of
+guessing a name:
+
+```jsonc
+{ "rules": { "R1": ["critical", { "rolesFrom": "anon" }] } }
+```
+
+An adapter resolves two role sets, because "at the API edge" and "reachable without credentials"
+are different questions:
+
+| `rolesFrom` | Roles | Use when |
+| --- | --- | --- |
+| `anon` | Only what an unauthenticated caller arrives as — `apis.anon_role`, `pgrst.db_anon_role`, Supabase's `anon`, graphile's visitor | Almost always. A signed-in role holding a write grant is the product; the anon role holding one is the bug. |
+| `exposure` | Every role at the edge, signed-in ones included | A surface where no role should be writing directly. |
+
+Both union with any explicit `roles`, so a preset can name a platform default *and* pick up a
+custom one. Rules that ask for neither stay inert — resolved roles never leak into a rule that
+didn't opt in. `report.exposure.anonRoles` carries the anonymous subset, and the pretty renderer
+marks it inline (`api roles: authenticated, anonymous (anon)`).
 
-| Preset | Behavior |
+| Posture | Behavior |
 | --- | --- |
 | `safegres:recommended` | Every rule at its default severity (the no-config behavior) |
-| `safegres:strict` | Everything escalated; fail-closed findings count 25% toward the score, `failOn: high` |
-| `safegres:constructive` | Auto-resolves exposure from the routing plane; R1/R2 watch `anonymous`; leak surfaces (A2, P5) critical; A3 off (API roles never own tables); `pg_partman`'s schema ignored |
-| `safegres:minimal` | Structural flags only (A1–A3) — fast CI smoke check |
+| `safegres:strict` | Everything escalated; fail-closed counts 25%; `failOn: high` |
+| `safegres:multi-tenant` | Row-visibility rules (A1/A2, L1–L3, L5) escalated — in a shared-table database an RLS gap is a cross-tenant read; one critical floors the grade at D |
+| `safegres:oltp` | Perf axis first: the policy-shape rules that turn an index scan into a per-row function call (X2–X4, X9) escalated; `failOn: perfGrade C` |
+| `safegres:minimal` | Structural flags only (A1–A3) — fast smoke check |
+
+Presets **retune**, they don't delete: a rule that doesn't apply to a stack is demoted to `info`
+(zero weight, so the score is unchanged) rather than switched off, so it stays in the report and
+stays re-tunable. `minimal` is the deliberate exception — being a smoke check is its whole job.
 
 CLI: `--config <path>`, `--preset <name>`, `--rule CODE=off|severity` (repeatable).
 
-### Scoring
+## Scoring
 
-Every report includes a config-driven score (0–100 + grade). The default **density** model normalizes by the exposed surface so large schemas don't saturate to 0/F:
+Each dimension is scored independently by the same function over disjoint finding sets. The
+default **density** model normalizes by the exposed surface, so a large schema doesn't saturate
+to 0/F:
 
 ```
 score = 100 · exp(−k · riskPoints / exposedTables)
 ```
 
-where `riskPoints` is the severity-weighted sum (critical 25, high 10, medium 4, low 1, info 0) of *exposed, fail-open* findings, and `k` defaults to 0.17 (≈ one critical per 10 exposed tables lands at a C). Non-exposed findings score 0; fail-closed findings score 0 unless `scoring.failClosedWeight` is raised; unknown exposure caps the score (`scoring.unknownExposureCap`, default 80). Any exposed critical floors the grade at C (`scoring.floorOnCritical`). The legacy flat-deduction model is available via `scoring.model: "weighted"`. Tune via `scoring.weights`, `scoring.perRuleWeights`, `scoring.densityK`, `scoring.gradeBands`. Gate CI with `--fail-on-score <n>` / `--fail-on-grade <g>` or `failOn` in config.
+`riskPoints` is the severity-weighted sum (critical 25, high 10, medium 4, low 1, info 0) of
+*exposed, fail-open, non-acknowledged* findings; `k` defaults to 0.17 (≈ one critical per ten
+exposed tables lands at a C). Non-exposed findings score 0; fail-closed findings score 0 unless
+`scoring.failClosedWeight` is raised; unknown exposure caps the score; any exposed critical floors
+the grade at C (`scoring.floorOnCritical`). Grades: A+ 97 · A 90 · B 80 · C 65 · D 50 · F below.
+The legacy flat-deduction model is `scoring.model: "weighted"`.
+
+Every report carries its own arithmetic: per-rule points, grade, and the **payoff** — how far the
+score would move if that rule's findings went away. Gate with `--fail-on <severity>`,
+`--fail-on-score <n>`, `--fail-on-grade <g>` and their `--fail-on-perf-*` counterparts.
 
-### Other commands
+## Commands
 
 ```bash
-safegres doctor        # diagnose config, parser, connection, catalog access, blind spots
-safegres print-config  # show the resolved effective config (--explain for per-key provenance)
+safegres audit          # audit the connected database (default command)
+safegres lint           # alias for audit, for a package.json script
+safegres perf           # audit + the performance dimension (= audit --perf)
+safegres doctor         # diagnose config, parser, connection, catalog visibility, exposure
+safegres eval           # grade the auditor against a corpus with known answers
+safegres print-config   # the resolved effective config (--explain for per-key provenance)
 ```
 
+| Group | Flags |
+| --- | --- |
+| Connection | `--connection <url>`, `--host`, `--port`, `--user`, `--password`, `--database`, `--pgpm [dir]` |
+| Config | `--config <path>`, `--preset <name>`, `--rule CODE=sev` |
+| Exposure | `--exposure-schemas <csv>`, `--exposed-only` |
+| Scope | `--schemas`, `--exclude-schemas`, `--roles`, `--exclude-roles`, `--ignore-extensions`, `--audit-extension-owned` |
+| Performance | `--perf`, `--stats`, `--explain`, `--perf-baseline <f>`, `--write-perf-baseline <f>`, `--fail-on-new-perf` |
+| Reporting | `--format pretty\|json\|json-pretty\|markdown\|sarif`, `--out <dir>`, `--sarif-sources <dir>`, `--summary`/`-q`, `--verbose`, `--compare <f>`, `--compare-ref <label>`, `--write-snapshot <f>` |
+| Call graph | `--call-graph`, `--baseline <f>`, `--write-baseline <f>`, `--fail-on-new-boundaries` |
+| Gating | `--fail-on <severity>`, `--fail-on-score <n>`, `--fail-on-grade <g>`, `--fail-on-perf-score`, `--fail-on-perf-grade`, `--report-only` |
+| Misc | `--skip-ast`, `--no-color`, `--help`, `--version` |
+
+The paths among those — `--pgpm`, the two baselines, and every `--write-*` — have config-file
+equivalents (`source.pgpm`, `perf.baseline`, `callGraph.baseline`, `outputs.dir`/`outputs.*`), so CI can carry
+them in version control rather than in a command line.
+
+## Going further
+
+- **[docs/rules.md](https://github.com/constructive-io/constructive/blob/main/packages/safegres/docs/rules.md)** — every rule's rationale: the lattice semantics, the access-path
+  signals behind X1, the X7/X8/X9 arguments, extension objects.
+- **[docs/reporting.md](https://github.com/constructive-io/constructive/blob/main/packages/safegres/docs/reporting.md)** — SARIF and code scanning, `--compare` deltas and snapshots.
+- **[docs/advanced.md](https://github.com/constructive-io/constructive/blob/main/packages/safegres/docs/advanced.md)** — runtime statistics (`--stats`), planner proof
+  (`--explain`), library use, pgpm workspaces.
+- **[docs/call-graph.md](https://github.com/constructive-io/constructive/blob/main/packages/safegres/docs/call-graph.md)** — the trust-boundary checklist (`--call-graph`) and
+  its baseline.
+
 ## Library use
 
 ```ts
@@ -439,47 +706,24 @@ import { audit, renderPretty } from 'safegres';
 const client = new Client(getPgEnvOptions());
 await client.connect();
 
-const report = await audit(client, {
-  excludeSchemas: ['my_private_schema']
-});
-
+const report = await audit(client, { perf: true });
 console.log(renderPretty(report));
-console.log(`${report.findings.length} findings`);
-```
-
-## pgpm projects
-
-For pgpm workspaces, safegres can deploy the workspace into an ephemeral test
-database and audit it — no running database or connection flags required
-(needs the optional peer dependency `pgsql-test`):
-
-```bash
-safegres audit --pgpm            # nearest pgpm module/workspace from cwd
-safegres audit --pgpm ./packages/my-db
-```
-
-Or as a jest test via the `safegres/pgpm-test` entrypoint:
-
-```ts
-import { auditPgpmWorkspace } from 'safegres/pgpm-test';
-
-it('passes the security audit', async () => {
-  const report = await auditPgpmWorkspace();
-  expect(report.score.grade).toBe('A+');
-});
-```
-
-Both discover the project's safegres config (`safegres.config.js`,
-`.safegresrc*`, …) by walking up from the workspace directory. pgpm projects
-usually don't have Constructive routing metadata, so declare the exposed
-surface statically:
-
-```json
-{
-  "extends": "safegres:recommended",
-  "exposure": { "schemas": ["app_public"] }
-}
-```
+console.log(report.score.grade, report.perf?.score.grade);
+```
+
+## Requirements
+
+- **PostgreSQL 14+.** `--explain` needs **16+** (`GENERIC_PLAN`); on older servers it reports
+  `perf.explain.unavailable` and leaves findings untouched.
+- **A connection.** No extension is required. `pg_stat_statements` is optional and only powers S4;
+  its absence is a note in the report, never an error.
+- **Catalog visibility.** Any role can run the audit, but a role that is neither superuser nor
+  `BYPASSRLS` may not see every policy and grant — `safegres doctor` says so explicitly. For a
+  score you can gate on, connect as the owner (in CI, that is the default anyway).
+- **`--stats` describes a workload**, so it is meaningless against a freshly provisioned CI
+  database. The `X*` and `A*`/`L*`/`R*` rules are deterministic and work fine on an empty one.
+- safegres **reads**. It never creates, alters, or drops anything, and `--explain` plans without
+  executing.
 
 ---