272 Commits
Author SHA1 Message Date
ddadminandClaude Opus 4.8 86bba06f09 docs(handoff): handoff coordinator-loop перенесён в навык (указатель)
- Зачем:
  - авторитетная версия должна жить у навыка (dotfiles), рядом с handoff-побратимом; здесь — чтобы не плодить расходящиеся копии.
- Что:
  - полное содержимое заменено коротким указателем на dotfiles-версию.
- Проверка:
  - открыть .scratch/handoffs/2026-06-14-coordinator-loop-context-economy.md

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-14 21:39:46 +03:00
ddadminandClaude Opus 4.8 5660d9e614 docs(handoff): зафиксирован разбор экономии контекста coordinator-loop
- Зачем:
  - сохранить выводы сессии проектирования, пока свежие; без записи они теряются при компактизации и в новой сессии.
- Что:
  - добавлен handoff с диагностикой двух «пожаров» — контекста координатора и токенов — по логам прогона Codex.
  - зафиксированы prior art (obra:superpowers), два принятых правила, кандидаты-фиксы и открытые вопросы.
- Проверка:
  - открыть .scratch/handoffs/2026-06-14-coordinator-loop-context-economy.md

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-14 21:09:10 +03:00
ddadmin d35254ead6 feat(stand): переведён аналитический путь на стартовую историю
- Зачем:
  - чистый стенд должен строить аналитику из генерации, а не из архивного 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 пройден без блокирующих находок.
2026-06-14 20:22:17 +03:00
ddadmin d5408f28e9 feat(generator): добавлена стартовая история через backfill
- Зачем:
  - стенду нужна повторяемая история с живым продолжением от модельной границы без дублей и разрыва визитов.
- Что:
  - добавлен 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.
2026-06-14 19:45:58 +03:00
ddadmin fcb06da16e feat(generator): добавлено восстановление state по модельному времени
- Зачем:
  - рестарт генератора должен продолжать поток от модельной точки без дублей и смешивания state разных настроек.
- Что:
  - state v2 хранит модельную и настенную метки, скорость, timezone, T0 и seed.
  - live-восстановление считает модельную точку по настенной дельте и проверяет совместимость config.
  - добавлен путь восстановления от T_end и тесты короткого и долгого простоя.
- Проверка:
  - make generator-test.
  - ClickHouse-сценарии короткого и долгого восстановления state.
  - reviewer gate issue 04 пройден после исправления совместимости state.
2026-06-14 18:47:34 +03:00
ddadmin 589e2321b3 feat(generator): добавлено ускорение модельного времени
- Зачем:
  - ускоренный стенд должен проходить больше модельного времени и давать соответствующий событийный бюджет.
- Что:
  - расчёт интенсивности переведён на модельную длительность тика.
  - добавлена устойчивая выборка бюджета при больших λ.
  - усилены тесты ×K, дневного коэффициента и независимости от настенного часа.
- Проверка:
  - make generator-test.
  - review gate после issue 03 пройден после исправления underflow Poisson.
2026-06-14 17:48:51 +03:00
ddadmin efb07b0283 feat(generator): добавлено модельное время live-потока
- Зачем:
  - генератор должен писать события от модельной точки T0 и проверяться повторяемо в ClickHouse.
- Что:
  - добавлены настройки модельного времени и передача модельной точки в live-тик.
  - дневной коэффициент считается по модельному времени и часовому поясу.
  - обновлены проверки, compose, документация и статус issue 02.
- Проверка:
  - make generator-test.
  - два чистых ClickHouse-прогона с GEN_STATE_RESET=true дали одинаковые контрольные числа.
2026-06-14 17:23:12 +03:00
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
ddadmin 79c2c2657c docs(generator): уточнены задачи по модельному времени
- Зачем:
  - ревью выявило слабые места в критериях приёмки модельного времени.
- Что:
  - уточнены правила повторяемости, чистого прогона и review gate.
  - добавлены критерии для однородности визита через восстановление и T_end.
  - обновлён handoff с важными рисками для следующего агента.
- Проверка:
  - git diff --check.
2026-06-14 16:12:46 +03:00
ddadmin 796c3f26a9 docs(generator): добавлены задачи по модельному времени
- Зачем:
  - нужен рабочий план для реализации модельного времени и стартовой истории.
