discussion framework migration

This commit is contained in:
2026-03-27 04:54:27 +00:00
parent 7e3e8c81f5
commit 6b08633798
18 changed files with 194 additions and 92 deletions
+17 -1
View File
@@ -1,2 +1,18 @@
{"type":"meta","next_id":{"DSC":2,"AGD":1,"DEC":1,"PLN":1,"LSN":19,"CLSN":1}}
{"type":"meta","next_id":{"DSC":18,"AGD":17,"DEC":1,"PLN":1,"LSN":19,"CLSN":1}}
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0001","file":"AGD-0001-runtime-edge-test-plan.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0002","file":"AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0003","file":"AGD-0003-system-run-cart.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0008","status":"open","ticket":"perf-runtime-telemetry-hot-path","title":"Agenda - [PERF] Runtime Telemetry Hot Path","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0007","file":"AGD-0007-perf-runtime-telemetry-hot-path.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0008","file":"AGD-0008-perf-async-background-work-lanes-for-assets-and-fs.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"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":"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":"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":"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-03-27","tags":[],"agendas":[{"id":"AGD-0012","file":"AGD-0012-perf-host-debug-overlay-isolation.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"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":"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":"AGD-0014-perf-cartridge-boot-and-program-ownership.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0016","status":"open","ticket":"tilemap-empty-cell-vs-tile-id-zero","title":"Tilemap Empty Cell vs Tile ID Zero","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0015","file":"AGD-0015-tilemap-empty-cell-vs-tile-id-zero.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0017","status":"open","ticket":"asset-entry-metadata-normalization-contract","title":"Asset Entry Metadata Normalization Contract","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0016","file":"AGD-0016-asset-entry-metadata-normalization-contract.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
@@ -0,0 +1,86 @@
---
id: AGD-0001
ticket: runtime-edge-test-plan
title: Agenda - Runtime Edge Test Plan
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - Runtime Edge Test Plan
## Problema
O core da VM está muito melhor testado do que a borda do runtime.
O miolo já cobre verificador, scheduler, GC, patching e execução básica. Já a camada de syscalls de sistema, FS, assets, bank e fluxos de firmware ainda tem cobertura desigual e rasa.
## Dor
- A parte mais sujeita a integração com host é justamente a menos protegida.
- Regressões na borda podem passar com o core inteiro verde.
- O projeto ganha falsa sensação de maturidade porque o núcleo está sólido, mas a superfície pública do runtime ainda pode quebrar com facilidade.
- Sem matriz de testes da borda, futuras PRs tendem a cobrir só o happy path.
## Alvo da Discussao
Definir um plano de testes para a borda do runtime proporcional ao risco da plataforma.
Essa agenda deve produzir uma visão clara de:
- quais domínios precisam de testes;
- qual nível de teste pertence a cada domínio;
- quais cenários são mandatórios antes de chamar o runtime de estável.
## O Que Precisa Ser Definido
1. Matriz de cobertura por domínio.
- system
- fs
- log
- asset
- bank
- firmware transitions
2. Tipos de teste.
- unitário puro
- integração entre runtime e VM
- testes de firmware
- testes host-dependentes isolados
3. Casos obrigatórios.
Cada domínio precisa definir:
- happy path;
- erro de contrato do guest;
- indisponibilidade/estado inválido do host;
- persistência/cleanup de estado quando aplicável.
4. Critério de severidade.
Que mudanças exigem teste novo obrigatório antes de merge.
5. Organização.
Onde os testes vivem para nao voltar a concentrar tudo em arquivos gigantes.
## O Que Necessita Para Resolver
- inventário da cobertura atual;
- definição dos cenários obrigatórios por domínio;
- política mínima para testes ignorados ou dependentes de host;
- decisão sobre helpers compartilhados para fixtures de runtime.
## Fora de Escopo
- benchmark/performance suite;
- fuzzing completo de toda a ISA;
- infraestrutura externa de CI além do necessário para os testes definidos.
## Critério de Saida Desta Agenda
Pode virar PR quando houver:
- matriz de cobertura aprovada;
- lista de cenários mínimos por domínio;
- decisão de organização dos testes;
- barra clara para aceitar novas syscalls e mudanças de runtime.
@@ -0,0 +1,86 @@
---
id: AGD-0002
ticket: packed-cartridge-loader-pmc
title: Agenda - Packed Cartridge Loader PMC
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - Packed Cartridge Loader PMC
## Problema
O loader reconhece a extensão `.pmc`, mas o caminho empacotado ainda nao existe de verdade.
Hoje o dispatcher aceita a intenção e delega para um loader que sempre falha com `InvalidFormat`.
## Dor
- A plataforma declara dois formatos de entrada, mas só um funciona.
- Distribuição real de cartuchos fica travada no layout de diretório.
- Host, firmware e ferramentas nao conseguem validar o caminho de distribuição final.
- O runtime continua dependente de estrutura de workspace em vez de artefato fechado.
## Alvo da Discussao
Definir o formato e o contrato do cartucho empacotado `.pmc` como artefato de distribuição do runtime.
O objetivo nao é só "descompactar um zip", e sim fixar:
- layout interno;
- regras de validação;
- limites de compatibilidade;
- superfície de erro;
- impacto em assinatura/versionamento futuro.
## O Que Precisa Ser Definido
1. Container.
O `.pmc` é zip, tar, formato próprio, ou envelope simples com header e blobs?
2. Estrutura interna.
Quais arquivos são obrigatórios e opcionais:
- `manifest.json`
- `program.pbx`
- `assets.pa`
- outros metadados
3. Regras de validação.
Ordem de parsing, integridade, presença de arquivos, tamanho máximo, duplicatas e versão suportada.
4. Política de compatibilidade.
Como o loader reage a versões futuras do container e do manifesto.
5. Segurança e determinismo.
Como impedir traversal, nomes ambíguos, arquivos extras maliciosos e dependência da ordem física do container.
6. Relação com o loader de diretório.
O comportamento validado deve ser idêntico entre diretório e `.pmc`, mudando apenas a origem dos bytes.
## O Que Necessita Para Resolver
- especificação mínima do container `.pmc`;
- decisão sobre biblioteca/abordagem de parsing;
- matriz de erros determinísticos;
- testes com cartuchos sintéticos válidos e inválidos;
- garantia de equivalência comportamental com o loader de diretório.
## Fora de Escopo
- compressão otimizada;
- assinatura criptográfica;
- distribuição incremental;
- pipeline completo do builder/packer.
## Critério de Saida Desta Agenda
Pode virar PR quando houver definição escrita de:
- formato do `.pmc`;
- arquivos obrigatórios;
- erros canônicos;
- invariantes de segurança;
- estratégia de testes de compatibilidade entre diretório e pacote.
@@ -0,0 +1,94 @@
---
id: AGD-0003
ticket: system-run-cart
title: Agenda - System Run Cart
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - System Run Cart
## Problema
A syscall `system.run_cart` existe na ABI pública, mas hoje não produz efeito real no runtime.
Isso cria uma falsa promessa de plataforma:
- o programa consegue declarar e chamar a syscall;
- o loader aceita sua existência;
- o runtime retorna sucesso vazio;
- nenhuma troca de cartucho, transição de firmware, validação de alvo ou política de segurança ocorre.
## Dor
- A ABI expõe uma capability de sistema que, na prática, nao existe.
- O guest pode acreditar que solicitou uma troca de app quando nada aconteceu.
- Isso corrói a confiabilidade da plataforma: a interface pública deixa de ser contrato e vira placebo.
- Qualquer ferramenta, SDK ou documentação construída sobre essa syscall passa a modelar um comportamento inexistente.
## Alvo da Discussao
Definir o contrato real de `system.run_cart` do ponto de vista:
- do guest;
- do runtime;
- do firmware;
- do host/cartridge loader.
Ao final da discussão, deve ficar claro se a syscall:
- permanece na ABI e ganha implementação completa; ou
- sai temporariamente da ABI até existir fluxo fechado.
## O Que Precisa Ser Definido
1. Semântica da operação.
O que significa "run cart": trocar imediatamente, agendar para o próximo frame, retornar ao firmware, reiniciar VM atual, ou apenas emitir uma intenção?
2. Origem do alvo.
Como o guest identifica o cartucho alvo: id numérico, nome canônico, path virtual, handle, manifesto, ou nenhum argumento nesta primeira versão?
3. Modelo de segurança.
Quem pode chamar isso, sob qual capability, e com quais restrições para evitar que um app force navegação arbitrária do sistema?
4. Ponto de integração.
Onde a transição vive: `VirtualMachineRuntime`, firmware, host, ou combinação dos três?
5. Efeitos observáveis.
O que acontece com:
- estado do app atual;
- FS aberto;
- assets carregados;
- telemetria;
- crash reports;
- logs.
6. Contrato de erro.
Quais falhas retornam trap ao guest e quais viram evento de sistema.
## O Que Necessita Para Resolver
- fluxo fechado entre syscall -> runtime -> firmware -> loader -> novo app;
- modelo explícito para seleção do alvo;
- definição de lifecycle da troca de cartucho;
- testes de integração cobrindo transição bem-sucedida, alvo inválido, capability insuficiente e cleanup de estado.
## Fora de Escopo
- catálogo completo de apps instalados;
- UX final do launcher/hub;
- resolução remota ou download de cartuchos;
- política de marketplace/distribuição.
## Critério de Saida Desta Agenda
Esta agenda só pode virar PR de implementação quando existir decisão escrita para:
- assinatura final da syscall;
- local canônico da troca de estado;
- política de erro;
- limpeza de recursos;
- cobertura mínima de testes de integração.
@@ -0,0 +1,65 @@
---
id: AGD-0004
ticket: system-fault-semantics-and-control-surface
title: Agenda - System Fault Semantics and Control Surface
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - System Fault Semantics and Control Surface
## Problema
O dominio `system` e pequeno, mas mistura consulta simples com superficie de controle de fluxo.
Hoje:
- `SystemHasCart` responde diretamente;
- `SystemRunCart` ainda nao tem efeito real;
- a agenda `009` resolve semantica funcional, mas nao fecha por si so a politica de fault do dominio.
## Dor
- sem uma agenda propria, `system` pode herdar fault semantics por acidente;
- `run_cart` pode acabar consolidando `Panic` ou `Trap` onde deveria existir retorno operacional;
- a fronteira entre falha do app, falha do firmware e falha do runtime fica opaca.
## Hotspots Atuais
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L114)
- [system.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/syscalls/domains/system.rs#L4)
- [009-system-run-cart.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/runtime/agendas/009-system-run-cart.md)
## Alvo da Discussao
Fechar a politica de fault e retorno do dominio `system`.
## O Que Precisa Ser Definido
1. Queries simples.
Decidir a politica de fault para consultas como `has_cart`.
2. `run_cart`.
Decidir como falhas operacionais de transicao devem ser expostas:
- `status`;
- `Trap`;
- `Panic`.
3. Relacao com firmware.
Delimitar quando a falha pertence ao app, ao firmware ou ao runtime.
## Dependencias
- `../specs/16a-syscall-policies.md`
- `009-system-run-cart.md`
## Critério de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- matriz de `status`/`Trap`/`Panic` para `system`;
- politica de retorno/falha de `run_cart`;
- relacao com firmware e crash surface.
@@ -0,0 +1,79 @@
---
id: AGD-0005
ticket: vm-owned-random-service
title: Agenda - VM-Owned Random Service
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - VM-Owned Random Service
## Problema
Precisamos de random como primeiro consumidor stateful VM-owned, mas sem fechar um contrato minimo o dominio pode nascer incoerente e nao deterministico.
## Alvo da Discussao
Fechar o perfil minimo de random VM-owned em cima do core definido na decisao `006`.
## O Que Precisa Ser Definido
1. Surface minima do servico.
Fechar operacoes como:
- `new(seed) -> rng_ref`;
- `next(rng_ref) -> int`;
- `destroy(rng_ref)`.
2. Determinismo e replay.
Definir:
- seed explicita obrigatoria;
- regra de reproducao frame a frame;
- comportamento esperado em replay.
3. Lifecycle e validade.
Definir:
- como lidar com `rng_ref` invalido/stale;
- relacao com GC;
- destruicao explicita vs cleanup por GC.
4. Fault/status do dominio.
Definir:
- quais erros sao `status`;
- quais casos viram `Trap`;
- inexistencia de `Panic` operacional.
5. Metadados e versionamento.
Definir IDs/version das operacoes de random para garantir mapeamento 1:1 FE/backend/runtime.
## Open Questions de Arquitetura
1. v1 aceita apenas modo deterministico por seed ou tambem entropy host?
2. `next` retorna apenas `int` ou precisamos variantes (`u32`, `float`) no mesmo ciclo?
3. precisamos de clone/split de gerador no MVP?
4. destruicao explicita deve ser obrigatoria para certificacao/custo ou opcional?
## Dependencias
- `../decisions/006-vm-owned-stateful-core-contract.md`
- `../virtual-machine/ISA_CORE.md`
- `../specs/16-host-abi-and-syscalls.md`
- `../specs/16a-syscall-policies.md`
## Fora de Escopo
- entropy nao deterministica como contrato base;
- PRNGs multiplos no mesmo ciclo de fechamento;
- APIs de colecoes stateful;
- window/app model.
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- surface minima de random VM-owned;
- contrato de determinismo/replay;
- fault/status de random;
- IDs/versionamento e validacoes de verifier para as operacoes do dominio.
@@ -0,0 +1,142 @@
---
id: AGD-0006
ticket: app-home-filesystem-surface-and-semantics
title: Agenda - App Home Filesystem Surface and Semantics
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - App Home Filesystem Surface and Semantics
## Problema
Apps precisam de filesystem util para dados de usuario, cache e configuracao, mas sem acesso ao FS inteiro do host.
Sem um contrato claro de `home` por app, a API tende a crescer com semantica inconsistente entre plataformas.
## Inputs Ja Fechados
1. Todo `app` acessa somente sua `home` logica.
2. Nunca ha acesso direto ao filesystem global do host pela userland.
3. O runtime `fs` interno continua cobrindo tanto `game` quanto `app`.
## Alvo da Discussao
Fechar a superficie e semantica funcional de `fs` para perfil `app`, com sandbox por `app_id` e transporte de bytes via decisao `003`.
## O Que Precisa Ser Definido
1. Surface minima do perfil `app`.
Operacoes candidatas:
- `read`;
- `write`;
- `exists`;
- `stat`;
- `list_dir`;
- `delete`;
- `mkdir`;
- `rename`.
2. Modelo de caminho logico.
Definir:
- raiz virtual (`home`);
- normalizacao de path;
- bloqueio de path traversal;
- limites de profundidade/tamanho.
3. Mapeamento host.
Definir:
- como `home` vira caminho fisico no host;
- isolamento entre apps por `app_id`;
- regras de portabilidade entre hosts.
4. Semantica de leitura/escrita.
Definir:
- leitura total vs parcial;
- overwrite vs append;
- truncation;
- criacao implicita;
- escrita atomica por arquivo (quando aplicavel).
5. Quotas e capacidade.
Definir:
- se v1 tem quota por app;
- comportamento para `storage full`;
- exposicao de metrica de uso livre/ocupado.
6. Metadados e listagem.
Definir:
- campos minimos de `stat`;
- shape canonico de `list_dir`;
- timestamps (sim/nao e com qual garantia).
7. Fault/status do dominio.
Fechar fronteira de:
- `status` operacional;
- `Trap` estrutural;
- `Panic` interno.
E obrigatorio fechar, por operacao, a matriz final de retorno e fault class.
## Responsabilidade Absorvida da Agenda 003
No perfil `app` (`home` sandbox), esta agenda passa a ser a fonte normativa para:
1. Catalogo de `status` de filesystem para app.
Minimo esperado:
- `OK`;
- `NOT_FOUND`;
- `PATH_INVALID`;
- `ACCESS_DENIED`;
- `NO_SPACE`;
- `ALREADY_EXISTS`;
- `UNAVAILABLE`.
2. Matriz por operacao (`read`, `write`, `exists`, `stat`, `list_dir`, `delete`, `mkdir`, `rename`).
Para cada caso, classificar explicitamente:
- `status`;
- `Trap`;
- `Panic`.
3. Shape de retorno por operacao.
Definir, no minimo:
- `status` como primeiro retorno;
- `bytes_transferred` em `read`/`write` quando aplicavel;
- payload de metadados/listagem com formato canonico.
4. Regra de escrita parcial.
`write` nao pode reportar sucesso parcial silencioso.
Quando a operacao nao puder ser concluida conforme contrato, deve retornar falha de dominio.
## Open Questions de Arquitetura
1. O v1 precisa de quota fixa por app ou apenas limites fisicos do host?
2. `rename` entra no MVP ou pode ficar para fase seguinte?
3. Qual conjunto minimo de metadados garante portabilidade real entre hosts?
4. Qual grau de atomicidade e obrigatorio para escrita de arquivo no v1?
## Dependencias
- `../decisions/003-vm-owned-byte-transfer-protocol.md`
- `../decisions/007-filesystem-fault-core-policy.md`
- `../specs/13-cartridge.md`
- `../specs/12-firmware-pos-and-prometeuhub.md`
- `../specs/16a-syscall-policies.md`
## Fora de Escopo
- slots de memcard para `game` (fechado na `spec 08`);
- acesso cross-app;
- sync remoto/cloud;
- DB embutido como contrato de plataforma.
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- surface minima de `fs` para `app` em `home`;
- sandbox e isolamento por `app_id`;
- semantica final de path/read/write/listagem;
- matriz completa de fault/status para as operacoes do perfil `app`.
@@ -0,0 +1,77 @@
---
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.
@@ -0,0 +1,85 @@
---
id: AGD-0008
ticket: perf-async-background-work-lanes-for-assets-and-fs
title: Agenda - [PERF] Async Background Work Lanes for Assets and FS
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - [PERF] Async Background Work Lanes for Assets and FS
## Problema
`asset.load()` hoje cria uma thread do SO por requisicao. Ao mesmo tempo, `fs` ainda nao tem uma politica clara para sync assincrono barato em hardware simples.
O projeto precisa de paralelismo para IO/decode/sync, mas o target inclui handheld DIY e hardware barato, onde um pool grande ou explosao de threads pode piorar a latencia em vez de melhorar.
## Dor
- `thread::spawn` por request escala mal e cria jitter.
- assets e `fs` competem por IO sem uma politica unica de fila/prioridade.
- sem lane dedicada, operacoes de background tendem a vazar custo para o main loop.
- sem disciplina, o host desktop vira referencia errada para hardware fraco.
## Hotspots Atuais
- [asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs#L353)
- [tick.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs#L53)
- [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs#L315)
## Alvo da Discussao
Fechar um modelo de execucao assincrona para `asset` e `fs` que seja previsivel em hardware simples.
## O Que Precisa Ser Definido
1. Topologia de workers.
Escolher entre:
- uma thread dedicada para `asset` e outra para `fs`;
- um worker unico multiplexando filas;
- um pool minimo e fixo;
- proibicao explicita de `spawn` por request.
2. Separacao por dominio.
Decidir se `asset` e `fs` compartilham scheduler/fila ou se cada dominio tem lane propria.
3. Politica de prioridade.
Definir:
- prioridade de loads visuais vs audio;
- prioridade de sync de save/config;
- limite de trabalho por frame para install/commit.
4. Modelo de retorno.
Fechar como o guest observa backlog, cancelamento e saturacao:
- status imediato de fila cheia;
- status de pending;
- metrica de backlog;
- politica de cancelamento.
5. Orçamento para hardware barato.
Definir quantas threads o runtime pode assumir como baseline.
## Open Questions de Arquitetura
1. O v1 precisa de lanes separadas para `asset` e `fs` ou basta uma fila central com classes de prioridade?
2. Decode de asset fica no mesmo worker do IO ou em fase distinta?
3. Commit/install no device continua no main thread por determinismo?
## Dependencias
- `../specs/09-events-and-concurrency.md`
- `../specs/15-asset-management.md`
- `../specs/16a-syscall-policies.md`
- `014-app-home-filesystem-surface-and-semantics.md`
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- numero e tipo de workers aceitos no baseline;
- fila/prioridade de `asset` e `fs`;
- proibicao ou aceitacao limitada de `thread::spawn` por request;
- modelo de status/telemetria para backlog e saturacao.
@@ -0,0 +1,79 @@
---
id: AGD-0009
ticket: perf-host-desktop-frame-pacing-and-presentation
title: Agenda - [PERF] Host Desktop Frame Pacing and Presentation
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - [PERF] Host Desktop Frame Pacing and Presentation
## Problema
O host desktop ainda roda em modo agressivo de polling e apresentacao continua.
Hoje o loop usa `ControlFlow::Poll`, pede redraw incondicionalmente e converte o framebuffer inteiro de RGB565 para RGBA8 a cada `RedrawRequested`, mesmo quando nao ha novo frame logico.
## Dor
- CPU fica ocupada sem ganho visual.
- port de referencia no desktop mascara problemas de pacing em hardware barato.
- a conta de energia/temperatura piora mesmo quando a VM esta ociosa.
## Hotspots Atuais
- [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs#L252)
- [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs#L270)
- [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs#L390)
## Alvo da Discussao
Fechar uma politica de pacing/apresentacao host-driven que nao desperdice CPU quando nao existe frame novo.
## O Que Precisa Ser Definido
1. Gatilho de redraw.
Decidir se redraw acontece:
- apenas com logical frame pronto;
- por deadline de vsync;
- por dirty flag do front buffer;
- por evento externo relevante.
2. Politica do event loop.
Decidir entre:
- `Wait`;
- `WaitUntil`;
- `Poll` apenas em modo debug/profiling.
3. Conversao de framebuffer.
Definir se a conversao RGB565 -> RGBA8:
- continua full-frame;
- passa a ser dirty-region;
- sai da CPU e vai para shader/path especifico do host.
4. Modo ocioso.
Delimitar comportamento quando VM esta pausada, em breakpoint ou sem cart.
## Open Questions de Arquitetura
1. O host desktop deve ser referencia conservadora de energia ou apenas shell de desenvolvimento?
2. O runtime precisa expor um sinal explicito de "novo frame disponivel" para o host?
3. Existe necessidade real de redraw continuo quando o overlay esta desligado?
## Dependencias
- `../specs/01-time-model-and-cycles.md`
- `../specs/10-debug-inspection-and-profiling.md`
- `../specs/11-portability-and-cross-platform-execution.md`
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- politica de control flow do host;
- criterio canonico de redraw;
- estrategia de conversao/apresentacao de framebuffer;
- comportamento de idle/pause/debug.
@@ -0,0 +1,74 @@
---
id: AGD-0010
ticket: perf-gfx-render-pipeline-and-dirty-regions
title: Agenda - [PERF] GFX Render Pipeline and Dirty Regions
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - [PERF] GFX Render Pipeline and Dirty Regions
## Problema
O renderer `gfx` recompõe a cena inteira a cada frame logico, mesmo quando a mudanca visual e pequena.
Hoje `render_all()` reconstrói buckets de sprites, escaneia os 512 sprites, redesenha layers e aplica dois passes fullscreen de fade sem politica de invalidacao.
## Dor
- custo visual basico cresce demais para hardware simples.
- pequenos updates pagam preco de full redraw.
- fade, HUD e world composition ficam sempre no caminho critico.
## Hotspots Atuais
- [gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs#L563)
- [gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs#L671)
## Alvo da Discussao
Definir ate onde o v1 precisa sair do modelo brute force para um pipeline com invalidacao e custo previsivel.
## O Que Precisa Ser Definido
1. Granularidade de invalidacao.
Escolher entre:
- dirty flag por frame inteiro;
- dirty region por layer;
- dirty list por sprite/HUD;
- combinacao minima viavel.
2. Buckets e traversal de sprites.
Decidir se os buckets continuam sendo reconstruidos por frame ou se viram estrutura incremental.
3. Fades.
Definir se fade neutro precisa bypass total e se fade parcial pode operar por regiao/camada.
4. Cache de composicao.
Delimitar se layers estaticas/HUD podem manter cache intermediario.
5. Meta de custo.
Fechar qual teto de pixels/trabalho por frame e aceitavel no baseline.
## Open Questions de Arquitetura
1. O fantasy console quer simular hardware de full redraw ou quer um renderer pragmatico para handheld barato?
2. Dirty regions quebram alguma expectativa de determinismo visivel?
3. O HUD deve continuar no mesmo pipeline da world scene?
## Dependencias
- `../specs/04-gfx-peripheral.md`
- `../specs/11-portability-and-cross-platform-execution.md`
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- nivel minimo de invalidacao no v1;
- politica de rebuild de buckets de sprites;
- bypass/cache de fade e HUD;
- meta de custo para o render pipeline.
@@ -0,0 +1,72 @@
---
id: AGD-0011
ticket: perf-runtime-introspection-syscalls
title: Agenda - [PERF] Runtime Introspection Syscalls
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - [PERF] Runtime Introspection Syscalls
## Problema
As syscalls de introspecao ainda carregam custo de serializacao e agregacao demais para algo que deveria ser observabilidade sob demanda.
Hoje `BankInfo` e `BankSlotInfo` montam JSON por chamada e puxam dados potencialmente caros do asset manager.
## Dor
- tooling de debug pode contaminar custo percebido da runtime surface.
- serializacao de string/JSON vira alocacao no meio do dispatch.
- sem fronteira clara, apps podem abusar de syscalls de introspecao como se fossem baratas.
## Hotspots Atuais
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L481)
- [asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs#L618)
## Alvo da Discussao
Separar claramente custo de introspecao/debug do custo da superficie operacional normal.
## O Que Precisa Ser Definido
1. Papel dessas syscalls.
Decidir se `BankInfo`/`BankSlotInfo` sao:
- superficie publica normal;
- superficie de debug;
- superficie host/devtools apenas.
2. Shape de retorno.
Definir se JSON continua existindo ou se v1 exige shape mais barato/canonico.
3. Caching.
Delimitar se snapshots de introspecao podem ser cacheados por frame.
4. Limites de uso.
Decidir se o runtime deve impor throttling, budget ou feature gate de debug.
## Open Questions de Arquitetura
1. Vale manter JSON na ABI do guest ou isso deveria ficar restrito ao host/debugger?
2. Existe um subconjunto de dados numericos suficiente para carts sem tooling externo?
3. O certifier deve observar essas chamadas como custo anormal de debug?
## Dependencias
- `../specs/10-debug-inspection-and-profiling.md`
- `../specs/15-asset-management.md`
- `../specs/16-host-abi-and-syscalls.md`
- `../specs/16a-syscall-policies.md`
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- papel normativo de `BankInfo`/`BankSlotInfo`;
- permanencia ou remocao de JSON como shape de retorno;
- politica de cache/throttling;
- custo aceitavel de introspecao no dispatch.
@@ -0,0 +1,70 @@
---
id: AGD-0012
ticket: perf-host-debug-overlay-isolation
title: Agenda - [PERF] Host Debug Overlay Isolation
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - [PERF] Host Debug Overlay Isolation
## Problema
O overlay de debug ainda usa o pipeline emulado de `gfx` e injeta custo visual no caminho normal do host.
Hoje o host formata strings por frame, desenha texto via `gfx` e faz `present()` extra para sobrepor telemetria.
## Dor
- debug ligado altera custo do render path que deveria estar sendo medido.
- overlay de desenvolvimento distorce a leitura de performance do console.
- handheld barato nao deveria pagar composicao de HUD tecnico no mesmo pipeline do jogo.
## Hotspots Atuais
- [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs#L126)
- [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs#L381)
## Alvo da Discussao
Isolar o overlay de debug do custo medido do console sem perder utilidade para desenvolvimento.
## O Que Precisa Ser Definido
1. Lugar de composicao.
Decidir se o overlay:
- continua no `gfx` emulado;
- sobe para camada host nativa;
- vira surface separada de debug.
2. Politica de strings/glyphs.
Definir se texto e reconstruido por frame ou cacheado.
3. Custo em modo debug.
Delimitar qual overhead e aceitavel quando overlay estiver ativo.
4. Efeito na telemetria.
Fechar se a telemetria deve incluir ou excluir explicitamente o custo do overlay.
## Open Questions de Arquitetura
1. O overlay precisa ser representativo do hardware final ou apenas ferramenta de desktop?
2. Vale um modo "perf puro" onde overlay nunca toca no framebuffer do console?
3. O host deve oferecer toggles separados para stats, logs e overlay visual?
## Dependencias
- `../specs/10-debug-inspection-and-profiling.md`
- `../specs/11-portability-and-cross-platform-execution.md`
## Criterio de Saida Desta Agenda
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.
@@ -0,0 +1,80 @@
---
id: AGD-0013
ticket: perf-vm-allocation-and-copy-pressure
title: Agenda - [PERF] VM Allocation and Copy Pressure
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - [PERF] VM Allocation and Copy Pressure
## Problema
O core da VM ainda aloca e clona demais em alguns caminhos relevantes, especialmente quando strings entram no fluxo.
Hoje `ADD` com string usa `format!`/`to_string()`, `GET_GLOBAL` clona valores e varios caminhos de erro montam strings dinamicas.
## Dor
- churn de heap reduz o teto de throughput da VM.
- carts que abusam de string e estado global pagam custo cedo demais.
- hardware barato sente alocacao repetitiva de forma desproporcional.
## Hotspots Atuais
- [virtual_machine.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-vm/src/virtual_machine.rs#L635)
- [virtual_machine.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-vm/src/virtual_machine.rs#L870)
- [tick.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs#L111)
## Alvo da Discussao
Definir o nivel de disciplina de alocacao/copia exigido do core da VM no baseline do console.
## O Que Precisa Ser Definido
1. Prioridade dos casos.
Fechar quais caminhos sao realmente hot:
- opcodes de string;
- acesso a globals;
- faults;
- logs.
2. Estrategia de ownership.
Decidir onde vale introduzir:
- borrow temporario;
- small-string strategy;
- copy-on-write;
- intern/cache de strings.
3. Meta de alocacao.
Definir se o projeto quer:
- zero alloc no frame loop feliz;
- alloc rara e explicita;
- apenas reducao oportunista.
4. Instrumentacao.
Decidir como medir alocacao sem transformar a VM em microbenchmark artificial.
## Open Questions de Arquitetura
1. Strings sao citizen de primeira classe no fantasy console ou recurso conveniente mas caro?
2. Vale endurecer a linguagem/ABI para reduzir alocacao implicitamente?
3. Caminhos de fault precisam ser maximizados para desempenho ou apenas os caminhos felizes?
## Dependencias
- `../specs/02a-vm-values-and-calling-convention.md`
- `../specs/03-memory-stack-heap-and-allocation.md`
- `../specs/10-debug-inspection-and-profiling.md`
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- caminho quente prioritario para desengordurar;
- meta minima de alocacao/copia da VM;
- estrategia de ownership para strings/values;
- instrumentacao canonica para medir regressao.
@@ -0,0 +1,74 @@
---
id: AGD-0014
ticket: perf-cartridge-boot-and-program-ownership
title: Agenda - [PERF] Cartridge Boot and Program Ownership
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - [PERF] Cartridge Boot and Program Ownership
## Problema
O bootstrap do cart ainda faz copia desnecessaria de dados grandes e de metadados que poderiam ter ownership mais claro.
Hoje `initialize_vm()` clona `program`, `title`, `app_version` e `entrypoint` ao carregar o cart. Isso nao e o maior gargalo em steady-state, mas sinaliza que ownership de boot ainda esta frouxo.
## Dor
- reload, troca de cart e cenarios de tooling pagam custo desnecessario.
- ownership frouxo no boot tende a reaparecer em hot-reload, debugger e loader.
- em hardware pequeno, boot "barato" tambem importa.
## Hotspots Atuais
- [lifecycle.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/lifecycle.rs#L125)
## Alvo da Discussao
Fechar um modelo de ownership de cart/programa que reduza copias sem comprometer simplicidade ou seguranca do runtime.
## O Que Precisa Ser Definido
1. Ownership do programa.
Decidir se o bytecode:
- e movido para a VM;
- e compartilhado por `Arc`;
- e mantido no cart com view emprestada.
2. Ownership de metadata.
Delimitar o que precisa ser copiado para estado corrente do runtime e o que pode ser referenciado.
3. Ciclo de vida.
Definir como ownership funciona em:
- boot inicial;
- troca de cart;
- debugger/reload;
- run-cart futuro.
4. Meta de boot.
Fechar qual custo de inicializacao e aceitavel para o baseline.
## Open Questions de Arquitetura
1. O projeto quer boot otimizado para trocas frequentes ou apenas para cold start?
2. Existe risco real de aliasing/perigo de lifetime ao evitar copias aqui?
3. Vale aceitar copia de metadata pequena e atacar so `program`?
## Dependencias
- `../specs/13-cartridge.md`
- `../specs/14-boot-profiles.md`
- `009-system-run-cart.md`
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- ownership canonico de `program`;
- politica de copia/referencia para metadata de cart;
- comportamento em reload/troca de cart;
- meta de custo para boot e reinicializacao.
@@ -0,0 +1,110 @@
---
id: AGD-0015
ticket: tilemap-empty-cell-vs-tile-id-zero
title: Tilemap Empty Cell vs Tile ID Zero
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Tilemap Empty Cell vs Tile ID Zero
## Contexto
O runtime hoje usa `tile.id == 0` como atalho para "tile ausente" no caminho de render de tilemap.
Ao mesmo tempo, o contrato de `tile bank` em evolucao no packer quer permitir que `tile_id = 0` seja um tile real e valido dentro do bank.
Isso cria conflito direto entre:
- semantica atual do tilemap no runtime;
- e o contrato de packing/runtime asset bank que trata `tile_id` como indice valido do bank desde zero.
## Problema
Precisamos decidir qual e a semantica correta para representar ausencia de tile em tilemaps.
Hoje o comportamento implicito e:
- `tile.id == 0` significa "nao desenhar";
- portanto o tile de indice `0` no bank fica inutilizavel no caminho de tilemap;
- sprites, por outro lado, nao carregam a mesma semantica implicita de vazio.
Isso deixa o modelo inconsistente:
1. o mesmo `tile_id` nao significa a mesma coisa em todos os consumidores;
2. o bank `TileBank` nao explicita reserva de `tile_id = 0`;
3. o packer teria que compensar uma regra de consumidor que nao esta modelada no contrato do asset bank.
## Pontos Criticos
- `tile_id` deve representar um indice valido no bank, nao um sentinel escondido, sempre que possivel;
- ausencia de tile e um conceito de tilemap/layer, nao necessariamente de bank asset;
- usar indices fora da faixa como sentinel tende a piorar validacao e debug;
- mudar o shape do tilemap pode ter custo de ABI/runtime, mas pode deixar o contrato mais honesto;
- manter o comportamento atual preserva compatibilidade local, mas cristaliza uma semantica implicita fraca.
## Opcoes
### Opcao A - Manter `tile.id == 0` como empty sentinel
O runtime segue tratando `tile_id = 0` como ausencia de tile no tilemap.
Consequencia:
- o primeiro tile real do bank precisaria comecar em `1` para o caminho de tilemap;
- o packer precisaria compensar isso;
- sprites e tilemaps continuariam com semanticas diferentes para o mesmo id.
### Opcao B - Tornar vazio explicito no tilemap model
O tilemap passa a representar vazio explicitamente, por exemplo com:
- `Option<Tile>`;
- ou `Tile { active/present, ... }`.
Consequencia:
- `tile_id = 0` volta a ser um tile valido no bank;
- ausencia de tile deixa de depender de valor especial do id;
- o runtime fica semanticamente mais consistente.
### Opcao C - Usar sentinel fora da faixa valida
O tilemap passa a tratar um `tile_id >= tile_capacity` como "empty".
Consequencia:
- evita usar `0` como sentinel;
- mas cria acoplamento ruim entre tilemap e capacidade do bank;
- e torna a validacao mais fragil e menos didatica.
## Sugestao / Recomendacao
Adotar `Opcao B`.
Ausencia de tile deve ser modelada explicitamente no tilemap/layer, e nao por um `tile_id` especial.
Direcao recomendada:
1. `tile_id` deve significar apenas "indice do tile no bank";
2. `tile_id = 0` deve ser permitido como tile real;
3. tilemaps devem ter vazio explicito no proprio modelo;
4. o render do tilemap deve testar esse estado explicito, nao `tile.id == 0`.
## Perguntas em Aberto
1. Qual shape e melhor para o primeiro wave:
`Option<Tile>` ou `Tile` com flag `active/present`?
2. Essa mudanca afeta apenas o tilemap path ou tambem deve harmonizar outros consumidores do modelo `Tile`?
3. Precisamos de estrategia de compatibilidade/migracao para codigo e testes que hoje assumem `tile.id == 0` como vazio?
## Criterio para Encerrar
Esta agenda pode ser encerrada quando houver decisao clara sobre:
- como vazio e representado no tilemap;
- se `tile_id = 0` volta a ser indice valido universal do bank;
- e quais pontos de spec/codigo do runtime precisam de propagacao.
@@ -0,0 +1,100 @@
---
id: AGD-0016
ticket: asset-entry-metadata-normalization-contract
title: Asset Entry Metadata Normalization Contract
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Asset Entry Metadata Normalization Contract
Status: Open
Domain Owner: `docs/runtime`
Cross-Domain Impact: `../studio/docs/packer`, `shipper`, `asset` loader
## Purpose
Normatizar como `AssetEntry.metadata` deve preservar a convergencia entre metadata autoral, metadata de codec e metadata de pipeline sem colapsar tudo num mapa plano ambiguo.
## Problem
O lado produtor (`packer`) ja convergiu para um contrato em que o runtime precisa ler campos obrigatorios diretamente de `AssetEntry.metadata`, mas tambem precisa manter segmentacao suficiente para nao perder significado entre:
- `asset.json.output.metadata`
- `asset.json.output.codec_configuration`
- `asset.json.output.pipeline`
Sem um contrato explicito no runtime:
- o packer pode materializar estruturas diferentes entre formatos;
- o loader/runtime pode passar a depender de flattening incidental;
- tooling e debug surfaces perdem previsibilidade;
- futuros formatos tendem a misturar metadata efetiva com detalhe interno de pipeline.
## Context
No ciclo atual de `tile bank`, o produtor ja fechou esta direcao:
- `asset.json.output.metadata` -> `AssetEntry.metadata`
- `asset.json.output.codec_configuration` -> `AssetEntry.metadata.codec`
- `asset.json.output.pipeline` -> `AssetEntry.metadata.pipeline`
Ao mesmo tempo, o runtime ainda consome alguns campos obrigatorios do tile bank diretamente no nivel raiz de `AssetEntry.metadata`, em especial:
- `tile_size`
- `width`
- `height`
- `palette_count`
A agenda precisa fechar se esse shape vira contrato geral de runtime para metadata normalizada de assets, e como o consumidor deve tratar campos obrigatorios format-specific versus subtrees segmentadas.
## Options
### Option A - Flat effective metadata map only
Tudo converge para um unico mapa plano em `AssetEntry.metadata`.
### Option B - Root effective metadata plus stable segmented subtrees
Campos runtime-obrigatorios ficam legiveis no nivel raiz, enquanto dados de codec e pipeline ficam em subtrees estaveis:
- `metadata.<field>`
- `metadata.codec.<field>`
- `metadata.pipeline.<field>`
### Option C - Fully segmented metadata only
Nada fica no nivel raiz; todo consumo passa por subtrees por origem.
## Tradeoffs
- Option A simplifica leitura curta, mas perde origem semantica e aumenta risco de colisao.
- Option B preserva leitura direta para campos obrigatorios do runtime e mantem segmentacao estavel para evolucao futura.
- Option C e semanticamente limpa, mas quebra o consumo direto atual de formatos como `tile bank` e introduz custo de migracao desnecessario agora.
## Recommendation
Adotar `Option B`.
Direcao recomendada:
- campos format-specific obrigatorios para decode/runtime continuam legiveis no nivel raiz de `AssetEntry.metadata`;
- `output.codec_configuration` materializa em `AssetEntry.metadata.codec`;
- `output.pipeline` materializa em `AssetEntry.metadata.pipeline`;
- o runtime nao deve exigir flattening total para consumir metadata segmentada;
- specs format-specific devem declarar explicitamente quais campos sao obrigatorios no nivel raiz.
## Open Questions
1. O contrato deve tratar o subtree raiz como semanticamente equivalente a `output.metadata` ou como effective metadata map mais amplo?
2. Quais readers/helpers do runtime devem ser criados para evitar parsing manual disperso de `metadata.codec` e `metadata.pipeline`?
## Expected Follow-up
1. Converter esta agenda em decision no `runtime`.
2. Propagar a decisao para `15-asset-management.md`.
3. Ajustar loaders format-specific para usar helpers consistentes de metadata quando necessario.
4. Alinhar o `packer` e testes de conformance com o shape final.