@baruk/core 0.4.2 → 0.6.0

package/src/db/migrations/0060_fiscal_credential_vault_and_run_authorization.sql

@@ -0,0 +1,321 @@
+-- 0060 — o cofre fiscal ganha classe de exposição, o certificado ganha
+-- identidade, e a primeira consulta real ganha um portão que se consome.
+--
+-- ═══ O defeito que a primeira seção existe para tornar indizível ══════════
+--
+-- `vault_credential` (0012) guarda todo segredo do escritório sob uma única
+-- regra de leitura: quem tem `vault.credential.decrypt` chama
+-- `POST /v1/vault/credentials/:id/reveal` e recebe o texto em claro. Para uma
+-- chave de API isso é o comportamento desejado — o operador precisa colá-la
+-- noutro sistema.
+--
+-- Para o material de um certificado digital, é a porta dos fundos do cofre. O
+-- envelope que a Fase 2 definiu carrega a CHAVE PRIVADA do cliente em base64;
+-- revelá-lo numa tela é entregá-la, e "não faça isso" não é um controle. Pior:
+-- o papel `accountant` do catálogo já carrega `vault.credential.decrypt`, de
+-- modo que a porta estava aberta para todo contador do escritório.
+--
+-- A correção não é tirar o botão da tela. É dizer no BANCO que existem duas
+-- classes de segredo, e que a segunda não tem caminho de saída:
+--
+--   revealable   pode voltar ao humano que o guardou (chave de API, token).
+--   write_only   entra, é usado pelo processo, e NUNCA volta.
+--
+-- E é uma RESTRIÇÃO, não uma convenção, que amarra `certificate` à segunda: um
+-- certificado gravado por qualquer caminho — rota nova, script, seed — nasce
+-- irrecuperável, inclusive num caminho que ainda não foi escrito.
+
+ALTER TABLE vault_credential ADD COLUMN IF NOT EXISTS exposure text NOT NULL DEFAULT 'revealable';
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT FROM pg_constraint WHERE conname = 'vault_credential_exposure_values') THEN
+    ALTER TABLE vault_credential ADD CONSTRAINT vault_credential_exposure_values
+      CHECK (exposure IN ('revealable', 'write_only'));
+  END IF;
+END $$;
+
+-- Backfill ANTES da restrição de coerência: uma credencial de certificado já
+-- gravada sob a regra antiga tornaria o CHECK inválido, e um `NOT VALID`
+-- silencioso deixaria exatamente as linhas antigas — as que já correram risco —
+-- fora da garantia.
+UPDATE vault_credential SET exposure = 'write_only'
+ WHERE category = 'certificate' AND exposure <> 'write_only';
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT FROM pg_constraint WHERE conname = 'vault_credential_certificate_is_write_only') THEN
+    ALTER TABLE vault_credential ADD CONSTRAINT vault_credential_certificate_is_write_only
+      CHECK (category <> 'certificate' OR exposure = 'write_only');
+  END IF;
+END $$;
+
+COMMENT ON COLUMN vault_credential.exposure IS
+  'write_only = não existe caminho de leitura para humano, por nenhuma rota. Material de certificado é write_only por RESTRIÇÃO, não por disciplina da camada de rota.';
+COMMENT ON CONSTRAINT vault_credential_certificate_is_write_only ON vault_credential IS
+  'Remover esta restrição é a decisão consciente de permitir que a chave privada de um cliente volte para uma tela.';
+
+-- ═══ 2 · A autorização de execução única ═════════════════════════════════
+--
+-- O motor da Fase 2 tem três desligamentos (flag de ambiente, elegibilidade,
+-- cadência) e todos são ESTADO: ligados, ficam ligados. Para a primeira
+-- consulta real contra um ambiente oficial, em nome de um contribuinte que não
+-- pediu nada, estado permanente é a forma errada de autorização — o titular
+-- autorizou UMA leitura, não um regime.
+--
+-- Esta tabela é um portão que se gasta. Quatro propriedades, todas no schema:
+--
+--   `max_runs = 1`          CHECK literal. "Uma execução" não é configuração.
+--   `operation = 'READ_ONLY'` idem. Mutação é INGRAVÁVEL nesta fase.
+--   `expires_at`            uma autorização esquecida morre sozinha.
+--   `runs_consumed`         nunca ultrapassa `max_runs`, e o CHECK é quem diz.
+--
+-- O período vem por EXTENSO — `period_start` e `period_end` além do par
+-- ano/mês. O relato humano que originou esta frente continha exemplos de datas
+-- inconsistentes entre si, e transformar "mês anterior" em regra implícita
+-- produziria uma coleta cuja janela ninguém confirmou. Aqui a janela é dado
+-- gravado, e a tela mostra as duas datas antes de qualquer execução.
+CREATE TABLE IF NOT EXISTS fiscal_run_authorization (
+  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')),
+  environment        text NOT NULL CHECK (environment IN ('synthetic', 'homologation', 'production')),
+  -- Slug da fonte, o mesmo vocabulário que governa cursor, disjuntor e
+  -- prontidão (`fiscal_sync_cursor.source`). Uma autorização emitida para uma
+  -- fonte não vale para outra.
+  source             text NOT NULL,
+  credential_kind    text NOT NULL DEFAULT 'certificate_a1'
+                       CHECK (credential_kind IN ('certificate_a1', 'certificate_a3', 'municipal_portal')),
+
+  operation          text NOT NULL DEFAULT 'READ_ONLY' CHECK (operation IN ('READ_ONLY', 'MUTATING')),
+
+  competence_year    int  NOT NULL CHECK (competence_year BETWEEN 2000 AND 2100),
+  competence_month   int  NOT NULL CHECK (competence_month BETWEEN 1 AND 12),
+  period_start       date NOT NULL,
+  period_end         date NOT NULL,
+
+  max_runs           int  NOT NULL DEFAULT 1,
+  runs_consumed      int  NOT NULL DEFAULT 0,
+
+  authorized_by      uuid NOT NULL REFERENCES "user"(id),
+  authorized_at      timestamptz NOT NULL DEFAULT now(),
+  -- Responsável contábil DECLARADO para esta execução. Texto, e não FK para
+  -- `user`: o profissional responsável pode não ter login no produto, e exigir
+  -- que tivesse forçaria a criação de uma identidade que ninguém pediu.
+  responsible_name   text,
+  expires_at         timestamptz NOT NULL,
+
+  consumed_at        timestamptz,
+  consumed_by_run_id uuid,
+  revoked_at         timestamptz,
+  revoked_by         uuid REFERENCES "user"(id),
+  revoke_reason      text,
+
+  created_at         timestamptz NOT NULL DEFAULT now(),
+  updated_at         timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT fiscal_run_authorization_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+
+  CONSTRAINT fiscal_run_authorization_one_shot CHECK (max_runs = 1),
+  CONSTRAINT fiscal_run_authorization_read_only CHECK (operation = 'READ_ONLY'),
+  CONSTRAINT fiscal_run_authorization_budget CHECK (runs_consumed >= 0 AND runs_consumed <= max_runs),
+  CONSTRAINT fiscal_run_authorization_consumption_coherent
+    CHECK ((consumed_at IS NULL) = (runs_consumed = 0)),
+  CONSTRAINT fiscal_run_authorization_window CHECK (period_end >= period_start),
+  CONSTRAINT fiscal_run_authorization_expiry CHECK (expires_at > authorized_at),
+  CONSTRAINT fiscal_run_authorization_revocation_coherent
+    CHECK ((revoked_at IS NULL) = (revoked_by IS NULL))
+);
+
+COMMENT ON CONSTRAINT fiscal_run_authorization_one_shot ON fiscal_run_authorization IS
+  'Uma execução. Não é configuração: é restrição. Um segundo run real exige uma segunda autorização.';
+COMMENT ON CONSTRAINT fiscal_run_authorization_read_only ON fiscal_run_authorization IS
+  'Mutação em sistema fiscal externo é ingravável nesta fase. Remover esta restrição é a decisão consciente de permitir escrita.';
+
+-- Uma autorização VIVA por (cliente, fonte, ambiente, competência). Sem isto,
+-- emitir duas e consumir as duas devolve na prática o regime permanente que a
+-- tabela existe para impedir.
+CREATE UNIQUE INDEX IF NOT EXISTS fiscal_run_authorization_live_uq
+  ON fiscal_run_authorization (tenant_id, client_id, source, environment,
+                               competence_year, competence_month)
+  WHERE consumed_at IS NULL AND revoked_at IS NULL;
+
+CREATE INDEX IF NOT EXISTS fiscal_run_authorization_client_idx
+  ON fiscal_run_authorization (tenant_id, client_id, authorized_at DESC);
+
+ALTER TABLE fiscal_run_authorization ENABLE ROW LEVEL SECURITY;
+ALTER TABLE fiscal_run_authorization FORCE ROW LEVEL SECURITY;
+CREATE POLICY fiscal_run_authorization_tenant_isolation ON fiscal_run_authorization
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ═══ 3 · A cobrança da PLATAFORMA, separada da cobrança do escritório ═════
+--
+-- Há duas cobranças neste produto e confundi-las custa caro nas duas direções:
+--
+--   plataforma   Baruk → escritório (assinatura do Office). `saas_subscription`.
+--   escritório   escritório → clientes dele (honorários). `receivable`.
+--
+-- O escritório fundador não paga a primeira. A forma ERRADA de implementar isso
+-- é desligar o financeiro dele — que apagaria a segunda, que é o produto
+-- inteiro. A forma errada seguinte é `if (tenant.code === 'sc')`, que faz o
+-- segundo escritório fundador virar um deploy.
+--
+-- Esta tabela é a forma certa: um fato do tenant, com quem concedeu, quando, e
+-- por quê. O motor de billing lê a linha; ele não conhece nenhum código de
+-- escritório.
+--
+-- ═══ Quem escreve não é quem é cobrado ═══════════════════════════════════
+--
+-- Um controle escrito pelo controlado não é controle. Se o tenant pudesse
+-- gravar a própria isenção, todo escritório seria fundador na primeira tarde.
+-- As políticas abaixo são POR COMANDO: o tenant LÊ a própria linha; só o
+-- operador da plataforma (a GUC `app.platform_operator`, que apenas as rotas de
+-- backoffice setam) INSERE, ATUALIZA ou APAGA.
+CREATE TABLE IF NOT EXISTS tenant_platform_billing (
+  tenant_id        uuid PRIMARY KEY REFERENCES tenant(id),
+  billing_mode     text NOT NULL DEFAULT 'standard' CHECK (billing_mode IN ('standard', 'exempt')),
+  exemption_reason text CHECK (exemption_reason IS NULL OR
+                               exemption_reason IN ('founding_tenant', 'internal', 'partner')),
+  founding_tenant  boolean NOT NULL DEFAULT false,
+  granted_by       uuid REFERENCES "user"(id),
+  granted_at       timestamptz,
+  -- Isenção com prazo é possível; a do fundador não tem, e `NULL` diz isso.
+  expires_on       date,
+  notes            text,
+  created_at       timestamptz NOT NULL DEFAULT now(),
+  updated_at       timestamptz NOT NULL DEFAULT now(),
+
+  -- Isentar custa motivo e data. `standard` é o estado gratuito — e o correto
+  -- para todo tenant sobre o qual ninguém decidiu nada.
+  CONSTRAINT tenant_platform_billing_exemption_needs_reason
+    CHECK (billing_mode = 'standard' OR (exemption_reason IS NOT NULL AND granted_at IS NOT NULL))
+);
+
+COMMENT ON TABLE tenant_platform_billing IS
+  'Cobrança da PLATAFORMA (Baruk → escritório). Não governa a cobrança do escritório aos clientes dele, que é outro domínio e continua ativa.';
+COMMENT ON CONSTRAINT tenant_platform_billing_exemption_needs_reason ON tenant_platform_billing IS
+  'Isentar exige motivo e data. Ausência de linha significa cobrança padrão, nunca isenção por omissão.';
+
+ALTER TABLE tenant_platform_billing ENABLE ROW LEVEL SECURITY;
+ALTER TABLE tenant_platform_billing FORCE ROW LEVEL SECURITY;
+
+-- Leitura: o próprio tenant, ou o operador.
+CREATE POLICY tenant_platform_billing_read ON tenant_platform_billing
+  FOR SELECT
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid
+         OR current_setting('app.platform_operator', true) = 'true');
+
+-- Escrita: SÓ o operador. Uma política por comando — `WITH CHECK` não governa
+-- DELETE, e uma política única deixaria o apagamento da própria isenção (ou da
+-- de outro) fora de qualquer regra.
+CREATE POLICY tenant_platform_billing_insert ON tenant_platform_billing
+  FOR INSERT WITH CHECK (current_setting('app.platform_operator', true) = 'true');
+CREATE POLICY tenant_platform_billing_update ON tenant_platform_billing
+  FOR UPDATE
+  USING (current_setting('app.platform_operator', true) = 'true')
+  WITH CHECK (current_setting('app.platform_operator', true) = 'true');
+CREATE POLICY tenant_platform_billing_delete ON tenant_platform_billing
+  FOR DELETE USING (current_setting('app.platform_operator', true) = 'true');
+
+-- ═══ 4 · O registry municipal deixa de responder só "não sabemos" ════════
+--
+-- `fiscal_coverage` (0058) já traz status, método, credencial exigida, fallback,
+-- fonte e data. Faltavam duas respostas que a política API-first exige ANTES de
+-- alguém cogitar automação de navegador:
+--
+--   `official_api_available`  existe caminho estruturado oficial?
+--   `supported_operations`    o que ele faz — listar, baixar, consultar evento?
+--
+-- Sem a primeira, "não achei API" e "não procurei" são o mesmo registro, e o
+-- segundo é o que costuma virar um Playwright logando num portal de prefeitura.
+ALTER TABLE fiscal_coverage ADD COLUMN IF NOT EXISTS official_api_available text NOT NULL DEFAULT 'unknown';
+ALTER TABLE fiscal_coverage ADD COLUMN IF NOT EXISTS supported_operations text[] NOT NULL DEFAULT '{}';
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT FROM pg_constraint WHERE conname = 'fiscal_coverage_official_api_values') THEN
+    ALTER TABLE fiscal_coverage ADD CONSTRAINT fiscal_coverage_official_api_values
+      CHECK (official_api_available IN ('yes', 'no', 'unknown'));
+  END IF;
+END $$;
+
+COMMENT ON COLUMN fiscal_coverage.official_api_available IS
+  '"no" é uma medição; "unknown" é a ausência dela. Só a primeira autoriza sequer discutir fallback por navegador.';
+
+-- ═══ Backfill: as linhas que já afirmavam cobertura ══════════════════════
+--
+-- A 0058 criou quatro linhas `SUPPORTED_OFFICIAL` — NF-e, CT-e e NFS-e nacional
+-- —, todas com a norma citada em `source_reference`. Com a coluna nova nascendo
+-- `unknown`, elas passariam a AFIRMAR cobertura sem ter respondido "existe
+-- caminho oficial?", que é justamente a pergunta que a coluna existe para fazer.
+--
+-- Uma coluna nova sem backfill deixa de fora exatamente as linhas antigas — as
+-- que já estavam em uso. O mesmo raciocínio do `exposure` acima.
+UPDATE fiscal_coverage SET
+  official_api_available = 'yes',
+  supported_operations = CASE
+    WHEN automation_method = 'dfe_nsu_soap' THEN ARRAY['dist_nsu', 'cons_nsu', 'cons_chave']
+    WHEN automation_method = 'dfe_nsu_rest' THEN ARRAY['list_by_nsu', 'fetch_document', 'fetch_events']
+    ELSE supported_operations
+  END
+WHERE coverage_status LIKE 'SUPPORTED%'
+  AND official_api_available = 'unknown'
+  AND automation_method IN ('dfe_nsu_soap', 'dfe_nsu_rest');
+
+-- As linhas dos três municípios do piloto. `SUPPORTED_OFFICIAL` aqui significa
+-- o que já significava na linha nacional do ADN: existe caminho oficial
+-- documentado — e não "já funcionou". Quem responde "já funcionou" é
+-- `digital_certificate.verified_at` somado a um `fiscal_sync_run` completo, e
+-- ambos continuam vazios.
+INSERT INTO fiscal_coverage (
+  id, document_type, jurisdiction_scope, jurisdiction_code, provider, coverage_status,
+  automation_method, credential_requirement, environments, fallback_type,
+  official_api_available, supported_operations,
+  last_verified_at, source_reference, notes
+) VALUES
+  (gen_random_uuid(), 'nfse', 'municipal', '5208707', 'nfse_adn', 'SUPPORTED_OFFICIAL',
+   'dfe_nsu_rest', 'icp_brasil_mtls', ARRAY['homologation', 'production'], 'manual_upload',
+   'yes', ARRAY['list_by_nsu', 'fetch_document', 'fetch_events'],
+   DATE '2026-09-08',
+   'Prefeitura de Goiânia — comunicado oficial de ajuste da NFS-e à Reforma Tributária (vigência 01/01/2026); LC 214/2025 art. 62; Manual dos Contribuintes — APIs do ADN v1.0',
+   'Goiânia MANTÉM emissor próprio (Sistema ISS Goiânia, provedor ISSNet) e o compartilhamento com o ADN é feito pela própria administração tributária. Logo o caminho de COLETA é o ADN nacional, por certificado — não o portal municipal. Nenhuma chamada autenticada foi feita a partir deste produto.'),
+
+  (gen_random_uuid(), 'nfse', 'municipal', '5201405', 'nfse_adn', 'SUPPORTED_OFFICIAL',
+   'dfe_nsu_rest', 'icp_brasil_mtls', ARRAY['homologation', 'production'], 'manual_upload',
+   'yes', ARRAY['list_by_nsu', 'fetch_document', 'fetch_events'],
+   DATE '2026-09-08',
+   'Portal oficial da Prefeitura de Aparecida de Goiânia (sistema NFS-e em issnetonline.com.br/aparecida); LC 214/2025 art. 62; Manual dos Contribuintes — APIs do ADN v1.0',
+   'Emissor municipal é ISSNet (mesmo provedor de Goiânia e Anápolis). Nenhuma API pública do ISSNet foi verificada; a via oficial de coleta é o ADN. Adesão específica do município ao compartilhamento NÃO foi confirmada em fonte municipal — apenas pela obrigação legal geral.'),
+
+  (gen_random_uuid(), 'nfse', 'municipal', '5201108', 'nfse_adn', 'SUPPORTED_OFFICIAL',
+   'dfe_nsu_rest', 'icp_brasil_mtls', ARRAY['homologation', 'production'], 'manual_upload',
+   'yes', ARRAY['list_by_nsu', 'fetch_document', 'fetch_events'],
+   DATE '2026-09-08',
+   'Prefeitura de Anápolis — Decreto nº 52.525 (03/03/2026, efeitos retroativos a 01/01/2026); LC 214/2025 art. 62; Manual dos Contribuintes — APIs do ADN v1.0',
+   'Anápolis mantém emissor municipal próprio (ISS.NET) com webservice local; o comunicado NÃO menciona o ADN. Simples Nacional migra ao emissor nacional a partir de 01/11/2026. A coleta pelo ADN depende do compartilhamento obrigatório, que este produto não verificou.'),
+
+  -- Estadual GO. A pergunta humana era "notas de entrada e saída"; a resposta
+  -- oficial separa as duas, e é essa separação que decide se um conector novo é
+  -- necessário — ou se o que falta não tem conector nenhum.
+  (gen_random_uuid(), 'nfe', 'state', 'GO', 'sefaz_dfe', 'SUPPORTED_OFFICIAL',
+   'dfe_nsu_soap', 'icp_brasil_mtls', ARRAY['homologation', 'production'], 'issuer_export',
+   'yes', ARRAY['dist_nsu', 'cons_nsu', 'cons_chave'],
+   DATE '2026-09-08',
+   'Secretaria da Economia de Goiás — Documentos Fiscais (nfeweb.sefaz.go.gov.br, arquivo XML por certificado digital); NT 2014.002 v1.02c',
+   'ENTRADAS: cobertas pela distribuição nacional NFeDistribuicaoDFe, autenticada por certificado ICP-Brasil — nenhuma credencial humana. SAÍDAS: o DF-e não distribui o que a própria empresa emitiu; a origem é o emissor do cliente. O login CPF/senha do portal da SEFAZ-GO NÃO é caminho de coleta estruturada e por isso não é modelado como credencial deste produto.')
+ON CONFLICT DO NOTHING;
+
+-- ═══ 5 · A capacidade ════════════════════════════════════════════════════
+--
+-- Chave NOVA, e não bump de `contract_version` — a versão do contrato é global
+-- (0055) e subi-la para exigir schema novo obrigaria todo worker a reconhecer a
+-- versão maior, inclusive os que nada têm a ver com cofre fiscal.
+INSERT INTO platform_capability (key, label, contract_version, declared_by_migration) VALUES
+  ('office.fiscal-credential-vault.v1',
+   'Cofre fiscal: certificado write-only, identidade conferida e autorização de execução única',
+   1, '0060')
+ON CONFLICT (key) DO NOTHING;