- Что:
  - добавлен parent PRD с инвариантами, зависимостями и review gate.
  - добавлены шесть локальных issue для последовательной работы.
  - добавлен handoff для продолжения в новой сессии.
- Проверка:
  - git diff --check.
2026-06-14 15:59:12 +03:00
ddadminandClaude Opus 4.8 fa93aef150 docs(context): глоссарий и спеки приведены в соответствие с ADR-0006
- Зачем:
  - ADR-0006 сделал генерацию единственным источником аналитики, а статический
    сид — архивным; глоссарий и спеки это ещё не отражали.
- Что:
  - CONTEXT.md: «статический сид» переименован в «архивный статический сид»
    (короткое имя сохранено), описан как временная кладовка значений с целью
    полного вывода; «стартовая история» получила синонимы «стартовый сид» и
    «новый сид»; раздел «Слои данных» отмечает переход аналитики на генерацию.
  - мат-спека: разделы «Персистентность через рестарты» и «Воспроизводимость»
    помечены как переописанные в спеке модельного времени (ссылкой, без повтора).
  - спека модельного времени: синоним «стартовый сид» добавлен в определение и
    в заметку о влиянии на документацию.
- Проверка:
  - git diff: термины и перекрёстные ссылки читаются непротиворечиво; ADR не
    правились (статус «архивный» не переносится в документы до ADR-0006).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-14 15:31:11 +03:00
ddadminandClaude Opus 4.8 18ac8279cd docs(handoff): зафиксирован handoff по ADR-0006 и спеке модельного времени
- Зачем:
  - сохранить контекст сессии для продолжения работы в новой сессии.
- Что:
  - добавлен handoff: что сделано и закоммичено, контекст вне артефактов, очередь шагов, ограничения.
- Проверка:
  - чтение .scratch/handoffs/2026-06-14-adr0006-source-flip-and-model-time-spec.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-14 15:07:27 +03:00
ddadminandClaude Opus 4.8 7e28cf06b9 docs(agents): язык рассуждений — английский, ответы и артефакты — русский
- Зачем:
  - кириллица занимает примерно в 1,5–2 раза больше токенов; рассуждения можно вести экономнее.
- Что:
  - добавлено правило: внутренние рассуждения и промежуточные пометки — на английском.
  - русский остаётся для ответов пользователю, документов, комментариев в коде и сообщений коммитов.
- Проверка:
  - чтение AGENTS.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-14 15:07:27 +03:00
ddadminandClaude Opus 4.8 c4cc01e206 docs(agents): уточнены правила русского языка и понятности документов
- Зачем:
  - прежняя формулировка допускала транслитерации и не требовала краткости и понятности самих документов.
- Что:
  - «устоявшийся английский» сужен до имён технологий, инструментов и кода.
  - добавлено правило: документы и объяснения — короткими фразами, простыми словами, понятность важнее буквальной точности.
- Проверка:
  - чтение AGENTS.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-14 14:52:09 +03:00
ddadminandClaude Opus 4.8 49512b190a docs(generator): зафиксированы источник аналитики и стартовая история
- Зачем:
  - генератор даёт здоровую пирамиду, и стенду нужен единый источник аналитики вместо вырожденного статического сида.
- Что:
  - добавлен ADR-0006: генерация — единственный источник аналитики, статический сид становится архивным (кладовка значений до синтеза фактуры).
  - добавлена спека модельного времени: точка отсчёта, заливка прошлого, стартовая история, сохранение состояния, воспроизводимость и проверка в два шага.
  - в ADR-0004 и ADR-0005 добавлены указатели вперёд на ADR-0006 и спеку.
- Проверка:
  - чтение документов; перекрёстные ссылки между ADR-0004/0005/0006 и спекой согласованы.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-14 14:47:20 +03:00
ddadminandClaude Opus 4.8 899a3f07a1 docs(research): зафиксировано внешнее ревью петли субагентов
- Зачем:
  - закрыть отложенный заход эксперимента: внешнее ревью результата
    автономной петли моделью другой родословной (дизайн-линия, не Кодекс).
