@fayz-ai/db 0.13.0 → 0.14.0

package/migrations/001_the_tenant_has_apps.sql

@@ -0,0 +1,314 @@
+-- ---------------------------------------------------------------------------
+-- 001_the_tenant_has_apps.sql — an account can run more than one application.
+--
+-- Until now the only thing a tenant could HAVE was a (plugin, facet) pair in
+-- app.tenant_plugins. Which PRODUCT a tenant was living in — the restaurant
+-- admin, the shop admin — was never written down: it was inferred from
+-- tenants.vertical_id, a free-text column with no FK and no check, stamped once
+-- by an AFTER INSERT trigger and never revisited. That was survivable while each
+-- product had its own Supabase pool and a merchant was literally two different
+-- auth.users. On one cluster it is not: the same person, the same account and
+-- the same public.products now sit behind two front doors, and nothing in the
+-- database says so.
+--
+-- So the relation gets written down.
+--
+--   app.apps         the registry — which applications exist at all
+--   app.tenant_apps  the relation  — which of them THIS account runs
+--
+-- The switcher in the sidebar reads the second through app_config(). Nothing
+-- here gates data: an app is a lens over the tenant's rows, not a boundary
+-- around them. Two apps on one tenant read the same public.products by design —
+-- that is the whole point, and it is why this is a relation and not a second
+-- tenant.
+--
+-- ── Why app_id has a real FK, when plugin_id does not ──────────────────────
+--
+-- tenant_plugins.plugin_id is text with only a regex, and vertical_id has not
+-- even that. The bill arrived: four vocabularies of "vertical" now disagree
+-- (the column, app.vertical_defaults, the TS union, the onboarding packs), and
+-- four of eight live tenants matched no defaults at all and were seeded with
+-- nothing. ADR 0022 — a registry with a real FOREIGN KEY from day one — is the
+-- rule this file follows so the same drift cannot start again.
+-- ---------------------------------------------------------------------------
+
+-- ── §1  the registry ───────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS app.apps (
+  id            text PRIMARY KEY CHECK (id ~ '^[a-z][a-z0-9-]*$'),
+  name          text NOT NULL,
+  -- A lucide icon NAME, resolved client-side through getLucideIcon — a curated
+  -- registry, not all of lucide. A name outside it falls back to initials
+  -- rather than dragging ~500KB of icons into every app that shows a launcher.
+  icon          text,
+  accent_color  text CHECK (accent_color IS NULL OR accent_color ~ '^#[0-9a-fA-F]{6}$'),
+  -- Canonical origin. Also the allow-list the session handoff checks against:
+  -- the switcher will not hand a session to an origin that is not named here.
+  url           text,
+  -- The plugins this app cannot work without. Activating the app activates
+  -- these; deactivating it does NOT deactivate them, because another app on the
+  -- same tenant may be standing on them.
+  requires      text[] NOT NULL DEFAULT '{}',
+  active        boolean NOT NULL DEFAULT true,
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now()
+);
+
+COMMENT ON TABLE app.apps IS
+  'Which applications exist on this cluster (001). The registry the app switcher reads. An app is a LENS over a tenant''s rows — it never scopes them; two apps on one tenant share public.products by design. `requires` names the plugins the app cannot work without; `url` doubles as the allow-list for the session handoff.';
+COMMENT ON COLUMN app.apps.icon IS 'Lucide icon name (e.g. ChefHat). Resolved through getLucideIcon, a curated registry — an unknown name falls back to initials.';
+COMMENT ON COLUMN app.apps.requires IS 'plugin_ids activated when the app is added. Removing the app does NOT remove them: another app may share them.';
+
+-- ── §2  the relation ───────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS app.tenant_apps (
+  tenant_id   uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  app_id      text NOT NULL REFERENCES app.apps(id) ON DELETE RESTRICT,
+  status      text NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'disabled')),
+  source      text NOT NULL DEFAULT 'manual' CHECK (source IN ('manual', 'onboarding', 'plan', 'default')),
+  added_by    uuid,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  updated_at  timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, app_id)
+);
+
+CREATE INDEX IF NOT EXISTS tenant_apps_app_idx ON app.tenant_apps (app_id);
+
+COMMENT ON TABLE app.tenant_apps IS
+  'Which applications THIS account runs (001). The app switcher lists the active rows. Disabling a row hides the app; it never touches the tenant''s data, which belongs to the tenant and not to the app that happened to write it.';
+
+-- Both tables carry updated_at, so reuse the spine's existing stamp.
+DROP TRIGGER IF EXISTS apps_updated_at ON app.apps;
+CREATE TRIGGER apps_updated_at BEFORE UPDATE ON app.apps
+  FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+
+DROP TRIGGER IF EXISTS tenant_apps_updated_at ON app.tenant_apps;
+CREATE TRIGGER tenant_apps_updated_at BEFORE UPDATE ON app.tenant_apps
+  FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+
+-- ── §3  RLS ────────────────────────────────────────────────────────────────
+--
+-- Same posture as app.tenant_plugins and app.vertical_defaults: the registry is
+-- world-readable to a signed-in user (it is a catalogue of products, not a
+-- secret), the relation is readable only for the tenants you belong to, and
+-- NEITHER has a write policy — writes go through the SECURITY DEFINER function
+-- in §4, which is where the permission and the plan ceiling are checked.
+
+ALTER TABLE app.apps ENABLE ROW LEVEL SECURITY;
+ALTER TABLE app.tenant_apps ENABLE ROW LEVEL SECURITY;
+
+DROP POLICY IF EXISTS apps_read ON app.apps;
+CREATE POLICY apps_read ON app.apps FOR SELECT TO authenticated USING (true);
+
+DROP POLICY IF EXISTS tenant_apps_read ON app.tenant_apps;
+CREATE POLICY tenant_apps_read ON app.tenant_apps FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+
+GRANT SELECT ON TABLE app.apps TO authenticated;
+GRANT ALL    ON TABLE app.apps TO service_role;
+GRANT SELECT ON TABLE app.tenant_apps TO authenticated;
+GRANT ALL    ON TABLE app.tenant_apps TO service_role;
+
+-- ── §4  the one writer ─────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.tenant_app_set(
+  p_app    text,
+  p_status text DEFAULT 'active',
+  p_source text DEFAULT 'manual'
+) RETURNS jsonb
+    LANGUAGE plpgsql SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+DECLARE
+  v_tenant   uuid := app.current_tenant_id();
+  v_app      app.apps%ROWTYPE;
+  v_plugin   text;
+  v_refused  text[] := '{}';
+BEGIN
+  IF v_tenant IS NULL THEN
+    RAISE EXCEPTION 'no tenant in scope' USING ERRCODE = '42501';
+  END IF;
+  IF NOT app.has_permission('settings.manage') THEN
+    RAISE EXCEPTION 'settings.manage is required to change which applications this account runs'
+      USING ERRCODE = '42501';
+  END IF;
+  IF p_status NOT IN ('active', 'disabled') THEN
+    RAISE EXCEPTION 'status must be active or disabled' USING ERRCODE = '22023';
+  END IF;
+
+  SELECT * INTO v_app FROM app.apps WHERE id = p_app AND active;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'no such application: %', p_app USING ERRCODE = '22023';
+  END IF;
+
+  INSERT INTO app.tenant_apps (tenant_id, app_id, status, source, added_by)
+  VALUES (v_tenant, p_app, p_status, p_source, auth.uid())
+  ON CONFLICT (tenant_id, app_id) DO UPDATE
+    SET status   = EXCLUDED.status,
+        source   = EXCLUDED.source,
+        added_by = EXCLUDED.added_by;
+
+  -- Adding an app switches on what it cannot work without. Each plugin still
+  -- passes the plan ceiling on its own: an app the plan allows may still name a
+  -- plugin it does not, and the honest answer is to add the app with that
+  -- plugin missing and SAY so, rather than to refuse the app or to smuggle the
+  -- plugin past the ceiling.
+  --
+  -- Removing an app switches OFF nothing. Another app on this tenant may be
+  -- standing on the same plugin, and the tenant's rows outlive both.
+  IF p_status = 'active' THEN
+    FOREACH v_plugin IN ARRAY v_app.requires LOOP
+      IF public.plan_permits(v_plugin, '', v_tenant) THEN
+        INSERT INTO app.tenant_plugins (tenant_id, plugin_id, facet, status, source, activated_by)
+        VALUES (v_tenant, v_plugin, '', 'active', 'default', auth.uid())
+        ON CONFLICT (tenant_id, plugin_id, facet) DO UPDATE
+          SET status = 'active';
+      ELSE
+        v_refused := v_refused || v_plugin;
+      END IF;
+    END LOOP;
+  END IF;
+
+  RETURN jsonb_build_object(
+    'app', p_app,
+    'status', p_status,
+    'plugins_activated', to_jsonb(v_app.requires),
+    'not_permitted_by_plan', to_jsonb(v_refused)
+  );
+END $$;
+
+REVOKE ALL ON FUNCTION public.tenant_app_set(text, text, text) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION public.tenant_app_set(text, text, text) TO authenticated;
+
+COMMENT ON FUNCTION public.tenant_app_set(text, text, text) IS
+  'Add or remove an application for the tenant in scope (001). Mirrors tenant_plugin_set: settings.manage required, the plan ceiling checked per required plugin, turning something OFF always allowed. Reports the plugins it could not switch on rather than failing the whole call.';
+
+-- ── §5  app_config() learns to answer "which apps" ─────────────────────────
+--
+-- Re-emitted whole rather than patched: this is the one function the shell asks
+-- on boot, and a reader should see the entire answer in one place. The only
+-- change is the 'apps' key.
+
+CREATE OR REPLACE FUNCTION public.app_config() RETURNS jsonb
+    LANGUAGE plpgsql STABLE SECURITY DEFINER
+    SET search_path TO ''
+    AS $$
+DECLARE
+  v_tenant uuid := app.current_tenant_id();
+BEGIN
+  IF v_tenant IS NULL THEN
+    -- Fail closed and legibly: a caller with no resolvable tenant gets an empty
+    -- configuration, not somebody else's.
+    RETURN jsonb_build_object('tenant_id', NULL, 'plugins', '[]'::jsonb, 'nav', '[]'::jsonb, 'apps', '[]'::jsonb);
+  END IF;
+
+  RETURN jsonb_build_object(
+    'tenant_id', v_tenant,
+    'branding',  public.tenant_branding(),
+    'settings',  public.tenant_settings(),
+    'plugins', coalesce((
+      SELECT jsonb_agg(jsonb_build_object(
+               'plugin', t.plugin_id,
+               'facet',  nullif(t.facet, ''),
+               'status', t.status,
+               'source', t.source,
+               'config', t.config,
+               'expires_at', t.expires_at
+             ) ORDER BY t.plugin_id, t.facet)
+        FROM app.tenant_plugins t
+       WHERE t.tenant_id = v_tenant
+         AND t.status = 'active'
+         AND (t.expires_at IS NULL OR t.expires_at > now())
+    ), '[]'::jsonb),
+    'apps', coalesce((
+      SELECT jsonb_agg(jsonb_build_object(
+               'id', a.id,
+               'name', a.name,
+               'icon', a.icon,
+               'accent_color', a.accent_color,
+               'url', a.url
+             ) ORDER BY a.name)
+        FROM app.tenant_apps ta
+        JOIN app.apps a ON a.id = ta.app_id
+       WHERE ta.tenant_id = v_tenant
+         AND ta.status = 'active'
+         AND a.active
+    ), '[]'::jsonb),
+    'nav', coalesce((
+      SELECT jsonb_agg(jsonb_build_object(
+               'key', n.entry_key, 'hidden', n.hidden, 'label', n.label,
+               'section', n.section, 'position', n.position
+             ) ORDER BY coalesce(n.position, 999), n.entry_key)
+        FROM app.tenant_nav n
+       WHERE n.tenant_id = v_tenant
+    ), '[]'::jsonb),
+    'permissions', coalesce((
+      SELECT jsonb_agg(DISTINCT rp.permission)
+        FROM app.memberships m
+        JOIN app.role_permissions rp ON rp.role_id = m.role_id AND rp.tenant_id = m.tenant_id
+       WHERE m.tenant_id = v_tenant AND m.user_id = auth.uid() AND m.active
+    ), '[]'::jsonb),
+    'generated_at', now()
+  );
+END $$;
+
+-- ── §6  the registry's first rows ──────────────────────────────────────────
+--
+-- `requires` mirrors the signals in packages/admin/src/onboarding/infer-vertical.ts,
+-- which already answers "which vertical is this app" from the plugins the bundle
+-- carries. Same evidence, read in the other direction — a second, disagreeing
+-- list is exactly how the four vertical vocabularies happened.
+--
+-- `url` is the dev origin. A cluster that publishes these apps elsewhere updates
+-- the row; nothing in code hardcodes a port.
+
+-- The names are the products' OUTWARD names (ADR: "Control" is the family, not
+-- the app). "Control" is spoken once — in the dropdown's own header — and each
+-- app's rail says only its vertical: Chef, Store, Studio. The switcher's list is
+-- outward, so it carries the full name.
+INSERT INTO app.apps (id, name, icon, accent_color, url, requires) VALUES
+  ('resto',  'ChefControl',   'ChefHat',       '#DC2626', 'http://localhost:5302', ARRAY['menu', 'financial', 'inventory']),
+  ('shop',   'StoreControl',  'ShoppingBag',   '#0F9D58', 'http://localhost:5305', ARRAY['shop', 'financial', 'inventory']),
+  ('beauty', 'StudioControl', 'Scissors',      '#7C3AED', 'http://localhost:5301', ARRAY['agenda', 'crm', 'financial']),
+  -- The school product has no agreed outward name yet; the vertical stands in.
+  ('school', 'Escola',        'GraduationCap', '#D97706', 'http://localhost:5311', ARRAY['courses', 'agenda', 'financial'])
+ON CONFLICT (id) DO UPDATE
+  SET name = EXCLUDED.name, icon = EXCLUDED.icon, accent_color = EXCLUDED.accent_color,
+      url = EXCLUDED.url, requires = EXCLUDED.requires;
+
+-- ── §7  backfill: what every existing tenant was already running ───────────
+--
+-- Read from vertical_id, which is the only record that exists. Deliberately a
+-- one-shot backfill and NOT a trigger: vertical_id being applied once at INSERT
+-- and never revisited is the defect this file exists to end, and reproducing
+-- that mechanism for apps would reproduce the defect. From here on the writer
+-- is tenant_app_set(), called by onboarding or by a person.
+--
+-- The mapping is wider than app.vertical_defaults' five values because the live
+-- column holds seven, four of which that table has never heard of.
+
+INSERT INTO app.tenant_apps (tenant_id, app_id, status, source)
+SELECT t.id,
+       CASE t.vertical_id
+         WHEN 'restaurant' THEN 'resto'
+         WHEN 'food'       THEN 'resto'
+         WHEN 'commerce'   THEN 'shop'
+         WHEN 'ecommerce'  THEN 'shop'
+         WHEN 'retail'     THEN 'shop'
+         WHEN 'salon'      THEN 'beauty'
+         WHEN 'clinic'     THEN 'beauty'
+         WHEN 'beauty'     THEN 'beauty'
+         WHEN 'school'     THEN 'school'
+         WHEN 'education'  THEN 'school'
+       END,
+       'active', 'default'
+  FROM public.tenants t
+ WHERE t.vertical_id IS NOT NULL
+   AND CASE t.vertical_id
+         WHEN 'restaurant' THEN 'resto' WHEN 'food'      THEN 'resto'
+         WHEN 'commerce'   THEN 'shop'  WHEN 'ecommerce' THEN 'shop'
+         WHEN 'retail'     THEN 'shop'  WHEN 'salon'     THEN 'beauty'
+         WHEN 'clinic'     THEN 'beauty' WHEN 'beauty'   THEN 'beauty'
+         WHEN 'school'     THEN 'school' WHEN 'education' THEN 'school'
+       END IS NOT NULL
+ON CONFLICT (tenant_id, app_id) DO NOTHING;

