Publish VCC Plus OSS source distribution for 3.6.2 build 60

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

No files matched your search

+137
View File
@@ -0,0 +1,137 @@
# Verified custom-Make debugging through MCP
> Technical evidence extract for the VCC Plus white paper. Only reviewed contracts, mechanisms, methods, results and limitations are retained. Original validation dates and configuration limits remain historical; this export is not a new test run.
## Read the build evidence first
Every completed executable build now reports `source_debugging` in `get_build`,
including ordinary custom-Make builds without a banked manifest. Successful
compilation and verified debugging are separate results:
- `verified` means the executable/source map and compiler type metadata passed
verification. `source_only` means executable evidence passed but typed C
metadata is unavailable; `reason` explains why. `unavailable` identifies an
executable, map, object, listing or source verification failure.
- `c_line_stops` lists actual compiler-mapped statements, with shared source path,
line, logical address and declared bank identity where applicable. `functions`
names only unique functions with a verified C statement inside their body.
- `function_entries` names verified executable entries, including supported
assembly/prologue entries. An entry stop does not establish a C statement or
stack-frame layout. `function_details` distinguishes a declaration from an
available C stop and explains missing C statements.
- `globals` lists shared file/global declarations, their verified type/storage
and module identity. These are declarations, not guessed runtime values.
Unsupported storage/type layouts are explicitly unavailable.
- Binary/link-map hashes, load entry, module page assignments and
`owned_stop_evidence` identify the exact build. Every catalog includes total
and truncation fields and is bounded by its encoded size.
Ordinary flat custom Makefiles must retain the matching binary, linker `.map`,
linked project `.o`, assembler `.lst` and source snapshots. Keep CMOC
`--intermediate` enabled when compiling and linking. The bundled compiler emits
its `VCCDBG1` type/storage records; retaining compiler-generated `.s` permits
verification of records too long for an assembler listing row. A useful Debug
compile uses `-O0 -fno-omit-frame-pointer`; optimized builds can legitimately
have fewer C statements or unavailable locals. No user Makefile is rewritten
merely to provide debugger metadata.
For example, a normal recipe can compile and link with:
```make
obj/main.o: main.c
@mkdir -p obj
"$(CMOC)" --coco -O0 -fno-omit-frame-pointer --intermediate --intdir=obj -c -o $@ $<
program.bin: obj/main.o
"$(CMOC)" --coco --intermediate --org=2800 -o $@ obj/main.o
```
This fragment only illustrates retained evidence; disk construction and launch
commands remain the project's declared recipe. Packed, relocated or bank-switched
programs must supply the public version-1 [banked debug manifest](MCP_BANKED_PLAYTEST.md).
Its hashes, unpacked images, section ownership and actual physical page identities
are required. It never falls back to a flat interpretation after verification
fails.
## Stop and inspect the owned guest
With an approved disposable-playtest connection, build the current revision and
use an advertised `functions` name as `stop_function` in `start_playtest`, or
`function_entries` with `stop_kind: "function_entry"`. Poll asynchronous startup
with `get_run`. Later `playtest_debug` with `action: "stop_at"` accepts the same
verified name/stop kind. Neither call accepts an arbitrary stop address.
Ordinary flat builds use the existing native guarded-breakpoint path. Complete
object-relocated executable bytes must match before the first named stop can
attach; the actual worker's mapping fingerprint is retained. No assumed stock
physical pages are substituted. Continuing can remove selected stops while
retaining the exact same code/mapping identity. A changed mapping or executable
byte makes the old attachment unavailable. An empty inspection selection alone
cannot establish an initial attachment.
At the verified paused state, `get_debug_snapshot` reports registers, honest
stop kind, source/function entry where known, actual physical pages/mapping
fingerprint and bounded `globals` values from the same safe memory capture.
A global outside the readable stopped mapping has an `unavailable` reason.
Unshared declarations are omitted. C frame locals remain unavailable at owned
entry/instruction stops; no frame is inferred from U or a guessed prologue.
Locally configured watches retain their existing rules.
`read_debug_memory` accepts only ranges advertised by that immutable snapshot,
up to 256 bytes. Resume, input, step, restart, source/artifact changes and
connection revocation invalidate the applicable observation. Inspection performs
no guest expressions, register writes, memory writes or side-effecting I/O reads.
A mismatched binary, object relocation, source identity or bank cannot produce a
verified snapshot merely because a requested function name exists.
For diagnostics and paged compiler output, use `get_build` and `get_build_log`;
those receipts are independent of whether source debugging is available.
## Diagnose the selected build
A newly exported toolset 7 C grant has `projectDiagnostics: true` and advertises
`get_build_log`. Build receipts retain action, configuration, revision and final
status. Both successful and failed builds report structured `diagnostics`, with
severity, source path/line/column when shared and known, stage, message and raw
diagnostic text. `first_error` selects an error even when warnings precede it or
fill the visible diagnostic list. `diagnostics_total` and
`diagnostics_truncated` explain bounded previews.
`exit_code` is the actual Make process status when one exists; it is null for a
preparation failure. A post-Make validation failure can correctly report exit 0
and `failure_kind: "validation"`: the command succeeded but its output was
unacceptable. `failure_stage` distinguishes compiler, assembler, linker, Make,
preparation or validation when the evidence identifies it. `invocation` records
the top-level command. `failing_command` is available only when a recognized
echoed command precedes the first retained error; hidden recipe commands remain
unavailable. Raw diagnostics stay in the redacted combined log, including lines
without source locations. Separate stdout/stderr are not fabricated.
```json
{"name":"get_build_log","arguments":{"build_id":"<build>","offset":0,"limit":16384}}
```
Follow `next_offset` until null to retrieve every retained UTF-8 byte. Offsets
refer to the frozen redacted log; they never read a host file or rerun a tool.
Each page accepts 1–32,768 bytes, preserving complete Unicode scalars (a scalar
can exceed an unusually small requested limit). The SHA-256 covers the complete
retained log. Only this connection's build IDs are accepted.
The process log retains at most 512 KiB, preserving its beginning and end when
clipped; the normal receipt shows a smaller preview. `process_output_bytes`,
`process_output_truncated`, `log_retained_bytes`, `log_truncated` and
`first_error_scope` distinguish complete evidence from a retained subset.
Pagination recovers the complete retained log, not bytes already dropped at the
process-output limit. The interface reports that limitation explicitly.
## Bounded owned call context
Fresh toolset-10 C playtest grants add `get_call_context(run_id, snapshot_id)`.
It exposes only a fixed 64-byte RAM window at actual S from the same immutable
verified pause. Proven normal CMOC calls can include caller and integer argument
locations; optimized, indirect or unknown frames retain explicit unavailability.
It does not enlarge ordinary memory-read ranges or shared-run access. See the
[call-context contract and qualification](MCP_CALL_CONTEXT.md).