improvements agendas and decisions

docs/runtime/agendas/003-filesystem-fault-semantics.md

@@ -1,49 +0,0 @@
-# Agenda - Filesystem Fault Semantics
-
-## Problema
-
-O dominio `fs` certamente precisara de politica de fault propria, mas ainda depende de duas discussoes anteriores:
-
-- a decisao `003` sobre transporte de bytes;
-- a agenda `013` sobre superficie/semantica de memcard para `game`;
-- a agenda `014` sobre superficie/semantica de `home` para `app`.
-
-Discutir fault semantics antes disso tende a cristalizar classificacao em cima de uma API que ainda pode mudar.
-
-## Alvo da Discussao
-
-Fechar a politica de fault de `fs` somente depois das agendas `013` e `014`.
-
-## O Que Precisa Ser Definido
-
-1. Fronteira entre `status` e `Trap` em `fs`.
-2. Politica para:
-   - handle invalido;
-   - path invalido;
-   - arquivo ausente;
-   - permissao negada;
-   - EOF;
-   - escrita parcial;
-   - storage full;
-   - mount indisponivel.
-3. Integracao com o protocolo de bytes da decisao `003`.
-4. Shape final de retorno das operacoes de `fs`.
-
-## Dependencias
-
-- `../decisions/003-vm-owned-byte-transfer-protocol.md`
-- `../specs/16a-syscall-policies.md`
-- `013-game-memcard-slots-surface-and-semantics.md`
-- `014-app-home-filesystem-surface-and-semantics.md`
-
-## Regra de Sequenciamento
-
-Esta agenda nao deve ser discutida antes da `013` e da `014`.
-
-## Critério de Saida Desta Agenda
-
-Pode virar PR quando houver decisao escrita sobre:
-
-- matriz de `status`/`Trap`/`Panic` para `fs`;
-- integracao final com `read`/`write`;
-- relacao entre semantica funcional de `fs` e fault semantics.

docs/runtime/agendas/013-game-memcard-slots-surface-and-semantics.md

@@ -61,6 +61,37 @@ Fechar o contrato de slots de memcard para jogos, usando a decisao `003` como da
    - `status` operacional;
    - `Trap` estrutural;
    - `Panic` interno.
+   E obrigatorio fechar, para cada operacao de slot, a matriz final de retorno e fault class.
+
+## Responsabilidade Absorvida da Agenda 003
+
+No perfil `game` (memcard), esta agenda passa a ser a fonte normativa para:
+
+1. Catalogo de `status` de memcard.
+   Minimo esperado:
+   - `OK`;
+   - `NOT_FOUND`/`EMPTY`;
+   - `NO_SPACE`;
+   - `ACCESS_DENIED`;
+   - `CORRUPT`;
+   - `CONFLICT`;
+   - `UNAVAILABLE`.
+
+2. Matriz por operacao (`slot_count`, `slot_stat`, `slot_read`, `slot_write`, `slot_commit`, `slot_clear`).
+   Para cada caso, classificar explicitamente:
+   - `status`;
+   - `Trap`;
+   - `Panic`.
+
+3. Shape de retorno por operacao.
+   Definir, no minimo:
+   - `status` como primeiro retorno;
+   - `bytes_transferred` em `slot_read`/`slot_write` quando aplicavel;
+   - flags auxiliares quando necessarias (ex.: estado de slot).
+
+4. Regra de escrita parcial.
+   `slot_write` nao pode reportar sucesso parcial silencioso.
+   Resultado deve respeitar a regra de atomicidade por slot.
 
 ## Open Questions de Arquitetura
 
@@ -72,6 +103,7 @@ Fechar o contrato de slots de memcard para jogos, usando a decisao `003` como da
 ## Dependencias
 
 - `../decisions/003-vm-owned-byte-transfer-protocol.md`
+- `../decisions/007-filesystem-fault-core-policy.md`
 - `../specs/08-save-memory-and-memcard.md`
 - `../specs/13-cartridge.md`
 - `../specs/12-firmware-pos-and-prometeuhub.md`
@@ -90,5 +122,4 @@ Pode virar PR quando houver decisao escrita sobre:
 - contrato de slots (`32 x 32KB`) e ownership por jogo;
 - envelope de identidade digital/visual do slot;
 - politica de copia fora do jogo;
-- surface minima + fault/status para operacoes de slot.
+- surface minima + matriz completa de fault/status por operacao de slot.
-

docs/runtime/agendas/014-app-home-filesystem-surface-and-semantics.md

@@ -67,6 +67,37 @@ Fechar a superficie e semantica funcional de `fs` para perfil `app`, com sandbox
    - `status` operacional;
    - `Trap` estrutural;
    - `Panic` interno.
+   E obrigatorio fechar, por operacao, a matriz final de retorno e fault class.
+
+## Responsabilidade Absorvida da Agenda 003
+
+No perfil `app` (`home` sandbox), esta agenda passa a ser a fonte normativa para:
+
+1. Catalogo de `status` de filesystem para app.
+   Minimo esperado:
+   - `OK`;
+   - `NOT_FOUND`;
+   - `PATH_INVALID`;
+   - `ACCESS_DENIED`;
+   - `NO_SPACE`;
+   - `ALREADY_EXISTS`;
+   - `UNAVAILABLE`.
+
+2. Matriz por operacao (`read`, `write`, `exists`, `stat`, `list_dir`, `delete`, `mkdir`, `rename`).
+   Para cada caso, classificar explicitamente:
+   - `status`;
+   - `Trap`;
+   - `Panic`.
+
+3. Shape de retorno por operacao.
+   Definir, no minimo:
+   - `status` como primeiro retorno;
+   - `bytes_transferred` em `read`/`write` quando aplicavel;
+   - payload de metadados/listagem com formato canonico.
+
+4. Regra de escrita parcial.
+   `write` nao pode reportar sucesso parcial silencioso.
+   Quando a operacao nao puder ser concluida conforme contrato, deve retornar falha de dominio.
 
 ## Open Questions de Arquitetura
 
