7.6 KiB
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:
-
verifiedmeans the executable/source map and compiler type metadata passed verification.source_onlymeans executable evidence passed but typed C metadata is unavailable;reasonexplains why.unavailableidentifies an executable, map, object, listing or source verification failure. -
c_line_stopslists actual compiler-mapped statements, with shared source path, line, logical address and declared bank identity where applicable.functionsnames only unique functions with a verified C statement inside their body. -
function_entriesnames verified executable entries, including supported assembly/prologue entries. An entry stop does not establish a C statement or stack-frame layout.function_detailsdistinguishes a declaration from an available C stop and explains missing C statements. -
globalslists 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_evidenceidentify 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:
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. 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.
{"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.