Decision Passport: Core

Offline-verifiable authorization and execution receipts for AI agents, tools, workflows, and autonomous systems.

Decision Passport Core is the public protocol layer for creating, exporting, and independently verifying tamper-evident proof bundles.

It helps answer:

What was requested?
Who or what approved it?
What exact payload was bound?
What executed or failed?
Can the result be verified offline without trusting the original system?

TypeScript + Python reference · pnpm · Append-only chain · Offline verification · No database required

v0.9.0 — Autonomous Action Receipt Profile

Decision Passport Core now covers:

• Core proof bundles and offline verifier semantics.
• Tool-call execution receipts.
• Batch verification and local audit reports.
• Autonomous / physical-world action receipt profiles.

This section is normative for what this repository can prove in the current public line.

1. A bundle's record hashes, chain links, and manifest chain hash are internally consistent.
2. Payload tampering and chain mutation are detected by offline verification.
3. Verification runs offline with no database, API key, or cloud dependency.
4. v0.7.0 verifier semantics classify runtime-claim, outcome-linkage, revocation/supersession, and trail-linkage states on supported bundle surfaces.
5. v0.8.0 Tool Call Wrapper can bind requested input hash, authorization state, execution outcome, and output/error hash into a verifiable receipt.
6. v0.8.1 Batch Verification can verify receipt sets, classify verification failures, and generate local audit reports.
7. v0.9.0 Autonomous Action Receipt Profile can bind autonomous-action metadata, safety-envelope claims, sensor/context hashes, simulation hashes, and outcomes into verifiable proof bundles.

1. Runtime policy enforcement at execution time.
2. Distributed replay prevention.
3. Storage-level immutability by itself.
4. Who authored a bundle, unless a separate signing/identity layer is used.
5. That a hosted guard executor blocked or allowed execution in real time.
6. That an external tool provider performed a side effect beyond evidence bound into the receipt.
7. That autonomous systems are safe.
8. Functional safety certification.
9. Robot, vehicle, drone, or machine control.
10. NVIDIA, ROS, Isaac, Jetson, DRIVE, CUDA, or hardware integration.

Use this repository when you need portable, offline-checkable proof artifacts for:

• AI action history.
• Tool-call receipts.
• Workflow execution evidence.
• Batch verification and audit/conformance workflows.
• Autonomous or physical-world action receipt profiles.

Use stronger infrastructure when you need runtime guard enforcement, execution claims, distributed replay protection, tenant isolation, signed bundles, key management, identity attestation, regulated deployment controls, or physical safety systems.

Those belong in control-plane, sovereign, runtime, or domain-specific adapters — not in decision-passport-core.

Logs and traces are operational telemetry. Decision Passport Core is a verifiable proof format with canonical hashing, chain integrity checks, receipt generation, batch verification, and profile-level proof semantics. Observability helps you inspect behavior. Decision Passport helps you verify the integrity of exported proof artifacts.

git clone https://github.com/brigalss-a/decision-passport-core.git
cd decision-passport-core
pnpm install --frozen-lockfile
pnpm build
pnpm test
pnpm verify-demo

No database, API key, or cloud account required.

Use this exact sequence for a fast validation pass:

pnpm install --frozen-lockfile
pnpm build
pnpm test
pnpm conformance
pnpm verifier:golden
pnpm verify-demo
pnpm example:smoke
pnpm example:batch-verification
python -m decision_passport.verify examples/reference-integrations/webhook-approval-receipt.bundle.json
python -m decision_passport.verify examples/reference-integrations/agent-tool-execution-receipt.bundle.json

If all commands pass, you have validated:

1. Core verifier correctness.
2. TypeScript/Python conformance parity.
3. Deterministic reference-integration behavior.
4. Tool Call Wrapper receipt generation.
5. Batch verification and audit report generation.
6. Auditor-grade output paths on canonical bundle surfaces.

Python reference implementation is available in python/decision_passport_py and mirrors the protocol surface for offline create and verify flows.

