Developer documentation

CAIN Trajectory

Last reviewed 31 August 2026

All docs

CAIN Trajectory Documentation#

Status: LIVE + FUNCTIONAL#

Verified 2026-09-08: /fabric/trajectories/ returns 3 trajectories for test tenant.

CAIN Trajectory is fully functional. The core enforcement engine, API, dashboard, and tests are all implemented and working.

What is CAIN Trajectory?#

CAIN Trajectory monitors and verifies the sequence of actions taken by an AI agent, detecting when individually permitted actions combine into an unsafe, unauthorized, or policy-violating trajectory.

Core principle: An action can be allowed while the trajectory is not.

CAIN evaluates both:

ACTION SAFETY - Is this individual action allowed?
TRAJECTORY SAFETY - Does this action fit within the allowed trajectory?

Trajectory Model#

A trajectory contains ordered events:

IDENTITY
ACTION
TOOL
RESOURCE
DECISION
EXECUTION
RESULT
NEXT ACTION

Every event has:

timestamp
tenant
principal
agent
action
tool
resource
decision ID
policy version
execution status
evidence ID

Trajectory States#

ACTIVE - Trajectory in progress
COMPLETED - Trajectory finished successfully
BLOCKED - Trajectory blocked by enforcement
VIOLATION - Trajectory violation detected
CANCELLED - Trajectory cancelled
EXPIRED - Trajectory expired

Trajectory Policies#

Sequence Constraints#

Trajectory policies define allowed and prohibited sequences:

ALLOW: read_customer_record
ALLOW: summarize_customer_record
DENY: external_upload (after read_customer_record)

Policy Operators#

NEVER_AFTER - This action cannot follow that action
MUST_PRECEDE - This action must come before another
MUST_FOLLOW - This action must come after another
REQUIRES - This action requires something
FORBIDS - This combination is forbidden
MAX_STEPS - Maximum steps in trajectory
MAX_RISK - Maximum risk accumulation
MAX_DURATION - Maximum trajectory duration
REQUIRES_APPROVAL - Approval required for this trajectory

Real-Time Enforcement#

Trajectory monitoring operates in the execution path via make_cain_decision() in cain_private.py:

AGENT → IDENTITY → CURRENT TRAJECTORY → PROPOSED ACTION
     → CAIN POLICY → TRAJECTORY ANALYSIS → RISK VERIFICATION
     → DECISION → ENFORCEMENT → EXECUTION → EVIDENCE

A trajectory violation MUST prevent the consequential action from executing.

Warning: A dashboard warning after the action already happened is NOT trajectory enforcement.

Verdict Model#

CAIN Trajectory uses the existing CAIN verdict model:

ALLOW - Action allowed, trajectory permits
DENY - Action or trajectory denied
REQUIRE_APPROVAL - Trajectory requires approval to continue
UNKNOWN - Cannot determine trajectory safety
ERROR - System error

Evidence#

Every consequential trajectory produces durable evidence with cryptographic integrity:

trajectory ID
event sequence with hash chain
HMAC signature for tamper detection
identity
agent
action
tool
resource
policy version
trajectory rule
decision
execution result
violation state
timestamp

Feature Status#

Feature	Status	Notes
Trajectory observation	LIVE + FUNCTIONAL	API verified 2026-09-08
Trajectory state machine	LIVE + FUNCTIONAL	State transitions work
Trajectory policies	LIVE + FUNCTIONAL	Policies stored and evaluated
Trajectory enforcement (API)	LIVE + FUNCTIONAL	API verified working
Trajectory enforcement (execution path)	LIVE + FUNCTIONAL	Enforced via make_cain_decision()
Trajectory simulation	LIVE + FUNCTIONAL	Evaluate endpoint works
Trajectory replay	LIVE + FUNCTIONAL (read-only)	Replay endpoint exists
Tenant isolation	LIVE + FUNCTIONAL	Verified - tenant-scoped queries
Evidence integrity	LIVE + FUNCTIONAL	HMAC+hash chain verified
Dashboard	LIVE + FUNCTIONAL	Shows real trajectory data
CLI	LIVE + FUNCTIONAL	cain trajectory commands work
API	LIVE + FUNCTIONAL	/fabric/trajectories/ verified
Conformance tests	LIVE + FUNCTIONAL	Tests exist and pass
MCP Integration	NOT DEPLOYED	Future work

API Endpoints#

Create Trajectory#

POST /fabric/trajectories/

Get Trajectory#

GET /fabric/trajectories/{trajectory_id}

List Trajectories#

GET /fabric/trajectories/

Evaluate Action (Simulation)#

POST /fabric/trajectories/{trajectory_id}/evaluate

Make Decision (Enforcement)#

POST /fabric/trajectories/{trajectory_id}/decide

Create Policy#

POST /fabric/trajectories/policies

Get Policy#

GET /fabric/trajectories/policies/{policy_id}

Get Evidence#

GET /fabric/trajectories/{trajectory_id}/evidence

CLI Commands#

# List trajectories
cain trajectory list

# Get a trajectory
cain trajectory get <trajectory_id>

# Create a trajectory
cain trajectory create --identity user1 --agent agent1

# Make a decision
cain trajectory decide <trajectory_id> read_data --tool read_tool

# Evaluate (simulate)
cain trajectory evaluate <trajectory_id> read_data

# List violations
cain trajectory violations

# Replay a trajectory
cain trajectory replay <trajectory_id>

# Get evidence
cain trajectory evidence <trajectory_id>

# Create a policy
cain trajectory policy-create --name "customer-data-policy" --rule "never_after:external_transfer:read_sensitive_data"

# Get a policy
cain trajectory policy <policy_id>

Dashboard#

Access the trajectory dashboard at: /trajectory/dashboard

Features:

View all trajectories
Filter by state
Visual timeline
Policy creation
API tester

Limitations#

1. MCP trajectory tracking not implemented (future work)