qp-capsule 1.0.0

Capsule Protocol Specification (CPS) — tamper-evident audit records for AI operations. Create, seal, verify, and chain Capsules in Python.

Capsule Protocol Specification (CPS)

Tamper-evident audit records for AI operations.

---

What is a Capsule?

A Capsule is a cryptographically sealed record of a single AI action. It has six sections that capture the complete audit trail for that action: what initiated it, what the system state was, why the AI made the decision it made, who or what authorized it, what tools were called, and what the outcome was.

Every Capsule is hashed with SHA3-256 and signed with Ed25519. Each Capsule records the hash of the previous one, forming a chain where tampering with any record invalidates every record that follows.

∀ action: ∃ capsule
"For every action, there exists a Capsule."

Why Capsules?

AI systems make thousands of autonomous decisions. When something goes wrong — or when a regulator asks "why did the AI do that?" — you need evidence that existed before the question was asked.

Capsules solve three problems that logging does not:

1. Pre-execution reasoning capture. Section 3 (Reasoning) records the AI's analysis, the options it considered, the option it selected, and why it rejected the alternatives — all captured before Section 5 (Execution) runs. This is contemporaneous evidence of deliberation, not a post-hoc reconstruction.

2. Cryptographic tamper evidence. Every Capsule is hashed and signed at the moment of creation. If anyone modifies the content after the fact, the hash changes, the signature fails, and the chain breaks. This is not a property of the storage layer — it is a property of every individual record.

3. Cross-language interoperability. The Capsule Protocol Specification defines byte-level serialization rules. A Capsule sealed in Python can be verified in Go, Rust, or TypeScript. All implementations produce identical canonical JSON for the same input, validated by 15 golden test vectors.

How It Works

The 6 Sections

Every Capsule records a complete action through six mandatory sections:

┌─────────────────────────────────────────────────────────┐
│                       CAPSULE                           │
├─────────────┬───────────────────────────────────────────┤
│ 1. Trigger  │ What initiated this action?               │
│ 2. Context  │ What was the state of the system?         │
│ 3. Reasoning│ Why was this decision made?               │
│ 4. Authority│ Who or what approved it?                  │
│ 5. Execution│ What tools were called?                   │
│ 6. Outcome  │ Did it succeed? What changed?             │
├─────────────┴───────────────────────────────────────────┤
│ SHA3-256 hash │ Ed25519 signature │ ML-DSA-65 (opt.)    │
│ Previous hash │ Sequence number   │ Timestamp           │
└─────────────────────────────────────────────────────────┘

The Hash Chain

Each Capsule records the SHA3-256 hash of the previous Capsule. This creates a chain where modifying, deleting, or inserting any record is immediately detectable.

Capsule #0          Capsule #1          Capsule #2
┌──────────┐        ┌──────────┐        ┌──────────┐
│ hash: A  │◀───────│ prev: A  │◀───────│ prev: B  │
│ prev: ∅  │        │ hash: B  │        │ hash: C  │
└──────────┘        └──────────┘        └──────────┘

No consensus mechanism. No distributed ledger. SHA3-256 hashes linking one record to the next.

The Cryptographic Seal

Every Capsule is sealed with a two-tier cryptographic architecture:

Layer	Algorithm	Standard	Purpose
Content integrity	SHA3-256	FIPS 202	Tamper-evident hashing
Classical signature	Ed25519	RFC 8032 / FIPS 186-5	Authenticity and non-repudiation
Post-quantum signature	ML-DSA-65	FIPS 204	Quantum-resistant protection (optional)
Temporal integrity	Hash chain	CPS v1.0	Ordering and completeness

Ed25519 is always required. ML-DSA-65 runs alongside Ed25519 as an optional dual signature (pip install qp-capsule[pq]). No deprecated cryptography. No runtime network dependencies. Air-gapped operation supported.

---

Quick Start

pip install qp-capsule

from qp_capsule import Capsule, Seal, CapsuleType, TriggerSection

# Create a Capsule
capsule = Capsule(
    type=CapsuleType.AGENT,
    trigger=TriggerSection(
        type="user_request",
        source="deploy-bot",
        request="Deploy service v2.4 to production",
    ),
)

