[hyperpolymath]

What & why

Top item on the roadmap after v0.3: the interchange contracts the sibling tools (did-you-actually-do-that, somethings-fishy) build against. This PR delivers the half that lives entirely in this repo — the verification protocol and the pinned wire formats.

The verification protocol

plasma facts . > before.json     # snapshot
<agent does its work>
plasma facts . > after.json      # snapshot again
plasma diff before.json after.json   # exactly what changed

An agent's claim "I only added SPDX headers" verifies as: files_added/files_removed/metadata_changed/git_changed empty, every headers_changed entry has before: null.

Changes

• plasma-engine/src/diff.rs — pure diff(before, after) → FactsDiff: files added/removed, SPDX header transitions (on common files; added/removed files are implied by the file lists), metadata changes, git state. Deterministically ordered; identical inputs give byte-identical JSON.
• plasma diff CLI — human or JSON output, exit semantics per diff(1): 0 identical, 1 differ, 2 error — scriptable without parsing.
• Exit-code fix (all commands) — anyhow errors from main previously exited 1, colliding with "violations found"/"snapshots differ". Usage/IO errors now exit 2 uniformly, matching the long-documented table in docs/cli-design.adoc. Caught by the new garbage-snapshot test.
• docs/interchange-contracts.adoc — pins all four wire contracts (facts snapshot, facts diff, findings JSON, SARIF plasma/<rule-id> namespace) with an additive-only evolution rule within a major version.
• Versions unified at 0.4.0 — including STATE.a2ml, CITATION.cff, codemeta.json, and the Justfile, which had lagged at 0.2.0.
• ROADMAP/CHANGELOG/cli-design updated.

Verification

• cargo test --workspace — 88 tests pass (12 integration across check/fix/diff suites, 33 engine, 42 parser, 1 root)
• cargo clippy --workspace --all-targets -- -D warnings and cargo fmt --check clean
• Live demo: two snapshots of this repo diff as identical (exit 0); the integration test drives the full snapshot → plasma fix --apply → snapshot → diff cycle and asserts the diff shape
• plasma check . self-check: 0 violations, 110 rules satisfied

Out of scope (remaining v0.4 / v0.3 items)

Git hooks, reference CI action, .plasma.toml policy pinning, release facts, overlay modify/override algebra, content facts — all tracked in ROADMAP.adoc.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JSVSF9HhKUhDrEV4xkMEXq

---

Generated by Claude Code