Предположим, к движку приходит второй потребитель. Не воркер демо, а, скажем, IDE-расширение или встроенный учебный отладчик без Web Worker’а. Что из протокола статьи (2) он унесёт с собой? Сторожевой таймер ему не нужен — нет границы потоков. Очередь сообщений не нужна — обработчики живут в том же потоке. Но «флаг шага», «координация паузы», «события paused по нескольким причинам» — это всё ему понадобится. И он, не разобрав статью (2), переизобретёт всё это заново.

Эта статья — про то, что переизобретать координацию приходится не потому, что воркер «специальный», а потому, что в v6 у координации не было своего места в библиотеке. v7 это место создал — класс-компаньон DebugSession рядом с TuringMachine в том же пакете.

Что переизобрёл воркер

Перечитаем протокол из статьи (2) под новым углом. Четыре механизма:

1. idle/busy вокруг асинхронной приостановки в onIter — обвязка для сторожевого таймера.
2. Флаг stepRequested внутри воркера — модель «шага» как одноразового запроса.
3. Синтетическое событие paused по клику «Пауза» — обработка внешней команды паузы.
4. Поле intervalMs в resume — чтение скорости «в момент клика», не «в момент старта».

Разнесём их по принадлежности. Первый и четвёртый — про воркер: сторожевой таймер живёт на основном потоке потому, что у него есть граница между потоками; intervalMs приходит на каждом resume потому, что поле ввода интервала и движок разъехались по разным потокам. Второй и третий — про координацию: модель шага как одноразового события, перевод внешней команды паузы в стандартное событие. Web Worker’ы тут ни при чём — те же самые механизмы понадобились бы в любом отладчике, который переключает движок между паузой и исполнением.

Два механизма из четырёх — кандидаты на подъём из потребителя в библиотеку. Воркеру осталось бы тогда два: обвязка сторожевого таймера и проброс параметра скорости при возобновлении. Это уже не «переизобретение координации», а адаптер между двумя интерфейсами: между протоколом сообщений воркера и API сессии.

Где может жить координация

В v6 координацию можно было разместить в двух местах:

• На стороне потребителя. Каждый новый отладчик строит её заново. Пока потребитель один, выбор места для координации выглядит обоснованным: сравнить не с чем. Двое уже подсветили бы дублирование, трое — подтвердили бы паттерн.
• В хуках движка. Этот соблазн разобран в статье (2): расширение onStep до асинхронной сигнатуры (v6.2.0) склеивало наблюдение и координацию. Появление выделенного хука onIter (v6.4.0) решило задачу «где живёт приостановка», но не сняло принципиального ограничения: хук — это точка уведомления, а не машина состояний. У хука нет своего внутреннего состояния, лайфсайкла, методов управления — он отдаёт обработчику только текущий момент и ждёт его Promise. А координация — это именно машина состояний: «пауза при брейкпоинте → continue / step-in / step-over / step-out / stop». При этом для step-over и step-out момент следующей паузы определяется по глубине стека.

Третий вариант в v6 не появился, потому что вопрос не был ещё вынужденным. С двумя потребителями (или тремя, или N) ответ становится очевидным: координация живёт в соседнем классе при движке. Не вниз по графу зависимостей (в потребителе), не внутри самого класса движка (в виде ещё одного хука), а вбок — в классе-компаньоне на том же уровне библиотеки.

Побочное доказательство: в v7 TuringMachine.run() снова стал синхронным, возвращающим void — без колбэков. В v4 этот же метод стал асинхронным ради асинхронного хука паузы (onDebugBreak, в v5 переименованного в onPause). Подъём координации обнулил эту причину, и сигнатура вернулась в исходное состояние. Если бы движку самому нужна была асинхронность, после исчезновения onPause сигнатура не вернулась бы к прежней форме — а вернулась. Значит, async в run() поддерживался только ради этого хука, а не ради самой логики исполнения.

Чем обладает DebugSession

