MEL: стейт-машина вместо карт обработчиковРЕАЛИЗОВАНО · :core:mel

1. TL;DR — что собрано

MEL — цикл Elm/MVU-типа поверх явной стейт-машины, реализованный в модуле :core:mel. Экран описывается одним классом-машиной (MelMachine<S, I, E>, создаётся фабрикой с аргументами экрана — §4.4): sealed-стейты владеют фактами, интенты привязаны к стейтам типами (интент чужого стейта рантайм дропает с логом, не CCE), переходы — чистые быстрые функции (Transition), вся асинхронщина — декларации (Command → интент, Subscription — функция от стейта), one-shot к UI — Effect-данные, исполняемые в композиции против типизированных MelEffectContext.

• DI: только constructor injection. Нет multibinding-карт, ключей, модулей — нечего упрощать. В пилоте зависимости передаются руками; в боевом коде — @AssistedInject + typed routes (§4.4).
• Без is: все связи — типизированные регистрации (on<Стейт, Интент>, subscribe<Стейт>, view<Стейт>, on<Эффект>); смарт-кастов нет. Полноту стережёт melGraphAssert по sealed-листьям (тест) + fail-fast в debug + detekt-правило MelNoTypeChecks.
• Рантайм: один последовательный цикл (Channel(UNLIMITED) + единственный consumer — гонки интентов исчезают по построению), эффекты буферизуются (не теряются), ошибки — обычные интенты (onError; механики errorHandler нет), подписки живут ровно в тех стейтах, где объявлены (дифф по ключам), есть стек состояний (push/pop/popTo) для внутриэкранных оверлеев.
• Compose: MelScreen { content{…}; effects{…}; transitions{…} } — builder с дефолтами; MelContent = AnimatedContent + оверлеи + SaveableStateHolder; MelEffectHost = буфер + repeatOnLifecycle(STARTED).
• Готово к использованию: ядро, тест-набор (:core:mel-test), 8 detekt-правил (:tools:detekt-rules), публикация в Nexus, пилот qr-sign. Тесты: :core:mel — 27, :core:mel-test — 29, detekt — 41, пилот — 18.

2. Уроки v3/simplemvi → принципы MEL

Каждый принцип — ответ на конкретную боль зоопарка MVI sbbol (v3: 44 модели, 897 ручных биндингов; SimpleMvi: 241 файл в ~30 фичах):

3. Словарь имён → типы в коде

Правило словаря: знакомые слова сохраняют смысл, новые имена — только у новой семантики.

Код разложен по подпакетам ru.mel.core.mel.* — слои без циклов: contract · effect · transition · log → graph → machine → runtime → compose.

Правило префикса Mel. Пакет снимает неоднозначность для компилятора; префикс — узнаваемость и отсутствие коллизий у потребителя и в плоском контексте, где пакета не видно (наследование, лог, трейс, автокомплит). Поэтому Mel несут: (1) маркеры контрактов, которые реализует код экрана — MelState, MelIntent, MelEffect, MelFacts, MelPopRequest, capability-маркеры Mel…Effect; (2) публичная поверхность — MelMachine, MelViewModel/MelModel, MelScreen, MelOps, MelConfig, MelEffectContext, MelRouter, MelInterceptor, MelRuntime, MelLog, готовые эффекты (терминальный MelExhausted, маркер MelCloseEffect). Без префикса — внутренний словарь DSL, namespace'нутый пакетом: Graph, Cell, ActiveClause, Subscription, ReduceScope, Command, Transition, MelStart, StackOp, Section, типизированные ключи CommandKey/SubscriptionKey. Третий столбец — пакет/файл в :core:mel.

4. Ядро: контракт и рантайм

4.1 Контракт (:core:mel, ~десяток небольших файлов)

Машина и секции делят общую базу билдеров MelOps — клетки строят Transition одним словарём:

// MelMachine.kt — определение экрана (S:MelState, I:MelIntent, E:MelEffect — маркеры контрактов)
abstract class MelMachine<S : MelState, I : MelIntent, E : MelEffect> : MelOps<S, I, E>() {

    /** Рождение машины (§4.4). Аргументы уже в конструкторе. Возвращает узкий тип MelStart
        (val to:S + effects/command/cancel), а не Transition: рождение кладёт первый стейт
        в пустой стек, поэтому стековая операция тут лишь одна — startNext(to, …). */
    abstract fun start(): MelStart<S, E>

    /** Граф: ВСЕ связи экрана — типизированные регистрации, без is/смарт-кастов. */
    abstract val graph: Graph<S, I, E>

    /** Декларации поведения интентов: debounce, интерсепторы — типами, не строками. */
    open val config: MelConfig = MelConfig.EMPTY
}

// ReduceScope.kt — словарь переходов (interface, общий receiver клетки/start/графа).
//   MelOps : ReduceScope (билдеры override), GraphBuilder : ReduceScope; Cell.reduce
//   получает receiver ReduceScope, так что s,i -> next(…) одинаков в машине, секции и тесте.
//   Ключи команд/подписок — типизированные value class: CommandKey/SubscriptionKey (§4.1).
fun next(to: S, vararg effects: E, command: Command<I>? = null, cancel: Set<CommandKey> = emptySet()): Transition<S, E>
fun stay(vararg effects: E, command: Command<I>? = null, cancel: Set<CommandKey> = emptySet()): Transition<S, E>
fun push(to: S, vararg effects: E, command: Command<I>? = null, cancel: Set<CommandKey> = emptySet()): Transition<S, E>
fun pop(vararg effects: E, command: Command<I>? = null, cancel: Set<CommandKey> = emptySet()): Transition<S, E>
fun popTo(target: Class<out S>, vararg effects: E, command: Command<I>? = null, cancel: Set<CommandKey> = emptySet()): Transition<S, E>
inline fun <reified T : S> popTo(vararg effects: E, command: Command<I>? = null, cancel: Set<CommandKey> = emptySet()): Transition<S, E>

