clean up
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good

This commit is contained in:
2026-04-10 23:38:20 +01:00
parent 8f98aee64e
commit 70cde0d975
12 changed files with 1 additions and 689 deletions
@@ -1,53 +0,0 @@
---
id: DEC-0007
ticket: perf-host-debug-overlay-isolation
title: Decision - [PERF] Host Debug Overlay Isolation
status: accepted
created: 2026-04-10
updated: 2026-04-10
agenda: AGD-0012
tags: [performance, host, gfx]
---
# Decision - [PERF] Host Debug Overlay Isolation
## Status
**Accepted**
## Contexto
O overlay de debug do PROMETEU, utilizado para exibir telemetria, logs e métricas em tempo real, está atualmente acoplado ao pipeline de renderização emulado (`gfx`) e ao processamento do runtime. Isso resulta em:
1. **Distorção de Performance:** O custo de formatar strings e realizar chamadas de desenho para o HUD técnico é contabilizado como ciclos do jogo, invalidando medições de certificação.
2. **Acoplamento Indevido:** O pipeline `gfx` emulado processa elementos visuais (HUD) que não existem no hardware original.
3. **Complexidade no Host:** O Host precisa lidar com a injeção dessas informações no buffer de emulação.
## Decisao
Fica decidido que o overlay de debug será movido integralmente para a camada **Host Desktop** (`prometeu-host-desktop-winit`), operando de forma 100% isolada do runtime e do pipeline de `gfx` emulado.
1. **Isolamento de Pipeline:** O overlay técnico deve ser tratado como uma "película" (layer) transparente aplicada pelo Host sobre o resultado final da renderização (pós-upscaling).
2. **Isolamento de Processamento:** Nenhuma instrução de desenho ou formatação de strings relacionada ao overlay deve ocorrer dentro do runtime ou durante os ciclos emulados.
3. **Acesso via API:** O Host acessará os dados necessários para o overlay através de uma API de telemetria passiva (baseada em atômicos, conforme definido na `DEC-0005`).
4. **Acionamento via F1:** O controle de visibilidade (toggle) do overlay é de responsabilidade exclusiva do Host, acionado pela tecla **F1**.
## Rationale
- **Pureza de Medição:** Ao remover o processamento do overlay do runtime, garantimos que 100% dos ciclos medidos pertencem à lógica do cartucho e periféricos emulados.
- **Desempenho no Hardware Alvo:** Como o overlay é exclusivo de Desktop, dispositivos handheld/consoles de baixo custo não devem pagar o preço de implementação ou ramificações lógicas para lidar com HUD técnico.
- **Qualidade Visual:** Utilizar o Host para renderizar o HUD permite o uso de fontes TrueType nítidas e Alpha Blending real, melhorando drasticamente a legibilidade para o desenvolvedor sem afetar a fidelidade da emulação.
## Invariantes / Contrato
- **Zero Overhead no Runtime:** A presença ou ausência do overlay não deve alterar o contador de ciclos consumidos por frame no runtime.
- **Agnosticismo de GFX:** O framebuffer emulado deve conter apenas os pixels gerados pelo cartucho, sem HUD técnico "queimado" na imagem.
- **Composição Assíncrona/Passiva:** O Host não deve bloquear o runtime para coletar dados para o overlay; a leitura deve ser feita a partir de buffers de telemetria já expostos.
## Impactos
- **Host (Desktop Winit):** Exige a implementação de uma camada de renderização nativa (ex: `egui` ou composição direta via `pixels`/`winit`) que suporte transparência.
- **Runtime API:** Deve expor campos de telemetria (FPS, Memory Usage, Cycles) via API para consumo pelo Host.
- **Especificações:** Atualização dos capítulos de Portabilidade e Debug para refletir o isolamento.
## Referencias
- `AGD-0012`: [PERF] Host Debug Overlay Isolation (Agenda de Origem).
- `DEC-0005`: [PERF] Push-based Telemetry Model (Modelo de acesso aos dados).
## Propagacao Necessaria
1. Remover hotspots de desenho de texto no `runner.rs` do host.
2. Implementar o novo sistema de HUD no host usando bibliotecas nativas.
3. Atualizar a documentação técnica em `docs/specs/runtime/`.
@@ -1,35 +0,0 @@
# DEC-0008: Full Migration to Atomic Telemetry
## Status
Accepted
## Contexto
Após o sucesso inicial do `AtomicTelemetry` (DEC-0007), identificou-se que a coexistência com os campos legados `telemetry_current` e `telemetry_last` no `VirtualMachineRuntime` é contraproducente. O usuário solicitou a remoção completa da camada de compatibilidade para simplificar o motor e garantir que o modelo atômico seja a única fonte de verdade para performance e inspeção.
## Decisao
1. **Remoção Total:** Eliminar os campos `telemetry_current` e `telemetry_last` da struct `VirtualMachineRuntime`.
2. **Modelo Único:** O `AtomicTelemetry` passa a ser a única estrutura responsável por rastrear métricas de execução (ciclos, memória, logs).
3. **Snapshot On-Demand:** Qualquer necessidade de telemetria estática (ex: para logs de erro ou final de frame) deve ser atendida pelo método `AtomicTelemetry::snapshot()`, que gera um `TelemetryFrame` imutável a partir do estado atômico atual.
4. **Atualização Condicional:** A atualização dos campos atômicos dentro do loop de `tick` da VM permanece protegida por `inspection_active`, garantindo overhead zero em modo de produção.
## Rationale
- **Simplicidade:** Reduz o número de campos no `VirtualMachineRuntime`.
- **Performance:** Evita a cópia de dados entre `telemetry_current` e `telemetry_last` ao final de cada frame.
- **Consistência:** Garante que o Host e o Runtime vejam os mesmos dados através da mesma API.
## Invariantes / Contrato
- O `VirtualMachineRuntime` deve possuir uma instância de `Arc<AtomicTelemetry>`.
- O `AtomicTelemetry` deve ser thread-safe (já garantido pelo uso de `std::sync::atomic`).
## Impactos
- **Runtime:** Alteração na struct principal e no loop de tick.
- **HAL:** Possível ajuste no `LogService` se ele dependia diretamente dos campos legados.
- **Docs:** Necessidade de atualizar as especificações de Debug e Portabilidade.
## Referencias
- AGD-0021 (Migration Agenda)
- DEC-0007 (Overlay Isolation Decision)
## Propagacao Necessaria
- Refatoração de `VirtualMachineRuntime`.
- Atualização de `prometeu-host-desktop-winit` para garantir que continua funcionando (já migrado no PLN-0006, mas deve ser validado).
@@ -1,61 +0,0 @@
---
id: DEC-0009
ticket: perf-host-debug-overlay-isolation
title: Decision - [PERF] Host Overlay Tooling Boundary
status: accepted
created: 2026-04-10
updated: 2026-04-10
agenda: AGD-0022
tags: [performance, host, gfx, overlay]
---
# Decision - [PERF] Host Overlay Tooling Boundary
## Status
**Accepted**
## Contexto
`DEC-0007` já determinou que o overlay técnico do desktop deve existir no Host e fora do pipeline de `gfx` emulado. Durante a execução, surgiu uma ambiguidade adicional: a implementação corretiva poderia ser interpretada como remoção ou desvalorização de `fill_rect` e `draw_text`, quando essas primitives continuam fazendo parte legítima do contrato gráfico atual da máquina emulada.
Também ficou explícito que “estar no host” não é suficiente se o overlay ainda desenhar usando `hardware.gfx`. O limite correto é mais estrito: o overlay deve possuir ferramentas próprias e compor em camada separada no host.
## Decisao
Fica decidido que o contrato do overlay técnico do desktop host será refinado da seguinte forma:
1. **Preservação do Contrato Emulado:** `fill_rect` e `draw_text` MUST remain part of the current syscall and emulated hardware contract. They MUST NOT be removed, weakened, or repurposed because of host overlay work.
2. **Separação de Ferramentas:** O overlay técnico do desktop host MUST use dedicated host-side tooling for panel composition, text rendering, simple bars, and alert presentation.
3. **Proibição de Dependência do Hardware Emulado:** O overlay MUST NOT call, depend on, or route through `hardware.gfx`, `fill_rect`, `draw_text`, or any equivalent emulated-framebuffer primitive.
4. **Camada Separada no Host:** O overlay MUST be rendered in a separate host layer/surface after the emulated frame is produced. The emulated framebuffer MAY be transported into the host presentation surface, but overlay pixels MUST NOT be written back into the emulated framebuffer.
5. **Módulo Dedicado:** A dedicated host module SHALL own overlay rendering behavior. The implementation MUST NOT remain embedded as ad hoc overlay drawing logic inside `runner.rs`.
6. **Escopo Visual Mínimo:** Para este ciclo, o overlay SHOULD remain intentionally simple: semitransparent panel, text, and simple bars where useful. It MUST NOT introduce a general UI framework, docking model, or movable window system.
7. **Responsabilidade do Runtime:** O runtime MUST remain responsible only for telemetry exposure and inspection state gating. It MUST NOT own overlay drawing behavior, layout policy, or visual composition.
## Rationale
- **Clareza de Fronteira:** Preservar o contrato da máquina e mover apenas o overlay evita misturar API emulada com inspeção técnica de host.
- **Pureza do Framebuffer:** Uma camada separada elimina a contaminação visual do framebuffer emulado e torna a validação objetiva.
- **Simplicidade Controlada:** Texto e barras simples resolvem legibilidade sem transformar o host overlay em um projeto paralelo de UI.
- **Manutenibilidade:** Um módulo dedicado reduz o risco de regressão arquitetural em `runner.rs`.
## Invariantes / Contrato
- `fill_rect` e `draw_text` continuam válidos para o domínio emulado.
- O overlay técnico do host não escreve no framebuffer emulado.
- O overlay técnico do host não depende de primitives do hardware emulado.
- O módulo de overlay é de responsabilidade exclusiva do host desktop.
- O ponto de composição do overlay ocorre depois que o frame emulado já está pronto para apresentação no host.
## Impactos
- **Host (Desktop Winit):** Exige um módulo próprio de overlay e uma estratégia de composição em camada separada.
- **Runtime API:** Nenhuma mudança conceitual adicional além de continuar expondo telemetria passiva e gating de inspeção.
- **Specs:** As especificações de debug e portabilidade devem distinguir explicitamente o contrato emulado das ferramentas de overlay do host.
- **Plano de Execução:** `PLN-0008` deve ser atualizado para refletir módulo dedicado e camada separada no host.
## Referencias
- `AGD-0022`: [PERF] Host Overlay Tooling Boundary Revision.
- `DEC-0007`: [PERF] Host Debug Overlay Isolation.
- `DEC-0008`: Full Migration to Atomic Telemetry.
## Propagacao Necessaria
1. Atualizar `PLN-0008` para refletir o módulo dedicado e a camada separada no host.
2. Implementar o módulo de overlay no `prometeu-host-desktop-winit`.
3. Remover o uso de `hardware.gfx` pelo overlay técnico.
4. Atualizar as specs para preservar o contrato gráfico emulado e separar a composição do overlay host.
@@ -1,50 +0,0 @@
---
id: DEC-0010
ticket: perf-host-debug-overlay-isolation
title: Decision - [PERF] Overlay Log Metric Uses Last Completed Frame
status: accepted
created: 2026-04-10
updated: 2026-04-10
agenda: AGD-0023
tags: [performance, host, telemetry, logs]
---
# Decision - [PERF] Overlay Log Metric Uses Last Completed Frame
## Status
**Accepted**
## Contexto
O campo `LOGS` do overlay técnico do desktop host estava lendo um contador transitório incrementado durante o frame e zerado no fechamento do frame lógico. Como o Host compõe o overlay de forma assíncrona em relação ao loop interno da máquina, esse valor visual tende a aparecer como `0` mesmo sob stress com alta emissão de logs.
## Decisao
1. O valor visual `LOGS` exposto ao overlay MUST represent the number of logs emitted during the last completed logical frame.
2. O contador transitório intra-frame MAY continue to exist for internal collection and frame-end aggregation, but it MUST NOT be exposed diretamente como métrica visual do overlay.
3. O `AtomicTelemetry::snapshot()` MUST expose the persisted last-frame value for `logs_count`.
4. A certificação MUST evaluate log pressure against the persisted last completed frame value, not against a host-timing-dependent transient value.
## Rationale
- O overlay precisa de um valor estável e observável pelo Host.
- O frame fechado é a unidade correta para comparação com outras métricas como ciclos e syscalls.
- A mesma semântica serve tanto para overlay quanto para certificação, evitando ambiguidade.
## Invariantes / Contrato
- `logs_count` em `TelemetryFrame` significa `logs from last completed logical frame`.
- O reset do contador transitório não pode apagar o valor persistido exposto ao Host.
- O overlay não deve depender de timing fino entre renderização do Host e fechamento do frame lógico.
## Impactos
- **HAL:** `AtomicTelemetry` precisa persistir o valor de logs do frame concluído.
- **Runtime:** no fechamento do frame, o valor de logs do frame deve ser copiado antes do reset do contador transitório.
- **Host overlay:** nenhuma mudança conceitual adicional além de passar a receber um valor útil e estável.
- **Specs:** capítulo de debug deve deixar explícita a semântica de `logs_count`.
## Referencias
- `AGD-0023`: [PERF] Overlay Log Metric Must Show Last Frame.
- `DEC-0008`: Full Migration to Atomic Telemetry.
- `DEC-0009`: Host Overlay Tooling Boundary.
## Propagacao Necessaria
1. Atualizar `PLN-0008` para incluir a semântica last-frame de `LOGS`.
2. Ajustar HAL e runtime para persistir `logs_count` ao final do frame.
3. Atualizar a especificação de debug.