Audit Trail

The audit trail is Layer 4 of the Kanoniv agent infrastructure stack: Identity -> Delegation -> Simulation -> Audit. It provides cryptographic proof of every action an agent takes against the identity graph.

The Problem

When AI agents resolve, merge, split, and mutate identity records, you need answers to three questions:

1. Who performed the action? (Which agent, provably)
2. What did they do? (Which entities were affected, and how)
3. Why was it allowed? (What delegation chain authorized it)

Traditional audit logs answer these with trust - you trust the server wrote the log correctly. Kanoniv's provenance system answers them with cryptography - each entry is signed by the agent's Ed25519 key and can be verified independently.

Provenance Entries

A ProvenanceEntry is a signed record of an agent action. It contains:

Field	Description
agent_did	The did:agent: identifier of the agent that acted
action	What was done (resolve, merge, split, etc.)
entity_ids	Which entities were affected
parent_ids	Content hashes of prior entries this one depends on
metadata	Arbitrary JSON context (reason, confidence, source)
signed_envelope	Ed25519 signature over the canonical payload

Every field is covered by the signature. Tampering with any outer field (even metadata) is detected during verification.

Action Types

Eight built-in action types cover the full identity lifecycle:

Action	When to use
resolve	Agent resolved a record to an entity
merge	Agent merged two or more entities
split	Agent split an entity into separate entities
mutate	Agent updated entity attributes
ingest	Agent ingested new source records
delegate	Agent granted authority to another agent
revoke	Agent revoked a prior delegation
custom(name)	Application-specific actions

The Signed DAG

Provenance entries form a directed acyclic graph (DAG) through parent chaining. Each entry's content_hash() - a SHA-256 hash of the signed envelope - serves as a stable identifier that child entries reference via parent_ids.

[Resolve entity-1]  [Resolve entity-2]
    hash: abc...         hash: def...
         \                  /
          \                /
    [Merge entity-1 + entity-2]
      parent_ids: [abc..., def...]
      hash: 789...
             |
    [Mutate merged entity]
      parent_ids: [789...]

This structure provides:

• Causal ordering - you can reconstruct the sequence of decisions that led to any state
• Multi-parent support - a merge entry naturally references the resolve entries for both source entities
• Tamper evidence - changing any entry invalidates all downstream hashes
• Independent verification - any party with the agent's public key can verify the chain

Integrity Verification

Verification checks two things:

1. Signature validity - the Ed25519 signature matches the agent's public key
2. Field integrity - the outer fields (agent_did, action, entity_ids, parent_ids, metadata) match what was actually signed in the envelope payload

This two-layer check prevents a subtle attack: someone could modify the outer entity_ids field after signing while leaving the signature valid (since the signature covers the inner payload). Full verification catches this.

// Full verification (signature + integrity)
entry.verify(&agent_identity)?;

// Signature-only verification (use with caution)
entry.verify_signature_only(&agent_identity)?;

Provenance vs. Events

Kanoniv provides two complementary audit mechanisms:

	Provenance	Events
Source	Agent-side (client library)	Server-side (Cloud API)
Trust model	Cryptographic (Ed25519 signatures)	Operational (server-generated)
Scope	Any agent action, including local operations	Entity state transitions in the Cloud graph
Chaining	DAG via content hashes	Chronological (timestamp + since cursor)
Use case	Prove an agent's decision history	Monitor entity lifecycle changes

Use provenance when you need to prove which agent made a decision and why. Use events when you need to react to entity state changes in real time.

Next Steps

• ProvenanceEntry in detail - creating, chaining, and verifying entries
• Entity lifecycle events - server-side event stream from the Cloud API
• Rust SDK reference - full API for kanoniv-agent-auth
• TypeScript SDK reference - full API for @kanoniv/agent-auth
• Python SDK reference - full API for kanoniv-agent-auth