Getting Started

Architecture

Loop Engine is a governance runtime, not a generic workflow orchestrator or AI automation builder. This page describes how the runtime composes decision loops, deterministic guards, and evidence with external Providers, Channels, and Integrations.

→ Full glossary: Runtime Taxonomy

Governance runtime (center of the model)

Every operational change that Loop Engine owns passes through the same boundary:

A named actor requests a transition.
Guards evaluate policy in the runtime (hard failures block; soft failures may warn).
Evidence is attached to the allowed transition.
An immutable event is emitted for audit and learning.

AI does not “run the business” inside Loop Engine — it operates inside deterministic governance boundaries. Orchestration frameworks may run elsewhere; loops govern the transitions.

1Providers          ← intelligence enters (LLMs, retrieval tools)
2        ↓
3Decision loops + Guards   ← GOVERNANCE: Loop Engine (policy before commit)
4        ↓
5Channels           ← humans participate (Slack, Teams, approvals)
6        ↓
7Integrations       ← systems of record execute (CRM, tickets, APIs)
8        ↓
9Evidence + learning ← audit + operational improvement

| Stage | What enters | What exits | Who participates | | --- | --- | --- | --- | | Providers | Context, signals | Structured AI/human submissions | Models as governed actors | | Loops + Guards | Transition requests | Allow / block / escalate | Runtime policy (deterministic) | | Channels | PENDING_HUMAN_* events | Human actor transitions | Operators in Slack, email, etc. | | Integrations | Approved transitions | CRM rows, webhooks, staged applies | Enterprise systems | | Evidence | Each commit | Audit + learning signals | Compliance, RevOps, SRE |

Evidence flow

Evidence is produced at transition time:

Inputs the actor used (scores, documents, approval notes)
Guard outcomes and soft warnings
Provider metadata (modelId, provider, promptHash for AI actors)

Downstream analytics and learning signals consume events — they do not replace the runtime evidence contract.

Runtime boundaries

| Boundary | Inside Loop Engine | Outside (but connected) | | --- | --- | --- | | Policy | Guards, allowed actors, transition graph | Prompt content alone is not policy | | State | Loop instance state, transition history | ERP/CRM records update via Integrations after approval | | Humans | Attribution + channel routing | Slack/Teams UIs are Channels | | Intelligence | Provider adapters submit decisions | Models do not call integrations directly |

Runtime platform vs Loop Engine Cloud

Loop Engine can run inside your infrastructure, or connect to hosted governance services from Better Data. Full positioning constraints and roadmap language: Runtime Platform Direction.

OSS runtime platform (today)

Local-first — your Node.js process runs createLoopSystem with chosen stores and adapters (not a required multi-service mesh today).
Self-host substrate — operational governance in your stack: loops, guards, evidence, events via @loop-engine/sdk.
Adapters — Providers, Channels, and Integrations you wire and operate.

→ Quick Start · Runtime Platform Direction

Loop Engine Cloud (hosted)

Governance control plane — multi-tenant HTTP API, connector credentials, documented /api/v1 contract.
Adds — managed connector paths (e.g. Slack, Google) and fleet-style operations without replacing the OSS runtime model.
Not claimed — full OSS parity with every Cloud feature; Studio; docker compose kit; multi-service runtime today.

→ Loop Engine Cloud HTTP API

Better Data company and application docs: docs.betterdata.co — not loopengine.io.

Connection types (taxonomy summary)

| Type | Role in architecture | Examples | | --- | --- | --- | | Provider | Intelligence into the loop | Claude, GPT-4o, Gemini, Grok | | Channel | Human approval / escalation surface | Slack, Teams, OpenClaw routing | | Integration | Systems and persistence after governance | Postgres, Kafka, PagerDuty, Commerce Gateway |

See Runtime Taxonomy for definitions and disambiguation (e.g. DCM “channels” vs human Channels).

Runtime primitives (implementation layer)

These packages implement the governance runtime. They are not the product category names — they are how the engine executes loops.

Loops

Loops are governed decision cycles: states, transitions, signals, and terminal outcomes. Transitions are triggered by signals and authorized by actors subject to guards.

1type LoopDefinition = {
2  loopId: string;
3  states: Array<{ stateId: string; terminal?: boolean }>;
4  initialState: string;
5  transitions: Array<{ transitionId: string; from: string; to: string; signal: string }>;
6};

Signals

Signals name the intent to move between states. They carry actor context into guard evaluation.

Actors

1type ActorType = "human" | "automation" | "ai-agent";

→ Actor Model

Guards

1type GuardSpec = {
2  guardId: string;
3  severity: "hard" | "soft";
4  evaluatedBy: "runtime" | "module" | "external";
5};

Hard guard failure emits loop.guard.failed and does not advance state.

→ Guards and Policy

Events

1type LoopTransitionExecutedEvent = {
2  type: "loop.transition.executed";
3  loopId: string;
4  aggregateId: string;
5  transitionId: string;
6  fromState: string;
7  toState: string;
8  actor: { type: ActorType; id: string };
9  evidence?: Record<string, unknown>;
10};

Learning signals

When a loop completes, learning signals compare predicted vs actual outcomes for improvement loops.

→ Learning Signals

End-to-end example (Provider → guards → Channel → Integration)

1"cmt">// @no-typecheck
2import { createLoopSystem } from "@loop-engine/sdk";
3import { createAnthropicActorAdapter } from "@loop-engine/adapter-anthropic";
4 
5const { engine } = await createLoopSystem({ loops: [/* procurement loop */] });
6const ai = createAnthropicActorAdapter({
7  apiKey: process.env.ANTHROPIC_API_KEY!,
8  model: "claude-opus-4-6"
9});
10 
11"cmt">// Integration may have created the aggregate; automation opens the loop.
12await engine.start({
13  loopId: "procurement" as never,
14  aggregateId: "PO-2001" as never,
15  actor: { type: "automation", id: "system:intake" }
16});
17 
18"cmt">// Provider: AI recommends a transition (does not bypass guards).
19const { actor, decision } = await ai.createSubmission({
20  loopId: "procurement",
21  loopName: "SCM Procurement",
22  currentState: "pending_analysis",
23  availableSignals: [{ signalId: "submit_recommendation", name: "Submit Recommendation" }],
24  instruction: "Recommend order action",
25  evidence: { forecast: 0.83 }
26});
27 
28await engine.transition({
29  aggregateId: "PO-2001" as never,
30  transitionId: "submit_recommendation" as never,
31  actor,
32  evidence: decision
33});
34 
35"cmt">// Guards run in runtime — e.g. confidence threshold.
36"cmt">// Channel: human approval transition (Slack/OpenClaw/PagerDuty routing).
37"cmt">// Integration: ERP/Commerce Gateway executes only after approved transition.
38"cmt">// Terminal state emits loop.completed + learning signal.

What Loop Engine is not

Not a replacement for Temporal, n8n, or BPM suites — use Loop Engine vs Workflow Engines.
Not an AI automation builder that skips policy.
Not a Slack bot product — Slack is a Channel when used for human approval.

Next steps