Core Concepts
Actor Model
Why actors matter
Every transition is attributed to an actor in the transition record and emitted events.
Nothing executes anonymously.
Actor types
human
Use when a person executes a transition.
1const actor = { type: 'human', id: actorId('drew@acme.com'), sessionId: 'sess_abc' }automation
Use for jobs, integrations, and rule engines.
1const actor = { type: 'automation', id: actorId('system:po-router'), serviceId: 'po-service' }ai-agent
Use for model-driven recommendations or execution.
1const actor = {2 type: 'ai-agent',3 id: actorId('agent:forecaster'),4 agentId: 'claude-3-5-sonnet',5 gatewaySessionId: 'gw_123'6}webhook
Use for externally triggered actions.
1const actor = { type: 'webhook', id: actorId('webhook:shopify'), source: 'shopify' }system
Use for internal runtime/platform initiated actions.
1const actor = { type: 'system', id: actorId('system:loop-engine') }Actor evidence
Use buildActorEvidence(actor, baseEvidence) to normalize actor-attributed evidence.
For all actors, the helper adds:
actor_typeactor_id
For ai-agent, it also adds:
ai_agent_id- optional
ai_confidenceandai_reasoning(when present in base evidence)
Authorization checks
canActorExecuteTransition(actor, transition, constraints?) returns:
1{ authorized: boolean; requiresApproval: boolean; reason?: string }1import { canActorExecuteTransition } from '@loop-engine/actors'2 3const auth = canActorExecuteTransition(actor, transition)4if (!auth.authorized) {5 console.log(auth.reason)6}