@intent-driven/runtime-local 0.2.0 → 0.4.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,52 @@ 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. |
+| `POST` | `/api/agent/:domain/exec/:intentId` | Ingest intent через `engine.submit`. Generic builder для add/replace/remove. Возвращает `200 {status:'confirmed', effect}` или `409 {status:'rejected', error:'invariant_violation', reason, cascaded}`. `400` для read-intents, `404` для unknown intent, `503` для wrong domain. |
+
+### POST /api/agent/:domain/exec/:intentId
+
+Тело запроса: `{ params: { ... } }`.
+
+`buildEffect()` строит effect по generic-семантике (идентично host'овскому `genericBuildEffects`):
+
+- `alpha=add` → `context = {...params, id: params.id || uuid}`, `value = null`
+- `alpha=replace` target=`Entity.field` → `context = {id: params.id}`, `value = JSON.stringify(params[field])`
+- `alpha=replace` target=`Entity` → `context = {...params}`, `value = null`
+- `alpha=remove` → `context = {id: params.id || params['<entity>Id']}`, `value = null`
+- `alpha=read` → 400 (читай через GET `/api/state/current`)
+
+Лежит на `engine.submit`, поэтому invariants всех 6 kinds автоматически проверяются (role-capability / referential / transition / cardinality / aggregate / expression).
+
+> **A1.3 (следующий PR):** intents с `lifecycle.requiresApproval` сейчас confirm'ятся напрямую. После добавления `lifecycleAugmenter` они будут создавать `ApprovalRequest` вместо ingest'а оригинального effect'а.
 
 ## 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.5: `GET /api/approvals/pending` + `POST /api/approvals/:id/approve|reject` + ApprovalRequest auto-injection (lifecycleAugmenter)
+- 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.4.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/buildEffect.js

@@ -0,0 +1,82 @@
+import { randomUUID } from "node:crypto";
+
+/**
+ * Generic effect-builder для intents без custom builder'а — закрывает
+ * 80%+ кейсов после `idf full-bootstrap`. Идентичен host'овскому
+ * `genericBuildEffects` (server/schema/effectBuildersRegistry.cjs):
+ *
+ *   alpha=add     → ctx={...params, id: params.id || uuid}
+ *   alpha=replace target='Entity.field' → ctx={id}, value=params[field] || params.value
+ *   alpha=replace target='Entity'       → ctx={...params}, value=null
+ *   alpha=remove  → ctx={id: params.id || params['<entity>Id']}
+ *
+ * Возвращает unsubmitted effect (без status/created_at — engine.submit
+ * проставит их сам).
+ */
+export function buildEffect({ intentId, intent, params = {}, viewerId = null }) {
+  if (!intent) {
+    throw new Error(`buildEffect: intent '${intentId}' not provided`);
+  }
+
+  const alpha = intent.alpha;
+  if (alpha === "read") {
+    throw new Error(`buildEffect: read intent '${intentId}' is not executable`);
+  }
+
+  const target = intent.target;
+  if (!target) {
+    throw new Error(`buildEffect: intent '${intentId}' has no target`);
+  }
+
+  const id = randomUUID();
+  const baseEffect = {
+    id,
+    intent_id: intentId,
+    alpha,
+    target,
+    scope: intent.scope || "account",
+  };
+  if (viewerId) baseEffect.user_id = viewerId;
+
+  switch (alpha) {
+    case "add": {
+      return {
+        ...baseEffect,
+        context: { ...params, id: params.id || id },
+        value: null,
+      };
+    }
+    case "replace": {
+      const segments = target.split(".");
+      if (segments.length > 1) {
+        const field = segments[segments.length - 1];
+        const raw = params[field] !== undefined ? params[field] : params.value;
+        // Engine validator JSON-парсит string values (host-convention для
+        // SQLite JSONB columns). Любое native JS value JSON-encode'ится.
+        const value = raw === undefined || raw === null ? null : JSON.stringify(raw);
+        return {
+          ...baseEffect,
+          context: { id: params.id },
+          value,
+        };
+      }
+      return {
+        ...baseEffect,
+        context: { ...params },
+        value: null,
+      };
+    }
+    case "remove": {
+      const entityName = target.split(".")[0];
+      const idKey = `${entityName.charAt(0).toLowerCase()}${entityName.slice(1)}Id`;
+      const entityId = params.id || params[idKey];
+      return {
+        ...baseEffect,
+        context: { id: entityId },
+        value: null,
+      };
+    }
+    default:
+      throw new Error(`buildEffect: unsupported alpha '${alpha}'`);
+  }
+}

package/src/createRuntime.js

@@ -3,6 +3,21 @@ 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";
+import { buildEffect } from "./buildEffect.js";
+
+/**
+ * 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 +30,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 +38,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 +82,95 @@ 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);
+    }
+  });
+
+  app.post("/api/agent/:domain/exec/:intentId", 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}'.`,
+      });
+    }
+    const intentId = req.params.intentId;
+    const intent = (ontology.intents || {})[intentId];
+    if (!intent) {
+      return res.status(404).json({
+        error: "intent_not_found",
+        intentId,
+        domain,
+      });
+    }
+    if (intent.alpha === "read") {
+      return res.status(400).json({
+        error: "read_intent_not_executable",
+        intentId,
+        message: `Read-intents must be executed via GET /api/state/current or /api/agent/${domain}/world.`,
+      });
+    }
+    try {
+      const params = (req.body && typeof req.body === "object" ? req.body.params : null) || {};
+      const effect = buildEffect({ intentId, intent, params });
+      const result = await engine.submit(effect);
+      if (result.status === "confirmed") {
+        return res.json({ status: "confirmed", effect });
+      }
+      return res.status(409).json({
+        status: "rejected",
+        error: "invariant_violation",
+        reason: result.reason,
+        cascaded: result.cascaded || [],
+        effect,
+      });
+    } 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;