diff --git a/docs/runtime/agendas/004-syscall-fault-classification.md b/docs/runtime/agendas/004-syscall-fault-classification.md deleted file mode 100644 index 611c33ae..00000000 --- a/docs/runtime/agendas/004-syscall-fault-classification.md +++ /dev/null @@ -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. diff --git a/docs/runtime/agendas/009-filesystem-surface-and-semantics.md b/docs/runtime/agendas/009-filesystem-surface-and-semantics.md index c3f16b31..02e44c84 100644 --- a/docs/runtime/agendas/009-filesystem-surface-and-semantics.md +++ b/docs/runtime/agendas/009-filesystem-surface-and-semantics.md @@ -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 diff --git a/docs/runtime/agendas/012-asset-fault-semantics-and-surface.md b/docs/runtime/agendas/012-asset-fault-semantics-and-surface.md new file mode 100644 index 00000000..58eb1979 --- /dev/null +++ b/docs/runtime/agendas/012-asset-fault-semantics-and-surface.md @@ -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. diff --git a/docs/runtime/agendas/013-audio-fault-semantics-and-surface.md b/docs/runtime/agendas/013-audio-fault-semantics-and-surface.md new file mode 100644 index 00000000..5bebafcb --- /dev/null +++ b/docs/runtime/agendas/013-audio-fault-semantics-and-surface.md @@ -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. diff --git a/docs/runtime/agendas/014-gfx-fault-semantics-and-command-contract.md b/docs/runtime/agendas/014-gfx-fault-semantics-and-command-contract.md new file mode 100644 index 00000000..aba98cb2 --- /dev/null +++ b/docs/runtime/agendas/014-gfx-fault-semantics-and-command-contract.md @@ -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. diff --git a/docs/runtime/agendas/015-system-fault-semantics-and-control-surface.md b/docs/runtime/agendas/015-system-fault-semantics-and-control-surface.md new file mode 100644 index 00000000..51244b31 --- /dev/null +++ b/docs/runtime/agendas/015-system-fault-semantics-and-control-surface.md @@ -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. diff --git a/docs/runtime/agendas/016-filesystem-fault-semantics.md b/docs/runtime/agendas/016-filesystem-fault-semantics.md new file mode 100644 index 00000000..558dabc7 --- /dev/null +++ b/docs/runtime/agendas/016-filesystem-fault-semantics.md @@ -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. diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index c9a17767..42a25312 100644 --- a/docs/runtime/agendas/README.md +++ b/docs/runtime/agendas/README.md @@ -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: diff --git a/docs/runtime/decisions/004-host-fault-taxonomy.md b/docs/runtime/decisions/004-host-fault-taxonomy.md new file mode 100644 index 00000000..e422b1bb --- /dev/null +++ b/docs/runtime/decisions/004-host-fault-taxonomy.md @@ -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`. diff --git a/docs/runtime/decisions/README.md b/docs/runtime/decisions/README.md index 0daf84bf..e4d672f1 100644 --- a/docs/runtime/decisions/README.md +++ b/docs/runtime/decisions/README.md @@ -17,3 +17,4 @@ Regra de uso: Decisoes atuais: - `003-vm-owned-byte-transfer-protocol.md` +- `004-host-fault-taxonomy.md`