---
id: PLN-0005
title: "Plano - [PERF] Implementação de Telemetria Push-based"
status: open
created: 2026-03-27
origin_decisions:
  - DEC-0005
tags: []
---

# Plano - [PERF] Implementação de Telemetria Push-based

## Briefing

Este plano detalha as alterações técnicas para migrar o sistema de telemetria de um modelo de varredura $O(n)$ com locks para um modelo push-based com contadores atômicos $O(1)$. O objetivo é reduzir o overhead do hot path do runtime e adicionar visibilidade sobre a memória RAM (Heap) e volume de logs.

## Decisions de Origem

*   [DEC-0005 - [PERF] Modelo de Telemetria Push-based](../decisions/DEC-0005-perf-push-based-telemetry-model.md)

## Alvo

*   `prometeu-drivers` (AssetManager)
*   `prometeu-vm` (Heap)
*   `prometeu-hal` (TelemetryFrame)
*   `prometeu-system` (LogService, VirtualMachineRuntime)
*   `prometeu-host-desktop-winit` (HostRunner)

## Escopo

1.  **Contadores Atômicos:** Implementação de `AtomicUsize` nos subsistemas de assets, heap e logs.
2.  **Telemetry Frame:** Expansão da struct para incluir `heap_used`, `heap_max` e `logs_count`.
3.  **Lógica de Tick:** Refatoração do `tick.rs` para usar `inspection_active` e snapshots de fim de frame.
4.  **Sinalização do Host:** Integração do campo `inspection_active` com o acionamento do overlay F1.

## Fora de Escopo

*   Migração da renderização do overlay para o host nativo (será tratado em plano derivado da AGD-0012).
*   Telemetria de FileSystem IO ou Corrotinas.

## Plano de Execucao

### Fase 1: Drivers e VM (Modelo Push)
1.  **`prometeu-drivers/src/asset.rs`:** 
    - Adicionar contadores em `BankPolicy`.
    - Atualizar contadores em `load_internal`, `commit` e `cancel`.
    - Refatorar `bank_info()` para retornar os valores atômicos sem varredura.
2.  **`prometeu-vm/src/heap.rs`:**
    - Adicionar contador `used_bytes` na struct `Heap`.
    - Atualizar contador em `alloc()` e `free()`.
3.  **`prometeu-system/src/log.rs`:**
    - Adicionar contador `logs_count` (resetável por frame) no `LogService`.

### Fase 2: HAL e Runtime (Contrato e Lógica)
1.  **`prometeu-hal/src/telemetry.rs`:**
    - Adicionar `heap_used_bytes`, `heap_max_bytes` e `logs_count` na `TelemetryFrame`.
2.  **`prometeu-system/src/virtual_machine_runtime.rs`:**
    - Adicionar campo `public inspection_active: bool`.
3.  **`prometeu-system/src/virtual_machine_runtime/tick.rs`:**
    - Modificar `tick()` para coletar `bank_info` detalhado apenas se `inspection_active == true`.
    - Implementar a captura do snapshot consolidado no fechamento do logical frame.

### Fase 3: Host e Integração
1.  **`prometeu-host-desktop-winit/src/runner.rs`:**
    - Sincronizar o estado do campo `overlay_enabled` com `firmware.os.inspection_active`.

## Criterios de Aceite

*   O sistema compila sem avisos de tipos inexistentes.
*   A telemetria de assets (`gfx`/`audio`) continua funcional no overlay F1.
*   Novos campos de Heap e Logs aparecem no log de performance do console.
*   O custo de telemetria no `tick` deve cair drasticamente quando o overlay estiver desligado (verificável via profiling).

## Tests / Validacao

*   **Teste Unitário:** Criar teste em `asset.rs` para garantir que contadores batem com a realidade após sequências de carga e cancelamento.
*   **Teste de Regressão:** Garantir que o `certifier` continua detectando violações de bank no fim do frame.

## Riscos

*   **Consistência Eventual:** Como os contadores são atômicos e não travam o sistema, pode haver uma defasagem momentânea durante um `commit` pesado; isto é aceitável conforme DEC-0005.