cd python/decision_passport_py
pip install -e .
python -m unittest discover -s tests -v
python -m decision_passport.verify ../../fixtures/valid-bundle.json

Serve the repo and open apps/verifier-web/. Drag any bundle JSON onto the page for client-side verification.

npx serve . -l 3000
# Open http://localhost:3000/apps/verifier-web/

Decision Passport is an append-only, hash-linked record system for AI, tool, workflow, and autonomous-action receipts.

Every material action — such as a recommendation, an approval, a tool execution, a batch verification result, or an autonomous-action claim — can be stamped into a tamper-evident chain. That chain is bundled and can be independently verified offline.

This repository provides deterministic verification semantics through canonical hashing and explicit chain rules. Record creation still uses runtime UUID and timestamp values, so fixture regeneration is not byte-identical unless controlled inputs are used.

AI agents run, tool calls happen, workflows execute, results are returned.
There may be logs, but no portable proof artifact.
External reviewers must trust the original system.
Hard to prove what was approved, what payload was bound, and what outcome was recorded.

AI agent runs, each material step is stamped into an append-only chain.
Bundle exported as portable JSON proof.
Verifier returns PASS when integrity checks succeed.
External reviewers can independently verify chain integrity.

import { createRecord, createManifest } from '@decision-passport/core';
import { verifyBasicBundle } from '@decision-passport/verifier-basic';

const chainId = `session-${Date.now()}`;

// 1. Stamp each action
const record1 = createRecord({
  chainId,
  lastRecord: null,
  actorId: 'claude-agent-01',
  actorType: 'ai_agent',
  actionType: 'AI_RECOMMENDATION',
  payload: {
    rationale: 'Policy v2.1, action within approved risk threshold',
    confidence: 0.94,
    policy_version: 'v2.1'
  }
});

const record2 = createRecord({
  chainId,
  lastRecord: record1,
  actorId: 'alice@company.com',
  actorType: 'human',
  actionType: 'HUMAN_APPROVAL_GRANTED',
  payload: { note: 'Reviewed and approved' }
});

const record3 = createRecord({
  chainId,
  lastRecord: record2,
  actorId: 'claude-agent-01',
  actorType: 'ai_agent',
  actionType: 'EXECUTION_SUCCEEDED',
  payload: { result_summary: 'Email delivered', message_id: 'msg-8821' }
});

// 2. Export a portable proof bundle
const records = [record1, record2, record3];
const bundle = {
  bundle_version: '1.4-basic' as const,
  exported_at_utc: new Date().toISOString(),
  passport_records: records,
  manifest: createManifest(records)
};

// 3. Verify independently (no network, no database)
const result = verifyBasicBundle(bundle);
console.log(result.status); // 'PASS'

Wrap any async tool/function call and export a portable proof bundle that can be verified offline.

import { withDecisionPassportToolCall, verifyToolCallReceipt } from '@decision-passport/tool-call-wrapper';

const receipt = await withDecisionPassportToolCall({
  tool: { name: 'send-email', version: '1.0' },
  actor: { id: 'claude-agent-01', type: 'ai_agent' },
  input: { to: 'alice@example.com', subject: 'Hello' },
  authorization: { approved: true, authorizationType: 'policy', policyVersion: 'v2.1' },
  execute: async (ctx) => {
    return { messageId: 'msg-001', delivered: true };
  }
});

console.log(receipt.status);           // 'SUCCESS'
console.log(receipt.inputHash);        // SHA-256 of normalized input
console.log(receipt.outputHash);       // SHA-256 of normalized output
console.log(receipt.verification.ok);  // true — bundle verified offline

const verification = verifyToolCallReceipt(receipt.bundle);
console.log(verification.ok);  // true

What this proves:

• The tool was called with a specific input (input hash)
• The tool produced a specific output (output hash)
• Authorization was granted before execution
• The full lifecycle is recorded in a tamper-evident chain

What this does not prove:

• That the agent identity is cryptographically verified
• That the tool execution was runtime-enforced
• That replay attacks are prevented

