# 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.