improvements agendas and decisions
This commit is contained in:
@@ -99,20 +99,10 @@ Toda operacao atua sobre uma janela explicita da heap da VM:
|
||||
|
||||
### 8. Politica de falha
|
||||
|
||||
- O protocolo deve preferir `status` ao maximo.
|
||||
- Falhas operacionais e erros observaveis de contrato devem retornar `status`, nao `Trap`.
|
||||
- `Trap` fica reservado para bug/inconsistencia interna do runtime.
|
||||
|
||||
Isso inclui, por decisao arquitetural, que erros como:
|
||||
|
||||
- `host_handle` invalido;
|
||||
- `HeapRef(Byte)` invalido;
|
||||
- kind incorreto;
|
||||
- offset invalido;
|
||||
- janela invalida;
|
||||
- indisponibilidade operacional do host;
|
||||
|
||||
devem ser modelados como `status`, nao como `Trap`, salvo se revelarem inconsistencia interna do runtime.
|
||||
- Esta decisao define o data plane de bytes, nao a taxonomia final de faults por dominio.
|
||||
- Condicoes operacionais devem retornar `status`.
|
||||
- Violacoes estruturais de chamada/ABI seguem `16a` e a decisao de fault policy do dominio.
|
||||
- Para `fs`, a classificacao normativa esta na decisao `007-filesystem-fault-core-policy.md`.
|
||||
|
||||
### 9. API minima necessaria na VM
|
||||
|
||||
|
||||
@@ -0,0 +1,98 @@
|
||||
# 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.
|
||||
@@ -18,6 +18,7 @@ Decisoes ativas:
|
||||
|
||||
- `003-vm-owned-byte-transfer-protocol.md`
|
||||
- `006-vm-owned-stateful-core-contract.md`
|
||||
- `007-filesystem-fault-core-policy.md`
|
||||
|
||||
Decisoes aposentadas que ja viraram spec:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user