feat(runtime): implement shared transactional memcard with async saves
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
This commit is contained in:
+155
@@ -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.
|
||||
Reference in New Issue
Block a user