@baruk/core 0.3.1 → 0.5.0

package/src/db/migrations/0055_job_capability_contract.sql

@@ -0,0 +1,300 @@
+-- 0055 — o contrato de capacidade dos JOBS, e a elegibilidade fiscal default-deny.
+--
+-- ═══ O que a Onda A fechou, e o que ficou aberto ═══════════════════════════
+--
+-- A Onda A fechou o skew de release entre a tela e a API: `GET /v1/capabilities`
+-- declara o que aquele build serve, o console exige o que vai usar, e a
+-- requisição condenada não parte (0054 / docs/architecture/141).
+--
+-- Isso protege a superfície HTTP. Não protege NADA que roda sem navegador.
+--
+-- Os dois crons deste produto (`baruk-collection-cron`, `baruk-billing-cron`)
+-- publicam na Render como serviços SEPARADOS do serviço web, a partir da mesma
+-- imagem mas com deploys independentes — e as migrations rodam no
+-- `preDeployCommand` do serviço WEB, não no cron. A ordem entre "a imagem nova
+-- do cron subiu" e "o schema novo foi aplicado" não é garantida por nada.
+--
+-- Então existem os dois lados da janela:
+--
+--   worker NOVO + schema VELHO → o job depende de coluna/tabela que ainda não
+--     existe. Hoje isso aparece como exceção no meio do loop, DEPOIS de já ter
+--     escrito no tenant anterior — estado parcial, que é exatamente o que a
+--     ingestão fiscal não pode produzir.
+--
+--   worker VELHO + schema NOVO → o job escreve linhas sem o que o schema novo
+--     passou a esperar. Aditivo sobrevive; obrigatório não.
+--
+-- ═══ Por que capacidade, e não SHA — de novo, e por outro motivo ═══════════
+--
+-- Para a tela, a contraparte é a API. Para um worker, a contraparte é o BANCO:
+-- é a única superfície que os dois lados enxergam. Comparar o commit da imagem
+-- do cron com o commit do serviço web acoplaria o job ao processo de release e
+-- reprovaria um hotfix inofensivo.
+--
+-- Por isso o registro vive AQUI, no banco, e quem o escreve é a MIGRATION —
+-- isto é, o mesmo ato que cria a capacidade. Uma capacidade não pode ser
+-- declarada por quem a consome: `baruk_app` recebe apenas SELECT nesta tabela
+-- (ver `db/migrate.ts`). Autoridade escrita pelo controlado não é autoridade,
+-- e um worker que pudesse declarar a própria capacidade teria um portão com a
+-- chave do lado de dentro.
+
+-- ── 1 · Registro de capacidades da PLATAFORMA ──────────────────────────────
+--
+-- Global, sem `tenant_id`: a capacidade é do schema, não do escritório. Sem RLS
+-- pelo mesmo motivo que `fiscal_attribute_definition` — e, como lá, a proteção
+-- é o privilégio, não a policy.
+--
+-- Chave IMUTÁVEL, igual ao contrato HTTP: mudança incompatível ganha `.v2`, e a
+-- `.v1` só sai quando nenhum worker em produção ainda a exigir. É essa regra
+-- que faz `worker velho + schema novo` ser seguro: o registro só CRESCE, e
+-- compatibilidade é continência de conjunto.
+CREATE TABLE IF NOT EXISTS platform_capability (
+  key                   text PRIMARY KEY,
+  label                 text NOT NULL,
+  -- Versão do FORMATO do contrato, não da capacidade. Um worker que não
+  -- reconhece a versão trata tudo como indisponível: fail-closed é a única
+  -- leitura segura de um contrato que não se sabe ler.
+  contract_version      int  NOT NULL,
+  -- Qual migration declarou. Não é decoração: é como se responde "desde qual
+  -- deploy esta capacidade existe?" sem depender de git em tempo de execução.
+  declared_by_migration text NOT NULL,
+  declared_at           timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT platform_capability_key_format
+    CHECK (key ~ '^[a-z0-9]+(-[a-z0-9]+)*(\.[a-z0-9]+(-[a-z0-9]+)*)+\.v[0-9]+$')
+);
+
+COMMENT ON TABLE platform_capability IS
+  'O que ESTE schema sabe fazer. Escrito só por migration (baruk_app tem apenas SELECT): quem consome a capacidade não pode declará-la.';
+
+INSERT INTO platform_capability (key, label, contract_version, declared_by_migration) VALUES
+  ('office.job-contract.v1',
+   'Contrato de capacidade para jobs e workers', 1, '0055'),
+  ('office.collection-cycle.v1',
+   'Ciclo diário de cobrança: geração de recebíveis da competência + régua', 1, '0055'),
+  ('office.saas-billing-cycle.v1',
+   'Ciclo do Billing SaaS: trial, renovação, régua e suspensão', 1, '0055')
+ON CONFLICT (key) DO NOTHING;
+
+-- ── 2 · Cursor do job, por tenant ──────────────────────────────────────────
+--
+-- Existe para que "não consumir cursor irreversivelmente" seja uma propriedade
+-- verificável, e não uma promessa. O cursor só avança quando o lote INTEIRO
+-- termina sob um contrato compatível; run bloqueado não o toca.
+--
+-- `contract_version` grava sob qual contrato aquela posição foi alcançada. Um
+-- worker que leia um cursor gravado sob contrato que ele não reconhece PARA —
+-- em vez de reinterpretar a posição com semântica diferente.
+CREATE TABLE IF NOT EXISTS job_cursor (
+  id               uuid PRIMARY KEY,
+  tenant_id        uuid NOT NULL REFERENCES tenant(id),
+  job_name         text NOT NULL,
+  position         text NOT NULL,
+  contract_version int  NOT NULL,
+  updated_at       timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT job_cursor_tenant_id_uq UNIQUE (tenant_id, id)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS job_cursor_uq ON job_cursor (tenant_id, job_name);
+
+ALTER TABLE job_cursor ENABLE ROW LEVEL SECURITY;
+ALTER TABLE job_cursor FORCE ROW LEVEL SECURITY;
+CREATE POLICY job_cursor_tenant_isolation ON job_cursor
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ── 3 · Trilha de execução do job ──────────────────────────────────────────
+--
+-- Um job bloqueado por incompatibilidade não pode falhar em silêncio. Esta
+-- tabela é o registro nomeado do bloqueio: qual job, qual versão, o que exigia,
+-- o que o schema declarava, e quando.
+--
+-- Sem PII e sem segredo por construção: só nomes de capacidade e contadores.
+CREATE TABLE IF NOT EXISTS job_run (
+  id                     uuid PRIMARY KEY,
+  tenant_id              uuid NOT NULL REFERENCES tenant(id),
+  job_name               text NOT NULL,
+  job_version            int  NOT NULL,
+  -- Os cinco estados. `TEMPORARILY_UNAVAILABLE` é deliberadamente separado de
+  -- `INCOMPATIBLE`: o primeiro volta sozinho e merece retry; o segundo exige um
+  -- deploy, e insistir nele é gastar orçamento contra uma parede.
+  readiness              text NOT NULL CHECK (readiness IN (
+                           'READY', 'TEMPORARILY_UNAVAILABLE', 'INCOMPATIBLE',
+                           'DISABLED', 'BLOCKED_BY_TENANT_CONFIG')),
+  status                 text NOT NULL CHECK (status IN ('completed', 'blocked', 'failed')),
+  contract_version       int,
+  required_capabilities  text[] NOT NULL DEFAULT '{}',
+  observed_capabilities  text[] NOT NULL DEFAULT '{}',
+  missing_capabilities   text[] NOT NULL DEFAULT '{}',
+  mutations              int  NOT NULL DEFAULT 0 CHECK (mutations >= 0),
+  cursor_advanced        boolean NOT NULL DEFAULT false,
+  detail                 text,
+  started_at             timestamptz NOT NULL DEFAULT now(),
+  finished_at            timestamptz,
+  CONSTRAINT job_run_tenant_id_uq UNIQUE (tenant_id, id),
+  -- O fail-closed vira invariante do BANCO, não promessa do TypeScript: é
+  -- impossível registrar um run bloqueado que tenha mutado ou avançado cursor.
+  -- Um refactor futuro que erre a ordem das operações não passa daqui.
+  CONSTRAINT job_run_blocked_is_inert
+    CHECK (status <> 'blocked' OR (mutations = 0 AND cursor_advanced = false)),
+  -- `READY` e bloqueio são mutuamente exclusivos: um run bloqueado tem de dizer
+  -- POR QUE, e 'READY' não é um motivo.
+  CONSTRAINT job_run_blocked_has_reason
+    CHECK (status <> 'blocked' OR readiness <> 'READY')
+);
+
+CREATE INDEX IF NOT EXISTS job_run_tenant_job_idx
+  ON job_run (tenant_id, job_name, started_at DESC);
+
+ALTER TABLE job_run ENABLE ROW LEVEL SECURITY;
+ALTER TABLE job_run FORCE ROW LEVEL SECURITY;
+CREATE POLICY job_run_tenant_isolation ON job_run
+  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 CONSTRAINT job_run_blocked_is_inert ON job_run IS
+  'Fail-closed como invariante de banco: run bloqueado com mutação ou cursor avançado não é gravável.';
+
+-- ═══ 4 · Elegibilidade fiscal — default deny em três camadas ════════════════
+--
+-- O achado que motiva isto: hoje NADA no produto distingue "cliente que existe"
+-- de "cliente que pode entrar em automação fiscal". Um job futuro que
+-- selecionasse por `deleted_at IS NULL` alcançaria, no tenant da SC, dois
+-- cadastros que foram criados em teste — e alcançaria a carteira real inteira
+-- no dia seguinte a uma importação.
+--
+-- É a mesma lição da 0047 (liberação do destinatário), aplicada a documento
+-- fiscal em vez de e-mail: a ausência tem de ser a barreira. Um default "entra
+-- quem ninguém proibiu" transforma omissão em autorização — e omissão é o
+-- estado natural de todo cliente que acabou de entrar.
+--
+-- Três camadas, porque três coisas diferentes podem estar erradas:
+--   tenant  → o ESCRITÓRIO ligou automação fiscal? em qual ambiente?
+--   cliente → ESTE cliente foi inscrito, para ESTE tipo de documento?
+--   credencial → existe insumo para operar em nome dele? verificado?
+--
+-- E uma quarta, que não é tabela: o estado de operação real
+-- (`tenant_pilot_milestone.real_pilot_start`, 0047). Ambiente `production`
+-- exige o marco declarado; `synthetic` não — é o que mantém desenvolvimento e
+-- homologação possíveis sem abrir a porta da carteira real.
+
+-- ── 4.1 · O escritório liga a automação, e declara em qual ambiente ────────
+--
+-- Ausência de linha = `disabled`. Não existe valor que signifique "herda".
+--
+-- `mode` é ambiente E chave ao mesmo tempo, de propósito: separá-los criaria o
+-- estado `enabled=true, environment=null`, que alguém teria de interpretar — e
+-- interpretação é onde documento de homologação vira documento real.
+CREATE TABLE IF NOT EXISTS tenant_fiscal_automation (
+  tenant_id   uuid PRIMARY KEY REFERENCES tenant(id),
+  mode        text NOT NULL DEFAULT 'disabled'
+                CHECK (mode IN ('disabled', 'synthetic', 'production')),
+  enabled_at  timestamptz,
+  enabled_by  uuid REFERENCES "user"(id),
+  note        text,
+  updated_at  timestamptz NOT NULL DEFAULT now(),
+  -- Ligar exige autor e data: "quem ligou isto?" é a única pergunta que a
+  -- linha existe para responder, e ela não pode ficar sem resposta.
+  CONSTRAINT tenant_fiscal_automation_enable_coherent
+    CHECK (mode = 'disabled' OR (enabled_at IS NOT NULL AND enabled_by IS NOT NULL))
+);
+
+ALTER TABLE tenant_fiscal_automation ENABLE ROW LEVEL SECURITY;
+ALTER TABLE tenant_fiscal_automation FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_fiscal_automation_tenant_isolation ON tenant_fiscal_automation
+  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 TABLE tenant_fiscal_automation IS
+  'Ausência de linha = automação fiscal desligada. Nenhuma migration liga escritório nenhum; ligar é ato humano com autor e data.';
+
+-- ── 4.2 · A inscrição do cliente, por tipo de documento ────────────────────
+--
+-- Por TIPO, e não um booleano no cliente: um escritório pode acompanhar a NFS-e
+-- de um cliente sem tocar na NF-e dele, e o inverso. Um booleano forçaria tudo
+-- ou nada, e "tudo" é sempre a escolha errada quando o insumo é documento
+-- fiscal de terceiro.
+--
+-- Revogação é lógica e mantém o histórico: quem esteve inscrito e saiu é um
+-- fato que a trilha precisa preservar.
+CREATE TABLE IF NOT EXISTS client_fiscal_enrollment (
+  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 ('nfe', 'nfse', 'cte', 'nfce')),
+  enrolled_at   timestamptz NOT NULL DEFAULT now(),
+  enrolled_by   uuid REFERENCES "user"(id),
+  revoked_at    timestamptz,
+  revoked_by    uuid REFERENCES "user"(id),
+  note          text,
+  CONSTRAINT client_fiscal_enrollment_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  CONSTRAINT client_fiscal_enrollment_revoke_coherent
+    CHECK ((revoked_at IS NULL) = (revoked_by IS NULL))
+);
+
+-- Uma inscrição VIVA por (cliente, tipo). Revogadas coexistem: são histórico.
+CREATE UNIQUE INDEX IF NOT EXISTS client_fiscal_enrollment_live_uq
+  ON client_fiscal_enrollment (tenant_id, client_id, document_type)
+  WHERE revoked_at IS NULL;
+
+ALTER TABLE client_fiscal_enrollment ENABLE ROW LEVEL SECURITY;
+ALTER TABLE client_fiscal_enrollment FORCE ROW LEVEL SECURITY;
+CREATE POLICY client_fiscal_enrollment_tenant_isolation ON client_fiscal_enrollment
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ── 4.3 · Prontidão da credencial ──────────────────────────────────────────
+--
+-- Esta fase NÃO exige certificado A1. Ela define o conceito e o lugar.
+--
+-- O estado `no_credential` não está no CHECK de propósito: ele é a AUSÊNCIA de
+-- linha, como em `client.communication_cleared_at`. Um enum com `no_credential`
+-- permitiria a linha existir dizendo "não tem" — e daí alguém a criaria por
+-- conveniência, e "não tem" viraria um estado configurável em vez do estado
+-- natural de todo cliente.
+--
+-- `secret_ref` é referência do cofre (`vault://<nome>`), nunca o segredo. O
+-- certificado é do CLIENTE, não do escritório e nem nosso: o que guardamos é
+-- para onde apontar.
+CREATE TABLE IF NOT EXISTS client_fiscal_credential (
+  id          uuid PRIMARY KEY,
+  tenant_id   uuid NOT NULL REFERENCES tenant(id),
+  client_id   uuid NOT NULL,
+  kind        text NOT NULL CHECK (kind IN ('certificate_a1', 'municipal_portal')),
+  status      text NOT NULL
+                CHECK (status IN ('configured_not_verified', 'verified', 'expired', 'revoked')),
+  secret_ref  text,
+  verified_at timestamptz,
+  expires_on  date,
+  updated_at  timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT client_fiscal_credential_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  -- `verified` sem data de verificação é uma afirmação sem prova.
+  CONSTRAINT client_fiscal_credential_verified_coherent
+    CHECK (status <> 'verified' OR verified_at IS NOT NULL),
+  -- Referência do cofre, jamais material. Um `-----BEGIN` aqui é acidente
+  -- grave; o banco recusa antes de virar um vazamento em backup.
+  CONSTRAINT client_fiscal_credential_ref_is_reference
+    CHECK (secret_ref IS NULL OR secret_ref ~ '^vault://[A-Za-z0-9_.:-]+$')
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS client_fiscal_credential_uq
+  ON client_fiscal_credential (tenant_id, client_id, kind);
+
+ALTER TABLE client_fiscal_credential ENABLE ROW LEVEL SECURITY;
+ALTER TABLE client_fiscal_credential FORCE ROW LEVEL SECURITY;
+CREATE POLICY client_fiscal_credential_tenant_isolation ON client_fiscal_credential
+  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 client_fiscal_credential.secret_ref IS
+  'Referência do cofre (vault://…). NUNCA o certificado nem a senha dele — o material é do cliente e não passa por aqui.';
+
+-- ── 5 · Nenhum cliente existente nasce elegível ────────────────────────────
+--
+-- Não há UPDATE, INSERT ou backfill nesta migration que torne alguém elegível.
+-- É a afirmação central do gate e ela é verificável: as três tabelas acima
+-- nascem VAZIAS, e vazio significa negado nas três camadas.
+--
+-- Vale para os 13 registros da SC e para os tenants sintéticos de certificação
+-- pelo mesmo motivo — nenhum deles é mencionado, então nenhum deles é ligado.

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;