proof-harness 0.1.0-next.1 → 0.1.0-next.10

package/COMPATIBILITY.md

@@ -11,7 +11,7 @@ Consumers must pin an exact prerelease version, for example:
 ```json
 {
   "devDependencies": {
-    "proof-harness": "0.1.0-next.1"
+    "proof-harness": "0.1.0-next.9"
   }
 }
 ```
@@ -24,3 +24,404 @@ tighten validation or packaging contracts even when its base version remains
 The trace, mission, and health protocol versions are independent from the npm
 package version. Consumers should reject unsupported artifact or protocol
 versions rather than guessing how to interpret them.
+
+## Prerelease migration notes
+
+### 0.1.0-next.10 — explicit primary mutation evidence (release candidate)
+
+Prepared for release; not yet published. After publication, pin exactly
+`proof-harness@0.1.0-next.10` and rerun a fresh baseline before mutation checks.
+Trace, mission, and health protocol versions remain unchanged.
+
+This fixes #26: next.9 accidentally required SDK-helper provenance for primary
+mutation assertions, although primary inventory accepts explicit consumer
+assertions. A mapped, decisive failed `role: "primary"` assertion recorded by
+`recordAssertion` can again detect a mutation without `emittedBy`. An explicit
+selector restriction on `emittedBy` still applies. Control sensitivity continues
+to require recognized SDK-helper provenance; controls never detect primary
+mutations. Existing freshness, plant, failed-run, and restoration checks remain.
+
+No new RPC helper or provenance field is required. Do not supply or forge
+`emittedBy`: public `recordAssertion` deliberately strips it. Consumer proof
+specs and protected catalogs own the meaning of explicit primary assertions.
+For an RPC EXECUTE-denial proof, successful unauthorized execution should emit
+the mapped failed primary assertion. Unrelated SQL, transport, or setup errors
+must remain incomplete or emit no decisive failure; they are not evidence of
+the mapped breach. Tightening the consumer denial probe to accept only the
+expected SQLSTATE (for example, `42501`) remains consumer-owned work.
+
+### 0.1.0-next.9 — anonymous actions and control sensitivity
+
+Published release. Pin exactly
+`proof-harness@0.1.0-next.9` and regenerate capabilities and baseline traces.
+Trace/mission/health versions remain unchanged. Authentication refusal and
+control-sensitivity output contracts use protocol/schema version 1.
+
+#### Anonymous self-service actions (#23)
+
+`assert.authorization` accepts `actor: "anonymous"` for **action probes only**.
+It sends the protected POST invoker request in a fresh API context, without
+login cookies or Authorization, and disables redirect following. It does not
+clear or reuse the authenticated page session. Use the Playwright project's
+`use.baseURL`, an explicit `action.baseURL`, or an already navigated page URL.
+
+```ts
+await assert.authorization({
+  actor: "anonymous", page,
+  action: {
+    module: "user-management", name: "selfDeleteAccount", inputParams: {},
+    expectedAuthRedirect: "/sign-in",
+  },
+});
+```
+
+The consumer must update its **guarded invoker**, after request validation and
+registered-handler lookup. In the catch around actual handler execution:
+
+```ts
+import { authenticationRedirectResponse } from "proof-harness/server";
+// Existing proofGuard, body validation, registry lookup, and handler call stay.
+const refusal = authenticationRedirectResponse(error, request, {
+  module: body.module, action: body.action, allowedRedirects: ["/sign-in"],
+});
+if (refusal) return refusal;
+// Keep the existing failure response for all other exceptions.
+```
+
+Choose the exact authentication destination from the consumer's own auth
+middleware. The adapter recognizes Next.js redirect errors only, requires no
+Cookie/Authorization request headers, and matches an exact allowlisted relative
+URL. It returns HTTP 401 with `{ protocolVersion: 1,
+ type: "proof_action_auth_refusal", module, action,
+ reason: "authentication_required", redirect }`. The client binds that envelope
+to the invoked action and the assertion checks `expectedAuthRedirect`.
+A generic 401/500, `action_threw`, invalid-form rejection, unexpected redirect,
+malformed result, or missing registry entry is incomplete evidence. Anonymous
+success is a failed authorization assertion. No seeded denied role is needed.
+
+Use `assert.actionSucceeds` with a disposable authenticated actor for the
+allowed-path control; account-deletion fixtures remain consumer-owned. The
+adapter's destination list and placement are protected trust inputs: it must
+only normalize authentication redirects from an executed registered action,
+not invoker setup errors or unrelated redirects. This is not automatic proof
+of an arbitrary application's authentication semantics.
+
+Workspace scope discovery now follows local caller-input bindings and accesses,
+including destructuring aliases and direct parse/safeParse results. It no
+longer counts comments, SQL/output keys, or generated/result workspace IDs.
+Unknown user-input dataflow used as workspace scope and dynamic input keys
+remain unassessed. Internal `_BOT.ts` actions retain their existing exemption
+from caller-boundary coverage. This is bounded local analysis, not intermodule
+schema inference. In particular `createTeamWorkspace` no longer inherits a
+cross-tenant requirement merely because it returns a new workspace ID. Declare
+any additional product invariants and add their proofs in the consumer.
+
+#### Separate positive-control sensitivity (#24)
+
+Move the old `TENANT-deny-all` entry out of the primary mutation catalog into
+a separate protected module named by `controlSensitivityCatalog` in
+`proof.config.mjs`. Keep its existing subject, apply SQL and spec; add:
+
+```js
+claims: [],
+controls: [{
+  kind: "tenant_isolation", target: "workspace_members", operation: "select",
+  emittedBy: "assert.tenantIsolation",
+}],
+expectedFailureCode: "tenant_isolation_control",
+```
+
+Run `proof-harness controls --inventory`, then `proof-harness controls` (or
+`--only TENANT-deny-all`). Both require fresh passing baseline evidence for
+every mapped package-origin **control** in the selected spec. The initial
+contract supports tenant-isolation SELECT controls emitted by
+`assert.tenantIsolation` or `assert.authorization`, with the exact failure code
+`tenant_isolation_control`. Other sensitivity categories remain unsupported.
+
+The runner reuses mutation planting/readback, isolated execution, restoration,
+and recovery checks. A successful test needs a non-timeout failed proof, a
+failed mapped control assertion of the same helper origin, and a step error
+beginning with that exact failure code. Setup errors, incomplete/skipped
+assertions, another spec, primary-only failures, or a missing failed control do
+not count. Unexpected owner-control database errors are setup failures rather
+than control rejection; explicit permission denial or zero visible owner rows
+can establish the intended anti-vacuity failure.
+
+Results live separately in `artifacts.controlSensitivity` (default
+`.proof/control-sensitivity`), with `mode: "control-sensitivity"`,
+`controlRejected`/`controlsTurnedRed`, and `detected: false`. They remain planted
+traces and cannot satisfy baseline claims or primary mutation coverage. Use
+`proof-harness controls --recover` for an interrupted run against the same
+local stack; the shared recovery journal blocks either runner until restored.
+Primary `mutate` still rejects `claims: []` with no resolved primary baseline.
+A failed control can no longer count as a failed primary claim of the same
+kind/target/operation. Wire both commands into consumer CI if both properties
+are required.
+
+### 0.1.0-next.8
+
+Published release `0.1.0-next.8`. Consumers pin exactly
+`proof-harness@0.1.0-next.8` when adopting these features.
+
+#### Direct RLS clients and Auth administration (#18)
+
+The scanner recognizes immutable local bindings returned by
+`createSupabaseRLSClient`, including named-import aliases and awaited calls.
+Their table writes are assessed as RLS writes, never recorded as service-role
+writes. Binding identity is local to its scope: shadowed identifiers,
+reassignment, escaped clients/builders, and unresolved privilege still fail.
+This remains convention-based discovery of the named consumer factories, not
+verification of their implementation or arbitrary wrapper/dataflow analysis.
+
+Direct `serviceClient.auth.admin.deleteUser(...)` is recorded in the additive
+capability field `serviceRoleAuthOperations: ["deleteUser"]`, separate from
+`serviceRoleMutations`. This does not pretend the Auth API is a SQL DELETE
+(and does not infer whether its optional soft-delete argument is true).
+Other administrative methods, dynamic method names, detached calls, and
+unresolved administrative privilege remain unassessed.
+
+Regenerate capabilities. Changes to Auth operations participate in drift under
+`service_role_mutations_changed`. Coverage requires a package-origin denial
+assertion and an allowed-path control for a user-facing Auth-admin action,
+even when it has no workspace input or voluntary invariant declaration.
+Existing explicit action-gap policy handling remains unchanged; a recognized
+operation alone is not passing authorization evidence. Trace, mission and
+health protocol versions are unchanged; capability schema remains additive v1.
+
+#### Catalog providers and rollback INSERT controls (#19, #20)
+
+These changes are not in the published `0.1.0-next.7`. They are opt-in; the
+default SQL parser and REST INSERT/DELETE control remain available. No trace,
+mission, or health protocol version changes. Pin exactly `0.1.0-next.8` only
+after it is released.
+
+#### Catalog assessment
+
+Set `schemaProvider: "scripts/proof/catalog-provider.mjs"` in the protected
+`proof.config.mjs`. `parse`, the parse step of `build`, and both sides of
+`drift` use it instead of the conservative SQL parser. ALTER and DROP are then
+evaluated by PostgreSQL, not inferred from historical CREATE statements.
+
+The module must export a default async function receiving:
+
+- `protocolVersion: 1`, `rootDir` for the tree being assessed;
+- `migrations`: ordered `{ path, sql, sha256 }` entries from the configured
+  migration directory (top-level `.sql` files), and their combined `inputHash`;
+- `withLocalPostgres(connectionUrl, callback)` and
+  `readPostgresCatalog(client, schemas = ["public"])` from `proof-harness/node`.
+  These are injected so the archived base needs no installed dependencies to
+  import these helpers. Keep the provider's own imports dependency-free.
+
+The consumer provider must create an empty disposable database, apply its
+versioned platform bootstrap and every supplied migration in order, read the
+catalog, and drop the database in `finally`. Fail on migration or cleanup
+errors. Return `{ protocolVersion: 1, assessed: true, issues: [], tables }` only
+after successful evaluation and cleanup; `tables` is the helper's result.
+The connection helper restricts connections to loopback hosts. The consumer
+owns the local database URL, creation privileges, platform bootstrap, migration
+ordering, schema selection, and any required role setup. Never use the live
+head database as the base catalog, clone an application-populated database,
+or catch a failed migration and return partial facts.
+
+Catalog table facts contain `schema`, `name`, `columns` (names), `rls_enabled`,
+`rls_forced`, and `policies`. Each policy contains `name`, `command`, `roles`,
+`mode`, `using`, and `check`. Classification is package-owned. Drift compares
+column names, RLS state including FORCE, and full policy facts; this does not
+add drift coverage for column types, defaults, functions, triggers, or grants.
+Malformed envelopes/facts and changed migration inputs fail assessment and
+replace stale successful output with an unassessed artifact.
+
+The schema artifact adds `assessment` with provider protocol/path/hash,
+migration paths/hashes, combined input hash, and repository source hash. This
+is source identity, not a signature. The provider, its platform bootstrap,
+configuration, and installed harness remain protected trust inputs.
+
+For generated migrations, retain `driftPrepare` to rebuild them in each tree.
+**Adoption requires a preparatory base commit:** register the provider, its
+platform bootstrap, and config in the consumer before the comparison that
+upgrades the package. Both base and head must declare a provider. Drift rejects
+switching assessment modes across the comparison and never substitutes head
+configuration for a base without the provider. Existing next.7 ignores the new
+keys; registering them does not repair its conservative parser. A consumer
+already blocked on next.7 needs to land this trusted setup separately before
+the candidate's first successful drift run.
+
+#### Append-only INSERT controls
+
+Configure the protected consumer config explicitly, using your local ports:
+
+```js
+insertControl: {
+  mode: "rollback",
+  databaseUrlEnv: "PROOF_DATABASE_URL",
+  role: "service_role",
+  supabaseUrl: "http://127.0.0.1:54321",
+}
+```
+
+Supply the corresponding local PostgreSQL URL through that environment
+variable; never commit its password. The configured REST origin must match
+`NEXT_PUBLIC_SUPABASE_URL`. The database URL must refer to the same stack,
+schema, and migrations as REST; the harness validates the configured origin
+but cannot discover which database a REST server actually serves.
+
+The denied INSERT still executes through the authenticated Supabase client.
+Only after an explicit `42501` denial and a service read confirming no write
+does the harness validate the same payload on one PostgreSQL connection:
+BEGIN, SET LOCAL ROLE, INSERT, force deferred constraints, ROLLBACK. The role
+must have the intended INSERT permission. Missing columns keep their database
+defaults; the harness supplies no tenancy values. An invalid payload, failed
+role change, database error, or unacknowledged rollback fails as incomplete
+evidence. The harness records the control assertion only after success and a
+REST reread confirming no matching row remains. There is no consumer callback
+that can stamp a passing control.
+
+No DELETE privilege is needed for this control. Transactional trigger writes
+also roll back, but sequence advancement and external side effects do not;
+use only a disposable local stack. This control checks database validity under
+the configured role, not REST middleware or an authenticated user's JWT
+context. Templates whose privileged insert depends on that context must supply
+a suitable database design/control strategy rather than treat this mode as
+equivalent. Product authorization errors must still use SQLSTATE `42501`;
+generic exceptions such as `P0001` are not accepted as authorization evidence.
+
+For maintainers, `PROOF_DATABASE_URL=... node tests/postgres-integration.mjs`
+after `pnpm build` exercises a separate temporary database against PostgreSQL,
+including immediate and deferred failures and catalog ALTER/DROP behavior.
+
+### 0.1.0-next.7 — audit hardening
+
+Published release `0.1.0-next.7` tightens acceptance behavior. Trace
+<a id="unreleased-audit-hardening"></a>
+
+### 0.1.0-next.7
+
+Published September 7, 2026. This release tightens acceptance behavior. Trace
+schema remains 2, with additive source/execution identity fields. Version 1
+and unversioned trace shapes remain explicitly readable, but CLI acceptance
+requires current provenance. Required consumer changes:
+
+- Regenerate traces. `verify`, `coverage`, and mutation inventory share a
+  decoder: corrupt JSON, duplicate proof IDs, unknown vocabulary, and
+  contradictory verdicts fail. Only passing baseline evidence can satisfy
+  claims; mutation evidence is separate. Current spec contents must match
+  `specHash`; in Git worktrees both `commit` and `sourceHash` must match.
+  `sourceHash` includes tracked and untracked nonignored inputs and excludes
+  configured generated artifacts. Run generators before proofs. Non-Git
+  exports cannot establish whole-source freshness and only check spec hashes.
+- Use a dedicated trace directory. The writer honors `artifacts.traces` and
+  the runner's `--traces-dir` override. IDs must use letters, digits, dots,
+  underscores, or hyphens, starting with a letter or digit. Duplicate IDs
+  cannot overwrite another proof; a later Playwright retry of the same test
+  may replace its earlier attempt. Standalone repeated runs need fresh output.
+  Mission aggregates now live at `<traces>/missions/<missionId>.json` to
+  prevent collisions with proof IDs. Cleanup refuses unknown JSON before
+  deleting any trace and rejects repository/ancestor directories, including
+  symlink aliases. Move legacy or corrupt files aside before rerunning.
+- UPDATE denial probes require stable `identityColumns` (default `["id"]`),
+  present and non-null in every target row, excluded from the update payload.
+  The attempted update must change a value. Rereads use original identities,
+  even when a write changes a filter column. SQL errors other than `42501`
+  are incomplete evidence. INSERT probes require a payload absent before the
+  probe and valid for a service-role control insertion; that control is
+  cleaned up. HTTP expectations must contain a status or a nonempty matcher
+  list. Write requests are never automatically retried after transport errors.
+- Capability discovery uses TypeScript syntax analysis for import aliases and
+  multiple actions. Unknown factory/client indirection, escaped service query
+  builders, dynamic table names, and ambiguous metadata block assessment.
+  Discovery still assumes the configured template action layout.
+- The SQL parser is deliberately conservative, not a final PostgreSQL catalog
+  evaluator. Unsupported ALTER/DROP or dynamic SQL makes schema assessment
+  fail. RLS must be explicitly enabled for classification; public ALL/write
+  policies are never exempted as public-read. Policy expressions and mode
+  participate in drift. Resolve unsupported migrations with a catalog-backed
+  integration before using this parser as a gate; do not edit shipped SQL or
+  mark an unassessed artifact assessed to obtain a pass.
+- Drift always regenerates both trees using the installed harness and each
+  tree's consumer configuration. It includes untracked actions, SQL, and
+  lockfiles. For ignored/generated migrations, configure `driftPrepare` as a
+  command argv array (for example `["node", "scripts/aggregate_migrations.mjs",
+  "--fresh"]`). That consumer-owned command runs in each tree before parsing;
+  failure prevents assessment. It must work in the archived tree without an
+  implicit dependency install. The old `driftSources` optimization is unused.
+- Mutations require fresh mapped baseline claims and write isolated traces.
+  SQL applies run as one transaction; recovery is attempted even after a
+  failed apply. Policy snapshots preserve expressions, roles, command, and
+  permissive/restrictive mode. Generic privilege mutations support direct,
+  owner-issued grants without grant options; unsupported inherited/PUBLIC or
+  ownership cases fail before planting. Move old mutation outputs aside on
+  first use: nonempty output directories require a harness ownership marker.
+  An interrupted run leaves `mutation-recovery.json` beside the mutation output
+  directory. Run `proof-harness mutate --recover` against the same local
+  database to restore and verify the journaled subject. A timeout, signal, or
+  incomplete failed claim never counts as detection. Recovery covers the
+  catalog's declared subject and cleanup, not arbitrary undeclared side effects.
+- Partial fixture setup is cleaned up, and cleanup errors now fail the proof.
+
+These checks validate observed evidence. Protect the installed harness,
+configuration, mission, policies, mutation catalog, and CI acceptance job from
+executor edits. Trace metadata is not a signature or a sandbox: it cannot
+establish honesty against an executor allowed to replace the gate or fabricate
+its inputs. Independent product acceptance and a trusted runner remain needed.
+
+### 0.1.0-next.6
+
+**Removed: the module-descriptor system.** It served the consumer's planner
+(what a module is for, what a buyer must decide, where answers land) and never
+fed verification, so it is now consumer-owned. Gone from the package:
+
+- CLI commands `modules` and `modules-check` (and the `modules` step inside
+  `build`); the `.proof/module-policy.json` accept-list introduced in
+  `next.5` went with the checker.
+- `proof-harness/shared` exports `ModuleMeta`, `ModuleDecision`,
+  `ModuleInput`, `ModuleDefault`, `ModuleSeam`, `ScannedModule`,
+  `ModulesArtifact`, `MODULE_DESCRIPTOR_SCHEMA_VERSION`, `MODULE_KINDS`,
+  `APPLIED_BY`, `ModuleKind`, `AppliedBy`, `isModuleKind`, `isAppliedBy`.
+- The `proof.config.mjs` keys `artifacts.modules`, `policies.module`,
+  `roots.modules`, `roots.sharedModules`, and `moduleKinds` (now ignored if
+  supplied).
+
+Migration: consumers using the system vendor it from
+`proof-harness@0.1.0-next.5` (Apache-2.0) — `cli/engines/scan_module_meta.mjs`,
+`cli/engines/proof_module_check.mjs`, and `src/shared/module-types.ts` plus the
+two vocabularies above — and point their `module.meta.ts` type imports at the
+vendored copy. Consumers that never ran `proof:modules` are unaffected. Trace,
+mission, and health protocol versions are unchanged.
+
+### 0.1.0-next.5
+
+No artifact schema or protocol changes. Three behavioral changes:
+
+- **`seed.workspace` no longer writes `type`.** The insert carries only
+  `name` plus caller-supplied values — the harness never invents a column
+  value it wasn't given. A schema whose `workspaces` table has required
+  columns without defaults (the conventional template's `type` included)
+  must supply them via `seed.workspace(name, { columns: { … } })` or the new
+  `workspaceColumns` option on `assert.tenantIsolation`, or add a database
+  default.
+- **`createProofServiceClient` refuses non-local targets.** Any
+  `NEXT_PUBLIC_SUPABASE_URL` whose parsed hostname is not
+  `localhost`/`127.0.0.1`/`[::1]` aborts as `unsafe_database` before a
+  client is constructed, because the suite deletes the users and workspaces
+  it seeds. CI setups reaching Supabase through a docker-network hostname
+  call `allowProofServiceHosts(["<host>"])` in code; there is no environment
+  override.
+- **`modules-check` gains an accept-list.** `.proof/module-policy.json`
+  (`schemaVersion: 1`, `acceptedUndescribed: [{ module, reason }]`) lets an
+  adopting consumer record undescribed required-root modules as visible debt
+  instead of turning the check off. Entries that stop applying fail as
+  `module_policy_stale`. Absent file = no acceptances; existing consumers
+  are unaffected.
+
+### 0.1.0-next.4
+
+No entry-point, artifact schema, or protocol changes. The `mutate` command
+tightens validation: each mutation's subject is now read back after apply and
+again after its proof, so a defect that never took effect fails as
+`NOT PLANTED` and one that was externally undone mid-run fails as
+`UN-PLANTED` — both distinct from a missed proof. A catalog mutation whose
+`apply` intentionally leaves its subject unchanged (it plants a side object
+that `cleanup` removes) must now declare `applyDoesNotChangeSubject: true`;
+runs with such undeclared mutations fail until the flag is added. The shared
+dev server is also started before the first defect is planted rather than
+inside the first mutation's window.

package/PROOF_SDK_CONTRACT.md

@@ -9,11 +9,8 @@ instead; this document is for anyone _consuming_ the template.
 
 > **"Manifest" in this document always means the _mission_ manifest**
 > (`.proof/current-mission.json`) — the file that pins what one PR must prove.
-> It is unrelated to a **module descriptor** (`module.meta.ts` →
-> `.proof/modules.json`), which describes what a module is for and what a buyer
-> must decide before using it. See §3.1 below.
 
-- **Version:** 1 (`schemaVersion` in every manifest and artifact)
+- **Versions:** mission manifests 1; proof traces 2; proof health protocol 1.
 - **Stability:** The shapes in this document are the contract. Additive
   changes (new optional fields, new vocabulary entries) do not bump the
   version; breaking changes bump `schemaVersion` and are documented here.
@@ -25,6 +22,17 @@ instead; this document is for anyone _consuming_ the template.
 
 ---
 
+## Current acceptance semantics
+
+The `0.1.0-next.7` audit hardening in [COMPATIBILITY.md](COMPATIBILITY.md#010-next7)
+supersedes older template-specific command examples below. Trace consumers
+must use `decodeTrace`/`decodeTraceBundle` for structural validation and
+`readTraceDirectory` for CLI-equivalent freshness checks. Evidence counts only
+when the proof and step passed, the assertion has a passing consistent verdict,
+and the trace is a baseline rather than a planted mutation. Helper-origin
+metadata is a convention enforced by the writer, not cryptographic attestation.
+The consumer controls and protects the runner and its trust inputs.
+
 ## 1. The loop
 
 ```
@@ -50,7 +58,7 @@ instead; this document is for anyone _consuming_ the template.
 │             │    fails cheaply BEFORE the database proofs run        │
 │             ├─ proof:verify                                          │
 │                 ├─ runs every *.proof.ts spec                        │
-│                 ├─ aggregates  .proof/traces/<missionId>.json        │
+│                 ├─ aggregates  .proof/traces/missions/<missionId>.json        │
 │                 └─ validates manifest requirements against artifacts │
 │             ├─ proof:coverage --strict                               │
 │             └─ proof:inventory → requires mutation or acceptance      │
@@ -534,7 +542,6 @@ Everything the template produces that the consumer consumes.
 | Output                      | Location                                                                       | Emitted by                                           | Cadence                                |
 | --------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------- | -------------------------------------- |
 | Capability map              | `.proof/capabilities.json` (gitignored)                                        | `pnpm proof:scan` (via `proof:build` in setup/CI)    | Every setup + CI run                   |
-| Module descriptors          | `.proof/modules.json` (gitignored)                                             | `pnpm proof:modules` (via `proof:build` in setup/CI) | Every setup + CI run                   |
 | Schema + RLS classification | `.proof/schema.json` (gitignored)                                              | `pnpm proof:parse` (via `proof:build` in setup/CI)   | Every setup + CI run                   |
 | Proof action allowlist      | `app/__shared/proof-runtime/action-registry.generated.ts`                      | `pnpm proof:registry`                                | When action requirements/probes change |
 | PR verification status      | GitHub check `Proof`                                                           | `pnpm proof:check` in `.github/workflows/ci.yml`     | Every PR push                          |
@@ -714,82 +721,16 @@ from another commit or whose `specFile` no longer exists with `stale_trace`.
 
 ---
 
-### 3.1 Module descriptors — what exists, and what must be decided
-
-`.proof/modules.json` answers a different question from everything else here.
-The trace artifacts say _"this claim was proved"_; this one says _"this is what
-exists, and this is what a buyer has to settle before it can be used"_. It is
-what a planning agent reads instead of the template's source, which is the point:
-without it the planner needs the codebase in its context, and that grows with
-every module we write.
+### 3.1 Module descriptors — moved to the consumer
 
-Regenerate it with `pnpm proof:modules`. Unlike `schema.json` it needs **no
-Docker, database, or migration aggregate** — it reads the filesystem and
-`capabilities.json`, and takes about a second.
-
-Each entry has a declared half and a derived half:
-
-```jsonc
-{
-  "schemaVersion": 1,
-  "modules": [
-    {
-      // Declared in app/__core/<module>/module.meta.ts
-      "id": "user-auth",
-      "kind": "core", // core | extension | business | generated
-      "purpose": "Signs people in and proves who they are — …",
-      "env": [],
-      "decisions": [
-        {
-          "id": "mfa_enforcement", // snake_case, unique across all modules
-          "ask": "Must people use a second factor to sign in?",
-          "because": "Stricter is safer but adds a step for everyone.",
-          "options": [{ "value": "optional", "means": "…" }],
-          "applied_by": "config", // config | content | code
-          "applies": ["app/__core/user-auth/src/config.ts#MFA_POLICY"],
-        },
-      ],
-      "inputs": [
-        /* values the buyer supplies rather than picks */
-      ],
-      "defaults": [
-        /* what we chose for them, each with a seam */
-      ],
-
-      // Derived from source — never written by hand
-      "path": "app/__core/user-auth",
-      "entities": [], // tables its own migrations create
-      "requires": ["config", "user-management"],
-      "uses_shared": ["ui", "db-supabase"],
-      "actions": [{ "name": "signin", "verb": null, "object": null }],
-      "proven": { "specs": 1, "mutations": 0 },
-    },
-  ],
-  // Tables no descriptor claims — today, the ones owned by __shared modules.
-  "unowned_tables": [
-    {
-      "table": "audit_logs",
-      "module": "audit-logging",
-      "path": "app/__shared/audit-logging",
-    },
-  ],
-}
-```
-
-**Two audiences, one file.** A planner reads `purpose`, `decisions`, `inputs`
-and `applied_by` — business language, no paths, roughly 80 tokens per decision.
-The agent that _applies_ an answer additionally reads `applies`, which names
-every place the answer lands, including files in other modules.
-
-**Every claim is checked.** `pnpm proof:modules:check` fails when a module has
-no descriptor, when an id does not match its directory, when a decision has
-fewer than two options or a duplicate id, when a declared environment variable
-is undocumented or an undeclared one is read, and — the one that matters most in
-practice — **when a seam no longer exists**. A moved file fails CI instead of
-quietly sending the next agent to the wrong place.
-
-Circular dependencies in the derived graph are **reported, not failed**, while a
-known inversion is being resolved.
+Until `0.1.0-next.5` the package also shipped a module-descriptor system
+(`module.meta.ts` → `.proof/modules.json`, plus the `modules` and
+`modules-check` commands). It served the consumer's *planner* — what a module
+is for, what a buyer must decide, where answers land — and never fed
+verification, so as of `0.1.0-next.6` it is consumer-owned and no longer part
+of this package. The last release carrying it is `proof-harness@0.1.0-next.5`
+(Apache-2.0), whose implementation is the reference for consumers vendoring
+the system into their own repository.
 
 ## 4. Failure contract
 
@@ -941,6 +882,33 @@ operation }` assertion has neither a matching mutation nor a valid entry in
   `.proof/mutation-policy.json`, pinned to the current spec hash and a passing
   positive control. A changed/deleted claim, changed spec, missing control, or
   newly added mutation makes the acceptance stale and fails inventory.
+- **A proof run cannot target a hosted database.** `createProofServiceClient`
+  parses `NEXT_PUBLIC_SUPABASE_URL` and hard-aborts as `unsafe_database` on
+  any hostname that is not local — matched on the parsed hostname, never by
+  substring, so `localhost.example.com` does not pass. The suite deletes the
+  auth users and workspaces it seeds; against a hosted project that failure
+  is silent and unrecoverable. There is deliberately no environment-variable
+  override: a genuinely disposable non-local host (a docker-network CI
+  hostname) is allowed in code via `allowProofServiceHosts`, where a reviewer
+  sees it. The mutation runner applies the same refusal to its psql target.
+- **The harness never invents a column value it wasn't given.** Anywhere the
+  package writes to a consumer-owned table, the values are caller-supplied or
+  the column is omitted — tenancy shape is a consumer decision.
+  `seed.workspace` writes only `name`; a schema that requires more states it
+  via `seed.workspace(name, { columns })` or `workspaceColumns` on
+  `assert.tenantIsolation`.
+- **A mutation that is not demonstrably live cannot judge a proof.** The
+  mutation runner never (re)applies migrations; it starts (or adopts) the
+  shared dev server before the first defect is planted, then reads each
+  mutation's subject back after apply and again after the proof. An apply that
+  left the subject unchanged fails as NOT PLANTED (a `REVOKE` no-op, or a
+  privilege still reachable via `PUBLIC` or an inherited role); a subject that
+  reverted mid-run — for example consumer tooling re-applying a wholesale
+  `REVOKE ALL; GRANT …` migration — fails as UN-PLANTED. Neither is reported
+  as a missed proof, because the proof never saw the defect. A mutation whose
+  apply intentionally leaves its subject untouched (it plants a side object
+  that `cleanup` removes) must declare `applyDoesNotChangeSubject: true` in
+  the catalog to opt out of the two subject comparisons explicitly.
 
 `pnpm proof:mutate` is the regression test for these guarantees: it re-opens known
 vulnerabilities in the local database one at a time and fails if the corresponding
@@ -1253,3 +1221,60 @@ a trace version bump.
 `.proof/coverage-policy.json` carries its own `schemaVersion` (currently `1`).
 It is authored, not derived, and is read only by `pnpm proof:coverage`; consumers
 do not need to parse it.
+
+
+## Catalog provider and rollback controls (0.1.0-next.8)
+
+The protected consumer config may opt into `schemaProvider` protocol 1 and
+`insertControl.mode: "rollback"`. See [the setup and migration contract](COMPATIBILITY.md)
+for the exact provider envelope, base-commit requirements, and control configuration.
+`proof-harness/node` exports `withLocalPostgres`, `readPostgresCatalog`,
+`rollbackInsertControl`, and the `PostgresCatalogTable`/`PostgresCatalogPolicy` types.
+Providers own database materialization; the harness validates catalog facts,
+classifies policies, binds source identity, and compares both trees. A rollback
+INSERT control is package-executed and can only record passing control evidence
+after its insert, deferred checks, rollback, and absence reread succeed. The
+original authenticated request remains the primary authorization assertion.
+
+
+## Direct Auth administration (0.1.0-next.8)
+
+Capability schema v1 adds optional `serviceRoleAuthOperations`, currently a
+closed list containing only `"deleteUser"`. It describes direct service-client
+Auth API calls separately from `serviceRoleMutations` (SQL table writes).
+Such user-facing actions require denial and allowed-control evidence in
+coverage even without a workspace input. Changes use the existing
+`service_role_mutations_changed` drift facet. See `COMPATIBILITY.md` for
+supported factory/binding shapes and required consumer regeneration.
+
+
+## Anonymous invocations and control sensitivity (0.1.0-next.9)
+
+The versioned anonymous refusal envelope is `ActionAuthenticationRefusal`
+(protocol 1), validated by `isActionAuthenticationRefusal` from the shared
+entry point. The server exports `authenticationRedirectResponse`; Playwright
+exports `actAsUser.invokeAnonymousAction` and accepts `actor: "anonymous"` in
+`assert.authorization` action probes. Only an action-bound, expected
+authentication redirect can establish a passing anonymous denial; generic
+exceptions are not evidence. See `COMPATIBILITY.md` for the required protected
+invoker integration and allowed authenticated control.
+
+`proof-harness controls` consumes `controlSensitivityCatalog` independently
+from primary mutation inventory and writes `mode: "control-sensitivity"`
+results under `artifacts.controlSensitivity`. Its mapped failed controls never
+count as primary mutation detection. The initial contract is limited to
+tenant-isolation SELECT anti-vacuity checks with `tenant_isolation_control`;
+see `COMPATIBILITY.md` for exact selectors, fresh baseline requirements and
+recovery. Consumer claims and product fixtures remain consumer-owned.
+
+## Explicit primary mutation evidence (0.1.0-next.10)
+
+Primary inventory and mutation detection accept explicit consumer assertions
+without `emittedBy`. Detection still requires a mapped, decisive failed primary
+assertion in a failed step and trace, plus the runner's baseline, plant, and
+failed-execution checks. Any selector requiring a specific `emittedBy` must
+still match it. A missing helper origin is not helper provenance: consumer
+specs and protected catalogs remain responsible for these assertions' meaning.
+Control sensitivity requires recognized SDK-helper provenance and cannot count
+as primary detection. Skipped, incomplete, and setup-only failures are not
+mapped decisive primary evidence. No trace protocol change is introduced.