orchestrator/docs/work-items/ORCH-124/08-data-requirements.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-124	architecture	architect	proposed	2026-06-16	claude-opus-4-8

08 — Требования к данным: ORCH-124 — per-task park-сигнал serial-gate

Work Item: ORCH-124 · Repo: orchestrator · Стадия: architecture

When-applicable / информационный (гейтом не парсится).

Изменения схемы БД

Одна аддитивная нуллабельная колонка на существующей таблице tasks (никаких новых таблиц):

Таблица	Колонка	Тип / дефолт	Семантика
tasks	paused_at	TEXT (по умолчанию отсутствует → NULL)	NULL = не на паузе; ISO-таймстамп (datetime('now')) = задача поставлена оператором на паузу (park)

Миграция — идемпотентный _ensure_column(conn, "tasks", "paused_at", "TEXT") в init_db(), ровно по образцу tasks.cancelled_at / tasks.cancel_requested_at / tasks.track (src/db.py:141-149). На уже мигрированной БД — no-op.

Индекс не требуется. Горячий SQL build_claim_clause сканирует tasks t2 уже сегодня (по repo/id); терм AND t2.paused_at IS NULL — дополнительный фильтр в существующем EXISTS-подзапросе, не новый план доступа. Кардинальность tasks per-repo мала; добавление индекса — преждевременная оптимизация (принцип минимума).

Новые/изменённые сущности

• tasks.paused_at — единственное durable хранилище намерения паузы. Запись — db.set_task_paused (paused_at=datetime('now')); сброс — db.clear_task_paused (paused_at=NULL); чтение — db.is_task_paused и SQL-предикат serial-gate. Все хелперы never-raise.
• Инвариант оси: paused_at — ортогональная ось «пауза», независимая от оси «терминальность» (stage IN ('done','cancelled')). serial-gate «активна» = stage NOT IN ('done','cancelled') AND paused_at IS NULL. task_deps/stages.py колонку paused_at не читают (терминал не трогается, NFR-4).
• Существующие таблицы (jobs / job_deps / repo_freeze / agent_runs) — без изменений.

Совместимость данных / миграции

• Аддитивно и идемпотентно: _ensure_column — no-op на уже-мигрированной БД; новая колонка дефолтит в NULL для всех существующих строк ⇒ все текущие задачи считаются «не на паузе» ⇒ поведение до ORCH-124 сохраняется до первой явной операторской паузы.
• Restart-safe / durable: значение в БД переживает рестарт процесса/контейнера (BR-2, R-3).
• Общая прод-БД (self-hosting): колонка добавляется на общей БД; при дефолтном serial_gate_pause_enabled и отсутствии паузнутых задач — нулевая регрессия для enduro (paused_at везде NULL).
• Откат: колонка инертна при ORCH_SERIAL_GATE_PAUSE_ENABLED=false (pause-терм опускается из SQL). Колонку можно оставить (безвредна); деструктивный drop не требуется и не рекомендуется на прод-БД.