@baruk/core 0.4.2 → 0.6.0

package/src/db/migrations/0051_seed_rules_from_catalog.sql

@@ -0,0 +1,72 @@
+-- 0051 — os 17 seeds viram regras, SEM ganhar precisão que não têm.
+--
+-- ═══ O risco que esta migration precisa não correr ═════════════════════════
+--
+-- É tentador aproveitar a estrutura nova para "melhorar" o seed: dar UF ao ISS,
+-- marcar as federais como validadas, escrever condição de folha nos itens
+-- trabalhistas. Cada uma dessas seria legislação inventada por quem não tem
+-- competência para inventá-la — e escrita num lugar em que passaria a parecer
+-- fonte.
+--
+-- Então esta migration converte o que existe, e **nada mais**:
+--
+--   • toda regra nasce `pending_validation`. Nenhuma vira `validated`: ninguém
+--     conferiu nada ainda, e o CHECK do banco exige autor para validar;
+--   • toda condição nasce `{"op":"always"}` — a aplicabilidade que o seed de
+--     fato tem hoje é por regime, e o regime já é filtrado por
+--     `applies_to_regime` no tipo de item. Não invento condição de folha;
+--   • os dois itens de esfera local viram `not_configured`, porque **não se
+--     sabe de qual UF nem de qual município eles são**. Dar-lhes uma
+--     jurisdição seria escolher um estado por conta própria.
+--
+-- `valid_from` é a data desta migration: é honesto dizer "esta regra existe no
+-- sistema desde hoje", e desonesto dizer que ela vale desde sempre.
+
+DO $$
+DECLARE
+  r record;
+  hoje date := CURRENT_DATE;
+BEGIN
+  FOR r IN
+    SELECT id, key, sphere, due_rule, note
+      FROM recurring_item_type
+     WHERE tenant_id IS NULL AND deleted_at IS NULL
+  LOOP
+    -- Idempotente: reexecutar não duplica.
+    IF EXISTS (SELECT 1 FROM fiscal_rule WHERE item_type_id = r.id AND tenant_id IS NULL) THEN
+      CONTINUE;
+    END IF;
+
+    IF r.sphere IN ('estadual', 'municipal') THEN
+      -- Marcador honesto: o item existe, a regra não. Sem UF, sem município e
+      -- sem vencimento — o motor devolve RULE_NOT_CONFIGURED e ninguém gera
+      -- obrigação local por engano.
+      --
+      -- Fica como `federal` no campo de escopo apenas porque o CHECK exige
+      -- jurisdição completa para state/municipal, e completá-la seria inventar.
+      -- O `status` é quem carrega a verdade: não configurada.
+      INSERT INTO fiscal_rule (
+        id, tenant_id, item_type_id, jurisdiction_scope, version, valid_from,
+        status, conditions, due_rule, note
+      ) VALUES (
+        gen_random_uuid(), NULL, r.id, 'federal', 1, hoje,
+        'not_configured', '{"op":"always"}'::jsonb, NULL,
+        coalesce(r.note || ' ', '') ||
+        '[N1] Item de esfera ' || r.sphere || ' sem jurisdição definida. ' ||
+        'Cadastre uma regra por UF (ou por município) antes de gerar.'
+      );
+    ELSE
+      INSERT INTO fiscal_rule (
+        id, tenant_id, item_type_id, jurisdiction_scope, version, valid_from,
+        status, conditions, due_rule, note
+      ) VALUES (
+        gen_random_uuid(), NULL, r.id, 'federal', 1, hoje,
+        'pending_validation', '{"op":"always"}'::jsonb, r.due_rule,
+        coalesce(r.note, '')
+      );
+    END IF;
+  END LOOP;
+END $$;
+
+COMMENT ON TABLE fiscal_rule IS
+  'Regra fiscal versionada por jurisdição. As 17 primeiras vieram do seed inicial e nascem PENDING_VALIDATION ou NOT_CONFIGURED — nenhuma foi conferida por pessoa, e nenhuma ganhou jurisdição ou prazo que o seed não tinha.';

package/src/db/migrations/0052_fiscal_rule_delete_scope.sql

