implements memcard
This commit is contained in:
@@ -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.
|
||||
@@ -24,6 +24,7 @@ Ela existe para explicar o modelo mental da fantasy handheld, suas influências,
|
||||
- [`008-gfx-status-first-fault-and-return-contract.md`](008-gfx-status-first-fault-and-return-contract.md)
|
||||
- [`009-audio-status-first-fault-and-return-contract.md`](009-audio-status-first-fault-and-return-contract.md)
|
||||
- [`010-asset-status-first-fault-and-return-contract.md`](010-asset-status-first-fault-and-return-contract.md)
|
||||
- [`011-game-memcard-slots-surface-and-semantics.md`](011-game-memcard-slots-surface-and-semantics.md)
|
||||
|
||||
## Rules
|
||||
|
||||
|
||||
Reference in New Issue
Block a user