Behavioral Invariants

Behavioral Invariants are declarative rules that express organizational behavioral expectations in terms that compliance teams can read and governance systems can enforce. They go beyond scope and permissions to capture patterns, ratios, rates, distributions, and meaning.

Overview

Invariants describe what normal behavior looks like — and flag when behavior departs from those norms. They are the core of what makes the Behavioral Control Plane a true control plane: in networking, a control plane defines routing rules that the data plane enforces. In Nomotic, behavioral invariants define behavioral rules that the governance pipeline enforces.

Invariants are compiled into optimized evaluation artifacts that attach to Behavioral Contracts and integrate into the governance pipeline. The compilation step transforms human-readable behavioral declarations into efficient runtime checks, including pre-computed thresholds, window configurations, and aggregation functions.

Invariant Types

Type	Description	Example
ratio	Distribution ratio constraints	Write-to-read ratio must stay below 0.3
distribution	Distribution shape constraints	No single target should exceed 60% of activity
drift	Drift threshold constraints	Action drift must stay below 0.20
semantic	Meaning fidelity constraints	Semantic fidelity for 'research' must stay above 0.85
temporal	Timing constraints	No activity outside business hours (8-18)
rate	Frequency constraints	Action rate must not exceed 2x baseline in window
count	Cardinality constraints	No more than 5 distinct targets per session

Quick Start

Using the Builder API

The InvariantBuilder provides a fluent API for creating invariant specifications:

from nomotic import InvariantBuilder, CompiledInvariants

# Define invariants
invariants = [
    InvariantBuilder.ratio(
        "write_to_read", "lt", 0.3,
        description="Write-to-read ratio must stay below 30%"
    ),
    InvariantBuilder.drift(
        "action", "lt", 0.20,
        description="Action distribution drift must stay below 20%"
    ),
    InvariantBuilder.semantic(
        "research", "gt", 0.85,
        description="Semantic fidelity for 'research' must exceed 85%"
    ),
    InvariantBuilder.count(
        "distinct_targets", "lt", 5.0, window=50,
        description="No more than 5 distinct targets in any 50-action window"
    ),
]

# Compile — validates all specs and raises ValueError on invalid specs
compiled = CompiledInvariants.compile(invariants)

Attaching to Contracts

Invariants are carried by Behavioral Contracts as a list of dictionaries:

from nomotic import BehavioralContract, InvariantBuilder
import time

contract = BehavioralContract(
    contract_id="contract-1",
    version=1,
    agent_id="claims-processor-01",
    created_at=time.time(),
    invariants=[
        InvariantBuilder.ratio("write_to_read", "lt", 0.3).to_dict(),
        InvariantBuilder.drift("action", "lt", 0.20).to_dict(),
        InvariantBuilder.semantic("research", "gt", 0.85).to_dict(),
    ],
)

# Compile from contract
compiled = contract.compile_invariants()

Evaluating at Runtime

Pass current behavioral state to evaluate all invariants:

from nomotic import FingerprintObserver, PriorRegistry

# Get current behavioral state
fingerprint = observer.get_fingerprint("agent-1")
drift = observer.get_drift("agent-1")
semantic_drift = observer.get_semantic_drift("agent-1")

# Evaluate
results = compiled.evaluate(
    fingerprint=fingerprint,
    drift_score=drift,
    semantic_drift=semantic_drift,
)

for r in results:
    print(f"{r.invariant_id}: {r.status} (value={r.current_value:.3f}, "
          f"threshold={r.threshold}, margin={r.margin:.2f})")

Core Concepts

InvariantSpec

A frozen dataclass that declares a single behavioral expectation:

Field	Type	Description
invariant_id	str	Unique identifier (auto-generated by Builder)
type	str	One of: ratio, distribution, drift, semantic, temporal, rate, count
description	str	Human-readable description
metric	str	What to measure (interpretation depends on type)
operator	str	Comparison: lt, gt, lte, gte, eq, between
threshold	float	The threshold value
threshold_upper	float | None	Upper bound for "between" operator
window	int | None	Rolling window size (number of actions)
window_seconds	float | None	Time-based window alternative

Metric Interpretation by Type

ratio: The metric field uses X_to_Y format, e.g. "write_to_read". The value is computed as action_distribution[X] / action_distribution[Y].

distribution: Supported metrics include "target_max" (highest single target proportion), "action_max" (highest single action proportion), and "target_count" (number of distinct targets).

drift: The metric names a drift distribution: "action", "target", "temporal", "outcome", "semantic", or "overall".

semantic: The metric is the anchor term name (e.g., "research"). The threshold is expressed as fidelity (1.0 - drift), so gt 0.85 means "semantic drift for this term must stay below 0.15".