/** Асинхронная работа: suspend-блок → финальный интент; ошибка — тоже интент (onError).
    Дубль key = replace. Механики errorHandler нет. */
fun command(key: CommandKey? = null, onError: (Throwable) -> I, block: suspend () -> I): Command<I>

/** Команда с прогрессом: промежуточные эмиссии + ОБЯЗАТЕЛЬНЫЙ финал (возврат блока).
    Отдельное имя, а не перегрузка command — чтобы трейлинг-лямбда без параметров
    не давала неоднозначность перегрузок. */
fun commandWithProgress(key: CommandKey? = null, onError: (Throwable) -> I,
    block: suspend (emit: suspend (I) -> Unit) -> I): Command<I>

// MelOps.kt — реализация ReduceScope (база машины и секции) + узкий билдер рождения:
//   startNext(to, …): MelStart — отдельный узкий тип старта, НЕ Transition (§4.4).
protected fun startNext(to: S, vararg effects: E, command: Command<I>? = null,
    cancel: Set<CommandKey> = emptySet()): MelStart<S, E>

Граф — обычное значение со списком регистраций; собирается DSL-ом graph { … }. Дубли клеток и ключей подписок — ошибка сборки с именами секций (require в GraphBuilder):

class GraphBuilder<S : MelState, I : MelIntent, E : MelEffect> : ReduceScope<S, I, E> {
    /** Клетка: (стейт, интент или sealed-группа) → обработчик. reduce — на receiver-е
        ReduceScope (билдеры next/stay/… доступны как s,i -> next(…)). on СТРОГ: II : I —
        только свои интенты экрана (чужой интент/опечатка = ошибка компиляции). Сквозные типы
        (MelPopRequest, напр. MelBack), не подклассы контракта экрана, перехватывает onAny (II : MelIntent). */
    inline fun <reified SS : S, reified II : I> on(reduce: ReduceScope<S, I, E>.(SS, II) -> Transition<S, E>)
    inline fun <reified II : MelIntent> onAny(reduce: ReduceScope<S, I, E>.(S, II) -> Transition<S, E>)   // сквозные (Back и т.п.)

    /** Клауза скоупа подписки (§7.2): стейт + типизированный предикат именно на этот стейт.
        Конструируется reified active<SS> { … }; имя 'active' (не 'on') — чтобы не сталкиваться
        с регистрацией клеток. Дефолт предиката — { true }. */
    inline fun <reified SS : S> active(predicate: (SS) -> Boolean = { true }): ActiveClause<S>

    /** Подписка со стейт-скоупом: живёт, пока в стеке есть запись, подходящая под одну из
        клауз (стейт клаузы И её предикат==true). Единый subscribe без арности — скоуп задают
        vararg-клаузы active<…>(); ≥1 клауза ОБЯЗАТЕЛЬНА (пустой скоуп = мёртвая подписка =
        ошибка сборки). onError обязателен для падающих источников (без него —
        debug-краш / бэкофф в release). Дубль ключа — ошибка сборки. */
    fun subscribe(key: SubscriptionKey, vararg clauses: ActiveClause<S>,
        onError: ((Throwable) -> I)? = null, source: () -> Flow<I>)

    fun include(section: Section<S, I, E>)   // секция приносит свои клетки и подписки
}

Результат клетки — Transition(op, effects, command, cancel), где op — sealed StackOp: Next(to) · Push(to) · Pop · PopTo(target) · Stay. Прямой assertEquals упирается в лямбду внутри Command — для тестов клеток есть assert-DSL в :core:mel-test (§8).

Прогрессная команда (форма для загрузки вложения / пакетного подписания «12 из 50»). Правило выбора против подписки: команда конечна и рождена переходом; подписка бесконечна и выведена из стейта:

on<Editing, AttachFile> { s, i -> next(
    s.copy(upload = UploadFacts(i.uri, progress = 0f)),
    command = commandWithProgress(key = CommandKey("upload"), onError = ::UploadFailed) { emit ->
        files.upload(i.uri).collect { p -> emit(UploadProgress(p)) }
        UploadDone(files.result())                               // обязательный финал
    },
)}
on<Editing, CancelUpload> { s, _ -> next(s.copy(upload = null), cancel = setOf(CommandKey("upload"))) }  // отмена — клетка

4.2 Рантайм (MelViewModel, один на все экраны)