See docs/TOOL_CALL_WRAPPER.md for full API reference.

Decision Passport can verify individual receipts or batch-verify receipt sets for audit and conformance workflows.

import { verifyBundleBatch, createVerificationAuditReport } from '@decision-passport/verifier-basic';

const report = verifyBundleBatch([bundle1, bundle2, bundle3], { label: 'audit-q1' });

console.log(report.passedCount);   // 2
console.log(report.failedCount);   // 1
console.log(report.failureSummary.byClass);
// { CHAIN_BREAK: 0, TAMPERED_PAYLOAD: 1, MALFORMED_BUNDLE: 0, ... }

// Export a Markdown audit report
const artifact = createVerificationAuditReport(report, { format: 'markdown' });
console.log(artifact.content);

What this proves:

• A set of bundles verified against the same deterministic offline rules as individual verification
• Failures classified into stable machine-readable categories
• Audit reports reproducible at any time from the same bundle set

What this does not prove:

• GPU acceleration, AI factory runtime integration, real-time monitoring, or cloud audit services

See docs/BATCH_VERIFICATION.md for full API reference.

Decision Passport makes autonomous execution provable — from AI tool calls to physical-world action receipts.

The Autonomous Action Receipt Profile defines how to use BasicProofBundle and PassportRecord to create offline-verifiable receipts for autonomous system actions: warehouse robots, delivery drones, autonomous vehicles, industrial arms, and edge AI agents.

Decision Passport does not replace functional safety systems.
Decision Passport records and verifies which safety envelope, evidence hashes, and authorization claims were bound to an autonomous action.

import { verifyBasicBundle } from '@decision-passport/verifier-basic';
import { readFileSync } from 'node:fs';

// Load a Decision Passport bundle from an autonomous robot
const bundle = JSON.parse(readFileSync('robot-receipt.json', 'utf8'));
const result = verifyBasicBundle(bundle);

// PASS: sensor hash, safety envelope, authorization, and outcome are all intact
// FAIL + HASH_MISMATCH: sensor data was tampered with after the record was signed
console.log(result.status); // "PASS" or "FAIL"

What this proves:

• Which sensor/context evidence hashes were bound to the autonomous decision
• Which safety envelope constraints were declared at decision time
• What authorization claim was granted or denied
• Whether a simulation scenario hash was included at authorization time
• What outcome was recorded — succeeded, failed, aborted, denied, or safety-blocked
• Chain integrity: none of the above can be mutated without breaking verification

What this does not prove:

• That sensors were accurate, safety envelopes were appropriate, or simulations were valid
• Safety certification — Decision Passport is not certified under ISO 26262 or any safety standard
• Hardware control or integration with NVIDIA DRIVE, Isaac, Jetson, ROS, or any external SDK

See docs/AUTONOMOUS_ACTION_PROFILE.md and docs/SIMULATION_TO_EXECUTION_PROFILE.md.

decision-passport-core/
├── packages/
│   ├── core/               ← Hash chain engine
│   │   ├── src/types.ts         ActionType, PassportRecord, ChainManifest, BasicProofBundle
│   │   ├── src/chain.ts         createRecord(), verifyChain(), assertValidChain()
│   │   ├── src/hashing.ts       hashCanonical(), hashPayload(): SHA-256, deterministic
│   │   ├── src/canonical.ts     Canonical JSON serialiser
│   │   ├── src/manifest.ts      createManifest()
│   │   ├── src/explain-tamper.ts explainTamper(): what changed and why it broke
│   │   ├── src/bundle-diff.ts   diffBundles(): compare two bundles field by field
│   │   └── src/errors.ts        ChainValidationError
│   │
│   ├── verifier-basic/     ← Offline bundle verifier + batch verification
│   │   ├── src/verify-bundle.ts       verifyBundle(): zero external deps
│   │   ├── src/batch-verification.ts  verifyBundleBatch(), failure classification, audit reports
│   │   └── src/html-report.ts         renderVerificationReport(): static HTML export
│   │
│   ├── tool-call-wrapper/  ← Stateless async tool/function receipt wrapper
│   │   ├── src/with-decision-passport-tool-call.ts
│   │   ├── src/verify-tool-call-receipt.ts
│   │   ├── src/hash.ts
│   │   ├── src/redaction.ts
│   │   └── src/errors.ts
│   │
│   └── demo/               ← Runnable demo
│       └── src/index.ts         Full demo: record → export → verify → PASS
│
├── apps/
│   └── verifier-web/       ← Browser verifier
│
├── fixtures/
│   ├── valid-bundle.json
│   ├── tampered-bundle.json
│   ├── broken-prev-hash.json
│   ├── malformed-bundle.json
│   └── autonomous/         ← Autonomous Action Receipt Profile fixtures
│
├── examples/
│   └── reference-integrations/
│       ├── tool-call-wrapper/
│       ├── batch-verification/
│       └── autonomous-action-receipt/
│
├── python/
│   └── decision_passport_py/    ← Python reference implementation
│
└── artifacts/              ← Generated by verifier/demo scripts

