@fayz-ai/db 0.12.0 → 0.13.0

package/migrations/082_people_membership_link.sql

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

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

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