@fayz-ai/db 0.14.0 → 0.16.0

package/migrations/043_fiscalcontrol_joins_the_family.sql

@@ -0,0 +1,75 @@
+-- ---------------------------------------------------------------------------
+-- 043_fiscalcontrol_joins_the_family.sql — a contabilidade ganha uma linha.
+--
+-- O oitavo produto do registro, e o segundo que é FUNÇÃO e não trade (como o
+-- LeadControl, 011): FiscalControl é o escritório de contabilidade da família.
+-- Todo tenant que opera um Control já produz o material contábil sem saber —
+-- partida dobrada em plg_financial_movements, balancete em
+-- v_financial_trial_balance, imposto por linha em plg_financial_invoice_item_taxes.
+-- O que falta é o app que olha esse material como um contador olha: plano de
+-- contas, lançamento, DRE, apuração. Com a reforma tributária tornando o
+-- destaque de IBS/CBS obrigatório em agosto/2026, esse olhar deixa de ser
+-- opcional para qualquer tenant fora do Simples.
+--
+-- ── `serves_verticals` fica VAZIO, de propósito ────────────────────────────
+-- Contabilidade não é um ramo, é uma função que atravessa todos. Semear por
+-- vertical (010) daria um app de contador para todo restaurante novo — uma tela
+-- de balancete que ninguém pediu. Este é opt-in: quem liga é `tenant_app_set`
+-- ou a mão da casa.
+--
+-- ── `requires` nomeia um plugin só ─────────────────────────────────────────
+-- `financial` é o razão inteiro: invoices, movimentos, plano de contas, caixa.
+-- Sem ele o rail é Painel e placeholders. `reports` e `fiscal-br` entram como
+-- opt-in quando os marcos M3/M4 fecharem — a migration que criar as telas é a
+-- que atualiza este array (mesma regra da 031).
+-- ---------------------------------------------------------------------------
+
+-- ── §1  a linha do registro ────────────────────────────────────────────────
+--
+-- #334155 (slate): o único setor sóbrio ainda livre na roda — os oito vizinhos
+-- já tomaram vermelho, ouro, verde, dois roxos, azul e teal. Combina com o que
+-- o app é: o produto sério da família. Branco sobre ele dá 9,6:1.
+--
+-- `url` é a origem de dev enquanto o app não é publicado; a coluna é a
+-- allow-list do handoff, e o coalesce impede que uma reaplicação devolva uma
+-- frota publicada para localhost (regra da 028/031).
+INSERT INTO app.apps (id, name, icon, accent_color, url, requires, serves_verticals, active) VALUES
+  ('fiscal', 'FiscalControl', 'Calculator', '#334155', 'http://localhost:5313',
+   ARRAY['financial'],
+   ARRAY[]::text[], true)
+ON CONFLICT (id) DO UPDATE
+  SET name = EXCLUDED.name, icon = EXCLUDED.icon, accent_color = EXCLUDED.accent_color,
+      requires = EXCLUDED.requires, active = true,
+      url = coalesce(app.apps.url, EXCLUDED.url);
+
+-- ── §2  quem recebe agora ──────────────────────────────────────────────────
+--
+-- Só as contas do dogfood que JÁ têm o financeiro ativo — a evidência honesta
+-- de que existe um razão para o contador ler. O app está em M0; distribuir para
+-- o cluster inteiro seria entregar um produto pela metade (regra da 031). O
+-- tenant ControlGroup, criado fora desta migration por platform_tenant_create,
+-- entra pelo p_apps da própria chamada.
+INSERT INTO app.tenant_apps (tenant_id, app_id, status, source)
+SELECT DISTINCT m.tenant_id, 'fiscal', 'active', 'manual'
+  FROM app.memberships m
+  JOIN auth.users u ON u.id = m.user_id
+ WHERE u.email = 'creators@fayalabs.com'
+   AND m.active
+   AND EXISTS (
+     SELECT 1 FROM app.tenant_plugins tp
+      WHERE tp.tenant_id = m.tenant_id AND tp.plugin_id = 'financial'
+        AND tp.facet = '' AND tp.status = 'active'
+   )
+ON CONFLICT (tenant_id, app_id) DO NOTHING;
+
+-- E o plugin que ele precisa, para exatamente essas contas. O teto do plano
+-- ganha do padrão, sempre.
+INSERT INTO app.tenant_plugins (tenant_id, plugin_id, facet, status, source)
+SELECT DISTINCT ta.tenant_id, r.plugin_id, '', 'active', 'default'
+  FROM app.tenant_apps ta
+  JOIN app.apps a ON a.id = ta.app_id
+  CROSS JOIN LATERAL unnest(a.requires) AS r(plugin_id)
+ WHERE ta.app_id = 'fiscal'
+   AND ta.status = 'active'
+   AND public.plan_permits(r.plugin_id, '', ta.tenant_id)
+ON CONFLICT (tenant_id, plugin_id, facet) DO NOTHING;

