@fayz-ai/db 0.13.0 → 0.14.0

package/migrations/114_migrations_ledger_immutable.sql

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

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

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

@@ -1,82 +0,0 @@
--- 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$;