@fayz-ai/db 0.17.0 → 0.18.0

package/migrations/120_o_servico_diz_se_ele_se_agenda.sql

@@ -0,0 +1,76 @@
+-- ---------------------------------------------------------------------------
+-- 120_o_servico_diz_se_ele_se_agenda.sql — nem todo serviço se marca na agenda.
+-- ---------------------------------------------------------------------------
+-- O formulário de agendamento do V2 oferece o catálogo inteiro. No BeautySoft
+-- ele oferece TRÊS — Avaliação, Revisão e Compra Antecipada —, e a regra está
+-- escrita na própria tela dele:
+--
+--   "Somente Avaliação, Revisão, Compra Antecipada e serviços com contrato
+--    assinado + avaliação vinculada podem ser agendados."
+--
+-- Não é detalhe de estética. É o desenho do negócio: o tratamento é VENDIDO
+-- (um pacote, um contrato), e o que se marca na agenda é o passo do processo —
+-- a consulta que avalia, o retorno que revisa, a entrega do que foi comprado
+-- antes. Oferecer os 122 no agendamento faz a recepção escolher entre "Ácido
+-- Hialurônico" e "Avaliação" como se fossem a mesma coisa, e marcar o
+-- tratamento em vez do passo é como o histórico do cliente deixa de fechar com
+-- o que ele pagou.
+--
+-- ── A forma no V2 ──────────────────────────────────────────────────────────
+-- Uma coluna, não um enum copiado do V1. `service_kind` de lá tem quatro
+-- valores dos quais três respondem à MESMA pergunta ("isto se marca?"), e o
+-- quarto — o serviço com contrato assinado + avaliação vinculada — depende de
+-- um contrato que o V2 ainda não modela. Um enum importado inteiro carregaria
+-- uma classificação que ninguém aqui sabe ler.
+--
+-- `is_bookable` é a pergunta, e é a MESMA palavra que `people.is_bookable` já
+-- usa para separar quem atende de quem trabalha na casa. Duas tabelas, uma
+-- pergunta, um nome.
+--
+-- ── Nasce TRUE, e isso é deliberado ────────────────────────────────────────
+-- Uma conta que nunca pensou no assunto continua marcando o que sempre marcou.
+-- A regra do ByDesign: pergunta não respondida cai no padrão, não em "não" —
+-- e o contrário esvaziaria o agendamento de toda conta no dia do deploy.
+--
+-- Quem vem do V1 responde na importação (`services.service_kind`) ou na tela
+-- de Serviços, no interruptor "Aparece na agenda".
+--
+-- Idempotente.
+-- ---------------------------------------------------------------------------
+
+-- ── Onde a coluna mora ─────────────────────────────────────────────────────
+-- Em `products`. A 191 aposentou o espelho `public.services` e um serviço
+-- passou a ser produto de `kind='service'` — é de lá que o SDK lê, e medido no
+-- cluster do salão os dois lados batem (122 e 122).
+--
+-- Nos pools que ainda têm a tabela antiga viva, a coluna vai nos DOIS: a tela
+-- de Serviços lê o espelho, e uma coluna que só existe de um lado seria um
+-- interruptor que se desliga e volta sozinho.
+ALTER TABLE public.products
+  ADD COLUMN IF NOT EXISTS is_bookable boolean NOT NULL DEFAULT true;
+
+COMMENT ON COLUMN public.products.is_bookable IS
+  'Este serviço pode ser MARCADO na agenda. Falso = vendido, não agendado (o '
+  'tratamento que se compra em pacote; o que se marca é a avaliação, a revisão '
+  'ou a entrega). Espelha o `service_kind` do V1. Só significa algo para '
+  'kind=service. Padrão true.';
+
+CREATE INDEX IF NOT EXISTS products_bookable_idx
+  ON public.products (tenant_id, is_bookable)
+  WHERE is_bookable;
+
+DO $$
+DECLARE
+  -- O oid guardado, e não `'public.services'::regclass` dentro do IF: o cast
+  -- LANÇA quando a relação não existe, e o `AND` não o protege — o planejador
+  -- avalia a subconsulta antes de decidir. Num banco do zero (sem o espelho
+  -- legado) isto derrubava a migration inteira com "relation does not exist",
+  -- que é exatamente o caso que o guarda existia para cobrir.
+  v_oid oid := to_regclass('public.services');
+BEGIN
+  IF v_oid IS NOT NULL
+     AND (SELECT relkind FROM pg_class WHERE oid = v_oid) = 'r' THEN
+    EXECUTE 'ALTER TABLE public.services ADD COLUMN IF NOT EXISTS is_bookable boolean NOT NULL DEFAULT true';
+    EXECUTE 'CREATE INDEX IF NOT EXISTS services_bookable_idx ON public.services (tenant_id, is_bookable) WHERE is_bookable';
+  END IF;
+END $$;

