prometeu-runtime/docs/runtime/learn/mental-model-save-memory-and-memcard.md

Save Memory and MEMCARD

Status: pedagogical Companion spec: ../specs/08-save-memory-and-memcard.md Historical snapshot: historical-game-memcard-slots-surface-and-semantics.md

PROMETEU trata persistência como hardware explícito, não como save invisível.

Mental Model

O MEMCARD não é save state. Ele é um dispositivo de persistência controlado pelo jogo.

Isso implica:

• tamanho conhecido;
• custo observável;
• necessidade de commit();
• possibilidade de falha;
• formato de dados sob controle do jogo.

Slot Thinking

O modelo certo nao e "o jogo salva arquivos". O modelo certo e "o jogo conversa com slots".

Isso muda o jeito de pensar persistencia:

• capacidade e finita e conhecida;
• cada slot tem identidade e estado;
• ownership pertence ao app_id do cart;
• o jogo nao ganha acesso amplo ao filesystem do host.

Essa escolha existe para manter:

• portabilidade;
• isolamento entre apps;
• UX previsivel de save;
• contrato executavel em desktop e hardware dedicado.

Staged Versus Committed

Uma intuicao importante em MEMCARD e a diferenca entre:

• mexer no conteudo em staging;
• tornar a escrita persistida de fato.

commit() existe para separar essas duas fases.

Isso ensina um modelo de persistencia mais honesto:

• escrever ainda nao e persistir;
• persistir tem custo;
• persistir pode falhar;
• atomicidade importa.

Why Explicit Commit Matters

O commit() existe para tornar persistência uma decisão técnica visível.

Sem ele, não há ilusão de que “salvar simplesmente aconteceu”. O jogo precisa assumir quando quer:

• materializar escrita;
• aceitar custo;
• lidar com risco de perda ou corrupção.

Runtime-Owned Metadata

Mesmo quando o payload pertence ao jogo, alguns aspectos do slot pertencem a maquina:

• integridade;
• geracao/versionamento;
• estado do slot;
• isolamento por ownership.

Isso evita que cada jogo reinvente sua propria semantica basica de persistencia e permite que tooling e Hub/OS apresentem save de forma coerente.

Hub/OS Role

PROMETEU separa claramente:

• o jogo grava e le seus slots;
• o Hub/OS faz export, import, copia e apresentacao de saves.

Essa separacao impede que userland vire um mini-gerenciador de arquivos e mantem as operacoes de sistema na camada certa.

Tooling Surface

Ferramentas externas podem expor utilidades como:

• criar ou resetar MEMCARD;
• importar e exportar .mem;
• inspecionar tamanho e uso;
• associar cartões a projetos.

Essas superfícies são auxiliares. Elas não mudam o contrato da máquina.

Why This Is Better Than Broad FS For Games

Para perfil game, o modelo de slot e melhor que abrir um filesystem geral porque:

• reduz ambiguidade de path, permissao e ownership;
• facilita import/export controlado;
• melhora compatibilidade entre hosts;
• deixa mais claro o que significa "save valido" para a maquina.

Why This Fits PROMETEU

Esse modelo conversa bem com a herança de console e com o foco DIY do projeto: persistência é parte do design da máquina, não conveniência escondida do host.