feat(host): expose memcard controls and qualify process persistence
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user