feat(runtime): implement shared transactional memcard with async saves
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-10-13 15:24:01 +01:00
parent 0af8b2b1fe
commit 6c2a07e579
65 changed files with 6222 additions and 985 deletions
+37 -10
View File
@@ -17,7 +17,8 @@ reference boundaries. The separate render frame scheduler remains active.
Fn values, frame-owned capture environments, typed indirect calls and receiver-first
trait dispatch use [the function-value contract](../specs/runtime/02b-vm-function-values-and-closures.md).
FRAME_SYNC resumes next PC; successful root RET permits recurring entry preparation.
New strings/bytes/save APIs, long-run stress and representative-game headroom require
The memcard byte carrier and bootstrap use the [save-memory contract](../specs/runtime/08-save-memory-and-memcard.md).
General string/byte APIs, long-run stress and representative-game headroom require
separate technical contracts and workloads.
The external Studio handoff targets are the build-pipeline
@@ -38,7 +39,7 @@ fallback. Use the canonical chapter's field order and UTF-8 rules, not Rust layo
TypeId, FunctionId and ImplementationId are independent image-local table indices;
zero is valid. BuiltinIds are imports, not local TypeIds. Function records contain
optional name, ordered named parameters, ordered result TypeIds, code offset/length,
a lifecycle-role byte followed by optional name, ordered named parameters, ordered result TypeIds, code offset/length,
extra local slots and maximum temporary slots. Names are independent of debug.
Widths are derived from TypeIds; serialize no parameter/result width caches.
`max_stack_slots = 0` is a literal zero limit. Boot authority remains FunctionId 0.
@@ -55,22 +56,48 @@ module/name/version and exact ABI counts; every declaration must be used. Loadin
binds it to SYSCALL after capability/ABI validation. Raw SYSCALL in producer PBX,
unknown declarations, invalid indices and unused declarations are rejected.
## Memcard and controlled-call lowering
Emit role 0 for ordinary functions, role 1 for optional BeforePause and role 2
for optional BeforeResume. Both lifecycle hooks have no parameters, results or
captures. A memcard-enabled cartridge declares capability `memcard`, a manifest
`memcard_slots` count in 1..64, and exactly one role 3 function with signature
`(Int64 context) -> Int32`, no captures, and a FunctionId different from zero.
The compiler chooses source-level spelling; the runtime binds only the role.
After frontend-owned initialization and before the first frame, emit the declared
`mem.bootstrap` HOSTCALL (0 arguments, 1 Int32 result). The runtime invokes role 3
on the same VM, then resumes the producer continuation after READY and coherent
registration. The producer must not directly call the role as a substitute for
this gate. Use 0 READY or 1 INCONSISTENT, with bounded `mem.diagnostic` text when
needed. This function executes once per boot with controlled-call fuel, outside
frame accounting; Init and Frame remain frontend concepts.
Declare the exact [mem ABI](../specs/runtime/08-save-memory-and-memcard.md#guest-abi).
Use concrete `Array<Int32>` storage for bytes 0..255, transfer at most 4096 bytes
per call, and preserve the session context for subsequent calls. The array's
storage charge is four bytes per element. Save requests return an opaque ID;
query reports durable success/failure/indeterminate or memory-only completion,
and explicit release frees the retained result. Hooks may submit/query; they
must not busy-wait for disk. Initial commits are held until READY so registration
and payload publication cannot deadlock each other.
## Independent binary oracles
The manually specified minimal executable in
`crates/console/prometeu-bytecode/tests/registry_v1.rs::minimal_bytes` is 193 bytes.
`crates/console/prometeu-bytecode/tests/registry_v1.rs::minimal_bytes` is 194 bytes.
Its directory begins at 32; eight entries end at 128:
| Kind | Offset | Length | Payload |
| --- | ---: | ---: | --- |
| constants | 128 | 4 | count 0 |
| functions | 132 | 29 | one unnamed zero-parameter/result function, offset 0, length 2, locals/max 0 |
| code | 161 | 2 | `01 00` (HALT) |
| exports | 163 | 4 | count 0 |
| syscalls | 167 | 4 | count 0 |
| types | 171 | 10 | one unnamed Bool import, BuiltinId `0x0013` |
| implementations | 181 | 4 | count 0 |
| captures | 185 | 8 | function count 1; empty environment |
| functions | 132 | 30 | role 0, one unnamed zero-parameter/result function, offset 0, length 2, locals/max 0 |
| code | 162 | 2 | `01 00` (HALT) |
| exports | 164 | 4 | count 0 |
| syscalls | 168 | 4 | count 0 |
| types | 172 | 10 | one unnamed Bool import, BuiltinId `0x0013` |
| implementations | 182 | 4 | count 0 |
| captures | 186 | 8 | function count 1; empty environment |
The independent multi-slot fixture in the same suite declares `fn(vec2)->vec2`
with TypeId 0, no serialized widths, no extra locals and max 2. Its fourteen code