116 lines
3.2 KiB
Markdown
116 lines
3.2 KiB
Markdown
---
|
|
id: LSN-0015
|
|
ticket: legacy-runtime-learn-import
|
|
title: Save Memory and MEMCARD
|
|
created: 2026-03-27
|
|
tags: [migration, tech-debt]
|
|
---
|
|
|
|
# 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`](LSN-0005-historical-game-memcard-slots-surface-and-semantics.md)
|
|
|
|
PROMETEU treats persistence as explicit hardware, not as invisible save behavior.
|
|
|
|
## Mental Model
|
|
|
|
MEMCARD is not save state. It is a persistence device controlled by the game.
|
|
|
|
That implies:
|
|
|
|
- known size;
|
|
- observable cost;
|
|
- the need for `commit()`;
|
|
- the possibility of failure;
|
|
- a data format under the game's control.
|
|
|
|
## Slot Thinking
|
|
|
|
The right model is not "the game saves files". The right model is "the game talks to slots".
|
|
|
|
That changes how you think about persistence:
|
|
|
|
- capacity is finite and known;
|
|
- each slot has identity and state;
|
|
- ownership belongs to the cart's `app_id`;
|
|
- the game does not get broad access to the host filesystem.
|
|
|
|
That choice exists to preserve:
|
|
|
|
- portability;
|
|
- isolation between apps;
|
|
- predictable save UX;
|
|
- a contract that runs on desktop and dedicated hardware.
|
|
|
|
## Staged Versus Committed
|
|
|
|
An important MEMCARD intuition is the difference between:
|
|
|
|
- changing content in staging;
|
|
- making the write actually persistent.
|
|
|
|
`commit()` existe para separar essas duas fases.
|
|
|
|
That teaches a more honest model of persistence:
|
|
|
|
- writing is not yet persisting;
|
|
- persisting has a cost;
|
|
- persisting can fail;
|
|
- atomicity matters.
|
|
|
|
## Why Explicit Commit Matters
|
|
|
|
`commit()` exists to make persistence a visible technical decision.
|
|
|
|
Without it, there is no illusion that "saving simply happened". The game must decide when it wants to:
|
|
|
|
- materialize a write;
|
|
- accept the cost;
|
|
- deal with the risk of loss or corruption.
|
|
|
|
## Runtime-Owned Metadata
|
|
|
|
Even when the payload belongs to the game, some aspects of the slot belong to the machine:
|
|
|
|
- integrity;
|
|
- generation/versioning;
|
|
- slot state;
|
|
- ownership isolation.
|
|
|
|
That prevents each game from reinventing its own basic persistence semantics and lets tooling and Hub/OS present save data coherently.
|
|
|
|
## Hub/OS Role
|
|
|
|
PROMETEU separates clearly:
|
|
|
|
- the game writes and reads its own slots;
|
|
- the Hub/OS handles export, import, copy, and save presentation.
|
|
|
|
That separation prevents userland from becoming a mini file manager and keeps system operations in the right layer.
|
|
|
|
## Tooling Surface
|
|
|
|
External tools may expose utilities such as:
|
|
|
|
- create or reset MEMCARD;
|
|
- import and export `.mem`;
|
|
- inspect size and usage;
|
|
- associate cards with projects.
|
|
|
|
Those surfaces are auxiliary. They do not change the machine contract.
|
|
|
|
## Why This Is Better Than Broad FS For Games
|
|
|
|
For the `game` profile, the slot model is better than exposing a broad filesystem because:
|
|
|
|
- it reduces ambiguity around path, permission, and ownership;
|
|
- it makes controlled import/export easier;
|
|
- it improves compatibility across hosts;
|
|
- it makes it clearer what a "valid save" means to the machine.
|
|
|
|
## Why This Fits PROMETEU
|
|
|
|
This model fits well with the project's console heritage and DIY focus: persistence is part of the machine design, not convenience hidden inside the host.
|