diff --git a/openspec/changes/complete-lab5-versioned-pipeline/.openspec.yaml b/openspec/changes/complete-lab5-versioned-pipeline/.openspec.yaml new file mode 100644 index 0000000..8a94d76 --- /dev/null +++ b/openspec/changes/complete-lab5-versioned-pipeline/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-06 diff --git a/openspec/changes/complete-lab5-versioned-pipeline/design.md b/openspec/changes/complete-lab5-versioned-pipeline/design.md new file mode 100644 index 0000000..e549b4d --- /dev/null +++ b/openspec/changes/complete-lab5-versioned-pipeline/design.md @@ -0,0 +1,26 @@ +## 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 после ready может быть убран при другой активной версии: следующий claim читает original; transient S3 read использует ограниченный retry. Исходные bytes остаются сохранены. Провал 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. diff --git a/openspec/changes/complete-lab5-versioned-pipeline/proposal.md b/openspec/changes/complete-lab5-versioned-pipeline/proposal.md new file mode 100644 index 0000000..e60e90d --- /dev/null +++ b/openspec/changes/complete-lab5-versioned-pipeline/proposal.md @@ -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. diff --git a/openspec/changes/complete-lab5-versioned-pipeline/specs/lab5-versioned-pipeline/spec.md b/openspec/changes/complete-lab5-versioned-pipeline/specs/lab5-versioned-pipeline/spec.md new file mode 100644 index 0000000..430c70c --- /dev/null +++ b/openspec/changes/complete-lab5-versioned-pipeline/specs/lab5-versioned-pipeline/spec.md @@ -0,0 +1,45 @@ +## 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** одна версия завершилась ошибкой, другая ещё обрабатывается +- **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, содержит реальные результаты и не удаляет данные предыдущих прогонов diff --git a/openspec/changes/complete-lab5-versioned-pipeline/tasks.md b/openspec/changes/complete-lab5-versioned-pipeline/tasks.md new file mode 100644 index 0000000..273381f --- /dev/null +++ b/openspec/changes/complete-lab5-versioned-pipeline/tasks.md @@ -0,0 +1,15 @@ +## 1. Предпосылки +- [x] 1.1 Подтвердить уровни 3/4 на SQLAlchemy отдельными циклами (grade3/NOTES.md, grade4/NOTES.md). +- [x] 1.2 Проверить существующие ограничения/Alembic: новой схемы не требуется; Context7 SQLAlchemy и FastStream проверены. + +## 2. Версии в attachments +- [ ] 2.1 Добавить команду/результат, handler и SQLAlchemy JobRepository с сериализацией постановки и безопасным failure нескольких версий. +- [ ] 2.2 Добавить recipe v1/v2 и передачу версии в отдельный render process. +- [ ] 2.3 Связать операторский CLI, аудит и DI; проверить конкурентность, reorder, старого держателя и ошибки собственными тестами. + +## 3. Доказательства +- [ ] 3.1 Усилить suite: принудительное v2→v1, snapshots/hashes, scoped S3 inventory, фактический SIGKILL; make track2. +- [ ] 3.2 make check/validate/lint/student-test, сборка и публичные smoke/persistence/failover/restore на финальном коде. +- [ ] 3.3 Полный level4 на финальном коде и три последовательных track2 с сырыми результатами. +- [ ] 3.4 Сохранить методику/гипотезу/сравнение/ограничения, синхронизировать specs, архивировать завершённый change после make lint. +- [ ] 3.5 Остановить свои стенды без удаления volumes и завершить с чистым деревом.