HUMΛN

Provenance Tracking

Every action in HUMΛN creates an immutable provenance record. Who did what, when, with whose authority, and why is always traceable. Provenance is the foundation of trust and accountability.

What is Provenance?

Provenance is the complete, auditable history of an entity or action. In HUMΛN, provenance tracks:

✅ Every Action

What happened, when, and the outcome

✅ Every Actor

Who performed the action (human or agent)

✅ Every Delegation

Who authorized whom to act on their behalf

✅ Every Context

Why the action was taken and under what conditions

python
# Every action automatically creates provenance
workflow = client.humanos.orchestrate(
    task="Process invoices",
    required_capabilities=["invoice_processing"]
)


# Query provenance chain
chain = client.provenance.get(workflow.workflow_id)


for entry in chain:
    print(f"[{entry.timestamp}] {entry.actor}")
    print(f"  Action: {entry.action}")
    print(f"  Delegated by: {entry.delegator}")
    print(f"  Capability used: {entry.capability}")
    print(f"  Result: {entry.result}")

The Provenance Chain

Actions form a chain of accountability. When an agent acts on behalf of a human, the provenance chain shows both identities:

1

Alice (Human) delegates to Agent

Delegation created: delegation_abc123

Scope: invoice_processing | Expires: 2024-12-31

2

Agent processes invoice INV-2024-001

Acting as: Agent on behalf of Alice

Capability: invoice_processing (expert) | Result: Approved $2,500

3

Alice reviews and confirms

Action: workflow.approve

Notes: "Approved. Good work." | Timestamp: 2024-01-15T14:32:00Z

Immutability & Cryptographic Integrity

Tamper-Proof Records

Provenance records are immutable and cryptographically signed. Once created, they cannot be:

  • •Modified - Content is hashed and chained
  • •Deleted - Records are permanent by design
  • •Reordered - Timestamps and sequence numbers enforce order
  • •Forged - Cryptographic signatures verify authenticity
python
# Verify provenance integrity
chain = client.provenance.get("passport_agent")


# Each entry includes cryptographic proof
for entry in chain:
    print(f"Entry ID: {entry.entry_id}")
    print(f"Previous hash: {entry.previous_hash}")
    print(f"Current hash: {entry.hash}")
    print(f"Signature: {entry.signature}")
    print(f"Signer: {entry.signer}")
    
    # Verify signature
    is_valid = client.provenance.verify_signature(entry)
    print(f"Valid: {is_valid}")

Querying Provenance

Provenance can be queried in multiple ways to support different audit needs:

By Entity (Passport)

Get all actions by a specific human or agent

python
# Get all actions by an agent
chain = client.provenance.get("passport_agent_456")


print(f"Total actions: {len(chain)}")
for entry in chain:
    print(f"  {entry.timestamp}: {entry.action}")

By Workflow

Trace all actions in a specific workflow

python
# Get provenance for a workflow
workflow_chain = client.provenance.query(
    entity_type="workflow",
    entity_id="workflow_abc123"
)


print("Workflow execution trace:")
for entry in workflow_chain:
    print(f"  [{entry.timestamp}] {entry.actor}: {entry.action}")

By Delegation Chain

See all actions performed under a delegation

python
# Query by delegation
delegated_actions = client.provenance.query(
    delegation_id="delegation_abc123",
    start_date="2024-01-01",
    end_date="2024-01-31"
)


print(f"Actions performed under delegation: {len(delegated_actions)}")

By Capability

Audit all uses of a specific capability

python
# Find all invoice processing actions
capability_actions = client.provenance.query(
    capability_id="invoice_processing",
    time_range={"start": "2024-01-01", "end": "2024-12-31"}
)


print(f"Total invoice processing actions: {len(capability_actions)}")

Compliance & Regulatory Audit

Provenance records support compliance with regulatory requirements including:

SOC 2

Audit trails for access control and data handling

GDPR

Right to audit, data lineage, consent tracking

SOX

Financial transaction traceability

HIPAA

Healthcare data access logging

Organizations can export provenance records in standard audit formats for compliance reporting.

Related

Provenance API

Query provenance programmatically

Constitutional Governance

Provenance as constitutional requirement