prometeu-runtime/docs/runtime/decisions/004-host-fault-taxonomy.md

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 009-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:

• 006-asset-fault-semantics-and-surface.md
• 005-audio-fault-semantics-and-surface.md
• 004-gfx-fault-semantics-and-command-contract.md
• 010-system-fault-semantics-and-control-surface.md
• 003-filesystem-fault-semantics.md

003-filesystem-fault-semantics.md so deve ser discutida depois da 002-filesystem-surface-and-semantics.md.