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

Walrus blob IDs are derived from content. If a single byte of a checkpoint changed, its blob ID would change too — so a stored ID can only ever return the exact bytes it was minted from. Verifying a trail is therefore a matter of re-fetching every blob in the manifest and confirming each one still fetches and unpacks cleanly.

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,
  "steps": [
    {
      "checkpoint_id": "1f164eb8-…",
      "blob_id": "WL4TgZgqRE9Pwq1…",
      "parent": null,
      "forked_from": null,
      "ok": true,
      "error": null
    }
  ]
}

ok only when every step passes

The top-level ok is true only when there is at least one checkpoint and verified === checkpoint_count. A single unreadable or corrupt blob flips it to false and marks the offending step with its error.

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.