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.

12 KiB Raw Blame History