package/migrations/121_a_liberacao_pergunta_uma_vez_e_nao_cento_e_vinte_mil.sql

@@ -0,0 +1,109 @@
+-- A liberação pergunta uma vez, e não cento e vinte mil.
+--
+-- Qualquer lista de Pessoas do Espaço Facial levava ~6,4 s e às vezes estourava
+-- o `statement_timeout` — a tela voltava vazia, que é como o PostgREST entrega
+-- o 57014. Medido no cluster, como `authenticated`, tenant Espaço Facial:
+--
+--     select count(*) from people where kind='customer'     6.206 ms  331.301 buffers
+--     lista com name ilike '%test%', limit 20               6.459 ms  336.521 buffers
+--
+-- ── Não era a busca ─────────────────────────────────────────────────────────
+--
+-- O primeiro suspeito é o `ilike '%test%'`: curinga à esquerda, e a suspeita é
+-- razoável. Mas o `count(*)` acima não tem busca nenhuma e custa o MESMO. O que
+-- os dois têm em comum é a política.
+--
+-- (Sobre o ILIKE, de passagem, porque ele volta: com RLS ligada ele NUNCA vai
+-- virar condição de índice. `texticlike` não é `leakproof`, e um qual que não é
+-- leakproof não desce abaixo da barreira de segurança — então o índice trigrama
+-- `people_name_trgm_idx`, que sozinho responde em 13 ms, fica de fora por
+-- construção. Isso não é um defeito a corrigir aqui; é o preço da barreira.)
+--
+-- ── Era esta linha ──────────────────────────────────────────────────────────
+--
+-- A política `people_available_in` (migration 087) tem quatro cláusulas em OU, e
+-- a terceira é:
+--
+--     NOT app.has_release_tuple('people.person', id)
+--
+-- `has_release_tuple` é barata: uma função SQL simples, inlinável, que faz um
+-- EXISTS num índice. O 087 a escreveu assim de propósito, porque a versão
+-- anterior era SECURITY DEFINER e o Postgres não inlina essas — cada linha
+-- pagava a montagem de um executor inteiro.
+--
+-- O que o 087 não viu é que barata **vezes cento e vinte mil** não é barata. A
+-- cláusula só é alcançada quando as duas anteriores falham, e no Espaço Facial
+-- elas falham SEMPRE:
+--
+--     pessoas no tenant                     120.808
+--     com unit_id NULL                      120.455   (99,7%)
+--     grants de people.person                 1.446   (grants_exist → verdadeiro)
+--
+-- Cliente de salão não mora numa filial — ela é da rede, e o V1 nem tem coluna
+-- de unidade em `clients`. Então `unit_id IS NOT NULL` é falso, e a sonda ao
+-- índice roda uma vez por linha: 2,8 buffers × 120 mil = os 331.301 do plano.
+--
+-- ── A correção ──────────────────────────────────────────────────────────────
+--
+-- A mesma pergunta, feita UMA vez. `NOT IN` sobre uma subconsulta NÃO
+-- correlacionada é resolvida como *hashed SubPlan*: o Postgres lê as 1.446
+-- linhas de grant, monta uma tabela hash e depois cada pessoa custa uma sondagem
+-- de hash em vez de uma descida de índice.
+--
+-- É o mesmo movimento que o funil do CRM já tinha feito por outro motivo: o que
+-- é correlacionado não desce para dentro da barreira, e o que não é, desce uma
+-- vez só.
+--
+--     select count(*) ...                   6.206 ms → 115 ms   (54×)
+--     lista com ilike, limit 20             6.459 ms → 467 ms   (14×)
+--
+-- O resultado é o MESMO — as duas formas devolvem 119.518 linhas. A quarta
+-- cláusula (`available_in_my_units`) continua depois do NOT IN e é ela que
+-- deixa passar quem tem tupla de liberação para a unidade de quem lê.
+--
+-- `resource_id IS NOT NULL` não é decoração: `NOT IN` com um NULO na lista
+-- devolve NULO para todo mundo, e NULO numa política esconde a linha. Sem essa
+-- cláusula, um grant órfão apagaria a agenda inteira de todo mundo.
+--
+-- ── E o índice da lista ─────────────────────────────────────────────────────
+--
+-- Com a política corrigida, o que sobra é a varredura ordenada por nome, e ela
+-- volta ao heap só para ler `is_active`, `unit_id`, `owner_id` e `id`. Pendurar
+-- essas quatro no índice que já existe transforma o `count` num Index Only Scan
+-- (255 ms → 115 ms). A chave não muda — é o mesmo índice, com carga.
+--
+-- Idempotente.
+
+ALTER POLICY people_available_in ON public.people USING (
+  (NOT (SELECT app.grants_exist('people.person', ARRAY['available_in', 'unavailable_in'])))
+  OR (unit_id IS NOT NULL)
+  -- A pergunta de sempre, resolvida uma vez: "esta pessoa tem tupla de
+  -- liberação?". Não correlacionada de propósito — é isso que a torna um hash.
+  OR (people.id NOT IN (
+        SELECT g.resource_id
+          FROM app.resource_grants g
+         WHERE g.tenant_id = (SELECT app.current_tenant_id())
+           AND g.resource_type = 'people.person'
+           AND g.relation IN ('available_in', 'unavailable_in')
+           AND g.resource_id IS NOT NULL))
+  OR (SELECT app.available_in_my_units('people.person', people.id)));
+
+-- Um índice novo em `resource_grants` foi tentado aqui e NÃO entrou. A ideia era
+-- ler por recurso em vez de por sujeito, porque o plano gasta 921 buffers para
+-- devolver 1.446 linhas. Medido: o planejador continuou escolhendo
+-- `resource_grants_subject_idx` — cuja chave já começa por
+-- (tenant_id, …, relation, resource_type) — e a subconsulta custa 0,95 ms de um
+-- total de 130. Índice que o planejador não escolhe é peso de escrita sem
+-- leitura, e fica registrado aqui em vez de no catálogo.
+
+-- A lista de pessoas: mesma chave do índice que já existia, com as quatro
+-- colunas que a política lê penduradas. O antigo sai depois do novo entrar,
+-- para nenhum plano ficar sem índice no meio.
+CREATE INDEX IF NOT EXISTS people_tenant_kind_name_cover_idx
+  ON public.people USING btree (tenant_id, kind, name)
+  INCLUDE (id, is_active, unit_id, owner_id);
+
+DROP INDEX IF EXISTS public.people_tenant_kind_name_idx;
+
+COMMENT ON INDEX public.people_tenant_kind_name_cover_idx IS
+  'A lista de Pessoas por tipo, em ordem de nome. As colunas penduradas são as que people_available_in e people_authz_select leem — sem elas o count volta ao heap linha a linha (121).';

