add agendas

docs/agendas/001-system-run-cart.md

@@ -0,0 +1,83 @@
+# 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.

docs/agendas/002-packed-cartridge-loader-pmc.md

@@ -0,0 +1,75 @@
+# 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.

docs/agendas/003-structured-runtime-abi.md

@@ -0,0 +1,77 @@
+# Agenda - Structured Runtime ABI
+
+## Problema
+
+Partes importantes da borda do runtime ainda escapam para strings, texto ad hoc e JSON serializado para transportar dados estruturados.
+
+Exemplos atuais:
+
+- `fs.read` converte bytes para `String`;
+- `fs.list_dir` concatena nomes com separador textual;
+- `bank.info` e `bank.slot_info` devolvem JSON em um slot string.
+
+## Dor
+
+- O ABI deixa de ser estrutural e volta a depender de parsing textual no guest.
+- Binários e bytes arbitrários ficam mutilados por `UTF-8 lossy`.
+- Contratos ficam frágeis: delimitadores, shape do JSON e nomes de campo viram parte implícita da API.
+- Isso contradiz a linha central do projeto: sem mágica, sem heurística, sem ambiguidade.
+- O custo futuro aumenta porque qualquer linguagem cliente passa a embutir parser de conveniência para tapar buraco de ABI.
+
+## Alvo da Discussao
+
+Definir um modelo canônico para dados estruturados e/ou binários na fronteira guest <-> runtime.
+
+Essa agenda precisa responder se o runtime vai operar com:
+
+- slots primitivos fixos;
+- objetos heapados do VM;
+- handles opacos para buffers/iteradores;
+- uma combinação dessas estratégias por domínio.
+
+## O Que Precisa Ser Definido
+
+1. Modelo de retorno estruturado.
+   Como representar listas, metadados de banco, resultados de leitura e payload binário sem texto improvisado.
+
+2. Política para bytes.
+   `fs.read` deve retornar buffer/array/handle, nao string textual.
+
+3. Política para structs.
+   `bank.info`, `button`, `slot info` e similares devem ter shape canônico:
+   - flatten em slots;
+   - objeto heapado;
+   - view estruturada com metadata fixa.
+
+4. Política para listas.
+   `fs.list_dir` nao deve depender de delimitador textual; precisa de shape navegável.
+
+5. Impacto no verifier e no HostReturn.
+   Se houver objetos heapados retornados por syscalls, a ABI e o runtime precisam suportar isso sem atalhos temporários.
+
+6. Estratégia de migração.
+   Como substituir contratos atuais sem consolidar compatibilidade acidental ruim.
+
+## O Que Necessita Para Resolver
+
+- decisão arquitetural para transporte de dados estruturados;
+- catálogo das syscalls afetadas;
+- atualização do ABI canônico;
+- estratégia de teste para garantir integridade de bytes e shape estável;
+- posição explícita sobre backward compatibility.
+
+## Fora de Escopo
+
+- serialização genérica estilo JSON para tooling externo;
+- reflection completa no guest;
+- coleção completa de tipos ricos do SDK.
+
+## Critério de Saida Desta Agenda
+
+Pode virar PR quando houver decisão escrita sobre:
+
+- shape canônico por domínio afetado;
+- representação de bytes;
+- impacto no heap/GC/HostReturn;
+- política de migração;
+- suite mínima de testes de ABI.

docs/agendas/004-syscall-fault-classification.md

