@baruk/core 0.4.2 → 0.6.0

package/src/db/migrations/0046_pilot_activation_model.sql

@@ -0,0 +1,184 @@
+-- 0046 — o modelo de dados que falta para ativar um cliente real.
+--
+-- A Fase 5 começou mapeando, contra o schema, exatamente quais dados um
+-- escritório precisa para ativar um cliente. Quatro ausências apareceram, e
+-- todas bloqueiam algo concreto do piloto:
+--
+--  1. **Não há onde guardar município e UF.** Três obrigações do catálogo são
+--     estaduais ou municipais e têm prazo que varia por localidade. Sem UF e
+--     município no cliente, marcar essas obrigações como "depende da localidade"
+--     é honesto mas inútil: não há o dado com que decidir.
+--
+--  2. **Não há responsável pelo cliente.** `recurring_instance` e
+--     `service_request` têm `responsible_user_id`; o cliente não tem. Então a
+--     carteira não pode ser dividida entre as pessoas do escritório — só as
+--     tarefas podem, uma a uma, depois de criadas.
+--
+--  3. **A importação não deixa rastro reversível.** `commitImport` cria
+--     clientes e devolve uma contagem. Não há como responder "quais linhas
+--     entraram naquela importação" nem desfazer uma importação inteira.
+--
+--  4. **A validação humana do catálogo não tem onde ser gravada.** O catálogo
+--     fiscal foi semeado tecnicamente e não foi conferido contra os serviços que
+--     a SC presta. Marcar "conferido" é por escritório, não global — o mesmo
+--     template de sistema pode ser válido para um escritório e não se aplicar a
+--     outro. Por isso é tabela própria, e não coluna em `recurring_item_type`:
+--     aquela linha é COMPARTILHADA entre todos os tenants, e uma coluna nela
+--     faria um escritório carimbar a validação do outro.
+--
+-- Nada aqui liga cobrança, obrigação ou envio. É só onde o dado passa a caber.
+
+-- ── 1 · Localidade e responsável do cliente ────────────────────────────────
+--
+-- Os campos de endereço são deliberadamente poucos: os que o produto usa hoje.
+-- `state_uf` tem CHECK de duas maiúsculas porque é ele que vai selecionar regra
+-- estadual — um "Goias" digitado no lugar de "GO" faria a regra não casar em
+-- silêncio, e silêncio é o modo de falha que esta fase existe para eliminar.
+
+ALTER TABLE client ADD COLUMN IF NOT EXISTS address_line text;
+ALTER TABLE client ADD COLUMN IF NOT EXISTS municipality text;
+ALTER TABLE client ADD COLUMN IF NOT EXISTS state_uf text;
+ALTER TABLE client ADD COLUMN IF NOT EXISTS postal_code text;
+ALTER TABLE client ADD COLUMN IF NOT EXISTS notes text;
+ALTER TABLE client ADD COLUMN IF NOT EXISTS responsible_user_id uuid REFERENCES "user"(id);
+ALTER TABLE client ADD COLUMN IF NOT EXISTS contract_started_on date;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT FROM pg_constraint WHERE conname = 'client_state_uf_format'
+  ) THEN
+    ALTER TABLE client ADD CONSTRAINT client_state_uf_format
+      CHECK (state_uf IS NULL OR state_uf ~ '^[A-Z]{2}$');
+  END IF;
+END $$;
+
+CREATE INDEX IF NOT EXISTS client_responsible_idx
+  ON client (tenant_id, responsible_user_id) WHERE deleted_at IS NULL;
+CREATE INDEX IF NOT EXISTS client_locality_idx
+  ON client (tenant_id, state_uf, municipality) WHERE deleted_at IS NULL;
+
+COMMENT ON COLUMN client.state_uf IS
+  'UF em duas maiúsculas. Seleciona regra estadual de vencimento; formato livre faria a regra não casar em silêncio.';
+COMMENT ON COLUMN client.responsible_user_id IS
+  'Responsável pela carteira deste cliente. Toda troca passa por audit_log — ver assignClientResponsible.';
+
+-- ── 2 · Lote de importação ─────────────────────────────────────────────────
+--
+-- Existe para duas perguntas que hoje não têm resposta: "o que entrou naquela
+-- importação?" e "como desfaço?". O desfazer é lógico (soft-delete dos clientes
+-- do lote que ninguém tocou desde então), nunca físico: apagar linha real é
+-- proibido, e um cliente que já ganhou honorário ou obrigação não é mais "só uma
+-- linha importada".
+--
+-- `source_digest` é o sha256 do CSV. É ele que amarra plano e commit: o commit
+-- recusa aplicar um conteúdo diferente do que foi previsto, em vez de reparsear
+-- e produzir um resultado que ninguém viu.
+
+CREATE TABLE IF NOT EXISTS client_import_batch (
+  id             uuid PRIMARY KEY,
+  tenant_id      uuid NOT NULL REFERENCES tenant(id),
+  source_digest  text NOT NULL,
+  source_name    text,
+  row_total      int  NOT NULL DEFAULT 0,
+  created_count  int  NOT NULL DEFAULT 0,
+  skipped_count  int  NOT NULL DEFAULT 0,
+  error_count    int  NOT NULL DEFAULT 0,
+  status         text NOT NULL DEFAULT 'applied'
+                   CHECK (status IN ('applied', 'rolled_back')),
+  created_by     uuid REFERENCES "user"(id),
+  created_at     timestamptz NOT NULL DEFAULT now(),
+  rolled_back_at timestamptz,
+  rolled_back_by uuid REFERENCES "user"(id),
+  CONSTRAINT client_import_batch_tenant_id_uq UNIQUE (tenant_id, id),
+  CHECK ((status <> 'rolled_back') OR rolled_back_at IS NOT NULL)
+);
+CREATE INDEX IF NOT EXISTS client_import_batch_tenant_idx
+  ON client_import_batch (tenant_id, created_at DESC);
+
+ALTER TABLE client ADD COLUMN IF NOT EXISTS import_batch_id uuid;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT FROM pg_constraint WHERE conname = 'client_import_batch_fk') THEN
+    ALTER TABLE client ADD CONSTRAINT client_import_batch_fk
+      FOREIGN KEY (tenant_id, import_batch_id)
+      REFERENCES client_import_batch (tenant_id, id);
+  END IF;
+END $$;
+
+CREATE INDEX IF NOT EXISTS client_import_batch_idx
+  ON client (tenant_id, import_batch_id) WHERE import_batch_id IS NOT NULL;
+
+ALTER TABLE client_import_batch ENABLE ROW LEVEL SECURITY;
+ALTER TABLE client_import_batch FORCE ROW LEVEL SECURITY;
+CREATE POLICY client_import_batch_tenant_isolation ON client_import_batch
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- ── 3 · Validação humana do catálogo, por escritório ───────────────────────
+--
+-- Um item do catálogo, para um escritório, está em um de quatro estados. O
+-- padrão é `pending_validation` e ele é o ponto inteiro: enquanto ninguém
+-- conferiu, o produto deve DIZER que ninguém conferiu, em vez de deixar o seed
+-- passar por verdade operacional.
+--
+-- `depends_on_locality` marca os itens cujo prazo muda por UF ou município. Não
+-- é um prazo inventado — é a ausência de prazo, declarada.
+
+CREATE TABLE IF NOT EXISTS recurring_item_type_validation (
+  id             uuid PRIMARY KEY,
+  tenant_id      uuid NOT NULL REFERENCES tenant(id),
+  item_type_id   uuid NOT NULL REFERENCES recurring_item_type(id),
+  status         text NOT NULL DEFAULT 'pending_validation'
+                   CHECK (status IN ('validated', 'pending_validation', 'not_applicable', 'disabled')),
+  depends_on_locality boolean NOT NULL DEFAULT false,
+  note           text,
+  validated_by   uuid REFERENCES "user"(id),
+  validated_at   timestamptz,
+  created_at     timestamptz NOT NULL DEFAULT now(),
+  updated_at     timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT recurring_item_type_validation_tenant_id_uq UNIQUE (tenant_id, id),
+  CHECK ((status <> 'validated') OR validated_at IS NOT NULL)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS recurring_item_type_validation_uq
+  ON recurring_item_type_validation (tenant_id, item_type_id);
+
+ALTER TABLE recurring_item_type_validation ENABLE ROW LEVEL SECURITY;
+ALTER TABLE recurring_item_type_validation FORCE ROW LEVEL SECURITY;
+CREATE POLICY recurring_item_type_validation_tenant_isolation ON recurring_item_type_validation
+  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 recurring_item_type_validation IS
+  'Conferência humana do catálogo, POR ESCRITÓRIO. Tabela própria porque recurring_item_type com tenant_id NULL é linha compartilhada: coluna nela faria um escritório carimbar a validação do outro.';
+
+-- ── 4 · O serviço contratado ganha responsável e vínculo com obrigação ─────
+--
+-- `fee_agreement` já era a entidade de serviço contratado: tem descrição, valor,
+-- periodicidade, vencimento, início, fim e status, e um cliente pode ter
+-- vários. Não se cria entidade nova para o que já existe. Faltavam duas coisas.
+--
+-- O vínculo é tabela de ligação porque a relação é N-para-N de verdade: um
+-- serviço de folha cobre eSocial, FGTS e a própria folha; e a mesma obrigação
+-- pode estar coberta por mais de um contrato ao longo do tempo.
+
+ALTER TABLE fee_agreement ADD COLUMN IF NOT EXISTS responsible_user_id uuid REFERENCES "user"(id);
+
+CREATE TABLE IF NOT EXISTS fee_agreement_obligation (
+  id                uuid PRIMARY KEY,
+  tenant_id         uuid NOT NULL REFERENCES tenant(id),
+  fee_agreement_id  uuid NOT NULL,
+  item_type_id      uuid NOT NULL REFERENCES recurring_item_type(id),
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT fee_agreement_obligation_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, fee_agreement_id) REFERENCES fee_agreement (tenant_id, id)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS fee_agreement_obligation_uq
+  ON fee_agreement_obligation (tenant_id, fee_agreement_id, item_type_id);
+
+ALTER TABLE fee_agreement_obligation ENABLE ROW LEVEL SECURITY;
+ALTER TABLE fee_agreement_obligation FORCE ROW LEVEL SECURITY;
+CREATE POLICY fee_agreement_obligation_tenant_isolation ON fee_agreement_obligation
+  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/0047_recipient_clearance.sql

@@ -0,0 +1,89 @@
+-- 0047 — liberação do destinatário para comunicação externa.
+--
+-- ── O que foi medido em produção ────────────────────────────────────────────
+--
+-- Em 2026-09-05, às 12:00, o cron de cobrança enviou 5 e-mails no tenant `sc`.
+-- Hoje isso é inofensivo: o único cliente com e-mail cadastrado é o do próprio
+-- titular, e os recebíveis são sintéticos.
+--
+-- O problema aparece no dia seguinte à importação da carteira real. A régua
+-- percorre todo cliente com e-mail e recebível vencido, e **nada no caminho
+-- pergunta se alguém conferiu aquele endereço**. Trezentos clientes importados
+-- de manhã recebem cobrança automática à tarde, sobre dados que ninguém
+-- validou. Foi exatamente assim que 81 e-mails saíram sobre a carteira de QA.
+--
+-- ── Por que não é consentimento ─────────────────────────────────────────────
+--
+-- O motor já tem consentimento, e ele está certo do jeito que está: a política
+-- do produto trata `unknown` como permitido no e-mail porque cobrança
+-- transacional se apoia na relação contratual. Mudar isso travaria a cobrança
+-- de toda carteira legada que nunca teve o campo preenchido — o próprio código
+-- do consentimento avisa disso.
+--
+-- São perguntas diferentes:
+--
+--   consentimento → "esta pessoa aceita ser contatada?"   (vontade do DESTINATÁRIO)
+--   liberação     → "alguém daqui conferiu este endereço?" (conferência do REMETENTE)
+--
+-- Elas se separam exatamente no caso que importa: o cliente recém-importado tem
+-- relação contratual e nenhuma conferência.
+--
+-- ── Por que a ausência bloqueia ─────────────────────────────────────────────
+--
+-- O padrão é NÃO liberado, e não existe configuração que inverta isso. Um
+-- default "libera se ninguém disse nada" transformaria a omissão em
+-- autorização — e omissão é o estado natural de todo cliente que acabou de
+-- entrar. O cliente não some da operação: ele aparece com pulo nomeado
+-- (`recipient_not_confirmed`) na trilha e contado no painel.
+
+ALTER TABLE client ADD COLUMN IF NOT EXISTS communication_cleared_at timestamptz;
+ALTER TABLE client ADD COLUMN IF NOT EXISTS communication_cleared_by uuid REFERENCES "user"(id);
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT FROM pg_constraint WHERE conname = 'client_clearance_coherent') THEN
+    -- Data e autor andam juntos: uma liberação sem autor não responde "quem
+    -- conferiu?", que é a única pergunta que ela existe para responder.
+    ALTER TABLE client ADD CONSTRAINT client_clearance_coherent
+      CHECK ((communication_cleared_at IS NULL) = (communication_cleared_by IS NULL));
+  END IF;
+END $$;
+
+CREATE INDEX IF NOT EXISTS client_clearance_idx
+  ON client (tenant_id, communication_cleared_at) WHERE deleted_at IS NULL;
+
+COMMENT ON COLUMN client.communication_cleared_at IS
+  'Quando alguém do escritório conferiu o contato e liberou este cliente para comunicação externa. NULL = não liberado, e a régua pula com motivo nomeado.';
+
+-- ── Marco de início do piloto real ──────────────────────────────────────────
+--
+-- Os registros hoje no tenant `sc` são de desenvolvimento, QA, homologação e
+-- demonstração — inclusive os do App Review da Meta. Nenhum é carteira real.
+--
+-- Sem um marco explícito, daqui a três meses ninguém distingue "cliente de
+-- teste de agosto" de "cliente real de setembro", e todo indicador do painel
+-- passa a misturar os dois. A tabela existe para que a fronteira seja um FATO
+-- gravado, com autor e data, e não uma lembrança.
+
+CREATE TABLE IF NOT EXISTS tenant_pilot_milestone (
+  id           uuid PRIMARY KEY,
+  tenant_id    uuid NOT NULL REFERENCES tenant(id),
+  milestone    text NOT NULL CHECK (milestone IN ('real_pilot_start')),
+  occurred_at  timestamptz NOT NULL DEFAULT now(),
+  declared_by  uuid REFERENCES "user"(id),
+  note         text,
+  CONSTRAINT tenant_pilot_milestone_tenant_id_uq UNIQUE (tenant_id, id)
+);
+
+-- Um marco por tenant: "quando começou de verdade" não admite duas respostas.
+CREATE UNIQUE INDEX IF NOT EXISTS tenant_pilot_milestone_uq
+  ON tenant_pilot_milestone (tenant_id, milestone);
+
+ALTER TABLE tenant_pilot_milestone ENABLE ROW LEVEL SECURITY;
+ALTER TABLE tenant_pilot_milestone FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_pilot_milestone_tenant_isolation ON tenant_pilot_milestone
+  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_pilot_milestone IS
+  'Fronteira gravada entre dado pré-produtivo (QA, demo, Meta App Review) e carteira real. Sem ela, os indicadores do painel misturam os dois e ninguém consegue separar depois.';

