HY2XS_flamy/docs/11-testing-and-acceptance.md

# Testing and acceptance

## Цель документа

Зафиксировать checklist для новой двухслойной схемы.

## Как запускать тесты

```bash
# Юнит-тесты и типы оркестратора
cd orchestrator && bun install --frozen-lockfile && bun run check && bun test

# Тесты и статический анализ HY2XS admin
cd apps && go vet ./... && go test ./...

# Проверка типов и сборка frontend
cd apps/frontend && pnpm install --frozen-lockfile && pnpm run verify

# Сверка среды разработки с versions.env (ничего не меняет)
./tools/dev/doctor.sh

# Полный E2E с реальным клиентом Hysteria (Debian 13 amd64; нужен Go)
HYSTERIA_BIN=/usr/local/bin/hysteria ./tools/test/e2e-hysteria.sh

# Production-сборка: прогоняет тесты, резолвер и compatibility gate
./tools/build/build.sh
```

`build.sh` останавливается, если падают тесты оркестратора, тесты админки или compatibility gate.

## A. Builder layer tests

### Проверяем
1. builder запускается на Debian 13 amd64 build host
2. итоговый пакет собирается без target-side шагов
3. bundled HY2XS admin реально входит в пакет
4. package metadata / build id присутствуют
5. compiled Bun/TypeScript orchestrator artifact присутствует
6. в пакет не попадает build-мусор
7. builder сам доставляет отсутствующие build-зависимости
8. builder проверяет версии Go/Bun/Node.js/pnpm
9. builder пишет версии toolchain в metadata
10. builder прогоняет `bun test` и `go test` до упаковки

## A1. Latest-stable resolver

Фикстуры и ожидаемое поведение (`orchestrator/test/hysteria-release.test.ts`):

| Сценарий | Ожидание |
| --- | --- |
| stable `app/v2.12.2` | выбирается |
| prerelease `app/v2.13.0` | игнорируется |
| draft `app/v2.14.0` | игнорируется |
| чужое семейство тегов (`core/`, `docs/`) | игнорируется |
| тег без префикса `app/` | игнорируется |
| `app/v2.9.10` против `app/v2.9.2` | выбирается `2.9.10` (числовое сравнение, не строковое) |
| отсутствует `hysteria-linux-amd64` | ошибка |
| дублирующийся `hysteria-linux-amd64` | ошибка, а не случайный выбор |
| non-https URL артефакта | ошибка |
| невалидный semver в теге | игнорируется |
| пустой список релизов | понятная ошибка |
| несовпадение SHA-256 | сборка падает |
| сетевая ошибка / rate limit | понятная ошибка с подсказкой про `GITHUB_TOKEN` и `HYSTERIA_CHANNEL=pinned` |

Отдельно проверяется, что **`latest stable` — это именно stable, а не максимальная строка или самый свежий тег**.

## A2. Release rollover

Ключевой acceptance-критерий модели «latest на сборке»:

```text
Сегодня:  latest = 2.12.2  →  пакет A закрепляет 2.12.2
Завтра:   latest = 2.12.3  →  пакет B закрепляет 2.12.3

Повторная установка пакета A всё равно ставит 2.12.2
```

Проверяется на двух уровнях:
- резолвер даёт разный результат на разных снимках upstream (`orchestrator/test/release-rollover.test.ts`);
- install-time код не импортирует резолвер, не обращается к `api.github.com` и не использует moving `latest` — это утверждение проверяется тестом и acceptance-шагом сборки.

## A3. Compatibility gate

1. скачанный артефакт проходит проверку SHA-256;
2. `hysteria version` совпадает с разрешённой версией;
3. реальный бинарник принимает канонический конфиг HY2XS для Gecko;
4. то же для Salamander;
5. при несовместимости падает **сборка** с сообщением `BUILD FAILED: unsupported Hysteria stable vX.Y.Z`, а не установка у пользователя.

## A4. Конфигурационный контракт (unit)

Таблица `orchestrator/test/env.test.ts`:

| Вход | Ожидание |
| --- | --- |
| значение не задано | `gecko` |
| `gecko` | принято |
| `salamander` | принято |
| неизвестный тип | отклонено |
| `Gecko` (регистр) | отклонено |
| gecko `max < min` | отклонено |
| gecko `max > 2048` | отклонено |
| gecko `max == 2048` | принято |
| неположительный/нецелый `min` | отклонено |
| пустой obfs-пароль | автогенерация, а не пустое значение в конфиге |
| `HY2XS_CONFIG_SCHEMA_VERSION=1` | отклонено с указанием на чистую установку |
| `HY2XS_CONFIG_SCHEMA_VERSION` отсутствует | отклонено как legacy-конфигурация |
| `HY2XS_CONFIG_SCHEMA_VERSION=` (пусто) | отклонено как legacy-конфигурация |
| `HY2XS_CONFIG_SCHEMA_VERSION=2` | принято |

Отсутствие маркера схемы отклоняется намеренно: до v1 этого поля не
существовало, поэтому именно пустое значение — самый вероятный признак
конфигурации 0.x. Любой fallback здесь молча превращал бы legacy-конфиг в
якобы валидный.

Отдельно — round-trip `parse(render(config)) == config`. Этот тест ловит класс ошибок «в рендер runtime-конфига попал литерал вместо значения из конфигурации».

Рендер конфига (`orchestrator/test/render-config.test.ts`):

- Gecko рендерит **только** gecko-подблок;
- Salamander рендерит **только** salamander-подблок;
- в конфиге никогда нет двух подтипов obfs одновременно;
- шаблон не содержит захардкоженного типа обфускации;
- пароль с пробелами и спецсимволами экранируется;
- YAML-инъекция через пароль отклоняется даже в обход env-валидации.

## A5. Граница установки и поколение (unit)

`orchestrator/test/clean-host.test.ts`:

- чистый хост проходит;
- **каждый** маркер по отдельности останавливает установку;
- список покрывает состояние, юниты, бинарник Hysteria и наследие 0.x;
- пути из конфигурации (`HY2XS_INSTALL_DIR`, `HY2XS_DATA_DIR`, `HY2XS_LOG_DIR`)
  попадают в список, а не только значения по умолчанию;
- всё, что удаляет `purge-v0.sh`, покрыто маркерами clean-host: два списка
  описывают одну границу и не имеют права разъезжаться;
- bootstrap-пути (`/usr/local/lib/hy2xs`, `/usr/local/lib/hy2xs/package`,
  `/usr/local/bin/hy2xs-orchestrator`) остаются маркерами **без исключений**:
  их создаёт оркестратор уже после проверки чистоты хоста, поэтому «мягкой»
  версии списка для PHASE 1 больше не существует;
- эти пути берутся из `config/profile.ts`, а не из копий строк: шаг, который
  их создаёт, и контракт, который на них отказывает, обязаны читать одно
  значение;
- сообщение перечисляет найденные маркеры и говорит, что хост не изменён.

`orchestrator/test/install-boundary.test.ts`:

- под read-only guard недоступны `writeText`, `writeTextAtomic`, `ensureDir` и
  все `runMutating*`-раннеры;
- read-only раннеры под guard'ом продолжают работать: разделение API — это не
  запрет наблюдения, а запрет мутации;
- классификация отказа зависит от ownership-флагов и фазы, а **не** от текста
  ошибки;
- `fatal_pre_apply` недостижим ни при одном взведённом флаге, включая
  `stateTouched`: записанный `install-state.json` уже делает хост изменённым;
- частично выполненная запись маркера (отказ на `chown` после успешного `write`)
  тоже даёт post-apply: флаг взводится **до** записи, а не после неё;
- начатая (не обязательно завершённая) установка пакетов уже даёт
  `fatal_post_apply` — регрессия на сценарий «PHASE 0 прошла, apt-get упал,
  установщик заявил, что ничего не тронул»;
- начатый bootstrap (`bootstrapTouched`) тоже даёт `fatal_post_apply`: раскладку
  выполняет оркестратор, и она учитывается наравне с остальными шагами.

`orchestrator/test/install-sequence.test.ts` — порядок фаз, который иначе
проверяется только на живом сервере:

- `preflight()` в режиме install **отказывается работать без явного
  `checkCleanHost`**, и отказ наступает до любой работы с системой;
- clean-host запрашивается ровно один раз за операцию и **до** первой записи
  install-state — регрессия на сценарий, где повторный preflight после
  `installDeps` опознавал собственный `install-state.json` как маркер чужой
  установки и валил каждую чистую установку;
- проход capabilities явно отказывается от clean-host;
- `bootstrapTouched` взводится **перед** `bootstrapRuntime`, а сам bootstrap
  идёт до `installDeps`;
- дальнейшая установка работает от установленного runtime-пакета;
- `diagnosticsCollect` обёрнута в `try/catch`, и `catch` стоит **до** отката:
  диагностика — best effort, откат — обязателен;
- в `package/install.sh` не осталось ни одной мутирующей команды, и он
  передаёт управление оркестратору через `exec`;
- классификация отказа `reconfigure`/`repair` идёт по ownership-флагам, а не по
  регулярному выражению над текстом ошибки.

`orchestrator/test/install-state.test.ts`:

- маркер текущего поколения принимается;
- маркер без полей поколения отклоняется, **несмотря на `installed: true`**;
- чужой `product`, `release_line` или `config_schema_version` отклоняются;
- записываемый маркер всегда несёт идентификацию поколения;
- незавершённая установка подсказывает `repair --allow-partial-state`.

## A5a. Обязательный откат (unit)

`orchestrator/test/rollback-mandatory.test.ts` — поведение механизма проверяется
настоящим внедрением отказа в стадию, проводка команд к нему — разбором
исходника (поднять systemd и nftables в этой среде нельзя):

- при отказе первой стадии отката выполняются **все** последующие;
- отказавшие стадии перечисляются по именам и в порядке объявления;
- откат не бросает даже при отказе всех стадий: наружу обязана уйти исходная
  ошибка операции, а не проблема внутри восстановления;
- не-`Error` причина (брошенная строка) не роняет откат;
- `persistFailureState` не пробрасывает отказ записи наружу — это и был P0:
  падение записи маркера отменяло откат целиком;
- в обработчике ошибки `install` и `reconfigure` не осталось незащищённой записи
  состояния (`advanceInstallState` / `markPhase` голым `await`);
