chore: initial scaffold — core and dsl packages

Signed-off-by: Todd Palmer <todd@betterdata.co>

Author: betterdataco

.eslintrc.base.js

@@ -0,0 +1,8 @@
+module.exports = {
+  root: true,
+  env: {
+    es2022: true,
+    node: true
+  },
+  extends: []
+};

.github/workflows/boundary-check.yml

@@ -0,0 +1,12 @@
+name: OSS Boundary Check
+
+on:
+  pull_request:
+    paths:
+      - "packages/**"
+
+jobs:
+  placeholder:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Workflow scaffolded. Full implementation in Prompt 9."

.github/workflows/ci.yml

@@ -0,0 +1,13 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "rc/*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  placeholder:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Workflow scaffolded. Full implementation in Prompt 9."

.github/workflows/release.yml

@@ -0,0 +1,11 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  placeholder:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Workflow scaffolded. Full implementation in Prompt 9."

.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+.turbo/
+*.tsbuildinfo
+coverage/
+.env
+.env.local
+sbom.json

CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing to Loop Engine
+
+## Governance
+
+Loop Engine follows a BDFL (Benevolent Dictator for Life) model.
+Better Data, Inc. controls the final roadmap and release decisions.
+Community contributions are welcome and encouraged.
+
+## How to contribute
+
+1. Open an issue before building anything significant
+2. Sign every commit with DCO: `Signed-off-by: Your Name <email>`
+   (required - add `git config commit.verbose true` and use `-s` flag)
+3. PRs must pass all CI checks before review
+4. Breaking changes to core types require RFC (open an issue with [RFC] prefix)
+
+## What belongs in this repo
+
+✅ Domain-neutral primitives (packages/core)
+✅ Loop definitions that work in any runtime (loops/)
+✅ Examples showing cross-domain applicability
+✅ Adapters for persistence and event buses
+
+❌ SCM-specific business logic (belongs in domain packs)
+❌ AI optimization algorithms (proprietary - not accepted)
+❌ Better Data-specific tenant or billing logic (proprietary)
+❌ Any import from packages outside this repository
+
+## Versioning
+
+All packages follow semver strictly.
+Breaking changes to event schemas require 6-month deprecation notice.
+Use changesets for all version bumps: `pnpm changeset`

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Loop Engine Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,77 @@
+# Loop Engine
+
+Loop Engine is an open-source runtime for constrained, observable, and improvable
+operational loops.
+
+It helps teams model enterprise processes as finite-state control systems that can
+be operated by humans, automation, and AI.
+
+Created by [Better Data](https://betterdata.co).
+
+## What it is
+
+The Loop Engine gives AI and automation structure, boundaries, and feedback - not
+improvisation. Every process is a bounded state machine. Every action has an
+attributed actor. Every completed loop emits structured training data.
+
+- **Portable loop definitions** - define any process as a bounded state machine
+- **Deterministic guards** - enforce policy before AI or automation can act
+- **First-class actor model** - human, automation, and AI actions are all attributed
+- **Structured events** - every transition emits training-quality data
+- **Self-learning loops** - closed loops generate improvement signals automatically
+
+## Quick start
+
+```bash
+npm install @loopengine/sdk
+```
+
+```typescript
+import { createLoopEngine } from "@loopengine/sdk";
+
+const engine = createLoopEngine({ store: memoryStore() });
+
+await engine.start({
+  loopId: "scm.procurement",
+  aggregateId: "PO-2026-0012"
+});
+
+await engine.transition({
+  aggregateId: "PO-2026-0012",
+  transitionId: "confirm_po",
+  actor: { type: "human", id: "drew.kim@example.com" },
+  evidence: { approved: true, method: "3-way-match" }
+});
+```
+
+## Packages
+
+| Package | Purpose |
+|---------|---------|
+| @loopengine/core | Domain model types - zero dependencies |
+| @loopengine/dsl | YAML/JSON loop authoring, parsing, validation |
+| @loopengine/runtime | State machine executor |
+| @loopengine/guards | Deterministic policy checks |
+| @loopengine/signals | Event-to-signal detection |
+| @loopengine/events | Canonical event schema |
+| @loopengine/actors | Actor model + AI actor constraints |
+| @loopengine/observability | Loop history, timelines, metrics |
+| @loopengine/sdk | Friendly developer interface (start here) |
+| @loopengine/registry-client | Fetch loop definitions from a registry |
+| @loopengine/ui-devtools | React devtools panel |
+| @loopengine/adapter-memory | In-memory store (testing/dev) |
+| @loopengine/adapter-postgres | PostgreSQL persistence |
+| @loopengine/adapter-kafka | Kafka event bus |
+
+## Examples
+
+See [examples/mini](./examples/mini) for lightweight runnable examples.
+For complete reference implementations, see [loop-examples](https://github.com/loopengine/loop-examples).
+
+## Documentation
+
+[loopengine.dev](https://loopengine.dev)
+
+## License
+
+MIT

ROADMAP.md

@@ -0,0 +1,35 @@
+# Roadmap
+
+## v0.1 - Foundation (current)
+
+- [x] Core domain model (@loopengine/core)
+- [x] DSL - YAML and TypeScript builder (@loopengine/dsl)
+- [x] Runtime - state machine executor (@loopengine/runtime)
+- [x] Guards - deterministic policy checks (@loopengine/guards)
+- [x] Actors - human, automation, AI agent model (@loopengine/actors)
+- [x] Events - canonical structured event schema (@loopengine/events)
+- [x] SDK - developer entry point (@loopengine/sdk)
+- [x] Adapters - memory, Postgres, Kafka, HTTP
+- [x] Canonical loops - SCM, CRM, finance, support
+
+## v0.2 - Observability + Devtools
+
+- [ ] Observability package - metrics, timeline, replay (@loopengine/observability)
+- [ ] UI Devtools - React panel for loop inspection (@loopengine/ui-devtools)
+- [ ] Loop Inspector app
+- [ ] Signal rules - state dwell, threshold breach, guard pattern
+
+## v0.3 - Registry
+
+- [ ] Registry client (@loopengine/registry-client)
+- [ ] Local registry support
+- [ ] loop-registry repo (hosted discovery)
+
+## v1.0 - Stable
+
+- [ ] Stable API across all core packages
+- [ ] 6-month deprecation window enforced on breaking changes
+- [ ] Community governance model documented
+
+This roadmap reflects current thinking. It will change based on contributor
+input and real-world usage. Open an RFC issue to propose additions.

apps/inspector/.gitkeep

@@ -0,0 +1 @@
+