SGF/docs/SGF_PAYABLE_REPORT_CAPTURE_DELIVERY.md

# Relatório financeiro — perfilagem e reutilização de captura validada

03/11/2026. Continuação técnica da [consulta de posições reconhecidas](SGF_PAYABLE_REPORT_DELIVERY.md), sem novo efeito financeiro ou direito. **Há código funcional de optimização**, além das rotinas de perfilagem. Não se repetiram as suites contabilísticas ou os benchmarks válidos de paginação de associações/documentos/pagamentos.

## Alteração implementada

O adaptador já validava integralmente cada recibo histórico na janela, mas devolvia só os pagamentos. O núcleo repetia `HistoricalPayments::capture` sobre esses mesmos pagamentos para comparar com a importação original. O relatório passa a pedir explicitamente um `HistoricalCapture` imutável, válido exclusivamente para aquela origem completa e contexto, reutilizando o resultado dessa primeira captura.

O recibo continua a passar pelo checksum, identidade/revisão, versão, validação integral de pagamentos e comparação do hash histórico. `PaymentDecisions::current` continua a reconstruir/verificar a importação original e as decisões. Não se retiraram verificações de auditoria, compatibilidade, montantes ou saldos. Os direitos e a pessoa continuam conferidos pelo percurso de leitura existente, sem cache de permissões.

O valor conserva a origem inteira, incluindo eventuais campos documentais chamados `revision` ou `missing`. Só aceita a origem original exacta ou a mesma origem com os metadados calculados exactos da listagem. Mudar ID local, quantidade de pagamentos, documento/versão, empresa/unidade/tenant ou esses metadados recusa a captura. A devolução do array não permite alterar o valor guardado. A janela termina sem retenção global dos valores.

**Comandos não usam estas capturas.** O núcleo recusa o valor quando o chamador não é o percurso de leitura conjunta; comandos conservam o carregamento e validação do histórico actual. O contrato anterior de `SupplierHistoryReceipts::page` continua a devolver arrays por omissão. Não se acrescentou parâmetro HTTP para optar por uma captura ou saltar validações.

## Ensaio e perfilagem

Nova base/role QA própria55439, `report-profile-b7f7d0c1c2c2`, restaurada de um dump só de leitura da fixture sintética de10.000 posições. Não se usou a base original para medições, escritas, manutenção ou decisões. Aproximadamente99,99% são cópias explícitas de volume do cenário original, não10.000 workflows de compras. Dump, configurações, credenciais, classe anterior arquivada e classes instrumentadas ficam privados.

Cada geração usa100 janelas de100 fontes, processos PHP independentes, limite512M e o mesmo contexto/filtro. A instrumentação está numa cópia privada da classe, sem opção de perfilagem na aplicação. Os tempos por etapa são de relógio e incluem as consultas dessas etapas; não se devem somar novamente os tempos SQL ao total. A actividade local não foi controlada; existe uma amostra por versão/condição. Não são resultados de carga sustentada ou de implantação.

| Implementação e condição | Tempo ms | Consultas | Pico heap PHP MiB | Selecção ms | Históricos ms | Posições ms | Hash/totais ms |
|---|---:|---:|---:|---:|---:|---:|---:|
| Anterior, restauro recente antes de ANALYZE |21548,229|2313|34|5920,125|3050,887|11710,591|424,818|
| Anterior, depois de ANALYZE só na cópia QA |22021,190|2313|34|2260,387|4136,342|14460,816|692,097|
| Captura reutilizada, mesmas estatísticas QA |12939,629|2313|34|1603,575|2902,426|7764,687|317,408|

O `EXPLAIN ANALYZE` anterior revelou um plano que estimava1 linha e processava10.000 antes de ordenar/limitar100, com60.185 blocos partilhados encontrados em cache e nenhum lido do disco nesse pedido. Actualizar estatísticas reduziu o tempo observado de selecção, **sem melhoria do total nessa amostra**. É um efeito de estatísticas, não de índice ou da captura reutilizada. A manutenção foi aplicada exclusivamente à cópia sintética nova; não é uma recomendação de aplicação automática no destino.

Entre a segunda e terceira linhas observou-se redução de cerca de41% no tempo total, com consultas/memória iguais e conteúdo financeiro idêntico. A alteração de código remove a captura duplicada; a variação local e a diferença dos tempos SQL impedem atribuir causalmente todo o ganho a essa única operação. Uma medição intermédia com a primeira implementação do vínculo da captura ficou diagnóstica e não é usada como resultado final; o vínculo foi reforçado para conservar campos documentais genuínos antes da medição final.

O gargalo **persiste**:12,9 segundos ainda é elevado para consulta interactiva. A etapa de posições ainda consome7,8 segundos, incluindo SQL, hidratação, reconstrução/verificação da importação e decisões, comparação e captura de resultados. O total SQL foi5,5 segundos e está incluído nas etapas. A próxima correcção mínima deve subperfilar essa etapa e o plano de selecção com estatísticas representativas, antes de escolher mais cache, índices ou geração assíncrona. Não se retiram validações apenas para reduzir o benchmark. Não houve índice experimental, índice no destino ou avaliação de throughput.

## Equivalência, recusas e preservação

-6 cenários/22 verificações em rollback: vínculo completo ao contexto/origem, metadados genuínos, imutabilidade, recusa da captura nos comandos, compatibilidade do contrato de arrays, igualdade de totais/componentes/hash/janelas, recibo inválido com saldo indeterminado e direito revogado.
-17 verificações HTTP reais na nova cópia:10.000 posições, foco, HTML/JSON, links de evidência, parâmetros indevidos, fonte/contexto inválidos, escape e `no-store`. Fotografia `REPEATABLE READ READ ONLY`, zero `FOR UPDATE`. Não são provas visuais.
-Comando efectivo `prepare_history` e repetição pelo motor normal, sobre a obrigação já reconhecida, devolvem o reconhecimento original sem outra obrigação. Prova revertida integralmente; o valor de janela não alimenta esse comando.
-Após medições e casos, a impressão digital financeira da cópia coincide com a prova válida original. A classe anterior arquivada e as provas/demos/pacotes antigos mantêm os seus hashes. Nenhum dado real ou associação protegida foi usado para este ensaio.

Os39 checks contados são22 de regressão e17 HTTP; o comando/repetição é registado como prova adicional, sem inventar outra contagem. Manifesto: [medições, igualdade e hashes](proofs/sgf-payable-report-capture-20261103.json). Originais, seis associações, cache bloqueada, demos e trabalho em curso preservados. Sem publicação, checkpoint, activação de Compras, concessões ou manutenção no destino. Revisão visual, carga sustentada e implantação continuam separadas e pendentes.

## Próxima integração proposta

A correcção de resultado industrial já lançado continua expressamente excluída da autorização actual. Foi preparado um recorte concreto [1800→1820, por par indivisível](GENERAL_LEDGER_INDUSTRIAL_CORRECTION_SCOPE.md), ainda só para decisão. A optimização de leitura desta entrega não autoriza esse novo efeito.