Loop Engine™

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