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
@@ -0,0 +1,155 @@
---
id: LSN-0067
ticket: memcard-fixed-slots-v1
title: Save publication and resource ownership are separate
created: 2026-10-13
tags: [memcard, persistence, async-work, ownership, recovery]
---
## Context
The runtime now implements one installed shared memory-card image, per-game RAM
snapshots and asynchronous explicit publication. The image has 64 logical slots
of 64 KiB and 68 rotating physical blocks. Game identity and public presentation
live in a catalog; binary slot records carry mapping, generation, timestamp and
CRC32C. The runtime validates private payload integrity without interpreting its
meaning. A game's local slot index remains stable while physical blocks rotate.
The historical source was accepted decision DEC-0055, executed through PLN-0186
for AGD-0064. Those workflow artifacts are disposable; the normative references
are [Save Memory and MEMCARD](../../../docs/specs/runtime/08-save-memory-and-memcard.md),
[Registry](../../../docs/specs/runtime/02c-program-registry-and-pbx-v1.md),
[Host ABI](../../../docs/specs/runtime/16-host-abi-and-syscalls.md) and
[producer handoff](../../../docs/vm-arch/registry-producer-handoff.md).
## Publication knowledge and resource lifetime
A timeout describes the observer's knowledge. It does not prove that the host
stopped touching memory or storage. A request therefore has two independent
concerns: the retained result visible to the game, and ownership held until the
worker actually returns. Releasing a result or ending a game cannot release a
snapshot source still in use. Conversely, a completed retained result must not
keep the lane occupied or prevent session teardown.
The implementation protects only the committing slot from writes and clear;
reads and other slots remain available. It retains one full-slot scratch buffer
instead of copying the whole snapshot for each save. Request context, mount
epoch and session identity prevent a late completion from updating a replacement
session. Regression coverage includes ending a session with an unconsumed,
already completed result, which exposed an ownership leak during integration.
Cancellation and entry into publication share an atomic control state. At the
deadline, a canceled attempt that never entered publication can report failure.
Once publication may have started, the result remains indeterminate until
reconciliation. A blocked host requires restart escalation even when publication
was provably prevented: storage and source ownership still have to remain valid.
The runtime neither kills the thread nor starts a replacement worker over its
resources. The watchdog runs outside that worker.
## A checksum does not make an old reference safe
Two valid map pages can reference different generations of payload and public
catalog data. The allocator protects the union of references from all usable
maps. It durably retires an old map before overwriting any block or public copy
that only that map protects. Otherwise recovery could select a valid old map
whose referenced bytes were already replaced.
Each candidate is coherent only after its referenced catalog, icons and payload
checksums validate. Recovery may select an older coherent map and reports that
fact. Unknown administrative damage blocks further writes until explicit
verification. Known quarantined blocks remain excluded; revalidation does not
silently reintegrate them. Same-card replacement carries known exclusions and
the attempted publication map so it can reconcile sequence, identity and slot
descriptors without overwriting the game's RAM snapshot.
The file backend allocates the entire image, including unused slot and public
regions, before namespace publication. Creating a sparse file of the right length
would postpone capacity failure until gameplay. Creation also refuses to replace
an existing file. Legacy save files remain untouched.
## Priority requires bounded work from every consumer
A highest-priority queue entry cannot preempt an arbitrary blocking asset job.
The production asset manager therefore uses bounded resumable decoding steps on
the same lane as saves, including preload. Glyph, sound and scene jobs retain
their progress and resume after the save; completed payloads are installed only
under the current asset generation. A second production asset worker would have
defeated the intended hardware budget.
Preload required special attention because it previously bypassed the ordinary
asynchronous path. Headless boot now waits for actual work progress while polling
deadlines; it does not impose artificial frame pacing. The resulting scheduling
contract is described in
[Coroutines and Cooperative Scheduling](../../../docs/specs/runtime/09a-coroutines-and-cooperative-scheduling.md).
## Bootstrap belongs at an explicit runtime boundary
The cartridge declares capability and requested slot count; Registry role 3 binds
the optional memcard bootstrap callable. An explicit producer boundary runs it
after producer initialization and before the first frame. The runtime preserves
the main continuation and applies a separate bounded call budget, without
learning frontend concepts such as Init or Frame roles.
Snapshot and preload preparation precede the hook. New registration stays
provisional until the hook reports readiness. A save requested during bootstrap
waits for registration publication rather than publishing payload under an
unregistered owner. Typed executable fixtures exercise this ordering, the
Array<Int32> byte carrier and once-only invocation.
Debugger stepping must use the same live memcard and session services as normal
execution. A temporary service created only for stepping would invalidate
context handles and make otherwise correct bytecode fail under a debugger.
Both execution paths are covered by the firmware integration fixture.
The general controlled-call design builds on
[lifecycle continuation ownership](../DSC-0062-guest-lifecycle-pause-and-resume-api/LSN-0066-lifecycle-calls-retain-the-game-continuation.md).
Save timestamps use the host's civil clock; ordering and timeouts use independent
mechanisms, as explained in
[civil time and elapsed time](../DSC-0063-host-clock-interface-for-runtime-utc-timestamps/LSN-0065-civil-time-is-not-ordering-or-elapsed-time.md).
## Player choice and opaque data
Memory-only mode uses the same RAM snapshot operations and reports its lack of
persistence explicitly. It can load an existing readable save or start clean,
including when persistent allocation cannot grow. No temporary disk save or
automatic upload hides behind that choice.
Removal and replacement preserve local edits. Same-card reinsertion reconciles
without reloading RAM; a different card requires explicit keep-local or
load-existing policy. SO replacement APIs require suspended gameplay. Unsaved
exit confirmation and the removal/restart dialogs use the existing lifecycle;
neither initialization nor bootstrap reruns on resume. External administration
removes a whole game, while a game's clear operation retains slot ownership.
The full external save-management application remains outside this delivery.
## Validation and limits
The tests cover image/schema bounds, CRC vectors, full-pool rotation, clean
reassignment, catalog growth/removal, quarantine and reintegration. Fault storage
separates volatile and durable bytes and injects commit/catalog failures,
including synchronization that persists bytes before returning an error. Other
tests cover a blocked host before and during publication, source protection,
retained results, RAM-only admission, card replacement and typed guest bootstrap.
Real file tests verify complete allocation, reopening, read-only access and
non-replacement of existing files. These are deterministic software checks,
not physical power-cut qualification.
A local debug-build measurement ran 20 full 64 KiB commits while a production
512x512 glyph asset load was active:
| Measurement | p50 | p95 | Maximum |
| --- | ---: | ---: | ---: |
| Admission to first IO | 0.049 ms | 0.071 ms | 0.139 ms |
| Commit completion | 11.379 ms | 24.428 ms | 29.839 ms |
These samples met the start and healthy-completion targets on the exercised local
file host. They do not establish handheld device tail latency or physical storage
durability. Each host backend and storage device needs its own qualification;
the implemented fallback for a host that cannot stop safely is resource retention
and explicit restart escalation.
Workspace regression includes all targets and features, formatting, clippy and
architecture checks. The five desktop debugger socket tests also pass when local
socket binding is allowed. The external compiler and raw-flash backend were not
part of this implementation; the producer handoff documents their integration
boundary without an external artifact compatibility layer.