docs(generator): README — черновой раздел «Как это работает»

Зачем: код генератора компактен, но нетривиален: многое в нём — соглашения, а
не конструкции, и чтением они не выводятся. Ближайшая опасность конкретна —
следующий этап трогает и план, и день, а вставка броска в середину функции
выглядит безобидно и молча меняет весь мир.

Что: цепочка от корневого зерна до строк событий; ленивость мира — когорта по
требованию и предыстория до D0, отсюда «любой день собирается сам по себе»;
правило порядка бросков внутри подпотока с механикой и способом обнаружения
промаха; причина целочисленной случайности со ссылкой на спеку. Раздел помечен
черновым: по сути верен, но на понятность читателем со стороны не выверен —
выверка вместе с полным путеводителем, тикет #48.

Проверка: `make lint` чист, `make test` — 353 passed; правка только в README.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-02 16:28:14 +03:00
co-authored by Claude Opus 5
parent eb433ad023
commit 7dcd1c9ba3
+27
View File
@@ -7,6 +7,33 @@
События уже есть: день-функция отдаёт по паре (зерно, D) упорядоченный поток
pageview. Торговые события и запуск снаружи — за следующими тикетами.
## Как это работает
> Раздел черновой. По сути он верен, но на понятность читателем со стороны не
> выверен: пишет его тот, кто держит устройство генератора в голове, а это
> худший судья понятности. Выверка — вместе с путеводителем, тикет #48.
Цепочка одна и всегда та же: корневое зерно → подпотоки по позиции в дереве
→ когорта дня (кто впервые пришёл, сколько раз вернётся, чей паспорт какой)
→ аудитория дня, то есть когорта плюс возвраты когорт окна → визиты этих кук
→ строки событий. Мир при этом ленив: когорта считается по требованию, а до
D0 живёт предыстория, поэтому любой день собирается сам по себе — прожитая
история для него не нужна и на него не влияет.
Главное правило для того, кто придёт следующим: **внутри подпотока порядок
бросков — часть контракта.** Броски раздаёт один генератор подряд, и k-й
бросок достаётся тому, кто спросил k-м. Приписать новый бросок в конец
функции безопасно: у прежних он ничего не отнимает. Вставить в середину —
значит сдвинуть все броски после него, а с ними и весь мир: события того же
дня станут другими, счётчики канонического мира разойдутся с манифестом, и
поймается это не ошибкой, а красным чеком. Ровно поэтому паспорта кук в
`plan.cohort` бросаются последними.
Случайность целочисленная — только диапазоны и выбор по целым весам: готовые
распределения numpy расходятся между версиями и архитектурами, а обещано
побайтовое совпадение (спека, раздел 2). Отсюда `weights.py` вместо
`rng.choice` с вероятностями.
## Что где лежит
- `src/clickstream_generator/world.py` — конфигурация мира: все его числа