@intent-driven/core

Ядро парадигмы Intent-Driven Frontend: движок эффектов, сворачивание мира (fold), алгебра намерений, кристаллизатор v2, четыре материализации (пиксели / голос / агент / документ), инварианты, фильтрация по роли и preapproval guard.

Часть экосистемы Intent-Driven Frontend (IDF).

Установка

npm install @intent-driven/core
# или
pnpm add @intent-driven/core

Peer dependency: react@>=18.

Использование

Базовый движок

import { useEngine, crystallizeV2 } from "@intent-driven/core";

const domain = {
  DOMAIN_ID: "todo",
  INTENTS: {
    create_task: {
      label: "Создать задачу",
      particles: { effects: [{ tau: "task", alpha: "create" }] },
    },
  },
  PROJECTIONS: {
    task_list: {
      label: "Задачи",
      archetype: "feed",
      source: "task",
      slots: { title: { field: "title" } },
    },
  },
  ONTOLOGY: {
    entities: { task: { fields: { title: { type: "string" } } } },
  },
  buildEffects: (intentId, ctx, world, drafts) => [],
};

function App() {
  const { world, exec } = useEngine(domain);
  return (
    <button onClick={() => exec("create_task", { title: "Новая задача" })}>
      + Задача
    </button>
  );
}

const artifact = crystallizeV2(
  domain.INTENTS,
  domain.PROJECTIONS,
  domain.ONTOLOGY,
  domain.DOMAIN_ID,
);

Фильтрация мира по роли (§5)

import { filterWorldForRole } from "@intent-driven/core";

const visibleWorld = filterWorldForRole(world, ontology, "customer");

Проверка инвариантов (§14)

import { checkInvariants } from "@intent-driven/core";

const violations = checkInvariants(ontology, world);
if (violations.length > 0) {
  // откат через cascadeReject
}

Материализация в документ (§1)

import { materializeAsDocument, renderDocumentHtml } from "@intent-driven/core";

const doc = materializeAsDocument(artifact, world, "catalog");
const html = renderDocumentHtml(doc);

Проверка asset-boundary (§19)

import { getAssets, validateAsset, ASSET_KINDS } from "@intent-driven/core";

const assets = getAssets(ontology);
const result = validateAsset(assetDef); // { valid, errors }

Что экспортируется

Движок

| Export | Описание | |--------|----------| | useEngine(domain) | Главный React-hook; возвращает { world, exec, Overlay } |

Fold — мир из эффектов

| Export | Описание | |--------|----------| | fold(effects) | Вычисляет текущий мир из подтверждённых эффектов Φ | | foldDrafts(effects, drafts) | Fold с учётом session-scoped черновиков Δ | | applyPresentation(world, projection) | Применяет presentation-трансформации | | buildTypeMap(ontology) | Строит карту типов из онтологии | | filterByStatus(effects, status) | Фильтрует эффекты по статусу | | causalSort(effects) | Топологическая сортировка по причинно-следственным связям |

Алгебра намерений (§12)

| Export | Описание | |--------|----------| | computeAlgebra(intents, world) | Вычисляет связи ▷ ⇌ ⊕ ∥ между намерениями | | computeAlgebraWithEvidence(...) | То же с доказательствами для witness-of-proof | | normalizeEntityFromTarget(target) | Нормализует entity-target для алгебры |

Кристаллизатор v2

| Export | Описание | |--------|----------| | crystallizeV2(intents, projections, ontology, domainId) | Строит артефакт (7 архетипов) | | validateArtifact(artifact) | Проверяет корректность артефакта | | generateEditProjections(ontology) | Генерирует edit-проекции для всех сущностей | | findReplaceIntents(intents, entityType) | Находит replace-намерения для формы | | buildFormSpec(intent, ontology) | Строит спецификацию формы из намерения | | registerArchetype(name, fn) | Регистрирует пользовательский архетип | | prependArchetype(name, fn) | Добавляет архетип в начало registry | | selectArchetype(artifact, projection) | Выбирает подходящий архетип | | getArchetypes() | Возвращает все зарегистрированные архетипы |

Материализации (§1)

