Requisição 170 — `ForcarAtualizacaoTest` não é idempotente e produz falhas fantasma

Achado durante a validação da req-169, em 18/09/2026. A suíte do núcleo passa numa execução limpa e falha na execução seguinte, sem que nenhuma linha de código tenha mudado. O efeito é pior do que o incômodo: depois de qualquer falha real, a próxima rodada acusa duas falhas adicionais que não existem, e quem está investigando perde tempo atrás de um defeito inventado.

1. Diagnóstico

• schemaMetadata() (gestor/controladores/atualizacoes/atualizacoes-banco-de-dados.php:275) guarda o conteúdo lido em static $meta e devolve o cache em toda chamada seguinte do processo. Em produção o arquivo nunca muda durante a execução, então o cache é correto.

• ForcarAtualizacaoTest tem três testes, e cada um escreve o seu próprio schema-metadata.json no mesmo diretório temporário. Como o cache é preenchido na primeira chamada do processo, o primeiro teste a rodar fixa o contrato para todos — os outros dois exercitam metadados que não são os seus.

• O PHPUnit grava .phpunit.result.cache e, na execução seguinte, reordena os testes colocando primeiro os que falharam ou demoraram. É essa reordenação que muda qual teste preenche o cache e, portanto, quais testes quebram.

Reprodução: php vendor/bin/phpunit tests/Unit/PHP/ForcarAtualizacaoTest.php duas vezes seguidas — a primeira passa, a segunda falha. Com --do-not-cache-result, passa sempre.

2. Escopo

• schemaMetadata() passa a aceitar recarga explícita, mantendo o cache como padrão para não alterar o comportamento em produção nem o custo de leitura no pipeline.

• ForcarAtualizacaoTest recarrega o contrato depois de escrever o seu schema-metadata.json, de modo que cada teste exercite os próprios metadados.

• O resultado não pode depender da ordem de execução nem de .phpunit.result.cache.

3. Critérios de Aceitação

1. Idempotência: a suíte passa em duas execuções seguidas, sem apagar .phpunit.result.cache.

2. Independência de ordem: os três testes passam isolados e em qualquer ordem.

3. Produção intacta: sem recarga explícita, schemaMetadata() continua servindo do cache.

4. Sem regressão: suíte do núcleo verde.