ArtifactDiff

A contract change verification gate for humans and AI agents.

Prove that an AI agent changed only the Office/PDF contract terms you authorized — semantically, visually, and cryptographically — before the document is delivered.

ArtifactDiff is local-first and offline. It turns a requested edit such as “change the payment window from 30 days to 45 days” into a frozen policy, verifies the candidate, and writes an immutable Review Bundle that both humans and agents can inspect.

Project status: 0.1.0 alpha. The contract-safe core and signed Golden Path are implemented and covered by more than 900 automated tests. Packaging and public release automation are still in progress.

What it catches

Candidate	Verdict	Delivery gate
Only the exact authorized clause occurrence changed	PASS	May proceed
The edit is semantically allowed but has an unexplained layout change	REVIEW	Blocked until a human approves that finding
A party, amount, date, signature, seal, attachment, or other protected content changed	FAIL	Blocked and not approvable

ArtifactDiff is deliberately fail-closed. Review remains blocking by default and a FAIL finding cannot be approved away.

Three-minute Golden Path

Prerequisites: Python 3.11+ and a local checkout of this repository. The demo uses only synthetic contracts and makes no network request after dependencies are installed.

python -m venv .venv
# Activate .venv using your shell, then:
python -m pip install -e ".[dev]"
python scripts/run_contract_golden_path.py --output build/contract-golden-path
python -m json.tool build/contract-golden-path/summary.json

The run creates three independently verified, Ed25519-signed Review Bundles:

authorized    raw=pass    effective=pass
review        raw=review  effective=review
unauthorized  raw=fail    effective=fail

The review case stays blocked. To demonstrate the signed event-chain transition with an explicitly simulated synthetic human reviewer, use a different output directory:

python scripts/run_contract_golden_path.py --output build/contract-golden-path-approved --approve-review

--approve-review is demo-only. Real approvals remain interactive human actions through artifactdiff review or artifactdiff approve; agents cannot approve their own findings. See the Golden Path walkthrough for the generated files and privacy boundaries.

The workflow

Human instruction
      │
      ▼
contract-safe policy ── freeze + optional Ed25519 authorization
      │
      ▼
controlled agent edit session
      │
      ▼
semantic rules + protected entities + visual envelope
      │
      ├── PASS ───────────────────────────────► deliver
      ├── REVIEW ─► signed per-finding review ─► deliver or reject
      └── FAIL ───────────────────────────────► reject
                          │
                          ▼
                 immutable Review Bundle

The Review Bundle is the system of record. The local review desk is only an authenticated loopback interface over that bundle.

Human and automation interfaces

The same application boundary powers every interface:

• CLI: create/validate/seal policies, open controlled sessions, verify changes, inspect findings, approve findings, and verify or pack bundles.
• Local review desk: inspect a bundle and sign one finding at a time without sending contracts or private keys to browser JavaScript.
• MCP: bounded inspect/draft/validate/local-verify tools for AI agents, with separate input and output roots and no approval or verified-signing capability.
• Offline HTML: portable human review reports linked to verified facts.

artifactdiff --help
artifactdiff policy --help
artifactdiff verify --help
artifactdiff review path/to/review-bundle

For an MCP host, configure absolute, path-separator-delimited roots before starting the stdio server:

ARTIFACTDIFF_MCP_INPUT_ROOTS=/absolute/contracts
ARTIFACTDIFF_MCP_OUTPUT_ROOTS=/absolute/artifactdiff-output
artifactdiff-mcp

MCP intentionally cannot approve findings or perform verified signing.

Why this is not another PDF diff

Ordinary document diff	ArtifactDiff
Shows everything that changed	Proves whether changes match a pre-authorized instruction
Text or pixels are the final result	Semantic, protected-entity, occurrence, metadata, and visual rules combine into one gate
A screenshot/report is the evidence	Content-addressed Review Bundle with policy, facts, verdict, evidence, signatures, and append-only decisions
Designed only for a person looking at two files	CLI, Python, MCP, offline report, and human review desk share one truth model
“Looks fine” may pass	REVIEW and unavailable evidence block by default

Security and privacy model

• Local-first and offline; no account or cloud service is required.
• contract-safe is enabled by default, with no implicit authorization.
• Exact expected edits are bound to their clause and occurrence.
• Parties, money, currencies, dates, durations, percentages, headers, footers, signatures, seals, and attachments are protected by default.
• Offline Ed25519 is the core trust mechanism; enterprise identity can be added through adapters later.
• Evidence defaults to minimal; full is explicit and sealed is encrypted for named recipients.
• MCP responses are bounded and do not return full contracts, page images, or key material.

Read the approved verification-gate design and the Plan 4.5 acceptance record for the full trust and verdict model.

Current format support

• PDF → PDF
• DOCX → DOCX
• DOCX → PDF
• English, Chinese, and bilingual contract structure
• Optional DOCX rendering through LibreOffice; PDF rendering is local

Development

python -m pip install -e ".[dev]"
python -m pytest -q

The repository currently contains unit, integration, tamper, CLI, MCP, review-desk, cross-format, and signed Golden Path acceptance coverage.

Next milestones

• Reproducible public synthetic corpus and zero-false-pass gate
• GitHub Action for binary-document pull request review
• Demo media and downloadable example Review Bundle
• Schemas, threat model, SBOM, provenance, and signed alpha release
• Plugin boundaries for enterprise parsers, renderers, signing, encryption, and storage

ArtifactDiff is being built around one narrow promise: when an agent edits a contract, you can prove exactly what it was allowed to change — and that it changed nothing else.