- откат в обеих командах идёт через `runRollbackStages`, а не цепочкой `await`;
- внутри `rollbackCurrentState` ни одна команда не обрывает следующие: отказ
  `systemctl daemon-reload` отменял перезапуск сервисов строкой ниже, то есть
  восстановленные unit-файлы так и не применялись.

## A5c. Целостность резервных копий (unit)

`orchestrator/test/backup-integrity.test.ts`:

- копия каждой операции адресуется своим каталогом, разные `op-id` не
  пересекаются;
- разные пути дают разные имена файлов копии, и имя не выходит за пределы
  каталога;
- отсутствовавший файл записан **явно** (`present: false`), а не выведен из
  неудачи `cp`;
- манифест переживает сериализацию без потерь;
- разбор строгий: манифест чужой операции, неизвестная версия, битый JSON,
  запись без пути, без признака существования или без имени копии —
  отклоняются. «Поле не разобралось, будем считать, что файла не было» означало
  бы удаление существующего файла при откате;
- копирование в `reconfigure` и в `firewall` не глушит ошибки, факт создания
  копии проверяется, а копия снимается **до** первой мутации;
- маркер готовности firewall (`prepared`) ставится после проверенных копий;
- восстановление firewall не глушит ошибки `cp`/`nft`, а резервные копии
  удаляются только после подтверждённого успеха — иначе сохраняются вместе с
  сообщением `manual recovery data preserved at …`.

## A5d. Порядок фиксации успеха (unit)

`orchestrator/test/commit-ordering.test.ts`:

- снятие таймера автоотката и удаление резервных копий — **разные** операции
  (`disarmFirewallRollback` / `cleanupFirewallRollback`), объединённая
  `cancelFirewallRollback` не вернулась ни в один вызов;
- `disarm` не удаляет копии;
- порядок в `install` и `reconfigure` одинаков: `disarm` → долговечная запись
  `installed` → `cleanup`;
- успешный smoke фиксируется отдельной фазой до снятия таймера;
- уборка после точки фиксации выполняется best-effort.

## A5e. Транзакционность rollback guard (unit)

`orchestrator/test/firewall-guard.test.ts`:

- маркер `auto-rollback-fired` создаётся rollback-скриптом **первым действием** —
  до проверки `prepared` и до первой попытки восстановления, в том числе когда
  восстанавливать нечего. Без этого «guard сработал» недоказуемо: транзиентные
  юниты systemd после выполнения исчезают, и `systemctl stop` для них неотличим
  от успешного снятия взведённого таймера;
- скрипт не маскирует ошибки (`|| true`, `2>/dev/null`), не использует `set -e`
  и возвращает накопленный `rc`: каждый сообщённый отказ поднимает код возврата,
  поэтому частичное восстановление уходит в `failed`, а не в молчаливый `0`;
- `rc` объявляется **до** создания маркера, а ранний выход возвращает его, а не
  жёсткий `0`. Инвариант фиксации верен только при условии «guard способен
  записать маркер»: пока `rc=0` стояло после, отказ записи (заполненный tmpfs
  `/run`, read-only ФС) не влиял ни на что — скрипт восстанавливал прежний
  firewall, завершался нулём, и операция фиксировала успех после реально
  сработавшего отката. Теперь у факта два канала: маркер и отказ юнита;
- маркер создаётся `touch`, а не `: >file`: двоеточие — special builtin POSIX,
  и ошибка перенаправления на нём обязана завершить неинтерактивный shell
  целиком, то есть в dash скрипт умер бы **до** восстановления firewall;
- поведенчески проверяется ранний путь скрипта — он заканчивается до первой
  команды восстановления и потому безопасен для запуска: при доступном каталоге
  маркер создаётся и выход нулевой, при недоступном — выход ненулевой;
- скрипт не трогает `nftables.service`: у него `ExecStop=nft flush ruleset`, и
  остановка сервиса стёрла бы только что восстановленные правила;
- скрипт разбирается **настоящим** shell-парсером. Парсер принимается только
  после двусторонней проверки — он обязан принять заведомо корректный скрипт и
  отвергнуть заведомо сломанный, иначе тест ничего не проверяет;
- небезопасный ключ операции отвергается: он служит именем каталога, именем
  systemd-юнита и подставляется в текст скрипта;
- снятие guard проверяет маркер **с обеих сторон** остановки, подтверждается
  `ActiveState` обоих юнитов, и на пути фиксации успеха допускает единственное
  состояние — `inactive`; на пути восстановления `failed` тоже допустим;
- сработавший guard опознаётся по **типу** ошибки: ошибка с тем же текстом, но
  другого типа классифицируется по владению, как и прежде;
- эффективный firewall сверяется семантически (фрагмент, entrypoint,
  загруженная таблица), и проверка выполняется read-only раннерами — та же
  проверка идёт в `doctor`;
- состояние `nftables.service` снимается до первой мутации и восстанавливается
  стадиями, идущими **до** применения ruleset;
- candidate-файлы убираются после успеха и best-effort при откате;
- ключ операции считается одной функцией: install писал в маркер сырой
  ISO-timestamp, и путь `/run/hy2xs/rollback/<op_id>` из runbook не существовал;
- команда взведения guard проверяется как **значение**, а не грепом по
  исходнику: `buildArmGuardArgv` возвращает готовый argv, и тест сверяет его
  целиком — имя юнита с явным суффиксом, `--on-active=45s`,
  `--timer-property=AccuracySec=1s`, `--timer-property=RemainAfterElapse=no`.
  Небезопасный ключ операции отвергается до запуска: shell в этой команде не
  участвует, поэтому единственная защита — отказ;
- барьер покоя проверяется **поведенчески**, с подставляемым наблюдателем
  systemd (`SystemdUnitProbe`), без systemd и без Linux:
  - взведённый таймер (`active/waiting`) и идущий прямо сейчас откат
    (`activating`) запрещают операцию с `PendingRecoveryError`;
  - отказ `list-units` **и** отказ `show` на любом отдельном юните дают
    `GuardStateUnknownError`: отсутствие ответа systemd — отсутствие
    наблюдения, а не наблюдение покоя. Прежний тест закреплял обратное
    (`return [];` в тексте функции) и потому пережил инверсию смысла: строка
    была на месте, а решение стало неверным;
  - оба отказа имеют общего предка `OperationBarrierError`;
  - покой — ровно `inactive` и `failed`; `maintenance`, `refreshing` и любое
    незнакомое состояние блокируют операцию, потому что политика перечисляет
    безопасные состояния, а не опасные;
  - `*.timer` в `SubState=elapsed` считается покоем: `TIMER_ELAPSED` в systemd
    отображается в `UNIT_ACTIVE`, и без этой ветки отработавший таймер
    блокировал бы `repair` навсегда. У сервиса тот же `SubState` ничего не
    значит;
  - разбор вывода `list-units` находит имя юнита и когда первой колонкой идёт
    маркер `●` (состояние `failed`) — иначе терялся бы именно аварийно
    сработавший guard.

## A5f. Взаимное исключение операций (unit)

`orchestrator/test/operation-lock.test.ts`:

- второй захват при живом держателе отказывает, и отказ называет держателя —
  команду, PID и время начала;
- замок снимается в `finally` и после отказа операции: иначе первая же неудачная
  установка заблокировала бы сервер до перезагрузки;
- замок мёртвого держателя переиспользуется, временный файл переиспользования не
  остаётся на диске;
- непонятое содержимое замка **не** снимается автоматически: оно не доказывает
  отсутствие операции, и сомнение трактуется в пользу отказа;
- `readLockHolder` отличает «замка нет» от «замок нечитаем»;
- захват под read-only guard отказывает, наблюдение — разрешено. Замок берётся
  до включения guard, и проверка существует, чтобы перенос захвата внутрь
  читающей фазы отказал громко, а не записал файл молча;
- барьер покоя вызывается **дважды** — до захвата и уже под замком, — а отказ
  второй проверки снимает замок за собой. Замок сам по себе гарантии не даёт:
  он защищает production paths, пока жив держатель, а rollback guard переживает
  свой процесс;
- политика CLI закреплена структурно: `install`/`reconfigure`/`repair`/`doctor`
  вызываются только под замком, `status`/`diagnostics` его не берут, но сообщают
  об идущей операции, а `preflight-install` отказывает до собственных проверок.

## A5b. Долговечная запись маркера (unit)

`orchestrator/test/atomic-write.test.ts`:

- содержимое заменяется целиком, а не дописывается поверх прежнего;
- при отказе записи по целевому пути остаётся **прежний полный** документ;
- временный файл не выживает ни при успехе, ни при отказе подстановки;
- права выставляются точно, независимо от umask (`0600`, `0644`);
- `ensureDir` приводит права **существующего** каталога к объявленным: `mkdir`
  этого не делает, поэтому «создать» и «права такие, как объявлено» — два
  разных действия;
- и запись, и создание каталога проходят через read-only guard;
- `persistInstallState` под guard'ом отказывает: единственный писатель маркера
  обязан идти через guarded-примитивы, иначе PHASE 0 смогла бы создать
  `/var/lib/hy2xs`, и «read-only» перестало бы быть правдой ровно для того
  файла, по которому clean-host принимает решение.

- `ensureDir` сообщает, был ли каталог **фактически создан**: родитель
  синхронизируется только при создании, иначе долговечность записи `hy2xs` в
  `/var/lib` осталась бы необеспеченной, и после потери питания мог исчезнуть
  весь каталог вместе с маркером.

Наличие самих `fsync` проверяется приёмкой сборки по исходнику: из
пользовательского процесса их не наблюдать, а без них `rename()` даёт
атомарность видимости без долговечности.

## A6. Редактирование секретов (unit)

`orchestrator/test/redaction.test.ts`:

- machine token не переживает редакцию серверного конфига — регрессия на
  построчное правило `auth:`, оставлявшее нетронутым `auth.http.url`;
- obfs-пароль не переживает редакцию;
- результат остаётся валидным YAML;
- несекретные поля сохраняются: диагностика должна оставаться полезной;
- неизвестное поле с секретоподобным именем вырезается;
- `acme.dns.config` вырезается целиком;
- невалидный YAML не роняет редакцию и всё равно чистится;
- секрет внутри URL-значения в env вырезается, даже если имя ключа несекретное
  (`HY2_AUTH_URL`);
