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,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.
|
||||
Reference in new issue
Block a user