Behavioral Contracts

A Behavioral Contract consolidates an agent's behavioral expectations into a single, versioned, cryptographically sealed, machine-enforceable artifact. It declares what the agent should do, how often, in what patterns, with what outcomes — and the Behavioral Control Plane holds it accountable to that declaration continuously.

Overview

Contracts bridge the gap between an agent's identity (birth certificate) and its runtime governance. Where a certificate says who an agent is, a contract says what it should do.

Contracts bundle:

• Identity binding — links to the agent's birth certificate and archetype

• Behavioral DNA — expected action, target, and outcome distributions derived from the archetype prior

• Authorized scope — what actions and targets the agent is permitted to use

• Trust parameters — initial trust score, floor, and ceiling

• Behavioral invariants — declarative rules the agent must never violate, compiled into runtime checks by the invariant compiler

• Semantic anchors — expected meaning-to-behavior mappings (consumed by the Semantic Drift system)

• Drift thresholds — per-distribution maximum allowed drift before alert/intervention

Core Concepts

Immutability and Versioning

Contracts are frozen dataclasses — once created, they cannot be modified. Changing an agent's expectations requires issuing a new contract version. The ContractStore maintains the full version history for audit purposes.

from nomotic import BehavioralContract, ContractStore

store = ContractStore()
store.store(contract_v1)  # version=1
store.store(contract_v2)  # version=2, must be > 1

active = store.get_active("agent-1")       # returns v2
v1 = store.get_version("agent-1", 1)       # returns v1
history = store.get_history("agent-1")      # returns [v1, v2]

Cryptographic Sealing

Every contract can be sealed with a SigningKey and verified with the corresponding VerifyKey. The seal covers all contract fields except signature and signed_by, so any tampering invalidates the seal.

from nomotic import SigningKey

sk, vk = SigningKey.generate()
sealed = contract.seal(sk, signer_id="[e-mail]")

assert sealed.verify(vk)  # True

Contract Generation

The generate_contract() function creates a contract from an archetype prior, automatically populating expected distributions:

from nomotic import generate_contract, PriorRegistry

registry = PriorRegistry.with_defaults()
contract = generate_contract(
    agent_id="claims-processor-01",
    archetype="customer-experience",
    prior_registry=registry,
    scope={"action_types": ["read", "query"], "targets": ["/crm/*"]},
    drift_thresholds={"action": 0.15, "target": 0.20},
)

If the archetype has a known prior (e.g., customer-experience), the expected distributions are populated from it. Unknown archetypes produce empty distributions — the agent starts with no behavioral baseline and builds one from observations.

Runtime Integration

Drift Threshold Enforcement

When a contract specifies drift_thresholds, the runtime compares the agent's current drift score against those thresholds after every evaluation. If any threshold is exceeded, the violation is recorded in the verdict metadata:

runtime = GovernanceRuntime(RuntimeConfig(enable_contracts=True))
runtime.set_contract(contract)

# After evaluation, if action_drift > contract threshold:
verdict = runtime.evaluate(action, context)
if verdict.metadata and "contract_threshold_violations" in verdict.metadata:
    # {"action": {"current": 0.32, "threshold": 0.15}}
    print(verdict.metadata["contract_threshold_violations"])

Configuration

Contract support is enabled by default in RuntimeConfig:

config = RuntimeConfig(
    enable_contracts=True,       # default: True
    contract_store=None,         # auto-created if None
)

To use a shared store across components, pass an explicit ContractStore instance.

API Endpoints

Method	Path	Description
POST	/v1/contracts	Generate and store a contract
GET	/v1/contracts/{agent_id}	Get active contract
GET	/v1/contracts/{agent_id}/history	Get version history
GET	/v1/contracts/{agent_id}/diff?v1=X&v2=Y	Diff between versions

POST /v1/contracts

{
  "agent_id": "claims-processor-01",
  "archetype": "customer-experience",
  "scope": {"action_types": ["read", "query"]},
  "drift_thresholds": {"action": 0.15, "target": 0.20}
}

GET /v1/contracts/{agent_id}/diff?v1=1&v2=2

Returns per-field changes between two versions:

{
  "version_from": 1,
  "version_to": 2,
  "changes": {
    "expected_action_distribution": {
      "read": {"from": 0.6, "to": 0.4},
      "write": {"from": 0.1, "to": 0.3}
    },
    "drift_thresholds": {
      "action": {"from": 0.15, "to": 0.25}
    }
  }
}

CLI Commands

# Generate a contract from archetype defaults
nomotic contract generate --agent=claims-01 --archetype=customer-experience

# Show the active contract for an agent
nomotic contract show --agent=claims-01

# Validate the cryptographic seal
nomotic contract validate --agent=claims-01

# Diff two contract versions
nomotic contract diff --agent=claims-01 --v1=1 --v2=2

Contract Fields Reference

Field	Type	Description
contract_id	str	Unique identifier (UUID)
version	int	Monotonically increasing version number
agent_id	str	Agent this contract governs
created_at	float	Unix timestamp of creation
certificate_id	str | None	Linked birth certificate
archetype	str	Archetype name (default: "general")
expected_action_distribution	dict[str, float]	Expected action type ratios (~1.0)
expected_target_distribution	dict[str, float]	Expected target ratios (~1.0)
expected_outcome_distribution	dict[str, float]	Expected verdict ratios (~1.0)
authorized_scope	dict[str, Any]	Authorized actions and targets
initial_trust	float	Starting trust score (default: 0.5)
trust_floor	float	Minimum trust (default: 0.0)
trust_ceiling	float	Maximum trust (default: 1.0)
invariants	list[dict]	Behavioral invariant specs
semantic_anchors	list[dict]	Semantic anchor definitions
drift_thresholds	dict[str, float]	Max drift per distribution (0.0–1.0)
signature	str	Hex-encoded cryptographic signature
signed_by	str	Signer identity

Drift Threshold Keys

Key	Distribution	What It Measures
action	Action	Shift in what types of actions the agent performs
target	Target	Shift in what resources the agent operates on
temporal	Temporal	Shift in when/how frequently the agent acts
outcome	Outcome	Shift in governance evaluation outcomes
semantic	Semantic	Shift in the intent/meaning of actions
overall	Composite	Weighted combination of all distributions

Example: Full Lifecycle

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

# 1. Generate contract from archetype
registry = PriorRegistry.with_defaults()
v1 = generate_contract(
    agent_id="support-bot",
    archetype="customer-experience",
    prior_registry=registry,
    drift_thresholds={"action": 0.15, "target": 0.20, "outcome": 0.25},
)

# 2. Seal it
sk, vk = SigningKey.generate()
v1_sealed = v1.seal(sk, signer_id="platform-admin")
assert v1_sealed.verify(vk)

# 3. Store in runtime
runtime = GovernanceRuntime(RuntimeConfig(enable_contracts=True))
runtime.set_contract(v1_sealed)

# 4. Later, update expectations (new version)
import dataclasses, uuid, time
v2 = dataclasses.replace(
    v1,
    contract_id=str(uuid.uuid4()),
    version=2,
    created_at=time.time(),
    drift_thresholds={"action": 0.25, "target": 0.30, "outcome": 0.25},
    signature="",
    signed_by="",
)
v2_sealed = v2.seal(sk, signer_id="platform-admin")
runtime.set_contract(v2_sealed)

# 5. Audit the change
diff = v1_sealed.diff(v2_sealed)
print(diff["changes"])  # Shows drift_thresholds changes