docs: close agenda 013 with memcard game slots decision

This commit is contained in:
2026-03-24 13:40:51 +00:00
parent 6a894b987d
commit f714db77fc
7 changed files with 146 additions and 144 deletions
@@ -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.
@@ -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.
+8 -11
View File
@@ -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: