PSR-001: PrimeSwarm Receipt Format Specification

Status: Draft v0.1 Published: 2026-09-12 Authors: Grigori Korotkikh, Only Institute License: MIT (the spec is open; implementations may be commercial)

Abstract

This specification defines a receipt format for AI agent governance decisions. A receipt is a cryptographically verifiable record that proves a governance gate evaluated a specific input against a specific policy and produced a specific decision. An auditor can replay the receipt using an open-source verifier and confirm the decision without trusting the system that produced it.

This format is designed to be framework-agnostic. Any AI governance system — PrimeSwarm, Microsoft AGT, NVIDIA NeMoClaw, or a custom implementation — can produce PSR-001 receipts. The format does not require ONLY Lang, PrimeSwarm, or any specific vendor.

Conformance Notation

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in BCP 14 [RFC 2119] [RFC 8174] when, and only when, they appear in all capitals.

1. Motivation

Most AI systems produce logs. A log says "this happened." A receipt says "this happened, here is the proof, and here is how you can verify it."

Logs are append-only narratives. They are useful for debugging. They are not useful for compliance. An auditor cannot replay a log entry and verify that the system made the correct decision. They can only trust that the log is accurate.

Receipts are cryptographic proofs. They include the policy that was evaluated, the input hash, the decision, and a hash that binds them together. An auditor can replay the evaluation and verify the result independently. They do not need to trust the receipt — they can verify it.

This specification defines the receipt format so that auditors, SIEM systems, and compliance tools can parse receipts from any conforming implementation using a single interface.

2. Receipt Structure

A PSR-001 receipt is a JSON document with the following fields:

### 2.1 Policy Object

The policy object describes what was evaluated.

For ONLY Lang policies, script_hash is the SHA-256 of the script text. For YAML policies (e.g., AGT), script_hash is the SHA-256 of the YAML file. For Rego policies, script_hash is the SHA-256 of the .rego file.

2.2 Input Object

The input object describes what was evaluated. PII MUST be stripped before hashing.

### 2.3 Evidence Object

The evidence object contains the proof that the evaluation produced the stated decision.

### 2.4 Identity Object

The identity object binds the decision to the agent that proposed it and the human that approved it, if applicable.

### 2.5 Governance Root Object

The governance_root object records the authority state at authorization time (T₀). It answers: who authorized this agent, under what role, on what basis, and in what context.

This object is OPTIONAL for PSR-001 v0.1 conformance but REQUIRED for Runtime Authority Continuity (see §12).

The actors array records the human or system that authorized the agent. If a compliance officer authorized an agent to make lending decisions, the actors array records their identity, role, and the scope of authority granted.

The lineage array forms a hash-linked chain. Each entry contains the receipt_hash of a prior receipt in the delegation chain. This creates a temporal chain of authority from the original authorization through every intermediate step to the current execution. An auditor can trace the full chain without trusting any single receipt.

The context_t0 object records the state of the world when authority was granted. At execution time (T₁), the gate compares context_t0 to context_t1 (in gate_decision) to detect condition drift.

2.6 Gate Decision Object

The gate_decision object records the authority state at execution time (T₁). It answers: was the authority from T₀ still valid when the action was actually executed?

This object is OPTIONAL for PSR-001 v0.1 conformance but REQUIRED for Runtime Authority Continuity (see §12).

The gate evaluates the action against current policy (as in §2.1–§2.3). It also evaluates whether the authority behind the action survived until the moment of execution. If authority_still_valid is false, the gate MUST DENY regardless of the action's compliance with policy. A technically compliant action executed under revoked authority is a governance failure.

3. Receipt Hash

The receipt_hash binds all REQUIRED fields of the receipt. It is computed as:

1. Construct a canonical JSON string containing only the REQUIRED fields: spec_version, receipt_id, timestamp, gate_state, policy, input, evidence, and receipt_hash itself set to the empty string. 2. Sort object keys lexicographically (RFC 8785 JSON Canonicalization Scheme). 3. Compute SHA-256 of the canonical JSON string. 4. The resulting hex digest is the receipt_hash.

The receipt_hash field in the receipt MUST match the hash computed by this procedure. If it does not, the receipt is invalid.

4. Signature

The signature object is OPTIONAL but RECOMMENDED for production deployments.

An auditor verifies the signature by: 1. Decoding the public key and signature from base64. 2. Verifying the Ed25519 signature over the receipt_hash using the public key. 3. If verification succeeds, the receipt is authentic. If it fails, the receipt is forged or tampered.

5. Replay Verification

An auditor verifies a receipt by replaying the evaluation:

1. Retrieve the policy script. Use policy.script_source or obtain the script through other means. Verify that SHA-256(script) == policy.script_hash. 2. Reconstruct the input. Use evidence.replay_inputs to reconstruct the exact input that was evaluated. Verify that SHA-256(sanitized_input) == input.input_hash. 3. Run the verifier. Execute the policy script against the reconstructed input using an open-source verifier (e.g., the ONLY Lang WASM verifier, or a conforming verifier for the stated policy.language). 4. Compare the result. The verifier's output MUST match: - gate_state - evidence.residual (if present) - evidence.indices_healed (if present) - evidence.reason_codes (if present) 5. Verify the hash. Recompute the receipt_hash per §3. It MUST match. 6. Verify the signature. If present, verify per §4.

If all checks pass, the decision is verified. The auditor did not need to trust the system — they verified it.

6. Example Receipt

{
  "spec_version": "PSR-001",
  "receipt_id": "rcpt_2026-09-12T14:30:00Z_a1b2c3d4",
  "timestamp": "2026-09-12T14:30:00.123Z",
  "gate_state": "ALLOW",
  "reason": "Budget within limits, bounds satisfied, no bias detected",
  "policy": {
    "language": "only-lang",
    "version": "1.2.0",
    "script_hash": "a3f5e8c1d2b4...",
    "script_source": "https://only.institute/policies/lending-v1.2.0.only"
  },
  "input": {
    "input_hash": "f7e2d1c9b8a6...",
    "input_type": "transaction",
    "field_values": [0.45, 0.30, 0.25],
    "metadata": {
      "tool": "loan_approval",
      "action": "approve",
      "amount_sanitized": true
    }
  },
  "evidence": {
    "residual": 0.0000000123,
    "residual_history": [0.15, 0.08, 0.03, 0.0000000123],
    "indices_healed": [2],
    "reason_codes": ["within_budget", "within_bounds", "no_bias"],
    "explanation": "Field 2 was healed from 0.0 to 0.25. Residual converged to 1.23e-8.",
    "replay_inputs": {
      "signs": [1, -1, 1, -1],
      "field": [0.45, 0.30, 0.25, 0.0],
      "script": "harmony([0.5, 0.3, 0.2])\nassert_bounds(0, 50, 0)\nbudget_limit(500)"
    }
  },
  "identity": {
    "agent_id": "loan-agent-001",
    "human_approver_id": null
  },
  "governance_root": {
    "actors": [
      {
        "actor_id": "compliance-officer-42",
        "actor_hash": "a1b2c3d4e5f6...",
        "role": "compliance_officer",
        "authority_scope": "lending_decisions"
      }
    ],
    "lineage": [
      {
        "receipt_hash": "f8e3d2c1b0a9...",
        "receipt_id": "rcpt_2026-09-12T10:00:00Z_x9y8z7",
        "timestamp": "2026-09-12T10:00:00.000Z"
      }
    ],
    "policy_version": "1.2.0",
    "justification": "Agent authorized for loan approvals up to $50k with credit score >= 700",
    "context_t0": {
      "timestamp": "2026-09-12T10:00:00.000Z",
      "data_hash": "b4c5d6e7f8a9...",
      "policy_hash": "a3f5e8c1d2b4...",
      "metadata": {
        "credit_score": 720,
        "max_loan_amount": 50000
      }
    }
  },
  "gate_decision": {
    "context_t1": {
      "timestamp": "2026-09-12T14:30:00.123Z",
      "data_hash": "c5d6e7f8a9b0...",
      "policy_hash": "a3f5e8c1d2b4...",
      "metadata": {
        "credit_score": 720,
        "max_loan_amount": 50000
      }
    },
    "authority_still_valid": true,
    "condition_drift": false,
    "condition_drift_fields": [],
    "revocation_detected": false,
    "lineage_intact": true
  },
  "receipt_hash": "e9c4f7a2b1d8...",
  "signature": {
    "algorithm": "ed25519",
    "public_key": "MCowBQYDK2VwAyEA...",
    "signature": "MEUCIQDk..."
  }
}

7. SIEM Integration

Receipts are designed to be forwarded to SIEM systems (Splunk, Datadog, Elastic, Sumo Logic, QRadar). The recommended forwarding format is:

• Transport: HTTPS POST or HEC (Splunk) or equivalent
• Encoding: JSON (this spec)
• Event type: primeswarm.receipt
• Indexing: By receipt_id, timestamp, gate_state, agent_id

A SIEM query for all DENY decisions in a time range:

index=ai_governance event_type="primeswarm.receipt" gate_state="DENY"
| stats count by reason_codes

8. Framework Compatibility

This format is designed to be produced by any governance system, not just PrimeSwarm:

A conforming implementation MUST: 1. Produce all REQUIRED fields. 2. Compute receipt_hash per §3. 3. Strip PII before computing input_hash. 4. Include evidence.replay_inputs sufficient for independent verification.

9. What This Spec Does Not Require

• It does not require ONLY Lang. Any policy language works.
• It does not require PrimeSwarm. Any governance system can produce conforming receipts.
• It does not require a specific verifier. Any open-source verifier that can replay the evaluation is sufficient.
• It does not require Ed25519 signatures. Signatures are RECOMMENDED but OPTIONAL.
• It does not require a specific SIEM. The JSON format is SIEM-agnostic.

10. Open Source Verifier

The Only Institute provides an open-source verifier for ONLY Lang receipts at:

• WASM verifier: github.com/only-institute/only-lang-wasm — runs in any browser, 162KB
• CLI verifier: github.com/only-institute/dgv-verifier — runs on any platform with Rust
• Test card catalogue: 89 website definitions, including proposed authority-continuity coverage. Catalogue size is not an executed-test or receipt count — dgv-verification-deck

For non-ONLY-Lang receipts, the auditor must use a verifier appropriate for the stated policy.language. The receipt format is the interface; the verifier is the implementation.

11. Versioning

This is version 0.1 (Draft). The spec version string is PSR-001.

Future versions:

• PSR-002 — adds batch receipts (multiple decisions in one document)
• PSR-003 — adds Merkle chain (hash-linked receipt sequences)
• PSR-004 — adds cross-system attestation (multiple systems co-signing a decision)

Breaking changes require a new spec version string. Non-breaking additions (new OPTIONAL fields) do not.

12. Runtime Authority Continuity

The problem

An agent can receive valid authority at T₀. By T₁, when it reaches the execution boundary, the conditions surrounding that authority may have changed. The data may be different. The policy may have changed. The delegation may have expanded. The risk may have changed. The intended objective may no longer match the action. Yet the technical permission can still remain active.

This creates a distinction: permission to act ≠ continuing authority to act.

Access control can establish that an agent is permitted to perform an action. Governance continuity asks something harder: was the authority still valid when the consequential action was actually executed?

The temporal governance chain

AUTHORIZATION → DELEGATION → CHANGING CONDITIONS → RUNTIME REASSESSMENT → EXECUTION → EVIDENCE

If governance verifies only the beginning of that chain, it may prove that the agent was authorized once without proving that the authority remained valid at execution.

How PSR-001 addresses this

The governance_root object (§2.5) records the authority state at T₀:

• Who authorized the agent (actors)
• The delegation chain (lineage)
• The policy version (policy_version)
• Why authority was granted (justification)
• The context when authority was granted (context_t0)

The gate_decision object (§2.6) records the authority state at T₁:

• The context at execution time (context_t1)
• Whether authority was still valid (authority_still_valid)
• Whether conditions drifted (condition_drift)
• Whether revocation was detected (revocation_detected)
• Whether the lineage chain is intact (lineage_intact)

These objects describe proposed evidence fields, not verified relationships. Their presence does not establish actor identity, delegation, revocation freshness or continuous authority. The legacy hash procedure in §3 does not bind these optional top-level objects; an implementation MUST NOT claim authenticated authority evidence from that legacy hash. A versioned, fully bound profile and runtime verification are required.

Proposed ONLY Lang commands (not implemented by the local experiment)

The following table specifies intended semantics. Website syntax highlighting and test-card descriptions do not implement these commands or demonstrate interpreter support. TC-070 through TC-089 remain proposed coverage until backed by executable fixtures and measured results:

If check_authority fails, the gate MUST DENY. If check_context_drift returns true, the gate MUST ESCALATE. If check_revocation returns true, the gate MUST DENY. If require_continuous_lineage finds a gap, the gate MUST DENY. If check_objective_drift finds the action outside the authorized scope, the gate MUST DENY.

Implemented experiment: Objective Contracts for quote preparation

The Python evaluator in only-dgv-verifier/objective_contract.py checks a structured contract against a proposed prepare_quote action and a separate host-supplied context. It checks the customer, service, currency, aggregate budget, actor, policy version, contract expiry, snapshot freshness, contract review and exact-proposal approval. Explicit unresolved requirements escalate rather than being interpreted as permission. It does not interpret natural-language intent.

Run dgv_runner.py --objective-experiment in the verifier repository to reproduce 28 synthetic cases. Results and replay inputs are in evidence/objective_contract_experiment.json; unit tests additionally check tampering, rehashed false decisions, evidence substitution, strict JSON parsing, boundary values and CLI behavior. These measured cases are separate from the numbered website cards and are not a certification.