- URL под **произвольным** именем ключа теряет встроенные учётные данные и
  секретные query-параметры, но сохраняет адрес; то же для URL внутри списка;
- `redactLogText` вырезает machine token из строки journald, сохраняя host,
  port и path; ловит секрет и вне URL; не трогает обычные строки; сохраняет
  хвостовую пунктуацию; идемпотентен — регрессия на diagnostics-бандл, где
  редактировались env и YAML, а `journal-admin.log` копировался как есть.

## A7. Machine token в журналах (unit)

`apps/middleware/log_test.go` — запрос
`/internal/hysteria/auth?access_token=SUPER_SECRET_SENTINEL`:

- sentinel **не появляется** в журнале ни в каком виде;
- в журнале есть `reqPath`, поля `reqUri` нет;
- имя query-параметра сохраняется (`reqQueryKeys`), значение — нет;
- пустой список параметров в журнал не пишется;
- то же правило действует на операторских маршрутах, а не только на машинном.

`apps/service/log_sanitize_test.go` — тот же санитайз на стороне админки: журнал
Hysteria покидает сервер через `ExportLog`, а `HY2_AUTH_URL` несёт
`access_token`, который upstream волен упомянуть в сообщении об ошибке.

## A8. Инвариант публичного endpoint (unit)

`orchestrator/test/network-endpoint.test.ts` — проба подменяет и DNS, и список
локальных адресов, поэтому тест не зависит ни от сети, ни от интерфейсов машины
разработчика.

| Сценарий | Результат |
| --- | --- |
| A-запись == текущий публичный IPv4 | PASS |
| A-запись == старый IPv4 | FAIL, в тексте оба адреса |
| A-запись отсутствует | FAIL |
| A == текущий + чужой | FAIL |
| у сервера 2 публичных IP, DNS использует один | PASS |
| `PUBLIC_HOST` — правильный IPv4-литерал | PASS |
| `PUBLIC_HOST` — устаревший IPv4-литерал | FAIL |
| `DOMAIN` совпадает, отдельный `PUBLIC_HOST` устарел | FAIL |
| `PUBLIC_HOST` совпадает, отдельный TLS-домен устарел | FAIL |
| нет ни одного локального публичного IPv4 | FAIL |
| `HY2XS_PUBLIC_ENDPOINT_POLICY` = strict / warn / off | fail / warn / skip |
| отсутствие A-записи при любой политике | FAIL |
| отказ резолвера (SERVFAIL/таймаут/отказ) при любой политике | FAIL, отдельный текст |

Отдельно проверяется классификация IPv4. Список исключений приведён к IANA
Special-Purpose Address Registry: приватные, CGNAT, link-local, multicast,
reserved, benchmarking (`198.18/15`), 6to4-anycast и **документационные**
диапазоны (`192.0.2/24`, `198.51.100/24`, `203.0.113/24`) не считаются
публичным адресом сервера. Регрессия: `203.0.113.5` из RFC-примеров раньше
проходил проверку как обычный публичный адрес. Границы проверяются с обеих
сторон — `172.32.0.0`, `192.0.1.1`, `198.20.0.1` и `203.0.112.255` считаются
публичными.

Отказ резолвера отделён от отсутствия записи: `ENODATA`/`ENOTFOUND`/`NXDOMAIN`
— это «нет A-записи» и чинится в DNS-панели, всё остальное — «резолвер не
ответил» и чинится в `/etc/resolv.conf`. Раньше оба случая печатались как
«has no A-record», и при сломанном резолвере оператор шёл править запись,
которая была на месте. Фатальны оба: без ответа резолвера проверка не выполнена,
а не «выполнена с замечанием».

## A9. Регистрация маршрутов (unit)

`apps/router/router_test.go` — единственное место, где ошибка проявляется
**паникой при старте сервиса**, а не ответом с кодом. Конфликт с
wildcard-маршрутом фронтенда или дублирующая регистрация обнаружились бы иначе
только на живом сервере.

- контур маршрутов собирается без паники;
- machine-auth зарегистрирован ровно на `constant.HysteriaMachineAuthPath`;
- операторский и auth API — под `constant.AdminAPIBase`;
- ни один маршрут не начинается со старого пространства имён;
- удалённые маршруты (включая `exportConfig`/`importConfig` и `getConfig`) не
  вернулись;
- пространство `/api/config` закрыто: в нём ровно четыре маршрута, и любой
  новый обязан быть добавлен в тест осознанно;
- `/healthz` на месте.

## A9a. Доступ к таблице `config` (unit)

`apps/model/constant/config_test.go` — allowlist как структура, а не как
соглашение:

- ни один внутренний ключ не читается и не записывается через API;
- `JWT_SECRET`, `PEER_SECRET_KEY`, `PEER_SECRET_ENCRYPTION_KEY` и
  `HYSTERIA2_TRAFFIC_STATS_SECRET` поимённо объявлены внутренними;
- пользовательские настройки остаются доступными;
- множество записываемых ключей — подмножество читаемых;
- неизвестный ключ закрыт **по умолчанию**: забытый при denylist ключ был бы
  сразу публичным.

`apps/controller/config_test.go` — то же на уровне HTTP:

- чтение и запись каждого секрета отклоняются;
- секрет, спрятанный среди разрешённых ключей, отклоняет весь запрос;
- отказ наступает **до** обращения к базе (тест работает без SQLite — сам факт,
  что обработчик не падает, это и доказывает);
- ключи оркестратора отклоняются с указанием владельца, а не общим «нет такого
  ключа»: оператор должен быть отправлен к `hy2xs-orchestrator reconfigure`;
- удалённые ключи (`HYSTERIA2_ENABLE`, `HYSTERIA2_CONFIG`,
  `HYSTERIA2_TRAFFIC_TIME`, `HYSTERIA2_CONFIG_REMARK`) отклоняются как
  неизвестные — проверка идёт по строковым литералам, потому что соответствующих
  констант в коде уже нет и появиться они не должны.

Атомарность партии проверяется на **настоящей** SQLite: без базы утверждение
«партия не применилась частично» бессмысленно, поскольку предметом утверждения
является именно состояние базы.

- разрешённый ключ первым, запрещённый вторым → запрос отклонён, значение
  первого ключа в базе **не изменилось**;
- невалидное cron-выражение → отказ, значение в базе не изменилось;
- один ключ дважды в партии → отказ (какое из двух значений считать намерением
  оператора, определить нельзя);
- корректная партия → значение сохранено, расписание применено к планировщику,
  число его записей не выросло.

Порядок в первом тесте принципиален. Предыдущая версия ставила запрещённый ключ
**первым** и до второго элемента не доходила, поэтому проходила и на реализации,
которая проверяла и записывала настройки в одном цикле.

## A9b. Планировщик (unit)

`apps/service/cron_scheduler_test.go` — планировщик как собственность процесса:

- четыре последовательные смены расписания **не увеличивают** число записей
  планировщика (главная регрессия: раньше каждая смена добавляла целый
  дублирующий набор джоб, а старое расписание продолжало работать);
- пустое выражение снимает джобу сброса, непустое возвращает её — без
  перезапуска процесса;
- невалидное выражение не меняет планировщик и не снимает действующую джобу;
- набор валидных и невалидных выражений проверяется тем же парсером, что и
  runtime: то, что `cron` умеет, обязано приниматься, остальное — отклоняться;
- невалидное значение в базе **не роняет старт**: на панели висит
  `/internal/hysteria/auth`, и отказ старта из-за строки расписания положил бы
  подключения пользователей. Фиксированные джобы поднимаются, сброс отключён,
  в журнале ERROR, и настройка чинится через API без перезапуска;
- второй `InitCron` поверх работающего отклоняется;
- `StopCron` идемпотентен и оставляет планировщик пустым.

## A9c. Токены и пароли (unit)

`apps/service/jwt_test.go`:

- round-trip: claims, включая `token_version`, переживают выписку и разбор;
- токен, подписанный **другим** HMAC-алгоритмом тем же ключом, отклоняется
  (прежний `keyfunc` не смотрел на `token.Method` вовсе);
- токен без `exp` отклоняется, истёкший отклоняется отдельным сообщением;
- токен с чужим `issuer` отклоняется даже при совпадении ключа;
- пустой `JWT_SECRET` — отказ и на выписку, и на разбор, а не подпись ключом
  нулевой длины.

`apps/util/encrypt_test.go`:

- `HashPassword` выдаёт bcrypt и солит: два хеша одного пароля различаются;
- вход по несолёному SHA-224 (формат предыдущего поколения) **невозможен**;
- любая не-bcrypt строка в поле хеша отклоняется.

`apps/util/rand_test.go` — отсутствие modulo bias: на выборке 200 000 символов
частоты первых восьми символов алфавита не отличаются от остальных более чем на
5%. Прежняя реализация давала здесь отношение 1.25.

## A9d. Пир установщика (unit)

`apps/service/peer_bootstrap_guard_test.go` — защита действует во всех путях
записи, а не только в импорте:

- смена секрета и переименование `bootstrap-admin-peer` отклоняются, состояние
  в базе не меняется;
- переименование обычного пира в зарезервированное имя отклоняется;
- создание пира с зарезервированным именем отклоняется;
- отключение и изменение квоты **разрешены**;
- удаление **разрешено**: это осознанное действие оператора, и расхождения
  между базой и `bootstrap-admin.secret` оно не создаёт.

## A9e. Жизненный цикл пира установщика (unit, настоящая SQLite)

`apps/dao/bootstrap_peer_test.go` — проверяется не функция, а поведение сервиса
при перезапуске: дефект, ради которого написан этот файл, проявлялся только на
ВТОРОМ запуске, поэтому каждый тест прогоняет полную последовательность
`InitSqlAt` дважды на одной базе.

- первый запуск создаёт пира и выставляет отметку `BOOTSTRAP_PEER_SEEDED`;
- обычный перезапуск не пересоздаёт пира и не плодит дублей (`id` тот же,
  запись ровно одна);
- **удаление переживает перезапуск**: после `DELETE` и рестарта пир не
  возвращается, хотя `HY2XS_ADMIN_CON_PASS` остаётся в окружении;
