Behavioral Provenance

Behavioral Provenance captures the agent's complete behavioral state at the exact moment of every governance decision. It transforms audit trails from sequences of scores into behavioral narratives — making every verdict explainable in behavioral terms.

Overview

Today, a governance verdict carries dimension scores, a UCS, a tier decision, and reasoning strings. Behavioral Provenance enriches every GovernanceVerdict with a BehavioralProvenance snapshot that includes:

• Fingerprint state — current confidence and top action/target distributions

• Drift state — overall drift, severity, and per-distribution breakdown across all five distributions (action, target, temporal, outcome, semantic)

• Semantic state — semantic drift score and most-drifted term

• Contract compliance — how many behavioral invariants are satisfied, violated, or approaching threshold

• Trust trajectory — current score, direction (rising/falling/stable), and velocity

• Behavioral influences — which specific signals influenced this verdict

Why It Matters

Without provenance, an audit trail shows:

Action ALLOWED. UCS: 0.87. Tier 1.

With provenance, the same verdict tells a story:

"This action was allowed because the agent's behavioral fingerprint showed 94% consistency across all five distributions, no active drift signals, and a rising trust trajectory over the last 200 actions."

Or for a denial:

"This action was denied because the agent's write-to-read ratio had exceeded its contract invariant for the past 15 minutes, semantic drift showed the term 'research' shifting toward booking-type actions, and trust was declining."

Quick Start

Behavioral provenance is automatically attached to every verdict when fingerprinting is enabled (the default):

from nomotic import GovernanceRuntime, Action, AgentContext, TrustProfile

runtime = GovernanceRuntime()
action = Action(agent_id="agent-1", action_type="read", target="/data")
context = AgentContext(
    agent_id="agent-1",
    trust_profile=TrustProfile(agent_id="agent-1"),
)

verdict = runtime.evaluate(action, context)

# Access provenance
prov = verdict.behavioral_provenance
print(prov.fingerprint_confidence)   # 0.22
print(prov.drift_severity)           # "none"
print(prov.trust_direction)          # "stable"
print(prov.summary())
# FP: 22% (1 obs) | Drift: none | No contract | Trust: 0.51 (stable)

The BehavioralProvenance Object

BehavioralProvenance is a frozen (immutable) dataclass with the following fields:

Fingerprint Snapshot

Field	Type	Description
fingerprint_confidence	float	0.0–1.0, from BehavioralFingerprint.confidence
total_observations	int	Number of actions observed for this agent
action_distribution_top3	tuple	Top 3 action types by frequency
target_distribution_top3	tuple	Top 3 targets by frequency

Drift State

Field	Type	Description
drift_overall	float	0.0–1.0, aggregate drift score
drift_severity	str	"none", "low", "moderate", "high", "critical"
drift_by_distribution	dict[str, float]	Per-distribution drift: action, target, temporal, outcome, semantic
primary_drift_distribution	str	Which distribution is drifting most

Semantic State

Field	Type	Description
semantic_drift_overall	float	0.0–1.0, semantic drift score
semantic_most_drifted_term	str	Instruction term with most meaning shift
semantic_detail	str	Human-readable explanation

Contract Compliance

Field	Type	Description
contract_id	str	Active contract ID (empty = no contract)
contract_version	int	Active contract version (0 = no contract)
invariants_satisfied	int	Drift thresholds currently within bounds
invariants_violated	int	Drift thresholds currently exceeded
invariants_approaching	int	Within 80% of threshold

Trust Trajectory

Field	Type	Description
trust_score	float	Current trust level (0.0–1.0)
trust_direction	str	"rising", "falling", or "stable"
trust_velocity	float	Rate of trust change per observation

Behavioral Influences

Field	Type	Description
behavioral_influences	tuple[str, ...]	Signals that influenced this verdict

Example influences:

• "moderate action drift (0.25) affecting behavioral consistency"

• "semantic drift on 'research' (0.32)"

• "contract threshold exceeded: action drift 0.30 > 0.15"

• "declining trust trajectory"

Methods

to_dict() -> dict

Full JSON-serializable representation. Tuples are converted to lists.

d = verdict.behavioral_provenance.to_dict()
import json
print(json.dumps(d, indent=2))

summary() -> str

One-line behavioral summary for audit display:

FP: 94% (847 obs) | Drift: low (action 0.08) | Contract v3: compliant | Trust: 0.72 (rising)
FP: 61% (122 obs) | Drift: high (semantic 0.42) | Contract v1: 2 violations | Trust: 0.38 (falling)
FP: 12% (24 obs) | Drift: none | No contract | Trust: 0.50 (stable)

Programmatic Construction

For advanced use cases, you can build provenance directly using build_provenance():

from nomotic import build_provenance, FingerprintObserver, PriorRegistry

observer = FingerprintObserver(prior_registry=PriorRegistry.with_defaults())
# ... after observing actions ...

provenance = build_provenance(
    agent_id="agent-1",
    fingerprint_observer=observer,
    contract_store=contract_store,        # optional
    trust_calibrator=trust_calibrator,    # optional
    contract_threshold_violations=None,   # from verdict.metadata
)

Audit Trail Integration

When audit logging is enabled, behavioral provenance is automatically included in audit record metadata:

record = audit_trail.records[-1]
prov_data = record.metadata.get("behavioral_provenance")
# Returns the full to_dict() output, or None if fingerprinting was disabled

This makes every audit record self-contained — the behavioral context is preserved alongside the governance decision for later review.

Architecture

Behavioral provenance is assembled after all drift computation completes in the governance pipeline:

1. Action evaluated through dimensions and tiers

2. Trust calibration updated

3. Behavioral fingerprint updated, drift computed

4. Contract drift thresholds checked

5. Behavioral provenance assembled from current state

6. Audit trail recorded (includes provenance)

7. Webhooks dispatched