agenda discussion and decisions
This commit is contained in:
parent
d588502b57
commit
68b87254a7
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -1,74 +0,0 @@
|
||||
# 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 e system precisam seguir a mesma filosofia.
|
||||
`input` so permanece aqui enquanto ainda existir como syscall; se migrar integralmente para intrinsic, sai deste escopo.
|
||||
|
||||
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.
|
||||
@ -77,7 +77,7 @@ Definir a superficie canonica do dominio `fs` no runtime, separando claramente:
|
||||
## Dependencias
|
||||
|
||||
- `../decisions/003-vm-owned-byte-transfer-protocol.md` para transporte de bytes;
|
||||
- `004-syscall-fault-classification.md` para shape de erro;
|
||||
- `../decisions/004-host-fault-taxonomy.md` para shape de erro;
|
||||
- specs de portabilidade para alinhamento com sandbox logico.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
@ -0,0 +1,71 @@
|
||||
# Agenda - Asset Fault Semantics and Surface
|
||||
|
||||
## Problema
|
||||
|
||||
O dominio `asset` ja se comporta como dominio orientado a status em partes da surface, mas ainda promove erro operacional para `Panic` em pontos centrais.
|
||||
|
||||
Exemplo atual:
|
||||
|
||||
- `AssetLoad` transforma `Err(e)` de `hw.assets().load(...)` em `VmFault::Panic(e)`.
|
||||
|
||||
Ao mesmo tempo:
|
||||
|
||||
- `AssetStatus` ja expoe um status numerico do dominio;
|
||||
- a decisao `004` ja aponta `asset` como dominio `status-first`;
|
||||
- a decisao `003` reforca a preferencia por status quando existir contrato funcional recuperavel.
|
||||
|
||||
## Dor
|
||||
|
||||
- falha de asset pode derrubar o app como se fosse bug estrutural do runtime;
|
||||
- a surface do dominio fica incoerente: `status` para observar, `Panic` para operar;
|
||||
- commit/cancel ainda nao deixam claro se handle desconhecido e status, no-op ou fault terminal.
|
||||
|
||||
## Hotspots Atuais
|
||||
|
||||
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L461)
|
||||
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L478)
|
||||
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L490)
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Fechar a taxonomia de fault e, se necessario, ajustar a surface publica de `asset` para que:
|
||||
|
||||
- falhas operacionais virem `status`;
|
||||
- `Trap` fique reservado para erro estrutural da chamada;
|
||||
- `Panic` fique restrito a invariantes quebradas.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. `AssetLoad`.
|
||||
Decidir o que retorna quando:
|
||||
- `asset_id` nao existe;
|
||||
- slot esta ocupado/conflita;
|
||||
- backend falha;
|
||||
- o asset manager entra em estado invalido.
|
||||
|
||||
2. `AssetStatus`.
|
||||
Confirmar se o enum atual e suficiente ou se precisa crescer.
|
||||
|
||||
3. `AssetCommit` e `AssetCancel`.
|
||||
Decidir o shape de fault/status para:
|
||||
- handle desconhecido;
|
||||
- handle ja finalizado;
|
||||
- transicao invalida.
|
||||
|
||||
4. Surface.
|
||||
Decidir se `commit`/`cancel` continuam `void` ou se precisam de retorno explicito.
|
||||
|
||||
5. Relacao com `bank`.
|
||||
Definir se erros de residency/slot entram em `asset` status ou em agenda separada de `bank`.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- `../decisions/004-host-fault-taxonomy.md`
|
||||
|
||||
## Critério de Saida Desta Agenda
|
||||
|
||||
Pode virar PR quando houver decisao escrita sobre:
|
||||
|
||||
- matriz de `status`/`Trap`/`Panic` para `asset`;
|
||||
- shape final de `AssetLoad`, `AssetStatus`, `AssetCommit` e `AssetCancel`;
|
||||
- eliminacao dos `Panic` operacionais indevidos do dominio.
|
||||
@ -0,0 +1,63 @@
|
||||
# Agenda - Audio Fault Semantics and Surface
|
||||
|
||||
## Problema
|
||||
|
||||
O dominio `audio` hoje se comporta como comando deterministico com forte tendencia a no-op/fallback, mas essa politica ainda nao esta escrita como contrato.
|
||||
|
||||
Exemplos atuais:
|
||||
|
||||
- `AudioPlay` cai para `bank_id = 0` quando o asset nao e encontrado;
|
||||
- o driver retorna sem efeito quando `voice_id` esta fora da faixa;
|
||||
- samples nao resolvidos nao produzem fault terminal.
|
||||
|
||||
## Dor
|
||||
|
||||
- a semantica real de erro fica escondida em detalhes de implementacao;
|
||||
- nao esta claro quando `audio` deve ser no-op, `status`, `Trap` ou `Panic`;
|
||||
- futuras mudancas podem cristalizar `Panic` onde hoje o dominio tolera ausencia de recurso.
|
||||
|
||||
## Hotspots Atuais
|
||||
|
||||
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L340)
|
||||
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L359)
|
||||
- [audio.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/audio.rs#L170)
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Fechar a politica de fault e surface de `audio` para o MVP.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. `voice_id` invalido.
|
||||
Decidir entre:
|
||||
- no-op deterministico;
|
||||
- `status`;
|
||||
- `Trap`.
|
||||
|
||||
2. Sample/bank ausente.
|
||||
Decidir entre:
|
||||
- no-op deterministico;
|
||||
- `status`;
|
||||
- `Trap`.
|
||||
|
||||
3. Voice unavailable.
|
||||
Decidir se o dominio precisa retorno de `status` para esse caso ou se politica de voz resolve isso sem retorno.
|
||||
|
||||
4. Surface.
|
||||
Decidir se `AudioPlay`/`AudioPlaySample` continuam `void` no MVP.
|
||||
|
||||
5. Faixas numericas.
|
||||
Decidir a politica para pitch/pan/volume fora da faixa normativa.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- `../decisions/004-host-fault-taxonomy.md`
|
||||
- spec de audio
|
||||
|
||||
## Critério de Saida Desta Agenda
|
||||
|
||||
Pode virar PR quando houver decisao escrita sobre:
|
||||
|
||||
- matriz de `status`/`Trap`/`Panic` para `audio`;
|
||||
- posicao explicita sobre no-op deterministico no dominio;
|
||||
- shape final de retorno de `AudioPlay` e `AudioPlaySample` no MVP.
|
||||
@ -0,0 +1,62 @@
|
||||
# Agenda - Gfx Fault Semantics and Command Contract
|
||||
|
||||
## Problema
|
||||
|
||||
`gfx` parece dominio command-style com pouca necessidade de status, mas a politica concreta entre `Trap`, no-op deterministico e fallback ainda nao esta consolidada.
|
||||
|
||||
Exemplos atuais:
|
||||
|
||||
- `GfxSetSprite` usa fallback estavel quando asset nao e encontrado;
|
||||
- indices fora da faixa podem virar no-op em vez de fault;
|
||||
- argumentos ausentes ainda sobem como `Panic` por detalhe de helper.
|
||||
|
||||
## Dor
|
||||
|
||||
- a surface de `gfx` pode ficar inconsistente entre comandos;
|
||||
- detalhes acidentais de implementacao podem ser confundidos com politica de dominio;
|
||||
- `Panic` pode vazar para o app em casos que sao apenas erro de comando ou comando ignoravel.
|
||||
|
||||
## Hotspots Atuais
|
||||
|
||||
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L178)
|
||||
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L213)
|
||||
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L227)
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Fixar a politica de fault de `gfx` como dominio de comando.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Erros estruturais.
|
||||
Confirmar o que continua `Trap`:
|
||||
- tipo invalido;
|
||||
- aridade invalida;
|
||||
- capability ausente.
|
||||
|
||||
2. Parametros fora da faixa.
|
||||
Decidir por comando:
|
||||
- clamp;
|
||||
- no-op;
|
||||
- `Trap`.
|
||||
|
||||
3. Asset/sprite name ausente em `set_sprite`.
|
||||
Decidir se fallback atual vira contrato oficial.
|
||||
|
||||
4. Indices fora da faixa.
|
||||
Decidir se sprite index invalido e no-op ou `Trap`.
|
||||
|
||||
5. Panic cleanup.
|
||||
Remover `Panic` acidental por argumento ausente/helper onde isso nao representa falha estrutural do runtime.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- `../decisions/004-host-fault-taxonomy.md`
|
||||
|
||||
## Critério de Saida Desta Agenda
|
||||
|
||||
Pode virar PR quando houver decisao escrita sobre:
|
||||
|
||||
- matriz de `Trap`/no-op/fallback para `gfx`;
|
||||
- politica de `set_sprite`;
|
||||
- reducao de `Panic` acidental no dominio.
|
||||
@ -0,0 +1,54 @@
|
||||
# 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 `001` 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)
|
||||
- [001-system-run-cart.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/runtime/agendas/001-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
|
||||
|
||||
- `../decisions/004-host-fault-taxonomy.md`
|
||||
- `001-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.
|
||||
47
docs/runtime/agendas/016-filesystem-fault-semantics.md
Normal file
47
docs/runtime/agendas/016-filesystem-fault-semantics.md
Normal file
@ -0,0 +1,47 @@
|
||||
# Agenda - Filesystem Fault Semantics
|
||||
|
||||
## Problema
|
||||
|
||||
O dominio `fs` certamente precisara de politica de fault propria, mas ainda depende de duas discussoes anteriores:
|
||||
|
||||
- a decisao `003` sobre transporte de bytes;
|
||||
- a agenda `009` sobre superficie e semantica funcional de filesystem.
|
||||
|
||||
Discutir fault semantics antes disso tende a cristalizar classificacao em cima de uma API que ainda pode mudar.
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Fechar a politica de fault de `fs` somente depois da agenda `009`.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Fronteira entre `status` e `Trap` em `fs`.
|
||||
2. Politica para:
|
||||
- handle invalido;
|
||||
- path invalido;
|
||||
- arquivo ausente;
|
||||
- permissao negada;
|
||||
- EOF;
|
||||
- escrita parcial;
|
||||
- storage full;
|
||||
- mount indisponivel.
|
||||
3. Integracao com o protocolo de bytes da decisao `003`.
|
||||
4. Shape final de retorno das operacoes de `fs`.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- `../decisions/003-vm-owned-byte-transfer-protocol.md`
|
||||
- `../decisions/004-host-fault-taxonomy.md`
|
||||
- `009-filesystem-surface-and-semantics.md`
|
||||
|
||||
## Regra de Sequenciamento
|
||||
|
||||
Esta agenda nao deve ser discutida antes da `009`.
|
||||
|
||||
## Critério de Saida Desta Agenda
|
||||
|
||||
Pode virar PR quando houver decisao escrita sobre:
|
||||
|
||||
- matriz de `status`/`Trap`/`Panic` para `fs`;
|
||||
- integracao final com `read`/`write`;
|
||||
- relacao entre semantica funcional de `fs` e fault semantics.
|
||||
@ -12,11 +12,15 @@ As agendas atuais são:
|
||||
|
||||
- `001-system-run-cart.md`
|
||||
- `002-packed-cartridge-loader-pmc.md`
|
||||
- `004-syscall-fault-classification.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`
|
||||
|
||||
## Sequenciamento Recomendado
|
||||
|
||||
@ -25,13 +29,17 @@ 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. `004-syscall-fault-classification.md`
|
||||
5. `009-filesystem-surface-and-semantics.md`
|
||||
6. `010-input-intrinsics-surface.md`
|
||||
7. `011-input-frame-semantics-and-portability.md`
|
||||
8. `005-runtime-edge-test-plan.md`
|
||||
9. `001-system-run-cart.md`
|
||||
10. `002-packed-cartridge-loader-pmc.md`
|
||||
4. `012-asset-fault-semantics-and-surface.md`
|
||||
5. `013-audio-fault-semantics-and-surface.md`
|
||||
6. `014-gfx-fault-semantics-and-command-contract.md`
|
||||
7. `001-system-run-cart.md`
|
||||
8. `015-system-fault-semantics-and-control-surface.md`
|
||||
9. `009-filesystem-surface-and-semantics.md`
|
||||
10. `016-filesystem-fault-semantics.md`
|
||||
11. `010-input-intrinsics-surface.md`
|
||||
12. `011-input-frame-semantics-and-portability.md`
|
||||
13. `005-runtime-edge-test-plan.md`
|
||||
14. `002-packed-cartridge-loader-pmc.md`
|
||||
|
||||
Justificativa curta:
|
||||
|
||||
@ -39,8 +47,12 @@ Justificativa curta:
|
||||
- `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.
|
||||
- a decisao `003` ja fechou o contrato base para trafego de bytes VM-owned e agora deve ser consumida, nao rediscutida aqui.
|
||||
- `004` fecha a taxonomia de falhas que `fs` e outras bordas vao reutilizar.
|
||||
- `009` usa a decisao `003` e a agenda `004` para fechar o dominio de filesystem sem texto improvisado.
|
||||
- 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.
|
||||
@ -49,10 +61,15 @@ Dependências principais:
|
||||
|
||||
- `008` depende de `007`
|
||||
- `006` depende de `007`
|
||||
- `009` depende da decisao `003` e da agenda `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`, da decisao `003`, de `004`, de `005` e deve alinhar com `009` quando usar `fs`
|
||||
- `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:
|
||||
|
||||
151
docs/runtime/decisions/004-host-fault-taxonomy.md
Normal file
151
docs/runtime/decisions/004-host-fault-taxonomy.md
Normal file
@ -0,0 +1,151 @@
|
||||
# Decision Record - Host Fault Taxonomy
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Contexto
|
||||
|
||||
A fronteira host-backed do runtime misturava quatro coisas diferentes:
|
||||
|
||||
- fault recuperavel de servico;
|
||||
- quebra terminal do app/VM;
|
||||
- falha estrutural grave do runtime;
|
||||
- indisponibilidade do host.
|
||||
|
||||
Ao mesmo tempo, a decisao `003-vm-owned-byte-transfer-protocol.md` ja fixou uma direcao importante:
|
||||
|
||||
- quando existir contrato funcional de retorno, o protocolo deve preferir `status`;
|
||||
- `Trap` nao deve ser usado para carregar erro operacional comum;
|
||||
- `Panic` deve ficar restrito a inconsistencia interna.
|
||||
|
||||
O codigo atual ainda revela severidade errada em varios pontos, por exemplo:
|
||||
|
||||
- `AssetLoad` promovendo erro operacional para `Panic`;
|
||||
- helpers de extracao promovendo argumento ausente para `Panic`;
|
||||
- `VmFault::Unavailable` sendo degradado para `Panic` no loop da VM.
|
||||
|
||||
## Decisao
|
||||
|
||||
### 1. Classes canonicas
|
||||
|
||||
A taxonomia canonica na fronteira host-backed passa a ser:
|
||||
|
||||
- `status`
|
||||
- `Trap`
|
||||
- `Panic`
|
||||
|
||||
`Unavailable` deixa de ser classe desejada do modelo.
|
||||
|
||||
### 2. `status`
|
||||
|
||||
- `status` representa fault recuperavel do servico.
|
||||
- Cada dominio pode ter seus proprios codigos/status.
|
||||
- Nao sera criado enum global unico de status para todos os dominios.
|
||||
- Quando a surface da operacao comportar retorno funcional, deve-se preferir `status` ao maximo.
|
||||
|
||||
Exemplos:
|
||||
|
||||
- recurso ausente;
|
||||
- handle desconhecido de dominio;
|
||||
- path nao encontrado;
|
||||
- permissao negada;
|
||||
- EOF;
|
||||
- escrita parcial/falha operacional;
|
||||
- indisponibilidade funcional recuperavel.
|
||||
|
||||
### 3. `Trap`
|
||||
|
||||
- `Trap` quebra a VM/app atual.
|
||||
- O firmware assume a partir da tela de crash.
|
||||
- `Trap` deve ser usado para erro estrutural de chamada, uso incorreto da ABI ou contrato que o guest nao recupera em runtime.
|
||||
|
||||
Exemplos:
|
||||
|
||||
- tipo de argumento errado;
|
||||
- aridade invalida;
|
||||
- syscall ou intrinsic invalido;
|
||||
- capability ausente;
|
||||
- shape de chamada impossivel para a ABI.
|
||||
|
||||
### 4. `Panic`
|
||||
|
||||
- `Panic` representa falha estrutural grave do runtime.
|
||||
- `Panic` nao descreve erro do app, e sim risco de quebra do proprio Prometeu/runtime/host integration.
|
||||
- `Panic` fica reservado para bug interno ou inconsistencia de implementacao.
|
||||
|
||||
Exemplos:
|
||||
|
||||
- metadata incoerente;
|
||||
- mismatch entre `ret_slots` declarados e retorno efetivo;
|
||||
- invariantes internas quebradas;
|
||||
- branch impossivel do runtime.
|
||||
|
||||
### 5. `Unavailable`
|
||||
|
||||
- `Unavailable` torna-se candidato a remocao do modelo.
|
||||
- A direcao aceita e:
|
||||
- indisponibilidade funcional recuperavel deve virar `status`;
|
||||
- colapso estrutural de integracao host/runtime deve virar `Panic`;
|
||||
- `Unavailable` nao deve ser expandido para novos dominios.
|
||||
|
||||
## Aplicacao por Dominio
|
||||
|
||||
### Assets
|
||||
|
||||
- `assets` e dominio `status-first`.
|
||||
- `AssetLoad` nao deve promover erro operacional comum para `Panic`.
|
||||
- `AssetStatus` confirma que o dominio ja tem semantica de status.
|
||||
- `commit`/`cancel` podem precisar de surface mais rica para evitar `Panic` indevido.
|
||||
|
||||
### Audio
|
||||
|
||||
- `audio` e dominio command-driven.
|
||||
- A direcao aceita e `Trap` estrutural + no-op/fallback deterministico ou `status` quando a surface passar a expor isso.
|
||||
- `audio` nao deve ser `panic-first`.
|
||||
|
||||
### Gfx
|
||||
|
||||
- `gfx` e dominio command-style.
|
||||
- A direcao aceita e `Trap` para erro estrutural de chamada e no-op/fallback/clamp para casos de dominio, conforme a semantica de cada comando.
|
||||
- `Panic` em `gfx` deve ficar restrito a colapso estrutural do runtime grafico.
|
||||
|
||||
### System
|
||||
|
||||
- `system` deve evitar `Panic` para falhas funcionais normais.
|
||||
- A taxonomia final de `run_cart` depende da agenda `001-system-run-cart.md`.
|
||||
|
||||
### Byte transfer
|
||||
|
||||
Para `read`/`write` e ops que reutilizem a decisao `003`:
|
||||
|
||||
- erros observaveis do protocolo devem virar `status`;
|
||||
- `Trap` praticamente sai da jogada;
|
||||
- `Panic` fica restrito a inconsistencia interna.
|
||||
|
||||
## Consequencias
|
||||
|
||||
### Positivas
|
||||
|
||||
- o runtime separa erro recuperavel de colapso terminal;
|
||||
- dominios host-backed ficam livres para usar `HostReturn` de forma rica;
|
||||
- `Panic` encolhe e passa a carregar gravidade real;
|
||||
- crash reports e telemetria ficam semanticamente melhores.
|
||||
|
||||
### Custos
|
||||
|
||||
- algumas surfaces publicas podem precisar mudar para devolver `status`;
|
||||
- o uso atual de `VmFault` precisara de limpeza por dominio;
|
||||
- o loop da VM precisara deixar de tratar `Unavailable` como caminho normal.
|
||||
|
||||
## Follow-up Obrigatorio
|
||||
|
||||
As seguintes agendas derivam desta decisao:
|
||||
|
||||
- `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`
|
||||
|
||||
`016-filesystem-fault-semantics.md` so deve ser discutida depois da `009-filesystem-surface-and-semantics.md`.
|
||||
@ -17,3 +17,4 @@ Regra de uso:
|
||||
Decisoes atuais:
|
||||
|
||||
- `003-vm-owned-byte-transfer-protocol.md`
|
||||
- `004-host-fault-taxonomy.md`
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user