implements memcard

This commit is contained in:
2026-03-24 13:40:51 +00:00
parent f714db77fc
commit 27d26b328b
20 changed files with 959 additions and 108 deletions
@@ -116,7 +116,7 @@ No perfil `app` (`home` sandbox), esta agenda passa a ser a fonte normativa para
## Fora de Escopo
- slots de memcard para `game` (fechado na decisao `011`);
- slots de memcard para `game` (fechado na `spec 08`);
- acesso cross-app;
- sync remoto/cloud;
- DB embutido como contrato de plataforma.
+3 -3
View File
@@ -32,9 +32,9 @@ Justificativa curta:
- `011` foi fechada pela decisao `006`.
- `012` e o primeiro consumidor da base stateful VM-owned fechada em `006`.
- `013` foi fechada pela decisao `011` (memcard `32 x 32KB`, ownership, identidade e copia fora do jogo).
- `013` foi fechada e absorvida por `spec 08` (historico em `learn/011`).
- `014` fecha o contrato de `home` para apps sem abrir FS global.
- a decisao `007` fixa o nucleo de fault policy de `fs`; os detalhes ficam distribuidos entre decisao `011` (`game`) e agenda `014` (`app`).
- a decisao `007` fixa o nucleo de fault policy de `fs`; os detalhes ficam distribuidos entre `spec 08` (`game`) e agenda `014` (`app`).
- a decisao `008` fixa o contrato status-first de `gfx`.
- a decisao `009` fixa o contrato status-first de `audio`.
- a decisao `010` fixa o contrato status-first de `asset`.
@@ -48,7 +48,7 @@ Dependências principais:
- `014` depende das decisoes `003`/`007`, de `16a`, de `12` (Hub/OS) e de `13` (`app_mode`)
- `007` depende da estabilizacao minima das agendas de superficie/fault por dominio
- `008` depende de contrato fechado de `13-cartridge.md` + comportamento equivalente ao loader de diretorio
- `009` depende da decisao `003`, de `16a` e da decisao `006`, e deve alinhar com decisao `011`/agenda `014` quando usar `fs`
- `009` depende da decisao `003`, de `16a` e da decisao `006`, e deve alinhar com `spec 08`/agenda `014` quando usar `fs`
- `010` depende de `16a` e da `009`
Regra de uso:
@@ -142,7 +142,7 @@ Para suportar este protocolo, a VM precisa expor API canonica para:
As seguintes agendas devem consumir esta decisao:
- `011-game-memcard-slots-surface-and-semantics.md` (decisao que absorveu a agenda `013`)
- `spec 08-save-memory-and-memcard.md` (historico arquitetural em `learn/011`)
- `014-app-home-filesystem-surface-and-semantics.md`
- discussoes futuras de data bank
@@ -10,7 +10,7 @@ A agenda `003-filesystem-fault-semantics.md` existia para fechar fault semantics
Com o split de `fs` em:
- decisao `011` (`game` memcard slots);
- `spec 08` (`game` memcard slots);
- agenda `014` (`app` home sandbox);
ficou claro que:
@@ -66,7 +66,7 @@ Se o dominio nao conseguir concluir a escrita segundo seu contrato de atomicidad
- retorna `status` de falha;
- nao mascara o resultado como sucesso.
### 6. Responsabilidade por perfil (movida para decisao `011` e agenda `014`)
### 6. Responsabilidade por perfil (movida para `spec 08` e agenda `014`)
Fica sob responsabilidade das agendas de superficie:
@@ -89,10 +89,10 @@ A agenda `003-filesystem-fault-semantics.md` e considerada absorvida e removida.
### Custos
- exige disciplina para manter a matriz de faults distribuida em duas agendas;
- exige revisao de consistencia entre decisao `011` e agenda `014` antes de PR final de implementacao.
- exige revisao de consistencia entre `spec 08` e agenda `014` antes de PR final de implementacao.
## Follow-up Obrigatorio
- `011-game-memcard-slots-surface-and-semantics.md` fecha a matriz de fault/status do perfil `game`;
- `spec 08-save-memory-and-memcard.md` fecha a matriz de fault/status do perfil `game`;
- `014-app-home-filesystem-surface-and-semantics.md` deve incluir a matriz de fault/status do perfil `app`;
- specs `16`/`16a` devem absorver esta decisao quando o contrato estiver implementado e estavel.
+3 -1
View File
@@ -19,7 +19,6 @@ Decisoes ativas:
- `003-vm-owned-byte-transfer-protocol.md`
- `006-vm-owned-stateful-core-contract.md`
- `007-filesystem-fault-core-policy.md`
- `011-game-memcard-slots-surface-and-semantics.md`
Decisoes implementadas e aposentadas (migradas para `learn/`):
@@ -32,6 +31,9 @@ Decisoes implementadas e aposentadas (migradas para `learn/`):
- `010-asset-status-first-fault-and-return-contract.md`
- spec: `../specs/15-asset-management.md`
- impl: `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`, `crates/console/prometeu-hal/src/syscalls/domains/asset.rs`, `crates/console/prometeu-hal/src/asset_bridge.rs`, `crates/console/prometeu-drivers/src/asset.rs`
- `011-game-memcard-slots-surface-and-semantics.md`
- spec: `../specs/08-save-memory-and-memcard.md`, `../specs/16-host-abi-and-syscalls.md`, `../specs/16a-syscall-policies.md`
- impl: `crates/console/prometeu-system/src/services/memcard.rs`, `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`, `crates/console/prometeu-hal/src/syscalls/domains/fs.rs`
Decisoes aposentadas que ja viraram spec:
+1
View File
@@ -24,6 +24,7 @@ Ela existe para explicar o modelo mental da fantasy handheld, suas influências,
- [`008-gfx-status-first-fault-and-return-contract.md`](008-gfx-status-first-fault-and-return-contract.md)
- [`009-audio-status-first-fault-and-return-contract.md`](009-audio-status-first-fault-and-return-contract.md)
- [`010-asset-status-first-fault-and-return-contract.md`](010-asset-status-first-fault-and-return-contract.md)
- [`011-game-memcard-slots-surface-and-semantics.md`](011-game-memcard-slots-surface-and-semantics.md)
## Rules
@@ -1,149 +1,140 @@
# Save Memory and MEMCARD
Domain: virtual hardware: save memory
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.
This chapter defines the `game` persistence surface in PROMETEU.
The MEMCARD contract is:
MEMCARD is a runtime-owned service layered on top of the runtime filesystem.
- 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.
Games do not get broad path-based filesystem access for saves. They use slot operations only.
Current model:
## 2 Profile Contract (`game`)
- Slot A is the required primary save device;
- additional slots remain future-facing surface.
The v1 contract is fixed:
Each slot corresponds to a host file such as:
- `32` slots per game (`slot_index: 0..31`);
- each slot has up to `32KB` payload;
- ownership is isolated by `app_id`;
- persistence is explicit through `slot_commit`;
- copy/export/import is a Hub/OS responsibility (outside game userland).
```
MyGame_A.mem
MyGame_B.mem
```
## 3 Slot Identity and Metadata
The runtime mounts this file as a **persistent storage device**.
Each slot has runtime-owned metadata:
## 2 Capacity and CAP
- `app_id` owner;
- `slot_index`;
- `save_uuid`;
- `generation`;
- `checksum`;
- `payload_size`;
- `state`.
The size of the MEMCARD is **fixed**, defined by the execution profile (CAP).
State values:
### 2.1 Suggested sizes
- `0 = EMPTY`
- `1 = STAGED`
- `2 = COMMITTED`
- `3 = CORRUPT`
| Profile | Size |
`generation` and `checksum` are not manually controlled by game code:
- `generation` increments on successful `slot_commit`;
- `checksum` is recalculated by runtime for committed payload integrity.
## 4 Host ABI Surface (v1)
Canonical module: `mem` (version `1`).
| Operation | Signature |
| --- | --- |
| JAM | 8 KB |
| STANDARD | 32 KB |
| ADVANCED | 128 KB |
| `slot_count` | `mem.slot_count() -> (status:int, count:int)` |
| `slot_stat` | `mem.slot_stat(slot:int) -> (status:int, state:int, used_bytes:int, generation:int, checksum:int)` |
| `slot_read` | `mem.slot_read(slot:int, offset:int, max_bytes:int) -> (status:int, payload_hex:string, bytes_read:int)` |
| `slot_write` | `mem.slot_write(slot:int, offset:int, payload_hex:string) -> (status:int, bytes_written:int)` |
| `slot_commit` | `mem.slot_commit(slot:int) -> status:int` |
| `slot_clear` | `mem.slot_clear(slot:int) -> status:int` |
The game **cannot exceed** this size.
`status` is always the first return slot.
Attempts to write above the limit result in an error.
### 4.1 Byte transport note (v1)
## 3 Peripheral API (v0.1)
Current ABI transport for memcard payload is `payload_hex:string`.
### 3.1 Logical Interface
This is a temporary transport form until VM-owned bytes (`HeapRef<Bytes>`) is exposed in the host ABI path.
The MEMCARD exposes a **simple single-blob API**:
## 5 Operation Semantics
```
mem.read_all() -> byte[]
mem.write_all(byte[])
mem.commit()
mem.clear()
mem.size() -> int
```
### `slot_count`
### 3.2 Operation Semantics
- returns slot capacity visible to game profile (`32`);
- does not depend on slot content.
#### `read_all()`
### `slot_stat`
- Returns all persisted content
- If the card is empty, returns a zeroed buffer
- Cycle cost proportional to size
- returns current state and integrity/version metadata for one slot.
#### `write_all(bytes)`
### `slot_read`
- Writes the buffer **to temporary memory**
- Does not persist immediately
- Fails if `bytes.length > mem.size()`
- reads from staged content when present, otherwise committed content;
- returns empty payload with success when offset is beyond current payload end.
#### `commit()`
### `slot_write`
- Persists data to the device
- **Mandatory** operation
- Simulates hardware flush
- May fail (e.g., I/O, simulated corruption)
- writes into slot staging buffer (does not persist directly);
- supports offset writes;
- does not allow resulting payload above `32KB`.
#### `clear()`
### `slot_commit`
- Zeroes the card content
- Requires `commit()` to persist
- persists staged payload for one slot;
- commit is atomic at slot operation level (all-or-error, no silent partial success).
#### `size()`
### `slot_clear`
- Returns total card capacity in bytes
- clears staged content and removes committed slot payload.
## 4 Explicit Commit Rule
## 6 Status Codes (Domain-Owned)
PROMETEU **does not save automatically**.
Minimum status catalog:
Without `commit()`:
- `0 = OK`
- `1 = EMPTY`
- `2 = NOT_FOUND`
- `3 = NO_SPACE`
- `4 = ACCESS_DENIED`
- `5 = CORRUPT`
- `6 = CONFLICT`
- `7 = UNAVAILABLE`
- `8 = INVALID_STATE`
- data remains volatile
- can be lost upon exiting the game
- simulates abrupt hardware shutdown
## 7 Fault Classification
## 5 Execution Cost (Cycles)
MEMCARD follows `16a`:
All MEMCARD operations have an explicit cost.
- `Trap`: structural violations (invalid slot index, invalid call shape, invalid window value type/range);
- `status`: operational domain conditions;
- `Panic`: runtime invariant break only.
### 5.1 Example (illustrative values)
Silent no-op is forbidden for operations with operational failure paths.
| Operation | Cost |
| --- | --- |
| read_all | 1 cycle / 256 bytes |
| write_all | 1 cycle / 256 bytes |
| commit | fixed + proportional cost |
## 8 Runtime Layering and Storage Mapping
These costs appear:
MEMCARD is a domain layer over runtime FS.
- in the profiler
- in the frame timeline
- in the CAP report
Runtime host mapping for v1 is namespace-isolated by `app_id`, for example:
## 6 `.mem` File Format
`/user/games/<app_id>/memcard/slot_<NN>.pmem`
The MEMCARD file has a simple and robust format.
The exact host-side file naming is internal to runtime/host as long as ownership and isolation guarantees are preserved.
### 6.1 Header
## 9 Explicit Persistence Rule
| Field | Size |
| --- | --- |
| Magic (`PMEM`) | 4 bytes |
| Version | 1 byte |
| Cart ID | 8 bytes |
| Payload Size | 4 bytes |
| CRC32 | 4 bytes |
PROMETEU does not auto-save slot staging data.
### 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
Without `slot_commit`, writes remain staged and are not guaranteed as persisted committed state.]
@@ -156,6 +156,22 @@ Return shape must also follow the operational policy in [`16a-syscall-policies.m
- operations with no real operational error path may remain `void` (`ret_slots = 0`);
- stack shape remains strict in both cases and must match syscall metadata exactly.
### MEMCARD game surface (`mem`, v1)
The game memcard profile uses module `mem` with status-first return shapes.
`mem` is a domain layer backed by runtime `fs` (it is not a separate storage backend).
Canonical operations in v1 are:
- `mem.slot_count() -> (status, count)`
- `mem.slot_stat(slot) -> (status, state, used_bytes, generation, checksum)`
- `mem.slot_read(slot, offset, max_bytes) -> (status, payload_hex, bytes_read)`
- `mem.slot_write(slot, offset, payload_hex) -> (status, bytes_written)`
- `mem.slot_commit(slot) -> status`
- `mem.slot_clear(slot) -> status`
Semantics and domain status catalog are defined by [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md).
## 7 Syscalls as Callable Entities (Not First-Class)
Syscalls behave like call sites, not like first-class guest values.
+5 -1
View File
@@ -66,12 +66,16 @@ Example groups:
- `gfx`
- `audio`
- `asset`
- `memcard`
- `fs` (includes game memcard module `mem` in v1)
Capability checks exist to constrain which host-managed surfaces a cartridge may use.
Input in v1 is VM-owned intrinsic surface and is not capability-gated through syscall policy.
Game memcard operations (`mem.*`) are status-first and use `fs` capability in v1.
`mem` remains layered on runtime `fs`; no parallel persistence channel is introduced.
Domain surface, status catalog and slot semantics are defined in [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md).
## 3 Interaction with the Garbage Collector
The VM heap and host-managed memory are separate.