prometeu-runtime/docs/runtime/learn/010-asset-status-first-fault-and-return-contract.md

Decision Record - Asset Status-First Fault and Return Contract

Status

Accepted

Contexto

A agenda 006-asset-fault-semantics-and-surface.md evidenciou inconsistencia no dominio asset:

• asset.status ja usa status numerico;
• asset.load ainda escalava erro operacional para Panic;
• asset.commit/asset.cancel eram void com no-op silencioso para varios casos.

Para alinhar o dominio com 16a, foi fechado contrato status-first para asset.

Decisao

1. Fronteira de fault class em asset

asset segue:

• Trap: violacao estrutural de ABI/chamada (tipo, aridade, capability, shape).
• status (inteiro): erro operacional recuperavel de dominio.
• Panic: apenas quebra de invariante interna de runtime/host.

2. Surface canonica do dominio

A surface final do MVP fica:

• asset.load(name, kind, slot) -> (status:int, handle:int)
• asset.status(handle) -> status:int
• asset.commit(handle) -> status:int
• asset.cancel(handle) -> status:int

Regras:

• handle so e valido quando status == ASSET_OK;
• em falha de load, handle deve ser 0.

3. No-op silencioso proibido

No-op silencioso nao e permitido para operacoes com erro operacional possivel.

Casos como:

• handle desconhecido;
• transicao invalida de lifecycle;
• slot invalido;
• asset ausente;

devem retornar status explicito.

4. asset.load (request path)

Falhas operacionais de request devem virar status, incluindo:

• ASSET_NOT_FOUND;
• SLOT_KIND_MISMATCH;
• SLOT_INDEX_INVALID;
• BACKEND_ERROR.

Panic nao deve ser usado para falha operacional de load.

5. asset.status (lifecycle path)

asset.status permanece a fonte de verdade do lifecycle assíncrono.

Codigos de lifecycle devem cobrir:

• PENDING
• LOADING
• READY
• COMMITTED
• CANCELED
• ERROR
• UNKNOWN_HANDLE

6. asset.commit e asset.cancel

Ambas operacoes devem retornar status.

Tabela minima de resposta:

• ASSET_OK (acao aceita/concluida para o estado atual)
• UNKNOWN_HANDLE
• INVALID_STATE

7. Relacao com dominio bank

Erros de residency/slot permanecem no dominio asset.

bank permanece dominio de inspecao (info, slot_info) e nao absorve erros operacionais de mutacao de asset lifecycle.

8. Compatibilidade e migracao

Nao ha requisito de compatibilidade retroativa para esta mudanca.

E permitido:

• alterar ret_slots de asset.load, asset.commit, asset.cancel;
• ajustar registry/loader/dispatch/runtime com o novo contrato;
• regenerar stress test com as assinaturas novas.

Consequencias

Positivas

• remove Panic operacional indevido do dominio asset;
• torna fluxo de lifecycle observavel e consistente;
• elimina ambiguidade de no-op em commit/cancel.

Custos

• exige migracao de ABI das syscalls asset;
• exige atualizacao de testes e artefatos gerados.

Follow-up Obrigatorio

• agenda 006-asset-fault-semantics-and-surface.md deve ser considerada absorvida e removida;
• specs 15 e 16a devem absorver o contrato final quando a implementacao estiver estavel;
• registry de syscall deve refletir o shape final (ret_slots) das operacoes asset.