@fayz-ai/db 0.14.0 → 0.16.0

package/migrations/073_a_exclusao_e_contrato_do_cliente_nao_do_cluster.sql

@@ -0,0 +1,300 @@
+-- A exclusão é contrato do CLIENTE, não do cluster.
+--
+-- `migration.excluded_tables` tinha chave `(source_table)` e nada mais. Uma
+-- decisão registrada ali valia para todos os tenants do cluster — e decisões
+-- de porte não são assim.
+--
+-- O caso que revelou: o caixa. No Pertinho do Céu a decisão foi não trazer
+-- (`cash_register_sessions` não era operação real ali). O Espaço Facial abre
+-- caixa todo dia em quatro unidades, e queria o histórico — mas a linha global
+-- o calava, e a tela `#/financial/cash/registers` abria vazia sem que nada no
+-- relatório dissesse por quê. A decisão de um cliente estava governando outro.
+--
+-- ── O modelo ────────────────────────────────────────────────────────────────
+--
+--   tenant_id NULL       vale para todo tenant  (as 44 linhas de hoje)
+--   tenant_id = X        vale só para X
+--   excluded = false     o tenant ENTRA, mesmo havendo linha global
+--
+-- A resolução é do mais específico para o mais geral: `ORDER BY tenant_id
+-- NULLS LAST` faz a linha do tenant vir antes da global, e o `LIMIT 1` escolhe
+-- ela. Sem isso não haveria como um cliente readmitir o que outro excluiu — só
+-- apagando a linha global, que apagaria a decisão junto.
+--
+-- `excluded` existe para que a readmissão seja uma LINHA, com motivo e data, e
+-- não a ausência de uma. O porquê de trazer vale tanto quanto o porquê de não
+-- trazer, e os dois ficam no mesmo lugar.
+--
+-- Nada muda para quem já estava: as 44 linhas nascem com `tenant_id = NULL` e
+-- `excluded = true`, que é exatamente o que elas significavam.
+--
+-- Idempotente.
+
+ALTER TABLE migration.excluded_tables
+  ADD COLUMN IF NOT EXISTS tenant_id uuid REFERENCES public.tenants(id) ON DELETE CASCADE,
+  ADD COLUMN IF NOT EXISTS excluded  boolean NOT NULL DEFAULT true,
+  ADD COLUMN IF NOT EXISTS decided_at timestamptz NOT NULL DEFAULT now();
+
+-- A PK antiga impedia a segunda linha da mesma tabela. Os dois índices abaixo
+-- dizem a mesma coisa com a granularidade certa: uma linha global por tabela,
+-- e uma linha por tabela POR tenant.
+ALTER TABLE migration.excluded_tables DROP CONSTRAINT IF EXISTS excluded_tables_pkey;
+
+CREATE UNIQUE INDEX IF NOT EXISTS excluded_tables_global_uq
+  ON migration.excluded_tables (source_table) WHERE tenant_id IS NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS excluded_tables_tenant_uq
+  ON migration.excluded_tables (source_table, tenant_id) WHERE tenant_id IS NOT NULL;
+
+COMMENT ON COLUMN migration.excluded_tables.tenant_id IS
+  'NULL = a decisão vale para todo tenant do cluster. Preenchido = vale só '
+  'para aquele cliente, e VENCE a linha global.';
+COMMENT ON COLUMN migration.excluded_tables.excluded IS
+  'false readmite a tabela para este tenant apesar da exclusão global. A '
+  'readmissão é uma linha com motivo, não a ausência de uma.';
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- E o motor resolve a exclusão pelo tenant do lote
+-- ─────────────────────────────────────────────────────────────────────────────
+
+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 TO ''
+AS $function$
+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_excluded boolean;
+  v_retry_split boolean := false;
+  -- O V1 manda: ver migration.is_mirroring() e o cabeçalho deste arquivo.
+  v_mirror 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);
+
+  v_mirror := coalesce(migration.is_mirroring(b.tenant_id), false);
+
+  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
+  --
+  -- A exclusão é resolvida do MAIS ESPECÍFICO para o mais geral: a linha do
+  -- tenant vence a linha global. "Não trazer caixa" foi uma decisão do
+  -- Pertinho do Céu, e não tinha por que calar o Espaço Facial — o contrato é
+  -- de cliente, não de cluster. `ORDER BY tenant_id NULLS LAST` é o que
+  -- implementa essa precedência: a linha com tenant vem antes da sem.
+  SELECT e.excluded, e.reason INTO v_excluded, 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
+     AND (e.tenant_id IS NULL OR e.tenant_id = b.tenant_id)
+   ORDER BY e.tenant_id NULLS LAST
+   LIMIT 1;
+  IF coalesce(v_excluded, false) THEN
+    RETURN migration._quarantine(l.id, p_batch, 'allowlist', 'source table is explicitly excluded: ' || coalesce(v_excl, 'no reason recorded'), p_row,
+      NULL, 'recorded decision: the table is in migration.excluded_tables');
+  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
+    -- Duas formas da MESMA pergunta, e não uma com IS NOT DISTINCT FROM: esse
+    -- operador não vira condição de índice, então a sondagem virava varredura
+    -- da ledger inteira daquela tabela — 83 ms e 66 MB POR LINHA oferecida,
+    -- medido com 123.535 linhas de `clients`. Aqui cada ramo é um qual simples
+    -- sobre a chave que existe, e os dois têm índice:
+    --   numérica → ledger_source_numeric_key (source_project, source_table, source_numeric_id, …)
+    --   uuid     → ledger_source_uuid_idx    (source_project, source_table, source_uuid)
+    -- O ramo numérico não repete o casamento de uuid porque não precisa: dentro
+    -- de (projeto, tabela) o id numérico JÁ identifica a linha da origem, e as
+    -- irmãs no ledger são a mesma linha com outro destino.
+    IF l.source_numeric_id IS NOT NULL THEN
+      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 = l.source_numeric_id
+                        AND s.id <> l.id AND s.status IN ('pending', 'skipped') AND to_regclass(s.target_table) IS NOT NULL) INTO v_retry_split;
+    ELSE
+      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_uuid = 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;
+    END IF;
+    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;
+
+  -- As duas travas do corte. Em regime de espelho elas ficam de fora, e é a única
+  -- diferença de comportamento deste arquivo:
+  --
+  --   valor financeiro   o V1 é a fonte da verdade enquanto o V2 não escreveu;
+  --                      recusar a atualização deixaria o V2 com o preço velho de
+  --                      uma venda que foi corrigida ontem, em silêncio.
+  --   linha apagada      quem apaga no V2 durante o espelho é o retire_row, e ele
+  --                      marca o ledger como `retired`. Uma linha ainda
+  --                      `migrated` cujo destino sumiu foi apagada por fora — e
+  --                      recriá-la é justamente refletir o V1, que ainda a tem.
+  IF l.status = 'migrated' AND NOT v_mirror 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
+    -- Dispatch by name rather than by a CASE arm per writer. The CASE meant every
+    -- new destination writer had to re-emit this whole function, and a row naming
+    -- a writer the CASE did not list fell through to NULL — silently, which is
+    -- the failure mode this schema exists to prevent. The allowlist's CHECK is
+    -- the vocabulary, `migration` is definer-only, and the name is verified to
+    -- exist before it is called, so an allowlist row naming a writer nobody built
+    -- quarantines with that sentence instead of vanishing.
+    IF to_regprocedure(format('migration.upsert_%s(uuid,uuid,jsonb,jsonb)', a.writer)) IS NULL THEN
+      RETURN migration._quarantine(l.id, p_batch, 'state',
+        format('the allowlist names writer %L for %s, and migration.upsert_%s does not exist', a.writer, p_source_table, a.writer),
+        p_row, v_target_table);
+    END IF;
+    -- %I on the whole identifier, not on the suffix: format('upsert_%I', 'order')
+    -- yields upsert_"order", which is not the function's name.
+    EXECUTE format('SELECT migration.%I($1, $2, $3, $4)', 'upsert_' || a.writer)
+      INTO v_res USING b.tenant_id, v_target_id, v_row, a.writer_args;
+  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
+    -- Mesma correção da sondagem de irmã, pelo mesmo motivo: com
+    -- IS NOT DISTINCT FROM nenhum dos dois índices da ledger é usado, e esta
+    -- busca acontece uma vez por destino extra de cada Venda.
+    IF p_source_numeric_id IS NOT NULL THEN
+      SELECT id INTO v_xid FROM migration.ledger
+       WHERE source_project = b.source_project AND source_table = p_source_table
+         AND source_numeric_id = p_source_numeric_id
+         AND target_table = x ->> 'target_table';
+    ELSE
+      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 NULL AND source_uuid = p_source_uuid
+         AND target_table = x ->> 'target_table';
+    END IF;
+    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 $function$
+
+;

