SGF/docs/NATIVE_PAYABLE_PAGED_READ_DELIVERY.md

# Consulta financeira paginada no SGC autónomo

02/11/2026 — `NATIVE-PAYABLE-PAGED-READ-SIM-v1`. Código local e provas exclusivamente sintéticas. Continuação da [leitura conjunta SGF](SGF_PAYABLE_PAGED_READ_DELIVERY.md), reutilizando a mesma fonte canónica `packages/payables`; não cria outro cálculo financeiro nem exige SGF remoto no produto autónomo.

## Implementação

O adaptador nativo passa a ter consulta paginada sobre as suas próprias facturas, linhas, validações e pagamentos originais. Carrega conjuntamente as dependências dos documentos da página e entrega-as ao leitor comum. Não carrega todas as facturas para depois recortar a página. Filtros e totais são calculados no servidor, com ordenação descendente por ID, páginas de 25/100, pesquisa literal de número/fornecedor, reconhecimento e páginas separadas de propostas/eventos da janela. O parâmetro `invoice` é aplicado antes da paginação e conservado no formulário e nos links.

Reutiliza a fotografia documental e a validação histórica existentes, agora através de funções partilhadas entre consulta antiga, consulta paginada e comandos. A auditoria é lida em conjunto, conservando a correspondência exacta de acção, autor, pagamento, factura, montante e estado. A consulta não lê dados bancários cifrados. Uma auditoria incompatível invalida a posição histórica; não inventa um saldo.

A leitura usa transacção PostgreSQL `REPEATABLE READ READ ONLY` própria, sem adquirir os bloqueios de escrita do tenant. Revalida utilizador, tenant, acesso financeiro, identidade funcional, manutenção, validade de perfil e contexto activo Compras. Pessoas não herda permissões financeiras de outro contexto. Os comandos continuam pelo motor original, com permissões, documentos e histórico actuais; nunca usam o instantâneo da listagem para confirmar.

Configuração nova `common-payables.paged_read_enabled=false` por defeito. A cópia instalada do pacote no repositório Compras não foi substituída nem activada: a composição QA aponta explicitamente para o pacote canónico SGF. Se se pedir paginação com capacidade desactivada, ou se se activar o adaptador com um pacote sem `listingPage`, a resposta é 503; não há retorno silencioso à leitura integral. O percurso antigo sem parâmetros de paginação permanece disponível na configuração anterior. Não foram criados direitos ou migrações operacionais.

## Comparativo medido

Uma factura proveniente do workflow nativo efectivo: 60 MZN de principal, 30 confirmados, 10 pendentes, 5 rejeitados, posição reconhecida de 30 MZN. Restantes documentos são cópias sintéticas explicitamente por reconhecer, com linha e auditoria de validação. As primeiras páginas excluem a factura original, mais antiga. Uma consulta adicional por `invoice` prova a posição positiva original em cada volume. **Este conjunto não representa 10.000 dívidas reconhecidas** e difere do conjunto SGF anterior.

| Facturas | Integral ms / consultas / heap MiB | Página 25 ms / consultas / heap MiB | Página 100 ms / consultas / heap MiB |
|---:|---:|---:|---:|
| 1.000 | 17.059,737 / 8.060 / 32 | 171,758 / 76 / 28 | 192,259 / 76 / 28 |
| 5.000 | 74.118,294 / 40.060 / 48 | 124,051 / 76 / 28 | 127,190 / 76 / 28 |
| 10.000 | 122.903,707 / 80.060 / 62 | 75,117 / 76 / 28 | 91,089 / 76 / 28 |

A pesquisa da factura original fez 79 consultas e demorou 113,647 / 91,986 / 72,009 ms nos respectivos volumes, sempre com 28 MiB e posição 30 MZN. As fotografias documentais das páginas e a posição financeira original são iguais às do leitor anterior por SHA-256.

