Files
mtusi2026lab4/openspec/changes/track2-reconciler/design.md
T
2026-10-22 21:04:01 +03:00

75 KiB
Raw Blame History

Design

Context

Мотивация — proposal.md, раздел Why. Требования — specs/.

Код

Состояние после upload-memory (5f4b9ff):

  • Уборщик. python -m src.cleaner [--once] (src/cleaner/main.py):

    • свой engine (пул 1) и клиент S3 с ключами пользователя cleaner;
    • цикл «проход → ожидание [cleaner] interval_seconds или сигнала», проверка grace > B = 17 с при старте;
    • коды 0/1/2.

    Проход — AttachmentCleanupService.clean_stale_pending: кандидаты keyset по частичному индексу, каждая строка в два шага под FOR UPDATE SKIP LOCKED — пометка, затем объект и строка одной транзакцией. Объект без строки и строку ready без объекта он не ищет.

  • Права S3 уборщика (infra/s3/bootstrap.sh, политика cleaner-objects): только s3:GetObject и s3:DeleteObject на <bucket>/*. Bootstrap и make s3_check проверяют, что список объектов ключом уборщика — 403. Спек object-storage («Ограниченные учётные данные уборщика») прямо запрещает ему список.

  • Клиент S3 (ObjectStorage) умеет put, head, open, delete, списка у него нет. _call всегда передаёт Key. Удалённый bucket у HEAD неотличим от отсутствующего ключа, правило — PLAN.md, s3-storage, вопрос 4.

  • Скачивание (AttachmentService.open_content): нет объекта или другой размер — error «Attachment content is missing» / «…size differs» и 500 (AttachmentContentMissing). Строка не меняется.

  • Схема attachments:

    • status IN ('pending', 'ready');
    • уникальный object_key — индекс uq_attachments_object_key;
    • частичный индекс pending;
    • CHECK updated_at >= created_at.

    Колонки пометки нет. Чтение и вставка перечисляют свои колонки (_ATTACHMENT_COLUMNS), поэтому новая колонка прежнему коду не мешает.

  • Тесты. Стенд отказов запускает уборщика с grace 20 с и интервалом 1 с. Hook умеет attachment-ids, object-ids (fs.tree), fail-attachments …, kill-api / start-api. Сверка покрытия требует тест или исключение для каждого сценария storage-consistency.

Пробы (2026-10-22, scratchpad, проект compose rcprobe)

Стенд пробы:

  • SeaweedFS тем же образом и аргументами, что s3, данные на tmpfs;
  • PostgreSQL 18.6 на tmpfs;
  • клиент botocore в образе mtusi-messenger:lab4;
  • bootstrap — сам infra/s3/bootstrap.sh проекта (read-only).

Volumes не создавались. Проект удалён, список volumes и сетей совпал с исходным (155 и 17).

Проверка Результат
Ключ уборщика с текущей политикой: список bucket, с префиксом и без, v1 и v2, HEAD bucket 403 AccessDenied; HEAD отсутствующего ключа — 404, GET — NoSuchKey
s3:ListBucket на arn:aws:s3:::messenger список своего bucket — 200, чужого — 403, HEAD bucket — 200, запись — 403
s3:ListBucket с Condition: StringLike s3:prefix messenger/attachments/* префикс messenger/attachments/ — 200, весь bucket и test_messenger/ — 403, HEAD bucket — 403, чужой bucket — 403. Условие SeaweedFS 4.48 соблюдает. Постраничный список под этим условием (3 страницы по 1000) — полный
s3:ListBucket только на ресурсе <bucket>/* списка нет (403), как в AWS
ListObjectsV2, 2 503 и 20 003 ключа под префиксом, MaxKeys 1000 3 и 21 страница, 0,31 с и ~2,0 с (~0,1 мс на ключ); LastModified с точностью до секунды, UTC; Size, ETag; токен продолжения — последний ключ открытым текстом
Порядок списка на соседях aaa/…, aaa-x, aaa.y/…, aaa0 порядок обхода каталогов: aaa/original, aaa/zzz, затем aaa-x. Это не порядок байтов: в нём aaa-x < aaa.y/… < aaa/…. Страницы по одному ключу совпали с одной страницей без пропусков и повторов
weed shell fs.rm объекта в /buckets/… HEAD — 404, в списке объекта нет, пустой каталог <id>/ в список не попадает
bucket удалён (s3.bucket.delete) список с префиксом — 404 NoSuchBucket, GET — NoSuchBucket, HEAD объекта — 404, как отсутствующий ключ
PostgreSQL, 21 000 строк (20 000 ready), общий план ALTER TABLE … ADD COLUMN lost_at timestamptz — 0,36 мс (только каталог). Страница 1000 ключей object_key = ANY($1) OR id = ANY($2) — Bitmap OR двух индексов, 6–7 мс: часть по uq_attachments_object_key — 5,6–6,2 мс (сравнение текста), часть по pk_attachments — 0,3–0,4 мс; один object_key = ANY — 6 мс. Обход ready keyset по id (status, lost_at, updated_at — фильтр) — Index Scan pk_attachments, 1000 строк за 0,4–0,6 мс

Запись KNOWN_ISSUES.md о bootstrap после удаления bucket

Воспроизведена на пробе и объяснена: дело в слотах томов, а не в повторном имени bucket.

Стенд Слотов томов После s3.bucket.delete и повторного bootstrap
tmpfs 4 ГБ 3 из 3 заняты «bucket created», затем «FAILED: api key wait (code 500)» дважды подряд. В журнале S3 — «No writable volumes and no free volumes left for collection:messenger»
tmpfs 16 ГБ 15 «bucket created», проверки прошли за 2 с

Почему так:

  • сервер запущен с -volume.max=0, и число слотов считается по свободному месту / 1 ГиБ;
  • удаление bucket удаляет томá его коллекции, но на маленьком диске слоты занимают тома коллекции по умолчанию (журналы filer);
  • новых томов для messenger выделить некуда.

У рабочего стенда volume на диске ВМ: 417 слотов, 403 свободны (weed shell volume.list, только чтение). Там удаление bucket и повтор bootstrap этим не падают. Решение 14.

Рабочий стенд перед change

Только чтение: 2 019 строк ready, 2 019 файлов original (fs.tree), строк ready без объекта и объектов без строки — 0, pending — 0.

Goals / Non-Goals

Goals:

  • Пункт трека 2 о reconciler (PLAN.md, этап 5): обе стороны, dry-run, --apply, повтор = 0, стресс с проверкой SHA-256.
  • Ни при каком порядке действий сверка не удаляет подтверждённое, используемое и свежее (гипотеза 5).
  • Остаточные риски upload-consistency закрыты автоматически. PUT-зомби убирает плановая сверка. Строку ready без объекта она помечает, и API отвечает по контракту, а не 500.
  • Смешанные версии при make rolling_update не хуже, чем до change.

Non-Goals:

  • Стоимость обхода, стратегии и ограничение скорости — track2-reconcile-cost (решение 13).
  • Восстановление байтов потерянного оригинала: их нет нигде.
  • Сверка других префиксов bucket (test_<db>/, .s3-check/) и чужих баз.
  • Новые статусы вложения. Контракт лабы 4 знает только ready.
  • Исправление записи KNOWN_ISSUES.md о bootstrap: reconciler bucket не создаёт (решение 14).

Decisions

1. Сверка — часть уборщика

Пакет src/cleaner/ и сервис compose cleaner вырастают в reconciler, как и задумано (PLAN.md, решение 7; design upload-consistency, решение 12):

  • python -m src.cleaner (сервис) — прежний цикл уборки, плюс плановая сверка (решение 9);
  • python -m src.cleaner --once — один проход уборки, как раньше;
  • python -m src.cleaner reconcile [--apply] [--max-changes N] — разовая сверка, по умолчанию dry-run. В compose — docker compose run --rm --no-deps cleaner reconcile … (точка входа уже python -m src.cleaner). Цель Makefile — make reconcile [APPLY=1] [MAX_CHANGES=N];
  • сервис AttachmentReconcileService(db_scope, storage) (src/core/services/attachment_reconcile.py), метод reconcile(*, older_than, apply, max_changes, page_size, batch_size, stop_requested). Зависшие загрузки он отдаёт AttachmentCleanupService (решение 7).

Как уборщик и сверка не мешают друг другу на строках pending:

  • внутри процесса проходы идут по очереди, одновременно не бывают;
  • между процессами (сервис и разовый run) сверка трогает строку pending только процедурой уборщика — тот же FOR UPDATE SKIP LOCKED и пометка;
  • объект строки pending правило «объект без метаданных» не видит: строка на него ссылается;
  • пометку потерянного оригинала получает только строка ready, а её уборщик не выбирает никогда;
  • все действия безопасно повторять, поэтому и две сверки разом ничего не ломают: удаление объекта и условный UPDATE идемпотентны.

Альтернатива: отдельная точка входа python -m src.reconciler, свой сервис и пользователь S3 reconciler. Отвергнута:

  • два процесса с доступом к одной базе, ещё два секрета, пользователь в bootstrap и строки make s3_check — ради разделения, которое почти ничего не даёт. У уборщика и так есть ключи всех объектов в БД, чтение и удаление любого объекта bucket. Список по префиксу своей базы (решение 2) добавляет к этому мало;
  • плановой сверке всё равно нужен долгоживущий процесс, а он уже есть.

Альтернатива: только ручная сверка, без плановой. Отвергнута: PUT-зомби жил бы до ручного запуска, и остаточный риск upload-consistency остался бы «навсегда» (решение 9). Альтернатива: фоновая задача реплик API. Запрещена (AGENTS.md). Альтернатива: lifecycle-правила S3. Отвергнуты: S3 не знает строк БД.

2. Права S3: список по префиксу вложений своей базы

Политика cleaner-objects получает второй оператор (проба — Context):

{"Effect": "Allow", "Action": ["s3:ListBucket"],
 "Resource": ["arn:aws:s3:::<bucket>"],
 "Condition": {"StringLike": {"s3:prefix": ["<база>/attachments/*"]}}}

Чтение и удаление на <bucket>/* — как были.

  • Префикс bootstrap получает в S3_CLEANER_LIST_PREFIX: ${POSTGRES_DB:?…}/attachments/ (окружение s3-bootstrap в docker-compose.yml). Это не секрет. Скрипт проверяет его по ^[a-z0-9_]+/attachments/$ и подставляет в JSON только проверенное значение. На стенде отказов и в bench/ (POSTGRES_DB=bench) префикс берётся тем же путём. Уборщику его не передают: свой префикс он строит из settings.database.name, как ключи объектов.
  • Проверки apply:
    • ключ уборщика получает 200 на список с префиксом;
    • 403 на список всего bucket — так же, как сейчас «cleaner key list is not denied».
  • Режим check (make s3_check), строки ключа уборщика:
    • «cleaner key list attachments prefix» — 200;
    • «cleaner key list objects» без префикса — 403, как было;
    • «cleaner key list other prefix» (.s3-check/) — 403;
    • «cleaner key list other bucket» — 403, как было.
  • Порядок обновления. Bootstrap только расширяет права и у API ничего не забирает (balancer.md). Новый уборщик со старой политикой получает AccessDenied на списке: проход сверки прерван, error «Object storage denied access», уборка работает. Поэтому вперёд — сначала docker compose up -d s3-bootstrap (решение 6).

Альтернатива: s3:ListBucket без условия. Отвергнута: уборщик видел бы ключи других баз (test_<db>/) и проверочные объекты, а сверке они не нужны. Альтернатива: s3:ListBucket на ресурсе <bucket>/*. По пробе списка не даёт. Альтернатива: сузить по префиксу и чтение с удалением. Отложена: проверки bootstrap удаляют ключом уборщика свои объекты под .s3-bootstrap/ и .s3-check/, их пришлось бы переделать. Ключи объектов уборщик и так берёт из БД своей базы.

3. Классы и проход сверки

Классы — спек storage-consistency, «Сверка bucket и БД». Порог older_than = utcnow() − [cleaner] pending_grace_seconds один на проход, по часам приложения, как у уборщика. Проход:

  1. S3 → БД. Страницы ListObjectsV2 по префиксу <база>/attachments/ ([reconciler] page_size, до 1000).
    • Ключ вида <база>/attachments/<uuid в нижнем регистре>/original (attachment_object_repo.parse_original_key) даёт id. Остальные ключи — «нестандартные».
    • На страницу — одно выражение к БД: id = ANY(:ids) OR object_key = ANY(:keys). Здесь ids — из стандартных ключей, keys — только нестандартные, обычно их нет. По пробе выборка по id в 15 раз дешевле выборки по тексту ключа.
    • Классификация без новых вызовов S3:
      • строка id с тем же ключом. pending — пропуск, это дело уборщика. ready без пометки: размер равен — порядок; другой — кандидат «другой размер», если строка старше порога, иначе «свежая». ready с пометкой: размер равен — кандидат «оригинал вернулся», иначе «уже помечено»;
      • строка id с другим ключом — «чужой объект»;
      • строки нет: LastModified раньше порога — кандидат «объект без метаданных», иначе «свежий объект»;
      • нестандартный ключ — строка с таким object_key есть: как у строки выше, иначе «чужой объект».
    • Каждый ключ попадает в множество seen.
  2. БД → S3. Keyset по id по всем строкам ready ([reconciler] page_size строк, Index Scan pk_attachments — проба).
    • Строка без пометки старше порога, ключа которой нет в seen, — кандидат «метаданные без объекта».
    • Моложе порога — «свежая».
    • С пометкой — «уже помечено», если оригинал не вернулся на шаге 1.
  3. Зависшие загрузки — решение 7.
  4. Перепроверка каждого кандидата непосредственно перед решением, в обоих режимах (решение 4).
  5. Предел изменений, затем действия, если --apply (решения 4 и 8).

Действия начинаются, только когда классификация закончена. Отказ хранилища на шагах 1–4 прерывает проход без единого изменения.

Почему множество, а не слияние двух отсортированных потоков. Порядок списка SeaweedFS — обход каталогов, а не порядок байтов (проба). Слияние с ORDER BY object_key COLLATE "C" на нестандартных ключах разошлось бы и дало бы ложные расхождения в обе стороны. Цена множества — память O(N): ~150 байт на ключ, при 100 тыс. объектов ~15 МБ при лимите уборщика 256 МБ. Замер — track2-reconcile-cost.

Почему гонка двух снимков (списка и строк) не даёт ложных расхождений:

  • объект без метаданных. API пишет строку до PUT (порядок записи attachments). Если объект попал в список, строка его загрузки уже зафиксирована и видна выборке, которая идёт после списка. Её нет, только если её убрал уборщик, — тогда объект и правда лишний;
  • метаданные без объекта. Строки моложе порога не проверяются. Строка старше порога стала ready раньше начала прохода, а её объект записан ещё раньше. Объекты ready никто, кроме сбоя, не удаляет, поэтому список их видит. Перепроверка HEAD отсекает и неполный ответ списка.

Альтернатива: HEAD на каждую строку вместо множества — стратегия следующего change (гипотеза 2). Альтернатива: временная таблица ключей в PostgreSQL и anti-join. Отвергнута: одна долгая транзакция противоречит idle_in_transaction_session_timeout и сроку шага 6 с.

4. Правила безопасности

Свойства — спек «Безопасность сверки». Как они держатся:

  • Что можно удалить. Удаление объекта — только у класса «объект без метаданных». Удаление строки — только у зависшей загрузки процедурой уборщика. Строки ready, используемые вложения (FK message_attachments и так не даст удалить строку) и объекты, на которые ссылается строка, не попадают ни в один удаляющий класс.

  • Свежее.

    • Объект: по LastModified S3 (часы ВМ, точность — секунда).
    • Строка ready: по updated_at — время перевода в ready.
    • Строка pending: по created_at, как у уборщика.

    Grace общий с уборщиком, его проверка границы живой загрузки (17 с) остаётся.

  • Перепроверка непосредственно перед решением:

    • объект без метаданных: выборка строки по id или по ключу (find_attachment_reference) — нет; HEAD — объект есть и старше порога. Перед самим DELETE выборка строки — ещё раз. Выборка страницы ищет стандартные ключи только по id (решение 3), поэтому строку с чужим id, которая ссылается на этот ключ (изменённые метаданные), находит именно перепроверка. Такой объект — «чужой объект», и он не удаляется;
    • метаданные без объекта и другой размер: get_attachment — ready, без пометки, тот же ключ; HEAD — объекта нет или размер другой;
    • оригинал вернулся: пометка на месте, HEAD — размер равен;
    • не подтвердилось — кандидат выбывает без записи о расхождении.
  • Bucket на месте. Перед подтверждением отсутствия объектов — список с префиксом и MaxKeys=1. HEAD bucket при условной политике — 403, проба. Удалённый bucket даёт NoSuchBucket, и проход прерван. Пустой, пересозданный bucket проходит проверку, но тогда кандидатов больше предела, и действует он.

  • Предел изменений. Число подтверждённых удалений объектов, пометок и снятий пометок сравнивается с max_changes (100 или аргумент). Больше — ни одного из этих изменений: error, код 3. Уборка зависших загрузок пределом не ограничена: уборщик делает её и без сверки. Предел защищает от сверки с «чужой» базой — пустой или восстановленной из старой копии, при живом bucket — и от пустого bucket.

  • Чужой объект — только отчёт и код 3. Удалять то, чего API не пишет, опасно: в лабе 5 под префиксом появятся варианты, а оператор мог положить копию сам.

  • Объект без метаданных удаляется в любой момент после порога. Объект зомби-загрузки удаляет и её компенсация. Два DELETE одного ключа безопасны.

Альтернатива: пометить строку перед действием, как уборщик. Не нужна: сверка не удаляет строк, а пометка потери — один условный UPDATE. Альтернатива: относительный предел (доля объектов). Отвергнут: на маленьком стенде он слишком мал, на большом слишком велик. Абсолютный предел понятнее оператору, и его легко поднять аргументом.

5. Потерянный оригинал и ответы API

  • Пометка — новая колонка attachments.lost_at timestamptz NULL: время, когда сверка подтвердила потерю. status и updated_at не меняются. Поэтому ответ метаданных прежний, error_code — null, как требует контракт для ready.

    • mark_lost: UPDATE … SET lost_at = :now WHERE id = :id AND status = 'ready' AND lost_at IS NULL AND object_key = :key RETURNING id;
    • clear_lost: … SET lost_at = NULL WHERE id = :id AND lost_at IS NOT NULL AND object_key = :key.
  • API (спек attachments, «Скачивание оригинала»):

    • скачивание помеченного — 404 not_found без обращения к S3, запись info «Attachment content is lost»;
    • непомеченного без объекта — 500, как было;
    • метаданные — 200, как было;
    • ссылка в новом сообщении — 201, как на любое ready.

    get_attachment и DTO получают lost_at. get_attachments и MessageService не меняются.

Почему так. В контракте лабы 4 у Attachment.status одно значение — ready (contracts/openapi.json), поэтому метаданные не могут сказать «потеряно». Для байтов контракт даёт «Отсутствующий вариант ready-объекта — 404» (contracts/README.md). 500 — «неожиданное исключение», а после сверки потеря уже ожидаема. Но прочтения возможны разные, поэтому это вопрос преподавателю (Open Questions; PLAN.md, ### track2-reconciler). Ответ «иначе» меняет только open_content и выборку вложений сообщения, спек attachments и тесты. Классы, правила и проход сверки от него не зависят.

Альтернатива: статус lost или failed в CHECK. Отвергнута:

  • контракт лабы 4 его не знает;
  • замена CHECK и прежние реплики упали бы на неизвестном значении enum при make rolling_update.

Альтернатива: удалить метаданные потерянного вложения, если оно не используется. Отвергнута: «строку без объекта не восстановить, reconciler её находит и помечает» (PLAN.md, «Трек 5»). Подтверждённое вложение не удаляется (гипотеза 5), а клиент с его id получил бы 404 на метаданные без объяснения. Альтернатива: отдельная таблица находок. Отвергнута: лишнее соединение в чтении вложения. Отчёт и так в журнале.

6. Схема и смешанные версии

Ревизия поверх 739b8f04d5fb:

  • первой строкой op.execute("SET LOCAL lock_timeout = '2s'") (migrations.md: ACCESS EXCLUSIVE на рабочую таблицу);
  • затем add_column('attachments', Column('lost_at', DateTime(timezone= True), nullable=True)) — только каталог, 0,36 мс на пробе;
  • downgrade — drop_column с тем же lock_timeout.

Модель — lost_at: Mapped[datetime | None]. Индекса нет: сверка просматривает все строки ready, API читает по id. CHECK «помечено только ready» не добавляется. Для существующей таблицы это NOT VALID или скан под блокировкой, а пометку и так ставит только условный UPDATE.

Смесь Что происходит По сравнению с «до change»
новая схема + прежние реплики (5f4b9ff) колонку не читают, у помеченного без объекта — 500 так же
новый уборщик + прежние реплики пометки ставятся, прежние реплики их не видят (500); объекты без строки удаляются безопасно — порядок записи прежних версий тот же, строка до PUT, с change attachments не хуже
прежний уборщик + новые реплики сверки нет, пометок нет так же
новый уборщик + прежняя политика S3 проход сверки прерван AccessDenied (error), уборка работает не хуже
новый уборщик на прежней схеме уборка работает; сверка падает на lost_at, error «Reconcile pass failed», процесс живёт не хуже; порядок ниже не даёт такой смеси

Порядок обновления:

  1. вперёд — docker compose up -d s3-bootstrap (политика со списком);
  2. затем make rolling_update (миграция, затем реплики);
  3. затем docker compose up -d --no-deps cleaner.

Откат — сначала уборщик (docker compose stop cleaner или прежний образ), потом make rolling_update COMMIT=<прежний> MIGRATE=0. Колонка и пометки остаются, прежнему коду они не мешают, а после возврата вперёд снова действуют.

7. Зависшие загрузки в сверке

  • Dry-run: кандидаты — attachment_repo.get_stale_pending страницами [cleaner] batch_size. Каждый — запись с id, ключом и возрастом. Ничего не меняется.
  • --apply: AttachmentCleanupService.clean_stale_pending(older_than=…, batch_size=…, stop_requested=…) — тот же код, что у сервиса уборки: пометка, затем объект и строка одной транзакцией под блокировкой. Число убранных — в итог сверки.
  • Порядок действий --apply: зависшие загрузки → объекты без метаданных → пометки → снятия пометок. Остановка (stop_requested) проверяется между действиями.

Альтернатива: сверка зависшие загрузки только называет. Отвергнута: без работающего уборщика --apply не довёл бы стенд до «повтор = 0», а общий код ничего не стоит.

8. Отчёт, журнал и коды выхода

  • DTO (dto.md):

    • ReconcileFindingDTO: kind, object_key, attachment_id, age_seconds, size_bytes, stored_size;
    • ReconcilePassDTO: apply, listed_objects, checked_rows, found и fixed по классам, fresh_objects, fresh_rows, lost_known, refused, interrupted_by, duration_ms.

    ReconcileFinding — StrEnum в enums/attachment.py: orphan_object, missing_object, size_mismatch, stale_pending, restored_object, unknown_object. Строки репозитория — AttachmentFullDTO, у него новое поле lost_at со значением по умолчанию. Отдельный тип не нужен.

  • Журнал (дельта service-logging, модуль attachment_reconcile_service):

    • находка — warning «Found storage discrepancy»;
    • исправленная — info «Fixed storage discrepancy» с action (deleted_object, marked_lost, cleared_lost, removed_pending);
    • итог — «Finished reconcile pass» (info или warning);
    • предел — error «Reconcile changes exceed limit»;
    • отдельные записи — первые RECONCILE_FINDINGS_LOGGED_MAX (1000, constants.py), в итоге — сколько осталось без записи.
  • Отчёт разового прохода — те же JSON-записи в stdout. Отдельного формата нет: hook и драйвер разбирают записи Found / Fixed / Finished.

  • Коды разового прохода (спек): 0 / 3 / 1 / 2. Код 3 — и при чужом объекте: он требует внимания оператора, хотя сверка его не тронет. Прерванный сигналом разовый проход — 1, сервис — 0 (дельта graceful-shutdown).

9. Плановая сверка

  • В цикле сервиса после прохода уборки проверяется срок плановой сверки (loop.time() против следующего срока):

    • первая сверка — при старте;
    • следующая — через [reconciler] interval_seconds (3600 с) после конца предыдущей;
    • 0 — без плановой сверки.

    Это тот же reconcile(apply=True, max_changes=[reconciler] max_changes). Непредвиденная ошибка — error с traceback, процесс живёт, как у уборки.

  • Граница. Объект без метаданных живёт не дольше grace + интервал + проход: ~15 + 60 мин + секунды. Цена на рабочем стенде (2 тыс. объектов) — меньше секунды в час. При 100 тыс. — порядка минуты под лимитом 0,25 CPU: разбор XML списка botocore — Python. Замер и выбор интервала — track2-reconcile-cost.

  • Стенд отказов — RECONCILER__INTERVAL_SECONDS: "0" в failures.compose.yml. Иначе плановая сверка исправляла бы расхождения, которые тест внёс и ещё проверяет. Плановую сверку проверяет отдельный уборщик с интервалом 1 с (решение 11). bench/ уборщика не запускает. У описанного в bench.compose.yml уборщика — тоже 0: профиль сверки track2-reconcile-cost задаст интервал сам.

Альтернатива: плановая сверка только с dry-run. Отвергнута: зомби оставались бы до ручного --apply. Предел и перепроверки делают автоматическое исправление безопасным. Альтернатива: первая сверка через интервал после старта. Отвергнута: частые пересоздания уборщика (make run_docker, обновление) откладывали бы её бесконечно.

10. Настройки

Секция [reconciler] (класс Reconciler, дельта service-configuration):

  • interval_seconds — float, ≥ 0, 3600;
  • page_size — int, 1–1000, 1000;
  • max_changes — int, ≥ 1, 100.

Разовая подмена — RECONCILER__*. Grace — [cleaner] pending_grace_seconds, одна ручка «свежести» на всю согласованность. Его проверка при старте уже есть и действует и на reconcile. Запись «Started cleaner» называет три новых значения и режим — сервис, --once или reconcile с apply. Строки — в config_example.toml.

Альтернатива: свой grace_seconds у сверки. Отвергнута: две ручки «свежести» разошлись бы. Для объектов без строки граница B не нужна, но меньший grace ничего не даёт, кроме риска.

11. Внедрение ошибок и тесты отказов

Новые действия hook (fault_hook.py, только stdlib, ключи S3 hook не получает):

Действие Что делает
put-object <ключ> тело из stdin. docker exec -i <проект>-api python -c … — botocore образа с ключами API из окружения контейнера пишет объект мимо приложения. Ключ — только под <FAULT_DATABASE>/attachments/, символы [A-Za-z0-9._/-]
delete-object <ключ> weed shell fs.rm /buckets/<bucket>/<ключ> — мимо шлюза S3, с той же проверкой ключа
delete-row <id>, set-size <id> <байт>, age-row <id> <секунд> psql: удалить строку (неиспользуемого вложения), изменить size_bytes, сдвинуть created_at и updated_at назад вместе. CHECK и непомеченность pending сохраняются
lost-ids id строк с lost_at
fail-attachments mark <filename> новый режим: UPDATE, который ставит lost_at строке с этим filename, падает с 08006. Отдельный триггер BEFORE UPDATE OF lost_at, чтобы прежние режимы и их функция не зависели от новой колонки; clear-fail-attachments снимает и его
reconcile dry-run|apply [<предел>] docker compose -p … run --rm --no-deps -T cleaner reconcile [--apply] [--max-changes N]: печатает записи процесса и строку exit_code=<n>, код hook — 0
stop|start cleaner сервис уборщика стенда (start — up -d --wait --no-recreate)
run-cleaner <секунд> отдельный уборщик <проект>-cleaner-scheduled (run -d, RECONCILER__INTERVAL_SECONDS=1) на N секунд, затем docker stop и его журнал; run_failures.py убирает его вместе с остальными

Объекты нельзя состарить: LastModified ставит S3. Поэтому тест с объектом без метаданных ждёт G + 1 с. Строки состаривает age-row, и там ждать не нужно.

Тесты (маркер fault; G = 20 с — grace стенда):

Тест Сценарии Ход
test_reconcile_finds_and_fixes storage-consistency «Расхождения с обеих сторон найдены», «Исправление расхождений», «Повторная сверка»; attachments «Потерянный оригинал» with outage(stop cleaner) → вложения A (в сообщении), B, C → put-object O (стандартный ключ), delete-object A, delete-row B, set-size C, загрузка P с fail-attachments commit (строка pending и объект) → ждать G + 1 → dry-run: у своих ключей и id — свои классы, exit_code 3, списки строк, объектов и lost-ids прежние, A — 500 → apply: O и объект B убраны, у P нет ни строки, ни объекта, A и C в lost-ids, A — 404, метаданные A равны ответу загрузки → повтор dry-run: своих расхождений нет, код соответствует записям
test_reconcile_keeps_fresh_used_and_unknown «Свежие не тронуты», «Используемое вложение не удаляется», «Чужой объект не удаляется» U1 в сообщении — age-row и delete-object; чужой X (…/attachments/x-<uuid>) → ждать G + 1 → свежие: U2 с удалённым объектом и F (put-object) → apply: F и X на месте, U2 не помечено, U1 помечено, метаданные U1 — 200, история отдаёт U1, строк не убыло, X — «чужой», код 3 → уборка X и F через hook
test_reconcile_restored_original «Оригинал вернулся» R: age-row, delete-object, apply → помечено → put-object R теми же байтами → apply → пометки нет, байты — 200 с тем же SHA-256
test_reconcile_change_limit «Предел изменений» L1–L3: age-row, delete-object → apply с пределом 2: код 3, error называет число не меньше 3 и предел 2, lost-ids без L → apply с пределом 100 → помечены все три
test_reconcile_object_storage_stopped «S3 недоступен во время сверки» M: age-row, delete-object → with outage(stop s3): apply — код 1, M не помечено → после возврата apply помечает
test_reconcile_interrupted_by_database «Прерванная сверка доводится повтором» N1 (filename f), N2: age-row, delete-object → fail-attachments mark f → apply — код 1 → снять триггер → apply → оба помечены → dry-run без них
test_reconcile_under_load «Сверка под нагрузкой» внесены 2 объекта без строки и 2 потери (age-row); 4 потока ~G + 15 с загружают ~100 KiB PNG из шума и отправляют сообщения со свежими id; поток сверки — apply раз в 3 с. В конце: внесённые исправлены, каждое 201-вложение скачивается с тем же SHA-256, каждое сообщение отдаёт свои attachment_ids, новые lost-ids (разность до и после) — только внесённые
test_scheduled_reconcile «Плановая сверка без команды» S: age-row, delete-object → run-cleaner 6 → в журнале «Finished reconcile pass», S в lost-ids

Тесты фильтруют записи сверки по своим id и ключам. Остатки прежних тестов (их строки pending) могут попасть в отчёт и в код выхода, поэтому код сверяется с записями того же прохода, а не с числом. Уборщик стенда остановлен только в первом тесте и только на его окно (with outage). Новые тесты добавляют к make failure_checks около 2,5–3 мин.

Красный прогон до кода. Новые тесты против прежнего кода — 5f4b9ff, команды reconcile нет. Падают все восемь: hook возвращает код 2 команды и ошибку разбора аргументов. Это доказательство, что тесты проверяют новое поведение. Сверка покрытия: новые сценарии storage-consistency и attachments синхронизируются в основные спеки в apply, как в прежних changes (spec_coverage.py читает только openspec/specs/).

12. Драйвер и evidence

Драйвер скилла (stdlib, Python 3.9), только стенд с LB. Разовая сверка — docker compose run --rm --no-deps -e CLEANER__PENDING_GRACE_SECONDS=<g> cleaner reconcile …, как у upload-consistency.

  • reconcile-cycle → evidence/reconcile/cycle.md:

    1. исходный dry-run с grace по умолчанию: 0 расхождений, иначе код 2, «стенд не сведён — make reconcile»;
    2. синтетические участники и вложения через LB;
    3. расхождения:
      • объект без строки — docker compose exec -T api python -c … с ключами реплики;
      • удалённые объекты — weed shell fs.rm;
      • удалённая строка, изменённый размер — psql;
      • обрыв между объектом и фиксацией — временный триггер commit на уникальный filename рабочей базы, снимается в finally и в начале следующего прогона;
      • чужой объект;
    4. ожидание grace прогона (30 с), затем dry-run: таблица «класс → ключ → id → возраст», снимки строк и объектов до и после совпали;
    5. байты потерянного — 500;
    6. --apply: таблица исправлений; байты — 404, метаданные — 200; история отдаёт id;
    7. повтор: исправимых 0, остался чужой. Его удаление оператором — шаг драйвера, затем повтор — код 0. Свежий объект не тронут, а после grace удалён;
    8. возврат оригинала: «оригинал вернулся», байты — 200 с тем же SHA-256.

    Код 1 при любом расхождении. Токенов и секретов в выводе нет.

  • reconcile-stress → evidence/reconcile/stress.md:

    1. предусловие — dry-run с grace 20 с без расхождений (иначе код 2);
    2. внесённые расхождения;
    3. N клиентов M секунд загружают и отправляют через LB, поток сверки — --apply с grace 20 с раз в ~3 с;
    4. в конце — таблица: загрузки по кодам, сообщения, проходы и исправления по классам, скачивания с несовпавшим SHA-256 — 0, сообщения с недоступным вложением — 0, повтор — 0.

    Это проверка корректности: тихий хост не нужен, паспорт хоста не снимается.

  • Остальное evidence:

    • evidence/reconcile/service.md — запись о старте с параметрами сверки, плановая сверка при старте, docker compose stop cleaner во время сверки при pause s3 (время и код), отказ старта с RECONCILER__PAGE_SIZE=5000;
    • evidence/s3/cleaner-list.md — bootstrap с новой политикой, make s3_check со строками списка, окружение s3-bootstrap в docker compose config;
    • evidence/migrations/lost-at.md — ревизия с нуля, повтор, откат, снова upgrade, --sql с lock_timeout;
    • evidence/tests/ — make failure_checks, make student_test через LB, make test_isolated.

    Регресс: make bench_rollout_quick (замена e1161f7 → новая ревизия), bench_failover_quick, bench_restore_quick, bench_quick.

  • REPORT.md:

    • раздел «Сверка хранилищ (трек 2)» — классы, правила, предел, права S3, ответы API, вопрос преподавателю;
    • строки таблицы доказательств уровня «5»;
    • ограничения (Risks ниже);
    • ответ на вопрос защиты «PUT прошёл, COMMIT нет» дополняется: зомби убирает сверка.

13. Граница с track2-reconcile-cost

Здесь В track2-reconcile-cost
одна стратегия: страницы LIST + одно выражение к БД на страницу, множество ключей, HEAD — только перепроверка найденного --strategy head — HEAD на строку и выборка на объект (гипотеза 2)
поверхностная сверка: наличие и размер из LIST --deep [--sample N] — SHA-256 чтением объекта, класс «другой SHA-256» (гипотеза 3)
[reconciler] page_size, interval_seconds, max_changes ограничение скорости обхода и его влияние на p95 фоновой нагрузки (гипотеза 4); выбор интервала по замеру
в итоге прохода — listed_objects, checked_rows, duration_ms профиль reconcile стенда bench/: N = 10k / 100k мимо API, доли расхождений, k6, сэмплер, 3 повтора, A/A, графики (гипотеза 1)
стресс --apply под загрузками — корректность (гипотеза 5) выводы по гипотезам 1–5 и ограничения в REPORT.md

14. Запись KNOWN_ISSUES.md о bootstrap

Причина найдена (Context): слоты томов на маленьком диске, а не повторное имя bucket. Reconciler bucket не создаёт и не удаляет. На NoSuchBucket он прерывает проход без изменений, поэтому чинить запись этому change не нужно.

В apply запись переписывается:

  • причина;
  • условие — диск, на котором -volume.max=0 даёт мало слотов: tmpfs проб, а не volume стендов проекта;
  • проба на 16 ГБ;
  • предложение на будущее — -master.volumeSizeLimitMB меньше 1024 или явный -volume.max на маленьких дисках.

Запись остаётся открытой.

Risks / Trade-offs

  • [Источник истины — PostgreSQL: база из старой копии или пустая при живом bucket] → объекты новых вложений станут «объектами без метаданных», и до предела изменений сверка их удалит. По истине БД это верно. Опасно восстановление базы в живую (pg_restore поверх) при работающем уборщике: удалились бы объекты строк, которые ещё не восстановлены. Митигация:
    • предел 100;
    • grace по объекту на старые объекты не действует. Поэтому правило в REPORT.md и docker.md: на время восстановления базы уборщик останавливают (docker compose stop cleaner), после — сначала make reconcile (dry-run).
  • [Чужой объект живёт, пока его не удалит оператор] → код 3 и warning на каждом проходе плановой сверки — видно в журнале. Удалять непонятное опаснее.
  • [Повреждение того же размера не видно] → поверхностная сверка сравнивает только размер. SHA-256 — глубокая сверка следующего change. Скачивание отдаёт такие байты и сейчас: API сверяет только размер.
  • [Память O(N) на ключи списка] → ~15 МБ на 100 тыс. объектов при лимите уборщика 256 МБ. Замер — следующий change.
  • [Плановая сверка задерживает уборку зависших загрузок на время прохода] → на рабочем стенде — меньше секунды. На 100 тыс. — порядка минуты при grace 15 мин. Ограничение — в спеке и REPORT.md.
  • [Пометка по ложному «нет объекта»] при неполном списке S3 → HEAD перепроверяет каждый кандидат и проверяет bucket. Остаток — bucket пересоздан пустым или подменён между перепроверкой и UPDATE. Тогда пометка верна: объекта правда нет. Она снимается сама, если объект вернётся.
  • [Две сверки одновременно] — плановая и разовая → действия идемпотентны, отчёты могут разойтись в числах fixed. Блокировки нет: проходу пришлось бы держать соединение пула уборщика всё время.
  • [Часы] → LastModified — часы ВМ (S3), порог — часы контейнера уборщика, это одни часы. Точность LastModified — секунда, при grace 900 с это ничтожно. updated_at строк пишут реплики. Консольный API на macOS расходится на секунды — меньше grace.
  • [Ответ API для потерянного оригинала — трактовка контракта] → вопрос преподавателю. Ответ меняет одну ветку open_content, сценарий и тест.
  • [Старый образ уборщика после make rolling_update] → сверки нет, как до change. Порядок обновления — решение 6, строка в balancer.md.
  • [Тесты отказов дольше на ~3 мин] → объекты нельзя состарить, ждать grace (20 с) нужно только тестам объектов без метаданных. Остальные состаривают строки.

Migration Plan

  1. Hook, стенд отказов и тесты раньше кода; красный прогон на нынешнем коде (5f4b9ff).
  2. Настройки [reconciler], enum и DTO, константа предела записей.
  3. Модель и ревизия lost_at: с нуля, повтор, откат, снова upgrade, --sql.
  4. Клиент S3 (список, время объекта), repo, AttachmentService (404), сервис сверки, пакет src/cleaner/ (команда, плановая сверка, коды).
  5. Bootstrap (политика, префикс, проверки), compose (s3-bootstrap), config_example.toml, Makefile (reconcile), bench/.
  6. Sync дельт в основные спеки и правка Purpose storage-consistency («Сверку … добавят следующие changes» → сверка есть), полный make failure_checks.
  7. Драйвер, правила, AGENTS.md, KNOWN_ISSUES.md, PLAN.md; регресс; commit после подтверждения; evidence; REPORT.md.

На рабочем стенде — make run_docker: bootstrap обновит политику, migrate добавит колонку, реплики и уборщик пересоздаются. Без простоя — порядок решения 6. Первая плановая сверка — при старте нового уборщика. По Context расхождений на стенде нет, ожидается итог без находок.

Откат — по решению 6. Пометки остаются в колонке. Политика со списком прежнему уборщику не мешает.

Open Questions

  • Ответ API на потерянный оригинал — вопрос преподавателю (PLAN.md, ### track2-reconciler → «Вопросы», п. 1). Контракт лабы 4 знает только status=ready. Есть три близких правила: «Отсутствующий вариант ready-объекта — 404», «404 — объекта нет или он чужой», «Неожиданное исключение — 500». По умолчанию до ответа (решение 5):

    • метаданные — 200;
    • байты — 404 после пометки, 500 до неё;
    • ссылка — 201.

    Ответ меняет ветку open_content (и выборку вложений сообщения, если ссылку тоже запретить), сценарий attachments «Потерянный оригинал» и тест. Классы, правила безопасности, схема и задачи сверки не меняются.

Уточнения apply

Решения, принятые в /opsx:apply (2026-10-22) без вопроса пользователю: мелкие, по спекам и решениям выше.

  1. Ответ на потерянный оригинал — вариант (а) по поручению основной сессии: вопрос 1 PLAN.md открыт, сделано по умолчанию (решение 5).

  2. ReconcileAction — второй StrEnum рядом с ReconcileFinding: названия действий в записях «Fixed» (deleted_object, marked_lost, cleared_lost, removed_pending) — значения enum, а не литералы.

  3. ReconcilePassDTO сверх решения 8: remaining (сколько подтверждённых осталось — по нему код 0 / 3) и unlogged (сколько находок не записано из-за RECONCILE_FINDINGS_LOGGED_MAX). found и fixed — MappingProxyType: DTO frozen, dict в нём был бы изменяемым (dto.md).

  4. Шаг уборщика — публичный. AttachmentCleanupService._remove стал remove_stale_pending (поведение то же, clean_stale_pending зовёт его), и сверка с --apply убирает зависшие загрузки им по одной, а не clean_stale_pending целиком (решение 7): так у каждой убранной загрузки своя запись «Fixed … removed_pending» с id, как у остальных классов, а кандидаты — те же, что в dry-run.

  5. Какие записи у --apply. Исправленное — только info «Fixed», оставшееся (чужой объект, отказ по пределу, прерванный проход) — warning «Found» в конце прохода. Так требует сценарий service-logging «Журнал разового прохода» (в --apply — две записи info, а не четыре).

  6. Перепроверка и перед самим действием. Шаг 4 перепроверяет всех кандидатов в обоих режимах; с --apply каждое действие ещё раз проверяет своё условие непосредственно перед собой: объект без строки — find_attachment_reference, пометка и снятие пометки — HEAD и условный UPDATE; перед первой пометкой bucket проверяется ещё раз (probe_originals). Не подтвердилось на действии — находка выбывает без записи и не считается оставшейся.

  7. Свежий чужой объект — свежий. Грейс действует на все объекты списка, в том числе чужие ключи: «свежее не считается расхождением» (спек «Безопасность сверки»). Объект без LastModified считается свежим: удалять без доказанного возраста нельзя.

  8. Отказ после сигнала — остановка. Если вызов S3 или шаг с БД упал, когда сигнал уже пришёл (вызов ждал замороженный S3 до срока), interrupted_by — stop: этого ждёт сценарий graceful-shutdown «docker stop во время сверки». Причину отказа всё равно записал нижний слой (object_storage, database).

  9. 404 без тела у списка — отсутствующий bucket. Клиент переводит NoSuchKey / 404 у list_objects_v2 в «bucket is missing»: у списка «объекта нет» не бывает, а пустой список вместо ошибки сделал бы удалённый bucket «потерей всех оригиналов».

  10. Цикл сервиса. После прохода уборки — плановая сверка, если подошёл срок; пауза — меньшее из [cleaner] interval_seconds и времени до сверки. --once плановой сверки не делает (как раньше — один проход уборки).

  11. Проверка префикса bootstrap — case, а не grep -x: значение с переводом строки (x\n<база>/attachments/) grep -x пропустил бы по второй строке. Проверка — до любого шага в режимах apply и check. Список своего префикса в apply проверяется с ожиданием (wait_key 200): новая политика доходит до шлюза подпиской, как ключ.

  12. Ревизия 5c3e1f0a9b7d (2026_10_22_1200-…_added_attachments_lost_at.py). Проверка на временной базе rc_lost_at_probe рабочего PostgreSQL: с нуля — все 7 ревизий, повтор — без изменений, downgrade -1 и снова upgrade, \d attachments — lost_at timestamp with time zone, без значения по умолчанию; --sql 739b8f04d5fb:head — SET LOCAL lock_timeout = '2s' перед ALTER TABLE attachments ADD COLUMN lost_at TIMESTAMP WITH TIME ZONE.

  13. Планы (задача 4.3) — та же база, 21 000 строк (20 000 ready), VACUUM (ANALYZE), общий план (plan_cache_mode = force_generic_plan, PREPARE текста, который рендерит SQLAlchemy для asyncpg):

    • страница 1000 id, пустой keys — Bitmap Heap Scan ← BitmapOr (pk_attachments, 1000 строк, 0,41 мс; uq_attachments_object_key — 0 поисков), 1,5 мс, 652 буфера;
    • 1000 id и 2 нестандартных ключа — тот же BitmapOr, по ключам — 1 поиск, 0,6 мс;
    • keyset ready по id с середины, 1000 строк — Index Scan pk_attachments (id > $2, статус — фильтр), 0,57 мс.

    Параметры — массивы (= ANY($1::UUID[])), а не список IN: план не зависит от длины страницы.

  14. Проба клиента и bootstrap (задачи 4.4 и 8.1) — проект rcapply (SeaweedFS проекта на tmpfs 16 ГБ, синтетические секреты, bootstrap и docker-compose.yml проекта): bootstrap трижды — код 0 (bucket и пользователи созданы, затем «exists»); префиксы messenger/, *, messenger/attachments/x, пустой, a/b/attachments/, с переводом строки, Messenger/attachments/ — «FAILED: cleaner list prefix» и код 1; check — «cleaner key list attachments prefix» 200, «… objects», «… other prefix», «… other bucket» 403. Клиентом проекта ключом уборщика: 2 504 ключа под префиксом — 3 страницы по 1000 за 0,29 с, все ключи, у каждого LastModified; весь bucket, префикс messenger/other/ и test_messenger/attachments/ — ObjectStorageUnavailable («denied access», AccessDenied); после s3.bucket.delete список и probe_originals — ObjectStorageUnavailable («bucket is missing», NoSuchBucket), а не пустая страница. Проект удалён, список volumes совпал с исходным (155).

  15. Hook: start cleaner — docker start контейнера. docker compose start cleaner проверяет зависимости сервиса, а migrate стенд запускает run --rm — его контейнера нет («cleaner is missing dependency migrate»; найдено первым прогоном новых тестов на новом коде).

  16. Фикстура stand(..., stdin=байты) — тело put-object; subprocess фикстуры — в байтовом режиме (stdout и stderr декодируются сами), прежние действия stdin не читают.

  17. Метаданные состаренных строк. age-row сдвигает created_at и updated_at, set-size меняет size_bytes — это поля ответа API. Тесты сравнивают метаданные помеченных с ответом загрузки без полей, которые изменил сам hook (assert_lost_content(aged=True), у C — размер из set-size); пометка сверки полей ответа не меняет — это проверяет вложение A без таких правок. Первый прогон новых тестов на новом коде падал именно на этом (дефект теста: ожидание противоречило его же внесённому изменению).

  18. Драйвер на рабочем стенде — только после 12.1. reconcile-cycle и reconcile-stress нужны колонка lost_at, новая политика S3 уборщика и образ с командой reconcile; до docker compose up -d s3-bootstrap и make rolling_update сверка на рабочем стенде падает (AccessDenied на списке, нет колонки). Рабочий стенд в apply не перестраивается (поручение основной сессии), поэтому проверка драйвера в задачах 10.1–10.2 — на временном полном стенде (проект compose с LB, своими хранилищами на tmpfs и портами); на рабочем — в группе 12.

Решения правок по /opsx:verify (2026-10-22, группа 13 tasks):

  1. Ключ строки вне префикса вложений — чужой объект (W2). Строка ready старше порога, ключа которой нет в списке, раньше была кандидатом «метаданные без объекта», и перепроверка делала HEAD по её ключу — в том числе <другая база>/… или <база>/elsewhere/…. Это противоречило абзацу спека «Объекты других баз и ключи вне префикса … MUST NOT читать». Реальный случай — база, восстановленная под другим именем: её строки ведут к объектам исходной базы. Теперь такая строка (и зависшая загрузка с таким ключом — её уборка удалила бы объект по этому ключу) — unknown_object без HEAD, без пометки и без уборки, код 3; HEAD, пометка, снятие пометки и удаление объекта ещё раз проверяют префикс (attachment_object_repo.is_own_key). Новый класс не заведён: «чужой объект» уже значит «требует оператора, сверка не меняет» — определение класса в спеке дополнено. Сервис уборки (clean_stale_pending) зависшую загрузку с чужим ключом по-прежнему убирает вместе с объектом по её ключу — это поведение upload-consistency, а не сверки; запись в KNOWN_ISSUES.md.
  2. Сигнал — перед каждым вызовом хранилища (S1). Раньше между проверками stop_requested() бывало два вызова подряд (страница списка → выборка БД, get_attachment → HEAD, HEAD → mark_lost / clear_lost, ссылки → DELETE, шаг БД → probe_originals), и при деградации S3 и PostgreSQL остановка ждала до ~11 с при stop_grace_period 10 с. Теперь _check_stop стоит перед каждым вызовом, и остановка ждёт не больше одного: S3 ≤ [s3] timeout_seconds (5 с), шаг с БД ≤ его срока (6 с). Теста нет: окно «первый вызов удался после долгого ожидания, а второй завис» по HTTP детерминированно не воспроизвести; прежний сценарий «docker stop во время сверки» (один зависший вызов) остаётся в evidence, код 1 разового прохода — п. 23.
  3. Ранний отказ по пределу — не в этом change (S4). Мысль: в --apply прекращать перепроверку классов под пределом, как только подтверждённых больше max_changes. Это ломает два инварианта: отчёт называет каждое расхождение (спек «Сверка bucket и БД») — неперепроверенные кандидаты не подтверждены и в отчёт не попали бы; ошибка предела называет число изменений — оно стало бы нижней границей. Поэтому не сделано. Цена при N ≫ предела — SELECT + HEAD на кандидата, ~1–3 мс; при 10 тыс. расхождений — десятки секунд, пока уборка ждёт. Варианты (перепроверка после решения о пределе с отчётом «кандидаты, не перепроверены», отдельный счётчик в итоге, порог «подтверждено > предела» только для плановой сверки) и замер — track2-reconcile-cost (PLAN.md).
  4. Тесты W1 и красные прогоны группы 13. Hook set-key <id> <ключ> меняет только object_key строки (psql, ключ под <FAULT_DATABASE>/, в том числе вне attachments/ — для W2). Ветки W1 в коде были верны: test_reconcile_keeps_referenced_objects и test_reconcile_limit_keeps_cleanup на коде a6071da — зелёные, а на временных регрессиях (_recheck_orphan без find_attachment_reference; _act пропускает при отказе по пределу и зависшие) — 2 failed: объект <Z>/original, на который ссылается Y, стал orphan_object; зависшая загрузка не убрана. Регрессии убраны, git diff src/ после — пусто. test_reconcile_foreign_key_untouched на коде a6071da — 1 failed: готовая строка с ключом <база>/elsewhere/<id> — missing_object (HEAD чужого префикса и пометка в --apply), зависшая — stale_pending (уборка удалила бы объект по чужому ключу).
  5. Код 1 разового прохода по SIGTERM (S5) — driver.py reconcile-signal: на проекте compose из окружения (рабочий mtusi-lab4 — отказ, код 2) замораживает S3, запускает разовый reconcile --apply отдельным контейнером, после «Started cleaner» — docker stop; ждёт код 1, «Finished reconcile pass» с interrupted_by: stop, «Stopped cleaner» с exit_code 1 и остановку быстрее stop_grace_period; S3 размораживается в finally. Снимок — после commit, на временном стенде.