@intent-driven/runtime-local 0.4.0 → 0.5.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.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).
+> **Статус:** v0.5 — full approve_pending cycle. Поддерживает `/api/health`, `/api/typemap`, `/api/agent/:domain/schema`, `/api/state/current`, `/api/agent/:domain/world`, `POST /api/agent/:domain/exec/:intentId` (с auto-injection ApprovalRequest для lifecycle.requiresApproval), `/api/approvals/pending`, `/api/approvals/:id/approve|reject`. Time-travel state/at, SSE-стрим, JWT auth — в следующих релизах.
 
 ## Зачем
 
@@ -59,7 +59,10 @@ Peer-зависимость: `@intent-driven/core@>=0.49.0` (через `@intent
 | `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` | Ingest intent через `engine.submit`. Generic builder для add/replace/remove. Возвращает `200 {status:'confirmed', effect}` для intent'ов без lifecycle, `202 {status:'pending_approval', approvalRequestId, ...}` для intent'ов с `lifecycle.requiresApproval`, или `409` при invariant violation. `400` для read-intents, `404` для unknown intent, `503` для wrong domain. |
+| `GET` | `/api/approvals/pending?domain=NAME&as=ROLE` | Pending ApprovalRequest'ы видимые caller'у (фильтр по `fromRole`). Lazy-expiry: requests с `now > expiresAt` автоматически переводятся в `expired` до возврата. |
+| `POST` | `/api/approvals/:id/approve` (body `{reason?}`) | Approver одобряет; `effectsPlanned` ingest'ятся через `engine.submit`. AR получает `status='approved'` + `approvedBy` + `approvedAt`. 403 если caller'а роль не в `fromRole`. 409 если уже terminal status / expired. |
+| `POST` | `/api/approvals/:id/reject` (body `{reason?}`) | Аналогично approve, но без ingest'а. `status='rejected'`. |
 
 ### POST /api/agent/:domain/exec/:intentId
 
@@ -75,13 +78,24 @@ Peer-зависимость: `@intent-driven/core@>=0.49.0` (через `@intent
 
 Лежит на `engine.submit`, поэтому invariants всех 6 kinds автоматически проверяются (role-capability / referential / transition / cardinality / aggregate / expression).
 
-> **A1.3 (следующий PR):** intents с `lifecycle.requiresApproval` сейчас confirm'ятся напрямую. После добавления `lifecycleAugmenter` они будут создавать `ApprovalRequest` вместо ingest'а оригинального effect'а.
+> **Approval lifecycle:** intents с `lifecycle.requiresApproval = { from: ['admin'], timeoutMs: 60_000 }` автоматически работают через ApprovalRequest. `lifecycleAugmenter` добавляет `ApprovalRequest` entity и augment'ит approver/proposer visibleFields на старте. POST exec возвращает 202 + `approvalRequestId`; реальный ingest происходит в `/approvals/:id/approve`. RBAC: `?as=ROLE` query (без auth в v0.5; JWT — будущая итерация).
+
+## Caller role
+
+В v0.5 caller's role резолвится через `?as=ROLE` query parameter. Без этого — `'agent'` по умолчанию. JWT/Bearer-token auth — в будущих релизах.
+
+```bash
+# Approver одобряет от имени admin'а
+curl -X POST http://localhost:3001/api/approvals/ar_abc.../approve?as=admin \
+  -d '{"reason":"validated by IT"}'
+```
 
 ## Roadmap (следующие PR)
 
-- 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`
+- v0.8: timer-driven approval expiry (вместо lazy-expiry в /pending)
+- v0.9: JWT auth + per-request viewer.scope
 
 ## Лицензия
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intent-driven/runtime-local",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Standalone Fold-runtime для local quickstart: stateful Φ + agent/exec + approvals + state — то, что делает host idf/server, но как npm-пакет",
   "type": "module",
   "exports": {

package/src/approvalAction.js

@@ -0,0 +1,49 @@
+/**
+ * Pure validation для approval-action — port host'овской
+ * `server/schema/approvalAction.cjs` в ESM.
+ *
+ * `validateApprovalAction` — null если action разрешён, иначе
+ * `{ httpStatus, error, ...details }` с failure-payload'ом.
+ */
+
+export function parseFromRoles(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value;
+  return String(value).split(",").map(s => s.trim()).filter(Boolean);
+}
+
+export function validateApprovalAction(action, ar, callerRole, now = Date.now()) {
+  if (action !== "approve" && action !== "reject") {
+    return { httpStatus: 400, error: "invalid_action", action };
+  }
+  if (!ar) {
+    return { httpStatus: 404, error: "approval_not_found" };
+  }
+  const allowedRoles = parseFromRoles(ar.fromRole);
+  if (!allowedRoles.includes(callerRole)) {
+    return {
+      httpStatus: 403,
+      error: "role_not_allowed",
+      callerRole,
+      allowedRoles,
+      message: `Approval requires role(s) [${allowedRoles.join(", ")}]; you are '${callerRole}'`,
+    };
+  }
+  if (ar.status !== "pending") {
+    return {
+      httpStatus: 409,
+      error: "already_resolved",
+      currentStatus: ar.status,
+      message: `ApprovalRequest already in terminal status '${ar.status}'`,
+    };
+  }
+  if (ar.expiresAt && Number(ar.expiresAt) < now) {
+    return {
+      httpStatus: 409,
+      error: "expired",
+      expiresAt: ar.expiresAt,
+      message: "ApprovalRequest expired before action",
+    };
+  }
+  return null;
+}

package/src/createRuntime.js

@@ -1,10 +1,13 @@
 import express from "express";
 import cors from "cors";
+import { randomUUID } from "node:crypto";
 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";
+import { augmentOntologyForLifecycle, hasApprovalLifecycle } from "./lifecycleAugmenter.js";
+import { validateApprovalAction, parseFromRoles } from "./approvalAction.js";
 
 /**
  * Engine validator JSON-парсит ef.value если оно string (host-convention для
@@ -29,14 +32,36 @@ const PKG_VERSION = (() => {
   }
 })();
 
+const DEFAULT_APPROVAL_TIMEOUT_MS = 5 * 60 * 1000;
+
+function resolveCallerRole(req, ontology) {
+  const candidates = [];
+  if (typeof req.query?.as === "string") candidates.push(req.query.as);
+  candidates.push("agent");
+  const roles = ontology?.roles || {};
+  for (const c of candidates) {
+    if (c && roles[c]) return c;
+  }
+  return null;
+}
+
+function findApprovalRequest(world, id) {
+  const all = world?.approvalRequests || [];
+  return all.find(r => r.id === id) || null;
+}
+
 export function createRuntime(opts = {}) {
-  const { ontology, seed = [], port = 3001, host = "127.0.0.1" } = opts;
+  const { ontology: rawOntology, seed = [], port = 3001, host = "127.0.0.1" } = opts;
 
-  if (!ontology || typeof ontology !== "object") {
+  if (!rawOntology || typeof rawOntology !== "object") {
     throw new Error("createRuntime: ontology is required");
   }
 
+  // augmenter добавляет ApprovalRequest entity + правит approver/proposer
+  // visibleFields когда есть intent с lifecycle.requiresApproval.
+  const ontology = augmentOntologyForLifecycle(rawOntology);
   const domain = ontology.name || "default";
+  const hasApproval = hasApprovalLifecycle(ontology.intents || {});
 
   const persistence = createInMemoryPersistence();
   const engine = createEngine({
@@ -134,6 +159,71 @@ export function createRuntime(opts = {}) {
     try {
       const params = (req.body && typeof req.body === "object" ? req.body.params : null) || {};
       const effect = buildEffect({ intentId, intent, params });
+
+      // Gate 2: human-approval lifecycle. Если intent.lifecycle.requiresApproval
+      // активен — НЕ ingest'им effect напрямую. Создаём ApprovalRequest в Φ;
+      // фактический ingest происходит в /api/approvals/:id/approve.
+      const lifecycle = intent.lifecycle?.requiresApproval;
+      if (lifecycle) {
+        const approvalRequestId = `ar_${randomUUID()}`;
+        const expiresAt = Date.now() + (Number(lifecycle.timeoutMs) || DEFAULT_APPROVAL_TIMEOUT_MS);
+        const fromRoles = Array.isArray(lifecycle.from)
+          ? lifecycle.from
+          : (typeof lifecycle.from === "string" ? [lifecycle.from] : []);
+        const callerRole = resolveCallerRole(req, ontology) || "agent";
+
+        const arEffect = {
+          id: randomUUID(),
+          intent_id: "_request_approval",
+          alpha: "add",
+          target: "approvalRequests",
+          value: null,
+          scope: "global",
+          parent_id: null,
+          context: {
+            id: approvalRequestId,
+            intentId,
+            domain,
+            proposedBy: callerRole,
+            proposedByRole: callerRole,
+            fromRole: fromRoles.join(","),
+            params: JSON.stringify(params),
+            effectsPlanned: JSON.stringify([effect]),
+            status: "pending",
+            expiresAt,
+            createdAt: Date.now(),
+            approvedBy: null,
+            approvedAt: null,
+            reason: null,
+          },
+          created_at: Date.now(),
+        };
+        const arResult = await engine.submit(arEffect);
+        if (arResult.status !== "confirmed") {
+          return res.status(500).json({
+            error: "approval_creation_failed",
+            reason: arResult.reason,
+            message: "Не удалось зарегистрировать ApprovalRequest в Φ",
+          });
+        }
+
+        return res.status(202).json({
+          status: "pending_approval",
+          approvalRequestId,
+          intentId,
+          domain,
+          fromRole: fromRoles,
+          expiresAt,
+          timeoutMs: lifecycle.timeoutMs,
+          effectsPlanned: [{
+            alpha: effect.alpha,
+            target: effect.target,
+            context: effect.context,
+            value: effect.value,
+          }],
+        });
+      }
+
       const result = await engine.submit(effect);
       if (result.status === "confirmed") {
         return res.json({ status: "confirmed", effect });
@@ -150,6 +240,161 @@ export function createRuntime(opts = {}) {
     }
   });
 
+  // ─── /api/approvals/* — approve / reject / pending list ──────────────
+  if (hasApproval) {
+    async function emitExpire(approvalRequestId) {
+      const expireEffect = {
+        id: randomUUID(),
+        intent_id: "_expire_approval",
+        alpha: "replace",
+        target: "approvalRequests.status",
+        value: JSON.stringify("expired"),
+        scope: "global",
+        parent_id: null,
+        context: { id: approvalRequestId },
+        created_at: Date.now(),
+      };
+      await engine.submit(expireEffect);
+    }
+
+    app.get("/api/approvals/pending", async (req, res, next) => {
+      try {
+        const reqDomain = req.query?.domain;
+        if (!reqDomain) {
+          return res.status(400).json({
+            error: "domain_required",
+            message: "Provide ?domain=NAME",
+          });
+        }
+        if (reqDomain !== domain) {
+          return res.status(404).json({ error: "domain_unknown", domain: reqDomain });
+        }
+        const callerRole = resolveCallerRole(req, ontology);
+        if (!callerRole) {
+          return res.status(400).json({ error: "role_unknown", domain });
+        }
+
+        let world = await engine.foldWorld();
+        const allRequests = (world.approvalRequests || []).filter(r => r.domain === domain);
+
+        const now = Date.now();
+        let didExpire = false;
+        for (const r of allRequests) {
+          if (r.status === "pending" && r.expiresAt && Number(r.expiresAt) < now) {
+            await emitExpire(r.id);
+            didExpire = true;
+          }
+        }
+        if (didExpire) world = await engine.foldWorld();
+
+        const filtered = (world.approvalRequests || [])
+          .filter(r => r.domain === domain)
+          .filter(r => r.status === "pending")
+          .filter(r => parseFromRoles(r.fromRole).includes(callerRole));
+
+        res.json({ domain, callerRole, now, requests: filtered });
+      } catch (err) {
+        next(err);
+      }
+    });
+
+    async function handleAction(req, res, action) {
+      const id = req.params.id;
+      const reason = (req.body?.reason || "").toString().slice(0, 500) || null;
+      const world = await engine.foldWorld();
+      const ar = findApprovalRequest(world, id);
+      if (!ar) {
+        return res.status(404).json({ error: "approval_not_found", id });
+      }
+      if (ar.domain !== domain) {
+        return res.status(404).json({ error: "domain_unknown", domain: ar.domain });
+      }
+      const callerRole = resolveCallerRole(req, ontology);
+      if (!callerRole) {
+        return res.status(400).json({ error: "role_unknown", domain });
+      }
+      const error = validateApprovalAction(action, ar, callerRole);
+      if (error) {
+        if (error.error === "expired") {
+          await emitExpire(id);
+        }
+        const { httpStatus, ...body } = error;
+        return res.status(httpStatus).json({ ...body, ...(error.error === "approval_not_found" ? { id } : {}) });
+      }
+
+      const now = Date.now();
+      const newStatus = action === "approve" ? "approved" : "rejected";
+      const callerId = `runtime-local:${callerRole}`;
+
+      const arUpdate = {
+        id: randomUUID(),
+        intent_id: action === "approve" ? "approve_request" : "reject_request",
+        alpha: "replace",
+        target: "approvalRequests",
+        value: null,
+        scope: "global",
+        parent_id: null,
+        context: {
+          id,
+          status: newStatus,
+          approvedBy: callerId,
+          approvedAt: now,
+          reason,
+        },
+        created_at: now,
+      };
+      const updateResult = await engine.submit(arUpdate);
+      if (updateResult.status !== "confirmed") {
+        return res.status(500).json({
+          error: "approval_update_failed",
+          reason: updateResult.reason,
+        });
+      }
+
+      let appliedEffects = [];
+      if (action === "approve") {
+        let planned;
+        try {
+          planned = JSON.parse(ar.effectsPlanned || "[]");
+        } catch {
+          return res.status(500).json({
+            error: "effects_corrupt",
+            message: "ApprovalRequest.effectsPlanned не парсится",
+          });
+        }
+        if (!Array.isArray(planned)) planned = [];
+        for (const e of planned) {
+          const fresh = {
+            ...e,
+            id: randomUUID(),
+            parent_id: arUpdate.id,
+            created_at: Date.now(),
+          };
+          const r = await engine.submit(fresh);
+          appliedEffects.push({
+            id: fresh.id,
+            intent_id: fresh.intent_id,
+            alpha: fresh.alpha,
+            target: fresh.target,
+            status: r.status,
+          });
+        }
+      }
+
+      return res.json({
+        status: newStatus,
+        approvalRequestId: id,
+        approvedBy: callerId,
+        approvedAt: now,
+        reason,
+        appliedEffects,
+      });
+    }
+
+    app.post("/api/approvals/:id/approve", (req, res) => handleAction(req, res, "approve"));
+    app.post("/api/approvals/:id/reject", (req, res) => handleAction(req, res, "reject"));
+  }
+
   let server = null;
 
   async function loadSeed() {

package/src/lifecycleAugmenter.js

@@ -0,0 +1,144 @@
+/**
+ * lifecycleAugmenter — автоматическое обогащение ontology mechanism'ом
+ * approval-lifecycle. Port host'овской `server/schema/lifecycleAugmenter.cjs`
+ * в ESM. Принцип «augment, don't override»: авторские declarations имеют
+ * приоритет.
+ *
+ * Когда хоть один intent объявляет `lifecycle.requiresApproval`, augmenter:
+ *   - добавляет ApprovalRequest entity (если автор не объявил свой)
+ *   - augmenting visibleFields на approver/proposer ролях
+ *   - canExecute approve_request/reject_request на approver-роли
+ *
+ * Pure: возвращает новый ontology-объект.
+ */
+
+const APPROVAL_REQUEST_ENTITY = {
+  ownerField: null,
+  fields: {
+    id:               { type: "text" },
+    intentId:         { type: "text", label: "Intent" },
+    domain:           { type: "text", label: "Domain" },
+    proposedBy:       { type: "text", label: "Proposed by", fieldRole: "name" },
+    proposedByRole:   { type: "text", label: "Proposed by role" },
+    fromRole:         { type: "text", label: "Approver role" },
+    params:           { type: "textarea", label: "Params (JSON)" },
+    effectsPlanned:   { type: "textarea", label: "Effects planned (JSON)" },
+    status: {
+      type: "select",
+      label: "Status",
+      options: ["pending", "approved", "rejected", "expired"],
+      fieldRole: "status",
+    },
+    expiresAt:        { type: "datetime", label: "Expires", fieldRole: "datetime" },
+    createdAt:        { type: "datetime", fieldRole: "datetime" },
+    approvedBy:       { type: "text", label: "Approved by" },
+    approvedAt:       { type: "datetime", label: "Approved at", fieldRole: "datetime" },
+    reason:           { type: "textarea", label: "Reason" },
+  },
+};
+
+const APPROVER_VISIBLE_FIELDS = Object.keys(APPROVAL_REQUEST_ENTITY.fields);
+const PROPOSER_VISIBLE_FIELDS = ["id", "intentId", "status", "expiresAt", "createdAt"];
+
+export function augmentOntologyForLifecycle(ontology) {
+  if (!ontology) return ontology;
+  const intents = ontology.intents || {};
+
+  const approvalIntents = collectApprovalIntents(intents);
+  if (approvalIntents.length === 0) return ontology;
+
+  const approverRoles = collectApproverRoles(approvalIntents);
+  const proposerRoles = mapProposerRoles(ontology, approvalIntents);
+
+  return {
+    ...ontology,
+    entities: ensureApprovalEntity(ontology.entities),
+    roles: augmentRoles(ontology.roles || {}, approverRoles, proposerRoles),
+  };
+}
+
+export function hasApprovalLifecycle(intents) {
+  return collectApprovalIntents(intents).length > 0;
+}
+
+function collectApprovalIntents(intents) {
+  if (!intents || typeof intents !== "object") return [];
+  return Object.entries(intents)
+    .filter(([_, intent]) => intent?.lifecycle?.requiresApproval)
+    .map(([id, intent]) => [id, intent.lifecycle.requiresApproval]);
+}
+
+function collectApproverRoles(approvalIntents) {
+  const set = new Set();
+  for (const [_, lifecycle] of approvalIntents) {
+    const from = lifecycle.from;
+    if (!from) continue;
+    const roles = Array.isArray(from) ? from : [from];
+    for (const r of roles) if (typeof r === "string") set.add(r);
+  }
+  return set;
+}
+
+function mapProposerRoles(ontology, approvalIntents) {
+  const intentIds = new Set(approvalIntents.map(([id]) => id));
+  const proposers = new Set();
+  for (const [roleName, role] of Object.entries(ontology.roles || {})) {
+    const ce = role.canExecute || [];
+    if (ce.some(id => intentIds.has(id))) proposers.add(roleName);
+  }
+  return proposers;
+}
+
+function ensureApprovalEntity(entities) {
+  if (entities?.ApprovalRequest) return entities;
+  return { ...(entities || {}), ApprovalRequest: APPROVAL_REQUEST_ENTITY };
+}
+
+function augmentRoles(roles, approverRoles, proposerRoles) {
+  const out = {};
+  for (const [name, role] of Object.entries(roles)) {
+    let augmented = role;
+    if (approverRoles.has(name)) {
+      augmented = augmentApproverRole(augmented);
+    } else if (proposerRoles.has(name)) {
+      augmented = augmentProposerRole(augmented);
+    }
+    out[name] = augmented;
+  }
+  return out;
+}
+
+function augmentApproverRole(role) {
+  return {
+    ...role,
+    visibleFields: ensureVisibleFields(role.visibleFields, APPROVER_VISIBLE_FIELDS),
+    canExecute: ensureCanExecuteHas(role.canExecute, ["approve_request", "reject_request"]),
+  };
+}
+
+function augmentProposerRole(role) {
+  return {
+    ...role,
+    visibleFields: ensureVisibleFields(role.visibleFields, PROPOSER_VISIBLE_FIELDS),
+  };
+}
+
+function ensureVisibleFields(visibleFields, defaultFields) {
+  const vf = visibleFields || {};
+  if (vf.ApprovalRequest) return vf;
+  return { ...vf, ApprovalRequest: defaultFields };
+}
+
+function ensureCanExecuteHas(canExecute, mustInclude) {
+  const ce = Array.isArray(canExecute) ? [...canExecute] : [];
+  for (const id of mustInclude) {
+    if (!ce.includes(id)) ce.push(id);
+  }
+  return ce;
+}
+
+export {
+  APPROVAL_REQUEST_ENTITY,
+  APPROVER_VISIBLE_FIELDS,
+  PROPOSER_VISIBLE_FIELDS,
+};