PIC Standard: Provenance & Intent Contracts

Local-first action gating for AI agents. Verify intent, provenance, and evidence before any high-impact tool call executes.

Contributors wanted. PIC is recruiting its first external contributors and co-maintainers. Start with the call for contributors and the pinned good-first issues. Today, PIC has a Python reference implementation; a second implementation in TypeScript, Go, or Rust is open to own (#48).

PIC is a lightweight, local-first protocol that forces AI agents to prove every important action before it happens. Agents must declare intent, impact, provenance, and evidence; PIC verifies everything and fails closed if anything is wrong.

PIC is not agent identity or delegation infrastructure; PIC is the action-bound verification contract that decides whether a high-impact tool call is justified to execute now.

No more hallucinations turning into wire transfers. No more prompt injections triggering data exports.

Example — when PIC blocks: A Slack message asks an LLM agent to send a $500 payment. PIC requires the agent to prove: where did this instruction come from? Is the source trusted? Is there evidence the invoice is real? The Slack message carries no trusted provenance, the claim has no backing evidence — PIC returns block. The payment tool never executes.

Table of Contents

• Why PIC?
• Quickstart
• The PIC Contract
• How It Works
• Evidence Verification
• Keyring (Trusted Signers)
• Integrations
• RFC & Prior Art
• Roadmap
• Project info
• Contributing

Why PIC?

Guardrails constrain what the model says. PIC constrains what the agent is allowed to do based on verifiable provenance + evidence.

PIC is built for agent frameworks, internal tool gateways, and production systems where high-impact actions must be justified before execution.

• Stops prompt injections & blind tool calls at the action boundary
• Works 100% locally: zero cloud, zero data leaves your machine
• Plugs into your stack in minutes: LangGraph, MCP, OpenClaw, Cordum
• Open-source (Apache 2.0): audit it, fork it, own it

Quickstart

Try the verifier locally against a sample high-impact proposal in under a minute.

pip install pic-standard

# Verify an example proposal
pic-cli verify examples/financial_irreversible.json

# Evidence-aware verification (hash + signature; hash proves integrity,
# signature provides authority for trust upgrade under v0.8.3)
# macOS / Linux
PIC_KEYS_PATH=pic_keys.example.json pic-cli verify examples/financial_hash_ok.json --verify-evidence
# PowerShell
# $env:PIC_KEYS_PATH="pic_keys.example.json"
# pic-cli verify examples/financial_hash_ok.json --verify-evidence

# Evidence-aware verification (signature — requires example keyring)
# macOS / Linux
PIC_KEYS_PATH=pic_keys.example.json pic-cli verify examples/financial_sig_ok.json --verify-evidence
# PowerShell
# $env:PIC_KEYS_PATH="pic_keys.example.json"
# pic-cli verify examples/financial_sig_ok.json --verify-evidence

Why the keyring on the hash example? Under v0.8.3 evidence semantics, a matching hash proves content-integrity of the referenced file bytes but does not, by itself, upgrade provenance trust. The signature evidence, verified against PIC_KEYS_PATH, supplies the authority-bearing trust upgrade for the money-impact action. See docs/spec-evidence.md §8 and issue #133.

Optional extras:

pip install "pic-standard[langgraph]"  # LangGraph PICToolNode
pip install "pic-standard[mcp]"        # MCP tool guarding
pip install "pic-standard[crypto]"     # Ed25519 signature evidence

From source (contributors):

git clone https://github.com/pic-standard/pic-standard.git
cd pic-standard && pip install -e ".[langgraph,mcp,crypto]"
pytest -q

The PIC Contract

PIC is enforced at the moment before tool execution. The agent must emit a structured Action Proposal that can be validated, verified, and bound to the intended tool.

Rule: For high-impact proposals, at least one claim must reference evidence from trusted provenance. Fail-closed.

How It Works

graph TD
    A[Untrusted Input] --> B{AI Agent / Planner}
    C[Trusted Data/DB] --> B
    B --> D[Action Proposal JSON]
    D --> E[PIC Verifier]
    E --> F{Valid Contract?}
    F -- Yes --> G[Tool Executor]
    F -- No --> H[Blocked / Alert Log]

How PIC Differs from Receipt / Audit / Reputation Systems

PIC is a pre-execution action-verification contract - a parallel surface in the agent-safety stack, not a primitive in a shared substrate. PIC decides at the action boundary whether a high-impact tool call is justified to execute now. Post-execution systems - bilateral receipts, signed audit logs, trust/reputation scores - record what already happened and are architecturally distinct.

PIC's pre-execution surface can contribute to Article 12-style traceability on the decision side: a verified Action Proposal is a structured decision artifact that may be incorporated into a high-risk AI system's record-keeping and logging architecture. PIC alone is not Article 12 compliance; it complements the broader system-level logging and retention duties in Articles 12 and 19. A post-execution attestation surface bound to the same primitives is drafted in docs/attestation-object-draft.md, kept local-first and operator-controlled by design.

Rule of thumb: if a system asks "should this action be allowed to run?", that's PIC's surface. If it asks "did this action run, and what's the agent's reputation?", that's a complementary post-execution surface — not a layer PIC sits inside.

Evidence Verification

PIC supports deterministic evidence verification that upgrades provenance trust in-memory.

Ed25519 signature verification requires pip install "pic-standard[crypto]".

# Verify hash evidence
pic-cli verify examples/financial_hash_ok.json --verify-evidence

# Verify signature evidence (requires keyring)
# macOS / Linux
PIC_KEYS_PATH=pic_keys.example.json pic-cli verify examples/financial_sig_ok.json --verify-evidence
# PowerShell
# $env:PIC_KEYS_PATH="pic_keys.example.json"
# pic-cli verify examples/financial_sig_ok.json --verify-evidence

Full guide: docs/evidence.md

Canonicalization (v0.8.0+): PIC Canonical JSON v1 (PIC-CJSON/1.0) defines the byte-exact serialization rules used when PIC hashes or signs JSON values. The normative spec is docs/canonicalization.md; a pure-stdlib reference implementation lives at pic_standard.canonical (canonicalize(), sha256_hex(), intent_digest_hex()). In v0.8.0 this is an additive capability — existing signature verification paths continue to work as in v0.7.x; wiring canonicalization into attestation-object-backed signatures is scheduled for a later release. Conformance vectors live under conformance/canonicalization/ and execute on every PR via the PIC Conformance CI job.

Keyring (Trusted Signers)

Signature evidence requires a keyring of trusted public keys with expiry and revocation support.

pic-cli keys                        # Inspect current keyring
pic-cli keys --write-example        # Generate starter keyring

Custom resolvers (v0.7+): As of v0.7, trust resolution is injectable and local-first. PIC no longer reloads the default keyring per signature, and custom resolvers can plug into the verifier and pipeline directly. Implement the KeyResolver protocol to use your own trust backend or preloaded trust source (HSM-backed service, Vault-managed keys, cached remote keyring, etc.):

from pic_standard import KeyResolver, StaticKeyRingResolver

Trust controls (v0.7.5+): PIC v0.7.5 introduces strict_trust mode — when enabled, all inbound provenance trust is sanitized to "untrusted" and only evidence verification can upgrade it. See docs/migration-trust-sanitization.md for migration guide.

Full guide: docs/keyring.md

Integrations

LangGraph

Guard any tool node with PICToolNode:

pip install "pic-standard[langgraph]"

PICToolNode now accepts verify_evidence, strict_trust, policy, and key_resolver for full pipeline configuration (v0.7.5+).

MCP (Model Context Protocol)

Enterprise tool guarding with fail-closed defaults, request correlation, DoS limits, and evidence sandboxing:

pip install "pic-standard[mcp]"

Full guide: docs/mcp-integration.md

OpenClaw

TypeScript plugin for OpenClaw AI agents (pic-gate, pic-init, pic-audit hooks):

pic-cli serve --port 7580
cd integrations/openclaw && npm install && npm run build

Full guide: docs/openclaw-integration.md

Cordum

Go Pack providing PIC verification as a Cordum workflow gate step with fail-closed three-way routing.

Full guide: docs/cordum-integration.md

HTTP Bridge (any language)

For non-Python integrations, PIC exposes an HTTP bridge:

pic-cli serve --port 3100
# POST /verify   — verify an action proposal
# GET  /health   — liveness check
# GET  /v1/version — package + protocol version

RFC & Prior Art

RFC-0001: PIC/1.0 — Provenance & Intent Contracts for AI Agent Action Safety

Formal specification covering scope, threat model, security properties, conformance levels, and prior art differentiation. Published as a defensive publication with a SHA-256 fingerprint manifest: docs/RFC-0001.SHA256.

Verify locally: sha256sum -c docs/RFC-0001.SHA256

Canonical Vocabulary — authoritative glossary of PIC terminology cited by external crosswalks and registries.

Roadmap

• Core verifier, CLI, schema, policy system
• Evidence verification (SHA-256 hash + Ed25519 signatures)
• Anchor integrations (LangGraph, MCP, OpenClaw, Cordum)
• Injectable key resolution + hot path fix (v0.7)
• Trust hardening + attestation object draft (v0.7.5)
• Canonicalization spec (PIC Canonical JSON v1) + reference implementation (v0.8.0)
• Initial conformance suite (canonicalization + core modes) with CI runner (v0.8.0)
• Cross-implementation conformance (TypeScript/Go verifier parity)
• Normative semantics (MUST/SHOULD spec document)
• OpenAPI spec + guard hardening (structured audit logs, request correlation)
• TypeScript local verifier (second independent implementation)

Project info

• Security policy — see SECURITY.md. Report vulnerabilities privately via GitHub Security Advisories; do not file public issues for security reports.
• Code of conduct — see CODE_OF_CONDUCT.md. PIC follows the Contributor Covenant 2.1. Reports go to team@madeinpluto.com.
• Citation — see CITATION.cff for full citation metadata. The Zenodo concept DOI 10.5281/zenodo.18725562 (badged at the top of this page) resolves to the latest archived release on Zenodo; per-version DOIs are listed on the Zenodo record.
• Foundation-track feedback — PIC Standard has undergone AAIF project-proposal review. The technical positioning was recognized; the current focus is expanding multi-organization maintainership, production adoption, and standards-track readiness.
• License — Apache-2.0; see LICENSE (also badged at the top of this page).

Contributing

We welcome contributions! See CONTRIBUTING.md for how to propose changes or report issues.

We're actively seeking:

• Security researchers to stress-test causal logic
• Framework authors to build native integrations
• Enterprise architects to define domain Impact Classes

Good first contribution areas right now: conformance vectors, OpenAPI spec, TS verifier groundwork, and security review of trust sanitization behavior.

If you find PIC useful, please consider giving us a star on GitHub: it helps attract more security experts and framework authors into the community.

Issues & ideas: GitHub Issues

Maintained by @fmsalvadori   MadeInPluto