From f714db77fc8904881552a15699f667ee06f95423 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Mon, 9 Mar 2026 07:54:31 +0000 Subject: [PATCH] docs: close agenda 013 with memcard game slots decision --- ...ame-memcard-slots-surface-and-semantics.md | 125 ----------------- ...p-home-filesystem-surface-and-semantics.md | 2 +- docs/runtime/agendas/README.md | 19 ++- .../003-vm-owned-byte-transfer-protocol.md | 2 +- .../007-filesystem-fault-core-policy.md | 12 +- ...ame-memcard-slots-surface-and-semantics.md | 129 ++++++++++++++++++ docs/runtime/decisions/README.md | 1 + 7 files changed, 146 insertions(+), 144 deletions(-) delete mode 100644 docs/runtime/agendas/013-game-memcard-slots-surface-and-semantics.md create mode 100644 docs/runtime/decisions/011-game-memcard-slots-surface-and-semantics.md 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 deleted file mode 100644 index fa281c9b..00000000 --- a/docs/runtime/agendas/013-game-memcard-slots-surface-and-semantics.md +++ /dev/null @@ -1,125 +0,0 @@ -# Agenda - Game Memcard Slots Surface and Semantics - -## Problema - -Jogos precisam de persistencia previsivel e portavel para save/config/blob, sem abrir acesso amplo ao filesystem. - -Ao mesmo tempo, copia de saves deve acontecer fora do jogo (Hub/OS), com identificacao digital e visual por slot. - -## Inputs Ja Fechados - -1. Perfil `game` usa 32 slots por jogo. -2. Cada slot oferece payload de ate 32KB. -3. Jogo acessa somente os proprios slots. -4. `commit` e atomico por slot. -5. Copia/export/import de slots ocorre fora do jogo. - -## Alvo da Discussao - -Fechar o contrato de slots de memcard para jogos, usando a decisao `003` como data plane de bytes. - -## O Que Precisa Ser Definido - -1. Surface minima para jogos. - Operacoes candidatas: - - `slot_count`; - - `slot_stat`; - - `slot_read`; - - `slot_write`; - - `slot_commit`; - - `slot_clear`. - -2. Envelope de identidade do slot. - Definir metadados runtime-owned: - - `app_id` dono; - - `slot_index`; - - `save_uuid`/generation; - - tamanho de payload; - - checksum/integridade; - - estado (`empty`, `used`, `corrupt`). - -3. Identidade visual do slot. - Definir metadados para Hub/OS: - - label/subtitulo; - - timestamp/logical counter; - - icone/preview (incluindo caminho para suporte futuro de icone animado estilo PSX). - -4. Politica de copia fora do jogo. - Definir: - - formato de export/import; - - validacoes de ownership; - - comportamento para conflito/duplicata/corrupcao. - -5. Integracao com storage host. - Definir: - - como slots viram arquivos fisicos no storage host; - - regra de namespace por jogo (`app_id`); - - garantias de atomicidade por slot. - -6. Fault/status do dominio. - Fechar fronteira de: - - `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 - -1. Qual fonte canonica de `app_id` unico no ecossistema? -2. Qual formato minimo do bloco visual do slot no v1? -3. Qual politica de integridade v1 (CRC somente vs assinatura adicional)? -4. Como o Hub deve tratar slots corrompidos sem quebrar UX? - -## 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` -- `../specs/16a-syscall-policies.md` - -## Fora de Escopo - -- acesso amplo de jogos ao FS por path; -- banco de dados ou sync remoto; -- APIs de app sandbox (fica na agenda `014`). - -## Criterio de Saida Desta Agenda - -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 + 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 d0f3b965..98a1fecd 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 @@ -116,7 +116,7 @@ No perfil `app` (`home` sandbox), esta agenda passa a ser a fonte normativa para ## Fora de Escopo -- slots de memcard para `game` (fica na agenda `013`); +- slots de memcard para `game` (fechado na decisao `011`); - acesso cross-app; - sync remoto/cloud; - DB embutido como contrato de plataforma. diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index 85d92576..3d245529 100644 --- a/docs/runtime/agendas/README.md +++ b/docs/runtime/agendas/README.md @@ -15,7 +15,6 @@ As agendas atuais são: - `009-system-run-cart.md` - `010-system-fault-semantics-and-control-surface.md` - `012-vm-owned-random-service.md` -- `013-game-memcard-slots-surface-and-semantics.md` - `014-app-home-filesystem-surface-and-semantics.md` ## Sequenciamento Recomendado @@ -23,20 +22,19 @@ As agendas atuais são: 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. `007-runtime-edge-test-plan.md` -5. `008-packed-cartridge-loader-pmc.md` -6. `009-system-run-cart.md` -7. `010-system-fault-semantics-and-control-surface.md` +2. `014-app-home-filesystem-surface-and-semantics.md` +3. `007-runtime-edge-test-plan.md` +4. `008-packed-cartridge-loader-pmc.md` +5. `009-system-run-cart.md` +6. `010-system-fault-semantics-and-control-surface.md` Justificativa curta: - `011` foi fechada pela decisao `006`. - `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). +- `013` foi fechada pela decisao `011` (memcard `32 x 32KB`, ownership, identidade e copia fora do jogo). - `014` fecha o contrato de `home` para apps sem abrir FS global. -- a decisao `007` fixa o nucleo de fault policy de `fs`; os detalhes ficam distribuidos em `013` e `014`. +- a decisao `007` fixa o nucleo de fault policy de `fs`; os detalhes ficam distribuidos entre decisao `011` (`game`) e agenda `014` (`app`). - a decisao `008` fixa o contrato status-first de `gfx`. - a decisao `009` fixa o contrato status-first de `audio`. - a decisao `010` fixa o contrato status-first de `asset`. @@ -47,11 +45,10 @@ Justificativa curta: Dependências principais: - `012` depende da decisao `006` e de `16`/`16a` -- `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`) - `007` depende da estabilizacao minima das agendas de superficie/fault por dominio - `008` depende de contrato fechado de `13-cartridge.md` + comportamento equivalente ao loader de diretorio -- `009` depende da decisao `003`, de `16a` e da decisao `006`, e deve alinhar com `013`/`014` quando usar `fs` +- `009` depende da decisao `003`, de `16a` e da decisao `006`, e deve alinhar com decisao `011`/agenda `014` quando usar `fs` - `010` depende de `16a` e da `009` Regra de uso: 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 86f1b846..6c23c458 100644 --- a/docs/runtime/decisions/003-vm-owned-byte-transfer-protocol.md +++ b/docs/runtime/decisions/003-vm-owned-byte-transfer-protocol.md @@ -142,7 +142,7 @@ Para suportar este protocolo, a VM precisa expor API canonica para: As seguintes agendas devem consumir esta decisao: -- `013-game-memcard-slots-surface-and-semantics.md` +- `011-game-memcard-slots-surface-and-semantics.md` (decisao que absorveu a agenda `013`) - `014-app-home-filesystem-surface-and-semantics.md` - discussoes futuras de data bank diff --git a/docs/runtime/decisions/007-filesystem-fault-core-policy.md b/docs/runtime/decisions/007-filesystem-fault-core-policy.md index c7d17542..c3e4edd3 100644 --- a/docs/runtime/decisions/007-filesystem-fault-core-policy.md +++ b/docs/runtime/decisions/007-filesystem-fault-core-policy.md @@ -10,13 +10,13 @@ A agenda `003-filesystem-fault-semantics.md` existia para fechar fault semantics Com o split de `fs` em: -- agenda `013` (`game` memcard slots); +- decisao `011` (`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`. +- os detalhes por perfil devem ser fechados no contrato de `game` e no de `app`. Isso permite remover a agenda `003` sem perder rigor. @@ -66,7 +66,7 @@ Se o dominio nao conseguir concluir a escrita segundo seu contrato de atomicidad - retorna `status` de falha; - nao mascara o resultado como sucesso. -### 6. Responsabilidade por perfil (movida para agendas `013` e `014`) +### 6. Responsabilidade por perfil (movida para decisao `011` e agenda `014`) Fica sob responsabilidade das agendas de superficie: @@ -84,15 +84,15 @@ A agenda `003-filesystem-fault-semantics.md` e considerada absorvida e removida. - 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. +- 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 `013` e `014` antes de PR final de implementacao. +- exige revisao de consistencia entre decisao `011` e agenda `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`; +- `011-game-memcard-slots-surface-and-semantics.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. diff --git a/docs/runtime/decisions/011-game-memcard-slots-surface-and-semantics.md b/docs/runtime/decisions/011-game-memcard-slots-surface-and-semantics.md new file mode 100644 index 00000000..225d7d84 --- /dev/null +++ b/docs/runtime/decisions/011-game-memcard-slots-surface-and-semantics.md @@ -0,0 +1,129 @@ +# Decision Record - Game Memcard Slots Surface and Semantics + +## Status + +Accepted + +## Contexto + +Jogos precisam de persistencia previsivel e portavel para save/config/blob, sem acesso amplo ao filesystem. + +A agenda `013-game-memcard-slots-surface-and-semantics.md` consolidou os inputs de produto: + +- `game` usa `32` slots por jogo; +- payload maximo por slot de `32KB`; +- jogo acessa somente slots do proprio `app_id`; +- persistencia explicita com `commit` atomico por slot; +- copia/export/import de saves ocorre fora do jogo (Hub/OS). + +Esta decisao fecha o contrato v1 do perfil `game` usando a decisao `003` como data plane de bytes. + +## Decisao + +### 1. Contrato base de capacidade e ownership + +- cada jogo possui exatamente `32` slots logicos (`0..31`); +- cada slot oferece payload util de ate `32 * 1024` bytes; +- acesso em userland e restrito ao `app_id` dono do cart carregado; +- nao existe acesso por path para jogos no v1. + +### 2. Surface minima de memcard (status-first) + +- `slot_count() -> (status:int, count:int)` +- `slot_stat(slot:int) -> (status:int, state:int, used_bytes:int, generation:int, checksum:int)` +- `slot_read(slot:int, buf:HeapRef, offset:int, max_bytes:int) -> (status:int, bytes_read:int)` +- `slot_write(slot:int, buf:HeapRef, offset:int, len:int) -> (status:int, bytes_written:int)` +- `slot_commit(slot:int) -> status:int` +- `slot_clear(slot:int) -> status:int` + +Regras: + +- `status` e sempre o primeiro retorno; +- operacoes de bytes usam `HeapRef` + janela explicita (`offset`, `max_bytes`/`len`); +- shape segue politica de `16a`. + +### 3. Envelope digital runtime-owned por slot + +Cada slot mantem metadados canonicos runtime-owned: + +- `app_id` dono; +- `slot_index`; +- `save_uuid`; +- `generation`; +- `payload_size`; +- `checksum`; +- `state` (`EMPTY`, `STAGED`, `COMMITTED`, `CORRUPT`). + +`generation` e `checksum` nao sao controlados manualmente pela userland: + +- `generation` incrementa a cada `slot_commit` bem-sucedido; +- `checksum` e recalculado pelo runtime no payload persistido. + +### 4. Envelope visual para Hub/OS + +O slot expoe metadados visuais para UX fora do jogo: + +- `label`; +- `subtitle`; +- `updated_at` (ou contador logico equivalente); +- `icon_ref` (v1 estatico, formato extensivel para animacao futura). + +### 5. Politica de escrita e atomicidade + +- `slot_write` altera staging (nao persiste no destino final); +- `slot_commit` aplica persistencia atomica por slot; +- sucesso parcial silencioso e proibido; +- em falha de commit, retorna `status` de erro e preserva invariante de atomicidade. + +### 6. Fronteira de fault class + +`memcard(game)` segue `16a`: + +- `Trap`: erro estrutural (slot fora da faixa, `HeapRef` invalido/dead, janela invalida, shape ABI invalido); +- `status`: erro operacional de dominio; +- `Panic`: apenas quebra de invariante interna. + +Catalogo minimo de status do dominio: + +- `OK`; +- `EMPTY`; +- `NOT_FOUND`; +- `NO_SPACE`; +- `ACCESS_DENIED`; +- `CORRUPT`; +- `CONFLICT`; +- `UNAVAILABLE`; +- `INVALID_STATE`. + +### 7. Politica de copia/export/import (fora do jogo) + +- copia/export/import e responsabilidade do Hub/OS; +- jogo nao recebe API para copiar slots entre apps; +- v1 valida ownership por `app_id` no import; +- conflito e corrupcao devem ser refletidos por status do dominio e UX do Hub. + +### 8. Integracao com storage host + +- namespace fisico isolado por `app_id`; +- representacao fisica por slot e interna ao runtime/host; +- persistencia deve usar estrategia atomica (arquivo temporario + flush + rename equivalente da plataforma). + +## Consequencias + +### Positivas + +- fecha o contrato de save de `game` sem abrir FS amplo; +- torna copy/export/import um fluxo de sistema (Hub/OS), nao de userland; +- padroniza integridade/versionamento de slot com `generation` + `checksum`. + +### Custos + +- exige implementacao de staging/commit atomico por slot; +- exige especificacao explicita do formato de export/import no Hub/OS; +- exige alinhamento com specs de memcard e ABI. + +## Follow-up Obrigatorio + +- a agenda `013-game-memcard-slots-surface-and-semantics.md` deve ser considerada fechada e removida; +- `specs/08-save-memory-and-memcard.md` deve absorver este contrato (`32 x 32KB`, slots por `app_id`, commit atomico); +- `specs/16-host-abi-and-syscalls.md` e `specs/16a-syscall-policies.md` devem absorver a surface e matriz de fault/status. diff --git a/docs/runtime/decisions/README.md b/docs/runtime/decisions/README.md index 07af1b23..6e2b58be 100644 --- a/docs/runtime/decisions/README.md +++ b/docs/runtime/decisions/README.md @@ -19,6 +19,7 @@ Decisoes ativas: - `003-vm-owned-byte-transfer-protocol.md` - `006-vm-owned-stateful-core-contract.md` - `007-filesystem-fault-core-policy.md` +- `011-game-memcard-slots-surface-and-semantics.md` Decisoes implementadas e aposentadas (migradas para `learn/`):