Что такое спецификация

dagstack/plugin-system-spec — нормативный источник истины. Он фиксирует что должно быть в любой реализации плагин-системы (для Python, TypeScript, Go, будущих языков) — и почему именно так, а не иначе. Конкретные реализации (plugin-system-python, plugin-system-typescript, plugin-system-go) обязаны соблюдать этот контракт и подтверждать соответствие набором конформанс-тестов.

Чем раздел «Спецификация» отличается от руководств

Раздел	Для кого	Что даёт
Понятия	Пользователь плагин-системы	Объясняет, как работает реестр/манифест/диспетчер сегодня, в применении к конкретному языку.
Руководства	Пользователь плагин-системы	Пошагово решает задачу (написать плагин, настроить конфиг).
Спецификация (этот раздел)	Автор реализации / автор собственного вида плагина / ревьюер	Объясняет почему принято решение; фиксирует нормативные гарантии, на которые можно опереться; описывает, какие ситуации binding обязан обработать одинаково независимо от языка.

Если вы пишете плагин для Python или TypeScript — читайте «Понятия» и «Руководства». Если вы:

• реализуете собственный binding для нового языка;
• разрабатываете свой вид плагина (hookspec) и хотите, чтобы он работал во всех языках;
• участвуете в архитектурном ревью изменений ядра;

— тогда вам в этот раздел.

Чем ADR отличаются от обычной документации

ADR (Architecture Decision Record) — короткий документ, который фиксирует одно архитектурное решение:

• Контекст — какую проблему решаем, что мешало её решить раньше.
• Решение — что делаем и какими средствами.
• Последствия — что становится проще / сложнее / невозможно после этого решения.
• Альтернативы — какие варианты рассматривались и почему отвергнуты.

ADR — исторический артефакт. Когда решение пересматривается, ADR не удаляется — появляется новый ADR, который supersedes предыдущий. Это позволяет проследить эволюцию архитектуры и понять рациональность текущего состояния.

Шесть ADR плагин-системы

На момент v1.0 спецификации зафиксированы шесть решений:

1. ADR-0001: Архитектура ядра — что такое плагин, манифест, реестр, контекст. Общая структура любой реализации.
2. ADR-0002: Семантика вызова хуков — пять классов диспетчеризации (singleton / broadcast-collect / broadcast-notify / chain / capability), их нормативное поведение.
3. ADR-0003: Orchestration-neutral runtime — восемь runtime-инвариантов, которые делают плагин работоспособным в FastAPI, Dagster, Celery и pytest одинаково.
4. ADR-0004: Формализм hookspec — как описывается контракт вида плагина через YAML + JSON Schema, из которого эмитируются типы для каждого языка.
5. ADR-0005: Горизонтальные расширения — governance, quota, observability поверх любого пользовательского плагина.
6. ADR-0006: File-based discovery — как именно реестр находит плагины в файловой системе.

Нормативный vs описательный текст

Страницы этого раздела — описательный русскоязычный synopsis каждого ADR. Они переводят формулировки нормативного контракта в понятный прозаический язык и добавляют кросс-языковые примеры.

Формальный нормативный текст ADR — в spec-репозитории dagstack/plugin-system-spec. В каждой странице этого раздела есть прямая ссылка на полный текст соответствующего ADR. Если вы готовите изменения в binding — читайте именно нормативную версию: там фиксируются все edge-case-ы, запрещённые конструкции, требования к сообщениям об ошибках.

Процесс изменения спецификации

Если вы хотите изменить поведение плагин-системы (добавить шестой класс диспетчеризации, ослабить инвариант, изменить формат манифеста):

1. Откройте issue в dagstack/plugin-system-spec с описанием проблемы и предлагаемого решения.
2. После обсуждения — PR с новым ADR (ADR-0007+) либо правкой существующего (с явным supersedes).
3. Пройти architect review и ревью мейнтейнеров реализаций — все plugin-system-<lang> должны подтвердить, что смогут реализовать предложенное.
4. После merge — обновить реализации и обновить соответствующий synopsis в этом разделе (в том же PR spec-репо, чтобы не возникало дрейфа).

Связанные спецификации

• dagstack/config-spec — плагин-система использует конфиг-стек для чтения секций плагинов (<kind>.<name>).
• dagstack/logger-spec — структурированное логирование в PluginContext.logger.
• dagstack/tenancy-spec — TenantContext передаётся в PluginContext для мульти-клиентной изоляции.

Таблица связей по решениям — на странице Связи между спеками.