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