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