Files
prometeu-studio/discussion/lessons/DSC-0085-studio-memcard-persistence-integration/LSN-0099-explicit-buffers-and-process-proven-persistence.md
T
bquarkz 71fb80efc3
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/head There was a failure building this commit
feat(studio): ship JavaFX 2 Play and delegate integration tooling
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.
2026-11-19 17:32:03 +00:00

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
studio
compiler
pbs
memcard
runtime-integration

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.

References