# 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": ""}, "artifacts": { "build/main.o": "", "build/main.lst": "", "build/debug/resident.raw": "" }, "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. Verification uses distinct evidence budgets: the manifest is at most 1 MiB; retained compiler `.s` assembly is at most 32 MiB per file; other evidence files (including listings, objects, linker maps, executable and raw images) are at most 8 MiB each. Unique retained evidence is capped at 128 MiB in total. Files are verified in full against their hashes; oversized evidence is rejected rather than truncated. Rejections identify the artifact path, observed size and byte limit. Existing limits on manifest records, module/page ownership and listing rows still apply. Large generated type records in assembly do not relax the assembler-listing row limits or establish a source mapping by themselves. 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. Version 1 permits logical-address reuse with distinct physical ownership. For code images that replace one another in the same physical RAM, use the explicit version-2 overlay group and owner contract. Runtime inspection requires complete loaded-code proof of exactly one owner; declaration alone does not establish residency. Build catalogs list static candidates, while a paused inspection reports current verified ownership and a residency fingerprint. 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":"","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":"","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":"","revision":0,"artifact_id":"","request_id":"resume-save-1","retained_disk_id":"","retained_disk_sha256":""} ``` 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.