prometeu-runtime/docs/agendas/004-syscall-fault-classification.md

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, input e system precisam seguir a mesma filosofia.

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.