From dc9256baf9fd3b08ada06141b36282a612c0350a Mon Sep 17 00:00:00 2001 From: Artyom Date: Fri, 6 Nov 2026 12:17:32 +0300 Subject: [PATCH] Propose forwarding the lab 5 foundation as an openspec change --- .../.openspec.yaml | 2 + .../design.md | 28 +++++++++++ .../proposal.md | 29 +++++++++++ .../specs/lab2-persistent-storage/spec.md | 31 ++++++++++++ .../specs/lab4-storage-reconciler/spec.md | 37 ++++++++++++++ .../specs/lab5-versioned-pipeline/spec.md | 49 +++++++++++++++++++ .../tasks.md | 16 ++++++ 7 files changed, 192 insertions(+) create mode 100644 openspec/changes/forward-lab5-sqlalchemy-foundation/.openspec.yaml create mode 100644 openspec/changes/forward-lab5-sqlalchemy-foundation/design.md create mode 100644 openspec/changes/forward-lab5-sqlalchemy-foundation/proposal.md create mode 100644 openspec/changes/forward-lab5-sqlalchemy-foundation/specs/lab2-persistent-storage/spec.md create mode 100644 openspec/changes/forward-lab5-sqlalchemy-foundation/specs/lab4-storage-reconciler/spec.md create mode 100644 openspec/changes/forward-lab5-sqlalchemy-foundation/specs/lab5-versioned-pipeline/spec.md create mode 100644 openspec/changes/forward-lab5-sqlalchemy-foundation/tasks.md diff --git a/openspec/changes/forward-lab5-sqlalchemy-foundation/.openspec.yaml b/openspec/changes/forward-lab5-sqlalchemy-foundation/.openspec.yaml new file mode 100644 index 0000000..8a94d76 --- /dev/null +++ b/openspec/changes/forward-lab5-sqlalchemy-foundation/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-06 diff --git a/openspec/changes/forward-lab5-sqlalchemy-foundation/design.md b/openspec/changes/forward-lab5-sqlalchemy-foundation/design.md new file mode 100644 index 0000000..f94f396 --- /dev/null +++ b/openspec/changes/forward-lab5-sqlalchemy-foundation/design.md @@ -0,0 +1,28 @@ +## Context + +См. proposal.md. Единственный источник — immutable snapshot ЛР5 f88e9ba43cdfd7eb6a5a7ae5feb4247b4e820071, база diff 64d5c67. ЛР6 содержит собственные OTel-порты, instrumentations и незакоммиченную инфраструктуру. Источник не изменяется. + +## Goals / Non-Goals + +Сохранить бизнес-поведение и обновить основу без стирания OTel. Новые грейды, переработка наблюдаемости и нагрузочные измерения не входят в перенос. + +## Decisions + +1. Трёхстороннее слияние по файлам с разрешённым списком путей. Копирование поверх всего каталога отброшено: потеряло бы локальный OTel. За сохранение обоих наборов изменений платим ручным разрешением конфликтов. +2. Перенести SQLAlchemy 2.0.45 и Alembic 1.16.5 из snapshot без новой схемы поверх уже проверенной. Порты UoW сохраняются, адаптеры зон используют ORM/Core и async_sessionmaker; shared содержит только engine, базу моделей и общую UoW. Получаем единый транзакционный механизм, цена — ORM-mapping и контроль RETURNING. +3. Alembic принимает legacy-журнал только после проверки checksum и каталога схемы, под advisory lock. Миграции аддитивны; пользовательские строки и volumes не удаляются. Неизвестная схема останавливает мигратор. +4. FastStream/aio-pika и ручной ack остаются: успешный handler завершает COMMIT до ack. OTel observer и контекст отложенных событий сохраняются при слиянии, SQL client spans остаются через instrumentation asyncpg под SQLAlchemy. SDK после fork, batch/periodic exporters и выключение OTEL_SDK_DISABLED не меняются. +5. Compose сохраняет OTel WIP, non-root, secrets через файлы, healthcheck и лимиты. API 18086; остальные опубликованные порты 26000–26999. Только свой project mtusi2026lab6, без удаления volumes. Никакой остановки чужих контейнеров. + +## Risks / Trade-offs + +- Конфликты UoW и OTel → make lint/student-test, включая наблюдателей, HTTP spans и миграции. +- Старые данные → тесты legacy upgrade со строками, идемпотентности и отказа при drift. +- Общий Docker host → записать фон и условия; smoke и функциональные тесты не выдавать за нагрузочный эксперимент. +- REPORT/evidence остаются неизменными → результаты переноса и ограничения остаются в verification.md для отдельного отчётного этапа. + +## Migration Plan + +Сохранить WIP и контрольные суммы защищённых файлов; перенести diff; обновить lockfile; проверить check/lint/student-test. Поднять собственный стенд с включённым SDK, выполнить smoke и повторный migrate. Остановить свой стенд без удаления volumes. Откат приложения возможен предыдущим образом при сохранённых данных; автоматический downgrade с удалением таблиц не выполняется. + +Документация проверена через Context7: SQLAlchemy rel_2_0_45 (async_sessionmaker, pool) и Alembic rel_1_16_5 (async env, run_sync, stamp). diff --git a/openspec/changes/forward-lab5-sqlalchemy-foundation/proposal.md b/openspec/changes/forward-lab5-sqlalchemy-foundation/proposal.md new file mode 100644 index 0000000..d2fb682 --- /dev/null +++ b/openspec/changes/forward-lab5-sqlalchemy-foundation/proposal.md @@ -0,0 +1,29 @@ +## Why + +ЛР6 основана на устаревшем состоянии ЛР5: адаптеры ещё используют raw asyncpg, отсутствуют Alembic и поздние исправления надёжности. Перенос основы необходим для сохранения минимума ЛР1–5, указанного в уровне «3» README; сам уровень «3» ЛР6 этим изменением не заявляется. + +## What Changes + +- Перенести разрешённый diff `64d5c67..f88e9ba43cdfd7eb6a5a7ae5feb4247b4e820071` только из immutable snapshot ЛР5. +- Объединить SQLAlchemy/Alembic, исправления конкурентности, pipeline, reconciler, тесты и инфраструктуру с существующими механизмами OTel ЛР6. +- Сохранить схему и данные при принятии legacy-журнала миграций; неизвестная схема должна отклоняться. +- Сохранить неизменными нормативные файлы, REPORT и evidence. Проверки переноса записать в verification.md этого change для следующего этапа отчёта. + +## Capabilities + +### New Capabilities + +- `lab4-storage-reconciler`: унаследовать безопасную сверку PostgreSQL и S3. +- `lab5-versioned-pipeline`: унаследовать повторную обработку по версии pipeline. + +### Modified Capabilities + +- `lab2-persistent-storage`: переход на Alembic с проверяемым сохранением legacy-схемы и данных. + +## Impact + +Затрагиваются src, Alembic, собственные тесты, зависимости, Dockerfile, Compose, Makefile, свои скрипты/CI и OpenSpec. API остаётся 1.6.0. Порты ЛР6: API 18086, остальные 26000–26999. Проверки: make check/lint/student-test и smoke собственного стенда. Будущая строка REPORT: «Сохранение минимума ЛР1–5»; отчёт в этой фазе не редактируется. + +## Non-goals + +Реализация и доказательства грейдов 3/4/5 ЛР6, нагрузочные замеры, публикация и Telegram исключены. Сохраняются ограничения Out of scope из openspec/config.yaml. diff --git a/openspec/changes/forward-lab5-sqlalchemy-foundation/specs/lab2-persistent-storage/spec.md b/openspec/changes/forward-lab5-sqlalchemy-foundation/specs/lab2-persistent-storage/spec.md new file mode 100644 index 0000000..200c201 --- /dev/null +++ b/openspec/changes/forward-lab5-sqlalchemy-foundation/specs/lab2-persistent-storage/spec.md @@ -0,0 +1,31 @@ +## MODIFIED Requirements + +### Requirement: Версионируемые миграции + +Схема SHALL создаваться версионируемыми миграциями, каждая в своей транзакции. Одноразовый процесс `migrate` SHALL завершаться до старта API; одновременные запуски SHALL сериализоваться. Повторный запуск SHALL NOT менять данные. При переходе со старого SQL-журнала процесс SHALL проверить контрольные суммы и фактическую схему до принятия версии. Неизвестная или изменённая история SHALL останавливать запуск без изменения пользовательских данных. Аддитивные изменения SHALL сохранять совместимость с предыдущей версией приложения. Основание: обязательное постоянное хранение и сохранение lab1–lab4 в README. + +#### Scenario: Миграции с пустого volume + +- **WHEN** стенд запускается с пустой PostgreSQL +- **THEN** все миграции применяются по порядку, migrate завершается кодом 0 и запускается API + +#### Scenario: Повторный запуск + +- **WHEN** migrate повторно запускается на той же БД +- **THEN** он завершается кодом 0 без изменения пользовательских строк + +#### Scenario: Переход старого стенда ЛР5 + +- **WHEN** БД содержит проверенный SQL-журнал ЛР5, вложения, задания, outbox и варианты +- **THEN** переход сохраняет строки, ограничения, состояния и ссылки на объекты + +#### Scenario: Изменённая миграция + +- **WHEN** контрольная сумма SQL-журнала или фактическая схема не совпадает с ожидаемой +- **THEN** принятие истории завершается ошибкой без изменения данных и отметки версии + +#### Scenario: Реплики не мигрируют схему + +- **WHEN** стартует реплика API, relay или worker +- **THEN** только отдельный процесс migrate изменяет журнал миграций + diff --git a/openspec/changes/forward-lab5-sqlalchemy-foundation/specs/lab4-storage-reconciler/spec.md b/openspec/changes/forward-lab5-sqlalchemy-foundation/specs/lab4-storage-reconciler/spec.md new file mode 100644 index 0000000..f923595 --- /dev/null +++ b/openspec/changes/forward-lab5-sqlalchemy-foundation/specs/lab4-storage-reconciler/spec.md @@ -0,0 +1,37 @@ +## Purpose + +Сохраняет совместимость перенесённой из ЛР4 сверки PostgreSQL и S3 с ранее записанными объектами и ограничивает её область, чтобы не вмешиваться в асинхронную обработку ЛР5. Основание — сохранение предыдущего решения при переносе; не является заявкой на грейд ЛР5. + +## ADDED Requirements + +### Requirement: Ручная сверка legacy-объектов + +Одноразовый reconciler SHALL по умолчанию работать в dry-run над прежним префиксом `attachments/`, выдавая JSON со счётчиками расхождений. Apply SHALL сохранять свежие объекты и повторно проверять ссылку в БД перед удалением старого orphan. Одновременный второй проход SHALL завершаться с признаком skipped. + +#### Scenario: Dry-run без изменения данных + +- **WHEN** оператор запускает reconciler без apply для legacy-объектов +- **THEN** он возвращает JSON и не меняет строки или байты + +#### Scenario: Повторная проверка защищает объект + +- **WHEN** после листинга старого orphan появляется строка с его ключом +- **THEN** apply сохраняет объект + +### Requirement: Карантин сохраняет данные + +При подтверждённом расхождении готового legacy-вложения apply SHALL поместить метаданные в карантин без удаления строки и объекта. GET `/api/v1/attachments/{id}/content` SHALL возвращать 404 с ошибкой not_found для карантина, метаданные остаются доступны участнику. Снятие карантина SHALL требовать совпадения SHA-256 даже без deep. + +#### Scenario: Возвращены другие байты той же длины + +- **WHEN** объект в карантине заменён байтами прежнего размера, но другого SHA-256 +- **THEN** карантин остаётся и скачивание не разрешается + +### Requirement: Разделение со staging и pipeline + +Перенесённая сверка SHALL NOT обходить или удалять объекты из `staging/`, `originals/` и `variants/`. Этими префиксами управляет pipeline ЛР5 и его существующая уборка staging. + +#### Scenario: Готовое вложение ЛР5 вне legacy-префикса + +- **WHEN** у нового вложения оригинал и варианты опубликованы pipeline +- **THEN** legacy-сверка не считает их orphan и не изменяет их diff --git a/openspec/changes/forward-lab5-sqlalchemy-foundation/specs/lab5-versioned-pipeline/spec.md b/openspec/changes/forward-lab5-sqlalchemy-foundation/specs/lab5-versioned-pipeline/spec.md new file mode 100644 index 0000000..641cf94 --- /dev/null +++ b/openspec/changes/forward-lab5-sqlalchemy-foundation/specs/lab5-versioned-pipeline/spec.md @@ -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, содержит реальные результаты и не удаляет данные предыдущих прогонов diff --git a/openspec/changes/forward-lab5-sqlalchemy-foundation/tasks.md b/openspec/changes/forward-lab5-sqlalchemy-foundation/tasks.md new file mode 100644 index 0000000..593953d --- /dev/null +++ b/openspec/changes/forward-lab5-sqlalchemy-foundation/tasks.md @@ -0,0 +1,16 @@ +## 1. Основа до грейдов ЛР6 + +- [ ] 1.1 Зафиксировать источник, WIP и контрольные суммы защищённых файлов. +- [ ] 1.2 Перенести зависимости, платформу SQLAlchemy и Alembic с legacy adoption. +- [ ] 1.3 Перенести identity и собственные проверки зоны. +- [ ] 1.4 Перенести messaging и собственные проверки зоны. +- [ ] 1.5 Перенести attachments, reconciler, pipeline и собственные проверки зоны. +- [ ] 1.6 Объединить точки сборки и OTel-порты, сохранив ack после COMMIT. +- [ ] 1.7 Объединить Dockerfile, Compose, Makefile, свои скрипты/CI; сохранить OTel WIP и порты ЛР6. +- [ ] 1.8 Выполнить make check, make lint, make student-test и проверить отсутствие raw asyncpg адаптеров. + +## 2. Проверка и завершение переноса + +- [ ] 2.1 Поднять свой стенд, выполнить публичный smoke и повторный migrate; записать Docker-фон. +- [ ] 2.2 Остановить свои стенды без удаления постоянных volumes, сверить защищённые файлы. +- [ ] 2.3 Записать реальные результаты и ограничения в verification.md; синхронизировать specs и архивировать change.