Developer documentation

CAIN Trajectory

Last reviewed 31 August 2026

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)