# Historical Snapshot - Game Memcard Slots Surface and Semantics

Status: historical snapshot in `learn`, not normative.
Current normative anchors:

- [`../specs/08-save-memory-and-memcard.md`](../../specs/08-save-memory-and-memcard.md)
- [`../specs/16-host-abi-and-syscalls.md`](../../specs/16-host-abi-and-syscalls.md)
- [`../specs/16a-syscall-policies.md`](../../specs/16a-syscall-policies.md)
- [`mental-model-save-memory-and-memcard.md`](mental-model-save-memory-and-memcard.md)
- [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)

## Status

Accepted

## Context

Games need predictable, portable persistence for save/config/blob data without broad filesystem access.

Agenda `013-game-memcard-slots-surface-and-semantics.md` consolidated the product inputs:

- `game` uses `32` slots per game;
- maximum payload per slot is `32KB`;
- the game accesses only slots owned by its own `app_id`;
- persistence is explicit, with atomic `commit` per slot;
- save copy/export/import happens outside the game (Hub/OS).

This decision closes the v1 contract for the `game` profile while using decision `003` as the byte data plane.

## Decision

### 1. Base capacity and ownership contract

- each game has exactly `32` logical slots (`0..31`);
- each slot offers up to `32 * 1024` bytes of usable payload;
- userland access is restricted to the `app_id` that owns the loaded cart;
- there is no path-based access for games in v1.

### 2. Minimum memcard surface (status-first)

- `slot_count() -> (status:int, count:int)`
- `slot_stat(slot:int) -> (status:int, state:int, used_bytes:int, generation:int, checksum:int)`
- `slot_read(slot:int, buf:HeapRef<Bytes>, offset:int, max_bytes:int) -> (status:int, bytes_read:int)`
- `slot_write(slot:int, buf:HeapRef<Bytes>, offset:int, len:int) -> (status:int, bytes_written:int)`
- `slot_commit(slot:int) -> status:int`
- `slot_clear(slot:int) -> status:int`

Rules:

- `status` is always the first return value;
- byte operations use `HeapRef<Bytes>` plus an explicit window (`offset`, `max_bytes`/`len`);
- shape follows the policy in `16a`.

### 3. Runtime-owned digital envelope per slot

Each slot keeps canonical runtime-owned metadata:

- owning `app_id`;
- `slot_index`;
- `save_uuid`;
- `generation`;
- `payload_size`;
- `checksum`;
- `state` (`EMPTY`, `STAGED`, `COMMITTED`, `CORRUPT`).

`generation` and `checksum` are not manually controlled by userland:

- `generation` increments on each successful `slot_commit`;
- `checksum` is recalculated by the runtime on the persisted payload.

### 4. Visual envelope for Hub/OS

The slot exposes visual metadata for UX outside the game:

- `label`;
- `subtitle`;
- `updated_at` (or equivalent logical counter);
- `icon_ref` (static in v1, extensible to future animation).

### 5. Write policy and atomicity

- `slot_write` changes staging (it does not persist to the final destination);
- `slot_commit` applies per-slot atomic persistence;
- silent partial success is forbidden;
- on commit failure, it returns error `status` and preserves the atomicity invariant.

### 6. Fault-class boundary

`memcard(game)` follows `16a`:

- `Trap`: structural error (slot out of range, invalid/dead `HeapRef`, invalid window, invalid ABI shape);
- `status`: operational domain error;
- `Panic`: internal invariant break only.

Minimum domain status catalog:

- `OK`;
- `EMPTY`;
- `NOT_FOUND`;
- `NO_SPACE`;
- `ACCESS_DENIED`;
- `CORRUPT`;
- `CONFLICT`;
- `UNAVAILABLE`;
- `INVALID_STATE`.

### 7. Copy/export/import policy (outside the game)

- copy/export/import is a Hub/OS responsibility;
- the game does not receive an API to copy slots between apps;
- v1 validates ownership by `app_id` on import;
- conflict and corruption must be reflected through domain status and Hub UX.

### 8. Integration with host storage

- physical namespace isolated by `app_id`;
- physical per-slot representation is internal to the runtime/host;
- persistence should use an atomic strategy (temporary file + flush + platform-equivalent rename).

## Consequences

### Positive

- closes the `game` save contract without opening broad FS access;
- makes copy/export/import a system flow (Hub/OS), not a userland flow;
- standardizes slot integrity/versioning through `generation` + `checksum`.

### Costs

- requires per-slot staging/atomic commit implementation;
- requires explicit specification of the export/import format in Hub/OS;
- requires alignment with memcard and ABI specs.

## Required Follow-up

- agenda `013-game-memcard-slots-surface-and-semantics.md` should be considered closed and removed;
- `specs/08-save-memory-and-memcard.md` should absorb this contract (`32 x 32KB`, slots by `app_id`, atomic commit);
- `specs/16-host-abi-and-syscalls.md` and `specs/16a-syscall-policies.md` should absorb the surface and fault/status matrix.