Skip to content

README.md

Latest commit

 

History

History
256 lines (182 loc) · 17.7 KB

README.md

File metadata and controls

256 lines (182 loc) · 17.7 KB

Intent-Driven Frontend (IDF)

Формат описания приложений с замыканием под собой. Не фреймворк, не low-code, не runtime — спецификация формы данных, над которой работают четыре независимых читателя: пиксели, голос, агентский API, документ.

npm @intent-driven/core npm @intent-driven/renderer spec Apache 2.0 core BSL 1.1 tests ~1960 cross-stack 4

Тезис

Приложение — это типизированная структура данных, а не код. Описывается четырьмя сущностями:

  • Ontology — типы домена с ролями и инвариантами
  • Intents — конструктивные частицы изменения мира (декларации, не handler'ы)
  • Projections — авторские контракты на логически связные виды
  • Φ — лог confirmed-эффектов; единственный источник истины
World(t) = fold(Φ_confirmed)

Из артефакта вычисляются четыре равноправные материализации §1: пиксели, голос, агентский API, документ. Один читатель — одна цель; viewer-scoping применяется ко всем четырём через одну функцию filterWorldForRole.

LLM участвует в проектировании и кристаллизации (witnesses с reliability: "heuristic"). В рантайме LLM отсутствует — ни одно решение, влияющее на состояние мира или рендер, не идёт через provider.

Серия статей

📖 «Мета-циркулярный evaluator для UX-формата» — три поста о замыкании формата под собой и AI как effect-emitter:

  1. «Closure: формат описывает себя» (скоро)
  2. «Анатомия: четыре читателя одного артефакта» (скоро)
  3. «AI как эффект-эмиттер» (скоро)

▶ Живая демонстрация — пройди по /meta (мета-домен), Pattern Inspector через Cmd+Shift+P, AI add-pattern через mock-LLM.

Пощупать за 60 секунд

# через npm — встраивание в существующий React-проект
npm install @intent-driven/core @intent-driven/renderer @intent-driven/adapter-mantine
import { useEngine } from "@intent-driven/core";
import { ProjectionRendererV2, registerUIAdapter } from "@intent-driven/renderer";
import { mantineAdapter } from "@intent-driven/adapter-mantine";

registerUIAdapter(mantineAdapter);

function App({ domain }) {
  const { world, exec } = useEngine(domain);
  return <ProjectionRendererV2 artifact={domain.ARTIFACT} world={world} exec={exec} />;
}
# или scaffold проект из существующей схемы (Postgres / OpenAPI / Prisma)
npx create-idf-app my-app
cd my-app && idf import postgres --connection $DATABASE_URL

17 доменов в одном движке кристаллизации

Домен Намерений Особенность
Sales 225 Аукционная барахолка, 4 роли, чисто-кристаллизационный (без ManualUI)
Keycloak 256 IAM Admin Console, AdminShell layout, scoped DataGrid, 5 tabs × 48 полей
ArgoCD 106 Status-driven admin, Swagger 2→3 import, K8s CRD inline-children
Messenger 100 WebSocket + WebRTC, real-time, 15 custom canvas
Notion 60 Block-based KB, первый polymorphic entity (Block × 15 variants)
Invest 61 Fintech, AntD, 7 правил Rules Engine, 3 ML-сервиса
LifeQuest 56 Цели + привычки, shadcn/doodle, mobile-first, 6 canvas
Reflect 47 Дневник эмоций (Yale RULER), Apple visionOS-glass
Freelance 46 Биржа услуг, multi-owner Deal (customer+executor), escrow, revision-loop
Delivery 45 Food last-mile, 5 ролей, scheduler + map + irreversibility
Compliance 38 SOX ICFR / «provable UI», 6 ролей, 15 invariants, 5 __irr:high intents
Automation 36 Visual workflow в духе n8n, 4 роли, threshold + schedule rules
Booking 22 Онлайн-запись, темпоральные предикаты, wizard
Planning 17 Коллективные опросы, кворум, phase-aware CTA
Workflow 15 Визуальный редактор процессов, React Flow canvas
Gravitino — Metadata catalog dogfood (Apache Gravitino WebUI v2 reference)
Meta 8 IDF, описанный в IDF. Self-hosting closure: 10 entities, Studio shell, 16 доменов в snapshot

Итого: ~1100 намерений, один движок, ~1960 тестов (842 host + 916 core + 175 renderer + 36 canvas-kit + 34 adapters).

Closure: формат описывает себя

Мета-домен /meta — это IDF, описанный в IDF. Каждая сущность формата (Domain, Intent, Projection, Pattern, Witness, RRule, Adapter, Capability, BacklogItem, PatternPromotion) — обычная entity в обычном ontology.entities. Каждый Pattern в банке — instance этой Pattern-entity. 16 доменов runtime-loaded в snapshot через crystallizeV2 + explainAllCrystallize.

Это closure-под-формат: первый внутренний observer, не зависящий от единичного use-case. Параллель — meta-circular evaluator из SICP 4.1.

AI как эффект-эмиттер

@intent-driven/llm-bridge — formal contract LLM subprocess → EffectSink → Φ. Claude CLI spawn'ится из мета-Studio, парсит stream-json, валидирует output через Zod gate, эмиттит ResearchRun + Pattern.applySource эффекты в общий лог. SSE broadcast обновляет UI в realtime.

Ключевой инвариант: LLM модифицирует формат, но не нарушает детерминизм рантайма — все эффекты проходят те же инварианты, что и человеческие.

await sink.emit({ α: "create", entity: "ResearchRun", fields: { runId, status: "running" } });
const { text } = await provider.run(prompt, { signal, onProgress });
const validated = SynthesizedApplySchema.parse(JSON.parse(text));
await sink.emit({ α: "replace", entity: "Pattern", fields: { applySource: validated.structure.apply } });

Четыре материализации §1

Читатель Endpoint Форматы Реализация
Pixels ProjectionRendererV2 + adapter registry React DOM 4 UI-адаптера, capability surface, Token Bridge
Voice GET /api/voice/:domain/:projection json / SSML / plain brevity-rules, top-3 для catalog, money как «два с половиной миллиона»
Agent API /api/agent/:domain/{schema,world,exec} JSON JWT + role.canExecute + visibleFields + preapproval
Document GET /api/document/:domain/:projection HTML / JSON structured document-граф, viewer-scoped 
const scoped   = filterWorldForRole(world, role);
const pixels   = ProjectionRendererV2(artifact, scoped);
const voice    = voiceMaterializer(artifact, scoped);
const agent    = agentSchema(artifact, scoped);
const document = documentMaterializer(artifact, scoped);

Pattern Bank

37 stable patterns (35 с structure.apply, 2 matching-only). Двухосевая таксономия: архетип (структура: feed/catalog/detail/...) × паттерн (поведение: monitoring/triage/execution/exploration/configuration). Falsification fixtures в .test.js для каждого паттерна.

Pattern Inspector (toggle Cmd+Shift+P) — Off / Preview / Commit / X-ray режимы. Derivation X-ray помечает каждый дериввированный slot warm-yellow border'ом с hover-trail.

patterns/stable/
├── catalog/   (11) — grid-card-layout, hero-create, kanban-phase-column-board, ...
├── detail/    (13) — subcollections, m2m-attach-dialog, lifecycle-locked-parameters, ...
├── cross/     (9)  — bulk-action-toolbar, hierarchy-tree-nav, irreversible-confirm, ...
└── feed/      (3)  — composer-entry, antagonist-toggle, response-cost-before-action

Четыре UI-адаптера на одной онтологии (валидация §17)

Адаптер Пакет Стиль Дефолт для
Mantine @intent-driven/adapter-mantine Corporate / data-dense booking, planning, workflow, messenger, sales
shadcn/ui (Doodle) @intent-driven/adapter-shadcn Handcrafted / sketch lifequest
Apple visionOS-glass @intent-driven/adapter-apple Premium / glassmorphism reflect
Ant Design @intent-driven/adapter-antd Enterprise / fintech-grade invest, compliance, keycloak, argocd, automation

Переключение в runtime через PrefsPanel ⚙ → UI-kit. adapter.capabilities декларативно описывает поддерживаемые primitive'ы; getCapability / supportsVariant дают graceful fallback.

Cross-stack реализации

Структурный стресс-тест: формат decoupled от языка. Четыре независимые имплементации читают один idf-spec и проходят L1+L2 conformance:

Стек Репо Уровень
JavaScript / React intent-driven-software/idf-sdk L1+L2+L3 (документ-материализация)
Go intent-driven-software/idf-go L1+L2+L3
Rust intent-driven-software/idf-rust L1+L2+L3
Swift intent-driven-software/idf-swift L1+L2+L3

Conformance harness — npm run conformance против shared L1+L2 fixtures.

Ключевые концепты

  • Намерение — атом формата: сущности, условия, эффекты, witnesses, подтверждение (RFC 2119 определение в спеке §3)
  • Проекция — формальная спецификация ⟨E, Q⟩: какие сущности показать, какой запрос, какие кнопки. Зависит от зрителя через role.scope
  • Кристаллизатор v2 — построение артефакта из (intents + ontology + projection). Чистая функция, перегенерируема, тестируема. 7 архетипов
  • Алгебра связей §12 — пять типов (▷ sequential, ⇌ antagonistic, ⊕ excluding, ∥ parallel, adjacency) выводятся из частиц, не декларируются
  • Темпоральный scheduler — schedule_timer / revoke_timer как системные intent'ы; таймеры — обычные эффекты τ в Φ
  • Map primitive — spatial primitive по образцу chart: 4 layer-kind, SVG-fallback, adapter-delegation
  • Irreversibility — instance-уровневая метка effect.context.__irr = { point, at, reason }; integrity-правило блокирует α:"remove" после point=high, at≠null
  • Reactive Rules Engine — event-condition-action + 4 extensions v1.5 (aggregation / threshold / schedule / condition)
  • Global Invariants — 6 видов: role-capability / referential / transition / cardinality / aggregate / expression

Что читать

  1. Манифест v2 — 26 глав в 8 частях, timeless-документ о формате IDF: тезис, объекты формата, алгебра, четыре читателя, авторство, conformance, границы, перспектива
  2. Открытая спецификация v0.1 — формальный документ под Apache 2.0, JSON-схемы L1+L2, conformance test fixtures
  3. Implementation status — живой документ: 17 доменов, 19 SDK-пакетов, ~1960 тестов, open items
  4. Field tests — каждый — один домен, один цикл «обнаружение блокера → формализация → закрытие»
  5. Серия статей (см. выше) — мета-циркулярность как narrative arc

Зеркала экосистемы

Репо Назначение
intent-driven-software/idf Этот — entry-point, манифест, спецификация, прототип
intent-driven-software/idf-sdk 19 npm-пакетов: ядро, рендерер, 4 адаптера, scaffold-путь, importers
intent-driven-software/idf-spec JSON Schema + conformance L1+L2 + cross-stack fixtures
intent-driven-software/idf-go Go-имплементация
intent-driven-software/idf-rust Rust-имплементация
intent-driven-software/idf-swift Swift-имплементация
intent-driven-software/idf-infra LLM subprocess bridge: effect-sink + llm-subprocess + llm-bridge
intent-driven-software/idf-auth Identity plane (live: auth.intent-design.tech)
intent-driven-software/idf-runtime Data plane (live: runtime.intent-design.tech)
intent-driven-software/idf-studio Control plane (live: studio.intent-design.tech)

Часть зеркал может быть в процессе миграции из DubovskiyIM/* namespace.

Граница применимости

Парадигма фальсифицируема, и это её сила:

  • Зона максимальной силы: транзакционные домены (e-commerce, аукционы, финтех, бронирование, операционка)
  • Зона высокой силы: темпоральные, коллаборативные, коммуникационные, admin/IAM, status-driven control planes
  • Граница: распределённые системы с eventual consistency, real-time collaborative editing (CRDT), ML в рантайме, game-loop / физика

Подробнее — §21 «Транзакционный уклон парадигмы» и §23 «Слабые места и открытые задачи» манифеста v2.

Лицензирование

Многолицензионный репозиторий:

Зона Лицензия Путь
Спецификация Apache License 2.0 spec/LICENSE
Документация (манифест, field-tests) Apache License 2.0 docs/LICENSE
Ядро @intent-driven/core Business Source License 1.1 → Apache 2.0 на 2030-04-15 in idf-sdk
Прототип, домены MIT LICENSE-CODE
Клиентские SDK пакеты MIT in idf-sdk

Подробнее — LICENSE (pointer, объясняющий split).

Автор: Игнат Дубовский · dubovskiy.im@gmail.com