Package Exports

@intent-driven/runtime-local

Readme

@intent-driven/runtime-local

Standalone Fold-runtime для локального quickstart'а. Принимает ontology.js (сгенерированный idf full-bootstrap), поднимает HTTP-сервер с эндпоинтами, которые ожидает @intent-driven/mcp-server для подключения к Claude Desktop / Cursor / Zed.

Статус: v0.6 — transition history-tracking (full pair validation для kind:transition invariants). Поддерживает все эндпоинты v0.5 + opts.history автоматически builds в engine submit.

Зачем

До этого пакета чтобы поднять Fold-runtime локально нужно было git clone idf + npm install + npm run server в host-репе. Это блокер коробочности: пользователь не должен знать про host. После этого пакета:

idf serve --ontology ./ontology.js   # планируется в @intent-driven/cli
# или программно:
import { createRuntime } from '@intent-driven/runtime-local';
const runtime = createRuntime({
  ontology: require('./ontology.js'),
  seed: require('./seed.json'),  // опц. — массив эффектов
});
await runtime.start();

Установка

npm install @intent-driven/runtime-local

Peer-зависимость: @intent-driven/core@>=0.49.0 (через @intent-driven/engine).

API

`createRuntime(opts)`

Создаёт runtime-инстанс. Не стартует сервер — для этого вызови .start().

Опция	Тип	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, engine, persistence, start(), stop() }. engine — instance @intent-driven/engine, для прямого использования (e.g., тесты).

`runtime.start()` → `Promise<{url, port, host}>`

Поднимает Express-сервер. Загружает seed в persistence перед listen. Возвращает actual URL/port (полезно при port: 0).

`runtime.stop()` → `Promise<void>`

Закрывает сервер.

Эндпоинты

Метод	Путь	Назначение
`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/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}` для 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

Тело запроса: { 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).

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 — в будущих релизах.

# Approver одобряет от имени admin'а
curl -X POST http://localhost:3001/api/approvals/ar_abc.../approve?as=admin \
  -d '{"reason":"validated by IT"}'

Roadmap (следующие PR)

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

JSPM