package/migrations/122_o_email_da_pessoa_e_um_email_nao_uma_lista.sql

@@ -0,0 +1,80 @@
+-- O e-mail da pessoa é um e-mail, não uma lista.
+--
+-- A ficha do profissional mostrava, no campo E-mail:
+--
+--     ["marataizes@espacofacial.com.br"]
+--
+-- e, no Telefone, `[]`. Não é defeito de tela: `people.email` e `people.phone`
+-- são `text`, e o porte do V1 gravou ali o JSON do array que o V1 mantém —
+-- lá uma pessoa pode ter vários e-mails, aqui a coluna guarda um.
+--
+-- Medido em 21/09/2026 (klvfxzreepavcpyjiwla, 123.484 pessoas, 25 contas):
+--
+--     e-mail em forma de array      456   (451 com um valor, 4 vazios, 1 com dois)
+--     telefone em forma de array    277   (233 com um valor, 43 vazios, 1 com dois)
+--
+-- ── Por que reparar o dado e não formatar na tela ──────────────────────────
+--
+-- Um `JSON.parse` na hora de desenhar esconderia o problema nos lugares que
+-- ainda não existem: a busca por e-mail não acha `["x@y"]` procurando `x@y`, o
+-- disparo de mensagem manda para um endereço com colchete, e o `unique` que um
+-- dia entrar nessa coluna vai tratar `x@y` e `["x@y"]` como pessoas diferentes.
+-- Campo estranho na tela é sintoma; a cura é onde o dado foi escrito.
+--
+-- ── O que sobra não se perde ───────────────────────────────────────────────
+--
+-- O primeiro valor sobe para a coluna; os demais descem para
+-- `metadata.contact.extra_emails` / `extra_phones`. São dois registros no
+-- cluster inteiro, mas apagar o segundo e-mail de alguém para deixar a coluna
+-- bonita é o tipo de perda que só aparece quando a pessoa não recebe o aviso.
+--
+-- Array vazio vira NULL: `[]` na tela diz que existe um telefone e não diz
+-- qual; vazio diz a verdade.
+
+DO $$
+DECLARE
+  v_emails integer := 0;
+  v_phones integer := 0;
+BEGIN
+  -- Guarda o que exceder ANTES de sobrescrever a coluna.
+  UPDATE public.people p
+     SET metadata = jsonb_set(
+           coalesce(p.metadata, '{}'::jsonb),
+           '{contact,extra_emails}',
+           (SELECT jsonb_agg(v) FROM jsonb_array_elements(p.email::jsonb) WITH ORDINALITY t(v, i) WHERE i > 1),
+           true)
+   WHERE p.email ~ '^\[.*\]$'
+     AND jsonb_typeof(p.email::jsonb) = 'array'
+     AND jsonb_array_length(p.email::jsonb) > 1;
+
+  UPDATE public.people p
+     SET metadata = jsonb_set(
+           coalesce(p.metadata, '{}'::jsonb),
+           '{contact,extra_phones}',
+           (SELECT jsonb_agg(v) FROM jsonb_array_elements(p.phone::jsonb) WITH ORDINALITY t(v, i) WHERE i > 1),
+           true)
+   WHERE p.phone ~ '^\[.*\]$'
+     AND jsonb_typeof(p.phone::jsonb) = 'array'
+     AND jsonb_array_length(p.phone::jsonb) > 1;
+
+  -- O primeiro valor vira o valor. `#>>'{0}'` devolve NULL no array vazio, que
+  -- é exatamente o que se quer guardar ali.
+  UPDATE public.people p
+     SET email = nullif(btrim(p.email::jsonb #>> '{0}'), '')
+   WHERE p.email ~ '^\[.*\]$'
+     AND jsonb_typeof(p.email::jsonb) = 'array';
+  GET DIAGNOSTICS v_emails = ROW_COUNT;
+
+  UPDATE public.people p
+     SET phone = nullif(btrim(p.phone::jsonb #>> '{0}'), '')
+   WHERE p.phone ~ '^\[.*\]$'
+     AND jsonb_typeof(p.phone::jsonb) = 'array';
+  GET DIAGNOSTICS v_phones = ROW_COUNT;
+
+  RAISE NOTICE 'people: % e-mail(s) e % telefone(s) saíram da forma de lista', v_emails, v_phones;
+END $$;
+
+COMMENT ON COLUMN public.people.email IS
+  'UM e-mail. O V1 guarda lista; o porte tem de escolher o principal e mandar o resto para metadata.contact.extra_emails (ver migration 122).';
+COMMENT ON COLUMN public.people.phone IS
+  'UM telefone. Mesma regra do e-mail — o excedente vai para metadata.contact.extra_phones (ver migration 122).';

package/migrations/123_um_writer_para_a_tabela_que_ja_tem_a_forma_certa.sql

@@ -0,0 +1,197 @@
+-- Um writer para a tabela que já tem a forma certa.
+--
+-- O porte tem 19 tabelas novas para transportar — caixa de entrada de NF-e,
+-- remessa bancária, comissão a pagar, ordem de produção, chamada de garçom — e
+-- todas foram DESENHADAS para este transporte: as colunas do destino têm o nome
+-- que o de-para produz, porque foram escritas olhando a origem.
+--
+-- Escrever dezenove writers de upsert quase idênticos custaria duas mil linhas
+-- e criaria dezenove lugares onde a mesma regra pode divergir. O motor já tem o
+-- precedente do contrário: `upsert_facet` serve dezesseis tabelas de origem com
+-- uma função só, lendo o alvo do `writer_args`.
+--
+-- Este é o mesmo movimento para o caso do upsert inteiro.
+--
+-- ── O que o torna seguro ────────────────────────────────────────────────────
+--
+-- SQL dinâmico a partir de jsonb é superfície de injeção, e a resposta não é
+-- "os dados vêm de lugar confiável" — isso é uma propriedade que se perde numa
+-- refatoração. As travas são estruturais:
+--
+--   1. O alvo tem de existir (`to_regclass`) E ser `target_table` de alguma
+--      linha da `migration.allowlist`. A allowlist é congelada por gatilho e só
+--      muda por arquivo de migration, então o conjunto de tabelas que este
+--      writer alcança é o conjunto que alguém escreveu num arquivo revisado.
+--
+--   2. Toda chave da linha é confrontada com `information_schema.columns` do
+--      alvo. O que casa vira coluna; o que não casa vai para `metadata` — não é
+--      descartado, e não vira identificador.
+--
+--   3. A coerção de tipo é do Postgres, não minha: `jsonb_populate_record`
+--      converte pelo ROWTYPE do destino. Texto que não é data falha ali, com o
+--      nome da coluna, em vez de virar nulo em silêncio.
+--
+--   4. Só as colunas que a linha traz entram no INSERT. As outras recebem o
+--      DEFAULT da tabela — que é o contrário de `jsonb_populate_record` sozinho,
+--      que preencheria tudo com nulo e apagaria os defaults.
+--
+-- ── O que ele NÃO faz ───────────────────────────────────────────────────────
+--
+-- Não traduz vocabulário, não deriva coluna, não recusa por regra de negócio.
+-- Tabela que precisa de qualquer uma dessas três coisas ganha writer próprio —
+-- é o caso de `upsert_appointment` (mapa de status), `upsert_clinical_session`
+-- (sete palavras fechadas) e `upsert_agenda_schedule` (dia inteiro vira faixa).
+-- Este writer é para a tabela que só precisa atravessar.
+--
+-- Idempotente.
+
+DO $$
+DECLARE v_def text;
+BEGIN
+  SELECT pg_get_constraintdef(oid) INTO v_def
+    FROM pg_constraint WHERE conname = 'allowlist_writer_check';
+  IF v_def IS NULL OR strpos(v_def, 'by_shape') > 0 THEN RETURN; END IF;
+  ALTER TABLE migration.allowlist DROP CONSTRAINT allowlist_writer_check;
+  EXECUTE replace(
+    'ALTER TABLE migration.allowlist ADD CONSTRAINT allowlist_writer_check ' || v_def,
+    '''person''::text', '''person''::text, ''by_shape''::text');
+END $$;
+
+CREATE OR REPLACE FUNCTION migration.upsert_by_shape(
+  p_tenant uuid, p_id uuid, p_row jsonb, p_args jsonb DEFAULT '{}'::jsonb
+) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path TO ''
+AS $function$
+DECLARE
+  v_target   text := p_args ->> 'target';
+  v_reg      regclass;
+  v_meta     jsonb := coalesce(p_row -> 'metadata', '{}'::jsonb);
+  v_cols     text[];
+  v_usadas   text[] := ARRAY[]::text[];
+  v_extra    jsonb := '{}'::jsonb;
+  v_payload  jsonb := '{}'::jsonb;
+  v_tem_meta boolean;
+  v_tem_unit boolean;
+  v_tem_upd  boolean;
+  v_unit     uuid;
+  v_lista    text;
+  v_select   text;
+  v_set      text;
+  v_existing uuid;
+  v_created  boolean := false;
+  v_falta    text;
+  k          text;
+  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', 'a row needs an id');
+  END IF;
+
+  -- Trava 1: o alvo existe e está declarado na allowlist.
+  v_reg := to_regclass(v_target);
+  IF v_reg IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state',
+      'reason', format('the by_shape writer needs a target that exists; got %L', coalesce(v_target, '<null>')));
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM migration.allowlist a WHERE a.target_table = v_target) THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state',
+      'reason', format('%s is not a target_table of any allowlist row — this writer only reaches what the de-para declares', v_target));
+  END IF;
+
+  -- Trava 2: as colunas reais do destino.
+  SELECT array_agg(a.attname ORDER BY a.attnum) INTO v_cols
+    FROM pg_attribute a
+   WHERE a.attrelid = v_reg AND a.attnum > 0 AND NOT a.attisdropped;
+
+  v_tem_meta := 'metadata'   = ANY (v_cols);
+  v_tem_unit := 'unit_id'    = ANY (v_cols);
+  v_tem_upd  := 'updated_at' = ANY (v_cols);
+
+  FOR k IN SELECT jsonb_object_keys(p_row) LOOP
+    IF k IN ('id', 'tenant_id', 'metadata') THEN CONTINUE; END IF;
+    IF k = ANY (v_cols) THEN
+      v_usadas := v_usadas || k;
+      v_payload := v_payload || jsonb_build_object(k, p_row -> k);
+    ELSE
+      -- Nem coluna nem descarte: o que não casa vira metadata, e continua
+      -- legível para quem for conferir o porte depois.
+      v_extra := v_extra || jsonb_build_object(k, p_row -> k);
+    END IF;
+  END LOOP;
+
+  IF v_tem_meta THEN
+    v_meta := v_meta || CASE WHEN v_extra = '{}'::jsonb THEN '{}'::jsonb
+                             ELSE jsonb_build_object('migration', jsonb_build_object('unmapped', v_extra)) END;
+  END IF;
+
+  -- Coluna obrigatória sem valor e sem default é recusa de VALOR, com o nome
+  -- dela — e não um erro de constraint no meio do lote.
+  SELECT string_agg(a.attname, ', ') INTO v_falta
+    FROM pg_attribute a
+   WHERE a.attrelid = v_reg AND a.attnum > 0 AND NOT a.attisdropped
+     AND a.attnotnull
+     AND NOT EXISTS (SELECT 1 FROM pg_attrdef d WHERE d.adrelid = a.attrelid AND d.adnum = a.attnum)
+     AND a.attname <> ALL (v_usadas)
+     AND a.attname NOT IN ('id', 'tenant_id');
+  IF v_falta IS NOT NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'value',
+      'reason', format('%s requires %s, and the de-para did not map it', v_target, v_falta));
+  END IF;
+
+  EXECUTE format('SELECT tenant_id FROM %s WHERE id = $1', v_reg) INTO v_existing USING p_id;
+  IF v_existing IS NOT NULL AND v_existing <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant',
+      'reason', format('%s %s already exists in another tenant', v_target, p_id));
+  END IF;
+
+  v_payload := v_payload || jsonb_build_object('id', p_id, 'tenant_id', p_tenant);
+  IF v_tem_meta THEN v_payload := v_payload || jsonb_build_object('metadata', v_meta); END IF;
+
+  v_lista  := (SELECT string_agg(quote_ident(x), ', ') FROM unnest(
+                 v_usadas || ARRAY['id', 'tenant_id'] ||
+                 CASE WHEN v_tem_meta THEN ARRAY['metadata'] ELSE ARRAY[]::text[] END) x);
+  v_select := (SELECT string_agg('r.' || quote_ident(x), ', ') FROM unnest(
+                 v_usadas || ARRAY['id', 'tenant_id'] ||
+                 CASE WHEN v_tem_meta THEN ARRAY['metadata'] ELSE ARRAY[]::text[] END) x);
+  v_set    := (SELECT string_agg(format('%I = EXCLUDED.%I', x, x), ', ')
+                 FROM unnest(v_usadas) x WHERE x <> 'created_at');
+  IF v_tem_meta THEN
+    v_set := coalesce(v_set || ', ', '') ||
+             format('metadata = migration._merge_meta(%s.metadata, EXCLUDED.metadata)', v_reg::text);
+  END IF;
+  IF v_tem_upd THEN
+    v_set := coalesce(v_set || ', ', '') || 'updated_at = now()';
+  END IF;
+
+  -- `jsonb_populate_record` contra o ROWTYPE do destino: a coerção é do
+  -- Postgres. Só as colunas que a linha trouxe entram, para as outras ficarem
+  -- com o DEFAULT da tabela.
+  IF v_set IS NULL OR v_set = '' THEN
+    EXECUTE format('INSERT INTO %s (%s) SELECT %s FROM jsonb_populate_record(null::%s, $1) r ON CONFLICT (id) DO NOTHING',
+                   v_reg, v_lista, v_select, v_reg) USING v_payload;
+  ELSE
+    EXECUTE format('INSERT INTO %s (%s) SELECT %s FROM jsonb_populate_record(null::%s, $1) r ON CONFLICT (id) DO UPDATE SET %s',
+                   v_reg, v_lista, v_select, v_reg, v_set) USING v_payload;
+  END IF;
+  v_created := v_existing IS NULL;
+
+  IF v_tem_unit THEN
+    BEGIN v_unit := (p_row ->> 'unit_id')::uuid; EXCEPTION WHEN OTHERS THEN v_unit := NULL; END;
+    PERFORM migration._set_unit(v_target, p_id, v_unit);
+  END IF;
+
+  IF v_standalone THEN
+    PERFORM migration._audit(p_tenant, v_target, 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 $function$;
+
+COMMENT ON FUNCTION migration.upsert_by_shape(uuid, uuid, jsonb, jsonb) IS
+  'Upsert genérico para a tabela de destino cujas colunas já têm o nome que o de-para produz. O alvo vem de writer_args.target e tem de ser target_table de alguma linha da allowlist.';
+
+REVOKE ALL ON FUNCTION migration.upsert_by_shape(uuid, uuid, jsonb, jsonb) FROM PUBLIC, anon, authenticated;
+GRANT EXECUTE ON FUNCTION migration.upsert_by_shape(uuid, uuid, jsonb, jsonb) TO service_role;

package/migrations/124_o_updated_at_so_pode_ser_atribuido_uma_vez.sql

@@ -0,0 +1,155 @@
+-- O `updated_at` só pode ser atribuído uma vez.
+--
+-- `upsert_by_shape` (123) montava o SET do ON CONFLICT com duas atribuições da
+-- mesma coluna quando a linha de origem trazia `updated_at`:
+--
+--     updated_at = EXCLUDED.updated_at   (porque a coluna veio mapeada)
+--     updated_at = now()                 (porque a tabela tem a coluna)
+--
+-- O Postgres recusa: `42601: multiple assignments to same column "updated_at"`.
+-- A primeira onda com o writer genérico devolveu 170 notas fiscais em
+-- quarentena por isso — e, em cascata, os 915 itens, pagamentos e duplicatas
+-- que dependiam delas.
+--
+-- ── E a correção não é escolher `now()` ─────────────────────────────────────
+--
+-- Quando a origem TRAZ `updated_at`, é ele que vale: o porte está copiando uma
+-- linha que mudou lá em 2025, e carimbar `now()` faria toda a história chegar
+-- com a data da migração. O espelho D-1 depende disso — é por `updated_at` que
+-- o cursor decide o que releu.
+--
+-- `now()` fica para quando a origem não diz: aí a única verdade disponível é
+-- "chegou agora".
+--
+-- Idempotente.
+
+CREATE OR REPLACE FUNCTION migration.upsert_by_shape(
+  p_tenant uuid, p_id uuid, p_row jsonb, p_args jsonb DEFAULT '{}'::jsonb
+) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path TO ''
+AS $function$
+DECLARE
+  v_target   text := p_args ->> 'target';
+  v_reg      regclass;
+  v_meta     jsonb := coalesce(p_row -> 'metadata', '{}'::jsonb);
+  v_cols     text[];
+  v_usadas   text[] := ARRAY[]::text[];
+  v_extra    jsonb := '{}'::jsonb;
+  v_payload  jsonb := '{}'::jsonb;
+  v_tem_meta boolean;
+  v_tem_unit boolean;
+  v_tem_upd  boolean;
+  v_unit     uuid;
+  v_lista    text;
+  v_select   text;
+  v_set      text;
+  v_existing uuid;
+  v_created  boolean := false;
+  v_falta    text;
+  k          text;
+  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', 'a row needs an id');
+  END IF;
+
+  v_reg := to_regclass(v_target);
+  IF v_reg IS NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state',
+      'reason', format('the by_shape writer needs a target that exists; got %L', coalesce(v_target, '<null>')));
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM migration.allowlist a WHERE a.target_table = v_target) THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'state',
+      'reason', format('%s is not a target_table of any allowlist row — this writer only reaches what the de-para declares', v_target));
+  END IF;
+
+  SELECT array_agg(a.attname ORDER BY a.attnum) INTO v_cols
+    FROM pg_attribute a
+   WHERE a.attrelid = v_reg AND a.attnum > 0 AND NOT a.attisdropped;
+
+  v_tem_meta := 'metadata'   = ANY (v_cols);
+  v_tem_unit := 'unit_id'    = ANY (v_cols);
+  v_tem_upd  := 'updated_at' = ANY (v_cols);
+
+  FOR k IN SELECT jsonb_object_keys(p_row) LOOP
+    IF k IN ('id', 'tenant_id', 'metadata') THEN CONTINUE; END IF;
+    IF k = ANY (v_cols) THEN
+      v_usadas := v_usadas || k;
+      v_payload := v_payload || jsonb_build_object(k, p_row -> k);
+    ELSE
+      v_extra := v_extra || jsonb_build_object(k, p_row -> k);
+    END IF;
+  END LOOP;
+
+  IF v_tem_meta THEN
+    v_meta := v_meta || CASE WHEN v_extra = '{}'::jsonb THEN '{}'::jsonb
+                             ELSE jsonb_build_object('migration', jsonb_build_object('unmapped', v_extra)) END;
+  END IF;
+
+  SELECT string_agg(a.attname, ', ') INTO v_falta
+    FROM pg_attribute a
+   WHERE a.attrelid = v_reg AND a.attnum > 0 AND NOT a.attisdropped
+     AND a.attnotnull
+     AND NOT EXISTS (SELECT 1 FROM pg_attrdef d WHERE d.adrelid = a.attrelid AND d.adnum = a.attnum)
+     AND a.attname <> ALL (v_usadas)
+     AND a.attname NOT IN ('id', 'tenant_id');
+  IF v_falta IS NOT NULL THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'value',
+      'reason', format('%s requires %s, and the de-para did not map it', v_target, v_falta));
+  END IF;
+
+  EXECUTE format('SELECT tenant_id FROM %s WHERE id = $1', v_reg) INTO v_existing USING p_id;
+  IF v_existing IS NOT NULL AND v_existing <> p_tenant THEN
+    RETURN jsonb_build_object('status', 'quarantined', 'kind', 'tenant',
+      'reason', format('%s %s already exists in another tenant', v_target, p_id));
+  END IF;
+
+  v_payload := v_payload || jsonb_build_object('id', p_id, 'tenant_id', p_tenant);
+  IF v_tem_meta THEN v_payload := v_payload || jsonb_build_object('metadata', v_meta); END IF;
+
+  v_lista  := (SELECT string_agg(quote_ident(x), ', ') FROM unnest(
+                 v_usadas || ARRAY['id', 'tenant_id'] ||
+                 CASE WHEN v_tem_meta THEN ARRAY['metadata'] ELSE ARRAY[]::text[] END) x);
+  v_select := (SELECT string_agg('r.' || quote_ident(x), ', ') FROM unnest(
+                 v_usadas || ARRAY['id', 'tenant_id'] ||
+                 CASE WHEN v_tem_meta THEN ARRAY['metadata'] ELSE ARRAY[]::text[] END) x);
+  -- `created_at` fica de fora porque criação não se reescreve. `updated_at` sai
+  -- daqui e volta logo abaixo — ou com o valor da ORIGEM, ou com `now()` quando
+  -- a origem não diz. Atribuir as duas coisas é o erro 42601 que esta migration
+  -- existe para corrigir.
+  v_set := (SELECT string_agg(format('%I = EXCLUDED.%I', x, x), ', ')
+              FROM unnest(v_usadas) x WHERE x NOT IN ('created_at', 'updated_at'));
+  IF v_tem_meta THEN
+    v_set := coalesce(v_set || ', ', '') ||
+             format('metadata = migration._merge_meta(%s.metadata, EXCLUDED.metadata)', v_reg::text);
+  END IF;
+  IF v_tem_upd THEN
+    v_set := coalesce(v_set || ', ', '') ||
+             CASE WHEN 'updated_at' = ANY (v_usadas)
+                  THEN 'updated_at = EXCLUDED.updated_at'
+                  ELSE 'updated_at = now()' END;
+  END IF;
+
+  IF v_set IS NULL OR v_set = '' THEN
+    EXECUTE format('INSERT INTO %s (%s) SELECT %s FROM jsonb_populate_record(null::%s, $1) r ON CONFLICT (id) DO NOTHING',
+                   v_reg, v_lista, v_select, v_reg) USING v_payload;
+  ELSE
+    EXECUTE format('INSERT INTO %s (%s) SELECT %s FROM jsonb_populate_record(null::%s, $1) r ON CONFLICT (id) DO UPDATE SET %s',
+                   v_reg, v_lista, v_select, v_reg, v_set) USING v_payload;
+  END IF;
+  v_created := v_existing IS NULL;
+
+  IF v_tem_unit THEN
+    BEGIN v_unit := (p_row ->> 'unit_id')::uuid; EXCEPTION WHEN OTHERS THEN v_unit := NULL; END;
+    PERFORM migration._set_unit(v_target, p_id, v_unit);
+  END IF;
+
+  IF v_standalone THEN
+    PERFORM migration._audit(p_tenant, v_target, 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 $function$;