@fayz-ai/db 0.12.0 → 0.13.0

package/migrations/063_legacy_tenancy_retired.sql

@@ -0,0 +1,568 @@
+-- ============================================================================
+-- 063_legacy_tenancy_retired.sql — tenant_members / locations / location_members
+-- stop being sources of truth (#134). They become COMPAT PROJECTIONS of
+-- app.memberships / app.units / app.membership_units.
+--
+-- WHY PROJECTION TABLES AND NOT VIEWS. The retirement was designed as views;
+-- the bench proved that shape impossible in this repo: frozen migrations
+-- (001, 019, 023 …) re-run on every force replay and execute
+-- `ALTER TABLE public.tenant_members ENABLE ROW LEVEL SECURITY`,
+-- `ADD COLUMN IF NOT EXISTS`, `CREATE POLICY … ON public.tenant_members` —
+-- every one of which ERRORS on a view ("This operation is not supported for
+-- views"), and plugin-blog 002 declares a FOREIGN KEY to tenant_members(id)
+-- and 004 declares FKs to locations(id), which a view cannot satisfy. Applied
+-- migrations are never edited, so the names must stay physical tables. What
+-- changes is who writes them:
+--
+--   * app.* is the ONLY source of truth. Triggers on app.memberships,
+--     app.membership_units, app.units and app.roles rebuild the projection rows
+--     (same ids: tenant_members.id = memberships.id, locations.id = units.id).
+--   * A write to a projection table by an API role is FORWARDED to app.* by a
+--     BEFORE trigger (as the invoker, so the app.* RLS policies decide), and
+--     the projection row is materialised by the same statement only when the
+--     forwarded write happened — the admin adapter's UPDATE role / DELETE
+--     member / INSERT location keep working, and RETURNING keeps returning.
+--       tenant_members INSERT   → app.memberships INSERT (members.manage; never self)
+--       tenant_members UPDATE   → memberships.role_id / person_id (never your own role)
+--       tenant_members DELETE   → memberships.active = false (history is kept)
+--       locations INSERT/UPDATE/DELETE → app.units (units.manage); legacy scalar
+--                                 columns travel in units.metadata
+--       location_members INSERT/DELETE → app.membership_units (members.manage)
+--   * The projection tables' policies are re-authored onto app.* helpers; the
+--     legacy self-insert policy (members_insert_own — the old model's P0) is
+--     dropped. On a force replay 001 re-creates it and this file drops it again.
+--
+-- DATA MIGRATION (idempotent, replay-safe): every legacy row that has no app.*
+-- counterpart is migrated once — tenant_members → memberships (role key mapped
+-- through the 'generic' template: owner/admin/manager/staff/viewer keep their
+-- key, anything else → staff, falling back to viewer, then to the least
+-- privileged non-owner system role; the tenant's roles are seeded from
+-- 'generic' first when it has none), locations → units (the first
+-- is_headquarters row → hq, the rest → branch; a tenant left without an hq
+-- gets its earliest unit promoted or, having none, an hq named after the
+-- tenant), location_members → membership_units (only for users who hold a
+-- membership; owners get all_units). Then app.compat_rebuild() re-derives the
+-- three projections completely.
+--
+-- Custom role grants of the legacy tenant_role_overrides / tenant_roles are
+-- NOT translated here — that is #136's mapping. public.permissions,
+-- role_permissions, tenant_role_overrides and tenant_roles are left in place.
+-- ============================================================================
+
+-- ─────────────────────────── helpers ────────────────────────────────────
+-- Two transaction-local switches:
+--   fayz.compat_sync    = 'on' while the projection is being (re)written from
+--                         app.* — the forwarding triggers let the row through.
+--   fayz.compat_forward = 'on' while a forwarding trigger writes app.* — the
+--                         sync triggers stay quiet; the outer statement
+--                         materialises the projection row itself.
+CREATE OR REPLACE FUNCTION app.compat_flag(p_name text)
+RETURNS boolean LANGUAGE sql STABLE SET search_path = '' AS $$
+  SELECT coalesce(current_setting('fayz.compat_' || p_name, true), '') = 'on';
+$$;
+REVOKE ALL ON FUNCTION app.compat_flag(text) FROM public, anon;
+GRANT EXECUTE ON FUNCTION app.compat_flag(text) TO authenticated, service_role;
+
+CREATE OR REPLACE FUNCTION app.compat_role_id(p_tenant uuid, p_key text)
+RETURNS uuid LANGUAGE sql STABLE SECURITY DEFINER SET search_path = '' AS $$
+  SELECT r.id FROM app.roles r WHERE r.tenant_id = p_tenant AND r.key = p_key;
+$$;
+REVOKE ALL ON FUNCTION app.compat_role_id(uuid, text) FROM public, anon;
+GRANT EXECUTE ON FUNCTION app.compat_role_id(uuid, text) TO authenticated, service_role;
+
+CREATE OR REPLACE FUNCTION app.compat_uuid(p_text text)
+RETURNS uuid LANGUAGE sql IMMUTABLE SET search_path = '' AS $$
+  SELECT CASE WHEN p_text ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' THEN p_text::uuid END;
+$$;
+REVOKE ALL ON FUNCTION app.compat_uuid(text) FROM public, anon;
+GRANT EXECUTE ON FUNCTION app.compat_uuid(text) TO authenticated, service_role;
+
+-- The legacy role-key mapping used by the data migration only.
+CREATE OR REPLACE FUNCTION app.compat_legacy_role_id(p_tenant uuid, p_key text)
+RETURNS uuid LANGUAGE sql STABLE SECURITY DEFINER SET search_path = '' AS $$
+  SELECT coalesce(
+    app.compat_role_id(p_tenant, p_key),
+    app.compat_role_id(p_tenant, CASE p_key WHEN 'owner' THEN 'owner' WHEN 'admin' THEN 'admin' WHEN 'manager' THEN 'manager'
+                                          WHEN 'staff' THEN 'staff' WHEN 'viewer' THEN 'viewer' ELSE 'staff' END),
+    app.compat_role_id(p_tenant, 'viewer'),
+    (SELECT r.id FROM app.roles r
+       LEFT JOIN app.role_permissions rp ON rp.tenant_id = r.tenant_id AND rp.role_id = r.id
+      WHERE r.tenant_id = p_tenant AND r.is_system AND r.key <> 'owner'
+      GROUP BY r.id, r.key ORDER BY count(rp.permission), r.key LIMIT 1)
+  );
+$$;
+REVOKE ALL ON FUNCTION app.compat_legacy_role_id(uuid, text) FROM public, anon, authenticated;
+
+-- ── projection writers (SECURITY DEFINER: they write the legacy tables as the
+--    migration role; the forwarding triggers see fayz.compat_sync = on) ─────
+CREATE OR REPLACE FUNCTION app.compat_sync_membership(p_tenant uuid, p_user uuid)
+RETURNS void LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE m record;
+BEGIN
+  PERFORM set_config('fayz.compat_sync', 'on', true);
+  SELECT ms.id, ms.tenant_id, ms.user_id, ms.role_id, ms.person_id, ms.created_at, ms.active,
+         r.key AS role_key
+    INTO m
+    FROM app.memberships ms
+    JOIN app.roles r ON r.tenant_id = ms.tenant_id AND r.id = ms.role_id
+   WHERE ms.tenant_id = p_tenant AND ms.user_id = p_user;
+
+  IF m.id IS NULL OR NOT m.active THEN
+    DELETE FROM public.location_members lm
+     WHERE lm.user_id = p_user
+       AND lm.location_id IN (SELECT u.id FROM app.units u WHERE u.tenant_id = p_tenant);
+    DELETE FROM public.tenant_members tm WHERE tm.tenant_id = p_tenant AND tm.user_id = p_user;
+  ELSE
+    -- a stale row for the same (tenant, user) under another id would collide
+    DELETE FROM public.tenant_members tm
+     WHERE tm.tenant_id = p_tenant AND tm.user_id = p_user AND tm.id <> m.id;
+    INSERT INTO public.tenant_members (id, tenant_id, user_id, role, person_id, created_at)
+    VALUES (m.id, m.tenant_id, m.user_id, m.role_key,
+            -- the legacy unique (tenant_id, person_id) must hold
+            CASE WHEN EXISTS (SELECT 1 FROM public.tenant_members x
+                               WHERE x.tenant_id = m.tenant_id AND x.person_id = m.person_id AND x.id <> m.id)
+                 THEN NULL ELSE m.person_id END,
+            m.created_at)
+    ON CONFLICT (id) DO UPDATE
+      SET tenant_id = EXCLUDED.tenant_id, user_id = EXCLUDED.user_id, role = EXCLUDED.role,
+          person_id = EXCLUDED.person_id, created_at = EXCLUDED.created_at;
+
+    DELETE FROM public.location_members lm
+     WHERE lm.user_id = p_user
+       AND lm.location_id IN (SELECT u.id FROM app.units u WHERE u.tenant_id = p_tenant)
+       AND NOT EXISTS (SELECT 1 FROM app.membership_units mu
+                        WHERE mu.tenant_id = p_tenant AND mu.user_id = p_user AND mu.unit_id = lm.location_id);
+    INSERT INTO public.location_members (location_id, user_id, role)
+    SELECT mu.unit_id, mu.user_id, coalesce(ro.key, m.role_key)
+      FROM app.membership_units mu
+      LEFT JOIN app.roles ro ON ro.tenant_id = mu.tenant_id AND ro.id = mu.role_override_id
+     WHERE mu.tenant_id = p_tenant AND mu.user_id = p_user
+       AND EXISTS (SELECT 1 FROM public.locations l WHERE l.id = mu.unit_id)
+    ON CONFLICT (location_id, user_id) DO UPDATE SET role = EXCLUDED.role;
+  END IF;
+  PERFORM set_config('fayz.compat_sync', 'off', true);
+END $$;
+REVOKE ALL ON FUNCTION app.compat_sync_membership(uuid, uuid) FROM public, anon, authenticated;
+
+CREATE OR REPLACE FUNCTION app.compat_sync_unit(p_unit uuid)
+RETURNS void LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE u record;
+BEGIN
+  PERFORM set_config('fayz.compat_sync', 'on', true);
+  SELECT * INTO u FROM app.units x WHERE x.id = p_unit;
+  IF u.id IS NULL THEN
+    DELETE FROM public.locations l WHERE l.id = p_unit;
+  ELSE
+    INSERT INTO public.locations
+           (id, tenant_id, kind, name, email, phone, address, city, state, country, postal_code,
+            is_headquarters, is_active, tags, notes, metadata, custom_fields, created_by, created_at, updated_at,
+            parent_id, code)
+    VALUES (u.id, u.tenant_id, coalesce(u.metadata ->> 'legacy_kind', u.kind), u.name,
+            u.metadata ->> 'email', u.metadata ->> 'phone', u.metadata ->> 'address',
+            u.metadata ->> 'city', u.metadata ->> 'state', coalesce(u.metadata ->> 'country', 'BR'),
+            u.metadata ->> 'postal_code',
+            u.kind = 'hq', u.active,
+            coalesce((SELECT array_agg(t) FROM jsonb_array_elements_text(CASE WHEN jsonb_typeof(u.metadata -> 'tags') = 'array' THEN u.metadata -> 'tags' ELSE '[]'::jsonb END) t), '{}'::text[]),
+            u.metadata ->> 'notes',
+            u.metadata,
+            CASE WHEN jsonb_typeof(u.metadata -> 'custom_fields') = 'object' THEN u.metadata -> 'custom_fields' ELSE '{}'::jsonb END,
+            app.compat_uuid(u.metadata ->> 'created_by'),
+            u.created_at, u.updated_at,
+            -- main's 039 gave locations a tree; the projection carries it, or the
+            -- units UI reads a flat list and 064b nulls the real tree on replay
+            u.parent_unit_id, u.metadata ->> 'code')
+    ON CONFLICT (id) DO UPDATE
+      SET tenant_id = EXCLUDED.tenant_id, kind = EXCLUDED.kind, name = EXCLUDED.name, email = EXCLUDED.email,
+          phone = EXCLUDED.phone, address = EXCLUDED.address, city = EXCLUDED.city, state = EXCLUDED.state,
+          country = EXCLUDED.country, postal_code = EXCLUDED.postal_code, is_headquarters = EXCLUDED.is_headquarters,
+          is_active = EXCLUDED.is_active, tags = EXCLUDED.tags, notes = EXCLUDED.notes, metadata = EXCLUDED.metadata,
+          custom_fields = EXCLUDED.custom_fields, created_by = EXCLUDED.created_by, updated_at = EXCLUDED.updated_at,
+          parent_id = EXCLUDED.parent_id, code = EXCLUDED.code;
+    -- created_by is stamped by the legacy trigger from auth.uid() when null; keep it null-safe.
+  END IF;
+  PERFORM set_config('fayz.compat_sync', 'off', true);
+END $$;
+REVOKE ALL ON FUNCTION app.compat_sync_unit(uuid) FROM public, anon, authenticated;
+
+-- Full re-derivation of the three projections (used by this migration and
+-- available to reconciliation). Deletes what app.* no longer has, upserts the rest.
+CREATE OR REPLACE FUNCTION app.compat_rebuild()
+RETURNS TABLE (n_tenant_members integer, n_locations integer, n_location_members integer)
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE r record;
+BEGIN
+  PERFORM set_config('fayz.compat_sync', 'on', true);
+  DELETE FROM public.location_members lm
+   WHERE NOT EXISTS (SELECT 1 FROM app.membership_units mu
+                       JOIN app.memberships m ON m.tenant_id = mu.tenant_id AND m.user_id = mu.user_id AND m.active
+                      WHERE mu.unit_id = lm.location_id AND mu.user_id = lm.user_id);
+  DELETE FROM public.tenant_members tm
+   WHERE NOT EXISTS (SELECT 1 FROM app.memberships m WHERE m.id = tm.id AND m.active);
+  DELETE FROM public.locations l
+   WHERE NOT EXISTS (SELECT 1 FROM app.units u WHERE u.id = l.id);
+  PERFORM set_config('fayz.compat_sync', 'off', true);
+  FOR r IN SELECT u.id FROM app.units u LOOP
+    PERFORM app.compat_sync_unit(r.id);
+  END LOOP;
+  FOR r IN SELECT m.tenant_id, m.user_id FROM app.memberships m LOOP
+    PERFORM app.compat_sync_membership(r.tenant_id, r.user_id);
+  END LOOP;
+  SELECT count(*)::integer INTO n_tenant_members FROM public.tenant_members;
+  SELECT count(*)::integer INTO n_locations FROM public.locations;
+  SELECT count(*)::integer INTO n_location_members FROM public.location_members;
+  RETURN NEXT;
+END $$;
+REVOKE ALL ON FUNCTION app.compat_rebuild() FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION app.compat_rebuild() TO service_role;
+
+-- ── sync triggers on app.* ──────────────────────────────────────────────
+CREATE OR REPLACE FUNCTION app.trg_memberships_compat()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  IF app.compat_flag('forward') THEN RETURN NULL; END IF;
+  IF TG_OP = 'DELETE' THEN
+    PERFORM app.compat_sync_membership(OLD.tenant_id, OLD.user_id);
+  ELSE
+    IF TG_OP = 'UPDATE' AND (OLD.tenant_id <> NEW.tenant_id OR OLD.user_id <> NEW.user_id) THEN
+      PERFORM app.compat_sync_membership(OLD.tenant_id, OLD.user_id);
+    END IF;
+    PERFORM app.compat_sync_membership(NEW.tenant_id, NEW.user_id);
+  END IF;
+  RETURN NULL;
+END $$;
+DROP TRIGGER IF EXISTS memberships_compat ON app.memberships;
+CREATE TRIGGER memberships_compat
+  AFTER INSERT OR UPDATE OR DELETE ON app.memberships
+  FOR EACH ROW EXECUTE FUNCTION app.trg_memberships_compat();
+
+CREATE OR REPLACE FUNCTION app.trg_membership_units_compat()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  IF app.compat_flag('forward') THEN RETURN NULL; END IF;
+  IF TG_OP IN ('DELETE', 'UPDATE') THEN
+    PERFORM app.compat_sync_membership(OLD.tenant_id, OLD.user_id);
+  END IF;
+  IF TG_OP IN ('INSERT', 'UPDATE') AND (TG_OP = 'INSERT' OR OLD.tenant_id <> NEW.tenant_id OR OLD.user_id <> NEW.user_id) THEN
+    PERFORM app.compat_sync_membership(NEW.tenant_id, NEW.user_id);
+  END IF;
+  RETURN NULL;
+END $$;
+DROP TRIGGER IF EXISTS membership_units_compat ON app.membership_units;
+CREATE TRIGGER membership_units_compat
+  AFTER INSERT OR UPDATE OR DELETE ON app.membership_units
+  FOR EACH ROW EXECUTE FUNCTION app.trg_membership_units_compat();
+
+CREATE OR REPLACE FUNCTION app.trg_units_compat()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  IF app.compat_flag('forward') THEN RETURN NULL; END IF;
+  IF TG_OP = 'DELETE' THEN
+    PERFORM app.compat_sync_unit(OLD.id);
+  ELSE
+    PERFORM app.compat_sync_unit(NEW.id);
+  END IF;
+  RETURN NULL;
+END $$;
+DROP TRIGGER IF EXISTS units_compat ON app.units;
+CREATE TRIGGER units_compat
+  AFTER INSERT OR UPDATE OR DELETE ON app.units
+  FOR EACH ROW EXECUTE FUNCTION app.trg_units_compat();
+
+-- a role key rename must show in tenant_members.role / location_members.role
+CREATE OR REPLACE FUNCTION app.trg_roles_compat()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE r record;
+BEGIN
+  IF OLD.key IS DISTINCT FROM NEW.key THEN
+    FOR r IN SELECT m.tenant_id, m.user_id FROM app.memberships m WHERE m.tenant_id = NEW.tenant_id AND m.role_id = NEW.id
+             UNION SELECT mu.tenant_id, mu.user_id FROM app.membership_units mu WHERE mu.tenant_id = NEW.tenant_id AND mu.role_override_id = NEW.id
+    LOOP
+      PERFORM app.compat_sync_membership(r.tenant_id, r.user_id);
+    END LOOP;
+  END IF;
+  RETURN NULL;
+END $$;
+DROP TRIGGER IF EXISTS roles_compat ON app.roles;
+CREATE TRIGGER roles_compat
+  AFTER UPDATE ON app.roles
+  FOR EACH ROW EXECUTE FUNCTION app.trg_roles_compat();
+
+-- ── forwarding triggers on the projection tables (SECURITY INVOKER: app.* RLS
+--    decides; a write that app.* filters to zero rows changes nothing) ──────
+CREATE OR REPLACE FUNCTION public.trg_tenant_members_forward()
+RETURNS trigger LANGUAGE plpgsql SET search_path = '' AS $$
+DECLARE v_role uuid; v_n integer;
+BEGIN
+  IF app.compat_flag('sync') THEN
+    RETURN CASE WHEN TG_OP = 'DELETE' THEN OLD ELSE NEW END;
+  END IF;
+  PERFORM set_config('fayz.compat_forward', 'on', true);
+  IF TG_OP = 'INSERT' THEN
+    v_role := app.compat_role_id(NEW.tenant_id, NEW.role);
+    IF v_role IS NULL THEN
+      RAISE EXCEPTION 'tenant_members: unknown role key % in this tenant', NEW.role USING ERRCODE = '22023';
+    END IF;
+    NEW.id := coalesce(NEW.id, gen_random_uuid());
+    INSERT INTO app.memberships (tenant_id, user_id, id, role_id, all_units, active, person_id, created_at)
+    VALUES (NEW.tenant_id, NEW.user_id, NEW.id, v_role, false, true, NEW.person_id, coalesce(NEW.created_at, now()));
+    PERFORM set_config('fayz.compat_forward', 'off', true);
+    RETURN NEW;
+  ELSIF TG_OP = 'UPDATE' THEN
+    IF NEW.role IS DISTINCT FROM OLD.role AND OLD.user_id = auth.uid() THEN
+      RAISE EXCEPTION 'tenant_members: you cannot change your own role' USING ERRCODE = '42501';
+    END IF;
+    IF NEW.tenant_id <> OLD.tenant_id OR NEW.user_id <> OLD.user_id OR NEW.id <> OLD.id THEN
+      RAISE EXCEPTION 'tenant_members: tenant, user and id are immutable' USING ERRCODE = '22023';
+    END IF;
+    v_role := app.compat_role_id(NEW.tenant_id, NEW.role);
+    IF v_role IS NULL THEN
+      RAISE EXCEPTION 'tenant_members: unknown role key % in this tenant', NEW.role USING ERRCODE = '22023';
+    END IF;
+    UPDATE app.memberships m SET role_id = v_role, person_id = NEW.person_id WHERE m.id = OLD.id;
+    GET DIAGNOSTICS v_n = ROW_COUNT;
+    PERFORM set_config('fayz.compat_forward', 'off', true);
+    IF v_n = 0 THEN RETURN NULL; END IF;
+    RETURN NEW;
+  ELSE
+    -- removing a member = deactivating the membership (history and FKs survive)
+    UPDATE app.memberships m SET active = false WHERE m.id = OLD.id AND m.active;
+    GET DIAGNOSTICS v_n = ROW_COUNT;
+    PERFORM set_config('fayz.compat_forward', 'off', true);
+    IF v_n = 0 THEN RETURN NULL; END IF;
+    RETURN OLD;
+  END IF;
+END $$;
+REVOKE ALL ON FUNCTION public.trg_tenant_members_forward() FROM public, anon;
+DROP TRIGGER IF EXISTS tenant_members_forward ON public.tenant_members;
+CREATE TRIGGER tenant_members_forward BEFORE INSERT OR UPDATE OR DELETE ON public.tenant_members
+  FOR EACH ROW EXECUTE FUNCTION public.trg_tenant_members_forward();
+
+CREATE OR REPLACE FUNCTION public.trg_locations_forward()
+RETURNS trigger LANGUAGE plpgsql SET search_path = '' AS $$
+DECLARE v_kind text; v_meta jsonb; v_n integer;
+BEGIN
+  IF app.compat_flag('sync') THEN
+    RETURN CASE WHEN TG_OP = 'DELETE' THEN OLD ELSE NEW END;
+  END IF;
+  PERFORM set_config('fayz.compat_forward', 'on', true);
+  IF TG_OP = 'DELETE' THEN
+    DELETE FROM app.units u WHERE u.id = OLD.id;
+    GET DIAGNOSTICS v_n = ROW_COUNT;
+    PERFORM set_config('fayz.compat_forward', 'off', true);
+    IF v_n = 0 THEN RETURN NULL; END IF;
+    RETURN OLD;
+  END IF;
+
+  -- the legacy scalar columns live in units.metadata
+  v_meta := (coalesce(NEW.metadata, '{}'::jsonb)
+             - ARRAY['email', 'phone', 'address', 'city', 'state', 'country', 'postal_code', 'tags', 'notes', 'custom_fields', 'legacy_kind'])
+         || jsonb_strip_nulls(jsonb_build_object(
+              'email', NEW.email, 'phone', NEW.phone, 'address', NEW.address, 'city', NEW.city,
+              'state', NEW.state, 'country', NEW.country, 'postal_code', NEW.postal_code,
+              'tags', CASE WHEN NEW.tags IS NULL OR cardinality(NEW.tags) = 0 THEN NULL ELSE to_jsonb(NEW.tags) END,
+              'notes', NEW.notes,
+              'custom_fields', CASE WHEN NEW.custom_fields IS NULL OR NEW.custom_fields = '{}'::jsonb THEN NULL ELSE NEW.custom_fields END,
+              'created_by', coalesce(NEW.created_by, auth.uid(), app.compat_uuid(NEW.metadata ->> 'created_by')),
+              'legacy_kind', CASE WHEN NEW.kind IN ('hq', 'branch') THEN NULL ELSE NEW.kind END));
+  IF TG_OP = 'INSERT' THEN
+    NEW.id := coalesce(NEW.id, gen_random_uuid());
+    v_kind := CASE WHEN coalesce(NEW.is_headquarters, false) OR NEW.kind = 'hq' THEN 'hq' ELSE 'branch' END;
+    IF v_kind = 'hq' AND EXISTS (SELECT 1 FROM app.units u WHERE u.tenant_id = NEW.tenant_id AND u.kind = 'hq') THEN
+      RAISE EXCEPTION 'locations: the tenant already has a headquarters unit' USING ERRCODE = '23505';
+    END IF;
+    INSERT INTO app.units (tenant_id, id, kind, name, active, metadata, created_at, updated_at)
+    VALUES (NEW.tenant_id, NEW.id, v_kind, NEW.name, coalesce(NEW.is_active, true), v_meta,
+            coalesce(NEW.created_at, now()), coalesce(NEW.updated_at, now()));
+    PERFORM set_config('fayz.compat_forward', 'off', true);
+    NEW.kind := v_kind; NEW.is_headquarters := (v_kind = 'hq'); NEW.is_active := coalesce(NEW.is_active, true);
+    NEW.metadata := v_meta; NEW.country := coalesce(NEW.country, 'BR');
+    RETURN NEW;
+  END IF;
+
+  IF NEW.tenant_id <> OLD.tenant_id OR NEW.id <> OLD.id THEN
+    RAISE EXCEPTION 'locations: tenant and id are immutable' USING ERRCODE = '22023';
+  END IF;
+  v_kind := CASE WHEN coalesce(NEW.is_headquarters, false) OR NEW.kind = 'hq' THEN 'hq' ELSE 'branch' END;
+  UPDATE app.units u
+     SET name = NEW.name, kind = v_kind, active = coalesce(NEW.is_active, true), metadata = v_meta
+   WHERE u.id = OLD.id;
+  GET DIAGNOSTICS v_n = ROW_COUNT;
+  PERFORM set_config('fayz.compat_forward', 'off', true);
+  IF v_n = 0 THEN RETURN NULL; END IF;
+  NEW.kind := v_kind; NEW.is_headquarters := (v_kind = 'hq'); NEW.metadata := v_meta;
+  RETURN NEW;
+END $$;
+REVOKE ALL ON FUNCTION public.trg_locations_forward() FROM public, anon;
+DROP TRIGGER IF EXISTS locations_forward ON public.locations;
+CREATE TRIGGER locations_forward BEFORE INSERT OR UPDATE OR DELETE ON public.locations
+  FOR EACH ROW EXECUTE FUNCTION public.trg_locations_forward();
+
+CREATE OR REPLACE FUNCTION public.trg_location_members_forward()
+RETURNS trigger LANGUAGE plpgsql SET search_path = '' AS $$
+DECLARE v_tenant uuid; v_n integer;
+BEGIN
+  IF app.compat_flag('sync') THEN
+    RETURN CASE WHEN TG_OP = 'DELETE' THEN OLD ELSE NEW END;
+  END IF;
+  PERFORM set_config('fayz.compat_forward', 'on', true);
+  IF TG_OP = 'INSERT' THEN
+    SELECT u.tenant_id INTO v_tenant FROM app.units u WHERE u.id = NEW.location_id;
+    IF v_tenant IS NULL THEN
+      RAISE EXCEPTION 'location_members: unknown location %', NEW.location_id USING ERRCODE = '22023';
+    END IF;
+    INSERT INTO app.membership_units (tenant_id, user_id, unit_id) VALUES (v_tenant, NEW.user_id, NEW.location_id);
+    PERFORM set_config('fayz.compat_forward', 'off', true);
+    NEW.id := coalesce(NEW.id, gen_random_uuid());
+    RETURN NEW;
+  ELSIF TG_OP = 'UPDATE' THEN
+    PERFORM set_config('fayz.compat_forward', 'off', true);
+    RAISE EXCEPTION 'location_members is a compat projection: rows are added and removed, not edited' USING ERRCODE = '0A000';
+  ELSE
+    DELETE FROM app.membership_units mu WHERE mu.unit_id = OLD.location_id AND mu.user_id = OLD.user_id;
+    GET DIAGNOSTICS v_n = ROW_COUNT;
+    PERFORM set_config('fayz.compat_forward', 'off', true);
+    IF v_n = 0 THEN RETURN NULL; END IF;
+    RETURN OLD;
+  END IF;
+END $$;
+REVOKE ALL ON FUNCTION public.trg_location_members_forward() FROM public, anon;
+DROP TRIGGER IF EXISTS location_members_forward ON public.location_members;
+CREATE TRIGGER location_members_forward BEFORE INSERT OR UPDATE OR DELETE ON public.location_members
+  FOR EACH ROW EXECUTE FUNCTION public.trg_location_members_forward();
+
+-- ─────────────────────── data migration (idempotent) ─────────────────────
+DO $migrate$
+DECLARE
+  t   record;
+  l   record;
+  v_has_hq boolean;
+  v_kind text;
+  v_first uuid;
+BEGIN
+  PERFORM set_config('fayz.compat_sync', 'off', true);
+  PERFORM set_config('fayz.compat_forward', 'off', true);
+
+  -- 1. roles for tenants that hold legacy memberships but no roles yet
+  FOR t IN
+    SELECT DISTINCT tm.tenant_id AS id
+      FROM public.tenant_members tm
+     WHERE NOT EXISTS (SELECT 1 FROM app.roles r WHERE r.tenant_id = tm.tenant_id)
+  LOOP
+    PERFORM app.seed_role_template(t.id, 'generic');
+    UPDATE public.tenants SET role_template = coalesce(role_template, 'generic') WHERE id = t.id;
+  END LOOP;
+
+  -- 2. tenant_members → memberships (ids preserved; owner ⇒ all_units)
+  FOR t IN
+    SELECT tm.*
+      FROM public.tenant_members tm
+     WHERE NOT EXISTS (SELECT 1 FROM app.memberships m WHERE m.tenant_id = tm.tenant_id AND m.user_id = tm.user_id)
+       AND EXISTS (SELECT 1 FROM auth.users u WHERE u.id = tm.user_id)
+     ORDER BY tm.created_at, tm.id
+  LOOP
+    DECLARE v_role uuid := app.compat_legacy_role_id(t.tenant_id, t.role);
+    BEGIN
+      IF v_role IS NULL THEN
+        RAISE EXCEPTION 'legacy tenancy: tenant % has no role to receive tenant_members.role = %', t.tenant_id, t.role;
+      END IF;
+      INSERT INTO app.memberships (tenant_id, user_id, id, role_id, all_units, active, person_id, created_at)
+      VALUES (t.tenant_id, t.user_id,
+              CASE WHEN EXISTS (SELECT 1 FROM app.memberships m WHERE m.id = t.id) THEN gen_random_uuid() ELSE t.id END,
+              v_role, t.role = 'owner', true, t.person_id, t.created_at)
+      ON CONFLICT (tenant_id, user_id) DO NOTHING;
+    END;
+  END LOOP;
+
+  -- 3. locations → units (same ids); one hq per tenant
+  FOR t IN SELECT DISTINCT loc.tenant_id AS id FROM public.locations loc
+            WHERE NOT EXISTS (SELECT 1 FROM app.units u WHERE u.id = loc.id)
+  LOOP
+    v_has_hq := EXISTS (SELECT 1 FROM app.units u WHERE u.tenant_id = t.id AND u.kind = 'hq');
+    FOR l IN SELECT * FROM public.locations x
+              WHERE x.tenant_id = t.id AND NOT EXISTS (SELECT 1 FROM app.units u WHERE u.id = x.id)
+              ORDER BY coalesce(x.is_headquarters, false) DESC, x.created_at, x.id
+    LOOP
+      v_kind := CASE WHEN NOT v_has_hq AND coalesce(l.is_headquarters, false) THEN 'hq' ELSE 'branch' END;
+      IF v_kind = 'hq' THEN v_has_hq := true; END IF;
+      INSERT INTO app.units (tenant_id, id, kind, name, active, metadata, created_at, updated_at)
+      VALUES (t.id, l.id, v_kind, l.name, coalesce(l.is_active, true),
+              coalesce(l.metadata, '{}'::jsonb) || jsonb_strip_nulls(jsonb_build_object(
+                'email', l.email, 'phone', l.phone, 'address', l.address, 'city', l.city, 'state', l.state,
+                'country', l.country, 'postal_code', l.postal_code,
+                'tags', CASE WHEN l.tags IS NULL OR cardinality(l.tags) = 0 THEN NULL ELSE to_jsonb(l.tags) END,
+                'notes', l.notes,
+                'custom_fields', CASE WHEN l.custom_fields = '{}'::jsonb THEN NULL ELSE l.custom_fields END,
+                'created_by', l.created_by,
+                'legacy_kind', CASE WHEN l.kind IN ('hq', 'branch') THEN NULL ELSE l.kind END)),
+              coalesce(l.created_at, now()), coalesce(l.updated_at, now()))
+      ON CONFLICT (id) DO NOTHING;
+    END LOOP;
+  END LOOP;
+
+  -- every tenant has a headquarters: promote the earliest unit, or create one
+  FOR t IN SELECT x.id, x.name FROM public.tenants x
+            WHERE NOT EXISTS (SELECT 1 FROM app.units u WHERE u.tenant_id = x.id AND u.kind = 'hq')
+  LOOP
+    SELECT u.id INTO v_first FROM app.units u WHERE u.tenant_id = t.id ORDER BY u.created_at, u.id LIMIT 1;
+    IF v_first IS NOT NULL THEN
+      UPDATE app.units SET kind = 'hq' WHERE id = v_first;
+    ELSE
+      INSERT INTO app.units (tenant_id, kind, name, slug, active)
+      VALUES (t.id, 'hq', coalesce(nullif(btrim(t.name), ''), 'Sede'), 'hq', true);
+    END IF;
+  END LOOP;
+
+  -- 4. location_members → membership_units (only members of the tenant)
+  INSERT INTO app.membership_units (tenant_id, user_id, unit_id)
+  SELECT u.tenant_id, lm.user_id, lm.location_id
+    FROM public.location_members lm
+    JOIN app.units u ON u.id = lm.location_id
+    JOIN app.memberships m ON m.tenant_id = u.tenant_id AND m.user_id = lm.user_id
+  ON CONFLICT DO NOTHING;
+
+  -- 5. re-derive the projections completely and re-check the share table
+  PERFORM app.compat_rebuild();
+  PERFORM app.recompute_all_user_unit_access('migration');
+END $migrate$;
+
+-- ─────────────────── policies on the projection tables ───────────────────
+-- Reads through the seam; writes need the platform permission key AND are then
+-- forwarded to app.* whose own policies decide again. The legacy self-insert
+-- (members_insert_own) is gone.
+DROP POLICY IF EXISTS "members_insert_own" ON public.tenant_members;
+DROP POLICY IF EXISTS "members_select" ON public.tenant_members;
+CREATE POLICY "members_select" ON public.tenant_members FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+DROP POLICY IF EXISTS "members_insert" ON public.tenant_members;
+CREATE POLICY "members_insert" ON public.tenant_members FOR INSERT TO authenticated
+  WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('members.manage')) AND user_id <> (select auth.uid()));
+DROP POLICY IF EXISTS "members_update" ON public.tenant_members;
+CREATE POLICY "members_update" ON public.tenant_members FOR UPDATE TO authenticated
+  USING (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('members.manage')))
+  WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('members.manage')));
+DROP POLICY IF EXISTS "members_delete" ON public.tenant_members;
+CREATE POLICY "members_delete" ON public.tenant_members FOR DELETE TO authenticated
+  USING (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('members.manage')) AND user_id <> (select auth.uid()));
+
+DROP POLICY IF EXISTS "locations_select" ON public.locations;
+CREATE POLICY "locations_select" ON public.locations FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+DROP POLICY IF EXISTS "locations_manage" ON public.locations;
+CREATE POLICY "locations_manage" ON public.locations FOR ALL TO authenticated
+  USING (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('units.manage')))
+  WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('units.manage')));
+
+DROP POLICY IF EXISTS "loc_members_select" ON public.location_members;
+CREATE POLICY "loc_members_select" ON public.location_members FOR SELECT TO authenticated
+  USING (location_id IN (SELECT l.id FROM public.locations l WHERE l.tenant_id IN (SELECT public.user_tenant_ids())));
+DROP POLICY IF EXISTS "loc_members_manage" ON public.location_members;
+CREATE POLICY "loc_members_manage" ON public.location_members FOR ALL TO authenticated
+  USING (location_id IN (SELECT l.id FROM public.locations l WHERE l.tenant_id = (select app.current_tenant_id())) AND (select app.has_permission('members.manage')))
+  WITH CHECK (location_id IN (SELECT l.id FROM public.locations l WHERE l.tenant_id = (select app.current_tenant_id())) AND (select app.has_permission('members.manage')));
+
+COMMENT ON TABLE public.tenant_members IS
+  'COMPAT PROJECTION of app.memberships (#134, 2026-08-18): same ids, role = app.roles.key, active memberships only. Derived by triggers; direct writes are forwarded to app.memberships under its RLS. Read it if you must; write app.* or use the RPCs. Removal: Phase 1.';
+COMMENT ON TABLE public.locations IS
+  'COMPAT PROJECTION of app.units (#134, 2026-08-18): same ids; is_headquarters = (kind = hq); contact/address columns come from units.metadata. Direct writes are forwarded to app.units under its RLS. Removal: Phase 1.';
+COMMENT ON TABLE public.location_members IS
+  'COMPAT PROJECTION of app.membership_units (#134, 2026-08-18): (location_id, user_id) = (unit_id, user_id) of active members; role = effective role key. Direct inserts/deletes are forwarded. Removal: Phase 1.';