ddmitry/clickstream-ch-kafka-superset-demo

Files

T

ddadmin 31a71f93ea docs(generator): зафиксирован контракт модельного времени

- Зачем:
  - нужно закрепить принятое человеком HITL-решение до кодовых задач 02-06.
- Что:
  - добавлен рабочий контракт настроек, хода часов, state, манифеста и ClickHouse-проверки.
  - выбран один живой ход часов через фиксированный модельный шаг без отдельной матрицы драйверов.
  - уточнена граница стартовой истории как [T0, T_end) и закрыт чек-лист issue 01.
- Проверка:
  - git diff --cached --check.

2026-06-14 16:30:15 +03:00

8.1 KiB

Raw Blame History

Модельное время и стартовая история генератора

Status: Draft

Зачем

Нужно довести решение ADR-0005 и ADR-0006 до рабочего процесса: генератор живёт по модельному времени, умеет быстро создать прошлое, сохранить слепок состояния и продолжить поток так, чтобы результат был проверяем в ClickHouse.

Источник решений:

docs/specs/2026-06-14-generator-model-time-and-startup-history.md
docs/adr/0005-generator-model-clock.md
docs/adr/0006-generation-as-sole-analytics-source.md
docs/research/2026-06-11-subagent-coordinator-experiment.md

Общие правила приёмки

Каждый кодовый срез должен заканчиваться проверкой через ClickHouse, а не только локальными тестами генератора.
Кодовые AFK-задачи идут через /tdd: один поведенческий тест, минимальная реализация, зелёная проверка. HITL- и документные задачи идут через обсуждение и фиксацию решения, без искусственного теста.
Координатор не работает в /goal на всю цепочку. Один worker получает один issue, не коммитит и не реализует следующие задачи.
После реализации worker делает саморевью без правок. Координатор классифицирует находки и возвращает только обязательные исправления.
В задачах 03 и 05 worker заранее даёт промежуточный статус, если статистический прогон или стендовая проверка идут долго.
Если исправление после review gate меняет дизайн, формат state, манифест или схему проверки, результат исправления проходит повторный review gate.
Коммиты делает координатор после своих проверок и git status --short.
Ручная проверка дашбордов глазами выполняется только в конце всей цепочки.

Сквозные инварианты

Рабочий контракт реализации живёт в docs/specs/2026-06-14-generator-model-time-and-startup-history.md, раздел «Рабочий контракт реализации». Задачи 02–06 берут имена настроек, формат манифеста, границу T_end и правила проверки оттуда.
event_timestamp — модельное время, а не настенные часы компьютера.
Операционные метки сервиса, история пачек, метрики здоровья и длительность тика остаются настенным временем, если отдельная задача не докажет обратное.
Живой ход часов идёт фиксированным модельным шагом GEN_TICK_SECONDS * GEN_MODEL_TIME_SPEED; промотка прошлого тоже повторяется точно при тех же настройках и чистом состоянии.
При ×K модельное время и событийный бюджет идут по модельной длительности тика, а не по реальной длительности сна процесса.
Часовой пояс модельных часов явно задан в контракте; дневной коэффициент считается по нему, а не по неявному локальному времени.
После сбоя точка возобновления считается из сохранённой связки модельного и настенного времени, а не простым datetime.now().
Стартовая история — это события плюс слепок состояния плюс манифест, чтобы не смешать данные от разных GEN_SEED, T0 и T_end.
Стартовая история покрывает [T0, T_end), живое продолжение начинается из слепка на T_end; на стыке не должно быть дублей и дыр.
Повторная проверка на чистом стенде должна быть воспроизводимой: либо команда явно чистит ClickHouse, Kafka-топики данных и состояние генератора, либо процесс идемпотентен.

Задачи

issues/01-time-and-startup-history-contract.md — контракт модельного времени и стартовой истории.
issues/02-model-time-to-clickhouse.md — минимальный поток по модельному времени до ClickHouse.
issues/03-model-speed-and-day-factor.md — ×K и дневной коэффициент по модельному времени.
issues/04-state-v2-model-resume.md — восстановление state v2 от модельной точки возобновления.
issues/05-startup-history-backfill-to-clickhouse.md — промотка прошлого, стартовая история и живое продолжение до ClickHouse.
issues/06-generated-history-as-analytics-source.md — штатный путь стенда переводится на стартовую историю как источник аналитики.

Контрольные точки

После задачи 3 нужен внешний review gate по сквозному инварианту времени: проверить, где ещё остались настенные часы, и не расходятся ли живой путь, расчёт интенсивности и сохранение состояния.
После задачи 5 нужен внешний review gate по распределениям и двум путям генерации: проверить форму данных, стык истории и живого продолжения, однородность визита до и после восстановления.

Для review gate после задачи 3 reviewer другой родословной сильно желателен. Для review gate после задачи 5 он обязателен: research показал, что форма распределений и свойства на стыке двух путей хуже ловятся одной линией проверки. Если такого reviewer-а нет, координатор останавливает цепочку и явно отдаёт решение человеку.

Финальная ручная приёмка

После задачи 6 человек смотрит Superset/Grafana и проверяет, что стенд живёт на генерации: видны история, возвраты, воронка и суточное «дыхание». Если текущих панелей не хватает для такого просмотра, создаётся отдельная задача на панель или runbook, а не расширяется эта цепочка задним числом.

Миграция уроков по ADR-0006 сознательно отслеживается отдельно. Задача 6 должна создать follow-up, если учебные материалы требуют нетривиальной переделки.

8.1 KiB Raw Blame History