Skip to main content

Source: docs/manual/provenance.md

This page is generated by site/scripts/sync-manual-docs.mjs.

Provenance Graph

The provenance graph records every action, decision, and data dependency in an agent run as a tamper-evident directed acyclic graph. It enables forensic analysis, run comparison, and reproducibility verification beyond what flat step logs provide.

Source: internal/agent/provenance*.go, cmd/provenance-query/main.go

Overview​

Provenance stores execution history as a directed graph instead of only flat step logs.

Why it matters:

  • trace what influenced a specific decision or output
  • compare divergence across runs
  • inspect cross-step influence chains

Graph Model​

Node Types​

  • decision
  • tool_call
  • tool_result
  • memory_fact
  • observation
  • input
  • output

Edge Types​

  • influenced
  • triggered
  • produced
  • consumed

Storage:

  • provenance_nodes
  • provenance_edges

How Graphs Are Built​

During trace save:

  • decision nodes are created from Decision
  • tool call/result nodes are attached when tools execute
  • memory influences are captured (aggregate and per-fact)
  • previous observation nodes can influence current decision nodes

When enabled, provenance persistence is coupled with trace writes and can run in one Postgres transaction path.

Query Modes​

CLI supports:

  • run subgraph (--run-id, optional --step)
  • ancestor traversal (--node-id --depth)
  • descendant traversal (--node-id --depth)
  • run diff (--run-id + --diff-run-id)

Step subgraph behavior includes cross-step same-run context when one edge endpoint is in the requested step.

Run Diffing​

DiffRuns compares run graphs by step and node type.

Reported diff classes include:

  • different_decision
  • different_tool_result
  • different_memory
  • missing_step

Use this to find where behavior diverged between two executions.

Retention and Pruning​

When trace retention pruning is enabled for runs, provenance nodes/edges are pruned with the same cutoff.

This keeps trace and provenance datasets consistent over long-lived runs.

CLI Reference​

cmd/provenance-query flags:

  • --run-id
  • --step
  • --node-id
  • --diff-run-id
  • --depth
  • --format text|json
  • --tenant

Configuration​

  • CRUVERO_PROVENANCE_ENABLED (default false)