Publish VCC Plus OSS source distribution for 3.6.2 build 60
This commit is contained in:
commit
c652a5276d
1192 files changed
+272368
No files matched your search
@@ -0,0 +1,187 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user