@baruk/core 0.4.2 → 0.5.0

package/src/db/migrations/0058_fiscal_operational_engine.sql

@@ -0,0 +1,516 @@
+-- 0058 — o motor operacional: quem pode rodar, quando, sozinho, e o que falta.
+--
+-- ═══ O que a Fase 1 provou, e o que ela deliberadamente não respondeu ══════
+--
+-- A 0056/0057 provaram que sabemos INGERIR: documento canônico, evento fora de
+-- ordem preservado, cursor que não avança sobre dado perdido. Tudo isso é
+-- exercido por uma chamada de função, com um ator humano ou um seed atrás.
+--
+-- Esta migration cria o que falta para a mesma ingestão rodar SOZINHA, todos os
+-- dias, sem que ninguém aperte nada — e, sobretudo, para que ela NÃO rode quando
+-- não deve. Cinco perguntas que a Fase 1 não tinha onde responder:
+--
+--   1. Duas execuções simultâneas sobre o mesmo cliente: o que impede?
+--   2. O worker morreu segurando a vez: quem devolve?
+--   3. O provedor caiu para TODOS os clientes: como não martelamos 200 vezes?
+--   4. Falta certificado: quem é avisado, e uma vez ou a cada tentativa?
+--   5. Este município tem coleta automática? — e a resposta honesta na maioria
+--      dos casos é "não sabemos", que precisa ser dizível.
+--
+-- ═══ Nenhuma destas tabelas habilita nada ══════════════════════════════════
+--
+-- A elegibilidade default-deny da 0055 continua sendo o portão. O que nasce aqui
+-- é a MECÂNICA de operar quem já passou por ele. Tabela vazia, como na 0055,
+-- já é a barreira: sem política, a frequência é `disabled`; sem lease, ninguém
+-- roda; sem linha de cobertura, a resposta é `UNKNOWN`, nunca "coberto".
+
+-- ── 1 · A vez de rodar ─────────────────────────────────────────────────────
+--
+-- ═══ Por que uma linha, e não um advisory lock ═════════════════════════════
+--
+-- `pg_advisory_lock` morreria com a conexão — o que resolve o item 2 de graça, e
+-- é tentador. Mas ele é INVISÍVEL: ninguém consulta "quem está segurando o
+-- cliente X?" numa tela, e um worker travado apareceria como um cliente que
+-- simplesmente não sincroniza, sem nenhum lugar onde olhar. Uma linha com
+-- `holder`, `heartbeat_at` e `expires_at` responde à mesma pergunta e ainda
+-- deixa rastro de quantas vezes a vez precisou ser tomada de volta.
+--
+-- ═══ A exclusão mútua é do ÍNDICE, não do TypeScript ═══════════════════════
+--
+-- A tomada é um `INSERT ... ON CONFLICT DO UPDATE ... WHERE expirou`. O
+-- PostgreSQL trava a linha conflitante: a segunda transação ESPERA a primeira
+-- confirmar e então reavalia o `WHERE`, que já será falso. Não existe janela
+-- entre "verifiquei que está livre" e "tomei" porque não existem dois momentos.
+-- Um `SELECT ... IF livre THEN UPDATE` teria essa janela, e ela é exatamente a
+-- corrida que deixa dois workers consultando o mesmo CNPJ contra a Receita.
+--
+-- ═══ Por que o fluxo entra na chave ════════════════════════════════════════
+--
+-- A vez é por (escritório, cliente, fonte, ambiente, tipo de documento) porque o
+-- cursor da 0056 tem essa mesma granularidade. Travar por cliente inteiro
+-- impediria a NFS-e de andar enquanto a NF-e roda, sem nenhum ganho: são cursores
+-- diferentes contra provedores diferentes.
+CREATE TABLE IF NOT EXISTS fiscal_sync_lease (
+  id               uuid PRIMARY KEY,
+  tenant_id        uuid NOT NULL REFERENCES tenant(id),
+  client_id        uuid NOT NULL,
+  source           text NOT NULL,
+  environment      text NOT NULL
+                     CHECK (environment IN ('synthetic', 'homologation', 'production')),
+  document_type    text NOT NULL CHECK (document_type IN ('nfse', 'nfe', 'cte', 'nfce')),
+
+  -- Quem está com a vez. Identidade do PROCESSO — nome do worker mais um
+  -- sufixo aleatório da instância. Nunca hostname de produção, nunca segredo:
+  -- esta coluna aparece em tela e em trilha.
+  holder           text NOT NULL CHECK (holder <> '' AND length(holder) <= 120),
+  -- O run que está segurando, quando já existe. Sem FK: o run é gravado no fim
+  -- e a vez é tomada no começo — exigir a linha aqui inverteria a ordem.
+  run_id           uuid,
+
+  acquired_at      timestamptz NOT NULL DEFAULT now(),
+  -- Sinal de vida. Um lote longo o renova; um processo morto para de renovar, e
+  -- é a distância entre este instante e agora que autoriza a retomada.
+  heartbeat_at     timestamptz NOT NULL DEFAULT now(),
+  -- Prazo. Passado ele, qualquer worker pode tomar a vez — e é ISTO que impede
+  -- o bloqueio eterno do item 2. Não existe lease sem prazo neste schema.
+  expires_at       timestamptz NOT NULL,
+  released_at      timestamptz,
+  -- Quantas vezes esta vez foi tomada de um titular que ainda não a devolvera.
+  -- Zero é o normal; um número que cresce é um worker que morre no meio, e essa
+  -- é uma pergunta operacional que nenhum log agregado responde.
+  recovered_count  int NOT NULL DEFAULT 0 CHECK (recovered_count >= 0),
+
+  created_at       timestamptz NOT NULL DEFAULT now(),
+  updated_at       timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT fiscal_sync_lease_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  -- Prazo anterior à tomada seria um lease nascido morto: livre para qualquer um
+  -- no instante seguinte, o que anula a exclusão em vez de expressá-la.
+  CONSTRAINT fiscal_sync_lease_expiry_after_acquire CHECK (expires_at > acquired_at)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS fiscal_sync_lease_stream_uq
+  ON fiscal_sync_lease (tenant_id, client_id, source, environment, document_type);
+CREATE INDEX IF NOT EXISTS fiscal_sync_lease_live_idx
+  ON fiscal_sync_lease (tenant_id, expires_at) WHERE released_at IS NULL;
+
+ALTER TABLE fiscal_sync_lease ENABLE ROW LEVEL SECURITY;
+ALTER TABLE fiscal_sync_lease FORCE ROW LEVEL SECURITY;
+CREATE POLICY fiscal_sync_lease_tenant_isolation ON fiscal_sync_lease
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+COMMENT ON COLUMN fiscal_sync_lease.expires_at IS
+  'Prazo da vez. Sem ele, um worker morto bloquearia o cliente para sempre — o modo de falha que este schema recusa a expressar (a coluna é NOT NULL).';
+
+-- ── 2 · Com que frequência, e a resposta padrão é "nenhuma" ────────────────
+--
+-- Elegibilidade responde QUEM pode. Esta tabela responde QUANDO — e são
+-- perguntas independentes: um cliente elegível com política ausente não roda,
+-- e ligar a política de um cliente inelegível não o faz rodar.
+--
+-- Duas rédeas para o mesmo portão seriam um defeito; duas rédeas para portões
+-- diferentes são o desenho. A prova é o caso que importa: no dia em que alguém
+-- inscrever a carteira inteira de uma vez, a frequência ainda será `disabled`
+-- para todos, e a inscrição sozinha não dispara nenhuma consulta ao ambiente
+-- nacional.
+CREATE TABLE IF NOT EXISTS fiscal_sync_policy (
+  id                uuid PRIMARY KEY,
+  tenant_id         uuid NOT NULL REFERENCES tenant(id),
+  -- NULL = padrão do escritório para aquele tipo. A linha do cliente vence.
+  client_id         uuid,
+  document_type     text NOT NULL CHECK (document_type IN ('nfse', 'nfe', 'cte', 'nfce')),
+
+  -- `disabled` é o default da COLUNA além de ser o significado da ausência de
+  -- linha. Redundante de propósito: um INSERT que esqueça a frequência não pode
+  -- resultar em automação ligada.
+  frequency         text NOT NULL DEFAULT 'disabled'
+                      CHECK (frequency IN ('disabled', 'hourly', 'daily', 'business_day')),
+  -- Hora local (America/Sao_Paulo) em que a janela diária abre. Buscar nota de
+  -- madrugada não é mais rápido e some do horário em que há alguém para olhar.
+  window_hour_local int NOT NULL DEFAULT 8 CHECK (window_hour_local BETWEEN 0 AND 23),
+
+  enabled_at        timestamptz,
+  enabled_by        uuid REFERENCES "user"(id),
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  updated_at        timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT fiscal_sync_policy_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  -- Frequência ligada sem registro de quem ligou e quando é automação sem dono.
+  CONSTRAINT fiscal_sync_policy_enabled_has_author
+    CHECK (frequency = 'disabled' OR (enabled_at IS NOT NULL))
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS fiscal_sync_policy_client_uq
+  ON fiscal_sync_policy (tenant_id, client_id, document_type) WHERE client_id IS NOT NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS fiscal_sync_policy_default_uq
+  ON fiscal_sync_policy (tenant_id, document_type) WHERE client_id IS NULL;
+
+ALTER TABLE fiscal_sync_policy ENABLE ROW LEVEL SECURITY;
+ALTER TABLE fiscal_sync_policy FORCE ROW LEVEL SECURITY;
+CREATE POLICY fiscal_sync_policy_tenant_isolation ON fiscal_sync_policy
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ── 3 · O provedor caiu para todos ─────────────────────────────────────────
+--
+-- O `next_attempt_after` da 0056 é POR CLIENTE, e resolve o caso de um cliente
+-- cuja consulta falhou. Ele não resolve o caso oposto e mais provável: o
+-- ambiente nacional fora do ar às 8h. Com cem clientes elegíveis, o recuo por
+-- cliente produz cem requisições contra um serviço que já respondeu que está
+-- indisponível — precisamente o padrão de consumo que o cStat 656 pune, e cujo
+-- bloqueio recai sobre o CNPJ de cem terceiros.
+--
+-- Um estado por (escritório, fonte, ambiente) faz o segundo cliente já nascer
+-- barrado pela falha do primeiro. `half_open` existe para que a reabertura seja
+-- um cliente de prova, e não a carteira inteira de uma vez.
+CREATE TABLE IF NOT EXISTS fiscal_provider_circuit (
+  id                   uuid PRIMARY KEY,
+  tenant_id            uuid NOT NULL REFERENCES tenant(id),
+  source               text NOT NULL,
+  environment          text NOT NULL
+                         CHECK (environment IN ('synthetic', 'homologation', 'production')),
+
+  state                text NOT NULL DEFAULT 'closed'
+                         CHECK (state IN ('closed', 'open', 'half_open')),
+  consecutive_failures int NOT NULL DEFAULT 0 CHECK (consecutive_failures >= 0),
+  last_error_class     text,
+  opened_at            timestamptz,
+  open_until           timestamptz,
+  last_failure_at      timestamptz,
+  last_success_at      timestamptz,
+  created_at           timestamptz NOT NULL DEFAULT now(),
+  updated_at           timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT fiscal_provider_circuit_tenant_id_uq UNIQUE (tenant_id, id),
+  -- Aberto sem prazo é fechado para sempre. O banco recusa a linha em vez de
+  -- confiar que o TypeScript sempre preencherá a data.
+  CONSTRAINT fiscal_provider_circuit_open_has_deadline
+    CHECK (state <> 'open' OR open_until IS NOT NULL)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS fiscal_provider_circuit_uq
+  ON fiscal_provider_circuit (tenant_id, source, environment);
+
+ALTER TABLE fiscal_provider_circuit ENABLE ROW LEVEL SECURITY;
+ALTER TABLE fiscal_provider_circuit FORCE ROW LEVEL SECURITY;
+CREATE POLICY fiscal_provider_circuit_tenant_isolation ON fiscal_provider_circuit
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ── 4 · O que só uma pessoa resolve ────────────────────────────────────────
+--
+-- Certificado vencido não é falha transitória: nenhuma quantidade de tentativas
+-- renova um A1. Mas transformar cada tentativa numa tarefa produziria uma fila
+-- com trinta linhas idênticas até o fim do mês — e uma fila que ninguém
+-- consegue ler é indistinguível de uma fila vazia.
+--
+-- Por isso a chave: UMA linha aberta por (escritório, cliente, motivo, fonte,
+-- ambiente), com contador. A trigésima ocorrência incrementa `occurrences` e
+-- move `last_seen_at`; ela não cria a trigésima tarefa.
+CREATE TABLE IF NOT EXISTS fiscal_intervention (
+  id             uuid PRIMARY KEY,
+  tenant_id      uuid NOT NULL REFERENCES tenant(id),
+  -- NULL quando o problema é do PROVEDOR e não de um cliente específico.
+  client_id      uuid,
+  kind           text NOT NULL
+                   CHECK (kind IN ('auth_required', 'certificate_expired', 'certificate_invalid',
+                                   'provider_access_denied', 'unsupported_source',
+                                   'repeated_failure')),
+  source         text,
+  environment    text CHECK (environment IS NULL OR
+                             environment IN ('synthetic', 'homologation', 'production')),
+  document_type  text CHECK (document_type IS NULL OR
+                             document_type IN ('nfse', 'nfe', 'cte', 'nfce')),
+
+  state          text NOT NULL DEFAULT 'open'
+                   CHECK (state IN ('open', 'acknowledged', 'resolved')),
+  -- Classe e contexto. NUNCA a resposta do provedor: um erro de TLS mútuo cita
+  -- caminho de arquivo e sujeito do certificado, e esta coluna vai para a tela.
+  detail         text NOT NULL,
+  occurrences    int NOT NULL DEFAULT 1 CHECK (occurrences > 0),
+
+  first_seen_at  timestamptz NOT NULL DEFAULT now(),
+  last_seen_at   timestamptz NOT NULL DEFAULT now(),
+  resolved_at    timestamptz,
+  resolved_by    uuid REFERENCES "user"(id),
+
+  CONSTRAINT fiscal_intervention_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  -- Resolvido sem data seria uma fila que esvazia sem deixar quando.
+  CONSTRAINT fiscal_intervention_resolved_coherent
+    CHECK ((state = 'resolved') = (resolved_at IS NOT NULL))
+);
+
+-- A deduplicação é do índice. `coalesce` porque NULL não colide com NULL em
+-- índice único, e sem isto cada tentativa criaria uma linha nova para um
+-- problema de provedor (client_id NULL) — a fila ilegível que a tabela evita.
+CREATE UNIQUE INDEX IF NOT EXISTS fiscal_intervention_open_uq
+  ON fiscal_intervention (
+    tenant_id,
+    coalesce(client_id, '00000000-0000-0000-0000-000000000000'::uuid),
+    kind,
+    coalesce(source, ''),
+    coalesce(environment, '')
+  ) WHERE state <> 'resolved';
+CREATE INDEX IF NOT EXISTS fiscal_intervention_open_idx
+  ON fiscal_intervention (tenant_id, state, last_seen_at DESC);
+
+ALTER TABLE fiscal_intervention ENABLE ROW LEVEL SECURITY;
+ALTER TABLE fiscal_intervention FORCE ROW LEVEL SECURITY;
+CREATE POLICY fiscal_intervention_tenant_isolation ON fiscal_intervention
+  USING (
+    tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid
+    AND (
+      NULLIF(current_setting('app.current_client', true), '') IS NULL
+      OR client_id = NULLIF(current_setting('app.current_client', true), '')::uuid
+    )
+  )
+  WITH CHECK (
+    tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid
+    AND (
+      NULLIF(current_setting('app.current_client', true), '') IS NULL
+      OR client_id = NULLIF(current_setting('app.current_client', true), '')::uuid
+    )
+  );
+
+-- ── 5 · Cobertura: o que sabemos, e o tamanho do que não sabemos ───────────
+--
+-- ═══ A afirmação perigosa ══════════════════════════════════════════════════
+--
+-- "O ADN cobre a NFS-e do Brasil inteiro" é falsa, e é a frase que um produto
+-- nacional diz sem perceber. A NFS-e nacional depende de ADESÃO do município ao
+-- convênio; os que não aderiram continuam emitindo pelo próprio portal, com
+-- login próprio e nenhum NSU. Vender coleta automática para um cliente cuja
+-- prefeitura não aderiu é prometer trabalho que ninguém vai fazer.
+--
+-- ═══ Por que a evidência é uma RESTRIÇÃO, e não uma convenção ══════════════
+--
+-- `fiscal_coverage_claim_needs_evidence` torna INGRAVÁVEL qualquer status que
+-- não seja `UNKNOWN` sem data de verificação e sem fonte. Não há caminho pelo
+-- qual alguém — ou um agente com pressa — declare "coberto" e siga adiante:
+-- afirmar cobertura passa a custar uma referência oficial, no banco, ou o INSERT
+-- falha. `UNKNOWN` é o único estado gratuito, e é o correto por padrão.
+--
+-- ═══ Catálogo GLOBAL, sem tenant e sem RLS ═════════════════════════════════
+--
+-- A adesão de um município ao ADN não é um fato de escritório: é o mesmo para
+-- todos. Uma cópia por tenant divergiria na primeira atualização. Segue o padrão
+-- de `fiscal_attribute_definition` e `platform_capability` — sem `tenant_id`,
+-- logo sem RLS que o proteja, logo o runtime SÓ LÊ (o REVOKE está em
+-- `migrate.ts`, junto dos irmãos).
+CREATE TABLE IF NOT EXISTS fiscal_coverage (
+  id                     uuid PRIMARY KEY,
+  document_type          text NOT NULL CHECK (document_type IN ('nfse', 'nfe', 'cte', 'nfce')),
+  jurisdiction_scope     text NOT NULL
+                           CHECK (jurisdiction_scope IN ('national', 'state', 'municipal')),
+  -- UF (2 letras) ou código IBGE do município (7 dígitos). NULL = a regra
+  -- PADRÃO daquele escopo, que é o que responde por toda jurisdição não medida.
+  jurisdiction_code      text CHECK (jurisdiction_code IS NULL OR
+                                     jurisdiction_code ~ '^([A-Z]{2}|[0-9]{7})$'),
+  provider               text NOT NULL,
+
+  coverage_status        text NOT NULL
+                           CHECK (coverage_status IN ('SUPPORTED_OFFICIAL', 'SUPPORTED_PROVIDER',
+                                                      'SUPPORTED_MANUAL_FALLBACK', 'UNKNOWN',
+                                                      'UNSUPPORTED')),
+  automation_method      text CHECK (automation_method IS NULL OR
+                                     automation_method IN ('dfe_nsu_soap', 'dfe_nsu_rest',
+                                                           'provider_api', 'portal_manual',
+                                                           'manual_upload')),
+  credential_requirement text NOT NULL DEFAULT 'unknown'
+                           CHECK (credential_requirement IN ('none', 'icp_brasil_mtls',
+                                                             'municipal_portal_login',
+                                                             'provider_api_key', 'unknown')),
+  -- Ambientes em que o caminho existe. Vazio = nenhum exercível hoje.
+  environments           text[] NOT NULL DEFAULT '{}',
+  fallback_type          text CHECK (fallback_type IS NULL OR
+                                     fallback_type IN ('manual_upload', 'client_delivery',
+                                                       'issuer_export', 'none')),
+  last_verified_at       date,
+  source_reference       text,
+  notes                  text,
+  created_at             timestamptz NOT NULL DEFAULT now(),
+  updated_at             timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT fiscal_coverage_claim_needs_evidence
+    CHECK (coverage_status = 'UNKNOWN'
+           OR (last_verified_at IS NOT NULL AND source_reference IS NOT NULL))
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS fiscal_coverage_key_uq
+  ON fiscal_coverage (document_type, jurisdiction_scope, coalesce(jurisdiction_code, ''), provider);
+
+COMMENT ON CONSTRAINT fiscal_coverage_claim_needs_evidence ON fiscal_coverage IS
+  'Afirmar cobertura custa fonte e data. UNKNOWN é o único status gratuito — e o correto quando ninguém mediu.';
+
+-- Semeado AQUI, e não num seed posterior, porque um banco limpo sem estas linhas
+-- responderia "não sabemos" até que alguém rodasse outro comando — e a diferença
+-- entre "medimos e não há" e "ninguém rodou o seed" é invisível na tela.
+INSERT INTO fiscal_coverage (
+  id, document_type, jurisdiction_scope, jurisdiction_code, provider, coverage_status,
+  automation_method, credential_requirement, environments, fallback_type,
+  last_verified_at, source_reference, notes
+) VALUES
+  -- NF-e: distribuição nacional confirmada. E a limitação que decide produto:
+  -- o DF-e NÃO devolve as notas que a própria empresa emitiu.
+  (gen_random_uuid(), 'nfe', 'national', NULL, 'sefaz_dfe', 'SUPPORTED_OFFICIAL',
+   'dfe_nsu_soap', 'icp_brasil_mtls', ARRAY['homologation', 'production'], 'issuer_export',
+   DATE '2026-09-07', 'NT 2014.002 v1.02c (ago/2020) — WS NFeDistribuicaoDFe, nfeDistDFeInteresse',
+   'Documentos EMITIDOS pela própria empresa não são distribuídos: para esses, a origem é o emissor do cliente. Espera obrigatória de 1h após cStat 137; consultar antes devolve cStat 656 e bloqueia o CNPJ do contribuinte.'),
+
+  -- CT-e: mesma mecânica, mesma norma irmã. Forma medida na pesquisa da Onda B;
+  -- a distribuição em si nunca foi exercida — por isso o `notes` diz isso.
+  (gen_random_uuid(), 'cte', 'national', NULL, 'sefaz_dfe', 'SUPPORTED_OFFICIAL',
+   'dfe_nsu_soap', 'icp_brasil_mtls', ARRAY['homologation', 'production'], 'issuer_export',
+   DATE '2026-09-07', 'NT 2015.002 — WS CTeDistribuicaoDFe',
+   'Forma de distribuição idêntica à da NF-e (distNSU/consNSU, ultNSU/maxNSU, docZip). Nenhuma chamada autenticada foi feita; adapter não implementado.'),
+
+  -- NFS-e nacional: a API existe e está documentada. O que ela alcança é outra
+  -- pergunta — respondida pela linha municipal abaixo.
+  (gen_random_uuid(), 'nfse', 'national', NULL, 'nfse_adn', 'SUPPORTED_OFFICIAL',
+   'dfe_nsu_rest', 'icp_brasil_mtls', ARRAY['homologation', 'production'], 'client_delivery',
+   DATE '2026-09-07', 'Manual dos Contribuintes — API do ADN v1.0 (12/02/2026), gov.br/nfse',
+   'Alcança apenas municípios que aderiram ao convênio da NFS-e nacional. O host exige TLS mútuo com certificado ICP-Brasil, inclusive para servir a documentação.'),
+
+  -- A linha que impede a afirmação perigosa. É ela que qualquer pergunta
+  -- municipal sem medição encontra — e ela responde `UNKNOWN`, não "coberto".
+  (gen_random_uuid(), 'nfse', 'municipal', NULL, 'municipio', 'UNKNOWN',
+   NULL, 'unknown', ARRAY[]::text[], 'manual_upload',
+   NULL, NULL,
+   'Adesão do município ao ADN não verificada. Enquanto não for, a coleta da NFS-e daquele município é desconhecida — nunca automática por herança da linha nacional.'),
+
+  -- NFC-e não é distribuída ao consumidor por DF-e. Não sabemos de caminho, e
+  -- dizê-lo é mais útil do que inventar um.
+  (gen_random_uuid(), 'nfce', 'national', NULL, 'sefaz_dfe', 'UNKNOWN',
+   NULL, 'unknown', ARRAY[]::text[], 'issuer_export',
+   NULL, NULL,
+   'Nenhuma pesquisa oficial desta onda cobriu a distribuição de NFC-e. Status permanece desconhecido até alguém medir.')
+ON CONFLICT DO NOTHING;
+
+-- ── 6 · O que o cursor não guardava sobre a EXECUÇÃO ───────────────────────
+--
+-- A 0056 modelou a posição no provedor (`last_nsu`, `max_nsu`) e a espera
+-- imposta por ele (`next_attempt_after`). Faltava o outro eixo: a cadência que
+-- NÓS escolhemos. São coisas distintas e a distinção importa — `next_attempt_after`
+-- é o provedor dizendo "não me procure antes disso" e desobedecê-lo bloqueia o
+-- CNPJ do cliente; `next_eligible_run_at` é a política do escritório dizendo
+-- "uma vez por dia basta" e antecipá-lo é só desperdício.
+--
+-- O gate efetivo é o MAIOR dos dois. Colapsá-los numa coluna só faria uma
+-- política diária apagar uma espera obrigatória de uma hora.
+ALTER TABLE fiscal_sync_cursor ADD COLUMN IF NOT EXISTS last_started_at timestamptz;
+ALTER TABLE fiscal_sync_cursor ADD COLUMN IF NOT EXISTS last_completed_at timestamptz;
+ALTER TABLE fiscal_sync_cursor ADD COLUMN IF NOT EXISTS next_eligible_run_at timestamptz;
+
+COMMENT ON COLUMN fiscal_sync_cursor.next_eligible_run_at IS
+  'Cadência NOSSA (política). Distinta de next_attempt_after, que é espera do PROVEDOR: desobedecer aquela bloqueia o CNPJ do cliente; antecipar esta é só desperdício. O gate é o maior dos dois.';
+
+-- ── 7 · A trilha do lote ganha identidade de execução ──────────────────────
+--
+-- `fiscal_sync_run` (0056) já registra contadores e cursor. Faltava dizer QUEM
+-- executou (qual worker, em qual versão) e o que aconteceu com os EVENTOS — que
+-- foi justamente o eixo que a Fase 1 · R1 teve de corrigir no pipeline e não
+-- chegou a refletir na trilha.
+ALTER TABLE fiscal_sync_run ADD COLUMN IF NOT EXISTS job_name text;
+ALTER TABLE fiscal_sync_run ADD COLUMN IF NOT EXISTS job_version int;
+ALTER TABLE fiscal_sync_run ADD COLUMN IF NOT EXISTS lease_id uuid;
+ALTER TABLE fiscal_sync_run ADD COLUMN IF NOT EXISTS events_pending int NOT NULL DEFAULT 0;
+ALTER TABLE fiscal_sync_run ADD COLUMN IF NOT EXISTS events_applied int NOT NULL DEFAULT 0;
+ALTER TABLE fiscal_sync_run ADD COLUMN IF NOT EXISTS events_reconciled int NOT NULL DEFAULT 0;
+-- Estado de retentativa DESTA execução, para que a decisão fique auditável sem
+-- ter de reconstruí-la a partir da classe do erro.
+ALTER TABLE fiscal_sync_run ADD COLUMN IF NOT EXISTS retryable boolean;
+ALTER TABLE fiscal_sync_run ADD COLUMN IF NOT EXISTS retry_after timestamptz;
+ALTER TABLE fiscal_sync_run ADD COLUMN IF NOT EXISTS attempt int;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT FROM pg_constraint WHERE conname = 'fiscal_sync_run_event_counts_nonneg') THEN
+    ALTER TABLE fiscal_sync_run ADD CONSTRAINT fiscal_sync_run_event_counts_nonneg
+      CHECK (events_pending >= 0 AND events_applied >= 0 AND events_reconciled >= 0);
+  END IF;
+  IF NOT EXISTS (SELECT FROM pg_constraint WHERE conname = 'fiscal_sync_run_blocked_has_no_events') THEN
+    -- A mesma invariante do `..._blocked_is_inert`, estendida aos eventos: um
+    -- lote que não rodou não pode ter mexido em evento nenhum. O banco recusa a
+    -- linha incoerente em vez de confiar na ordem das atribuições.
+    ALTER TABLE fiscal_sync_run ADD CONSTRAINT fiscal_sync_run_blocked_has_no_events
+      CHECK (outcome NOT IN ('blocked_eligibility', 'blocked_credential', 'blocked_contract', 'throttled')
+             OR (events_pending = 0 AND events_applied = 0 AND events_reconciled = 0));
+  END IF;
+END $$;
+
+CREATE INDEX IF NOT EXISTS fiscal_sync_run_job_idx
+  ON fiscal_sync_run (tenant_id, job_name, started_at DESC);
+
+-- ── 8 · A capacidade que o worker desta fase exige ─────────────────────────
+--
+-- Declarada na MESMA migration que cria o schema que a sustenta (expand →
+-- declare → deploy → contract). Enquanto ela não existir no banco, o worker fica
+-- INCOMPATIBLE pelo Gate B0 e não escreve nada — que é a janela de skew
+-- resolvida sem coordenação de deploy.
+INSERT INTO platform_capability (key, label, contract_version, declared_by_migration) VALUES
+  ('office.fiscal-sync-worker.v1',
+   'Motor operacional de sincronização fiscal: lease, política, circuito, fila humana e cobertura',
+   1, '0058')
+ON CONFLICT (key) DO NOTHING;
+
+-- ── 9 · Reprocessar o que ficou preservado ─────────────────────────────────
+--
+-- A caixa de entrada da 0057 guarda duas coisas: evento à espera do alvo, e
+-- item que o parser não conseguiu ler. O segundo caso tem um desfecho que a
+-- 0057 não previu — e que é exatamente o motivo de o item ter sido guardado:
+-- **o parser melhora**. Um XML ilegível hoje é legível depois de um deploy, e
+-- reprocessá-lo pode produzir um DOCUMENTO, não um evento.
+--
+-- As restrições da 0057 tornam esse desfecho ingravável: `applied` exige
+-- `applied_event_id`, e qualquer estado diferente de `invalid` exige
+-- `target_access_key` e `event_type` — campos que um documento não tem.
+--
+-- O item ficaria preso em `invalid` para sempre, com o documento já gravado ao
+-- lado dele: um registro dizendo "não deu para ler" sobre bytes que foram lidos.
+ALTER TABLE fiscal_ingestion_inbox ADD COLUMN IF NOT EXISTS applied_document_id uuid;
+ALTER TABLE fiscal_ingestion_inbox ADD COLUMN IF NOT EXISTS reprocessed_at timestamptz;
+ALTER TABLE fiscal_ingestion_inbox ADD COLUMN IF NOT EXISTS reprocess_count int NOT NULL DEFAULT 0;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT FROM pg_constraint WHERE conname = 'fiscal_ingestion_inbox_applied_document_fk'
+  ) THEN
+    ALTER TABLE fiscal_ingestion_inbox
+      ADD CONSTRAINT fiscal_ingestion_inbox_applied_document_fk
+      FOREIGN KEY (tenant_id, applied_document_id) REFERENCES fiscal_document (tenant_id, id);
+  END IF;
+END $$;
+
+ALTER TABLE fiscal_ingestion_inbox
+  DROP CONSTRAINT IF EXISTS fiscal_ingestion_inbox_applied_has_event;
+ALTER TABLE fiscal_ingestion_inbox
+  ADD CONSTRAINT fiscal_ingestion_inbox_applied_has_destination
+  -- Aplicado exige DESTINO: um evento sobre um documento, ou o documento em si.
+  -- A restrição continua fechando o caso que importa — `applied` sem nada do
+  -- outro lado —, e passa a admitir o segundo destino legítimo.
+  CHECK (state <> 'applied'
+         OR (applied_at IS NOT NULL
+             AND (applied_event_id IS NOT NULL OR applied_document_id IS NOT NULL)));
+
+ALTER TABLE fiscal_ingestion_inbox
+  DROP CONSTRAINT IF EXISTS fiscal_ingestion_inbox_event_is_addressable;
+ALTER TABLE fiscal_ingestion_inbox
+  ADD CONSTRAINT fiscal_ingestion_inbox_event_is_addressable
+  -- Item à espera de alvo continua obrigado a dizer QUAL alvo e QUE evento — é
+  -- essa exigência que impede um item sem destino de se disfarçar de pendente.
+  -- O que passa a ser dispensado é o item já resolvido como documento.
+  CHECK (state <> 'pending_target'
+         OR (target_access_key IS NOT NULL AND event_type IS NOT NULL));
+
+ALTER TABLE fiscal_ingestion_inbox
+  DROP CONSTRAINT IF EXISTS fiscal_ingestion_inbox_reprocess_nonneg;
+ALTER TABLE fiscal_ingestion_inbox
+  ADD CONSTRAINT fiscal_ingestion_inbox_reprocess_nonneg CHECK (reprocess_count >= 0);
+
+COMMENT ON COLUMN fiscal_ingestion_inbox.applied_document_id IS
+  'Documento produzido pelo REPROCESSAMENTO de um item antes ilegível. O parser melhora; os bytes guardados existem justamente para essa segunda chance.';

package/src/db/migrations/0059_fiscal_contract_version.sql

@@ -0,0 +1,59 @@
+-- 0059 — qual parser leu este lote.
+--
+-- ═══ A pergunta que a Fase 3 tornou respondível ════════════════════════════
+--
+-- O leiaute da NFS-e nacional mudou duas vezes entre dez/2025 e fev/2026 (XSD
+-- v1.00 → v1.01, e três anexos revisados no intervalo). Vai mudar de novo: a
+-- reforma tributária já colocou o bloco `IBSCBS` no schema vigente e ele ainda
+-- vai ganhar regra de apuração.
+--
+-- Quando isso acontecer, a pergunta operacional é uma só: **quais lotes foram
+-- lidos pelo parser antigo?** Sem esta coluna a resposta exige cruzar a data da
+-- linha com o `git log` do deploy — uma reconstrução que erra na primeira janela
+-- de rollback, porque a data do commit não é a data em que ele estava servindo.
+--
+-- `source` não serve para isso: ele identifica a FONTE (`nfse_adn`), e a fonte é
+-- a mesma antes e depois da mudança de contrato. Sobrecarregá-lo com a versão
+-- quebraria o casamento de adapter no reprocessamento, que compara `source` por
+-- igualdade para escolher quem sabe ler os bytes guardados.
+--
+-- ═══ Por que a coluna é anulável, e não tem default ════════════════════════
+--
+-- `NULL` é a resposta honesta para as linhas que existiam antes desta migration
+-- e para os adapters sintéticos, que não implementam contrato externo nenhum. Um
+-- default como `'nfse-adn:v1'` gravaria uma afirmação falsa em linha nenhuma
+-- para tornar a coluna "mais completa" — e uma coluna que mente é pior que uma
+-- coluna vazia, porque a vazia não engana quem investiga.
+
+ALTER TABLE fiscal_sync_run ADD COLUMN IF NOT EXISTS contract_version text;
+
+COMMENT ON COLUMN fiscal_sync_run.contract_version IS
+  'Versão do contrato do provedor que o adapter implementava neste lote (ex.: nfse-adn:v1). NULL para adapter sintético ou linha anterior à 0059.';
+
+-- ── Segurança de skew ──────────────────────────────────────────────────────
+--
+-- A aplicação que grava esta coluna não pode rodar contra um banco que ainda não
+-- a tem: o `INSERT` falharia no meio do ciclo, depois do lease tomado e
+-- possivelmente depois da requisição ao provedor — o pior lugar para falhar,
+-- porque o consumo já foi gasto e o cursor não avançou.
+--
+-- O Gate B0 resolve isso sem coordenação de deploy, e o mecanismo correto é uma
+-- CAPACIDADE NOVA — não um `contract_version` maior.
+--
+-- ═══ Por que não bumpar `contract_version` ═════════════════════════════════
+--
+-- `platform_capability.contract_version` é a versão do FORMATO DO REGISTRO, e é
+-- global: `probePlatformCapabilities` recusa a tabela inteira quando as linhas
+-- divergem ("registro com versões de contrato divergentes" → `absent`). Subir a
+-- versão de uma linha só derrubaria TODOS os workers — cobrança e faturamento
+-- inclusive — por causa de uma coluna do motor fiscal.
+--
+-- A dimensão certa é a chave. Capacidade é comparada por CONTINÊNCIA: o worker
+-- exige um conjunto, o banco declara outro, e basta que o declarado contenha o
+-- exigido. É por isso que "schema novo com worker velho" funciona de graça — e
+-- é a mesma propriedade que faz "worker novo com schema velho" fechar sozinho.
+INSERT INTO platform_capability (key, label, contract_version, declared_by_migration) VALUES
+  ('office.fiscal-contract-version.v1',
+   'A execução fiscal registra a versão do contrato do provedor que a processou',
+   1, '0059')
+ON CONFLICT (key) DO NOTHING;