Experimental receipts use DGV-OBJECTIVE-EXPERIMENT-1, not the PSR-001 legacy hash contract. All receipt fields except receipt_hash are covered by SHA-256. Canonicalization is sorted-key compact ASCII JSON with safe integer values, ordered arrays, booleans and null; duplicate keys and floats are rejected. No general RFC 8785 conformance or digital signature is claimed.

The replay verifier re-evaluates all recorded predicates and compares the complete receipt. Without an independent original request/context it returns UNVERIFIABLE. With a matching host-supplied reference it returns VERIFIED_AGAINST_SUPPLIED_CONTEXT, not an authorization to execute again. External identity, approval and revocation assertions are not authenticated by this experiment.

Implemented experiment: revocation propagation with two local gates

The Python module only-dgv-verifier/revocation_store.py implements a versioned authority store backed by SQLite. Authority checks, token consumption and the synthetic destination write all happen inside one BEGIN IMMEDIATE transaction. A gate cannot authorize a write using a stale cached authority, because the check and the write commit together or fail together.

Run dgv_runner.py --revocation-experiment in the verifier repository to reproduce 36 cases: 12 sequential scenarios plus 24 simultaneous revoke/write races using two local gate processes against one temporary SQLite database. Results, the full committed history snapshot, measurements and a report hash are in evidence/revocation_experiment.json; unit tests additionally check tampering, audit reordering, clock rollback, store identity, token binding, expiry and CLI behavior.

The experiment demonstrated:

• A gate with a stale cached authority cannot execute after revocation commits — the execution check runs inside the same transaction as the write.
• Store unavailability (locked database) fails closed — no cached-permission fallback.
• One-use tokens are bound to the exact action, payload and destination.
• 24 simultaneous revoke/write races all resolved correctly, ordered by transaction commit.
• A write committed before revocation is not retroactively undone.
• The committed history is independently auditable: reordering, omission or payload alteration is detected.

This does not prove:

• Network partition resilience: the "unavailable store" case is a SQLite lock timeout, not a real network outage.
• Replicated consensus: one SQLite database, one writer at a time. Multi-region deployment needs consensus to maintain the same guarantee.
• Authenticated identities: trusted local processes have direct database access.
• External exactly-once: commit errors are unconfirmed — reconcile by action ID before retrying.
• Production SLA: latency samples describe this run only.

The report hash is not a digital signature. An independent trusted checkpoint is needed to detect wholesale replacement.

Still outside the demonstrated scope

• Live integration: no CRM writes or ONLY Lang interpreter integration. No quote was sent or accepted.
• Semantic completeness: a human must review whether the contract captures the objective. The evaluator cannot detect an omitted requirement in free text.
• Network-scale authority: no network partition, replicated consensus or multi-region propagation is tested. The revocation experiment uses two local processes against one SQLite database.
• Atomic enforcement: aggregate checks require a complete authoritative ledger and atomic check-and-reserve at the live write boundary. The revocation experiment tests synthetic writes, not CRM actions.
• Independent assurance: the native verifier source is now published in native/. An audit package (AUDIT_PACKAGE.md) and differential test (differential_test.py) are provided. However, no named third party has completed an audit. A passing card description is not a build comparison. The native binary simulates most governance checks via hard-coded responses rather than computing them.

Conformance

Including governance_root and gate_decision MUST NOT be treated as proof of Runtime Authority Continuity. Legacy PSR-001 compatibility and authority-evidence verification are separate questions. The experimental Objective Contract profile is explicitly separate; migrating it into PSR-001 requires a versioned schema, canonicalization and trust-model review. A receipt establishes only the relationships actually verified against trustworthy evidence, not legal certification.

References

• RFC 2119 — Key words for use in RFCs
• RFC 8785 — JSON Canonicalization Scheme
• Ed25519 — Edwards-curve Digital Signature Algorithm
• OWASP Agentic Top 10 — Agentic security risks
• NIST AI RMF 1.0 — AI Risk Management Framework

Appendix A: JSON Schema

A machine-readable JSON Schema for PSR-001 receipts is available at /specs/psr-001/schema.json. Implementations SHOULD validate receipts against this schema before accepting them.

Appendix B: Mapping to Existing Implementations

PrimeSwarm VerificationReceipt (dgv-verifier)

The existing VerificationReceipt struct maps to PSR-001 as follows:

### PrimeSwarm EvidencePack (only-lang)

The existing EvidencePack struct maps to PSR-001 as follows:

### Microsoft AGT Audit Entry

AGT's audit entry maps to PSR-001 as follows:

AGT's Merkle hash chain provides tamper detection but not replay verification. A conforming AGT-to-PSR-001 adapter would need to add policy.script_hash, input.input_hash, and evidence.replay_inputs to enable independent replay.