proof

Proof

The universal record format for AI governance.

Why Proof Exists

AI agents are moving from pilot to production. Regulators are catching up — the EU AI Act, SOC 2 AI controls, state-level AI laws — and every one of them requires evidence: what did the agent do, what controls were in place, can you prove it?

Today that evidence is scattered across CloudWatch JSON, LangSmith exports, CSV dumps, screenshots, and PDF summaries. Every tool invents its own format. Auditors get a pile of incompatible files. Verification is manual. Tamper evidence is nonexistent.

Proof solves this by defining one record format that any tool can produce and any auditor can verify. One binary, one schema, one chain. Offline, signed, deterministic.

The primitive is separate from the products built on top of it. Discovery tools, compliance engines, and policy enforcers all import Proof as their shared record and signing layer. Third parties — agent frameworks, MCP servers, CI pipelines — can adopt the format independently by importing the Go module or implementing the JSON Schema spec. The format earns standard status through adoption, not announcement.

What Proof Is

An open-source Go module and verification CLI. Four operations:

• Create — Structured, schema-validated proof records with deterministic hashing
• Chain — Append records to tamper-evident hash chains (same mechanism as certificate transparency logs)
• Sign — Ed25519 or cosign (Sigstore) signatures on records, chains, and bundles
• Verify — Offline verification of any proof artifact with a single binary

What Proof Is Not

• Not a policy engine. Proof does not make allow/block decisions.
• Not a scanner or collector. Proof does not discover tools or capture agent activity.
• Not a compliance engine. Proof does not evaluate whether evidence satisfies controls — it defines what records look like and what controls require.
• Not AI-powered. Zero LLMs, zero ML, zero probabilistic components. Deterministic canonicalization, cryptographic hashing, schema validation. Same inputs, same outputs, always.

Quick Start

PROOF_VERSION="$(gh release view --repo Clyra-AI/proof --json tagName -q .tagName 2>/dev/null || curl -fsSL https://api.github.com/repos/Clyra-AI/proof/releases/latest | python3 -c 'import json,sys; print(json.load(sys.stdin)[\"tag_name\"])')"
go install github.com/Clyra-AI/proof/cmd/proof@"${PROOF_VERSION}"

proof types list          # 18 built-in record types
proof frameworks list     # 10 built-in starter frameworks (79 controls)
proof verify ./artifact   # Verify any proof artifact offline

Library Usage

import "github.com/Clyra-AI/proof"

record, err := proof.NewRecord(proof.RecordOpts{
	Source:        "my-mcp-server",
	SourceProduct: "my-product",
	Type:          "tool_invocation",
	Event:         map[string]any{"tool": "postgres_query", "action": "SELECT"},
})
if err != nil {
	return err
}

chain := proof.NewChain("default")
if err := proof.AppendToChain(chain, record); err != nil {
	return err
}

key, err := proof.GenerateSigningKey()
if err != nil {
	return err
}
if _, err := proof.Sign(&chain.Records[0], key); err != nil {
	return err
}

Every tool invocation now produces a signed, chainable, verifiable proof record. No configuration files, no account, no network access.

Custom Record Types

if err := proof.RegisterCustomTypeSchema("vendor.custom_event", "./custom.schema.json"); err != nil {
	return err
}

Custom types validate against the base proof record schema plus your type-specific schema. They chain and sign identically to built-in types.

Portable bundles can carry a scoped custom type registry in record-types.json. The manifest version is 1 and each entry records record_type, schema_id, schema_version, a safe relative schema_path, and its SHA-256 digest. Portable schema files declare matching $id and x-proof-schema-version metadata. Strict bundle verification requires the manifest and every referenced schema to be listed and hash-covered by the bundle manifest. Verification loads these definitions into a call-local schema.Registry; they never leak into the legacy process-global registration API. Use proof.NewSchemaRegistry and proof.ValidateRecordWithRegistry when validating records from an explicitly scoped registry.

Control, Containment, and Telemetry Correlation

ControlContainmentTelemetryProfile is a versioned, product-neutral envelope for event, action, contract, run, session, policy, decision, proof, causal, containment, boundary, revocation, and acknowledgement references, along with OpenTelemetry trace_id/span_id/parent_span_id fields. binding_mode is either identifier_only or digest_bound. Identifier-only references prove only that identifiers were recorded; Proof does not infer enforcement, containment, telemetry authenticity, or product semantics. Digest-bound references use the same SHA-256 RelationshipRef fields and canonicalization rules as the rest of Proof. See schemas/v1/control-containment-telemetry-v1.schema.json.

