99 lines
2.9 KiB
Markdown
99 lines
2.9 KiB
Markdown
# 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:
|
|
|
|
- agenda `013` (`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 dentro de `013` e `014`.
|
|
|
|
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 agendas `013` e `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 `013` e `014` focadas nos detalhes reais de produto.
|
|
|
|
### Custos
|
|
|
|
- exige disciplina para manter a matriz de faults distribuida em duas agendas;
|
|
- exige revisao de consistencia entre `013` e `014` antes de PR final de implementacao.
|
|
|
|
## Follow-up Obrigatorio
|
|
|
|
- `013-game-memcard-slots-surface-and-semantics.md` deve incluir 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.
|