Propose forwarding the lab 5 foundation as an openspec change
This commit is contained in:
@@ -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.
|
||||
+31
@@ -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 изменяет журнал миграций
|
||||
|
||||
+37
@@ -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 и не изменяет их
|
||||
+49
@@ -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.
|
||||
Reference in New Issue
Block a user