• Последовательный цикл: Channel<MelIntent>(UNLIMITED) + единственный consumer в viewModelScope.launch(loopDispatcher). Интенты обрабатываются строго по одному — класс гонок v3 не существует; Mutex не нужен. Канал типизирован MelIntent (объединение I ∪ MelBack): несёт и интенты экрана, и сквозные типы (интеграционный MelBack : MelPopRequest : MelIntent). Публичный вход — MelModel.send(intent: I) (строго типизирован экраном); тонкий MelModel.pop() кладёт в тот же канал MelBack для BackHandler (§4.7) — отдельного нетипизированного входа нет.
• Эффект-канал и поверхность effects: Flow<E>: публичный поток эффектов типизирован E экрана и честен — несёт только эффекты экрана, никаких unchecked-каст. Внутри это effectChannel: Channel<E>. Ядровой терминал MelExhausted идёт отдельным внутренним потоком MelViewModel.coreEffects: Flow<MelCommonEffect> (internal, не часть MelModel). Мерджит его единственный потребитель — MelEffectHost: merge(model.effects, coreEffects) на границе общего супертипа MelEffect (дефолт-хендлеры фильтруют по классу маркера). Так публичный effects: Flow<E> остаётся типобезопасным для любого коллектора с конкретным E (раньше подмешивание MelExhausted через map { it as E } рвало такой коллектор CCE). Отдельного публичного host-канала нет (мост host/child — будущий дизайн, §4.3/§11).
• Тредовая модель: цикл (клетки, дифф подписок, интерсепторы) — на loopDispatcher (по умолчанию Dispatchers.Default; в тестах — StandardTestDispatcher, цикл детерминирован). Стейт — StateFlow, UI собирает на Main. Следствие: клетки обязаны быть быстрыми — тяжёлое в командах (они конкурентны), не в переходах.
• Маршрутизация (стек, §7): скан стека с вершины вниз, выигрывает первая запись с клеткой (Graph.findCell — единый источник истины «наиболее специфичной клетки»: лист интента → его sealed-группа → onAny, lookup по Class). Вершина применяет переход полностью; фоновая запись может только обновлять себя (stay/next своего индекса) — стековая операция из фона = violation. Интент без клетки — drop + структурный лог + onDropped интерсептору, не CCE.
• Эффекты (доставка): оба канала эффектов — UNLIMITED, UI собирает их объединённый effects в repeatOnLifecycle(STARTED) через MelEffectHost. Буферизуются без подписчика — доставка гарантирована (закрывает «эффект до подписчика теряется» и гонку холодного старта qr-сканера).
• Команды: конкурентны, живут до завершения в скоупе модели — переход их не убивает, результат долетит. Дубль ключа = replace (работающая отменяется до запуска новой); cancel-набор перехода отменяет команды по ключу до запуска команды этого же перехода.
• Подписки (§7.2): дифф по ключам после рождения и каждого не-stay перехода; желаемый набор — union по всему стеку. Ключ остался — не трогать; выпал — отмена; появился — запуск. Источник без onError при падении — лог + переподписка с бэкоффом (1с → ×2 → потолок 30с), в debug-режиме строгости (failFast) — краш.
• Ошибки (§4.2): исключение в команде → её onError-интент; в источнике подписки → её onError или бэкофф; в reduce — программная ошибка (переходы чистые, IO запрещён конвенцией) → краш в debug, лог + поведение stay в release. Режим строгости — MelRuntime.failFast (приложение включает в debug).

4.3 Композиция машин: мост host/child design

Мульти-модельные хосты (в auth 8 экранов в одном компоненте) — реальный кейс. В MEL машины изолированы, поэтому связь — явный мост: хост владеет дочерними машинами и видит их эффекты; ребёнок о хосте не знает, помечает часть эффектов маркером «адресовано выше» (маркер вводится вместе с мостом). Ни маркера, ни рантайма моста (bridge(child){…}) в core пока нет — это первый открытый вопрос пилота мульти-модельного экрана (§11). Пока внутриэкранные подсостояния решаются стеком (§7.3), а межэкранные — эффектом + роутером (§7.4); ни то, ни другое моста не требует.

4.4 Аргументы экрана и старт машины

Аргументы — параметры рождения машины, а не интенты. В v3 экраны слали себе при старте 12 интентов Args.* (New, ExistingById…) каналом событий с гонками cold-start — из-за DI-ограничения ViewModel-карты. В MEL причина не существует: машина создаётся фабрикой, аргументы лежат в конструкторе к моменту start().

// пилот qr-sign: аргумент — типизированные данные (бывший интент FromOperation)
data class QrSignArgs(val operationId: String)

class QrSignMachine(
    private val args: QrSignArgs,                // в сэмпле — руками; в проекте @AssistedInject
    private val interactor: IQrSignInteractor,
    private val docUpdates: IQrDocUpdates,
) : MelMachine<QrSignState, QrSignIntent, QrSignEffect>() {

    // рождение = первый переход: стартовый стейт Loading + команда загрузки от args.
    // startNext(...) возвращает MelStart — узкий тип старта (§4.1), а не Transition.
    override fun start() = startNext(Loading, command = loadCommand())
}

• Источники аргументов сводятся к одному типу: Bundle фрагмента, backStackEntry.toRoute<Screen.X>() в NavHost, диплинк. Обвязка экрана достаёт typed args и отдаёт фабрике.
• Рождение vs изменение: новые аргументы живому экрану (singleTop, повторный диплинк) — это событие → интент ArgsChanged(newArgs) с обычной клеткой.
• Тест старта: в пилоте — QrSignMachineTest: machine.start().toTransition().assert { to<Loading>(); command() } — как любая клетка (MelStart.toTransition() разворачивает рождение в Transition для общего assert-DSL).
• В проекте — @AssistedInject (Dagger поддерживает официально): @Assisted args в конструктор машины + @AssistedFactory; ViewModel создаёт машину через фабрику. В сэмпле обходимся ручной передачей — DI-обвязка ортогональна ядру.

4.5 Compose-слой

Связка «однонаправленная машина + Compose» требует сознательных решений — иначе Compose используется как XML с перерисовкой всего экрана. MEL закладывает их в ядро:

Гранулярная рекомпозиция — из стабильности контрактов