- Что:
  - добавлена секция об итогах ревью: прогноз по находке A не оправдался,
    петля её поймала (try→fresh + регрессионный тест в коммите 640050e).
  - зафиксировано, что внешний взгляд добавил сквозные находки (расхождение
    живого/восстановленного путей, форма распределения длины визита).
  - уточнена гипотеза о пользе reviewer-а другой родословной.
- Проверка:
  - git show --stat HEAD; чтение docs/research/2026-06-11-subagent-coordinator-experiment.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-14 13:17:06 +03:00
Dmitry Dementiev ce3552eaf2 docs(research): зафиксирован эксперимент с координатором субагентов
- Зачем:
  - выводы агентного эксперимента нужны как durable-основа для будущего скилла, а не как одноразовый handoff.
- Что:
  - добавлена research note с гипотезой, протоколом, наблюдениями и ограничениями эксперимента.
  - зафиксированы роли координатора, worker-а и reviewer-а, классификация находок и инварианты будущего скилла.
- Проверка:
  - ручная перечитка docs/research/2026-06-11-subagent-coordinator-experiment.md.
2026-06-11 18:44:07 +03:00
Dmitry Dementiev 341637c810 docs(generator): зафиксирована модель времени генератора (ADR-0005)
- Зачем:
  - инвариант «время генератора ≡ реальное ×1» неудобен для учебного плана:
    медленные явления (возвраты, воронка) не успеть показать на уроке, а
    историческую глубину живой генератор не создаёт.
- Что:
  - добавлен ADR-0005: модельные часы отвязаны от настенного времени, режимы
    (живой ×1 / ускоренный ×K / заливка) — драйверы одного шва, правило 30 минут
    переопределено в модельном времени; сид-продолжение помечено как будущее.
  - в CONTEXT.md разведены три значения «сида» и добавлен термин модельного
    времени и масштаба ×K.
  - добавлен handoff с отложенным ревью петли и реконсиляцией мат-спеки.
- Проверка:
  - прочитать docs/adr/0005-generator-model-clock.md и раздел «Три значения
    слова сид» в CONTEXT.md; git log -1.
2026-06-11 18:37:27 +03:00
Dmitry Dementiev 2eaeda3308 docs(generator): зафиксирован вывод финального reviewer-цикла
- Зачем:
  - наблюдения по задаче 07 нужны для итоговой рефлексии эксперимента с субагентами.
- Что:
  - добавлен вывод о роли reviewer-а в проверке силы интеграционного теста.
- Проверка:
  - git diff -- .scratch/handoffs/2026-06-11-subagent-coordinator-experiment.md.
2026-06-11 18:26:57 +03:00
Dmitry Dementiev 6c4e0f4d16 feat(generator): подключена новая модель к steady-stream сервису
- Зачем:
  - после калибровки потока и 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.
2026-06-11 18:26:39 +03:00
Dmitry Dementiev 4a08465f7d docs(generator): дополнены наблюдения эксперимента с субагентами
- Зачем:
  - результаты первых циклов эксперимента нужно сохранить отдельно от рабочих изменений генератора.
- Что:
  - зафиксированы выводы по саморевью, reviewer-субагенту и второму кругу ревью.
  - описана классификация reviewer-находок перед отправкой worker-агенту.
- Проверка:
  - git diff --stat -- .scratch/handoffs/2026-06-11-subagent-coordinator-experiment.md.
2026-06-11 18:02:25 +03:00
Dmitry Dementiev 640050e409 feat(generator): добавлено состояние версии 2 для рестартов
- Зачем:
  - генератор должен переживать рестарт без потери популяции пользователей и коротко прерванных активных визитов.
- Что:
  - добавлен компактный state v2 для популяции, активных визитов и остатка бюджета рождений.
  - сервис генератора переведён на единый тиковый поток с сохранением и восстановлением состояния.
  - добавлена безопасная деградация для старого state v1 и битого state v2.
  - покрыты короткий и долгий простой, reset состояния и валидация вложенного state.
- Проверка:
  - uv run --with-requirements generator/requirements.txt pytest generator/tests -q.
  - git diff --check.
2026-06-11 18:01:57 +03:00
Dmitry Dementiev 8f1e997cc9 feat(generator): откалиброван поток steady-stream генератора
- Зачем:
  - поток генератора должен соответствовать модели интенсивности и профилю сида перед реализацией состояния версии 2.
