docs: close agenda 013 with memcard game slots decision
This commit is contained in:
parent
6a894b987d
commit
f714db77fc
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -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.
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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<Bytes>, offset:int, max_bytes:int) -> (status:int, bytes_read:int)`
|
||||
- `slot_write(slot:int, buf:HeapRef<Bytes>, 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<Bytes>` + 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.
|
||||
@ -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/`):
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user