package/migrations/002_the_spine_drops_the_vendor_and_the_dead.sql

@@ -0,0 +1,129 @@
+-- ============================================================================
+-- 002_the_spine_drops_the_vendor_and_the_dead — fayz_search_sources and
+-- the superseded grant table leave (#352).
+--
+-- ── fayz_search_sources ────────────────────────────────────────────────────
+-- 137 took the vendor out of the spine's names: a table should say what it
+-- holds, not who built it. `fayz_search_sources` became `search_sources` and
+-- 141 left the old name answering until callers moved. One caller never did,
+-- and it is the spine's own: public.fayz_search_reindex(). Redefined below
+-- from 000_baseline's body with that one name changed, then the view goes.
+--
+-- (The function keeps its own vendor name. 137 renamed three objects and this
+-- was not one of them; renaming it here would be a second decision wearing
+-- this file's clothes, and it needs its own with its callers counted.)
+--
+-- ── public.resource_grants, and the two functions that read it ─────────────
+-- #242 superseded it with app.resource_grants, 064 carried the rows across,
+-- and its own COMMENT has said since then that "it no longer governs any
+-- policy". Measured, and that is exactly true: ZERO policies reference either
+-- function that reads it, no view does, and no other function does. What is
+-- left is two SECURITY DEFINER functions selecting from an empty table that
+-- nothing calls — dead code over a dead table, which is the most expensive
+-- kind to leave, because the next person to find it has to prove it is dead
+-- all over again.
+--
+-- Dropped together and in order: a SQL (not plpgsql) function binds its names
+-- at creation, so the table cannot go first.
+--
+-- ── addresses gets the FK it always should have had ───────────────────────
+-- public.addresses is the address model (017, 113, 142) and carries no foreign
+-- key at all. For the OWNER that is deliberate and unavoidable — owner_type is
+-- polymorphic across six kinds and no single FK can express it. For tenant_id
+-- it is neither: every other core table has it, and without it a deleted
+-- tenant leaves its addresses behind. Added guarded, so a pool that somehow
+-- has orphans is told rather than failed.
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION public.fayz_search_reindex() RETURNS integer
+    LANGUAGE plpgsql
+    SET search_path TO 'public', 'extensions', 'pg_temp'
+    AS $$
+DECLARE
+  v_src      record;
+  v_rel      text;
+  v_name     text;
+  v_built    integer := 0;
+  v_has_trgm boolean := EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'pg_trgm');
+  v_has_gin  boolean := EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'btree_gin');
+BEGIN
+  IF NOT v_has_trgm THEN
+    RAISE NOTICE 'fayz search: pg_trgm missing — no index built, search falls back to sequential LIKE';
+    RETURN 0;
+  END IF;
+
+  FOR v_src IN
+    SELECT * FROM public.search_sources WHERE enabled ORDER BY entity_key
+  LOOP
+    v_rel := to_regclass(v_src.relation)::text;
+    CONTINUE WHEN v_rel IS NULL;
+    -- A view cannot be indexed; only its base tables can.
+    CONTINUE WHEN (SELECT c.relkind FROM pg_class c WHERE c.oid = to_regclass(v_src.relation))
+                  NOT IN ('r', 'p');
+
+    -- Name derived from (relation, expression): two sources over the same
+    -- columns share one index instead of building it twice.
+    v_name := 'fayz_search_' || substr(md5(v_rel || '|' || v_src.haystack_expr), 1, 20);
+
+    BEGIN
+      IF v_has_gin THEN
+        -- Composite: the tenant equality is resolved INSIDE the index, so a
+        -- 500-tenant pool does not trigram-scan its neighbours' rows.
+        EXECUTE format(
+          'CREATE INDEX IF NOT EXISTS %I ON %s USING gin (%I, public.fayz_norm(%s) gin_trgm_ops)',
+          v_name, v_rel, v_src.tenant_column, v_src.haystack_expr);
+      ELSE
+        EXECUTE format(
+          'CREATE INDEX IF NOT EXISTS %I ON %s USING gin (public.fayz_norm(%s) gin_trgm_ops)',
+          v_name, v_rel, v_src.haystack_expr);
+      END IF;
+      v_built := v_built + 1;
+    EXCEPTION WHEN OTHERS THEN
+      -- Most likely cause: btree_gin present but with no GIN opclass for the
+      -- tenant column's type. A trigram-only index still serves every query;
+      -- the tenant equality just becomes a recheck.
+      BEGIN
+        EXECUTE format(
+          'CREATE INDEX IF NOT EXISTS %I ON %s USING gin (public.fayz_norm(%s) gin_trgm_ops)',
+          v_name, v_rel, v_src.haystack_expr);
+        v_built := v_built + 1;
+      EXCEPTION WHEN OTHERS THEN
+        RAISE NOTICE 'fayz search: could not index % (%): %', v_src.entity_key, v_rel, SQLERRM;
+      END;
+    END;
+  END LOOP;
+
+  RETURN v_built;
+END $$;
+
+DROP VIEW IF EXISTS public.fayz_search_sources;
+
+DROP FUNCTION IF EXISTS public.granted_record_ids(text);
+DROP FUNCTION IF EXISTS public.restricted_record_ids(text);
+DROP TABLE IF EXISTS public.resource_grants;
+
+DO $addr$
+DECLARE v_orphans bigint;
+BEGIN
+  IF to_regclass('public.addresses') IS NULL THEN RETURN; END IF;
+  IF EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'addresses_tenant_id_fkey') THEN RETURN; END IF;
+
+  SELECT count(*) INTO v_orphans
+    FROM public.addresses a
+   WHERE NOT EXISTS (SELECT 1 FROM public.tenants t WHERE t.id = a.tenant_id);
+
+  IF v_orphans > 0 THEN
+    RAISE NOTICE 'addresses: % row(s) name a tenant that does not exist — FK not added, clean them first', v_orphans;
+    RETURN;
+  END IF;
+
+  ALTER TABLE public.addresses
+    ADD CONSTRAINT addresses_tenant_id_fkey
+    FOREIGN KEY (tenant_id) REFERENCES public.tenants(id) ON DELETE CASCADE;
+END $addr$;
+
+-- ── fayz_global_search, the third of 137's renames ─────────────────────────
+-- Same shim, different shape: a FUNCTION forwarding to public.global_search
+-- rather than a view forwarding to a table. Same verdict — no caller in the
+-- code, no view, no other function.
+DROP FUNCTION IF EXISTS public.fayz_global_search(text, uuid, text[], integer, integer);

