8.4 KiB
Системные паттерны 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) скрывают специфичные требования к данным и производительности.
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: Наличие тестов на обратную совместимость схем.