package/src/db/migrations/0048_item_type_note.sql

@@ -0,0 +1,16 @@
+-- 0048 — a observação do catálogo passa a chegar a quem confere.
+--
+-- `FiscalCatalogEntry.note` existe na vertical desde a Fase 3, com o comentário
+-- "Aparece na UI para o operador saber o que ajustar". Ela nunca apareceu:
+-- não havia coluna, o seed não a escrevia, e a tela não tinha o que mostrar.
+--
+-- Nove das dezessete entradas têm nota, e são exatamente as que o escritório
+-- precisa ler para decidir — as de esfera estadual e municipal, cujo prazo
+-- muda por localidade, e as que dependem do segmento atendido. A conferência
+-- humana do catálogo é o bloqueio desta fase, e ela estava sendo pedida sem a
+-- informação que a torna possível.
+
+ALTER TABLE recurring_item_type ADD COLUMN IF NOT EXISTS note text;
+
+COMMENT ON COLUMN recurring_item_type.note IS
+  'Observação para quem confere: o que este item exige de decisão local (UF, município, segmento). Não é regra — é o que o operador precisa saber para decidir.';

package/src/db/migrations/0049_national_fiscal_engine.sql

@@ -0,0 +1,279 @@
+-- 0049 — a fundação nacional do motor fiscal.
+--
+-- ═══ A decisão de modelagem que organiza tudo ═══════════════════════════════
+--
+-- Hoje `recurring_item_type` responde duas perguntas diferentes na mesma linha:
+--
+--   "o que é esta obrigação?"        → DAS, ISS, eSocial. Nacional e estável.
+--   "para quem, quando e como vence?" → varia por UF, por município e no tempo.
+--
+-- Enquanto as duas moram juntas, o índice único em `(key)` permite UMA linha
+-- por chave, e daí saem as três limitações que a auditoria mediu: o ISS de
+-- Goiânia e o de São Paulo não coexistem, duas versões da mesma regra não
+-- coexistem, e a aplicabilidade só sabe olhar regime.
+--
+-- Esta migration separa as duas perguntas:
+--
+--   `recurring_item_type`  → a IDENTIDADE. Continua como está. Nada quebra.
+--   `fiscal_rule`          → a REGRA: jurisdição + vigência + versão +
+--                            condições + vencimento.
+--
+-- Um tipo de item passa a ter N regras: uma federal, uma por UF, uma por
+-- município, e mais de uma no tempo. É o que abrangência nacional exige, e é
+-- aditivo — nenhuma linha existente é reescrita.
+--
+-- ═══ O que esta migration NÃO faz ══════════════════════════════════════════
+--
+-- Não cataloga regra nenhuma do Brasil. Ela cria a capacidade; o conteúdo
+-- entra depois, com governança. Os 17 seeds atuais são migrados na 0050 SEM
+-- ganhar precisão que não têm.
+
+-- ── 1 · Vocabulário do perfil fiscal ───────────────────────────────────────
+--
+-- Registro de atributos, e não colunas em `client`.
+--
+-- A alternativa seria `has_employees`, `icms_taxpayer`, `iss_taxpayer`,
+-- `ipi_taxpayer`… uma coluna por pergunta fiscal. Isso não escala: cada UF e
+-- cada segmento acrescenta perguntas, e a tabela de cliente viraria uma
+-- estrutura rígida impossível de evoluir — exatamente o que a premissa pede
+-- para evitar.
+--
+-- Com um REGISTRO, acrescentar um atributo é INSERT, não migration. E a FK
+-- impede erro de digitação virar atributo novo em silêncio.
+
+CREATE TABLE IF NOT EXISTS fiscal_attribute_definition (
+  key           text PRIMARY KEY,
+  label         text NOT NULL,
+  description   text,
+  value_type    text NOT NULL CHECK (value_type IN ('boolean', 'text', 'enum')),
+  -- Para `enum`: os valores aceitos. Para os demais, `null`.
+  allowed_values jsonb,
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  CHECK ((value_type = 'enum') = (allowed_values IS NOT NULL))
+);
+
+COMMENT ON TABLE fiscal_attribute_definition IS
+  'Vocabulário GLOBAL do perfil fiscal. Acrescentar atributo é INSERT, não migration — é o que permite o modelo evoluir sem alterar a tabela de cliente.';
+
+INSERT INTO fiscal_attribute_definition (key, label, description, value_type, allowed_values) VALUES
+  ('has_employees', 'Possui empregados',
+   'Decide a aplicabilidade das obrigações trabalhistas. A AUSÊNCIA deste dado não é "não": é desconhecido, e o motor devolve INSUFFICIENT_DATA.',
+   'boolean', NULL),
+  ('icms_taxpayer', 'Contribuinte de ICMS', NULL, 'boolean', NULL),
+  ('ipi_taxpayer', 'Contribuinte de IPI', NULL, 'boolean', NULL),
+  ('iss_taxpayer', 'Contribuinte de ISS', NULL, 'boolean', NULL),
+  ('activity_segment', 'Segmento de atividade', NULL,
+   'enum', '["comercio","industria","servicos","misto"]'::jsonb),
+  ('cnae_primary', 'CNAE principal', 'Código, sem interpretação pelo motor nesta fase.', 'text', NULL),
+  ('state_registration', 'Inscrição estadual', NULL, 'text', NULL),
+  ('municipal_registration', 'Inscrição municipal', NULL, 'text', NULL)
+ON CONFLICT (key) DO NOTHING;
+
+-- ── 2 · Perfil fiscal do cliente ───────────────────────────────────────────
+--
+-- Ausência de linha = atributo DESCONHECIDO, e é distinto de `false`. É a
+-- distinção que sustenta o `INSUFFICIENT_DATA` do motor: um cliente sobre o
+-- qual ninguém disse se tem empregados não pode receber eSocial nem ser
+-- declarado isento dele.
+
+CREATE TABLE IF NOT EXISTS client_fiscal_attribute (
+  id            uuid PRIMARY KEY,
+  tenant_id     uuid NOT NULL REFERENCES tenant(id),
+  client_id     uuid NOT NULL,
+  attribute_key text NOT NULL REFERENCES fiscal_attribute_definition(key),
+  value_bool    boolean,
+  value_text    text,
+  source        text,
+  updated_by    uuid REFERENCES "user"(id),
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT client_fiscal_attribute_tenant_id_uq UNIQUE (tenant_id, id),
+  FOREIGN KEY (tenant_id, client_id) REFERENCES client (tenant_id, id),
+  -- Exatamente um valor. Nenhum seria linha sem informação; dois seriam duas
+  -- respostas para a mesma pergunta.
+  CHECK ((value_bool IS NOT NULL)::int + (value_text IS NOT NULL)::int = 1)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS client_fiscal_attribute_uq
+  ON client_fiscal_attribute (tenant_id, client_id, attribute_key);
+
+ALTER TABLE client_fiscal_attribute ENABLE ROW LEVEL SECURITY;
+ALTER TABLE client_fiscal_attribute FORCE ROW LEVEL SECURITY;
+CREATE POLICY client_fiscal_attribute_tenant_isolation ON client_fiscal_attribute
+  USING (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+-- Código IBGE do município: o identificador canônico.
+--
+-- `client.municipality` é texto livre e serve para a tela. Casar regra
+-- municipal por texto livre falharia no primeiro "Goiania" sem acento. O
+-- código é opcional: sem ele, regra municipal devolve INSUFFICIENT_DATA em vez
+-- de casar por aproximação.
+ALTER TABLE client ADD COLUMN IF NOT EXISTS municipality_ibge_code text;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT FROM pg_constraint WHERE conname = 'client_ibge_format') THEN
+    ALTER TABLE client ADD CONSTRAINT client_ibge_format
+      CHECK (municipality_ibge_code IS NULL OR municipality_ibge_code ~ '^[0-9]{7}$');
+  END IF;
+END $$;
+
+-- ── 3 · A regra fiscal versionada ──────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS fiscal_rule (
+  id            uuid PRIMARY KEY,
+  -- NULL = regra GLOBAL do produto. NOT NULL = regra do próprio escritório.
+  -- Mesmo padrão de `recurring_item_type` e `role`: ler o global é direito de
+  -- todos; escrevê-lo, de ninguém que opere como tenant.
+  tenant_id     uuid REFERENCES tenant(id),
+  item_type_id  uuid NOT NULL REFERENCES recurring_item_type(id),
+
+  -- ── jurisdição ──────────────────────────────────────────────────────────
+  jurisdiction_scope text NOT NULL CHECK (jurisdiction_scope IN ('federal', 'state', 'municipal')),
+  jurisdiction_uf    text CHECK (jurisdiction_uf IS NULL OR jurisdiction_uf ~ '^[A-Z]{2}$'),
+  jurisdiction_city_ibge text CHECK (jurisdiction_city_ibge IS NULL OR jurisdiction_city_ibge ~ '^[0-9]{7}$'),
+  -- A jurisdição precisa ser COMPLETA para o seu nível. Uma regra "estadual"
+  -- sem UF não é uma regra: é um marcador que casaria com o país inteiro.
+  CHECK (
+    (jurisdiction_scope = 'federal'   AND jurisdiction_uf IS NULL AND jurisdiction_city_ibge IS NULL) OR
+    (jurisdiction_scope = 'state'     AND jurisdiction_uf IS NOT NULL AND jurisdiction_city_ibge IS NULL) OR
+    (jurisdiction_scope = 'municipal' AND jurisdiction_uf IS NOT NULL AND jurisdiction_city_ibge IS NOT NULL)
+  ),
+
+  -- ── vigência e versão ───────────────────────────────────────────────────
+  version       int NOT NULL DEFAULT 1 CHECK (version > 0),
+  valid_from    date NOT NULL,
+  valid_until   date,
+  CHECK (valid_until IS NULL OR valid_until >= valid_from),
+
+  status        text NOT NULL DEFAULT 'pending_validation'
+                  CHECK (status IN ('not_configured', 'pending_validation', 'validated', 'expired', 'disabled')),
+
+  -- ── conteúdo ────────────────────────────────────────────────────────────
+  -- AST declarativa. Interpretada por código tipado, NUNCA avaliada como
+  -- expressão: nada aqui vira `eval`, SQL ou função.
+  conditions    jsonb NOT NULL DEFAULT '{"op":"always"}'::jsonb,
+  due_rule      jsonb,
+
+  -- ── procedência ─────────────────────────────────────────────────────────
+  source_reference text,
+  validated_by  uuid REFERENCES "user"(id),
+  validated_at  timestamptz,
+  note          text,
+
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now(),
+  deleted_at    timestamptz,
+
+  CONSTRAINT fiscal_rule_tenant_id_uq UNIQUE (tenant_id, id),
+  -- Uma regra `validated` sem quem validou é uma afirmação sem autor.
+  CHECK ((status <> 'validated') OR (validated_at IS NOT NULL AND validated_by IS NOT NULL)),
+  -- `not_configured` é o estado honesto de quem não tem vencimento definido.
+  -- Uma regra validada SEM vencimento produziria obrigação sem data.
+  CHECK ((status <> 'validated') OR due_rule IS NOT NULL)
+);
+
+-- Versões da mesma regra não se sobrepõem: uma só vigente por jurisdição.
+-- Mesmo padrão que `accounting_regime` já provou para o regime do cliente.
+CREATE UNIQUE INDEX IF NOT EXISTS fiscal_rule_current_uq
+  ON fiscal_rule (
+    coalesce(tenant_id::text, '-'), item_type_id, jurisdiction_scope,
+    coalesce(jurisdiction_uf, '-'), coalesce(jurisdiction_city_ibge, '-')
+  )
+  WHERE valid_until IS NULL AND deleted_at IS NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS fiscal_rule_version_uq
+  ON fiscal_rule (
+    coalesce(tenant_id::text, '-'), item_type_id, jurisdiction_scope,
+    coalesce(jurisdiction_uf, '-'), coalesce(jurisdiction_city_ibge, '-'), version
+  )
+  WHERE deleted_at IS NULL;
+
+-- Pré-filtragem: a engine busca por jurisdição + vigência antes de avaliar
+-- condição nenhuma. Sem este índice, avaliar a carteira exigiria varrer o
+-- catálogo inteiro por cliente.
+CREATE INDEX IF NOT EXISTS fiscal_rule_lookup_idx
+  ON fiscal_rule (jurisdiction_scope, jurisdiction_uf, jurisdiction_city_ibge, valid_from)
+  WHERE deleted_at IS NULL;
+CREATE INDEX IF NOT EXISTS fiscal_rule_item_idx
+  ON fiscal_rule (item_type_id, valid_from) WHERE deleted_at IS NULL;
+
+ALTER TABLE fiscal_rule ENABLE ROW LEVEL SECURITY;
+ALTER TABLE fiscal_rule FORCE ROW LEVEL SECURITY;
+
+-- Leitura: a regra global e as do próprio escritório.
+-- Escrita: SOMENTE as do próprio escritório.
+--
+-- O `WITH CHECK` sem o ramo `IS NULL` é a lição da 0045: com ele, qualquer
+-- tenant forjaria regra fiscal GLOBAL — que vale para todos os escritórios do
+-- país. É a escalada mais cara que este schema comporta.
+CREATE POLICY fiscal_rule_visibility ON fiscal_rule
+  USING (tenant_id IS NULL OR tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid)
+  WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant', true), '')::uuid);
+
+DO $$
+DECLARE owner_role text;
+BEGIN
+  SELECT tableowner INTO owner_role FROM pg_tables
+   WHERE schemaname = 'public' AND tablename = 'fiscal_rule';
+  IF owner_role IS NULL THEN
+    RAISE EXCEPTION 'fiscal_rule sem dono identificável — abortando';
+  END IF;
+  -- FORCE RLS vale para o dono; o provisionamento do catálogo global roda sem
+  -- tenant no contexto e precisa de política nominal. Padrão da 0042/0045.
+  EXECUTE format(
+    'CREATE POLICY fiscal_rule_system_provisioning ON fiscal_rule FOR ALL TO %I USING (true) WITH CHECK (true)',
+    owner_role);
+END $$;
+
+COMMENT ON POLICY fiscal_rule_visibility ON fiscal_rule IS
+  'Leitura: regra global + as do tenant. Escrita: SOMENTE do tenant. O ramo IS NULL fora do WITH CHECK impede forjar regra fiscal nacional (lição do P0-A, Fase 4).';
+
+-- ── 4 · Política operacional do escritório ─────────────────────────────────
+--
+-- Separa REGRA LEGAL de PROCEDIMENTO DO ESCRITÓRIO.
+--
+-- O prazo legal do DAS é do país. O prazo em que o escritório quer os
+-- documentos do cliente na mão é dele. Enquanto os dois moram no mesmo campo,
+-- ajustar o procedimento interno reescreve a regra legal — em silêncio, e para
+-- todo mundo que enxerga aquela linha.
+
+CREATE TABLE IF NOT EXISTS tenant_rule_policy (
+  id            uuid PRIMARY KEY,
+  tenant_id     uuid NOT NULL REFERENCES tenant(id),
+  item_type_id  uuid NOT NULL REFERENCES recurring_item_type(id),
+  -- Dias ANTES do vencimento legal em que o escritório quer a coisa pronta.
+  -- Não altera o vencimento legal: acrescenta um prazo interno ao lado dele.
+  internal_lead_days int CHECK (internal_lead_days IS NULL OR internal_lead_days BETWEEN 0 AND 90),
+  enabled       boolean NOT NULL DEFAULT true,
+  note          text,
+  updated_by    uuid REFERENCES "user"(id),
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT tenant_rule_policy_tenant_id_uq UNIQUE (tenant_id, id)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS tenant_rule_policy_uq
+  ON tenant_rule_policy (tenant_id, item_type_id);
+
+ALTER TABLE tenant_rule_policy ENABLE ROW LEVEL SECURITY;
+ALTER TABLE tenant_rule_policy FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_rule_policy_tenant_isolation ON tenant_rule_policy
+  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_rule_policy IS
+  'Procedimento do escritório, ao LADO da regra legal e nunca por cima dela. Prazo interno não é prazo legal.';
+
+-- ── 5 · Preservação histórica ──────────────────────────────────────────────
+--
+-- A instância já congela `label` e `due_date`. Falta saber QUAL versão da
+-- regra produziu aquela data — sem isso, uma V2 publicada amanhã faz a
+-- obrigação de ontem parecer ter nascido de uma regra que não existia.
+
+ALTER TABLE recurring_instance ADD COLUMN IF NOT EXISTS fiscal_rule_id uuid REFERENCES fiscal_rule(id);
+ALTER TABLE recurring_instance ADD COLUMN IF NOT EXISTS fiscal_rule_version int;
+
+COMMENT ON COLUMN recurring_instance.fiscal_rule_id IS
+  'Versão EXATA da regra que gerou esta obrigação. Publicar uma V2 não altera o que já foi gerado sob a V1.';

package/src/db/migrations/0050_fiscal_vocabulary_readonly.sql

@@ -0,0 +1,29 @@
+-- 0050 — o vocabulário do perfil fiscal é lido pelo runtime, nunca escrito.
+--
+-- Esta migration existe separada da 0049 por uma razão de processo, e vale
+-- registrar: eu havia acrescentado este bloco ao fim da 0049 depois de ela já
+-- ter sido aplicada. O runner recusou — migrations são imutáveis, e a checagem
+-- de hash existe exatamente para impedir que o que rodou num ambiente seja
+-- diferente do que roda no próximo.
+--
+-- ── A barreira ─────────────────────────────────────────────────────────────
+--
+-- `fiscal_attribute_definition` é catálogo GLOBAL, sem `tenant_id`. Não há RLS
+-- que o proteja, porque não há linha de ninguém: a barreira só pode ser o
+-- privilégio.
+--
+-- O runtime lê o vocabulário a cada avaliação de aplicabilidade e nunca o
+-- escreve. Um tenant capaz de inserir atributo aqui poderia criar um atributo
+-- que nenhuma regra usa (inócuo) ou — pior — apagar um que as regras de todos
+-- os escritórios usam, derrubando a avaliação do país inteiro por FK.
+--
+-- Repetido em `migrate.ts` no mesmo bloco de `role` e `audit_log`: o GRANT da
+-- allowlist é amplo por construção e devolveria a escrita no deploy seguinte.
+-- Foi o defeito que a Fase 3 encontrou ao separar GRANT de hardening.
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT FROM pg_roles WHERE rolname = 'baruk_app') THEN
+    EXECUTE 'REVOKE INSERT, UPDATE, DELETE ON fiscal_attribute_definition FROM baruk_app';
+  END IF;
+END $$;