- то же после трёх перезапусков подряд;
- отключённый пир сохраняет `disabled = 1` и свой `secret_digest`;
- отметка и пир пишутся одной транзакцией: при конфликте `UNIQUE(name)` внутри
  транзакции отметка не остаётся выставленной;
- отсутствие `HY2XS_ADMIN_CON_PASS` на чистой базе — отказ старта;
- перезапуск установленного сервиса без этой переменной проходит штатно;
- `HYSTERIA2_TRAFFIC_STATS_SECRET`: пустой env при пустой базе — отказ старта,
  сгенерированного токена в базе не появляется; токен, уже согласованный
  ранее, принимается без переменной.

## A9f. Резервная копия пиров (unit)

`apps/service/peer_export_backup_test.go`:

- `includeSecrets=true` на исправных данных отдаёт секрет каждого пира;
- нерасшифровываемый секрет хотя бы одного пира отклоняет **весь** запрос,
  сообщение называет пира, частичное содержимое не возвращается;
- пир вовсе без шифртекста — тот же отказ;
- `includeSecrets=false` повреждённых данных не замечает и пустой `secret`
  отдаёт штатно: это и есть смысл безопасного режима.

## A9g. Слой данных: «нет записи» против «база не ответила» (unit)

`apps/dao/config_test.go`:

- `UpdateConfig` по отсутствующей строке — **отказ**, а не тихий успех: UPDATE
  без совпавших строк не является ошибкой SQL, и раньше оператор получал
  подтверждение изменения, которого не произошло, а планировщик тут же получал
  новое расписание;
- `UpdateConfig` не создаёт строк: это работа `UpsertConfigValue`;
- транзакционная партия откатывается целиком, если одна из строк отсутствует;
- `GetConfig`/`GetPeer` возвращают `ErrConfigNotFound`/`ErrPeerNotFound`,
  отличимые через `errors.Is` от `ErrStorage`.

`apps/cmd/reset_test.go` — единственный оставшийся потребитель, который склеивал
эти два ответа:

- на пустой базе `reset-admin` создаёт учётную запись, bcrypt-хеш подходит к
  напечатанному паролю, `force_password_change` выставлен;
- поверх существующей записи обновление идёт **на месте**: тот же `id`, новый
  пароль, увеличенный `token_version`, прежний пароль больше не действует;
- при отказе чтения (`ErrStorage`) сброс **останавливается**: вторая учётная
  запись не создаётся, существующая не меняется, напечатанный пароль не
  действует. База в этом тесте полностью работоспособна — воспроизводится ровно
  транзиентный отказ («database is locked»), при котором прежний код уходил в
  ветку создания и оставлял на сервере вторую рабочую учётку с уже
  напечатанным паролем;
- при `ErrAdminUserNotFound` создание по-прежнему выполняется: строгость к
  отказу хранилища не имеет права сломать штатный путь восстановления;
- непригодный для bcrypt пароль останавливает сброс, а не пишет пустую строку
  в `password_hash` — раньше ошибка хеширования проглатывалась
  (`hash, _ := util.HashPassword(...)`), и команда восстановления доступа
  молча его отбирала: `VerifyPassword` отклоняет всё, что не bcrypt;
- sentinel'ы разных таблиц несут одинаковый текст (`WrongPassword` уезжает в
  ответ Hysteria и менять его нельзя), поэтому проверяется именно
  различимость через `errors.Is`, а не по строке.

## A10. Импорт пиров (unit)

`apps/service/peer_import_test.go`:

- выгрузка, сделанная `ExportPeer`, принимается без правок;
- имя проверяется теми же правилами, что и при обычном создании пира: длина,
  набор символов, отсутствие пробелов и переводов строки;
- `bootstrap-admin-peer` не может быть импортирован ни по имени, ни по `authId`:
  его секрет продублирован в `/etc/hy2xs/bootstrap-admin.secret`;
- диапазоны `quotaBytes`, `expiresAt`, `maxDevices`, `disabled`, `bannedUntil`,
  счётчиков трафика и длины секрета проверяются;
- sentinel-значения (`quotaBytes = -1`, `maxDevices = 0`) остаются валидными;
- дубликаты имени и `authId` внутри одной партии отклоняются;
- партия сверх лимита отклоняется;
- невалидная **последняя** запись отклоняет весь файл: импорт применяется
  целиком или не применяется вовсе.

`apps/service/peer_import_tx_test.go` — та же гарантия уже на уровне базы, на
настоящей SQLite. Валидация не даёт применить испорченный файл, но она ничего
не говорит о конфликте с тем, что УЖЕ лежит в базе:

- валидная партия применяется целиком;
- **cross-conflict откатывается полностью**: пусть в базе есть
  `A(auth_id=aaa, name=alice1)` и `B(auth_id=bbb, name=bob123)`, а файл несёт
  `(auth_id=aaa, name=bob123)` — поиск найдёт A по `auth_id` и попытается
  переименовать её в `bob123`, прямо в `UNIQUE(name)`. Записи, шедшие в файле
  до конфликтной, не должны остаться применёнными. Тест дополнительно
  убеждается, что отказ пришёл **из базы**, а не из валидации;
- дубликат `auth_id` на вставке ведёт себя так же;
- отказ валидации не доходит до базы вовсе;
- пир установщика защищён и внутри транзакции;
- обновление без секрета в файле не перезаписывает существующий секрет.

`apps/controller/peer_test.go` — разбор загруженного файла:

- файл с **хвостовым** JSON-документом отклоняется: `json.Decoder` читает первый
  документ и останавливается, поэтому раньше оператор видел «импорт выполнен»,
  а вторая половина файла молча не применялась;
- неизвестные поля и файл не с расширением `.json` отклоняются;
- корректный одиночный документ доходит до базы и создаёт пира.

## A7. Контракт версий (build)

Шаг `verify_versions_contract` (`tools/build/lib/versions.sh`) роняет сборку до
создания tarball при рассинхроне `versions.env` с `PACKAGE_VERSION`,
`packageManager` обоих `package.json`, схемой в `package/config/hy2xs.env`,
константами, скомпилированными в оркестратор, директивой `go` в `apps/go.mod`,
metadata пакета и версией, которую сообщает собранный `hy2xs-admin`.

Разбор upstream `hashes.txt` покрыт `orchestrator/test/hysteria-release.test.ts`:
реальный формат релиза, отсутствие путаницы `hysteria-linux-amd64` с
`hysteria-linux-amd64-avx`, форма `sha256:<hex>`, верхний регистр,
противоречивые записи, отсутствие нужной строки.

## A11. Проверка зависимостей на уязвимости (build)

`tools/build/lib/security.sh` — обязательный шаг между тестами админки и записью
metadata. Подробности в [docs/02](02-build-layer-and-package.md); здесь важно
поведение при отказе:

| Код `govulncheck` | Трактовка |
| --- | --- |
| `0` | чисто |
| `3` | найдены **вызываемые** уязвимости → сборка падает |
| иное | отказ самого инструмента → сборка падает отдельным сообщением |

Последняя строка существенна: ненулевой код неизвестной природы нельзя
трактовать как «уязвимостей нет». По той же причине недоступность реестра npm
для `pnpm audit` — это отказ проверки, а не её отрицательный результат.

`pnpm audit` проверяет **весь** lock-граф frontend, а не production-подграф:
build tooling исполняется на build-машине и порождает production-бандл, поэтому
уязвимость в нём уезжает в артефакт. Приёмка сборки следит, чтобы `--prod` не
вернулся в гейт.

## A11a. Обязательные тесты (build)

Гейт тестов устроен так же, как гейт зависимостей: аварийного выхода нет,
результат виден по готовому артефакту.

| Шаг сборки | Что запускается |
| --- | --- |
| `run_orchestrator_tests` | `bun x tsc --noEmit`, `bun test` |
| `bundle_ui` | `pnpm run typecheck` до сборки bundle |
| `run_admin_tests` | `go vet ./...`, `go test ./...` |

Приёмка проверяет:

- отключающей тесты переменной нет ни в одном модуле сборки, ни в README/docs
  (место для истории — `CHANGELOG.md`);
- `metadata/package.env` содержит `tests_gate=true`;
- утверждение о прогоне выставляется **после** самого прогона, а не до него;
- `write_metadata` отказывается писать метаданные, если хотя бы один из двух
  прогонов не подтверждён.

## A12. Приёмка проверяет код, а не упоминания

Два контракта приёмки на снимке до этого патча **гарантированно роняли сборку на
корректном коде**, и оба — по одной причине: они искали подстроку там, где
подстрока обязана присутствовать.

| Проверка | Что ловила на самом деле |
| --- | --- |
| `verify_api_namespace_contract` | `grep -rlF '/hui'` возвращал `apps/router/router_test.go` (регрессионный тест, который ПЕРЕЧИСЛЯЕТ legacy-префикс, чтобы доказать его отсутствие) и сам `versions.sh`, где эта строка стоит в тексте проверки |
| «peer import не выходит за транзакцию» | `source.slice(start)` брал файл от начала `applyPeerImportEntry` **и до конца**, захватывая `ExistPeerName` и `UpdatePeerLastConnectionAt` — обычные операции вне импорта, которым глобальное соединение положено |

Первая падала на шаге versions contract — шестым из четырнадцати, до резолва
Hysteria. Вторая не была замечена только потому, что сборка до неё не доходила.

Отсюда правило и помощники `code_without_comments` / `code_mentions_in` в
`acceptance.sh`: проверка смотрит на код, а комментарий, объясняющий, почему
чего-то больше нет, обязан называть это по имени и не должен ломать сборку.
Отсутствие legacy-маршрута доказывает не `grep` по исходникам, а
`TestRouterHasNoLegacyNamespace` на таблице маршрутов собранного роутера —
и существование этого теста само проверяется контрактом.

## B. Target install tests

### На чистом Debian 13 проверяем
1. пакет запускается без ручной сборки на сервере
2. Hysteria2 скачивается с official upstream
3. bundled HY2XS admin раскладывается локально из пакета
4. создаются нужные каталоги
5. создаются systemd unit-файлы
6. создаются `hy2xs.env` и `post-install.env` с правами `0600 root:root`
7. baseline firewall применяется корректно через staged mode
8. SSH остаётся доступным
9. `reconfigure --dry-run` выводит план изменений
10. `reconfigure --apply` применяет изменения и проходит smoke

## C. Runtime tests

