@fayz-ai/db 0.12.0 → 0.13.0

package/migrations/102_migration_rpcs.sql

@@ -0,0 +1,933 @@
+-- ============================================================================
+-- 102_migration_rpcs.sql — the destination RPCs of the migration contract
+-- (PRD 10 / #148): batches, fence + kill switch (ADR 0008), the generic
+-- upsert-by-uuid entry point (ADR 0007), the column mapper, and the typed
+-- writers for the core-A destinations that exist today (person, unit,
+-- category, product, order; invoice guarded on the financial slice's table).
+--
+-- Every function: SECURITY DEFINER SET search_path = '', executable by
+-- service_role only (the extractor's credential). None relies on auth.uid():
+-- the actor is the service, the tenant comes from the batch. Business rules:
+--   • allowlist first (unknown/excluded table ⇒ quarantine 'allowlist')
+--   • fence second (not fenced / kill switch ⇒ raise, nothing recorded)
+--   • id = source uuid when present, else minted once and kept in the ledger
+--   • same source row + same checksum ⇒ 'skipped' with no effect; older cursor
+--     ⇒ 'skipped: stale cursor'; changed row ⇒ upsert unless a financial
+--     value would change (⇒ quarantine 'value', destination untouched)
+--   • ambiguity of tenant / identity (CPF) / state / value / fk ⇒ quarantine,
+--     never a silent correction
+--   • every effective write lands an audit_logs row (action migration.upsert)
+-- ============================================================================
+
+-- ─────────────────────────────── small helpers ─────────────────────────
+CREATE OR REPLACE FUNCTION migration._has_column(p_table text, p_col text) RETURNS boolean
+LANGUAGE sql STABLE SET search_path = '' AS $$
+  SELECT to_regclass(p_table) IS NOT NULL AND EXISTS (
+    SELECT 1 FROM pg_attribute a WHERE a.attrelid = to_regclass(p_table) AND a.attname = p_col AND a.attnum > 0 AND NOT a.attisdropped)
+$$;
+
+-- Cursors are opaque strings ordered lexicographically (ISO-8601 UTC timestamps,
+-- zero-padded sequences); two all-digit cursors compare numerically.
+CREATE OR REPLACE FUNCTION migration.cursor_cmp(a text, b text) RETURNS integer
+LANGUAGE sql IMMUTABLE AS $$
+  SELECT CASE
+    WHEN a IS NULL AND b IS NULL THEN 0
+    WHEN a IS NULL THEN -1
+    WHEN b IS NULL THEN 1
+    WHEN a ~ '^\d+$' AND b ~ '^\d+$' THEN sign(a::numeric - b::numeric)::integer
+    WHEN a < b THEN -1 WHEN a > b THEN 1 ELSE 0 END
+$$;
+
+CREATE OR REPLACE FUNCTION migration._deep_set(p_target jsonb, p_path text[], p_value jsonb) RETURNS jsonb
+LANGUAGE plpgsql IMMUTABLE AS $$
+DECLARE v_child jsonb;
+BEGIN
+  IF p_path IS NULL OR array_length(p_path, 1) IS NULL THEN RETURN p_target; END IF;
+  IF array_length(p_path, 1) = 1 THEN
+    RETURN jsonb_set(coalesce(p_target, '{}'::jsonb), p_path, p_value, true);
+  END IF;
+  v_child := coalesce(p_target -> p_path[1], '{}'::jsonb);
+  IF jsonb_typeof(v_child) <> 'object' THEN v_child := '{}'::jsonb; END IF;
+  RETURN jsonb_set(coalesce(p_target, '{}'::jsonb), p_path[1:1], migration._deep_set(v_child, p_path[2:], p_value), true);
+END $$;
+
+-- metadata merge: incoming keys win, except metadata.migration where roles are
+-- unioned and merged_from is concatenated (a merged Person keeps every origin).
+CREATE OR REPLACE FUNCTION migration._merge_meta(p_existing jsonb, p_incoming jsonb) RETURNS jsonb
+LANGUAGE plpgsql IMMUTABLE AS $$
+DECLARE
+  v jsonb := coalesce(p_existing, '{}'::jsonb) || coalesce(p_incoming, '{}'::jsonb);
+  v_m jsonb;
+  v_roles jsonb;
+  v_from jsonb;
+BEGIN
+  IF (p_existing ? 'migration') AND (p_incoming ? 'migration') THEN
+    v_m := (p_existing -> 'migration') || (p_incoming -> 'migration');
+    SELECT coalesce(jsonb_agg(DISTINCT r ORDER BY r), '[]'::jsonb) INTO v_roles
+      FROM (SELECT jsonb_array_elements_text(coalesce(p_existing #> '{migration,roles}', '[]'::jsonb)) r
+            UNION SELECT jsonb_array_elements_text(coalesce(p_incoming #> '{migration,roles}', '[]'::jsonb))) s;
+    v_from := coalesce(p_existing #> '{migration,merged_from}', '[]'::jsonb) || coalesce(p_incoming #> '{migration,merged_from}', '[]'::jsonb);
+    IF jsonb_array_length(v_roles) > 0 THEN v_m := v_m || jsonb_build_object('roles', v_roles); END IF;
+    IF jsonb_array_length(v_from) > 0 THEN v_m := v_m || jsonb_build_object('merged_from', v_from); END IF;
+    v := jsonb_set(v, '{migration}', v_m, true);
+  END IF;
+  RETURN v;
+END $$;
+
+-- The one hq per tenant / any other index the destination enforces is a state
+-- the migration must not resolve on its own; the writers convert those into
+-- quarantines. This sets unit_id only where the scaffold added the column.
+CREATE OR REPLACE FUNCTION migration._set_unit(p_table text, p_id uuid, p_unit uuid) RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  IF p_unit IS NULL OR NOT migration._has_column(p_table, 'unit_id') THEN RETURN; END IF;
+  EXECUTE format('UPDATE %s SET unit_id = $1 WHERE id = $2', p_table) USING p_unit, p_id;
+END $$;
+
+CREATE OR REPLACE FUNCTION migration._destination_values(p_table text, p_id uuid, p_cols text[]) RETURNS jsonb
+LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = '' AS $$
+DECLARE v jsonb; v_out jsonb;
+BEGIN
+  IF p_id IS NULL OR to_regclass(p_table) IS NULL THEN RETURN NULL; END IF;
+  EXECUTE format('SELECT to_jsonb(t) FROM %s t WHERE t.id = $1', p_table) INTO v USING p_id;
+  IF v IS NULL THEN RETURN NULL; END IF;
+  SELECT coalesce(jsonb_object_agg(c, v -> c), '{}'::jsonb) INTO v_out FROM unnest(coalesce(p_cols, '{}')) c WHERE v ? c;
+  RETURN v_out;
+END $$;
+
+-- The fence gate every write goes through (ADR 0008).
+CREATE OR REPLACE FUNCTION migration._assert_fence(p_tenant uuid) RETURNS void
+LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = '' AS $$
+DECLARE v_state text; v_kill boolean;
+BEGIN
+  SELECT state, kill_switch INTO v_state, v_kill FROM migration.tenant_fence WHERE tenant_id = p_tenant;
+  IF v_state IS NULL OR v_state NOT IN ('fenced', 'v2_writer') THEN
+    RAISE EXCEPTION 'tenant % is not fenced for migration (fence state: %)', p_tenant, coalesce(v_state, 'none')
+      USING ERRCODE = '55000', HINT = 'migration.fence_set(tenant, ''fenced'') opens the destination for migration writes.';
+  END IF;
+  IF v_kill THEN
+    RAISE EXCEPTION 'kill switch is on for tenant %: the tenant went back to V1', p_tenant USING ERRCODE = '55000';
+  END IF;
+END $$;
+
+-- ─────────────────────────────── fence + kill switch ───────────────────
+CREATE OR REPLACE FUNCTION migration.fence_set(p_tenant uuid, p_state text) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE f migration.tenant_fence%ROWTYPE;
+BEGIN
+  IF p_state NOT IN ('v1_writer', 'fenced', 'v2_writer') THEN
+    RAISE EXCEPTION 'fence_set: state must be v1_writer|fenced|v2_writer (got %)', p_state USING ERRCODE = '22023';
+  END IF;
+  INSERT INTO migration.tenant_fence (tenant_id) VALUES (p_tenant) ON CONFLICT (tenant_id) DO NOTHING;
+  SELECT * INTO f FROM migration.tenant_fence WHERE tenant_id = p_tenant FOR UPDATE;
+  IF p_state = 'v1_writer' AND f.first_v2_write_at IS NOT NULL THEN
+    RAISE EXCEPTION 'PONR passed for tenant % at %: it cannot return to V1 (ADR 0008)', p_tenant, f.first_v2_write_at USING ERRCODE = '55000';
+  END IF;
+  IF p_state <> 'v1_writer' AND f.kill_switch THEN
+    RAISE EXCEPTION 'kill switch is on for tenant %: turn it off before fencing again', p_tenant USING ERRCODE = '55000';
+  END IF;
+  UPDATE migration.tenant_fence
+     SET state = p_state,
+         fenced_at = CASE WHEN p_state = 'fenced' THEN coalesce(fenced_at, now()) ELSE fenced_at END
+   WHERE tenant_id = p_tenant
+   RETURNING * INTO f;
+  RETURN to_jsonb(f);
+END $$;
+
+CREATE OR REPLACE FUNCTION migration.kill_switch(p_tenant uuid, p_on boolean) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE f migration.tenant_fence%ROWTYPE;
+BEGIN
+  INSERT INTO migration.tenant_fence (tenant_id) VALUES (p_tenant) ON CONFLICT (tenant_id) DO NOTHING;
+  SELECT * INTO f FROM migration.tenant_fence WHERE tenant_id = p_tenant FOR UPDATE;
+  IF p_on THEN
+    IF f.first_v2_write_at IS NOT NULL THEN
+      RAISE EXCEPTION 'PONR passed for tenant % at %: the kill switch cannot return it to V1 (ADR 0008)', p_tenant, f.first_v2_write_at USING ERRCODE = '55000';
+    END IF;
+    UPDATE migration.tenant_fence SET kill_switch = true, state = 'v1_writer' WHERE tenant_id = p_tenant RETURNING * INTO f;
+  ELSE
+    UPDATE migration.tenant_fence SET kill_switch = false WHERE tenant_id = p_tenant RETURNING * INTO f;
+  END IF;
+  RETURN to_jsonb(f);
+END $$;
+
+-- The point of no return: the first exclusive V2 write of a fenced tenant.
+-- Called by the triggers of 093 (canonical) or by a service that knows it just
+-- wrote as V2. Idempotent; a no-op for tenants without a fence row.
+CREATE OR REPLACE FUNCTION migration.mark_v2_write(p_tenant uuid) RETURNS void
+LANGUAGE sql SECURITY DEFINER SET search_path = '' AS $$
+  UPDATE migration.tenant_fence
+     SET first_v2_write_at = now()
+   WHERE tenant_id = p_tenant AND first_v2_write_at IS NULL AND state IN ('fenced', 'v2_writer');
+$$;
+
+-- ─────────────────────────────── batches ───────────────────────────────
+CREATE OR REPLACE FUNCTION migration.batch_open(p_tenant uuid, p_source_project text, p_cursor_from text DEFAULT NULL, p_source_tenant_id bigint DEFAULT NULL)
+RETURNS uuid LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE v_id uuid;
+BEGIN
+  IF p_source_project IS NULL OR btrim(p_source_project) = '' THEN
+    RAISE EXCEPTION 'batch_open: source_project is required' USING ERRCODE = '22023';
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM public.tenants WHERE id = p_tenant) THEN
+    RAISE EXCEPTION 'batch_open: unknown tenant %', p_tenant USING ERRCODE = 'P0002';
+  END IF;
+  INSERT INTO migration.batches (tenant_id, source_project, source_tenant_id, cursor_from)
+  VALUES (p_tenant, p_source_project, p_source_tenant_id, p_cursor_from)
+  RETURNING id INTO v_id;
+  RETURN v_id;
+END $$;
+
+CREATE OR REPLACE FUNCTION migration.batch_pause(p_batch uuid) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE b migration.batches%ROWTYPE;
+BEGIN
+  SELECT * INTO b FROM migration.batches WHERE id = p_batch FOR UPDATE;
+  IF NOT FOUND THEN RAISE EXCEPTION 'batch_pause: unknown batch %', p_batch USING ERRCODE = 'P0002'; END IF;
+  IF b.status <> 'running' THEN RAISE EXCEPTION 'batch_pause: batch % is % (only a running batch pauses)', p_batch, b.status USING ERRCODE = '55000'; END IF;
+  UPDATE migration.batches SET status = 'paused' WHERE id = p_batch RETURNING * INTO b;
+  RETURN to_jsonb(b);
+END $$;
+
+CREATE OR REPLACE FUNCTION migration.batch_resume(p_batch uuid) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE b migration.batches%ROWTYPE;
+BEGIN
+  SELECT * INTO b FROM migration.batches WHERE id = p_batch FOR UPDATE;
+  IF NOT FOUND THEN RAISE EXCEPTION 'batch_resume: unknown batch %', p_batch USING ERRCODE = 'P0002'; END IF;
+  IF b.status <> 'paused' THEN RAISE EXCEPTION 'batch_resume: batch % is % (only a paused batch resumes)', p_batch, b.status USING ERRCODE = '55000'; END IF;
+  UPDATE migration.batches SET status = 'running' WHERE id = p_batch RETURNING * INTO b;
+  RETURN to_jsonb(b);
+END $$;
+
+CREATE OR REPLACE FUNCTION migration.batch_close(p_batch uuid, p_status text DEFAULT 'done') RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE b migration.batches%ROWTYPE; v_counts jsonb; v_to text;
+BEGIN
+  IF p_status NOT IN ('done', 'failed') THEN RAISE EXCEPTION 'batch_close: status must be done|failed' USING ERRCODE = '22023'; END IF;
+  SELECT * INTO b FROM migration.batches WHERE id = p_batch FOR UPDATE;
+  IF NOT FOUND THEN RAISE EXCEPTION 'batch_close: unknown batch %', p_batch USING ERRCODE = 'P0002'; END IF;
+  IF b.status NOT IN ('running', 'paused') THEN RAISE EXCEPTION 'batch_close: batch % is already %', p_batch, b.status USING ERRCODE = '55000'; END IF;
+  SELECT coalesce(jsonb_object_agg(status, n), '{}'::jsonb) INTO v_counts
+    FROM (SELECT status, count(*) AS n FROM migration.ledger WHERE batch_id = p_batch GROUP BY status) s;
+  SELECT cursor INTO v_to FROM migration.ledger WHERE batch_id = p_batch AND cursor IS NOT NULL
+   ORDER BY CASE WHEN cursor ~ '^\d+$' THEN cursor::numeric END DESC NULLS LAST, cursor DESC LIMIT 1;
+  UPDATE migration.batches
+     SET status = p_status, finished_at = now(), cursor_to = coalesce(v_to, cursor_to),
+         counts = counts || jsonb_build_object('ledger', v_counts)
+   WHERE id = p_batch RETURNING * INTO b;
+  RETURN to_jsonb(b);
+END $$;
+
+CREATE OR REPLACE FUNCTION migration._count(p_batch uuid, p_outcome text) RETURNS void
+LANGUAGE sql SECURITY DEFINER SET search_path = '' AS $$
+  UPDATE migration.batches
+     SET counts = counts || jsonb_build_object(p_outcome, coalesce((counts ->> p_outcome)::integer, 0) + 1)
+   WHERE id = p_batch;
+$$;
+
+-- Where does the delta start? The highest cursor the destination has migrated
+-- for that tenant and source table (the extractor asks before each table).
+CREATE OR REPLACE FUNCTION migration.next_cursor(p_tenant uuid, p_source_table text) RETURNS text
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = '' AS $$
+  SELECT cursor FROM migration.ledger
+   WHERE tenant_id = p_tenant AND source_table = p_source_table AND status = 'migrated' AND cursor IS NOT NULL
+   ORDER BY CASE WHEN cursor ~ '^\d+$' THEN cursor::numeric END DESC NULLS LAST, cursor DESC
+   LIMIT 1;
+$$;
+
+-- ─────────────────────────────── references + mapping ──────────────────
+-- A V1 reference (numeric id or uuid) → the destination id through the ledger.
+-- p_target narrows to one destination when a source table splits (order|invoice).
+CREATE OR REPLACE FUNCTION migration.resolve_ref(p_project text, p_source_table text, p_value text, p_target text DEFAULT NULL)
+RETURNS uuid LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = '' AS $$
+DECLARE v_target text := p_target; v_id uuid;
+BEGIN
+  IF p_value IS NULL OR btrim(p_value) = '' THEN RETURN NULL; END IF;
+  IF v_target IS NULL THEN SELECT target_table INTO v_target FROM migration.allowlist WHERE source_table = p_source_table; END IF;
+  IF p_value ~ '^\d+$' THEN
+    SELECT target_id INTO v_id FROM migration.ledger
+     WHERE source_project = p_project AND source_table = p_source_table AND source_numeric_id = p_value::bigint
+       AND status = 'migrated' AND target_id IS NOT NULL AND (v_target IS NULL OR target_table = v_target)
+     LIMIT 1;
+  ELSIF p_value ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' THEN
+    SELECT target_id INTO v_id FROM migration.ledger
+     WHERE source_project = p_project AND source_table = p_source_table AND source_uuid = p_value::uuid
+       AND status = 'migrated' AND target_id IS NOT NULL AND (v_target IS NULL OR target_table = v_target)
+     LIMIT 1;
+  END IF;
+  RETURN v_id;
+END $$;
+
+-- Source-shaped row → {row: target-shaped columns, metadata: jsonb paths,
+-- unresolved: [{column, ref_table, ref}]}. Only mapped columns survive (R5).
+CREATE OR REPLACE FUNCTION migration.map_row(p_project text, p_source_table text, p_row jsonb) RETURNS jsonb
+LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  v_map jsonb; k text; spec text; v jsonb;
+  v_row jsonb := '{}'::jsonb; v_meta jsonb := '{}'::jsonb; v_unres jsonb := '[]'::jsonb;
+  v_col text; v_ref text; v_target text; v_resolved uuid; v_raw text;
+BEGIN
+  SELECT columns INTO v_map FROM migration.allowlist WHERE source_table = p_source_table;
+  FOR k, spec IN SELECT key, value #>> '{}' FROM jsonb_each(coalesce(v_map, '{}'::jsonb)) LOOP
+    v := p_row -> k;
+    IF v IS NULL OR spec IS NULL OR spec = '-' THEN CONTINUE; END IF;
+    IF spec LIKE 'jsonb:%' THEN
+      v_meta := migration._deep_set(v_meta, string_to_array(substr(spec, 7), '.'), v);
+    ELSIF position('@' IN spec) > 0 THEN
+      IF jsonb_typeof(v) = 'null' THEN CONTINUE; END IF;
+      v_col := split_part(spec, '@', 1);
+      v_ref := split_part(split_part(spec, '@', 2), ':', 1);
+      v_target := nullif(split_part(split_part(spec, '@', 2), ':', 2), '');
+      v_raw := v #>> '{}';
+      v_resolved := migration.resolve_ref(p_project, v_ref, v_raw, v_target);
+      IF v_resolved IS NULL THEN
+        v_unres := v_unres || jsonb_build_object('column', v_col, 'ref_table', v_ref, 'ref', v_raw);
+      ELSE
+        v_row := v_row || jsonb_build_object(v_col, v_resolved);
+      END IF;
+    ELSE
+      v_row := v_row || jsonb_build_object(spec, v);
+    END IF;
+  END LOOP;
+  RETURN jsonb_build_object('row', v_row, 'metadata', v_meta, 'unresolved', v_unres);
+END $$;
+
+-- ─────────────────────────────── typed writers ─────────────────────────
+-- Each takes the DESTINATION tenant, the destination id (ADR 0007), a
+-- target-shaped row (map_row output: columns + metadata) and writer args from
+-- the allowlist. Returns {status: migrated|quarantined|skipped, target_id,
+-- reason, kind (quarantine kind), merged, extra: [split rows]}. They are
+-- idempotent by id and callable on their own by service_role (then they check
+-- the fence and audit themselves; through upsert_row the ledger does).
+
+-- audit for standalone calls (upsert_row audits with the batch context)
+CREATE OR REPLACE FUNCTION migration._audit(p_tenant uuid, p_target_table text, p_target_id uuid, p_meta jsonb) RETURNS void
+LANGUAGE sql SECURITY DEFINER SET search_path = '' AS $$
+  INSERT INTO public.audit_logs (tenant_id, user_id, action, entity_type, entity_id, metadata)
+  VALUES (p_tenant, NULL, 'migration.upsert', p_target_table, p_target_id::text, coalesce(p_meta, '{}'::jsonb));
+$$;
+
+CREATE OR REPLACE FUNCTION migration._standalone() RETURNS boolean
+LANGUAGE sql STABLE AS $$ SELECT coalesce(current_setting('migration.batch', true), '') = '' $$;
+
+-- Person: one Person per human (people multi-role contract, 070/071). Dedup
+-- by the normalised document (people_normalize_document — the same form the
+-- people slice's partial unique index enforces): one live match ⇒ merge into
+-- the survivor (fill nulls, add the role in person_roles, remember the origin
+-- in metadata.migration.merged_from; the ledger rows point at the survivor);
+-- no document ⇒ new Person, unless someone already shares the same email AND
+-- phone (identity quarantine: merge only by exact document, PRD 03 R2). Roles
+-- are person_roles rows; people.kind is derived by the people slice's triggers.
+CREATE OR REPLACE FUNCTION migration._ensure_role(p_tenant uuid, p_person uuid, p_role text) RETURNS void
+LANGUAGE sql SECURITY DEFINER SET search_path = '' AS $$
+  INSERT INTO public.person_roles (tenant_id, person_id, role, is_primary)
+  VALUES (p_tenant, p_person, p_role,
+          NOT EXISTS (SELECT 1 FROM public.person_roles r WHERE r.tenant_id = p_tenant AND r.person_id = p_person AND r.is_primary))
+  ON CONFLICT DO NOTHING;
+$$;
+
+CREATE OR REPLACE FUNCTION migration.upsert_person(p_tenant uuid, p_id uuid, p_row jsonb, p_args jsonb DEFAULT '{}'::jsonb)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  v_role text := coalesce(p_args ->> 'role', 'customer');
+  v_doc text := public.people_normalize_document(p_row ->> 'document_number');
+  v_meta jsonb := coalesce(p_row -> 'metadata', '{}'::jsonb);
+  v_origin jsonb;
+  v_existing_tenant uuid;
+  v_tombstone uuid;
+  v_candidates uuid[];
+  v_n integer;
+  v_survivor uuid;
+  v_standalone boolean := migration._standalone();
+BEGIN
+  IF v_standalone THEN PERFORM migration._assert_fence(p_tenant); PERFORM set_config('migration.writer', 'on', true); END IF;
+  IF p_id IS NULL OR nullif(btrim(coalesce(p_row ->> 'name', '')), '') IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', 'a person needs an id and a name');
+  END IF;
+  IF v_role NOT IN ('customer', 'professional', 'employee', 'contact', 'supplier', 'lead') THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', format('unknown person role %s', v_role));
+  END IF;
+  v_origin := coalesce(v_meta -> 'migration', '{}'::jsonb) - 'merged_from';
+
+  SELECT tenant_id, merged_into_id INTO v_existing_tenant, v_tombstone FROM public.people WHERE id = p_id;
+  IF v_existing_tenant IS NOT NULL AND v_existing_tenant <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant', 'reason', format('person %s already exists in another tenant', p_id));
+  END IF;
+  IF v_tombstone IS NOT NULL THEN
+    -- the row was merged in V2 after it landed: the human's decision stands, the source now maps to the survivor
+    PERFORM migration._ensure_role(p_tenant, v_tombstone, v_role);
+    RETURN jsonb_build_object('status', 'migrated', 'target_id', v_tombstone, 'reason', 'merged', 'merged', true);
+  END IF;
+
+  IF v_existing_tenant IS NOT NULL THEN
+    -- the same source row again (delta): mapped columns override, the rest stays
+    UPDATE public.people SET
+      name = p_row ->> 'name',
+      email = CASE WHEN p_row ? 'email' THEN p_row ->> 'email' ELSE email END,
+      phone = CASE WHEN p_row ? 'phone' THEN p_row ->> 'phone' ELSE phone END,
+      document_number = CASE WHEN p_row ? 'document_number' THEN v_doc ELSE document_number END,
+      avatar_url = CASE WHEN p_row ? 'avatar_url' THEN p_row ->> 'avatar_url' ELSE avatar_url END,
+      date_of_birth = CASE WHEN p_row ? 'date_of_birth' THEN (p_row ->> 'date_of_birth')::date ELSE date_of_birth END,
+      address = CASE WHEN p_row ? 'address' THEN p_row ->> 'address' ELSE address END,
+      city = CASE WHEN p_row ? 'city' THEN p_row ->> 'city' ELSE city END,
+      state = CASE WHEN p_row ? 'state' THEN p_row ->> 'state' ELSE state END,
+      country = CASE WHEN p_row ? 'country' THEN p_row ->> 'country' ELSE country END,
+      postal_code = CASE WHEN p_row ? 'postal_code' THEN p_row ->> 'postal_code' ELSE postal_code END,
+      notes = CASE WHEN p_row ? 'notes' THEN p_row ->> 'notes' ELSE notes END,
+      is_active = CASE WHEN p_row ? 'is_active' THEN coalesce((p_row ->> 'is_active')::boolean, true) ELSE is_active END,
+      metadata = migration._merge_meta(metadata, v_meta)
+    WHERE id = p_id;
+    PERFORM migration._ensure_role(p_tenant, p_id, v_role);
+    PERFORM migration._set_unit('public.people', p_id, (p_row ->> 'unit_id')::uuid);
+    IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.people', p_id, jsonb_build_object('reason', 'updated')); END IF;
+    RETURN jsonb_build_object('status', 'migrated', 'target_id', p_id, 'reason', 'updated');
+  END IF;
+
+  IF v_doc IS NOT NULL THEN
+    SELECT array_agg(id) INTO v_candidates FROM public.people
+     WHERE tenant_id = p_tenant AND document_number = v_doc AND merged_into_id IS NULL;
+  ELSIF nullif(btrim(coalesce(p_row ->> 'email', '')), '') IS NOT NULL AND nullif(public.fayz_digits(p_row ->> 'phone'), '') IS NOT NULL THEN
+    SELECT array_agg(id) INTO v_candidates FROM public.people
+     WHERE tenant_id = p_tenant AND merged_into_id IS NULL AND lower(email) = lower(p_row ->> 'email')
+       AND public.fayz_digits(phone) = public.fayz_digits(p_row ->> 'phone');
+  END IF;
+  v_n := coalesce(array_length(v_candidates, 1), 0);
+
+  IF v_doc IS NOT NULL AND v_n >= 2 THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'identity',
+      'reason', format('ambiguous document: %s existing people share document %s', v_n, v_doc), 'candidates', to_jsonb(v_candidates));
+  END IF;
+  IF v_doc IS NULL AND v_n >= 1 THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'identity',
+      'reason', format('no document: %s existing person(s) share the same email and phone — merge only by exact document', v_n), 'candidates', to_jsonb(v_candidates));
+  END IF;
+
+  IF v_doc IS NOT NULL AND v_n = 1 THEN
+    v_survivor := v_candidates[1];
+    UPDATE public.people SET
+      email = coalesce(email, p_row ->> 'email'),
+      phone = coalesce(phone, p_row ->> 'phone'),
+      avatar_url = coalesce(avatar_url, p_row ->> 'avatar_url'),
+      date_of_birth = coalesce(date_of_birth, (p_row ->> 'date_of_birth')::date),
+      address = coalesce(address, p_row ->> 'address'),
+      city = coalesce(city, p_row ->> 'city'),
+      state = coalesce(state, p_row ->> 'state'),
+      country = coalesce(country, p_row ->> 'country'),
+      postal_code = coalesce(postal_code, p_row ->> 'postal_code'),
+      notes = coalesce(notes, p_row ->> 'notes'),
+      metadata = migration._merge_meta(metadata,
+        (v_meta - 'migration') || jsonb_build_object('migration', jsonb_build_object('merged_from', jsonb_build_array(v_origin))))
+    WHERE id = v_survivor;
+    PERFORM migration._ensure_role(p_tenant, v_survivor, v_role);
+    IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.people', v_survivor, jsonb_build_object('reason', 'merged', 'origin', v_origin)); END IF;
+    RETURN jsonb_build_object('status', 'migrated', 'target_id', v_survivor, 'reason', 'merged', 'merged', true);
+  END IF;
+
+  -- kind is written for compatibility only; the role row below is the truth
+  -- (fayz.people_kind_sync = on keeps the kind→role trigger quiet meanwhile)
+  PERFORM set_config('fayz.people_kind_sync', 'on', true);
+  INSERT INTO public.people (id, tenant_id, kind, name, email, phone, document_number, avatar_url, date_of_birth,
+                             address, city, state, country, postal_code, notes, is_active, metadata)
+  VALUES (p_id, p_tenant, coalesce(public.person_role_to_kind(v_role), v_role), p_row ->> 'name', p_row ->> 'email', p_row ->> 'phone', v_doc,
+          p_row ->> 'avatar_url', (p_row ->> 'date_of_birth')::date, p_row ->> 'address', p_row ->> 'city', p_row ->> 'state',
+          coalesce(p_row ->> 'country', 'BR'), p_row ->> 'postal_code', p_row ->> 'notes',
+          coalesce((p_row ->> 'is_active')::boolean, true), v_meta);
+  PERFORM set_config('fayz.people_kind_sync', 'off', true);
+  PERFORM migration._ensure_role(p_tenant, p_id, v_role);
+  PERFORM migration._set_unit('public.people', p_id, (p_row ->> 'unit_id')::uuid);
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.people', p_id, jsonb_build_object('reason', 'created')); END IF;
+  RETURN jsonb_build_object('status', 'migrated', 'target_id', p_id, 'reason', 'created');
+END $$;
+
+-- Unit: a V1 company (hq|branch) or location group (grouping branch).
+CREATE OR REPLACE FUNCTION migration.upsert_unit(p_tenant uuid, p_id uuid, p_row jsonb, p_args jsonb DEFAULT '{}'::jsonb)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  v_kind text;
+  v_meta jsonb := coalesce(p_row -> 'metadata', '{}'::jsonb);
+  v_existing_tenant uuid;
+  v_created boolean := false;
+  v_standalone boolean := migration._standalone();
+BEGIN
+  IF v_standalone THEN PERFORM migration._assert_fence(p_tenant); PERFORM set_config('migration.writer', 'on', true); END IF;
+  IF p_id IS NULL OR nullif(btrim(coalesce(p_row ->> 'name', '')), '') IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', 'a unit needs an id and a name');
+  END IF;
+  v_kind := CASE
+    WHEN coalesce(p_args ->> 'grouping', 'false') = 'true' THEN 'branch'
+    WHEN lower(coalesce(p_row ->> 'kind', '')) IN ('true', 't', 'hq') THEN 'hq'
+    WHEN lower(coalesce(p_row ->> 'kind', '')) IN ('false', 'f', 'branch') THEN 'branch'
+    ELSE coalesce(p_args ->> 'default_kind', 'branch') END;
+  IF coalesce(p_args ->> 'grouping', 'false') = 'true' THEN v_meta := v_meta || jsonb_build_object('grouping', true); END IF;
+
+  SELECT tenant_id INTO v_existing_tenant FROM app.units WHERE id = p_id;
+  IF v_existing_tenant IS NOT NULL AND v_existing_tenant <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant', 'reason', format('unit %s already exists in another tenant', p_id));
+  END IF;
+  BEGIN
+    IF v_existing_tenant IS NULL THEN
+      INSERT INTO app.units (tenant_id, id, kind, parent_unit_id, name, slug, active, metadata)
+      VALUES (p_tenant, p_id, v_kind, (p_row ->> 'parent_unit_id')::uuid, p_row ->> 'name', p_row ->> 'slug',
+              coalesce((p_row ->> 'active')::boolean, true), v_meta);
+      v_created := true;
+    ELSE
+      UPDATE app.units SET
+        kind = v_kind,
+        parent_unit_id = CASE WHEN p_row ? 'parent_unit_id' THEN (p_row ->> 'parent_unit_id')::uuid ELSE parent_unit_id END,
+        name = p_row ->> 'name',
+        slug = CASE WHEN p_row ? 'slug' THEN p_row ->> 'slug' ELSE slug END,
+        active = CASE WHEN p_row ? 'active' THEN coalesce((p_row ->> 'active')::boolean, true) ELSE active END,
+        metadata = migration._merge_meta(metadata, v_meta)
+      WHERE id = p_id;
+    END IF;
+  EXCEPTION WHEN unique_violation OR foreign_key_violation OR check_violation THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', format('%s: %s', SQLSTATE, SQLERRM));
+  END;
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'app.units', p_id, jsonb_build_object('reason', CASE WHEN v_created THEN 'created' ELSE 'updated' END)); END IF;
+  RETURN jsonb_build_object('status', 'migrated', 'target_id', p_id, 'reason', CASE WHEN v_created THEN 'created' ELSE 'updated' END);
+END $$;
+
+-- Category: shared categories(kind) of the catalog.
+CREATE OR REPLACE FUNCTION migration.upsert_category(p_tenant uuid, p_id uuid, p_row jsonb, p_args jsonb DEFAULT '{}'::jsonb)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  v_kind text := coalesce(p_args ->> 'kind', 'product');
+  v_meta jsonb := coalesce(p_row -> 'metadata', '{}'::jsonb);
+  v_existing_tenant uuid;
+  v_created boolean := false;
+  v_standalone boolean := migration._standalone();
+BEGIN
+  IF v_standalone THEN PERFORM migration._assert_fence(p_tenant); PERFORM set_config('migration.writer', 'on', true); END IF;
+  IF p_id IS NULL OR nullif(btrim(coalesce(p_row ->> 'name', '')), '') IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', 'a category needs an id and a name');
+  END IF;
+  SELECT tenant_id INTO v_existing_tenant FROM public.categories WHERE id = p_id;
+  IF v_existing_tenant IS NOT NULL AND v_existing_tenant <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant', 'reason', format('category %s already exists in another tenant', p_id));
+  END IF;
+  IF v_existing_tenant IS NULL THEN
+    INSERT INTO public.categories (id, tenant_id, kind, name, slug, parent_id, icon, color, sort_order, is_active, metadata)
+    VALUES (p_id, p_tenant, v_kind, p_row ->> 'name', p_row ->> 'slug', (p_row ->> 'parent_id')::uuid, p_row ->> 'icon', p_row ->> 'color',
+            coalesce((p_row ->> 'sort_order')::integer, 0), coalesce((p_row ->> 'is_active')::boolean, true), v_meta);
+    v_created := true;
+  ELSE
+    UPDATE public.categories SET
+      kind = v_kind, name = p_row ->> 'name',
+      slug = CASE WHEN p_row ? 'slug' THEN p_row ->> 'slug' ELSE slug END,
+      parent_id = CASE WHEN p_row ? 'parent_id' THEN (p_row ->> 'parent_id')::uuid ELSE parent_id END,
+      icon = CASE WHEN p_row ? 'icon' THEN p_row ->> 'icon' ELSE icon END,
+      color = CASE WHEN p_row ? 'color' THEN p_row ->> 'color' ELSE color END,
+      sort_order = CASE WHEN p_row ? 'sort_order' THEN (p_row ->> 'sort_order')::integer ELSE sort_order END,
+      is_active = CASE WHEN p_row ? 'is_active' THEN coalesce((p_row ->> 'is_active')::boolean, true) ELSE is_active END,
+      metadata = migration._merge_meta(metadata, v_meta)
+    WHERE id = p_id;
+  END IF;
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.categories', p_id, jsonb_build_object('reason', CASE WHEN v_created THEN 'created' ELSE 'updated' END)); END IF;
+  RETURN jsonb_build_object('status', 'migrated', 'target_id', p_id, 'reason', CASE WHEN v_created THEN 'created' ELSE 'updated' END);
+END $$;
+
+-- Product: catalog item kind good|service (products.kind when the catalog slice
+-- added the column, metadata.catalog.kind always).
+CREATE OR REPLACE FUNCTION migration.upsert_product(p_tenant uuid, p_id uuid, p_row jsonb, p_args jsonb DEFAULT '{}'::jsonb)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  v_kind text := coalesce(p_args ->> 'kind', 'good');
+  v_meta jsonb := coalesce(p_row -> 'metadata', '{}'::jsonb);
+  v_existing_tenant uuid;
+  v_created boolean := false;
+  v_active boolean := coalesce((p_row ->> 'is_active')::boolean, true);
+  v_standalone boolean := migration._standalone();
+BEGIN
+  IF v_standalone THEN PERFORM migration._assert_fence(p_tenant); PERFORM set_config('migration.writer', 'on', true); END IF;
+  IF p_id IS NULL OR nullif(btrim(coalesce(p_row ->> 'name', '')), '') IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', 'a product needs an id and a name');
+  END IF;
+  v_meta := migration._deep_set(v_meta, ARRAY['catalog', 'kind'], to_jsonb(v_kind));
+  SELECT tenant_id INTO v_existing_tenant FROM public.products WHERE id = p_id;
+  IF v_existing_tenant IS NOT NULL AND v_existing_tenant <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant', 'reason', format('product %s already exists in another tenant', p_id));
+  END IF;
+  IF v_existing_tenant IS NULL THEN
+    INSERT INTO public.products (id, tenant_id, category_id, name, description, sku, price, cost, currency, unit, image_url, status, is_active, metadata)
+    VALUES (p_id, p_tenant, (p_row ->> 'category_id')::uuid, p_row ->> 'name', p_row ->> 'description', p_row ->> 'sku',
+            (p_row ->> 'price')::numeric, (p_row ->> 'cost')::numeric, coalesce(p_row ->> 'currency', 'BRL'), p_row ->> 'unit',
+            p_row ->> 'image_url', CASE WHEN v_active THEN 'active' ELSE 'inactive' END, v_active, v_meta);
+    v_created := true;
+  ELSE
+    UPDATE public.products SET
+      name = p_row ->> 'name',
+      category_id = CASE WHEN p_row ? 'category_id' THEN (p_row ->> 'category_id')::uuid ELSE category_id END,
+      description = CASE WHEN p_row ? 'description' THEN p_row ->> 'description' ELSE description END,
+      sku = CASE WHEN p_row ? 'sku' THEN p_row ->> 'sku' ELSE sku END,
+      price = CASE WHEN p_row ? 'price' THEN (p_row ->> 'price')::numeric ELSE price END,
+      cost = CASE WHEN p_row ? 'cost' THEN (p_row ->> 'cost')::numeric ELSE cost END,
+      unit = CASE WHEN p_row ? 'unit' THEN p_row ->> 'unit' ELSE unit END,
+      image_url = CASE WHEN p_row ? 'image_url' THEN p_row ->> 'image_url' ELSE image_url END,
+      status = CASE WHEN p_row ? 'is_active' THEN (CASE WHEN v_active THEN 'active' ELSE 'inactive' END) ELSE status END,
+      is_active = CASE WHEN p_row ? 'is_active' THEN v_active ELSE is_active END,
+      metadata = migration._merge_meta(metadata, v_meta)
+    WHERE id = p_id;
+  END IF;
+  IF migration._has_column('public.products', 'kind') THEN
+    EXECUTE 'UPDATE public.products SET kind = $1 WHERE id = $2' USING v_kind, p_id;
+  END IF;
+  PERFORM migration._set_unit('public.products', p_id, (p_row ->> 'unit_id')::uuid);
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.products', p_id, jsonb_build_object('reason', CASE WHEN v_created THEN 'created' ELSE 'updated' END)); END IF;
+  RETURN jsonb_build_object('status', 'migrated', 'target_id', p_id, 'reason', CASE WHEN v_created THEN 'created' ELSE 'updated' END);
+END $$;
+
+-- Invoice: guarded on the financial slice's table (#141). Absent ⇒ skipped with a
+-- clear reason; present ⇒ insert-only through the columns that exist (a
+-- financial document is never rewritten by the migration).
+CREATE OR REPLACE FUNCTION migration.upsert_invoice(p_tenant uuid, p_id uuid, p_row jsonb, p_args jsonb DEFAULT '{}'::jsonb)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  v_table text := 'public.plg_financial_invoices';
+  v_candidate jsonb;
+  v_cols text[] := '{}';
+  v_vals text[] := '{}';
+  k text; v jsonb;
+  v_exists boolean;
+  v_standalone boolean := migration._standalone();
+BEGIN
+  IF to_regclass(v_table) IS NULL THEN
+    RETURN jsonb_build_object('status', 'skipped', 'reason', 'destination table absent: ' || v_table);
+  END IF;
+  IF v_standalone THEN PERFORM migration._assert_fence(p_tenant); PERFORM set_config('migration.writer', 'on', true); END IF;
+  EXECUTE format('SELECT EXISTS (SELECT 1 FROM %s WHERE id = $1)', v_table) INTO v_exists USING p_id;
+  IF v_exists THEN
+    RETURN jsonb_build_object('status', 'skipped', 'target_id', p_id, 'reason', 'invoice already exists: financial documents are never rewritten by the migration');
+  END IF;
+  v_candidate := jsonb_build_object(
+    'id', p_id, 'tenant_id', p_tenant,
+    'unit_id', p_row -> 'unit_id', 'order_id', p_row -> 'order_id',
+    'party_id', p_row -> 'party_id', 'counterparty_id', p_row -> 'party_id',
+    'direction', coalesce(p_args ->> 'direction', p_row ->> 'direction', 'receivable'),
+    'kind', coalesce(p_args ->> 'kind', 'receivable'),
+    'total', p_row -> 'total', 'total_amount', p_row -> 'total', 'amount', p_row -> 'total',
+    'status', coalesce(p_row ->> 'status', 'open'),
+    'competence_date', p_row -> 'competence_date', 'due_date', p_row -> 'due_date',
+    'notes', p_row -> 'notes', 'metadata', coalesce(p_row -> 'metadata', '{}'::jsonb));
+  FOR k, v IN SELECT key, value FROM jsonb_each(v_candidate) LOOP
+    IF v IS NULL OR jsonb_typeof(v) = 'null' THEN CONTINUE; END IF;
+    IF migration._has_column(v_table, k) THEN
+      v_cols := v_cols || quote_ident(k);
+      v_vals := v_vals || format('(%L::jsonb #>> ''{}'')::%s', v, (SELECT format_type(a.atttypid, a.atttypmod) FROM pg_attribute a WHERE a.attrelid = to_regclass(v_table) AND a.attname = k));
+    END IF;
+  END LOOP;
+  EXECUTE format('INSERT INTO %s (%s) VALUES (%s)', v_table, array_to_string(v_cols, ', '), array_to_string(v_vals, ', '));
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, v_table, p_id, jsonb_build_object('reason', 'created')); END IF;
+  RETURN jsonb_build_object('status', 'migrated', 'target_id', p_id, 'reason', 'created');
+END $$;
+
+-- Order: a V1 invoice as a Venda (ADR 0004). Financial columns are written once;
+-- upsert_row refuses a later change of them (value quarantine). With
+-- split_invoice the receivable invoice is written too when its table exists — a
+-- second ledger row for the same source row (deterministic id, so a replay
+-- reaches the same invoice).
+CREATE OR REPLACE FUNCTION migration.upsert_order(p_tenant uuid, p_id uuid, p_row jsonb, p_args jsonb DEFAULT '{}'::jsonb)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  v_kind text := coalesce(p_args ->> 'kind', 'sale');
+  v_map jsonb := coalesce(p_args -> 'status_map', '{}'::jsonb);
+  v_src_status text := p_row ->> 'status';
+  v_status text;
+  v_meta jsonb := coalesce(p_row -> 'metadata', '{}'::jsonb);
+  v_existing_tenant uuid;
+  v_created boolean := false;
+  v_invoice jsonb;
+  v_invoice_id uuid;
+  v_extra jsonb := '[]'::jsonb;
+  v_standalone boolean := migration._standalone();
+BEGIN
+  IF v_standalone THEN PERFORM migration._assert_fence(p_tenant); PERFORM set_config('migration.writer', 'on', true); END IF;
+  IF p_id IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', 'an order needs an id');
+  END IF;
+  v_status := coalesce(v_map ->> coalesce(v_src_status, ''), v_map ->> '*', v_src_status, 'completed');
+  v_meta := migration._deep_set(v_meta, ARRAY['migration', 'source_status'], to_jsonb(v_src_status));
+
+  SELECT tenant_id INTO v_existing_tenant FROM public.orders WHERE id = p_id;
+  IF v_existing_tenant IS NOT NULL AND v_existing_tenant <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant', 'reason', format('order %s already exists in another tenant', p_id));
+  END IF;
+  IF v_existing_tenant IS NULL THEN
+    INSERT INTO public.orders (id, tenant_id, kind, reference_number, status, party_id, subtotal, discount, tax, total, currency, completed_at, notes, metadata)
+    VALUES (p_id, p_tenant, v_kind, p_row ->> 'reference_number', v_status, (p_row ->> 'party_id')::uuid,
+            (p_row ->> 'subtotal')::numeric, coalesce((p_row ->> 'discount')::numeric, 0), coalesce((p_row ->> 'tax')::numeric, 0),
+            (p_row ->> 'total')::numeric, coalesce(p_row ->> 'currency', 'BRL'), (p_row ->> 'completed_at')::timestamptz,
+            p_row ->> 'notes', v_meta);
+    v_created := true;
+  ELSE
+    -- financial columns are guarded upstream (upsert_row) and not touched here
+    UPDATE public.orders SET
+      kind = v_kind,
+      reference_number = CASE WHEN p_row ? 'reference_number' THEN p_row ->> 'reference_number' ELSE reference_number END,
+      status = CASE WHEN p_row ? 'status' THEN v_status ELSE status END,
+      party_id = CASE WHEN p_row ? 'party_id' THEN (p_row ->> 'party_id')::uuid ELSE party_id END,
+      completed_at = CASE WHEN p_row ? 'completed_at' THEN (p_row ->> 'completed_at')::timestamptz ELSE completed_at END,
+      notes = CASE WHEN p_row ? 'notes' THEN p_row ->> 'notes' ELSE notes END,
+      metadata = migration._merge_meta(metadata, v_meta)
+    WHERE id = p_id;
+  END IF;
+  PERFORM migration._set_unit('public.orders', p_id, (p_row ->> 'unit_id')::uuid);
+
+  IF coalesce(p_args ->> 'split_invoice', 'false') = 'true' THEN
+    v_invoice_id := md5('migration:invoice:' || p_id::text)::uuid;
+    v_invoice := migration.upsert_invoice(p_tenant, v_invoice_id,
+      jsonb_build_object('order_id', p_id, 'party_id', p_row -> 'party_id', 'unit_id', p_row -> 'unit_id', 'total', p_row -> 'total',
+                         'competence_date', p_row -> 'completed_at', 'status', 'open', 'metadata', v_meta),
+      jsonb_build_object('direction', 'receivable', 'kind', 'receivable'));
+    v_extra := v_extra || jsonb_build_object('target_table', 'public.plg_financial_invoices', 'target_id', v_invoice_id,
+                                             'status', CASE WHEN v_invoice ->> 'status' = 'migrated' THEN 'migrated' ELSE 'skipped' END,
+                                             'reason', v_invoice ->> 'reason',
+                                             'financial', CASE WHEN v_invoice ->> 'status' = 'migrated' THEN jsonb_build_object('total', p_row -> 'total') ELSE NULL END);
+  END IF;
+  IF v_standalone THEN PERFORM migration._audit(p_tenant, 'public.orders', p_id, jsonb_build_object('reason', CASE WHEN v_created THEN 'created' ELSE 'updated' END)); END IF;
+  RETURN jsonb_build_object('status', 'migrated', 'target_id', p_id, 'reason', CASE WHEN v_created THEN 'created' ELSE 'updated' END, 'extra', v_extra);
+END $$;
+
+-- ─────────────────────────────── the entry point ───────────────────────
+CREATE OR REPLACE FUNCTION migration._quarantine(p_ledger_id bigint, p_batch uuid, p_kind text, p_reason text, p_payload jsonb, p_target_table text DEFAULT NULL)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE v_q bigint; v_l migration.ledger%ROWTYPE;
+BEGIN
+  UPDATE migration.quarantine SET resolved_at = now(), resolution = 'superseded by a later offer of the same row'
+   WHERE ledger_id = p_ledger_id AND resolved_at IS NULL;
+  -- a row already at the destination keeps status 'migrated' (the earlier
+  -- version stays); the open quarantine row is what flags it
+  UPDATE migration.ledger SET status = CASE WHEN status = 'migrated' THEN 'migrated' ELSE 'quarantined' END,
+         reason = p_kind || ': ' || p_reason, batch_id = p_batch, target_table = coalesce(target_table, p_target_table)
+   WHERE id = p_ledger_id RETURNING * INTO v_l;
+  INSERT INTO migration.quarantine (ledger_id, tenant_id, batch_id, kind, reason, payload)
+  VALUES (p_ledger_id, v_l.tenant_id, p_batch, p_kind, p_reason, p_payload) RETURNING id INTO v_q;
+  PERFORM migration._count(p_batch, 'quarantined');
+  RETURN jsonb_build_object('status', 'quarantined', 'kind', p_kind, 'reason', p_reason, 'target_table', v_l.target_table,
+                            'target_id', v_l.target_id, 'ledger_id', p_ledger_id, 'quarantine_id', v_q);
+END $$;
+
+CREATE OR REPLACE FUNCTION migration._upsert_row_impl(p_batch uuid, p_source_table text, p_source_numeric_id bigint, p_source_uuid uuid, p_cursor text, p_row jsonb)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  b migration.batches%ROWTYPE;
+  a migration.allowlist%ROWTYPE;
+  l migration.ledger%ROWTYPE;
+  v_checksum text := md5(p_row::text);
+  v_target_table text;
+  v_target_id uuid;
+  v_mapped jsonb; v_row jsonb; v_meta jsonb; v_unres jsonb;
+  v_dest jsonb; v_fin jsonb;
+  v_res jsonb; v_status text; v_col text; v_excl text;
+  v_retry_split boolean := false;
+  x jsonb; v_xid bigint;
+BEGIN
+  SELECT * INTO b FROM migration.batches WHERE id = p_batch;
+  IF NOT FOUND THEN RAISE EXCEPTION 'upsert_row: unknown batch %', p_batch USING ERRCODE = 'P0002'; END IF;
+  IF b.status <> 'running' THEN
+    RAISE EXCEPTION 'upsert_row: batch % is % (only a running batch accepts rows)', p_batch, b.status USING ERRCODE = '55000';
+  END IF;
+  PERFORM migration._assert_fence(b.tenant_id);
+
+  SELECT * INTO a FROM migration.allowlist WHERE source_table = p_source_table;
+  v_target_table := a.target_table;
+
+  SELECT * INTO l FROM migration.ledger
+   WHERE source_project = b.source_project AND source_table = p_source_table
+     AND ((p_source_numeric_id IS NOT NULL AND source_numeric_id = p_source_numeric_id)
+       OR (p_source_numeric_id IS NULL AND source_uuid = p_source_uuid))
+     AND coalesce(target_table, '') = coalesce(v_target_table, '')
+   FOR UPDATE;
+  IF NOT FOUND THEN
+    INSERT INTO migration.ledger (source_project, source_table, source_numeric_id, source_uuid, tenant_id, target_table, checksum, cursor, batch_id, status)
+    VALUES (b.source_project, p_source_table, p_source_numeric_id, p_source_uuid, b.tenant_id, v_target_table, v_checksum, p_cursor, p_batch, 'pending')
+    RETURNING * INTO l;
+  ELSIF l.tenant_id <> b.tenant_id THEN
+    RETURN migration._quarantine(l.id, p_batch, 'tenant',
+      format('source row already belongs to tenant %s; this batch migrates tenant %s', l.tenant_id, b.tenant_id), p_row);
+  END IF;
+
+  -- allowlist
+  IF p_source_table LIKE 'import\_ef\_%' OR EXISTS (SELECT 1 FROM migration.excluded_tables e WHERE e.source_table = p_source_table) THEN
+    SELECT reason INTO v_excl FROM migration.excluded_tables e WHERE e.source_table = CASE WHEN p_source_table LIKE 'import\_ef\_%' THEN 'import_ef_*' ELSE p_source_table END;
+    RETURN migration._quarantine(l.id, p_batch, 'allowlist', 'source table is explicitly excluded: ' || coalesce(v_excl, 'no reason recorded'), p_row);
+  END IF;
+  IF a.source_table IS NULL THEN
+    RETURN migration._quarantine(l.id, p_batch, 'allowlist', format('source table %s is not in the core-A allowlist', p_source_table), p_row);
+  END IF;
+  -- tenant identity of the source row vs the batch
+  IF b.source_tenant_id IS NOT NULL AND (p_row ->> 'tenant_id') ~ '^\d+$' AND (p_row ->> 'tenant_id')::bigint <> b.source_tenant_id THEN
+    RETURN migration._quarantine(l.id, p_batch, 'tenant',
+      format('source row tenant_id %s differs from the batch source_tenant_id %s', p_row ->> 'tenant_id', b.source_tenant_id), p_row);
+  END IF;
+
+  -- idempotency + delta
+  IF EXISTS (SELECT 1 FROM migration.quarantine q WHERE q.ledger_id = l.id AND q.resolved_at IS NULL AND md5(q.payload::text) = v_checksum) THEN
+    PERFORM migration._count(p_batch, 'skipped');
+    RETURN jsonb_build_object('status', 'skipped', 'reason', 'quarantined and unresolved: ' || coalesce(l.reason, ''),
+                              'target_table', l.target_table, 'target_id', l.target_id, 'ledger_id', l.id);
+  END IF;
+  IF l.status = 'migrated' THEN
+    -- a split destination that did not exist on the first offer (invoice) and exists now: run the writer again
+    SELECT EXISTS (SELECT 1 FROM migration.ledger s
+                    WHERE s.source_project = l.source_project AND s.source_table = l.source_table
+                      AND s.source_numeric_id IS NOT DISTINCT FROM l.source_numeric_id AND s.source_uuid IS NOT DISTINCT FROM l.source_uuid
+                      AND s.id <> l.id AND s.status IN ('pending', 'skipped') AND to_regclass(s.target_table) IS NOT NULL) INTO v_retry_split;
+    IF l.checksum = v_checksum AND NOT v_retry_split THEN
+      PERFORM migration._count(p_batch, 'skipped');
+      RETURN jsonb_build_object('status', 'skipped', 'reason', 'unchanged', 'target_table', l.target_table, 'target_id', l.target_id, 'ledger_id', l.id);
+    END IF;
+    IF l.checksum <> v_checksum AND migration.cursor_cmp(p_cursor, l.cursor) < 0 THEN
+      PERFORM migration._count(p_batch, 'skipped');
+      RETURN jsonb_build_object('status', 'skipped', 'reason', format('stale cursor: %s < %s already migrated', p_cursor, l.cursor),
+                                'target_table', l.target_table, 'target_id', l.target_id, 'ledger_id', l.id);
+    END IF;
+  END IF;
+
+  -- no writer yet: recorded, re-offered later
+  IF a.writer IS NULL THEN
+    UPDATE migration.ledger SET status = 'pending', reason = format('no destination writer for %s yet', v_target_table),
+           checksum = v_checksum, cursor = p_cursor, batch_id = p_batch WHERE id = l.id;
+    PERFORM migration._count(p_batch, 'pending');
+    RETURN jsonb_build_object('status', 'pending', 'reason', format('no destination writer for %s yet', v_target_table),
+                              'target_table', v_target_table, 'target_id', l.target_id, 'ledger_id', l.id);
+  END IF;
+
+  -- map + references
+  v_mapped := migration.map_row(b.source_project, p_source_table, p_row);
+  v_row := v_mapped -> 'row'; v_meta := v_mapped -> 'metadata'; v_unres := v_mapped -> 'unresolved';
+  IF jsonb_array_length(v_unres) > 0 THEN
+    RETURN migration._quarantine(l.id, p_batch, 'fk', 'unresolved reference(s): ' || v_unres::text, p_row);
+  END IF;
+
+  -- destination id (ADR 0007): the source uuid, else the id minted on the first offer
+  v_target_id := coalesce(l.target_id, p_source_uuid, gen_random_uuid());
+  v_meta := jsonb_set(v_meta, '{migration}', coalesce(v_meta -> 'migration', '{}'::jsonb) || jsonb_build_object(
+              'source_project', b.source_project, 'source_table', p_source_table, 'source_numeric_id', p_source_numeric_id,
+              'source_uuid', p_source_uuid, 'batch_id', p_batch), true);
+  v_row := v_row || jsonb_build_object('metadata', v_meta);
+  SELECT coalesce(jsonb_object_agg(c, v_row -> c), '{}'::jsonb) INTO v_fin FROM unnest(a.financial_columns) c WHERE v_row ? c;
+
+  -- never overwrite an existing financial value; never re-create a deleted row
+  IF l.status = 'migrated' THEN
+    IF cardinality(a.financial_columns) > 0 THEN
+      v_dest := migration._destination_values(v_target_table, l.target_id, a.financial_columns);
+      IF v_dest IS NULL THEN
+        RETURN migration._quarantine(l.id, p_batch, 'state', 'target row no longer exists in the destination (deleted after migration); not re-created', p_row);
+      END IF;
+      FOREACH v_col IN ARRAY a.financial_columns LOOP
+        IF (v_row ? v_col) AND round(coalesce((v_row ->> v_col)::numeric, 0), 2) IS DISTINCT FROM round(coalesce((v_dest ->> v_col)::numeric, 0), 2) THEN
+          RETURN migration._quarantine(l.id, p_batch, 'value',
+            format('financial column %s: destination %s, incoming %s — an existing financial value is never overwritten', v_col, coalesce(v_dest ->> v_col, 'null'), coalesce(v_row ->> v_col, 'null')), p_row);
+        END IF;
+      END LOOP;
+    ELSIF migration._destination_values(v_target_table, l.target_id, ARRAY['id']) IS NULL THEN
+      RETURN migration._quarantine(l.id, p_batch, 'state', 'target row no longer exists in the destination (deleted after migration); not re-created', p_row);
+    END IF;
+  END IF;
+
+  -- delegate; any error is a state quarantine, never a partial write
+  BEGIN
+    v_res := CASE a.writer
+      WHEN 'person'   THEN migration.upsert_person(b.tenant_id, v_target_id, v_row, a.writer_args)
+      WHEN 'unit'     THEN migration.upsert_unit(b.tenant_id, v_target_id, v_row, a.writer_args)
+      WHEN 'category' THEN migration.upsert_category(b.tenant_id, v_target_id, v_row, a.writer_args)
+      WHEN 'product'  THEN migration.upsert_product(b.tenant_id, v_target_id, v_row, a.writer_args)
+      WHEN 'order'    THEN migration.upsert_order(b.tenant_id, v_target_id, v_row, a.writer_args)
+      WHEN 'invoice'  THEN migration.upsert_invoice(b.tenant_id, v_target_id, v_row, a.writer_args)
+    END;
+  EXCEPTION WHEN OTHERS THEN
+    v_res := jsonb_build_object('status', 'quarantined', 'kind', 'state', 'reason', format('%s: %s', SQLSTATE, SQLERRM));
+  END;
+  v_status := coalesce(v_res ->> 'status', 'quarantined');
+
+  IF v_status = 'quarantined' THEN
+    RETURN migration._quarantine(l.id, p_batch, coalesce(v_res ->> 'kind', 'state'), coalesce(v_res ->> 'reason', 'writer refused'), p_row);
+  END IF;
+  IF v_status = 'skipped' THEN
+    UPDATE migration.ledger SET status = 'skipped', reason = v_res ->> 'reason', checksum = v_checksum, cursor = p_cursor, batch_id = p_batch,
+           target_id = coalesce((v_res ->> 'target_id')::uuid, target_id) WHERE id = l.id;
+    PERFORM migration._count(p_batch, 'skipped');
+    RETURN jsonb_build_object('status', 'skipped', 'reason', v_res ->> 'reason', 'target_table', v_target_table, 'target_id', v_res ->> 'target_id', 'ledger_id', l.id);
+  END IF;
+
+  v_target_id := coalesce((v_res ->> 'target_id')::uuid, v_target_id);
+  UPDATE migration.ledger
+     SET status = 'migrated', target_table = v_target_table, target_id = v_target_id, checksum = v_checksum, cursor = p_cursor,
+         batch_id = p_batch, reason = v_res ->> 'reason', financial = nullif(v_fin, '{}'::jsonb)
+   WHERE id = l.id;
+  UPDATE migration.quarantine SET resolved_at = now(), resolution = 'row migrated on a later offer' WHERE ledger_id = l.id AND resolved_at IS NULL;
+
+  -- split rows (a Venda's invoice): one more ledger row per extra destination
+  FOR x IN SELECT value FROM jsonb_array_elements(coalesce(v_res -> 'extra', '[]'::jsonb)) LOOP
+    SELECT id INTO v_xid FROM migration.ledger
+     WHERE source_project = b.source_project AND source_table = p_source_table
+       AND source_numeric_id IS NOT DISTINCT FROM p_source_numeric_id AND source_uuid IS NOT DISTINCT FROM p_source_uuid
+       AND target_table = x ->> 'target_table';
+    IF v_xid IS NULL THEN
+      INSERT INTO migration.ledger (source_project, source_table, source_numeric_id, source_uuid, tenant_id, target_table, target_id, checksum, cursor, batch_id, status, reason, financial)
+      VALUES (b.source_project, p_source_table, p_source_numeric_id, p_source_uuid, b.tenant_id, x ->> 'target_table', (x ->> 'target_id')::uuid,
+              v_checksum, p_cursor, p_batch, x ->> 'status', x ->> 'reason', nullif(x -> 'financial', 'null'::jsonb));
+    ELSE
+      UPDATE migration.ledger SET target_id = (x ->> 'target_id')::uuid, checksum = v_checksum, cursor = p_cursor, batch_id = p_batch,
+             status = x ->> 'status', reason = x ->> 'reason', financial = coalesce(nullif(x -> 'financial', 'null'::jsonb), financial) WHERE id = v_xid;
+    END IF;
+  END LOOP;
+
+  INSERT INTO public.audit_logs (tenant_id, user_id, action, entity_type, entity_id, metadata)
+  VALUES (b.tenant_id, NULL, 'migration.upsert', v_target_table, v_target_id::text,
+          jsonb_build_object('batch_id', p_batch, 'source_project', b.source_project, 'source_table', p_source_table,
+                             'source_numeric_id', p_source_numeric_id, 'source_uuid', p_source_uuid, 'reason', v_res ->> 'reason'));
+  PERFORM migration._count(p_batch, 'migrated');
+  RETURN jsonb_build_object('status', 'migrated', 'reason', v_res ->> 'reason', 'target_table', v_target_table, 'target_id', v_target_id,
+                            'ledger_id', l.id, 'merged', coalesce((v_res ->> 'merged')::boolean, false), 'extra', coalesce(v_res -> 'extra', '[]'::jsonb));
+END $$;
+
+-- The generic destination write. Marks the transaction as a migration writer
+-- (so the PONR triggers of 093 stay quiet) for the duration of the call only.
+CREATE OR REPLACE FUNCTION migration.upsert_row(p_batch uuid, p_source_table text, p_source_numeric_id bigint, p_source_uuid uuid, p_cursor text, p_row jsonb)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE v jsonb;
+BEGIN
+  IF p_row IS NULL OR jsonb_typeof(p_row) <> 'object' THEN
+    RAISE EXCEPTION 'upsert_row: p_row must be a JSON object (the source row)' USING ERRCODE = '22023';
+  END IF;
+  IF p_source_numeric_id IS NULL AND p_source_uuid IS NULL THEN
+    RAISE EXCEPTION 'upsert_row: a source row needs a numeric id or a uuid' USING ERRCODE = '22023';
+  END IF;
+  IF p_source_table IS NULL OR btrim(p_source_table) = '' THEN
+    RAISE EXCEPTION 'upsert_row: source_table is required' USING ERRCODE = '22023';
+  END IF;
+  PERFORM set_config('migration.writer', 'on', true);
+  PERFORM set_config('migration.batch', p_batch::text, true);
+  BEGIN
+    v := migration._upsert_row_impl(p_batch, p_source_table, p_source_numeric_id, p_source_uuid, p_cursor, p_row);
+  EXCEPTION WHEN OTHERS THEN
+    PERFORM set_config('migration.writer', 'off', true);
+    PERFORM set_config('migration.batch', '', true);
+    RAISE;
+  END;
+  PERFORM set_config('migration.writer', 'off', true);
+  PERFORM set_config('migration.batch', '', true);
+  RETURN v;
+END $$;
+
+-- ─────────────────────────────── grants ────────────────────────────────
+-- Dedup lookups use the people slice's document index (people_tenant_document_uidx,
+-- 071); the earlier private expression index is retired.
+DROP INDEX IF EXISTS public.people_migration_document_idx;
+
+DO $$
+DECLARE r record;
+BEGIN
+  FOR r IN SELECT p.oid::regprocedure AS sig FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace WHERE n.nspname = 'migration' LOOP
+    EXECUTE format('REVOKE ALL ON FUNCTION %s FROM public, anon, authenticated', r.sig);
+  END LOOP;
+END $$;
+GRANT EXECUTE ON FUNCTION migration.cursor_cmp(text, text), migration.fence_set(uuid, text), migration.kill_switch(uuid, boolean),
+  migration.mark_v2_write(uuid), migration.batch_open(uuid, text, text, bigint), migration.batch_pause(uuid), migration.batch_resume(uuid),
+  migration.batch_close(uuid, text), migration.next_cursor(uuid, text), migration.resolve_ref(text, text, text, text),
+  migration.map_row(text, text, jsonb), migration.upsert_person(uuid, uuid, jsonb, jsonb), migration.upsert_unit(uuid, uuid, jsonb, jsonb),
+  migration.upsert_category(uuid, uuid, jsonb, jsonb), migration.upsert_product(uuid, uuid, jsonb, jsonb), migration.upsert_order(uuid, uuid, jsonb, jsonb),
+  migration.upsert_invoice(uuid, uuid, jsonb, jsonb), migration.upsert_row(uuid, text, bigint, uuid, text, jsonb)
+  TO service_role;