Files
slm-design/DRAFT/rules/level-2.md

210 lines
16 KiB
Markdown
Raw Normal View History

2026-07-30 10:56:48 +03:00
# Правила SLM второго уровня
2026-08-02 22:53:05 +03:00
Доменный пакет Level 2 соблюдает правила Level 1 и дополнительные правила этого реестра. Для предметной области в пакетной форме [`SLM-L1-DOMAIN-R015`](./level-1.md#slm-l1-domain-r015) заменяется правилами доменного пакета; остальные предметные области того же SLM root могут сохранять форму доменного модуля Level 1. [`SLM-L1-GROUP-R007`](./level-1.md#slm-l1-group-r007) сохраняется для Groups внутри пакета и вне слоя `domains`, а для навигационных Groups слоя `domains` заменяется `SLM-L2-GROUP-R004`. Для модуля `api` правило [`SLM-L1-MODULE-A004`](./level-1.md#slm-l1-module-a004) уточняется `SLM-L2-API-A019`: объявленные фасеты вместе образуют один логический публичный API и не считаются deep imports. Ранее использовавшиеся номера `SLM-L2-DOMAIN-R001` и `SLM-L2-MIGRATION-A017` не переиспользуются.
2026-07-30 10:56:48 +03:00
## Граница доменного пакета
2026-07-30 10:56:48 +03:00
### SLM-L2-DOMAIN-R002
2026-07-30 10:56:48 +03:00
> **Предметная граница пакета**
2026-07-30 10:56:48 +03:00
>
> Каждая предметная область, использующая пакетную форму Level 2, представлена ровно одним доменным пакетом; все его модули относятся только к этой предметной области.
### SLM-L2-DOMAIN-A003
> **Корень доменного пакета**
>
2026-08-02 22:53:05 +03:00
> Корень доменного пакета содержит только декларативную metadata, модуль `api` и допустимые Groups и не содержит других прямых модулей, исполняемых файлов, изменяемого состояния, ресурсов жизненного цикла, публичного API или реэкспортов.
### SLM-L2-GROUP-R004
> **Навигационная Group доменов**
>
> Group, расположенная непосредственно в слое `domains` или другой такой Group, содержит только доменные модули Level 1, доменные пакеты Level 2 и навигационные Groups и не владеет реализацией, состоянием, жизненным циклом или публичным API.
2026-08-02 22:53:05 +03:00
## Доменный API
2026-08-02 22:53:05 +03:00
### SLM-L2-API-R005
2026-08-02 22:53:05 +03:00
> **Модуль api**
>
2026-08-02 22:53:05 +03:00
> Каждый доменный пакет содержит ровно один модуль `api`, который объявляет один или несколько именованных Domain API, их публичные модели, результаты, ошибки, dependency ports и фабрики.
2026-08-02 22:53:05 +03:00
### SLM-L2-API-R006
2026-08-02 22:53:05 +03:00
> **Семантическая власть Domain API**
>
2026-08-02 22:53:05 +03:00
> Доступные приложению доменные данные, модели, validation, семантика команд и запросов, результаты и ожидаемые ошибки производятся или проверяются модулем `api`; adapters, assemblies и framework bindings не определяют параллельную предметную модель или переход.
2026-08-02 22:53:05 +03:00
### SLM-L2-API-A007
2026-08-02 22:53:05 +03:00
> **Импортная замкнутость api**
>
2026-08-02 22:53:05 +03:00
> Все runtime- и type-only импорты модуля `api`, кроме междоменных зависимостей по `SLM-L2-DEPENDENCY-A012`, ведут только к файлам этого модуля, объявленным environment-neutral ресурсам `shared` и внешним пакетам, объявленным как API-safe.
### SLM-L2-FACTORY-R008
> **Фабрики Domain API**
>
2026-08-02 22:53:05 +03:00
> Каждому публичному Domain API соответствует ровно одна именованная фабрика фасета `api/factory`; фабрика получает явные ports и cross-domain API, создаёт только этот Domain API, не выбирает adapter или assembly и не запускает скрытые ресурсы жизненного цикла.
## Ошибки домена
### SLM-L2-ERROR-R009
> **Публичный контракт ошибок**
>
2026-08-02 22:53:05 +03:00
> Каждый ожидаемый сбой публичной операции Domain API представлен именованным readonly сериализуемым типом собственной доменной ошибки с устойчивым кодом; тип экспортируется через `api`, а необходимые внешним потребителям runtime-коды и guards только через `api/runtime`.
### SLM-L2-ERROR-R010
> **Изоляция исходных ошибок**
>
2026-08-02 22:53:05 +03:00
> Сбой provider, adapter, SDK, транспорта, storage или другого домена, доступный приложению через Domain API, представлен только безопасной ошибкой собственного доменного контракта и не раскрывает исходный объект, тип, message, status, payload или cause.
## Assemblies и зависимости
### SLM-L2-ASSEMBLY-R011
> **Роль assembly**
>
2026-08-02 22:53:05 +03:00
> Каждая assembly является SLM-модулем одного объявленного production-контекста, выбирает adapter-модули, вызывает одну или несколько фабрик своего `api` и возвращает явный именованный граф готовых Domain API, не добавляя предметные операции, модели или ошибки.
### SLM-L2-DEPENDENCY-A012
> **Междоменные импорты Level 2**
>
2026-08-02 22:53:05 +03:00
> Статическая связь между разными доменными границами, хотя бы одна из которых является пакетом Level 2, допускает только type-only импорт публичного API доменного модуля Level 1 или фасета `api` пакета Level 2 либо runtime-импорт `api/runtime` пакета Level 2; остальные публичные и внутренние пути другого домена не импортируются.
### SLM-L2-ENVIRONMENT-A013
> **Совместимость среды выполнения**
>
2026-08-02 22:53:05 +03:00
> Для каждой объявленной точки входа, поддерживаемого набора resolver conditions и framework execution phase её достижимый executable import-граф не содержит несовместимых runtime capabilities; type-only связи, framework reference и deferred edges проверяются отдельно и не считаются обычным выполнением.
## Framework Groups и тестирование
### SLM-L2-FRAMEWORK-R014
> **Framework Group домена**
>
> Framework binding modules доменного пакета размещаются в Group, названной по фреймворку, и каждый прямой дочерний элемент этой Group является framework binding module.
### SLM-L2-FRAMEWORK-R015
> **Framework binding module**
>
2026-08-02 22:53:05 +03:00
> Модуль внутри Framework Group владеет одной domain-specific framework-ответственностью, получает готовые Domain API, материализует их значения средствами фреймворка и не вызывает фабрики, не выбирает adapters, не обращается к предметному внешнему источнику в обход Domain API и не владеет страницей, маршрутом или multi-domain композицией.
### SLM-L2-TEST-R016
> **Проверка владельцев Level 2**
>
2026-08-02 22:53:05 +03:00
> Каждый публичный сценарий проверяется через фабрику владеющего им Domain API, каждый adapter — по контракту реализуемого port, а основные тесты assembly и framework binding module проверяют только собственные публичные границы и не повторяют полный набор сценариев Domain API.
## Совместное применение форм
### SLM-L2-DOMAIN-A026
> **Однозначная форма домена**
>
> Каждая предметная область объявлена ровно в одной форме: как доменный модуль Level 1 либо как доменный пакет Level 2; один SLM root может одновременно содержать разные предметные области обеих форм.
2026-08-02 22:53:05 +03:00
## Внешние библиотеки api
2026-08-02 22:53:05 +03:00
### SLM-L2-API-R018
2026-08-02 22:53:05 +03:00
> **API-safe внешний пакет**
>
2026-08-02 22:53:05 +03:00
> Внешний пакет объявляется API-safe только если он детерминирован, не выполняет ввод-вывод, не владеет изменяемым состоянием или runtime capability и не является SDK, generated client, storage, state/query manager, framework или другой технической интеграцией.
2026-07-30 20:48:05 +03:00
2026-08-02 22:53:05 +03:00
## Публичные фасеты api
2026-07-30 20:48:05 +03:00
2026-08-02 22:53:05 +03:00
### SLM-L2-API-A019
2026-07-30 20:48:05 +03:00
2026-08-02 22:53:05 +03:00
> **Публичные фасеты api**
2026-07-30 20:48:05 +03:00
>
2026-08-02 22:53:05 +03:00
> Публичный API модуля `api` имеет обязательные entry points `api` только с type exports и `api/factory` только с runtime exports, может иметь `api/ports` только при наличии объявленного dependency port и только с type exports и `api/runtime` только с runtime exports и не имеет других публичных путей или deep imports.
2026-07-30 20:48:05 +03:00
2026-08-02 22:53:05 +03:00
## Обязательная штатная сборка
2026-07-30 20:48:05 +03:00
### SLM-L2-ASSEMBLY-A020
2026-07-30 20:48:05 +03:00
2026-08-02 22:53:05 +03:00
> **Обязательная assembly default**
2026-07-30 20:48:05 +03:00
>
2026-08-02 22:53:05 +03:00
> Корень каждого доменного пакета содержит ровно одну непустую Group `assemblies` с ровно одним прямым модулем `default`; каждый другой прямой дочерний элемент Group также является объявленной границей assembly-модуля.
2026-07-30 20:48:05 +03:00
### SLM-L2-ADAPTER-R021
> **Модули production adapters**
>
2026-08-02 22:53:05 +03:00
> Если хотя бы одна фабрика имеет dependency port, корень доменного пакета содержит непустую Group `adapters`, а каждая связная production-реализация одного или нескольких ports принадлежит ровно одному adapter-модулю этой Group и не определяется в другом месте production-графа.
2026-07-30 20:48:05 +03:00
2026-08-02 22:53:05 +03:00
### SLM-L2-API-A022
2026-07-30 20:48:05 +03:00
2026-08-02 22:53:05 +03:00
> **Потребители фасетов и сборочных модулей**
2026-07-30 20:48:05 +03:00
>
2026-08-02 22:53:05 +03:00
> Фасет `api` импортируется извне только через `import type`, `api/ports` импортируют только adapters своего домена, assemblies и тесты, `api/factory` и concrete adapters в production импортируют только assemblies своего домена, а `api/runtime` не импортируют adapters и используют только через объявленный публичный путь с соблюдением правил слоёв и междоменных зависимостей.
## Жизненный цикл assembly
### SLM-L2-ASSEMBLY-R023
2026-08-02 22:53:05 +03:00
> **Транзакционный lifecycle assembly**
>
2026-08-02 22:53:05 +03:00
> Assembly не запускает скрытую долгоживущую работу; cleanup каждого созданного ею ресурса и каждого полученного adapter lifecycle handle немедленно регистрируется, при частичной ошибке выполняется в обратном порядке, а успешный результат с cleanup obligations предоставляет идемпотентный aggregate cleanup, после завершения которого resources не вызывают callbacks.
2026-08-02 22:53:05 +03:00
## Недетерминизм api
2026-08-02 22:53:05 +03:00
### SLM-L2-API-R024
> **Явные источники недетерминизма**
>
2026-08-02 22:53:05 +03:00
> Операция Domain API получает текущее время, timer, random, ID generator, environment и другие источники недетерминизма только через явные ports фабрики и не читает их из скрытого runtime-окружения.
2026-08-02 22:53:05 +03:00
## Публичный runtime api
2026-08-02 22:53:05 +03:00
### SLM-L2-API-R025
2026-08-02 22:53:05 +03:00
> **Детерминированный runtime api**
>
2026-08-02 22:53:05 +03:00
> Фасет `api/runtime` экспортирует только необходимые реальным внешним потребителям детерминированные значения и функции без ввода-вывода, изменяемого состояния, runtime capability или environment-specific поведения.
## Dependency ports
### SLM-L2-PORT-R027
> **Consumer-owned port**
>
> Каждый dependency port принадлежит модулю `api`, описывает минимальную необходимую ему capability и закрытый набор ожидаемых port failures без concrete provider, SDK, framework или transport types; adapter реализует этот контракт, но не определяет его семантику.
## Материализация состояния
### SLM-L2-STATE-R028
> **Framework-owned materialization**
>
> Framework binding или composition может владеть framework metadata и собственным UI-state, но материализует доменный payload только из values, outcomes и events, произведённых или проверенных Domain API, и применяет предметный optimistic merge, reconciliation или transition только через операцию либо детерминированный runtime модуля `api`.
## Realtime
### SLM-L2-REALTIME-R029
> **Проверяемый realtime-контракт**
>
> Каждый realtime port явно определяет correlation, момент подтверждения команды, ordering, duplicate, reconnect, resync, cancellation и cleanup semantics; adapter скрывает transport protocol, а Domain API публикует только проверенные события, outcomes и собственные стабильные ошибки.
## Runtime-граф assemblies
### SLM-L2-ASSEMBLY-R030
> **Ацикличная runtime-сборка**
>
> Runtime-граф публичных API доменных модулей Level 1 и Domain API пакетов Level 2, включая assembly inputs, factory dependencies и передаваемые callbacks, не содержит циклов, а graph owner создаёт независимые API раньше зависимых и очищает их в обратном порядке.
### SLM-L2-ASSEMBLY-R031
> **Контекст default assembly**
>
> `assemblies/default` представляет один объявленный штатный production-набор API, dependencies, runtime capabilities и lifecycle; имя `default` само по себе не означает browser-, server- или isomorphic-совместимость, а отличающийся контекст получает отдельную именованную assembly.