1. `hysteria-server` active
2. `hy2xs-admin` active
3. Hysteria слушает только IPv4 (`0.0.0.0:<udp_port>`)
4. HY2XS admin слушает ожидаемый `HY2XS_UI_BIND_HOST:<ui_port>`
5. тестовый совместимый клиент подключается
6. идёт реальный трафик
7. лимит 50/50 Mbps соблюдается при согласованной клиентской конфигурации
8. reboot не ломает baseline
9. Hysteria2 управляется systemd unit, а не внутренним updater'ом admin panel
10. нет IPv6 listen (`[::]`) для Hysteria/HY2XS admin
11. `trafficStats.secret` не равен `JWT_SECRET`
12. bootstrap admin secret существует и имеет `0600`
13. `trafficStats` API: корректный secret принимает запрос, неверный secret отклоняется
14. TLS mode в `config.yaml` соответствует runtime env (`acme|file|self_signed_dev`)
15. при `HY2XS_TLS_MODE=acme` в `config.yaml` выставлен `acme.type` из `HY2XS_ACME_TYPE`
16. direct `hysteria2://` node URL в API/QR формируется по `HY2XS_PUBLIC_HOST` + `HY2XS_PUBLIC_PORT`; subscription delivery endpoint отключён в baseline и не входит в acceptance
17. `nft -c -f /etc/nftables.conf` проходит после apply
18. пароль admin и `con_pass` не перезаписываются при рестарте `hy2xs-admin`
19. остановка/рестарт UI не останавливает `hysteria-server`
20. traffic accounting/kick ориентируются на systemd status; ключа `HYSTERIA2_ENABLE` в базе больше нет
21. `/etc/hysteria/config.yaml` имеет `0640 hysteria:hy2xs-admin`
22. `hy2xs-admin` может читать `/etc/hysteria/config.yaml`, но не может писать
23. смена расписания сброса трафика применяется **без** перезапуска `hy2xs-admin`, и число джоб планировщика не растёт
24. невалидное cron-выражение отклоняется API, а значение в базе не меняется
25. `systemctl restart hy2xs-admin` завершает сервис штатно: планировщик остановлен до закрытия SQLite, в журнале нет `database is closed`
26. `govulncheck ./...` на графе релиза не находит вызываемых уязвимостей

## C1. Семантический smoke конфига

Недостаточно `grep` по YAML: он не отличит нужное поле от такой же строки в другой секции и не заметит оставшийся рядом лишний подблок.

Smoke разбирает `/etc/hysteria/config.yaml` и сверяет с production-профилем:

```text
effective Hysteria version == версия из metadata пакета

obfs:
  type == HY2XS_HYSTERIA_OBFS_TYPE
  ровно один подблок, соответствующий type
  password непустой
  для gecko: minPacketSize == 512, maxPacketSize == 1200

bandwidth:
  up/down == runtime env
  disableLossCompensation == false

congestion:
  type == bbr
  bbrProfile == standard

quic:
  disableStatelessReset == false
  окна, maxIncomingStreams, disablePathMTUDiscovery == baseline
  maxIdleTimeout == 30s

trafficStats:
  listen == runtime env
  secret непустой

auth:
  type == http
  url == http://127.0.0.1:<UI_PORT>/internal/hysteria/auth?access_token=<machine token>
  insecure == (tlsMode == self_signed_dev)

TLS:
  acme-режим не содержит секции tls
  acme: type/email/ca/dir/listenHost/первый домен == профиль
  file-режим не содержит секции acme

верхний уровень:
  нет секций вне production-профиля
```

`maxIdleTimeout` присутствовал в профиле, но не проверялся: конфиг с уехавшим
idle timeout проходил семантическую проверку. Точно так же `auth.http.url`
раньше сверялся только на наличие подстроки `access_token=`, из-за чего
уехавший порт или путь остались бы незамеченными — а это единственный канал
допуска пиров.

Сообщение об ошибке для `auth.http.url` намеренно не печатает сам токен: текст
уходит в логи и в diagnostics-бандл. Это закреплено отдельным тестом.

## C2. End-to-end с реальным клиентом

`tools/test/e2e-hysteria.sh`, отдельно для Gecko и Salamander:

1. сервер принимает сгенерированный конфиг и стартует;
2. TLS handshake;
3. handshake с обфускацией;
4. HTTP auth HY2XS: разрешённый пир принят;
5. HTTP auth HY2XS: неразрешённый пир отклонён;
6. клиент подключается **именно по ссылке, которую выдаёт production-код**;
7. TCP forwarding;
8. UDP forwarding;
9. `trafficStats` с валидным secret;
10. `trafficStats` с невалидным secret отклоняется;
11. per-peer accounting содержит аутентифицированного пира;
12. перезапуск сервера;
13. быстрое переподключение клиента (поведение stateless reset).

Пункт 6 — тот самый, который ловит класс ошибок, неизбежный при наивном включении Gecko: сервер работает, ссылка формально валидна, а клиент по ней не подключается.

### Одна реализация URI, а не две

Ссылка берётся из production-генератора через `apps/tools/share-uri`, который
вызывает ту же `service.BuildHysteria2ShareURI`, что и панель.

Раньше внутри e2e жила **вторая** реализация URI на bash. Go-юнит-тесты
проверяли production-генератор, e2e проверял свою функцию — и дрейф любой из
них оставлял обе группы тестов зелёными.

Единственное расхождение с пользовательской ссылкой — `insecure=1`: e2e
работает на самоподписанном сертификате. Это расхождение ограничено с двух
сторон:

- e2e отдельно печатает и проверяет **production-вариант** ссылки
  (`insecure=0`, корректные `obfs` и `sni`);
- Go-тест `TestBuildHysteria2ShareURI_InsecureDiffersOnlyInThatParam`
  доказывает, что кроме этого параметра ссылки совпадают побайтово;
- Go-тест `TestBuildHysteria2Url_ProductionPathNeverDisablesVerification`
  фиксирует, что production-путь никогда не передаёт `insecure=1`.

Для запуска e2e нужен Go (`GO_BIN`).

## C3. Share URI (unit)

`apps/service/hysteria2_api_test.go`:

- Gecko URI содержит `obfs=gecko` и `obfs-password`;
- Salamander URI содержит `obfs=salamander` и `obfs-password`;
- конфиг без обфускации даёт ссылку без `obfs`;
- неизвестный тип обфускации в ссылку не попадает;
- обфускация без пароля в ссылку не попадает;
- SNI: ACME-домен → `HY2XS_DOMAIN` → `HY2XS_PUBLIC_HOST`, IP не используется;
- спецсимволы в credentials и obfs-пароле переживают round-trip: `+`, пробел, `#`, `@`, `/`, `?`, `&`, `=`, `%`, кириллица;
- литеральный `+` кодируется как `%2B` и не схлопывается с пробелом (регрессия на upstream-баг 2.9.3).

## C4. Экспорт конфига (unit)

`apps/service/hysteria2_export_test.go`:

- неизвестные upstream-секции переживают экспорт целиком, включая вложенные карты и списки;
- операционные поля остаются читаемыми;
- вырезаются: obfs-пароль, `trafficStats.secret`, `access_token`, `auth.userpass`, учётные данные ACME DNS, пароли outbound;
- вырезается **неизвестное** поле с секретным именем;
- URL под произвольным именем ключа (`endpoint:`) теряет учётные данные и
  `access_token`, но сохраняет адрес; то же для URL внутри списка;
- не-URL скаляры (`50 mbps`, `0.0.0.0:443`, `10.0.0.1:1080`, `30s`, числа)
  проходят санитайзер без изменений;
- пути к файлам (`tls.key`, `ech.keyPath`, `clientCA`) остаются видимыми.

Го- и TS-санитайзеры описывают один контракт и покрыты зеркальными тестами:
граница определяется значением, а не именем ключа.

## D0. Граница установки на живом сервере

Проверяется на хосте, где уже стоит предыдущая установка:

1. `install.sh` завершается отказом на PHASE 0;
2. `/usr/local/lib/hy2xs` **не создан и не изменён**;
3. `/var/lib/hy2xs/install-state.json` не перезаписан;
4. `hysteria-server` и `hy2xs-admin` остались `active`;
5. в тексте отказа перечислены найденные маркеры и указан
   `docs/14-legacy-cleanup.md`;
6. после `tools/legacy/purge-v0.sh --apply --yes-i-know` установка проходит.

Пункты 2–4 — прямая регрессия: прежний установщик успевал переписать
`/usr/local/lib/hy2xs` и `install-state.json`, а затем откатом останавливал и
выключал работающие службы старой установки.

## D1. Отказ сразу после успешной PHASE 0 (fault injection)

Проверяется на чистом хосте. Это узкая щель между «PHASE 0 прошла» и «первая
мутирующая операция упала» — место, где установщик раньше врал.

1. PHASE 0 проходит успешно;
2. `installDeps` ломается искусственно (например, недоступный apt-репозиторий
   или временно испорченный `/etc/apt/sources.list.d/`);
3. установка завершается отказом;
4. в выводе **нет** `fatal_pre_apply` и нет фразы про «ничего не применялось»;
5. `/var/lib/hy2xs/install-state.json` существует и честно показывает
   `phase: failed` с текстом ошибки;
6. `owned_paths` в маркере содержит `/usr/local/lib/hy2xs`,
   `/usr/local/bin/hy2xs-orchestrator` и `/usr/local/lib/hy2xs/package` —
   всё, что операция действительно создала;
7. diagnostics-бандл собран;
8. `hy2xs-orchestrator status` не заявляет установку успешной.

До исправления шаги 4–7 давали противоположный результат: `install-state.json`
уже лежал на диске, но отказ классифицировался как pre-apply, обработка
состояния пропускалась, а следующая установка на этой машине отказывалась по
clean-host контракту из-за оставшегося маркера.

Пункт 6 закрывает вторую половину той же щели. Пока раскладку оркестратора и
runtime-пакета выполнял `install.sh`, эти пути не принадлежали никому: они не
попадали в `owned_paths`, а отказ **второго** preflight (сменился DNS, занялся
порт, не ответил резолвер) объявлялся `fatal_pre_apply` — «на сервере ничего не
изменено» — при уже созданном каталоге оркестратора.

## D1b. Откат при невозможности записать состояние отказа (fault injection)

