Core Concepts

IntegrationAdapter Archetype

What is an IntegrationAdapter?

An IntegrationAdapter is a package that implements one of Loop Engine's pluggable interfaces and slots into LoopEngineOptions (or the matching registry-client option). Every adapter preserves the same governance model — guards enforced, actors attributed, audit trail intact — and is swappable without changing loop definitions or business logic.

At rc.0 there are four canonical archetypes. All four share the same shape:

1. An interface contract exported from a runtime package.
2. An options slot on LoopEngineOptions (or createLoopSystem options) that accepts an implementation of that interface.
3. One or more shipped adapters that fulfill the interface.
4. A "build your own" path if the shipped adapters don't cover your backend.

1interface LoopEngineOptions {
2  registry: LoopRegistry   "cmt">// Registry archetype
3  store: LoopStore         "cmt">// Store archetype
4  eventBus?: EventBus      "cmt">// EventBus archetype
5  guardEvaluator?: GuardEvaluator
6  clock?: () => string
7}

The AI archetype sits slightly outside this shape — AI adapters are invoked from transition execution paths rather than slotted into LoopEngineOptions directly — but follows the same "interface + shipped implementations + build-your-own" pattern.

The four archetypes

Store adapter

| | | |---|---| | Interface | LoopStore from @loop-engine/runtime | | Slot | options.store | | Shipped | memoryStore() from @loop-engine/adapter-memory; PlanetScale store from betterdata-loops (proprietary) | | Docs | @loop-engine/adapter-memory · In-Memory integration · Postgres integration |

Store adapters persist loop instances and transition history. Swap backends without changing loop definitions.

Registry adapter

| | | |---|---| | Interface | LoopRegistry from @loop-engine/registry-client | | Slot | options.registry | | Shipped | localRegistry, httpRegistry, betterDataRegistry (from @loop-engine/registry-client and its /betterdata subpath) | | Docs | @loop-engine/registry-client |

Registry adapters load LoopDefinition objects. Use localRegistry for in-process registration, httpRegistry for remote JSON catalogs, or betterDataRegistry for the Better Data catalog API.