@fayz-ai/db 0.11.0 → 0.13.0

package/migrations/114_migrations_ledger_immutable.sql

@@ -0,0 +1,65 @@
+-- 114_migrations_ledger_immutable.sql
+--
+-- The migration ledger stops being append-only by politeness. Fix for #145.
+--
+-- `public._migrations` is what `fayz db apply` reads to know what has run and to
+-- detect checksum drift. It had RLS enabled and **zero policies**, which sounds
+-- locked — but `service_role` holds BYPASSRLS, so as far as the API was concerned
+-- the ledger was an ordinary writable table: `UPDATE 1`, `DELETE 1`, both
+-- succeeded. A client could quietly tell the applier that a migration it never
+-- ran has already run, or that one it did run has not.
+--
+-- WHAT "APPEND-ONLY" ACTUALLY MEANS HERE, because the criterion overstates it and
+-- the chain itself proves the overstatement: `107_core_table_prefix.sql:359`
+-- deliberately DELETEs a ledger row so the next apply re-runs a file that had no
+-- fix-forward form. Forgetting a row is a legitimate migration act. A rule that
+-- forbade it would be a rule the chain breaks on line one.
+--
+-- So the enforceable property is not "nothing is ever deleted". It is:
+--
+--   1. no API role touches the ledger at all — not anon, not authenticated, and
+--      not service_role, which is the one that could;
+--   2. a row's IDENTITY never changes. `checksum`, `applied_at`, `applied_by` and
+--      `plugin_version` move when a file is legitimately re-applied after an
+--      edit — that is how drift detection works — but the (plugin_id, file_name)
+--      a row stands for is fixed for its life. Rewriting that is not a
+--      correction, it is a forgery: it makes one file's history describe another.
+--
+-- The applier connects through the Supabase Management API, which runs as
+-- `postgres`, so it is unaffected. This is a boundary between the applier and the
+-- API, not a freeze.
+--
+-- Replay-safe: CREATE OR REPLACE + DROP/CREATE TRIGGER, no data touched.
+
+CREATE OR REPLACE FUNCTION app.migrations_ledger_guard()
+RETURNS trigger LANGUAGE plpgsql SECURITY INVOKER SET search_path = '' AS $$
+BEGIN
+  -- 1. the ledger belongs to the applier, not to the API surface
+  IF current_user IN ('anon', 'authenticated', 'service_role') THEN
+    RAISE EXCEPTION
+      'public._migrations is the migration applier''s ledger — % may not write it', current_user
+      USING ERRCODE = '42501',
+            HINT = 'Apply migrations with `fayz db apply`, which owns this table and detects checksum drift.';
+  END IF;
+
+  -- 2. a row's identity is fixed for its life; its provenance is not
+  IF TG_OP = 'UPDATE' AND (NEW.id <> OLD.id
+                           OR NEW.plugin_id <> OLD.plugin_id
+                           OR NEW.file_name <> OLD.file_name) THEN
+    RAISE EXCEPTION
+      'public._migrations: the (plugin_id, file_name) of ledger row % cannot change — that would make one file''s history describe another', OLD.id
+      USING ERRCODE = '42501',
+            HINT = 'Re-applying an edited file updates its checksum; it does not move the row to a different file.';
+  END IF;
+
+  RETURN CASE WHEN TG_OP = 'DELETE' THEN OLD ELSE NEW END;
+END $$;
+REVOKE ALL ON FUNCTION app.migrations_ledger_guard() FROM public, anon, authenticated;
+
+DROP TRIGGER IF EXISTS migrations_ledger_guard ON public._migrations;
+CREATE TRIGGER migrations_ledger_guard
+  BEFORE INSERT OR UPDATE OR DELETE ON public._migrations
+  FOR EACH ROW EXECUTE FUNCTION app.migrations_ledger_guard();
+
+COMMENT ON TABLE public._migrations IS
+  'The migration applier''s ledger (#145). Client-immutable: no API role may write it (104). A row''s (plugin_id, file_name) is fixed for its life; checksum/applied_at/applied_by move when a file is legitimately re-applied after an edit, which is how drift detection works. A migration may forget a row (097 does, deliberately) — that is an applier act, not a client one.';

package/migrations/115_registration_honours_field_rules.sql

