Files

150 lines
8.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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. Banked evidence permits compiler `.s` files
up to 32 MiB while retaining 8 MiB limits for other evidence, the 1 MiB manifest
limit and the 128 MiB aggregate cap. Size failures name the artifact and exact
limit; hash, declared-output and symbolic-link checks still apply. No evidence
is truncated to make a source map appear verified.
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 [banked debug manifest](MCP_BANKED_PLAYTEST.md).
Version 1 preserves distinct physical ownership; version 2 supports explicitly
declared mutually exclusive code overlays. Discover
`banked_debug_manifest_versions` and `verified_code_overlays` through
`get_capabilities` before preparing that evidence.
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. Owned memory and
call-context reads also compare a fresh complete capture, including verified
residency, registers, cycles and safe memory, even at the same field clock.
The residency fingerprint names a current proof rather than a monotonic guest
write counter; A→B→A still requires fresh capture validation. 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).