Проверяется на чистом хосте. Это доказательство того, что телеметрия состояния
больше не стоит перед восстановлением.

**Тайминг здесь — часть сценария, и его легко испортить.**

`tmpfs` НЕЛЬЗЯ монтировать заранее: первая же запись маркера (`preflight_ok`)
получит `ENOSPC`, установка отвалится до firewall, и проверяться будет совсем
другой путь — обычный `fatal_post_apply` на ранней стадии.

Порядок строго такой:

1. запустить установку и дождаться в журнале `step=firewall status=done`;
2. **только теперь**, во втором терминале:

```bash
mount -t tmpfs -o size=16k tmpfs /var/lib/hy2xs
dd if=/dev/zero of=/var/lib/hy2xs/filler bs=1k count=64 2>/dev/null || true
```

3. вызвать искусственный отказ следующего шага установки.

Ловить это окно руками неудобно, поэтому тот же сценарий имеет смысл прогнать и
через отказ на более длинном шаге (`smoke`), где времени заметно больше:
дождаться `step=smoke checks`, смонтировать `tmpfs` и остановить один из
сервисов, чтобы smoke не сошёлся.

Сценарий:

1. установка доходит **дальше** шага firewall (то есть `firewallTouched`
   взведён, правила применены);
2. следующий шаг ломается искусственно;
3. запись `phase: failed` в маркер падает по `ENOSPC`;
4. в журнале есть `failed to persist failure state, continuing with the
   mandatory rollback`;
5. **откат всё равно выполняется**: `rollbackFirewallNow` снимает применённые
   правила, `/etc/nftables.conf` возвращается к прежнему состоянию, а
   развёрнутые этой операцией юниты останавливаются и выключаются;
6. SSH остаётся доступным;
7. в журнале перечислены отказавшие стадии отката, если они были, и наружу
   ушла **исходная** ошибка операции, а не `ENOSPC`.

До исправления шаги 4–6 давали противоположный результат: бросок из записи
состояния уносил управление наружу, и сервер оставался с применённым firewall
неудавшейся установки.

Тот же сценарий повторяется для `reconfigure`, где цена выше: там откат
дополнительно возвращает конфиги из `/etc/hy2xs/backups`, и оба восстановления
отменялись разом.

Дополнительно проверяется независимость стадий: если сделать неработоспособной
первую стадию (например, сделать `/etc/nftables.conf` неперезаписываемым через
`chattr +i` между применением firewall и отказом), восстановление конфигов и
остановка сервисов обязаны выполниться всё равно, а в журнале обязаны появиться
`rollback stage "…" failed, continuing with the remaining stages` и итоговое
`rollback finished with N failed stage(s)`.

## D1c. Данные отката переживают отказ фиксации успеха

Проверяется на чистом хосте. Это второй сценарий того же класса, но на
противоположном конце операции: отказывает не промежуточный шаг, а **запись
успеха**.

1. установка доходит до успешного `smoke`, в маркере появляется
   `phase: smoke_ok`;
2. сразу после этого `/var/lib/hy2xs` делается недоступным для записи (тот же
   `tmpfs`, смонтированный по появлению `step=smoke checks status=done`);
3. запись `phase: installed` падает;
4. `/run/hy2xs/rollback/<op>/prepared` и обе резервные копии firewall **всё ещё
   существуют** — это и есть проверяемое свойство;
5. откат выполняется полностью: `/etc/nftables.conf` возвращается к прежнему
   содержимому, развёрнутые юниты останавливаются;
6. в журнале **нет** строки `no HY2XS rollback markers found`.

До исправления пункты 4–6 давали противоположный результат: снятие таймера и
удаление копий выполнял один вызов, стоявший до записи `installed`, поэтому
откат запускался, но откатывать ему было нечем.

Обратная проверка — успешный путь: после нормально завершённой установки
`/run/hy2xs/rollback/` пуст, а `phase: installed` записан.

## D1d. Отказ снятия резервной копии останавливает reconfigure до мутации

Проверяется на рабочей установке.

1. `/etc/hy2xs/backups` делается недоступным для записи (`chattr +i` или
   заполненный `tmpfs`);
2. запускается `reconfigure --apply`;
3. операция отказывает на шаге `backup` с сообщением про несозданную копию;
4. `/etc/hysteria/config.yaml`, unit-файлы и `/etc/nftables.conf` **не
   изменены**, сервисы не перезапускались.

Отдельно проверяется привязка копии к операции: после успешного `reconfigure`
в `/etc/hy2xs/backups/` остаётся ровно один каталог — текущей операции — с
`manifest.json`, и в нём перечислены все семь путей, включая отсутствовавшие с
`"present": false`.

## D1e. Guard доходит до дедлайна — фиксация успеха запрещена

Проверяется на чистом хосте. Это сценарий гонки между автоматическим откатом
firewall и успешным smoke.

Окно guard — 45 секунд, и оно намеренно короче худшего случая smoke: на
медленном, но исправном сервере retry-бюджеты дают заметно больше. Раньше это
означало, что автоматический откат мог вернуть прежний firewall, пока smoke
продолжает идти, а единственной проверкой firewall в smoke был `nft -c` — разбор
текущего файла, каким бы он ни был. Прежний валидный ruleset проходил её
зелёным, и сервер объявлялся успешно настроенным с **предыдущим** firewall.

Сценарий:

1. установка доходит до шага `firewall`, в журнале появляется
   `firewall rollback guard armed: … fires in 45s (timer accuracy 1s)`.
   Пока guard ждёт, свойства таймера проверяются напрямую — обещанное окно
   обязано быть контрактом systemd, а не намерением:

   ```bash
   systemctl show hy2xs-fw-rollback-<op-id>.timer \
     -p ActiveState -p SubState -p AccuracyUSec -p RemainAfterElapse
   ```

   Ожидается `ActiveState=active`, `SubState=waiting`, `AccuracyUSec=1s`,
   `RemainAfterElapse=no`. Без явной точности systemd вправе сработать в окне
   `[45s; 45s + AccuracySec]`, а умолчание `AccuracySec=` — одна минута, то
   есть реальное окно было бы 45–105 секунд;
2. smoke искусственно замедляется дольше 45 секунд. Проще всего задержать один
   из сервисов — например, добавить в `hy2xs-admin.service` временный
   `ExecStartPre=/bin/sleep 60` и выполнить `systemctl daemon-reload` до запуска
   установки;
3. guard срабатывает: в journal появляется юнит
   `hy2xs-fw-rollback-<op-id>.service`, а на диске —
   `/run/hy2xs/rollback/<op-id>/auto-rollback-fired`;
4. установка **обязана** завершиться отказом, даже если smoke успел сойтись;
5. в маркере установки стоит `phase: firewall_guard_fired`, а не
   `installed`, и не `smoke_failed`;
6. `installed: true` не записан;
7. выполняется обычный откат операции: firewall возвращается к прежнему
   состоянию, развёрнутые этой операцией юниты останавливаются;
8. SSH остаётся доступным.

Отдельно проверяется вторая половина того же дефекта — семантический smoke.
Если на рабочей установке подменить `/etc/nftables.d/hy2xs.nft` на прежний
валидный ruleset и выполнить `hy2xs-orchestrator doctor`, диагностика обязана
отказать с сообщением про несовпадение эффективного firewall, а не пройти по
`nft -c`.

## D1f. Конкурентная операция отказывает до первой мутации

Проверяется на рабочей установке. Проверяемое свойство — отказ происходит
**до** снятия резервной копии и до первой мутации, а не в середине транзакции.

1. запускается длинный `reconfigure --apply` (например, с задержкой в
   `ExecStartPre`, как в D1e);
2. во втором терминале, пока первый идёт, запускается второй
   `reconfigure --apply`;
3. второй отказывает сразу, с текстом
   `another HY2XS operation is already in progress: reconfigure (pid …)`;
4. `/etc/hy2xs/backups/` **не** пополнился каталогом второй операции;
5. `/etc/hysteria/config.yaml`, unit-файлы и `/etc/nftables.conf` изменены
   ровно один раз — первой операцией;
6. `/run/hy2xs/rollback/` содержит каталог только первой операции.

Те же проверки для пар:

```text
install  идёт  ->  doctor            отказывает
install  идёт  ->  install.sh        отказывает на PHASE 0, до собственных проверок
reconfigure идёт -> repair           отказывает
```

И обратная проверка — наблюдающие команды не блокируются:

```text
reconfigure идёт -> hy2xs-orchestrator status
  → выполняется
  → в отчёте operation_in_progress = "reconfigure (pid …)"
  → human_status предупреждает, что это снимок незавершённой транзакции

reconfigure идёт -> diagnostics collect
  → выполняется
  → в stderr есть note об идущей операции
```

Отдельно проверяется, что замок не переживает своего держателя. **Важно:**
прерывать операцию нужно ДО шага `firewall`, иначе проверяется уже сценарий
D1h, а не этот.

1. `reconfigure --apply` прерывается `Ctrl+C` на шаге `config generation` —
   замок снят, следующий `reconfigure` проходит;
2. процесс убивается `kill -9` на том же шаге, после чего следующая операция
   сообщает `is held by … which is no longer running; reclaiming it` и
   продолжает;
3. `/run/lock/hy2xs-orchestrator.lock` не остаётся после завершения операции.

## D1h. Аварийно умершая операция с вооружённым guard

Проверяется на рабочей установке. Это стык двух защитных механизмов, и до его
закрытия каждый из них по отдельности работал правильно, а вместе они
оставляли дыру.

Замок защищает production paths, пока **жив процесс-держатель**. Rollback guard
firewall — отдельный systemd-объект, который свой процесс переживает. Поэтому:

```text
A берёт замок -> применяет firewall -> вооружает guard на 45 секунд
A аварийно умирает
B берёт замок (снятый обработчиком сигнала либо переиспользованный)
B начинает менять production paths
guard A срабатывает и возвращает firewall, который был ДО A
```

Уникальные `op-id` здесь не помогают: каталоги копий разные, а
`/etc/nftables.conf`, `/etc/nftables.d/hy2xs.nft` и ruleset в ядре — общие.

Сценарий:

1. `reconfigure --apply` доводится до появления в журнале
   `firewall rollback guard armed`;