Машина эмитит новый стейт целиком, но Compose скипает поддеревья при структурном равенстве стабильных параметров. Фасетная структура стейта — это и есть skip-механика: смена isReloading не рекомпозирует реквизиты, потому что фасет doc (QrDocFacts) не изменился. Требования: стейты и фасеты — @Immutable-data class'ы, коллекции — immutable, strong skipping (дефолт Kotlin 2.0+). Дисциплину держит detekt-правило MelImmutableFacts (запрет var/мутабельных коллекций/MutableState в классе с маркером MelState/MelFacts).

Анимации переходов — типизированно, в том же стиле регистраций

MelContent — это AnimatedContent под капотом. Дефолт — Crossfade по классу вершины (melCrossfade); точечно — типизированные пары, без is:

transitions {
    between<Loading, Content>(melFadeThrough)   // готовые трансформы в Transitions.kt
    between<Editing, Signing>(melSlideUp)       // push пуллера — выезд снизу
}

• pop() не убивает вью мгновенно — exit-анимация доигрывает на уходящем стейте. Оверлеи (overlay<S>) появляются и уходят снизу через AnimatedVisibility с MutableTransitionState, переживающим pop (MelOverlays в compose/MelContent.kt).

Suspend-хендлеры эффектов и превью

• Хендлеры в effects{} — suspend; каждый исполняется в своей корутине (скоуп STARTED), поэтому долгий suspend-хендлер (снек/диалог) не паркует очередь эффектов — навигация/закрытие за ним не ждут: on<NavigateToPayment> { e, context -> … } — нативная стыковка с suspend-API Compose. Бесплатное следствие — диалог-подтверждение: эффект показывает suspend-диалог, результат возвращается интентом.
• Превью — следствие «вью = функция от стейта»: в пилоте ContentPreview/ConfirmPreview/StubPreview — @Composable от голого стейта (QrSignContentView(Content(previewDoc), send = {})), без модели, DI и моков.

4.6 Process death и rememberSaveable

Дефолт честный: process death = перерождение. start() детерминирован, args восстановлены — машина заново грузится. Это сегодняшнее поведение всего зоопарка, и для списков/деталок оно правильное. MelContent оборачивает каждую запись стека в SaveableStateHolder с ключом записи: push не убивает remember-состояние подложки, а ушедшая из стека запись чистится из holder'а (повторный push того же типа не воскрешает UI-мелочь). Opt-in снапшот черновика (snapshot-блок, capture-в-момент-save, restored как вторые args) спроектирован, но не реализован — нужен экрану вроде payorder с набитой полформой; в пилоте qr-sign черновика нет.

4.7 DX-пакет: дефолты как builder

Архитектура масштабируется вниз хуже, чем вверх. Лечится пакетом дефолтов, оформленных единым builder-ом MelScreen: всё опционально, кроме контента; дефолт действует, пока блок не объявлен; переопределение — видимая строчка в ревью.

@Composable
fun QrSignScreen(model: MelModel<QrSignState, QrSignIntent, QrSignEffect>, router: MelRouter) {
    val snackbar = remember { SnackbarHostState() }            // snackbar — инструмент ЭТОГО экрана, не core
    Box(Modifier.fillMaxSize()) {
        // context = ::MelSnackContext (база-роутер + snackbar-host) из :core:mel-compose-material (§5 п.1)
        MelScreen(model, router, context = { MelSnackContext(it.router, snackbar) }) {
            content {                                          // единственный обязательный блок
                view<Loading> { QrSignShimmer() }
                view<Content> { s -> QrSignContentView(s, model::send) }
                overlay<Confirm> { s -> QrSignConfirmView(s, model::send) }   // оверлей поверх живого Content
                view<Stub> { s -> QrSignStubView(s, model::send) }
            }
            effects {                                          // закрытие — у дефолта; снек/навигация — тут
                on<QrSignEffect.ShowSnack> { e, context -> context.snackbar.showSnackbar(e.text) }
                on<QrSignEffect.NavigateToPayment> { e, context -> /* роутер */ }
            }
            transitions { between<Loading, Content>(melFadeThrough) }  // точечно поверх Crossfade
        }
        SnackbarHost(snackbar, Modifier.align(Alignment.BottomCenter))
    }
}

// модель — фабрикой из машины, без per-screen MelViewModel-подкласса (§6.5). Новый key = новая
// машина (новый start()). Per-screen VM остаётся допустимым, но не обязателен.
val model = melViewModel(key = "qr-sign-$session") { QrSignMachine(args, interactor, docUpdates) }

// тривиальный экран — это ВЕСЬ его UI-код (паритет с SimpleMvi по церемонии):
@Composable
fun TechBreakScreen(model: MelModel<…>) = MelScreen(model) {
    content { view<Content> { s -> TechBreakContent(s, model::send) } }
}

5. Правила контракта экрана

