Spec v0.1.0

Verifiable provenance, any language.

A formal, language-neutral specification for verifiable provenance — stable method IDs, JSON schemas, conformance levels, and test vectors.

Quick start Handbook

Verify

python tools/python/prov_validator.py check-vector integrity.digest.sha256 # → INFO: Test vector integrity.digest.sha256 passed

Declare

// prov-capabilities.json { "schema": "prov-capabilities@v0.1", "implements": ["adapter.wrap.envelope_v0_1", "integrity.digest.sha256"], "conformance_level": "L2-engine" }

Validate

python -m prov_validator validate-manifest prov-capabilities.json python -m prov_validator conformance-report prov-capabilities.json -o report.json

What prov-spec defines

A minimal, stable surface any engine can implement.

Stable Method IDs

Namespaced identifiers (adapter.*, engine.*, integrity.*, lineage.*) with a hard guarantee: stable IDs are append-only and will never change semantics within a major version.

JSON Schemas

Strict schemas for provenance records, artifacts, evidence, and MCP envelopes — additionalProperties: false, forward-compatible within patch.

Test Vectors

Canonical inputs/outputs for each method. Run them in any language to verify your implementation before shipping.

Conformance levels

Incremental tiers — each builds on the previous. Claim only what you implement.

Level

Name

Required methods

Integrity

integrity.digest.sha256 (or sha512 / blake3)

Engine

L1 + adapter.wrap.envelope_v0_1 · adapter.provenance.attach_record_v0_1 · engine.prov.artifact.register_output

Lineage

L2 + lineage.parent.link

Quick start

Run a test vector

git clone https://github.com/mcp-tool-shop-org/prov-spec
cd prov-spec
python tools/python/prov_validator.py check-vector integrity.digest.sha256

List all stable methods

python tools/python/prov_validator.py list-methods
# 19 stable methods across 4 namespaces

Validate a provenance record

python -m prov_validator validate-methods record.json --strict

Generate a conformance report

python -m prov_validator conformance-report prov-capabilities.json -o report.json

Who is this for?

Language-neutral. Not a framework. Not MCP-specific.

Engine authors

Implement provenance in any language against a stable, versioned spec. Ship a prov-capabilities.json to declare what you support.

Tool integrators

Wrap existing tools with provenance records. Use the adapter.* methods to handle envelopes, errors, and pass-through cases correctly.

Auditors & builders

Verify provenance claims against test vectors. Build provenance-aware infrastructure with confidence in forward compatibility.