discussion framework migration
This commit is contained in:
@@ -1,75 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,75 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,83 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,54 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,68 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,131 +0,0 @@
|
||||
# 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`.
|
||||
@@ -1,66 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,74 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,68 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,63 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,61 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,59 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,69 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,63 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,99 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,89 +0,0 @@
|
||||
# 024-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.
|
||||
@@ -1,90 +0,0 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user