1. Факты — в стейте, инструменты — в MelEffectContext. Тест: «есть equals по значению / нужно клетке / проверяется в юнит-тесте» → стейт; «объект с методами show()/dismiss()» → контекст. Никаких MutableState-флагов в контексте (detekt MelNoMutableEffectContext); никаких инструментов (TextFieldState, пейджеры) в стейте (detekt MelNoInstrumentsInState). Контекст эффект-слоя получает только эффект-хендлер; вью инструментов не видят (вью = чистая функция стейта, state→intent). Базовый MelEffectContext несёт только роутер; готовое material-расширение со снек-хостом — MelSnackContext(router, snackbar) в отдельном модуле :core:mel-compose-material (чтобы material3 не утекал в ядро :core:mel); на экране context = { MelSnackContext(it.router, snackbar) }, а хендлеры снека/ошибки идут против context.snackbar (§4.7).
2. Стейт = «перезапустить жизненный цикл», поле = «факт внутри него». Смена стейта пересоздаёт вью и пересчитывает подписки; то, что должно пережить (рефреш-шиммер, лоадер), — поля текущего стейта (isReloading, isSigning).
3. Интенты — sealed-группами на стейт (ContentIntent : QrSignIntent), внутри — подгруппы по секциям. Сквозные (Back) — сквозной тип интеграции (MelBack : MelPopRequest) через onAny/дефолт.
4. Эффекты — данные. Лямбды с захватом инструментов (v3 UseSnackbar { … }) запрещены (detekt MelEffectsAreData): исполнение — только в композиции, регистрациями on<Эффект> в effects{}.
5. Результаты и ошибки команд — интенты с именами-фактами (Loaded, SignFailed) — они такие же клетки машины, как клики.
6. Никаких is/as по стейтам, интентам и эффектам в коде экранов (detekt MelNoTypeChecks). Любая связь — типизированная регистрация. Цена зафиксирована честно: exhaustiveness переезжает от компилятора к тесту (melGraphAssert) и debug-fail-fast; взамен — один стиль диспатча на весь фреймворк и отсутствие смарт-каст-простыней.

6. Пилот: экран qr-sign

Пилот в :sample:migration/qrsign/ — порт реального sbbol-экрана подписания по QR (payorder/.../qr_sign: QRSignMviModel + QRSignComponent с ~9 редьюсерами и Dagger-картой биндингов, DebounceMutator, эффекты ShowLoader/ShowShimmering). Здесь — один класс-машина + секция, без is/as и без карт. Экран средней сложности специально: реальная подписка, оверлей-пуллер и фоновая маршрутизация — чтобы проверить ядро в бою.

6.1 Стейты: владеют фактами

sealed interface QrSignState : MelState {

    data object Loading : QrSignState                  // стартовый шиммер из start(); args уже в машине

    data class Content(                                 // документ показан
        val doc: QrDocFacts,                           // фасет фактов (QrDocFacts : MelFacts)
        val isReloading: Boolean = false,              // бывший ShowShimmeringEffect — факт, не эффект
    ) : QrSignState

    data class Confirm(                                 // ОВЕРЛЕЙ-пуллер поверх Content (push, §7.3)
        val doc: QrDocFacts,
        val isSigning: Boolean = false,                // бывший ShowLoaderEffect — факт; гаснет по построению
    ) : QrSignState

    data class Stub(val message: String) : QrSignState // тупик с кнопкой повтора
}

6.2 Интенты: привязаны к стейтам, sealed-группами

sealed interface QrSignIntent : MelIntent {
    sealed interface LoadingIntent : QrSignIntent {
        data class Loaded(val doc: QrDocFacts) : LoadingIntent
        data class LoadFailed(val message: String) : LoadingIntent
    }
    sealed interface ContentIntent : QrSignIntent {
        data object SignClick : ContentIntent           // открыть пуллер
        data object Rescan : ContentIntent              // перечитать (дебаунсится в config)
        data class Rescanned(val doc: QrDocFacts) : ContentIntent
        data class RescanFailed(val message: String) : ContentIntent
        data class DocUpdated(val doc: QrDocFacts) : ContentIntent    // эмиссия подписки docUpdates (фоновая)
        data class UpdatesBroken(val message: String) : ContentIntent // onError подписки
        data object GoToPayment : ContentIntent
        data object CloseClick : ContentIntent
    }
    sealed interface ConfirmIntent : QrSignIntent {
        data object ConfirmSign : ConfirmIntent
        data object CancelSign : ConfirmIntent
        data class Signed(val doc: QrDocFacts) : ConfirmIntent
        data class SignFailed(val message: String) : ConfirmIntent
    }
    sealed interface StubIntent : QrSignIntent { data object Retry : StubIntent }
}
// Back в контракт НЕ входит: интеграционный MelBack : MelPopRequest, дефолт pop()/MelExhausted

6.3 Машина: тонкий граф + секция

override fun start() = startNext(Loading, command = loadCommand())            // MelStart, не Transition (§4.1)

override val graph = graph<QrSignState, QrSignIntent, QrSignEffect> {
    on<Loading, Loaded>     { _, i -> next(Content(i.doc)) }
    on<Loading, LoadFailed> { _, i -> next(Stub(i.message)) }
    on<Stub, Retry>         { _, _ -> next(Loading, command = loadCommand()) }  // повтор = путь рождения

    on<Content, SignClick> { s, _ -> push(Confirm(s.doc)) }                     // пуллер: Content жив в стеке
    on<Content, Rescan>    { s, _ -> next(s.copy(isReloading = true),
        command = command(key = CommandKey("load"), onError = { RescanFailed(it.userMessage()) }) {
            Rescanned(interactor.getDocument(args.operationId))
        }) }
    on<Content, Rescanned>   { s, i -> next(s.copy(doc = i.doc, isReloading = false)) }
    on<Content, RescanFailed>{ s, i -> next(s.copy(isReloading = false), ShowError(i.message)) }
    on<Content, DocUpdated>  { s, i -> next(s.copy(doc = i.doc)) }              // фоновая маршрутизация (§7.3)
    on<Content, UpdatesBroken>{ s, i -> stay(ShowError(i.message)) }
    on<Content, GoToPayment> { s, _ -> stay(NavigateToPayment(s.doc.id)) }     // навигация — данные (§7.4)
    on<Content, CloseClick>  { _, _ -> stay(Close) }

    include(SignSection(interactor))                                          // клетки Confirm — в секции

    // подписка со скоупом из ДВУХ стейтов (§7.2): обновления нужны и в Content, и под пуллером Confirm,
    // поэтому push(Confirm) её не рвёт. Скоуп — vararg-клаузы active<…>() (per-state DSL).
    subscribe(SubscriptionKey("docUpdates"), active<Content>(), active<Confirm>(),
        onError = { UpdatesBroken(it.userMessage()) }) {
        docUpdates.flow(args.operationId).map(ContentIntent::DocUpdated)
    }
}

