---
id: DEC-0010
ticket: perf-host-debug-overlay-isolation
title: Decision - [PERF] Overlay Log Metric Uses Last Completed Frame
status: accepted
created: 2026-04-10
updated: 2026-04-10
agenda: AGD-0023
tags: [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.