package/migrations/003_the_role_rpcs_finish_and_the_mirrors_go.sql

@@ -0,0 +1,135 @@
+-- ============================================================================
+-- 003_the_role_rpcs_finish_and_the_mirrors_go — #136's last four tables, and
+-- the two RPCs that were missing for them to leave (#352).
+--
+-- #136 moved authorization into app.* and left four write-through mirrors in
+-- public so @fayz-ai/admin's permission matrix kept working. Each carries its
+-- own COMMENT saying it is deprecated and naming what replaces it, and every
+-- one of those comments has ended with "Drop in Phase 1" since Phase 0.
+--
+--   public.permissions            -> public.v_authz_permissions
+--   public.role_permissions       -> always empty; app.role_permissions is per
+--                                    tenant and this global table never held a
+--                                    row. Measured: zero, in every pool.
+--   public.tenant_roles           -> public.v_authz_roles
+--   public.tenant_role_overrides  -> public.v_authz_role_permissions
+--
+-- WHY THEY COULD NOT LEAVE. The read side was ready — the v_authz_* views have
+-- existed all along, and they ARE security_invoker, so RLS on app.* still
+-- applies to whoever selects them. The WRITE side was not: role_create_from_
+-- template and role_set_permissions cover creating a role and setting its
+-- grants, and nothing covered RENAMING or DELETING one. The admin did both by
+-- writing public.tenant_roles and letting a trigger redirect it. So the mirror
+-- was not kept for the matrix; it was kept for two verbs nobody had written.
+--
+-- They are written here, to the same shape as the two that exist: SECURITY
+-- DEFINER with an empty search_path, the tenant from the session rather than a
+-- parameter, roles.manage required, and a system role refused — with delete
+-- refusing on top of that any role somebody is still assigned, because taking
+-- a member's role away as a side effect of tidying is not a rename.
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION public.role_rename(p_role_id uuid, p_name text, p_description text DEFAULT NULL)
+ RETURNS uuid
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO ''
+AS $function$
+DECLARE
+  v_tenant uuid := app.current_tenant_id();
+  v_role   app.roles%ROWTYPE;
+BEGIN
+  IF auth.uid() IS NULL OR v_tenant IS NULL THEN
+    RAISE EXCEPTION 'role_rename: no active tenant for this session' USING ERRCODE = '42501';
+  END IF;
+  IF NOT app.has_permission('roles.manage') THEN
+    RAISE EXCEPTION 'role_rename: 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_rename: role not found in the active tenant' USING ERRCODE = 'P0002';
+  END IF;
+  -- A system role's name is the platform's, not the tenant's: it is what the
+  -- permission templates and every vertical's seed refer to.
+  IF v_role.is_system THEN
+    RAISE EXCEPTION 'role_rename: a system role cannot be renamed' USING ERRCODE = '42501';
+  END IF;
+  IF p_name IS NOT NULL AND btrim(p_name) = '' THEN
+    RAISE EXCEPTION 'role_rename: a name cannot be blank' USING ERRCODE = '22023';
+  END IF;
+
+  UPDATE app.roles
+     SET name        = coalesce(btrim(p_name), name),
+         -- NULL description is "clear it", which is why this is not coalesce:
+         -- the caller passing NULL for a field it did not touch would be the
+         -- bug, and the admin sends the field only when the form changed it.
+         description = p_description,
+         updated_at  = now()
+   WHERE tenant_id = v_tenant AND id = p_role_id;
+
+  RETURN p_role_id;
+END $function$;
+
+REVOKE ALL ON FUNCTION public.role_rename(uuid, text, text) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION public.role_rename(uuid, text, text) TO authenticated, service_role;
+
+COMMENT ON FUNCTION public.role_rename(uuid, text, text) IS
+  'Rename a tenant-created role (PRD 01 / #136). System roles are refused: their names belong to the templates. Pass p_description explicitly — NULL clears it.';
+
+CREATE OR REPLACE FUNCTION public.role_delete(p_role_id uuid)
+ RETURNS void
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO ''
+AS $function$
+DECLARE
+  v_tenant  uuid := app.current_tenant_id();
+  v_role    app.roles%ROWTYPE;
+  v_holders integer;
+BEGIN
+  IF auth.uid() IS NULL OR v_tenant IS NULL THEN
+    RAISE EXCEPTION 'role_delete: no active tenant for this session' USING ERRCODE = '42501';
+  END IF;
+  IF NOT app.has_permission('roles.manage') THEN
+    RAISE EXCEPTION 'role_delete: 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_delete: role not found in the active tenant' USING ERRCODE = 'P0002';
+  END IF;
+  IF v_role.is_system THEN
+    RAISE EXCEPTION 'role_delete: a system role cannot be deleted' USING ERRCODE = '42501';
+  END IF;
+
+  -- Deleting a role somebody holds silently demotes them. Refuse and say how
+  -- many, so the caller reassigns first: an authorization change should never
+  -- be a side effect of tidying up a list.
+  SELECT count(*) INTO v_holders
+    FROM app.memberships m
+   WHERE m.tenant_id = v_tenant AND m.role_id = p_role_id AND m.active;
+  IF v_holders > 0 THEN
+    RAISE EXCEPTION 'role_delete: % member(s) still hold this role — reassign them first', v_holders
+      USING ERRCODE = '23503';
+  END IF;
+
+  DELETE FROM app.role_permissions WHERE tenant_id = v_tenant AND role_id = p_role_id;
+  DELETE FROM app.roles            WHERE tenant_id = v_tenant AND id      = p_role_id;
+END $function$;
+
+REVOKE ALL ON FUNCTION public.role_delete(uuid) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION public.role_delete(uuid) TO authenticated, service_role;
+
+COMMENT ON FUNCTION public.role_delete(uuid) IS
+  'Delete a tenant-created role and its grants (PRD 01 / #136). Refuses a system role, and refuses any role an active member still holds.';
+
+-- ── the four mirrors, now that the verbs exist ──────────────────────────────
+-- No view depends on any of them (checked), the triggers that redirected their
+-- writes are dropped with the tables they sit on, and every function that
+-- names them is plpgsql, which resolves names when it runs rather than when it
+-- is created.
+DROP TABLE IF EXISTS public.tenant_role_overrides;
+DROP TABLE IF EXISTS public.tenant_roles;
+DROP TABLE IF EXISTS public.role_permissions;
+DROP TABLE IF EXISTS public.permissions;