prometeu-runtime/discussion/workflow/agendas/AGD-0007-perf-runtime-telemetry-hot-path.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0007	perf-runtime-telemetry-hot-path	Agenda - [PERF] Runtime Telemetry Hot Path	open	2026-03-27

Agenda - [PERF] Runtime Telemetry Hot Path

Problema

O runtime cobra telemetria de asset bank no caminho quente de todo host tick.

Hoje, tick() consulta bank_info() para gfx e audio mesmo quando nenhum logical frame foi fechado. O custo de observabilidade acaba sendo pago continuamente pela execucao normal.

Dor

• CPU e locks sao gastos em todos os ticks, nao apenas quando a metrica muda.
• hardware barato sofre mais com trabalho pequeno e repetitivo do que com picos raros.
• overlay, stats e certifier acabam puxando custo estrutural para o core do runtime.

Hotspots Atuais

• tick.rs
• asset.rs

Alvo da Discussao

Remover varredura e agregacao lock-heavy do hot path do tick sem perder observabilidade util.

O Que Precisa Ser Definido

1. Modelo de metrica. Decidir o que passa a ser contador incremental e o que continua sendo snapshot sob demanda.

2. Frequencia de coleta. Decidir se atualizacao acontece:

   • no fechamento do logical frame;
   • apenas com overlay/debug ativo;
   • por amostragem periodica;
   • por evento de mutacao (load, commit, cancel).

3. Responsabilidade da agregacao. Delimitar se a verdade dos bytes/slots fica:

   • no AssetManager;
   • no runtime;
   • em uma camada propria de telemetry cache.

4. Garantia de consistencia. Decidir qual grau de defasagem e aceitavel para handheld barato:

   • exato em tempo real;
   • eventual por frame;
   • eventual por tick de debug.

Open Questions de Arquitetura

1. O certifier realmente precisa de snapshot de bank a cada tick? Não. O certifier aceita dados do fim do frame anterior, pois violações de limites de bank costumam ser persistentes entre frames.
2. O overlay pode ler uma versao resumida da telemetria em vez de recalcular tudo? Sim. O AssetManager passará a prover uma struct BankStats pré-calculada via contadores atômicos.
3. Vale manter caminho "preciso" so para testes/debug e caminho "barato" para runtime normal? Sim, mas a "precisão" será definida como "atualizado no último evento de mutação", o que já é suficiente para ambos os casos.
4. Como detectar o modo de depuração/inspeção de forma correta e desacoplada? Através de um novo campo inspection_active: bool no VirtualMachineRuntime, controlado explicitamente pelo Host (ex: quando o Overlay F1 ou o Debugger remoto estão ativos). O certifier não deve ser usado para este propósito.

Sugestao / Recomendacao

1. Modelo de Métrica (Push-based):

   • Migrar de snapshot total O(n) para contadores incrementais O(1) no AssetManager.
   • Utilizar AtomicUsize ou campos protegidos por Mutex simples para used_bytes, inflight_bytes e slots_occupied.
   • Atualizar esses contadores apenas em eventos de mutação (load, commit, cancel).

2. Frequência de Coleta (Dois Níveis):

   • Básica (Sempre): O Runtime deve atualizar telemetry_current no fechamento de cada logical frame (FrameSync ou EndOfRom). Isso garante dados para o certifier com custo O(1).
   • Alta Frequência (Sob Demanda): Manter atualização em todo host tick apenas se inspection_active for true (Overlay F1 visível ou Debugger conectado).

3. Responsabilidade da Agregação (Centralizada):

   • O AssetManager é o dono da "verdade incremental". O Runtime consome um snapshot barato (struct POD) sem varredura de locks.

4. Garantia de Consistência (Eventual):

   • Aceitar defasagem de até 1 frame lógico para métricas de asset bank.

Dependencias

• ../specs/10-debug-inspection-and-profiling.md
• ../specs/16a-syscall-policies.md

Criterio de Saida Desta Agenda

Pode virar PR quando houver decisao escrita sobre:

• metrica incremental vs snapshot;
• ponto canonico de atualizacao da telemetria;
• custo maximo aceitavel no hot path do tick;
• comportamento de overlay/certifier sobre dados defasados.