improvements agendas and decisions

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

@@ -0,0 +1,122 @@
+# 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`.