@intent-driven/runtime-local 0.2.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 Standalone Fold-runtime для локального quickstart'а. Принимает ontology.js (сгенерированный `idf full-bootstrap`), поднимает HTTP-сервер с эндпоинтами, которые ожидает `@intent-driven/mcp-server` для подключения к Claude Desktop / Cursor / Zed.
 
-> **Статус:** v0.1 — skeleton. Поддерживает `/api/health`, `/api/typemap`, `/api/agent/:domain/schema` (discovery). Полный agent/exec, approvals lifecycle, /api/state/* — в следующих релизах (см. roadmap fold-15min).
+> **Статус:** v0.3 — stateful Φ через `@intent-driven/engine`. Поддерживает `/api/health`, `/api/typemap`, `/api/agent/:domain/schema` (discovery), `/api/state/current`, `/api/agent/:domain/world` (fold снимок). agent/exec + approvals lifecycle — в следующих релизах (см. roadmap fold-15min).
 
 ## Зачем
 
@@ -12,7 +12,10 @@ Standalone Fold-runtime для локального quickstart'а. Приним
 idf serve --ontology ./ontology.js   # планируется в @intent-driven/cli
 # или программно:
 import { createRuntime } from '@intent-driven/runtime-local';
-const runtime = createRuntime({ ontology: require('./ontology.js') });
+const runtime = createRuntime({
+  ontology: require('./ontology.js'),
+  seed: require('./seed.json'),  // опц. — массив эффектов
+});
 await runtime.start();
 ```
 
@@ -22,7 +25,7 @@ await runtime.start();
 npm install @intent-driven/runtime-local
 ```
 
-Peer-зависимость: `@intent-driven/core@>=0.49.0` (нужен для будущих релизов с validator/fold; в v0.1 не требуется в runtime, но указан как peer для forward-compat).
+Peer-зависимость: `@intent-driven/core@>=0.49.0` (через `@intent-driven/engine`).
 
 ## API
 
@@ -33,33 +36,36 @@ Peer-зависимость: `@intent-driven/core@>=0.49.0` (нужен для
 | Опция | Тип | Default | Описание |
 |---|---|---|---|
 | `ontology` | object | **required** | IDF ontology — `{ entities, intents, roles, projections, ... }`. |
+| `seed` | array | `[]` | Pre-confirmed эффекты для начального состояния Φ. Каждый — `{id, intent_id, alpha, target, context, value?, status: 'confirmed', created_at}`. Primitive `value` (строки/числа) нормализуются в JSON-encoded автоматически. |
 | `port` | number | `3001` | Порт. `0` = random (для тестов). |
 | `host` | string | `'127.0.0.1'` | Bind-адрес. |
 
-Возвращает `{ app, ontology, domain, start(), stop() }`.
+Возвращает `{ app, ontology, domain, engine, persistence, start(), stop() }`. `engine` — instance `@intent-driven/engine`, для прямого использования (e.g., тесты).
 
 ### `runtime.start()` → `Promise<{url, port, host}>`
 
-Поднимает Express-сервер. Возвращает actual URL/port (полезно при `port: 0`).
+Поднимает Express-сервер. Загружает `seed` в persistence перед listen. Возвращает actual URL/port (полезно при `port: 0`).
 
 ### `runtime.stop()` → `Promise<void>`
 
 Закрывает сервер.
 
-## Эндпоинты (v0.1)
+## Эндпоинты
 
 | Метод | Путь | Назначение |
 |---|---|---|
 | `GET` | `/api/health` | Liveness check для `idf doctor` и MCP-server. Возвращает `{status, domain, runtime, version}`. |
 | `GET` | `/api/typemap` | Сводка ontology: entities/intents/roles names. |
-| `GET` | `/api/agent/:domain/schema` | Full ontology snapshot для MCP discovery. 503 если domain не совпадает с зарегистрированным. |
+| `GET` | `/api/agent/:domain/schema` | Full ontology snapshot для MCP discovery. 503 если domain не совпадает. |
+| `GET` | `/api/state/current` | Folded world snapshot — `{domain, world: {products: [...], orders: [...]}}`. |
+| `GET` | `/api/agent/:domain/world` | Тот же world, что и `/api/state/current`. Этот endpoint вызывает `@intent-driven/mcp-server` для resource-чтения. 503 при mismatch domain. |
 
 ## Roadmap (следующие PR)
 
-- v0.2: in-memory Φ-store + `GET /api/state/at` + `GET /api/state/diff`
-- v0.3: `POST /api/agent/:domain/exec/:intentId` — ingest с invariant validation, ApprovalRequest auto-injection через `lifecycleAugmenter`
-- v0.4: `GET /api/approvals/pending` + `POST /api/approvals/:id/approve|reject` + timer-driven expiry
-- v0.5: SSE-стрим `/api/approvals/stream` для `idf approvals --watch`
+- v0.4: `POST /api/agent/:domain/exec/:intentId` — ingest через `engine.submit` с invariant validation, ApprovalRequest auto-injection через `lifecycleAugmenter`
+- v0.5: `GET /api/approvals/pending` + `POST /api/approvals/:id/approve|reject` + timer-driven expiry
+- v0.6: `GET /api/state/at?t=ISO` + `/api/state/diff?from=&to=` — time-travel
+- v0.7: SSE-стрим `/api/approvals/stream` для `idf approvals --watch`
 
 ## Лицензия
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intent-driven/runtime-local",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Standalone Fold-runtime для local quickstart: stateful Φ + agent/exec + approvals + state — то, что делает host idf/server, но как npm-пакет",
   "type": "module",
   "exports": {
@@ -13,7 +13,8 @@
   ],
   "dependencies": {
     "cors": "^2.8.5",
-    "express": "^4.21.2"
+    "express": "^4.21.2",
+    "@intent-driven/engine": "0.4.0"
   },
   "devDependencies": {
     "vitest": "^4.1.0",

package/src/createRuntime.js

@@ -3,6 +3,20 @@ import cors from "cors";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
+import { createEngine, createInMemoryPersistence } from "@intent-driven/engine";
+
+/**
+ * Engine validator JSON-парсит ef.value если оно string (host-convention для
+ * SQLite JSONB columns). Seed-эффекты от user-кода обычно содержат native
+ * JS values — нормализуем primitive strings обратно в JSON-encoded.
+ */
+function normalizeSeedEffect(ef) {
+  if (ef.value === undefined || ef.value === null) return { ...ef };
+  if (typeof ef.value === "string") {
+    return { ...ef, value: JSON.stringify(ef.value) };
+  }
+  return { ...ef };
+}
 
 const PKG_VERSION = (() => {
   try {
@@ -15,7 +29,7 @@ const PKG_VERSION = (() => {
 })();
 
 export function createRuntime(opts = {}) {
-  const { ontology, port = 3001, host = "127.0.0.1" } = opts;
+  const { ontology, seed = [], port = 3001, host = "127.0.0.1" } = opts;
 
   if (!ontology || typeof ontology !== "object") {
     throw new Error("createRuntime: ontology is required");
@@ -23,6 +37,12 @@ export function createRuntime(opts = {}) {
 
   const domain = ontology.name || "default";
 
+  const persistence = createInMemoryPersistence();
+  const engine = createEngine({
+    domain: { INTENTS: ontology.intents || {}, ONTOLOGY: ontology },
+    persistence,
+  });
+
   const app = express();
   app.use(cors());
   app.use(express.json({ limit: "10mb" }));
@@ -61,17 +81,52 @@ export function createRuntime(opts = {}) {
     });
   });
 
+  app.get("/api/state/current", async (_req, res, next) => {
+    try {
+      const world = await engine.foldWorld();
+      res.json({ domain, world });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  app.get("/api/agent/:domain/world", async (req, res, next) => {
+    if (req.params.domain !== domain) {
+      return res.status(503).json({
+        error: "ontology_unavailable",
+        domain: req.params.domain,
+        message: `Ontology for '${req.params.domain}' is not registered. Runtime serves '${domain}'.`,
+      });
+    }
+    try {
+      const world = await engine.foldWorld();
+      res.json({ domain, world });
+    } catch (err) {
+      next(err);
+    }
+  });
+
   let server = null;
 
+  async function loadSeed() {
+    if (!Array.isArray(seed) || seed.length === 0) return;
+    for (const ef of seed) {
+      await persistence.appendEffect(normalizeSeedEffect(ef));
+    }
+  }
+
   return {
     app,
     ontology,
     domain,
+    engine,
+    persistence,
 
     async start() {
       if (server) {
         throw new Error("runtime already started");
       }
+      await loadSeed();
       return await new Promise((resolve, reject) => {
         const s = app.listen(port, host, () => {
           server = s;