---
work_item: ORCH-114
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-15
model_used: claude-opus-4-8
---

# adr-0045: Durable transition-ownership lease + expected-stage CAS — единое владение side-effectful переходами стадий

- **Статус:** proposed
- **Дата:** 2026-06-15
- **Задача:** ORCH-114 (bug → escalate full-cycle; системный наследник кластера ORCH-110/111/112/113)
- **Детальный ADR:** `docs/work-items/ORCH-114/06-adr/ADR-001-transition-ownership-lease-and-stage-cas.md`
- **Обобщает:** `adr-0043` (ORCH-113 in-memory finalizer-liveness — отправная точка)
- **Уточняет/опирается:** `adr-0011` (reaper/lease-reclaim ORCH-065), `adr-0040` (бюджеты ORCH-109),
  `adr-0042` (merge-retest ORCH-110), `adr-0027` (merge-lease ORCH-043), `adr-0029` (coverage-ratchet ORCH-027),
  ORCH-071/073/093 (SHA-in-main / already-in-main), ORCH-036 (`INITIATED` self-deploy)

## Контекст

Корневой класс инцидент-цепочки ORCH-110/111/112/113: **у side-effectful переходов стадий нет единого
владения**. `db.update_task_stage` — голый `UPDATE … WHERE id=?` без CAS (`db.py:671–679`); `advance_stage`
ре-ентерабельна без защиты и исполняет минуты-длинные необратимые под-гейты (`deploy-staging → deploy`:
security→merge-retest→coverage→image-freshness; `deploy → done`: `merge_pr`/ratchet/proof-of-merge) **до**
единственной записи стадии. ≥5 акторов входят в переход независимо (монитор/webhook/reconciler F-1/reaper/
Phase-C finalizer) + 6 путей пишут стадию в обход `advance_stage` (5× `gitea.py`, 1× `plane.py:806`).
ORCH-113 (`finalizer_liveness`) закрыл это лишь in-memory, reaper-Tier-2, `deploy-staging`, теряя владение
на рестарте — остаточный кросс-путь дал двойной эффект и противоречие rollback↔done (ORCH-111, job 1914/PR #130).

## Решение

Два комплементарных аддитивных слоя под единым kill-switch, never-raise:

1. **Durable transition-lease** — новая аддитивная таблица `transition_lease`
   (`task_id PK, owner, owner_pid, owner_boot_id, run_id, stage, acquired_at`; `CREATE TABLE IF NOT EXISTS`,
   паттерн `repo_freeze`/`coverage_baseline`). Владение захватывается на **входе** в side-effectful регион
   `advance_stage` (рёбра `deploy-staging→deploy`, `deploy→done`, Phase C `run_deploy_finalizer`); второй
   актор, увидев **живого** владельца, не стартует под-гейты вовсе (предотвращение класса, а не починка).
   Release — в `try/finally`. **Liveness = `owner_pid` + `owner_boot_id`**, НЕ heartbeat (heartbeat отвергнут
   тем же доводом, что в adr-0043: блокирующий 900s re-test не может его бить). Реклейм мёртвого/устаревшего
   (pid мёртв ИЛИ boot-id чужой) — немедленно; зависший живой добивается Tier-3.
2. **Expected-stage CAS** — `update_task_stage_cas(task_id, expected_stage, new_stage)`
   (`UPDATE tasks SET stage=? … WHERE id=? AND stage=?`, rowcount==1 ⇒ выиграл; 0 ⇒ проиграл → аборт без
   побочных эффектов). Покрывает остаточное окно гонки И 6 обходных путей. Без epoch-колонки: для текущей
   модели стадия *и есть* версия (epoch — задокументированное форвард-расширение под `--workers>1`).

**Осведомлённость акторов:** reaper консультирует durable-lease на **всех** путях (обобщение ORCH-113):
живой → defer, мёртвый → реклейм, Tier-3 маркер игнорирует; reconciler F-1 и webhook (Approved/Confirm
Deploy) — новый skip-guard по образцу escalated/Blocked/task-deps. `finalizer_liveness` сохранён без правок
как поведение при **выключенном** ORCH-114 (надстройка durable-слоя поверх).

**Умное восстановление (FR-4)** — НЕ новый recovery-мозг, а композиция: `requeue_running_jobs` (есть) +
startup stale-clear (boot-id mismatch ⇒ старые lease мертвы) + идемпотентность re-drive через
**авторитетные durable-факты предшественников** (SHA-in-main ORCH-071/073, `INITIATED` ORCH-036,
coverage-ratchet CAS ORCH-027). Lease лишь гарантирует **последовательную**, не конкурентную, их проверку.

**Бюджет (NFR-6):** lease без собственного TTL; жёсткий потолок возраста = Tier-3 `reaper_max_running_s`
(5400), reaper при реапе force-освобождает lease. Сквозной инвариант `5400 > Σ(≈4460)+grace` и
`reaper_finalize_grace_s`/`reaper_max_running_s` — **не тронуты**.

**Конфиг:** `transition_lease_enabled=True` (kill-switch) + `transition_lease_repos=""` (CSV; пусто →
self-hosting only, паттерн coverage/serial-gate). Leaf `src/transition_lease.py` never-raise.

**Инварианты:** `STAGE_TRANSITIONS` / `QG_CHECKS` / каждый `check_*` / machine-verdict-ключи / схемы
**существующих** таблиц — байт-в-байт; +1 аддитивная таблица; механизм не рестартит прод, не пушит/
force-push `main`, не трогает detached-деплой (NFR-5). Hot-path `claim_next_job` не тронут (fail-open).

## Альтернативы

- Только CAS (без lease) — не предотвращает двойной side-effect в полёте.
- Только lease (без CAS) — не покрывает 6 обходных путей + окно consult→acquire.
- Heartbeat-liveness — блокирующий re-test не бьёт heartbeat (довод adr-0043).
- Lease-файл per-task — CAS на стадию всё равно DB-операция; БД когерентнее, merge-lease-файл per-repo для
  иной задачи (сериализация мержей), не дублируется.
- epoch-колонка / sub-state `finalizing` в `jobs.status` / per-stage grace на Σ — отвергнуто (как в adr-0043:
  меняет семантику/нарушает бюджет/неиспользуемо).

## Последствия

- (+) Класс двойного эффекта закрыт в корне; конкурентный/после-рестартовый/reconciler/webhook пути покрыты.
- (+) Рестарт-safe без нового таймера; boot-id готовит multi-process; бюджет и инварианты конвейера целы; +1 таблица.
- (+) Дыра обходных путей gitea/plane закрыта CAS; откат — один env-флаг.
- (−) Полная multi-writer эксклюзия валидна при одном процессе/одной БД (как adr-0043); durable делает её
  корректной для рестарта, но `--workers>1`-верификация — вне объёма (риск в `10-tech-risks.md`).

## Связи

- Обобщает `adr-0043`; опирается на `adr-0011`/`adr-0040`/`adr-0042`/`adr-0027`/`adr-0029` и ORCH-071/073/093/036.
- Маркеры (ORCH-078/TRACEABILITY): блоки reaper/finalizer-liveness/stage-engine несут ORCH-065/109/110/113 +
  новый `ORCH-114`; правки сверяются с их ADR (анти-археология — этот сводный сквозной ADR).
- Детально: `docs/work-items/ORCH-114/06-adr/ADR-001-transition-ownership-lease-and-stage-cas.md`.
</content>
