@fayz-ai/db 0.11.0 → 0.13.0

package/migrations/052_authz_fanout.sql

@@ -0,0 +1,253 @@
+-- ============================================================================
+-- 052_authz_fanout.sql — user_unit_access maintenance (§5) + reconciliation (§6).
+--
+-- The share table is DERIVED from memberships × membership_units × units. Rather
+-- than hand-writing an add/remove per event and getting one of the four fan-out
+-- cases wrong, every trigger rebuilds the affected users' rows from the source
+-- of truth (app.compute_user_unit_access) inside the same transaction. The
+-- reconciliation job is the same rebuild for a whole tenant, with a diff-log.
+--
+-- Decisions taken as the spec's defaults (grill items 1, 2 and 8): access at a
+-- parent unit PROPAGATES to its subtree; a deactivated unit's rows are REMOVED
+-- (reconciliation restores them on reactivation); `via` provenance is kept.
+--
+-- The four cases:
+--   F1 membership_units insert/delete/update  → rebuild that user
+--   F2 memberships insert/update(all_units, active, role)/delete → rebuild that user
+--   F3 units insert (active)                  → rebuild every all_units member and
+--                                               every user with explicit access to
+--                                               an ancestor of the new unit
+--   F4 units.parent_unit_id / active change   → rebuild the tenant's affected users
+--                                               (all_units + anyone with explicit
+--                                               access anywhere in the tenant)
+-- ============================================================================
+
+-- What (unit, via) a user should have. Precedence when several paths reach the
+-- same unit: all_units > explicit > subtree.
+CREATE OR REPLACE FUNCTION app.compute_user_unit_access(p_tenant uuid, p_user uuid)
+RETURNS TABLE (unit_id uuid, via text)
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+  WITH m AS (
+    SELECT all_units FROM app.memberships
+     WHERE tenant_id = p_tenant AND user_id = p_user AND active
+  ),
+  explicit AS (
+    SELECT mu.unit_id
+      FROM app.membership_units mu
+      JOIN app.units u ON u.tenant_id = mu.tenant_id AND u.id = mu.unit_id AND u.active
+     WHERE mu.tenant_id = p_tenant AND mu.user_id = p_user
+       AND EXISTS (SELECT 1 FROM m)
+  ),
+  subtree AS (
+    -- descendants of every explicit unit (parent access ⇒ subtree access)
+    WITH RECURSIVE d AS (
+      SELECT u.id, u.parent_unit_id, 0 AS depth
+        FROM app.units u
+       WHERE u.tenant_id = p_tenant AND u.id IN (SELECT unit_id FROM explicit)
+      UNION ALL
+      SELECT c.id, c.parent_unit_id, d.depth + 1
+        FROM app.units c
+        JOIN d ON c.parent_unit_id = d.id
+       WHERE c.tenant_id = p_tenant AND c.active AND d.depth < 32
+    )
+    SELECT DISTINCT id AS unit_id FROM d WHERE depth > 0
+  ),
+  everything AS (
+    SELECT u.id AS unit_id FROM app.units u
+     WHERE u.tenant_id = p_tenant AND u.active
+       AND EXISTS (SELECT 1 FROM m WHERE all_units)
+  ),
+  ranked AS (
+    SELECT unit_id, 'all_units'::text AS via, 1 AS prio FROM everything
+    UNION ALL
+    SELECT unit_id, 'explicit', 2 FROM explicit
+    UNION ALL
+    SELECT unit_id, 'subtree', 3 FROM subtree
+  )
+  SELECT DISTINCT ON (unit_id) unit_id, via
+    FROM ranked
+   ORDER BY unit_id, prio;
+$$;
+
+-- Rebuild one user's rows in place. Returns (added, removed). Two statements on
+-- purpose: a row whose `via` changed is deleted by the first and re-inserted by
+-- the second — a single data-modifying CTE cannot delete and upsert the same
+-- row in one command.
+CREATE OR REPLACE FUNCTION app.refresh_user_unit_access(p_tenant uuid, p_user uuid, OUT added integer, OUT removed integer)
+LANGUAGE plpgsql SECURITY DEFINER
+SET search_path = ''
+AS $$
+BEGIN
+  WITH desired AS (
+    SELECT unit_id, via FROM app.compute_user_unit_access(p_tenant, p_user)
+  ), del AS (
+    DELETE FROM app.user_unit_access a
+     WHERE a.tenant_id = p_tenant AND a.user_id = p_user
+       AND NOT EXISTS (SELECT 1 FROM desired d WHERE d.unit_id = a.unit_id AND d.via = a.via)
+    RETURNING 1
+  )
+  SELECT count(*) INTO removed FROM del;
+
+  WITH ins AS (
+    INSERT INTO app.user_unit_access (tenant_id, user_id, unit_id, via)
+    SELECT p_tenant, p_user, d.unit_id, d.via FROM app.compute_user_unit_access(p_tenant, p_user) d
+    ON CONFLICT (tenant_id, user_id, unit_id) DO NOTHING
+    RETURNING 1
+  )
+  SELECT count(*) INTO added FROM ins;
+END $$;
+
+-- The reconciliation job (§6): rebuild a whole tenant, log the diff, return it.
+-- Runs after every authz migration (source='migration'), nightly per tenant
+-- (source='scheduled'), on demand (source='manual'). A non-zero diff outside a
+-- migration is an incident: v_authz_reconciliation_alerts (043) surfaces it.
+CREATE OR REPLACE FUNCTION app.recompute_user_unit_access(p_tenant uuid, p_source text DEFAULT 'manual')
+RETURNS TABLE (added integer, removed integer)
+LANGUAGE plpgsql SECURITY DEFINER
+SET search_path = ''
+AS $$
+DECLARE
+  v_added   integer := 0;
+  v_removed integer := 0;
+  v_details jsonb := '[]'::jsonb;
+  r record;
+BEGIN
+  IF p_source NOT IN ('migration', 'scheduled', 'manual', 'test') THEN
+    RAISE EXCEPTION 'recompute_user_unit_access: unknown source %', p_source;
+  END IF;
+
+  -- Rows for users who no longer hold a membership at all cannot exist (FK
+  -- cascade); rows for members are rebuilt one by one.
+  FOR r IN SELECT m.user_id FROM app.memberships m WHERE m.tenant_id = p_tenant LOOP
+    DECLARE a integer; d integer;
+    BEGIN
+      SELECT ra.added, ra.removed INTO a, d FROM app.refresh_user_unit_access(p_tenant, r.user_id) ra;
+      IF a <> 0 OR d <> 0 THEN
+        v_details := v_details || jsonb_build_object('user_id', r.user_id, 'added', a, 'removed', d);
+      END IF;
+      v_added := v_added + a;
+      v_removed := v_removed + d;
+    END;
+  END LOOP;
+
+  INSERT INTO app.authz_reconciliation_log (tenant_id, source, added, removed, details)
+  VALUES (p_tenant, p_source, v_added, v_removed, v_details);
+
+  added := v_added; removed := v_removed;
+  RETURN NEXT;
+END $$;
+
+-- Every tenant (used by migrations touching authz tables, and by the bench).
+CREATE OR REPLACE FUNCTION app.recompute_all_user_unit_access(p_source text DEFAULT 'migration')
+RETURNS TABLE (tenant_id uuid, added integer, removed integer)
+LANGUAGE plpgsql SECURITY DEFINER
+SET search_path = ''
+AS $$
+DECLARE r record; a integer; d integer;
+BEGIN
+  FOR r IN SELECT t.id FROM public.tenants t LOOP
+    SELECT x.added, x.removed INTO a, d FROM app.recompute_user_unit_access(r.id, p_source) x;
+    tenant_id := r.id; added := a; removed := d;
+    RETURN NEXT;
+  END LOOP;
+END $$;
+
+REVOKE ALL ON FUNCTION app.compute_user_unit_access(uuid, uuid) FROM public;
+REVOKE ALL ON FUNCTION app.refresh_user_unit_access(uuid, uuid) FROM public;
+REVOKE ALL ON FUNCTION app.recompute_user_unit_access(uuid, text) FROM public;
+REVOKE ALL ON FUNCTION app.recompute_all_user_unit_access(text) FROM public;
+GRANT EXECUTE ON FUNCTION app.recompute_user_unit_access(uuid, text) TO service_role;
+GRANT EXECUTE ON FUNCTION app.recompute_all_user_unit_access(text) TO service_role;
+-- An admin may reconcile her own tenant on demand (the function still needs the
+-- membership: it is gated inside the wrapper below).
+CREATE OR REPLACE FUNCTION public.authz_reconcile_my_tenant()
+RETURNS TABLE (added integer, removed integer)
+LANGUAGE plpgsql SECURITY DEFINER
+SET search_path = ''
+AS $$
+DECLARE v_tenant uuid := app.current_tenant_id();
+BEGIN
+  IF v_tenant IS NULL OR NOT app.has_permission('members.manage') THEN
+    RAISE EXCEPTION 'authz_reconcile_my_tenant: not allowed' USING ERRCODE = '42501';
+  END IF;
+  RETURN QUERY SELECT x.added, x.removed FROM app.recompute_user_unit_access(v_tenant, 'manual') x;
+END $$;
+REVOKE ALL ON FUNCTION public.authz_reconcile_my_tenant() FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.authz_reconcile_my_tenant() TO authenticated, service_role;
+
+-- ═════════════════════════════ triggers ═══════════════════════════════════
+
+-- F1 — membership_units
+CREATE OR REPLACE FUNCTION app.trg_membership_units_fanout()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  IF TG_OP IN ('INSERT', 'UPDATE') THEN
+    PERFORM app.refresh_user_unit_access(NEW.tenant_id, NEW.user_id);
+  END IF;
+  IF TG_OP IN ('DELETE', 'UPDATE') AND (TG_OP = 'DELETE' OR OLD.user_id <> NEW.user_id OR OLD.tenant_id <> NEW.tenant_id) THEN
+    PERFORM app.refresh_user_unit_access(OLD.tenant_id, OLD.user_id);
+  END IF;
+  RETURN NULL;
+END $$;
+DROP TRIGGER IF EXISTS membership_units_fanout ON app.membership_units;
+CREATE TRIGGER membership_units_fanout
+  AFTER INSERT OR UPDATE OR DELETE ON app.membership_units
+  FOR EACH ROW EXECUTE FUNCTION app.trg_membership_units_fanout();
+
+-- F2 — memberships (insert / all_units toggle / activate / deactivate / delete)
+CREATE OR REPLACE FUNCTION app.trg_memberships_fanout()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    -- rows go with the FK cascade; nothing to rebuild
+    RETURN NULL;
+  END IF;
+  IF TG_OP = 'INSERT' OR OLD.all_units IS DISTINCT FROM NEW.all_units OR OLD.active IS DISTINCT FROM NEW.active THEN
+    PERFORM app.refresh_user_unit_access(NEW.tenant_id, NEW.user_id);
+  END IF;
+  RETURN NULL;
+END $$;
+DROP TRIGGER IF EXISTS memberships_fanout ON app.memberships;
+CREATE TRIGGER memberships_fanout
+  AFTER INSERT OR UPDATE OR DELETE ON app.memberships
+  FOR EACH ROW EXECUTE FUNCTION app.trg_memberships_fanout();
+
+-- F3 + F4 — units. On insert of an active unit: every all_units member gets it,
+-- and every user with explicit access to an ancestor gets it via subtree — the
+-- classic forgotten case (franchisor opens a branch). On a parent move or an
+-- active flip: rebuild every user whose scope can depend on the tree.
+CREATE OR REPLACE FUNCTION app.trg_units_fanout()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE r record;
+BEGIN
+  IF TG_OP = 'INSERT' AND NOT NEW.active THEN
+    RETURN NULL;
+  END IF;
+  IF TG_OP = 'UPDATE'
+     AND OLD.parent_unit_id IS NOT DISTINCT FROM NEW.parent_unit_id
+     AND OLD.active IS NOT DISTINCT FROM NEW.active THEN
+    RETURN NULL; -- a rename does not change scope
+  END IF;
+  -- Affected: all_units members + anyone holding explicit unit access in the
+  -- tenant (their subtree may have gained/lost this unit). Members with no
+  -- unit access at all cannot be affected.
+  FOR r IN
+    SELECT DISTINCT m.user_id
+      FROM app.memberships m
+     WHERE m.tenant_id = NEW.tenant_id
+       AND (m.all_units OR EXISTS (SELECT 1 FROM app.membership_units mu WHERE mu.tenant_id = m.tenant_id AND mu.user_id = m.user_id))
+  LOOP
+    PERFORM app.refresh_user_unit_access(NEW.tenant_id, r.user_id);
+  END LOOP;
+  RETURN NULL;
+END $$;
+DROP TRIGGER IF EXISTS units_fanout ON app.units;
+CREATE TRIGGER units_fanout
+  AFTER INSERT OR UPDATE ON app.units
+  FOR EACH ROW EXECUTE FUNCTION app.trg_units_fanout();
+
+-- Bring every tenant's share table in line with this migration (a no-op on a
+-- fresh database; on a converted one it is the first reconciliation).
+SELECT app.recompute_all_user_unit_access('migration');

