prometeu-runtime/docs/runtime/agendas/README.md

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
• 005-runtime-edge-test-plan.md
• 009-filesystem-surface-and-semantics.md
• 010-input-intrinsics-surface.md
• 011-input-frame-semantics-and-portability.md
• 012-asset-fault-semantics-and-surface.md
• 013-audio-fault-semantics-and-surface.md
• 014-gfx-fault-semantics-and-command-contract.md
• 015-system-fault-semantics-and-control-surface.md
• 016-filesystem-fault-semantics.md
• 017-vm-owned-builtins-protocol-and-system-services.md

Sequenciamento Recomendado

Ordem sugerida para discussão e futura execução:

1. 007-single-canonical-architecture.md
2. 008-hardware-specs-reorganization.md
3. 006-break-monolith-runtime.md
4. 017-vm-owned-builtins-protocol-and-system-services.md
5. 012-asset-fault-semantics-and-surface.md
6. 013-audio-fault-semantics-and-surface.md
7. 014-gfx-fault-semantics-and-command-contract.md
8. 001-system-run-cart.md
9. 015-system-fault-semantics-and-control-surface.md
10. 009-filesystem-surface-and-semantics.md
11. 016-filesystem-fault-semantics.md
12. 010-input-intrinsics-surface.md
13. 011-input-frame-semantics-and-portability.md
14. 005-runtime-edge-test-plan.md
15. 002-packed-cartridge-loader-pmc.md

Justificativa curta:

• 007 vem primeiro porque elimina ambiguidade sobre qual documento manda.
• 008 vem em seguida porque reorganiza o terreno documental onde specs e arquitetura se apoiam.
• 006 entra depois porque refactor estrutural grande sem documentação estável tende a cristalizar decisões erradas.
• 017 entra cedo para fechar um protocolo VM-owned unico (input/random/window/builtins) sem contaminar a fronteira de syscall host-backed.
• a decisao 003 ja fechou o contrato base para trafego de bytes VM-owned e agora deve ser consumida, nao rediscutida aqui.
• a decisao 004 ja fechou a taxonomia base de falhas host-backed e agora deve ser consumida pelos dominios.
• 012, 013 e 014 quebram o refactor de fault semantics por dominio onde a dor ja esta visivel no codigo.
• 001 vem antes de 015 porque run_cart ainda nao tem semantica funcional fechada.
• 015 fecha a taxonomia do dominio system depois de 001.
• 009 usa as decisoes 003 e 004 para fechar o dominio de filesystem sem texto improvisado.
• 016 fica explicitamente depois de 009, para nao classificar falhas de uma surface que ainda pode mudar.
• 010 e 011 isolam o dominio maior de input fora de syscall, tratando pad e touch como superfícies centrais, button como parte de pad, e explicitando a migracao da leitura de input para intrinsics.
• 005 fecha a barra de qualidade antes das implementações mais arriscadas.
• 001 e 002 dependem mais fortemente de contrato de sistema, ABI e documentação estáveis.

Dependências principais:

• 008 depende de 007
• 006 depende de 007
• 017 depende de 007 e deve alinhar com 16/16a, alem das decisoes 003 e 004
• 009 depende das decisoes 003 e 004
• 012 depende da decisao 004
• 013 depende da decisao 004
• 014 depende da decisao 004
• 015 depende da decisao 004 e 001
• 016 depende das decisoes 003, 004 e da 009
• 010 depende de 007
• 011 depende de 010
• 001 depende de 007, das decisoes 003 e 004, de 005 e deve alinhar com 009 quando usar fs
• 002 depende de 007 e deve ser alinhada com a reorganização documental de 008

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.