david.boston / ultimate-tool
Hardware-in-the-loop development platform for the Commodore 64.
Star
Fork 0
Watch
ultimate-tool docs CONTRACTS.md
5.8 kB
Markdown
at main

Versioned development contracts #

Ultimate Tool versions manifests, immutable runs and externally consumed operations independently. A new writer is not permission to rewrite old runs. Readers reject unsupported future schemas explicitly.

Manifest schema 11 #

All previously supported manifest schemas remain readable. Two optional fields require schema 11:

  • build.container_image: an explicit nonempty container image reference. Only this reference is inspected for optional Docker image identity. Omitting it does not launch Docker. The toolchain field remains the developer's textual identity of the actual build or approved prebuilt inputs. Schemas 1–10 retain their previous optional image-inspection behavior for compatibility.
  • tests.memory_checkpoint_capture: declares a bounded cooperative frozen-RAM contract. It requires mailbox observation and expected terminal pass. The runner records bounded double-read proof after successful screen and terminal assertions; comparison verifies that proof and same-input eligibility. See checkpoint comparison. Parsing this field alone grants no hardware permission or arbitrary-program memory-read safety.

Checkpoint semantics are frozen_post_terminal_v1: the reviewed program writes its named ranges and safe marker before terminal pass and never changes them afterward. At most 16 ranges, 256 bytes per range and 1024 bytes total are allowed. The marker is 1–16 bytes expressed as lowercase hexadecimal. Names are unique lowercase ASCII slugs. Ranges and marker must be nonoverlapping ordinary RAM in $0200–$9FFF or $C000–$CFFF, outside configured mailbox, command, screen and crash-capture regions. This is not a live safe-point protocol or permission for arbitrary DMA reads into a running program.

Run schema 13 #

The reader accepts supported schemas 1–13 without changing their files. New C64 test records store an optional structured test_expectations snapshot: selected test/observation, expected terminal/screen, timeouts, and a startup command fingerprint (name, total name+payload byte length, payload SHA-256). It is present even if the selected test's build fails. An operation that does not execute a manifest C64 test must not acquire expectations merely because its display name matches a declared test. The source-linked debug capture is one such operation: it validates the fixed post-stop pass/QUT1 contract and carries only the declared test's name, so its record omits test_expectations even when that test declares a differing timeout or screen.

Legacy absence is unavailable information, not a failed assertion or an invitation to read today's manifest. The fingerprint omits payload text, but other existing evidence such as the manifest and submitted command bytes can contain that text. Run bundles are not automatically safe to publish.

The optional memory_checkpoint_capture metadata identifies the bounded capture evidence described above, including invalid partial captures preserved on failure. Historical records do not gain it retroactively.

Opt-in strict gate #

strict_gate is a default-false boolean on the shared test and probe requests (CLI --strict-gate, HTTP/MCP strict_gate). All three surfaces use the one name and forward it unchanged; omitting it selects the ordinary, unchanged behavior, and legacy requests and records are unaffected by its addition. It is a fail-stop restriction, not an added permission: it does not relax the pinned-identity check, the reset count, the probe expiry, the mutation token, the origin check, or any lease, and it grants no extra hardware authorization. It is orthogonal to compare_checkpoints. A strict job must consume a probe that was itself requested with strict_gate; otherwise the service answers 422 probe_strictness_mismatch before the permit is consumed and before any mutation. The bounded supported shapes, the mutation budget, and the pause/resume ownership rules are documented in CHECKPOINT_COMPARISON.md. No physical-device run of this restriction has been recorded.

Integrity verification #

Finished records can be checked against their registered SHA256SUMS manifest. The shared verifier rejects pending/unfinished records, invalid names, duplicate or missing/phantom entries, ordinary symlink and registered-file aliases, drifted run metadata and mismatched hashes. It streams large evidence in bounded memory. Run metadata reads are capped at 16 MiB; checksum manifests at 4 MiB and 16,384 entries. Raw trace data belongs in separate registered files.

This proves observed content consistency, not authenticity or an ongoing safety guarantee after files change. Keep raw and derived evidence together locally; curated public derivatives require a separate privacy review.

Error contracts and envelopes #

New core errors use stable codes diagnostic_report_failed, checkpoint_capture_failed, and checkpoint_comparison_failed, with evidence layer exit code 5. Invalid declarations retain configuration exit code 2. A valid comparison that reports a behavioral mismatch will be a test-failure result, not a malformed invocation; its command behavior is documented with that operation when implemented.

The CLI envelope remains schema 1. The HTTP service envelope is schema 13 and the MCP adapter envelope is schema 12. Diagnostic report and detail pages have inner contract schema 1; the flat HTTP representation names it diagnostic_report_schema_version. Run schema versions nested in a response are independent of those outer envelopes. See HTTP API and MCP for supported operations and authorization requirements.