prometeu-runtime/docs/runtime/agendas

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:

• 007-runtime-edge-test-plan.md
• 008-packed-cartridge-loader-pmc.md
• 009-system-run-cart.md
• 010-system-fault-semantics-and-control-surface.md
• 012-vm-owned-random-service.md
• 014-app-home-filesystem-surface-and-semantics.md
• 015-perf-runtime-telemetry-hot-path.md
• 016-perf-async-background-work-lanes-for-assets-and-fs.md
• 017-perf-host-desktop-frame-pacing-and-presentation.md
• 018-perf-gfx-render-pipeline-and-dirty-regions.md
• 019-perf-runtime-introspection-syscalls.md
• 020-perf-host-debug-overlay-isolation.md
• 021-perf-vm-allocation-and-copy-pressure.md
• 022-perf-cartridge-boot-and-program-ownership.md
• 024-asset-entry-metadata-normalization-contract.md

Sequenciamento Recomendado [PERF]

Ordem sugerida para discussao das agendas de performance:

1. 015-perf-runtime-telemetry-hot-path.md
2. 016-perf-async-background-work-lanes-for-assets-and-fs.md
3. 017-perf-host-desktop-frame-pacing-and-presentation.md
4. 018-perf-gfx-render-pipeline-and-dirty-regions.md
5. 019-perf-runtime-introspection-syscalls.md
6. 020-perf-host-debug-overlay-isolation.md
7. 021-perf-vm-allocation-and-copy-pressure.md
8. 022-perf-cartridge-boot-and-program-ownership.md

Justificativa curta:

• 015 e o imposto mais imediato no hot path do runtime.
• 016 fecha a topologia de trabalho assincrono antes de codarmos otimizaoes isoladas.
• 017 impede que o host desktop continue mascarando custo real com busy-poll.
• 018 define o teto de custo do renderer antes de micro-otimizacoes locais.
• 019 separa observabilidade de superficie operacional normal.
• 020 impede que tooling de debug distorca medicao de render e frame pacing.
• 021 entra depois que os gargalos estruturais maiores estiverem delimitados.
• 022 fecha ownership e custo de boot, importante mas menos quente que o frame loop.

Sequenciamento Recomendado

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

1. 012-vm-owned-random-service.md
2. 014-app-home-filesystem-surface-and-semantics.md
3. 007-runtime-edge-test-plan.md
4. 008-packed-cartridge-loader-pmc.md
5. 009-system-run-cart.md
6. 010-system-fault-semantics-and-control-surface.md

Justificativa curta:

• 011 foi fechada pela decisao 006.
• 012 e o primeiro consumidor da base stateful VM-owned fechada em 006.
• 013 foi fechada e absorvida por spec 08 (historico em learn/historical-game-memcard-slots-surface-and-semantics.md).
• 014 fecha o contrato de home para apps sem abrir FS global.
• a decisao 007 fixa o nucleo de fault policy de fs; os detalhes ficam distribuidos entre spec 08 (game) e agenda 014 (app).
• a decisao 008 fixa o contrato status-first de gfx.
• a decisao 009 fixa o contrato status-first de audio.
• a decisao 010 fixa o contrato status-first de asset.
• a agenda 007 vem depois para transformar as decisoes em cobertura de regressao na borda do runtime.
• 008 depende da decisao 011, porque o shipper do .pmc nao deve decidir o contrato interno do packer de assets no meio da implementacao.
• 009 e 010 ficam no fim porque run_cart nao e objetivo do ciclo atual.

Dependências principais:

• 012 depende da decisao 006 e de 16/16a
• 014 depende das decisoes 003/007, de 16a, de 12 (Hub/OS) e de 13 (app_mode)
• 007 depende da estabilizacao minima das agendas de superficie/fault por dominio
• 008 depende da decisao 011, de contrato fechado de 13-cartridge.md e de comportamento equivalente ao loader de diretorio
• 009 depende da decisao 003, de 16a e da decisao 006, e deve alinhar com spec 08/agenda 014 quando usar fs
• 010 depende de 16a e da 009

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.