cherrypick/openspec/changes/cherrypick-system-spec/design.md

Context

CherryPick — монорепозиторий DI‑экосистемы для Dart/Flutter, включающий ядро рантайма, аннотации, генератор и Flutter‑интеграцию, а также адаптер логирования для Talker. Требуется системная спецификация модулей и их контрактов на русском языке.

Goals / Non-Goals

Goals:

• Зафиксировать архитектурные границы и контракты модулей.
• Согласовать терминологию и жизненные циклы ключевых сущностей.
• Дать проверяемые требования с однозначными сценариями.

Non-Goals:

• Изменение или рефакторинг кода.
• Детализация низкоуровневых алгоритмов генератора.
• Документация внешних библиотек (Flutter, Talker).

Decisions

• Разбить спецификацию по четырем capability: di-runtime, annotations-and-codegen, flutter-integration, talker-logging-adapter.
• Все требования формулировать нормативно (MUST) и снабжать сценариями WHEN/THEN.
• Описывать сущности, жизненный цикл, ошибки и точки расширения в каждом capability.

Альтернативы:

• Единый монолитный spec.md: отклонено из-за ухудшения навигации и поддержки.
• Использовать SHOULD/MAY: отклонено для уменьшения двусмысленности.

Risks / Trade-offs

• [Risk] Спецификация может расходиться с фактическим поведением кода → Mitigation: привязка требований к публичным API и README, дальнейшая валидация при реализации.
• [Risk] Перекрывающиеся требования между capability → Mitigation: строгие границы и минимальный повтор.

Migration Plan

• Спецификация вводится как документ без влияния на runtime.
• При необходимости последующих изменений — через отдельные change‑запросы OpenSpec.

Open Questions

• Нужно ли фиксировать требования по производительности (O(1) lookup) как отдельный раздел?
• Нужны ли отдельные сценарии для edge‑cases (например, singleton + params)?