Core Concepts

Signals

What signals are

Signals are detected patterns derived from loop events.
A SignalRule evaluates event streams and returns a detection result when matched.

SignalRule anatomy

1interface SignalRule {
2  id: string
3  name: string
4  description: string
5  targetLoopId?: LoopId
6  evaluate: (events: LoopEvent[]) => SignalDetectionResult | null
7}

Built-in signal rules

threshold-breach

• Signal type: THRESHOLD_BREACH
• Detects numeric evidence crossing configured threshold
• Config: field, operator, threshold

state-dwell

• Signal type: STATE_DWELL_EXCEEDED
• Detects prolonged dwell in a target state
• Config: state, maxDwellMinutes

repeated-guard-failure

• Signal type: GUARD_FAILURE_PATTERN
• Detects repeated loop.guard.failed events for one guard ID
• Config: guardId, maxFailures

loop-not-started

• Signal type: LOOP_TRIGGER_DELAYED
• Detects when a signal is received but no loop started in time window
• Config: maxDelayMinutes

Create a signal engine

1import { createSignalEngine } from '@loop-engine/sdk'
2 
3const signals = createSignalEngine()
4signals.subscribe((signal) => {
5  console.log(signal.type, signal.subject, signal.confidence)
6})

Connect signal detection to loop creation

1signals.subscribe(async (signal) => {
2  if (signal.type !== 'THRESHOLD_BREACH') return
3  await engine.start({
4    loopId: 'scm.replenishment',
5    aggregateId: aggregateId(`repl-${Date.now()}`),
6    orgId: 'acme',
7    actor: { type: 'system', id: 'system:signal-router' },
8    metadata: { triggeredBy: signal.id }
9  })
10})