@fayz-ai/db 0.11.0 → 0.13.0

package/migrations/064_agent_guard_authz.sql

@@ -0,0 +1,118 @@
+-- ============================================================================
+-- 064_agent_guard_authz.sql — agent_guard reads the authz tables (#134, PRD 01 R9).
+--
+-- public.agent_guard(tenant, actor, feature, action, limit_key, used, n) is the
+-- SQL mirror of resolveAccess/resolveLimit that every agent_* write RPC in the
+-- fleet calls first (agenda 005/006/008/014, crm 011/012, financial 009, forms
+-- 003, marketing 007, blog 002). Same signature, same return contract (NULL =
+-- allowed; the AgentDenial jsonb otherwise), same actor-spoof guard as 016,
+-- same plan/limit part as 015. What changes is WHERE the role decision comes
+-- from: the actor's ACTIVE membership in app.memberships and the permission set
+-- of its role in app.role_permissions. There is no owner special case any more:
+-- an owner passes because its role holds the whole catalog.
+--
+-- Key resolution: '{feature}.{action}' passes when the role holds that key,
+-- '{feature}.manage', or the plugin-root '{plugin}.manage' (the first segment
+-- of the feature — the same "the resource's own {plugin}.manage" reading 041
+-- uses for resource_grants). Sub-features such as 'financial.receivables' are
+-- therefore covered by 'financial.manage' until #136 seeds each plugin's own
+-- declaredFeatures keys.
+--
+-- Legacy tenant_role_overrides / role_permissions (public.*) are no longer
+-- consulted: per-tenant customisation is app.roles + app.role_permissions.
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION public.agent_guard(
+  p_tenant_id uuid,
+  p_actor_user_id uuid,
+  p_feature text,
+  p_action text,
+  p_limit_key text DEFAULT NULL,
+  p_used integer DEFAULT NULL,
+  p_n integer DEFAULT 1
+) RETURNS jsonb
+LANGUAGE plpgsql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+DECLARE
+  v_role_id uuid;
+  v_has boolean;
+  v_plan_id text;
+  v_ent jsonb;
+  v_feature_flag jsonb;
+  v_cap numeric;
+BEGIN
+  -- ── actor integrity (016): a JWT caller can only act as themselves ───────
+  IF auth.uid() IS NOT NULL AND auth.uid() IS DISTINCT FROM p_actor_user_id THEN
+    RETURN jsonb_build_object('allowed', false, 'reason', 'role',
+                              'upgradeUrl', '/settings/subscription');
+  END IF;
+
+  -- ── membership + role (app.*) ────────────────────────────────────────────
+  SELECT m.role_id INTO v_role_id
+    FROM app.memberships m
+   WHERE m.tenant_id = p_tenant_id AND m.user_id = p_actor_user_id AND m.active;
+  IF v_role_id IS NULL THEN
+    RETURN jsonb_build_object('allowed', false, 'reason', 'role',
+                              'upgradeUrl', '/settings/subscription');
+  END IF;
+
+  SELECT EXISTS (
+    SELECT 1 FROM app.role_permissions rp
+     WHERE rp.tenant_id = p_tenant_id
+       AND rp.role_id = v_role_id
+       AND rp.permission IN (p_feature || '.' || p_action,
+                             p_feature || '.manage',
+                             split_part(p_feature, '.', 1) || '.manage')
+  ) INTO v_has;
+  IF NOT v_has THEN
+    RETURN jsonb_build_object('allowed', false, 'reason', 'role',
+                              'upgradeUrl', '/settings/subscription');
+  END IF;
+
+  -- ── plan feature gate (015, unchanged; nobody bypasses the plan) ─────────
+  SELECT t.plan INTO v_plan_id FROM public.tenants t WHERE t.id = p_tenant_id;
+  SELECT p.entitlements INTO v_ent FROM public.plans p WHERE p.id = v_plan_id;
+
+  IF v_ent IS NOT NULL THEN
+    v_feature_flag := v_ent->'features'->p_feature;
+    IF v_feature_flag IS NOT NULL AND v_feature_flag = to_jsonb(false) THEN
+      RETURN jsonb_build_object('allowed', false, 'reason', 'plan',
+                                'upgradeUrl', '/settings/subscription');
+    END IF;
+
+    IF p_limit_key IS NOT NULL AND p_used IS NOT NULL THEN
+      v_cap := (v_ent->'limits'->>p_limit_key)::numeric;
+      IF v_cap IS NOT NULL AND v_cap <> -1 AND (p_used + COALESCE(p_n, 1)) > v_cap THEN
+        RETURN jsonb_build_object('allowed', false, 'reason', 'limit',
+                                  'limit', jsonb_build_object('key', p_limit_key,
+                                                              'max', v_cap,
+                                                              'used', p_used),
+                                  'upgradeUrl', '/settings/subscription');
+      END IF;
+    END IF;
+  END IF;
+
+  RETURN NULL;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.agent_guard(uuid, uuid, text, text, text, integer, integer) FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.agent_guard(uuid, uuid, text, text, text, integer, integer)
+  TO authenticated, service_role;
+
+-- ── the allowlist on schema app: no trigger function is executable by anon ─
+-- 040 set the default privileges for schema app, but trigger functions created
+-- with CREATE OR REPLACE keep whatever ACL they were born with. A trigger fires
+-- without an EXECUTE check, so nothing needs the grant; anon holds none.
+DO $$
+DECLARE r record;
+BEGIN
+  FOR r IN
+    SELECT p.oid::regprocedure AS fn
+      FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+     WHERE n.nspname = 'app' AND (has_function_privilege('anon', p.oid, 'EXECUTE') OR has_function_privilege('public', p.oid, 'EXECUTE'))
+  LOOP
+    EXECUTE format('REVOKE ALL ON FUNCTION %s FROM public, anon', r.fn);
+  END LOOP;
+END $$;

package/migrations/064b_supersede_unit_scope.sql

@@ -0,0 +1,205 @@
+-- ============================================================================
+-- 064_supersede_unit_scope.sql — one authorization model, not two (#242).
+--
+-- `main` shipped a unit model in 039–044: `public.locations` as the unit,
+-- `location_members` as the binding, `public.resource_grants` for sharing, and
+-- one RESTRICTIVE `unit_scope` policy per table on nine tables. It works, it has
+-- screens, and it is in production shape.
+--
+-- It also has no permission dimension. The predicate asks three things — is it
+-- my tenant, is it a unit I reach, is it mine or shared with me — and none of
+-- them is *may I write this*. That is why a franchisee can edit the network
+-- price table: there is nowhere to say otherwise. In the model this chain
+-- brings, `app.has_permission(perm, unit)` resolves through
+-- `effective_role_id(tenant, uid, unit)`, which returns the unit's override role
+-- or the base role — and a brand row (`unit_id IS NULL`) resolves to the BASE
+-- role, so the override cannot reach it. The franchisee edits their own branch
+-- and not the network's.
+--
+-- Backward compatibility is not a requirement here: a cut-over is acceptable.
+-- What is NOT acceptable is losing what main's model already recorded, so this
+-- file moves the data before it retires the mechanism.
+--
+-- WHAT IS KEPT FROM MAIN, ON PURPOSE
+--
+--   · `tenants.unit_scoping_enabled` — the per-account switch, honoured by
+--     `app.unit_scoping_on()` in 051. Rolling out one account at a time is
+--     better than the always-on this chain originally had.
+--   · `public.locations` / `location_members` keep working: 063 already turned
+--     them into write-through projections of `app.units` / `app.membership_units`,
+--     so the units UI (10 components, all of them through one `data.ts`) and the
+--     read models of 044/045/046 keep answering.
+--   · `teams` and `team_members` stay as data. This model has no team subject,
+--     so team grants are expanded into per-user grants below rather than lost.
+--
+-- WHAT CHANGES MEANING, AND IT IS DELIBERATE
+--
+--   `location_members.role` ADDS to the org role in main's model ("unions with
+--   the org role, never subtracts"). Here it becomes an OVERRIDE for that unit.
+--   That is the change that makes the franchisee case expressible at all — an
+--   additive role can never take `catalog.edit` away from a brand row. Recorded
+--   in DECISIONS.md.
+--
+-- Replay-safe: every step guarded on the object still being there.
+-- ============================================================================
+
+-- ── 1. the tree main grew, carried into app.units ───────────────────────
+-- 063 built app.units from locations before `parent_id` and `code` existed.
+-- Only ever ADOPTS a parent; never clears one. On a replay `locations` is already
+-- the projection of app.units, so a symmetric "make them equal" would read back a
+-- NULL the projection had not carried yet and flatten the real tree — which is
+-- what it did, and the fan-out then took B1 and B2 away from the F1 manager.
+UPDATE app.units u
+   SET parent_unit_id = coalesce(u.parent_unit_id, l.parent_id),
+       metadata = u.metadata || jsonb_strip_nulls(jsonb_build_object('code', l.code))
+  FROM public.locations l
+ WHERE l.id = u.id
+   AND ((l.parent_id IS NOT NULL AND u.parent_unit_id IS NULL)
+        OR (l.code IS NOT NULL AND u.metadata ->> 'code' IS DISTINCT FROM l.code));
+
+-- a region is a unit that has children; main's `kind` vocabulary was
+-- region|branch, this chain's is hq|branch, and the hq is the tenant's root
+UPDATE app.units u SET kind = 'branch'
+ WHERE u.kind NOT IN ('hq', 'branch');
+
+-- ── 2. the per-unit role, as an override ────────────────────────────────
+DO $$
+DECLARE v_n integer := 0;
+BEGIN
+  IF to_regclass('public.location_members') IS NULL THEN RETURN; END IF;
+  IF NOT EXISTS (SELECT 1 FROM information_schema.columns
+                  WHERE table_schema = 'public' AND table_name = 'location_members' AND column_name = 'role') THEN
+    RETURN;
+  END IF;
+
+  UPDATE app.membership_units mu
+     SET role_override_id = r.id
+    FROM public.location_members lm
+    JOIN app.roles r ON r.key = lm.role
+   WHERE mu.unit_id = lm.location_id
+     AND mu.user_id = lm.user_id
+     AND r.tenant_id = mu.tenant_id
+     AND lm.role IS NOT NULL
+     AND mu.role_override_id IS DISTINCT FROM r.id;
+  GET DIAGNOSTICS v_n = ROW_COUNT;
+  RAISE NOTICE '064: % per-unit role(s) carried as overrides', v_n;
+END $$;
+
+-- ── 3. the grants main recorded ─────────────────────────────────────────
+-- main: (resource_table, resource_id, grantee_type user|team|unit, access, reason)
+-- here: (resource_type, resource_id, relation, subject_type user|unit|role)
+--
+-- `reason` is what separates the two relations: 'catalog' means "this item is
+-- sold in these units" (a release), anything else means "somebody clicked
+-- share". A team grant has no subject here, so it is expanded to its members —
+-- losing the grouping is better than losing the access.
+DO $$
+DECLARE v_n integer := 0;
+BEGIN
+  IF to_regclass('public.resource_grants') IS NULL THEN RETURN; END IF;
+
+  INSERT INTO app.resource_grants (tenant_id, resource_type, resource_id, relation, subject_type, subject_id, created_by)
+  SELECT g.tenant_id,
+         -- main keys grants by TABLE; this model keys them by resource type
+         coalesce(sr.resource_type, 'catalog.product'),
+         g.resource_id,
+         CASE WHEN g.reason = 'catalog' THEN 'available_in' ELSE 'shared_with' END,
+         g.grantee_type,
+         g.grantee_id,
+         g.granted_by
+    FROM public.resource_grants g
+    LEFT JOIN LATERAL (
+      SELECT r.resource_type FROM app.scaffold_registry r
+       WHERE r.table_schema = 'public' AND r.table_name = g.resource_table
+       LIMIT 1) sr ON true
+   WHERE g.grantee_type IN ('user', 'unit')
+  ON CONFLICT DO NOTHING;
+  GET DIAGNOSTICS v_n = ROW_COUNT;
+
+  -- team → its members, one grant each
+  IF to_regclass('public.team_members') IS NOT NULL THEN
+    INSERT INTO app.resource_grants (tenant_id, resource_type, resource_id, relation, subject_type, subject_id, created_by)
+    SELECT g.tenant_id, coalesce(sr.resource_type, 'catalog.product'), g.resource_id,
+           CASE WHEN g.reason = 'catalog' THEN 'available_in' ELSE 'shared_with' END,
+           'user', tm.user_id, g.granted_by
+      FROM public.resource_grants g
+      JOIN public.team_members tm ON tm.team_id = g.grantee_id
+      LEFT JOIN LATERAL (
+        SELECT r.resource_type FROM app.scaffold_registry r
+         WHERE r.table_schema = 'public' AND r.table_name = g.resource_table
+         LIMIT 1) sr ON true
+     WHERE g.grantee_type = 'team'
+    ON CONFLICT DO NOTHING;
+  END IF;
+  RAISE NOTICE '064: % grant(s) carried', v_n;
+END $$;
+
+-- ── 4. retire the mechanism, now that the data moved ────────────────────
+-- The nine RESTRICTIVE policies must go BEFORE the scaffold sweep (065) starts
+-- putting this chain's template on the same tables: two restrictive predicates
+-- AND together, and main's asks a question this model answers differently, so
+-- leaving both would hide rows for reasons nobody could read off either one.
+DO $$
+DECLARE r record; v_n integer := 0;
+BEGIN
+  FOR r IN SELECT schemaname, tablename FROM pg_policies
+            WHERE schemaname = 'public' AND policyname = 'unit_scope' LOOP
+    EXECUTE format('DROP POLICY IF EXISTS unit_scope ON %I.%I', r.schemaname, r.tablename);
+    v_n := v_n + 1;
+  END LOOP;
+  RAISE NOTICE '064: % unit_scope policy(ies) retired — the scaffold template takes over in 065', v_n;
+END $$;
+
+COMMENT ON TABLE public.resource_grants IS
+  'SUPERSEDED by app.resource_grants (#242). Rows were carried across in 064; this table is left in place so main''s screens keep reading while they move. It no longer governs any policy.';
+
+-- The switch survives and now drives this chain's predicate too.
+COMMENT ON COLUMN public.tenants.unit_scoping_enabled IS
+  'Per-account switch for unit scoping, from main 039 and kept (#242). Read by app.unit_scoping_on(): with it off, every unit of the account is reachable and the plans are the ones from before units existed.';
+
+-- ── 5. main's write-stamp keeps working, against this model's constraints ──
+-- `041_scoped_columns` put a BEFORE INSERT trigger on nine tables that fills
+-- `unit_id` from the request header and `owner_id` from the actor. That is a good
+-- feature and this chain does not have it: it is what makes "the appointment is
+-- born in Ipanema without reception typing anything" true.
+--
+-- It does collide with one thing. The scaffold's `owner_id` carries a composite
+-- FK to `app.memberships(tenant_id, user_id)` — an owner who is not a member of
+-- the row's tenant is unrepresentable, which is the point. main's stamp writes
+-- `auth.uid()` unconditionally, so a caller acting on a tenant they do not belong
+-- to used to get a NULL owner and now gets a 23503.
+--
+-- The trigger is re-emitted with the membership test the FK expects. Same
+-- behaviour for every legitimate write; the illegitimate one goes back to being
+-- refused by the policy (42501) instead of by a constraint (23503), which is the
+-- error the caller can act on.
+DO $$
+DECLARE r record; v_n integer := 0;
+BEGIN
+  FOR r IN SELECT p.proname, replace(p.proname, 'stamp_scope_', '') AS tbl
+             FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+            WHERE n.nspname = 'public' AND p.proname LIKE 'stamp\_scope\_%' LOOP
+    CONTINUE WHEN to_regclass('public.' || r.tbl) IS NULL;
+    EXECUTE format($f$
+      CREATE OR REPLACE FUNCTION public.%I() RETURNS trigger
+      LANGUAGE plpgsql SECURITY DEFINER SET search_path TO 'public', 'pg_temp'
+      AS $body$
+      BEGIN
+        IF NEW.unit_id IS NULL THEN
+          NEW.unit_id := public.requested_unit();
+        END IF;
+        -- only an actual member can own a row here: the composite FK says so
+        IF NEW.owner_id IS NULL AND EXISTS (
+             SELECT 1 FROM app.memberships m
+              WHERE m.tenant_id = NEW.tenant_id AND m.user_id = auth.uid() AND m.active) THEN
+          NEW.owner_id := auth.uid();
+        END IF;
+        RETURN NEW;
+      EXCEPTION WHEN OTHERS THEN
+        RETURN NEW;
+      END $body$;
+    $f$, r.proname);
+    v_n := v_n + 1;
+  END LOOP;
+  RAISE NOTICE '064b: % write-stamp trigger(s) re-emitted with the membership test', v_n;
+END $$;

package/migrations/065_scaffold_sweep.sql

@@ -0,0 +1,139 @@
+-- ============================================================================
+-- 065_scaffold_sweep.sql — the remaining core-A public tables under the ONE
+-- RLS template (043 app.scaffold_table), in SHADOW mode (PRD 01 R6 / #135).
+--
+-- Shadow: the table's existing canonical policies stay; the four
+-- <t>_authz_* template policies are ADDED (permissive policies OR together, so
+-- nothing is denied that was allowed) and app.shadow_report() (056) counts,
+-- per member, what the old predicate shows vs what the new one would — the
+-- flip to 'enforce' happens per table, on evidence, with
+-- app.scaffold_set_mode(table, 'enforce').
+--
+-- Which tables (owned by no other Phase-0 slice):
+--   public.appointments       agenda.appointment   plugin agenda     owner scoping on
+--   public.appointment_items  agenda.appointment_item plugin agenda  (gets tenant_id, backfilled from the appointment)
+--   public.schedules          agenda.schedule      plugin agenda
+--   public.transactions       financial.transaction plugin financial (legacy generic archetype)
+-- Not swept, on purpose:
+--   public.addresses — its owner_id is a POLYMORPHIC domain column (person /
+--     location / tenant, 017) and the template reads owner_id as "member who
+--     owns the row"; scaffolding would add an FK to app.memberships that the
+--     data violates and change the meaning of the column. Phase 1: rename to
+--     holder_id, then scaffold under people. Documented in 01a.
+--   people / categories / products / services / orders / order_items — the
+--     people, catalog and O2C slices own them (enforce).
+--
+-- Backfills are guarded: unit_id ← location_id only where that id is an
+-- app.units id of the same tenant (the tenancy slice decides whether locations
+-- keep their ids as units; nothing here assumes it).
+-- ============================================================================
+
+-- A pre-existing unit_id (plugin tables carried one pointing at public.locations)
+-- that is not an app.units id of the same tenant cannot take the composite FK
+-- the scaffold adds. Rather than fail the migration or lose the value, the
+-- retrofit files park it here and null the column; the tenancy slice / Phase 1
+-- re-link once locations → units ids are settled.
+CREATE TABLE IF NOT EXISTS app.legacy_unit_quarantine (
+  table_name     text NOT NULL,
+  row_id         uuid NOT NULL,
+  tenant_id      uuid,
+  legacy_unit_id uuid NOT NULL,
+  quarantined_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (table_name, row_id)
+);
+ALTER TABLE app.legacy_unit_quarantine ENABLE ROW LEVEL SECURITY;
+GRANT ALL ON app.legacy_unit_quarantine TO service_role;
+COMMENT ON TABLE app.legacy_unit_quarantine IS
+  'unit_id values that predate app.units and did not resolve to a unit of the row''s tenant when the table was scaffolded (#135). Re-link in Phase 1, then delete the row here.';
+
+-- Park + null a legacy unit_id that does not resolve; returns rows quarantined.
+CREATE OR REPLACE FUNCTION app.quarantine_legacy_unit_ids(p_table regclass)
+RETURNS integer LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE v_schema text; v_name text; v_n integer := 0;
+BEGIN
+  SELECT n.nspname, c.relname INTO v_schema, v_name FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE c.oid = p_table;
+  IF NOT EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = v_schema AND table_name = v_name AND column_name = 'unit_id')
+     OR NOT EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = v_schema AND table_name = v_name AND column_name = 'tenant_id')
+     OR to_regclass('app.units') IS NULL THEN
+    RETURN 0;
+  END IF;
+  EXECUTE format(
+    'WITH bad AS (SELECT t.id, t.tenant_id, t.unit_id FROM %1$I.%2$I t WHERE t.unit_id IS NOT NULL
+        AND NOT EXISTS (SELECT 1 FROM app.units u WHERE u.tenant_id = t.tenant_id AND u.id = t.unit_id)),
+     park AS (INSERT INTO app.legacy_unit_quarantine (table_name, row_id, tenant_id, legacy_unit_id)
+              SELECT %3$L, id, tenant_id, unit_id FROM bad ON CONFLICT DO NOTHING RETURNING 1),
+     fix AS (UPDATE %1$I.%2$I t SET unit_id = NULL WHERE t.id IN (SELECT id FROM bad) RETURNING 1)
+     SELECT count(*) FROM fix', v_schema, v_name, v_name) INTO v_n;
+  RETURN v_n;
+END $$;
+REVOKE ALL ON FUNCTION app.quarantine_legacy_unit_ids(regclass) FROM public, anon, authenticated;
+
+DO $$
+DECLARE r record;
+BEGIN
+  -- ── appointments
+  IF to_regclass('public.appointments') IS NOT NULL THEN
+    PERFORM app.scaffold_table('public.appointments', 'agenda.appointment', 'agenda', true, 'shadow');
+    IF EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = 'public' AND table_name = 'appointments' AND column_name = 'location_id')
+       AND to_regclass('app.units') IS NOT NULL THEN
+      UPDATE public.appointments a SET unit_id = a.location_id
+       WHERE a.unit_id IS NULL AND a.location_id IS NOT NULL
+         AND EXISTS (SELECT 1 FROM app.units u WHERE u.tenant_id = a.tenant_id AND u.id = a.location_id);
+    END IF;
+  END IF;
+
+  -- ── appointment_items (child: tenant_id derived from the appointment)
+  IF to_regclass('public.appointment_items') IS NOT NULL THEN
+    PERFORM app.scaffold_table('public.appointment_items', 'agenda.appointment_item', 'agenda', false, 'shadow');
+    UPDATE public.appointment_items ai SET tenant_id = a.tenant_id
+      FROM public.appointments a
+     WHERE a.id = ai.booking_id AND ai.tenant_id IS NULL;
+    UPDATE public.appointment_items ai SET unit_id = a.unit_id
+      FROM public.appointments a
+     WHERE a.id = ai.booking_id AND ai.unit_id IS NULL AND a.unit_id IS NOT NULL;
+    -- tighten once every row has a tenant (fresh chains: immediately)
+    IF NOT EXISTS (SELECT 1 FROM public.appointment_items WHERE tenant_id IS NULL) THEN
+      EXECUTE 'ALTER TABLE public.appointment_items ALTER COLUMN tenant_id SET NOT NULL';
+    END IF;
+    -- keep the child in step with its parent's tenant/unit on insert
+    CREATE OR REPLACE FUNCTION public.trg_appointment_items_inherit_scope()
+    RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $fn$
+    BEGIN
+      IF NEW.tenant_id IS NULL OR NEW.unit_id IS NULL THEN
+        SELECT coalesce(NEW.tenant_id, a.tenant_id), coalesce(NEW.unit_id, a.unit_id) INTO NEW.tenant_id, NEW.unit_id
+          FROM public.appointments a WHERE a.id = NEW.booking_id;
+      END IF;
+      RETURN NEW;
+    END $fn$;
+    EXECUTE 'DROP TRIGGER IF EXISTS appointment_items_inherit_scope ON public.appointment_items';
+    EXECUTE 'CREATE TRIGGER appointment_items_inherit_scope BEFORE INSERT ON public.appointment_items FOR EACH ROW EXECUTE FUNCTION public.trg_appointment_items_inherit_scope()';
+  END IF;
+
+  -- ── schedules
+  IF to_regclass('public.schedules') IS NOT NULL THEN
+    PERFORM app.scaffold_table('public.schedules', 'agenda.schedule', 'agenda', false, 'shadow');
+    IF EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = 'public' AND table_name = 'schedules' AND column_name = 'location_id')
+       AND to_regclass('app.units') IS NOT NULL THEN
+      UPDATE public.schedules s SET unit_id = s.location_id
+       WHERE s.unit_id IS NULL AND s.location_id IS NOT NULL
+         AND EXISTS (SELECT 1 FROM app.units u WHERE u.tenant_id = s.tenant_id AND u.id = s.location_id);
+    END IF;
+  END IF;
+
+  -- ── transactions (legacy generic archetype; O2C's ledger supersedes it)
+  IF to_regclass('public.transactions') IS NOT NULL THEN
+    PERFORM app.scaffold_table('public.transactions', 'financial.transaction', 'financial', false, 'shadow');
+  END IF;
+END $$;
+
+-- The API roles keep what they had; the template narrows through RLS.
+DO $$
+DECLARE t text;
+BEGIN
+  FOREACH t IN ARRAY ARRAY['appointments', 'appointment_items', 'schedules', 'transactions'] LOOP
+    IF to_regclass('public.' || t) IS NOT NULL THEN
+      EXECUTE format('GRANT SELECT, INSERT, UPDATE, DELETE ON public.%I TO authenticated', t);
+      EXECUTE format('GRANT ALL ON public.%I TO service_role', t);
+    END IF;
+  END LOOP;
+END $$;

package/migrations/066_shadow_report.sql

@@ -0,0 +1,122 @@
+-- ============================================================================
+-- 066_shadow_report.sql — the shadow-mode report and the flip to enforce (#135).
+--
+-- app.shadow_report([tenant]) — for every table in app.scaffold_registry with
+-- mode = 'shadow' and every active member of the tenant(s), how many rows the
+-- OLD SELECT policies show (the permissive non-template policies still on the
+-- table, OR-ed, exactly as Postgres combines them) vs how many the NEW template
+-- policy (<t>_authz_select) would show, and the difference both ways:
+--   unexpected_denials  rows the old predicate shows and the new one hides
+--                       (what the flip would take away from that member)
+--   newly_visible       rows the new predicate shows and the old one hides
+-- Both predicates are the policies' own text (pg_policies.qual), evaluated as
+-- WHERE clauses with the member's JWT claims set transaction-locally
+-- (request.jwt.claims / request.jwt.claim.sub, the same knobs PostgREST turns)
+-- — no role switch: the function is SECURITY DEFINER (bypasses RLS) and the
+-- helpers read auth.uid()/claims from those settings. The caller's own claims
+-- are saved and restored.
+--
+-- Semantics on the synthetic fixture: only owners are mirrored in
+-- public.tenant_members until the tenancy slice retires it, so the OLD
+-- predicate (user_tenant_ids()) shows rows only to owners; a member without the
+-- plugin's `.read` (reception on transactions) shows denials only once she is a
+-- tenant_members row — the suite creates that condition and asserts the count.
+--
+-- app.scaffold_set_mode(table, 'enforce'|'shadow') — re-applies the registered
+-- scaffold in the new mode (enforce drops the pre-existing policies and records
+-- them in the registry; shadow re-adds nothing that was dropped).
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION app.shadow_report(p_tenant uuid DEFAULT NULL)
+RETURNS TABLE (
+  tenant_id uuid,
+  table_name text,
+  member_user_id uuid,
+  old_visible integer,
+  new_visible integer,
+  unexpected_denials integer,
+  newly_visible integer
+)
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_prev_claims text := current_setting('request.jwt.claims', true);
+  v_prev_sub    text := current_setting('request.jwt.claim.sub', true);
+  v_prev_role   text := current_setting('request.jwt.claim.role', true);
+  t   record;
+  m   record;
+  v_old text;
+  v_new text;
+  v_o integer; v_n integer; v_d integer; v_w integer;
+BEGIN
+  FOR t IN
+    SELECT r.table_schema, r.table_name FROM app.scaffold_registry r WHERE r.mode = 'shadow' ORDER BY 1, 2
+  LOOP
+    IF to_regclass(format('%I.%I', t.table_schema, t.table_name)) IS NULL THEN CONTINUE; END IF;
+    IF NOT EXISTS (SELECT 1 FROM information_schema.columns c WHERE c.table_schema = t.table_schema AND c.table_name = t.table_name AND c.column_name = 'tenant_id') THEN CONTINUE; END IF;
+
+    SELECT coalesce(string_agg('(' || p.qual || ')', ' OR '), 'false') INTO v_old
+      FROM pg_policies p
+     WHERE p.schemaname = t.table_schema AND p.tablename = t.table_name
+       AND p.cmd IN ('SELECT', 'ALL') AND p.permissive = 'PERMISSIVE' AND p.qual IS NOT NULL
+       AND p.policyname <> ALL (ARRAY[t.table_name || '_authz_select', t.table_name || '_authz_insert', t.table_name || '_authz_update', t.table_name || '_authz_delete']);
+    SELECT p.qual INTO v_new FROM pg_policies p
+     WHERE p.schemaname = t.table_schema AND p.tablename = t.table_name AND p.policyname = t.table_name || '_authz_select';
+    IF v_new IS NULL THEN CONTINUE; END IF;
+
+    FOR m IN
+      SELECT ms.tenant_id, ms.user_id FROM app.memberships ms
+       WHERE ms.active AND (p_tenant IS NULL OR ms.tenant_id = p_tenant)
+       ORDER BY 1, 2
+    LOOP
+      PERFORM set_config('request.jwt.claims', jsonb_build_object('sub', m.user_id::text, 'role', 'authenticated', 'aud', 'authenticated', 'tenant_id', m.tenant_id::text)::text, true);
+      PERFORM set_config('request.jwt.claim.sub', m.user_id::text, true);
+      PERFORM set_config('request.jwt.claim.role', 'authenticated', true);
+      EXECUTE format(
+        'SELECT count(*) FILTER (WHERE coalesce((%1$s), false)),
+                count(*) FILTER (WHERE coalesce((%2$s), false)),
+                count(*) FILTER (WHERE coalesce((%1$s), false) AND NOT coalesce((%2$s), false)),
+                count(*) FILTER (WHERE coalesce((%2$s), false) AND NOT coalesce((%1$s), false))
+           FROM %3$I.%4$I WHERE tenant_id = $1',
+        v_old, v_new, t.table_schema, t.table_name)
+        INTO v_o, v_n, v_d, v_w USING m.tenant_id;
+      tenant_id := m.tenant_id; table_name := t.table_name; member_user_id := m.user_id;
+      old_visible := v_o; new_visible := v_n; unexpected_denials := v_d; newly_visible := v_w;
+      RETURN NEXT;
+    END LOOP;
+  END LOOP;
+  PERFORM set_config('request.jwt.claims', coalesce(v_prev_claims, ''), true);
+  PERFORM set_config('request.jwt.claim.sub', coalesce(v_prev_sub, ''), true);
+  PERFORM set_config('request.jwt.claim.role', coalesce(v_prev_role, ''), true);
+END $$;
+REVOKE ALL ON FUNCTION app.shadow_report(uuid) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION app.shadow_report(uuid) TO service_role;
+
+-- One row per shadow table: the roll-up an operator reads before flipping.
+CREATE OR REPLACE FUNCTION app.shadow_report_summary(p_tenant uuid DEFAULT NULL)
+RETURNS TABLE (table_name text, members integer, members_denied integer, unexpected_denials bigint, newly_visible bigint)
+LANGUAGE sql SECURITY DEFINER SET search_path = ''
+AS $$
+  SELECT r.table_name, count(*)::int, count(*) FILTER (WHERE r.unexpected_denials > 0)::int, sum(r.unexpected_denials), sum(r.newly_visible)
+    FROM app.shadow_report(p_tenant) r
+   GROUP BY r.table_name ORDER BY 1;
+$$;
+REVOKE ALL ON FUNCTION app.shadow_report_summary(uuid) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION app.shadow_report_summary(uuid) TO service_role;
+
+-- The flip: same table, same resource/plugin/owner scoping, new mode.
+CREATE OR REPLACE FUNCTION app.scaffold_set_mode(p_table regclass, p_mode text)
+RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE r app.scaffold_registry%ROWTYPE; v_schema text; v_name text;
+BEGIN
+  SELECT n.nspname, c.relname INTO v_schema, v_name FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE c.oid = p_table;
+  SELECT * INTO r FROM app.scaffold_registry WHERE table_schema = v_schema AND table_name = v_name;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'scaffold_set_mode: %.% is not registered — call app.scaffold_table first', v_schema, v_name;
+  END IF;
+  PERFORM app.scaffold_table(p_table, r.resource_type, r.plugin, r.owner_scoping, p_mode);
+END $$;
+REVOKE ALL ON FUNCTION app.scaffold_set_mode(regclass, text) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION app.scaffold_set_mode(regclass, text) TO service_role;