- Зачем:
- список DAG'ов должен читаться лесенкой ddl_init → world_init →
world_next_day, а путь менти — проходиться пустыми формами
(issue #4, спека редизайна пути менти, решения 2–3).
- Что:
- generator_control переименован в world_init, дефолт операции —
import; next-day ушёл из выпадашки в отдельный DAG;
- новый беспараметрный world_next_day: расписание */30 * * * *,
создаётся на паузе, catchup=False, max_active_runs=1; общие
задачи вынесены в airflow/dags/utils/startup_history_tasks.py;
- доки и контрактные тесты обновлены синхронно; быстрый старт
README — без make ddl, схему создаёт DAG ddl_init.
- Проверка:
- make test (210 + 31) и make lint зелёные;
- живая приёмка на чистом стенде: world_init пустой формой
импортировал эталонный мир за 217 с (3 дня, 280 437 событий),
world_next_day после снятия с паузы добавляет ровно один день
за прогон, дашборд Superset собирается.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- менти собирал мир генерацией (минуты и десятки минут CPU); теперь
готовый трёхдневный мир загружается импортом за ~2 минуты, и числа
у всех менти совпадают число-в-число (issue #3).
- Что:
- артефакт data/startup_history/reference-world.json.xz в git:
3 модельных дня daily-wave, ~850 МБ JSON → 32 МБ xz;
- чтение и запись артефакта понимают .xz потоково (lzma); пустое поле
artifact_path в пульте и make startup-history-import читают эталон;
- длительность профиля daily-wave стала 3d — в тон эталонному миру;
- предпроверка чистого стенда ставит зависимости генератора через uv;
экспорт и импорт разведены отдельными переменными Makefile;
- доки и runbook обновлены; новые контрактные тесты: xz round-trip
и дефолтные пути артефакта.
- Проверка:
- make test (210 + 31) и make lint зелёные; импорт на чистом стенде
за 2м03с, manifest совпал (280437 событий), Superset-проверка
зелёная; независимое ревью — APPROVED.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- менти доставался плоский тестовый профиль ci; учебный профиль
должен быть один — daily-wave с суточной волной (issue #6).
- Что:
- дефолт daily-wave во всех точках: форма пульта generator_control,
launch.py (API и CLI), Config, Makefile, четыре shell-скрипта.
- автопроверки передают ci явно; контрактный тест пульта теперь
проверяет сам дефолт Param профиля (через AST), а не подстроку.
- доки в том же изменении: README, OPERATIONS, TEST_PLAN,
generator/README, runbook startup-history.
- Проверка:
- make test (206 + 31 passed) и make lint — зелёные.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- форма Trigger DAG требовала заполнить все поля: канонический запуск
«выбрать профиль, остальное пусто» через UI был невозможен (находка F1
ручного HITL); артефакты backfill (data/*.json, 49 МБ) рисковали
попасть в коммит.
- Что:
- пять необязательных Param переведены на Param(None, type=["null",
"string"]) — идиома необязательного поля, проверено по Context7
(Airflow 2.10.5); все места чтения уже None-безопасны (or "").
- контрактный тест дополнен: у необязательных Param есть "null" в type,
у operation/profile — нет.
- .gitignore: правило data/*.json (сиды data/*.jsonl остаются под git);
задача 21 закрыта в .scratch.
- Проверка:
- make test (205 + 31 passed) и make lint — зелёные.
- Зачем:
- режим кормления стенда порциями: менти триггерит «следующий день»,
видит полный цикл DWH за один шаг (задача 13, вариант 2 — генерация
от слепка T_end).
- Что:
- новый ограниченный режим next-day: восстановление мира из state,
генерация ровно [T_end, T_end+24h), публикация данные -> state ->
манифест (манифест — точка фиксации, автоотката нет).
- операция next-day в DAG generator_control: своя предпроверка границы
вместо clean-guard, идемпотентность через параметр expected_t_end.
- цепочка границ — накопительное поле boundaries в манифесте, старый
формат читается как [T0, T_end]; импорт не изменён.
- новая проверка цепочки (make generated-history-chain-check): непарные
счётчики и однородность по каждой границе, явный статус нулевого
стыка, хвост за границей по всем четырём топикам, литералы в UTC
с микросекундами.
- документация OPERATIONS.md: глагол, предпроверка, восстановление
после сбоя, ограничение retention; в задаче 13 — решения двух слепых
ревью постановки и кода с аргументами отклонений.
- Проверка:
- make test: 204 теста генератора + 31 контракт корня, зелёные.
- make generated-history-chain-check: зелёный, 2 внутренние границы,
непарные счётчики нулевые; учебный цикл: DM 322 -> 10026 -> 19196
за два next-day подряд.
- make generated-history-runtime-check (регрессия задачи 20): зелёный.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- коммит-гейт не запускал корневые контрактные тесты, а часть подтверждённых обходов могла снова смешать разные миры генератора.
- Что:
- добавлены цели make test, make lint и contract-test с тихим pytest-выводом через Docker.
- закрыты обходы через generator-reset, неизвестную версию state и fail-open проверку DM-витрин.
- усилены поведенческие контракты CHECK_LIVE_SEAM, профиля manifest и pause-check etl_pipeline; обновлены документы и issue 19.
- Проверка:
- make test; make lint; git diff --check.
- Зачем:
- зелёный результат проверок должен означать фактический стык и точный контракт дашборда.
- Что:
- проверка startup-history читает manifest, требует live seam и непустой ODS.
- добавлен быстрый runtime gate для daily-wave и live-продолжения.
- Superset sync ограничен целевым dashboard и сверяет существенные params.
- Проверка:
- docker target tests; make generator-test; make generated-history-runtime-check.
- Зачем:
- свежий стенд должен доходить до generator_control без скрытых ручных шагов и зависаний.
- Что:
- quick start явно готовит DDL и откладывает Superset init до готового DM.
- generator_control проверяет паузу etl_pipeline до мутирующих шагов.
- make up пересобирает Airflow и поднимает базовый набор сервисов.
- Проверка:
- make generator-test; docker compose config --quiet; make clean; make up; make ddl.
- Зачем:
- старый state и ручной live-генератор могли тихо писать события в новый мир данных.
- Что:
- добавлена общая проверка чистого стенда для Airflow и host-путей.
- защищены backfill, import, continue и clean-start сценарии live-generator.
- описан миграционный отказ старого state.
- Проверка:
- make generator-test; docker compose config --quiet; py_compile; bash -n.
- Зачем:
- визит после восстановления не должен менять браузер и источники перехода внутри одного click_id.
- Что:
- добавлен base_click_id в state v3 для восстановления донора фактуры.
- исправлено восстановление timestamp offset без потери микросекунд.
- расширены тесты и стыковая проверка browser/source и device/os/geo.
- Проверка:
- uv run --with-requirements generator/requirements.txt pytest generator/tests -q.
- bash -n scripts/check_generated_analytics.sh.
- git diff --cached --check.
- Зачем:
- суточная волна должна быть видна на занятии за минуты, а не за сутки работы стенда.
- Что:
- профиль daily-wave переведён на speed 60 при тике 1 секунда.
- приглушены подробные live-логи успешного тика без изменения сохранения state.
- обновлены тесты, спека и инструкции запуска быстрого профиля.
- Проверка:
- make generator-test.
- git diff --cached --check.
- Зачем:
- нужен основной ручной интерфейс стенда для backfill/import/check без консольной матрицы переменных.
- Что:
- добавлен DAG generator_control с параметрами Airflow, ветвлением операций и ожиданием ETL.
- вынесена общая логика запуска и предпроверок генератора для Airflow.
- обновлены compose-настройки, зависимости, тесты и документация по пульту.
- Проверка:
- uv run --with pytest --with-requirements generator/requirements.txt pytest generator/tests -q.
- docker compose config --quiet.
- Зачем:
- чистый стенд должен строить аналитику из генерации, а не из архивного JSONL-сида.
- Что:
- добавлены команды generated-history-analytics и generated-history-check.
- обновлены README, operations и Superset-документы под путь generator backfill -> DM -> Superset.
- создан follow-up на миграцию учебных материалов с архивного сида.
- Проверка:
- make generated-history-analytics.
- make generated-history-check.
- reviewer gate issue 06 пройден без блокирующих находок.
- Зачем:
- стенду нужна повторяемая история с живым продолжением от модельной границы без дублей и разрыва визитов.
- Что:
- добавлен backfill-режим с `GEN_MODEL_T_END`, manifest и state на `T_end`.
- live-запуск восстанавливается из manifest без настенной дельты и проверяет совместимость state.
- добавлены SQL-проверки формы данных, повторяемости и стыка backfill с live.
- Проверка:
- make generator-test.
- два чистых ClickHouse-прогона backfill дали одинаковые manifest checksums и digest.
- reviewer gate issue 05 пройден после исправлений state/manifest.
- Зачем:
- рестарт генератора должен продолжать поток от модельной точки без дублей и смешивания state разных настроек.
- Что:
- state v2 хранит модельную и настенную метки, скорость, timezone, T0 и seed.
- live-восстановление считает модельную точку по настенной дельте и проверяет совместимость config.
- добавлен путь восстановления от T_end и тесты короткого и долгого простоя.
- Проверка:
- make generator-test.
- ClickHouse-сценарии короткого и долгого восстановления state.
- reviewer gate issue 04 пройден после исправления совместимости state.
- Зачем:
- ускоренный стенд должен проходить больше модельного времени и давать соответствующий событийный бюджет.
- Что:
- расчёт интенсивности переведён на модельную длительность тика.
- добавлена устойчивая выборка бюджета при больших λ.
- усилены тесты ×K, дневного коэффициента и независимости от настенного часа.
- Проверка:
- make generator-test.
- review gate после issue 03 пройден после исправления underflow Poisson.
- Зачем:
- генератор должен писать события от модельной точки T0 и проверяться повторяемо в ClickHouse.
- Что:
- добавлены настройки модельного времени и передача модельной точки в live-тик.
- дневной коэффициент считается по модельному времени и часовому поясу.
- обновлены проверки, compose, документация и статус issue 02.
- Проверка:
- make generator-test.
- два чистых ClickHouse-прогона с GEN_STATE_RESET=true дали одинаковые контрольные числа.
- Зачем:
- после калибровки потока и state v2 генератор нужно принять как рабочий steady-stream источник, а не как исторически сломанный прототип.
- Что:
- добавлен сервисный тест multi-event визита с мок-публикацией во все четыре Kafka-топика.
- compose позволяет переопределять демо-параметры генератора без правки файла, сохраняя внутренние контейнерные адреса.
- README, OPERATIONS, KNOWN_ISSUES и карточка задачи синхронизированы с новой моделью и state v2.
- Проверка:
- uv run --with-requirements generator/requirements.txt pytest generator/tests -q.
- git diff --check.
- GEN_STATE_RESET=true GEN_POPULATION_MAX=123 docker compose config.
- Зачем:
- генератор должен переживать рестарт без потери популяции пользователей и коротко прерванных активных визитов.
- Что:
- добавлен компактный state v2 для популяции, активных визитов и остатка бюджета рождений.
- сервис генератора переведён на единый тиковый поток с сохранением и восстановлением состояния.
- добавлена безопасная деградация для старого state v1 и битого state v2.
- покрыты короткий и долгий простой, reset состояния и валидация вложенного state.
- Проверка:
- uv run --with-requirements generator/requirements.txt pytest generator/tests -q.
- git diff --check.
- Зачем:
- поток генератора должен соответствовать модели интенсивности и профилю сида перед реализацией состояния версии 2.
- Что:
- событийный бюджет тика переведён в рождения визитов через ожидаемую среднюю длину визита.
- дефолты интенсивности и обычный docker-compose запуск синхронизированы с целевыми 30 событиями в минуту.
- добавлены статистические проверки длины визита, воронки, новых пользователей, межсессионных пауз и долгого окна потока.
- обновлены README, OPERATIONS и карточка задачи 05.
- Проверка:
- uv run --with-requirements generator/requirements.txt pytest generator/tests -q.
- git diff --check.
- Зачем:
- steady-stream генератору нужны устойчивые пользователи и возвраты между визитами, чтобы поток был похож на живую модель поведения.
- Что:
- добавлена ограниченная популяция с кулдауном возврата, ротацией новых пользователей и защитой от второго активного визита.
- UUID переведены на единый ГПСЧ генератора, а завершение визита считается по запланированному последнему событию.
- добавлены регрессионные тесты и обновлена документация генератора.
- Проверка:
- uv run --with-requirements generator/requirements.txt pytest generator/tests -q
- Зачем:
- генератор должен выпускать события визита по запланированным тикам, не приклеивая весь визит к одному запуску.
- Что:
- добавлен тиковый слой `TickStreamGenerator` с активными визитами и выпуском созревших событий.
- добавлена валидация потолка активных визитов относительно потолка популяции.
- сохранён событийный смысл `event_budget` и добавлен регрессионный тест против разгона интенсивности.
- Проверка:
- `uv run --with-requirements generator/requirements.txt pytest generator/tests -q` — 81 passed.
- Зачем:
- генератор должен создавать учебно полезный визит с общим click_id, правдоподобным путём и честным тиковым бюджетом событий.
- Что:
- добавлена марковская цепочка страниц, запланированные метки времени и потолок GEN_MAX_SESSION_EVENTS.
- добавлен набор тикового батча из нескольких визитов до рассчитанного бюджета событий.
- обновлены тесты, README, KNOWN_ISSUES и статусы задач 01/02.
- Проверка:
- uv run --with pytest --with-requirements generator/requirements.txt pytest generator/tests -q
- Зачем:
- нужен первый проверяемый срез новой модели, где один визит содержит несколько связанных событий.
- Что:
- добавлен индекс browser-событий по click_id для выбора сид-визита как основы.
- generate_batch теперь выпускает несколько browser-событий с одним новым click_id и общим device/geo-контекстом.
- добавлен тест публичного контракта связанного визита.
- Проверка:
- make generator-test.
- Зачем:
- закрыть Open questions спеки формы доработки перед передачей на
реализацию; адверсариальное ревью показало, что прежние ориентиры
(популяция/паузы/интенсивность) взаимно несовместимы, а документы
опираются на неверный факт о сиде («1..7 событий на визит»).
- Что:
- добавлена docs/specs/2026-06-10-generator-math-model.md: марковская
цепочка по страницам, формула связи «популяция-интенсивность-пауза»
(λ по умолчанию 30/мин), кулдаун возврата, правило 30 минут на рестарт,
критерии приёмки.
- в CONTEXT.md добавлен профиль сид-датасета (полный замер: длины визитов
1..27, медиана 10, конверсия 25%, петли и события после /confirmation)
и исправлено ложное «разброс времени внутри click_id <= 1 мин».
- исправлен факт «1..7 событий» в KNOWN_ISSUES.md и ADR-0004; критерии
Validation спеки формы доработки приведены к фактам сида.
- Проверка:
- перекрёстные ссылки между спеками/ADR/CONTEXT.md открываются; цифры
профиля сида воспроизводятся скриптом подсчёта по полным data/*.jsonl.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- генератор не влит и неочевидно почему; при возврате к нему легко
переоткрывать заново вывод, что click_id на событие ломает семантику визита.
- Что:
- добавлен KNOWN_ISSUES.md: модель интенсивности ок, модель сущностей неверна,
план перехода на иерархию пользователь -> сессия -> событие.
- в шапку README.md добавлено предупреждение со ссылкой на KNOWN_ISSUES.md.
- Проверка:
- прочитать generator/KNOWN_ISSUES.md и сверить с generate_batch() в generator.py.
- Зачем:
- нужна визуализация метрик generator в реальном времени
- Prometheus job уже настроен, не хватает Grafana dashboard
- Что:
- добавлен provisioning-файл dashboards/generator-overview.json
- 6 разделов: Overview, Events by Topic, Errors, Tick Statistics, Status, Info
- Overview: Total Events/min (все 4 топика), Tick Duration (p50/p99)
- Events by Topic: bar chart Events per Hour, Events Rate, Total Events
- Errors: Total Errors, Error Rate, Errors by Topic (с 'or on() vector(0)')
- Tick Statistics: Duration Distribution, Hour Factor (text), Tick Interval (text)
- Status: Generator Status (threshold 120s), Generator Health (heartbeat), Time Since Last Tick
- Info: команды и предупреждения о хардкоде GEN_TICK_SECONDS=5s
- исправлены панели ошибок с 'or on() vector(0)' для корректного отображения 0
- заменен heatmap на bar chart для стабильности
- добавлены пояснения про Events/min = сумма 4 связанных топиков
- Hour Factor синхронизирован с кодом генератора (00-05/09-18)
- Generator Health: переименовано из State Management с value mappings
- обновлены docs/OPERATIONS.md и generator/README.md
- удален устаревший plans/generator-monitoring-plan.md
- Проверка:
- дашборд открывается на http://localhost:3000/d/generator-overview
- все панели отображают данные корректно (протестировано через Playwright)
- ошибки показывают 0 вместо No data
- Events/min корректно отображает сумму всех 4 топиков (~800-1000/min)
- Зачем:
- упростить и сделать безопаснее сериализацию состояния генератора
- повысить устойчивость старта при временной недоступности Kafka
- Что:
- заменена сериализация rng state на JSON-safe формат без pickle/base64
- добавлено восстановление tuple-структуры rng state после json
- добавлен общий retry с exponential backoff для ensure_topics
- обновлена документация по continuity и ограничениям после рестарта
- расширены тесты state-сценариев и retry-логики
- Проверка:
- make generator-test
- 50 passed
- Зачем:
- генератор должен продолжать работу с места остановки после падения/рестарта
- нужно сохранять continuity тиков и состояние RNG для воспроизводимости
- Что:
- добавлен GeneratorState dataclass (tick, rng_state, last_batch_id, timestamp)
- добавлен KafkaStateManager для работы с compact topic generator_state
- топик создаётся с cleanup.policy=compact (хранится только последнее значение)
- интеграция в GeneratorService: восстановление при старте, сохранение после тика
- новые env: GEN_STATE_ENABLED (по умолчанию true), GEN_STATE_RESET (по умолчанию false)
- добавлены тесты test_state.py
- обновлена документация README.md
- Проверка:
- make generator-test (45 тестов проходят)
- docker compose restart generator - продолжает с сохранённого tick
- GEN_STATE_RESET=true - начинает с tick=1
- Изолированы ошибки history-канала: best-effort с логированием, не валят тик
- Добавлено явное создание топика generator_batch_history при старте
- Добавлена защита от пустого словаря (ValueError при загрузке)
- Обновлена документация о структуре тестов
- Исправлены тесты на пустой словарь
Ревью: изоляция ошибок history, явное создание топика, защита от пустых данных
- Удалён класс InMemoryBatchHistory и вся fallback-логика
- Упрощён KafkaBatchHistory: убраны _initialized, get_stats(), обработка ошибок
- Обновлена документация (generator/README.md, docs/OPERATIONS.md)
- Упрощены тесты, удалены тесты для удалённого функционала
- Код стал честнее: без Kafka генератор падает при старте
Ревьюер: Prometheus даёт достаточно visibility, fallback избыточен
- Зачем:
- ревью rev5: ClickHouse-интеграция была проблемной (порт 9000 native vs HTTP,
неработающий fallback, отсутствие DDL для базы meta)
- архитектурно чище: генератор остаётся pure Kafka producer,
история доступна для аналитики через стандартный ingestion
- Что:
- удален ClickHouseBatchHistory, clickhouse-connect зависимость
- добавлен KafkaBatchHistory с записью в топик generator_batch_history
- добавлен BatchRecord.to_dict() для JSON-сериализации
- добавлен рабочий fallback: Kafka → InMemory при недоступности
- удален pytest-asyncio (не использовался)
- добавлены тесты test_kafka_history.py (15 тестов) и test_service.py (6 тестов)
- обновлена документация: топик вместо таблицы ClickHouse
- Проверка:
- make generator-test: 44/44 тестов пройдено
- docker-compose валиден, генератор не зависит от clickhouse
- Зачем:
- были только standalone скрипты без системы запуска
- нужна стандартная система тестирования для CI/CD
- Что:
- добавлен pytest и pytest-asyncio в requirements.txt
- создана директория tests/ с conftest.py (fixtures)
- разделены тесты по модулям: test_config, test_generation, test_history
- добавлены команды в Makefile: generator-test, generator-test-build, generator-test-cov
- удалены устаревшие test_local.py и test_comprehensive.py
- обновлена документация в README.md
- Проверка:
- make generator-test — 23/23 тестов пройдено
- Зачем:
- нужен постоянный поток данных для демонстрации работы стека
- текущий batch-загрузчик не позволяет показать streaming-сценарии
- Что:
- добавлен сервис generator с режимом steady (Poisson-интенсивность)
- генератор публикует в 4 топика: browser/location/device/geo_events
- сохраняются связи event_id и click_id между событиями
- сборка через uv для скорости и компактности образа
- добавлены команды generator-* в Makefile
- комплексные тесты: валидация, статистика, формат сообщений
- Проверка:
- `docker run --rm -v $(pwd)/..:/workspace -w /workspace/generator generator:test python test_comprehensive.py` — 8/8 тестов
- `make generator-up` — 3 тика без ошибок, отправлено 2904 сообщения
ddadminandClaude Fable 5
Dmitry Dementiev