# Save Memory and MEMCARD

Status: pedagogical
Companion spec: [`../specs/08-save-memory-and-memcard.md`](../specs/08-save-memory-and-memcard.md)
Historical snapshot: [`historical-game-memcard-slots-surface-and-semantics.md`](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.