# Decision Record - Filesystem Fault Core Policy

## Status

Accepted

## Contexto

A agenda `003-filesystem-fault-semantics.md` existia para fechar fault semantics de `fs` depois das discussoes de superficie.

Com o split de `fs` em:

- `spec 08` (`game` memcard slots);
- agenda `014` (`app` home sandbox);

ficou claro que:

- existe um nucleo de politica que pode ser decidido agora;
- os detalhes por perfil devem ser fechados no contrato de `game` e no de `app`.

Isso permite remover a agenda `003` sem perder rigor.

## Decisao

### 1. Fronteira canonica de falhas para `fs`

`fs` segue o modelo de `16a`:

- `Trap`: violacao estrutural de contrato ABI/chamada.
- `status`: condicao operacional de dominio.
- `Panic`: quebra de invariante interno do runtime/host.

### 2. O que e estrutural (`Trap`) em `fs`

No dominio `fs`, sao estruturais:

- assinatura de chamada invalida (`arg_slots`/`ret_slots`);
- `HeapRef` invalido/dead;
- kind de objeto incompativel para a operacao;
- janela de bytes invalida (offset/length fora do buffer VM-owned).

### 3. O que e operacional (`status`) em `fs`

Sao operacionais (nao estruturais):

- recurso ausente (`not found`/slot vazio quando aplicavel);
- permissao/sandbox negada;
- `storage full`;
- indisponibilidade temporaria do backend;
- conflitos/corrupcao detectados no dominio.

### 4. Integracao obrigatoria com decisao `003`

Operacoes de bytes em `fs` devem usar:

- `HeapRef<Bytes>` VM-owned;
- janela explicita (`offset` + `max_bytes`);
- retorno com `status` e `bytes_transferred` quando aplicavel.

### 5. Regra de escrita parcial

`write` nao pode produzir sucesso parcial silencioso.

Se o dominio nao conseguir concluir a escrita segundo seu contrato de atomicidade:

- retorna `status` de falha;
- nao mascara o resultado como sucesso.

### 6. Responsabilidade por perfil (movida para `spec 08` e agenda `014`)

Fica sob responsabilidade das agendas de superficie:

- catalogo final de codigos `status` por operacao;
- matriz completa por operacao (`status`/`Trap`/`Panic`);
- shape final de retorno para cada operacao de cada perfil.

### 7. Encerramento da agenda `003`

A agenda `003-filesystem-fault-semantics.md` e considerada absorvida e removida.

## Consequencias

### Positivas

- elimina uma agenda transversal que atrasava fechamento;
- preserva um nucleo unico de fault policy para todo `fs`;
- deixa `game` e `app` focados nos detalhes reais de produto.

### Custos

- exige disciplina para manter a matriz de faults distribuida em duas agendas;
- exige revisao de consistencia entre `spec 08` e agenda `014` antes de PR final de implementacao.

## Follow-up Obrigatorio

- `spec 08-save-memory-and-memcard.md` fecha a matriz de fault/status do perfil `game`;
- `014-app-home-filesystem-surface-and-semantics.md` deve incluir a matriz de fault/status do perfil `app`;
- specs `16`/`16a` devem absorver esta decisao quando o contrato estiver implementado e estavel.