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

package/COMPATIBILITY.md

@@ -27,9 +27,105 @@ versions rather than guessing how to interpret them.
 
 ## Prerelease migration notes
 
-### 0.1.0-next.10 — explicit primary mutation evidence (release candidate)
+### 0.1.0-next.12 — independent isolation fixtures and column ACL recovery (candidate)
 
-Prepared for release; not yet published. After publication, pin exactly
+Not yet published. Keep the existing consumer pin until this release is reviewed
+and published; then pin exactly `proof-harness@0.1.0-next.12`.
+
+`assert.tenantIsolation` now accepts a caller-owned `isolationFixture` instead of
+workspace seeding. Supply a stable fixture `id`, the matching `table`, an explicit
+`scopeColumn`, `setup()` returning two distinct actors and scope values, and
+`cleanup()` that can handle partial setup. Scope values can be user IDs or
+independent account IDs. `scope: "account"` requires this fixture path. Existing
+workspace fixtures and their reverse-direction behavior remain unchanged.
+
+```ts
+await assert.tenantIsolation({
+  table: "notifications",
+  scope: "account",
+  scopeColumn: "account_id",
+  isolationFixture: {
+    id: "notifications-two-accounts-v1",
+    table: "notifications",
+    async setup() {
+      // Consumer creates real Auth customers, resolves account IDs, and seeds rows.
+      return {
+        a: { actor: { email: ownerA.email, password: ownerA.password }, scopeValue: accountA.id },
+        b: { actor: { email: ownerB.email, password: ownerB.password }, scopeValue: accountB.id },
+      };
+    },
+    async cleanup() { await cleanupOwnedResources(); },
+  },
+});
+```
+
+The SDK creates the service client and authenticated probe clients itself. Both
+sides must contain rows before probing; each owner must read all scoped rows,
+and each outsider must see none. Both directions are mandatory. Scope/criterion
+filters apply identically to ground truth and probes. Setup and cleanup run
+without helper provenance; callers cannot stamp SDK assertions. Cleanup errors
+fail the proof. Fixture IDs appear in probe detail; existing trace source hashes
+bind tracked and nonignored fixture source to evidence. Keep fixtures under the
+consumer's source identity, not an excluded artifact directory. This path is
+database-only: `page` is unsupported. It does not extend account-policy SQL
+classification; existing explicit classifier reviews remain separate.
+
+`tablePrivilege` mutations now snapshot the relevant table and column ACL entries
+(including grant options) and compare that complete state after restoration.
+Column UPDATE grants removed by PostgreSQL's table REVOKE are re-established.
+Owner-issued direct grants, including grant options, are supported; delegated
+grant graphs, inherited/PUBLIC effective privileges, and owner-target mutations
+remain blocked before planting. No CASCADE recovery is used. Recovery fails
+closed on an old Boolean snapshot: it cannot reconstruct already-lost column
+grants. Keep that journal and reconcile with the protected baseline rather than
+claiming automatic recovery succeeded.
+
+After upgrading: port fixtures to the public API, regenerate baseline evidence,
+restore formal table-isolation coverage, and rerun frozen install, static/unit/
+browser checks, the full proof/mutation/control gate, package parity, production
+build, and smoke. Verify actual profile editing and denied privileged-column
+writes after mutations. Package tests are not a substitute for that consumer run.
+Trace, mission, and health protocol versions remain unchanged; the internal
+ACL recovery snapshot has its own version 1.
+
+### 0.1.0-next.11 — conservative service RPC assessment
+
+Published release. Pin exactly `proof-harness@0.1.0-next.11`.
+Regenerate
+capabilities and rerun the complete baseline, coverage, inventory, and mutation
+validation after adoption. Trace, mission, and health versions are unchanged.
+
+Capability schema v1 gains additive `serviceRoleRpcCalls` entries with a literal
+`function` and `assessment: "potential_privileged_write"`. Direct const-bound
+service-client `.rpc("name", args)` calls support awaiting/returning the result
+and zero-argument `.single()` / `.maybeSingle()` result chains. Dynamic names,
+escaped builders, unsupported chains, and RLS-client RPCs remain unassessed.
+An RLS client can invoke a SECURITY DEFINER function; its privilege is not inferred
+from the client name. Result shaping does not establish read-only behavior.
+
+This is conservative action-boundary assessment, not SQL function-body analysis.
+It does not infer affected tables, effective grants, overloads, nested functions,
+or transactional correctness. Consumer SQL/function privilege proofs and mutation
+catalogs remain necessary; do not interpret this field as complete SQL write coverage.
+
+Every service RPC action requires passing primary denial and allowed control
+assertions targeting the exact `module:action`, both with `operation: "invoke"`.
+The requirement applies without workspace inputs and to `_BOT` actions. Existing
+assertion-origin rules remain in force; explicit authorization assertions retain
+the consumer-owned trust boundary. RPC requirements cannot be waived through
+`acceptedActionGaps`. No new runtime helper or caller-to-callee evidence mapping
+is introduced.
+
+Evidence for a signed webhook caller does not automatically satisfy a separately
+callable write action. Protect and test the actual action boundary, including
+alternative invocation paths; a staged route, `_BOT` suffix, or a generic 500
+response is not proof of authorization. If that boundary cannot be established,
+coverage remains blocked. Do not hide RPCs from discovery to bypass the gate.
+
+
+### 0.1.0-next.10 — explicit primary mutation evidence
+
+Published release. 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.
 