@@ -0,0 +1,73 @@
+# Agenda - Syscall Fault Classification
+
+## Problema
+
+Hoje a fronteira de syscalls ainda mistura:
+
+- erro do programa guest;
+- erro operacional recuperável;
+- inconsistência interna do runtime/host.
+
+Na prática, vários casos que deveriam ser `Trap` para o guest ainda sobem como `Panic`.
+
+## Dor
+
+- O modelo de falhas perde rigor.
+- Guest bug e bug interno do runtime viram a mesma classe de falha terminal.
+- Diagnóstico fica pior: o sistema nao distingue uso incorreto da API de corrupção/inconsistência de implementação.
+- Isso atrapalha tooling, crash reports, certificação e confiança no runtime.
+
+## Alvo da Discussao
+
+Definir a taxonomia canônica de falhas na fronteira de syscall.
+
+O objetivo é estabelecer uma regra previsível para classificar:
+
+- `Trap`: erro do guest, violação de contrato, argumento inválido, estado inválido observável;
+- `Panic`: bug interno, inconsistência de metadados, violação de invariantes do runtime;
+- `Unavailable`: indisponibilidade do host ou feature ausente.
+
+## O Que Precisa Ser Definido
+
+1. Regra por categoria de erro.
+   Como classificar:
+   - handle inválido;
+   - path inválido;
+   - asset inexistente;
+   - capability insuficiente;
+   - retorno incoerente do host;
+   - falha interna de serviço.
+
+2. Mapeamento por domínio.
+   FS, assets, bank, log, gfx, input e system precisam seguir a mesma filosofia.
+
+3. Superfície de telemetria e crash report.
+   O que deve aparecer para usuário, tooling e testes.
+
+4. Compatibilidade com verifier e ABI.
+   O verifier continua estrutural; a taxonomia runtime precisa ser coerente com essa divisão.
+
+5. Regras para bibliotecas host.
+   Implementações de `NativeInterface` e bridges precisam saber quando devolver `Trap`, `Panic` ou `Unavailable`.
+
+## O Que Necessita Para Resolver
+
+- matriz de classificação de falhas por syscall/domínio;
+- revisão do uso atual de `VmFault`;
+- atualização de crash reporting e logs onde necessário;
+- testes cobrindo casos representativos em cada classe.
+
+## Fora de Escopo
+
+- novo sistema completo de códigos de erro por domínio;
+- redesign do debugger protocol;
+- retries automáticos ou políticas complexas de recuperação.
+
+## Critério de Saida Desta Agenda
+
+Pode virar PR quando existir decisão fechada para:
+
+- taxonomia formal de falhas;
+- exemplos classificados por domínio;
+- critérios do que é `Trap` vs `Panic`;
+- impacto em testes e crash reporting.

docs/agendas/005-runtime-edge-test-plan.md

@@ -0,0 +1,75 @@
+# 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.

docs/agendas/006-break-monolith-runtime.md

@@ -0,0 +1,87 @@
+# Agenda - Break Monolith Runtime
+
+## Problema
+
+Partes críticas do runtime cresceram como monólitos:
+
+- dispatcher de syscalls concentrado em um arquivo enorme;
+- lógica de VM e testes unitários convivendo no mesmo arquivo gigante;
+- fronteiras entre domínio, orquestração e teste cada vez menos nítidas.
+
+Isso hoje é visível principalmente em:
+
+- `prometeu-vm/src/virtual_machine.rs`
+- `prometeu-system/src/virtual_machine_runtime.rs`
+- `prometeu-hal/src/syscalls.rs`
+
+## Dor
+
+- Evolução fica cara porque qualquer mudança exige navegar arquivos enormes.
+- Review perde precisão: comportamento, helper, contrato e teste se misturam no mesmo lugar.
+- A chance de regressão cresce porque a coesão está baixa e o isolamento entre domínios está fraco.
+- O custo cognitivo para novos contribuidores já está alto demais para o estágio do projeto.
+- Testes internos gigantes mascaram ownership ruim de comportamento.
+
+## Alvo da Discussao
+
+Definir uma estratégia de modularização do runtime que preserve as invariantes atuais, mas reduza o acoplamento estrutural.
+
+O objetivo não é "fatiar por estética". É:
+
+- extrair dispatcher de syscalls por domínio;
+- separar responsabilidades dentro do runtime;
+- tirar testes unitários do arquivo monolítico da VM quando fizer sentido;
+- manter discoverability e rigor arquitetural.
+
+## O Que Precisa Ser Definido
+
+1. Topologia de módulos.
+   Como dividir syscalls por domínio:
+   - `system`
+   - `gfx`
+   - `input`
+   - `audio`
+   - `fs`
+   - `log`
+   - `asset`
+   - `bank`
+
+2. Dono da orquestração.
+   O que continua no runtime central e o que migra para módulos/serviços especializados.
+
+3. Estratégia para a VM.
+   Quais blocos de `virtual_machine.rs` devem virar módulos dedicados:
+   - execução/opcodes
+   - loader init
+   - syscalls
+   - GC/safepoint hooks
+   - helpers de testes
+
+4. Estratégia de testes.
+   Quais testes permanecem próximos ao módulo e quais viram integração.
+
+5. Critério de coesão.
+   Como evitar trocar um monólito por vinte arquivos arbitrários sem fronteira real.
+
+## O Que Necessita Para Resolver
+
+- mapa atual de responsabilidades por arquivo;
+- proposta de topologia modular;
+- critério de migração de testes;
+- definição clara do que é API interna entre módulos;
+- plano incremental de refactor sem quebrar o runtime no meio.
+
+## Fora de Escopo
+
+- redesign funcional do comportamento da VM;
+- reescrita completa do runtime;
+- reorganização cosmética sem ganho de ownership.
+
+## Critério de Saida Desta Agenda
+
+Pode virar PR quando houver:
+
+- proposta de módulos aprovada;
+- fronteira clara entre dispatcher, domínio e orquestração;
+- plano para testes unitários e integração;
+- estratégia incremental que preserve o comportamento existente.

