# Save Memory and MEMCARD

Domain: virtual hardware: save memory
Function: normative

Didactic companion: [`../learn/save-memory-and-memcard.md`](../learn/save-memory-and-memcard.md)

## 1 Scope

This chapter defines the runtime-facing persistent save surface of PROMETEU.

The MEMCARD contract is:

- explicit persistence controlled by the game;
- fixed capacity determined by profile;
- host-backed slot storage;
- mandatory `commit()` to persist writes;
- explicit cost and integrity metadata.

Current model:

- Slot A is the required primary save device;
- additional slots remain future-facing surface.

Each slot corresponds to a host file such as:

```
MyGame_A.mem
MyGame_B.mem
```

The runtime mounts this file as a **persistent storage device**.

## 2 Capacity and CAP

The size of the MEMCARD is **fixed**, defined by the execution profile (CAP).

### 2.1 Suggested sizes

| Profile | Size |
| --- | --- |
| JAM | 8 KB |
| STANDARD | 32 KB |
| ADVANCED | 128 KB |

The game **cannot exceed** this size.

Attempts to write above the limit result in an error.

## 3 Peripheral API (v0.1)

### 3.1 Logical Interface

The MEMCARD exposes a **simple single-blob API**:

```
mem.read_all()   -> byte[]
mem.write_all(byte[])
mem.commit()
mem.clear()
mem.size()       -> int
```

### 3.2 Operation Semantics

#### `read_all()`

- Returns all persisted content
- If the card is empty, returns a zeroed buffer
- Cycle cost proportional to size

#### `write_all(bytes)`

- Writes the buffer **to temporary memory**
- Does not persist immediately
- Fails if `bytes.length > mem.size()`

#### `commit()`

- Persists data to the device
- **Mandatory** operation
- Simulates hardware flush
- May fail (e.g., I/O, simulated corruption)

#### `clear()`

- Zeroes the card content
- Requires `commit()` to persist

#### `size()`

- Returns total card capacity in bytes

## 4 Explicit Commit Rule

PROMETEU **does not save automatically**.

Without `commit()`:

- data remains volatile
- can be lost upon exiting the game
- simulates abrupt hardware shutdown

## 5 Execution Cost (Cycles)

All MEMCARD operations have an explicit cost.

### 5.1 Example (illustrative values)

| Operation | Cost |
| --- | --- |
| read_all | 1 cycle / 256 bytes |
| write_all | 1 cycle / 256 bytes |
| commit | fixed + proportional cost |

These costs appear:

- in the profiler
- in the frame timeline
- in the CAP report

## 6 `.mem` File Format

The MEMCARD file has a simple and robust format.

### 6.1 Header

| Field | Size |
| --- | --- |
| Magic (`PMEM`) | 4 bytes |
| Version | 1 byte |
| Cart ID | 8 bytes |
| Payload Size | 4 bytes |
| CRC32 | 4 bytes |

### 6.2 Payload

- Binary buffer defined by the game
- Fixed size
- Content interpreted only by the game

## 7 Integrity and Security

- CRC validates corruption
- Cart ID prevents using wrong save
- Version allows future format evolution
- Runtime can:
    - warn of corruption
    - allow card reset