Launch the JavaFX 2 project shell on Java 25 with an interactive viewport, managed Play lifecycle and project mutation guards. Preserve headless/MCP and save compatibility, and qualify exact runtime executable bundles. Separate unit JaCoCo gates from opt-in integration suites and use the internal Pong fixture for the headless visual pilot. Move maintenance and native conformance tools into tooling; retain the VS Code extension and update current navigation links. Validation: tooling make verify passed, including 1064 Studio unit tests, JaCoCo thresholds and 22 headless integration tests.
11 KiB
id, ticket, title, created, tags
| id | ticket | title | created | tags | |||||
|---|---|---|---|---|---|---|---|---|---|
| LSN-0099 | studio-memcard-persistence-integration | Explicit buffers and process-proven persistence | 2026-10-30 |
|
Original problem and ownership
Owner: Studio, with propagation to compiler/pbs and compiler/general. A native memcard ABI alone did not give a saved-source game a stable cartridge identity, an admitted bootstrap, usable byte storage or a supported installed-process route. The runtime already owned physical storage, admission, asynchronous publication, player choices and recovery. Reimplementing those policies in Studio would have created a second host rather than an integration.
Historical decision DEC-0083, including the explicitly approved MemcardBuffer revision D5a, was executed through PLN-0161 from AGD-0087. The normative results live in the linked specifications. The runtime provider independently delivered its public host extension; Studio then consumed that published contract. This lesson consolidates the completed work rather than changing its requirements.
Identity belongs in versioned source; media selection does not
prometeu.json carries an explicit integral uint32 app_id and optional integral
memcard_slots in 1..64. Slot declaration, capability, imports and exactly one
bootstrap role must form a coherent image. Invalid or partial configuration fails
before launch. Ordinary projects keep their existing flow.
New Studio projects persist their initial identity. A legacy project adopts its previous generated ID once, atomically, preserving unknown source JSON fields. Subsequent rename/version/language/stdlib changes do not regenerate it. Copying the manifest copies the game's identity; a distinct game needs a different ID. This prevents a routine upgrade from looking like a different save owner.
The image stays outside build output. Both Debug and headless default to
.studio/memcard.pmc; local .studio/setup.json may explicitly select another
memcardPath, including a shared external image. A per-session headless mount
may override it explicitly. Debug forwards the provider's --memcard option.
Neither launching nor a missing file implies permission to create or replace it.
The runtime creates, mounts, locks and reconciles media.
A byte buffer is a distinct source contract
Ordinary PBS arrays preserve vacant elements and optional reads using Array storage. Runtime mem byte transfers require concrete Array. Changing every array to satisfy one ABI would break ordinary language semantics.
sdk.mem therefore exports an opaque, origin-verified MemcardBuffer:
import {Mem, MemcardBuffer} from @sdk:mem;
let bytes = new MemcardBuffer(4);
bytes.write(0, 0);
bytes.write(1, 127);
bytes.write(2, 128);
bytes.write(3, 255);
Capacity is an int in 0..4096, fixed and initially zeroed. capacity(),
read(index) and write(index,value) use int; writes accept only 0..255.
Invalid capacity/index/value traps before mutation. Reference copies alias the
same native array, including function parameters and captured references.
Successful reads from a slot mutate the same buffer and preserve bytes outside
the returned range. No Struct wrapper, Dynamic boxing, adapter copy, runtime
BuiltinId or syscall was introduced. User spelling cannot forge the SDK origin.
The buffer serves both private slot payloads and public icons. A slot is logical save identity, not a buffer object. Presentation supplies public title, format version and icon; the runtime owns publication. No general serialization codec or implicit autosave is part of this integration.
Bootstrap is explicit data across the compiler boundary
PBS selects [MemcardBoot] on a unique canonical top-level nongeneric
(context: long) -> int function without captures. Imported/reexported references
to the same declaration do not create competing hooks. The target and its
dependencies are retention roots, published as nonzero FunctionId/Registry role 3.
The frontend requests a neutral host bootstrap through common lifecycle IR.
Common assembly emits mem.bootstrap@1 after all initializers and before the
first Frame, inside the once-per-boot guard. It does not inspect PBS marker names
or invoke the hook directly. The runtime owns admission and controlled-call fuel.
Pause/resume preserves the session rather than rerunning Init or bootstrap.
A bootstrap commit must not be busy-waited: registration is provisional until READY. The installed opt-in example instead submits in Frame, polls across frames, distinguishes terminal states and releases its retained result.
Status-first results must survive the facade
All fourteen operations retain the exact mem@1 imports, argument/result order
and capability. Numeric context/request/status/domain results are long, bootstrap
is int, flags are bool and bytes are MemcardBuffer. In particular,
slot_stat.has_payload is numeric 0/1, while dirty/info flags are bool.
On a domain failure, unused native result positions are Null. A conventional
typed wrapper RET validated those payload positions before the caller could
inspect status. The trusted SDK HostForward path therefore emits the exact host
call at the facade callsite, preserving positional/named evaluation and result
ordering without that intermediate RET. Check status before reading any payload.
The seven slot_stat results are source-grouped under stat.durable without
changing their flattened ABI slots.
Native request IDs are opaque; registration can already have used one. Query state, deadline reason, dirty RAM and worker activity are distinct observations. Only SUCCESS establishes durable success. MEMORY_ONLY is completion without a disk claim; INDETERMINATE is not a proven rollback. Releasing a retained result does not imply that outstanding IO relinquished its resources.
Published host controls preserve user decisions
Memcard use explicitly negotiates protocol 1.1 and capability memcard from the
configured installation. Ordinary projects retain 1.0 compatibility. Studio does
not infer support from runtimeVersion or invent flags or a second transport.
After a successful task build, an MCP boot can explicitly prepare/open media:
{"projectRoot":"/absolute/project","taskId":"current-task","buildId":"current-build","memcard":{"action":"open","access":"read_write"},"memcardChoice":"persistent"}
Omitted image path uses the local selection. Deliberate first creation is
action:create; open errors never trigger create or a RAM fallback.
memory_fresh and memory_existing are explicit alternative choices. Native
state, idle mount/unmount, same-card reconcile and continuation in memory are
projected through the existing supervised session; the runtime retains policy.
Reset/shutdown forward explicitly supplied discardUnsaved and
pendingWrites:wait/cancel. A native refusal becomes MEMCARD_ERROR with the
original operation/reason/state and keeps the process/channel/session usable.
The caller may inspect it and make a later explicit decision. An advance stopped
for media action becomes ACTION_REQUIRED with known progress, not session loss.
Human reclaim first attempts protected shutdown without discard consent. A refusal keeps manual mutation locked and shows native diagnostics. DEV offers a separately confirmed discard of remaining game RAM and cancellation of admitted writes before retrying cleanup. Canceling sends no consent. Stop, release, timeout and process death never imply that a publication did not happen.
Final qualification and reproducibility
Source/PBX tests, native production-host tests and installed-process tests answer different questions. A file remount between Firmware objects proves native behavior but does not qualify a client consuming a distributed executable.
The process gate builds actual PBS through the production compiler and Studio shipper. A writer observes native terminal commit SUCCESS and exits. Separate reader processes reopen the same image, check exactly 00 7f 80 ff in bootstrap, then render an observable oracle. The reachable reader entry/role call graph has no saving or presentation calls, its native request stays null, and the entire image remains byte-identical. A further reader upgrades app_version from 1 to 2 while retaining app_id 4294967295. Both PBS optimizer variants pass against runtime dev/release binary layouts and an independently extracted distribution.
The same gate proves explicit memory-only admission, missing-file open without creation, protected reset/shutdown refusal, deliberate discard, default-path create/unmount and structured recovery refusal outside a suspended session. Unit/MCP tests retain native state and full uint64 string IDs; actual JavaFX tests exercise canceled and accepted discard confirmation. Full regression and installed knowledge checks pass. Evidence and commands distinguish every route, including source hashes, profiles and binary/archive fingerprints.
Qualification consumed the existing provider delivery on baseline dcf6561, identified by exact per-file hashes. During finalization the provider independently committed it as a4bec5bc4577850543f57c79f5124ca00169e1b3; all recorded provider source hashes still match and its final working tree is clean. Studio performed no runtime source/configuration writes or commits. Qualification is on macOS arm64; physical power-cut, other platforms and the full reference-game Build/Play/UI/MCP deployment remain outside this capacity and belong to DSC-0086.
Pitfalls to avoid
- Regenerating app_id when version or title changes disconnects existing saves.
- Treating Array and concrete native byte arrays as interchangeable hides a real storage contract and breaks vacancy semantics.
- A typed facade may trap before a caller checks a failed native status.
- Native remounts, successful compilation or advance acknowledgements do not prove durable persistence through the installed process interface.
- A retained terminal result does not prove active IO; an IO timeout does not prove publication failed. Preserve the runtime's separate observations.
- Killing a process after a native shutdown refusal removes the opportunity for an explicit decision. Refusal must preserve the session; escalation after an actual transport failure must report uncertainty rather than durable failure.