docs/agendas/007-single-canonical-architecture.md

@@ -0,0 +1,81 @@
+# Agenda - Single Canonical Architecture
+
+## Problema
+
+Hoje a arquitetura do runtime está fragmentada em documentos com níveis diferentes de autoridade.
+
+Na prática existem pelo menos dois problemas:
+
+- mais de um documento tenta falar pela arquitetura;
+- um deles ainda se apresenta como `stub`, enquanto outro se declara baseline canônico.
+
+## Dor
+
+- Contribuidores perdem tempo tentando descobrir qual documento manda.
+- PR arquitetural pode ser validada por um texto e contrariar outro.
+- A documentação deixa de servir como guardrail e passa a gerar ambiguidade.
+- O projeto perde disciplina exatamente na camada que deveria fixar invariantes.
+
+## Alvo da Discussao
+
+Definir um único documento canônico de arquitetura do runtime, com papel explícito para cada outro documento remanescente.
+
+O alvo é matar a ambiguidade, não só mover arquivos.
+
+Ao final da discussão deve ficar claro:
+
+- qual documento é canônico;
+- quais docs são derivativos, históricos ou de apoio;
+- o que deve ser removido, fundido ou rebaixado de autoridade.
+
+## O Que Precisa Ser Definido
+
+1. Documento canônico.
+   Onde vive a arquitetura mandatória do runtime.
+
+2. Escopo do documento.
+   Quais invariantes ele deve cobrir:
+   - execution model
+   - memory model
+   - safepoints
+   - scheduler
+   - verifier
+   - syscall ABI
+   - firmware/runtime boundary
+
+3. Papel dos demais docs.
+   O que é:
+   - arquitetura normativa
+   - roadmap
+   - histórico
+   - specification detalhada
+   - material pedagógico
+
+4. Política de atualização.
+   Mudança arquitetural deve exigir atualização do doc canônico no mesmo PR?
+
+5. Estratégia de remoção do `stub`.
+   Se será apagado, redirecionado ou transformado em índice.
+
+## O Que Necessita Para Resolver
+
+- inventário dos docs que hoje competem por autoridade;
+- decisão de taxonomia documental;
+- definição do local canônico;
+- plano de migração de conteúdo sem perder contexto útil;
+- regra de governança para futuras PRs arquiteturais.
+
+## Fora de Escopo
+
+- reorganização completa de todo o diretório `docs/`;
+- rewrite estilístico de todo material pedagógico;
+- padronização editorial fina além do necessário para eliminar ambiguidade.
+
+## Critério de Saida Desta Agenda
+
+Pode virar PR quando houver:
+
+- definição do documento canônico;
+- lista do que será removido, fundido ou rebaixado;
+- regra explícita de atualização futura;
+- plano curto de migração sem deixar lacuna documental.

