@marktiderman/genesis-supabase 0.3.0 → 0.4.0

package/README.md

@@ -4,16 +4,30 @@ Supabase for Genesis apps on web and React Native.
 
 ```ts
 import { createGenesisSupabase, must } from "@marktiderman/genesis-supabase";
-import { keychainStorage, refreshWhileActive, wipeSessionOnReinstall } from "@marktiderman/genesis-supabase/native";
+import {
+  keychainStorage,
+  refreshWhileActive,
+  wipeSessionOnReinstall,
+} from "@marktiderman/genesis-supabase/native";
 import * as SecureStore from "expo-secure-store";
 import * as ExpoCrypto from "expo-crypto";
 import AsyncStorage from "@react-native-async-storage/async-storage";
 import { AppState } from "react-native";
 
 const session = keychainStorage(SecureStore);
-await wipeSessionOnReinstall({ session, sessionKey: "sb-<project-ref>-auth-token", installMarker: AsyncStorage });
-
-export const supabase = createGenesisSupabase<Database>({ url, publishableKey, storage: session, platform: "native", crypto: ExpoCrypto });
+await wipeSessionOnReinstall({
+  session,
+  sessionKey: "sb-<project-ref>-auth-token",
+  installMarker: AsyncStorage,
+});
+
+export const supabase = createGenesisSupabase<Database>({
+  url,
+  publishableKey,
+  storage: session,
+  platform: "native",
+  crypto: ExpoCrypto,
+});
 refreshWhileActive(supabase, AppState);
 
 const rows = must(await supabase.from("tasks").select("*"));
@@ -47,18 +61,25 @@ import Constants from "expo-constants";
 import { storeAppleToken } from "@marktiderman/genesis-supabase";
 import { signInWithApple } from "@marktiderman/genesis-supabase/native";
 
-const digest = (s: string) => Crypto.digestStringAsync(Crypto.CryptoDigestAlgorithm.SHA256, s);
+const digest = (s: string) =>
+  Crypto.digestStringAsync(Crypto.CryptoDigestAlgorithm.SHA256, s);
 
 async function onApple() {
   // The nonce is 32 random bytes from crypto.getRandomValues (createGenesisSupabase installs it on native).
-  const result = await signInWithApple(supabase, AppleAuthentication, { digest });
+  const result = await signInWithApple(supabase, AppleAuthentication, {
+    digest,
+  });
   if (result.canceled) return; // they closed Apple's sheet: not an error
   if (result.error) return showError(result.error.message); // result.error.code says why
   // Apple shares the name on the first sign-in only, so save it now.
-  if (result.fullName) await supabase.auth.updateUser({ data: { full_name: result.fullName } });
+  if (result.fullName)
+    await supabase.auth.updateUser({ data: { full_name: result.fullName } });
   // For revoking on deletion: hand the single-use code to the server now (see "Revoking Apple's tokens").
   if (result.authorizationCode) {
-    const stored = await storeAppleToken(supabase, { authorizationCode: result.authorizationCode, clientId: Constants.expoConfig?.ios?.bundleIdentifier });
+    const stored = await storeAppleToken(supabase, {
+      authorizationCode: result.authorizationCode,
+      clientId: Constants.expoConfig?.ios?.bundleIdentifier,
+    });
     if (!stored.ok) console.warn(stored.error.message); // they're signed in either way
   }
 }
@@ -84,10 +105,15 @@ async function onApple() {
 import { GoogleOneTapSignIn } from "@react-native-google-signin/google-signin";
 import { signInWithGoogle } from "@marktiderman/genesis-supabase/native";
 
-GoogleOneTapSignIn.configure({ webClientId: WEB_CLIENT_ID, iosClientId: IOS_CLIENT_ID }); // once, at start-up
+GoogleOneTapSignIn.configure({
+  webClientId: WEB_CLIENT_ID,
+  iosClientId: IOS_CLIENT_ID,
+}); // once, at start-up
 
 async function onGoogle() {
-  const result = await signInWithGoogle(supabase, GoogleOneTapSignIn, { digest });
+  const result = await signInWithGoogle(supabase, GoogleOneTapSignIn, {
+    digest,
+  });
   if (result.canceled) return;
   if (result.error) return showError(result.error.message);
 }
@@ -119,11 +145,15 @@ import * as WebBrowser from "expo-web-browser";
 import { completeOAuthRedirect } from "@marktiderman/genesis-supabase/native";
 
 const redirectTo = "myapp://auth/callback";
-const { data } = await supabase.auth.signInWithOAuth({ provider: "google", options: { redirectTo, skipBrowserRedirect: true } });
+const { data } = await supabase.auth.signInWithOAuth({
+  provider: "google",
+  options: { redirectTo, skipBrowserRedirect: true },
+});
 const res = await WebBrowser.openAuthSessionAsync(data.url!, redirectTo);
 if (res.type === "success") {
   const result = await completeOAuthRedirect(supabase, res.url);
-  if (result.error) showError(result.error.message); // never result.error.providerMessage
+  if (result.error)
+    showError(result.error.message); // never result.error.providerMessage
   else if (result.redirectType === "recovery") router.push("/set-password");
 }
 ```
@@ -163,12 +193,12 @@ test is `migrations/tests/0001_genesis_account_deletion.test.sql`: copy it to
 
 It refuses, by error code (`SupabaseQueryError.code` on the client):
 
-| Code | When |
-|---|---|
+| Code    | When                                                                                                                             |
+| ------- | -------------------------------------------------------------------------------------------------------------------------------- |
 | `42501` | Nobody is signed in, or the person has a verified MFA factor and the session isn't `aal2`: verify the second factor, then retry. |
-| `GA001` | The app's hook refused (below). |
-| `GA002` | The app requires a recent sign-in and this one isn't: sign in again, then retry. |
-| `23503` | A row still references the login: a foreign key without `on delete cascade`, or files in Storage. |
+| `GA001` | The app's hook refused (below).                                                                                                  |
+| `GA002` | The app requires a recent sign-in and this one isn't: sign in again, then retry.                                                 |
+| `23503` | A row still references the login: a foreign key without `on delete cascade`, or files in Storage.                                |
 
 - **Your data:** deleting the login removes the rows whose foreign keys to `auth.users(id)` are
   `on delete cascade`, and is refused (`23503`) while any other row still points at it, so the
@@ -354,6 +384,15 @@ and release notes (`notes`, an array of `{ version, title?, body }`). Copy it in
 
 ## Push (the push block)
 
