BehaviorLedger

The BehaviorLedger assembles a complete, self-contained decision record at write time so that any governance decision can be fully reconstructed without querying multiple systems.

This is the difference between an audit trail (a log of events) and a behavior ledger (a reconstructable record of judgment). Nomotic has the audit trail. The BehaviorLedger makes every entry in that trail fully self-explanatory.

What a Ledger Entry Contains

Every BehaviorLedgerEntry captures:

• Verdict: the governance decision (ALLOW, DENY, ESCALATE, MODIFY, SUSPEND), UCS score, tier, reasoning, and vetoes

• Pipeline Trace: every decision point the runtime evaluated, with input/output state at each step

• Dimension Scores: all dimension assessments (not just top 3), with scores, weights, veto flags, and reasoning

• Behavioral State: fingerprint confidence, observations, drift by distribution, severity, trust score/direction/velocity

• Contract Snapshot: the contract state at the time of decision, embedded so reconstruction works even after contract updates

• Semantic Context: instruction context, matched anchor terms, per-term drift, aggregate semantic drift

• Causal Links: connections to previous decisions showing how they influenced this one through trust changes

• Action-to-Pass: what would need to change for a different verdict (dimension gaps for denials, safety margin for approvals)

• Reversibility Assessment: reversibility level, whether it forced Tier 3 escalation

• Cross-Dimensional Signals: count and UCS adjustment from correlated dimension patterns

• Contextual Modification: weight adjustments and trust modifiers applied

• Hash Chain: cryptographic hash linking to previous entry for tamper evidence

Pipeline Trace

The PipelineTracer captures every decision point during evaluate():

Step	Description
trust_decay	Time decay applied to trust profile
contextual_modifier	Weight and trust modifications from context
reversibility	Reversibility assessment of the action
dimension_eval	Evaluation of all governance dimensions
cross_dimensional	Cross-dimensional signal detection
tier1	Tier 1 deterministic gate (veto check)
ucs_compute	Unified Confidence Score computation
ucs_adjustment	Cross-dimensional UCS adjustment
reversibility_escalation	Forced Tier 3 due to irreversibility
tier2	Tier 2 threshold evaluation
tier3	Tier 3 deliberative review

Each step records input_state, output_state, and whether it produced the final verdict (decided_verdict).

Causal Chain

Each ledger entry links to its predecessor through CausalLink objects. These show how previous decisions influenced the current one — primarily through trust changes. The get_causal_chain() method walks these links backward, producing a complete decision history.

Action-to-Pass

For every decision, the ledger records what would need to change:

• DENY verdicts: which dimensions need improvement (dimension_gaps), what UCS is needed (ucs_needed), and the gap

• ALLOW verdicts: the safety margin (margin_to_deny) and the closest dimension to triggering a veto

Reading a Ledger Entry

Summary Format

Decision #847 for agent claims-bot at 2026-03-07T14:22:03Z. Action: query on
customer_records. Verdict: ALLOW (UCS 0.847, Tier 2). Pipeline: trust_decay:
no change, tier2: allow, no vetoes. Behavioral state: fingerprint 94%
confidence, drift low, trust 0.72 (rising). Contract: contract v3 (12
invariants). Margin to deny: 0.547. Previous decision #846 contributed
+0.010 trust.

Narrative Format

Multi-paragraph reconstruction walking through each pipeline step, suitable for compliance review or regulatory reporting.

CLI Commands

# Show the most recent ledger entry for an agent
nomotic ledger show --agent=<id>

# Show a specific entry by sequence number
nomotic ledger show --agent=<id> --sequence=<n>

# Walk causal chain backward from an entry
nomotic ledger trace --agent=<id> --sequence=<n> --depth=<n>

# Print narrative reconstruction
nomotic ledger narrative --agent=<id> --sequence=<n>

# Verify hash chain integrity
nomotic ledger verify --agent=<id>

# Query entries with filters
nomotic ledger query --agent=<id> --verdict=DENY --limit=10

API Endpoints

Method	Path	Description
GET	/v1/ledger/{agent_id}/latest	Most recent entry
GET	/v1/ledger/{agent_id}/{sequence}	Specific entry
GET	/v1/ledger/{agent_id}/trace/{sequence}?depth=10	Causal chain
GET	/v1/ledger/{agent_id}/narrative/{sequence}	Narrative (text/plain)
GET	/v1/ledger/{agent_id}?verdict=DENY&limit=10	Query with filters
GET	/v1/ledger/{agent_id}/verify	Hash chain verification

Configuration

Enable the BehaviorLedger in RuntimeConfig:

from nomotic.runtime import GovernanceRuntime, RuntimeConfig

runtime = GovernanceRuntime(RuntimeConfig(
    enable_behavior_ledger=True,
))

Or provide your own store:

from nomotic.behavior_ledger import BehaviorLedgerStore

store = BehaviorLedgerStore(base_dir="/path/to/ledger", max_entries=100000)
runtime = GovernanceRuntime(RuntimeConfig(
    enable_behavior_ledger=True,
    behavior_ledger_store=store,
))

Performance

• Zero overhead when disabled: no tracer is created, no pipeline steps are recorded

• Minimal overhead when enabled: the tracer collects already-computed data at each pipeline step; the ledger entry is assembled from existing objects (verdict, fingerprint, drift, contract) after the verdict is produced

• Hash chain computation: one SHA-256 per entry, ~microseconds