diff --git a/docs/runtime/agendas/003-filesystem-fault-semantics.md b/docs/runtime/agendas/003-filesystem-fault-semantics.md deleted file mode 100644 index 24b9b9a3..00000000 --- a/docs/runtime/agendas/003-filesystem-fault-semantics.md +++ /dev/null @@ -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. diff --git a/docs/runtime/agendas/013-game-memcard-slots-surface-and-semantics.md b/docs/runtime/agendas/013-game-memcard-slots-surface-and-semantics.md index 9c47e7c9..fa281c9b 100644 --- a/docs/runtime/agendas/013-game-memcard-slots-surface-and-semantics.md +++ b/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. diff --git a/docs/runtime/agendas/014-app-home-filesystem-surface-and-semantics.md b/docs/runtime/agendas/014-app-home-filesystem-surface-and-semantics.md index 051d551e..d0f3b965 100644 --- a/docs/runtime/agendas/014-app-home-filesystem-surface-and-semantics.md +++ b/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`. diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index 58ad86d4..a9bf7ea3 100644 --- a/docs/runtime/agendas/README.md +++ b/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` -5. `004-gfx-fault-semantics-and-command-contract.md` -6. `005-audio-fault-semantics-and-surface.md` -7. `006-asset-fault-semantics-and-surface.md` -8. `007-runtime-edge-test-plan.md` -9. `008-packed-cartridge-loader-pmc.md` -10. `009-system-run-cart.md` -11. `010-system-fault-semantics-and-control-surface.md` +4. `004-gfx-fault-semantics-and-command-contract.md` +5. `005-audio-fault-semantics-and-surface.md` +6. `006-asset-fault-semantics-and-surface.md` +7. `007-runtime-edge-test-plan.md` +8. `008-packed-cartridge-loader-pmc.md` +9. `009-system-run-cart.md` +10. `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`) -- `014` depende da decisao `003`, de `16a`, de `12` (Hub/OS) e de `13` (`app_mode`) -- `003` depende da decisao `003`, de `16a`, da `013` e da `014` +- `013` depende das decisoes `003`/`007`, de `16a`, de `08` (memcard), 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`) - `004` depende de `16a` - `005` depende de `16a` - `006` depende de `16a` diff --git a/docs/runtime/decisions/003-vm-owned-byte-transfer-protocol.md b/docs/runtime/decisions/003-vm-owned-byte-transfer-protocol.md index a9d105e9..86f1b846 100644 --- a/docs/runtime/decisions/003-vm-owned-byte-transfer-protocol.md +++ b/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. -- 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 diff --git a/docs/runtime/decisions/007-filesystem-fault-core-policy.md b/docs/runtime/decisions/007-filesystem-fault-core-policy.md new file mode 100644 index 00000000..c7d17542 --- /dev/null +++ b/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` 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. diff --git a/docs/runtime/decisions/README.md b/docs/runtime/decisions/README.md index 91775f63..042f79fd 100644 --- a/docs/runtime/decisions/README.md +++ b/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: