@fayz-ai/db 0.13.0 → 0.14.0

package/migrations/082_people_membership_link.sql

@@ -1,142 +0,0 @@
--- ============================================================================
--- 082_people_membership_link.sql — the login and the Person are one human
--- (PRD 03 R3 · ADR 0003 / 0006 · #137).
---
--- app.memberships.person_id (040) now points at people(tenant_id, id): one
--- user = one Person per tenant (partial unique), and a membership can only be
--- linked to a live person of its own tenant. The link is made by
--- people_link_membership(person, user) (members.manage), which also gives the
--- person an employee role if she has no staff role yet — a login is a member
--- of the team. The reverse rule ("every professional/employee with a login
--- has person_id") cannot be a constraint — a professional without a login is
--- legitimate — so it is enforced softly: v_people_missing_membership_link
--- lists the memberships of the tenant that still have no Person, with the
--- suggested match by e-mail. Idempotent and replay-safe.
--- ============================================================================
-
-DO $$
-BEGIN
-  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'app.memberships'::regclass AND conname = 'memberships_person_fk') THEN
-    ALTER TABLE app.memberships ADD CONSTRAINT memberships_person_fk
-      FOREIGN KEY (tenant_id, person_id) REFERENCES public.people(tenant_id, id) ON DELETE SET NULL;
-  END IF;
-END $$;
--- one Person ↔ at most one membership per tenant
-CREATE UNIQUE INDEX IF NOT EXISTS memberships_tenant_person_uidx
-  ON app.memberships (tenant_id, person_id) WHERE person_id IS NOT NULL;
-
--- a membership never points at a merge tombstone
-CREATE OR REPLACE FUNCTION app.trg_memberships_person_link_check()
-RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
-BEGIN
-  IF NEW.person_id IS NULL THEN
-    RETURN NEW;
-  END IF;
-  IF EXISTS (SELECT 1 FROM public.people p WHERE p.tenant_id = NEW.tenant_id AND p.id = NEW.person_id AND p.merged_into_id IS NOT NULL) THEN
-    RAISE EXCEPTION 'memberships.person_id must point at a live person, not a merge tombstone' USING ERRCODE = '23514';
-  END IF;
-  RETURN NEW;
-END $$;
-DROP TRIGGER IF EXISTS memberships_person_link_check ON app.memberships;
-CREATE TRIGGER memberships_person_link_check
-  BEFORE INSERT OR UPDATE OF person_id ON app.memberships
-  FOR EACH ROW EXECUTE FUNCTION app.trg_memberships_person_link_check();
-
--- ─────────────────────────────── the RPC ───────────────────────────────
--- Links the membership of p_user (in the session tenant) to p_person. The
--- person must be a live person of the tenant, in a unit of the caller's
--- scope; neither side may already be linked elsewhere. Ensures the person
--- wears at least one staff role (professional or employee) — creates an
--- employee role when she wears none. Returns the membership id.
-CREATE OR REPLACE FUNCTION public.people_link_membership(p_person uuid, p_user uuid)
-RETURNS uuid
-LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
-AS $$
-DECLARE
-  v_tenant uuid := public.people_assert_scope('members.manage');
-  p        public.people%ROWTYPE;
-  m        app.memberships%ROWTYPE;
-  v_other  uuid;
-BEGIN
-  SELECT * INTO p FROM public.people WHERE tenant_id = v_tenant AND id = p_person FOR UPDATE;
-  IF NOT FOUND THEN RAISE EXCEPTION 'people_link_membership: person not found in this tenant' USING ERRCODE = 'P0002'; END IF;
-  IF p.merged_into_id IS NOT NULL THEN
-    RAISE EXCEPTION 'people_link_membership: person is a merge tombstone (use %)', p.merged_into_id USING ERRCODE = 'P0001';
-  END IF;
-  IF p.unit_id IS NOT NULL AND NOT app.has_unit(p.unit_id) THEN
-    RAISE EXCEPTION 'people_link_membership: person is in a unit out of your scope' USING ERRCODE = '42501';
-  END IF;
-  SELECT * INTO m FROM app.memberships WHERE tenant_id = v_tenant AND user_id = p_user FOR UPDATE;
-  IF NOT FOUND THEN RAISE EXCEPTION 'people_link_membership: no membership for this user in this tenant' USING ERRCODE = 'P0002'; END IF;
-  IF m.person_id IS NOT NULL AND m.person_id <> p_person THEN
-    RAISE EXCEPTION 'people_link_membership: this login is already linked to another person (%)', m.person_id USING ERRCODE = '23505';
-  END IF;
-  SELECT x.user_id INTO v_other FROM app.memberships x WHERE x.tenant_id = v_tenant AND x.person_id = p_person AND x.user_id <> p_user;
-  IF v_other IS NOT NULL THEN
-    RAISE EXCEPTION 'people_link_membership: this person is already linked to another login (%)', v_other USING ERRCODE = '23505';
-  END IF;
-
-  IF m.person_id IS DISTINCT FROM p_person THEN
-    UPDATE app.memberships SET person_id = p_person WHERE tenant_id = v_tenant AND user_id = p_user;
-  END IF;
-
-  -- a login is a member of the team: at least one staff role
-  IF NOT EXISTS (SELECT 1 FROM public.person_roles r
-                  WHERE r.tenant_id = v_tenant AND r.person_id = p_person
-                    AND r.role IN ('professional', 'employee')
-                    AND public.person_role_active(r.valid_from, r.valid_to)) THEN
-    INSERT INTO public.person_roles (tenant_id, person_id, role, unit_id, is_primary, metadata)
-    VALUES (v_tenant, p_person, 'employee', p.unit_id,
-            NOT EXISTS (SELECT 1 FROM public.person_roles r WHERE r.tenant_id = v_tenant AND r.person_id = p_person AND r.is_primary),
-            jsonb_build_object('source', 'people_link_membership'))
-    ON CONFLICT DO NOTHING;
-    -- an expired employee row for the same unit blocks the insert above: reopen it
-    UPDATE public.person_roles r
-       SET valid_to = NULL, valid_from = least(r.valid_from, current_date)
-     WHERE r.tenant_id = v_tenant AND r.person_id = p_person AND r.role = 'employee'
-       AND NOT public.person_role_active(r.valid_from, r.valid_to)
-       AND NOT EXISTS (SELECT 1 FROM public.person_roles x WHERE x.tenant_id = v_tenant AND x.person_id = p_person
-                        AND x.role IN ('professional', 'employee') AND public.person_role_active(x.valid_from, x.valid_to));
-  END IF;
-
-  INSERT INTO public.audit_logs (tenant_id, user_id, action, entity_type, entity_id, metadata)
-  VALUES (v_tenant, auth.uid(), 'people.link_membership', 'people', p_person::text, jsonb_build_object('user_id', p_user, 'membership_id', m.id));
-  RETURN m.id;
-END $$;
-REVOKE ALL ON FUNCTION public.people_link_membership(uuid, uuid) FROM public, anon;
-GRANT EXECUTE ON FUNCTION public.people_link_membership(uuid, uuid) TO authenticated, service_role;
-
--- ─────────────────────────────── the soft rule, visible ────────────────
--- The person a human would probably link to a login: same e-mail as the
--- auth user, live, wearing a staff role. auth.users is not readable by API
--- roles, so this is a definer function that answers only for members.read
--- holders of the tenant (the same gate as the memberships read policy).
-CREATE OR REPLACE FUNCTION public.people_suggest_for_user(p_tenant uuid, p_user uuid)
-RETURNS uuid
-LANGUAGE sql STABLE SECURITY DEFINER SET search_path = ''
-AS $$
-  SELECT p.id
-    FROM auth.users u
-    JOIN public.people p ON p.tenant_id = p_tenant AND p.merged_into_id IS NULL
-                        AND p.email IS NOT NULL AND lower(p.email) = lower(u.email)
-   WHERE u.id = p_user
-     AND p_tenant = app.current_tenant_id()
-     AND app.has_permission('members.read')
-     AND EXISTS (SELECT 1 FROM public.person_roles r
-                  WHERE r.tenant_id = p.tenant_id AND r.person_id = p.id
-                    AND r.role IN ('professional', 'employee')
-                    AND public.person_role_active(r.valid_from, r.valid_to))
-   ORDER BY p.created_at
-   LIMIT 1;
-$$;
-REVOKE ALL ON FUNCTION public.people_suggest_for_user(uuid, uuid) FROM public, anon;
-GRANT EXECUTE ON FUNCTION public.people_suggest_for_user(uuid, uuid) TO authenticated, service_role;
-
--- Memberships of the tenant with no Person yet (+ the suggested match). Reads
--- through the caller's RLS on memberships (members.read or self).
-CREATE OR REPLACE VIEW public.v_people_missing_membership_link WITH (security_invoker = true) AS
-  SELECT m.tenant_id, m.id AS membership_id, m.user_id, m.role_id, m.active,
-         public.people_suggest_for_user(m.tenant_id, m.user_id) AS suggested_person_id
-    FROM app.memberships m
-   WHERE m.person_id IS NULL;
-GRANT SELECT ON public.v_people_missing_membership_link TO authenticated, service_role;

package/migrations/083_people_data_migration.sql

@@ -1,75 +0,0 @@
--- ============================================================================
--- 083_people_data_migration.sql — every existing Person gets its roles
--- (PRD 03 R1/R4 · #137). Data only, idempotent, guarded.
---
--- Rows written before 070 have a kind and no role. They converge here:
---   people.kind  customer → customer · staff → employee · lead → lead (CRM) ·
---                supplier|vendor → supplier (inventory) · contact → contact ·
---                professional → professional · employee → employee
---   staff_members (the resto-saas / salon app extension, when present) →
---                professional role in addition to employee: v_staff is who
---                the agenda assigns and pays a rate to
--- Kinds outside the vocabulary (an app's 'teacher', 'patient', …) get no
--- role and keep their kind — they are the app's, not the platform's.
--- Nothing here merges people or touches documents (071 quarantines; humans
--- decide). Re-running is a no-op: every insert is ON CONFLICT DO NOTHING.
--- ============================================================================
-
--- 1. kind → the primary role. Roles are inserted through the same trigger
---    path a new writer would take, so kind and role agree afterwards
---    ('vendor' converges to 'supplier').
-INSERT INTO public.person_roles (tenant_id, person_id, role, unit_id, is_primary, metadata)
-SELECT p.tenant_id, p.id, public.person_kind_to_role(p.kind), p.unit_id, true,
-       jsonb_build_object('source', 'migration:073', 'from_kind', p.kind)
-  FROM public.people p
- WHERE public.person_kind_to_role(p.kind) IS NOT NULL
-   AND p.merged_into_id IS NULL
-   AND NOT EXISTS (SELECT 1 FROM public.person_roles r WHERE r.tenant_id = p.tenant_id AND r.person_id = p.id)
-ON CONFLICT DO NOTHING;
-
--- 2. staff_members (app extension, PK person_id) → professional role. Guarded
---    on the table AND its columns: the extension is the app's, not ours.
-DO $$
-DECLARE v_n integer := 0;
-BEGIN
-  IF to_regclass('public.staff_members') IS NOT NULL
-     AND EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = 'public' AND table_name = 'staff_members' AND column_name = 'person_id') THEN
-    INSERT INTO public.person_roles (tenant_id, person_id, role, unit_id, is_primary, metadata)
-    SELECT p.tenant_id, p.id, 'professional', p.unit_id, false,
-           jsonb_build_object('source', 'migration:073', 'from', 'staff_members')
-      FROM public.staff_members s
-      JOIN public.people p ON p.id = s.person_id
-     WHERE p.merged_into_id IS NULL
-       AND NOT EXISTS (SELECT 1 FROM public.person_roles r
-                        WHERE r.tenant_id = p.tenant_id AND r.person_id = p.id AND r.role = 'professional')
-    ON CONFLICT DO NOTHING;
-    GET DIAGNOSTICS v_n = ROW_COUNT;
-    RAISE NOTICE 'people: % staff_members row(s) received a professional role', v_n;
-  END IF;
-END $$;
-
--- 3. CRM leads (kind = 'lead') and inventory suppliers (kind = 'supplier') are
---    covered by step 1 — both plugins write kind, so their rows already carry
---    the right role. Nothing plugin-specific to do here; the plugins keep
---    working on kind until they read v_people_active_roles (Phase 1).
-
--- 4. Reconcile: a person whose kind disagrees with her primary active role
---    (only possible for rows edited between 070 and now) is re-derived.
-DO $$
-DECLARE r record;
-BEGIN
-  FOR r IN
-    SELECT p.tenant_id, p.id
-      FROM public.people p
-     WHERE p.merged_into_id IS NULL
-       AND public.person_kind_to_role(p.kind) IS NOT NULL
-       AND EXISTS (SELECT 1 FROM public.person_roles x WHERE x.tenant_id = p.tenant_id AND x.person_id = p.id)
-       AND p.kind IS DISTINCT FROM public.person_role_to_kind((
-             SELECT x.role FROM public.person_roles x
-              WHERE x.tenant_id = p.tenant_id AND x.person_id = p.id
-                AND public.person_role_active(x.valid_from, x.valid_to)
-              ORDER BY x.is_primary DESC, x.valid_from, x.created_at, public.person_role_precedence(x.role), x.id LIMIT 1))
-  LOOP
-    PERFORM public.people_sync_kind(r.tenant_id, r.id);
-  END LOOP;
-END $$;

package/migrations/084_people_registrations_tokens.sql

@@ -1,282 +0,0 @@
--- ============================================================================
--- 084_people_registrations_tokens.sql — the public edges of People, as
--- contracts (PRD 03 R6 · RN-CLI-01/02 · #137). No UI here.
---
--- person_registrations: the pre-registration queue (V1 client_registrations).
--- A row arrives with the raw payload (the QR form of the unit, fields per
--- FieldRules); person_registrations_process() turns it into a Person with
--- dedup by exact CPF: one match → 'merged' (the existing person, plus a
--- customer role); no signal → 'created'; anything ambiguous (2+ document
--- matches, or e-mail/phone matches without a document match) → 'quarantined'
--- with a person_identity_quarantine row — a human then resolves it with the
--- 'create' or 'merge' actions. Never a silent merge (PRD 10 R4).
---
--- person_access_tokens: opaque, single-use, expiring tokens for the client
--- portal (V1 client_access_tokens). Only the hash is stored; the token is
--- returned once by person_access_token_issue() (people.edit) and redeemed by
--- anon through person_access_token_redeem() — there is no anon SELECT, ever.
--- Idempotent and replay-safe.
--- ============================================================================
-
--- ─────────────────────────────── registrations ─────────────────────────
-CREATE TABLE IF NOT EXISTS public.person_registrations (
-  id                uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-  tenant_id         uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
-  unit_id           uuid,
-  payload           jsonb NOT NULL DEFAULT '{}'::jsonb,   -- the form as submitted (name, phone, document_number, email, …)
-  document_number   text,                                 -- normalised copy of payload.document_number
-  status            text NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'merged', 'created', 'quarantined', 'rejected')),
-  matched_person_id uuid,
-  quarantine_id     uuid REFERENCES public.person_identity_quarantine(id) ON DELETE SET NULL,
-  created_at        timestamptz NOT NULL DEFAULT now(),
-  updated_at        timestamptz NOT NULL DEFAULT now(),
-  processed_at      timestamptz,
-  processed_by      uuid,
-  FOREIGN KEY (tenant_id, matched_person_id) REFERENCES public.people(tenant_id, id) ON DELETE SET NULL
-);
-CREATE INDEX IF NOT EXISTS person_registrations_pending_idx ON public.person_registrations (tenant_id, status, created_at);
-CREATE INDEX IF NOT EXISTS person_registrations_document_idx ON public.person_registrations (tenant_id, document_number) WHERE document_number IS NOT NULL;
-
--- the document column mirrors the payload, normalised
-CREATE OR REPLACE FUNCTION public.trg_person_registrations_normalize()
-RETURNS trigger LANGUAGE plpgsql AS $$
-BEGIN
-  NEW.document_number := public.people_normalize_document(coalesce(NEW.document_number, NEW.payload ->> 'document_number'));
-  RETURN NEW;
-END $$;
-DROP TRIGGER IF EXISTS person_registrations_normalize ON public.person_registrations;
-CREATE TRIGGER person_registrations_normalize
-  BEFORE INSERT OR UPDATE OF payload, document_number ON public.person_registrations
-  FOR EACH ROW EXECUTE FUNCTION public.trg_person_registrations_normalize();
-
-SELECT app.scaffold_table('public.person_registrations', 'people.person_registration', 'people', false, 'enforce');
-GRANT SELECT, INSERT, UPDATE, DELETE ON public.person_registrations TO authenticated;
-GRANT ALL ON public.person_registrations TO service_role;
-REVOKE ALL ON public.person_registrations FROM anon;
-
--- Turns a registration into a Person. Actions:
---   'process' (default) — the dedup rules above, from 'pending'
---   'create'            — a human decided it is a new person, from 'quarantined'
---   'merge'             — a human picked p_person_id, from 'quarantined' (people.manage)
---   'reject'            — from 'pending' or 'quarantined'
--- Requires people.create in the registration's unit. Returns
--- {registration_id, status, person_id}. Never edits an existing person's data.
-CREATE OR REPLACE FUNCTION public.person_registrations_process(p_id uuid, p_action text DEFAULT 'process', p_person_id uuid DEFAULT NULL)
-RETURNS jsonb
-LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
-AS $$
-DECLARE
-  v_tenant  uuid := app.current_tenant_id();
-  v_actor   uuid := auth.uid();
-  r         public.person_registrations%ROWTYPE;
-  v_email   text;
-  v_phone   text;
-  v_by_doc  uuid[];
-  v_by_sig  uuid[];
-  v_person  uuid;
-  v_q       uuid;
-  v_status  text;
-BEGIN
-  IF v_tenant IS NULL THEN RAISE EXCEPTION 'no active tenant for this session' USING ERRCODE = '42501'; END IF;
-  IF p_action NOT IN ('process', 'create', 'merge', 'reject') THEN
-    RAISE EXCEPTION 'person_registrations_process: unknown action %', p_action USING ERRCODE = '22023';
-  END IF;
-  SELECT * INTO r FROM public.person_registrations WHERE tenant_id = v_tenant AND id = p_id FOR UPDATE;
-  IF NOT FOUND THEN RAISE EXCEPTION 'person_registrations_process: registration not found in this tenant' USING ERRCODE = 'P0002'; END IF;
-  PERFORM public.people_assert_scope(CASE WHEN p_action = 'merge' THEN 'people.manage' ELSE 'people.create' END, r.unit_id);
-
-  IF p_action = 'process' AND r.status <> 'pending' THEN
-    RAISE EXCEPTION 'person_registrations_process: only a pending registration can be processed (status %)', r.status USING ERRCODE = 'P0001';
-  END IF;
-  IF p_action IN ('create', 'merge') AND r.status <> 'quarantined' THEN
-    RAISE EXCEPTION 'person_registrations_process: % resolves a quarantined registration (status %)', p_action, r.status USING ERRCODE = 'P0001';
-  END IF;
-  IF p_action = 'reject' AND r.status NOT IN ('pending', 'quarantined') THEN
-    RAISE EXCEPTION 'person_registrations_process: registration already %', r.status USING ERRCODE = 'P0001';
-  END IF;
-
-  IF p_action = 'reject' THEN
-    UPDATE public.person_registrations SET status = 'rejected', processed_at = now(), processed_by = v_actor WHERE id = r.id;
-    RETURN jsonb_build_object('registration_id', r.id, 'status', 'rejected', 'person_id', NULL);
-  END IF;
-
-  IF p_action = 'merge' THEN
-    IF p_person_id IS NULL THEN RAISE EXCEPTION 'person_registrations_process: merge needs p_person_id' USING ERRCODE = '22023'; END IF;
-    SELECT p.id INTO v_person FROM public.people p WHERE p.tenant_id = v_tenant AND p.id = p_person_id AND p.merged_into_id IS NULL;
-    IF v_person IS NULL THEN RAISE EXCEPTION 'person_registrations_process: person not found in this tenant' USING ERRCODE = 'P0002'; END IF;
-    v_status := 'merged';
-  ELSIF p_action = 'create' THEN
-    v_person := NULL;
-    v_status := 'created';
-  ELSE
-    -- 'process': the dedup rules
-    v_email := nullif(lower(btrim(r.payload ->> 'email')), '');
-    v_phone := nullif(regexp_replace(coalesce(r.payload ->> 'phone', ''), '\D', '', 'g'), '');
-    IF r.document_number IS NOT NULL THEN
-      SELECT coalesce(array_agg(p.id ORDER BY p.created_at), '{}') INTO v_by_doc
-        FROM public.people p
-       WHERE p.tenant_id = v_tenant AND p.merged_into_id IS NULL AND p.document_number = r.document_number;
-    ELSE
-      v_by_doc := '{}';
-    END IF;
-    IF cardinality(v_by_doc) = 1 THEN
-      v_person := v_by_doc[1];
-      v_status := 'merged';
-    ELSIF cardinality(v_by_doc) > 1 THEN
-      v_status := 'quarantined';
-      v_by_sig := v_by_doc;
-    ELSE
-      -- no document match: a same e-mail / same phone person is a possible
-      -- duplicate the CPF cannot confirm — a human decides
-      SELECT coalesce(array_agg(p.id ORDER BY p.created_at), '{}') INTO v_by_sig
-        FROM public.people p
-       WHERE p.tenant_id = v_tenant AND p.merged_into_id IS NULL
-         AND ((v_email IS NOT NULL AND lower(p.email) = v_email)
-           OR (v_phone IS NOT NULL AND regexp_replace(coalesce(p.phone, ''), '\D', '', 'g') = v_phone));
-      IF cardinality(v_by_sig) > 0 THEN
-        v_status := 'quarantined';
-      ELSE
-        v_status := 'created';
-      END IF;
-    END IF;
-
-    IF v_status = 'quarantined' THEN
-      INSERT INTO public.person_identity_quarantine (tenant_id, document_number, person_ids, reason, context)
-      VALUES (v_tenant, r.document_number, v_by_sig,
-              CASE WHEN cardinality(v_by_doc) > 1 THEN 'registration: more than one person carries this document'
-                   ELSE 'registration: e-mail/phone match without a document match' END,
-              jsonb_build_object('source', 'person_registrations_process', 'registration_id', r.id))
-      ON CONFLICT (tenant_id, document_number) WHERE resolved_at IS NULL AND document_number IS NOT NULL DO UPDATE
-        SET person_ids = EXCLUDED.person_ids, context = public.person_identity_quarantine.context || EXCLUDED.context
-      RETURNING id INTO v_q;
-      UPDATE public.person_registrations SET status = 'quarantined', quarantine_id = v_q, processed_at = now(), processed_by = v_actor WHERE id = r.id;
-      RETURN jsonb_build_object('registration_id', r.id, 'status', 'quarantined', 'person_id', NULL, 'quarantine_id', v_q, 'candidates', to_jsonb(v_by_sig));
-    END IF;
-  END IF;
-
-  IF v_status = 'created' THEN
-    -- kind = 'customer' goes through the compat trigger: the customer role is
-    -- created as primary. Vertical fields stay in metadata.registration.
-    INSERT INTO public.people (tenant_id, unit_id, kind, name, email, phone, document_number, date_of_birth,
-                               address, city, state, country, postal_code, notes, metadata, created_by)
-    VALUES (v_tenant, r.unit_id, 'customer',
-            coalesce(nullif(btrim(r.payload ->> 'name'), ''), 'Sem nome'),
-            nullif(btrim(r.payload ->> 'email'), ''), nullif(btrim(r.payload ->> 'phone'), ''), r.document_number,
-            CASE WHEN (r.payload ->> 'date_of_birth') ~ '^\d{4}-\d{2}-\d{2}$' THEN (r.payload ->> 'date_of_birth')::date END,
-            nullif(r.payload ->> 'address', ''), nullif(r.payload ->> 'city', ''), nullif(r.payload ->> 'state', ''),
-            coalesce(nullif(r.payload ->> 'country', ''), 'BR'), nullif(r.payload ->> 'postal_code', ''), nullif(r.payload ->> 'notes', ''),
-            jsonb_build_object('registration', jsonb_build_object('id', r.id, 'unit_id', r.unit_id, 'payload', r.payload)),
-            v_actor)
-    RETURNING id INTO v_person;
-  ELSE
-    -- merged: the person exists; she is (also) a customer now. Nothing else is
-    -- overwritten — the registration keeps the payload for a human to compare.
-    IF NOT EXISTS (SELECT 1 FROM public.person_roles x WHERE x.tenant_id = v_tenant AND x.person_id = v_person AND x.role = 'customer'
-                    AND public.person_role_active(x.valid_from, x.valid_to)) THEN
-      INSERT INTO public.person_roles (tenant_id, person_id, role, unit_id, is_primary, metadata)
-      VALUES (v_tenant, v_person, 'customer', r.unit_id,
-              NOT EXISTS (SELECT 1 FROM public.person_roles x WHERE x.tenant_id = v_tenant AND x.person_id = v_person AND x.is_primary),
-              jsonb_build_object('source', 'person_registrations_process', 'registration_id', r.id))
-      ON CONFLICT DO NOTHING;
-      UPDATE public.person_roles x SET valid_to = NULL, valid_from = least(x.valid_from, current_date)
-       WHERE x.tenant_id = v_tenant AND x.person_id = v_person AND x.role = 'customer' AND NOT public.person_role_active(x.valid_from, x.valid_to)
-         AND NOT EXISTS (SELECT 1 FROM public.person_roles y WHERE y.tenant_id = v_tenant AND y.person_id = v_person AND y.role = 'customer' AND public.person_role_active(y.valid_from, y.valid_to));
-    END IF;
-  END IF;
-
-  UPDATE public.person_registrations
-     SET status = v_status, matched_person_id = v_person, processed_at = now(), processed_by = v_actor
-   WHERE id = r.id;
-  IF r.quarantine_id IS NOT NULL THEN
-    UPDATE public.person_identity_quarantine SET resolved_at = now(), resolved_by = v_actor, resolution = v_status || ':' || v_person::text
-     WHERE id = r.quarantine_id AND resolved_at IS NULL;
-  END IF;
-  INSERT INTO public.audit_logs (tenant_id, user_id, action, entity_type, entity_id, metadata)
-  VALUES (v_tenant, v_actor, 'people.registration.' || v_status, 'people', v_person::text, jsonb_build_object('registration_id', r.id, 'action', p_action));
-  RETURN jsonb_build_object('registration_id', r.id, 'status', v_status, 'person_id', v_person);
-END $$;
-REVOKE ALL ON FUNCTION public.person_registrations_process(uuid, text, uuid) FROM public, anon;
-GRANT EXECUTE ON FUNCTION public.person_registrations_process(uuid, text, uuid) TO authenticated, service_role;
-
--- ─────────────────────────────── access tokens ─────────────────────────
-CREATE TABLE IF NOT EXISTS public.person_access_tokens (
-  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,
-  token_hash  text NOT NULL,                     -- sha256(token), hex; the token itself is never stored
-  purpose     text NOT NULL,                     -- 'portal', 'pre_registration', 'consent', …
-  expires_at  timestamptz NOT NULL,
-  used_at     timestamptz,
-  created_by  uuid,
-  created_at  timestamptz NOT NULL DEFAULT now(),
-  updated_at  timestamptz NOT NULL DEFAULT now(),
-  CHECK (purpose ~ '^[a-z][a-z0-9_]*$'),
-  FOREIGN KEY (tenant_id, person_id) REFERENCES public.people(tenant_id, id) ON DELETE CASCADE
-);
-CREATE UNIQUE INDEX IF NOT EXISTS person_access_tokens_hash_uidx ON public.person_access_tokens (token_hash);
-CREATE INDEX IF NOT EXISTS person_access_tokens_person_idx ON public.person_access_tokens (tenant_id, person_id, expires_at DESC);
-
-SELECT app.scaffold_table('public.person_access_tokens', 'people.person_access_token', 'people', false, 'enforce');
--- reads for the tenant's own tooling ("which tokens are open for this
--- person"), writes only through the RPCs below; anon nothing at all
-REVOKE ALL ON public.person_access_tokens FROM anon, authenticated;
-GRANT SELECT ON public.person_access_tokens TO authenticated;
-GRANT ALL ON public.person_access_tokens TO service_role;
-
--- Issues a token for a person of the session tenant (people.edit in her
--- unit); returns the opaque token exactly once. 256 bits from the CSPRNG
--- behind gen_random_uuid(); only its sha256 is stored.
-CREATE OR REPLACE FUNCTION public.person_access_token_issue(p_person uuid, p_purpose text, p_ttl interval DEFAULT interval '7 days')
-RETURNS text
-LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
-AS $$
-DECLARE
-  v_tenant uuid := app.current_tenant_id();
-  p        public.people%ROWTYPE;
-  v_token  text;
-BEGIN
-  IF v_tenant IS NULL THEN RAISE EXCEPTION 'no active tenant for this session' USING ERRCODE = '42501'; END IF;
-  SELECT * INTO p FROM public.people WHERE tenant_id = v_tenant AND id = p_person;
-  IF NOT FOUND THEN RAISE EXCEPTION 'person_access_token_issue: person not found in this tenant' USING ERRCODE = 'P0002'; END IF;
-  IF p.merged_into_id IS NOT NULL THEN RAISE EXCEPTION 'person_access_token_issue: person is a merge tombstone' USING ERRCODE = 'P0001'; END IF;
-  PERFORM public.people_assert_scope('people.edit', p.unit_id);
-  IF p_ttl IS NULL OR p_ttl <= interval '0' OR p_ttl > interval '90 days' THEN
-    RAISE EXCEPTION 'person_access_token_issue: ttl must be within (0, 90 days]' USING ERRCODE = '22023';
-  END IF;
-  v_token := replace(gen_random_uuid()::text || gen_random_uuid()::text, '-', '');
-  INSERT INTO public.person_access_tokens (tenant_id, person_id, unit_id, token_hash, purpose, expires_at, created_by)
-  VALUES (v_tenant, p_person, p.unit_id, encode(sha256(convert_to(v_token, 'UTF8')), 'hex'), p_purpose, now() + p_ttl, auth.uid());
-  RETURN v_token;
-END $$;
-REVOKE ALL ON FUNCTION public.person_access_token_issue(uuid, text, interval) FROM public, anon;
-GRANT EXECUTE ON FUNCTION public.person_access_token_issue(uuid, text, interval) TO authenticated, service_role;
-
--- Redeems a token: single use, expiring, callable by anon (the portal link).
--- Unknown, used and expired all fail the same way — no oracle. Returns the
--- person id; what the portal may then read is Phase 1's contract.
-CREATE OR REPLACE FUNCTION public.person_access_token_redeem(p_token text)
-RETURNS uuid
-LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
-AS $$
-DECLARE
-  t public.person_access_tokens%ROWTYPE;
-BEGIN
-  IF p_token IS NULL OR length(p_token) < 32 THEN
-    RAISE EXCEPTION 'invalid or expired token' USING ERRCODE = '28000';
-  END IF;
-  SELECT * INTO t FROM public.person_access_tokens
-   WHERE token_hash = encode(sha256(convert_to(p_token, 'UTF8')), 'hex')
-   FOR UPDATE;
-  IF NOT FOUND OR t.used_at IS NOT NULL OR t.expires_at <= now() THEN
-    RAISE EXCEPTION 'invalid or expired token' USING ERRCODE = '28000';
-  END IF;
-  UPDATE public.person_access_tokens SET used_at = now() WHERE id = t.id;
-  RETURN t.person_id;
-END $$;
-REVOKE ALL ON FUNCTION public.person_access_token_redeem(text) FROM public;
-GRANT EXECUTE ON FUNCTION public.person_access_token_redeem(text) TO anon, authenticated, service_role;
-
-COMMENT ON TABLE public.person_registrations IS
-  'Pre-registration queue (V1 client_registrations): the raw form per unit; person_registrations_process() creates or matches the Person with dedup by exact CPF, quarantining ambiguity.';
-COMMENT ON TABLE public.person_access_tokens IS
-  'Opaque single-use expiring tokens for the client portal (V1 client_access_tokens). Only sha256 hashes; issue via person_access_token_issue(), redeem via person_access_token_redeem() (anon-callable). No anon SELECT.';