Document verified lab 5 grades and archive the versioned pipeline

This commit is contained in:
Artyom
2026-11-06 12:11:44 +03:00
parent 9ba3076fa8
commit f88e9ba43c
94 changed files with 13926 additions and 4 deletions
@@ -0,0 +1,4 @@
schema: spec-driven
created: 2026-11-06
archived: 2026-11-06
lab: 5
@@ -0,0 +1,38 @@
## Context
PostgreSQL — источник истины, RabbitMQ с FastStream/aio-pika — at-least-once транспорт. Имеются уникальные jobs(attachment_id,pipeline_version), attachment_variants(attachment_id,pipeline_version,name), lease_token и условная публикация только большей версии. Нет оператора версии и различимых recipe.
## Goals / Non-Goals
Завершить трек 2 без изменения HTTP-контракта. Подтвердить отсутствие потери 202, дублей эффектов и перезаписи v2 результатом v1. Уровни 3/4 остаются действующими. Не менять shared и другие зоны, не переписывать готовые механизмы.
## Decisions
- ReprocessAttachment принадлежит attachments; AdminProvider связывает обработчик с AttachmentsUnitOfWork/JobRepository, Clock и IdGenerator. Команда reprocess принимает только 1/2; неизвестное вложение → not_found, pending/failed → conflict (failed обслуживает replay), существующая/опубликованная версия → noop, новая → queued. Ready всё время остаётся ready и доступна текущая опубликованная версия.
- Под блокировкой строки attachment проверяется уникальный индекс jobs_effect_key. Только отсутствующая версия получает job+outbox+аудит одной транзакцией. Это сериализует одновременные операторские команды ценой короткой row lock. SELECT существующего job не берёт его блокировку: нет инверсии lock job→attachment с worker. Уникальный индекс остаётся последним ограничением целостности. SQLAlchemy Core с bound parameters, AsyncSession/UoW. Схема и старые данные не меняются.
- Ошибка одной версии не должна ставить attachment в failed, пока другая версия queued/processing. После фиксации job failure берётся блокировка attachment и отдельным запросом проверяются активные jobs; сериализация двух одновременных failures позволяет последнему выставить failed. Ready не меняется. Цена — короткая дополнительная блокировка на редком пути ошибки.
- v1 сохраняет JPEG 85/WebP 80; v2 использует JPEG 90/WebP 85. Размеры, EXIF transpose, white alpha, metadata removal и max bytes/pixels/time/memory одинаковы. Ключ S3 содержит версию и digest: старый PUT не адресует объект новой версии, оригинал неизменен. Версии recipe после выпуска не редактируются; для нового recipe нужна новая версия.
- Worker: claim+COMMIT → read/PUT S3 → variants+условная publication+COMMIT → manual ack. Сбой до PUT восстанавливается lease/outbox, после PUT повтор пишет те же ключи, после COMMIT повтор становится noop. Relay: durable outbox → publish mandatory/persistent с confirm → mark published+COMMIT; потерянный confirm создаёт повтор. Это идемпотентный эффект, не exactly-once доставка.
- Staging нельзя убирать, пока у вложения есть queued/processing job: старый держатель мог захватить staging до публикации новой версии. Claim ready-вложения всегда читает неизменяемый original, даже если staging ещё существует. Блокировка attachment сериализует уборку и reprocess; новые версии больше не зависят от удаляемого staging. Провал v2 не скрывает уже готовую v1.
- Reorder доказывается принудительно: relay остановлен, вручную публикуется только v2, ожидается published=2, затем relay выпускает v1 и дубль v2. Stale after v2 сравнивает публичный снимок, SQL и реально отдаваемые bytes. Старый работник после нового покрывается конкурентным тестом.
- Suite инвентаризует S3 только по IDs этого запуска, проверяет отсутствие лишних объектов и наличие всех ожидаемых ключей. Старые volumes и DLQ не очищаются. Каждый crash фиксирует фактический контейнер; retention меняет возраст только своей синтетической строки.
## Method
Гипотеза: один эффект на (attachment_id,version,variant), published_version монотонна, ready не откатывается и все 202 сохраняются при заданных отказах. Контроль — smoke_pipeline без fault; воздействия — дубли до/после ready, reorder attempts/versions, crashes до эффекта/после S3/после COMMIT, SIGKILL, stale v1 после v2. Три независимых последовательных запуска с новыми synthetic IDs. Сырые JSON содержат SHA/UTC/снимки/инварианты; таблица сравнивает контроль и faults, версии и все повторы. Длительность сценария включает Docker restart/healthcheck и не является latency SLA.
## Risks / Trade-offs
Две фиксированные версии, один Docker host и один broker node не доказывают отказоустойчивость к потере диска/кластера. Наблюдаемые API состояния дискретны; SQL conditional update и конкурентные тесты дополняют выборку. Minor limits.py и legacy reconcile demo сохраняются. Отдельный агент пишет итоговый REPORT. Containers non-root/read-only, закреплённые версии, healthcheck, порты и ресурсы не меняются. Перед окончанием все свои стенды остановить без удаления volumes.
## Найденный обязательный отказ
Первый track2 (run1.json) выявил queued задание без claims и два сообщения в DLQ: duplicate_in_flight не достиг ready за 90 s. Повтор именно этого job_id воспроизводит DBAPIError; другой дубль проходит. Сохраняются оба результата, SQLSTATE добавляется в безопасный журнал для точного установления причины. До исправления и трёх новых успешных серий change не завершён.
Регрессия воспроизводится в чистом процессе с графом импортов worker: первый UPDATE ORM в этом графе импортов возвращает UUID job_id как attempt; INSERT job_events затем падает с SQLSTATE 22000. Все UPDATE jobs используют SQLAlchemy Core table, без ORM synchronize_session и дополнительного RETURNING PK. Схема/данные не меняются. Регрессионный тест запускает два конкурентных claim в отдельных холодных процессах с разными hash seeds; исходный вариант падает, исправленный обязан пройти. В журнале остаётся только класс ошибки и SQLSTATE, без параметров.
Третий повтор verified-run3.json обнаружил гонку уборки staging и старого worker: v2 готова, v1 получила ObjectMissingError вместо superseded. Это критичный провал обязательного reorder; прежние два PASS не считаются завершённой серией. Регрессия задерживает держателя до/после side effect, публикует v2, запускает cleanup и требует сохранить staging до окончания активного держателя. После исправления повторяются локальные, публичные проверки, уровень 4 и три новые серии.
## Проверенный результат
Финальный код 9ba3076fa8ba707de932e053fc22f455d83b3210: 508 собственных тестов PASS, 1 macOS RLIMIT_AS skip компенсирован Linux worker_limits; публичные smoke/persistence/failover PASS; полный level4 17/17 и 8 инвариантов; track2 три пригодных повтора 13/13 и 8 инвариантов каждый, 39 IDs/174 объекта. Сводка — qualified/RESULTS.md и summary.json в evidence/sqlalchemy-2026-11-06/track2. Прерванный инфраструктурой третий запуск исключён и повторён без повторения пригодных серий. Docker общий, фон описан в evidence; времена не являются изолированным benchmark. Свой project остановлен без удаления четырёх volumes. На защите демонстрируются queued при остановленном worker, crash COMMIT→ack и v2→v1 с неизменным опубликованным снимком.
@@ -0,0 +1,23 @@
## Why
README, оценка «5», трек 2 требует versioned pipeline и доказательство идемпотентности при duplicate/reorder/crash/stale job. Уровни 3/4 подтверждены, но CLI не имеет reprocess, renderer игнорирует pipeline_version, а сценарий reorder не гарантирует завершение v2 до v1.
## What Changes
Добавить явную операторскую постановку версии 1/2, два детерминированных recipe и сохранение опубликованного результата при работе другой версии. Автоматизировать сильный reorder, дубли и crashes с инвентаризацией объектов только синтетических вложений. Выполнить три последовательных повтора и подготовить методику, сырые данные, сравнение и ограничения для строки трека 2 будущего REPORT.
## Capabilities
### New Capabilities
- lab5-versioned-pipeline: явная постановка версии, монотонное опубликование и воспроизводимые инварианты при сбоях.
### Modified Capabilities
Нет: существующие требования и внешний API продолжают действовать.
## Impact
Только зона attachments: команда/обработчик, JobRepository, SQLAlchemy адаптер, Pillow renderer, admin entrypoint/DI, собственные тесты, suite/Makefile, evidence и OpenSpec. Поля версии, уникальные ключи и fencing уже есть в Alembic; новая схема не нужна. Нормативные файлы и REPORT не меняются.
## Non-goals
Out of scope из openspec/config.yaml: OTel/ЛР6, TLS/ЛР7, трек 1 и публикация. Не заявляется exactly-once доставка или производительность production.
@@ -0,0 +1,49 @@
## Purpose
Определяет наблюдаемые гарантии versioned pipeline и воспроизводимое доказательство идемпотентности для трека 2 оценки «5» README лабораторной 5.
## ADDED Requirements
### Requirement: Явная постановка версии
Оператор SHALL иметь команду reprocess с attachment-id и pipeline-version 1 или 2. Повтор той же версии SHALL возвращать noop без новой job или outbox. Для неизвестного вложения возвращается not_found, для pending/failed — conflict без изменения состояния; failed восстанавливается существующим replay. Успех queued SHALL означать durable job и outbox. Требование трассируется на README, трек 2.
#### Scenario: Одновременные операторские запросы
- **WHEN** несколько команд запрашивают версию 2 одного вложения
- **THEN** ровно одна получает queued, остальные noop; создаётся одна job версии 2 и одно намерение доставки
#### Scenario: Ошибочный запрос
- **WHEN** указана неподдерживаемая версия, неизвестный id или failed-вложение
- **THEN** новая работа не создаётся, оператор получает явную ошибку/результат отказа
### Requirement: Монотонная публикация различимых версий
Версии 1 и 2 SHALL давать детерминированные варианты с различимыми recipe при сохранении форматов/размеров контракта. API SHALL отдавать только опубликованную версию, published_version SHALL возрастать, а ready SHALL NOT откатываться. Работа или ошибка старой версии SHALL NOT перезаписывать новую. Ошибка одной версии SHALL NOT завершать всё вложение в failed, пока остаётся активная версия. Требование трассируется на README, трек 2 и contracts/attachment-states.md.
#### Scenario: Новая версия завершилась первой
- **WHEN** версия 2 достигла ready до доставки версии 1
- **THEN** последующая версия 1 не меняет опубликованные варианты; оригинал и байты версии 2 сохраняются
#### Scenario: Старый держатель завершился позже
- **WHEN** worker версии 1 задержан после записи объектов, а версия 2 опубликована
- **THEN** завершение версии 1 не перезаписывает опубликованный результат версии 2
#### Scenario: Уборка при активной версии
- **WHEN** новая версия уже готова, а старый worker задержан до или после side effect и запускается очистка staging
- **THEN** исходник активного worker сохраняется до его завершения; последующая обработка ready-вложения использует устойчивый опубликованный оригинал и не зависит от незавершённой уборки
#### Scenario: Ошибка при нескольких версиях
- **WHEN** одна версия завершилась ошибкой, другая ещё обрабатывается
- **THEN** вложение не становится failed до завершения оставшейся работы, а уже ready продолжает скачиваться
### Requirement: Воспроизводимые инварианты при отказах
Одна команда make track2 SHALL запускать контроль без отказа и автоматические duplicate, reorder, crash до/после эффекта, SIGKILL и stale job после версии 2. Результат SHALL включать UTC/SHA, фактические контейнеры, отсутствие потери подтверждённых 202, лишних эффектов и отката ready/версии, соответствие байтов метаданным и объектов собственных вложений ожидаемым ключам. Исследование SHALL содержать три последовательных повтора, сравнение, ограничения и объяснение at-least-once доставки. Требование трассируется на README, трек 2; унаследованные негативные сценарии остаются в спецификациях уровней 3/4.
#### Scenario: Повтор после эффекта
- **WHEN** worker падает после PUT либо после COMMIT до ack и получает ту же job снова
- **THEN** итоговое вложение доступно, лишнего набора вариантов нет, принятая job не потеряна
#### Scenario: Проверяемая серия
- **WHEN** три раза последовательно выполняется make track2 с разными output paths
- **THEN** каждый отчёт проверяет собственные принятые IDs, содержит реальные результаты и не удаляет данные предыдущих прогонов
@@ -0,0 +1,19 @@
## 1. Предпосылки
- [x] 1.1 Подтвердить уровни 3/4 на SQLAlchemy отдельными циклами (grade3/NOTES.md, grade4/NOTES.md).
- [x] 1.2 Проверить существующие ограничения/Alembic: новой схемы не требуется; Context7 SQLAlchemy и FastStream проверены.
## 2. Версии в attachments
- [x] 2.1 Добавить команду/результат, handler и SQLAlchemy JobRepository с сериализацией постановки и безопасным failure нескольких версий.
- [x] 2.2 Добавить recipe v1/v2 и передачу версии в отдельный render process.
- [x] 2.3 Связать операторский CLI, аудит и DI; проверить конкурентность, reorder, старого держателя и ошибки собственными тестами.
- [x] 2.4 Исправить доказанные критичные cold claim и cleanup race; подтвердить регрессиями до/после и финальной серией на 9ba3076.
## 3. Доказательства
- [x] 3.1 Усилить suite: принудительное v2→v1, snapshots/hashes, scoped S3 inventory, фактический SIGKILL; make track2.
- [x] 3.2 make check/validate/lint/student-test, сборка и публичные smoke/persistence/failover/restore на финальном коде.
- [x] 3.3 Полный level4 на финальном коде и три последовательных track2 с сырыми результатами.
- [x] 3.4 Сохранить методику/гипотезу/сравнение/ограничения, синхронизировать specs, архивировать завершённый change после make lint.
- [x] 3.5 Остановить свои стенды без удаления volumes и завершить с чистым деревом.
Финальные доказательства: evidence/sqlalchemy-2026-11-06/track2/qualified/RESULTS.md, summary.json, run1.json, run2.json, run3-retry.json, level4.json, shutdown.json. Interrupted run3.json исключён; его 10 IDs восстановились без manual replay. Код проверок: 9ba3076fa8ba707de932e053fc22f455d83b3210. Финальный коммит архивирует только спецификацию/результаты; код после квалификации не менялся.