docs(specs): итог тикета #203 внесен в раздел 9 спеки программы лаб

- Зачем:
  - раздел 9 отсылал к открытому тикету #203; решение принято, указатель
    должен вести на итог, а не на вопрос.
- Что:
  - фраза «докуда ведет карта #182» заменена итогом: карта закрыта приемкой
    спеки, исполнение ведет карта #206.
- Проверка:
  - вычитка раздела 9 файла docs/specs/2026-09-01-labs-program.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.env.example

@@ -7,6 +7,7 @@ CLICKHOUSE_02_TCP_PORT=29001
 CLICKHOUSE_CLUSTER_SECRET=cluster-26-secret
 CLICKHOUSE_DEFAULT_PASSWORD=default-26-local
 CLICKHOUSE_ETL_PASSWORD=etl-26-writer
+CLICKHOUSE_LIFECYCLE_PASSWORD=lifecycle-26-owner
 CLICKHOUSE_BI_PASSWORD=bi-26-reader
 CLICKHOUSE_ANALYST_PASSWORD=analyst-26-reader
 CLICKHOUSE_GRAFANA_PASSWORD=grafana-26-reader

AGENTS.md

@@ -82,6 +82,11 @@ Airflow) и названия из кода. Если для понятия ес
   `generator/` — код генератора. Правишь даги или Superset — зови корневую,
   правишь генератор — зови из `generator/`.
 - Изменения держать минимальными и в границах задания.
+- `make clean` полностью удаляет постоянное состояние стенда. Перед этой
+  командой назови состояние вне прикладного мира, которое требуется удалить,
+  и объясни, почему `make rebuild-storage` его не удаляет. При изменении DDL
+  или проверке на чистых данных по умолчанию используй адресную очистку либо
+  `make rebuild-storage`.
 - Куда класть новую проверку, что утверждает каждая цель `make` и почему смоук
   обязан оставаться быстрым — [`docs/architecture/testing.md`](docs/architecture/testing.md).
 - Секреты не коммитить: настройки — через `.env`, образец — `.env.example`.
@@ -152,6 +157,10 @@ Airflow) и названия из кода. Если для понятия ес
   дефис (`clickstream-event.md`). Ни даты, ни номера: документ не событие
   истории, а текущее описание живого формата — и собирается из кода, а не
   пишется руками.
+- Имена файлов в `docs/labs/` — слаг строчными латинскими буквами через дефис
+  (`top-pages-daily.md`), индекс папки — `README.md`. Здесь живут ТЗ учебных
+  заданий. Ни даты, ни номера: задание — не событие истории, а живой документ,
+  и правится он вместе с тем, о чем говорит. Слаг называет предмет задания.
 - Имена файлов в `docs/adr/` — `NNNN-краткое-имя.md`: сквозной номер из четырёх
   цифр и слаг (`0001-stand-services.md`). Решения нумеруются подряд, дата
   в имени не нужна.

CONTEXT.md

@@ -118,8 +118,8 @@ ClickHouse. Форма файла решена, длина — нет: стро
 
 **Стартовый мир**:
 Первые восемь дней оси (понедельник по понедельник), которыми стенд
-наполняется при каждом `make up`. Маленький кусок эталонного мира, всегда
+наполняется при каждом `make up`. Он же эталонный мир, всегда один и тот же:
-один и тот же: на нём принимаются следующие этапы.
+на нем принимаются следующие этапы.
 _Избегать_: зерновой мир
 
 **Опись мира**:
@@ -209,3 +209,8 @@ _Избегать_: описание схемы, документация кон
 потоковый приём событий.
 _Избегать_: путать с приёмником и пакетным режимом — те про сторону
 генератора, про отправку; забор — про сторону хранилища, про чтение.
+
+**Техническая проверка**:
+Проверка, чей оракул — внутренний эталон стенда (опись мира), которого у
+настоящего магазина нет. За учебный урок DQ не выдаётся.
+_Избегать_: DQ-проверка — та работает на наблюдаемых данных магазина.

Makefile

@@ -4,23 +4,27 @@ GENERATOR_LIMIT ?=
 GENERATOR_SPEED ?=
 
 # Цели корня — про стенд; проверки генератора — в `generator/Makefile`.
-.PHONY: up down clean ps logs smoke check-clickhouse check-services config-test lint generate-batch generate-live
+.PHONY: up down clean rebuild-storage ps logs smoke check-clickhouse check-services config-test lint generate-batch generate-live
 
 # --- Жизнь стенда ---
 
-# Второй шаг: `--wait` дожидается служб, а приём событий асинхронный — довод
+# Compose дожидается инфраструктуры, Airflow — готового прикладного мира.
-# целиком в шапке скрипта.
 up:
-	$(COMPOSE) up --detach --build --wait --wait-timeout 600
+	$(COMPOSE) up --detach --build --wait --wait-timeout 600 --remove-orphans
-	COMPOSE_BIN="$(COMPOSE)" ./scripts/wait-for-world.sh
+	COMPOSE_BIN="$(COMPOSE)" ./scripts/run-dag.sh world_initialize
-	COMPOSE_BIN="$(COMPOSE)" ./scripts/ingest-starting-orders.sh
 
 down:
 	$(COMPOSE) down --remove-orphans
 
+# Полное удаление стенда, а не способ получить чистые данные перед проверкой.
+# Граница операции и требование к обоснованию — в AGENTS.md.
 clean:
 	$(COMPOSE) down --volumes --remove-orphans
 
+# Возврат прикладного мира к началу без удаления инфраструктурных томов.
+rebuild-storage:
+	COMPOSE_BIN="$(COMPOSE)" ./scripts/run-dag.sh world_recreate
+
 ps:
 	$(COMPOSE) ps
 

README.md

@@ -14,8 +14,9 @@ Prometheus, Grafana, экспортёр метрик Kafka и общая баз
 целиком со стороны клиента: у него есть контракт схемы события, из которого
 собрано [описание выгрузки](docs/formats/clickstream-event.md), модельный мир и
 проигрыватель, отправляющий дни в Kafka или в файл. События доезжают до
-типизированного `ods.event`, а `make up` наполняет стенд стартовым миром —
+типизированного `ods.event`, а `dds.event_v` отдаёт их на языке бизнес-модели
-первой неделей модельного времени.
+без копии данных. `make up` наполняет стенд стартовым миром — первой неделей
+модельного времени.
 
 ## Быстрый старт
 
@@ -67,9 +68,10 @@ make check-services
 стенд и ждёт здорового состояния долгоживущих контейнеров. В образ Airflow
 добавлены закреплённые клиенты ClickHouse и Kafka. Одноразовые `airflow-init` и
 `superset-init` завершаются с кодом 0. Первый обновляет схему Airflow,
-подготавливает администратора и подключение к `clickhouse-01`. Второй обновляет
+подготавливает администратора и два подключения к `clickhouse-01`. Второй
-Superset, создаёт администратора и импортирует подключение к `clickhouse-02`.
+обновляет Superset, создаёт администратора и импортирует подключение к
-С нуля подъём занимает около трёх минут, на живом стенде — около минуты.
+`clickhouse-02`. На ноутбуке в режиме энергосбережения приёмочный подъём с
+пустых томов занял около десяти минут, повторный на живом стенде — около трёх.
 
 `make smoke` за секунды спрашивает, собран ли стенд: зависимости машины,
 здоровье контейнеров, устройство keeper, ответ Kafka с машины через отображённый
@@ -118,36 +120,41 @@ Kafka по той же причине спрашивают снаружи. Её
 поднятый стенд, сколько стоит прогон и куда класть новую — в
 [карте проверок](docs/architecture/testing.md).
 
-Остановить контейнеры без удаления данных можно командой `make down`. Для
+Остановить контейнеры без удаления данных можно командой `make down`. Если
-полного сброса с удалением всех именованных томов используйте `make clean`.
+нужно вернуть прикладной мир к началу, `make rebuild-storage` запустит в
-Повторный `make up` безопасен: одноразовая подготовка приложений идемпотентна.
+Airflow его явную пересборку: удалит прикладные базы ClickHouse, топики и
+позиции потребителей Kafka, затем создаст схему и данные заново. Службы и их
+тома останутся на месте. `make clean` удаляет весь стенд вместе с именованными
+томами и для обычной разработки не нужен. Перед пересборкой поставьте
+`world_live` на паузу и дайте уже начатому работнику закончить день.
 
 ## Стартовый мир
 
-Стенд поднимается не пустым: разовая служба `world-init` играет в топик `hits`
+Стенд поднимается не пустым: `make up` через REST API запускает даг Airflow
-первые восемь дней модельного времени — понедельник по понедельник, 401 185
+`world_initialize`. Тот создаёт прикладные топики и схему, собирает образ
-событий. Следом второй запуск того же генератора отправляет в топик `orders`
+генератора и играет в `hits` первые восемь дней модельного времени — понедельник
-семь слепков — за дни 0…6. Дальше оба источника разбирает хранилище, и к концу
+по понедельник, 401 185 событий. Следом второй запуск генератора отправляет в
-`make up` события лежат в `ods.event`, а заказы — в `ods.order_v`. Так у всякой
+`orders` семь слепков — за дни 0…6. Даг ждёт приёма обоих источников и только
-лабы есть данные, и всегда одни и те же.
+тогда ставит позицию мира в `8`. Так у всякой лабы есть данные, и всегда одни и
+те же.
 
 Последний день намеренно неполон: события дня 7 уже приехали, а его слепок
 уедет только с первым ходом мира. Поэтому на свежем стенде правый край графика
 выручки отстаёт от кликстрима и дозаполняется по мере движения мира — так
 виден разный темп потокового трекера и ночной выгрузки магазина.
 
-Ждать приходится дольше, чем работает заливка. `make up` сначала опрашивает
+Повторный `make up` безопасен: `world_initialize` видит готовую позицию,
-ClickHouse, пока события не доедут, затем разово запускает даг `orders_ingest`
+сообщает в журнале, что мир уже существует, и не применяет DDL, не собирает
-и ждёт его конца. Повторный `make up` заливает мир заново; это не ошибка, а
+образ и не заливает данные повторно. Изменённую схему применяют адресно либо
-свойство: номера событий и версии заказов те же, и повторы схлопнут
+явной командой `make rebuild-storage`.
-`ReplacingMergeTree`.
 
 Сам мир в git не хранится — он чистая функция зерна, и держать его в
 репозитории значило бы держать там кэш. Вместо него лежит **опись мира**,
 [`data/world-inventory.json`](data/world-inventory.json): зерно, версия
 генератора, хеш каталога товаров и по строке на каждый день — дата, число
-событий и хеш его байтов. Опись отвечает на единственный вопрос: тот ли это
+событий и хеш его байтов. У дней с закрытым окном там же лежат счётчики
-мир, что был вчера.
+классов расхождений по заказам. Опись отвечает на единственный вопрос: тот ли
+это мир, что был вчера.
 
 Спрашивают её двое. `make test` в `generator/` сверяет опись с тем, что
 собирается из кода сегодня: правка генератора меняет мир, и опись надо
@@ -202,9 +209,9 @@ make generate-live GENERATOR_DAY=3 GENERATOR_SPEED=1000
 docker compose --profile generator build generator
 ```
 
-Тот же образ несёт заливка стартового мира, поэтому свежим его держит и
+Тот же образ несёт заливка стартового мира. Перед такой заливкой
-обычный `make up`: он собирает образы всего стенда, и генератор теперь среди
+`world_initialize` сам собирает его из текущего дерева; на готовом мире
-них.
+повторный `make up` до сборки не доходит.
 
 Разведено это нарочно: собрать образ и запустить контейнер — разные действия, и
 цель запуска, молча пересобирающая образ, стирает между ними границу. Что образ
@@ -231,11 +238,13 @@ uv run --project generator python -m clickstream_generator batch \
 
 ### Пульт мира
 
-Считать дни самому необязательно. В Airflow живёт **пульт мира** — три дага,
+Считать дни самому необязательно. В Airflow живёт **пульт мира**: два дага
-которые зовут тот же образ генератора и ведут позицию на оси за вас.
+создают его начальное состояние, а три двигают ось дальше.
 
 | Даг | Что делает |
 | --- | --- |
+| `world_initialize` | создаёт стартовый мир, если его ещё нет; повторный запуск ничего не меняет |
+| `world_recreate` | удаляет только прикладной мир и запускает его создание заново |
 | `world_next_day` | играет следующие дни пачкой; сколько — параметр запуска, по умолчанию один |
 | `world_live_day` | играет следующий день в темпе модельного времени, около двадцати четырёх минут |
 | `world_live` | выключатель: пока снят с паузы, дёргает `world_live_day` день за днём |
@@ -248,8 +257,15 @@ uv run --project generator python -m clickstream_generator batch \
 
 Позицию хранит переменная Airflow `world_position` — номер первого несыгранного
 дня. Ставит её работник, сыгравший день, и только по успеху: оборванный прогон
-позицию не двигает, и следующий запуск играет тот же день заново. Нет
+позицию не двигает, и следующий запуск играет тот же день заново. Отсутствующая
-переменной — мир в стартовом состоянии.
+переменная означает, что мир ещё не создавали; `-1` — очистка не закончена,
+`0` — очистка закончена, а начальная генерация ещё не завершена. Работники
+начинают играть только с позиции `8` и больше.
+
+В форме запуска можно выбрать только число дней. Первый день работник берет из
+`world_position`. Поля «Logical date» и «Run ID» спрятаны в «Advanced Options».
+Они нужны самому Airflow и на выбор дня не влияют. Сыгранные дни и новую
+позицию работник пишет в журнал шага `remember_played`.
 
 Выключатель создаётся на паузе. Снимите — мир поедет сам; поставите обратно —
 встанет на границе модельных суток, доиграв начатый день. Форма пульта и доводы
@@ -286,12 +302,14 @@ uv run --project generator python -m clickstream_generator batch \
 - Prometheus — `http://127.0.0.1:29090`;
 - Grafana — `http://127.0.0.1:23000`, пользователь `admin`, пароль `admin`.
 
-В ClickHouse шесть пользователей и пять ролей:
+В ClickHouse семь пользователей и шесть ролей:
 
-- `etl` применяет DDL и подключает Airflow; роль `etl_writer` читает и пишет
+- `etl` подключает рабочие даги Airflow; роль `etl_writer` читает и пишет слои
-  слои хранилища;
+  хранилища;
-- `bi` подключает Superset; роль `bi_reader` читает справочники `dic` и будущие
+- `lifecycle` применяет канонический DDL и пересоздаёт прикладные базы; роль
-  слои DDS и DM;
+  `lifecycle_owner` не даёт эти административные права рабочим дагам;
+- `bi` подключает Superset; роль `bi_reader` читает ODS, DDS, DM и справочники
+  `dic`, а запросы Superset обращаются к публичным `_v`;
 - `analyst` предназначен для подключения человека и читает все слои и
   справочники;
 - `grafana` с ролью `monitoring_reader` подключает Grafana и читает все слои,
@@ -353,8 +371,9 @@ docker compose up --force-recreate --wait clickhouse-01 clickhouse-02
 Prometheus собирает встроенные метрики двух серверов и keeper, а через
 `kafka-exporter` — состояние Kafka. Поверх этого в Grafana поднимается дашборд
 «Данные»: свежесть, поток, брак, сходимость Kafka с ClickHouse, отставание
-чтения и дневной слепок заказов. Устройство зоны и разбор панелей — в
+чтения и дневной слепок заказов. Устройство зоны — в [справочнике
-[справочнике мониторинга](docs/architecture/monitoring.md); правил оповещения
+мониторинга](docs/architecture/monitoring/README.md), разбор панелей — в
+[описании дашборда](docs/architecture/monitoring/data.md); правил оповещения
 пока нет.
 
 Airflow закреплён на 3.3.0. Состав обязательных процессов, LocalExecutor,
@@ -362,10 +381,12 @@ Airflow закреплён на 3.3.0. Состав обязательных п
 [архитектурой Airflow 3.3](https://airflow.apache.org/docs/apache-airflow/3.3.0/core-concepts/overview.html),
 [публичным интерфейсом](https://airflow.apache.org/docs/apache-airflow/3.3.0/public-airflow-interface.html)
 и [описанием здоровья](https://airflow.apache.org/docs/apache-airflow/3.3.0/administration-and-deployment/logging-monitoring/check-health.html).
-Для пробников проверены публичный `Connection.get` из `airflow.sdk` и клиент
+Для ClickHouse установлен официальный провайдер Airflow: SQL-файлы исполняет
+общий `SQLExecuteQueryOperator`, программные запросы идут через
+`ClickHouseHook`. Провайдер работает поверх закреплённого
 `clickhouse-connect`. Официальный провайдер Kafka сам использует
-`confluent-kafka`; отдельное подключение и обёртки провайдера здесь не нужны,
+`confluent-kafka`; отдельное подключение и его обёртки здесь не нужны, поэтому
-поэтому прямой клиент оставляет образ и пример короче.
+клиент Kafka добавлен в образ напрямую.
 Superset закреплён на 6.1.0; драйвер `clickhouse-connect`, форма
 `clickhousedb://` и драйвер Postgres сверены с
 [документацией подключений Superset](https://superset.apache.org/user-docs/6.1.0/databases/)

compose.yaml

@@ -17,6 +17,7 @@ x-clickhouse-common: &clickhouse-common
     CLICKHOUSE_CLUSTER_SECRET: ${CLICKHOUSE_CLUSTER_SECRET:?Скопируйте .env.example в .env}
     CLICKHOUSE_DEFAULT_PASSWORD: ${CLICKHOUSE_DEFAULT_PASSWORD:?Скопируйте .env.example в .env}
     CLICKHOUSE_ETL_PASSWORD: ${CLICKHOUSE_ETL_PASSWORD:?Скопируйте .env.example в .env}
+    CLICKHOUSE_LIFECYCLE_PASSWORD: ${CLICKHOUSE_LIFECYCLE_PASSWORD:?Скопируйте .env.example в .env}
     CLICKHOUSE_BI_PASSWORD: ${CLICKHOUSE_BI_PASSWORD:?Скопируйте .env.example в .env}
     CLICKHOUSE_ANALYST_PASSWORD: ${CLICKHOUSE_ANALYST_PASSWORD:?Скопируйте .env.example в .env}
     CLICKHOUSE_GRAFANA_PASSWORD: ${CLICKHOUSE_GRAFANA_PASSWORD:?Скопируйте .env.example в .env}
@@ -33,9 +34,8 @@ x-clickhouse-common: &clickhouse-common
     retries: 30
     start_period: 10s
 
-# Факты стенда, у которых стало по два потребителя: разовая служба генератора и
+# Факты генератора и пульта мира названы по одному разу — иначе они однажды
-# пульт мира. Названы по одному разу — иначе однажды разойдутся, и заметит это
+# разойдутся, и заметит это не проверка, а менти с пустым топиком.
-# не проверка, а менти с пустым топиком.
 x-generator-image: &generator-image clickstream-generator:local
 x-orders-topic: &orders-topic orders
 
@@ -46,16 +46,12 @@ x-kafka-target: &kafka-target
   <<: *kafka-common
   KAFKA_TOPIC: hits
 
-x-orders-kafka-target: &orders-kafka-target
-  <<: *kafka-common
-  KAFKA_TOPIC: *orders-topic
-
 x-world-starting-days: &world-starting-days "8"
 
+# Общие образы Airflow и Superset собирают службы инициализации. Причина
+# отдельного build: ADR 0001.
 x-airflow-common: &airflow-common
   image: clickstream-airflow:local
-  build:
-    context: ./infra/airflow
   environment:
     AIRFLOW__CORE__EXECUTOR: LocalExecutor
     AIRFLOW__CORE__PARALLELISM: "4"
@@ -73,9 +69,9 @@ x-airflow-common: &airflow-common
     AIRFLOW_ADMIN_USER: ${AIRFLOW_ADMIN_USER:?Скопируйте .env.example в .env}
     AIRFLOW_ADMIN_PASSWORD: ${AIRFLOW_ADMIN_PASSWORD:?Скопируйте .env.example в .env}
     CLICKHOUSE_ETL_PASSWORD: ${CLICKHOUSE_ETL_PASSWORD:?Скопируйте .env.example в .env}
-    # Пульт мира поднимает генератор сам, отдельным контейнером, — значит те же
+    CLICKHOUSE_LIFECYCLE_PASSWORD: ${CLICKHOUSE_LIFECYCLE_PASSWORD:?Скопируйте .env.example в .env}
-    # факты стенда, что compose даёт разовой службе генератора, нужны и дагам.
+    # Пульт мира поднимает генератор отдельным контейнером. Имя сети собирается
-    # Имя сети собирается из имени проекта: у второй копии стенда оно другое.
+    # из имени проекта: у второй копии стенда оно другое.
     <<: *kafka-target
     GENERATOR_IMAGE: *generator-image
     STAND_NETWORK: ${COMPOSE_PROJECT_NAME}_default
@@ -83,9 +79,14 @@ x-airflow-common: &airflow-common
     KAFKA_ORDERS_TOPIC: *orders-topic
   volumes:
     - ./dags:/opt/airflow/dags:ro
-    # Запросы дагов: даг называет файл, а текст читает Airflow при исполнении
+    # Запросы дагов: даг называет файл, а обработчик DAG при разборе загружает
-    # задачи. Каталог тот же, что применяет DDL, — вся SQL стенда живёт в sql/.
+    # его текст. Каталог тот же, что применяет DDL, — вся SQL стенда живёт в sql/.
     - ./sql:/opt/airflow/sql:ro
+    # Инициализация мира собирает канонический образ из того же контекста, что
+    # ручной generator. Docker SDK архивирует эти файлы внутри задачи.
+    - ./generator:/opt/airflow/world/generator:ro
+    - ./data:/opt/airflow/world/data:ro
+    - ./.dockerignore:/opt/airflow/world/.dockerignore:ro
     - ./infra/airflow/init.sh:/opt/airflow/init.sh:ro
     - airflow_logs:/opt/airflow/logs
     - airflow_auth:/opt/airflow/auth
@@ -96,15 +97,6 @@ x-generator-common: &generator-common
     context: .
     dockerfile: generator/Dockerfile
   restart: "no"
-  depends_on:
-    kafka-init:
-      condition: service_completed_successfully
-    # Читать топик движок Kafka начинает не при своём создании, а когда над ним
-    # появляется матвью приёма, и она создаётся последней по номеру файла
-    # (sql/ddl/40-stg-views.sql). Отправь генератор события раньше — они лягут в
-    # топик и молча минуют хранилище.
-    clickhouse-init:
-      condition: service_completed_successfully
   environment:
     # Адрес брокера и имя топика — факты стенда, и называет их стенд.
     # Остальное (день, зерно, число дней, предел пачки) приходит аргументами
@@ -113,8 +105,6 @@ x-generator-common: &generator-common
 
 x-superset-common: &superset-common
   image: clickstream-superset:local
-  build:
-    context: ./infra/superset
   environment:
     SUPERSET_CONFIG_PATH: /app/pythonpath/superset_config.py
     SUPERSET_SECRET_KEY: ${SUPERSET_SECRET_KEY:?Скопируйте .env.example в .env}
@@ -228,119 +218,6 @@ services:
       retries: 15
       start_period: 10s
 
-  kafka-init:
-    image: apache/kafka:4.3.1
-    restart: "no"
-    depends_on:
-      kafka:
-        condition: service_healthy
-    entrypoint: ["/bin/bash", "-ec"]
-    command:
-      - |
-        topic_partition_count() {
-          /opt/kafka/bin/kafka-topics.sh \
-            --bootstrap-server kafka:9092 \
-            --describe \
-            --topic hits | \
-            sed -n '1s/.*PartitionCount: \([0-9][0-9]*\).*/\1/p'
-        }
-
-        /opt/kafka/bin/kafka-topics.sh \
-          --bootstrap-server kafka:9092 \
-          --create \
-          --if-not-exists \
-          --topic hits \
-          --partitions 2 \
-          --replication-factor 1
-
-        partition_count="$$(topic_partition_count)"
-        # Брокер разрешает автосоздание, хотя потребитель ClickHouse его не запрашивает.
-        # На сохранённом томе другой клиент мог уже создать hits с одним разделом.
-        if [[ "$$partition_count" == "1" ]]; then
-          /opt/kafka/bin/kafka-topics.sh \
-            --bootstrap-server kafka:9092 \
-            --alter \
-            --topic hits \
-            --partitions 2
-          partition_count="$$(topic_partition_count)"
-        fi
-        if [[ "$$partition_count" != "2" ]]; then
-          printf 'ОШИБКА: у топика hits разделов: %s, ожидалось: 2.\n' \
-            "$${partition_count:-неизвестно}" >&2
-          exit 1
-        fi
-
-        # Топик заказов: одна партиция, читает его один чтец на ноде 1 —
-        # довод в ADR 0008.
-        /opt/kafka/bin/kafka-topics.sh \
-          --bootstrap-server kafka:9092 \
-          --create \
-          --if-not-exists \
-          --topic orders \
-          --partitions 1 \
-          --replication-factor 1
-
-  # DDL применяется с ноды 1 по порядку имён файлов после готовности всего кластера.
-  clickhouse-init:
-    image: clickhouse/clickhouse-server:26.3.17.56
-    restart: "no"
-    depends_on:
-      kafka-init:
-        condition: service_completed_successfully
-      clickhouse-01:
-        condition: service_healthy
-      clickhouse-02:
-        condition: service_healthy
-    environment:
-      LC_ALL: C
-      CLICKHOUSE_ETL_PASSWORD: ${CLICKHOUSE_ETL_PASSWORD:?Скопируйте .env.example в .env}
-    entrypoint: ["/bin/bash", "-ec"]
-    command:
-      - |
-        set -- /ddl/*.sql
-        if [[ ! -e "$$1" ]]; then
-          printf 'ОШИБКА: в /ddl нет файлов SQL.\n' >&2
-          exit 1
-        fi
-        for ddl_file do
-          printf 'Применяем %s.\n' "$${ddl_file##*/}"
-          clickhouse-client \
-            --host clickhouse-01 \
-            --user etl \
-            --password "$$CLICKHOUSE_ETL_PASSWORD" \
-            --multiquery \
-            --queries-file "$$ddl_file"
-        done
-    volumes:
-      - ./sql/ddl:/ddl:ro
-
-  # Стартовый мир: восемь модельных дней уезжают в топик при каждом подъёме.
-  # Что это за дни и каким мир обязан выйти — data/world-inventory.json.
-  #
-  # Число дней стоит здесь числом: YAML не читает Python, и одно из двух мест
-  # (второе — `STARTING_DAYS` в inventory.py) лишнее по построению. Правя одно,
-  # правьте второе — на страже тут никто не стоит: залей эта служба лишний
-  # день, он лёг бы за рамкой дат описи и остался бы незамеченным. Внутри YAML
-  # число одно на всех: то же говорит дагам пульта, где кончается стартовый мир.
-  #
-  # Повторный `make up` заливает мир заново, и это не оплошность: `WatchID` у
-  # событий те же, ReplacingMergeTree схлопнет повтор в ODS. Сырьё в STG при
-  # этом честно удвоится — свойство слоя, описанное в storage.md.
-  world-init:
-    <<: *generator-common
-    command: ["batch", "--day", "0", "--days", *world-starting-days]
-
-  # Второй источник стартового мира идёт после событий тем же генератором.
-  # Сдвиг команды snapshot оставляет день 7 первому ходу мира: за восемь
-  # дней уезжают семь слепков, дней 0…6.
-  world-snapshots:
-    <<: *generator-common
-    depends_on:
-      world-init:
-        condition: service_completed_successfully
-    environment: *orders-kafka-target
-    command: ["snapshot", "--day", "0", "--days", *world-starting-days]
-
   # Тот же образ для ручных прогонов: `make generate-batch`, `make generate-live`.
   # Под профилем — чтобы обычный подъём стенда её не трогал.
   generator:
@@ -378,6 +255,8 @@ services:
 
   airflow-init:
     <<: *airflow-common
+    build:
+      context: ./infra/airflow
     user: "0:0"
     restart: "no"
     depends_on:
@@ -385,14 +264,6 @@ services:
         condition: service_healthy
       clickhouse-01:
         condition: service_healthy
-      # Не убирать: без зависимого успешный clickhouse-init считается
-      # упавшим для --wait.
-      clickhouse-init:
-        condition: service_completed_successfully
-      # По той же причине. Слепки идут за событиями и замыкают цепь разовых
-      # служб; долгоживущие службы данных её не ждут, а `airflow-init` ждёт.
-      world-snapshots:
-        condition: service_completed_successfully
     entrypoint: ["/bin/bash"]
     command: ["/opt/airflow/init.sh"]
 
@@ -433,10 +304,16 @@ services:
       - /var/run/docker.sock:/var/run/docker.sock
       - ./dags:/opt/airflow/dags:ro
       - ./sql:/opt/airflow/sql:ro
+      - ./generator:/opt/airflow/world/generator:ro
+      - ./data:/opt/airflow/world/data:ro
+      - ./.dockerignore:/opt/airflow/world/.dockerignore:ro
       - ./infra/airflow/init.sh:/opt/airflow/init.sh:ro
       - airflow_logs:/opt/airflow/logs
       - airflow_auth:/opt/airflow/auth
-    mem_limit: 640m
+    # LocalExecutor запускает здесь до четырех процессов задач одновременно.
+    # 640 МиБ дали OOM, а 1 ГиБ - давление на memory.max при штатном dq_check;
+    # 1,5 ГиБ оставляет запас при AIRFLOW__CORE__PARALLELISM=4.
+    mem_limit: 1536m
     healthcheck:
       test: ["CMD-SHELL", "curl -sf http://127.0.0.1:8974/health >/dev/null"]
       interval: 10s
@@ -463,6 +340,8 @@ services:
 
   superset-init:
     <<: *superset-common
+    build:
+      context: ./infra/superset
     restart: "no"
     healthcheck:
       disable: true

dags/dds_transform.py

@@ -0,0 +1,434 @@
+"""Трансформации слоя DDS: сборка моделей.
+
+Заказ и сессия собираются заменой дневных партиций. Карта идентичностей
+пересчитывается целиком после заказа, потому что читает его текущую модель.
+
+Расписания у дага нет и параметров тоже: объём каждого прогона он выводит сам
+из состояния слоёв и позиции мира, поэтому один и тот же запуск одинаково
+верен из триггера дневного конвейера, с кнопки менти и после падения
+(docs/architecture/etl.md, «Объём прогона»).
+
+Заказ и сессия гасят повтор заменой партиции целиком: день собирается в
+таблицу-двойник и подменяет собой партицию цели. Карта пишет полный набор пар
+новой версией, а точное чтение даёт FINAL. Замена партиции разобрана в
+sql/dds/order_replace.sql; точное чтение карты описано в
+sql/ddl/50-dds-views.sql.
+"""
+
+from __future__ import annotations
+
+import datetime
+import logging
+import os
+import time
+from pathlib import Path
+
+from airflow.exceptions import AirflowException
+from airflow.providers.clickhousedb.hooks.clickhouse import ClickHouseHook
+from airflow.providers.common.sql.operators.sql import SQLExecuteQueryOperator
+from airflow.sdk import Variable, dag, task, task_group
+
+# Пропуск приезжает из Task SDK: в airflow.exceptions он объявлен устаревшим
+# и говорит об этом в журнал задачи (проверено на 3.3.0).
+from airflow.sdk.exceptions import AirflowSkipException
+
+START_DATE = datetime.datetime(2026, 1, 1, tzinfo=datetime.UTC)
+
+SQL_ROOT = Path("/opt/airflow/sql")
+CLICKHOUSE_CONNECTION = "clickhouse_default"
+CLICKHOUSE_CLUSTER = "clickstream_cluster"
+
+KAFKA_BOOTSTRAP_SERVERS = os.environ["KAFKA_BOOTSTRAP_SERVERS"]
+HITS_TOPIC = os.environ["KAFKA_TOPIC"]
+HITS_GROUP = "clickstream_hits"
+HITS_PARTITIONS = (0, 1)
+
+READINESS_TIMEOUT_SECONDS = 300
+READINESS_POLL_SECONDS = 3
+
+# Позиция на оси модельного времени: номер первого несыгранного дня. Её ставит
+# пульт мира, и только она отличает прожитый день от живого — зачем это
+# сессиям, разобрано в sql/dds/session_scope.sql.
+WORLD_POSITION = "world_position"
+
+
+def _kafka_readiness() -> tuple[bool, str]:
+    """Проверить, дочитала ли группа оба раздела событий."""
+    from confluent_kafka import ConsumerGroupTopicPartitions, TopicPartition
+    from confluent_kafka.admin import AdminClient, OffsetSpec
+
+    admin = AdminClient({"bootstrap.servers": KAFKA_BOOTSTRAP_SERVERS})
+    groups = admin.list_consumer_groups(request_timeout=10).result()
+    if groups.errors:
+        raise RuntimeError(f"Kafka не вернула список групп: {groups.errors}")
+
+    group_exists = any(group.group_id == HITS_GROUP for group in groups.valid)
+    committed: dict[int, int] = {}
+    if group_exists:
+        request = ConsumerGroupTopicPartitions(
+            HITS_GROUP,
+            [TopicPartition(HITS_TOPIC, partition) for partition in HITS_PARTITIONS],
+        )
+        result = admin.list_consumer_group_offsets([request], request_timeout=10)[
+            HITS_GROUP
+        ].result()
+        for topic_partition in result.topic_partitions:
+            if topic_partition.error is None and topic_partition.offset >= 0:
+                committed[topic_partition.partition] = topic_partition.offset
+
+    high_watermarks: dict[int, int] = {}
+    watermark_errors: dict[int, str] = {}
+    # OffsetSpec.latest возвращает следующее смещение после хвоста; сверено
+    # через Context7 и на установленном confluent-kafka 2.15.0.
+    latest = admin.list_offsets(
+        {
+            TopicPartition(HITS_TOPIC, partition): OffsetSpec.latest()
+            for partition in HITS_PARTITIONS
+        },
+        request_timeout=10,
+    )
+    for topic_partition, future in latest.items():
+        try:
+            offset = future.result().offset
+            if offset >= 0:
+                high_watermarks[topic_partition.partition] = offset
+        except Exception as error:
+            watermark_errors[topic_partition.partition] = str(error)
+
+    all_known = group_exists
+    total_lag = 0
+    parts: list[str] = []
+    for partition in HITS_PARTITIONS:
+        offset = committed.get(partition)
+        high = high_watermarks.get(partition)
+        lag = high - offset if offset is not None and high is not None else None
+        if lag is None or lag < 0:
+            all_known = False
+        else:
+            total_lag += lag
+        logging.info(
+            "Kafka %s[%s]: подтверждено=%s, верхнее смещение=%s, отставание=%s",
+            HITS_TOPIC,
+            partition,
+            offset,
+            high,
+            lag,
+        )
+        parts.append(
+            f"{HITS_TOPIC}[{partition}]: подтверждено={offset}, "
+            f"верхнее смещение={high}, отставание={lag}"
+        )
+        if partition in watermark_errors:
+            parts[-1] += (
+                f", ошибка чтения верхнего смещения={watermark_errors[partition]}"
+            )
+
+    if not group_exists:
+        logging.info("группа потребителей %s отсутствует", HITS_GROUP)
+    lag_text = str(total_lag) if all_known else "неизвестно"
+    logging.info("суммарное отставание Kafka: %s", lag_text)
+    detail = "; ".join(parts)
+    if not group_exists:
+        detail = f"группа {HITS_GROUP} отсутствует; {detail}"
+    return all_known and total_lag == 0, detail
+
+
+def _delivery_queue_readiness() -> tuple[bool, str]:
+    """Проверить, пуста ли очередь доставки событий на каждой ноде."""
+    query = f"""
+        SELECT
+            node,
+            sum(queued_files) AS files,
+            arrayStringConcat(
+                groupArrayIf(
+                    last_exception,
+                    queued_files > 0 AND notEmpty(last_exception)
+                ),
+                '; '
+            ) AS last_exception
+        FROM
+        (
+            -- У пустой очереди нет строк; system.one оставляет обе ноды
+            -- видимыми и в зеленом опросе.
+            SELECT
+                hostName() AS node,
+                toUInt64(0) AS queued_files,
+                '' AS last_exception
+            FROM clusterAllReplicas('{CLICKHOUSE_CLUSTER}', system.one)
+
+            UNION ALL
+
+            SELECT
+                hostName(),
+                data_files + broken_data_files AS queued_files,
+                last_exception
+            FROM clusterAllReplicas(
+                '{CLICKHOUSE_CLUSTER}', system.distribution_queue
+            )
+            WHERE database = 'ods' AND table = 'event_dist'
+        )
+        GROUP BY node
+        ORDER BY node
+    """
+    rows = ClickHouseHook(clickhouse_conn_id=CLICKHOUSE_CONNECTION).get_records(query)
+    ready = True
+    nodes: list[str] = []
+    for node, files, last_exception in rows:
+        files = int(files)
+        ready = ready and files == 0
+        logging.info(
+            "очередь ods.event_dist на %s: файлов=%s, последняя ошибка=%s",
+            node,
+            files,
+            last_exception or "нет",
+        )
+        detail = f"{node}: файлов={files}"
+        if last_exception:
+            detail += f", последняя ошибка={last_exception}"
+        nodes.append(detail)
+    return ready, "; ".join(nodes)
+
+
+def _wait_for_phase(
+    probe,
+    phase: str,
+    deadline: float,
+) -> None:
+    """Дождаться прохождения одного барьера до общего крайнего срока."""
+    last_observation = "первый опрос не выполнен"
+    last_error: str | None = None
+    while time.monotonic() < deadline:
+        try:
+            ready, last_observation = probe()
+            last_error = None
+        except Exception as error:
+            ready = False
+            last_error = str(error)
+            logging.warning("%s: ошибка опроса: %s", phase, last_error)
+        if ready:
+            return
+
+        remaining = deadline - time.monotonic()
+        if remaining > 0:
+            time.sleep(min(READINESS_POLL_SECONDS, remaining))
+
+    detail = last_observation
+    if last_error:
+        detail += f"; ошибка последнего опроса: {last_error}"
+    raise AirflowException(
+        f"общий срок ожидания готовности в {READINESS_TIMEOUT_SECONDS} с "
+        f'истек на этапе "{phase}": {detail}'
+    )
+
+
+def _world_position() -> int:
+    """Позиция мира числом, с внятным отказом на непригодном значении.
+
+    Ту же переменную читает пульт, но общего модуля у дагов нет намеренно:
+    связь между пультом и трансформацией держит сама переменная, а не импорт.
+    """
+    raw_position = Variable.get(WORLD_POSITION, default=None)
+    if raw_position is None:
+        raise AirflowException(
+            "мир ещё не создан: выполните make up и дождитесь world_initialize"
+        )
+    try:
+        position = int(raw_position)
+    except (TypeError, ValueError) as error:
+        raise AirflowException(
+            f"world_position={raw_position!r} не является номером дня; "
+            "выполните make rebuild-storage"
+        ) from error
+    if position < 1:
+        raise AirflowException(
+            f"мир не готов: world_position={position}; "
+            "выполните make up или make rebuild-storage"
+        )
+    return position
+
+
+def _days(first_day: datetime.date, last_day: datetime.date) -> list[str]:
+    """Дни отрезка строками — в таком виде их ждёт замена партиции."""
+    return [
+        (first_day + datetime.timedelta(days=shift)).isoformat()
+        for shift in range((last_day - first_day).days + 1)
+    ]
+
+
+@task
+def replacements(scope: dict[str, object]) -> list[dict[str, object]]:
+    """Разложить дни в аргументы размноженной задачи замены.
+
+    Шаг существует ради ограничения Airflow: размножать задачу можно
+    только по целому возврату другой задачи — ни по ключу словаря, ни по
+    карте поверх него. Отсюда отдельный возврат под один список.
+
+    День едет в запрос подстановкой Jinja, а не параметром ClickHouse:
+    в ALTER … PARTITION сервер параметр не подставляет — замерено,
+    отвечает синтаксической ошибкой. Значение при этом не внешнее, его
+    вернул сам ClickHouse запросом объёма.
+    """
+    return [{"params": {"day": day}} for day in scope["days"]]
+
+
+@dag(
+    dag_id="dds_transform",
+    schedule=None,
+    start_date=START_DATE,
+    is_paused_upon_creation=False,
+    # Два прогона разом собирали бы один и тот же двойник: второй затёр бы
+    # чужую сборку между вставкой и заменой партиций.
+    max_active_runs=1,
+    template_searchpath=str(SQL_ROOT),
+    tags=["dds"],
+)
+def dds_transform():
+    """Пересобрать сущности DDS по текущему состоянию источников."""
+
+    @task
+    def wait_for_source() -> None:
+        """Дождаться чтения событий из Kafka и их доставки в ODS."""
+        deadline = time.monotonic() + READINESS_TIMEOUT_SECONDS
+        _wait_for_phase(_kafka_readiness, "Kafka", deadline)
+        _wait_for_phase(
+            _delivery_queue_readiness,
+            "очередь доставки ClickHouse",
+            deadline,
+        )
+
+    @task_group(group_id="order")
+    def order():
+        """Заказ: дышащее окно плюс дни, которых в слое ещё нет."""
+
+        @task
+        def scope() -> dict[str, object]:
+            """Спросить у хранилища, какие дни собирает этот запуск."""
+            query = (SQL_ROOT / "dds" / "order_scope.sql").read_text(encoding="utf-8")
+            hook = ClickHouseHook(clickhouse_conn_id=CLICKHOUSE_CONNECTION)
+            row = hook.get_first(query)
+            # Пустой ответ означает пустой источник: собирать нечего, и
+            # зеленеть на этом нельзя — прогон встаёт с внятной причиной.
+            if row is None:
+                raise AirflowException(
+                    "в ods.order нет ни одного заказа: собирать нечего; "
+                    "проверьте, дошёл ли слепок до хранилища"
+                )
+            first_day, last_day = row
+            days = _days(first_day, last_day)
+            logging.info(
+                "объём пересборки: %s … %s, дней %d",
+                first_day,
+                last_day,
+                len(days),
+            )
+            return {
+                "first_day": first_day.isoformat(),
+                "last_day": last_day.isoformat(),
+                "days": days,
+            }
+
+        days = scope()
+
+        rebuild = SQLExecuteQueryOperator(
+            task_id="rebuild",
+            conn_id=CLICKHOUSE_CONNECTION,
+            sql="dds/order_rebuild.sql",
+            parameters={
+                "load_id": "{{ run_id }}",
+                "first_day": days["first_day"],
+                "last_day": days["last_day"],
+            },
+            split_statements=True,
+            do_xcom_push=False,
+        )
+
+        # Замена идёт по партиции за раз — другой формы у операции нет. День
+        # становится отдельной задачей: в интерфейсе видно, сколько дней несёт
+        # прогон, а повтор после отказа стоит одного дня, а не всей пересборки.
+        replace = SQLExecuteQueryOperator.partial(
+            task_id="replace",
+            conn_id=CLICKHOUSE_CONNECTION,
+            sql="dds/order_replace.sql",
+            do_xcom_push=False,
+        ).expand_kwargs(replacements(days))
+
+        rebuild >> replace
+
+    @task_group(group_id="session")
+    def session():
+        """Сессия: дни, которые мир уже прожил, а слой ещё не собрал."""
+
+        @task
+        def scope() -> dict[str, object]:
+            """Спросить у хранилища и у позиции мира, какие дни собирает запуск."""
+            query = (SQL_ROOT / "dds" / "session_scope.sql").read_text(encoding="utf-8")
+            hook = ClickHouseHook(clickhouse_conn_id=CLICKHOUSE_CONNECTION)
+            row = hook.get_first(query, parameters={"position": _world_position()})
+            if row is None:
+                raise AirflowException(
+                    "в ods.event нет ни одного события: собирать нечего; "
+                    "проверьте, дошёл ли поток до хранилища"
+                )
+            first_day, last_day = row
+            # Пропуск, а не отказ: слой полон по последний прожитый день, а
+            # сегодняшний ещё идёт. Это обычное состояние повторного прогона,
+            # и в интерфейсе оно видно пропущенной группой.
+            if first_day is None:
+                raise AirflowSkipException(
+                    f"сессии собраны по {last_day} включительно, "
+                    "новых прожитых дней нет"
+                )
+            days = _days(first_day, last_day)
+            logging.info(
+                "объём сборки: %s … %s, дней %d",
+                first_day,
+                last_day,
+                len(days),
+            )
+            return {
+                "first_day": first_day.isoformat(),
+                "last_day": last_day.isoformat(),
+                "days": days,
+            }
+
+        days = scope()
+
+        rebuild = SQLExecuteQueryOperator(
+            task_id="rebuild",
+            conn_id=CLICKHOUSE_CONNECTION,
+            sql="dds/session_rebuild.sql",
+            parameters={
+                "load_id": "{{ run_id }}",
+                "first_day": days["first_day"],
+                "last_day": days["last_day"],
+            },
+            split_statements=True,
+            do_xcom_push=False,
+        )
+
+        replace = SQLExecuteQueryOperator.partial(
+            task_id="replace",
+            conn_id=CLICKHOUSE_CONNECTION,
+            sql="dds/session_replace.sql",
+            do_xcom_push=False,
+        ).expand_kwargs(replacements(days))
+
+        rebuild >> replace
+
+    source_ready = wait_for_source()
+    orders = order()
+    sessions = session()
+    source_ready >> [orders, sessions]
+
+    identity_map = SQLExecuteQueryOperator(
+        task_id="identity_map",
+        conn_id=CLICKHOUSE_CONNECTION,
+        sql="dds/identity_map_rebuild.sql",
+        parameters={"load_id": "{{ run_id }}"},
+        do_xcom_push=False,
+    )
+
+    orders >> identity_map
+
+
+dds_transform()

dags/dm_transform.py

@@ -0,0 +1,208 @@
+"""Трансформации слоя DM: сборка стендовых витрин.
+
+Выручка наследует ритм заказов. Сверка соединяет окно заказов с прожитым
+хвостом событий. Обе заменяют дневные партиции. Трафик наследует
+ретроспективность карты идентичностей и пересчитывает всю историю новой
+версией. Объем каждого прогона выводится из состояния слоев.
+"""
+
+from __future__ import annotations
+
+import datetime
+import logging
+from pathlib import Path
+
+from airflow.exceptions import AirflowException
+from airflow.providers.clickhousedb.hooks.clickhouse import ClickHouseHook
+from airflow.providers.common.sql.operators.sql import SQLExecuteQueryOperator
+from airflow.sdk import Variable, dag, task, task_group
+
+START_DATE = datetime.datetime(2026, 1, 1, tzinfo=datetime.UTC)
+
+SQL_ROOT = Path("/opt/airflow/sql")
+CLICKHOUSE_CONNECTION = "clickhouse_default"
+# Та же ось модельного времени, что у DDS. Общего модуля у дагов нет
+# намеренно: связь держит переменная Airflow, а не импорт одного дага другим.
+WORLD_POSITION = "world_position"
+
+
+def _world_position() -> int:
+    """Позиция мира для границы прожитых событий сверки.
+
+    Причина отдельного чтения переменной разобрана у одноименной функции в
+    ``dds_transform.py``.
+    """
+    raw_position = Variable.get(WORLD_POSITION, default=None)
+    if raw_position is None:
+        raise AirflowException(
+            "мир еще не создан: выполните make up и дождитесь world_initialize"
+        )
+    try:
+        position = int(raw_position)
+    except (TypeError, ValueError) as error:
+        raise AirflowException(
+            f"world_position={raw_position!r} не является номером дня; "
+            "выполните make rebuild-storage"
+        ) from error
+    if position < 1:
+        raise AirflowException(
+            f"мир не готов: world_position={position}; "
+            "выполните make up или make rebuild-storage"
+        )
+    return position
+
+
+def _days(first_day: datetime.date, last_day: datetime.date) -> list[str]:
+    """Дни отрезка строками - в таком виде их ждет замена партиции."""
+    return [
+        (first_day + datetime.timedelta(days=shift)).isoformat()
+        for shift in range((last_day - first_day).days + 1)
+    ]
+
+
+@task
+def replacements(scope: dict[str, object]) -> list[dict[str, object]]:
+    """Разложить дни в аргументы размноженной задачи замены.
+
+    Отдельный словарь нужен каждому экземпляру ``expand_kwargs``; тот же
+    прием разобран в ``dds_transform.py`` на замене партиций заказов.
+    """
+    return [{"params": {"day": day}} for day in scope["days"]]
+
+
+@dag(
+    dag_id="dm_transform",
+    schedule=None,
+    start_date=START_DATE,
+    is_paused_upon_creation=False,
+    max_active_runs=1,
+    template_searchpath=str(SQL_ROOT),
+    tags=["dm"],
+)
+def dm_transform():
+    """Пересобрать стендовые витрины по текущему состоянию DDS."""
+
+    @task_group(group_id="revenue_daily")
+    def revenue_daily():
+        """Выручка: изменяемое окно заказов и пропущенная история."""
+
+        @task
+        def scope() -> dict[str, object]:
+            """Спросить у хранилища, какие дни пересобирает запуск."""
+            query = (SQL_ROOT / "dm" / "revenue_daily_scope.sql").read_text(
+                encoding="utf-8"
+            )
+            hook = ClickHouseHook(clickhouse_conn_id=CLICKHOUSE_CONNECTION)
+            row = hook.get_first(query)
+            if row is None:
+                raise AirflowException(
+                    "нет слепка заказов в ODS или готовых заказов в DDS; "
+                    "дождитесь загрузки слепка и сначала выполните dds_transform"
+                )
+            first_day, last_day = row
+            days = _days(first_day, last_day)
+            logging.info(
+                "объем пересборки: %s … %s, дней %d",
+                first_day,
+                last_day,
+                len(days),
+            )
+            return {
+                "first_day": first_day.isoformat(),
+                "last_day": last_day.isoformat(),
+                "days": days,
+            }
+
+        days = scope()
+
+        rebuild = SQLExecuteQueryOperator(
+            task_id="rebuild",
+            conn_id=CLICKHOUSE_CONNECTION,
+            sql="dm/revenue_daily_rebuild.sql",
+            parameters={
+                "load_id": "{{ run_id }}",
+                "first_day": days["first_day"],
+                "last_day": days["last_day"],
+            },
+            split_statements=True,
+            do_xcom_push=False,
+        )
+
+        replace = SQLExecuteQueryOperator.partial(
+            task_id="replace",
+            conn_id=CLICKHOUSE_CONNECTION,
+            sql="dm/revenue_daily_replace.sql",
+            do_xcom_push=False,
+        ).expand_kwargs(replacements(days))
+
+        rebuild >> replace
+
+    revenue_daily()
+
+    @task_group(group_id="purchase_vs_orders")
+    def purchase_vs_orders():
+        """Сверка: окно заказов, прожитый хвост и предварительные дни."""
+
+        @task
+        def scope() -> dict[str, object]:
+            """Спросить у обоих источников, какие дни пересобрать."""
+            query = (SQL_ROOT / "dm" / "purchase_vs_orders_scope.sql").read_text(
+                encoding="utf-8"
+            )
+            hook = ClickHouseHook(clickhouse_conn_id=CLICKHOUSE_CONNECTION)
+            row = hook.get_first(query, parameters={"position": _world_position()})
+            if row is None:
+                raise AirflowException(
+                    "нет принятого слепка заказов или прожитых покупок; "
+                    "дождитесь источников и сначала выполните dds_transform"
+                )
+            first_day, last_day = row
+            days = _days(first_day, last_day)
+            logging.info(
+                "объем пересборки: %s … %s, дней %d",
+                first_day,
+                last_day,
+                len(days),
+            )
+            return {
+                "first_day": first_day.isoformat(),
+                "last_day": last_day.isoformat(),
+                "days": days,
+            }
+
+        days = scope()
+
+        rebuild = SQLExecuteQueryOperator(
+            task_id="rebuild",
+            conn_id=CLICKHOUSE_CONNECTION,
+            sql="dm/purchase_vs_orders_rebuild.sql",
+            parameters={
+                "load_id": "{{ run_id }}",
+                "first_day": days["first_day"],
+                "last_day": days["last_day"],
+            },
+            split_statements=True,
+            do_xcom_push=False,
+        )
+
+        replace = SQLExecuteQueryOperator.partial(
+            task_id="replace",
+            conn_id=CLICKHOUSE_CONNECTION,
+            sql="dm/purchase_vs_orders_replace.sql",
+            do_xcom_push=False,
+        ).expand_kwargs(replacements(days))
+
+        rebuild >> replace
+
+    purchase_vs_orders()
+
+    SQLExecuteQueryOperator(
+        task_id="daily_traffic",
+        conn_id=CLICKHOUSE_CONNECTION,
+        sql="dm/daily_traffic_rebuild.sql",
+        parameters={"load_id": "{{ run_id }}"},
+        do_xcom_push=False,
+    )
+
+
+dm_transform()

dags/dq_check.py

@@ -0,0 +1,319 @@
+"""Проверки качества стендовых моделей и витрин.
+
+Пять проверок сначала собирают общий донор. После его полной сборки дневные
+партиции публикуются одной серией замен, и только затем именованные задачи
+утверждают результат. Расхождение поэтому остаётся в ``dm.dq_summary_v`` до
+красного завершения дага; ошибка сборки прежнюю сводку не меняет.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import logging
+from pathlib import Path
+
+from airflow.exceptions import AirflowException
+from airflow.providers.clickhousedb.hooks.clickhouse import ClickHouseHook
+from airflow.providers.common.sql.operators.sql import SQLExecuteQueryOperator
+from airflow.sdk import Variable, dag, get_current_context, task, task_group
+
+START_DATE = datetime.datetime(2026, 1, 1, tzinfo=datetime.UTC)
+
+SQL_ROOT = Path("/opt/airflow/sql")
+INVENTORY_PATH = Path("/opt/airflow/world/data/world-inventory.json")
+CLICKHOUSE_CONNECTION = "clickhouse_default"
+WORLD_POSITION = "world_position"
+DETAIL_LIMIT = 20
+
+SUMMARY_COLUMNS = [
+    "data_date",
+    "check_name",
+    "reference_rows",
+    "actual_rows",
+    "failed_rows",
+    "status",
+    "_load_id",
+    "_load_ts",
+]
+
+
+def _clickhouse_hook() -> ClickHouseHook:
+    """Подключение, которое дожидается записи в Distributed-таблицу."""
+    return ClickHouseHook(
+        clickhouse_conn_id=CLICKHOUSE_CONNECTION,
+        session_settings={"distributed_foreground_insert": 1},
+    )
+
+
+def _world_position() -> int:
+    """Первый несыгранный день оси мира."""
+    raw_position = Variable.get(WORLD_POSITION, default=None)
+    if raw_position is None:
+        raise AirflowException(
+            "мир еще не создан: выполните make up и дождитесь world_initialize"
+        )
+    try:
+        position = int(raw_position)
+    except (TypeError, ValueError) as error:
+        raise AirflowException(
+            f"world_position={raw_position!r} не является номером дня; "
+            "выполните make rebuild-storage"
+        ) from error
+    if position < 1:
+        raise AirflowException(
+            f"мир не готов: world_position={position}; "
+            "выполните make up или make rebuild-storage"
+        )
+    return position
+
+
+def _publish_summary(
+    check_name: str,
+    summaries: list[tuple[object, ...]],
+) -> list[str]:
+    """Записать дневную сводку и вернуть малый срез готовой диагностики."""
+    if not summaries:
+        raise AirflowException(f"{check_name}: область проверки пуста")
+
+    diagnostics: list[str] = []
+    context = get_current_context()
+    load_id = context["run_id"]
+    load_ts = datetime.datetime.now(datetime.UTC)
+    rows = []
+    for (
+        data_date,
+        reference_rows,
+        actual_rows,
+        failed_rows,
+        details,
+    ) in summaries:
+        rows.append(
+            (
+                data_date,
+                check_name,
+                reference_rows,
+                actual_rows,
+                failed_rows,
+                "pass" if failed_rows == 0 else "fail",
+                load_id,
+                load_ts,
+            )
+        )
+        diagnostics.extend(details[: DETAIL_LIMIT - len(diagnostics)])
+
+    _clickhouse_hook().bulk_insert_rows(
+        "dm.dq_summary_stage_dist",
+        rows,
+        column_names=SUMMARY_COLUMNS,
+    )
+    return diagnostics
+
+
+def _build_sql_check(
+    check_name: str,
+    sql_name: str,
+    parameters: dict[str, object] | None = None,
+) -> list[str]:
+    """Выполнить SQL-сверку и записать ее дневные итоги в донор."""
+    query = (SQL_ROOT / "dq" / sql_name).read_text(encoding="utf-8")
+    summaries = _clickhouse_hook().get_records(query, parameters=parameters)
+    return _publish_summary(check_name, summaries)
+
+
+@task
+def build_sql_check(check_name: str, sql_name: str) -> list[str]:
+    """Собрать проверку, которой не нужны координаты модельного мира."""
+    return _build_sql_check(check_name, sql_name)
+
+
+@task
+def build_sessions_vs_reference() -> list[str]:
+    """Сверить сессии только в пределах прожитых дней мира."""
+    return _build_sql_check(
+        "sessions_vs_reference",
+        "sessions_vs_reference.sql",
+        parameters={"position": _world_position()},
+    )
+
+
+@task
+def build_classes_vs_inventory() -> list[str]:
+    """Сопоставить классы закрытых дней с техническим оракулом генератора."""
+    inventory = json.loads(INVENTORY_PATH.read_text(encoding="utf-8"))
+    expected = {
+        (datetime.date.fromisoformat(day["date"]), mismatch_class): count
+        for day in inventory["days"]
+        if "orders" in day
+        for mismatch_class, count in day["orders"].items()
+    }
+    if not expected:
+        raise AirflowException("classes_vs_inventory: в описи нет закрытых дней")
+
+    query = (SQL_ROOT / "dq" / "classes_vs_inventory.sql").read_text(encoding="utf-8")
+    # GROUP BY закономерно не возвращает группу из нуля строк.
+    actual = {key: 0 for key, count in expected.items() if count == 0}
+    actual.update(
+        {
+            (data_date, mismatch_class): count
+            for data_date, mismatch_class, count in _clickhouse_hook().get_records(
+                query
+            )
+            if (data_date, mismatch_class) in expected
+        }
+    )
+    summaries = []
+    for data_date in sorted({day for day, _ in expected}):
+        details = []
+        reference_rows = 0
+        actual_rows = 0
+        failed_rows = 0
+        for (day, mismatch_class), reference_count in sorted(expected.items()):
+            if day != data_date:
+                continue
+            actual_key = (day, mismatch_class)
+            actual_count = actual.get(actual_key)
+            reference_rows += 1
+            actual_rows += int(actual_key in actual)
+            if reference_count != actual_count:
+                failed_rows += 1
+                actual_text = actual_count if actual_count is not None else "нет ключа"
+                details.append(
+                    f"{day} key={mismatch_class}: "
+                    f"эталон={reference_count}, "
+                    f"объект={actual_text}"
+                )
+        summaries.append((data_date, reference_rows, actual_rows, failed_rows, details))
+    return _publish_summary("classes_vs_inventory", summaries)
+
+
+@task
+def publication_scope() -> list[dict[str, dict[str, str]]]:
+    """Вернуть дни полностью собранного донора для размноженной замены."""
+    rows = _clickhouse_hook().get_records(
+        "SELECT DISTINCT data_date FROM dm.dq_summary_stage_dist ORDER BY data_date"
+    )
+    if not rows:
+        raise AirflowException("донор dm.dq_summary пуст: публиковать нечего")
+    return [{"params": {"day": data_date.isoformat()}} for (data_date,) in rows]
+
+
+@task
+def drop_stale_partitions() -> None:
+    """Убрать дни, исчезнувшие после починки с обеих сторон сверки."""
+    hook = _clickhouse_hook()
+    stale_days = hook.get_records(
+        """
+        SELECT DISTINCT data_date
+        FROM dm.dq_summary_dist
+        WHERE data_date GLOBAL NOT IN
+            (SELECT data_date FROM dm.dq_summary_stage_dist)
+        ORDER BY data_date
+        """
+    )
+    for (data_date,) in stale_days:
+        # ALTER PARTITION не принимает параметр ClickHouse. Значение пришло
+        # из колонки Date самого хранилища и форматируется без внешнего ввода.
+        hook.run(
+            "ALTER TABLE dm.dq_summary_rep ON CLUSTER clickstream_cluster "
+            f"DROP PARTITION '{data_date.isoformat()}'"
+        )
+
+
+@task
+def assert_check(check_name: str, diagnostics: list[str]) -> None:
+    """Покрасить именованную задачу по уже опубликованной сводке."""
+    failed_days = _clickhouse_hook().get_records(
+        """
+        SELECT data_date, reference_rows, actual_rows, failed_rows
+        FROM dm.dq_summary_v
+        WHERE check_name = {check_name:String} AND failed_rows > 0
+        ORDER BY data_date
+        """,
+        parameters={"check_name": check_name},
+    )
+    if not failed_days:
+        return
+
+    for detail in diagnostics:
+        logging.error("%s: %s", check_name, detail)
+    summary = "; ".join(
+        f"{data_date}: эталонных ключей {reference_rows}, "
+        f"фактических {actual_rows}, нарушено {failed_rows}"
+        for data_date, reference_rows, actual_rows, failed_rows in failed_days
+    )
+    raise AirflowException(f"{check_name}: {summary}")
+
+
+@dag(
+    dag_id="dq_check",
+    schedule=None,
+    start_date=START_DATE,
+    is_paused_upon_creation=False,
+    max_active_runs=1,
+    template_searchpath=str(SQL_ROOT),
+    tags=["dq"],
+)
+def dq_check():
+    """Собрать, опубликовать и утвердить текущее качество данных."""
+    prepare = SQLExecuteQueryOperator(
+        task_id="prepare",
+        conn_id=CLICKHOUSE_CONNECTION,
+        sql="dq/prepare.sql",
+        do_xcom_push=False,
+    )
+
+    sessions = build_sessions_vs_reference()
+    classes = build_classes_vs_inventory.override(
+        task_id="build_classes_vs_inventory"
+    )()
+    revenue = build_sql_check.override(task_id="build_revenue_daily_vs_dds")(
+        "revenue_daily_vs_dds", "revenue_daily_vs_dds.sql"
+    )
+    purchases = build_sql_check.override(task_id="build_purchase_vs_orders_vs_dds")(
+        "purchase_vs_orders_vs_dds", "purchase_vs_orders_vs_dds.sql"
+    )
+    traffic = build_sql_check.override(task_id="build_daily_traffic_vs_dds")(
+        "daily_traffic_vs_dds", "daily_traffic_vs_dds.sql"
+    )
+    builders = [sessions, classes, revenue, purchases, traffic]
+    prepare >> builders
+
+    days = publication_scope()
+    for builder in builders:
+        builder >> days
+
+    replace = SQLExecuteQueryOperator.partial(
+        task_id="publish",
+        conn_id=CLICKHOUSE_CONNECTION,
+        sql="dq/replace.sql",
+        do_xcom_push=False,
+    ).expand_kwargs(days)
+
+    sessions_assertion = assert_check.override(task_id="sessions_vs_reference")(
+        "sessions_vs_reference", sessions
+    )
+    classes_assertion = assert_check.override(task_id="classes_vs_inventory")(
+        "classes_vs_inventory", classes
+    )
+
+    @task_group(group_id="marts_vs_dds")
+    def assert_marts():
+        return [
+            assert_check.override(task_id="revenue_daily_vs_dds")(
+                "revenue_daily_vs_dds", revenue
+            ),
+            assert_check.override(task_id="purchase_vs_orders_vs_dds")(
+                "purchase_vs_orders_vs_dds", purchases
+            ),
+            assert_check.override(task_id="daily_traffic_vs_dds")(
+                "daily_traffic_vs_dds", traffic
+            ),
+        ]
+
+    assertions = [sessions_assertion, classes_assertion, *assert_marts()]
+    remove_stale = drop_stale_partitions()
+    replace >> remove_stale >> assertions
+
+
+dq_check()

dags/etl_pipeline.py

@@ -0,0 +1,53 @@
+"""Дневной конвейер: DDS, DM и проверка качества.
+
+Своих преобразований у дага нет. Ждущие триггеры связывают состояния:
+если слой краснеет, конвейер не запускает следующий слой и краснеет сам.
+"""
+
+from __future__ import annotations
+
+import datetime
+
+from airflow.providers.standard.operators.trigger_dagrun import TriggerDagRunOperator
+from airflow.sdk import dag
+
+START_DATE = datetime.datetime(2026, 1, 1, tzinfo=datetime.UTC)
+
+
+@dag(
+    dag_id="etl_pipeline",
+    schedule=None,
+    start_date=START_DATE,
+    is_paused_upon_creation=False,
+    max_active_runs=1,
+    tags=["etl"],
+)
+def etl_pipeline():
+    """Собрать слои последовательно по текущему состоянию данных."""
+    dds = TriggerDagRunOperator(
+        task_id="trigger_dds",
+        trigger_dag_id="dds_transform",
+        wait_for_completion=True,
+        poke_interval=10,
+    )
+    dm = TriggerDagRunOperator(
+        task_id="trigger_dm",
+        trigger_dag_id="dm_transform",
+        wait_for_completion=True,
+        poke_interval=10,
+    )
+    # Airflow 3.3: оператор провайдера standard с wait_for_completion=True
+    # поднимает AirflowException, если запущенный даг завершился красным.
+    # Поведение и путь импорта повторно сверены через Context7 27 августа
+    # 2026 года.
+    dq = TriggerDagRunOperator(
+        task_id="trigger_dq",
+        trigger_dag_id="dq_check",
+        wait_for_completion=True,
+        poke_interval=10,
+    )
+
+    dds >> dm >> dq
+
+
+etl_pipeline()

dags/homework_check.py

@@ -0,0 +1,138 @@
+"""Ручная самопроверка учебных витрин DM против их источников."""
+
+from __future__ import annotations
+
+import datetime
+import logging
+from pathlib import Path
+
+from airflow.exceptions import AirflowException
+from airflow.providers.clickhousedb.hooks.clickhouse import ClickHouseHook
+from airflow.sdk import dag, task
+
+START_DATE = datetime.datetime(2026, 1, 1, tzinfo=datetime.UTC)
+SQL_ROOT = Path("/opt/airflow/sql/dq")
+CLICKHOUSE_CONNECTION = "clickhouse_default"
+DETAIL_LIMIT = 20
+
+
+def _clickhouse_hook() -> ClickHouseHook:
+    """Подключение к ClickHouse для чтения обеих сторон сверки."""
+    return ClickHouseHook(clickhouse_conn_id=CLICKHOUSE_CONNECTION)
+
+
+def _mart_exists(hook: ClickHouseHook, mart: str) -> bool:
+    """Проверить наличие публичной витрины на ноде подключения."""
+    database, name = mart.split(".", maxsplit=1)
+    rows = hook.get_records(
+        """
+        SELECT count()
+        FROM system.tables
+        WHERE database = {database:String} AND name = {name:String}
+        """,
+        parameters={"database": database, "name": name},
+    )
+    return rows[0][0] == 1
+
+
+@task
+def check_mart(
+    mart: str,
+    lab_path: str,
+    sql_name: str,
+    scope_sql_name: str | None = None,
+) -> None:
+    """Сверить одну домашнюю витрину с независимым ответом из источника."""
+    hook = _clickhouse_hook()
+    if not _mart_exists(hook, mart):
+        raise AirflowException(f"витрина {mart} не найдена; выполните ТЗ {lab_path}")
+
+    try:
+        query = (SQL_ROOT / sql_name).read_text(encoding="utf-8")
+        scope_query = (
+            (SQL_ROOT / scope_sql_name).read_text(encoding="utf-8")
+            if scope_sql_name is not None
+            else None
+        )
+    except OSError as error:
+        raise AirflowException(
+            f"стенд не может прочитать запрос проверки {sql_name}: {error}; "
+            "сообщите наставнику"
+        ) from error
+
+    try:
+        parameter_sets = [None]
+        if scope_query is not None:
+            parameter_sets = [{"day": day} for (day,) in hook.get_records(scope_query)]
+        summaries = [
+            summary
+            for parameters in parameter_sets
+            for summary in hook.get_records(query, parameters=parameters)
+        ]
+    except Exception as error:
+        raise AirflowException(
+            f"не удалось проверить витрину {mart}: {error}; "
+            f"сверьте договор колонок и проверку в ТЗ {lab_path}"
+        ) from error
+
+    failed_rows = sum(summary[3] for summary in summaries)
+    if failed_rows == 0:
+        return
+
+    diagnostics = [detail for summary in summaries for detail in summary[4]][
+        :DETAIL_LIMIT
+    ]
+    for detail in diagnostics:
+        logging.error("%s: %s", mart, detail)
+    days = "; ".join(
+        f"{data_date}: ключей источника {reference_rows}, "
+        f"ключей витрины {actual_rows}, расходятся {day_failed_rows}"
+        for data_date, reference_rows, actual_rows, day_failed_rows, _ in summaries
+        if day_failed_rows > 0
+    )
+    compared_sides = diagnostics[0]
+    raise AirflowException(
+        f"витрина {mart} расходится с источником: {days}. "
+        f"Пример сравнения: {compared_sides}. Сверьтесь с ТЗ {lab_path}"
+    )
+
+
+@dag(
+    dag_id="homework_check",
+    schedule=None,
+    start_date=START_DATE,
+    is_paused_upon_creation=False,
+    max_active_runs=1,
+    tags=["dm", "labs"],
+)
+def homework_check():
+    """Дать отдельный результат самопроверки по каждой домашней витрине."""
+    check_mart.override(task_id="events_enriched")(
+        "dm.events_enriched_v",
+        "docs/labs/events-enriched.md",
+        "events_enriched_vs_dds.sql",
+        "events_enriched_scope.sql",
+    )
+    check_mart.override(task_id="top_pages_daily")(
+        "dm.top_pages_daily_v",
+        "docs/labs/top-pages-daily.md",
+        "top_pages_daily_vs_dds.sql",
+    )
+    check_mart.override(task_id="session_overview")(
+        "dm.session_overview_v",
+        "docs/labs/session-overview.md",
+        "session_overview_vs_dds.sql",
+    )
+    check_mart.override(task_id="dq_errors_daily")(
+        "dm.dq_errors_daily_v",
+        "docs/labs/dq-errors-daily.md",
+        "dq_errors_daily_vs_ods.sql",
+    )
+    check_mart.override(task_id="utm_effectiveness")(
+        "dm.utm_effectiveness_v",
+        "docs/labs/utm-effectiveness.md",
+        "utm_effectiveness_vs_dds.sql",
+    )
+
+
+homework_check()

dags/orders_ingest.py

@@ -18,9 +18,9 @@
 from __future__ import annotations
 
 import datetime
-import logging
 
-from airflow.sdk import Connection, dag, get_current_context, task
+from airflow.providers.common.sql.operators.sql import SQLExecuteQueryOperator
+from airflow.sdk import dag
 
 START_DATE = datetime.datetime(2026, 1, 1, tzinfo=datetime.UTC)
 
@@ -43,67 +43,25 @@ SQL_ROOT = "/opt/airflow/sql"
 )
 def orders_ingest():
     """Забрать приехавший слепок заказов и разложить его по слоям."""
-
+    pull_batch = SQLExecuteQueryOperator(
-    def clickhouse_client():
+        task_id="pull_batch",
-        # Импорт при выполнении задачи, а не при разборе файла: обработчик DAG
+        conn_id="clickhouse_default",
-        # разбирает его снова и снова, и импорт наверху оплачивался бы каждым
+        sql="stg/orders_raw_load.sql",
-        # разбором.
+        parameters={"load_id": "{{ run_id }}"},
-        import clickhouse_connect
+        do_xcom_push=False,
-
-        connection = Connection.get("clickhouse_default")
-        return clickhouse_connect.get_client(
-            host=connection.host,
-            port=connection.port,
-            username=connection.login,
-            password=connection.password,
-            database=connection.schema or "default",
-            connect_timeout=5,
-            send_receive_timeout=30,
-        )
-
-    # Аргумент с расширением из templates_exts Airflow подменяет текстом файла:
-    # берёт его из template_searchpath и прогоняет через Jinja при исполнении
-    # задачи, а не при разборе дага. В задачу приезжает готовый запрос — вместе
-    # с тем, что файл подключил через include.
-    @task(templates_exts=(".sql",))
-    def pull_batch(sql: str) -> None:
-        load_id = get_current_context()["run_id"]
-        client = clickhouse_client()
-        try:
-            summary = client.command(sql, parameters={"load_id": load_id})
-        finally:
-            client.close()
-        # Размер порции — read_rows: written_rows у вставки в Distributed
-        # считает не приехавшее.
-        logging.info(
-            "порция принята: строк %s, _load_id %s",
-            summary.summary["read_rows"],
-            load_id,
-        )
-
-    @task(templates_exts=(".sql",))
-    def parse_batch(good_rows_sql: str, bad_rows_sql: str) -> None:
-        """Разобрать срез сырья в версии заказов и в брак.
-
-        Обе вставки в одном task_id: транзакции между ними ClickHouse не даёт,
-        а повтор задачи безопасен — срез читается по тому же неизменному
-        _load_id (docs/architecture/orders/ingestion.md, «Поток данных»).
-        """
-        load_id = get_current_context()["run_id"]
-        client = clickhouse_client()
-        try:
-            client.command(good_rows_sql, parameters={"load_id": load_id})
-            client.command(bad_rows_sql, parameters={"load_id": load_id})
-        finally:
-            client.close()
-        # Счётчиков строк нет: у запроса с WHERE read_rows считает прочитанное
-        # с диска, а не подошедшее (storage.md, «Что проверено»).
-        logging.info("срез разобран: _load_id %s", load_id)
-
-    pull_batch("stg/orders_raw_load.sql") >> parse_batch(
-        "ods/order_load.sql",
-        "ods/order_errors_load.sql",
     )
+    parse_batch = SQLExecuteQueryOperator(
+        task_id="parse_batch",
+        conn_id="clickhouse_default",
+        sql="ods/order_parse.sql",
+        parameters={"load_id": "{{ run_id }}"},
+        split_statements=True,
+        do_xcom_push=False,
+    )
+
+    # ClickHouse не даёт транзакции между двумя вставками parse_batch. Один
+    # task_id сохраняет их порядок и одну точку повтора для неизменного load_id.
+    pull_batch >> parse_batch
 
 
 orders_ingest()

dags/test_clickhouse.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 import datetime
 import uuid
 
+from airflow.providers.clickhousedb.hooks.clickhouse import ClickHouseHook
 from airflow.sdk import Connection, dag, get_current_context, task
 
 CLUSTER = "clickstream_cluster"
@@ -54,27 +55,12 @@ def _remote_parameters() -> dict[str, str]:
     }
 
 
-def _clickhouse_client():
+def _clickhouse_hook() -> ClickHouseHook:
-    # clickhouse_connect импортируется внутри функции, а не наверху файла:
+    return ClickHouseHook(clickhouse_conn_id="clickhouse_default")
-    # обработчик DAG разбирает этот файл снова и снова, и импорт наверху
-    # оплачивался бы каждым разбором. Тяжёлые импорты Airflow советует
-    # держать внутри задач.
-    import clickhouse_connect
-
-    connection = Connection.get("clickhouse_default")
-    return clickhouse_connect.get_client(
-        host=connection.host,
-        port=connection.port,
-        username=connection.login,
-        password=connection.password,
-        database=connection.schema or "default",
-        connect_timeout=5,
-        send_receive_timeout=30,
-    )
 
 
-def _table_engines(client, source: str) -> list[tuple[str, str]]:
+def _table_engines(hook: ClickHouseHook, source: str) -> list[tuple[str, str]]:
-    result = client.query(
+    return hook.get_records(
         f"""
         SELECT name, engine
         FROM {source}
@@ -84,23 +70,23 @@ def _table_engines(client, source: str) -> list[tuple[str, str]]:
         """,
         parameters=_remote_parameters(),
     )
-    return result.result_rows
 
 
-def _drop_tables(client) -> None:
+def _drop_tables(hook: ClickHouseHook) -> None:
-    client.command(
+    hook.run(
-        f"DROP TABLE IF EXISTS default.{DISTRIBUTED_TABLE} ON CLUSTER {CLUSTER} SYNC"
+        [
-    )
+            f"DROP TABLE IF EXISTS default.{DISTRIBUTED_TABLE} "
-    client.command(
+            f"ON CLUSTER {CLUSTER} SYNC",
-        f"DROP TABLE IF EXISTS default.{LOCAL_TABLE} ON CLUSTER {CLUSTER} SYNC"
+            f"DROP TABLE IF EXISTS default.{LOCAL_TABLE} ON CLUSTER {CLUSTER} SYNC",
+        ],
     )
 
 
 # Отсутствие таблиц проверяют обе задачи — перед созданием и после уборки,
 # — поэтому у этой проверки своё имя, а остальные живут прямо в теле задач.
-def _assert_tables_absent(client) -> None:
+def _assert_tables_absent(hook: ClickHouseHook) -> None:
     for node_name, source in NODES:
-        remaining = _table_engines(client, source)
+        remaining = _table_engines(hook, source)
         if remaining:
             raise RuntimeError(
                 f"служебные таблицы остались на {node_name}: {remaining}"
@@ -118,11 +104,11 @@ def _assert_tables_absent(client) -> None:
 def test_clickhouse():
     @task
     def prepare_tables() -> None:
-        client = _clickhouse_client()
+        hook = _clickhouse_hook()
-        try:
+        _drop_tables(hook)
-            _drop_tables(client)
+        _assert_tables_absent(hook)
-            _assert_tables_absent(client)
+        hook.run(
-            client.command(
+            [
                 f"""
                 CREATE TABLE default.{LOCAL_TABLE} ON CLUSTER {CLUSTER}
                 (
@@ -133,9 +119,7 @@ def test_clickhouse():
                     '{{replica}}'
                 )
                 ORDER BY marker
-                """
+                """,
-            )
-            client.command(
                 f"""
                 CREATE TABLE default.{DISTRIBUTED_TABLE} ON CLUSTER {CLUSTER}
                 AS default.{LOCAL_TABLE}
@@ -145,86 +129,77 @@ def test_clickhouse():
                     '{LOCAL_TABLE}',
                     cityHash64(marker)
                 )
-                """
+                """,
-            )
+            ],
-            for node_name, source in NODES:
+        )
-                actual_tables = _table_engines(client, source)
+        for node_name, source in NODES:
-                if actual_tables != EXPECTED_TABLES:
+            actual_tables = _table_engines(hook, source)
-                    raise RuntimeError(
+            if actual_tables != EXPECTED_TABLES:
-                        f"неверный набор таблиц на {node_name}: {actual_tables}"
+                raise RuntimeError(
-                    )
+                    f"неверный набор таблиц на {node_name}: {actual_tables}"
-        finally:
+                )
-            client.close()
 
     @task
     def write_marker() -> dict[str, str]:
-        client = _clickhouse_client()
+        hook = _clickhouse_hook()
-        try:
+        marker = f"{get_current_context()['run_id']}:{uuid.uuid4()}"
-            marker = f"{get_current_context()['run_id']}:{uuid.uuid4()}"
+        hook.bulk_insert_rows(
-            client.insert(
+            f"default.{LOCAL_TABLE}",
-                f"default.{LOCAL_TABLE}",
+            [[marker]],
-                [[marker]],
+            column_names=["marker"],
-                column_names=["marker"],
+        )
-            )
+        local_rows = hook.get_records(
-            local_rows = client.query(
+            f"""
-                f"""
+            SELECT hostName(), marker
-                SELECT hostName(), marker
+            FROM default.{LOCAL_TABLE}
-                FROM default.{LOCAL_TABLE}
+            WHERE marker = {{marker:String}}
-                WHERE marker = {{marker:String}}
+            """,
-                """,
+            parameters={"marker": marker},
-                parameters={"marker": marker},
+        )
-            ).result_rows
+        if len(local_rows) != 1 or local_rows[0][1] != marker:
-            if len(local_rows) != 1 or local_rows[0][1] != marker:
+            raise RuntimeError(f"маркер не найден в локальной таблице: {marker}")
-                raise RuntimeError(f"маркер не найден в локальной таблице: {marker}")
+        return {"marker": marker, "hostname": local_rows[0][0]}
-            return {"marker": marker, "hostname": local_rows[0][0]}
-        finally:
-            client.close()
 
     @task
     def read_from_node_2(written: dict[str, str]) -> None:
-        client = _clickhouse_client()
+        hook = _clickhouse_hook()
-        try:
+        node_2_rows = hook.get_records(
-            node_2_rows = client.query(
+            """
-                """
+            SELECT hostName()
-                SELECT hostName()
+            FROM remote(
-                FROM remote(
+                'clickhouse-02:9000', 'system', 'one',
-                    'clickhouse-02:9000', 'system', 'one',
+                {remote_user:String}, {remote_password:String}
-                    {remote_user:String}, {remote_password:String}
+            )
-                )
+            """,
-                """,
+            parameters=_remote_parameters(),
-                parameters=_remote_parameters(),
+        )
-            ).result_rows
+        if len(node_2_rows) != 1:
-            if len(node_2_rows) != 1:
+            raise RuntimeError(f"не удалось определить имя ноды 2: {node_2_rows}")
-                raise RuntimeError(f"не удалось определить имя ноды 2: {node_2_rows}")
+        distributed_rows = hook.get_records(
-            distributed_rows = client.query(
+            f"""
-                f"""
+            SELECT _shard_num, hostName(), marker
-                SELECT _shard_num, hostName(), marker
+            FROM remote(
-                FROM remote(
+                'clickhouse-02:9000',
-                    'clickhouse-02:9000',
+                'default',
-                    'default',
+                '{DISTRIBUTED_TABLE}',
-                    '{DISTRIBUTED_TABLE}',
+                {{remote_user:String}},
-                    {{remote_user:String}},
+                {{remote_password:String}}
-                    {{remote_password:String}}
+            )
-                )
+            WHERE marker = {{marker:String}}
-                WHERE marker = {{marker:String}}
+            """,
-                """,
+            parameters={
-                parameters={
+                "marker": written["marker"],
-                    "marker": written["marker"],
+                **_remote_parameters(),
-                    **_remote_parameters(),
+            },
-                },
+        )
-            ).result_rows
+        if written["hostname"] == node_2_rows[0][0]:
-            if written["hostname"] == node_2_rows[0][0]:
+            raise RuntimeError("запись и чтение маркера должны идти с разных нод")
-                raise RuntimeError(
+        expected_rows = [(1, written["hostname"], written["marker"])]
-                    "запись и чтение маркера должны выполняться с разных нод"
+        if distributed_rows != expected_rows:
-                )
+            raise RuntimeError(
-            expected_rows = [(1, written["hostname"], written["marker"])]
+                "нода 2 не прочитала маркер первого шарда через Distributed: "
-            if distributed_rows != expected_rows:
+                f"{written['marker']}, получено {distributed_rows}"
-                raise RuntimeError(
+            )
-                    "нода 2 не прочитала маркер первого шарда через Distributed: "
-                    f"{written['marker']}, получено {distributed_rows}"
-                )
-        finally:
-            client.close()
 
     # Уборка идёт только после успеха: упавший пробник оставляет кластер таким,
     # каким сломался, а остатки сносит начало следующего запуска. Правило
@@ -233,12 +208,9 @@ def test_clickhouse():
     # с упавшей проверкой (ADR 0003).
     @task
     def cleanup_tables() -> None:
-        client = _clickhouse_client()
+        hook = _clickhouse_hook()
-        try:
+        _drop_tables(hook)
-            _drop_tables(client)
+        _assert_tables_absent(hook)
-            _assert_tables_absent(client)
-        finally:
-            client.close()
 
     prepared = prepare_tables()
     written = write_marker()

dags/world_control.py

@@ -12,6 +12,9 @@
 идут отправка слепка тем же контейнером генератора и ждущий триггер дага приёма
 `orders_ingest`.
 
+Живой день после установки позиции дожидается еще и `etl_pipeline`. Пачка
+только разгоняет источники: слои после нее менти догоняет ручным запуском.
+
 Разделение не косметическое. Расписание на самом работнике заставило бы кнопку
 паузы значить две вещи разом — «мир не едет сам» и «даг выключен», — а работник
 при этом выглядел бы в списке выключенным, хотя нажимают его каждый день.
@@ -25,8 +28,10 @@
 from __future__ import annotations
 
 import datetime
+import logging
 import os
 
+from airflow.exceptions import AirflowException
 from airflow.providers.docker.operators.docker import DockerOperator
 from airflow.providers.standard.operators.trigger_dagrun import TriggerDagRunOperator
 from airflow.sdk import Param, Variable, dag, get_current_context, task
@@ -45,8 +50,8 @@ GENERATOR_ENVIRONMENT = {
 ORDERS_TOPIC = os.environ["KAFKA_ORDERS_TOPIC"]
 STARTING_DAYS = int(os.environ["WORLD_STARTING_DAYS"])
 
-# Позиция на оси: номер первого несыгранного дня. Переменной нет — мир в
+# Позиция на оси: номер первого несыгранного дня. До конца инициализации
-# стартовом состоянии, и играть надо сразу за ним.
+# работники не имеют права угадывать её — состояние объяснено в ADR 0013.
 #
 # Позиция ставится, а не увеличивается. Наложись один прогон на другой, худшее
 # при таком правиле — сыгранный дважды день, а повтор схлопнет
@@ -69,7 +74,24 @@ TAGS = ["пульт мира"]
 @task
 def first_unplayed_day() -> int:
     """Номер дня, с которого играть."""
-    return int(Variable.get(WORLD_POSITION, default=STARTING_DAYS))
+    raw_position = Variable.get(WORLD_POSITION, default=None)
+    if raw_position is None:
+        raise AirflowException(
+            "мир ещё не создан: выполните make up и дождитесь world_initialize"
+        )
+    try:
+        position = int(raw_position)
+    except (TypeError, ValueError) as error:
+        raise AirflowException(
+            f"world_position={raw_position!r} не является номером дня; "
+            "выполните make rebuild-storage"
+        ) from error
+    if position < STARTING_DAYS:
+        action = (
+            "выполните make up" if position == 0 else "выполните make rebuild-storage"
+        )
+        raise AirflowException(f"мир не готов: world_position={position}; {action}")
+    return position
 
 
 def _generator(task_id: str, command: list[str]) -> DockerOperator:
@@ -120,7 +142,19 @@ def _ingest_orders() -> TriggerDagRunOperator:
     tags=TAGS,
     params={
         "days": Param(
-            1, type="integer", minimum=1, maximum=7, title="Сколько дней прожить"
+            1,
+            type="integer",
+            minimum=1,
+            maximum=7,
+            title="Сколько дней прожить",
+            # description_md рендерится подсказкой прямо в форме запуска
+            # (params.rst, Airflow 3.3), чтобы правило было видно сразу.
+            description_md=(
+                "Форма задает только число дней. Номер первого несыгранного "
+                "дня работник берет из переменной `world_position` (Admin → "
+                "Variables). Поля Logical date и Run ID нужны самому Airflow "
+                "и на выбор дня не влияют."
+            ),
         )
     },
 )
@@ -128,14 +162,20 @@ def world_next_day():
     """Прожить следующие дни пачкой, без пауз.
 
     Запускается руками. День по умолчанию один, но разгон вперёд идёт одним
-    нажимом, а не десятью: сколько дней играть — параметр запуска.
+    нажимом, а не десятью: сколько дней играть — параметр запуска. Первый
+    день работник берет из `world_position`. Логическая дата прогона на выбор
+    дня не влияет.
     """
 
     @task
     def remember_played(first_day: int) -> None:
         """Позиция ставится по сыгранным дням и только по успеху."""
         days = get_current_context()["params"]["days"]
-        Variable.set(WORLD_POSITION, str(first_day + days))
+        position = first_day + days
+        Variable.set(WORLD_POSITION, str(position))
+        logging.info(
+            "дни %s–%s сыграны; новая позиция — %s", first_day, position - 1, position
+        )
 
     first_day = first_unplayed_day()
     played = _generator(
@@ -175,12 +215,15 @@ def world_live_day():
     Ускорение ×60: модельные сутки укладываются примерно в двадцать четыре
     реальные минуты, и суточная волна разворачивается на глазах. Запускается
     руками; чтобы мир жил так день за днём сам, есть выключатель `world_live`.
+    Следующий день работник берет из `world_position`. Логическая дата прогона
+    на выбор дня не влияет.
     """
 
     @task
     def remember_played(first_day: int) -> None:
         """Позиция ставится по сыгранному дню и только по успеху."""
         Variable.set(WORLD_POSITION, str(first_day + 1))
+        logging.info("сыгран день %s; новая позиция — %s", first_day, first_day + 1)
 
     first_day = first_unplayed_day()
     played = _generator("play_day", ["live", "--day", PLAYED_DAY])
@@ -191,7 +234,14 @@ def world_live_day():
         ["snapshot", "--day", PLAYED_DAY, "--topic", ORDERS_TOPIC],
     )
 
-    first_day >> played >> sent >> _ingest_orders() >> remember_played(first_day)
+    position = remember_played(first_day)
+    etl = TriggerDagRunOperator(
+        task_id="trigger_etl_pipeline",
+        trigger_dag_id="etl_pipeline",
+        wait_for_completion=True,
+        poke_interval=10,
+    )
+    first_day >> played >> sent >> _ingest_orders() >> position >> etl
 
 
 @dag(

dags/world_lifecycle.py

@@ -0,0 +1,377 @@
+"""Создание и пересоздание прикладного мира.
+
+Compose поднимает службы, а этот граф создаёт всё прикладное поверх них:
+топики, схему ClickHouse, данные стартовых дней, позицию модельного времени и
+готовые слои. `world_initialize` безопасен для обычного `make up`;
+`world_recreate` — явная операция обслуживания, которая сначала объявляет
+прежний мир недействительным.
+
+Контракт состояний и доводы — ADR 0013 и спека жизненного цикла мира.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import logging
+import os
+import time
+from pathlib import Path
+
+from airflow.exceptions import AirflowException
+from airflow.providers.clickhousedb.hooks.clickhouse import ClickHouseHook
+from airflow.providers.common.sql.operators.sql import SQLExecuteQueryOperator
+from airflow.providers.docker.hooks.docker import DockerHook
+from airflow.providers.docker.operators.docker import DockerOperator
+from airflow.providers.standard.operators.trigger_dagrun import TriggerDagRunOperator
+from airflow.sdk import Variable, chain, dag, task
+
+START_DATE = datetime.datetime(2026, 1, 1, tzinfo=datetime.UTC)
+TAGS = ["жизненный цикл мира"]
+
+WORLD_POSITION = "world_position"
+STARTING_DAYS = int(os.environ["WORLD_STARTING_DAYS"])
+HITS_TOPIC = os.environ["KAFKA_TOPIC"]
+ORDERS_TOPIC = os.environ["KAFKA_ORDERS_TOPIC"]
+KAFKA_BOOTSTRAP_SERVERS = os.environ["KAFKA_BOOTSTRAP_SERVERS"]
+GENERATOR_IMAGE = os.environ["GENERATOR_IMAGE"]
+STAND_NETWORK = os.environ["STAND_NETWORK"]
+
+SQL_ROOT = Path("/opt/airflow/sql")
+DDL_ROOT = SQL_ROOT / "ddl"
+WORLD_ROOT = Path("/opt/airflow/world")
+INVENTORY = WORLD_ROOT / "data/world-inventory.json"
+CLICKHOUSE_CONNECTION = "clickhouse_lifecycle"
+CLICKHOUSE_CLUSTER = "clickstream_cluster"
+APPLICATION_DATABASES = ("stg", "dm", "dds", "ods", "dic")
+CONSUMER_GROUPS = ("clickstream_hits", "clickstream_orders")
+TOPICS = {HITS_TOPIC: 2, ORDERS_TOPIC: 1}
+
+
+def _clickhouse_hook() -> ClickHouseHook:
+    """Подключить владельца жизненного цикла."""
+    return ClickHouseHook(clickhouse_conn_id=CLICKHOUSE_CONNECTION)
+
+
+def _generator(task_id: str, command: list[str]) -> DockerOperator:
+    """Запустить канонический образ генератора в сети стенда."""
+    return DockerOperator(
+        task_id=task_id,
+        image=GENERATOR_IMAGE,
+        command=command,
+        network_mode=STAND_NETWORK,
+        environment={
+            "KAFKA_BOOTSTRAP_SERVERS": KAFKA_BOOTSTRAP_SERVERS,
+            "KAFKA_TOPIC": HITS_TOPIC,
+        },
+        # Вывод уже переехал в журнал задачи; завершённый контейнер не нужен.
+        auto_remove="force",
+        # Временный путь Airflow существует внутри контейнера, но монтировать
+        # его пытается хостовый Docker. Генератору этот каталог не нужен.
+        mount_tmp_dir=False,
+    )
+
+
+def _kafka_error_code(error: Exception) -> int:
+    """Код ошибки из KafkaException."""
+    return error.args[0].code()
+
+
+@dag(
+    dag_id="world_initialize",
+    schedule=None,
+    start_date=START_DATE,
+    is_paused_upon_creation=False,
+    max_active_runs=1,
+    template_searchpath=str(SQL_ROOT),
+    tags=TAGS,
+)
+def world_initialize():
+    """Создать стартовый мир, если готового мира ещё нет."""
+
+    @task.branch
+    def choose_path() -> str:
+        raw_position = Variable.get(WORLD_POSITION, default=None)
+        if raw_position is None:
+            logging.info("world_position отсутствует: создаём первый мир")
+            return "create_topics"
+        try:
+            position = int(raw_position)
+        except (TypeError, ValueError) as error:
+            raise AirflowException(
+                f"world_position={raw_position!r} не является номером дня; "
+                "выполните make rebuild-storage"
+            ) from error
+        if position == 0:
+            logging.info("очистка завершена: создаём мир заново")
+            return "create_topics"
+        if position == -1:
+            raise AirflowException(
+                "world_position=-1: очистка мира не завершена; "
+                "повторите make rebuild-storage"
+            )
+        if position >= STARTING_DAYS:
+            logging.info("мир уже существует: world_position=%s", position)
+            return "world_already_exists"
+        raise AirflowException(
+            f"world_position={position}: недопустимое незавершённое состояние; "
+            "выполните make rebuild-storage"
+        )
+
+    @task
+    def world_already_exists() -> None:
+        """Читаемый зелёный конец ветки без изменений."""
+        logging.info("инициализация не требуется: готовый мир не изменён")
+
+    @task
+    def create_topics() -> None:
+        """Создать топики до появления читающих их таблиц ClickHouse."""
+        from confluent_kafka import KafkaError, KafkaException
+        from confluent_kafka.admin import AdminClient, NewTopic
+
+        admin = AdminClient({"bootstrap.servers": KAFKA_BOOTSTRAP_SERVERS})
+        futures = admin.create_topics(
+            [
+                NewTopic(name, num_partitions=partitions, replication_factor=1)
+                for name, partitions in TOPICS.items()
+            ],
+            request_timeout=30,
+            operation_timeout=15,
+        )
+        for name, future in futures.items():
+            try:
+                future.result()
+                logging.info("топик %s создан", name)
+            except KafkaException as error:
+                if _kafka_error_code(error) != KafkaError.TOPIC_ALREADY_EXISTS:
+                    raise
+                logging.info("топик %s уже существует", name)
+
+        metadata = admin.list_topics(timeout=15)
+        for name, expected_partitions in TOPICS.items():
+            topic = metadata.topics.get(name)
+            actual_partitions = (
+                len(topic.partitions) if topic and not topic.error else 0
+            )
+            if actual_partitions != expected_partitions:
+                raise AirflowException(
+                    f"у топика {name} разделов {actual_partitions}, "
+                    f"ожидалось {expected_partitions}; "
+                    "выполните make rebuild-storage"
+                )
+
+    @task
+    def build_generator_image() -> None:
+        """Собрать генератор из текущего дерева, а не из старого образа."""
+        client = DockerHook(
+            docker_conn_id=None,
+            base_url="unix://var/run/docker.sock",
+            timeout=900,
+        ).get_conn()
+        output = client.build(
+            path=str(WORLD_ROOT),
+            dockerfile="generator/Dockerfile",
+            tag=GENERATOR_IMAGE,
+            rm=True,
+            decode=True,
+        )
+        for item in output:
+            if error := item.get("error"):
+                raise AirflowException(
+                    f"сборка генератора завершилась ошибкой: {error}"
+                )
+            if stream := item.get("stream", "").strip():
+                logging.info("docker build: %s", stream)
+
+    @task
+    def wait_for_events() -> None:
+        """Дождаться приёма всех событий описи, включая строки брака."""
+        inventory = json.loads(INVENTORY.read_text(encoding="utf-8"))
+        expected = sum(day["events"] for day in inventory["days"])
+        first_date = inventory["days"][0]["date"]
+        last_date = inventory["days"][-1]["date"]
+        query = f"""
+            SELECT
+                (SELECT count() FROM ods.event_dist
+                    WHERE EventDate BETWEEN '{first_date}' AND '{last_date}')
+              + (SELECT count() FROM ods.event_errors_dist)
+        """
+
+        hook = _clickhouse_hook()
+        arrived = 0
+        for attempt in range(1, 101):
+            row = hook.get_first(query)
+            if row is None:
+                raise AirflowException("ClickHouse не вернул счётчик приёма")
+            arrived = int(row[0])
+            if arrived >= expected:
+                logging.info("стартовый мир принят: строк %s", arrived)
+                return
+            if attempt % 5 == 0:
+                logging.info("принято %s из %s строк", arrived, expected)
+            time.sleep(3)
+        raise AirflowException(
+            f"стартовый мир не принят за 300 с: строк {arrived} из {expected}; "
+            "проверьте журнал send_initial_events и "
+            "SELECT * FROM system.kafka_consumers"
+        )
+
+    @task
+    def remember_starting_position() -> None:
+        """Объявить мир готовым только после приёма обоих источников."""
+        Variable.set(WORLD_POSITION, str(STARTING_DAYS))
+        logging.info("мир готов: world_position=%s", STARTING_DAYS)
+
+    route = choose_path()
+    ready = world_already_exists()
+    topics = create_topics()
+    ddl_files = sorted(DDL_ROOT.glob("*.sql"))
+    if not ddl_files:
+        raise AirflowException(f"в {DDL_ROOT} нет файлов DDL")
+    ddl_tasks = [
+        SQLExecuteQueryOperator(
+            task_id=f"apply_{path.stem.replace('-', '_')}",
+            conn_id=CLICKHOUSE_CONNECTION,
+            sql=f"ddl/{path.name}",
+            split_statements=True,
+            do_xcom_push=False,
+        )
+        for path in ddl_files
+    ]
+    image = build_generator_image()
+    events = _generator(
+        "send_initial_events",
+        ["batch", "--day", "0", "--days", str(STARTING_DAYS)],
+    )
+    arrived = wait_for_events()
+    snapshots = _generator(
+        "send_initial_snapshots",
+        [
+            "snapshot",
+            "--day",
+            "0",
+            "--days",
+            str(STARTING_DAYS),
+            "--topic",
+            ORDERS_TOPIC,
+        ],
+    )
+    orders = TriggerDagRunOperator(
+        task_id="trigger_orders_ingest",
+        trigger_dag_id="orders_ingest",
+        wait_for_completion=True,
+        poke_interval=10,
+    )
+    position = remember_starting_position()
+    etl = TriggerDagRunOperator(
+        task_id="trigger_etl_pipeline",
+        trigger_dag_id="etl_pipeline",
+        wait_for_completion=True,
+        poke_interval=10,
+    )
+
+    route >> [ready, topics]
+    chain(topics, *ddl_tasks, image, events, arrived, snapshots, orders, position, etl)
+
+
+@dag(
+    dag_id="world_recreate",
+    schedule=None,
+    start_date=START_DATE,
+    is_paused_upon_creation=False,
+    max_active_runs=1,
+    tags=TAGS,
+)
+def world_recreate():
+    """Удалить только прикладной мир и делегировать его создание."""
+
+    @task
+    def invalidate_world() -> None:
+        Variable.set(WORLD_POSITION, "-1")
+        logging.info("прежний мир недействителен: world_position=-1")
+
+    @task
+    def drop_application_databases() -> None:
+        hook = _clickhouse_hook()
+        for database in APPLICATION_DATABASES:
+            logging.info("удаляем базу %s", database)
+            hook.run(
+                f"DROP DATABASE IF EXISTS {database} "
+                f"ON CLUSTER {CLICKHOUSE_CLUSTER} SYNC"
+            )
+
+    @task
+    def delete_consumer_groups() -> None:
+        from confluent_kafka import KafkaError, KafkaException
+        from confluent_kafka.admin import AdminClient
+
+        admin = AdminClient({"bootstrap.servers": KAFKA_BOOTSTRAP_SERVERS})
+        remaining = set(CONSUMER_GROUPS)
+        for attempt in range(1, 31):
+            futures = admin.delete_consumer_groups(
+                sorted(remaining), request_timeout=15
+            )
+            for group, future in futures.items():
+                try:
+                    future.result()
+                    remaining.discard(group)
+                    logging.info("группа %s удалена", group)
+                except KafkaException as error:
+                    code = _kafka_error_code(error)
+                    if code == KafkaError.GROUP_ID_NOT_FOUND:
+                        remaining.discard(group)
+                    elif code != KafkaError.NON_EMPTY_GROUP:
+                        raise
+            if not remaining:
+                return
+            if attempt % 5 == 0:
+                logging.info("ждём выхода потребителей из групп: %s", sorted(remaining))
+            time.sleep(2)
+        raise AirflowException(
+            f"за 60 с не освободились группы потребителей: {sorted(remaining)}"
+        )
+
+    @task
+    def delete_topics() -> None:
+        from confluent_kafka import KafkaError, KafkaException
+        from confluent_kafka.admin import AdminClient
+
+        admin = AdminClient({"bootstrap.servers": KAFKA_BOOTSTRAP_SERVERS})
+        futures = admin.delete_topics(list(TOPICS), request_timeout=30)
+        for name, future in futures.items():
+            try:
+                future.result()
+                logging.info("топик %s удалён", name)
+            except KafkaException as error:
+                if _kafka_error_code(error) != KafkaError.UNKNOWN_TOPIC_OR_PART:
+                    raise
+
+        for _ in range(30):
+            existing = set(admin.list_topics(timeout=10).topics) & set(TOPICS)
+            if not existing:
+                return
+            time.sleep(1)
+        raise AirflowException(f"топики не исчезли за 30 с: {sorted(existing)}")
+
+    @task
+    def mark_world_clean() -> None:
+        Variable.set(WORLD_POSITION, "0")
+        logging.info("очистка завершена: world_position=0")
+
+    invalid = invalidate_world()
+    databases = drop_application_databases()
+    groups = delete_consumer_groups()
+    topics = delete_topics()
+    clean = mark_world_clean()
+    initialize = TriggerDagRunOperator(
+        task_id="trigger_world_initialize",
+        trigger_dag_id="world_initialize",
+        wait_for_completion=True,
+        poke_interval=10,
+    )
+
+    invalid >> databases >> groups >> topics >> clean >> initialize
+
+
+world_initialize()
+world_recreate()

data/world-inventory.json

@@ -6,87 +6,94 @@
     {
       "day": 0,
       "date": "2026-06-01",
-      "events": 50626,
+      "events": 50628,
-      "sha256": "81ad7f402bdd4c8b56425f6439a024b9996e5ca95dd207d444290d20a70ed407"
+      "sha256": "d09704ed99e45824e451e2f6bbbbd5c547df382f7a582699955010f3807eb0ee",
+      "orders": {
+        "match": 192,
+        "cancelled": 20,
+        "lost_event": 3,
+        "duplicate_event": 2,
+        "amount_delta": 6
+      }
     },
     {
       "day": 1,
       "date": "2026-06-02",
-      "events": 49722,
+      "events": 49727,
-      "sha256": "5f7aa0301832008db612eff05899b1210af958c888ac2e9e89f4b7a552569eff"
+      "sha256": "8005d2934eb353478e35331d7ae7ae6876c7934b2d9032fde92cf6ce86d6460f"
     },
     {
       "day": 2,
       "date": "2026-06-03",
-      "events": 52361,
+      "events": 52363,
-      "sha256": "10ac9ce65ca6dc171689edf78ef5cd785e8c8a80e54d236bf2b9d6dbf6997070"
+      "sha256": "e13f6f3f3977386a94d0e63b6849675cb5d2486a277d559fd415923cfc82e53a"
     },
     {
       "day": 3,
       "date": "2026-06-04",
-      "events": 53157,
+      "events": 53159,
-      "sha256": "7bf4deadd8f69a6c479fceabfe2d1e8ea8db76919b10a8b9e780006708da31c3"
+      "sha256": "91c713add62222adc3f89c04e6cc087d8c44e2385d14d0464e2c016b6952b9fd"
     },
     {
       "day": 4,
       "date": "2026-06-05",
-      "events": 50078,
+      "events": 50087,
-      "sha256": "b9e758fb72f937aa5ad1f2e90dee5ec147b16cfd89e49e51a00582f909458c29"
+      "sha256": "b7fc27d73fc157a48bece0189c7983f6bc672f052e0703cd799b9774da4b904e"
     },
     {
       "day": 5,
       "date": "2026-06-06",
-      "events": 47164,
+      "events": 47169,
-      "sha256": "f08a9f9a439f1da9e4ad8d94b9f65b7f3329256e41446d22d900cc4825f2480c"
+      "sha256": "82cb8017d53d6dee8438d3683b7a901f1ace139f3b8ae836215722bb580fe207"
     },
     {
       "day": 6,
       "date": "2026-06-07",
-      "events": 48683,
+      "events": 48686,
-      "sha256": "7e45d9dd59c902067fa6847d813669b1ab9a4ee88d2f192382577a5ed8d590a7"
+      "sha256": "b50ad0fcc7d1ea0c637cfcba98e5c2b55d65215cffa3693bc77edeaa83e6c783"
     },
     {
       "day": 7,
       "date": "2026-06-08",
       "events": 49394,
-      "sha256": "286ccc2451847ac8de215b5e902c328371021ad5502bd4afca0494b6f313aef7"
+      "sha256": "358d51b36221d822960237702fa6327fb663a57cf49cc4415a859b16e5aa05a2"
     }
   ],
   "snapshots": [
     {
       "day": 0,
       "date": "2026-06-01",
-      "sha256": "6c3e3c1c8689ec23f53f0953db1b941e6f010e9e56a74d8d017f40195d3dec17"
+      "sha256": "93b39f261cbbe894402ebe0525460fed1809e5712639be4b73b79dac2b39f5bd"
     },
     {
       "day": 1,
       "date": "2026-06-02",
-      "sha256": "9acb523cfd47f3d97d55122025852982ba5a1d8362036308ce72a4d9fb767f43"
+      "sha256": "4fef382cd84868ccfb61a9d8610cdd26f9a749bbae8b20800c45e520e9ce414e"
     },
     {
       "day": 2,
       "date": "2026-06-03",
-      "sha256": "b81482491c4c0b874ea84d5f3f05144100c906dacc059c068b331df258b97172"
+      "sha256": "caf9ed2e77d2fcc99066a548dcba60f61f1ff0d4402de31457a06f23fd2d8306"
     },
     {
       "day": 3,
       "date": "2026-06-04",
-      "sha256": "9d1ab326c4bf8b78c9fcaf7015d8029f9ad4cff5558b89c730eb428d175cc9ee"
+      "sha256": "cdb9e4e00b57c04985866b5a851a8e2f23b3e9205ea131c7a5076672ee8b5669"
     },
     {
       "day": 4,
       "date": "2026-06-05",
-      "sha256": "0e30d0e192e121121003c0cc9aaa55e24924afb983caff15ab105705fbf2bd00"
+      "sha256": "c58d2c20fe3b4cee2973f34c322090dbb66d3793bfaab0337c22b53fb5a3ec7f"
     },
     {
       "day": 5,
       "date": "2026-06-06",
-      "sha256": "9a2ad812fcff9a40a988f24f8aa4fc7a379873d173a95ddacd438592aed0bfb5"
+      "sha256": "bbf28b1d375e4815695c72a5915a22a3c9b36195b97ec4cc7c739466dbe70b53"
     },
     {
       "day": 6,
       "date": "2026-06-07",
-      "sha256": "e1706a27ff55de489a505489148c7a959329d95ad6597d92d3f78505f67bb221"
+      "sha256": "8ca077576bcf014c0d492c7d7190e38c0e46ec95951ad840df93eb75ee5a00d3"
     }
   ]
 }

docs/adr/0001-stand-services.md

@@ -10,6 +10,19 @@
 обработчик DAG. Triggerer не запускается: в каркасе нет отложенных задач.
 Два интеграционных пробника написаны через публичный `airflow.sdk`.
 
+Долгоживущие процессы Airflow зависят от `airflow-init`, а Superset — от
+`superset-init`. Это ребро нужно самому `up --wait`: Docker Compose 2.40.3
+считает успешно завершившийся одноразовый сервис без зависимого упавшим и
+возвращает единицу — поведение проверено при исполнении #37. Зависимость
+включает результат подготовки в общий граф ожидания.
+
+У каждого общего локального образа один блок `build`. Он находится у службы
+инициализации. Остальные службы зависят от неё и используют тот же `image`.
+`docker compose up --build` завершает сборку до запуска контейнеров, поэтому
+одного блока достаточно. В Buildx 0.30.1 одинаковые блоки у нескольких служб
+запускают параллельный экспорт одного тега. Иногда сборка завершается ошибкой
+`image already exists`.
+
 Для входа выбран SimpleAuthManager. У него нет команды создания пользователя,
 поэтому `airflow-init` записывает пароль администратора из окружения в
 JSON-файл отдельного тома `airflow_auth`. Новый именованный том принадлежит
@@ -24,13 +37,20 @@ JSON-файл отдельного тома `airflow_auth`. Новый имен
 пользователи и строки подключения. Это экономит один контейнер, но сохраняет
 границу владения данными.
 
-Airflow получает подготовленное общее подключение к `clickhouse-01`, а
+Airflow получает два подготовленных подключения к `clickhouse-01`: рабочее
-Superset — подключение `clickhousedb://` к `clickhouse-02`. Провайдер
+`clickhouse_default` и административное `clickhouse_lifecycle` для дагов
-ClickHouse для Airflow не нужен: локальный образ содержит прямой клиент.
+жизненного цикла мира ([ADR 0013](0013-world-lifecycle.md)). Оба имеют тип
-Пробник создаёт служебные таблицы `ON CLUSTER`, пишет на первой ноде и через
+`clickhouse`, который регистрирует официальный провайдер
-`remote` читает `Distributed` на второй. Разные ноды сохраняют учебную
+`apache-airflow-providers-clickhousedb`. SQL-файлы исполняет общий
-ловушку: забытый `ON CLUSTER` проявится в Superset, даже если операция Airflow
+`SQLExecuteQueryOperator`, а программные запросы идут через `ClickHouseHook`.
-на первой ноде прошла успешно.
+Сам провайдер работает через `clickhouse-connect`; его версия закреплена
+отдельно, чтобы сборка не меняла транспорт незаметно.
+
+Superset получает подключение `clickhousedb://` к `clickhouse-02`. Пробник
+Airflow создаёт служебные таблицы `ON CLUSTER`, пишет на первой ноде и через
+`remote` читает `Distributed` на второй. Разные ноды сохраняют учебную ловушку:
+забытый `ON CLUSTER` проявится в Superset, даже если операция Airflow на первой
+ноде прошла успешно.
 
 Клиент Kafka также добавлен прямо в образ Airflow. Официальный провайдер
 использует тот же `confluent-kafka`, а пробнику не нужны его подключение,
@@ -76,10 +96,18 @@ Prometheus читает встроенные точки метрик двух с
 Оттуда взяты `airflow.sdk`, обязательный отдельный обработчик DAG, возможность
 не запускать triggerer и проверка конкретных компонентов здоровья.
 
-Для интеграционных пробников проверены `Connection.get` в публичном
+Для ClickHouse через Context7 и официальную документацию Airflow проверены
-`airflow.sdk`, запросы через `clickhouse-connect` и состав официального
+`ClickHouseHook`, тип подключения `clickhouse` и работа
-провайдера Kafka. Выбран прямой `confluent-kafka`: провайдер строит свои
+`SQLExecuteQueryOperator` с SQL-файлом, параметрами и несколькими выражениями.
-подключения и обёртки поверх него, которые двум коротким пробникам не нужны.
+Закреплён `apache-airflow-providers-clickhousedb==1.0.0`: на 21 августа
+2026 года это последний стабильный выпуск; `1.0.1` опубликован только как
+предварительная версия. Зависимость провайдера допускает любой
+`clickhouse-connect>=1.3.0`, поэтому прежний `clickhouse-connect==1.6.0`
+оставлен прямой зависимостью образа.
+
+Для Kafka проверен состав официального провайдера. Выбран прямой
+`confluent-kafka`: провайдер строит свои подключения и обёртки поверх него,
+которые двум коротким пробникам не нужны.
 
 Драйверы и строки подключения проверены по документации Superset 6.1.0:
 [подключения к базам](https://superset.apache.org/user-docs/6.1.0/databases/),

docs/adr/0002-monitoring-scope.md

@@ -120,4 +120,24 @@ ClickHouse, Kafka и Airflow, 17 — в дашборде генератора, 1
 модельные сутки значит записать ускорение мира в JSON дашборда — ровно ту
 пометку, от которой этот же ADR отговаривает выше, — а реальные сутки на стенде
 не с чем сравнивать. Довод целиком и остальное устройство дашборда —
-[docs/architecture/monitoring.md](../architecture/monitoring.md).
+[docs/architecture/monitoring/data.md](../architecture/monitoring/data.md).
+
+Тогда же собраны «Кластер» и «Запросы». Довод про `clusterAllReplicas`
+подтвердился с одной поправкой: очередь распределённых DDL лежит не у ноды, а в
+keeper, и обе ноды читают её целиком — запрос вернул с каждой одни и те же 124
+записи. Обёртка там не добавила бы правды, а удвоила бы каждую строку, поэтому
+единственная панель «Кластера» без неё — эта. Keeper своих системных таблиц не
+имеет вовсе, и панель по нему приходит из Prometheus.
+
+«Запросы» получили на две панели больше, чем сказано выше. Разбор запросов по
+посетителям продиктован [ADR 0007](0007-clickhouse-access.md): своя учётка
+Grafana заведена там ровно затем, чтобы её запросы были отличимы от
+человеческих.
+Отдельная панель ошибок понадобилась потому, что отказ достаётся шарду: в
+замере с принудительным пределом памяти каждая нода записала свой, и строка
+шарда видна только без фильтра по инициатору. Здешний сюжет про тяжёлый
+`GROUP BY` при этом кончается не отказом, а сбросом на диск
+([ADR 0004](0004-resource-limits.md)) — отказ на стенде приходится вызывать
+настройкой. Устройство обоих дашбордов —
+[cluster.md](../architecture/monitoring/cluster.md) и
+[queries.md](../architecture/monitoring/queries.md).

docs/adr/0004-resource-limits.md

@@ -19,16 +19,23 @@
 
 Нодам ClickHouse — по 4 ГиБ вместо гигабайта. Дальше в этом тексте предел
 памяти контейнера (`mem_limit`) называется коробкой: сервер живёт внутри неё и
-о самой машине ничего не знает. Остальные `mem_limit` не меняются.
+о самой машине ничего не знает. На 1 августа остальные `mem_limit` не менялись.
 
 Числа, выставленные ради прежнего бюджета, остаются в силе, но лишаются
 статуса решения: `KAFKA_HEAP_OPTS`, `shared_buffers`, `max_connections`,
-`AIRFLOW__CORE__PARALLELISM` и девять неизменённых `mem_limit`. Основания,
+`AIRFLOW__CORE__PARALLELISM` и восемь оставшихся `mem_limit`. Основания,
 кроме отменённого, у них нет. Кто в них упрётся — меняет по первому
 свидетельству и этот ADR не пересматривает. Срок хранения метрик Prometheus
 сюда не входит: неделя истории — осознанный учебный выбор, и цена у него
 дисковая.
 
+27 августа таким пределом впервые стала коробка `airflow-scheduler`:
+LocalExecutor исполняет в ней до четырех процессов задач одновременно, а
+640 МиБ этого не вместили. Коробка поднята до 1,5 ГиБ. Ресурсные ограничения
+из отдельных дагов удалены. Общий предел параллелизма уже задает Airflow.
+`max_active_runs=1` остается там, где два запуска делили бы один донор и могли
+повредить публикацию.
+
 Ресурсный довод ADR 0001 отозван.
 
 ## Почему
@@ -94,8 +101,8 @@ ClickHouse сам понижает каждый до 512 МиБ, а на сте
 заранее, и в покое стенд занимает около 3,2 ГБ. Восемь гигабайт нужны не сумме
 пределов, а работе с запасом.
 
-Остальные девять лимитов не меняются, потому что ни один из них ни разу не
+На 1 августа остальные девять лимитов не менялись, потому что ни один из них
-сработал. Снять их скопом — то же изменение без свидетельств, каким они были
+не сработал. Снять их скопом — то же изменение без свидетельств, каким они были
 выставлены, только в обратную сторону. Лечение здесь не в том, чтобы стереть
 числа, а в том, чтобы лишить их статуса закона: число без основания меняют,
 когда оно мешает, и не защищают как принятое решение.
@@ -151,3 +158,13 @@ to 2.00 GiB because the system has limited RAM` и такие же строки
 Значение `max_server_memory_usage_to_ram_ratio` = 0,9 и то, что в cgroup предел
 считается от коробки, а не от машины, сверены по документации ClickHouse через
 MCP Context7.
+
+`airflow-scheduler` проверен отдельно 27 августа 2026 года. На свежем
+контейнере две попытки запустить четыре DQ-сверки параллельно в коробке
+640 МиБ дошли ровно до `memory.max` и дали `oom_kill=1`: сначала при выгрузке
+57 567 ключей сессий в Python, затем и после переноса дневной агрегации в
+ClickHouse. В коробке 1 ГиБ сам `dq_check` прошел, но снова коснулся верхней
+границы (`memory.events.max=57`). Полный `etl_pipeline` без локальных
+ограничений задач в коробке 1,5 ГиБ завершился успешно: пик - 1 013 760 000
+байт, `memory.events.max=0`, `oom_kill=0`. Docker не резервирует разницу между
+пиком и пределом, поэтому этот запас не увеличивает расход памяти в покое.

docs/adr/0007-clickhouse-access.md

@@ -1,18 +1,23 @@
 # ADR 0007. Доступ к ClickHouse: пользователи файлом, доверие нод секретом
 
 Дата: 9 августа 2026 года. Статус: принято; роль `monitoring_reader`
-и пользователь `grafana` добавлены 21 августа 2026 года (#114).
+и пользователь `grafana` добавлены 21 августа 2026 года (#114), права
+`bi_reader` расширены до ODS, DDS и DM 25 августа 2026 года (#150).
 
 ## Решение
 
-У кластера шесть пользователей и пять ролей.
+У кластера семь пользователей и шесть ролей.
 
 - `default` — с паролем, только служебный: проверки здоровья нод и работа
   изнутри контейнеров. Приложения им не ходят.
-- `etl` с ролью `etl_writer` — чтение и запись во всех слоях. Им ходит
+- `etl` с ролью `etl_writer` — чтение и запись во всех слоях. Им ходят рабочие
-  Airflow и применяется DDL при подъёме стенда.
+  даги Airflow.
-- `bi` с ролью `bi_reader` — чтение витрин DM, слоя DDS и справочников `dic`.
+- `lifecycle` с ролью `lifecycle_owner` — создание и удаление только
-  Им ходит Superset.
+  прикладных баз и объектов. Им даги жизненного цикла применяют DDL и
+  пересоздают мир ([ADR 0013](0013-world-lifecycle.md)).
+- `bi` с ролью `bi_reader` — чтение слоёв ODS, DDS и DM, а также справочников
+  `dic`. Им ходит Superset; его запросы обращаются к публичным `_v`, хотя права
+  шире.
 - `analyst` с ролью `analyst_reader` — чтение всех слоёв и справочников. Им
   человек подключается снаружи, из своего клиента.
 - `grafana` с ролью `monitoring_reader` — чтение слоёв, таблиц базы `dic` и
@@ -38,24 +43,28 @@
 Сетевых ограничений на `default` нет: порты стенда и так открыты только на
 `127.0.0.1`, а внутри сети Compose дверь заперта паролем.
 
-Устройство модели — кто каким пользователем ходит и где живут пароли —
+Раздел README «Состав и доступ» описывает, кто каким пользователем ходит и где
-опишет раздел README «Состав и доступ»; здесь только решение и доводы.
+живут пароли; здесь остаются решение и доводы. Отдельного справочника по
-Отдельного справочника по доступу в `docs/architecture/` не заводим: своего
+доступу в `docs/architecture/` нет: точные права видны в `access.xml`, конвенция
-содержания сверх этих двух документов у него сегодня нет, а дом ему
+чтения через `_v` описана в доке хранилища.
-понадобится, когда появятся слои DDS и DM и гранты размножатся. Абзац README
-«У локального учебного кластера нет пароля» этим решением отменяется.
 
 ## Почему
 
 Стенд учит не администрированию доступа, а чтению отказа в правах: человек
 должен узнать в бою картину, которую видел здесь, и понимать, чего просить.
 Отсюда критерий отбора — модель должна читаться из текста ошибки, а не из
-описания. Поэтому пользователей мало, имена у них говорящие, а границы
+описания. Поэтому пользователей мало, имена у них говорящие. В бою BI обычно
-проходят там, где их обычно проводят в компаниях: `bi` видит витрины и слой
+читает витрины и модельный слой. ODS ему могут открыть для расследования или
-DDS под ними, потому что так чаще всего и бывает; заодно расхождение витрины
+сверки. Стенд оставляет этот доступ постоянным, но сохраняет две крупные
-со слоем ниже остаётся проверяемым одним и тем же пользователем. Справочники
+границы: `bi` отделён от STG и от записи. Один пользователь может сверить всю
-видны всем читателям и никому на запись: зона входит в хранилище сбоку, и её
+цепочку DM → DDS → ODS, не получая доступа к сырью и изменению данных.
-содержимым владеет файл репозитория, а не слой.
+Справочники видны всем читателям и никому на запись: зона входит в хранилище
+сбоку, и её содержимым владеет файл репозитория, а не слой.
+
+Ограничить `bi` одними `_v` поверх `Distributed` можно только отдельным
+маршрутом, учётной записью или копией данных. Эта механика не даёт нового урока.
+Публичное представление остаётся договором чтения; границу прав оно не задаёт
+([исследование](../research/2026-08-25-clickhouse-distributed-view-security.md)).
 
 **Беспарольный `dict`.** Пароль пришлось бы вписать в текст DDL словаря, то
 есть положить секрет в git. Ходить этой учёткой некуда: право у неё одно —
@@ -121,16 +130,15 @@ DDS под ними, потому что так чаще всего и быва
 
 ## Следствия
 
-До появления слоёв DDS и DM читать `bi` почти нечего, и это намеренно.
+Новые таблицы ODS, DDS и DM не требуют отдельного гранта для `bi_reader`.
-Дашборды рисуются поверх модели данных, а не поверх типизированных событий,
+Явный договор `_v` защищает потребителя от устройства хранения и случайных
-поэтому доступ Superset к ODS не планировался и правами не выдаётся.
+новых колонок.
-Единственное, что ему доступно сегодня, — справочники: с ними зона `dic`
-пришла раньше своих потребителей.
 
-Владелец матвью приёма определяется тем, кто применил DDL. Весь DDL стенда
+DDL для матвью приёма выполняется от имени `lifecycle`. Это видно в журнале
-идёт через `IF NOT EXISTS`, поэтому на существующих томах три матвью
+запросов, а при создании ClickHouse проверяет у этой учётки чтение источника и
-сохранят нынешнего владельца, а на собранном заново стенде им станет `etl`.
+вставку в цель. Так отдельная учётка показывает границу между редким
-Работают оба — права есть у обоих, — но два стенда в этом расходятся.
+управлением структурой и повседневной записью `etl`, не выдавая рабочим дагам
+право удалять базы.
 
 Лаба «сломать права» вариантом с файлами не закрывается: создать через SQL
 новую роль и нового пользователя ничто не мешает, и новую роль разрешено
@@ -182,11 +190,20 @@ ClickHouse через MCP Context7 (#114).
 - Секрет кластера принимается внутри `remote_servers` в виде
   `<secret from_env="CLICKHOUSE_CLUSTER_SECRET"/>`. Запрос от `etl` через обе
   ноды выполнился на каждой под пользователем `etl`.
-- `from_env` работает у элемента `password`: `etl`, `bi` и `analyst` вошли с
+- `from_env` работает у элемента `password`: `etl`, `lifecycle`, `bi` и
-  паролями из окружения и получили свои роли.
+  `analyst` вошли с паролями из окружения и получили свои роли.
 - При запросе от `bi` через Distributed на второй ноде `system.query_log`
   показал `user = bi` и `initial_user = bi`. Значит, на соседнем шарде
   применяются права инициатора, а не общей учётной записи.
 - Права на отсутствующие базы `dds` и `dm` приняты. До создания баз они видны
   в `SHOW GRANTS FOR etl_writer`; временная таблица в `dm` подтвердила право
   `bi` на чтение после появления базы.
+
+Расширение `bi_reader` проверено на живом стенде 25 августа 2026 года (#150):
+
+- `SHOW GRANTS FOR bi_reader` содержит `SELECT` на ODS, DDS и DM;
+- `bi` прочитал одинаковое число строк из `ods.event_v` и `dds.event_v`;
+- чтение `stg.hits_raw_rep` завершилось ошибкой `ACCESS_DENIED`;
+- представление над `Distributed` с `SQL SECURITY DEFINER` на удалённой ноде
+  сохранило исходного пользователя `bi`. Причина и отклонённые варианты
+  разобраны в [исследовании](../research/2026-08-25-clickhouse-distributed-view-security.md).

docs/adr/0008-order-ingestion.md

@@ -141,7 +141,10 @@
 
 Этап 3 забирает у этапа 5 первый настоящий даг. Раздел 9 мастер-спеки отдавал
 даги этапу 5 целиком; приём заказов без дага не существует, поэтому порядок
-меняется. `etl_pipeline` остаётся за этапом 5.
+меняется. `etl_pipeline` остаётся за этапом 5. Позднее сдвинулся и он:
+резолюция #134 родила его этапом 4 — [дневным конвейером
+трансформаций](../architecture/etl.md), — а этапу 5 оставила партиционную
+переобработку.
 
 Расхождения с мастер-спекой, внесённые тем же коммитом: раздел 6 (чтец заказов
 живёт на одной ноде и без матвью), раздел 7 (развилка закрыта, у `orders` одна

docs/adr/0009-world-control.md

@@ -30,6 +30,11 @@
 работник берёт из переменной, а не из логической даты прогона: календарь Airflow
 к оси мира отношения не имеет.
 
+Позднее [ADR 0013](0013-world-lifecycle.md) отдал Airflow начальную позицию и
+состояния обслуживания: переменной нет до первого создания мира, `-1` означает
+незавершённую очистку, `0` — чистый мир до генерации, а работники принимают
+только позицию `8` и больше.
+
 Пакетная автоматика — второй выключатель, дёргающий `world_next_day`, —
 **отложена, а не отвергнута**.
 
@@ -130,7 +135,10 @@
 Этапы 3 и 5 зовут генератор тем же приёмом: пакетный забор слепка заказов
 ([ADR 0008](0008-order-ingestion.md)) прирастает к тому же работнику, а
 `etl_pipeline` этапа 5 получает готовую обвязку `DockerOperator` и готовое
-правило позиции.
+правило позиции. Позднее резолюция #134 родила `etl_pipeline` этапом 4 —
+[дневным конвейером трансформаций](../architecture/etl.md) без генераторных
+шагов: обвязка и правило позиции остаются работникам, а живой день дёргает
+конвейер после установки позиции.
 
 Расхождения, внесённые тем же коммитом: раздел 8 спеки генератора (позицию
 двигал «только даг `next_day`»; теперь — всякий, кто сыграл день, значением

docs/adr/0010-order-versions-in-ods.md

@@ -1,7 +1,9 @@
 # ADR 0010. Заказы в ODS: версии сущности вместо подмены слепка
 
 Дата: 16 августа 2026 года. Статус: принято. Частично заменяет
-[ADR 0008](0008-order-ingestion.md).
+[ADR 0008](0008-order-ingestion.md). Колонка версии пересмотрена
+[ADR 0014](0014-order-version-snapshot-date.md): вместо `updated_at` —
+`snapshot_date`.
 
 ## Решение
 

docs/adr/0013-world-lifecycle.md

@@ -0,0 +1,70 @@
+# ADR 0013. Жизненный цикл мира ведёт Airflow
+
+Дата: 21 августа 2026 года. Статус: принято. Реализация — тикет #119.
+
+## Решение
+
+Compose поднимает службы стенда. Airflow владеет прикладным миром: топиками
+Kafka, DDL прикладных баз ClickHouse, стартовыми данными и позицией модельного
+времени. `make` поднимает инфраструктуру и через REST API запускает нужный даг,
+дожидаясь его результата.
+
+Безопасный даг `world_initialize` создаёт мир, если тот ещё не создан. На
+готовом мире он ничего не меняет и успешно сообщает об этом в журнале.
+Разрушительный даг `world_recreate` очищает прикладные базы, топики и позиции
+их потребителей, затем запускает `world_initialize` и ждёт его завершения.
+Канонический DDL применяет отдельная учётная запись Airflow с правами только на
+прикладную структуру стенда.
+
+`world_position` остаётся единственным состоянием пульта:
+
+- переменной нет — стенд ещё не инициализировали;
+- `-1` — прежний мир признан недействительным, очистка не завершена;
+- `0` — мир очищен и готов к начальной генерации;
+- `8` и больше — первый несыгранный день готового мира.
+
+`world_recreate` ставит `-1` до первого удаления и `0` только после успешной
+очистки. `world_initialize` принимает отсутствие позиции или `0`, а значение
+`8` и больше считает готовым миром. После генерации стартовых дней и успешного
+приема обоих источников позиция становится `8`; затем инициализация последним
+шагом ждет дневной конвейер `etl_pipeline`. При отказе преобразований мир
+остается готовым на позиции `8`, а конвейер после исправления запускают рукой.
+Обычные даги движения мира работают только с готовой позицией.
+
+## Почему
+
+Прежняя цепочка делила один процесс между Compose, shell-скриптами и Airflow:
+одноразовые службы создавали стартовые данные, отдельный сценарий ждал их
+приёма, а пересборка сама исправляла внутреннюю переменную пульта. Из-за этой
+границы успешная отправка в Kafka выдавалась за создание мира, повторный
+`make up` смешивался с инициализацией данных, а узкая пересборка сохраняла в
+Kafka сообщения и офсеты прежнего мира.
+
+Airflow уже ведёт последующие дни и приём заказов. Отдав ему начало той же оси,
+получаем один наблюдаемый процесс и одну точку успеха: зеленая ветка создания в
+`world_initialize` подтверждает, что схема создана, стартовый мир принят, его
+следующий день известен, а слои DDS и DM собраны. Короткая ветка готового мира
+по-прежнему подтверждает позицию и ничего не меняет.
+
+## Что это решение уточняет
+
+- В [ADR 0007](0007-clickhouse-access.md) DDL больше не принадлежит `etl`:
+  прикладную структуру ведёт отдельный `lifecycle`.
+- В [ADR 0009](0009-world-control.md) отсутствие `world_position` больше не
+  означает готовый стартовый мир. Начальную позицию ставит
+  `world_initialize`, а работники принимают только `8` и больше.
+- Одноразовые службы Compose и shell-ожидание, описанные прежним устройством
+  хранилища, отменены. Их последовательность стала наблюдаемым графом Airflow.
+
+## Отклонено
+
+- Оставить создание мира в Compose, а позицию исправлять из
+  `make rebuild-storage`: работает технически, но сохраняет двух
+  оркестраторов одного процесса.
+- Один безусловно разрушительный даг для первого и повторного запуска: обычный
+  `make up` мог бы стереть уже прожитые дни.
+- Отдельная переменная состояния мира: она дублировала бы
+  `world_position` и могла разойтись с ней. Значения `-1` и `0` выражают
+  нужные переходы в одном месте.
+- Выдать обычной учётной записи `etl` право удаления баз: рабочий конвейер не
+  должен получать административные права из-за редкой операции восстановления.

docs/adr/0014-order-version-snapshot-date.md

@@ -0,0 +1,96 @@
+# ADR 0014. Версия заказа в ODS: дата слепка
+
+Дата: 26 августа 2026 года. Статус: принято. Пересматривает колонку версии
+из [ADR 0010](0010-order-versions-in-ods.md); остальные решения того ADR в
+силе. Развилка разобрана в #163, реализация — #165.
+
+## Решение
+
+`ods.order` хранит версии заказа в `ReplacingMergeTree(snapshot_date)`: при
+схлопывании выживает строка позднейшего слепка, который нёс заказ. Формула
+решения: у полного слепка версия — сам слепок; истина — то, что источник
+сказал последним.
+
+Ключ сущности, партиция и шардирование не меняются. `updated_at` остаётся
+деловым полем, и деловой ответ слоя от смены версии не зависит: на
+канонических слепках выбор по дате слепка побайтово совпадает с выбором по
+деловой метке, потому что метка монотонна по слепкам, а слепок дня — чистая
+функция зерна и дня (тесты генератора
+`test_the_state_is_read_at_the_boundary_of_the_day` и
+`test_two_runs_give_the_same_snapshot`).
+
+Решение покупает две вещи.
+
+- **Детерминизм слоя.** Разные слепки несут разные даты — ничьей между
+  содержательно разными строками не бывает. При версии `updated_at` доставки
+  неизменившегося заказа равны по версии, и выжившая строка — жребий: у 86
+  заказов стартового мира выживала строка серединного слепка, притом что у
+  всех 3034 пар строк с равным `updated_at` деловые поля совпадали побайтово
+  (замеры #137). Документация ClickHouse обещает при ничьей победу последней
+  вставленной строки — замер это опроверг, полагаться на неё было бы ошибкой.
+- **Правдивый ярлык.** `snapshot_date` выжившей строки — последний слепок,
+  который нёс заказ. Объём пересборки DDS читается прямо из данных, причём
+  без `FINAL`: слияние сохраняет максимум даты по построению. Константа
+  окна K уходит со стороны стенда вместе с риском дрейфа её двух копий
+  (ревью #151 ставило этому риску MAJOR).
+
+## Ответ доводу ADR 0010
+
+ADR 0010 отверг семейство «публикацию решает дата наблюдения»: у потребителя
+нет признака полноты слепка. Довод целил в подмену партиции — ей полнота
+нужна, потому что неполная партиция стёрла бы уже принятые версии. Колонке
+версии полнота не нужна: она сравнивает свежесть строк одного заказа, и
+недоехавшая строка просто оставляет в силе предыдущую — ровно как при версии
+по деловой метке.
+
+## Границы допущения
+
+- **Дисциплина слепков.** Слепок с поздней датой не несёт состояния старше.
+  Источник, собирающий слепок из отставшей реплики, это ломает; модельный
+  мир — нет: см. тесты выше.
+- **Одна дата — один слепок.** Ограничение вшито в движок: вторая
+  внутридневная выгрузка дала бы ничью уже на деловых полях. Это условие
+  контракта источника, его место — в границе строгого приёма
+  ([приём заказов](../architecture/orders/ingestion.md)).
+- **Окно наследует потерю строк.** Частичный отказ вставки после коммита
+  офсетов может унести старший день последнего слепка — выведенное окно
+  молча сузится. Лекарство прежнее, сверка слоя с источником в контуре DQ
+  ([конвейер](../architecture/etl.md), «Чего конвейер о себе не знает»).
+- **Тихая правка лечится только внутри окна.** Строку, изменённую без
+  сдвига `updated_at`, перекроет следующий слепок; замёрзший заказ источник
+  больше не показывает, там лечит лишь сверка полей.
+- **Повторная доставка слепка.** Байты совпадают, жребий остаётся только на
+  `_load_id` и `_load_ts`; ярлык даты детерминирован.
+- **Правка живого мира не подхватится.** DDL исполняется при рождении мира,
+  `ALTER` колонку версии не меняет: решение вступает в силу пересозданием
+  хранилища (`make rebuild-storage`).
+
+## Отклонённые варианты
+
+- **Оставить как есть, сверку копий K отдать DQ.** Лотерея ярлыков остаётся
+  задокументированным грехом, окно — константой с риском дрейфа.
+- **Убрать координаты доставки из ODS.** Наказывает поле за вопрос, на
+  который оно не бралось отвечать: расследованию (связка годных строк,
+  ошибок и сырья) координаты служили честно.
+- **Дедупликация на вставке.** Детерминизм «обычно», не по построению:
+  анти-джойн с собственной целью не атомарен, лаг реплик протаскивает дубли.
+  Приём теряет урок «разобрал и вставил», а ярлык со смыслом «первый
+  носитель» хуже для обеих ролей поля: окну нужен последний носитель, и
+  сырьё живо скорее у него.
+- **Склейка `(updated_at, snapshot_date)` в одну колонку версии.** Движок
+  берёт одну колонку, склейка требует битовой упаковки. Робастнее к
+  недисциплинированному источнику, но платит читаемостью DDL за защиту от
+  сценариев, которых модельный мир не производит.
+- **Склейка `(snapshot_date, updated_at)`.** Путь отступления: если у
+  источника появятся переиздания слепка одной даты, версия дорастает до
+  этой формы. От правок без сдвига метки внутри одной даты не спасает и она.
+
+## Связанные решения
+
+- [ADR 0010](0010-order-versions-in-ods.md) — версии заказа в ODS; здесь
+  пересмотрена только колонка версии.
+- [Приём заказов](../architecture/orders/ingestion.md) — граница строгого
+  приёма и четыре координаты строки.
+- [Модель заказа в DDS](../architecture/dds/order.md) — читатель окна
+  пересборки.
+- Развилка, веер и два холодных ревью — #163.

docs/adr/0015-counter-timezone.md

@@ -0,0 +1,36 @@
+# ADR 0015. Модельный день считается в часовом поясе счетчика
+
+Дата: 28 августа 2026 года. Статус: принято. Реализация — тикет #39.
+
+## Решение
+
+Модельные сутки считаются в часовом поясе счетчика UTC+4. `EventDate` обозначает
+дату в этом поясе, а `UTCEventTime` — абсолютную метку времени. Граница
+модельного дня приходится на полночь счетчика.
+
+Суточная волна посетителя привязана к его местному времени. У гостя из другого
+пояса она сдвигается на разницу с поясом счетчика, но общая граница дня остается
+прежней.
+
+## Почему
+
+Так устроена выгрузка Метрики: дата события уже посчитана в поясе счетчика.
+Полночь в этом поясе не разрезает утренние сессии в регионе мира. Регион можно
+выбирать независимо от технического пояса счетчика.
+
+Для всего потока дня нужна одна граница суток. Местное время гостя описывает
+поведение в пределах этих суток, а отдельная дата для каждого посетителя не
+нужна.
+
+## Отклонено
+
+В разделе 9 отклоненные варианты не зафиксированы.
+
+## Следствия
+
+У ночных событий `toDate(UTCEventTime) != EventDate`. Хранилище берет день из
+готового `EventDate`, а не выводит его из абсолютной метки. Поворот суточной
+волны слегка размывает общий пик активности гостей из разных поясов.
+
+Решение принято при исполнении тикета #39 и зафиксировано в спеке этапа 2,
+раздел 9.

docs/adr/0016-cookie-passport.md

@@ -0,0 +1,28 @@
+# ADR 0016. Паспорт куки хранится в плане состава на всю ее жизнь
+
+Дата: 28 августа 2026 года. Статус: принято. Реализация — тикет #39.
+
+## Решение
+
+Браузер, операционная система, устройство, экран и город принадлежат куке на всю
+ее жизнь. План состава выбирает и хранит паспорт, а день только переносит его в
+поля событий.
+
+Две куки одного человека получают один город и разные устройства. Броски
+паспорта идут после прежних бросков состава, поэтому прежние измерения не
+сдвинулись.
+
+## Почему
+
+Кука представляет браузер на устройстве, поэтому ее паспорт не должен меняться
+между днями. Только план состава связывает две куки с одним человеком. Поэтому
+он может задать им один город и разные устройства.
+
+## Отклонено
+
+- Выводить паспорт арифметикой из `ClientID`: этот идентификатор не несет
+  сведений о двухкуковой паре, поэтому по нему нельзя задать двум кукам одного
+  человека один город и разные устройства.
+
+Решение принято при исполнении тикета #39 и зафиксировано в спеке этапа 2,
+раздел 9.

docs/adr/0017-order-numbering.md

@@ -0,0 +1,34 @@
+# ADR 0017. Номер заказа объединяет две проекции покупки
+
+Дата: 28 августа 2026 года. Статус: принято. Реализация — тикет #40.
+
+## Решение
+
+Номер заказа включает день по модельному времени и порядковый номер покупки в
+этот день, например `20260603-0042`. Событийная сторона пишет его в
+`purchaseID`, бэкенд — в `order_id`; обе стороны берут один номер из плана
+покупки.
+
+Все покупки, попавшие в поток дня, нумеруются в порядке событий и до любых
+потерь следующих этапов.
+
+## Почему
+
+По читаемому номеру сразу виден день заказа. Один номер соединяет две проекции
+одной покупки. Генераторы кликстрима и бэкенда не согласуют его отдельно.
+
+Присвоение до потерь сохраняет номера остальных заказов: исчезновение одного
+события не должно перенумеровывать чужие покупки и разрывать связь с бэкендом.
+
+## Отклонено
+
+- Присваивать номера после внесения потерь: одна потеря сдвинула бы все
+  следующие номера за день и разорвала бы связь уже созданных проекций.
+
+## Следствия
+
+`purchaseID` и `order_id` изначально совпадают. Из-за расхождения событие может
+исчезнуть после присвоения номера, но номера сохранившихся заказов не меняются.
+
+Решение принято при исполнении тикета #40 и зафиксировано в спеке этапа 2,
+раздел 9.

docs/architecture/dds/README.md

@@ -0,0 +1,59 @@
+# Слой DDS: бизнес-модель хранилища
+
+Устройство детального слоя: сущности, которыми хранилище говорит с
+витринами, их связи и правила слоя. Набор собирается развилками карты #127
+(этап 4) и правится по мере постройки.
+
+Рамки заданы мастер-спекой [«Боевой реализм стенда
+(v2)»](../../specs/2026-07-30-stand-v2-realism.md): карта таблиц и витрины —
+раздел 7, сверка — раздел 4, склейка идентичностей — раздел 5. Дом выбран
+развилкой #130 — первой, которой понадобилось записать резолюцию в доки:
+записи этапа 4 живут здесь, по хранилищную сторону границы
+«источник | хранилище». Устройство источников остаётся их
+собственным наборам ([заказы бэкенда](../orders/README.md)) — генератор
+переносим и о нашем DDS не знает.
+
+## Карта модели
+
+Целостность модели — связи и ко-локация — живёт в этом разделе; файлы
+сущностей держат глубину и на карту ссылаются.
+
+- **Заказ** (`dds.order_v`, хранение `dds.order_rep` / `_dist`) — физическая
+  сущность: одна строка — заказ в текущем состоянии, позиции массивами в
+  строке, наполняется заменой партиций — [модель заказа](order.md).
+- **Сессия** (`dds.session_v`, хранение `dds.session_rep` / `_dist`) —
+  расчётная сущность: одна строка — визит,
+  нарезку по правилу визита стенд делает сам, `VisitID` генератора — эталон
+  сверки; наполнение заменой дневной партиции — [модель сессии](session.md).
+- **Событие** (`dds.event_v`) — контракт над ODS, а не копия: представление,
+  переводящее событие на язык бизнес-модели, — [контракт события](event.md).
+- **Карта идентичностей** (`dds.identity_map_v`, хранение
+  `dds.identity_map_rep` / `_dist`) — кука ↔ пользователь магазина —
+  [модель карты](identity.md).
+
+Связи держатся двумя ключами моста (спека, разделы 4 и 5): `purchaseID[1]`
+события равен `order_id` заказа — по нему идут сверка и сборка склейки;
+`user_id` заказа связывает куки одного человека. Ко-локацию задаёт
+шардирование: события и карта идентичностей раскладываются одним выражением
+от куки, заказы — от `order_id`. Поэтому обогащение витрин склейкой
+локально, а сверка и сборка карты ходят через GLOBAL JOIN с обеими
+сторонами-подзапросами ([исследование
+соединений](../../research/2026-08-22-distributed-join.md)).
+
+## Правила слоя
+
+- DDS обслуживает человека с дашбордом: время лежит в поясе счётчика,
+  пересчёт — один раз при наполнении слоя ([дока хранилища](../storage.md),
+  «Часовые пояса»).
+- Публичный договор каждой сущности — `_v`; роли объектов и конвенция чтения
+  заданы [докой хранилища](../storage.md), «Имена объектов».
+- Служебные колонки — координаты собственной загрузки слоя; чужие ярлыки не
+  переносятся, а спрашиваются у их слоя по ключу сущности. Вывод правила и
+  цепочка расследования — [модель заказа](order.md).
+- Наполняет слой [дневной конвейер](../etl.md): запуск, объём прогона и
+  замена партиций на кластере — его устройство.
+
+## Родословная
+
+Дом набора и первая сущность собраны развилкой #130 карты #127; форма
+набора — [ADR 0011](../../adr/0011-component-docs.md).

docs/architecture/dds/event.md

@@ -0,0 +1,140 @@
+# Контракт события в DDS
+
+Учебный результат: менти видит первый на стенде пример правила «слой — это
+контракт, а не обязательно копия данных». Заказ и сессия — физические
+таблицы, а событие в DDS не хранится вовсе: `dds.event_v` — представление,
+которое переводит событие на язык бизнес-модели, не копируя ни строки.
+Витрины DM читают его, а не ODS напрямую.
+
+## Форма
+
+Обычное представление над `ods.event_v` — вторым уровнем, так что `FINAL`
+остаётся спрятанным в один слой, внутри контракта ODS. Единственное
+сомнение против такой формы — «представление материализуется до фильтра» —
+снято исследованием [проталкивания
+условий](../../research/2026-08-22-view-predicate-pushdown.md): условия
+внешних запросов доезжают до партиций и первичного ключа сквозь два уровня
+представлений и переименование колонок.
+
+Две оговорки исследования соблюдены контрактом. Ключевая для срезов колонка
+`event_date` отдаётся переименованием `EventDate`, не пересчётом — иначе
+индекс перестал бы её анализировать. Цена `FINAL` — отключённый
+автоматический `PREWHERE` — свойство ODS, представление её не усугубляет.
+
+Как публичный договор DDS, представление перечисляет колонки явно и следует
+общей [конвенции чтения](../storage.md), «Имена объектов».
+
+## Язык модели
+
+Имена атрибутов — имена модели, а не нормализованные имена источника
+([CONTEXT.md](../../../CONTEXT.md), «Нормализованное имя»). Для большинства
+колонок они совпадают: атрибут переезжает под нормализованным именем из
+[описания выгрузки](../../formats/clickstream-event.md). Расхождения два,
+и каждое — решение модели:
+
+- **`WatchID` → `event_id`**: модель зовёт сущность событием, «watch» —
+  жаргон выгрузки Метрики.
+- **`UTCEventTime` → `event_time` в поясе счётчика** (`Europe/Samara`):
+  DDS обслуживает человека с дашбордом, время лежит местным ([дока
+  хранилища](../storage.md), «Часовые пояса»). Пересчёт — смена линзы, байты
+  те же, проталкиванию не мешает. Второй метки времени контракт не отдаёт:
+  выбор линзы слой сделал за читателя, UTC остаётся языком ODS.
+
+`ClientID` остаётся `client_id`: это устоявшееся имя куки во всей
+экосистеме Метрики, по нему шардирование и мост к `dds.identity_map_v`;
+своё имя здесь создало бы третий синоним. `client_timezone` тоже остаётся —
+это атрибут посетителя, а не линза времени.
+
+`purchase_revenue` сохраняет смысл поля источника. Тип денег нормализуется в
+ODS; точный тип и проверка описаны в разделе
+[«Актуальные события»](../storage.md#актуальные-события). DDS только
+переименовывает уже нормализованную колонку.
+
+## Расшифровки
+
+Одна: `device_category` — коды 1–4 в строки `desktop` / `mobile` /
+`tablet` / `tv`. У настоящей Метрики этот атрибут и есть строка (выгрузка
+стенда несёт число — принятое отступление: спека, раздел 1.1), контракт возвращает
+ему боевой вид.
+
+Значения `device_category` 1–4 получают имена, остальные сохраняются
+десятичной строкой. Новый код остаётся видимым, пока у него не появится имя в
+договоре.
+
+Остальные кодированные атрибуты не расшифровываются. Для `goals_reached`
+справочника целей на стенде нет, id и есть язык. Регионы в расшифровке не
+нуждаются: выгрузка несёт названия рядом с id (`region_city`,
+`region_country`), словарь ничего бы не раскрыл. Идея дать менти собрать
+справочник регионов самому ушла в лабы — issue #143.
+
+## Что скрыто
+
+- **`VisitID`** — чужой суррогат сессии: свою сессию модель чеканит сама
+  (`session_id`, [модель сессии](session.md)), а эталон — инструмент
+  проверки, не атрибут модели. DQ-сверка нарезки идёт за эталоном в
+  `ods.event_v`: она по построению сопоставляет наш слой с чужим чеканом —
+  честно, что за чужим она и идёт в его слой.
+- **`Sign`** — колонка формата без механики: генератор исправлений не шлёт,
+  и в модели события колонке ответить нечего. Честный рассказ о ней живёт в
+  DDL ODS и лекции.
+- **`ecommerce`** — сырой JSON: сырьё, а не атрибут. Разобранные массивы
+  `purchase_*` и `product_*` в контракте есть; лаба про разбор JSON внутри
+  колонки читает ODS.
+- **`_load_ts`** — у представления нет собственной загрузки, а чужие
+  координаты слой не переносит (правило слоя — [модель
+  заказа](order.md), «Служебные колонки»); расследование спрашивает ODS по
+  ключу события.
+
+Остальные колонки отдаются целиком, включая `ip_address` и оба
+`region_*_id`: контракт — не цензор, он прячет только то, чему в модели
+нечего сказать.
+
+## Читатели
+
+- Сборка сессий: ключи нарезки (`client_id`, `event_time`,
+  `event_date`), тип события, страница, UTM, паспорт куки — категория
+  устройства приходит уже расшифрованной.
+- Витрины `dm.events_enriched_v`, `dm.top_pages_daily_v` и
+  `dm.utm_effectiveness_v` (`declared_revenue` берется из `purchase_revenue`).
+- Событийная сторона сверки `dm.purchase_vs_orders_v`: `purchase_id`,
+  `purchase_revenue`, `event_date`.
+- DQ-сверка сессий с эталоном читает не его, а `ods.event_v` —
+  см. «Что скрыто».
+
+## Не входит
+
+- Форма витрин DM — #135.
+- Лаба со справочником регионов — issue #143, проектирование лаб.
+
+## Отклонённые варианты
+
+- **Материализация вместо представления.** Дублировала бы широкий ODS ради
+  переименований, и урок «слой — контракт, а не копия» пропал бы;
+  единственный довод за — сомнение в проталкивании условий — снят
+  исследованием #128.
+- **`utc_event_time` второй меткой рядом с `event_time`.** Контракт вернул
+  бы читателю выбор линзы, который слой обязан делать сам; расхождение двух
+  часов — урок ODS, не DDS.
+- **`visit_id` в контракте.** Сверка и лаба читали бы одну поверхность, но
+  чужой чекан встал бы атрибутом модели — тем же доводом модель сессии не
+  пустила его в свою строку. Решение владельца: DQ-опыт показательнее,
+  когда эталон приходит из другого слоя.
+- **`cookie_id` вместо `client_id`.** Честное имя модели, но третий синоним
+  куки на ровном месте: проза говорит «кука», экосистема — `ClientID`.
+- **Словарь регионов на стенде.** Повторил бы урок `dictGet` каталога
+  вторым разом, а раскрывать нечего — названия уже в строке. Идея «сделать
+  руками» ушла в лабы (issue #143).
+- **Прочие расшифровки** (`goals_reached` в имена целей, `has_gclid` в
+  Bool). Справочника целей нет; косметика без читателя.
+
+## Связанные решения
+
+- [Проталкивание условий сквозь
+  представления](../../research/2026-08-22-view-predicate-pushdown.md) —
+  резолюция #128: форма контракта и обе её оговорки.
+- [Модель сессии](session.md) — `session_id` и довод против чужого чекана;
+  сюда же передан вопрос о судьбе `VisitID`.
+- [Модель заказа](order.md) — правило служебных колонок слоя.
+- Мастер-спека, раздел 7 — два контракта: `ods.event_v` хранит язык
+  источника, `dds.event_v` говорит языком модели.
+- [CONTEXT.md](../../../CONTEXT.md) — «Нормализованное имя», «Хранилище».

docs/architecture/dds/identity.md

@@ -0,0 +1,122 @@
+# Карта идентичностей в DDS
+
+Учебный результат: менти строит физический мост между кукой трекера и
+пользователем магазина, раскладывает его по ключу будущего соединения и видит,
+как пакетный полный пересчёт сочетается с точным публичным представлением.
+
+## Назначение
+
+Карта — адресная книга: «эта кука уже покупала как этот пользователь
+магазина». Связь становится известна только после покупки, потому что в
+кликстриме есть `client_id`, а `user_id` живёт в заказе. Две куки одного
+покупателя дают две строки с одним `user_id`; поэтому витрина может показать
+рядом число посетителей по кукам и число известных людей после склейки.
+
+Это не полная клиентская база. Куки без покупки остаются анонимными, а карта не
+пытается угадать их владельца.
+
+## Зерно и состав строки
+
+Одна строка — известная пара `client_id` × `user_id`. Деловых колонок две:
+
+- `client_id UInt64` — кука трекера;
+- `user_id UInt64` — пользователь магазина.
+
+Собственные служебные колонки `_load_id String` и
+`_load_ts DateTime64(3, 'UTC')` показывают, каким запуском и когда пара записана
+в DDS. Они имеют читателя при расследовании повтора и потому входят в публичный
+договор вместе с деловой парой.
+
+`first_matched_at` нет. Запланированные витрины его не читают, а два возможных
+смысла — «первая покупка вообще» и «момент, с которого связь была известна
+хранилищу» — требуют разных исторических моделей. Этот вопрос оставлен
+[самостоятельной работе](https://git.dementev.space/ddmitry/clickstream-data-platform/issues/145),
+а текущий стенд не выдаёт один смысл за другой.
+
+Статус заказа связь не меняет: любой заказ, сопоставленный с событием покупки,
+показывает владельца куки. Отмена меняет состояние заказа, но не личность
+покупателя.
+
+## Физическая модель и публичный интерфейс
+
+- `dds.identity_map_rep` — локальная
+  `ReplicatedReplacingMergeTree(_load_ts)`, `ORDER BY (client_id, user_id)`,
+  без партиционирования;
+- `dds.identity_map_dist` — распределённая поверхность записи, шардирование
+  по `cityHash64(client_id)`;
+- `dds.identity_map_v` — публичное обычное представление над `_dist`, которое
+  перечисляет четыре колонки явно и применяет `FINAL`.
+
+Повторы полного запуска физически могут лежать рядом до фонового слияния.
+`FINAL` оставляет одну последнюю версию пары, поэтому пользователь всегда читает
+точную карту через `_v`. Роли объектов и доступ следуют общей
+[конвенции](../storage.md), «Имена объектов».
+
+Шардирование совпадает с событиями и сессиями. Благодаря этому витрина может
+обогащать их картой локально по `client_id`; точную форму распределённого
+запроса решает проектирование витрин #135.
+
+## Сборка
+
+Карта собирается один раз в суточной пакетной цепочке после обновления модели
+заказов и до зависимых витрин. При догоняющем запуске за несколько дней хватает
+одной сборки после всей пачки заказов.
+
+Источники — вся доступная история `dds.event_v` и текущее состояние заказов
+`dds.order_v`. Трансформация:
+
+1. оставляет события `purchase` и разворачивает единственный `purchase_id`;
+2. соединяет его с `order_id` заказа через `GLOBAL INNER JOIN`;
+3. выбирает различные пары `client_id`, `user_id`;
+4. добавляет координаты текущего запуска и пишет полный набор в
+   `dds.identity_map_dist`.
+
+`GLOBAL` нужен потому, что события разложены по `client_id`, а заказы — по
+`order_id`: строки соединения не ко-локированы. Правая сторона мала, поэтому
+рассылка заказов приемлема. Материализованное представление здесь не подходит:
+заказ может появиться в пакетном слепке позже уже принятого события покупки.
+
+## Повтор запуска
+
+Каждый запуск заново получает все известные пары из источников. Он не читает
+предыдущую карту и не делает anti-join «вставить только отсутствующее».
+`_load_ts` служит версией `ReplacingMergeTree`, а `dds.identity_map_v` прячет
+физические повторы через `FINAL`.
+
+Полный пересчёт выбран потому, что карта стенда мала, источники уже содержат
+нужную историю, а повтор задачи не зависит от того, на каком месте оборвался
+предыдущий. Мир стенда не отзывает связь куки с пользователем, поэтому удалять
+исчезнувшие пары не требуется.
+
+## Читатели
+
+- `dm.daily_traffic_v` — посетители по `client_id` и известные пользователи по
+  `user_id` рядом;
+- учебные запросы — показать, как несколько кук одного человека меняют
+  `uniq`;
+- расследование пакетного запуска — `_load_id` и `_load_ts` текущей версии
+  пары.
+
+## Отклонённые варианты
+
+- **`first_matched_at` в текущей модели.** Нет запланированного читателя и нет
+  однозначной временной семантики; идея передана в issue #145.
+- **Словарь ClickHouse.** Для малой карты мог бы ускорить точечное обогащение,
+  но спрятал бы физическую модель и не добавил нового урока рядом с уже
+  существующим словарём товаров.
+- **Одно динамическое представление без физической карты.** Повторяло бы
+  соединение всей истории при каждом чтении, не давало ко-локации результата и
+  не показывало устройство реального слоя хранения.
+- **Инкремент через anti-join с самой картой.** Делал бы результат предыдущего
+  запуска обязательным входом и усложнял повтор без пользы на объёме стенда.
+- **Материализованное представление от событий.** Не увидело бы заказ, который
+  приехал позже события покупки.
+
+## Связанные решения
+
+- [Карта DDS](README.md) — связи сущностей и публичная поверхность `_v`.
+- [Модель заказа](order.md) — текущее состояние заказа и пакетное наполнение.
+- [Контракт события](event.md) — поля событий на языке DDS.
+- [Исследование распределённых соединений](../../research/2026-08-22-distributed-join.md)
+  — форма `GLOBAL JOIN` и капкан `INSERT SELECT` между разными ключами
+  шардирования.

docs/architecture/dds/order.md

@@ -0,0 +1,134 @@
+# Модель заказа в DDS
+
+Учебный результат: менти проектирует бизнес-сущность поверх готового ODS —
+выбирает зерно, состав строки и способ наполнения — и видит идемпотентность
+трансформации, устроенную иначе, чем в приёме: заменой партиции, а не
+версиями.
+
+## Зерно
+
+Одна строка — заказ в текущем состоянии, ключ — `order_id`. Модель отвечает
+на вопрос «что сейчас известно о заказе»; историю версий не хранит:
+читателя у истории нет ни в одной витрине, а ODS её и не обещает —
+промежуточные версии съедают фоновые слияния. «Дыхание» выручки внутри окна
+K живёт на текущем состоянии само: пересборка дня меняет статусы заказов, и
+число дня меняется вместе с ними.
+
+## Состав строки
+
+Деловые поля источника переезжают из `ods.order_v` без переименований —
+бэкенд уже говорит в snake_case: `order_id`, `user_id`, `status`, деньги в
+`Decimal` (`items_total`, `discount`, `delivery`, `total`).
+
+Времена `created_at` и `updated_at` пересчитываются при загрузке в пояс
+счётчика: DDS обслуживает человека с дашбордом ([дока
+хранилища](../storage.md), «Часовые пояса»). Там же один раз считается
+**день заказа** — колонка `order_date`, по образцу `EventDate` у события:
+суточные срезы группируются по готовой дате и пояса не упоминают.
+
+Позиции разобраны из сырой строки `items` в три типизированных массива
+одной длины — артикул, количество, цена (`Decimal`). Это родная для
+ClickHouse денормализация: позиция не живёт без заказа и собственного ключа
+не имеет, а разворачивает массивы читатель — `ARRAY JOIN` в витрине
+выручки, с обогащением категорией через `dictGet`
+([мастер-спека](../../specs/2026-07-30-stand-v2-realism.md), раздел 7). Разбор
+JSON происходит один раз, на границе ODS → DDS, куда его и положила спека
+(раздел 2); записывать его параллельными колонками-массивами или `Nested` —
+выбор DDL, не модели.
+
+## Движок и наполнение
+
+`dds.order_rep` — `ReplicatedMergeTree` без колонки версии: партиция —
+`order_date` (день заказа неизменен), ключ сортировки — `order_id`.
+`dds.order_dist` шардирует по `cityHash64(order_id)`, тем же выражением, что
+ODS: это единственный устойчивый ключ сущности.
+
+Идемпотентность держит замена партиции, а не версии. Сбор дня — батч после
+прихода слепка: трансформация собирает партицию заново из `ods.order_v` и
+атомарно подменяет. Поэтому каждая строка физической таблицы — ровно один
+заказ, а чтению не нужен `FINAL`. Пока окно K живо, день «дышит» — статусы
+заказов меняются, и партиция дня пересобирается очередным запуском; на выходе
+из окна день замерзает.
+
+Публичная поверхность — `dds.order_v`: обычное представление с явным списком
+деловых и собственных служебных колонок над `dds.order_dist`, без `FINAL`.
+Роли объектов и доступ следуют общей [конвенции](../storage.md), «Имена
+объектов».
+
+Механика запуска — где собирается партиция и как подменяется на кластере —
+сюда не входит: это устройство [дневного конвейера](../etl.md).
+
+## Служебные колонки
+
+Строка получает `_load_id` и `_load_ts` запуска трансформации, собравшего
+её партицию, — по общей конвенции хранилища. При замене партиции они
+одинаковы у всех строк дня и отвечают на вопрос «каким запуском и когда
+собран этот день».
+
+Ярлыки ODS (`snapshot_date`, `_load_id` приёма, `_load_ts` прибытия) в модель
+не переезжают. Они описывают наблюдение и доставку строки в ODS. Модель DDS
+хранит текущее деловое состояние заказа. В ODS `snapshot_date` задаёт версию и
+называет последний слепок, в котором источник показал заказ
+([ADR 0014](../../adr/0014-order-version-snapshot-date.md)). Дату
+наблюдения и координаты доставки читатель спрашивает у ODS по
+`order_id`. Правило слоя:
+**служебные колонки — координаты собственной загрузки слоя; чужие координаты
+спрашиваются у их слоя по ключу сущности**.
+
+Происшествие качества данных расследуется цепочкой, где каждый шаг
+спрашивает свой слой на его языке: по `_load_id` строки DDS видно, какой
+запуск собрал день; по `order_id` ODS показывает физические версии и брак —
+там свой `_load_id` приёма связывает годные строки, ошибки и сырьё; дальше
+сырьё STG, пока живо. Окно расследования задано сроками хранения: сырьё —
+трое суток, брак — месяц ([дока хранилища](../storage.md)).
+
+## Читатели
+
+- Витрина выручки `dm.revenue_daily_v`: заказы в `paid`, `ARRAY JOIN`
+  позиций, категория через `dictGet` (спека, раздел 7).
+- Сверка `dm.purchase_vs_orders_v`: `order_id`, `order_date`, `items_total`,
+  `status`; соединение — GLOBAL JOIN с обеими сторонами-подзапросами
+  ([исследование соединений](../../research/2026-08-22-distributed-join.md)).
+- Сборка карты идентичностей: пара `order_id` ↔ `user_id`, источник —
+  `dds.order_v`.
+
+## Не входит
+
+- Механика запуска трансформации и замены партиций на кластере —
+  [дневной конвейер](../etl.md).
+- Контур проверок качества (даг DQ, `dm.dq_summary`) — отдельный разговор
+  этапа 4.
+- Инкрементальное наполнение вместо пересборки — техдолг #2.
+
+## Отклонённые варианты
+
+- **Одно динамическое представление вместо физической таблицы.** Рамка стенда —
+  показать модель данных, которую хранилище готовит потребителям; урок
+  «слой — контракт, а не копия» уже закреплён за `dds.event_v`, а разбор
+  позиций и пересчёт времён при каждом чтении собирали бы модель заново на
+  лету. Публичное `dds.order_v` поверх готовой физической модели этому доводу
+  не противоречит: оно ничего заново не вычисляет.
+- **`ReplacingMergeTree` ещё раз.** Повторил бы механику ODS вторым разом:
+  физически хранил бы устаревшие состояния, вернул бы `FINAL`
+  и обёртку-представление — а урок версий менти уже отыграл.
+- **Отдельная сущность `dds.order_item`.** Вторая таблица, второй вопрос
+  шардирования и `JOIN` там, где хватает `ARRAY JOIN`; нормализация из
+  реляционного мира, а не модель под колоночное хранилище. `JOIN` менти
+  увидит в сверке, работу с массивами — только здесь.
+- **Зерно «версия заказа» (история).** Читателя нет; ODS историю не
+  обещает, а мир при нужде переигрывается генератором.
+- **Перенос ярлыков ODS** — см. «Служебные колонки».
+- **Без модели вовсе: витрины читают `ods.order_v` напрямую.** Разбор JSON
+  и пересчёт времён расползлись бы по витринам, а модель данных — то, ради
+  чего сущность и строится, — не была бы показана.
+
+## Связанные решения
+
+- [ADR 0010](../../adr/0010-order-versions-in-ods.md) — версии заказов в
+  ODS, устойчивая поверхность `ods.order_v`.
+- [Приём заказов](../orders/ingestion.md) — граница строгого приёма и
+  четыре координаты строки ODS.
+- [Проталкивание условий сквозь
+  представления](../../research/2026-08-22-view-predicate-pushdown.md) —
+  резолюция #128 той же карты: цена `FINAL` и цепочек представлений, фон, на
+  котором здесь выбрана физическая таблица.

docs/architecture/dds/session.md

@@ -0,0 +1,162 @@
+# Модель сессии в DDS
+
+Учебный результат: менти строит расчётную сущность, которой нет в потоке, —
+режет события на сессии по правилу визита, чеканит идентификатор и сверяет
+свою нарезку с эталоном. Стенд здесь играет роль сессионизатора: в бою её
+играет Метрика, которая режет визиты у себя и с октября 2025 отдаёт готовый
+`VisitID` прямо в хитах. Поэтому стенд считает сессии сам, а `VisitID`
+генератора использует только как эталон самопроверки — иначе сборка сессий
+выродилась бы в `GROUP BY` по чужому полю и центральный урок
+слоя пропал бы. Без этого абзаца действия стенда выглядят странно: «зачем
+считать то, что уже дано колонкой».
+
+## Зерно
+
+Одна строка — один визит ([CONTEXT.md](../../../CONTEXT.md)): подряд идущие
+события одной куки без пауз длиннее 30 минут, не пересекающие границу суток.
+В нарезку входят все три типа событий — торговые садятся на свои страницы
+и держат сессию наравне с просмотрами. События внутри сессии
+упорядочиваются по метке времени события (`UTCEventTime` — опорная колонка
+приёма).
+
+Граница суток проходит по модельному дню счётчика, и он у события уже есть:
+`EventDate` — свойство содержимого. Раз сессия сутки не пересекает, у всех
+её событий `EventDate` один; он и становится **днём сессии** — колонкой
+партиции, без пересчёта.
+
+## Идентификатор
+
+Идентификатор сессии в природе не существует: сессия — расчётная сущность,
+и id ей чеканит тот, кто сессионизирует. `VisitID` — такой же суррогат,
+отчеканенный генератором в роли Метрики; наш — `session_id`,
+детерминированный хеш от пары «кука + начало сессии» (`cityHash64`).
+Детерминированность обязательна: партиция дня пересобирается заменой, и
+повторный прогон обязан отчеканить те же id — счётчик или UUID это правило
+ломают.
+
+`session_id` — не ключ сортировки и не ключ шардирования, а колонка-ручка:
+в соединениях он не участвует — события его не несут, мост к заказам живёт
+на событиях. Читатели ручки — лаба сессий (сопоставить свою нарезку со
+стендовой и назвать расхождение одним числом) и разбор DQ-расхождений.
+
+## Состав строки
+
+Боевой образец — таблица визитов Метрики, парная к нашему формату хита; по
+ней состав и собран:
+
+- **ключи и времена**: кука, `session_id`, начало и конец сессии,
+  длительность, день сессии. Времена — в поясе счётчика по правилу слоя;
+- **счётчики**: событий всего, просмотров, корзин, покупок;
+- **страницы**: входная и выходная — как `StartURL`/`EndURL` визита; полного
+  списка страниц нет и у Метрики, топы считаются по событиям;
+- **атрибуция**: UTM-метки первого события сессии — так визит атрибутирует
+  Метрика. В v1 витрина брала последнее касание — заменено осознанно;
+- **паспорт куки**: категория устройства (расшифрованная, язык бизнес-модели)
+  и город — у куки они постоянны, берутся с первого события;
+- **служебные**: `_load_id` и `_load_ts` собравшего запуска — правило слоя
+  ([модель заказа](order.md), «Служебные колонки»).
+
+Осознанные расхождения с образцом: **денег в сессии нет** — визит Метрики
+несёт клиентскую выручку, у нас деньги считает только бэкенд (спека, раздел
+7), а клиентская сумма живёт в сверке; **целей нет** — их место заняли
+счётчики торговых событий.
+
+## Движок и наполнение
+
+`dds.session_rep` — `ReplicatedMergeTree` без колонки версии, по образцу
+заказа: партиция — день сессии, ключ сортировки — кука и начало сессии.
+`dds.session_dist` шардирует по `cityHash64(client_id)`, тем же выражением,
+что события, — это ко-локация с `dds.identity_map_rep` ([дока
+хранилища](../storage.md), «Раскладка по шардам»).
+Совпадение ключа с событиями не случайно: все события куки лежат на одном
+шарде, поэтому сессионизация локальна по природе — капкан смены ключа при
+вставке, который дока хранилища обещает сборкам DDS, у сессий не стреляет.
+
+Сборка — дневной батч: хранилище выше ODS по смыслу батчевое, раз второй
+источник приходит раз в сутки. Собирается день, который мир уже прожил, и
+собирается один раз и целиком; какой день прожит, слой спрашивает у позиции
+мира ([дневной конвейер](../etl.md), «Объём прогона»). Идемпотентность держит
+замена партиции. В отличие от заказов, где батч пересобирает до K «дышащих»
+дней, у сессии дышащего окна нет: прожитый день самодостаточен (правило
+спеки, раздел 6). Второй раз он соберётся только
+вынужденно — когда упавшая замена оставила позади дыру и хвост от неё накрыл
+соседние дни. Дней в одном прогоне при этом бывает несколько — столько,
+сколько мир успел прожить без слоя. Внутри живого дня
+модель сессии про сегодня честно молчит — «сегодня» смотрят через
+`dds.event_v`; сессия и по смыслу не финальна, пока день не прожит.
+
+Публичная поверхность — `dds.session_v`: обычное представление с явным
+списком деловых и собственных служебных колонок над `dds.session_dist`.
+Роли объектов и доступ следуют общей [конвенции](../storage.md), «Имена
+объектов».
+
+Источник сборки — `dds.event_v` ([контракт события](event.md)): сессии
+нужны от него ключи нарезки, тип события, страница, UTM и паспорт куки.
+Механика запуска — где собирается партиция и как подменяется на кластере —
+не входит: это устройство [дневного конвейера](../etl.md).
+
+## Сверка с эталоном
+
+Счётная DQ-проверка с зерном «кука × день»: число сессий нашей нарезки
+равно `uniqExact(VisitID)` по тем же событиям. Счёт по Distributed ловит и
+склеенную, и разрезанную сессию — мимо него проходит лишь взаимная
+компенсация ошибок внутри одной куки за день; эталон в модель не тащим —
+строка сессии остаётся нашей, а не генераторной. Поштучное сопоставление
+границ — материал лабы, где менти разбирает найденное расхождение руками. Дом проверки —
+контур DQ этапа 4. Сверке нужен `VisitID`, а сборке сессий — нет; контракт
+`dds.event_v` его скрывает, и за эталоном проверка идёт в `ods.event_v`
+([контракт события](event.md)).
+
+## Читатели
+
+- Витрина обзора сессий `session_overview_v`: дневные итоги визитов в
+  срезе устройств; читает `dds.session_v` и поднимает зерно до дня — состав и довод
+  в ее [ТЗ](../../labs/session-overview.md) (#135).
+- DQ-сверка с эталоном (см. выше).
+- Лаба сессий: менти собирает нарезку сам до знакомства с кодом стенда,
+  потом сравнивает — с эталоном и со стендовой.
+
+## Не входит
+
+- Механика запуска трансформации и замены партиций на кластере —
+  [дневной конвейер](../etl.md).
+- Контур проверок качества (даг DQ, `dm.dq_summary`) — отдельный разговор
+  этапа 4.
+- Форма витрин над сессиями — #135.
+
+## Отклонённые варианты
+
+- **Готовый `VisitID` вместо своей нарезки.** Сборка выродилась бы в
+  `GROUP BY` по чужому полю: центральный урок слоя съеден, сверка с эталоном
+  осталась бы без предмета. Боевой довод «Метрика теперь отдаёт `VisitID` в
+  хитах» честно рассказывается в лабе — после того как менти собрал сам.
+- **Гибрид: сборка по `VisitID`, DQ пересчитывает нарезку.** Сторож на
+  нарезку, которой сборка не делает; та же работа, что в варианте «считать
+  сам», но урок спрятан в проверку.
+- **Одно динамическое представление вместо физической таблицы.** Оконная
+  сессионизация на каждое чтение;
+  урок «слой — контракт, а не копия» уже закреплён за `dds.event_v` — доводы
+  модели заказа, здесь они только сильнее. Публичное `dds.session_v` поверх
+  готовой физической модели ничего заново не считает.
+- **Счётчик или UUID вместо детерминированного хеша.** Пересборка партиции
+  выдала бы другие id — замена перестала бы быть идемпотентной.
+- **`VisitID` колонкой в строке сессии.** Чужой чекан в своей модели: наша
+  сессия обязана уметь расходиться с эталоном, на этом стоит сверка;
+  поштучное сопоставление — лаба, не таблица.
+- **Массив посещённых страниц.** Вес без читателя: вход и выход — как у
+  визита Метрики, топы страниц считает витрина по событиям.
+- **UTM последнего касания (как в v1).** Визит атрибутируется своим первым
+  хитом; последнее касание — атрибуция другого уровня, не сессионного.
+- **Деньги в сессии.** Выручка — только по бэкенду; клиентская сумма живёт
+  в сверке (спека, разделы 4 и 7).
+
+## Связанные решения
+
+- [Модель заказа](order.md) — прецедент замены партиций в DDS и правило
+  служебных колонок слоя.
+- [Дока хранилища](../storage.md) — раскладка по шардам, конвенции имён,
+  часовые пояса.
+- Мастер-спека, разделы 1.2 и 7 — `VisitID` как эталон самопроверки
+  (принятое отступление приёмки), карта таблиц.
+- [CONTEXT.md](../../../CONTEXT.md) — «Визит», «Граница суток», «День
+  активности».

docs/architecture/dm.md

@@ -0,0 +1,266 @@
+# Слой DM: витрины
+
+Как модель DDS превращается в витрины для потребителя BI: какую форму
+принимает витрина, кто какие витрины строит и как слой проверяется. Состав
+колонок каждой витрины задаёт раздел 7 мастер-спеки; здесь — форма,
+наполнение и контроль.
+
+## Форма: по зерну, не по цене запроса
+
+Витрина, меняющая зерно источника — дневной агрегат, сверка по заказам, —
+материализуется: `dm.<имя>_rep` / `_dist` и публичное `dm.<имя>_v` с явным
+списком колонок, по общим [конвенциям хранилища](storage.md). Наполняет её
+`dm_transform`; ритм и механика пересборки — ниже. Витрина, сохраняющая зерно
+источника — переименование, обогащение строки, — остаётся обычным
+представлением: копию событий ради других имён колонок не держит ни один
+боевой склад.
+
+Правило выбрано учебной целью, а не ценой запроса. На объёмах стенда
+представлениями обошлось бы всё: условия сквозь цепочку представлений
+проходят ([исследование](../research/2026-08-22-view-predicate-pushdown.md)).
+Но пересборка агрегатов конвейером — производственный паттерн, ради
+которого стенд и строится, а пара «таблица рядом с представлением»
+показывает: форма — решение по роли витрины, у одного слоя законны обе.
+
+## Кто строит: стенд и менти
+
+Стенд привозит готовыми витрины трёх сюжетов дашборда этапа 8 и
+инфраструктуру контроля:
+
+- `revenue_daily` — выручка по дням и категориям; образец материализованной
+  витрины, на него ссылаются учебные задания;
+- `purchase_vs_orders` — сверка A+C с классами расхождений; зерно — заказ,
+  шардирование сохраняет ко-локацию заказов по `cityHash64(order_id)`;
+- `daily_traffic` — пара «посетители» / «известные пользователи», обогащение
+  [картой идентичностей](dds/identity.md);
+- `dq_summary` — сводка проверок качества (ниже).
+
+Остальные витрины спеки — учебные задания: менти строит их сам по ТЗ с
+образцом. Разминка — представление `events_enriched_v` (зерно события),
+затем агрегаты `top_pages_daily`, `session_overview` и `dq_errors_daily`,
+последней — самая содержательная `utm_effectiveness` с уроком `declared_*`.
+Построенная витрина встаёт в конвейер руками менти: финальный пункт ТЗ
+каждого агрегата — добавить задачу своей витрины в `dm_transform`. До этого
+конвейер о ней не знает и остаётся зелёным, после — витрина пересобирается
+наравне со стендовыми. У разминочного представления такого пункта нет:
+пересобирать нечего. Тексты заданий — в [`docs/labs/`](../labs/README.md).
+
+Дашборд этапа 8 стоит только на витринах стенда: приёмка этапа не зависит
+от выполненных домашек. Свой дашборд по витринам менти —
+[необязательная лаба](../labs/superset-dashboard.md) после этапа 8. Устройство
+стендового дашборда — в [доке зоны Superset](superset.md).
+
+## Ритм пересборки
+
+День витрины пересобирается, пока может измениться его источник, —
+поэтому ритмов три, по числу источников:
+
+- **от событий и сессий** — день замерзает сразу; пересборка догоняет
+  хвост несобранных дней заменой дневных партиций;
+- **от заказов** — день дышит, пока входит в последний слепок; пересборка
+  заменяет партиции этого отрезка, дни за ним закрыты по построению;
+- **от карты идентичностей** — не замерзает никогда: склейка
+  ретроспективна, покупка сегодня делает куку известной во всех её прошлых
+  днях, а карта пересчитывается целиком.
+
+Поэтому `daily_traffic` наследует у своего источника и ритм, и механику:
+полный пересчёт всех дней каждый прогон в `ReplacingMergeTree(_load_ts)`,
+как у самой карты. Дневных партиций у неё нет: партиция — единица замены,
+а эта витрина заменяется только целиком. На стенде такая работа остается
+быстрой; витрина читает сессии и карту через их публичные договоры.
+Пересчитывать точечно только затронутые дни не из чего: для этого надо
+знать, какие связки новые, а полный пересчёт карты этот след затирает —
+восстановление следа оставлено лабе повышенной сложности (issue #149).
+
+У `purchase_vs_orders` два источника и одна непрерывная пересборка. Заказная
+сторона задает изменяемое окно последним принятым слепком ODS, событийная —
+последний прожитый день с `purchase`. Левая граница возвращает первую дыру и
+самый ранний день с `awaiting_order`: предварительная строка уже есть в
+витрине, поэтому поиск отсутствующего дня ее не заметит. Правая граница
+доходит до более позднего из двух хвостов. Так один прогон догоняет пакетный
+разгон длиннее K и не оставляет старое ожидание замороженным.
+
+## Витрины стенда
+
+Публичные представления перечисляют деловые колонки и координаты запуска
+`_load_id`, `_load_ts` явно. Новая колонка физической таблицы сама в договор не
+попадет.
+
+### `dm.revenue_daily_v`
+
+Зерно: день заказа × категория товара. Витрина читает только оплаченные
+заказы из `dds.order_v`, синхронно разворачивает три массива позиций и узнает
+категорию артикула через `dic.products`. Один заказ с несколькими позициями
+категории считается в `orders` один раз. `units` складывает количество единиц,
+`revenue` складывает цену позиции × количество. Скидка, доставка и итог заказа
+между категориями не делятся. `aov` равен `revenue / orders` в том же срезе и
+хранит два знака после запятой.
+
+Первый запуск строит всю доступную историю. Следующие берут границы дней из
+последнего слепка ODS: только источник знает, какие даты еще может изменить.
+Пропущенный оплаченный день расширяет левую границу, чтобы частичный отказ
+не оставил дыру после следующего прогона. Агрегат при этом читает DDS; ODS
+отвечает только на вопрос об объеме.
+
+`dm.revenue_daily_rep` нарезана по `report_date`; день собирается в
+таблице-доноре и заменяется через `REPLACE PARTITION`. Цель и донор шардируются
+по `cityHash64(product_category)`. Кроме дня, у витрины только категория, а
+шесть категорий стартового мира близки по объему. Более сложный составной ключ
+распределил бы эту маленькую таблицу без нового урока.
+
+### `dm.purchase_vs_orders_v`
+
+Зерно — заказ. Покупки из `dds.event_v` сначала сворачиваются по
+`purchase_id[1]`: контракт источника обещает один номер и одну объявленную
+сумму, а отдельный счет событий оставляет класс `duplicate_event`
+наблюдаемым. Заказы приходят из `dds.order_v`. Обе стороны записаны
+подзапросами, затем соединены `FULL OUTER GLOBAL JOIN`: голая левая
+Distributed-таблица вернула бы каждый непарный заказ по разу с каждого шарда
+([исследование](../research/2026-08-22-distributed-join.md)).
+
+Непарная сторона остается `NULL` благодаря `join_use_nulls = 1`. При
+`join_use_nulls = 0` ClickHouse заполнил бы ее нулем или пустой строкой и скрыл
+отсутствие источника. Клиентская `declared_revenue` и серверная `items_total`
+сравниваются как `Decimal(18, 2)`. Классы проверяются по порядку:
+`awaiting_order` для покупки без заказа, затем `cancelled`, `lost_event`,
+`duplicate_event`, `amount_delta`, `match`. Поэтому отмененный заказ без
+события остается отмененным, а не потерянным.
+
+Витрина нарезана по `order_day`, цель и донор шардируются по
+`cityHash64(order_id)`. Диапазон собирается в доноре одной вставкой и
+заменяется по дням. Первичная сборка охватывает всю историю обоих источников;
+следующие прогоны идут по двустороннему ритму, описанному выше.
+
+### `dm.daily_traffic_v`
+
+В строке один день. `visitors` считает разные `client_id` из
+`dds.session_v`; `known_users` считает разные `user_id` после левого соединения
+с полной текущей `dds.identity_map_v`. Анонимная сессия остается в витрине.
+Несколько кук одного человека увеличивают `visitors`, но дают одного
+`known_user`, поэтому `known_users <= visitors`.
+
+Сессии и карта лежат по `client_id`, но публичные `_v` скрывают
+`Distributed`-таблицы от локальной подстановки. На ClickHouse 26.3
+`EXPLAIN PLAN` показал чтение обоих шардов на инициаторе: настройка
+`distributed_product_mode = 'local'` локального соединения не дала. Поэтому
+витрина использует явный `GLOBAL LEFT JOIN` через публичные договоры, а не
+подменяет их физическими таблицами. Это дороже по сети, зато граница слоев
+остается явной. Новая связь куки меняет прошлые дни, поэтому каждый запуск
+пишет полную историю новой версией в `ReplacingMergeTree(_load_ts)`, а
+публичное представление выбирает текущие строки через `FINAL`.
+
+## `dm.dq_summary`
+
+Зерно публичного `dm.dq_summary_v` — «день данных × атомарная проверка».
+Строка отвечает, каково качество дня сейчас; историю запусков хранит Airflow.
+Партиция совпадает с днём данных и заменяется через `REPLACE PARTITION`.
+
+Деловые колонки сводки:
+
+- `data_date` — проверяемый день;
+- `check_name` — устойчивое имя инварианта;
+- `reference_rows` — число деловых ключей на эталонной стороне;
+- `actual_rows` — число деловых ключей в проверяемом объекте;
+- `failed_rows` — число отсутствующих или различающихся ключей;
+- `status` — `pass` при нуле нарушений, иначе `fail`.
+
+Служебные `_load_id` и `_load_ts` называют собравший запуск. Представление
+перечисляет колонки явно. Порогов и промежуточного состояния нет.
+
+## Звено DQ конвейера
+
+Даг `dq_check` стоит в `etl_pipeline` после `dm_transform` и проверяет пять
+атомарных договоров:
+
+- `sessions_vs_reference`: ключ — `client_id` внутри дня, эталон —
+  `uniqExact(VisitID)` из `ods.event_v`, объект — число строк
+  `dds.session_v`;
+- `classes_vs_inventory`: ключ — `mismatch_class`, эталон — счётчик из
+  `orders` в описи мира, объект — число заказов класса в
+  `dm.purchase_vs_orders_v`. Проверяются `match`, `cancelled`, `lost_event`,
+  `duplicate_event` и `amount_delta` только для покрытых описью закрытых дней;
+- `revenue_daily_vs_dds`: ключ — `product_category` внутри дня. Сравниваются
+  `orders`, `units`, `revenue` и `aov` с прямым агрегатом `dds.order_v`;
+- `purchase_vs_orders_vs_dds`: ключ — `order_id` внутри дня. Все деловые
+  поля сверки сравниваются с независимой сборкой из `dds.event_v` и
+  `dds.order_v`;
+- `daily_traffic_vs_dds`: ключ — день. `visitors` и `known_users`
+  сравниваются с прямыми агрегатами `dds.session_v` и
+  `dds.identity_map_v`.
+
+Область каждой проверки выводится из объединения сторон. Полностью потерянный
+день или ключ поэтому не исчезает из результата. Разные ошибки тоже не могут
+скомпенсировать друг друга общим итогом: `failed_rows` считается после
+сопоставления деловых ключей.
+
+`classes_vs_inventory` — техническая растяжка пути от генератора до DM. Она
+подтверждает, что до витрины доехал записанный в описи мир, но не проверяет
+сам генератор: у настоящего магазина такого оракула нет.
+
+Четыре SQL-сверки считают дневные итоги в ClickHouse и возвращают Airflow
+только сводку и малый срез диагностики. Техническая сверка с описью читает
+небольшой файл JSON в Python. Все пять сборок пишут в общий донор. После их
+успеха даг заменяет проверенные дневные партиции. Затем именованные задачи
+читают опубликованную сводку и падают при `failed_rows > 0`. Расхождение успевает
+сохраниться до красного завершения, а ошибка сборки не затирает прежний
+результат. Красная задача печатает не больше двадцати нарушенных ключей за
+проверку со значениями сторон. Для полного списка итоговую агрегацию SQL-сверки
+заменяют на `SELECT * FROM comparison WHERE failed ORDER BY data_date,
+business_key`.
+
+Если после починки день исчез с обеих сторон, его больше нет и в новом доноре.
+Такой день удаляется из сводки отдельно: старая красная строка не должна
+превращаться в историю попыток.
+
+## Даг самопроверки
+
+Домашки контролирует `homework_check` — отдельный даг без расписания: менти
+запускает его рукой. По задаче на каждое из
+[пяти заданий по витринам](../labs/README.md).
+Задача красная, пока витрины нет или счёт не сходится, и зелёная, когда
+построено верно; сообщение об ошибке говорит, что не так и куда смотреть. Проверки — инварианты против источников витрины,
+золотые константы не прибиваются. В `dq_summary` даг не пишет: он инструмент
+лабы, а не история качества конвейера.
+
+Приём проверен на соседнем учебном стенде Airflow + Greenplum:
+валидационный даг с группами проверок по слоям давал менти обратную связь
+по каждому шагу домашки, не трогая рабочий конвейер.
+
+## Отклонённые варианты
+
+- **Весь слой представлениями.** Дёшево и всегда свежо, но главный
+  производственный паттерн слоя — пересборка агрегатов — остался бы
+  невидим, а `dm_transform` — без работы.
+- **Материализовать всё.** Копия событий ради переименования колонок —
+  антипаттерн, который менти увёз бы в бой.
+- **Гибрид по цене запроса.** Выбор формы по стоимости, которой на объёмах
+  стенда нет: сторож без настоящей опасности.
+- **Проверки домашек в конвейерном звене DQ.** Конвейер стоял бы красным до
+  выполнения лаб, а проверка, которая всегда красная, приучает себя
+  игнорировать.
+- **«Жёлтый» статус недостроенной витрины.** У задачи Airflow нет такого
+  состояния; изображать его логами — семантика, которую пришлось бы
+  расшифровывать. Красное «ещё не построено» честнее.
+- **Самопроверка пишет в `dq_summary`.** Попытки менти смешались бы с
+  историей качества конвейера.
+- **Окно заказов для `daily_traffic` — прошлое замерзает.** Дни за окном хранили
+  бы число известных на момент закрытия — витрина тихо расходится с картой
+  и протаскивает обратно «знание на дату», отвергнутое развилкой карты
+  (#133).
+- **Инкрементальный пересчёт затронутых дней по `first_matched_at`.**
+  Производственный ход, но на объёмах стенда его экономия неизмерима, а
+  след новых связок требует вернуть колонку, выкинутую в #133. Стал лабой
+  повышенной сложности — issue #149.
+- **Superset поверх DDS без слоя DM.** Терялся бы урок «витрина — контракт
+  под потребителя», против раздела 7 спеки.
+
+## Связанные решения
+
+- [Мастер-спека](../specs/2026-07-30-stand-v2-realism.md), разделы 4 и 7, —
+  состав колонок витрин и классы сверки.
+- [Дневной конвейер](etl.md) — запуск `dm_transform`, объём прогона,
+  замена партиций на кластере.
+- [Дока хранилища](storage.md) — имена объектов, конвенция чтения через `_v`,
+  партиция-донор.
+- [Карта модели DDS](dds/README.md) — источники витрин.
+- Резолюция — тикет #135 карты #127.

docs/architecture/etl.md

@@ -0,0 +1,173 @@
+# Дневной конвейер трансформаций
+
+Как принятые источники превращаются в модель DDS и витрины DM: кто запускает
+трансформации, когда и в каком объёме. Правила самих сущностей — зерно,
+движки, что именно пересобирается — живут в доках слоя
+([карта модели DDS](dds/README.md)); здесь — только конвейер.
+
+Дневная сборка вперёд появляется на этапе 4 и остаётся основным режимом
+конвейера. На этапе 5 к ней добавляется партиционная переобработка: запуск
+произвольного прошлого дня по команде.
+
+## Форма
+
+Дневной конвейер на стенде один — даг `etl_pipeline`. Своей работы
+у него нет: он дёргает слойные даги последовательно и ждёт каждый —
+`dds_transform`, затем `dm_transform` и `dq_check`. Состав проверок описан в
+[доке слоя DM](dm.md).
+
+Ждущие вызовы сделаны `TriggerDagRunOperator`. Проверка через Context7 по
+ближайшей доступной документации Airflow 3.x (версия 3.1.6) подтвердила, что
+оператор опрашивает точный созданный им прогон и краснеет вслед за потомком.
+
+Слойные даги устроены по образцу `orders_ingest`: без расписания, один
+активный прогон, запускаются триггером конвейера или рукой при разборе
+происшествий. Витрины внутри `dm_transform` — отдельные задачи.
+
+## Три пути запуска
+
+```text
+world_initialize ─┐
+world_live_day ───┼─> etl_pipeline ─> dds_transform ─> dm_transform ─> dq_check
+запуск рукой ─────┘
+
+world_next_day ─────> источники без ETL
+```
+
+- **Живой день.** `world_live_day` дёргает конвейер с ожиданием — последним
+  шагом, после установки позиции. Порядок несёт смысл: день сыгран — факт,
+  упавшая трансформация его не отменяет, поэтому позиция ставится раньше; но
+  зеленеть, не узнав, разложился ли день, работник не должен
+  ([ADR 0003](../adr/0003-dag-run-state.md)).
+  Такой отказ чинится перезапуском `etl_pipeline` рукой — перезапуску ничего
+  не нужно помнить, см. «Объём прогона».
+- **Разгон пачкой.** `world_next_day` конвейер не дёргает: пульт управляет
+  генератором и только им. После разгона менти запускает конвейер сам —
+  и видит, как слои догоняют уехавший вперёд мир.
+- **Рождение мира.** `world_initialize` дёргает конвейер последним шагом:
+  `make up` отдаёт стенд с собранными слоями, а не пустые витрины. Уроки
+  ручного запуска начинаются со следующих дней.
+
+## Объём прогона
+
+Параметров у конвейера нет: объём он выводит сам из `world_position` и
+состояния слоёв. Сессии догоняют хвост — от первого несобранного дня по
+последний прожитый; заказы пересобирают дышащее окно и тот же хвост; карта
+идентичностей пересчитывается целиком; правила витрин — у
+[слоя DM](dm.md).
+Поэтому один и тот же запуск одинаково верен из триггера, с кнопки менти и
+после падения, а разгону на семь дней хватает одного прогона.
+
+Окно заказов задаёт последний слепок, наблюдаемый в ODS. У каждого заказа
+`snapshot_date` равен последнему слепку, в котором источник его показал.
+Трансформация выбирает строки с максимальной `snapshot_date` и берёт среди них
+минимальный и максимальный `order_date`. Это границы дней, состояние которых
+источник ещё может изменить
+([ADR 0014](../adr/0014-order-version-snapshot-date.md)). Кроме живого окна,
+трансформация закрывает пропуски: находит самый ранний день, представленный в
+ODS и ещё не собранный в DDS, затем при необходимости расширяет до него левую
+границу.
+
+Позиция мира заказам не отвечает: она говорит, какой день прожит, а не какой
+доехал. Прогон дня D везёт слепок дня D − 1, да и ставится позиция раньше
+трансформации, так что после неудачного приёма обгоняет хранилище. Слой обязан
+считать объём по тому, что у него есть, а не по тому, что мир о себе заявляет.
+
+Для сессий границу задаёт `world_position`: она отличает полностью прожитый
+день от ещё идущего. Сами события этой границы не показывают: и посреди дня D,
+и сразу после его конца их позднейший день равен D. Если собрать сессии посреди
+дня, визит, начатый в 23:50, останется обрезанным: завершённый день слой
+повторно не собирает. Поэтому последний прожитый день равен первому дню
+событий плюс позиция минус один
+([`sql/dds/session_scope.sql`](../../sql/dds/session_scope.sql)).
+Оговорка про «доехал» остаётся в силе и здесь: за хвост потока отвечает не
+позиция, а «Готовность источника».
+
+## Готовность источника
+
+Первый шаг `dds_transform` проходит два барьера за общий срок в 300 секунд.
+Сначала клиент `confluent-kafka` сверяет подтвержденные смещения группы
+`clickstream_hits` с верхними смещениями обоих разделов `hits`. Группа, оба
+раздела и все смещения должны существовать. Суммарное отставание должно стать
+нулевым. Каждый опрос пишет в журнал оба смещения и отставание по разделу.
+
+Только после этого шаг проверяет обе ноды ClickHouse через
+`clusterAllReplicas`: у `ods.event_dist` в `system.distribution_queue` не
+должно остаться файлов. Каждый опрос пишет в журнал ноды, число файлов и
+`last_exception` очереди. Оба барьера опрашиваются раз в три секунды и делят
+один крайний срок. После Kafka срок не отсчитывается заново.
+
+Зелёный приём заказов о событиях не говорит ничего — топики разные и
+потребители разные. Одного нулевого отставания Kafka тоже мало: чтец мог
+подтвердить сообщение раньше, чем Distributed-таблица доставила файл на шард.
+Два барьера закрывают обе части пути до того, как сессии выберут свой объем.
+
+## Идемпотентность
+
+Партиция не заменяется простой вставкой. День собирается в таблицу-двойник —
+вставка через Distributed раскладывает строки по шардам, — затем
+`REPLACE PARTITION` на кластере атомарно подменяет кусок каждого шарда. Эта
+механика — часть самих трансформаций и строится этапом 4: без неё дневной
+прогон не повторяем. Сущности, пересчитываемые целиком, идемпотентны и без
+замены: полная перезапись в `ReplacingMergeTree` — так живут карта
+идентичностей и витрина `daily_traffic` ([слой DM](dm.md)).
+
+## Чего конвейер о себе не знает
+
+Трансформация собирает слой по правилу, а не сверяет его с источником. Отсюда
+три вещи, которых она не заметит, и у всех трёх один адрес — контур DQ.
+
+- **Часть последнего слепка не доехала.** Отказ вставки после коммита офсетов
+  уносит прочитанное с собой. Пропади так строки самого старого дня окна —
+  окно, выведенное из ярлыков, молча сузится, и день не пересоберётся
+  ([`sql/dds/order_scope.sql`](../../sql/dds/order_scope.sql)).
+- **Замена партиции прошла на одном шарде из двух.** День в слое есть — значит,
+  объём следующего прогона его не тронет, а слой останется собранным наполовину
+  из старого, наполовину из нового.
+- **Брак внутри `items` становится нулями.** Строгий приём внутрь позиций не
+  смотрит, разбор по типу молчит, и цена без числа доедет до витрины выручки
+  нулём ([`sql/dds/order_rebuild.sql`](../../sql/dds/order_rebuild.sql)).
+
+Общее у них одно, и оно же подсказывает лекарство: ответить может только
+сверка слоя с источником по дню — счёт заказов и позднейший `updated_at` с
+обеих сторон. Трансформации такую сверку не поручают намеренно: она собирает,
+а проверяет другой. Так две роли остаются различимы, и ни одна не
+притворяется другой.
+
+## Не входит
+
+- Партиционная переобработка — переиграть произвольный прошлый день или
+  диапазон, включая форму необязательных параметров того же дага.
+- Инкрементальный ETL вместо пересборки отклонен (#2, wontfix). Идея отдельной
+  лабы на эту тему — #149.
+- Состав витрин `dm_transform` и проверок `dq_check` —
+  [дока слоя DM](dm.md).
+
+## Отклонённые варианты
+
+- **Задачи трансформаций прямо в работниках пульта.** Один зелёный прогон —
+  весь день, но пульт — про ось времени: работников два, шаги дублировались
+  бы, а этапу 5 пришлось бы выдирать их обратно.
+- **Make-цель или SQL рукой при приёмке.** Второй оркестратор рядом с
+  Airflow — против [ADR 0013](../adr/0013-world-lifecycle.md), — а в живом
+  режиме слои копили бы отставание молча.
+- **Временный даг с нейтральным именем до этапа 5.** Дневная сборка вперёд
+  никуда не денется, переезд был бы переименованием ради выдуманной границы.
+- **Диапазон дней параметрами триггера.** Ручному запуску менти параметры
+  передавать некому, а перезапуск после падения требовал бы помнить conf
+  упавшего прогона.
+- **Принять гонку с хвостом `hits`.** Дыра всплыла бы в DQ-сверке, а
+  чиниться — не раньше этапа 5.
+
+## Связанные решения
+
+- [ADR 0003](../adr/0003-dag-run-state.md) — зелёный конец графа не
+  переживает отказ выше: отсюда ожидания в триггерах.
+- [ADR 0009](../adr/0009-world-control.md) — пульт мира: его работник
+  живого дня и дёргает конвейер.
+- [ADR 0013](../adr/0013-world-lifecycle.md) — жизненный цикл мира: почему
+  прикладным процессом владеет Airflow и почему `world_initialize` кончается
+  собранными слоями.
+- Резолюция — тикет #134 карты #127; что пересобирает каждая сущность —
+  [заказ](dds/order.md), [сессия](dds/session.md),
+  [карта идентичностей](dds/identity.md).

docs/architecture/generator/README.md

@@ -0,0 +1,59 @@
+# Генератор кликстрима
+
+Путеводитель показывает, как пройти генератор от корневого зерна до двух
+выходов дня, не пересказывая код и спеки.
+
+## Целевая картина одним взглядом
+
+- **Подпоток определяется местом в дереве, а мир внутри подпотока — порядком
+  бросков** — [дерево зерен и порядок бросков](seeds.md).
+- **Мир поднимает только когорты окна, нужные запрошенному дню** —
+  [ленивость мира](lazy-world.md).
+- **Устройство и город принадлежат куке на всю жизнь и потому решаются
+  планом состава** — [паспорт куки](cookie-passport.md).
+- **Выбор по весам сведен к целым броскам и арифметике интервалов** —
+  [целочисленная случайность](randomness.md).
+- **Торговля получает готовые строки страниц и возвращает поток событий
+  вместе с покупками для бэкенда** — [шов торговых событий](commerce-seam.md).
+- **Сутки принадлежат поясу счетчика, а `UTCEventTime` остается абсолютной
+  меткой** — [время модельного дня](counter-time.md).
+
+```mermaid
+flowchart LR
+    seed["Корневое зерно"] --> streams["Подпотоки"]
+    streams --> cohorts["Когорты"]
+    cohorts --> audience["Аудитория дня"]
+    audience --> visits["Визиты"]
+    visits --> output["Выход day.stream"]
+    output --> events["Поток событий"]
+    output --> backend["Заказы дня<br/>orders.of_day"]
+```
+
+За правой ветвью начинается отдельный набор документов —
+[устройство заказов](../orders/README.md).
+
+## Живой проход
+
+Из каталога `generator/` одна команда собирает канонический D0 и показывает
+все стадии на одном экране:
+
+```sh
+make demo
+```
+
+Когорту и аудиторию пример получает через открытый интерфейс плана, а визиты
+считает группировкой выходных строк по `VisitID`. Код прохода —
+[`demo.main`](../../../generator/src/clickstream_generator/demo.py).
+
+## Родословная
+
+Устройство генератора и основания решений записаны в [спеке этапа
+2](../../specs/2026-08-01-generator.md), а границы двух источников и склейки —
+в [мастер-спеке стенда](../../specs/2026-07-30-stand-v2-realism.md).
+Основания трех решений записаны в
+[ADR 0015](../../adr/0015-counter-timezone.md),
+[ADR 0016](../../adr/0016-cookie-passport.md) и
+[ADR 0017](../../adr/0017-order-numbering.md), а спека этапа 2 закрыта.
+Путеводитель появился по тикету
+[#48](https://git.dementev.space/ddmitry/clickstream-data-platform/issues/48):
+он отвечает на другой вопрос — как пройти принятое устройство по коду.

docs/architecture/generator/commerce-seam.md

@@ -0,0 +1,34 @@
+# Шов торговых событий
+
+Этот документ отвечает на вопрос, что день передает торговой части и что
+получает от нее назад.
+
+[`day.stream`](../../../generator/src/clickstream_generator/day.py) сначала
+собирает выровненные по строкам ряды трафика:
+
+- `columns` — готовые колонки просмотров страниц;
+- `page` — вид страницы магазина;
+- `product` — номер товара у карточки;
+- `person` — человек за кукой строки.
+
+`page` указывает, куда может сесть торговое событие, а `product` — какой товар
+посетитель действительно открыл. `person` в кликстрим не выходит: он нужен
+только для второй проекции покупки — заказа бэкенда.
+
+[`commerce.weave`](../../../generator/src/clickstream_generator/commerce.py)
+принимает эти ряды, вплетает `add_to_cart` и `purchase`, снова упорядочивает
+поток и возвращает обновленные `columns`, `page`, `product` вместе с
+[`commerce.Purchases`](../../../generator/src/clickstream_generator/commerce.py).
+
+`Purchases` — узкая передача следующей стороне. В ней лежат номер заказа,
+купленные товары и количества, клиентская выручка, промокод, момент события и
+человек. Все они получены из тех же покупок, что уехали в поток, а не разобраны
+назад из JSON.
+
+[`orders.of_day`](../../../generator/src/clickstream_generator/orders.py)
+принимает `Purchases`, а [`day.Day`](../../../generator/src/clickstream_generator/day.py)
+отдает заказы рядом с колонками событий. Здесь поток дня расходится на две
+ветви, показанные в индексе.
+
+За этой границей начинается [устройство заказов](../orders/README.md). Судьба,
+слепки и деньги бэкенда описаны там.

docs/architecture/generator/cookie-passport.md

@@ -0,0 +1,29 @@
+# Паспорт куки
+
+Этот документ отвечает на вопрос, почему паспорт куки решает план состава, а
+день только разворачивает его в события.
+
+[`plan.cohort`](../../../generator/src/clickstream_generator/plan.py) получает
+случайность через
+[`seeds.cohort_stream`](../../../generator/src/clickstream_generator/seeds.py)
+и вызывает [`plan._passports`](../../../generator/src/clickstream_generator/plan.py)
+в ветви «состав мира». Это не подпоток отдельного дня.
+
+`plan._passports` выбирает строки устройства и города из справочников. У
+двухкуковой пары город первой куки переносится во вторую, а устройство
+выбирается из другой половины профилей. Сведения о парах есть только у плана.
+Если независимо вывести паспорт каждой куки из `ClientID`, один человек может
+оказаться в двух городах — это будет ложью в данных.
+
+[`plan.Cohort`](../../../generator/src/clickstream_generator/plan.py) хранит
+номера устройства и города. `Cohort.visitors_on` переносит их в
+[`plan.DayAudience`](../../../generator/src/clickstream_generator/plan.py), а
+[`day.stream`](../../../generator/src/clickstream_generator/day.py) разворачивает
+профили в колонки событий. День не бросает паспорт заново, поэтому кука
+сохраняет его на всю жизнь.
+
+Броски паспорта стоят после прежнего состава когорты. Правило такого
+продолжения подпотока описано в [дереве зерен](seeds.md), а выбор
+паспорта объясняет [ADR 0016](../../adr/0016-cookie-passport.md). Зачем стенду
+нужна двухкуковая пара одного человека, фиксирует
+[мастер-спека](../../specs/2026-07-30-stand-v2-realism.md), раздел 5.

docs/architecture/generator/counter-time.md

@@ -0,0 +1,40 @@
+# Время модельного дня
+
+Этот документ отвечает на вопрос, почему дата модельных суток не обязана
+совпадать с UTC-датой события.
+
+В коде встречаются три координаты времени:
+
+- D — номер дня на оси модельного времени;
+- `EventDate` — дата D в поясе счетчика;
+- `UTCEventTime` — абсолютная метка события.
+
+Местное время гостя задает форму активности внутри суток, а границу дня задает
+пояс счетчика.
+
+[`world.ORIGIN`](../../../generator/src/clickstream_generator/world.py) — D0
+календарной оси: он переводит номер D в конкретную дату. Это не механизм
+часового пояса. Механизм —
+[`world.COUNTER_TIMEZONE_MINUTES`](../../../generator/src/clickstream_generator/world.py),
+смещение пояса счетчика от UTC.
+
+В [`day._columns`](../../../generator/src/clickstream_generator/day.py)
+`EventDate` получается как `ORIGIN + D`. Чтобы получить абсолютную полночь
+тех же суток, код вычитает смещение счетчика, а затем прибавляет секунды
+события внутри дня. Поэтому сутки `2026-06-01` в UTC+4 начинаются в
+`2026-05-31 20:00:00Z`: у первых четырех часов
+`toDate(UTCEventTime) != EventDate`.
+
+[`day._starts`](../../../generator/src/clickstream_generator/day.py) сначала
+выбирает час из городской строки весов, собранной
+[`day._hour_cumulative`](../../../generator/src/clickstream_generator/day.py),
+а затем равномерно выбирает секунду внутри часа. Строка поворачивает суточную
+волну на разницу между поясом гостя и поясом счетчика. Так вечерний пик гостя
+попадает в нужные часы внутри дня, но граница суток и `EventDate` остаются
+счетчиковыми.
+
+Как часовой пояс меняет представление времени в ClickHouse, описано в разделе
+«Часовые пояса» [документа о хранилище](../storage.md). Типы и публичный смысл
+полей записаны в [описании события](../../formats/clickstream-event.md).
+Выбор модели времени объясняет
+[ADR 0015](../../adr/0015-counter-timezone.md).

docs/architecture/generator/lazy-world.md

@@ -0,0 +1,26 @@
+# Ленивость мира
+
+Этот документ отвечает на вопрос, как любой день собирается без прожитой
+истории и без глобального списка посетителей.
+
+[`plan.cohort`](../../../generator/src/clickstream_generator/plan.py) строит
+одну когорту по зерну и дню ее появления. Отрицательные дни обозначают
+предысторию; ее глубину ограничивает
+[`world.RETURN_TAIL_DAYS`](../../../generator/src/clickstream_generator/world.py).
+Запоминание уже рассчитанных когорт ускоряет соседние вызовы, но не становится
+состоянием мира: очистка кеша не меняет результат.
+
+[`plan.audience`](../../../generator/src/clickstream_generator/plan.py) для
+дня D спрашивает `Cohort.visitors_on(D)` у когорт от
+`D - RETURN_TAIL_DAYS` до D и соединяет полученные части. Поэтому вызов для
+D0 поднимает всю предысторию в окне — 91 когорту от D−90 до D0.
+
+Когорты предыстории дают D0 вернувшихся посетителей, но собственных событий
+не порождают. Ось событий начинается в D0. Окно активности отсчитывается от
+первого дня человека и остается общим для обеих его кук; за краем окна
+когорта больше не может попасть в аудиторию.
+
+Отсюда самостоятельность дня: D500 и D5 заглядывают назад на одинаковое число
+когорт. Ни плану состава, ни день-функции горизонт мира не нужен.
+Зачем приняты предыстория и ограниченное окно, объясняет [спека
+генератора](../../specs/2026-08-01-generator.md), раздел 1.

docs/architecture/generator/randomness.md

@@ -0,0 +1,41 @@
+# Целочисленная случайность
+
+Этот документ отвечает на вопрос, как читать целочисленный выбор по весам и
+зачем генератору свой маленький `weights.py`.
+
+За `PCG64` и целые броски `Generator.integers` отвечает NumPy.
+Генератор стенда не пользуется готовым выбором по вещественным вероятностям и
+плавающими распределениями: их алгоритмы и системная математика могут
+различаться между версиями и архитектурами. Зависимости закреплены, а броски
+остаются целыми — так выполняется побайтовое обещание, записанное в [спеке
+генератора](../../specs/2026-08-01-generator.md), раздел 2.
+
+## Одна таблица весов
+
+[`weights.pick`](../../../generator/src/clickstream_generator/weights.py)
+сначала получает накопленные веса. Для весов `2, 3, 1` это границы
+`2, 5, 6`. Затем он бросает целое число из полуинтервала `[0, 6)` и находит
+первую границу справа:
+
+- броски `0–1` выбирают вариант 0;
+- броски `2–4` выбирают вариант 1;
+- бросок `5` выбирает вариант 2.
+
+Размер участка и есть вес варианта. Нормировать веса до долей единицы не
+нужно.
+
+## Своя таблица для каждой строки
+
+[`weights.pick_row`](../../../generator/src/clickstream_generator/weights.py)
+работает так же, когда у каждого броска свой ряд весов. Ряды с одинаковой
+суммой укладываются друг за другом. Номер ряда смещает бросок на его участок,
+единый поиск находит ячейку, а обратное смещение возвращает номер варианта.
+
+Конкретный проход виден в
+[`day._hour_cumulative`](../../../generator/src/clickstream_generator/day.py)
+и [`day._starts`](../../../generator/src/clickstream_generator/day.py): для
+каждого города суточная волна повернута в свой ряд, но сумма весов от поворота
+не меняется.
+
+При чтении вызова `pick` полезно представлять ряд целочисленных участков:
+бросок выбирает вариант, в чей участок он попал.

docs/architecture/generator/seeds.md

@@ -0,0 +1,61 @@
+# Дерево зерен и порядок бросков
+
+Этот документ отвечает на вопрос, почему место подпотока стабильно, а порядок
+бросков внутри него менять нельзя.
+
+## Два порядка
+
+[`seeds.cohort_stream`](../../../generator/src/clickstream_generator/seeds.py)
+и [`seeds.day_stream`](../../../generator/src/clickstream_generator/seeds.py)
+находят ветвь по позиции `SeedSequence(entropy, spawn_key)`. Поэтому результат
+ветви не зависит от того, какую соседнюю ветвь вычислили раньше.
+
+Внутри найденной ветви живет один `Generator`. Каждый его вызов забирает
+следующие значения. Поэтому порядок вызовов меняет результат: прежний
+пятый бросок после вставки становится шестым и достается другому свойству
+мира.
+
+Дерево целиком описано в модуле
+[`seeds`](../../../generator/src/clickstream_generator/seeds.py), а
+[`seeds.Component`](../../../generator/src/clickstream_generator/seeds.py)
+задает его нижний уровень — четыре подпотока дня:
+
+```text
+корневое зерно
+├── состав мира
+│   ├── ось событий → номер дня → когорта
+│   └── предыстория → глубина → когорта до D0
+└── дни
+    └── номер дня
+        ├── TRAFFIC
+        ├── COMMERCE
+        ├── ORDERS
+        └── BEACONS — потеря и повторная отправка событий
+```
+
+Отрицательному дню нельзя отдать отрицательную позицию, поэтому предыстория
+получила отдельную ветвь. Компоненты дня тоже занимают позиции, а не получают
+зерна в порядке запуска.
+
+## Что ломает вставка
+
+Новый бросок в середине функции сдвигает все последующие значения этого
+подпотока. Код продолжает работать, но тем же свойствам достается другая
+случайность. Соседние подпотоки остаются прежними, а измененная часть
+канонического мира проявляется в описи и побайтовом сравнении.
+
+Какое обещание воспроизводимости это защищает, записано в
+[спеке генератора](../../specs/2026-08-01-generator.md), раздел 2. Здесь важно
+различать два свойства: `SeedSequence` стабилизирует адрес ветви, но порядок
+бросков внутри `Generator` стабилизирует только сам код.
+
+## Броски последними
+
+Новое свойство продолжает существующий подпоток после прежних бросков. Такой
+бросок не отнимает значения у уже рассчитанных свойств. В
+[`plan.cohort`](../../../generator/src/clickstream_generator/plan.py) паспорт
+куки был дописан после состава и назначенных заказов, а личность человека —
+после паспорта. Поэтому прежние ряды остались прежними.
+
+Почему паспорт вообще принадлежит этой ветви, разобрано отдельно в
+[документе о паспорте куки](cookie-passport.md).

docs/architecture/monitoring.md

@@ -1,205 +0,0 @@
-# Мониторинг: из чего собран и что скребёт
-
-Документ описывает зону мониторинга: какие сервисы в неё входят, что собирает
-Prometheus, какие источники данных подготовлены в Grafana, каким пользователем
-она ходит в ClickHouse и что показывают собранные дашборды. Зачем зоне именно
-такой состав и какие дашборды на нём задуманы — [ADR
-0002](../adr/0002-monitoring-scope.md); устройство доступа — [ADR
-0007](../adr/0007-clickhouse-access.md).
-
-**Что здесь есть и чего ещё нет.** Собран пол: свой образ Grafana с плагином
-ClickHouse, два подготовленных источника данных, экспортёр метрик Kafka и цель
-для него у Prometheus. Поверх пола стоит главный дашборд — «Данные»; «Кластер»
-и «Запросы» приносят отдельные тикеты. Правил оповещения и серверного журнала
-`system.text_log` тоже пока нет.
-
-## Состав
-
-| Сервис | Образ | Что делает |
-|---|---|---|
-| `prometheus` | `prom/prometheus:v3.13.2` | опрашивает цели раз в 15 секунд, порт стенда `29090` |
-| `grafana` | `clickstream-grafana:local` | интерфейс мониторинга; собирается из `infra/grafana/`, порт стенда `23000` |
-| `kafka-exporter` | `danielqsj/kafka-exporter:v1.9.0` | переводит состояние брокера в метрики Prometheus, порт `9308` |
-
-Плагин ClickHouse 4.20.0 входит в образ Grafana. Фоновая установка плагинов
-при запуске отключена.
-
-## Что скребёт Prometheus
-
-| Цель | Задание | Метка `role` | Откуда метрики |
-|---|---|---|---|
-| `clickhouse-01:9363` | `clickhouse` | `server` | встроенный экспортёр ноды |
-| `clickhouse-02:9363` | `clickhouse` | `server` | встроенный экспортёр ноды |
-| `clickhouse-keeper:9363` | `clickhouse-keeper` | `keeper` | встроенный экспортёр keeper |
-| `kafka-exporter:9308` | `kafka` | `exporter` | внешний экспортёр |
-
-Ровно эти четыре цели пересчитывает `check_prometheus_targets` в
-`scripts/stand-smoke.sh` — и по значению `up`, и по списку адресов. Пятая цель
-красит смоук; это и есть способ заметить, что состав пола поменяли молча.
-
-## Источники данных Grafana
-
-Оба источника подготовлены файлами в `infra/grafana/provisioning/datasources/`
-и объявлены `editable: false`: править их через интерфейс нельзя, источник
-истины — репозиторий.
-
-- `prometheus` — основной по умолчанию, ходит на `http://prometheus:9090`.
-- `clickhouse` — плагин `grafana-clickhouse-datasource`, нативный протокол,
-  `clickhouse-01:9000`, пользователь `grafana`, пароль из `.env`.
-
-Источник ClickHouse смотрит на `clickhouse-01`. Системные таблицы обеих нод
-панели читают через `clusterAllReplicas`, как принято в ADR 0002.
-
-## Доступ к ClickHouse
-
-Grafana ходит пользователем `grafana` с ролью `monitoring_reader`: читает слои,
-таблицы базы `dic` и системные таблицы. `REMOTE` разрешает
-`clusterAllReplicas`, `CLUSTER` — запросы `ON CLUSTER`. Решение о своей роли
-записано в [ADR 0007](../adr/0007-clickhouse-access.md). Пароль задаётся
-переменной `CLICKHOUSE_GRAFANA_PASSWORD`.
-
-## Куда кладутся дашборды
-
-Каталог `infra/grafana/provisioning/dashboards/` смонтирован в контейнер и
-объявлен провайдером в `provider.yml`: Grafana подхватывает оттуда файлы
-дашбордов, удалять и править их через интерфейс запрещено. Новый дашборд — это
-новый файл в каталоге и больше ничего: в `compose.yaml` заходить не нужно, ради
-этого каталог и заведён заранее.
-
-Файлы каталога разбирает `make config-test`, рядом с файлами дагов и по тому же
-доводу ([testing.md](testing.md)).
-
-## Дашборд «Данные»
-
-`infra/grafana/provisioning/dashboards/data.json` — шесть панелей на один
-экран. Вопрос у экрана один: с потоком всё в порядке? Состав панелей и довод за
-каждую — [ADR 0002](../adr/0002-monitoring-scope.md).
-
-Порогов и цветовых вердиктов на панелях нет: на дашборд смотрят глазами,
-красное и зелёное живёт в проверках и дагах DQ.
-
-| Панель | Откуда берёт | О чём отвечает |
-|---|---|---|
-| Свежесть | `ods.event_dist`, `ods.order_dist` | сколько прошло с последней доехавшей строки |
-| Поток | `stg.hits_raw_dist`, `stg.orders_raw_dist` | сколько строк приезжает в слой сырья |
-| Брак | те же и `ods.*_errors_dist` | сколько приехавшего не разобралось и какая это доля |
-| Сходимость | экспортёр Kafka и `stg.hits_raw_dist` | произведённое против приземлившегося |
-| Отставание | `kafka_consumergroup_lag` | сколько сообщений не прочитано |
-| Дневной слепок | `stg.orders_raw_dist` | какой слепок доехал, когда и после какой паузы |
-
-### Почему слои у панелей разные
-
-Свежесть спрашивают у ODS. Это слой, который читают, и у заказов дорога до него
-длиннее: сырьё привозит забор, а типизированную строку кладёт разбор. Встань
-разбор — свежесть ODS это покажет, свежесть сырья нет.
-
-Читает свежесть физическую `_dist`, а не каноническое `ods.*_v`. Представление
-прячет за собой `FINAL` и отвечает про текущее состояние сущностей, а вопрос
-здесь про доставку: местом диагностики доставленных версий физическая таблица
-названа там же, где заведено представление (`sql/ddl/30-ods-views.sql`).
-
-Поток и брак считаются по слою сырья. Сырьё записывает каждую доставку и ничего
-не схлопывает, а `ReplacingMergeTree` в ODS схлопнет и повтор доставки события,
-и все версии одного заказа. Считай мы поток по ODS — он занизился бы, и тем
-сильнее, чем дольше живёт стенд.
-
-Доля брака берётся от приехавшего, а не от суммы «годные плюс брак»: брак не
-отдельная куча, а часть сырья, которая не прошла разбор.
-
-Окно у панели брака — окно дашборда, и это не косметика. Сырьё живёт трое
-суток, а брак — месяц: доля за всё время делила бы месяц брака на трое суток
-приехавшего и однажды перевалила бы за сотню процентов.
-
-Панель дневного слепка, наоборот, окна не знает. Её вопрос про состояние, а не
-про отрезок, и последние десять слепков она показывает всегда.
-
-Отдельного ряда «против вчерашнего» на панели потока нет, и это решение, а не
-пропуск. Реальное «вчера» на стенде чаще всего приходится на время, когда
-стенда ещё не было. А сдвинуть ряд на модельные сутки значит записать в JSON
-дашборда ускорение мира — ровно ту пометку про тик, которую [ADR
-0002](../adr/0002-monitoring-scope.md) в дашборде держать не велит: поменяют
-ускорение, и панель молча соврёт. Сравнение остаётся глазу: модельные сутки
-укладываются в минуты реального времени, и соседние дни мира помещаются в одно
-окно панели сами.
-
-### Чтецов Kafka панели не читают
-
-`stg.hits_raw_kafka` и `stg.orders_raw_kafka` — таблицы движка Kafka, а не
-хранилище: запрос из панели у второго забрал бы слепок себе и сдвинул офсеты
-(`kafka_commit_on_select`, см. `sql/ddl/10-stg-tables.sql`), а даг приёма
-приехал бы к пустому топику. Приземлившееся панели считают по `stg.*_raw_dist`,
-произведённое — по метрикам экспортёра.
-
-### Как считается сходимость
-
-Произведённое живёт в Kafka, приземлившееся — в ClickHouse, и со своей стороны
-ни одна из них не видит другую. Поэтому панель смешанная: ряд «произведено в
-Kafka» приходит из Prometheus, ряд «приземлилось в ClickHouse» — из ClickHouse.
-Единицы общие — сообщений за интервал панели. Со стороны Kafka это разность
-офсетов топика, «сейчас минус интервал назад», с суммой по обеим партициям; со
-стороны ClickHouse — `count()` строк сырья по тому же интервалу.
-
-Два соседних способа отвергнуты, и оба по замеру на живом стенде. `increase`
-растягивает приращение на всё окно и на минутном интервале промахивается на
-проценты: здоровый стенд выглядел бы расходящимся. Накопленный итог от начала
-окна точнее обоих приростов, но отсчитывать его надо от края окна — а на
-свежем стенде окно начинается раньше, чем появился экспортёр, и ряд пропадает
-целиком.
-
-Столбцы ClickHouse подписаны правым краем, а не левым. Точка Prometheus — это
-прирост к моменту времени, а `count()` по интервалу — сумма, которая набирается
-к его концу; подпиши мы её началом, здоровые ряды разъехались бы ровно на один
-столбец. Шаг панели при этом не мельче минуты: экспортёр опрашивают раз в
-пятнадцать секунд, и на более мелком шаге ряд Kafka пошёл бы ступеньками там,
-где ряд ClickHouse идёт гладко.
-
-Точка в точку ряды всё равно не совпадут, и ждать этого не надо: опрос
-экспортёра не попадает на границы столбцов, поэтому на разгоне потока линия
-Kafka идёт чуть выше. Читается устойчивый разрыв между линиями, а не разница в
-один столбец.
-
-Панель смотрит на топик событий. У него приём непрерывный, и разрыв виден
-сразу. Слепок заказов уезжает пачкой раз в модельные сутки, и вопрос к нему
-другой — не «сходится ли поток», а «доехала ли выгрузка и вовремя ли». На него
-отвечает своя панель, и модельный день она берёт из самого сообщения: в сырьё
-он приезжает полем `snapshot_date`.
-
-## Что проверено
-
-Права роли `monitoring_reader` сверены 21 августа 2026 года по документации
-ClickHouse через MCP Context7; разбор — в
-[ADR 0007](../adr/0007-clickhouse-access.md), раздел «Что проверено».
-
-Сам состав проверен на живом стенде 21 августа 2026 года, собранном заново
-после `make clean`.
-
-- Grafana видит плагин `grafana-clickhouse-datasource` 4.20.0
-  (`/api/plugins?type=datasource`), оба подготовленных источника здоровы.
-- Запрос источника ClickHouse к `system.one` через `clusterAllReplicas` вернул
-  2 — с одной ноды видны обе.
-- Prometheus видит ровно четыре цели, все со значением `up = 1`; запрос
-  `kafka_consumergroup_lag` вернул ряды по группам `clickstream_*`.
-- `make smoke` 21/21, `make check-clickhouse` 10/10, `make check-services` 7/7.
-
-Дашборд «Данные» проверен на живом стенде в тот же день, `world_live` снят с
-паузы.
-
-- Дашборд поднимается из каталога сам: файл положен, панели появились без
-  ручного импорта. Сохранение и удаление через API отвергнуты («Cannot save
-  provisioned dashboard», «provisioned dashboard cannot be deleted»).
-- Все шесть панелей отвечают через `/api/ds/query` — и в окне часа по
-  умолчанию, и в окне на шесть часов, которое начинается раньше, чем поднялся
-  экспортёр. Пустых нет ни при идущем потоке, ни при остановленном.
-- Брак: подсунутое в топик `hits` негодное сообщение легло в
-  `ods.event_errors` с классом `keyset_mismatch`; панель показала единицу и
-  долю 0,039 % в десятиминутном окне. Строка убрана мутациями из
-  `stg.hits_raw_rep` и `ods.event_errors_rep`, обе таблицы вернулись к нулю.
-- Сходимость: на живом потоке за двадцать пять минут медиана расхождения между
-  рядами 3 %, худший столбец 11 % — на переломе потока, как и описано выше.
-  Отказы тоже по замеру: `increase` расходился сильнее, а накопленный итог
-  пропадал целиком, стоило окну начаться раньше экспортёра.
-- Свежесть реагирует на остановленный поток и возвращается. Через пять минут
-  после конца модельного дня панель показала 305 с у событий и 288 с у
-  заказов; стоило пустить следующий день, события вернулись к секунде.
-  Свежесть заказов при этом растёт до конца дня и садится, когда доедет его
-  слепок, — так и устроен второй источник.

docs/architecture/monitoring/README.md

@@ -0,0 +1,104 @@
+# Мониторинг: из чего собран и за чем следит
+
+Набор описывает зону мониторинга: какие сервисы в неё входят, что собирает
+Prometheus, какие источники данных подготовлены в Grafana, каким пользователем
+она ходит в ClickHouse и куда кладутся дашборды. Устройство каждого дашборда —
+отдельным файлом, указатели ниже. Зачем зоне именно такой состав и какие
+дашборды на нём задуманы — [ADR 0002](../../adr/0002-monitoring-scope.md);
+устройство доступа — [ADR 0007](../../adr/0007-clickhouse-access.md).
+
+**Что здесь есть и чего ещё нет.** Собран пол: свой образ Grafana с плагином
+ClickHouse, два подготовленных источника данных, экспортёр метрик Kafka и цель
+для него у Prometheus. Поверх пола стоят все три дашборда ADR 0002, они
+перечислены ниже. Правил оповещения и серверного журнала `system.text_log`
+пока нет.
+
+## Состав
+
+| Сервис | Образ | Что делает |
+|---|---|---|
+| `prometheus` | `prom/prometheus:v3.13.2` | опрашивает цели раз в 15 секунд, порт стенда `29090` |
+| `grafana` | `clickstream-grafana:local` | интерфейс мониторинга; собирается из `infra/grafana/`, порт стенда `23000` |
+| `kafka-exporter` | `danielqsj/kafka-exporter:v1.9.0` | переводит состояние брокера в метрики Prometheus, порт `9308` |
+
+Плагин ClickHouse 4.20.0 входит в образ Grafana. При сборке Grafana CLI берёт
+закреплённый выпуск из официального репозитория на GitHub, а не из каталога
+Grafana: прямой запрос к каталогу при проверке вернул HTTP 451. Фоновая
+установка плагинов при запуске отключена.
+
+## Кого опрашивает Prometheus
+
+| Цель | Задание | Метка `role` | Откуда метрики |
+|---|---|---|---|
+| `clickhouse-01:9363` | `clickhouse` | `server` | встроенный экспортёр ноды |
+| `clickhouse-02:9363` | `clickhouse` | `server` | встроенный экспортёр ноды |
+| `clickhouse-keeper:9363` | `clickhouse-keeper` | `keeper` | встроенный экспортёр keeper |
+| `kafka-exporter:9308` | `kafka` | `exporter` | внешний экспортёр |
+
+Ровно эти четыре цели пересчитывает `check_prometheus_targets` в
+`scripts/stand-smoke.sh` — и по значению `up`, и по списку адресов. Пятая цель
+красит смоук; это и есть способ заметить, что состав пола поменяли молча.
+
+## Источники данных Grafana
+
+Оба источника подготовлены файлами в `infra/grafana/provisioning/datasources/`
+и объявлены `editable: false`: править их через интерфейс нельзя, источник
+истины — репозиторий.
+
+- `prometheus` — основной по умолчанию, ходит на `http://prometheus:9090`.
+- `clickhouse` — плагин `grafana-clickhouse-datasource`, нативный протокол,
+  `clickhouse-01:9000`, пользователь `grafana`, пароль из `.env`.
+
+Источник ClickHouse смотрит на `clickhouse-01`. Системные таблицы обеих нод
+панели читают через `clusterAllReplicas`, как принято в ADR 0002.
+
+## Доступ к ClickHouse
+
+Grafana ходит пользователем `grafana` с ролью `monitoring_reader`: читает слои,
+таблицы базы `dic` и системные таблицы. `REMOTE` разрешает
+`clusterAllReplicas`, `CLUSTER` — запросы `ON CLUSTER`. Решение о своей роли
+записано в [ADR 0007](../../adr/0007-clickhouse-access.md). Пароль задаётся
+переменной `CLICKHOUSE_GRAFANA_PASSWORD`.
+
+## Дашборды
+
+Каталог `infra/grafana/provisioning/dashboards/` смонтирован в контейнер и
+объявлен провайдером в `provider.yml`: Grafana подхватывает оттуда файлы
+дашбордов, удалять и править их через интерфейс запрещено. Новый дашборд — это
+новый файл в каталоге и больше ничего: в `compose.yaml` заходить не нужно, ради
+этого каталог и заведён заранее.
+
+Файлы каталога разбирает `make config-test`, рядом с файлами дагов и по тому же
+доводу ([testing.md](../testing.md)).
+
+Порогов и цветовых вердиктов на панелях нет ни на одном дашборде: на них
+смотрят глазами, красное и зелёное живёт в проверках и дагах DQ.
+
+Собранные дашборды:
+
+- **«Данные»** (`data.json`) — с потоком всё в порядке: свежесть, поток, брак,
+  сходимость Kafka с ClickHouse, отставание чтения и дневной слепок заказов.
+  Устройство и разбор панелей — [data.md](data.md).
+- **«Кластер»** (`cluster.json`) — что с машиной: процессор, память и диски
+  обеих нод, части и слияния, keeper, очередь распределённых DDL. Устройство и
+  разбор панелей — [cluster.md](cluster.md).
+- **«Запросы»** (`queries.json`) — что выполнялось и во что обошлось: тяжёлые
+  запросы, аппетит по посетителям, ошибки. Устройство и разбор панелей —
+  [queries.md](queries.md).
+
+## Что проверено
+
+Права роли `monitoring_reader` сверены 21 августа 2026 года по документации
+ClickHouse через MCP Context7; разбор — в
+[ADR 0007](../../adr/0007-clickhouse-access.md), раздел «Что проверено».
+
+Сам состав проверен на живом стенде 21 августа 2026 года, собранном заново
+после `make clean`.
+
+- Grafana видит плагин `grafana-clickhouse-datasource` 4.20.0
+  (`/api/plugins?type=datasource`), оба подготовленных источника здоровы.
+- Запрос источника ClickHouse к `system.one` через `clusterAllReplicas` вернул
+  2 — с одной ноды видны обе.
+- Prometheus видит ровно четыре цели, все со значением `up = 1`; запрос
+  `kafka_consumergroup_lag` вернул ряды по группам `clickstream_*`.
+- `make smoke` 21/21, `make check-clickhouse` 10/10, `make check-services` 7/7.

docs/architecture/monitoring/cluster.md

@@ -0,0 +1,156 @@
+# Дашборд «Кластер»
+
+`infra/grafana/provisioning/dashboards/cluster.json` — семь панелей. Вопрос у
+экрана один: что с машиной? Состав панелей и довод за каждую —
+[ADR 0002](../../adr/0002-monitoring-scope.md).
+
+Свой вопрос каждая панель называет заголовком прямо на экране. Здесь — только
+источники, о них и речь ниже.
+
+| Панель | Откуда берёт |
+|---|---|
+| Процессор | `system.metric_log` |
+| Память | `system.asynchronous_metric_log` |
+| Диски | `system.metric_log` |
+| Части | `system.parts` |
+| Слияния | `system.part_log` |
+| Keeper | встроенные метрики keeper через Prometheus |
+| Распределённый DDL | `system.distributed_ddl_queue` |
+
+Окно у дашборда — полчаса, обновление — полминуты. Пачка из
+`make generate-batch` проходит за двадцать секунд, и на получасовой оси это
+узкий всплеск в пару столбиков. Шире окно не берут, чтобы всплеск не выродился
+в точку; уже — чтобы не промахнуться мимо него, заглянув через минуту, и чтобы
+рядом осталось спокойное время: подъём читается только над полом. Кто хочет
+разглядеть форму вплотную, растягивает окно мышью по самому всплеску.
+
+Панель частей окна не знает вовсе. `system.parts` — опись живых частей, и
+вопрос к ней про сейчас: колонки со временем в ней есть, но ни одна не годится
+в ось. Очередь DDL окна тоже не знает, но по другой причине: она показывает
+последние двадцать записей, потому что в спокойные полчаса пуста, а пустая
+панель ничего бы не рассказала.
+
+## Обе ноды на одной панели
+
+Системная таблица у каждой ноды своя: `system.metric_log` на `clickhouse-01`
+знает только про `clickhouse-01`. Запрос без обёртки показал бы половину
+правды и ничем бы себя не выдал — вторая нода просто не появилась бы в легенде.
+Поэтому запросы идут через `clusterAllReplicas`, а `hostName()` подписывает,
+чья это строка.
+
+Исключений два, и они разной природы. Очередь распределённых DDL лежит не у
+ноды, а в keeper, и обе ноды читают из него одну и ту же очередь целиком,
+вместе со строками про соседа. Обёртка здесь не добавила бы правды, а удвоила
+бы каждую строку — это единственная панель дашборда без неё. Правило поэтому
+звучит так: `clusterAllReplicas` нужен там, где у каждой ноды своя правда.
+
+Второе исключение мягче. Панель слияний читает обе ноды той же обёрткой, но
+складывает их в один ряд: шарды сливают симметрично, и разделение удвоило бы
+легенду ради двух одинаковых кривых.
+
+## Пол на графиках — журналы самого сервера
+
+ClickHouse ведёт около десятка собственных журналов: `metric_log`,
+`trace_log`, `text_log`, `query_log` и соседние. Все они — таблицы MergeTree:
+их пишут и сливают постоянно, даже когда на стенде не происходит ничего.
+Отсюда процессор и диски, которые никогда не падают в ноль.
+
+Вычесть этот пол на процессоре и дисках нечем: их счётчики знают, сколько
+работы сделал процесс, и не знают, ради какой таблицы. Своя нагрузка на этих
+двух панелях читается как подъём над полом, а не как число само по себе.
+
+У частей и слияний пол отделим: в `system.parts` и `system.part_log` у каждой
+строки написано, какой таблице она принадлежит. Обе панели поэтому показывают
+всё, кроме журналов сервера, — и у каждой на это своя причина.
+
+Столбик у слияний шириной в минуту, а не в шаг панели. Слияния — события
+редкие: на своём шаге столбик выродился бы в волосяную линию, и четыре события
+за полчаса пришлось бы искать глазами.
+
+Слияниям фильтр иначе не пережить по размеру: за спокойные полчаса они съели
+6 492 части в системных журналах против 219 в `ods` и `stg` вместе. Оставь мы
+журналы в кадре, ряды слоёв прижались бы к нулю, и панель рассказывала бы про
+уборку за сервером вместо приехавших данных. Сколько эта уборка стоит, видно
+этажом выше, на процессоре и дисках.
+
+Частям фильтр нужен для другого: без него в таблице десятки строк, а значит
+нужен предел — и предел рвёт пару нод пополам, оставляя таблицу с одной нодой в
+кадре. С фильтром помещаются все, и предел не нужен.
+
+## Что именно меряют процессор, память и диски
+
+Процессор считается по времени самого сервера
+(`ProfileEvent_OSCPUVirtualTimeMicroseconds`), а не по загрузке машины.
+Метрики с именами `OS*` сняты с хоста целиком: обе ноды показывали бы в них
+одно и то же число, и панель на два ряда потеряла бы смысл.
+
+Память показана резидентной (`MemoryResident`), а не той, что сервер считает
+своей (`MemoryTracking`). Разница не косметическая: на праздной ноде
+`MemoryTracking` — 113 МиБ при 846 МиБ резидентной памяти, а ядро, решая, кого
+убить за нехватку памяти, смотрит на вторую величину
+([ADR 0004](../../adr/0004-resource-limits.md)). По первой нода, которую
+вот-вот убьют, выглядит совершенно здоровой.
+
+Пунктирный ряд «отведено» — предел памяти контейнера, та самая коробка из
+ADR 0004. Он тоже читается живьём, метрикой `CGroupMemoryTotal`: впиши мы
+4 ГиБ числом в JSON, панель молча соврала бы в тот день, когда предел поменяют.
+
+У дисков считаются обращения к файлам — `OSReadChars` и `OSWriteChars`.
+Счётчики блочного устройства (`OSReadBytes`) для той же панели не годятся:
+блочное чтение на стенде почти всё время нулевое, части лежат в страничном
+кэше, и слияние перечитывает их оттуда. Работа при этом идёт настоящая, и
+панель по блокам показывала бы её рваным пунктиром.
+
+## Keeper и очередь DDL — то, что живёт вне нод
+
+Keeper — отдельный сервис, системных таблиц у него нет, и панель по нему
+единственная на дашборде приходит из Prometheus.
+
+Показывает она размер дерева. В keeper лежит журнал репликации, а в нём —
+запись на каждую часть: пока поток идёт, дерево растёт, а когда части
+домержились и старые записи убраны, оседает. Замер за полчаса живого потока:
+9 078 узлов на подъёме, 11 512 на пике, 10 308 через десять минут после того,
+как поток встал.
+
+Очередь распределённых DDL — вторая половина того же сюжета: через keeper
+проходит каждый запрос `ON CLUSTER`. Заглядывают сюда с одним вопросом: доехал
+ли он до обеих нод и что ответила каждая.
+
+## Что проверено
+
+Дашборд проверен на живом стенде 21 августа 2026 года.
+
+- Дашборд поднимается из каталога сам, все семь панелей отвечают через
+  `/api/ds/query` в окне на полчаса. Пустых нет.
+- Обе ноды видны на четырёх панелях из пяти, что читают системные таблицы нод.
+  Пятая — слияния, там ноды сложены намеренно. Без `clusterAllReplicas`
+  осталась только очередь DDL, и обёртка ей действительно не нужна: запрос с
+  ней вернул с `clickhouse-01` и с `clickhouse-02` одно и то же число записей —
+  на день замера 124 и 124.
+- Под нагрузкой. `make generate-batch` (50 626 событий одной пачкой), замер в
+  десятисекундных вёдрах: процессор поднялся с 0,04–0,18 ядра до 0,54 на одной
+  ноде и 0,64 на другой, запись — с 400 КиБ/с до 2,1 и 4,5 МиБ/с. Ведро тут
+  часть ответа: в тридцатисекундном тот же прогон даёт 0,29 и 0,21 ядра.
+  Следующие десять секунд обе величины уже вернулись к прежним: на таком объёме
+  подъём и оседание укладываются в полминуты.
+- Слияния под той же нагрузкой отозвались столбиком в ряду `stg` высотой в
+  15 съеденных частей.
+- Блочное чтение действительно молчит: за минуту вокруг вставки `OSReadBytes`
+  был нулевым в десяти десятисекундных окнах из четырнадцати, а обращения к
+  файлам шли непрерывно во всех.
+- Память: около 1 ГиБ занятого против 4 ГиБ отведённого на каждой ноде.
+- Панель частей показала `ods.order_rep` по 142 строки в части против 13 046 у
+  `ods.event_rep` — заказы приезжают дневным слепком, события потоком. Строк
+  вышло восемь: четыре таблицы, каждая обеими нодами. Таблиц ошибок среди них
+  нет, и это правда состояния — частей у них пока не появилось.
+- Очередь DDL показала `CREATE MATERIALIZED VIEW ... ON CLUSTER` в состоянии
+  `Finished` и со временем по каждой ноде. Новые безопасные записи для показа
+  оставляет `make check-clickhouse`: цель создаёт и удаляет временные таблицы
+  `ON CLUSTER`. Канонический DDL появляется в очереди при создании мира дагом
+  `world_initialize`.
+
+Подписи рядов (`${__field.labels.node}`) и правило, по которому пунктирным
+становится только ряд «отведено», сверены по документации Grafana через MCP
+Context7. И то и другое применяется на стороне браузера, через
+`/api/ds/query` их не видно: там проверено только, что нода приезжает меткой
+ряда, а метрика — его именем.

docs/architecture/monitoring/data.md

@@ -0,0 +1,117 @@
+# Дашборд «Данные»
+
+`infra/grafana/provisioning/dashboards/data.json` — шесть панелей на один
+экран. Вопрос у экрана один: с потоком всё в порядке? Состав панелей и довод за
+каждую — [ADR 0002](../../adr/0002-monitoring-scope.md).
+
+Свой вопрос каждая панель называет заголовком прямо на экране. Здесь — только
+источники, о них и речь ниже.
+
+| Панель | Откуда берёт |
+|---|---|
+| Свежесть | `ods.event_dist`, `ods.order_dist` |
+| Поток | `stg.hits_raw_dist`, `stg.orders_raw_dist` |
+| Брак | те же и `ods.*_errors_dist` |
+| Сходимость | экспортёр Kafka и `stg.hits_raw_dist` |
+| Отставание | `kafka_consumergroup_lag` |
+| Дневной слепок | `stg.orders_raw_dist` |
+
+## Почему слои у панелей разные
+
+Свежесть спрашивают у ODS. Это слой, который читают, и у заказов дорога до него
+длиннее: сырьё привозит забор, а типизированную строку кладёт разбор. Встань
+разбор — свежесть ODS это покажет, свежесть сырья нет.
+
+Читает свежесть физическую `_dist`, а не каноническое `ods.*_v`. Представление
+прячет за собой `FINAL` и отвечает про текущее состояние сущностей, а вопрос
+здесь про доставку. Местом диагностики доставленных версий физическая таблица
+названа там же, где заведено представление (`sql/ddl/30-ods-views.sql`).
+
+Поток и брак считаются по слою сырья. Сырьё записывает каждую доставку и ничего
+не схлопывает, а `ReplacingMergeTree` в ODS схлопнет и повтор доставки события,
+и все версии одного заказа. Считай мы поток по ODS — он занизился бы, и тем
+сильнее, чем дольше живёт стенд.
+
+Доля брака берётся от приехавшего, а не от суммы «годные плюс брак»: брак не
+отдельная куча, а часть сырья, которая не прошла разбор.
+
+Окно у панели брака — окно дашборда, и это не косметика. Сырьё живёт трое
+суток, а брак — месяц: доля за всё время делила бы месяц брака на трое суток
+приехавшего и однажды перевалила бы за сотню процентов.
+
+Панель дневного слепка, наоборот, окна не знает. Её вопрос про состояние, а не
+про отрезок, и последние десять слепков она показывает всегда.
+
+Отдельного ряда «против вчерашнего» на панели потока нет, и это решение, а не
+пропуск. Реальное «вчера» на стенде чаще всего приходится на время, когда
+стенда ещё не было. А сдвинуть ряд на модельные сутки значит записать в JSON
+дашборда ускорение мира — ровно ту пометку про тик, которую [ADR
+0002](../../adr/0002-monitoring-scope.md) в дашборде держать не велит: поменяют
+ускорение, и панель молча соврёт. Сравнение остаётся глазу: модельные сутки
+укладываются в минуты реального времени, и соседние дни мира помещаются в одно
+окно панели сами.
+
+## Приземлившееся считают по слою сырья
+
+Приземлившееся панели считают по `stg.*_raw_dist`, произведённое — по метрикам
+экспортёра. Таблицы движка Kafka `stg.hits_raw_kafka` и `stg.orders_raw_kafka`
+хранилищем не работают: у второго стоит `kafka_commit_on_select`
+(`sql/ddl/10-stg-tables.sql`), и запрос из панели забрал бы слепок себе,
+сдвинул офсеты, а даг приёма приехал бы к пустому топику.
+
+## Как считается сходимость
+
+Произведённое живёт в Kafka, приземлившееся — в ClickHouse, и со своей стороны
+ни одна из них не видит другую. Поэтому панель смешанная: ряд «произведено в
+Kafka» приходит из Prometheus, ряд «приземлилось в ClickHouse» — из ClickHouse.
+Единицы общие: сообщения за интервал панели. Со стороны Kafka это разность
+офсетов топика, «сейчас минус интервал назад», с суммой по обеим партициям; со
+стороны ClickHouse — `count()` строк сырья по тому же интервалу.
+
+Два соседних способа отвергнуты, и оба по замеру на живом стенде. `increase`
+растягивает приращение на всё окно и на минутном интервале промахивается на
+проценты: здоровый стенд выглядел бы расходящимся. Накопленный итог от начала
+окна точнее обоих приростов, но отсчитывать его надо от края окна — а на
+свежем стенде окно начинается раньше, чем появился экспортёр, и ряд пропадает
+целиком.
+
+Столбцы ClickHouse подписаны правым краем, а не левым. Точка Prometheus — это
+прирост к моменту времени, а `count()` по интервалу — сумма, которая набирается
+к его концу; подпиши мы её началом, здоровые ряды разъехались бы ровно на один
+столбец. Шаг панели при этом не мельче минуты: экспортёр опрашивают раз в
+пятнадцать секунд, и на более мелком шаге ряд Kafka пошёл бы ступеньками там,
+где ряд ClickHouse идёт гладко.
+
+Точка в точку ряды всё равно не совпадут, и ждать этого не надо: опрос
+экспортёра не попадает на границы столбцов, поэтому на разгоне потока линия
+Kafka идёт чуть выше. Читать надо устойчивый разрыв между линиями; разница в
+один столбец не значит ничего.
+
+Панель смотрит на топик событий. У него приём непрерывный, и разрыв виден
+сразу. Слепок заказов уезжает пачкой раз в модельные сутки, и вопрос к нему
+другой — не «сходится ли поток», а «доехала ли выгрузка и вовремя ли». На него
+отвечает своя панель, и модельный день она берёт из самого сообщения: в сырьё
+он приезжает полем `snapshot_date`.
+
+## Что проверено
+
+Дашборд проверен на живом стенде 21 августа 2026 года, `world_live` снят с
+паузы.
+
+- Дашборд поднимается из каталога сам: файл положен, панели появились без
+  ручного импорта. Сохранение и удаление через API отвергнуты («Cannot save
+  provisioned dashboard», «provisioned dashboard cannot be deleted»).
+- Все шесть панелей отвечают через `/api/ds/query` — и в окне часа по
+  умолчанию, и в окне на шесть часов, которое начинается раньше, чем поднялся
+  экспортёр. Пустых нет ни при идущем потоке, ни при остановленном.
+- Брак: подсунутое в топик `hits` негодное сообщение легло в
+  `ods.event_errors` с классом `keyset_mismatch`; панель показала единицу и
+  долю 0,039 % в десятиминутном окне. Строка убрана мутациями из
+  `stg.hits_raw_rep` и `ods.event_errors_rep`, обе таблицы вернулись к нулю.
+- Сходимость: на живом потоке за двадцать пять минут медиана расхождения между
+  рядами 3 %, худший столбец 11 % — на переломе потока, как и описано выше.
+- Свежесть реагирует на остановленный поток и возвращается. Через пять минут
+  после конца модельного дня панель показала 305 с у событий и 288 с у
+  заказов; стоило пустить следующий день, события вернулись к секунде.
+  Свежесть заказов при этом растёт до конца дня и садится, когда доедет его
+  слепок, — так и устроен второй источник.

docs/architecture/monitoring/queries.md

@@ -0,0 +1,76 @@
+# Дашборд «Запросы»
+
+`infra/grafana/provisioning/dashboards/queries.json` — три панели поверх одной
+таблицы, `system.query_log`. Вопрос у экрана один: что выполнялось и во что это
+обошлось? Состав панелей и довод за каждую —
+[ADR 0002](../../adr/0002-monitoring-scope.md).
+
+Свой вопрос каждая панель называет заголовком прямо на экране. Здесь — только
+то, чего в заголовке не скажешь.
+
+Журнал у каждой ноды свой, поэтому все три панели читают его через
+`clusterAllReplicas` — то же правило, что и на [«Кластере»](cluster.md).
+
+Окно — час, обновление — полминуты. Час взят потому, что сюда приходят с
+вопросом о прошлом: «почему у меня всё стояло десять минут назад». Полминуты —
+чтобы только что запущенный тяжёлый запрос не пришлось ждать: в журнал он
+попадает через несколько секунд после конца.
+
+## Первым в списке видно сам мониторинг
+
+Grafana ходит в ClickHouse обычным пользователем, и её запросы ложатся в
+журнал наравне с человеческими. На спокойном стенде верх списка тяжёлых
+запросов занимает `grafana`: панель свежести с дашборда «Данные» читает по
+полмиллиона строк за каждое обновление.
+
+Так и надо: мониторинг тоже стоит денег, и цену видно там же, где и всё
+остальное. Спрячь мы свои запросы фильтром — цена ушла бы с глаз, а панель «Кто
+спрашивает» недосчиталась бы самого частого посетителя.
+
+Различать посетителей дашборд умеет потому, что у Grafana своя учётка со своей
+ролью ([ADR 0007](../../adr/0007-clickhouse-access.md)). Ходи она под
+аналитиком, панель «Кто спрашивает» показывала бы одну строку на всех.
+
+## Что отброшено и почему
+
+Каждый запрос попадает в журнал дважды: строкой начала и строкой конца. В
+строке начала нет ни длительности, ни памяти, ни прочитанных строк — там их
+ещё неоткуда взять. Панели считают по строкам конца.
+
+Распределённый запрос кладёт в журнал не только себя. Инициатор пишет свою
+строку, а каждый шард — свою, про доставшийся ему кусок. Две панели из трёх
+считают только запросы инициатора: иначе один запрос человека выглядел бы
+тремя, а прочитанные строки сложились бы дважды.
+
+Панель ошибок, наоборот, куски шардов показывает: отказ случается там, где
+считали, и строка шарда — единственное место, где эта нода названа. В замере с
+принудительным пределом памяти `clickhouse-01` записал свой отказ, а
+`clickhouse-02` — свой, и вторая строка видна только без фильтра по
+инициатору.
+
+## Пустой пользователь
+
+Часть строк журнала приходит без имени пользователя: так записана собственная
+работа сервера — чтение топиков движком Kafka, вставки материализованных
+представлений, обслуживание. Панели подписывают такие строки «фоновая работа
+сервера»: пустая клетка в таблице читается как поломка, а это не она.
+
+## Что проверено
+
+Дашборд проверен на живом стенде 21 августа 2026 года.
+
+- Дашборд поднимается из каталога сам, все три панели отвечают через
+  `/api/ds/query` в окне на час. Пустых нет.
+- Тяжёлый запрос виден. `GROUP BY` по `ods.event_dist` от учётки `analyst`
+  приехал в панель со своими числами: 741 мс, 53,32 МиБ памяти, 701 994
+  прочитанные строки.
+- Ошибки видны и различаются по природе: отказ по правам (`bi` без `SELECT` на
+  `ods`) и ошибка в тексте запроса (несуществующая колонка) легли в панель
+  разными строками, каждая с полным текстом.
+- Строка шарда в панели ошибок настоящая. Принудительный предел памяти на
+  распределённом `GROUP BY` дал две записи: `clickhouse-01` с
+  `is_initial_query = 1` и `clickhouse-02` с нулём. Вторая пропала бы, стой на
+  панели тот же фильтр, что на соседних.
+- Панель «Кто спрашивает» разделила шесть учёток — `grafana`, `analyst`, `etl`,
+  `dict`, `bi`, `default` — и фоновую работу сервера. Больше всех прочитала
+  `grafana`: 11,5 млн строк за час, своими же панелями.

docs/architecture/orders/README.md

@@ -27,8 +27,8 @@
   не случиться вовсе. На выходе из окна заказ либо `paid`, либо `cancelled` —
   [судьба заказа](fate.md).
 - **Расхождения и опоздания — часть мира, а не грязь**: два подпотока —
-  заказная и событийная стороны; броски независимы, пересечения выходят
+  `ORDERS` для заказной стороны и `BEACONS` для событийной; броски независимы,
-  арифметикой, приоритет классов работает по-настоящему —
+  пересечения выходят арифметикой, приоритет классов работает по-настоящему —
   [классы расхождений и опоздание](fate.md).
 - **Опись хранит только то, чего движение мира не меняет**: хеш байтов
   каждого слепка и счётчики наблюдаемых классов —
@@ -38,8 +38,10 @@
   [мост к склейке](identity.md).
 - **Приём — пакетный забор**: одно прямое чтение Kafka в STG, два
   `INSERT SELECT` в типизированный ODS и таблицу ошибок; `ods.order`
-  принимает версии заказа на `ReplacingMergeTree(updated_at)` —
+  принимает версии заказа на `ReplacingMergeTree(snapshot_date)` —
   [приём из Kafka в ODS](ingestion.md).
+- **Дальше заказ живёт моделью DDS** — уже по хранилищную сторону границы,
+  в наборе слоя: [модель заказа](../dds/order.md).
 - **Стартовый мир отправляет семь слепков** (дни 0…6): у последнего прожитого
   дня клики есть, а заказов нет, и график выручки дозаполняется по ходу
   мира — [заказы в стартовом мире](start-world.md).
@@ -49,14 +51,6 @@
 
 ## Открытые решения
 
-- **Имя подпотока событийной стороны** — вместе с её содержимым на этапе 6;
-  из мёртвых имён никто не бросает, переименование ничего не сдвигает (#72).
-  Заказная сторона уже названа — подпоток `ORDERS` ([судьба
-  заказа](fate.md)).
-- **Конкретные веса и доли** — таблицы исходов, моментов, задержки опоздания,
-  доли классов, стоимость доставки — калибровка при реализации; финальная
-  фиксация чисел — пересборка эталонного мира, этап 7. При пересборке правки
-  потребуют только числа, не устройство.
 - **Контур проверок качества для расхождений** (даг DQ, `dm.dq_summary`) —
   остаётся в тумане карты #69; естественное место разговора — этап 4.
 - **Каноническое чтение событий `ods.event_v`** — отдельный тикет #86, к

docs/architecture/orders/fate.md

@@ -16,11 +16,10 @@
 и `LATECOMERS` решения не переживают — они названы по классам витрины, а
 компонент называет часть мира; новые стороны занимают те же позиции.
 Заказная сторона названа при реализации — подпоток `ORDERS` на позиции 2;
-событийная получит имя вместе с содержимым на этапе 6, до тех пор позиция 3
+событийная — `BEACONS` на позиции 3: маячок счетчика либо не долетает, либо
-занята мёртвым именем прежней нарезки. Отклонено: *один компонент на всю
+отправляется повторно. Отклонено: *один компонент на всю судьбу* — правка
-судьбу* — правка событийной механики молча меняла бы байты слепка;
+событийной механики молча меняла бы байты слепка; *компонент на класс* —
-*компонент на класс* — пять имён под ручки калибровки, которые крутятся
+пять имён под ручки калибровки, которые крутятся разом.
-разом.
 
 **Правило формы, без которого разделение не работает: броски заказной стороны
 делаются на полную длину дня, а не на отобранных заказах.** Иначе длина броска
@@ -56,8 +55,11 @@
 часа покупки, и менти нашёл бы этот наклон первым же разрезом.
 
 **Доли.** Ориентир мастер-спеки ~5% читается как доля отменённых вообще; как
-она делится между двумя дорогами — строки таблицы исходов. Точные числа —
+она делится между двумя дорогами — строки таблицы исходов. Замер на
-калибровка этапа 7; проверок вида «отмен от 4 до 6 процентов» не заводим.
+каноническом мире (28 дней, 2026-08-30, docs/architecture/testing.md, «Что
+проверено»): отменено 5,15% заказов — 3,03% оплачен-потом-отменен, 2,12%
+отменен неоплаченным; в пределах ориентира. Проверок вида «отмен от 4 до 6
+процентов» не заводим.
 
 **Что из двух дорог видно.** В `dds.order` дороги неразличимы — там последняя
 версия; различает их история версий: сырьё STG и физические версии
@@ -108,12 +110,13 @@
 покупку. Довод не в связности легенды: точечный дубль ломал бы урок соседнего
 класса — разрыв воронки, на котором держится потеря, сжался бы втрое; при
 сюжетном разрыв снова равен доле потерь. `purchaseID`, суммы и позиции у дубля
-один в один — посчитал наивно, удвоил выручку. Дубль случается только там, где
+один в один — посчитал наивно, удвоил выручку. Дубль случается только там,
-до следующего визита куки остаётся запас сверх таймаута: иначе сборка сессий у
+где пауза до следующего визита куки длиннее таймаута и задержки дубля вместе:
-менти разошлась бы с `VisitID` — сломался бы эталон, ради которого `VisitID`
+иначе сборка сессий у менти разошлась бы с `VisitID` — сломался бы эталон,
-в потоке лежит. Задержка дубля — секунды-минуты, короче таймаута визита,
+ради которого `VisitID` в потоке лежит. Задержка дубля —
-поэтому `VisitID` тот же. Полночь режет дубль парой — просмотр вместе с
+секунды-минуты, короче таймаута визита, поэтому `VisitID` тот же. Полночь
-покупкой, по тому же правилу, что у подтверждения с торговым хвостом.
+режет дубль парой — просмотр вместе с покупкой, по тому же правилу, что у
+подтверждения с торговым хвостом.
 Отклонено: *обе точечные* — дубль затирает урок потери; *обе сюжетные* —
 потеря перестаёт быть видна со стороны трекера.
 
@@ -127,18 +130,20 @@
 подделывается — строка создана, когда заказ родился, — но в слепках дней
 d…d+δ−1 её нет, а с d+δ она появляется в том состоянии, до которого заказ
 дожил: отменённый на второй день и опоздавший на третий приедет в первом же
-своём слепке как `cancelled` — «выгрузка догоняет жизнь». Задержка — таблица
+своём слепке как `cancelled` — «выгрузка догоняет жизнь». Таблица задержки
-весов из трёх строк: 0 на подавляющем весе, 1 и 2 — это и есть «D+1/D+2»
+состоит из трёх строк: δ = 0/1/2 с весами 90/5/5; 1 и 2 — это D+1 и D+2
-мастер-спеки. Меряется она в днях снятия слепка, а не отправки: иначе сдвиг
+мастер-спеки. Бросок идёт последним в подпотоке `ORDERS`; затем δ назначенного
-отправки удвоился бы, и обещанные D+1/D+2 стали бы D+2/D+3. Дальше таблица не
+планом заказа обнуляется. Меряется задержка в днях снятия слепка, а не
-идёт: заказ с δ = 6 приехал бы ровно в одном слепке, и обещание «пропущенный
+отправки: иначе сдвиг отправки удвоился бы, и обещанные D+1/D+2 стали бы
-день ничего не ломает» на нём перестало бы быть верным; при δ ≤ 2 у всякого
+D+2/D+3. Дальше таблица не идёт: заказ с δ = 6 приехал бы ровно в одном
-заказа слепков не меньше пяти. Легенда: заказ ушёл в ручную обработку и попал
+слепке, и обещание «пропущенный день ничего не ломает» на нём перестало бы
-в выгрузку позже. Отклонено: *сдвиг `created_at`* — подделка аудита источника:
+быть верным; при δ ≤ 2 у всякого заказа слепков не меньше пяти.
-день создания строки разошёлся бы с днём покупки, чьё равенство держит
+Легенда: заказ ушёл в ручную обработку и попал в выгрузку позже. Отклонено:
-синхронная модель ([откуда берётся заказ](snapshot.md)), заказ уехал бы в
+*сдвиг `created_at`* — подделка аудита источника: день создания строки
-чужую партицию, и «выручка дня D» перестала бы отвечать покупкам дня D —
+разошёлся бы с днём покупки, чьё равенство держит синхронная модель
-сломалась бы та самая сверка, ради которой всё строится.
+([откуда берётся заказ](snapshot.md)), заказ уехал бы в чужую партицию,
+и «выручка дня D» перестала бы отвечать покупкам дня D — сломалась бы та
+самая сверка, ради которой всё строится.
 
 **Пересечения.** Броски независимы, пересечения выходят арифметикой, приоритет
 мастер-спеки работает по-настоящему. Исключений два, и оба названы выше: дубль

docs/architecture/orders/ingestion.md

@@ -7,10 +7,10 @@
 ## Проблема
 
 Заказы приезжают полным слепком окна изменяемости, но Kafka передаёт его
-отдельными сообщениями и не сообщает потребителю, где слепок закончился. Прямое
+отдельными сообщениями и не сообщает потребителю, где слепок закончился.
-чтение Kafka Engine возвращает одну порцию. Поэтому прежняя публикация через
+Прямое чтение Kafka Engine возвращает одну порцию без признака полноты.
-`REPLACE PARTITION snapshot_date` приравнивала дату наблюдения к отсутствующей
+Поэтому `snapshot_date` не может служить границей публикации: `REPLACE
-транспортной границе и могла заменить день неполным набором строк.
+PARTITION` могла бы заменить партицию дня неполным набором строк.
 
 Одновременно типизированный ODS не должен принимать правдоподобные значения по
 умолчанию из грязного JSON или останавливать весь пакет из-за одной строки.
@@ -19,8 +19,8 @@
 
 - сохранить пакетный забор как контраст потоковому приёму событий;
 - один раз принять байты в STG и независимо разложить строки на годные и брак;
-- хранить в ODS типизированные версии заказов, не привязывая идемпотентность к
+- хранить в ODS типизированные версии заказов, не публикуя слепок заменой
-  `snapshot_date`;
+  партиции;
 - дать следующим слоям один корректный способ прочитать текущее состояние;
 - оставить код проверки коротким и ограничить его контрактом провода.
 
@@ -39,24 +39,27 @@
 конца прогона. Все строки получают `_load_id`, равный `run_id` Airflow.
 `_load_ts` вычисляется при этой записи и дальше переносится без пересчёта.
 Запрос забора лежит в [`sql/stg/orders_raw_load.sql`](../../../sql/stg/orders_raw_load.sql):
-даг задаёт порядок и параметры, а преобразование остаётся в SQL своего слоя.
+`SQLExecuteQueryOperator` задаёт подключение и передаёт `run_id` как параметр
+ClickHouse `load_id`, а преобразование остаётся в SQL своего слоя.
 
 Один следующий `task_id` отвечает за весь переход STG → ODS. Внутри него два
 последовательных `INSERT SELECT` читают неизменный срез по `_load_id`: первый
 пишет годные строки в `ods.order`, второй — брак в `ods.order_errors`.
 Транзакции между запросами нет. При частичном сбое Airflow повторяет весь
 `task_id`; одинаковые исходные строки и служебные метки не вычисляются заново.
-Запросы лежат рядом с целями:
+Обе вставки лежат в одном самодостаточном файле
-[`order_load.sql`](../../../sql/ods/order_load.sql) и
+[`order_parse.sql`](../../../sql/ods/order_parse.sql). Airflow сначала
-[`order_errors_load.sql`](../../../sql/ods/order_errors_load.sql).
+шаблонизирует файл, затем делит получившийся SQL на выражения и исполняет их по
+порядку в одной задаче `parse_batch`.
 
-Условия запросов взаимодополняющие: один общий предикат определяет брак, а
+Условия запросов взаимодополняющие: один общий предикат определяет годную
-годная ветвь использует его буквальное отрицание. Все функции предиката
+строку, а ветвь брака использует его буквальное отрицание. Все функции предиката
 возвращают результат без исключения, а сам предикат всегда заканчивается в
 `true` или `false`, не в `NULL`. Постоянный классификатор между STG и ODS для
-этого не нужен. Обе ветви включают один файл
+этого не нужен. Предикат объявлен локальным макросом Jinja внутри
-[`_order_wire_contract.sql`](../../../sql/ods/_order_wire_contract.sql), поэтому
+`order_parse.sql` и разворачивается в оба выражения. Макрос убирает
-предикат нельзя случайно исправить только в одной из них.
+дублирование, но не вводит отдельный фрагмент, который нельзя исполнить
+самостоятельно.
 
 ## Граница строгого приёма
 
@@ -78,6 +81,13 @@ JSON-объектом с точным набором ключей: `order_id`, `
 малый контракт заказа нет причины. Граница строгости заканчивается на форме
 провода: содержимое позиций и бизнес-инварианты намеренно остаются ниже.
 
+Контракт источника задаёт частоту: **одной дате соответствует один слепок**. Это
+свойство всего слепка, поэтому предикат одной строки его не проверяет. Вторая
+выгрузка того же дня даст ничью по `snapshot_date`, и выбор строки потеряет
+однозначность. Модельный источник выполняет условие; в настоящей интеграции
+его фиксируют в договоре с источником
+([ADR 0014](../../adr/0014-order-version-snapshot-date.md)).
+
 Класс брака выбирается первым совпадением:
 
 1. `not_an_object`;
@@ -91,18 +101,35 @@ JSON-объектом с точным набором ключей: `order_id`, `
 ## Роль ODS
 
 `ods.order_rep` хранит физически принятые версии в
-`ReplacingMergeTree(updated_at)`. Ключ сортировки — `order_id`, партиция — день
+`ReplacingMergeTree(snapshot_date)`. Ключ сортировки — `order_id`, партиция —
-неизменного `created_at`. `ods.order_dist` шардирует по
+день неизменного `created_at`. `ods.order_dist` шардирует по
 `cityHash64(order_id)`: только так все версии заказа попадают на один шард и
 `FINAL` даёт корректный результат через распределённую таблицу.
 
 Четыре координаты отвечают на разные вопросы:
 
-- `updated_at` — какая бизнес-версия заказа новее;
 - `snapshot_date` — в слепке какого модельного дня источник показал строку;
+- `updated_at` — когда строку последний раз меняли в источнике;
 - `_load_id` — какой запуск Airflow принял строку;
 - `_load_ts` — когда строка приехала в хранилище.
 
+Версию выбирает `snapshot_date`: выживает строка с максимальной датой слепка
+([ADR 0014](../../adr/0014-order-version-snapshot-date.md)). Поэтому
+`snapshot_date` показывает последнее наблюдение заказа. По строкам последней
+даты слепка DDS определяет окно пересборки. `_load_id` и `_load_ts` принадлежат
+той физической строке, которую сохранило слияние, и описывают её доставку.
+
+Схема версий стоит на дисциплине источника: слепок с поздней датой не
+показывает состояния старше. Модельный мир её держит — состояние читается на
+границе суток, и слепок дня выходит чистой функцией зерна и дня; источник,
+собирающий слепок из отставшей реплики, её ломает. Деловая метка `updated_at`
+при этом монотонна по слепкам, поэтому выбор по дате слепка даёт тот же ответ,
+что выбор по метке (замер — «Что проверено»). Тихая правка строки — ручным
+`UPDATE` мимо приложения, миграцией — метку не двигает, но следующий слепок
+перекроет её сам, пока заказ в окне изменяемости. За окном источник заказ
+больше не показывает, и там помогает только сверка самих полей, в терминах
+dbt snapshots — стратегия `check` вместо `timestamp`.
+
 Обычное чтение `_dist` показывает физически сохранившиеся версии и нужно для
 диагностики. Их число зависит от фоновых слияний: ODS не служит архивом истории.
 `ods.order_v` сохраняет те же источник-ориентированные поля без обогащения
@@ -112,8 +139,9 @@ JSON-объектом с точным набором ключей: `order_id`, `
 
 Это представление остаётся ответственностью ODS: оно скрывает механику чтения
 версий, но не строит бизнес-модель. DDS читает `ods.order_v` и отдельно решает,
-какие сущности, связи и производные признаки ему нужны. Нужен ли `_load_id`
+какие сущности, связи и производные признаки ему нужны. Судьба служебных
-выше ODS, решается вместе с DDS, а не здесь.
+колонок выше ODS решена вместе с моделью DDS: чужие ярлыки туда не переезжают
+([модель заказа](../dds/order.md)).
 
 ## Одно чтение Kafka
 
@@ -178,6 +206,21 @@ JSON-объектом с точным набором ключей: `order_id`, `
 `20260608-0007`, который прежде приходил с отрицательным итогом, теперь
 `5490.00 − 823.50 + 299.00 = 4965.50`.
 
+При исполнении #124 21 августа 2026 года адресная пересборка мира прошла через
+`SQLExecuteQueryOperator`: `pull_batch` и `parse_batch` завершились успешно. В
+`system.query_log` на первой ноде осталось ровно по одному завершённому запросу
+пользователя `etl` для забора в STG, записи годных строк и записи брака.
+
+Дисциплина источника замерена 22 августа 2026 года при исполнении #137.
+Во всех 3034 парах строк с равным `updated_at` деловые поля совпали
+побайтово, а по слепкам метка ни разу не убывала.
+
+Текущее состояние проверено на пересобранном мире 26 августа 2026 года при
+исполнении #165. После двух слепков физическая таблица содержала 3356 версий
+1917 заказов. У всех строк `ods.order_v` дата слепка совпала с последним
+слепком заказа; деловые поля совпали с эталоном `argMax` по `updated_at` из
+сырья. В обеих сверках расхождений нет.
+
 Забор из Kafka в STG снят на живом стенде 18 августа 2026 года при исполнении
 #93: одно прямое чтение приносит весь слепок дня, метаданные доставки доступны,
 офсеты коммитятся, а сбой забора не двигает позицию мира. Числа — [ADR

docs/architecture/orders/inventory.md

@@ -16,11 +16,11 @@
   артефакт мира. Побайтовое обещание («слепок переснимается и даёт те же
   байты») опись начинает сторожить.
 - **Счётчики классов расхождений — наблюдаемых, после приоритета**, по
-  итоговой судьбе заказов дня; единица счёта — заказ, и опись называет её
+  итоговой судьбе заказов дня. В строке закрытого дня поле `orders` хранит
-  словом. Сойтись с запросом менти они могут только на днях с закрытым окном:
+  число заказов каждого класса; пока окно открыто, поля нет. При N сыгранных
-  при N сыгранных днях таких N − 7 (день d закрывается слепком d + 6, а
+  днях закрыты N − 7 (день d закрывается слепком d + 6, а последний
-  последний отправленный слепок несёт день N − 2). Читатель у них придёт
+  отправленный слепок несёт день N − 2). Их читатель — техническая
-  этапом 4 — проверка сверки; не окажется читателя — та же бритва режет и их.
+  проверка `classes_vs_inventory` из DQ-звена этапа 4.
 - **Контрольные числа идентичности не заводятся вовсе**: uniq известных
   пользователей и число двухкуковых пар растут, пока мир едет, — опоры из них
   не выходит; генератор сторожит хеш, транспорт — счёт событий.

docs/architecture/orders/snapshot.md

@@ -18,9 +18,10 @@
   в трекере — не отдельная порода, а класс B, и делает его событийная сторона
   выбрасыванием события после присвоения номера
   ([классы расхождений](fate.md));
-- номер заказа общий у обеих проекций: `order_id` = клиентский `purchaseID`,
+- обе проекции используют один номер заказа: `order_id` = клиентский
-  читаемый номер «день и порядковый номер покупки» ([спека
+  `purchaseID`;
-  генератора](../../specs/2026-08-01-generator.md), раздел 9); нумеруются все
+  читаемый номер «день и порядковый номер покупки» описан в
+  [ADR 0017](../../adr/0017-order-numbering.md); нумеруются все
   покупки, дошедшие до потока дня, — до всяких потерь;
 - скидка заказа выводится из промокода события по таблице «код → скидка» —
   числу мира, которое этап 3 берёт готовым (спека генератора, разделы 8 и 9).
@@ -59,12 +60,14 @@
 топик льёт даг* — второй путь доставки и второй сериализатор; *слепок едет
 топиком `hits`* — убивает два режима приёма.
 
-**Сборка окна.** Слепок дня D несёт заказы, рождённые в дни D−6…D, и
+**Сборка окна.** Слепок дня D берет заказы, рожденные в дни D−6…D, а несет из
-собирается переигровкой этих семи дней: заказы дня — производная всей воронки
+них те, что уже попали в выгрузку: механика опоздания живет в
-дня, дешёвого пути к ним нет. Цена — семь проигрышей дня (~14 с) на слепок; у
+[судьбе заказа](fate.md). Окно собирается переигровкой этих семи дней: заказы
-начала оси окно усекается само. Отклонено: *кэш заказов на томе* — состояние
+дня — производная всей воронки дня, дешёвого пути к ним нет. Цена — семь
-между прогонами; *окно держит хранилище* — топик перестаёт нести слепок;
+проигрышей дня (~14 с) на слепок; у начала оси окно усекается само. Отклонено:
-*K = 1* — это страховочный срез 1 мастер-спеки, он в резерве.
+*кэш заказов на томе* — состояние между прогонами; *окно держит хранилище* —
+топик перестаёт нести слепок; *K = 1* — это страховочный срез 1 мастер-спеки,
+он в резерве.
 
 **Отправка.** Слепок **снимается на границе суток, а отправляется следующим
 прогоном**: даг, играющий день D, отправляет слепок дня D−1 — ночная выгрузка

docs/architecture/orders/start-world.md

@@ -6,13 +6,14 @@
 Генератор играет два источника с разными темпами — поток Метрики и ночную
 выгрузку магазина; разные темпы дают всё остальное.
 
-`world-init` играет восемь дней одним прогоном `batch --day 0 --days 8`;
+Даг `world_initialize` играет восемь дней одним прогоном
-слепки отправляет второй запуск — команда `snapshot` того же диапазона (два
+`batch --day 0 --days 8`; слепки отправляет второй запуск — команда `snapshot`
-источника — два запуска, [слепок и его доставка](snapshot.md)), и со сдвигом
+того же диапазона (два источника — два запуска,
-отправки уезжают **слепки дней 0…6**. Слепок дня 7 снят на границе суток и
+[слепок и его доставка](snapshot.md)). Со сдвигом отправки уезжают **слепки
-уедет первым же ходом мира. Особого режима у стартового мира нет: правило
+дней 0…6**, затем даг `orders_ingest` принимает их в хранилище. Слепок дня 7
-отправки живёт в одном месте — в проигрывателе; генератору это решение не
+снят на границе суток и уедет первым же ходом мира. Особого режима у стартового
-стоит ничего.
+мира нет: правило отправки живёт в одном месте — в проигрывателе; генератору
+это решение не стоит ничего.
 
 Что видно снаружи: у последнего прожитого дня клики есть, а заказов нет;
 глубже — день 0 виден дожившим до конца окна, день 6 — только что родившимся.

docs/architecture/storage.md

@@ -6,7 +6,7 @@
 раздел «Что проверено» — чему в этом тексте верить и на каком основании.
 
 **Что здесь описано и чего ещё нет.** Собран этап 1: кластер из двух шардов,
-keeper, Kafka, каркас сервисов. Этап 2 идёт: в `sql/ddl/` лежит вся цепочка
+keeper, Kafka, каркас сервисов. Этап 2 собран: в `sql/ddl/` лежит вся цепочка
 `Kafka → STG → ODS` — чтец топика `hits`, таблицы сырья, типизированное
 событие с таблицей ошибок, поверхность актуального состояния и три матвью.
 Этап 3 добавил вход второго источника и довёл его до ODS: топик `orders`, свой
@@ -14,7 +14,11 @@ keeper, Kafka, каркас сервисов. Этап 2 идёт: в `sql/ddl/`
 состояния. Наполняет всю цепочку даг `orders_ingest` двумя шагами, а не матвью.
 Тот же этап принёс первый справочник — словарь товаров из общего с генератором
 CSV-файла. Живёт он вне цепочки слоёв, в зоне `dic`, и читает не файл, а
-подложку над ним ([ADR 0012](../adr/0012-dictionary-home.md)).
+подложку над ним ([ADR 0012](../adr/0012-dictionary-home.md)). Этап 4 начат
+публичным договором события `dds.event_v` над точным состоянием ODS, а следом
+получил две физические модели слоя — заказ и сессию: их собирает заменой
+партиций даг `dds_transform`. Сессия среди них особая: в потоке такой сущности
+нет, стенд режет её из событий сам.
 Дальше по тексту устройство описано так, как оно проектируется; построенное от
 заложенного отличает карта таблиц в конце.
 
@@ -36,7 +40,7 @@ CSV-файла. Живёт он вне цепочки слоёв, в зоне `d
 | `_kafka` | таблица на движке `Kafka` |
 | `_file` | таблица на движке `File` — чтец файла |
 | `_mv` | материализованное представление |
-| `_v` | обычное представление |
+| `_v` | обычное представление, публичная поверхность чтения |
 
 Суффикс носит каждый физический объект. Голого имени у таблицы не существует:
 запрос к `stg.hits_raw` даёт громкую ошибку «нет такой таблицы» — а под голым
@@ -63,6 +67,24 @@ CSV-файла. Живёт он вне цепочки слоёв, в зоне `d
 `order`, `session`. Граница между «как привезли» и «что это такое»
 проходит по STG, и имена её показывают.
 
+В DDS публичный договор сущности заканчивается на `_v`. Потребительские запросы
+и витрины называют только представление; `_rep` и `_dist` служат загрузке,
+диагностике и обслуживанию. Представление перечисляет колонки явно, даже если
+его запрос — простая проекция над `_dist`: договор не выдаёт устройство
+кластера и случайно добавленные в физическую таблицу колонки. У события
+физической копии в DDS нет, но правило то же: `dds.event_v` — его публичный
+договор.
+
+Право доступа здесь намеренно шире договора. Роль `bi_reader` может читать
+любые объекты ODS, DDS и DM, но физические объекты от этого не становятся
+публичной поверхностью. Конвенцию держат явный список колонок, документация и
+ревью, а не запрет на физические таблицы.
+
+Широкое право принято в [ADR 0007](../adr/0007-clickhouse-access.md): узкая
+граница поверх `Distributed` потребовала бы отдельной механики. Механизм
+ClickHouse и отклонённые варианты записаны в
+[исследовании](../research/2026-08-25-clickhouse-distributed-view-security.md).
+
 ## Раскладка по шардам
 
 Пишем только в `_dist`. Локальные таблицы остаются для чтения и обслуживания —
@@ -84,12 +106,24 @@ CSV-файла. Живёт он вне цепочки слоёв, в зоне `d
 Пошардовые счётчики STG и ODS поэтому не сходятся и сходиться не должны —
 сверять слои можно только через `_dist`.
 
+Разные ключи у слоёв ставят капкан на вставке `INSERT INTO цель_dist SELECT …
+FROM источник_dist`. Заводское значение `parallel_distributed_insert_select` —
+2: если обе таблицы на одном кластере, вставка исполняется локально на каждом
+шарде, минуя ключ шардирования цели. Строки наследуют раскладку источника, и
+ошибки при этом нет — расхождение видно только пересчётом ключей по
+`hostName()`. Так половина заказов и легла на оба шарда, где
+`ReplacingMergeTree` через границу шарда дубли не схлопывает (замер — «Что
+проверено», #137). Лекарство — явное `parallel_distributed_insert_select = 0`
+в `SETTINGS` такой вставки: раскладку делает инициатор, по ключу цели
+(`sql/ods/order_parse.sql`). Капкан ждёт и сборки DDS: они тоже будут читать
+`_dist` и писать в `_dist` с другим ключом.
+
 Ключи ко-локации названы заранее, потому что на них стоит политика соединений из
 раздела 6 спеки: обычное соединение разрешено только по ключу ко-локации, всё
-прочее — через `GLOBAL`. Значит `dds.session` и `dds.identity_map` шардируются по
+прочее — через `GLOBAL`. Значит `dds.session_dist` и `dds.identity_map_dist`
-`cityHash64(ClientID)`. Объекты DDS с зерном заказа должны сохранять ко-локацию
+шардируются по `cityHash64(client_id)`. Объекты DDS с зерном заказа сохраняют
-по `cityHash64(order_id)`; ключи остальных частей будущей модели и витрин
+ко-локацию по `cityHash64(order_id)`; ключи остальных частей модели и витрин
-появятся вместе с ними.
+появляются вместе с ними.
 
 Замена партиций не используется для `ods.order`: версии прошлых дней
 доливаются, а прямое чтение Kafka не задаёт границы полного слепка ([ADR
@@ -98,6 +132,14 @@ CSV-файла. Живёт он вне цепочки слоёв, в зоне `d
 разложена по шардам по тому же ключу. Форму донора следует решать вместе с таким
 объектом, а не переносить на ODS заранее.
 
+Первым такой донор понадобился заказу DDS, и правило на нём видно целиком:
+`dds.order_stage_rep` объявлен через `AS dds.order_rep` и шардируется тем же
+`cityHash64(order_id)`. Совпадение структуры требует сама операция, а совпадение
+ключа — устройство замены: она идёт по локальным таблицам, шард за шардом, и
+строка, попавшая в доноре не на свой шард, при подмене пропала бы с одного шарда
+и задвоилась на другом. Доводы целиком — в
+[`sql/ddl/45-dds-tables.sql`](../../sql/ddl/45-dds-tables.sql).
+
 ## Служебные колонки
 
 Собственные колонки не повторяют имён виртуальных. Виртуальные даёт движок:
@@ -141,8 +183,8 @@ kafka_offset)`: разбор полётов идёт от «какое сооб
 заказов — пакетным шагом. Дальше метка переносится в ODS как есть и отвечает на
 вопрос «когда строка приехала в хранилище», а не «когда её разобрали». В
 `ods.event` она же служит колонкой версии `ReplacingMergeTree` и схлопывает
-повтор доставки. У `ods.order` версию задаёт `updated_at` источника;
+повтор доставки. У `ods.order` версию задаёт `snapshot_date` — дата слепка
-`_load_ts` только показывает, когда конкретная строка приехала.
+источника; `_load_ts` только показывает, когда конкретная строка приехала.
 
 `created_at` и `updated_at` заказа к служебным колонкам хранилища не относятся.
 Они приезжают в сообщении как аудит строки в БД источника и в ODS разбираются в
@@ -175,14 +217,21 @@ ODS и в таблицу ошибок. Нужен ли он выше ODS, реш
 
 `ods.event_v` — обычное представление над `ods.event_dist FINAL`. Оно сохраняет
 имена, типы и зерно события, но всегда возвращает актуальную версию. Актуальное
-состояние читают через него, а не повторяют `FINAL` в каждом запросе. Будущее
+состояние читают через него, а не повторяют `FINAL` в каждом запросе.
-`dds.event_v` отвечает за другое: даёт событию язык бизнес-модели, в том числе
+`dds.event_v` отвечает за другое: даёт событию язык бизнес-модели, в том
-snake_case-имена и расшифровку кодов.
+числе snake_case-имена и расшифровку кодов.
+
+Типы ODS обычно повторяют контракт выгрузки. Денежный `purchaseRevenue` —
+исключение: источник объявляет `Array(Float64)`, а материализованное
+представление ODS разбирает числа сырого JSON сразу в
+`Array(Decimal(18, 2))`. DDS наследует этот тип без нового преобразования.
+Прямой разбор подтвержден документацией ClickHouse через Context7 и запросом
+к ClickHouse 26.3; сравнение с сырьем подтвердило: копейки всех покупок целы.
 
 ## Версии заказов
 
 `ods.order_rep` хранит принятые версии в
-`ReplacingMergeTree(updated_at)`: ключ сортировки — `order_id`, партиция —
+`ReplacingMergeTree(snapshot_date)`: ключ сортировки — `order_id`, партиция —
 `toDate(created_at)`. `ods.order_dist` шардирует по
 `cityHash64(order_id)`. Все версии заказа лежат в одной партиции, чтобы их могли
 схлопывать фоновые слияния, и на одном шарде, чтобы распределённый `FINAL`
@@ -192,10 +241,13 @@ snake_case-имена и расшифровку кодов.
 версии, которые ещё не убрали фоновые слияния, и не является архивом истории.
 `ods.order_v` служит поверхностью точного текущего состояния для следующих
 слоёв. Представление сохраняет язык источника и не решает, какой станет модель
-DDS. `snapshot_date` в нём остаётся датой наблюдения строки, а не ключом
+DDS. `snapshot_date` в нём одновременно дата наблюдения и колонка версии. Она
-публикации. Полное решение — в
+не доказывает полноту принятой порции, поэтому ODS не публикует партиции по
-[ADR 0010](../adr/0010-order-versions-in-ods.md) и
+дате слепка. Модель версионного ODS записана в
-[спецификации приёма заказов](orders/ingestion.md).
+[ADR 0010](../adr/0010-order-versions-in-ods.md), выбор колонки версии описан в
+[ADR 0014](../adr/0014-order-version-snapshot-date.md), пакетный приём описан в
+[спецификации приёма заказов](orders/ingestion.md). Контракт следующего слоя
+задан в [модели заказа в DDS](dds/order.md).
 
 ## Часовые пояса
 
@@ -244,7 +296,7 @@ UTC+4), и пересчёт идёт один раз при наполнении
 **День берётся из `EventDate`.** Дата в поясе счётчика уже посчитана
 генератором и лежит колонкой, так что суточные срезы группируются по ней и
 пояса не упоминают вовсе. Почему у ночных событий `toDate(UTCEventTime)` с ней
-расходится — [спека генератора](../specs/2026-08-01-generator.md), раздел 9.
+расходится, объясняет [ADR 0015](../adr/0015-counter-timezone.md).
 
 ## Путь реплицированных таблиц в keeper
 
@@ -438,9 +490,9 @@ kafka_offset)`: смотрят такую таблицу от класса, а
 административная операция, роль `etl` права на неё не получает.
 
 Деньги каталога живут в трёх единицах: в CSV — целые копейки, словарь отдаёт
-`Decimal(18, 2)`, `productPrice` события — целые рубли. Разрыв намеренный, на
+`Decimal(18, 2)`, `productPrice` события — целые рубли. Поэтому точную сумму
-нём стоит урок про `Float64` ([описание
+заказа берут из `purchaseRevenue`, а не складывают округленные цены товаров
-выгрузки](../formats/clickstream-event.md)).
+([описание выгрузки](../formats/clickstream-event.md)).
 
 Устройство обоих объектов — почему такой движок, такая форма пути, такой
 пользователь и такое окно — расписано в
@@ -450,21 +502,23 @@ kafka_offset)`: смотрят такую таблицу от класса, а
 
 Исполняемые дагами запросы лежат по правилу
 `sql/<слой>/<объект>_<роль>.sql`. Слой — слой цели запроса: забор заказов в
-сырьё живёт в `sql/stg/orders_raw_load.sql`, две ветви разбора — в `sql/ods/`.
+сырьё живёт в `sql/stg/orders_raw_load.sql`, разбор — в
-Даг называет файлы, передаёт параметры и задаёт порядок выполнения, но не
+`sql/ods/order_parse.sql`. Даг называет файлы, передаёт параметры и задаёт
-хранит текст преобразований. Общий фрагмент начинается с подчёркивания: файл
+порядок выполнения, но не хранит текст преобразований. Два выражения разбора
-`sql/ods/_order_wire_contract.sql` сам не исполняется, его включают обе ветви
+делят локальный макрос Jinja в том же файле; подключаемого SQL-фрагмента между
-разбора.
+ними нет.
 
-Airflow читает и собирает эти файлы штатным шаблонизатором при исполнении
+SQL-файлы исполняет штатный `SQLExecuteQueryOperator`. При разборе Python-кода
-задачи. Каталог `sql/` смонтирован во все его службы только для чтения. Поэтому
+обработчик DAG читает список DDL-файлов, загружает содержимое каждого
-обработчик дагов не зависит от наличия SQL на машине при разборе Python, а
+названного SQL-файла и кладёт его в сериализованный граф. При исполнении Airflow
-планировщик видит те же файлы при исполнении задачи.
+разворачивает в этом тексте Jinja; параметры ClickHouse передаются отдельно и
+не подставляются строкой. Каталог `sql/` смонтирован во все службы Airflow
+только для чтения.
 
 ### DDL
 
-Файлы лежат в `sql/ddl/` и применяются по порядку имён. Сначала все статичные
+Файлы лежат в `sql/ddl/` и применяются по порядку имён: источник и цель
-объекты, потом матвью — тогда к моменту создания матвью её цель уже существует.
+создаются до представления или матвью, которые их используют.
 
 | Файл | Что в нём |
 |---|---|
@@ -474,54 +528,52 @@ Airflow читает и собирает эти файлы штатным шаб
 | `20-ods-tables.sql` | типизированное событие, версии заказа и обе таблицы ошибок |
 | `30-ods-views.sql` | актуальные события, текущие заказы и матвью разбора в ODS |
 | `40-stg-views.sql` | матвью приёма: чтец в сырьё |
+| `45-dds-tables.sql` | физические модели заказа, сессии и карты идентичностей, доноры партиций |
+| `50-dds-views.sql` | публичные договоры сущностей DDS |
+| `55-dm-tables.sql` | физические витрины выручки, сверки и трафика, доноры дневных партиций |
+| `60-dm-views.sql` | публичные договоры витрин DM |
 
 Справочники идут сразу за базами: зона `dic` не зависит ни от одного слоя, и
 правила порядка слоёв к ней не применяются.
 
 Порядок остальных задают два правила. Первое: матвью принадлежит слою своей
-цели, а не источника, — разбор из STG в ODS лежит среди файлов ODS, потому что
+цели, а не источника, — разбор из STG в ODS лежит среди файлов ODS, потому
-наполняет ODS. Второе: матвью приёма создаётся последней из всех, и потому нарушает
+что наполняет ODS. Второе: последней среди матвью цепочки Kafka создаётся
-нумерацию слоёв. Kafka-движок начинает читать топик ровно тогда, когда к нему
+матвью приёма, и потому она нарушает нумерацию слоёв. Kafka-движок начинает
-привязывают первую матвью; создай её раньше разбора — и всё, что доедет в
+читать топик, когда к нему привязывают первую матвью; создай её раньше
-зазоре, ляжет в сырьё и не попадёт в ODS никуда, ни в событие, ни в ошибки. На
+разбора — и всё, что доедет в зазоре, ляжет в сырьё и не попадёт в ODS
-пустом топике зазор безвреден, поэтому первый прогон о нём не скажет. Проснётся
+никуда, ни в событие, ни в ошибки. На пустом топике зазор безвреден,
-он, когда тома ClickHouse снесены, а данные Kafka целы, — то есть на обычной
+поэтому первый прогон о нём не скажет. Проснётся он, когда тома ClickHouse
-отладке.
+снесены, а данные Kafka целы, — то есть на обычной отладке.
 
-Применение — двумя одноразовыми сервисами при `make up`, по образцу уже
+Файлы применяет даг `world_initialize` с ноды 1 отдельной учётной записью
-работающих `airflow-init` и `superset-init`. Сначала `kafka-init` создаёт топики
+`lifecycle`: один файл — одна последовательная задача
-— `hits` с двумя партициями и `orders` с одной ([ADR
+`SQLExecuteQueryOperator`, а выражения внутри разделяет сам оператор. Всё
-0008](../adr/0008-order-ingestion.md)), — затем `clickhouse-init` дожидается его
+`ON CLUSTER`, кроме чтеца заказов — он объявлен только на этой ноде. Перед DDL
-завершения и применяет файлы с ноды 1: всё `ON CLUSTER`, кроме чтеца заказов —
+даг создаёт `hits` с двумя партициями и `orders` с одной
-он объявлен только на этой ноде. Порядок страхует `hits` от автосоздания с
+([ADR 0008](../adr/0008-order-ingestion.md)). Этот порядок не даёт `hits`
-одной партицией. Переключателей тут два, и путать их не надо: брокер
+автоматически создаться с одной партицией. Брокер автосоздание разрешает, а
-автосоздание разрешает, а потребитель librdkafka внутри ClickHouse его не
+потребитель librdkafka внутри ClickHouse его не просит. Оба конца измерены;
-просит — оба конца измерены, см. «Что проверено». То есть стенд держится на
+результаты приведены в разделе «Что проверено». Успех дага означает больше,
-умолчании клиента, а урок «обе ноды читают топик» умирает тихо, поэтому топик и
+чем применённый DDL: оба стартовых
-создаётся явно, до применения DDL.
+источника приняты, а позиция мира установлена последней задачей. Полный граф и
+состояния отказа описаны в [спеке жизненного цикла](../specs/2026-08-21-world-lifecycle.md).
 
-Образцы копируются не целиком, и в двух местах. `clickhouse-init` обязан ждать
+Повторный `make up` поверх готового мира проходит зелёным без изменений:
-готовности **обеих** нод: `ON CLUSTER` ждёт исполнения на всех хостах и по
+`world_initialize` ветвится раньше DDL. Поэтому изменённый объект обычным
-таймауту бросает, а `airflow-init` ждёт только первую ноду, `superset-init` —
+подъёмом не применяется. В разработке меняют или пересоздают только затронутый
-только вторую. И второе: оба образца переживают `make up --wait` лишь потому, что
+объект, партицию либо базу слоя. Если нужен целиком канонический мир,
-от них зависят долгоживущие сервисы. Что делает `--wait` с одноразовым сервисом
+`make rebuild-storage` запускает `world_recreate`: тот удаляет прикладные базы
-без зависимых, проверено при исполнении #37 на Docker Compose 2.40.3: считает
+`stg`, `dm`, `dds`, `ods`, `dic`, позиции групп потребителей и прикладные топики,
-его упавшим и возвращает единицу, хотя контейнер вышел с нулём. Поэтому
+затем вызывает `world_initialize`. Службы и их тома остаются на месте, а позиция
-зависимые есть и у новой пары: `clickhouse-init` ждёт `kafka-init`, а
+возвращается к концу стартовых дней. Полный `make clean` для изменения DDL не
-`airflow-init` — `clickhouse-init`, и цепочка упирается в долгоживущий Airflow.
+нужен. Когда какая область очистки уместна перед проверкой, задаёт
-Побочная выгода важнее обхода `--wait`: к моменту старта Airflow DDL заведомо
+[карта проверок](testing.md).
-применён.
-
-Повторный `make up` поверх живого тома проходит зелёным: весь DDL идёт через
-`CREATE ... IF NOT EXISTS`. Оборотная сторона — изменённый объект тем же
-запуском не применяется, причём молча. Отдельного механизма для этого нет и не
-нужно: правка существующего DDL случается, только пока стенд пишут, а лекарство
-уже есть — `make clean && make up`. Мир регенерируется, сырьё живёт трое суток,
-терять нечего.
 
 ## Карта таблиц
 
-Ниже — то, что закладывают этапы 2 и 3; всё перечисленное лежит в `sql/ddl/`.
+Ниже — объекты, уже построенные этапами 2–4; всё перечисленное лежит в
+`sql/ddl/`.
 
 | База | Объект | Что это |
 |---|---|---|
@@ -537,15 +589,37 @@ Airflow читает и собирает эти файлы штатным шаб
 | `ods` | `ods.order_rep` / `_dist` | типизированные версии заказа |
 | `ods` | `ods.order_v` | текущая версия заказа на языке источника |
 | `ods` | `ods.order_errors_rep` / `_dist` | строки слепка, не прошедшие строгий приём |
+| `dds` | `dds.event_v` | событие на языке бизнес-модели без физической копии |
+| `dds` | `dds.order_rep` / `_dist` | заказ в текущем состоянии, партиция — день заказа |
+| `dds` | `dds.order_stage_rep` / `_dist` | двойник заказа: в нём день собирается перед заменой партиции |
+| `dds` | `dds.order_v` | публичный договор заказа |
+| `dds` | `dds.session_rep` / `_dist` | визит, нарезанный слоем; партиция — день сессии |
+| `dds` | `dds.session_stage_rep` / `_dist` | двойник сессии: в нём день собирается перед заменой партиции |
+| `dds` | `dds.session_v` | публичный договор сессии |
+| `dds` | `dds.identity_map_rep` / `_dist` | известная пара куки с пользователем; таблицы полного пересчёта |
+| `dds` | `dds.identity_map_v` | точный публичный договор карты идентичностей с `FINAL` |
+| `dm` | `dm.revenue_daily_rep` / `_dist` | дневная выручка по категориям |
+| `dm` | `dm.revenue_daily_stage_rep` / `_dist` | таблица-двойник, донор дневных партиций выручки |
+| `dm` | `dm.revenue_daily_v` | публичный договор дневной выручки |
+| `dm` | `dm.purchase_vs_orders_rep` / `_dist` | сверка покупок с заказами, партиция — день заказа |
+| `dm` | `dm.purchase_vs_orders_stage_rep` / `_dist` | донор дневных партиций сверки |
+| `dm` | `dm.purchase_vs_orders_v` | публичный договор сверки с `NULL` для отсутствующей стороны |
+| `dm` | `dm.daily_traffic_rep` / `_dist` | версии дневных счетчиков трафика |
+| `dm` | `dm.daily_traffic_v` | точные текущие счетчики трафика с `FINAL` |
+| `dm` | `dm.dq_summary_rep` / `_dist` | текущее качество дня по атомарным проверкам |
+| `dm` | `dm.dq_summary_stage_rep` / `_dist` | общий донор дневных партиций DQ-сводки |
+| `dm` | `dm.dq_summary_v` | публичная сводка качества дней |
 | `dic` | `dic.products_file` | чтец CSV-каталога, общего с генератором |
 | `dic` | `dic.products` | словарь товаров поверх подложки |
 
 Матвью разбора у заказов нет: срез сырья раскладывают по этим двум целям два
-`INSERT SELECT` шага `parse_batch` из файлов `sql/ods/order_load.sql` и
+`INSERT SELECT` одной задачи `parse_batch` из файла
-`sql/ods/order_errors_load.sql`.
+`sql/ods/order_parse.sql`.
 
-Слой DDS и слой DM появляются на следующих этапах; их состав задан разделом
+В слое DDS построены событие, заказ, сессия и карта идентичностей. Событие
-7 мастер-спеки и переносится сюда по мере постройки.
+остаётся представлением над ODS; заказ и сессия гасят повтор заменой партиции;
+карта пишет полный набор пар в версионную таблицу. В DM выручка и сверка
+заменяют партиции изменяемых дней, а трафик пишет полную историю новой версией.
 
 ## Что проверено
 
@@ -578,6 +652,15 @@ DDL-словарь с файловым источником внутри `user_f
 разобрано, почему отказ в праве на движок называет не то право, которого не
 хватает.
 
+**Проверка ко-локации заказов 22 августа 2026 года (#137).** Context7 и
+`system.settings` закреплённого ClickHouse 26.3 назвали одну и ту же тройку
+значений `parallel_distributed_insert_select`: `0` — выключено, `1` — `SELECT`
+на каждом шарде, `2` — `SELECT` и `INSERT` на каждом шарде; заводское — `2`.
+На живых данных видны и дефект, и починка: до правки 1189 из 1662 заказов
+лежали на обоих шардах, после явного нуля и повторного разбора того же
+`_load_id` — ни одного. Вершина версий уцелела: деловые поля `ods.order_v`
+сошлись с эталоном, посчитанным прямо из сырья.
+
 **Проверка версий заказов 18 августа 2026 года (#94).** MCP Context7 подтвердил,
 что `JSONType` возвращает имя типа значения JSON, — на нём стоит проверка типов
 в предикате приёма заказов. Остальное снято на закреплённом ClickHouse 26.3.
@@ -609,8 +692,8 @@ DDL-словарь с файловым источником внутри `user_f
 порции из пяти строк (две версии одного заказа плюс по одной строке каждого
 класса брака) годные ушли в `ods.order`, брак — в `ods.order_errors` с
 ожидаемыми классами. Обе версии легли в одну партицию и на один шард; `FINAL`
-через распределённую таблицу вернул одну строку — ту, у которой `updated_at`
+через распределённую таблицу вернул одну строку — ту, что несла позднейшую
-позже, — тогда как физический счёт показывал две. Повтор задачи с тем же
+версию, — тогда как физический счёт показывал две. Повтор задачи с тем же
 `_load_id` строку в `ods.order_v` и её `_load_ts` не изменил, а таблица ошибок
 записала тот же брак второй раз, как и обещано спецификацией приёма.
 
@@ -748,5 +831,41 @@ Kafka с пустым значением (ноль байт) и запись-н
 таблице. Это вычитано, а не измерено. На устройство приёма оговорка не влияет:
 служебные колонки мы заполняем выражением при любом ответе.
 
+**Проверка замены партиций 26 августа 2026 года (#151).** Context7 подтвердил
+договор `REPLACE PARTITION`: `ON CLUSTER` в синтаксисе есть, а источник и цель
+обязаны совпадать структурой, ключом партиции, ключом сортировки, первичным
+ключом и политикой хранения. На закреплённом ClickHouse 26.3 замена по локальным
+таблицам с `ON CLUSTER` прошла на обеих нодах, а сборка стартового мира в
+двойник разложила 1662 заказа строго по ключу: шард 1 получил только чётные
+`cityHash64(order_id)`, шард 2 — только нечётные.
+
+**Проверка карты идентичностей 26 августа 2026 года (#153).** Context7
+подтвердил версию в `ReplacingMergeTree` и точное чтение через `FINAL`. Два
+полных прогона оставили 3180 физических строк и 1590 пар в `_v`; все пары
+подтверждены покупкой и заказом, а строк на чужом шарде нет.
+
+Тем же днём измерены ещё три поведения ClickHouse.
+
+- **Параметр в `ALTER … PARTITION` не подставляется.** Запрос с `{day:Date}` в
+  выражении партиции отвечает кодом 62, синтаксической ошибкой; литерал
+  проходит. Отсюда единственное место в репозитории, где значение попадает в
+  запрос подстановкой Jinja, а не параметром ClickHouse
+  ([`sql/dds/order_replace.sql`](../../sql/dds/order_replace.sql)).
+- **`TRUNCATE` — отдельное право, в `ALTER` оно не входит.** Роль `etl`, у
+  которой есть `ALTER ON dds.*`, получает на `TRUNCATE` код 497, а
+  `ALTER TABLE … DROP PARTITION ALL` на той же таблице проходит. Двойник
+  поэтому чистится снятием партиций: у операции нашлась форма, на которую право
+  уже выдано, и расширять доступ не понадобилось.
+- **`JSONExtract` читает `Decimal` прямо из строки JSON.** Цена на проводе —
+  строка с двумя знаками (`"1289.99"`), и разбор в
+  `Array(Tuple(sku String, qty UInt32, price Decimal(18, 2)))` даёт число без
+  промежуточного `toDecimal64`. Проверено на живом слепке; честность разбора
+  сторожит инвариант бэкенда — сумма «цена × количество» совпала с `items_total`
+  у всех 1662 заказов.
+- **`JSONExtract` читает `Decimal` и из числа JSON.** Массив
+  `purchaseRevenue`, объявленный источником как `Array(Float64)`, разбирается
+  сразу в `Array(Decimal(18, 2))`. Синтаксис подтвержден через Context7 и на
+  ClickHouse 26.3; все суммы после ODS совпали с сырьем до копейки.
+
 **Сказано по памяти, проверки нет.** Группа пуста: оба утверждения, ждавшие
 матвью разбора, закрыты опытами при исполнении #43 и переехали выше.

docs/architecture/superset.md

@@ -0,0 +1,165 @@
+# Superset: витрины глазами
+
+Документ описывает зону BI: куда Superset ходит за данными и за своими
+метаданными, из чего собран стендовый дашборд, как снять свежий экспорт после
+правки в интерфейсе и почему правка руками живет только до перезапуска.
+
+Состав сюжетов и колонок витрин здесь не повторяется: он живет в
+[спеке](../specs/2026-07-30-stand-v2-realism.md), раздел 7, и в
+[доке слоя DM](dm.md).
+
+## Устройство зоны
+
+Superset читает ClickHouse пользователем `bi` **на ноде 2** — так задано
+подключением `ClickHouse` (`clickhousedb://bi@clickhouse-02:8123`). Нода 2
+здесь — ловушка правильных ошибок из
+[спеки](../specs/2026-07-30-stand-v2-realism.md), раздел «Роли нод»: DDL идет
+с ноды 1, и забытый `ON CLUSTER` виден в дашборде.
+
+Пароля в подключении нет. Его отдает штатное хранилище паролей Superset
+(`SQLALCHEMY_CUSTOM_PASSWORD_STORE` в `infra/superset/superset_config.py`),
+которое читает `CLICKHOUSE_BI_PASSWORD` из окружения. Поэтому файл подключения
+безопасно лежит в git, и экспорт из интерфейса не должен возвращать пароль
+обратно в YAML.
+
+Свои метаданные — подключения, датасеты, графики, дашборды, пользователи —
+Superset держит в базе `superset` служебного `postgres-metadata`, рядом с базой
+Airflow. В ClickHouse он не пишет ничего.
+
+## Дерево импорта
+
+`infra/superset/import/` — это дашборд стенда в виде файлов. Каталог
+смонтирован в контейнер как `/app/import`.
+
+| Файл | Что описывает |
+|---|---|
+| `metadata.yaml` | версия формата, `1.0.0`; больше в нем ничего нет |
+| `databases/clickhouse.yaml` | подключение к ClickHouse: URI без пароля и постоянный uuid |
+| `datasets/ClickHouse/*.yaml` | три витрины: `revenue_daily_v`, `purchase_vs_orders_v`, `daily_traffic_v` |
+| `charts/*.yaml` | три графика: столбики выручки, сводная таблица сверки, линии трафика |
+| `dashboards/business_stories.yaml` | дашборд «Бизнес-сюжеты» и раскладка панелей |
+
+Связаны файлы не путями, а uuid. Датасет называет `database_uuid`, график —
+`dataset_uuid`, а дашборд не называет графики вовсе: единственная связь с ними
+лежит в его `position`, где узел `CHART-*` несет `meta.uuid` нужного графика.
+График, которого нет в `position`, импортируется молча и не появляется нигде.
+
+Uuid у стенда розданы рукой: общее начало
+`19600000-0000-4000-8000-`, дальше номер объекта в последнем блоке — `1`–`3`
+у датасетов, `101`–`103` у графиков, `201` у дашборда
+(`…-000000000101`). Экспорт из интерфейса приносит свои, сгенерированные;
+их заменяют на эти, иначе повторный импорт заведет вторую копию объекта вместо
+обновления первой.
+
+Датасет несет русские имена колонок, формат денег и метрику — а график только
+ссылается на них по имени. Значит, подпись или формат правятся в одном месте, а
+не в каждом графике.
+
+Датасеты объявлены физическими (`schema: dm`, `sql: null`), хотя за именем стоит
+представление ClickHouse. Импорт в источник не ходит и разницы между таблицей и
+представлением не знает, а виртуальный датасет со своим SQL просто повторил бы
+запрос, который уже живет в `sql/ddl/60-dm-views.sql`.
+
+## Импорт при каждой инициализации
+
+Последняя строка `infra/superset/init.sh`:
+
+```
+superset import-directory /app/import --overwrite
+```
+
+Служба `superset-init` отрабатывает перед подъемом самого Superset, то есть при
+каждом `make up`. Без `--overwrite` второй прогон падал бы на первом же
+знакомом uuid; с ним объект обновляется на месте, и повторная инициализация
+проходит без ошибок.
+
+Отсюда правило зоны: **стендовый дашборд не расширяют руками в интерфейсе.**
+Правка живет до следующей инициализации, а потом молча заменяется тем, что
+лежит в git. Пробовать интерфейс менти никто не мешает — но все, что должно
+пережить перезапуск, приезжает файлом.
+
+Это правило относится только к стендовым объектам. Свои датасеты, графики и
+дашборды менти живут в той же базе метаданных Superset, а импорт трогает
+только объекты с известными ему uuid. Поэтому свои объекты переживают
+`make up` и `make rebuild-storage`. Их стирает только `make clean` или
+адресный сброс базы метаданных по рецепту ниже.
+
+## Как снять свежий экспорт
+
+Маршрут один: правишь на живом стенде, забираешь экспорт, кладешь дерево в git.
+
+1. Собрать или поправить график и дашборд в интерфейсе — на стенде, а не в
+   файлах. Ключи `params` графиков велики, недокументированы и меняются от
+   версии к версии; неверный ключ не ошибается, а рисует пустоту. Интерфейс
+   здесь единственный надежный оракул.
+2. Снять экспорт и достать его из контейнера:
+
+   ```
+   docker compose exec superset superset export-dashboards -f /tmp/export.zip
+   docker compose cp superset:/tmp/export.zip /tmp/export.zip
+   unzip -d /tmp/superset-export /tmp/export.zip
+   ```
+
+   Внутри архива — один каталог `dashboard_export_<дата>` ровно той же формы,
+   что и дерево импорта. Команда выгружает все дашборды сразу; на стенде он
+   один.
+3. Вычистить экспортный сор перед коммитом:
+   - выбросить экспортный `databases/` — наш `clickhouse.yaml` остается как
+     есть, с постоянным uuid и без пароля;
+   - оставить в `metadata.yaml` одну строку `version: 1.0.0`;
+   - убрать из графиков `params.datasource`, `params.slice_id` и
+     `params.dashboards` — это идентификаторы строк того Superset, где
+     снимали, а импорт выводит связи из uuid;
+   - убрать `query_context` — снимок запроса оттуда же. Импорт его не
+     требует и обратно не заполняет: после переимпорта он остается пустым, на
+     отрисовку это не влияет;
+   - перезаписать русские строки читаемыми. Экспорт кодирует их
+     `\uXXXX`-последовательностями, и после каждого круга их приходится
+     раскодировать заново: имена графиков и подписи колонок читает менти, и в
+     файле, и в диффе. Годится любой повторный дамп YAML с
+     `allow_unicode=True`;
+   - вернуть постоянные uuid из схемы выше.
+4. Скопировать вычищенное дерево в `infra/superset/import/` и проверить
+   импортом **на пустых метаданных** — иначе прогон проверит только обновление
+   уже стоящих объектов, а молчаливый пропуск нового спрячется за старым.
+   Активы Superset лежат в базе `superset` службы `postgres-metadata`, поэтому
+   адресный сброс — эта база:
+
+   ```
+   docker compose stop superset
+   docker compose exec postgres-metadata sh -c \
+     'psql -U "$POSTGRES_USER" -d postgres \
+        -c "DROP DATABASE superset WITH (FORCE)" \
+        -c "CREATE DATABASE superset OWNER \"$SUPERSET_METADATA_USER\""'
+   docker compose run --rm superset-init
+   docker compose up -d superset
+   ```
+
+   Базу приходится создавать тут же: скрипт `infra/postgres/init/` заводит ее
+   один раз, при первой инициализации тома Postgres. `make rebuild-storage`
+   для этой проверки не годится — он гоняет `world_recreate` в ClickHouse и
+   метаданных Superset не касается. `make clean` сбросит и их, но заодно снесет
+   весь стенд, включая метаданные Airflow в той же службе.
+
+   После импорта дашборд смотрят глазами: это единственное доказательство —
+   см. ловушку ниже.
+
+## Ловушки
+
+**Импорт молчит.** График, чей `dataset_uuid` не разрешился, отбрасывается без
+единого слова; дашборд, у которого не сошлись ссылки на графики,
+пропускается. Ошибки уходят в журнал, и `init.sh`
+завершается нулем в любом случае. Поэтому импорт проверяют глазами или
+запросом к API — но не тем, что команда отработала.
+
+**`--overwrite` синхронизирует датасет разрушительно.** Колонки и метрики
+берутся из YAML целиком: добавленная в интерфейсе метрика или подпись колонки
+исчезнет при следующем старте контейнера. Правка датасета — это правка файла.
+
+## Что проверяет стенд
+
+`make check-services` входит в Superset, находит подключение `ClickHouse`,
+сверяет его uuid и безопасный URI и требует схему `dm` — то есть подтверждает
+живое подключение и хранилище пароля. Сами графики и дашборд ни одна цель не
+проверяет: их смотрят глазами после переинициализации. Полная карта целей — в
+[доке проверок](testing.md).

docs/architecture/testing.md

@@ -34,20 +34,21 @@
 спрашивают его отдельно.
 
 Стенд нужен трём целям из восьми. Цена — замер, см. «Что проверено».
-`make config-test`, `make smoke` и `make check-services` перемерены 21 августа
+`make smoke` и `make check-services` перемерены 28 августа 2026 года,
-2026 года, `make check-clickhouse` — 19 августа, корневой `make lint` —
+`make config-test` — 21 августа, `make check-clickhouse` — 19 августа,
-9 августа, `make test` — 7 августа; остальные стоят с замера 6 августа.
+корневой `make lint` — 9 августа, `make test` — 30 августа; остальные стоят с
+замера 6 августа.
 
 | Цель | Откуда | Что утверждает | Стенд | Цена |
 |---|---|---|---|---|
 | `make config-test` | корень | Compose разбирается, файлы DAG и дашборды Grafana синтаксически целы, в diff нет пробельных ошибок. О работоспособности не говорит ничего | не нужен | 1 с |
 | `make lint` | корень | Код стенда — `dags/` и `infra/superset/` — отформатирован и проходит ruff | не нужен | 0,4 с |
-| `make smoke` | корень | Стенд **собран**: службы живы, порты отвечают, подключения настроены друг на друга. Вширь и по касательной к каждой службе. Единственная цель, которая здесь правда смоук | нужен | 17 с |
+| `make smoke` | корень | Стенд **собран**: службы живы, порты отвечают, подключения настроены друг на друга. Вширь и по касательной к каждой службе. Единственная цель, которая здесь правда смоук | нужен | 25 с |
 | `make check-clickhouse` | корень | Всё, что спрашивают **у ClickHouse** и он отвечает сам: макросы, шарды, реплики, путь в keeper, ключ шардирования, очередь распределённых DDL, ответ словаря товаров, счёт событий стартового мира против описи | нужен | 24 с |
-| `make check-services` | корень | **Службы работают**: DAG запускается и доходит, топик создаётся и удаляется, Superset логинится и ходит в базу | нужен | 93 с |
+| `make check-services` | корень | **Службы работают**: DAG запускается и доходит, топик создаётся и удаляется, Superset логинится и ходит в базу | нужен | 71 с |
 | `make lint` | `generator/` | Код генератора отформатирован и проходит ruff | не нужен | 0,4 с |
 | `make typecheck` | `generator/` | Типы генератора сходятся (ty) | не нужен | 0,5 с |
-| `make test` | `generator/` | Генератор делает то, что обещает; схема события остаётся объявленным контрактом, а собранные из кода [описание выгрузки](../formats/clickstream-event.md) и [опись мира](../../data/world-inventory.json) — свежими | не нужен | 71 с |
+| `make test` | `generator/` | Генератор делает то, что обещает; схема события остаётся объявленным контрактом, а собранные из кода [описание выгрузки](../formats/clickstream-event.md) и [опись мира](../../data/world-inventory.json) — свежими | не нужен | 176,5 с |
 
 **Строк с именем `make lint` две, и это не опечатка.** Одноимённые цели за
 разными дверями охватывают разное: корневая не видит ни одного файла
@@ -71,9 +72,15 @@
 тогда окружение окупится, и условие возврата — именно это, а не «стало
 неудобно».
 
-Цена самого `make up` — 8 м 18 с с нуля и 3 м 35 с на живом стенде. В цену
+Цена самого `make up` с пустых томов — 8 м 18 с до переезда жизненного цикла в
-целей она не входит, но записана здесь по той же причине: подъём пересчитывает
+Airflow. В цену целей она не входит. На готовом мире подъём больше не
-оба источника стартового мира и ждёт их приёма.
+пересчитывает данные: `world_initialize` зеленеет без изменений.
+
+`make rebuild-storage` тоже не проверка. Команда через Airflow удаляет
+прикладные базы ClickHouse, топики и позиции групп Kafka, заново применяет DDL,
+заливает стартовый мир и возвращает его пульт к концу стартовых дней. Службы и
+их тома она сохраняет, поэтому возврат к каноническим данным не требует
+холодного запуска всего стенда.
 
 ## Правило: смоук обязан оставаться быстрым
 
@@ -96,20 +103,29 @@ ClickHouse отвечает сразу.
 Деление целей ценно ровно до тех пор, пока оно не превратилось в «гонять
 всегда всё».
 
+Состояние перед проверкой восстанавливается в самой узкой достаточной области:
+сначала объект или партиция, затем база слоя. Если нужен целиком чистый
+прикладной мир, `make rebuild-storage` пересобирает его базы, топики, позиции
+потребителей и данные. `make clean` нужен, только когда меняется или сломано
+постоянное состояние вне этих баз либо проверяется сам запуск с пустых томов.
+Требование к обоснованию полного сброса задаёт `AGENTS.md`. Неизвестную поломку
+сначала исследуют: полный сброс уничтожает её следы.
+
 | Когда | Что гонять |
 |---|---|
 | Правка в работе | `make config-test` и `make smoke` |
 | PR или задача | плюс цели, которых правка касалась: DAG-и, Superset или Kafka — `check-services`; DDL, кластер или данные — `check-clickhouse` |
-| Приёмка этапа | `make up` с нуля и все три цели на стенде |
+| Приёмка этапа | все три цели на стенде; запуск с пустых томов — только для изменений начальной сборки или постоянного состояния служб |
 
 Правки генератора добавляют к этому `make lint`, `make typecheck` и `make test`
 из каталога `generator/`: стенд им не нужен, а `make test` из них самая
 дорогая. Правки дагов и Superset — корневой `make lint`.
 
-Тринадцать секунд из её семидесяти одной — пересборка восьми модельных дней
+Двадцать секунд из ее ста семидесяти шести — пересборка восьми модельных дней
-для сверки с описью мира. Дешевле хеши не сравнить: чтобы узнать, тот ли
+для сверки с описью мира (20,5 с из 176,5). Дешевле хеши не сравнить: чтобы
-получается мир, его надо получить. Место выбрано по той же оси «кого
+узнать, тот ли получается мир, его надо получить. Место выбрано по той же
-спрашивают» — вопрос обращён к коду генератора, стенд ему не нужен, — и
+оси «кого спрашивают» — вопрос обращён к коду генератора, стенд ему не
+нужен, — и
 краснеет проверка там, где надо: сразу после правки генератора. Не будь её,
 расхождение всплыло бы получасом позже, на поднятом стенде, где выглядит
 поломкой хранилища, а не забытой пересборкой.
@@ -194,12 +210,14 @@ Kafka → STG → ODS, и живёт он в `make check-clickhouse`.
 | `make check-services` | `scripts/stand-services.sh` |
 | `make check-clickhouse` | `scripts/check-clickhouse.sh` |
 
-Особняком — два сценария продолжения `make up`, оба не проверки.
+Особняком стоит `scripts/run-dag.sh`: это не проверка, а общий REST-переход от
-`scripts/wait-for-world.sh` ждёт, пока события доедут из Kafka в ODS:
+`make` к Airflow. `make up` запускает через него `world_initialize`, а
-`docker compose up --wait` видит конец отправки, но приём идёт асинхронно.
+`make rebuild-storage` — `world_recreate`; сценарий ждёт появления дага в API,
-Затем `scripts/ingest-starting-orders.sh` разово запускает единственный даг
+а затем до минуты повторяет только стартовый ответ `Dag with dag_id not found`.
-приёма заказов `orders_ingest` и ждёт его конца. Оба ждут ограниченным циклом,
+Прочие ответы и сетевые ошибки он не повторяет: при потерянном ответе запуск мог
-а не паузой наугад.
+уже создаться. Сценарий печатает идентификаторы дага и прогона и возвращает
+вызывающему его итог. Ожидание доставки событий и запуск `orders_ingest` теперь
+видны задачами `world_initialize`, а не спрятаны в shell.
 
 Общее у смоука и `check-services` — счёт проверок, обращение к Compose и две
 проверки — вынесено в `scripts/stand-common.sh`; сам он не запускается.
@@ -221,15 +239,183 @@ Kafka → STG → ODS, и живёт он в `make check-clickhouse`.
 
 ## Что проверено
 
+**Калибровка заказной стороны 30 августа 2026 года при исполнении #194.**
+Пересборки эталонного мира не будет (#192), поэтому доли заказной стороны
+сверены замером внутренностей генератора — окно 28 модельных дней,
+канонический seed, без транспорта, — тем же приемом, каким `test_plan.py` и
+`test_commerce.py` меряют мир. Команда (из `generator/`):
+
+```bash
+uv run python - <<'PY'
+from collections import Counter
+from clickstream_generator import day, inventory, orders, world
+from clickstream_generator.seeds import CANONICAL_SEED
+
+WINDOW = 28
+class_totals: Counter[str] = Counter()
+outcome_totals: Counter[int] = Counter()
+delivery_totals: Counter[int] = Counter()
+delay_totals: Counter[int] = Counter()
+total_orders = 0
+
+for d in range(WINDOW):
+    today = day.stream(CANONICAL_SEED, d)
+    for key, value in inventory._order_class_counts(today).items():
+        class_totals[key] += value
+    money = today.orders
+    total_orders += len(money)
+    for value in money.outcome.tolist():
+        outcome_totals[value] += 1
+    for value in money.delivery.tolist():
+        delivery_totals[value] += 1
+    for value in money.snapshot_delay.tolist():
+        delay_totals[value] += 1
+
+print(total_orders, dict(class_totals), dict(outcome_totals),
+      dict(delivery_totals), dict(delay_totals))
+PY
+```
+
+6973 заказов за 28 дней. Доли из таблицы сверки (после приоритета классов):
+отменено 5,15% (ориентир мастер-спеки ~5%, в пределах; из них 3,03%
+оплачен-потом-отменен и 2,12% отменен неоплаченным — веса `world.py`
+95/3/2); дубль `purchase` 1,89% (ориентир ~2%, в пределах); дельта суммы
+1,32% (ориентир 1–2%, в пределах); потеря `purchase` 1,78% при броске 3% —
+вычеты штатные: назначенные планом покупки из броска исключены (мост
+склейки), часть случаев уходит в отмену приоритетом; наблюдаемая доля
+принята решением владельца (#194). Стоимость доставки — 35,5% / 49,2%
+/ 15,4%, совпадает с весами `DELIVERY_KOPECKS_WEIGHTS`. Опоздание слепков
+(`ORDER_SNAPSHOT_DELAY_WEIGHTS`) — доля заказов с δ>0 составила 8,39%
+(ориентир мастер-спеки ~10%, в пределах). Скрипт замера в репозиторий не
+входит; вывод — в отчете issue #194.
+
+**Перезамер 30 августа 2026 года при исполнении #192.** Команды запускались
+из `generator/`:
+
+```bash
+time make inventory
+uv run python -m clickstream_generator batch --day 0 --days 8 \
+  --file /tmp/stage7-events.jsonl
+for snapshot_day in 1 2 3 4 5 6 7; do
+  uv run python -m clickstream_generator snapshot --day "$snapshot_day" \
+    --file "/tmp/stage7-snapshot-${snapshot_day}.jsonl"
+done
+wc -c /tmp/stage7-events.jsonl /tmp/stage7-snapshot-{1,2,3,4,5,6,7}.jsonl
+time make test
+```
+
+Опись пересобралась за 20,515 с. Файловый приемник записал 460 731 812 байт:
+458 478 771 байт событий и 2 253 041 байт слепков. `make test` прошел 437/0
+за 176,476 с. Прежние 71 с (7 августа, #42) выросли по двум причинам: тестов
+стало 437 против 407, и потяжелел сам мир — та же пересборка восьми дней
+стоила 13 с, теперь 20,5. Эта правка добавила один тест — проигрыш дня.
+
+**Приемка #172 28 августа 2026 года.** Холодный `create_app()` занимал
+28,3-28,4 секунды, а чтение подключения после запуска - 0,07 секунды. Предел
+30 секунд почти целиком уходил на запуск второго приложения. Увеличивать его
+не стали: Superset не обещает постоянного времени `create_app()`.
+
+После входа проверка делает три GET-запроса к уже работающему Superset: находит
+`ClickHouse`, сверяет UUID и безопасный URI, затем требует схему `dm`. Так без
+второго запуска проверяются сохраненное подключение и хранилище пароля. Форму
+API сверили через Context7 и с исходным кодом Superset 6.1.0. `superset test-db`
+отклонен, потому что тоже запускает приложение; прямой SQL к `dbs` не проверяет
+соединение.
+
+Проверка больше не подтверждает, что сам Superset использует Postgres для
+метаданных. Короткий запрос к Postgres показывает лишь готовность базы, а REST
+API - подключение к ClickHouse. Для `check-services` этого достаточно.
+
+После перезапуска Superset три прогона прошли 7/7 за 71, 67 и 70 секунд.
+`make config-test` прошел. `make smoke` дал 21/21 за 25 секунд; его код не
+менялся, прежний замер был 17 секунд. Неверный UUID дал 5/1: красной стала
+только проверка метаданных, пароль в вывод не попал.
+
+**Приемка #156 27 августа 2026 года.** `make rebuild-storage` занял 7 минут.
+На чистом прикладном мире `world_initialize` сам довел позицию до `8`, дождался
+`etl_pipeline` и оставил заполненными DDS и обе витрины. После пересборки прошли
+`make smoke` 21/21 и `make check-clickhouse` 10/10. Перед стендовыми сценариями
+прошли `make config-test` и `make lint`.
+
+Два прогона `world_next_day` не изменили слои; один ручной `etl_pipeline` без
+параметров догнал оба дня. Полный прогон `world_live_day` занял 27 м 2 с и
+завершился только после успешных DDS и DM.
+
+Временная синтаксическая поломка `sql/dm/daily_traffic_rebuild.sql` дала
+красную цепочку: DDS завершился успешно, а `daily_traffic`, DM, `etl_pipeline`
+и `world_live_day` покраснели. После возврата исправного SQL ручной
+`etl_pipeline` без параметров завершился успешно на позиции `12` и восстановил
+слои.
+
+Для проверки пакетного барьера `stg.hits_raw_mv` временно отсоединили командой
+`DETACH` на обеих нодах. После `world_next_day` отставание Kafka составило
+46 367 (19 128 + 27 239). Во время ожидания матвью вернули командой `ATTACH`.
+Журнал готовности записал повторные опросы с отставанием 46 367, затем 27 239
+и 0; после этого очередь `ods.event_dist` содержала 0 файлов на обеих нодах,
+и ETL завершился успешно. Проверка `EXISTS` снова дала `1` на обеих нодах,
+позиция равна `13`.
+
+После пересборки `make check-services` дважды дал 5/1: только импорт Superset
+не уложился в существующий тайм-аут 30 с. Диагностический пробник импорта с
+ожиданием 90 с прошел 3/0. Финальный штатный повтор прошел 7/7 за 129 с.
+
+**Перезамер 21 августа 2026 года при исполнении #124.** Образ Airflow собран с
+`apache-airflow-providers-clickhousedb==1.0.0`,
+`apache-airflow-providers-common-sql==2.0.1` и
+`clickhouse-connect==1.6.0`; `pip check` не нашёл несовместимых зависимостей.
+Адресная пересборка мира через `make rebuild-storage` заняла 3 м 5 с: все шесть
+задач DDL, `pull_batch` и `parse_batch` завершились успешно. После неё прошли
+смоук 21/21 за 17 с, проверка ClickHouse 10/10 и межсервисная проверка 7/7 за
+100 с.
+
+Первый `make up` после замены образа попал в короткий рассинхрон запуска
+Airflow: API уже сообщил о здоровье и отдал `world_initialize` по GET, но POST
+нового запуска ещё ответил `Dag with dag_id not found`. Ошибок импорта не было;
+через несколько секунд повторный `make up` завершился успешно и не менял
+готовый мир.
+
 **Перезамер 21 августа 2026 года при исполнении #114.** После добавления
 `kafka-exporter` и источника ClickHouse смоук прошёл 21/21 за 16–17 секунд,
 `check-services` — 7/7 за 93 секунды. При остановленном экспортёре смоук дал
 19/2: назвал нездоровый сервис и отсутствие одной из четырёх целей. После
 возврата сервиса прогон снова дал 21/21.
 
-**Перезамер 20 августа 2026 года при исполнении #96.** `make up` после
+После переноса #119 поверх этого состава повторный `make up` сохранил готовый
-`make clean` прошёл за 8 м 18 с, повтор на живом стенде — за 3 м 35 с. Служба
+мир, смоук прошёл 21/21, проверка ClickHouse — 10/10, межсервисная — 7/7.
-семи слепков заняла около 28 секунд между концом `world-init` и своим концом.
+
+**Приёмка логики #119 до переноса поверх мониторинга 21 августа 2026 года.**
+`make rebuild-storage` через Airflow прошёл за 3 м 9 с: позиция прошла задачи
+`-1` → `0` → `8`, топики получили новые идентификаторы, группы дочитали новые
+топики без отставания, а ODS принял 401 185 событий без брака и 2 851
+актуальный заказ. Задача `build_generator_image` заняла по 1,5 с в двух
+прогонах.
+Повторный `make up` занял 2 м 41 с вместе со штатным повторным запуском служб
+инициализации; `world_initialize` завершился за один цикл опроса и оставил
+счётчики неизменными. Отдельно проверены красные отказы `world_initialize` при
+`-1` и `world_next_day` при отсутствующей позиции, `0` и `-1`; `lifecycle`
+отказано в чтении `system.users`, но разрешено чтение `system.settings`.
+
+Итоговый холодный `make up` из пустых томов занял 9 м 39 с после 25 с на
+`make clean`. Даг создал отсутствующую позицию и закончил на `8`; ODS снова
+получил 401 185 событий без брака и 2 851 заказ. У `hits` два раздела, у
+`orders` один, отставание обеих групп равно нулю. На тогдашнем составе стенда
+прошли смоук 20/20, проверка ClickHouse 10/10 и межсервисная проверка 7/7.
+
+Оборванную очистку проверили после записи `world_position=-1`: остановили
+первую ноду ClickHouse, и `world_recreate` покраснел на удалении баз. Следующий
+`make up` тоже покраснел и оставил `-1`. После возврата ноды повторный
+`make rebuild-storage` восстановил мир.
+
+**Прототип 21 августа 2026 года при исследовании #110.** Предшествующая
+shell-версия узкой пересборки за 2 м 25 с пересоздала прикладные базы, отправила
+401 185 событий и 6 656 версий заказов и вернула позицию с 11 на 8. Замер
+оставлен как ориентир цены, но не подтверждает нынешнюю реализацию Airflow: тот
+вариант не очищал Kafka и был отклонён как второй оркестратор мира.
+
+**Перезамер 20 августа 2026 года при исполнении #96, до переезда в Airflow.**
+`make up` после `make clean` прошёл за 8 м 18 с, повтор на живом стенде — за
+3 м 35 с. Отправка семи слепков заняла около 28 секунд.
+
 Прежний замер ниже — 2 м 50 с и 1 м 5 с до появления приёма заказов и пульта
 мира. Весь рост приписывать слепкам нельзя: на холодном прогоне основное время
 ушло ещё до сценариев ожидания: `airflow-init` завершился примерно на 320-й

docs/formats/clickstream-event.md

@@ -11,10 +11,12 @@
 по элементу на товар. Отдельной сущности «визит» в выгрузке нет — визиты
 собирают на стороне хранилища, а `VisitID` дан как эталон для самопроверки.
 
-Имена и типы колонок — стороны источника. Хранилище принимает их как есть и
+Имена и типы колонок описывают сторону источника. Обычно ODS принимает их без
-нормализует у себя: то же имя в нашем стиле ждёт в столбце «Нормализованное
+изменений. Исключение — `purchaseRevenue`: источник объявляет Float64, а ODS
-имя». Это имя источника, приведённое к snake_case, а не имя атрибута в
+хранит деньги в Decimal. Точный локальный тип назван в документации
-модели данных: слой DDS складывает свою модель и называет атрибуты по ней.
+хранилища. Имя в нашем стиле ждет в столбце «Нормализованное имя». Это имя
+источника, приведенное к snake_case, а не имя атрибута в модели данных: слой
+DDS складывает свою модель и называет атрибуты по ней.
 Столбец «Тип numpy» показывает, чем колонка представлена внутри генератора;
 у массивов это тип элемента. Номер — место колонки в выгрузке: порядок задан
 контрактом.
@@ -90,7 +92,7 @@
 | № | Колонка | Тип ClickHouse | Тип numpy | Нормализованное имя | Комментарий |
 |---|---|---|---|---|---|
 | 37 | `purchaseID` | `Array(String)` | `object` | `purchase_id` | номер заказа; у события purchase — один элемент |
-| 38 | `purchaseRevenue` | `Array(Float64)` | `float64` | `purchase_revenue` | выручка заказа глазами клиента; Float64, как у Метрики — на этом держится урок о расхождениях с бэкендом |
+| 38 | `purchaseRevenue` | `Array(Float64)` | `float64` | `purchase_revenue` | выручка заказа глазами клиента; источник объявляет Float64, ODS хранит точный Decimal |
 | 39 | `purchaseCurrency` | `Array(String)` | `object` | `purchase_currency` | валюта заказа |
 | 40 | `purchaseCoupon` | `Array(String)` | `object` | `purchase_coupon` | купон заказа, если был применён |
 | 41 | `productID` | `Array(String)` | `object` | `product_id` | id товаров события |

docs/labs/README.md

@@ -0,0 +1,109 @@
+# Учебные задания: витрины слоя DM и дашборд в Superset
+
+Пять домашних заданий — про витрины слоя DM. Стенд привозит слой
+наполовину: витрины трех сюжетов дашборда и контроль качества построены,
+остальные витрины строит менти. Каждое из них — самостоятельное ТЗ: что за
+витрина, какое у нее зерно, из чего она собирается и как проверить, что
+собралась верно.
+
+Шестое задание — необязательная лаба в Superset. В ней менти собирает свой
+дашборд поверх пяти витрин.
+
+Общее устройство слоя — [дока DM](../architecture/dm.md). Она отвечает на
+вопросы «почему так», задание отвечает на вопрос «что сделать».
+
+## Порядок
+
+Задания идут по нарастанию: каждое следующее опирается на то, что уже
+усвоено.
+
+| № | Результат | Чему учит |
+|---|---|---|
+| 1 | [`events_enriched_v`](events-enriched.md) | слой — это контракт, а не копия данных |
+| 2 | [`top_pages_daily`](top-pages-daily.md) | зерно сменилось — витрина материализуется и встает в конвейер |
+| 3 | [`session_overview`](session-overview.md) | зерно решает, на какие вопросы витрина уже не ответит |
+| 4 | [`dq_errors_daily`](dq-errors-daily.md) | у брака свой день и свой срок жизни |
+| 5 | [`utm_effectiveness`](utm-effectiveness.md) | `declared_` в имени — предупреждение, а не украшение |
+| 6 | [Свой дашборд в Superset](superset-dashboard.md) — необязательная лаба | свои объекты BI живут отдельно от стендовых |
+
+## Общие правила
+
+Они одни для пяти заданий по витринам, поэтому записаны здесь, а не
+повторяются в каждом ТЗ.
+
+**Читать — через `_v`.** Публичный договор сущности DDS — представление с
+суффиксом `_v`: `dds.event_v`, `dds.session_v`. Витрина называет только
+его; физические `_rep` и `_dist` служат загрузке и обслуживанию. Соседнюю
+домашку витрина источником тоже не берет: витрина слоя DM читает договор
+DDS, и задания остаются независимыми. Исключение одно и оно оговорено в
+задании 4: у таблиц брака публичного договора нет.
+
+**Писать — только в `_dist`.** При записи в локальную таблицу раскладку
+определяет то, какая нода случайно выполняла код, а не свойство данных.
+Правило и его следствия — [дока хранилища](../architecture/storage.md),
+«Раскладка по шардам».
+
+**Форма — по зерну.** Витрина, меняющая зерно источника, материализуется:
+`dm.<имя>_rep` / `_dist`, донор `dm.<имя>_stage_rep` / `_stage_dist` и
+публичное `dm.<имя>_v` с явным списком колонок. Витрина, сохраняющая зерно,
+остается обычным представлением. Довод — [дока DM](../architecture/dm.md),
+«Форма: по зерну, не по цене запроса».
+
+**Ключ шардирования — твое решение.** Ни одно ТЗ ключа не называет.
+Правило выбора и требование к донору — [дока
+хранилища](../architecture/storage.md), «Раскладка по шардам»: донор
+объявляется через `AS <цель>_rep` и шардируется тем же ключом, что цель,
+иначе замена партиции потеряет строку на одном шарде и задвоит на другом.
+Названный ключ надо уметь защитить: почему он не дает перекоса и почему
+более сложный тут ничего не добавляет. Образец такой защиты —
+`dm.revenue_daily_dist` в [`sql/ddl/55-dm-tables.sql`](../../sql/ddl/55-dm-tables.sql).
+
+**Где лежит код.** DDL домашек — свой файл `sql/ddl/70-labs.sql`: он
+применяется после стендовых по порядку имени, и твои объекты не мешаются
+со стендовыми. У агрегатов рядом со стендовыми ложатся еще три запроса —
+`sql/dm/<витрина>_scope.sql` спрашивает у хранилища, какие дни пересобирает
+запуск, `_rebuild.sql` собирает их в донор, `_replace.sql` заменяет
+партицию, — и задача в
+[`dags/dm_transform.py`](../../dags/dm_transform.py). У разминочного
+представления нет ничего из этого: весь его код — одно `CREATE VIEW`.
+
+**Образец на все случаи** — витрина `revenue_daily`: у нее есть все пять
+объектов, донор, сборка, замена дневных партиций и задача в конвейере.
+Списывать с нее устройство можно и нужно; списывать состав колонок — нет,
+он у каждой витрины свой.
+
+## Самопроверка
+
+Даг `homework_check` запускается рукой, расписания у него нет. Задача
+витрины красная, пока витрины нет или счет не сходится, и зеленая, когда
+собрано верно. В сводку качества конвейера `dm.dq_summary` он не пишет:
+это инструмент лабы, а не история качества стенда.
+
+Проверка пяти заданий по витринам устроена одинаково и золотых констант не
+содержит: рядом с витриной независимым запросом собирается тот же ответ —
+прямо из источника витрины, минуя ее саму. У четырех заданий источник эталона
+тот же, что у витрины, `dds.session_v` или `dds.event_v`; у задания 4 это
+таблицы брака ODS, потому что в DDS у брака представительства нет. Обе стороны
+соединяются по деловому ключу через `FULL OUTER JOIN`, и считается число строк,
+где стороны разошлись или одной стороны нет. Ноль — зеленый.
+Полное соединение здесь обязательно: при обычном пропавший день или
+пропавший ключ просто не попал бы в результат и остался бы незамечен.
+
+Раздел «Как проверить себя» каждого ТЗ по витрине называет деловой ключ и
+сравниваемые величины. Тот же прием в стендовом исполнении — [даг
+`dq_check`](../../dags/dq_check.py) и запросы в [`sql/dq/`](../../sql/dq).
+
+**Предупреждение.** Запросы самой проверки лежат в `sql/dq/` открыто, и
+имена называют витрину и роль сверки. Проверка на инвариантах неизбежно
+близка к ответу: чтобы сверить витрину, надо ее пересчитать. Прятать эти
+файлы никто не станет — но открыв их до того, как задание сделано, ты
+обменяешь урок на готовый SQL.
+Смотреть туда стоит после своей сборки: сравнить два решения полезно,
+списать одно — нет.
+
+## Уборка
+
+Черновики и опыты за собой сносить: правило проверок стенда —
+[дока тестирования](../architecture/testing.md). Снесенная витрина обязана
+снова покраснить свою задачу в `homework_check` — если не покраснила,
+проверка ничего и не проверяла.

docs/labs/dq-errors-daily.md

@@ -0,0 +1,118 @@
+# Задание 4: `dm.dq_errors_daily`
+
+**Чему учит:** у брака свой день и свой срок жизни. Витрина качества живет
+по времени загрузки, а не по модельному дню, и переживает собственный
+источник — поэтому «пересобрать все» здесь означает «стереть историю».
+
+## Роль витрины
+
+Сводка приемки: сколько строк за день не прошли разбор и по какой причине.
+Читают ее, когда качество потока просело: сначала смотрят, вырос ли класс
+брака, потом идут за сырым текстом в саму таблицу ошибок.
+
+Витрина отвечает на вопрос «сколько и чего», а не «что именно сломалось».
+Разбирательство с конкретной строкой начинается в `ods.event_errors_dist` и
+`ods.order_errors_dist`, где рядом с классом лежат сырой текст и координаты
+доставки.
+
+## Источник: единственное исключение из правила `_v`
+
+Общее правило домашек — читать через публичный договор `_v`. У таблиц брака
+такого договора нет, и заводить его ради этой витрины не надо: брак — не
+сущность бизнес-модели, а диагностика слоя приема. Читать нужно
+распределенные таблицы напрямую:
+
+- `ods.event_errors_dist` — брак разбора событий;
+- `ods.order_errors_dist` — брак разбора слепка заказов.
+
+Именно `_dist`, а не `_rep`: локальная таблица вернет строки одного шарда, и
+витрина тихо покажет половину брака. Ошибки при этом не будет — ошибка
+появится позже, когда по витрине примут решение.
+
+## Зерно и форма
+
+Зерно — **день загрузки × источник × класс брака**. Зерно источника —
+строка брака, значит зерно сменилось и витрина материализуется:
+`dm.dq_errors_daily_rep` / `_dist`, донор `_stage_rep` / `_stage_dist`,
+публичное `dm.dq_errors_daily_v`. Ключ партиции — день загрузки.
+
+День здесь — `toDate(_load_ts)`, то есть настоящее время, когда строка
+приехала в хранилище, а не модельный день мира. Модельного дня у брака нет
+и быть не может: он живет в содержимом, а содержимое как раз и не
+разобралось.
+
+## Состав колонок
+
+| Колонка | Тип | Что это |
+|---|---|---|
+| `load_date` | `Date` | день загрузки, в который приехал брак |
+| `source` | `LowCardinality(String)` | `event` или `order` |
+| `error_class` | `LowCardinality(String)` | класс брака из таблицы ошибок |
+| `error_rows` | `UInt64` | число забракованных строк |
+| `_load_id` | `String` | запуск, собравший день |
+| `_load_ts` | `DateTime64(3, 'UTC')` | когда собран |
+
+Две похожие колонки рядом различаются намеренно: `load_date` — про день,
+когда приехал брак, `_load_ts` — про запуск, который собрал витрину. Первая
+деловая, вторая служебная, и совпадать они не обязаны.
+
+Классы у двух источников свои и не пересекаются по смыслу, поэтому колонка
+`source` в зерне обязательна: без нее одинаковое имя класса у событий и у
+заказов слилось бы в одну строку.
+
+## Ритм пересборки: витрина переживает источник
+
+Таблицы брака живут месяц (`TTL`), сырье — трое суток. Витрина живет без
+срока: сводка «сколько брака было в марте» нужна и после того, как сами
+строки марта удалены.
+
+Отсюда правило прогона: пересобираются **только те дни загрузки, которые
+еще есть в источнике**. Спроси у источника список живых дней и замени
+партиции ровно этих дней. Соблазн «собрать все заново в донор и подменить
+таблицу целиком» здесь стоит дороже обычного: истекшие по `TTL` дни исчезли
+бы из витрины навсегда, а вместе с ними — единственная оставшаяся память о
+них.
+
+Текущий день загрузки не замерзает до конца суток: поток событий идет, и
+брак в него еще добавится. Это нормально, день просто пересоберется на
+следующем прогоне.
+
+## Ключ шардирования
+
+Твое решение по [правилу донора](../architecture/storage.md), «Раскладка по
+шардам». Витрина крошечная: классов брака у событий и заказов вместе меньше
+десятка. Учти это в защите ключа — иногда правильный ответ звучит как
+«перекос здесь ничего не стоит, и вот почему».
+
+## Как проверить себя
+
+Деловой ключ — пара `source` и `error_class` внутри `load_date`. Область
+проверки — дни загрузки, которые еще живы хотя бы в одной таблице ошибок:
+день за границей `TTL` сверять не с чем, и его отсутствие в источнике не
+ошибка.
+
+Собери прямой счет по обеим таблицам ошибок, соедини с
+`dm.dq_errors_daily_v` полным внешним соединением по ключу и посчитай
+строки, где ключа нет с одной из сторон или где расходится `error_rows`.
+Ноль — зеленый.
+
+Отдельно: сумма `error_rows` по живым дням равна общему числу строк в
+`ods.event_errors_dist` плюс `ods.order_errors_dist`. Если эта сумма вышла
+примерно вдвое меньше — витрина почти наверняка собрана с `_rep` вместо
+`_dist` и видит один шард из двух.
+
+**Пустая витрина — верный ответ.** На чистом стенде брака нет, обе стороны
+пусты, расхождений ноль, задача зеленая. Проверка, которая требует хотя бы
+одной строки, на здоровом стенде краснела бы всегда и приучала бы себя
+игнорировать.
+
+## Приемка
+
+- [ ] пять объектов витрины созданы, донор объявлен через `AS` и шардируется
+      ключом цели;
+- [ ] источники — `_dist`-таблицы обоих видов брака;
+- [ ] прогон заменяет партиции только живых дней источника и не трогает
+      истекшие;
+- [ ] задача `dq_errors_daily` в `homework_check` зеленая — в том числе на
+      чистом стенде, где брака нет;
+- [ ] задача витрины добавлена в `dm_transform`.

docs/labs/events-enriched.md

@@ -0,0 +1,114 @@
+# Задание 1: `dm.events_enriched_v`
+
+**Чему учит:** слой — это контракт, а не копия данных. Витрина, которая не
+меняет зерно источника, остается представлением, и копии событий ради
+других имен колонок не заводит ни один боевой склад.
+
+Это разминка. Строк она не хранит, в конвейер не встает, ключа шардирования
+у нее нет. Задача одна: собрать плоское событие для BI и не поддаться
+соблазну разложить его на диск.
+
+## Роль витрины
+
+Договор события в DDS широкий — 44 колонки, почти весь формат выгрузки:
+часть из них технические координаты источника, часть — параллельные массивы
+товаров. Аналитику в Superset нужен плоский набор деловых полей и пара
+производных, которые иначе каждый пишет заново в каждом запросе.
+
+Витрина отвечает на вопрос «что вообще происходило»: с нее начинают, когда
+надо посмотреть на события глазами человека, а не разбирать широкую строку
+источника.
+
+Источником для витрин следующих заданий она не служит. Витрина слоя DM
+читает публичный договор DDS — так устроены и стендовые витрины, и потому
+задания независимы: соседнюю домашку можно делать первой, а можно не делать
+вовсе.
+
+## Зерно и форма
+
+Зерно — **событие**: одна строка витрины равна одной строке `dds.event_v`.
+Зерно источника сохранено, значит форма — обычное представление
+`CREATE VIEW dm.events_enriched_v`, без физической таблицы, без донора и
+без задачи в `dm_transform`. Пересобирать нечего.
+
+Источник — `dds.event_v`, и только он.
+
+## Состав колонок
+
+Явный список обязателен: договор не должен расширяться сам, когда в
+источник добавят колонку.
+
+**Время и посетитель:** `event_date`, `event_time`, `event_hour`,
+`client_id`, `event_id`.
+
+**Действие:** `event_type` (`pageview`, `add_to_cart`, `purchase`), `url`,
+`page_path`, `referer`, `referer_host`, `title`.
+
+**Атрибуция:** `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`,
+`utm_term`.
+
+**Паспорт визита:** `device_category`, `browser`, `operating_system`,
+`region_country`, `region_city`.
+
+**Торговый блок, массивами как в источнике:** `product_id`, `product_name`,
+`product_category`, `product_price`, `product_quantity`,
+`product_event_type`, `purchase_id`, `purchase_revenue`, `purchase_coupon`.
+
+Три колонки в источнике не лежат и считаются здесь:
+
+| Колонка | Как считается | Зачем |
+|---|---|---|
+| `event_hour` | `toHour(event_time)` | суточный профиль спрашивают в каждом отчете |
+| `page_path` | путь `url` без домена и параметров | группировка по странице без разбора строки в каждом запросе |
+| `referer_host` | домен `referer` | «откуда пришли» одним значением, а не полным адресом |
+
+Служебных `_load_id` и `_load_ts` у витрины нет, и это не забывчивость. Их
+нет и у `dds.event_v`: событие в DDS не грузят, а читают из ODS, поэтому
+координат собственной загрузки у него не бывает. Служебная колонка называет
+запуск, который положил строку на диск, — здесь на диск никто ничего не
+кладет.
+
+## Ловушка задания
+
+Массивы `product_*` тянет развернуть через `ARRAY JOIN` — так плоская
+таблица становится по-настоящему плоской. Разворачивать нельзя, и вреда
+здесь два.
+
+Очевидный: у события с тремя позициями получилось бы три строки, зерно
+витрины перестало бы совпадать с зерном источника, а вместе с ним развалилось
+бы и правило формы — такую витрину уже пришлось бы материализовать.
+
+Неочевидный и куда более разрушительный: `ARRAY JOIN` — соединение
+внутреннее, и строку с пустым массивом он выбрасывает. Торговый блок пуст у
+всех событий, кроме корзин и покупок, то есть у подавляющего большинства.
+Так «плоская таблица событий» превращается в таблицу товарных позиций и
+теряет девятнадцать строк из двадцати — а по имени и по составу колонок она
+по-прежнему выглядит таблицей событий. Ошибка не падает и ничего не
+подсвечивает.
+
+Массивы едут в договор как есть; разворачивает их тот, кому нужна позиция
+заказа, — и делает это уже в своей витрине, с другим зерном и другим именем.
+
+## Как проверить себя
+
+Деловой ключ — `event_id` внутри дня. Собери прямой ответ из `dds.event_v`
+за тот же день, соедини с витриной полным внешним соединением и посчитай
+строки, где ключа нет с одной из сторон или где различаются значения
+деловых колонок. Ноль — зеленый.
+
+Отдельно проверяются три производные колонки: `event_hour`, `page_path` и
+`referer_host` должны совпасть с тем же выражением, посчитанным по
+`dds.event_v` на лету.
+
+Если строк в витрине оказалось в разы меньше, чем в источнике, а остались в
+ней одни корзины и покупки — это развернутые массивы: `ARRAY JOIN` выбросил
+все события с пустым торговым блоком.
+
+## Приемка
+
+- [ ] `dm.events_enriched_v` создано, физических таблиц под ним нет;
+- [ ] список колонок в представлении явный;
+- [ ] число строк и набор `event_id` совпадают с `dds.event_v` за каждый
+      прожитый день;
+- [ ] задача `events_enriched` в `homework_check` зеленая;
+- [ ] задачи в `dm_transform` **нет** — и не должно быть.

docs/labs/session-overview.md

@@ -0,0 +1,121 @@
+# Задание 3: `dm.session_overview`
+
+**Чему учит:** агрегат хранит слагаемые, а не готовые средние и доли.
+Среднее по строкам витрины не складывается никогда, а уникальных нельзя
+складывать даже тогда, когда на сегодняшних данных сумма сходится.
+
+## Роль витрины
+
+Дневной портрет визитов в разрезе устройств: сколько было сессий, какие они
+были длинные, сколько страниц смотрели и как часто доходили до покупки.
+Вопрос витрины — «как люди ходят по магазину с телефона и с настольного
+компьютера, и чем эти визиты отличаются».
+
+Сессия на стенде — расчетная сущность, ее уже нарезал слой DDS. Собирать
+визиты заново из событий не нужно и нельзя: это была бы вторая нарезка,
+которая тихо разойдется с первой.
+
+Витрина с таким именем была и на прошлом стенде, но зерно у нее сменилось,
+и сменилось не по вкусу. Там визитов как сущности не было, и витрина
+нарезала их сама, строкой на визит. Здесь визит — сущность слоя DDS, и
+витрина, повторяющая его зерно, оказалась бы обычным представлением по
+[правилу формы](../architecture/dm.md): копией сессий с другими именами
+колонок. Чтобы задание осталось про дневной агрегат, витрина поднялась на
+зерно выше — до дня и среза.
+
+## Зерно и форма
+
+Зерно — **день сессии × категория устройства**. Источник —
+`dds.session_v`, у него зерно визита, значит зерно сменилось и витрина
+материализуется: `dm.session_overview_rep` / `_dist`, донор `_stage_rep` /
+`_stage_dist`, публичное `dm.session_overview_v`. Ключ партиции — день.
+
+Категория устройства взята из сессии как есть: у куки она постоянна, и слой
+DDS уже перевел код источника в слово. Словарь расшифровки шире, чем мир
+стенда: слов в нем четыре, а встречаются три — `desktop`, `mobile` и
+`tablet`. Строку под `tv` заводить незачем, она возникнет сама, если такие
+визиты появятся.
+
+## Состав колонок
+
+| Колонка | Тип | Что это |
+|---|---|---|
+| `report_date` | `Date` | день сессии |
+| `device_category` | `LowCardinality(String)` | категория устройства |
+| `sessions` | `UInt64` | число визитов |
+| `visitors` | `UInt64` | число разных `client_id` |
+| `bounce_sessions` | `UInt64` | визиты ровно из одного события |
+| `purchase_sessions` | `UInt64` | визиты, в которых была хотя бы одна покупка |
+| `duration_seconds_total` | `UInt64` | суммарная длительность визитов |
+| `events_total` | `UInt64` | событий во всех визитах |
+| `pageviews` | `UInt64` | просмотров страниц |
+| `cart_adds` | `UInt64` | добавлений в корзину |
+| `purchases` | `UInt64` | покупок |
+| `_load_id` | `String` | запуск, собравший день |
+| `_load_ts` | `DateTime64(3, 'UTC')` | когда собран |
+
+Средней длительности и доли отказов в витрине нет намеренно. Хранить
+`avg_duration_seconds` было бы удобнее ровно один раз — пока смотрят одну
+строку. Тот, кто захочет среднее по дню целиком, сложит средние по трем
+устройствам и получит неправду: средние не складываются, они взвешиваются.
+Пара «`duration_seconds_total` и `sessions`» дает верный ответ на любом
+срезе, а деление стоит потребителю один вызов. То же и с долей отказов:
+храним `bounce_sessions` и `sessions`, долю считает тот, кто спрашивает.
+
+С `visitors` история тоньше, и в ней главная ловушка задания. Складывать
+уникальных по строкам нельзя: один и тот же посетитель, попавший в две
+строки, будет посчитан дважды. Проверь на стенде — и увидишь, что сумма
+`visitors` по устройствам за день **сходится** с `dm.daily_traffic_v`.
+
+Это не отменяет правила, а показывает, откуда берется совпадение: в мире
+стенда устройство приписано куке на всю жизнь ([словарь
+понятий](../../CONTEXT.md), «Паспорт куки»), поэтому одна кука лежит ровно
+в одной строке дня, и пересекаться строкам не в чем.
+
+Совпадение это — свойство мира, а не свойство витрины. Появятся визиты
+одной куки с двух устройств — сумма поедет, и ни одна проверка об этом не
+скажет: отчет просто начнет тихо завышать аудиторию. Отсюда правило,
+которое стоит унести с задания: складывать уникальных нельзя даже там, где
+сегодня получается. Число посетителей дня спрашивают у
+`dm.daily_traffic_v`, где оно посчитано на своем зерне.
+
+## Ритм пересборки
+
+Источник — сессии: день замерзает, как только прожит. Объем прогона тот же,
+что в задании 2, — хвост от первого несобранного прожитого дня; механика та
+же: донор и замена дневных партиций.
+
+## Ключ шардирования
+
+Твое решение по [правилу донора](../architecture/storage.md), «Раскладка по
+шардам». Здесь у измерения всего три встречающихся значения, и распределены
+они неровно: планшеты — тонкая полоса, а телефоны и настольные машины держат
+основную массу. Прежде чем брать хеш от одного `device_category`, посчитай,
+сколько строк ляжет на каждый шард, и назови, чем тебя устраивает результат.
+
+## Как проверить себя
+
+Деловой ключ — `device_category` внутри дня. Собери прямой агрегат из
+`dds.session_v` за день, соедини с `dm.session_overview_v` полным внешним
+соединением и посчитай строки, где ключа нет с одной из сторон или где
+расходится любой счетчик. Ноль — зеленый.
+
+Две проверки покрупнее ловят грубую ошибку сразу:
+
+- сумма `sessions` за день равна числу строк `dds.session_v` этого дня:
+  ни один визит не потерян и ни один не задвоен;
+- сумма `events_total` за день равна сумме `events_total` по сессиям того
+  же дня.
+
+Если суммы событий сходятся, а сумма сессий больше числа визитов — почти
+наверняка витрина собрана из событий, а не из сессий.
+
+## Приемка
+
+- [ ] пять объектов витрины созданы, донор объявлен через `AS` и шардируется
+      ключом цели;
+- [ ] `dm.session_overview_v` перечисляет колонки явно;
+- [ ] источник витрины — `dds.session_v`, своей нарезки визитов в ней нет;
+- [ ] средних и долей в физической таблице нет;
+- [ ] задача `session_overview` в `homework_check` зеленая;
+- [ ] задача витрины добавлена в `dm_transform`.

docs/labs/superset-dashboard.md

@@ -0,0 +1,87 @@
+# Задание 6 (необязательное): свой дашборд в Superset
+
+**Чему учит:** довести свои витрины до потребителя — завести в Superset
+датасеты поверх публичных представлений, подобрать графики под вопросы и
+собрать из них один связный экран.
+
+Эта лаба идет после заданий 1–5 и опирается на их результат. Ее можно
+пропустить: основной предмет стенда — ClickHouse, а здесь вся работа — в
+интерфейсе BI.
+
+## Роль дашборда
+
+Собери обзор трафика и поведения посетителей. Он должен отвечать на три
+вопроса: что происходило в магазине, какие страницы, устройства и рекламные
+каналы дали результат, были ли ошибки приема данных.
+
+Стендовый дашборд «Бизнес-сюжеты» собран из готовых витрин. Свой дашборд
+собери из пяти витрин, которые ты построил в заданиях. Копировать раскладку
+стендового дашборда не нужно: выбери форму, в которой ответы читаются без
+пояснений рядом с экраном.
+
+## Свои объекты — отдельно
+
+Не добавляй графики в стендовый дашборд и не правь его датасеты. При
+инициализации Superset импорт с `--overwrite` заменит ручные правки стендовых
+объектов файлами из репозитория. `make up` свой дашборд не стирает; срок жизни
+таких объектов описан в [доке Superset](../architecture/superset.md), «Импорт
+при каждой инициализации».
+
+Заведи отдельные датасеты и графики, собери из них свой дашборд. Назови его,
+например, «Мои витрины DM». Это то же правило, по которому DDL домашек лежит
+в `sql/ddl/70-labs.sql`: стенд привозит свои объекты, менти создает свои.
+
+## Датасеты
+
+Заведи в подключении `ClickHouse` пять физических датасетов схемы `dm`:
+
+- `events_enriched_v`;
+- `top_pages_daily_v`;
+- `session_overview_v`;
+- `dq_errors_daily_v`;
+- `utm_effectiveness_v`.
+
+## Состав дашборда
+
+Каждая из пяти витрин должна появиться хотя бы в одном графике. Точный тип
+графика выбери сам. На дашборде покажи следующее:
+
+| Витрина | Что показать |
+|---|---|
+| `events_enriched_v` | число событий по часу и типу события |
+| `top_pages_daily_v` | страницы с просмотрами, посетителями и добавлениями в корзину |
+| `session_overview_v` | сравнение устройств по визитам, отказам и визитам с покупкой |
+| `dq_errors_daily_v` | число ошибок по дню загрузки, источнику и классу |
+| `utm_effectiveness_v` | трафик, покупки и заявленную выручку по рекламным каналам |
+
+Для долей используй слагаемые из витрин. Например, доля отказов считается
+как сумма `bounce_sessions`, деленная на сумму `sessions`. Среднее по готовым
+долям для такого графика не подходит — урок задания 3 остается в силе.
+
+Названия графиков, осей и показателей должны объяснять экран без чтения SQL.
+
+## Как проверить себя
+
+Эта лаба проверяется глазами. У расположения панелей и понятных подписей нет
+счетного инварианта, поэтому задачи для нее в `homework_check` нет.
+
+Открой список дашбордов и проверь:
+
+- «Бизнес-сюжеты» остался отдельным стендовым дашбордом;
+- твой дашборд открывается без ошибок и содержит график от каждого из пяти
+  датасетов;
+- подписи, единицы измерения и легенды читаются без обращения к SQL;
+- прямой трафик не исчез из графика UTM, а заявленная выручка не выдана за
+  серверную;
+- пустой график ошибок нормален, если в таблицах брака сейчас нет строк.
+
+Последний проход сделай как читатель: найди на экране самый заметный канал,
+страницу и устройство, затем проверь, понятно ли из подписей, что именно
+сравнивается. Если ответ приходится угадывать, поправь график или его название.
+
+## Приемка
+
+- [ ] пять датасетов читают публичные представления витрин заданий 1–5;
+- [ ] создан отдельный дашборд, стендовые объекты не изменены;
+- [ ] каждая витрина представлена хотя бы одним графиком;
+- [ ] дашборд проверен глазами по разделу выше.

docs/labs/top-pages-daily.md

@@ -0,0 +1,114 @@
+# Задание 2: `dm.top_pages_daily`
+
+**Чему учит:** зерно сменилось — значит витрина материализуется, живет
+дневными партициями и встает в конвейер. Первая настоящая витрина: пять
+объектов, донор, замена партиции, задача в `dm_transform`.
+
+## Роль витрины
+
+Популярность страниц по дням: сколько раз страницу открыли, сколько разных
+посетителей ее видели и что на ней делали кроме просмотра.
+
+Торговое событие садится на ту страницу, где случилось: корзина — на
+карточку товара, покупка — на страницу подтверждения заказа. Поэтому у
+карточки товара рядом стоят просмотры и корзины, и их отношение —
+конверсия карточки — главный вопрос к этой витрине: какие товары кладут в
+корзину, едва открыв, а какие смотрят и уходят.
+
+Воронки «просмотр → корзина → покупка» здесь нет и быть не может: корзина и
+покупка живут на разных страницах, и связать их шаги в одну цепочку на
+зерне страницы не из чего. Путь одного человека собирают из событий или из
+сессий, а витрина страниц отвечает про страницу.
+
+## Зерно и форма
+
+Зерно — **день события × страница**. Источник — события, у него зерно
+события, значит зерно сменилось и витрина материализуется:
+`dm.top_pages_daily_rep` / `_dist`, донор `_stage_rep` / `_stage_dist`,
+публичное `dm.top_pages_daily_v`.
+
+Страница — это `page_path`, путь `url` без домена и параметров запроса;
+считается он здесь же, из колонки `url` источника. Полный адрес в зерно не
+берется: с параметрами запроса одна и та же страница рассыпалась бы на
+сотни строк, и витрина перестала бы отвечать на свой вопрос.
+
+Ключ партиции — день: он же единица пересборки.
+
+Источник — `dds.event_v`, публичный договор события. Витрина задания 1
+источником не служит: витрина слоя DM читает договор DDS, как и стендовые
+витрины, и не зависит от того, выполнена ли соседняя домашка.
+
+## Состав колонок
+
+| Колонка | Тип | Что это |
+|---|---|---|
+| `report_date` | `Date` | день события |
+| `page_path` | `LowCardinality(String)` | путь страницы |
+| `pageviews` | `UInt64` | число событий `pageview` на странице |
+| `visitors` | `UInt64` | число разных `client_id` на странице |
+| `cart_adds` | `UInt64` | число событий `add_to_cart` на странице |
+| `purchases` | `UInt64` | число событий `purchase` на странице |
+| `_load_id` | `String` | запуск, собравший день |
+| `_load_ts` | `DateTime64(3, 'UTC')` | когда собран |
+
+Счетчики условные: строку дают все три типа событий, а различает их
+`countIf`. Отфильтровать источник по `event_type = 'pageview'`, как
+подсказывает имя витрины, — значит получить витрину из одних просмотров:
+страницы останутся на месте, а `cart_adds` и `purchases` у всех строк
+обнулятся. Ошибка тихая: витрина выглядит собранной, и главный ее вопрос —
+конверсия карточки — молча отвечает «ноль везде».
+
+## Ритм пересборки
+
+Источник — события: день замерзает сразу, как только прожит. Значит
+пересобирать нужно только то, что еще не собрано: хвост дней, которых в
+витрине нет, — от первого несобранного прожитого дня до последнего
+прожитого. Готовые дни трогать незачем, а вот дыру, оставленную частичным
+отказом, объем прогона обязан подобрать: ищи не последний собранный день, а
+первый несобранный.
+
+Механика — сборка отрезка в донор одной вставкой и замена дневных партиций
+по одной, как у `revenue_daily`.
+
+## Ключ шардирования
+
+Твое решение по [правилу донора](../architecture/storage.md), «Раскладка по
+шардам». Подумай, чем эта витрина отличается от `revenue_daily`: там кроме
+дня было одно измерение из шести близких по объему значений, здесь —
+страницы, которых много и которые по популярности очень неровные.
+
+## Как проверить себя
+
+Деловой ключ — `page_path` внутри дня. Собери прямой агрегат из
+`dds.event_v` за день, соедини с `dm.top_pages_daily_v` полным внешним
+соединением по ключу и посчитай строки, где ключа нет с одной из сторон или
+где расходится любой из четырех счетчиков. Ноль — зеленый.
+
+Две проверки попроще, ими удобно ловить грубую ошибку до полного
+соединения:
+
+- сумма `pageviews` за день равна числу событий `pageview` этого дня в
+  `dds.event_v`;
+- сумма `purchases` за день равна числу событий `purchase` этого дня.
+
+Проверки ловят разное. Фильтр `WHERE event_type = 'pageview'` первая из них
+пропускает: отбор строк по типу не меняет счет событий того же типа.
+Расхождение покажет только вторая — вместе с `cart_adds` обнулятся и
+`purchases`. Проверку выбирают по тому, умеет ли она покраснеть на твоей
+ошибке, а не по тому, как быстро она пишется: [проверка, которая не умеет
+краснеть, бесполезна](../architecture/testing.md).
+
+`visitors` складывать по строкам нельзя: один посетитель ходит по разным
+страницам и в сумме посчитается несколько раз. Число посетителей дня
+спрашивают у `dm.daily_traffic_v`, а не у этой витрины.
+
+## Приемка
+
+- [ ] пять объектов витрины созданы, донор объявлен через `AS` и шардируется
+      ключом цели;
+- [ ] `dm.top_pages_daily_v` перечисляет колонки явно, включая `_load_id` и
+      `_load_ts`;
+- [ ] объем прогона выводится из состояния витрины, а не задается руками;
+- [ ] задача `top_pages_daily` в `homework_check` зеленая;
+- [ ] задача витрины добавлена в `dm_transform`, повторный прогон конвейера
+      результат не меняет.

docs/labs/utm-effectiveness.md

@@ -0,0 +1,150 @@
+# Задание 5: `dm.utm_effectiveness`
+
+**Чему учит:** приставка `declared_` в имени колонки — предупреждение, а не
+украшение. Она говорит: это заявка клиента, а не деньги отчетности. Урок
+здесь дает конфликт: суммы не сойдутся, и раскапывать почему предстоит
+самому.
+
+Правило стенда: **поведение и атрибуцию считаем по трекеру, деньги — по
+бэкенду**. Эта витрина — единственное разрешенное исключение: атрибуции по
+UTM у бэкенда нет, метки живут только в кликстриме. Раз считать иначе
+нечем, клиентская сумма берется, но называется своим именем.
+
+## Роль витрины
+
+Эффективность рекламных каналов по дням: сколько трафика привел канал,
+сколько корзин и покупок в нем случилось и на какую сумму эти покупки, по
+словам клиента.
+
+## Атрибуция: по событию, а не по визиту
+
+Метки едут на каждом событии, и витрина группирует события по их
+собственным меткам. Модели «первое касание» или «последнее касание» здесь
+нет: их построение — отдельная тема, а это витрина трафика по меткам.
+
+`dds.session_v` при этом несет UTM первого события визита, и ответ «какой
+канал привел» из сессии и из этой витрины будет разным. Это не
+ошибка ни одной из сторон — это два разных вопроса, и в отчете их надо
+различать.
+
+## Прямой трафик из витрины не выбрасывается
+
+Соблазн отфильтровать строки без меток велик: витрина же про рекламу.
+Отфильтровать нельзя по двум причинам. Первая деловая: прямой трафик —
+обычно самый крупный «канал» магазина, и отчет, где его нет, врет о доле
+рекламы. Вторая техническая: как только часть событий выпала, итог витрины
+перестал сходиться с итогом источника, и проверить сборку стало нечем.
+
+Пустые метки остаются пустыми строками, как в источнике. Своего слова для
+«прямого захода» витрина не изобретает: чем меньше выдуманных значений, тем
+меньше расшифровывать читателю.
+
+## Зерно и форма
+
+Зерно — **день события × `utm_source` × `utm_medium` × `utm_campaign`**.
+Зерно источника — событие, значит витрина материализуется:
+`dm.utm_effectiveness_rep` / `_dist`, донор `_stage_rep` / `_stage_dist`,
+публичное `dm.utm_effectiveness_v`. Ключ партиции — день.
+
+Источник — `dds.event_v`, публичный договор события: витрина слоя DM читает
+договор DDS, а не соседнюю витрину.
+
+## Состав колонок
+
+| Колонка | Тип | Что это |
+|---|---|---|
+| `report_date` | `Date` | день события |
+| `utm_source` | `LowCardinality(String)` | источник кампании |
+| `utm_medium` | `LowCardinality(String)` | канал кампании |
+| `utm_campaign` | `String` | имя кампании |
+| `visitors` | `UInt64` | число разных `client_id` |
+| `pageviews` | `UInt64` | просмотров страниц |
+| `add_to_carts` | `UInt64` | добавлений в корзину |
+| `purchases` | `UInt64` | покупок |
+| `declared_revenue` | `Decimal(18, 2)` | выручка покупок глазами клиента |
+| `_load_id` | `String` | запуск, собравший день |
+| `_load_ts` | `DateTime64(3, 'UTC')` | когда собран |
+
+`declared_revenue` складывает `purchase_revenue[1]` событий `purchase`.
+Индекс не описка: блок `purchase*` едет параллельными массивами, и у события
+покупки в них ровно один элемент — контракт источника обещает один номер
+заказа и одну объявленную сумму на событие. Тем же индексом берет свою
+сторону стендовая сверка `purchase_vs_orders`.
+
+Приводить тип не нужно: в договоре `purchase_revenue` уже
+`Array(Decimal(18, 2))`. `Float64` эта сумма была только в выгрузке
+источника, и ODS перевел ее в точные деньги на приеме — сложение Decimal
+точное, и где стоит `CAST`, до или после `sum`, на результат не влияет.
+Витрина просто хранит то, что сложила, в `Decimal(18, 2)`.
+
+`utm_campaign` оставлена обычной строкой: имен кампаний со временем
+становится много, и словарь `LowCardinality` на растущем множестве
+перестает окупаться.
+
+## Ритм пересборки
+
+Источник — события: день замерзает сразу. Объем прогона и механика те же,
+что в задании 2: хвост несобранных дней, донор, замена дневных партиций.
+
+## Ключ шардирования
+
+Твое решение по [правилу донора](../architecture/storage.md), «Раскладка по
+шардам». Зерно здесь составное, из трех колонок, и решение «взять хеш от
+одной из них» надо защищать отдельно: назови, какая доля строк придется на
+самое частое значение выбранной колонки.
+
+## Конфликт, ради которого витрина и написана
+
+Собери за один и тот же день две суммы: `sum(declared_revenue)` из своей
+витрины и `sum(revenue)` из `dm.revenue_daily_v`. Они не сойдутся, и это
+верное поведение обеих витрин.
+
+Базы у двух сумм при этом сравнимые: `revenue_daily` складывает цену позиций
+на количество и ни скидки, ни доставки в себя не берет — ровно то, что видит
+клиент. Значит все расхождение до копейки объясняется тем, что случилось с
+заказом, а не тем, как считали деньги. Ищи ответы среди таких причин:
+
+- отмененный заказ из кликстрима никуда не девается: событие покупки
+  случилось, а `revenue_daily` считает только оплаченные;
+- событие покупки может потеряться по дороге, а заказ при этом доехать —
+  и наоборот, событие приехать дважды;
+- клиент назвал сумму, отличную от серверной суммы позиций: генератор
+  делает это намеренно у одного-двух заказов из ста.
+
+Как эти же расхождения выглядят на зерне заказа, показывает стендовая
+витрина `dm.purchase_vs_orders_v` с ее классами расхождений: это готовый
+ответ на вопрос «а сколько именно и из-за чего». Запиши свой вывод —
+в двух-трех фразах, своими словами.
+
+Проверять сходимость этих двух сумм не нужно и нельзя: они и не должны
+сходиться.
+
+## Как проверить себя
+
+Деловой ключ — тройка `utm_source`, `utm_medium`, `utm_campaign` внутри
+дня. Собери прямой агрегат из `dds.event_v` за день, соедини с
+`dm.utm_effectiveness_v` полным внешним соединением и посчитай строки, где
+ключа нет с одной из сторон или где расходится любая из пяти величин. Ноль —
+зеленый.
+
+Две проверки покрупнее ловят самые частые ошибки:
+
+- сумма `pageviews`, `add_to_carts` и `purchases` за день равна числу
+  событий соответствующего типа в `dds.event_v` за тот же день;
+- сумма `declared_revenue` за день равна сумме `purchase_revenue[1]` по всем
+  событиям `purchase` этого дня.
+
+Обе не сойдутся, если прямой трафик отфильтрован, и разойдутся ровно на его
+долю — по этому следу отфильтрованные строки и находят. `visitors`, как и в
+задании 3, по строкам не складывается: один посетитель приходит по разным
+меткам.
+
+## Приемка
+
+- [ ] пять объектов витрины созданы, донор объявлен через `AS` и шардируется
+      ключом цели;
+- [ ] строки без UTM-меток в витрине остались;
+- [ ] `declared_revenue` хранится в `Decimal(18, 2)`;
+- [ ] расхождение с `dm.revenue_daily_v` объяснено письменно;
+- [ ] задача `utm_effectiveness` в `homework_check` зеленая;
+- [ ] задача витрины добавлена в `dm_transform`.

docs/research/2026-08-16-order-snapshot-wire-format.md

@@ -126,6 +126,10 @@ parseDateTime64InJodaSyntaxOrNull(
 использовать и для типизированной строки, и для маршрутизации ошибки; нулевая
 дата не нужна.
 
+> Актуальный стенд: версию `ods.order` задаёт `snapshot_date`
+> ([ADR 0014](../adr/0014-order-version-snapshot-date.md)). Следующий
+> абзац фиксирует исходный вывод исследования и не описывает текущий контракт.
+
 `updated_at` допустим как колонка версии `ReplacingMergeTree`: ClickHouse
 явно разрешает для `ver` тип `DateTime64` и оставляет строку с максимальной
 версией

docs/research/2026-08-22-distributed-join.md

@@ -0,0 +1,235 @@
+# Соединение двух Distributed-таблиц на стенде
+
+Дата исследования: 2026-08-22. Тикет #129, хвост раздела 11 мастер-спеки.
+
+Учебный результат: менти видит на своём кластере, где именно выполняется
+JOIN двух Distributed-таблиц, чем GLOBAL отличается от обычного соединения и
+почему «правильный» ключ шардирования в DDL ещё не гарантирует ко-локацию
+данных.
+
+Проверено двумя дорогами: читающими запросами на живом стенде
+(ClickHouse 26.3.17.56, 2 шарда × 1 реплика; запросы помечены
+`log_comment = 'r129-*'`, разбор — по `system.query_log` обеих нод) и по
+документации ClickHouse через MCP Context7 (страницы «JOIN Clause →
+Distributed JOIN», «Distributed table engine», «IN operators → distributed
+subqueries», настройки `distributed_product_mode`,
+`prefer_global_in_and_join`, `parallel_distributed_insert_select`).
+
+## Короткий вывод
+
+- Обычный JOIN и `IN` с Distributed-таблицей справа режутся настройкой
+  `distributed_product_mode = 'deny'` — это заводское значение, стенд его не
+  менял. Ошибка: `DISTRIBUTED_IN_JOIN_SUBQUERY_DENIED`.
+- `GLOBAL JOIN` собирает правую часть один раз на ноде-инициаторе, кладёт во
+  временную таблицу `_data_…` и рассылает её на все шарды; каждый шард
+  соединяет свой локальный кусок левой таблицы с этой копией. Это видно в
+  журнале запросов второй ноды дословно.
+- Режим `local` переписывает правую Distributed-таблицу на локальную. Ответ
+  верен только при настоящей ко-локации по ключу соединения; иначе он молча
+  меньше правильного — ошибки не будет.
+- Если левая часть — подзапрос, а не голая таблица, ClickHouse 26.3 вообще не
+  раздаёт соединение по шардам: обе стороны стягиваются на инициатор и JOIN
+  выполняется там один раз. `GLOBAL` и `distributed_product_mode` при этом ни
+  на что не влияют.
+- Ловушка `FULL OUTER`: при голой левой Distributed-таблице непарная строка
+  правой части попадает в ответ по разу с каждого шарда — на нашем кластере
+  дважды. С подзапросами с обеих сторон ответ верный.
+- Находка стенда: ко-локация заказов по `cityHash64(order_id)` сломана — 1189
+  из 1662 заказов лежат на обоих шардах одинаковыми строками. Виновата
+  настройка `parallel_distributed_insert_select = 2` (заводское значение
+  в 26.3): `INSERT … SELECT` из Distributed в Distributed выполнился локально
+  на каждом шарде, и строки заказов унаследовали раскладку сырья — по хешу
+  сырой строки. События целы: все 401 185 строк лежат по своему хешу
+  `cityHash64(ClientID)`.
+
+## Как выполняется соединение: три наблюдаемых плана
+
+### Обычный JOIN голых Distributed-таблиц — запрещён
+
+```sql
+SELECT count() FROM ods.order_dist AS a
+INNER JOIN ods.order_dist AS b ON a.order_id = b.order_id
+```
+
+Обе версии планировщика (`enable_analyzer` 0 и 1) отвечают:
+
+```text
+Code: 288. DB::Exception: Double-distributed IN/JOIN subqueries is denied
+(distributed_product_mode = 'deny'). You may rewrite query to use local
+tables in subqueries, or use GLOBAL keyword, or set distributed_product_mode
+to suitable value. (DISTRIBUTED_IN_JOIN_SUBQUERY_DENIED)
+```
+
+Причина по документации: запрос переписывается для каждого шарда, и правая
+Distributed-таблица внутри такой переписки означала бы «каждый шард ещё раз
+спрашивает весь кластер» — N шардов породили бы N×N подзапросов. Режим `deny`
+запрещает это по умолчанию. Тот же запрет действует на `IN
+(SELECT … FROM …_dist)` — поэтому в исследовательских запросах ниже стоит
+`GLOBAL IN`.
+
+### GLOBAL JOIN — правая часть собирается один раз и рассылается
+
+```sql
+SELECT count() FROM ods.order_dist AS a
+GLOBAL INNER JOIN ods.order_dist AS b ON a.order_id = b.order_id
+```
+
+Журнал запросов второй ноды показывает оба шага (log_comment
+`r129-bare-global`):
+
+```text
+SELECT order_id FROM ods.order_rep                -- шард отдаёт свой кусок правой части
+SELECT count() FROM ods.order_rep
+GLOBAL ALL INNER JOIN `_data_14241958685358625318_…` ON …  -- шард соединяет локальную левую с разосланной копией
+```
+
+Инициатор один раз прочёл правую часть со всех шардов, собрал временную
+таблицу в памяти, разослал её и слил частичные результаты. Цена GLOBAL —
+память инициатора и рассылка по сети, поэтому он для малой правой части;
+заказы (2851 строка) малы.
+
+### Подзапрос слева выключает раздачу по шардам
+
+```sql
+SELECT count()
+FROM (SELECT arrayJoin(purchaseID) AS pid FROM ods.event_dist
+      WHERE notEmpty(purchaseID)) AS e
+INNER JOIN ods.order_dist AS o ON e.pid = o.order_id
+```
+
+Этот запрос прошёл без ошибки даже при `deny`, и с `GLOBAL`, и во всех
+режимах `distributed_product_mode` — план один и тот же: вторая нода получила
+два независимых чтения (`SELECT … FROM ods.event_rep`,
+`SELECT order_id FROM ods.order_rep`), а соединение выполнил инициатор,
+прочитав целиком обе стороны (404 036 строк). Раздачи соединения по шардам
+здесь нет вовсе, поэтому нет и «двойной распределённости», которую режим
+`deny` запрещает.
+
+## distributed_product_mode на живых данных
+
+Самосоединение заказов, счёт пар строк. Правильные ответы посчитаны отдельно
+как суммы квадратов кратностей: по `order_id` — 5229, по `user_id` — 6087.
+
+| Ключ | GLOBAL | `local` | `allow` |
+|---|---|---|---|
+| `order_id` (заявленный ключ шардирования) | 5229 | **2851** | — |
+| `user_id` (ко-локации нет и не заявлено) | 6087 | **3281** | 6087 |
+
+`local` переписывает правую часть на локальную таблицу — в журнале второй
+ноды виден дословный `… FROM ods.order_rep INNER JOIN ods.order_rep …`. Ответ
+совпадает с суммой пошардовых соединений и верен только тогда, когда обе
+строки каждой пары лежат на одном шарде. По `user_id` это ожидаемо не так. По
+`order_id` ответ тоже неверен — потому что настоящая раскладка заказов ключу
+не соответствует (см. ниже). `allow` разрешает наивный план «каждый шард
+спрашивает весь кластер»: ответ верный, чтений — квадрат от числа шардов.
+
+Документация даёт четыре режима (`deny`, `local`, `global`, `allow`) и
+отдельную настройку `prefer_global_in_and_join`, которая молча превращает
+обычные IN/JOIN в GLOBAL. Стенд ничего из этого не меняет: явный `GLOBAL` в
+тексте запроса честнее незаметной настройки — читатель видит цену в самом
+запросе.
+
+## Ловушка FULL OUTER на кластере
+
+Строка правой части, не нашедшая пары, добавляется в ответ каждым шардом:
+
+```sql
+SELECT countIf(b_flag = 1) FROM ods.order_dist AS a
+GLOBAL FULL OUTER JOIN
+  (SELECT 'zzz-no-such-order' AS oid, 1 AS b_flag) AS b ON a.order_id = b.oid
+-- ответ: 2  (одна фиктивная строка вернулась дважды — по разу с каждого шарда)
+```
+
+Так ведут себя обе версии планировщика. Механика прямая: каждый шард получил
+копию правой части, у каждого она не нашла пары в его локальном куске, и
+каждый честно отдал её как непарную. Стоит обернуть левую часть в подзапрос —
+соединение выполняется один раз на инициаторе, и ответ становится верным:
+
+```sql
+… FROM (SELECT order_id FROM ods.order_dist) AS a GLOBAL FULL OUTER JOIN … 
+-- ответ: 1
+```
+
+## Находка: ко-локация заказов сломана
+
+DDL обещает раскладку по `cityHash64(order_id)`, но на живых данных половина
+строк лежит не на своём шарде:
+
+| Шард | на своём шарде | не на своём |
+|---|---|---|
+| 1 | 696 | 725 |
+| 2 | 750 | 680 |
+
+1189 из 1662 заказов присутствуют на обоих шардах одинаковыми строками —
+одна и та же версия, один и тот же `_load_id`. Пути реплик в keeper у шардов
+разные, репликация ни при чём.
+
+Причина — `parallel_distributed_insert_select = 2`, заводское значение
+в 26.3. По документации: если выполняется `INSERT INTO distributed_a
+SELECT … FROM distributed_b` и обе таблицы на одном кластере, запрос
+выполняется локально на каждом шарде. Ровно это делает разбор заказов
+(`sql/ods/order_parse.sql`: `INSERT INTO ods.order_dist … FROM
+stg.orders_raw_dist`): каждый шард разобрал свой кусок сырья и записал его в
+свою локальную таблицу, минуя ключ шардирования цели. Строки заказов
+унаследовали раскладку STG — хеш сырой строки, то есть случайную относительно
+`order_id`. Заказ, попавший в несколько дневных слепков, приезжает несколькими
+разными сырыми строками и оседает на обоих шардах; ReplacingMergeTree
+схлопывает дубли только внутри шарда.
+
+Следствия уже наблюдаемы: `count()` по `ods.order_dist` даёт 2851 при 1662
+заказах, а точное чтение работает только через `GROUP BY order_id` /
+`argMax` — пошардовый `FINAL` через дубль на соседнем шарде не переступит.
+События этой болезни не имеют: их пишет матвью приёма от Kafka-таблицы, не
+из Distributed, и раскладка по `cityHash64(ClientID)` точна на всех 401 185
+строках.
+
+Починка — отдельный тикет, не этого исследования: разбору заказов нужно
+явное `parallel_distributed_insert_select = 0` (строки поедут через ключ
+шардирования цели), плюс пересборка уже разложенного. Тот же капкан ждёт
+любую будущую сборку DDS вида `INSERT INTO …_dist SELECT … FROM …_dist`, у
+которой ключ цели отличается от ключа источника.
+
+## Выводы для identity_map (спека §5)
+
+Сборка карты — соединение покупок из событий с заказами по
+`purchaseID = order_id`. Ключ соединения не ключ ко-локации событий, поэтому
+по политике раздела 6 спеки соединение обязано быть GLOBAL — и эмпирика это
+подтверждает: обычный JOIN голых таблиц запрещён, `local` дал бы молча
+неверный ответ. GLOBAL здесь дёшев: правая часть — заказы, их тысячи.
+
+На практике левая часть сборки — подзапрос (события фильтруются по
+`notEmpty(purchaseID)` и разворачиваются `arrayJoin`), а значит на 26.3
+соединение выполнится один раз на инициаторе. `GLOBAL` в тексте при этом не
+лишний: он выражает политику спеки, ничего не стоит и защищает запрос от
+смены плана при другой форме запроса или версии сервера.
+
+Запись результата в `dds.identity_map` (шардирование `cityHash64(client_id)`)
+пойдёт тем же `INSERT … SELECT`. Источник — результат соединения, а не голая
+Distributed-таблица, поэтому капкан `parallel_distributed_insert_select` на
+эту вставку не распространяется; но проверку раскладки после первой сборки
+стоит включить в приёмку — теперь ясно, что заявленный ключ и настоящая
+раскладка умеют расходиться.
+
+## Выводы для purchase_vs_orders_v (спека §7)
+
+`FULL OUTER GLOBAL JOIN` для сверки корректен при одном условии: обе стороны —
+подзапросы, и соединение выполняется один раз на инициаторе. Витрина это
+условие выполняет естественно: покупки нужно развернуть из массива и
+агрегировать (класс `duplicate_event` иначе не посчитать), заказы — привести
+к последней версии. С голой Distributed-таблицей слева витрина удваивала бы
+каждый заказ без события — весь класс `lost_event` — по числу шардов.
+
+Прогон сверочной формы на живых данных (обе стороны — подзапросы с
+`GROUP BY`): 1662 совпадения, 255 покупок без заказа (ждут слепка,
+`awaiting_order`), 0 заказов без покупки, без задвоений. Обе величины
+согласуются с прямыми счётами — форма пригодна как каркас витрины.
+
+## Чем проверялось
+
+Все запросы — читающие, от служебного пользователя внутри контейнеров
+(`docker compose exec clickhouse-01 … clickhouse-client`), следы — в
+`system.query_log` обеих нод по `log_comment` с префиксом `r129-`. Документные
+утверждения (механика GLOBAL, режимы `distributed_product_mode`, поведение
+`parallel_distributed_insert_select`) сверены с документацией ClickHouse через
+MCP Context7; поведение FULL OUTER на кластере в документации не описано —
+здесь источник только эмпирика.

docs/research/2026-08-22-view-predicate-pushdown.md

@@ -0,0 +1,169 @@
+# Проталкивание условий сквозь представления над FINAL
+
+Дата исследования: 2026-08-22. Тикет #128, карта #127.
+
+Вопрос: пробрасывает ли ClickHouse условия запроса внутрь обычного
+представления над таблицей с `FINAL` (`ods.event_v`) и внутрь вложенного
+представления над ним (будущее `dds.event_v`) — или разворачивает
+представление целиком и фильтрует потом.
+
+## Короткий вывод
+
+- Пробрасывает. Обычное представление — это подзапрос в `FROM`, и условие
+  внешнего запроса доезжает сквозь него до партиций и первичного ключа
+  таблицы. Проверено планом и счётчиком прочитанных строк.
+- Второй уровень вложенности ничего не ломает: сквозь подзапрос над
+  `ods.event_v` с переименованными колонками условие доезжает так же —
+  срезание партиций совпадает с прямым запросом к `ods.event_dist FINAL`
+  один в один.
+- Условие доезжает даже сквозь вычисленную колонку: фильтр по
+  `toStartOfWeek(EventDate)` анализируется индексом MinMax.
+- Единственное, что `FINAL` отнимает, — автоматический перенос условия в
+  `PREWHERE`: настройка `optimize_move_to_prewhere_if_final` по умолчанию
+  выключена. Срезание по индексам при этом работает полностью; теряется
+  только оптимизация порядка чтения колонок внутри уже выбранных гранул.
+- Для контракта `dds.event_v` это значит: цепочка обычных представлений
+  ODS → DDS годится, представление до фильтра не материализуется.
+
+## Как проверяли
+
+Живой стенд, ClickHouse 26.3.17.56, `enable_analyzer = 1` (умолчание).
+Только читающие запросы с ноды 1: `EXPLAIN indexes = 1`,
+`EXPLAIN actions = 1`, `SELECT` со сверкой по `system.query_log`.
+Вложенное представление не создавали — состояние стенда не менялось;
+второй уровень эмулирован эквивалентным подзапросом.
+
+Устройство пары: `ods.event_rep` — `ReplicatedReplacingMergeTree(_load_ts)`,
+`PARTITION BY EventDate`, `ORDER BY (CounterID, EventDate,
+intHash32(ClientID), WatchID)`; на момент опыта 16 активных кусков в
+8 партициях, 24 гранулы. `ods.event_v` — `SELECT * FROM ods.event_dist FINAL`.
+
+## Опыт 1. Фильтр по ключу партиции сквозь представление
+
+```sql
+EXPLAIN indexes = 1
+SELECT count() FROM ods.event_v WHERE EventDate = '2026-06-01';
+```
+
+План читает `ods.event_rep` с условием `EventDate in [20605, 20605]` во всех
+трёх индексах — MinMax, Partition, PrimaryKey: `Parts: 2/16`,
+`Granules: 3/24`. Прямой запрос `SELECT count() FROM ods.event_dist FINAL
+WHERE EventDate = '2026-06-01'` даёт те же цифры. Представление ничего не
+прячет от анализа индексов.
+
+## Опыт 2. Второй уровень: подзапрос над представлением
+
+Будущее `dds.event_v` — представление над `ods.event_v` с переименованием в
+язык бизнес-модели. Эмуляция:
+
+```sql
+EXPLAIN indexes = 1
+SELECT count()
+FROM (
+    SELECT WatchID AS watch_id, EventDate AS event_date,
+           lower(EventType) AS event_type
+    FROM ods.event_v
+) WHERE event_date = '2026-06-01';
+```
+
+Условие по переименованной колонке доехало до таблицы: `Parts: 2/16`,
+`Granules: 3/24` — цифры совпали с опытом 1. Два уровня разворачивания и
+переименование колонок проталкиванию не мешают.
+
+Отдельно проверена вычисленная колонка:
+
+```sql
+SELECT count()
+FROM (SELECT toStartOfWeek(EventDate) AS event_week FROM ods.event_v)
+WHERE event_week = '2026-06-01';
+```
+
+В плане условие `toStartOfWeek(EventDate) in [20605, 20605]` стоит в индексе
+MinMax и срезает `Parts: 0/16` — ноль корректен: при умолчании функции ни
+одна неделя не начинается в этот понедельник. То есть даже фильтр по
+выражению от ключевой колонки анализируется индексом, пока функция ему
+понятна.
+
+## Опыт 3. Фильтр по ключу сортировки
+
+```sql
+EXPLAIN indexes = 1
+SELECT count() FROM ods.event_v WHERE CounterID = 42150607;
+```
+
+Условие `CounterID in [...]` дошло до PrimaryKey (`Search Algorithm: binary
+search`). Гранулы не срезались (`24/24`) — но это свойство данных, а не
+представления: счётчик один, он есть в каждой грануле.
+
+## Опыт 4. PREWHERE и FINAL
+
+По колонке вне ключа (`EventType = 'pageview'`, `EXPLAIN actions = 1`,
+запрос с широким списком колонок):
+
+- `ods.event_rep` без `FINAL` — условие уехало в `Prewhere filter`;
+- `ods.event_rep FINAL` и `ods.event_v` — условие осталось обычным `Filter`
+  над шагом чтения.
+
+Причина — настройка `optimize_move_to_prewhere_if_final`, на стенде `0`
+(умолчание). Это цена самого `FINAL`, а не представления: прямой запрос с
+`FINAL` ведёт себя так же.
+
+## Опыт 5. Счётчик прочитанных строк
+
+План — обещание; исполнение сверено по `system.query_log`
+(`read_rows` начального запроса, сумма по кластеру):
+
+| Запрос | read_rows |
+|---|---|
+| `ods.event_v` без фильтра | 401 185 |
+| `ods.event_v WHERE EventDate = '2026-06-01'` | 50 626 |
+| подзапрос над `ods.event_v`, фильтр по `event_date` | 50 626 |
+
+Фильтр сквозь представление читает только партиции своего дня, вложенность
+не добавляет ни строки. 401 185 — все физические строки обеих нод.
+
+## Что говорит документация
+
+Сверено через MCP Context7 22 августа 2026 года, библиотека
+`/websites/clickhouse`.
+
+- Обычное представление не хранит данных: при обращении его запрос
+  исполняется как подзапрос в `FROM` — `SELECT a, b, c FROM view`
+  эквивалентен `SELECT a, b, c FROM (SELECT ...)`
+  (`sql-reference/statements/create/view`).
+- Проталкивание предикатов в подзапросы — штатная работа оптимизатора;
+  анализатор доводит фильтры до хранилища, включая срезание партиций и
+  первичного ключа (changelog 2026, настройки семейства
+  `allow_push_predicate_*`).
+- `optimize_move_to_prewhere_if_final` управляет автоматическим `PREWHERE`
+  для запросов с `FINAL` (`settings/session-settings`); на стенде она в
+  умолчании `0`, что и видно в опыте 4.
+- `do_not_merge_across_partitions_select_final = 1` заставляет `FINAL`
+  обрабатывать партиции независимо; с 2026 года значение `1` включает режим
+  безусловно, а автоматику решает отдельная настройка
+  `enable_automatic_decision_for_merging_across_partitions_for_final`
+  (changelog 2026). К `ods.event` режим применим: партиция — `EventDate`,
+  версии одного события всегда лежат в одном дне. На стенде настройка `0`,
+  и трогать её не понадобилось — вопрос тикета решился без неё.
+- `FINAL` поверх подзапроса не работает — модификатор обязан стоять у самой
+  таблицы (`guides/.../analyzer`, «Fixing Invalid FINAL Usage»). Наша
+  цепочка это соблюдает: `FINAL` живёт в один слой, внутри `ods.event_v`.
+
+## Вывод для контракта dds.event_v
+
+Сомнение владельца — «представление материализуется до фильтра» — не
+подтвердилось. Условия по ключу партиции и ключу сортировки доезжают до
+индексов сквозь два уровня обычных представлений, переименование колонок и
+анализируемые выражения; исполняется это, а не только планируется.
+
+Цепочка обычных представлений ODS → DDS → DM годится как форма контракта.
+Две оговорки в контракт:
+
+1. `FINAL` внутри `ods.event_v` отключает автоматический `PREWHERE` — на
+   объёмах стенда это незаметно, но слабый фильтр по неключевой колонке
+   при широком `SELECT` читает больше, чем без `FINAL`. Это свойство
+   `FINAL`, представления его не усугубляют.
+2. Индекс срезает только то, что умеет анализировать: фильтр по колонке,
+   которую `dds.event_v` вычислит нетривиальным выражением, до индекса
+   может не доехать. Ключевые для срезов колонки — прежде всего
+   `EventDate` — стоит отдавать в DDS переименованием, а не пересчётом.

docs/research/2026-08-25-clickhouse-distributed-view-security.md

@@ -0,0 +1,132 @@
+# Права DEFINER у представления над Distributed
+
+Дата исследования: 2026-08-25. Тикет #150. ClickHouse 26.3.17.56.
+
+## Вопрос
+
+Почему `dds.event_v` с `SQL SECURITY DEFINER`, созданное пользователем
+`lifecycle`, всё равно читает удалённый `ods.event_rep` как `bi`? Можно ли
+оставить `bi` только с правом на публичное представление DDS, не заводя отдельный
+маршрут или пользователя и не копируя данные?
+
+## Короткий вывод
+
+Простого поддерживаемого способа в ClickHouse 26.3 нет. `DEFINER` меняет
+пользователя, чьи права проверяет локальный запрос представления, но сохраняет
+в запросе имя его первоначального инициатора — `initial_user`. Движок
+`Distributed` передаёт это имя на шарды, а межсерверный секрет делает его
+пользователем удалённой сессии. Поэтому на координаторе источники читает
+`lifecycle`, а на соседнем шарде физическую таблицу читает `bi`.
+
+Это не заявленная семантика `SQL SECURITY DEFINER`: документация обещает, что
+право на источник требуется определившему представление пользователю, а
+вызывающему достаточно `SELECT` на представление. Поведение следует из
+сочетания двух реализаций и выглядит как недокументированное ограничение или
+дефект распределённого исполнения.
+
+## Где меняется пользователь
+
+`dds.event_v` разворачивается в запрос к `ods.event_v`, затем к
+`ods.event_dist FINAL`. Для внутреннего запроса представления ClickHouse
+создаёт новый контекст в
+[`getSQLSecurityOverriddenContext`](https://github.com/ClickHouse/ClickHouse/blob/v26.3.17.56-lts/src/Storages/StorageInMemoryMetadata.cpp#L135-L175):
+
+1. копирует исходный `ClientInfo` целиком, включая `initial_user = bi`;
+2. затем отдельно вызывает `setUser` для определившего представление
+   пользователя `lifecycle`.
+
+В контексте остаются два имени с разными задачами: `lifecycle` отвечает за
+локальную проверку прав, а `bi` остаётся первоначальным пользователем запроса.
+Второй `SQL SECURITY DEFINER` на `ods.event_v` повторяет те же два шага и
+поэтому ничего не меняет.
+
+## Что происходит на границе шарда
+
+`Distributed` копирует `ClientInfo` из контекста и отправляет его на удалённую
+ноду без замены `initial_user`
+([`RemoteQueryExecutor.cpp`](https://github.com/ClickHouse/ClickHouse/blob/v26.3.17.56-lts/src/QueryPipeline/RemoteQueryExecutor.cpp#L415-L444)).
+При межсерверном секрете имя входит в подписываемые данные запроса
+([`Connection.cpp`](https://github.com/ClickHouse/ClickHouse/blob/v26.3.17.56-lts/src/Client/Connection.cpp#L968-L994)).
+Принимающая нода проверяет подпись и открывает сессию с
+`AlwaysAllowCredentials{client_info.initial_user}`
+([`TCPHandler.cpp`](https://github.com/ClickHouse/ClickHouse/blob/v26.3.17.56-lts/src/Server/TCPHandler.cpp#L2303-L2356)).
+
+Секрет здесь выполняет штатную функцию. Это не случайный побочный эффект.
+Документация `Distributed` прямо говорит: если задан `<secret>`, `initial_user`
+становится текущим пользователем удалённого запроса
+([описание кластера](https://github.com/ClickHouse/ClickHouse/blob/v26.3.17.56-lts/docs/en/engines/table-engines/special/distributed.md#L105-L118)).
+Так права, роли и ограничения исходного пользователя одинаково действуют на
+всех шардах: координатор подтверждает личность пользователя, но не превращает
+его запрос в запрос своей служебной учётки. Протокол не передаёт отдельно
+эффективного пользователя `DEFINER`, поэтому на стенде эта защита и
+останавливает `bi` у `ods.event_rep`.
+
+## Рассмотренные варианты
+
+### Настройка или другая форма представления
+
+В 26.3 нет настройки, которая подменяет `initial_user` на определившего
+представление пользователя только для чтения `Distributed`.
+`push_external_roles_in_interserver_queries` пересылает роли именно
+`initial_user`, не роли `DEFINER`
+([исходник отправки](https://github.com/ClickHouse/ClickHouse/blob/v26.3.17.56-lts/src/QueryPipeline/RemoteQueryExecutor.cpp#L425-L444)).
+`distributed_ddl_use_initial_user_and_roles` относится только к заданиям
+`ON CLUSTER`. На `SELECT` настройка не действует
+([объявление настройки](https://github.com/ClickHouse/ClickHouse/blob/v26.3.17.56-lts/src/Core/ServerSettings.cpp#L1002-L1006)).
+
+### Пользователь в существующем описании кластера
+
+С межсерверным секретом ClickHouse выбирает специальную межсерверную
+аутентификацию и не использует пароль из описания реплики
+([`Connection::sendHello`](https://github.com/ClickHouse/ClickHouse/blob/v26.3.17.56-lts/src/Client/Connection.cpp#L452-L476)).
+Чтобы удалённый запрос всегда шёл как `lifecycle`, пришлось бы убрать секрет и
+передавать его пароль. Тогда между нодами перестанет передаваться исходный
+пользователь. Одна модель доступа сменится другой, менее прозрачной.
+
+### `remote()` с явными реквизитами
+
+Для `remote()` ClickHouse умеет заменить `initial_user` пользователем из
+адреса
+([`executeQuery.cpp`](https://github.com/ClickHouse/ClickHouse/blob/v26.3.17.56-lts/src/Interpreters/ClusterProxy/executeQuery.cpp#L96-L120)).
+Но представлению понадобятся адреса и реквизиты удалённого пользователя — в
+тексте DDL либо в отдельной настройке. Это и есть отдельный маршрут доступа;
+он сложнее нынешнего кластера и требует хранить ещё один секрет.
+
+### Промежуточное локальное представление на шарде
+
+Можно направить `Distributed` на локальное представление с `DEFINER`, но
+удалённому пользователю всё равно нужен `SELECT` на это представление. Значит
+появятся дополнительный объект и дополнительный грант, а `bi` увидит
+поверхность одного шарда. Физическая таблица останется закрытой, но простота и
+контракт «только публичная поверхность DDS» исчезнут.
+
+### Ослабление проверки
+
+- `SQL SECURITY NONE` снимает проверку источника, но устарело и позволяет
+  создателю такого представления исполнять произвольный запрос; ClickHouse
+  требует для этого отдельное право
+  ([документация](https://github.com/ClickHouse/ClickHouse/blob/v26.3.17.56-lts/docs/en/sql-reference/statements/create/view.md#L115-L136)).
+- Право `bi` на физическую ODS-таблицу решает ошибку без новой механики, но
+  ослабляет исходную границу.
+- Физическая или материализованная копия в DDS сохраняет границу, но добавляет
+  хранение и жизненный цикл данных ради переименования колонок.
+
+## Решение для стенда
+
+25 августа 2026 года выбрана простота: роль `bi_reader` читает ODS, DDS и DM
+целиком. Потребительские запросы продолжают обращаться к `_v`. Этот договор
+держат документация и ревью; границы прав задают гранты.
+
+Отдельный межсерверный маршрут, служебная учётка и физическая поверхность DDS
+отклонены: каждый вариант добавляет механику только ради защиты, которой стенд
+не учит. Готовой настройки, которая сохранила бы и узкую границу, и простое
+устройство, в закреплённой версии нет.
+
+## Граница уверенности
+
+Механизм подтверждён исходным кодом точной версии 26.3.17.56. Простую настройку
+искали в настройках сервера и в путях формирования удалённого запроса этой же
+версии. Уверенность в обоих выводах высокая. Официального
+текста, который называет сочетание `DEFINER + Distributed + secret`
+поддерживаемым ограничением или зарегистрированным дефектом, не найдено;
+классификация как дефекта остаётся выводом из расхождения документации и кода.

docs/research/2026-08-31-labs-inventory.md

@@ -0,0 +1,279 @@
+# Инвентаризация сюжетов лаб по слоям стенда
+
+Это материал для спеки программы лаб (#202): полный список сюжетов без отбора. Спека решит, что оставить и в каком порядке поставить. Здесь для каждого участка стенда записано, чему на нем научится менти. Тикет — #201, карта — #182.
+
+Каждый сюжет описан четырьмя строками: **урок**, **материал**, **форма** и **проверка**. Возможны три формы:
+
+- *построить свое по ТЗ* — как в пяти домашних заданиях DM: рядом есть образец, но нет готового ответа;
+- *вычитание* — удалить SQL готовой трансформации и написать его заново; даги остаются без изменений (уточнение владельца в комментарии к #148);
+- *расследование* — данные уже лежат на стенде или стенд намеренно ломается, а менти ищет причину и объясняет ее.
+
+Существующие шесть заданий из `docs/labs/` входят в список как готовое ядро слоя DM. Идеи из тикетов #143, #145, #148, #149, #186, #187, #188 разнесены по подходящим участкам. В конце отдельно проверяется гипотеза «вычитание + DQ» для каждого потока нижних слоев.
+
+## STG — прием и сырье
+
+**1. Push против pull: два способа принять топик.**  
+Урок: способ приема зависит от источника. Поток постоянно читает подписанная матвью, а слепок забирает отдельный запрос по команде.  
+Материал: оба чтеца в `sql/ddl/10-stg-tables.sql` (у `orders_raw_kafka` нет ни матвью, ни `ON CLUSTER`, зато есть `kafka_commit_on_select`), матвью приема `sql/ddl/40-stg-views.sql`, забор `sql/stg/orders_raw_load.sql`, `dags/orders_ingest.py`; сравнение цены и наблюдаемости — заготовка спеки (`docs/specs/2026-07-30-stand-v2-realism.md`, раздел 12).  
+Форма: расследование двух живых путей на одном стенде.  
+Проверка: офсеты групп `clickstream_hits` и `clickstream_orders`, счет строк сырья по `_load_id`.
+
+**2. Кто читал топик и куда легли данные.**  
+Урок: нода, которая читает топик, может меняться от прогона к прогону. Раскладка данных не меняется: ее определяет ключ шардирования — свойство самих данных.  
+Материал: колонка `consumer_host` в `stg.hits_raw_dist`; `docs/architecture/storage.md`, «Раскладка по шардам».  
+Форма: расследование данных.  
+Проверка: пересчет ключа шардирования по `hostName()` — строк на чужом шарде нет.
+
+**3. Вторая consumer group — дубли.**  
+Урок: на кластер нужна одна группа потребителей. Если завести вторую, каждая нода получит полную копию топика.  
+Материал: `kafka_group_name` в `sql/ddl/10-stg-tables.sql`; сцена названа спекой (раздел 12).  
+Форма: расследование-опыт «сломай — увидь — верни» на переигранном дне.  
+Проверка: счет событий против описи мира (`make check-clickhouse`); уборка — снятием партиции `_load_ts` (правило из `docs/architecture/testing.md`).
+
+**4. Дырка в офсетах.**  
+Урок: сырье может сохранить не все сообщения, которые пришли из источника. Пустое сообщение или зазор после пересоздания матвью видны только по разрыву в `kafka_offset`, поэтому пропажу не нужно искать глазами.  
+Материал: `docs/architecture/storage.md`, «Что проверено» (опыты 5 и 7 августа); колонка `kafka_offset` в сырье.  
+Форма: расследование.  
+Проверка: непрерывность офсетов внутри партиции.
+
+**5. Две оси времени.**  
+Урок: переобработка данных и очистка диска живут по разным часам. Сырье разбивается на части и удаляется по `_load_ts`, а модельный день появляется только в ODS. Поэтому TTL по модельной дате работал бы неверно.  
+Материал: `sql/ddl/10-stg-tables.sql` (TTL трое суток, `ttl_only_drop_parts`), `docs/architecture/storage.md`, «Срок жизни сырья».  
+Форма: расследование-вопрос (почему нельзя нарезать сырье по `EventDate`).  
+Проверка: ответ сверяется с доводом доки; счетного инварианта нет.
+
+## ODS — типизация и брак
+
+**6. Предикат и его буквальное отрицание.**  
+Урок: годные строки и брак должны делить поток без пропусков и пересечений. NULL в предикате незаметно теряет строку, а исключение роняет вставку и останавливает чтение топика.  
+Материал: `sql/ddl/30-ods-views.sql` (пара матвью событий), `sql/ods/order_parse.sql` (макрос `order_wire_contract`), ADR 0005.  
+Форма: расследование — подложить в топик по строке каждого класса брака и найти их в `ods.event_errors_dist` / `ods.order_errors_dist`.  
+Проверка: «сырье среза = годные + брак» на управляемой пачке; строки опыта убрать за собой.
+
+**7. Три времени и версия-наблюдение.**  
+Урок: у строки заказа есть четыре временные координаты. Версию сущности задает дата слепка источника, а не время загрузки. `FINAL` живет ровно в одном месте — за представлением `_v`.  
+Материал: `sql/ddl/20-ods-tables.sql`, `sql/ddl/30-ods-views.sql`, ADR 0010 и 0014, `docs/architecture/orders/ingestion.md` («Роль ODS»).  
+Форма: расследование — физические версии `ods.order_dist` против `ods.order_v`.  
+Проверка: эталон `argMax` по `updated_at` прямо из сырья (прием #165).
+
+**8. Часовой пояс как способ смотреть на время.**  
+Урок: у ночных событий `toDate(UTCEventTime)` может не совпадать с `EventDate`. Это нормальное свойство данных. День нужно считать по готовой колонке и явно называть часовой пояс, в котором его рассматривают.  
+Материал: `docs/architecture/storage.md`, «Часовые пояса»; ADR 0015.  
+Форма: расследование данных.  
+Проверка: менти сам находит ночные события и объясняет расхождение.
+
+**9. Сырое против разобранного: `ecommerce`.**  
+Урок: типизированный разбор JSON может молча подменить ошибку значением. Например, `qty` со значением «oops» превратится в 0. Поэтому правильность разбора нужно подтверждать инвариантом источника.  
+Материал: колонка `ecommerce` рядом с массивами `purchase_*` / `product_*` в `ods.event`; разбор `items` в `sql/dds/order_rebuild.sql`; спека, раздел 1.2 («кандидат будущей лабы»).  
+Форма: построить свое по ТЗ — разобрать `ecommerce` запросом и сверить с готовыми массивами того же события.  
+Проверка: построчная сверка с колонками-массивами.
+
+## DDS — модель
+
+**10. Лаба сессий: своя нарезка против эталона.**  
+Урок: сессия — расчетная сущность, границы которой определяет логика в хранилище. Самостоятельная нарезка может разойтись с эталоном. Если расхождение невозможно, задание сводится к `GROUP BY` по готовому полю.  
+Материал: `docs/architecture/dds/session.md`, `sql/dds/session_rebuild.sql` (два окна, полный порядок `(event_time, event_id)`, детерминированный чекан), эталон `VisitID` в `ods.event_v`.  
+Форма: построить свое — менти собирает нарезку сам до знакомства со стендовым кодом; либо вычитание `session_rebuild.sql` (раздел о гипотезе ниже).  
+Проверка: `dq_check` / `sessions_vs_reference` (зерно кука × день против `uniqExact(VisitID)`); затем сравнение со стендовой нарезкой по `session_id`.
+
+**11. Поштучный разбор расхождения нарезки.**  
+Урок: счетная сверка показывает, сколько сессий разошлось. Чтобы понять, где именно отличаются границы, нужно вручную соединить свою сессию с эталонной по времени.  
+Материал: `sql/dq/sessions_vs_reference.sql`, `docs/architecture/dds/session.md`, «Сверка с эталоном» («поштучное сопоставление границ — материал лабы»).  
+Форма: расследование.  
+Проверка: найденная кука, день и пауза, на которой решения разошлись.
+
+**12. Склейка идентичностей во времени (#145).**  
+Урок: текущее знание о пользователе и знание на выбранную дату дают разные отчеты. Если использовать сведения из будущего, исторический график известной аудитории изменится.  
+Материал: `dds.identity_map_v` (пары без временной колонки — решение `docs/architecture/dds/identity.md`), момент связи выводится как минимум времени `purchase`-события, соединенного с заказом.  
+Форма: построить свое (запрос, без изменения стенда).  
+Проверка: два способа на одном наборе данных; расхождение объясняется письменно.
+
+**13. Справочник регионов (#143).**  
+Урок: справочник содержит данные, которыми источник владеет вне хранилища. Если собрать словарь руками, можно разобраться в механике, которую готовый каталог стенда позволяет только использовать.  
+Материал: образец `sql/ddl/05-dic-catalog.sql` и ADR 0012; зацепка в контракте — `region_city_id` / `region_country_id` отдаются как есть (`dds.event_v`).  
+Форма: построить свое по образцу (свой CSV, подложка, словарь, `dictGet` в отчете).  
+Проверка: обогащенный отчет; неатомарность обновления словаря на двух нодах — дополнительное наблюдение (спека, раздел 12).
+
+**14. Инвариант позиций: недостающая проверка.**  
+Урок: равенство «цена × количество = items_total» проверяет, не исказил ли молчаливый разбор данные. Сейчас это равенство проверяют вручную, хотя ему нужно постоянное место в контуре DQ.  
+Материал: комментарий в `sql/dds/order_rebuild.sql` («постоянное место такой проверки — контур DQ этапа 4; пока она делается руками»), образцы `sql/dq/*_vs_dds.sql`, `dags/dq_check.py`.  
+Форма: построить свое — новая проверка по образцу существующих пяти.  
+Проверка: проверка обязана уметь краснеть — испортить позицию руками и увидеть красное (`docs/architecture/testing.md`).
+
+**15. Сверка слоя с источником по дню.**  
+Урок: трансформация выполняет заданное правило, но сама не замечает, что часть данных не приехала. Это обнаруживает отдельная сверка слоя с источником.  
+Материал: `docs/architecture/etl.md`, «Чего конвейер о себе не знает» (три слепых пятна и лекарство: счет заказов и поздний `updated_at` с обеих сторон).  
+Форма: построить свое — вторая самодельная DQ-проверка.  
+Проверка: снести часть дня в ODS-окне — проверка краснеет, конвейер сам не замечал.
+
+## DM — витрины
+
+**16. Пять домашек DM (готовое ядро).**  
+Урок: готовые ТЗ уже содержат пять отдельных уроков (`docs/labs/README.md`): `events_enriched_v` показывает, что слой задает контракт, а не копирует данные; `top_pages_daily` меняет зерно, материализует витрину и включает ее в конвейер; `session_overview` учит хранить слагаемые вместо средних и не складывать уникальные значения, даже если на текущих данных результат совпадает; `dq_errors_daily` показывает, что у брака есть собственный день и срок жизни, а витрина может пережить источник; `utm_effectiveness` объясняет, зачем в имени нужно предупреждение `declared_`.  
+Материал: пять готовых ТЗ в `docs/labs/README.md`.  
+Форма: построить свое по ТЗ.  
+Проверка: `dags/homework_check.py` + `sql/dq/*_vs_dds.sql` (полное внешнее соединение с независимым ответом).
+
+**17. Свой дашборд в Superset (готовая необязательная лаба).**  
+Урок: пользовательские объекты BI хранятся отдельно от стендовых и переживают перезапуск. Стендовые объекты при импорте перезаписываются.  
+Материал: `docs/labs/superset-dashboard.md`, `docs/architecture/superset.md`.  
+Форма: построить свое.  
+Проверка: глазами — счетного инварианта у раскладки панелей нет.
+
+**18. Инкремент против пересборки (#149, повышенная сложность).**  
+Урок: чтобы обновлять меньше данных, приходится хранить историю изменений. Полная перезагрузка эту историю стирает.  
+Материал: `sql/dm/daily_traffic_rebuild.sql` (полный пересчет), `docs/architecture/dm.md`, «Ритм пересборки» и отклоненный вариант; момент `first_matched_at` — из сюжета 12.  
+Форма: построить свое (инкрементальная альтернатива рядом со стендовой).  
+Проверка: бесплатный контроль — результат обязан совпасть с эталонной витриной `dm.daily_traffic_v`.
+
+**19. Вычитание стендовых витрин.**  
+Урок: при сверке двух источников нужен `GLOBAL FULL OUTER JOIN` с подзапросами с обеих сторон, `join_use_nulls` и явный приоритет классов. Значение с отсутствующей стороны должно остаться `NULL`, а не превратиться в ноль.  
+Материал: `sql/dm/purchase_vs_orders_rebuild.sql` (и соседние `revenue_daily_*`, `daily_traffic_*`), `docs/architecture/dm.md`.  
+Форма: вычитание — с оговоркой: запросы `sql/dq/*_vs_dds.sql` лежат открыто и почти дословно повторяют рецепт витрины. Предупреждение из `docs/labs/README.md` («открыв их до того, как задание сделано, ты обменяешь урок на готовый SQL») здесь особенно важно.  
+Проверка: `dq_check`, группа `marts_vs_dds` + `classes_vs_inventory`.
+
+## BI — Superset (сюжеты сверх готовой лабы)
+
+**20. Ловушка ноды 2.**  
+Урок: забытый `ON CLUSTER` и представление над локальной таблицей могут проявиться только в дашборде. Superset намеренно читает ноду 2, а DDL запускается с ноды 1.  
+Материал: `docs/architecture/superset.md`, «Устройство зоны»; спека, «Роли нод».  
+Форма: расследование-опыт (создать объект без `ON CLUSTER`, открыть дашборд).  
+Проверка: своя же находка и починка.
+
+## Поперек слоев
+
+### Airflow-переобработка по дневным партициям
+
+**21. Переиграть день X.**  
+Урок: объем повторного прогона определяется состоянием хранилища. После падения конвейеру не нужно помнить параметры прошлого запуска: он ищет первую несобранную дату, а не последнюю собранную.  
+Материал: `sql/dds/order_scope.sql` и `session_scope.sql` (окно + хвост от первой дыры, `GLOBAL NOT IN`), `dags/dds_transform.py` (день — отдельная размноженная задача замены), `docs/architecture/etl.md`.  
+Форма: расследование-опыт — снести партицию дня в `dds.session_rep`, запустить `etl_pipeline` без параметров, увидеть, как объем сам нашел дыру.  
+Проверка: `dq_check` зеленый, день вернулся тем же (детерминированный чекан).
+
+**22. Атомарность — пошардовая.**  
+Урок: `REPLACE PARTITION` заменяет данные в локальных таблицах по одному шарду. Если одна из двух замен завершится ошибкой, половина дня останется старой. Сам конвейер этого не заметит, поэтому нужна отдельная сверка.  
+Материал: `sql/dds/order_replace.sql` (комментарий о границе обещания), `docs/architecture/etl.md`, «Чего конвейер о себе не знает»; правило донора — `sql/ddl/45-dds-tables.sql`.  
+Форма: расследование (в паре с сюжетом 15).  
+Проверка: `purchase_vs_orders_vs_dds` или самодельная сверка по дню.
+
+### Сверка purchase vs orders (классы A–D)
+
+**23. Воронка подтверждений и недосчет трекера (#186, класс B).**  
+Урок: со стороны трекера потерянное событие можно обнаружить только по разрыву воронки между `/confirmation` и `purchase`. Отсюда правило: поведение считаем по трекеру, деньги — по бэкенду.  
+Материал: `lost_event` в `dm.purchase_vs_orders_v`, события дня в `dds.event_v`; механика — `docs/architecture/orders/fate.md` («потеря точечная»).  
+Форма: расследование.  
+Проверка: оцененный недосчет сходится с долей `lost_event` закрытых дней.
+
+**24. Бизнес-дубль и наивная выручка (#187, класс D).**  
+Урок: движок удаляет технические дубли, а бизнес-дубли приходится определять самим — по `purchaseID`, а не по совпадению строк. `ReplacingMergeTree` не удалит дубль с новым `WatchID`, и это правильное поведение.  
+Материал: `duplicate_event`, свертка по `purchase_id[1]` в `sql/dm/purchase_vs_orders_rebuild.sql`; `fate.md` («дубль сюжетный»).  
+Форма: расследование — наивный `SUM` против дедуплицированного.  
+Проверка: разница равна вкладу дублей; сверка с `dm.revenue_daily_v`.
+
+**25. Дельта суммы объясняется сравнением позиций (класс C).**  
+Урок: `amount_delta` обозначает конкретное расхождение, а не случайный шум. Его можно до копейки объяснить вычеркнутой позицией, если разобрать вложенный JSON и применить `ARRAY JOIN`. Ради этого навыка позиции и разбираются.  
+Материал: `amount_delta` в сверке, массивы `product_*` события против `item_*` заказа; `fate.md` («дельта — вычеркнутая позиция»).  
+Форма: расследование.  
+Проверка: найденная позиция и ее полная стоимость равны дельте.
+
+**26. Две дороги отмены и история версий (класс A).**  
+Урок: текущее состояние заказа не сохраняет его историю. Различить случаи «оплачен и отменен» и «отменен неоплаченным» можно только по следам: физическим версиям ODS до слияния и сырью STG, пока оно хранится трое суток.  
+Материал: `fate.md`, «Что из двух дорог видно»; `ods.order_dist`, `stg.orders_raw_dist`; выручка дня, которая выросла и убыла.  
+Форма: расследование с ограничением по времени — часть случаев неразличима принципиально, и признать это тоже урок.  
+Проверка: списки заказов по дорогам, сверенные с историей версий.
+
+### Опоздания и закрытие дня
+
+**27. Опоздавшие заказы и закрытое окно (#188).**  
+Урок: отчет за день зависит от момента расчета. День можно считать закрытым, когда источник уже не способен его изменить. Поэтому опись хранит счетчики классов только для закрытых дней.  
+Материал: `awaiting_order` в `dm.purchase_vs_orders_v`, задержка слепков D+1/D+2 (`fate.md`, «Опоздание»), `data/world-inventory.json` (счетчики `orders` только у дней с закрытым окном), возврат `awaiting_order`-дней в объем — `sql/dm/purchase_vs_orders_scope.sql`.  
+Форма: расследование по ходу проживаемых дней.  
+Проверка: вчерашний отчет, не сошедшийся утром, сходится завтра; разность слепков называет опоздавших.
+
+**28. Дыхание выручки.**  
+Урок: значение выручки за день меняется, пока день внутри окна изменяемости, а после выхода из окна фиксируется. Эти изменения видны как повторные пересборки партиции.  
+Материал: `dm.revenue_daily_v` по ходу дней, окно из ярлыка `snapshot_date` (`sql/dm/revenue_daily_scope.sql`), K = 7 — константа мира.  
+Форма: расследование-наблюдение (снять один день несколько раз).  
+Проверка: за окном значение больше не меняется.
+
+### Мониторинг и runbook
+
+В репозитории пока нет runbook для случаев «keeper упал / DDL повис». Спека оставляет его в хвосте этапа 9 вместе с `system.text_log` (ADR 0002), потому что такой документ должен опираться на реальный опыт. Поэтому менти может написать runbook сам: по шагам сломать сценарий, записать наблюдения и оставить стенду документ, которого сейчас не хватает.
+
+**29. Keeper — общая память кластера.**  
+Урок: без keeper останавливаются DDL и репликация. На дашборде это бывает видно раньше, чем в ошибках запросов. Читаемый путь в keeper помогает понять, какие данные он хранит и за что отвечает.  
+Материал: панель keeper и очередь DDL в `docs/architecture/monitoring/cluster.md`, `system.zookeeper` (читаемый путь — `docs/architecture/storage.md`, «Путь реплицированных таблиц»), `make smoke` / `make check-clickhouse`.  
+Форма: расследование-опыт «посмотрели — сломали — увидели — вернули» (остановить keeper), итог — свой runbook.  
+Проверка: возврат к зеленым целям `make`; шаги записаны.
+
+**30. Повисший DDL.**  
+Урок: каждый запрос `ON CLUSTER` проходит через keeper. Очередь распределенных DDL показывает, дошел ли запрос до обеих нод и что ответила каждая из них.  
+Материал: `system.distributed_ddl_queue`, панель «Распределенный DDL» (`cluster.md`: единственная панель без `clusterAllReplicas` — и почему).  
+Форма: расследование-опыт (DDL при недоступной второй ноде, таймаут `ON CLUSTER`).  
+Проверка: запись в очереди со статусом по нодам; починка доводит до `Finished`.
+
+**31. Мониторинг сам стоит денег.**  
+Урок: запросы Grafana попадают в `system.query_log` вместе с запросами людей. Самый частый клиент хранилища — сам мониторинг. Если отфильтровать его запросы, стоимость наблюдаемости станет невидимой.  
+Материал: `docs/architecture/monitoring/queries.md` (панель «Кто спрашивает», строки начала и конца, куски шардов в панели ошибок).  
+Форма: расследование.  
+Проверка: собственное объяснение верха списка тяжелых запросов.
+
+**32. Свежесть второго источника — пила, а не линия.**  
+Урок: возраст заказов растет в течение дня и резко уменьшается после нового слепка. Так устроен источник; это не признак деградации. Для панелей свежести, потока и брака выбираются разные слои данных. Если выбрать неверный слой, панель даст правдоподобный, но ложный ответ.  
+Материал: `docs/architecture/monitoring/data.md` (почему свежесть — ODS, поток и брак — сырье, окно доли брака).  
+Форма: расследование.  
+Проверка: предсказать форму графика до взгляда на него.
+
+### За границей лаб — опорные точки лекций
+
+Спека (раздел 12) оставляет несколько сюжетов для лекций и не включает их в лабораторные работы: `Sign` и CollapsingMergeTree (почему на стенде `sum(Sign)` равен `count()`, а в бою нет), «как выбирают топологии в бою», идентичность «как в бою» (`setUserID`, вероятностная склейка, identity graph), анти-паттерны ключа шардирования. Последний сюжет уже входит в домашние задания DM как требование защитить выбранный ключ (`docs/labs/README.md`).
+
+## Гипотеза «вычитание + DQ» для нижних слоев
+
+В #148 предложено удалить SQL трансформаций потока и написать его заново. Владелец уточнил, что даги менять не нужно: это несущая инфраструктура. Обратную связь дают инварианты, которые не зависят от реализации слоя. Ниже каждый поток проверяется отдельно: что можно отдать на переписывание, что должно остаться, чем проверять результат и где заканчивается эталон.
+
+На всю таблицу влияют два общих факта:
+
+- `homework_check` покрывает только пять витрин DM. `dq_check` содержит пять проверок, но внешний эталон есть лишь у двух: `sessions_vs_reference` использует чужой чекан `VisitID` из `ods.event_v`, а `classes_vs_inventory` — опись мира. Три проверки `*_vs_dds` пересчитывают витрину из DDS по тому же рецепту. Они находят ошибку в сборке витрины, но не ошибку в DDS, потому что обе стороны читают один слой.
+- Все сверки читают таблицы `_dist`, поэтому их агрегаты не зависят от раскладки (спека, раздел 6). Если строка попала не на свой шард, счетные проверки останутся зелеными. Это ловит только пересчет ключа шардирования по `hostName()` (прием из `docs/architecture/storage.md`, замер #137). Такой пересчет нужно явно включать в ТЗ каждого вычитания.
+
+### По потокам
+
+**События STG (прием).** На переписывание этот участок не отдается. Здесь почти нет трансформации: `stg.hits_raw_mv` перекладывает колонки (`sql/ddl/40-stg-views.sql`). При этом пересоздание матвью на работающем стенде незаметно пропускает ближайшие сообщения (замер в `storage.md`, «Что проверено»). Чтец, таблицы сырья и матвью остаются несущей стеной. Урок этого участка раскрывают расследования из сюжетов 1–5.
+
+**События STG → ODS (разбор).** Вся логика — в DDL, в паре матвью `sql/ddl/30-ods-views.sql`; отдельных файлов событий в `sql/ods/` нет. Удаление и пересоздание этих матвью остановит прием и снова создаст зазор с пропущенными сообщениями. Поэтому обычное вычитание здесь не подходит. Рабочая форма — **«собери рядом»**: выполнить пакетный `INSERT SELECT` из сырья в собственную таблицу по срезу `_load_ts`, а затем построчно сверить результат с нетронутым `ods.event_v`. Эталоном служат стендовый ODS и подневный счет против описи (`make check-clickhouse`). Однако опись проверяет только количество и только для покрытых ею дней. Содержимое неопорных колонок остается без независимой проверки: неверно разобранные UTM или браузер нигде не покраснеют, потому что витрины сверяются с DDS, а DDS читает ODS. Срок работы тоже ограничен: сырье хранится трое суток.
+
+**Заказы STG (забор, `sql/stg/orders_raw_load.sql`).** Формально трансформация вынесена в отдельный файл, но ее учебный смысл сводится к перекладке колонок, а цена ошибки велика. Офсеты коммитятся при чтении, поэтому неверный повтор унесет слепок до следующего переигрыша дня через пульт. Этот участок остается стеной. Эталон описи — хеш байтов слепка — проверяет топик, но не сам забор.
+
+**Заказы STG → ODS (`sql/ods/order_parse.sql`).** Вычитание возможно с оговоркой. Это пакетный шаг, идемпотентный по `_load_id`: повтор не меняет `ods.order_v` («Что проверено» в `orders/ingestion.md`). Брак обрабатывается отдельной целью, а слепок можно вернуть переигрышем дня. Обратную связь менти собирает сам: проверяет равенство «сырье среза = годные + брак» по `_load_id`, а текущее состояние сверяет с `argMax` по `updated_at` из сырья. Ниже по течению результат проверяет `classes_vs_inventory` через DDS и витрину. Слабое место — ветвь брака. Чистый мир не производит брак, поэтому отрицание предиката останется непроверенным, пока менти сам не подложит по строке каждого класса. Готовый рецепт есть в `orders/ingestion.md`, «Риски и проверка»; после опыта данные нужно обязательно убрать.
+
+**DDS сессия (`session_scope` / `rebuild` / `replace`).** Это лучший поток для вычитания: здесь гипотеза подтверждается без дополнительных условий. Эталон `VisitID` внешний, а `sessions_vs_reference.sql` считает чужой чекан и не повторяет алгоритм нарезки. Ошибиться можно в важных местах: в полном порядке окон, границе суток в `PARTITION BY`, детерминированном чекане и расчете объема из позиции мира. Эталон заканчивается на атрибутах строки. Сверка работает на зерне кука × день и проверяет только число сессий. Поэтому неверные границы, длительность, вход, выход или UTM могут пройти зеленым. `session_overview` из `homework_check` тоже согласится, потому что сверяет витрину с тем же слоем. Вторая ступень обратной связи — поштучная сверка границ по `VisitID` из сюжета 11, которую менти пишет сам.
+
+**DDS заказ (`order_scope` / `rebuild` / `replace`).** Вычитание возможно при условии: сначала нужно построить недостающую проверку. Косвенный эталон уже есть. `classes_vs_inventory` ловит потерянные заказы и неверные статусы закрытых дней, а `purchase_vs_orders` проверяет `items_total`. Но независимо не проверяются разбор массивов `item_*` и время в поясе `Europe/Samara`. Выручка сойдется сама с собой, а счетчиков выручки в описи намеренно нет (спека, раздел 8). Стенд уже подсказывает решение: до вычитания нужно реализовать инвариант «цена × количество = items_total» из сюжета 14. Последовательность «сначала сторож, потом ломать» сама становится частью урока.
+
+**DDS карта идентичностей (`identity_map_rebuild.sql`).** Для чистого вычитания этот поток не подходит: независимого эталона нет. `daily_traffic_vs_dds` читает карту с обеих сторон, поэтому пустая или задвоенная карта пройдет проверку. Счетчики идентичности в опись не входят (спека, раздел 8). Менти может сам написать слабые инварианты: `known_users <= visitors` и «каждая пара подтверждена покупкой и заказом». Они проверят допустимость пар, но не их полноту. Подходящие формы — «собери рядом и сверь со стендовой картой» либо вычитание вместе с самодельной проверкой, которая честно названа неполной.
+
+**DM стендовые витрины.** Формально это самый защищенный участок: `dq_check` независимо пересчитывает каждую витрину. На деле проверка содержит готовый ответ: `revenue_daily_vs_dds.sql` дословно повторяет рецепт витрины. Вычитание возможно как сюжет 19, но только с предупреждением из `docs/labs/README.md` о цене подглядывания.
+
+### Сводная таблица
+
+| Поток | Отдать на переписывание | Несущая стена | Обратная связь | Где кончается эталон |
+|---|---|---|---|---|
+| События STG | ничего | чтец, сырье, `hits_raw_mv` | опись (счет) | все, кроме счета |
+| События STG→ODS | «собери рядом», не вычитание | обе матвью, `*_errors` | стендовый ODS рядом, опись | содержимое неопорных колонок; окно сырья 3 суток |
+| Заказы STG | ничего | чтец, забор | хеш слепка в описи | сам забор |
+| Заказы STG→ODS | `order_parse.sql` | `*_errors`, чтец | баланс среза по `_load_id`, `argMax(updated_at)`, опись классов | ветвь брака — пока не подложен брак руками |
+| DDS сессия | `session_*` (все три) | донор, DDL, даг | `sessions_vs_reference` (внешний эталон) | атрибуты строки — нужна поштучная сверка |
+| DDS заказ | `order_*` (все три) | донор, DDL, даг | опись классов, `items_total` в сверке | разбор позиций и пояс — сначала сюжет 14 |
+| DDS карта | только с оговорками | DDL, даг | нет независимой | почти сразу; форма — «собери рядом» |
+| DM витрины | `revenue/pvo/traffic` | доноры, DDL, даг | `dq_check` целиком | ответ лежит в самой проверке |
+
+### Вывод
+
+Гипотеза «вычитание + DQ» подходит не для всех нижних слоев. Без оговорок она работает только для сессий DDS: там есть внешний эталон, настоящие места для ошибок и проверка, которая не содержит готового решения.
+
+Для заказов DDS и разбора заказов ODS нужна последовательность «сначала построй сторожа, потом ломай». Недостающие инварианты — сюжеты 14 и 15, а также баланс среза — сами входят в учебный материал. Их нужно построить до вычитания.
+
+STG и прием событий нельзя отдавать в форме «удали и перепиши»: код там служит несущей частью стенда. Для этих участков подходят расследования и форма «собери рядом».
+
+У всех счетных проверок остается общая дыра — раскладка по шардам. Поэтому пересчет ключа по `hostName()` должен входить в ТЗ каждого вычитания отдельной строкой.

docs/specs/2026-07-30-stand-v2-realism.md

@@ -138,8 +138,9 @@ Ecommerce (заполнены только у торговых событий):
 | `ecommerce` | String — сырой JSON события, как отдаёт Метрика (кандидат будущей лабы: сырое против разобранного) |
 
 `add_to_cart` несёт массивы `product*` с одним товаром; `purchase` — состав
-заказа и блок `purchase*`. Выручка у клиента — во Float64, как у Метрики:
+заказа и блок `purchase*`. Выручка приходит JSON-числом Float64, как у
-это не недосмотр, а часть урока о расхождениях (см. раздел 4).
+Метрики. ODS один раз нормализует деньги в `Array(Decimal(18, 2))`, не меняя
+формат источника; DDS наследует тип хранения без нового вычисления.
 
 ### 1.3 Ключи и движки
 
@@ -210,9 +211,9 @@ Ecommerce (заполнены только у торговых событий):
   ключей совпадает с порядком полей в таблице контракта, у позиции — `sku`,
   `qty`, `price`: так байты воспроизводимы без сортировки ключей. Разница с
   кликстримом намеренна: там значения `purchaseRevenue` приезжают JSON-числами
-  и разбираются как `Array(Float64)`, а бэкенд передаёт деньги строками для
+  Float64, а бэкенд передает деньги строками. На границе ODS оба источника
-  точного `Decimal`. Это показывает расхождение представлений денег в двух
+  становятся `Decimal(18, 2)`: клиентское число разбирается сразу, без
-  источниках.
+  промежуточного Float64 в хранилище.
   Запись собирает явная функция существующего канонического сериализатора:
   один словарь с вложенным списком и один `orjson.dumps`, без универсального
   слоя кодеков.
@@ -220,18 +221,21 @@ Ecommerce (заполнены только у торговых событий):
   [исследовании формата](../research/2026-08-16-order-snapshot-wire-format.md).
 
 - `ods.order` принимает версии заказа в
-  `ReplacingMergeTree(updated_at)`: `ORDER BY order_id`, партиция по дню
+  `ReplacingMergeTree(snapshot_date)`: `ORDER BY order_id`, партиция по дню
-  неизменного `created_at`, шардирование по `cityHash64(order_id)`.
+  неизменного `created_at`, шардирование по `cityHash64(order_id)`. Дата
-  `snapshot_date` остаётся датой наблюдения источника, но не задаёт публикацию
+  слепка служит колонкой версии: выживает строка с максимальной
-  или идемпотентность. Физическое чтение может видеть несколько версий;
+  `snapshot_date` ([ADR 0014](../adr/0014-order-version-snapshot-date.md)).
-  `ods.order_v` возвращает точное текущее состояние. Устройство модели DDS и
+  Дата не доказывает полноту принятой порции, поэтому ODS не заменяет партицию
-  способ её материализации решаются отдельно.
+  слепка целиком. Физическое чтение может видеть несколько версий;
+  `ods.order_v` возвращает точное текущее состояние. В DDS одна строка хранит
+  один заказ с позициями в типизированных массивах; физическая модель и
+  пакетное наполнение описаны в [доке заказа](../architecture/dds/order.md).
 
   Пропущенный день ничего не ломает, следующий слепок самовосстанавливает.
-- `items` остаётся сырой строкой JSON в ODS. Разбирать позиции следует на
+- `items` остаётся сырой строкой JSON в ODS. Позиции разбираются на границе
-  границе ODS → DDS, но их представление определяется вместе с будущей моделью
+  ODS → DDS в типизированные массивы строки заказа. Это остаётся носителем
-  заказов. Это остаётся носителем навыка «вложенный JSON в ClickHouse», не
+  навыка «вложенный JSON в ClickHouse», не превращая приём в преждевременную
-  превращая приём в преждевременную модель данных.
+  модель данных.
 - Статусы держим все три: смена `created` → `paid` и есть причина «дыхания»
   выручки внутри окна; сужение до двух — резервный срез 1. На выходе из окна
   заказ либо `paid`, либо `cancelled`: неоплаченного отменяют, «навсегда
@@ -261,7 +265,7 @@ CSV в репозитории (`data/catalog/products.csv`: `sku`, `name`, `cate
 | | Расхождение | Механика в генераторе | Ориентир доли |
 |---|---|---|---|
 | A | Отмена | заказ дошёл до `cancelled`, `purchase` остался | ~5% заказов — отменённые вообще, обе дороги отмены вместе |
-| B | Потерянное событие | заказ есть, `purchase` не доехал | ~3% |
+| B | Потерянное событие | заказ есть, `purchase` не доехал | бросок 3%, наблюдаемых ~1,8%: часть маячков защищена парами склейки, часть уходит в отмену приоритетом |
 | C | Дельта суммы | вычеркнутая позиция: товара не оказалось в наличии, у заказа на одну позицию меньше, чем в клиентских массивах. Сверка приведена к сравнимой базе (`items_total`, не `total`); `amount_delta` — остаток, не объяснённый этим приведением, и сравнением позиций он объясняется — на этом стоит урок класса | ~1–2% |
 | D | Дубль события | повторный `purchase` от обновления `/confirmation`: новый `WatchID` с тем же `purchaseID` — бизнес-дубль, не технический; дедуп ReplacingMergeTree его не съедает и не должен | ~2% |
 
@@ -270,8 +274,9 @@ CSV в репозитории (`data/catalog/products.csv`: `sku`, `name`, `cate
 
 Пятое — **опоздание** — бесплатно даёт формат доставки: часть заказов
 впервые появляется в слепке D+1/D+2 («вчера не сходилось, сегодня сошлось»),
-ориентир ~10%. Точные доли фиксируются при пересборке эталонного мира;
+ориентир ~10%. Точные доли зафиксированы замером на каноническом мире
-опись хранит счётчики наблюдаемых классов после приоритета — в заказах и
+(28 дней, 2026-08-30, #194) — запись в «Что проверено»
+[карты проверок](../architecture/testing.md); опись хранит счётчики наблюдаемых классов после приоритета — в заказах и
 только по дням с закрытым окном (раздел 8).
 
 Не берём: сироту-фрод (`purchase` есть, а заказа не будет никогда) —
@@ -282,7 +287,7 @@ CSV в репозитории (`data/catalog/products.csv`: `sku`, `name`, `cate
 под именем `declared_*` там, где атрибуция без трекера невозможна (UTM);
 слово `declared` в имени — сигнал «это заявка клиента, не деньги
 отчётности». Оно выучивается на конфликте: суммы не сойдутся, менти сам
-раскопает почему (Float64 против Decimal, промокод, доставка, отмены).
+раскопает почему (состав позиций, промокод, доставка, отмены).
 
 ## 5. Анонимность и склейка идентичностей
 
@@ -292,12 +297,19 @@ CSV в репозитории (`data/catalog/products.csv`: `sku`, `name`, `cate
 - **Карта соответствий кука↔пользователь** строится трансформацией из уже
   существующего моста: `purchase`-событие (`ClientID`, `purchaseID`) ↔ заказ
   (`order_id`, `user_id`). Ни новых полей, ни нового транспорта.
-- Форма и место карты: таблица `dds.identity_map`
+- Форма и место карты: `dds.identity_map_rep` хранит пару `client_id` UInt64,
-  (`client_id` UInt64, `user_id` UInt64, `first_matched_at` DateTime),
+  `user_id` UInt64 и координаты собственной загрузки `_load_id`, `_load_ts` в
-  ReplacingMergeTree, `ORDER BY (client_id, user_id)`, шардирование по
+  `ReplicatedReplacingMergeTree(_load_ts)` с `ORDER BY (client_id, user_id)`.
-  `cityHash64(client_id)` — тем же выражением, что события (иначе ко-локации
+  `dds.identity_map_dist` шардирует по `cityHash64(client_id)` — тем же
-  нет); ко-локация делает обогащение витрин локальным;
+  выражением, что события; ко-локация позволяет обогащать витрины локально.
-  заказы при сборке карты подтягиваются через GLOBAL JOIN.
+  Публичный интерфейс `dds.identity_map_v` перечисляет колонки явно и прячет
+  `FINAL`. `first_matched_at` в стенде нет: у него нет читателя; история
+  склейки оставлена самостоятельной работе в issue #145.
+- Карта пересобирается пакетно после модели заказов: все `purchase` из
+  `dds.event_v` соединяются с текущими заказами `dds.order_v` через
+  `GLOBAL JOIN`, статус заказа связь покупателя с кукой не отменяет. Каждый
+  запуск пишет полный текущий набор различных пар; предыдущий результат не
+  служит источником следующего.
 - **N:1**: часть покупателей покупает с двух кук («телефон и ноутбук») —
   параметр мира; значение фиксирует эта спека: 15%, детерминировано
   от seed. Ядро лабы:
@@ -357,19 +369,32 @@ CSV в репозитории (`data/catalog/products.csv`: `sku`, `name`, `cate
   ошибка в `*_errors`, а не молчаливые нули: имена CamelCase регистрозависимы,
   опечатка иначе не падает.
 - **Политика соединений**: по ключу ко-локации — обычное соединение с
-  комментарием, почему локальный результат корректен; по любому другому ключу
+  комментарием, почему локальный результат корректен; если публичные
-  — только явный GLOBAL; `NOT IN` — только `GLOBAL NOT IN`. Сверка
+  представления скрывают ко-локацию — решение записывается рядом с витриной.
+  По любому другому ключу — только явный GLOBAL; `NOT IN` — только
+  `GLOBAL NOT IN`. Сверка
   `purchase`↔заказ —
   легитимная GLOBAL-витрина (заказы малы).
 - **Конвейер без TRUNCATE**: поток версий — в ReplacingMergeTree, точное чтение
   — через `FINAL` или равносильный выбор последней версии; батчевая
   переобработка нижележащих объектов — по дневным партициям
   (`DROP/REPLACE PARTITION ON CLUSTER`); `TRUNCATE ... ON CLUSTER` в конвейере не
-  применяется вовсе — полный сброс стенда делается `make clean && make up`, то
+  применяется вовсе: обычная переобработка ограничена партицией, а полное
-  есть вместе с томами. `DROP/REPLACE PARTITION` работает только по
+  восстановление данных — базами слоёв в следующем пункте. `DROP/REPLACE
-  **локальным** таблицам ON CLUSTER, не по Distributed; замена через
+  PARTITION` работает только по **локальным** таблицам ON CLUSTER, не по
-  DROP+INSERT неатомарна — дашборд в середине прогона честно моргает (это
+  Distributed; замена через DROP+INSERT неатомарна — дашборд в середине прогона
-  осознанная цена, не баг).
+  честно моргает (это осознанная цена, не баг).
+- **Область очистки следует за областью состояния**: обычная разработка не
+  требует пустых томов. Сначала пересоздаётся затронутый объект, партиция или
+  база слоя; если нужен целиком чистый мир, пересоздаются прикладные базы
+  ClickHouse, топики и позиции их потребителей Kafka, затем заново заливаются
+  данные. Сами службы и их тома сохраняются. `make clean` нужен, только когда
+  требуется удалить состояние вне прикладного мира либо проверить запуск именно
+  с пустых томов. Перед таким сбросом агент называет это состояние и объясняет,
+  почему более узкой очистки недостаточно. «Так проще и надёжнее» не считается
+  обоснованием. Обязательный `make clean` перед каждой приёмкой отвергнут: он
+  стирает следы неисправности и превращает редкий холодный запуск в постоянную
+  цену разработки.
 - **Поздние заказы поглощает ODS** как новую версию `order_id`. Как их
   подхватывают материализованные объекты DDS и DM, решается вместе с их моделью,
   а не при проектировании приёма.
@@ -411,16 +436,21 @@ README.
 | STG | `stg.orders_raw_kafka`, `stg.orders_raw`, без MV | сырые строки слепка; чтец на ноде 1, забирает пакетный шаг |
 | ODS | `ods.event` (+`_errors`), `ods.event_v` | типизированные версии событий, брак и точное актуальное состояние |
 | ODS | `ods.order` (+`_errors`), `ods.order_v` | типизированные версии заказов, брак и точное текущее состояние |
-| DDS | `dds.session` | сборка сессий из событий (наследник `dds.click`) |
+| DDS | `dds.session_rep` / `_dist`, `dds.session_v` | физическая сборка сессий и её публичный интерфейс |
-| DDS | `dds.event_v` | представление над `ods.event`: snake_case-имена, расшифровка кодов `DeviceCategory`; витрины DM читают его, а не ODS напрямую |
+| DDS | `dds.event_v` | представление над `ods.event_v`: snake_case-имена, расшифровка кодов `DeviceCategory`; витрины DM читают его, а не ODS напрямую |
-| DDS | модель заказов | зерно, связи и материализация проектируются на этапе DDS |
+| DDS | `dds.order_rep` / `_dist`, `dds.order_v` | текущая модель заказа и её публичный интерфейс |
-| DDS | `dds.identity_map` | карта кука↔пользователь |
+| DDS | `dds.identity_map_rep` / `_dist`, `dds.identity_map_v` | физическая карта кука↔пользователь и её точный публичный интерфейс |
 | DIC | подложка `products_file` и словарь `products` | каталог из CSV, вне цепочки слоёв ([ADR 0012](../adr/0012-dictionary-home.md)) |
 | DM | витрины `dm.*_v`, `dm.dq_summary` | см. ниже |
 
 У каждой таблицы слоя — пара из локальной и распределённой, имена по конвенции
 суффиксов; она же задаёт служебные колонки, нарезку и срок хранения сырья —
 см. [доку хранилища](../architecture/storage.md).
+Потребительские запросы и витрины читают сущности DDS через `_v` с явным
+списком колонок; `_rep` и `_dist` служат загрузке, диагностике и обслуживанию.
+Договор держится конвенцией, а не правами: модель доступа описана в
+[ADR 0007](../adr/0007-clickhouse-access.md), договор чтения — в
+[доке хранилища](../architecture/storage.md), «Имена объектов».
 
 Заказы принимаются **пакетным забором** ([ADR
 0008](../adr/0008-order-ingestion.md), [ADR
@@ -428,17 +458,13 @@ README.
 матвью к нему не привязана, и сырьё забирает шаг, которым управляет Airflow —
 одно прямое чтение вставляет порцию в `stg.orders_raw` с `_load_id` запуска.
 Один следующий `task_id` двумя последовательными запросами пишет годные строки
-и ошибки из того же среза. `ods.order` хранит версии по `updated_at`,
+и ошибки из того же среза. `ods.order` выбирает текущую версию по максимальной
-а не публикует партицию `snapshot_date`. Слой сырья остаётся точкой повтора и
+`snapshot_date` ([ADR 0014](../adr/0014-order-version-snapshot-date.md)). Слой
-разбора одной принятой порции.
+сырья остаётся точкой повтора и разбора одной принятой порции.
-
-Стенд получает от этого два режима приёма рядом, поток и слепок, и сравнение
-из опорных точек раздела 12 переформулировано под них.
 
 Состав служебных колонок задаёт дока хранилища. Спеке важны два следствия:
-`ods.event` и `ods.order` получают метку загрузки `_load_ts`, но у
+`ods.event` и `ods.order` получают метку загрузки `_load_ts`, но версию
-заказа бизнес-версию задаёт `updated_at`; `_load_id` проходит через STG и обе
+заказа задаёт дата слепка; `_load_id` проходит через STG и обе цели ODS. Таблицы
-цели ODS. Таблицы
 `stg.*_raw` хранят метаданные доставки Kafka вместе с именем читавшей ноды —
 без них урок «какая нода читала топик» ненаблюдаем.
 Модельного дня в STG нет: `EventDate` — свойство содержимого, а содержимое
@@ -447,8 +473,8 @@ README.
 Kafka день переигрывается генератором заново: снимок — кэш чистой функции,
 см. [спеку генератора](2026-08-01-generator.md).
 
-`ods.event_v` сохраняет имена, типы и зерно ODS, но скрывает `FINAL` и возвращает
+`ods.event_v` сохраняет имена, типы и зерно ODS, но скрывает `FINAL` и
-актуальную версию события. Будущее `dds.event_v` — другой контракт: оно
+возвращает актуальную версию события. `dds.event_v` — другой контракт: оно
 переводит событие на язык бизнес-модели, в том числе даёт snake_case-имена и
 расшифровывает коды. Это первый на стенде пример правила «слой — это контракт,
 а не обязательно копия данных».
@@ -483,13 +509,20 @@ Kafka день переигрывается генератором заново:
   счётчики `purchases`/`add_to_carts` оживают из таксономии, добавляется
   `declared_revenue` по UTM.
 - **`daily_traffic_v`** — расширяется парой «посетители» / «известные
-  пользователи» (обогащение через `dds.identity_map`, локальное соединение
+  пользователи». Обогащение идет явным `GLOBAL LEFT JOIN` через
-  по ключу ко-локации).
+  `dds.identity_map_v`: опыт на ClickHouse 26.3 показал, что публичные `_v`
+  скрывают ко-локацию от локальной подстановки.
 - `events_enriched_v`, `top_pages_daily_v`, `session_overview_v`,
-  `dq_errors_daily_v` — переезжают на новую модель без смены роли: источник —
+  `dq_errors_daily_v` — переезжают на новую модель без смены роли. Источник
-  `dds.event_v`, не `ods.event`.
+  и зерно у двух из них меняет сама новая модель, и это зафиксировано ТЗ
-- `dm.dq_summary` переводится с TRUNCATE+INSERT на партиционную замену
+  домашек ([`docs/labs/`](../labs/README.md)):
-  (политика «без TRUNCATE»).
+  `session_overview_v` читает `dds.session_v` и поднимается на зерно «день ×
+  срез», потому что визит стал сущностью DDS и витрина его зерна была бы
+  копией сессий; `dq_errors_daily_v` читает таблицы `ods.*_errors`, у
+  которых в DDS представительства нет. Остальные две читают `dds.event_v`,
+  а не `ods.event`.
+- `dm.dq_summary` хранит текущее качество дня и обновляется партиционной
+  заменой (политика «без TRUNCATE»).
 
 Дашборд Superset получает три новых сюжета: выручка по дням и категориям,
 таблица сверки с классами расхождений, пара посетители/известные.
@@ -500,10 +533,11 @@ Kafka день переигрывается генератором заново:
 
 ## 8. Эталонный мир и опись
 
-В git хранится только опись эталонного мира; сам снимок (14 модельных
+В git хранится только опись эталонного мира; сам снимок генерируется на
-дней) генерируется на месте — при `make up` и при проверках (решение
+месте — при `make up` и при проверках (решение развилки «Производительность»
-развилки «Производительность» карты #26, подробности —
+карты #26, подробности — [спека генератора](2026-08-01-generator.md),
-[спека генератора](2026-08-01-generator.md), раздел 5). Опись несёт
+раздел 5). Снимок — 8 дней, совпадает со стартовым миром: обещание в 14 дней
+снято на этапе 7. Опись несёт
 паспорт мира (каноническое зерно, версия генератора), контрольные счётчики
 и хеши по дням; проверки «пустой git diff» и «пересгенерируй день N —
 сравни хеш» живут на ней. Политика версионирования артефакта (бывший туман
@@ -512,16 +546,19 @@ Kafka день переигрывается генератором заново:
 
 - по строке на каждый отправленный слепок — хеш байтов: побайтовое обещание
   «слепок переснимается и даёт те же байты» опись сторожит наравне с днями;
-- заказная сторона: заказы, выручка и счётчики наблюдаемых классов
+- заказная сторона: счётчики наблюдаемых классов расхождений после
-  расхождений после приоритета, в заказах — по дням с закрытым окном
+  приоритета; каждый показывает число заказов и хранится только для дня с
-  (самопроверка лабы сверки; при N сыгранных днях таких дней N − 7);
+  закрытым окном (читатель — техническая проверка `classes_vs_inventory`
+  звена DQ; при N сыгранных днях таких дней N − 7). Отдельных полей для
+  общего числа заказов и выручки в описи пока нет: для них не назван
+  читатель;
 - контрольные числа идентичности не заводятся: uniq известных пользователей
   и число двухкуковых покупателей растут, пока мир едет, а счётчик без
   названного читателя в опись не кладётся
   ([что хранит опись](../architecture/orders/inventory.md)).
 
-Снимок вырастет против v1 (ecommerce-массивы, заказы) — размер проверить
+Размер снимка замерен на этапе 7 — запись в разделе «Что проверено»
-при пересборке.
+[карты проверок](../architecture/testing.md).
 
 ## 9. Оценка объёма исполнения
 
@@ -583,8 +620,8 @@ v2 стартует пустым, поэтому объём ниже — это
    выручка, сверка A+C.
 5. Airflow: `etl_pipeline` (партиционная переобработка).
 6. Расхождения B+D и опоздания; счётчики описи.
-7. Эталонный мир: опись и пересборка снимка, чек-скрипты; CI-генерация
+7. Эталонный мир: опись и пересборка снимка, чек-скрипты. CI-генерация
-   на amd64 и arm64.
+   снята (спека генератора, раздел 5).
 8. Superset-дашборд v2.
 9. Мониторинг и runbook «keeper упал / DDL повис в очереди». Состав дашбордов
    и границы — ADR 0002. Этап идёт не подряд, см. ниже.
@@ -607,9 +644,11 @@ ADR 0002 с приёмочными совпадают почти целиком.
 
 Что гонять на приёмке этапа — строка в [карте
 проверок](../architecture/testing.md), раздел «Какую проверку когда
-запускать»: стенд собирается с нуля и на нём зелены все три цели, которым
+запускать»: на стенде зелены все три цели, которым он нужен, а состояние перед
-нужен стенд. Это гигиена, а не приёмка: она обещает, что этап не сломал стенд,
+проверкой восстанавливается в самой узкой достаточной области. Запуск с пустых
-и молчит о его предмете — дашборд может быть не нарисован, а все три останутся
+томов обязателен только для изменения начальной сборки или постоянного состояния
+служб, а не как общая гигиена этапа. Эти цели обещают, что этап не сломал стенд,
+и молчат о его предмете — дашборд может быть не нарисован, а все три останутся
 зелёными. Свои наблюдаемые критерии каждый этап получает при разбиении в
 /to-tickets. Документация правится в PR этапа (правило AGENTS.md).
 
@@ -619,9 +658,15 @@ ADR 0002 с приёмочными совпадают почти целиком.
   расхождение часов клиент/коллектор — туман карты, вернётся своим тикетом.
 - Лабы и курс: v2 — другой стенд, лабы для него пишутся с нуля отдельной
   работой после этой спеки; редизайн лаб v1 (#7) остаётся в v1 и сюда не
-  переносится. Спека даёт будущим лабам только опорные точки — контрольные
+  переносится. Исключение — домашки слоя DM: ТЗ витрин менти и даг
-  числа описи (сверка, идентичность). Явное следствие: после этапа 9
+  самопроверки забраны в этап 4 резолюцией #135, потому что витрина менти и
-  стенд работает, но учебного пути на нём ещё нет.
+  конвейер, в который она встает, проектируются вместе. Сюда же —
+  необязательная лаба «свой дашборд в Superset» (#197): она стоит на
+  витринах домашек DM и продумана до готового ТЗ в этапе 8, тогда как
+  остальные лабы пока на уровне идей. Единый стиль блока
+  домашек — за работой учебного пути. Спека даёт будущим лабам только
+  опорные точки — контрольные числа описи (сверка, идентичность). Явное
+  следствие: после этапа 9 стенд работает, но учебного пути на нём ещё нет.
 - Инкрементальный ETL (#8) — свой issue.
 - Реплики (2×2), HAProxy, репликационная эксплуатация — в лекцию, не в стенд.
 - TLS между нодами, настоящее хранилище и ротация секретов, внешние учётные
@@ -657,8 +702,6 @@ Kafka Engine на двух нодах снят с этого списка при
 `ReplacingMergeTree`. Проверять то, что заведомо случается и заведомо
 обезврежено, — работа без ответа на конце.
 
-- Поведение соединения двух Distributed-таблиц и `distributed_product_mode` —
-  эмпирически на стенде (хвост #14).
 - Размер артефакта эталонного мира после пересборки.
 - Спорные API (Airflow Datasets/сенсоры, ClickHouse DDL) — перед кодом
   сверять через MCP Context7 (правило AGENTS.md).

docs/specs/2026-08-21-world-lifecycle.md

@@ -0,0 +1,264 @@
+# Жизненный цикл мира: создание и пересоздание ведёт Airflow
+
+Дата: 21 августа 2026 года. Решение и доводы — [ADR 0013](../adr/0013-world-lifecycle.md);
+здесь устройство, которое из него следует.
+
+## Задача
+
+До этой работы начало оси мира собирали трое. Compose создавал топики, применял
+DDL и двумя одноразовыми службами заливал восемь дней. Shell-сценарии ждали,
+пока события доедут до ODS, и разово дёргали даг приёма заказов. Airflow вёл
+мир после стартовой заливки.
+
+Граница владения не совпадала с процессом, и это видно по следствиям. Успешная
+отправка в Kafka выдавалась за созданный мир: `world-init` завершался сразу
+после записи в топик, до приёма сообщений хранилищем.
+Повторный `make up` смешивал подъём служб с повторной заливкой данных. Узкая
+пересборка хранилища сохраняла в Kafka сообщения и офсеты прежнего мира, потому
+что чинила только ClickHouse. Позиция пульта правилась снаружи Airflow — тем,
+кто миром не управляет.
+
+**Чему учит переезд.** Менти видит один наблюдаемый граф, которому принадлежат
+прикладная схема, данные мира и позиция модельного времени, — и Compose,
+который держит только инфраструктуру. Зеленая ветка создания в
+`world_initialize` подтверждает: схема создана, оба источника приняты,
+следующий день известен, слои DDS и DM собраны.
+
+## Решение
+
+Граница владения одна: **Compose отвечает за инфраструктуру; Airflow — за
+прикладной мир.**
+
+Compose держит долгоживущие службы, сети, тома, объявленные файлом учётные
+записи ClickHouse, инициализацию метаданных Airflow и инициализацию Superset.
+
+Airflow держит прикладные топики Kafka, канонический DDL прикладных баз `stg`,
+`ods`, `dds`, `dm`, `dic`, данные стартового мира, их приём и переменную
+`world_position`.
+
+Одноразовых служб `kafka-init`, `clickhouse-init`, `world-init` и
+`world-snapshots` в графе Compose не остаётся. Ни профиля, ни вызова через
+`compose run` им не оставляют: спрятанная за профилем служба — тот же второй
+оркестратор, только менее заметный.
+
+`make` инфраструктурой и ограничивается: поднимает стенд, зовёт нужный даг
+через REST API Airflow и ждёт результата. Shell больше не применяет DDL, не
+запускает генератор и не правит позицию.
+
+### Учётная запись жизненного цикла
+
+Прикладную структуру создаёт и удаляет отдельная учётная запись `lifecycle` с
+ролью `lifecycle_owner`, объявленная тем же файлом, что остальные учётные записи
+([ADR 0007](../adr/0007-clickhouse-access.md)). Ей разрешено администрировать
+прикладные базы — заводить и удалять их и объекты внутри, — читать их и
+выполнять кластерный DDL. Ей разрешено чтение `system.settings`: без него
+драйвер `clickhouse-connect` под официальным провайдером Airflow не открывает
+соединение. Административные запросы к системным базам ей запрещены.
+
+`etl` при этом не расширяется. Право удаления баз нужно редкой операции
+восстановления и остаётся у `lifecycle`. Граница проверяема: при лишнем запросе
+менти увидит в ошибке имя учётной записи и недостающее право.
+
+### Что Airflow получает от репозитория
+
+Каталог `/opt/airflow/world` — то, что нужно для создания мира: `generator/`,
+`data/` и корневой `.dockerignore` смонтированы только для чтения. Из первого
+собирается канонический образ генератора, из второго читается опись мира, а
+последний не пускает в контекст сборки локальные окружения и кэши. Запросы
+стенда приезжают прежним монтированием `sql/`.
+
+Меняющиеся API сверены через Context7 и затем с установленными пакетами
+стенда. Выбраны публичный REST API v2 и ждущий `TriggerDagRunOperator` Airflow,
+сборка образа через `DockerHook.get_conn().build()`, futures `AdminClient` для
+Kafka, `SQLExecuteQueryOperator` для исполняемых SQL-файлов ClickHouse и
+`ClickHouseHook` для запросов, чей результат обрабатывает Python. Оператор сам
+шаблонизирует файл и при `split_statements=True` исполняет выражения по порядку;
+собственный разбор SQL дагу больше не нужен.
+
+## Контракты дагов
+
+Оба дага публичные: без расписания, не на паузе, `max_active_runs = 1`. Их
+запускают руками из интерфейса и командой `make` через REST API.
+
+### `world_initialize` — создать мир, если его нет
+
+Даг безопасен по построению: на готовом мире он ничего не меняет.
+
+1. Читает `world_position` и решает, что делать дальше: инициализировать,
+   успешно завершиться без изменений или покраснеть. Разбор состояний — в
+   таблице ниже.
+2. Создаёт топики: `hits` с двумя партициями, `orders` с одной. Топики идут
+   **до** DDL: чтец ClickHouse начинает читать топик, когда над ним появляется
+   матвью, и топик, созданный брокером сам, приехал бы с одним разделом
+   ([ADR 0008](../adr/0008-order-ingestion.md)).
+3. Применяет канонический DDL из `sql/ddl/` по порядку имён файлов, с ноды 1,
+   учётной записью `lifecycle`. Каждый файл — отдельная последовательная
+   задача `SQLExecuteQueryOperator`; выражения внутри неё исполняются по
+   порядку с `split_statements=True`. Красная задача называет файл и не пускает
+   последующие. Правило «матвью приёма создаётся последней» остаётся за
+   раскладкой файлов и не переезжает в даг.
+4. Собирает канонический образ генератора. Иначе мир мог бы приехать из старого
+   кода: сборкой образа при подъёме больше никто не занимается.
+5. Играет стартовые дни одним прогоном `batch` того же образа.
+6. Ждёт, пока события доедут до ODS. Условие ожидания то же, что у прежнего
+   сценария, и оно точное: сумма строк `ods.event_dist` за даты описи и строк
+   `ods.event_errors_dist` не меньше суммы событий из
+   [`data/world-inventory.json`](../../data/world-inventory.json). «Что-то
+   приехало» условием не считается.
+7. Отправляет слепки заказов вторым прогоном образа — со сдвигом, дни 0…6
+   ([заказы в стартовом мире](../architecture/orders/start-world.md)).
+8. Дергает `orders_ingest` ждущим триггером и продолжает только после его
+   успеха.
+9. Ставит позицию в `WORLD_STARTING_DAYS`: источники приняты, мир уже создан.
+10. Последним шагом дергает `etl_pipeline` ждущим триггером. Конвейер
+    последовательно ждет `dds_transform` и `dm_transform`; отказ слоя красит
+    инициализацию.
+
+Порядок задач связывает проверки: каждый шаг подтверждён предыдущим, а красная
+задача называет место остановки. Ветка "мир уже существует" конвейер не
+запускает: обычный повтор `make up` по-прежнему ничего не меняет.
+
+### `world_recreate` — снести мир и создать заново
+
+Сначала даг выполняет всю разрушительную часть, затем делегирует создание мира.
+
+1. Ставит позицию в `-1`: прежний мир объявлен недействительным раньше, чем с
+   ним что-то произошло.
+2. Удаляет прикладные базы ClickHouse `stg`, `dm`, `dds`, `ods`, `dic` — первым
+   делом, чтобы чтецы Kafka перестали существовать вместе с ними.
+3. Удаляет позиции групп потребителей `clickstream_hits` и
+   `clickstream_orders`, затем топики `hits` и `orders`.
+4. Ставит позицию в `0` — только после успешной очистки.
+5. Дёргает `world_initialize` ждущим триггером и ждёт его результата.
+
+**Общего модуля с шагами двух дагов нет.** Переиспользование здесь — это
+делегирование: пересборка вызывает создание мира целиком. Такой модуль стал бы
+третьим местом с той же последовательностью, а первое же расхождение между
+дагами пришлось бы прятать в его параметрах.
+
+### Сторожа у работников мира
+
+`world_next_day` и `world_live_day` краснеют, если позиции нет либо она меньше
+`WORLD_STARTING_DAYS`. Отказ называет прочитанное значение и следующий шаг:
+поднять стенд или пересобрать хранилище. Выключатель `world_live` своего
+сторожа не получает — он краснеет вслед за работником.
+
+`orders_ingest` сторожа не получает вовсе: его зовёт сама инициализация, когда
+готового мира ещё нет.
+
+## Состояния позиции
+
+`world_position` остаётся единственным состоянием пульта.
+
+| Позиция | `world_initialize` | `world_recreate` | Работники |
+|---|---|---|---|
+| переменной нет | создаёт мир | очищает и создаёт | красный отказ |
+| `-1` | красный отказ: очистка не завершена, повторите `make rebuild-storage` | очищает и создаёт | красный отказ |
+| `0` | создаёт мир | очищает и создаёт | красный отказ |
+| `WORLD_STARTING_DAYS` и больше | мир уже есть: пишет это в журнал и зеленеет | очищает и создаёт | работают |
+
+Значения между `1` и `WORLD_STARTING_DAYS` штатно не возникают: позиция
+становится либо `-1`, либо `0`, либо номером сыгранного дня за стартовым миром.
+Попав на такое значение, `world_initialize` краснеет тем же отказом, что на
+`-1`, и называет прочитанное число.
+
+## Поведение при отказах
+
+**Пересборка упала на очистке.** Позиция остаётся `-1`. Обычный `make up` эту
+поломку не заглаживает: `world_initialize` краснеет и говорит, что мир
+недействителен и пересборку надо повторить. Стенд обязан назвать незавершённую
+очистку вслух и не продолжать работу молча.
+
+**Очистка прошла, создание остановилось до установки позиции.** Позиция
+остаётся `0`. Инициализация детерминирована, поэтому следующий `make up` просто
+пробует её заново — с того же места и с тем же результатом.
+
+**ETL упал после установки позиции.** Мир и оба источника уже готовы, поэтому
+позиция остается в `WORLD_STARTING_DAYS`. После исправления запускают рукой
+`etl_pipeline`: он сам выводит объем из состояния данных. Повторный
+`world_initialize` здесь не поможет: при готовой позиции инициализация уйдет в
+короткую ветку без изменений.
+
+**Позицию в `WORLD_STARTING_DAYS` ставит только успех обоих источников.**
+События доехали, слепки приняты, `orders_ingest` зелёный — тогда и только тогда
+мир считается созданным.
+
+**Порядок очистки Kafka входит в контракт.** Пока живы чтецы
+ClickHouse, они состоят в группах потребителей, и удаление группы недопустимо.
+Поэтому сначала удаляются базы, затем топики.
+
+**Позицию удалили руками на живом мире.** Даг честно зальёт мир заново: сырьё
+в STG удвоится, ODS схлопнет повтор дедупликацией. Условие ожидания на непустом
+ODS истинно сразу — этим оно и ограничено, обещание «доехала именно эта
+заливка» ни один счёт дать не может. Сторожа на этот случай нет: ошибку менти
+делает себе сам и тут же видит.
+
+**Слоты Airflow.** Их четыре. При пересборке `world_recreate` ждет
+`world_initialize`, тот ждет `etl_pipeline`, а конвейер ждет слой. В живом
+режиме такую же цепочку образуют `world_live`, `world_live_day`, `etl_pipeline`
+и слой. В обоих случаях три ожидающие задачи оставляют слою последний слот.
+Одновременная пересборка добавляет ожидания и загоняет стенд в тупик.
+Поэтому пересборка — явная операция обслуживания: оператор ставит `world_live`
+на паузу и даёт работникам доиграть. Предусловие остаётся в документации;
+механизм блокировок стоил бы дороже этой строки.
+
+## Границы
+
+- **`make up` не мигратор схемы.** На готовом мире изменённый DDL не
+  применяется. Обновляет схему явная пересборка `world_recreate` либо
+  адресная правка объекта в разработке. Размен принят с открытыми глазами.
+- **Ни блокировок, ни статуса, ни автоматической паузы.** Предусловие
+  обслуживания названо словами.
+- **`etl` не расширяется**, `orders_ingest` не получает сторожа.
+- **`make clean` сохраняет свой смысл**: полное удаление постоянного состояния
+  стенда. Ни в пересборку, ни в обычную проверку он не входит.
+- **`make generate-batch` и `make generate-live` остаются** — с них снимаются
+  унаследованные зависимости от исчезающих одноразовых служб.
+- Содержание DDL, код генератора и устройство слоёв не меняются.
+
+## Проверка
+
+Цели `make` — обычные: `config-test` и `lint` без стенда, `smoke`,
+`check-clickhouse` и `check-services` на поднятом. Сверх них проверяются
+сценарии, которых у стенда раньше не было.
+
+- **Повторный `make up` на живом мире** проходит быстро и ничего не меняет:
+  позиция та же, счётчики `check-clickhouse` те же, в журнале дага сказано, что
+  мир уже есть.
+- **`make rebuild-storage`** возвращает канонический мир: позиция проходит
+  `-1` → `0` → `WORLD_STARTING_DAYS`, в ODS ровно даты описи, топики созданы
+  заново, офсеты групп идут с нуля, DDS и DM собраны.
+- **Красные пути проверяются своими отказами.** Сторож работника при
+  отсутствующей, нулевой и отрицательной позиции; `world_initialize` на `-1`;
+  оборванная очистка, оставляющая `-1`. Проверка, не видевшая своей поломки,
+  доказывает только то, что умеет печатать «ЗЕЛЁНО».
+- **Отказ в правах читается.** Учётная запись `lifecycle` применяет весь DDL
+  без единой ошибки прав, а административный запрос к системной базе ей
+  отклоняют — и текст отказа называет учётку.
+- **Один холодный `make clean && make up`** оправдан на итоговой приёмке и
+  только этой работой: она меняет самый первый подъём стенда, а его иначе не
+  увидеть. Обобщать этот случай не нужно — обычная проверка по-прежнему
+  обходится узкой областью очистки.
+
+Замеры холодного и повторного `make up` и пересборки записываются в
+[карту проверок](../architecture/testing.md), раздел «Что проверено».
+
+## Отклонённые варианты
+
+- **Спрятать одноразовые службы за профилем или звать их `compose run`.**
+  Дешевле всего в правках, но оставляет двух оркестраторов одного процесса —
+  ровно то, ради чего затевался переезд.
+- **Оставить применение DDL и заливку мира в shell, а Airflow отдать только
+  позицию.** Тогда «один наблюдаемый процесс» остаётся обещанием: половина
+  графа живёт в журнале терминала.
+- **Вынести общие шаги двух дагов в отдельный модуль.** Третье место для той же
+  последовательности; расхождение дагов пряталось бы в его параметрах.
+- **Применять изменённый DDL при каждом `make up`.** Это мигратор схемы; ему
+  нужен отдельный разговор, в граф создания мира он не помещается.
+- **Выдать права на удаление баз учётной записи `etl`.** Отвергнуто ещё
+  ADR 0013: конвейер не получает административные права из-за редкой операции.
+- **Завести блокировку или статус обслуживания, чтобы пересборка не
+  сталкивалась с движением мира.** Механизм на редкий ручной случай дороже
+  предусловия, названного словами.
+- **Сторож на `orders_ingest`.** Даг зовут до того, как мир существует; сторож
+  запретил бы саму инициализацию.

docs/specs/2026-09-01-labs-program.md

@@ -0,0 +1,293 @@
+# Программа учебных лаб
+
+Эта спека собирает программу лаб из
+[инвентаризации сюжетов](../research/2026-08-31-labs-inventory.md), выполненной
+в тикете #201. Тикет спеки — #202, карта — #182.
+
+Статус: спека принята владельцем; судьба идей-кандидатов решена здесь поименно.
+
+## 1. Кому и зачем
+
+Менти уже прошел большой теоретический курс ClickHouse объемом около 60 часов.
+Он знает устройство системы в теории, но почти ничего не делал своими руками.
+
+Поэтому в программе нет вводного блока с теорией. Здесь теория становится
+ремеслом: менти руками осваивает слои хранилища, DQ, оркестрацию и
+идемпотентность.
+
+Обещание программы: менти проходит конвейер стенда автором, а не читателем.
+
+## 2. Устройство программы: основная программа и факультативы
+
+У частей программы два статуса, третьего нет.
+
+**Основная программа** — обязательная часть. Менти проходит ее целиком и по
+порядку, потому что каждая следующая ступень опирается на предыдущую. От
+ступени к ступени растет самостоятельность: сначала менти получает готовые ТЗ с
+готовыми сторожами (DQ-проверками), а затем строит сторожей сам.
+
+**Факультативы** — необязательные лабы. Они собраны в тематические разделы,
+чтобы менти мог одним взглядом выбрать интересное. Для каждого раздела указано,
+после какой ступени основной программы он открывается.
+
+В программе используются четыре формы заданий:
+
+- *построить свое по ТЗ* — рядом есть образец, но готового ответа нет;
+- *вычитание* — SQL готовой трансформации удаляется и пишется заново, а даги
+  остаются как несущая инфраструктура;
+- *собери рядом* — менти строит свою копию результата рядом с нетронутым
+  стендовым и сверяет их построчно;
+- *расследование* — данные уже лежат на стенде или стенд намеренно ломается, а
+  менти ищет причину и объясняет ее.
+
+## 3. Основная программа — семь ступеней
+
+### Ступень 1. Построй пять витрин слоя DM
+
+Первая часть программы опирается на шесть существующих заданий из
+[`docs/labs/`](../labs/README.md). Пять ТЗ по витринам входят в первую ступень
+основной программы и выполняются как есть. Их точечный пересмотр — работа
+реализации. Шестое задание, про свой дашборд в Superset, остается факультативом
+в разделе «Superset и BI». Набор уроков пяти витрин уже записан в их общем
+описании: от слоя как договора до честных имен показателей.
+
+Форма — построить свое по ТЗ. Обратную связь дает даг `homework_check`.
+
+### Ступень 2. Свой отчет в Superset
+
+Менти строит один график в Superset поверх витрины, которую сделал на первой
+ступени. Урок — увидеть, как собственный результат из хранилища становится
+отчетом в BI, не превращая знакомство с инструментом в отдельный большой
+проект.
+
+Форма — построить свое по ТЗ. Результат проверяется глазами. ТЗ для этой новой
+ступени предстоит написать при реализации программы. Полный собственный дашборд
+остается факультативом в разделе «Superset и BI».
+
+### Ступень 3. Нарежь сессии сам
+
+До того как открыть стендовый SQL нарезки сессий в DDS, менти самостоятельно
+делит события на визиты. Сначала он сравнивает число своих сессий с эталоном
+`VisitID`. Затем вручную соединяет свою сессию с эталонной и поштучно разбирает
+хотя бы одно расхождение границ. Урок — счет называет проблему, но причину
+приходится искать в отдельных строках.
+
+Форма — построить свое по ТЗ и провести расследование. Обратная связь состоит
+из счетной сверки с `VisitID` и ручного сопоставления границ.
+
+### Ступень 4. Перепиши нарезку стенда
+
+Менти удаляет и заново пишет SQL нарезки сессий DDS: расчет объема, пересборку
+и замену. Урок — изменить расчетную сущность внутри готового конвейера и
+проверить ее внешним эталоном. Это единственный поток, для которого
+инвентаризация подтвердила вычитание без оговорок: здесь есть настоящие места
+для ошибок, а проверка не содержит готового ответа.
+
+Форма — вычитание. Обратную связь дают `dq_check` и поштучная сверка,
+построенная на третьей ступени.
+
+### Ступень 5. Сначала сторож, потом ломай: заказы
+
+Сначала менти строит две недостающие DQ-проверки. Первая утверждает равенство
+«цена × количество = items_total». Вторая сверяет слой с источником по дням. Их
+менти строит по образцу пяти стендовых проверок в `sql/dq/`. Обе проверки
+должны покраснеть на управляемой ошибке. Затем менти вручную подкладывает по
+строке каждого класса брака, проверяет разбор и убирает эти строки за собой.
+
+Только после этого он вычитает разбор заказов ODS `order_parse` и трансформацию
+заказа DDS. Урок — сторожа строят до рискованного изменения, а не после первой
+поломки.
+
+Форма — построить свои проверки по ТЗ, провести управляемое расследование и
+выполнить вычитание. Обратную связь дают две новые проверки, баланс годных и
+ошибочных строк по срезу и существующие сверки заказов.
+
+### Ступень 6. Разбери сырые события и сверь результат со стендом
+
+Менти пакетно разбирает срез сырья событий в собственную таблицу и построчно
+сверяет результат с нетронутым стендовым ODS. Урок — изучить разбор потока
+отдельно от живого приема и использовать стендовый результат как образец для
+сверки. Матвью разбора остаются несущей стеной: их пересоздание молча теряет
+сообщения.
+
+Форма — «собери рядом». Обратная связь — построчная сверка двух разборов. Ее
+границы называются прямо: срок работы ограничен окном хранения сырья, а
+содержимое неопорных колонок можно сравнить только со стендовым разбором, не с
+независимым эталоном.
+
+### Ступень 7. Мониторинг: куда смотреть
+
+Сначала менти знакомится с панелями стенда. Затем проводит два безопасных
+расследования. В первом он находит в `query_log`, что верх списка тяжелых
+запросов занимает сам мониторинг. Во втором объясняет, почему свежесть второго
+источника выглядит как пила, а не как линия, и выбирает правильный слой данных
+для панели.
+
+Форма — расследование. Обратная связь — найденные запросы и верное объяснение
+формы графика и выбора слоя. Ломательные опыты остаются в факультативе «Что
+делать, когда стенд сломался». Урок ступени — куда и на что смотреть в живой
+системе.
+
+**Общее правило вычитания:** ТЗ каждого вычитания на ступенях 4 и 5 включает
+пересчет ключа шардирования по `hostName()`. Счетные сверки читают `_dist`,
+поэтому учитывают строку даже на чужом шарде и остаются зелеными: они не видят
+саму ошибку раскладки.
+
+## 4. Факультативы — пять разделов
+
+Ниже перечислены только названия сюжетов и их уроки. Материал, формы и способы
+проверки остаются в [инвентаризации](../research/2026-08-31-labs-inventory.md).
+
+### Почему выручка не сходится
+
+Этот раздел рекомендован первым из факультативов. Он открывается после ступени
+1 основной программы: материал живет на стенде с этапа 6.
+
+- **Почему трекер недосчитывает покупки (#186).** Разрыв воронки подтверждений
+  показывает потерянные события и границу доверия к двум источникам.
+- **Почему повтор покупки завышает выручку (#187).** Движок убирает технический
+  дубль строки, а повтор одной покупки приходится находить по деловому ключу.
+- **Какая позиция объясняет разницу в сумме.** Расхождение суммы нужно
+  разложить до конкретной вычеркнутой позиции и объяснить до копейки.
+- **Был ли отмененный заказ оплачен.** Текущее состояние не заменяет историю, а
+  некоторые различия после истечения срока сырья уже не восстановить.
+- **Когда отчет за день можно считать окончательным (#188).** Отчет за день
+  становится окончательным лишь после того, как источник больше не может
+  изменить этот день.
+- **Почему выручка за день еще меняется.** Внутри окна изменяемости выручка
+  движется, а после закрытия дня фиксируется.
+
+### Тонкий анализ данных
+
+Открывается после ступени 1 основной программы.
+
+- **Что мы знали о пользователе в тот день (#145).** Текущее знание и знание на
+  дату дают разные отчеты; сведения из будущего меняют прошлое.
+- **Добавь названия регионов в отчет (#143).** Менти собирает свой словарь по
+  образцу каталога и обогащает отчет через `dictGet`.
+
+### Superset и BI
+
+Открывается после ступени 2 основной программы.
+
+- **Свой дашборд.** Готовая лаба
+  [`docs/labs/superset-dashboard.md`](../labs/superset-dashboard.md) учит
+  хранить пользовательские объекты отдельно от стендовых.
+- **Почему дашборд не видит объект на второй ноде.** Забытый `ON CLUSTER` может
+  остаться незаметным до тех пор, пока дашборд не обратится ко второй ноде.
+
+### Инженерия стенда
+
+Открывается после ступени 1 основной программы. Сюжеты про переигрывание дня и
+пошардовую атомарность раскроются полнее после ступени 4, когда менти уже
+спускался в DDS.
+
+- **Как принимать данные из Kafka: потоком или слепком.** Поток и слепок
+  требуют разных способов приема и дают разную наблюдаемость.
+- **Почему данные попадают на свои шарды независимо от ноды чтения.**
+  Нода-потребитель может меняться, а раскладку строк определяет ключ
+  шардирования.
+- **Почему вторая группа потребителей дублирует поток.** Еще одна группа
+  потребителей создает еще одну полную копию потока.
+- **Как заметить пропущенные сообщения по офсетам.** Разрыв в офсетах
+  показывает потерю, которую трудно заметить по самим данным.
+- **Почему сырье удаляется по времени загрузки.** Очистка сырья живет по
+  времени загрузки, а не по модельному дню.
+- **Куда попадают битые строки.** Годные строки и брак делят поток без
+  пропусков и пересечений; менти подкладывает по строке каждого класса брака
+  событий и находит их в `ods.event_errors_dist`.
+- **Какая версия заказа считается текущей.** Версию заказа задает слепок
+  источника, а `FINAL` скрывается за представлением.
+- **Почему один момент попадает в разные дни.** Один момент дает разные дни в
+  разных поясах, поэтому день и пояс нужно называть явно.
+- **Проверь, как стенд разобрал JSON в `ecommerce`.** Типизированный разбор
+  может молча подменить ошибку значением, поэтому менти сам разбирает сырой
+  JSON и сравнивает результат с массивами стенда.
+- **Как конвейер восстанавливает пропущенный день.** Конвейер сам находит дыру
+  и определяет объем повторной обработки по состоянию хранилища.
+- **Что будет, если день заменился не на всех шардах.** Замена дня завершается
+  отдельно на каждом шарде, поэтому целостность результата подтверждает
+  отдельная сверка.
+- **Как обновлять витрину без полной пересборки (#149) — повышенная
+  сложность.** Экономия на пересчете требует хранить историю изменений, которую
+  полная пересборка стирает.
+
+### Что делать, когда стенд сломался
+
+Открывается после ступени 7 основной программы; весь раздел — повышенная
+сложность.
+
+- **Что ломается вместе с keeper.** Остановка keeper связывает состояние DDL и
+  репликации с тем, что видно на панелях и в системных таблицах.
+- **Где искать запрос DDL, который не завершился.** Очередь распределенного DDL
+  показывает путь запроса и ответ каждой ноды.
+
+Итог раздела — runbook, которого сейчас не хватает стенду. Менти пишет его по
+результатам опытов, и документ остается в проекте.
+
+## 5. Границы вычитания по потокам
+
+Подробное сравнение потоков и таблица доказательств остаются в
+[инвентаризации](../research/2026-08-31-labs-inventory.md). Спека берет это
+сравнение за основу и проводит свои границы. Без оговорок вычитанию отдаются
+только сессии DDS. Заказы можно вычитать лишь после самодельных сторожей. Для
+событий ODS выбрана форма «собери рядом»; вычитание здесь отклонено. Прием STG
+и забор заказов остаются несущей стеной и доступны только для расследований.
+Карту идентичностей спека решает не отдавать вычитанию; причины этого выбора
+названы в следующем разделе.
+
+## 6. Что не вошло
+
+Вычитание стендовых витрин DM не входит в программу. Оно повторяет урок
+готового ядра DM, а открытые сверочные запросы в `sql/dq/` почти дословно
+содержат ответ.
+
+Форма «собери рядом» для карты идентичностей тоже не входит. Независимого
+эталона нет, а слабые инварианты проверяют допустимость связей, но не полноту.
+Аналитический урок идентичности уже несет склейка во времени (#145) в
+факультативе «Тонкий анализ данных».
+
+Сюжеты, которые инвентаризация относит к лекциям, остаются лекциями: `Sign` и
+CollapsingMergeTree, топологии в бою и идентичность «как в бою». Эта спека
+оставляет их в
+[списке опорных точек раздела 12 спеки v2](2026-07-30-stand-v2-realism.md#опорные-точки-для-будущих-лекций-и-лаб).
+
+## 7. Судьба идей-кандидатов
+
+Эти решения закрывают тикеты после приемки спеки:
+
+- #143, справочник регионов — вошла в факультатив «Тонкий анализ данных».
+- #145, склейка во времени — вошла в факультатив «Тонкий анализ данных».
+- #148, домашки ниже DM и вычитание — вошла в основную программу как ступени
+  4–6. Форму для каждого потока уточнила инвентаризация #201: вычитание,
+  «сначала сторож» или «собери рядом».
+- #149, инкрементальный `daily_traffic` — вошла в факультатив «Инженерия
+  стенда» с пометкой «повышенная сложность».
+- #186, воронка подтверждений — вошла в факультатив «Почему выручка не
+  сходится».
+- #187, бизнес-дубль — вошла в факультатив «Почему выручка не сходится».
+- #188, опоздавшие заказы — вошла в факультатив «Почему выручка не сходится».
+
+## 8. Отклоненные варианты оси
+
+- **Чистое «снизу вверх»: STG → ODS → DDS → DM.** Оно начинает программу с
+  самого тяжелого по инфраструктуре участка. Внизу быстро кончается эталон
+  обратной связи, а вычитание вслепую заставляет переписывать слой, которым
+  менти еще не пользовался.
+- **Два прохода: сначала расследования снизу вверх, потом постройка сверху
+  вниз.** Пролог из восьми расследований откладывает первый собственный
+  результат. Вместо этого расследования разнесены по факультативам и
+  открываются по мере прохождения основной программы.
+- **Сюжетами поперек слоев.** Такой порядок ломает принятое решение, по
+  которому готовые задания открывают программу, и превращает путь в сетку
+  зависимостей.
+
+## 9. Границы спеки и что дальше
+
+Спека не переписывает существующие ТЗ в `docs/labs/` и общий README; точечный
+пересмотр относится к реализации.
+
+Реализация программы тоже находится за границей спеки. В нее входят новые ТЗ
+для ступеней 2–7 основной программы и факультативов, а также отражение порядка
+программы в `docs/labs/README.md`. Карту #182 приемка этой спеки закрыла;
+исполнение ведет отдельная карта — тикет #206 (решение тикета #203).

generator/Makefile

@@ -1,4 +1,4 @@
-.PHONY: lint typecheck test docs inventory
+.PHONY: lint typecheck test demo docs inventory
 
 # --- Проверки ---
 
@@ -12,6 +12,11 @@ typecheck:
 test:
 	uv run pytest
 
+# --- Пример из путеводителя ---
+
+demo:
+	uv run python -m clickstream_generator.demo
+
 # --- Сборка из кода ---
 
 docs:

generator/README.md

@@ -13,31 +13,11 @@
 
 ## Как это работает
 
-> Раздел черновой. По сути он верен, но на понятность читателем со стороны не
+Корневое зерно ветвится на подпотоки, из них складываются когорты, аудитория
-> выверен: пишет его тот, кто держит устройство генератора в голове, а это
+дня, визиты, строки событий и заказы. План поднимает состав мира по требованию,
-> худший судья понятности. Выверка — вместе с путеводителем, тикет #48.
+а день-функция проживает один день без накопленного состояния. Код этой
-
+цепочки, ее схема и запуск D0 собраны в
-Цепочка одна и всегда та же: корневое зерно → подпотоки по позиции в дереве
+[путеводителе](../docs/architecture/generator/README.md).
-→ когорта дня (кто впервые пришёл, сколько раз вернётся, чей паспорт какой)
-→ аудитория дня, то есть когорта плюс возвраты когорт окна → визиты этих кук
-→ строки событий. Мир при этом ленив: когорта считается по требованию, а до
-D0 живёт предыстория, поэтому любой день собирается сам по себе — прожитая
-история для него не нужна и на него не влияет.
-
-Главное правило для того, кто придёт следующим: **внутри подпотока порядок
-бросков — часть контракта.** Броски раздаёт один генератор подряд, и k-й
-бросок достаётся тому, кто спросил k-м. Приписать новый бросок в конец
-функции безопасно: у прежних он ничего не отнимает. Вставить в середину —
-значит сдвинуть все броски после него, а с ними и весь мир: события того же
-дня станут другими, счётчики канонического мира разойдутся с описью, и
-поймается это не ошибкой, а красным чеком. Ровно поэтому паспорта кук в
-`plan.cohort` брошены последними, а личность человека приписана уже за ними:
-куки, пары и паспорта остались теми же до байта.
-
-Случайность целочисленная — только диапазоны и выбор по целым весам: готовые
-распределения numpy расходятся между версиями и архитектурами, а обещано
-побайтовое совпадение (спека, раздел 2). Отсюда `weights.py` вместо
-`rng.choice` с вероятностями.
 
 ## Что где лежит
 
@@ -86,7 +66,8 @@ D0 живёт предыстория, поэтому любой день соб
   из контракта. Документ руками не правят — пересобирают.
 - `src/clickstream_generator/inventory.py` — сборка описи мира
   ([`data/world-inventory.json`](../data/world-inventory.json)): паспорт мира
-  и хеши восьми дней, которыми наполняется стенд. Руками не правят —
+  и хеши восьми дней, которыми наполняется стенд, плюс счётчики классов
+  расхождений по заказам для дней с закрытым окном. Руками не правят —
   пересобирают целью `make inventory`.
 - `tests/` — инварианты контракта, свежесть описания и обещания мира:
   чистота от зерна, приток, гарантия двухкуковых пар, форма суточной волны
@@ -103,6 +84,7 @@ D0 живёт предыстория, поэтому любой день соб
 - `make test` — тесты генератора;
 - `make lint` — ruff: проверка и формат;
 - `make typecheck` — ty: проверка типов;
+- `make demo` — пройти стадии канонического D0 на одном экране;
 - `make docs` — пересобрать описание выгрузки;
 - `make inventory` — пересобрать опись мира.
 

generator/src/clickstream_generator/commerce.py

@@ -53,6 +53,7 @@
 """
 
 from dataclasses import dataclass
+from enum import IntEnum
 from typing import Any
 
 import numpy as np
@@ -160,6 +161,14 @@ class Purchases:
         return self.person_id.size
 
 
+class EventOutcome(IntEnum):
+    """Что случилось с маячком purchase после создания заказа."""
+
+    DELIVERED = 0
+    LOST = 1
+    DUPLICATED = 2
+
+
 @dataclass(frozen=True, slots=True)
 class _Events:
     """Строки одного вида торговых событий, готовые встать в поток.
@@ -177,9 +186,18 @@ class _Events:
     basket: NDArray[np.int64]
 
 
-# Что торговая половина отдаёт дню: поток целиком — колонки, страницы и
+@dataclass(frozen=True, slots=True)
-# товары — и покупки дня вторым выходом.
+class Woven:
-Woven = tuple[dict[str, NDArray[Any]], NDArray[np.uint8], NDArray[np.int64], Purchases]
+    """Что торговая половина отдает дню после вплетения событий."""
+
+    columns: dict[str, NDArray[Any]]
+    page: NDArray[np.uint8]
+    product: NDArray[np.int64]
+    purchases: Purchases
+    event_outcome: NDArray[np.int8]
+    # Для каждой покупки: назначен ли её заказ планом.
+    assigned_order: NDArray[np.bool_]
+
 
 # День без единой корзины: покупок в нём нет, а форма у рядов есть.
 _NO_PURCHASES = Purchases(
@@ -191,6 +209,8 @@ _NO_PURCHASES = Purchases(
     revenue=np.empty(0, dtype=np.int64),
     moment=np.empty(0, dtype="datetime64[s]"),
 )
+_NO_EVENT_OUTCOMES = np.empty(0, dtype=np.int8)
+_NO_ASSIGNED_ORDERS = np.empty(0, dtype=np.bool_)
 
 
 def weave(
@@ -200,6 +220,7 @@ def weave(
     page: NDArray[np.uint8],
     product: NDArray[np.int64],
     person: NDArray[np.uint64],
+    assigned_order: NDArray[np.bool_],
 ) -> Woven:
     """Вплетает торговые события в поток и отдаёт поток и покупки дня.
 
@@ -207,14 +228,21 @@ def weave(
     события встают между ними, и поток пересобирается одним порядком. Второй
     выход — покупки дня: то же самое, чем они уехали в события.
 
-    `person` — человек за кукой каждой строки, выровненный по входящему
+    `person` и `assigned_order` выровнены по входящему потоку. Оба
-    потоку: личность приходит от плана состава, а не выводится из трекера
+    признака приходят из плана состава: личность дает заказу `user_id`,
-    (docs/architecture/orders/identity.md).
+    а назначение защищает мост склейки от потери purchase.
     """
     rng = day_stream(seed, day, Component.COMMERCE)
     baskets = _baskets(rng, page, product, columns["VisitID"])
     if not len(baskets):
-        return columns, page, product, _NO_PURCHASES
+        return Woven(
+            columns=columns,
+            page=page,
+            product=product,
+            purchases=_NO_PURCHASES,
+            event_outcome=_NO_EVENT_OUTCOMES,
+            assigned_order=_NO_ASSIGNED_ORDERS,
+        )
 
     goods = catalog.catalog()
     draws = _draws(rng, baskets)
@@ -225,8 +253,20 @@ def weave(
         _order_events(columns, baskets, goods, draws, revenue, coupons),
     )
     columns, page, product, basket = _stream(rng, columns, page, product, events)
-    purchases = _purchases(columns, basket, baskets, draws, revenue, coupons, person)
+    purchases, assigned = _purchases(
-    return columns, page, product, purchases
+        columns, basket, baskets, draws, revenue, coupons, person, assigned_order
+    )
+    columns, page, product, event_outcome = _corrupt_events(
+        seed, day, columns, page, product, purchases, assigned
+    )
+    return Woven(
+        columns=columns,
+        page=page,
+        product=product,
+        purchases=purchases,
+        event_outcome=event_outcome,
+        assigned_order=assigned,
+    )
 
 
 def _draws(rng: np.random.Generator, baskets: _Baskets) -> _Draws:
@@ -653,7 +693,8 @@ def _purchases(
     revenue: NDArray[np.int64],
     coupons: NDArray[np.object_],
     person: NDArray[np.uint64],
-) -> Purchases:
+    assigned_order: NDArray[np.bool_],
+) -> tuple[Purchases, NDArray[np.bool_]]:
     """Покупки дня — то же, чем они уехали в события, только структурой.
 
     Порядок здесь — порядок строк потока, он же порядок номеров заказа:
@@ -664,7 +705,7 @@ def _purchases(
     here = np.flatnonzero(rows["EventType"] == PURCHASE)
     mine = basket[here]
     bought = [baskets.positions_of(number, draws.kept) for number in mine.tolist()]
-    return Purchases(
+    purchases = Purchases(
         order_id=tuple(rows["purchaseID"][row][0] for row in here.tolist()),
         person_id=person[baskets.confirmation[mine]],
         product=tuple(baskets.product[group] for group in bought),
@@ -673,6 +714,118 @@ def _purchases(
         revenue=revenue[mine],
         moment=rows["UTCEventTime"][here],
     )
+    return purchases, assigned_order[baskets.confirmation[mine]]
+
+
+def _corrupt_events(
+    seed: int,
+    day: int,
+    rows: dict[str, NDArray[Any]],
+    page: NDArray[np.uint8],
+    product: NDArray[np.int64],
+    purchases: Purchases,
+    assigned: NDArray[np.bool_],
+) -> tuple[
+    dict[str, NDArray[Any]], NDArray[np.uint8], NDArray[np.int64], NDArray[np.int8]
+]:
+    """Теряет purchase или повторяет пару подтверждения.
+
+    Заказы уже собраны, а номера покупок уже вписаны в строки. Поэтому
+    порча меняет только событийную сторону. Все броски делаются на полную
+    длину покупок дня, чтобы отбор одного класса не сдвигал другой.
+    """
+    count = len(purchases)
+    if not count:
+        return rows, page, product, _NO_EVENT_OUTCOMES
+
+    rng = day_stream(seed, day, Component.BEACONS)
+    lost = (rng.integers(0, 100, count) < world.LOST_PURCHASE_PERCENT) & ~assigned
+    duplicate_draw = rng.integers(0, 100, count) < world.DUPLICATE_PURCHASE_PERCENT
+    delay = rng.integers(*world.DUPLICATE_DELAY_SECONDS, count)
+    watch = ids.unique_apart_from(rng, 2 * count, rows["WatchID"]).reshape(count, 2)
+
+    purchase_rows = np.flatnonzero(rows["EventType"] == PURCHASE)
+    confirmation_rows = _confirmation_rows(rows, page, purchase_rows)
+    eligible = _duplicate_eligibility(rows, purchase_rows, delay)
+    duplicated = ~lost & duplicate_draw & eligible
+
+    outcome = np.full(count, EventOutcome.DELIVERED, dtype=np.int8)
+    outcome[lost] = EventOutcome.LOST
+    outcome[duplicated] = EventOutcome.DUPLICATED
+
+    keep = np.ones(page.size, dtype=bool)
+    keep[purchase_rows[lost]] = False
+    sources = np.column_stack(
+        (confirmation_rows[duplicated], purchase_rows[duplicated])
+    )
+    selected = np.flatnonzero(duplicated)
+    if selected.size:
+        copies = sources.ravel()
+        shifted = np.repeat(delay[selected], 2).astype("timedelta64[s]")
+        additions = {name: values[copies] for name, values in rows.items()}
+        additions["UTCEventTime"] = additions["UTCEventTime"] + shifted
+        additions["WatchID"] = watch[selected].ravel()
+        # Первая строка пары — обновление confirmation: ее предыдущая
+        # страница — она же, а не checkout из первого просмотра.
+        additions["Referer"] = additions["URL"].copy()
+        rows = {
+            name: np.concatenate((values[keep], additions[name]))
+            for name, values in rows.items()
+        }
+        page = np.concatenate((page[keep], page[copies]))
+        product = np.concatenate((product[keep], product[copies]))
+    else:
+        rows = {name: values[keep] for name, values in rows.items()}
+        page = page[keep]
+        product = product[keep]
+
+    order = np.lexsort((rows["WatchID"], rows["UTCEventTime"]))
+    return (
+        {name: values[order] for name, values in rows.items()},
+        page[order],
+        product[order],
+        outcome,
+    )
+
+
+def _confirmation_rows(
+    rows: dict[str, NDArray[Any]],
+    page: NDArray[np.uint8],
+    purchase_rows: NDArray[np.int64],
+) -> NDArray[np.int64]:
+    """Находит просмотр, с которым purchase образует пару."""
+    confirmation = (rows["EventType"] == "pageview") & (page == Page.CONFIRMATION)
+    by_visit = {
+        int(rows["VisitID"][row]): row for row in np.flatnonzero(confirmation).tolist()
+    }
+    return np.array(
+        [by_visit[int(rows["VisitID"][row])] for row in purchase_rows.tolist()],
+        dtype=np.int64,
+    )
+
+
+def _duplicate_eligibility(
+    rows: dict[str, NDArray[Any]],
+    purchase_rows: NDArray[np.int64],
+    delay: NDArray[np.int64],
+) -> NDArray[np.bool_]:
+    """Проверяет полночь и запас до следующего визита куки."""
+    moment = rows["UTCEventTime"][purchase_rows]
+    shifted = moment + delay.astype("timedelta64[s]")
+    before_midnight = shifted < _midnight(rows) + np.timedelta64(1, "D")
+    eligible = before_midnight.copy()
+    for number, row in enumerate(purchase_rows.tolist()):
+        later_visit = (
+            (rows["ClientID"] == rows["ClientID"][row])
+            & (rows["VisitID"] != rows["VisitID"][row])
+            & (rows["UTCEventTime"] > moment[number])
+        )
+        if np.any(later_visit):
+            next_start = rows["UTCEventTime"][later_visit].min()
+            eligible[number] &= next_start - moment[number] > np.timedelta64(
+                world.VISIT_TIMEOUT_SECONDS + int(delay[number]), "s"
+            )
+    return eligible
 
 
 def _midnight(columns: dict[str, NDArray[Any]]) -> np.datetime64:

generator/src/clickstream_generator/day.py

@@ -100,6 +100,8 @@ class Day:
     page: NDArray[np.uint8]
     product: NDArray[np.int64]
     orders: orders.Orders
+    # Событийный исход каждого заказа, в том же порядке.
+    purchase_outcome: NDArray[np.int8]
 
     def __len__(self) -> int:
         return self.page.size
@@ -162,20 +164,23 @@ def stream(seed: int, day: int) -> Day:
     # целиком: в нём же они и упорядочиваются. Вторым выходом приходят
     # покупки дня — из них заказная сторона собирает заказы.
     person = np.repeat(audience.person_id[visits.cookie], visits.pages)
-    columns, page, product, purchases = commerce.weave(
+    assigned_order = np.repeat(visits.ordering, visits.pages)
+    woven = commerce.weave(
         seed,
         day,
         {name: value[order] for name, value in columns.items()},
         page[alive][order],
         product[alive][order],
         person[alive][order],
+        assigned_order[alive][order],
     )
     return Day(
         day=day,
-        columns=columns,
+        columns=woven.columns,
-        page=page,
+        page=woven.page,
-        product=product,
+        product=woven.product,
-        orders=orders.of_day(seed, day, purchases),
+        orders=orders.of_day(seed, day, woven.purchases, woven.assigned_order),
+        purchase_outcome=woven.event_outcome,
     )
 
 

generator/src/clickstream_generator/demo.py

@@ -0,0 +1,62 @@
+"""Короткий проход по цепочке генератора на каноническом дне D0."""
+
+from collections import Counter
+
+import numpy as np
+
+from clickstream_generator import day, plan, seeds, world
+
+DAY = 0
+
+
+def _number(value: int) -> str:
+    """Разделяет разряды числа для чтения с экрана."""
+    return f"{value:,}".replace(",", " ")
+
+
+def render() -> str:
+    """Собирает D0 и показывает его стадии без числового эталона."""
+    seed = seeds.CANONICAL_SEED
+    cohort = plan.cohort(seed, DAY)
+    audience = plan.audience(seed, DAY)
+    events = day.stream(seed, DAY)
+
+    _, rows_per_visit = np.unique(events.columns["VisitID"], return_counts=True)
+    event_types = Counter(str(value) for value in events.columns["EventType"])
+    smallest_visit = int(rows_per_visit.min())
+    largest_visit = int(rows_per_visit.max())
+
+    return "\n".join(
+        (
+            f"Зерно: {seed}",
+            "Подпотоки D0: состав мира → когорта; день → трафик, торговля, заказы",
+            (
+                f"Когорта D0: людей — {_number(cohort.people)}; "
+                f"кук — {_number(len(cohort.client_id))}"
+            ),
+            (
+                f"Аудитория D0: кук — {_number(len(audience.client_id))}; "
+                f"когорты D-{world.RETURN_TAIL_DAYS}...D0"
+            ),
+            (
+                f"Визиты по VisitID: групп — {_number(len(rows_per_visit))}; "
+                f"строк в группе — {smallest_visit}–{largest_visit}"
+            ),
+            (
+                f"Строки событий: {_number(len(events))} "
+                f"(pageview — {_number(event_types['pageview'])}; "
+                f"add_to_cart — {_number(event_types['add_to_cart'])}; "
+                f"purchase — {_number(event_types['purchase'])}); "
+                f"заказов — {_number(len(events.orders))}"
+            ),
+        )
+    )
+
+
+def main() -> None:
+    """Печатает проход по D0."""
+    print(render())
+
+
+if __name__ == "__main__":
+    main()

generator/src/clickstream_generator/inventory.py

@@ -1,15 +1,16 @@
 """Опись мира: чем стенд наполняется при подъёме и каким это обязано выйти.
 
 Мир — чистая функция зерна (спека генератора, раздел 2), поэтому в git лежит не
-он сам, а опись: паспорт мира, число событий по дням и хеш байтов каждого дня.
+он сам, а опись: паспорт мира, число событий и хеш байтов каждого дня, счётчики
-Сам мир пересчитывается когда угодно, а опись отвечает на единственный вопрос —
+классов расхождений по заказам. Сам мир пересчитывается когда угодно, а опись
-**тот ли это мир, что был вчера**. Разошлись хеши — мир уехал, и дальше уже
+отвечает на единственный вопрос — **тот ли это мир, что был вчера**. Разошлись
-неважно, чего от него ждали проверки.
+хеши — мир уехал, и дальше уже неважно, чего от него ждали проверки.
 
 Дней в описи восемь: столько заливается в стенд при `make up`. Понедельник по
 понедельник — полная неделя с выходными и первый замкнутый цикл окна K = 7.
-Эталонный снимок в четырнадцать дней придёт на этапе 7 и станет продолжением
+Это и есть эталонный мир: обещание в четырнадцать дней снято на этапе 7 —
-этой же описи, а не вторым файлом.
+у хвоста не нашлось читателя. Понадобится длиннее — опись продолжит этот
+же файл, а не заведет второй.
 
 **Сторожат мир хеши, а не паспорт.** Паспорт отвечает на другой вопрос — «чем
 это сделано»: зерно и версия генератора. Поменяй кто-нибудь код так, что мир
@@ -43,15 +44,15 @@ from importlib.metadata import version
 from pathlib import Path
 from typing import Any
 
+from clickstream_generator import commerce, serialize, world
 from clickstream_generator import day as day_module
 from clickstream_generator import orders as orders_module
-from clickstream_generator import serialize, world
 from clickstream_generator.catalog import CATALOG_PATH
 from clickstream_generator.seeds import CANONICAL_SEED
 
-# Сколько дней оси заливается в стенд при подъёме. То же число стоит у службы
+# Сколько дней оси описывает стартовый мир. То же число Airflow получает из
-# `world-init` в compose.yaml: YAML не читает Python, и одно из двух мест —
+# compose.yaml: YAML не читает Python, и одно из двух мест лишнее по построению.
-# лишнее по построению. Расхождение поймают счётчики make check-clickhouse.
+# Расхождение поймают счётчики make check-clickhouse.
 STARTING_DAYS = 8
 
 
@@ -66,7 +67,10 @@ def build() -> dict[str, Any]:
     orders = []
     for number in range(STARTING_DAYS):
         today = day_module.stream(CANONICAL_SEED, number)
-        days.append(_day(number, today))
+        row = _day(number, today)
+        if number < STARTING_DAYS - world.ORDER_WINDOW_DAYS:
+            row["orders"] = _order_class_counts(today)
+        days.append(row)
         orders.append(today.orders)
 
     return {
@@ -115,6 +119,46 @@ def _snapshot(number: int, orders: list[orders_module.Orders]) -> dict[str, Any]
     }
 
 
+def _order_class_counts(today: day_module.Day) -> dict[str, int]:
+    """Заказы дня по итоговому классу по приоритету спеки."""
+    purchase = today.columns["EventType"] == commerce.PURCHASE
+    declared = {
+        purchase_id[0]: round(revenue[0] * commerce.KOPECKS)
+        for purchase_id, revenue in zip(
+            today.columns["purchaseID"][purchase],
+            today.columns["purchaseRevenue"][purchase],
+            strict=True,
+        )
+    }
+    counts = {
+        "match": 0,
+        "cancelled": 0,
+        "lost_event": 0,
+        "duplicate_event": 0,
+        "amount_delta": 0,
+    }
+
+    for order_id, order_outcome, event_outcome, items_total in zip(
+        today.orders.order_id,
+        today.orders.outcome,
+        today.purchase_outcome,
+        today.orders.items_total,
+        strict=True,
+    ):
+        if order_outcome != orders_module.OrderOutcome.PAID:
+            counts["cancelled"] += 1
+        elif event_outcome == commerce.EventOutcome.LOST:
+            counts["lost_event"] += 1
+        elif event_outcome == commerce.EventOutcome.DUPLICATED:
+            counts["duplicate_event"] += 1
+        elif items_total != declared[order_id]:
+            counts["amount_delta"] += 1
+        else:
+            counts["match"] += 1
+
+    return counts
+
+
 def _date(number: int) -> str:
     return (world.ORIGIN + timedelta(days=number)).isoformat()
 

generator/src/clickstream_generator/orders.py

@@ -24,11 +24,13 @@
 одной доли перебрасывала бы весь подпоток после себя
 (docs/architecture/orders/fate.md).
 
-**Судьба заказа — исход и его моменты**: из окна изменяемости заказ выходит
+**Судьба заказа — исход, его моменты и задержка выгрузки**. Из окна
-оплаченным или отменённым, а когда именно это случилось, сказано смещением в
+изменяемости заказ выходит оплаченным или отменённым, а когда именно это
-секундах от рождения заказа. Момента, которого у исхода нет, нет и в данных:
+случилось, сказано смещением в секундах от рождения заказа. Момента, которого
-его место занимает −1, а не ноль, — иначе «оплатили в секунду рождения» было
+у исхода нет, нет и в данных: его место занимает −1, а не ноль, — иначе
-бы не отличить от «не оплатили вовсе».
+«оплатили в секунду рождения» было бы не отличить от «не оплатили вовсе».
+Задержка говорит, сколько ранних слепков заказ пропустит; назначенный планом
+приезжает сразу.
 
 **Состояние на границе суток** — чтение готовой судьбы, а не накопление:
 слепок дня D учитывает моменты не позже границы D|D+1 и по ним называет
@@ -62,6 +64,7 @@ _DELIVERY_CUMULATIVE = np.cumsum(
 )
 _OUTCOME_CUMULATIVE = np.cumsum(world.ORDER_OUTCOME_WEIGHTS)
 _MOMENT_HOUR_CUMULATIVE = np.cumsum(world.ORDER_MOMENT_HOUR_WEIGHTS)
+_SNAPSHOT_DELAY_CUMULATIVE = np.cumsum(world.ORDER_SNAPSHOT_DELAY_WEIGHTS)
 
 
 class OrderOutcome(IntEnum):
@@ -103,12 +106,18 @@ class Orders:
     outcome: NDArray[np.int64]
     paid_after: NDArray[np.int64]
     cancelled_after: NDArray[np.int64]
+    snapshot_delay: NDArray[np.int64]
 
     def __len__(self) -> int:
         return self.user_id.size
 
 
-def of_day(seed: int, day: int, purchases: Purchases) -> Orders:
+def of_day(
+    seed: int,
+    day: int,
+    purchases: Purchases,
+    assigned_order: NDArray[np.bool_],
+) -> Orders:
     """Заказы дня `day`: его покупки, к которым бэкенд добавил свои деньги."""
     rng = day_stream(seed, day, Component.ORDERS)
     delivery = _delivery(rng, len(purchases))
@@ -116,6 +125,7 @@ def of_day(seed: int, day: int, purchases: Purchases) -> Orders:
     product, quantity, items_total = _delta(rng, purchases)
     created_at = _created_at(rng, purchases)
     discount = _discount(purchases, items_total)
+    snapshot_delay = _snapshot_delay(rng, assigned_order)
     return Orders(
         day=day,
         order_id=purchases.order_id,
@@ -130,6 +140,7 @@ def of_day(seed: int, day: int, purchases: Purchases) -> Orders:
         outcome=outcome,
         paid_after=paid_after,
         cancelled_after=cancelled_after,
+        snapshot_delay=snapshot_delay,
     )
 
 
@@ -166,6 +177,11 @@ def at_boundary(rows: Orders, day: int) -> tuple[list[str], NDArray[np.datetime6
     return status.tolist(), updated
 
 
+def arrived(rows: Orders, day: int) -> NDArray[np.bool_]:
+    """Какие заказы уже попали в выгрузку к слепку дня `day`."""
+    return rows.day + rows.snapshot_delay <= day
+
+
 def _boundary(day: int) -> np.datetime64:
     """Граница суток `day`|`day+1` абсолютной меткой: полночь пояса счётчика.
 
@@ -218,6 +234,15 @@ def _created_at(
     )
 
 
+def _snapshot_delay(
+    rng: np.random.Generator,
+    assigned_order: NDArray[np.bool_],
+) -> NDArray[np.int64]:
+    """Сколько ранних слепков пропустит заказ; назначенный приезжает сразу."""
+    delay = pick(rng, _SNAPSHOT_DELAY_CUMULATIVE, assigned_order.size)
+    return np.where(assigned_order, 0, delay)
+
+
 def _moment(rng: np.random.Generator, orders: int) -> NDArray[np.int64]:
     """Момент внутри окна: час по таблице весов и равномерная секунда в нём.
 

generator/src/clickstream_generator/schema.py

@@ -12,12 +12,12 @@
 
 - `name` — имя источника, как в облачной выгрузке Метрики; сырой слой хранит
   его без изменений.
-- `clickhouse_type` — тип в хранилище ровно в той записи, в какой его вернёт
+- `clickhouse_type` — тип колонки у источника в той записи, которой пользуется
-  `system.columns`: параметры входят в имя типа целиком, без сокращений
+  ClickHouse: параметры входят в имя целиком, без сокращений
-  (`LowCardinality(String)`, `Array(Float64)`). Сверено 2026-08-01 —
+  (`LowCardinality(String)`, `Array(Float64)`). Обычно ODS берет его без
-  по документации ClickHouse через Context7 и запросом к узлу стенда
+  изменений. Исключение одно: денежный `purchaseRevenue` приезжает как
-  (26.3.17.56). Запись важна потому, что по ней человек пишет DDL: тип,
+  Float64, а на границе хранения разбирается прямо в Decimal. Поэтому поле
-  сокращённый здесь, приедет в таблицу сокращённым же.
+  описывает выгрузку, а локальный тип ODS назван в документации хранилища.
 - `numpy_dtype` — чем колонка представлена внутри генератора; у массивов это
   тип элемента. Строки живут в `object`-массивах: numpy-строки фиксированной
   длины стенду ничего не дают.
@@ -371,8 +371,8 @@ COLUMNS: tuple[Column, ...] = (
         numpy_dtype="float64",
         normalized_name="purchase_revenue",
         group=ColumnGroup.ECOMMERCE,
-        comment="выручка заказа глазами клиента; Float64, как у Метрики —"
+        comment="выручка заказа глазами клиента; источник объявляет Float64,"
-        " на этом держится урок о расхождениях с бэкендом",
+        " ODS хранит точный Decimal",
     ),
     Column(
         name="purchaseCurrency",

generator/src/clickstream_generator/schema_doc.py

@@ -27,10 +27,12 @@ PREAMBLE = """# Описание выгрузки: событие кликстр
 по элементу на товар. Отдельной сущности «визит» в выгрузке нет — визиты
 собирают на стороне хранилища, а `VisitID` дан как эталон для самопроверки.
 
-Имена и типы колонок — стороны источника. Хранилище принимает их как есть и
+Имена и типы колонок описывают сторону источника. Обычно ODS принимает их без
-нормализует у себя: то же имя в нашем стиле ждёт в столбце «Нормализованное
+изменений. Исключение — `purchaseRevenue`: источник объявляет Float64, а ODS
-имя». Это имя источника, приведённое к snake_case, а не имя атрибута в
+хранит деньги в Decimal. Точный локальный тип назван в документации
-модели данных: слой DDS складывает свою модель и называет атрибуты по ней.
+хранилища. Имя в нашем стиле ждет в столбце «Нормализованное имя». Это имя
+источника, приведенное к snake_case, а не имя атрибута в модели данных: слой
+DDS складывает свою модель и называет атрибуты по ней.
 Столбец «Тип numpy» показывает, чем колонка представлена внутри генератора;
 у массивов это тип элемента. Номер — место колонки в выгрузке: порядок задан
 контрактом.

generator/src/clickstream_generator/seeds.py

@@ -7,7 +7,7 @@
     │   ├── ось          → номер дня: когорта этого дня
     │   └── предыстория  → глубина: когорта дня до D0
     └── дни
-        └── номер дня    → трафик, торговля, заказная сторона, опоздания
+        └── номер дня    → трафик, торговля, заказы, маячки счетчика
 
 Механизм — `numpy.random.SeedSequence`: потомок полностью определяется парой
 (зерно, позиция в дереве), а не порядком вычислений. Сверено через Context7
@@ -40,10 +40,8 @@ class Component(IntEnum):
     # каждого заказа читает из его собственного дня
     # (docs/architecture/orders/fate.md).
     ORDERS = 2
-    # Событийную сторону — потерю и дубль события — заведёт этап 6; до тех
+    # Маячки счетчика: потеря и повторная отправка событий.
-    # пор позиция занята мёртвым именем прежней нарезки, и из него никто не
+    BEACONS = 3
-    # бросает.
-    LATECOMERS = 3
 
 
 class _Branch(IntEnum):

generator/src/clickstream_generator/serialize.py

@@ -45,7 +45,7 @@ from numpy.typing import NDArray
 
 from clickstream_generator import catalog, schema, world
 from clickstream_generator.day import Day
-from clickstream_generator.orders import Orders, at_boundary
+from clickstream_generator.orders import Orders, arrived, at_boundary
 
 _ARRAY_PREFIX = "Array("
 
@@ -72,9 +72,10 @@ def events(day: Day, limit: int | None = None) -> list[bytes]:
 def orders(window: Sequence[Orders], day: int) -> list[bytes]:
     """Канонические байты слепка дня `day`: по документу JSON на заказ.
 
-    `window` — заказы дней окна, от раннего дня к позднему: слепок несёт их
+    `window` — заказы дней окна, от раннего дня к позднему. Уже приехавшие
-    подряд, и порядок строк выходит порядком рождения заказов, он же
+    заказы слепок несёт подряд, поэтому порядок строк остаётся порядком
-    возрастание `order_id`. Какие это дни, решает `orders.window`.
+    рождения, он же возрастание `order_id`. Какие это дни, решает
+    `orders.window`.
 
     Деньги уезжают строками с ровно двумя знаками, а не числами: у заказа они
     станут `Decimal`, и дробь двоичного числа была бы потерей точности до
@@ -97,7 +98,8 @@ def orders(window: Sequence[Orders], day: int) -> list[bytes]:
         delivery = rows.delivery.tolist()
         total = rows.total.tolist()
 
-        for number, order_id in enumerate(rows.order_id):
+        for number in np.flatnonzero(arrived(rows, day)).tolist():
+            order_id = rows.order_id[number]
             payloads.append(
                 orjson.dumps(
                     {

generator/src/clickstream_generator/world.py

@@ -169,6 +169,16 @@ BUYER_CHECKOUT_OF_CART_PERCENT = 60
 # страницу, на которой посетитель его нажал.
 TRADE_DELAY_SECONDS = (2, 8)
 
+# Событийная сторона сверки: потерянные маячки purchase и повторная
+# отправка пары «просмотр подтверждения + purchase». Замер (28 дней,
+# канонический мир, 2026-08-30): дубль 1,89% — в пределах ориентира ~2%;
+# потеря 1,78% при броске 3% — так и задумано: назначенные планом покупки
+# из броска исключены (мост склейки), часть съедает приоритет отмены;
+# наблюдаемая доля принята решением владельца (#194).
+LOST_PURCHASE_PERCENT = 3
+DUPLICATE_PURCHASE_PERCENT = 2
+DUPLICATE_DELAY_SECONDS = (30, 301)
+
 # Кто и что кладёт в корзину: доля открытых карточек, которая до неё дошла.
 # Оба ряда читаются по уровням спроса товара (`catalog.DEMAND_LEVELS`):
 # магнит, обычный, залёживается.
@@ -238,8 +248,8 @@ GOAL_PURCHASE_ID = 42150002
 # обычная курьерская, срочная. Это единственные деньги заказа, которых нет
 # ни в одном событии: выручка клиента — сумма позиций, скидку по промокоду
 # считает бэкенд по таблице `COUPONS`, а доставку решает свой бросок
-# заказной стороны. Числа черновые: калибровка — пересборка эталонного
+# заказной стороны. Замер (28 дней, канонический мир, 2026-08-30): 35,5% /
-# мира, этап 7.
+# 49,2% / 15,4% — совпадает с весами.
 DELIVERY_KOPECKS_WEIGHTS = (
     (0, 35),
     (29_900, 50),
@@ -248,12 +258,13 @@ DELIVERY_KOPECKS_WEIGHTS = (
 
 # Чем кончается окно изменяемости заказа: веса трёх исходов, в порядке
 # `orders.OrderOutcome`. «Создан» навсегда мир не допускает — из окна заказ
-# выходит либо оплаченным, либо отменённым. Доли черновые: калибровка —
+# выходит либо оплаченным, либо отменённым. Замер (28 дней, 2026-08-30):
-# пересборка эталонного мира, этап 7.
+# отменено 5,15% заказов — 3,03% оплачен-потом-отменен, 2,12% отменен
+# неоплаченным; ориентир мастер-спеки ~5%.
 ORDER_OUTCOME_WEIGHTS = (
     95,  # оплачен
     3,  # оплачен, потом отменён
-    2,  # отменён неоплаченным
+    2,  # отменен неоплаченным
 )
 
 # Когда внутри окна случается момент заказа — оплата или отмена: веса часов
@@ -261,8 +272,8 @@ ORDER_OUTCOME_WEIGHTS = (
 # с каким весом»; часов в сумме ровно 144 — самый узкий край окна, у заказа,
 # рождённого в конце суток (docs/architecture/orders/fate.md). Почти всё в
 # первые сутки, дальше затухание до края:
-# профиль гаснет, поэтому обрыв окна в данных не виден. Веса черновые, как и
+# профиль гаснет, поэтому обрыв окна в данных не виден. Веса зафиксированы
-# доли исходов.
+# вместе с долями исходов — тем же замером выше.
 ORDER_MOMENT_HOUR_WEIGHTS = tuple(
     weight
     for hours, weight in ((6, 100), (18, 60), (24, 25), (48, 8), (48, 2))
@@ -273,6 +284,12 @@ ORDER_MOMENT_HOUR_WEIGHTS = tuple(
 # наличии, и заказ приезжает на строку короче клиентской корзины. Бросается
 # доля на все заказы дня, а достаётся дельта не всем — однопозиционному заказу
 # терять нечего, и таких больше половины, — поэтому в сверке наблюдаемая доля
-# выходит вдвое-втрое ниже броска, около ориентира мастер-спеки в 1–2%. Число
+# выходит вдвое-втрое ниже броска, около ориентира мастер-спеки в 1–2%. Замер
-# черновое: калибровка — пересборка эталонного мира, этап 7.
+# (28 дней, 2026-08-30): наблюдаемая доля 1,32% — в пределах ориентира.
 ORDER_DELTA_PERCENT = 4
+
+# На сколько первых дневных слепков заказ опоздает: веса δ = 0, 1, 2.
+# Назначенные планом заказы после броска получают 0, чтобы мост склейки
+# появился в стартовом мире. Замер (28 дней, 2026-08-30): доля опоздавших
+# (δ>0) 8,39% — в пределах ориентира мастер-спеки ~10%.
+ORDER_SNAPSHOT_DELAY_WEIGHTS = (90, 5, 5)

generator/tests/test_commerce.py

@@ -21,7 +21,7 @@ from clickstream_generator.seeds import CANONICAL_SEED, Component
 
 WEEKDAY = 2
 WEEK = 7
-# Окно эталонного снимка: доли по уровням спроса меряются на нём целиком —
+# Окно замера — две недели: доли по уровням спроса меряются на нем целиком —
 # на одном дне у самого редкого уровня набирается слишком мало карточек.
 FORTNIGHT = 14
 
@@ -133,15 +133,15 @@ def opened_cards(events: day.Day) -> set[tuple[int, int]]:
     )
 
 
-def test_a_confirmation_in_the_stream_always_has_its_purchase(weekday: day.Day):
+def test_only_a_lost_purchase_leaves_a_confirmation_without_purchase(
-    """Клиентская сторона честная: подтверждение без покупки — это потеря.
+    weekday: day.Day,
-
+):
-    Потери и дубли стенд заводит намеренно и позже (этапы 4 и 6); здесь их
+    """Потеря выбрасывает purchase, но оставляет просмотр confirmation."""
-    быть не должно ни одной. Обратное тоже верно: покупка без подтверждения
-    в потоке — заказ ниоткуда.
-    """
     bought = set(rows_of(weekday, commerce.PURCHASE)["VisitID"].tolist())
-    assert confirmed_visits(weekday) == bought
+    missing = confirmed_visits(weekday) - bought
+    lost = int((weekday.purchase_outcome == commerce.EventOutcome.LOST).sum())
+    assert len(missing) == lost > 0
+    assert bought <= confirmed_visits(weekday)
 
 
 def test_the_day_boundary_takes_the_confirmation_together_with_its_purchase(
@@ -159,7 +159,10 @@ def test_the_day_boundary_takes_the_confirmation_together_with_its_purchase(
     events = day.stream(CANONICAL_SEED, WEEKDAY)
     bought = set(rows_of(events, commerce.PURCHASE)["VisitID"].tolist())
     assert bought
-    assert confirmed_visits(events) == bought
+    missing = confirmed_visits(events) - bought
+    lost = int((events.purchase_outcome == commerce.EventOutcome.LOST).sum())
+    assert len(missing) == lost
+    assert bought <= confirmed_visits(events)
 
 
 def test_a_purchase_carries_exactly_one_order_number(weekday: day.Day):
@@ -525,13 +528,15 @@ def test_the_goals_repeat_the_trade_events(weekday: day.Day):
 
 def test_the_order_number_reads_as_the_day_and_the_count(weekday: day.Day):
     """Номер — день и порядковый номер покупки в нём; он же `order_id` бэкенда."""
-    orders = rows_of(weekday, commerce.PURCHASE)
+    events = rows_of(weekday, commerce.PURCHASE)
-    numbers = [cell[0] for cell in orders["purchaseID"]]
+    numbers = [cell[0] for cell in events["purchaseID"]]
     date = str(weekday.columns["EventDate"][0]).replace("-", "")
-    assert numbers == [f"{date}-{place:04d}" for place in range(1, len(numbers) + 1)]
+    expected = [f"{date}-{place:04d}" for place in range(1, len(weekday.orders) + 1)]
-    assert len(set(numbers)) == len(numbers)
+    # Порча идет после нумерации: потеря оставляет дыру, а дубль
-    # Нумерация идёт в порядке событий: строки дня уже упорядочены по времени.
+    # повторяет готовый номер и не двигает соседей.
-    assert list(orders["UTCEventTime"]) == sorted(orders["UTCEventTime"])
+    assert list(weekday.orders.order_id) == expected
+    assert set(numbers) <= set(expected)
+    assert list(events["UTCEventTime"]) == sorted(events["UTCEventTime"])
 
 
 def test_the_coupon_comes_from_the_world_table_and_does_not_touch_the_revenue(
@@ -599,7 +604,23 @@ def test_the_trade_flow_draws_from_its_own_named_branch(
 
     monkeypatch.setattr(commerce, "day_stream", spy)
     day.stream(CANONICAL_SEED, WEEKDAY)
-    assert asked == [(CANONICAL_SEED, WEEKDAY, Component.COMMERCE)]
+    assert asked == [
+        (CANONICAL_SEED, WEEKDAY, Component.COMMERCE),
+        (CANONICAL_SEED, WEEKDAY, Component.BEACONS),
+    ]
+
+
+def test_an_assigned_purchase_is_never_lost(monkeypatch: pytest.MonkeyPatch):
+    """Гарантия плана сильнее порчи: мост склейки не теряется."""
+    monkeypatch.setattr(world, "LOST_PURCHASE_PERCENT", 100)
+    monkeypatch.setattr(world, "DUPLICATE_PURCHASE_PERCENT", 0)
+    events = day.stream(CANONICAL_SEED, WEEKDAY)
+    audience = plan.audience(CANONICAL_SEED, WEEKDAY)
+
+    promised = set(audience.client_id[audience.assigned_order].tolist())
+    bought = set(rows_of(events, commerce.PURCHASE)["ClientID"].tolist())
+    assert promised
+    assert bought == promised
 
 
 def test_the_promised_orders_of_a_pair_become_purchases(week: list[day.Day]):
@@ -627,6 +648,78 @@ def test_the_promised_orders_of_a_pair_become_purchases(week: list[day.Day]):
     assert pairs == plan.counters(CANONICAL_SEED, WEEK).pairs
 
 
+def test_a_duplicate_repeats_the_confirmation_story(weekday: day.Day):
+    """Обновление повторяет просмотр и purchase в том же визите."""
+    purchases = rows_of(weekday, commerce.PURCHASE)
+    ids_by_order: dict[str, list[int]] = {}
+    for row, cell in enumerate(purchases["purchaseID"]):
+        ids_by_order.setdefault(str(cell[0]), []).append(row)
+    duplicated = [rows for rows in ids_by_order.values() if len(rows) == 2]
+
+    expected = int((weekday.purchase_outcome == commerce.EventOutcome.DUPLICATED).sum())
+    assert len(duplicated) == expected > 0
+    for pair in duplicated:
+        first, second = sorted(pair, key=lambda row: purchases["UTCEventTime"][row])
+        delay = (
+            (purchases["UTCEventTime"][second] - purchases["UTCEventTime"][first])
+            .astype("timedelta64[s]")
+            .astype(int)
+        )
+        assert world.DUPLICATE_DELAY_SECONDS[0] <= delay
+        assert delay < world.DUPLICATE_DELAY_SECONDS[1]
+        assert delay < world.VISIT_TIMEOUT_SECONDS
+        assert purchases["VisitID"][first] == purchases["VisitID"][second]
+        assert purchases["WatchID"][first] != purchases["WatchID"][second]
+        for name in (
+            "purchaseID",
+            "purchaseRevenue",
+            "productID",
+            "productQuantity",
+            "ecommerce",
+        ):
+            left, right = purchases[name][first], purchases[name][second]
+            if isinstance(left, np.ndarray):
+                assert np.array_equal(left, right), name
+            else:
+                assert left == right, name
+
+        visit = purchases["VisitID"][first]
+        confirmation = (
+            (weekday.columns["EventType"] == "pageview")
+            & (weekday.page == Page.CONFIRMATION)
+            & (weekday.columns["VisitID"] == visit)
+        )
+        views = np.flatnonzero(confirmation)
+        assert views.size == 2
+        assert len(set(weekday.columns["WatchID"][views].tolist())) == 2
+        view_delay = (
+            (
+                weekday.columns["UTCEventTime"][views].max()
+                - weekday.columns["UTCEventTime"][views].min()
+            )
+            .astype("timedelta64[s]")
+            .astype(int)
+        )
+        assert view_delay == delay
+
+        cookie = purchases["ClientID"][first]
+        later_visit = (
+            (weekday.columns["ClientID"] == cookie)
+            & (weekday.columns["VisitID"] != visit)
+            & (weekday.columns["UTCEventTime"] > purchases["UTCEventTime"][second])
+        )
+        if np.any(later_visit):
+            gap = (
+                (
+                    weekday.columns["UTCEventTime"][later_visit].min()
+                    - purchases["UTCEventTime"][second]
+                )
+                .astype("timedelta64[s]")
+                .astype(int)
+            )
+            assert gap > world.VISIT_TIMEOUT_SECONDS
+
+
 def paired_cookies() -> set[int]:
     """Куки двухкуковых пар: их заказы обещаны планом, а не решены днём."""
     cookies: set[int] = set()
@@ -642,21 +735,26 @@ def test_flagged_buyers_buy_again_much_more_often(week: list[day.Day]):
     «Постоянный покупатель» читается только так — как кука, которая ходит
     неделями и покупает не раз: метки в событии нет и не будет.
 
-    Куки двухкуковых пар из счёта исключены: их заказы назначил план, и
+    Куки двухкуковых пар из счета исключены: их заказы назначил план, и
-    вместе с ними лифт мерил бы гарантию, а не два новых рычага. Остаются
+    вместе с ними лифт мерил бы гарантию, а не два новых рычага. Даже после
-    те помеченные, чьи покупки решил день: повторно покупают 4,6% из них
+    событийной порчи оставшиеся помеченные покупают повторно более чем вдвое
-    против 1,5% прочих — втрое чаще при пороге «вдвое».
+    чаще прочих.
     """
-    purchases: dict[int, int] = {}
+    purchases: dict[int, set[str]] = {}
     flagged: set[int] = set()
     for number, events in enumerate(week):
         audience = plan.audience(CANONICAL_SEED, number)
         flagged |= set(audience.client_id[audience.buyer].tolist())
-        for cookie in rows_of(events, commerce.PURCHASE)["ClientID"].tolist():
+        rows = rows_of(events, commerce.PURCHASE)
-            purchases[cookie] = purchases.get(cookie, 0) + 1
+        for cookie, order_id in zip(
+            rows["ClientID"].tolist(),
+            (str(cell[0]) for cell in rows["purchaseID"]),
+            strict=True,
+        ):
+            purchases.setdefault(cookie, set()).add(order_id)
 
     def repeat_share(cookies: set[int]) -> float:
-        again = sum(1 for cookie in cookies if purchases[cookie] > 1)
+        again = sum(1 for cookie in cookies if len(purchases[cookie]) > 1)
         return again / len(cookies)
 
     buyers = set(purchases)

generator/tests/test_day.py

@@ -68,6 +68,7 @@ def orders(events: day.Day) -> list[list[Any]]:
             int(theirs.outcome[number]),
             int(theirs.paid_after[number]),
             int(theirs.cancelled_after[number]),
+            int(theirs.snapshot_delay[number]),
         ]
         for number in range(len(theirs))
     ]
@@ -88,6 +89,7 @@ def snapshot(events: day.Day) -> dict[str, Any]:
         "page": events.page.tolist(),
         "product": events.product.tolist(),
         "orders": orders(events),
+        "purchase_outcome": events.purchase_outcome.tolist(),
     }
 
 
@@ -115,6 +117,7 @@ def test_the_snapshot_notices_everything_the_day_hands_out(weekday: day.Day):
         page=weekday.page,
         product=weekday.product,
         orders=weekday.orders,
+        purchase_outcome=weekday.purchase_outcome,
     )
     assert snapshot(reordered) != original
 

generator/tests/test_demo.py

@@ -0,0 +1,32 @@
+"""Запускаемый путеводитель остается коротким и проходит всю цепочку."""
+
+import subprocess
+from pathlib import Path
+
+
+def test_demo_runs_and_shows_the_whole_chain() -> None:
+    """Сторожит команду и стадии, а числа мира оставляет описи."""
+    finished = subprocess.run(
+        ["make", "--silent", "demo"],
+        check=False,
+        capture_output=True,
+        cwd=Path(__file__).parents[1],
+        text=True,
+    )
+
+    assert finished.returncode == 0, finished.stderr
+    lines = finished.stdout.splitlines()
+    assert [line.partition(":")[0] for line in lines] == [
+        "Зерно",
+        "Подпотоки D0",
+        "Когорта D0",
+        "Аудитория D0",
+        "Визиты по VisitID",
+        "Строки событий",
+    ]
+    assert "когорты D-" in lines[3] and "...D0" in lines[3]
+    assert "строк в группе" in lines[4]
+    assert all(
+        label in lines[5]
+        for label in ("pageview", "add_to_cart", "purchase", "заказов")
+    )

generator/tests/test_inventory.py

@@ -17,7 +17,9 @@ from pathlib import Path
 import pytest
 
 from clickstream_generator import cli
+from clickstream_generator import day as day_module
 from clickstream_generator.inventory import STARTING_DAYS, build
+from clickstream_generator.seeds import CANONICAL_SEED
 
 INVENTORY_PATH = Path(__file__).resolve().parents[2] / "data" / "world-inventory.json"
 
@@ -25,6 +27,9 @@ INVENTORY_PATH = Path(__file__).resolve().parents[2] / "data" / "world-inventory
 # отправляемых; этот дешевле прочих — его окно короче.
 RUN_DAY = 2
 
+# День любой: хеш дня не зависит ни от соседей, ни от края описи.
+REPLAY_DAY = 4
+
 
 @pytest.fixture(scope="module")
 def inventory() -> dict:
@@ -41,6 +46,24 @@ def test_inventory_is_up_to_date(inventory: dict):
     )
 
 
+def test_order_class_counters_cover_only_closed_days(inventory: dict):
+    """Итог заказа становится опорой только после закрытия его окна."""
+    rows = [row for row in inventory["days"] if "orders" in row]
+
+    assert [row["day"] for row in rows] == [0]
+    assert set(rows[0]["orders"]) == {
+        "match",
+        "cancelled",
+        "lost_event",
+        "duplicate_event",
+        "amount_delta",
+    }
+    assert rows[0]["orders"]["lost_event"] > 0
+    assert rows[0]["orders"]["duplicate_event"] > 0
+    today = day_module.stream(CANONICAL_SEED, rows[0]["day"])
+    assert sum(rows[0]["orders"].values()) == len(today.orders)
+
+
 def test_the_inventory_holds_the_hash_of_every_sent_snapshot(inventory: dict, tmp_path):
     """У каждого отправленного слепка — своя строка с хешем его байтов.
 
@@ -60,3 +83,17 @@ def test_the_inventory_holds_the_hash_of_every_sent_snapshot(inventory: dict, tm
 
     row = next(row for row in inventory["snapshots"] if row["day"] == RUN_DAY - 1)
     assert row["sha256"] == sent
+
+
+def test_a_replayed_day_matches_its_inventory_hash(tmp_path):
+    """Опись сверяется с байтами, вышедшими из CLI, а не с собранной тут же:
+    пересчет сравнивался бы сам с собой.
+    """
+    stored = json.loads(INVENTORY_PATH.read_text(encoding="utf-8"))
+    path = tmp_path / "day.jsonl"
+
+    assert cli.main(["batch", "--day", str(REPLAY_DAY), "--file", str(path)]) == 0
+
+    sent = hashlib.sha256(path.read_bytes()).hexdigest()
+    row = next(row for row in stored["days"] if row["day"] == REPLAY_DAY)
+    assert row["sha256"] == sent

generator/tests/test_orders.py

@@ -58,17 +58,52 @@ def user_id_by_order(events: day.Day) -> dict[str, int]:
     )
 
 
-def test_every_order_of_the_day_is_a_purchase_of_the_day(weekday: day.Day):
+def purchase_row_by_order(
-    """Заказ — вторая проекция покупки, а не второе порождение.
+    events: day.Day,
+) -> tuple[dict[str, NDArray[Any]], dict[str, int]]:
+    """Первая строка purchase каждого доехавшего заказа."""
+    rows = purchases_of(events)
+    index: dict[str, int] = {}
+    for row, cell in enumerate(rows["purchaseID"]):
+        index.setdefault(str(cell[0]), row)
+    return rows, index
 
-    У всякого заказа ровно одно событие `purchase`, и номер у них один:
+
-    сойтись двум источникам больше негде — сверка стенда соединяется
+def test_every_order_of_the_day_is_a_purchase_of_the_day(weekday: day.Day):
-    именно по нему.
+    """Заказ рождается до потери или дубля его событийной проекции."""
-    """
     events = purchases_of(weekday)
     numbers = [cell[0] for cell in events["purchaseID"]]
     assert len(numbers) > 100
-    assert list(weekday.orders.order_id) == numbers
+    lost = {
+        order_id
+        for order_id, outcome in zip(
+            weekday.orders.order_id, weekday.purchase_outcome, strict=True
+        )
+        if outcome == commerce.EventOutcome.LOST
+    }
+    assert set(numbers) == set(weekday.orders.order_id) - lost
+    assert len(numbers) - len(set(numbers)) == int(
+        (weekday.purchase_outcome == commerce.EventOutcome.DUPLICATED).sum()
+    )
+
+
+def test_an_assigned_order_never_waits_for_a_later_snapshot(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    """Гарантия плана сильнее опоздания: мост склейки приезжает сразу."""
+    # Все неназначенные заказы опаздывают на два дня. Нулевую задержку после
+    # такого броска могут получить только заказы, защищённые планом.
+    monkeypatch.setattr(
+        orders, "_SNAPSHOT_DELAY_CUMULATIVE", np.array([0, 0, 1], dtype=np.int64)
+    )
+    events = day.stream(CANONICAL_SEED, WEEKDAY)
+    audience = plan.audience(CANONICAL_SEED, WEEKDAY)
+
+    promised = set(audience.person_id[audience.assigned_order].tolist())
+    immediate = set(events.orders.user_id[events.orders.snapshot_delay == 0].tolist())
+    assert promised
+    assert immediate == promised
+    assert (events.orders.snapshot_delay == 2).any()
 
 
 def dropped_line(client: list[tuple[Any, int]], order: list[tuple[Any, int]]):
@@ -88,16 +123,18 @@ def test_the_order_repeats_the_purchase_up_to_one_dropped_line(weekday: day.Day)
     """
     goods = catalog.catalog()
     price = dict(zip(goods.sku.tolist(), goods.price.tolist(), strict=True))
-    events = purchases_of(weekday)
+    events, row_by_order = purchase_row_by_order(weekday)
     money = weekday.orders
     deltas = 0
 
     for number, order in enumerate(weekday.orders.order_id):
-        assert order == events["purchaseID"][number][0]
+        if weekday.purchase_outcome[number] == commerce.EventOutcome.LOST:
+            continue
+        row = row_by_order[order]
         client = list(
             zip(
-                events["productID"][number].tolist(),
+                events["productID"][row].tolist(),
-                events["productQuantity"][number].tolist(),
+                events["productQuantity"][row].tolist(),
                 strict=True,
             )
         )
@@ -110,7 +147,7 @@ def test_the_order_repeats_the_purchase_up_to_one_dropped_line(weekday: day.Day)
         )
         # Выручка клиента и `items_total` бэкенда — одно число: в событии
         # оно дробное, у заказа целое в копейках.
-        revenue = round(events["purchaseRevenue"][number][0] * commerce.KOPECKS)
+        revenue = round(events["purchaseRevenue"][row][0] * commerce.KOPECKS)
         if mine == client:
             assert money.items_total[number] == revenue
             continue
@@ -136,15 +173,18 @@ def test_the_discount_comes_from_the_coupon_of_the_event(
 
     for today in start_world:
         money = today.orders
-        events = purchases_of(today)
+        events, row_by_order = purchase_row_by_order(today)
-        codes = [cell[0] for cell in events["purchaseCoupon"]]
+        for number, order_id in enumerate(money.order_id):
-        for number, code in enumerate(codes):
+            if today.purchase_outcome[number] == commerce.EventOutcome.LOST:
+                continue
+            row = row_by_order[order_id]
+            code = events["purchaseCoupon"][row][0]
             items_total = money.items_total[number]
             expected = items_total * percent[code] // 100 if code else 0
             assert money.discount[number] == expected, money.order_id[number]
             assert money.discount[number] < items_total
 
-            revenue = round(events["purchaseRevenue"][number][0] * commerce.KOPECKS)
+            revenue = round(events["purchaseRevenue"][row][0] * commerce.KOPECKS)
             discounted_delta += int(bool(code) and items_total != revenue)
 
     # Иначе проверка не отличила бы новую базу скидки от прежней.
@@ -255,8 +295,13 @@ def test_the_user_id_is_the_person_behind_the_cookie(weekday: day.Day):
         zip(audience.client_id.tolist(), audience.person_id.tolist(), strict=True)
     )
     events = purchases_of(weekday)
-    for number, cookie in enumerate(events["ClientID"].tolist()):
+    by_order = user_id_by_order(weekday)
-        assert weekday.orders.user_id[number] == person[cookie]
+    for order_id, cookie in zip(
+        (cell[0] for cell in events["purchaseID"]),
+        events["ClientID"].tolist(),
+        strict=True,
+    ):
+        assert by_order[order_id] == person[cookie]
     assert np.all(weekday.orders.user_id > 0)
     assert weekday.orders.user_id.max() < 2**53
 

generator/tests/test_plan.py

@@ -14,8 +14,8 @@ import pytest
 from clickstream_generator import plan, reference, world
 from clickstream_generator.seeds import CANONICAL_SEED
 
-# Горизонт эталонного снимка — две недели (спека, раздел 5).
+# Окно замера плана — две недели: два цикла недельной сезонности.
-SNAPSHOT_DAYS = 14
+WINDOW_DAYS = 14
 
 
 @pytest.fixture(autouse=True)
@@ -54,9 +54,9 @@ def test_the_plan_is_a_pure_function_of_the_seed():
 
 
 def test_counters_are_a_pure_function_of_the_seed():
-    first = plan.counters(CANONICAL_SEED, SNAPSHOT_DAYS)
+    first = plan.counters(CANONICAL_SEED, WINDOW_DAYS)
     plan.cohort.cache_clear()
-    assert first == plan.counters(CANONICAL_SEED, SNAPSHOT_DAYS)
+    assert first == plan.counters(CANONICAL_SEED, WINDOW_DAYS)
 
 
 def test_a_remembered_cohort_cannot_be_spoiled_from_outside():
@@ -216,12 +216,12 @@ def test_the_passport_points_into_the_directories():
 
 def test_the_daily_audience_matches_the_spec_band():
     """6–8 тыс. посетителей в день — правдоподобный средний магазин."""
-    counters = plan.counters(CANONICAL_SEED, SNAPSHOT_DAYS)
+    counters = plan.counters(CANONICAL_SEED, WINDOW_DAYS)
     assert all(6_000 <= size <= 8_000 for size in counters.audience)
 
 
 def test_the_influx_holds_its_daily_number():
-    counters = plan.counters(CANONICAL_SEED, SNAPSHOT_DAYS)
+    counters = plan.counters(CANONICAL_SEED, WINDOW_DAYS)
     average = sum(counters.new_cookies) / len(counters.new_cookies)
     assert abs(average - world.DAILY_INFLUX) < world.DAILY_INFLUX // 10
 
@@ -232,7 +232,7 @@ def test_the_influx_breathes_with_the_week():
     def mean(numbers: tuple[int, ...] | list[int]) -> float:
         return sum(numbers) / len(numbers)
 
-    counters = plan.counters(CANONICAL_SEED, SNAPSHOT_DAYS)
+    counters = plan.counters(CANONICAL_SEED, WINDOW_DAYS)
     weekdays = [size for day, size in enumerate(counters.new_cookies) if day % 7 < 5]
     weekend = [size for day, size in enumerate(counters.new_cookies) if day % 7 >= 5]
     expected = mean(world.WEEKLY_PROFILE_PERCENT[5:]) / mean(
@@ -250,7 +250,7 @@ def test_the_influx_differs_even_on_the_same_weekday():
 def test_the_influx_is_visible_on_the_plan():
     """Накопленная аудитория растёт с горизонтом и с дневной не сходится."""
     week = plan.counters(CANONICAL_SEED, 7)
-    fortnight = plan.counters(CANONICAL_SEED, SNAPSHOT_DAYS)
+    fortnight = plan.counters(CANONICAL_SEED, WINDOW_DAYS)
     assert week.visitors < fortnight.visitors
     assert fortnight.visitors > 2 * max(fortnight.audience)
 
@@ -258,21 +258,21 @@ def test_the_influx_is_visible_on_the_plan():
 def test_the_horizon_is_a_prefix_not_another_world():
     """Продление истории днём N+1 не трогает дни 1…N."""
     week = plan.counters(CANONICAL_SEED, 7)
-    fortnight = plan.counters(CANONICAL_SEED, SNAPSHOT_DAYS)
+    fortnight = plan.counters(CANONICAL_SEED, WINDOW_DAYS)
     assert fortnight.audience[:7] == week.audience
     assert fortnight.new_cookies[:7] == week.new_cookies
 
 
 def test_counters_count_the_same_audience_that_the_day_gets():
     """Счётчики и дня-функция спрашивают один план — расходиться им негде."""
-    counters = plan.counters(CANONICAL_SEED, SNAPSHOT_DAYS)
+    counters = plan.counters(CANONICAL_SEED, WINDOW_DAYS)
-    for day in (0, 7, SNAPSHOT_DAYS - 1):
+    for day in (0, 7, WINDOW_DAYS - 1):
         actual = plan.audience(CANONICAL_SEED, day).client_id.size
         assert actual == counters.audience[day]
 
 
 def test_counters_know_the_pairs_before_a_single_event():
-    counters = plan.counters(CANONICAL_SEED, SNAPSHOT_DAYS)
+    counters = plan.counters(CANONICAL_SEED, WINDOW_DAYS)
     assert counters.pairs > 0
 
 

generator/tests/test_seeds.py

@@ -78,7 +78,7 @@ def test_day_components_do_not_share_randomness():
         Component.TRAFFIC,
         Component.COMMERCE,
         Component.ORDERS,
-        Component.LATECOMERS,
+        Component.BEACONS,
     )
     assert len({int(component) for component in components}) == 4
     draws = {

generator/tests/test_snapshot.py

@@ -128,7 +128,9 @@ def test_the_record_matches_the_wire_contract(days: list[day_module.Day]):
         )
 
         if _born(record) == _date(SHORT_WINDOW_DAY):
-            assert record["created_at"][:19] + "Z" == bought[record["order_id"]]
+            # Потерянного purchase в трекере нет, но заказ остается.
+            if record["order_id"] in bought:
+                assert record["created_at"][:19] + "Z" == bought[record["order_id"]]
 
 
 def test_negative_money_does_not_leave_the_source(days: list[day_module.Day]):
@@ -174,6 +176,63 @@ def test_the_rows_go_in_the_order_of_birth(days: list[day_module.Day]):
     assert len(set(numbers)) == len(numbers)
 
 
+def test_lateness_changes_only_the_rows_present_in_a_snapshot(
+    days: list[day_module.Day],
+):
+    """Неопоздавшие строки остаются прежними байтами и в прежнем порядке."""
+    number = SHORT_WINDOW_DAY
+    window = [today.orders for today in days[: number + 1]]
+    eager = serialize.orders(
+        [
+            replace(rows, snapshot_delay=np.zeros_like(rows.snapshot_delay))
+            for rows in window
+        ],
+        number,
+    )
+    actual = serialize.orders(window, number)
+    actual_ids = {json.loads(payload)["order_id"] for payload in actual}
+    expected = [
+        payload for payload in eager if json.loads(payload)["order_id"] in actual_ids
+    ]
+
+    assert len(actual) < len(eager)
+    assert actual == expected
+
+
+def test_a_two_day_late_order_first_arrives_in_its_lived_state(
+    days: list[day_module.Day],
+):
+    """Заказ δ = 2 пропускает D и D+1 и догоняет жизнь, не меняя `created_at`."""
+    honest = days[0].orders
+    target = 0
+    delay = np.zeros_like(honest.snapshot_delay)
+    delay[target] = 2
+    cancelled_after = honest.cancelled_after.copy()
+    cancelled_after[target] = 30 * 3600
+    late = replace(
+        honest,
+        snapshot_delay=delay,
+        cancelled_after=cancelled_after,
+    )
+    order_id = late.order_id[target]
+
+    for number in (0, 1):
+        assert order_id not in {
+            json.loads(payload)["order_id"]
+            for payload in serialize.orders([late], number)
+        }
+
+    arrived = {
+        record["order_id"]: record
+        for record in map(json.loads, serialize.orders([late], 2))
+    }[order_id]
+    created_at = np.datetime_as_string(
+        late.created_at[target], unit="ms", timezone="UTC"
+    )
+    assert arrived["status"] == "cancelled"
+    assert arrived["created_at"] == created_at
+
+
 def test_the_state_is_read_at_the_boundary_of_the_day(days: list[day_module.Day]):
     """Дыхание окна: оплаченный назавтра заказ в сегодняшнем слепке `created`.
 
@@ -325,7 +384,10 @@ def _purchase_times(today: day_module.Day) -> dict[str, str]:
     times = np.datetime_as_string(
         today.columns["UTCEventTime"][here], unit="s", timezone="UTC"
     )
-    return dict(zip(numbers, times.tolist(), strict=True))
+    result: dict[str, str] = {}
+    for number, moment in zip(numbers, times.tolist(), strict=True):
+        result.setdefault(number, moment)
+    return result
 
 
 def _born(record: dict) -> date:

generator/tests/test_world.py

@@ -122,6 +122,11 @@ def test_the_trade_event_never_overtakes_the_next_page():
     assert max(world.TRADE_DELAY_SECONDS) <= min(world.PAGE_PAUSE_SECONDS)
 
 
+def test_the_duplicate_delay_stays_inside_a_visit_timeout():
+    assert 0 < min(world.DUPLICATE_DELAY_SECONDS)
+    assert max(world.DUPLICATE_DELAY_SECONDS) <= world.VISIT_TIMEOUT_SECONDS
+
+
 def conversion(cart: int, checkout_of_cart: int) -> float:
     """Конверсия визита в заказ, проценты: произведение трёх шагов воронки."""
     return cart * checkout_of_cart * world.CONFIRMATION_OF_CHECKOUT_PERCENT / 100**2

infra/airflow/Dockerfile

@@ -2,14 +2,19 @@ FROM apache/airflow:3.3.0
 
 USER root
 
+# SQL-файлы ClickHouse исполняет официальный провайдер Airflow. Он разрешает
+# любую версию clickhouse-connect >= 1.3.0, поэтому драйвер закреплён отдельно:
+# сборка стенда не должна незаметно менять транспорт при обновлении зависимостей.
+#
 # Официальный провайдер Kafka использует тот же confluent-kafka. Пробникам
 # не нужны его подключения и обёртки, поэтому в образ добавлен сам клиент.
 #
 # Провайдера docker, которым пульт мира зовёт генератор, ставить не нужно:
 # база несёт его сама — 4.5.7 к Airflow 3.3.0, замер 13 августа 2026 года.
 RUN uv pip install --python /home/airflow/.local/bin/python --no-cache \
+        "apache-airflow-providers-clickhousedb==1.0.0" \
         "clickhouse-connect==1.6.0" \
         "confluent-kafka==2.15.0" \
-    && python -c "import clickhouse_connect, confluent_kafka"
+    && python -c "import airflow.providers.clickhousedb, clickhouse_connect, confluent_kafka"
 
 USER airflow

infra/airflow/init.sh

@@ -22,11 +22,26 @@ PY
 
 runuser -u airflow -- airflow db migrate
 runuser -u airflow -- airflow connections delete clickhouse_default >/dev/null 2>&1 || true
+# Прикладные запросы короткие: 30 с отличают зависший транспорт от работы запроса.
 runuser -u airflow -- airflow connections add clickhouse_default \
-    --conn-type generic \
+    --conn-type clickhouse \
     --conn-host clickhouse-01 \
     --conn-port 8123 \
     --conn-login etl \
     --conn-password "$CLICKHOUSE_ETL_PASSWORD" \
     --conn-schema default \
-    --conn-description "ClickHouse, нода 1; типизированный провайдер появится на этапе ETL"
+    --conn-extra '{"connect_timeout": 5, "send_receive_timeout": 30}' \
+    --conn-description "ClickHouse, нода 1; запросы прикладных дагов"
+
+runuser -u airflow -- airflow connections delete clickhouse_lifecycle >/dev/null 2>&1 || true
+# `ON CLUSTER` ждёт хосты до 180 с. Транспорт живёт дольше, чтобы ClickHouse
+# успел назвать незавершённый хост вместо сетевого тайм-аута.
+runuser -u airflow -- airflow connections add clickhouse_lifecycle \
+    --conn-type clickhouse \
+    --conn-host clickhouse-01 \
+    --conn-port 8123 \
+    --conn-login lifecycle \
+    --conn-password "$CLICKHOUSE_LIFECYCLE_PASSWORD" \
+    --conn-schema default \
+    --conn-extra '{"connect_timeout": 5, "send_receive_timeout": 300}' \
+    --conn-description "ClickHouse, нода 1; создание и пересоздание прикладного мира"

infra/clickhouse/users.d/access.xml

@@ -25,9 +25,26 @@
                 <query>GRANT FILE ON *.*</query>
             </grants>
         </etl_writer>
+        <!-- Жизненный цикл мира: тот же канонический DDL, но с удалением баз. -->
+        <lifecycle_owner>
+            <grants>
+                <query>GRANT SELECT, INSERT, ALTER, CREATE TABLE, CREATE VIEW, DROP TABLE, DROP VIEW, CREATE DATABASE, DROP DATABASE ON stg.*</query>
+                <query>GRANT SELECT, INSERT, ALTER, CREATE TABLE, CREATE VIEW, DROP TABLE, DROP VIEW, CREATE DATABASE, DROP DATABASE ON ods.*</query>
+                <query>GRANT SELECT, INSERT, ALTER, CREATE TABLE, CREATE VIEW, DROP TABLE, DROP VIEW, CREATE DATABASE, DROP DATABASE ON dds.*</query>
+                <query>GRANT SELECT, INSERT, ALTER, CREATE TABLE, CREATE VIEW, DROP TABLE, DROP VIEW, CREATE DATABASE, DROP DATABASE ON dm.*</query>
+                <query>GRANT SELECT, CREATE TABLE, CREATE DICTIONARY, dictGet, DROP TABLE, DROP DICTIONARY, CREATE DATABASE, DROP DATABASE ON dic.*</query>
+                <!-- clickhouse-connect читает эту таблицу при подключении. -->
+                <query>GRANT SELECT ON system.settings</query>
+                <query>GRANT CLUSTER ON *.*</query>
+                <query>GRANT REMOTE ON *.*</query>
+                <query>GRANT KAFKA ON *.*</query>
+                <query>GRANT FILE ON *.*</query>
+            </grants>
+        </lifecycle_owner>
         <!-- Оба читателя: clickhouse-connect читает system.settings при подключении. -->
         <bi_reader>
             <grants>
+                <query>GRANT SELECT ON ods.*</query>
                 <query>GRANT SELECT ON dds.*</query>
                 <query>GRANT SELECT ON dm.*</query>
                 <query>GRANT SELECT, dictGet ON dic.*</query>
@@ -75,6 +92,13 @@
                 <query>GRANT etl_writer</query>
             </grants>
         </etl>
+        <lifecycle>
+            <password from_env="CLICKHOUSE_LIFECYCLE_PASSWORD"/>
+            <quota>default</quota>
+            <grants>
+                <query>GRANT lifecycle_owner</query>
+            </grants>
+        </lifecycle>
         <bi>
             <password from_env="CLICKHOUSE_BI_PASSWORD"/>
             <quota>default</quota>

infra/grafana/Dockerfile

@@ -6,6 +6,8 @@ FROM grafana/grafana:13.1.1
 USER root
 ENV GF_PATHS_PLUGINS=/usr/share/grafana/plugins \
     GF_PLUGINS_PREINSTALL_DISABLED=true
+ARG CLICKHOUSE_PLUGIN_VERSION=4.20.0
 RUN grafana cli --pluginsDir "$GF_PATHS_PLUGINS" \
-    plugins install grafana-clickhouse-datasource 4.20.0
+    --pluginUrl "https://github.com/grafana/clickhouse-datasource/releases/download/v${CLICKHOUSE_PLUGIN_VERSION}/grafana-clickhouse-datasource-${CLICKHOUSE_PLUGIN_VERSION}.zip" \
+    plugins install grafana-clickhouse-datasource "$CLICKHOUSE_PLUGIN_VERSION"
 USER grafana

infra/grafana/provisioning/dashboards/cluster.json

@@ -0,0 +1,318 @@
+{
+  "uid": "cluster",
+  "title": "Кластер",
+  "timezone": "utc",
+  "schemaVersion": 42,
+  "refresh": "30s",
+  "time": {
+    "from": "now-30m",
+    "to": "now"
+  },
+  "panels": [
+    {
+      "type": "timeseries",
+      "title": "Процессор: сколько ядер занимает нода",
+      "datasource": {
+        "type": "grafana-clickhouse-datasource",
+        "uid": "clickhouse"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 8,
+        "x": 0,
+        "y": 0
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "datasource": {
+            "type": "grafana-clickhouse-datasource",
+            "uid": "clickhouse"
+          },
+          "editorType": "sql",
+          "queryType": "timeseries",
+          "format": 0,
+          "rawSql": "SELECT\n    $__timeInterval(event_time) AS t,\n    hostName() AS node,\n    -- Процессорное время самого сервера. Метрики с именами OS* сняты с машины\n    -- целиком, и в них обе ноды показывали бы одно и то же число.\n    sum(ProfileEvent_OSCPUVirtualTimeMicroseconds) / 1e6 / $__interval_s AS \"ядер\"\nFROM clusterAllReplicas('clickstream_cluster', system.metric_log)\nWHERE $__timeFilter(event_time)\nGROUP BY t, node\nORDER BY t, node"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "displayName": "${__field.labels.node}",
+          "min": 0,
+          "decimals": 2
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "Память: сколько нода занимает и сколько ей отведено",
+      "datasource": {
+        "type": "grafana-clickhouse-datasource",
+        "uid": "clickhouse"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 8,
+        "x": 8,
+        "y": 0
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "datasource": {
+            "type": "grafana-clickhouse-datasource",
+            "uid": "clickhouse"
+          },
+          "editorType": "sql",
+          "queryType": "timeseries",
+          "format": 0,
+          "rawSql": "SELECT\n    $__timeInterval(event_time) AS t,\n    hostName() AS node,\n    -- Занятое меряется резидентной памятью: именно её ядро сравнивает с\n    -- пределом контейнера, когда решает, убить ли ноду.\n    maxIf(value, metric = 'MemoryResident') AS \"занято\",\n    maxIf(value, metric = 'CGroupMemoryTotal') AS \"отведено\"\nFROM clusterAllReplicas('clickstream_cluster', system.asynchronous_metric_log)\nWHERE $__timeFilter(event_time)\n    AND metric IN ('MemoryResident', 'CGroupMemoryTotal')\nGROUP BY t, node\nORDER BY t, node"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "displayName": "${__field.name} · ${__field.labels.node}",
+          "min": 0,
+          "unit": "bytes"
+        },
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byRegexp",
+              "options": "отведено.*"
+            },
+            "properties": [
+              {
+                "id": "custom.lineStyle",
+                "value": {
+                  "fill": "dash",
+                  "dash": [
+                    10,
+                    10
+                  ]
+                }
+              },
+              {
+                "id": "custom.fillOpacity",
+                "value": 0
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "Диски: сколько нода читает и пишет",
+      "datasource": {
+        "type": "grafana-clickhouse-datasource",
+        "uid": "clickhouse"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 8,
+        "x": 16,
+        "y": 0
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "datasource": {
+            "type": "grafana-clickhouse-datasource",
+            "uid": "clickhouse"
+          },
+          "editorType": "sql",
+          "queryType": "timeseries",
+          "format": 0,
+          "rawSql": "SELECT\n    $__timeInterval(event_time) AS t,\n    hostName() AS node,\n    -- Байты, прошедшие через обращения к файлам: чтение из страничного кэша\n    -- тоже видно. Счётчики блочного устройства на вставке молчат.\n    sum(ProfileEvent_OSReadChars) / $__interval_s AS \"чтение\",\n    sum(ProfileEvent_OSWriteChars) / $__interval_s AS \"запись\"\nFROM clusterAllReplicas('clickstream_cluster', system.metric_log)\nWHERE $__timeFilter(event_time)\nGROUP BY t, node\nORDER BY t, node"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "displayName": "${__field.name} · ${__field.labels.node}",
+          "min": 0,
+          "unit": "Bps"
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "table",
+      "title": "Части: сколько их у таблицы и по сколько строк в каждой",
+      "datasource": {
+        "type": "grafana-clickhouse-datasource",
+        "uid": "clickhouse"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 8
+      },
+      "options": {},
+      "targets": [
+        {
+          "refId": "A",
+          "datasource": {
+            "type": "grafana-clickhouse-datasource",
+            "uid": "clickhouse"
+          },
+          "editorType": "sql",
+          "queryType": "table",
+          "format": 1,
+          "rawSql": "SELECT\n    concat(database, '.', table) AS \"Таблица\",\n    hostName() AS \"Нода\",\n    count() AS \"Частей\",\n    sum(rows) AS \"Строк\",\n    round(sum(rows) / count()) AS \"Строк в части\",\n    sum(bytes_on_disk) AS \"На диске\"\nFROM clusterAllReplicas('clickstream_cluster', system.parts)\nWHERE active\n    AND database != 'system'\nGROUP BY \"Таблица\", \"Нода\"\nORDER BY \"Таблица\", \"Нода\"\n"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "На диске"
+            },
+            "properties": [
+              {
+                "id": "unit",
+                "value": "bytes"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "type": "timeseries",
+      "title": "Слияния: сколько частей они съедают",
+      "datasource": {
+        "type": "grafana-clickhouse-datasource",
+        "uid": "clickhouse"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 8
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "datasource": {
+            "type": "grafana-clickhouse-datasource",
+            "uid": "clickhouse"
+          },
+          "editorType": "sql",
+          "queryType": "timeseries",
+          "format": 0,
+          "rawSql": "SELECT\n    $__timeInterval(event_time) AS t,\n    database AS db,\n    sum(length(merged_from)) AS \"частей съедено\"\nFROM clusterAllReplicas('clickstream_cluster', system.part_log)\nWHERE $__timeFilter(event_time)\n    AND event_type = 'MergeParts'\n    AND database != 'system'\nGROUP BY t, db\nORDER BY t, db"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "displayName": "${__field.labels.db}",
+          "min": 0,
+          "custom": {
+            "drawStyle": "bars",
+            "fillOpacity": 60,
+            "stacking": {
+              "mode": "normal"
+            }
+          }
+        },
+        "overrides": []
+      },
+      "interval": "1m"
+    },
+    {
+      "type": "timeseries",
+      "title": "Keeper: сколько узлов в дереве",
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "gridPos": {
+        "h": 7,
+        "w": 8,
+        "x": 0,
+        "y": 16
+      },
+      "options": {
+        "tooltip": {
+          "mode": "multi"
+        }
+      },
+      "targets": [
+        {
+          "refId": "A",
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prometheus"
+          },
+          "editorMode": "code",
+          "expr": "ClickHouseAsyncMetrics_KeeperZnodeCount",
+          "legendFormat": "узлов в дереве",
+          "range": true
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "min": 0
+        },
+        "overrides": []
+      }
+    },
+    {
+      "type": "table",
+      "title": "Распределённый DDL: что прошло по кластеру и чем кончилось",
+      "datasource": {
+        "type": "grafana-clickhouse-datasource",
+        "uid": "clickhouse"
+      },
+      "gridPos": {
+        "h": 7,
+        "w": 16,
+        "x": 8,
+        "y": 16
+      },
+      "options": {},
+      "targets": [
+        {
+          "refId": "A",
+          "datasource": {
+            "type": "grafana-clickhouse-datasource",
+            "uid": "clickhouse"
+          },
+          "editorType": "sql",
+          "queryType": "table",
+          "format": 1,
+          "rawSql": "SELECT\n    query_create_time AS \"Создан\",\n    entry AS \"Запись\",\n    host AS \"Нода\",\n    status AS \"Состояние\",\n    query_duration_ms AS \"Заняло, мс\",\n    exception_text AS \"Ошибка\",\n    query AS \"Запрос\"\nFROM system.distributed_ddl_queue\nORDER BY entry DESC, \"Нода\"\nLIMIT 20"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": []
+      }
+    }
+  ]
+}

infra/grafana/provisioning/dashboards/queries.json

@@ -0,0 +1,135 @@
+{
+  "uid": "queries",
+  "title": "Запросы",
+  "timezone": "utc",
+  "schemaVersion": 42,
+  "refresh": "30s",
+  "time": {
+    "from": "now-1h",
+    "to": "now"
+  },
+  "panels": [
+    {
+      "type": "table",
+      "title": "Тяжёлые запросы: что прочитало больше всех",
+      "datasource": {
+        "type": "grafana-clickhouse-datasource",
+        "uid": "clickhouse"
+      },
+      "gridPos": {
+        "h": 10,
+        "w": 24,
+        "x": 0,
+        "y": 0
+      },
+      "options": {},
+      "targets": [
+        {
+          "refId": "A",
+          "datasource": {
+            "type": "grafana-clickhouse-datasource",
+            "uid": "clickhouse"
+          },
+          "editorType": "sql",
+          "queryType": "table",
+          "format": 1,
+          "rawSql": "SELECT\n    event_time AS \"Когда\",\n    hostName() AS \"Нода\",\n    if(empty(user), 'фоновая работа сервера', user) AS \"Кто\",\n    query_duration_ms AS \"Заняло, мс\",\n    memory_usage AS \"Память\",\n    read_rows AS \"Прочитано строк\",\n    result_rows AS \"Отдано строк\",\n    query AS \"Запрос\"\nFROM clusterAllReplicas('clickstream_cluster', system.query_log)\nWHERE $__timeFilter(event_time)\n    -- Начало запроса записано отдельной строкой, и в ней ещё нет ни времени,\n    -- ни памяти. Куски распределённого запроса отброшены: считает их тот, кто\n    -- запрос затеял.\n    AND type != 'QueryStart'\n    AND is_initial_query\nORDER BY \"Прочитано строк\" DESC\nLIMIT 20"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "Память"
+            },
+            "properties": [
+              {
+                "id": "unit",
+                "value": "bytes"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "type": "table",
+      "title": "Кто спрашивает: сколько запросов и какой у них аппетит",
+      "datasource": {
+        "type": "grafana-clickhouse-datasource",
+        "uid": "clickhouse"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 24,
+        "x": 0,
+        "y": 10
+      },
+      "options": {},
+      "targets": [
+        {
+          "refId": "A",
+          "datasource": {
+            "type": "grafana-clickhouse-datasource",
+            "uid": "clickhouse"
+          },
+          "editorType": "sql",
+          "queryType": "table",
+          "format": 1,
+          "rawSql": "SELECT\n    if(empty(user), 'фоновая работа сервера', user) AS \"Кто\",\n    count() AS \"Запросов\",\n    sum(read_rows) AS \"Прочитано строк\",\n    max(memory_usage) AS \"Самый прожорливый, память\",\n    round(quantile(0.9)(query_duration_ms)) AS \"Девять из десяти быстрее, мс\"\nFROM clusterAllReplicas('clickstream_cluster', system.query_log)\nWHERE $__timeFilter(event_time)\n    AND type != 'QueryStart'\n    AND is_initial_query\nGROUP BY \"Кто\"\nORDER BY \"Прочитано строк\" DESC"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "Самый прожорливый, память"
+            },
+            "properties": [
+              {
+                "id": "unit",
+                "value": "bytes"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "type": "table",
+      "title": "Ошибки: на чём запросы споткнулись",
+      "datasource": {
+        "type": "grafana-clickhouse-datasource",
+        "uid": "clickhouse"
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 24,
+        "x": 0,
+        "y": 18
+      },
+      "options": {},
+      "targets": [
+        {
+          "refId": "A",
+          "datasource": {
+            "type": "grafana-clickhouse-datasource",
+            "uid": "clickhouse"
+          },
+          "editorType": "sql",
+          "queryType": "table",
+          "format": 1,
+          "rawSql": "SELECT\n    event_time AS \"Когда\",\n    hostName() AS \"Нода\",\n    if(empty(user), 'фоновая работа сервера', user) AS \"Кто\",\n    exception AS \"Чем кончилось\",\n    query AS \"Запрос\"\nFROM clusterAllReplicas('clickstream_cluster', system.query_log)\nWHERE $__timeFilter(event_time)\n    -- Здесь куски распределённого запроса нужны: отказ по памяти случается\n    -- на шарде, а не у того, кто спрашивал.\n    AND type IN ('ExceptionBeforeStart', 'ExceptionWhileProcessing')\nORDER BY \"Когда\" DESC\nLIMIT 20"
+        }
+      ],
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": []
+      }
+    }
+  ]
+}