evidence-bundle-diff

Diff two evidence-bundle manifests and classify the transitions that hurt a downstream consumer's integrity assumptions.

The evidence-bundle counterpart to agent-card-diff and mcp-tool-card-diff.

Status: v0.1.0 — Node 20/22 supported, library + CLI.

Why

An evidence bundle is the artifact that proves a claim. When two versions of the manifest exist — "what we shipped to the auditor last week" vs "what we're about to ship this week" — a reviewer needs to see at a glance: did any existing file get rewritten? Did the signer change? Did the expiration shrink? Did the bundle's purpose shift from compliance-disclosure to something narrower?

What counts as breaking

Change	Breaking?
Item content hash changed	✅ (items are immutable — replace, don't rewrite)
Item removed	✅
Signature removed	✅
Signer identity changed	✅
Signature algorithm changed	✅
Bundle schema version changed	✅
Bundle id changed	✅
Bundle purpose changed	✅
Expiration shortened	✅
Item added	—
Item size / media-type / source-uri changed	—
Expiration extended / added	—
Signature added	—
Bundle subject changed / creator changed	—
Relationships added / removed	—
Provenance block changed	—

CLI

npx evidence-bundle-diff <previous-manifest.json> <next-manifest.json>
    [--format json|markdown|summary]
    [--strict] [--out FILE]

Exit code:

• 0 — no changes OR only non-breaking changes
• 1 — diff is breaking (or --strict and any change exists)
• 2 — usage / I/O error

Drop it into CI to gate evidence-bundle PRs.

Library

import { diffManifests, toMarkdown, toSummary, BREAKING_REASONS } from "evidence-bundle-diff";

const diff = diffManifests(previous, next);
console.log(diff.breaking);           // boolean
console.log(diff.added.items);        // ["tabletop-2026-05-10", …]
console.log(diff.removed.relationships);
console.log(toMarkdown(diff));
console.log(toSummary(diff));         // "BREAKING 7 changes" / "no changes"

Composes with

• evidence-bundle-spec — the schema this diffs.
• evidence-bundle-builder — produces the manifest.json files this consumes.
• agent-card-diff, mcp-tool-card-diff — sibling diff tools for the AgentCard and Tool Card surfaces.

Develop

npm install
npm run lint && npm run typecheck && npm run coverage && npm run build
npm run demo

License

AGPL-3.0-or-later