- Что:
  - событийный бюджет тика переведён в рождения визитов через ожидаемую среднюю длину визита.
  - дефолты интенсивности и обычный docker-compose запуск синхронизированы с целевыми 30 событиями в минуту.
  - добавлены статистические проверки длины визита, воронки, новых пользователей, межсессионных пауз и долгого окна потока.
  - обновлены README, OPERATIONS и карточка задачи 05.
- Проверка:
  - uv run --with-requirements generator/requirements.txt pytest generator/tests -q.
  - git diff --check.
2026-06-11 17:17:34 +03:00
Dmitry Dementiev d7c5a56675 docs(generator): зафиксирован процесс эксперимента с субагентами
- Зачем:
  - перед запуском задачи 05 нужно отделить координационные договорённости от будущих изменений генератора.
- Что:
  - добавлен handoff с правилами эксперимента координатора и субагентов.
  - уточнён порядок возврата к задаче состояния версии 2 после калибровки потока.
- Проверка:
  - git diff -- .scratch/feature-data-generator/issues/06-state-v2-and-restart.md .scratch/handoffs/2026-06-11-subagent-coordinator-experiment.md.
2026-06-11 16:34:45 +03:00
Dmitry Dementiev fda5db8ad9 feat(generator): добавлена популяция пользователей
- Зачем:
  - steady-stream генератору нужны устойчивые пользователи и возвраты между визитами, чтобы поток был похож на живую модель поведения.
- Что:
  - добавлена ограниченная популяция с кулдауном возврата, ротацией новых пользователей и защитой от второго активного визита.
  - UUID переведены на единый ГПСЧ генератора, а завершение визита считается по запланированному последнему событию.
  - добавлены регрессионные тесты и обновлена документация генератора.
- Проверка:
  - uv run --with-requirements generator/requirements.txt pytest generator/tests -q
2026-06-11 16:08:37 +03:00
Dmitry Dementiev d8da27187e feat(generator): добавлен поток активных визитов по тикам
- Зачем:
  - генератор должен выпускать события визита по запланированным тикам, не приклеивая весь визит к одному запуску.
- Что:
  - добавлен тиковый слой `TickStreamGenerator` с активными визитами и выпуском созревших событий.
  - добавлена валидация потолка активных визитов относительно потолка популяции.
  - сохранён событийный смысл `event_budget` и добавлен регрессионный тест против разгона интенсивности.
- Проверка:
  - `uv run --with-requirements generator/requirements.txt pytest generator/tests -q` — 81 passed.
2026-06-11 15:32:53 +03:00
Dmitry Dementiev 642789d484 refactor(generator): разнесён сервис генератора по src-пакету
- Зачем:
  - перед активными визитами нужно отделить генеративную модель от Kafka, состояния и сервисного цикла.
- Что:
  - перенесены модули генератора в пакет `src/clickstream_generator`.
  - `generator.py` оставлен фасадом и точкой входа с совместимыми импортами.
  - обновлены Dockerfile, тесты, README, спека и issue 02.5.
- Проверка:
  - `docker build -t generator:test generator`.
  - `docker run --rm -v /home/dmitry/sources/clickstream-ch-kafka-superset-demo:/workspace -w /workspace/generator generator:test pytest tests/ -q`.
  - `python -m py_compile generator.py src/clickstream_generator/*.py` в Docker.
2026-06-11 15:00:50 +03:00
Dmitry Dementiev 48e3bf2900 docs(generator): добавлена задача уборки сервиса
- Зачем:
  - перед задачей активных визитов нужно отделить модель генератора от сервисной обвязки.
- Что:
  - добавлена спека уборки сервиса генератора перед задачей 03.
  - добавлена промежуточная issue 02.5 с критериями приёмки.
  - уточнены требования к Dockerfile и временному тиковому слою.
  - задача 03 заблокирована новой задачей уборки.
- Проверка:
  - просмотрен staged diff через `git diff --cached --stat`.
2026-06-11 13:48:24 +03:00
Dmitry Dementiev eaf4888ed9 docs(agents): обновлены правила работы агента
- Зачем:
  - локальные инструкции должны отражать актуальные правила работы с Python в репозитории.
- Что:
  - добавлено требование использовать uv для Python.
  - удалена устаревшая строка цели репозитория из AGENTS.md.
- Проверка:
  - git diff --cached -- AGENTS.md