2. процесс убивается `kill -9` (замок остаётся устаревшим) — и, отдельным
   прогоном, `kill -TERM` (замок снимается обработчиком, то есть его вообще не
   будет; это и есть случай, который проверка живости держателя не ловит);
3. **до истечения 45 секунд** запускается `repair` или `reconfigure --apply`;
4. новая операция обязана отказать:

```text
previous HY2XS operation is no longer running, but its firewall rollback guard
is still armed: hy2xs-fw-rollback-<op-id>.timer (active/waiting)
```

5. отказ происходит **до** снятия резервной копии и до первой мутации;
6. `install.sh` в том же окне отказывает на PHASE 0 по той же причине;
7. после срабатывания guard транзиентный таймер выгружается
   (`RemainAfterElapse=no`), и `repair` проходит. Проверяется наблюдением, а не
   ожиданием на глаз:

   ```bash
   systemctl show hy2xs-fw-rollback-<op-id>.timer -p LoadState -p ActiveState
   systemctl list-units --all --plain 'hy2xs-fw-rollback-*'
   ```

   Ожидается, что таймера в списке больше нет; оставшийся `.service` в
   состоянии `failed` (частичное восстановление) операцию не блокирует.

Обратная проверка: на сервере без вооружённого guard барьер молчит и ни одну
операцию не задерживает, а `failed` от уже отработавшего guard **не** считается
непокоем — иначе он заблокировал бы `repair`, которым и чинят последствия.

Отдельная проверка того же барьера — недоказуемое состояние. Барьер обязан
различать «guard вооружён» и «спросить не удалось»: это разные утверждения, и
оператору по ним нужны разные действия.

1. на рабочей установке без вооружённого guard делается недоступным запрос к
   systemd — проще всего временно подложить в `PATH` оркестратора `systemctl`,
   завершающийся ненулевым кодом;
2. любая операция жизненного цикла (`repair`, `reconfigure --apply`, `doctor`,
   `install.sh` на PHASE 0) обязана отказать:

```text
unable to verify firewall rollback guard state; systemd query failed,
refusing to start a lifecycle operation
```

3. отказ происходит **до** первой мутации, и тип ошибки —
   `GuardStateUnknownError`, а не `PendingRecoveryError`: ждать окна отката
   здесь бессмысленно;
4. `hy2xs-orchestrator status` при этом **не** падает: он замок не берёт и
   существует в том числе для сломанного хоста, поэтому сообщает
   `rollback_guard_state: "unknown"` и `firewall_state: "guard_unknown"`;
5. после возврата рабочего `systemctl` операция проходит без дополнительных
   действий.

Смысл проверки — в том, что прежнее поведение было противоположным: отказ
запроса давал пустой список guard'ов, барьер считал систему спокойной и
пропускал операцию, а взведённый таймер предыдущей операции срабатывал уже
посреди неё.

## D1g. Успешная установка не оставляет следов транзакции

Проверяется на чистом хосте, обычной успешной установкой. Это обратная проверка
к D1c и D1e: она ловит противоположную ошибку — данные транзакции, пережившие
её завершение.

После `installed`:

```text
systemctl list-units --all --plain 'hy2xs-fw-rollback-*'   → пусто
ls /run/hy2xs/rollback/                            → пусто
ls /run/lock/hy2xs-orchestrator.lock               → отсутствует
ls /etc/nftables.conf.candidate                    → отсутствует
ls /etc/nftables.d/hy2xs.nft.candidate             → отсутствует
```

и `/var/lib/hy2xs/install-state.json` содержит `phase: installed`,
`installed: true`, а `op_id` в нём совпадает с именем каталога, который лежал в
`/run/hy2xs/rollback/` во время установки.

`/etc/nftables.conf.candidate` — прямая регрессия: он не удалялся вообще, и
успешная установка оставляла его на сервере навсегда.

## D1a. Проход установки не спотыкается о собственный маркер

Проверяется на чистом хосте, обычной успешной установкой.

1. `install.sh` доходит до `preflight capabilities` **после** `apt-get`;
2. установка на этом шаге **не** падает с текстом «обнаружена предыдущая или
   посторонняя установка»;
3. установка доходит до `installed`.

Это сценарий, который не воспроизводится ни на одном dry-run: clean-host внутри
`install` проверялся дважды, и ко второму разу на диске уже лежал собственный
`/var/lib/hy2xs/install-state.json`, записанный после первого preflight. Каждая
чистая установка падала сразу после `apt-get`, получала `fatal_post_apply` и
оставляла сервер наполовину настроенным. Структурно закреплено в
`orchestrator/test/install-sequence.test.ts`.

## D2. Устаревший DNS после смены IPv4 провайдером

Проверяется на рабочей установке.

```text
сервер:  текущий публичный IPv4 = B
DNS:     A-запись = A (старый адрес)

hy2xs-orchestrator doctor
  → FAIL
  → в выводе присутствуют и A, и B

обновить A-запись на B, дождаться TTL

hy2xs-orchestrator doctor
  → PASS
```

Дополнительно: `reconfigure --apply` при устаревшей A-записи тоже обязан
отказать — инвариант живёт в общем `preflight`, а не в одном `doctor`.

## D. Negative tests

1. не Debian 13
2. порт уже занят
3. старое конфликтующее состояние уже существует
4. домен / SNI заданы некорректно
5. bundled UI отсутствует в пакете
6. Hysteria upstream недоступен
7. firewall применился частично
8. install flow прерван посередине
9. попытка использовать `HY2XS_IPV6_ENABLED=true`
10. `HY2XS_PUBLIC_HOST=0.0.0.0`
11. неизвестный `HY2XS_HYSTERIA_OBFS_TYPE`
12. конфигурация со схемой `HY2XS_CONFIG_SCHEMA_VERSION` из линейки `0.x`
13. upstream `latest` несовместим с шаблоном HY2XS — падает сборка, не установка
14. `HY2XS_PUBLIC_HOST` резолвится не на этот сервер
15. `HY2XS_DOMAIN` резолвится не на этот сервер при отличном от него `PUBLIC_HOST`
16. A-запись содержит правильный адрес и чужой одновременно
17. неизвестное значение `HY2XS_PUBLIC_ENDPOINT_POLICY`
18. импорт пиров с невалидной записью — файл не применяется частично
19. импорт пиров, пытающийся перезаписать `bootstrap-admin-peer`

## E. Fix20 production matrix (обязательные сценарии)

1. **Clean Debian 13 minimal**:
   - только SSH, без ручной установки зависимостей;
   - default `/etc/nftables.conf` stub;
   - install проходит полностью;
   - `doctor`/`status` показывают рабочее состояние.

2. **Non-systemd container**:
   - fail-fast до destructive шагов;
   - диагностическое сообщение с причиной capability/systemd.

3. **Foreign nftables**:
   - при `HY2XS_FIREWALL_MODE=managed` install/reconfigure блокируются;
   - при `HY2XS_FIREWALL_MODE=takeover` создаются backup/rollback guard и apply проходит.

4. **Rollback guard cleanup** (сценарий D1g):
   - после успешного apply/smoke не остаются `hy2xs-fw-rollback-*.timer/.service`;
   - `/run/hy2xs/rollback/`, `/run/lock/hy2xs-orchestrator.lock` и
     `*.candidate` не переживают успешную операцию.

4a. **Guard доходит до дедлайна** (сценарий D1e):
   - `auto-rollback-fired` создан, операция завершается отказом с
     `phase: firewall_guard_fired`;
   - `installed: true` не записан, даже если smoke успел сойтись.

4b. **Конкурентные операции** (сценарий D1f):
   - вторая операция отказывает **до** снятия резервной копии и первой мутации;
   - `status`/`diagnostics` не блокируются и сообщают об идущей операции;
   - замок не переживает своего держателя.

4c. **Аварийная смерть с вооружённым guard** (сценарий D1h):
   - новая операция отказывает, пока `hy2xs-fw-rollback-*` ещё активен, в том
     числе когда замка не осталось вовсе;
   - после срабатывания guard `repair` проходит.

5. **Partial install + repair**:
   - состояние `install-state` фиксирует промежуточную фазу;
   - `repair` завершает граф до `installed=true`.

6. **AAAA при IPv4-only**:
   - policy строго валидируется preflight;
   - soft warning path не используется в production baseline.

7. **Slow-start admin readiness**:
   - install не падает на race после restart;
   - readiness waiters дожидаются listener/healthz.

8. **Отказ между PHASE 0 и первой мутацией** (сценарий D1):
   - `install-state.json` честно показывает `failed`;
   - установщик не заявляет, что хост не изменён.

9. **Устаревший DNS после смены IPv4** (сценарий D2):
   - `doctor` и `reconfigure` отказывают;
   - в выводе присутствуют оба адреса.

## Acceptance criteria

Система принимается, если:

