@baruk/core 0.4.2 → 0.6.0

package/src/db/migrations/0056_fiscal_document_ingestion.sql

@@ -0,0 +1,337 @@
+-- 0056 — o documento fiscal como registro canônico, e o cursor que o busca.
+--
+-- ═══ O problema operacional, na frase de quem o tem ════════════════════════
+--
+-- A proprietária da SC precisa chegar mais cedo ou sair mais tarde para "fazer
+-- baixa de nota fiscal de cliente". Essa expressão não descreve UMA rotina: ela
+-- cobre buscar NFS-e emitidas no portal do município, buscar NF-e destinadas ao
+-- cliente no ambiente nacional, salvar XML, conferir contra o que o cliente
+-- mandou, e classificar por competência. Fluxos diferentes, sistemas
+-- diferentes, e só o último é trabalho de contador.
+--
+-- Esta migration cria onde o resultado dessa busca cabe — e nada além disso.
+-- Capturar documento NÃO é escriturar: apuração, obrigação e fechamento
+-- continuam em outros domínios, e é deliberado que esta tabela não os toque.
+--
+-- ═══ Por que um modelo só para NF-e, NFS-e e CT-e ══════════════════════════
+--
+-- A pesquisa oficial desta onda mediu que os três compartilham a MESMA forma de
+-- distribuição:
+--
+--   NF-e   NT 2014.002 v1.02c (ago/2020) — WS `NFeDistribuicaoDFe`,
+--          `distNSU`/`consNSU`/`consChNFe`, lote de até 50, `ultNSU`/`maxNSU`,
+--          `docZip` gZip+base64.
+--   CT-e   NT 2015.002 — WS `CTeDistribuicaoDFe`, `distNSU`/`consNSU`,
+--          `ultNSU`/`maxNSU`, `docZip`. Mesma semântica, outro documento.
+--   NFS-e  Manual dos Contribuintes do ADN v1.0 (12/02/2026) —
+--          `GET /DFe/{NSU}` e `GET /NFSe/{ChaveAcesso}/Eventos`. REST em vez de
+--          SOAP, e o MESMO conceito de NSU.
+--
+-- Um cursor NSU sobre um ator identificado por documento serve aos três. Modelar
+-- só NFS-e agora criaria retrabalho garantido, e modelar cada um em tabela
+-- própria triplicaria dedupe, cursor e trilha. Um registro canônico com
+-- `document_type`, e o específico no payload normalizado.
+
+-- ── 1 · O documento fiscal ─────────────────────────────────────────────────
+--
+-- RAW e NORMALIZED coexistem, e nenhum dos dois é derivável do outro em
+-- produção: o XML original é o que tem valor probatório e o que a Receita
+-- reconhece; o normalizado é o que a tela lê sem reparsear XML a cada render.
+-- Normalizar NUNCA destrói o original — `raw_blob_id` aponta para `blob`, que
+-- já carrega sha256, tamanho e chave de storage particionada por
+-- {tenant}/{client}/{yyyy}/{mm}.
+--
+-- `normalized` é jsonb e não colunas por campo. Isso não é preguiça de
+-- modelagem: a reforma tributária acrescenta IBS e CBS aos leiautes, e um
+-- schema rígido demais hoje descartaria em silêncio campos que ainda não
+-- existem. O que é consultado vira coluna; o resto sobrevive no jsonb e no XML.
+CREATE TABLE IF NOT EXISTS fiscal_document (
+  id                 uuid PRIMARY KEY,
+  tenant_id          uuid NOT NULL REFERENCES tenant(id),
+  client_id          uuid NOT NULL,
+
+  document_type      text NOT NULL CHECK (document_type IN ('nfse', 'nfe', 'cte', 'nfce')),
+  -- `received` é o caso que a NT 2014.002 privilegia: "Documentos emitidos pela
+  -- própria empresa NÃO estarão disponíveis para consulta" no DF-e da NF-e. Já
+  -- o ADN da NFS-e devolve documentos em que o contribuinte é emitente,
+  -- tomador OU intermediário. A coluna existe porque a resposta é diferente por
+  -- documento, e tratar tudo como "nota do cliente" perderia a distinção que
+  -- decide o que se faz com ela.
+  direction          text NOT NULL CHECK (direction IN ('issued', 'received', 'intermediary')),
+
+  source             text NOT NULL,
+  -- Sem fallback entre ambientes, nos dois sentidos (Gate B0 §4). Documento de
+  -- homologação nunca vira documento real por omissão de coluna.
+  source_environment text NOT NULL
+                       CHECK (source_environment IN ('synthetic', 'homologation', 'production')),
+  -- Posição do cursor que entregou este documento. Texto e não bigint: o NSU da
+  -- NT 2014.002 tem até 15 dígitos e o do ADN não promete ser numérico.
+  source_nsu         text,
+
+  access_key         text,
+  document_number    text,
+  series             text,
+  issuer_document    text,
+  issuer_name        text,
+  recipient_document text,
+  recipient_name     text,
+  issued_at          timestamptz,
+  -- Competência CONTÁBIL, separada da emissão de propósito: nota emitida em
+  -- 02/10 pode pertencer à competência 2026-09, e assumir que as duas são a
+  -- mesma coisa é como o fechamento mensal sai errado.
+  competence_label   text CHECK (competence_label IS NULL OR competence_label ~ '^\d{4}-\d{2}$'),
+  gross_amount       numeric(14,2),
+  currency           text NOT NULL DEFAULT 'BRL',
+
+  -- Cancelada não é apagada. A nota existiu, foi contabilizada por alguém, e
+  -- some do painel só se alguém decidir escondê-la — nunca por efeito colateral
+  -- de um evento.
+  status             text NOT NULL DEFAULT 'active'
+                       CHECK (status IN ('active', 'cancelled', 'replaced', 'denied')),
+  -- `summary` é o `resNFe`: o que o ambiente nacional entrega ao destinatário
+  -- ANTES da manifestação. `full` é o `procNFe`. A distinção é do leiaute, não
+  -- nossa, e o produto precisa dizer qual tem — um resumo apresentado como
+  -- documento completo é uma mentira sobre o que o escritório possui.
+  content_kind       text NOT NULL DEFAULT 'summary' CHECK (content_kind IN ('summary', 'full')),
+
+  raw_blob_id        uuid,
+  raw_sha256         text CHECK (raw_sha256 IS NULL OR raw_sha256 ~ '^[a-f0-9]{64}$'),
+  normalized         jsonb NOT NULL DEFAULT '{}'::jsonb,
+
+  -- Identidade de deduplicação. Calculada pelo adapter conforme o tipo: chave de
+  -- acesso quando existe, senão o par (fonte, identificador do provedor), senão
+  -- o hash do conteúdo. Nunca o NSU sozinho — o mesmo documento pode reaparecer
+  -- sob outro NSU num replay, e é exatamente esse o caso que a dedupe existe
+  -- para absorver.
+  dedupe_key         text NOT NULL,
+
+  ingested_at        timestamptz NOT NULL DEFAULT now(),
+  updated_at         timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT fiscal_document_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  FOREIGN KEY (tenant_id, raw_blob_id) REFERENCES blob (tenant_id, id),
+  -- Um documento marcado `full` sem original guardado é uma afirmação sem
+  -- lastro. `summary` pode não ter blob: o resumo cabe no normalizado.
+  CONSTRAINT fiscal_document_full_has_raw
+    CHECK (content_kind <> 'full' OR raw_blob_id IS NOT NULL)
+);
+
+-- A dedupe é por (tenant, cliente, chave). Cliente entra porque a MESMA nota
+-- pode ser destinada a um cliente e emitida por outro dentro do mesmo
+-- escritório — são dois fatos contábeis distintos sobre o mesmo XML.
+CREATE UNIQUE INDEX IF NOT EXISTS fiscal_document_dedupe_uq
+  ON fiscal_document (tenant_id, client_id, dedupe_key);
+
+CREATE INDEX IF NOT EXISTS fiscal_document_client_idx
+  ON fiscal_document (tenant_id, client_id, issued_at DESC);
+CREATE INDEX IF NOT EXISTS fiscal_document_competence_idx
+  ON fiscal_document (tenant_id, competence_label, document_type);
+
+ALTER TABLE fiscal_document ENABLE ROW LEVEL SECURITY;
+ALTER TABLE fiscal_document FORCE ROW LEVEL SECURITY;
+-- Duas fronteiras, não uma. O ramo aberto de `app.current_client` é o mesmo
+-- padrão das demais tabelas client-scoped: staff vê o escritório inteiro, o
+-- portal vê só o próprio cliente.
+CREATE POLICY fiscal_document_tenant_isolation ON fiscal_document
+  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
+    )
+  );
+
+COMMENT ON COLUMN fiscal_document.competence_label IS
+  'Competência CONTÁBIL (YYYY-MM), separada de issued_at: emissão e competência divergem, e assumir que são a mesma coisa erra o fechamento.';
+COMMENT ON COLUMN fiscal_document.content_kind IS
+  'summary = resNFe (o que o ambiente nacional entrega antes da manifestação); full = procNFe. Apresentar resumo como documento completo é mentir sobre o que o escritório possui.';
+
+-- ── 2 · Eventos do documento ───────────────────────────────────────────────
+--
+-- Cancelamento, substituição e correção são EVENTOS, e o documento continua
+-- existindo. A NT 2014.002 é explícita: o cancelamento é entregue mesmo sem
+-- manifestação do destinatário, justamente porque ele muda o que a nota
+-- significa sem apagá-la.
+CREATE TABLE IF NOT EXISTS fiscal_document_event (
+  id                 uuid PRIMARY KEY,
+  tenant_id          uuid NOT NULL REFERENCES tenant(id),
+  fiscal_document_id uuid NOT NULL,
+  event_type         text NOT NULL
+                       CHECK (event_type IN ('cancellation', 'replacement', 'correction',
+                                             'manifestation', 'other')),
+  event_code         text,
+  occurred_at        timestamptz,
+  source_nsu         text,
+  raw_blob_id        uuid,
+  payload            jsonb NOT NULL DEFAULT '{}'::jsonb,
+  dedupe_key         text NOT NULL,
+  ingested_at        timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT fiscal_document_event_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, fiscal_document_id) REFERENCES fiscal_document (tenant_id, id),
+  FOREIGN KEY (tenant_id, raw_blob_id) REFERENCES blob (tenant_id, id)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS fiscal_document_event_dedupe_uq
+  ON fiscal_document_event (tenant_id, fiscal_document_id, dedupe_key);
+
+ALTER TABLE fiscal_document_event ENABLE ROW LEVEL SECURITY;
+ALTER TABLE fiscal_document_event FORCE ROW LEVEL SECURITY;
+CREATE POLICY fiscal_document_event_tenant_isolation ON fiscal_document_event
+  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 cursor de sincronização ──────────────────────────────────────────
+--
+-- Por (tenant, cliente, fonte, ambiente), e não por job: o NSU do ambiente
+-- nacional é POR CNPJ consultado. O `job_cursor` do Gate B0 é por tenant e não
+-- tem essa granularidade — reaproveitá-lo colapsaria a posição de todos os
+-- clientes numa só e o primeiro cliente sincronizado apagaria a posição dos
+-- outros.
+--
+-- ═══ `next_attempt_after` é a defesa contra o cStat 656 ════════════════════
+--
+-- A NT 2014.002 §3.5 é explícita: "A empresa deverá aguardar um tempo mínimo de
+-- UMA HORA para efetuar uma nova solicitação de distribuição caso receba a
+-- indicação que não existem mais documentos" (`ultNSU` == `maxNSU`, cStat 137).
+-- Consultar antes disso é "consumo indevido" e o ambiente nacional rejeita com
+-- **cStat 656**, bloqueando o CNPJ.
+--
+-- E o CNPJ bloqueado é o DO CLIENTE, não o nosso. Um laço mal escrito aqui
+-- produz dano num terceiro que não pediu nada — por isso a espera é uma coluna
+-- do banco e não um `sleep` no processo. Processo morre; linha não.
+CREATE TABLE IF NOT EXISTS fiscal_sync_cursor (
+  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')),
+  -- Última posição CONFIRMADAMENTE persistida. Nunca adiantada antes do commit
+  -- dos documentos daquele lote.
+  last_nsu             text,
+  -- Maior NSU que o provedor declarou existir. `last_nsu = max_nsu` é a
+  -- condição que arma a espera de uma hora.
+  max_nsu              text,
+  last_success_at      timestamptz,
+  -- Antes deste instante, nenhuma requisição sai. É o que impede o 656.
+  next_attempt_after   timestamptz,
+  consecutive_failures int NOT NULL DEFAULT 0 CHECK (consecutive_failures >= 0),
+  last_error_class     text,
+  contract_version     int NOT NULL DEFAULT 1,
+  created_at           timestamptz NOT NULL DEFAULT now(),
+  updated_at           timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT fiscal_sync_cursor_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS fiscal_sync_cursor_uq
+  ON fiscal_sync_cursor (tenant_id, client_id, source, environment);
+
+ALTER TABLE fiscal_sync_cursor ENABLE ROW LEVEL SECURITY;
+ALTER TABLE fiscal_sync_cursor FORCE ROW LEVEL SECURITY;
+CREATE POLICY fiscal_sync_cursor_tenant_isolation ON fiscal_sync_cursor
+  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_cursor.next_attempt_after IS
+  'Defesa contra o cStat 656 da NT 2014.002: uma hora de espera depois de cStat 137. O CNPJ que o 656 bloqueia é o do CLIENTE — por isso a espera é linha de banco, não sleep de processo.';
+
+-- ── 4 · A trilha do lote ───────────────────────────────────────────────────
+--
+-- `job_run` (Gate B0) responde "o worker pôde rodar?". Esta responde "o que a
+-- busca trouxe?" — são perguntas diferentes e uma não substitui a outra.
+--
+-- Sem XML e sem PII: contadores, classe de erro e as duas pontas do cursor.
+CREATE TABLE IF NOT EXISTS fiscal_sync_run (
+  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')),
+  outcome             text NOT NULL
+                        CHECK (outcome IN ('completed', 'no_documents', 'throttled',
+                                           'blocked_eligibility', 'blocked_credential',
+                                           'blocked_contract', 'provider_error', 'failed')),
+  documents_fetched   int NOT NULL DEFAULT 0 CHECK (documents_fetched >= 0),
+  documents_new       int NOT NULL DEFAULT 0 CHECK (documents_new >= 0),
+  documents_duplicate int NOT NULL DEFAULT 0 CHECK (documents_duplicate >= 0),
+  documents_failed    int NOT NULL DEFAULT 0 CHECK (documents_failed >= 0),
+  cursor_before       text,
+  cursor_after        text,
+  error_class         text,
+  detail              text,
+  started_at          timestamptz NOT NULL DEFAULT now(),
+  finished_at         timestamptz,
+  duration_ms         int,
+  CONSTRAINT fiscal_sync_run_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  -- A mesma invariante do `job_run`, aplicada ao dado: um lote bloqueado não
+  -- trouxe documento e não moveu cursor. O banco recusa a linha incoerente em
+  -- vez de confiar na ordem das operações do TypeScript.
+  CONSTRAINT fiscal_sync_run_blocked_is_inert
+    CHECK (outcome NOT IN ('blocked_eligibility', 'blocked_credential', 'blocked_contract', 'throttled')
+           OR (documents_fetched = 0 AND documents_new = 0 AND cursor_after IS NOT DISTINCT FROM cursor_before))
+);
+
+CREATE INDEX IF NOT EXISTS fiscal_sync_run_idx
+  ON fiscal_sync_run (tenant_id, client_id, started_at DESC);
+
+ALTER TABLE fiscal_sync_run ENABLE ROW LEVEL SECURITY;
+ALTER TABLE fiscal_sync_run FORCE ROW LEVEL SECURITY;
+CREATE POLICY fiscal_sync_run_tenant_isolation ON fiscal_sync_run
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ── 5 · A capacidade que o worker fiscal vai exigir ────────────────────────
+--
+-- Declarada AQUI, na mesma migration que cria o schema que a sustenta — é a
+-- regra expand → declare → deploy → contract do doc 142. Antes disso o worker
+-- fica INCOMPATIBLE e não escreve; depois passa sozinho.
+INSERT INTO platform_capability (key, label, contract_version, declared_by_migration) VALUES
+  ('office.fiscal-ingestion.v1',
+   'Ingestão de documentos fiscais: registro canônico, eventos, cursor e trilha', 1, '0056')
+ON CONFLICT (key) DO NOTHING;
+
+-- ── 6 · O terceiro ambiente ────────────────────────────────────────────────
+--
+-- A 0055 modelou dois: `synthetic` e `production`. A pesquisa desta onda mostrou
+-- que faltava um, e que ele é o mais importante do meio do caminho: a
+-- **produção restrita** do ADN (`adn.producaorestrita.nfse.gov.br`) e a
+-- homologação da SEFAZ não são nem laboratório nem produção. São ambientes
+-- OFICIAIS, que respondem como o real, com documento que não vale nada.
+--
+-- Sem essa distinção, ligar homologação exigiria declarar o escritório em
+-- `production` — e aí um adapter apontado para produção de verdade passaria a
+-- elegibilidade que alguém abriu para ensaiar. É o fallback silencioso que o
+-- Gate B0 proibiu, entrando pela porta do vocabulário.
+ALTER TABLE tenant_fiscal_automation DROP CONSTRAINT IF EXISTS tenant_fiscal_automation_mode_check;
+ALTER TABLE tenant_fiscal_automation ADD CONSTRAINT tenant_fiscal_automation_mode_check
+  CHECK (mode IN ('disabled', 'synthetic', 'homologation', 'production'));
+
+COMMENT ON COLUMN tenant_fiscal_automation.mode IS
+  'disabled (ausência de linha também) | synthetic (fixture) | homologation (ambiente OFICIAL de teste, documento sem valor) | production. Sem fallback entre eles, em nenhuma direção.';
+
+-- ── 6 · Retirada de `client_fiscal_credential` ─────────────────────────────
+--
+-- Criada ontem, na 0055, e é invenção: o domínio de certificado já existe em
+-- `digital_certificate` (vertical contábil, migration 1002), COM consumidores
+-- vivos — a rota de compliance e o painel do piloto. Duas tabelas para o mesmo
+-- fato dariam duas respostas para "este cliente tem certificado?", e elas
+-- divergiriam na primeira vez que alguém atualizasse só uma.
+--
+-- A remoção é segura e foi medida antes: em produção a tabela tem
+-- `n_tup_ins = 0` — nenhuma inserção desde a criação, não apenas nenhuma linha
+-- viva. Nada é perdido porque nada foi escrito.
+--
+-- A prontidão passa a sair de `digital_certificate`, que ganha o que lhe
+-- faltava para responder à pergunta (ver a migration 1004 da vertical).
+DROP TABLE IF EXISTS client_fiscal_credential;

package/src/db/migrations/0057_fiscal_pending_event_inbox.sql

@@ -0,0 +1,228 @@
+-- 0057 — a caixa de entrada da ingestão fiscal, e a direção que deixa de ser adivinhada.
+--
+-- ═══ O defeito que esta migration existe para fechar ═══════════════════════
+--
+-- A 0056 modelou `fiscal_document_event` como evento DE um documento: a coluna
+-- `fiscal_document_id` é `NOT NULL` e tem chave estrangeira. Está certo — um
+-- cancelamento é, por definição, o cancelamento de uma nota.
+--
+-- O que faltava é o que fazer com o evento que chega ANTES da nota. E ele
+-- chega: o ambiente nacional ordena a distribuição por RECEPÇÃO, não por
+-- emissão, e a NT 2014.002 não promete o contrário em lugar nenhum. Um evento
+-- de NSU 100 sobre um documento que só será entregue no NSU 101 é o caso
+-- normal, não a exceção.
+--
+-- O motor tratava esse evento como "duplicado", contava o item como absorvido e
+-- **avançava o cursor**. O NSU 100 ficava commitado sem que nada de 100
+-- existisse em lugar algum — e quando o documento 101 chegasse, o cancelamento
+-- dele já teria sido perdido para sempre. Uma nota cancelada permaneceria
+-- válida no fechamento, e a única forma de descobrir seria a fiscalização.
+--
+-- ═══ A invariante, escrita de uma vez ══════════════════════════════════════
+--
+--   NENHUM NSU É COMMITADO SEM QUE A INFORMAÇÃO CORRESPONDENTE ESTEJA
+--   DURAVELMENTE PRESERVADA.
+--
+-- "Duravelmente preservada" tem quatro formas, e todas são linha de banco:
+-- documento gravado, evento aplicado, evento GUARDADO À ESPERA do alvo, ou
+-- item ilegível guardado como tal. Não encontrar o alvo não é nenhuma delas.
+--
+-- ═══ Por que uma caixa de entrada, e não `fiscal_document_event` nullable ══
+--
+-- Tornar `fiscal_document_id` nulável custaria mais do que parece:
+--
+--   · a deduplicação é `UNIQUE (tenant_id, fiscal_document_id, dedupe_key)`, e
+--     em índice único NULL não colide com NULL — o mesmo evento pendente
+--     entraria quantas vezes fosse reapresentado, que é exatamente a
+--     propriedade que a dedupe existe para dar;
+--   · a tabela não tem `client_id`, e sem ele não há como provar que o evento
+--     do Cliente A não reconcilia com o documento do Cliente B — a RLS dela é
+--     de tenant apenas, porque o documento-alvo já carregava a fronteira de
+--     cliente;
+--   · e a invariante "todo evento pertence a um documento", que hoje o banco
+--     garante, viraria disciplina de código.
+--
+-- Então a espera vive em tabela própria. Ela NÃO é um domínio paralelo: nada
+-- aqui é consultado como documento fiscal, nada aqui aparece na tela de
+-- documentos, e a vida de uma linha daqui termina virando
+-- `fiscal_document_event`. É uma caixa de entrada, e caixa de entrada é a
+-- estrutura certa para "chegou, é válido, ainda não dá para arquivar".
+--
+-- ═══ Por que o RAW mora aqui dentro, em `bytea` ════════════════════════════
+--
+-- O documento fiscal guarda o XML no `blob` (storage externo, sha256, chave
+-- particionada) e está certo: ele é grande, é permanente e tem valor
+-- probatório. A caixa de entrada é o oposto — pequena, transitória e a única
+-- coisa que separa o cursor de perder informação.
+--
+-- Se a preservação dependesse do storage, existiria uma janela real: gravar o
+-- objeto, o processo morrer, e o cursor commitar depois com base num `PUT` que
+-- não aconteceu. Guardando os bytes na MESMA transação que move o cursor, a
+-- janela não existe — ou as duas coisas acontecem, ou nenhuma. É a diferença
+-- entre uma invariante e uma intenção.
+--
+-- Quando o evento é reconciliado, o `fiscal_document_event` resultante segue o
+-- caminho normal do `blob`; a linha desta caixa mantém os bytes originais como
+-- histórico, e é isso que permite reprocessar um evento aplicado por engano sem
+-- pedir nada ao provedor de novo.
+
+-- ── 1 · A caixa de entrada ─────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS fiscal_ingestion_inbox (
+  id                 uuid PRIMARY KEY,
+  tenant_id          uuid NOT NULL REFERENCES tenant(id),
+  -- Presente e NOT NULL de propósito: é a fronteira que impede o evento de um
+  -- cliente de reconciliar com o documento de outro dentro do mesmo escritório.
+  client_id          uuid NOT NULL,
+
+  source             text NOT NULL,
+  source_environment text NOT NULL
+                       CHECK (source_environment IN ('synthetic', 'homologation', 'production')),
+  -- O NSU que entregou o item. NOT NULL aqui, ao contrário de
+  -- `fiscal_document.source_nsu`: uma linha desta tabela SÓ existe por causa de
+  -- um item de cursor, e sem o NSU não há como responder "o que havia em 100?".
+  source_nsu         text NOT NULL,
+
+  -- Os três estados, e o que cada um significa:
+  --
+  --   pending_target  evento válido cujo documento-alvo ainda não chegou.
+  --   applied         já virou `fiscal_document_event`. Fica como histórico.
+  --   invalid         o item não pôde ser interpretado. Os bytes ficam para
+  --                   recuperação manual (`consNSU`) em vez de sumirem.
+  --
+  -- Não há estado `duplicate`: item repetido não cria linha nenhuma — o índice
+  -- único abaixo o absorve, e a repetição é um DESFECHO da ingestão, não um
+  -- estado do dado. Chamar de duplicata o evento sem alvo foi o defeito
+  -- original, e o vocabulário não vai voltar a permiti-lo.
+  state              text NOT NULL DEFAULT 'pending_target'
+                       CHECK (state IN ('pending_target', 'applied', 'invalid')),
+
+  document_type      text CHECK (document_type IS NULL
+                                 OR document_type IN ('nfse', 'nfe', 'cte', 'nfce')),
+  event_type         text CHECK (event_type IS NULL
+                                 OR event_type IN ('cancellation', 'replacement', 'correction',
+                                                   'manifestation', 'other')),
+  event_code         text,
+  -- `nSeqEvento` do leiaute. Entra na ordem de aplicação quando dois eventos
+  -- do mesmo tipo caem na mesma caixa.
+  event_sequence     text,
+  occurred_at        timestamptz,
+  -- Chave do documento que este evento altera. É por ela que a reconciliação
+  -- encontra o que estava esperando.
+  target_access_key  text,
+
+  raw                bytea NOT NULL CHECK (octet_length(raw) <= 8388608),
+  raw_sha256         text NOT NULL CHECK (raw_sha256 ~ '^[a-f0-9]{64}$'),
+  normalized         jsonb NOT NULL DEFAULT '{}'::jsonb,
+
+  -- Classe do motivo, nunca a mensagem do provedor nem trecho de XML.
+  reject_reason      text,
+
+  received_at        timestamptz NOT NULL DEFAULT now(),
+  applied_at         timestamptz,
+  applied_event_id   uuid,
+
+  dedupe_key         text NOT NULL,
+
+  CONSTRAINT fiscal_ingestion_inbox_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  FOREIGN KEY (tenant_id, applied_event_id) REFERENCES fiscal_document_event (tenant_id, id),
+
+  -- Um evento sem chave-alvo não teria como ser reconciliado nunca: seria
+  -- guardado para sempre sem chance de sair. O banco recusa em vez de deixar a
+  -- caixa acumular linhas inertes.
+  CONSTRAINT fiscal_ingestion_inbox_event_is_addressable
+    CHECK (state = 'invalid' OR (target_access_key IS NOT NULL AND event_type IS NOT NULL)),
+  -- Aplicado sem o evento resultante seria uma afirmação sem lastro — a mesma
+  -- classe do `full` sem RAW da 0056.
+  CONSTRAINT fiscal_ingestion_inbox_applied_has_event
+    CHECK (state <> 'applied' OR (applied_at IS NOT NULL AND applied_event_id IS NOT NULL)),
+  -- E inválido sem motivo seria um item descartado em silêncio com aparência
+  -- de registro.
+  CONSTRAINT fiscal_ingestion_inbox_invalid_has_reason
+    CHECK (state <> 'invalid' OR reject_reason IS NOT NULL)
+);
+
+-- ═══ A deduplicação é do BANCO ═════════════════════════════════════════════
+--
+-- Por (tenant, cliente, chave de dedupe), sem NULL em coluna nenhuma do índice.
+-- É o que faz o replay do mesmo lote, o retry depois de crash e o evento
+-- reapresentado depois do documento existir convergirem para uma linha só.
+CREATE UNIQUE INDEX IF NOT EXISTS fiscal_ingestion_inbox_dedupe_uq
+  ON fiscal_ingestion_inbox (tenant_id, client_id, dedupe_key);
+
+-- A busca da reconciliação: "quem estava esperando por esta chave?". Parcial
+-- porque só o que está pendente interessa a essa pergunta.
+CREATE INDEX IF NOT EXISTS fiscal_ingestion_inbox_pending_idx
+  ON fiscal_ingestion_inbox (tenant_id, client_id, target_access_key)
+  WHERE state = 'pending_target';
+
+CREATE INDEX IF NOT EXISTS fiscal_ingestion_inbox_age_idx
+  ON fiscal_ingestion_inbox (tenant_id, state, received_at);
+
+ALTER TABLE fiscal_ingestion_inbox ENABLE ROW LEVEL SECURITY;
+ALTER TABLE fiscal_ingestion_inbox FORCE ROW LEVEL SECURITY;
+-- Duas fronteiras, como em `fiscal_document`: tenant sempre, cliente quando o
+-- portal define `app.current_client`.
+CREATE POLICY fiscal_ingestion_inbox_tenant_isolation ON fiscal_ingestion_inbox
+  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
+    )
+  );
+
+COMMENT ON TABLE fiscal_ingestion_inbox IS
+  'Itens de NSU que o modelo canônico ainda não pode representar: evento cujo documento-alvo não chegou, e item ilegível. Existe para que o cursor nunca avance sobre informação não preservada.';
+COMMENT ON COLUMN fiscal_ingestion_inbox.raw IS
+  'Bytes originais do item, na MESMA transação que move o cursor. Externalizá-los abriria a janela entre o PUT no storage e o commit do cursor.';
+COMMENT ON COLUMN fiscal_ingestion_inbox.state IS
+  'pending_target | applied | invalid. Não existe `duplicate`: item repetido não cria linha — chamar de duplicata o evento sem alvo foi o defeito que esta tabela corrige.';
+
+-- ── 2 · Direção deixa de ser adivinhada ────────────────────────────────────
+--
+-- Até aqui o parser da NFS-e devolvia `direction: 'issued'` fixo, com um
+-- comentário dizendo que a ingestão resolveria — e a ingestão não resolvia.
+-- Toda nota capturada nascia "emitida pelo cliente", inclusive as em que ele é
+-- o tomador. Num escritório contábil isso não é um rótulo errado: é a diferença
+-- entre receita e despesa.
+--
+-- A direção passa a sair do CONFRONTO entre o documento do ator consultado e os
+-- participantes declarados no leiaute (emitente, tomador, intermediário). E
+-- quando o confronto não decide, o resultado é `unknown` — explícito, visível
+-- na tela e filtrável — em vez de `issued` por omissão.
+--
+-- `unknown` não é um estado de erro: o ADN distribui ao contribuinte documentos
+-- em que ele figura em qualquer dos três papéis, mas nada impede um leiaute
+-- futuro, ou um documento parcial, de não trazer o participante que decidiria.
+-- Um rótulo honesto de "não deu para dizer" é a única resposta que não mente.
+ALTER TABLE fiscal_document DROP CONSTRAINT IF EXISTS fiscal_document_direction_check;
+ALTER TABLE fiscal_document ADD CONSTRAINT fiscal_document_direction_check
+  CHECK (direction IN ('issued', 'received', 'intermediary', 'unknown'));
+
+COMMENT ON COLUMN fiscal_document.direction IS
+  'issued | received | intermediary | unknown. Resultado do confronto entre o documento do ator consultado e os participantes do leiaute. `unknown` quando o confronto não decide — nunca `issued` por omissão.';
+
+-- ── 3 · A capacidade da nova forma ─────────────────────────────────────────
+--
+-- Chave NOVA, não `contract_version` maior: o registro é lido inteiro e versões
+-- divergentes na mesma tabela o tornam ilegível (`probePlatformCapabilities`).
+-- A regra da 0055 é que o registro só CRESCE, e compatibilidade é continência
+-- de conjunto — mudança incompatível ganha `.v2`.
+--
+-- E ela é incompatível de verdade: um worker que escrevesse pela forma nova num
+-- schema sem esta tabela veria o INSERT falhar, o item ficar não preservado e o
+-- cursor parar. Fail-closed por construção — mas o portão explícito diz o
+-- motivo antes, em vez de deixar o job parar sem explicação.
+INSERT INTO platform_capability (key, label, contract_version, declared_by_migration) VALUES
+  ('office.fiscal-ingestion.v2',
+   'Ingestão fiscal com caixa de entrada de evento pendente, reconciliação e direção classificada',
+   1, '0057')
+ON CONFLICT (key) DO NOTHING;