@fayz-ai/db 0.11.0 → 0.13.0

package/migrations/080_people_roles.sql

@@ -0,0 +1,269 @@
+-- ============================================================================
+-- 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

@@ -0,0 +1,271 @@
+-- ============================================================================
+-- 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.';