# APIX001 abril/2026: batimento com a semantica oficial v2.6 (Task C1b)

Data: 2026-07-19. Task C1b do plano mestre `docs/plans/2026-07-19-plano-mestre-fechamento-frentes.md` (ADENDO 19/07). Substitui o relatorio anterior desta mesma trilha (`2026-07-19-apix-abril-numeros-corretos-e-dossie-retificacao.md`, renomeado por git mv para este arquivo) e SUPERA a tese "legado subnotificou" do batimento da madrugada (`docs/reports/2026-07-19-batimento-apix042026-vs-restore-autbank.md`, que recebeu nota de errata no topo). A errata detalhada esta na secao 4.

Tudo desta entrega e LOCAL: restore mssql (`monetarie-bak-mssql`), Postgres local (`monetarie-pg`, porta 15432 conferida como OrbStack via lsof, nao tunel SSM), gerador oficial do core rodado por `mix run --no-start`. Zero toque em HML/PRD/AWS.

## 1. A semantica oficial (fonte primaria, conferida nesta sessao)

Fonte: instrucao de preenchimento oficial do APIX001 versao 2.6, planilha `APIX001_2-6.xlsx` baixada do BCB em 2026-07-19 (Task A5) de:

    https://www.bcb.gov.br/content/estabilidadefinanceira/pix/Remessa_informacoes_Pix/APIX001_2-6.xlsx

sha256 do arquivo baixado: `5dacb41b4b50300f713cdef8e99d768479eb68833423b7729cb46c0f439ab273` (as duas copias no scratchpad da sessao, a do download e a da revisao adversarial, tem o MESMO hash). As citacoes abaixo foram re-extraidas NESTA sessao do `xl/sharedStrings.xml` da propria planilha (indice da string entre colchetes) e conferem literalmente com o que a A5 gravou nos moduledocs do gerador (`aggregator.ex`, `generator.ex`, commit `32da38b8`).

Tabela 1 do Anexo (Detalhamento das Transacoes), literal:

- codigo 5 [237]: "Transações liquidadas pelo Liquidante referente a transações de participantes indiretos, sem cursar pelo SPI. Informação deve ser prestada apenas pelo Liquidante."
- codigo 6 [238]: "Transações liquidadas pelo próprio participante que não cursaram pelo SPI, envolvendo seus próprios clientes."
- codigo 7 [239]: "Transações que cursariam no SPI ou fora do SPI mas foram rejeitadas pelo PSP do usuário Pagador após tratamento por suspeita de fraude. Informação deve ser remetida pelo PSP do usuário Pagador."
- codigos 1 a 4 [230, 232, 234, 236]: "(descontinuado)".

QtdConsultas (grupo ConsultasDict), literal [209]: "Quantidade de consultas destinadas à efetuação de transações Pix resolvidas na cópia do DICT do participante, sem que o próprio DICT tenha sido consultado."

Historico de versoes, v1.0.2 [281-282], literal: "Esclarecimento de que as transações mencionadas nos campos 'Quantidade de transações' e 'Montante financeiro das transações' são aquelas iniciadas por determinada instituição."

Consequencias (as mesmas provadas por teste na A5):

1. O grupo Transacoes cobre SOMENTE liquidacao FORA do SPI. Transacoes que cursaram pelo SPI nao entram em NENHUM balde: o BCB as recebe do proprio SPI.
2. O balde 5 e privativo do Liquidante de participantes indiretos. A Monetarie nao e Liquidante: balde 5 = zeros (o XSD exige as 12 linhas, zeros validos).
3. O balde 6 = fora-SPI entre clientes proprios (as 5 internas de abril).
4. QtdConsultas NAO e "consultas ao DICT": e consulta resolvida na copia LOCAL sem ir ao DICT. As 604 consultas do restore FORAM ao DICT (tabela `DICT_CONSULTA` com status HTTP de resposta do DICT) e portanto nao servem de fonte para esse campo.

## 2. O arquivo v2 gerado (gerador oficial corrigido + overrides do operador)

Gerado nesta sessao por `scripts/apix_abril/generate_apix_local.exs` sobre a MESMA projecao validada da C1 (que permanece correta: ela projeta o acervo, nao decide taxonomia), agora com o `Cadoc1201` corrigido pela A5 (commit `32da38b8`) e a API `Aggregator.aggregate_and_upsert/3` com os parametros do operador:

- Arquivo: `scripts/apix_abril/out/APIX042026-v2-semantica-oficial.xml` (6.420 bytes)
- sha256: `90dda5dca81cdb3c23ba94c7af569b93883de18fccd51db8f65ae48a5df4dceb`
- Validacao: xmllint contra `core/backend/priv/schemas/APIX001_2-6.xsd` = "validates"
- Snapshot upsertado com `tipo_envio=I`, `disponibilidade_bp=9845`, `consultas_dict=80` (saida do proprio script)

