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