@loop-engine/core

1npm install @loop-engine/core

1export type LoopId = string & { readonly __brand: "LoopId" }
2export type StateId = string & { readonly __brand: "StateId" }
3export type TransitionId = string & { readonly __brand: "TransitionId" }
4export type AggregateId = string & { readonly __brand: "AggregateId" }
5export type ActorId = string & { readonly __brand: "ActorId" }
6export type GuardId = string & { readonly __brand: "GuardId" }
7export type SignalId = string & { readonly __brand: "SignalId" }
8export type OutcomeId = string & { readonly __brand: "OutcomeId" }
9export type CorrelationId = string & { readonly __brand: "CorrelationId" }

1import { aggregateId, transitionId } from "@loop-engine/core"
2 
3const aggregate = aggregateId("EXP-2026-001")
4const transition = transitionId("approve")

1export type ActorType = "human" | "automation" | "ai-agent" | "system"
2export type LoopStatus =
3  | "pending"
4  | "active"
5  | "completed"
6  | "failed"
7  | "cancelled"
8  | "suspended"
9 
10export interface GuardSpec {
11  id: GuardId
12  description: string
13  failureMessage: string
14  severity: "hard" | "soft"
15  evaluatedBy: "runtime" | "module" | "external"
16}
17 
18export interface StateSpec {
19  id: StateId
20  description?: string
21  isTerminal?: boolean
22  isError?: boolean
23}
24 
25export interface TransitionSpec {
26  id: TransitionId
27  from: StateId
28  to: StateId
29  allowedActors: ActorType[]
30  guards?: GuardSpec[]
31  sideEffects?: SideEffectSpec[]
32  description?: string
33}
34 
35export interface LoopDefinition {
36  id: LoopId
37  version: string
38  description: string
39  domain: string
40  states: StateSpec[]
41  initialState: StateId
42  transitions: TransitionSpec[]
43  outcome: OutcomeSpec
44  participants?: string[]
45  spawnableLoops?: LoopId[]
46  metadata?: Record<string, unknown>
47}

1export interface ActorRef {
2  id: ActorId
3  type: ActorType
4  displayName?: string
5  metadata?: Record<string, unknown>
6}
7 
8export interface LoopInstance {
9  loopId: LoopId
10  aggregateId: AggregateId
11  currentState: StateId
12  status: LoopStatus
13  startedAt: string
14  updatedAt: string
15  correlationId?: string
16  completedAt?: string
17  metadata?: Record<string, unknown>
18}
19 
20export interface TransitionRecord {
21  aggregateId: AggregateId
22  loopId: LoopId
23  transitionId: TransitionId
24  signal: SignalId
25  fromState: StateId
26  toState: StateId
27  actor: ActorRef
28  occurredAt: string
29  evidence?: Record<string, unknown>
30}

1export interface OutcomeSpec {
2  id: OutcomeId
3  description: string
4  valueUnit: string
5  measurable: boolean
6  businessMetrics?: BusinessMetric[]
7}
8 
9export interface Signal {
10  id: SignalId
11  type: string
12  subject: string
13  confidence?: number
14  observedAt: string
15  payload: Record<string, unknown>
16  triggeredLoopId?: LoopId
17}