Read Paths

• proof.ReadRecord(path) parses JSON into a Record without schema validation.
• proof.ReadAndValidateRecord(path) parses and validates both record structure and type-specific schema.

Governance Events

record, err := proof.NewRecordFromEvent(proof.GovernanceEvent{
	EventID:   "evt-1",
	Timestamp: "2026-02-20T12:00:00Z",
	EventType: "tool_gate",
	Detail:    map[string]any{"verdict": "allow"},
}, "axym")
if err != nil {
	return err
}

Use schemas/v1/governance-event-v1.schema.json for event validation. See docs/governance-events.md and docs/record-context-keys.md.

Bundle Signing and Verification

signedManifest, err := proof.SignBundleManifest(inputManifest, key) // pure: no file mutation
if err != nil {
	return err
}

_, err = proof.SignBundleFile("./bundle", key) // explicit file mutation of ./bundle/manifest.json
if err != nil {
	return err
}

verified, err := proof.VerifyBundle("./bundle", proof.BundleVerifyOpts{
	VerifySignatures: true,
	PublicKey:        proof.PublicKey{Public: key.Public},
	Strict:           true,
})
if err != nil {
	return err
}
_ = signedManifest
_ = verified

Strict verification is additive and opt-in. For bundles it rejects ambiguous or duplicate normalized manifest paths, unlisted files, and symbolic links. proof.VerifyChainWithOptions applies the same opt-in model to chain metadata, rejecting inconsistent record_count and head_hash values. Gait pack/runpack callers can enable the equivalent checks through core/gait.VerifyOpts.Strict. Existing verification entry points retain their legacy behavior.

Record Format

The atomic unit is the proof record — a structured, signed artifact that captures what happened, what controls were in place, and the cryptographic integrity needed to prove it wasn't tampered with.