O arquivo v1 da C1 (balde 5 com 243 pix, QtdConsultas 604), gerado com a taxonomia DEFEITUOSA anterior, foi renomeado por git mv para `scripts/apix_abril/out/APIX042026-v1-NAOTRANSMITIR.xml` e fica como historico auditavel. Ele NAO pode ser transmitido em hipotese nenhuma.

### Overrides do operador aplicados e por que espelhar o legado e o honesto aqui

Tres campos vieram do arquivo do legado por override explicito (`tipo_envio`, `disponibilidade_basis_points`, `consultas_dict_qtd`). A justificativa, campo a campo:

- `tipo_envio = "I"`: o arquivo do legado estava CORRETO nos baldes (secao 3); este v2 nao e retificacao de nada, e a prova de que o nosso gerador oficial reproduz a competencia. "S" so entraria se o dono decidisse retificar (secao 5).
- `disponibilidade_basis_points = 9845` (98.45): o IndiceDisponibilidade e medicao OPERACIONAL do participante (secao 4.3 do Manual de Tempos do Pix, citacao [217] da planilha). O legado operava o sistema em abril e mediu 98.45; o restore nao carrega essa medicao e nos nao temos como medi-la retroativamente. Inventar 100.00 (default) seria declarar disponibilidade que ninguem mediu; espelhar a medicao de quem operou e o unico valor com lastro.
- `consultas_dict_qtd = 80`: pela definicao oficial [209], o campo conta consultas resolvidas na copia LOCAL do DICT sem consultar o DICT. So o sistema do legado sabia quantas resolveu localmente; as 604 do restore foram AO DICT (fonte errada para este campo). O 80 do legado e a unica medicao existente da grandeza oficial; espelha-lo e o honesto.

O que NAO recebeu override: receita fonte 1 (o gerador computou das fees projetadas = 0.00; a origem do 586.03 do legado segue desconhecida, secao 3) e os tempos DICT (medicoes operacionais do legado sem fonte no core e sem override na A5; divergencia documentada na tabela).

## 3. Batimento celula a celula: arquivo do legado vs arquivo v2 nosso vs restore

Arquivo do legado: `~/Desktop/APIX042026.xml` (AutBank, TipoEnvio I, transmitido na epoca). Restore: consultas da C1/batimento da madrugada, todas re-verificadas pela projecao (verificacao pos-insert do script fecha ao centavo).