@@ -78,6 +109,7 @@ Fechar a superficie e semantica funcional de `fs` para perfil `app`, com sandbox
 ## Dependencias
 
 - `../decisions/003-vm-owned-byte-transfer-protocol.md`
+- `../decisions/007-filesystem-fault-core-policy.md`
 - `../specs/13-cartridge.md`
 - `../specs/12-firmware-pos-and-prometeuhub.md`
 - `../specs/16a-syscall-policies.md`
@@ -96,4 +128,4 @@ Pode virar PR quando houver decisao escrita sobre:
 - surface minima de `fs` para `app` em `home`;
 - sandbox e isolamento por `app_id`;
 - semantica final de path/read/write/listagem;
-- fault/status para as operacoes do perfil `app`.
+- matriz completa de fault/status para as operacoes do perfil `app`.

docs/runtime/agendas/README.md

@@ -10,7 +10,6 @@ Objetivo:
 
 As agendas atuais são:
 
-- `003-filesystem-fault-semantics.md`
 - `004-gfx-fault-semantics-and-command-contract.md`
 - `005-audio-fault-semantics-and-surface.md`
 - `006-asset-fault-semantics-and-surface.md`
@@ -29,14 +28,13 @@ Ordem sugerida para discussão e futura execução:
 1. `012-vm-owned-random-service.md`
 2. `013-game-memcard-slots-surface-and-semantics.md`
 3. `014-app-home-filesystem-surface-and-semantics.md`
-4. `003-filesystem-fault-semantics.md`
+4. `004-gfx-fault-semantics-and-command-contract.md`
-5. `004-gfx-fault-semantics-and-command-contract.md`
+5. `005-audio-fault-semantics-and-surface.md`
-6. `005-audio-fault-semantics-and-surface.md`
+6. `006-asset-fault-semantics-and-surface.md`
-7. `006-asset-fault-semantics-and-surface.md`
+7. `007-runtime-edge-test-plan.md`
-8. `007-runtime-edge-test-plan.md`
+8. `008-packed-cartridge-loader-pmc.md`
-9. `008-packed-cartridge-loader-pmc.md`
+9. `009-system-run-cart.md`
-10. `009-system-run-cart.md`
+10. `010-system-fault-semantics-and-control-surface.md`
-11. `010-system-fault-semantics-and-control-surface.md`
 
 Justificativa curta:
 
@@ -44,18 +42,17 @@ Justificativa curta:
 - `012` e o primeiro consumidor da base stateful VM-owned fechada em `006`.
 - `013` fecha o contrato de memcard para jogos (`32 x 32KB`, ownership, identidade e copia fora do jogo).
 - `014` fecha o contrato de `home` para apps sem abrir FS global.
-- `003` vem depois de `013` e `014` para consolidar fault semantics de `fs` em ambos os perfis.
+- a decisao `007` fixa o nucleo de fault policy de `fs`; os detalhes ficam distribuidos em `013` e `014`.
 - `004`, `005` e `006` consolidam fault semantics por dominio com base em `16a`.
-- `007` vem depois para transformar as decisoes em cobertura de regressao na borda do runtime.
+- a agenda `007` vem depois para transformar as decisoes em cobertura de regressao na borda do runtime.
 - `008` e importante, mas nao bloqueia bytecode/backend agora.
 - `009` e `010` ficam no fim porque `run_cart` nao e objetivo do ciclo atual.
 
 Dependências principais:
 
 - `012` depende da decisao `006` e de `16`/`16a`
-- `013` depende da decisao `003`, de `16a`, de `08` (memcard), de `12` (Hub/OS) e de `13` (`app_mode`)
+- `013` depende das decisoes `003`/`007`, de `16a`, de `08` (memcard), de `12` (Hub/OS) e de `13` (`app_mode`)
-- `014` depende da decisao `003`, de `16a`, de `12` (Hub/OS) e de `13` (`app_mode`)
+- `014` depende das decisoes `003`/`007`, de `16a`, de `12` (Hub/OS) e de `13` (`app_mode`)
-- `003` depende da decisao `003`, de `16a`, da `013` e da `014`
 - `004` depende de `16a`
 - `005` depende de `16a`
 - `006` depende de `16a`

docs/runtime/decisions/003-vm-owned-byte-transfer-protocol.md

@@ -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.
+- Esta decisao define o data plane de bytes, nao a taxonomia final de faults por dominio.
-- Falhas operacionais e erros observaveis de contrato devem retornar `status`, nao `Trap`.
+- Condicoes operacionais devem retornar `status`.
-- `Trap` fica reservado para bug/inconsistencia interna do runtime.
+- 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`.
-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.
 
 ### 9. API minima necessaria na VM
 

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

@@ -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.

docs/runtime/decisions/README.md

@@ -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: