188 lines
9.4 KiB
Markdown
188 lines
9.4 KiB
Markdown
# Owned-playtest disk exchange
|
|
|
|
A fresh C connection with **Allow Disposable Playtests** can advertise
|
|
`playtest_media_exchange` and the `list_playtest_media` /
|
|
`exchange_playtest_media` tools. Check live discovery and `get_capabilities`
|
|
before planning exchanges. Existing connections keep their original schemas;
|
|
new tools require a newly reviewed connection and a restarted client helper.
|
|
This feature operates only on an owned disposable guest, never the ordinary
|
|
shared run or personal mounted media.
|
|
|
|
## Declare the disk products
|
|
|
|
In **C Development → Project Settings → Build**, list additional playtest disk
|
|
outputs, one project-relative path per line. The portable project configuration
|
|
uses:
|
|
|
|
```json
|
|
{
|
|
"diskImage": "build/HOME.dsk",
|
|
"playtestDisks": [
|
|
"build/DATA.dsk",
|
|
"build/WRONG.dsk",
|
|
"build/CORRUPT.dsk"
|
|
]
|
|
}
|
|
```
|
|
|
|
This is a configuration fragment. Keep the rest of the project's actual build
|
|
and launch settings. The primary `diskImage` remains the boot disk. Up to eight
|
|
additional `.dsk` or `.os9` products are supported, each no larger than 512 KiB.
|
|
They must be ordinary generated files from the same approved Make build. The
|
|
app validates relative paths, distinct outputs, source/output separation,
|
|
regular-file identity and exact build hashes; symbolic or hard-linked products
|
|
are refused. A successful normal/disk build must produce every declared disk.
|
|
Changing declarations changes the reviewed recipe and isolated build identity.
|
|
Source refresh review preserves drafts and does not run the guest.
|
|
|
|
The app retains immutable artifact copies. A playtest creates its own writable
|
|
copy of each declared disk, including the primary. It does not edit project
|
|
products. Deliberately wrong editions and corrupted game catalogs/payloads may
|
|
be separate declared images. The app still rejects malformed disk containers;
|
|
validation of a game-specific label, edition or checksum belongs to the guest.
|
|
|
|
## List and select without paths
|
|
|
|
Call `list_playtest_media` with the current project, revision and artifact:
|
|
|
|
```json
|
|
{"project_id":"<project>","revision":0,"artifact_id":"<artifact>"}
|
|
```
|
|
|
|
The response's `media` rows supply opaque `media_id` values, readable project
|
|
product names, `base_sha256`, current `media_sha256`, byte counts and compatible
|
|
retained choices. Add `run_id` to inspect this run's private copies, including
|
|
inserted/dirty/retained state. Listing never advances emulation. The current
|
|
mounted disk is measured in the worker; ejected copies use their frozen bytes.
|
|
A writable copy's current hash can differ from its artifact base hash.
|
|
|
|
Compatible retained choices are bounded to the latest sixteen per product;
|
|
counts and a truncation flag identify omitted history. `list_playtest_disks`
|
|
keeps its older primary-boot-disk-only contract. Additional world/data disks
|
|
are not advertised as primary boot selections.
|
|
|
|
The drive is **FD0**. No tool accepts a host pathname, another drive number,
|
|
arbitrary bytes, another project's disks or a personal guest. Product IDs bind
|
|
to the current artifact, not just a filename. Listing and insertion recheck the
|
|
project/revision/artifact and any retained disk's exact provenance and bytes.
|
|
|
|
## Exchange at a guest prompt
|
|
|
|
1. Boot the primary disk through the project's declared commands.
|
|
2. Use normal guest input to reach its disk-change prompt.
|
|
3. Pause the owned run with `playtest_debug` and `action: "pause"`. A guest
|
|
waiting for keyboard input is still a running machine until explicitly paused.
|
|
4. Insert a listed private copy with its exact current hash:
|
|
|
|
```json
|
|
{"run_id":"<owned run>","request_id":"insert-data-1","action":"insert","media_id":"<listed media ID>","media_sha256":"<listed current SHA-256>"}
|
|
```
|
|
|
|
To leave FD0 empty, omit both selection fields:
|
|
|
|
```json
|
|
{"run_id":"<owned run>","request_id":"eject-data-1","action":"eject"}
|
|
```
|
|
|
|
An exchange also requires an idle floppy controller. A paused CPU or stopped
|
|
motor alone does not prove an incomplete guest transaction has finished. The
|
|
app refuses an exchange while a command is pending; it never cancels the guest's
|
|
disk I/O to force a swap. Continue through the guest's normal recovery path and
|
|
pause at an appropriate prompt instead.
|
|
|
|
The host exports and durably retains the old disk before committing replacement.
|
|
The worker validates the complete new image before removing the old one. It
|
|
checks the old hash and media generation again at commit. A validation,
|
|
provenance, stale-ownership or retention refusal before commit leaves the old
|
|
paused disk and its dirty bytes intact. The same private copy is reused when switching back.
|
|
|
|
Exchanges do not reset the guest, advance its field clock, type keys or modify
|
|
RAM/registers. The response reports `previous_media`, retained snapshot identity,
|
|
new selection, `media_generation`, hashes, dirty state and the unchanged clock,
|
|
with `guest_advanced: false` and `guest_reset: false`. Normal input resumes the
|
|
guest so it can read the newly inserted disk itself. Capture the framebuffer
|
|
and inspect the game's response; a successful mount is not proof that the game
|
|
accepted the media.
|
|
|
|
Reuse a request ID only with the identical selection. The cached receipt prevents
|
|
a retry from performing another exchange; different arguments conflict. Exchanges
|
|
consume the existing owned mutation-request budget, not emulated fields. The
|
|
normal input, audio, startup and ownership limits remain in force.
|
|
|
|
An ownership refusal at the final precommit check returns `stale_run` and leaves the
|
|
current disk in place. If the worker acknowledges a committed exchange but
|
|
run ownership expires before its success reply can be returned, the still-authorized
|
|
connection can receive `stale_run_after_commit`: the swap happened, and its
|
|
committed receipt is retained. This reason distinguishes that acknowledged
|
|
outcome from a precommit refusal; it does not restore authority or include the
|
|
withheld receipt. Connection revocation takes precedence and returns
|
|
`access_denied` without exposing the run outcome.
|
|
|
|
Do not issue a new request ID to repeat an exchange after a lost reply or
|
|
`stale_run_after_commit`. An identical-ID/identical-arguments retry can reuse a
|
|
retained receipt only if the same run still passes the current connection,
|
|
project, revision and artifact ownership checks. Inspection for reconciliation
|
|
has the same authorization requirements. A revoked grant cannot retrieve a
|
|
receipt or inspect its former run merely because the app retained the outcome.
|
|
If the run is no longer accessible, use a newly reviewed connection and the
|
|
compatible retained-disk listing described below; old-run access is not renewed.
|
|
|
|
Obtain a new debug snapshot after an exchange; earlier inspection/call-context
|
|
snapshots are invalidated even though CPU/RAM and the field clock did not change.
|
|
The public helper gives exchange the existing bounded 55-second playtest
|
|
transport deadline, allowing durable retention before returning its receipt.
|
|
|
|
If the worker connection fails after a possible commit and its final selection
|
|
cannot be confirmed, the run is retired. The host retains every frozen copy and
|
|
reports `media_selection_uncertain` instead of guessing which disk was inserted.
|
|
List media without the retired `run_id` to recover compatible retained choices,
|
|
then start a fresh run. An interrupted reply is not evidence that no swap took
|
|
place; do not create another request to repeat an uncertain operation in that run.
|
|
|
|
## Save, restart and retain every disk
|
|
|
|
For a one-drive application, insert Home at its save prompt, use its real Save
|
|
command, then insert Data to continue. `restart_playtest` cold-boots the currently
|
|
inserted private disk through the declared commands; it keeps all the other
|
|
private copies and their changes. Insert the boot disk first when the current
|
|
data disk cannot boot. Restart does not automatically choose another disk.
|
|
|
|
`stop_playtest` retains every disk in the owned set, even when FD0 is empty.
|
|
`retained_media` returns an individual immutable disk ID/hash and product
|
|
provenance for each. The established top-level `retained_disk_id` and
|
|
`retained_disk_sha256` refer to the primary Home copy. Cleanup remains possible
|
|
after the execution/request budget is exhausted. Failed persistence is retryable
|
|
without sending a second STOP or discarding the frozen exported bytes.
|
|
|
|
To start a new run, use the primary retained fields as before. Additional copies
|
|
are explicit fresh-grant selections:
|
|
|
|
```json
|
|
{
|
|
"project_id":"<project>",
|
|
"revision":0,
|
|
"artifact_id":"<current artifact>",
|
|
"request_id":"resume-disk-set-1",
|
|
"retained_disk_id":"<saved Home ID>",
|
|
"retained_disk_sha256":"<saved Home SHA-256>",
|
|
"retained_media":[{
|
|
"media_id":"<current artifact Data ID>",
|
|
"retained_disk_id":"<saved Data ID>",
|
|
"retained_disk_sha256":"<saved Data SHA-256>"
|
|
}]
|
|
}
|
|
```
|
|
|
|
Omit `retained_media` for fresh additional copies. Each selected retained image
|
|
must match this project, primary artifact base and its own declared product/base
|
|
hash. A stale product ID, changed data image, wrong project or altered retained
|
|
bytes is refused. Retained originals remain immutable; resumed runs receive
|
|
separate private copies and retain their parent links. This restores disks, not
|
|
running CPU/RAM state. Use the guest's normal Load/Continue action after boot.
|
|
|
|
See [owned playtests](MCP_BANKED_PLAYTEST.md),
|
|
[project refresh](MCP_PROJECT_RELIABILITY.md) and
|
|
[custom Make projects](MCP_CUSTOM_MAKE.md). The
|
|
[validation record](MCP_PLAYTEST_MEDIA_VALIDATION.md) distinguishes generic
|
|
guest/transport checks from application-specific acceptance.
|