docs(generator): зафиксировано независимое ревью и задачи на потом

- Зачем:
  - после coordinator-loop нужно независимое ревью результатов модельного
    времени и стартовой истории; пропущенный внешний review gate после задачи 5
    закрыт другой родословной.
- Что:
  - добавлен verification-handoff: что проверено независимо, дефект стыка
    (issue 09) и открытые пробелы (×K, crash recovery, коридоры мат-спеки,
    воспроизводимость, review gate задачи 3).
  - заведены issues 08 (портативный артефакт + runbook + идеи интерфейса),
    09 (баг браузерной фактуры на стыке), 10 (читаемость гео-карты).
  - в docs/course/PRD.md §7 — открытый вопрос «генератор как скрытая
    инфраструктура vs отдельный урок».
- Проверка:
  - git show --stat HEAD
  - чтение .scratch/handoffs/2026-06-14-generator-model-time-verification-review.md

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-14 23:03:08 +03:00
co-authored by Claude Opus 4.8
parent 86bba06f09
commit d7f02fd700
5 changed files with 321 additions and 0 deletions
@@ -0,0 +1,96 @@
# Handoff: независимое ревью модельного времени и стартовой истории
Дата: 2026-06-14
Жанр: одноразовый handoff по ADR-0003.
## Контекст
После прогона coordinator-loop по фичам `feature-data-generator` и
`generator-model-time-startup-history` (issues 0106, реализация Codex) проведено
независимое ревью результатов — другой родословной (Claude). Это в том числе
закрыло пропущенный внешний review gate после задачи 5 из PRD: он был выполнен той
же родословной, что и worker, а PRD требовал другую.
## Что проверили независимо (не по отчётам)
- `make generator-test``134 passed` (своим прогоном).
- Код = «Рабочий контракт реализации» спеки буква в букву: настройки
`GEN_MODEL_*`, state v2 (`model_timestamp/wall_timestamp/model_time_speed/…`),
формула live-возобновления, полуоткрытая граница `[T0, T_end)` с
`drain_until(include_boundary=False)`, манифест и антисмешивание.
- Данные в ClickHouse реальные и сходятся с отчётами до цифры: 6 ч → 16 054;
перепрогнали 1 сутки → 93 952; 2 суток → 187 087 событий / 17 397 визитов /
2 765 пользователей.
- Пирамида (users < visits < events), возвраты, монотонность обеих воронок,
отсутствие архивного сида (все строки 2026 года).
- Повторяемость суточной волны на 2 сутках: часовые числа day1≈day2
(отношение в основном 0.9–1.1), форма «ночь–день» повторяется.
- Стык backfill→live (live-доливка от `T_end=2026-01-03`): дублей 0, граница
держится, device/os/гео на стыке однородны.
- Дашборд: визуальная приёмка (шаг 2 спеки) — человеком и через Playwright.
«Rows by Layer» (4 равных столбца = 187 312) корректен: пайплайн проносит
событие 1:1, потерь нет, дедуп at-least-once на чистом backfill не возникает.
## Что нашли
- **issue 09 — реальный дефект стыка.** Браузерная фактура не переживает
восстановление визита: у визитов, активных ровно на `T_end`, в live-продолжении
меняется `browser_name`/`browser_language` (17/22 и 22/22), хотя внутри чистого
backfill браузер постоянен (0/14556). device/гео не задеты. Нарушает заявленный
критерий однородности задач 04/05; проверялось неполно (смотрели только поля
`dds.click`, а не per-event браузер в `dds.event`). Масштаб ~0.13% визитов.
- Гео-карта на дашборде нечитаема (нет легенды/подсказок/понятной шкалы) — issue 10.
- Стартовый сид по умолчанию — 6 часов (быстрый профиль для CI); суточная волна на
нём не видна, для просмотра нужен ≥2-суточный профиль через env.
## Открытые пробелы проверки (НЕ закрыты)
Ревью прошло по корректности кода, форме данных, стыку и дашборду, но НЕ трогало:
1. **×K не гоняли.** Все прогоны на `speed=1`. Ускорение модельного времени,
событийный бюджет по модельной длительности и смена дневного коэффициента при
×K проверены только в коде/по отчёту issue 03.
2. **Live-crash recovery не воспроизводили.** Формула возобновления с настенной
дельтой и закрытие просроченных визитов — только в коде. Гипотеза: дефект
issue 09 бьёт и сюда (тот же restore-механизм), эмпирически не подтверждено.
3. **Распределения не сверяли с коридорами мат-спеки** (`2026-06-10-generator-math-model.md`).
Подтвердили форму (монотонность, возвраты, длина), но не попадание
`confirmation_share` и доли коротких визитов в спроектированные коридоры.
4. **Воспроизводимость сами не перепрогоняли** — идентичность checksum при
повторном чистом прогоне взята из отчётов issue 03/05.
5. **Второй review gate (после задачи 3) не делали** — систематический sweep на
утечку настенных часов в расчёт интенсивности и сохранение состояния.
Помельче: не проверяли обработку повреждённого/старого state (fresh-start с
предупреждением), `browser_user_agent` (тот же механизм, что issue 09), сам процесс
coordinator-loop по правилам PRD.
## Зафиксированные follow-up (все needs-triage, на потом)
- `issues/07-migrate-course-from-archive-seed.md` — миграция уроков.
- `issues/08-startup-history-portable-artifact-and-usage-docs.md` — портативный
артефакт стартовой истории + runbook + идеи интерфейса (глаголы вместо флагов,
длительность/профили, громкий отказ при несовпадении, доливка кусочком,
Airflow-DAG как пульт).
- `issues/09-seam-browser-fixture-not-preserved.md` — дефект браузерной фактуры.
- `issues/10-dashboard-geo-map-readability.md` — читаемость гео-карты.
- `docs/course/PRD.md` §7 — развилка «генератор как скрытая инфраструктура vs
отдельный урок про генератор» (не грузить менти марковскими цепями).
## Состояние стенда
Поднят на 2 сутках генерации (+ несколько live-тиков от seam-проверки): ClickHouse,
Kafka, Superset, postgres-metadata. Дашборд:
`http://localhost:8088/superset/dashboard/ecommerce-analytics/`.
## Suggested skills
- `tdd` — для фикса issue 09 (один поведенческий тест на однородность браузера через
стык, затем минимальная правка).
- `conventional-commits` — перед коммитами.
- `claude-team-review` / внешний reviewer другой родословной — на пробелы 1–5.
## Следующий шаг
Сегодня только фиксация, без правок. Дальше — приоритизировать issue 09 (баг) против
08/10 (удобство/виз) и закрыть пробелы проверки 1–5 (особенно ×K и crash recovery).