Provenance

The Audit Trail for Every AI Action

What is Provenance?

Provenance is the complete history of who did what, when, and on whose authority. Every action in the HUMΛN ecosystem is logged with full context.

Think of it as Git for AI workflows — you can trace every decision back to its origin, understand who authorized it, and verify it cryptographically.

Why Provenance Matters

Compliance: Prove who did what for audits

Debugging: Trace errors to their source

Trust: Verify AI decisions

Security: Detect unauthorized actions

What's Tracked?

Every action in HUMΛN generates a provenance entry with:

🔐 Who

The Passport ID of the actor (human, org, or agent). If delegated, includes both delegator and delegatee.

📋 What

The action type (e.g., passport.create, workflow.approve) and the resource affected (e.g., workflow_abc123).

⏰ When

The timestamp (ISO 8601 format) of when the action occurred.

🗂️ Context

Additional metadata: delegationId, capabilitiesUsed, workflowId, input/output data, and more.

🔗 Chain

The provenance chain — a linked list of all actions that led to this one. Example: Alice → Acme Corp → Invoice Agent → Action

Example Provenance Entry

json

{
  "provenanceId": "prov_abc123xyz",
  "timestamp": "2024-01-15T14:32:10.123Z",
  "actionType": "workflow.orchestrate",
  "resourceId": "workflow_inv_batch_50",
  
  // Who performed the action
  "actor": {
    "passportId": "passport_agent_invoice",
    "type": "agent",
    "name": "Invoice Processor"
  },
  
  // On whose behalf (if delegated)
  "delegator": {
    "passportId": "passport_alice_123",
    "type": "individual",
    "name": "Alice Smith"
  },
  
  // What capabilities were used
  "capabilitiesUsed": [
    "invoice_processing",
    "financial_analysis"
  ],
  
  // Delegation info
  "delegationId": "delegation_alice_to_agent",
  
  // Action details
  "action": {
    "task": "Process 50 invoices from Acme Corp",
    "inputData": {
      "invoiceCount": 50,
      "organization": "Acme Corp"
    },
    "outputData": {
      "processedCount": 50,
      "totalAmount": 125000,
      "summary": "..."
    }
  },
  
  // Provenance chain (who authorized whom)
  "chain": [
    {
      "passportId": "passport_alice_123",
      "type": "individual",
      "action": "delegated_to"
    },
    {
      "passportId": "passport_acme_corp",
      "type": "organization",
      "action": "employed"
    },
    {
      "passportId": "passport_agent_invoice",
      "type": "agent",
      "action": "executed"
    }
  ],
  
  // Cryptographic signature
  "signature": "0x1234...abcd"
}

Query Provenance

Use the Provenance API to query the audit trail:

Get Provenance for a Resource

SDK:

Query by Actor

SDK:

Query by Capability

SDK:

Understanding the Provenance Chain

Every action includes a provenance chain — a linked list of authorizations:

┌──────────────────────────────────────────────────────────────┐
│                   PROVENANCE CHAIN                             │
├──────────────────────────────────────────────────────────────┤
│                                                                │
│  Alice Smith [Individual]                                      │
│  passport_alice_123                                            │
│        ↓ employed by                                           │
│  Acme Corp [Organization]                                      │
│  passport_acme_corp                                            │
│        ↓ delegated to                                          │
│  Invoice Processor [Agent]                                     │
│  passport_agent_invoice                                        │
│        ↓ executed                                              │
│  Workflow: Process 50 Invoices                                 │
│  workflow_inv_batch_50                                         │
│                                                                │
└──────────────────────────────────────────────────────────────┘

This chain proves:
1. Alice works for Acme Corp
2. Alice delegated to the Invoice Processor agent
3. The agent executed the workflow on Alice's behalf
4. Full authority chain: Alice → Acme Corp → Agent → Action

Common Use Cases

Compliance Audits

Export provenance logs to prove who performed what actions during a specific time period (SOC 2, GDPR, HIPAA)

Security Investigations

Trace suspicious activity back to its source. Did an agent exceed its delegation? Find out instantly.

Debugging Workflows

When a workflow fails, query provenance to see exactly what happened, in what order, and with what data.

Cost Attribution

Track which agents/workflows consume the most resources. Bill back to departments or customers.

Agent Performance

Analyze provenance to see which agents are fastest, most reliable, or most cost-effective.

Provenance vs Traditional Logs

Feature	Traditional Logs	Provenance
Structure	Unstructured text	Structured JSON
Authority Chain	Not tracked	Full chain
Cryptographic Proof	None	Signed & verifiable
Queryable	Grep/search only	Rich API queries
Delegation Context	Not captured	Full delegation info

Learn More