# Генератор кликстрима

Клиентская сторона стенда: отсюда берётся поток событий — широкое событие по
образцу облачной выгрузки Яндекс Метрики. Устройство и принятые решения —
спека [«Генератор (этап 2)»](../docs/specs/2026-08-01-generator.md).

Пока здесь контракт схемы события и план состава мира — событий генератор ещё
не порождает.

## Что где лежит

- `src/clickstream_generator/world.py` — конфигурация мира: все его числа
  одним местом. Правка любого — смена мира; крутить их и предлагается.
- `src/clickstream_generator/seeds.py` — иерархия зёрен: кто из какого
  подпотока берёт случайность. На ней держится весь детерминизм.
- `src/clickstream_generator/plan.py` — план состава: кто есть в мире в
  день D. Когорты, приток, двухкуковые пары и счётчики — до генерации
  событий.
- `src/clickstream_generator/schema.py` — контракт схемы: чистые данные о
  колонках выгрузки. Собственность генератора; из него выводятся сам
  генератор, его валидация и описание выгрузки в доках.
- `src/clickstream_generator/schema_doc.py` — сборка «описания выгрузки»
  ([`docs/formats/clickstream-event.md`](../docs/formats/clickstream-event.md))
  из контракта. Документ руками не правят — пересобирают.
- `tests/` — инварианты контракта, свежесть описания и обещания плана:
  чистота от зерна, приток, гарантия двухкуковых пар.

## Команды

Из корня репозитория:

- `make test` — тесты генератора;
- `make lint` — ruff: проверка и формат;
- `make typecheck` — ty: проверка типов;
- `make docs` — пересобрать описание выгрузки.

Python и зависимости — через `uv`, версии закреплены в `uv.lock`: на этом
держится обещание побайтовой воспроизводимости (спека, раздел 2).