| Export | Описание | |--------|----------| | materializeAsDocument(artifact, world, projId) | Document-материализация (§1 4-я) | | renderDocumentHtml(doc) | HTML из document-графа | | materializeAsVoice(artifact, world, projId) | Voice-материализация (§1 3-я) | | renderVoiceSsml(voiceDoc) | SSML для TTS | | renderVoicePlain(voiceDoc) | Plain text для отладки |

Фильтрация по роли (§5)

| Export | Описание | |--------|----------| | filterWorldForRole(world, ontology, roleId) | Viewer-scoping с m2m через role.scope | | BASE_ROLES | Словарь базовых ролей: owner / viewer / agent / observer | | validateBase(base) | Проверяет корректность base-значения | | getRolesByBase(ontology, base) | Возвращает роли с заданной base | | isAgentRole(role) | Проверяет, является ли роль агентской | | isObserverRole(role) | Проверяет наблюдательную роль | | isOwnerRole(role) | Проверяет роль владельца | | auditOntologyRoles(ontology) | Аудит аннотаций ролей домена |

Preapproval guard (§17)

| Export | Описание | |--------|----------| | checkPreapproval(intent, ctx, world, preapprovalDef) | Проверяет 5 типов предикатов для agent-лимитов |

Инварианты (§14)

| Export | Описание | |--------|----------| | checkInvariants(ontology, world) | Проверяет schema-level ∀-свойства мира | | registerKind(kind, handler) | Регистрирует обработчик нового вида инварианта | | KIND_HANDLERS | Встроенные обработчики: role-capability, referential, transition, cardinality, aggregate |

Необратимость (§23)

| Export | Описание | |--------|----------| | mergeIntoContext(context, irrDef) | Добавляет __irr к контексту эффекта |

Asset-boundary (§19)

| Export | Описание | |--------|----------| | ASSET_KINDS | Перечень допустимых видов внешних активов | | getAssets(ontology) | Возвращает ontology.assets[] | | validateAsset(asset) | Валидирует декларацию актива |

Прочее

| Export | Описание | |--------|----------| | checkComposition(intents) | Проверяет корректность composition-алгебры | | checkIntegrity(world, ontology) | Integrity rules (referential, state machine) | | parseCondition(expr) / parseConditions(exprs) | Парсер условных выражений | | PARTICLE_COLORS, ALPHA_LABELS, LINK_COLORS | Визуальные константы для графа намерений | | SLOT_STATUS_COLORS, BOOKING_STATUS_COLORS | Константы статусов |

Связь с IDF

@intent-driven/core — канонический пакет парадигмы. Все остальные пакеты экосистемы зависят от него:

• @intent-driven/renderer использует crystallizeV2, fold, computeAlgebra для рендера
• @intent-driven/adapter-* получают capability surface от renderer, а не от core напрямую
• @intent-driven/canvas-kit — автономен, peer только react
• Server-слой (server/schema/*.cjs в основном репо) — thin re-exports из core для CJS-совместимости

Манифест IDF v1.7: docs/manifesto-v1.7.md

Версии

CHANGELOG.md

0.x — нестабильный API, breaking changes возможны без bump major. После 2–3 успешных продакшн-интеграций → 1.0.0.

Лицензия

Business Source License 1.1 (BUSL-1.1).

Коротко:

• Некоммерческое использование, обучение, исследования — свободно.
• Внутреннее корпоративное использование и разработка ваших собственных приложений на базе @intent-driven/core (которые вы распространяете своим конечным пользователям) — свободно.
• Hosted SaaS / PaaS, где третьи лица строят приложения поверх @intent-driven/core без установки собственного экземпляра, требует коммерческой лицензии от Licensor до Change Date.
• Change Date: 2030-04-15 (через 4 года от первой публикации). После этой даты пакет автоматически конвертируется в Apache License 2.0.

Полный текст: LICENSE. Вопросы по коммерческой лицензии — issue в репозитории или email указанный в author.

Клиентские пакеты экосистемы (@intent-driven/renderer, @intent-driven/adapter-*, @intent-driven/canvas-kit) распространяются под MIT, но используют @intent-driven/core как peer-dependency — их потребители также соглашаются с условиями BUSL-1.1 для @intent-driven/core до Change Date.