# Seal it — SHA3-256 hash + Ed25519 signature
seal = Seal()
seal.seal(capsule)

# Verify it — anyone can, anytime
assert seal.verify(capsule)

With Hash Chain

pip install qp-capsule[storage]

from qp_capsule import Capsule, Seal, CapsuleChain, CapsuleStorage, CapsuleType, TriggerSection

storage = CapsuleStorage()
chain = CapsuleChain(storage)
seal = Seal()

capsule = Capsule(
    type=CapsuleType.AGENT,
    trigger=TriggerSection(source="deploy-bot", request="Deploy v2.4"),
)

# One call: chain + seal + store
capsule = await chain.seal_and_store(capsule, seal)

# Verify the entire chain
result = await chain.verify()
assert result.valid

---

Install

pip install qp-capsule

Cross-language SDKs (TypeScript, Go, Rust) are planned. The CPS specification and 15 golden test vectors define the byte-level contract — any conforming implementation can seal and verify Capsules interchangeably.

Python extras

Command	What You Get	Dependencies
pip install qp-capsule	Create, seal, verify	1 (pynacl)
pip install qp-capsule[storage]	+ Hash chain + SQLite persistence	2 (+ sqlalchemy)
pip install qp-capsule[postgres]	+ Hash chain + PostgreSQL (multi-tenant)	2 (+ sqlalchemy)
pip install qp-capsule[pq]	+ Post-quantum ML-DSA-65 signatures	2 (+ liboqs)

---

Capsule Protocol Specification (CPS)

All implementations follow the Capsule Protocol Specification, which defines:

• Record structure — the 6-section Capsule model with all field types and defaults
• Canonical serialization — byte-level JSON rules for deterministic hashing
• Sealing algorithm — SHA3-256 + Ed25519 + optional ML-DSA-65
• Hash chain rules — sequence numbering and hash linking
• Golden test vectors — 15 conformance fixtures for cross-language verification

  Language A (seal)  ──→  Canonical JSON + SHA3-256 + Ed25519  ──→  Language B (verify) ✓

The specification is language-agnostic. Any implementation that passes the 15 golden test vectors can seal and verify Capsules produced by any other.

Full specification: specs/cps/

---

Examples

The examples/ directory contains realistic Capsule records showing the 6-section model in practice:

Example	Type	Scenario
deploy-to-production.json	AGENT	Production deployment with structured reasoning, human approval, and tool calls
file-read-tool.json	TOOL	Simple tool invocation by an agent
kill-switch-activation.json	KILL	Emergency stop triggered by anomaly detection
chat-with-rag.json	CHAT	RAG query with source attribution and model metadata
policy-denied-action.json	TOOL	Destructive action blocked by safety policy
multi-step-workflow.json	WORKFLOW	Three linked Capsules showing parent-child hierarchy

---

Custom Storage Backends

Capsule ships with SQLite and PostgreSQL storage. To build your own backend, implement CapsuleStorageProtocol — a runtime-checkable typing.Protocol with 7 async methods. Any conforming backend plugs directly into CapsuleChain. See Architecture for details.

---

Documentation

Document	Audience
Getting Started	Developers
Architecture	Developers, Auditors
API Reference	Developers
Security Evaluation	CISOs, Security Teams
Compliance Mapping	Regulators, GRC
CPS Specification	SDK Authors
Audit Report	CISOs, Auditors

---

Contributing

See CONTRIBUTING.md. Protocol changes go through the CPS change proposal process.

License and Patents

Apache License 2.0 with additional patent grant. You can use all patented innovations freely for any purpose, including commercial use.

Full Platform

This package provides the protocol primitives. For the full autonomous AI platform with Vault, Cognition, Intelligence, and Hub, see Quantum Pipes Core.

---

∀ action: ∃ capsule

Python reference implementation · Cross-language SDKs planned

Website · Full Platform · CPS Specification · Security Policy · Patent Grant

Copyright 2026 Quantum Pipes Technologies, LLC