docs/agendas/008-hardware-specs-reorganization.md

@@ -0,0 +1,77 @@
+# Agenda - Hardware Specs Reorganization
+
+## Problema
+
+As specs de hardware hoje estão com cara de colcha de retalhos.
+
+Há material útil, mas a organização mistura:
+
+- capítulos extensos e narrativos;
+- conteúdo normativo e conteúdo pedagógico;
+- temas de VM, firmware, cartridge, assets e ABI no mesmo bloco de "hardware";
+- granularidade desigual entre capítulos.
+
+## Dor
+
+- Fica difícil saber o que é norma e o que é explicação.
+- A navegação está ruim para quem precisa alterar um domínio específico.
+- Ownership documental por área não está claro.
+- Revisões futuras tendem a acrescentar mais remendos em vez de consolidar o modelo.
+- O risco de contradição entre spec, arquitetura e implementação cresce.
+
+## Alvo da Discussao
+
+Definir uma organização coerente para as specs do sistema, com separação clara entre:
+
+- spec normativa;
+- material conceitual/pedagógico;
+- arquitetura de runtime;
+- domínios de hardware/periféricos;
+- firmware, cartridge e tooling-related specs.
+
+## O Que Precisa Ser Definido
+
+1. Taxonomia das specs.
+   Quais grandes categorias devem existir:
+   - machine/runtime
+   - hardware/peripherals
+   - firmware/system
+   - cartridge/package
+   - host ABI
+   - assets/tooling
+
+2. Critério de corte.
+   O que pertence a "hardware" de fato e o que deve sair desse pacote.
+
+3. Estrutura de navegação.
+   Como organizar índice, capítulos, subpastas e documentos canônicos por domínio.
+
+4. Nível de autoridade.
+   Quais documentos são normativos e quais são apenas explicativos.
+
+5. Estratégia de migração.
+   Como reorganizar sem quebrar referências, sem perder contexto e sem reescrever tudo de uma vez.
+
+## O Que Necessita Para Resolver
+
+- inventário da estrutura atual;
+- proposta de taxonomia e árvore de diretórios;
+- mapeamento capítulo atual -> destino futuro;
+- política para docs históricos ou híbridos;
+- critério mínimo de consistência editorial para novos documentos.
+
+## Fora de Escopo
+
+- reescrever toda a spec de hardware imediatamente;
+- normalizar cada frase ou estilo de escrita;
+- atualizar todo conteúdo técnico de cada capítulo nesta mesma discussão.
+
+## Critério de Saida Desta Agenda
+
+Pode virar PR quando houver:
+
+- taxonomia alvo aprovada;
+- nova árvore de organização definida;
+- mapa de migração dos capítulos atuais;
+- decisão sobre normativo vs pedagógico;
+- plano incremental de execução.

docs/agendas/README.md

@@ -0,0 +1,26 @@
+# Agendas
+
+Este diretório reúne agendas de discussão arquitetural para itens pendentes ou frágeis do runtime.
+
+Objetivo:
+
+- explicitar a dor real do sistema;
+- delimitar o que precisa ser decidido antes de codar;
+- servir de base para futuras PRs de implementação JVM-grade.
+
+As agendas atuais são:
+
+- `001-system-run-cart.md`
+- `002-packed-cartridge-loader-pmc.md`
+- `003-structured-runtime-abi.md`
+- `004-syscall-fault-classification.md`
+- `005-runtime-edge-test-plan.md`
+- `006-break-monolith-runtime.md`
+- `007-single-canonical-architecture.md`
+- `008-hardware-specs-reorganization.md`
+
+Regra de uso:
+
+- se a implementação exigir decisão estrutural, ela deve nascer daqui antes de virar PR de código;
+- se uma agenda já estiver resolvida, a PR derivada deve citar explicitamente qual decisão foi tomada;
+- se a agenda revelar ambiguidade demais, ela não deve ser convertida em PR até o alvo ficar preciso.