override val config = config { debounce<ContentIntent.Rescan>(500.milliseconds) }  // типом, не строкой

6.4 Секция — клетки одной зоны ответственности

class SignSection(private val interactor: IQrSignInteractor) :
    Section<QrSignState, QrSignIntent, QrSignEffect>() {

    override fun GraphBuilder<…>.register() {
        on<Confirm, ConfirmSign>(::confirmSign)
        on<Confirm, CancelSign> { _, _ -> pop() }
        on<Confirm, Signed>     { _, _ -> pop(ShowSnack("Документ подписан")) }  // этап завершён — закрываем пуллер;
                                                                              // подписанный документ долетит до Content подпиской
        on<Confirm, SignFailed> { s, i -> next(s.copy(isSigning = false), ShowError(i.message)) }
    }

    private fun confirmSign(state: Confirm, intent: ConfirmSign) =
        if (state.isSigning) stay()                          // дабл-клик — клетка машины, не DebounceMutator
        else next(
            state.copy(isSigning = true),                    // бывший ShowLoaderEffect — факт
            command = command(key = CommandKey("sign"), onError = { SignFailed(it.userMessage()) }) {
                Signed(interactor.sign(state.doc))
            },
        )
}

6.5 Что показывает пилот: фоновая маршрутизация

Главная демонстрация — интент фоновой подписки долетает к записи под вершиной стека. Сценарий подписи:

[Content]            подписка docUpdates запущена (скоуп Content+Confirm)
[Content, Confirm]   SignClick → push: Content жив, подписка не дёргалась
                     ConfirmSign → isSigning=true + команда sign
                     ... interactor.sign() эмитит подписанный документ в шину docUpdates ДО возврата ...
[Content, Confirm]   Signed (финал команды) → pop(ShowSnack) — закрываем пуллер
[Content]            на записи Content уже / вот-вот применится DocUpdated(signed) фоновой подпиской

Порядок Signed / DocUpdated не важен: pop() возвращает к живому Content, чьи факты актуализирует фоновый интент (клетка on<Content, DocUpdated> применяется к записи под пуллером — StackOp.Next по своему индексу, §7.3), а не к замороженному снапшоту. Итог детерминирован — Content(signed). Кнопка сэмпла «Эмулировать пуш» шлёт обновление в шину снаружи экрана — экран узнаёт о нём той же подпиской, демонстрируя живой скоуп. Всё это покрыто табличным тестом QrSignMachineTest (§8).

Создание модели — фабрикой melViewModel. Рантайм-фасад экрана — MelModel<S, I, E> (stack/state/effects + send(I)/pop()), его реализует общий MelViewModel. Пилот не пишет per-screen подкласс ViewModel: @Composable melViewModel(key) { machine } (runtime/MelViewModelFactory.kt) поднимает модель прямо из машины через androidx-viewModel; новый key = новая машина (новый start(), как key("qr-sign-$session") в сэмпле). Без явного key дефолт выводится из типов S/I/E (иначе viewModel ключует по стёртому MelViewModel — одинаковому для всех экранов, и два melViewModel{} под одним стором вернули бы один инстанс); два инстанса ОДНОГО экрана различай явным ключом. Per-screen MelViewModel-подкласс остаётся допустимым (когда нужен свой конструктор/DI), но обязательным не является.

6.6 Секции: доктрина и переиспользование

Секция — составная часть графа: связный набор клеток (+ подписок), оформленный обычным @Inject-классом (Section<S, I, E>, наследник MelOps). Ось секции — зона ответственности, а не стейт. В пилоте SignSection накрывает Confirm; на большом экране у одного Editing было бы несколько секций (поля, получатель, действия). Машина делает include(section) — и всё.

Доктрина — три правила (зашиты в KDoc Section)

1. Секция владеет клетками, не стейтом. Форма стейта — собственность контракта экрана; секции читают и copy()-ят. Дубль клетки (стейт, интент) между секциями — ошибка сборки графа, сообщение называет обе секции.
2. Секции общаются через факты стейта, не через интенты друг другу. «Послать интент соседней секции» — возрождение v3-шных awaitState-цепочек; общая логика выносится в обычные функции, вызываемые из обеих клеток.
3. Подписки секции — её собственные: питают её же клетки. Коллизия ключей между секциями — та же ошибка сборки.

Когда секция не нужна: это инструмент организации, не обязательный слой. В пилоте Content-зона — клетки инлайн в машине, секция только у подписания. Эвристика: секция появляется, когда у зоны есть свои зависимости, больше ~5–7 клеток или нужна переиспользуемость (в sbbol SignPullerModule жил в 5 компонентах → одна секция, include в N машин). Градиент: инлайн-клетки → приватные методы машины → секция.

7. Подписки, стек состояний и навигация

7.1 Лестница времени жизни подписок

Дифф идёт по ключам, а не по классам стейтов: ключ, оставшийся в наборе после перехода, означает «не трогать». Подписка объявляется один раз со стейт-скоупом (повторный ключ — ошибка сборки). Ступени:

