dev/perf-runtime-telemetry-hot-path (#13)
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good

Reviewed-on: #13
Co-authored-by: bQUARKz <bquarkz@gmail.com>
Co-committed-by: bQUARKz <bquarkz@gmail.com>
This commit was merged in pull request #13.
This commit is contained in:
2026-04-10 08:32:00 +00:00
committed by bquarkz
parent 5e80ea46b8
commit c65362c186
24 changed files with 622 additions and 664 deletions
@@ -1,77 +0,0 @@
---
id: AGD-0007
ticket: perf-runtime-telemetry-hot-path
title: Agenda - [PERF] Runtime Telemetry Hot Path
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# 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](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs#L167)
- [asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs#L618)
## 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?
2. O overlay pode ler uma versao resumida da telemetria em vez de recalcular tudo?
3. Vale manter caminho "preciso" so para testes/debug e caminho "barato" para runtime normal?
## 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.
@@ -52,19 +52,22 @@ Isolar o overlay de debug do custo medido do console sem perder utilidade para d
## Open Questions de Arquitetura
1. O overlay precisa ser representativo do hardware final ou apenas ferramenta de desktop?
Não, como é HUD técnico, pode e deve ser renderizado pelo Host nativo para melhor legibilidade.
2. Vale um modo "perf puro" onde overlay nunca toca no framebuffer do console?
Sim. O isolamento garante que o `gfx` emulado esteja 100% livre para o jogo durante a medição.
3. O host deve oferecer toggles separados para stats, logs e overlay visual?
Sim. O `HostRunner` deve expor controles granulares via `inspection_active`.
4. Como melhorar a legibilidade e estética (Glyphs/Transparência)?
Migrar a renderização do HUD para o Host Nativo (Winit/Pixels), permitindo o uso de fontes TrueType (monospaced) nítidas e Alpha Blending real para transparência no fundo do painel.
## Dependencias
- `../specs/10-debug-inspection-and-profiling.md`
- `../specs/11-portability-and-cross-platform-execution.md`
## Criterio de Saida Desta Agenda
## Sugestao / Recomendacao
Pode virar PR quando houver decisao escrita sobre:
- onde o overlay e composto;
- politica de cache de texto/glyphs;
- como o custo do overlay aparece na telemetria;
- overhead maximo aceitavel em modo debug.
1. **Migração para Camada Host Nativa:** Renderizar o HUD de debug em uma surface separada ou via pipeline nativo do Host (depois do upscaling do framebuffer do console).
2. **Fontes TrueType (Mono):** Substituir os glyphs bitmapped rudimentares por uma fonte nativa de alta qualidade e nítida.
3. **Composição Alpha:** Permitir fundo semi-transparente para o overlay para não bloquear a visão do jogo.
4. **Acionamento Explícito:** Host deve gerenciar `inspection_active: true` no runtime apenas quando o HUD ou Debugger estiverem ativos.