prometeu-runtime/docs/runtime/decisions/007-filesystem-fault-core-policy.md

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.