feat(host): expose memcard controls and qualify process persistence
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good

This commit is contained in:
2026-10-30 10:10:07 +00:00
parent dcf6561ea7
commit a4bec5bc45
42 changed files with 4778 additions and 100 deletions
@@ -328,6 +328,40 @@ ordinary storage failures are domain results.
## Host integration
### Public host controls
The installed headless interface is the negotiated memcard surface of
[Headless Automation](11a-headless-automation-protocol.md#memcard-controls).
Media selection belongs to the host instance, never the cartridge manifest.
Opening, creation and the three boot choices are explicit. Missing, corrupt,
inaccessible or read-only media never silently select fresh RAM or create a file.
File hosts acquire a nonblocking exclusive OS lock, including for read-only
access, before validating the opened image. The lock follows file identity and
therefore covers aliases across desktop/headless processes. Contention is BUSY;
unsupported locking is an explicit refusal. Creation locks the new file before
publishing its name and never replaces an existing destination. Locks and native
buffers remain owned until actual IO cessation, independently of result release,
discard consent and timeout. Inspection through a second mounted reader is not
supported while an owner holds the image.
Native observation distinguishes dirty RAM, retained terminal results and actual
IO ownership. Reset/shutdown wait for admitted IO, or request cancellation when
explicitly selected, then reevaluate dirty RAM. Remaining dirty RAM requires
explicit discard consent; refusal preserves the resident session. Neither wait,
cancel nor discard starts a save or proves rollback. Unconfirmed cessation blocks
reset/closure confirmation and requires restart supervision. EOF/transport loss
attempts bounded cancellation/cleanup without saving or resuming the guest.
An installed image with an indeterminate publication remains write-blocked after
reset; another persistent admission requires explicit revalidation first.
The headless owner polls IO/deadlines while idle without advancing VM instructions,
input, ticks or frames. A resident game awaiting media action is paused, not
terminated. Explicit reconciliation reopens only the selected card identity after
safe cessation, preserves RAM/continuation and the original retained request
result, and never reruns bootstrap. Different-card switching is not part of this
public host surface.
The desktop host accepts `--memcard PATH` for an existing image and
`--memcard PATH --create-memcard` for explicit creation. Creation never replaces
an existing file. File creation, opening, mount validation and save IO execute
@@ -30,7 +30,7 @@ and may terminate the process tree. There is no transport replay or durable queu
## Handshake and compatibility
The server first emits a `hello` object with `sessionId`, `protocolVersion`
(`major: 1, minor: 0`), real `runtimeVersion`, `capabilities` and `limits`.
(`major: 1, minor: 1`), real `runtimeVersion`, `capabilities` and `limits`.
Session identity is opaque and process-local, excluded from deterministic oracles.
Before work, the client sends `initialize` with `protocolVersion` and an array
@@ -130,6 +130,8 @@ if the process dies. The final response is authoritative when delivered.
Shutdown/EOF requests cancellation, waits for the active work to reach its boundary,
drops the host and exits; explicit shutdown receives its response after cleanup.
Negotiated memcard shutdown may refuse with native state and keep the channel
available, as specified in [Memcard controls](#memcard-controls).
Disconnect never starts/resumes execution. A failed process requires a new explicit
session, not replay. Host session loss does not implicitly release Studio authority.
@@ -175,6 +177,106 @@ structured faults, progress on partial failure and retained desktop run/debug.
Neither Studio UI nor an AI model is required. See `tests/automation_process.rs`
in prometeu-cli and the in-process deterministic-control tests in the headless crate.
## Memcard controls
Protocol minor 1.1 adds capability `memcard`. Initialize negotiates the lesser
minor. These commands and parameters require minor >= 1 and `memcard` in
requiredCapabilities; unsupported use fails before mutation. Clients negotiating
1.0 keep the previous command/result shapes. No executable-version inference,
default image, alternate transport or headless media startup flags are defined.
| Command | Parameters | Meaning |
| --- | --- | --- |
| memcard_mount | path, action: open/create, access: read_write/read_only | prepare explicit media before boot; bounded result |
| memcard_unmount | empty object | release idle media outside a resident session |
| get_memcard_state | empty object | coherent native observation, without guest execution |
| boot | path, optional memcardChoice: persistent/memory_fresh/memory_existing | explicit player choice required for a memcard cartridge |
| memcard_reconcile | empty object | recover selected same-card identity while suspended |
| memcard_continue_in_memory | empty object | explicit safe SO detach, preserving RAM |
| reset / shutdown | optional discardUnsaved (false), pendingWrites: wait/cancel (wait) | controlled teardown; no autosave |
Mount requires no resident game or outstanding IO. Create/read_only is invalid.
Paths are resolved relative to process cwd, reported absolutely; parent directories
must exist. Open does not create; create never replaces, converts or repairs media.
Persistent requires writable coherent media; memory_existing requires a readable
record for the cartridge appId. No error changes that choice automatically.
After an admitted boot attempt, retry requires explicit reset; parsing and
negotiation failures do not admit boot. Reset preserves selected media/lock.
State has closed objects `media`, `session`, `io`, `recovery`, a nullable `request`,
`dirty` and `dirtySlots`. Media reports path/cardId/access/preparation/error/health;
session reports identity/choice/mode/boot phase/residency/action requirement.
Requests report original identity, operation, local slot, state, deadline reason,
storage error and retention, independently of IO activity. cardId is 32 lowercase
hex digits; request IDs and mount epochs are decimal strings. Unknown values are
null, never invented outcomes. Schemas distributed with the installation specify
all fields. Inspection never releases requests or exposes private save payloads.
Domain failures use `memcard_error` with `details.operation`, `details.reason`
and `details.state`. Reasons include choice_required, unavailable, corrupt,
unsupported, read_only, access_denied, already_exists, busy, no_space,
out_of_memory, invalid_state, invalid_range, counter_exhausted, identity_mismatch,
unsaved_changes, indeterminate and restart_required. Human messages are not codes.
Original worker error, deadline cause and durable result are separate observations.
Shutdown stops an active advance at its existing frame boundary, then evaluates
IO and dirty RAM. Wait/cancel only concern already admitted work. After IO ceases,
remaining dirty RAM without discard consent returns unsaved_changes and leaves
the session/channel usable. Terminal results retained by the guest alone do not
block closure. Unconfirmed IO cessation never returns closed:true or permits
resource/lock release. Successful negotiated reset adds `memcard` to the state
result; shutdown returns closed:true and its final `memcard` snapshot, after checked
cleanup. EOF/output loss attempts bounded cancellation without save/resumption;
process death does not establish publication outcome.
An advance stopped for resident media action returns stop:action_required with
known completed progress. Resident state is paused; a host dialog is not counted
as a game frame. Idle IO polling leaves guest counters/input unchanged. Reconcile
accepts no replacement path, validates expected identity before changes, preserves
RAM/continuation/original retained results and does not rerun initialization.
Runtime qualification uses neutral PBX/ABI fixtures, real distinct processes and
an isolated extracted distribution. It proves SUCCESS, termination, exact readback
without resave and stable appId across cartridge versions. Consumer source-language
compilation and client adaptation are separate work; the provider has no frontend
build dependency. No global installation or consumer configuration update is needed.
### Integration sequence
Start `prometeu headless --stdio` from the selected installation and consume its
hello before sending work. Require the capability explicitly:
```json
{"requestId":"init","command":"initialize","params":{"protocolVersion":{"major":1,"minor":1},"requiredCapabilities":["memcard"]}}
{"requestId":"media","command":"memcard_mount","params":{"path":"/absolute/save.pmc","action":"open","access":"read_write"}}
{"requestId":"boot","command":"boot","params":{"path":"/absolute/cartridge","memcardChoice":"persistent"}}
{"requestId":"step","command":"advance","params":{"frames":1}}
{"requestId":"save-state","command":"get_memcard_state","params":{}}
{"requestId":"close","command":"shutdown","params":{"pendingWrites":"wait"}}
```
Each request above follows the successful response to the preceding one. Creating
new media requires a deliberate `action:create`; do not retry an open failure
with create. Memory choices are `memory_fresh` and `memory_existing`. No client
may replace a failed persistent choice with either automatically.
If closure reports unsaved_changes, keep the process/session and expose that
native state to the caller. A later explicit choice may send
`{"discardUnsaved":true,"pendingWrites":"cancel"}`; do not infer that consent
from a UI stop, timeout or process error. A successful commit is the guest/native
request state `success`, independently of its reason; neither an advance response
nor closed:true proves that a save occurred.
On reopening, launch a different process, open the same image and choose the
appropriate mode explicitly. The neutral process oracle verifies exact prior
bytes without resaving and repeats with a changed cartridge version and unchanged
appId. Run `cargo test -p prometeu-cli --test automation_process
memcard_public_distinct_process_save_readback_and_version_identity`; add
`--release` to qualify that profile independently. For an extracted archive,
set `PROMETEU_PROTOCOL_TEST_INSTALL` and run the ignored
`packaged_memcard_process_persistence` test. It invokes the installed dispatcher
from another cwd without modifying any consumer project or installation.
## Program Registry integration
When exposing initialization failures, retain the [structured load error](02c-program-registry-and-pbx-v0.md#errors-and-publication) code, typed reason and available context. Human-readable messages are not a parsing contract; a load error has no fabricated runtime PC. Failed loads must not publish executable sessions. Existing protocol request names and transport behavior are unchanged.