Merge branch 'main' of https://git.vakanaut.ru/admin/akyldash into feature/toktom-platform-development-plan

# Conflicts:
#	CHANGELOG.md

.gitea/actions/kaniko-push/Dockerfile

@@ -0,0 +1,4 @@
+FROM ghcr.io/osscontainertools/kaniko:v1.28.5-debug@sha256:c73ca67a3b494bce79a8fb6090c4f73c18997ab272d80bffc460a62343aeb412
+COPY release-build.sh /usr/local/bin/release-build
+COPY validate-destination.sh /usr/local/bin/validate-destination.sh
+ENTRYPOINT ["/busybox/sh", "/usr/local/bin/release-build"]

.gitea/actions/kaniko-push/action.yml

@@ -0,0 +1,23 @@
+name: Publish a pinned Akyldash image
+description: Build and push one commit-tagged image with pinned rootless Kaniko
+inputs:
+  workspace:
+    description: Checked out source directory
+    required: true
+  dockerfile:
+    description: Dockerfile path relative to workspace
+    required: true
+  destination:
+    description: Commit-specific OCI tag
+    required: true
+  digest_file:
+    description: Workspace path for Kaniko's resulting digest
+    required: true
+runs:
+  using: docker
+  image: Dockerfile
+  args:
+    - ${{ inputs.workspace }}
+    - ${{ inputs.dockerfile }}
+    - ${{ inputs.destination }}
+    - ${{ inputs.digest_file }}

.gitea/actions/kaniko-push/release-build.sh

@@ -0,0 +1,22 @@
+#!/busybox/sh
+set -eu
+
+workspace=$1
+dockerfile=$2
+destination=$3
+digest_file=$4
+: "${REGISTRY_USERNAME:?registry username secret is required}"
+: "${REGISTRY_PASSWORD:?registry password secret is required}"
+/busybox/sh /usr/local/bin/validate-destination.sh "$dockerfile" "$destination"
+
+mkdir -p /kaniko/.docker "$(dirname "$digest_file")"
+auth=$(printf '%s:%s' "$REGISTRY_USERNAME" "$REGISTRY_PASSWORD" | base64 | tr -d '\n')
+umask 077
+printf '{"auths":{"git.vakanaut.ru":{"auth":"%s"}}}\n' "$auth" > /kaniko/.docker/config.json
+unset auth REGISTRY_USERNAME REGISTRY_PASSWORD
+/kaniko/executor \
+  --context="dir://${workspace}" \
+  --dockerfile="${workspace}/${dockerfile}" \
+  --destination="$destination" \
+  --digest-file="$digest_file" \
+  --no-push-cache

.gitea/actions/kaniko-push/validate-destination.sh

@@ -0,0 +1,49 @@
+#!/bin/sh
+set -eu
+
+if [ "$#" -ne 2 ]; then
+  echo 'ERROR: expected Dockerfile path and image destination' >&2
+  exit 2
+fi
+
+dockerfile=$1
+destination=$2
+case "$dockerfile" in
+  deploy/production/Dockerfile.backend)
+    repository=git.vakanaut.ru/admin/akyldash/backend
+    ;;
+  deploy/production/Dockerfile.opensearch)
+    repository=git.vakanaut.ru/admin/akyldash/opensearch
+    ;;
+  *)
+    echo 'ERROR: Dockerfile is outside the approved production image set' >&2
+    exit 2
+    ;;
+esac
+
+case "$destination" in
+  "$repository":*) tag=${destination#"$repository":} ;;
+  *)
+    echo 'ERROR: destination is outside the approved registry repository' >&2
+    exit 2
+    ;;
+esac
+
+commit=${tag%%-*}
+run_id=${tag#*-}
+case "$commit" in
+  ''|*[!0123456789abcdef]*)
+    echo 'ERROR: destination commit must be a lowercase Git SHA-1' >&2
+    exit 2
+    ;;
+esac
+if [ "${#commit}" -ne 40 ] || [ "$run_id" = "$tag" ]; then
+  echo 'ERROR: destination tag must contain a 40-character commit and run ID' >&2
+  exit 2
+fi
+case "$run_id" in
+  ''|*[!0123456789]*)
+    echo 'ERROR: destination run ID must be numeric' >&2
+    exit 2
+    ;;
+esac

.gitea/workflows/ci.yaml

@@ -44,6 +44,7 @@ jobs:
             infra/bootstrap/verify.sh infra/bootstrap/verify-helper.sh infra/bootstrap/audit-host.sh \
             infra/deploy/install-helper.sh infra/deploy/compose-helper.sh infra/deploy/test-compose-helper.sh \
             infra/deploy/prepare-production-config.sh infra/deploy/test-production-config-guard.sh \
+            .gitea/actions/kaniko-push/release-build.sh \
             infra/bootstrap/test-audit-host.sh infra/bootstrap/test-root-guard.sh \
             infra/bootstrap/test-verify-helper.sh infra/test/run-as-unprivileged.sh \
             infra/runner/install-runner.sh infra/runner/install-runner-lib.sh \
@@ -52,6 +53,12 @@ jobs:
             infra/runner/test-ci-container-builds.sh
           python3 -c "import ast,pathlib; ast.parse(pathlib.Path('infra/runner/secure-runner-image.py').read_text())"
           python3 -c "import ast,pathlib; ast.parse(pathlib.Path('infra/deploy/validate_release.py').read_text())"
+          python3 -c "import ast,pathlib; ast.parse(pathlib.Path('infra/deploy/deploy_release.py').read_text())"
+          python3 -c "import ast,pathlib; ast.parse(pathlib.Path('infra/deploy/create_release_manifest.py').read_text())"
+          python3 -c "import ast,pathlib; ast.parse(pathlib.Path('infra/deploy/release_handoff.py').read_text())"
+          python3 -c "import ast,pathlib; ast.parse(pathlib.Path('infra/deploy/release_refs.py').read_text())"
+          python3 -c "import ast,pathlib; ast.parse(pathlib.Path('infra/deploy/release_state.py').read_text())"
+          python3 -c "import ast,pathlib; ast.parse(pathlib.Path('infra/deploy/deployment_lock.py').read_text())"
       - name: Run deployment contract and rollback tests
         run: python3 -m unittest discover -s infra/deploy -p 'test_*.py' -v
       - name: Validate production Compose and Caddyfile
@@ -75,3 +82,14 @@ jobs:
           workspace: ${{ github.workspace }}
           dockerfile: deploy/production/Dockerfile.opensearch
           destination: akyldash-opensearch:ci
+      - name: Prepare a synthetic artifact compatibility marker
+        run: |
+          mkdir -p artifact-smoke
+          printf 'Gitea artifact upload smoke test; no release data.\n' > artifact-smoke/marker.txt
+      - name: Verify Gitea runtime artifact upload
+        uses: https://gitea.com/actions/gitea-upload-artifact@055b8b3f04a4a7ed853f2c6ab04256f83e4874dc
+        with:
+          name: artifact-smoke-${{ github.run_id }}
+          path: artifact-smoke/marker.txt
+          if-no-files-found: error
+          retention-days: 1

.gitea/workflows/deploy-handoff.yaml

@@ -0,0 +1,64 @@
+name: Production handoff status (not deployed)
+
+on:
+  workflow_run:
+    workflows: ["Release production images"]
+    branches: [main]
+    types: [completed]
+
+jobs:
+  deployment-status:
+    name: NOT DEPLOYED - handoff status only
+    if: >-
+      gitea.event.workflow_run.conclusion == 'success' &&
+      gitea.event.workflow_run.event == 'workflow_run' &&
+      gitea.event.workflow_run.head_branch == 'main'
+    runs-on: akyldash-ci
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+      - name: Verify source release identity before artifact lookup
+        env:
+          SOURCE_WORKFLOW: ${{ gitea.event.workflow.name }}
+          SOURCE_WORKFLOW_PATH: ${{ gitea.event.workflow_run.path }}
+          SOURCE_EVENT: ${{ gitea.event.workflow_run.event }}
+          SOURCE_CONCLUSION: ${{ gitea.event.workflow_run.conclusion }}
+          SOURCE_BRANCH: ${{ gitea.event.workflow_run.head_branch }}
+          SOURCE_RUN_ID: ${{ gitea.event.workflow_run.id }}
+          SOURCE_SHA: ${{ gitea.event.workflow_run.head_sha }}
+          SOURCE_REPOSITORY: ${{ gitea.event.repository.full_name }}
+        run: python3 infra/deploy/release_handoff.py validate-handoff-source
+      - name: Read artifact metadata with the installed Gitea helper when available
+        env:
+          GITEA_URL: ${{ gitea.server_url }}
+          GITEA_TOKEN: ${{ gitea.token }}
+          SOURCE_RUN_ID: ${{ gitea.event.workflow_run.id }}
+          SOURCE_WORKFLOW: ${{ gitea.event.workflow.name }}
+          SOURCE_WORKFLOW_PATH: ${{ gitea.event.workflow_run.path }}
+          SOURCE_EVENT: ${{ gitea.event.workflow_run.event }}
+          SOURCE_CONCLUSION: ${{ gitea.event.workflow_run.conclusion }}
+          SOURCE_BRANCH: ${{ gitea.event.workflow_run.head_branch }}
+          SOURCE_SHA: ${{ gitea.event.workflow_run.head_sha }}
+          SOURCE_REPOSITORY: ${{ gitea.event.repository.full_name }}
+        run: |
+          if ! command -v gitea-api >/dev/null 2>&1; then
+            echo 'DRY-RUN only: gitea-api is unavailable in this job; artifact metadata and host handoff are not verified.'
+            python3 infra/deploy/release_handoff.py dry-run
+            exit 0
+          fi
+          if [[ -z ${GITEA_TOKEN:-} ]]; then
+            echo 'DRY-RUN only: GITEA_TOKEN is unavailable; artifact metadata and host handoff are not verified.'
+            python3 infra/deploy/release_handoff.py dry-run
+            exit 0
+          fi
+          metadata=$(mktemp)
+          trap 'rm -f "$metadata"' EXIT
+          gitea-api GET "/repos/admin/akyldash/actions/runs/${SOURCE_RUN_ID}/artifacts" > "$metadata"
+          python3 infra/deploy/release_handoff.py dry-run --artifact-metadata "$metadata"
+      - name: State that no deployment was performed
+        run: |
+          echo 'DEPLOYMENT STATUS: NOT DEPLOYED'
+          echo 'This workflow checks source provenance and may inspect artifact metadata only.'
+          echo 'It does not download the descriptor ZIP, open SSH, or invoke the Windows receiver.'
+          echo 'No Windows execution runner or automatic runtime binding has been verified.'

.gitea/workflows/release-images.yaml

@@ -0,0 +1,90 @@
+name: Release production images
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    branches: [main]
+    types: [completed]
+
+jobs:
+  publish-images:
+    if: >-
+      gitea.event.workflow_run.conclusion == 'success' &&
+      gitea.event.workflow_run.event == 'push' &&
+      gitea.event.workflow_run.head_branch == 'main'
+    runs-on: akyldash-ci
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ gitea.event.workflow_run.head_sha }}
+      - name: Verify successful CI source before using registry credentials
+        env:
+          SOURCE_WORKFLOW: ${{ gitea.event.workflow.name }}
+          SOURCE_WORKFLOW_PATH: ${{ gitea.event.workflow_run.path }}
+          SOURCE_EVENT: ${{ gitea.event.workflow_run.event }}
+          SOURCE_CONCLUSION: ${{ gitea.event.workflow_run.conclusion }}
+          SOURCE_BRANCH: ${{ gitea.event.workflow_run.head_branch }}
+          SOURCE_RUN_ID: ${{ gitea.event.workflow_run.id }}
+          SOURCE_SHA: ${{ gitea.event.workflow_run.head_sha }}
+          SOURCE_REPOSITORY: ${{ gitea.event.repository.full_name }}
+        run: python3 infra/deploy/release_handoff.py validate-ci-source
+      - name: Require explicitly configured Gitea registry credentials
+        env:
+          REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
+          REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
+        run: |
+          test -n "$REGISTRY_USERNAME" || { echo 'REGISTRY_USERNAME repository secret is required'; exit 1; }
+          test -n "$REGISTRY_PASSWORD" || { echo 'REGISTRY_PASSWORD repository secret is required'; exit 1; }
+      - name: Build and publish backend image
+        uses: ./.gitea/actions/kaniko-push
+        env:
+          REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
+          REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
+        with:
+          workspace: ${{ github.workspace }}
+          dockerfile: deploy/production/Dockerfile.backend
+          destination: git.vakanaut.ru/admin/akyldash/backend:${{ gitea.event.workflow_run.head_sha }}-${{ gitea.run_id }}
+          digest_file: ${{ github.workspace }}/release/backend.digest
+      - name: Build and publish OpenSearch image
+        uses: ./.gitea/actions/kaniko-push
+        env:
+          REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
+          REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
+        with:
+          workspace: ${{ github.workspace }}
+          dockerfile: deploy/production/Dockerfile.opensearch
+          destination: git.vakanaut.ru/admin/akyldash/opensearch:${{ gitea.event.workflow_run.head_sha }}-${{ gitea.run_id }}
+          digest_file: ${{ github.workspace }}/release/opensearch.digest
+      - name: Create and validate release descriptor
+        run: |
+          python3 infra/deploy/create_release_manifest.py \
+            --repository admin/akyldash \
+            --commit '${{ gitea.event.workflow_run.head_sha }}' \
+            --run-id '${{ gitea.run_id }}' \
+            --source-run-id '${{ gitea.event.workflow_run.id }}' \
+            --backend-digest release/backend.digest \
+            --opensearch-digest release/opensearch.digest \
+            --output release/release-manifest.json
+          python3 infra/deploy/validate_release.py release/release-manifest.json \
+            --policy infra/deploy/release-policy.json
+          (cd release && sha256sum release-manifest.json > release-manifest.json.sha256)
+      - id: descriptor
+        name: Record release descriptor digest
+        run: |
+          (cd release && sha256sum -c release-manifest.json.sha256)
+          digest=$(sha256sum release/release-manifest.json)
+          digest=${digest%% *}
+          printf 'descriptor_sha256=%s\n' "$digest" >> "$GITEA_OUTPUT"
+      - name: Upload verified release descriptor
+        uses: https://gitea.com/actions/gitea-upload-artifact@055b8b3f04a4a7ed853f2c6ab04256f83e4874dc
+        with:
+          name: release-descriptor-${{ gitea.run_id }}-${{ steps.descriptor.outputs.descriptor_sha256 }}
+          path: |
+            release/release-manifest.json
+            release/release-manifest.json.sha256
+          if-no-files-found: error
+          retention-days: 90
+      - name: Confirm uploaded release descriptor
+        run: |
+          (cd release && sha256sum -c release-manifest.json.sha256)
+          echo 'Release descriptor and checksum are available as this run artifact.'

AGENTS.md

@@ -1,7 +1,11 @@
 # Акылдаш — инструкции для агента
 
 Проект: юридическая информационно-аналитическая платформа; Search API на
-Python, SQLite и OpenSearch. Production пока не развернут.
+Python, SQLite и OpenSearch. На 2026-10-25 публичный `/review` и прямой origin
+отвечают HTTP 200; состав production-контейнеров, готовность индекса и
+проверенность backup/restore не подтверждены. Сверяй актуальное состояние с
+[`CURRENT_STATE.md`](docs/operations/CURRENT_STATE.md), не считай HTTP 200
+доказательством готовности поиска.
 
 - Начинай с [инфраструктурного состояния](docs/operations/CURRENT_STATE.md) и
   [правил доступа](docs/operations/ACCESS.md). Не запрашивай доступы повторно.
@@ -37,6 +41,31 @@ Python, SQLite и OpenSearch. Production пока не развернут.
 - После каждого изменения инфраструктуры обновляй
   `docs/operations/CURRENT_STATE.md` по фактическим проверкам.
 
+## Delivery First: проверка по уровню риска
+
+- Перед работой укажи в PR уровень `LOW`, `MEDIUM` или `HIGH`; при сомнении
+  выбери более высокий. Уровень добавляет нужную проверку, но никогда не
+  отменяет CI, одобрение или защиту `main`.
+- Каждый PR сохраняет текущие проверки Gitea Actions: job IDs
+  `tests-and-images` и `runner-smoke`. Не переименовывай и не обходи их, не
+  удаляй тесты или проверки безопасности ради скорости.
+- `LOW`: документация, комментарии и тексты без изменения исполняемого
+  поведения или контракта; проверяй diff и актуальность утверждений, затем
+  дождись обычного CI.
+- `MEDIUM`: изменение поведения в одном компоненте; добавь регрессионный тест,
+  выполни целевые проверки и обычный CI.
+- `HIGH`: доступ/авторизация, данные и ingestion, схемы/хранилища,
+  backup/restore/recovery, production config, секреты, runner/CI, безопасность
+  или deploy; выполни целевые тесты вместе с обычным CI и приложи проверяемое
+  обоснование угроз, совместимости и rollback. Production-действия остаются
+  за владельцем.
+- Ревью блокирует только конкретный воспроизводимый дефект, нарушение границы
+  доступа/безопасности, несовместимость данных или контракта, пропущенную
+  обязательную проверку либо отсутствие безопасного rollback. Идеи и стилистические
+  замечания перечисляй отдельно как неблокирующие.
+- Полная процедура, метрики, Gitea-ограничения и проверенные временные бюджеты:
+  [DELIVERY_POLICY.md](docs/development/DELIVERY_POLICY.md).
+
 ## Автономный workflow PR
 
 - Маршруты ниже указаны из контекста оркестратора/root: оркестратор — thread

CHANGELOG.md

@@ -2,9 +2,38 @@
 
 ## Не выпущено
 
+- Успешный CI на `push` в `main` запускает release workflow: при настроенных
+  registry secrets он собирает образы rootless Kaniko, публикует digest
+  references и сохраняет schema-v4 descriptor с SHA-256 в Gitea artifact;
+  sidecar проверяется после извлечения из корня. Следующий workflow проверяет
+  source-run identity и, при доступном `gitea-api`, метаданные артефакта только
+  в dry-run и явно сообщает `NOT DEPLOYED`: ZIP не скачивается, SSH и host
+  apply не выполняются. Добавлена отдельная root-verified status→fixed-tuple→
+  Windows `--once` привязка через строгий SSH dispatcher; она не использует
+  Gitea/PR runner и не требует Gitea token на Windows. Config и Task Scheduler
+  template выключены, задача не зарегистрирована и production CD не активирован.
+  Зелёный handoff не означает деплой. Подготовлены owner-run cutover и rollback с
+  проверкой backup, image IDs, RU/KY canaries и recovery journal; CI проверяет
+  synthetic artifact и завершается ошибкой при отсутствии файлов. Windows
+  receiver прошёл 17 synthetic client checks, 8 protocol checks и проверку
+  private owner ACL на disposable real-NTFS fixture. Inert Windows argv probe
+  подтвердил передачу пути скрипта с пробелами; Task Scheduler COM проверил
+  XML с `TASK_VALIDATE_ONLY` — задачу не регистрировали, не обновляли и не
+  запускали. Production D: path, SSH, установка на VPS и полный backup/restore
+  не проверены; cutover остаётся заблокирован до отдельного restore-теста и
+  owner bootstrap. Принимаются только завершённые успешные Gitea runs; pending
+  recovery journal записывается до остановки
+  сервисов, повторно применённый release отклоняется до простоя, а проверка
+  `main` использует явно заданный production checkout. Windows preflight
+  проверяет owner ACL и требует свободное место под максимальный допустимый
+  архив.
 - Frontend `0.3.3` / Backend `0.13.2`: управление пользователями отображается
   согласно правам аккаунта, подписи ролей локализованы, повторяющиеся действия
   кабинета убраны, а знак лаборатории приведён к основному бренду.
+- Добавлена политика Delivery First по уровням `LOW`/`MEDIUM`/`HIGH`: описаны
+  обязательная глубина проверок, регрессионные тесты и доказательства угроз,
+  совместимости и отката; обычные CI, одобрение и защита `main` остаются
+  обязательными.
 - Frontend `0.3.2`: устранены пересечения названия бренда с поиском и
   мобильной навигации документа; навигационные ссылки получили общие quiet и
   primary состояния.
@@ -16,6 +45,8 @@
   изменения ширины результатов и документа. Язык поиска находится в фильтрах;
   состояния открытия, оглавление правовых заголовков, лаборатория и кабинет
   приведены к последовательной и компактной компоновке.
+- Добавлен план развития платформы со сравнением возможностей «Токтом Онлайн»,
+  пробелов Акылдаша и этапов продуктовой проверки.
 - Frontend `0.2.6` / Backend `0.13.1`: двухпанельная компоновка поиска
   сохраняется до ширины 1175 px, чтобы три панели не обрезались при
   промежуточных ширинах окна.

backend/README.md

@@ -171,16 +171,31 @@ python3 backend/search/minjust_opensearch.py \
 После проверки production-индекса следует переключать alias, чтобы удалённые
 фрагменты не оставались в поиске.
 
-Чтобы переключить alias атомарно только после успешной полной загрузки,
-передайте `--alias`:
+Alias переключается только после refresh, точного сравнения полного fragment
+count с inventory, обеих языковых canary-проверок и совпадения ожидаемого
+текущего индекса. Перед cutover обязательно укажите RU/KY запросы и точное имя
+старого target:
 
 ```bash
 python3 backend/search/minjust_opensearch.py \
   --url http://127.0.0.1:9200 \
   --index akyldash-fragments-v2 \
-  --alias akyldash-fragments-current
+  --alias akyldash-fragments-current \
+  --expected-old-index akyldash-fragments-v1 \
+  --canary-ru 'утверждённый русский запрос' \
+  --canary-ky 'бекитилген кыргызча суроо'
 ```
 
+Wildcard removal, пустой индекс и alias с несколькими target запрещены. Если
+старый target успел измениться после проверки, OpenSearch отклонит атомарную
+операцию удаления точного старого alias. `--resume` повторно проверяет весь
+ожидаемый inventory, а не только количество документов текущего запуска.
+Если ответ на alias request потерян после успешного переключения или процесс
+остановился до записи завершённого checkpoint, повторный запуск проверит
+фактическую цель alias. Уже опубликованный candidate оставляется на месте, и
+checkpoint завершается; старый target позволяет безопасно повторить cutover,
+а любой другой target останавливает операцию.
+
 После каждого принятого Bulk-пакета загрузчик атомарно сохраняет checkpoint и
 печатает код безопасного возобновления. При временных HTTP 429/5xx, timeout и
 обрыве соединения запрос повторяется автоматически. Прерванную загрузку можно

backend/search/minjust_opensearch.py

@@ -17,7 +17,7 @@ from typing import Iterator
 
 from search.catalog import authority_codes, legal_force_code, source_code
 
-APP_VERSION = "0.13.2"
+APP_VERSION = "0.13.3"
 LANGUAGES = {"ru", "ky"}
 DEFAULT_MAPPING = Path(__file__).with_name("minjust-fragments-index.json")
 
@@ -342,10 +342,17 @@ def load_bulk(
     resume: bool = False,
     checkpoint: Path = Path("data/opensearch/minjust-fragments.checkpoint.json"),
     alias: str | None = None,
+    expected_old_index: str | None = None,
+    canary_ru: str | None = None,
+    canary_ky: str | None = None,
 ) -> tuple[int, int]:
     base = url.rstrip("/")
     if alias is not None and (not alias or alias == index):
         raise ValueError("--alias must differ from --index")
+    if alias is not None and (not expected_old_index or expected_old_index == index):
+        raise ValueError("alias publication requires an exact --expected-old-index")
+    if alias is not None and (not canary_ru or not canary_ky):
+        raise ValueError("alias publication requires both Russian and Kyrgyz canary queries")
     index_url = f"{base}/{urllib.parse.quote(index, safe='')}"
     if resume:
         cluster_uuid, index_uuid = opensearch_identity(base, index, index_url)
@@ -364,6 +371,7 @@ def load_bulk(
         alias,
     )
     documents = document_count(input_root, limit, start_at)
+    expected_fragments = sum(1 for _ in bulk_pairs(input_root, index, limit)) if alias else None
     if not resume:
         write_json_atomic(checkpoint, state)
     fragments = 0
@@ -398,27 +406,100 @@ def load_bulk(
         write_json_atomic(checkpoint, state)
         print(f"checkpoint={last_code} fragments={fragments}", flush=True)
     if alias:
-        switch_alias(base, index, alias)
+        if not expected_fragments:
+            raise ValueError("refusing to publish an index with an empty expected fragment inventory")
+        validate_candidate_index(base, index, expected_fragments, canary_ru, canary_ky)
+        switch_alias(base, index, alias, expected_old_index)
     state["complete"] = True
     write_json_atomic(checkpoint, state)
     return documents, fragments
 
 
-def switch_alias(base: str, index: str, alias: str) -> None:
+def alias_target(base: str, alias: str) -> str:
+    alias_url = f"{base.rstrip('/')}/_alias/{urllib.parse.quote(alias, safe='')}"
+    try:
+        result = request_json(alias_url, "GET", None, "application/json")
+    except RuntimeError as error:
+        if "failed with HTTP 404:" in str(error):
+            raise ValueError(f"alias {alias} has no current target; explicit bootstrap is required") from error
+        raise
+    if not isinstance(result, dict) or len(result) != 1:
+        raise ValueError(f"alias {alias} must point to exactly one index")
+    target, definition = next(iter(result.items()))
+    if not isinstance(definition, dict) or alias not in definition.get("aliases", {}):
+        raise ValueError(f"alias {alias} response is malformed")
+    return target
+
+
+def validate_candidate_index(
+    base: str, index: str, expected_fragments: int, canary_ru: str, canary_ky: str
+) -> None:
+    if expected_fragments <= 0:
+        raise ValueError("expected fragment count must be positive")
+    encoded_index = urllib.parse.quote(index, safe='')
+    refreshed = request_json(f"{base.rstrip('/')}/{encoded_index}/_refresh", "POST", None, "application/json")
+    shards = refreshed.get("_shards", {})
+    if not isinstance(shards, dict) or shards.get("failed") != 0:
+        raise RuntimeError(f"refresh failed for candidate index {index}")
+    count_result = request_json(f"{base.rstrip('/')}/{encoded_index}/_count", "GET", None, "application/json")
+    if count_result.get("count") != expected_fragments:
+        raise RuntimeError(
+            f"candidate index {index} has {count_result.get('count')} fragments; expected {expected_fragments}"
+        )
+    for language, query in (("ru", canary_ru), ("ky", canary_ky)):
+        payload = json.dumps({"size": 1, "query": {"match": {f"text_{language}": query}}}).encode()
+        result = request_json(
+            f"{base.rstrip('/')}/{encoded_index}/_search", "POST", payload, "application/json"
+        )
+        hits = result.get("hits", {}).get("hits", [])
+        if not hits or not isinstance(hits[0].get("_source", {}).get(f"text_{language}"), str):
+            raise RuntimeError(f"candidate index {index} failed the {language} canary query")
+
+
+def switch_alias(base: str, index: str, alias: str, expected_old_index: str) -> None:
     if not alias or alias == index:
         raise ValueError("--alias must differ from --index")
-    result = request_json(
-        f"{base.rstrip('/')}/_aliases",
-        "POST",
-        json.dumps({
-            "actions": [
-                {"remove": {"index": "*", "alias": alias, "must_exist": False}},
-                {"add": {"index": index, "alias": alias}},
-            ]
-        }).encode(),
-        "application/json",
-    )
-    if result.get("acknowledged") is not True:
+    if not expected_old_index or expected_old_index == index:
+        raise ValueError("--expected-old-index must name the exact previous index")
+    actual_old_index = alias_target(base, alias)
+    if actual_old_index == index:
+        return
+    if actual_old_index != expected_old_index:
+        raise ValueError(
+            f"alias {alias} currently targets {actual_old_index}, expected {expected_old_index}; refusing cutover"
+        )
+    try:
+        result = request_json(
+            f"{base.rstrip('/')}/_aliases",
+            "POST",
+            json.dumps({
+                "actions": [
+                    {"remove": {"index": expected_old_index, "alias": alias, "must_exist": True}},
+                    {"add": {"index": index, "alias": alias}},
+                ]
+            }).encode(),
+            "application/json",
+        )
+    except Exception as error:
+        try:
+            current = alias_target(base, alias)
+        except Exception:
+            raise RuntimeError(f"alias switch outcome is unknown; inspect {alias} before resuming") from error
+        if current == index:
+            return
+        if current != expected_old_index:
+            raise ValueError(
+                f"alias {alias} now targets unexpected index {current}; refusing to retry publication"
+            ) from error
+        raise RuntimeError(f"alias switch failed; {alias} still targets {expected_old_index}") from error
+    if not isinstance(result, dict) or result.get("acknowledged") is not True:
+        current = alias_target(base, alias)
+        if current == index:
+            return
+        if current != expected_old_index:
+            raise ValueError(
+                f"alias {alias} now targets unexpected index {current}; refusing to retry publication"
+            )
         raise RuntimeError(f"OpenSearch did not acknowledge alias switch: {alias}")
 
 
@@ -430,6 +511,9 @@ def main() -> int:
     parser.add_argument("--limit", type=int)
     parser.add_argument("--url", help="create the index and stream bounded Bulk requests instead of writing a file")
     parser.add_argument("--alias", help="atomically point this alias at --index after a successful load")
+    parser.add_argument("--expected-old-index", help="exact current alias target required for guarded cutover")
+    parser.add_argument("--canary-ru", help="approved Russian query that must match the candidate index")
+    parser.add_argument("--canary-ky", help="approved Kyrgyz query that must match the candidate index")
     parser.add_argument("--mapping", type=Path, default=DEFAULT_MAPPING)
     parser.add_argument("--batch-mb", type=int, default=25)
     parser.add_argument("--resume", action="store_true", help="load into an existing index")
@@ -460,6 +544,9 @@ def main() -> int:
             arguments.resume,
             checkpoint,
             arguments.alias,
+            arguments.expected_old_index,
+            arguments.canary_ru,
+            arguments.canary_ky,
         )
         destination = arguments.url
     else:

backend/search/review.html

@@ -657,7 +657,7 @@
       <section class="search__document" id="public-document-panel" aria-labelledby="public-document-heading"><div class="search__document-head"><div class="search__breadcrumbs" hidden><span>Документ</span><span aria-hidden="true">/</span><span id="document-breadcrumb">Выберите результат</span></div><div><button class="search__mobile-back" id="document-back" type="button">К результатам</button><button class="search__expand" id="document-expand" type="button" aria-label="Развернуть документ">Развернуть</button></div><h2 id="public-document-heading">Документ</h2></div><p id="public-document-meta" class="search__document-meta"><span id="document-facts">Выберите документ в выдаче, чтобы открыть текст.</span><label class="search__document-language" hidden>Язык<select id="document-language" disabled aria-label="Язык документа"></select></label></p><div class="search__document-toolbar"><details class="search__toc" id="document-toc"><summary>Содержание</summary><nav aria-label="Содержание документа"><ol id="document-toc-list"><li>Оглавление появится после загрузки документа</li></ol></nav></details><label class="search__edition-label"><select id="document-edition" disabled aria-label="Редакция документа"></select></label><button id="document-print" type="button">Печать</button><a id="document-source" class="search__source-link" href="#" target="_blank" rel="noreferrer" hidden>Официальный источник</a></div><div class="search__find"><label for="document-find">Найти в документе</label><input id="document-find" type="search" placeholder="Фраза в документе" disabled><span class="search__find-count" id="document-find-count" aria-live="polite"></span><button id="document-find-prev" type="button" disabled aria-label="Предыдущее совпадение"><svg viewBox="0 0 20 20" width="18" height="18" aria-hidden="true"><path d="m12 4-6 6 6 6" fill="none" stroke="currentColor" stroke-width="1.8"/></svg></button><button id="document-find-next" type="button" disabled aria-label="Следующее совпадение"><svg viewBox="0 0 20 20" width="18" height="18" aria-hidden="true"><path d="m8 4 6 6-6 6" fill="none" stroke="currentColor" stroke-width="1.8"/></svg></button></div><p class="search__document-note" id="document-note" hidden></p><article id="public-document-body" class="search__document-body"></article></section>
     </div>
   </main>
-  <footer class="search__footer"><span><strong>Акылдаш</strong> <span aria-hidden="true">·</span> Правовая база Кыргызстана</span><span>Frontend v0.3.3 <span aria-hidden="true">·</span> Backend v0.13.2</span></footer>
+  <footer class="search__footer"><span><strong>Акылдаш</strong> <span aria-hidden="true">·</span> Правовая база Кыргызстана</span><span>Frontend v0.3.3 <span aria-hidden="true">·</span> Backend v0.13.3</span></footer>
   <div class="review__actions"><div class="review__actions-inner"><label>Проверяющий<input id="reviewer" readonly aria-label="Проверяющий"></label><label>Комментарий к выдаче <input id="overall-comment" maxlength="4000" placeholder="Что важно учесть? (необязательно)"></label><button class="review__button--primary" id="save" type="button" disabled>Сначала выполните поиск</button><p id="draft-status" class="review__status" role="status" aria-live="polite">Черновик появится после поиска.</p></div></div>
   <dialog id="login-dialog" aria-labelledby="login-heading"><form class="review__page" id="login-form"><h2 id="login-heading">Вход в Акылдаш</h2><p>Введите учетные данные, выданные администратором.</p><label>Логин<input id="login-username" name="username" autocomplete="username" required minlength="3" maxlength="64"></label><label>Пароль<input id="login-password" name="password" type="password" autocomplete="current-password" required></label><p id="login-error" class="review__status review__status--error" role="alert"></p><button class="review__button--primary" type="submit">Войти</button></form></dialog>
   <dialog id="password-dialog" aria-labelledby="password-heading"><form class="review__page" id="password-form"><h2 id="password-heading">Создайте новый пароль</h2><p class="review__notice">Для продолжения замените временный пароль. Используйте не менее 12 символов.</p><label>Текущий пароль<input id="current-password" type="password" autocomplete="current-password" required></label><label>Новый пароль<input id="new-password" type="password" autocomplete="new-password" minlength="12" maxlength="256" required></label><label>Повторите новый пароль<input id="confirm-password" type="password" autocomplete="new-password" minlength="12" maxlength="256" required></label><p id="password-error" class="review__status review__status--error" role="alert"></p><button class="review__button--primary" type="submit">Сохранить пароль</button></form></dialog>
@@ -675,7 +675,7 @@
   <dialog id="document-dialog"><button class="review__dialog-close" id="dialog-close" type="button">Закрыть</button><h2 id="dialog-heading">Документ</h2><div class="review__document-body" id="dialog-body"></div></dialog>
   <dialog class="search__about" id="sources-dialog" aria-labelledby="sources-heading"><button class="review__dialog-close" id="sources-close" type="button">Закрыть</button><h2 id="sources-heading">Источники документов</h2><p>Поиск выполняется по документам, подготовленным из правовых источников Кыргызской Республики. Для каждого результата доступная редакция и ссылка на официальный источник показываются в панели документа.</p><p>Официальный источник: <a href="https://cbd.minjust.gov.kg/" target="_blank" rel="noreferrer">Централизованный банк данных правовой информации Министерства юстиции Кыргызской Республики</a>.</p></dialog>
   <div class="review__tour-spotlight" id="tutorial-spotlight" hidden aria-hidden="true"></div><dialog class="review__tour" id="tutorial-dialog" aria-labelledby="tutorial-heading" aria-describedby="tutorial-text"><div class="review__tour-content"><p class="review__tour-kicker">Короткое знакомство</p><h2 id="tutorial-heading"></h2><p id="tutorial-text"></p><div class="review__tour-footer"><span class="review__tour-progress" id="tutorial-progress"></span><div class="review__tour-actions"><button id="tutorial-skip" type="button">Пропустить</button><button class="review__button--primary" id="tutorial-next" type="button">Далее</button></div></div></div></dialog>
-  <footer class="review__header"><div class="review__header-content">Акылдаш · Frontend v0.3.3 · Backend v0.13.2 · Внутренняя лаборатория релевантности</div></footer>
+  <footer class="review__header"><div class="review__header-content">Акылдаш · Frontend v0.3.3 · Backend v0.13.3 · Внутренняя лаборатория релевантности</div></footer>
   <script>
     document.body.classList.add('review__locked');
     const DRAFT_KEY = 'akyldash-search-review-draft';
@@ -709,8 +709,8 @@
     $('review-review-nav').classList.toggle('is-active', reviewRoute); $('review-search-nav').classList.toggle('is-active', searchRoute); $('review-users-open').classList.toggle('is-active', usersRoute); $('review-nav').classList.toggle('is-active', reviewRoute); $('search-nav').classList.toggle('is-active', searchRoute);
     document.body.classList.toggle('is-review-route', reviewRoute);
     document.body.classList.toggle('is-search-route', searchRoute); document.body.classList.toggle('is-users-route', usersRoute);
-    if (usersRoute) { document.title = 'Пользователи · Акылдаш'; $('route-heading').textContent = 'Пользователи'; $('route-description').textContent = 'Управляйте учётными записями. Доступ к действиям проверяется сервером.'; $('tutorial-open').hidden = true; document.querySelector('.review__skip').href = '#users-page'; document.querySelector('footer .review__header-content').textContent = 'Акылдаш · Frontend v0.3.3 · Backend v0.13.2'; }
-    else if (!reviewRoute) { document.title = 'Поиск по правовой базе · Акылдаш'; document.querySelector('.review__header-content').hidden = true; $('tutorial-open').hidden = true; document.querySelector('.review__skip').href = '#public-results'; document.querySelector('footer .review__header-content').textContent = 'Акылдаш · Frontend v0.3.3 · Backend v0.13.2'; }
+    if (usersRoute) { document.title = 'Пользователи · Акылдаш'; $('route-heading').textContent = 'Пользователи'; $('route-description').textContent = 'Управляйте учётными записями. Доступ к действиям проверяется сервером.'; $('tutorial-open').hidden = true; document.querySelector('.review__skip').href = '#users-page'; document.querySelector('footer .review__header-content').textContent = 'Акылдаш · Frontend v0.3.3 · Backend v0.13.3'; }
+    else if (!reviewRoute) { document.title = 'Поиск по правовой базе · Акылдаш'; document.querySelector('.review__header-content').hidden = true; $('tutorial-open').hidden = true; document.querySelector('.review__skip').href = '#public-results'; document.querySelector('footer .review__header-content').textContent = 'Акылдаш · Frontend v0.3.3 · Backend v0.13.3'; }
     async function apiFetch(path, options = {}) { const response = await fetch(path, {credentials: 'same-origin', ...options}); if (response.status === 401 && path !== '/auth/login') { document.body.classList.add('review__locked'); if (!$('login-dialog').open) $('login-dialog').showModal(); $('login-username').focus(); } return response; }
     const showLogin = () => { document.body.classList.add('review__locked'); if (!$('login-dialog').open) $('login-dialog').showModal(); $('login-username').focus(); };
     const enterWorkspace = (user) => { account = user; $('signed-in-user').textContent = user.username; $('review-signed-in-user').textContent = user.username; $('reviewer').value = user.username; $('profile-username').textContent = user.username; $('profile-role').textContent = roleLabel(user); $('profile-created').textContent = new Date(user.created_at * 1000).toLocaleDateString('ru-RU'); const canManageUsers = user.can_manage_users === true; $('review-nav').hidden = true; $('review-users-open').hidden = !canManageUsers || searchRoute; $('search-users-open').hidden = !canManageUsers || !searchRoute; document.body.classList.remove('review__locked'); if (usersRoute) { if (!canManageUsers) { location.replace('/'); return; } document.body.classList.add('is-admin'); const savedLanguage = (() => { try { return localStorage.getItem('akyldash-ui-language') || 'ru'; } catch (_) { return 'ru'; } })(); updateUsersLanguage(savedLanguage); } else if (searchRoute) initSearchPage(); };
@@ -1343,7 +1343,7 @@
       document.querySelectorAll('.review__user-table-head [role="columnheader"]').forEach((cell, index) => { cell.textContent = [words.login, words.role, words.state, words.lastLogin, words.actions][index]; });
       $('create-user-heading').textContent = words.create; document.querySelectorAll('#create-user-form label').forEach((label, index) => { const input = label.querySelector('input'); label.firstChild.textContent = `${[words.username, words.tempPassword][index]} `; if (input) label.append(input); }); document.querySelector('#create-user-form p').textContent = words.tempHelp; document.querySelector('#create-user-form button[type="submit"]').textContent = words.create;
       $('delete-user-heading').textContent = words.deleteHeading; $('delete-user-confirm').textContent = words.delete; document.querySelectorAll('#create-user-dialog [data-close], #delete-user-dialog [data-close]').forEach((button) => button.textContent = words.cancel);
-      document.querySelector('footer .review__header-content').textContent = `Акылдаш · Frontend v0.3.3 · Backend v0.13.2`;
+      document.querySelector('footer .review__header-content').textContent = `Акылдаш · Frontend v0.3.3 · Backend v0.13.3`;
       if (usersRoute && account) loadUsers();
     };
     $('users-ui-ru').addEventListener('click', () => updateUsersLanguage('ru'));

backend/test_minjust_opensearch.py

@@ -70,21 +70,178 @@ class MinjustOpenSearchTest(unittest.TestCase):
             self.assertEqual(flags, {"920292": True, "920492": False})
 
     def test_switches_alias_atomically_after_successful_load(self):
-        with patch("search.minjust_opensearch.request_json", return_value={"acknowledged": True}) as request:
-            switch_alias("http://127.0.0.1:9200/", "akyldash-fragments-v2", "akyldash-fragments-current")
+        with patch("search.minjust_opensearch.request_json", side_effect=[
+            {"akyldash-fragments-v1": {"aliases": {"akyldash-fragments-current": {}}}},
+            {"acknowledged": True},
+        ]) as request:
+            switch_alias(
+                "http://127.0.0.1:9200/", "akyldash-fragments-v2",
+                "akyldash-fragments-current", "akyldash-fragments-v1",
+            )
 
-        self.assertEqual(request.call_args.args[:2], ("http://127.0.0.1:9200/_aliases", "POST"))
-        body = json.loads(request.call_args.args[2])
-        self.assertEqual(body["actions"][0], {"remove": {"index": "*", "alias": "akyldash-fragments-current", "must_exist": False}})
+        self.assertEqual(request.call_args_list[1].args[:2], ("http://127.0.0.1:9200/_aliases", "POST"))
+        body = json.loads(request.call_args_list[1].args[2])
+        self.assertEqual(body["actions"][0], {"remove": {"index": "akyldash-fragments-v1", "alias": "akyldash-fragments-current", "must_exist": True}})
         self.assertEqual(body["actions"][1], {"add": {"index": "akyldash-fragments-v2", "alias": "akyldash-fragments-current"}})
 
         with self.assertRaisesRegex(ValueError, "differ"):
-            switch_alias("http://127.0.0.1:9200", "same", "same")
+            switch_alias("http://127.0.0.1:9200", "same", "same", "old")
         with self.assertRaisesRegex(ValueError, "differ"):
-            switch_alias("http://127.0.0.1:9200", "index", "")
-        with patch("search.minjust_opensearch.request_json", return_value={"acknowledged": False}):
+            switch_alias("http://127.0.0.1:9200", "index", "", "old")
+        with patch("search.minjust_opensearch.request_json", return_value={
+            "akyldash-fragments-v3": {"aliases": {"alias": {}}}
+        }) as request:
+            with self.assertRaisesRegex(ValueError, "currently targets"):
+                switch_alias("http://127.0.0.1:9200", "new", "alias", "akyldash-fragments-v1")
+        request.assert_called_once()
+        with patch("search.minjust_opensearch.request_json", side_effect=[
+            {"old": {"aliases": {"alias": {}}}}, {"acknowledged": False},
+            {"old": {"aliases": {"alias": {}}}},
+        ]):
             with self.assertRaisesRegex(RuntimeError, "did not acknowledge"):
-                switch_alias("http://127.0.0.1:9200", "index", "alias")
+                switch_alias("http://127.0.0.1:9200", "index", "alias", "old")
+
+    def test_switch_alias_recovers_when_post_succeeds_but_response_is_lost(self):
+        with patch("search.minjust_opensearch.request_json", side_effect=[
+            {"old": {"aliases": {"alias": {}}}},
+            RuntimeError("response lost after OpenSearch applied request"),
+            {"candidate": {"aliases": {"alias": {}}}},
+        ]) as request:
+            switch_alias("http://os:9200", "candidate", "alias", "old")
+        self.assertEqual(request.call_count, 3)
+        self.assertEqual(request.call_args_list[1].args[1], "POST")
+        self.assertEqual(request.call_args_list[2].args[1], "GET")
+
+    def test_switch_alias_is_idempotent_after_process_stops_before_checkpoint(self):
+        with patch("search.minjust_opensearch.request_json", return_value={
+            "candidate": {"aliases": {"alias": {}}}
+        }) as request:
+            switch_alias("http://os:9200", "candidate", "alias", "old")
+        request.assert_called_once()
+
+    def test_switch_alias_refuses_to_retry_after_unexpected_target(self):
+        with patch("search.minjust_opensearch.request_json", side_effect=[
+            {"old": {"aliases": {"alias": {}}}},
+            RuntimeError("response lost"),
+            {"other": {"aliases": {"alias": {}}}},
+        ]):
+            with self.assertRaisesRegex(ValueError, "unexpected index"):
+                switch_alias("http://os:9200", "candidate", "alias", "old")
+
+    def test_resume_completes_checkpoint_when_alias_switched_before_previous_process_stopped(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            input_root = root / "normalized"
+            document_root = input_root / "documents/1"
+            document_root.mkdir(parents=True)
+            with closing(sqlite3.connect(input_root / "manifest.sqlite3")) as connection:
+                with connection:
+                    connection.execute("CREATE TABLE documents (code TEXT, state TEXT)")
+                    connection.execute("INSERT INTO documents VALUES ('1', 'success')")
+            (document_root / "document.json").write_text(
+                json.dumps({"schema_version": "1", "source_code": "1", "editions": [
+                    {"source_code": "1", "source_order": 0},
+                ]}),
+                encoding="utf-8",
+            )
+            text = "текст закона"
+            fragment = document_root / "editions/1/ru/fragments.json"
+            fragment.parent.mkdir(parents=True)
+            fragment.write_text(json.dumps([{
+                "id": "document:1:edition:1:lang:ru:fragment:1",
+                "document_code": "1", "edition_code": "1", "language": "ru", "position": 1,
+                "type": "paragraph", "text": text,
+                "text_sha256": hashlib.sha256(text.encode()).hexdigest(),
+                "source_path": "documents/1/editions/1/ru.html", "source_sha256": "b" * 64,
+            }]), encoding="utf-8")
+            checkpoint = root / "checkpoint.json"
+            state = {
+                "schema_version": 2,
+                "url": "http://os:9200",
+                "cluster_uuid": "cluster",
+                "index": "candidate",
+                "index_uuid": "index-uuid",
+                "input": str(input_root.resolve()),
+                "manifest_sha256": hashlib.sha256((input_root / "manifest.sqlite3").read_bytes()).hexdigest(),
+                "limit": None,
+                "alias": "current",
+                "last_document_code": "1",
+                "complete": False,
+            }
+            checkpoint.write_text(json.dumps(state), encoding="utf-8")
+
+            with (
+                patch("search.minjust_opensearch.request_json", side_effect=[
+                    {"cluster_uuid": "cluster"},
+                    {"candidate": {"settings": {"index": {"uuid": "index-uuid"}}}},
+                    {"errors": False, "items": [{"index": {}}]},
+                    {"candidate": {"aliases": {"current": {}}}},
+                ]) as request,
+                patch("search.minjust_opensearch.validate_candidate_index") as validate_candidate,
+            ):
+                self.assertEqual(
+                    load_bulk(
+                        input_root, "http://os:9200", "candidate", resume=True, checkpoint=checkpoint,
+                        alias="current", expected_old_index="previous", canary_ru="закон", canary_ky="мыйзам",
+                    ),
+                    (1, 1),
+                )
+            self.assertTrue(json.loads(checkpoint.read_text(encoding="utf-8"))["complete"])
+            self.assertEqual(request.call_args_list[-1].args[1], "GET")
+            validate_candidate.assert_called_once_with("http://os:9200", "candidate", 1, "закон", "мыйзам")
+
+    def test_zero_fragment_candidate_never_reaches_alias_switch(self):
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary) / "normalized"
+            document = root / "documents/1"
+            document.mkdir(parents=True)
+            with closing(sqlite3.connect(root / "manifest.sqlite3")) as connection:
+                connection.execute("CREATE TABLE documents (code TEXT, state TEXT)")
+                connection.execute("INSERT INTO documents VALUES ('1', 'success')")
+            (document / "document.json").write_text(
+                json.dumps({"source_code": "1", "editions": []}), encoding="utf-8"
+            )
+            with (
+                patch("search.minjust_opensearch.request_json", side_effect=[
+                    {}, {"cluster_uuid": "cluster"},
+                    {"test-index": {"settings": {"index": {"uuid": "index"}}}},
+                ]) as request,
+                patch("search.minjust_opensearch.validate_candidate_index") as validate_candidate,
+                patch("search.minjust_opensearch.switch_alias") as switch,
+            ):
+                with self.assertRaisesRegex(ValueError, "empty expected fragment inventory"):
+                    load_bulk(
+                        root, "http://127.0.0.1:9200", "test-index",
+                        checkpoint=Path(temporary) / "checkpoint.json", alias="current",
+                        expected_old_index="old-index", canary_ru="закон", canary_ky="мыйзам",
+                    )
+            self.assertEqual(request.call_count, 3)
+            validate_candidate.assert_not_called()
+            switch.assert_not_called()
+
+    def test_candidate_index_requires_exact_count_and_both_language_canaries(self):
+        from search.minjust_opensearch import validate_candidate_index
+
+        with patch("search.minjust_opensearch.request_json", side_effect=[
+            {"_shards": {"failed": 0}},
+            {"count": 2},
+            {"hits": {"hits": [{"_source": {"text_ru": "тест"}}]}},
+            {"hits": {"hits": [{"_source": {"text_ky": "сыноо"}}]}},
+        ]) as request:
+            validate_candidate_index("http://os:9200", "candidate", 2, "тест", "сыноо")
+        self.assertEqual(request.call_count, 4)
+        with patch("search.minjust_opensearch.request_json", side_effect=[
+            {"_shards": {"failed": 0}}, {"count": 1}
+        ]):
+            with self.assertRaisesRegex(RuntimeError, "expected 2"):
+                validate_candidate_index("http://os:9200", "candidate", 2, "тест", "сыноо")
+        with patch("search.minjust_opensearch.request_json", side_effect=[
+            {"_shards": {"failed": 0}}, {"count": 2},
+            {"hits": {"hits": [{"_source": {"text_ru": "тест"}}]}},
+            {"hits": {"hits": []}},
+        ]):
+            with self.assertRaisesRegex(RuntimeError, "ky canary"):
+                validate_candidate_index("http://os:9200", "candidate", 2, "тест", "сыноо")
 
     def test_exports_atomic_bulk_and_rejects_mismatched_fragment(self):
         with tempfile.TemporaryDirectory() as temporary:
@@ -160,13 +317,16 @@ class MinjustOpenSearchTest(unittest.TestCase):
                 document_codes(root / "normalized", 1, "8")
 
             checkpoint = root / "checkpoint.json"
-            with patch("search.minjust_opensearch.request_json") as request:
+            with (
+                patch("search.minjust_opensearch.request_json") as request,
+                patch("search.minjust_opensearch.validate_candidate_index") as validate_candidate,
+                patch("search.minjust_opensearch.switch_alias") as switch,
+            ):
                 request.side_effect = [
                     {},
                     {"cluster_uuid": "cluster-1"},
                     {"test-index": {"settings": {"index": {"uuid": "index-1"}}}},
                     {"errors": False, "items": [{"index": {}}, {"index": {}}]},
-                    {"acknowledged": True},
                 ]
                 self.assertEqual(
                     load_bulk(
@@ -176,11 +336,19 @@ class MinjustOpenSearchTest(unittest.TestCase):
                         maximum_bytes=4096,
                         checkpoint=checkpoint,
                         alias="test-current",
+                        expected_old_index="test-index-old",
+                        canary_ru="закон",
+                        canary_ky="мыйзам",
                     ),
                     (2, 2),
                 )
-                self.assertEqual(request.call_args_list[-2].args[3], "application/x-ndjson")
-                self.assertEqual(request.call_args_list[-1].args[:2], ("http://127.0.0.1:9200/_aliases", "POST"))
+                self.assertEqual(request.call_args_list[-1].args[3], "application/x-ndjson")
+                validate_candidate.assert_called_once_with(
+                    "http://127.0.0.1:9200", "test-index", 2, "закон", "мыйзам"
+                )
+                switch.assert_called_once_with(
+                    "http://127.0.0.1:9200", "test-index", "test-current", "test-index-old"
+                )
             state = json.loads(checkpoint.read_text(encoding="utf-8"))
             self.assertEqual(state["last_document_code"], "7")
             self.assertTrue(state["complete"])
@@ -191,7 +359,11 @@ class MinjustOpenSearchTest(unittest.TestCase):
             legacy["last_document_code"] = "8"
             legacy["complete"] = False
             checkpoint.write_text(json.dumps(legacy), encoding="utf-8")
-            with patch("search.minjust_opensearch.request_json") as request:
+            with (
+                patch("search.minjust_opensearch.request_json") as request,
+                patch("search.minjust_opensearch.validate_candidate_index") as validate_candidate,
+                patch("search.minjust_opensearch.switch_alias"),
+            ):
                 request.side_effect = [
                     {"cluster_uuid": "cluster-1"},
                     {"test-index": {"settings": {"index": {"uuid": "index-1"}}}},
@@ -226,6 +398,9 @@ class MinjustOpenSearchTest(unittest.TestCase):
                         resume=True,
                         checkpoint=checkpoint,
                         alias="test-current",
+                        expected_old_index="test-index-old",
+                        canary_ru="закон",
+                        canary_ky="мыйзам",
                     )
             with patch("search.minjust_opensearch.request_json") as request:
                 request.side_effect = [
@@ -256,12 +431,18 @@ class MinjustOpenSearchTest(unittest.TestCase):
                         resume=True,
                         checkpoint=checkpoint,
                         alias="test-current",
+                        expected_old_index="test-index-old",
+                        canary_ru="закон",
+                        canary_ky="мыйзам",
                     )
-            with patch("search.minjust_opensearch.request_json") as request:
+            with (
+                patch("search.minjust_opensearch.request_json") as request,
+                patch("search.minjust_opensearch.validate_candidate_index") as validate_candidate,
+                patch("search.minjust_opensearch.switch_alias"),
+            ):
                 request.side_effect = [
                     {"cluster_uuid": "cluster-1"},
                     {"test-index": {"settings": {"index": {"uuid": "index-1"}}}},
-                    {"acknowledged": True},
                 ]
                 self.assertEqual(
                     load_bulk(
@@ -272,11 +453,16 @@ class MinjustOpenSearchTest(unittest.TestCase):
                         resume=True,
                         checkpoint=checkpoint,
                         alias="test-current",
+                        expected_old_index="test-index-old",
+                        canary_ru="закон",
+                        canary_ky="мыйзам",
                     ),
                     (1, 0),
                 )
-                self.assertTrue(all(call.args[1] == "GET" for call in request.call_args_list[:-1]))
-                self.assertEqual(request.call_args_list[-1].args[1], "POST")
+                self.assertTrue(all(call.args[1] == "GET" for call in request.call_args_list))
+                validate_candidate.assert_called_once_with(
+                    "http://127.0.0.1:9200", "test-index", 2, "закон", "мыйзам"
+                )
 
             state["last_document_code"] = "9"
             state["complete"] = False
@@ -295,6 +481,9 @@ class MinjustOpenSearchTest(unittest.TestCase):
                         resume=True,
                         checkpoint=checkpoint,
                         alias="test-current",
+                        expected_old_index="test-index-old",
+                        canary_ru="закон",
+                        canary_ky="мыйзам",
                     )
 
             failed_checkpoint = root / "failed-checkpoint.json"
@@ -341,6 +530,9 @@ class MinjustOpenSearchTest(unittest.TestCase):
                         resume=True,
                         checkpoint=checkpoint,
                         alias="test-current",
+                        expected_old_index="test-index-old",
+                        canary_ru="закон",
+                        canary_ky="мыйзам",
                     )
 
             http_error = urllib.error.HTTPError(

deploy/production/README.md

@@ -110,3 +110,55 @@ Follow the procedures in [`BACKUP.md`](../../docs/operations/BACKUP.md),
 
 Automated production deployment is not enabled. Deployments remain owner-run;
 record the release and verify service health before considering it complete.
+
+## Image release and owner-run cutover
+
+PR CI still builds both production images with Kaniko `--no-push`. The separate
+`Release production images` workflow is manual and runs only when dispatched
+from protected `main`. It requires repository secrets named
+`REGISTRY_USERNAME` and `REGISTRY_PASSWORD`; without them it fails before any
+build. Configure those secrets only after the owner confirms a dedicated
+Gitea account/token with write access to the two repository packages and no
+unneeded administration rights. Do not reuse a runner or production host
+credential. The workflow uses the Gitea host and fixed package namespace
+`git.vakanaut.ru/admin/akyldash/{backend,opensearch}`, pushes unique
+commit/run-ID tags, captures registry digests, validates the release
+descriptor, and uploads the JSON plus SHA-256 sidecar as a Gitea Actions
+artifact using a full-SHA-pinned Gitea-compatible v3 action. PR CI also uploads
+a tiny synthetic marker with one-day retention to verify the runner's runtime
+artifact path without registry credentials. The runner cache stays disabled;
+artifact compatibility is based on the runtime API supported by act_runner
+0.2.13/Gitea 1.25.5 and will be empirically checked by PR CI. Registry and
+artifact retention must preserve release digests and descriptors for the full
+rollback window; the owner must confirm both policies.
+
+The schema-v3 descriptor records source repository/ref/commit, workflow run ID,
+pinned Kaniko builder and both image digests. It is an unsigned trace record,
+not a cryptographic attestation; deployment relies on retrieving it from the
+authenticated Gitea run artifact and verifying its checksum and repository
+allowlist. Do not treat the sidecar alone as proof of authenticity.
+
+For a future owner-approved cutover, use the root-owned checkout and run
+`infra/deploy/deploy_release.py` as root with the downloaded manifest, its
+matching verified cold backup, and `infra/deploy/release-policy.json`, plus
+owner-verified non-empty Russian and Kyrgyz canary queries, for example
+`--canary-ru '<known Russian query>' --canary-ky '<known Kyrgyz query>'`.
+The helper checks both queries against the public Search API through local
+HTTPS after Compose reports healthy, and requires at least one result with a
+document code before recording the new release state. Select queries only
+after corpus/index canaries have been verified; do not use generic terms that
+can match unrelated test data. The helper requires the backup image references and image IDs to match the live
+stack, serializes deploy and rollback with `/run/akyldash-deploy.lock`,
+atomically switches both protected env image refs, and always runs Compose with
+`--no-build`. It records recovery state before changing references. If ref
+replacement reports an error after an atomic rename, recovery rereads the
+actual file and restores the prior pair before restarting; an unexpected or
+unverifiable pair stops recovery and leaves a secret-free journal. A failed
+cutover refuses a subsequent release until an owner resolves the journal.
+Rollback accepts a digest-pinned previous release
+only when that backup matches the separately recorded previous refs and image
+IDs. Legacy tag rollback remains supported. Neither the helper nor registry
+secrets are installed on the VPS by this PR; deployment remains an owner-only
+operation and must wait for host/data/backup review. The exact sanitized
+evidence required from the owner is listed in
+[`DEPLOYMENT_OWNER_PACKET.md`](../../docs/operations/DEPLOYMENT_OWNER_PACKET.md).

docs/development/DELIVERY_POLICY.md

@@ -0,0 +1,177 @@
+# Delivery First: проверка изменений по риску
+
+Эта политика помогает быстро принимать небольшие изменения и добавляет
+проверки там, где ошибка затрагивает пользователей, данные или границы
+безопасности. Класс риска выбирает глубину проверки; он не позволяет снять
+обязательную проверку, одобрение или защиту `main`.
+
+## Порядок работы
+
+1. До реализации укажи в PR `LOW`, `MEDIUM` или `HIGH` и коротко объясни
+   причину. Если изменение пересекает несколько областей, выбери самый высокий
+   класс. При неопределённости используй более высокий класс.
+2. Сначала проследи путь изменения от пользовательского/API входа до данных,
+   внешних систем и отката. Для изменения поведения добавь регрессионный тест,
+   который подтверждает конкретный контракт или прежний дефект.
+3. Запусти проверку именно затронутого поведения и обычный Gitea CI. Для UI
+   дополнительно выполни `cd tools/frontend-visual-review && npm ci && npm test`;
+   этот браузерный набор сейчас не входит в Gitea CI.
+4. В PR перечисли класс риска, команды и результаты, остаточные ограничения,
+   а для high-risk — совместимость, угрозы и безопасный rollback. Не заявляй
+   проверку, которой фактически не было.
+5. Ревьюер отделяет блокирующие дефекты от улучшений. Блокер должен указывать
+   конкретное место, условие воспроизведения и последствие. Стилистические
+   предпочтения и предложения на будущее фиксируются отдельно и не задерживают
+   PR.
+
+## Классы риска
+
+| Класс | Когда применять | Требуемое подтверждение |
+|---|---|---|
+| `LOW` | Документация, комментарии, переименование без изменения поведения, форматирование без изменения конфигурационной семантики. Нет изменения контракта, доступа, данных или исполнения. | Проверить diff и сверить утверждения/команды с исходным кодом и действующей процедурой. Выполнить обычный CI. Если документация меняет операторский шаг, проверить его в безопасном локальном или synthetic окружении. |
+| `MEDIUM` | Ограниченное изменение поведения одного компонента, внутреннего API, UI или локального скрипта без изменения модели доверия и формата хранимых данных. | Целевые тесты затронутого компонента и регрессионная проверка, если меняется поведение; обычный CI. Для UI приложить результаты браузерного набора и synthetic визуальной проверки, если они относятся к изменённому экрану/потоку. Проверить обратную совместимость публичных запросов и ответов. |
+| `HIGH` | Авторизация и роли; secrets и credential flow; ingestion и происхождение данных; формат/миграция хранилища; backup/restore/recovery; production config; runner, CI и supply chain; безопасность; сетевые/host-границы; deploy и rollback. | Обычный CI плюс целевые проверки каждого затронутого trust/data boundary; regression-тест; проверка негативного пути и совместимости; независимое ревью конкретных угроз и последствий. Для операций с данными использовать synthetic/staging данные и план отката. Изменение production допускается только владельцем после отдельного согласования, проверки backup и готового rollback. |
+
+Нельзя понижать класс из-за малого diff, срочности или простоты реализации:
+маленькое изменение правила доступа или восстановления всё равно `HIGH`.
+Нельзя считать отсутствие найденных тестов доказательством отсутствия риска.
+
+## CI и ограничения Gitea
+
+Проверенная конфигурация проекта:
+
+- Репозиторий `admin/akyldash`, Gitea API вернул `1.25.5` 2026-10-24.
+- Workflow `.gitea/workflows/ci.yaml` запускается на `pull_request` и `push` в
+  `main`; job ID, который следует сохранять для совместимости статусов, —
+  `tests-and-images`.
+  Он последовательно выполняет backend, Telegram, backup/restore, shell guards,
+  deployment tests, Compose/Caddy validation и две production image builds.
+- `.gitea/workflows/runner-smoke.yaml` сохраняет отдельный job ID `runner-smoke`
+  и проверяет runtime-изоляцию job-контейнера: отсутствие системного и
+  rootless Docker socket, production env/secrets и host checkout. Smoke дополняет
+  статические проверки runner/CI и не дублирует их.
+- Инфраструктурная конфигурация репозитория закрепляет официальный
+  `act_runner 0.2.13`, label `akyldash-ci`, capacity 1 и ограничения job 2 CPU,
+  3 GiB RAM, 512 процессов, 15 GiB store. Версия runner и лимиты приведены по
+  IaC; в рамках этой задачи VPS не проверялся. Job-контейнеры не должны получать
+  ни один Docker socket.
+- Текущая политика `main` из branch API: ветка защищена и требует одного
+  одобрения. На момент проверки API также сообщил `enable_status_check=false`
+  и пустой список status contexts. Это PR не меняет branch protection.
+  Если владелец отдельно включит обязательные статусы, сначала проверьте их
+  точные контексты: `CI / tests-and-images (pull_request)` и
+  `Runner smoke test / runner-smoke (pull_request)`. Не переименовывайте job IDs.
+
+Функции и границы текущих проверок:
+
+| Блок workflow | Назначение и риск пропуска | Перекрытие |
+|---|---|---|
+| Checkout и Python setup | Подготовка повторяемой среды; пропуск может дать ложный успех на неподходящем образе. | Инфраструктурный шаг, не покрывается тестами приложения. |
+| Backend и Telegram tests | Регрессии API, логики поиска/аккаунтов и Telegram bot. Риск продуктовый; для auth/data изменений — `HIGH`. | Разные пакеты и контракты; отдельная ветка тестов. |
+| Backup/restore tests | Целостность backup, восстановление и отказные сценарии; риск потери данных — `HIGH`. | Не дублируется тестами backend. |
+| Bootstrap/recovery/verifier/host-audit/production-config guards | Отказ от root и защиты host identity, аргументов и production paths; обход может дать административное действие или затронуть host — `HIGH`. | Несколько guard-тестов проверяют разные скрипты и условия; считать их дублями без анализа каждого контракта нельзя. |
+| Runner config, installer guards и CI container isolation | Ограничения runner, repeatability установки и запрет socket/privileged/host mounts; риск — доступ к host/production — `HIGH`. | Статические/синтетические проверки дополняются реальным runtime smoke, это разные уровни. |
+| Shell syntax и Python AST parse | Раннее обнаружение ошибок парсинга; риск пропуска — поломка запуска скрипта/проверки. | Это синтаксис, а не функциональные тесты. |
+| Deployment contract/rollback tests, Compose config и Caddy validation | Совместимость deploy contract/rollback и конфигурации production stack/proxy; риск — deploy outage/data impact — `HIGH`. | Compose проверяет интерпретацию конфигурации, Caddy — синтаксис proxy, Python suite — contract/rollback logic. Функции отличаются. |
+| Две Kaniko image builds | Проверка Dockerfile и воспроизводимости backend/OpenSearch production images; риск — сломанная сборка/небезопасный путь supply chain — `HIGH`. | Два Dockerfile — две разные целевые images; build-only, оба `--no-push`. |
+| Runner smoke (отдельный workflow) | Runtime-проверка известного системного socket path, production paths/secrets и host checkout отсутствия в job; риск — нарушение изоляции — `HIGH`. | Дополняет статические runner/CI guards; не повторяет их. |
+
+Gitea API не предоставляет пригодный список steps для завершённого run в этой
+версии; длительность каждой строки таблицы поэтому `N/A`. Не распределяй общий
+CI runtime между блоками пропорционально числу тестов или строк кода.
+
+Gitea 1.25 документация подтверждает используемые события `push`,
+`pull_request` и `workflow_dispatch`. Она также документирует ограничения,
+которые запрещают строить безопасное ускорение на привычных GitHub Actions
+предположениях:
+
+- `runs-on` поддерживает статическую метку или список меток; текущая
+  `akyldash-ci` — статическая метка.
+- Выражения доступны ограниченно; в сравнении с GitHub Actions Gitea 1.25
+  обещает функцию `always()`, поэтому workflow не должен зависеть от
+  `if:`-выражений для динамического выбора набора тестов по diff или уровню
+  риска.
+- `jobs.<job_id>.timeout-minutes`, `permissions`, `concurrency` и
+  `jobs.<job_id>.environment` в Gitea 1.25 игнорируются. Не используйте их как
+  защиту, срок исполнения, обязательный approval или средство экономии.
+- У runner capacity 1. Разделение текущей последовательной работы на
+  параллельные jobs не даёт измеримого параллельного исполнения на этом runner
+  и может добавить запуск/очередь. Сохраняйте проверку сборки обеих production
+  images: она подтверждает Dockerfiles, но использует Kaniko с `--no-push` и не
+  публикует образы.
+
+Источники семантики: [Gitea 1.25 Actions comparison](https://docs.gitea.com/1.25/usage/actions/comparison/),
+[Gitea 1.25 Actions FAQ](https://docs.gitea.com/1.25/usage/actions/faq/) и
+[act_runner guide](https://docs.gitea.com/1.25/usage/actions/act-runner/).
+Перед использованием новой workflow-семантики сверяй её с документацией
+установленной версии и проверяй фактическим run. Не добавляй проверки самой
+этой политики или статические тесты, утверждающие её текст.
+
+## Временные ориентиры и фактические измерения
+
+Ориентиры — цель для поиска затрат, а не разрешение убрать тесты:
+
+- Обычный полный CI: до 5 минут от старта job до завершения. При превышении
+  сначала измерить и оптимизировать узкий участок, сохраняя тесты и изоляцию.
+- Расширенный путь для `HIGH` (обычный CI плюс целевые проверки): целевой
+  суммарный интервал 10–15 минут. Это пока ориентир, а не отдельный
+  автоматический workflow или установленный timeout.
+
+Срез 2026-10-24 получен из документированного [Gitea Actions task API](https://docs.gitea.com/api/1.25/operations/list-action-tasks/)
+`/repos/admin/akyldash/actions/tasks?limit=50`. Взяты 20 последних завершённых
+`tests-and-images`; длительность оценена как `updated_at - run_started_at`:
+
+| Метрика | Измерение |
+|---|---:|
+| CI completed sample | 20 прогонов, 20 success |
+| CI median | 147.5 s (2:27.5) |
+| CI p90 | 172 s (2:52) |
+| CI max | 192 s (3:12) |
+| Runner smoke median / max | 2 s / 3 s, последние 20 прогонов |
+
+Прежней reconciliation или оценок длительности в доступной документации
+репозитория, workflows, PR и issues не найдено; этот срез является первой
+подтверждённой базой, и сравнить его с прежней оценкой нельзя.
+Все 20 измеренных полных CI прогонов ниже пяти минут; текущая конфигурация уже
+достигает обычного ориентира. Отдельного extended workflow нет, поэтому
+10–15-минутная цель пока не имеет фактической базы. В выборке нет breakdown по
+steps: документированный endpoint для jobs завершённого run возвратил пустой
+список; это известное ограничение Gitea 1.25.5 ([upstream issue #38286](https://github.com/go-gitea/gitea/issues/38286)).
+Не распределяй время между тестами и image builds по предположению. При будущих
+изменениях workflow записывай доступные timestamps и точный размер выборки;
+после изменения Gitea/runner перепроверь, стал ли доступен надёжный step timing.
+
+## Метрики потока поставки
+
+Для каждого релиза/месячного обзора отдельно собирать:
+
+| Метрика | Определение и источник |
+|---|---|
+| Ready → merge | Время с момента, когда PR реально готов к ревью, до merge. Не подменять датой создания draft PR; при отсутствии точного ready timestamp записывать `N/A`. |
+| Merge → deploy | Merge timestamp до фактического production deploy timestamp. Deploy пока не автоматизирован; пока нет подтверждённого deploy evidence, записывать `N/A`, не ноль. |
+| CI duration | `run_started_at` → task completion (`updated_at`) по Actions API; отдельно указывать медиану, p90, максимум, период и число прогонов. |
+| Повторные прогоны | Число неуспешных/повторных прогонов на commit до первого успеха; отличать rerun от нового commit/push. |
+| Блокирующие замечания | Число ревью-находок, удовлетворяющих критериям blockers выше; неблокирующие считать отдельно. |
+| Вышедшие регрессии | Подтверждённые после merge дефекты, связанные с изменением; фиксировать компонент, тяжесть и пропущенный сигнал. |
+| Rollback | Количество фактически выполненных rollback, причина и результат проверки данных/сервиса. Не считать написанный план фактическим rollback. |
+
+На момент этого аудита PR/API не дают надёжного ready timestamp для старых
+изменений; production deployment не автоматизирован, а задачи этого PR не
+содержат deploy telemetry. Поэтому ready→merge, merge→deploy, escaped
+regressions и rollback baseline остаются `N/A`, пока не появится проверяемая
+запись. Не придумывай значения из `created_at` или даты последнего update.
+
+## Критерий блокирующего ревью
+
+Блокирующие замечания ограничены случаями:
+
+- воспроизводимый дефект с конкретным условием и последствием;
+- расширение доступа, утечка секрета или обход границы runner/production;
+- потеря/искажение данных или несовместимость API/storage без безопасного пути;
+- обязательный тест или подтверждение из таблицы риска отсутствует/не проходит;
+- опасная операция не имеет проверяемого backup/rollback плана.
+
+Каждый блокер содержит файл/участок, шаги воспроизведения или точное условие,
+последствие и минимальный безопасный fix. Остальные замечания — отдельный
+неблокирующий список. Review и approval остаются за людьми; агент не начинает
+review сам и не сливает PR.

docs/operations/BACKUP.md

@@ -2,130 +2,79 @@
 
 ## Current status
 
-No production data or backup existed during the 2026-10-11 audit. The repository
-now contains `infra/backup/archive.py`; it is not installed or run on the VPS,
-and `/var/backups/akyldash` remains a planned root-only location.
+The owner requires that a complete production archive never be written to the
+VPS, even temporarily. The reviewed implementation in PR #59 streams stopped
+Compose state directly from the root receiver to the owner's Windows client;
+the client stores it only under `D:\Dev\akyldash\.backups`. The VPS retains
+only a secret-free identity (backup ID, size, archive and manifest hashes,
+manifest) in root-owned release state. The Windows rerun passed 12 synthetic
+client checks, 8 protocol checks, and a disposable real-NTFS private owner-ACL
+fixture. The production D: path, SSH connection, VPS installation, and
+full production backup remain unverified. There is no verified production
+backup, so production deployment remains blocked.
 
-## Required release policy
+## External backup flow
 
-- Create a backup before every production change, including any future schema
-  or index migration.
-- Include the normalized corpus, `search-users.sqlite3`,
-  `search-reviews.sqlite3`, the OpenSearch index/snapshot, deployment digest,
-  Caddy's certificate data, and required secret file in the protected backup
-  set. Store secrets and Caddy private keys with equivalent access controls.
-- Verify archive readability, checksums, and SQLite integrity before relying
-  on it. Never overwrite or delete the only usable backup.
-- Keep one current pre-release backup. If deployment fails, retain the backup
-  required to restore the previous state.
-- Test restore into an isolated target before relying on the backup. Do not
-  restore over production as a test.
+- The release receiver takes the shared deployment lock and stops the stack.
+- It streams a tar/gzip archive through a bounded binary SSH session. It does
+  not create a local archive or temporary full-size copy on the VPS.
+- The Windows receiver requires the exact D: repository, a real NTFS path,
+  restrictive ACLs, and the exact `/.backups/` rule in that checkout's local
+  `.git/info/exclude`. Before SSH connects, it also requires at least 100 GiB
+  plus 1 MiB of free D: space, matching the protocol's maximum archive size.
+  The ACL owner and every allowed full-control entry must be the current user,
+  SYSTEM, or local Administrators; other and deny entries fail closed.
+  It writes into a private staging directory, checks the
+  stream size and SHA-256, verifies the archive and manifest, then publishes
+  the complete backup directory without overwriting an existing ID. It checks
+  the published ACL before acknowledging; on failure it removes only the same
+  verified staging directory, and refuses cleanup if its identity or contents
+  have changed.
+- Only after Windows confirms the stored archive identity does the VPS proceed
+  with image cutover. If backup transport or verification fails, it attempts
+  to restart the previous services and records a recovery journal if restart
+  fails.
+- Rollback first challenges Windows with the root-pinned previous backup
+  identity. Windows verifies the local archive and streams it back; the VPS
+  compares its exact size and SHA-256 before stopping services. Rollback then
+  creates a fresh external backup of the current state before changing image
+  references. It restores images only, never application data or OpenSearch
+  state.
 
-## Clean first deployment
+Windows PowerShell is the intended client. The Windows checks exercised the
+destination and ACL rules, including a disposable real-NTFS private owner-ACL
+fixture. The actual production D: destination and SSH path remain unverified.
+An owner must separately test archive restore on an isolated target before
+relying on this path. Do not restore over production as a test.
 
-No backup is needed only when Compose has no containers and all four
-persistent mounts are confirmed empty. For a first install with a preloaded
-corpus and not-yet-created named volumes, use `--initial-deployment` to create
-the pre-start backup. This flag is accepted only with no Compose containers and
-when `DATA_ROOT` contains exactly `minjust-normalized/`; it archives absent
-named volumes as empty components. In every normal backup, an absent volume is
-an error because it could mean that a previous installation lost data.
-Missing mount definitions, inaccessible Docker state, or partial service
-containers are also errors and must stop deployment. Do not create placeholder
-containers to make backup pass.
+## Backup contents and limits
 
-For the corpus-only initial case, run this before the first `up` from the
-approved checkout. Replace the timestamp with one real UTC timestamp:
+The existing `infra/backup/archive.py` manifest records the Git revision,
+deployment-file hashes, image references and IDs, and the components included
+in the archive: application data, OpenSearch, Caddy data/configuration,
+`production.env`, and the review secret. Secret-bearing files and SQLite files
+are archived with restrictive modes. The archive verifier rejects unsafe
+members and checks SQLite integrity. SSH encrypts archive bytes in transit.
+The destination contains secrets and private keys; D: encryption at rest (for
+example, BitLocker) has not been verified. This PR adds no client-side
+encryption or signing, so the owner must verify storage encryption and retain
+the restrictive ACLs before using it.
 
-```bash
-cd /opt/akyldash/current
-sudo python3 infra/backup/archive.py create \
-  --compose-file deploy/production/compose.yaml \
-  --env-file /etc/akyldash/production.env \
-  --initial-deployment \
-  --output /var/backups/akyldash/akyldash-initial-corpus-YYYYMMDDTHHMMSSZ.tar.gz
-sudo python3 infra/backup/archive.py verify /var/backups/akyldash/akyldash-initial-corpus-YYYYMMDDTHHMMSSZ.tar.gz
-```
+The external protocol caps control frames at 64 KiB, chunks at 1 MiB, and the
+archive at 100 GiB. SSH provides transport encryption and server host-key
+verification. The receiver uses a fixed SSH command and does not accept a
+caller-supplied path or shell command. It relies on the existing owner SSH
+configuration; no key, host entry, sudo rule, or VPS setting is added here.
 
-## Cold backup procedure
+## Restore
 
-The script requires every Compose container to be stopped. Schedule downtime,
-then run from the approved checkout on the VPS:
+Use `infra/backup/archive.py restore` only with an archive already present in a
+protected owner-controlled location, and target a new staging directory on an
+isolated recovery host. Review [recovery](RECOVERY.md) and
+[deployment](DEPLOYMENT.md) first. This PR does not perform or authorize a
+production restore, data migration, or VPS operation. Keep the previous
+external archive until the owner has verified the replacement and explicitly
+approved its retention period.
 
-```bash
-cd /opt/akyldash/current
-sudo docker compose --env-file /etc/akyldash/production.env -f deploy/production/compose.yaml stop
-sudo python3 infra/backup/archive.py create \
-  --compose-file deploy/production/compose.yaml \
-  --env-file /etc/akyldash/production.env \
-  --output /var/backups/akyldash/akyldash-YYYYMMDDTHHMMSSZ.tar.gz
-sudo python3 infra/backup/archive.py verify /var/backups/akyldash/akyldash-YYYYMMDDTHHMMSSZ.tar.gz
-```
-
-Replace the timestamp placeholder with one real UTC timestamp before running.
-On a clean first deployment, `create` exits with a clear message that backup
-can be skipped. With existing data and all expected volumes present, it
-archives the storage even when no Compose containers exist. A preloaded corpus
-with no named volumes requires the explicit `--initial-deployment` mode;
-otherwise missing volumes are rejected. Partial service containers or running
-services are rejected as unsafe. The create command archives the application data,
-OpenSearch volume, Caddy data/config volumes, production environment file, and
-review secret. It records the checked-out Git revision, deployment-file hashes,
-and image references/IDs for each stopped Compose service, writes a SHA-256
-sidecar, and refuses to overwrite an existing archive. It also runs SQLite
-`quick_check`. Start the stack again only after verification succeeds:
-
-```bash
-cd /opt/akyldash/current
-sudo docker compose --env-file /etc/akyldash/production.env -f deploy/production/compose.yaml up -d
-```
-
-## Initial post-setup baseline
-
-After the first index has been loaded and validated, the initial `admin` account
-has been created, and `/review` responds over HTTPS, create a second backup.
-This one captures the initialized index, account database, and newly created
-Caddy/OpenSearch volumes. Stop all services, create and verify the archive,
-then start the stack again:
-
-```bash
-cd /opt/akyldash/current
-sudo docker compose --env-file /etc/akyldash/production.env -f deploy/production/compose.yaml stop
-sudo python3 infra/backup/archive.py create \
-  --compose-file deploy/production/compose.yaml \
-  --env-file /etc/akyldash/production.env \
-  --output /var/backups/akyldash/akyldash-initial-baseline-YYYYMMDDTHHMMSSZ.tar.gz
-sudo python3 infra/backup/archive.py verify /var/backups/akyldash/akyldash-initial-baseline-YYYYMMDDTHHMMSSZ.tar.gz
-sudo docker compose --env-file /etc/akyldash/production.env -f deploy/production/compose.yaml up -d
-```
-
-Use one real UTC timestamp in both archive paths. Do not treat initial
-production setup as complete until this baseline archive verifies. Keep the
-pre-start corpus archive as well until the baseline is verified and copied to
-separately managed encrypted storage.
-
-Keep the local archive root-only, then copy it to separately managed encrypted
-storage. A local archive alone does not protect against loss of the VPS disk.
-Restore extracts only to a new `akyldash-restore-*` directory under `/tmp` or
-`/var/tmp` and validates the checksum and SQLite databases. Applying the staged
-contents requires the separate recovery-target tool; it refuses the inventoried
-production host, existing data/volumes, and an unmarked host. Example isolated
-restore:
-
-```bash
-sudo python3 infra/backup/archive.py restore /var/backups/akyldash/backup.tar.gz \
-  --target-dir /var/tmp/akyldash-restore-test
-```
-
-This validates and stages the archive. On the replacement host only, after
-running bootstrap with `--recovery-target` and checking out the matching Git
-revision, apply the staged data:
-
-```bash
-sudo python3 infra/backup/apply_restore.py \
-  --staging-dir /var/tmp/akyldash-restore-test
-```
-
-The apply command restores data and named volumes but leaves services stopped.
-Test the full procedure on a separate recovery host before relying on it. Do
-not run an unreviewed restore over existing data.
+The former `/var/backups/akyldash` create/verify procedure is superseded and
+must not be used for a full production archive on the VPS.

docs/operations/CI_RUNNER.md

@@ -59,10 +59,11 @@ Dockerfiles are built in a separate pinned Kaniko container action with explicit
 job container receives no Docker socket. Kaniko uses `--no-push` and
 `--no-push-cache`, so CI validates the full backend and OpenSearch builds but
 does not publish images or export build output. The two builds run sequentially
-within one job. CI run 69 completed both builds on the runner. Actual per-action
+within one job. CI run 69 completed both builds historically; the latest
+verified main CI run 175 and smoke run 176 succeeded on `b5adc092`. Actual per-action
 resource-limit enforcement and peak memory or disk usage were not independently
-measured or verified. No registry credentials,
-production secrets, elevated container options, or arbitrary host mounts are configured.
+measured or verified. No registry credentials, production service secrets,
+elevated container options, or arbitrary host mounts are configured in PR CI.
 
 The Kaniko action uses the `linux/amd64` v1.28.5-debug manifest
 `sha256:c73ca67a3b494bce79a8fb6090c4f73c18997ab272d80bffc460a62343aeb412`,
@@ -70,7 +71,41 @@ listed in the [official GitHub Packages entry](https://github.com/osscontainerto
 The pinned Caddy image digest remains the same as the former `docker run`
 validation. act_runner starts these container actions; they do not expose its
 rootless Docker socket to workflow steps.
-Production deployment is not automated.
+Production deployment is not enabled. `release-images.yaml` now starts only
+after a successful `CI` workflow run for a push to `main`; it checks the source
+workflow, event, branch, conclusion, and SHA and checks that the SHA is still
+the current `main` before exposing Registry credentials. It checks out that
+exact source SHA and uses the release workflow's own run ID for image tags and
+the schema-v3 descriptor. PR CI remains no-push and receives no Registry or
+production credentials.
+
+Image publication still requires the existing `REGISTRY_USERNAME` and
+`REGISTRY_PASSWORD` Actions secrets, which are not configured or verified.
+When configured, they must be package-write-only for the two approved image
+names. The release descriptor is unsigned. The SHA-256 is included in the
+artifact name so a later workflow can identify the expected digest from
+artifact metadata without treating job output as trusted input. The existing
+SHA-256 sidecar remains inside the artifact. The workflow has not yet run with
+Registry credentials, and the sequential Kaniko build's peak resources have not
+been measured beyond the configured 2 CPU, 3 GiB RAM, 512-process job limits.
+
+`deploy-handoff.yaml` runs after a successful release on `main`. It rechecks the
+source run and stale-SHA guard. Its current mode is explicitly dry-run: it may
+read JSON artifact metadata using the installed `gitea-api` helper when present,
+but it never downloads the ZIP or opens an SSH connection. If the helper is not
+present in the job image, it reports that artifact metadata and host handoff
+remain unverified. No SSH, sudo, production secret, or Docker socket is passed
+to the runner.
+
+Gitea 1.25.5 documents a run-artifact metadata endpoint and a ZIP endpoint that
+redirects to a blob URL. The currently audited `gitea-api` helper supports JSON
+GET requests but has no binary output option and does not follow redirects, so
+it cannot yet fetch and independently verify the host-side artifact. Do not
+enable a live handoff until an owner-approved binary-safe retrieval capability
+validates HTTPS redirects and never forwards the API token across origins. The
+host must independently validate the successful `main` release run, artifact
+name and ZIP sidecar before any guarded deployment. The owner must also verify
+artifact and Registry retention covers the rollback window.
 
 ## Installation and registration
 
@@ -160,10 +195,11 @@ that token; do not put it in command-line arguments or environment variables.
    present in the job container.
 3. Confirm the run reports the expected runner, succeeds, and the runner
    service and health timer remain active.
-4. Inspect the `CI` workflow run and confirm Caddy plus both Kaniko actions pass
-   on `akyldash-ci`. The Kaniko jobs are intentionally build-only: publishing
-   images requires a separately reviewed registry workflow and credentials.
-   Do not add production deploy workflows or secrets to this runner.
+4. Inspect the `CI` workflow run and confirm Caddy plus both no-push Kaniko
+   actions pass on `akyldash-ci`. Image publication is a distinct manual
+   main-only workflow with package-only credentials; it does not deploy.
+   Never add production service secrets, Docker socket access, or host mounts
+   to this runner.
 
 ## Upgrade
 

docs/operations/CORPUS_HANDOFF.md

@@ -171,12 +171,14 @@ to a new staging location with owner-approved permissions, verify the copied
 manifest and files there, and only then consider placing it under `DATA_ROOT`.
 Never overwrite an existing corpus or OpenSearch volume.
 
-The current bulk importer checks individual Bulk API item results, but it can
-switch an alias after a zero-fragment input and does not enforce a refresh,
-count comparison, or representative-query check before that switch. Until a
-separate change adds those gates, do not pass `--alias` during production
-loading. Load into a new versioned index only after the corpus transfer is
-verified; require a nonzero fragment count, successful item results, an
-explicit refresh, a matching OpenSearch document count, and representative
-Russian/Kyrgyz queries before an owner performs an alias change. Take and
-verify the required backup before any production index or service change.
+The bulk importer now refuses alias publication until all Bulk item results
+are successful, the full staged index is refreshed, its fragment count exactly
+matches the complete normalized inventory (including on resume), and approved
+Russian and Kyrgyz canaries both return text. The alias must currently target
+the exact `--expected-old-index`; wildcard removals and implicit first-time
+alias creation are rejected. OpenSearch performs removal of that exact target
+and addition of the candidate in one alias request. A mismatch or validation
+failure leaves the existing alias untouched. This is a code-level gate only:
+no production index or corpus was changed, and the live inventory and canary
+terms still require owner verification. See `backend/README.md` for the
+operator flags and use a new versioned index for every candidate.

docs/operations/CURRENT_STATE.md

@@ -1,10 +1,151 @@
 # Infrastructure current state
 
-Read-only host recheck: 2026-10-18. Source: SSH as `codex`, local repository
-inspection, and Gitea API. Root-only Docker state, UFW rule details, and
-protected file metadata remain unverified.
+## Proposed external deployment runtime binding — 2026-11-01
 
-## VPS facts
+- PR #59 now proposes a root-only read-only status endpoint and exact-literal
+  SSH dispatcher for `status` and `deploy`. The status path bounds the Gitea
+  run list to ten entries, verifies the selected run/workflow/current `main`,
+  validates artifact metadata and ZIP bytes, and returns only a release tuple.
+  It fails closed for a stale host checkout, recovery journal, incomplete
+  listing, or the exact release already recorded as applied. The deploy
+  receiver still independently revalidates and uses the existing lock,
+  recovery journal, cold-backup ACK, cutover, and rollback protections.
+- The Windows client proposes a disabled-by-default `--once` mode with a
+  fixed `D:\Dev\akyldash` target and `akyldash_release` alias. The example
+  config and Task Scheduler XML are both disabled; the template uses an
+  interactive least-privilege owner, ignores overlapping invocations, and
+  does not wake the computer. No Windows task, SSH key, VPS command, helper,
+  or trigger config has been installed or exercised. Production CD remains
+  inactive.
+- Remaining owner prerequisites are exact root forced-command/SSH host-key
+  setup for the dispatcher, installation of the reviewed Windows client under
+  a non-user-writable path, private ACLs for its config and D: backups, a
+  root-controlled checkout matching current `main`, and all previously listed
+  backup/restore and production readiness gates. The status endpoint does not
+  advance the host checkout and refuses to offer a stale release.
+
+Owner decision recorded 2026-10-26: a complete backup must not be stored on
+the VPS, including temporarily. The local archive/full cold-backup commands in
+`BACKUP.md` are superseded and unauthorized. PR #59 now contains a proposed
+Windows-controlled external stream receiver and root-side deploy/rollback
+code. The Windows rerun passed 12 synthetic client checks and 8 protocol
+checks, plus a disposable real-NTFS fixture for the private owner ACL. The
+production D: path, SSH connection, VPS installation, full backup, and
+separate-target restore remain unverified. No verified external backup or
+separate-target restore exists, so production deployment remains blocked by
+the backup gate.
+
+## Code-only deployment work — 2026-10-31
+
+- Work is being prepared in the existing PR #59 branch from the then-current
+  `main`; no merge, VPS operation, live release, or workflow dispatch was
+  performed for this work.
+- The release descriptor now binds both the release run and its successful CI
+  source run. Host-side source verification uses the installed `gitea-api`
+  helper contract; the PR carries the inspected helper fixture plus a bounded
+  binary-download patch. The installer verifies the fixture hash before
+  applying the patch.
+- Backup bytes are streamed through a bounded SSH protocol to the fixed
+  Windows destination. Root release state stores only a secret-free backup
+  identity. The rollback handshake requires the exact previously pinned
+  archive and creates a fresh external backup before image references change.
+  Local VPS archive paths fail closed.
+- Review fixes in this PR require Gitea `status=completed` with
+  `conclusion=success`, resolve `main` from `/opt/akyldash/current`, write a
+  durable pending journal before stopping services, and reject an already
+  applied release before downtime. The Windows client checks D: capacity,
+  NTFS/path/ACL owner and allowed entries, and the local ignore rule before
+  SSH; it requires 100 GiB plus 1 MiB free. The Windows rerun passed 12
+  synthetic client checks, 8 protocol checks, and a disposable real-NTFS
+  private owner-ACL fixture; actual D:, SSH, and VPS remain unverified.
+- Receiver cleanup after a post-publication ACL failure is identity-bound to
+  the owned staging directory and permits only the expected archive files. A
+  replaced, reparse, or unexpected target is left for manual review without an
+  ACK; this path is covered by local fixtures and the Windows rerun.
+- Synthetic tests cover archive/protocol integrity, helper download rules,
+  artifact/run provenance, receiver publication, release schema, and rollback
+  refusal. The 12 synthetic Windows client checks, 8 protocol checks, and
+  disposable real-NTFS private owner-ACL fixture passed. The actual D: path,
+  SSH alias, Gitea helper against
+  the live instance, root helper installation, artifact redirect, production
+  backup/restore, and actual release/rollback remain unverified.
+- Owner bootstrap blockers remain: verify a root-controlled SSH route for the
+  fixed commands using existing host-key checking; provision only the
+  necessary read-only Gitea token, exact redirect origin if needed, and
+  approved RU/KY canaries; confirm registry pull and retention policy; test
+  the Windows client and a separate-target restore. No new key, sudo rule,
+  Docker access, credential, or VPS setting is added by the code change.
+
+Read-only deployment recheck: 2026-10-25. Source: SSH as `codex`, direct-origin
+and public HTTPS probes, local `main` checkout, and Gitea API. No VPS files,
+services, firewall, containers, volumes, production data, or credentials were
+changed or inspected. Root-only Docker state, UFW rule details, protected file
+metadata, current backup/restore validity, and the live corpus/index remain
+unverified. The 2026-10-18 inventory below is a historical snapshot where it
+conflicts with this dated recheck.
+
+## Latest read-only recheck — 2026-10-25
+
+- `https://akyldash.kg/review` returned HTTP 200 with valid TLS through the
+  public Cloudflare edge and through direct HTTPS to origin `206.223.249.118`.
+  This verifies that route only; it does not prove search or index readiness.
+- TCP listeners now include 22, 80, and 443. The older no-listener/Cloudflare
+  521 observations below are historical, not current state.
+- VPS reports 4 CPUs, 7.7 GiB RAM (about 3.7 GiB available), and 31 GiB free
+  on `/`. Current runner-mount free space was not rechecked.
+- `/opt/akyldash/current` exists, is a root-owned directory mode `0755`.
+  Reading its Git SHA failed with Git's `dubious ownership` safety guard; no
+  `safe.directory` setting was added, so the installed revision is unknown.
+- `akyldash-act-runner.service` is active under `akyldash-runner`; installed
+  `act_runner` is `0.2.13`. The separate `akyldash-runner-restart.service`
+  remains failed since 2026-10-14; its cause could not be read from the
+  unprivileged journal view. No restart was attempted.
+- `akyldash-verify`, `akyldash-compose`, and `akyldash-rollback` are absent
+  from PATH in the unprivileged check; no root helper or Docker operation was
+  run.
+- Gitea is `1.25.5`; `main` is `b5adc09203cbbbd298054248206b9f47ae4a44ca`.
+  CI run 175 and runner smoke 176 succeeded on that commit. Package write
+  access and runner inventory remain outside this API principal's permissions.
+- PR #59 head `852d639c455ff1c60202405e112d47b8128d66c6` received formal
+  review #308 with five requested fixes. CI run 177 failed in
+  `test_digest_rollback_fails_before_stopping_or_changing_references` because
+  the test's global `Path.stat` mock made `Path.exists()` report a false
+  recovery-journal hit under CI Python 3.12; runner smoke 178 succeeded. A
+  fix batch in this PR isolates state paths, handles ambiguous alias/cutover
+  outcomes, verifies rollback image IDs, and adds a synthetic artifact upload
+  check. On 2026-10-25 CI run 179 and runner smoke 180 succeeded at PR head
+  `9d8ce6b6`; CI took 2m43s and the synthetic upload step reported success.
+  The run API identifies run ID 567 and reports `run_attempt: 0`, Gitea's
+  legacy sentinel. The release workflow therefore uses the unique run ID and
+  does not depend on the unavailable attempt value. The run's artifact link was
+  downloaded from Gitea UI as `artifact-smoke-567-`: the ZIP was 191 bytes,
+  SHA-256 `ae0a2262147f222aacb4fdd1d12459f7160c67b1d0ee5d7ae2db1de8958f120f`,
+  and contained the expected 51-byte `marker.txt`. The API artifact listing
+  available to this principal returned no entries, but the downloaded file
+  verifies artifact availability. No live release or VPS change was made.
+- The release descriptor SHA-256 sidecar now records `release-manifest.json`
+  relative to the `release` directory, matching the flattened layout observed
+  for downloaded Gitea artifacts. A local synthetic regression verifies the
+  checksum from the artifact extraction root; the credentialed release
+  workflow remains unrun.
+- Owner-only outstanding evidence: sanitized container/volume and protected
+  file metadata; current backup and separate-target restore verification;
+  live corpus/index counts and RU/KY canaries; Cloudflare TLS mode; registry
+  writer identity and digest retention. Never include secret values in that
+  evidence packet. The checklist is in
+  [`DEPLOYMENT_OWNER_PACKET.md`](DEPLOYMENT_OWNER_PACKET.md).
+
+The deployment PR adds a manual main-only image-publish workflow and an
+owner-run `--no-build` cutover path, but neither has been executed against the
+VPS. Its release descriptor is an unsigned trace record; cryptographic image
+attestation remains a separate owner decision.
+
+## Historical host snapshot — 2026-10-18
+
+Source: SSH as `codex`, local repository inspection, and Gitea API. Root-only
+Docker state, UFW rule details, and protected file metadata were not verified.
+
+## Historical VPS facts — 2026-10-18
 
 - Host: `avprogs.hlab.kz`, `206.223.249.118`, SSH port `22`, user `codex`.
 - OS: Ubuntu Server `24.04.5 LTS`; kernel `6.8.0-142-generic` from the prior
@@ -42,13 +183,11 @@ protected file metadata remain unverified.
   and `git.vakanaut.ru` resolves to `195.209.48.28`. From the VPS,
   `https://git.vakanaut.ru/api/v1/version` returned Gitea `1.25.5`; runner
   registration and Gitea Actions protocol connectivity are not confirmed.
-- `akyldash.kg` resolves to Cloudflare IPv4/IPv6 edge addresses. From the VPS,
-  HTTPS returned Cloudflare `521` with TLS verification result `0` on
-  2026-10-18. TCP listeners were SSH `22` and local DNS only, so no origin
-  listener on `80`/`443` was observed. Origin TLS and Cloudflare Full (strict)
-  are not verified.
+- `akyldash.kg` resolved to Cloudflare IPv4/IPv6 edge addresses. HTTPS returned
+  Cloudflare `521` on this historical 2026-10-18 check; current recheck is
+  recorded above. Cloudflare Full (strict) mode remains unverified.
 
-## Application and Gitea facts
+## Historical application and Gitea facts — 2026-10-18
 
 - Repository: `admin/akyldash`, default branch `main`; Gitea version `1.25.5`.
 - The repository API reports push permission, Actions and packages enabled, and
@@ -87,23 +226,46 @@ protected file metadata remain unverified.
   The mode has not been run on a VPS.
 - The repository defines a root-owned read-only verifier, Compose `config` and
   `status` helper, guarded rollback helper, and installer with exact sudoers
-  command rules. None is installed on the VPS. CI contains no production
-  deployment job; starting/stopping services remains owner-run.
-- Rollback preflight validates digest-pinned image references against archived
-  image IDs and local availability, then refuses before stopping services or
-  creating a backup because the current flow cannot safely switch immutable
-  digest references. This behavior is covered by synthetic local tests; it has
-  not been exercised on the VPS.
-- This branch adds an offline release-manifest validator and tests for the
-  repository allowlist intended for a future root-owned host integration. The
-  manifest format does not prove source provenance. No registry, host policy,
-  publish credential, or deployment integration is configured or installed.
+  command rules. None was installed on the VPS at this inventory. The current
+  PR adds fixed root-side release/rollback receivers without adding a `codex`
+  sudoers rule or Docker access. Neither receiver has been installed or run.
+- The former local-VPS rollback path has been superseded and now fails closed.
+  The PR rollback path requires a root-pinned external archive identity,
+  rechecks its exact bytes through the owner client, creates a fresh external
+  backup before changing refs, and preserves a secret-free recovery journal on
+  failure. Synthetic tests only; no production rollback was performed.
+- The image release workflow now starts after successful CI for a push to
+  `main`. It checks the source workflow/event/branch/conclusion and exact source
+  SHA, checks out that SHA, and uses both release and source run IDs in the
+  schema-v4 descriptor. Registry secrets `REGISTRY_USERNAME` and
+  `REGISTRY_PASSWORD` remain unconfigured/unverified; no values were created or
+  inspected. PR image builds remain no-push. The descriptor SHA-256 is included
+  in the artifact name, and the artifact also retains its checksum sidecar.
+  The descriptor remains unsigned trace metadata, not cryptographic
+  attestation.
+- A separate `deploy-handoff.yaml` runs after a successful release and checks
+  the source run and stale-main guards. Its job is explicitly
+  `NOT DEPLOYED - handoff status only`; a green result is not a deployment. It
+  reads artifact metadata through `gitea-api` only if that helper is available
+  in the job image; otherwise it reports metadata and host handoff as
+  unverified. It does not download artifact ZIPs, connect to SSH, or apply a
+  release. No repository workflow binding to a Windows runtime starts the
+  receiver. PR #59 now proposes a separate disabled local `--once` trigger
+  that queries a root-verified tuple; it is not installed or active. Image
+  release is automated, but production deployment is not yet automatic CD. The original
+  audited `gitea-api` helper lacks binary output and safe 302 handling; the
+  current PR carries a tested patch and host-side artifact verifier, but
+  neither is installed. No deploy key, fixed SSH entry, extra sudo rule, or
+  Gitea CD variable has been configured. Production apply remains blocked on
+  owner bootstrap, external backup and separate-target restore, and the other
+  gates above.
 - A repository-scoped official `act_runner` `0.2.13` installation is
   configured in `infra/runner/`: rootless Docker under `akyldash-runner`, 15 GiB
   ext4 loop-backed image/workspace storage, capacity 1, per-job limits (2 CPU,
   3 GiB RAM, 512 processes), account slice limits (2.5 CPU, 4 GiB RAM, 2048
   tasks), rotated file logs, and a systemd health timer. Jobs target the
-  `akyldash-ci` label and do not receive either Docker socket. On 2026-10-18,
+  `akyldash-ci` label and do not receive either Docker socket. Latest verified
+  main CI run 175 and smoke run 176 succeeded on `b5adc092`. On 2026-10-18,
   SSH showed `akyldash-act-runner.service` active under `akyldash-runner`, with
   zero restarts and about 115 MiB current memory. Its rootless Docker store is
   mounted from `/dev/loop0` as ext4 with `rw,nosuid,nodev`; the 15 GiB mount had

docs/operations/DEPLOYMENT.md

@@ -1,126 +1,169 @@
 # Deployment
 
-## Current status
+## Status and authorization
 
-Production deployment is not enabled or tested on the VPS. The owner completed
-the root bootstrap: Docker/Compose are active and target directories exist.
-The `codex` account cannot access the Docker socket. No root-owned checkout or
-restricted helpers are installed; protected env/secret metadata and Docker
-container/volume state remain unverified because they require root.
-The unprivileged audit sees no listener on `80`, `443`, or `1500`; Cloudflare
-still returns `521`. Do not deploy until the owner has reviewed root-only host
-state, supplied protected configuration and the approved corpus/index, and
-backup/restore have been tested.
+The implementation in PR #59 is not merged, installed, or exercised against
+the VPS. No release, backup, restore, or production service operation has been
+performed by this change. Production deployment remains blocked until the
+owner has verified host state, registry access, protected configuration,
+corpus/index readiness, RU/KY canaries, an external backup, and restore on a
+separate target. See [current state](CURRENT_STATE.md) and the
+[owner evidence packet](DEPLOYMENT_OWNER_PACKET.md).
 
-## First host preparation
+The existing `codex` account has no Docker socket access and receives no new
+privilege in this change. The external receiver requires an owner-controlled
+SSH entry that runs the fixed root command; no SSH key, `authorized_keys`
+entry, sudo rule, or root alias is created here. If `akyldash_vps` logs in as
+`codex`, it cannot run the root-only receiver and the client fails closed.
+Do not grant general sudo or Docker access to make the flow work.
 
-1. The initial root bootstrap is complete. After reviewing and merging the
-   infrastructure PR, the owner must install that approved `main` checkout at
-   `/opt/akyldash/current` (the path was absent during the unprivileged audit):
+## Release verification and image publication
 
-   ```bash
-   sudo git clone --branch main --single-branch https://git.vakanaut.ru/admin/akyldash.git /opt/akyldash/current
-   ```
+`.gitea/workflows/ci.yaml` remains the required test and image-build workflow.
+The release workflow runs after successful main CI, verifies the source run and
+commit, and publishes digest-pinned images plus a small release descriptor.
+The descriptor records both the release workflow run ID and the successful CI
+source run ID. PR builds do not publish images. Production runtime secrets are
+not supplied to CI.
 
-   The checkout is root-owned by default. Then run
-   `sudo bash /opt/akyldash/current/infra/bootstrap/audit-host.sh`. This
-   read-only audit reports Docker state, protected-file metadata, UFW rules,
-   listeners, and ISPmanager without printing secret contents. Resolve any
-   existing containers, volumes, or data before proceeding; do not overwrite
-   or delete them.
-2. After confirming the existing env and secret do not exist and reviewing the
-   tracked defaults, run
-   `sudo bash /opt/akyldash/current/infra/deploy/prepare-production-config.sh`.
-   It creates `/etc/akyldash/production.env` from the tracked example and
-   generates `/etc/akyldash/review_secret`; both are root-owned mode `0600`.
-   It refuses to overwrite either file and does not start services or create
-   volumes. Review `DATA_ROOT` and follow the
-   [corpus inventory and handoff gates](CORPUS_HANDOFF.md) before placing the
-   approved normalized corpus there.
-3. After reviewing the root-owned checkout and audit output, run
-   `sudo bash /opt/akyldash/current/infra/deploy/install-helper.sh`. It installs
-   the backup reader, read-only verifier, `akyldash-compose config|status`, and
-   rollback helper with exact sudoers command rules. The Compose helper has no
-   start/stop/build operation and grants no direct Docker access. Actual
-   deployments remain owner-run through the documented Compose commands.
-4. Confirm DNS points through Cloudflare to this origin. The owner reports UFW
-   already allows TCP `80` and `443`; read and document the full rules before
-   any firewall decision. TCP `1500` is allowed by owner report but has no
-   observed listener and no ISPmanager package/service was found; the owner
-   must identify its purpose. Do not change UFW as part of this procedure. The
-   Compose Caddy service obtains and renews HTTPS certificates automatically;
-   Cloudflare Full (strict) still needs end-to-end verification.
-5. For a clean first deployment, skip backup only when Compose confirms there
-   are no containers and all persistent mounts are empty. If any data exists,
-   create and verify a backup before starting a new version. For a preloaded
-   corpus with absent named volumes, use `--initial-deployment`; it is limited
-   to a container-free host whose `DATA_ROOT` contains only
-   `minjust-normalized/`. Normal backups reject absent volumes. An uncertain
-   or partial state stops deployment. Then start services, load and validate
-   the OpenSearch index, create the initial admin interactively, verify
-   `/review` over HTTPS, and create the required post-setup baseline backup
-   described in `BACKUP.md`. Record the backend image ID for drift checks:
+On the host, the fixed root receiver uses the installed `gitea-api` helper to
+re-fetch and verify the exact successful CI and release runs, current `main`,
+artifact name, checksum, manifest schema, builder pin, image policy, and commit
+binding. Its binary `DOWNLOAD` extension accepts HTTPS and at most one
+allowlisted HTTPS redirect, does not forward the token across origins, bounds
+the response, and refuses to overwrite an existing file. The installer checks
+the exact audited helper fixture hash before applying its patch. The helper
+and source code are not installed on the VPS by this PR.
 
-   ```bash
-   sudo sh -c 'docker compose --env-file /etc/akyldash/production.env -f /opt/akyldash/current/deploy/production/compose.yaml ps --quiet backend | xargs -r docker inspect --format "{{.Image}}" > /opt/akyldash/deployed-image.txt'
-   sudo chmod 0600 /opt/akyldash/deployed-image.txt
-   ```
+## One-shot runtime binding proposed by PR #59
 
-Application deployment remains owner-run. The repository-scoped `act_runner`
-`0.2.13` service is active under `akyldash-runner` and uses rootless Docker on a
-separate loop-backed filesystem. CI run 75 and smoke run 76 succeeded on main
-head `0e276ae6`. Runner job containers have neither Docker socket nor production
-secrets. CI has no image publishing or production deployment step. The
-repository defines sudo helpers for fixed verification, read-only Compose
-`config`/`status`, and guarded rollback, but none is installed on the VPS. They
-do not start or stop services.
+PR #59 adds a root-only, read-only status command and a fixed SSH dispatcher.
+The dispatcher accepts only the literal status or deploy command in
+`SSH_ORIGINAL_COMMAND`; it accepts no arguments and performs no shell
+evaluation. Status fails closed on a stale root checkout, recovery journal,
+incomplete Gitea run listing, failed source/workflow checks, invalid artifact
+metadata/ZIP, or a release already applied. The candidate response contains
+only a run ID, commit, and descriptor digest. The root receiver independently
+repeats release verification and the existing backup/ACK/cutover guards.
 
-## Release image contract (preparation only)
+The Windows client adds a one-shot `receive_external.py --once` mode. Its
+configuration is fixed to `D:\Dev\akyldash` and the `akyldash_release` SSH
+alias, and is disabled by default. It uses BatchMode, disables forwarding,
+uses the existing host-key checking, bounds status output and time, then calls
+the existing `run_release` path. Rollback remains a separate explicit
+owner-run command. The example Task Scheduler XML is disabled, runs as the
+interactive owner at least privilege, ignores overlapping instances, and
+never wakes the computer. No task has been registered or enabled by this PR.
 
-`infra/deploy/validate_release.py` checks an offline JSON release manifest
-against an explicitly supplied repository allowlist. Schema version 1 requires
-exactly `schema_version`, `source_ref`, `commit`, and `images`; the source ref
-must be `refs/heads/main`, the commit must be a 40-character lowercase Git
-SHA-1, and the images must contain exactly `backend` and `opensearch` as
-`repository@sha256:<64 lowercase hex>` references. The policy has schema
-version 1 and one non-empty repository allowlist for each service. Unknown or
-duplicate JSON keys are rejected.
+Before any activation, the owner must install the reviewed receiver and its
+`archive.py` and `external_session.py` dependencies under a non-user-writable
+`C:\Program Files\Akyldash` directory, set the config ACL so
+only the owner, SYSTEM, and Administrators have full control, fill in the real
+Python executable, owner SID, and local start time in the task template, and
+confirm SSH host-key checking and the forced-command alias. Keep `enabled`
+false and the task
+disabled until the normal backup/restore and production readiness gates are
+recorded. Do not bind a Gitea workflow or PR runner to this Windows host.
 
-The validator takes the manifest path and an explicit policy path:
+The root-side status endpoint requires `/opt/akyldash/current` to exactly
+match current `main`; it does not update that checkout. An owner must advance
+the root-controlled checkout through the approved installation process before
+a release built from a newer commit can be considered ready. Gitea's filtered
+workflow-run listing is bounded to ten entries; if Gitea reports more entries
+or an inconsistent page, status returns unavailable rather than guessing.
 
-```bash
-python3 infra/deploy/validate_release.py release.json --policy /etc/akyldash/release-policy.json
-```
+## Automation boundary: deployment is not active
 
-The policy shape is `{"schema_version":1,"repositories":{"backend":["registry.invalid/akyldash/backend"],"opensearch":["registry.invalid/akyldash/opensearch"]}}`.
-These `registry.invalid` names are format examples only; this change does not
-create a policy file or approve a registry.
+The automatic chain currently ends at release publication:
 
-The repository name in the policy must be approved for the registry. No real
-registry namespace or root-owned host policy is configured by this change; do
-not use the synthetic `registry.invalid` names in tests as production values.
-The host integration must load policy only from its fixed root-owned path.
-This validator checks format and allowlist only: a manifest can claim a main
-ref and commit, but is not proof of source, build provenance, signature, or
-trusted publication. CI still has no publish credentials, image publication,
-host helper, or deploy trigger.
+1. Successful `main` CI triggers image builds and publishes digest references
+   plus the release descriptor artifact.
+2. `deploy-handoff.yaml` verifies the source run and may read artifact metadata.
+   Its job is explicitly status-only: **NOT DEPLOYED**. It does not download
+   the descriptor ZIP, call the Windows client, open SSH, or invoke the root
+   receiver. A green result means only that this status check completed.
+3. The fixed receiver is physically started only by an explicitly enabled
+   owner-controlled Windows trigger or by the manual release CLI. The proposed
+   `--once` path queries root's verified status endpoint and receives the
+   fixed tuple; no repository workflow invokes it. The example scheduler and
+   config remain disabled, and no Windows trigger has been installed or
+   exercised.
 
-Compose merges an image override with the existing service `build` entries.
-The regression test renders fake digest references and confirms both entries
-remain; any future deploy command must use `docker compose up --no-build` so
-the host cannot silently build a different image. This does not make digest
-rollback available: the current rollback helper expects local tags. A separate
-host-side deploy/rollback design, owner-approved registry permissions and
-retention, and manual backup/health/rollback end-to-end validation are still
-required before publishing or enabling CD.
+Production CD is still not active: no Windows task or credential is installed,
+and no VPS or live D: operation has been performed. This design avoids a
+Windows Actions runner entirely; the owner-controlled local task is not exposed
+to PR jobs. The SSH account/key must be restricted to the exact dispatcher
+commands and verified host key. Do not use an unrestricted `authorized_keys`
+entry or a persistent host-mode runner with D: and SSH access.
 
-## CI
+## External backup and cutover
 
-`.gitea/workflows/ci.yaml` runs the Python unit suites and builds both
-production images on pull requests and pushes to `main`. It does not publish an
-image or deploy production. `.gitea/workflows/runner-smoke.yaml` exercises the
-`akyldash-ci` runner on pull requests, pushes to `main`, or manual dispatch.
-Both workflows passed on main head `0e276ae6` in runs 75 and 76 respectively.
-The repository runner-list endpoint is not available to the current API
-principal, so its registration details cannot be independently read through
-Gitea API.
+The fixed root release receiver accepts only a bounded protocol request over
+stdin. It does not accept a remote shell command, artifact path, or image
+reference from the caller. It rechecks the release and current `main`, takes a
+shared lock, captures running image IDs, and stops the stack. It streams the
+cold archive directly to the owner's Windows client at
+`D:\Dev\akyldash\.backups`; the VPS does not hold a full archive, including
+temporarily. The Windows client requires a real NTFS destination with private
+ACLs and a precise local Git exclude rule. It publishes only after hash,
+archive, and manifest verification, and acknowledges the exact live session
+nonce and backup identity.
+
+Only after the acknowledgement does the host pull approved digest references,
+atomically replace both image refs, and start Compose with `--no-build`. It
+checks running image IDs, `/review`, and non-empty Russian and Kyrgyz search
+canaries. A stale main, source mismatch, invalid archive, image mismatch, or
+failed health/canary check stops cutover and attempts recovery using the
+pre-change references. A recovery journal blocks another operation if
+automatic recovery cannot be verified.
+
+Rollback uses the root-pinned prior external archive and creates a fresh
+external backup of current state before switching refs. It restores images
+only, not data. Old local VPS backup paths and legacy release states without a
+pinned external backup identity are rejected. See [backup and restore](BACKUP.md)
+and [rollback](ROLLBACK.md).
+
+The receiver records a durable pending recovery journal before stopping
+services. A retry of the exact release already recorded in pinned state is
+rejected before backup or downtime. Gitea source verification requires
+`status=completed` and `conclusion=success`, and resolves current `main` from
+the explicit production checkout. The Windows client checks the destination,
+ACL, ignore rule, and full protocol archive capacity before opening SSH.
+
+## Owner bootstrap still required
+
+After review and merge, the owner must decide whether to install the helper
+from a root-owned checkout and provision, without exposing values in logs:
+
+- a read-only Gitea API token in `/etc/akyldash/gitea-api-token`, root-owned
+  mode `0600`;
+- the exact artifact redirect origin allowlist in
+  `/etc/akyldash/gitea-download-origins`, if the Gitea artifact endpoint
+  redirects;
+- approved Russian and Kyrgyz search canaries in
+  `/etc/akyldash/release-canaries.json`, root-owned mode `0600`;
+- a root-only SSH path to `/usr/local/sbin/akyldash-release-deploy` and
+  `/usr/local/sbin/akyldash-release-rollback` using the existing owner key and
+  verified host key.
+- a dedicated SSH alias `akyldash_release` backed by a key restricted to
+  `/usr/local/sbin/akyldash-release-dispatch`; its forced command must preserve
+  exact `SSH_ORIGINAL_COMMAND` matching and grant no shell, forwarding, PTY,
+  or arbitrary command access;
+- a protected installation of the Windows client under
+  `C:\Program Files\Akyldash`, with the sample JSON and Task Scheduler XML
+  reviewed and kept disabled until the owner explicitly accepts unattended
+  polling.
+
+The installer intentionally does not create credentials, SSH entries, canary
+values, registry permissions, or a new privilege rule. Existing files with
+unexpected owner, mode, or content cause installation to stop for owner
+review. Do not run the installer or receiver from CI. The owner's first use
+must be a separate-target restore check and a reviewed dry run; this PR does
+not authorize a production cutover.
+
+The Windows client uses the existing OpenSSH host-key checking. Its configured
+alias must reach a root-controlled endpoint capable of invoking the fixed
+receiver; no new key or sudo permission is requested. Windows ACL and NTFS
+checks, SSH host configuration, artifact redirect origin, registry pull
+access, and every production health gate remain unverified until the owner
+checks them.

docs/operations/DEPLOYMENT_OWNER_PACKET.md

@@ -0,0 +1,91 @@
+# Deployment owner evidence packet
+
+This packet is a list of owner-only checks. It does not authorize a production
+change. Do not include token/password values, environment-file contents,
+private keys, secret material, or raw process environments.
+
+## Required before release use
+
+- PR #59 proposes a disabled one-shot Windows trigger. No task or endpoint is
+  installed. If the owner chooses to activate it after merge and all other
+  gates, install the reviewed `receive_external.py`, `archive.py`, and
+  `external_session.py` client files in `C:\Program Files\Akyldash` with
+  write access limited to administrators/SYSTEM, copy
+  `infra/deploy/windows-release-trigger.example.json` to
+  `C:\ProgramData\Akyldash\release-trigger.json` and retain
+  `enabled:false`, then grant only the interactive owner, SYSTEM, and
+  Administrators full control on the config and its parent. Fill in the real
+  Python path, owner SID, and a future local start time in the XML template.
+  Review/import the task while
+  disabled; it runs as that logged-on owner at least privilege, ignores a
+  concurrent instance, does not wake the PC, and invokes only `--once`. Enable
+  the JSON and task only after the owner separately approves unattended
+  polling. Disable either one to stop future polls; an already running cold
+  backup/deploy must be allowed to finish or be explicitly recovered.
+- The `akyldash_release` SSH key must be dedicated to the root forced-command
+  dispatcher, with OpenSSH `restrict` (or equivalent no-PTY/no-forwarding
+  options), verified host-key checking, and exact status/deploy command
+  matching. Do not put an unrestricted command or shell in root's
+  `authorized_keys`. The existing rollback key/path remains a separate manual
+  owner action. No key is generated, copied, or installed by this PR.
+- Decide whether unattended production CD is acceptable. It currently is not
+  active: `deploy-handoff.yaml` remains status-only and reports `NOT DEPLOYED`;
+  the proposed local task and its config remain disabled. This avoids exposing
+  the Windows host to repository PR workflows. Verify that the root status
+  command is installed from a reviewed checkout, its forced-command key is
+  restricted, and the host checkout exactly matches current `main`. It does
+  not update that checkout automatically. The endpoint fails closed if the
+  filtered workflow-run API page is incomplete (more than ten candidates or
+  count mismatch), so status API behavior must be checked on the live Gitea
+  before activation.
+- Confirm the registry package names and least-privilege writer/pull access for
+  `admin/akyldash/backend` and `admin/akyldash/opensearch`; record digest
+  retention for the rollback window.
+- Confirm Gitea artifact retention covers the rollback window. The workflow
+  requests 90 days for the small release descriptor and checksum.
+- Provide a dated, sanitized root audit: installed checkout SHA, Compose
+  services and image IDs, health state, volume paths/modes, protected-file
+  owner/mode, listener summary, and current recovery-journal state.
+- Confirm a root-controlled SSH path exists for the fixed deploy and rollback
+  commands, using existing owner SSH configuration and verified host-key
+  checking. The repository `codex` account must not receive general sudo,
+  Docker-group membership, or a Docker socket. No SSH key or root alias is
+  provisioned by this PR.
+- If required, install a narrowly scoped, read-only Gitea API token at
+  `/etc/akyldash/gitea-api-token` with root ownership and mode `0600`. Record
+  only whether it is present and its scope; never send its value.
+- Verify the Gitea artifact download origin. If redirected, provision only the
+  exact HTTPS origin in `/etc/akyldash/gitea-download-origins` as a root-owned
+  mode-`0600` file. The patched helper must not send its token to that origin.
+- Provide owner-approved RU and KY search canary queries in
+  `/etc/akyldash/release-canaries.json`, root-owned mode `0600`. Confirm they
+  return expected non-empty results without sending corpus documents.
+- Confirm Cloudflare TLS mode, origin certificate renewal, and current public
+  `/review` and search health.
+
+## Backup and recovery gates
+
+- The complete archive must remain on the owner-controlled Windows destination
+  `D:\Dev\akyldash\.backups`; never stage a full archive on the VPS.
+- Synthetic Windows protocol checks and a disposable private-NTFS owner-ACL
+  fixture passed. Before relying on the flow, run its checks against the actual
+  D: path and local `.git/info/exclude`, then verify an approved backup is
+  published only after hash and manifest verification.
+- Confirm D: encryption at rest. Archives contain production secrets and
+  private keys; the protocol encrypts transport but does not encrypt files at
+  rest.
+- Restore a verified archive on an isolated separate target and check data,
+  SQLite integrity, OpenSearch, and required secrets. Do not use production as
+  a restore test.
+- Confirm current data/index counts, corpus generation, and migration
+  compatibility. Image rollback does not restore data or undo schema changes.
+- Set the archive retention period and keep the previous verified archive
+  throughout the rollback window.
+
+The installer does not create credentials, SSH configuration, canary values,
+registry access, or new sudo rules. The PR has not been installed or run
+against production. Windows validation passed 12 synthetic client checks, 8
+protocol checks, and a disposable real-NTFS private owner-ACL fixture. The
+actual D: path, SSH, full backup, and separate-target restore remain
+unverified. Keep deployment disabled until the owner records evidence for
+each gate above.

docs/operations/ROLLBACK.md

@@ -1,41 +1,34 @@
 # Rollback
 
-## Current status
+The current rollback implementation is code only. PR #59 has not been merged,
+installed, or run against the VPS. No current production release state or
+external backup has been verified; production rollback is therefore not
+available yet.
 
-There is no production release, backup, or installed rollback helper. The
-repository contains a root-owned rollback helper and a separate installer, but
-neither has been run on the VPS.
+After owner installation and separate-target restore validation, rollback is
+an owner-controlled Windows-to-VPS session. The Windows client reads the exact
+previous backup identity pinned in root-owned release state, validates the
+saved archive and sidecar, then sends it over SSH. The VPS accepts the bytes
+only when size and SHA-256 match that root-pinned identity. It verifies the
+current deployment against release state, stops Compose, and streams a fresh
+cold backup to Windows before changing either image reference.
 
-After a verified cold backup is created before a release, an owner must check
-that the data format is compatible with the prior backend/OpenSearch images.
-Then run the limited helper with that archive:
+The rollback helper verifies deployment-file hashes, previous image refs and
+image IDs, and that the fresh backup matches the current image IDs. It does not
+restore application data, OpenSearch contents, or secrets. It uses the shared
+deployment lock, atomically switches both image references, starts Compose
+with `--no-build`, verifies running image IDs and the local `/review` health
+route, then records the new release state. Failures attempt to restore the
+pre-rollback references and services; unresolved recovery is recorded in a
+root-owned journal and blocks subsequent release/rollback operations.
 
-```bash
-sudo -n /usr/local/sbin/akyldash-rollback \
-  /var/backups/akyldash/<pre-release-backup>.tar.gz --data-compatible
-```
+The former `akyldash-rollback <VPS path>` interface now fails closed and performs
+no Docker operation. Local `/var/backups/akyldash` archives cannot authorize a
+rollback. Legacy release states without a verified external `previous_backup`
+identity also cannot authorize this rollback path.
 
-The helper verifies archive integrity, Compose image references, deployment
-file hashes, and the availability of both prior local images. It makes and
-verifies a second cold backup, restores only the prior backend/OpenSearch image
-tags, waits for Compose healthchecks, and checks HTTPS locally. Digest-pinned
-references are validated against their recorded local image IDs, but rollback
-fails before stopping services or making a backup when either image reference
-uses `@sha256:`. The helper cannot safely switch immutable digest references
-with the current release-recording flow. Do not retag a digest manually; digest
-rollback needs a separately reviewed atomic release-reference mechanism.
-
-It refuses to restore if the current Compose/Caddyfile differs from the saved
-release. This does not restore data or automatically undo a release with an
-unknown schema change. The application has no formal migration framework;
-compatibility must be checked for every change. If it is uncertain, stop and ask
-the owner.
-
-The initial owner-run deployment must record its running backend image ID in
-`/opt/akyldash/deployed-image.txt` with mode `0600`; the rollback helper updates
-that record after a successful rollback, and `infra/bootstrap/verify.sh` checks
-it against the running container.
-
-Any data restore requires the owner, a verified pre-change backup, and a
-maintenance window. Preserve the failed release and both backups until recovery
-is confirmed.
+The application has no formal migration framework. Check schema and index
+compatibility before rollback. If compatibility is uncertain, stop; do not
+attempt a data restore as part of an image rollback. A data restore requires a
+separate owner-approved recovery plan and maintenance window. See
+[backup and restore](BACKUP.md) and [deployment](DEPLOYMENT.md).

docs/product/platform-development-plan-toktom-2026-10-24.md

@@ -0,0 +1,307 @@
+# План развития «Акылдаш»: конкурентный анализ «Токтом Онлайн»
+
+Дата: 24 октября 2026 года. Статус: предложение для продуктового решения;
+не утверждённый бюджет или срок выпуска. Изменения приложения этим документом
+не выполняются.
+
+## 1. Вывод и оценка шансов
+
+**На текущем этапе «Акылдаш» не готов заменить профессиональную СПС целиком.
+Шанс построить востребованный продукт есть, если начать с ограниченного
+практического сегмента и доказать качество данных и экономию времени.**
+
+Копирование всей широты конкурента потребует не только разработки, но и
+постоянной юридической редакции, получения материалов, сопровождения клиентов
+и продаж. Рекомендуемая стартовая гипотеза — поиск и контроль норм для
+небольших юридических и бухгалтерских команд, работающих с ОсОО/ЖЧК,
+налогообложением и трудовыми вопросами. Наличие отдельных поисковых улучшений
+по ОсОО и налогам делает этот сегмент удобным для проверки, но само по себе
+не подтверждает спрос.
+
+| Сценарий | Оценка | Что должно измениться |
+| --- | --- | --- |
+| Быстрая полная замена привычной СПС | Низкие шансы сейчас | Нужны надёжный выпуск, полнота материалов и профессиональные инструменты |
+| Дополнительный инструмент для одной практической задачи | Наиболее реалистичная гипотеза | Пилот должен показать измеримую пользу без обязательного отказа от прежней системы |
+| Основное рабочее место небольшой команды | Условно достижимо после пилота | Нужны удержание, обновления, персональная работа и подтверждённая готовность платить |
+| Массовая платформа с ИИ-консультантом | Долгосрочная гипотеза | Нужны проверяемые ответы, экономика обслуживания и контроль юридических ошибок |
+
+Проценты вероятности успеха не рассчитываются: нет данных о числе клиентов
+конкурента, продажах, удержании, нашей команде, бюджете и стоимости привлечения.
+Цены, скорость и качество поиска систем в одинаковых условиях не сравнивались.
+Техническая возможность создать функцию не доказывает коммерческое преимущество.
+
+## 2. Основание и ограничения исследования
+
+Изучено открытое [руководство «Токтом Онлайн»](https://online.toktom.kg/cms/Topic/273)
+целиком: портал, учётные записи, продукты, поиск и работа с документами.
+В таблице ниже номера означают разделы этого руководства. Описание функции
+подтверждает её документирование, но не результат испытания платной системы.
+Дата последнего обновления руководства не установлена; старый год в подвале
+не позволяет определить актуальность отдельных инструкций.
+
+Отдельная [страница продукта](https://online.toktom.kg/cms/Topic/292)
+заявляет ежедневное обновление и работу через интернет с синхронизацией
+персональных данных. Это заявления поставщика; их фактическое выполнение
+не проверялось. Актуальный тариф на этой странице предлагается запрашивать.
+
+База сравнения «Акылдаш»: актуальная на повторной сверке `origin/main`, commit
+`c8d0086a9f20485c5efe6f9d3ccd476dd9f07065` (2 ноября 2026 года). Матрица
+G01–G25, описание текущих возможностей в разделе 3 и этапы A–F в разделе 6
+повторно сверены с этой базой. Проверены:
+
+- [README](../../README.md), [обзор продукта](project-overview.md);
+- [API](../../backend/search/api.py), [поисковый интерфейс](../../backend/search/review.html),
+  [учётные записи](../../backend/search/auth.py), [запросы](../../backend/search/query.py);
+- [каталоги](search-catalog-v1.md), [план frontend](frontend-search-sps-plan.md),
+  [readiness gate](frontend-design-readiness-plan.md);
+- [состояние инфраструктуры и корпуса](../operations/CURRENT_STATE.md),
+  [доступ](../operations/ACCESS.md), а также актуальные реализации Search API,
+  учётных записей и поискового интерфейса.
+
+Матрица отражает возможности реализации на указанном commit, а не только
+состояние прежней базы исследования. В частности, в текущем внутреннем контуре
+администратор может создавать и удалять учётные записи и сбрасывать пароль;
+публичная регистрация и восстановление по email по-прежнему отсутствуют.
+Технические версии кода: Backend 0.13.3 (`APP_VERSION` в
+`backend/search/minjust_opensearch.py`), Frontend 0.3.3 (подвал
+`backend/search/review.html`), Telegram-бот 0.2.2 (`APP_VERSION` в
+`tools/telegram-bot/bot.py`). Корневой README указывает Backend 0.13.2;
+`backend/README.md` содержит более старые Backend 0.13.0 / Frontend 0.2.3.
+При расхождении использованы версия backend и подвал интерфейса в указанном
+commit. Эти версии не подтверждают развёртывание соответствующего кода.
+Живой production, полнота локального корпуса и пользовательская доступность
+не подтверждены текущими проверками. Нельзя считать функцию доступной клиентам
+только на основании наличия кода.
+
+## 3. Что уже есть у нас
+
+В реализации есть полнотекстовый поиск RU/KY, фильтры по виду, статусу, группе
+органа, юридической силе и дате; пагинация и сортировка по релевантности/дате.
+Есть API карточки и редакций, чтение выбранной редакции и языка, оглавление,
+поиск внутри текста, печать и переход на официальный источник.
+Это **не нужно разрабатывать заново**.
+
+Учётные записи SQLite, проверка полномочий на сервере,
+смена пароля и административные создание, удаление и сброс пароля доступны
+во внутреннем контуре. Лаборатория собирает оценки выдачи и комментарии
+проверяющих. Это не публичная регистрация, не восстановление пароля по email,
+не пользовательские заметки к нормам и не история исследований между устройствами.
+
+По состоянию, записанному в `CURRENT_STATE.md`, публичный запуск и готовность
+всего корпуса не подтверждены. В документе есть исторические проверки архива
+и ограниченного staging; успешная обработка одного документа не доказывает
+полноту и актуальность базы. RAG в README отмечен как ещё не созданный.
+
+## 4. Функциональные пробелы
+
+Обозначения: **нет** — в проверенных API, UI и профильных планах отсутствует
+готовая возможность; **частично** — есть основа, но сценарий неполон;
+**не подтверждено** — без аудита корпуса или рабочего сервиса вывод невозможен.
+«Нет» относится к реализации указанного commit, а не ко всем внешним наработкам.
+P0 — до публичного пилота; P1 — основное рабочее место; P2 — после спроса;
+P3 — только при отдельном обосновании.
+
+| ID | Возможность в руководстве «Токтом» | Состояние «Акылдаш» и необходимое дополнение | Приоритет |
+| --- | --- | --- | --- |
+| G01 | Регистрация, восстановление, соцвход (§1.1–1.2) | Частично: внутренние аккаунты есть; публичный onboarding и восстановление по email отсутствуют. Соцвход отложить | P1 / P3 |
+| G02 | Организация и профиль (§3.1.1) | Частично: есть кабинет, но нет полноценной модели организаций | P2 |
+| G03 | Счёт, платежи (§3.1.2) | Нет: коммерческий учёт и сверка оплат | P2 |
+| G04 | Продукты, сроки, промокоды (§3.2.1–3) | Нет: тарифные права и жизненный цикл подписки | P2 |
+| G05 | Подключение коллег (§3.2.4–5) | Нет: приглашения и права внутри организации; внутренние роли не заменяют это | P2 |
+| G06 | Настройки выдачи (§3.2.6) | Частично: параметры доступны, серверного сохранения предпочтений нет | P1 |
+| G07 | Тематические разделы (§3.3.1) | Частично: черновая таксономия есть, публичный тематический фильтр отсутствует | P1 |
+| G08 | Судебные, справочные, зарубежные материалы (§3.3.1) | Не подтверждено: специализированные полные коллекции и их поиск не показаны; наличие отдельных актов в ЦБД не исключается | P2 / P3 |
+| G09 | Новые документы (§3.3.3) | Нет отдельной пользовательской ленты поступлений | P1 |
+| G10 | Избранное, изменения (§3.3.4) | Нет серверного списка и пользовательского контроля изменений | P1 |
+| G11 | История документов/запросов (§3.3.5) | Нет синхронизированной истории исследования; URL браузера и история входов — другие данные | P1 |
+| G12 | Обзор обновлений (§3.3.6) | Нет журнала новых, изменённых и отменённых актов для пользователя | P0 / P1 |
+| G13 | Открытие по коду (§3.4.2) | Частично: API принимает код, отдельного пользовательского сценария нет | P1 |
+| G14 | Расширенные реквизиты (§3.4.3) | Частично: нужны номер, раздельные поля названия/текста, тематический отбор, множественные значения и поиск без обязательного q | P1 |
+| G15 | Детальные органы, публикация (§3.4.3.1) | Частично: API ограничен группами органов; нет полного реестра и фильтров по регистрации/источнику публикации | P2 |
+| G16 | Шаблоны запросов (§3.4.3.2) | Нет именованных сохранённых поисков | P1 |
+| G17 | Сортировка по органу/виду (§3.5.3) | Нет таких режимов и выбора направления; текущая дата имеет дополнительный приоритет статуса | P2 |
+| G18 | Word: выдача/документ (§3.5.4; 3.6.6) | Нет DOCX-экспорта; браузерная печать уже есть | P1 |
+| G19 | Справка и реквизиты (§3.6.1) | Частично: метаданные есть, полная читаемая паспортная карточка требует доработки | P1 |
+| G20 | Связи, обратные ссылки (§3.6.7–8) | Нет собственного проверенного графа связей и обратного индекса; исходные HTML-ссылки не равнозначны | P1 |
+| G21 | Предпросмотр, «Связной» (§3.6.9; 13) | Нет контекстного просмотра и связей на уровне конкретной нормы | P2 |
+| G22 | Графические копии (§3.6.10) | Частично на уровне архива: готовая выдача оригиналов не подтверждена; вложения staging не верифицированы | P2 |
+| G23 | Сравнение редакций (§3.6.12) | Нет сопоставления двух текстов и выделения изменений; переключатель редакций уже есть | P1 |
+| G24 | Языковое сравнение (§3.6.14) | Нет параллельного просмотра; переключение RU/KY уже есть | P1 |
+| G25 | Форум, сообщения (§2; 3.2.7–8) | Нет пользовательского сообщества; рабочий Telegram-бот команды его не заменяет | P3 |
+
+Редакции, языки, оглавление и печать (§3.6.2–5) в перечень отсутствующих
+функций не включены. Для сравнительного списка использовано
+[руководство поставщика](https://online.toktom.kg/cms/Topic/273).
+
+## 5. Стратегия отличия
+
+Это гипотезы развития, а не установленные преимущества над конкурентом.
+Отсутствие описания в его руководстве не доказывает отсутствия функции.
+
+1. **Проверяемая актуальность.** На каждой норме показывать источник, редакцию,
+   время последней успешной проверки и ограничения данных. Разделять дату
+   получения, принятия, вступления в силу и период применимости.
+2. **Практический двуязычный поиск.** Измерять RU и KY отдельно на реальных
+   задачах, сокращениях и опечатках. Не обещать кыргызскую морфологию только
+   из-за наличия ICU. Не подменять отсутствующий официальный текст переводом.
+3. **Рабочая задача вместо набора документов.** Проверить сценарий
+   «найти применимую норму → проверить редакцию → сохранить доказательство →
+   получить сигнал об изменении». Он должен занимать меньше времени у пилота.
+4. **Объяснение с проверяемыми ссылками.** После надёжного поиска добавить
+   ответы с точными цитатами и открытием фрагмента. При недостатке источников
+   система сообщает об этом; юридические выводы требуют проверки специалистом.
+
+Удобный интерфейс и низкая цена сами по себе не обеспечат переход клиентов.
+Открытые источники также не дают автоматического разрешения на любой способ
+их использования. Права на каждый новый источник проверяются отдельно;
+копирование базы и редакционных материалов конкурента в план не входит.
+
+## 6. Последовательность развития и приёмка
+
+Сроки ниже — предварительные диапазоны для команды из двух разработчиков
+с регулярным участием юриста и частичным участием дизайнера/эксплуатации.
+Это предположение для обсуждения, не оценка существующего штата. При иной
+команде и после обследования данных сроки нужно пересчитать. Переходы
+определяются результатами, а не истечением недель.
+
+### Этап A. Данные и воспроизводимый запуск — P0, ориентир 3–6 недель
+
+Зависимости: состояние официального API, доступный корпус и участие владельца
+инфраструктуры. Назначить ответственных за данные, эксплуатацию и юридическую
+проверку. Согласовать правила текущей редакции и обработки неизвестного статуса.
+
+- Завершить квалификацию источника и полный аудит корпуса; отдельно проверить
+  языки, порядок редакций, контрольные суммы, ошибки, вложения и пропуски.
+- Запустить воспроизводимый цикл проверки обновлений с журналом изменений
+  и безопасным переключением индекса. Из этого журнала строить G12 и G09.
+- Выполнить существующий readiness gate, зафиксировать baseline и ограничения.
+- Подготовить пилотное развёртывание, наблюдение за ошибками, проверенный backup
+  и восстановление в изолированной среде по существующим процедурам.
+
+Приёмка: завершённый отчёт о полноте с объяснёнными исключениями; повторный
+запуск не создаёт дубликатов; неудачное обновление сохраняет рабочий индекс;
+сквозные сценарии RU/KY проходят; восстановление проверено. Рекомендуемая цель
+актуализации — не более суток от доступности изменения у источника; сначала
+измерить достижимость и только затем обещать SLA пользователям.
+
+### Этап B. Поисковое рабочее место — P1, ориентир 4–6 недель
+
+Зависимость: этап A. Закрыть G07, G13–14, G18–19 и уточнить G06.
+Использовать готовые просмотр, печать и оглавление; не переписывать их.
+
+- Утвердить темы и устойчивые идентификаторы; не превращать черновые хеши
+  классификатора в публичный контракт без проверки.
+- Добавить точный номер и независимые поля поиска; разрешить отбор только
+  по реквизитам; определить семантику AND/OR и множественного выбора.
+- Сделать паспорт документа, пользовательский сценарий открытия по коду и
+  DOCX с редакцией, языком, источником и временем выгрузки. Не обещать PDF-
+  экспорт сверх печати до подтверждения отдельной потребности.
+
+Приёмка: 20 задач пилота успешно проходят путь от запроса до нужного фрагмента;
+документы без языка/текста имеют понятное состояние; файл экспорта воспроизводит
+выбранную редакцию; новые правила не ухудшают замороженный relevance baseline.
+
+### Этап C. Возвращение к работе и контроль — P1, ориентир 3–5 недель
+
+Зависимости: A–B; для внешних пользователей — выбранная модель доступа и
+проверенное восстановление аккаунта G01. Для закрытого пилота допустимы
+создаваемые администратором внутренние аккаунты без публичной регистрации.
+
+Закрыть G06, G10–11, G16: серверные избранное, история и шаблоны; G09/G12
+показать как пользовательскую ленту. Добавить настройки контроля и доставки
+уведомлений только после появления надёжного журнала обновлений. Выбор канала
+и согласие пользователя — отдельное решение; наличие бота команды не означает
+готовность продуктовых уведомлений.
+
+Приёмка: сохранённое доступно со второго устройства; данные разных аккаунтов
+изолированы; удаление/отключение контроля работает; повторная обработка события
+не дублирует сигнал. Правила хранения истории и удаления аккаунта документированы.
+
+### Этап D. Анализ нормы — P1/P2, ориентир 5–8 недель
+
+Зависимости: проверенные редакции, структура фрагментов и метаданные A–B.
+Закрыть G23–24 и базовую часть G20; затем G21, G22 и G15 по результатам пилота.
+Для связей сохранять источник, целевую редакцию и уверенность сопоставления.
+
+Приёмка: юрист проверяет не менее 30 разнообразных пар редакций, включая
+перенумерацию и перемещение статей; интерфейс отличает техническую правку от
+содержательной, а неопределённость показывает явно. Параллельный RU/KY-просмотр
+использует одну редакцию и не выдумывает соответствия. Неуверенные ссылки
+не выдаются как подтверждённые связи. Текстовый diff не считается юридическим
+заключением о дате применимости нормы.
+
+### Этап E. Платный командный продукт — P2, ориентир 4–8 недель
+
+Зависимость: подтверждённые повторное использование и готовность платить.
+Закрыть G02–05 и недостающую часть G01. Сначала выбрать одну понятную модель
+подписки и необходимый канал оплаты; не воспроизводить весь биллинг конкурента.
+
+Приёмка: организация приглашает и отзывает участника; сервер проверяет права
+и срок доступа; повторное платёжное событие не создаёт повторное начисление;
+просроченная подписка не уничтожает сохранённые данные. Стоимость эксплуатации,
+юридической редакции и поддержки учитывается в экономике тарифа.
+
+### Этап F. Новые источники и ответы — P2/P3, отдельная оценка
+
+G08, G17, G25 и оставшиеся расширения включать по измеренному спросу.
+Для судебной практики сначала исследовать законность получения, полноту,
+обезличивание и обновляемость; для экспертных материалов — лицензирование
+и редакционную ответственность. Международные акты проверять в существующем
+корпусе прежде, чем создавать отдельный загрузчик. Зарубежную базу и форум
+не ставить на критический путь первого продукта.
+
+RAG — отдельная разработка после A–D. Начать с поиска доказательств и цитат,
+затем краткого ответа. Приёмка: замороженный экспертный набор, проверка каждой
+ссылки и редакции, отказ при недостатке данных и ноль критических неподтверждённых
+юридических утверждений на приёмочном наборе. Это критерий допуска, а не гарантия
+безошибочности вне набора. Сравнение качества ИИ конкурентов пока не выполнено.
+
+## 7. Проверка рыночной гипотезы и условия остановки
+
+Параллельно этапу A провести 12–15 интервью с юристами и бухгалтерами, включая
+пользователей действующих СПС. Собирать обезличенные задачи, частоту,
+потери времени, критичные источники и причины отказа от нового сервиса.
+Цены сравнивать после получения актуальных коммерческих предложений.
+
+Предлагаемый пилот: 10–15 специалистов, 4 недели, 20 одинаковых задач с RU/KY
+и простыми/сложными запросами. С согласия участников сравнить время и долю
+правильных решений в текущем инструменте и «Акылдаш»; менять порядок систем,
+чтобы уменьшить эффект обучения. Результат оценивает юрист по первоисточнику.
+
+Цели ниже — предлагаемые пороги решения, не уже достигнутые показатели:
+
+| Измерение | Предлагаемый порог | Решение |
+| --- | --- | --- |
+| Качество поиска | Recall@10 ≥ 0,90 и MRR@10 ≥ 0,75 на независимо проверенном наборе, отдельно RU и KY | При недостижении улучшать поиск до расширения функций |
+| Практическая польза | Медианное время правильного выполнения задач меньше минимум на 25% | При отсутствии выигрыша пересмотреть сценарий и сегмент |
+| Возвращаемость | Не менее 60% активированных участников пользуются продуктом на четвёртой неделе | При провале сначала исследовать причины, затем решать о биллинге |
+| Готовность платить | Не менее трёх независимых организаций готовы на платный пилот по названной цене | Переходить к этапу E после проверки экономики |
+| Доверие | Нет критических ошибок редакции/источника в приёмочных задачах | Любая такая ошибка блокирует публичные обещания надёжности |
+
+Малый пилот помогает выбрать направление, но не даёт оценки доли рынка.
+Если пользователям необходимы источники, которые мы не можем законно получить,
+либо стоимость сопровождения превышает приемлемый тариф, сузить сегмент или
+остановить выбранную модель до дальнейших вложений.
+
+## 8. Ближайший рабочий цикл
+
+1. Назначить владельца продукта и юридического редактора; согласовать сегмент.
+2. Зафиксировать состояние корпуса и readiness gate на актуальной main.
+3. Провести интервью, собрать задачи и заморозить критерии пилота.
+4. Превратить этап A и минимальную часть B в отдельные задачи с зависимостями
+   и критериями приёмки. Согласовать связь с существующим планом frontend,
+   не отменяя его gate этим документом.
+5. После пилота пересчитать сроки, стоимость и порядок C–F; выбрать, какие
+   пробелы действительно мешают продаже, а какие можно отложить.
+
+Для реализации сохранять существующую архитектуру Python/SQLite/OpenSearch,
+использовать текущие API и компоненты, добавлять зависимости только по
+обоснованной необходимости. Изменения проводить отдельными PR с проверками,
+версией при изменении кода, независимым review и changelog. Production-действия
+и изменение инфраструктуры требуют действующих процедур доступа и backup.
+
+---
+
+Повторная сверка реализации: `main` `c8d0086a9f20485c5efe6f9d3ccd476dd9f07065`.
+Backend v0.13.3 · Frontend v0.3.3 · Telegram-бот v0.2.2. Это версии
+исследованного кода; они не подтверждают развёртывание этих версий.

infra/backup/archive.py

@@ -17,6 +17,7 @@ import sys
 import tarfile
 import tempfile
 from pathlib import Path, PurePosixPath
+from typing import BinaryIO
 
 COMPONENTS = {
     "data",
@@ -68,7 +69,7 @@ def read_manifest(archive: tarfile.TarFile) -> dict:
     stream = archive.extractfile("manifest.json")
     if stream is None:
         raise ValueError("backup manifest is unreadable")
-    manifest = json.load(stream)
+    manifest = json.loads(stream.read().decode("utf-8"), object_pairs_hook=unique_json_object)
     components = manifest.get("components") if isinstance(manifest, dict) else None
     if (
         not isinstance(manifest, dict)
@@ -90,6 +91,15 @@ def read_manifest(archive: tarfile.TarFile) -> dict:
     return manifest
 
 
+def unique_json_object(pairs: list[tuple[str, object]]) -> dict:
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError(f"duplicate backup manifest field: {key}")
+        result[key] = value
+    return result
+
+
 def verify_archive(path: Path) -> dict:
     checksum_path = Path(f"{path}.sha256")
     expected = checksum_path.read_text(encoding="ascii").split()[0]
@@ -99,6 +109,31 @@ def verify_archive(path: Path) -> dict:
         return read_manifest(archive)
 
 
+def verify_external_archive(path: Path, *, expected_sha256: str, expected_manifest_sha256: str) -> dict:
+    if path.is_symlink() or not path.is_file():
+        raise ValueError("external backup must be a regular file")
+    if not re.fullmatch(r"[0-9a-f]{64}", expected_sha256) or digest(path) != expected_sha256:
+        raise ValueError("external backup SHA-256 does not match the live session")
+    with tarfile.open(path, "r:gz") as archive:
+        manifest_member = next(member for member in checked_members(archive) if member.name == "manifest.json")
+        stream = archive.extractfile(manifest_member)
+        if stream is None:
+            raise ValueError("external backup manifest is unreadable")
+        manifest_bytes = stream.read(1024 * 1024 + 1)
+        manifest = read_manifest(archive)
+        canonical_manifest = json.dumps(manifest, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        if len(manifest_bytes) > 1024 * 1024 or hashlib.sha256(canonical_manifest).hexdigest() != expected_manifest_sha256:
+            raise ValueError("external backup manifest does not match the live session")
+        for member in archive.getmembers():
+            if member.isfile():
+                stream = archive.extractfile(member)
+                if stream is None:
+                    raise ValueError(f"external backup member is unreadable: {member.name}")
+                while stream.read(1024 * 1024):
+                    pass
+        return manifest
+
+
 def parse_sources(values: list[str], required: set[str] = COMPONENTS) -> dict[str, Path]:
     sources: dict[str, Path] = {}
     for value in values:
@@ -277,43 +312,14 @@ def create_backup(
     for name in ("production-env", "review-secret"):
         if sources[name] is None or not sources[name].is_file():
             raise ValueError(f"sensitive component must be a regular file: {name}")
-    if sources["data"] is not None and sources["data"].is_dir():
-        check_sqlite(sources["data"])
-
-    manifest = {
-        "format": 1,
-        "created_at": dt.datetime.now(dt.timezone.utc).isoformat(),
-        "git_revision": revision,
-        "images": images or {},
-        "deployment_files": deployment_files or {},
-        "components": sorted(sources),
-    }
+    manifest = backup_manifest(sources, revision, images, deployment_files)
     with tempfile.NamedTemporaryFile(dir=parent, prefix=".akyldash-backup-", delete=False) as temp:
         temporary = Path(temp.name)
     os.chmod(temporary, 0o600)
     checksum_temp = Path(f"{temporary}.sha256")
     try:
         with tarfile.open(temporary, "w:gz") as archive:
-            encoded = json.dumps(manifest, sort_keys=True).encode("utf-8")
-            info = tarfile.TarInfo("manifest.json")
-            info.size = len(encoded)
-            info.mode = 0o600
-            archive.addfile(info, io.BytesIO(encoded))
-            for name, source in sorted(sources.items()):
-                if source is None:
-                    info = tarfile.TarInfo(f"{name}/")
-                    info.type = tarfile.DIRTYPE
-                    info.mode = 0o700
-                    archive.addfile(info)
-                    continue
-                def protect_secrets(member: tarfile.TarInfo) -> tarfile.TarInfo:
-                    if name in {"production-env", "review-secret"}:
-                        member.mode = 0o600
-                    if member.name.endswith((".sqlite3", ".sqlite3-wal", ".sqlite3-shm")):
-                        member.mode = 0o600
-                    return member
-
-                archive.add(source, arcname=name, recursive=True, filter=protect_secrets)
+            write_backup(archive, sources, manifest)
         with tarfile.open(temporary, "r:gz") as archive:
             read_manifest(archive)
         checksum_fd = os.open(checksum_temp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
@@ -330,6 +336,65 @@ def create_backup(
         checksum_temp.unlink(missing_ok=True)
 
 
+def backup_manifest(
+    sources: dict[str, Path | None], revision: str, images: dict | None, deployment_files: dict[str, str] | None
+) -> dict:
+    for name, source in sources.items():
+        if source is not None and (source.is_symlink() or not (source.is_dir() or source.is_file())):
+            raise ValueError(f"source must be a regular file or directory: {name}")
+    for name in ("production-env", "review-secret"):
+        if sources[name] is None or not sources[name].is_file():
+            raise ValueError(f"sensitive component must be a regular file: {name}")
+    if sources["data"] is not None and sources["data"].is_dir():
+        check_sqlite(sources["data"])
+    return {
+        "format": 1,
+        "created_at": dt.datetime.now(dt.timezone.utc).isoformat(),
+        "git_revision": revision,
+        "images": images or {},
+        "deployment_files": deployment_files or {},
+        "components": sorted(sources),
+    }
+
+
+def write_backup(archive: tarfile.TarFile, sources: dict[str, Path | None], manifest: dict) -> None:
+    encoded = json.dumps(manifest, sort_keys=True).encode("utf-8")
+    info = tarfile.TarInfo("manifest.json")
+    info.size = len(encoded)
+    info.mode = 0o600
+    archive.addfile(info, io.BytesIO(encoded))
+    for name, source in sorted(sources.items()):
+        if source is None:
+            info = tarfile.TarInfo(f"{name}/")
+            info.type = tarfile.DIRTYPE
+            info.mode = 0o700
+            archive.addfile(info)
+            continue
+
+        def protect_secrets(member: tarfile.TarInfo) -> tarfile.TarInfo:
+            if name in {"production-env", "review-secret"}:
+                member.mode = 0o600
+            if member.name.endswith((".sqlite3", ".sqlite3-wal", ".sqlite3-shm")):
+                member.mode = 0o600
+            return member
+
+        archive.add(source, arcname=name, recursive=True, filter=protect_secrets)
+
+
+def create_backup_stream(
+    output: BinaryIO, sources: dict[str, Path | None], revision: str,
+    images: dict | None = None, deployment_files: dict[str, str] | None = None,
+    manifest: dict | None = None,
+) -> dict:
+    if os.geteuid() != 0:
+        raise ValueError("external production backup must run as root")
+    manifest = manifest or backup_manifest(sources, revision, images, deployment_files)
+    with tarfile.open(fileobj=output, mode="w|gz") as archive:
+        write_backup(archive, sources, manifest)
+    output.flush()
+    return manifest
+
+
 def restore_to_staging(backup: Path, target: Path) -> None:
     if not target.name.startswith("akyldash-restore-"):
         raise ValueError("restore target must be a new akyldash-restore-* staging directory")

infra/backup/external_session.py

@@ -0,0 +1,338 @@
+"""Bounded binary protocol for one live owner-controlled external backup session."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import secrets
+import struct
+import datetime as dt
+from typing import BinaryIO
+
+MAGIC = b"AKYL"
+ACK_MAGIC = b"AKYA"
+CHALLENGE_MAGIC = b"AKYB"
+RESULT_MAGIC = b"AKYR"
+VERSION = 1
+CHUNK_BYTES = 1024 * 1024
+MAX_CONTROL_BYTES = 64 * 1024
+MAX_ARCHIVE_BYTES = 100 * 1024**3
+BACKUP_ID_RE = re.compile(r"[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}\Z")
+SHA256_RE = re.compile(r"[0-9a-f]{64}\Z")
+NONCE_RE = re.compile(r"[0-9a-f]{64}\Z")
+
+
+def nonce() -> str:
+    return secrets.token_hex(32)
+
+
+def _json_frame(writer: BinaryIO, magic: bytes, value: dict) -> None:
+    payload = json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    if len(payload) > MAX_CONTROL_BYTES:
+        raise ValueError("external backup control message exceeds its size limit")
+    writer.write(magic + struct.pack("!I", len(payload)) + payload)
+    writer.flush()
+
+
+def _read_exact(reader: BinaryIO, length: int) -> bytes:
+    parts = bytearray()
+    while len(parts) < length:
+        block = reader.read(length - len(parts))
+        if not block:
+            raise ValueError("external backup session ended before a complete protocol frame")
+        parts.extend(block)
+    return bytes(parts)
+
+
+def _read_json_frame(reader: BinaryIO, magic: bytes) -> dict:
+    if _read_exact(reader, len(magic)) != magic:
+        raise ValueError("external backup protocol version or frame type is invalid")
+    return _read_json_after_magic(reader)
+
+
+def _read_json_after_magic(reader: BinaryIO) -> dict:
+    size = struct.unpack("!I", _read_exact(reader, 4))[0]
+    if size > MAX_CONTROL_BYTES:
+        raise ValueError("external backup control message exceeds its size limit")
+    try:
+        value = json.loads(_read_exact(reader, size), object_pairs_hook=_unique_object)
+    except (UnicodeError, json.JSONDecodeError) as error:
+        raise ValueError("external backup control message is invalid JSON") from error
+    if not isinstance(value, dict):
+        raise ValueError("external backup control message must be a JSON object")
+    return value
+
+
+def _unique_object(pairs: list[tuple[str, object]]) -> dict:
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError(f"duplicate external backup field: {key}")
+        result[key] = value
+    return result
+
+
+def write_request(writer: BinaryIO, request: dict) -> None:
+    validate_request(request)
+    _json_frame(writer, MAGIC, request)
+
+
+def read_request(reader: BinaryIO) -> dict:
+    request = _read_json_frame(reader, MAGIC)
+    validate_request(request)
+    return request
+
+
+def validate_request(request: object) -> dict:
+    if (not isinstance(request, dict) or type(request.get("version")) is not int
+            or request["version"] != VERSION):
+        raise ValueError("external backup request has an unsupported version")
+    if request.get("action") == "release" and set(request) == {
+        "version", "action", "run_id", "commit", "descriptor_sha256"
+    }:
+        if (not isinstance(request["run_id"], str) or not request["run_id"].isdigit()
+                or not isinstance(request["commit"], str) or not re.fullmatch(r"[0-9a-f]{40}", request["commit"])
+                or not isinstance(request["descriptor_sha256"], str)
+                or not SHA256_RE.fullmatch(request["descriptor_sha256"])):
+            raise ValueError("external deployment request identity is invalid")
+        return request
+    if request.get("action") == "rollback" and set(request) == {
+        "version", "action", "data_compatible"
+    } and request["data_compatible"] is True:
+        return request
+    raise ValueError("external deployment request has unexpected fields or action")
+
+
+def read_header(reader: BinaryIO) -> dict:
+    header = _read_json_frame(reader, MAGIC)
+    return validate_header(header)
+
+
+def validate_header(header: object) -> dict:
+    if not isinstance(header, dict):
+        raise ValueError("external backup header is invalid")
+    if set(header) != {"version", "nonce", "backup_id", "manifest", "manifest_sha256", "context"}:
+        raise ValueError("external backup header has unexpected fields")
+    if (type(header["version"]) is not int or header["version"] != VERSION
+            or not isinstance(header["nonce"], str)
+            or not NONCE_RE.fullmatch(header["nonce"]) or not isinstance(header["backup_id"], str)
+            or not BACKUP_ID_RE.fullmatch(header["backup_id"]) or not isinstance(header["manifest"], dict)
+            or not isinstance(header["manifest_sha256"], str)
+            or not SHA256_RE.fullmatch(header["manifest_sha256"])):
+        raise ValueError("external backup header is invalid")
+    canonical = json.dumps(header["manifest"], sort_keys=True, separators=(",", ":")).encode("utf-8")
+    if hashlib.sha256(canonical).hexdigest() != header["manifest_sha256"]:
+        raise ValueError("external backup manifest identity does not match its header")
+    if not isinstance(header["context"], dict):
+        raise ValueError("external backup context is invalid")
+    return header
+
+
+def read_response(reader: BinaryIO) -> tuple[str, dict]:
+    magic = _read_exact(reader, 4)
+    value = _read_json_after_magic(reader) if magic in {MAGIC, RESULT_MAGIC} else None
+    if magic == MAGIC:
+        return "header", validate_header(value)
+    if magic == RESULT_MAGIC:
+        result = value
+        if (set(result) != {"version", "status", "message"} or type(result["version"]) is not int
+                or result["version"] != VERSION
+                or result["status"] not in {"success", "error"} or not isinstance(result["message"], str)):
+            raise ValueError("external backup final result is invalid")
+        return "result", result
+    raise ValueError("external deployment response frame is invalid")
+
+
+def write_header(writer: BinaryIO, *, session_nonce: str, backup_id: str, manifest: dict,
+                 context: dict | None = None) -> str:
+    if not NONCE_RE.fullmatch(session_nonce) or not BACKUP_ID_RE.fullmatch(backup_id):
+        raise ValueError("external backup session identity is invalid")
+    manifest_bytes = json.dumps(manifest, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    manifest_sha256 = hashlib.sha256(manifest_bytes).hexdigest()
+    _json_frame(writer, MAGIC, {
+        "version": VERSION,
+        "nonce": session_nonce,
+        "backup_id": backup_id,
+        "manifest": manifest,
+        "manifest_sha256": manifest_sha256,
+        "context": context or {},
+    })
+    return manifest_sha256
+
+
+class ArchiveFrameWriter:
+    def __init__(self, writer: BinaryIO, *, maximum: int = MAX_ARCHIVE_BYTES):
+        self.writer = writer
+        self.maximum = maximum
+        self.size = 0
+        self.digest = hashlib.sha256()
+        self.buffer = bytearray()
+        self.closed = False
+
+    def write(self, data: bytes) -> int:
+        if self.closed:
+            raise ValueError("external backup stream is already closed")
+        self.size += len(data)
+        if self.size > self.maximum:
+            raise ValueError("external backup archive exceeds its size limit")
+        self.digest.update(data)
+        remaining = memoryview(data)
+        while remaining:
+            take = min(CHUNK_BYTES - len(self.buffer), len(remaining))
+            self.buffer.extend(remaining[:take])
+            remaining = remaining[take:]
+            if len(self.buffer) == CHUNK_BYTES:
+                self._flush_chunk(CHUNK_BYTES)
+        return len(data)
+
+    def _flush_chunk(self, size: int) -> None:
+        block = bytes(self.buffer[:size])
+        del self.buffer[:size]
+        self.writer.write(struct.pack("!I", len(block)))
+        self.writer.write(block)
+
+    def finish(self) -> tuple[int, str]:
+        if self.closed:
+            raise ValueError("external backup stream is already closed")
+        if self.buffer:
+            self._flush_chunk(len(self.buffer))
+        digest = self.digest.hexdigest()
+        self.writer.write(struct.pack("!I", 0) + struct.pack("!Q", self.size) + bytes.fromhex(digest))
+        self.writer.flush()
+        self.closed = True
+        return self.size, digest
+
+
+def receive_archive(reader: BinaryIO, output: BinaryIO, *, maximum: int = MAX_ARCHIVE_BYTES) -> tuple[int, str]:
+    digest = hashlib.sha256()
+    size = 0
+    while True:
+        length = struct.unpack("!I", _read_exact(reader, 4))[0]
+        if length == 0:
+            expected_size = struct.unpack("!Q", _read_exact(reader, 8))[0]
+            expected_digest = _read_exact(reader, 32).hex()
+            break
+        if length > CHUNK_BYTES or size + length > maximum:
+            raise ValueError("external backup archive frame exceeds its size limit")
+        chunk = _read_exact(reader, length)
+        output.write(chunk)
+        digest.update(chunk)
+        size += length
+    output.flush()
+    actual_digest = digest.hexdigest()
+    if size != expected_size or actual_digest != expected_digest:
+        raise ValueError("external backup byte count or SHA-256 does not match its stream trailer")
+    return size, actual_digest
+
+
+def write_ack(writer: BinaryIO, *, session_nonce: str, backup_id: str, size: int,
+              archive_sha256: str, manifest_sha256: str, verified: bool) -> None:
+    if (not NONCE_RE.fullmatch(session_nonce) or not BACKUP_ID_RE.fullmatch(backup_id)
+            or type(size) is not int or not 0 < size <= MAX_ARCHIVE_BYTES
+            or not SHA256_RE.fullmatch(archive_sha256) or not SHA256_RE.fullmatch(manifest_sha256)
+            or verified is not True):
+        raise ValueError("external backup acknowledgement is invalid")
+    _json_frame(writer, ACK_MAGIC, {
+        "version": VERSION,
+        "nonce": session_nonce,
+        "backup_id": backup_id,
+        "size": size,
+        "archive_sha256": archive_sha256,
+        "manifest_sha256": manifest_sha256,
+        "verified": verified,
+    })
+
+
+def write_challenge(writer: BinaryIO, identity: dict, *, session_nonce: str) -> None:
+    if (not NONCE_RE.fullmatch(session_nonce) or not isinstance(identity, dict)
+            or set(identity) != {"backup_id", "size", "archive_sha256", "manifest_sha256", "manifest"}):
+        raise ValueError("external rollback challenge is invalid")
+    if (not isinstance(identity["backup_id"], str) or not BACKUP_ID_RE.fullmatch(identity["backup_id"])
+            or type(identity["size"]) is not int or not 0 < identity["size"] <= MAX_ARCHIVE_BYTES
+            or not isinstance(identity["archive_sha256"], str) or not SHA256_RE.fullmatch(identity["archive_sha256"])
+            or not isinstance(identity["manifest_sha256"], str) or not SHA256_RE.fullmatch(identity["manifest_sha256"])
+            or not isinstance(identity["manifest"], dict)):
+        raise ValueError("external rollback backup identity is invalid")
+    canonical = json.dumps(identity["manifest"], sort_keys=True, separators=(",", ":")).encode("utf-8")
+    if hashlib.sha256(canonical).hexdigest() != identity["manifest_sha256"]:
+        raise ValueError("external rollback manifest identity is inconsistent")
+    _json_frame(writer, CHALLENGE_MAGIC, {"version": VERSION, "nonce": session_nonce, **identity})
+
+
+def read_challenge(reader: BinaryIO) -> dict:
+    value = _read_json_frame(reader, CHALLENGE_MAGIC)
+    if (set(value) != {"version", "nonce", "backup_id", "size", "archive_sha256", "manifest_sha256", "manifest"}
+            or type(value["version"]) is not int or value["version"] != VERSION
+            or not isinstance(value["nonce"], str)
+            or not NONCE_RE.fullmatch(value["nonce"]) or not isinstance(value["backup_id"], str)
+            or not BACKUP_ID_RE.fullmatch(value["backup_id"]) or type(value["size"]) is not int
+            or not 0 < value["size"] <= MAX_ARCHIVE_BYTES
+            or not isinstance(value["archive_sha256"], str) or not SHA256_RE.fullmatch(value["archive_sha256"])
+            or not isinstance(value["manifest_sha256"], str) or not SHA256_RE.fullmatch(value["manifest_sha256"])
+            or not isinstance(value["manifest"], dict)):
+        raise ValueError("external rollback challenge is invalid")
+    canonical = json.dumps(value["manifest"], sort_keys=True, separators=(",", ":")).encode("utf-8")
+    if hashlib.sha256(canonical).hexdigest() != value["manifest_sha256"]:
+        raise ValueError("external rollback challenge manifest identity is inconsistent")
+    return value
+
+
+def read_ack(reader: BinaryIO, *, session_nonce: str, backup_id: str, size: int,
+             archive_sha256: str, manifest_sha256: str) -> dict:
+    ack = _read_json_frame(reader, ACK_MAGIC)
+    if (set(ack) != {"version", "nonce", "backup_id", "size", "archive_sha256", "manifest_sha256", "verified"}
+            or type(ack.get("version")) is not int or type(ack.get("size")) is not int
+            or ack.get("verified") is not True):
+        raise ValueError("external backup acknowledgement is invalid")
+    expected = {
+        "version": VERSION, "nonce": session_nonce, "backup_id": backup_id,
+        "size": size, "archive_sha256": archive_sha256,
+        "manifest_sha256": manifest_sha256, "verified": True,
+    }
+    if ack != expected:
+        raise ValueError("external backup acknowledgement does not match this live session")
+    return ack
+
+
+def write_result(writer: BinaryIO, *, status: str, message: str = "") -> None:
+    if status not in {"success", "error"} or len(message.encode("utf-8")) > 4096:
+        raise ValueError("external backup result is invalid")
+    _json_frame(writer, RESULT_MAGIC, {"version": VERSION, "status": status, "message": message})
+
+
+def read_result(reader: BinaryIO) -> dict:
+    result = _read_json_frame(reader, RESULT_MAGIC)
+    if (set(result) != {"version", "status", "message"} or type(result["version"]) is not int
+            or result["version"] != VERSION or result["status"] not in {"success", "error"}
+            or not isinstance(result["message"], str)):
+        raise ValueError("external backup final result is invalid")
+    return result
+
+
+def send_backup_session(writer: BinaryIO, reader: BinaryIO, *, sources: dict, revision: str,
+                        images: dict, deployment_files: dict[str, str], context: dict) -> dict:
+    from archive import backup_manifest, create_backup_stream
+
+    manifest = backup_manifest(sources, revision, images, deployment_files)
+    session_nonce = nonce()
+    backup_id = "akyldash-" + dt.datetime.now(dt.timezone.utc).strftime("%Y%m%dT%H%M%SZ") + "-" + session_nonce[:8]
+    manifest_sha256 = write_header(
+        writer, session_nonce=session_nonce, backup_id=backup_id, manifest=manifest, context=context
+    )
+    framed = ArchiveFrameWriter(writer)
+    create_backup_stream(
+        framed, sources, revision, images, deployment_files, manifest=manifest
+    )
+    size, archive_sha256 = framed.finish()
+    read_ack(
+        reader, session_nonce=session_nonce, backup_id=backup_id, size=size,
+        archive_sha256=archive_sha256, manifest_sha256=manifest_sha256,
+    )
+    return {
+        "backup_id": backup_id,
+        "archive_sha256": archive_sha256,
+        "manifest_sha256": manifest_sha256,
+        "size": size,
+        "manifest": manifest,
+    }

infra/backup/receive_external.py

@@ -0,0 +1,507 @@
+#!/usr/bin/env python3
+"""Receive and verify one cold backup from the fixed owner SSH session to D:."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import secrets
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+import threading
+from pathlib import Path
+
+from archive import verify_external_archive
+from external_session import (ArchiveFrameWriter, read_challenge, read_response, read_result,
+                              MAX_ARCHIVE_BYTES, receive_archive, write_ack, write_request)
+
+DEFAULT_REPOSITORY = Path(r"D:\Dev\akyldash")
+DEFAULT_DEPLOY_SSH_ALIAS = "akyldash_release"
+TRIGGER_CONFIG = Path(r"C:\ProgramData\Akyldash\release-trigger.json")
+RELEASE_STATUS_COMMAND = "/usr/local/sbin/akyldash-release-status"
+MAX_STATUS_BYTES = 1024
+STATUS_TIMEOUT_SECONDS = 180
+NOT_READY_REASONS = {
+    "recovery_journal", "host_checkout_stale", "no_current_main_release", "main_advanced",
+    "already_applied",
+}
+MAX_ERROR_BYTES = 8192
+_WINDOWS = os.name == "nt"
+
+
+def _reparse(path: Path) -> bool:
+    if path.is_symlink():
+        return True
+    try:
+        return bool(path.stat().st_file_attributes & 0x400)
+    except AttributeError:
+        return False
+    except FileNotFoundError:
+        return False
+
+
+def _directory_identity(path: Path) -> tuple[int, int]:
+    info = path.lstat()
+    if _reparse(path) or not stat.S_ISDIR(info.st_mode) or not info.st_ino:
+        raise ValueError("backup publication directory is not a stable real directory")
+    return info.st_dev, info.st_ino
+
+
+def _remove_owned_directory(path: Path, identity: tuple[int, int]) -> None:
+    try:
+        current = _directory_identity(path)
+    except FileNotFoundError:
+        return
+    if current != identity:
+        raise ValueError(f"refusing to remove a replaced backup directory: {path}")
+    for child in path.iterdir():
+        child_info = child.lstat()
+        if (child.name not in {"backup.tar.gz", "backup.tar.gz.sha256"}
+                or _reparse(child) or not stat.S_ISREG(child_info.st_mode)):
+            raise ValueError(f"refusing to remove unexpected backup content: {child}")
+    shutil.rmtree(path)
+
+
+def check_private_acl(path: Path) -> None:
+    command = r"""
+$ErrorActionPreference = 'Stop'
+$acl = Get-Acl -LiteralPath $env:AKYLDASH_ACL_PATH
+$driveRoot = [System.IO.Path]::GetPathRoot($env:AKYLDASH_ACL_PATH)
+$volume = [System.IO.DriveInfo]::new($driveRoot)
+if (-not $volume.IsReady -or $volume.DriveFormat -ne 'NTFS') { exit 5 }
+$owner = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+$allowed = @($owner, 'S-1-5-18', 'S-1-5-32-544')
+$aclOwner = $acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value
+if ($aclOwner -notin $allowed) { exit 6 }
+$ownerAllowed = $false
+foreach ($rule in $acl.Access) {
+  $sid = $rule.IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value
+  if ($rule.AccessControlType -ne [System.Security.AccessControl.AccessControlType]::Allow -or $sid -notin $allowed) { exit 2 }
+  if (($rule.FileSystemRights -band [System.Security.AccessControl.FileSystemRights]::FullControl) -ne [System.Security.AccessControl.FileSystemRights]::FullControl) { exit 3 }
+  if ($sid -eq $owner) { $ownerAllowed = $true }
+}
+if (-not $ownerAllowed) { exit 4 }
+"""
+    environment = {
+        "SystemRoot": os.environ.get("SystemRoot", r"C:\Windows"),
+        "AKYLDASH_ACL_PATH": str(path),
+    }
+    result = subprocess.run(
+        ["powershell.exe", "-NoProfile", "-NonInteractive", "-Command", command],
+        env=environment, text=True, capture_output=True,
+    )
+    if result.returncode:
+        raise ValueError(f"backup path ACL is not private (PowerShell status {result.returncode})")
+
+
+def check_capacity(free_bytes: int) -> None:
+    if free_bytes < MAX_ARCHIVE_BYTES + 1024 * 1024:
+        raise ValueError("D: must have room for the maximum 100 GiB archive plus staging metadata")
+
+
+def check_repository_target(repository: Path, backup_id: str, *, allow_existing: bool = False) -> tuple[Path, Path]:
+    if not repository.is_absolute() or not repository.is_dir() or _reparse(repository):
+        raise ValueError("repository must be an existing real directory on the selected Windows volume")
+    if _WINDOWS and repository.drive.upper() != "D:":
+        raise ValueError("external backup destination is restricted to D:\\Dev\\akyldash")
+    if _WINDOWS and repository.resolve().as_posix().lower() != "d:/dev/akyldash":
+        raise ValueError("external backup destination is restricted to D:\\Dev\\akyldash")
+    if _WINDOWS:
+        check_capacity(shutil.disk_usage(repository).free)
+    for parent in repository.parents:
+        if _reparse(parent):
+            raise ValueError("backup destination has a reparse-point parent")
+    git_dir = subprocess.run(
+        ["git", "-C", str(repository), "rev-parse", "--absolute-git-dir"],
+        check=True, text=True, capture_output=True,
+    ).stdout.strip()
+    exclude = Path(git_dir) / "info" / "exclude"
+    if _reparse(exclude) or not exclude.is_file():
+        raise ValueError("the repository's local .git/info/exclude file is unavailable or unsafe")
+    root = repository / ".backups"
+    final = root / backup_id
+    target_file = final / "backup.tar.gz"
+    relative = target_file.relative_to(repository).as_posix()
+    result = subprocess.run(
+        ["git", "-C", str(repository), "check-ignore", "--no-index", "-v", "--", relative],
+        text=True, capture_output=True,
+    )
+    if result.returncode:
+        raise ValueError("the exact D: backup target is not ignored by local Git metadata")
+    try:
+        source, _line, pattern = result.stdout.split("\t", 1)[0].rsplit(":", 2)
+    except ValueError as error:
+        raise ValueError("git check-ignore returned an unrecognized source record") from error
+    source_path = Path(source)
+    if not source_path.is_absolute():
+        source_path = repository / source_path
+    if source_path.resolve() != exclude.resolve() or pattern != "/.backups/":
+        raise ValueError("the exact D: backup target must be ignored by .git/info/exclude")
+    if root.exists():
+        if _reparse(root) or not root.is_dir():
+            raise ValueError("D: backup root must be a real directory")
+    else:
+        root.mkdir()
+    check_private_acl(root)
+    if final.exists() or _reparse(final):
+        if not allow_existing or _reparse(final) or not final.is_dir():
+            raise ValueError("backup ID already exists or resolves through a reparse point")
+    elif allow_existing:
+        raise ValueError("the pinned external backup is missing from D:")
+    return root, final
+
+
+def open_previous_backup(repository: Path, challenge: dict) -> Path:
+    _root, directory = check_repository_target(repository, challenge["backup_id"], allow_existing=True)
+    check_private_acl(directory)
+    archive_path = directory / "backup.tar.gz"
+    sidecar = directory / "backup.tar.gz.sha256"
+    for path in (archive_path, sidecar):
+        if _reparse(path) or not path.is_file():
+            raise ValueError("pinned external backup files must be regular files")
+        check_private_acl(path)
+    if archive_path.stat().st_size != challenge["size"]:
+        raise ValueError("pinned external backup size does not match root-owned release state")
+    expected_sidecar = f"{challenge['archive_sha256']}  backup.tar.gz\n"
+    if sidecar.read_text(encoding="ascii") != expected_sidecar:
+        raise ValueError("pinned external backup checksum sidecar does not match root-owned release state")
+    manifest = verify_external_archive(
+        archive_path,
+        expected_sha256=challenge["archive_sha256"],
+        expected_manifest_sha256=challenge["manifest_sha256"],
+    )
+    if manifest != challenge["manifest"]:
+        raise ValueError("pinned external backup contents differ from root-owned release state")
+    return archive_path
+
+
+def _drain_stderr(stream, output: bytearray) -> None:
+    while True:
+        chunk = stream.read(1024)
+        if not chunk:
+            return
+        if len(output) < MAX_ERROR_BYTES:
+            output.extend(chunk[: MAX_ERROR_BYTES - len(output)])
+
+
+def _unique_json_object(pairs: list[tuple[str, object]]) -> dict:
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("release status contains duplicate JSON fields")
+        result[key] = value
+    return result
+
+
+def validate_status_response(payload: bytes) -> dict | None:
+    if not payload or len(payload) > MAX_STATUS_BYTES:
+        raise ValueError("release status response is empty or exceeds its size limit")
+    try:
+        value = json.loads(payload.decode("utf-8"), object_pairs_hook=_unique_json_object)
+    except (UnicodeError, json.JSONDecodeError) as error:
+        raise ValueError("release status response is invalid JSON") from error
+    if (not isinstance(value, dict) or set(value) != {"schema_version", "state", "reason", "release"}
+            or type(value["schema_version"]) is not int or value["schema_version"] != 1):
+        raise ValueError("release status response has an unsupported schema")
+    if value["state"] == "not_ready":
+        if (not isinstance(value["reason"], str) or value["reason"] not in NOT_READY_REASONS
+                or value["release"] is not None):
+            raise ValueError("release status not-ready response is invalid")
+        return None
+    if value["state"] != "candidate" or value["reason"] is not None:
+        raise ValueError("release status state is invalid")
+    release = value["release"]
+    if not isinstance(release, dict) or set(release) != {"run_id", "commit", "descriptor_sha256"}:
+        raise ValueError("release status candidate tuple is invalid")
+    if (not isinstance(release["run_id"], str) or not re.fullmatch(r"[0-9]{1,20}", release["run_id"])
+            or not isinstance(release["commit"], str) or not re.fullmatch(r"[0-9a-f]{40}", release["commit"])
+            or not isinstance(release["descriptor_sha256"], str)
+            or not re.fullmatch(r"[0-9a-f]{64}", release["descriptor_sha256"])):
+        raise ValueError("release status candidate identity is invalid")
+    return {"version": 1, "action": "release", **release}
+
+
+def load_trigger_config(path: Path = TRIGGER_CONFIG) -> dict:
+    if not _WINDOWS:
+        raise ValueError("automatic release trigger is available only on Windows")
+    if (_reparse(path) or _reparse(path.parent) or not path.is_file()
+            or not path.parent.is_dir()):
+        raise ValueError("release trigger configuration is missing or unsafe")
+    check_private_acl(path.parent)
+    check_private_acl(path)
+    try:
+        with path.open("rb") as stream:
+            raw = stream.read(4097)
+    except OSError as error:
+        raise ValueError("release trigger configuration is unreadable") from error
+    if not raw or len(raw) > 4096:
+        raise ValueError("release trigger configuration is empty or oversized")
+    try:
+        value = json.loads(raw.decode("utf-8"), object_pairs_hook=_unique_json_object)
+    except (UnicodeError, json.JSONDecodeError) as error:
+        raise ValueError("release trigger configuration is invalid JSON") from error
+    if (not isinstance(value, dict)
+            or set(value) != {"schema_version", "enabled", "repository", "ssh_alias"}
+            or type(value["schema_version"]) is not int or value["schema_version"] != 1
+            or type(value["enabled"]) is not bool
+            or value["repository"] != str(DEFAULT_REPOSITORY)
+            or value["ssh_alias"] != DEFAULT_DEPLOY_SSH_ALIAS):
+        raise ValueError("release trigger configuration does not match the fixed deployment target")
+    return value
+
+
+def query_release_status(*, ssh: str = "ssh", ssh_alias: str = DEFAULT_DEPLOY_SSH_ALIAS) -> dict | None:
+    if shutil.which(ssh) is None:
+        raise ValueError("OpenSSH client is unavailable")
+    if ssh_alias != DEFAULT_DEPLOY_SSH_ALIAS:
+        raise ValueError("automatic release status uses only the fixed deployment SSH alias")
+    command = [
+        ssh, "-T", "-o", "BatchMode=yes", "-o", "ConnectTimeout=15",
+        "-o", "ClearAllForwardings=yes", "-o", "ForwardAgent=no", "-o", "ForwardX11=no",
+        ssh_alias, RELEASE_STATUS_COMMAND,
+    ]
+    process = subprocess.Popen(
+        command, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+    )
+    output = bytearray()
+    overflow = threading.Event()
+
+    def read_status() -> None:
+        while True:
+            chunk = process.stdout.read(min(4096, MAX_STATUS_BYTES + 1 - len(output)))
+            if not chunk:
+                return
+            if len(output) + len(chunk) > MAX_STATUS_BYTES:
+                overflow.set()
+                process.kill()
+                return
+            output.extend(chunk)
+
+    stdout_thread = threading.Thread(target=read_status, daemon=True)
+    stderr_thread = threading.Thread(target=_drain_stderr, args=(process.stderr, bytearray()), daemon=True)
+    stdout_thread.start()
+    stderr_thread.start()
+    try:
+        return_code = process.wait(timeout=STATUS_TIMEOUT_SECONDS)
+    except subprocess.TimeoutExpired as error:
+        process.kill()
+        process.wait()
+        raise ValueError("release status request timed out") from error
+    finally:
+        stdout_thread.join()
+        stderr_thread.join()
+    if overflow.is_set() or return_code:
+        raise ValueError("release status command failed or exceeded its response limit")
+    return validate_status_response(bytes(output))
+
+
+def receive_backup(reader, writer, *, repository: Path, request: dict, expected_context: dict | None = None) -> dict:
+    frame, value = read_response(reader)
+    if frame == "result":
+        raise ValueError(value["message"] or "remote deploy preflight failed")
+    header = value
+    context = header["context"]
+    if request["action"] == "release":
+        expected_context = {key: request[key] for key in ("action", "run_id", "commit", "descriptor_sha256")}
+        if context != expected_context:
+            raise ValueError("source backup session does not match the requested release tuple")
+    elif expected_context is None or context != expected_context:
+        raise ValueError("rollback backup session does not match the pinned previous backup")
+
+    root, final = check_repository_target(repository, header["backup_id"])
+    staging = Path(tempfile.mkdtemp(prefix=".staging-", dir=root))
+    staging_identity = None
+    published_identity = None
+    ack_started = False
+    try:
+        staging_identity = _directory_identity(staging)
+        check_private_acl(staging)
+        archive_path = staging / "backup.tar.gz"
+        with archive_path.open("xb") as archive_file:
+            size, archive_sha256 = receive_archive(reader, archive_file)
+            archive_file.flush()
+            os.fsync(archive_file.fileno())
+        os.chmod(archive_path, 0o600)
+        check_private_acl(archive_path)
+        manifest = verify_external_archive(
+            archive_path,
+            expected_sha256=archive_sha256,
+            expected_manifest_sha256=header["manifest_sha256"],
+        )
+        if manifest != header["manifest"]:
+            raise ValueError("saved backup contents differ from the source-generated session manifest")
+        sidecar = staging / "backup.tar.gz.sha256"
+        with sidecar.open("x", encoding="ascii", newline="\n") as stream:
+            stream.write(f"{archive_sha256}  backup.tar.gz\n")
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.chmod(sidecar, 0o600)
+        check_private_acl(sidecar)
+        if final.exists() or _reparse(final):
+            raise ValueError("backup ID already exists or resolves through a reparse point")
+        os.rename(staging, final)
+        published_identity = staging_identity
+        if _directory_identity(final) != published_identity:
+            raise ValueError("published backup directory identity changed during rename")
+        for path in (final, final / "backup.tar.gz", final / "backup.tar.gz.sha256"):
+            check_private_acl(path)
+        ack_started = True
+        write_ack(
+            writer, session_nonce=header["nonce"], backup_id=header["backup_id"], size=size,
+            archive_sha256=archive_sha256, manifest_sha256=header["manifest_sha256"], verified=True,
+        )
+        return {"backup_id": header["backup_id"], "archive_sha256": archive_sha256, "size": size}
+    except Exception as error:
+        cleanup_path = final if published_identity is not None and not ack_started else staging
+        cleanup_identity = published_identity if cleanup_path == final else staging_identity
+        if cleanup_identity is not None:
+            try:
+                _remove_owned_directory(cleanup_path, cleanup_identity)
+            except Exception as cleanup_error:
+                raise ValueError(
+                    f"backup failed and its output could not be safely removed; inspect {cleanup_path}"
+                ) from cleanup_error
+        raise
+
+
+def run_release(request: dict, *, repository: Path = DEFAULT_REPOSITORY, ssh: str = "ssh",
+                ssh_alias: str = "akyldash_vps") -> None:
+    if shutil.which(ssh) is None:
+        raise ValueError("OpenSSH client is unavailable")
+    if not ssh_alias or any(character not in "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_.-" for character in ssh_alias):
+        raise ValueError("SSH alias must name an existing owner-controlled host entry")
+    check_repository_target(repository, "preflight-" + secrets.token_hex(16))
+    process = subprocess.Popen(
+        [ssh, "-T", "-o", "BatchMode=yes", "-o", "ConnectTimeout=15",
+         "-o", "ClearAllForwardings=yes", "-o", "ForwardAgent=no", "-o", "ForwardX11=no",
+         ssh_alias, "/usr/local/sbin/akyldash-release-deploy"],
+        stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+    )
+    errors = bytearray()
+    thread = threading.Thread(target=_drain_stderr, args=(process.stderr, errors), daemon=True)
+    thread.start()
+    try:
+        write_request(process.stdin, request)
+        process.stdin.flush()
+        saved = receive_backup(process.stdout, process.stdin, repository=repository, request=request)
+        final = read_result(process.stdout)
+        if process.stdout.read(1):
+            raise ValueError("unexpected trailing bytes after external deployment result")
+        process.stdin.close()
+        return_code = process.wait()
+        thread.join()
+        if return_code or final["status"] != "success":
+            message = final.get("message", "remote deployment failed")
+            raise ValueError(f"remote deployment failed (ssh status {return_code}): {message}")
+        print(f"PASS release completed; verified external backup {saved['backup_id']} ({saved['size']} bytes)")
+    except Exception:
+        if process.poll() is None:
+            process.kill()
+        process.wait()
+        thread.join()
+        raise
+
+
+def run_release_once(*, config_file: Path = TRIGGER_CONFIG, ssh: str = "ssh") -> None:
+    config = load_trigger_config(config_file)
+    if not config["enabled"]:
+        print("Release trigger is disabled; no SSH connection opened.")
+        return
+    request = query_release_status(ssh=ssh, ssh_alias=config["ssh_alias"])
+    if request is None:
+        print("No verified current-main release is ready; deployment not started.")
+        return
+    run_release(request, repository=Path(config["repository"]), ssh=ssh, ssh_alias=config["ssh_alias"])
+
+
+def run_rollback(*, repository: Path = DEFAULT_REPOSITORY, ssh: str = "ssh",
+                 ssh_alias: str = "akyldash_vps") -> None:
+    if shutil.which(ssh) is None:
+        raise ValueError("OpenSSH client is unavailable")
+    if not ssh_alias or any(character not in "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_.-" for character in ssh_alias):
+        raise ValueError("SSH alias must name an existing owner-controlled host entry")
+    check_repository_target(repository, "preflight-" + secrets.token_hex(16))
+    process = subprocess.Popen(
+        [ssh, "-T", ssh_alias, "/usr/local/sbin/akyldash-release-rollback"],
+        stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+    )
+    errors = bytearray()
+    thread = threading.Thread(target=_drain_stderr, args=(process.stderr, errors), daemon=True)
+    thread.start()
+    request = {"version": 1, "action": "rollback", "data_compatible": True}
+    try:
+        write_request(process.stdin, request)
+        process.stdin.flush()
+        challenge = read_challenge(process.stdout)
+        archive_path = open_previous_backup(repository, challenge)
+        framed = ArchiveFrameWriter(process.stdin, maximum=challenge["size"])
+        with archive_path.open("rb") as archive_file:
+            for chunk in iter(lambda: archive_file.read(1024 * 1024), b""):
+                framed.write(chunk)
+        size, digest = framed.finish()
+        if size != challenge["size"] or digest != challenge["archive_sha256"]:
+            raise ValueError("D: previous backup changed during the live rollback session")
+        write_ack(process.stdin, session_nonce=challenge["nonce"], backup_id=challenge["backup_id"],
+                  size=size, archive_sha256=digest, manifest_sha256=challenge["manifest_sha256"], verified=True)
+        receive_backup(process.stdout, process.stdin, repository=repository, request=request,
+                       expected_context={key: challenge[key] for key in
+                                         ("backup_id", "archive_sha256", "manifest_sha256")} | {"action": "rollback"})
+        final = read_result(process.stdout)
+        if process.stdout.read(1):
+            raise ValueError("unexpected trailing bytes after external rollback result")
+        process.stdin.close()
+        return_code = process.wait()
+        thread.join()
+        if return_code or final["status"] != "success":
+            raise ValueError(f"remote rollback failed (ssh status {return_code}): {final.get('message', 'error')}")
+        print(f"PASS rollback completed; fresh external backup saved for {challenge['backup_id']}")
+    except Exception:
+        if process.poll() is None:
+            process.kill()
+        process.wait()
+        thread.join()
+        raise
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--once", action="store_true", help="query the fixed status endpoint and deploy at most one verified release")
+    parser.add_argument("--rollback", action="store_true")
+    parser.add_argument("--data-compatible", action="store_true")
+    parser.add_argument("--run-id")
+    parser.add_argument("--commit")
+    parser.add_argument("--descriptor-sha256")
+    parser.add_argument("--ssh-alias", default="akyldash_vps")
+    args = parser.parse_args()
+    try:
+        if args.once:
+            if (args.rollback or args.data_compatible or any(
+                    (args.run_id, args.commit, args.descriptor_sha256))
+                    or args.ssh_alias != "akyldash_vps"):
+                raise ValueError("--once accepts no release tuple, rollback, compatibility flag, or custom SSH alias")
+            run_release_once()
+        elif args.rollback:
+            if not args.data_compatible or any((args.run_id, args.commit, args.descriptor_sha256)):
+                raise ValueError("rollback requires --data-compatible and accepts no release tuple")
+            run_rollback(ssh_alias=args.ssh_alias)
+        else:
+            if not args.run_id or not args.commit or not args.descriptor_sha256 or args.data_compatible:
+                raise ValueError("release requires --run-id, --commit, and --descriptor-sha256")
+            request = {
+                "version": 1, "action": "release", "run_id": args.run_id,
+                "commit": args.commit, "descriptor_sha256": args.descriptor_sha256,
+            }
+            run_release(request, ssh_alias=args.ssh_alias)
+    except (OSError, ValueError, subprocess.SubprocessError, json.JSONDecodeError) as error:
+        print(f"ERROR: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

infra/backup/test_archive.py

@@ -1,4 +1,5 @@
 import hashlib
+import io
 import json
 import sqlite3
 import tarfile
@@ -8,7 +9,7 @@ from pathlib import Path
 from types import SimpleNamespace
 from unittest.mock import patch
 
-from archive import COMPONENTS, compose_sources, create_backup, restore_to_staging, verify_archive
+from archive import COMPONENTS, compose_sources, create_backup, create_backup_stream, restore_to_staging, verify_archive, verify_external_archive
 
 
 class BackupArchiveTests(unittest.TestCase):
@@ -50,6 +51,39 @@ class BackupArchiveTests(unittest.TestCase):
         self.assertEqual((target / "review-secret").stat().st_mode & 0o777, 0o600)
         self.assertEqual(verify_archive(self.backup)["components"], sorted(COMPONENTS))
 
+    def test_external_stream_uses_no_local_archive_and_verifies_received_bytes(self):
+        stream = io.BytesIO()
+        with patch("archive.os.geteuid", return_value=0):
+            manifest = create_backup_stream(stream, self.sources, "a" * 40)
+        self.assertFalse(self.backup.exists())
+        received = self.private / "received.tar.gz"
+        received.write_bytes(stream.getvalue())
+        verified = verify_external_archive(
+            received,
+            expected_sha256=hashlib.sha256(stream.getvalue()).hexdigest(),
+            expected_manifest_sha256=hashlib.sha256(
+                json.dumps(manifest, sort_keys=True, separators=(",", ":")).encode("utf-8")
+            ).hexdigest(),
+        )
+        self.assertEqual(verified["git_revision"], "a" * 40)
+
+    def test_external_archive_rejects_changed_manifest_and_duplicate_keys(self):
+        stream = io.BytesIO()
+        with tarfile.open(fileobj=stream, mode="w:gz") as archive:
+            info = tarfile.TarInfo("manifest.json")
+            raw = b'{"format":1,"format":1,"components":[],"images":{},"deployment_files":{}}'
+            info.size = len(raw)
+            archive.addfile(info, io.BytesIO(raw))
+            for name in COMPONENTS:
+                info = tarfile.TarInfo(name + "/")
+                info.type = tarfile.DIRTYPE
+                archive.addfile(info)
+        received = self.private / "duplicate.tar.gz"
+        received.write_bytes(stream.getvalue())
+        with self.assertRaisesRegex(ValueError, "duplicate backup manifest"):
+            verify_external_archive(received, expected_sha256=hashlib.sha256(stream.getvalue()).hexdigest(),
+                                    expected_manifest_sha256="0" * 64)
+
     def test_rejects_checksum_mismatch_without_creating_staging(self):
         create_backup(self.backup, self.sources, "abc123")
         self.backup.write_bytes(self.backup.read_bytes() + b"tamper")

infra/backup/test_external_session.py

@@ -0,0 +1,139 @@
+import hashlib
+import io
+import json
+import struct
+import unittest
+
+from external_session import (
+    ArchiveFrameWriter, CHUNK_BYTES, read_ack, read_challenge, read_header, read_request, read_result,
+    receive_archive, write_ack, write_challenge, write_header, write_request, write_result,
+)
+from external_session import ACK_MAGIC, MAGIC
+
+
+class ExternalSessionTests(unittest.TestCase):
+    def setUp(self):
+        self.nonce = "a" * 64
+        self.backup_id = "backup-20261031T120000Z"
+        self.manifest = {"format": 1, "git_revision": "b" * 40, "images": {}}
+
+    def make_stream(self, payload=b"tar\x00bytes" * 100):
+        stream = io.BytesIO()
+        manifest_sha = write_header(
+            stream, session_nonce=self.nonce, backup_id=self.backup_id, manifest=self.manifest
+        )
+        framed = ArchiveFrameWriter(stream, maximum=4096)
+        framed.write(payload[:37])
+        framed.write(payload[37:])
+        size, digest = framed.finish()
+        stream.seek(0)
+        return stream, payload, manifest_sha, size, digest
+
+    def test_binary_archive_round_trip_and_live_ack_binding(self):
+        stream, payload, manifest_sha, size, digest = self.make_stream()
+        header = read_header(stream)
+        target = io.BytesIO()
+        self.assertEqual(receive_archive(stream, target, maximum=4096), (size, digest))
+        self.assertEqual(target.getvalue(), payload)
+        self.assertEqual(hashlib.sha256(payload).hexdigest(), digest)
+
+        ack = io.BytesIO()
+        write_ack(ack, session_nonce=self.nonce, backup_id=self.backup_id,
+                  size=size, archive_sha256=digest, manifest_sha256=manifest_sha, verified=True)
+        ack.seek(0)
+        self.assertEqual(read_ack(
+            ack, session_nonce=header["nonce"], backup_id=header["backup_id"], size=size,
+            archive_sha256=digest, manifest_sha256=manifest_sha,
+        )["verified"], True)
+
+    def test_single_large_write_is_split_into_bounded_frames(self):
+        payload = b"x" * (CHUNK_BYTES * 2 + 13)
+        stream = io.BytesIO()
+        writer = ArchiveFrameWriter(stream)
+        writer.write(payload)
+        size, digest = writer.finish()
+        stream.seek(0)
+        target = io.BytesIO()
+        self.assertEqual(receive_archive(stream, target), (size, digest))
+        self.assertEqual(target.getvalue(), payload)
+
+    def test_rejects_wrong_nonce_replay_and_unverified_ack(self):
+        stream, _payload, manifest_sha, size, digest = self.make_stream()
+        ack = io.BytesIO()
+        write_ack(ack, session_nonce="c" * 64, backup_id=self.backup_id,
+                  size=size, archive_sha256=digest, manifest_sha256=manifest_sha, verified=True)
+        ack.seek(0)
+        with self.assertRaisesRegex(ValueError, "does not match"):
+            read_ack(ack, session_nonce=self.nonce, backup_id=self.backup_id, size=size,
+                     archive_sha256=digest, manifest_sha256=manifest_sha)
+
+    def test_rejects_corrupt_digest_truncated_stream_and_oversized_chunk(self):
+        stream, _payload, _manifest_sha, _size, _digest = self.make_stream()
+        read_header(stream)
+        corrupted = bytearray(stream.getvalue())
+        corrupted[-1] ^= 1
+        corrupted_stream = io.BytesIO(corrupted)
+        read_header(corrupted_stream)
+        with self.assertRaisesRegex(ValueError, "SHA-256"):
+            receive_archive(corrupted_stream, io.BytesIO(), maximum=4096)
+        truncated = io.BytesIO(stream.getvalue()[:-3])
+        read_header(truncated)
+        with self.assertRaisesRegex(ValueError, "ended before"):
+            receive_archive(truncated, io.BytesIO(), maximum=4096)
+        with self.assertRaisesRegex(ValueError, "size limit"):
+            receive_archive(io.BytesIO(b"\x00\x10\x00\x01"), io.BytesIO(), maximum=4096)
+
+    def test_final_result_is_bounded_and_typed(self):
+        stream = io.BytesIO()
+        write_result(stream, status="error", message="backup verification failed")
+        stream.seek(0)
+        self.assertEqual(read_result(stream)["status"], "error")
+        with self.assertRaisesRegex(ValueError, "invalid"):
+            write_result(io.BytesIO(), status="maybe")
+
+    def test_rollback_challenge_pins_external_archive_identity(self):
+        identity = {
+            "backup_id": self.backup_id, "size": 128, "archive_sha256": "c" * 64,
+            "manifest_sha256": hashlib.sha256(
+                json.dumps(self.manifest, sort_keys=True, separators=(",", ":")).encode()
+            ).hexdigest(), "manifest": self.manifest,
+        }
+        stream = io.BytesIO()
+        write_challenge(stream, identity, session_nonce=self.nonce)
+        stream.seek(0)
+        self.assertEqual(read_challenge(stream), {"version": 1, "nonce": self.nonce, **identity})
+        identity["size"] = 0
+        with self.assertRaisesRegex(ValueError, "identity"):
+            write_challenge(io.BytesIO(), identity, session_nonce=self.nonce)
+
+    def test_release_request_is_strictly_typed_and_rejects_extra_commands(self):
+        request = {
+            "version": 1, "action": "release", "run_id": "301", "commit": "b" * 40,
+            "descriptor_sha256": "c" * 64,
+        }
+        stream = io.BytesIO()
+        write_request(stream, request)
+        stream.seek(0)
+        self.assertEqual(read_request(stream), request)
+        with self.assertRaisesRegex(ValueError, "unexpected fields"):
+            write_request(io.BytesIO(), request | {"shell": "id"})
+
+    def test_protocol_rejects_boolean_integers_and_non_boolean_ack(self):
+        payload = json.dumps({"version": True, "action": "rollback", "data_compatible": True}).encode()
+        request = io.BytesIO(MAGIC + struct.pack("!I", len(payload)) + payload)
+        with self.assertRaisesRegex(ValueError, "unsupported version"):
+            read_request(request)
+        ack_value = {
+            "version": 1, "nonce": self.nonce, "backup_id": self.backup_id,
+            "size": 128, "archive_sha256": "c" * 64,
+            "manifest_sha256": "d" * 64, "verified": 1,
+        }
+        payload = json.dumps(ack_value).encode()
+        ack = io.BytesIO(ACK_MAGIC + struct.pack("!I", len(payload)) + payload)
+        with self.assertRaisesRegex(ValueError, "acknowledgement is invalid"):
+            read_ack(ack, session_nonce=self.nonce, backup_id=self.backup_id, size=128,
+                     archive_sha256="c" * 64, manifest_sha256="d" * 64)
+
+
+if __name__ == "__main__":
+    unittest.main()

infra/backup/test_receive_external.py

@@ -0,0 +1,314 @@
+import io
+import json
+import os
+import subprocess
+import xml.etree.ElementTree as ET
+import tarfile
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+import receive_external
+from archive import COMPONENTS
+from external_session import ArchiveFrameWriter, read_ack, write_header
+
+
+class ExternalReceiverTests(unittest.TestCase):
+    def test_windows_preflight_requires_full_protocol_archive_capacity(self):
+        required = receive_external.MAX_ARCHIVE_BYTES + 1024 * 1024
+        receive_external.check_capacity(required)
+        with self.assertRaisesRegex(ValueError, "maximum 100 GiB archive"):
+            receive_external.check_capacity(required - 1)
+
+    def setUp(self):
+        self.request = {
+            "version": 1, "action": "release", "run_id": "301", "commit": "a" * 40,
+            "descriptor_sha256": "b" * 64,
+        }
+        self.manifest = {
+            "format": 1, "created_at": "2026-10-31T12:00:00+00:00", "git_revision": "c" * 40,
+            "images": {"backend": {"configured": "backend:old", "image_id": "sha256:" + "d" * 64}},
+            "deployment_files": {"deploy/production/compose.yaml": "e" * 64},
+            "components": sorted(COMPONENTS),
+        }
+
+    def source_stream(self, context=None):
+        archive_stream = io.BytesIO()
+        with tarfile.open(fileobj=archive_stream, mode="w:gz") as archive:
+            manifest_bytes = json.dumps(self.manifest, sort_keys=True).encode("utf-8")
+            member = tarfile.TarInfo("manifest.json")
+            member.size = len(manifest_bytes)
+            archive.addfile(member, io.BytesIO(manifest_bytes))
+            for component in COMPONENTS:
+                member = tarfile.TarInfo(component + "/")
+                member.type = tarfile.DIRTYPE
+                archive.addfile(member)
+        payload = archive_stream.getvalue()
+        stream = io.BytesIO()
+        manifest_sha = write_header(
+            stream, session_nonce="f" * 64, backup_id="backup-20261031T120000Z",
+            manifest=self.manifest,
+            context=context or {key: self.request[key] for key in ("action", "run_id", "commit", "descriptor_sha256")},
+        )
+        framed = ArchiveFrameWriter(stream)
+        framed.write(payload)
+        size, digest = framed.finish()
+        stream.seek(0)
+        return stream, manifest_sha, size, digest
+
+    def test_verified_archive_is_atomically_published_before_ack(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            final = root / "backup-20261031T120000Z"
+            stream, manifest_sha, size, digest = self.source_stream()
+            ack = io.BytesIO()
+            with patch.object(receive_external, "check_repository_target", return_value=(root, final)), \
+                 patch.object(receive_external, "check_private_acl") as acl_check:
+                result = receive_external.receive_backup(
+                    stream, ack, repository=root, request=self.request
+                )
+            self.assertEqual(result, {"backup_id": final.name, "archive_sha256": digest, "size": size})
+            self.assertTrue((final / "backup.tar.gz").is_file())
+            if os.name == "nt":
+                for path in (final, final / "backup.tar.gz", final / "backup.tar.gz.sha256"):
+                    acl_check.assert_any_call(path)
+            else:
+                self.assertEqual((final / "backup.tar.gz").stat().st_mode & 0o777, 0o600)
+            self.assertEqual((final / "backup.tar.gz.sha256").read_text(), f"{digest}  backup.tar.gz\n")
+            ack.seek(0)
+            self.assertTrue(read_ack(
+                ack, session_nonce="f" * 64, backup_id=final.name, size=size,
+                archive_sha256=digest, manifest_sha256=manifest_sha,
+            )["verified"])
+
+    def test_mismatched_release_binding_never_publishes_or_acks(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            final = root / "backup-20261031T120000Z"
+            stream, _manifest_sha, _size, _digest = self.source_stream(
+                context={"action": "release", "run_id": "999", "commit": "a" * 40,
+                         "descriptor_sha256": "b" * 64}
+            )
+            ack = io.BytesIO()
+            with patch.object(receive_external, "check_repository_target", return_value=(root, final)), \
+                 patch.object(receive_external, "check_private_acl"):
+                with self.assertRaisesRegex(ValueError, "does not match"):
+                    receive_external.receive_backup(stream, ack, repository=root, request=self.request)
+            self.assertFalse(final.exists())
+            self.assertEqual(ack.getvalue(), b"")
+
+    def test_invalid_saved_stream_is_removed_without_publication(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            final = root / "backup-20261031T120000Z"
+            stream, _manifest_sha, _size, _digest = self.source_stream()
+            raw = bytearray(stream.getvalue())
+            raw[-1] ^= 1
+            ack = io.BytesIO()
+            with patch.object(receive_external, "check_repository_target", return_value=(root, final)), \
+                 patch.object(receive_external, "check_private_acl"):
+                with self.assertRaisesRegex(ValueError, "SHA-256"):
+                    receive_external.receive_backup(io.BytesIO(raw), ack, repository=root, request=self.request)
+            self.assertFalse(final.exists())
+            self.assertEqual(list(root.iterdir()), [])
+            self.assertEqual(ack.getvalue(), b"")
+
+    def test_post_publish_acl_failure_removes_owned_final_without_ack(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            final = root / "backup-20261031T120000Z"
+            stream, _manifest_sha, _size, _digest = self.source_stream()
+            ack = io.BytesIO()
+
+            def fail_published_archive(path):
+                if path == final / "backup.tar.gz":
+                    raise ValueError("post-publish ACL failed")
+
+            with patch.object(receive_external, "check_repository_target", return_value=(root, final)), \
+                 patch.object(receive_external, "check_private_acl", side_effect=fail_published_archive):
+                with self.assertRaisesRegex(ValueError, "post-publish ACL failed"):
+                    receive_external.receive_backup(stream, ack, repository=root, request=self.request)
+            self.assertFalse(final.exists())
+            self.assertEqual(list(root.iterdir()), [])
+            self.assertEqual(ack.getvalue(), b"")
+
+    def test_cleanup_refuses_a_replaced_or_reparse_directory(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            owned = root / "owned"
+            final = root / "final"
+            owned.mkdir()
+            identity = receive_external._directory_identity(owned)
+            owned.rename(root / "moved-owned")
+            final.mkdir()
+            with self.assertRaisesRegex(ValueError, "replaced backup directory"):
+                receive_external._remove_owned_directory(final, identity)
+            self.assertTrue(final.is_dir())
+            self.assertTrue((root / "moved-owned").is_dir())
+            if os.name != "nt":
+                link = root / "link"
+                link.symlink_to(final, target_is_directory=True)
+                with self.assertRaisesRegex(ValueError, "real directory"):
+                    receive_external._remove_owned_directory(link, identity)
+                self.assertTrue(final.is_dir())
+
+    def test_cleanup_refuses_unexpected_directory_contents(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "owned"
+            path.mkdir()
+            identity = receive_external._directory_identity(path)
+            (path / "foreign-data").write_text("keep", encoding="utf-8")
+            with self.assertRaisesRegex(ValueError, "unexpected backup content"):
+                receive_external._remove_owned_directory(path, identity)
+            self.assertEqual((path / "foreign-data").read_text(encoding="utf-8"), "keep")
+
+    def test_target_requires_exact_local_git_exclude_rule(self):
+        with tempfile.TemporaryDirectory() as directory:
+            repository = Path(directory)
+            exclude = repository / ".git/info/exclude"
+            exclude.parent.mkdir(parents=True)
+            exclude.write_text("/.backups/\n", encoding="utf-8")
+            responses = [
+                type("Result", (), {"stdout": str(repository / ".git"), "returncode": 0})(),
+                type("Result", (), {
+                    "stdout": f"{exclude}:1:/.backups/\t.backups/backup-id/backup.tar.gz\n",
+                    "returncode": 0,
+                })(),
+            ]
+            with patch.object(receive_external, "_WINDOWS", False), \
+                 patch.object(receive_external.subprocess, "run", side_effect=responses), \
+                 patch.object(receive_external, "check_private_acl"):
+                root, final = receive_external.check_repository_target(
+                    repository, "backup-id"
+                )
+            self.assertEqual(root, repository / ".backups")
+            self.assertEqual(final, root / "backup-id")
+
+    def test_windows_path_guard_rejects_a_synthetic_non_d_destination(self):
+        with tempfile.TemporaryDirectory() as directory:
+            repository = Path(directory)
+            with patch.object(receive_external, "_WINDOWS", True):
+                with self.assertRaisesRegex(ValueError, r"restricted to D:\\Dev\\akyldash"):
+                    receive_external.check_repository_target(repository, "backup-id")
+
+    def test_windows_acl_probe_does_not_inherit_credentials(self):
+        result = type("Result", (), {"returncode": 0})()
+        with patch.dict("os.environ", {"GITEA_TOKEN": "must-not-pass"}, clear=True), \
+             patch.object(receive_external.subprocess, "run", return_value=result) as run_mock:
+            receive_external.check_private_acl(Path(r"D:\Dev\akyldash\.backups"))
+        child_env = run_mock.call_args.kwargs["env"]
+        self.assertNotIn("GITEA_TOKEN", child_env)
+        self.assertEqual(child_env["AKYLDASH_ACL_PATH"], r"D:\Dev\akyldash\.backups")
+        self.assertIn("System.IO.DriveInfo", run_mock.call_args.args[0][-1])
+        self.assertNotIn("Get-Volume", run_mock.call_args.args[0][-1])
+        self.assertIn("$acl.GetOwner(", run_mock.call_args.args[0][-1])
+        self.assertIn("$aclOwner -notin $allowed", run_mock.call_args.args[0][-1])
+
+    def test_private_acl_rejects_an_unapproved_acl_owner(self):
+        result = type("Result", (), {"returncode": 6})()
+        with patch.object(receive_external.subprocess, "run", return_value=result) as run_mock:
+            with self.assertRaisesRegex(ValueError, "PowerShell status 6"):
+                receive_external.check_private_acl(Path(r"D:\Dev\akyldash\.backups"))
+        command = run_mock.call_args.args[0][-1]
+        self.assertIn("$acl.GetOwner(", command)
+        self.assertIn("if ($aclOwner -notin $allowed) { exit 6 }", command)
+
+    def test_destination_preflight_fails_before_opening_ssh(self):
+        with tempfile.TemporaryDirectory() as directory, \
+             patch.object(receive_external.shutil, "which", return_value="ssh"), \
+             patch.object(receive_external, "check_repository_target", side_effect=ValueError("preflight failed")) as preflight, \
+             patch.object(receive_external.subprocess, "Popen") as popen:
+            with self.assertRaisesRegex(ValueError, "preflight failed"):
+                receive_external.run_release(self.request, repository=Path(directory))
+            with self.assertRaisesRegex(ValueError, "preflight failed"):
+                receive_external.run_rollback(repository=Path(directory))
+        self.assertEqual(preflight.call_count, 2)
+        self.assertTrue(all(call.args[1].startswith("preflight-") for call in preflight.call_args_list))
+        popen.assert_not_called()
+
+    def test_status_response_accepts_only_the_fixed_candidate_tuple(self):
+        response = {"schema_version": 1, "state": "candidate", "reason": None,
+                    "release": {"run_id": "302", "commit": "a" * 40,
+                                "descriptor_sha256": "b" * 64}}
+        self.assertEqual(receive_external.validate_status_response(json.dumps(response).encode()),
+                         {"version": 1, "action": "release", **response["release"]})
+        response["reason"] = []
+        with self.assertRaises(ValueError):
+            receive_external.validate_status_response(json.dumps(response).encode())
+        self.assertIsNone(receive_external.validate_status_response(
+            b'{"schema_version":1,"state":"not_ready","reason":"already_applied","release":null}'
+        ))
+
+    def test_status_response_rejects_extra_or_duplicate_fields(self):
+        payload = (b'{"schema_version":1,"state":"not_ready","reason":"recovery_journal",'
+                   b'"release":null,"extra":0}')
+        with self.assertRaisesRegex(ValueError, "schema"):
+            receive_external.validate_status_response(payload)
+        with self.assertRaisesRegex(ValueError, "duplicate"):
+            receive_external.validate_status_response(
+                b'{"schema_version":1,"state":"not_ready","reason":"recovery_journal",'
+                b'"release":null,"release":null}')
+
+    def test_status_query_uses_only_fixed_command_and_non_forwarding_ssh(self):
+        payload = (b'{"schema_version":1,"state":"not_ready",'
+                   b'"reason":"no_current_main_release","release":null}\n')
+        process = type("Process", (), {
+            "stdout": io.BytesIO(payload), "stderr": io.BytesIO(),
+            "wait": lambda self, timeout: 0,
+        })()
+        with patch.object(receive_external.shutil, "which", return_value="ssh"), \
+             patch.object(receive_external.subprocess, "Popen", return_value=process) as popen:
+            self.assertIsNone(receive_external.query_release_status())
+        command = popen.call_args.args[0]
+        self.assertEqual(command[-2:], ["akyldash_release", receive_external.RELEASE_STATUS_COMMAND])
+        self.assertIn("ForwardAgent=no", command)
+        self.assertIn("ClearAllForwardings=yes", command)
+        self.assertEqual(popen.call_args.kwargs["stdin"], subprocess.DEVNULL)
+
+    def test_once_disabled_is_noop_and_candidate_reuses_existing_release_flow(self):
+        config = {"schema_version": 1, "enabled": False,
+                  "repository": str(receive_external.DEFAULT_REPOSITORY),
+                  "ssh_alias": receive_external.DEFAULT_DEPLOY_SSH_ALIAS}
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "trigger.json"
+            path.write_text(json.dumps(config), encoding="utf-8")
+            with patch.object(receive_external, "_WINDOWS", True), \
+                 patch.object(receive_external, "check_private_acl"), \
+                 patch.object(receive_external, "query_release_status") as query, \
+                 patch.object(receive_external, "run_release") as deploy:
+                receive_external.run_release_once(config_file=path)
+                query.assert_not_called()
+                deploy.assert_not_called()
+
+                config["enabled"] = True
+                path.write_text(json.dumps(config), encoding="utf-8")
+                candidate = {"version": 1, "action": "release", "run_id": "302",
+                             "commit": "a" * 40, "descriptor_sha256": "b" * 64}
+                query.return_value = candidate
+                receive_external.run_release_once(config_file=path)
+                deploy.assert_called_once_with(
+                    candidate, repository=receive_external.DEFAULT_REPOSITORY,
+                    ssh="ssh", ssh_alias="akyldash_release")
+
+    def test_windows_trigger_templates_are_fixed_and_disabled(self):
+        root = Path(__file__).resolve().parents[1] / "deploy"
+        config = json.loads((root / "windows-release-trigger.example.json").read_text(encoding="utf-8"))
+        self.assertEqual(config, {
+            "schema_version": 1, "enabled": False,
+            "repository": r"D:\Dev\akyldash", "ssh_alias": "akyldash_release",
+        })
+        task = ET.parse(root / "windows-release-trigger.example.xml").getroot()
+        ns = {"t": "http://schemas.microsoft.com/windows/2004/02/mit/task"}
+        self.assertEqual(task.findtext("t:Settings/t:Enabled", namespaces=ns), "false")
+        self.assertEqual(task.findtext("t:Settings/t:MultipleInstancesPolicy", namespaces=ns), "IgnoreNew")
+        self.assertEqual(task.findtext("t:Settings/t:StopIfGoingOnBatteries", namespaces=ns), "false")
+        self.assertEqual(task.findtext("t:Principals/t:Principal/t:RunLevel", namespaces=ns), "LeastPrivilege")
+        self.assertEqual(
+            task.findtext("t:Actions/t:Exec/t:Arguments", namespaces=ns),
+            '"C:\\Program Files\\Akyldash\\receive_external.py" --once',
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

infra/deploy/akyldash-release-deploy.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $EUID -ne 0 || $# -gt 1 || ( $# -eq 1 && $1 != status ) ]]; then
+  echo "This fixed receiver is owner-run as root and accepts its request only on stdin." >&2
+  exit 1
+fi
+
+helper=/usr/local/lib/akyldash/gitea-api
+token_file=/etc/akyldash/gitea-api-token
+origins_file=/etc/akyldash/gitea-download-origins
+if [[ -L $helper || ! -x $helper || $(stat -c %U:%a "$helper") != root:750 ]]; then
+  echo "The reviewed root-owned Gitea helper is not installed." >&2
+  exit 1
+fi
+if [[ -L $token_file || ! -f $token_file || $(stat -c %U:%a "$token_file") != root:600 ]]; then
+  echo "A root-owned mode-0600 read-only Gitea API token file is required." >&2
+  exit 1
+fi
+GITEA_TOKEN=$(< "$token_file")
+if [[ ! $GITEA_TOKEN =~ ^[A-Za-z0-9_-]+$ ]]; then
+  echo "The Gitea API token file is empty or has an invalid format." >&2
+  exit 1
+fi
+
+GITEA_DOWNLOAD_ORIGINS=
+if [[ -e $origins_file || -L $origins_file ]]; then
+  if [[ -L $origins_file || ! -f $origins_file || $(stat -c %U:%a "$origins_file") != root:600 ]]; then
+    echo "Gitea artifact redirect origins must be a root-owned mode-0600 file." >&2
+    exit 1
+  fi
+  while IFS= read -r origin || [[ -n $origin ]]; do
+    [[ -z $origin ]] && continue
+    if [[ ! $origin =~ ^https://[A-Za-z0-9.-]+(:[0-9]+)?$ ]]; then
+      echo "Gitea artifact redirect origin configuration is invalid." >&2
+      exit 1
+    fi
+    if [[ -n $GITEA_DOWNLOAD_ORIGINS ]]; then
+      GITEA_DOWNLOAD_ORIGINS+=,
+    fi
+    GITEA_DOWNLOAD_ORIGINS+=$origin
+  done < "$origins_file"
+fi
+
+export GITEA_URL=https://git.vakanaut.ru
+export GITEA_TOKEN GITEA_DOWNLOAD_ORIGINS
+export PATH=/usr/local/lib/akyldash:/usr/bin:/bin
+if [[ $# -eq 1 ]]; then
+  exec /usr/bin/python3 /usr/local/lib/akyldash/external_status.py
+fi
+exec /usr/bin/python3 /usr/local/lib/akyldash/external_deploy.py

infra/deploy/akyldash-release-dispatch.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $EUID -ne 0 || $# -ne 0 ]]; then
+  echo "The restricted release dispatcher accepts only its exact SSH command." >&2
+  exit 1
+fi
+
+case "${SSH_ORIGINAL_COMMAND:-}" in
+  /usr/local/sbin/akyldash-release-status)
+    exec /usr/local/sbin/akyldash-release-deploy status
+    ;;
+  /usr/local/sbin/akyldash-release-deploy)
+    exec /usr/local/sbin/akyldash-release-deploy
+    ;;
+  *)
+    echo "The restricted release dispatcher accepts only status or deploy." >&2
+    exit 126
+    ;;
+esac

infra/deploy/akyldash-release-rollback.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $EUID -ne 0 || $# -ne 0 ]]; then
+  echo "This fixed receiver is owner-run as root and accepts its request only on stdin." >&2
+  exit 1
+fi
+export PATH=/usr/local/lib/akyldash:/usr/bin:/bin
+exec /usr/bin/python3 /usr/local/lib/akyldash/external_rollback.py

infra/deploy/create_release_manifest.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Create a traceable, unsigned release descriptor from verified build digests."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+BUILDER_IMAGE = "ghcr.io/osscontainertools/kaniko:v1.28.5-debug@sha256:c73ca67a3b494bce79a8fb6090c4f73c18997ab272d80bffc460a62343aeb412"
+
+
+def digest(path: Path) -> str:
+    value = path.read_text(encoding="ascii").strip()
+    if not re.fullmatch(r"sha256:[0-9a-f]{64}", value):
+        raise ValueError(f"invalid Kaniko digest in {path}")
+    return value
+
+
+def create(repository: str, commit: str, source_run_id: str, run_id: str, backend: Path, opensearch: Path) -> dict:
+    if not re.fullmatch(r"[a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9._-]*", repository):
+        raise ValueError("repository must be lowercase owner/repository")
+    if not re.fullmatch(r"[0-9a-f]{40}", commit):
+        raise ValueError("commit must be a 40-character lowercase Git SHA-1")
+    if not re.fullmatch(r"[0-9]+", run_id):
+        raise ValueError("run_id must be numeric")
+    if not re.fullmatch(r"[0-9]+", source_run_id):
+        raise ValueError("source_run_id must be numeric")
+    registry = "git.vakanaut.ru/" + repository
+    return {
+        "schema_version": 4,
+        "source_ref": "refs/heads/main",
+        "repository": repository,
+        "commit": commit,
+        "workflow": ".gitea/workflows/release-images.yaml",
+        "run_id": run_id,
+        "source_run_id": source_run_id,
+        "builder": {"name": "Kaniko", "image": BUILDER_IMAGE},
+        "images": {
+            "backend": f"{registry}/backend@{digest(backend)}",
+            "opensearch": f"{registry}/opensearch@{digest(opensearch)}",
+        },
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--repository", required=True)
+    parser.add_argument("--commit", required=True)
+    parser.add_argument("--run-id", required=True)
+    parser.add_argument("--source-run-id", required=True)
+    parser.add_argument("--backend-digest", required=True, type=Path)
+    parser.add_argument("--opensearch-digest", required=True, type=Path)
+    parser.add_argument("--output", required=True, type=Path)
+    args = parser.parse_args()
+    try:
+        manifest = create(args.repository, args.commit, args.source_run_id, args.run_id, args.backend_digest, args.opensearch_digest)
+        args.output.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    except (OSError, UnicodeError, ValueError) as error:
+        print(f"ERROR: {error}", file=sys.stderr)
+        return 1
+    print(f"PASS release descriptor for {manifest['commit']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

infra/deploy/deploy_release.py

@@ -0,0 +1,257 @@
+#!/usr/bin/env python3
+"""Owner-run, locked production release cutover using a verified cold backup."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import urllib.parse
+from pathlib import Path
+
+from create_release_manifest import BUILDER_IMAGE
+from deployment_lock import deployment_lock
+from release_refs import read_images, replace_images
+from release_state import read_json, validate_images, validate_state, write_json_atomic
+from validate_release import read_json as read_manifest_json, validate_manifest
+
+ROOT = Path("/opt/akyldash/current")
+COMPOSE_FILE = ROOT / "deploy/production/compose.yaml"
+ENV_FILE = Path("/etc/akyldash/production.env")
+BACKUP_DIR = Path("/var/backups/akyldash")
+BACKUP_TOOL = Path("/usr/local/lib/akyldash/archive.py")
+STATE_FILE = Path("/opt/akyldash/release-state.json")
+JOURNAL_FILE = Path("/opt/akyldash/release-recovery.json")
+DEPLOYED_IMAGE_FILE = Path("/opt/akyldash/deployed-image.txt")
+SERVICES = ("backend", "opensearch")
+SEARCH_CANARY_URL = "https://akyldash.kg/search"
+
+
+def run(command: list[str], capture: bool = False) -> str:
+    result = subprocess.run(command, check=True, text=True, capture_output=capture)
+    return result.stdout.strip() if capture else ""
+
+
+def compose(*args: str, capture: bool = False) -> str:
+    return run(["docker", "compose", "--env-file", str(ENV_FILE), "-f", str(COMPOSE_FILE), *args], capture)
+
+
+def image_ids(*, allow_stopped: bool = False) -> dict[str, dict[str, str]]:
+    configured = read_images(ENV_FILE)[1]
+    records = {}
+    for service, key in (("backend", "BACKEND_IMAGE"), ("opensearch", "OPENSEARCH_IMAGE")):
+        container = compose("ps", "--all", "--quiet", service, capture=True)
+        if not container or "\n" in container:
+            raise ValueError(f"expected exactly one existing {service} container")
+        inspection = run(
+            ["docker", "inspect", "--format", "{{.State.Running}}\t{{.Image}}", container], capture=True
+        )
+        running, separator, image_id = inspection.partition("\t")
+        if not separator or (running != "true" and not (allow_stopped and running == "false")):
+            raise ValueError(f"{service} container state is not approved for the release operation")
+        if not re.fullmatch(r"sha256:[0-9a-f]{64}", image_id):
+            raise ValueError(f"invalid running image ID for {service}")
+        records[service] = {"configured": configured[key], "image_id": image_id}
+    return records
+
+
+def write_deployed_backend_image(image_id: str) -> None:
+    if not re.fullmatch(r"sha256:[0-9a-f]{64}", image_id):
+        raise ValueError("invalid backend image ID for deployment record")
+    with tempfile.NamedTemporaryFile(dir=DEPLOYED_IMAGE_FILE.parent, prefix=".deployed-image-", delete=False) as stream:
+        temporary = Path(stream.name)
+        stream.write(f"{image_id}\n".encode("ascii"))
+        stream.flush()
+        os.fsync(stream.fileno())
+    try:
+        os.chmod(temporary, 0o600)
+        os.replace(temporary, DEPLOYED_IMAGE_FILE)
+        directory_fd = os.open(DEPLOYED_IMAGE_FILE.parent, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
+        try:
+            os.fsync(directory_fd)
+        finally:
+            os.close(directory_fd)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def require_backup_matches_current(current: dict, backup: dict) -> None:
+    if current != backup:
+        raise ValueError("backup image references or image IDs do not match the current deployment")
+
+
+def restore_previous_references(old_env: dict[str, str], new_env: dict[str, str]) -> None:
+    _, actual = read_images(ENV_FILE)
+    if actual == new_env:
+        replace_images(ENV_FILE, new_env, old_env)
+    elif actual != old_env:
+        raise ValueError("production image references match neither the previous nor target release")
+    _, restored = read_images(ENV_FILE)
+    if restored != old_env:
+        raise ValueError("previous production image references could not be verified")
+
+
+def app_images(value: dict, label: str) -> dict[str, dict[str, str]]:
+    images = value.get("images")
+    if not isinstance(images, dict) or not set(SERVICES) <= images.keys():
+        raise ValueError(f"{label} does not contain both application image records")
+    return validate_images({service: images[service] for service in SERVICES}, label)
+
+
+def validate_search_response(payload: dict, language: str) -> None:
+    results = payload.get("results") if isinstance(payload, dict) else None
+    if not isinstance(results, list) or not results:
+        raise ValueError(f"{language} search canary returned no results")
+    if not isinstance(results[0], dict) or not str(results[0].get("code", "")).strip():
+        raise ValueError(f"{language} search canary returned a malformed first result")
+
+
+def check_search_canary(language: str, query: str) -> None:
+    if language not in {"ru", "ky"} or not query.strip():
+        raise ValueError("both Russian and Kyrgyz search canaries must be non-empty")
+    params = urllib.parse.urlencode({"q": query, "language": language, "page_size": "1"})
+    output = run(
+        ["curl", "--fail", "--silent", "--show-error", "--resolve", "akyldash.kg:443:127.0.0.1",
+         f"{SEARCH_CANARY_URL}?{params}"], capture=True
+    )
+    try:
+        payload = json.loads(output)
+    except json.JSONDecodeError as error:
+        raise ValueError(f"{language} search canary returned invalid JSON") from error
+    validate_search_response(payload, language)
+
+
+def deploy_external(
+    manifest_value: dict, policy_value: dict, backup_value: dict, backup_identity: dict,
+    descriptor_sha256: str, current_before_stop: dict, canary_ru: str, canary_ky: str,
+) -> None:
+    if os.geteuid() != 0:
+        raise ValueError("production cutover is owner-run and requires root")
+    manifest = validate_manifest(manifest_value, policy_value)
+    if manifest["builder"] != {"name": "Kaniko", "image": BUILDER_IMAGE}:
+        raise ValueError("release descriptor uses an unapproved builder")
+    from release_state import validate_backup_identity
+
+    backup_identity = validate_backup_identity({
+        key: backup_identity[key]
+        for key in ("backup_id", "size", "archive_sha256", "manifest_sha256", "manifest")
+    })
+    if backup_identity is None or backup_identity["manifest"] != backup_value:
+        raise ValueError("release requires a source-generated, live-verified external backup")
+    if not re.fullmatch(r"[0-9a-f]{64}", descriptor_sha256):
+        raise ValueError("release descriptor digest is invalid")
+    from release_handoff import latest_main_sha
+    if latest_main_sha(ROOT) != manifest["commit"]:
+        raise ValueError("main advanced after the external backup; refusing a stale release cutover")
+    if not isinstance(current_before_stop, dict) or image_ids(allow_stopped=True) != current_before_stop:
+        raise ValueError("stopped services do not match the pre-backup image snapshot")
+    if app_images(backup_value, "external backup images") != current_before_stop:
+        raise ValueError("external backup image identities do not match the current deployment")
+    repository_revision = run(["git", "-C", str(ROOT), "rev-parse", "HEAD"], capture=True)
+    if repository_revision != manifest["commit"]:
+        raise ValueError("host checkout does not match the verified release commit")
+    current_files = {
+        name: hashlib.sha256((ROOT / name).read_bytes()).hexdigest()
+        for name in ("deploy/production/compose.yaml", "deploy/production/Caddyfile")
+    }
+    if backup_value.get("deployment_files") != current_files:
+        raise ValueError("external backup configuration does not match the checked out Compose and Caddy files")
+    pinned = None
+    if STATE_FILE.exists() or STATE_FILE.is_symlink():
+        pinned = validate_state(read_json(STATE_FILE))
+        if pinned["current"] != current_before_stop:
+            raise ValueError("current deployment does not match the recorded release state")
+
+    backup_record = {
+        "backup_id": backup_identity["backup_id"],
+        "size": backup_identity["size"],
+        "archive_sha256": backup_identity["archive_sha256"],
+        "manifest_sha256": backup_identity["manifest_sha256"],
+        "manifest": backup_value,
+    }
+    backup_record = validate_backup_identity(backup_record)
+
+    old_env = {"BACKEND_IMAGE": current_before_stop["backend"]["configured"], "OPENSEARCH_IMAGE": current_before_stop["opensearch"]["configured"]}
+    new_env = {"BACKEND_IMAGE": manifest["images"]["backend"], "OPENSEARCH_IMAGE": manifest["images"]["opensearch"]}
+    journal = read_json(JOURNAL_FILE)
+    state_written = False
+    try:
+        for service in SERVICES:
+            reference = manifest["images"][service]
+            run(["docker", "pull", reference])
+            pulled_id = run(["docker", "image", "inspect", "--format", "{{.Id}}", reference], capture=True)
+            if not re.fullmatch(r"sha256:[0-9a-f]{64}", pulled_id):
+                raise ValueError(f"registry returned an invalid image ID for {service}")
+        target = {
+            service: {"configured": manifest["images"][service], "image_id": run(
+                ["docker", "image", "inspect", "--format", "{{.Id}}", manifest["images"][service]], capture=True
+            )}
+            for service in SERVICES
+        }
+        journal.update({"status": "external-backup-verified", "target": target})
+        write_json_atomic(JOURNAL_FILE, journal)
+        replace_images(ENV_FILE, old_env, new_env)
+        journal["status"] = "references-switched"
+        write_json_atomic(JOURNAL_FILE, journal)
+        compose("up", "--detach", "--no-build", "--wait", "--wait-timeout", "300")
+        actual = image_ids()
+        if actual != target:
+            raise ValueError("started image IDs do not match the release descriptor")
+        run(["curl", "--fail", "--silent", "--show-error", "--resolve", "akyldash.kg:443:127.0.0.1",
+             "https://akyldash.kg/review", "--output", "/dev/null"])
+        check_search_canary("ru", canary_ru)
+        check_search_canary("ky", canary_ky)
+        write_deployed_backend_image(actual["backend"]["image_id"])
+        state = {
+            "schema_version": 2, "commit": manifest["commit"],
+            "manifest_sha256": descriptor_sha256, "current": actual,
+            "previous": current_before_stop, "previous_backup": backup_record,
+        }
+        write_json_atomic(STATE_FILE, state)
+        state_written = True
+        JOURNAL_FILE.unlink()
+        print(f"PASS deployed release {manifest['commit']} with --no-build", file=sys.stderr)
+    except Exception as error:
+        if state_written:
+            journal["status"] = "release-active-journal-cleanup-needed"
+            journal["error_type"] = type(error).__name__
+            journal["recovery"] = "release is active; verify host and resolve the recovery journal"
+            write_json_atomic(JOURNAL_FILE, journal)
+            raise ValueError(f"release is active; recovery journal preserved at {JOURNAL_FILE}") from error
+        journal["status"] = "cutover-failed"
+        journal["error_type"] = type(error).__name__
+        try:
+            restore_previous_references(old_env, new_env)
+            compose("up", "--detach", "--no-build", "--wait", "--wait-timeout", "300")
+            restored = image_ids()
+            if restored != current_before_stop:
+                raise ValueError("restored running image IDs do not match the previous release")
+            write_deployed_backend_image(current_before_stop["backend"]["image_id"])
+            if pinned is not None:
+                write_json_atomic(STATE_FILE, pinned)
+            elif (STATE_FILE.exists() or STATE_FILE.is_symlink()) and not STATE_FILE.is_symlink():
+                STATE_FILE.unlink()
+            journal["recovery"] = "previous references and running image IDs restored and verified"
+        except Exception as recovery_error:
+            journal["recovery"] = (
+                f"manual recovery required ({type(recovery_error).__name__}); "
+                "references, release state, and external backup identity are recorded"
+            )
+        write_json_atomic(JOURNAL_FILE, journal)
+        raise ValueError(f"cutover failed; recovery journal preserved at {JOURNAL_FILE}") from error
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    argparse.ArgumentParser(description=__doc__).parse_args()
+    print("ERROR: local backup paths are disabled; use the fixed external session receiver", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

infra/deploy/deployment_lock.py

@@ -0,0 +1,32 @@
+"""One root-owned lock shared by image cutover and rollback."""
+
+from __future__ import annotations
+
+import fcntl
+import os
+import stat
+from contextlib import contextmanager
+from pathlib import Path
+
+LOCK_FILE = Path("/run/akyldash-deploy.lock")
+
+
+@contextmanager
+def deployment_lock():
+    descriptor = os.open(LOCK_FILE, os.O_CREAT | os.O_RDWR | getattr(os, "O_NOFOLLOW", 0), 0o600)
+    try:
+        info = os.fstat(descriptor)
+        if not stat.S_ISREG(info.st_mode) or info.st_mode & 0o777 != 0o600:
+            raise ValueError("deployment lock must be a regular mode-0600 file")
+        if os.geteuid() == 0 and info.st_uid != 0:
+            raise ValueError("deployment lock must be root-owned")
+        try:
+            fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError as error:
+            raise ValueError("another deployment or rollback holds the shared lock") from error
+        try:
+            yield
+        finally:
+            fcntl.flock(descriptor, fcntl.LOCK_UN)
+    finally:
+        os.close(descriptor)

infra/deploy/external_deploy.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Fixed root-side Gitea release receiver and external-backup cutover."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+from archive import compose_sources
+from deployment_lock import deployment_lock
+from deploy_release import JOURNAL_FILE, ROOT, SERVICES, compose, deploy_external, image_ids
+from external_session import read_request, send_backup_session, validate_request, write_result
+from release_source import fetch_release
+from release_state import read_json, validate_state, write_json_atomic
+
+POLICY_FILE = Path("/etc/akyldash/release-policy.json")
+CANARIES_FILE = Path("/etc/akyldash/release-canaries.json")
+COMPOSE_FILE = ROOT / "deploy/production/compose.yaml"
+ENV_FILE = Path("/etc/akyldash/production.env")
+
+
+def owner_canaries() -> tuple[str, str]:
+    info = CANARIES_FILE.lstat()
+    if (CANARIES_FILE.is_symlink() or not CANARIES_FILE.is_file() or info.st_uid != 0
+            or info.st_mode & 0o777 != 0o600):
+        raise ValueError("release canaries must be stored in a root-owned mode-0600 file")
+    value = json.loads(CANARIES_FILE.read_text(encoding="utf-8"))
+    if not isinstance(value, dict) or set(value) != {"ru", "ky"}:
+        raise ValueError("release canary configuration must contain exactly ru and ky")
+    queries = (value["ru"], value["ky"])
+    if any(not isinstance(query, str) or not query.strip() or len(query) > 256 for query in queries):
+        raise ValueError("release canaries must be non-empty strings of at most 256 characters")
+    return queries
+
+
+def restart_current(current: dict) -> None:
+    compose("up", "--detach", "--no-build", "--wait", "--wait-timeout", "300")
+    if image_ids() != current:
+        raise ValueError("restarted service image IDs do not match the pre-backup deployment")
+
+
+def execute(request: dict, *, reader, writer, policy: dict | None = None, api=None,
+            current_main: str | None = None, canaries: tuple[str, str] | None = None) -> dict:
+    if os.geteuid() != 0:
+        raise ValueError("the fixed external deployment receiver must run as root")
+    validate_request(request)
+    policy = policy if policy is not None else read_json(POLICY_FILE)
+    canary_ru, canary_ky = canaries or owner_canaries()
+    if JOURNAL_FILE.exists() or JOURNAL_FILE.is_symlink():
+        raise ValueError(f"recovery journal exists at {JOURNAL_FILE}; resolve it before another release")
+    manifest, _manifest_bytes = fetch_release(
+        request, policy=policy, current_main=current_main, checkout=ROOT,
+        **({"api": api} if api is not None else {}),
+    )
+
+    with deployment_lock():
+        if JOURNAL_FILE.exists() or JOURNAL_FILE.is_symlink():
+            raise ValueError(f"recovery journal exists at {JOURNAL_FILE}; resolve it before another release")
+        current = image_ids()
+        current_record = {service: current[service] for service in SERVICES}
+        revision = deploy_release_revision()
+        if revision != manifest["commit"]:
+            raise ValueError("installed host checkout does not match the verified release commit")
+        previous_state = None
+        if STATE_FILE.exists() or STATE_FILE.is_symlink():
+            previous_state = validate_state(read_json(STATE_FILE))
+            if previous_state["current"] != current_record:
+                raise ValueError("current deployment does not match the recorded release state")
+            if (previous_state["commit"] == manifest["commit"]
+                    and previous_state["manifest_sha256"] == request["descriptor_sha256"]):
+                raise ValueError("release is already applied")
+        journal = {
+            "schema_version": 2, "status": "external-backup-pending", "commit": manifest["commit"],
+            "manifest_sha256": request["descriptor_sha256"], "previous": current_record,
+        }
+        write_json_atomic(JOURNAL_FILE, journal)
+        try:
+            compose("stop")
+            sources, stopped_revision, stopped_images, deployment_files = compose_sources(COMPOSE_FILE, ENV_FILE)
+            if stopped_revision != revision or stopped_images.get("backend") != current["backend"] or stopped_images.get("opensearch") != current["opensearch"]:
+                raise ValueError("stopped production inventory does not match its pre-backup snapshot")
+            backup_identity = send_backup_session(
+                writer, reader, sources=sources, revision=stopped_revision,
+                images=stopped_images, deployment_files=deployment_files,
+                context={key: request[key] for key in ("action", "run_id", "commit", "descriptor_sha256")},
+            )
+        except Exception as error:
+            try:
+                restart_current(current)
+                JOURNAL_FILE.unlink(missing_ok=True)
+            except Exception as recovery_error:
+                journal.update({"status": "external-backup-failed",
+                                "error_type": type(error).__name__,
+                                "recovery_error_type": type(recovery_error).__name__})
+                write_json_atomic(JOURNAL_FILE, journal)
+                raise ValueError(f"external backup failed and current services need recovery; journal at {JOURNAL_FILE}") from error
+            raise
+
+        backup_record = {key: backup_identity[key] for key in
+                         ("backup_id", "size", "archive_sha256", "manifest_sha256", "manifest")}
+        journal = {
+            "schema_version": 2, "status": "external-backup-verified", "commit": manifest["commit"],
+            "manifest_sha256": request["descriptor_sha256"], "backup": backup_record,
+            "previous": current_record,
+        }
+        write_json_atomic(JOURNAL_FILE, journal)
+        try:
+            deploy_external(
+                manifest, policy, backup_identity["manifest"], backup_record,
+                request["descriptor_sha256"], current_record, canary_ru, canary_ky,
+            )
+        except Exception as error:
+            current_journal = read_json(JOURNAL_FILE) if JOURNAL_FILE.exists() else {}
+            if current_journal.get("status") == "external-backup-verified":
+                try:
+                    restart_current(current)
+                    JOURNAL_FILE.unlink()
+                except Exception as recovery_error:
+                    current_journal["status"] = "pre-cutover-recovery-needed"
+                    current_journal["error_type"] = type(error).__name__
+                    current_journal["recovery_error_type"] = type(recovery_error).__name__
+                    write_json_atomic(JOURNAL_FILE, current_journal)
+                    raise ValueError(f"pre-cutover recovery failed; journal at {JOURNAL_FILE}") from error
+            raise
+        return {"backup_id": backup_record["backup_id"], "commit": manifest["commit"]}
+
+
+def deploy_release_revision() -> str:
+    from deploy_release import run
+    return run(["git", "-C", str(ROOT), "rev-parse", "HEAD"], capture=True)
+
+
+STATE_FILE = Path("/opt/akyldash/release-state.json")
+
+
+def main() -> int:
+    try:
+        request = read_request(sys.stdin.buffer)
+        result = execute(request, reader=sys.stdin.buffer, writer=sys.stdout.buffer)
+        write_result(sys.stdout.buffer, status="success", message=result["backup_id"])
+    except Exception as error:
+        print(f"ERROR: {type(error).__name__}: {error}", file=sys.stderr)
+        try:
+            write_result(sys.stdout.buffer, status="error", message=f"deployment failed ({type(error).__name__})")
+        except (BrokenPipeError, OSError):
+            pass
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

infra/deploy/external_rollback.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""Root-side rollback using a pinned external backup and a fresh external backup."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from archive import compose_sources
+from deployment_lock import deployment_lock
+from deploy_release import COMPOSE_FILE, ENV_FILE, JOURNAL_FILE, ROOT, compose, image_ids
+from external_session import (nonce, read_ack, read_request,
+                              receive_archive, send_backup_session, write_challenge,
+                              write_result)
+from release_state import (read_json, validate_state, write_json_atomic)
+from rollback import rollback_external
+
+STATE_FILE = ROOT.parent / "release-state.json"
+
+
+class Discard:
+    def write(self, chunk: bytes) -> int:
+        return len(chunk)
+
+    def flush(self) -> None:
+        pass
+
+
+def execute(*, reader, writer) -> str:
+    if os.geteuid() != 0:
+        raise ValueError("the fixed external rollback receiver must run as root")
+    request = read_request(reader)
+    if request != {"version": 1, "action": "rollback", "data_compatible": True}:
+        raise ValueError("external rollback request is invalid")
+    if JOURNAL_FILE.exists() or JOURNAL_FILE.is_symlink():
+        raise ValueError(f"recovery journal exists at {JOURNAL_FILE}; resolve it before rollback")
+
+    with deployment_lock():
+        state = validate_state(read_json(STATE_FILE))
+        if state["schema_version"] != 2 or state["previous_backup"] is None:
+            raise ValueError("release state has no verified external previous backup")
+        target = state["previous_backup"]
+        session_nonce = nonce()
+        write_challenge(writer, target, session_nonce=session_nonce)
+        size, digest = receive_archive(reader, Discard(), maximum=target["size"])
+        if size != target["size"] or digest != target["archive_sha256"]:
+            raise ValueError("rollback bytes do not match the root-pinned external backup")
+        read_ack(reader, session_nonce=session_nonce, backup_id=target["backup_id"], size=size,
+                 archive_sha256=digest, manifest_sha256=target["manifest_sha256"])
+
+        current = image_ids()
+        if current != state["current"]:
+            raise ValueError("current deployment does not match root-pinned release state")
+        journal = {"schema_version": 2, "status": "external-backup-pending", "previous": current}
+        write_json_atomic(JOURNAL_FILE, journal)
+        try:
+            compose("stop")
+            sources, revision, stopped_images, deployment_files = compose_sources(COMPOSE_FILE, ENV_FILE)
+            if any(stopped_images.get(service) != record for service, record in current.items()):
+                raise ValueError("stopped deployment does not match its pre-rollback snapshot")
+            fresh = send_backup_session(
+                writer, reader, sources=sources, revision=revision, images=stopped_images,
+                deployment_files=deployment_files,
+                context={"action": "rollback", "backup_id": target["backup_id"],
+                         "archive_sha256": target["archive_sha256"],
+                         "manifest_sha256": target["manifest_sha256"]},
+            )
+        except Exception as error:
+            try:
+                compose("up", "--detach", "--no-build", "--wait", "--wait-timeout", "300")
+                if image_ids() != current:
+                    raise ValueError("restarted image IDs differ from the pre-rollback deployment")
+                JOURNAL_FILE.unlink(missing_ok=True)
+            except Exception as recovery_error:
+                journal.update({"status": "external-backup-failed",
+                                "error_type": type(error).__name__,
+                                "recovery_error_type": type(recovery_error).__name__})
+                write_json_atomic(JOURNAL_FILE, journal)
+                raise ValueError(f"rollback backup failed and services need recovery; journal at {JOURNAL_FILE}") from error
+            raise
+
+        fresh_record = {key: fresh[key] for key in
+                        ("backup_id", "size", "archive_sha256", "manifest_sha256", "manifest")}
+        write_json_atomic(JOURNAL_FILE, {
+            "schema_version": 2, "status": "external-backup-verified",
+            "backup": fresh_record, "previous": current,
+        })
+        try:
+            rollback_external(state=state, target_identity=target, current=current,
+                              fresh_backup=fresh_record, data_compatible=True)
+        except Exception as error:
+            journal = read_json(JOURNAL_FILE) if JOURNAL_FILE.exists() else {}
+            if journal.get("status") == "external-backup-verified":
+                try:
+                    compose("up", "--detach", "--no-build", "--wait", "--wait-timeout", "300")
+                    if image_ids() != current:
+                        raise ValueError("restarted image IDs differ from the pre-rollback deployment")
+                    JOURNAL_FILE.unlink()
+                except Exception as recovery_error:
+                    journal.update({
+                        "status": "pre-cutover-recovery-needed",
+                        "error_type": type(error).__name__,
+                        "recovery_error_type": type(recovery_error).__name__,
+                    })
+                    write_json_atomic(JOURNAL_FILE, journal)
+                    raise ValueError(f"rollback preflight failed and services need recovery; journal at {JOURNAL_FILE}") from error
+            raise
+        return fresh_record["backup_id"]
+
+
+def main() -> int:
+    try:
+        result = execute(reader=sys.stdin.buffer, writer=sys.stdout.buffer)
+        write_result(sys.stdout.buffer, status="success", message=result)
+        return 0
+    except Exception as error:
+        print(f"ERROR: {type(error).__name__}: {error}", file=sys.stderr)
+        try:
+            write_result(sys.stdout.buffer, status="error", message=f"rollback failed ({type(error).__name__})")
+        except OSError:
+            pass
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

infra/deploy/external_status.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Read-only selector for one fully verified current-main release candidate."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+from deploy_release import JOURNAL_FILE, ROOT, STATE_FILE
+from release_handoff import latest_main_sha
+from release_source import fetch_release, latest_release_request
+from release_state import read_json, validate_state
+
+POLICY_FILE = Path("/etc/akyldash/release-policy.json")
+STATUS_MAX_BYTES = 1024
+SHA_RE = re.compile(r"[0-9a-f]{40}\Z")
+
+
+def checkout_sha(checkout: Path) -> str:
+    result = subprocess.run(
+        ["git", "-C", str(checkout), "rev-parse", "HEAD"],
+        check=True, text=True, capture_output=True, timeout=10,
+    )
+    value = result.stdout.strip()
+    if not SHA_RE.fullmatch(value):
+        raise ValueError("production checkout revision is invalid")
+    return value
+
+
+def status_document(*, api=None, checkout: Path = ROOT, journal: Path = JOURNAL_FILE,
+                    policy_file: Path = POLICY_FILE, state_file: Path = STATE_FILE,
+                    main_lookup=latest_main_sha,
+                    checkout_lookup=checkout_sha) -> dict:
+    if os.geteuid() != 0:
+        raise ValueError("release status command must run as root")
+    if journal.exists() or journal.is_symlink():
+        return {"schema_version": 1, "state": "not_ready", "reason": "recovery_journal", "release": None}
+
+    current_main = main_lookup(checkout)
+    if checkout_lookup(checkout) != current_main:
+        return {"schema_version": 1, "state": "not_ready", "reason": "host_checkout_stale", "release": None}
+
+    api_args = {"api": api} if api is not None else {}
+    request = latest_release_request(current_main=current_main, checkout=checkout, **api_args)
+    if request is None:
+        return {"schema_version": 1, "state": "not_ready", "reason": "no_current_main_release", "release": None}
+    if state_file.exists() or state_file.is_symlink():
+        state = validate_state(read_json(state_file))
+        if (state["commit"] == request["commit"]
+                and state["manifest_sha256"] == request["descriptor_sha256"]):
+            return {"schema_version": 1, "state": "not_ready", "reason": "already_applied", "release": None}
+    manifest, _raw = fetch_release(
+        request, policy=read_json(policy_file), current_main=current_main, checkout=checkout,
+        **api_args,
+    )
+    if manifest["commit"] != current_main or manifest["run_id"] != request["run_id"]:
+        raise ValueError("verified release descriptor does not match the selected source")
+    if main_lookup(checkout) != current_main:
+        return {"schema_version": 1, "state": "not_ready", "reason": "main_advanced", "release": None}
+    if journal.exists() or journal.is_symlink():
+        return {"schema_version": 1, "state": "not_ready", "reason": "recovery_journal", "release": None}
+    if state_file.exists() or state_file.is_symlink():
+        state = validate_state(read_json(state_file))
+        if (state["commit"] == request["commit"]
+                and state["manifest_sha256"] == request["descriptor_sha256"]):
+            return {"schema_version": 1, "state": "not_ready", "reason": "already_applied", "release": None}
+    return {
+        "schema_version": 1,
+        "state": "candidate",
+        "reason": None,
+        "release": {key: request[key] for key in ("run_id", "commit", "descriptor_sha256")},
+    }
+
+
+def write_status(value: dict, stream=None) -> None:
+    payload = json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8") + b"\n"
+    if len(payload) > STATUS_MAX_BYTES:
+        raise ValueError("release status response exceeds its size limit")
+    (stream or sys.stdout.buffer).write(payload)
+
+
+def main() -> int:
+    try:
+        write_status(status_document())
+    except Exception as error:
+        print(f"release status unavailable ({type(error).__name__})", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

infra/deploy/gitea-api-base.fixture

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ -z "${GITEA_URL:-}" ]; then
+  echo "gitea-api: GITEA_URL is not set" >&2
+  exit 1
+fi
+
+if [ -z "${GITEA_TOKEN:-}" ]; then
+  echo "gitea-api: GITEA_TOKEN is not set" >&2
+  exit 1
+fi
+
+method="${1:-GET}"
+path="${2:-}"
+body="${3:-}"
+
+if [ -z "$path" ]; then
+  echo "Usage: gitea-api METHOD /path [JSON]" >&2
+  exit 2
+fi
+
+base="${GITEA_URL%/}/api/v1"
+tmp="$(mktemp)"
+
+cleanup() {
+  rm -f "$tmp"
+}
+trap cleanup EXIT
+
+args=(
+  -sS
+  -o "$tmp"
+  -w "%{http_code}"
+  -X "$method"
+  -H "Authorization: token ${GITEA_TOKEN}"
+  -H "Accept: application/json"
+)
+
+if [ -n "$body" ]; then
+  args+=(
+    -H "Content-Type: application/json"
+    --data "$body"
+  )
+fi
+
+http_code="$(curl "${args[@]}" "${base}${path}")"
+curl_status=$?
+
+cat "$tmp"
+
+if [ "$curl_status" -ne 0 ]; then
+  echo >&2
+  echo "gitea-api: curl failed with exit code $curl_status" >&2
+  exit "$curl_status"
+fi
+
+case "$http_code" in
+  2??)
+    exit 0
+    ;;
+  *)
+    echo >&2
+    echo "gitea-api: HTTP $http_code" >&2
+    exit 1
+    ;;
+esac

infra/deploy/gitea-api-binary-download.patch

@@ -0,0 +1,92 @@
+--- a/gitea-api
++++ b/gitea-api
+@@ -13,0 +14,5 @@
++if [[ ! "$GITEA_TOKEN" =~ ^[A-Za-z0-9_-]+$ ]]; then
++  echo "gitea-api: GITEA_TOKEN contains unsupported characters" >&2
++  exit 1
++fi
++
+@@ -30,0 +36,78 @@
++if [ "$method" = "DOWNLOAD" ]; then
++  output="$body"
++  max_bytes=10485760
++  if [ -z "$output" ] || [ ! -d "$(dirname "$output")" ] || [ -e "$output" ] || [ -L "$output" ]; then
++    echo "Usage: gitea-api DOWNLOAD /path /new/output-file" >&2
++    exit 2
++  fi
++  case "$GITEA_URL" in
++    https://*) gitea_host="${GITEA_URL#https://}"; gitea_host="${gitea_host%%/*}"; gitea_origin="https://${gitea_host}" ;;
++    *) echo "gitea-api: binary downloads require HTTPS" >&2; exit 2 ;;
++  esac
++  if [[ ! "$gitea_origin" =~ ^https://[A-Za-z0-9.-]+(:[0-9]+)?$ ]]; then
++    echo "gitea-api: invalid Gitea origin for binary download" >&2
++    exit 2
++  fi
++  headers="$(mktemp)"
++  download="$(mktemp "$(dirname "$output")/.gitea-api-download.XXXXXX")"
++  chmod 600 "$download"
++  cleanup() { rm -f "$tmp" "$headers" "$download"; }
++  trap cleanup EXIT
++
++  http_code="$(curl -sS -D "$headers" -o /dev/null -w "%{http_code}" --max-filesize 1048576 \
++    -H "Accept: application/octet-stream" --config - "${base}${path}" <<< "header = \"Authorization: token ${GITEA_TOKEN}\"")" || { echo "gitea-api: artifact metadata request failed" >&2; exit 1; }
++  if [[ "$http_code" == 2?? ]]; then
++    set +e
++    curl -sS --fail --proto '=https' --max-filesize "$max_bytes" \
++      --config - "$base$path" <<< "header = \"Authorization: token ${GITEA_TOKEN}\"" | head -c "$((max_bytes + 1))" > "$download"
++    statuses=("${PIPESTATUS[@]}")
++    set -e
++    size="$(wc -c < "$download")"
++    if (( size > max_bytes )); then
++      echo "gitea-api: artifact exceeds the 10 MiB download limit" >&2
++      exit 1
++    fi
++    if (( statuses[0] != 0 || statuses[1] != 0 )); then
++      echo "gitea-api: artifact download failed" >&2
++      exit 1
++    fi
++  elif [[ "$http_code" == 302 ]]; then
++    location="$(awk 'tolower(substr($0,1,9)) == "location:" { sub(/^[^:]*:[[:space:]]*/, ""); sub(/\r$/, ""); value=$0 } END { print value }' "$headers")"
++    if [[ ! "$location" =~ ^https://([A-Za-z0-9.-]+(:[0-9]+)?)(/[^#]*)?$ ]]; then
++      echo "gitea-api: artifact redirect is not an absolute HTTPS URL" >&2
++      exit 1
++    fi
++    redirect_origin="https://${BASH_REMATCH[1],,}"
++    gitea_origin="${gitea_origin,,}"
++    if [[ "$redirect_origin" != "$gitea_origin" && ",${GITEA_DOWNLOAD_ORIGINS:-}," != *",${redirect_origin},"* ]]; then
++      echo "gitea-api: artifact redirect origin is not allowlisted" >&2
++      exit 1
++    fi
++    set +e
++    curl -sS --proto '=https' --max-filesize "$max_bytes" -o - "$location" | head -c "$((max_bytes + 1))" > "$download"
++    statuses=("${PIPESTATUS[@]}")
++    set -e
++    size="$(wc -c < "$download")"
++    if (( size > max_bytes )); then
++      echo "gitea-api: artifact exceeds the 10 MiB download limit" >&2
++      exit 1
++    fi
++    if (( statuses[0] != 0 )); then
++      echo "gitea-api: artifact download failed" >&2
++      exit 1
++    fi
++  else
++    echo "gitea-api: artifact endpoint returned HTTP $http_code" >&2
++    exit 1
++  fi
++  size="$(wc -c < "$download")"
++  if (( size > max_bytes )); then
++    echo "gitea-api: artifact exceeds the 10 MiB download limit" >&2
++    exit 1
++  fi
++  chmod 600 "$download"
++  ln -- "$download" "$output" || { echo "gitea-api: output file already exists" >&2; exit 1; }
++  echo "PASS downloaded Gitea artifact (${size} bytes)"
++  exit 0
++fi
++
+@@ -36 +118,0 @@
+-  -H "Authorization: token ${GITEA_TOKEN}"
+@@ -47 +129 @@
+-http_code="$(curl "${args[@]}" "${base}${path}")"
++http_code="$(curl "${args[@]}" --config - "${base}${path}" <<< "header = \"Authorization: token ${GITEA_TOKEN}\"")"

infra/deploy/install-helper.sh

@@ -8,10 +8,21 @@ fi
 
 checkout=/opt/akyldash/current
 rollback_source=$checkout/infra/deploy/rollback.py
+release_refs_source=$checkout/infra/deploy/release_refs.py
+release_state_source=$checkout/infra/deploy/release_state.py
+deployment_lock_source=$checkout/infra/deploy/deployment_lock.py
 backup_source=$checkout/infra/backup/archive.py
 verify_source=$checkout/infra/bootstrap/verify-helper.sh
 compose_source=$checkout/infra/deploy/compose-helper.sh
-if [[ ! -d $checkout/.git || ! -f $rollback_source || ! -f $backup_source || ! -f $verify_source || ! -f $compose_source ]]; then
+release_deploy_source=$checkout/infra/deploy/akyldash-release-deploy.sh
+release_rollback_source=$checkout/infra/deploy/akyldash-release-rollback.sh
+release_dispatch_source=$checkout/infra/deploy/akyldash-release-dispatch.sh
+release_controller_source=$checkout/infra/deploy/external_deploy.py
+release_status_source=$checkout/infra/deploy/external_status.py
+gitea_helper_fixture=$checkout/infra/deploy/gitea-api-base.fixture
+gitea_helper_patch=$checkout/infra/deploy/gitea-api-binary-download.patch
+release_policy_source=$checkout/infra/deploy/release-policy.json
+if [[ ! -d $checkout/.git || ! -f $rollback_source || ! -f $release_refs_source || ! -f $release_state_source || ! -f $deployment_lock_source || ! -f $backup_source || ! -f $verify_source || ! -f $compose_source || ! -f $release_deploy_source || ! -f $release_rollback_source || ! -f $release_dispatch_source || ! -f $release_controller_source || ! -f $release_status_source || ! -f "$checkout/infra/deploy/external_rollback.py" || ! -f "$checkout/infra/backup/external_session.py" || ! -f "$checkout/infra/deploy/create_release_manifest.py" || ! -f "$checkout/infra/deploy/deploy_release.py" || ! -f "$checkout/infra/deploy/release_handoff.py" || ! -f "$checkout/infra/deploy/release_source.py" || ! -f "$checkout/infra/deploy/validate_release.py" || ! -f $gitea_helper_fixture || ! -f $gitea_helper_patch || ! -f $release_policy_source ]]; then
   echo "Install the approved repository checkout at $checkout first." >&2
   exit 1
 fi
@@ -43,8 +54,13 @@ if ! command -v visudo >/dev/null 2>&1; then
   echo "visudo is required to validate the restricted sudoers rule." >&2
   exit 1
 fi
+if ! command -v patch >/dev/null 2>&1 || ! command -v sha256sum >/dev/null 2>&1; then
+  echo "patch and sha256sum are required to install the reviewed binary-safe Gitea helper." >&2
+  exit 1
+fi
+bash -n "$release_deploy_source" "$release_rollback_source" "$release_dispatch_source"
 
-for path in /usr/local/sbin/akyldash-verify /usr/local/sbin/akyldash-rollback /usr/local/sbin/akyldash-compose /usr/local/lib/akyldash/archive.py /etc/sudoers.d/akyldash-codex; do
+for path in /usr/local/sbin/akyldash-verify /usr/local/sbin/akyldash-rollback /usr/local/sbin/akyldash-compose /usr/local/sbin/akyldash-release-deploy /usr/local/sbin/akyldash-release-rollback /usr/local/sbin/akyldash-release-dispatch /usr/local/lib/akyldash/archive.py /usr/local/lib/akyldash/external_session.py /usr/local/lib/akyldash/create_release_manifest.py /usr/local/lib/akyldash/deploy_release.py /usr/local/lib/akyldash/deployment_lock.py /usr/local/lib/akyldash/external_deploy.py /usr/local/lib/akyldash/external_status.py /usr/local/lib/akyldash/external_rollback.py /usr/local/lib/akyldash/rollback.py /usr/local/lib/akyldash/release_handoff.py /usr/local/lib/akyldash/release_refs.py /usr/local/lib/akyldash/release_source.py /usr/local/lib/akyldash/release_state.py /usr/local/lib/akyldash/validate_release.py /usr/local/lib/akyldash/gitea-api /etc/akyldash/release-policy.json /etc/sudoers.d/akyldash-codex; do
   if [[ -L $path ]]; then
     echo "Refusing symlink at $path." >&2
     exit 1
@@ -53,9 +69,44 @@ done
 
 install -d -o root -g root -m 0755 /usr/local/lib/akyldash
 install -o root -g root -m 0644 "$backup_source" /usr/local/lib/akyldash/archive.py
+install -o root -g root -m 0644 "$release_refs_source" /usr/local/lib/akyldash/release_refs.py
+install -o root -g root -m 0644 "$release_state_source" /usr/local/lib/akyldash/release_state.py
+install -o root -g root -m 0644 "$deployment_lock_source" /usr/local/lib/akyldash/deployment_lock.py
+install -o root -g root -m 0644 "$checkout/infra/backup/external_session.py" /usr/local/lib/akyldash/external_session.py
+install -o root -g root -m 0644 "$checkout/infra/deploy/create_release_manifest.py" /usr/local/lib/akyldash/create_release_manifest.py
+install -o root -g root -m 0644 "$checkout/infra/deploy/deploy_release.py" /usr/local/lib/akyldash/deploy_release.py
+install -o root -g root -m 0644 "$rollback_source" /usr/local/lib/akyldash/rollback.py
+install -o root -g root -m 0644 "$checkout/infra/deploy/external_deploy.py" /usr/local/lib/akyldash/external_deploy.py
+install -o root -g root -m 0644 "$release_status_source" /usr/local/lib/akyldash/external_status.py
+install -o root -g root -m 0644 "$checkout/infra/deploy/external_rollback.py" /usr/local/lib/akyldash/external_rollback.py
+install -o root -g root -m 0644 "$checkout/infra/deploy/release_handoff.py" /usr/local/lib/akyldash/release_handoff.py
+install -o root -g root -m 0644 "$checkout/infra/deploy/release_source.py" /usr/local/lib/akyldash/release_source.py
+install -o root -g root -m 0644 "$checkout/infra/deploy/validate_release.py" /usr/local/lib/akyldash/validate_release.py
+if [[ -e /etc/akyldash/release-policy.json ]]; then
+  if [[ -L /etc/akyldash/release-policy.json || $(stat -c %U:%a /etc/akyldash/release-policy.json) != root:600 || ! -f /etc/akyldash/release-policy.json || $(cat /etc/akyldash/release-policy.json) != "$(cat "$release_policy_source")" ]]; then
+    echo "The root-owned release policy exists with unexpected contents; review it manually." >&2
+    exit 1
+  fi
+else
+  install -o root -g root -m 0600 "$release_policy_source" /etc/akyldash/release-policy.json
+fi
+gitea_tmp=$(mktemp -d /run/akyldash-gitea-api.XXXXXX)
+trap 'rm -rf -- "$gitea_tmp"' EXIT
+cp "$gitea_helper_fixture" "$gitea_tmp/gitea-api"
+if [[ $(sha256sum "$gitea_tmp/gitea-api" | cut -d ' ' -f 1) != 8227332d28e27bcce9b4e3801f6b8d4323636174a82c93a0177970f560629df0 ]]; then
+  echo "The inspected base gitea-api helper changed; review a new patch before installing." >&2
+  exit 1
+fi
+patch --batch --fuzz=0 -p1 -d "$gitea_tmp" < "$gitea_helper_patch"
+bash -n "$gitea_tmp/gitea-api"
+install -o root -g root -m 0750 "$gitea_tmp/gitea-api" /usr/local/lib/akyldash/gitea-api
+rm -rf -- "$gitea_tmp"
 install -o root -g root -m 0750 "$verify_source" /usr/local/sbin/akyldash-verify
 install -o root -g root -m 0750 "$rollback_source" /usr/local/sbin/akyldash-rollback
 install -o root -g root -m 0750 "$compose_source" /usr/local/sbin/akyldash-compose
+install -o root -g root -m 0750 "$release_deploy_source" /usr/local/sbin/akyldash-release-deploy
+install -o root -g root -m 0750 "$release_rollback_source" /usr/local/sbin/akyldash-release-rollback
+install -o root -g root -m 0750 "$release_dispatch_source" /usr/local/sbin/akyldash-release-dispatch
 
 sudoers_file=/etc/sudoers.d/akyldash-codex
 expected=$'codex ALL=(root) NOPASSWD: /usr/local/sbin/akyldash-verify\ncodex ALL=(root) NOPASSWD: /usr/local/sbin/akyldash-rollback *\ncodex ALL=(root) NOPASSWD: /usr/local/sbin/akyldash-compose config\ncodex ALL=(root) NOPASSWD: /usr/local/sbin/akyldash-compose status'

infra/deploy/release-policy.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "repositories": {
+    "backend": ["git.vakanaut.ru/admin/akyldash/backend"],
+    "opensearch": ["git.vakanaut.ru/admin/akyldash/opensearch"]
+  }
+}

infra/deploy/release_handoff.py

@@ -0,0 +1,129 @@
+"""Fail-closed validation for CI-to-release and release-to-deploy workflow events."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+SHA_RE = re.compile(r"[0-9a-f]{40}\Z")
+RUN_ID_RE = re.compile(r"[0-9]+\Z")
+DESCRIPTOR_RE = re.compile(r"release-descriptor-([0-9]+)-([0-9a-f]{64})\Z")
+
+
+def latest_main_sha(checkout: Path | None = None) -> str:
+    result = subprocess.run(
+        ["git", "-C", str(checkout or Path.cwd()), "ls-remote", "--exit-code", "origin", "refs/heads/main"],
+        check=True,
+        text=True,
+        capture_output=True,
+        timeout=10,
+    )
+    if len(result.stdout) > 256:
+        raise ValueError("current main lookup exceeded its output limit")
+    fields = result.stdout.split()
+    if len(fields) != 2 or fields[1] != "refs/heads/main" or not SHA_RE.fullmatch(fields[0]):
+        raise ValueError("could not determine the current main commit")
+    return fields[0]
+
+
+def validate_source(
+    *, workflow: str, event: str, conclusion: str, branch: str, run_id: str, head_sha: str,
+    workflow_path: str, repository: str, stage: str, current_main: str,
+) -> None:
+    expected = {
+        "release": ("CI", "ci.yaml@refs/heads/main", "push"),
+        "handoff": ("Release production images", "release-images.yaml@refs/heads/main", "workflow_run"),
+    }
+    if stage not in expected:
+        raise ValueError("unknown release handoff stage")
+    expected_workflow, expected_path, expected_event = expected[stage]
+    if workflow != expected_workflow or workflow_path != expected_path or event != expected_event:
+        raise ValueError("source workflow or event is not approved for this stage")
+    if repository != "admin/akyldash":
+        raise ValueError("source repository is not admin/akyldash")
+    if conclusion != "success" or branch != "main":
+        raise ValueError("only successful source runs on main may continue")
+    if not RUN_ID_RE.fullmatch(run_id) or not SHA_RE.fullmatch(head_sha):
+        raise ValueError("source run ID or commit SHA is invalid")
+    if current_main != head_sha:
+        raise ValueError("source run is stale because main has advanced")
+
+
+def descriptor_request(artifact_response: object, *, run_id: str, head_sha: str) -> dict[str, str]:
+    if not isinstance(artifact_response, dict):
+        raise ValueError("artifact metadata must be a JSON object")
+    artifacts = artifact_response.get("artifacts")
+    if not isinstance(artifacts, list) or len(artifacts) != 1:
+        raise ValueError("expected exactly one release descriptor artifact")
+    artifact = artifacts[0]
+    if not isinstance(artifact, dict):
+        raise ValueError("release artifact metadata is invalid")
+    name = artifact.get("name")
+    match = DESCRIPTOR_RE.fullmatch(name) if isinstance(name, str) else None
+    if not match or match.group(1) != run_id:
+        raise ValueError("release artifact name does not bind the source run and descriptor digest")
+    if artifact.get("expired") is True:
+        raise ValueError("release descriptor artifact has expired")
+    source = artifact.get("workflow_run")
+    if not isinstance(source, dict) or (
+        str(source.get("id")) != run_id
+        or source.get("head_sha") != head_sha
+        or source.get("head_branch") != "main"
+        or source.get("event") != "workflow_run"
+        or source.get("conclusion") != "success"
+    ):
+        raise ValueError("artifact metadata does not match the successful source release run")
+    return {"run_id": run_id, "commit": head_sha, "descriptor_sha256": match.group(2)}
+
+
+def _source_from_environment() -> dict[str, str]:
+    return {
+        "workflow": os.environ.get("SOURCE_WORKFLOW", ""),
+        "workflow_path": os.environ.get("SOURCE_WORKFLOW_PATH", ""),
+        "event": os.environ.get("SOURCE_EVENT", ""),
+        "conclusion": os.environ.get("SOURCE_CONCLUSION", ""),
+        "branch": os.environ.get("SOURCE_BRANCH", ""),
+        "run_id": os.environ.get("SOURCE_RUN_ID", ""),
+        "head_sha": os.environ.get("SOURCE_SHA", ""),
+        "repository": os.environ.get("SOURCE_REPOSITORY", ""),
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("stage", choices=("validate-ci-source", "validate-handoff-source", "dry-run"))
+    parser.add_argument("--artifact-metadata", type=Path)
+    args = parser.parse_args()
+    try:
+        source = _source_from_environment()
+        stage = "release" if args.stage == "validate-ci-source" else "handoff"
+        validate_source(**source, stage=stage, current_main=latest_main_sha())
+        if args.stage == "validate-ci-source":
+            print(f"PASS successful CI source {source['head_sha']} is current main")
+            return 0
+        if args.artifact_metadata is None:
+            print(
+                "DRY-RUN only: source release is current, but artifact metadata was not read; "
+                "host handoff is unavailable"
+            )
+            return 0
+        response = json.loads(args.artifact_metadata.read_text(encoding="utf-8"))
+        request = descriptor_request(response, run_id=source["run_id"], head_sha=source["head_sha"])
+    except (OSError, UnicodeError, json.JSONDecodeError, subprocess.CalledProcessError, ValueError) as error:
+        print(f"ERROR: {error}", file=sys.stderr)
+        return 1
+    print(
+        "DRY-RUN only: validated handoff tuple "
+        f"run_id={request['run_id']} commit={request['commit']} "
+        f"descriptor_sha256={request['descriptor_sha256']}; ZIP bytes were not fetched and no host connection was opened"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

infra/deploy/release_refs.py

@@ -0,0 +1,79 @@
+"""Read and atomically replace the two application image references."""
+
+from __future__ import annotations
+
+import os
+import re
+import tempfile
+from pathlib import Path
+
+KEYS = {"BACKEND_IMAGE", "OPENSEARCH_IMAGE"}
+IMAGE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:/-]*(?:@sha256:[0-9a-f]{64})?\Z")
+
+
+def read_images(path: Path) -> tuple[str, dict[str, str]]:
+    if path.is_symlink() or not path.is_file():
+        raise ValueError("production env must be a regular non-symlink file")
+    text = path.read_text(encoding="utf-8")
+    values: dict[str, str] = {}
+    lines = text.splitlines(keepends=True)
+    for line in lines:
+        if not re.match(r"^\s*(?:export\s+)?(?:BACKEND_IMAGE|OPENSEARCH_IMAGE)\b", line):
+            continue
+        match = re.fullmatch(r"(BACKEND_IMAGE|OPENSEARCH_IMAGE)=([^\r\n]+)(\r?\n)?", line)
+        if not match:
+            raise ValueError("application image assignments must use plain KEY=value syntax")
+        key, value = match.group(1), match.group(2)
+        if key in values or not IMAGE.fullmatch(value):
+            raise ValueError(f"invalid or duplicate {key} in production env")
+        values[key] = value
+    if set(values) != KEYS:
+        raise ValueError("production env must define exactly one backend and OpenSearch image")
+    return text, values
+
+
+def replace_images(
+    path: Path,
+    expected: dict[str, str],
+    replacement: dict[str, str],
+    *,
+    require_root: bool = True,
+) -> None:
+    if set(expected) != KEYS or set(replacement) != KEYS:
+        raise ValueError("both complete application image references are required")
+    if any(not isinstance(value, str) or not IMAGE.fullmatch(value) for value in (*expected.values(), *replacement.values())):
+        raise ValueError("invalid application image reference")
+    text, current = read_images(path)
+    info = path.stat()
+    if require_root and (os.geteuid() != 0 or info.st_uid != 0 or info.st_mode & 0o777 != 0o600):
+        raise ValueError("production env must be root-owned mode 0600 before a release switch")
+    if current != expected:
+        raise ValueError("production image references changed; refusing partial or stale release switch")
+    lines = text.splitlines(keepends=True)
+    updated = []
+    for line in lines:
+        if not re.match(r"^\s*(?:export\s+)?(?:BACKEND_IMAGE|OPENSEARCH_IMAGE)\b", line):
+            updated.append(line)
+            continue
+        match = re.fullmatch(r"(BACKEND_IMAGE|OPENSEARCH_IMAGE)=([^\r\n]+)(\r?\n)?", line)
+        if match:
+            newline = match.group(3) or ""
+            updated.append(f"{match.group(1)}={replacement[match.group(1)]}{newline}")
+        else:
+            raise ValueError("application image assignments must use plain KEY=value syntax")
+    target = path.parent
+    with tempfile.NamedTemporaryFile("w", encoding="utf-8", dir=target, prefix=f".{path.name}.", delete=False) as stream:
+        temporary = Path(stream.name)
+        stream.write("".join(updated))
+        stream.flush()
+        os.fsync(stream.fileno())
+    try:
+        os.chmod(temporary, path.stat().st_mode & 0o777)
+        os.replace(temporary, path)
+        directory_fd = os.open(target, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
+        try:
+            os.fsync(directory_fd)
+        finally:
+            os.close(directory_fd)
+    finally:
+        temporary.unlink(missing_ok=True)

infra/deploy/release_source.py

@@ -0,0 +1,256 @@
+"""Verify a Gitea release and its exact uploaded descriptor through gitea-api."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import resource
+import signal
+import stat
+import subprocess
+import tempfile
+import zipfile
+from pathlib import Path, PurePosixPath
+from urllib.parse import urlencode
+
+from release_handoff import descriptor_request, latest_main_sha, validate_source
+from validate_release import read_json, unique_object, validate_manifest
+
+REPOSITORY = "admin/akyldash"
+RELEASE_WORKFLOW = ".gitea/workflows/release-images.yaml"
+CI_WORKFLOW = ".gitea/workflows/ci.yaml"
+MAX_DESCRIPTOR_BYTES = 1024 * 1024
+MAX_API_RESPONSE_BYTES = 1024 * 1024
+MAX_API_DOWNLOAD_BYTES = 10 * 1024 * 1024
+MAX_CANDIDATE_RELEASE_RUNS = 10
+API_TIMEOUT_SECONDS = 15
+
+
+def run_api_helper(command: list[str], *, env: dict | None, timeout: int,
+                   max_stdout_bytes: int, max_file_bytes: int) -> bytes:
+    def limit_files() -> None:
+        _soft, hard = resource.getrlimit(resource.RLIMIT_FSIZE)
+        limit = max_file_bytes + 1 if hard == resource.RLIM_INFINITY else min(max_file_bytes + 1, hard)
+        resource.setrlimit(resource.RLIMIT_FSIZE, (limit, hard))
+
+    with tempfile.TemporaryFile() as output:
+        process = subprocess.Popen(
+            command, stdout=output, stderr=subprocess.DEVNULL, env=env,
+            start_new_session=True, preexec_fn=limit_files,
+        )
+        try:
+            return_code = process.wait(timeout=timeout)
+        except subprocess.TimeoutExpired as error:
+            try:
+                os.killpg(process.pid, signal.SIGTERM)
+            except ProcessLookupError:
+                pass
+            try:
+                process.wait(timeout=2)
+            except subprocess.TimeoutExpired:
+                pass
+            try:
+                os.killpg(process.pid, signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+            process.wait()
+            raise ValueError("Gitea helper request timed out") from error
+        if return_code:
+            raise ValueError("Gitea helper request failed")
+        output.seek(0, os.SEEK_END)
+        if output.tell() > max_stdout_bytes:
+            raise ValueError("Gitea helper response exceeds its size limit")
+        output.seek(0)
+        return output.read(max_stdout_bytes + 1)
+
+
+def api_json(path: str, *, helper: str = "gitea-api", env: dict | None = None) -> dict:
+    try:
+        response = run_api_helper(
+            [helper, "GET", path], env=env, timeout=API_TIMEOUT_SECONDS,
+            max_stdout_bytes=MAX_API_RESPONSE_BYTES, max_file_bytes=MAX_API_RESPONSE_BYTES,
+        )
+    except (OSError, subprocess.SubprocessError) as error:
+        raise ValueError("Gitea API request failed") from error
+    if len(response) > MAX_API_RESPONSE_BYTES:
+        raise ValueError("Gitea helper response exceeds its size limit")
+    try:
+        value = json.loads(response.decode("utf-8"), object_pairs_hook=unique_object)
+    except (UnicodeError, json.JSONDecodeError) as error:
+        raise ValueError("Gitea API response is invalid JSON") from error
+    if not isinstance(value, dict):
+        raise ValueError("Gitea API returned a non-object response")
+    return value
+
+
+def latest_release_request(*, current_main: str, api=api_json,
+                           checkout: Path | None = None) -> dict | None:
+    if not re.fullmatch(r"[0-9a-f]{40}", current_main):
+        raise ValueError("current main commit is invalid")
+    query = urlencode({
+        "event": "workflow_run", "branch": "main", "status": "success",
+        "head_sha": current_main, "page": 1, "limit": MAX_CANDIDATE_RELEASE_RUNS,
+    })
+    runs_response = api(
+        f"/repos/{REPOSITORY}/actions/workflows/{Path(RELEASE_WORKFLOW).name}/runs?{query}"
+    )
+    runs = runs_response.get("workflow_runs")
+    total = runs_response.get("total_count")
+    if type(total) is not int or total < 0 or not isinstance(runs, list):
+        raise ValueError("Gitea release-run listing is invalid")
+    if total > MAX_CANDIDATE_RELEASE_RUNS or len(runs) != total:
+        raise ValueError("Gitea release-run listing is incomplete")
+    if not runs:
+        return None
+    run_ids = []
+    for run in runs:
+        if not isinstance(run, dict):
+            raise ValueError("Gitea release-run listing contains an invalid entry")
+        run_id = run.get("id")
+        if (isinstance(run_id, bool) or not isinstance(run_id, (int, str))
+                or not str(run_id).isdigit() or len(str(run_id)) > 20):
+            raise ValueError("Gitea release-run listing contains an invalid run ID")
+        head_sha = run.get("head_sha")
+        if head_sha is not None and head_sha != current_main:
+            raise ValueError("Gitea release-run listing does not match current main")
+        run_ids.append(str(run_id))
+    run_id = max(run_ids, key=int)
+    verify_run(run_id, stage="handoff", commit=current_main, api=api,
+               current_main=current_main, checkout=checkout)
+    metadata = api(f"/repos/{REPOSITORY}/actions/runs/{run_id}/artifacts")
+    return descriptor_request(metadata, run_id=run_id, head_sha=current_main)
+
+
+def ensure_private_scratch(path: Path) -> None:
+    path.mkdir(mode=0o700, parents=True, exist_ok=True)
+    if path.is_symlink() or path.stat().st_uid != 0 or path.stat().st_mode & 0o077:
+        raise ValueError("artifact scratch directory must be a private root-owned directory")
+
+
+def verify_run(run_id: str, *, stage: str, commit: str, api=api_json, current_main: str | None = None,
+               checkout: Path | None = None) -> dict:
+    if not run_id.isdigit() or not re.fullmatch(r"[0-9a-f]{40}", commit):
+        raise ValueError("Gitea run identity is invalid")
+    run = api(f"/repos/{REPOSITORY}/actions/runs/{run_id}")
+    if not isinstance(run, dict) or str(run.get("id")) != run_id:
+        raise ValueError("Gitea returned a different workflow run")
+    if run.get("status") not in {"completed", "success"} or run.get("conclusion") != "success":
+        raise ValueError("workflow run is not successful")
+    workflow_id = run.get("workflow_id")
+    if not isinstance(workflow_id, (int, str)) or not str(workflow_id):
+        raise ValueError("workflow run has no workflow identity")
+    workflow = api(f"/repos/{REPOSITORY}/actions/workflows/{workflow_id}")
+    expected_workflow, path, event = (
+        ("CI", CI_WORKFLOW, "push") if stage == "ci" else
+        ("Release production images", RELEASE_WORKFLOW, "workflow_run")
+    )
+    if (workflow.get("name") != expected_workflow or workflow.get("path") != path
+            or str(workflow.get("id")) != str(workflow_id)):
+        raise ValueError("workflow ID does not resolve to the approved workflow name and path")
+    if run.get("name") not in {None, expected_workflow}:
+        raise ValueError("workflow run name is not approved")
+    if run.get("head_sha") != commit:
+        raise ValueError("workflow run commit does not match the release request")
+    branch = run.get("head_branch")
+    if branch != "main" or run.get("event") != event:
+        raise ValueError("workflow run is not the approved main event")
+    validate_source(
+        workflow=expected_workflow, workflow_path=f"{Path(path).name}@refs/heads/main", event=event,
+        conclusion="success", branch=branch, run_id=run_id, head_sha=commit,
+        repository=REPOSITORY, stage="release" if stage == "ci" else "handoff",
+        current_main=current_main or latest_main_sha(checkout),
+    )
+    return run
+
+
+def validate_artifact_zip(path: Path, *, descriptor_sha256: str, release_run_id: str,
+                          ci_run_id: str | None, commit: str, policy: object) -> tuple[dict, bytes]:
+    if not re.fullmatch(r"[0-9a-f]{64}", descriptor_sha256):
+        raise ValueError("requested descriptor digest is invalid")
+    try:
+        with zipfile.ZipFile(path) as archive:
+            members = archive.infolist()
+            names = [member.filename for member in members]
+            expected = {"release-manifest.json", "release-manifest.json.sha256"}
+            if len(names) != 2 or set(names) != expected:
+                raise ValueError("release artifact must contain exactly the manifest and checksum files")
+            payloads = {}
+            for member in members:
+                name = PurePosixPath(member.filename)
+                mode = member.external_attr >> 16
+                kind = stat.S_IFMT(mode)
+                if (member.is_dir() or name.is_absolute() or len(name.parts) != 1
+                        or name.as_posix() != member.filename
+                        or kind not in {0, stat.S_IFREG}
+                        or member.file_size > MAX_DESCRIPTOR_BYTES
+                        or member.compress_size > MAX_DESCRIPTOR_BYTES):
+                    raise ValueError("release artifact contains an unsafe or oversized member")
+                with archive.open(member) as stream:
+                    chunks = []
+                    size = 0
+                    while chunk := stream.read(64 * 1024):
+                        size += len(chunk)
+                        if size > MAX_DESCRIPTOR_BYTES:
+                            raise ValueError("release artifact member exceeds its size limit")
+                        chunks.append(chunk)
+                    if size != member.file_size:
+                        raise ValueError("release artifact member size does not match its ZIP metadata")
+                    payloads[member.filename] = b"".join(chunks)
+    except (OSError, zipfile.BadZipFile, RuntimeError) as error:
+        raise ValueError(f"release artifact ZIP is invalid: {error}") from error
+
+    manifest_bytes = payloads["release-manifest.json"]
+    if hashlib.sha256(manifest_bytes).hexdigest() != descriptor_sha256:
+        raise ValueError("release descriptor bytes do not match the requested SHA-256")
+    checksum = payloads["release-manifest.json.sha256"]
+    expected_sidecar = f"{descriptor_sha256}  release-manifest.json\n".encode("ascii")
+    if checksum != expected_sidecar:
+        raise ValueError("release descriptor checksum sidecar is invalid")
+    try:
+        manifest = json.loads(manifest_bytes, object_pairs_hook=unique_object)
+    except (UnicodeError, json.JSONDecodeError) as error:
+        raise ValueError("release descriptor JSON is invalid") from error
+    validated = validate_manifest(manifest, policy)
+    if (validated["run_id"] != release_run_id
+            or (ci_run_id is not None and validated["source_run_id"] != ci_run_id)
+            or validated["commit"] != commit):
+        raise ValueError("release descriptor does not bind the verified CI and release runs")
+    return validated, manifest_bytes
+
+
+def fetch_release(request: dict, *, policy: object, helper: str = "gitea-api",
+                  temp_dir: Path = Path("/run/akyldash"), env: dict | None = None,
+                  api=api_json, current_main: str | None = None,
+                  checkout: Path | None = None) -> tuple[dict, bytes]:
+    run_id, commit, descriptor_sha256 = (
+        request["run_id"], request["commit"], request["descriptor_sha256"]
+    )
+    current_main = current_main or latest_main_sha(checkout)
+    release_run = verify_run(run_id, stage="handoff", commit=commit, api=api,
+                             current_main=current_main, checkout=checkout)
+    metadata = api(f"/repos/{REPOSITORY}/actions/runs/{run_id}/artifacts")
+    tuple_data = descriptor_request(metadata, run_id=run_id, head_sha=commit)
+    if tuple_data["descriptor_sha256"] != descriptor_sha256:
+        raise ValueError("requested descriptor digest does not match the Gitea run artifact")
+    artifact = metadata["artifacts"][0]
+    artifact_id = artifact.get("id")
+    if not isinstance(artifact_id, (int, str)) or not str(artifact_id).isdigit():
+        raise ValueError("release descriptor artifact has no numeric ID")
+    ensure_private_scratch(temp_dir)
+    from tempfile import TemporaryDirectory
+    with TemporaryDirectory(prefix="akyldash-release-", dir=temp_dir) as scratch:
+        zip_path = Path(scratch) / "artifact.zip"
+        run_api_helper(
+            [helper, "DOWNLOAD", f"/repos/{REPOSITORY}/actions/artifacts/{artifact_id}/zip", str(zip_path)],
+            env=env, timeout=30, max_stdout_bytes=4096, max_file_bytes=MAX_API_DOWNLOAD_BYTES,
+        )
+        manifest, manifest_bytes = validate_artifact_zip(
+            zip_path, descriptor_sha256=tuple_data["descriptor_sha256"], release_run_id=run_id,
+            ci_run_id=None, commit=commit, policy=policy,
+        )
+        source_run_id = manifest["source_run_id"]
+        verify_run(source_run_id, stage="ci", commit=commit, api=api, current_main=current_main,
+                   checkout=checkout)
+        return manifest, manifest_bytes

infra/deploy/release_state.py

@@ -0,0 +1,109 @@
+"""Atomic, secret-free release state and recovery journal helpers."""
+
+from __future__ import annotations
+
+import json
+import hashlib
+import os
+import re
+import tempfile
+from pathlib import Path
+
+SERVICES = {"backend", "opensearch"}
+
+
+def unique_object(pairs: list[tuple[str, object]]) -> dict:
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError(f"duplicate release state field: {key}")
+        result[key] = value
+    return result
+
+
+def validate_images(value: object, label: str) -> dict[str, dict[str, str]]:
+    if not isinstance(value, dict) or set(value) != SERVICES:
+        raise ValueError(f"{label} must contain backend and opensearch")
+    result = {}
+    for service in sorted(SERVICES):
+        record = value[service]
+        if not isinstance(record, dict) or set(record) != {"configured", "image_id"}:
+            raise ValueError(f"{label} has an invalid {service} record")
+        configured, image_id = record["configured"], record["image_id"]
+        if (
+            not isinstance(configured, str)
+            or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._:/-]*(?:@sha256:[0-9a-f]{64})?", configured)
+            or not isinstance(image_id, str)
+            or not re.fullmatch(r"sha256:[0-9a-f]{64}", image_id)
+        ):
+            raise ValueError(f"{label} has invalid {service} values")
+        result[service] = {"configured": configured, "image_id": image_id}
+    return result
+
+
+def write_json_atomic(path: Path, value: dict, mode: int = 0o600) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile("w", encoding="utf-8", dir=path.parent, prefix=f".{path.name}.", delete=False) as stream:
+        temporary = Path(stream.name)
+        json.dump(value, stream, sort_keys=True, indent=2)
+        stream.write("\n")
+        stream.flush()
+        os.fsync(stream.fileno())
+    try:
+        os.chmod(temporary, mode)
+        os.replace(temporary, path)
+        directory_fd = os.open(path.parent, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
+        try:
+            os.fsync(directory_fd)
+        finally:
+            os.close(directory_fd)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def read_json(path: Path) -> dict:
+    if path.is_symlink() or not path.is_file():
+        raise ValueError(f"release state is not a regular file: {path}")
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"), object_pairs_hook=unique_object)
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise ValueError(f"release state is unreadable: {error}") from error
+    if not isinstance(value, dict):
+        raise ValueError("release state must be a JSON object")
+    return value
+
+
+def validate_state(state: object) -> dict:
+    old_fields = {"schema_version", "commit", "manifest_sha256", "current", "previous"}
+    new_fields = old_fields | {"previous_backup"}
+    if (not isinstance(state, dict) or type(state.get("schema_version")) is not int
+            or state.get("schema_version") not in {1, 2}
+            or set(state) != (old_fields if state.get("schema_version") == 1 else new_fields)):
+        raise ValueError("release state has unsupported schema")
+    if not isinstance(state["commit"], str) or not re.fullmatch(r"[0-9a-f]{40}|rollback", state["commit"]):
+        raise ValueError("release state commit is invalid")
+    if not isinstance(state["manifest_sha256"], str) or not re.fullmatch(r"[0-9a-f]{64}|rollback", state["manifest_sha256"]):
+        raise ValueError("release state provenance is invalid")
+    state["current"] = validate_images(state["current"], "current images")
+    state["previous"] = validate_images(state["previous"], "previous images")
+    if state["schema_version"] == 2:
+        state["previous_backup"] = validate_backup_identity(state["previous_backup"])
+    return state
+
+
+def validate_backup_identity(value: object) -> dict | None:
+    if value is None:
+        return None
+    required = {"backup_id", "size", "archive_sha256", "manifest_sha256", "manifest"}
+    if not isinstance(value, dict) or set(value) != required:
+        raise ValueError("external backup identity has an unsupported shape")
+    if (not isinstance(value["backup_id"], str) or not re.fullmatch(r"akyldash-[0-9]{8}T[0-9]{6}Z-[0-9a-f]{8}", value["backup_id"])
+            or type(value["size"]) is not int or not 0 < value["size"] <= 100 * 1024**3
+            or not isinstance(value["archive_sha256"], str) or not re.fullmatch(r"[0-9a-f]{64}", value["archive_sha256"])
+            or not isinstance(value["manifest_sha256"], str) or not re.fullmatch(r"[0-9a-f]{64}", value["manifest_sha256"])
+            or not isinstance(value["manifest"], dict)):
+        raise ValueError("external backup identity has invalid values")
+    canonical = json.dumps(value["manifest"], sort_keys=True, separators=(",", ":")).encode("utf-8")
+    if hashlib.sha256(canonical).hexdigest() != value["manifest_sha256"]:
+        raise ValueError("external backup manifest identity is inconsistent")
+    return value

infra/deploy/rollback.py

@@ -3,9 +3,7 @@
 
 from __future__ import annotations
 
-import argparse
-import datetime as dt
-import json
+import hashlib
 import os
 import re
 import subprocess
@@ -16,8 +14,9 @@ from pathlib import Path
 ROOT = Path("/opt/akyldash/current")
 COMPOSE_FILE = ROOT / "deploy/production/compose.yaml"
 ENV_FILE = Path("/etc/akyldash/production.env")
-BACKUP_DIR = Path("/var/backups/akyldash")
-BACKUP_TOOL = Path("/usr/local/lib/akyldash/archive.py")
+STATE_FILE = Path("/opt/akyldash/release-state.json")
+JOURNAL_FILE = Path("/opt/akyldash/release-recovery.json")
+DEPLOYED_IMAGE_FILE = Path("/opt/akyldash/deployed-image.txt")
 APP_SERVICES = {"backend", "opensearch"}
 IMAGE_TAG_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:/-]*")
 IMAGE_DIGEST_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:/-]*@sha256:[0-9a-f]{64}")
@@ -27,7 +26,11 @@ def is_digest_reference(reference: str) -> bool:
     return IMAGE_DIGEST_RE.fullmatch(reference) is not None
 
 
-def image_restore_plan(manifest: dict, configured: dict[str, str]) -> dict[str, tuple[str, str]]:
+def image_restore_plan(
+    manifest: dict,
+    configured: dict[str, str],
+    expected_previous: dict[str, dict[str, str]] | None = None,
+) -> dict[str, tuple[str, str]]:
     images = manifest.get("images")
     if not isinstance(images, dict) or not APP_SERVICES <= images.keys():
         raise ValueError("backup has no previous backend and OpenSearch images")
@@ -38,7 +41,7 @@ def image_restore_plan(manifest: dict, configured: dict[str, str]) -> dict[str,
             raise ValueError(f"invalid image record for {service}")
         reference = image.get("configured")
         image_id = image.get("image_id")
-        if reference != configured.get(service):
+        if expected_previous is None and reference != configured.get(service):
             raise ValueError(f"Compose image reference changed for {service}; refusing rollback")
         if not isinstance(reference, str) or not (
             IMAGE_TAG_RE.fullmatch(reference) or is_digest_reference(reference)
@@ -46,6 +49,10 @@ def image_restore_plan(manifest: dict, configured: dict[str, str]) -> dict[str,
             raise ValueError(f"invalid image reference for {service}")
         if not isinstance(image_id, str) or not re.fullmatch(r"sha256:[0-9a-f]{64}", image_id):
             raise ValueError(f"invalid previous image ID for {service}")
+        if expected_previous is not None and expected_previous.get(service) != {
+            "configured": reference, "image_id": image_id
+        }:
+            raise ValueError(f"backup does not match the pinned previous {service} release")
         plan[service] = (image_id, reference)
     return plan
 
@@ -77,9 +84,9 @@ def require_tag_rollback(plan: dict[str, tuple[str, str]]) -> None:
 
 
 def tag_previous_images(plan: dict[str, tuple[str, str]]) -> None:
-    require_tag_rollback(plan)
     for image_id, reference in plan.values():
-        run(["docker", "image", "tag", image_id, reference])
+        if not is_digest_reference(reference):
+            run(["docker", "image", "tag", image_id, reference])
 
 
 def run(command: list[str], *, capture: bool = False) -> str:
@@ -101,98 +108,136 @@ def record_backend_image() -> None:
     image_id = run(["docker", "inspect", "--format", "{{.Image}}", container], capture=True)
     if not re.fullmatch(r"sha256:[0-9a-f]{64}", image_id):
         raise ValueError("backend returned an invalid image ID")
-    target = Path("/opt/akyldash/deployed-image.txt")
+    target = DEPLOYED_IMAGE_FILE
     with tempfile.NamedTemporaryFile(dir=target.parent, prefix=".deployed-image-", delete=False) as stream:
         temporary = Path(stream.name)
         stream.write(f"{image_id}\n".encode("ascii"))
     os.chmod(temporary, 0o600)
     try:
         os.replace(temporary, target)
+        directory_fd = os.open(target.parent, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
+        try:
+            os.fsync(directory_fd)
+        finally:
+            os.close(directory_fd)
     finally:
         temporary.unlink(missing_ok=True)
 
 
+def running_image_ids() -> dict[str, str]:
+    result: dict[str, str] = {}
+    for service in sorted(APP_SERVICES):
+        container = compose("ps", "--all", "--quiet", service, capture=True)
+        if not container or "\n" in container:
+            raise ValueError(f"expected exactly one running {service} container")
+        inspection = run(
+            ["docker", "inspect", "--format", "{{.State.Running}}\t{{.Image}}", container], capture=True
+        )
+        running, separator, image_id = inspection.partition("\t")
+        if not separator or running != "true" or not re.fullmatch(r"sha256:[0-9a-f]{64}", image_id):
+            raise ValueError(f"{service} container is not running with a valid image ID")
+        result[service] = image_id
+    return result
+
+
+def require_running_image_ids(expected: dict[str, str], actual: dict[str, str], label: str) -> None:
+    if actual != expected:
+        raise ValueError(f"running image IDs do not match the {label}")
+
+
 def rollback(backup: Path, data_compatible: bool) -> None:
+    raise ValueError("local VPS backup paths are disabled; use the owner-controlled external rollback session")
+
+
+def rollback_external(
+    *, state: dict, target_identity: dict, current: dict, fresh_backup: dict,
+    data_compatible: bool,
+) -> None:
+    if os.geteuid() != 0:
+        raise ValueError("external rollback must run in the root-controlled receiver")
     if not data_compatible:
-        raise ValueError("confirm data compatibility with --data-compatible before rollback")
-    if not backup.is_file() or backup.is_symlink() or backup.resolve().parent != BACKUP_DIR.resolve():
-        raise ValueError(f"backup must be a regular file directly under {BACKUP_DIR}")
-    if backup.stat().st_uid != 0 or backup.stat().st_mode & 0o777 != 0o600:
-        raise ValueError("rollback backup must be root-owned mode 0600")
-    checksum = Path(f"{backup}.sha256")
-    if checksum.is_symlink() or not checksum.is_file() or checksum.stat().st_uid != 0 or checksum.stat().st_mode & 0o777 != 0o600:
-        raise ValueError("rollback checksum sidecar must be root-owned mode 0600")
+        raise ValueError("confirm data compatibility before external rollback")
+    from deploy_release import image_ids
+    from release_refs import read_images, replace_images
+    from release_state import read_json, validate_backup_identity, validate_state, write_json_atomic
 
-    sys.path.insert(0, str(BACKUP_TOOL.parent))
-    from archive import digest, verify_archive
-
-    manifest = verify_archive(backup)
-    deployment_files = {
-        relative: digest(ROOT / relative)
+    pinned = validate_state(state)
+    if pinned.get("schema_version") != 2 or pinned.get("previous_backup") is None:
+        raise ValueError("release state has no verified external previous backup")
+    target_identity = validate_backup_identity(target_identity)
+    fresh_backup = validate_backup_identity(fresh_backup)
+    if target_identity != pinned["previous_backup"]:
+        raise ValueError("rollback archive is not the root-pinned previous external backup")
+    if image_ids(allow_stopped=True) != current:
+        raise ValueError("stopped production images differ from the pre-rollback snapshot")
+    current_files = {
+        relative: hashlib.sha256((ROOT / relative).read_bytes()).hexdigest()
         for relative in ("deploy/production/compose.yaml", "deploy/production/Caddyfile")
     }
-    if deployment_files != manifest.get("deployment_files"):
-        raise ValueError("Compose or Caddyfile changed since this backup; restore the matching Git revision first")
-    rendered = json.loads(compose("config", "--format", "json", capture=True))
-    configured = {service: rendered["services"][service]["image"] for service in APP_SERVICES}
-    plan = image_restore_plan(manifest, configured)
+    if target_identity["manifest"].get("deployment_files") != current_files:
+        raise ValueError("previous backup deployment files differ from the current checkout")
+    if app_images(target_identity["manifest"], "previous external backup") != pinned["previous"]:
+        raise ValueError("previous backup image identities do not match root-pinned release state")
+    if app_images(fresh_backup["manifest"], "pre-rollback external backup") != current:
+        raise ValueError("fresh external backup does not match the current deployment")
+
+    env_text, configured_values = read_images(ENV_FILE)
+    del env_text
+    configured = {service: configured_values[f"{service.upper()}_IMAGE"] for service in APP_SERVICES}
+    plan = image_restore_plan(target_identity["manifest"], configured, pinned["previous"])
     verify_previous_images(plan)
-    require_tag_rollback(plan)
+    before = {"BACKEND_IMAGE": configured["backend"], "OPENSEARCH_IMAGE": configured["opensearch"]}
+    after = {"BACKEND_IMAGE": plan["backend"][1], "OPENSEARCH_IMAGE": plan["opensearch"][1]}
+    journal = read_json(JOURNAL_FILE)
+    if journal.get("status") != "external-backup-verified" or journal.get("backup") != fresh_backup:
+        raise ValueError("fresh external backup journal is missing or does not match this rollback")
 
-    backup_name = f"akyldash-pre-rollback-{dt.datetime.now(dt.timezone.utc):%Y%m%dT%H%M%SZ}.tar.gz"
-    backup_output = BACKUP_DIR / backup_name
-    compose("stop")
     try:
-        run(
-            [
-                "python3",
-                str(BACKUP_TOOL),
-                "create",
-                "--compose-file",
-                str(COMPOSE_FILE),
-                "--env-file",
-                str(ENV_FILE),
-                "--output",
-                str(backup_output),
-            ]
-        )
-        run(["python3", str(BACKUP_TOOL), "verify", str(backup_output)])
-    except Exception:
-        compose("up", "--detach")
-        raise
-
-    tag_previous_images(plan)
-    compose("up", "--detach", "--no-build", "--wait", "--wait-timeout", "300")
-    run(
-        [
-            "curl",
-            "--fail",
-            "--silent",
-            "--show-error",
-            "--resolve",
-            "akyldash.kg:443:127.0.0.1",
-            "https://akyldash.kg/review",
-            "--output",
-            "/dev/null",
-        ]
-    )
-    record_backend_image()
-    print(f"PASS application images restored from {backup}; pre-rollback backup: {backup_output}")
+        tag_previous_images(plan)
+        replace_images(ENV_FILE, before, after)
+        journal["status"] = "rollback-references-switched"
+        journal["rollback_from"] = target_identity
+        write_json_atomic(JOURNAL_FILE, journal)
+        compose("up", "--detach", "--no-build", "--wait", "--wait-timeout", "300")
+        expected = {service: plan[service][0] for service in APP_SERVICES}
+        require_running_image_ids(expected, running_image_ids(), "verified previous external backup")
+        run(["curl", "--fail", "--silent", "--show-error", "--resolve", "akyldash.kg:443:127.0.0.1",
+             "https://akyldash.kg/review", "--output", "/dev/null"])
+        record_backend_image()
+        restored = {
+            service: {"configured": plan[service][1], "image_id": plan[service][0]}
+            for service in APP_SERVICES
+        }
+        write_json_atomic(STATE_FILE, {
+            "schema_version": 2, "commit": "rollback", "manifest_sha256": "rollback",
+            "current": restored, "previous": current, "previous_backup": fresh_backup,
+        })
+        JOURNAL_FILE.unlink()
+    except Exception as error:
+        journal["status"] = "rollback-failed"
+        journal["error_type"] = type(error).__name__
+        try:
+            _text, current_env = read_images(ENV_FILE)
+            active = {"BACKEND_IMAGE": current_env["BACKEND_IMAGE"], "OPENSEARCH_IMAGE": current_env["OPENSEARCH_IMAGE"]}
+            if active == after:
+                replace_images(ENV_FILE, after, before)
+            elif active != before:
+                raise ValueError("image references match neither the current nor rollback release")
+            compose("up", "--detach", "--no-build", "--wait", "--wait-timeout", "300")
+            require_running_image_ids({service: current[service]["image_id"] for service in APP_SERVICES},
+                                      running_image_ids(), "pre-rollback deployment")
+            record_backend_image()
+            write_json_atomic(STATE_FILE, pinned)
+            journal["recovery"] = "pre-rollback references and image IDs restored"
+        except Exception as recovery_error:
+            journal["recovery"] = f"manual recovery required ({type(recovery_error).__name__})"
+        write_json_atomic(JOURNAL_FILE, journal)
+        raise ValueError(f"external rollback failed; recovery journal preserved at {JOURNAL_FILE}") from error
 
 
 def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("backup", type=Path)
-    parser.add_argument("--data-compatible", action="store_true")
-    args = parser.parse_args()
-    try:
-        if os.geteuid() != 0:
-            raise ValueError("rollback must run through the restricted root helper")
-        rollback(args.backup, args.data_compatible)
-    except Exception as error:
-        print(f"ERROR: {error}", file=sys.stderr)
-        return 1
-    return 0
+    print("ERROR: local VPS backup paths are disabled; use the owner-controlled external rollback session", file=sys.stderr)
+    return 1
 
 
 if __name__ == "__main__":

infra/deploy/test_deploy_release.py

@@ -0,0 +1,92 @@
+import fcntl
+import json
+import os
+import stat
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import deploy_release
+import deployment_lock
+import release_refs
+
+
+class DeploymentCutoverTests(unittest.TestCase):
+    def setUp(self):
+        self.current = {
+            "backend": {"configured": "akyldash/backend:local", "image_id": "sha256:" + "a" * 64},
+            "opensearch": {"configured": "akyldash/opensearch:local", "image_id": "sha256:" + "b" * 64},
+        }
+
+    def test_mismatched_backup_is_rejected_before_any_cutover(self):
+        changed = {**self.current, "backend": {**self.current["backend"], "image_id": "sha256:" + "c" * 64}}
+        with self.assertRaisesRegex(ValueError, "do not match"):
+            deploy_release.require_backup_matches_current(changed, self.current)
+
+    def test_search_canary_requires_nonempty_result_with_document_code(self):
+        deploy_release.validate_search_response({"results": [{"code": "DOC-1"}]}, "ru")
+        for payload in ({"results": []}, {"results": [{}]}, {"error": "unavailable"}):
+            with self.subTest(payload=payload), self.assertRaisesRegex(ValueError, "canary"):
+                deploy_release.validate_search_response(payload, "ky")
+
+    def test_shared_lock_rejects_concurrent_deployment(self):
+        with tempfile.TemporaryDirectory() as directory:
+            lock_path = Path(directory) / "deploy.lock"
+            with patch.object(deployment_lock, "LOCK_FILE", lock_path):
+                descriptor = lock_path.open("w")
+                os.chmod(lock_path, 0o600)
+                fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                try:
+                    with self.assertRaisesRegex(ValueError, "shared lock"):
+                        with deploy_release.deployment_lock():
+                            pass
+                finally:
+                    fcntl.flock(descriptor, fcntl.LOCK_UN)
+                    descriptor.close()
+
+    def test_fsync_error_after_atomic_replace_restores_previous_references(self):
+        old = {"BACKEND_IMAGE": "akyldash/backend:old", "OPENSEARCH_IMAGE": "akyldash/opensearch:old"}
+        new = {"BACKEND_IMAGE": "registry/backend@sha256:" + "c" * 64,
+               "OPENSEARCH_IMAGE": "registry/opensearch@sha256:" + "d" * 64}
+        with tempfile.TemporaryDirectory() as directory:
+            env_file = Path(directory) / "production.env"
+            env_file.write_text("BACKEND_IMAGE=akyldash/backend:old\nOPENSEARCH_IMAGE=akyldash/opensearch:old\n")
+            original_fsync = release_refs.os.fsync
+            calls = 0
+
+            def fail_first_directory_fsync(descriptor):
+                nonlocal calls
+                calls += 1
+                if calls == 2:
+                    raise OSError("simulated directory fsync failure after replace")
+                original_fsync(descriptor)
+
+            with patch.object(release_refs.os, "fsync", side_effect=fail_first_directory_fsync):
+                with self.assertRaisesRegex(OSError, "after replace"):
+                    release_refs.replace_images(env_file, old, new, require_root=False)
+                self.assertEqual(release_refs.read_images(env_file)[1], new)
+                with (
+                    patch.object(deploy_release, "ENV_FILE", env_file),
+                    patch.object(deploy_release, "replace_images", side_effect=lambda path, expected, replacement:
+                                 release_refs.replace_images(path, expected, replacement, require_root=False)),
+                ):
+                    deploy_release.restore_previous_references(old, new)
+            self.assertEqual(release_refs.read_images(env_file)[1], old)
+
+    def test_external_cutover_rejects_unvalidated_release_before_docker_operations(self):
+        with patch.object(deploy_release.os, "geteuid", return_value=0), patch.object(deploy_release, "run") as run_mock, patch.object(deploy_release, "compose") as compose_mock:
+            with self.assertRaisesRegex(ValueError, "manifest must contain exactly"):
+                deploy_release.deploy_external(
+                    {}, {"schema_version": 1, "repositories": {
+                        "backend": ["registry/backend"], "opensearch": ["registry/search"]
+                    }}, {}, {}, "0" * 64, self.current, "ру", "кыргызча"
+                )
+        run_mock.assert_not_called()
+        compose_mock.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()

infra/deploy/test_external_deploy.py

@@ -0,0 +1,78 @@
+import json
+import tempfile
+import unittest
+from contextlib import nullcontext
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "backup"))
+
+import external_deploy
+
+
+COMMIT = "a" * 40
+DESCRIPTOR = "d" * 64
+CURRENT = {
+    "backend": {"configured": "registry/backend:current", "image_id": "sha256:" + "1" * 64},
+    "opensearch": {"configured": "registry/search:current", "image_id": "sha256:" + "2" * 64},
+}
+
+
+def release_state(commit: str, descriptor: str) -> dict:
+    return {
+        "schema_version": 1, "commit": commit, "manifest_sha256": descriptor,
+        "current": CURRENT, "previous": CURRENT,
+    }
+
+
+class ExternalDeployTests(unittest.TestCase):
+    def run_execute(self, root: Path, state: dict, *, compose_mock=None):
+        compose_mock = compose_mock or Mock()
+        state_file = root / "state.json"
+        state_file.write_text("{}", encoding="utf-8")
+        journal = root / "journal.json"
+        request = {"version": 1, "action": "release", "run_id": "401",
+                   "commit": COMMIT, "descriptor_sha256": DESCRIPTOR}
+        with (
+            patch.object(external_deploy.os, "geteuid", return_value=0),
+            patch.object(external_deploy, "validate_request"),
+            patch.object(external_deploy, "POLICY_FILE", root / "policy.json"),
+            patch.object(external_deploy, "CANARIES_FILE", root / "canaries.json"),
+            patch.object(external_deploy, "JOURNAL_FILE", journal),
+            patch.object(external_deploy, "STATE_FILE", state_file),
+            patch.object(external_deploy, "fetch_release", return_value=({"commit": COMMIT}, b"")),
+            patch.object(external_deploy, "deployment_lock", return_value=nullcontext()),
+            patch.object(external_deploy, "image_ids", return_value=CURRENT),
+            patch.object(external_deploy, "deploy_release_revision", return_value=COMMIT),
+            patch.object(external_deploy, "read_json", return_value=state),
+            patch.object(external_deploy, "compose", compose_mock),
+        ):
+            result = external_deploy.execute(
+                request, reader=None, writer=None, policy={}, current_main=COMMIT, canaries=("ru", "ky")
+            )
+            return result, compose_mock, journal
+
+    def test_same_verified_release_is_rejected_before_stopping_services(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            compose = Mock()
+            with self.assertRaisesRegex(ValueError, "already applied"):
+                self.run_execute(root, release_state(COMMIT, DESCRIPTOR), compose_mock=compose)
+            self.assertFalse((root / "journal.json").exists())
+            compose.assert_not_called()
+
+    def test_pending_journal_is_durable_before_service_stop(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            compose = Mock(side_effect=KeyboardInterrupt)
+            with self.assertRaises(KeyboardInterrupt):
+                self.run_execute(root, release_state("b" * 40, "e" * 64), compose_mock=compose)
+            journal = json.loads((root / "journal.json").read_text(encoding="utf-8"))
+            self.assertEqual(journal["status"], "external-backup-pending")
+            self.assertEqual(journal["commit"], COMMIT)
+
+
+if __name__ == "__main__":
+    unittest.main()

infra/deploy/test_external_rollback.py

@@ -0,0 +1,117 @@
+import hashlib
+import io
+import json
+import sys
+import tempfile
+import unittest
+from contextlib import nullcontext
+from pathlib import Path
+from unittest.mock import patch
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "backup"))
+
+import external_rollback
+from external_session import read_challenge, write_request
+from release_state import read_json, validate_state
+
+
+class ExternalRollbackTests(unittest.TestCase):
+    def test_pending_journal_is_durable_before_rollback_service_stop(self):
+        manifest = {"git_revision": "a" * 40}
+        manifest_sha = hashlib.sha256(
+            json.dumps(manifest, sort_keys=True, separators=(",", ":")).encode()
+        ).hexdigest()
+        identity = {
+            "backup_id": "akyldash-20261031T120000Z-12345678", "size": 64,
+            "archive_sha256": "b" * 64, "manifest_sha256": manifest_sha, "manifest": manifest,
+        }
+        current = {
+            "backend": {"configured": "registry/backend:current", "image_id": "sha256:" + "1" * 64},
+            "opensearch": {"configured": "registry/search:current", "image_id": "sha256:" + "2" * 64},
+        }
+        state = {
+            "schema_version": 2, "commit": "c" * 40, "manifest_sha256": "d" * 64,
+            "current": current, "previous": current, "previous_backup": identity,
+        }
+        request = io.BytesIO()
+        write_request(request, {"version": 1, "action": "rollback", "data_compatible": True})
+        request.seek(0)
+        with tempfile.TemporaryDirectory() as directory:
+            journal = Path(directory) / "journal.json"
+            with (
+                patch.object(external_rollback.os, "geteuid", return_value=0),
+                patch.object(external_rollback, "STATE_FILE", Path(directory) / "state.json"),
+                patch.object(external_rollback, "JOURNAL_FILE", journal),
+                patch.object(external_rollback, "read_json", return_value=state),
+                patch.object(external_rollback, "deployment_lock", return_value=nullcontext()),
+                patch.object(external_rollback, "nonce", return_value="e" * 64),
+                patch.object(external_rollback, "receive_archive", return_value=(64, "b" * 64)),
+                patch.object(external_rollback, "read_ack"),
+                patch.object(external_rollback, "image_ids", return_value=current),
+                patch.object(external_rollback, "compose", side_effect=KeyboardInterrupt),
+            ):
+                with self.assertRaises(KeyboardInterrupt):
+                    external_rollback.execute(reader=request, writer=io.BytesIO())
+            self.assertEqual(read_json(journal)["status"], "external-backup-pending")
+
+    def test_release_state_rejects_boolean_schema_version(self):
+        with self.assertRaisesRegex(ValueError, "unsupported schema"):
+            validate_state({
+                "schema_version": True, "commit": "a" * 40,
+                "manifest_sha256": "b" * 64, "current": {}, "previous": {},
+            })
+
+    def test_release_state_rejects_duplicate_identity_fields(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "state.json"
+            path.write_text('{"schema_version":1,"schema_version":2}', encoding="utf-8")
+            with self.assertRaisesRegex(ValueError, "duplicate release state field"):
+                read_json(path)
+
+    def test_unpinned_archive_stream_fails_before_service_operations(self):
+        manifest = {"git_revision": "a" * 40}
+        identity = {
+            "backup_id": "akyldash-20261031T120000Z-12345678", "size": 64,
+            "archive_sha256": "b" * 64,
+            "manifest_sha256": hashlib.sha256(
+                json.dumps(manifest, sort_keys=True, separators=(",", ":")).encode()
+            ).hexdigest(),
+            "manifest": manifest,
+        }
+        state = {
+            "schema_version": 2, "commit": "c" * 40, "manifest_sha256": "d" * 64,
+            "current": {
+                "backend": {"configured": "registry/backend:current", "image_id": "sha256:" + "1" * 64},
+                "opensearch": {"configured": "registry/search:current", "image_id": "sha256:" + "2" * 64},
+            },
+            "previous": {
+                "backend": {"configured": "registry/backend:old", "image_id": "sha256:" + "3" * 64},
+                "opensearch": {"configured": "registry/search:old", "image_id": "sha256:" + "4" * 64},
+            },
+            "previous_backup": identity,
+        }
+        request = io.BytesIO()
+        write_request(request, {"version": 1, "action": "rollback", "data_compatible": True})
+        request.seek(0)
+        response = io.BytesIO()
+        with tempfile.TemporaryDirectory() as directory, \
+             patch.object(external_rollback.os, "geteuid", return_value=0), \
+             patch.object(external_rollback, "STATE_FILE", Path(directory) / "state.json"), \
+             patch.object(external_rollback, "JOURNAL_FILE", Path(directory) / "journal.json"), \
+             patch.object(external_rollback, "read_json", return_value=state), \
+             patch.object(external_rollback, "deployment_lock", return_value=nullcontext()), \
+             patch.object(external_rollback, "nonce", return_value="e" * 64), \
+             patch.object(external_rollback, "receive_archive", return_value=(64, "f" * 64)), \
+             patch.object(external_rollback, "image_ids") as image_ids, \
+             patch.object(external_rollback, "compose") as compose:
+            with self.assertRaisesRegex(ValueError, "root-pinned"):
+                external_rollback.execute(reader=request, writer=response)
+        response.seek(0)
+        challenge = read_challenge(response)
+        self.assertEqual(challenge["backup_id"], identity["backup_id"])
+        image_ids.assert_not_called()
+        compose.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()

infra/deploy/test_external_status.py

@@ -0,0 +1,81 @@
+import json
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import ANY, patch
+
+import external_status
+
+
+class ExternalStatusTests(unittest.TestCase):
+    def test_status_is_candidate_only_after_release_descriptor_verification(self):
+        commit = "a" * 40
+        request = {"run_id": "302", "commit": commit, "descriptor_sha256": "b" * 64}
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            journal = root / "recovery.json"
+            policy = root / "policy.json"
+            state = root / "state.json"
+            policy.write_text("{}", encoding="utf-8")
+            with patch.object(external_status.os, "geteuid", return_value=0), \
+                 patch.object(external_status, "latest_main_sha", return_value=commit), \
+                 patch.object(external_status, "latest_release_request", return_value=request) as select, \
+                 patch.object(external_status, "fetch_release", return_value=({"commit": commit, "run_id": "302"}, b"descriptor")) as verify:
+                value = external_status.status_document(
+                    api=lambda _path: {}, checkout=root, journal=journal, policy_file=policy,
+                    state_file=state, main_lookup=lambda _path: commit,
+                    checkout_lookup=lambda _path: commit,
+                )
+        self.assertEqual(value["state"], "candidate")
+        self.assertEqual(value["release"], request)
+        select.assert_called_once_with(current_main=commit, checkout=root, api=ANY)
+        verify.assert_called_once()
+
+    def test_status_suppresses_an_exactly_applied_release(self):
+        commit = "a" * 40
+        request = {"run_id": "302", "commit": commit, "descriptor_sha256": "b" * 64}
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            journal, policy, state = root / "journal", root / "policy.json", root / "state.json"
+            policy.write_text("{}", encoding="utf-8")
+            images = {name: {"configured": f"registry.test/{name}@sha256:{'c' * 64}",
+                             "image_id": "sha256:" + "d" * 64}
+                      for name in ("backend", "opensearch")}
+            state.write_text(json.dumps({
+                "schema_version": 1, "commit": commit, "manifest_sha256": request["descriptor_sha256"],
+                "current": images, "previous": images,
+            }), encoding="utf-8")
+            with patch.object(external_status.os, "geteuid", return_value=0), \
+                 patch.object(external_status, "latest_release_request", return_value=request), \
+                 patch.object(external_status, "fetch_release") as verify:
+                result = external_status.status_document(
+                    api=lambda _path: {}, checkout=root, journal=journal, policy_file=policy,
+                    state_file=state, main_lookup=lambda _path: commit,
+                    checkout_lookup=lambda _path: commit,
+                )
+        self.assertEqual(result["reason"], "already_applied")
+        verify.assert_not_called()
+
+    def test_status_fails_closed_for_root_guard_recovery_and_stale_checkout(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            journal = root / "recovery.json"
+            policy = root / "policy.json"
+            policy.write_text("{}", encoding="utf-8")
+            with patch.object(external_status.os, "geteuid", return_value=1000):
+                with self.assertRaisesRegex(ValueError, "must run as root"):
+                    external_status.status_document(checkout=root, journal=journal, policy_file=policy)
+            with patch.object(external_status.os, "geteuid", return_value=0):
+                journal.touch()
+                value = external_status.status_document(checkout=root, journal=journal, policy_file=policy)
+                self.assertEqual(value["reason"], "recovery_journal")
+                journal.unlink()
+                value = external_status.status_document(
+                    checkout=root, journal=journal, policy_file=policy,
+                    main_lookup=lambda _path: "a" * 40, checkout_lookup=lambda _path: "c" * 40,
+                )
+                self.assertEqual(value["reason"], "host_checkout_stale")
+
+
+if __name__ == "__main__":
+    unittest.main()

infra/deploy/test_gitea_api_binary.py

@@ -0,0 +1,155 @@
+import hashlib
+import os
+import shutil
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+FIXTURE = ROOT / "infra/deploy/gitea-api-base.fixture"
+PATCH = ROOT / "infra/deploy/gitea-api-binary-download.patch"
+FIXTURE_SHA256 = "8227332d28e27bcce9b4e3801f6b8d4323636174a82c93a0177970f560629df0"
+
+
+FAKE_CURL = r'''#!/usr/bin/env python3
+import os
+import sys
+from pathlib import Path
+
+args = sys.argv[1:]
+config = sys.stdin.read() if "--config" in args else ""
+def value(flag, default=None):
+    return args[args.index(flag) + 1] if flag in args else default
+
+url = args[-1]
+mode = os.environ["FAKE_CURL_MODE"]
+log = Path(os.environ["FAKE_CURL_LOG"])
+log.write_text(log.read_text() + url + "\n" if log.exists() else url + "\n")
+headers = value("-D")
+output = value("-o")
+has_token = "Authorization: token fixture-secret" in config or any(arg == "Authorization: token fixture-secret" for arg in args)
+if any("fixture-secret" in arg for arg in args):
+    Path(os.environ["FAKE_TOKEN_ARGS"]).write_text("leaked")
+if "gitea.test" in url and has_token:
+    Path(os.environ["FAKE_GITEA_AUTH"]).write_text("True")
+if "blob.test" in url or not value("-w"):
+    if "blob.test" in url:
+        Path(os.environ["FAKE_BLOB_AUTH"]).write_text(str(has_token))
+    body = b"zip-fixture-bytes"
+    if mode == "oversize":
+        body = b"x" * (10 * 1024 * 1024 + 10)
+    try:
+        if output and output != "-":
+            Path(output).write_bytes(body)
+        else:
+            sys.stdout.buffer.write(body)
+            sys.stdout.buffer.flush()
+    except BrokenPipeError:
+        raise SystemExit(23)
+    if value("-w"):
+        print("200", end="")
+    raise SystemExit(0)
+
+if value("-w"):
+    code = "302" if mode in {"redirect", "unlisted", "oversize"} else "200"
+    if headers:
+        location = "https://blob.test/archive.zip" if mode != "unlisted" else "https://evil.test/archive.zip"
+        Path(headers).write_text(f"HTTP/1.1 {code} Fixture\r\nLocation: {location}\r\n\r\n")
+    print(code, end="")
+    raise SystemExit(0)
+
+raise SystemExit(99)
+'''
+
+
+class GiteaApiBinaryDownloadTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.root = Path(self.temp.name)
+        self.bin = self.root / "bin"
+        self.bin.mkdir()
+        self.helper = self.root / "gitea-api"
+        shutil.copyfile(FIXTURE, self.helper)
+        self.helper.chmod(0o700)
+        applied = subprocess.run(
+            ["patch", "-p1", "-i", str(PATCH)], cwd=self.root,
+            text=True, capture_output=True,
+        )
+        if applied.returncode:
+            self.fail(applied.stderr or applied.stdout)
+        self.curl = self.bin / "curl"
+        self.curl.write_text(FAKE_CURL, encoding="utf-8")
+        self.curl.chmod(0o700)
+        self.log = self.root / "calls"
+        self.auth = self.root / "blob-auth"
+        self.gitea_auth = self.root / "gitea-auth"
+        self.token_args = self.root / "token-args"
+
+    def tearDown(self):
+        self.temp.cleanup()
+
+    def run_download(self, mode, output, origins="https://blob.test"):
+        env = {
+            **os.environ,
+            "PATH": f"{self.bin}:{os.environ['PATH']}",
+            "GITEA_URL": "https://gitea.test",
+            "GITEA_TOKEN": "fixture-secret",
+            "GITEA_DOWNLOAD_ORIGINS": origins,
+            "FAKE_CURL_MODE": mode,
+            "FAKE_CURL_LOG": str(self.log),
+            "FAKE_BLOB_AUTH": str(self.auth),
+            "FAKE_GITEA_AUTH": str(self.gitea_auth),
+            "FAKE_TOKEN_ARGS": str(self.token_args),
+        }
+        return subprocess.run(
+            [str(self.helper), "DOWNLOAD", "/repos/admin/akyldash/actions/artifacts/7/zip", str(output)],
+            env=env, text=True, capture_output=True,
+        )
+
+    def test_fixture_is_exact_audited_helper_and_patch_applies(self):
+        self.assertEqual(hashlib.sha256(FIXTURE.read_bytes()).hexdigest(), FIXTURE_SHA256)
+
+    def test_downloads_allowlisted_https_redirect_without_forwarding_token(self):
+        output = self.root / "artifact.zip"
+        result = self.run_download("redirect", output)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(output.read_bytes(), b"zip-fixture-bytes")
+        self.assertEqual(output.stat().st_mode & 0o777, 0o600)
+        self.assertEqual(self.auth.read_text(), "False")
+        self.assertTrue(self.gitea_auth.exists())
+        self.assertFalse(self.token_args.exists())
+
+    def test_downloads_direct_https_response_from_gitea(self):
+        output = self.root / "artifact.zip"
+        result = self.run_download("direct", output)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(output.read_bytes(), b"zip-fixture-bytes")
+        self.assertTrue(self.gitea_auth.exists())
+        self.assertFalse(self.token_args.exists())
+
+    def test_refuses_unlisted_redirect_before_fetching_target(self):
+        output = self.root / "artifact.zip"
+        result = self.run_download("unlisted", output)
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("not allowlisted", result.stderr)
+        self.assertFalse(output.exists())
+        self.assertNotIn("evil.test", self.log.read_text())
+
+    def test_caps_chunked_response_and_does_not_publish_partial_file(self):
+        output = self.root / "artifact.zip"
+        result = self.run_download("oversize", output)
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("10 MiB", result.stderr)
+        self.assertFalse(output.exists())
+
+    def test_refuses_to_overwrite_existing_output(self):
+        output = self.root / "artifact.zip"
+        output.write_bytes(b"keep")
+        result = self.run_download("redirect", output)
+        self.assertNotEqual(result.returncode, 0)
+        self.assertEqual(output.read_bytes(), b"keep")
+
+
+if __name__ == "__main__":
+    unittest.main()

infra/deploy/test_release_manifest.py

@@ -6,25 +6,32 @@ import tempfile
 import unittest
 from pathlib import Path
 
+from create_release_manifest import create
 from validate_release import validate_manifest
 
 ROOT = Path(__file__).resolve().parents[2]
 REPOSITORIES = {
-    "backend": ["registry.invalid/akyldash/backend"],
-    "opensearch": ["registry.invalid/akyldash/opensearch"],
+    "backend": ["git.vakanaut.ru/admin/akyldash/backend"],
+    "opensearch": ["git.vakanaut.ru/admin/akyldash/opensearch"],
 }
+BUILDER = {"name": "Kaniko", "image": "ghcr.io/osscontainertools/kaniko:v1.28.5-debug@sha256:c73ca67a3b494bce79a8fb6090c4f73c18997ab272d80bffc460a62343aeb412"}
 
 
 class ReleaseManifestTests(unittest.TestCase):
     def setUp(self):
         self.policy = {"schema_version": 1, "repositories": REPOSITORIES}
         self.manifest = {
-            "schema_version": 1,
+            "schema_version": 4,
             "source_ref": "refs/heads/main",
+            "repository": "admin/akyldash",
             "commit": "a" * 40,
+            "workflow": ".gitea/workflows/release-images.yaml",
+            "run_id": "49",
+            "source_run_id": "48",
+            "builder": BUILDER,
             "images": {
-                "backend": "registry.invalid/akyldash/backend@sha256:" + "b" * 64,
-                "opensearch": "registry.invalid/akyldash/opensearch@sha256:" + "c" * 64,
+                "backend": "git.vakanaut.ru/admin/akyldash/backend@sha256:" + "b" * 64,
+                "opensearch": "git.vakanaut.ru/admin/akyldash/opensearch@sha256:" + "c" * 64,
             },
         }
 
@@ -36,8 +43,13 @@ class ReleaseManifestTests(unittest.TestCase):
         with self.assertRaisesRegex(ValueError, "source_ref"):
             validate_manifest(self.manifest, self.policy)
 
+    def test_rejects_old_manifest_schema_with_unavailable_run_attempt(self):
+        self.manifest["schema_version"] = 2
+        with self.assertRaisesRegex(ValueError, "schema_version"):
+            validate_manifest(self.manifest, self.policy)
+
     def test_rejects_tag_instead_of_digest(self):
-        self.manifest["images"]["backend"] = "registry.invalid/akyldash/backend:latest"
+        self.manifest["images"]["backend"] = "git.vakanaut.ru/admin/akyldash/backend:latest"
         with self.assertRaisesRegex(ValueError, "sha256"):
             validate_manifest(self.manifest, self.policy)
 
@@ -51,8 +63,13 @@ class ReleaseManifestTests(unittest.TestCase):
         with self.assertRaisesRegex(ValueError, "commit"):
             validate_manifest(self.manifest, self.policy)
 
+    def test_rejects_manifest_from_another_repository(self):
+        self.manifest["repository"] = "admin/other"
+        with self.assertRaisesRegex(ValueError, "repository must be admin/akyldash"):
+            validate_manifest(self.manifest, self.policy)
+
     def test_rejects_repository_outside_policy(self):
-        self.manifest["images"]["backend"] = "registry.invalid/other/backend@sha256:" + "b" * 64
+        self.manifest["images"]["backend"] = "git.vakanaut.ru/other/backend@sha256:" + "b" * 64
         with self.assertRaisesRegex(ValueError, "not allowed"):
             validate_manifest(self.manifest, self.policy)
 
@@ -70,8 +87,8 @@ class ReleaseManifestTests(unittest.TestCase):
             manifest_path = Path(directory) / "manifest.json"
             policy_path = Path(directory) / "policy.json"
             manifest_path.write_text(
-                '{"schema_version":1,"source_ref":"refs/heads/main","commit":"' + "a" * 40
-                + '","images":{"backend":"first","backend":"second","opensearch":"third"}}',
+                '{"schema_version":4,"source_ref":"refs/heads/main","repository":"admin/akyldash","commit":"' + "a" * 40
+                + '","workflow":".gitea/workflows/release-images.yaml","run_id":"49","source_run_id":"48","builder":{},"images":{"backend":"first","backend":"second","opensearch":"third"}}',
                 encoding="utf-8",
             )
             policy_path.write_text(json.dumps(self.policy), encoding="utf-8")
@@ -99,8 +116,8 @@ class ReleaseManifestTests(unittest.TestCase):
 
     @unittest.skipUnless(shutil.which("docker"), "Docker CLI is unavailable")
     def test_compose_override_renders_digest_images_and_preserves_build(self):
-        backend = "registry.invalid/akyldash/backend@sha256:" + "b" * 64
-        opensearch = "registry.invalid/akyldash/opensearch@sha256:" + "c" * 64
+        backend = "git.vakanaut.ru/admin/akyldash/backend@sha256:" + "b" * 64
+        opensearch = "git.vakanaut.ru/admin/akyldash/opensearch@sha256:" + "c" * 64
         with tempfile.TemporaryDirectory() as directory:
             temp = Path(directory)
             secret = temp / "review_secret"
@@ -126,6 +143,27 @@ class ReleaseManifestTests(unittest.TestCase):
         self.assertIn("build", services["backend"])
         self.assertIn("build", services["opensearch"])
 
+    def test_creates_commit_and_builder_traceability_from_kaniko_digests(self):
+        with tempfile.TemporaryDirectory() as directory:
+            backend, opensearch = Path(directory) / "backend", Path(directory) / "opensearch"
+            backend.write_text("sha256:" + "b" * 64, encoding="ascii")
+            opensearch.write_text("sha256:" + "c" * 64, encoding="ascii")
+            result = create("admin/akyldash", "a" * 40, "48", "49", backend, opensearch)
+        self.assertEqual(validate_manifest(result, self.policy), result)
+        self.assertEqual(result["workflow"], ".gitea/workflows/release-images.yaml")
+        self.assertEqual(result["builder"], BUILDER)
+        self.assertEqual(result["run_id"], "49")
+        self.assertEqual(result["source_run_id"], "48")
+        self.assertNotIn("run_attempt", result)
+
+    def test_manifest_creation_rejects_missing_digest(self):
+        with tempfile.TemporaryDirectory() as directory:
+            backend, opensearch = Path(directory) / "backend", Path(directory) / "opensearch"
+            backend.write_text("", encoding="ascii")
+            opensearch.write_text("sha256:" + "c" * 64, encoding="ascii")
+            with self.assertRaisesRegex(ValueError, "invalid Kaniko digest"):
+                create("admin/akyldash", "a" * 40, "48", "49", backend, opensearch)
+
 
 if __name__ == "__main__":
     unittest.main()

infra/deploy/test_release_refs.py

@@ -0,0 +1,64 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+from release_refs import read_images, replace_images
+
+
+class ReleaseReferenceTests(unittest.TestCase):
+    def test_replaces_both_refs_as_one_expected_state_and_preserves_other_config(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "production.env"
+            path.write_text(
+                "DATA_ROOT=/srv/data\nBACKEND_IMAGE=akyldash/backend:local\n"
+                "OPENSEARCH_IMAGE=akyldash/opensearch:local\n",
+                encoding="utf-8",
+            )
+            old = {
+                "BACKEND_IMAGE": "akyldash/backend:local",
+                "OPENSEARCH_IMAGE": "akyldash/opensearch:local",
+            }
+            new = {
+                "BACKEND_IMAGE": "git.vakanaut.ru/admin/akyldash/backend@sha256:" + "a" * 64,
+                "OPENSEARCH_IMAGE": "git.vakanaut.ru/admin/akyldash/opensearch@sha256:" + "b" * 64,
+            }
+            replace_images(path, old, new, require_root=False)
+            text, actual = read_images(path)
+        self.assertEqual(actual, new)
+        self.assertTrue(text.startswith("DATA_ROOT=/srv/data\n"))
+
+    def test_stale_or_partial_reference_set_is_unchanged(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "production.env"
+            original = "BACKEND_IMAGE=old/backend:tag\nOPENSEARCH_IMAGE=old/search:tag\n"
+            path.write_text(original, encoding="utf-8")
+            with self.assertRaisesRegex(ValueError, "changed"):
+                replace_images(path, {"BACKEND_IMAGE": "stale", "OPENSEARCH_IMAGE": "old/search:tag"}, {
+                    "BACKEND_IMAGE": "new/backend:tag", "OPENSEARCH_IMAGE": "new/search:tag"
+                }, require_root=False)
+            self.assertEqual(path.read_text(encoding="utf-8"), original)
+
+    def test_duplicate_and_missing_variables_fail_closed(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "production.env"
+            path.write_text("BACKEND_IMAGE=a/b:tag\nBACKEND_IMAGE=a/b:tag\nOPENSEARCH_IMAGE=c/d:tag\n")
+            with self.assertRaisesRegex(ValueError, "duplicate"):
+                read_images(path)
+            path.write_text("BACKEND_IMAGE=a/b:tag\n")
+            with self.assertRaisesRegex(ValueError, "exactly one"):
+                read_images(path)
+
+    def test_indented_duplicate_assignment_is_not_ignored(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "production.env"
+            path.write_text(
+                "BACKEND_IMAGE=a/b:tag\n OPENSEARCH_IMAGE=attacker/search:tag\n"
+                "OPENSEARCH_IMAGE=c/d:tag\n",
+                encoding="utf-8",
+            )
+            with self.assertRaisesRegex(ValueError, "plain KEY=value"):
+                read_images(path)
+
+
+if __name__ == "__main__":
+    unittest.main()

infra/deploy/test_release_source.py

@@ -0,0 +1,276 @@
+import hashlib
+import json
+import stat
+import sys
+import tempfile
+import unittest
+from urllib.parse import parse_qs, urlsplit
+import zipfile
+from pathlib import Path
+from unittest.mock import patch
+
+import release_source
+
+POLICY = {
+    "schema_version": 1,
+    "repositories": {
+        "backend": ["registry.test/akyldash/backend"],
+        "opensearch": ["registry.test/akyldash/opensearch"],
+    },
+}
+COMMIT = "a" * 40
+RELEASE_RUN = "302"
+CI_RUN = "301"
+MANIFEST = {
+    "schema_version": 4,
+    "source_ref": "refs/heads/main",
+    "repository": "admin/akyldash",
+    "commit": COMMIT,
+    "workflow": ".gitea/workflows/release-images.yaml",
+    "run_id": RELEASE_RUN,
+    "source_run_id": CI_RUN,
+    "builder": {"name": "Kaniko", "image": "ghcr.io/osscontainertools/kaniko:v1.28.5-debug@sha256:c73ca67a3b494bce79a8fb6090c4f73c18997ab272d80bffc460a62343aeb412"},
+    "images": {
+        "backend": "registry.test/akyldash/backend@sha256:" + "b" * 64,
+        "opensearch": "registry.test/akyldash/opensearch@sha256:" + "c" * 64,
+    },
+}
+
+
+def write_artifact(path, manifest=MANIFEST, extra=()):
+    raw = json.dumps(manifest, sort_keys=True).encode()
+    digest = hashlib.sha256(raw).hexdigest()
+    with zipfile.ZipFile(path, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+        archive.writestr("release-manifest.json", raw)
+        archive.writestr("release-manifest.json.sha256", f"{digest}  release-manifest.json\n")
+        for name, payload in extra:
+            archive.writestr(name, payload)
+    return digest, raw
+
+
+class ReleaseSourceTests(unittest.TestCase):
+    def test_verify_run_binds_run_id_workflow_path_event_branch_commit_and_main(self):
+        def api(path):
+            if path.endswith("/actions/runs/301"):
+                return {"id": 301, "workflow_id": "ci.yaml", "name": "CI", "status": "completed",
+                        "conclusion": "success", "head_sha": COMMIT, "head_branch": "main", "event": "push"}
+            return {"id": "ci.yaml", "name": "CI", "path": ".gitea/workflows/ci.yaml"}
+        run = release_source.verify_run(CI_RUN, stage="ci", commit=COMMIT, api=api, current_main=COMMIT)
+        self.assertEqual(run["head_sha"], COMMIT)
+        with self.assertRaisesRegex(ValueError, "workflow run is not successful"):
+            release_source.verify_run(CI_RUN, stage="ci", commit=COMMIT,
+                                      api=lambda path: {"id": 301, "status": "failure"}, current_main=COMMIT)
+
+    def test_completed_run_requires_success_conclusion(self):
+        responses = {
+            f"/repos/admin/akyldash/actions/runs/{CI_RUN}": {
+                "id": int(CI_RUN), "workflow_id": "ci.yaml", "status": "completed",
+                "conclusion": "cancelled", "head_sha": COMMIT,
+                "head_branch": "main", "event": "push",
+            },
+        }
+        with self.assertRaisesRegex(ValueError, "workflow run is not successful"):
+            release_source.verify_run(CI_RUN, stage="ci", commit=COMMIT,
+                                      api=lambda path: responses[path], current_main=COMMIT)
+
+    def test_zip_descriptor_checks_exact_members_digest_source_ids_and_allowlist(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "artifact.zip"
+            digest, _ = write_artifact(path)
+            manifest, raw = release_source.validate_artifact_zip(
+                path, descriptor_sha256=digest, release_run_id=RELEASE_RUN,
+                ci_run_id=CI_RUN, commit=COMMIT, policy=POLICY,
+            )
+            self.assertEqual(manifest, MANIFEST)
+            self.assertEqual(hashlib.sha256(raw).hexdigest(), digest)
+            with self.assertRaisesRegex(ValueError, "requested SHA-256"):
+                release_source.validate_artifact_zip(
+                    path, descriptor_sha256="d" * 64, release_run_id=RELEASE_RUN,
+                    ci_run_id=CI_RUN, commit=COMMIT, policy=POLICY,
+                )
+            with self.assertRaisesRegex(ValueError, "does not bind"):
+                release_source.validate_artifact_zip(
+                    path, descriptor_sha256=digest, release_run_id=RELEASE_RUN,
+                    ci_run_id="999", commit=COMMIT, policy=POLICY,
+                )
+
+    def test_zip_refuses_extra_traversal_duplicate_and_symlink_members(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            extras = (
+                (("../outside", b"x"),),
+                (("release-manifest.json", b"duplicate"),),
+            )
+            for extra in extras:
+                path = root / f"bad-{len(list(root.iterdir()))}.zip"
+                digest, _ = write_artifact(path, extra=extra)
+                with self.assertRaises(ValueError):
+                    release_source.validate_artifact_zip(
+                        path, descriptor_sha256=digest, release_run_id=RELEASE_RUN,
+                        ci_run_id=CI_RUN, commit=COMMIT, policy=POLICY,
+                    )
+
+            path = root / "symlink.zip"
+            raw = json.dumps(MANIFEST, sort_keys=True).encode()
+            digest = hashlib.sha256(raw).hexdigest()
+            with zipfile.ZipFile(path, "w") as archive:
+                info = zipfile.ZipInfo("release-manifest.json")
+                info.create_system = 3
+                info.external_attr = (stat.S_IFLNK | 0o777) << 16
+                archive.writestr(info, raw)
+                archive.writestr("release-manifest.json.sha256", f"{digest}  release-manifest.json\n")
+            with self.assertRaisesRegex(ValueError, "unsafe"):
+                release_source.validate_artifact_zip(
+                    path, descriptor_sha256=digest, release_run_id=RELEASE_RUN,
+                    ci_run_id=CI_RUN, commit=COMMIT, policy=POLICY,
+                )
+
+    def test_fetch_release_rechecks_both_runs_and_uses_only_gitea_api_helper(self):
+        with tempfile.TemporaryDirectory() as fixture_dir:
+            fixture_zip = Path(fixture_dir) / "artifact.zip"
+            descriptor_sha, _ = write_artifact(fixture_zip)
+        request = {"run_id": RELEASE_RUN, "commit": COMMIT, "descriptor_sha256": descriptor_sha}
+        artifact_id = 77
+        run_responses = {
+            f"/repos/admin/akyldash/actions/runs/{RELEASE_RUN}": {
+                "id": int(RELEASE_RUN), "workflow_id": "release-images.yaml", "name": "Release production images",
+                "status": "completed", "conclusion": "success", "head_sha": COMMIT,
+                "head_branch": "main", "event": "workflow_run",
+            },
+            "/repos/admin/akyldash/actions/workflows/release-images.yaml": {
+                "id": "release-images.yaml", "name": "Release production images",
+                "path": ".gitea/workflows/release-images.yaml",
+            },
+            f"/repos/admin/akyldash/actions/runs/{CI_RUN}": {
+                "id": int(CI_RUN), "workflow_id": "ci.yaml", "name": "CI", "status": "completed",
+                "conclusion": "success", "head_sha": COMMIT, "head_branch": "main", "event": "push",
+            },
+            "/repos/admin/akyldash/actions/workflows/ci.yaml": {
+                "id": "ci.yaml", "name": "CI", "path": ".gitea/workflows/ci.yaml",
+            },
+            f"/repos/admin/akyldash/actions/runs/{RELEASE_RUN}/artifacts": {
+                "artifacts": [{
+                    "id": artifact_id, "name": f"release-descriptor-{RELEASE_RUN}-{descriptor_sha}",
+                    "expired": False,
+                    "workflow_run": {"id": int(RELEASE_RUN), "head_sha": COMMIT,
+                                     "head_branch": "main", "event": "workflow_run", "conclusion": "success"},
+                }]
+            },
+        }
+        with tempfile.TemporaryDirectory() as directory:
+            scratch = Path(directory) / "scratch"
+            scratch.mkdir(mode=0o700)
+            calls = []
+
+            def api(path):
+                calls.append(path)
+                return run_responses[path]
+
+            def api_helper(command, **kwargs):
+                calls.append(command)
+                path = Path(command[-1])
+                write_artifact(path)
+                return b"PASS"
+
+            # The source helper requires a private root directory; this synthetic test isolates its owner check.
+            with patch.object(release_source, "ensure_private_scratch"):
+                with patch("release_source.run_api_helper", side_effect=api_helper):
+                    manifest, raw = release_source.fetch_release(
+                        request, policy=POLICY, temp_dir=scratch, api=api, current_main=COMMIT
+                    )
+            self.assertEqual(manifest, MANIFEST)
+            self.assertEqual(hashlib.sha256(raw).hexdigest(), descriptor_sha)
+            self.assertTrue(any(isinstance(call, list) and call[1] == "DOWNLOAD" for call in calls))
+
+    def test_latest_release_request_uses_bounded_filtered_listing_and_verifies_details(self):
+        descriptor_sha = "e" * 64
+        responses = {
+            "/repos/admin/akyldash/actions/workflows/release-images.yaml/runs": {
+                "total_count": 2,
+                "workflow_runs": [
+                    {"id": 410, "head_sha": None, "workflow_id": None, "head_branch": None},
+                    {"id": 411, "head_sha": None, "workflow_id": None, "head_branch": None},
+                ],
+            },
+            "/repos/admin/akyldash/actions/runs/411": {
+                "id": 411, "workflow_id": "release-images.yaml", "name": "Release production images",
+                "status": "completed", "conclusion": "success", "head_sha": COMMIT,
+                "head_branch": "main", "event": "workflow_run",
+            },
+            "/repos/admin/akyldash/actions/workflows/release-images.yaml": {
+                "id": "release-images.yaml", "name": "Release production images",
+                "path": ".gitea/workflows/release-images.yaml",
+            },
+            "/repos/admin/akyldash/actions/runs/411/artifacts": {
+                "artifacts": [{
+                    "id": 9, "name": f"release-descriptor-411-{descriptor_sha}", "expired": False,
+                    "workflow_run": {"id": 411, "head_sha": COMMIT, "head_branch": "main",
+                                     "event": "workflow_run", "conclusion": "success"},
+                }]
+            },
+        }
+        calls = []
+
+        def api(path):
+            calls.append(path)
+            parsed = urlsplit(path)
+            return responses[parsed.path]
+
+        request = release_source.latest_release_request(current_main=COMMIT, api=api)
+        self.assertEqual(request, {"run_id": "411", "commit": COMMIT, "descriptor_sha256": descriptor_sha})
+        filters = parse_qs(urlsplit(calls[0]).query)
+        self.assertEqual(filters, {
+            "event": ["workflow_run"], "branch": ["main"], "status": ["success"],
+            "head_sha": [COMMIT], "page": ["1"], "limit": ["10"],
+        })
+        self.assertIn("/actions/workflows/release-images.yaml/runs?", calls[0])
+        self.assertIn("/repos/admin/akyldash/actions/runs/411", calls)
+
+    def test_latest_release_request_fails_closed_on_incomplete_listing(self):
+        with self.assertRaisesRegex(ValueError, "incomplete"):
+            release_source.latest_release_request(
+                current_main=COMMIT,
+                api=lambda _path: {"total_count": 11, "workflow_runs": [{"id": i} for i in range(10)]},
+            )
+
+    def test_latest_release_request_rejects_wrong_detailed_source(self):
+        responses = {
+            "/repos/admin/akyldash/actions/workflows/release-images.yaml/runs": {
+                "total_count": 1, "workflow_runs": [{"id": 411}],
+            },
+            "/repos/admin/akyldash/actions/runs/411": {
+                "id": 411, "workflow_id": "release-images.yaml", "status": "completed",
+                "conclusion": "success", "head_sha": "f" * 40,
+                "head_branch": "main", "event": "workflow_run",
+            },
+            "/repos/admin/akyldash/actions/workflows/release-images.yaml": {
+                "id": "release-images.yaml", "name": "Release production images",
+                "path": ".gitea/workflows/release-images.yaml",
+            },
+        }
+        def api(path):
+            return responses[urlsplit(path).path]
+
+        with self.assertRaisesRegex(ValueError, "does not match"):
+            release_source.latest_release_request(current_main=COMMIT, api=api)
+
+    def test_api_json_caps_response_and_passes_no_token_argument(self):
+        with patch.object(release_source, "run_api_helper", return_value=b'{"ok":true}') as run:
+            self.assertEqual(release_source.api_json("/repos/admin/akyldash"), {"ok": True})
+        command = run.call_args.args[0]
+        self.assertEqual(command, ["gitea-api", "GET", "/repos/admin/akyldash"])
+        self.assertEqual(run.call_args.kwargs["timeout"], release_source.API_TIMEOUT_SECONDS)
+        with patch.object(release_source, "run_api_helper", return_value=b"x" * (release_source.MAX_API_RESPONSE_BYTES + 1)):
+            with self.assertRaisesRegex(ValueError, "size limit"):
+                release_source.api_json("/repos/admin/akyldash")
+
+    def test_api_helper_timeout_is_bounded_and_fails_closed(self):
+        with self.assertRaisesRegex(ValueError, "timed out"):
+            release_source.run_api_helper(
+                [sys.executable, "-c", "import time; time.sleep(10)"], env=None,
+                timeout=0.05, max_stdout_bytes=32, max_file_bytes=32,
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

infra/deploy/test_release_workflow.py

@@ -0,0 +1,372 @@
+import contextlib
+import io
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+import release_handoff
+from release_handoff import descriptor_request, validate_source
+
+ROOT = Path(__file__).resolve().parents[2]
+GITEA_UPLOAD_ARTIFACT = "https://gitea.com/actions/gitea-upload-artifact@055b8b3f04a4a7ed853f2c6ab04256f83e4874dc"
+
+
+def workflow_step_env(path, step_name, payload):
+    lines = path.read_text(encoding="utf-8").splitlines()
+    marker = f"      - name: {step_name}"
+    start = lines.index(marker)
+    block = []
+    for line in lines[start + 1 :]:
+        if line.startswith("      - "):
+            break
+        block.append(line)
+    env_start = block.index("        env:") + 1
+    env = {}
+    for line in block[env_start:]:
+        match = re.fullmatch(r"          ([A-Z_]+): \$\{\{ (gitea(?:\.[a-z_]+)+) \}\}", line)
+        if not match:
+            if line.startswith("          ") and not line.startswith("            "):
+                break
+            continue
+        key, expression = match.groups()
+        value = payload
+        for component in expression.split("."):
+            value = value[component]
+        env[key] = str(value)
+    return env
+
+
+class ReleaseWorkflowTests(unittest.TestCase):
+    def test_latest_main_lookup_uses_explicit_checkout(self):
+        with tempfile.TemporaryDirectory() as directory, patch.object(
+            release_handoff.subprocess, "run",
+            return_value=type("Result", (), {"stdout": "a" * 40 + "\trefs/heads/main\n"})(),
+        ) as run:
+            self.assertEqual(release_handoff.latest_main_sha(Path(directory)), "a" * 40)
+        self.assertEqual(run.call_args.args[0][:3], ["git", "-C", directory])
+
+    def test_publisher_runs_only_after_successful_main_ci_and_binds_source_sha(self):
+        workflow = (ROOT / ".gitea/workflows/release-images.yaml").read_text(encoding="utf-8")
+        self.assertIn('workflows: ["CI"]', workflow)
+        self.assertIn("branches: [main]", workflow)
+        self.assertIn("types: [completed]", workflow)
+        self.assertIn("gitea.event.workflow_run.conclusion == 'success'", workflow)
+        self.assertIn("gitea.event.workflow_run.event == 'push'", workflow)
+        self.assertIn("gitea.event.workflow_run.head_branch == 'main'", workflow)
+        self.assertIn("ref: ${{ gitea.event.workflow_run.head_sha }}", workflow)
+        self.assertIn("python3 infra/deploy/release_handoff.py validate-ci-source", workflow)
+        self.assertNotIn("workflow_dispatch:", workflow)
+        self.assertIn("secrets.REGISTRY_USERNAME", workflow)
+        self.assertIn("secrets.REGISTRY_PASSWORD", workflow)
+        self.assertIn(GITEA_UPLOAD_ARTIFACT, workflow)
+        self.assertIn("release/release-manifest.json.sha256", workflow)
+        self.assertIn("retention-days: 90", workflow)
+        self.assertIn("if-no-files-found: error", workflow)
+        self.assertNotIn("gitea.run_attempt", workflow)
+        self.assertIn("${{ gitea.run_id }}", workflow)
+        self.assertIn("${{ gitea.event.workflow_run.head_sha }}", workflow)
+        self.assertIn("steps.descriptor.outputs.descriptor_sha256", workflow)
+        self.assertIn("(cd release && sha256sum -c release-manifest.json.sha256)", workflow)
+        self.assertNotIn("docker compose", workflow)
+
+        guard = workflow.index("Verify successful CI source before using registry credentials")
+        registry_secret = workflow.index("Require explicitly configured Gitea registry credentials")
+        self.assertLess(guard, registry_secret)
+
+    def test_workflow_yaml_maps_gitea_125_payload_into_both_source_guards(self):
+        head_sha = "a" * 40
+        cases = (
+            ("release-images.yaml", "Verify successful CI source before using registry credentials",
+             "validate-ci-source", "CI", "ci.yaml@refs/heads/main", "push", "583"),
+            ("deploy-handoff.yaml", "Verify source release identity before artifact lookup",
+             "validate-handoff-source", "Release production images",
+             "release-images.yaml@refs/heads/main", "workflow_run", "584"),
+        )
+        for filename, step, command, name, path, event, run_id in cases:
+            payload = {
+                "action": "completed",
+                "workflow": {"id": "workflow-id", "name": name, "path": path.split("@")[0], "state": "active"},
+                "workflow_run": {
+                    "id": int(run_id), "path": path, "event": event, "conclusion": "success",
+                    "head_branch": "main", "head_sha": head_sha,
+                },
+                "repository": {"full_name": "admin/akyldash"},
+            }
+            workflow_path = ROOT / ".gitea/workflows" / filename
+            source_env = workflow_step_env(workflow_path, step, {"gitea": {"event": payload}})
+            self.assertEqual(set(source_env), {
+                "SOURCE_WORKFLOW", "SOURCE_WORKFLOW_PATH", "SOURCE_EVENT", "SOURCE_CONCLUSION",
+                "SOURCE_BRANCH", "SOURCE_RUN_ID", "SOURCE_SHA", "SOURCE_REPOSITORY",
+            })
+            self.assertIn(f"release_handoff.py {command}", workflow_path.read_text(encoding="utf-8"))
+            with (
+                patch.dict(os.environ, source_env),
+                patch.object(sys, "argv", ["release_handoff.py", command]),
+                patch.object(release_handoff, "latest_main_sha", return_value=head_sha),
+            ):
+                self.assertEqual(release_handoff.main(), 0)
+
+            with self.subTest(filename=filename, invalid="repository"), patch.dict(
+                os.environ, source_env | {"SOURCE_REPOSITORY": "attacker/akyldash"}
+            ), patch.object(sys, "argv", ["release_handoff.py", command]), patch.object(
+                release_handoff, "latest_main_sha", return_value=head_sha
+            ):
+                self.assertEqual(release_handoff.main(), 1)
+
+    def test_deploy_handoff_is_dry_and_uses_the_source_release_run_id(self):
+        workflow = (ROOT / ".gitea/workflows/deploy-handoff.yaml").read_text(encoding="utf-8")
+        self.assertIn("name: Production handoff status (not deployed)", workflow)
+        self.assertIn("name: NOT DEPLOYED - handoff status only", workflow)
+        self.assertIn('workflows: ["Release production images"]', workflow)
+        self.assertIn("branches: [main]", workflow)
+        self.assertIn("types: [completed]", workflow)
+        self.assertIn("gitea.event.workflow_run.conclusion == 'success'", workflow)
+        self.assertIn("gitea.event.workflow_run.event == 'workflow_run'", workflow)
+        self.assertIn("gitea.event.workflow_run.head_branch == 'main'", workflow)
+        self.assertIn("SOURCE_RUN_ID: ${{ gitea.event.workflow_run.id }}", workflow)
+        self.assertNotIn("SOURCE_RUN_ID: ${{ gitea.run_id }}", workflow)
+        self.assertIn("gitea-api GET", workflow)
+        self.assertNotIn("curl ", workflow)
+        self.assertNotIn("AKYLDASH_DEPLOY_SSH_KEY", workflow)
+        self.assertNotIn("docker.sock", workflow)
+        self.assertIn("host handoff are not verified", workflow)
+        self.assertIn("DEPLOYMENT STATUS: NOT DEPLOYED", workflow)
+        self.assertIn("No Windows execution runner or automatic runtime binding has been verified.", workflow)
+        self.assertNotIn("receive_external.py", workflow)
+        self.assertNotIn("akyldash-production-windows", workflow)
+
+    def test_source_guards_reject_wrong_event_or_stale_main(self):
+        valid = dict(
+            workflow="CI", workflow_path="ci.yaml@refs/heads/main", repository="admin/akyldash",
+            event="push", conclusion="success", branch="main",
+            run_id="301", head_sha="a" * 40, stage="release", current_main="a" * 40,
+        )
+        validate_source(**valid)
+        for change in (
+            {"event": "pull_request"},
+            {"branch": "feature/test"},
+            {"conclusion": "failure"},
+            {"workflow": "untrusted workflow"},
+            {"workflow_path": "untrusted.yaml@refs/heads/main"},
+            {"repository": "untrusted/repository"},
+            {"head_sha": "A" * 40},
+            {"run_id": "3/../1"},
+            {"current_main": "b" * 40},
+        ):
+            with self.subTest(change=change), self.assertRaises(ValueError):
+                validate_source(**(valid | change))
+
+    def test_handoff_tuple_binds_artifact_run_commit_and_digest(self):
+        run_id = "302"
+        head_sha = "a" * 40
+        digest = "b" * 64
+        response = {
+            "artifacts": [{
+                "id": 9,
+                "name": f"release-descriptor-{run_id}-{digest}",
+                "expired": False,
+                "workflow_run": {
+                    "id": int(run_id), "head_sha": head_sha, "head_branch": "main",
+                    "event": "workflow_run", "conclusion": "success",
+                },
+            }]
+        }
+        request = descriptor_request(response, run_id=run_id, head_sha=head_sha)
+        self.assertEqual(request, {"run_id": run_id, "commit": head_sha, "descriptor_sha256": digest})
+        self.assertEqual(set(request), {"run_id", "commit", "descriptor_sha256"})
+        for artifact in (
+            {**response["artifacts"][0], "name": f"release-descriptor-303-{digest}"},
+            {**response["artifacts"][0], "name": f"release-descriptor-{run_id}-not-a-digest"},
+            {**response["artifacts"][0], "workflow_run": {"id": 303}},
+            {**response["artifacts"][0], "expired": True},
+        ):
+            with self.subTest(artifact=artifact), self.assertRaises(ValueError):
+                descriptor_request({"artifacts": [artifact]}, run_id=run_id, head_sha=head_sha)
+        with self.assertRaises(ValueError):
+            descriptor_request({"artifacts": [response["artifacts"][0], response["artifacts"][0]]}, run_id=run_id, head_sha=head_sha)
+
+    def test_dry_run_validates_the_tuple_without_opening_a_host_connection(self):
+        run_id = "302"
+        head_sha = "a" * 40
+        artifacts = {
+            "artifacts": [{
+                "name": f"release-descriptor-{run_id}-{'b' * 64}",
+                "expired": False,
+                "workflow_run": {
+                    "id": int(run_id), "head_sha": head_sha, "head_branch": "main",
+                    "event": "workflow_run", "conclusion": "success",
+                },
+            }]
+        }
+        with tempfile.TemporaryDirectory() as directory:
+            metadata = Path(directory) / "artifacts.json"
+            metadata.write_text(json.dumps(artifacts), encoding="utf-8")
+            environment = {
+                "SOURCE_WORKFLOW": "Release production images",
+                "SOURCE_WORKFLOW_PATH": "release-images.yaml@refs/heads/main",
+                "SOURCE_EVENT": "workflow_run",
+                "SOURCE_CONCLUSION": "success",
+                "SOURCE_BRANCH": "main",
+                "SOURCE_RUN_ID": run_id,
+                "SOURCE_SHA": head_sha,
+                "SOURCE_REPOSITORY": "admin/akyldash",
+            }
+            output = io.StringIO()
+            with (
+                patch.dict(os.environ, environment),
+                patch.object(sys, "argv", ["release_handoff.py", "dry-run", "--artifact-metadata", str(metadata)]),
+                patch.object(release_handoff, "latest_main_sha", return_value=head_sha),
+                contextlib.redirect_stdout(output),
+            ):
+                self.assertEqual(release_handoff.main(), 0)
+        self.assertIn("descriptor_sha256=" + "b" * 64, output.getvalue())
+        self.assertIn("ZIP bytes were not fetched", output.getvalue())
+        self.assertIn("no host connection was opened", output.getvalue())
+
+    def test_pr_ci_has_small_synthetic_artifact_upload_without_registry_secrets(self):
+        workflow = (ROOT / ".gitea/workflows/ci.yaml").read_text(encoding="utf-8")
+        self.assertIn("Verify Gitea runtime artifact upload", workflow)
+        self.assertIn(GITEA_UPLOAD_ARTIFACT, workflow)
+        self.assertIn("retention-days: 1", workflow)
+        self.assertIn("if-no-files-found: error", workflow)
+        self.assertNotIn("github.run_attempt", workflow)
+        self.assertIn("${{ github.run_id }}", workflow)
+        self.assertIn("artifact-smoke/marker.txt", workflow)
+        self.assertNotIn("REGISTRY_PASSWORD", workflow)
+
+    def test_release_checksum_survives_flattened_artifact_layout(self):
+        workflow = (ROOT / ".gitea/workflows/release-images.yaml").read_text(encoding="utf-8")
+        generate = "(cd release && sha256sum release-manifest.json > release-manifest.json.sha256)"
+        verify = "(cd release && sha256sum -c release-manifest.json.sha256)"
+        self.assertIn(generate, workflow)
+        self.assertIn(verify, workflow)
+
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            release = root / "release"
+            release.mkdir()
+            (release / "release-manifest.json").write_text(
+                "synthetic manifest\n", encoding="utf-8"
+            )
+
+            generated = subprocess.run(
+                ["bash", "-e", "-c", generate], cwd=root, text=True, capture_output=True
+            )
+            self.assertEqual(generated.returncode, 0, generated.stderr)
+            verified = subprocess.run(
+                ["bash", "-e", "-c", verify], cwd=root, text=True, capture_output=True
+            )
+            self.assertEqual(verified.returncode, 0, verified.stderr)
+
+            extracted = root / "artifact-root"
+            extracted.mkdir()
+            (extracted / "release-manifest.json").write_bytes((release / "release-manifest.json").read_bytes())
+            (extracted / "release-manifest.json.sha256").write_bytes(
+                (release / "release-manifest.json.sha256").read_bytes()
+            )
+            downloaded = subprocess.run(
+                ["sha256sum", "-c", "release-manifest.json.sha256"],
+                cwd=extracted,
+                text=True,
+                capture_output=True,
+            )
+            self.assertEqual(downloaded.returncode, 0, downloaded.stderr)
+
+    def test_pr_build_remains_no_push_and_push_action_has_no_engine_socket(self):
+        build_action = (ROOT / ".gitea/actions/kaniko-build/action.yml").read_text(encoding="utf-8")
+        push_action = (ROOT / ".gitea/actions/kaniko-push/release-build.sh").read_text(encoding="utf-8")
+        self.assertIn("--no-push", build_action)
+        self.assertIn("--no-push-cache", build_action)
+        self.assertIn("REGISTRY_USERNAME:?", push_action)
+        self.assertIn("REGISTRY_PASSWORD:?", push_action)
+        self.assertNotIn("docker.sock", push_action)
+        self.assertNotIn("DOCKER_HOST", push_action)
+        self.assertIn("--digest-file=", push_action)
+
+    def test_release_validator_accepts_workflow_tags_without_credentials_or_kaniko(self):
+        workflow = (ROOT / ".gitea/workflows/release-images.yaml").read_text(encoding="utf-8")
+        dockerfile = ROOT / ".gitea/actions/kaniko-push/Dockerfile"
+        release_builder = (ROOT / ".gitea/actions/kaniko-push/release-build.sh").read_text(encoding="utf-8")
+        validator = ROOT / ".gitea/actions/kaniko-push/validate-destination.sh"
+        self.assertIn(
+            "COPY validate-destination.sh /usr/local/bin/validate-destination.sh",
+            dockerfile.read_text(encoding="utf-8"),
+        )
+        self.assertIn(
+            '/busybox/sh /usr/local/bin/validate-destination.sh "$dockerfile" "$destination"',
+            release_builder,
+        )
+        self.assertIn(
+            "destination: git.vakanaut.ru/admin/akyldash/backend:${{ gitea.event.workflow_run.head_sha }}-${{ gitea.run_id }}",
+            workflow,
+        )
+        self.assertIn(
+            "destination: git.vakanaut.ru/admin/akyldash/opensearch:${{ gitea.event.workflow_run.head_sha }}-${{ gitea.run_id }}",
+            workflow,
+        )
+        examples = (
+            ("deploy/production/Dockerfile.backend", "git.vakanaut.ru/admin/akyldash/backend"),
+            ("deploy/production/Dockerfile.opensearch", "git.vakanaut.ru/admin/akyldash/opensearch"),
+        )
+        environment = {"PATH": os.environ.get("PATH", "/usr/bin:/bin")}
+        for dockerfile_path, repository in examples:
+            destination = f"{repository}:{'a' * 40}-567"
+            with self.subTest(repository=repository):
+                accepted = subprocess.run(
+                    ["sh", str(validator), dockerfile_path, destination],
+                    text=True,
+                    capture_output=True,
+                    env=environment,
+                )
+                self.assertEqual(accepted.returncode, 0, accepted.stderr)
+
+                for invalid in (
+                    destination + "-1",
+                    destination.replace(repository, "registry.invalid/other/image"),
+                    f"{repository}:{'A' * 40}-567",
+                    f"{repository}:{'a' * 39}-567",
+                    f"{repository}:{'a' * 40}-",
+                    f"{repository}:{'a' * 40}-not-a-run-id",
+                ):
+                    rejected = subprocess.run(
+                        ["sh", str(validator), dockerfile_path, invalid],
+                        text=True,
+                        capture_output=True,
+                        env=environment,
+                    )
+                    self.assertNotEqual(rejected.returncode, 0, invalid)
+
+                rejected_dockerfile = subprocess.run(
+                    ["sh", str(validator), "deploy/production/Dockerfile.unapproved", destination],
+                    text=True,
+                    capture_output=True,
+                    env=environment,
+                )
+                self.assertNotEqual(rejected_dockerfile.returncode, 0)
+
+    def test_forced_command_dispatcher_has_only_exact_status_and_deploy_literals(self):
+        dispatcher = ROOT / "infra/deploy/akyldash-release-dispatch.sh"
+        installer = (ROOT / "infra/deploy/install-helper.sh").read_text(encoding="utf-8")
+        source = dispatcher.read_text(encoding="utf-8")
+        self.assertEqual(subprocess.run(["bash", "-n", str(dispatcher)]).returncode, 0)
+        self.assertIn('/usr/local/sbin/akyldash-release-status)', source)
+        self.assertIn('/usr/local/sbin/akyldash-release-deploy)', source)
+        self.assertIn('[[ $EUID -ne 0 || $# -ne 0 ]]', source)
+        self.assertNotIn("eval", source)
+        self.assertIn('install -o root -g root -m 0750 "$release_dispatch_source" /usr/local/sbin/akyldash-release-dispatch', installer)
+        self.assertIn('bash -n "$release_deploy_source" "$release_rollback_source" "$release_dispatch_source"', installer)
+        rejected = subprocess.run(
+            ["bash", str(dispatcher)], env={**os.environ, "SSH_ORIGINAL_COMMAND": "id"},
+            text=True, capture_output=True,
+        )
+        self.assertNotEqual(rejected.returncode, 0)
+
+
+if __name__ == "__main__":
+    unittest.main()

infra/deploy/test_rollback.py

@@ -1,12 +1,22 @@
 import json
 import subprocess
 import sys
+import tempfile
 import unittest
 from types import SimpleNamespace
 from unittest.mock import patch
 
 import rollback
-from rollback import image_restore_plan, require_tag_rollback, tag_previous_images, verify_previous_images
+import deployment_lock
+import release_refs
+import release_state
+from rollback import (
+    image_restore_plan,
+    require_running_image_ids,
+    require_tag_rollback,
+    tag_previous_images,
+    verify_previous_images,
+)
 
 
 class RollbackPlanTests(unittest.TestCase):
@@ -27,10 +37,30 @@ class RollbackPlanTests(unittest.TestCase):
         self.assertEqual(plan["backend"][1], "akyldash/backend:local")
         self.assertEqual(plan["opensearch"][1], "akyldash/opensearch:local")
 
+    def test_rollback_rejects_running_images_that_differ_from_restore_plan(self):
+        expected = {"backend": "sha256:" + "a" * 64, "opensearch": "sha256:" + "b" * 64}
+        actual = {**expected, "opensearch": "sha256:" + "c" * 64}
+        with self.assertRaisesRegex(ValueError, "rollback plan"):
+            require_running_image_ids(expected, actual, "rollback plan")
+
     def test_refuses_changed_compose_image_reference(self):
         with self.assertRaisesRegex(ValueError, "reference changed"):
             image_restore_plan(self.manifest, {**self.configured, "backend": "other/backend:tag"})
 
+    def test_release_state_allows_guarded_digest_to_legacy_and_legacy_to_digest_restore(self):
+        previous = self.manifest["images"].copy()
+        self.configured["backend"] = "registry/backend@sha256:" + "d" * 64
+        plan = image_restore_plan(self.manifest, self.configured, previous)
+        self.assertEqual(plan["backend"][1], "akyldash/backend:local")
+        old_digest = "registry/backend@sha256:" + "c" * 64
+        self.manifest["images"]["backend"] = {
+            "configured": old_digest, "image_id": "sha256:" + "a" * 64
+        }
+        previous["backend"] = self.manifest["images"]["backend"]
+        self.configured["backend"] = "akyldash/backend:local"
+        plan = image_restore_plan(self.manifest, self.configured, previous)
+        self.assertEqual(plan["backend"][1], old_digest)
+
     def test_refuses_digest_reference_that_cannot_be_retagged(self):
         self.manifest["images"]["backend"]["configured"] = "registry/backend@sha256:" + "c" * 64
         self.configured["backend"] = self.manifest["images"]["backend"]["configured"]
@@ -68,53 +98,19 @@ class RollbackPlanTests(unittest.TestCase):
             with self.assertRaisesRegex(ValueError, "previous image is unavailable"):
                 verify_previous_images(plan)
 
-    def test_digest_reference_is_never_tagged(self):
+    def test_digest_reference_is_restored_without_retagging(self):
         digest = "registry/backend@sha256:" + "c" * 64
         plan = {"backend": ("sha256:" + "a" * 64, digest)}
         with patch("rollback.run") as run_mock:
-            with self.assertRaisesRegex(ValueError, "not supported safely"):
-                tag_previous_images(plan)
+            tag_previous_images(plan)
         run_mock.assert_not_called()
 
-    def test_digest_rollback_fails_before_stopping_or_changing_references(self):
-        backend_id = "sha256:" + "a" * 64
-        opensearch_id = "sha256:" + "b" * 64
-        digest = "registry/backend@sha256:" + "c" * 64
-        manifest = {
-            "images": {
-                "backend": {"configured": digest, "image_id": backend_id},
-                "opensearch": self.manifest["images"]["opensearch"],
-            },
-            "deployment_files": {
-                "deploy/production/compose.yaml": "compose-hash",
-                "deploy/production/Caddyfile": "caddy-hash",
-            },
-        }
-        rendered = {
-            "services": {
-                "backend": {"image": digest},
-                "opensearch": {"image": self.configured["opensearch"]},
-            }
-        }
-        fake_archive = SimpleNamespace(
-            digest=lambda path: "compose-hash" if path.name == "compose.yaml" else "caddy-hash",
-            verify_archive=lambda _backup: manifest,
-        )
-        backup = rollback.BACKUP_DIR / "synthetic.tar.gz"
-        with (
-            patch("rollback.Path.is_file", return_value=True),
-            patch("rollback.Path.is_symlink", return_value=False),
-            patch("rollback.Path.stat", return_value=SimpleNamespace(st_uid=0, st_mode=0o100600)),
-            patch("rollback.compose", return_value=json.dumps(rendered)) as compose_mock,
-            patch("rollback.run", side_effect=[backend_id, backend_id, opensearch_id]) as run_mock,
-            patch.dict(sys.modules, {"archive": fake_archive}),
-        ):
-            with self.assertRaisesRegex(ValueError, "not supported safely"):
-                rollback.rollback(backup, data_compatible=True)
-        compose_mock.assert_called_once_with("config", "--format", "json", capture=True)
-        self.assertEqual(run_mock.call_count, 3)
-        self.assertTrue(all(call.args[0][:3] == ["docker", "image", "inspect"]
-                            for call in run_mock.call_args_list))
+    def test_local_vps_backup_path_is_disabled_without_docker_operations(self):
+        with patch("rollback.compose") as compose_mock, patch("rollback.run") as run_mock:
+            with self.assertRaisesRegex(ValueError, "local VPS backup paths are disabled"):
+                rollback.rollback(rollback.Path("/var/backups/akyldash/old.tar.gz"), data_compatible=True)
+        compose_mock.assert_not_called()
+        run_mock.assert_not_called()
 
     def test_tag_rollback_keeps_existing_image_tag_operation(self):
         plan = image_restore_plan(self.manifest, self.configured)

infra/deploy/validate_release.py

@@ -10,6 +10,7 @@ import sys
 from pathlib import Path
 
 SERVICES = {"backend", "opensearch"}
+REPOSITORY = "admin/akyldash"
 COMMIT_RE = re.compile(r"[0-9a-f]{40}\Z")
 REPOSITORY_RE = re.compile(
     r"[a-z0-9]+(?:[._-][a-z0-9]+)*(?::[0-9]+)?"
@@ -58,16 +59,27 @@ def validate_policy(policy: object) -> dict[str, list[str]]:
 def validate_manifest(manifest: object, policy: object) -> dict[str, object]:
     allowed_repositories = validate_policy(policy)
     if not isinstance(manifest, dict) or set(manifest) != {
-        "schema_version", "source_ref", "commit", "images"
+        "schema_version", "source_ref", "repository", "commit", "workflow", "run_id", "source_run_id", "builder", "images"
     }:
-        raise ValueError("manifest must contain exactly schema_version, source_ref, commit, and images")
-    if type(manifest["schema_version"]) is not int or manifest["schema_version"] != 1:
+        raise ValueError("manifest must contain exactly the release source, builder, run, and image fields")
+    if type(manifest["schema_version"]) is not int or manifest["schema_version"] != 4:
         raise ValueError("unsupported manifest schema_version")
     if manifest["source_ref"] != "refs/heads/main":
         raise ValueError("manifest source_ref must be refs/heads/main")
     commit = manifest["commit"]
     if not isinstance(commit, str) or not COMMIT_RE.fullmatch(commit):
         raise ValueError("manifest commit must be a 40-character lowercase Git SHA-1")
+    if manifest["repository"] != REPOSITORY:
+        raise ValueError(f"manifest repository must be {REPOSITORY}")
+    if manifest["workflow"] != ".gitea/workflows/release-images.yaml":
+        raise ValueError("manifest workflow is not the approved image release workflow")
+    if not isinstance(manifest["run_id"], str) or not re.fullmatch(r"[0-9]+", manifest["run_id"]):
+        raise ValueError("manifest run_id must be a numeric Gitea Actions run ID")
+    if not isinstance(manifest["source_run_id"], str) or not re.fullmatch(r"[0-9]+", manifest["source_run_id"]):
+        raise ValueError("manifest source_run_id must be a numeric Gitea CI run ID")
+    builder = manifest["builder"]
+    if builder != {"name": "Kaniko", "image": "ghcr.io/osscontainertools/kaniko:v1.28.5-debug@sha256:c73ca67a3b494bce79a8fb6090c4f73c18997ab272d80bffc460a62343aeb412"}:
+        raise ValueError("manifest builder is not the pinned release builder")
     images = manifest["images"]
     if not isinstance(images, dict) or set(images) != SERVICES:
         raise ValueError("manifest images must contain exactly backend and opensearch")

infra/deploy/windows-release-trigger.example.json

@@ -0,0 +1,6 @@
+{
+  "schema_version": 1,
+  "enabled": false,
+  "repository": "D:\\Dev\\akyldash",
+  "ssh_alias": "akyldash_release"
+}

infra/deploy/windows-release-trigger.example.xml

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>One-shot poll for a root-verified Akyldash release. Disabled template; requires owner review.</Description>
+    <URI>\Akyldash\ReleaseTrigger</URI>
+  </RegistrationInfo>
+  <Triggers>
+    <CalendarTrigger>
+      <StartBoundary>2026-11-02T09:00:00</StartBoundary>
+      <Enabled>false</Enabled>
+      <ScheduleByDay><DaysInterval>1</DaysInterval></ScheduleByDay>
+      <Repetition>
+        <Interval>PT5M</Interval>
+        <Duration>P1D</Duration>
+        <StopAtDurationEnd>false</StopAtDurationEnd>
+      </Repetition>
+    </CalendarTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Owner">
+      <UserId>REPLACE_WITH_OWNER_SID</UserId>
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>true</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>false</StartWhenAvailable>
+    <Enabled>false</Enabled>
+    <Hidden>false</Hidden>
+    <WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+  </Settings>
+  <Actions Context="Owner">
+    <Exec>
+      <Command>C:\Program Files\Akyldash\python.exe</Command>
+      <Arguments>&quot;C:\Program Files\Akyldash\receive_external.py&quot; --once</Arguments>
+      <WorkingDirectory>C:\Program Files\Akyldash</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>