+> **Superseded by [`@marktiderman/genesis-notifications`](../notifications/README.md).** Its
+> migration adopts this one's three tables in place (adding columns, changing no row), replaces
+> `genesis_push_register` and `genesis_push_forget` with stricter versions (a token moves to
+> another login only from the same phone, and forget reveals nothing), and its runner replaces
+> the `genesis-push-send` function and the sender functions below. Migration 0005 and the
+> function stay here unchanged for apps that already run them; new apps take the notifications
+> block instead. When you move, remove 0005's pgTAP test from your app (two of its assertions
+> describe the old register and forget) and stop calling `genesis-push-send`.
+
 [`migrations/0005_genesis_push.sql`](./migrations/0005_genesis_push.sql) and the
 [`genesis-push-send`](./functions/genesis-push-send) Edge Function are the server half of
 `@marktiderman/genesis-native/push`. Copy the migration into your app's `supabase/migrations/`
@@ -467,11 +506,11 @@ into your app under a new timestamp; it stands alone.
 
 Functions (templates; copy the folder into `supabase/functions/`):
 
-| Function | What it does | Secrets |
-|---|---|---|
-| `genesis-support-intake` | The wire contract over HTTP (boot, submit, list) for clients without supabase-js; acts as the caller, never the service role | `GENESIS_SUPPORT_ORIGINS` (web origins) |
-| `genesis-support-notify` | A Database Webhook on new reports: a GitHub issue per report and/or a signed webhook, with a summary only (no person, device, context or screenshot) | `GENESIS_SUPPORT_WEBHOOK_SECRET`, `GITHUB_TOKEN` + `GITHUB_REPO`, `SUPPORT_WEBHOOK_URL` (+ `SUPPORT_WEBHOOK_SIGNING_SECRET`) |
-| `genesis-support-cleanup` | On a schedule: removes queued and orphaned screenshots through the Storage API | `GENESIS_SUPPORT_CLEANUP_SECRET` |
+| Function                  | What it does                                                                                                                                         | Secrets                                                                                                                      |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `genesis-support-intake`  | The wire contract over HTTP (boot, submit, list) for clients without supabase-js; acts as the caller, never the service role                         | `GENESIS_SUPPORT_ORIGINS` (web origins)                                                                                      |
+| `genesis-support-notify`  | A Database Webhook on new reports: a GitHub issue per report and/or a signed webhook, with a summary only (no person, device, context or screenshot) | `GENESIS_SUPPORT_WEBHOOK_SECRET`, `GITHUB_TOKEN` + `GITHUB_REPO`, `SUPPORT_WEBHOOK_URL` (+ `SUPPORT_WEBHOOK_SIGNING_SECRET`) |
+| `genesis-support-cleanup` | On a schedule: removes queued and orphaned screenshots through the Storage API                                                                       | `GENESIS_SUPPORT_CLEANUP_SECRET`                                                                                             |
 
 All three deploy with `verify_jwt = false` (each checks its caller or secret itself).
 
@@ -508,22 +547,31 @@ alter table public.tenant_feature_changes add foreign key (tenant_id) references
 Without the admin hook nobody can change a switch (`42501`, with a hint): it fails closed.
 
 ```ts
-import { setTenantFeature, tenantFeatures, tenantFeatureHistory } from "@marktiderman/genesis-supabase";
+import {
+  setTenantFeature,
+  tenantFeatures,
+  tenantFeatureHistory,
+} from "@marktiderman/genesis-supabase";
 
 const features = await tenantFeatures(supabase, teamId); // members and admins; 42501 for anyone else
 if (features.isOn("chat")) showChatTab();
 
-await setTenantFeature(supabase, { tenantId: teamId, featureId: "chat", enabled: false, reason: "Launching next month" });
+await setTenantFeature(supabase, {
+  tenantId: teamId,
+  featureId: "chat",
+  enabled: false,
+  reason: "Launching next month",
+});
 const history = await tenantFeatureHistory(supabase, teamId); // admins: who, when, why, newest first
 ```
 
-| | |
-| --- | --- |
+|                                                               |                                                                                |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------ |
 | `public.set_tenant_feature(tenant, feature, enabled, reason)` | admins only (the hook); a reason of 1 to 500 characters; a FeatureId-shaped id |
