prometeu-runtime/docs/runtime/agendas/012-asset-fault-semantics-and-surface.md

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
• dispatch.rs
• dispatch.rs

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.