# 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`.