-| `public.tenant_features_off(tenant)` | the ids that are off; members (`private.genesis_tenant_member`) and admins |
-| `public.tenant_feature_settings(tenant)` | every switch with its reason, who and when; admins |
-| `public.tenant_feature_history(tenant, max_rows)` | every change, newest first; admins |
-| `private.tenant_feature_on(tenant, feature)` | for SQL gates; a feature with no row is on |
+| `public.tenant_features_off(tenant)`                          | the ids that are off; members (`private.genesis_tenant_member`) and admins     |
+| `public.tenant_feature_settings(tenant)`                      | every switch with its reason, who and when; admins                             |
+| `public.tenant_feature_history(tenant, max_rows)`             | every change, newest first; admins                                             |
+| `private.tenant_feature_on(tenant, feature)`                  | for SQL gates; a feature with no row is on                                     |
 
 Every change, through the function or by the service role writing the table directly, is
 recorded by a trigger in `public.tenant_feature_changes` with the person (none for the service
@@ -541,6 +589,52 @@ A delete that cascades into `tenant_features` (from your tenant table, or a pers
 goes with them) isn't recorded, so it never refuses the tenant's or the person's deletion; saving
 the same switch and reason again changes nothing, not even who and when.
 
+## Testing your schema's data contract (genesis_testing)
+
+`sql/testing/genesis_testing.sql` is a pgTAP kit that checks your own tables and functions keep the
+Genesis data rules. **Test databases only:** never put it in `supabase/migrations/`. It can sign
+in as anyone, and the API roles can't call it (only `sign_out` and `user_id`). Copy it to `supabase/tests/database/000_genesis_testing.test.sql` (the leading
+zeros make `supabase test db` run it first; it commits only the `genesis_testing` schema and reports
+one passing line of its own). Then call the helpers from your own test files, inside their usual
+`begin; … rollback;`:
+
+```sql
+select genesis_testing.create_users();          -- owner, staff, client, stranger (fixed ids)
+select genesis_testing.refuses($$delete from notes where id = '…'$$,
+  genesis_testing.user_id('client'), 'a client can''t delete a note outright');
+select genesis_testing.server_owned('public.notes', 'id', '…',
+  array['status', 'completed_at'], genesis_testing.user_id('client'));
+select genesis_testing.allows_system_paths($$delete from notes where id = '…'$$,
+  array['bt.hard_delete=on'], genesis_testing.user_id('client'), 'system work can delete');
+select genesis_testing.never_shows('select * from group_progress(''…'')', 'PRIVATE-ANSWER',
+  genesis_testing.user_id('staff'), 'a private answer never reaches the report');
+select genesis_testing.sees('select * from notes', genesis_testing.user_id('client'), 2, 'own notes only');
+```
+
+| Helper                                                               | Passes when                                                                                                           |
+| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `refuses(sql, user, description)`                                    | The write raises 42501 or changes no row.                                                                             |
+| `allows(sql, user, description, min_rows)`                           | It runs without an error (`user` null: signed out, as jobs and backfills run).                                        |
+| `allows_with_setting(sql, setting, value, user, description)`        | It runs with a bypass setting such as `bt.hard_delete`.                                                               |
+| `allows_system_paths(sql, settings, user, description)`              | It runs signed out and under each `name=value` setting (one line each).                                               |
+| `server_owned(table, key_column, key, columns, user)`                | The user can't change any of `columns` (one line each), whether the update raises, misses, or a trigger puts it back. |
+| `never_shows(query, marker, user, description)` / `never_shows_anon` | `marker` appears nowhere in what the query returns, for a table, a view or a report function.                         |
+| `sees(query, user, expected, description)`                           | The query returns exactly `expected` rows.                                                                            |
+
+A `user` of null means the system: no signed-in user and the test's own role, as jobs, backfills and
+migrations run. Checks only pass on evidence: any error other than a refusal fails them (so a typo
+can't pass), and "changed nothing" counts only when a control run can make the change (so a wrong
+key can't pass). Every check runs in a savepoint that is always rolled back, so checks never affect each other. A
+failing check prints why (`# changed from open to done`, `# raised 23514 …`). The `probe_*`
+functions return the same verdict as jsonb for testing your own helpers. `sign_in(who)`,
+`sign_in_anon()` and `sign_out()` act as someone for the rest of a test, setting both
+`request.jwt.claims` and the legacy `request.jwt.claim.sub`.
+
+What to cover, from the review history behind this kit: every guard trigger against every system
+path (signed out, your bypass settings, cascades and ON DELETE SET NULL); every column only the
+server sets; every security-definer function that reads a table with a privacy flag. The fixture
+ids are shared with `@marktiderman/genesis-core/testing`.
+
 ## Blocks
 
 `accountBlock` and `tenantFeaturesBlock` are `defineBlock` declarations
@@ -554,5 +648,4 @@ functions above don't change; the declarations are for `resolveBlocks` and the s
 - **The URL polyfill.** Supabase's React Native guides still import `react-native-url-polyfill/auto` before creating the client. Keep it until your app has tested PKCE sign-in end to end without it: React Native's built-in `URL` has improved, but the docs don't yet say it's enough.
 - **`refreshWhileActive` on native only.** Supabase gates the AppState listener to native platforms; call it from native code (not on web, where the browser already refreshes in the background).
 
-
 Part of the [Genesis framework](https://github.com/marktiderman/genesis).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marktiderman/genesis-supabase",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -37,6 +37,7 @@
     "dist",
     "functions",
     "migrations",
+    "sql",
     "README.md"
   ],
   "dependencies": {

package/sql/testing/genesis_testing.sql

@@ -0,0 +1,526 @@
+-- genesis_testing: pgTAP helpers that check an app's own schema keeps the data contract.
+--
+-- TEST DATABASES ONLY. Never put this file in `supabase/migrations/` (the doctor's supabase pack
+-- flags it there): it signs in as anyone and resets roles, which only a test may do.
+--
+-- Copy this file into your app's `supabase/tests/database/` as `000_genesis_testing.test.sql`. The
+-- leading zeros make `supabase test db` run it first, and it commits the `genesis_testing` schema
+-- (and nothing else) so the test files after it can call the helpers. It ends with a one-line plan
+-- of its own, so pg_prove reports it as a passing test file. Re-running it is safe: everything is
+-- `create or replace`.
+--
+-- Every check runs its statement in a savepoint that is always rolled back, so one check never
+-- changes what the next one sees. Each returns one pgTAP line (`ok …` / `not ok …`), with a `diag`
+-- explaining a failure. The `genesis_testing.probe_*` functions return the same verdict as jsonb
+-- ({ "pass": bool, "detail": text }) for tests of your own helpers.
+--
+-- A check only passes on evidence. A refusal counts only when it is one (42501, or a guard's
+-- `raise exception`, P0001); any other error fails the check, so a typo can't pass. "Changed no
+-- row" and "value unchanged" count only when a control run (the system, or a user you name) can
+-- make the same change, so a missing row or a wrong key can't pass either.
+--
+-- `user` arguments: a uuid acts as that signed-in user; null means the system: no signed-in user and
+-- the test's own role, the way jobs, backfills and migrations run.
+--
+-- Roles and sign-in follow Supabase: `authenticated`/`anon`/`service_role`, and `auth.uid()` reads
+-- `request.jwt.claims` (the legacy `request.jwt.claim.sub` is set too, for older images).
+--
+-- The contract it checks (Genesis data rules):
+--   * refuses:        a write the user may not make is refused, or changes no row the control can.
+--   * server_owned:   a client can't change columns only the server sets (status, kinds, totals…).
+--   * allows / allows_with_setting / allows_system_paths:
+--                     guards let system work through: no signed-in user (jobs, backfills), the
+--                     app's bypass settings (e.g. `bt.hard_delete`), cascades and ON DELETE SET NULL.
+--   * never_shows:    a private value never appears in what a user can read, reports included.
+--   * sees:           a user reads exactly the rows they should.
+--
+-- Requires pgTAP (`create extension if not exists pgtap with schema extensions;`, or any schema).
+
+create schema if not exists genesis_testing;
+
+-- Fixture people ----------------------------------------------------------------------------
+
+/**
+ * The shared fixture ids, the same ones `@marktiderman/genesis-core/testing` uses:
+ * owner, staff, client, stranger.
+ */
+create or replace function genesis_testing.user_id(_who text)
+returns uuid language sql immutable set search_path = '' as $$
+  select case _who
+    when 'owner' then '00000000-0000-4000-8000-000000000001'::uuid
+    when 'staff' then '00000000-0000-4000-8000-000000000002'::uuid
+    when 'client' then '00000000-0000-4000-8000-000000000003'::uuid
+    when 'stranger' then '00000000-0000-4000-8000-000000000004'::uuid
+  end
+$$;
+
+/** Creates the four fixture logins in auth.users (skips any that already exist). */
+create or replace function genesis_testing.create_users()
+returns void language sql set search_path = '' as $$
+  insert into auth.users (id, instance_id, aud, role, email, raw_app_meta_data, raw_user_meta_data, created_at, updated_at)
+  select genesis_testing.user_id(w), '00000000-0000-0000-0000-000000000000', 'authenticated', 'authenticated',
+         'genesis-testing-' || w || '@example.test', '{}'::jsonb, jsonb_build_object('full_name', initcap(w)), now(), now()
+    from unnest(array['owner', 'staff', 'client', 'stranger']) w
+  on conflict (id) do nothing
+$$;
+
+-- Acting as someone ---------------------------------------------------------------------------
+-- The probes never call a genesis_testing function while acting as a user (they inline
+-- set_config and `reset role`), so the API roles only need sign_out and user_id (see the end).
+
+/** Acts as a signed-in user for the rest of the transaction (or the enclosing savepoint). */
+create or replace function genesis_testing.sign_in(_user uuid)
+returns void language plpgsql set search_path = '' as $$
+begin
+  perform pg_catalog.set_config('request.jwt.claims',
+    pg_catalog.json_build_object('sub', _user, 'role', 'authenticated')::text, true);
+  perform pg_catalog.set_config('request.jwt.claim.sub', _user::text, true);
+  perform pg_catalog.set_config('role', 'authenticated', true);
+end $$;
+
+/** Acts as a fixture person: 'owner', 'staff', 'client' or 'stranger'. */
+create or replace function genesis_testing.sign_in(_who text)
+returns void language sql set search_path = '' as $$
+  select genesis_testing.sign_in(genesis_testing.user_id(_who))
+$$;
+
+/** Acts as someone signed out (the anon key). */
+create or replace function genesis_testing.sign_in_anon()
+returns void language plpgsql set search_path = '' as $$
+begin
+  perform pg_catalog.set_config('request.jwt.claims', '{"role":"anon"}', true);
+  perform pg_catalog.set_config('request.jwt.claim.sub', '', true);
+  perform pg_catalog.set_config('role', 'anon', true);
+end $$;
+
+/** Back to the test's own role with no claims: the system, as jobs, backfills and migrations run. */
+create or replace function genesis_testing.sign_out()
+returns void language plpgsql set search_path = '' as $$
+begin
+  perform pg_catalog.set_config('request.jwt.claims', '', true);
+  perform pg_catalog.set_config('request.jwt.claim.sub', '', true);
+  execute 'reset role';
+end $$;
+
+/** Internal: act as `_user` (null: the system) without calling another genesis_testing function. */
+create or replace function genesis_testing._act(_user uuid)
+returns void language plpgsql set search_path = '' as $$
+begin
+  if _user is null then
+    perform pg_catalog.set_config('request.jwt.claims', '', true);
+    perform pg_catalog.set_config('request.jwt.claim.sub', '', true);
+    execute 'reset role';
+  else
+    perform pg_catalog.set_config('request.jwt.claims',
+      pg_catalog.json_build_object('sub', _user, 'role', 'authenticated')::text, true);
+    perform pg_catalog.set_config('request.jwt.claim.sub', _user::text, true);
+    perform pg_catalog.set_config('role', 'authenticated', true);
+  end if;
+end $$;
+
+/** Whether an error is a refusal: 42501 (insufficient privilege) or P0001 (a guard's raise). */
+create or replace function genesis_testing.is_refusal(_sqlstate text)
+returns boolean language sql immutable set search_path = '' as $$
+  select _sqlstate in ('42501', 'P0001')
+$$;
+
+-- Probes (verdicts as jsonb) ------------------------------------------------------------------
+
+/**
+ * Runs `_sql` as `_user` (null: the system) in a savepoint that is rolled back. Returns
+ * { ok, rows, sqlstate, message }: `ok` is false when it raised.
+ */
+create or replace function genesis_testing.run_as(_sql text, _user uuid)
+returns jsonb language plpgsql set search_path = '' as $$
+declare
+  _rows bigint := 0;
+  _out jsonb;
+begin
+  begin
+    perform genesis_testing._act(_user);
+    execute _sql;
+    get diagnostics _rows = row_count;
+    _out := pg_catalog.jsonb_build_object('ok', true, 'rows', _rows);
+    raise exception using errcode = 'GT000', message = 'genesis_testing rollback';
+  exception
+    when sqlstate 'GT000' then null;
+    when others then
+      _out := pg_catalog.jsonb_build_object('ok', false, 'rows', 0, 'sqlstate', sqlstate, 'message', sqlerrm);
+  end;
+  return _out;
+end $$;
+
+/**
+ * `refuses` as a verdict. Passes when `_user` gets a refusal (42501/P0001), or changes no row while
+ * the control (`_control_user`, null: the system) changes at least one with the same statement.
+ */
+create or replace function genesis_testing.probe_refuses(_sql text, _user uuid, _control_user uuid default null)
+returns jsonb language plpgsql set search_path = '' as $$
+declare
+  _r jsonb := genesis_testing.run_as(_sql, _user);
+  _c jsonb;
+begin
+  if not (_r ->> 'ok')::boolean then
+    return pg_catalog.jsonb_build_object('pass', genesis_testing.is_refusal(_r ->> 'sqlstate'),
+      'detail', case when genesis_testing.is_refusal(_r ->> 'sqlstate') then 'refused: ' || (_r ->> 'message')
+        else pg_catalog.format('raised %s (%s), which isn''t a refusal (42501 or P0001)', _r ->> 'sqlstate', _r ->> 'message') end);
+  end if;
+  if (_r ->> 'rows')::bigint > 0 then
+    return pg_catalog.jsonb_build_object('pass', false,
+      'detail', pg_catalog.format('it ran and changed %s row(s)', _r ->> 'rows'));
+  end if;
+  _c := genesis_testing.run_as(_sql, _control_user);
+  return pg_catalog.jsonb_build_object('pass', (_c ->> 'ok')::boolean and (_c ->> 'rows')::bigint > 0,
+    'detail', case
+      when not (_c ->> 'ok')::boolean then pg_catalog.format('the control raised %s (%s), so there was nothing to refuse', _c ->> 'sqlstate', _c ->> 'message')
+      when (_c ->> 'rows')::bigint = 0 then 'the control changed no row either: nothing to refuse (check the statement and the row)'
+      else 'changed no row; the control changed ' || (_c ->> 'rows') end);
+end $$;
+
+/** `allows` as a verdict: ran without an error (optionally changing at least `_min_rows`). */
+create or replace function genesis_testing.probe_allows(_sql text, _user uuid, _min_rows bigint default 0)
+returns jsonb language plpgsql set search_path = '' as $$
+declare
+  _r jsonb := genesis_testing.run_as(_sql, _user);
+begin
+  if not (_r ->> 'ok')::boolean then
+    return pg_catalog.jsonb_build_object('pass', false,
+      'detail', pg_catalog.format('raised %s: %s', _r ->> 'sqlstate', _r ->> 'message'));
+  end if;
+  return pg_catalog.jsonb_build_object('pass', (_r ->> 'rows')::bigint >= _min_rows,
+    'detail', pg_catalog.format('changed %s row(s), expected at least %s', _r ->> 'rows', _min_rows));
+end $$;
+
+/**
+ * An SQL expression of `_type` that differs from `_current` (its text form), or null when the type
+ * needs a value from the caller (arrays, ranges, composite and other types). Domains use their base
+ * type; enums pick another label.
+ */
+create or replace function genesis_testing.other_value(_type regtype, _current text)
+returns text language plpgsql stable set search_path = '' as $$
+declare
+  _base regtype := _type;
+  _label text;
+begin
+  select coalesce(nullif(t.typbasetype, 0), t.oid)::regtype into _base from pg_catalog.pg_type t where t.oid = _type;
+  if exists (select 1 from pg_catalog.pg_type t where t.oid = _base and t.typtype = 'e') then
+    select e.enumlabel into _label from pg_catalog.pg_enum e
+     where e.enumtypid = _base and e.enumlabel is distinct from _current
+     order by e.enumsortorder limit 1;
+    return case when _label is null then null else pg_catalog.quote_literal(_label) || '::' || _type::text end;
+  end if;
+  return case
+    when _base = 'boolean'::regtype then pg_catalog.quote_literal(coalesce(not _current::boolean, true)::text)
+    when _base in ('smallint'::regtype, 'integer'::regtype, 'bigint'::regtype, 'numeric'::regtype,
+                   'real'::regtype, 'double precision'::regtype)
+      then pg_catalog.quote_literal((coalesce(_current::numeric, 0) + 1)::text)
+    when _base = 'uuid'::regtype then pg_catalog.quote_literal(gen_random_uuid()::text)
+    when _base in ('timestamptz'::regtype, 'timestamp'::regtype)
+      then pg_catalog.quote_literal((coalesce(_current::timestamptz, now()) + interval '1 day')::text)
+    when _base = 'date'::regtype then pg_catalog.quote_literal((coalesce(_current::date, current_date) + 1)::text)
+    when _base in ('jsonb'::regtype, 'json'::regtype) then pg_catalog.quote_literal('{"genesis_testing":true}')
+    when (select t.typname from pg_catalog.pg_type t where t.oid = _base) in ('text', 'varchar', 'bpchar', 'citext')
+      then pg_catalog.quote_literal('genesis_testing:' || coalesce(_current, ''))
+    else null
+  end || '::' || _type::text;
+end $$;
+
+/**
+ * `server_owned` as a verdict for one column. A control run (the system) first sets `_column` of
+ * the row `_key_column` = `_key` to a different value (`_value`, an SQL expression, or one chosen
+ * for the type) and must change the stored value: that proves the row exists and the value is
+ * writable at all. Then, as `_user`, the same update must leave the stored value as it was, whether
+ * it was refused (42501/P0001), matched no row, or a trigger put the value back. Any other error
+ * fails the check.
+ */
+create or replace function genesis_testing.probe_server_owned(
+  _table regclass, _key_column text, _key text, _column text, _user uuid, _value text default null)
+returns jsonb language plpgsql set search_path = '' as $$
+declare
+  _type regtype;
+  _expr text;
+  _update text;
+  _read text;
+  _before text;
+  _control text;
+  _after text;
+  _state text;
+  _err text;
+begin
+  select a.atttypid::regtype into _type
+    from pg_catalog.pg_attribute a
+   where a.attrelid = _table and a.attname = _column and a.attnum > 0 and not a.attisdropped;
+  if _type is null then
+    return pg_catalog.jsonb_build_object('pass', false, 'detail', pg_catalog.format('%s has no column %s', _table, _column));
+  end if;
+  _read := pg_catalog.format('select (%I)::text from %s where %I::text = %L', _column, _table, _key_column, _key);
+  execute _read into _before;
+  _expr := coalesce(_value, genesis_testing.other_value(_type, _before));
+  if _expr is null then
+    return pg_catalog.jsonb_build_object('pass', false,
+      'detail', pg_catalog.format('pass a value for %s (type %s) to try', _column, _type));
+  end if;
+  _update := pg_catalog.format('update %s set %I = %s where %I::text = %L', _table, _column, _expr, _key_column, _key);
+
+  -- Control: the system can make the change (the row exists and the new value differs).
+  begin
+    perform genesis_testing._act(null);
+    begin
+      execute _update;
+      execute _read into _control;
+    exception when others then
+      _err := sqlstate || ' ' || sqlerrm;
+    end;
+    raise exception using errcode = 'GT000', message = 'genesis_testing rollback';
+  exception when sqlstate 'GT000' then null;
+  end;
+  if _err is not null then
+    return pg_catalog.jsonb_build_object('pass', false, 'detail', 'the control update raised ' || _err);
+  end if;
+  if _control is not distinct from _before then
+    return pg_catalog.jsonb_build_object('pass', false, 'detail', pg_catalog.format(
+      'the control couldn''t change %s either (no row with %s = %s, or the same value): nothing was tested',
+      _column, _key_column, _key));
+  end if;
+
+  -- As the user.
+  begin
+    perform genesis_testing._act(_user);
+    begin
+      execute _update;
+    exception when others then
+      _state := sqlstate;
+      _err := sqlstate || ' ' || sqlerrm;
+    end;
+    -- Back to the test's role inline: the API roles can't call genesis_testing._act.
+    execute 'reset role';
+    execute _read into _after;
+    raise exception using errcode = 'GT000', message = 'genesis_testing rollback';
+  exception when sqlstate 'GT000' then null;
+  end;
+  if _state is not null and not genesis_testing.is_refusal(_state) then
+    return pg_catalog.jsonb_build_object('pass', false,
+      'detail', 'raised ' || _err || ', which isn''t a refusal (42501 or P0001)');
+  end if;
+  return pg_catalog.jsonb_build_object('pass', _after is not distinct from _before,
+    'detail', case
+      when _after is not distinct from _before then coalesce('refused: ' || _err, 'unchanged')
+      else pg_catalog.format('%s changed from %s to %s', _column, coalesce(_before, 'null'), coalesce(_after, 'null'))
+    end);
+end $$;
+
+/**
+ * `never_shows` as a verdict: runs `_query` as `_user` (null: the system; `_anon`: signed out with
+ * the anon key) and passes when `_marker` appears nowhere in its rows. A refusal (42501/P0001)
+ * counts as showing nothing; any other error fails the check.
+ */
+create or replace function genesis_testing.probe_never_shows(_query text, _marker text, _user uuid, _anon boolean default false)
+returns jsonb language plpgsql set search_path = '' as $$
+declare
+  _text text;
+  _esc text;
+  _shown boolean;
+  _state text;
+  _err text;
+begin
+  begin
+    if _anon then
+      perform pg_catalog.set_config('request.jwt.claims', '{"role":"anon"}', true);
+      perform pg_catalog.set_config('request.jwt.claim.sub', '', true);
+      perform pg_catalog.set_config('role', 'anon', true);
+    else
+      perform genesis_testing._act(_user);
+    end if;
+    begin
+      execute pg_catalog.format('select coalesce(jsonb_agg(to_jsonb(q))::text, '''') from (%s) q', _query) into _text;
+    exception when others then
+      _state := sqlstate;
+      _err := sqlstate || ' ' || sqlerrm;
+    end;
+    raise exception using errcode = 'GT000', message = 'genesis_testing rollback';
+  exception when sqlstate 'GT000' then null;
+  end;
+  if _state is not null then
+    return pg_catalog.jsonb_build_object('pass', genesis_testing.is_refusal(_state),
+      'detail', case when genesis_testing.is_refusal(_state) then 'refused: ' || _err
+        else 'raised ' || _err || ', which isn''t a refusal: fix the query' end);
+  end if;
+  -- The rows are serialized as JSON, which escapes quotes, backslashes and control characters,
+  -- so look for the marker as JSON writes it too.
+  _esc := pg_catalog.to_jsonb(_marker)::text;
+  _esc := pg_catalog.substr(_esc, 2, pg_catalog.length(_esc) - 2);
+  _shown := pg_catalog.strpos(_text, _marker) > 0 or pg_catalog.strpos(_text, _esc) > 0;
+  return pg_catalog.jsonb_build_object('pass', not _shown,
+    'detail', case when not _shown then 'not shown'
+                   else pg_catalog.format('%L appears in: %s', _marker, pg_catalog.left(_text, 300)) end);
+end $$;
+
+/** `sees` as a verdict: `_query` returns exactly `_expected` rows for `_user` (null: the system). */
+create or replace function genesis_testing.probe_sees(_query text, _user uuid, _expected bigint)
+returns jsonb language plpgsql set search_path = '' as $$
+declare
+  _n bigint;
+  _err text;
+begin
+  begin
+    perform genesis_testing._act(_user);
+    begin
+      execute pg_catalog.format('select count(*) from (%s) q', _query) into _n;
+    exception when others then
+      _err := sqlstate || ' ' || sqlerrm;
+    end;
+    raise exception using errcode = 'GT000', message = 'genesis_testing rollback';
+  exception when sqlstate 'GT000' then null;
+  end;
+  if _err is not null then
+    return pg_catalog.jsonb_build_object('pass', false, 'detail', 'raised ' || _err);
+  end if;
+  return pg_catalog.jsonb_build_object('pass', _n = _expected,
+    'detail', pg_catalog.format('saw %s row(s), expected %s', _n, _expected));
+end $$;
+
+-- Assertions (pgTAP lines) --------------------------------------------------------------------
+
+/**
+ * One pgTAP line from a verdict, with the detail as a diagnostic when it failed. pgTAP's own
+ * functions call each other unqualified, so this finds pgTAP's schema and runs with it on the path.
+ */
+create or replace function genesis_testing.tap(_verdict jsonb, _description text)
+returns text language plpgsql set search_path = '' as $$
+declare
+  _schema text;
+  _line text;
+  _path text := pg_catalog.current_setting('search_path');
+begin
+  select n.nspname into _schema
+    from pg_catalog.pg_extension x join pg_catalog.pg_namespace n on n.oid = x.extnamespace
+   where x.extname = 'pgtap';
+  if _schema is null then
+    raise exception 'genesis_testing needs pgTAP: create extension pgtap';
+  end if;
+  perform pg_catalog.set_config('search_path', pg_catalog.quote_ident(_schema), true);
+  execute 'select ok($1, $2)' into _line using (_verdict ->> 'pass')::boolean, _description;
+  if not (_verdict ->> 'pass')::boolean then
+    execute 'select $1 || E''\n'' || diag($2)' into _line using _line, _verdict ->> 'detail';
+  end if;
+  perform pg_catalog.set_config('search_path', _path, true);
+  return _line;
+end $$;
+
+/**
+ * `_user` may not do `_sql`: it's refused (42501/P0001), or changes no row while the control
+ * (`_control_user`, null: the system) changes at least one.
+ */
+create or replace function genesis_testing.refuses(_sql text, _user uuid, _description text, _control_user uuid default null)
+returns text language sql set search_path = '' as $$
+  select genesis_testing.tap(genesis_testing.probe_refuses(_sql, _user, _control_user), _description)
+$$;
+
+/** `_user` (null: the system) can do `_sql` without an error, changing at least `_min_rows`. */
+create or replace function genesis_testing.allows(_sql text, _user uuid, _description text, _min_rows bigint default 0)
+returns text language sql set search_path = '' as $$
+  select genesis_testing.tap(genesis_testing.probe_allows(_sql, _user, _min_rows), _description)
+$$;
+
+/**
+ * `_sql` runs with the bypass setting `_setting` = `_value` (e.g. 'bt.hard_delete' = 'on'), as
+ * `_user` (null: the system). The setting only lasts for this check.
+ */
+create or replace function genesis_testing.allows_with_setting(
+  _sql text, _setting text, _value text, _user uuid, _description text)
+returns text language plpgsql set search_path = '' as $$
+declare
+  _verdict jsonb;
+begin
+  begin
+    perform pg_catalog.set_config(_setting, _value, true);
+    _verdict := genesis_testing.probe_allows(_sql, _user);
+    raise exception using errcode = 'GT000', message = 'genesis_testing rollback';
+  exception when sqlstate 'GT000' then null;
+  end;
+  return genesis_testing.tap(_verdict, _description);
+end $$;
+
+/**
+ * Every system path can do `_sql`: the system (signed out) and each bypass setting in `_settings`
+ * ('name=value'), as `_user` when one is given. One line per path.
+ */
+create or replace function genesis_testing.allows_system_paths(
+  _sql text, _settings text[], _user uuid, _description text)
+returns setof text language plpgsql set search_path = '' as $$
+declare
+  _s text;
+begin
+  return next genesis_testing.allows(_sql, null, _description || ' (the system, no signed-in user)');
+  foreach _s in array coalesce(_settings, array[]::text[]) loop
+    -- Split on the first '=' only: the value may contain '=' itself.
+    return next genesis_testing.allows_with_setting(_sql, pg_catalog.split_part(_s, '=', 1),
+      pg_catalog.substr(_s, pg_catalog.strpos(_s, '=') + 1), _user,
+      pg_catalog.format('%s (%s)', _description, _s));
+  end loop;
+end $$;
+
+/**
+ * A client can't change any of `_columns` on the row `_key_column` = `_key`: one line per column.
+ * Use it for every column only the server sets (status the server derives, kinds, totals, owner
+ * and audit columns, timestamps a trigger stamps). For an array, range or composite column, call
+ * `probe_server_owned` with a `_value` to try.
+ */
+create or replace function genesis_testing.server_owned(
+  _table regclass, _key_column text, _key text, _columns text[], _user uuid)
+returns setof text language plpgsql set search_path = '' as $$
+declare
+  _c text;
+begin
+  foreach _c in array _columns loop
+    return next genesis_testing.tap(
+      genesis_testing.probe_server_owned(_table, _key_column, _key, _c, _user),
+      pg_catalog.format('%s.%s is server-owned for %s', _table, _c, coalesce(_user::text, 'the system')));
+  end loop;
+end $$;
+
+/**
+ * `_marker` (a value only a private row holds) never appears in what `_user` reads through
+ * `_query`: a table, a view, or a report function (`select * from report_fn(…)`). Use it for
+ * every security-definer function that reads a table with a privacy flag.
+ */
+create or replace function genesis_testing.never_shows(_query text, _marker text, _user uuid, _description text)
+returns text language sql set search_path = '' as $$
+  select genesis_testing.tap(genesis_testing.probe_never_shows(_query, _marker, _user), _description)
+$$;
+
+/** Like never_shows, signed out with the anon key. */
+create or replace function genesis_testing.never_shows_anon(_query text, _marker text, _description text)
+returns text language sql set search_path = '' as $$
+  select genesis_testing.tap(genesis_testing.probe_never_shows(_query, _marker, null, true), _description)
+$$;
+
+/** `_user` (null: the system) reads exactly `_expected` rows through `_query`. */
+create or replace function genesis_testing.sees(_query text, _user uuid, _expected bigint, _description text)
+returns text language sql set search_path = '' as $$
+  select genesis_testing.tap(genesis_testing.probe_sees(_query, _user, _expected), _description)
+$$;
+
+-- Privileges: the API roles can't call any of this, except sign_out (a test calls it while acting
+-- as a user to get back to its own role) and user_id (a fixed id, used in assertions made while
+-- signed in). To switch users, sign_out first. Revoked by name (no blanket grants or revokes).
+revoke usage on schema genesis_testing from public;
+do $$
+declare
+  _f regprocedure;
+begin
+  for _f in
+    select p.oid::regprocedure from pg_catalog.pg_proc p
+      join pg_catalog.pg_namespace n on n.oid = p.pronamespace
+     where n.nspname = 'genesis_testing'
+  loop
+    execute pg_catalog.format('revoke execute on function %s from public, anon, authenticated, service_role', _f);
+  end loop;
+end $$;
+grant usage on schema genesis_testing to anon, authenticated;
+grant execute on function genesis_testing.sign_out(), genesis_testing.user_id(text) to anon, authenticated;
+
+-- When run as a test file of its own (000_genesis_testing.test.sql), report that it loaded.
+select plan(1);
+select has_schema('genesis_testing', 'genesis_testing helpers are loaded');
+select * from finish();

package/sql/testing/tests/genesis_testing.test.sql

@@ -0,0 +1,181 @@
+-- Tests for genesis_testing.sql against a small sample schema with good and deliberately broken
+-- rules, so each helper is shown both passing and catching a failure (through its probe_*).
+-- Run: load genesis_testing.sql, then this file, in one database with pgTAP.
+begin;
+create extension if not exists pgtap with schema extensions;
+select plan(39);
+
+select genesis_testing.create_users();
+
+-- A sample app: notes owned by a person, with a server-owned status, a guarded delete that
+-- system work may bypass, a child table with ON DELETE SET NULL, and a private flag.
+create type public.gt_mood as enum ('calm', 'busy');
+create table public.gt_notes (
+  id uuid primary key,
+  owner uuid not null references auth.users (id),
+  body text not null,
+  status text not null default 'open',
+  private boolean not null default false,
+  mood public.gt_mood not null default 'calm',
+  tags text[] not null default '{}',
+  stage text not null default 'draft' check (stage in ('draft', 'sent'))
+);
+create table public.gt_links (
+  id uuid primary key,
+  note_id uuid references public.gt_notes (id) on delete set null
+);
+alter table public.gt_notes enable row level security;
+alter table public.gt_links enable row level security;
+create policy "own notes" on public.gt_notes for all to authenticated
+  using (owner = (select auth.uid())) with check (owner = (select auth.uid()));
+create policy "links" on public.gt_links for all to authenticated using (true) with check (true);
+grant select, insert, update, delete on public.gt_notes, public.gt_links to authenticated;
+grant select on public.gt_notes to anon;
+
+-- status is server-owned: a trigger puts it back for signed-in users.
+create function public.gt_notes_guard() returns trigger language plpgsql as $$
+begin
+  if (select auth.uid()) is not null and new.status is distinct from old.status then
+    new.status := old.status;
+  end if;
+  return new;
+end $$;
+create trigger gt_notes_guard before update on public.gt_notes for each row execute function public.gt_notes_guard();
+
+-- Deleting is refused unless system work (no user, or gt.hard_delete=on).
+create function public.gt_notes_no_delete() returns trigger language plpgsql as $$
+begin
+  if (select auth.uid()) is not null and coalesce(current_setting('gt.hard_delete', true), '') <> 'on' then
+    raise exception 'Bin it instead' using errcode = '42501';
+  end if;
+  return old;
+end $$;
+create trigger gt_notes_no_delete before delete on public.gt_notes for each row execute function public.gt_notes_no_delete();
+
+-- A report that respects the private flag, and a broken one that leaks it.
+create function public.gt_report_good() returns table (owner uuid, body text)
+language sql security definer set search_path = '' as $$
+  select n.owner, n.body from public.gt_notes n where not n.private
+$$;
+create function public.gt_report_leaky() returns table (owner uuid, body text)
+language sql security definer set search_path = '' as $$
+  select n.owner, n.body from public.gt_notes n
+$$;
+grant execute on function public.gt_report_good(), public.gt_report_leaky() to authenticated;
+
+insert into public.gt_notes (id, owner, body, private) values
+  ('00000000-0000-4000-9000-000000000001', genesis_testing.user_id('client'), 'shared note', false),
+  ('00000000-0000-4000-9000-000000000002', genesis_testing.user_id('client'), 'SECRET-DIARY', true),
+  ('00000000-0000-4000-9000-000000000003', genesis_testing.user_id('owner'), 'owner note', false);
+insert into public.gt_links values ('00000000-0000-4000-9100-000000000001', '00000000-0000-4000-9000-000000000001');
+
+-- Fixtures and acting as someone ---------------------------------------------------------------
+select is(genesis_testing.user_id('client'), '00000000-0000-4000-8000-000000000003'::uuid, 'fixture ids are fixed');
+select is((select count(*) from auth.users where email like 'genesis-testing-%@example.test'), 4::bigint, 'four fixture logins');
+select genesis_testing.sign_in('client');
+select is((select auth.uid()), genesis_testing.user_id('client'), 'sign_in sets auth.uid()');
+select is(current_user::text, 'authenticated', 'sign_in acts as authenticated');
+select genesis_testing.sign_out();
+select is((select auth.uid()), null, 'sign_out clears the user');
+
+-- refuses ---------------------------------------------------------------------------------------
+select genesis_testing.refuses(
+  $$update public.gt_notes set body = 'x' where id = '00000000-0000-4000-9000-000000000001'$$,
+  genesis_testing.user_id('stranger'), 'a stranger changes no row of the client''s note');
+select genesis_testing.refuses(
+  $$delete from public.gt_notes where id = '00000000-0000-4000-9000-000000000001'$$,
+  genesis_testing.user_id('client'), 'the client can''t delete outright (42501)');
+select is((genesis_testing.probe_refuses(
+  $$update public.gt_notes set body = 'x' where id = '00000000-0000-4000-9000-000000000001'$$,
+  genesis_testing.user_id('client')) ->> 'pass')::boolean, false,
+  'refuses fails when the user can make the change');
+select is((select body from public.gt_notes where id = '00000000-0000-4000-9000-000000000001'), 'shared note',
+  'a probe leaves no change behind');
+
+-- server_owned ----------------------------------------------------------------------------------
+select genesis_testing.server_owned('public.gt_notes', 'id', '00000000-0000-4000-9000-000000000001',
+  array['status'], genesis_testing.user_id('client'));
+select is((genesis_testing.probe_server_owned('public.gt_notes', 'id', '00000000-0000-4000-9000-000000000001',
+  'private', genesis_testing.user_id('client')) ->> 'pass')::boolean, false,
+  'server_owned catches a column the client can change');
+select is((genesis_testing.probe_server_owned('public.gt_notes', 'id', '00000000-0000-4000-9000-000000000001',
+  'nope', genesis_testing.user_id('client')) ->> 'pass')::boolean, false, 'server_owned fails on a missing column');
+select is((genesis_testing.probe_server_owned('public.gt_notes', 'id', '00000000-0000-4000-9000-000000000001',
+  'body', genesis_testing.user_id('stranger')) ->> 'pass')::boolean, true,
+  'a column RLS keeps the user away from passes too');
+
+-- allows and the system paths ------------------------------------------------------------------
+select genesis_testing.allows_system_paths(
+  $$delete from public.gt_notes where id = '00000000-0000-4000-9000-000000000001'$$,
+  array['gt.hard_delete=on'], genesis_testing.user_id('client'), 'the guard lets system deletes through');
+select is((genesis_testing.probe_allows(
+  $$delete from public.gt_notes where id = '00000000-0000-4000-9000-000000000001'$$,
+  genesis_testing.user_id('client')) ->> 'pass')::boolean, false, 'allows fails when the guard refuses');
+select genesis_testing.allows(
+  $$delete from public.gt_notes where id = '00000000-0000-4000-9000-000000000001'$$, null,
+  'ON DELETE SET NULL on a child doesn''t trip a guard', 1);
+select is((genesis_testing.probe_allows(
+  $$update public.gt_notes set body = body where id = '00000000-0000-4000-9000-000000000001'$$,
+  genesis_testing.user_id('client'), 2) ->> 'pass')::boolean, false, 'allows checks the minimum rows changed');
+
+select genesis_testing.allows_system_paths(
+  $$select 1 where coalesce(current_setting('gt.mode', true), 'a=b') = 'a=b'$$,
+  array['gt.mode=a=b'], genesis_testing.user_id('client'), 'a setting value may contain =');
+
+-- never_shows and sees ---------------------------------------------------------------------------
+select genesis_testing.never_shows('select * from public.gt_report_good()', 'SECRET-DIARY',
+  genesis_testing.user_id('owner'), 'the good report hides private notes');
+select is((genesis_testing.probe_never_shows('select * from public.gt_report_leaky()', 'SECRET-DIARY',
+  genesis_testing.user_id('owner')) ->> 'pass')::boolean, false, 'never_shows catches a leaky report');
+select is((genesis_testing.probe_never_shows($$select 'say "hi"' as v$$, 'say "hi"',
+  genesis_testing.user_id('owner')) ->> 'pass')::boolean, false, 'never_shows finds a marker JSON escapes');
+select genesis_testing.never_shows_anon('select * from public.gt_notes', 'SECRET-DIARY',
+  'anon sees no notes (RLS, no anon policy)');
+select genesis_testing.sees('select * from public.gt_notes', genesis_testing.user_id('client'), 2,
+  'the client sees their two notes');
+select is((genesis_testing.probe_sees('select * from public.gt_notes', genesis_testing.user_id('stranger'), 1)
+  ->> 'pass')::boolean, false, 'sees fails on the wrong count');
+
+-- No false passes ---------------------------------------------------------------------------------
+select is((genesis_testing.probe_refuses(
+  $$update public.gt_notes set body = 'x' where id = '00000000-0000-4000-9000-0000000000ff'$$,
+  genesis_testing.user_id('stranger')) ->> 'pass')::boolean, false,
+  'refuses fails when the control can''t change a row either (wrong id)');
+select is((genesis_testing.probe_refuses(
+  $$update public.gt_notse set body = 'x'$$, genesis_testing.user_id('stranger')) ->> 'pass')::boolean, false,
+  'refuses fails on an error that isn''t a refusal (a typo)');
+select is((genesis_testing.probe_refuses(
+  $$update public.gt_notes set body = 'x' where id = '00000000-0000-4000-9000-000000000001'$$,
+  genesis_testing.user_id('stranger'), genesis_testing.user_id('owner')) ->> 'pass')::boolean, false,
+  'refuses fails when the named control can''t make the change either');
+select is((genesis_testing.probe_never_shows('select * from public.gt_reprot_good()', 'SECRET-DIARY',
+  genesis_testing.user_id('owner')) ->> 'pass')::boolean, false, 'never_shows fails on a typo, not passes');
+select is((genesis_testing.probe_server_owned('public.gt_notes', 'id', '00000000-0000-4000-9000-0000000000ff',
+  'status', genesis_testing.user_id('client')) ->> 'pass')::boolean, false,
+  'server_owned fails on a key that matches no row');
+select is((genesis_testing.probe_server_owned('public.gt_notes', 'id', '00000000-0000-4000-9000-000000000001',
+  'mood', genesis_testing.user_id('client')) ->> 'pass')::boolean, false,
+  'server_owned handles enums: a writable enum column fails');
+select is((genesis_testing.probe_server_owned('public.gt_notes', 'id', '00000000-0000-4000-9000-000000000001',
+  'tags', genesis_testing.user_id('client')) ->> 'detail'), 'pass a value for tags (type text[]) to try',
+  'server_owned asks for a value for an array column instead of passing');
+select is((genesis_testing.probe_server_owned('public.gt_notes', 'id', '00000000-0000-4000-9000-000000000001',
+  'tags', genesis_testing.user_id('client'), $$array['x']$$) ->> 'pass')::boolean, false,
+  'with a value, a writable array column fails');
+select is((genesis_testing.probe_server_owned('public.gt_notes', 'id', '00000000-0000-4000-9000-000000000001',
+  'stage', genesis_testing.user_id('client')) ->> 'pass')::boolean, false,
+  'server_owned fails when the tried value breaks a check (the control raises), not passes');
+select is((genesis_testing.probe_server_owned('public.gt_notes', 'id', '00000000-0000-4000-9000-000000000001',
+  'stage', genesis_testing.user_id('client'), $$'sent'$$) ->> 'pass')::boolean, false,
+  'with a valid value, a writable checked column fails');
+
+-- Privileges -------------------------------------------------------------------------------------
+select ok(not has_function_privilege('authenticated', 'genesis_testing.run_as(text, uuid)', 'execute'),
+  'API roles can''t run statements through the kit');
+select ok(not has_function_privilege('anon', 'genesis_testing.sign_in(uuid)', 'execute'),
+  'API roles can''t sign in as someone');
+select ok(has_function_privilege('authenticated', 'genesis_testing.sign_out()', 'execute'),
+  'a test acting as a user can sign out');
+
+select * from finish();
+rollback;