package/migrations/044_o_teste_gratis_dura_trinta_dias.sql

@@ -0,0 +1,15 @@
+-- ---------------------------------------------------------------------------
+-- 044_o_teste_gratis_dura_trinta_dias.sql
+--
+-- A família Control abre para signup público e a promessa comercial passa a
+-- ser "30 dias grátis" — 7 dias não dão para um restaurante montar cardápio,
+-- treinar a equipe e rodar um mês de pedidos.
+--
+-- O prazo vive num único lugar: o DEFAULT da coluna. Só tenants NOVOS são
+-- afetados; quem já tem data estampada mantém a sua, e quem nasceu antes do
+-- trial (NULL) continua sem trial — nunca "expirado". O trigger
+-- tenants_trial_is_readonly segue impedindo escrita client-side na data.
+-- ---------------------------------------------------------------------------
+
+ALTER TABLE public.tenants
+  ALTER COLUMN trial_ends_at SET DEFAULT (now() + interval '30 days');

package/migrations/045_o_espelho_manda_enquanto_o_v2_nao_escreveu.sql

@@ -0,0 +1,519 @@
+-- O espelho manda enquanto o V2 não escreveu.
+--
+-- O schema `migration` foi desenhado para uma migração de CORTE: lê o V1 uma vez,
+-- escreve no V2, e a partir daí o V2 é o dono. Duas travas vêm dessa premissa e
+-- estão certas dentro dela:
+--
+--   1. valor financeiro existente NUNCA é sobrescrito  → quarentena `value`
+--   2. linha de destino apagada NUNCA é recriada       → quarentena `state`
+--
+-- Só que o corte não é o que está acontecendo. O V1 continua sendo o sistema que
+-- as pessoas usam enquanto o V2 é reescrito, e os dois precisam rodar em paralelo
+-- até a troca de rota. Nesse regime o V2 é um ESPELHO: se a venda mudou de valor
+-- no V1, ela tem que mudar no V2; se a linha foi apagada no V1, ela tem que sumir
+-- do V2. As duas travas acima invertem o sinal — protegem do V1 um dado que só o
+-- V1 conhece.
+--
+-- A saída NÃO é um flag que alguém liga e esquece de desligar. É uma pergunta que
+-- o banco já sabe responder: alguém escreveu pelo V2 DEPOIS que este tenant foi
+-- declarado espelho? Enquanto não, não há o que proteger, e o V1 manda. No
+-- instante em que o `trg_ponr_stamp` carimbar uma escrita do V2, as duas travas
+-- voltam sozinhas, sem ninguém lembrar de nada.
+--
+--     mirror_mode E nenhuma escrita do V2 desde mirror_since  →  o V1 sobrescreve
+--     qualquer outra coisa                                    →  as travas de sempre
+--
+-- **Por que `mirror_since` e não só `first_v2_write_at IS NULL`.** A versão
+-- ingênua dessa regra não funcionaria em nenhum dos tenants que existem hoje:
+-- `first_v2_write_at` do Espaço Facial está carimbado em 05/09 19:10 e o do
+-- Artorius em 08/09 21:06 — ANTES da primeira onda de cada um, em ambos os casos
+-- porque o provisionamento do dono criou uma `public.people` fora do writer de
+-- migração. É o caso que o `access.py` do fayz-etl avisa. Um carimbo desses é uma
+-- escrita administrativa, não o V2 assumindo o tenant, e ler os dois como a mesma
+-- coisa desligaria o espelho justamente onde ele foi pedido.
+--
+-- `mirror_since` é a declaração: "a partir de agora este tenant é espelho". O
+-- carimbo anterior fica na tabela, como histórico, e para de valer. E o
+-- `trg_ponr_stamp` passa a RE-CARIMBAR quando a escrita do V2 é posterior à
+-- declaração — sem isso, o carimbo velho bloquearia para sempre a detecção da
+-- escrita nova, e o espelho nunca perceberia que o V2 assumiu.
+--
+-- Uma honestidade: o gatilho de PONR só existe em `public.orders` e
+-- `public.people`. "O V2 escreveu" significa, hoje, "o V2 criou uma venda ou uma
+-- pessoa" — que são os dois eventos que importam, e não é o universo inteiro.
+--
+-- E, para o que sumiu: `migration.retire_row`. O V1 apaga de verdade — de 406
+-- tabelas, uma só tem `deleted_at` —, então uma leitura incremental nunca vê a
+-- linha que não está mais lá. Sem baixa o V2 acumula fantasma: venda cancelada
+-- que continua no faturamento, cliente removido que continua na lista.
+--
+-- Idempotente.
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- 1. A cerca ganha o regime
+-- ─────────────────────────────────────────────────────────────────────────────
+
+ALTER TABLE migration.tenant_fence
+  ADD COLUMN IF NOT EXISTS mirror_mode boolean NOT NULL DEFAULT false;
+
+ALTER TABLE migration.tenant_fence
+  ADD COLUMN IF NOT EXISTS mirror_since timestamptz;
+
+COMMENT ON COLUMN migration.tenant_fence.mirror_mode IS
+  'Tenant em regime de espelho: o V1 continua sendo o sistema vivo e o V2 reflete. '
+  'Sozinho não autoriza nada — quem decide é migration.is_mirroring().';
+COMMENT ON COLUMN migration.tenant_fence.mirror_since IS
+  'Quando este tenant foi declarado espelho. Escrita do V2 ANTERIOR a isto é '
+  'histórico (tipicamente o provisionamento do dono); posterior encerra o regime.';
+
+-- A pergunta, num lugar só: os dois chamadores (o despachante e a baixa) precisam
+-- da MESMA resposta, e duplicar o predicado é como as duas metades passam a
+-- divergir no terceiro mês.
+CREATE OR REPLACE FUNCTION migration.is_mirroring(p_tenant uuid)
+RETURNS boolean
+LANGUAGE sql
+STABLE SECURITY DEFINER
+SET search_path TO ''
+AS $function$
+  SELECT coalesce(f.mirror_mode, false)
+         AND f.mirror_since IS NOT NULL
+         AND (f.first_v2_write_at IS NULL OR f.first_v2_write_at <= f.mirror_since)
+    FROM migration.tenant_fence f
+   WHERE f.tenant_id = p_tenant
+$function$;
+
+COMMENT ON FUNCTION migration.is_mirroring(uuid) IS
+  'O V1 manda neste tenant? Verdadeiro enquanto o tenant está declarado espelho e '
+  'nenhuma escrita do V2 aconteceu depois da declaração.';
+
+-- O gatilho de PONR precisa saber RE-carimbar. Na versão anterior ele só escrevia
+-- quando `first_v2_write_at` era nulo — o que, num tenant que já tem carimbo
+-- antigo, faria a escrita nova do V2 passar despercebida e o espelho continuar
+-- sobrescrevendo o que o V2 acabou de gravar.
+CREATE OR REPLACE FUNCTION migration.trg_ponr_stamp()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path TO ''
+AS $function$
+DECLARE v_tenant uuid;
+BEGIN
+  IF coalesce(current_setting('migration.writer', true), '') = 'on' THEN RETURN NULL; END IF;
+  v_tenant := CASE WHEN TG_OP = 'DELETE' THEN OLD.tenant_id ELSE NEW.tenant_id END;
+  IF v_tenant IS NOT NULL THEN
+    -- Uma escrita por re-arme, e nenhuma depois: assim que o carimbo passa a ser
+    -- posterior a `mirror_since`, o predicado para de casar. Sem essa condição a
+    -- linha da cerca viraria ponto quente de contenção num restaurante que grava
+    -- comanda o dia inteiro.
+    UPDATE migration.tenant_fence SET first_v2_write_at = now()
+     WHERE tenant_id = v_tenant AND state IN ('fenced', 'v2_writer')
+       AND (first_v2_write_at IS NULL
+            OR (mirror_since IS NOT NULL AND first_v2_write_at < mirror_since));
+  END IF;
+  RETURN NULL;
+END $function$;
+
+-- O ledger ganha o estado de quem foi baixado. Não é `quarantined` (não houve
+-- recusa) e não é `skipped` (a linha existia e deixou de existir): sem estado
+-- próprio, uma baixa ficaria indistinguível de uma linha que nunca chegou, e a
+-- conferência passaria a acusar falta onde houve exclusão legítima.
+DO $$
+BEGIN
+  ALTER TABLE migration.ledger DROP CONSTRAINT IF EXISTS ledger_status_check;
+  ALTER TABLE migration.ledger ADD CONSTRAINT ledger_status_check
+    CHECK (status = ANY (ARRAY['pending', 'migrated', 'quarantined', 'skipped', 'retired']));
+END $$;
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- 2. Como cada destino dá baixa
+-- ─────────────────────────────────────────────────────────────────────────────
+
+-- NASCE VAZIA DE PROPÓSITO.
+--
+-- `retire_row` tem uma escada genérica (deleted_at → cancelled_at → is_active →
+-- DELETE) que cobre a maioria das tabelas sem ninguém decidir nada. O que ela NÃO
+-- faz é adivinhar vocabulário: `public.orders.status` não tem CHECK declarando os
+-- valores possíveis, então escrever 'cancelled' ali seria este arquivo inventando
+-- a semântica de cancelamento de uma venda — exatamente o tipo de default
+-- silencioso que o resto deste schema existe para impedir.
+--
+-- Enquanto ninguém decide, uma venda apagada no V1 cai em quarentena `state` com
+-- o motivo escrito (há movimento financeiro apontando para ela, e o FK é NO
+-- ACTION), e o operador vê o número. Quando alguém DECIDIR o que é uma venda
+-- baixada no V2, a decisão entra aqui em uma linha, versionada.
+CREATE TABLE IF NOT EXISTS migration.retire_policy (
+  target_table text PRIMARY KEY,
+  -- 'soft'   grava `column` = `value` (ou now() quando value é nulo e a coluna é tempo)
+  -- 'delete' apaga a linha
+  -- 'keep'   não baixa: a linha do V2 permanece, e o ledger registra a decisão
+  mode         text NOT NULL CHECK (mode = ANY (ARRAY['soft', 'delete', 'keep'])),
+  column_name  text,
+  value        text,
+  reason       text NOT NULL,
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  CHECK (mode <> 'soft' OR column_name IS NOT NULL)
+);
+
+COMMENT ON TABLE migration.retire_policy IS
+  'O que "apagado na origem" significa em cada tabela de destino. Vazia = escada '
+  'genérica do retire_row. Uma linha aqui é uma decisão de produto, tomada uma vez '
+  'e versionada — não um default que o motor escolheu sozinho.';
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- 3. A baixa
+-- ─────────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION migration.retire_row(
+  p_batch uuid,
+  p_source_table text,
+  p_source_numeric_id bigint,
+  p_source_uuid uuid,
+  p_reason text DEFAULT 'apagada na origem'
+) RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path TO ''
+AS $function$
+DECLARE
+  b migration.batches%ROWTYPE;
+  l migration.ledger%ROWTYPE;
+  pol migration.retire_policy%ROWTYPE;
+  v_mirror boolean;
+  v_col text; v_val text; v_type text;
+  v_n integer := 0;
+  v_done integer := 0;
+  v_first jsonb;
+BEGIN
+  SELECT * INTO b FROM migration.batches WHERE id = p_batch;
+  IF NOT FOUND THEN RAISE EXCEPTION 'retire_row: unknown batch %', p_batch USING ERRCODE = 'P0002'; END IF;
+  IF b.status <> 'running' THEN
+    RAISE EXCEPTION 'retire_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);
+  IF NOT v_mirror THEN
+    -- Baixar fora do regime de espelho seria apagar do V2 um dado que o V2 pode
+    -- já ter adotado como seu. A recusa é a trava, não um detalhe de permissão.
+    RETURN jsonb_build_object('status', 'refused', 'reason',
+      'tenant is not in mirror mode; a retirement outside the mirror regime would '
+      'delete data the V2 may already own');
+  END IF;
+
+  -- Uma linha da origem pode ter mais de um destino (a Venda e o seu título).
+  -- Baixar um e deixar o outro deixaria o financeiro apontando para nada.
+  FOR l IN
+    SELECT * FROM migration.ledger
+     WHERE source_project = b.source_project
+       AND source_table = p_source_table
+       AND tenant_id = b.tenant_id
+       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 status = 'migrated'
+       AND target_table IS NOT NULL
+       AND target_id IS NOT NULL
+     FOR UPDATE
+  LOOP
+    v_n := v_n + 1;
+    SELECT * INTO pol FROM migration.retire_policy WHERE target_table = l.target_table;
+
+    IF pol.mode = 'keep' THEN
+      UPDATE migration.ledger
+         SET status = 'retired', reason = 'retire_policy=keep: ' || pol.reason,
+             batch_id = p_batch, updated_at = now()
+       WHERE id = l.id;
+      v_done := v_done + 1;
+      CONTINUE;
+    END IF;
+
+    -- A escada. `deleted_at` e `cancelled_at` primeiro porque preservam a linha
+    -- e a história; `is_active` depois; o DELETE só quando não há nada que
+    -- signifique "não vale mais" naquela tabela.
+    v_col := NULL;
+    IF pol.mode = 'soft' THEN
+      v_col := pol.column_name; v_val := pol.value;
+    ELSIF pol.mode IS NULL THEN
+      IF    migration._has_column(l.target_table, 'deleted_at')   THEN v_col := 'deleted_at';   v_val := NULL;
+      ELSIF migration._has_column(l.target_table, 'cancelled_at') THEN v_col := 'cancelled_at'; v_val := NULL;
+      ELSIF migration._has_column(l.target_table, 'is_active')    THEN v_col := 'is_active';    v_val := 'false';
+      ELSIF migration._has_column(l.target_table, 'active')       THEN v_col := 'active';       v_val := 'false';
+      END IF;
+    END IF;
+
+    BEGIN
+      IF v_col IS NOT NULL THEN
+        IF v_val IS NULL THEN
+          EXECUTE format('UPDATE %s SET %I = now() WHERE id = $1', l.target_table, v_col)
+            USING l.target_id;
+        ELSE
+          SELECT a.atttypid::regtype::text INTO v_type
+            FROM pg_attribute a
+           WHERE a.attrelid = to_regclass(l.target_table) AND a.attname = v_col;
+          EXECUTE format('UPDATE %s SET %I = $1::%s WHERE id = $2', l.target_table, v_col, v_type)
+            USING v_val, l.target_id;
+        END IF;
+      ELSE
+        EXECUTE format('DELETE FROM %s WHERE id = $1', l.target_table) USING l.target_id;
+      END IF;
+
+      -- O carimbo é o que faz a baixa auditável depois que o ledger for lido por
+      -- outra pessoa: sem ele, uma linha desativada é indistinguível de uma que o
+      -- usuário desativou à mão.
+      IF v_col IS NOT NULL AND migration._has_column(l.target_table, 'metadata') THEN
+        EXECUTE format(
+          'UPDATE %s SET metadata = coalesce(metadata, ''{}''::jsonb) || $1 WHERE id = $2',
+          l.target_table)
+          USING jsonb_build_object('migration', jsonb_build_object(
+                  'retired_at', now(), 'reason', p_reason, 'batch_id', p_batch)),
+                l.target_id;
+      END IF;
+
+      UPDATE migration.ledger
+         SET status = 'retired',
+             reason = p_reason || coalesce(' (' || v_col || ')', ' (delete)'),
+             batch_id = p_batch, updated_at = now()
+       WHERE id = l.id;
+      PERFORM migration._audit(b.tenant_id, l.target_table, l.target_id,
+        jsonb_build_object('action', 'migration.retire', 'reason', p_reason,
+                           'source_table', p_source_table, 'batch_id', p_batch));
+      v_done := v_done + 1;
+    EXCEPTION WHEN OTHERS THEN
+      -- O caso concreto: uma venda apagada no V1 cujo movimento financeiro no V2
+      -- aponta para ela com FK NO ACTION. Cascatear seria apagar o razão junto
+      -- por causa de uma exclusão na origem — o motor recusa e escreve o porquê.
+      v_first := coalesce(v_first, migration._quarantine(l.id, p_batch, 'state',
+        format('não foi possível dar baixa em %s: %s: %s', l.target_table, SQLSTATE, SQLERRM),
+        jsonb_build_object('source_table', p_source_table,
+                           'source_numeric_id', p_source_numeric_id,
+                           'source_uuid', p_source_uuid, 'reason', p_reason),
+        l.target_table));
+    END;
+  END LOOP;
+
+  IF v_n = 0 THEN
+    -- Exclusão de linha que nunca foi migrada. É o caso NORMAL — tudo que foi
+    -- criado e apagado entre duas rodadas, e toda tabela cujo domínio o V2 ainda
+    -- não tem. Silencioso de propósito: contá-lo como erro afogaria o relatório.
+    RETURN jsonb_build_object('status', 'absent', 'source_table', p_source_table);
+  END IF;
+  IF v_done = 0 AND v_first IS NOT NULL THEN
+    RETURN v_first;
+  END IF;
+  PERFORM migration._count(p_batch, 'retired');
+  RETURN jsonb_build_object('status', 'retired', 'source_table', p_source_table,
+                            'rows', v_done, 'refused', v_n - v_done);
+END $function$;
+
+COMMENT ON FUNCTION migration.retire_row(uuid, text, bigint, uuid, text) IS
+  'Dá baixa no V2 na linha que foi APAGADA na origem. Só roda com a cerca em '
+  'modo espelho. Nunca cascateia: o que não puder ser baixado vira quarentena '
+  '`state` com o SQLSTATE escrito.';
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- 4. O despachante aprende o regime
+-- ─────────────────────────────────────────────────────────────────────────────
+
+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
+    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;
+
+  -- 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
+    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 $function$;