Один источник правды на плагин — убиваем рассинхрон трёх файлов

Каждый плагин в Tinker Dice имел три файла, описывающих одни и те же вещи тремя разными способами: manifest.ts (документация для AI), definition.ts (метаданные редактора) и core.ts (рантайм-логика). Когда добавлялось новое действие, нужно было обновить все три. Забудешь одно — и AI будет генерировать графы с возможностями, которых нет, или пропустит возможности, которые есть.

Симптомы были повсюду: manifest.capabilities.providesActions расходился с реальными хэндлерами в core.ts. AI-документация описывала параметры одним образом, definition.ts — другим, а core.ts принимал третий. Мёртвые импорты от удалённых типов. Builder AI получал противоречивую информацию и генерировал невалидные графы.

ADR-016 ввёл createPlugin() — фабрику, которая принимает единый дескриптор и генерирует из него PluginManifest, HandlerDefinition[] и подкласс BasePlugin. Дескриптор использует defineAction() и defineGuard() для колокации метаданных с логикой хэндлеров. Параметры, inputs, outputs, AI-документация — всё в одном месте.

Ключевые принципы:

• Колокация — метаданные действия живут рядом с логикой хэндлера
• Генерация вместо дублирования — manifest и definition генерируются, не пишутся руками
• Обратная совместимость — PluginRegistry, HandlerRegistry и Engine не меняются
• Инкрементальная миграция — плагины мигрируют по одному

Структура файлов после миграции: plugin.ts (SSOT-дескриптор), core.ts (только рантайм, без изменений), ui-widget.tsx (без изменений), а manifest.ts и definition.ts становятся тонкими re-exports из plugin.ts.

Это устранило целую категорию багов. Когда единый источник правды говорит, что действие принимает параметры [deckId, count] — AI-документация, ноды редактора и рантайм все согласны. Никакого рассинхрона. Никакого «AI думал, что плагин умеет X, потому что manifest.ts не обновили».

Это тот же урок, который каждая кодовая база рано или поздно усваивает: три источника правды для одного факта всегда расходятся. Один источник правды не может разойтись — он может только быть неправ, а неправильное легче исправить.