| Campo / celula | Legado | v2 nosso | Restore (verdade) | Veredicto |
|---|---|---|---|---|
| Transacoes 5/1..5/4 (qtd, valor, especie) | 0 em tudo | 0 em tudo | 243 pix via SPI existem, mas NAO entram (semantica oficial: balde 5 e do Liquidante; via-SPI fora do grupo) | COINCIDE |
| Transacoes 6/1 qtd | 5 | 5 | 5 internas aprovadas | COINCIDE |
| Transacoes 6/1 valor | 804000 | 804000.00 | R$ 804.000,00 ao centavo (extrato, perna D) | COINCIDE |
| Transacoes 6/1 especie | 0 | 0.00 | 0 (o Pix Saque de R$ 650,00 e transacao EXTERNA via SPI, fora do grupo) | COINCIDE |
| Transacoes 6/2..6/4 | 0 | 0 | 0 | COINCIDE |
| Transacoes 7/* (fraude) | 0 | 0 | sem fonte de rejeicao por fraude no restore; 0 | COINCIDE |
| Devolucoes 1 e 2 | 0 | 0 | 0 (provado: sem INDDEVOLUCAO, sem E2E original) | COINCIDE |
| Bloqueios cautelares 1..4 | 0 | 0 | sem tabela de bloqueio cautelar nos backups | COINCIDE |
| Receita fonte 1 | 586.03 | 0.00 | nao derivavel destes backups (fees projetadas = 0; acervo `mon_core.account_entries` de abril = 0 linhas, provado no batimento da madrugada) | DIVERGE; origem do 586.03 desconhecida (core AutBank/monbank, fora destes restores) |
| Receitas fontes 2..4 | 0 | 0 | sem fonte | COINCIDE |
| TemposTransacoes SPI p50 / p99 | 3.34 / 7.22 | 3.34 / 7.22 | percentile_disc das duracoes INICIO ate FINAL das 243 pix: bate EXATO | COINCIDE (tempos SPI sao grupo proprio do leiaute e seguem legitimos mesmo com os baldes zerados) |
| TemposTransacoes fora-SPI p50 | 1.02 | 1.27 | percentile_disc sobre {0.833, 0.840, 1.267, 1.273, 1.387} = 1.27 | DIVERGE; metodo de percentil do legado indeterminado (1.02 nao e reproduzivel por disc sobre as duracoes reais); o nosso e defensavel pela formula documentada |
| TemposTransacoes fora-SPI p99 | 1.39 | 1.39 | disc = 1.387 -> 1.39 | COINCIDE |
| TempoMaxBloqueioCautelar | 0.0 | 0.00 | 0 | COINCIDE |
| TemposDict (consulta 1.81, registro 1.55, exclusao 1.15, notif portab 0.3, envio portab 1.4) | preenchidos | 0.00 em tudo | medicoes operacionais do legado; p99 de consulta derivado do restore = 1.90 (1901 ms) diverge inclusive do 1.81 declarado | DIVERGE; sem fonte no core e sem override na A5; lacuna documentada (item 6.4) |
| ConsultasDict QtdConsultas | 80 | 80 | 604 foram AO DICT (fonte errada para o campo); a grandeza oficial (resolvidas na copia local) so o legado mediu | COINCIDE por espelhamento honesto (override); verdade independente indisponivel |
| Disponibilidade | 98.45 | 98.45 | medicao operacional do legado, nao derivavel do restore | COINCIDE por espelhamento honesto (override) |
| TempoAutorizacoes / Autorizacoes | 0 / zeros | 0.00 / zeros | 0 | COINCIDE |
| Responsavel (NomeResp/Email/Tel) | MURILO DE MELLO BAYER | default institucional do gerador | cadastro, nao transacional | DIVERGE; irrelevante para o batimento (em geracao futura vem do metadata da entity ou env `CADOC1201_RESP_*`) |
| TipoEnvio | I | I | n/a | COINCIDE |
| Formatacao | `Mes="4"`, valores sem casas (`804000`, `0`) | `Mes="04"`, valores com 2 casas (`804000.00`, `0.00`) | n/a | ambos VALIDAM no XSD 2.6 (xmllint); diferenca cosmetica |

Resumo: com a semantica oficial aplicada, TODOS os baldes de transacao, devolucao, bloqueio e autorizacao COINCIDEM entre o arquivo do legado e o nosso gerador oficial, ao centavo. As divergencias remanescentes sao: receita fonte 1 (586.03 de origem desconhecida), p50 fora-SPI (metodo de percentil), tempos DICT (medicao operacional sem fonte nossa) e responsavel (cadastro). Nenhuma delas sustenta tese de subnotificacao.

## 4. ERRATA da tese anterior (datada, sem apagar a historia)

**O que os relatorios de 19/07 (madrugada e manha) afirmaram**: que o arquivo do legado "subnotificou" abril/2026 por declarar ZERO no balde 5 (que liamos como "via SPI", contra 243 reais) e 80 consultas DICT (contra 604 no acervo); o dossie chegou a preparar retificacao TipoEnvio S.

**Por que a tese caiu (2026-07-19, revisao adversarial da C1 com a fonte primaria)**: a instrucao oficial de preenchimento do BCB (secao 1) prova que o balde 5 nunca foi "via SPI": e privativo do Liquidante de participantes indiretos, e transacoes que cursaram pelo SPI nao entram em NENHUM balde do grupo Transacoes. O erro de taxonomia era NOSSO, no `Cadoc1201` do core (balde 5 contando pix via SPI) e tambem na taxonomia da cabine; foi corrigido na Task A5 (commit `32da38b8`) com suite propria. Nas consultas, a definicao oficial de QtdConsultas (copia local, sem ir ao DICT) e uma grandeza DIFERENTE das 604 consultas ao DICT do restore: o 80 do legado nao e refutavel (possivelmente correto) e a comparacao 80 vs 604 era comparacao de grandezas distintas.

**Status revisado da tese**: REFUTADA nos baldes de transacao (o legado estava CERTO); INDETERMINADA nas consultas (sem como medir a grandeza oficial retroativamente); a unica celula material ainda sem verificacao possivel de nossa parte e a receita fonte 1 (586.03).

**Encadeamento documental**: o relatorio `2026-07-19-batimento-apix042026-vs-restore-autbank.md` ganhou nota de errata no topo apontando para este; o relatorio anterior desta trilha foi renomeado para este arquivo (git mv preserva a historia no git); o XML v1 foi renomeado para `APIX042026-v1-NAOTRANSMITIR.xml`. O que os relatorios anteriores provaram sobre o RESTORE (integridade, somas ao centavo, 604 consultas ao DICT, tempos) permanece valido: o que mudou foi a LEITURA do leiaute, nao os fatos do acervo.

## 5. Veredito do dossie: retificacao PROVAVELMENTE DESNECESSARIA

1. O arquivo `APIX042026.xml` transmitido pelo legado estava CORRETO nos baldes de transacao (5 zerado por semantica, 6/1 = 5 / R$ 804.000,00 exato), nas devolucoes, bloqueios e autorizacoes (zeros verdadeiros).
2. QtdConsultas 80: indeterminado, possivelmente correto (definicao oficial e medicao da copia local que so o legado tinha).
3. Disponibilidade 98.45 e tempos: medicoes operacionais do legado, sem indicio de erro.
4. A unica celula que nao conseguimos verificar por nenhuma fonte e a receita fonte 1 (586.03): nao derivavel dos backups PIX nem do acervo core local (0 linhas em abril).

**Recomendacao ao dono: NAO retificar.** A decisao so muda se o dono souber, pela fonte do core do legado (AutBank/monbank), que a origem do 586.03 diverge do que deveria ter sido declarado; nesse caso (e so nesse) o caminho de retificacao TipoEnvio S continua pronto: gerar pelo painel CADOC (`POST /admin/cadoc/generate` tipo 1201) com os overrides do operador (`tipo_envio: "S"`, disponibilidade, consultas, receita corrigida) e entregar pelo ciclo STA do APIX001 ja existente.

## 6. O que segue vivo desta frente

1. **Gerador oficial = `Monetarie.UseCases.Regulatory.Cadoc1201` CORRIGIDO** (Task A5, commit `32da38b8`): taxonomia oficial v2.6 provada por teste (aggregator 25 casos, serializer 9 com xmllint, controller 4), parametros do operador validados no `POST /admin/cadoc/generate`. O gerador da cabine (`SettlementService.Apix`, taxonomia 5/7 tambem errada) fica aposentado como calculadora auxiliar, conforme decisao ja tomada.
2. **Ciclo STA do APIX001 pronto** (`sta_delivery.ex`), sem mudanca nesta task.
3. **Meses futuros**: gerar pelo painel com os overrides do operador documentados: `disponibilidade_basis_points` (medicao operacional do mes), `consultas_dict_qtd` (se a cabine nao resolver consulta em copia local, o valor honesto e 0), `fraude_rejeitadas`, `devolucoes`/`bloqueios_cautelares`/`autorizacoes` fora-SPI quando existirem, `receitas` fonte 1 quando a tarifa nao estiver em `transactions.fee_amount`. Sem override, defaults documentados no moduledoc do Aggregator.
4. **Follow-up honesto**: tempos DICT nao tem override na A5 nem fonte no core (`dict_lookup_events` nao guarda duracao); se o BACEN cobrar fidelidade nesses percentis, e evolucao nova (fonte de duracao na cabine DICT ou override adicional).

## 7. Adendo: projecao local e prova de idempotencia total (--cleanup)

A projecao da C1 e artefato 100% LOCAL e agora 100% REMOVIVEL. A revisao da C1 apontou que os marcadores cobriam so `transactions`/`dict_lookup_events`, deixando entity, snapshot `cadoc1201_records` e trackers `regulatory_files` sem marcador. O script `scripts/apix_abril/project_restore_to_core.py` ganhou o subcomando `--cleanup`, que remove TUDO: linhas com marcador, snapshots cadoc1201 de 04/2026 da entity, trackers `regulatory_files` CADOC_1201 de 04/2026 e os `audit_logs` desses trackers (escopados por resource_id, sem tocar auditoria de outras frentes), e a propria entity ispb 46026562 (best-effort: num banco com dados reais os FKs RESTRICT de accounts/users/webhooks a seguram e o script avisa sem quebrar).

Prova executada nesta sessao (saidas integrais no terminal da sessao):

1. `--cleanup` sobre a projecao viva: `DELETE 2` (audit dos trackers), `DELETE 1` (snapshot), `DELETE 1` (tracker), `DELETE 248` (transactions), `DELETE 604` (dict_lookup_events), `DELETE 1` (entity); verificacao pos-cleanup com 6 contadores = TODOS ZERO ("cleanup OK: zero residuo da projecao no mon_core local").
2. Segundo `--cleanup` em seguida: no-op (todos DELETE 0, verificacao zero), idempotente.
3. Re-projecao completa: verificacao pos-insert fecha com o restore ao centavo (243 / 13.810.512,30 / 5 / 804.000,00 / 604).
4. Re-geracao: XML byte a byte IDENTICO, sha256 `90dda5dca81cdb3c23ba94c7af569b93883de18fccd51db8f65ae48a5df4dceb` igual ao da primeira geracao v2. Ciclo cleanup -> projecao -> geracao e deterministico e sem residuo.

NAO projetar em HML/PRD sem decisao expressa do dono (regra inalterada).