prometeu-runtime/docs/runtime/agendas/013-game-memcard-slots-surface-and-semantics.md

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.

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
• ../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 + fault/status para operacoes de slot.