package/migrations/053_authz_catalog_templates.sql

@@ -0,0 +1,402 @@
+-- ============================================================================
+-- 053_authz_catalog_templates.sql — the platform permission catalog, the owner
+-- role that never lags the catalog, vertical role templates, and the business
+-- table scaffold (§4/§7 template as one idempotent function).
+--
+-- A new access rule is a row, not a migration (C6): permissions are seeded by
+-- app.seed_permissions(jsonb) — the platform here, each plugin from its
+-- declaredFeatures (#136) — and role templates are rows in app.role_templates
+-- that app.seed_role_template(tenant, template) instantiates as system roles.
+-- ============================================================================
+
+-- ── seed_permissions(jsonb) ─────────────────────────────────────────────
+-- [{key, plugin, description}] upserted. Called by the platform (below) and by
+-- plugin migrations. Idempotent; never removes a key (removal is a decision).
+CREATE OR REPLACE FUNCTION app.seed_permissions(p_rows jsonb)
+RETURNS integer
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE v_n integer;
+BEGIN
+  WITH ins AS (
+    INSERT INTO app.permissions (key, plugin, description)
+    SELECT r->>'key', r->>'plugin', r->>'description'
+      FROM jsonb_array_elements(p_rows) r
+    ON CONFLICT (key) DO UPDATE SET plugin = EXCLUDED.plugin, description = coalesce(EXCLUDED.description, app.permissions.description)
+    RETURNING 1
+  ) SELECT count(*) INTO v_n FROM ins;
+  RETURN v_n;
+END $$;
+REVOKE ALL ON FUNCTION app.seed_permissions(jsonb) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION app.seed_permissions(jsonb) TO service_role;
+
+-- ── the owner role never lags the catalog ───────────────────────────────
+-- "Owner" is a role with a permission set, not a bypass. So that a plugin
+-- installed tomorrow does not leave every owner without its keys, a new catalog
+-- key is granted to every tenant's system `owner` role on insert.
+CREATE OR REPLACE FUNCTION app.trg_permissions_grant_owner()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  INSERT INTO app.role_permissions (tenant_id, role_id, permission)
+  SELECT r.tenant_id, r.id, NEW.key
+    FROM app.roles r
+   WHERE r.is_system AND r.key = 'owner'
+  ON CONFLICT DO NOTHING;
+  RETURN NULL;
+END $$;
+DROP TRIGGER IF EXISTS permissions_grant_owner ON app.permissions;
+CREATE TRIGGER permissions_grant_owner
+  AFTER INSERT ON app.permissions
+  FOR EACH ROW EXECUTE FUNCTION app.trg_permissions_grant_owner();
+
+-- ── platform catalog (core-A keys) ──────────────────────────────────────
+-- '{feature}.{action}' with actions read/create/edit/delete/manage(+read_all
+-- where owner scoping exists). Plugins add theirs (#136 seeds declaredFeatures).
+SELECT app.seed_permissions('[
+  {"key":"tenant.read","plugin":"platform","description":"See the tenant"},
+  {"key":"tenant.manage","plugin":"platform","description":"Change tenant settings, name, plan"},
+  {"key":"units.read","plugin":"platform","description":"List units"},
+  {"key":"units.manage","plugin":"platform","description":"Create, move, deactivate units"},
+  {"key":"members.read","plugin":"platform","description":"See who is a member and where"},
+  {"key":"members.manage","plugin":"platform","description":"Invite, change role/units, deactivate members"},
+  {"key":"roles.read","plugin":"platform","description":"See roles and their permissions"},
+  {"key":"roles.manage","plugin":"platform","description":"Create and edit tenant roles"},
+  {"key":"authz.grants.manage","plugin":"platform","description":"Write resource grants for any resource type"},
+  {"key":"settings.read","plugin":"platform","description":"Read tenant settings"},
+  {"key":"settings.manage","plugin":"platform","description":"Change tenant settings"},
+  {"key":"billing.manage","plugin":"platform","description":"Plans and payment"},
+  {"key":"audit.read","plugin":"platform","description":"Read the audit log"},
+  {"key":"reports.read","plugin":"reports","description":"Read reports"},
+
+  {"key":"people.read","plugin":"people","description":"Read people in scope"},
+  {"key":"people.read_all","plugin":"people","description":"Read every person of the unit regardless of owner"},
+  {"key":"people.create","plugin":"people"},{"key":"people.edit","plugin":"people"},{"key":"people.delete","plugin":"people"},{"key":"people.manage","plugin":"people"},
+
+  {"key":"catalog.read","plugin":"catalog"},{"key":"catalog.create","plugin":"catalog"},{"key":"catalog.edit","plugin":"catalog"},{"key":"catalog.delete","plugin":"catalog"},{"key":"catalog.manage","plugin":"catalog"},
+
+  {"key":"orders.read","plugin":"orders"},{"key":"orders.read_all","plugin":"orders"},{"key":"orders.create","plugin":"orders"},{"key":"orders.edit","plugin":"orders"},{"key":"orders.delete","plugin":"orders"},{"key":"orders.manage","plugin":"orders"},
+
+  {"key":"agenda.read","plugin":"agenda"},{"key":"agenda.read_all","plugin":"agenda"},{"key":"agenda.create","plugin":"agenda"},{"key":"agenda.edit","plugin":"agenda"},{"key":"agenda.delete","plugin":"agenda"},{"key":"agenda.manage","plugin":"agenda"},
+
+  {"key":"financial.read","plugin":"financial"},{"key":"financial.read_all","plugin":"financial"},{"key":"financial.create","plugin":"financial"},{"key":"financial.edit","plugin":"financial"},{"key":"financial.delete","plugin":"financial"},{"key":"financial.manage","plugin":"financial"},
+  {"key":"financial.cash_session","plugin":"financial","description":"Open/close a cash session (caixinha)"},
+
+  {"key":"inventory.read","plugin":"inventory"},{"key":"inventory.create","plugin":"inventory"},{"key":"inventory.edit","plugin":"inventory"},{"key":"inventory.delete","plugin":"inventory"},{"key":"inventory.manage","plugin":"inventory"}
+]'::jsonb);
+
+-- ── role templates (system roles per vertical) ──────────────────────────
+-- Rows, not code: (template, role_key, role_name, permission). The `owner`
+-- role of every template holds the whole catalog (granted at seed time and kept
+-- current by the trigger above), so it needs no rows here.
+CREATE TABLE IF NOT EXISTS app.role_templates (
+  template   text NOT NULL,
+  role_key   text NOT NULL,
+  role_name  text NOT NULL,
+  sort_order integer NOT NULL DEFAULT 0,
+  permission text NOT NULL REFERENCES app.permissions(key) ON DELETE CASCADE,
+  PRIMARY KEY (template, role_key, permission)
+);
+ALTER TABLE app.role_templates ENABLE ROW LEVEL SECURITY;
+GRANT SELECT ON app.role_templates TO authenticated;
+DROP POLICY IF EXISTS role_templates_select ON app.role_templates;
+CREATE POLICY role_templates_select ON app.role_templates FOR SELECT TO authenticated USING (true);
+
+CREATE OR REPLACE FUNCTION app.seed_role_template_rows(p_template text, p_role_key text, p_role_name text, p_sort integer, p_perms text[])
+RETURNS void LANGUAGE sql SECURITY DEFINER SET search_path = '' AS $$
+  INSERT INTO app.role_templates (template, role_key, role_name, sort_order, permission)
+  SELECT p_template, p_role_key, p_role_name, p_sort, unnest(p_perms)
+  ON CONFLICT DO NOTHING;
+$$;
+REVOKE ALL ON FUNCTION app.seed_role_template_rows(text, text, text, integer, text[]) FROM public, anon, authenticated;
+
+-- generic — the SDK's historical five (owner/admin/manager/staff/viewer), the
+-- target of the tenant_members role mapping in #134.
+SELECT app.seed_role_template_rows('generic', 'admin', 'Administrator', 1, ARRAY[
+  'tenant.read','units.read','units.manage','members.read','members.manage','roles.read','roles.manage','settings.read','settings.manage','audit.read','reports.read',
+  'people.manage','catalog.manage','orders.manage','agenda.manage','financial.manage','inventory.manage']);
+SELECT app.seed_role_template_rows('generic', 'manager', 'Manager', 2, ARRAY[
+  'tenant.read','units.read','members.read','roles.read','settings.read','reports.read',
+  'people.manage','catalog.manage','orders.manage','agenda.manage','financial.manage','inventory.manage']);
+SELECT app.seed_role_template_rows('generic', 'staff', 'Staff', 3, ARRAY[
+  'tenant.read','units.read','people.read','people.create','people.edit','catalog.read','orders.read','orders.create','orders.edit','agenda.read','agenda.create','agenda.edit','inventory.read']);
+SELECT app.seed_role_template_rows('generic', 'viewer', 'Viewer', 4, ARRAY[
+  'tenant.read','units.read','people.read','catalog.read','orders.read','agenda.read','inventory.read','financial.read']);
+
+-- salon (owner_id off in the vertical template)
+SELECT app.seed_role_template_rows('salon', 'manager', 'Gerente', 1, ARRAY[
+  'tenant.read','units.read','members.read','members.manage','roles.read','settings.read','reports.read','audit.read',
+  'people.manage','catalog.manage','orders.manage','agenda.manage','financial.manage','inventory.manage']);
+SELECT app.seed_role_template_rows('salon', 'reception', 'Recepção', 2, ARRAY[
+  'tenant.read','units.read','people.read','people.create','people.edit','catalog.read','orders.read','orders.create','orders.edit','agenda.read','agenda.create','agenda.edit']);
+SELECT app.seed_role_template_rows('salon', 'professional', 'Profissional', 3, ARRAY[
+  'tenant.read','units.read','people.read','catalog.read','orders.read','agenda.read','agenda.edit']);
+SELECT app.seed_role_template_rows('salon', 'financial', 'Financeiro', 4, ARRAY[
+  'tenant.read','units.read','people.read','orders.read','reports.read','financial.manage']);
+
+-- clinic (owner_id on: professionals see their own patients; manager read_all)
+SELECT app.seed_role_template_rows('clinic', 'manager', 'Coordenação', 1, ARRAY[
+  'tenant.read','units.read','members.read','members.manage','roles.read','settings.read','reports.read','audit.read',
+  'people.manage','catalog.manage','orders.manage','agenda.manage','financial.manage','inventory.manage']);
+SELECT app.seed_role_template_rows('clinic', 'reception', 'Recepção', 2, ARRAY[
+  'tenant.read','units.read','people.read','people.create','people.edit','catalog.read','orders.read','orders.create','orders.edit','agenda.read','agenda.create','agenda.edit']);
+SELECT app.seed_role_template_rows('clinic', 'professional', 'Profissional', 3, ARRAY[
+  'tenant.read','units.read','people.read','people.edit','catalog.read','orders.read','agenda.read','agenda.edit']);
+SELECT app.seed_role_template_rows('clinic', 'financial', 'Financeiro', 4, ARRAY[
+  'tenant.read','units.read','people.read','orders.read','reports.read','financial.manage']);
+
+-- restaurant
+SELECT app.seed_role_template_rows('restaurant', 'manager', 'Gerente', 1, ARRAY[
+  'tenant.read','units.read','members.read','members.manage','roles.read','settings.read','reports.read','audit.read',
+  'people.manage','catalog.manage','orders.manage','financial.manage','inventory.manage']);
+SELECT app.seed_role_template_rows('restaurant', 'cashier', 'Caixa', 2, ARRAY[
+  'tenant.read','units.read','people.read','catalog.read','orders.read','orders.edit','financial.read','financial.create','financial.cash_session']);
+SELECT app.seed_role_template_rows('restaurant', 'waiter', 'Garçom', 3, ARRAY[
+  'tenant.read','units.read','people.read','people.create','catalog.read','orders.read','orders.create','orders.edit']);
+SELECT app.seed_role_template_rows('restaurant', 'kitchen', 'Cozinha', 4, ARRAY[
+  'tenant.read','units.read','catalog.read','orders.read','orders.edit','inventory.read']);
+
+-- ── seed_role_template(tenant, template) ────────────────────────────────
+-- Instantiates the template's system roles for a tenant (owner + the rows
+-- above). Idempotent: existing roles are kept, missing permissions added,
+-- nothing removed (a tenant may have tightened a system role on purpose).
+-- Returns the tenant's owner role id.
+CREATE OR REPLACE FUNCTION app.seed_role_template(p_tenant uuid, p_template text DEFAULT 'generic')
+RETURNS uuid
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE v_owner uuid;
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM app.role_templates WHERE template = p_template) THEN
+    RAISE EXCEPTION 'seed_role_template: unknown template %', p_template;
+  END IF;
+
+  INSERT INTO app.roles (tenant_id, key, name, is_system)
+  VALUES (p_tenant, 'owner', 'Owner', true)
+  ON CONFLICT (tenant_id, key) DO NOTHING;
+  SELECT id INTO v_owner FROM app.roles WHERE tenant_id = p_tenant AND key = 'owner';
+
+  INSERT INTO app.role_permissions (tenant_id, role_id, permission)
+  SELECT p_tenant, v_owner, p.key FROM app.permissions p
+  ON CONFLICT DO NOTHING;
+
+  INSERT INTO app.roles (tenant_id, key, name, is_system)
+  SELECT DISTINCT ON (t.role_key) p_tenant, t.role_key, t.role_name, true
+    FROM app.role_templates t WHERE t.template = p_template
+   ORDER BY t.role_key
+  ON CONFLICT (tenant_id, key) DO NOTHING;
+
+  INSERT INTO app.role_permissions (tenant_id, role_id, permission)
+  SELECT p_tenant, r.id, t.permission
+    FROM app.role_templates t
+    JOIN app.roles r ON r.tenant_id = p_tenant AND r.key = t.role_key
+   WHERE t.template = p_template
+  ON CONFLICT DO NOTHING;
+
+  RETURN v_owner;
+END $$;
+REVOKE ALL ON FUNCTION app.seed_role_template(uuid, text) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION app.seed_role_template(uuid, text) TO service_role;
+
+-- ═════════════════════ business-table scaffold (§4 + §7) ═════════════════
+-- app.scaffold_table(table, resource_type, plugin, owner_scoping, mode)
+--
+-- Stamps a table with the three structural columns, unique(tenant_id, id),
+-- the composite FKs, tenant-first indexes, enable+force RLS, the updated_at
+-- trigger and the ONE policy template every business table gets:
+--
+--   select  tenant = current ∧ (unit null ∨ has_unit) ∧ (owner null ∨ owner = me ∨
+--           shared_with grant ∨ {plugin}.read_all) ∧ {plugin}.read
+--   insert  tenant/unit as above ∧ {plugin}.create
+--   update  select-scope ∧ {plugin}.edit (using + with check)
+--   delete  select-scope ∧ {plugin}.delete
+--
+-- Vertical differences are configuration: the policy text is identical whether
+-- the vertical fills owner_id (clinic) or leaves it null (salon); owner_scoping
+-- is recorded so a template can say which. mode='enforce' replaces every
+-- pre-existing policy on the table with the template; mode='shadow' keeps them
+-- and adds the template ones (permissive policies OR together, so shadow adds no
+-- restriction) — app.shadow_report (#135) then compares old vs new decisions.
+CREATE TABLE IF NOT EXISTS app.scaffold_registry (
+  table_schema  text NOT NULL,
+  table_name    text NOT NULL,
+  resource_type text NOT NULL,
+  plugin        text NOT NULL,
+  owner_scoping boolean NOT NULL DEFAULT true,
+  mode          text NOT NULL CHECK (mode IN ('shadow', 'enforce')),
+  previous_policies text[] NOT NULL DEFAULT '{}',
+  applied_at    timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (table_schema, table_name)
+);
+ALTER TABLE app.scaffold_registry ENABLE ROW LEVEL SECURITY;
+GRANT SELECT ON app.scaffold_registry TO authenticated;
+DROP POLICY IF EXISTS scaffold_registry_select ON app.scaffold_registry;
+CREATE POLICY scaffold_registry_select ON app.scaffold_registry FOR SELECT TO authenticated USING (true);
+
+CREATE OR REPLACE FUNCTION app.scaffold_table(
+  p_table regclass,
+  p_resource_type text,
+  p_plugin text,
+  p_owner_scoping boolean DEFAULT true,
+  p_mode text DEFAULT 'enforce'
+)
+RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_schema text;
+  v_name   text;
+  v_q      text;   -- quoted qualified name
+  v_prev   text[] := '{}';
+  v_rows   bigint;
+  r        record;
+  v_scope  text;   -- the row-scope predicate shared by every policy
+BEGIN
+  IF p_mode NOT IN ('shadow', 'enforce') THEN
+    RAISE EXCEPTION 'scaffold_table: mode must be shadow|enforce';
+  END IF;
+  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;
+  v_q := format('%I.%I', v_schema, v_name);
+
+  -- ── columns
+  IF NOT EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = v_schema AND table_name = v_name AND column_name = 'id') THEN
+    RAISE EXCEPTION 'scaffold_table: % has no id column', v_q;
+  END IF;
+  EXECUTE format('SELECT count(*) FROM %s', v_q) INTO v_rows;
+  IF NOT EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = v_schema AND table_name = v_name AND column_name = 'tenant_id') THEN
+    EXECUTE format('ALTER TABLE %s ADD COLUMN tenant_id uuid REFERENCES public.tenants(id) ON DELETE CASCADE', v_q);
+    IF v_rows = 0 THEN EXECUTE format('ALTER TABLE %s ALTER COLUMN tenant_id SET NOT NULL', v_q); END IF;
+  END IF;
+  EXECUTE format('ALTER TABLE %s ADD COLUMN IF NOT EXISTS unit_id uuid', v_q);
+  EXECUTE format('ALTER TABLE %s ADD COLUMN IF NOT EXISTS owner_id uuid', v_q);
+  EXECUTE format('ALTER TABLE %s ADD COLUMN IF NOT EXISTS created_at timestamptz NOT NULL DEFAULT now()', v_q);
+  EXECUTE format('ALTER TABLE %s ADD COLUMN IF NOT EXISTS updated_at timestamptz NOT NULL DEFAULT now()', v_q);
+
+  -- ── unique(tenant_id, id) — enables composite FKs from other tables
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = p_table AND conname = v_name || '_tenant_id_id_key') THEN
+    EXECUTE format('ALTER TABLE %s ADD CONSTRAINT %I UNIQUE (tenant_id, id)', v_q, v_name || '_tenant_id_id_key');
+  END IF;
+  -- ── composite FKs: unit within tenant, owner a member of the tenant
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = p_table AND conname = v_name || '_unit_fk') THEN
+    EXECUTE format('ALTER TABLE %s ADD CONSTRAINT %I FOREIGN KEY (tenant_id, unit_id) REFERENCES app.units(tenant_id, id) ON DELETE SET NULL', v_q, v_name || '_unit_fk');
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = p_table AND conname = v_name || '_owner_fk') THEN
+    EXECUTE format('ALTER TABLE %s ADD CONSTRAINT %I FOREIGN KEY (tenant_id, owner_id) REFERENCES app.memberships(tenant_id, user_id) ON DELETE SET NULL', v_q, v_name || '_owner_fk');
+  END IF;
+
+  -- ── tenant-first indexes
+  EXECUTE format('CREATE INDEX IF NOT EXISTS %I ON %s (tenant_id, unit_id)', v_name || '_tenant_unit_idx', v_q);
+  EXECUTE format('CREATE INDEX IF NOT EXISTS %I ON %s (tenant_id, owner_id) WHERE owner_id IS NOT NULL', v_name || '_tenant_owner_idx', v_q);
+
+  -- ── updated_at
+  EXECUTE format('DROP TRIGGER IF EXISTS %I ON %s', v_name || '_updated_at', v_q);
+  EXECUTE format('CREATE TRIGGER %I BEFORE UPDATE ON %s FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at()', v_name || '_updated_at', v_q);
+
+  -- ── RLS
+  EXECUTE format('ALTER TABLE %s ENABLE ROW LEVEL SECURITY', v_q);
+  EXECUTE format('ALTER TABLE %s FORCE ROW LEVEL SECURITY', v_q);
+  IF p_mode = 'enforce' THEN
+    FOR r IN SELECT policyname FROM pg_policies WHERE schemaname = v_schema AND tablename = v_name
+             AND policyname NOT IN (v_name || '_authz_select', v_name || '_authz_insert', v_name || '_authz_update', v_name || '_authz_delete') LOOP
+      v_prev := v_prev || r.policyname;
+      EXECUTE format('DROP POLICY IF EXISTS %I ON %s', r.policyname, v_q);
+    END LOOP;
+  END IF;
+
+  v_scope := format(
+    'tenant_id = (select app.current_tenant_id())'
+    || ' AND (unit_id IS NULL OR (select app.has_unit(unit_id)))'
+    || ' AND (owner_id IS NULL OR owner_id = (select auth.uid())'
+    ||      ' OR (select app.has_grant(%L, id, ARRAY[''shared_with'']))'
+    ||      ' OR (select app.has_permission(%L, unit_id)))',
+    p_resource_type, p_plugin || '.read_all');
+
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_select', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR SELECT TO authenticated USING (%s AND (select app.has_permission(%L, unit_id)))',
+                 v_name || '_authz_select', v_q, v_scope, p_plugin || '.read');
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_insert', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR INSERT TO authenticated WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (unit_id IS NULL OR (select app.has_unit(unit_id))) AND (select app.has_permission(%L, unit_id)))',
+                 v_name || '_authz_insert', v_q, p_plugin || '.create');
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_update', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR UPDATE TO authenticated USING (%s AND (select app.has_permission(%L, unit_id))) WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (unit_id IS NULL OR (select app.has_unit(unit_id))) AND (select app.has_permission(%L, unit_id)))',
+                 v_name || '_authz_update', v_q, v_scope, p_plugin || '.edit', p_plugin || '.edit');
+  EXECUTE format('DROP POLICY IF EXISTS %I ON %s', v_name || '_authz_delete', v_q);
+  EXECUTE format('CREATE POLICY %I ON %s FOR DELETE TO authenticated USING (%s AND (select app.has_permission(%L, unit_id)))',
+                 v_name || '_authz_delete', v_q, v_scope, p_plugin || '.delete');
+
+  INSERT INTO app.scaffold_registry (table_schema, table_name, resource_type, plugin, owner_scoping, mode, previous_policies)
+  VALUES (v_schema, v_name, p_resource_type, p_plugin, p_owner_scoping, p_mode, v_prev)
+  ON CONFLICT (table_schema, table_name) DO UPDATE
+    SET resource_type = EXCLUDED.resource_type, plugin = EXCLUDED.plugin, owner_scoping = EXCLUDED.owner_scoping,
+        mode = EXCLUDED.mode, applied_at = now(),
+        previous_policies = CASE WHEN EXCLUDED.mode = 'enforce' AND app.scaffold_registry.mode = 'shadow'
+                                 THEN app.scaffold_registry.previous_policies || EXCLUDED.previous_policies
+                                 ELSE EXCLUDED.previous_policies END;
+END $$;
+REVOKE ALL ON FUNCTION app.scaffold_table(regclass, text, text, boolean, text) FROM public, anon, authenticated;
+
+-- ═════════════════════ read views for the UI (public.v_authz_*) ═══════════
+-- security_invoker: the caller's RLS on the app tables decides what she sees.
+CREATE OR REPLACE VIEW public.v_authz_units WITH (security_invoker = true) AS
+  SELECT tenant_id, id, kind, parent_unit_id, name, slug, active, company_legal_entity_id, metadata, created_at, updated_at FROM app.units;
+CREATE OR REPLACE VIEW public.v_authz_roles WITH (security_invoker = true) AS
+  SELECT tenant_id, id, key, name, description, is_system, created_at, updated_at FROM app.roles;
+CREATE OR REPLACE VIEW public.v_authz_permissions WITH (security_invoker = true) AS
+  SELECT key, plugin, description FROM app.permissions;
+CREATE OR REPLACE VIEW public.v_authz_role_permissions WITH (security_invoker = true) AS
+  SELECT tenant_id, role_id, permission FROM app.role_permissions;
+CREATE OR REPLACE VIEW public.v_authz_memberships WITH (security_invoker = true) AS
+  SELECT tenant_id, user_id, id, role_id, all_units, active, person_id, invited_by, created_at, updated_at FROM app.memberships;
+CREATE OR REPLACE VIEW public.v_authz_membership_units WITH (security_invoker = true) AS
+  SELECT tenant_id, user_id, unit_id, role_override_id, created_at FROM app.membership_units;
+CREATE OR REPLACE VIEW public.v_authz_user_unit_access WITH (security_invoker = true) AS
+  SELECT tenant_id, user_id, unit_id, via FROM app.user_unit_access;
+CREATE OR REPLACE VIEW public.v_authz_resource_grants WITH (security_invoker = true) AS
+  SELECT tenant_id, resource_type, resource_id, relation, subject_type, subject_id, created_by, created_at FROM app.resource_grants;
+CREATE OR REPLACE VIEW public.v_authz_role_templates WITH (security_invoker = true) AS
+  SELECT template, role_key, role_name, sort_order, permission FROM app.role_templates;
+-- Reconciliation runs whose diff was not zero outside a migration: the alert.
+CREATE OR REPLACE VIEW public.v_authz_reconciliation_alerts WITH (security_invoker = true) AS
+  SELECT id, tenant_id, run_at, source, added, removed, details
+    FROM app.authz_reconciliation_log
+   WHERE source <> 'migration' AND (added <> 0 OR removed <> 0);
+GRANT SELECT ON public.v_authz_units, public.v_authz_roles, public.v_authz_permissions, public.v_authz_role_permissions,
+                public.v_authz_memberships, public.v_authz_membership_units, public.v_authz_user_unit_access,
+                public.v_authz_resource_grants, public.v_authz_role_templates, public.v_authz_reconciliation_alerts
+  TO authenticated, service_role;
+-- The simple views over one table are auto-updatable: writes through them hit
+-- the write policies of 041 (units/roles/role_permissions/memberships/units/grants).
+GRANT INSERT, UPDATE, DELETE ON public.v_authz_units, public.v_authz_roles, public.v_authz_role_permissions,
+                                public.v_authz_memberships, public.v_authz_membership_units, public.v_authz_resource_grants
+  TO authenticated, service_role;
+
+-- ── the session's authz context, once per session per unit (§8) ─────────
+CREATE OR REPLACE FUNCTION public.authz_my_permissions(p_unit uuid DEFAULT NULL)
+RETURNS SETOF text
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = ''
+AS $$
+  SELECT rp.permission
+    FROM app.role_permissions rp
+   WHERE rp.tenant_id = app.current_tenant_id()
+     AND rp.role_id = app.effective_role_id(app.current_tenant_id(), auth.uid(), p_unit)
+   ORDER BY 1;
+$$;
+CREATE OR REPLACE FUNCTION public.authz_context()
+RETURNS jsonb
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = ''
+AS $$
+  SELECT jsonb_build_object(
+    'tenant_id', app.current_tenant_id(),
+    'user_id', auth.uid(),
+    'role_key', (SELECT r.key FROM app.memberships m JOIN app.roles r ON r.tenant_id = m.tenant_id AND r.id = m.role_id
+                  WHERE m.tenant_id = app.current_tenant_id() AND m.user_id = auth.uid() AND m.active),
+    'all_units', (SELECT m.all_units FROM app.memberships m WHERE m.tenant_id = app.current_tenant_id() AND m.user_id = auth.uid() AND m.active),
+    'units', coalesce((SELECT jsonb_agg(jsonb_build_object('unit_id', a.unit_id, 'via', a.via) ORDER BY a.unit_id)
+                         FROM app.user_unit_access a WHERE a.tenant_id = app.current_tenant_id() AND a.user_id = auth.uid()), '[]'::jsonb),
+    'permissions', coalesce((SELECT jsonb_agg(p ORDER BY p) FROM public.authz_my_permissions(NULL) p), '[]'::jsonb)
+  );
+$$;
+REVOKE ALL ON FUNCTION public.authz_my_permissions(uuid) FROM public, anon;
+REVOKE ALL ON FUNCTION public.authz_context() FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.authz_my_permissions(uuid) TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.authz_context() TO authenticated, service_role;