@@ -0,0 +1,57 @@
+-- 0052 — fechar o DELETE da regra fiscal GLOBAL.
+--
+-- ═══ O defeito, encontrado pelo teste antes do deploy ══════════════════════
+--
+-- A 0049 criou uma política única para `fiscal_rule`:
+--
+--   USING      (tenant_id IS NULL OR tenant_id = current_tenant)
+--   WITH CHECK (tenant_id = current_tenant)
+--
+-- Esse par fecha INSERT e UPDATE — e **não fecha DELETE**. `WITH CHECK` só
+-- governa a linha que passa a existir; quem decide o que um DELETE alcança é o
+-- `USING`. Com o ramo `IS NULL` ali, qualquer escritório apagava regra fiscal
+-- nacional: as regras de todos os outros escritórios do país.
+--
+-- É a mesma forma do P0-A da Fase 4 — o ramo `IS NULL` no lugar errado — com
+-- um agravante: lá a barreira de privilégio segurava, porque `role` teve
+-- INSERT/UPDATE/DELETE revogados do runtime. Aqui não dá para revogar: o
+-- escritório precisa escrever as PRÓPRIAS regras. A separação tem de vir da
+-- política.
+--
+-- ═══ A correção ════════════════════════════════════════════════════════════
+--
+-- Uma política por comando, em vez de uma para tudo. Ler o catálogo nacional é
+-- direito de todos; alterá-lo, de ninguém que opere como escritório.
+
+DROP POLICY IF EXISTS fiscal_rule_visibility ON fiscal_rule;
+
+CREATE POLICY fiscal_rule_read ON fiscal_rule
+  FOR SELECT
+  USING (tenant_id IS NULL OR tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+CREATE POLICY fiscal_rule_insert ON fiscal_rule
+  FOR INSERT
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+CREATE POLICY fiscal_rule_update ON fiscal_rule
+  FOR UPDATE
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+CREATE POLICY fiscal_rule_delete ON fiscal_rule
+  FOR DELETE
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+COMMENT ON POLICY fiscal_rule_read ON fiscal_rule IS
+  'Leitura: catálogo nacional + regras do próprio escritório.';
+COMMENT ON POLICY fiscal_rule_delete ON fiscal_rule IS
+  'Apagar SOMENTE as próprias. A política única da 0049 deixava o DELETE alcançar a regra global, porque WITH CHECK não governa DELETE — só o USING governa.';
+
+-- ── A mesma pergunta, feita às policies vizinhas ───────────────────────────
+--
+-- `role` e `role_permission` têm o mesmo formato desde a 0045 e, no papel,
+-- o mesmo buraco no DELETE. Lá a segunda barreira segura: a 0045 revogou
+-- INSERT, UPDATE e DELETE do runtime, e `migrate.ts` repete o REVOKE a cada
+-- deploy. Fica registrado aqui porque a próxima pessoa a ler aquela policy vai
+-- fazer esta pergunta — e a resposta é "o privilégio segura", não "a política
+-- está certa".

package/src/db/migrations/0053_rule_validity_lower_bound.sql

@@ -0,0 +1,44 @@
+-- 0053 — `valid_from` descreve a REGRA, não o dia em que a linha foi criada.
+--
+-- ═══ O erro da 0051, e por que ele parecia certo ═══════════════════════════
+--
+-- A 0051 gravou `valid_from = CURRENT_DATE` nas regras do seed, com a
+-- justificativa de que é honesto dizer "esta regra existe no sistema desde
+-- hoje". A frase é verdadeira e a modelagem estava errada: `valid_from` não
+-- descreve quando o REGISTRO nasceu — descreve desde quando a REGRA vale.
+--
+-- O efeito apareceu no primeiro teste: um escritório que abre a competência de
+-- agosto em setembro — que é o normal da profissão, não a exceção — não
+-- recebia obrigação nenhuma, porque nenhuma regra era candidata para agosto.
+--
+-- ═══ Por que uma data antiga é mais honesta que hoje ══════════════════════
+--
+-- Não se sabe desde quando cada obrigação do seed está em vigor; várias são
+-- anteriores ao produto. As duas opções eram:
+--
+--   hoje        → afirma que a regra não valia em agosto. É falso.
+--   limite baixo → afirma que ela vale desde antes de o sistema existir, sem
+--                  dizer desde quando. É verdadeiro e incompleto.
+--
+-- A segunda é a correta: `2000-01-01` aqui não é uma data legal, é a ausência
+-- de início declarado. Declarar o início de verdade faz parte de validar a
+-- regra, e as regras do seed continuam `pending_validation` justamente porque
+-- ninguém as validou.
+--
+-- Nada disso relaxa a barreira: uma regra pendente não gera obrigação. O que
+-- muda é que ela passa a ser CANDIDATA e a aparecer na prévia com o motivo
+-- certo — "aguarda conferência" em vez de "não existe regra", que mandaria o
+-- escritório procurar o que já está lá.
+
+UPDATE fiscal_rule
+   SET valid_from = DATE '2000-01-01',
+       note = coalesce(note || ' ', '') ||
+              '[N1] Início de vigência não declarado: a data é um limite inferior, não uma afirmação legal.',
+       updated_at = now()
+ WHERE tenant_id IS NULL
+   AND deleted_at IS NULL
+   AND valid_from > DATE '2000-01-01'
+   AND status IN ('pending_validation', 'not_configured');
+
+COMMENT ON COLUMN fiscal_rule.valid_from IS
+  'Desde quando a REGRA vale — não quando a linha foi criada. Regra sem início declarado usa um limite inferior antigo, e declarar o início real faz parte de validá-la.';

package/src/db/migrations/0054_tenant_profile_and_rule_source.sql

@@ -0,0 +1,89 @@
+-- 0054 — a identidade do escritório vira dado do produto, e a regra fiscal
+-- passa a citar a fonte.
+--
+-- ═══ Por que estas duas coisas na mesma migration ══════════════════════════
+--
+-- As duas nascem do mesmo achado da auditoria C360: o produto tinha caminho de
+-- LEITURA e não tinha caminho de ESCRITA. A marca do escritório vivia em
+-- `tenant.settings` e só era gravável por `UPDATE` manual no banco; a regra
+-- fiscal tinha `source_reference` em texto livre e nenhum lugar canônico para o
+-- endereço da norma. Nos dois casos o efeito é o mesmo: um escritório novo
+-- exigia desenvolvedor.
+--
+-- Nenhuma tabela nova. Nenhum GRANT novo: `tenant` e `fiscal_rule` já estão na
+-- allowlist do runtime, e GRANT em Postgres é por tabela — coluna nova nasce
+-- alcançável pelo mesmo privilégio.
+
+-- ── 1 · Identidade do escritório ───────────────────────────────────────────
+--
+-- `display_name` e `legal_name` já existiam. Faltavam o documento e o fuso, e
+-- os dois têm consumidor concreto e próximo:
+--
+--   documento → o escritório é ele mesmo um contribuinte. A onda de ingestão
+--               fiscal precisa do CNPJ dele para o certificado da própria casa
+--               (`digital_certificate.client_id IS NULL` já prevê esse caso).
+--   fuso      → todo vencimento hoje é calculado em data, sem hora. No dia em
+--               que houver corte por horário (janela de envio, D-0 às 18h), a
+--               ausência do fuso vira erro de um dia para metade do país.
+--
+-- Só dígitos, como em `client.document_number`: máscara é apresentação, e duas
+-- representações do mesmo documento não se encontram em nenhuma busca.
+ALTER TABLE tenant ADD COLUMN IF NOT EXISTS document_number text;
+ALTER TABLE tenant ADD COLUMN IF NOT EXISTS timezone text NOT NULL DEFAULT 'America/Sao_Paulo';
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT FROM pg_constraint WHERE conname = 'tenant_document_format') THEN
+    ALTER TABLE tenant ADD CONSTRAINT tenant_document_format
+      CHECK (document_number IS NULL OR document_number ~ '^[0-9]{11}$' OR document_number ~ '^[0-9]{14}$');
+  END IF;
+
+  -- Fuso: a lista dos fusos BRASILEIROS, não um texto livre.
+  --
+  -- `CHECK` não enxerga `pg_timezone_names`, então a alternativa seria aceitar
+  -- qualquer string e descobrir o erro na primeira conversão. O produto é
+  -- nacional; enumerar os dezesseis fusos do país é a restrição honesta e
+  -- fecha a porta para `'GMT-3'`, `'Brasilia'` e afins, que parecem certos e
+  -- não são identificadores IANA.
+  IF NOT EXISTS (SELECT FROM pg_constraint WHERE conname = 'tenant_timezone_br') THEN
+    ALTER TABLE tenant ADD CONSTRAINT tenant_timezone_br
+      CHECK (timezone IN (
+        'America/Sao_Paulo','America/Bahia','America/Fortaleza','America/Recife',
+        'America/Belem','America/Araguaina','America/Maceio','America/Campo_Grande',
+        'America/Cuiaba','America/Santarem','America/Manaus','America/Porto_Velho',
+        'America/Boa_Vista','America/Rio_Branco','America/Eirunepe','America/Noronha'
+      ));
+  END IF;
+END $$;
+
+COMMENT ON COLUMN tenant.document_number IS
+  'CNPJ (14) ou CPF (11) do próprio escritório, só dígitos. O escritório é contribuinte de si mesmo — a ingestão fiscal precisa deste número para o certificado da casa.';
+COMMENT ON COLUMN tenant.timezone IS
+  'Fuso IANA do escritório. Restrito aos fusos brasileiros: o produto é nacional e um texto livre aceitaria identificadores que não existem.';
+
+-- ── 2 · A regra fiscal cita a fonte ────────────────────────────────────────
+--
+-- `source_reference` continua sendo a referência humana ("IN RFB 2.005/2021,
+-- art. 3º"). `source_url` é o ENDEREÇO oficial, separado de propósito: uma URL
+-- misturada com texto livre não pode ser verificada, aberta na tela nem
+-- comparada entre versões.
+--
+-- Só https. A regra fiscal aparece numa tela de conferência e o endereço vira
+-- link; `javascript:` e `data:` num campo editável seriam XSS armazenado com a
+-- assinatura do escritório.
+--
+-- Isto NÃO valida a regra. Citar a fonte é o insumo da conferência humana, e
+-- `status` continua exigindo `validated_by` e `validated_at` para sair de
+-- `pending_validation`.
+ALTER TABLE fiscal_rule ADD COLUMN IF NOT EXISTS source_url text;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT FROM pg_constraint WHERE conname = 'fiscal_rule_source_url_https') THEN
+    ALTER TABLE fiscal_rule ADD CONSTRAINT fiscal_rule_source_url_https
+      CHECK (source_url IS NULL OR source_url ~ '^https://[^\s"''<>]+$');
+  END IF;
+END $$;
+
+COMMENT ON COLUMN fiscal_rule.source_url IS
+  'Endereço oficial da norma, https. Insumo da conferência humana — citar a fonte não valida a regra.';

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.