2026-06-11 12:59:29 +03:00
Dmitry Dementiev 32f4fee41c feat(generator): добавлена модель связанного визита
- Зачем:
  - генератор должен создавать учебно полезный визит с общим click_id, правдоподобным путём и честным тиковым бюджетом событий.
- Что:
  - добавлена марковская цепочка страниц, запланированные метки времени и потолок GEN_MAX_SESSION_EVENTS.
  - добавлен набор тикового батча из нескольких визитов до рассчитанного бюджета событий.
  - обновлены тесты, README, KNOWN_ISSUES и статусы задач 01/02.
- Проверка:
  - uv run --with pytest --with-requirements generator/requirements.txt pytest generator/tests -q
2026-06-11 12:52:48 +03:00
Dmitry Dementiev d38124263a feat(generator): добавлен связанный визит в генератор
- Зачем:
  - нужен первый проверяемый срез новой модели, где один визит содержит несколько связанных событий.
- Что:
  - добавлен индекс browser-событий по click_id для выбора сид-визита как основы.
  - generate_batch теперь выпускает несколько browser-событий с одним новым click_id и общим device/geo-контекстом.
  - добавлен тест публичного контракта связанного визита.
- Проверка:
  - make generator-test.
2026-06-11 11:00:39 +03:00
Dmitry Dementiev f0370cdb90 docs(generator): добавлены задачи реализации и handoff
- Зачем:
  - переработку steady-stream генератора нужно передать агентам как набор
    проверяемых вертикальных задач, а не как один крупный rewrite.
- Что:
  - создан локальный набор из семи ready-for-agent задач для реализации новой
    иерархической модели генератора.
  - добавлен handoff с текущим состоянием обсуждения, рекомендуемым следующим
    шагом через TDD и примером команды /goal для запуска задачи 01.
- Проверка:
  - git diff HEAD~1 --stat.
2026-06-11 10:48:37 +03:00
Dmitry DementievandClaude Fable 5 bcca8f5127 docs(generator): уточнена мат-спека по итогам ревью, handoff для передачи
- Зачем:
  - повторное адверсариальное ревью нашло ошибку в формуле межсессионной
    паузы (двойной счёт кулдауна) и незакрытый контракт публикации
    device/geo; дизайн-этап завершён, работа передаётся исполнителю.
- Что:
  - исправлена формула паузы (баланс цикла, минус длительность визита);
    зафиксированы каденция device/geo «на каждое событие, как в сиде»,
    правило выбора возвращающегося, стартовое распределение страниц,
    калибровка по медиане и среднему, инвариант потолков конфигурации,
    компактное хранение профиля ссылкой на сид-сессию.
  - уточнены критерии приёмки (среднее паузы вместо медианы, счёт шага
    «товары», имена полей времени) в обеих спеках.
  - добавлен handoff .scratch/handoffs/2026-06-10-generator-spec-to-codex.md
    (передача на детальный план/реализацию), отработавший handoff от
    2026-06-09 удалён.
