Verifying Integrity

The behavioral ledger makes your machines’ history tamper-evident. The ledger validator is the tool that checks it. With one command you can confirm that a run’s history is unbroken, that a machine’s content matches its recorded hash, and that a release or package carries a valid signature.

You run verification when you need to prove, not assume: before trusting a trace someone handed you, before promoting a machine, before installing a package from the registry, or in CI as a gate that fails if integrity is ever compromised.

The command

mashin verify machine <id>              # Verify a machine's content hash
mashin verify run <id>                  # Verify a run's hash chain and head hash
mashin verify release <id>              # Verify a release attestation signature
mashin verify package <name@version>    # Verify a package tarball hash and signature

Each invocation prints a JSON report:

{
  "subject": "run_01jq…",
  "type": "run",
  "status": "pass",
  "checks": [
    { "name": "hash_chain", "status": "pass", "details": "42 events, chain intact" },
    { "name": "head_hash",  "status": "pass", "details": "head matches last event" }
  ],
  "failures": 0
}

The top-level status is pass when no check failed, fail when one did, and legacy when the subject predates the integrity mechanism it would be checked against (see below). failures is the count of failed checks, so a CI step can gate on a single number.

What each subject checks

run — the ledger chain

Verifying a run confirms its recorded history is internally consistent and unbroken:

• hash_chain — recomputes the event hash chain across the run’s steps and confirms every prev_hash links correctly. A break is reported at the exact event index where it occurs.
• head_hash — confirms the run’s stored head hash equals the hash of its last event. This is the single value that fingerprints the entire run; if it matches, the whole chain behind it is accounted for.

If a field of any past event were altered, the chain check fails at that event and the head hash no longer matches. There is nowhere to hide a change.

machine — the definition

• definition_hash / content_hash — recomputes the hash of the machine’s definition and compares it to what was recorded. A match proves the machine is byte-for-byte the one whose hash was stored; a mismatch proves it was modified.

release — the attestation

• attestation_signature — verifies the signature on the release attestation against the signer’s public key, proving the release was attested by the holder of that key and has not been altered since.

package — the registry artifact

• tarball_hash — recomputes the package contents hash and compares it to the manifest.
• signature — verifies the package signature against the publisher’s keys.

Published krates (and the registry’s countersigning attestation) are signed with a hybrid signature: a classical Ed25519 signature and a post-quantum ML-DSA-65 signature (NIST FIPS 204), both over the same content. Verification requires both to be valid. This means a krate is never weaker than classical signing, and the post-quantum leg cannot be stripped: a krate presented with the post-quantum signature removed is rejected. Each leg’s algorithm travels with the artifact, so verification honors what the publisher signed with rather than assuming a fixed algorithm.

Reading the results

Check status	Meaning
pass	The check ran and the artifact is intact.
fail	The check ran and detected a mismatch. The artifact is not what it claims to be. Investigate before trusting it.
skip	The check could not run because a required value was not recorded.
legacy	The artifact was created before this integrity mechanism existed, so there is nothing to verify against.

A legacy result is not a failure; it means “no proof available,” not “proof failed.” A fail is the one to act on: it is the signal that a record, definition, or artifact was changed after it was sealed.

Deeper verification

mashin verify run checks the chain and head hash, which is what most workflows need. The platform also performs a fuller provenance check programmatically, used during cross-cell exchange and promotion. It adds:

• Definition integrity — the machine hash recorded on the run matches the machine that ran.
• Policy integrity — the recorded policy hash matches the trust level and capabilities the machine declared.
• Runtime hash present — the runtime fingerprint was recorded.
• Execution chain — the step-level prev_hash values form a valid chain.
• Purity certificates — pure compute steps carry their no-effects certification.
• Evolution-ledger linkage — the run’s machine version exists in the evolution ledger and that ledger’s own chain is intact.

When a run is verified across cells, the receiving cell checks the originating cell’s signatures using its public key, so a trace can be trusted no matter which cell delivered it. This is what makes governed history portable: trust the cryptography, not the courier.

In CI

Because the report is JSON with a failures count, verification slots into a pipeline as a gate:

mashin verify run "$RUN_ID" | jq -e '.failures == 0'

The command exits non-zero on a failed check, so it can stand alone as a step that blocks a merge or a deploy if integrity is ever broken.

Related

• The Behavioral Ledger — what is being verified, and why it holds
• Cells — where runs and their history are stored
• Publishing — releases and packages, and how they are signed