docs: propose track2-reconcile-cost

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-23 03:47:27 +03:00
co-authored by Claude Opus 5.5
parent 7f4e626b49
commit dcdfe5f2e4
11 changed files with 2372 additions and 0 deletions
+94
View File
@@ -1426,3 +1426,97 @@ Change вне сводной таблицы, до `track2-reconcile-cost`: ис
**Ответ пользователя 2026-10-23:** полную метку не переснимать,
`evidence/uploads/baseline/` остаётся. В apply — точечная проба памяти
PUT и `make bench_uploads_quick` (tasks 4.4).
### track2-reconcile-cost
#### Решения
Приняты 2026-10-23 в `/opsx:propose`, подробности — design change
`track2-reconcile-cost`. Пробы — design, Context: временный проект
compose `rccost`, тот же `docker-compose.yml`, образ рабочего стенда
(`7f4e626`), PostgreSQL и S3 на volumes `rccost_*` — удалены по имени.
После пробы volumes, сети и образы — как до неё (155 / 17 / 24). Во время
пробы работали `domains-*`, поэтому задержки шумные, а счётчики точные.
1. **Профиль `reconcile`** (решение 1):
- `make bench_reconcile` — **~50 мин**, `make bench_reconcile_quick` —
**~6 мин**;
- результаты — `evidence/reconcile/<метка>/`;
- этапы: A — 1k × 1 MiB, свежий стенд; B — 10k × 4 KiB, свежий;
C — 30k и D — 100k, тот же набор растёт; S4 — свежий стенд;
- три повтора кругами.
Полная метка — отдельная точка commit после commit гипотез, на тихом
хосте: основная сессия останавливает `domains-*` на ~50 мин.
2. **Набор** (решение 2):
- N = 10k / 30k / 100k объектов по 4 KiB и 1k по 1 MiB;
- расхождения — по 0,25 % на класс (без метаданных, без объекта,
другой размер, зависшая загрузка), класс по номеру объекта;
- grace проходов — 30 с.
Отвергнуты: 10k и 100k без средней точки, 1M, доли 0 % и 10 %,
случайные позиции.
3. **Наполнение мимо API** (решение 3):
- строки — `\copy` через stdin psql стенда;
- объекты — загрузчик `bench/fill_objects.py` в контейнере на образе
стенда, botocore и ключи API, ~1 750 PUT/с, упор в S3.
Проход сверки — разовый уборщик, его результат — его журнал. Это новое
исключение границы чёрного ящика — только у профиля сверки.
4. **Стратегия `--strategy head`** (решение 4): выборка строки на объект
и HEAD на строку, без множества ключей. Только разовый проход;
плановая — `batch`. Проба: ~5,15 мс на объект против 0,30 у `batch`
(~17×).
5. **Глубокая сверка `--deep` — по требованию** (решение 5):
- SHA-256 потоком;
- новый класс `checksum_mismatch`, с `--apply` — пометка потерянного
оригинала;
- «оригинал вернулся» теперь требует того же SHA-256 во всех режимах.
Выборочная глубокая в плановой отвергнута. Проба: предел глубокой на
лимите стенда — CPU уборщика, а не S3 (уточнение гипотезы 3).
6. **Предел скорости `[reconciler] max_objects_per_second`, по умолчанию
2000** (решение 6):
- считаются объекты S3: ключи списка, HEAD, GET, DELETE;
- пауза прерывается сигналом;
- разовый проход принимает `--max-objects-per-second`, `make
reconcile` — `RATE`.
2000/с — ~0,2 ядра S3 на списке. Плановый проход 100k — ~65 с вместо
~30.
7. **S4 — ранний отказ по пределу** (решение 7). Выбран порог
«подтверждено больше предела» с отдельным счётчиком `unchecked` в
итоге. Он действует у любого `--apply`, dry-run перепроверяет всех.
Проба на текущем коде: +5,3 мс на кандидата, +53 с при 10 000
кандидатов. Отвергнуты отказ по числу неподтверждённых кандидатов и
ранний отказ только у плановой сверки. Замер — ячейки S4 на образе
`7f4e626` и на checkout.
8. **Счёт запросов** (решение 8):
- внутренний: счётчики клиента S3 по операциям и байтам, сеансы БД
обёрткой `db_scope` — в итоге прохода;
- внешний — только в метке: метрики шлюза `-metricsPort` на loopback,
только у S3 профиля сверки (override генерирует `run.py`) — и
`pg_stat_database`. Проба: шлюз считает HEAD типом GET, совпало до
запроса.
Отвергнуты `pg_stat_statements` и порт метрик у рабочего стенда.
9. **Фоновая нагрузка и порог H4** (решение 10):
- 300 скачиваний, 50 записей и 50 чтений истории в секунду;
- тихие окна по 30 с до и после прохода;
- порог — медиана `p95(проход) / p95(окна)` ≤ 1,5 у `stand`,
`stand-unlimited`, `fast-limited`;
- контраст: `fast-unlimited` (1 CPU без предела) > 1,5 (проба: ×2,2);
- A/A окон вне [1/1,5; 1,5] — «не различимо».
10. **A/A и сравнение меток** (решение 11): A/A — внутри метки (разброс
повторов, окна до и после). Второй метки и `make bench_compare` нет.
11. **Гипотезы H1–H4 и ожидание S4** (решение 12) уточнены по пробе. Они
идут в `REPORT.md` отдельным commit до метки.
12. **Пять тестов отказов** и аргументы hook (решение 14). Красный прогон
— на `7f4e626`. Остановку во время паузы предела проверяет `driver.py
reconcile-signal --pace` → `evidence/reconcile/service.md`.
#### Вопросы
Нет. Вопрос 1 раздела `### track2-reconciler` (ответ API на потерянный
оригинал) открыт и касается и класса «другой SHA-256». Ответ меняет ту
же ветку `open_content`, а не решения этого change.
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-23
@@ -0,0 +1,863 @@
# Design
## Context
Мотивация — `proposal.md`, раздел Why. Требования — `specs/`.
### Код
Состояние на `7f4e626`:
- **Сверка** (`AttachmentReconcileService.reconcile`, design change
`track2-reconciler`, решения 3, 4, 7, 8) — одна стратегия:
- страницы ListObjectsV2 по 1000 ключей;
- на страницу одно выражение к БД по `id`;
- множество ключей `seen`, затем keyset строк `ready`;
- зависшие загрузки;
- перепроверка каждого кандидата: выборка в БД и HEAD;
- предел, затем действия.
Сверка поверхностная: наличие и размер из списка. Байты не читаются.
SHA-256 оригинала лежит в `attachments.sha256` (32 байта), но его никто
не сверяет. «Оригинал вернулся» сравнивает только размер.
- **Предел изменений** (`_act`): отказ решается после перепроверки всех
кандидатов. Замечание S4 verify `track2-reconciler` — `PLAN.md`, раздел
6.
- **Итог прохода** называет классы, свежие, помеченные и длительность.
Сколько было запросов к S3 и PostgreSQL, не знает никто.
- **Клиент S3** (`ObjectStorage`) счётчиков не ведёт. `open` читает тело
блоками по 64 KiB со сроком на блок.
- **Уборщик**: лимиты рабочего стенда — 0,25 CPU / 256 МБ, пул БД 1,
`pool_pre_ping`. Разовый проход — `docker compose run --rm --no-deps
cleaner reconcile [--apply] [--max-changes N]`.
- **Стенд `bench/`.** S3 запускает только профиль `uploads`. Уборщик
описан в `bench.compose.yml` (интервал сверки 0), но профили его не
запускают. Есть:
- сэмплер `scan` — cgroup всех контейнеров, без сети;
- `resources.py` — окна и агрегаты CPU и памяти;
- сборка образа прежнего commit `build_from` (`git archive`);
- строки k6 на запрос в файл консоли (`k6/failover.js`).
Скрипты на хосте — только stdlib, приложение не импортируется
(`bench.md`).
### Пробы (2026-10-23, scratchpad, проект compose `rccost`)
Стенд пробы:
- тот же `docker-compose.yml` с override без портов и `config.toml`;
- образ рабочего стенда, код `7f4e626`;
- PostgreSQL и S3 на named volumes `rccost_*`, удалены по имени после
пробы;
- у S3 те же аргументы плюс `-metricsPort` — порт метрик шлюза;
- две реплики, LB, уборщик с лимитами рабочего стенда.
Наполнение мимо API:
- строки — `psql \copy … FROM STDIN` из генератора на stdlib;
- объекты — PUT загрузчиком на botocore образа API ключами пользователя
API;
- класс объекта — по `i mod 400`, по 0,25 % на класс.
На хосте всё время пробы работали контейнеры `domains-*`, поэтому
задержки шумные. Счётчики точные. После пробы volumes, сети и образы —
как до неё (155 / 17 / 24).
| Проверка | Результат |
|---|---|
| Наполнение | строки: 10k — 0,25 с, 90k — ~2 с. Объекты 4 KiB: один процесс × 32 потока — 635 PUT/с (S3 0,38 ядра); три процесса × 24 — ~1 750 PUT/с, S3 0,88 ядра — упор в S3 (90k за 52 с). Объекты 1 MiB: 113 PUT/с |
| Batch, dry-run, 0,25 CPU, без фоновой нагрузки | 10k — 3,0 с; 100k — 30,6 / 29,7 / 29,3 с: 0,30 мс на объект при обоих N. Уборщик — 0,24–0,25 ядра (упор в свой лимит CPU), S3 — 0,35–0,43, PostgreSQL — 0,02–0,03. Найдено ровно внесённое (25 и 250 на класс) |
| Память уборщика | ~97 MiB к началу прохода (импорт и модели botocore; старт до прохода — 5–6 с при 0,25 CPU), пик 111,6 MiB на 100k: ~150 Б на ключ множества |
| Метрики шлюза S3 (`SeaweedFS_s3_request_total`) | проход 100k: LIST +101 (100 страниц и проба bucket), GET +750 — HEAD шлюз считает типом GET: 500 × 200 и 250 × 404. Совпало с ожидаемым до запроса |
| PostgreSQL (`pg_stat_database`) | транзакций ≈ 2 × сеансов сверки: `pool_pre_ping` даёт свою |
| «HEAD на строку» (скрипт пробы клиентом и repo проекта в контейнере уборщика, 20k) | выборка строки на объект — 2,67 мс, HEAD на строку — 2,48 мс: ~5,15 мс на объект, в ~17 раз дороже batch. Упор в CPU уборщика (0,62–0,66 мс CPU на вызов) |
| Глубокая (GET и SHA-256, 0,25 CPU) | 4 KiB — 2,5–2,9 мс на объект; 1 MiB — 10,5 мс (95 MiB/с), уборщик 0,25 ядра, S3 0,19 — упор в CPU уборщика, а не в S3 |
| Уборщик 1 CPU | batch 100k — 13,1 с (S3 0,65 ядра: теперь упор в список шлюза); HEAD — 0,69 мс (1 447/с); глубокая 1 MiB — 4,8 мс (208 MiB/с, S3 0,39) |
| CPU S3 на объект | ключ списка — 0,085–0,11 мс; HEAD — 0,25–0,32 мс; GET 4 KiB — ~0,5 мс; GET 1 MiB — 1,9–2,0 мс |
| S4 на текущем коде (100k и ещё 10 000 строк `ready` без объектов) | dry-run — 83,1 с против 29,7 (+53 с, 5,3 мс на кандидата: выборка и HEAD при 0,25 CPU); `--apply` отказал по пределу (10 750 > 100) через 86,1 с, по пути убрав 250 зависших |
| Фоновая нагрузка 50 скачиваний + 50 записей + 50 чтений в секунду | p95 во время batch, HEAD и глубокой (0,25 и 1 CPU) не выше окон без прохода (8 против 10–11 мс) |
| То же, 300 скачиваний/с (реплики ~0,55 ядра, S3 ~0,18, PostgreSQL ~0,14) | окна без прохода — p95 скачиваний 10 и 6 мс. Batch с 1 CPU без предела — 22 мс (×2,2–2,75), запись — 18, чтение — 12. Batch с 0,25 CPU — 9 мс (без эффекта). Ещё одно окно без прохода дало 93 мс — помеха хоста |
### Что проба меняет в гипотезах `PLAN.md`
- **Гипотеза 3.** «Упирается в чтение S3» на лимитах рабочего стенда
неверно: глубокую сверку ограничивает CPU уборщика (0,25). S3 занят на
0,19 ядра.
- **Гипотеза 4.** Эффект зависит от CPU уборщика. Его лимит 0,25 сам
держит нагрузку на S3. Без предела скорости эффект виден, только если у
уборщика больше CPU. Поэтому опыт с 1 CPU — управляемый (решение 10).
Уточнённые гипотезы — решение 12.
## Goals / Non-Goals
**Goals:**
- Пункт трека 2 «измерить стоимость обхода» (`README.md`). Повторяемая
метка с гипотезами, записанными до неё, результатами и ограничениями.
- Стратегии и глубина — настоящие ветки кода с теми же правилами
безопасности, а не прототипы пробы.
- Предел скорости и ранний отказ по пределу (S4) выбраны по замеру и
проверены меткой.
- Счёт запросов сверки сверяется с независимым счётчиком S3.
- Полная метка — не дольше часа: её снимают на тихом хосте, и основная
сессия на это время останавливает чужие контейнеры.
**Non-Goals:**
- Распараллеливание прохода (несколько вызовов S3 одновременно): проход
последовательный, как в `track2-reconciler`. Ускорение не цель, цель —
измерить и ограничить.
- Выборочная глубокая сверка в плановой (решение 5).
- Перенос метрик шлюза S3 в рабочий стенд: порт метрик — только у S3
профиля сверки (решение 8).
- Сравнение меток командой `make bench_compare` (решение 11).
- `REPORT.md` целиком, чистый clone, PR (этап 7 `PLAN.md`).
## Decisions
### 1. Профиль `reconcile`: этапы, ячейки, длительность
Команды: `make bench_reconcile [RECONCILE_LABEL=…]` (метка `baseline` по
умолчанию) и `make bench_reconcile_quick` (метка `quick-reconcile-<время>`,
в `.gitignore`). Результаты — `evidence/reconcile/<метка>/`, рядом с
evidence `track2-reconciler`, как `evidence/uploads/`. Проход сверки —
разовый уборщик в контейнере, «ячейка» — его вариант на одних данных.
Полная метка:
| Этап | Стенд | Набор | Ячейки, по 3 повтора |
|---|---|---|---|
| A | свежий | 1 000 × 1 MiB | `batch`; `deep`; `deep-fast` (уборщик 1 CPU) |
| B | свежий | 10 000 × 4 KiB | `batch`; `head`; `deep` |
| C | тот же, +20 000 | 30 000 × 4 KiB | `batch`; `head` |
| D | тот же, +70 000 | 100 000 × 4 KiB | `batch`; фоновая нагрузка: `stand` (0,25 CPU, предел 2000/с), `stand-unlimited` (0,25 CPU, 0), `fast-unlimited` (1 CPU, 0), `fast-limited` (1 CPU, 2000/с) |
| S4 | свежий | 10 000 чистых × 4 KiB + 1 000, затем ещё 9 000 строк `ready` без объектов | `--apply --max-changes 100`: `before` (образ `7f4e626`) и `after` (checkout), при 1 000 и 10 000 кандидатов |
Порядок и правила:
- Ячейки без фоновой нагрузки — dry-run без предела скорости
(`--max-objects-per-second 0`): там меряется естественная цена.
- Повторы — кругами: в каждом круге ячейки этапа в перестановке от зерна
(`order_seed`), как у `uploads`. План — в `meta.json` до первого
прохода.
- Dry-run ничего не меняет, поэтому повторы идут на одних данных без
перезаливки.
- `--apply` есть только в S4, где проход отказывает по пределу и тоже
ничего не меняет. Зависших загрузок в наборе S4 нет, поэтому отказ не
трогает и их.
Ожидаемая длительность (по пробе, с запасом на старт контейнеров ~6 с на
проход; хост тихий):
| Часть | Время |
|---|---|
| сборка образов checkout и `7f4e626` (кэш слоёв) | ~2 мин |
| A: стенд, 1 GiB объектов, ожидание grace, 9 проходов | ~2,5 мин |
| B: стенд, 10k, 9 проходов (HEAD ~55 с, глубокая ~30 с) | ~6 мин |
| C: +20k, 6 проходов (HEAD ~160 с) | ~10 мин |
| D: +70k, 3 прохода batch и 12 проходов под нагрузкой с окнами по 30 с | ~20 мин |
| S4: стенд, 12 проходов (`before` при 10 000 — ~60 с) | ~6,5 мин |
| **итого** | **~50 мин** (оценка 45–55) |
Быстрый профиль: один свежий стенд, 2 000 × 4 KiB.
- По одному проходу `batch`, `head` и `deep`.
- Четыре варианта под нагрузкой с окнами по 5 с.
- S4 с 300 кандидатами: `before` и `after`.
Итого **~6 мин**, из них ~1–1,5 мин — сборка образа `7f4e626` при
первом запуске.
*Альтернатива:* один свежий стенд на каждое N, как матрица лабы 2.
Отвергнута: 100k пришлось бы наливать трижды (наполнение и ожидание
grace — ~2 мин на этап). Набор только растёт, и классы задаются номером
объекта (решение 2), поэтому этапы B–D сравнимы. *Альтернатива:* HEAD на
100k. Отвергнута: ~515 с на проход, 26 мин на три повтора. HEAD
линеен по построению (вызов на объект), и 10k с 30k это показывают.
*Альтернатива:* глубокая сверка на 100k по 4 KiB. Отвергнута: ~250 с на
проход. Её цена на объект от N не зависит, а цену байтов даёт этап A.
### 2. Набор данных и доли расхождений
- **Размеры.** N = 10 000, 30 000, 100 000 объектов по 4 KiB — одна
кривая от N из трёх точек. Отдельно 1 000 объектов по 1 MiB — цена
байтов у глубокой сверки. Цена списка и HEAD от размера объекта не
зависит, а у чтения два слагаемых: ~2,5 мс на вызов и ~8 мс на MiB при
0,25 CPU (проба). Их и разделяют два размера.
- **Доли.** По 0,25 % от N на класс, 1 % всего: объект без метаданных,
метаданные без объекта, другой размер, зависшая загрузка. Класс — по
`i mod 400` (0, 1, 2, 3), остальные объекты согласованы. Расхождения
разбросаны по всему пространству ключей равномерно, а ожидаемое число
по классам при любом N известно точно.
- **Объект `i`:**
- `id` — UUID v4 из SHA-256 строки `<зерно>:<i>`;
- содержимое — повторённый SHA-256 строки `<зерно>:<i>:c`, обрезанный
до размера;
- `Content-Type: image/png`. Сверка формат не проверяет. Скачивание
API тоже: оно сверяет только размер, и синтетические байты фоновой
нагрузке подходят.
- **Строки:**
- чат и владелец — читаемый чат и пользователь фикстуры `prepare.js`;
- SHA-256 — от того же содержимого;
- `created_at` = `updated_at` = время наполнения минус сутки, то есть
старше grace;
- зависшая загрузка — `pending` с тем же временем.
- **Grace проходов** — `CLEANER__PENDING_GRACE_SECONDS=30`. Это больше
границы живой загрузки (17 с), и проверку при старте он проходит.
Объекты старше grace становятся сами: проходы этапа начинаются через
grace + 2 с после последнего PUT. С grace 900 с каждый этап ждал бы
15 мин.
- **Проверка набора.** Первый dry-run этапа сверяет итог с моделью:
- `listed_objects` равно числу объектов;
- `checked_rows` равно числу строк `ready`;
- `found` по классам равно внесённому.
Каждый следующий проход сверяет `found` так же. Расхождение — отказ
команды с ячейкой, классом и обоими числами (спек `load-benchmark`,
«Найдено не то, что внесено»).
*Альтернатива:* N = 10k и 100k (как в `PLAN.md`). Отвергнута: по двум
точкам линейность не отличить от `a + b·N` с изгибом. *Альтернатива:*
N = 1M. Отвергнута: наполнение ~10 мин, проход ~5 мин при 0,25 CPU,
метка — часы. Предел по памяти выводится из наклона (~150 Б на ключ),
решение 12, H1. *Альтернатива:* доля 0 %. Отвергнута: без кандидатов нет
перепроверок, а проверке набора нечего сравнивать. *Альтернатива:* доля
10 %. Отвергнута: перепроверка (10k × 5,3 мс ≈ 53 с на 100k) перекрыла
бы цену обхода (~30 с). Цену перепроверки отдельно меряет S4.
*Альтернатива:* случайные позиции расхождений. Отвергнута: ожидаемые
числа стали бы оценкой, а не точным значением.
### 3. Наполнение мимо API и граница чёрного ящика
- **Пользователи и чат** — `k6/prepare.js` через LB, как у остальных
профилей.
- **Метаданные** — оркестратор передаёт CSV в `docker exec -i
mtusi-bench-postgres psql … -c "\copy attachments (…) FROM STDIN"`.
Генерирует строки `bench/reconcile.py` (stdlib), файла CSV нет. Новое
исключение границы: до сих пор оркестратор менял в PostgreSQL только
служебное (обслуживание, планы в откатываемой транзакции). Это данные
стенда, схему он не трогает.
- **Объекты** — загрузчик `bench/fill_objects.py`. Он работает только в
контейнере на образе стенда (`mtusi-messenger:bench`), как
`sampler.sh` — только в своём:
- botocore образа, `src` загрузчик не импортирует;
- каталог `bench/` смонтирован только на чтение, генератор набора — из
`reconcile.py`;
- ключи пользователя API передаются окружением `docker run -e <имя>`
без значения в argv;
- три процесса по 24 потока: упор в S3, ~1 750 PUT/с по пробе.
Контейнер называется `mtusi-bench-fill` и входит в список остатков
стенда.
- **Проход сверки** — `docker compose run -d --name
mtusi-bench-reconcile-<n> --no-deps -e CLEANER__PENDING_GRACE_SECONDS=30
cleaner reconcile …`, затем `docker wait`, журнал и `docker rm`.
Результат прохода — его собственные JSON-записи «Started cleaner»,
«Finished reconcile pass» и «Reconcile changes exceed limit»: это выход
приложения, как ответ HTTP для k6. Вариант `before` — тот же вызов с
override `.work/cleaner-before.compose.yml` (`image:
mtusi-messenger:bench-from`). Тег стенда не меняется, и ошибка не
оставит реплики на чужом образе.
- **Измерение мимо приложения** — по образцу статистики LB:
- метрики шлюза S3 — `docker exec mtusi-bench-s3 wget -qO-
http://127.0.0.1:<порт>/metrics` до и после прохода (решение 8);
- `pg_stat_database` — psql до и после прохода;
- cgroup — сэмплер.
- **Расхождения S4** — строки `ready` без объектов. Их пишет оркестратор
тем же `\copy`.
*Альтернатива:* наполнение через API. Отвергнута:
- 100k загрузок — минуты под 4 местами загрузки на реплику;
- расхождения всё равно вносятся мимо API;
- содержимое объектов не управляется.
*Альтернатива:* `weed filer.copy` / HTTP filer изнутри контейнера S3.
Отвергнута: в обход шлюза S3 объекты получили бы не тот путь
метаданных, что у PUT приложения, а файлы пришлось бы сначала создать в
контейнере. *Альтернатива:* загрузчик на хосте. Отвергнута: на хосте —
только stdlib (`bench.md`), подписи SigV4 там нет, а порт S3 стенда на
хост не публикуется.
### 4. Стратегия «HEAD на строку»
`reconcile --strategy head` — только разовый проход. Стратегия по
умолчанию (`batch`) не меняется.
- **S3 → БД.** Те же страницы списка. На каждый ключ — своя выборка
строки: стандартный ключ — по `id`, нестандартный — по `object_key`
(`get_attachments_for_objects` с одним элементом). Здесь
классифицируются только объекты без строки (объект без метаданных,
чужой объект) и свежие объекты. Строку с тем же ключом этот шаг
пропускает: её объект проверит HEAD.
- **БД → S3.** Тот же keyset строк `ready`. На каждую строку своей базы
— HEAD её ключа:
- объекта нет — метаданные без объекта;
- размер другой — другой размер;
- строка помечена, а размер равен — кандидат «оригинал вернулся»;
- иначе — согласовано.
Свежесть — те же правила. Ключ строки вне префикса — чужой объект без
HEAD, как в `batch`.
- **Без множества `seen`:** память O(страницы), а не O(N).
- Зависшие, перепроверка, предел и действия — общие со стратегией
`batch`.
Почему те же расхождения. Каждая пара «объект — строка» классифицируется
теми же правилами. `batch` находит «строку без объекта» как «ключа нет
среди увиденных», `head` — как «HEAD ответил 404». На неизменных данных
итог один и тот же. Это проверяет тест отказов «Стратегия HEAD находит
то же», а метка сверяет `found` на каждом проходе. Если между списком и
HEAD объект удалили, `head` найдёт «метаданные без объекта», а `batch`
не найдёт до следующего прохода. Оба исхода безопасны: перепроверка
общая.
Плановая сверка — всегда `batch`. Стратегия `head` остаётся в коде как
вариант для оператора: проход без памяти на множество, когда N за
пределом памяти уборщика (решение 12, H1 и H2).
*Альтернатива:* только HEAD на строку, без списка. Отвергнута: объекты
без метаданных без списка не найти. *Альтернатива:* стратегия как
настройка `[reconciler] strategy`. Отвергнута: плановой сверке нужен
только `batch`, а лишняя ручка — путь сломать плановую сверку
конфигурацией. *Альтернатива:* удалить `head` после замера. Отвергнута:
это единственный проход с памятью O(1) от N, его цена измерена и
названа в отчёте.
### 5. Глубокая сверка по требованию
`reconcile --deep` — только разовый проход, с любой стратегией.
- **Что читается.** Каждая строка `ready` без пометки, старше grace, у
которой объект того же размера. В `batch` размер известен из страницы
списка, в `head` вместо HEAD сразу идёт GET. Объект читается
`ObjectStorage.open` блоками по 64 KiB со сроком на блок, SHA-256
считается потоком (`hashlib`). Память — один блок.
- **Класс `checksum_mismatch`** («другой SHA-256»). С `--apply` — пометка
потерянного оригинала, как у другого размера. Он входит в классы под
пределом. Перепроверка и проверка перед пометкой заново читают объект
и сравнивают SHA-256. Это дорого только для найденных, а их мало.
- **Снятие пометки.** «Оригинал вернулся» теперь требует того же SHA-256
во всех режимах, не только с `--deep`. Перепроверка и проверка перед
снятием читают объект. Это один-два GET на помеченное вложение с
объектом того же размера — их единицы. Без этого поверхностная сверка
сняла бы пометку, которую поставила глубокая (размер же равен). Кроме
того, оператор мог вернуть не тот файл того же размера, и API отдавал
бы чужие байты.
- **Что видит API.** Скачивание помеченного — 404, метаданные — 200, как
у любого потерянного оригинала (спек `attachments`, «Скачивание
оригинала»). Вопрос преподавателю об ответе на потерянный оригинал
(`PLAN.md`, `### track2-reconciler`, вопрос 1) касается и этого
класса. Ответ «иначе» меняет ту же ветку `open_content`.
- **Плановая сверка глубокой не бывает.** На 100k объектов по 1 MiB
глубокий проход — ~17 мин при 0,25 CPU (~10,5 мс на объект), то есть
CPU уборщика на всё время прохода. Порча внутри SeaweedFS (ошибка CRC
иглы тома) даёт ошибку чтения, а не другие байты. Глубокая сверка
ловит другое: объект перезаписали мимо API байтами того же размера.
*Альтернатива:* выборочная глубокая сверка в плановой (K объектов за
проход). Отвергнута:
- случайная выборка ловит редкий класс с вероятностью K/N за проход;
- детерминированное покрытие требует хранить, что уже проверено, — это
миграция;
- плановая сверка стала бы непредсказуемо дороже.
По требованию оператор запускает её, когда есть причина: после
инцидента или восстановления. *Альтернатива:* ETag S3 вместо чтения.
Отвергнута: ETag шлюза — MD5 того, что шлюз получил. Перезаписанный
объект получает новый ETag, а сравнивать его не с чем: MD5 в метаданных
нет, а его колонка — миграция. *Альтернатива:* сумма SHA-256 от S3
(`x-amz-checksum-sha256`). Отвергнута: поддержку в SeaweedFS 4.48 никто
не проверял, и её пришлось бы передавать при каждой загрузке.
### 6. Предел скорости `[reconciler] max_objects_per_second`
- **Что считается.** Объекты S3, которые проход затронул:
- каждый ключ страницы списка, в том числе проба bucket (`MaxKeys=1`);
- каждый HEAD, GET и DELETE.
Обращения к PostgreSQL не считаются: у сверки они дешёвые, PostgreSQL
за проход — 0,02–0,1 ядра по пробе.
- **Как.** Перед каждым вызовом S3 сверка проверяет сигнал (как
сейчас) и темп. Если затронуто больше, чем `R × (время с начала
прохода)`, она ждёт, пока средняя скорость не опустится до R. Ждёт
кусками по 0,2 с с проверкой сигнала: остановка не ждёт паузы (спек
`graceful-shutdown`). Счёт берётся из счётчиков клиента S3 (решение
8), поэтому DELETE уборки зависших загрузок тоже считаются.
- **Где задаётся.** `[reconciler] max_objects_per_second` — float ≥ 0, по
умолчанию 2000, 0 — без предела. Разовая подмена —
`RECONCILER__MAX_OBJECTS_PER_SECOND`. У разового прохода — ещё
`--max-objects-per-second R`, у `make reconcile` — `RATE=R`. Плановая
сверка берёт значение из настроек.
- **Почему 2000.** CPU шлюза на ключ списка — 0,085–0,11 мс (проба).
2000 ключей в секунду — ~0,2 ядра S3 из 1. Естественная скорость
`batch` на лимите стенда — ~6 000 ключей/с в шаге списка и ~3 400/с в
среднем за проход. Предел удлиняет проход 100k с ~30 с до ~65 с: шаг
списка — не меньше 50 с, шаг строк без S3 — как был. На рабочем стенде
(2–3 тыс. объектов) — ~1,5 с в час. Зато граница
нагрузки на S3 не зависит от того, сколько CPU дали уборщику. Проба
показала: с 1 CPU без предела p95 скачиваний вырос в 2,2 раза. Метка
проверяет это H4 (решение 10).
- **HEAD и глубокая сверка.** Объект у них дороже для S3: HEAD ~0,3 мс,
GET 4 KiB ~0,5 мс, GET 1 MiB ~2 мс CPU шлюза. При 2000/с шлюз
перегрузили бы, но на 0,25 CPU уборщик даёт только ~400 вызовов в
секунду. Предел для них на быстром уборщике — `REPORT.md` по замеру
метки: CPU S3 на объект каждой ячейки.
*Альтернатива:* пауза между страницами (`page_pause_seconds`).
Отвергнута: она не ограничивает HEAD и GET, и у каждой стратегии значила
бы разное. *Альтернатива:* запросов S3 в секунду. Отвергнута: страница
списка — один запрос на 1000 ключей, а HEAD — запрос на объект. Для
`batch` такой предел не ограничивал бы ничего. *Альтернатива:* байтов в
секунду. Отвергнута как единственная ручка: обход без чтения она не
ограничивает. Как вторая ручка — лишняя: глубокая сверка по требованию,
и её темп задаёт тот же аргумент. *Альтернатива:* доля времени S3 (пауза
пропорционально длительности вызова). Отвергнута: длительность вызова
включает разбор XML в самом уборщике, а время прохода по такой ручке
заранее не посчитать. *Альтернатива:* только лимит CPU контейнера.
Отвергнута: он неявный, меняется вместе с лимитом и не виден в
настройках сверки. Опыт `fast-unlimited` показывает, что будет без
предела.
### 7. Отказ по пределу без лишних перепроверок (S4)
Выбран вариант «порог „подтверждено больше предела“ и отдельный счётчик
в итоге» из `PLAN.md`, раздел 6. Он действует у любого `--apply`, не
только у плановой сверки.
- В `_recheck_all` при `apply` сверка считает подтверждённых классов под
пределом (`LIMITED_KINDS` и `checksum_mismatch`). Как только их больше
`max_changes`, она прекращает перепроверять кандидатов этих классов, а
каждого оставшегося считает в `unchecked`. Зависшие загрузки и чужие
объекты перепроверки не требуют и проходят как раньше.
- `_act` отказывает по тому же условию. Запись `error` «Reconcile
changes exceed limit» называет `changes` = `max_changes + 1`,
`max_changes` и `unchecked`. Итог — `unchecked`, код 3. Уборка
зависших — как раньше.
- Dry-run перепроверяет всех и называет каждое расхождение. После
отказа оператор запускает dry-run (`docker.md`: «сначала `make
reconcile`»).
Почему так. Отказ решён, как только подтверждённых `max_changes + 1`:
остальные кандидаты исход не меняют, и их перепроверка — только цена.
Проба: +5,3 мс на кандидата при 0,25 CPU. При 10 000 кандидатов — +53 с
к проходу. В сценарии, ради которого предел есть, — пустая база при
живом bucket, 100k объектов — это ~9 мин каждой плановой сверки, и всё
это время уборка зависших ждёт. После правки — `max_changes + 1`
перепроверок, ~0,5 с. Отказ при этом обоснован всегда: подтверждено
больше предела, а не «кандидатов много».
Цена — два инварианта ослаблены только для отказавшего `--apply`:
- ошибка называет нижнюю границу числа изменений;
- неперепроверенные кандидаты не названы поимённо, только числом.
Спек `storage-consistency` уточнён в обоих местах.
*Альтернатива:* решать отказ по числу кандидатов до перепроверки
(вариант «перепроверка после решения о пределе»). Отвергнута: кандидаты
не подтверждены. Гонка с загрузками или неполный список дали бы
ложный отказ, и сверка не исправила бы и то, что исправить можно.
*Альтернатива:* ранний отказ только у плановой сверки. Отвергнута: один
и тот же `--apply` вёл бы себя по-разному. Разовый `--apply` платил бы
полную цену, хотя полный отчёт у оператора и так есть — dry-run.
*Альтернатива:* оставить как есть. Отвергнута по замеру выше.
Замер — ячейки S4 (решение 1): `before` на образе `7f4e626`
(`Profile.reconcile_before`, `git archive`, проверка commit до стенда,
как у `uploads_before`) и `after`, оба `--apply --max-changes 100`, у
`after` — `--max-objects-per-second 0`. У прежнего кода предела скорости
нет, и сравнение должно быть честным.
### 8. Счёт запросов S3 и PostgreSQL
- **Внутренний счёт — в итоге прохода.**
- `ObjectStorage` ведёт счётчики попыток вызовов по операциям (`list`,
`head`, `get`, `delete`, `put`), ключей страниц списка и прочитанных
байтов. `stats()` отдаёт неизменяемый снимок.
- Сверка берёт снимки в начале и в конце прохода. Счёт на стороне
клиента ловит и DELETE уборки зависших, и пробу bucket.
- Сеансы PostgreSQL сверка считает обёрткой своего `db_scope`. Ту же
обёртку получает её `AttachmentCleanupService`: шаги уборки входят в
счёт.
- Итог прохода называет `s3_requests` по операциям, `storage_objects`
(затронутые объекты S3 — решение 6), `read_bytes`, `db_sessions` и
`phase_ms` — длительность шагов `list`, `rows`, `stale`, `recheck`,
`act`.
- **Внешний счёт в метке.**
- S3: `SeaweedFS_s3_request_total` по типам до и после прохода.
`-metricsPort` слушает `-metricsIp`, а по умолчанию это `-ip.bind`,
то есть `127.0.0.1`. Проба: порт 9327 слушает только loopback, из
сети стенда недоступен.
- Флаг есть только у S3 профиля сверки. Override
`.work/s3-metrics.compose.yml` генерирует `run.py`: берёт `command`
сервиса `s3` из `docker compose config` того же стенда и дописывает
флаг. Списка аргументов в двух местах нет, расхождения с рабочим
стендом тоже. Аргументы — в паспорте.
- Шлюз считает HEAD типом GET. Поэтому сверка счётчиков — `LIST =
list`, `GET = head + get`, `DELETE = delete`.
- В ячейках без фоновой нагрузки равенство обязательно. Иначе —
пометка `count_mismatch`: строка остаётся, а вывод H1–H2 называет
пометку.
- PostgreSQL: `pg_stat_database` (транзакции, `tup_returned`,
`tup_fetched`, `blks_hit`, `blks_read`) до и после прохода.
Равенства с сеансами нет: `pool_pre_ping` даёт свою транзакцию, а
проверки LB `SELECT 1` раз в секунду. Это справочный счёт рядом с
CPU PostgreSQL.
*Альтернатива:* только внутренний счёт. Отвергнута: гипотеза 2 — о
числе запросов, и её подтверждение не должно держаться на самоотчёте
испытуемого. *Альтернатива:* только внешний. Отвергнута: в ячейках с
фоновой нагрузкой метрики смешивают API и сверку. Оператору нужна цена
прохода и на рабочем стенде, где порта метрик нет. *Альтернатива:*
`pg_stat_statements`. Отвергнута:
- нужен `shared_preload_libraries` и `CREATE EXTENSION` в базе стенда —
это смена настроек PostgreSQL для всех профилей и объект в схеме,
видимый приложению;
- выражения `get_attachment` у API и сверки одинаковые.
*Альтернатива:* журнал аудита шлюза. Отвергнута: SeaweedFS пишет его во
fluentd, а это ещё один сервис. *Альтернатива:* порт метрик и у рабочего
стенда. Отложена: это изменение S3 рабочего стенда ради замера, хотя
`make s3_check` порт на loopback и принял бы. Место ему — лаба 6, сбор
метрик.
### 9. Ресурсы прохода
- Сэмплер `scan` (`sampler.sh`) работает весь этап с интервалом 0,5 с
(`Profile.reconcile_sample_interval_s`). Проход 10k длится ~3 с, и
интервала в 1 с мало.
- **Окно прохода** — по часам ВМ: `[t_end − duration_ms, t_end]`, где
`t_end` — время записи «Finished reconcile pass».
- **CPU за окно.** S3, PostgreSQL, реплик, LB и уборщика — агрегаты
`resources.py` по окну. Уборщик — по полному `id` контейнера прохода:
роль `cleaner` по метке сервиса compose.
- **Память уборщика.** В начале прохода — выборка у начала окна, пик —
наибольшая выборка за жизнь контейнера. Прирост — их разность: это
множество ключей и кандидаты.
*Альтернатива:* `memory.peak` cgroup и сэмплер `peak` (как у `uploads`).
Отвергнута: cgroup разового контейнера исчезает с его выходом, и
прочитать пик после прохода нельзя, а выборки раз в 0,5 с проход
длиной в секунды хватает. *Альтернатива:* `ru_maxrss` процесса в итоге
прохода. Отвергнута: у долгоживущего сервиса это пик за всю жизнь, а не
за проход. Внешний замер тоже не должен держаться на самоотчёте.
### 10. Фоновая нагрузка и порог H4
- **Сценарий** `bench/k6/background.js`, открытая модель, три сценария
`constant-arrival-rate`:
- скачивания — 300/с. Вложения — выборка 5 000 согласованных объектов
набора от зерна, `.work/downloads.json` от `run.py`. Скачивает
читатель фикстуры: он владелец и участник чата набора;
- запись сообщений — 50/с, в чат записи;
- чтение первой страницы истории чата записи — 50/с.
Строка на запрос — `bg,<d|w|r>,<отправка мс>,<длительность мс>,<статус>`
в файл консоли k6, как `fo,…` у `failover`. Число строк сверяется с
итерациями из итога k6. Нагрузка по пробе: реплики ~0,55 ядра каждая
(около половины потолка, как у `failover`), S3 ~0,18, PostgreSQL ~0,14.
Загрузок в фоне нет: они меняли бы набор во время проходов.
- **Окна.** Один запуск k6 на весь блок H4 этапа D. Перед первым
проходом и после каждого — 30 с без прохода. Окно «до» прохода i —
тихое окно перед стартом его контейнера, окно «после» — тихое окно
после выхода. Старт контейнера (импорт, ~5 с) в окна не входит: S3 и
API он не трогает.
- **Мера.** По каждому сценарию и окну — p50, p95, p99, число ответов и
ошибок. Влияние прохода — `r = p95(окно прохода) / p95(окна до и после
вместе)`. Шум — `a = p95(до) / p95(после)` (A/A).
- **Предел скорости в вариантах:** `stand` и `fast-limited` — 2000/с
(по умолчанию), `stand-unlimited` и `fast-unlimited` — 0.
- **Порог — до метки, в commit гипотез:**
- **держится:** медиана `r` по трём повторам ≤ 1,5 для каждого из трёх
сценариев. Это у вариантов `stand`, `stand-unlimited` и
`fast-limited`;
- **контраст:** у `fast-unlimited` медиана `r` скачиваний > 1,5. Иначе
метод эффекта не видит, и H4 — «не проверена», а не «подтверждена»;
- **шум:** медиана `a` по сценарию вне [1/1,5; 1,5] — вывод «не
различимо на этом хосте»;
- ответы 5xx фоновой нагрузки — пометка прохода, при них H4 не
подтверждается.
- Дополнительно, без вердикта, — p95 окна шага списка (`phase_ms.list`
от начала прохода). В этом шаге у `batch` нагружен S3.
*Альтернатива:* фон 50 + 50 + 50/с. Отвергнута: проба не увидела эффекта
даже у HEAD и глубокой с 1 CPU. В окнах прохода p95 был даже ниже, чем
без него, и порог мерил бы шум. *Альтернатива:* поиск интенсивности
до насыщения S3 (как R* трека 1). Отвергнута: минуты на каждый этап и
другой вопрос — ёмкость, а не влияние прохода. *Альтернатива:*
абсолютный порог (+20 мс). Отвергнута: при p95 ~10 мс даже двукратный
рост (22 мс в пробе) остался бы под порогом. *Альтернатива:* H4 с HEAD и
глубокой. Отвергнута для метки: это разовые операции оператора, а их
цену для S3 дают ячейки без нагрузки (CPU S3 на объект, решение 6).
Глубокий проход 100k идёт ~250 с, три повтора — ещё 13 мин.
### 11. A/A и сравнение меток
- Все сравнения — внутри одной метки, на одних данных, в одной сессии
хоста (`bench.md`: «Варианты сравниваются внутри одной метки»):
стратегии, глубина, CPU уборщика, предел, `before` / `after`.
- Шум ячеек без нагрузки — разброс трёх повторов. Отличие засчитывается,
только если разбросы не пересекаются (правило `bench_compare`).
Ожидаемые отличия — в разы (17× у HEAD), а разброс повторов batch по
пробе — 3 %.
- Шум H4 — A/A окон до и после (решение 10).
- **Второй метки A/A нет.** Она удвоила бы время тихого хоста (~50 мин)
и сравнивала бы разные сессии хоста — это хуже, чем окна внутри одной.
- **`make bench_compare` метки сверки не сравнивает.** Он читает
`evidence/bench/`, а метки сверки лежат в `evidence/reconcile/`:
команда отказывает с «not found» и кодом 2. Методики разные, и так и
должно быть. Быстрая метка с полной не сравнивается — у них разные N.
*Альтернатива:* отдельная метка `reconcile-aa`. Отвергнута выше.
*Альтернатива:* научить `compare.py` меткам сверки. Отвергнута: «до» и
«после» здесь одна метка (ячейки S4), а других сравнений change не
требует.
### 12. Гипотезы (текст для commit гипотез)
Числа — из проб (Context), а не из метки. Вывод по метке пишется после
неё. Если он расходится с гипотезой, гипотеза названа опровергнутой.
- **H1 — линейность (`batch`, dry-run, 0,25 CPU, без предела):**
- цена на объект (`duration_ms / N`) при 10k, 30k и 100k различается
не больше чем на 20 % (проба: 0,30 мс при 10k и 100k);
- S3: ⌈N / 1000⌉ страниц списка, одна проба bucket и HEAD только у
кандидатов (0,75 % N в наборе метки);
- сеансов PostgreSQL — по одному на страницу списка, на страницу строк
`ready` и на выборку зависших, плюс по одному на кандидата, кроме
зависших;
- прирост памяти уборщика за проход — не больше 300 Б на ключ (проба:
~150). Отсюда предел `batch` при 256 МБ — порядка миллиона ключей.
- **H2 — `batch` против HEAD на строку (10k и 30k):**
- на обход `batch` делает ≈ 3 запроса на 1000 объектов (страница
списка, выборка страницы, страница строк), HEAD — ≈ 2 на объект
(выборка на объект и HEAD на строку). Перепроверка кандидатов у
стратегий общая. С ней при 1 % расхождений — ~18 против ~2 000
запросов к S3 и PostgreSQL на 1000 объектов;
- время на объект у HEAD больше в 10 раз и более (проба: ~17×);
- память HEAD-прохода от N не растёт: прирост ≤ 5 MiB при 10k и 30k.
- **H3 — поверхностная против глубокой:**
- глубокая на 4 KiB дороже `batch` по времени на объект не меньше чем
в 5 раз (проба: ~9×), с GET на каждую строку;
- на 1 MiB время на объект больше, чем на 4 KiB, на 5 мс и более на
MiB (проба: ~8 мс при 0,25 CPU);
- на лимите стенда предел глубокой — CPU уборщика (≥ 90 % лимита), а
не S3 (≤ 50 % ядра);
- с 1 CPU у уборщика она быстрее не меньше чем в 1,5 раза.
Вывод, который проверяется: глубокая — по требованию, не в плановой.
- **H4 — влияние на фоновую нагрузку (100k, `batch`)** — порог решения
10: `stand`, `stand-unlimited` и `fast-limited` — медиана `r` ≤ 1,5 по
всем трём сценариям; `fast-unlimited` — `r` скачиваний > 1,5 (проба:
2,2–2,75).
- **S4 — цена отказа по пределу (ожидание, не гипотеза трека).** Проход
без кандидатов — ячейка `batch` этапа B, тот же N = 10k:
- `before` длиннее него примерно на D × 5 мс: +5 с при 1 000 и +50 с
при 10 000;
- `after` — не больше чем на 1 с, запросов HEAD — не больше
`max_changes + 1`;
- отказ, код 3 и неизменность данных — у обоих.
Гипотеза 5 («ничего подтверждённого не удалено») закрыта стрессом
`track2-reconciler` (`evidence/reconcile/stress.md`). Новые ветки
покрывают тесты отказов (решение 14).
### 13. Файлы метки, сводка, графики
- `meta.json`:
- профиль целиком (поля `reconcile_*`), план, образы, `before_commit`;
- аргументы S3 и порт метрик;
- лимиты контейнеров;
- модель набора по этапам: N, размеры, доли, зерно;
- фоновая нагрузка;
- `host_state`, `other_containers`, `docker.kernel`.
- `passes.csv` — строка на проход:
- этап, ячейка, вариант, повтор, стратегия, глубина, CPU уборщика,
предел;
- N объектов и строк, внесено и найдено по классам;
- длительность и шаги, цена на объект;
- запросы S3 сверки и по метрикам, сеансы и счётчики PostgreSQL,
байты, `unchecked`;
- CPU уборщика, S3, PostgreSQL, реплик и LB за окно, память уборщика;
- код выхода и пометки.
Новые столбцы — только в конец (`bench.md`).
- `windows.csv` — строка на проход × окно × сценарий: границы, ответы,
ошибки, p50, p95, p99.
- `summary.md`:
- паспорт;
- таблицы по этапам (медиана и min–max ячейки);
- S4 до и после;
- строки H1–H4 и S4 с числами и вердиктом.
- SVG — `plots.Svg` из `bench/plots.py`, stdlib:
- `cost-by-n.svg` — время прохода от N у `batch` и `head`, точки
глубокой;
- `requests-by-n.svg` — запросы S3 и сеансы PostgreSQL от N,
логарифмическая шкала;
- `background-p95.svg` — `r` по вариантам и сценариям с линией порога
и полосой A/A.
- `raw/<проход>-cleaner.json` — записи «Started», «Finished» и
«exceed limit». Записи «Found» — только числом, их до тысячи на проход.
- `raw/h4-k6.json` — итог k6 блока H4.
- Разбор и сводка — `bench/reconcile.py` без docker, `--selftest` на
синтетических журналах, метриках и строках k6, как у `uploads.py`.
`make bench_plots` не меняется: он строит графики серий трека 1 по
нескольким меткам.
### 14. Тесты отказов и evidence
**Hook** (`fault_hook.py`): `reconcile dry-run|apply [<предел>]
[--strategy head] [--deep] [--max-objects-per-second R]`. Аргументы
проверяются по списку и передаются команде как есть. Тело `put-object`
— любые байты, в том числе того же размера. Новых действий нет.
**Тесты** (маркер `fault`, G = 20 с — grace стенда отказов):
| Тест | Сценарии `storage-consistency` | Ход |
|---|---|---|
| `test_reconcile_head_strategy_same_findings` | «Стратегия HEAD находит то же» | расхождения как в `…_finds_and_fixes` → ждать G + 1 → dry-run `batch` и `head`: свои находки по классам и ключам равны, коды равны, у `head` `s3_requests.head` и `db_sessions` больше |
| `test_reconcile_deep_checksum` | «Другой SHA-256 находит глубокая сверка» | A в сообщении → `put-object` A другими байтами того же размера, `age-row` → ждать G + 1 → dry-run: A нет; `--deep`: A — `checksum_mismatch`, `read_bytes` > 0, код 3, `lost-ids` прежние → `--deep --apply`: A помечено, байты — 404, метаданные — 200 |
| `test_reconcile_restore_needs_same_bytes` | «Вернулся другой объект того же размера», «Оригинал вернулся» | R помечено (`age-row`, `delete-object`, apply) → `put-object` других байтов того же размера → ждать G + 1 → apply: R в `lost-ids`, 404 → `put-object` исходных байтов → ждать G + 1 → apply: пометки нет, 200 с тем же SHA-256 |
| `test_reconcile_rate_limit` | «Скорость прохода ограничена», «Без ограничения скорости» | dry-run с R = max(5, ⌈объектов / 4⌉) и с 0: при R `duration_ms` ≥ 1000 × `storage_objects` / R × 0,95, без предела проход короче; находки и код одинаковы |
| `test_reconcile_limit_stops_rechecks` | «Отказ по пределу без лишних перепроверок» | 6 вложений: `age-row`, `delete-object` → apply с пределом 2: код 3, `changes` = 3, `unchecked` ≥ 3, ни одно не помечено → dry-run: все 6 названы → apply 100: все помечены |
`test_reconcile_change_limit` не меняется: при L1–L3 и пределе 2 на
третьем подтверждённом `changes` = 3, как он и ждёт (`≥ 3`).
**Красный прогон до кода** на `7f4e626`: новые аргументы — ошибка
argparse (код 2), `test_reconcile_restore_needs_same_bytes` — пометка
снята по размеру. Падают все пять. Это доказательство, что тесты
проверяют новое поведение (`evidence/tests/failure-checks.md`).
**Сверка покрытия.** Новые сценарии `storage-consistency`
синхронизируются в основные спеки в apply, как в прежних changes:
`spec_coverage.py` читает только `openspec/specs/`. Purpose спека
`storage-consistency` правится руками: «стоимость обхода описывает
change» → описано в нём.
**Evidence:**
- `evidence/reconcile/service.md`, новый раздел «Остановка во время
паузы предела скорости». `driver.py reconcile-signal --pace`: тот же
драйвер, вместо `pause s3` — `--max-objects-per-second 1`, `docker
stop` через 2 с после «Started cleaner». Ожидание: код 1,
`interrupted_by: stop`, остановка ≤ 1 с после сигнала. Спек
`graceful-shutdown` в сверку покрытия не входит.
- `evidence/tests/` — полный `make failure_checks` и красный прогон,
`make test_isolated`.
- Метка `evidence/reconcile/baseline/`.
### 15. Журнал и настройки
- «Started cleaner»: `reconcile_max_objects_per_second`. У разового
прохода — ещё `reconcile_strategy` и `reconcile_deep`.
- «Finished reconcile pass» — поля решения 8 и `strategy`, `deep`,
`max_objects_per_second`, `unchecked`. Ключи `s3_requests` и
`phase_ms` — постоянные строки, значения — числа. SHA-256 объектов в
записях нет (дельта `service-logging`).
- «Reconcile changes exceed limit»: плюс `unchecked`.
- `ReconcileFinding.CHECKSUM_MISMATCH = "checksum_mismatch"`;
`ReconcileStrategy` (`batch`, `head`) — `StrEnum` в
`enums/attachment.py`.
- `ReconcilePassDTO` — новые поля в конце со значениями по умолчанию,
отображения — `MappingProxyType` (`dto.md`).
- `config_example.toml` — строка `max_objects_per_second`. Правило
`settings.md` — поле и обоснование 2000.
- `make reconcile [APPLY=1] [MAX_CHANGES=N] [STRATEGY=head] [DEEP=1]
[RATE=R]`.
### 16. Точки commit в apply
Как во всех changes лабы. Commit делает основная сессия после
подтверждения (`bench.md`, «Измеренное состояние — commit»):
1. **Код:** тесты и hook, красный прогон, сверка, клиент, настройки,
CLI, стенд `bench/` (профили, загрузчик, сценарий k6, разбор,
`--selftest`), `make bench_reconcile_quick` на дереве, правила и
AGENTS.md, синхронизация спеков, полный `make failure_checks`, `make
lint`.
2. **Гипотезы:** раздел `REPORT.md` с H1–H4 и ожиданием S4 (решение 12)
и методикой — отдельным commit раньше метки. Спек `load-benchmark`,
«Гипотезы сверки до прогонов».
3. **Метка:** `make bench_reconcile` с закоммиченного кода, на тихом
хосте: основная сессия останавливает `domains-*` на ~50 мин, затем
поднимает. Каталог метки — отдельным commit.
4. **Evidence и отчёт:**
- `evidence/reconcile/service.md` (пауза предела);
- `evidence/tests/`;
- выводы по метке и ограничения в `REPORT.md`, строки таблицы
доказательств;
- `PLAN.md`.
## Risks / Trade-offs
- **[Предел 2000/с удлиняет плановый проход вдвое]** → на 100k с ~30 до
~65 с, на рабочем стенде — ~1,5 с в час. Уборка зависших ждёт прохода,
grace — 900 с. Метка проверяет, нужен ли предел на лимитах стенда
(`stand-unlimited`). Если нет, `REPORT.md` скажет, что он страхует
быстрый уборщик.
- **[Порог H4 против шума задержек хоста]** → в пробе на шумном хосте
тихие окна различались в 1,67 раза, и одно дало 93 мс. Метка
снимается на тихом хосте, решает медиана трёх повторов. A/A окон до и
после каждого прохода делает вывод «не различимо», если шум больше
порога. Контраст `fast-unlimited` проверяет, что метод эффект видит.
- **[Подмена гипотез пробой]** → гипотезы уточнены по пробе на шумном
хосте до метки (как в `upload-memory`). Метка — проверка на тихом
хосте. Расхождение с ней пишется опровержением, а не правкой
гипотезы.
- **[Счёт сверки — самоотчёт испытуемого]** → в ячейках без нагрузки он
сверяется с метриками шлюза (решение 8). Проба: совпало до запроса.
- **[Порт метрик S3 только в профиле сверки]** → это отличие аргументов
S3 от рабочего стенда. Оно в спеке `load-benchmark` и в паспорте, как
`auto_explain` у PostgreSQL. На путь запросов метрики не влияют.
- **[Проход `head` и глубокий занимают CPU уборщика на минуты]** → это
разовые операции оператора. Время на объект в метке и рекомендация
предела — в `REPORT.md`. Уборщик стенда (сервис) на время разового
прохода не останавливается: это другой контейнер.
- **[Синтетические объекты]** → 4 KiB и 1 MiB вместо настоящих PNG. Цена
списка и HEAD от размера не зависит, а у глубокой — два слагаемых по
двум размерам. Ограничение — в `REPORT.md`.
- **[Глубокая сверка помечает «чужие байты» потерянными]** → скачивание
становится 404 вместо отдачи не тех байтов. Если это законная замена
оператором, оператор возвращает исходные байты, и пометка снимается.
Вопрос преподавателю об ответе на потерянный оригинал касается и этого
класса.
- **[Снятие пометки читает объект]** → один-два GET на помеченное
вложение с объектом того же размера в каждом проходе. Таких единицы.
- **[Ранний отказ называет нижнюю границу изменений]** → ошибка
называет `changes` = предел + 1 и `unchecked`. Точное число даёт
dry-run, и порядок действий оператора не меняется.
- **[Наполнение мимо API пишет в данные стенда]** → новое исключение
границы чёрного ящика, только у профиля сверки, только на свежем
стенде `mtusi-bench`. Схему оно не меняет. Описано в `bench.md` и в
спеке.
- **[Метка ~50 мин требует тихого хоста]** → основная сессия
останавливает `domains-*` и поднимает после. Быстрый профиль (~6 мин)
проверяет стенд и на шумном хосте. Выводы опираются на точные счётчики,
байты, время и p95 метки на тихом хосте.
## Migration Plan
1. Тесты отказов и hook — раньше кода. Красный прогон на `7f4e626`.
2. Enum, DTO, настройка `max_objects_per_second`, счётчики клиента S3.
3. Сервис сверки: темп, ранний отказ, глубокая, `head`, стоимость в
итоге. CLI уборщика, `make reconcile`, `config_example.toml`.
4. Синхронизация дельт в основные спеки, Purpose `storage-consistency`.
Полный `make failure_checks`.
5. Стенд `bench/`: override уборщика, `reconcile.py` с `--selftest`,
`fill_objects.py`, `k6/background.js`, профили в `run.py`, цели
`Makefile`, `.gitignore`. `make bench_reconcile_quick` на дереве и
регресс быстрых профилей.
6. Драйвер `reconcile-signal --pace`, правила, AGENTS.md, `PLAN.md`.
7. Commit кода, затем commit гипотез, метка, commit метки, evidence и
отчёт (решение 16).
Рабочий стенд: новый код уборщика — `docker compose up -d --no-deps
cleaner` или `make run_docker`, решает основная сессия. Миграции нет. Новый
уборщик с прежними репликами совместим: пометку `checksum_mismatch`
прежние реплики читают как любой `lost_at` — 404. Прежний уборщик с новыми
репликами — как до change.
Откат — прежний образ уборщика. Пометки остаются в `lost_at`.
## Open Questions
Нет. Вопрос преподавателю об ответе на потерянный оригинал (`PLAN.md`,
`### track2-reconciler`, вопрос 1) открыт и касается класса «другой
SHA-256». Ответ меняет ту же ветку `open_content`, а не этот change.
@@ -0,0 +1,127 @@
# Proposal
## Why
Уровень «5», трек 2 «Согласованность двух хранилищ» (`README.md`)
требует ещё и «гипотезу, повторяемую методику, результаты и ограничения;
измерить стоимость обхода». Сверка bucket и БД уже есть (change
`track2-reconciler`): одна стратегия, поверхностная проверка, без
ограничения скорости. Сколько она стоит при росте числа объектов и
мешает ли рабочему трафику — пока не измерено. Гипотезы 1–4 трека
(`PLAN.md`, «Трек 5») не проверены.
Verify `track2-reconciler` передал сюда замечание S4. При массовом
расхождении `--apply` перепроверяет каждого кандидата и только потом
отказывает по пределу. Проба этого change: 10 000 лишних кандидатов
добавляют к проходу ~53 с, всё это время уборка зависших загрузок ждёт.
## What Changes
- **Стратегия «HEAD на строку»** — `reconcile --strategy head`, только
разовый проход. Для каждого объекта списка — своя выборка строки, для
каждой строки `ready` — HEAD её объекта, без множества ключей в памяти.
Расхождения и правила безопасности те же, что у стратегии по умолчанию
(страница списка и одно выражение к БД на страницу). Плановая сверка
остаётся на стратегии по умолчанию.
- **Глубокая сверка по требованию** — `reconcile --deep`. Сверка читает
объект и сравнивает его SHA-256 с метаданными. Новый класс «другой
SHA-256»: с `--apply` такой оригинал помечается потерянным, как при
другом размере. Плановая сверка глубокой не бывает. Пометку
«оригинал вернулся» сверка снимает, только если у объекта и тот же
размер, и тот же SHA-256. Раньше хватало размера.
- **Ограничение скорости** — `[reconciler] max_objects_per_second`. По
умолчанию 2000, 0 — без ограничения. Это предел того, сколько объектов
S3 проход затрагивает в секунду: ключи страниц списка, HEAD, GET и
DELETE. Разовый проход принимает предел аргументом. Пауза ограничения
прерывается сигналом остановки.
- **Отказ по пределу без лишних перепроверок (S4).** С `--apply` сверка
перестаёт перепроверять кандидатов классов под пределом, как только
подтверждённых больше `max_changes`. Отказ к этому моменту уже решён.
Итог называет, сколько кандидатов не перепроверено. Dry-run по-прежнему
перепроверяет и называет каждое расхождение.
- **Итог прохода называет стоимость:**
- стратегию, глубину и предел скорости;
- запросы S3 по операциям и прочитанные байты — по счётчикам клиента
S3;
- сеансы с PostgreSQL;
- длительность по шагам прохода.
- **Профиль `reconcile` стенда `bench/`** — `make bench_reconcile`
(~50 мин) и `make bench_reconcile_quick` (~6 мин), результаты — в
`evidence/reconcile/<метка>/`. Что в нём:
- наполнение мимо API: метаданные — запись в PostgreSQL стенда,
объекты — прямой PUT в S3 стенда;
- N = 10k / 30k / 100k объектов по 4 KiB и 1k объектов по 1 MiB,
расхождения — по 0,25 % каждого класса;
- стратегии, глубина, лимит CPU уборщика и предел скорости;
- фоновая нагрузка k6 с заранее заданным порогом p95;
- цена отказа по пределу на образе до change и после;
- три повтора, A/A внутри метки;
- счётчики запросов сверки сверяются с метриками шлюза S3;
- сэмплер, сводка с выводами по гипотезам 1–4 и графики.
- **Тесты отказов**: те же расхождения у стратегии HEAD, другой SHA-256,
возврат объекта с другим содержимым, предел скорости, отказ по пределу
без лишних перепроверок. Hook передаёт сверке новые аргументы.
- **Отчёт:** гипотезы — отдельным commit до метки, выводы и ограничения
— после неё. Строки таблицы доказательств уровня «5».
Не входит:
- сводка всего отчёта, чистый clone и PR (этап 7 `PLAN.md`);
- остальные записи `KNOWN_ISSUES.md`;
- выборочная глубокая сверка в плановой (отвергнута, design);
- presigned upload, превью и 202 (лаба 5).
Гипотезу 5 («ничего подтверждённого не удалено») закрыл стресс change
`track2-reconciler`. Новые ветки сверки покрывают тесты отказов этого
change.
## Capabilities
### New Capabilities
Нет.
### Modified Capabilities
- `storage-consistency`: стратегия HEAD, глубокая сверка и класс «другой
SHA-256», ограничение скорости, отказ по пределу без лишних
перепроверок, снятие пометки только при том же SHA-256, плановая
сверка — стратегия по умолчанию, поверхностная, с пределом скорости
из настроек.
- `service-configuration`: `[reconciler] max_objects_per_second`.
- `service-logging`: стоимость прохода в итоге сверки, новые поля
записей о старте и о пределе изменений.
- `graceful-shutdown`: остановка уборщика во время паузы ограничения
скорости.
- `student-tests`: hook запускает сверку со стратегией, глубиной и
пределом скорости.
- `load-benchmark`: профиль сверки, S3 и уборщик в его стенде, стоимость
сверки в отчёте.
## Impact
- Код:
- `src/core/services/attachment_reconcile.py` — стратегия HEAD,
глубокая сверка, темп, ранний отказ по пределу, стоимость в итоге;
- `src/infra/s3/client.py` — счётчики вызовов по операциям, ключей
списка и прочитанных байт;
- `src/cleaner/main.py` — аргументы `--strategy`, `--deep`,
`--max-objects-per-second`;
- `src/config/settings.py` — поле `max_objects_per_second`;
- DTO и enum.
Миграции нет: SHA-256 и `lost_at` уже в схеме.
- Стенд `bench/`:
- `run.py` — профили `reconcile` и `reconcile_quick`;
- новые `reconcile.py` (разбор, сводка, графики, `--selftest`),
`fill_objects.py` (загрузчик объектов в контейнере на образе
приложения) и `k6/background.js`;
- `bench.compose.yml` — лимиты уборщика без swap.
- Прочее: `Makefile` (`bench_reconcile`, `bench_reconcile_quick`,
аргументы `make reconcile`), `config_example.toml`, `.gitignore`.
- Тесты: `student-tests/test_failures.py`, `fault_hook.py`.
- Документы: скилл `run-mtusi-messenger` (`reconcile-signal --pace`).
Правила `bench.md`, `service-layer.md`, `infra.md`, `settings.md`,
`logging.md`, `run-modes.md`, `student-tests.md`, `dto.md`. Ещё
AGENTS.md, `REPORT.md` и `PLAN.md`.
- Регресс: `make failure_checks` дольше на ~1–2 мин. Быстрые профили
`bench/` и `make test_isolated` — без изменений.
@@ -0,0 +1,46 @@
## MODIFIED Requirements
### Requirement: Остановка уборщика
По SIGTERM уборщик незавершённых загрузок (capability
`storage-consistency`) SHALL довести текущий шаг уборки загрузки до
конца или до отката и больше новых шагов не начинать. Загрузка,
остановленная между шагами, остаётся в состоянии, из которого её
доводит следующий проход.
Так же — во время сверки bucket и БД. Текущий вызов S3 или шаг с
PostgreSQL доводится до конца или до отката. Новые страницы списка и
новые действия не начинаются. Ожидание из-за предела скорости сверки
(capability `storage-consistency`, «Скорость сверки») сигнал прерывает
сразу: остановка не ждёт конца паузы. Сверку, прерванную сигналом,
доводит следующий проход, как прерванную отказом.
Затем сервис уборщика SHALL выйти с кодом 0 раньше срока остановки
контейнера (10 с), а не по SIGKILL. Разовый проход сверки, прерванный
сигналом, SHALL выходить с кодом 1: проход не завершён. Сигнал во время
старта процесса SHALL завершать его с кодом 0 без traceback, как у API
(требование «Остановка во время старта»). Остановка SHALL быть видна в
журнале записью об остановке уборщика.
#### Scenario: docker stop уборщика
- **WHEN** выполняется `docker compose stop cleaner` для работающего
уборщика
- **THEN** команда завершается быстрее 10 с, код выхода контейнера 0, а
в журнале есть запись об остановке
#### Scenario: docker stop во время сверки
- **WHEN** `docker compose stop cleaner` выполняется, пока идёт проход
сверки, а вызов S3 в нём ждёт ответа
- **THEN** команда завершается быстрее 10 с, код выхода контейнера 0, а
в журнале — итог сверки с причиной прерывания «остановка» и запись об
остановке уборщика
#### Scenario: docker stop во время паузы предела скорости
- **WHEN** `docker stop` выполняется для разового прохода сверки, пока
тот ждёт из-за предела скорости
- **THEN** контейнер останавливается не позже чем через секунду после
сигнала, код выхода 1, а в журнале — итог сверки с причиной прерывания
«остановка» и запись об остановке уборщика
@@ -0,0 +1,274 @@
## MODIFIED Requirements
### Requirement: Фиксированный стенд
Стенд SHALL состоять из балансировщика (LB), реплик приложения,
PostgreSQL и Valkey. В профилях загрузок и сверки к ним SHALL
добавляться S3 с его bootstrap, а в профиле сверки — ещё разовые проходы
процесса уборщика. Число реплик SHALL задаваться методикой, по умолчанию
одна. Приложение SHALL запускаться в контейнерах из образа, собранного
из текущего checkout тем же `Dockerfile`. Исключения — профиль
поочерёдной замены и варианты «до» профилей загрузок и сверки. Они берут
образ commit, заданного методикой: образ собирается тем же `Dockerfile`
из файлов этого commit без изменения рабочего дерева. Профиль замены
заканчивается на образе текущего checkout. LB SHALL
запускаться из того же образа и с той же конфигурацией, что у рабочего
стенда. PostgreSQL и Valkey SHALL запускаться из тех же образов, что у
рабочего стенда. Valkey получает ту же конфигурацию. PostgreSQL
получает те же настройки образа плюс модуль записи планов, выключенный
вне снятия плана. S3 SHALL запускаться из того же образа и с теми же
аргументами сервера, что у рабочего стенда, а bucket и пользователей
создаёт тот же bootstrap. В профиле сверки к аргументам S3 добавляется
порт метрик шлюза: он слушает только loopback контейнера S3, и по нему
оркестратор считает запросы к S3. В сериях трека 1 предел соединений
PostgreSQL (`max_connections`) — параметр конфигурации серии, по
умолчанию 100, как у образа. Схема БД SHALL применяться миграциями до
наполнения.
Лимиты SHALL быть одинаковыми во всех прогонах профиля, а в серии трека
1 — во всех прогонах одной конфигурации:
- у каждой реплики приложения — лимит CPU и памяти без swap, заданный
методикой (в профилях лабы 2 — 1 CPU и 2 ГБ, в серии трека 1 — по
конфигурации);
- у LB, PostgreSQL, Valkey, S3 и уборщика — свои лимиты CPU и памяти без
swap, заданные методикой; в серии трека 1 они одинаковы во всех
конфигурациях; у уборщика в управляемом опыте профиля сверки — другой
лимит CPU, тоже заданный методикой;
- у генератора нагрузки в профилях трека 1 — лимит CPU и памяти без
swap, заданный методикой; в остальных профилях генератор без лимита.
Буфер приёма сокетов реплик приложения SHALL быть ограничен так же, как
у рабочего стенда (`load-balancing`, «Загрузки через балансировщик»).
Значение SHALL записываться в паспорт.
Healthcheck образа приложения SHALL быть отключён: готовность реплик
проверяет LB. Порты стенда на хост MUST NOT публиковаться. Настройки
приложения и хранилищ SHALL браться из методики стенда, а не из `.env`
и `config.toml` рабочего стенда. Пароли хранилищ и секреты S3 SHALL
генерироваться на прогон. Генератор нагрузки SHALL работать в той же
docker-сети и обращаться к приложению через LB по имени сервиса, минуя
проброс портов хоста. Стенд SHALL считаться готовым, когда LB видит
готовыми все реплики.
#### Scenario: Лимиты в паспорте
- **WHEN** прогон завершён
- **THEN** паспорт стенда содержит число реплик и лимиты CPU и памяти
реплики приложения, LB, PostgreSQL и Valkey, прочитанные у запущенных
контейнеров, и они одинаковы для всех размеров
#### Scenario: Лимиты конфигурации серии
- **WHEN** серия трека 1 завершена
- **THEN** паспорт по каждой конфигурации содержит число реплик, лимиты
CPU и памяти каждого контейнера стенда и генератора и предел
соединений PostgreSQL, прочитанные у запущенных контейнеров, и они
одинаковы во всех повторах конфигурации
#### Scenario: Нехватка памяти
- **WHEN** процесс приложения превысил лимит памяти и был убит
- **THEN** прогон помечен как проваленный из-за OOM, а не записан как
обычный результат
#### Scenario: Настройки рабочего стенда не влияют
- **WHEN** `.env` и `config.toml` рабочего стенда изменены или
отсутствуют
- **THEN** стенд запускается с теми же настройками приложения и
хранилищ, а окружение приложения в паспорте то же
#### Scenario: Схема до наполнения
- **WHEN** начинается наполнение размера
- **THEN** миграции применены до последней ревизии, и приложение
отвечает готовностью
#### Scenario: Одна реплика за балансировщиком
- **WHEN** профиль лабы 2 (`full`, `quick`, `restore`,
`restore_quick`) запущен с одной репликой
- **THEN** все запросы генератора проходят через LB, прогон завершается
с кодом 0, а таблицы прогонов и сводка содержат те же столбцы и
разделы, что раньше
#### Scenario: Образ прежнего commit
- **WHEN** запускается профиль поочерёдной замены
- **THEN** реплики стартуют на образе commit из методики, схема — на
его последней ревизии, рабочее дерево не меняется, а commit и образы
до и после записаны в паспорт
#### Scenario: S3 в профиле загрузок
- **WHEN** запускается профиль загрузок
- **THEN** S3 стенда запущен из образа рабочего стенда с его аргументами
и лимитами, bootstrap завершился успешно, а образ и лимиты S3 и
ограничение буфера приёма реплики записаны в паспорт
#### Scenario: S3 и уборщик в профиле сверки
- **WHEN** запускается профиль сверки
- **THEN** S3 стенда запущен из образа рабочего стенда с его аргументами
и портом метрик только на loopback своего контейнера, bootstrap
завершился успешно, а аргументы S3, образы и лимиты S3 и уборщика
записаны в паспорт
## ADDED Requirements
### Requirement: Профиль сверки
Команда `make bench_reconcile` (метка `RECONCILE_LABEL`, по умолчанию
`baseline`) SHALL на свежем стенде мерить стоимость прохода сверки
bucket и БД (capability `storage-consistency`). Команда `make
bench_reconcile_quick` — то же на малом наборе и одним повтором, метка
`quick-reconcile-…`, в git не идёт. Результаты SHALL сохраняться в
`evidence/reconcile/<метка>/`. Занятая метка SHALL давать отказ до
запуска стенда.
Стенд — LB, две реплики, PostgreSQL, Valkey и S3 с лимитами рабочего
стенда (требование «Фиксированный стенд»). Проход сверки — разовый
процесс уборщика из образа приложения с лимитами рабочего стенда
(0,25 CPU, 256 МБ без swap), в управляемом опыте — с 1 CPU. Grace
проходов — короткий, заданный методикой, но больше границы живой
загрузки (capability `service-configuration`, «Параметры уборщика»).
Данные — синтетические вложения одного чата:
- 10 000, 30 000 и 100 000 объектов по 4 KiB — один набор, который
растёт между этапами;
- 1 000 объектов по 1 MiB — на отдельном стенде, для цены чтения байтов.
Расхождения SHALL вноситься при наполнении, по 0,25 % от числа объектов
каждого класса: объект без метаданных, метаданные без объекта, другой
размер, зависшая загрузка. Класс объекта SHALL определяться его номером,
а содержимое — номером и зерном методики.
Граница чёрного ящика:
- пользователи и чат создаются через API;
- метаданные вложений оркестратор пишет в PostgreSQL стенда, объекты —
прямой записью в S3 стенда ключами пользователя API;
- проход сверки — процесс уборщика из образа приложения, его результат —
журнал этого процесса;
- фоновая нагрузка — генератор по HTTP через LB;
- сверх этого оркестратор читает счётчики cgroup контейнеров, метрики
шлюза S3 на loopback его контейнера и счётчики PostgreSQL.
Приложение оркестратор не импортирует.
Проходы:
- без фоновой нагрузки и без предела скорости:
- стратегия по умолчанию на всех размерах набора;
- стратегия HEAD на 10 000 и 30 000 объектов;
- глубокая сверка на 10 000 объектов по 4 KiB и на объектах по 1 MiB;
- глубокая сверка с уборщиком 1 CPU на объектах по 1 MiB;
- с фоновой нагрузкой, на 100 000 объектов, стратегия по умолчанию:
- лимит CPU рабочего стенда с пределом скорости по умолчанию и без
предела;
- 1 CPU без предела и с пределом по умолчанию.
Фоновая нагрузка идёт с постоянной интенсивностью, заданной методикой:
скачивания вложений набора, запись сообщений и чтение истории. До и
после каждого прохода — окна без прохода;
- отказ по пределу: `--apply` с пределом изменений 100, когда
кандидатов 1 000 и 10 000, — на образе до change и на образе текущего
checkout.
Каждый проход повторяется три раза, повторы одной ячейки не идут подряд.
Варианты сравниваются внутри одной метки, на одних данных и в одной
сессии хоста. Шум — разброс повторов ячейки, а у проходов с фоновой
нагрузкой ещё отношение p95 окон до и после прохода (A/A).
Для каждого прохода SHALL сохраняться:
- итог прохода из журнала уборщика — длительность и длительность шагов,
просмотренные объекты и строки, найденные расхождения по классам,
затронутые объекты S3, запросы к S3 по операциям, прочитанные байты,
сеансы с PostgreSQL, неперепроверенные кандидаты, код выхода;
- запросы к S3 по метрикам шлюза и счётчики PostgreSQL за проход;
- CPU уборщика, S3 и PostgreSQL за проход;
- память уборщика в начале прохода и её пик;
- у проходов с фоновой нагрузкой — по каждому сценарию в окне прохода и
в окнах до и после: число ответов, ошибки, p50, p95 и p99.
Достоверность:
- найденные расхождения SHALL по каждому классу совпадать с внесёнными.
Иначе команда завершается ненулевым кодом: замер на неверных данных —
не результат;
- в проходах без фоновой нагрузки запросы к S3 по счётчикам сверки SHALL
совпадать с метриками шлюза, иначе проход помечается;
- ответ 5xx фоновой нагрузки — пометка прохода.
В паспорте метки SHALL быть:
- лимиты и образы, в том числе commit варианта «до»;
- аргументы S3;
- размеры набора, размеры объектов, доли расхождений и зерно;
- grace проходов и предел скорости по умолчанию;
- фоновая нагрузка;
- версия ядра ВМ;
- состояние хоста и посторонние контейнеры.
Сводка SHALL давать по каждой ячейке медиану и разброс повторов, вывод
по каждой гипотезе (требование «Стоимость сверки в отчёте») и графики:
длительность и запросы прохода от размера набора по стратегиям, p95
фоновой нагрузки по вариантам.
#### Scenario: Полный профиль сверки
- **WHEN** выполнен `make bench_reconcile`
- **THEN** в `evidence/reconcile/<метка>/` есть паспорт, таблица проходов
со всеми ячейками по три повтора, таблица окон фоновой нагрузки,
сводка с выводами по гипотезам и графики, код выхода 0
#### Scenario: Быстрый профиль сверки
- **WHEN** выполнен `make bench_reconcile_quick`
- **THEN** за несколько минут проходят все виды проходов на малом наборе
по одному повтору, код выхода 0, каталог метки в git не попадает
#### Scenario: Найдено не то, что внесено
- **WHEN** проход нашёл в каком-то классе не столько расхождений,
сколько внесено
- **THEN** команда завершается ненулевым кодом, называет класс, ячейку и
оба числа и удаляет стенд
#### Scenario: Счётчики сверки и метрики S3
- **WHEN** завершён проход без фоновой нагрузки
- **THEN** в строке прохода запросы к S3 по счётчикам сверки равны
запросам по метрикам шлюза, а при различии строка помечена
### Requirement: Стоимость сверки в отчёте
`REPORT.md` SHALL содержать по профилю сверки:
- гипотезы и ожидание, записанные и зафиксированные commit до первого
прохода метки:
- о линейности прохода;
- о цене стратегии HEAD;
- о цене глубокой сверки;
- о влиянии на фоновую нагрузку с порогом p95;
- ожидаемую цену отказа по пределу;
- методику: стенд, лимиты, данные и граница наполнения, ячейки, фоновую
нагрузку, повторы и A/A;
- таблицы результатов метки по ячейкам:
- длительность и цена на объект;
- запросы к S3 и PostgreSQL, байты, CPU и память;
- p95 фоновой нагрузки по вариантам;
- цена отказа по пределу до и после change;
- выводы по каждой гипотезе, обоснование предела скорости по умолчанию
и рекомендации для стратегии HEAD и глубокой сверки;
- ограничения: один хост, ВМ Docker Desktop, генератор на том же хосте,
одна нода S3, синтетические объекты двух размеров.
Числа в отчёт SHALL переноситься из сводки метки, а не пересчитываться
вручную.
#### Scenario: Гипотезы сверки до прогонов
- **WHEN** проверяющий смотрит историю `REPORT.md` и каталога метки
- **THEN** commit с гипотезами раньше commit с результатами метки
#### Scenario: Выводы по метке сверки
- **WHEN** проверяющий открывает раздел стоимости сверки в `REPORT.md`
- **THEN** у каждой гипотезы есть вывод со ссылкой на ячейки сводки
метки, а числа совпадают со сводкой
@@ -0,0 +1,44 @@
## MODIFIED Requirements
### Requirement: Параметры сверки
Параметры сверки bucket и БД (capability `storage-consistency`) SHALL
задаваться в секции `[reconciler]`:
- `interval_seconds` — пауза между плановыми сверками процесса
уборщика, по умолчанию 3600; 0 — без плановой сверки;
- `page_size` — сколько ключей сверка берёт одной страницей списка S3
и сколько строк одним запросом к PostgreSQL, по умолчанию 1000, не
больше 1000;
- `max_changes` — предел изменений за проход, по умолчанию 100;
- `max_objects_per_second` — предел скорости прохода: сколько объектов
S3 он затрагивает в секунду (capability `storage-consistency`,
«Скорость сверки»), по умолчанию 2000; 0 — без ограничения.
`interval_seconds` и `max_objects_per_second` SHALL быть
неотрицательными числами, `page_size` и `max_changes` — целыми не меньше
1. Иначе уборщик MUST NOT стартовать (требование «Некорректное значение
останавливает запуск»).
Отдельного grace у сверки нет: она берёт `[cleaner]
pending_grace_seconds` и его проверку границы живой загрузки
(требование «Параметры уборщика»). Разовая подмена SHALL работать через
окружение `RECONCILER__*` без правки файлов. Разовый проход SHALL
принимать предел изменений и предел скорости и аргументами команды.
Значения по умолчанию и их обоснование SHALL быть описаны в
`REPORT.md`. Реплики API секцию `[reconciler]` не используют.
#### Scenario: Параметры сверки по умолчанию
- **WHEN** уборщик запущен без секции `[reconciler]` и без переменных
`RECONCILER__*`
- **THEN** запись о его старте называет интервал сверки 3600 с,
страницу 1000, предел изменений 100 и предел скорости 2000 объектов в
секунду
#### Scenario: Неверный параметр сверки
- **WHEN** уборщик запускается с `RECONCILER__PAGE_SIZE=5000`,
`RECONCILER__MAX_CHANGES=0`, `RECONCILER__INTERVAL_SECONDS=-1` или
`RECONCILER__MAX_OBJECTS_PER_SECOND=-1`
- **THEN** уборщик не стартует, в журнале — ошибка проверки настроек с
именем поля
@@ -0,0 +1,62 @@
## MODIFIED Requirements
### Requirement: Журнал сверки
Сверка bucket и БД (capability `storage-consistency`) SHALL писать в
журнал процесса уборщика JSON-записи в формате этой capability, в каждой
— `instance_id` процесса. Записи:
- запись о старте уборщика дополнительно называет интервал сверки,
размер страницы, предел изменений и предел скорости, а у разового
прохода — ещё стратегию обхода и глубину;
- каждое найденное расхождение — класс, ключ объекта, `id` вложения,
если он известен, возраст, размеры объекта и метаданных, если они
разные. Уровень `warning`, если расхождение осталось, и `info`, если
проход с `--apply` его исправил, с названием действия;
- итог прохода — режим, стратегия, глубина, предел скорости, сколько
объектов и строк просмотрено, сколько найдено и исправлено по классам,
сколько свежих и уже помеченных, сколько кандидатов не перепроверено,
длительность и причина прерывания. Ещё итог называет стоимость
прохода: сколько объектов S3 он затронул, запросы к S3 по операциям
(список, запрос метаданных, чтение, удаление), сколько байтов объектов
прочитано, сколько было сеансов с PostgreSQL и длительность каждого
шага прохода. Уровень `info`, если расхождений не осталось, иначе
`warning`;
- превышение предела изменений — `error` с пределом, числом
подтверждённых изменений и числом кандидатов, которых проход не
перепроверял;
- отказ S3 или PostgreSQL — `warning`, непредвиденная ошибка — `error` с
traceback.
Если расхождений за проход больше тысячи, отдельными записями SHALL
писаться только первые, а итог SHALL называть, сколько осталось без
записи. Скачивание потерянного оригинала реплика API SHALL писать
записью уровня `info` с `id` вложения и ключом объекта, а не `error`.
Записи сверки MUST NOT содержать ключи доступа и секреты S3, ключ
подписи, подписи запросов, `filename` вложений, байты объектов и их
SHA-256.
#### Scenario: Журнал разового прохода
- **WHEN** сверка находит объект без метаданных и метаданные без
объекта, а затем исправляет их с `--apply`
- **THEN** результат такой:
- в журнале dry-run — две записи `warning` с классом, ключом и
возрастом и итог `warning`;
- в журнале прохода с `--apply` — две записи `info` с действием и
итог `info`;
- секретов S3 и `filename` в журнале нет
#### Scenario: Предел изменений в журнале
- **WHEN** сверка с `--apply` отказывается исправлять из-за предела
- **THEN** в журнале запись `error` с пределом, числом подтверждённых
изменений и числом неперепроверенных кандидатов, а итог прохода —
`warning`
#### Scenario: Стоимость прохода в итоге
- **WHEN** выполняется разовая сверка с `--strategy head` и `--deep`
- **THEN** итог называет эту стратегию, глубину и предел скорости,
затронутые объекты S3, запросы к S3 по операциям, прочитанные байты,
сеансы с PostgreSQL и длительность каждого шага, а секретов S3,
`filename` и SHA-256 объектов в журнале нет
@@ -0,0 +1,369 @@
## MODIFIED Requirements
### Requirement: Сверка bucket и БД
Сверка SHALL сравнивать объекты вложений в bucket — ключи с префиксом
`<имя базы>/attachments/` — с метаданными вложений той же базы в
PostgreSQL и находить расхождения семи классов:
- **объект без метаданных** — объект с ключом вида
`<база>/attachments/<id>/original`, на который не ссылается ни одна
строка и для `id` которого строки нет;
- **метаданные без объекта** — вложение `ready`, объекта по ключу из его
метаданных в bucket нет;
- **другой размер** — вложение `ready`, размер объекта не равен
`size_bytes`;
- **другой SHA-256** — вложение `ready`, размер объекта равен
`size_bytes`, а SHA-256 его содержимого не равен SHA-256 из
метаданных. Этот класс ищет только глубокая сверка;
- **зависшая загрузка** — вложение в статусе «загружается» старше grace,
то же, что убирает уборщик (требование «Уборщик незавершённых
загрузок»);
- **оригинал вернулся** — оригинал вложения помечен потерянным
(требование «Потерянный оригинал»), а объект снова есть с тем же
размером и тем же SHA-256;
- **чужой объект** — то, что сверка не меняет и оставляет оператору:
- объект под префиксом вложений, ключа такого вида API не пишет;
- объект с ключом вида `<id>/original`, у строки которого другой ключ
или на который ссылается строка другого `id`;
- ключ вне префикса вложений своей базы в метаданных вложения: объект
по такому ключу сверка не читает.
Сверку SHALL выполнять процесс уборщика, а не реплики API: разовым
проходом (`make reconcile` или команда сверки в контейнере уборщика) и
плановым (требование «Плановая сверка»). Разовый проход по умолчанию
SHALL ничего не менять (dry-run). С `--apply` он SHALL исправлять:
- объект без метаданных — удалить объект;
- метаданные без объекта, другой размер и другой SHA-256 — пометить
оригинал вложения потерянным;
- зависшую загрузку — убрать тем же порядком, что уборщик;
- вернувшийся оригинал — снять пометку.
Чужой объект сверка MUST NOT удалять, а вложение, метаданные которого
ведут к нему, — помечать или убирать: чужой объект попадает только в
отчёт.
Разовый проход SHALL принимать стратегию обхода:
- по умолчанию — страницы списка объектов и одно обращение к PostgreSQL
на страницу. Ключи списка сверка запоминает, а строки `ready`
сравнивает с ними;
- `--strategy head` — для каждого объекта списка отдельное обращение к
PostgreSQL, для каждой строки `ready` — запрос метаданных её объекта в
S3. Ключей списка сверка не запоминает.
Обе стратегии SHALL находить на одних данных одни и те же расхождения
тех же классов и подчиняться одним правилам безопасности (требование
«Безопасность сверки»).
По умолчанию сверка поверхностная: наличие и размер объекта, байты она
не читает. С `--deep` разовый проход SHALL ещё читать каждый объект
вложения `ready` того же размера, которому больше grace, и сравнивать
SHA-256 его содержимого с метаданными. Плановая сверка глубокой не
бывает (требование «Плановая сверка»).
Отчёт SHALL называть по каждому расхождению класс, ключ объекта, `id`
вложения, если он известен, и возраст. Исключение — кандидаты, которых
проход с `--apply` не перепроверял после отказа по пределу (требование
«Безопасность сверки»): итог называет их число. Итог прохода SHALL
называть:
- стратегию, глубину и предел скорости (требование «Скорость сверки»);
- сколько объектов и строк просмотрено;
- сколько расхождений найдено и исправлено по классам;
- сколько объектов и строк пропущено как свежие;
- сколько вложений уже помечены потерянными;
- сколько кандидатов не перепроверено;
- стоимость прохода: сколько объектов S3 он затронул, запросы к S3 по
операциям, сколько байтов объектов прочитано, сколько было сеансов с
PostgreSQL и сколько длился каждый шаг прохода.
После успешного исправления повторный проход SHALL не находить ни одного
исправимого расхождения.
Код выхода разового прохода:
- 0 — расхождений нет: dry-run их не нашёл, `--apply` исправил все, и
чужих объектов нет;
- 3 — расхождения остались: их нашёл dry-run, `--apply` отказался по
пределу изменений или в bucket есть чужие объекты;
- 1 — проход прерван отказом хранилища, ошибкой или сигналом;
- 2 — неверная конфигурация.
#### Scenario: Расхождения с обеих сторон найдены
- **WHEN** всё это старше grace, и выполняется сверка без `--apply`:
- в bucket мимо API записан объект вложения;
- у готового вложения удалён объект;
- у неиспользуемого готового вложения удалены метаданные;
- у другого в метаданных изменён размер;
- загрузка оборвалась между записью объекта и фиксацией `ready`
- **THEN** отчёт называет каждое расхождение его классом, ключом и
возрастом, код выхода 3, а в PostgreSQL и в bucket ничего не
изменилось
#### Scenario: Исправление расхождений
- **WHEN** после этого выполняется сверка с `--apply`
- **THEN** результат такой:
- объекты без метаданных удалены;
- зависшей загрузки нет — ни метаданных, ни объекта;
- оба вложения с потерянным оригиналом помечены, их метаданные на
месте;
- код выхода 0
#### Scenario: Повторная сверка
- **WHEN** сразу после исправления сверка выполняется ещё раз
- **THEN** ни одного из этих расхождений в отчёте нет, а код выхода
соответствует отчёту: 0, если расхождений в нём нет
#### Scenario: Стратегия HEAD находит то же
- **WHEN** в стенде те же расхождения, что в сценарии «Расхождения с
обеих сторон найдены», и выполняются сверка без `--apply` со
стратегией по умолчанию и с `--strategy head`
- **THEN** оба отчёта называют одни и те же расхождения тех же классов с
теми же ключами, коды выхода равны, а итог стратегии HEAD называет
больше запросов к S3 и сеансов с PostgreSQL
#### Scenario: Другой SHA-256 находит глубокая сверка
- **WHEN** объект готового вложения перезаписан мимо API байтами того же
размера, вложению и объекту больше grace, и выполняется сверка без
`--apply` — сначала без `--deep`, затем с `--deep`
- **THEN** поверхностная сверка это вложение расхождением не считает, а
глубокая называет его классом «другой SHA-256», и её итог называет
прочитанные байты; код выхода 3, а в PostgreSQL и в bucket ничего не
изменилось
- **AND** сверка с `--deep --apply` помечает оригинал потерянным:
скачивание — 404, метаданные — 200
### Requirement: Безопасность сверки
Сверка MUST NOT удалять:
- метаданные вложений, кроме уборки зависшей загрузки;
- объект, на который ссылаются метаданные, в любом статусе;
- объект с ключом вида `<id>/original`, если строка этого `id` есть.
Вложение, на которое ссылается сообщение, MUST NOT терять из-за сверки
ни метаданные, ни объект, ни ссылку в истории. Если его оригинал
потерян, сверка его только помечает.
Свежее сверка MUST NOT трогать и не считает расхождением:
- объект, записанный или изменённый в S3 меньше grace назад;
- вложение, метаданные которого записаны или переведены в `ready` меньше
grace назад.
Grace — тот же, что у уборщика (capability `service-configuration`,
«Параметры уборщика»).
Каждое расхождение SHALL перепроверяться в PostgreSQL и в S3
непосредственно перед действием:
- объект без метаданных — строки с этим ключом или `id` по-прежнему
нет, объект на месте и старше grace;
- метаданные без объекта и другой размер — вложение по-прежнему `ready`
с тем же ключом, а объекта по ключу нет или его размер другой;
- другой SHA-256 — вложение по-прежнему `ready` с тем же ключом, объект
того же размера, а SHA-256 заново прочитанного содержимого другой;
- вернувшийся оригинал — пометка на месте, объект того же размера и
того же SHA-256 заново прочитанного содержимого.
Не подтвердилось — действие не выполняется. Отсутствие объекта MUST NOT
считаться подтверждённым, пока не проверено, что bucket на месте. Иначе
удалённый bucket выглядел бы как потеря всех оригиналов.
Предел изменений: если за проход нужно удалить объекты, пометить
оригиналы или снять пометки больше чем у `[reconciler] max_changes`
вложений, сверка с `--apply` MUST NOT выполнять ни одно из этих
изменений. Как только подтверждённых таких изменений больше предела, она
SHALL перестать перепроверять остальных кандидатов этих классов: отказ
уже решён, а каждая перепроверка — обращения к PostgreSQL и S3, пока
уборка зависших загрузок ждёт. Она пишет ошибку с пределом и числом
подтверждённых изменений, которое больше предела, и завершается кодом
3. Итог называет, сколько кандидатов не перепроверено. Сверка без
`--apply` перепроверяет каждого кандидата. Разовый проход SHALL
принимать больший предел аргументом. Уборка зависших загрузок пределом
не ограничена.
Сверка, уборщик и две сверки одновременно SHALL не мешать друг другу:
- каждое действие безопасно повторять;
- зависшую загрузку сверка убирает тем же порядком и под той же
блокировкой, что уборщик.
Объекты других баз и ключи вне префикса вложений своей базы сверка MUST
NOT читать и менять. Вложение, в метаданных которого такой ключ, —
готовое или зависшую загрузку — она называет в отчёте чужим объектом, не
проверяет его объект, не помечает и не убирает.
#### Scenario: Свежие не тронуты
- **WHEN** в bucket мимо API записан объект вложения, у готового
вложения удалён объект, обоим меньше grace, и выполняется сверка с
`--apply`
- **THEN** объект на месте, вложение не помечено, а отчёт считает их
свежими, а не расхождениями
#### Scenario: Используемое вложение не удаляется
- **WHEN** у вложения, на которое ссылается сообщение, удалён объект,
ему больше grace, и выполняется сверка с `--apply`
- **THEN** результат такой:
- вложение помечено потерянным;
- его метаданные — 200;
- история чата по-прежнему отдаёт его `id` в сообщении;
- ни одна строка вложений не удалена
#### Scenario: Чужой объект не удаляется
- **WHEN** под префиксом вложений базы лежит объект с ключом, которого
API не пишет, ему больше grace, и выполняется сверка с `--apply`
- **THEN** объект на месте, отчёт называет его чужим, код выхода 3
#### Scenario: Предел изменений
- **WHEN** расхождений, которые сверка исправила бы, больше предела, и
выполняется сверка с `--apply`
- **THEN** ни один объект не удалён, ни одно вложение не помечено,
ошибка называет предел и число подтверждённых изменений больше него,
код выхода 3
- **AND** с пределом не меньше их числа повтор исправляет все
#### Scenario: Отказ по пределу без лишних перепроверок
- **WHEN** расхождений, которые сверка исправила бы, вдвое больше
предела, и выполняется сверка с `--apply`
- **THEN** ошибка называет предел и число подтверждённых изменений — на
одно больше предела, итог называет остальных кандидатов
неперепроверенными, ни одно вложение не помечено, код выхода 3
- **AND** сверка без `--apply` называет каждое из этих расхождений
#### Scenario: Предел не останавливает уборку зависших
- **WHEN** загрузка оборвалась между записью объекта и фиксацией `ready`
больше grace назад, расхождений, которые сверка исправила бы, больше
предела, и выполняется сверка с `--apply`
- **THEN** код выхода 3, ни одно вложение не помечено, а зависшей
загрузки нет — ни метаданных, ни объекта
#### Scenario: Объект, на который ссылается строка, не удаляется
- **WHEN** всё это старше grace, и выполняется сверка с `--apply`:
- у готового вложения X в метаданных другой ключ под префиксом
вложений, объекта по нему нет, а объект `<X>/original` на месте;
- готовое вложение Y ссылается на ключ `<Z>/original`, строки Z нет, и
объекты `<Y>/original` и `<Z>/original` на месте
- **THEN** результат такой:
- все три объекта на месте, отчёт называет их чужими, код выхода 3;
- X помечено потерянным: объекта по его ключу нет;
- Y не помечено: объект по его ключу есть
#### Scenario: Ключ вне префикса вложений не трогается
- **WHEN** у готового вложения и у зависшей загрузки старше grace в
метаданных ключ вне префикса вложений своей базы, и выполняется сверка
с `--apply`
- **THEN** отчёт называет оба чужими, код выхода 3, вложение не помечено,
а метаданные зависшей загрузки и объекты обоих под префиксом вложений
на месте
#### Scenario: Сверка под нагрузкой
- **WHEN** выполняются все условия:
- участники дольше grace загружают вложения и отправляют сообщения с
ними;
- в это время сверка с `--apply` повторяется раз в несколько секунд;
- в стенде есть внесённые расхождения
- **THEN** внесённые расхождения исправлены, каждое вложение, загрузка
которого ответила 201, скачивается с тем же SHA-256, а каждое
сообщение отдаёт свои `attachment_ids`
### Requirement: Потерянный оригинал
Если сверка подтвердила, что объекта готового вложения нет, его размер
другой или — у глубокой сверки — SHA-256 его содержимого другой, она
SHALL пометить оригинал вложения потерянным и записать время пометки в
метаданные. Сверка не удаляет ни метаданные, ни ссылки сообщений, ни
объект другого размера или другого содержимого. Байты сверка не
восстанавливает: их нет нигде. Что видит API для помеченного вложения —
capability `attachments`, «Скачивание оригинала».
Пометка MUST NOT менять поля вложения в ответах API, в том числе
`status` и `updated_at`. Пометку SHALL снимать сверка с `--apply`, когда
объект по ключу вложения снова есть, его размер равен `size_bytes`, а
SHA-256 содержимого — SHA-256 из метаданных. Чтобы это проверить, сверка
читает такой объект и без `--deep`. Объект того же размера с другим
содержимым пометку MUST NOT снимать.
#### Scenario: Оригинал вернулся
- **WHEN** оригинал вложения помечен потерянным, затем те же байты
записаны в bucket под его ключом, и выполняется сверка с `--apply`
- **THEN** пометка снята, байты вложения скачиваются — 200 с тем же
SHA-256, а следующий проход не находит расхождений по этому вложению
#### Scenario: Вернулся другой объект того же размера
- **WHEN** оригинал вложения помечен потерянным, затем под его ключом
записаны другие байты того же размера, и выполняется сверка с
`--apply`
- **THEN** пометка на месте, скачивание — 404, а отчёт не называет это
вложение вернувшимся
- **AND** после записи тех же байтов, что были загружены, сверка с
`--apply` снимает пометку
### Requirement: Плановая сверка
Процесс уборщика SHALL сам выполнять сверку с исправлением, без
разового прохода:
- при старте;
- затем не реже чем раз в `[reconciler] interval_seconds`;
- с пределом изменений и пределом скорости из настроек;
- стратегией по умолчанию и без глубокой сверки.
Значение 0 выключает плановую сверку. Плановая и разовая сверки — один
и тот же проход с теми же правилами безопасности.
Ограничение называется в `REPORT.md`. Пока идёт проход сверки, уборка
зависших загрузок ждёт его конца. Объект без метаданных на стенде живёт
не дольше суммы grace, интервала сверки и прохода. С пределом скорости
по умолчанию проход длится не меньше секунды на каждые 2000 затронутых
объектов S3 (требование «Скорость сверки»).
#### Scenario: Плановая сверка без команды
- **WHEN** у готового вложения старше grace удалён объект, а уборщик
работает с коротким интервалом сверки
- **THEN** не позже интервала с запасом вложение помечено потерянным
без разового прохода, а в журнале уборщика есть итог сверки
## ADDED Requirements
### Requirement: Скорость сверки
Проход сверки SHALL в среднем от своего начала затрагивать не больше
`[reconciler] max_objects_per_second` объектов S3 в секунду. Одним
объектом считаются каждый ключ страницы списка, запрос метаданных
объекта, чтение и удаление объекта. Обгоняя предел, проход ждёт, и
ожидание MUST NOT задерживать остановку по сигналу (capability
`graceful-shutdown`, «Остановка уборщика»). Значение 0 — без
ограничения.
Разовый проход SHALL принимать предел аргументом, плановая сверка берёт
его из настроек. Обращения к PostgreSQL предел не ограничивает.
Найденные расхождения, исправления, правила безопасности и код выхода
от предела MUST NOT зависеть.
Как выбран предел по умолчанию и какой предел нужен стратегии HEAD и
глубокой сверке, SHALL быть описано в `REPORT.md` по замеру профиля
сверки (capability `load-benchmark`, «Профиль сверки»).
#### Scenario: Скорость прохода ограничена
- **WHEN** выполняется сверка без `--apply` с пределом скорости, при
котором проход затрагивает объектов S3 на несколько секунд
- **THEN** проход длится не меньше, чем число затронутых объектов S3 из
итога, делённое на предел, а отчёт называет те же расхождения и код
выхода тот же, что у прохода без предела
#### Scenario: Без ограничения скорости
- **WHEN** тот же проход выполняется с пределом 0
- **THEN** он не ждёт: проход короче, чем с пределом, а итог называет
предел 0
@@ -0,0 +1,108 @@
## MODIFIED Requirements
### Requirement: Проверки отказов на отдельном стенде
Сценарии отказов SHALL проверяться автоматически одной командой
`make failure_checks`:
- `sessions`: «Истёкший токен», «Срок не продлевается», «БД остановлена при
запросе с токеном»;
- `data-storage`: «Сбой при добавлении участников», «БД остановлена»,
«БД вернулась», «Соединения исчерпаны»;
- `health`: «Хранилище не готово», «Кэш недоступен», «Хранилище
объектов недоступно»;
- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся»,
«Очистка кэша»;
- `idempotency`: «Сбой при записи сообщения», «Отказ БД при отправке»,
«Ключ после срока»;
- `api-conventions`: «Лимит одновременных загрузок»;
- `attachments`: «Запись в S3 не удалась», «Отклонённая загрузка ничего
не оставляет», «S3 остановлен», «S3 завис», «Незавершённая загрузка не
видна», «Сбой записи метаданных», «Фиксация ready не удалась», «Обрыв
передачи тела», «Отказ раньше очереди», «Все места заняты», «Очередь
ожидания полна», «Ожидание места», «Место освобождается», «Медленный
клиент», «Медленная передача в срок», «Потерянный оригинал», «Загрузка
после простоя S3»;
- `storage-consistency`: все сценарии.
Команда SHALL:
- собрать образ из рабочего дерева;
- поднять отдельный стенд со своими PostgreSQL, Valkey и S3, применить
миграции и bootstrap S3;
- запустить четыре API:
- с настройками по умолчанию;
- «тесный» — с коротким сроком сессии и ключа идемпотентности и пулом
из одного соединения;
- «узкий по загрузкам» — с одним местом загрузки, одной загрузкой в
очереди, коротким сроком ожидания места и коротким сроком тела;
- «с коротким сроком S3» — со сроком вызова S3 в одну секунду: простой
дольше срока вызова в проверке длится полторы секунды, а не шесть.
Значения «узкого» API и API с коротким сроком S3 SHALL передаваться
проверкам, и проверки SHALL сверять с ними стенд;
- запустить уборщика с коротким grace и интервалом, сравнимыми со
временем теста, без плановой сверки, и передать их значения
проверкам. Grace при этом SHALL проходить проверку границы живой
загрузки (`service-configuration`, «Параметры уборщика»). Сверку
проверки запускают сами, и плановая сверка не меняет стенд у них за
спиной;
- выполнить проверки отказов;
- удалить стенд вместе с его данными при любом исходе.
Hook стенда отказов SHALL уметь:
- сообщить вложения стенда в PostgreSQL с их статусами, `id` последнего
вложения в статусе «загружается» и `id` вложений с потерянным
оригиналом;
- сообщить, у каких вложений есть объект в bucket стенда, — по самим
объектам, а не по каталогам хранилища;
- внедрить отказ PostgreSQL:
- при записи метаданных загрузки с заданным `filename`;
- при фиксации её `ready`, и задержать такую фиксацию;
- при пометке потерянного оригинала такого вложения;
- убить и снова запустить обычный API стенда;
- внести расхождения хранилищ:
- записать объект в bucket стенда мимо API и удалить объект мимо API —
только под префиксом вложений базы стенда;
- удалить метаданные вложения, изменить в них размер и сдвинуть их
время в прошлое;
- выполнить разовую сверку — без изменений или с `--apply`, с заданным
пределом изменений, стратегией обхода, глубиной и пределом скорости —
и вернуть её записи и код выхода;
- остановить и запустить уборщика стенда, а также запустить отдельного
уборщика с коротким интервалом плановой сверки на заданное время и
вернуть его журнал.
Других сведений о хранилищах проверки вложений не получают. Объекты без
метаданных проверка находит сравнением двух списков: вложений и
объектов. Ключи доступа S3 hook не получает и не печатает: объект мимо
API записывает процесс в контейнере стенда своими ключами.
Порты PostgreSQL, Valkey и S3 этого стенда MUST NOT публиковаться на
хосте, API — только на `127.0.0.1`. Рабочий стенд, его база, кэш,
хранилище объектов и контейнеры MUST NOT затрагиваться. Код выхода
SHALL быть ненулевым, если не прошла хотя бы одна проверка или уборка.
Параллельный запуск двух прогонов не поддерживается: уборка хвоста в
начале второго удаляет стенд первого.
#### Scenario: Успешный прогон
- **WHEN** рабочий стенд запущен, и выполнен `make failure_checks`
- **THEN** все проверки отказов прошли, код выхода 0, контейнеров и
volumes стенда отказов после команды нет, а у контейнеров рабочего
стенда прежнее время старта, и рабочий API отвечает
#### Scenario: Упавшая проверка
- **WHEN** во время `make failure_checks` падает хотя бы одна проверка
- **THEN** код выхода ненулевой, журналы API и уборщика стенда отказов
выведены, стенд отказов удалён
#### Scenario: Прерывание
- **WHEN** `make failure_checks` прерван Ctrl+C
- **THEN** стенд отказов остановлен и удалён вместе с volumes
#### Scenario: Хвост прошлого прогона
- **WHEN** контейнеры или volumes стенда отказов остались от прогона,
убитого без уборки
- **THEN** следующий `make failure_checks` удаляет их и начинает заново
@@ -0,0 +1,383 @@
# Tasks
Как строить — `design.md` (дальше «решение N»), что должно получиться —
дельты в `specs/`. Порядок — design, Migration Plan. Тесты и hook
пишутся первыми: так красный прогон снимается на коде `7f4e626` без
checkout и stash. Перед первым файлом слоя прочитать его правило:
`service-layer.md`, `repo-layer.md`, `dto.md`, `infra.md`,
`logging.md`, `settings.md`, `run-modes.md`, `docker.md`,
`student-tests.md`, `bench.md`.
**Точки commit** (решение 16). Commit делает основная сессия после
подтверждения (`bench.md`, «Измеренное состояние — commit»):
1. код — группа 9.1;
2. гипотезы — группа 9.2, раньше метки;
3. метка — группа 10;
4. evidence и отчёт — группа 11.
Evidence и метка — только с закоммиченного кода.
**Уборка.** Временные проекты compose, их volumes, сети и образы
убираются сразу после проверки. Сначала `docker compose down` без `-v`,
затем `docker volume rm` по именам своих volumes. Число volumes, сетей и
образов сверяется с исходным. Volumes `mtusi-lab4_postgres_data` и
`mtusi-lab4_s3_data` не удаляются никогда. Контейнеры `domains-*` и
`.env` не трогаются.
**Ожидаемо красное по ходу работы**, остальное разбирается по AGENTS.md:
- между задачами 1.2 и 5.1 сверка покрытия `make student_test` падает
на маркерах новых сценариев («marker points to unknown scenario»);
- новых исключений сверки change не добавляет, поэтому
`test_exclusion_evidence_exists` не меняется.
Вопрос преподавателю об ответе на потерянный оригинал открыт (`PLAN.md`,
`### track2-reconciler`, вопрос 1). Класс «другой SHA-256» помечается
так же, как другой размер. Ответ «иначе» меняет только ветку
`open_content`, сценарий `attachments` и ожидания тестов 1.2.
## 1. Hook, тесты и красный прогон
- [ ] 1.1 `student-tests/fault_hook.py` (только stdlib, синтаксис 3.9),
действие `reconcile dry-run|apply [<предел>]` по решению 14:
- необязательные `--strategy head`, `--deep` и
`--max-objects-per-second R`;
- каждое проверяется по списку разрешённых: стратегия — `batch` или
`head`, R — неотрицательное число. Иначе код 2 hook;
- аргументы передаются `reconcile` в контейнере уборщика как есть;
- docstring hook называет новые аргументы.
Проверка: `make lint`; поведение — задача 1.3.
- [ ] 1.2 `student-tests/test_failures.py`, маркер `fault`, пять тестов по
таблице решения 14 с `@pytest.mark.spec("storage-consistency", …)` на
каждый новый сценарий:
- `test_reconcile_head_strategy_same_findings`;
- `test_reconcile_deep_checksum`;
- `test_reconcile_restore_needs_same_bytes` (ещё и «Оригинал вернулся»);
- `test_reconcile_rate_limit` (оба сценария скорости);
- `test_reconcile_limit_stops_rechecks`.
Тесты фильтруют записи сверки по своим `id` и ключам и сверяют код с
записями того же прохода (`Reconcile.assert_code_matches`), как тесты
`track2-reconciler`. Байты «другие того же размера» — свои для каждого
теста, от зерна. Проверка: задача 1.3.
- [ ] 1.3 Красный прогон до кода групп 2–4 (дерево с 1.1–1.2, код
`7f4e626`):
```
make failure_checks FAULT_ARGS='-k "head_strategy or deep_checksum or restore_needs or rate_limit or limit_stops"'
```
Ожидание: падают все пять — ошибка argparse (код 2) у новых аргументов,
снятие пометки по размеру у `…_restore_needs_same_bytes`, `changes` > 3
у `…_limit_stops_rechecks`. Вывод сохранить в scratchpad для evidence
11.2. Проверка: 5 failed с этими причинами, стенд отказов убран.
## 2. Настройки, enum и DTO
- [ ] 2.1 `src/config/settings.py`, класс `Reconciler`:
`max_objects_per_second: float = Field(default=2000, ge=0)` с
комментарием о единице и 0 (решение 6, дельта
`service-configuration`). Ещё строка в `config_example.toml`.
Проверка:
- `uv run python -c "from src.config import settings;
print(settings.reconciler.max_objects_per_second)"` — 2000.0;
- `RECONCILER__MAX_OBJECTS_PER_SECOND=-1 uv run python -m src.cleaner
reconcile` — «Invalid cleaner settings» с `loc` поля и код 2 до
обращения к хранилищам.
- [ ] 2.2 `src/schemas/enums/attachment.py`:
- `ReconcileFinding.CHECKSUM_MISMATCH = "checksum_mismatch"` с
комментарием;
- `ReconcileStrategy` (`batch`, `head`).
`src/schemas/dataclasses/attachment.py`, `ReconcilePassDTO` — новые
поля в конце со значениями по умолчанию (решения 8 и 15): `strategy`,
`deep`, `max_objects_per_second`, `storage_objects`, `s3_requests`,
`read_bytes`, `db_sessions`, `unchecked`, `phase_ms`. Отображения —
`MappingProxyType`. Экспорт — в `__init__.py` по алфавиту (`dto.md`).
Проверка: `make lint`, импорт `src.schemas` без ошибок.
## 3. Счётчики клиента S3
- [ ] 3.1 `src/infra/s3/client.py` по решению 8:
- `ObjectStorage` считает попытки вызовов по операциям (`list`,
`head`, `get`, `delete`, `put`) в `_call`, ключи страниц — в
`list_page`, прочитанные байты — в `_read_chunk`;
- `stats()` отдаёт снимок `StorageStats` (frozen, отображение —
`MappingProxyType`);
- поведение вызовов, сроки и перевод ошибок не меняются;
- docstring модуля называет счётчики.
Проверка: `make lint`. Совпадение с метриками шлюза — задача 6.7 (без
пометки `count_mismatch`).
## 4. Сервис сверки и процесс уборщика
- [ ] 4.1 `AttachmentReconcileService.reconcile(…, strategy, deep,
max_objects_per_second, …)` по решениям 6, 8 и 15:
- темп перед каждым вызовом S3 рядом с `_check_stop`. Счёт затронутых
объектов — дельта `storage.stats()` от начала прохода, ожидание —
кусками ≤ 0,2 с с проверкой сигнала;
- обёртка `db_scope` со счётом сеансов, её же получает внутренний
`AttachmentCleanupService`;
- `phase_ms` шагов `list`, `rows`, `stale`, `recheck`, `act`;
- поля стоимости в DTO и в «Finished reconcile pass».
Проверка: тесты `…_rate_limit` и `…_head_strategy_same_findings`
(поле `db_sessions`) зелёные в задаче 5.2.
- [ ] 4.2 Ранний отказ по пределу по решению 7:
- в `_recheck_all` при `apply`, как только подтверждённых классов под
пределом (вместе с `checksum_mismatch`) больше `max_changes`,
остальные кандидаты этих классов не перепроверяются и идут в
`unchecked`;
- «Reconcile changes exceed limit» с `unchecked`;
- dry-run перепроверяет всех.
Проверка: `…_limit_stops_rechecks` и прежние
`test_reconcile_change_limit`, `…_limit_keeps_cleanup` — зелёные (5.2).
- [ ] 4.3 Глубокая сверка по решению 5:
- с `--deep` — GET и SHA-256 потоком (`open_original`, блоки клиента)
у строк `ready` без пометки, старше grace и того же размера;
- класс `checksum_mismatch` — в `LIMITED_KINDS` (пометка под
пределом), в `NEEDS_BUCKET` — нет: объект есть. Перепроверка и
проверка перед пометкой заново читают объект;
- «оригинал вернулся» во всех режимах подтверждается тем же SHA-256:
перепроверка и проверка перед `clear_lost`;
- `read_bytes` в итоге. SHA-256 в журнал не пишется.
Проверка: `…_deep_checksum`, `…_restore_needs_same_bytes`,
`test_reconcile_restored_original` — зелёные (5.2).
- [ ] 4.4 Стратегия `head` по решению 4:
- шаг S3 → БД — выборка строки на объект (`get_attachments_for_objects`
с одним элементом); строки с тем же ключом пропускаются;
- шаг БД → S3 — HEAD на строку своей базы (с `--deep` — GET);
- множества `seen` нет;
- зависшие, перепроверка, предел и действия — общие.
Проверка: `…_head_strategy_same_findings` зелёный (5.2); на 10k в
задаче 6.7 `found` равен внесённому.
- [ ] 4.5 `src/cleaner/main.py`:
- аргументы `reconcile` — `--strategy {batch,head}`, `--deep`,
`--max-objects-per-second R` (≥ 0, иначе ошибка argparse, код 2);
- плановая сверка — `batch`, без `--deep`, предел из настроек;
- «Started cleaner» с `reconcile_max_objects_per_second`, а у разового
прохода — ещё с `reconcile_strategy` и `reconcile_deep`.
`Makefile`, цель `reconcile` — `STRATEGY=head`, `DEEP=1`, `RATE=R`.
Проверка: `make -n reconcile STRATEGY=head DEEP=1 RATE=5` печатает
аргументы; `--max-objects-per-second -1` — код 2.
## 5. Спеки и проверки отказов
- [ ] 5.1 Sync дельт в основные спеки — все шесть capability, как в
прежних changes. Purpose `storage-consistency` правится руками:
«стоимость обхода и стратегии описывает change» → описаны в этом
change. Проверка:
- `openspec validate --specs` без ошибок;
- `make student_test` против временного или рабочего стенда — сверка
покрытия без «unknown scenario»;
- новые сценарии `storage-consistency` считаются покрытыми проверками
отказов.
- [ ] 5.2 Полный `make failure_checks` на дереве после групп 2–4: все
проверки зелёные (49 прежних и 5 новых), журнал PostgreSQL без
признаков аварии, стенд отказов убран. Проверка: код 0, число и время в
выводе (ожидаемо дольше на ~1,5–2 мин).
## 6. Профиль `reconcile` стенда `bench/`
- [ ] 6.1 `bench/bench.compose.yml`, сервис `cleaner`: лимиты
`BENCH_CLEANER_CPUS` / `BENCH_CLEANER_MEMORY` в
`deploy.resources.limits` и `memswap_limit` — без swap, как у
остальных. `compose_env` в `run.py` их задаёт: `Profile.cleaner_cpus`
0,25 и `cleaner_memory` 256m — лимиты рабочего стенда. Проверка: в
`docker compose config` стенда у `cleaner` 0,25 / 256 МиБ и swap =
памяти; прежние профили не меняются (паспорт `stand.app_env` тот же).
- [ ] 6.2 `bench/reconcile.py` (только stdlib, без docker) по решениям
2, 10–13:
- модель набора: `id`, содержимое и класс по номеру, строки CSV для
`\copy`, ожидаемые числа по этапам;
- план этапов и ячеек кругами от `order_seed`;
- разбор записей уборщика, метрик шлюза и строк `bg,…` k6;
- окна и `r` / `a` H4;
- строки `passes.csv` и `windows.csv`;
- вердикты H1–H4 и S4;
- `summary.md`, SVG через `plots.Svg`;
- `--selftest` на синтетических журналах, метриках и строках.
Проверка: `uv run python bench/reconcile.py --selftest` — код 0.
- [ ] 6.3 `bench/fill_objects.py` по решению 3:
- работает только в контейнере на образе стенда, botocore образа, `src`
не импортирует;
- генератор набора — из `reconcile.py` (`/bench` только на чтение);
- ключи API — из окружения, `docker run -e <имя>` без значения;
- `--processes`, `--threads`, диапазон номеров и размер объекта;
- печатает число объектов и PUT/с, ошибка PUT — код 1.
Проверка: задача 6.7 — `listed_objects` равно модели.
- [ ] 6.4 `bench/k6/background.js` по решению 10:
- три сценария `constant-arrival-rate` (скачивания из
`/work/downloads.json`, запись в чат записи, чтение его первой
страницы);
- строка `bg,…` на запрос в файл консоли;
- идентификация — `lib.js`, отправка — `messageHeaders`;
- интенсивности, длительность и VU — из окружения.
Проверка: задача 6.7 — число строк равно итерациям итога k6, ответов
5xx нет.
- [ ] 6.5 `bench/run.py`, профили `reconcile` и `reconcile_quick` (поля
`Profile.reconcile_*` — целиком в `meta.json`) и `Bench.run_reconcile`
по решениям 1–3, 7–10, 13:
- S3 запускается у профилей загрузок и сверки;
- override `.work/s3-metrics.compose.yml` из `command` сервиса `s3`
`docker compose config` с `-metricsPort`;
- наполнение: строки — `\copy` через stdin psql, объекты — контейнер
`mtusi-bench-fill`, ожидание grace + 2 с после последнего PUT;
- разовые проходы `mtusi-bench-reconcile-<n>` с лимитом CPU варианта
через окружение compose; `before` — с override образа
`bench-from`;
- снимки метрик S3 и `pg_stat_database` до и после прохода;
- сэмплер `scan` 0,5 с на этап;
- блок H4: один k6 на блок, тихие окна 30 с;
- S4 на свежем стенде: строки без объектов `\copy`;
- сверка `found` с моделью — отказ команды; `count_mismatch` —
пометка;
- проверка commit `reconcile_before` до стенда — код 2, как у
`uploads_before`;
- `mtusi-bench-fill` и `mtusi-bench-reconcile-*` — в остатках стенда и
уборке;
- строка хода на каждый проход.
Проверка — задача 6.7.
- [ ] 6.6 `Makefile`: цели `bench_reconcile [RECONCILE_LABEL=…]` и
`bench_reconcile_quick` под `$(KEEP_AWAKE)`, с комментариями о
длительности (~50 и ~6 мин). `.gitignore` —
`evidence/reconcile/quick-reconcile-*`. Проверка: `make -n
bench_reconcile` и `make -n bench_reconcile_quick` печатают команды
`run.py`.
- [ ] 6.7 `make bench_reconcile_quick` на дереве (шумный хост допустим).
Проверка:
- код 0, все виды проходов;
- `found` равен внесённому;
- нет `count_mismatch`, нет 5xx фона;
- в `summary.md` — строки H1–H4 и S4, SVG открываются;
- время ~6 мин;
- после — volumes, сети и образы как до запуска (кроме тегов
`mtusi-messenger:bench*`, которые профиль снимает сам).
Записать время и итог в `PLAN.md` (решения apply).
- [ ] 6.8 Регресс `bench/` после правок старта стенда: `make
bench_uploads_quick` и `make bench_quick` — код 0. `--selftest`
`uploads.py`, `resources.py`, `scaling.py`, `failover.py` — код 0.
Проверка: коды и строки хода без ошибок.
## 7. Драйвер скилла
- [ ] 7.1 `driver.py reconcile-signal --pace` (stdlib, Python 3.9) по
решению 14:
- вместо `pause s3` — разовый `reconcile --max-objects-per-second 1`;
- `docker stop` через 2 с после «Started cleaner»;
- ожидание: код 1, «Finished reconcile pass» с `interrupted_by: stop`,
«Stopped cleaner» с `exit_code` 1, остановка ≤ 1 с после сигнала;
- только не рабочий проект compose, как сейчас.
`SKILL.md` называет режим. Проверка: запуск на временном проекте —
код 0 драйвера, затем уборка проекта.
## 8. Правила и документы
- [ ] 8.1 Правила:
- `bench.md` — раздел «Профиль сверки (`reconcile`)» и строка таблицы
инструментов. Исключения границы: наполнение данных стенда `\copy`,
загрузчик в контейнере, метрики шлюза на loopback, разовые проходы
уборщика и их журнал; порт метрик только у S3 профиля сверки;
`bench_compare` к меткам сверки не применяется;
- `service-layer.md` — стратегии, глубокая, темп, ранний отказ, счёт
сеансов;
- `infra.md` — счётчики клиента S3 и `stats()`;
- `settings.md` — `max_objects_per_second` и обоснование 2000;
- `logging.md` — поля «Started», «Finished» и «exceed limit»;
- `run-modes.md` — аргументы `reconcile`;
- `student-tests.md` — пять тестов, аргументы hook, красный прогон;
- `dto.md` — enum и поля DTO.
Проверка: правила не противоречат design и дельтам.
- [ ] 8.2 AGENTS.md:
- абзац о лабе — change `track2-reconcile-cost`;
- таблица команд: `bench_reconcile`, `bench_reconcile_quick`, аргументы
`make reconcile`, `reconcile-signal --pace`;
- карта кода: `bench/reconcile.py`, `fill_objects.py`,
`k6/background.js`, сервис сверки, клиент S3;
- карта evidence: `evidence/reconcile/<метка>/`;
- правило «Лаба 4, сверка» — предел скорости, стратегии, глубокая,
ранний отказ.
Проверка: все пути в AGENTS.md существуют.
- [ ] 8.3 `PLAN.md`, раздел `### track2-reconcile-cost` — решения apply
(«Решения») и вопросы, если появятся. Проверка: раздел есть, ссылки на
design.
- [ ] 8.4 `make lint`, `make check`, `make validate
PYTHON=.venv/bin/python`, `openspec validate track2-reconcile-cost
--strict`. Проверка: все — код 0.
## 9. Commit кода и гипотезы
- [ ] 9.1 Commit кода — точка 1 (основная сессия, после подтверждения:
`git status`, `git diff --stat`, предложенное сообщение). Рабочий стенд
для evidence этого change не нужен. Новый код уборщика на нём — по
решению основной сессии (design, Migration Plan). Проверка: дерево
чистое, hash commit записан в `PLAN.md` при следующем commit.
- [ ] 9.2 Гипотезы H1–H4, ожидание S4 и методика (решение 12) — в
`REPORT.md`, раздел «Стоимость сверки: гипотезы (change
`track2-reconcile-cost`)». Это отдельный commit — точка 2, раньше
метки. Проверка: в `git log` commit гипотез после commit кода и до
commit метки.
## 10. Метка
- [ ] 10.1 `make bench_reconcile` с закоммиченного кода на тихом хосте:
- рабочий стенд — `make stop`, `domains-*` основная сессия
останавливает на ~50 мин и потом поднимает;
- проверка хоста — `bench.md`, «Результаты»;
- затем commit каталога метки — точка 3.
Проверка:
- `dirty: false`, нет `host_warnings` и `other_containers`;
- все ячейки, по три повтора;
- `found` равен внесённому, нет `count_mismatch` и 5xx фона;
- в `summary.md` — вердикты H1–H4 и S4.
Расхождение с гипотезой — не повод править гипотезу: вывод
«опровергнута» пишется в `REPORT.md`.
## 11. Evidence и отчёт
- [ ] 11.1 `evidence/reconcile/service.md`, раздел «Остановка во время
паузы предела скорости» — вывод `driver.py reconcile-signal --pace`
(задача 7.1) с закоммиченного кода: команда, дата, commit. Проверка:
код 1, `interrupted_by: stop`, остановка ≤ 1 с.
- [ ] 11.2 `evidence/tests/`:
- `failure-checks.md` — полный `make failure_checks` с закоммиченного
кода и красный прогон задачи 1.3;
- `make test_isolated` — зелёный, база и префикс `test_<db>/` убраны.
Проверка: числа и commit в файлах, `test_exclusion_evidence_exists`
зелёный.
- [ ] 11.3 `REPORT.md` (спек `load-benchmark`, «Стоимость сверки в
отчёте»):
- раздел «Стоимость сверки: результаты метки `baseline`» — паспорт,
таблицы по этапам, H4 и S4 из `summary.md`, вывод по каждой гипотезе
со ссылкой на ячейки сводки;
- выбор предела 2000 по метке и рекомендации для `head` и глубокой —
CPU S3 на объект;
- «Сверка хранилищ»: стратегия `head`, глубокая и класс «другой
SHA-256», снятие пометки по SHA-256, предел скорости, ранний отказ,
стоимость в итоге;
- строки таблицы доказательств уровня «5»;
- «Ограничения»: один хост, ВМ, генератор на том же хосте, одна нода
S3, синтетические объекты двух размеров, лимит CPU уборщика.
Проверка: числа совпадают со сводкой метки, ссылки `evidence/…`
существуют.
- [ ] 11.4 `PLAN.md`: строка 6 сводной таблицы — commit кода, гипотез и
метки, evidence; раздел `### track2-reconcile-cost` дополнен. Затем
commit evidence и отчёта — точка 4. Проверка: дерево чистое после
commit.