Refresh reviewed MCP output export, four-drive owned playtests, bounded BASIC readiness, and pinned CMOC 0.1.101 source/patches. Preserve independent source-edition identity, empty libraries, notices and privacy boundaries. Validated 74 export/privacy checks, pinned dependency sources, and an independent unsigned universal Release build. A subsequent documentation-only correction removes an excluded qualification link; all build inputs remain identical.
234 lines
12 KiB
Markdown
234 lines
12 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.
|
||
Fresh multi-drive grants additionally declare strict Boolean
|
||
`playtestMultiDrive: true` with toolset 13 or later. Legacy media grants retain
|
||
their FD0-only schema; an app update does not expand an old connection.
|
||
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.
|
||
|
||
On a fresh multi-drive connection, `exchange_playtest_media` accepts integer
|
||
`drive` 0–3 for **FD0–FD3**; omission means FD0. Legacy media connections remain
|
||
FD0-only. No tool accepts a host pathname, 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.
|
||
|
||
## Read a coherent four-drive receipt
|
||
|
||
Fresh multi-drive results carry `media_contract_version: 2` and a `drives` array
|
||
with exactly four bounded observations. Each row identifies numeric `drive`,
|
||
`label` (`FD0` through `FD3`), `inserted`/`disk_present`, current `media_id`, byte
|
||
count, original/current hashes, generation, dirty state and effective protection.
|
||
The host associates the row with product/base provenance, media key and available
|
||
retained identities. A media inventory row's nullable `drive` identifies current
|
||
placement; product identity remains independent of placement.
|
||
|
||
`disk_reads` and `disk_writes` count guest-transferred data bytes over the worker's
|
||
lifetime. `mount_read_bytes` and `mount_write_bytes` reset at a media-generation
|
||
change. They are not counts of completed Save commands. Use guest save/reload,
|
||
exact before/after hashes and the relevant generation's activity together. A
|
||
rewritten identical value can have activity without a changed content hash.
|
||
Read-only listing/capture does not advance emulation. Established top-level disk
|
||
fields continue to describe FD0; top-level retained primary fields still identify
|
||
the reviewed primary product even when it was moved to another drive.
|
||
|
||
## 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","drive":1,"media_id":"<listed media ID>","media_sha256":"<listed current SHA-256>"}
|
||
```
|
||
|
||
This example leaves Home in FD0 and inserts Data in FD1. To leave FD1 empty,
|
||
omit both selection fields and name that drive:
|
||
|
||
```json
|
||
{"run_id":"<owned run>","request_id":"eject-data-1","action":"eject","drive":1}
|
||
```
|
||
|
||
`drive` must be a whole number from 0 through 3; booleans, fractional numbers and
|
||
out-of-range values are refused. A fresh multi-drive insert also accepts strict
|
||
Boolean `write_protected`. Omission preserves that copy's current setting; false
|
||
cannot remove format-imposed protection. Eject forbids this option and the
|
||
media/hash insertion fields. Protection belongs to the private copy and survives
|
||
exchange, restart and retention independently of its content hash.
|
||
|
||
The same writable private copy cannot be mounted in two drives at once. Eject
|
||
then insert to move it; matching bytes alone do not make two independent copies
|
||
the same object. An exchange affects only its target drive and never changes
|
||
BASIC's current/default drive.
|
||
|
||
An exchange also requires an idle shared floppy controller, including activity
|
||
associated with a different drive. 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 `target_drive`, `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, target drive and explicit
|
||
protection choice. An omitted drive and explicit drive 0 are normalized to the
|
||
same 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. A multi-drive application can instead
|
||
keep Home in FD0 and Data in FD1 and decide its own save routing.
|
||
`restart_playtest` cold-boots through the declared commands while preserving
|
||
all current drive assignments, bytes and protection. Ensure FD0 contains the
|
||
intended boot disk before a DOS boot. Restart does not secretly move the primary
|
||
product to FD0 or choose a bootable disk. Startup mount maps are not part of
|
||
this interface: insert into other drives through explicit paused exchanges.
|
||
|
||
`stop_playtest` freezes the mounted state coherently and drains the four drives
|
||
through separate bounded exports before worker exit. It retains every disk in
|
||
the owned set, including ejected copies and when FD0 is empty. A combined reply
|
||
does not concatenate four full disk images across the 1 MiB transport limit.
|
||
`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.
|