Propose forwarding the lab 5 foundation as an openspec change

This commit is contained in:
Artyom
2026-11-06 12:17:32 +03:00
parent a8836ce8b5
commit dc9256baf9
7 changed files with 192 additions and 0 deletions
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-06
@@ -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).
@@ -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.
@@ -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 изменяет журнал миграций
@@ -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 и не изменяет их
@@ -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,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.