clean up

discussion/index.ndjson

@@ -15,7 +15,7 @@
 {"type":"discussion","id":"DSC-0010","status":"open","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0009","file":"workflow/agendas/AGD-0009-perf-host-desktop-frame-pacing-and-presentation.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
 {"type":"discussion","id":"DSC-0011","status":"open","ticket":"perf-gfx-render-pipeline-and-dirty-regions","title":"Agenda - [PERF] GFX Render Pipeline and Dirty Regions","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0010","file":"workflow/agendas/AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
 {"type":"discussion","id":"DSC-0012","status":"open","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0011","file":"workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
-{"type":"discussion","id":"DSC-0013","status":"open","ticket":"perf-host-debug-overlay-isolation","title":"Agenda - [PERF] Host Debug Overlay Isolation","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[{"id":"AGD-0012","file":"workflow/agendas/AGD-0012-perf-host-debug-overlay-isolation.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-10"},{"id":"AGD-0022","file":"AGD-0022-host-overlay-tooling-boundary-revision.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"},{"id":"AGD-0023","file":"AGD-0023-overlay-log-metric-last-frame.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0007","file":"workflow/decisions/DEC-0007-perf-host-debug-overlay-isolation.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"},{"id":"DEC-0009","file":"DEC-0009-host-overlay-tooling-boundary.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0022"},{"id":"DEC-0010","file":"DEC-0010-overlay-log-metric-last-frame.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10","ref_agenda":"AGD-0023"}],"plans":[{"id":"PLN-0006","file":"workflow/plans/PLN-0006-perf-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"},{"id":"PLN-0008","file":"PLN-0008-host-overlay-native-composition-alignment.md","status":"in_progress","created_at":"2026-04-10","updated_at":"2026-04-10","ref_decisions":["DEC-0007","DEC-0008","DEC-0009","DEC-0010"]}],"lessons":[{"id":"LSN-0027","file":"lessons/DSC-0013-perf-host-debug-overlay-isolation/LSN-0027-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
+{"type":"discussion","id":"DSC-0013","status":"done","ticket":"perf-host-debug-overlay-isolation","title":"Agenda - [PERF] Host Debug Overlay Isolation","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"lessons/DSC-0013-perf-host-debug-overlay-isolation/LSN-0027-host-debug-overlay-isolation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
 {"type":"discussion","id":"DSC-0024","status":"done","ticket":"generic-memory-bank-slot-contract","title":"Agenda - Generic Memory Bank Slot Contract","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["runtime","asset","memory-bank","slots","host"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0029","file":"lessons/DSC-0024-generic-memory-bank-slot-contract/LSN-0029-slot-first-bank-telemetry-belongs-in-asset-manager.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
 {"type":"discussion","id":"DSC-0014","status":"open","ticket":"perf-vm-allocation-and-copy-pressure","title":"Agenda - [PERF] VM Allocation and Copy Pressure","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0013","file":"workflow/agendas/AGD-0013-perf-vm-allocation-and-copy-pressure.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
 {"type":"discussion","id":"DSC-0015","status":"open","ticket":"perf-cartridge-boot-and-program-ownership","title":"Agenda - [PERF] Cartridge Boot and Program Ownership","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0014","file":"workflow/agendas/AGD-0014-perf-cartridge-boot-and-program-ownership.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}

discussion/workflow/agendas/AGD-0012-perf-host-debug-overlay-isolation.md

@@ -1,49 +0,0 @@
----
-id: AGD-0012
-ticket: perf-host-debug-overlay-isolation
-title: Agenda - [PERF] Host Debug Overlay Isolation
-status: done
-created: 2026-03-27
-resolved: 2026-04-10
-decision: DEC-0007
-tags: [performance, host, gfx]
----
-
-# Agenda - [PERF] Host Debug Overlay Isolation
-
-## Contexto
-O overlay de debug é uma ferramenta exclusiva para o ambiente **Desktop** (`prometeu-host-desktop-winit`). Ele visa fornecer telemetria em tempo real para desenvolvedores sem impactar a fidelidade da emulação ou o desempenho medido do hardware final (handhelds/consoles de baixo custo), onde este overlay não existirá.
-
-## Problema
-Atualmente, o overlay de debug está indevidamente acoplado ao pipeline de `gfx` emulado e ao processamento do runtime.
-- **Distorção de Performance:** O custo de renderizar o HUD técnico (formatação de strings e draw calls extras) é contabilizado como custo do jogo.
-- **Acoplamento de Pipeline:** O pipeline de `gfx` precisa processar elementos que não pertencem à lógica da máquina virtual.
-- **Hotspots:** `runner.rs` realiza `present()` extra e manipulação de texto no loop principal.
-
-## Pontos Críticos
-- **Fato:** O overlay é uma necessidade de desenvolvimento Desktop, não uma funcionalidade da máquina `prometeu`.
-- **Risco:** Qualquer processamento de overlay dentro do runtime `prometeu` invalida a pureza dos ciclos medidos para certificação.
-- **Tradeoff:** Mover o overlay para o Host exige acesso assíncrono ou passivo aos dados de telemetria.
-- **Hipótese:** Um overlay 100% nativo no Host (Winit/Pixels) usando fontes TrueType terá custo desprezível e legibilidade superior.
-
-## Opções
-- **Opção A (Recomendada):** Camada Host Nativa. O `HostRunner` renderiza o HUD em uma surface separada ou faz um *compositing* nativo após o upscaling do framebuffer do console.
-- **Opção B:** Overlay via IPC/Sidecar. Ferramenta externa de inspeção (descartada por complexidade visual).
-- **Opção C:** Manter no `gfx` emulado com otimização (descartada por não resolver o acoplamento).
-
-## Sugestão / Recomendação
-1. **Agnosticismo de GFX:** O overlay deve ser tratado como uma "película" transparente aplicada pelo Host Desktop sobre o resultado final da renderização.
-2. **Isolamento de Processamento:** Nenhuma instrução de desenho ou formatação de strings do overlay deve ocorrer dentro do runtime.
-3. **Acesso via API:** O Host acessará os dados de telemetria através de uma API dedicada (baseada no modelo push-based da `DEC-0005`).
-4. **Interface de Controle:** O acionamento permanece via tecla **F1** como um *toggle*, gerenciado pela camada de Host.
-5. **Composição via Host:** Utilizar bibliotecas nativas do Host para renderizar o HUD com fontes TrueType nítidas e Alpha Blending real.
-
-## Perguntas em Aberto
-- Nenhuma. As questões sobre acesso via API e acionamento via F1 foram resolvidas durante a discussão.
-
-## Critério para Encerrar
-A agenda é considerada encerrada quando:
-- Houver consenso sobre o isolamento total do pipeline de `gfx`.
-- O método de acesso aos dados (API) estiver definido.
-- O controle de interface (F1) estiver estabelecido.
-*(Critérios atingidos em 2026-04-10)*

discussion/workflow/agendas/AGD-0021-full-migration-to-atomic-telemetry.md

@@ -1,31 +0,0 @@
-# AGD-0021: Full Migration to Atomic Telemetry
-
-## Contexto
-Durante a implementação do isolamento do overlay de debug no Host Desktop (DEC-0007), foi introduzido o `AtomicTelemetry` para permitir acesso assíncrono e sem locks aos dados de performance. Por motivos de cautela inicial, os campos legados `telemetry_current` e `telemetry_last` foram mantidos no `VirtualMachineRuntime` para compatibilidade com processos de certificação e logs internos.
-
-## Problema
-A manutenção de dois sistemas paralelos de telemetria gera redundância de código, aumenta a superfície de erro e consome ciclos de CPU desnecessários para atualizar dados que já estão disponíveis de forma mais eficiente via atômicos. A "compatibilidade" pretendida não justifica o débito técnico de manter estruturas duplicadas.
-
-## Pontos Críticos
-- **Fato:** `AtomicTelemetry` já provê todos os dados necessários (ciclos, memória, logs).
-- **Risco:** Remoção de `telemetry_last` pode quebrar ferramentas que dependem de snapshots estáticos por frame se não houver um substituto claro de snapshot via atômicos.
-- **Tradeoff:** A migração exige refatorar o `VirtualMachineRuntime` e possivelmente o `LogService` para convergirem em uma única fonte de verdade.
-- **Hipótese:** Um snapshot derivado do `AtomicTelemetry` ao final de cada frame é suficiente para substituir o `telemetry_last` legado sem perda de precisão.
-
-## Opções
-- **Opção A (Recomendada):** Migração total e remoção dos campos legados. O `AtomicTelemetry` torna-se a única fonte de verdade. Onde snapshots estáveis são necessários, eles são extraídos via `AtomicTelemetry::snapshot()`.
-- **Opção B:** Manter redundância (Descartada pelo usuário).
-
-## Sugestão / Recomendação
-1. Remover `telemetry_current` e `telemetry_last` do `VirtualMachineRuntime`.
-2. Refatorar o loop de execução para atualizar exclusivamente o `AtomicTelemetry`.
-3. Garantir que o `LogService` e outras auditorias consumam dados do novo modelo.
-4. Atualizar as especificações para refletir o modelo único.
-
-## Perguntas em Aberto
-1. Existe algum uso específico de `telemetry_last` em ferramentas externas (não mapeadas) que dependem do layout de memória antigo? (Assumimos que não para este escopo).
-
-## Criterio para Encerrar
-- Remoção completa dos campos no código.
-- Compilação e execução bem-sucedida do Host Desktop com o novo modelo único.
-- Atualização da documentação normativa.

discussion/workflow/agendas/AGD-0022-host-overlay-tooling-boundary-revision.md

@@ -1,96 +0,0 @@
----
-id: AGD-0022
-ticket: perf-host-debug-overlay-isolation
-title: Agenda - [PERF] Host Overlay Tooling Boundary Revision
-status: accepted
-created: 2026-04-10
-resolved: 2026-04-10
-decision: DEC-0009
-tags: [performance, host, gfx, overlay]
----
-
-# Agenda - [PERF] Host Overlay Tooling Boundary Revision
-
-## Contexto
-
-`DEC-0007` fechou o movimento do overlay de debug para o `Host Desktop`, fora do runtime e fora do pipeline de `gfx` emulado. Durante a execução, a formulação acabou ficando forte demais em um ponto: passou a sugerir que `fill_rect` e `draw_text` deveriam deixar de existir no contrato atual, quando na verdade o usuário quer preservar essas ferramentas como parte válida do contrato de syscall atual.
-
-O ajuste pedido agora é mais específico:
-- `fill_rect` e `draw_text` permanecem como parte do contrato atual da máquina e continuam disponíveis para uso legítimo do software emulado;
-- o overlay técnico de host não pode depender desse caminho;
-- o overlay deve possuir ferramentas próprias para compor o que for necessário no host, fora do `hardware.gfx`.
-
-## Problema
-
-Sem registrar essa revisão, a execução fica ambígua em dois pontos:
-- podemos remover ou enfraquecer APIs gráficas que não deveriam ser tocadas;
-- podemos continuar interpretando o overlay host como “qualquer desenho fora do runtime”, mesmo se ele ainda reutilizar primitives do hardware emulado.
-
-O resultado é ruído entre contrato da máquina, contrato do host, e ferramentas de inspeção.
-
-## Pontos Criticos
-
-- **Fato:** O overlay continua sendo exclusivo do host desktop.
-- **Fato:** `fill_rect` e `draw_text` fazem parte do contrato atual de syscall e não devem ser removidos por causa do overlay.
-- **Risco:** Se o host overlay continuar apoiado em `hardware.gfx`, ele continua contaminando o framebuffer emulado.
-- **Risco:** Se criarmos “tools próprias” sem delimitar bem a fronteira, podemos introduzir um mini-subsistema paralelo sem contrato claro.
-- **Tradeoff:** Preservar o contrato atual da máquina simplifica compatibilidade, mas exige um caminho de composição separado no host para não misturar domínio emulado com inspeção técnica.
-
-## Opcoes
-
-- **Opção A (Recomendada):** Preservar `fill_rect`/`draw_text` como contrato do hardware emulado e criar um conjunto de ferramentas nativas do host para o overlay.
-  - O overlay passa a usar renderer/layout/composição próprios do host.
-  - O runtime continua apenas expondo dados.
-  - O `hardware.gfx` fica reservado ao conteúdo da máquina emulada.
-
-- **Opção B:** Generalizar `fill_rect`/`draw_text` para servirem também ao host overlay.
-  - Reaproveita código existente.
-  - Mantém o acoplamento semântico entre overlay técnico e hardware emulado.
-  - Dificulta provar pureza do framebuffer.
-
-- **Opção C:** Criar novas syscalls específicas de overlay no runtime.
-  - Formaliza ferramentas novas, mas empurra responsabilidade de inspeção para dentro da máquina.
-  - Viola a direção de host-only já aceita e reabre debate maior do que o necessário.
-
-## Sugestao / Recomendacao
-
-Seguir com a **Opção A** e revisar a decisão operacional nestes termos:
-
-1. `fill_rect` e `draw_text` permanecem intactos como parte do contrato atual de syscall e do hardware emulado.
-2. O overlay técnico do desktop host não pode chamar nem depender dessas primitives do `hardware.gfx`.
-3. O host deve ter ferramentas próprias de overlay, com responsabilidades explícitas:
-   - montagem dos dados exibidos;
-   - layout do painel;
-   - rasterização/composição nativa;
-   - controle visual de transparência e tipografia.
-4. O runtime continua responsável apenas por telemetria e sinais de inspeção, nunca por desenho do overlay.
-5. A validação precisa provar dois limites:
-   - o contrato gráfico emulado continua disponível;
-   - o overlay técnico não escreve no framebuffer emulado.
-
-Para este ciclo, o overlay deve permanecer deliberadamente simples:
-- painel semitransparente;
-- texto para métricas e estados;
-- barras básicas para uso relativo de orçamento/capacidade quando isso melhorar leitura;
-- sem badges decorativos, widgets complexos, docking, janelas móveis, ou mini-framework de UI.
-
-Essa direção preserva o objetivo principal do ticket, que é a fronteira arquitetural correta, sem transformar o host overlay em um projeto próprio.
-
-## Perguntas em Aberto
-
-- A implementação deve ficar embutida em `runner.rs` inicialmente ou nascer como módulo dedicado (`overlay.rs`) desde o começo?
-- A composição será feita diretamente no buffer final do `pixels` ou via camada/render pass separada dentro do host?
-Nenhuma. Em 2026-04-10 foi acordado:
-- módulo dedicado para o overlay;
-- camada separada no host;
-- sem blit do overlay no framebuffer emulado;
-- o framebuffer emulado pode ser transportado para a surface/camada de overlay do host, nunca o contrário.
-
-## Criterio para Encerrar
-
-Esta agenda pode ser encerrada quando houver consenso explícito sobre:
-- preservação de `fill_rect` e `draw_text` no contrato atual;
-- proibição de uso dessas primitives pelo overlay técnico;
-- conjunto mínimo de ferramentas próprias do overlay no host;
-- ponto exato de composição no pipeline do desktop host.
-*(Critérios atingidos em 2026-04-10)*

discussion/workflow/agendas/AGD-0023-overlay-log-metric-last-frame.md

@@ -1,53 +0,0 @@
----
-id: AGD-0023
-ticket: perf-host-debug-overlay-isolation
-title: Agenda - [PERF] Overlay Log Metric Must Show Last Frame
-status: accepted
-created: 2026-04-10
-resolved: 2026-04-10
-decision: DEC-0010
-tags: [performance, host, telemetry, logs]
----
-
-# Agenda - [PERF] Overlay Log Metric Must Show Last Frame
-
-## Contexto
-
-Após mover o overlay para a camada de Host, o campo visual `LOGS` passou a expor um contador transitório compartilhado com o `LogService`. Esse contador é incrementado durante o frame e zerado no fechamento do frame lógico. Na prática, quando o Host lê a telemetria para desenhar o overlay, o valor visual tende a aparecer como `0`, mesmo em cenários com alta emissão de logs.
-
-## Problema
-
-O campo `LOGS` no overlay não está representando a informação útil para inspeção visual. Um valor transitório intra-frame é adequado para coleta interna, mas não para HUD técnico renderizado assíncronamente pelo Host.
-
-## Pontos Criticos
-
-- **Fato:** O Host lê a telemetria fora do momento exato em que o contador transitório atinge seu pico.
-- **Fato:** A certificação precisa continuar vendo a pressão de logs do frame completo.
-- **Risco:** Manter a semântica atual torna o campo visual enganoso e inutilizável.
-- **Tradeoff:** Precisamos preservar o contador transitório para coleta interna, mas expor ao overlay apenas um valor persistido do último frame fechado.
-
-## Opcoes
-
-- **Opção A (Recomendada):** Persistir `logs from last completed frame` no `AtomicTelemetry` e fazer o overlay ler apenas esse valor.
-- **Opção B:** Manter contador ao vivo e tentar amostrar em outro ponto do loop.
-- **Opção C:** Mostrar ambos os valores no overlay.
-
-## Sugestao / Recomendacao
-
-Seguir com a **Opção A**:
-
-1. O contador transitório de logs continua existindo apenas para coleta interna durante o frame.
-2. No fechamento do frame lógico, o runtime persiste em `AtomicTelemetry` o total de logs do frame recém-concluído.
-3. O campo `LOGS` visível no overlay deve representar exclusivamente `logs from last completed frame`.
-4. A certificação deve continuar operando sobre esse mesmo valor persistido do frame concluído.
-
-## Perguntas em Aberto
-
-- Nenhuma. Em 2026-04-10 foi decidido que o overlay deve mostrar apenas logs do último frame concluído.
-
-## Criterio para Encerrar
-
-- semântica visual de `LOGS` definida como `last completed frame`;
-- certificação preservada;
-- implementação alinhada no HAL, runtime, overlay e specs.
-*(Critérios atingidos em 2026-04-10)*

discussion/workflow/decisions/DEC-0007-perf-host-debug-overlay-isolation.md

@@ -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/`.

discussion/workflow/decisions/DEC-0008-full-migration-to-atomic-telemetry.md

@@ -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).

discussion/workflow/decisions/DEC-0009-host-overlay-tooling-boundary.md

@@ -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.

discussion/workflow/decisions/DEC-0010-overlay-log-metric-last-frame.md

@@ -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.

discussion/workflow/plans/PLN-0006-perf-host-debug-overlay-isolation.md

@@ -1,64 +0,0 @@
----
-id: PLN-0006
-ticket: perf-host-debug-overlay-isolation
-title: PR/Plan - [PERF] Host Debug Overlay Isolation
-status: open
-created: 2026-04-10
-updated: 2026-04-10
-decisions: [DEC-0007]
-tags: [performance, host, gfx]
----
-
-# PR/Plan - [PERF] Host Debug Overlay Isolation
-
-## Briefing
-Implementação do isolamento total do overlay de debug no Host Desktop (`prometeu-host-desktop-winit`), removendo o acoplamento com o runtime e o pipeline de `gfx` emulado.
-
-## Decisions de Origem
-- `DEC-0007`: [PERF] Host Debug Overlay Isolation.
-- `DEC-0005`: [PERF] Push-based Telemetry Model (base para extração de dados).
-
-## Alvo
-- `crates/host/prometeu-host-desktop-winit`: Implementação da camada nativa de HUD.
-- `crates/runtime`: Exposição de campos de telemetria via API.
-- `docs/specs/runtime`: Atualização das especificações de debug e portabilidade.
-
-## Escopo
-- **Spec Work:**
-    - Atualizar `docs/specs/runtime/10-debug-inspection-and-profiling.md` para remover menções ao HUD emulado.
-    - Atualizar `docs/specs/runtime/11-portability-and-cross-platform-execution.md` para reforçar a separação de responsabilidades (Host-side HUD).
-- **Code Work:**
-    - Expansão da API de telemetria no runtime para incluir todos os dados necessários (Cycles, Memory, Logs).
-    - Remoção do código de desenho de texto legado no `runner.rs`.
-    - Integração de biblioteca nativa (ex: `egui` ou composição via `pixels`) para renderização do novo overlay no Host.
-    - Implementação do toggle via tecla **F1** no `HostRunner`.
-
-## Fora de Escopo
-- Implementação de overlay visual em outros hosts (mobile, handheld).
-- Alterações na lógica de emulação central (loop de execução).
-
-## Plano de Execucao
-1. **Fase 1: Especificações (Spec)**
-    - Revisar e atualizar os arquivos de especificação (`10-debug` e `11-portability`).
-2. **Fase 2: Runtime Telemetry API (Code)**
-    - Garantir que todos os campos de telemetria estejam expostos via atômicos/push-based conforme `DEC-0005`.
-3. **Fase 3: Host HUD Implementation (Code)**
-    - Integrar o novo motor de HUD no `prometeu-host-desktop-winit`.
-    - Conectar os dados da API de telemetria à visualização do HUD.
-4. **Fase 4: Cleanup (Code)**
-    - Remover hotspots de formatação de strings e draw calls do overlay antigo no Host.
-
-## Criterios de Aceite
-- O overlay de debug é ativado/desativado via tecla **F1**.
-- O overlay utiliza fontes TrueType (monospaced) nítidas e fundo semi-transparente.
-- O framebuffer emulado não contém pixels do HUD (composição nativa pós-upscaling).
-- O custo de ciclos do runtime é idêntico com o overlay ligado ou desligado.
-
-## Tests / Validacao
-- **Verificação Visual:** Confirmar a qualidade das fontes e a transparência do novo HUD.
-- **Benchmarking:** Comparar os ciclos consumidos por frame com e sem o HUD ativo para provar isolamento.
-- **Teste de Regressão:** Garantir que o F1 toggle não afeta a estabilidade do loop de emulação.
-
-## Riscos
-- **Overhead no Host:** A renderização nativa (ex: `egui`) pode introduzir overhead no Host Desktop em máquinas muito fracas (geralmente aceitável em Desktop).
-- **Sincronização de Telemetria:** Pequeno atraso visual entre o frame renderizado e os dados exibidos se a coleta for puramente assíncrona (aceitável para telemetria de debug).

discussion/workflow/plans/PLN-0007-full-migration-to-atomic-telemetry.md

@@ -1,52 +0,0 @@
-# PLN-0007: Full Migration to Atomic Telemetry
-
-## Briefing
-Este plano detalha a remoção técnica dos campos legados de telemetria no `VirtualMachineRuntime` e a migração de todos os consumidores para o modelo de `AtomicTelemetry` introduzido na DEC-0007.
-
-## Decisions de Origem
-- DEC-0008 (Full Migration to Atomic Telemetry)
-- DEC-0007 (Host Debug Overlay Isolation)
-
-## Alvo
-- `crates/console/prometeu-system`
-- `crates/console/prometeu-hal`
-- `crates/host/prometeu-host-desktop-winit`
-
-## Escopo
-- Remoção de `telemetry_current` e `telemetry_last` de `VirtualMachineRuntime`.
-- Refatoração do `VirtualMachineRuntime::tick` para remover atualizações redundantes.
-- Atualização do `VirtualMachineRuntime::lifecycle` para remover inicialização e reset dos campos legados.
-- Refatoração do `LogService` para consumir logs via `AtomicTelemetry`.
-- Atualização do `HostRunner` (Desktop) para remover qualquer referência residual aos campos legados.
-- Atualização das especificações técnicas em `docs/specs/runtime/`.
-
-## Fora de Escopo
-- Mudanças no formato do `TelemetryFrame` (a menos que estritamente necessário para compatibilidade).
-- Otimizações de performance não relacionadas à telemetria.
-
-## Plano de Execucao
-1. **Fase 1: HAL & Telemetry**
-   - Verificar se `AtomicTelemetry` possui todos os campos necessários.
-   - Garantir que `LogService` está alinhado com o novo modelo.
-2. **Fase 2: Runtime Refactor**
-   - Remover campos de `VirtualMachineRuntime` em `mod.rs`.
-   - Limpar inicialização em `lifecycle.rs`.
-   - Limpar loop de atualização em `tick.rs`.
-3. **Fase 3: Host & Integration**
-   - Corrigir chamadas no `HostRunner` que ainda usem os campos antigos.
-   - Validar que o snapshot atômico atende às necessidades de inspeção.
-4. **Fase 4: Specs & Cleanup**
-   - Atualizar `10-debug` e `11-portability`.
-   - Emitir lição aprendida LSN-0028.
-
-## Criterios de Aceite
-- O projeto compila sem warnings relacionados a campos não utilizados.
-- O Host Desktop inicia e o overlay (F1) exibe telemetria correta via atômicos.
-- Não existem mais os campos `telemetry_current` e `telemetry_last` no código fonte.
-
-## Tests / Validacao
-- `cargo check` em todos os crates afetados.
-- Execução manual do host desktop para validar overlay.
-
-## Riscos
-- **Perda de Snapshot de Frame:** Se o `snapshot()` não for chamado no momento certo ao final do frame, o overlay pode mostrar valores parciais de ciclos (resolvido chamando `snapshot()` no Host no momento de renderização do overlay).

discussion/workflow/plans/PLN-0008-host-overlay-native-composition-alignment.md

@@ -1,144 +0,0 @@
----
-id: PLN-0008
-ticket: perf-host-debug-overlay-isolation
-title: PR/Plan - Host Overlay Native Composition Alignment
-status: in_progress
-created: 2026-04-10
-completed:
-tags: [performance, host, gfx, telemetry]
----
-
-## Objective
-
-Bring the desktop debug overlay implementation back into compliance with `DEC-0007`, `DEC-0009`, and `DEC-0010` by keeping the overlay in the host layer while rendering it in a dedicated host module and separate host layer, outside the emulated hardware framebuffer and outside `hardware.gfx`.
-
-## Background
-
-`DEC-0007` requires the debug overlay to be a host-only layer composed after the emulated frame is complete. `DEC-0009` further clarifies that `fill_rect` and `draw_text` remain part of the emulated machine contract, but the host overlay must not depend on them and must live in a dedicated host module and separate host layer. `DEC-0010` fixes the semantics of the visible `LOGS` metric so the Host overlay reads the last completed frame value instead of a transient intra-frame counter.
-
-The current `HostRunner` still calls `hardware.gfx.fill_rect()` and `hardware.gfx.draw_text()` for the overlay, which means the HUD is still being injected into the emulated graphics path even though its data source already comes from `AtomicTelemetry`.
-
-`PLN-0007` completed the telemetry migration, so the remaining gap is no longer data access. The remaining gap is presentation architecture in the desktop host.
-
-## Scope
-
-### Included
-- Remove all overlay rendering calls that write through `hardware.gfx`.
-- Introduce a desktop-host-native overlay composition path in `prometeu-host-desktop-winit`.
-- Implement the overlay in a dedicated host module instead of ad hoc logic inside `runner.rs`.
-- Keep overlay visibility and lifecycle fully controlled by the desktop host.
-- Continue reading inspection data through `AtomicTelemetry::snapshot()` and host-side log access.
-- Expose `LOGS` to the overlay as the last completed logical frame value.
-- Update runtime specifications so they explicitly state that the overlay is host-native and not part of the emulated machine framebuffer.
-- Add verification that enabling the overlay does not mutate emulated pixels.
-
-### Excluded
-- Adding overlays to non-desktop hosts.
-- Reopening the telemetry model or changing `TelemetryFrame` semantics.
-- Reworking unrelated presentation, frame pacing, debugger transport, or certification behavior.
-
-## Execution Steps
-
-### Step 1 - Extract overlay responsibilities into a dedicated host module
-
-**What:**
-Move overlay formatting, layout, and drawing responsibilities out of `runner.rs` and into a dedicated host module.
-
-**How:**
-Create a dedicated module such as `overlay.rs` that owns host overlay data preparation, panel layout, simple bars, and text rendering. `runner.rs` should orchestrate visibility and presentation only. The new module must never call emulated graphics primitives.
-
-**File(s):**
-- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
-- `crates/host/prometeu-host-desktop-winit/src/stats.rs`
-- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
-
-### Step 2 - Compose the overlay in a separate host layer
-
-**What:**
-Ensure the overlay is rendered in a separate host layer/surface and never blitted into the emulated framebuffer.
-
-**How:**
-Preserve the `F1` toggle in `HostRunner`, keep telemetry reads on the host side, and present the overlay after the emulated frame is already ready for display. The implementation may transport the emulated framebuffer into the host presentation surface, but the overlay must remain a separate host composition step and must not write back into `hardware.gfx`.
-
-**File(s):**
-- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
-- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
-
-### Step 3 - Add regression coverage for framebuffer purity
-
-**What:**
-Add tests or deterministic checks that prove the overlay no longer modifies emulated graphics output.
-
-**How:**
-Cover the overlay toggle and composition boundary with focused host tests where practical. At minimum, add a test seam or helper that lets the host render path be exercised without requiring overlay drawing through `hardware.gfx`. If a full automated framebuffer assertion is not practical yet, add a narrow unit test around the new composition entry point plus manual verification instructions that compare raw emulated output with overlay enabled and disabled.
-
-**File(s):**
-- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
-- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
-- `crates/host/prometeu-host-desktop-winit/src/tests.rs` or existing test module location
-
-### Step 4 - Align log metric semantics with frame-end snapshots
-
-**What:**
-Ensure the visible `LOGS` metric represents the last completed frame instead of a transient in-flight counter.
-
-**How:**
-Persist the completed-frame log count into `AtomicTelemetry` before resetting the transient `LogService` counter. Keep certification evaluation and host overlay consumption aligned on that persisted frame-end value.
-
-**File(s):**
-- `crates/console/prometeu-hal/src/log/log_service.rs`
-- `crates/console/prometeu-hal/src/telemetry.rs`
-- `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs`
-- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
-
-### Step 5 - Update normative documentation
-
-**What:**
-Align specs and workflow artifacts with the corrected execution path.
-
-**How:**
-Update the runtime debug and portability specifications to explicitly say the overlay is desktop-host-native, post-upscaling, and outside the emulated framebuffer. Keep the discussion workflow aligned by referencing this corrective plan during execution and closure.
-
-**File(s):**
-- `docs/specs/runtime/10-debug-inspection-and-profiling.md`
-- `docs/specs/runtime/11-portability-and-cross-platform-execution.md`
-
-## Test Requirements
-
-### Unit Tests
-- Host overlay toggle logic remains host-owned and does not require `hardware.gfx` text drawing.
-- New host-native overlay composition entry point can format and present telemetry without mutating the emulated framebuffer abstraction.
-- Simple bars and text layout are owned by the dedicated host overlay module.
-
-### Integration Tests
-- `cargo check` for `prometeu-host-desktop-winit`, `prometeu-system`, and any touched supporting crate.
-- If automated host rendering tests are feasible, verify an emulated frame buffer dump is identical with overlay off and overlay on before the host-only composition stage.
-
-### Manual Verification
-- Run the desktop host, toggle `F1`, and confirm the overlay appears and disappears correctly.
-- Capture or inspect the emulated framebuffer path and confirm no HUD pixels are written into machine output.
-- Confirm telemetry values still update through `AtomicTelemetry`.
-
-## Acceptance Criteria
-
-- [ ] No desktop overlay code writes through `hardware.gfx.fill_rect`, `hardware.gfx.draw_text`, or equivalent emulated-machine drawing APIs.
-- [ ] `fill_rect` and `draw_text` remain intact as part of the emulated graphics contract and are not repurposed for host overlay rendering.
-- [ ] The desktop overlay remains controlled by `HostRunner` and uses host-side telemetry snapshots.
-- [ ] The visible overlay is composed in a separate host layer after the emulated frame and is not burned into the emulated framebuffer.
-- [ ] Runtime telemetry remains gated by inspection state and continues to function for overlay consumption.
-- [ ] The visible `LOGS` metric represents the last completed logical frame.
-- [ ] Specs describe the overlay as host-native and outside the emulated hardware contract.
-
-## Dependencies
-
-- `DEC-0007` accepted and unchanged.
-- `DEC-0008` accepted and unchanged.
-- `DEC-0009` accepted and unchanged.
-- `DEC-0010` accepted and unchanged.
-- Existing `AtomicTelemetry` host snapshot path remains available.
-
-## Risks
-
-- Desktop-native text and alpha composition may require extra host rendering plumbing that is more complex than the previous `hardware.gfx` path.
-- Without an explicit test seam, it is easy to accidentally reintroduce overlay writes into the emulated graphics path during future host refactors.
-- Host composition cost may rise slightly, but that cost is acceptable as long as it remains outside runtime cycle accounting.