@fayz-ai/db 0.13.0 → 0.14.0

package/migrations/080_people_roles.sql

@@ -1,269 +0,0 @@
--- ============================================================================
--- 080_people_roles.sql — one Person per human, many roles (ADR 0003 / PRD 03 /
--- #137).
---
--- public.people keeps one row per human; public.person_roles says which hats
--- that human wears in the tenant (customer · professional · employee · contact
--- · supplier · lead), each with a validity window and an optional unit. The
--- SDK's single `people.kind` stays as a COMPAT column: it is DERIVED from the
--- primary active role by trigger, and a direct write to `kind` (every existing
--- code path: the archetype adapter, the CRM's lead=kind, the inventory
--- supplier registry, the agenda's public booking upsert) converges into a role
--- row, so old and new writers agree. Deprecation: kind is read-only in Phase 1
--- and dropped in Phase 2 (docs/data/phase-0/03-people-multirole.md).
---
--- Both tables are stamped with the authz scaffold (043) in enforce mode: the
--- 004/006 tenant_members policies on people are dropped on purpose — RLS on
--- people is now the one template (unit scope + owner scope + people.*).
--- Idempotent and replay-safe.
--- ============================================================================
-
--- ─────────────────────────────── vocabulary ────────────────────────────
--- role → the SDK kind old readers filter on. `professional` and `employee`
--- both read as 'staff' (the agenda's professionalKind, the team roster);
--- `supplier` reads as 'supplier' because that is what plugin-inventory's
--- registry filters on today (DATA-MODEL's 'vendor' has no reader — accepted as
--- an alias on the way in, never written back).
-CREATE OR REPLACE FUNCTION public.person_role_to_kind(p_role text)
-RETURNS text LANGUAGE sql IMMUTABLE PARALLEL SAFE AS $$
-  SELECT CASE p_role
-    WHEN 'customer'     THEN 'customer'
-    WHEN 'professional' THEN 'staff'
-    WHEN 'employee'     THEN 'staff'
-    WHEN 'lead'         THEN 'lead'
-    WHEN 'supplier'     THEN 'supplier'
-    WHEN 'contact'      THEN 'contact'
-  END
-$$;
-
--- kind → the role a legacy write of `kind` means. NULL for kinds outside the
--- vocabulary (an app's own 'teacher', 'patient', …): those are left alone by
--- the derivation and get roles only when someone writes person_roles.
-CREATE OR REPLACE FUNCTION public.person_kind_to_role(p_kind text)
-RETURNS text LANGUAGE sql IMMUTABLE PARALLEL SAFE AS $$
-  SELECT CASE p_kind
-    WHEN 'customer'     THEN 'customer'
-    WHEN 'staff'        THEN 'employee'
-    WHEN 'employee'     THEN 'employee'
-    WHEN 'professional' THEN 'professional'
-    WHEN 'lead'         THEN 'lead'
-    WHEN 'supplier'     THEN 'supplier'
-    WHEN 'vendor'       THEN 'supplier'
-    WHEN 'contact'      THEN 'contact'
-  END
-$$;
-
--- A role is active from valid_from (inclusive) until valid_to (exclusive):
--- valid_to is the first day the role no longer applies. Both dates are dates,
--- not timestamps — a hat is worn by the day.
-CREATE OR REPLACE FUNCTION public.person_role_active(p_from date, p_to date)
-RETURNS boolean LANGUAGE sql STABLE PARALLEL SAFE AS $$
-  SELECT p_from <= current_date AND (p_to IS NULL OR p_to > current_date)
-$$;
-
-GRANT EXECUTE ON FUNCTION public.person_role_to_kind(text), public.person_kind_to_role(text), public.person_role_active(date, date)
-  TO anon, authenticated, service_role;
-
--- ─────────────────────────────── people: scaffold ──────────────────────
--- Adds unit_id / owner_id / unique(tenant_id,id) / composite FKs / forced RLS
--- with the template. Owner scoping is ON here so the clinic template can fill
--- owner_id (a professional sees her own patients); the salon leaves it NULL
--- and the same policy text opens every row of the unit.
-SELECT app.scaffold_table('public.people', 'people.person', 'people', true, 'enforce');
-
--- ─────────────────────────────── person_roles ──────────────────────────
-CREATE TABLE IF NOT EXISTS public.person_roles (
-  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-  tenant_id   uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
-  person_id   uuid NOT NULL,
-  role        text NOT NULL CHECK (role IN ('customer', 'professional', 'employee', 'contact', 'supplier', 'lead')),
-  unit_id     uuid,                                   -- role valid in one unit; NULL = the whole tenant
-  valid_from  date NOT NULL DEFAULT current_date,
-  valid_to    date,                                   -- first day the role no longer applies
-  is_primary  boolean NOT NULL DEFAULT false,
-  metadata    jsonb NOT NULL DEFAULT '{}'::jsonb,     -- CBO, vínculo, origin/partnership refs (ADR 0009)
-  created_at  timestamptz NOT NULL DEFAULT now(),
-  updated_at  timestamptz NOT NULL DEFAULT now(),
-  CHECK (valid_to IS NULL OR valid_to >= valid_from),
-  FOREIGN KEY (tenant_id, person_id) REFERENCES public.people(tenant_id, id) ON DELETE CASCADE
-);
--- one hat per (person, role, unit); NULL unit folds to the zero uuid so the
--- tenant-wide row is unique too
-CREATE UNIQUE INDEX IF NOT EXISTS person_roles_person_role_unit_uidx
-  ON public.person_roles (tenant_id, person_id, role, (coalesce(unit_id, '00000000-0000-0000-0000-000000000000'::uuid)));
-CREATE INDEX IF NOT EXISTS person_roles_tenant_person_idx ON public.person_roles (tenant_id, person_id);
-CREATE INDEX IF NOT EXISTS person_roles_tenant_role_idx ON public.person_roles (tenant_id, role, person_id);
-
-SELECT app.scaffold_table('public.person_roles', 'people.person_role', 'people', false, 'enforce');
-
-GRANT SELECT, INSERT, UPDATE, DELETE ON public.person_roles TO authenticated;
-GRANT ALL ON public.person_roles TO service_role;
-REVOKE ALL ON public.person_roles FROM anon;
-
--- ─────────────────────────────── kind ⇄ roles ──────────────────────────
--- Trigger functions are SECURITY DEFINER on purpose: derived data must not
--- depend on the writer's RLS (a receptionist with people.create but without
--- people.edit still gets a consistent kind); they touch nothing but kind and
--- the role row the kind implies. `fayz.people_kind_sync` (transaction-local)
--- marks our own writes so the two directions never chase each other.
-
--- roles → kind: the primary active role; else the earliest active one, ties
--- broken by a fixed precedence (professional, employee, customer, supplier,
--- contact, lead — staff hats first: that is who the roster and the agenda
--- look for). A person whose every role expired keeps the last kind (kind is
--- NOT NULL). Kinds outside the vocabulary are never rewritten.
-CREATE OR REPLACE FUNCTION public.person_role_precedence(p_role text)
-RETURNS integer LANGUAGE sql IMMUTABLE PARALLEL SAFE AS $$
-  SELECT CASE p_role WHEN 'professional' THEN 1 WHEN 'employee' THEN 2 WHEN 'customer' THEN 3
-                     WHEN 'supplier' THEN 4 WHEN 'contact' THEN 5 WHEN 'lead' THEN 6 ELSE 9 END
-$$;
-GRANT EXECUTE ON FUNCTION public.person_role_precedence(text) TO anon, authenticated, service_role;
-
-CREATE OR REPLACE FUNCTION public.people_sync_kind(p_tenant uuid, p_person uuid)
-RETURNS void
-LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
-AS $$
-DECLARE
-  v_role    text;
-  v_kind    text;
-  v_current text;
-BEGIN
-  SELECT r.role INTO v_role
-    FROM public.person_roles r
-   WHERE r.tenant_id = p_tenant AND r.person_id = p_person
-     AND public.person_role_active(r.valid_from, r.valid_to)
-   ORDER BY r.is_primary DESC, r.valid_from, r.created_at, public.person_role_precedence(r.role), r.id
-   LIMIT 1;
-  IF v_role IS NULL THEN
-    RETURN;
-  END IF;
-  v_kind := public.person_role_to_kind(v_role);
-  SELECT p.kind INTO v_current FROM public.people p WHERE p.tenant_id = p_tenant AND p.id = p_person;
-  IF NOT FOUND OR v_current = v_kind THEN
-    RETURN;
-  END IF;
-  IF v_current IS NOT NULL AND public.person_kind_to_role(v_current) IS NULL THEN
-    RETURN; -- an app-specific kind: frozen, not ours to rewrite
-  END IF;
-  PERFORM set_config('fayz.people_kind_sync', 'on', true);
-  UPDATE public.people SET kind = v_kind WHERE tenant_id = p_tenant AND id = p_person;
-  PERFORM set_config('fayz.people_kind_sync', 'off', true);
-END $$;
-REVOKE ALL ON FUNCTION public.people_sync_kind(uuid, uuid) FROM public, anon, authenticated;
-
-CREATE OR REPLACE FUNCTION public.trg_person_roles_sync_kind()
-RETURNS trigger
-LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
-AS $$
-BEGIN
-  IF TG_OP = 'DELETE' THEN
-    PERFORM public.people_sync_kind(OLD.tenant_id, OLD.person_id);
-    RETURN NULL;
-  END IF;
-  PERFORM public.people_sync_kind(NEW.tenant_id, NEW.person_id);
-  IF TG_OP = 'UPDATE' AND (OLD.person_id <> NEW.person_id OR OLD.tenant_id <> NEW.tenant_id) THEN
-    PERFORM public.people_sync_kind(OLD.tenant_id, OLD.person_id); -- a role moved (merge): the old person too
-  END IF;
-  RETURN NULL;
-END $$;
-DROP TRIGGER IF EXISTS person_roles_sync_kind ON public.person_roles;
-CREATE TRIGGER person_roles_sync_kind
-  AFTER INSERT OR UPDATE OR DELETE ON public.person_roles
-  FOR EACH ROW EXECUTE FUNCTION public.trg_person_roles_sync_kind();
-
--- kind → role: a legacy writer that says "this person is a customer" gets a
--- customer role, made primary (kind WAS the type; the write is honoured). Other
--- roles are left as they are — a kind write cannot express "no longer X";
--- closing a role is an explicit valid_to on person_roles. An existing row of
--- that role (any unit) is reused; a closed one is reopened.
-CREATE OR REPLACE FUNCTION public.trg_people_kind_to_role()
-RETURNS trigger
-LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
-AS $$
-DECLARE
-  v_role text;
-  v_id   uuid;
-BEGIN
-  IF coalesce(current_setting('fayz.people_kind_sync', true), 'off') = 'on' THEN
-    RETURN NULL;
-  END IF;
-  IF TG_OP = 'UPDATE' AND NEW.kind IS NOT DISTINCT FROM OLD.kind THEN
-    RETURN NULL;
-  END IF;
-  v_role := public.person_kind_to_role(NEW.kind);
-  IF v_role IS NULL THEN
-    RETURN NULL;
-  END IF;
-
-  SELECT r.id INTO v_id
-    FROM public.person_roles r
-   WHERE r.tenant_id = NEW.tenant_id AND r.person_id = NEW.id AND r.role = v_role
-   ORDER BY public.person_role_active(r.valid_from, r.valid_to) DESC, r.is_primary DESC, r.created_at
-   LIMIT 1;
-
-  UPDATE public.person_roles SET is_primary = false
-   WHERE tenant_id = NEW.tenant_id AND person_id = NEW.id AND is_primary AND (v_id IS NULL OR id <> v_id);
-
-  IF v_id IS NULL THEN
-    INSERT INTO public.person_roles (tenant_id, person_id, role, unit_id, is_primary)
-    VALUES (NEW.tenant_id, NEW.id, v_role, NEW.unit_id, true)
-    ON CONFLICT DO NOTHING;
-  ELSE
-    UPDATE public.person_roles
-       SET is_primary = true,
-           valid_from = least(valid_from, current_date),
-           valid_to = CASE WHEN valid_to IS NOT NULL AND valid_to <= current_date THEN NULL ELSE valid_to END
-     WHERE id = v_id AND (NOT is_primary OR NOT public.person_role_active(valid_from, valid_to));
-  END IF;
-  RETURN NULL;
-END $$;
-DROP TRIGGER IF EXISTS people_kind_to_role ON public.people;
-CREATE TRIGGER people_kind_to_role
-  AFTER INSERT OR UPDATE OF kind ON public.people
-  FOR EACH ROW EXECUTE FUNCTION public.trg_people_kind_to_role();
-
--- ─────────────────────────────── the read contract ─────────────────────
--- What the agenda, the roster and the CRM read from now on: the active hats of
--- live people. An expired role is not here; a merged tombstone (071) and an
--- inactive person are not here. security_invoker: the caller's RLS on both
--- tables decides.
-CREATE OR REPLACE VIEW public.v_people_active_roles WITH (security_invoker = true) AS
-  SELECT r.tenant_id, r.person_id, r.id AS role_id, r.role, r.unit_id, r.is_primary,
-         r.valid_from, r.valid_to, r.metadata,
-         p.name AS person_name, p.kind AS person_kind, p.email, p.phone, p.document_number,
-         p.unit_id AS person_unit_id, p.owner_id AS person_owner_id
-    FROM public.person_roles r
-    JOIN public.people p ON p.tenant_id = r.tenant_id AND p.id = r.person_id
-   WHERE public.person_role_active(r.valid_from, r.valid_to)
-     AND coalesce(p.is_active, true);
-GRANT SELECT ON public.v_people_active_roles TO authenticated, service_role;
-
--- ─────────────────────────────── shared RPC guard ──────────────────────
--- Every people RPC (071/072/074) checks the same three things: a session
--- tenant, unit membership when the row has a unit, and the permission in that
--- unit. Raises 42501 — the RLS code — so a denied RPC and a denied write read
--- the same to the app.
-CREATE OR REPLACE FUNCTION public.people_assert_scope(p_perm text, p_unit uuid DEFAULT NULL)
-RETURNS uuid
-LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = ''
-AS $$
-DECLARE v_tenant uuid := app.current_tenant_id();
-BEGIN
-  IF v_tenant IS NULL THEN
-    RAISE EXCEPTION 'no active tenant for this session' USING ERRCODE = '42501';
-  END IF;
-  IF p_unit IS NOT NULL AND NOT app.has_unit(p_unit) THEN
-    RAISE EXCEPTION 'unit out of scope' USING ERRCODE = '42501';
-  END IF;
-  IF NOT app.has_permission(p_perm, p_unit) THEN
-    RAISE EXCEPTION 'permission % denied', p_perm USING ERRCODE = '42501';
-  END IF;
-  RETURN v_tenant;
-END $$;
-REVOKE ALL ON FUNCTION public.people_assert_scope(text, uuid) FROM public, anon;
-GRANT EXECUTE ON FUNCTION public.people_assert_scope(text, uuid) TO authenticated, service_role;
-
-COMMENT ON TABLE public.person_roles IS
-  'The hats a Person wears in the tenant (customer · professional · employee · contact · supplier · lead), each with a validity window and an optional unit. people.kind is derived from the primary active role (compat; read-only in Phase 1, dropped in Phase 2).';
-COMMENT ON COLUMN public.people.kind IS
-  'DEPRECATED compat: derived from person_roles (primary active role → customer|staff|lead|supplier|contact). Writing it still works and creates/promotes the matching role. Read roles from public.v_people_active_roles. Read-only in Phase 1, dropped in Phase 2.';

package/migrations/081_people_identity.sql

@@ -1,271 +0,0 @@
--- ============================================================================
--- 081_people_identity.sql — identity by document, dedup, merge, quarantine
--- (PRD 03 R2 · PRD 10 R4 · ADR 0003 / 0007 · #137).
---
--- One human per tenant per document (CPF/CNPJ): document_number is normalised
--- on write and a partial unique index holds `(tenant_id, document_number)`.
--- The index is created ONLY when the data allows it — if duplicates already
--- exist when this file runs, they are written to person_identity_quarantine,
--- a NOTICE is raised and the index is skipped (never a silent merge; PRD 10
--- R4). people_identity_index_ensure() is the same step as a callable, so the
--- operator re-runs it after resolving the quarantine.
---
--- Merge is a decision, not a heuristic: people_merge(survivor, duplicate,
--- reason) works only when both rows carry the same non-null document;
--- anything else is "ambiguous identity" and raises. The duplicate becomes a
--- tombstone (merged_into_id), every FK that pointed at it is repointed, its
--- roles move, and two rows record it: audit_logs and person_merges (the row
--- PRD 10's migration ledger points at). Idempotent and replay-safe.
--- ============================================================================
-
--- ─────────────────────────────── normalisation ─────────────────────────
--- Canonical form = separators stripped, letters upper-cased, empty → NULL:
--- '529.982.247-25' and '52998224725' are the same CPF; '11.222.333/0001-81'
--- and '11222333000181' the same CNPJ. Letters are KEPT (upper-cased) rather
--- than stripped: Brazil's CNPJ is alphanumeric from July 2026 (RFB IN
--- 2.229/2024) — a digits-only rule would silently corrupt those.
-CREATE OR REPLACE FUNCTION public.people_normalize_document(p_doc text)
-RETURNS text LANGUAGE sql IMMUTABLE PARALLEL SAFE AS $$
-  SELECT nullif(upper(regexp_replace(coalesce(p_doc, ''), '[^0-9A-Za-z]', '', 'g')), '')
-$$;
-GRANT EXECUTE ON FUNCTION public.people_normalize_document(text) TO anon, authenticated, service_role;
-
-CREATE OR REPLACE FUNCTION public.trg_people_normalize_document()
-RETURNS trigger LANGUAGE plpgsql AS $$
-BEGIN
-  NEW.document_number := public.people_normalize_document(NEW.document_number);
-  RETURN NEW;
-END $$;
-DROP TRIGGER IF EXISTS people_normalize_document ON public.people;
-CREATE TRIGGER people_normalize_document
-  BEFORE INSERT OR UPDATE OF document_number ON public.people
-  FOR EACH ROW EXECUTE FUNCTION public.trg_people_normalize_document();
-
--- Rows written before the trigger existed converge to the canonical form
--- (format only — no identity is decided here).
-UPDATE public.people
-   SET document_number = public.people_normalize_document(document_number)
- WHERE document_number IS NOT NULL
-   AND document_number IS DISTINCT FROM public.people_normalize_document(document_number);
-
--- ─────────────────────────────── tombstone ─────────────────────────────
-ALTER TABLE public.people ADD COLUMN IF NOT EXISTS merged_into_id uuid;
-DO $$
-BEGIN
-  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'public.people'::regclass AND conname = 'people_merged_into_fk') THEN
-    ALTER TABLE public.people ADD CONSTRAINT people_merged_into_fk
-      FOREIGN KEY (tenant_id, merged_into_id) REFERENCES public.people(tenant_id, id) ON DELETE SET NULL;
-  END IF;
-  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'public.people'::regclass AND conname = 'people_merged_into_not_self') THEN
-    ALTER TABLE public.people ADD CONSTRAINT people_merged_into_not_self CHECK (merged_into_id IS DISTINCT FROM id);
-  END IF;
-END $$;
-CREATE INDEX IF NOT EXISTS people_merged_into_idx ON public.people (tenant_id, merged_into_id) WHERE merged_into_id IS NOT NULL;
-COMMENT ON COLUMN public.people.merged_into_id IS
-  'Set by people_merge(): this row is a tombstone of the human now recorded at merged_into_id. Excluded from the document unique index and from v_people_active_roles.';
-
--- ─────────────────────────────── quarantine + merge ledger ─────────────
--- Not scaffolded on purpose: these are ledgers, read by people.manage and
--- written only by the migration and the merge RPC. The generic
--- tenant_isolation_* policies a replay of 002 may add are dropped here.
-CREATE TABLE IF NOT EXISTS public.person_identity_quarantine (
-  id              uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-  tenant_id       uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
-  document_number text,                       -- NULL when the ambiguity is not by document
-  person_ids      uuid[] NOT NULL,
-  reason          text NOT NULL,
-  context         jsonb NOT NULL DEFAULT '{}'::jsonb,
-  created_at      timestamptz NOT NULL DEFAULT now(),
-  resolved_at     timestamptz,
-  resolved_by     uuid,
-  resolution      text
-);
-CREATE UNIQUE INDEX IF NOT EXISTS person_identity_quarantine_open_doc_uidx
-  ON public.person_identity_quarantine (tenant_id, document_number) WHERE resolved_at IS NULL AND document_number IS NOT NULL;
-CREATE INDEX IF NOT EXISTS person_identity_quarantine_tenant_idx ON public.person_identity_quarantine (tenant_id, created_at DESC);
-
-CREATE TABLE IF NOT EXISTS public.person_merges (
-  id              uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-  tenant_id       uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
-  survivor_id     uuid NOT NULL,
-  duplicate_id    uuid NOT NULL,
-  document_number text,
-  reason          text NOT NULL,
-  actor           uuid,
-  details         jsonb NOT NULL DEFAULT '{}'::jsonb,
-  created_at      timestamptz NOT NULL DEFAULT now(),
-  FOREIGN KEY (tenant_id, survivor_id) REFERENCES public.people(tenant_id, id) ON DELETE CASCADE,
-  FOREIGN KEY (tenant_id, duplicate_id) REFERENCES public.people(tenant_id, id) ON DELETE CASCADE
-);
-CREATE INDEX IF NOT EXISTS person_merges_survivor_idx ON public.person_merges (tenant_id, survivor_id);
-CREATE INDEX IF NOT EXISTS person_merges_duplicate_idx ON public.person_merges (tenant_id, duplicate_id);
-
-DO $$
-DECLARE t text; p text;
-BEGIN
-  FOREACH t IN ARRAY ARRAY['person_identity_quarantine', 'person_merges'] LOOP
-    EXECUTE format('ALTER TABLE public.%I ENABLE ROW LEVEL SECURITY', t);
-    EXECUTE format('ALTER TABLE public.%I FORCE ROW LEVEL SECURITY', t);
-    FOREACH p IN ARRAY ARRAY['tenant_isolation_select', 'tenant_isolation_insert', 'tenant_isolation_update', 'tenant_isolation_delete'] LOOP
-      EXECUTE format('DROP POLICY IF EXISTS %I ON public.%I', p, t);
-    END LOOP;
-    EXECUTE format('DROP POLICY IF EXISTS %I ON public.%I', t || '_select', t);
-    EXECUTE format('CREATE POLICY %I ON public.%I FOR SELECT TO authenticated USING (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission(''people.manage'')))', t || '_select', t);
-    EXECUTE format('REVOKE ALL ON public.%I FROM anon, authenticated', t);
-    EXECUTE format('GRANT SELECT ON public.%I TO authenticated', t);
-    EXECUTE format('GRANT ALL ON public.%I TO service_role', t);
-  END LOOP;
-END $$;
-
--- ─────────────────────────────── the unique index, guarded ─────────────
--- Creates people_tenant_document_uidx when no live duplicate exists; otherwise
--- quarantines each duplicate group and returns false (with a NOTICE). Callable
--- again after the quarantine is resolved. Not for the app: migration / ops.
-CREATE OR REPLACE FUNCTION public.people_identity_index_ensure()
-RETURNS boolean
-LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
-AS $$
-DECLARE v_groups integer;
-BEGIN
-  IF to_regclass('public.people_tenant_document_uidx') IS NOT NULL THEN
-    RETURN true;
-  END IF;
-  INSERT INTO public.person_identity_quarantine (tenant_id, document_number, person_ids, reason, context)
-  SELECT p.tenant_id, p.document_number, array_agg(p.id ORDER BY p.created_at, p.id),
-         'duplicate document_number found while creating people_tenant_document_uidx',
-         jsonb_build_object('source', 'people_identity_index_ensure', 'count', count(*))
-    FROM public.people p
-   WHERE p.document_number IS NOT NULL AND p.merged_into_id IS NULL
-   GROUP BY p.tenant_id, p.document_number
-  HAVING count(*) > 1
-  ON CONFLICT (tenant_id, document_number) WHERE resolved_at IS NULL AND document_number IS NOT NULL DO NOTHING;
-
-  SELECT count(*) INTO v_groups
-    FROM (SELECT 1 FROM public.people p
-           WHERE p.document_number IS NOT NULL AND p.merged_into_id IS NULL
-           GROUP BY p.tenant_id, p.document_number HAVING count(*) > 1) d;
-  IF v_groups > 0 THEN
-    RAISE NOTICE 'people identity: % duplicate document group(s) quarantined (public.person_identity_quarantine); people_tenant_document_uidx NOT created — resolve with people_merge() and call people_identity_index_ensure() again', v_groups;
-    RETURN false;
-  END IF;
-  EXECUTE 'CREATE UNIQUE INDEX IF NOT EXISTS people_tenant_document_uidx ON public.people (tenant_id, document_number) WHERE document_number IS NOT NULL AND merged_into_id IS NULL';
-  RETURN true;
-END $$;
-REVOKE ALL ON FUNCTION public.people_identity_index_ensure() FROM public, anon, authenticated;
-GRANT EXECUTE ON FUNCTION public.people_identity_index_ensure() TO service_role;
-
-SELECT public.people_identity_index_ensure();
-
--- ─────────────────────────────── people_merge ──────────────────────────
--- Requires people.manage in the session tenant. Only exact document equality
--- merges; everything else raises P0001 'ambiguous identity — quarantine'.
--- Effects, all in one transaction: person_roles moved (a role the survivor
--- already wears is dropped from the duplicate and listed in details); every
--- FK column that references people(id) in schemas public/app repointed (a
--- unique violation there — e.g. both humans hold a login — aborts the merge:
--- a human decides); the duplicate tombstoned (merged_into_id, is_active
--- false); an audit_logs row; a person_merges row; open quarantine rows that
--- now hold at most one live person marked resolved. Returns the survivor id.
-CREATE OR REPLACE FUNCTION public.people_merge(p_survivor uuid, p_duplicate uuid, p_reason text)
-RETURNS uuid
-LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
-AS $$
-DECLARE
-  v_tenant  uuid := public.people_assert_scope('people.manage');
-  v_actor   uuid := auth.uid();
-  s         public.people%ROWTYPE;
-  d         public.people%ROWTYPE;
-  v_moved   integer := 0;
-  v_dropped jsonb := '[]'::jsonb;
-  v_repoint jsonb := '[]'::jsonb;
-  v_n       integer;
-  fk        record;
-  v_merge   uuid;
-BEGIN
-  IF p_survivor IS NULL OR p_duplicate IS NULL OR p_survivor = p_duplicate THEN
-    RAISE EXCEPTION 'people_merge: survivor and duplicate must be two different people' USING ERRCODE = '22023';
-  END IF;
-  IF p_reason IS NULL OR btrim(p_reason) = '' THEN
-    RAISE EXCEPTION 'people_merge: a reason is required' USING ERRCODE = '22023';
-  END IF;
-  SELECT * INTO s FROM public.people WHERE tenant_id = v_tenant AND id = p_survivor FOR UPDATE;
-  IF NOT FOUND THEN RAISE EXCEPTION 'people_merge: survivor not found in this tenant' USING ERRCODE = 'P0002'; END IF;
-  SELECT * INTO d FROM public.people WHERE tenant_id = v_tenant AND id = p_duplicate FOR UPDATE;
-  IF NOT FOUND THEN RAISE EXCEPTION 'people_merge: duplicate not found in this tenant' USING ERRCODE = 'P0002'; END IF;
-  IF (s.unit_id IS NOT NULL AND NOT app.has_unit(s.unit_id)) OR (d.unit_id IS NOT NULL AND NOT app.has_unit(d.unit_id)) THEN
-    RAISE EXCEPTION 'people_merge: both people must be in units of your scope' USING ERRCODE = '42501';
-  END IF;
-  IF s.merged_into_id IS NOT NULL OR d.merged_into_id IS NOT NULL THEN
-    RAISE EXCEPTION 'people_merge: one of the rows is already a merge tombstone' USING ERRCODE = 'P0001';
-  END IF;
-  IF s.document_number IS NULL OR d.document_number IS NULL OR s.document_number <> d.document_number THEN
-    RAISE EXCEPTION 'ambiguous identity — quarantine (people_merge only merges two people with the same non-null document_number)' USING ERRCODE = 'P0001';
-  END IF;
-
-  -- roles: move what the survivor lacks, drop (and record) what she already has
-  SELECT coalesce(jsonb_agg(jsonb_build_object('role', r.role, 'unit_id', r.unit_id, 'valid_from', r.valid_from, 'valid_to', r.valid_to, 'metadata', r.metadata)), '[]'::jsonb)
-    INTO v_dropped
-    FROM public.person_roles r
-   WHERE r.tenant_id = v_tenant AND r.person_id = p_duplicate
-     AND EXISTS (SELECT 1 FROM public.person_roles x
-                  WHERE x.tenant_id = v_tenant AND x.person_id = p_survivor AND x.role = r.role
-                    AND coalesce(x.unit_id, '00000000-0000-0000-0000-000000000000'::uuid) = coalesce(r.unit_id, '00000000-0000-0000-0000-000000000000'::uuid));
-  DELETE FROM public.person_roles r
-   WHERE r.tenant_id = v_tenant AND r.person_id = p_duplicate
-     AND EXISTS (SELECT 1 FROM public.person_roles x
-                  WHERE x.tenant_id = v_tenant AND x.person_id = p_survivor AND x.role = r.role
-                    AND coalesce(x.unit_id, '00000000-0000-0000-0000-000000000000'::uuid) = coalesce(r.unit_id, '00000000-0000-0000-0000-000000000000'::uuid));
-  UPDATE public.person_roles r
-     SET person_id = p_survivor,
-         is_primary = CASE WHEN EXISTS (SELECT 1 FROM public.person_roles x WHERE x.tenant_id = v_tenant AND x.person_id = p_survivor AND x.is_primary) THEN false ELSE r.is_primary END
-   WHERE r.tenant_id = v_tenant AND r.person_id = p_duplicate;
-  GET DIAGNOSTICS v_moved = ROW_COUNT;
-
-  -- every reference to the duplicate now points at the survivor (public + app)
-  FOR fk IN
-    SELECT n.nspname AS sch, c.relname AS tbl, a.attname AS col
-      FROM pg_constraint k
-      JOIN pg_class c ON c.oid = k.conrelid
-      JOIN pg_namespace n ON n.oid = c.relnamespace
-      JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum = ANY (k.conkey)
-     WHERE k.contype = 'f' AND k.confrelid = 'public.people'::regclass
-       AND n.nspname IN ('public', 'app')
-       AND NOT (c.relname = 'person_roles' AND a.attname = 'person_id')
-       AND NOT (c.relname = 'person_merges')
-       AND a.attname <> 'tenant_id'
-  LOOP
-    EXECUTE format('UPDATE %I.%I SET %I = $1 WHERE %I = $2', fk.sch, fk.tbl, fk.col, fk.col) USING p_survivor, p_duplicate;
-    GET DIAGNOSTICS v_n = ROW_COUNT;
-    IF v_n > 0 THEN
-      v_repoint := v_repoint || jsonb_build_object('table', fk.sch || '.' || fk.tbl, 'column', fk.col, 'rows', v_n);
-    END IF;
-  END LOOP;
-
-  UPDATE public.people
-     SET merged_into_id = p_survivor, is_active = false
-   WHERE tenant_id = v_tenant AND id = p_duplicate;
-
-  INSERT INTO public.person_merges (tenant_id, survivor_id, duplicate_id, document_number, reason, actor, details)
-  VALUES (v_tenant, p_survivor, p_duplicate, s.document_number, p_reason, v_actor,
-          jsonb_build_object('roles_moved', v_moved, 'roles_dropped', v_dropped, 'repointed', v_repoint,
-                             'duplicate_snapshot', jsonb_build_object('name', d.name, 'email', d.email, 'phone', d.phone, 'kind', d.kind)))
-  RETURNING id INTO v_merge;
-
-  INSERT INTO public.audit_logs (tenant_id, user_id, action, entity_type, entity_id, metadata)
-  VALUES (v_tenant, v_actor, 'people.merge', 'people', p_survivor::text,
-          jsonb_build_object('duplicate_id', p_duplicate, 'reason', p_reason, 'merge_id', v_merge, 'document_number', s.document_number));
-
-  UPDATE public.person_identity_quarantine q
-     SET resolved_at = now(), resolved_by = v_actor, resolution = 'merged:' || v_merge::text
-   WHERE q.tenant_id = v_tenant AND q.resolved_at IS NULL AND q.person_ids @> ARRAY[p_duplicate]
-     AND (SELECT count(*) FROM public.people p WHERE p.tenant_id = v_tenant AND p.id = ANY (q.person_ids) AND p.merged_into_id IS NULL) <= 1;
-
-  RETURN p_survivor;
-END $$;
-REVOKE ALL ON FUNCTION public.people_merge(uuid, uuid, text) FROM public, anon;
-GRANT EXECUTE ON FUNCTION public.people_merge(uuid, uuid, text) TO authenticated, service_role;
-
-COMMENT ON TABLE public.person_identity_quarantine IS
-  'Identity ambiguities that must be decided by a human (PRD 10 R4): duplicate documents found when creating the unique index, registrations whose signals match people without a document match. Never merged silently.';
-COMMENT ON TABLE public.person_merges IS
-  'Ledger of people_merge(): survivor, duplicate, document, reason, actor and what moved. The migration ledger (PRD 10) points at these rows for humans that arrived as two V1 records.';