# Системные паттерны Mastermind

Этот документ описывает нормативные паттерны взаимодействия подсистем Mastermind.

## 1. Capability-Oriented Clean Architecture

**Problem**: Высокая связность между захватом, хранилищем и UI мешает тестированию и безопасности.
**Rule**: Каждая функциональная область (Capability) инкапсулирована в отдельный модуль с чёткими границами. Взаимодействие происходит через порты (протоколы).
**Apply when**: При добавлении новой крупной функциональности (например, новый вид захвата).
**Avoid**: Прямой импорт конкретных реализаций (Adapters) между модулями.
**Trade-offs**: Требует больше кода для инициализации (Dependency Injection).
**Verification**: Запрещены перекрёстные импорты в Swift модулях; Unit-тесты используют Mock-реализации портов.

## 2. Ports & Async Events

**Problem**: Глобальные шины событий (EventBus) делают зависимости неявными и затрудняют отладку.
**Rule**: Запросы и команды идут через явные порты (Application Ports). Факты о произошедшем передаются через типизированные асинхронные потоки событий (Typed Async Events). Глобальная шина запрещена.
**Apply when**: Для межмодульного взаимодействия.
**Avoid**: Использование `NotificationCenter` или глобальных `ObservableObject`.
**Trade-offs**: Требует явной оркестрации в Composition Root.
**Verification**: Каждый исходящий поток событий должен быть частью интерфейса порта модуля.

## 3. Observation Ledger

**Problem**: Прямая запись результатов захвата в граф знаний приводит к потере контекста и невозможности переобработки данных.
**Rule**: Collectors записывают только неизменяемые "свидетельства" (Observations) в лог (Ledger). Только Knowledge Pipeline читает этот лог.
**Apply when**: При обработке любого потока данных из источников (Sources).
**Avoid**: Прямое обновление Facts или Entities из Collectors.
**Trade-offs**: Увеличивает объём хранимых данных на диске до момента очистки (Retention).
**Verification**: База данных содержит таблицу `Observations` с Provenance.

## 4. Idempotent Projectors & Durable Checkpoints

**Problem**: Сбой во время обработки Observations может привести к дублированию или потере знаний в графе.
**Rule**: Проекторы (Projectors) читают лог Observations и обновляют граф, сохраняя контрольные точки (Checkpoints). Процесс должен быть идемпотентным.
**Apply when**: При преобразовании сырых данных в Assertions и Facts.
**Avoid**: Логика проекции, зависящая от текущего времени или внешнего состояния вне лога.
**Trade-offs**: Усложняет логику обновления графа.
**Verification**: Перезапуск проектора с одного и того же чекпоинта должен приводить к идентичному состоянию графа.

## 5. Capability-Specific Persistence Ports

**Problem**: Общие репозитории (Generic Repository<T>) скрывают специфичные требования к данным и производительности.
**Rule**: Каждый модуль определяет свои узкие порты для работы с данными (например, `AppendObservation`, `QueryContext`). Реализация за скрытым SQLite/SQLCipher адаптером.
**Avoid**: Использование общего DAO или прямого доступа к БД вне адаптера.
**Verification**: Интерфейсы портов содержат только те методы, которые реально нужны данному модулю.

## 6. Central Egress Gate & Privacy Envelopes

**Problem**: Риск случайной отправки конфиденциальных данных (PII) в облако.
**Rule**: Весь исходящий трафик к внешним провайдерам проходит через единый Egress Gate. Данные передаются в типизированных конвертах (Privacy Envelopes) с метаданными о классификации.
**Apply when**: Любая передача данных за пределы Mac (Cloud Providers).
**Avoid**: Прямые сетевые запросы из Assistant или других модулей.
**Trade-offs**: Единая точка отказа и бутылочное горлышко производительности.
**Verification**: Egress Gate блокирует любые данные без явного Provider Context Permission.

## 7. Work Scheduler & Budgets

**Problem**: Непрерывный захват и ML-обработка могут замедлять UI или разряжать батарею.
**Rule**: Центральный планировщик распределяет задачи по приоритетам и бюджетам ресурсов. Аудио и интерактив всегда выше фоновой индексации.
**Avoid**: Запуск `Task.detached` без указания приоритета и лимитов.
**Trade-offs**: Может увеличивать задержку (latency) для фоновых задач.
**Verification**: Приложение снижает активность в Low Power Mode.

## 8. Bounded Derived Caches

**Problem**: Кэширование может приводить к несогласованности данных и утечкам памяти.
**Rule**: Все кэши ограничены (bounded), принадлежат конкретным акторам (actor-owned) и могут быть полностью перестроены из Context Store.
**Apply when**: Для OCR, embeddings и UI элементов.
**Avoid**: Использование глобального `NSCache` без ограничений по времени и размеру.
**Verification**: Unit-тесты проверяют очистку кэша при достижении лимитов.

## 9. Structured Local Tracing

**Problem**: Текстовые логи бесполезны для отладки сложных распределённых процессов без передачи контента.
**Rule**: Использование структурированных спанов и событий с Correlation IDs (SourceID, ObservationID). Redacted metadata — только технические детали.
**Avoid**: Логирование распознанного текста или аудио-транскриптов.
**Verification**: Логи не содержат персональных данных пользователя, но позволяют проследить путь конкретной Observation.

## 10. Versioned Boundaries

**Problem**: Изменение формата данных (ASR, LLM, Export) ломает совместимость.
**Rule**: Все границы (Sidecars, Providers, Archives) используют типизированные DTO с версионированием и Contract Tests. Tolerant Reader обязателен.
**Avoid**: Сериализация внутренних доменных типов напрямую.
**Verification**: Наличие тестов на обратную совместимость схем.