package/PROOF_SDK_CONTRACT.md

@@ -1278,3 +1278,25 @@ 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.
+
+## Conservative service RPC assessment (0.1.0-next.11)
+
+Capability schema v1 adds `serviceRoleRpcCalls: { function: string,
+assessment: "potential_privileged_write" }[]`. Missing fields in older artifacts
+are not evidence that a fresh source scan contains no RPCs. Regenerate artifacts
+when adopting this change. The scanner deliberately over-approximates service
+RPC privilege without inventing SQL table effects. Coverage requires an exact
+action-targeted primary denial and allowed control with operation `invoke`,
+including internal actions and actions without workspace inputs. Caller evidence
+is not transitively inherited. See COMPATIBILITY.md for supported syntax and
+remaining unassessable cases.
+
+## Independent scope fixtures (0.1.0-next.12 candidate)
+
+The Playwright entry point exports `IsolationFixture`, `IsolationParticipant`,
+and `TenantIsolationOptions`. `isolationFixture` is an alternative to the legacy
+workspace `setup`/`fixture` options. Its setup and cleanup are consumer-owned;
+clients, ground-truth checks, both owner controls, and both outsider probes stay
+SDK-owned. Missing either side, malformed actors/scopes, failed probes or cleanup
+prevent a passing proof. The SDK does not emit provenance on callback assertions.
+See COMPATIBILITY.md for the public call shape and source-identity requirements.

package/README.md

@@ -1,16 +1,45 @@
 # proof-harness
 
-Prerelease verification and conformance toolkit for proof traces, missions,
-fixtures, and Playwright probes.
+Verification tools for making specific claims about agent-generated code—and
+checking that deliberately broken behavior makes those claims fail.
 