Класс лежит в packages/machine/src/classes/DebugSession.ts — там же, где TuringMachine. Конструируется напрямую — new DebugSession(machine, {initialState}). Движок про сессию ничего не знает; сессия знает про движок только через его публичный синхронный генератор runStepByStep плюс один пакет-приватный аксессор по символу MACHINE_STATE_INTERNAL, который сосед-модуль может прочитать, а публичный index.ts не реэкспортирует. Тот же паттерн пакет-приватной видимости через Symbol, что и STATE_INTERNAL (turing-machine-js#180) — даёт сессии доступ к снимку halt-стека на каждой итерации, не выпуская его наружу через публичный API.

Сессия слушает четыре события, каждое со своим договором о диспетчеризации:

• step — без ожидания Promise. Синхронный, горячий цикл наблюдения; Promise, возвращённый слушателем, не дожидается. Один-в-один контракт onStep из v6.
• iter — дожидается. Покадровая координация: приостановка между итерациями, синтез границы шага, всё, ради чего движку нужно дождаться слушателя. Один-в-один контракт onIter из статьи (2).
• pause — слушатели вызываются без ожидания Promise (как у step и halt: Promise, который вернул бы async-слушатель, не дожидается). Но после их вызова сама сессия блокируется на собственном внутреннем Promise — и пока этот Promise не разрешится, цикл #drive не дёрнет следующий шаг генератора. Разрешает этот Promise один из методов управления сессией: continue() / stepIn() / stepOver() / stepOut() / stop(). Все они по дизайну вызываются откуда-то снаружи — из клика в UI, из сообщения от основного потока (когда сессия живёт в воркере) или по таймеру.
• halt — без ожидания Promise. Терминальное событие сессии.

Управление сессией зеркалит подходы DevTools там, где это имеет смысл. pause() — внешний запрос паузы; срабатывает на before-стороне следующей итерации с cause: ’manual’. stepIn() — пауза на следующей итерации. stepOver() — пауза на следующей итерации с depth <= clickTimeDepth: фреймы, которые текущая итерация уложила в стек, доигрываются до возврата без остановки. stepOut() — пауза, когда глубина halt-стека упадёт ниже момента клика (depth < clickTimeDepth): текущая обёртка закончилась, управление перешло в её override. stepOut() из глубины 0 бросает исключение: «выйти не из чего» — это ошибка в коде потребителя, а не молчаливая no-op. setRunInterval(ms) — задаёт покадровую задержку между итерациями. stop() — терминал, сессия завершается. Сессия одноразовая: start() вызывается один раз; для повторного прогона — новая сессия.

Обнаружение брейкпоинтов тоже переехало. В v6 генератор runStepByStep сам решал, какая итерация «должна выстрелить» по state.debug. В v7 генератор отдаёт минимальное MachineState, а сессия через MACHINE_STATE_INTERNAL читает текущий символ ленты, проверяет его на попадание в фильтры before/after у state.debug с помощью matchFilter и сама диспетчеризует pause с cause: ’breakpoint’. У движкового генератора больше нет «отладочной» логики — он чистое исполнение. У сессии — все три причины паузы (breakpoint, step, manual) в одном описании PauseInfo { side, cause } с порядком приоритета breakpoint > step > manual, если несколько причин совпали на одной итерации.

Это и есть «координация как машина состояний», которая не помещалась в хук: внутреннее состояние (Promise паузы, который держит движок остановленным; активный режим step-in/over/out; зафиксированная при клике глубина halt-стека), методы управления, лайфсайкл — всё в одном объекте, у которого есть собственный конструктор и собственный метод start().

Что осталось в воркере

После подъёма координации воркер не оказался пустым. За что он отвечает теперь:

• Сама граница Web Worker’а — протокол сообщений, сэндбокс пользовательского кода, лайфсайкл запросов на сборку, прогон, шаг. Воркер — естественное место для этого слоя.
• Покадровая задержка, обёрнутая сообщениями idle/busy для сторожевого таймера WORKER_TIMEOUT_MS. У сессии для задержки между итерациями есть свой setRunInterval(ms). Но воркеру он не годится: эта задержка выполняется внутри #drive-цикла сессии, и обернуть её парой сообщений idle/busy снаружи невозможно — а без обвязки сторожевой таймер на основном потоке сработает на легитимной задержке как на зависании. Поэтому воркер реализует задержку в собственном обработчике события iter (которое сессия дожидается асинхронно): внутри обработчика пара сообщений idle и busy оборачивает await setTimeout(intervalMs) ровно там, где нужно.
• Хранение и обновление intervalMs. Семантика «withPause читается в момент клика» из статьи (2) никуда не делась — поле интервала в UI это UI-уровень. Воркер держит актуальное значение в своей локальной переменной и обновляет его на каждом сообщении resume от основного потока.
• Трансляция UI-кликов в методы сессии: клик «Пауза» → activeSession.pause(), клик «Шаг» → activeSession.stepIn(), клик «Продолжить» → activeSession.continue(). Воркер больше не синтезирует событие paused из onIter — все паузы (брейкпоинт, шаг, ручная) возвращаются через единственное событие pause сессии с дискриминантом cause.

Граница чистая. Осталось то, чем сессия не может владеть, не залезая на территорию потребителя. Ушло то, что воркер-специфичным никогда не было — это была координация, замаскированная под воркер-специфику. Другой потребитель — встроенный в IDE отладчик, DAP-сервер, учебная демонстрация без Worker’а — соберёт DebugSession иначе (без postMessage, без сторожевого таймера), но с тем же самым API сессии.

Подъём обобщается

PostMachine.debugRun() возвращает PostDebugSession, который оборачивает движковый DebugSession. Те же четыре события, те же методы шага, тот же лайфсайкл. Сверху — оборачивание MachineState в post-специфичные arrivalPath / candidatePaths и фильтрация по реестру брейкпоинтов PostMachine перед прокидыванием события pause наружу. Воркер демо обрабатывает обе сессии через структурный тип SessionLike — оба выглядят как одно и то же снаружи.

Это и есть компаньон-компаньона: паттерн обобщается на один уровень выше. Библиотека движка один раз поднимает координацию в свой класс-компаньон; следующая библиотека сверху поднимает свою специфику в свой класс-компаньон, оборачивающий движковый. Доказательство того, что «класс-компаньон» — не одноразовый трюк под одну библиотеку, а воспроизводимая форма.

Что из этого следует

В линейке статей про API движка вырисовываются три урока подряд:

• Из статьи (1): именование лайфсайкла фиксирует решения о форме API — назовите состояния правильно, и поверхность сама окажется в нужной форме.
• Из статьи (2): наблюдение и координация — разные задачи, и каждой нужен свой договор хука со своей семантикой диспетчеризации.
• Из этой статьи: когда N потребителей переизобретают одну и ту же координационную обвязку поверх ваших хуков, ваш хук-контракт не неполный — он на не той гранулярности. Координационная машина состояний — это сосед хуков, а не их расширение.

Диагностика для автора библиотеки: если приходится расширять сигнатуру хука, чтобы потребитель смог сделать ту работу, которая у него и так есть (мажор v6.2.0 из статьи (2)), — или если форма обработчика повторяется из потребителя в потребителя без существенных различий (тот случай, который и подтолкнул к этому рефакторингу), — значит, от хука просят то, чего хук в принципе сделать не может.

Для движка это вылилось в чёткую границу: публичный синхронный runStepByStep, его координационный компаньон DebugSession, и любой потребитель — воркер демо, DAP-сервер, in-process отладочная панель — пишет адаптер между своей точкой входа и API сессии, а не координационный слой заново.

Код: turing-machine-js (движок, v7 — DebugSession), post-machine-js (PostDebugSession) и machines-demo (воркер демо, переписанный вокруг сессии в PR #80).

И сразу захотелось регрессионный тест: прогнать машину через round-trip и проверить, что на выходе — та же машина. Вот на слове «та же» всё и завертелось.

Побайтово? Нет: id узлов — это runtime-id инстансов, и fromGraph назначает их заново. Той же структуры? Иногда да, иногда нет — смотря как устроена композиция. Так же себя ведёт? Это вообще другая проверка, графа она не касается.

Оказалось, «та же» — не один вопрос, а три, и на каждый отвечает своё API. Эти три ответа я добавлял в библиотеку годами, по одному, и долго не проговаривал себе, что это три отдельные границы, а не один растяжимый «equals». Объект, граф, поведение — три ипостаси одной машины, и в плоской машине они дают один и тот же ответ. Композиция — место, где ответы расходятся. Дальше — про то, что у движка для этого есть, где проходят границы и как v7 уложила две ипостаси из трёх в форму графа, оставив для третьей отдельную функцию equivalentOn.

Что у движка вообще есть?

Прежде чем разводить три ипостаси, нужен инвентарь.

В движке три слоя, на которые ложится вопрос «а та же ли машина?»:

Объекты времени исполнения. State — узел графа машины. У него есть имя, переходы (на каждый возможный символ ленты — следующее состояние, что писать, куда двигаться), и идентичность: два разных State — это два разных объекта, как бы ни выглядели их таблицы переходов.

Граф как сериализация. State.toGraph(state, tapeBlock) обходит достижимые состояния и возвращает Graph — обычные данные: узлы с именами и переходами, индексированные числовыми id. State.fromGraph(graph) принимает граф и собирает машину обратно: {start, tapeBlock, states}. Поверх графа — toMermaid(graph) и fromMermaid(text), отображение в синтаксис Mermaid flowchart и обратно. Парсер строгий: принимает только то, что эмиттер выпускает.

Поведенческая эквивалентность. equivalentOn(reference, candidate, cases) в utilities/equivalence.ts — запускает обе машины на тестовых лентах, сравнивает выходы и снимки на каждом шаге. Отдельный модуль, ничего не знает про граф.

Три слоя — три вопроса «те же ли?». Дальше — про то, как они расходятся.

Плоская машина: простой случай

У плоской машины — без композиции — все три ипостаси совпадают.

Объектно: один State равен другому, если это тот же экземпляр (===). Это базовая семантика JavaScript, ничего движок к ней не добавляет.

Графово: возьмите toGraph, прогоните через JSON туда-обратно, восстановив через fromGraph — полу́чите двойник с теми же именами и переходами. Совпадение не байт-в-байт, а с точностью до переименования id: id узлов — это runtime-id инстансов, и при пересборке через fromGraph они назначаются заново. В репозитории есть регрессионный тест на это (turing-machine-js#139). Проверяет не «выглядит так же», а «имеет ту же структуру».

Поведенчески: equivalentOn прогонит обе машины по тестовым лентам и подтвердит «да, отработали одинаково».

Простой случай. Все три ипостаси совпадают, потому что нет места, где они могли бы разойтись. Но место расхождения есть — композиция.

Композиция: где становится интересно

Композиция в движке выглядит так:

const wrapper = baseState.withOverriddenHaltState(overrideState);

Новое состояние-обёртка wrapper делегирует поиск переходов своему baseState, но подменяет halt-выход: вместо остановки машины — переход в overrideState.

Концептуально обёртка — это «выполнить базовое состояние как подпрограмму, на выходе перейти в overrideState». Имя композиции строится по правилу: для базы с именем A и оверрайда с именем B обёртка получает имя A(B). О том, как и почему именно это имя — отдельная статья «Семь стрел, 429 деревьев» (1).

Здесь начинают расходиться три ипостаси.

Объектно: обёртка и база — два разных State. wrapper !== baseState. Это следствие того, что withOverriddenHaltState возвращает новый экземпляр.

Графово: обёртка своих переходов не имеет. Они живут на базе. Если визуализировать граф, обёртка — это узел с делегированием, не с переходами.

Поведенчески: обёртка и база не эквивалентны. У них разный halt-выход. На любом входе трейс совпадает шаг в шаг вплоть до halt-выхода базы — и расходится ровно в этот момент.

Обёртка существует как самостоятельный объект ровно для того, чтобы хранить эту подмену. Дальше вопрос: как уложить её в граф, чтобы fromGraph сумел её восстановить?

Как композиция попадает в граф

Мне нужно было, чтобы граф сам нёс композицию, — это убивало двух зайцев. Во-первых, fromGraph восстанавливает машину прямо из структуры, а не угадывает композицию по runtime-подсказке. Во-вторых, граф остаётся читаемым: композиция видна на самой диаграмме, а не растворяется в плоском списке переходов. В v7 (turing-machine-js#180) обёртка эмитируется двумя узлами:

• Узел-обёртка — call-site без переходов, форма [[wrapper-name]], поле bareStateId указывает на базу.
• Узел базы — обычный узел с переходами, форма [baseState-name], помещённый внутрь Mermaid subgraph «callable subtree of NAME».

Целиком, на примере scanToX(eraseHere):

Этого достаточно, чтобы fromGraph восстановил обёртку по структуре: вот call-site, вот база, на которую он ссылается. Граф кодирует композицию, а не намекает на неё.

Под капотом (можно пропустить). Halt-выход каждого frame-а — отдельный узел isHaltMarker с id = -frameId; в рантайме он сворачивается в синглтон haltState, но на графе живёт отдельно, иначе вся машина «втягивается» в один halt-узел. Когда одна база достижима из нескольких обёрток, frame-ы считаются union-find по достижимости баз (подпись subgraph — «callable subtree of A» или «callable scope: A ∪ B»). Начало машины помечено служебным idle([idle]) с пунктирной enter-стрелкой — якорь, по которому парсер находит стартовое состояние. Метки переходов записаны по простому шаблону [reads] → [writes]/[moves] — по ячейке на ленту.

Та же машина после round-trip?

Для простой композиции — одна обёртка, одна база, дерево не пересекается с другими — round-trip воспроизводи́м с точностью до переименования id. Граф хранит узлы, имена, переходы; fromGraph собирает ту же машину обратно. Композитное имя scanToX(eraseHere) в граф попадает — это подпись узла-обёртки, — но fromGraph его не читает: композитное имя он пересобирает заново из базы и оверрайда, через единственное разрешённое место мутации имени, Symbol-accessor STATE_INTERNAL (turing-machine-js#180). Поэтому накопления имён не происходит: на каждой пересборке имя считается из структуры, а не наращивается поверх предыдущего. Ровно это и проверяет регрессионный тест на простые обёртки.

Ломается воспроизводимость на общей базе — когда один и тот же State служит базой сразу нескольким обёрткам. Не выдумка: в library-binary-numbers алгоритм minusOne устроен так, что invertNumber оказывается базой двух обёрток, внешней и внутренней (полный граф). Один объект, два call-site.

Структуру это не ломает: toGraph обходит достижимые состояния ровно раз, по id инстанса, поэтому общая база — это один узел, а две обёртки просто ссылаются на него двумя стрелками; fromGraph восстанавливает ровно один общий инстанс на обе обёртки. Сама общая база переживает round-trip. А вот воспроизводимость сериализации — нет: повторная пересборка может дать граф, который не сводится к исходному, даже если закрыть глаза на id.

Та же форма в миниатюре, на scanToX — одна база под двумя обёртками:

Под капотом (можно пропустить). Id узлов — это runtime-id инстансов, fromGraph назначает их заново. «Воспроизводимо» здесь значит: сериализовать, пересобрать, сериализовать снова и сравнить два графа, игнорируя сами значения id. У простой обёртки повторный toGraph даёт ту же раскладку с точностью до переименования. В случае с общей базой, например одной на две обёртки, id после пересборки могут идти в другом порядке, а узлы эмитируются отсортированными по id — раскладка съезжает, и закрытие глаз на id уже не помогает.

И вот тут граф перестаёт быть тем ответом, на который стоит опираться. Зато equivalentOn на обеих машинах даёт allAgree: true: по поведению — та же. Граница простая: воспроизводимость сериализации — только на простых обёртках, поведенческая эквивалентность — всегда.

Где живёт equivalentOn

equivalentOn(reference, candidate, cases) живёт в utilities/equivalence.ts. reference и candidate — это Runnable ({ state, getTapeBlock }), cases — массив тестовых входов; функция запускает обе машины, сравнивает выходы и снимки на каждом шаге и возвращает отчёт { results, allAgree }: пошаговые результаты плюс итоговое «да/нет» в allAgree.

Важно, что он не живёт в utilities/stateGraph.ts, где собраны toGraph/fromGraph. Это разные модули, разные слои библиотеки. equivalentOn ничего не знает про граф; ему всё равно, эмитируется ли обёртка как call-site или как один узел, в каких frame-ах живут переходы. Он смотрит только на наблюдаемое поведение.

Это и есть его роль. Когда воспроизводимость toGraph/fromGraph зыбка (общая база на две обёртки), equivalentOn отвечает на вопрос, который потребителю на самом деле нужен: «после восстановления — это та же машина по поведению?». Граф — это инструмент сериализации; поведение — это контракт.

Ловушка, в которую легко попасть: проверять тождество через === над State-инстансами. После пересборки это даёт false — fromGraph всегда создаёт свежие инстансы, — хотя поведение совпадает. Ложная регрессия на ровном месте. equivalentOn нужен ровно для того, чтобы такого не происходило, — но для этого надо знать, что он есть.

Теги: данные едут с графом, идентичность остаётся локальной

Маленькая, но симптоматичная добавка v7 — теги (turing-machine-js#186). У State появился API: state.tag('hot', 'subroutine-entry'), state.tags, state.untag(...). Теги — это строковые метки на инстансе. Нужны они инструментам поверх машины: toMermaid раскрашивает и группирует по ним узлы через classDef, а потребители вроде post-machine-js помечают ими точки входа подпрограмм. На семантику машины теги не влияют.

Что про них важно для трёх ипостасей:

• Поведенчески — не считаются. equivalentOn теги не смотрит. Машина с тегами и без них на одних и тех же переходах — поведенчески одна и та же.
• Графово — переживают round-trip. GraphNode.tags сериализуется; toMermaid эмитирует теги в подписи узла через <br> и как classDef для цветовой группировки в рендере; fromMermaid читает из подписи (<br> — источник истины, classDef декоративный).
• Объектно — локальны инстансу. Теги живут на конкретном State, не на базе. Две обёртки делят одну базу, но набор тегов у каждой — свой. Пометь одну — и вторая, и сама база останутся без тега.

Хорошая граница: данные, описывающие узел графа, едут с графом; идентичность инстанса остаётся локальной для конкретной сборки. Теги оказываются посередине: для поведения их нет (equivalentOn к ним слеп), но они долговечнее ===-идентичности — та обнуляется на каждой пересборке, а теги едут с графом и переживают round-trip.

Что я в итоге понял

Три ипостаси я не задумывал разом — они набрались по одной, и только задним числом стало видно, что это разные проекции одной сущности, не один растяжимый «equals».

Объектную JavaScript даёт бесплатно: === и instanceof работают сами. Поведенческую я получил почти даром — equivalentOn это просто прогон двух машин на тестах. А графовую пришлось проектировать: без неё fromGraph не восстановил бы из сериализованной машины ничего, и именно ради неё v7 уложила композицию в данные графа.

Две вещи дошли до меня поздно. Биективное именование композиций — не украшение, а условие: пока имена неоднозначны, граф теряет один из видов проверки на «те же» ещё до того, как fromGraph запустится. Об этой же неоднозначности — статья (1). И поведенческая эквивалентность должна жить отдельно от графа: equivalentOn ничего не знает про toGraph, и это правильно — потребителю чаще нужен поведенческий ответ, а не побайтовый round-trip.

А ещё теги подсказали простую проверку: что переживает round-trip — описывает узел графа, что не переживает — описывает конкретный инстанс. Добавляю поле — смотрю, в какую ипостась оно попадает: от этого зависит, в каком смысле оно делает две машины «теми же».

Код: turing-machine-js (движок с v7-графовыми утилитами). Интерактивное демо на demo.machines.mellonis.ru рисует машины через toMermaid и подсвечивает текущий переход.

Я говорю «машины», а на деле — два разных экземпляра State @turing-machine-js/machine, сконструированные по-разному, с разным поведением во время исполнения, и со строго одинаковым state.name. Это происходило в библиотеке, которую я разрабатываю в качестве хобби с 2019 года, и я этого не замечал семь лет.

Обнаружил случайно, начиная с задачи на чистку Mermaid-визуализации. Закончил — кардинальной переделкой того, как композиция состояний отражается в имени. И узнал, что за этой переделкой прячется число $C_7=429$.

С чего всё началось

Композиция в движке устроена одним примитивом: baseState.withOverrodeHaltState(overrideState). Возвращает копию baseState, у которой halt-переходы во время исполнения уходят в overrideState вместо реального halt’а. Дальше я буду называть baseState базовым состоянием, а возвращаемую копию — обёрткой над ним. Композиция через обёртку — единственный способ собрать большую машину из маленьких подпрограмм: каждая подпрограмма в идеале заканчивается halt, и каждый withOverrodeHaltState переопределяет, куда идти после, вместо того чтобы остановиться.

Имя у получившейся обёртки в старом API формировалось так:

state.#name = `${this.name}>${override.name}`;

То есть A.withOverrodeHaltState(B) называется A>B. Просто и наглядно: читается как «A, потом B».

Эта строка ушла в продакшен в 2019 году и с тех пор не менялась. Она просачивается в логи, сообщения об ошибках, тесты, которые сравнивают state.name, и в любой диагностический вывод, на который смотрит пользователь.

Поводом разобраться стала Mermaid-визуализация. Тикет turing-machine-js#138 ставил задачу убрать дублирование. До v7 toMermaid рендерил обёртку как отдельный узел, на котором повторял все переходы базового состояния — визуально это выглядело так, будто у обёртки своя жизнь. Но переходы у обёртки те же, что у базы — даже #symbolToDataMap тот же. Своё у неё другое — call-frame-семантика: на входе push override на halt-стек, на halt’е базы — pop. А по сути обёртка вносит сверх базы только одно: куда уходит halt.

Грубо говоря, это выглядело так:

A и A>B — два узла с буквально одинаковыми исходящими переходами в A1, плюс у обёртки появляется пунктирная стрелка onHalt в B. Читающий видит «два разных автомата», хотя на уровне поведения это один автомат с одной точкой расхождения — куда уходит halt.

Первая попытка исправить визуализацию выглядела разумно: обёртку отрисовать одним узлом, переходы взять с базы, override-halt — отдельной стрелкой:

Один узел A>B, переходы — те же, что у базы; override-halt — отдельной пунктирной стрелкой от halt’а в B. Чисто, компактно, без визуального шума. Почти сработало.

Почти сработало = сломалось

Возьмём minusOne из library-binary-numbers — он собирается через вложенные обёртки:

const minusOne = invertNumber
  .withOverrodeHaltState(
    plusOne
      .withOverrodeHaltState(
        invertNumber
          .withOverrodeHaltState(normalizeNumber),
      ),
  );

Получается имя invertNumber>plusOne>invertNumber>normalizeNumber — три разделителя > в реальном коде, к тому же одна база (invertNumber) встречается дважды. Если имя длиннее, его соблазнительно прочесть как «инструкцию обхода». Например, A>B>B>A>A>B>B>A (семь разделителей): каждая буква — база, в которую переходишь на halt’е предыдущей. Последовательность обхода баз должна совпасть с именем.

Только это самообман. Имя ни в каком формальном смысле не определяет последовательность обхода. Оно напоминает её. И только если конкретная цепочка собралась тем единственным образом, которым я её представлял, когда выбрал способ записи композиции в 2019-м.

Загвоздка

Возьмём имя поскромнее: A>B>A. Сколько способов его построить?

Минимум два:

// Конструкция 1
const c1 = A.withOverrodeHaltState(B.withOverrodeHaltState(A));

// Конструкция 2
const c2 = A.withOverrodeHaltState(B).withOverrodeHaltState(A);

В обоих случаях правило ${this.name}>${override.name} даёт одну и ту же строку — A>B>A. Но топология обёрток разная — каждая конструкция собирает своё бинарное дерево (внутренние узлы • — применения withOverrodeHaltState, листья — исходные State):

И поведение тоже разное:

• Конструкция 1 (A.wohs(B.wohs(A))): у A halt уходит в обёртку «B с halt’ом в A». При исполнении walk такой: A → B → A.
• Конструкция 2 (A.wohs(B).wohs(A)): обёртка «A с halt’ом в B» дальше обёрнута ещё раз — теперь halt уходит в A. При исполнении walk: A → A. Внутренний override B мёртв: на halt-стек попадает только override самой внешней .wohs()-операции.

Имя одинаковое. Просто потому, что плоский разделитель > не запоминает, где в дереве конструирования каждая стрелка стояла. А дерево там было.

Потерянное дерево

Композиция через withOverrodeHaltState — операция бинарная: левый аргумент (this), правый аргумент (override). Каждое её применение — это новый узел в дереве. У узла два ребёнка: база и override. Если ребёнок сам обёртка, дерево там продолжается ещё одним узлом; если нет, это исходное State — лист. После N применений в дереве N узлов-обёрток и N+1 лист — стандартное свойство бинарного дерева. Например, у minusOne выше: 3 применения (3 узла-обёртки) и 4 листа — invertNumber, plusOne, invertNumber, normalizeNumber. Вот это же дерево явно:

Имя же — плоское — конкатенация имён через >. Из бинарного дерева получается строка, и обратно строка восстанавливает дерево только если соглашение об именовании биективно. У плоской >-нотации оно не биективно.

Сколько разных деревьев соответствует одному имени с N разделителями? Стандартный ответ из комбинаторики: число Каталана $C_N$.

$C_n=\frac{1}{n+1}\left(\genfrac{}{}{0px}{}{2n}{n}\right)$ — это та самая последовательность, которая считает: число бинарных деревьев с n+1 листьями, число правильных скобочных последовательностей длины 2n, число путей Дика длины 2n, число триангуляций (n+2)-угольника, и ещё с десяток изоморфных комбинаторных объектов. Одно из тех чисел, которые «вылезают отовсюду».

В нашем случае самая близкая проекция — расстановка скобок: для произвольного бинарного оператора • число способов расставить скобки в выражении a • b • c • ... (n+1 операндов) равно $C_n$. withOverrodeHaltState — как раз такой оператор, и каждой расстановке скобок соответствует своё дерево композиции.

Первые восемь значений: $C_0=1$, $C_1=1$, $C_2=2$, $C_3=5$, $C_4=14$, $C_5=42$, $C_6=132$, ${𝑪}_7=429$.

Для нашего A>B>B>A>A>B>B>A это значит: 429 различных деревьев композиции, у каждого по-своему расставлены родительско-дочерние связи, дают одну и ту же строку. И это не теоретическая верхняя оценка — это точное число несовпадающих структур, прячущихся за одним именем.

Пример поменьше — A>B>C>D (три разделителя). По формуле $C_3=5$; вот эти пять деревьев, сконструированные в коде:

// 1. полностью левоассоциативное
((A.wohs(B)).wohs(C)).wohs(D)

// 2.
(A.wohs(B.wohs(C))).wohs(D)

// 3.
(A.wohs(B)).wohs(C.wohs(D))

// 4.
A.wohs((B.wohs(C)).wohs(D))

// 5. полностью правоассоциативное
A.wohs(B.wohs(C.wohs(D)))

Все пять схлопываются в одну и ту же плоскую строку A>B>C>D. В скобочной нотации, которая придёт в v7, каждое получит уникальное имя — об этом ниже.

Починка скобками

Если плоский разделитель теряет дерево, то скобки его сохраняют. v7 (turing-machine-js#148) меняет соглашение об именовании на:

state.#name = `${this.name}(${override.name})`;

A.withOverrodeHaltState(B) теперь называется A(B). Возвращаемся к нашим двум конструкциям A>B>A:

// Конструкция 1: A(B(A))
const c1 = A.withOverrodeHaltState(B.withOverrodeHaltState(A));

// Конструкция 2: A(B)(A) — в чистой скобочной нотации
const c2 = A.withOverrodeHaltState(B).withOverrodeHaltState(A);

Те же буквы, разная расстановка скобок, разные деревья. Имена различимы. Биекция!

И это не изобретённое соглашение. Сбалансированные скобочные строки длины 2n — каноническая запись бинарных деревьев с n+1 листьями в комбинаторике. Это та самая биекция, на которой держится один из основных счётных результатов о числах Каталана. Лучший формат не был придуман — в нём просто будет отражена структурность, которую >-нотация всё это время выбрасывала.

Стоимость для пользователя — запрет на скобки ( и ) в именах состояний: конструктор State бросает исключение. Скобки зарезервированы под композицию. Зато > больше не зарезервирован — можно использовать в пользовательских именах свободно.

Вторая половина истории

Чистая скобочная биекция выше — это история про именование. v7 заодно подчищает и runtime. turing-machine-js#176 добавляет коллапс цепочек: внутри withOverrodeHaltState теперь делается bare = this.#bareState ?? this. То есть A.wohs(B).wohs(A) распознаётся как «обёртывание уже-обёрнутой A», внутренний override (B) при этом всё равно мёртв во время исполнения (на halt-стек кладётся только override самой внешней обёртки), и вместо A(B)(A) получается просто A(A).

Так что в реальном v7 наша Конструкция 2 не даст A(B)(A) — на этапе сборки она схлопывается в A(A). Скобочное именование само по себе биективно (каждому дереву — своё имя); коллапс цепочек убирает деревья, неотличимые на runtime. В итоге имя в v7 описывает поведение машины, а не историю её построения.

И заодно: метод переименовывается. withOverrodeHaltState → withOverriddenHaltState (turing-machine-js#149). Past-tense (overrode) в этой идиоме читался криво — должен был быть past participle (overridden). Семилетняя грамматическая опечатка на публичном API. Чинится одним rename без алиаса.

Где ещё встречается подобное

Неинъективная сериализация — общий паттерн. Если в вашем коде есть «имя», которое склеивается плоским разделителем из чего-то структурно древовидного, шансы на C_n-баг ненулевые. Несколько примеров:

• Цепочки расширений файлов — .tar.gz, .spec.ts, .d.ts. Работает по соглашению, потому что расширения известны заранее. Стоит поставить точку в имени файла — и сразу возникает неоднозначность: my.app.tar.gz — это базовое имя my.app с расширением .tar.gz или базовое имя my.app.tar с расширением .gz? Разные инструменты разрешают по-разному.
• Имена джоинов в БД через _: user_address_country. Если user_address уже сам по себе имя таблицы (подчёркивание — часть идентификатора), то user_address_country неоднозначно: то ли это user.address_country, то ли user_address.country. Починка — квалифицированное пространство имён или явные алиасы.
• Модульные пути в Java/Python — com.example.foo.Bar. Это может быть класс Bar в пакете com.example.foo или вложенный класс foo.Bar в пакете com.example. Разрешается по соглашению (заглавная буква — класс), а не самим именованием.

Эвристика для код-ревью: если ваш «идентификатор» — это плоская конкатенация разделителем чего-то древовидного, поищите C_n-баг. Чаще всего он скрытый: имена случайно не пересекаются на тех данных, что в проде, но архитектурно дыра всегда там.

В моей библиотеке C_n-баг прятался семь лет, потому что никто не пытался поймать движок на коллизии имён. Чтобы её обнаружить, надо догадаться построить два структурно разных дерева и проверить, что имена у них различаются. Такой тест никто не пишет, пока не узнает, что коллизия в принципе возможна.

Что уезжает в v7

Три тикета, которые задумывались как три отдельных изменения, но при ближайшем рассмотрении — одна и та же мысль:

• Скобочное именование (turing-machine-js#148). Биекция между деревьями композиции и именами.

• Чистая Mermaid-визуализация (turing-machine-js#138, turing-machine-js#174). Обёртка рендерится как отдельный узел [[композитное-имя]], тело базы — как подграф callable subtree of NAME. Структурная ясность имени отражается в визуальной ясности диаграммы:

  Обёртка — call-site; тело базы — callable subtree; halt — return. Композиция в движке буквально стала чтением как вызов функции.

• withOverrodeHaltState → withOverriddenHaltState (turing-machine-js#149). Грамматика на публичном API.

Все три про одно: композиция — древовидная, представление должно сохранять дерево, а не размывать его.

В заключение

Чистка визуализации привела к перестройке именования. Это та же история, которую я уже описывал в "Два мажора, один README, одно демо": дизайн-ревью, которое тесты провести не могут, ловит то, что тестам не видно. Там это были документация и первый потребитель API. Здесь — визуализация. Жанр один и тот же: ставишь себя перед задачей показать структуру, и структура — если она кривая — начинает торчать. Тесты этого не делают, потому что они смотрят на поведение, а кривизна структуры зачастую видна только в её представлении.

Семь стрел, 429 деревьев. Имя, которое выглядело как инструкция обхода, на деле было одной из 429 возможных. v7 даёт каждой её собственное имя — и оставляет за визуализацией право показать, как это дерево на самом деле росло. А что обёртка — это call-frame, и эту структуру стоит вытащить в отдельный тип, — уже другая история (turing-machine-js#213).

Возникает вопрос: где именно в цикле итерации воркеру нужно реализовать приостановку? Кандидатов два, и выбор между ними фиксирует сразу два контракта: хуков движка и протокола между воркером и основным потоком. Выбрать точку — это спроектировать обе стороны сразу; промахнуться — испортить обе. Эта статья — про этот выбор.

Введение

turing-machine-js — интерпретатор машины Тьюринга. У движка есть хук onStep — переданный обработчик вызывается после каждого шага машины. Этим вводным про движок ограничимся. Подробнее про устройство и предыдущие изменения API — в статьях «Три мажора, две ошибки: проектирование API приостановки для интерпретатора машины Тьюринга» (1) и «Два мажора, один README, одно демо: два почти бесплатных дизайн-ревью» (2).

Первый настоящий потребитель движка — machines-demo, интерактивный отладчик. Пользовательская машина исполняется в Web Worker’е; UI на основном потоке показывает трейс. То же самое демо, которое в статье (2) спровоцировало два мажора в движке (#109, #108). В этой статье — следующий эпизод из жизни того же движка: v6.2 → v6.3 → v6.4.

В демо есть режим RUNNING_AUTO: пользователь выбирает интервал, нажимает «Старт», машина шагает автоматически. Изначально режим был устроен прямолинейно — основной поток запускал машину в режиме пошагового выполнения (через runner.step() — обёртку над движковым runStepByStep() в воркере), между шагами вставлял setTimeout(intervalMs) для трейса. Просто и работает — до тех пор, пока пользователь не поставит брейкпоинт.

Брейкпоинты в движке реализованы внутри machine.run(): цикл итераций находится в самом движке, и при попадании в debug-помеченное состояние он сам себя останавливает. runStepByStep() же — генератор: цикл по нему крутит потребитель, и брейкпоинты он не видит. machines-demo#43 и был этой дырой — пользователь ставит брейкпоинт в режиме RUNNING_AUTO, нажимает «Старт», но брейкпоинт игнорируется. Чтобы брейкпоинты заработали, RUNNING_AUTO должен перейти с runStepByStep() на run().

Но run() крутит цикл итераций внутри движка, не передавая управление наружу. Раньше приостановка жила в паузах между вызовами runner.step() на основном потоке — то есть на стороне потребителя, который сам управлял интервалом между шагами. С переходом на run() этой паузы на стороне потребителя больше нет — приостановку нужно либо переносить внутрь движка (в существующий или новый хук), либо убирать. Это и стало дизайн-вопросом.

Ещё одна архитектурная деталь, которая нам пригодится: у основного потока есть сторожевой таймер на воркер. Если воркер молчит на сообщениях дольше WORKER_TIMEOUT_MS, основной поток считает его подвисшим (например, недостижимое halt-состояние пользовательской машины) и убивает воркер. Любое размещение приостановки должно с этим таймером уживаться.

Где может жить приостановка

Два кандидата:

1. Внутри onStep — синхронного хука, который движок зовёт после каждого шага. Сейчас его сигнатура (state) => void. Можно расширить её до (state) => void | Promise<void> — и тогда обработчик может await-ить задержку прямо там.
2. На границе итерации — добавить новый хук, специально для асинхронных ожиданий. Имя пока неважно; важно, что вызывается он один раз в конце каждой итерации движка, и движок ждёт возвращённый Promise.

Оба варианта отвечают на вопрос «где живёт приостановка». Но они одновременно диктуют, как устроен протокол между воркером и основным потоком.

Если приостановка стоит в onStep, она оказывается посредине каждой итерации движка — в той точке, где зовётся onStep. К этой же точке приходится привязывать и всё остальное в протоколе: и сторожевой таймер, и обработку клика «Пауза» от пользователя — всё повисает на этой мид-итерационной задержке.

Если приостановка стоит на границе итерации, у воркера в конце каждой итерации появляется момент — движок не работает, ждёт Promise. В этот момент удобно помириться со сторожевым таймером и быть готовым к обработке клика «Пауза».

Дальше — оба контракта по очереди.

Контракт «Внутри onStep»

v6.2.0 пошла первым путём — расширила сигнатуру onStep с (state) => void до (state) => void | Promise<void>. Обработчик теперь мог await-ить задержку прямо там, где раньше только смотрел состояние. Со стороны воркера это выглядело красиво — один хук, одна точка ожидания, никаких новых сущностей.

Уже через несколько часов я пометил v6.2.0 в npm как deprecated. Не «вышла версия посвежее, обновляйтесь по случаю», а явное предупреждение: эта версия — неправильная.

v6.3.0 откатила расширение сигнатуры. Причина — простая: onStep задумывался как хук наблюдения, а не координации. Он работает синхронно, посредине каждой итерации движка, для того чтобы потребитель мог посмотреть на состояние и где-то его записать. Добавить ему await в сигнатуру — значит склеить две разные задачи в одну: и наблюдать, и удерживать движок. Читатель сигнатуры теперь не различает: этот хук — «посмотри на состояние» или «придержи здесь движок»? Назначение хука перестаёт быть видно из сигнатуры.

Симптом того, что что-то не так, проявился в документации. README должна была пояснить, как пользоваться расширенным onStep. Честный абзац начинался с оговорки: «onStep — это хук наблюдения, но вы можете возвращать из него Promise, и движок дождётся его перед следующей итерацией». Не получалось убрать ни «но», ни вторую половину фразы. Документация работала ровно так, как описано в статье (2): прозой давила на форму — форма треснула.

v6.4.0 добавила отдельный хук — onIter. Сигнатура: (state) => void | Promise<void>. Контракт: вызывается один раз в конце каждой итерации, асинхронно, безусловно. Имя — iteration boundary, граница итерации — описывает что хук делает (даёт точку в конце итерации, в которой можно подождать), а не зачем потребитель собирается его использовать. А использовать его можно по-разному: для приостановки между шагами трейса, для синхронизации с UI, для прерывания прогона (например, по AbortSignal).

Контракт хуков движка теперь различает три задачи:

• onStep — синхронный, посредине итерации. Наблюдение за состоянием.
• onPause — асинхронный, условный (срабатывает только на брейкпоинтах). Граница между ходом и остановом.
• onIter — асинхронный, безусловный (срабатывает на каждой итерации). Координация: удержание движка для асинхронной работы потребителя.

Три хука — три разные задачи. Наблюдение не должно удерживать движок; для этого есть отдельный, асинхронный хук. Удержание не должно прятаться в хуке наблюдения; для этого есть onIter. Пауза по брейкпоинту — это вообще отдельный сценарий, и под него есть onPause, у которого событие срабатывания явно прописано в имени.

Контракт «На границе итерации»

Где живёт приостановка — теперь ясно: внутри обработчика onIter. Но обработчик onIter запускается внутри воркера, а пауза от пользователя приходит снаружи — с основного потока, по клику. Между ними нужен протокол.

Этот протокол содержит четыре механизма: пара сообщений idle/busy, флаг stepRequested, синтетическое событие paused, поле intervalMs в resume. Каждый закрывает одну конкретную проблему, которую расположение приостановки создаёт.

Сообщения idle и busy: приостановка сторожевого таймера

Упомянутый выше сторожевой таймер в onIter начинает мешать.

Приостановка в onIter на каждой итерации может легко превышать таймаут — особенно если пользователь выкрутил intervalMs на «медленно» (демо позволяет ставить интервал, скажем, в две секунды). Получается ложная тревога: воркер не подвис, он просто ждёт.

Решение — воркер сам сообщает основному потоку, в какой момент он «работает», а в какой «ждёт». Перед тем как await-ить приостановку в onIter, воркер посылает сообщение idle. После того как приостановка завершилась, посылает busy. Основной поток приостанавливает сторожевой таймер на промежутке между idle и busy. Таймер продолжает ловить настоящие зависания (например, недостижимое halt-состояние), но не путает их с легитимным замедлением трейса.

Без такой обёртки у сторожевого таймера два плохих варианта. Либо брать порог с запасом — тогда настоящие зависания не ловятся (или ловятся слишком поздно). Либо брать порог впритык — выше вероятность ложного срабатывания (воркер убивается на легитимной задержке). Сообщения idle / busy разрешают оба сценария одновременно.

Шаг — флаг внутри воркера, а не состояние движка

Когда пользователь нажимает «Шаг», основной поток посылает воркеру сообщение resume с флагом step: true — «продвинь машину на одну итерацию и снова поставь паузу». Реализовано это так: воркер выставляет флаг stepRequested = true. На следующем onIter обработчик видит флаг, сбрасывает его в false, синтезирует событие paused и снова ждёт. Машина прошла ровно один шаг.

Принципиально: «шаг» — это флаг внутри воркера, а не часть состояния движка. Движок не знает, что такое «шаг», — он просто на следующей итерации опять оказался в режиме ожидания. Координация лежит снаружи движка. onIter остаётся тонким await-хуком — он не мутирует движок, он только приостанавливает его выполнение. Это и сделало onIter жизнеспособным как контракт: в нём нет «специальной логики шага», есть только Promise, который воркер сам контролирует. Если бы шаг был частью состояния движка, контракт onIter пришлось бы расширять до «и ещё, дёрни вот этот флаг», и хук перестал бы быть тонким.

При «Шаге» замедление излишне

При нажатии на «Шаг» замедление излишне — пользователь сам играет роль таймера: кликает столько раз и так быстро, как ему нужно. Реализация это отражает: при «Шаге» intervalMs игнорируется, обработчик onIter не вставляет ожидание. Это самое чистое выражение разделения «наблюдение ≠ координация» внутри воркера: когда управляет пользователь, движок подчиняется.

Синтетическая пауза по клику

Сценарий: машина в RUNNING_AUTO — движок выполняется с приостановками по времени, между итерациями onIter ждёт intervalMs. Пользователь нажимает в UI кнопку «Пауза». Клик приходит на основной поток. Основной поток посылает воркеру сообщение pause. Воркер в этот момент удерживает движок в приостановке — Promise ещё не разрешился. Что делать?

Решение — синтезировать такую же паузу, как от брейкпоинта. У UI уже есть готовый обработчик: на paused из воркера он переключается в «остановлено». Если клик «Пауза» пойдёт по другому пути, появится вторая ветка с тем же поведением. Поэтому воркер и синтезирует paused — для UI клик «Пауза» неотличим от срабатывания брейкпоинта.

Воркер отменяет приостановку (разрешает её принудительно, заранее), выставляет флаг stepRequested = false, и из обработчика onIter после возврата из ожидания посылает наружу событие paused — синтетическое, а не возникшее в ходе нормальной работы движка. Под капотом два сценария различаются (один отменяет приостановку, другой ждёт её естественного завершения), но контракт снаружи — один сценарий «пауза».

intervalMs — параметр resume, не run()

Приостановка реализуется в onIter по intervalMs. Откуда воркер берёт это значение? Не из параметров запуска run(). А из последнего сообщения resume: каждое из них приходит с актуальным intervalMs из основного потока.

Причина — пользователь может управлять величиной задержки между приостановками во время прогона. Значение в UI читается в момент клика, не в момент старта run(); следующее resume передаст новое значение, и со следующей итерации приостановка подстроится. Маленькая цена для протокола, большой выигрыш для UX.

Двойственность, явно

Приостановка живёт в одной точке итерации. С точки зрения движка эта точка — обработчик onIter: хук, который вызывается один раз в конце каждой итерации, асинхронно. С точки зрения протокола та же точка — это промежуток между сообщениями idle и busy, в котором сторожевой таймер приостановлен, клик «Пауза» может мягко отменить приостановку, а intervalMs берётся из последнего resume.

Одна точка, два API. От выбора зависят все последующие этапы проектирования. Положить её посредине хука наблюдения — это сразу поломать обе стороны: документация на расширенный onStep не пишется без «но», обёртку сообщениями idle/busy не к чему прикрутить (один и тот же хук обозначает и наблюдение, и ожидание), синтетическое событие paused приходится посылать из неестественного места. Без чистой границы итерации страдают и хук, и протокол.

Заключение

Разделять наблюдение и координацию — это то, ради чего контракт хуков движка различает три задачи, а не сливает в одну. Склеить их — соблазн, которому поддался v6.2.0. И единственное, что позволило осознать ошибочность подхода за несколько часов — README движка не получалось написать честно, и smoke-тест демо не получалось пройти. Два почти бесплатных дизайн-ревью (статья (2)).

Код: turing-machine-js (движок, v6.2 → v6.4) и machines-demo (демо).

Именно работа над документацией вскрыла обе ошибки. Тут есть мета-урок: документация — самое дешёвое дизайн-ревью, которое можно у себя устроить, но это уже тема для другого поста.

Это и есть тот самый «пост», другая статья — и первое, что ей нужно сделать, это поправить тизер. Тизер привирает. Документация поймала только одну из двух ошибок. Вторую поймал первый настоящий потребитель API, которого я собирал параллельно. Эти два ревью сработали в паре: документация смотрит на форму API, потребитель — на использование. Вместе они ловят то, чего не видят тесты.

Если вы выпускаете что угодно за интерфейсом — библиотеку, CLI, любую сущность за контрактом, — это два ревью, которые вы, скорее всего, не оставляете без внимания.

Напоминание

«Три мажора, две ошибки» разбирает движок и v4-API паузы — onStep, onDebugBreak, флаги debug на состояниях. Здесь я опираюсь на неё, не повторяясь слишком. Траектория v4 → v6 включает три брейкинг-мажора: переименование хука, ужесточение семантики halt и схлопывание lifecycle-тиков. Первые два всплыли в демо. Третий — в документации.

Демо: v4 → v5

Пока v4 уезжала в релиз, я начал собирать machines-demo — интерактивный отладчик Turing-машины и первый не-тестовый клиент движка.

Демо — естественный первый потребитель: у него двойная цель. Продуктовая — публичное распространение и демонстрация движка в действии. Техническая — обкатка изменений и проверка концепций на живой API-поверхности. Обе цели делают разработку демо неотъемлемой частью релизного цикла, а не опциональной добавкой к нему.

Демо задействовало оба хука одновременно: onStep заполнял буфер команд для UI-трейса на каждой итерации; onDebugBreak управлял циклом «пауза / продолжение».

Демо собиралось. Тесты проходили. Но писать его было неудобно, по двум причинам.

Во-первых, after-сработка onDebugBreak приходила с данными предыдущего yield’а — теми же, что предыдущий onStep уже показал. Демо обрабатывало одно и то же дважды, и вопрос «почему два хука для одного события?» задавал не я, а как будто сам код. Я открыл turing-machine-js#109 как RFC об отношениях этих двух хуков, перечислил четыре эскиза; резолюция сузилась до именования. onDebugBreak ставил целью использования «отладку», глагол же потребителя — «пауза». Переименование без зазрения совести и без алиаса. v5.

Во-вторых, в UI демо появился сценарий «приостановиться перед halt» — дать пользователю заглянуть в финальное состояние машины до того, как она завершится. Естественная реализация — флажок debug на самом haltState. Первый тест-кейс установил haltState.debug = { before: true, after: true }, потому что симметрия выглядела правильной. Срабатывал же только before. Хуже того: after-сработка на самой итерации, которая привела к halt, не доходила до обработки — цикл выходил, как только state.isHalt становилось true. turing-machine-js#108 разбил это на две части: восстановить потерянную after-сработку (баг); бросать исключение при записи в haltState.debug.after (API).

Обе претензии пришли со стороны потребителя. Демо не показал баг в коде — он показал формат взаимодействия с API. Имена не подходили под применение. Снисходительность к входным данным не соответствовала тому, что пользователь пытался сделать. Тесты сверяли поведение с собственной внутренней моделью движка — ок, зе́лено. Демо сверило поведение с ментальной моделью потребителя — и выдало две конкретные претензии (не ок).

Документация: v5 → v6

v5 уехала. README требовал обновления. Новый раздел про порядок диспатча должен был объяснить — словами, — когда срабатывают onPause(before), onStep и onPause(after) относительно той итерации, которую они описывают.

Первый честный абзац выглядел примерно так:

onPause(after, K) срабатывает на yield’е итерации K+1, с payload’ом, подставленным из снэпшота итерации K, до того как сработают onPause(before, K+1) или onStep(K+1).

Я какое-то время смотрел на это предложение. Короче не получалось. Предложение о подстановке — это не то, что читатель должен был встретить.

Код работал. Тесты проходили. Демо корректно потребляло хуки. Ошибка была не в этом — она была в форме диспатча, и эта форма становилась видна только с той стороны, где её приходилось формулировать словами.

Фикс схлопнул lifecycle: before(K) → step(K) → after(K) на одном и том же yield’е. Без подстановок. Без межитерационного планирования. Без финального добора для останавливающейся итерации (в «Трёх мажорах, двух ошибках» я перевёл это как «пост-цикловой добор»; сейчас, пожалуй, обошёлся бы покороче). Абзац README теперь звучит так:

На yield’е итерации K хуки срабатывают в lifecycle-порядке.

А такое предложение читатель проходит не задумываясь. turing-machine-js#119 уехал как v6.

Прямая цитата из предыдущей статьи:

Код работал, тесты проходили, документация была корректной. Просто дизайн был неправильным.

К этому хочется добавить: документация была корректной только при условии, что читатель смирится с тремя объясняющими предложениями, которые ему читать не следовало. Это не «корректная документация» — это документация, извиняющаяся за форму.

Ревью документацией поймало форму, не использование. Демо работало. Тесты проходили. Только давление прозы в этот раз вскрыло внутренние проблемы реализации.

Три ревью, три слоя

Опишем, что проверяет каждое:

• Тесты сверяют код с самим собой. Внутренняя консистентность. Движок выдаёт то, что движок должен выдавать. Зелёные тесты — это база.
• Первый настоящий потребитель сверяет код с ментальной моделью потребителя. Совпадает ли формат API с тем, что пользователь пытается сделать? Ревью реального взаимодействия с API привело к его изменению: переименованию и запрету halt-after.
• Документация в виде прозы (не JSDoc, а связный README-нарратив) сверяет код с авторским объяснением. Есть ли у дизайна честное однопараграфное описание? Отсутствие такового заставило внимательно посмотреть на танец с подстановкой и отказаться от него.

Каждое ревью ловит то, что не ловит слой ниже. Тесты не ловят форму; потребитель не ловит проблемы взаимодействия, которые он умело может обойти; документация не ловит UX-неровности, которые ей упоминать не пришлось.

Стоимость асимметричная. Разработка настоящего потребителя — самое дорогое из трёх ревью; написание документации — самое дешёвое. И всё-таки даже самое дорогое из них обходится дешевле, чем переделывать API после того, как проблемы вскроются у пользователей: отсюда и «почти бесплатные» в заголовке. Настоящего потребителя нужно разработать до мажорного релиза — только это ревью делает API комфортным в использовании. Документация после этого ограждает то, что осталось.

Эвристики на следующий мажор

1. Соберите первого настоящего потребителя до мажора. Не тест-фикстуру — а потребителя со своей ментальной моделью. Трудности, с которыми он сталкивается, — это те же трудности, с которыми потом столкнутся все ваши пользователи.
2. Напишите параграф про порядок диспатча до того, как зафиксируете порядок диспатча. Если не получается одной фразой описать, что и когда срабатывает, — диспатч неправильный. Решения такого рода должны приниматься на этапе проектирования, а не документации, тогда когда не написано даже и строчки кода.
3. Перечитайте документацию глазами незнакомца. Если параграф читается как извинение за форму — документация работает, она явила ошибку формы. Чинить надо форму, а не параграф.

Три мажора. Один README. Одно демо. Тестам сказать было нечего.

Код: turing-machine-js (движок) и machines-demo (первый не-тестовый потребитель, на котором всплыли v4 → v5).

За последние две недели я выкатил подряд четыре ломающих мажорных релиза @turing-machine-js/machine — v3, v4, v5, v6 — и самое интересное здесь было не в какой-то одной фиче. Интересно было смотреть, как один и тот же участок API (хук приостановки/брейкпоинта в управляющем цикле) переделывался дважды за три версии, и каждый раз потому, что в прошлый раз там выпирало то, что выпирать не должно.

Этот пост — разбор полётов. Если вы проектируете API приостановки/шага/брейкпоинта для интерпретатора на цикле-генераторе, для планировщика или рантайма DSL, ошибки, которые я допустил, нетрудно повторить — и полезнее сначала встретить их в чужом коде.

Постановка задачи

Движок исполняет машину Тьюринга. Внутри — генератор: каждый yield — один шаг (одно срабатывание перехода на одном символе ленты). Управляющий цикл выглядит примерно так:

async function run({ initialState, onStep }) {
  for (const m of runStepByStep({ initialState })) {
    await onStep?.(m);
    if (m.state.isHalt) return;
  }
}

MachineState (m) — снимок состояния машины на каждой итерации: какое состояние сейчас будет исполнено, текущий и следующий символы, движения, которые сделают головки. Потребитель — логгер, UI, тест — может подцепиться к onStep и наблюдать.

В v4 я хотел добавить способ приостановить выполнение в выбранных точках — как брейкпоинт в отладчике. У любого State должна быть возможность задать конфигурацию debug:

myState.debug = { before: [symA], after: [symA] };

...а управляющий цикл должен давать потребителю возможность заглянуть внутрь машины и решить, когда продолжить.

v4: выкатываем

Дизайн v4 был простым. Я сделал run() асинхронным, добавил хук onDebugBreak и спроектировал его так:

await machine.run({
  initialState,
  onStep: (m) => { /* каждый шаг */ },
  onDebugBreak: async (m) => {
    if (m.debugBreak?.before) console.log('before:', m.state.name);
    if (m.debugBreak?.after)  console.log('after:',  m.state.name);
    // зависаем здесь до резолва промиса
  },
});

Поле debug у состояния — мутабельное. state.debug = { before: true } ставит брейк перед шагом; before: [symA] фильтрует по тому, что читает головка. Хук вызывается через await, поэтому любой потребитель может реализовать сценарий «приостановить машину, пока человек не нажмёт Продолжить» — просто не резолвить промис.

Также хотелось ставить брейкпоинты на halt:

haltState.debug = { before: true };  // приостановка перед выходом

Это работало. Фильтры по списку символов на haltState молча игнорировались — у haltState нет символа под головкой, по которому можно было бы фильтровать. Ну и ладно, подумал я, — будем снисходительны к входным данным, главное, что универсальный true срабатывает.

В этом дизайне было два просчёта. Я не замечал ни одного, пока не сел писать документацию, а следом — UI.

Ошибка № 1: хук описывает движок, а не потребителя

onDebugBreak на бумаге читается как вполне разумное имя. Движок выстреливает «debug break»; вы цепляете на него хук.

Но что потребитель в этом хуке делает? Приостанавливает. Заглядывает внутрь. Ждёт ввод. Возобновляет. Хук на самом деле не уведомляет о том, что произошло событие, — он предлагает точку сотрудничества.

Имя onDebugBreak несёт одну конкретную рамку — «отладка». Но тот же хук — это ровно то, что нужно для пошаговой визуализации, замедленного воспроизведения, плавной анимации, UI с «нажмите пробел, чтобы двинуться дальше». Ничто из этого не отладка. Это всё приостановка.

Кажется мелочью. Это не мелочь — потому что, увидев имя, потребители начинают проектировать вокруг него: их обработчик называется handleDebugBreak, в их стейт-машине заводится булева debugging, кнопка в UI подписана «Остановить отладку». Имя расползается по словарю каждого потребителя.

Я написал RFC (turing-machine-js#109) и переименовал хук в v5. Жёсткое переименование, без алиаса с депрекацией:

await machine.run({
    initialState,
-   onDebugBreak: (m) => { ... },
+   onPause: (m) => { ... },
  });

Поле пейлоада m.debugBreak осталось — это метаданные о том, почему сработал этот yield ({ before: true } или { after: true }), и «break» внутри пейлоада нормально читается. Но имя хука — это контракт с потребителем: onPause описывает, что он делает, а не что делает движок.

Правило на следующий раз: называя хук, называйте глагол потребителя, а не событие движка. Хуки — это точки сотрудничества, а не event listeners.

Ограничение: haltState.debug.after — бессмыслица

Вторая ошибка v4 пряталась под инстинктом быть снисходительным к входным данным. haltState.debug.after молча принимал запись. Просто не срабатывал.

Почему? Потому что семантика after в этом движке означает «сработать на итерации после той, что соответствовала фильтру». Для обычных состояний это логично: вы выходите из состояния K, исполняется следующая итерация (K+1), и на её yield-е потребителю сообщают: «кстати, фильтр after на K сработал на прошлом шаге». Но halt — терминальное. После halt никакого K+1 нет. Событию after не за что зацепиться.

В v4 я молча проглатывал haltState.debug.after = true. Хуже того, я пропускал также { before: true, after: true } — половина присваивания была осмысленной, половина была no-op-ом, и потребитель об этом не узнавал.

В v5 я сделал так, чтобы обе формы бросали исключение при записи (turing-machine-js#108, часть 2):

- haltState.debug = { before: true, after: true }; // v5: бросает — 'after' на halt не за что зацепиться
+ haltState.debug = { before: true };

Правило на следующий раз: если у конфигурации нет семантики — кидайте исключение пораньше. Молчаливый no-op на входе выглядит юзерфрендли — ровно до момента, когда потребитель полдня выясняет, почему у него UI не срабатывает на halt. «Будь снисходителен» — ложная экономия, когда снисходительность глушит реальную ошибку.

Заодно я починил связанный баг: фильтр after самой останавливающейся итерации тоже не срабатывал (turing-machine-js#108, часть 1). Управляющий цикл выходил, как только state.isHalt становилось true, — и after-событие от предыдущей итерации, которое в норме сработало бы на этом финальном yield-е, просто проваливалось. В v5 я добавил пост-цикловой добор, чтобы оно сработало.

К этому я ещё вернусь.

И один бонус v5: общий выключатель на run() для всей системы приостановки.

await machine.run({ initialState, debug: false, onPause: ... });

При false все срабатывания приостановки подавляются вне зависимости от того, что прописано в state.debug по всему графу (turing-machine-js#106). Можно A/B-тестировать «режим отладки», не переписывая граф и не вычищая каждое поле state.debug. Флаг управляет диспатчем onPause; само поле полезной нагрузки m.debugBreak по-прежнему заполняется на yield-ах генератора (это свойство итерации, а не того, как run() решил его выставить наружу).

Ошибка №2: танец подстановки

Эту я поймал с особой гордостью — код работал, тесты проходили, документация была корректной. Просто дизайн был неправильным.

В v4 и v5 after K (срабатывание after для итерации K) на самом деле происходило на yield-е итерации K+1. Управляющий цикл проносил между yield-ами флажок pendingAfterFromPrev, и на yield-е следующей итерации сначала диспатчил хук after, потом хук before, потом onStep. Хук для after-срабатывания K должен был видеть состояние K, а не K+1. Поэтому я подставлял снимок предыдущего yield-а в поле m.state итерации K+1 — только на время диспатча after.

Это работало. Но у этого были три побочки:

1. Подстановка протекала. Потребители хотели доступ к неподставленному, «настоящему» состоянию итерации (тому, которое видит хук step), — см. turing-machine-js#107. Часть пользователей читала MachineState.debugBreak напрямую из runStepByStep и удивлялась, что m.state относится к итерации, на которой after сработал, а не к той, что его породила.

2. Halt требовал отдельной ветки. Как уже сказано: собственный after останавливающейся итерации срабатывает после выхода из цикла. В v5 для этого появился пост-цикловой добор. И у этого добора своя ветка кода, со своей подстановкой, отдельной от диспатча внутри цикла.

3. Возвращаемый тип генератора расширился. Поскольку пост-цикловому добору надо было вернуть финальный yield-нутый объект наружу из итератора, тип возврата runStepByStep стал Generator<MachineState, MachineState | null> — yield-тип и return-тип. Канонический потребитель на for..of return-значения не видит, но всякий, кто читал сигнатуру типа, теперь должен был разбираться, почему слотов два.

Всё это выросло из одного проектного решения: диспатчить after K на yield-е итерации K+1, а не на собственном yield-е итерации K.

В v6 я это схлопнул (turing-machine-js#119). Жизненный цикл одной итерации теперь честно before → step → after. Срабатывание after приходится на тот же yield, что и итерация, которая его породила. Нет подстановки. Нет pendingAfterFromPrev. Нет пост-циклового добора. Тип возврата генератора сужается обратно до Generator<MachineState>.

// v6
await machine.run({
  initialState,
  onStep: (m) => { /* без изменений */ },
  onPause: (m) => {
    if (m.debugBreak?.before) console.log('before:', m.state.name);
    if (m.debugBreak?.after)  console.log('after:',  m.state.name);
  },
});

Порядок диспатча между хуками поменялся (любой тест, утверждавший pause(after K-1) → pause(before K) → step(K), пришлось перевернуть в pause(before K) → step(K) → pause(after K)), но множество вызванных диспатчей и семантика на каждой итерации не изменились. Потребители, относящиеся к хукам как к независимым наблюдателям, не видят никаких различий (turing-machine-js#107 — «отдать наружу неподставленное состояние» — исчез как проблема: подстановки больше нет, обходить нечего).

Правило на следующий раз: если пейлоаду хука нужно подставлять состояние из другой итерации, а не из той, что сейчас yield-ит, — последовательность диспатча неверна. Фазы жизненного цикла (before, step, after) принадлежат той итерации, которую описывают. Подстановка была не хитрым приёмом, а протечкой — она говорила, что события стоят не на том такте.

Что я заберу в следующий API приостановки/брейкпоинтов

1. Называйте хуки глаголом потребителя, а не событием движка. onPause, а не onDebugBreak. onProgress, а не onChunkReceived. Имя расползается по ментальной модели каждого потребителя — выбирайте ту рамку, которую хотите им передать.

2. Кидайте исключение при невозможных конфигурациях — и пораньше. «Снисходительность к входным данным» подходит для форм, которые могут быть осмысленными; это ловушка для форм, которые осмысленными быть не могут. У haltState.debug.after = true не было возможной семантики. Молчаливое проглатывание стоило одному пользователю полдня — пока я не заметил.

3. Фазы жизненного цикла принадлежат той итерации, которую описывают. Если хочется диспатчить after K на yield-е K+1 — спросите, какой пейлоад приходится подставлять, чтобы это выглядело правильно. Подстановка — это и есть сигнал.

4. Общий выключатель стоит дёшево и оправдывает себя. Булева на входной точке, которая выключает всю фичу целиком (без переписывания флажков на уровне графа), делает фичу безопасной для прода и удобной для тестов. run({ debug: false }) был одной из самых мелких добавок v5 — и одной из самых востребованных среди зависимых проектов.

5. Ломающие изменения стоят мажора. Три мажора за две недели звучат дорого. На самом деле — нет, если синхронный downstream — один репозиторий (в моём случае @post-machine-js/machine, который синхронно с движком обновил peer-зависимость ^4.0.0 → ^6.0.0 и переименовал свой внутренний __onDebugBreak → __onPause). Эргономика API копится у всех зависимых проектов на весь срок жизни библиотеки — заплатите цену миграции, пока API ещё молодой.

Дизайн v6 — это то, что мне следовало выпустить ещё в v4. Тогда у меня не было нужного словаря — я думал «выставить наружу события движка», а не «спроектировать контракт потребителя». Именно работа над документацией вскрыла обе ошибки. Тут есть мета-урок: документация — самое дешёвое дизайн-ревью, которое можно у себя устроить, но это уже тема для другого поста.

Код: turing-machine-js (движок) и post-machine-js (машина Поста поверх него, версии синхронизированы). Интерактивное демо на demo.machines.mellonis.ru использует v6-хук onPause для кнопок Step / Run / Stop.