Files
VCCPlusOSS/docs/development/MCP_DEBUG_EVIDENCE.md
T

7.6 KiB
Raw Blame History

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:

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.