7.2 Стек состояний

Линейная машина упирается в контекстно-слепые промежуточные стейты. Ответ — стек состояний (StackOp в transition/Transition.kt, реализован в MelViewModel.applyOp):

next(to)          // replace вершины: стейт ЗАВЕРШЁН (поведение линейной машины)
push(to)          // поверх: нижний стейт ЖИВ — факты сохранены, подписки не трогаются
pop()             // вернуться к живому стейту, как он был (актуализированному фоновыми интентами)
popTo<Content>()  // аналог v3 backTo

Семантика (важнее API):

• Рендерится и принимает интенты вершина. Вью, зарегистрированная как overlay<S> (пуллер, диалог с собственным флоу), рисуется поверх ближайшей не-overlay записи стека: MelContent сканирует базу и рисует все оверлеи над ней.
• Подписка живёт, пока её стейт в стеке: рантайм диффит union ключей по всему стеку, не по вершине. [Content, Confirm] — docUpdates живёт, хотя на вершине Confirm.
• Интенты живых фоновых подписок маршрутизируются к своей записи стека (DocUpdated применяется к Content в глубине и обновляет его факты — на pop возвращаешься к актуальному состоянию). Ограничение, проверяемое рантаймом: фоновая запись может только обновлять себя (next/stay своего индекса); push/pop — только с вершины (иначе violation).
• Back из коробки: дефолт ядра для MelPopRequest — pop() пока стек глубже одного, иначе терминальный MelExhausted (нав-смысл — на высоте интеграции, преемник v3 BackStateReducer).

7.3 Навигация между экранами: край машины

Принцип: машина не знает о существовании других экранов. Наружу она отдаёт данные (Effect), внутрь получает данные (Intent). Межэкранный слой (фрагменты, NavController, IMainRouter, диплинки) MEL не трогает — он живёт за интерфейсом MelRouter в MelEffectContext. MEL стандартизирует только край экрана.

// эффекты навигации — данные, без роутера в машине
on<Content, GoToPayment> { s, _ -> stay(QrSignEffect.NavigateToPayment(s.doc.id)) }

// исполнение — в композиции; роутер — инструмент из контекста
effects { on<NavigateToPayment> { e, context -> context.router.toPayment(e.docId) } }

// ВОЗВРАТ результата — это вход, значит подписка → интент (как docUpdates в пилоте)
subscribe(SubscriptionKey("pickerResult"), active<Content>()) { savedStateHandle.getStateFlow(KEY, null).filterNotNull().map(::Selected) }

• «Навигация из фона» решена по построению: Effect-канал буферизован и собирается в repeatOnLifecycle(STARTED) — навигационный эффект от позднего результата команды дождётся возвращения экрана, не упадёт и не потеряется. Это паттерн, которым в sbbol уже починили гонку QR-сканера, — здесь он дефолт для всей навигации.
• v3/simplemvi ↔ MEL экраны смешиваются свободно: межэкранный слой общий, машина о соседях не знает. Критично для инкрементальной миграции.
• Back — иерархия: стек машины глубже дна → pop(). На дне BackHandler включён, только если у машины есть клетка на MelBack для текущей вершины (handlesBack) — машинно-владеемый root-back; иначе системный Back закрывает экран (NavHost/фрагменты). MelBack без своей клетки на дне → терминальный MelExhausted → закрытие интеграцией.
• Совместимость с Jetpack NavHost: destination навграфа = экран = своя машина; NavController — роутер в контексте. Граница «destination vs стек машины»: destination — то, что живёт самостоятельно (адресуемо, диплинк); стек машины — то, что неотделимо от экрана (флоу с его фактами).

8. Тестирование и дисциплина

Знание о машине собрано в значение Graph (список регистраций) — его инспектируют рантайм, тесты и debug-fail-fast. Это избавляет MEL от собственного KSP: генерировать нечего (карт и ключей нет), а тела функций KSP всё равно не видит.

• Клетки — чистые функции + assert-DSL (:core:mel-test, Transition.assert): прямой assertEquals упирается в лямбду внутри Command, поэтому переход сверяется по фактам — стейт предикатом, команда ключом, эффекты типами. Без корутин и моков фреймворка.
• Машина целиком — table-driven через Graph.reduce (тот же lookup, что в рантайме): список (стейт, интент) → ожидание; стейл-клетки проверяются «интент X в стейте Y не маршрутизируется».
• Полнота — melGraphAssert (главный страж после «без is»): перечисляет sealed-листья стейтов и интентов и сверяет с регистрациями — частично покрытая группа, мёртвый интент, пустой стейт; падает со списком всех дыр + дамп графа. Дубли клеток/ключей ловит сам GraphBuilder при сборке. Сознательные исключения — с обязательной причиной: terminal<Stub>(), allowUnhandled<…>("причина"), allowDead<…>("причина").
• Вью и эффект-хендлеры регистрируются в композиции — их полноту стережёт MelRuntime.violation (fail-fast в debug) при первом непокрытом стейте/эффекте + smoke-прогон экрана.

// пилот: assert-DSL клетки (TransitionAssert)
SignSection(interactor).confirmSign(Confirm(doc), ConfirmSign).assert {
    to<Confirm> { it.isSigning }
    command("sign")
    noEffects()
}

// пилот: страж полноты — проходит без единого исключения (граф закрыт по построению)
class QrSignGraphTest {
    @Test fun graph() = melGraphAssert(QrSignMachine(QrSignArgs("op-1"), interactor, docUpdates))
}

