prometeu-runtime/docs/runtime/specs/08-save-memory-and-memcard.md

Save Memory and MEMCARD

Domain: virtual hardware: save memory Function: normative

Didactic companion: ../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