Core Concepts
What is a Loop?
The problem
Enterprise AI systems fail when actions are not bounded by explicit state, policy, and traceability.
Loop Engine provides finite states, deterministic transition checks, and event traces that make decisions auditable.
A loop is not a workflow
| | Workflow | Loop |
|---|---|---|
| Unit of work | Task | Outcome |
| State | Implicit | Explicit and named |
| Actors | Generic user/system | human / automation / ai-agent / webhook / system |
| Failure model | Usually generic step errors | Guard failures and attributed rejections |
| Learning | External or absent | Structured signals and measurable outcomes |
Anatomy of a loop (LoopDefinition)
id: LoopIdversion: stringdescription: stringdomain: stringstates: StateSpec[]initialState: StateIdtransitions: TransitionSpec[]outcome: OutcomeSpecparticipants?: string[]spawnableLoops?: LoopId[]metadata?: Record<string, unknown>
Use optional fields (participants, spawnableLoops, metadata) only when needed by your platform model.
Lifecycle (LoopStatus)
1OPEN -> IN_PROGRESS -> CLOSED2OPEN -> IN_PROGRESS -> ERROR3OPEN -> IN_PROGRESS -> CANCELLEDReal example (abbreviated from loops/scm/procurement.yaml)
1id: scm.procurement2version: 1.0.03domain: scm4description: Purchase order lifecycle from requisition through settlement5states:6 - id: OPEN7 - id: PO_CONFIRMED8 - id: RECEIVED9 - id: INVOICE_MATCHED10 - id: SETTLED11 isTerminal: true12initialState: OPEN13transitions:14 - id: confirm_po15 from: OPEN16 to: PO_CONFIRMED17 allowedActors: [human, automation, ai-agent]18 guards:19 - id: approval_obtained20 severity: hard21 evaluatedBy: external22 description: PO must be approved before confirmation23 failureMessage: PO confirmation requires explicit approval24outcome:25 id: po_settled26 description: Purchase order fully settled27 valueUnit: po_settled28 measurable: true