{
  "record_id": "prf-2026-09-15T10:30:00Z-a7f3b2c1",
  "record_version": "1.0",
  "timestamp": "2026-09-15T10:30:00Z",
  "source": "my-mcp-server",
  "source_product": "my-product",
  "record_type": "tool_invocation",
  "event": {
    "tool": "postgres_query",
    "action": "SELECT",
    "parameters": {
      "query_hash": "sha256:abc123...",
      "target": "payments.transactions"
    }
  },
  "controls": {
    "permissions_enforced": true,
    "approved_scope": "read-only on payments.*",
    "within_scope": true
  },
  "relationship": {
    "parent_ref": {
      "kind": "trace",
      "id": "trace_2026_09_15_1030"
    },
    "entity_refs": [
      {"kind": "agent", "id": "agent:billing-assistant"},
      {"kind": "tool", "id": "tool:postgres_query"},
      {
        "kind": "vendor.dataset",
        "id": "resource:payments.transactions",
        "digest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
        "schema_id": "vendor.dataset-manifest",
        "schema_version": "2.0",
        "source_product": "vendor"
      }
    ],
    "policy_ref": {
      "policy_id": "prod.tool-access",
      "policy_version": "v3",
      "policy_digest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  },
  "integrity": {
    "record_hash": "sha256:def456...",
    "previous_record_hash": "sha256:ghi789...",
    "signing_key_id": "a1b2c3...",
    "signature": "base64:..."
  }
}

Records are immutable, deterministic, and JSON-native — readable by any language, any tool, any text editor. Relationship fields are optional and schema-defined, so products can build graph queries later without changing the proof format. Relationship references can bind an ID to immutable bytes with digest and identify the producing contract with schema_id, schema_version, and source_product. New records normalize valid SHA-256 digests to lowercase while preserving whether the caller supplied the sha256: prefix. Existing built-in reference and edge kinds remain valid; extensions use lowercase dot-separated names such as vendor.dataset or vendor.derived-from. Unknown additive relationship fields are preserved and remain covered by record hashes and signatures.

Built-in Record Types

18 types covering the full AI governance surface, each with its own JSON Schema:

Record types are extensible. Define a custom type by providing a JSON Schema that extends the base record schema.

Hash Chains

Records are chained — each record's hash includes the previous record's hash, creating a tamper-evident sequence. Modify or delete a record and the chain breaks. proof chain verify identifies the exact break point.

Record 1 → hash(record_1)                      →┐
Record 2 → hash(record_2 + prev_hash)           →┐
Record 3 → hash(record_3 + prev_hash)           →┐
...
$ proof chain verify ./records/
Chain intact. 1,427 records. No gaps.

This is not blockchain. It is the same mechanism used in certificate transparency logs. Simple, proven, auditable.

Signing

Two backends, one verification surface:

• Ed25519 (default) — Fast, offline, no external dependencies
• Cosign / Sigstore — Supply chain ecosystem alignment, OIDC keyless signing

Both backends produce records that pass chain verification. The signing backend is transparent to the verifier. Key management supports customer-managed keys, ephemeral keys for development, and key revocation with signed revocation lists.

Canonicalization

Deterministic serialization is essential for hash stability. Proof implements canonicalization across four domains:

All digests carry algo_id (sha256 or hmac-sha256) and optional salt_id metadata.

Compliance Framework Definitions

YAML files declare what regulatory controls require and which evidence paths can satisfy them. Proof evaluates deterministic evidence coverage only. It does not decide regulatory applicability, scope gating, or compliance status.

controls:
  - id: article-12
    title: Record-Keeping
    evidence_sets:
      - id: runtime_control
        source_products: [gait]
        required_record_types: [tool_invocation, permission_check, compiled_action]
        required_fields: [record_id, timestamp, source, source_product, record_type, event, integrity.record_hash]
        minimum_frequency: continuous
      - id: combined
        source_products: [wrkr, gait]
        required_record_types: [scan_finding, tool_invocation, compiled_action]
        required_fields: [record_id, timestamp, source, source_product, record_type, event, integrity.record_hash]
        minimum_frequency: continuous

10 built-in starter frameworks ship with v1 (79 controls total). Add custom frameworks via YAML.

Built-ins are starter definitions; teams can add custom frameworks via YAML files. Control IDs/titles for AIUC-1 and OWASP Agentic Top 10 are sourced from their published framework documents.

• AIUC-1: https://aiuc-1.com/data-and-privacy (and linked Security/Safety/Reliability/Accountability/Society sections)
• OWASP Agentic Top 10: https://genai.owasp.org/resource/agentic-top-10/

CLI Reference

proof verify <path>                    Verify record, chain, bundle, or Gait artifact
  --chain                              Verify chain integrity
  --signatures                         Verify signatures
  --public-key <hex|base64>            Ed25519 public key
  --cosign-key <path>                  Cosign public key
  --cosign-cert <path>                 Cosign certificate
  --cosign-cert-identity <id>          Expected certificate identity
  --cosign-cert-issuer <issuer>        Expected OIDC issuer
  --custom-type-schema <type>=<path>   Custom type schema (repeatable)
  --revocation-list <path>             Signed key revocation list
  --revocation-key <hex>               Revocation list signer public key

proof inspect <path>                   Human-readable artifact display
  --record <record_id>                 Inspect specific record by ID

proof chain verify <path>              Verify chain integrity
  --from <RFC3339>                     Start of time range
  --to <RFC3339>                       End of time range

proof types list                       List all registered record types
proof types validate <schema-path>     Validate a custom record type schema

proof frameworks list                  List built-in starter framework definitions
proof frameworks show <id|path>        Display framework controls

proof completion <shell>               Shell completion generation

Global flags: --json, --quiet, --explain

Exit Codes

Stable contract. CI pipelines can rely on consistent semantics across all tools that adopt this vocabulary.

Gait Compatibility

Proof verifies Gait artifacts directly — packs, runpacks, and signed JSON — without any Gait dependency:

proof verify ./gait-pack.zip
proof verify ./gait-runpack.zip
proof verify --signatures --public-key <key> ./gait-pack.zip

The signing and canonicalization code in Proof was extracted from Gait's production codebase. KeyID(), Signature{}, and JCS digest functions produce byte-identical output, so artifacts signed by Gait before the extraction verify correctly with Proof.

Compatibility packages for migration:

• github.com/Clyra-AI/proof/signing — Ed25519 key management with dev/prod modes
• github.com/Clyra-AI/proof/canon — CanonicalizeJSON() and DigestJCS() aliases
• github.com/Clyra-AI/proof/schema — ValidateJSON() and ValidateJSONL() helpers
• github.com/Clyra-AI/proof/exitcode — Exit code constants with legacy aliases

Public API support and deprecation status are documented in docs/api-contract.md. Python-first integration patterns are documented in docs/python-integration.md.

Design Principles

1. The spec is the product. JSON Schema files are the normative specification. The Go module is the reference implementation. If they disagree, the spec wins.
2. Zero opinions. Proof does not know what compliance means. It creates, chains, signs, and verifies. What records mean is someone else's problem.
3. Boring cryptography. Ed25519 (RFC 8032), SHA-256, RFC 8785. No novel constructions, no experimental algorithms.
4. Library-first, CLI-second. The Go module is the primary artifact. The CLI is a thin wrapper. Every command maps to a module function.
5. Extracted, not greenfield. Built by extracting production-proven code from Gait, not by writing from scratch. Same pattern as Sigstore (extracted from cosign), OCI (extracted from Docker), HCL (extracted from Terraform).
6. Offline-first. All core operations — create, chain, sign, verify — work without network access. Air-gapped environments are first-class.

Repository Layout

cmd/proof/           CLI (Cobra-based)
core/
  record/            Record creation, validation, hashing
  chain/             Hash chain append and verification
  signing/           Ed25519 + cosign signing
  bundle/            Bundle manifests and bundle sign/verify
  canon/             Canonicalization (JSON, SQL, URL, text)
  schema/            JSON Schema validation + type registry
  framework/         YAML framework definition loading
  gait/              Gait pack/runpack compatibility verification
  errors/            Structured library errors (kind/code/path/field)
  exitcode/          Exit code constants
signing/             Compatibility package (Gait migration)
canon/               Compatibility package (Gait migration)
schema/              Compatibility package (Gait migration)
exitcode/            Compatibility package (Gait migration)
schemas/v1/          JSON Schema spec files (language-agnostic contract)
  types/             18 record type schemas
frameworks/          10 compliance framework YAML definitions
docs/                Supplementary format and interoperability documentation
testdata/            Golden vectors and test fixtures
scripts/             Test and validation scripts
perf/                Performance budgets

Development

make fmt             # Format
make lint            # Vet + golangci-lint
make test            # Unit tests
make prepush-full    # Full gate: lint + test + coverage + contract + integration + e2e + acceptance
make test-uat-local  # UAT for source/go-install/local-release paths; add --brew for Homebrew install path

CI pipelines: main, PR, determinism (cross-platform), CodeQL, nightly (hardening + chaos + performance + soak), release (GoReleaser + checksums + SBOM + cosign + SLSA provenance).

Install

# Verified one-command install (Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/Clyra-AI/proof/main/scripts/install.sh | sh

# Optional: pin a specific tag
curl -fsSL https://raw.githubusercontent.com/Clyra-AI/proof/main/scripts/install.sh | sh -s -- --version v1.2.3

Homebrew publication path:

brew tap Clyra-AI/homebrew-tap
brew install proof

Go module and CLI install:

PROOF_VERSION="$(gh release view --repo Clyra-AI/proof --json tagName -q .tagName 2>/dev/null || curl -fsSL https://api.github.com/repos/Clyra-AI/proof/releases/latest | python3 -c 'import json,sys; print(json.load(sys.stdin)[\"tag_name\"])')"
go install github.com/Clyra-AI/proof/cmd/proof@"${PROOF_VERSION}"
go get github.com/Clyra-AI/proof@"${PROOF_VERSION}"

Release checksum/signature verification:

PROOF_VERSION="$(gh release view --repo Clyra-AI/proof --json tagName -q .tagName)"
gh release download "${PROOF_VERSION}" -R Clyra-AI/proof -D /tmp/proof-release
cd /tmp/proof-release
sha256sum -c checksums.txt

# Optional if cosign is installed and signature assets are present
cosign verify-blob \
  --certificate checksums.txt.pem \
  --signature checksums.txt.sig \
  checksums.txt

See docs/release-distribution.md for full release and Homebrew publication workflow.

Project Docs

• docs/api-contract.md
• docs/python-integration.md
• CONTRIBUTING.md
• SECURITY.md
• CHANGELOG.md

License

See LICENSE.