@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.