QrSignMachineTest — 17 табличных кейсов: рождение, каждая клетка Content/Confirm/Stub, гейт дабл-клика, фоновый DocUpdated под пуллером, стейл-интент чужого стейта. Плюс QrSignGraphTest. Итого по экосистеме MEL тестов: :core:mel — 27 (рантайм: цикл, команды, подписки, эффекты), :core:mel-test — 29 (сам граф-ассерт и DSL), :tools:detekt-rules — 41, пилот — 18.

8.1 Detekt-набор mel-* (:tools:detekt-rules)

8 правил дисциплины, подключены к экранным модулям (:sample:migration, :app). Все правила — PSI, без type resolution: IDE-плагин detekt не поддерживает type resolution для подсветки на лету (известное ограничение), поэтому от TR отказались — так все 8 правил работают и в Studio на лету, и в Gradle-таске. Контракты детектятся по маркерам (MelState/MelIntent/MelEffect/MelFacts из contract/Contracts.kt): хелпер идёт BFS по супертипам в пределах файла в поисках маркера — легаси *State/*Effect без маркера не трогается.

8.2 Инструменты графа реализовано

Собрано — модуль :tools:mel-graph + IDE-плагин :tools:mel-idea-plugin: статическая экстракция графа из PSI (MelGraphExtractor / headless-MelPsiWalker для CI); тул-виндоу «MEL» — каталог экранов слева (фильтр по модулю, поиск, скрытие тестовых) и живая диаграмма стейтов справа (собственный Java2D-рендер с layered-layout, без JCEF: узлы по ролям start/overlay/terminal, дашированные рёбра команд/pop, иконки подписок); навигация из узла/ребра/инспектора в исходник (OpenFileDescriptor по SourceRef); панель-инспектор узла (факты, подписки, локальные экшены, переходы — каждый ссылкой в код); экспорт Mermaid в буфер и PNG на диск. Граф несёт overlay-стейты, ключи команд и их результаты, дебаунс, подписки.

Golden-сверка статика↔рантайм собрана: MelGraphCrossCheckTest в пилоте сверяет граф PSI-уокера с настоящим QrSignMachine.graph, где рантайм — авторитет (статике расходиться нельзя) — это и закрывает риск «статический анализ соврал». Отдельного именованного MelDiagram.golden(…) нет: роль закрыта связкой MermaidEmitter + MelGraphCrossCheckTest.

Ещё не сделано design: code-инспекции с quick-fix в IDE (в plugin.xml только toolWindow; дисциплину держат detekt-правила §8.1, но «на лету» в редакторе их нет); вкладка миграции v3/SimpleMvi → MEL в плагине. Дверь к FIR-чекеру компилятора (видит тела регистраций) сознательно закрыта из-за цены поддержки — открывать, только если тест-таймовая полнота начнёт пропускать реальные баги.

9. Сосуществование, публикация, миграция

• Отдельный пакет. :core:mel + :core:mel-test ничем не пересекаются с существующими фреймворками: свой рантайм-VM, свои контракты. На одном хосте старые и новые экраны живут вместе (межэкранный слой общий, §7.3).
• Опубликовано как библиотека. Координаты ru.mel:core / ru.mel:test / ru.mel:detekt, версия 0.1.0, репозиторий Nexus maven-mixed. Конфиг публикации — общий скрипт gradle/mel-publishing.gradle.kts, применяется в 3 модулях. Развязка от sbbol-стаба: :core:mel не зависит от логгера приложения — у него свой подключаемый MelLog (MelLog.delegate = … одной строкой). Направление: распространять MEL артефактом, а не копированием исходников.
• Перенос старых экранов — по необходимости (когда экран всё равно переписывается), не кампанией. Default для новых экранов; legacy замораживается рэтчетом (MelMigrationRatchet).

9.1 Гайд переноса v3 → MEL

Главный вопрос к каждому v3-редьюсеру: «чем он был на самом деле?» В v3 редьюсер — единственный юнит, поэтому в нём смешаны вычисления, оркестрация IO и обработка ошибок. Таблица разложения:

9.2 Гайд переноса SimpleMvi → MEL

SimpleMvi (241 файл в ~30 фичах) — концептуальный младший брат MEL, перенос идейно проще, чем v3: та же триада <Intent, State, Effect> (интенты уже sealed), последовательная обработка, даже буферизованный эффект уже изобретён (setBufferedEffect).

10. Минусы и риски

11. Что реализовано и что осталось открытым

Итоговая карта зрелости — чтобы документ не выдавал желаемое за сделанное:

Решённые в дизайне вопросы (зафиксированы реализацией ядра): сериализация стека — стек не сохраняется, восстановление в базовый стейт (§4.6); имя пакета — core/mel, отстройка от нумерации MVI сознательная; команды с прогрессом — commandWithProgress с обязательным финалом + cancel(key) (§4.1); гонка close-vs-cancel — enqueue через trySend (§4.2).

Основание: исходная спека-драфт целевой архитектуры (sbbol mel-design.html, 2026-06-13) и её реализация в :core:mel (2026-06-14). Разборы болей — payorder (PayOrderComponent.kt: 205 биндингов, debounce-список UniqueUtils, интент UseLoader), mass-sign (screenState-мешок, ShowLoader/ShowShimmering-эффекты, рукописный errorHandler), QR-sign (гонка cold-start). Прецеденты архитектуры: The Elm Architecture (Cmd/Sub), The Composable Architecture (отмена эффектов по ключам, подписки от стейта), MVIKotlin/Orbit (каналы side effect).