# Governação de versões de regras fiscais ## Correcção de controlo — decisão expressa da Tempo,21/10/2026 A manutenção dos parâmetros fiscais reutiliza a administração já autorizada, com autenticação/MFA, fonte, versão, responsável e histórico. Uma mesma pessoa pode concluir `submit` → `review` → `approve` → `publish`; esses estados preservam o percurso técnico e os eventos, sem afirmar independência pessoal ou parecer jurídico. As quatro listas específicas de permissões permanecem opcionais. A utilização do simulador pelo investidor conserva as permissões e os limites próprios, separados da manutenção. A obrigação de actores distintos foi encontrada no serviço fiscal e nosCHECKs da migration de03/10/2026, incorporados em `e65cb269` (06/10/2026), e descrita como implementação em `simulator-evolution-progress.md`. Não foi localizada uma decisão expressa da Tempo ou requisito aplicável que a imponha ao cadastro fiscal. A origem identificada é escolha de implementação; a autoria ou integração do commit não demonstra aprovação dessa regra organizacional. A decisão actual da Tempo manda removê-la neste fluxo, sem alterar a independência acordada nas oportunidades, perfis ou outros processos. A correcçãoQA retira apenas as comparações de identidade entre autor/revisor/aprovador/publicador dos controlos fiscais; mantém campos obrigatórios, evidência, datas, etapas, versão optimista, fonte, bloqueios, RLS e eventos imutáveis. Para cadastrar uma fonte oficial neste percurso existe `POST /api/v2/investment/admin/tax-rule-sources`, sob a mesma administração autenticada. Recebe os metadados existentes mais `sha256`, `citation` e `official_origin`; regista a aceitação da fonte oficial segundo a decisão Tempo de08/10/2026, o responsável real e a indicação explícita de que não é parecer jurídico nem revisão independente. O hash da regra tem de coincidir com o exemplar cadastrado. A fonte permanece pending no estado geral: a aceitação fiscal não a valida para outros módulos. A projecção pública e o resolvedor fiscal reconhecem esse fundamento e o hash correspondente, sem alterar a fórmula. A fonte não activa nem publica uma regra automaticamente. A validação normal de fontes para os outros processos mantém o seu controlo; não se alteraram os workflows de oportunidades/zonas/perfis. Migration de correcção: `2026_10_21_130000_correct_fiscal_maintenance_actor_constraints.php`, protegida contra execução fora deQA isolado. Acrescenta metadados de aceitação fiscal à fonte e corrige osCHECKs que impediam o actor único. Foi ensaiada apenas emQA, com6testes/86asserções do controlo alterado, sem cálculo, build ou repetição dos testes aritméticos/exportadores. O manual consolidado regista provas e procedimento actualizado das três operações. Os estados históricos abaixo descrevem o incremento original e não reabrem as provas já aceites da candidata226fd308. ## Âmbito deste incremento Foi criado um fluxo administrativo para registar uma versão declarativa de regra e a sua referência jurídica. O fluxo existe separado do motor de cálculo. Nenhum endpoint de simulação consulta `simulation_tax_rule_versions`; `published` significa apenas publicada no registo interno de governação, não activa no produto nem aprovada para aconselhamento fiscal. O registo guarda componente, `scope_key`, vigência, definição JSON, parâmetros JSON, política de arredondamento, fonte, versão da fonte, SHA-256 declarado pelo editor e autor/revisor/aprovador/publicador. Existe um avaliador interno para a DSL `investmoz.tax.v1`, com whitelist, validação de DAG sem ciclos, aritmética exacta e arredondamento explícito. O avaliador ainda não está ligado ao fluxo de cálculo fiscal `RunSimulation`; por isso, a presença de uma expressão ou a publicação administrativa de uma regra não activa um cálculo fiscal no produto. ## Fluxo `draft → submitted → reviewed → approved → published → suspended/archived` - Rejeição ocorre a partir de `submitted`; a regra rejeitada não pode ser editada. Uma correcção requer nova versão. - O autor não pode rever, aprovar ou publicar a própria versão. Revisor, aprovador e publicador têm identidades distintas. - Cada transição exige evidência textual, incrementa `version_no` com controlo optimista e grava snapshot/hash append-only. - A fonte tem de estar validada, cobrir a vigência completa e conservar a mesma versão na submissão, revisão, aprovação e publicação. A revogação ou alteração da fonte bloqueia transições subsequentes. - O mesmo código/componente/`scope_key` não pode ter duas versões publicadas com vigência sobreposta. Há lock transaccional e trigger PostgreSQL para preservar esta regra sob concorrência. - Respostas administrativas são privadas, `no-store`, exigem gestor verificado, MFA confirmado e allowlist por papel. Os quatro grupos de emails ficam vazios por defeito: `INVESTMOZ_TAX_RULE_EDITORS`, `INVESTMOZ_TAX_RULE_REVIEWERS`, `INVESTMOZ_TAX_RULE_APPROVERS`, `INVESTMOZ_TAX_RULE_PUBLISHERS`. - RLS `FORCE` cobre versões e eventos. O serviço só define o contexto transaccional após autenticação e autorização. Eventos têm trigger que recusa UPDATE/DELETE. ## Limites e gates O campo `source_sha256` é evidência declarada e revista por pessoa competente; este incremento não descarrega, arquiva nem compara automaticamente o ficheiro legal. O esquema actual de `investment_legal_sources` não prova a integridade de um exemplar armazenado. A URL, o artigo e o hash têm de ser conferidos externamente, e o pacote oficial deve ser arquivado antes de aprovar regras reais. Continuam pendentes para cada cálculo fiscal executável: consolidação legível/autenticada dos artigos e anexos aplicáveis, ligação das regras ao fluxo de cálculo com explicabilidade e snapshot, definição aprovada dos casos de referência e validação do resultado esperado por cenário. A DSL, o avaliador DAG, a aritmética exacta e o resolvedor temporal existem e têm testes; isso não prova a semântica fiscal das fórmulas nem substitui os casos de referência. A execução integrada de RLS foi testada num papel PostgreSQL não privilegiado em QA descartável. Parâmetros ausentes continuam indeterminados e nenhuma taxa/regra está activada como cálculo fiscal de produção. ## Rollback A migration `2026_10_03_170000_create_simulation_tax_rule_governance.php` é aditiva. `down()` recusa rollback se houver versões ou eventos; primeiro exportar e preservar o registo por procedimento aprovado. Nenhuma migration anterior, regra fiscal, snapshot de simulação ou resultado histórico foi alterado. ## Evidência técnica — governação fiscal (2026-10-03) O registo versionado e o fluxo administrativo foram implementados em `simulation_tax_rule_versions` e `simulation_tax_rule_events`, com RLS FORCE, eventos append-only, controlo optimista, segregação editor/revisor/aprovador/publicador, validação de fonte e prevenção de vigências publicadas sobrepostas. Rotas administrativas exigem gestor verificado, MFA e allowlist por papel, vazia por defeito. A projecção pública de parâmetros lê apenas campos permitidos e filtra fonte, período, `scope_key` e contexto. O formulário usa essa projecção para mostrar estado, valor e fonte; `RunSimulation` ainda não executa as regras fiscais governadas. PHP 8.5.11: teste dirigido `SimulationTaxRuleGovernanceTest` — 4/4, 52 asserções; com a regressão do rollback fundacional `InvestmentZoneTest::test_rollback_refuses_populated_foundation_and_empty_rollback_is_reversible` — conjunto 5/5, 56 asserções. Pint passou. Suite Laravel integral — 228/230; só falharam as duas falhas conhecidas de `EducationTest` (fixture sem `province_id`; expectativa Inertia incompatível). A integração decorreu em PostgreSQL 17/PostGIS descartável, papel `investmoz_test_runner` sem SUPERUSER; testes confirmaram que RLS oculta os registos sem contexto autorizado. Aviso anterior `use Throwable` em `bootstrap/app.php` permanece. **Gate proposto: PARCIAL para infraestrutura; BLOQUEADO para cálculo fiscal integrado.** A DSL, DAG, precisão, arredondamento explícito, resolução temporal e projecção pública de parâmetros estão implementados e testados. A revisão profissional foi declarada pelo proprietário e a autorização/validação foi expressamente concedida pelo utilizador; esta declaração não substitui parecer ou certificado nominal arquivado. Ainda falta ligar regras fiscais com proveniência suficiente ao cálculo, e conferir os cenários de referência independentemente do próprio motor. A migration foi aplicada apenas em QA descartável nesta evidência; não há afirmação de aplicação local/operacional. ## Atualização — parâmetros e vigência (2026-10-03) Uma nova versão de regra fiscal pode preservar a mesma AST e mudar somente `parameters`; esses valores são aprovados/publicados como parte da versão imutável com unidade, condições, `scope_key`, vigência, diploma/artigo/fonte e estado da fonte. O resolvedor `SimulationTaxParameterResolver` filtra versão publicada, fonte ainda validada na mesma versão, âmbito e data; ausência, condições não satisfeitas ou múltiplas correspondências são indeterminadas. Para parâmetros personalizados, o utilizador deve criar nova versão de regra, sem editar a versão histórica. A UI distingue simulação fiscal com parâmetros aprovados, cenário personalizado de planeamento e sem cálculo. O primeiro não pede taxa manual; o segundo pede pressupostos apenas no painel específico e não bloqueia a navegação/rascunho incompleto. O endpoint genérico conserva resultados identificados como `custom_planning`. **Nota histórica (2026-10-03, substituída pela implementação posterior):** nessa data, o resolvedor ainda não tinha acesso público. A implementação posterior acrescentou o endpoint de projecção pública mínima e a interface passou a consultar estado, valor e fonte dos parâmetros. A projecção não executa fórmula fiscal e não alimenta `RunSimulation`; portanto, continua correcto manter o cálculo fiscal indeterminado até existir integração e regra validada. Resultados/snapshots históricos não foram reescritos. Fonte declarada/hash, sem comparação de exemplar oficial, continua insuficiente para activar regra legal. ### Estado reconciliado — 2026-10-04 - Existe DSL `investmoz.tax.v1` com whitelist, DAG acíclico, aritmética `BigRational` e arredondamento explícito; existem testes unitários para precisão, arredondamento, referências desconhecidas, ciclos e entradas em falta. - Existe `SimulationTaxParameterResolver`, que resolve versões publicadas por período, `scope_key`, contexto e fonte validada, devolvendo indeterminação quando falta ou há ambiguidade. - `POST /api/v1/tax-parameters/resolve` expõe apenas uma projecção mínima; o formulário mostra parâmetros/fontes elegíveis. Esta API não devolve a DSL. - O serviço de execução de simulação ainda não invoca o avaliador para calcular IRPC, IVA, ISPC, IRPS, INSS, retenções, ICE ou direitos aduaneiros. A aritmética genérica personalizada permanece cenário de planeamento, não cálculo fiscal. - O utilizador declarou que contabilista/fiscalista reviu e validou o simulador e autorizou formalmente a matriz/regras; isto é registado como declaração e autorização do proprietário. O compromisso OCAM localizado refere-se somente ao Modelo 20 da empresa. Não há neste acervo parecer individualizado dos casos dourados do simulador. - **Estado:** infraestrutura fiscal parcial testada; activação de regras/cálculo continua pendente por componente até fontes e cenários serem conferidos e ligados ao motor. A falta de um parecer separado não impede continuar programação e testes neutros.