@@ -0,0 +1,172 @@
+-- 115_registration_honours_field_rules.sql
+--
+-- The validation API gets its first caller. Fix for #144.
+--
+-- #144 shipped FieldRules with three states per tenant, per unit and per context,
+-- a resolver, and `field_rules_check`, which raises in pt-BR with a HINT. All of
+-- it works. Nothing called it. `095_config_field_rules.sql:16` even names the
+-- caller it expected -- "the check-in RPC calls field_rules_check('check_in',
+-- 'person', ...)" -- and that RPC does not exist; plugin-agenda ships fifteen
+-- migrations and no check-in.
+--
+-- So the acceptance sentence ("a required FieldRule blocks the RPC in pt-BR") had
+-- no RPC to block, and a mechanism nobody invokes is indistinguishable from one
+-- that does not work.
+--
+-- `person_registrations_process` is the natural host and was the clearest
+-- illustration of the gap: it read `payload ->> 'name'` and, when that was empty,
+-- wrote the Person anyway under the name 'Sem nome'. A tenant that had declared
+-- name REQUIRED for pre-registration got a row called "Sem nome".
+--
+-- The check goes in before the INSERT, on the `pre_registration` context, scoped
+-- to the registration's own unit so a branch's stricter rule applies. A tenant
+-- with no rule for that context is unaffected -- the check returns {} and the
+-- call is a no-op -- so this changes behaviour only where somebody asked for it.
+--
+-- The other half of #144's acceptance (a hidden field never reaching the payload)
+-- is a read-side concern and is not addressed here; it stays on the issue.
+--
+-- Replay-safe: CREATE OR REPLACE of one function, no DDL, no data touched.
+
+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
+    -- The tenant's FieldRules for this context decide whether this payload may
+    -- become a Person at all. Until now field_rules_check had ZERO callers: the
+    -- rules resolved, raised in pt-BR, and nothing ever asked them — while this
+    -- very statement defaulted a missing name to 'Sem nome' and wrote the row
+    -- (#144). A tenant with no pre_registration rule is unaffected: the check
+    -- returns {} and this is a no-op.
+    PERFORM public.field_rules_check('pre_registration', 'person', r.payload, r.unit_id);
+
+    -- 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 $$;

package/migrations/116_field_rules_check_needs_a_tenant.sql

@@ -0,0 +1,72 @@
+-- 116_field_rules_check_needs_a_tenant.sql
+--
+-- A validator that cannot see the rules must not approve. Fix for #147.
+--
+-- `field_rules_check` resolves the tenant from `app.current_tenant_id()`, which
+-- reads the JWT. With no claim there is no tenant, so `field_rules_validate`
+-- finds no rules, so nothing is ever "missing", so the function returns the
+-- payload untouched -- a clean pass on a payload containing none of the required
+-- fields.
+--
+-- That is not hypothetical. `11-verification-suite.md` told the QA Agent to run
+-- its invariants as `service_role`, and US-PLT-ADM-07 claims this function raises
+-- 23514 for a missing required field. Run exactly as documented it returned `{}`,
+-- so **the agent got a silent pass on the very violation it was checking for**.
+--
+-- The doc is corrected in the same commit to say "as the persona". This is the
+-- half that does not depend on anyone reading it: with no tenant, the function
+-- refuses instead of approving. Failing closed is the only safe direction for a
+-- validator -- a false "valid" is worse than an error, because it is invisible.
+--
+-- ONE TRAP WORTH RECORDING, because it cost a bench run and will catch the next
+-- person. 097 renamed the eight core tables AND rewrote every function body that
+-- referenced them, with pg_get_functiondef + regexp_replace. So the live body of
+-- this function says `entity_fields`, while 085 -- the file it is defined in --
+-- still says `plg_entity_fields`, because applied files are never edited. Lifting
+-- a function from its original file after 097 therefore RESURRECTS the old table
+-- name and the function breaks at its first call:
+--
+--     ERROR: relation "public.plg_entity_fields" does not exist
+--
+-- The reference below is the post-097 name on purpose. scripts/check-post-097-names.mjs
+-- now fails CI on any migration after 097 that mentions one of the eight old names.
+--
+-- Replay-safe: CREATE OR REPLACE of one function, no DDL, no data touched.
+
+CREATE OR REPLACE FUNCTION public.field_rules_check(p_context text, p_reference text, p_payload jsonb, p_unit uuid DEFAULT NULL)
+RETURNS jsonb
+LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_res    jsonb := public.field_rules_validate(p_context, p_reference, p_payload, p_unit);
+  v_tenant uuid := app.current_tenant_id();
+  v_labels text;
+BEGIN
+  -- Without a tenant there are no rules, so nothing is ever "missing" and this
+  -- returns the payload untouched — a caller checking for a required field gets
+  -- a clean pass on a payload that has none of them. That is what happened to the
+  -- QA Agent hooks (#147): the doc told them to run as `service_role`, which
+  -- carries no JWT, so ADM-07 silently returned {} where it claimed to raise.
+  -- A validator that cannot see the rules must say so, not approve.
+  IF v_tenant IS NULL THEN
+    RAISE EXCEPTION 'field_rules_check: no active tenant — the rules cannot be resolved, so nothing can be validated'
+      USING ERRCODE = '42501',
+            HINT = 'Call this as the persona whose form is being validated. service_role carries no tenant claim.';
+  END IF;
+  IF (v_res ->> 'ok')::boolean THEN
+    RETURN v_res -> 'payload';
+  END IF;
+  SELECT string_agg(coalesce(
+           (SELECT f.label FROM public.entity_fields f
+             WHERE f.reference = p_reference AND f.key = k.key
+               AND (f.tenant_id IS NULL OR f.tenant_id = v_tenant)
+               AND f.archived_at IS NULL AND nullif(btrim(f.label), '') IS NOT NULL
+             ORDER BY f.tenant_id NULLS LAST LIMIT 1),
+           k.key), ', ' ORDER BY k.ord)
+    INTO v_labels
+    FROM jsonb_array_elements_text(v_res -> 'missing') WITH ORDINALITY AS k(key, ord);
+  RAISE EXCEPTION 'Campo obrigatório: %', v_labels
+    USING ERRCODE = '23514',
+          DETAIL = format('field_rules_check: required fields missing for %s/%s: %s', p_context, p_reference, (v_res -> 'missing')::text),
+          HINT = 'Preencha os campos obrigatórios antes de continuar.';
+END $$;

package/migrations/117_authz_reconciliation_schedule.sql

@@ -0,0 +1,82 @@
+-- 117_authz_reconciliation_schedule.sql
+--
+-- The reconciliation alert stops being a view nobody queries. Fix for #133.
+--
+-- #133's criterion is "`recompute_user_unit_access` + diff-log; runs after authz
+-- migrations and on demand; **alert when diff ≠ 0 outside migrations**". What
+-- shipped for the last clause was `public.v_authz_reconciliation_alerts` — a
+-- correct view over the diff log, and nothing that ever reads it. Nothing was
+-- scheduled, no channel existed, and `source = 'scheduled'` appeared nowhere in
+-- the repo, so on a built database the log held only rows the migrations and the
+-- tests wrote. An alert nobody runs is a query, and the difference matters most
+-- in the case the alert exists for: `user_unit_access` is a PRECOMPUTED
+-- projection, so a drift there is not a slow page — it is a person seeing units
+-- they should not, or losing units they should have, silently, until someone
+-- happens to look.
+--
+-- Three parts, and the third is the one that makes it an alert:
+--
+--   1. `app.authz_reconcile_all()` — recompute every tenant with source
+--      'scheduled', returning what it changed. It fixes as it goes: the
+--      projection is derived, so the recompute IS the repair, and leaving a
+--      known-wrong access row in place to preserve evidence would be choosing
+--      forensics over the person who cannot see her own unit. The diff log keeps
+--      the evidence.
+--   2. a pg_cron job at 03:41, following the idiom of 033 (guarded on pg_cron
+--      being present, idempotent by job name, off-peak and off-the-hour so it
+--      does not stampede with every other platform's 03:00).
+--   3. `app.authz_alert_reconciliation()` — RAISES WARNING per drifting tenant,
+--      so a non-zero diff reaches the Postgres log and anything tailing it,
+--      instead of sitting in a table. This is the honest ceiling for what a
+--      migration can wire on its own: routing to Slack or a pager needs an
+--      endpoint the platform owns, and inventing one here would be a channel
+--      nobody is on.
+--
+-- Replay-safe: CREATE OR REPLACE, cron.schedule upserts by job name.
+
+CREATE OR REPLACE FUNCTION app.authz_reconcile_all()
+RETURNS TABLE (tenant_id uuid, added integer, removed integer)
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE r record; v record;
+BEGIN
+  FOR r IN SELECT t.id FROM public.tenants t ORDER BY t.id LOOP
+    SELECT * INTO v FROM app.recompute_user_unit_access(r.id, 'scheduled');
+    IF v.added <> 0 OR v.removed <> 0 THEN
+      tenant_id := r.id; added := v.added; removed := v.removed;
+      RETURN NEXT;
+    END IF;
+  END LOOP;
+END $$;
+REVOKE ALL ON FUNCTION app.authz_reconcile_all() FROM public, anon, authenticated;
+
+-- The alert itself. A WARNING is what a migration can reach on its own; the
+-- platform decides where the log goes.
+CREATE OR REPLACE FUNCTION app.authz_alert_reconciliation()
+RETURNS integer LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE r record; v_n integer := 0;
+BEGIN
+  FOR r IN SELECT * FROM app.authz_reconcile_all() LOOP
+    v_n := v_n + 1;
+    RAISE WARNING 'authz drift: tenant % had user_unit_access repaired (+% / -%). A precomputed access row was wrong until now — see public.v_authz_reconciliation_alerts',
+      r.tenant_id, r.added, r.removed;
+  END LOOP;
+  IF v_n = 0 THEN
+    RAISE NOTICE 'authz reconciliation: no drift';
+  END IF;
+  RETURN v_n;
+END $$;
+REVOKE ALL ON FUNCTION app.authz_alert_reconciliation() FROM public, anon, authenticated;
+
+DO $do$
+BEGIN
+  IF to_regprocedure('cron.schedule(text, text, text)') IS NULL THEN
+    RAISE WARNING 'pg_cron is not available: authz reconciliation is NOT scheduled on this pool — a drift in user_unit_access would go unnoticed';
+    RETURN;
+  END IF;
+  -- 03:41: off-peak, and off the hour so it does not land with every other
+  -- platform's 03:00 job. Daily, because the fan-out triggers keep the projection
+  -- right in the same transaction — this is the net that catches what a trigger
+  -- could not see (a restore, a manual fix, a bug), not the primary mechanism.
+  PERFORM cron.schedule('fayz_authz_reconcile', '41 3 * * *',
+                        $cmd$SELECT app.authz_alert_reconciliation()$cmd$);
+END $do$;