package/src/db/migrations/0061_client_official_registry_provenance.sql

@@ -0,0 +1,193 @@
+-- 0061 — de onde veio cada dado cadastral, e quem mandou nele.
+--
+-- ═══ O defeito que a proveniência existe para tornar indizível ═════════════
+--
+-- Sem ela, um cadastro pré-preenchido por fonte oficial e um cadastro digitado
+-- à mão são a MESMA linha. E aí duas coisas ficam impossíveis:
+--
+--   1. atualizar sem destruir. Uma segunda consulta traria o valor oficial, e
+--      sobrescrever apagaria a correção que uma pessoa fez de propósito — o
+--      telefone que o escritório sabe estar certo, o e-mail que mudou e a
+--      Receita ainda não sabe.
+--   2. explicar. "Por que o município deste cliente é Goiânia?" tem respostas
+--      diferentes conforme alguém tenha digitado ou a Receita tenha dito, e a
+--      diferença decide quanto se confia no dado.
+--
+-- A tabela guarda o retrato OFICIAL, ao lado do cadastro — nunca por cima dele.
+-- O cadastro continua sendo o que o escritório afirma; esta linha é o que a
+-- fonte disse, quando disse, e por qual provedor.
+--
+-- ═══ Por que uma tabela, e não colunas em `client` ════════════════════════
+--
+-- Colunas `*_source` em `client` dobrariam a largura da tabela e ainda assim não
+-- guardariam o valor oficial DIVERGENTE — só a etiqueta. É justamente o valor
+-- divergente que a tela de conferência precisa mostrar lado a lado.
+
+CREATE TABLE IF NOT EXISTS client_registry_snapshot (
+  id                    uuid PRIMARY KEY,
+  tenant_id             uuid NOT NULL REFERENCES tenant(id),
+  client_id             uuid NOT NULL,
+
+  -- Quem respondeu, e se é fonte oficial. `official = false` NÃO é proibido —
+  -- é o que permite registrar um provedor de teste sem que ele se disfarce de
+  -- Receita Federal na trilha.
+  provider              text NOT NULL,
+  provider_official     boolean NOT NULL DEFAULT false,
+  fetched_at            timestamptz NOT NULL DEFAULT now(),
+
+  -- O documento consultado, em dígitos. Guardado aqui porque o `client` pode ser
+  -- corrigido depois, e o retrato tem de dizer sobre QUAL número ele fala.
+  document_digits       text NOT NULL CHECK (document_digits ~ '^[0-9]{14}$'),
+
+  -- O retrato normalizado. Todo campo é opcional: toda fonte tem lacuna, e uma
+  -- lacuna precisa ser dizível como ausência — não como string vazia.
+  legal_name            text,
+  trade_name            text,
+  registration_status   text,
+  opened_on             date,
+  legal_nature          text,
+  company_size          text,
+  primary_activity_code text,
+  primary_activity_text text,
+  secondary_activities  jsonb NOT NULL DEFAULT '[]'::jsonb,
+  street                text,
+  street_number         text,
+  complement            text,
+  district              text,
+  postal_code           text,
+  municipality          text,
+  state_uf              text,
+  phone                 text,
+  email                 text,
+  share_capital_cents   bigint,
+
+  -- ═══ O silêncio da fonte NÃO é "não" ════════════════════════════════════
+  -- `NULL` aqui significa "a fonte não informou", e é diferente de `false`.
+  -- Colapsar os dois é como um optante do Simples vira Lucro Presumido por
+  -- omissão — e o regime decide quais obrigações o motor aplica.
+  simples_optant        boolean,
+  mei_optant            boolean,
+
+  created_at            timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT client_registry_snapshot_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id)
+);
+
+COMMENT ON COLUMN client_registry_snapshot.simples_optant IS
+  'NULL = a fonte não informou. NÃO é false. O regime tributário depende disso, e silêncio não é negativa.';
+
+-- Um retrato por (cliente, provedor, momento). O índice serve à pergunta real:
+-- "qual foi o último retrato deste cliente?".
+CREATE INDEX IF NOT EXISTS client_registry_snapshot_latest_idx
+  ON client_registry_snapshot (tenant_id, client_id, fetched_at DESC);
+
+ALTER TABLE client_registry_snapshot ENABLE ROW LEVEL SECURITY;
+ALTER TABLE client_registry_snapshot FORCE ROW LEVEL SECURITY;
+CREATE POLICY client_registry_snapshot_tenant_isolation ON client_registry_snapshot
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ═══ A etiqueta por ATRIBUTO ══════════════════════════════════════════════
+--
+-- O retrato acima diz o que a fonte falou. Esta tabela diz o que aconteceu com
+-- cada campo DO CADASTRO: veio da fonte, ou uma pessoa o escreveu?
+--
+-- É ela que faz `HUMAN_OVERRIDE_PRESERVED` ser verificável: um campo marcado
+-- `human` nunca é sobrescrito por atualização automática, e isso é uma consulta
+-- — não uma convenção que alguém precisa lembrar.
+CREATE TABLE IF NOT EXISTS client_field_provenance (
+  id           uuid PRIMARY KEY,
+  tenant_id    uuid NOT NULL REFERENCES tenant(id),
+  client_id    uuid NOT NULL,
+  field        text NOT NULL,
+  origin       text NOT NULL CHECK (origin IN ('official_lookup', 'human', 'import')),
+  provider     text,
+  verified_at  timestamptz,
+  updated_at   timestamptz NOT NULL DEFAULT now(),
+  updated_by   uuid REFERENCES "user"(id),
+
+  CONSTRAINT client_field_provenance_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  -- Origem oficial sem provedor é afirmação sem autor.
+  CONSTRAINT client_field_provenance_official_needs_provider
+    CHECK (origin <> 'official_lookup' OR (provider IS NOT NULL AND verified_at IS NOT NULL))
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS client_field_provenance_uq
+  ON client_field_provenance (tenant_id, client_id, field);
+
+ALTER TABLE client_field_provenance ENABLE ROW LEVEL SECURITY;
+ALTER TABLE client_field_provenance FORCE ROW LEVEL SECURITY;
+CREATE POLICY client_field_provenance_tenant_isolation ON client_field_provenance
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ═══ O nome fantasia ══════════════════════════════════════════════════════
+--
+-- `client` guarda `display_name` e `legal_name`, e não tinha onde pôr o nome
+-- fantasia — que é o que a fonte oficial devolve e o que a equipe usa para
+-- falar do cliente ("HIPER FESTA", não "OLIVEIRA PRODUTOS PARA FESTAS LTDA").
+ALTER TABLE client ADD COLUMN IF NOT EXISTS trade_name text;
+
+COMMENT ON COLUMN client.trade_name IS
+  'Nome fantasia. Distinto de display_name (como o escritório chama) e de legal_name (razão social).';
+
+INSERT INTO platform_capability (key, label, contract_version, declared_by_migration) VALUES
+  ('office.client-registry-provenance.v1',
+   'Retrato de fonte oficial e proveniência por atributo do cadastro do cliente',
+   1, '0061')
+ON CONFLICT (key) DO NOTHING;
+
+-- ═══ A consulta em si — cota, cache e trilha na MESMA linha ═══════════════
+--
+-- Esta tabela existe por três perguntas que não têm outra fonte:
+--
+--   1. **quantas consultas este escritório já fez na janela?** Sem contagem
+--      persistente, um contador em memória zera a cada redeploy e some quando
+--      há duas instâncias — que é exatamente quando o limite importa.
+--   2. **já perguntamos este CNPJ há pouco?** Uma segunda consulta idêntica em
+--      cinco minutos gasta cota de um contrato pago para reobter o que já se
+--      sabe. O `payload` é o cache; o TTL vive no código.
+--   3. **quem perguntou por qual empresa?** Consulta de CNPJ é rastreável por
+--      dever próprio: é a pergunta "esse escritório andou varrendo documentos?".
+--
+-- **Sem FK para `client`, e é de propósito.** A consulta acontece ANTES de o
+-- cliente existir — o operador digita o CNPJ numa tela de cadastro vazia. Uma FK
+-- aqui tornaria impossível registrar justamente a consulta mais comum.
+CREATE TABLE IF NOT EXISTS client_registry_lookup (
+  id              uuid PRIMARY KEY,
+  tenant_id       uuid NOT NULL REFERENCES tenant(id),
+  document_digits text NOT NULL CHECK (document_digits ~ '^[0-9]{14}$'),
+  provider        text NOT NULL,
+  outcome         text NOT NULL CHECK (outcome IN ('ok', 'failed')),
+  -- O motivo da recusa, quando houve. Vocabulário fechado no código
+  -- (`CompanyLookupFailure`); aqui fica aberto para não travar a migration num
+  -- vocabulário que ainda vai crescer com o primeiro provedor real.
+  failure_reason  text,
+  -- O retrato devolvido, quando houve. É o cache: uma repetição dentro do TTL
+  -- é respondida daqui sem tocar a rede. NULL em toda linha `failed` — falha
+  -- não se cacheia, senão uma indisponibilidade de um minuto ficaria colada
+  -- no CNPJ pelo resto do TTL.
+  payload         jsonb,
+  requested_by    uuid REFERENCES "user"(id),
+  created_at      timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT client_registry_lookup_tenant_id_uq UNIQUE (tenant_id, id),
+  CONSTRAINT client_registry_lookup_failure_has_no_payload
+    CHECK (outcome = 'ok' OR payload IS NULL)
+);
+
+-- A cota pergunta "quantas linhas deste tenant desde X"; o cache pergunta
+-- "qual a última linha `ok` deste documento". Um índice serve às duas.
+CREATE INDEX IF NOT EXISTS client_registry_lookup_quota_idx
+  ON client_registry_lookup (tenant_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS client_registry_lookup_cache_idx
+  ON client_registry_lookup (tenant_id, document_digits, created_at DESC)
+  WHERE outcome = 'ok';
+
+ALTER TABLE client_registry_lookup ENABLE ROW LEVEL SECURITY;
+ALTER TABLE client_registry_lookup FORCE ROW LEVEL SECURITY;
+CREATE POLICY client_registry_lookup_tenant_isolation ON client_registry_lookup
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);

package/src/db/migrations/0062_first_contact_and_capability_truth.sql

@@ -0,0 +1,119 @@
+-- 0062 — o primeiro contato, e a diferença entre "existe" e "nós fizemos".
+--
+-- ═══ Dois defeitos, e por que eles são o mesmo defeito ════════════════════
+--
+-- **1. O impasse.** A execução exigia `verified_at`; `verified_at` significa "o
+-- ambiente oficial já aceitou"; e só uma execução produz esse aceite. A primeira
+-- consulta real era inalcançável por construção — não por configuração, não por
+-- falta de certificado. A auditoria da C2 encontrou o ciclo fechado.
+--
+-- **2. A cobertura mentindo por omissão.** `coverage_status = 'SUPPORTED_OFFICIAL'`
+-- responde "a norma oferece um caminho oficial?". A tela mostrava isso ao lado do
+-- botão de autorizar, e o operador lia "o Baruk já fala com esse serviço". Para
+-- `sefaz_dfe` isso era falso: não existe adaptador, só a string do conector.
+--
+-- Os dois são a mesma confusão — **tratar o que o mundo oferece como o que este
+-- produto construiu**. A correção é a mesma nos dois: separar os fatos em
+-- colunas próprias e obrigar cada portão a citar a sua.
+
+-- ═══ 1 · A verdade da capacidade, por camada ══════════════════════════════
+--
+-- `official_api_available` já respondia "existe API oficial?". Faltavam as duas
+-- perguntas seguintes, e é a ausência delas que produzia a leitura errada.
+ALTER TABLE fiscal_coverage
+  ADD COLUMN IF NOT EXISTS connector_implemented boolean NOT NULL DEFAULT false;
+ALTER TABLE fiscal_coverage
+  ADD COLUMN IF NOT EXISTS protocol_verified boolean NOT NULL DEFAULT false;
+
+COMMENT ON COLUMN fiscal_coverage.official_api_available IS
+  'A NORMA oferece um caminho oficial? Fato do mundo, independente deste produto.';
+COMMENT ON COLUMN fiscal_coverage.connector_implemented IS
+  'ESTE produto tem adaptador para o caminho? Fato do repositório. `sefaz_dfe` era SUPPORTED_OFFICIAL sem uma linha de adaptador — foi o que esta coluna passou a tornar dizível.';
+COMMENT ON COLUMN fiscal_coverage.protocol_verified IS
+  'O envelope/contrato do serviço foi conferido contra o serviço REAL? Ler documentação não conta; para o ADN, os nomes dos campos do envelope não estão publicados em lugar acessível.';
+
+-- Backfill explícito, e não default silencioso.
+--
+-- `DEFAULT false` deixaria toda linha existente afirmando "não implementado", o
+-- que por acaso está certo para `sefaz_dfe` e errado para `nfse_adn`. Um acerto
+-- por acaso é o que some no primeiro conector novo.
+UPDATE fiscal_coverage SET connector_implemented = true
+ WHERE provider = 'nfse_adn';
+UPDATE fiscal_coverage SET connector_implemented = false
+ WHERE provider = 'sefaz_dfe';
+-- Nenhum conector tem o protocolo conferido contra o serviço real hoje. O do
+-- ADN depende de um Swagger servido pelo próprio host que exige mTLS.
+UPDATE fiscal_coverage SET protocol_verified = false;
+
+-- ═══ 2 · A autorização passa a apontar para UM certificado ════════════════
+--
+-- Sem isto, trocar o certificado depois de autorizar mantinha a autorização de
+-- pé — e a execução aconteceria com material que ninguém aprovou. O caso não é
+-- teórico: substituir certificado é a operação normal quando um vence.
+ALTER TABLE fiscal_run_authorization
+  ADD COLUMN IF NOT EXISTS credential_fingerprint text;
+
+COMMENT ON COLUMN fiscal_run_authorization.credential_fingerprint IS
+  'sha256 do DER do certificado vigente quando a autorização foi emitida. O executor recusa quando o certificado atual difere: autorizar é aprovar UM material, não uma intenção.';
+
+-- ═══ 3 · O primeiro contato é um ATO, e ele tem registro próprio ══════════
+--
+-- Por que uma coluna e não um tipo de autorização separado: a autorização já é
+-- one-shot, read-only, escopada e expirável. O primeiro contato não precisa de
+-- outra tabela — precisa de uma DECLARAÇÃO de que quem autorizou sabia que a
+-- credencial ainda não fora aceita por ninguém.
+--
+-- `false` como padrão importa: uma autorização comum continua exigindo
+-- credencial verificada. Só quem marca este campo aceita o risco do bootstrap.
+ALTER TABLE fiscal_run_authorization
+  ADD COLUMN IF NOT EXISTS first_contact boolean NOT NULL DEFAULT false;
+
+COMMENT ON COLUMN fiscal_run_authorization.first_contact IS
+  'Autorização de PRIMEIRO CONTATO: aceita credencial válida localmente e ainda não aceita por nenhum ambiente oficial. É o único caminho que resolve o impasse do verified_at, e nenhum agendador pode emiti-la.';
+
+-- Quem executou, e por qual porta.
+--
+-- `manual` é o único valor que o primeiro contato admite, e o CHECK abaixo é
+-- quem garante isso — não um `if` em TypeScript que alguém remove.
+ALTER TABLE fiscal_run_authorization
+  ADD COLUMN IF NOT EXISTS trigger_kind text NOT NULL DEFAULT 'manual';
+
+ALTER TABLE fiscal_run_authorization
+  DROP CONSTRAINT IF EXISTS fiscal_run_authorization_trigger_kind_check;
+ALTER TABLE fiscal_run_authorization
+  ADD CONSTRAINT fiscal_run_authorization_trigger_kind_check
+  CHECK (trigger_kind IN ('manual', 'scheduled'));
+
+-- ═══ O CHECK que impede o agendador de fazer o bootstrap ══════════════════
+--
+-- Está no banco, e não no orquestrador, porque a regra tem de sobreviver a um
+-- refactor do orquestrador. Um cron que tentasse emitir autorização de primeiro
+-- contato viola a linha abaixo e a transação morre.
+ALTER TABLE fiscal_run_authorization
+  DROP CONSTRAINT IF EXISTS fiscal_run_authorization_first_contact_is_manual;
+ALTER TABLE fiscal_run_authorization
+  ADD CONSTRAINT fiscal_run_authorization_first_contact_is_manual
+  CHECK (first_contact = false OR trigger_kind = 'manual');
+
+COMMENT ON CONSTRAINT fiscal_run_authorization_first_contact_is_manual ON fiscal_run_authorization IS
+  'Primeiro contato é ato de gente. Um agendador que o tentasse estaria decidindo, sozinho, gastar o certificado de um terceiro contra a Receita pela primeira vez.';
+
+-- ═══ 4 · A habilitação fiscal do tenant, com granularidade ════════════════
+--
+-- `tenant_fiscal_automation` já existe (0058) e responde por MODO — qual
+-- ambiente o escritório declarou operar. Ela continua sendo a chave-geral.
+--
+-- O que faltava era o outro lado do par: a matrícula POR CLIENTE já existia em
+-- `client_fiscal_enrollment` (0058), também por `document_type`. Nada disso
+-- precisa de tabela nova — precisa de superfície e de auditoria, que vêm no
+-- código desta mesma frente.
+--
+-- Registrado aqui para quem ler a migration procurando as tabelas e não as
+-- encontrar: elas existem desde a 0058, e esta frente as LIGA, não as cria.
+
+-- ═══ 5 · A capacidade ═════════════════════════════════════════════════════
+INSERT INTO platform_capability (key, label, contract_version, declared_by_migration) VALUES
+  ('office.fiscal-first-contact.v1',
+   'Primeiro contato fiscal: autorização one-shot que aceita credencial válida só localmente',
+   1, '0062')
+ON CONFLICT (key) DO NOTHING;