[feature][P2] Volume Ledger — metadata-only data-volume tally, opt-in, foundation for bestiary volume-based billing

[FabioLeitao]

Contexto / motivação

Discussão privada (operador, 2026-08-24): a escada de tiers do Boar hoje precifica por
footprint×paralelismo (docs/adr/ADR-0027, PLAN_PRODUCT_TIERS_AND_OPEN_CORE.md), não por
volume — decisão deliberada. Mas os demais produtos do bestiário (não neste repo) podem querer
precificar por volume manifestado (evento/grant/operação), e o Boar é o único componente que
já enumera as fontes primeiro. Esta issue pede só a infraestrutura de medição e exposição do
volume — não decide se o Boar cobra por ela. Se a decisão for não cobrar, o dado fica exposto e
não-usado (fica livre).

O que já existe (verificado agora, base pra não duplicar)

• core/database.py + docs/adr/ADR-0051-incremental-filesystem-scan-file-identity-fingerprint.md
  (Phase 1 do docs/plans/PLAN_INCREMENTAL_SCAN_IDEMPOTENCY.md, já no código): toda
  FilesystemFinding grava source_size (bytes, via Path.stat()) — não precisa de nova coleta,
  é stat(), não leitura de conteúdo.
• connectors/sql_table_row_estimate.py (já no código): estimate_table_rows() — estimativa
  de linhas só por catálogo (pg_class.reltuples / sys.partitions / all_tables.num_rows /
  information_schema.tables.table_rows), Postgres/MSSQL/Oracle/MySQL/MariaDB, sem COUNT(*)
  na heap. Hoje só orienta estratégia de sampling — não expõe tamanho em bytes, não vira
  resultado de relatório.

Pedido

1. Byte-size por catálogo, mesmos 5 dialetos, mesmo padrão sql_table_row_estimate.py
   (módulo novo ou extensão do mesmo, ex. estimate_table_bytes()):
   • Postgres: pg_total_relation_size(oid) (dados+índices)
   • MSSQL: sys.dm_db_partition_stats (soma de used_page_count * 8192)
   • Oracle: DBA_SEGMENTS/USER_SEGMENTS (bytes)
   • MySQL/MariaDB: information_schema.tables.DATA_LENGTH + INDEX_LENGTH
   • Catálogo-only, sem tocar linha — mesmo princípio de docs/GLOSSARY.md (metadata-only).
2. Uma estrutura de saída nova (nome sugerido: Volume Ledger — evitar "manifest", já
   sobrecarregado no repo: report/scan_evidence.py, report/evidence_collector.py,
   core/licensing/guard.py, integridade de release, plugin SDK todos já usam "manifest" pra
   coisas diferentes) — por target/fonte: total_bytes_approx, total_objects_or_rows_approx,
   method (stat | catalog | unavailable), computed_at. Local natural: par de
   report/scan_evidence.py/report/evidence_collector.py, ou seção nova no --export-audit-trail
   (core/audit_export.py).
3. Opt-in explícito, default off (ex. report.volume_ledger: false) — zero mudança de
   comportamento pra quem não ligar. Sem enforcement/billing neste repo — só medição+exposição.
4. Documentar explicitamente no plano: este componente é pensado como insumo pros demais
   produtos do bestiário (fora deste repo) decidirem billing por volume — o Boar em si
   permanece na métrica de footprint×paralelismo já ratificada, a menos que decisão futura mude
   isso.

Critérios de aceite

• Criar docs/plans/PLAN_VOLUME_LEDGER.md com <!-- plans-hub-summary: ... -->.
• Executar python scripts/plans_hub_sync.py --write.
• Adicionar entry em docs/plans/PLANS_TODO.md.
• estimate_table_bytes() (ou equivalente) cobrindo os 5 dialetos já suportados por
  estimate_table_rows(), mesmo padrão de erro (None silencioso, nunca exceção derruba scan).
• Volume Ledger desligado por padrão; teste cobrindo comportamento idêntico ao atual quando
  desligado.
• Teste cobrindo soma de source_size por target (filesystem) e byte-estimate por
  dialeto (DB), incluindo o caso "dialeto sem estimador" (retorna None, não quebra).
• docs/REPORTS_AND_COMPLIANCE_OUTPUTS.md (+ pt_BR) documentando o novo campo/flag.

---

Triado e proposto — Claude (Sonnet 5) · auditor externo (READONLY, só gh issue create). Origem:
conversa privada de arquitetura/pricing com o operador, 2026-08-24 — não é achado de segurança.

[FabioLeitao]

