Core Concepts

Observability

What Loop Engine tracks

Runtime state comes from:

• LoopInstance records (currentState, status, timestamps)
• TransitionRecord[] history (who did what, when, and with what evidence)

The observability package computes aggregate metrics and timelines from that data.

LoopMetrics

computeMetrics(instances, history, period) returns:

• loopId
• period
• totalInstances
• openInstances
• closedInstances
• errorInstances
• avgDurationMs
• medianDurationMs
• p95DurationMs
• completionRate
• guardFailureRate
• aiActorRate
• humanActorRate
• avgTransitionCount

1import { computeMetrics } from '@loop-engine/observability'

Timelines and state residency

Use buildTimeline(instance, history) for a normalized timeline view.

Use getStateResidency(timeline) to see dwell per state:

1import { buildTimeline, getStateResidency } from '@loop-engine/observability'
2 
3const timeline = buildTimeline(instance, history)
4const residency = getStateResidency(timeline)

State residency highlights bottlenecks (for example loops spending excessive time in OPEN or INVOICE_MATCHED).

Replay and validation

replayLoop(definition, history) validates transition history against a definition:

1import { replayLoop } from '@loop-engine/observability'
2 
3const replay = replayLoop(definition, history)
4if (!replay.valid) {
5  console.error(replay.errors)
6}

Use replay for:

• audits
• debugging invalid transitions
• migration validation after definition updates

Devtools

@loop-engine/ui-devtools exports components for local diagnostics:

• DevtoolsPanel
• LoopTimeline
• EventStream
• StateDiagram
• MetricsCard