package/migrations/074_a_classificacao_quebrada_nao_leva_o_dinheiro_junto.sql

@@ -0,0 +1,332 @@
+-- A classificação quebrada não leva o dinheiro junto.
+--
+-- `migration._upsert_row_impl` recusa a linha inteira quando QUALQUER
+-- referência não resolve:
+--
+--     IF jsonb_array_length(v_unres) > 0 THEN
+--       RETURN migration._quarantine(… 'fk', 'unresolved reference(s): ' …);
+--
+-- A regra é boa como padrão: um pedido sem cliente, um item sem pedido, uma
+-- parcela sem título — todos são linhas sem sentido, e deixá-las entrar seria
+-- pior que recusá-las.
+--
+-- Mas ela trata como iguais duas coisas que não são. Há referência que é
+-- IDENTIDADE (sem ela a linha não existe) e há referência que é
+-- CLASSIFICAÇÃO (sem ela a linha existe, só não está catalogada).
+--
+-- ── O caso que revelou ──────────────────────────────────────────────────────
+--
+-- A perna contábil de um movimento financeiro é classificação. Sem ela o
+-- dinheiro continua tendo valor, vencimento, unidade e contraparte — tudo o
+-- que a tela de Contas a Receber mostra, e tudo o que o extrato soma.
+--
+-- Medido em 20/09/2026, tenant Espaço Facial: dos 84 ids de `account_central`
+-- citados pelos movimentos recusados, **81 não existem no V1**. A referência
+-- já estava quebrada na ORIGEM — o V1 apagou a conta e deixou o ponteiro. O
+-- porte então recusava o movimento por um defeito que não era dele.
+--
+-- O preço, na tela:
+--
+--     Millenium  · contas a receber 2026   V1 1.829   V2 1.721   −R$ 138.027
+--
+-- Cento e três linhas de dinheiro real fora da tela por causa de um rótulo
+-- que o próprio V1 havia perdido.
+--
+-- ── A regra nova, e por que ela é declarada ────────────────────────────────
+--
+-- `migration.allowlist.optional_refs` nomeia, POR TABELA, as colunas cuja
+-- referência pode faltar sem que a linha perca o sentido. Não é heurística e
+-- não é geral: é uma decisão por tabela, escrita, como tudo neste motor.
+--
+-- O que não resolveu não some: vai para `metadata.migration.unresolved`, com
+-- a coluna e o id da origem. Sai da tela, fica no registro — a diferença
+-- entre tratar um defeito e escondê-lo.
+--
+-- O padrão continua o de antes: `optional_refs` nulo, e a linha é recusada
+-- como sempre foi.
+--
+-- Idempotente.
+
+ALTER TABLE migration.allowlist
+  ADD COLUMN IF NOT EXISTS optional_refs text[];
+
+COMMENT ON COLUMN migration.allowlist.optional_refs IS
+  'Colunas cuja referência pode não resolver sem que a linha seja recusada — '
+  'classificação, não identidade. O que não resolve vai para '
+  'metadata.migration.unresolved. Nulo = comportamento padrão, tudo obrigatório.';
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- O motor separa identidade de classificação
+-- ─────────────────────────────────────────────────────────────────────────────
+
+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 TO ''
+AS $function$
+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;
+  -- O V1 manda: ver migration.is_mirroring() e o cabeçalho deste arquivo.
+  v_mirror 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);
+
+  v_mirror := coalesce(migration.is_mirroring(b.tenant_id), false);
+
+  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,
+      NULL, 'recorded decision: the table is in migration.excluded_tables');
+  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
+    -- Duas formas da MESMA pergunta, e não uma com IS NOT DISTINCT FROM: esse
+    -- operador não vira condição de índice, então a sondagem virava varredura
+    -- da ledger inteira daquela tabela — 83 ms e 66 MB POR LINHA oferecida,
+    -- medido com 123.535 linhas de `clients`. Aqui cada ramo é um qual simples
+    -- sobre a chave que existe, e os dois têm índice:
+    --   numérica → ledger_source_numeric_key (source_project, source_table, source_numeric_id, …)
+    --   uuid     → ledger_source_uuid_idx    (source_project, source_table, source_uuid)
+    -- O ramo numérico não repete o casamento de uuid porque não precisa: dentro
+    -- de (projeto, tabela) o id numérico JÁ identifica a linha da origem, e as
+    -- irmãs no ledger são a mesma linha com outro destino.
+    IF l.source_numeric_id IS NOT NULL THEN
+      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 = l.source_numeric_id
+                        AND s.id <> l.id AND s.status IN ('pending', 'skipped') AND to_regclass(s.target_table) IS NOT NULL) INTO v_retry_split;
+    ELSE
+      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_uuid = 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;
+    END IF;
+    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';
+
+  -- Referência OPCIONAL: a que pode faltar sem que a linha perca o sentido.
+  --
+  -- Nem toda referência é identidade. A perna contábil de um movimento é
+  -- CLASSIFICAÇÃO: sem ela o dinheiro continua tendo valor, vencimento,
+  -- unidade e contraparte — tudo o que a tela de Contas a Receber mostra.
+  -- Recusar o movimento inteiro porque a classificação dele aponta para uma
+  -- conta que o próprio V1 apagou é perder o fato para preservar o rótulo.
+  --
+  -- Medido em 20/09/2026 no Espaço Facial: 81 das 84 contas do razão citadas
+  -- pelos movimentos recusados NÃO EXISTEM no V1. A referência já estava
+  -- quebrada na origem. Custo na tela: R$ 138.027 só no Millenium.
+  --
+  -- Quais colunas podem faltar é DECLARADO por tabela, em
+  -- `migration.allowlist.optional_refs` — nunca adivinhado. O que ficou sem
+  -- resolver vai para `metadata.migration.unresolved`: some da tela, não do
+  -- registro.
+  IF jsonb_array_length(v_unres) > 0 AND a.optional_refs IS NOT NULL THEN
+    v_meta := migration._deep_set(v_meta, ARRAY['migration', 'unresolved'],
+      coalesce((SELECT jsonb_agg(x) FROM jsonb_array_elements(v_unres) x
+                 WHERE x ->> 'column' = ANY (a.optional_refs)), '[]'::jsonb));
+    v_unres := coalesce((SELECT jsonb_agg(x) FROM jsonb_array_elements(v_unres) x
+                          WHERE NOT (x ->> 'column' = ANY (a.optional_refs))), '[]'::jsonb);
+  END IF;
+
+  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;
+
+  -- As duas travas do corte. Em regime de espelho elas ficam de fora, e é a única
+  -- diferença de comportamento deste arquivo:
+  --
+  --   valor financeiro   o V1 é a fonte da verdade enquanto o V2 não escreveu;
+  --                      recusar a atualização deixaria o V2 com o preço velho de
+  --                      uma venda que foi corrigida ontem, em silêncio.
+  --   linha apagada      quem apaga no V2 durante o espelho é o retire_row, e ele
+  --                      marca o ledger como `retired`. Uma linha ainda
+  --                      `migrated` cujo destino sumiu foi apagada por fora — e
+  --                      recriá-la é justamente refletir o V1, que ainda a tem.
+  IF l.status = 'migrated' AND NOT v_mirror 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
+    -- Dispatch by name rather than by a CASE arm per writer. The CASE meant every
+    -- new destination writer had to re-emit this whole function, and a row naming
+    -- a writer the CASE did not list fell through to NULL — silently, which is
+    -- the failure mode this schema exists to prevent. The allowlist's CHECK is
+    -- the vocabulary, `migration` is definer-only, and the name is verified to
+    -- exist before it is called, so an allowlist row naming a writer nobody built
+    -- quarantines with that sentence instead of vanishing.
+    IF to_regprocedure(format('migration.upsert_%s(uuid,uuid,jsonb,jsonb)', a.writer)) IS NULL THEN
+      RETURN migration._quarantine(l.id, p_batch, 'state',
+        format('the allowlist names writer %L for %s, and migration.upsert_%s does not exist', a.writer, p_source_table, a.writer),
+        p_row, v_target_table);
+    END IF;
+    -- %I on the whole identifier, not on the suffix: format('upsert_%I', 'order')
+    -- yields upsert_"order", which is not the function's name.
+    EXECUTE format('SELECT migration.%I($1, $2, $3, $4)', 'upsert_' || a.writer)
+      INTO v_res USING b.tenant_id, v_target_id, v_row, a.writer_args;
+  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
+    -- Mesma correção da sondagem de irmã, pelo mesmo motivo: com
+    -- IS NOT DISTINCT FROM nenhum dos dois índices da ledger é usado, e esta
+    -- busca acontece uma vez por destino extra de cada Venda.
+    IF p_source_numeric_id IS NOT NULL THEN
+      SELECT id INTO v_xid FROM migration.ledger
+       WHERE source_project = b.source_project AND source_table = p_source_table
+         AND source_numeric_id = p_source_numeric_id
+         AND target_table = x ->> 'target_table';
+    ELSE
+      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 NULL AND source_uuid = p_source_uuid
+         AND target_table = x ->> 'target_table';
+    END IF;
+    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 $function$
+
+;
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- E a declaração: as pernas contábeis do movimento são classificação
+-- ─────────────────────────────────────────────────────────────────────────────
+--
+-- Só estas duas, e só nesta tabela. `financial_invoice_id`, `unit_id` e a
+-- contraparte continuam obrigatórios: sem eles o movimento não sabe de quem é
+-- nem de onde veio, e aí ele é mesmo uma linha sem sentido.
+
+SET LOCAL migration.allowlist_unlock = 'on';
+
+UPDATE migration.allowlist
+   SET optional_refs = ARRAY['debit_account_id', 'credit_account_id']
+ WHERE source_table = 'financial_movements';
+
+RESET migration.allowlist_unlock;