Correção de estado — a base já está mais adiantada do que esta issue sugere

Reverificado em código hoje (2026-08-25), com call site. Quando abri esta issue eu subestimei o que
já existe:

Fase 2 do ADR-0051 (scan_object_state) NÃO é plano — está implementada e fiada:

• core/database.py:309 — tabela com UniqueConstraint("target_name", "abs_path", name="uq_scan_object_path")
• core/database.py:960 — upsert_object_state(), semântica INSERT OR REPLACE
• connectors/filesystem_connector.py:936 — call site real, gravando size, mtime_ns e content_fingerprint a cada finding
• tests/test_database.py — cobertura

Por que isso importa para esta issue: o UniqueConstraint por (target, path) torna a tabela
idempotente por caminho — varrer N vezes não soma, atualiza no lugar. Ou seja, um inventário de
footprint mapeado (SUM(size)) para filesystem já é consultável hoje, sem coleta nova, e o
content_fingerprint já permite deduplicar o mesmo conteúdo em caminhos distintos.

O escopo real desta issue encolhe para o que de fato falta:

1. O eixo de bytes para DB por catálogo (pg_total_relation_size / DATA_LENGTH+INDEX_LENGTH /
   DBA_SEGMENTS / sys.dm_db_partition_stats) — hoje connectors/sql_table_row_estimate.py só
   estima linhas. Esta parte segue válida como pedido original.
2. A estrutura de saída / superfície de leitura.

A parte de filesystem vira consulta, não coleta. Ver #1760 (query SUM(size) + dedup) e o
comentário em #1718 (Fase 2 fiada; Fase 3 é que está pendente).

---

Nota de método: eu havia afirmado nesta sessão que a Fase 2 "era só plano". Estava errado — a
própria busca que rodei retornava core/database.py na saída e eu li mal. Registro aqui para que a
issue não carregue adiante a premissa errada.

[FabioLeitao]

🔴 Duplicata de #1578 — recomendo fechar esta e consolidar lá

#1578 ([P2][feature][inventory] Data Estate Volume Inventory — tamanho e delta da superfície em
escopo, aberta 2026-08-15) já cobre o escopo desta issue, e cobre melhor:

Aqui	Em #1578
bytes de DB por catálogo	"Start with metadata obtainable without additional content reads: filesystem, database catalog sizes, and object storage object sizes"
medição metadata-only	"Do not collect extra content solely to measure volume"
idempotência no re-scan	"Re-scanning the same scope must not sum the estate again" / AC: "Two identical scans do not double the observed estate"
tratar tamanho indisponível	"A target without a supported size appears as unknown, never as zero"

#1578 ainda acrescenta o que eu não previ: delta entre observações, breakdown por
connector/tipo de fonte, measurement method e confidence explícitos no artefato, e definição de
TiB/GiB × TB/GB nas superfícies.

Como eu criei trabalho paralelo — e a issue me avisava

A própria #1578 traz, na seção Before implementation:

1. Search for existing plans/issues/PRs covering scan manifest, data-source inventory,
incremental scans/idempotency, object storage and database connectors.
2. If overlap exists, update the canonical item rather than creating parallel work.

Não segui. Busquei com gh api search/code, que não indexa corpo de issue — então #1578
nunca apareceu. O correto seria gh issue list --search. Mesmo erro de método que já me custou
outras três vezes hoje.

O que NÃO é duplicata (não fechar junto)

• [feature][P2] Teto de footprint por licença: claim dbmax_footprint_gb + blocos + graça de uma sessão #1762 (teto de footprint, claim dbmax_footprint_gb, blocos, graça de volume) — a própria
  #1578 põe isso em Out of scope: "Charging by TB, JWT volume claims, commercial packs,
  grace/overage". É o par comercial dela, e a separação está correta: #1578 entrega valor de
  inventário ao cliente independente de cobrança.
• [feature][P2] Declarar cobertura parcial no artefato quando o scan não cobriu o estate inteiro #1761 (declarar cobertura parcial no artefato) — é sobre cobertura do scan, não sobre
  tamanho do estate. Eixos diferentes.

Sugestão: fechar esta como duplicata de #1578 e migrar para lá o único detalhe que talvez não
esteja explícito — os nomes concretos de query por dialeto (pg_total_relation_size /
DATA_LENGTH+INDEX_LENGTH / DBA_SEGMENTS / sys.dm_db_partition_stats), seguindo o padrão que
connectors/sql_table_row_estimate.py já usa para linhas.

Não fecho eu mesmo — fechar issue está fora do meu contrato neste repo.