Condições equivalentes: mesma base sintética por volume, PHP 8.4.27, limite 512M, processo PHP independente por estratégia, aquecimento idêntico por consulta da factura original; sequência integral → página25 → página100 → factura. Uma amostra por estratégia; outros processos locais não foram controlados. Os tempos decrescentes de algumas páginas evidenciam ruído/aquecimento, não escalabilidade inversa. Memória é pico de heap PHP alocado, não RSS; base do framework 28 MiB. **Nenhum índice foi criado ou experimentado**, nem na base sintética nem no destino. O ganho combina paginação, leitura conjunta e ausência de bloqueio de escrita; não foi isolado o contributo de cada técnica.

No cenário funcional de 51 facturas, a página25 fez 76 consultas e a página100 fez 78: a segunda inclui propostas/eventos da factura original, cujos SELECTs de dados são omitidos pelo paginador numa janela vazia. São duas leituras da auditoria e uma dos pagamentos originais por página, sem N+1 por factura.

## Provas consolidadas

- Nove testes novos, 113 asserções: filtros/totais/páginas disjuntas, paridade antiga/nova, factura específica, literal de pesquisa, ausência de N+1, auditoria alterada, tenant indevido, revogação, perfil expirado, manutenção, contexto Pessoas, compatibilidade desactivada e pacote antigo.
- 26 casos distintos de compatibilidade afectados, 183 asserções. Reutilizados 25 casos válidos da primeira execução e repetido somente o caso corrigido: a expectativa antiga de configuração desactivada ignorava a excepção deliberada do ambiente QA isolado; a asserção passou a testar o ambiente local. A regra de produção não mudou. Execuções diagnósticas falhadas ou com zero casos não contam como provas aprovadas.
- Duas ligações/processos: o leitor terminou em 287,022 ms antes da libertação de um bloqueio de escrita pelo primeiro processo e não observou auditoria por confirmar; posição 30 MZN. Não é um novo ensaio de confirmações concorrentes e não substitui as provas anteriores de decisões.
- 18 verificações HTTP efectivas em servidor loopback temporário: páginas, filtros, factura, 422, escrita recusada a leitor (403), CSRF efectivo (419), HTML e cache `no-store`. Não houve navegador nem revisão visual.
- PHPStan nível7 nos três ficheiros de produção afectados: zero erros. Formatação e sintaxe verificadas. Não se repetiram suites alheias ao incremento.
- Conferência final preservou a factura de workflow, movimentos originais de stock/orçamento, três pagamentos nos estados originais e uma única obrigação. A flag de paginação do destino continua falsa.

Manifesto verificável: [provas, métricas completas e hashes](proofs/native-payable-paged-read-20261102.json). Artefactos privados e credenciais de QA ficam fora do repositório. `scripts/summarize-native-payable-page.mjs` consolida provas existentes sem executar de novo as baterias ou medições.

## Limitações e continuidade

O gargalo da leitura integral era percorrer todas as facturas e voltar a consultar origens/auditorias por documento. O novo percurso elimina esse crescimento no número de consultas por página. Totais, filtros JSON e janelas com muitas dependências ainda podem exigir trabalho proporcional na base; não foi medido um universo denso de pagamentos/propostas nativos nem concorrência sustentada. Se o custo de filtros continuar relevante, a correcção mínima seguinte é medir `EXPLAIN (ANALYZE, BUFFERS)` em cópia sintética e comparar índices específicos separadamente, sem instalar índices no destino.

Origem histórica viva foi comprovada na composição nativa QA. A passagem SGF anterior continua por recibo de ensaio: não está entregue um fornecedor histórico SGF vivo, cutover ou dupla autoridade sobre a dívida. Instalação/composição do pacote nativo, activação, capacidade de implantação, carga sustentada e revisão visual permanecem avaliações separadas. Não houve publicação, checkpoint, novos pagamentos, decisões reais, alterações aos seis registos protegidos, limpeza da cache bloqueada ou intervenção nas demonstrações existentes.