PassportRecord[0]        PassportRecord[1]        PassportRecord[2]
─────────────────        ─────────────────        ─────────────────
id: uuid                 id: uuid                 id: uuid
sequence: 0              sequence: 1              sequence: 2
prev_hash: GENESIS       prev_hash: hash[0]       prev_hash: hash[1]
payload_hash: sha256     payload_hash: sha256     payload_hash: sha256
record_hash: sha256 ──►  record_hash: sha256 ──►  record_hash: sha256
                                                          │
                                                          ▼
                                               ChainManifest
                                               chain_hash = record_hash[2]
                                                          │
                                                          ▼
                                               BasicProofBundle
                                               (portable · verifiable · exportable)

Tampering with any single byte in any record breaks every subsequent hash. The chain becomes self-auditing.

The atomic unit of trust. Every record contains:

type ActionType =
  | 'AI_RECOMMENDATION'       // Agent produces a decision
  | 'HUMAN_APPROVAL_GRANTED'  // Human approves
  | 'HUMAN_APPROVAL_REJECTED' // Human rejects
  | 'POLICY_APPROVAL_GRANTED' // Policy engine approves
  | 'EXECUTION_PENDING'       // Action queued
  | 'EXECUTION_SUCCEEDED'     // Action completed successfully
  | 'EXECUTION_FAILED'        // Action failed
  | 'EXECUTION_ABORTED'       // Action cancelled
  | 'HUMAN_OVERRIDE'          // Human overrides system decision
  | 'POLICY_EXCEPTION';       // Exception granted

Chain summary: chain_id, record_count, first_record_id, last_record_id, chain_hash.

The portable export format (bundle_version: "1.4-basic"). Contains all records + manifest. Self-contained, verifiable offline.

import { verifyBasicBundle } from '@decision-passport/verifier-basic';
import fs from 'fs';

const bundle = JSON.parse(fs.readFileSync('./bundle.json', 'utf8'));
const result = verifyBasicBundle(bundle);

console.log(result.status);  // 'PASS' | 'FAIL'
console.log(result.summary);      // short human summary
console.log(result.reasonCodes);  // stable machine-readable reason codes
console.log(result.checks);       // array of individual check results
console.log(result.nextSteps);    // concise triage guidance on FAIL

A CLI verifier is also available at packages/verifier-basic/src/cli.ts:

pnpm tsx packages/verifier-basic/src/cli.ts ./bundle.json

Compare two bundles to see exactly what changed:

pnpm diff-bundles fixtures/valid-bundle.json fixtures/tampered-bundle.json

Or use the API:

import { diffBundles } from '@decision-passport/core';

const result = diffBundles(bundleA, bundleB);
console.log(result.identical); // false
console.log(result.summary);   // '1 difference(s) found: 1 field change(s).'
console.log(result.findings);  // structured diff findings

The Python package in python/decision_passport_py is protocol-first and offline-only, not an API wrapper.

