{"id":47720170,"url":"https://github.com/brigalss-a/decision-passport-core","last_synced_at":"2026-04-26T00:04:48.330Z","repository":{"id":348136679,"uuid":"1196603316","full_name":"brigalss-a/decision-passport-core","owner":"brigalss-a","description":"Append-only trust layer for AI agent actions with offline verification, tamper detection, and portable proof bundles.","archived":false,"fork":false,"pushed_at":"2026-04-11T18:47:51.000Z","size":136,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-11T20:29:33.312Z","etag":null,"topics":["agent-infrastructure","ai-governance","append-only","audit-trail","cryptographic-proof","offline-verification","tamper-evident","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/brigalss-a/decision-passport-core#readme","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brigalss-a.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-30T21:26:13.000Z","updated_at":"2026-04-11T18:47:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"d65343f9-5f51-4584-875e-5b5e60a888cc","html_url":"https://github.com/brigalss-a/decision-passport-core","commit_stats":null,"previous_names":["brigalss-a/decision-passport-core"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/brigalss-a/decision-passport-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brigalss-a%2Fdecision-passport-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brigalss-a%2Fdecision-passport-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brigalss-a%2Fdecision-passport-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brigalss-a%2Fdecision-passport-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brigalss-a","download_url":"https://codeload.github.com/brigalss-a/decision-passport-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brigalss-a%2Fdecision-passport-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32280982,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-infrastructure","ai-governance","append-only","audit-trail","cryptographic-proof","offline-verification","tamper-evident","typescript"],"created_at":"2026-04-02T19:20:04.446Z","updated_at":"2026-04-26T00:04:48.313Z","avatar_url":"https://github.com/brigalss-a.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Decision Passport: Core\n\n[![CI](https://github.com/brigalss-a/decision-passport-core/actions/workflows/ci.yml/badge.svg)](https://github.com/brigalss-a/decision-passport-core/actions/workflows/ci.yml)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n\n**Offline-verifiable authorization and execution receipts for AI agents, tools, workflows, and autonomous systems.**\n\nDecision Passport Core is the public protocol layer for creating, exporting, and independently verifying tamper-evident proof bundles.\n\nIt helps answer:\n\n```text\nWhat was requested?\nWho or what approved it?\nWhat exact payload was bound?\nWhat executed or failed?\nCan the result be verified offline without trusting the original system?\n```\n\n**TypeScript + Python reference** · **pnpm** · **Append-only chain** · **Offline verification** · **No database required**\n\n---\n\n## Current public line\n\n**v0.9.0 — Autonomous Action Receipt Profile**\n\nDecision Passport Core now covers:\n\n- Core proof bundles and offline verifier semantics.\n- Tool-call execution receipts.\n- Batch verification and local audit reports.\n- Autonomous / physical-world action receipt profiles.\n\n---\n\n## Trust panel\n\n| Signal | Current status |\n| --- | --- |\n| Status | Public release track |\n| Current implementation line | v0.9.0 — Autonomous Action Receipt Profile |\n| API stability | Pre-1.0, changes possible |\n| Verification scope | Hash-chain integrity, manifest checks, wrapper receipt verification, batch verification reports, autonomous action profile fixtures |\n| Security disclosure | See `SECURITY.md`, report privately via email |\n| Recommended usage | Proof layer for traceability, tool-call receipts, batch audit, autonomous-action receipt profiles, and offline verification |\n| Not yet included | Hosted runtime enforcement, claim tokens, replay locks, DB persistence, signed identity/attestation layer, safety certification |\n\n---\n\n## Release track\n\n| Version | Status | Capability |\n| --- | --- | --- |\n| v0.7.0 | Released | Core-first semantics: DecisionTrail, RuntimeClaim, OutcomeBinding verifier-visible semantics |\n| v0.8.0 | Released | Tool Call Wrapper: wrap async tool/function executions into offline-verifiable receipts |\n| v0.8.1 | Released | Batch Verification + Audit Reports: verify receipt sets, classify failures, generate local reports |\n| v0.9.0 | Current | Autonomous Action Receipt Profile: safety-envelope and evidence-hash receipt profile for autonomous/physical-world actions |\n\n---\n\n## v0.9.0 Implementation Truth Map\n\nThis section is normative for what this repository can prove in the current public line.\n\n| Surface | v0.9.0 status | Truth statement |\n| --- | --- | --- |\n| Core proof bundles | Implemented | TypeScript and Python verifiers validate supported bundle chain and manifest integrity. |\n| DecisionTrail / RuntimeClaim / OutcomeBinding semantics | Implemented for verifier-visible protocol surfaces | These semantics remain protocol/bundle-level and do not imply hosted runtime enforcement. |\n| Tool Call Wrapper | Implemented | Async tool/function executions can be wrapped into Decision Passport receipts with SUCCESS, FAILED, DENIED, and ABORTED outcomes. |\n| Wrapper verification | Implemented | Wrapper-generated receipts can be verified offline through existing verifier paths. |\n| Batch verification | Implemented | Multiple proof bundles can be verified together using deterministic offline verification rules. |\n| Failure classification | Implemented | Batch results classify common failure families in stable machine-readable categories. |\n| Audit reports | Implemented | Local JSON/Markdown reports can summarize verification results for audit and conformance workflows. |\n| Autonomous Action Receipt Profile | Implemented | Autonomous/physical-world actions can be represented as proof bundles using safety-envelope claims, evidence hashes, and outcome binding. |\n| Simulation-to-execution profile | Implemented as docs/fixtures | Simulation scenario hashes can be bound to runtime action receipts. |\n| Runtime enforcement | Not included | The repo records and verifies receipts; it does not block or allow execution at runtime. |\n| Replay protection | Not included | Distributed replay locks and claim-token registries belong in future control-plane/runtime layers. |\n| Functional safety certification | Not included | Decision Passport records and verifies claims; it does not certify autonomous systems. |\n\n---\n\n## What this proves\n\n1. A bundle's record hashes, chain links, and manifest chain hash are internally consistent.\n2. Payload tampering and chain mutation are detected by offline verification.\n3. Verification runs offline with no database, API key, or cloud dependency.\n4. v0.7.0 verifier semantics classify runtime-claim, outcome-linkage, revocation/supersession, and trail-linkage states on supported bundle surfaces.\n5. v0.8.0 Tool Call Wrapper can bind requested input hash, authorization state, execution outcome, and output/error hash into a verifiable receipt.\n6. v0.8.1 Batch Verification can verify receipt sets, classify verification failures, and generate local audit reports.\n7. 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.\n\n## What this does not prove\n\n1. Runtime policy enforcement at execution time.\n2. Distributed replay prevention.\n3. Storage-level immutability by itself.\n4. Who authored a bundle, unless a separate signing/identity layer is used.\n5. That a hosted guard executor blocked or allowed execution in real time.\n6. That an external tool provider performed a side effect beyond evidence bound into the receipt.\n7. That autonomous systems are safe.\n8. Functional safety certification.\n9. Robot, vehicle, drone, or machine control.\n10. NVIDIA, ROS, Isaac, Jetson, DRIVE, CUDA, or hardware integration.\n\n## When to use this\n\nUse this repository when you need portable, offline-checkable proof artifacts for:\n\n- AI action history.\n- Tool-call receipts.\n- Workflow execution evidence.\n- Batch verification and audit/conformance workflows.\n- Autonomous or physical-world action receipt profiles.\n\n## When you need stronger infrastructure\n\nUse 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.\n\nThose belong in control-plane, sovereign, runtime, or domain-specific adapters — not in decision-passport-core.\n\n## How this differs from logs, traces, and observability\n\nLogs 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.\n\n---\n\n## Verify in 60 seconds\n\n```bash\ngit clone https://github.com/brigalss-a/decision-passport-core.git\ncd decision-passport-core\npnpm install --frozen-lockfile\npnpm build\npnpm test\npnpm verify-demo\n```\n\nNo database, API key, or cloud account required.\n\n### First 5 Minutes\n\nUse this exact sequence for a fast validation pass:\n\n```bash\npnpm install --frozen-lockfile\npnpm build\npnpm test\npnpm conformance\npnpm verifier:golden\npnpm verify-demo\npnpm example:smoke\npnpm example:batch-verification\npython -m decision_passport.verify examples/reference-integrations/webhook-approval-receipt.bundle.json\npython -m decision_passport.verify examples/reference-integrations/agent-tool-execution-receipt.bundle.json\n```\n\nIf all commands pass, you have validated:\n\n1. Core verifier correctness.\n2. TypeScript/Python conformance parity.\n3. Deterministic reference-integration behavior.\n4. Tool Call Wrapper receipt generation.\n5. Batch verification and audit report generation.\n6. Auditor-grade output paths on canonical bundle surfaces.\n\nPython reference implementation is available in `python/decision_passport_py` and mirrors the protocol surface for offline create and verify flows.\n\n### Optional Python quick check\n\n```bash\ncd python/decision_passport_py\npip install -e .\npython -m unittest discover -s tests -v\npython -m decision_passport.verify ../../fixtures/valid-bundle.json\n```\n\n### Browser verifier\n\nServe the repo and open `apps/verifier-web/`. Drag any bundle JSON onto the page for client-side verification.\n\n```bash\nnpx serve . -l 3000\n# Open http://localhost:3000/apps/verifier-web/\n```\n\n\u003c!-- markdownlint-disable MD033 --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/core-browser-pass.svg\" alt=\"Browser verifier PASS\" width=\"680\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/core-browser-fail.svg\" alt=\"Browser verifier FAIL\" width=\"680\" /\u003e\n\u003c/p\u003e\n\u003c!-- markdownlint-enable MD033 --\u003e\n\n---\n\n## What is Decision Passport?\n\nDecision Passport is an **append-only, hash-linked record system** for AI, tool, workflow, and autonomous-action receipts.\n\nEvery 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.\n\nThis 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.\n\n---\n\n## Before / After\n\n### Without Decision Passport\n\n```text\nAI agents run, tool calls happen, workflows execute, results are returned.\nThere may be logs, but no portable proof artifact.\nExternal reviewers must trust the original system.\nHard to prove what was approved, what payload was bound, and what outcome was recorded.\n```\n\n### With Decision Passport\n\n```text\nAI agent runs, each material step is stamped into an append-only chain.\nBundle exported as portable JSON proof.\nVerifier returns PASS when integrity checks succeed.\nExternal reviewers can independently verify chain integrity.\n```\n\n---\n\n## Quick example\n\n```typescript\nimport { createRecord, createManifest } from '@decision-passport/core';\nimport { verifyBasicBundle } from '@decision-passport/verifier-basic';\n\nconst chainId = `session-${Date.now()}`;\n\n// 1. Stamp each action\nconst record1 = createRecord({\n  chainId,\n  lastRecord: null,\n  actorId: 'claude-agent-01',\n  actorType: 'ai_agent',\n  actionType: 'AI_RECOMMENDATION',\n  payload: {\n    rationale: 'Policy v2.1, action within approved risk threshold',\n    confidence: 0.94,\n    policy_version: 'v2.1'\n  }\n});\n\nconst record2 = createRecord({\n  chainId,\n  lastRecord: record1,\n  actorId: 'alice@company.com',\n  actorType: 'human',\n  actionType: 'HUMAN_APPROVAL_GRANTED',\n  payload: { note: 'Reviewed and approved' }\n});\n\nconst record3 = createRecord({\n  chainId,\n  lastRecord: record2,\n  actorId: 'claude-agent-01',\n  actorType: 'ai_agent',\n  actionType: 'EXECUTION_SUCCEEDED',\n  payload: { result_summary: 'Email delivered', message_id: 'msg-8821' }\n});\n\n// 2. Export a portable proof bundle\nconst records = [record1, record2, record3];\nconst bundle = {\n  bundle_version: '1.4-basic' as const,\n  exported_at_utc: new Date().toISOString(),\n  passport_records: records,\n  manifest: createManifest(records)\n};\n\n// 3. Verify independently (no network, no database)\nconst result = verifyBasicBundle(bundle);\nconsole.log(result.status); // 'PASS'\n```\n\n---\n\n## Tool Call Wrapper\n\nWrap any async tool/function call and export a portable proof bundle that can be verified offline.\n\n```typescript\nimport { withDecisionPassportToolCall, verifyToolCallReceipt } from '@decision-passport/tool-call-wrapper';\n\nconst receipt = await withDecisionPassportToolCall({\n  tool: { name: 'send-email', version: '1.0' },\n  actor: { id: 'claude-agent-01', type: 'ai_agent' },\n  input: { to: 'alice@example.com', subject: 'Hello' },\n  authorization: { approved: true, authorizationType: 'policy', policyVersion: 'v2.1' },\n  execute: async (ctx) =\u003e {\n    return { messageId: 'msg-001', delivered: true };\n  }\n});\n\nconsole.log(receipt.status);           // 'SUCCESS'\nconsole.log(receipt.inputHash);        // SHA-256 of normalized input\nconsole.log(receipt.outputHash);       // SHA-256 of normalized output\nconsole.log(receipt.verification.ok);  // true — bundle verified offline\n\nconst verification = verifyToolCallReceipt(receipt.bundle);\nconsole.log(verification.ok);  // true\n```\n\n**What this proves:**\n- The tool was called with a specific input (input hash)\n- The tool produced a specific output (output hash)\n- Authorization was granted before execution\n- The full lifecycle is recorded in a tamper-evident chain\n\n**What this does not prove:**\n- That the agent identity is cryptographically verified\n- That the tool execution was runtime-enforced\n- That replay attacks are prevented\n\nSee [docs/TOOL_CALL_WRAPPER.md](docs/TOOL_CALL_WRAPPER.md) for full API reference.\n\n---\n\n## Batch Verification\n\nDecision Passport can verify individual receipts or batch-verify receipt sets for audit and conformance workflows.\n\n```typescript\nimport { verifyBundleBatch, createVerificationAuditReport } from '@decision-passport/verifier-basic';\n\nconst report = verifyBundleBatch([bundle1, bundle2, bundle3], { label: 'audit-q1' });\n\nconsole.log(report.passedCount);   // 2\nconsole.log(report.failedCount);   // 1\nconsole.log(report.failureSummary.byClass);\n// { CHAIN_BREAK: 0, TAMPERED_PAYLOAD: 1, MALFORMED_BUNDLE: 0, ... }\n\n// Export a Markdown audit report\nconst artifact = createVerificationAuditReport(report, { format: 'markdown' });\nconsole.log(artifact.content);\n```\n\n**What this proves:**\n- A set of bundles verified against the same deterministic offline rules as individual verification\n- Failures classified into stable machine-readable categories\n- Audit reports reproducible at any time from the same bundle set\n\n**What this does not prove:**\n- GPU acceleration, AI factory runtime integration, real-time monitoring, or cloud audit services\n\nSee [docs/BATCH_VERIFICATION.md](docs/BATCH_VERIFICATION.md) for full API reference.\n\n---\n\n## Autonomous Action Receipt Profile\n\nDecision Passport makes autonomous execution provable — from AI tool calls to physical-world action receipts.\n\nThe 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.\n\n\u003e **Decision Passport does not replace functional safety systems.**  \n\u003e Decision Passport records and verifies which safety envelope, evidence hashes, and authorization claims were bound to an autonomous action.\n\n```typescript\nimport { verifyBasicBundle } from '@decision-passport/verifier-basic';\nimport { readFileSync } from 'node:fs';\n\n// Load a Decision Passport bundle from an autonomous robot\nconst bundle = JSON.parse(readFileSync('robot-receipt.json', 'utf8'));\nconst result = verifyBasicBundle(bundle);\n\n// PASS: sensor hash, safety envelope, authorization, and outcome are all intact\n// FAIL + HASH_MISMATCH: sensor data was tampered with after the record was signed\nconsole.log(result.status); // \"PASS\" or \"FAIL\"\n```\n\n**What this proves:**\n- Which sensor/context evidence hashes were bound to the autonomous decision\n- Which safety envelope constraints were declared at decision time\n- What authorization claim was granted or denied\n- Whether a simulation scenario hash was included at authorization time\n- What outcome was recorded — succeeded, failed, aborted, denied, or safety-blocked\n- Chain integrity: none of the above can be mutated without breaking verification\n\n**What this does not prove:**\n- That sensors were accurate, safety envelopes were appropriate, or simulations were valid\n- Safety certification — Decision Passport is not certified under ISO 26262 or any safety standard\n- Hardware control or integration with NVIDIA DRIVE, Isaac, Jetson, ROS, or any external SDK\n\nSee [docs/AUTONOMOUS_ACTION_PROFILE.md](docs/AUTONOMOUS_ACTION_PROFILE.md) and [docs/SIMULATION_TO_EXECUTION_PROFILE.md](docs/SIMULATION_TO_EXECUTION_PROFILE.md).\n\n---\n\n## Architecture\n\n```text\ndecision-passport-core/\n├── packages/\n│   ├── core/               ← Hash chain engine\n│   │   ├── src/types.ts         ActionType, PassportRecord, ChainManifest, BasicProofBundle\n│   │   ├── src/chain.ts         createRecord(), verifyChain(), assertValidChain()\n│   │   ├── src/hashing.ts       hashCanonical(), hashPayload(): SHA-256, deterministic\n│   │   ├── src/canonical.ts     Canonical JSON serialiser\n│   │   ├── src/manifest.ts      createManifest()\n│   │   ├── src/explain-tamper.ts explainTamper(): what changed and why it broke\n│   │   ├── src/bundle-diff.ts   diffBundles(): compare two bundles field by field\n│   │   └── src/errors.ts        ChainValidationError\n│   │\n│   ├── verifier-basic/     ← Offline bundle verifier + batch verification\n│   │   ├── src/verify-bundle.ts       verifyBundle(): zero external deps\n│   │   ├── src/batch-verification.ts  verifyBundleBatch(), failure classification, audit reports\n│   │   └── src/html-report.ts         renderVerificationReport(): static HTML export\n│   │\n│   ├── tool-call-wrapper/  ← Stateless async tool/function receipt wrapper\n│   │   ├── src/with-decision-passport-tool-call.ts\n│   │   ├── src/verify-tool-call-receipt.ts\n│   │   ├── src/hash.ts\n│   │   ├── src/redaction.ts\n│   │   └── src/errors.ts\n│   │\n│   └── demo/               ← Runnable demo\n│       └── src/index.ts         Full demo: record → export → verify → PASS\n│\n├── apps/\n│   └── verifier-web/       ← Browser verifier\n│\n├── fixtures/\n│   ├── valid-bundle.json\n│   ├── tampered-bundle.json\n│   ├── broken-prev-hash.json\n│   ├── malformed-bundle.json\n│   └── autonomous/         ← Autonomous Action Receipt Profile fixtures\n│\n├── examples/\n│   └── reference-integrations/\n│       ├── tool-call-wrapper/\n│       ├── batch-verification/\n│       └── autonomous-action-receipt/\n│\n├── python/\n│   └── decision_passport_py/    ← Python reference implementation\n│\n└── artifacts/              ← Generated by verifier/demo scripts\n```\n\n### Trust chain model\n\n```text\nPassportRecord[0]        PassportRecord[1]        PassportRecord[2]\n─────────────────        ─────────────────        ─────────────────\nid: uuid                 id: uuid                 id: uuid\nsequence: 0              sequence: 1              sequence: 2\nprev_hash: GENESIS       prev_hash: hash[0]       prev_hash: hash[1]\npayload_hash: sha256     payload_hash: sha256     payload_hash: sha256\nrecord_hash: sha256 ──►  record_hash: sha256 ──►  record_hash: sha256\n                                                          │\n                                                          ▼\n                                               ChainManifest\n                                               chain_hash = record_hash[2]\n                                                          │\n                                                          ▼\n                                               BasicProofBundle\n                                               (portable · verifiable · exportable)\n```\n\nTampering with any single byte in any record breaks every subsequent hash. The chain becomes self-auditing.\n\n---\n\n## Core concepts\n\n### PassportRecord\n\nThe atomic unit of trust. Every record contains:\n\n| Field | Description |\n| --- | --- |\n| `id` | UUID |\n| `chain_id` | Session identifier |\n| `sequence` | Monotonic counter (0, 1, 2, ...) |\n| `timestamp_utc` | ISO 8601 timestamp |\n| `actor_id` | Who acted (agent ID, user email, system name) |\n| `actor_type` | `human` / `ai_agent` / `system` / `policy` |\n| `action_type` | Category (see below) |\n| `payload` | Action data (structured) |\n| `payload_hash` | SHA-256 of payload |\n| `prev_hash` | Hash of previous record (or `GENESIS`) |\n| `record_hash` | SHA-256 of the full record (excluding itself) |\n| `metadata` | Optional: environment, tenant, policy refs |\n\n### Action types\n\n```typescript\ntype ActionType =\n  | 'AI_RECOMMENDATION'       // Agent produces a decision\n  | 'HUMAN_APPROVAL_GRANTED'  // Human approves\n  | 'HUMAN_APPROVAL_REJECTED' // Human rejects\n  | 'POLICY_APPROVAL_GRANTED' // Policy engine approves\n  | 'EXECUTION_PENDING'       // Action queued\n  | 'EXECUTION_SUCCEEDED'     // Action completed successfully\n  | 'EXECUTION_FAILED'        // Action failed\n  | 'EXECUTION_ABORTED'       // Action cancelled\n  | 'HUMAN_OVERRIDE'          // Human overrides system decision\n  | 'POLICY_EXCEPTION';       // Exception granted\n```\n\n### ChainManifest\n\nChain summary: `chain_id`, `record_count`, `first_record_id`, `last_record_id`, `chain_hash`.\n\n### BasicProofBundle\n\nThe portable export format (`bundle_version: \"1.4-basic\"`). Contains all records + manifest. Self-contained, verifiable offline.\n\n---\n\n## Offline verification\n\n```typescript\nimport { verifyBasicBundle } from '@decision-passport/verifier-basic';\nimport fs from 'fs';\n\nconst bundle = JSON.parse(fs.readFileSync('./bundle.json', 'utf8'));\nconst result = verifyBasicBundle(bundle);\n\nconsole.log(result.status);  // 'PASS' | 'FAIL'\nconsole.log(result.summary);      // short human summary\nconsole.log(result.reasonCodes);  // stable machine-readable reason codes\nconsole.log(result.checks);       // array of individual check results\nconsole.log(result.nextSteps);    // concise triage guidance on FAIL\n```\n\nA CLI verifier is also available at `packages/verifier-basic/src/cli.ts`:\n\n```bash\npnpm tsx packages/verifier-basic/src/cli.ts ./bundle.json\n```\n\n### Bundle diff\n\nCompare two bundles to see exactly what changed:\n\n```bash\npnpm diff-bundles fixtures/valid-bundle.json fixtures/tampered-bundle.json\n```\n\nOr use the API:\n\n```typescript\nimport { diffBundles } from '@decision-passport/core';\n\nconst result = diffBundles(bundleA, bundleB);\nconsole.log(result.identical); // false\nconsole.log(result.summary);   // '1 difference(s) found: 1 field change(s).'\nconsole.log(result.findings);  // structured diff findings\n```\n\n### Python reference implementation\n\nThe Python package in `python/decision_passport_py` is protocol-first and offline-only, not an API wrapper.\n\n```bash\ncd python/decision_passport_py\npip install -e .\npython -m decision_passport.verify ../../fixtures/valid-bundle.json\npython -m decision_passport.diff ../../fixtures/valid-bundle.json ../../fixtures/tampered-bundle.json\n```\n\nThe verifier checks:\n\n1. Every `record_hash` matches the recomputed deterministic hash\n2. Every `prev_hash` correctly chains to the previous record\n3. Sequence numbers are gapless and correct\n4. `chain_hash` in the manifest matches the terminal record\n\nIf the input is malformed, verification returns `FAIL` with a structure reason code.\nIf integrity checks fail, verification returns `FAIL` with integrity reason codes.\n\n### Schema and compatibility\n\n- [Schema and versioning](docs/schema-versioning.md): bundle structure, record fields, hashing rules, evolution guidance\n- [Compatibility matrix](docs/compatibility-matrix.md): which tools work with which formats\n- [Verifier compatibility promise](docs/verifier-compatibility-promise.md): 12-month supported/deprecated/unsupported policy\n- [Verifier auditor output](docs/verifier-auditor-output.md): deterministic verdict/code/location/reason/remediation_hint contract\n- [Protocol conformance](docs/protocol-conformance.md): normative verifier checks and fixture outcomes\n- [Conformance manifest](fixtures/conformance-manifest.json): machine-readable expected verdict map for canonical fixtures\n- [JSON Schemas](docs/json-schema/): machine-readable schemas for `BasicProofBundle`, `ChainManifest`, `PassportRecord`\n- [Release verification](docs/release-verification.md): how to verify a published release locally\n- [Release provenance](docs/release-provenance.md): official release artifacts, 3-minute local verification, and trust limitations\n- [Reference integrations](examples/reference-integrations/README.md): two ultra-small end-to-end examples (webhook approval receipt and agent/tool execution receipt)\n- [Append-only guarantees](docs/append-only-guarantees.md): what the protocol enforces, what verification detects, storage-level limits\n- [Bundle Diff](docs/bundle-diff.md): how to compare two bundles, generate diff artifacts, and interpret findings\n\n### Trust model docs\n\n- [Boundaries](docs/BOUNDARIES.md): exact scope, non-goals, and trust boundary edges\n- [Threat model](docs/THREAT_MODEL.md): addressed threats, assumptions, and residual risk\n- [Verification model](docs/VERIFICATION_MODEL.md): PASS and FAIL semantics, safe interpretation\n- [Tamper cases](docs/TAMPER_CASES.md): concrete failure patterns and investigation guidance\n\n---\n\n## Lite vs Enterprise\n\n| Capability | Core (this repo) | Enterprise (private) |\n| --- | --- | --- |\n| Append-only hash chain | ✓ Free | ✓ |\n| Basic bundle export (JSON) | ✓ Free | ✓ |\n| Offline verifier | ✓ Free | ✓ |\n| CLI verifier | ✓ Free | ✓ |\n| Demo + examples | ✓ Free | ✓ |\n| Execution claims (single-use auth tokens) | N/A | ✓ |\n| Guard enforcement (blocking before execution) | N/A | ✓ |\n| Replay protection (nonce + TTL) | N/A | ✓ |\n| Outcome binding (cryptographic result sealing) | N/A | ✓ |\n| PostgreSQL persistence | N/A | ✓ |\n| Redis distributed locking | N/A | ✓ |\n| Merkle proof bundle | N/A | ✓ |\n| Advanced verifier (enterprise-grade) | N/A | ✓ |\n| Sovereign signed bundles (HMAC-SHA256) | N/A | ✓ |\n| Air-gapped verifier packaging | N/A | ✓ |\n| Dashboard + live backend | N/A | ✓ |\n| SSO / RBAC / tenant isolation | N/A | ✓ |\n\n---\n\n## Commercial paths\n\nCore is free and open source.\n\nHosted, business, enterprise, and sovereign deployment options are available on request.\n\nContact: [contact@bespea.com](mailto:contact@bespea.com)\n\n---\n\n## Roadmap\n\n- [x] Core hash chain engine\n- [x] BasicProofBundle export\n- [x] Offline verifier\n- [x] CLI verifier\n- [x] Demo with sample data\n- [x] Tamper explainer\n- [x] HTML verification report export\n- [x] Browser verifier\n- [x] Deterministic valid + tampered fixtures\n- [x] Bundle diff utility\n- [x] Tool Call Wrapper (`withDecisionPassportToolCall()`)\n- [x] Batch Verification + Audit Reports (`verifyBundleBatch()`, failure classification, JSON/Markdown reports)\n- [x] Autonomous Action Receipt Profile\n- [ ] MCP verifier/recorder server\n- [ ] OpenClaw Lite alignment against core wrapper\n- [ ] Provider adapters for OpenAI/Anthropic tool-use flows\n- [ ] Python parity for Tool Call Wrapper\n- [ ] Trusted timestamping integration (RFC 3161)\n\n---\n\n## Repo map\n\nThis repository is the **public protocol layer**. The full ecosystem:\n\n| Repo | Visibility | Purpose |\n| --- | --- | --- |\n| `decision-passport-core` | **Public** | This repo: protocol, chain, basic verifier |\n| `decision-passport-openclaw-lite` | **Public** | OpenClaw integration bridge (Lite) |\n| `decision-passport-control-plane-real` | **Private** | Claims, guard, replay, outcomes, persistence |\n| `decision-passport-sovereign-real` | **Private** | Signed bundles, air-gapped verifier |\n\n---\n\n## External Technical Validation\n\nTo keep this repository technically honest, we keep public feedback channels focused on reproducible verifier and conformance evidence.\n\n- Adoption and validation signals: `docs/adoption-signals.md`\n- Verifier contract feedback template: `.github/ISSUE_TEMPLATE/verifier-contract-feedback.md`\n- Conformance/integration feedback template: `.github/ISSUE_TEMPLATE/conformance-or-integration-feedback.md`\n\nWhen reporting feedback, include exact commands, fixture/bundle inputs, and expected vs actual verifier outputs.\n\n---\n\n## Contributing\n\nContributions to the public protocol are welcome.\n\nFork the repository on GitHub, then run:\n\n```bash\ngit clone https://github.com/YOUR_USERNAME/decision-passport-core.git\ncd decision-passport-core\ngit checkout -b feat/my-improvement\npnpm install --frozen-lockfile\npnpm test\n```\n\nThen open a pull request with a clear description of what changed and why.\n\n---\n\n## License\n\n[Apache-2.0](LICENSE). See full text in LICENSE file.\n\n\u003e 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.\n\n---\n\n## About\n\nDecision Passport is built and maintained by Bespoke Champions League Ltd, London, United Kingdom.\n\nIt powers the trust layer inside [Bespea](https://bespea.com). Decision Passport emerged from a real-world problem: AI systems making material delivery, execution, and approval decisions without a portable, verifiable record.\n\nMaintainer:\nGrigore-Andrei Traistaru\nFounder\n\u003ccontact@bespea.com\u003e\n\u003chttps://bespea.com\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrigalss-a%2Fdecision-passport-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrigalss-a%2Fdecision-passport-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrigalss-a%2Fdecision-passport-core/lists"}