Files
Brian Holman 5534005799 Sync VCC Plus 3.7.1 build 67 source
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.
2026-11-17 08:42:27 -07:00

24 KiB
Raw Permalink Blame History

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 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:

{
  "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.

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 copy at a paused, idle guest without reset or time advance; fresh multi-drive grants select FD0–FD3 and insert-time protection; retain 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, preserve all selected drives/copies/protection, and repeat the boot commands.
stop_playtest Freeze and independently retain every test disk before ending the worker.

Bounded call context 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, four-drive receipts and transferred-byte activity. Fresh multi-drive grants use toolset 13+ with playtestMultiDrive: true; older media grants keep FD0-only behavior. restart_playtest preserves the mount map rather than moving the primary disk to FD0; ensure the intended boot disk is present there.

Development debug evidence and diagnostics 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. Audio capture is advancing; framebuffer capture is nonadvancing. Processor selection 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:

{"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.

{"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:

"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:

"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:

{"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.