prometeu-runtime/discussion/workflow/plans/PLN-0005-perf-push-based-telemetry-implementation.md

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

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

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.