- Проверка:
  - цифры спеки сверены замерами по полным data/*.jsonl (стартовые страницы
    58/24/17, шаги воронки 98>=94>=56>=35>=25, device 1000 строк / 99
    уникальных); повторное ревью свежим агентом блокеров не оставило.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-10 18:02:57 +03:00
Dmitry DementievandClaude Fable 5 0b5fc64f6f docs(agents): добавлено правило понятного русского языка
- Зачем:
  - ответы и документы агентов должны быть читаемы неспециалистом,
    без англицизмов и непереведённых слов.
- Что:
  - в AGENTS.md (раздел «Обязательные правила») добавлено требование к
    языку: понятный русский, устоявшиеся английские термины допустимы,
    сложные темы объяснять доступно.
- Проверка:
  - git diff AGENTS.md; правило видно в начале раздела обязательных правил.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-10 17:34:29 +03:00
Dmitry DementievandClaude Fable 5 6efa031023 docs(generator): добавлена мат-спека модели и исправлен профиль сида
- Зачем:
  - закрыть 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>
2026-06-10 17:32:47 +03:00
Dmitry DementievandClaude Opus 4.8 bce1ded9c4 docs(handoff): добавлен handoff по переработке генератора
- Зачем:
  - продолжить работу над генератором в новой сессии без потери контекста.
- Что:
  - .scratch/handoffs/2026-06-09-generator-rework.md: где остановились,
    ссылки на ADR/спеку, следующий шаг, suggested skills, состояние git.
- Проверка:
  - прочитать .scratch/handoffs/2026-06-09-generator-rework.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-09 18:04:08 +03:00
Dmitry DementievandClaude Opus 4.8 6ddc7a90d4 docs(generator): зафиксировано направление переработки генератора
- Зачем:
  - при возврате к генератору не переоткрывать выбор «генератор vs реплей»
    и иметь готовую рамку требований под реализацию steady-stream.
- Что:
  - ADR-0004: steady-stream питается синтетическим иерархическим генератором,
    не реплеем сида (обоснование + отклонённые варианты C/B).
  - спека docs/specs/2026-06-09: требования к иерархической модели сущностей
    и критерии приёмки; математика делегирована follow-up-спеке.
  - CONTEXT.md: термины «популяция пользователей», «возвращающийся пользователь».
- Проверка:
  - прочитать ADR-0004 и спеку; сверить термины в CONTEXT.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-09 18:04:00 +03:00
ddadminandDmitry Dementiev dd2c3cdaf9 docs(generator): зафиксирован дефект генеративной модели и план доработки
- Зачем:
  - генератор не влит и неочевидно почему; при возврате к нему легко
    переоткрывать заново вывод, что click_id на событие ломает семантику визита.
- Что:
  - добавлен KNOWN_ISSUES.md: модель интенсивности ок, модель сущностей неверна,
    план перехода на иерархию пользователь -> сессия -> событие.
  - в шапку README.md добавлено предупреждение со ссылкой на KNOWN_ISSUES.md.
- Проверка:
  - прочитать generator/KNOWN_ISSUES.md и сверить с generate_batch() в generator.py.
2026-06-09 17:27:17 +03:00
ddadminandDmitry Dementiev 40633602f5 docs(plans): добавлен план инкрементальной загрузки ETL v2
- Зачем:
  - нужно зафиксировать архитектуру перехода от full refresh к инкрементальной загрузке
  - план служит референсом для реализации и code review
- Что:
  - добавлен plans/incremental-etl-v2.md с полным описанием:
    * архитектура watermark (event_ts + lookback 5min)
    * DDL для meta.etl_watermarks_history с TTL 30 дней
    * SQL шаблоны для всех слоев (ODS, DDS, DM)
    * структура DAG с параллельной загрузкой ODS
    * функции get_watermark и save_watermark
    * алерты Grafana для late arrivals
    * демонстрация late arrivals через комментарии и логи
    * сценарии тестирования
    * оценка трудозатрат (15-16 часов)
- Проверка:
  - файл создан: plans/incremental-etl-v2.md
  - структура соответствует принятой архитектуре
  - все параметры согласованы (TTL, lookback, параллельность)
2026-06-09 17:27:17 +03:00
ddadminandDmitry Dementiev d97be5fa56 feat(monitoring): добавлен дашборд Grafana для мониторинга generator
- Зачем:
  - нужна визуализация метрик 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)
2026-06-09 17:27:17 +03:00
ddadminandDmitry Dementiev a70999d77a fix(generator): устранены риски стабильности из code review
- Зачем:

  - ревью выявило: фатальный старт при битом state, отсутствие retry в runtime

  - нужна graceful degradation и самовосстановление при сбоях Kafka

- Что:

  - GeneratorState.from_dict() теперь валидирует rng_state через setstate()

  - добавлен from_dict_safe() для graceful degradation (лог + start fresh)

  - KafkaPublisher: retry + reconnect в publish(), retry в flush()

  - KafkaBatchHistory: retry + reconnect в add(), retry в flush()

  - KafkaStateManager: retry в save(), load(), flush()

  - тесты: валидация state, graceful degradation, retry поведение

- Проверка:

  - make generator-test: 59 тестов проходят

  - docker compose restart generator - продолжает с tick=8 (was 6)

  - GEN_STATE_RESET=true - начинает с tick=1
2026-06-09 17:27:17 +03:00
ddadminandDmitry Dementiev e9a46e47ae fix(kafka): обновлено хранение state генератора без pickle
- Зачем:
  - упростить и сделать безопаснее сериализацию состояния генератора
  - повысить устойчивость старта при временной недоступности Kafka
- Что:
  - заменена сериализация rng state на JSON-safe формат без pickle/base64
  - добавлено восстановление tuple-структуры rng state после json
  - добавлен общий retry с exponential backoff для ensure_topics
  - обновлена документация по continuity и ограничениям после рестарта
  - расширены тесты state-сценариев и retry-логики
- Проверка:
  - make generator-test
  - 50 passed
2026-06-09 17:27:16 +03:00
ddadminandDmitry Dementiev 31e8901eb0 feat(generator): добавлено сохранение стейта между рестартами
- Зачем:

  - генератор должен продолжать работу с места остановки после падения/рестарта

  - нужно сохранять 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
2026-06-09 17:27:16 +03:00
ddadminandDmitry Dementiev ea114153b9 fix(generator): обработка findings из финального ревью
- Изолированы ошибки history-канала: best-effort с логированием, не валят тик
- Добавлено явное создание топика generator_batch_history при старте
- Добавлена защита от пустого словаря (ValueError при загрузке)
- Обновлена документация о структуре тестов
- Исправлены тесты на пустой словарь

Ревью: изоляция ошибок history, явное создание топика, защита от пустых данных
2026-06-09 17:27:16 +03:00
ddadminandDmitry Dementiev ffe81167c3 refactor(generator): удалён in-memory fallback для истории батчей
- Удалён класс InMemoryBatchHistory и вся fallback-логика
- Упрощён KafkaBatchHistory: убраны _initialized, get_stats(), обработка ошибок
- Обновлена документация (generator/README.md, docs/OPERATIONS.md)
- Упрощены тесты, удалены тесты для удалённого функционала
- Код стал честнее: без Kafka генератор падает при старте

Ревьюер: Prometheus даёт достаточно visibility, fallback избыточен
2026-06-09 17:27:16 +03:00
ddadminandDmitry Dementiev 731d991f94 refactor(generator): история batch в Kafka вместо ClickHouse
- Зачем:
  - ревью 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
2026-06-09 17:27:16 +03:00
ddadminandDmitry Dementiev 36ecbc62b1 test(generator): добавлен pytest и реорганизованы тесты
- Зачем:
  - были только 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 тестов пройдено
2026-06-09 17:27:16 +03:00
ddadminandDmitry Dementiev 04541677ff feat(generator): доработка по ревью rev5 — тики, метрики, история
- Зачем:
  - ревью rev5 выявило несоответствие плану: дефолт 60s против 5s,
    неработающий jitter, отсутствие Prometheus-метрик и персистентности
- Что:
  - дефолт GEN_TICK_SECONDS изменён с 60s на 5s (steady-stream режим)
  - реализован GEN_JITTER_PCT в расчёте объёма тика (вариативность)
  - добавлены Prometheus метрики: generator_events_total,
    generator_publish_errors_total, generator_tick_duration_seconds,
    generator_last_success_timestamp (порт 9109)
  - добавлен ClickHouseBatchHistory с записью в meta.generator_batches
  - lazy import kafka-python для тестов без Kafka
  - обновлён scrape_config в configs/prometheus.yml
  - удалён нерабочий verify_kafka.py
- Проверка:
  - test_comprehensive.py: 9/9 тестов пройдено
  - docker build -t generator:rev5 . — успешно
  - docker-compose.yml валиден
2026-06-09 17:27:01 +03:00
ddadminandDmitry Dementiev e8d1c9efa9 feat(infra): добавлен автономный генератор событий для Kafka
- Зачем:
  - нужен постоянный поток данных для демонстрации работы стека
  - текущий 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 сообщения
2026-06-09 17:27:01 +03:00
ddadminandDmitry Dementiev 7c6cfd7d18 docs(docs): обновлён план генератора по интеграции Prometheus
- Зачем:
  - зафиксировать решение об observability генератора на уровне MVP-плана
- Что:
  - добавлены требования по /metrics, scrape_config и target generator:9109
  - добавлен env-параметр GEN_METRICS_PORT
  - обновлены шаг внедрения и критерии успеха
- Проверка:
  - проверен diff только для plans/generator_demo_stream_plan.md
2026-06-09 17:26:31 +03:00