Files
VCCPlusOSS/docs/development/MCP_BANKED_PLAYTEST.md
T

377 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Banked C debugging and owned MCP playtests
> Technical evidence extract for the VCC Plus white paper. Only reviewed contracts, mechanisms, methods, results and limitations are retained. Original validation dates and configuration limits remain historical; this export is not a new test run.
## Build evidence for packed programs
Set optional `debugManifest` in `vccplus-project.json` to a generated relative
JSON path, for example `build/debug/manifest.json`. The Make recipe must produce
it alongside the exact configured binary and disk. Changing that setting or its
exporter changes the approved recipe and requires native
[project-refresh review](MCP_PROJECT_RELIABILITY.md)
or a new connection. `get_build`
returns `debug_manifest` with the generated path, SHA-256, byte count and exact
UTF-8 text when it fits the 128 KiB sharing limit. Builds can
succeed without usable debug evidence; their receipts report why source debugging
is unavailable. In `source_debugging`, `status: "verified"` includes verified
source/type information; `"source_only"` distinguishes a verified source map from
unavailable variable metadata, and `"unavailable"` reports a failed map check.
A successful recipe alone does not establish any of these debug claims.
There is no fallback that treats a packed image as an unpacked
source image.
Manifest version 1 contains:
```json
{
"version": 1,
"entryPoint": 3584,
"binary": {"path": "build/game.bin", "sha256": "<64 lowercase hex digits>"},
"disk": {"path": "build/game.dsk", "sha256": "<64 lowercase hex digits>"},
"linkMap": {"path": "build/game.map", "sha256": "<64 lowercase hex digits>"},
"sources": {"main.c": "<sha256>"},
"artifacts": {
"build/main.o": "<sha256>",
"build/main.lst": "<sha256>",
"build/debug/resident.raw": "<sha256>"
},
"modules": [{
"id": "resident-code",
"sections": ["code"],
"codeSections": ["code"],
"image": {"path": "build/debug/resident.raw", "logicalAddress": 4096},
"pages": [{"logicalPage": 0, "physicalPage": 56}]
}]
}
```
This is a structural example, not a manifest for a runnable program. Include the
complete source set retained by the build service and every project object,
listing and raw slice used as evidence. The source set includes retained UTF-8,
non-NUL `.c`, `.h`, `.s`, `.asm`, `.lwasm` and `.inc` files, including generated
compiler assembly. Paths are canonical project-relative
regular files retained in the immutable result. Symlinks, traversal, inconsistent
hashes, ambiguous ownership and out-of-range sections fail verification. A raw
image can specify `offset` and `length`; logical and physical pages are 8 KiB.
Physical page numbers identify actual RAM backing after hardware mirroring, not
just the value written to an MMU register. Installed RAM capacity is checked by
the emulator. The packed binary's transfer address is `entryPoint`; it can belong
to a loader outside the unpacked C modules.
Declare each linker section under one module. `codeSections` names executable,
immutable sections; mutable data and BSS belong in `sections` with their real page
assignments but are excluded from code guards. BSS needs no invented raw zeros.
A pure BSS module may omit `image` entirely when `codeSections` is empty;
its explicit page assignments and section ownership still apply. An initialized
section cannot use that omission to skip object byte verification.
Keep mutable bytes out of executable sections. Split modules when unrelated pages
need not remain mapped together. Different overlays may reuse a logical address
only with distinct physical ownership.
Hashes bind the declaration to one build. VCC Plus independently replays object
relocations against the raw module bytes and verifies live RAM before publishing
source locations or values. Complete executable section guards include code
without C line markers. ROM and I/O mappings cannot masquerade as RAM. A stop in
the wrong bank, changed code or an unmapped overlay has no verified C location.
Expected bank switches preserve the banked attachment. Native banked source runs
use the project's declared disk launch; a binary-only packed project can still run
without a source attachment. Manual address breakpoints
remain separately owned. Optimized locals and unknown frame layouts remain
unavailable; globals are shown only with verified storage placement.
## Grant a disposable playtest
In **C Development → Assistant…**, select **Allow Disposable Playtests** and,
for a custom project, **Use Project Makefile**, then save the private connection.
The grant permits repeated launches of current built artifacts without another
launch prompt. It does not grant arbitrary host paths, commands, register writes
or guest-memory edits. Revoking the connection, changing the project revision or
rebuilding invalidates the owned run.
A playtest uses the installed app's `vcc-playtest` helper in a separate process,
stock Disk BASIC and 512 KB, with MC6809 by default or HD6309 selected in a fresh
build 45 connection, and a private writable copy of the selected
artifact or retained test disk. It does not load another emulator core into the personal session.
It reads no personal settings, tapes, cartridges or mounted drives. The app's
configured launch commands run on that test machine. The worker advances only
when asked, so a capture does not consume game time.
Use the live tool catalog and `get_capabilities` as the contract:
| Tool | Purpose |
| --- | --- |
| `list_playtest_disks` | List retained primary boot disks scoped to the current project, with opaque IDs, hashes and artifact provenance. |
| `list_playtest_media` (fresh media grant) | List the current artifact's reviewed disk products and, optionally, an owned run's private copies and compatible retained histories. |
| `exchange_playtest_media` (fresh media grant) | Insert/eject a listed private FD0 copy at a paused, idle guest without reset or time advance; retain the old bytes before replacement. |
| `start_playtest` | Supply current project, revision, artifact and request IDs. Optionally select `processor: "MC6809"` (default) or `"HD6309"`, a retained disk by ID and exact hash, or name `stop_function` with `stop_kind: "c_line"` (default) or `"function_entry"`. |
| `playtest_input` | Send steps of named physical `keys` held for `fields`, with optional complete standard `joysticks` snapshots on fresh joystick grants. Omitted ports center and release. |
| `get_playtest_input` (toolset 9 joystick grant) | Read actual owned input and clock without advancing; input receipts also carry per-step delivery traces. |
| `capture_playtest` | Read the framebuffer PNG, text when available, field clock, CPU and disk identities without advancing. |
| `capture_playtest_graphics` | At a paused owned state, render the current display buffer and optionally one declared buffer by ID, with physical identities and ordered PNG images. |
| `capture_playtest_audio` (development toolset 7) | Advance 1–120 guest fields, then pause and return direct PCM16 stereo WAV with actual timing/boot identity. Requires a fresh audio-enabled owned grant. |
| `playtest_debug` | Pause, continue, instruction-step, or arm a verified named function with `stop_at` and its `stop_kind`. |
| `get_debug_snapshot` | At a verified C or function stop, read its honest stop kind, module/physical identity, registers, permitted memory ranges and named watches. |
| `read_debug_memory` | Read an advertised range from the same immutable stopped snapshot, up to 256 bytes. |
| `get_call_context` (fresh toolset 10) | Read exactly 64 bytes at the paused owned guest’s actual S, with caller/integer-argument interpretation only where compiled evidence proves it. Supply the same run and snapshot IDs. |
| `restart_playtest` | Cold restart the owned machine, retain its writable disk, and repeat the boot commands. |
| `stop_playtest` | End the worker and retain its test disk in the app's development results. |
[Bounded call context](MCP_CALL_CONTEXT.md) explains raw versus proven values, fresh grants and snapshot invalidation.
Disk exchange covers `playtestDisks` declarations,
private writable sets, correct/wrong/empty media tests and explicit multi-disk
resumption. `restart_playtest` keeps the currently inserted disk; it does not
choose the primary disk automatically.
Development [debug evidence and diagnostics](MCP_DEBUG_EVIDENCE.md) extend these
receipts to ordinary verified custom-Make artifacts. Flat code uses verified
executable guards and observed runtime mapping; no physical bank is guessed.
See [audio timing, budgets and retry behavior](MCP_AUDIO_CAPTURE.md). Audio capture
is advancing; framebuffer capture is nonadvancing.
[Processor selection](MCP_PLAYTEST_PROCESSORS.md) describes toolset 8,
actual 6309 mode/MD reporting, restart behavior and legacy grants.
`playtest_input` accepts up to 64 steps, 1–600 fields per step and 3,600 fields per
request. Named keys include lowercase letters, digits, `up`, `down`, `left`, `backspace`,
`right`, `space`, `enter`, `clear`, `break`, `alt`, `control`, `f1`, `f2` and
`shift` and `period`. `period` is the actual unshifted CoCo period key; `backspace`
names the same physical key as `left`. Hold `shift` with a key for its physical
shifted meaning. The ordinary shared-run `send_keys` restrictions are unchanged.
A chord can hold up to eight distinct keys. A run has a bounded total
field budget of 216,000 attempts and 16 boots, including initialization and
restarts. Receipts include `remaining_field_budget` and `remaining_boots`.
`field_clock` counts completed emulated video fields, not game updates or wall
time; a breakpoint can interrupt a field and stop an input plan early. The
worker releases held keys at the end of a plan. Instruction stepping is one CPU instruction,
not a C source step.
For example, this plan types a period and releases every key. Retrying its exact
request ID and plan returns the prior receipt without another press:
```json
{"run_id":"<owned run>","request_id":"period-1","steps":[{"keys":["period"],"fields":6},{"keys":[],"fields":6}]}
```
The `get_build.source_debugging` catalogs distinguish `functions` (unique
functions with a mapped C statement) from `function_entries` (unique compiler function symbols whose full
range belongs to verified executable sections). Choose the corresponding
`stop_kind`; assembly-declared input samplers and interrupt/graphics routines can
use the latter without adding fake C statements or changing the compiler.
```json
{"run_id":"<owned run>","request_id":"sample-entry-1","action":"stop_at","function":"sample_input","stop_kind":"function_entry"}
```
At an assembly entry, `get_debug_snapshot` returns `source_stop: null`, a
`function_stop` with the symbol, entry/current address, physical bank and verified
declaration location, and `stop_kind: "function_entry"`. Instruction steps inside
that function report `"assembly_instruction"` until a mapped C instruction is
reached. A declaration is not a claim that a C statement is executing. Registers,
verified shared globals and bounded memory remain available; C locals and frame
layouts are not guessed. Missing, ambiguous, non-executable or wrong-bank symbols
remain unavailable. The same selector verifies advertised entries and requested
stops. Every module used by that snapshot must still pass its runtime byte
guards; another mapped overlay that has not finished loading acquires no source
claim merely because its page is selected.
Development build 42 also supports banked `source_only` Release inspection when
typed C metadata is absent. The build advertises `executable_symbols` proven
against its own retained objects, linker placements and initialized executable
bytes. Unique C underscore aliases may select those addresses with
`stop_kind: "function_entry"`. This selects an executable symbol, not a guessed
C function extent. A snapshot reports `symbol_stop`/`symbols_at_pc` and
`executable_stop`; it uses `symbol_entry` or `assembly_instruction` where no C
statement is mapped. `function_stop` remains empty without typed function proof.
Registers and advertised executable-code ranges remain readable, while `watches`
is empty and `source_debugging.variables` explicitly says `unavailable`. No Debug
addresses, guessed C frames or arbitrary memory ranges are substituted.
Advertised symbol/function catalogs and `symbols_at_pc` have a 32 KiB encoded
JSON budget each, with matching `_total` and `_truncated` fields. Private verified
selectors retain all names even when a public list is truncated. A `symbol_stop`
requires exactly one full verified match, not merely one displayed match.
Executable-code inspection requires known contributing source evidence inside
the shared project scope; an unknown source does not grant code access.
### Paused graphics-buffer captures
An optional manifest `framebuffers` array declares up to four buffers:
```json
"framebuffers": [
{"id":"page_a","physicalAddress":262144,"mode":"hscreen2"},
{"id":"page_b","physicalAddress":294912,"mode":"hscreen2"}
]
```
These addresses are an example for the bundled GIME library's two pages, not
defaults for another project. IDs contain 1–64 ASCII letters, digits, underscores
or dashes; `displayed` is reserved. Supported layouts are `sg4`, `pmode0` through
`pmode4`, and `hscreen1` through `hscreen4`. The app verifies the manifest's build
identity, and the worker checks the complete buffer against actual installed RAM.
An unsupported format or range is refused. Recipe/exporter changes require the
usual new approval; public calls cannot supply addresses, modes or raw bytes.
Development build 43 additionally supports **live GIME canvases**. Fixed
`hscreen2` still means BASIC's 320×192, 160-byte-row layout; it is not a label for
every 16-color application. Declare custom canvases explicitly:
```json
"framebuffers": [
{"id":"canvas_a","physicalAddress":0,"mode":"current_gime","canvasBytes":65536},
{"id":"canvas_b","physicalAddress":131072,"mode":"current_gime","canvasBytes":65536}
]
```
These example origins are not defaults. `canvasBytes` is required for
`current_gime`, must be a power of two of at least 8 KiB, and must align with the
physical origin. Canvas spans must be disjoint and fit actual installed RAM;
the worker is a 512 KiB machine. Fixed modes do not accept `canvasBytes`.
At a paused GIME graphics state, the current video origin must identify exactly
one declared active canvas. The selected canvas inherits the live viewport's
width, height, row pitch, horizontal pan, vertical scroll, palette and byte offset
relative to that active canvas. Hardware horizontal row wrapping is preserved.
Every sampled byte must remain in the declared active and selected spans; the
preview refuses an escape instead of inventing vertical canvas-modulo behavior.
Unsupported text/compatibility layouts are refused for this mode.
Metadata reports `video_origin`, `row_stride_bytes`, `horizontal_offset_bytes` and
`vertical_scroll_lines`; identified canvases also report `canvas_id`,
`canvas_address`, `canvas_bytes` and `viewport_offset`. `physical_address` remains
the first actual sampled byte, including pan, rather than the declared origin.
The two images still share one frozen state. No capture API accepts caller
addresses or changes the live registers/RAM.
Pause, then call `capture_playtest_graphics` with `run_id` and optional
`buffer_id`. It returns the current displayed-buffer preview first, followed by
the selected declared buffer. Both use the same stopped generation/cycle/field
state and become standard MCP image blocks; metadata carries physical ranges,
layout, dimensions and identity. Rendering uses a copied GPU state, advances no
guest instruction and changes no RAM or registers. Logical preview dimensions
may differ from the bordered 640×480 framebuffer image.
The normal `capture_playtest` PNG is still the last published video frame.
Its `display_buffer` describes the current video-register selection, which can
already have changed before another frame is published. The paused capture is
labeled `paused_register_preview`; it does not claim to reconstruct a historical
scanout or infer which unregistered page the guest will draw next.
Only the latest successful artifact in this connection can start an owned run.
Finish one configuration's playtest before building another configuration.
### Asynchronous startup
Build 43 advertises `async_playtest_start`. `start_playtest` promptly accepts the
operation with a reserved `run_id`, `status: starting` and a preparation phase.
Poll `get_run` until startup is ready or reports a terminal failure; do not send
movement, capture or debugger calls while it is still preparing. Phase updates
distinguish metadata verification, artifact loading, retention, boot and capture.
Preparation does not hold an open MCP reply for the whole build-map/boot cost.
Reuse the exact original request ID and arguments to recover the same operation;
a conflicting retry is refused. A failure remains inspectable rather than
silently starting a second machine. `stop_playtest` can cancel the reserved run
while it is starting. Revocation, source/revision changes and cancellation cannot
leave a late-created worker orphaned; cleanup completes before another startup
can replace it. A transport timeout is reported separately from a malformed or
incomplete host envelope, and neither justifies an automatic new start ID.
Use the connected `project_id` and `revision` with `get_run`, as with ordinary
compiled runs. `status: ready` contains the current worker `receipt`; inspect
its `state` (`paused` or `running`) separately. Startup readiness is not a claim
that the guest reached the requested breakpoint. Initial metadata receipts omit
PNG data; call a capture tool explicitly when ready. Terminal `failed` receipts
retain the phase and bounded error, and a cancelled operation settles only after
any late worker has been retired.
### Resume a retained test disk
Stopping or revoking a run retains its writable disk in the app's development
results. `stop_playtest` returns `retained_disk_id` and `retained_disk_sha256`;
`list_playtest_disks` can recover the current project's recorded disks after an
app restart or connection replacement. A listed record supplies `disk_sha256`;
pass that value as `retained_disk_sha256` when starting the run. Listing reads
bounded provenance metadata; resumption rechecks the actual disk bytes against
the supplied hash. Legacy or incomplete records are not added to that listing.
These are opaque selections, not host paths. Rebuild the current project and pass the selected receipt to
`start_playtest`:
```json
{"project_id":"<current project>","revision":0,"artifact_id":"<current built artifact>","request_id":"resume-save-1","retained_disk_id":"<retained run UUID>","retained_disk_sha256":"<exact saved disk SHA-256>"}
```
Both retained-disk fields are required together. The app checks the saved bytes,
project ownership and recorded base-artifact disk hash before launching. A
rebuild may have a new artifact ID while producing the same base disk bytes.
A changed base disk requires a fresh test; the interface does not silently mix
an old saved disk with changed program evidence. Resuming cold-boots a fresh
machine using the project's declared commands. It restores disk contents, not
CPU or RAM state. Use the guest program's normal Load/Continue action afterward.
The retained original stays unchanged. The resumed run gets a separate writable
copy and, when stopped, its own retained ID with a parent-disk link. Receipts
distinguish the selected disk's hash from the current artifact disk hash, and
runtime source verification still checks the code actually loaded in RAM.
Receipt identities have separate meanings:
| Field | Meaning |
| --- | --- |
| `artifact_disk_sha256` | Fresh disk bytes produced by the current build artifact. |
| `disk_original_sha256` | Initial bytes copied into this worker, including a selected retained save. |
| `disk_sha256` | Current writable test-disk bytes after guest activity. |
| `retained_disk_sha256` | Exact bytes successfully persisted when the worker is stopped. |
| `disk_origin` / `disk_provenance.origin` | Recorded origin, including `legacy_receipt` when old provenance is absent. |
Recorded children preserve `origin_artifact_id` and
`origin_artifact_disk_sha256` separately from the current execution artifact and
`parent_disk_id`. Current build identity does not assert that it generated a
legacy disk's historical bytes.
Disks retained before this feature have no project/artifact sidecar. They are
never exposed through an unscoped listing. A client that already holds that
run's UUID and exact disk SHA-256 from its previous receipt can explicitly resume
it from the fixed app-managed retention area. Its origin is reported as
`legacy_receipt`; the app does not invent missing old artifact provenance.
Subsequent child records preserve that origin and bind to the current project
and selected execution artifact. No arbitrary file path, memory write or change
to the personal machine is accepted by this interface.
Successful retention publishes the disk and its metadata together. Replacing a
run waits for persistence. If a write fails after export, the app keeps the
exported bytes for retry and does not claim `disk_retained: true`. Keep the app
open while resolving that failure; repeating the same stop request retries
persistence without executing the guest or exporting a second disk.
Use a fresh request ID for each distinct action. Retrying an identical accepted
request returns its receipt without executing inputs or restarting twice. Reusing
an ID for a different action is rejected. Broken worker communication retires the
run instead of risking a duplicated action. Save/load tests use real guest input
and the retained disk; debugger writes are not part of this interface.
A PNG belongs to the guest display, not a capture of the Mac desktop. The public MCP transport returns a standard image content block alongside
dimensions and frame identity; the internal worker uses `png_base64`. Consumers
may save that image within their own project. Source snapshots expose only verified
shared program ranges, never arbitrary live machine memory. Available named
watch rows include their verified address, byte count and bank identity when
the storage belongs to a shared readable range, so clients do not guess where
a structure resides.
## Qualification
See the current development validation and remaining checks.
The distribution record identifies the delivered candidate and completed checks.
Authored regressions cover both guest CPUs, wrong-bank stops, complete code
mutation, stale source commands, immutable bridge inputs, manifest tampering,
physical storage ownership and input request retries. Actual game evidence and
remaining limitations are recorded with the candidate rather than asserted by
this protocol description.
Large compiler type records can exceed the assembler's input-line limit. The
reader recovers complete records only from the retained, source-hashed compiler
assembly and requires matching listing record order, count and exact truncation
prefixes, then verifies all referenced object/linker labels as before. This
supports large application structures without relaxing build identity checks.
The optional `VCC_TEST_BANKED_ARTIFACT` XCTest input qualifies any retained
custom-project artifact without executing its Makefile or starting an emulator.