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

Это и есть тот самый «пост», другая статья — и первое, что ей нужно сделать, это поправить тизер. Тизер привирает. Документация поймала только одну из двух ошибок. Вторую поймал первый настоящий потребитель 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.