---
id: DEC-0005
title: "Decisão - [PERF] Modelo de Telemetria Push-based"
status: closed
created: 2026-03-27
resolved: 2026-03-27
agenda: AGD-0007
tags: []
---

# Decisão - [PERF] Modelo de Telemetria Push-based

## Status

**Fechada (Closed)** - Consensus reached. Implementation approved.

## Contexto

O runtime atual (`VirtualMachineRuntime::tick()`) realiza a coleta de telemetria de asset banks (`gfx` e `audio`) em todos os *host ticks*. Essa coleta envolve a chamada de `bank_info()` no `AssetManager`, que executa uma varredura $O(n)$ sobre mapas de recursos e adquire múltiplos locks de leitura. Em hardwares limitados (handhelds), esse custo repetitivo no caminho quente degrada a performance desnecessariamente, mesmo quando o sistema está estável ou em pausa.

## Decisão

1.  **Modelo de Contadores no Driver e Runtime:** O `AssetManager`, a `Heap` da VM e o `LogService` devem substituir a varredura/contagem total por **contadores atômicos** (`used_bytes`, `inflight_bytes`, `slots_occupied`, `logs_count`) para cada subsistema. Esses contadores serão atualizados incrementalmente ($O(1)$) em cada mutação (load, commit, alloc, free, log).
2.  **Snapshot Obrigatório de Fim de Frame:** O runtime capturará o estado desses contadores (Banks, Heap e Logs) **apenas uma vez** por fechamento de frame lógico (`FrameSync` ou `EndOfRom`). Este snapshot será usado para alimentar a `telemetry_last` e o `certifier`.
3.  **Coleta sob Demanda (Inspection Mode):** A coleta em cada *host tick* será reativada **somente** se o novo sinalizador `inspection_active: bool` do runtime for verdadeiro.
4.  **Desacoplamento do Certifier:** A ativação do `certifier` não habilitará mais a telemetria detalhada em cada tick. O certifier será servido exclusivamente pelos snapshots de fim de frame lógico.

## Rationale

*   **Performance:** Reduz o custo do tick do runtime de $O(n)$ com locks para $O(1)$ sem locks no modo normal.
*   **Observabilidade:** Mantém dados precisos para o overlay (via modo inspeção) e dados válidos para o certifier (via snapshot de frame).
*   **Modularidade:** Desacopla as necessidades de depuração (Overlay F1) das necessidades de validação normativa (Certifier).

## Invariantes / Contrato

*   O `AssetManager` é a única fonte da verdade para o uso de memória de assets; o runtime não deve tentar calcular esses valores manualmente.
*   Contadores atômicos garantem que o runtime possa ler estatísticas de bancos sem travar mutações em andamento (consistência eventual).
*   A defasagem de até 1 frame lógico é aceitável para métricas de assets bank no modo de operação normal.

## Impactos

*   **Drivers:** Necessidade de adicionar e gerenciar contadores no `AssetManager`.
*   **Virtual Machine:** Adicionar contador atômico de `used_bytes` na `Heap`.
*   **Log Service:** Adicionar contador incremental de logs emitidos no frame no `LogService`.
*   **Runtime:** Modificação no `VirtualMachineRuntime` para incluir o campo `inspection_active` e lógica condicional no `tick()`.
*   **Host:** O host (ex: desktop-winit) deve agora sinalizar quando o overlay de depuração está ativo via `inspection_active`.

## Referências

*   Agenda [AGD-0007-perf-runtime-telemetry-hot-path.md](../agendas/AGD-0007-perf-runtime-telemetry-hot-path.md)
*   Spec `10-debug-inspection-and-profiling.md`

## Propagação Necessária

*   Atualizar o `VirtualMachineRuntime` para expor o campo `inspection_active`.
*   Atualizar o `HostRunner` para sinalizar `inspection_active` quando o overlay F1 for alternado.
*   Atualizar a struct `TelemetryFrame` para incluir campos de Heap Memory e Log count.