prometeu-runtime/discussion/workflow/decisions/DEC-0010-overlay-log-metric-last-frame.md

id	ticket	title	status	created	updated	agenda	tags
DEC-0010	perf-host-debug-overlay-isolation	Decision - [PERF] Overlay Log Metric Uses Last Completed Frame	accepted	2026-04-10	2026-04-10	AGD-0023	performance host telemetry logs

Decision - [PERF] Overlay Log Metric Uses Last Completed Frame

Status

Accepted

Contexto

O campo LOGS do overlay técnico do desktop host estava lendo um contador transitório incrementado durante o frame e zerado no fechamento do frame lógico. Como o Host compõe o overlay de forma assíncrona em relação ao loop interno da máquina, esse valor visual tende a aparecer como 0 mesmo sob stress com alta emissão de logs.

Decisao

1. O valor visual LOGS exposto ao overlay MUST represent the number of logs emitted during the last completed logical frame.
2. O contador transitório intra-frame MAY continue to exist for internal collection and frame-end aggregation, but it MUST NOT be exposed diretamente como métrica visual do overlay.
3. O AtomicTelemetry::snapshot() MUST expose the persisted last-frame value for logs_count.
4. A certificação MUST evaluate log pressure against the persisted last completed frame value, not against a host-timing-dependent transient value.

Rationale

• O overlay precisa de um valor estável e observável pelo Host.
• O frame fechado é a unidade correta para comparação com outras métricas como ciclos e syscalls.
• A mesma semântica serve tanto para overlay quanto para certificação, evitando ambiguidade.

Invariantes / Contrato

• logs_count em TelemetryFrame significa logs from last completed logical frame.
• O reset do contador transitório não pode apagar o valor persistido exposto ao Host.
• O overlay não deve depender de timing fino entre renderização do Host e fechamento do frame lógico.

Impactos

• HAL: AtomicTelemetry precisa persistir o valor de logs do frame concluído.
• Runtime: no fechamento do frame, o valor de logs do frame deve ser copiado antes do reset do contador transitório.
• Host overlay: nenhuma mudança conceitual adicional além de passar a receber um valor útil e estável.
• Specs: capítulo de debug deve deixar explícita a semântica de logs_count.

Referencias

• AGD-0023: [PERF] Overlay Log Metric Must Show Last Frame.
• DEC-0008: Full Migration to Atomic Telemetry.
• DEC-0009: Host Overlay Tooling Boundary.

Propagacao Necessaria

1. Atualizar PLN-0008 para incluir a semântica last-frame de LOGS.
2. Ajustar HAL e runtime para persistir logs_count ao final do frame.
3. Atualizar a especificação de debug.