temporal: The metric specifies allowed hours as "start-end", e.g. "8-18" for business hours. The measured value is the fraction of actions outside those hours.

rate: The metric is "action_frequency". Value is actions per second within the window.

count: Supported metrics: "distinct_targets" and "distinct_actions" within the window.

Operators

Operator	Meaning
lt	Current value must be less than threshold
gt	Current value must be greater than threshold
lte	Current value must be less than or equal to threshold
gte	Current value must be greater than or equal to threshold
eq	Current value must equal threshold (within 0.001)
between	Current value must be between threshold and threshold_upper

InvariantResult

Each evaluated invariant produces an InvariantResult:

Field	Type	Description
invariant_id	str	Which invariant was evaluated
satisfied	bool	Whether the invariant passed
current_value	float	The measured metric value
threshold	float	The threshold it was compared against
margin	float	Distance from threshold (0.0 = at threshold, higher = safer)
status	str	"satisfied", "violated", or "approaching"
detail	str	Human-readable evaluation detail

Status logic:

• "violated" — invariant is not satisfied

• "approaching" — satisfied but margin < 0.20 (within 20% of threshold)

• "satisfied" — satisfied with comfortable margin

CompiledInvariants

The compilation step validates all specs, groups them by evaluation strategy, and provides the evaluate() and summary() methods:

compiled = CompiledInvariants.compile(specs)

# Evaluate against current state
results = compiled.evaluate(
    fingerprint=fp,
    drift_score=drift,
    semantic_drift=sem_drift,
    action_window=recent_actions,
)

# Summary counts
summary = compiled.summary()
# {"satisfied": 5, "violated": 1, "approaching": 2}

Runtime Integration

When a contract carries invariants, the governance runtime automatically evaluates them after every verdict and updates the Behavioral Provenance with invariant status counts:

verdict = runtime.evaluate(action, context)

prov = verdict.behavioral_provenance
print(prov.invariants_satisfied)    # 5
print(prov.invariants_violated)     # 0
print(prov.invariants_approaching)  # 1
print(prov.summary())
# FP: 85% (500 obs) | Drift: low (action 0.08) | Contract v1: compliant | Trust: 0.72 (rising)

Structural vs Semantic Invariants

Invariants fall into two categories:

Structural invariants describe operational patterns:

• "Action frequency should not increase more than 2x within any 1-hour window"

• "The write-to-read ratio should stay below 0.3"

• "No more than 5 distinct target categories should be accessed in a single session"

Semantic invariants describe meaning preservation:

• "Semantic similarity to contract anchor for 'research' must stay above 0.85 across any 10-action window"

• "No instruction term should shift more than 15% from its baseline action mapping"

Both types are specified using the same InvariantSpec format and compiled into the same evaluation pipeline.

Example: Complete Contract with Invariants

from nomotic import (
    BehavioralContract, ContractStore, InvariantBuilder,
    GovernanceRuntime, RuntimeConfig, PriorRegistry,
    generate_contract,
)
import time

# Define invariants
invariant_dicts = [
    InvariantBuilder.ratio(
        "write_to_read", "lt", 0.3,
        description="Write-to-read ratio must stay below 30%"
    ).to_dict(),
    InvariantBuilder.distribution(
        "target_max", "lt", 0.6,
        description="No single target should exceed 60% of activity"
    ).to_dict(),
    InvariantBuilder.drift(
        "action", "lt", 0.20,
        description="Action distribution drift below 20%"
    ).to_dict(),
    InvariantBuilder.semantic(
        "research", "gt", 0.85,
        description="Research term fidelity above 85%"
    ).to_dict(),
    InvariantBuilder.count(
        "distinct_targets", "lt", 10.0, window=100,
        description="No more than 10 targets in any 100-action window"
    ).to_dict(),
]

# Generate contract with invariants
registry = PriorRegistry.with_defaults()
contract = generate_contract(
    agent_id="research-bot",
    archetype="research",
    prior_registry=registry,
    invariants=invariant_dicts,
    drift_thresholds={"action": 0.15, "target": 0.20},
)

# Store and use in runtime
runtime = GovernanceRuntime(RuntimeConfig(enable_contracts=True))
runtime.set_contract(contract)

# Invariants are now automatically evaluated on every action

Validation

Every InvariantSpec can be validated before compilation:

spec = InvariantSpec(
    invariant_id="test",
    type="rate",
    metric="action_frequency",
    operator="lt",
    threshold=2.0,
    description="Rate limit",
    # Missing required window!
)

errors = spec.validate()
# ["Type 'rate' requires window or window_seconds to be set."]

CompiledInvariants.compile() validates all specs and raises ValueError if any are invalid, ensuring only well-formed invariants reach runtime evaluation.