Publish VCC Plus OSS source distribution for 3.6.2 build 60

This commit is contained in:
Brian Holman committed 2026-11-13 00:14:03 -07:00
commit c652a5276d
1192 files changed
+272368

No files matched your search

+51
View File
@@ -0,0 +1,51 @@
# Assembly Development
> 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.
Open **Develop → Assembly Development…** at a CoCo 3 BASIC prompt. The first document is Hello World — Earth or Mars. You can run it before saving a file or creating a disk.
## Working with several files
Use **File → Open Source…** for a single file with local includes, or **Open Project Folder…** for a folder of sources. Assembly instructions in LWASM normally start after whitespace. Put labels in the left column. Relative filenames and labels keep their original spelling and case. Save your work as ordinary UTF-8 source. Recoverable drafts retain edits separately from saved files.
The default project entry is `main.asm`. In a project folder, **File → Project Settings…** opens the editable `vccplus-assembly.json` configuration. For an object-linked program, set the entry module, additional modules and your LWLINK script:
```json
{
"main": "main.asm",
"modules": ["draw.asm"],
"linkScript": "layout.link"
}
```
VCC Plus assembles each module, links the objects and verifies source addresses against the final loaded bytes. Use the listing or native disassembly when a source location is ambiguous. A custom Make recipe can instead declare `makefile`, `target` and `binary`. Review the recipe before allowing it to run with your Mac account’s permissions. Custom recipes produce a runnable/exportable binary and can use the machine debugger. Verified source stops require the native assembly or link workflow.
## Share an assembly project with a local assistant
In Assembly Development, choose **File → Local Assistant Access… → Save Assembly Connection…**. The saved connection gives one client access to the current assembly document, including unsaved edits. Configure the client with the bundled helper and the saved connection file. See the local MCP client instructions.
Build 28 can read the listed files, assemble them with the bundled LWASM, return diagnostics and propose a single-line replacement. Review the current and proposed lines in the access panel. **Apply Edit** updates that buffer and supports the editor’s usual Undo. Assemble the revised source, set a stop on an executable instruction, then choose **Run Shared Build…**. At a verified pause the client can read the mapped source line, instruction bytes, PC, available A and E registers and the text byte at `$0400`. **Revoke Connection** ends access. Selecting another document also ends its grant.
Build 29 adds **multi-file review**. The assistant can call `propose_project_edits` with one to eight existing shared assembly or include files and up to 16 KiB of UTF-8 replacement source altogether. Open each filename to compare the entire proposed source with its current draft. **Apply All Changes** updates all the drafts together. **Cancel Changes** preserves them. Save writes the updated files. **Undo All Changes** in the access panel restores the previous drafts as one operation while that applied revision is current. If the workspace changes during review, ask the client to reread and propose against the new revision. Native two-file review
In build 30, start the shared build from the BASIC prompt to play an assembly text game over MCP. After the native launch the assistant can read the screen and send one letter, digit or space at a time. When the program returns to BASIC, the live game controls close. Play an interactive program
The development client can also call `get_machine_status` for the actual CPU, memory and media state, build and run blockers, and the latest build ID and status. Use `get_run` after a native run to obtain its run ID. At a verified source stop, `get_debug_snapshot` returns registers, the source stop and the readable address ranges. Pass the same run and snapshot IDs to `read_debug_memory` to read up to 256 permitted bytes. Stale snapshots and addresses outside the disclosed ranges are refused.
Share a direct-assembly project containing up to 32 UTF-8 assembly and include files, up to 64 KiB each and 512 KiB overall. Project includes must resolve inside the shared snapshot. Linked projects and custom Make recipes use the native workbench. Earlier CPU and target qualification
The assembly regression client exercises a dedicated app launched with `--interface-validation --mcp-assembly-regression --mcp-assembly-fixture EMPTY_DIR --mcp-rom-dir ROM_DIR`. Use a fresh, private directory each time and pass `--helper HELPER --fixture EMPTY_DIR --cpu 6809 --target 6809` to the client. For HD6309, add `--basic-6309 --mcp-assembly-hd6309` to the app and use `--cpu 6309 --target 6309` for the client. The test covers stale proposals, cancellation, whole-project apply and undo, an assembled run after changing both files, snapshot-scoped memory reads, and refusal of an out-of-project include. The optional mismatched combination checks that a 6809 guest refuses HD6309-only code.
## Verification on November 5, 2026
The screen-cell lesson assembled and ran in Disk BASIC, Hard Drive BASIC and CoCo SDC on both emulated processors. The disk export also ran from a Disk BASIC prompt with `LOADM"FIRST":EXEC`. The two-module test checked the linked address of a subroutine and its relocated operand. Follow the reference lesson table to reproduce the seven smaller CPU experiments.
The 78 focused Xcode tests passed on arm64 and again under x86_64 Rosetta. They cover assembly, BASIC bibliography and profile integration, the shared C build and source-map services, and disk safeguards. All 66 portable core checks also passed on arm64.
On macOS 27.2 with Xcode 27.2, the isolated native window test stopped before the first instruction, stepped twice, returned keyboard focus to the running CoCo, opened an example in a separate document and resized the editor. The relocated, locally signed development app produced identical binaries with the arm64 and Rosetta x86_64 slices of its embedded assembler. Physical Intel hardware, a macOS 14 installation and a notarized installer were outside this pass.
- Assembly editor paused after the screen write
- Quick Reference with LDA selected
While the editor is open it monitors the active project's files. Before source stepping or continuing it rechecks the project inputs. While a different document is open or the window is closed, a running guest can still reach stops armed for the previously loaded binary.
+339
View File
@@ -0,0 +1,339 @@
# BASIC development workspace
> 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.
## Direct machine operations
- **Load into CoCo** installs the editor's complete program at a safe BASIC
prompt, without running it. It replaces the existing in-memory program and
prepares a fresh BASIC execution/variable state. The previous running/paused
state of the emulator is preserved; a paused load does not execute guest
instructions until Run or Resume completes the interpreter initialization.
- **Run** performs the same validated replacement and starts a fresh execution
through the existing ROM interpreter. It does not add a source breakpoint or
require an additional Run action in the emulator.
- **Read from CoCo** reads the program currently in BASIC memory back into the
editor. This includes changes made through the CoCo's own line editor. It reads
program source, not variable values or a suspended execution checkpoint.
Load and Run preflight the entire source, ROM, memory mapping, available space
and interpreter state before replacing program memory. They refuse an unsafe
state, such as a program still executing or waiting for INPUT. Mounted disks,
cassettes, cartridges and machine configuration are retained. Existing media
save/export protections remain independent of these program-memory operations.
Read-back is a canonical listing: keywords use their BASIC spellings, `?` may
become `PRINT`, lines are numbered and sorted, and ROM-inserted separators around
`ELSE` and apostrophe remarks are handled so that reading and reloading preserves
the program. It is not a byte-for-byte copy of the editor's original formatting.
Programs containing unsupported binary/non-ASCII text or damaged line links are
rejected without replacing the editor's contents.
## BASIC line breakpoints
Click the gutter circle beside a numbered statement, or use **Toggle BASIC
breakpoint at insertion point** in the toolbar. Breakpoints are explicit; the
sample and a new document start with none. **Run** installs the program and its
breakpoints together, so even its first line can stop before executing. Changes
to the breakpoint set can also attach to an already-loaded matching program.
At a breakpoint the whole emulator pauses, the source line is highlighted, and
**Continue** resumes without reloading BASIC, clearing variables, unwinding
GOSUB/FOR stacks or closing files. Continue executes the stopped line once before
that breakpoint can stop again. **Run** remains a fresh program transfer, subject
to the existing OK-prompt guard; it is not the Continue action. The main emulator
Resume action can also leave a BASIC stop.
These are **line-entry breakpoints**. A colon-separated second statement and a
return into the middle of a line do not re-trigger that line's entry breakpoint.
The stepping controls below can stop at those individual statements.
In Earth or Mars, set a breakpoint on the line that prints `M$` and add
`M$` as a watch. Run the program and select a planet. At the stop, the watch
contains its greeting and the screen still shows the menu. Step once to print
the greeting. Continue to switch back to the usual text colors and return to BASIC.
The editor checks its source against the tokenized program in CoCo memory.
Editing the source detaches the live mapping immediately and hides the execution
highlight; pending breakpoint numbers apply on the next Run. A core comparison
of the line chain, command dispatcher and memory mapping also detaches when the
guest program or relevant memory changes. Continue rechecks the source and stop
on the emulation queue before resuming. It refuses a stale stop. Explicit CPU
stepping, PC changes, binary loading, resets and configuration replacement also
end the BASIC debugging attachment. Manual machine-code breakpoints are kept
separately.
Breakpoint selections last for the current editor document/session. New, Open
and Read from CoCo clear them; Renumber clears them after changing the labels so
old breakpoint numbers cannot silently target different code. Source files and
recovery drafts do not currently store breakpoints. Closing the workspace window
alone preserves its model and the paused CoCo session.
The hook uses the shared command dispatcher at `$ADC6`, with the current line at
`$0068` and input pointer at `$00A6`. The input pointer must identify the line's
first token. The Color, Extended and Disk BASIC dispatch loops have different
entry paths but converge here. The implementation validates the qualified
bundled CoCo 3 interpreter and dispatcher before enabling this behavior; it does
not patch ROM or program bytes. The primary references are the command dispatch
sections in [Color BASIC Unravelled](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/color-basic-unravelled.pdf),
[Extended BASIC Unravelled](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/extended-basic-unravelled.pdf)
and [Disk BASIC Unravelled](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/disk-basic-unravelled.pdf).
## Statement stepping and Step Over
At a BASIC breakpoint, **Step Into BASIC statement** (the down-arrow toolbar
button) executes until the next statement the interpreter dispatches. A yellow
highlight identifies its source line; a stronger orange highlight identifies
its next token, including separate statements on the same line. The mapping is
emitted by the tokenizer from the original editor source, preserving spelling,
spacing, CRLF and source order. Highlighting never edits the document or moves
the insertion point.
**Step Over BASIC subroutine** (the bent-arrow button) follows a `GOSUB` through
its `RETURN`, including recursion and `ON … GOSUB`. Nested `FOR/NEXT` loops are
not mistaken for subroutine calls. An explicit breakpoint inside the call still
wins. On an ordinary statement, Step Over stops at the next statement just like
Step Into. `IF` can dispatch an inline THEN/ELSE command as a separate stop;
expressions themselves are not individually stepped. REM, DATA, skipped branches
and empty separators follow the interpreter's behavior.
The editor is temporarily read-only while a step is running. **Pause BASIC step**
appears during a wait, and the main emulator Pause action also cancels stepping.
A step pauses automatically after 600 emulated video frames (about ten seconds),
so a nonreturning subroutine or INPUT wait cannot leave an unbounded debugger
operation. Continue resumes the existing execution without reloading. After
cancellation or the limit, stepping becomes available again at the next BASIC
breakpoint; no statement highlight is invented for a mid-statement pause.
Use Show CoCo and Continue to supply input normally.
END, STOP, and runtime errors that return to BASIC finish a step at the OK prompt.
The emulator remains paused; Continue lets the prompt accept commands or a new
editor transfer. Program,
interpreter or mapping changes cancel an active step and detach its source map.
Changes to the editor after a stop also detach debugging as described above.
Step Over observes the qualified interpreter's GOSUB frame push at `$AE9D` and
RETURN pop at `$AEDA`, recording and matching frame addresses instead of guessing
from the stack pointer alone. The input-loop entry at `$AC7C` identifies a return
to the prompt. These routines and the dispatcher are guarded against changes;
CoCo 3's normal boot patch to the preceding OK-print routine is outside the guard.
The [Color BASIC Unravelled](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/color-basic-unravelled.pdf)
GO, RETURN and command-dispatch listings provide the interpreter reference.
## Step Out and runtime errors
**Step Out** runs the current `GOSUB` through its `RETURN`, stopping before the
next mapped statement in the caller. It handles nested and recursive calls and
skips intervening `FOR` frames. Explicit breakpoints still take precedence. The
button is unavailable at top level, in an unrecognized stack, or after a
mid-statement pause. Pause and the same 600-frame execution bound apply.
The caller walk starts at the interpreter's current dispatch return address,
verifies its BSR/JSR instruction, and walks typed 18-byte FOR and five-byte GOSUB
frames within BASIC's RAM bounds. It verifies the saved caller line/pointer
against the attached source, then matches the exact frame at `$AEDA`. A changed
caller frame cancels Step Out. Different DOS command-loop return addresses are
accepted only when their call into the recognized dispatcher is verified.
Run now attaches error observation even without a source breakpoint. It still
runs immediately and never adds a default breakpoint. Unhandled errors finish
the ROM's normal reporting and file cleanup, then pause before keyboard input
at the OK prompt. A banner shows the ROM's actual two-character error code and
source line; **Show Line** selects that numbered source row without modifying it.
This is line-level navigation, not a claim to identify the exact faulty
expression. Values that remain in BASIC can be inspected at this stop.
Choose **Continue** to return to the normal prompt before editing and running a
corrected program. If source edits have already detached debugging, resume the
CoCo from the main window. Continue does not resume the aborted BASIC program.
A new transfer, changed source, reset, or detached source mapping clears the old
error. The last matching error can remain visible after returning to the prompt.
`ON ERR GOTO` remains under the ROM's control. Handled errors do not produce the
unhandled-error banner or an automatic stop; a breakpoint in the handler still
works. Error observation uses the shared `$AC65` reporting path after the error
code has been printed, rather than intercepting every error before the guest
can handle it. The error routines are guarded alongside command dispatch.
The additional interpreter references are the
[Disk BASIC Unravelled command-loop and error-driver listings](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/disk-basic-unravelled.pdf)
and [Super Extended BASIC Unravelled error-trap listings](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/super-extended-basic-unravelled.pdf).
## Variables and watches
The collapsible **Variables and Watches** panel reads the stopped BASIC program's
numeric and string variables, DIM arrays, and DEF FN entries. It refreshes at a
BASIC breakpoint, after statement stepping, and at the stepping stop before the
OK prompt. **Refresh BASIC variables** also rereads a safe stop. Continuing,
editing the source, resetting or detaching debugging clears the displayed values.
An arbitrary CPU pause in the middle of INPUT, expression evaluation or string
collection is not a safe BASIC inspection stop.
Arrays expand into pages of 32 elements. Their displayed bounds are inclusive
and begin at zero; multidimensional indices use the source's order. Strings
preserve case and quote their contents, with nonprinting bytes escaped as
`\xHH`. Numbers decode the interpreter's five-byte floating-point representation.
DEF FN entries are identified but never evaluated.
**Watches** accepts named variables and array elements with literal, nonnegative
subscripts, such as `A`, `NAME$`, or `M(1,2)`. BASIC identifies names by their first
two characters, so `NAME$` appears as `NA$`. Unknown names say **Not assigned**;
unknown arrays say **Not dimensioned**. Wrong subscript counts and out-of-range
indices are reported separately. Watches do not evaluate expressions, functions,
PEEK or assignments and never create a guest variable. Up to 128 watch names are
remembered with the local workspace recovery draft, independently of breakpoints.
Inspection copies normal BASIC RAM on the emulation queue without executing
instructions, modifying memory or accessing device registers. It validates the
qualified interpreter, source/program identity, MMU mapping, variable-table
bounds and array descriptors. Strings whose descriptors point outside ordinary
BASIC RAM are shown as unavailable. A malformed table returns an inspection
error instead of guessed values. Asynchronous results are discarded after the
source, machine generation or stopped execution position changes. This is
read-only inspection; editing values and general expression watches are not
implemented.
## Validation approach
`BASICBridgeTests` runs against optional, ignored
`platforms/macos/LocalResources/ROMs/coco3.rom` and `disk11.rom`. Tests explicitly
skip the ROM integrations if those files are absent; no proprietary ROM bytes are
checked into the repository. Both guest processors are exercised sequentially
because the retained emulator core is process-global.
The key independent oracle enters an authored fixture through the actual ROM's
keyboard/tokenizer, captures the tokenized RAM program, then compares it with a
directly loaded version of the same source. The fixture includes strings,
`DATA`, `REM`, apostrophe remarks, `?`, function tokens, `ELSE`, disk commands and
CoCo 3 commands. Reading that program and reloading the returned source must
produce the same bytes. Other checks cover direct execution without queued
keystrokes, preserved media and machine generation, rejected source preserving
the previous program, and unsupported machines rejecting direct writes. Export
checks cover deterministic DSK/CAS output, paused memory/register preservation,
running-program preservation, invalid source/names and unchanged media and
machine generation. Separate core checks load the exported files through the
actual ROM's `LOAD` and `CLOAD`, including programs crossing disk granules and
cassette data blocks; cassette checks use the normal transport rather than fast
loading.
The BASIC command references maintained by Color Computer Archive are useful
background for command vocabulary and usage:
[Color BASIC, Extended BASIC and Disk BASIC references](https://colorcomputerarchive.com/repo/Documents/BASIC%20Commands/).
Interpreter storage and execution behavior are documented in
[Color BASIC Unravelled](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/color-basic-unravelled.pdf).
The bundled Quick Reference provides original local
explanations and examples. These source links do not imply that the external
manuals are bundled with the workspace.
### Initial validation — November 4, 2026
The 13 focused native tests passed on both Apple Silicon and x86_64 under
Rosetta: five bridge integrations, six editor/language/recovery checks and two
pure core token/validation tests, exercising the final normal-RUN-handler path.
The complete 63-check standalone core suite also passed. There were no failures or
skips. Each real-ROM bridge case exercised both the 6809 and 6309. The original interpreter's typed
program and the directly installed program matched byte for byte; canonical
read-back reloaded to the same representation. Paused Load preserved cycle count,
and immediate Read followed by Run executed successfully. Execution printed the
expected result with no queued paste; disk/tape assignments and machine generation
were unchanged. Invalid/oversized source, active loops, INPUT waits and unsupported
machines were rejected without replacing the previous program.
These original checks use authored isolated machine instances and predate the
line-breakpoint feature. They do not qualify other ROM revisions.
### BASIC line-debugging validation — November 4, 2026
All 40 targeted tests passed on Apple Silicon and x86_64 under Rosetta: ten
BASIC bridge integrations, 19 workspace tests and 11 existing core/native debugger
checks. The BASIC breakpoint cases run on both emulated processors. They verify
stopping before execution, repeated loop stops, Continue without a reset,
subroutine return state and variables, colon statements, coexistence with manual
CPU breakpoints, rejection of mismatched source and invalid line numbers, and
detachment after program-memory edits, PC changes and reset.
The isolated native UI check verifies both gutter clicks and the accessible
insertion-point toggle, Run to a selected line, Continue, unchanged source and
machine generation, disabling Continue after editing, and clearing breakpoints.
The captured window was visually reviewed for gutter alignment and stopped-line
highlighting. That checkpoint covered line-entry debugging; the later sections record
statement stepping and variable inspection. No default breakpoint is installed.
### Statement stepping validation — November 5, 2026
All 50 targeted tests passed on Apple Silicon and x86_64/Rosetta (Apple Silicon
in a 46-test pass plus four final guard/mapping checks): 17 BASIC bridge tests,
20 workspace tests, two tokenization/export core checks and 11 existing debugger
regressions. The new bridge cases exercise both emulated processors. Coverage
includes same-line statements, source order/CRLF and keyword case, FOR/NEXT,
IF/ELSE, nested and recursive GOSUB, ON GOSUB, explicit breakpoint precedence,
return to the OK prompt after END and a runtime error, an INPUT wait canceled
without clearing its program, and the 600-frame bound on a nonreturning call.
Self-modifying BASIC detaches and stops rather than highlighting stale source.
The editor test verifies that moving the token highlight within one line leaves
source text and insertion point unchanged.
The isolated native check passed Step Into, Step Over, same-line token rendering,
Continue after the OK-prompt stop, and pausing an INPUT wait. The existing gutter,
Continue and stale-source UI regression also passed. The final window capture was
visually reviewed; only the app window is retained here. Xcode emitted internal
QoS diagnostics during automated editor lookup; those did not fail the tests,
and this validation does not establish their underlying cause.
## Variables and watches validation — November 5, 2026
All 53 targeted tests passed on Apple Silicon and Intel under Rosetta: 19 BASIC
bridge integrations, 21 workspace checks, two pure core checks and 11 debugger
regressions. Each BASIC bridge test exercises both emulated CPUs. Real-ROM
fixtures independently create numbers (including negative, fractional, large
and small values), mixed-case/empty/binary strings, numeric and string arrays,
and DEF FN entries. The inspector recovers their values and source-order array
indices without changing RAM, cycle counts, program revision or media. Tests
also reject stale source, running/mid-statement inspection and damaged tables.
Synthetic RAM checks cover malformed array ranks, lengths, offsets, variable
pointers and string descriptors pointing at device addresses. Watch checks cover
canonical names, bounds, unknown variables, rejected expressions and recovery.
The final native checks passed array expansion, adding scalar/string/array
watches, value refresh after stepping, clearing values on Continue, and the
existing Step Into/Step Over/INPUT-cancellation workflow. The final asynchronous
stop guard and layout built for both architectures; all 21 workspace tests were
rerun successfully on Apple Silicon. A small disclosure control was replaced by
a full-row accessible array button. The breakpoint ruler now draws and clips its
own separator within the editor, fixing the vertical line previously extending
through the toolbar and footer. Window-only screenshots were visually reviewed.
Xcode still reports its internal QoS warning during UI automation; this pass does
not identify or claim to resolve that separate warning.
## Step Out, runtime-error and preset validation — November 5, 2026
The added real-ROM bridge tests exercise both emulated processors and cover
nested/recursive returns, FOR frames, explicit-breakpoint precedence, stale
source and top-level refusal, division-by-zero, syntax, DATA, type and disk-file
errors, normal ROM error output, and preserved `ON ERR GOTO` behavior.
An isolated test creates the actual Disk BASIC, Hard Drive BASIC and CoCo SDC
preset definitions from private ROMs and authored starter media. Each preset runs
`DIR` against its own mounted storage, transfers and reads back source, stops at
a breakpoint, inspects a scalar and array, steps into/out of a subroutine, and
reports an unhandled error. Optional private `rgbdos.rom` and `sdcdos.rom` are
required for that case. No personal working media are opened or modified.
The native UI test checks Step Out availability, caller return, exact source-row
selection, unchanged source, correcting/re-running after an error, and compact
window controls. The resize regression verifies a real size change and checks
that both the header and full preset guidance stay within the window. The
inspector reduces its visible rows in shorter windows while retaining its own
scrolling. Representative window captures:
- Returned to caller
- Runtime error source navigation
Validation for this stage: 57 selected BASIC/core/debugger tests passed on Apple
Silicon and the same 57 passed on Intel through Rosetta, with no skips. The native
Step Out/error-navigation workflow passed in the isolated app. Both build
architectures compiled. Xcode's App Intents metadata notice and internal test
service/QoS diagnostics are not claimed resolved by this change.
+66
View File
@@ -0,0 +1,66 @@
# Shipped CMOC benchmark decision
> 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.
## Results
All **864 executions passed**: eight CPU workloads, three input seeds, two repeats,
three build profiles, two compiler host slices and three guest processor modes.
Every serialized result byte matched an independent host reference. Repeats had
identical cycle counts; both compiler slices emitted identical guest binaries.
| Comparison | Measured result |
| --- | --- |
| Existing Release versus Debug, MC6809 | 14.17% fewer cycles, equal-workload geometric mean |
| Frame-pointer omission versus Release, MC6809 | 0.69% fewer cycles |
| Frame-pointer omission versus Release, HD6309 emulation | 0.69% fewer cycles |
| Frame-pointer omission versus Release, HD6309 native | 0.84% fewer cycles |
| Omission size savings | About 3% of summed initialized payload bytes; 17–32 bytes per test program |
| Largest MC6809 omission speed gain | About 2.9%, input handling |
These modest additional gains do not justify making CMOC's explicitly experimental
frame-pointer omission option the default. Projects with measured size or speed
pressure can opt in and qualify their own behavior. Debug's frame is intentional
and supports verified locals and caller reconstruction.
## Compiler and method
The exact CMOC 0.1.100 compiler and target runtime came from the retained
notarized **3.6.2 build 55** app. Its compiler bytes matched the installed
app. SHA-256 of universal `libexec/cmoc`:
`c46271d42037420d3f9d294c670f2d6130c469cf6fd2c41ec2338d990e313512`.
The manifest records all three optimizer fixes and debug metadata at version 1.
The different mutable local staging compiler was not used.
No compiler was rebuilt or patched during benchmarking. A stock compiler
comparison was not needed to choose defaults for the shipped compiler; previous
target regressions already establish the correctness need for our fixes.
Profiles were Debug `-O0 -fno-omit-frame-pointer`, existing Release `-O2`, and
Release `-O2 -fomit-frame-pointer`, using generated-project relocation and switch
defaults. Exact breakpoint cycle deltas include the workload call/return and
exclude setup and result collection. Guest IRQ/FIRQ are masked. Three-NOP
calibration passed at 6/6/3 cycles for MC6809, HD6309 emulation/native respectively.
Initialized size includes startup, linked helpers, setup and collection. BSS and
static RAM spans are separate receipt fields; stack/heap reservations are not
included. No host elapsed-time or baseline-subtraction estimate is used.
The fresh arm64 Release core was built through the existing VCCCoreChecks scheme.
The measured core/device inputs matched the reviewed implementation. All 67 shared Release core checks
and four benchmark evidence-accounting checks passed, with no skips. Structured receipts hash the compiler/tools, runtime archives, linked core and
frozen benchmark inputs. Raw logs, binaries and private ROMs stay outside Git.
## Limits
The eight cases cover arithmetic, sprite/collision logic, memory/CRC, sorting/state
dispatch, framebuffer work, sample mixing, indexed input and sector/directory
processing. Device-themed cases use synthetic application buffers; they do not
measure real graphics/audio/input/disk I/O or device-library compatibility. Full
linked test-program size includes harness overhead and is not a game-size forecast.
The x86_64 compiler ran under Rosetta on Apple Silicon. Both guest CPUs were
emulated, and the harness explicitly selected 6309 native mode while retaining
6809 machine code. This is not physical Intel, macOS 14, physical CoCo, whole-game
frame-rate, audible-output, UI or accessibility qualification. No normal app
session or personal media was operated. Complex projects, interrupts and inline
assembly need separate qualification before considering a global omission default.
@@ -0,0 +1,107 @@
# CMOC indexed argument-load qualification
> 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.
## Failure and general correction
A joystick-driven program passed adjacent axis and calibration bytes to one
function. After loading `centers[index + 1]`, CMOC's `removeUselessLdaOrLdb`
peephole rule deleted the reload of `index` before `centers[index]`:
```asm
LDB index
LDX #centers
LDB D,X
```
The last instruction overwrites B only after computing its effective address.
B is the low byte of D, so the first load is required. Without it, the previous
argument's value becomes the subscript. Correct emulator joystick values can
therefore reach incorrect compiled game logic.
The rule also checked the instruction mnemonic instead of its operand for
predecrement/postincrement effects, and recognized only an explicit `B,` prefix
on the intervening X load. The new
[`cmoc-indexed-argument-load.patch`](../../tools/toolchain/patches/cmoc-indexed-argument-load.patch)
uses the compiler's existing `InsEffects.read` analysis on both following
instructions. It preserves B dependencies, including D-indexed and indirect
operands, and uses the existing side-effect predicate on the removed load.
Independent overwritten loads can still be optimized. This is a compiler rule
correction; it does not recognize a game, input API, variable name or source
pattern.
`build.py` applies the patch only to its ignored source copy after the existing
compiler patches. `build-runtime.py` records `vccIndexedArgumentLoadFix: 1`.
The pinned CMOC source and third-party manifests remain unchanged.
## Target-executed regression
The authored [fixture](../../tests/toolchain/indexed-arguments/qualification.c)
passes four actual bytes to a capture function from two arrays, at runtime
indices 0 and 2. It covers byte indices, word indices and pointer bases. Distinct
surrounding sentinels distinguish the stale-index error from legitimate values.
The guest prints raw result bytes; expected values and comparison belong to the
host runner, rather than the optimizer under test.
For each pair of indices, the expected bytes are:
```text
04 0C 08 10 14 1C 18 20
```
The baseline staged compiler passed `-O0` on MC6809 and HD6309 but failed `-O2`
on both. Its byte-index case printed `04 0C 3A 10 14 1C 3A 20`: the sentinel
`3A` replaced the third argument. Retained generated assembly confirmed the
removed reload immediately before `LDB D,X`.
The fixed universal staged compiler passed `-O0` and `-O2` on both emulated
processors through both its arm64 and x86_64 compiler slices: eight executions,
each checking all six calls. All use `--coco --no-relocate --switch=jump`.
The CoCo 3 ROM is an explicitly supplied local input. The x86_64 host compiler
ran under Rosetta on Apple Silicon; no physical Intel or physical CoCo result
is claimed.
Reproduce with a staged runtime and a separately built shared-core library:
```sh
python3 tests/toolchain/indexed-arguments/check.py \
platforms/macos/LocalResources/ToolchainBundle \
/path/to/libVCCCore.a platforms/macos/LocalResources/ROMs/coco3.rom \
--host-arch arm64
python3 tests/toolchain/indexed-arguments/check.py \
platforms/macos/LocalResources/ToolchainBundle \
/path/to/libVCCCore.a platforms/macos/LocalResources/ROMs/coco3.rom \
--host-arch x86_64
```
The regression also runs within `tools/toolchain/check.py --rom`. Its runner
uses temporary output and leaves the app, guest sessions and disk images alone.
## Additional checks and runtime staging
- The focused native [rule check](../../tests/toolchain/indexed-arguments/check-rule.py)
links the actual compiler build objects and checks 13 dependency/side-effect
guards and two safe removals. It covers direct/indirect B and D indexing,
intervening LDX/LEAX dependencies, and direct/indirect index/stack updates.
- Existing indexed-subtraction and logical-negation target regressions pass at
`-O0` and `-O2` on both guest processors with the new compiler.
- The public source-only toolchain build passes; all nine library archive
targets, greeting compile/link, DECB format and known assembler bytes pass.
- Both compiler slices were rebuilt through `tools/toolchain/build.py` with
explicit `--host-arch arm64` and `--host-arch x86_64` and minimum macOS 14.
- `tools/toolchain/verify-runtime.py` passes for that bundle: both complete
architecture build chains, system-only dynamic dependencies, relocated bundle
paths, preprocessor errors, dependency regeneration with spaces/quotes/`#`/`$`,
bundled Perl modules, disk allocation and ROM-backed/standalone disk linking,
with developer tools deliberately unavailable to the bundled workflow.
To run the native rule check after a native `build.py` source build:
```sh
python3 tests/toolchain/indexed-arguments/check-rule.py \
.build/cmoc-indexed-arguments/fixed/work/cmoc
```
@@ -0,0 +1,38 @@
# C development release qualification
> 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.
## Findings during qualification
- Build 6 exposed an outdated locally staged CMOC binary: dependency paths with
quotation marks failed the existing relocation regression, although the current
reviewed compiler source already has the correction. Both host slices were rebuilt
from that source; the relocation regression now passes. Packaging now requires the runtime relocation check before
signing or uploading a candidate.
## Completed November 3, 2026
| Check | Result |
| --- | --- |
| Full XCTest, corrected compiler | 414 passed on arm64 and 414 on x86_64/Rosetta; zero failures or skips. The optional local BASIC printer test was enabled. |
| Release core and private starter checks | All 61 core checks; disk/cassette regeneration, hard-disk BASIC, NitrOS-9 boot/shared HD1, Orchestra-90 and Speech/Sound passed. |
| Hello Disk from bundled template | Fresh source copy; native source edit, Save All, incremental rebuild, disk replacement confirmation, verified breakpoint, C step, Continue, normal quit and saved-source reopening. |
| Exact DMG-installed app | Copied from the read-only mounted DMG to a separate location. Signature and Gatekeeper passed. Reopened saved source, rebuilt with its bundled tools, stopped at `main.c:9`, and ran to disk result `0`, generated count `5`, and all five expected words. |
| CoCo Letters | Fresh recursive Make project built in the installed app; generated dictionary and bootable disk; source locations verified in nine C files. Native DOS boot and RGB/Easy/User selection reached the playable board. Separate core execution checked cursor response, nonzero audio, and unchanged disk bytes on 6809 and 6309 with 128 KB. |
| Installed toolchain relocation | The exact installed payload passed the existing runtime verifier, including both complete host-architecture build chains, unusual paths, dependency regeneration, Perl/modules, disk API linking and unavailable developer tools. Thin test copies are re-signed ad hoc; the original installed app retains Developer ID signatures. |
| Media and workspace protection | Full regression coverage passed for failed/cancelled/clean builds, immutable results, live-media cleanup guards, changed/missing files, interrupted builds, draft recovery and saved tab restoration. |
| Distribution | Universal app and DMG accepted by Apple, stapled, and accepted by Gatekeeper; embedded app, resources, DMG checksum, Applications link and Finder layout verified. |
The native checks used isolated startup storage and separate projects; the normal
emulator and media were not changed. The saved-source reopening was explicit:
the isolated launch intentionally creates fresh preferences each time. Persistent
tab/history/recovery restoration was exercised by the automated model tests.
Native text editing used accessibility text entry because direct synthetic keyboard
events were not delivered reliably to the signed app; keyboard editing/Undo have
separate native regression coverage from the editing milestone.
CoCo Letters is a build/run qualification fixture, not a bundled game. Its default
selected breakpoint was `waitTicks` at line 85, which this short play sequence did
not reach; its pending source attachment is not counted as a debugger pass.
Hello Disk and the two-CPU source/debugger tests provide that qualification.
Optimized game locals remain subject to the documented debugger limits.
+79
View File
@@ -0,0 +1,79 @@
# Self-contained CMOC runtime
> 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.
## Runtime contract
| Tool or directory | Purpose |
| --- | --- |
| `bin/make` | GNU Make 4.4.1: ordinary, recursive, incremental and parallel Makefile builds. |
| `bin/cmoc`, `libexec/cmoc` | Relocatable wrapper/native CMOC 0.1.100 compiler. |
| `bin/cpp`, `bin/mcpp` | Native CMOC adapter and mcpp 2.7.2 preprocessor. |
| `bin/lwasm`, `bin/lwlink`, `bin/lwar` | LWTools 4.25 assembler, linker and archive tool. |
| `bin/writecocofile` | CMOC's native disk-image insertion utility. |
| `bin/perl` | Universal launcher for bundled Perl 5.44.0 and its matching core modules. |
| `bin/install-coco-boot-loader` | Relocatable wrapper running the unchanged upstream loader script with bundled Perl. |
| `share/cmoc` | Target headers/runtime and optional library archives. |
| `libexec/perl/<architecture>` | Independent relocatable interpreter/core-module installation; architecture-specific `Config.pm` and XS modules stay paired. |
| `LICENSES`, `manifest.json` | Retained upstream notices, tool versions, library hashes and native-helper architecture inventory. |
The app selects bundled tools first on PATH and removes inherited Make/Perl overrides. Project recipes may intentionally set their own variables. Makefiles still run ordinary commands: a recipe requiring an additional host compiler, third-party command, GNU-specific tar option or non-core Perl package must supply that dependency. “Full Make” does not imply every possible program a Make recipe can call is bundled. We do not download CPAN packages or provide a host C/XS development SDK.
The compiler wrapper creates a temporary space-free alias for target headers/libraries because upstream CMOC builds some assembler/linker commands through a shell. Application and project-directory names containing spaces work. Keep individual source and product filenames simple relative names; arbitrary shell metacharacters/spaces inside those individual names remain an upstream limitation.
The maintained `cmoc-make-dependencies.patch` escapes generated Make dependency targets/prerequisites and decodes quoted preprocessor paths in both CMOC readers. The adapter quotes raw path characters emitted by mcpp. This covers real SDK header paths inside a relocated `VCC Plus.app`, including parent directories containing spaces, quotes, `#` and `$`. `verify-runtime.py` exercises both `--deps-only` and `--deps`, automatic inclusion/regeneration, changed-header rebuilding and no-op builds on both architectures.
The bundled CMOC 0.1.100 optimizer preserves accumulator-indexed addresses when simplifying byte subtraction and comparisons. The runtime manifest records `vccIndexedByteSubtractionFix: 1`. The change takes effect when a project is recompiled. [Compiler patch and regression](../../tools/toolchain/patches/README.md)
The runtime manifest records `vccAddZeroFlagsFix: 1` for correct logical negation of integer results at `-O2`. Recompile existing guest programs to pick up the fix. [Logical negation regression](../../tools/toolchain/patches/README.md)
App staging adds a deterministic payload hash to the installed manifest. Workspace caches therefore invalidate when the compiler, helpers or headers change, even with the same upstream version.
Native project builds pass `MAKE=make` with the bundled tools first on PATH. This keeps recursive `$(MAKE)` recipes working when the actual application path contains spaces. The runtime regression includes a recursive child Makefile.
### Scoped inline-assembly preprocessing
Ordinary C uses mcpp's standard conforming preprocessing. If explicit `asm { ... }` blocks occur, the adapter obtains a second expansion in mcpp's documented assembler mode and substitutes only those balanced assembly bodies. This preserves immediate/indexed operands such as `#COUNT` and `-COUNT,x` without changing ordinary C token boundaries, string literals, macro stringizing or preprocessing errors. Both passes must identify matching block counts; an incomplete or inconsistent block fails rather than compiling a truncated transformation. Source line markers are retained and translated to CMOC's expected syntax.
The adapter does not globally enable assembler mode or LWASM `newsource`. Five regressions cover assembly macro operands, multiple blocks/include markers, unchanged C/string behavior, invalid C token-paste rejection, error line numbers and actual generated 6809 immediate bytes.
## Included target libraries
The standalone compiler now builds all nine reviewed library archive targets. The installed public runtime includes the following headers/archives; add the relevant `-l` option to the project's Makefile rather than automatically linking everything.
| Library | Link option | Upstream terms |
| --- | --- | --- |
| BGraph | `-lbgraph` | Public domain, original acknowledgments retained. |
| BSound | `-lbsound` | Public domain. |
| BControl | `-lbcontrol` | Public domain. |
| CardGame | `-lcardgame` | Public domain. |
| HiresTxt | `-lhirestxt` | Public domain. |
| AStar | `-lastar` | Public domain. |
| WydeAlloc | `-lwydealloc` | GPL-3.0-or-later. |
| Ebitor | `-lebitor` | GPL-3.0-or-later. |
| VCC Plus Speech/Sound | `-lssc` | GPL-3.0-or-later. Requires Speech/Sound for audible output. |
| VCC Plus Orchestra-90 | `-lorch90` | GPL-3.0-or-later. Stereo DAC access works with the optional composer ROM omitted. |
| VCC Plus GIME graphics | `-lgime` | GPL-3.0-or-later. Two 320 × 192, 16-color pages on a CoCo 3. |
| VCC Plus joystick input | `-linput -lbcontrol` | GPL-3.0-or-later wrapper over public-domain BControl. Samples one CoCo port per call. |
| VCC Plus C compatibility subset | `-lvcccompat` | GPL-3.0-or-later. In a custom Makefile, also set `export VCC_CMOC_COMPAT = 1` to activate its headers. |
| decbfile ROM-backed core | `-ldecbfile` | Public domain; subset described below. |
`tools/toolchain/stage-libraries.py` builds eight optional libraries from unchanged source copies with the bundled compiler and unusable Apple SDK settings. Header names, archive bytes and upstream notices are recorded in the runtime. GPL library linking carries its own obligations; compiler licensing does not automatically determine the license of an otherwise independent user program.
## Validation
```sh
python3 tools/toolchain/verify-sources.py
python3 tests/toolchain/test_cpp_adapter.py
python3 tools/toolchain/verify-runtime.py platforms/macos/LocalResources/ToolchainBundle
```
Runtime verification audits all native helpers for architecture slices and system-only dependencies, relocates the whole payload into a path with spaces, and compiles through bundled Make with invalid Apple developer-directory/SDK settings. It repeats with separately thinned Apple Silicon/Intel helper tools, exercises bundled Perl's Getopt::Long and Digest::SHA XS module, and checks the boot-loader wrapper. Deliberate preprocessing failure must stop Make with the correct line number. Intel execution on Apple Silicon uses Rosetta.
November 3, 2026: all nine library archive builds passed without the SDK preprocessor. The original CoCo Letters project built its 161,280-byte disk using the bundled compiler, interpreter and asset/boot helpers. Full Apple Silicon and separately thinned Intel builds produced identical disk bytes (SHA-256 `da81baceb20967be2822a353ae64369eda7e830102b21a0127052d04fead1470`); a no-op Make and clean parallel rebuild also passed. Its disk booted on both emulated CPUs with 128 KB; title, RGB/Easy/User selection, cursor response, 90,624 read events, zero writes and 2,040 nonzero audio samples passed. This is a smoke test, not exhaustive gameplay qualification.
Perl is dual-licensed GPL-1.0-or-later / Artistic-1.0-Perl; retained component notices include the bzip2 BSD-style license. mcpp is BSD-2-Clause. GNU Make's executable is GPL-3.0-or-later; its separate manual retains GFDL terms. Exact source snapshots, upstream notices and hashes are in `third_party/`. No private input is needed to reproduce the public toolchain.
## C debug metadata
The local [CMOC debug extension](../../tools/toolchain/patches/README.md) is applied to compiler build copies, leaving the pinned upstream snapshot unchanged. Compiling with `-fno-omit-frame-pointer` emits versioned type/scope/storage metadata; unoptimized preserved frames enable locals. The IDE verifies it against the same linked artifacts used for C source mapping. See [C source debugging](CMOC_SOURCE_DEBUGGING.md) for capabilities and limits.
+135
View File
@@ -0,0 +1,135 @@
# C source debugging
> 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.
VCC Plus extends the existing CMOC workspace with source-line stepping, verified C call stacks and read-only variable inspection. The source editor, debugger and live CoCo use the same machine; changing inspector tabs never reloads or resets it.
## Stepping
Build a project, then run to a verified source breakpoint. **C Step Into** advances to the next mapped source line, entering functions whose source is available. **Over** completes the current line without stopping inside called functions, except at an existing breakpoint. **Out** finishes the current function and stops at its actual return address; the caller may still be completing the original call expression. **Instruction** remains available for assembly-level work.
Mapping is by file and line, not individual statements or columns. Several statements on one line cannot be stepped separately. A one-line loop stops on a new iteration. Unmapped library code is executed normally; returning into unmapped code shows the assembly fallback. Existing user breakpoints take precedence. Pause cancels a pending step. Instruction, frame and call-depth limits prevent an unbounded step; the stop reason explains why execution paused. Interrupts and 6309 TFM block transfers retain their normal guest behavior.
Every step checks the paused machine generation, program revision, MMU mapping, PC and verified instruction bytes on the emulation queue. Flat programs retain their original effective-MMU fingerprint throughout a step. A reset, debugger memory edit, changed source, different build or incompatible mapping requires reconnecting the build. Changed executable bytes are not silently treated as the original C program.
## Banked programs
Custom Make projects can supply a verified banked debug manifest alongside their build outputs. This associates the delivered program with its original linker output, source/object/listing identities, complete relocated code sections and explicit logical-to-physical RAM page assignments. See [the MCP banked-development contract](MCP_BANKED_PLAYTEST.md) for the manifest and installed-app workflow. A packed or overlapping binary alone is insufficient to reconstruct those associations.
Different modules may occupy the same CoCo address at different times. The debugger identifies a module by its actual installed RAM pages and complete expected executable bytes, including assembly code outside mapped C lines. Identical opcodes in a loader or another physical page do not establish source identity. ROM overlays do not count as mapped RAM. Overlapping modules must have mutually exclusive page assignments; ambiguous simultaneous claims are rejected.
Arming disk-source stops pauses only to configure the debugger; it does not copy code into RAM, change PC or reset the machine. Normal DOS/LOADM execution installs the program. A source stop becomes eligible when its own module is mapped and matches its verified code. Other overlays need not be mapped simultaneously. Manual debugger breakpoints remain independent and can still stop in unmatched code.
The attachment survives expected bank switches. Each paused source location, call stack and variable view uses the currently mapped modules from the same immutable machine snapshot. A bank-aware source step checks the initial paused fingerprint to reject stale commands, then follows declared page switches and selects the matching module at each mapped instruction. A wrong bank or changed module code stops the step with an explanation. The ordinary flat-program fingerprint rules remain unchanged.
Bank awareness does not recover optimized locals or create a frame convention. Compiler-described globals can be inspected where their storage is currently mapped and verified; unavailable overlay storage remains unavailable. Caller reconstruction still requires the supported, verified U-frame convention and stops at unsupported assembly, optimized or unmapped boundaries. An address by itself does not identify a module, and the debugger does not switch guest banks merely to inspect a value.
### Verified function-entry stops over MCP
For an owned playtest, a banked project can expose executable function symbols
in addition to mapped C statements. `get_build.source_debugging.functions`
contains unique names with a mapped C body instruction; `function_entries`
contains unique compiler symbols whose full entry-to-end range is covered by
verified executable guards and physical page assignments. Data/BSS symbols,
ambiguous names and incomplete executable ranges do not become entry stops.
Select `stop_kind: "function_entry"` with the advertised name when starting an
owned run or arming `playtest_debug`'s `stop_at` action. This can stop in an
assembly input sampler or a verified prologue before its first C statement.
At a pure assembly stop, `source_stop` remains null and `function_stop` identifies
the actual symbol, entry/current address, module, physical RAM and declaration
location. The declaration line is not an executing C statement. Subsequent
instruction steps report `assembly_instruction` where no mapped C line exists.
A C source stop can also include the enclosing verified function identity.
The runtime uses the same immutable snapshot and complete module-code checks
for these observations. It does not guess locals, unwind an unsupported frame,
execute an expression or switch guest banks. Owned MCP snapshots expose
registers, verified shared globals, locally configured named watches and bounded
readable ranges. Native C source stepping and the native assembly debugger retain
their existing controls. See [the owned-playtest contract](MCP_BANKED_PLAYTEST.md)
for selection, input and retained-disk behavior.
## Call stacks and caller inspection
Choose **Call Stack** in the lower inspector while paused in a verified C build. The innermost function is first; recursive invocations appear as separate frames. Selecting a supported caller opens its source at the call site and makes **Variables** and **Watches** use that invocation's parameters and locals. Return to the first frame to inspect the paused function again.
Frame selection is inspection only: it does not change PC, registers, guest memory or execution. **Into**, **Over**, **Out** and **Instruction** always operate on the actual paused execution point, even while viewing a caller. The editor distinguishes the selected caller from the execution location. Values come from the current paused memory snapshot, not a historical copy taken when the call occurred; globals and objects reached through pointers can reflect changes made by the callee.
The unwinder supports the ordinary, unoptimized CMOC calling convention with a preserved U frame. It verifies compiled code, frame layout, readable stack links and the direct call instruction associated with each saved return address. Source scope is the caller's call site, not an arbitrary instruction near its return address. Unavailable or ambiguous links stop the stack with an explanation rather than searching memory for plausible return addresses. Interrupt handlers, assembly/optimized frames, indirect calls, nonstandard prologues and unmapped runtime/library callers can therefore leave a partial stack. A partial stack is not a claim that execution started at the oldest displayed function.
## Variables and watches
Choose **Variables** in the lower inspector to see compiler-described globals, parameters and locals in the selected frame's scope. Choose **Watches**, enter an expression and press Return or **Add Watch**. Watch expressions are remembered per project; removing one does not alter guest memory. Values are refreshed from a single paused PC/register/memory snapshot and disappear when the program runs or its source identity becomes invalid.
Supported values include signed/unsigned integers, pointers, arrays and structures/unions. Expand an array or aggregate in **Variables** or **Watches** to browse its elements and members. Pointers show their address first; expanding one explicitly inspects its pointed-to value. Nested values use the selected call-stack frame and the same paused memory snapshot as their parent. Scope and shadowing come from compiler metadata rather than parsing editor text.
Expansion is read-only. Variables and container children are shown in pages of up to 32 entries; the visible tree is capped at 255 rows and traversal at 12 levels. Pointer cycles stop with an explanation instead of expanding repeatedly. Unsupported children remain individually unavailable so other members can still be inspected. Null pointers, unavailable memory and unsupported pointed-to types produce explanations; a pointer does not imply an array length or an allocation guarantee. A pointer may refer to readable memory that is no longer a live C object.
Expressions such as `values[2]`, `player.x`, `pointer->field`, `*pointer` or `&score` remain available when a focused watch is more useful than browsing. Expansion never executes a getter or guest function, writes memory, or reads hardware I/O. Open branches stay stable while the same paused snapshot refreshes. Changing frames, advancing execution or invalidating the build clears expansion state so a previous frame’s tree cannot be mistaken for the new context.
Expressions support integer literals, arithmetic, comparison, bitwise and logical operators. Calculated results use **checked 64-bit watch integers**, not CMOC's target integer-promotion or overflow rules; stored variables retain their declared target types. Function calls, assignments, increment/decrement, casts, floating-point literals and floating-point watch arithmetic/comparisons are not supported. Stored floating-point values are supported as described below. Hardware I/O and unavailable memory are never read through live device ports. Unsupported values produce an explanation, not a guessed number.
### Floating-point values
Variables, array elements, structure/union fields, pointer targets and direct watches now display compiler-described floating-point values, including parameters and locals from a verified caller frame. Rebuild existing projects with the updated bundled compiler: older debug metadata does not identify the format and reports that a rebuild is needed. The app never guesses the format from the current ROM, type name or storage size alone.
The supported encodings are CoCo BASIC's packed five-byte format (also used by CMOC's native float option) and big-endian IEEE binary32 selected by `--mc6839`. The compiler records the encoding in each floating type, including nested types. Unknown formats and genuine unsupported double-precision layouts remain unavailable. CMOC 0.1.100 treats the C spelling `double` as an alias for `float`; that spelling does not add precision.
BASIC values retain their 32-bit significand and display up to 11 significant decimal digits; IEEE binary32 displays up to 9. Scientific notation handles very small/large values, and IEEE signed zero, subnormals, infinities and NaNs are recognized. The decimal display reflects the stored approximation: for example, CMOC's BASIC-format `0.1f` displays as `0.099999999977`. This is not evidence of a failed calculation. Inspection uses only the existing paused memory snapshot and never calls guest floating-point routines. Arithmetic in watches remains integer-only.
This decoder does not install additional float runtimes or bundle Motorola's ROM. The BASIC-backed runtime was qualified by running actual arithmetic on both guest CPUs. The native and MC6839 encodings were qualified from real compiler output and synthetic format-boundary tests; executing those optional math runtimes is outside this change.
Generated Debug Makefiles and the Hello World/Hello Disk templates preserve the frame pointer. Existing custom Makefiles can opt in with `-O0 -fno-omit-frame-pointer --intermediate` on C compilation. Rebuild with the bundled VCC Plus compiler. Locals require both unoptimized code and the preserved U frame; optimized locals are unavailable. Existing projects are never rewritten automatically. Use Project Settings to preview and explicitly regenerate a generated Makefile when desired.
The compiler extension is a maintained GPL patch applied to a build copy. Pinned upstream sources remain pristine. Versioned type/storage/scope comments and zero-byte labels are associated with the exact object, listing, linker map, source snapshots and executable. See [the patch contract](../../tools/toolchain/patches/README.md). Ordinary builds without the debug-frame option retain their prior compiler output.
## Remaining limits
- No editable C variables or semantic refactoring yet. Identifier completion and parameter hints are available as separate source-based editor assistance.
- Inline assembly and optimized-away or ambiguous C locations retain the native assembly fallback. Verified executable function entries are separately available for owned MCP playtests; they do not create C statement locations.
- Caller inspection is limited to verified frame chains. Unsupported links stop reconstruction; there is no speculative stack scanning.
- Source-line stepping does not imply statement-level precision.
- API-level documentation and online help remain a separate project.
## Validation
Verified November 3, 2026:
- Full `VCCCoreChecks` suite on Apple Silicon and Intel: **348 tests per architecture, 347 passed, one optional local BASIC-printer ROM test skipped, zero failures**.
- Universal Debug and Release application builds passed. No source warnings; Xcode emits its existing non-actionable AppIntents metadata notice because this app does not use AppIntents.
- Core regression coverage includes both guest processors, nested calls/returns, interrupts, one-line loops, permanent breakpoints, cancellation, stale program identity, bounded execution and 6309 TFM transfers.
- Actual compiled two-file programs verify Into/Over/Out, recursive frames, lexical shadowing, integer/array/pointer/structure values, mutation and I/O rejection, and invalidated executable bytes. Metadata coverage also keeps the incremental build workspace alive to exercise macOS temporary-path aliases.
- The native app built and ran a two-file C project to a source breakpoint, stepped into its helper, displayed `value = 2`, `local = 7`, `score = 5` and `values = [11, 22, 33]`, evaluated `values[1] + local` to **29**, and returned to the caller. The watch correctly reported `local` unavailable after leaving its scope. Keyboard entry remained in the watch field.
- Call-stack tests recover six real frames across two source files on both guest processors, including recursive arguments/locals and odd-byte frame alignment. They reject corrupt, unavailable, stale-code, unverified-prologue, optimized and interrupt boundaries and enforce a depth limit.
- The development-model regression verifies that selecting a caller changes its source navigation and values without changing PC, registers, cycles or memory. Polling preserves the selection; changed source hides stale frames and stepping returns inspection to frame zero.
- Native Call Stack review showed `recurse` × 4, `wrapper`, and `main`. Selecting `wrapper` displayed `value = 7`, `local = 12`, and `byteLocal = 42`. The recursive caller watch `n + local` evaluated to **12**; stepping advanced the actual leaf and restored frame zero, where the watch was **10**. The frame picker stayed open across refreshes, and controls remained usable at 900 × 650 points.
- Seven additional tree tests cover typed child paths, two-page arrays, nested structures/unions, explicit pointer traversal, unavailable siblings, null/I/O/cycle/depth errors, stale code, and owned snapshot buffers. The compiled two-file fixture checks current/caller values on both guest processors and proves registers, cycles and memory remain unchanged. The model regression also checks root paging, the visible-row limit and expansion identity across refresh/frame/step changes.
- Native tree review displayed `local.point = {x: -17, y: 21}` and the same object through `local.pointer`, then caller `bag.point = {x: -7, y: 11}`. Array paging advanced to `bag.samples[32] = 132`; stepping restored frame zero and made caller-only watches unavailable. The compact Watches pane now reserves space for its frame picker, entry field and scrollable values at 900 × 650 points.
- Eight new floating-point tests cover compiler encoding tags and constant bytes for BASIC/native/MC6839, missing/unknown/inconsistent metadata, precision boundaries, IEEE subnormals/special values, memory/I/O/stale-code rejection and explicit arithmetic rejection. The real two-file program performs BASIC-backed addition and multiplication on both guest processors, then verifies globals, parameters, locals, arrays, members, pointers and caller values without changing guest state.
- Native floating-point review displayed `input = -6.25`, `local = -5.75`, `globalResult = 3.75`, and caller `measurements.x = 1.25`. Expanded array values and direct pointer watches worked; stepping restored frame zero. The revised compiler is staged for both host architectures, and ordinary optimized object bytes remain unchanged.
- Pinned upstream source hashes remain unchanged; the compiler extension is reproducible from the committed patch. The normal emulator session and user media were not used for these checks.
These are captures of the running native application, not mockups:
Caller watch capture · Compact window capture
Compact variable-inspector layout
Expanded floating-point caller watch
+60
View File
@@ -0,0 +1,60 @@
# Disposable guest audio capture
> 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.
A newly exported C connection
uses toolset 7. `capture_playtest_audio` requires both the native **Allow
Disposable Playtests** permission and the exported `playtestAudio: true` flag.
Older grants retain their advertised tools. No microphone permission is used.
```json
{
"name": "capture_playtest_audio",
"arguments": {"run_id": "<owned run>", "request_id": "tone-01", "fields": 60}
}
```
The operation releases held keys, drains earlier audio, resumes the owned guest
and advances at most the requested **1–120 emulated fields**, then pauses it.
An armed verified breakpoint can shorten the interval; `completed` reports that
case. It does not record wall-clock playback or the personal emulator session.
For a sound triggered by a key, use ordinary `playtest_input` first and then
capture the following interval. That preceding input's audio is deliberately
outside the clip. Framebuffer capture remains a separate nonadvancing operation.
The result contains one standard MCP `audio` content block with `mimeType:
"audio/wav"`. Text and structured metadata omit the base64 payload. The WAV is
uncompressed 44,100 Hz stereo, signed 16-bit little-endian PCM from the emulator's
normal audio output, before host volume or playback. No filtering or synthetic
silence is added. A constant DAC level can be silent with a DC offset; analyze
variation or centered RMS rather than requiring all-zero samples.
The receipt binds the clip to `run_id`, `project_id`, `revision`, `artifact_id`
and `boot`. Its `audio` object reports encoding, sample rate, channels, bit depth,
`sample_frames` (stereo pairs), `sample_count` (interleaved scalar samples), WAV
byte count and SHA-256. `field_start`, `field_end`, `fields_requested`,
`fields_advanced`, `cycles_start` and `cycles_end` describe the actual guest
interval; `advances_execution: true` makes the timing effect explicit.
Reuse an identical request ID and plan after a transport retry: it returns the
original bytes and interval without advancing again. Changing its plan is a
conflict. A retry after a cold restart still identifies the original clip's boot;
a new clip has the new boot number. Revoked or incompatible runs cannot replay
their clips through a stale grant.
Each clip is limited to 131,072 stereo sample frames (524,332 WAV bytes). A run
retains at most 16 unique audio requests and 4 MiB of WAV bytes across all its
boots. Before a new request, enough byte allowance must remain for a maximum
clip. Retried receipts consume no additional allowance. Existing emulated-field,
boot and 1,024 mutation-request limits also apply. Receipts expose remaining
audio and mutation budgets. No audio files are automatically written to a project
or published to a server.
`stop_playtest` is exempt from execution/audio request budgets and retains its
usual ownership, request-conflict, disk-preservation and retry safeguards. Even
after the execution ledger is full, an assistant can stop and retain its owned
worker. This exemption does not authorize another input, step or restart.
See [verified debugging and diagnostics](MCP_DEBUG_EVIDENCE.md),
[owned playtests](MCP_BANKED_PLAYTEST.md) and
[project refresh](MCP_PROJECT_RELIABILITY.md) for related contracts.
+376
View File
@@ -0,0 +1,376 @@
# 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.
@@ -0,0 +1,29 @@
# MCP processor selection — build 45
> 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.
## Contract and focused qualification
[Processor selection](MCP_PLAYTEST_PROCESSORS.md) documents toolset 8's optional
canonical CPU, MC6809 default, normalized retry identity, actual CPU/mode/MD
reporting and 6309-only debugger registers. CPU selection is fixed for the run;
guest code controls native mode. Existing ownership, executable guards, bank
checks, budgets, keyboard release and retained-media protections remain intact.
- **107 selected XCTest cases passed per host architecture**, arm64 and x86_64
under Rosetta, with zero failures or skips. Suites: `CMOCBuildServiceTests`,
`CMOCVariableDebugTests`, `MCPPlaytestTests` through the VCCMac scheme.
- Real 512 KB guests exercised both CPUs: artifact/global bytes, verified flat
stops, frame/audio metadata, bounded input, retries, cold restart and retention.
A separate authored 6309 guest executed LDW/TFR and LDMD, exposing actual
E/F/W/V/MD values and native mode; a pre-LDMD stop after cold restart proved
MD zero and emulation mode. No host memory/register writes manufactured it.
- Native and Intel/Rosetta helper protocol regressions passed, including toolsets
5/7/8, absent or malformed processor permission, canonical selectors and invalid values.
- The reusable public acceptance fixture/script is checked in. Its new guest
N command compiles with the installed toolchain and executes LDMD only when
deliberately entered in an HD6309 run. Compiler `volatile` support remains
absent and is reported honestly; qualification uses actual observed bytes.
+118
View File
@@ -0,0 +1,118 @@
# Owned playtest call context
> 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.
## Access and timing
The tool requires toolset 10 or newer and explicit boolean `playtest` and
`playtestCallContext` fields in the private grant. BASIC, assembly, legacy grants
and ordinary shared runs do not gain access. Native export records the current
consent; editing client-side grant fields cannot enlarge the app's permission.
The consent explains the bounded stack inspection.
First pause at a verified stop in an owned disposable guest, then obtain its
immutable snapshot:
```json
{"name":"get_debug_snapshot","arguments":{"run_id":"<owned run>"}}
```
Use the returned IDs without adding an address, length or expression:
```json
{"name":"get_call_context","arguments":{"run_id":"<owned run>","snapshot_id":"<snapshot>"}}
```
The app checks the connection, project, revision, artifact and owned worker.
It captures the worker without advancing it and requires the same boot, field
clock, frame, cycles, generation, processor/mode/MD, registers, mapping,
program revision, complete memory and availability mask. A step, resume, restart,
new snapshot, disk exchange, rebuild, source change or revocation invalidates old context.
Request-budget bookkeeping is not guest state and does not invalidate a read.
Repeated reads of an unchanged snapshot return the same context.
## Bounded raw view
`status: "available"` supplies `stack_window` with exactly 64 bytes starting at
actual register **S**. It includes byte values, big-endian `words_be` with offsets
and addresses, and the physical RAM spans backing the logical window. Every
byte must be available RAM. ROM, unavailable pages, protected high memory,
wrapping ranges and unverified program locations fail closed.
`interpretation: "uninterpreted"` is deliberate: words can be saved registers,
locals, padding or arguments. Do not call an arbitrary stack word a return
address or a C value. The caller cannot choose another address, increase the
window, dereference a pointer, evaluate a guest expression or modify state.
This tool does not add stack ranges to `read_debug_memory`, whose existing
advertised ranges remain unchanged.
## Evidence-gated interpretations
`caller` and `arguments` have their own availability status, independent of the
raw view. A verified source location alone does not prove a call frame.
Caller interpretation requires compiler function metadata and verified normal
CMOC preserved-U prologue/epilogue bytes. At exact entry it uses the two bytes at
S; in a mapped body it uses U+2 only when the complete saved-frame/return slot is
inside the same 64-byte window. The return value must match one unique verified
direct call instruction targeting this callee, in approved caller source and
verified live code. There is no scan for plausible return addresses, speculative
unwinding, indirect-call guess or interrupt/tail-call assumption.
Integer argument values require compiler-provided positive frame offsets and
full-function scope, that normal ABI proof and a verified direct caller. Only
nonoverlapping, named integer locations wholly inside the same window are
interpreted. Unsupported types, pointers/aggregates, unknown or optimized frames,
missing metadata, ambiguous callers and locations outside the window stay
unavailable. No pointed-to storage is read.
`recorded_parameter_count` counts eligible compiler location records;
`all_recorded_parameters_available` states whether all those records were
interpreted. It does not prove that metadata contains the function's complete
prototype or all runtime arguments. Each interpreted item carries its location,
byte count and evidence label.
For an optimized/source-only entry, the raw view can still help an assistant
compare the stop with the project's own assembly emitted through its approved
Make diagnostic and `get_build_log`. Such analysis must distinguish observations
from inferred ABI meaning; the app does not manufacture typed arguments.
## Qualification
Focused authored helper tests cover safe bounds, RAM/bank identity, proven entry
and body cases, unsupported frames, ambiguous calls, stale metadata and types.
The public-helper harness checks fresh/legacy/forged grant discovery and dispatch,
strict two-ID arguments and unavailable results. Real worker and authenticated
host-boundary checks are recorded below. Private ROMs/toolchain and temporary
results remain outside Git; missing inputs are explicit skips.
### Executed checks — November 12, 2026
- Ten authored helper tests passed on arm64 and x86_64: bounds, unavailable RAM,
bank/source identity, entry and body interpretation, signed integer widths,
unsupported frames/types, ambiguous callers, stale metadata and overlaps.
- Five debugger inspection tests passed on both architectures, including the
semantic fingerprint regression and existing BASIC, assembly and C inspection.
- The real authenticated native C-grant test passed on both architectures. A
compiled seven-argument fixture exercised build, owned startup, snapshot and
context requests over the actual local transport. Wrong run/snapshot IDs,
extra address arguments, stepping/rebuild staleness, revocation and unapproved
or forged client grants were rejected. A non-owned run ID was rejected; this
test did not launch a separate ordinary shared run.
- A real 512 KB worker fixture passed on MC6809, HD6309 emulation mode and HD6309
native mode on both host architectures. Ordinary guest instructions created
the call/arguments. Repeated inspection preserved the complete captured guest
state; inspected and uninspected twins subsequently produced identical,
nonconstant guest PCM. Return, restart and retained-disk bytes also matched.
No host memory/register injection was used to create the call or its values.
- The public helper's complete protocol harness passed with both arm64 and
x86_64 helpers, including 23 fresh/legacy/malformed/forged grant variants,
strict two-ID schema validation and unavailable-result forwarding.
The x86_64 test bundle and worker were verified as thin Intel binaries and ran
through Rosetta on Apple Silicon. This is not physical Intel or macOS 14
qualification.
+137
View File
@@ -0,0 +1,137 @@
# Verified custom-Make debugging through MCP
> 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.
## Read the build evidence first
Every completed executable build now reports `source_debugging` in `get_build`,
including ordinary custom-Make builds without a banked manifest. Successful
compilation and verified debugging are separate results:
- `verified` means the executable/source map and compiler type metadata passed
verification. `source_only` means executable evidence passed but typed C
metadata is unavailable; `reason` explains why. `unavailable` identifies an
executable, map, object, listing or source verification failure.
- `c_line_stops` lists actual compiler-mapped statements, with shared source path,
line, logical address and declared bank identity where applicable. `functions`
names only unique functions with a verified C statement inside their body.
- `function_entries` names verified executable entries, including supported
assembly/prologue entries. An entry stop does not establish a C statement or
stack-frame layout. `function_details` distinguishes a declaration from an
available C stop and explains missing C statements.
- `globals` lists shared file/global declarations, their verified type/storage
and module identity. These are declarations, not guessed runtime values.
Unsupported storage/type layouts are explicitly unavailable.
- Binary/link-map hashes, load entry, module page assignments and
`owned_stop_evidence` identify the exact build. Every catalog includes total
and truncation fields and is bounded by its encoded size.
Ordinary flat custom Makefiles must retain the matching binary, linker `.map`,
linked project `.o`, assembler `.lst` and source snapshots. Keep CMOC
`--intermediate` enabled when compiling and linking. The bundled compiler emits
its `VCCDBG1` type/storage records; retaining compiler-generated `.s` permits
verification of records too long for an assembler listing row. A useful Debug
compile uses `-O0 -fno-omit-frame-pointer`; optimized builds can legitimately
have fewer C statements or unavailable locals. No user Makefile is rewritten
merely to provide debugger metadata.
For example, a normal recipe can compile and link with:
```make
obj/main.o: main.c
@mkdir -p obj
"$(CMOC)" --coco -O0 -fno-omit-frame-pointer --intermediate --intdir=obj -c -o $@ $<
program.bin: obj/main.o
"$(CMOC)" --coco --intermediate --org=2800 -o $@ obj/main.o
```
This fragment only illustrates retained evidence; disk construction and launch
commands remain the project's declared recipe. Packed, relocated or bank-switched
programs must supply the public version-1 [banked debug manifest](MCP_BANKED_PLAYTEST.md).
Its hashes, unpacked images, section ownership and actual physical page identities
are required. It never falls back to a flat interpretation after verification
fails.
## Stop and inspect the owned guest
With an approved disposable-playtest connection, build the current revision and
use an advertised `functions` name as `stop_function` in `start_playtest`, or
`function_entries` with `stop_kind: "function_entry"`. Poll asynchronous startup
with `get_run`. Later `playtest_debug` with `action: "stop_at"` accepts the same
verified name/stop kind. Neither call accepts an arbitrary stop address.
Ordinary flat builds use the existing native guarded-breakpoint path. Complete
object-relocated executable bytes must match before the first named stop can
attach; the actual worker's mapping fingerprint is retained. No assumed stock
physical pages are substituted. Continuing can remove selected stops while
retaining the exact same code/mapping identity. A changed mapping or executable
byte makes the old attachment unavailable. An empty inspection selection alone
cannot establish an initial attachment.
At the verified paused state, `get_debug_snapshot` reports registers, honest
stop kind, source/function entry where known, actual physical pages/mapping
fingerprint and bounded `globals` values from the same safe memory capture.
A global outside the readable stopped mapping has an `unavailable` reason.
Unshared declarations are omitted. C frame locals remain unavailable at owned
entry/instruction stops; no frame is inferred from U or a guessed prologue.
Locally configured watches retain their existing rules.
`read_debug_memory` accepts only ranges advertised by that immutable snapshot,
up to 256 bytes. Resume, input, step, restart, source/artifact changes and
connection revocation invalidate the applicable observation. Inspection performs
no guest expressions, register writes, memory writes or side-effecting I/O reads.
A mismatched binary, object relocation, source identity or bank cannot produce a
verified snapshot merely because a requested function name exists.
For diagnostics and paged compiler output, use `get_build` and `get_build_log`;
those receipts are independent of whether source debugging is available.
## Diagnose the selected build
A newly exported toolset 7 C grant has `projectDiagnostics: true` and advertises
`get_build_log`. Build receipts retain action, configuration, revision and final
status. Both successful and failed builds report structured `diagnostics`, with
severity, source path/line/column when shared and known, stage, message and raw
diagnostic text. `first_error` selects an error even when warnings precede it or
fill the visible diagnostic list. `diagnostics_total` and
`diagnostics_truncated` explain bounded previews.
`exit_code` is the actual Make process status when one exists; it is null for a
preparation failure. A post-Make validation failure can correctly report exit 0
and `failure_kind: "validation"`: the command succeeded but its output was
unacceptable. `failure_stage` distinguishes compiler, assembler, linker, Make,
preparation or validation when the evidence identifies it. `invocation` records
the top-level command. `failing_command` is available only when a recognized
echoed command precedes the first retained error; hidden recipe commands remain
unavailable. Raw diagnostics stay in the redacted combined log, including lines
without source locations. Separate stdout/stderr are not fabricated.
```json
{"name":"get_build_log","arguments":{"build_id":"<build>","offset":0,"limit":16384}}
```
Follow `next_offset` until null to retrieve every retained UTF-8 byte. Offsets
refer to the frozen redacted log; they never read a host file or rerun a tool.
Each page accepts 1–32,768 bytes, preserving complete Unicode scalars (a scalar
can exceed an unusually small requested limit). The SHA-256 covers the complete
retained log. Only this connection's build IDs are accepted.
The process log retains at most 512 KiB, preserving its beginning and end when
clipped; the normal receipt shows a smaller preview. `process_output_bytes`,
`process_output_truncated`, `log_retained_bytes`, `log_truncated` and
`first_error_scope` distinguish complete evidence from a retained subset.
Pagination recovers the complete retained log, not bytes already dropped at the
process-output limit. The interface reports that limitation explicitly.
## Bounded owned call context
Fresh toolset-10 C playtest grants add `get_call_context(run_id, snapshot_id)`.
It exposes only a fixed 64-byte RAM window at actual S from the same immutable
verified pause. Proven normal CMOC calls can include caller and integer argument
locations; optimized, indirect or unknown frames retain explicit unavailability.
It does not enlarge ordinary memory-read ranges or shared-run access. See the
[call-context contract and qualification](MCP_CALL_CONTEXT.md).
+187
View File
@@ -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.
@@ -0,0 +1,82 @@
# Processor selection for disposable 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.
## Discovery and starting a run
Export a fresh C Assistant connection with **Allow Disposable Playtests**.
Toolset 8 with `playtestProcessors: true` adds optional `processor` to
`start_playtest`. Earlier grants retain their schemas and MC6809 default.
This adds no tool: a fully enabled fresh C connection still advertises 28.
`get_capabilities` reports `playtest_processor_selection`,
`playtest_processors: ["MC6809", "HD6309"]` and
`playtest_default_processor: "MC6809"`. Use the live schema when choosing input.
```json
{
"name": "start_playtest",
"arguments": {
"project_id": "<current project>",
"revision": 0,
"artifact_id": "<current verified build>",
"request_id": "6309-entry-1",
"processor": "HD6309",
"stop_function": "main",
"stop_kind": "function_entry"
}
}
```
Omitting `processor` selects `MC6809`. Exact canonical names are required;
numeric values, `6309`, null and aliases are rejected. Explicit MC6809 and the
omitted default identify the same selection. An identical start request returns
its reserved run. Changing processor with that ID returns `request_id_conflict`.
Startup remains asynchronous: poll `get_run` until ready, failed or cancelled.
Pending receipts report `requested_processor` without claiming an observed
execution mode. Once ready, the worker receipt reports actual CPU state.
## Actual processor and execution mode
Worker receipts, captures and owned debugger snapshots report:
| Field | MC6809 | HD6309 |
| --- | --- | --- |
| `processor` | `MC6809` | `HD6309` |
| `requested_processor` | `MC6809` | `HD6309` |
| `execution_mode` | `not_applicable` | `emulation` or `native` |
| `md_register` | null | Actual MD byte |
| Legacy `cpu` in worker receipts | `6809` | `6309` |
The 6309 resets into emulation mode. Only guest instructions such as `LDMD`
change mode; the tool never sets MD. Mode is observed at each receipt's actual
stop. A guest that executes LDMD again after restart may therefore already be
native by its next stop. 6309 debugger registers additionally include actual
`E`, `F`, `W`, `V` and `MD`; W combines E/F. MC6809 snapshots omit those registers.
Existing code, bank, source, global and memory availability checks still apply.
A processor choice does not create C metadata or change a compiler target.
Build an artifact appropriate to the selected CPU. `restart_playtest` retains
the processor and writable disk. To change CPU, stop and start another run with
a new request ID. Retained disks may be resumed under either CPU after the usual
project, artifact and hash checks; compare actual run identities in test reports.
## Input, audio and limits
Ownership, revision, executable-byte verification, field, boot, mutation and
audio limits remain in force. Stop/retention remains available after execution
budgets are exhausted. Shared-run `send_keys` restrictions are unchanged.
`playtest_input` releases physical keys at the end of each bounded plan.
`capture_playtest_audio` also releases keys before and after its recording
interval; it records the following guest interval, not prior input or sound.
Do not use it to claim a continuously held moving-route test. See the
[audio contract](MCP_AUDIO_CAPTURE.md) and
[banked playtest contract](MCP_BANKED_PLAYTEST.md).
Qualification should run the same compatible disk on both CPUs and retain its
artifact hash, actual CPU/mode, boot/field identity, framebuffer, debugger/global
evidence and stop/retention receipts. Native-mode validation requires guest code
that really executes LDMD. The [build 45 record](MCP_BUILD45_VALIDATION.md)
identifies executed checks and their limits.
+100
View File
@@ -0,0 +1,100 @@
# Project inputs, cache safety and scoped MCP refresh
> 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.
## One content-based input manifest
Project navigation entries, build snapshots, input hashes and assistant scope use
`CMOCProjectInputManifest`. Its entries identify relative path, role, inclusion
reason, content hash, relevant control permissions and whether the entry affects
the source revision/build. Excluded directory rows explain the entire subtree
without reading or hashing its generated contents. The public manifest is paged;
it contains metadata, not file bytes or private connection credentials.
Nested C headers are included recursively. Explicit configured include paths,
sources, generator prerequisites and approved support roots remain inputs.
Retained generated C is still a source input unless declared as an output.
Conventional compiler products, declared binary/disk/debug outputs, logs,
receipts and incidental evidence directories are excluded. There is no blanket
exclusion of every `build` or `generated` directory.
Projects can add these optional literal, project-relative settings:
```json
{
"resourceInputs": ["assets/questions.dat", "out/prebuilt.dat"],
"generatedInputs": [".build/shared/generated.h"],
"outputDirectories": ["out", "test-evidence"]
}
```
Explicit resources/generated inputs override soft directory exclusions; they
cannot be the same path as a concrete declared output. The arrays do not accept
shell patterns or outside-root paths. Version-control metadata stays excluded.
Included paths cannot traverse symlinks. Support remains limited to explicitly
declared regular sibling directories; an include or dependency file never grants
access to a new root.
The same product/evidence exclusions apply inside approved support folders.
Intentional native helper executables in those approved roots are retained. A
settings file inside a support folder is ordinary input data; it cannot declare
additional support roots or expand access. An explicit single-file exception
inside an excluded project folder does not re-include its siblings.
Content and relevant control permissions determine identity. Modification times
are Make scheduling hints, so touching a file does not itself change a revision.
An actual source/header/resource edit still invalidates the affected artifact
and owned run. Restricted C recipes use only their reviewed C/header set (or the
fixed Hello Disk inputs), not unrelated personal Makefiles or resources.
## Inspect and refresh a connection
- `read_project_inputs(project_id, offset?, limit?)` pages the approved manifest
and current refresh summary; `limit` is 1–256.
- `refresh_project(project_id, revision, request_id)` refreshes authorized inputs
or requests native review for a changed scope/control set. Reuse the identical
request ID for the same operation.
- `get_project_refresh(project_id, refresh_id)` reports pending, approved,
rejected or unchanged status, current revision and bounded change metadata.
Existing clean shared files refresh under their grant. The native workbench
updates clean tabs while preserving unsaved drafts. An external edit that
conflicts with a draft's saved base requires local resolution; refresh does not
discard or silently merge that draft.
New included files, recipe/generator changes, support scope changes and executable
control permissions require native review. The window shows concrete relative
paths, old/new inclusion/roles/permissions/hashes and bounded before/after text.
Approval rechecks the reviewed inputs, session and editor identity before adoption;
it does not execute Make or start a guest. Rejected/pending changes block build,
run and source-edit application, while safe status/help/approved-file inspection
and refresh polling remain available. Private credentials never appear in these
responses. A new support root's members are not read or hashed before native
approval authorizes that root.
Stale-state errors retain their ordinary error text and add structured
`error_details` with expected/current revision/artifact facts and changed relative
input paths where known. Lists include totals/truncation indicators rather than
exceeding the transport limit. Inspect the current state before retrying with
updated identities; do not silently create another run.
## Safe cache reuse
The cache is an isolated working copy. Its index and dependency provenance are
checked before reuse. Removed inputs, corrupt/missing populated-cache receipts,
or dependency files referring to missing/foreign snapshot paths cause that
working copy to be discarded and repopulated from current approved inputs.
Supported relative dependencies and valid workspace/toolchain absolute paths
retain normal incremental behavior.
The app does not rewrite arbitrary Make dependency syntax or run a project's
`clean` recipe to repair a cache. Original source, personal media and immutable
earlier build artifacts remain intact. Every included input is protected against
recipe mutation; declared outputs are distinct and can be regenerated/cleaned.
The following development stage adds [audio capture](MCP_AUDIO_CAPTURE.md) and
[verified debugging/build diagnostics](MCP_DEBUG_EVIDENCE.md). Existing
owned-worker bounds, request idempotency, verified debugging and disk provenance
remain in force.
+15
View File
@@ -0,0 +1,15 @@
# Repository organization
> 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.
| Directory | Responsibility |
| --- | --- |
| `src/core/` | Shared CPU, MMU, I/O, video/timing, debugger and machine-session code. Existing `VCC::Mac` C++ names remain to avoid an unrelated API refactor. Conditional Windows host bridges remain beside shared code where needed. |
| `src/devices/` | Portable cartridge/device models, FD-502 disk images, hard disks/clock, RAM disk, Speech/Sound chip cores. |
| `platforms/macos/` | Native app, Xcode project, bridge, resources, packaging and Mac-specific tools. Open `platforms/macos/VCC.xcodeproj`. |
| `platforms/windows/` | Original Windows UI, plugins, resources, Visual Studio solution and build scripts. Open `Vcc.sln` here or run its build scripts from this directory. This is not yet a VCC Plus Windows product. |
| `third_party/` | Retained legacy graphics dependencies and reviewed, pinned development-tool/library/example sources. See the inventory. |
| `tools/` | Repository/toolchain integration scripts. |
| `tests/` | Shared core, Mac interface/bridge and optional toolchain compatibility checks. |
| `docs/` | Product, development and validation documentation; approved artwork. |
| `.build/`, `dist/` | Ignored local build products and distribution candidates. |