feat: add reconcile strategies, deep check, rate limit and cost profile

- reconcile --strategy head, --deep (checksum_mismatch), restore needs the same SHA-256
- [reconciler] max_objects_per_second (2000), pause interrupted by signal
- --apply stops rechecks once the limit is exceeded (unchecked)
- pass cost in the summary: S3 objects and requests, bytes, DB sessions, phases
- S3 client counters, cleaner exits with os._exit after main()
- fault tests, hook args, driver reconcile-signal --pace
- bench profile reconcile / reconcile_quick: fill outside the API, gateway metrics, background load
- sync spec deltas, rules, AGENTS.md, PLAN.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-23 04:52:56 +03:00
co-authored by Claude Opus 5.5
parent dcdfe5f2e4
commit 8d4cf7eebf
41 changed files with 5344 additions and 441 deletions
@@ -785,6 +785,78 @@ change» → описано в нём.
доказательств;
- `PLAN.md`.
### Уточнения apply
Решения, принятые в `/opsx:apply` без пользователя (он недоступен), — то
же в `PLAN.md`, `### track2-reconcile-cost`, «Решения apply».
1. **Пауза предела — после вызова S3, а не перед следующим** (решение 6).
Перед вызовом остаётся проверка сигнала. Пауза «до следующего» не
ограничивала бы последний вызов прохода: проход из одной страницы
списка не ждал бы вовсе, и сценарий «Скорость прохода ограничена»
(длительность ≥ объектов / предел) не выполнялся бы. Средняя скорость
от начала прохода та же; DELETE шага уборки — `_pace` после
`remove_stale_pending`.
2. **`StoredObjectInfo.last_modified` и у `open` (GET)** (решения 4–5):
глубокая сверка `head` читает объект сразу, без HEAD, и свежесть
объекта проверяет по `LastModified` ответа GET. Поведение вызова не
меняется — в метаданных одно поле больше.
3. **`ReconcileFindingDTO.sha256`** — SHA-256 строки в находке: по нему
действие (`_fix`) сверяет заново прочитанный объект без лишней выборки
строки. В журнал не попадает (`_record` перечисляет поля сам).
4. **Глубокая сверка и свежесть** (решение 5): строка моложе grace —
`fresh_rows`, объект моложе grace — `fresh_objects`, ни тот, ни другой
не читается; объект исчез или изменил размер после списка — без
находки (следующий проход). Обе стратегии считают одинаково.
5. **Вернувшийся объект с другим SHA-256** — `lost_known` (пометка на
месте), а не находка: отчёт его вернувшимся не называет.
6. **Hook** (решение 14): предел изменений — первым позиционным
аргументом, флаги — по одному разу; иначе код 2.
7. **Тест предела скорости**: восемь загрузок (объектов хватает и на
свежем стенде, `-k rate_limit`), своя потеря оригинала — сравнение
своих находок; уборщик стенда стоит на время двух проходов, иначе
зависшая загрузка соседнего теста могла бы стать «старше grace» между
ними.
8. **Быстрый профиль — два свежих стенда**, а не один (решение 1): S4 на
стенде с внесёнными классами убрал бы зависшие загрузки первым же
`--apply`, и найденное у «до» и «после» разошлось бы с моделью.
Цена — ~40 с.
9. **Остановка k6 блока H4** — `docker exec mtusi-bench-k6 pkill -INT -f
background.js`: по SIGINT k6 завершает сценарии и пишет итог; строки
`bg,…` сверяются с итерациями так же, как у `failover`. Длительность —
с точностью 0,01 мс: p95 чтения истории — единицы миллисекунд, и целые
мс огрубляли `r` (быстрый профиль: `r` чтения 3,0 из 1 и 3 мс).
10. **Память в H1 и H2** (решение 12): выборка «в начале прохода» по
отсчётам 0,5 с ловит процесс до прогрева клиентов (быстрый профиль:
44–89 МиБ, рост ~14 МиБ на 2 000 объектов — постоянная часть, не
множество). Поэтому H1 — наклон пика памяти `batch` между наименьшим и
наибольшим N (Б на ключ), H2 — рост пика `head` между N; прирост
прохода на объект остаётся столбцом `passes.csv`. Гипотезы в
`REPORT.md` записаны в этой форме до метки.
11. **Каждый проход сверяет с моделью** ещё `listed_objects` и
`checked_rows`, не только первый проход этапа; S4 — без ожидания grace:
у его объектов есть строки, свежесть на находки не влияет.
12. **Окно шага списка** (решение 10, справочно) — строка `list` в
`windows.csv`, в вердикт не входит.
13. **`driver.py reconcile-signal --pace`** кладёт 8 объектов пробы под
`<база>/attachments/pace-signal-*` (botocore в одноразовом контейнере
`api` его ключами): на пустом bucket временного стенда проход не
затронул бы ни одного объекта и не ждал бы. Объекты удаляются в
`finally`. Остановка меряется от события `kill` Docker до
`State.FinishedAt` (оба — часы ВМ); время `docker stop` (CLI и разбор
контейнера демоном) печатается рядом.
14. **Выход уборщика без финализации интерпретатора** (спек
`graceful-shutdown`, «docker stop во время паузы предела скорости»).
Проба на временном стенде: пауза прерывается за ~0,2 с после сигнала
(«Stopped cleaner» через 0,18 с), но процесс выходил ещё через
0,8–1,5 с — финализация модулей botocore и SQLAlchemy при 0,25 CPU (у
обычного прохода без сигнала — те же ~0,8 с). Итог — 1,16–1,5 с, больше
секунды спека. `src/cleaner/__main__.py` после `main()` сбрасывает
stdout и stderr и выходит `os._exit(code)`: engine и клиент S3 к этому
моменту закрыты, записи уже в stdout. После правки — 0,22 с от сигнала
до выхода. Ошибки argparse и непредвиденные исключения выходят как
раньше (до `os._exit` не доходят).
## Risks / Trade-offs
- **[Предел 2000/с удлиняет плановый проход вдвое]** → на 100k с ~30 до
+26 -26
View File
@@ -37,7 +37,7 @@ Evidence и метка — только с закоммиченного кода
## 1. Hook, тесты и красный прогон
- [ ] 1.1 `student-tests/fault_hook.py` (только stdlib, синтаксис 3.9),
- [x] 1.1 `student-tests/fault_hook.py` (только stdlib, синтаксис 3.9),
действие `reconcile dry-run|apply [<предел>]` по решению 14:
- необязательные `--strategy head`, `--deep` и
`--max-objects-per-second R`;
@@ -47,7 +47,7 @@ Evidence и метка — только с закоммиченного кода
- docstring hook называет новые аргументы.
Проверка: `make lint`; поведение — задача 1.3.
- [ ] 1.2 `student-tests/test_failures.py`, маркер `fault`, пять тестов по
- [x] 1.2 `student-tests/test_failures.py`, маркер `fault`, пять тестов по
таблице решения 14 с `@pytest.mark.spec("storage-consistency", …)` на
каждый новый сценарий:
- `test_reconcile_head_strategy_same_findings`;
@@ -60,7 +60,7 @@ Evidence и метка — только с закоммиченного кода
записями того же прохода (`Reconcile.assert_code_matches`), как тесты
`track2-reconciler`. Байты «другие того же размера» — свои для каждого
теста, от зерна. Проверка: задача 1.3.
- [ ] 1.3 Красный прогон до кода групп 2–4 (дерево с 1.1–1.2, код
- [x] 1.3 Красный прогон до кода групп 2–4 (дерево с 1.1–1.2, код
`7f4e626`):
```
@@ -74,7 +74,7 @@ Evidence и метка — только с закоммиченного кода
## 2. Настройки, enum и DTO
- [ ] 2.1 `src/config/settings.py`, класс `Reconciler`:
- [x] 2.1 `src/config/settings.py`, класс `Reconciler`:
`max_objects_per_second: float = Field(default=2000, ge=0)` с
комментарием о единице и 0 (решение 6, дельта
`service-configuration`). Ещё строка в `config_example.toml`.
@@ -84,7 +84,7 @@ Evidence и метка — только с закоммиченного кода
- `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`:
- [x] 2.2 `src/schemas/enums/attachment.py`:
- `ReconcileFinding.CHECKSUM_MISMATCH = "checksum_mismatch"` с
комментарием;
- `ReconcileStrategy` (`batch`, `head`).
@@ -98,7 +98,7 @@ Evidence и метка — только с закоммиченного кода
## 3. Счётчики клиента S3
- [ ] 3.1 `src/infra/s3/client.py` по решению 8:
- [x] 3.1 `src/infra/s3/client.py` по решению 8:
- `ObjectStorage` считает попытки вызовов по операциям (`list`,
`head`, `get`, `delete`, `put`) в `_call`, ключи страниц — в
`list_page`, прочитанные байты — в `_read_chunk`;
@@ -112,7 +112,7 @@ Evidence и метка — только с закоммиченного кода
## 4. Сервис сверки и процесс уборщика
- [ ] 4.1 `AttachmentReconcileService.reconcile(…, strategy, deep,
- [x] 4.1 `AttachmentReconcileService.reconcile(…, strategy, deep,
max_objects_per_second, …)` по решениям 6, 8 и 15:
- темп перед каждым вызовом S3 рядом с `_check_stop`. Счёт затронутых
объектов — дельта `storage.stats()` от начала прохода, ожидание —
@@ -124,7 +124,7 @@ Evidence и метка — только с закоммиченного кода
Проверка: тесты `…_rate_limit` и `…_head_strategy_same_findings`
(поле `db_sessions`) зелёные в задаче 5.2.
- [ ] 4.2 Ранний отказ по пределу по решению 7:
- [x] 4.2 Ранний отказ по пределу по решению 7:
- в `_recheck_all` при `apply`, как только подтверждённых классов под
пределом (вместе с `checksum_mismatch`) больше `max_changes`,
остальные кандидаты этих классов не перепроверяются и идут в
@@ -134,7 +134,7 @@ Evidence и метка — только с закоммиченного кода
Проверка: `…_limit_stops_rechecks` и прежние
`test_reconcile_change_limit`, `…_limit_keeps_cleanup` — зелёные (5.2).
- [ ] 4.3 Глубокая сверка по решению 5:
- [x] 4.3 Глубокая сверка по решению 5:
- с `--deep` — GET и SHA-256 потоком (`open_original`, блоки клиента)
у строк `ready` без пометки, старше grace и того же размера;
- класс `checksum_mismatch` — в `LIMITED_KINDS` (пометка под
@@ -146,7 +146,7 @@ Evidence и метка — только с закоммиченного кода
Проверка: `…_deep_checksum`, `…_restore_needs_same_bytes`,
`test_reconcile_restored_original` — зелёные (5.2).
- [ ] 4.4 Стратегия `head` по решению 4:
- [x] 4.4 Стратегия `head` по решению 4:
- шаг S3 → БД — выборка строки на объект (`get_attachments_for_objects`
с одним элементом); строки с тем же ключом пропускаются;
- шаг БД → S3 — HEAD на строку своей базы (с `--deep` — GET);
@@ -155,7 +155,7 @@ Evidence и метка — только с закоммиченного кода
Проверка: `…_head_strategy_same_findings` зелёный (5.2); на 10k в
задаче 6.7 `found` равен внесённому.
- [ ] 4.5 `src/cleaner/main.py`:
- [x] 4.5 `src/cleaner/main.py`:
- аргументы `reconcile` — `--strategy {batch,head}`, `--deep`,
`--max-objects-per-second R` (≥ 0, иначе ошибка argparse, код 2);
- плановая сверка — `batch`, без `--deep`, предел из настроек;
@@ -168,7 +168,7 @@ Evidence и метка — только с закоммиченного кода
## 5. Спеки и проверки отказов
- [ ] 5.1 Sync дельт в основные спеки — все шесть capability, как в
- [x] 5.1 Sync дельт в основные спеки — все шесть capability, как в
прежних changes. Purpose `storage-consistency` правится руками:
«стоимость обхода и стратегии описывает change» → описаны в этом
change. Проверка:
@@ -177,21 +177,21 @@ Evidence и метка — только с закоммиченного кода
покрытия без «unknown scenario»;
- новые сценарии `storage-consistency` считаются покрытыми проверками
отказов.
- [ ] 5.2 Полный `make failure_checks` на дереве после групп 2–4: все
- [x] 5.2 Полный `make failure_checks` на дереве после групп 2–4: все
проверки зелёные (49 прежних и 5 новых), журнал PostgreSQL без
признаков аварии, стенд отказов убран. Проверка: код 0, число и время в
выводе (ожидаемо дольше на ~1,5–2 мин).
## 6. Профиль `reconcile` стенда `bench/`
- [ ] 6.1 `bench/bench.compose.yml`, сервис `cleaner`: лимиты
- [x] 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) по решениям
- [x] 6.2 `bench/reconcile.py` (только stdlib, без docker) по решениям
2, 10–13:
- модель набора: `id`, содержимое и класс по номеру, строки CSV для
`\copy`, ожидаемые числа по этапам;
@@ -204,7 +204,7 @@ Evidence и метка — только с закоммиченного кода
- `--selftest` на синтетических журналах, метриках и строках.
Проверка: `uv run python bench/reconcile.py --selftest` — код 0.
- [ ] 6.3 `bench/fill_objects.py` по решению 3:
- [x] 6.3 `bench/fill_objects.py` по решению 3:
- работает только в контейнере на образе стенда, botocore образа, `src`
не импортирует;
- генератор набора — из `reconcile.py` (`/bench` только на чтение);
@@ -213,7 +213,7 @@ Evidence и метка — только с закоммиченного кода
- печатает число объектов и PUT/с, ошибка PUT — код 1.
Проверка: задача 6.7 — `listed_objects` равно модели.
- [ ] 6.4 `bench/k6/background.js` по решению 10:
- [x] 6.4 `bench/k6/background.js` по решению 10:
- три сценария `constant-arrival-rate` (скачивания из
`/work/downloads.json`, запись в чат записи, чтение его первой
страницы);
@@ -223,7 +223,7 @@ Evidence и метка — только с закоммиченного кода
Проверка: задача 6.7 — число строк равно итерациям итога k6, ответов
5xx нет.
- [ ] 6.5 `bench/run.py`, профили `reconcile` и `reconcile_quick` (поля
- [x] 6.5 `bench/run.py`, профили `reconcile` и `reconcile_quick` (поля
`Profile.reconcile_*` — целиком в `meta.json`) и `Bench.run_reconcile`
по решениям 1–3, 7–10, 13:
- S3 запускается у профилей загрузок и сверки;
@@ -247,13 +247,13 @@ Evidence и метка — только с закоммиченного кода
- строка хода на каждый проход.
Проверка — задача 6.7.
- [ ] 6.6 `Makefile`: цели `bench_reconcile [RECONCILE_LABEL=…]` и
- [x] 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` на дереве (шумный хост допустим).
- [x] 6.7 `make bench_reconcile_quick` на дереве (шумный хост допустим).
Проверка:
- код 0, все виды проходов;
- `found` равен внесённому;
@@ -264,14 +264,14 @@ Evidence и метка — только с закоммиченного кода
`mtusi-messenger:bench*`, которые профиль снимает сам).
Записать время и итог в `PLAN.md` (решения apply).
- [ ] 6.8 Регресс `bench/` после правок старта стенда: `make
- [x] 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) по
- [x] 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»;
@@ -284,7 +284,7 @@ Evidence и метка — только с закоммиченного кода
## 8. Правила и документы
- [ ] 8.1 Правила:
- [x] 8.1 Правила:
- `bench.md` — раздел «Профиль сверки (`reconcile`)» и строка таблицы
инструментов. Исключения границы: наполнение данных стенда `\copy`,
загрузчик в контейнере, метрики шлюза на loopback, разовые проходы
@@ -300,7 +300,7 @@ Evidence и метка — только с закоммиченного кода
- `dto.md` — enum и поля DTO.
Проверка: правила не противоречат design и дельтам.
- [ ] 8.2 AGENTS.md:
- [x] 8.2 AGENTS.md:
- абзац о лабе — change `track2-reconcile-cost`;
- таблица команд: `bench_reconcile`, `bench_reconcile_quick`, аргументы
`make reconcile`, `reconcile-signal --pace`;
@@ -311,10 +311,10 @@ Evidence и метка — только с закоммиченного кода
ранний отказ.
Проверка: все пути в AGENTS.md существуют.
- [ ] 8.3 `PLAN.md`, раздел `### track2-reconcile-cost` — решения apply
- [x] 8.3 `PLAN.md`, раздел `### track2-reconcile-cost` — решения apply
(«Решения») и вопросы, если появятся. Проверка: раздел есть, ссылки на
design.
- [ ] 8.4 `make lint`, `make check`, `make validate
- [x] 8.4 `make lint`, `make check`, `make validate
PYTHON=.venv/bin/python`, `openspec validate track2-reconcile-cost
--strict`. Проверка: все — код 0.