-This repository is the standalone source of the package. It requires Node 24
-and pnpm 11.9.0:
+Developed alongside a consumer template, this is an opinionated prerelease,
+not a universal agent acceptance system. It can help teams that already have
+executable requirements and want structured evidence, coverage checks, and
+mutation checks around them.
+
+## Try it without the template
+
+The [standalone authorization example](https://github.com/TiKa-Nexus/proof-harness/tree/main/examples/authorization)
+uses a tiny JavaScript rule and the public package. It needs Node 24 and pnpm
+11.9.0; no database, credentials, app server, or browser download.
 
 ```sh
-pnpm install --frozen-lockfile
-pnpm check
+git clone https://github.com/TiKa-Nexus/proof-harness.git
+cd proof-harness/examples/authorization
+pnpm install
+pnpm demo
 ```
 
+You will see a passing proof, an intentionally failed proof after the rule is
+broken, and confirmation that the source was restored. The example validates
+recorded evidence; it is an introduction, not the full CLI mutation workflow.
+
+## What it does—and what it establishes
+
+The harness records structured proof traces, validates evidence and missions,
+and provides coverage, drift, mutation, and control-sensitivity engines.
+It can establish that a configured claim was observed and that a mapped defect
+was detected. The consuming project supplies the requirements and trust inputs.
+
+A passing trace does not establish overall correctness, adequate requirements,
+or security against an agent that can rewrite the acceptance gate. Keep code
+review, conventional tests, and trusted CI alongside it. See the
+[integration guide](https://github.com/TiKa-Nexus/proof-harness/blob/main/docs/INTEGRATING.md)
+for ownership, adoption steps, and current environment constraints, and
+[contributor guide](https://github.com/TiKa-Nexus/proof-harness/blob/main/CONTRIBUTING.md)
+for setup and approachable contributions.
+
 ## Installation
 
 Public prereleases are published under the npm `next` tag. Pin an exact
@@ -37,10 +66,11 @@ and consumer pinning requirements.
 The package has two layers; consumers should know which one they are leaning
 on:
 
-- **Assumes nothing about your schema** — trace recording and the assertion
+- **Reusable verification mechanics** — trace recording and the assertion
   vocabulary, mission validation, coverage and its ratchet, drift, mutation
   testing, and the CLI. These read your generated schema and config, or take
-  what you give them.
+  what you give them. CLI discovery supports specific source and SQL patterns;
+  configurable paths do not make every framework compatible.
 - **Assumes the conventional Supabase/workspace layout** — `seed.*` (a
   `workspaces` table with a `name` column, a `workspace_members` join table,
   and a `public.users` mirror maintained by a `handle_new_user` trigger) and
@@ -118,6 +148,15 @@ separate positive-control sensitivity runner. It also distinguishes caller
 workspace inputs from generated result IDs. See [next.9 setup and migration](COMPATIBILITY.md)
 before upgrading; consumer invoker and catalog changes are required.
 
-Release candidate `0.1.0-next.10` restores explicit consumer primary assertions
+Release `0.1.0-next.10` restores explicit consumer primary assertions
 for mutation detection while retaining strict control provenance. See the
-[next.10 migration notes](COMPATIBILITY.md) before adopting it after publication.
+[next.10 migration notes](COMPATIBILITY.md) before adopting it.
+
+Release `0.1.0-next.11` discovers direct service RPC calls as potentially
+privileged writes and requires action-boundary evidence even without workspace
+inputs or for internal actions. See [required migration steps](COMPATIBILITY.md)
+before adopting the exact version.
+
+Release candidate `0.1.0-next.12` adds caller-owned account/user isolation fixtures
+and restores column grants and grant options after table-privilege mutations.
+Keep existing pins until publication; see [migration requirements](COMPATIBILITY.md).

package/cli/engines/proof_coverage.mjs

@@ -367,17 +367,23 @@ function buildReport() {
   for (const capability of [...(capabilities.capabilities ?? [])].sort((a, b) =>
     `${a.module}:${a.name}`.localeCompare(`${b.module}:${b.name}`),
   )) {
+    const rpcCalls = capability.serviceRoleRpcCalls ?? [];
     if (
-      (capability.acceptsWorkspaceId !== true &&
+      !rpcCalls.length &&
+      ((capability.acceptsWorkspaceId !== true &&
         !(capability.serviceRoleAuthOperations ?? []).length) ||
-      capability.internalOnly === true
+        capability.internalOnly === true)
     ) {
       continue;
     }
 
     const workspaceMutations = capability.serviceRoleMutations ?? [];
     const authOperations = capability.serviceRoleAuthOperations ?? [];
-    if (workspaceMutations.length === 0 && authOperations.length === 0)
+    if (
+      workspaceMutations.length === 0 &&
+      authOperations.length === 0 &&
+      rpcCalls.length === 0
+    )
       continue;
 
     const action = `${capability.module}:${capability.name}`;
@@ -385,6 +391,7 @@ function buildReport() {
       (assertion) =>
         assertion.passed === true &&
         assertion.target === action &&
+        (!rpcCalls.length || assertion.operation === "invoke") &&
         normalizedRole(assertion) === "primary" &&
         denialKinds.has(assertion.kind) &&
         verifiedOrigin(assertion, { isTable: false }),
@@ -393,13 +400,16 @@ function buildReport() {
       (assertion) =>
         assertion.passed === true &&
         assertion.target === action &&
+        (!rpcCalls.length || assertion.operation === "invoke") &&
         normalizedRole(assertion) === "control" &&
         controlKinds.has(assertion.kind),
     );
     const denialProven = denialEvidence.length > 0;
     const controlProven = controlEvidence.length > 0;
     const proven = denialProven && controlProven;
-    const acceptance = acceptedActionGaps.get(action);
+    const acceptance = rpcCalls.length
+      ? undefined
+      : acceptedActionGaps.get(action);
     if (!proven && acceptance) usedActionAcceptances.add(action);
 
     // These targets are now resolved by a derived action requirement.
@@ -410,6 +420,7 @@ function buildReport() {
       tables: [...new Set(workspaceMutations.map((m) => m.table))].sort(),
       mutations: workspaceMutations,
       authOperations,
+      rpcCalls,
       denial: denialProven ? "proven" : "gap",
       control: controlProven ? "proven" : "gap",
       status: proven ? "proven" : acceptance ? "accepted_gap" : "gap",
@@ -599,7 +610,7 @@ function printReport(report) {
     );
     heading(
       "SERVICE-ROLE ACTION BOUNDARIES",
-      "Derived from workspace-targeted service-role writes or privileged Auth operations. Each action needs both an unauthorized/cross-tenant refusal and an allowed-path control; withProof metadata is not consulted.",
+      "Derived from workspace-targeted service-role writes, privileged Auth operations, or service RPC calls (including internal actions). Each action needs both an unauthorized/cross-tenant refusal and an allowed-path control; withProof metadata is not consulted.",
     );
     console.log("");
     printTable(
@@ -611,6 +622,9 @@ function printReport(report) {
             [
               ...r.tables,
               ...r.authOperations.map((op) => `auth.admin.${op}`),
+              ...r.rpcCalls.map(
+                (call) => `rpc.${call.function} (potential write)`,
+              ),
             ].join(","),
         },
         { header: "denial", get: (r) => r.denial },

package/cli/engines/proof_mutation_check.mjs

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
+import {
+  tableAclSnapshotSql,
+  validateTableAcl,
+  restoreTableAclSql,
+} from "./proof_table_acl.mjs";
 import {
   validateControlBaseline,
   assertionSelectorsTurnedRed,
@@ -234,13 +239,13 @@ function assertDirectPrivilege(container, subject, functionSubject = false) {
     `SELECT NOT EXISTS (
     SELECT 1 FROM ${catalog} c, LATERAL aclexplode(coalesce(c.${acl},acldefault('${defaultKind}',c.${owner}))) a
     WHERE c.oid = ${object} AND a.privilege_type = ${quoteLiteral(subject.privilege.toUpperCase())}
-      AND ((a.grantee = ${quoteLiteral(subject.role)}::regrole AND (a.is_grantable OR a.grantor <> c.${owner}))
+      AND ((a.grantee = ${quoteLiteral(subject.role)}::regrole AND (${functionSubject ? "a.is_grantable OR " : ""}a.grantor <> c.${owner}))
         OR (a.grantee <> ${quoteLiteral(subject.role)}::regrole AND (a.grantee = 0 OR pg_has_role(${quoteLiteral(subject.role)},a.grantee,'USAGE'))))
   ) AND NOT EXISTS (SELECT 1 FROM ${catalog} WHERE oid = ${object} AND ${owner} = ${quoteLiteral(subject.role)}::regrole)`,
   );
   if (supported !== "t")
     throw new Error(
-      "[PROOF_FAIL] mutation_unassessed: privilege restoration supports owner-issued direct grants without grant options; inherited, PUBLIC, and owner privileges require a dedicated catalog mutation",
+      `[PROOF_FAIL] mutation_unassessed: privilege restoration requires owner-issued direct grants${functionSubject ? " without grant options" : ""}; inherited, PUBLIC, and owner privileges require a dedicated catalog mutation`,
     );
 }
 
@@ -314,17 +319,13 @@ const SUBJECTS = {
   },
 
   tablePrivilege: {
-    preflight: (container, s) => assertDirectPrivilege(container, s),
+    preflight: (container, s) => {
+      assertDirectPrivilege(container, s);
+      validateTableAcl(queryScalar(container, tableAclSnapshotSql(s)));
+    },
     describe: (s) => `${s.privilege} on ${s.table} for ${s.role}`,
-    snapshot: (container, s) =>
-      queryScalar(
-        container,
-        `SELECT has_table_privilege(${quoteLiteral(s.role)}, ${quoteLiteral(s.table)}, ${quoteLiteral(s.privilege)})`,
-      ),
-    restore: (s, snapshot) =>
-      snapshot === "t"
-        ? `GRANT ${s.privilege} ON ${s.table} TO ${s.role};`
-        : `REVOKE ${s.privilege} ON ${s.table} FROM ${s.role};`,
+    snapshot: (container, s) => queryScalar(container, tableAclSnapshotSql(s)),
+    restore: restoreTableAclSql,
   },
 
   functionPrivilege: {

package/cli/engines/proof_table_acl.mjs

@@ -0,0 +1,62 @@
+// Canonical relevant ACL state, not effective has_table_privilege booleans.
+const lit = (value) => "'" + String(value).replaceAll("'", "''") + "'";
+const ident = (value) => '"' + String(value).replaceAll('"', '""') + '"';
+export function tableAclSnapshotSql(subject) {
+  return `WITH target AS (SELECT oid, relowner, relacl FROM pg_class WHERE oid = ${lit(subject.table)}::regclass), entries AS (
+    SELECT NULL::text AS column_name, a.* FROM target t, LATERAL aclexplode(coalesce(t.relacl,acldefault('r',t.relowner))) a
+    UNION ALL
+    SELECT c.attname::text, a.* FROM target t JOIN pg_attribute c ON c.attrelid=t.oid AND c.attnum>0 AND NOT c.attisdropped,
+      LATERAL aclexplode(c.attacl) a
+  ) SELECT json_build_object('version',1,'owner',(SELECT pg_get_userbyid(relowner) FROM target),
+    'entries',coalesce((SELECT json_agg(json_build_object('column',column_name,'grantor',pg_get_userbyid(grantor),
+      'grantee',CASE WHEN grantee=0 THEN 'PUBLIC' ELSE pg_get_userbyid(grantee) END,'grantable',is_grantable)
+      ORDER BY column_name NULLS FIRST,grantor,grantee,is_grantable)
+      FROM entries WHERE privilege_type=${lit(subject.privilege.toUpperCase())}), '[]'::json))::text`;
+}
+export function validateTableAcl(snapshot) {
+  const value = JSON.parse(snapshot);
+  if (
+    value?.version !== 1 ||
+    typeof value.owner !== "string" ||
+    !Array.isArray(value.entries) ||
+    value.entries.some(
+      (e) =>
+        !(e.column === null || typeof e.column === "string") ||
+        typeof e.grantee !== "string" ||
+        typeof e.grantable !== "boolean" ||
+        e.grantor !== value.owner,
+    )
+  )
+    throw new Error(
+      "[PROOF_FAIL] mutation_unassessed: table ACL requires versioned owner-issued grants; delegated grant graphs need a dedicated mutation",
+    );
+  return value;
+}
+export function restoreTableAclSql(subject, snapshot) {
+  const value = validateTableAcl(snapshot);
+  const privilege = subject.privilege.toUpperCase();
+  if (
+    ![
+      "SELECT",
+      "INSERT",
+      "UPDATE",
+      "DELETE",
+      "TRUNCATE",
+      "REFERENCES",
+      "TRIGGER",
+      "MAINTAIN",
+    ].includes(privilege)
+  )
+    throw new Error("unsupported table privilege");
+  const role = subject.role === "PUBLIC" ? "PUBLIC" : ident(subject.role);
+  // Revoking a table privilege also removes this role's column grants. Restore
+  // those explicitly, preserving grant options. No CASCADE: unexpected dependent
+  // grants abort instead of destroying state not represented by the snapshot.
+  const sql = [`REVOKE ${privilege} ON ${subject.table} FROM ${role};`];
+  for (const entry of value.entries.filter((e) => e.grantee === subject.role)) {
+    sql.push(
+      `GRANT ${privilege}${entry.column === null ? "" : ` (${ident(entry.column)})`} ON ${subject.table} TO ${role}${entry.grantable ? " WITH GRANT OPTION" : ""};`,
+    );
+  }
+  return sql.join("\n");
+}

package/cli/engines/scan_proof_capabilities.mjs

@@ -317,6 +317,7 @@ function scanFile(file, constants) {
       : undefined;
   }
   const mutations = new Map();
+  const rpcCalls = new Set();
   visit(source, (n) => {
     if (ts.isIdentifier(n) && clientKind(n)) {
       const parent = n.parent;
@@ -324,7 +325,7 @@ function scanFile(file, constants) {
       const query =
         ts.isPropertyAccessExpression(parent) &&
         parent.expression === n &&
-        parent.name.text === "from" &&
+        ["from", "rpc"].includes(parent.name.text) &&
         ts.isCallExpression(parent.parent) &&
         parent.parent.expression === parent;
       const adminOperation =
@@ -360,6 +361,49 @@ function scanFile(file, constants) {
     }
     if (!ts.isCallExpression(n) || !ts.isPropertyAccessExpression(n.expression))
       return;
+    if (n.expression.name.text === "rpc") {
+      const kind = clientKind(n.expression.expression);
+      const target = literal(n.arguments[0]);
+      if (kind !== "service")
+        problems.push(
+          "RPC privilege/effects cannot be resolved: only direct service-client RPC assessment is supported",
+        );
+      if (!target || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(target))
+        problems.push("RPC requires a literal unqualified function name");
+      let chain = n;
+      while (
+        ts.isPropertyAccessExpression(chain.parent) &&
+        chain.parent.expression === chain
+      ) {
+        const member = chain.parent;
+        if (
+          !["single", "maybeSingle"].includes(member.name.text) ||
+          !ts.isCallExpression(member.parent) ||
+          member.parent.expression !== member ||
+          member.parent.arguments.length !== 0
+        ) {
+          problems.push("RPC result chain is unsupported");
+          break;
+        }
+        chain = member.parent;
+      }
+      let parent = chain.parent;
+      let awaited = false;
+      while (
+        ts.isAwaitExpression(parent) ||
+        ts.isParenthesizedExpression(parent)
+      ) {
+        if (ts.isAwaitExpression(parent)) awaited = true;
+        parent = parent.parent;
+      }
+      if (
+        !awaited &&
+        !ts.isReturnStatement(parent) &&
+        !(ts.isArrowFunction(parent) && parent.body === chain)
+      )
+        problems.push("RPC query builder escapes its recognized chain");
+      if (kind === "service" && target) rpcCalls.add(target);
+    }
     if (
       n.expression.name.text === "from" &&
       ts.isIdentifier(n.expression.expression) &&
@@ -507,6 +551,10 @@ function scanFile(file, constants) {
         `${a.table}:${a.operation}`.localeCompare(`${b.table}:${b.operation}`),
       ),
       serviceRoleAuthOperations: [...authOperations].sort(),
+      serviceRoleRpcCalls: [...rpcCalls].sort().map((name) => ({
+        function: name,
+        assessment: "potential_privileged_write",
+      })),
       middleware: {
         auth: /\bwithAuth\s*\(/.test(body),
         tenantIsolation: /\bwithTenantIsolation\s*\(/.test(body),

package/dist/node.d.ts

@@ -26,6 +26,11 @@ interface CapabilitiesArtifact {
         }>;
         /** Direct supported privileged Auth API calls, separate from SQL writes. */
         serviceRoleAuthOperations?: readonly "deleteUser"[];
+        /** Conservative RPC assessment; does not infer SQL tables, grants or read-only behavior. */
+        serviceRoleRpcCalls?: ReadonlyArray<{
+            function: string;
+            assessment: "potential_privileged_write";
+        }>;
         /** Relevant guards observed in the action pipeline. */
         middleware?: {
             auth: boolean;