Guides

Audit trail

verify_trail is the flight recorder. It walks a thread's entire chain of checkpoints and re-fetches each content-addressed blob, proving the run is intact and tamper-evident.

Why it works

Every checkpoint blob is hashed with SHA-256 at write time, and that hash is recorded in the per-thread manifest. To verify a trail, TuskPoint re-fetches each blob, recomputes its SHA-256, and compares it to the stored hash. A match proves the bytes are byte-for-byte what was written; any mismatch is a FAIL. This is a cryptographic check, not merely a successful fetch — a blob that was swapped or corrupted in place is caught even if it still downloads.

Each step is reported as PASS (hash matches), FAIL (hash differs — tampered), or UNVERIFIED (the checkpoint predates integrity proofs and carries no stored hash, so it can't be cryptographically confirmed).

Run it

verify_trail

verify_trail("run-42")

It returns a per-checkpoint report plus an overall verdict:

returns

{
  "thread_id": "run-42",
  "ok": true,
  "checkpoint_count": 4,
  "verified": 4,
  "tampered_count": 0,
  "steps": [
    {
      "checkpoint_id": "1f164eb8-…",
      "blob_id": "WL4TgZgqRE9Pwq1…",
      "stored_hash": "9e1c…",
      "recomputed_hash": "9e1c…",
      "status": "PASS"
    }
  ]
}

ok only when every step passes and none are tampered

The top-level ok is true only when at least one checkpoint was hash-verified and tampered_count === 0. A single mismatched hash flips it to false and marks the offending step FAIL with its recomputed hash so you can see exactly what changed.

Via the Python API

python

from langgraph_checkpoint_walrus import WalrusSaver, WalrusClient

saver = WalrusSaver(WalrusClient())
report = saver.verify_trail("run-42")
assert report["ok"], "trail failed verification!"

What it's good for

Compliance — produce a verifiable record that an agent's decisions were not altered after the fact.
Debugging — catch a corrupt or missing checkpoint before it surfaces as a confusing resume failure.
Hand-off — let one agent verify another's trail before continuing from it.