@fayz-ai/db 0.12.0 → 0.13.0

package/migrations/072_role_rpcs.sql

@@ -0,0 +1,126 @@
+-- ============================================================================
+-- 072_role_rpcs.sql — tenant roles as an operation, not a table write (#136).
+--
+-- The vertical templates (043) instantiate the SYSTEM roles of a tenant. A
+-- network's "kit por cargo" (V1: permission_rules of the franchisor) and a
+-- salon's "duplicate the financial role" are TENANT roles: app.roles rows with
+-- is_system = false, created from an existing role's permission set. Two RPCs
+-- make that a single, audited call under the platform key roles.manage:
+--
+--   public.role_create_from_template(role_key, name, template_role[, template[, description]])
+--       clone the permissions of a role of MY tenant (system or custom) — or,
+--       with p_template, of a vertical template row (app.role_templates) —
+--       into a new tenant role. Returns the new role id.
+--   public.role_set_permissions(role_id, keys[])
+--       replace a role's permission set. The system owner role is immutable
+--       (it always holds the whole catalog); unknown keys are rejected as a
+--       whole, nothing partial.
+--
+-- Actor = auth.uid(); tenant = app.current_tenant_id() (never a parameter);
+-- denial is ERRCODE 42501. SECURITY DEFINER with search_path = '' so the RLS on
+-- app.* does not double-gate the write once the permission is checked here.
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION public.role_create_from_template(
+  p_role_key text,
+  p_name text,
+  p_template_role text,
+  p_template text DEFAULT NULL,
+  p_description text DEFAULT NULL
+) RETURNS uuid
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_tenant uuid := app.current_tenant_id();
+  v_source uuid;
+  v_id     uuid;
+  v_n      integer;
+BEGIN
+  IF auth.uid() IS NULL OR v_tenant IS NULL THEN
+    RAISE EXCEPTION 'role_create_from_template: no active tenant for this session' USING ERRCODE = '42501';
+  END IF;
+  IF NOT app.has_permission('roles.manage') THEN
+    RAISE EXCEPTION 'role_create_from_template: roles.manage is required' USING ERRCODE = '42501';
+  END IF;
+  IF p_role_key IS NULL OR p_role_key !~ '^[a-z][a-z0-9_-]*$' THEN
+    RAISE EXCEPTION 'role_create_from_template: role key must match ^[a-z][a-z0-9_-]*$ (got %)', coalesce(p_role_key, '<null>') USING ERRCODE = '22023';
+  END IF;
+  IF p_name IS NULL OR btrim(p_name) = '' THEN
+    RAISE EXCEPTION 'role_create_from_template: a name is required' USING ERRCODE = '22023';
+  END IF;
+  IF EXISTS (SELECT 1 FROM app.roles r WHERE r.tenant_id = v_tenant AND r.key = p_role_key) THEN
+    RAISE EXCEPTION 'role_create_from_template: role % already exists in this tenant', p_role_key USING ERRCODE = '23505';
+  END IF;
+
+  IF p_template IS NULL THEN
+    SELECT r.id INTO v_source FROM app.roles r WHERE r.tenant_id = v_tenant AND r.key = p_template_role;
+    IF v_source IS NULL THEN
+      RAISE EXCEPTION 'role_create_from_template: no role % in this tenant to clone from', p_template_role USING ERRCODE = 'P0002';
+    END IF;
+  ELSIF NOT EXISTS (SELECT 1 FROM app.role_templates t WHERE t.template = p_template AND t.role_key = p_template_role) THEN
+    RAISE EXCEPTION 'role_create_from_template: template %/% does not exist', p_template, p_template_role USING ERRCODE = 'P0002';
+  END IF;
+
+  INSERT INTO app.roles (tenant_id, key, name, description, is_system)
+  VALUES (v_tenant, p_role_key, btrim(p_name), p_description, false)
+  RETURNING id INTO v_id;
+
+  IF p_template IS NULL THEN
+    INSERT INTO app.role_permissions (tenant_id, role_id, permission)
+    SELECT v_tenant, v_id, rp.permission FROM app.role_permissions rp
+     WHERE rp.tenant_id = v_tenant AND rp.role_id = v_source
+    ON CONFLICT DO NOTHING;
+  ELSE
+    INSERT INTO app.role_permissions (tenant_id, role_id, permission)
+    SELECT v_tenant, v_id, t.permission FROM app.role_templates t
+     WHERE t.template = p_template AND t.role_key = p_template_role
+    ON CONFLICT DO NOTHING;
+  END IF;
+  GET DIAGNOSTICS v_n = ROW_COUNT;
+
+  RETURN v_id;
+END $$;
+REVOKE ALL ON FUNCTION public.role_create_from_template(text, text, text, text, text) FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.role_create_from_template(text, text, text, text, text) TO authenticated, service_role;
+
+CREATE OR REPLACE FUNCTION public.role_set_permissions(p_role_id uuid, p_keys text[])
+RETURNS integer
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_tenant  uuid := app.current_tenant_id();
+  v_role    app.roles%ROWTYPE;
+  v_unknown text;
+  v_keys    text[] := coalesce(p_keys, '{}');
+  v_n       integer;
+BEGIN
+  IF auth.uid() IS NULL OR v_tenant IS NULL THEN
+    RAISE EXCEPTION 'role_set_permissions: no active tenant for this session' USING ERRCODE = '42501';
+  END IF;
+  IF NOT app.has_permission('roles.manage') THEN
+    RAISE EXCEPTION 'role_set_permissions: roles.manage is required' USING ERRCODE = '42501';
+  END IF;
+  SELECT * INTO v_role FROM app.roles r WHERE r.tenant_id = v_tenant AND r.id = p_role_id;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'role_set_permissions: role not found in the active tenant' USING ERRCODE = 'P0002';
+  END IF;
+  IF v_role.is_system AND v_role.key = 'owner' THEN
+    RAISE EXCEPTION 'role_set_permissions: the owner role is immutable (it always holds the whole catalog)' USING ERRCODE = '42501';
+  END IF;
+  SELECT string_agg(k, ', ' ORDER BY k) INTO v_unknown
+    FROM unnest(v_keys) k WHERE NOT EXISTS (SELECT 1 FROM app.permissions p WHERE p.key = k);
+  IF v_unknown IS NOT NULL THEN
+    RAISE EXCEPTION 'role_set_permissions: unknown permission key(s): %', v_unknown USING ERRCODE = '23503';
+  END IF;
+
+  DELETE FROM app.role_permissions rp
+   WHERE rp.tenant_id = v_tenant AND rp.role_id = p_role_id AND rp.permission <> ALL (v_keys);
+  INSERT INTO app.role_permissions (tenant_id, role_id, permission)
+  SELECT v_tenant, p_role_id, k FROM unnest(v_keys) k
+  ON CONFLICT DO NOTHING;
+
+  SELECT count(*) INTO v_n FROM app.role_permissions rp WHERE rp.tenant_id = v_tenant AND rp.role_id = p_role_id;
+  RETURN v_n;
+END $$;
+REVOKE ALL ON FUNCTION public.role_set_permissions(uuid, text[]) FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.role_set_permissions(uuid, text[]) TO authenticated, service_role;

package/migrations/073_legacy_rbac_retire.sql

@@ -0,0 +1,471 @@
+-- ============================================================================
+-- 073_legacy_rbac_retire.sql — retire the legacy RBAC tables of the SDK
+-- (public.permissions / role_permissions / tenant_role_overrides / tenant_roles)
+-- in favour of app.permissions / app.roles / app.role_permissions (#136).
+--
+-- What happens here, in order:
+--   1. DATA MIGRATION. Every tenant_roles row becomes an app.roles row
+--      (is_system = false, same id). For every (tenant, role key) that exists in
+--      app.roles, the legacy effective set — role_permissions[key] ∪ granted
+--      overrides − revoked overrides — becomes app.role_permissions rows, keys
+--      translated to '{feature}.{action}' (legacy 'update' → 'edit', 'write' →
+--      'create'). Anything that cannot land (unknown key, role key without an
+--      app.roles row) is written to app.legacy_permission_quarantine — nothing
+--      is dropped silently.
+--   2. COMPAT FACADE. The four tables stay PHYSICALLY (001/021 replay
+--      `CREATE TABLE IF NOT EXISTS` + `ALTER TABLE … ENABLE ROW LEVEL SECURITY`
+--      + `CREATE POLICY` on those names — none of which works on a view, so a
+--      DROP + VIEW would break the force replay of the chain; verified) but
+--      become READ-ONLY MIRRORS of app.*, refilled here and kept current by
+--      triggers on app.permissions / app.roles / app.role_permissions:
+--        permissions(id = key, category = plugin)
+--        role_permissions            — empty (V2 has no global per-key defaults)
+--        tenant_roles                — app.roles WHERE NOT is_system (custom roles)
+--        tenant_role_overrides       — app.role_permissions ⋈ app.roles as
+--                                      (role = key, permission_id, granted = true),
+--                                      owner excluded (the admin grants it everything)
+--      This keeps @fayz-ai/admin's permission matrix (listProfiles) reading the
+--      truth with the shape it expects. Its WRITES (createProfile/updateProfile/
+--      deleteProfile on tenant_roles + tenant_role_overrides) are redirected by
+--      BEFORE ROW triggers into app.roles / app.role_permissions — as the
+--      caller, so app.* RLS (roles.manage) gates them — and the row itself is
+--      never written (RETURN NULL); the mirror re-projects it. Direct writes to
+--      permissions / role_permissions are revoked from the API roles.
+--   3. POLICIES of the four tables re-authored on app.* (members read their
+--      tenant's rows; roles.manage to write) under the SAME names 001/021 use,
+--      so a replay converges on these; the generic tenant_isolation_* that
+--      002's replay adds to tenant_roles is dropped again here.
+--   4. Deprecation: COMMENT ON TABLE. Phase 1 drops the four tables and the
+--      mirror/redirect triggers once @fayz-ai/admin reads public.v_authz_* —
+--      the mirror functions already no-op when a table is gone.
+--
+-- Idempotent + replay-safe: the migration reads whatever is in the legacy
+-- tables (on replay: the mirror, which is already in app.*), every insert is
+-- ON CONFLICT DO NOTHING, and the mirror is rebuilt from app.* at the end.
+-- ============================================================================
+
+-- ── 0. quarantine ─────────────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS app.legacy_permission_quarantine (
+  id             bigserial PRIMARY KEY,
+  source_table   text NOT NULL,
+  tenant_id      uuid,
+  role_key       text,
+  permission_id  text,
+  granted        boolean,
+  reason         text NOT NULL CHECK (reason IN ('role-missing', 'permission-unknown', 'tenant-missing')),
+  payload        jsonb NOT NULL DEFAULT '{}'::jsonb,
+  quarantined_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX IF NOT EXISTS legacy_permission_quarantine_uniq
+  ON app.legacy_permission_quarantine (source_table, coalesce(tenant_id, '00000000-0000-0000-0000-000000000000'::uuid), coalesce(role_key, ''), coalesce(permission_id, ''), reason);
+ALTER TABLE app.legacy_permission_quarantine ENABLE ROW LEVEL SECURITY;
+GRANT SELECT ON app.legacy_permission_quarantine TO authenticated;
+GRANT ALL ON app.legacy_permission_quarantine TO service_role;
+GRANT USAGE, SELECT ON SEQUENCE app.legacy_permission_quarantine_id_seq TO service_role;
+DROP POLICY IF EXISTS legacy_permission_quarantine_select ON app.legacy_permission_quarantine;
+CREATE POLICY legacy_permission_quarantine_select ON app.legacy_permission_quarantine FOR SELECT TO authenticated
+  USING (tenant_id IS NOT NULL AND tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('roles.manage')));
+COMMENT ON TABLE app.legacy_permission_quarantine IS
+  'Legacy RBAC rows (SDK role_permissions/tenant_role_overrides) that could not be migrated into app.role_permissions (#136): unknown key or role key without an app.roles row. Review, then grant through role_set_permissions.';
+
+-- ── 1. key translation ────────────────────────────────────────────────────
+-- Legacy shapes: 'people.read' (feature.action) or ('people', actions[]) rows.
+-- Actions: legacy 'update' is V2 'edit', 'write' is 'create'. Returns NULL when
+-- no catalog key matches (the caller quarantines or raises).
+CREATE OR REPLACE FUNCTION app.legacy_permission_key(p_permission_id text, p_action text DEFAULT NULL)
+RETURNS text
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = ''
+AS $$
+  WITH cand AS (
+    SELECT k, prio FROM (
+      SELECT CASE
+               WHEN p_action IS NOT NULL THEN p_permission_id || '.' || CASE p_action WHEN 'update' THEN 'edit' WHEN 'write' THEN 'create' ELSE p_action END
+               ELSE regexp_replace(regexp_replace(p_permission_id, '\.update$', '.edit'), '\.write$', '.create')
+             END AS k, 1 AS prio
+      UNION ALL
+      SELECT CASE WHEN p_action IS NOT NULL THEN p_permission_id || '.' || p_action ELSE p_permission_id END, 2
+    ) c
+  )
+  SELECT k FROM cand WHERE EXISTS (SELECT 1 FROM app.permissions p WHERE p.key = cand.k) ORDER BY prio LIMIT 1;
+$$;
+REVOKE ALL ON FUNCTION app.legacy_permission_key(text, text) FROM public, anon;
+GRANT EXECUTE ON FUNCTION app.legacy_permission_key(text, text) TO authenticated, service_role;
+
+-- ── 2. the data migration (callable; runs once below, no-ops on replay) ───
+CREATE OR REPLACE FUNCTION app.migrate_legacy_rbac()
+RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_roles     integer := 0;
+  v_grants    integer := 0;
+  v_revoked   integer := 0;
+  v_quar      integer := 0;
+  r           record;
+  v_key       text;
+  v_role_id   uuid;
+  v_prev      text := coalesce(current_setting('app.legacy_mirror_sync', true), 'off');
+BEGIN
+  -- Reads of the legacy tables below must not be redirected: this function
+  -- writes app.* directly, so the mirror re-projects at the end (resync).
+  PERFORM set_config('app.legacy_mirror_sync', 'on', true);
+
+  -- 2a. custom roles → app.roles (same id, is_system false)
+  IF to_regclass('public.tenant_roles') IS NOT NULL THEN
+    WITH ins AS (
+      INSERT INTO app.roles (tenant_id, id, key, name, description, is_system, created_at)
+      SELECT tr.tenant_id, tr.id, tr.key, tr.name, tr.description, false, coalesce(tr.created_at, now())
+        FROM public.tenant_roles tr
+       WHERE EXISTS (SELECT 1 FROM public.tenants t WHERE t.id = tr.tenant_id)
+         AND tr.key ~ '^[a-z][a-z0-9_-]*$'
+         AND NOT EXISTS (SELECT 1 FROM app.roles ar WHERE ar.id = tr.id AND ar.tenant_id <> tr.tenant_id)
+      ON CONFLICT (tenant_id, key) DO NOTHING
+      RETURNING 1
+    ) SELECT count(*) INTO v_roles FROM ins;
+    -- keys the CHECK of app.roles refuses go to the quarantine
+    INSERT INTO app.legacy_permission_quarantine (source_table, tenant_id, role_key, reason, payload)
+    SELECT 'tenant_roles', tr.tenant_id, tr.key, 'role-missing', jsonb_build_object('name', tr.name, 'why', 'key does not match ^[a-z][a-z0-9_-]*$')
+      FROM public.tenant_roles tr WHERE tr.key !~ '^[a-z][a-z0-9_-]*$'
+    ON CONFLICT DO NOTHING;
+  END IF;
+
+  -- 2b. global defaults (role_permissions) fanned into every tenant that has the role key
+  IF to_regclass('public.role_permissions') IS NOT NULL THEN
+    FOR r IN
+      SELECT rp.role, rp.permission_id, rp.actions FROM public.role_permissions rp
+    LOOP
+      IF position('.' IN r.permission_id) > 0 THEN
+        v_key := app.legacy_permission_key(r.permission_id);
+        IF v_key IS NULL THEN
+          INSERT INTO app.legacy_permission_quarantine (source_table, tenant_id, role_key, permission_id, granted, reason)
+          VALUES ('role_permissions', NULL, r.role, r.permission_id, true, 'permission-unknown') ON CONFLICT DO NOTHING;
+          CONTINUE;
+        END IF;
+        WITH ins AS (
+          INSERT INTO app.role_permissions (tenant_id, role_id, permission)
+          SELECT ro.tenant_id, ro.id, v_key FROM app.roles ro WHERE ro.key = r.role
+          ON CONFLICT DO NOTHING RETURNING 1
+        ) SELECT v_grants + count(*) INTO v_grants FROM ins;
+      ELSE
+        -- legacy (feature, actions[]) shape
+        FOR v_key IN SELECT app.legacy_permission_key(r.permission_id, a) FROM unnest(coalesce(r.actions, '{}')) a LOOP
+          IF v_key IS NULL THEN
+            INSERT INTO app.legacy_permission_quarantine (source_table, tenant_id, role_key, permission_id, granted, reason, payload)
+            VALUES ('role_permissions', NULL, r.role, r.permission_id, true, 'permission-unknown', jsonb_build_object('actions', to_jsonb(r.actions))) ON CONFLICT DO NOTHING;
+            CONTINUE;
+          END IF;
+          WITH ins AS (
+            INSERT INTO app.role_permissions (tenant_id, role_id, permission)
+            SELECT ro.tenant_id, ro.id, v_key FROM app.roles ro WHERE ro.key = r.role
+            ON CONFLICT DO NOTHING RETURNING 1
+          ) SELECT v_grants + count(*) INTO v_grants FROM ins;
+        END LOOP;
+      END IF;
+      IF NOT EXISTS (SELECT 1 FROM app.roles ro WHERE ro.key = r.role) THEN
+        INSERT INTO app.legacy_permission_quarantine (source_table, tenant_id, role_key, permission_id, granted, reason)
+        VALUES ('role_permissions', NULL, r.role, r.permission_id, true, 'role-missing') ON CONFLICT DO NOTHING;
+      END IF;
+    END LOOP;
+  END IF;
+
+  -- 2c. per-tenant overrides: granted → insert, revoked → delete
+  IF to_regclass('public.tenant_role_overrides') IS NOT NULL THEN
+    FOR r IN
+      SELECT o.tenant_id, o.role, o.permission_id, o.granted FROM public.tenant_role_overrides o
+       ORDER BY o.granted DESC   -- grants first, then revocations win (V1 semantics: overrides beat defaults)
+    LOOP
+      IF NOT EXISTS (SELECT 1 FROM public.tenants t WHERE t.id = r.tenant_id) THEN
+        INSERT INTO app.legacy_permission_quarantine (source_table, tenant_id, role_key, permission_id, granted, reason)
+        VALUES ('tenant_role_overrides', r.tenant_id, r.role, r.permission_id, r.granted, 'tenant-missing') ON CONFLICT DO NOTHING;
+        CONTINUE;
+      END IF;
+      SELECT ro.id INTO v_role_id FROM app.roles ro WHERE ro.tenant_id = r.tenant_id AND ro.key = r.role;
+      IF v_role_id IS NULL THEN
+        INSERT INTO app.legacy_permission_quarantine (source_table, tenant_id, role_key, permission_id, granted, reason)
+        VALUES ('tenant_role_overrides', r.tenant_id, r.role, r.permission_id, r.granted, 'role-missing') ON CONFLICT DO NOTHING;
+        CONTINUE;
+      END IF;
+      v_key := app.legacy_permission_key(r.permission_id);
+      IF v_key IS NULL THEN
+        INSERT INTO app.legacy_permission_quarantine (source_table, tenant_id, role_key, permission_id, granted, reason)
+        VALUES ('tenant_role_overrides', r.tenant_id, r.role, r.permission_id, r.granted, 'permission-unknown') ON CONFLICT DO NOTHING;
+        CONTINUE;
+      END IF;
+      IF r.granted THEN
+        INSERT INTO app.role_permissions (tenant_id, role_id, permission) VALUES (r.tenant_id, v_role_id, v_key)
+        ON CONFLICT DO NOTHING;
+        IF FOUND THEN v_grants := v_grants + 1; END IF;
+      ELSE
+        DELETE FROM app.role_permissions rp WHERE rp.tenant_id = r.tenant_id AND rp.role_id = v_role_id AND rp.permission = v_key
+          AND NOT EXISTS (SELECT 1 FROM app.roles ro WHERE ro.id = v_role_id AND ro.is_system AND ro.key = 'owner');
+        IF FOUND THEN v_revoked := v_revoked + 1; END IF;
+      END IF;
+    END LOOP;
+  END IF;
+
+  SELECT count(*) INTO v_quar FROM app.legacy_permission_quarantine;
+  PERFORM set_config('app.legacy_mirror_sync', v_prev, true);
+  RETURN jsonb_build_object('roles_created', v_roles, 'grants_inserted', v_grants, 'grants_revoked', v_revoked, 'quarantined_total', v_quar);
+END $$;
+REVOKE ALL ON FUNCTION app.migrate_legacy_rbac() FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION app.migrate_legacy_rbac() TO service_role;
+
+-- ── 3. mirror maintenance (app.* → legacy tables), SECURITY DEFINER ───────
+-- Every mirror write runs with app.legacy_mirror_sync = on so the redirect
+-- triggers of §4 pass it through instead of bouncing it back into app.*.
+CREATE OR REPLACE FUNCTION app.legacy_rbac_resync()
+RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_prev text := coalesce(current_setting('app.legacy_mirror_sync', true), 'off');
+  v_perms integer := 0; v_roles integer := 0; v_over integer := 0;
+BEGIN
+  PERFORM set_config('app.legacy_mirror_sync', 'on', true);
+  IF to_regclass('public.permissions') IS NOT NULL THEN
+    DELETE FROM public.permissions p WHERE NOT EXISTS (SELECT 1 FROM app.permissions a WHERE a.key = p.id);
+    INSERT INTO public.permissions (id, category, description)
+    SELECT a.key, a.plugin, a.description FROM app.permissions a
+    ON CONFLICT (id) DO UPDATE SET category = EXCLUDED.category, description = EXCLUDED.description;
+    GET DIAGNOSTICS v_perms = ROW_COUNT;
+  END IF;
+  IF to_regclass('public.role_permissions') IS NOT NULL THEN
+    DELETE FROM public.role_permissions;
+  END IF;
+  IF to_regclass('public.tenant_roles') IS NOT NULL THEN
+    DELETE FROM public.tenant_roles tr WHERE NOT EXISTS (SELECT 1 FROM app.roles r WHERE r.id = tr.id AND r.tenant_id = tr.tenant_id AND NOT r.is_system);
+    -- a same-key row with another id would collide: drop it first, the upsert re-creates it with the app.roles id
+    DELETE FROM public.tenant_roles tr WHERE EXISTS (SELECT 1 FROM app.roles r WHERE r.tenant_id = tr.tenant_id AND r.key = tr.key AND r.id <> tr.id);
+    INSERT INTO public.tenant_roles (id, tenant_id, key, name, description, created_at)
+    SELECT r.id, r.tenant_id, r.key, r.name, r.description, r.created_at FROM app.roles r WHERE NOT r.is_system
+    ON CONFLICT (id) DO UPDATE SET key = EXCLUDED.key, name = EXCLUDED.name, description = EXCLUDED.description;
+    GET DIAGNOSTICS v_roles = ROW_COUNT;
+  END IF;
+  IF to_regclass('public.tenant_role_overrides') IS NOT NULL THEN
+    DELETE FROM public.tenant_role_overrides o
+     WHERE NOT o.granted
+        OR NOT EXISTS (SELECT 1 FROM app.role_permissions rp JOIN app.roles r ON r.tenant_id = rp.tenant_id AND r.id = rp.role_id
+                        WHERE rp.tenant_id = o.tenant_id AND r.key = o.role AND rp.permission = o.permission_id AND NOT (r.is_system AND r.key = 'owner'));
+    INSERT INTO public.tenant_role_overrides (tenant_id, role, permission_id, granted)
+    SELECT rp.tenant_id, r.key, rp.permission, true
+      FROM app.role_permissions rp JOIN app.roles r ON r.tenant_id = rp.tenant_id AND r.id = rp.role_id
+     WHERE NOT (r.is_system AND r.key = 'owner')
+    ON CONFLICT (tenant_id, role, permission_id) DO UPDATE SET granted = true;
+    GET DIAGNOSTICS v_over = ROW_COUNT;
+  END IF;
+  PERFORM set_config('app.legacy_mirror_sync', v_prev, true);
+  RETURN jsonb_build_object('permissions', v_perms, 'tenant_roles', v_roles, 'tenant_role_overrides', v_over);
+END $$;
+REVOKE ALL ON FUNCTION app.legacy_rbac_resync() FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION app.legacy_rbac_resync() TO service_role;
+
+CREATE OR REPLACE FUNCTION app.trg_mirror_permissions()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE v_prev text := coalesce(current_setting('app.legacy_mirror_sync', true), 'off');
+BEGIN
+  IF to_regclass('public.permissions') IS NULL THEN RETURN NULL; END IF;
+  PERFORM set_config('app.legacy_mirror_sync', 'on', true);
+  IF TG_OP = 'DELETE' THEN
+    DELETE FROM public.permissions WHERE id = OLD.key;
+  ELSE
+    IF TG_OP = 'UPDATE' AND OLD.key <> NEW.key THEN DELETE FROM public.permissions WHERE id = OLD.key; END IF;
+    INSERT INTO public.permissions (id, category, description) VALUES (NEW.key, NEW.plugin, NEW.description)
+    ON CONFLICT (id) DO UPDATE SET category = EXCLUDED.category, description = EXCLUDED.description;
+  END IF;
+  PERFORM set_config('app.legacy_mirror_sync', v_prev, true);
+  RETURN NULL;
+END $$;
+DROP TRIGGER IF EXISTS permissions_mirror_legacy ON app.permissions;
+CREATE TRIGGER permissions_mirror_legacy AFTER INSERT OR UPDATE OR DELETE ON app.permissions
+  FOR EACH ROW EXECUTE FUNCTION app.trg_mirror_permissions();
+
+CREATE OR REPLACE FUNCTION app.trg_mirror_roles()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE v_prev text := coalesce(current_setting('app.legacy_mirror_sync', true), 'off');
+BEGIN
+  IF to_regclass('public.tenant_roles') IS NULL THEN RETURN NULL; END IF;
+  PERFORM set_config('app.legacy_mirror_sync', 'on', true);
+  IF TG_OP = 'DELETE' THEN
+    DELETE FROM public.tenant_roles WHERE id = OLD.id;
+    IF to_regclass('public.tenant_role_overrides') IS NOT NULL THEN
+      DELETE FROM public.tenant_role_overrides WHERE tenant_id = OLD.tenant_id AND role = OLD.key;
+    END IF;
+  ELSE
+    IF TG_OP = 'UPDATE' AND OLD.key <> NEW.key AND to_regclass('public.tenant_role_overrides') IS NOT NULL THEN
+      UPDATE public.tenant_role_overrides SET role = NEW.key WHERE tenant_id = NEW.tenant_id AND role = OLD.key;
+    END IF;
+    IF NEW.is_system THEN
+      DELETE FROM public.tenant_roles WHERE id = NEW.id;
+    ELSE
+      DELETE FROM public.tenant_roles WHERE tenant_id = NEW.tenant_id AND key = NEW.key AND id <> NEW.id;
+      INSERT INTO public.tenant_roles (id, tenant_id, key, name, description, created_at)
+      VALUES (NEW.id, NEW.tenant_id, NEW.key, NEW.name, NEW.description, NEW.created_at)
+      ON CONFLICT (id) DO UPDATE SET key = EXCLUDED.key, name = EXCLUDED.name, description = EXCLUDED.description;
+    END IF;
+  END IF;
+  PERFORM set_config('app.legacy_mirror_sync', v_prev, true);
+  RETURN NULL;
+END $$;
+DROP TRIGGER IF EXISTS roles_mirror_legacy ON app.roles;
+CREATE TRIGGER roles_mirror_legacy AFTER INSERT OR UPDATE OR DELETE ON app.roles
+  FOR EACH ROW EXECUTE FUNCTION app.trg_mirror_roles();
+
+CREATE OR REPLACE FUNCTION app.trg_mirror_role_permissions()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  v_prev text := coalesce(current_setting('app.legacy_mirror_sync', true), 'off');
+  v_role app.roles%ROWTYPE;
+BEGIN
+  IF to_regclass('public.tenant_role_overrides') IS NULL THEN RETURN NULL; END IF;
+  PERFORM set_config('app.legacy_mirror_sync', 'on', true);
+  IF TG_OP IN ('DELETE', 'UPDATE') THEN
+    SELECT * INTO v_role FROM app.roles WHERE tenant_id = OLD.tenant_id AND id = OLD.role_id;
+    IF FOUND THEN
+      DELETE FROM public.tenant_role_overrides WHERE tenant_id = OLD.tenant_id AND role = v_role.key AND permission_id = OLD.permission;
+    END IF;
+  END IF;
+  IF TG_OP IN ('INSERT', 'UPDATE') THEN
+    SELECT * INTO v_role FROM app.roles WHERE tenant_id = NEW.tenant_id AND id = NEW.role_id;
+    IF FOUND AND NOT (v_role.is_system AND v_role.key = 'owner') THEN
+      INSERT INTO public.tenant_role_overrides (tenant_id, role, permission_id, granted)
+      VALUES (NEW.tenant_id, v_role.key, NEW.permission, true)
+      ON CONFLICT (tenant_id, role, permission_id) DO UPDATE SET granted = true;
+    END IF;
+  END IF;
+  PERFORM set_config('app.legacy_mirror_sync', v_prev, true);
+  RETURN NULL;
+END $$;
+DROP TRIGGER IF EXISTS role_permissions_mirror_legacy ON app.role_permissions;
+CREATE TRIGGER role_permissions_mirror_legacy AFTER INSERT OR UPDATE OR DELETE ON app.role_permissions
+  FOR EACH ROW EXECUTE FUNCTION app.trg_mirror_role_permissions();
+
+-- ── 4. write-through redirect (legacy tables → app.*), SECURITY INVOKER ───
+-- Fires for the admin's writes. Runs as the caller: app.* RLS (roles.manage,
+-- NOT is_system on delete) is the gate. When the mirror itself is writing
+-- (flag on) the row passes through untouched.
+CREATE OR REPLACE FUNCTION public.trg_legacy_tenant_roles_redirect()
+RETURNS trigger LANGUAGE plpgsql SET search_path = '' AS $$
+BEGIN
+  IF coalesce(current_setting('app.legacy_mirror_sync', true), 'off') = 'on' THEN
+    RETURN CASE WHEN TG_OP = 'DELETE' THEN OLD ELSE NEW END;
+  END IF;
+  IF TG_OP = 'INSERT' THEN
+    INSERT INTO app.roles (tenant_id, key, name, description, is_system)
+    VALUES (NEW.tenant_id, NEW.key, NEW.name, NEW.description, false);
+  ELSIF TG_OP = 'UPDATE' THEN
+    UPDATE app.roles SET key = NEW.key, name = NEW.name, description = NEW.description
+     WHERE tenant_id = OLD.tenant_id AND key = OLD.key AND NOT is_system;
+  ELSE
+    DELETE FROM app.roles WHERE tenant_id = OLD.tenant_id AND key = OLD.key AND NOT is_system;
+  END IF;
+  RETURN NULL;   -- the legacy row is never written; the mirror re-projects app.roles
+END $$;
+DO $$
+BEGIN
+  IF to_regclass('public.tenant_roles') IS NOT NULL THEN
+    EXECUTE 'DROP TRIGGER IF EXISTS tenant_roles_redirect ON public.tenant_roles';
+    EXECUTE 'CREATE TRIGGER tenant_roles_redirect BEFORE INSERT OR UPDATE OR DELETE ON public.tenant_roles FOR EACH ROW EXECUTE FUNCTION public.trg_legacy_tenant_roles_redirect()';
+  END IF;
+END $$;
+
+CREATE OR REPLACE FUNCTION public.trg_legacy_overrides_redirect()
+RETURNS trigger LANGUAGE plpgsql SET search_path = '' AS $$
+DECLARE v_role uuid; v_key text; v_row record;
+BEGIN
+  IF coalesce(current_setting('app.legacy_mirror_sync', true), 'off') = 'on' THEN
+    RETURN CASE WHEN TG_OP = 'DELETE' THEN OLD ELSE NEW END;
+  END IF;
+  -- the OLD half (UPDATE/DELETE): drop the grant it stood for
+  IF TG_OP IN ('UPDATE', 'DELETE') THEN
+    SELECT r.id INTO v_role FROM app.roles r WHERE r.tenant_id = OLD.tenant_id AND r.key = OLD.role;
+    v_key := app.legacy_permission_key(OLD.permission_id);
+    IF v_role IS NOT NULL AND v_key IS NOT NULL THEN
+      DELETE FROM app.role_permissions rp WHERE rp.tenant_id = OLD.tenant_id AND rp.role_id = v_role AND rp.permission = v_key;
+    END IF;
+  END IF;
+  -- the NEW half (INSERT/UPDATE): grant, or revoke when granted = false
+  IF TG_OP IN ('INSERT', 'UPDATE') THEN
+    SELECT r.id INTO v_role FROM app.roles r WHERE r.tenant_id = NEW.tenant_id AND r.key = NEW.role;
+    IF v_role IS NULL THEN
+      RAISE EXCEPTION 'tenant_role_overrides is a compat facade of app.role_permissions: role % does not exist in tenant %', NEW.role, NEW.tenant_id USING ERRCODE = '23503';
+    END IF;
+    v_key := app.legacy_permission_key(NEW.permission_id);
+    IF v_key IS NULL THEN
+      RAISE EXCEPTION 'tenant_role_overrides is a compat facade of app.role_permissions: permission % is not in the catalog (app.permissions)', NEW.permission_id USING ERRCODE = '23503';
+    END IF;
+    IF NEW.granted THEN
+      INSERT INTO app.role_permissions (tenant_id, role_id, permission) VALUES (NEW.tenant_id, v_role, v_key)
+      ON CONFLICT DO NOTHING;
+    ELSE
+      DELETE FROM app.role_permissions rp WHERE rp.tenant_id = NEW.tenant_id AND rp.role_id = v_role AND rp.permission = v_key;
+    END IF;
+  END IF;
+  RETURN NULL;
+END $$;
+DO $$
+BEGIN
+  IF to_regclass('public.tenant_role_overrides') IS NOT NULL THEN
+    EXECUTE 'DROP TRIGGER IF EXISTS tenant_role_overrides_redirect ON public.tenant_role_overrides';
+    EXECUTE 'CREATE TRIGGER tenant_role_overrides_redirect BEFORE INSERT OR UPDATE OR DELETE ON public.tenant_role_overrides FOR EACH ROW EXECUTE FUNCTION public.trg_legacy_overrides_redirect()';
+  END IF;
+END $$;
+
+-- ── 5. run the migration, then rebuild the mirror from app.* ─────────────
+DO $$
+DECLARE v jsonb;
+BEGIN
+  v := app.migrate_legacy_rbac();
+  RAISE NOTICE 'legacy rbac migrated: %', v;
+  v := app.legacy_rbac_resync();
+  RAISE NOTICE 'legacy rbac mirror rebuilt: %', v;
+END $$;
+
+-- ── 6. policies on app.* (same names as 001/021 ⇒ replay converges) ───────
+DO $$
+BEGIN
+  IF to_regclass('public.tenant_role_overrides') IS NOT NULL THEN
+    EXECUTE 'DROP POLICY IF EXISTS "overrides_select" ON public.tenant_role_overrides';
+    EXECUTE 'CREATE POLICY "overrides_select" ON public.tenant_role_overrides FOR SELECT TO authenticated USING ((select app.is_member(tenant_id)))';
+    EXECUTE 'DROP POLICY IF EXISTS "overrides_manage" ON public.tenant_role_overrides';
+    EXECUTE 'CREATE POLICY "overrides_manage" ON public.tenant_role_overrides FOR ALL TO authenticated USING (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission(''roles.manage''))) WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission(''roles.manage'')))';
+    EXECUTE 'DROP POLICY IF EXISTS tenant_isolation_select ON public.tenant_role_overrides';
+    EXECUTE 'DROP POLICY IF EXISTS tenant_isolation_insert ON public.tenant_role_overrides';
+    EXECUTE 'DROP POLICY IF EXISTS tenant_isolation_update ON public.tenant_role_overrides';
+    EXECUTE 'DROP POLICY IF EXISTS tenant_isolation_delete ON public.tenant_role_overrides';
+  END IF;
+  IF to_regclass('public.tenant_roles') IS NOT NULL THEN
+    EXECUTE 'DROP POLICY IF EXISTS "tenant_roles_select" ON public.tenant_roles';
+    EXECUTE 'CREATE POLICY "tenant_roles_select" ON public.tenant_roles FOR SELECT TO authenticated USING ((select app.is_member(tenant_id)))';
+    EXECUTE 'DROP POLICY IF EXISTS "tenant_roles_manage" ON public.tenant_roles';
+    EXECUTE 'CREATE POLICY "tenant_roles_manage" ON public.tenant_roles FOR ALL TO authenticated USING (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission(''roles.manage''))) WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission(''roles.manage'')))';
+    -- 002's replay stamps the generic policies on any public table with tenant_id; not here
+    EXECUTE 'DROP POLICY IF EXISTS tenant_isolation_select ON public.tenant_roles';
+    EXECUTE 'DROP POLICY IF EXISTS tenant_isolation_insert ON public.tenant_roles';
+    EXECUTE 'DROP POLICY IF EXISTS tenant_isolation_update ON public.tenant_roles';
+    EXECUTE 'DROP POLICY IF EXISTS tenant_isolation_delete ON public.tenant_roles';
+  END IF;
+END $$;
+
+-- ── 7. grants + deprecation ───────────────────────────────────────────────
+-- permissions / role_permissions: read-only for the API (the mirror writes as
+-- definer). tenant_roles / tenant_role_overrides keep their write privileges so
+-- the redirect triggers can fire — no row ever lands there from a caller.
+DO $$
+BEGIN
+  IF to_regclass('public.permissions') IS NOT NULL THEN
+    EXECUTE 'REVOKE INSERT, UPDATE, DELETE, TRUNCATE ON public.permissions FROM authenticated, anon';
+    EXECUTE 'COMMENT ON TABLE public.permissions IS ''DEPRECATED (#136, Phase 0): read-only mirror of app.permissions (id = key, category = plugin) kept for @fayz-ai/admin''''s permission matrix. Drop in Phase 1 once the admin reads public.v_authz_permissions.''';
+  END IF;
+  IF to_regclass('public.role_permissions') IS NOT NULL THEN
+    EXECUTE 'REVOKE INSERT, UPDATE, DELETE, TRUNCATE ON public.role_permissions FROM authenticated, anon';
+    EXECUTE 'COMMENT ON TABLE public.role_permissions IS ''DEPRECATED (#136, Phase 0): always empty. Per-role grants live in app.role_permissions (per tenant); the admin reads them through tenant_role_overrides. Drop in Phase 1.''';
+  END IF;
+  IF to_regclass('public.tenant_roles') IS NOT NULL THEN
+    EXECUTE 'REVOKE ALL ON public.tenant_roles FROM anon';
+    EXECUTE 'COMMENT ON TABLE public.tenant_roles IS ''DEPRECATED (#136, Phase 0): write-through mirror of app.roles WHERE NOT is_system. Writes are redirected to app.roles by trigger (roles.manage via RLS). Drop in Phase 1 once @fayz-ai/admin uses public.v_authz_roles / role_create_from_template.''';
+  END IF;
+  IF to_regclass('public.tenant_role_overrides') IS NOT NULL THEN
+    EXECUTE 'REVOKE ALL ON public.tenant_role_overrides FROM anon';
+    EXECUTE 'COMMENT ON TABLE public.tenant_role_overrides IS ''DEPRECATED (#136, Phase 0): write-through mirror of app.role_permissions ⋈ app.roles (role = key, granted = true; owner excluded). Writes are redirected to app.role_permissions by trigger. Drop in Phase 1 once @fayz-ai/admin uses public.v_authz_role_permissions / role_set_permissions.''';
+  END IF;
+END $$;