1. production builder на Debian 13 amd64 выдаёт переносимый install package
2. target server не выполняет build step
3. Hysteria2 получена из official upstream
4. HY2XS admin поставлен из install package
5. `post-install.env` отражает фактическое deploy-состояние
6. оркестратор зафиксирован как Bun/TypeScript stack и поставляется как готовый install-артефакт
7. оркестратор не требует standalone update / rollback / uninstall subcommands
8. bounded rollback в install/reconfigure корректно отрабатывает failure-сценарии firewall/systemd/config/smoke, и ни один его собственный отказ не отменяет остальные стадии
9. Telegram/access layer не требуется для прохождения install acceptance
10. отсутствует production path для port hopping
11. UI не запускается от root
12. клиентские endpoint не зависят от request `Host`/`hostname`
13. production build verify падает, если `config/hy2xs.env` содержит placeholder-значения
14. production build verify падает при dirty git tree (кроме `ALLOW_DIRTY_BUILD=true`)
15. metadata содержит `source_git_commit`, `dirty_tree`, `build_profile=production`
16. builder без override на сегодняшний день автоматически выбирает последнюю стабильную версию Hysteria
17. собранный пакет содержит **точные** версию, URL и SHA-256
18. выход новой версии Hysteria после сборки не меняет содержимое старого пакета
19. новая установка генерирует Gecko
20. Gecko использует `512/1200`
21. установленная Hysteria реально принимает сгенерированный YAML
22. сервис запускается под существующим непривилегированным пользователем `hysteria`
23. созданный пользователь получает `hysteria2://` с `obfs=gecko` и `obfs-password`
24. совместимый клиент Hysteria подключается напрямую по этой ссылке
25. после перезапуска Hysteria клиент быстро восстанавливает соединение
26. режим `HY2XS_HYSTERIA_OBFS_TYPE=salamander` полностью работоспособен
27. admin читает Gecko-конфиг без ошибок
28. экспорт не уничтожает современные и неизвестные upstream-поля
29. экспорт не содержит секретов
30. frontend отображает Gecko
31. `namedotcom` удалён, актуальные ACME-провайдеры отражены
32. документация нигде не утверждает, что Salamander — фиксированный инвариант
33. документация не фиксирует конкретный номер версии как «текущую версию», а объясняет latest-stable build policy
34. форма создания пира содержит примеры значений и пояснения для полей «Пир», «Комментарий» и «Секрет»
35. `hy2xs-orchestrator doctor` не перезапускает сервисы и не рвёт живые соединения, и это обеспечено read-only guard'ом, а не соглашением о выборе раннера
36. удаление `bootstrap-admin-peer` переживает `systemctl restart` и `reboot`: пир не воскресает
37. отключённый `bootstrap-admin-peer` остаётся отключённым после перезапуска
38. резервная копия с `includeSecrets=true` завершается ошибкой целиком, если секрет хотя бы одного пира недоступен
39. админка не генерирует `HYSTERIA2_TRAFFIC_STATS_SECRET` сама: пустой env при пустой базе — отказ старта
40. проверка зависимостей на уязвимости не имеет обходов ни в сборке, ни в документации, и покрывает весь lock-граф frontend
41. `apps/go.mod` объявляет `toolchain`, совпадающий с `GO_VERSION` из `versions.env`
42. `tools/dev/doctor.sh` / `doctor.ps1` показывают расхождение среды разработки с `versions.env`
43. маршруты-алиасы `/:id/client-url` и `/:id/qr` удалены и не входят в публичный API v1
44. `pnpm run typecheck` (`vue-tsc --noEmit`) проходит без ошибок и является обязательным шагом сборки
45. проверка типов идёт до сборки bundle, а не после
46. `vue-tsc` версии 3 и выше: 0.x проверку шаблонов не выполняет
47. `pnpm audit` по всему графу зависимостей frontend не находит уязвимостей
48. локальные SVG-иконки собираются спрайтом из репозитория, без `vite-plugin-svg-icons`
49. каждая иконка задаёт систему координат: `viewBox` либо пара `width`/`height`
50. страница конфига Hysteria не содержит элементов управления, которые ничего не сохраняют
51. невозможность записать состояние отказа не отменяет откат: восстановление выполняется, в журнале остаётся отметка о неудавшейся записи
52. `install-state.json` пишется одним писателем, атомарно и с `fsync` файла и каталога: после потери питания на диске лежит либо прежний полный документ, либо новый полный
53. ownership-флаг маркера установки взводится **до** записи, поэтому отказ на `chown` не даёт `fatal_pre_apply` при уже созданном файле
54. тесты и проверка типов не имеют обходов ни в сборке, ни в документации; `metadata/package.env` содержит `tests_gate=true`, и это утверждение опирается на фактический прогон
55. `reset-admin` при недоступной базе отказывает, а не создаёт вторую учётную запись администратора; ошибка хеширования не приводит к пустому `password_hash`
56. данные для отката переживают долговечную фиксацию успеха: снятие таймера автоотката и удаление резервных копий разделены записью `phase: installed`
57. резервная копия снимается строго и до первой мутации; несозданная копия останавливает операцию, а не игнорируется
58. копия привязана к операции: откат восстанавливает состояние непосредственно перед текущим проходом, а не сохранённое предыдущим
59. ни одна команда отката не глушит свой код возврата; отказавшие стадии перечисляются, а артефакты восстановления удаляются только после подтверждённого успеха
60. `doctor` не выполняет проб, изменяющих данные в админке: авторизация действующим паролем пира ограничена режимом `install`
61. снятие rollback guard доказывается, а не объявляется: отсутствие маркера `auto-rollback-fired` и `ActiveState=inactive` обоих юнитов — предусловие записи `phase: installed`
62. сработавший guard запрещает фиксацию успеха, каким бы ни был результат smoke, и получает собственную причину отказа `firewall_guard_fired`
63. smoke сверяет **эффективный** firewall с конфигурацией операции, а не только разбирает `/etc/nftables.conf`
64. автоматический откат firewall сообщает о частичном восстановлении отказом юнита, а не молчаливым кодом 0, и сохраняет данные восстановления
65. откат восстанавливает `enabled`/`active` состояние `nftables.service`, а не только файлы правил
66. операции жизненного цикла сериализованы эксклюзивным замком: вторая операция отказывает до первой мутации, а `status`/`diagnostics` не блокируются
67. замок снимается при любом завершении держателя, включая `Ctrl+C`, SIGTERM и обрыв SSH; замок мёртвого держателя переиспользуется безопасно
68. новая операция не начинается, пока у предыдущей остаётся вооружённый rollback guard: условие старта — «у предыдущей нет исполнителей, способных изменить систему», а не «её PID мёртв»
69. отказ записи маркера `auto-rollback-fired` не может привести к фиксации успеха: он переводит юнит guard в `failed`, а `failed` фиксацию запрещает
70. восстановление `UnitFileState` у `nftables.service` не обещает точности, которой не даёт: восстанавливаются `enabled`/`disabled`, остальные состояния называются оператору и не трогаются
71. отказ запроса к systemd не выдаётся за покой: барьер обязан **доказать** отсутствие исполнителей предыдущей операции, а при невозможности получить доказательство отказывает с `GuardStateUnknownError`, а не разрешает операцию
72. покой guard перечисляется белым списком (`inactive`, `failed`): незнакомое состояние systemd блокирует операцию, а не проходит молча по принципу «его нет в списке опасных»
73. отработавший таймер не блокирует операцию навсегда: `RemainAfterElapse=no` выгружает его, а барьер дополнительно опознаёт `SubState=elapsed` у `*.timer` как покой
74. обещанное окно отката — контракт systemd, а не намерение: у транзиентного таймера явно задан `AccuracySec=1s`, иначе умолчание `AccuracySec=1min` превращало «45 секунд» в 45–105
75. состояние guard читает один наблюдатель: `status` берёт его у того же кода, что и барьер, и сообщает `unknown` вместо тихого «guard'ов нет» при отказе systemd
76. ни один релизный гейт не подаёт вывод в поиск с флагом `-q` через пайплайн: под `set -o pipefail` оборванный продюсер отдаёт 141, и «совпадение найдено» превращается в ненулевой код — для отрицательных проверок это ложный PASS. Сравнение идёт через here-string, и возврат пайплайна запрещён отдельной приёмкой
77. отрицательные сканы по дереву исходников формулируют **синтаксическую форму**, а не подстроку: вызов — имя со скобкой или обратной кавычкой, импорт — `import` со спецификатором, зависимость — ключ в `package.json`. Прозаическое упоминание удалённой вещи разрешено, иначе гейт запрещает документировать собственную работу

### Почему отрицательный скан не ищет подстроку

Комментарий, объясняющий, почему чего-то больше нет, обязан называть это по
имени. Скан по голой подстроке такой комментарий не отличает от кода и падает
ровно на документации к выполненной им же работе. В этом файле урок оплачен
пять раз: скан versions contract ловил сам себя на `/hui`; dead-route скан
падал на `router_test.go`, который перечисляет удалённые маршруты, чтобы
доказать их отсутствие; скан иконок — на блочном комментарии о замене плагина;
скан прежних имён раннеров — на слове `systemd-run` в прозе; скан
`cancelFirewallRollback` — на комментарии о её разделении.

`code_has` отбрасывает **строчные** комментарии (`//`, `#`), но не блочные
`/* … */`. Блок-парсер сознательно не заводится: наивный стриппер спотыкается
о `/*` внутри строк и регулярных выражений и может вычистить настоящий код —
а это ложный PASS, то есть лекарство хуже болезни. Для файлов с блочными
комментариями формулируется синтаксическая форма либо утверждение опирается на
более сильный гейт.

Пример последнего: литерального скана по `virtual:svg-icons-register` больше
нет. Его роль исполняет production `vite build`, который проходит раньше:
активный `import "virtual:svg-icons-register"` при отсутствующем плагине не
разрешается резолвером, и сборка bundle падает. Проверяется исполняемый импорт,
а не совпадение подстроки.

### Почему пайплайн в `grep -q` запрещён

Поиск с флагом `-q` прекращает чтение на **первом** совпадении и закрывает свой
конец канала. Продюсер, которому осталось что писать, получает `SIGPIPE` и
завершается кодом 141, а `set -o pipefail` делает 141 статусом всей
конструкции. Смысл инвертируется:

```text
совпадение НАЙДЕНО -> продюсер оборван -> статус 141 -> «не найдено»
```

Для утвердительной проверки это ложный FAIL — гейт отвергает корректный
артефакт. Для отрицательной («такой конструкции в коде нет») — **ложный PASS**:
запрещённая конструкция найдена, а гейт зелёный.

Порог измерим и резкий. Пока весь вывод продюсера помещается в буфер канала —
64 KiB на Linux, — он записывает всё, не блокируясь, и успевает завершиться
раньше, чем потребитель вообще начнёт читать. Замер на 60 прогонах каждого
размера:

```text
    4 KiB … 60 KiB   отказов 0
   64 KiB            отказов 58/60
   96 KiB и больше   отказов 60/60
```

Поэтому такая проверка годами выглядит исправной, а переворачивается на первом
источнике крупнее буфера. В этом репозитории файлы такого размера уже есть
(`tools/build/lib/acceptance.sh` — 123 KiB, `orchestrator/src/steps/firewall.ts`
— 67 KiB).

Правильная форма — here-string, у которого пайплайна нет вовсе:

```bash
grep -q 'PATTERN' <<<"$content" || fail "..."
```

Для содержимого файла есть `code_has FILE [флаги] -- PATTERN`: он читает код без
комментариев в переменную **отдельным оператором** и сравнивает через
here-string. Отдельный оператор важен: в контексте `! code_has …` bash отключает
`errexit` на весь вызов, поэтому неудачное чтение проверяется явно, а не
рассчитывает на `set -e`.