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