cd python/decision_passport_py
pip install -e .
python -m decision_passport.verify ../../fixtures/valid-bundle.json
python -m decision_passport.diff ../../fixtures/valid-bundle.json ../../fixtures/tampered-bundle.json

The verifier checks:

1. Every record_hash matches the recomputed deterministic hash
2. Every prev_hash correctly chains to the previous record
3. Sequence numbers are gapless and correct
4. chain_hash in the manifest matches the terminal record

If the input is malformed, verification returns FAIL with a structure reason code. If integrity checks fail, verification returns FAIL with integrity reason codes.

• Schema and versioning: bundle structure, record fields, hashing rules, evolution guidance
• Compatibility matrix: which tools work with which formats
• Verifier compatibility promise: 12-month supported/deprecated/unsupported policy
• Verifier auditor output: deterministic verdict/code/location/reason/remediation_hint contract
• Protocol conformance: normative verifier checks and fixture outcomes
• Conformance manifest: machine-readable expected verdict map for canonical fixtures
• JSON Schemas: machine-readable schemas for BasicProofBundle, ChainManifest, PassportRecord
• Release verification: how to verify a published release locally
• Release provenance: official release artifacts, 3-minute local verification, and trust limitations
• Reference integrations: two ultra-small end-to-end examples (webhook approval receipt and agent/tool execution receipt)
• Append-only guarantees: what the protocol enforces, what verification detects, storage-level limits
• Bundle Diff: how to compare two bundles, generate diff artifacts, and interpret findings

• Boundaries: exact scope, non-goals, and trust boundary edges
• Threat model: addressed threats, assumptions, and residual risk
• Verification model: PASS and FAIL semantics, safe interpretation
• Tamper cases: concrete failure patterns and investigation guidance

Core is free and open source.

Hosted, business, enterprise, and sovereign deployment options are available on request.

Contact: contact@bespea.com

• Core hash chain engine
• BasicProofBundle export
• Offline verifier
• CLI verifier
• Demo with sample data
• Tamper explainer
• HTML verification report export
• Browser verifier
• Deterministic valid + tampered fixtures
• Bundle diff utility
• Tool Call Wrapper (withDecisionPassportToolCall())
• Batch Verification + Audit Reports (verifyBundleBatch(), failure classification, JSON/Markdown reports)
• Autonomous Action Receipt Profile
• MCP verifier/recorder server
• OpenClaw Lite alignment against core wrapper
• Provider adapters for OpenAI/Anthropic tool-use flows
• Python parity for Tool Call Wrapper
• Trusted timestamping integration (RFC 3161)

This repository is the public protocol layer. The full ecosystem:

To keep this repository technically honest, we keep public feedback channels focused on reproducible verifier and conformance evidence.

• Adoption and validation signals: docs/adoption-signals.md
• Verifier contract feedback template: .github/ISSUE_TEMPLATE/verifier-contract-feedback.md
• Conformance/integration feedback template: .github/ISSUE_TEMPLATE/conformance-or-integration-feedback.md

When reporting feedback, include exact commands, fixture/bundle inputs, and expected vs actual verifier outputs.

Contributions to the public protocol are welcome.

Fork the repository on GitHub, then run:

git clone https://github.com/YOUR_USERNAME/decision-passport-core.git
cd decision-passport-core
git checkout -b feat/my-improvement
pnpm install --frozen-lockfile
pnpm test

Then open a pull request with a clear description of what changed and why.

Apache-2.0. See full text in LICENSE file.

You may use, modify, and distribute this software freely, including in commercial products. The express patent grant protects you and your users. Product names, logos, and hosted offerings remain the intellectual property of Bespoke Champions League Ltd.

Decision Passport is built and maintained by Bespoke Champions League Ltd, London, United Kingdom.

It powers the trust layer inside Bespea. Decision Passport emerged from a real-world problem: AI systems making material delivery, execution, and approval decisions without a portable, verifiable record.

Maintainer: Grigore-Andrei Traistaru Founder contact@bespea.com https://bespea.com