diff --git a/docs/agendas/001-system-run-cart.md b/docs/agendas/001-system-run-cart.md new file mode 100644 index 00000000..9a27a6b5 --- /dev/null +++ b/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. diff --git a/docs/agendas/002-packed-cartridge-loader-pmc.md b/docs/agendas/002-packed-cartridge-loader-pmc.md new file mode 100644 index 00000000..15836947 --- /dev/null +++ b/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. diff --git a/docs/agendas/003-structured-runtime-abi.md b/docs/agendas/003-structured-runtime-abi.md new file mode 100644 index 00000000..69021e97 --- /dev/null +++ b/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. diff --git a/docs/agendas/004-syscall-fault-classification.md b/docs/agendas/004-syscall-fault-classification.md new file mode 100644 index 00000000..f9847ebe --- /dev/null +++ b/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. diff --git a/docs/agendas/005-runtime-edge-test-plan.md b/docs/agendas/005-runtime-edge-test-plan.md new file mode 100644 index 00000000..5596eea9 --- /dev/null +++ b/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. diff --git a/docs/agendas/006-break-monolith-runtime.md b/docs/agendas/006-break-monolith-runtime.md new file mode 100644 index 00000000..80c5f63b --- /dev/null +++ b/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. diff --git a/docs/agendas/007-single-canonical-architecture.md b/docs/agendas/007-single-canonical-architecture.md new file mode 100644 index 00000000..c712973b --- /dev/null +++ b/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. diff --git a/docs/agendas/008-hardware-specs-reorganization.md b/docs/agendas/008-hardware-specs-reorganization.md new file mode 100644 index 00000000..0d51de55 --- /dev/null +++ b/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. diff --git a/docs/agendas/README.md b/docs/agendas/README.md new file mode 100644 index 00000000..0d21953a --- /dev/null +++ b/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.