588 lines
37 KiB
Markdown
588 lines
37 KiB
Markdown
# Tasks
|
||
|
||
Как строить — `design.md` (дальше «решение N»). Что должно получиться —
|
||
дельты `specs/graceful-shutdown`, `specs/student-tests` и
|
||
`specs/load-benchmark`. Номера коммитов — таблица решения 14.
|
||
|
||
**Правила.**
|
||
|
||
- **Правила слоёв.** Перед первым файлом слоя — Read его правила (и
|
||
одного файла из каталога, чтобы правило подгрузилось):
|
||
|
||
| Что правим | Правила |
|
||
|---|---|
|
||
| `bench/` | `.claude/rules/bench.md` |
|
||
| `student-tests/` | `student-tests.md`, `api-contract.md` |
|
||
| `src/infra/`, `src/main.py`, `src/__main__.py` | `infra.md`, `logging.md`, `run-modes.md`, `api-layer.md`, `docker.md` |
|
||
| `scripts/rolling-update.sh` | `balancer.md` |
|
||
| `.claude/skills/run-mtusi-messenger/driver.py` | `SKILL.md` того же каталога |
|
||
|
||
- **Только Edit и Write.** Файлы меняются только ими: не sed, не
|
||
heredoc, не `python -c` (глобальное правило пользователя). Перед
|
||
правкой — Read файла. Запускать `uv run python -c …` и `python3 -c …`
|
||
для проверок можно.
|
||
- **Коммиты** — без подтверждения (бриф основной сессии). Английский
|
||
conventional style, сообщения — таблица решения 14, последняя строка
|
||
`Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>`. Push,
|
||
checkout, reset, stash, rebase нельзя; `git revert` в задаче 3.6 —
|
||
можно.
|
||
- **Стенды.** Удалять и пересоздавать можно `mtusi-lab3` (рабочий),
|
||
`mtusi-bench` и `mtusi-lab3-failures`. Чужие проекты (`mtusi-lab2` и
|
||
другие) не трогать.
|
||
- **Упавший тест или прогон** — сначала разбор и названная причина,
|
||
потом правка (AGENTS.md). Правка кода — новый commit и повтор
|
||
проверки.
|
||
- **Журнал этапа** — `<scratchpad>/fix-known-issues/journal.md`
|
||
(scratchpad сессии apply): хэши, ключевые строки выводов, заметки для
|
||
«Найдено в apply». Отметки задач до 8.8 тоже ведутся там: паспорт
|
||
меток `bench/` пишет `git.dirty`, и перед каждым `make bench_*`
|
||
`git status --porcelain` должен быть пуст. В файлы change отметки
|
||
переносятся в 8.8.
|
||
- **`REPORT.md` может править основная сессия.** Перед каждой правкой —
|
||
свежий Read. Чужие изменения не откатывать и от своего имени не
|
||
коммитить: спросить основную сессию.
|
||
- **Долгие команды** — всё дольше пары минут — фоном, журнал в
|
||
`<scratchpad>/fix-known-issues/<имя>.log`:
|
||
|
||
```sh
|
||
nohup make <цель> > <scratchpad>/fix-known-issues/<имя>.log 2>&1 &
|
||
```
|
||
|
||
Ожидание — циклом (`until ! pgrep -f "[b]ench/run.py" >/dev/null; do
|
||
sleep 15; done`, Bash с `run_in_background` или Monitor), не дольше
|
||
30 мин на вызов. Ни один вызов инструмента не должен упереться в
|
||
10 минут.
|
||
- **Проверка хоста** — перед каждым прогоном `bench/` (3.4, 3.5, 3.7,
|
||
7.8) и перед замерами `stop-at-start` (5.2, 5.9). Вывод — в журнал:
|
||
- `pmset -g batt | head -1` — `AC Power`;
|
||
- `memory_pressure | tail -1` — давления нет, свободной памяти хватает
|
||
на ВМ 7,7 GiB (ориентир прежних замеров — 50 % и больше);
|
||
- для `bench/`: `make stop`, затем `docker ps --format '{{.Names}}'` —
|
||
пусто;
|
||
- `LC_ALL=C sysctl -n vm.loadavg` — второе число (5 мин) < 8;
|
||
- `pgrep -x zoom.us` — пусто;
|
||
- `vm_stat | grep Swapouts` — до прогона и после.
|
||
|
||
Плохо хоть одно — прогон не запускать: остановиться и вернуть отчёт
|
||
основной сессии с выводом команды.
|
||
- **Секреты.** В evidence и журнале нет токенов, паролей, хэшей целиком,
|
||
`.env` и абсолютных путей домашнего каталога (`evidence/README.md`).
|
||
- **Уведомления в Telegram** — только если их поручает бриф apply, через
|
||
скилл `telegram-send`.
|
||
|
||
## 1. Подготовка
|
||
|
||
- [ ] 1.1 Исходное состояние:
|
||
- `git status --porcelain` пуст;
|
||
- `git log --oneline -1` — commit `docs: propose fix-known-issues
|
||
change`. Его хэш — `BASE` в журнале;
|
||
- `docker compose ps` — пять контейнеров `mtusi-lab3` `healthy`,
|
||
`make lb_stats` — обе реплики `UP`. Иначе — `make run_docker`.
|
||
- [ ] 1.2 Read правил из таблицы «Правила слоёв» и по одному файлу из
|
||
каждого затрагиваемого каталога: `bench/run.py`,
|
||
`student-tests/run_failures.py`, `src/main.py`, `src/infra/logger.py`,
|
||
`scripts/rolling-update.sh`,
|
||
`.claude/skills/run-mtusi-messenger/driver.py`. Проверка: список
|
||
прочитанного — в журнале.
|
||
|
||
## 2. Паспорт метки — `swapouts_delta` (запись 5, решение 13)
|
||
|
||
- [ ] 2.1 `bench/run.py`:
|
||
- функция `swapouts_delta(start, end) -> int | None` рядом со
|
||
`swap_warning`, с докстрингом: `None`, если одного счётчика нет;
|
||
иначе разность, в том числе 0;
|
||
- `swap_warning` считает через неё, тексты предупреждений прежние;
|
||
- конец `main()` пишет `meta["host_state"]["swapouts_delta"]`, когда
|
||
значение не `None`;
|
||
- код ячеек серий (`host_swapouts`) не трогать.
|
||
|
||
Проверка: `git diff --stat` — только `bench/run.py`.
|
||
- [ ] 2.2 Самопроверка, вывод — в журнал:
|
||
|
||
```sh
|
||
uv run python -c "import sys; sys.path.insert(0, 'bench'); import run; d, w = run.swapouts_delta, run.swap_warning; assert d({'swapouts': 0}, {'swapouts': 0}) == 0; assert d({'swapouts': None}, {'swapouts': 3}) is None; assert d({'swapouts': 5}, {'swapouts': None}) is None; assert d({'swapouts': 5}, {'swapouts': 9}) == 4; assert w({'swapouts': 0}, {'swapouts': 0}) is None; assert w({'swapouts': 5}, {'swapouts': 9}) == 'host swapped out 4 pages during the run: rerun'; print('swapouts ok')"
|
||
```
|
||
|
||
Ожидается `swapouts ok`. Затем `make lint` — код 0, других файлов он
|
||
не меняет.
|
||
- [ ] 2.3 Commit 1. Проверка: `git status --porcelain` пуст.
|
||
|
||
## 3. События фазы `failover` — поток (запись 3, решения 9, 10)
|
||
|
||
- [ ] 3.1 `bench/run.py` (решение 9):
|
||
- метод `Stand.container_events(container, path)` — поток `docker
|
||
events` по контейнеру в файл, тот же фильтр и формат, что у прежнего
|
||
`Stand.events`; докстринг — почему поток (буфер демона, 256
|
||
событий);
|
||
- `run_phase`: поток — в `work_dir/<фаза>-events.log`, запуск после
|
||
выбора цели и до `k6_console`, остановка `terminate` + `wait` после
|
||
`wait_ready` после фазы, в `finally`. События — `failover.parse_events`
|
||
этого файла, выбор действия и возврата прежний;
|
||
- прежний `Stand.events` удалить.
|
||
|
||
Проверка:
|
||
- `grep -n "def events\|stand.events(" bench/run.py` — пусто;
|
||
- `grep -n "container_events" bench/run.py` — определение и вызов;
|
||
- сообщение `docker events of … not found` осталось (сценарий
|
||
«Событие не получено»);
|
||
- `uv run python bench/scaling.py --selftest` и `uv run python
|
||
bench/resources.py --selftest` — `selftest ok`;
|
||
- `make lint` — код 0.
|
||
- [ ] 3.2 Commit 2. Проверка: дерево чистое, хэш — в журнал.
|
||
- [ ] 3.3 Временная сверка (решение 10):
|
||
- в `bench/run.py` — метод запроса к буферу демона: копия прежнего
|
||
`Stand.events` под именем `events_from_buffer`;
|
||
- в `run_phase` после событий из потока — тот же разбор по буферу за
|
||
окно `started - 5` … `ended + 1`:
|
||
- TimeNano действия и возврата равны — `self.say` «cross-check:
|
||
stream = buffer», оба момента;
|
||
- в буфере их нет — «cross-check: buffer lost the events»;
|
||
- различаются — `BenchError`.
|
||
|
||
`make lint`, commit 3. Хэш — в журнал.
|
||
- [ ] 3.4 Прогон 1 без помех: проверка хоста (с `make stop`), затем
|
||
`nohup make bench_failover_quick > <scratchpad>/fix-known-issues/failover-cross.log
|
||
2>&1 &`, ожидание. Проверка:
|
||
- код 0, 4 фазы;
|
||
- в журнале 4 строки «cross-check: stream = buffer»;
|
||
- `meta.json` метки `evidence/failover/quick-failover-*` (последней):
|
||
- `status` `complete`, `git.dirty` `false`, `git.commit` = commit 3;
|
||
- `host_state.swapouts_delta` есть и равен `end.swapouts −
|
||
start.swapouts`. Его нет — только если `start.swapouts` равен
|
||
`null`.
|
||
|
||
Чтение — `python3 -c` с `json.load`. Сбой — разбор.
|
||
- [ ] 3.5 Прогон 2 под шумом `docker exec`. Проверка хоста, затем:
|
||
|
||
```sh
|
||
S=<scratchpad>/fix-known-issues; rm -f $S/noise.stop
|
||
nohup sh -c 'n=0; s=$(date +%s); while [ ! -f "$1" ]; do if docker exec mtusi-bench-valkey true >/dev/null 2>&1; then n=$((n + 1)); else sleep 0.5; fi; done; echo "noise-execs=$n seconds=$(( $(date +%s) - s ))"' sh $S/noise.stop > $S/noise.log 2>&1 &
|
||
nohup make bench_failover_quick > $S/failover-noise.log 2>&1 &
|
||
```
|
||
|
||
После конца `run.py` — `touch $S/noise.stop`, затем `cat
|
||
$S/noise.log`. Проверка:
|
||
- код 0, 4 фазы, строк «docker events … not found» нет;
|
||
- хотя бы в одной фазе «cross-check: buffer lost the events»;
|
||
- в журнал — частота шума (execs за секунды) и какие фазы потеряли
|
||
события в буфере.
|
||
|
||
Ни одна фаза не потеряла — шума мало: повтор один раз с двумя такими
|
||
циклами. Снова нет — записать как результат и идти дальше.
|
||
- [ ] 3.6 Откат сверки: `git revert --no-commit <commit 3>`, затем `git
|
||
commit`, сообщение commit 4 с телом «This reverts commit <хэш>.» и
|
||
строкой `Co-Authored-By`. Проверка: `git diff <commit 2> HEAD --
|
||
bench` пуст.
|
||
- [ ] 3.7 Итоговый прогон на окончательном коде: проверка хоста, `make
|
||
bench_failover_quick` (фоном, журнал `failover-final.log`). Проверка:
|
||
- код 0, 4 фазы, строк «cross-check» нет;
|
||
- `meta.json`: `git.commit` = commit 4, `git.dirty` `false`,
|
||
`swapouts_delta` — как в 3.4.
|
||
|
||
Затем рабочий стенд снова: `make run_docker`, `make lb_stats` — обе
|
||
реплики `UP`.
|
||
|
||
## 4. PostgreSQL стенда отказов (запись 4, решения 11, 12)
|
||
|
||
- [ ] 4.1 `student-tests/run_failures.py` (решение 12):
|
||
- константа признаков аварии;
|
||
- функция чтения журнала: `dc(project, "logs", "--no-log-prefix",
|
||
"postgres", quiet=True)`;
|
||
- сводка `postgres log: N lines, crash markers M; "too many clients"
|
||
X, "administrator command" Y`;
|
||
- при M > 0 — строки признаков (не больше 20) и `results["postgres"]
|
||
= 1`;
|
||
- вызов после pytest и до уборки, только если pytest запускался;
|
||
- строка в докстринге модуля.
|
||
|
||
`make lint`, commit 5.
|
||
- [ ] 4.2 Красный прогон, то есть воспроизведение дефекта на
|
||
закоммиченном коде (сценарий «PostgreSQL перезапустился аварийно»):
|
||
`nohup make failure_checks > <scratchpad>/fix-known-issues/failure-red.log
|
||
2>&1 &`, ожидание (~70 с). Ожидается:
|
||
- 17 passed;
|
||
- сводка журнала с `crash markers` > 0, среди строк — `untracked
|
||
child process … exited with exit code 2` и `reinitializing`;
|
||
- `results` содержит `'postgres': 1`, код выхода не 0;
|
||
- стенд отказов удалён: `docker ps -a --filter
|
||
label=com.docker.compose.project=mtusi-lab3-failures -q` пусто.
|
||
|
||
Не воспроизвелось — повтор `make failure_checks FAULT_ARGS='-k
|
||
connection_limit'` до двух раз. Нет и тогда — остановиться, разобрать
|
||
и вернуть отчёт основной сессии; `init: true` вслепую не коммитить.
|
||
- [ ] 4.3 Исправление (решение 11):
|
||
- `student-tests/failures.compose.yml`: `init: true` у `postgres`;
|
||
в шапке — зачем (сироты `psql` из `fill-connections` подбирает
|
||
init, а не postmaster);
|
||
- `student-tests/fault_hook.py`: комментарий у `FILL_SH` про сирот и
|
||
init стенда. Код hook не меняется.
|
||
|
||
`make lint`, commit 6.
|
||
- [ ] 4.4 Зелёные прогоны (сценарий «Заполнение и освобождение
|
||
слотов»): `make failure_checks` два раза. До и после — `StartedAt`
|
||
контейнеров `mtusi-lab3` (`docker inspect`). В каждом прогоне:
|
||
- код 0, 17 passed;
|
||
- сводка `crash markers 0`, а «too many clients» и «administrator
|
||
command» > 0: заполнение и освобождение правда были;
|
||
- `results: {'fault': 0, 'postgres': 0}`, стенд отказов удалён.
|
||
|
||
Во время одного прогона, пока идёт pytest: `docker inspect -f
|
||
'{{.HostConfig.Init}}' mtusi-lab3-failures-postgres-1` → `true`.
|
||
`StartedAt` рабочего стенда не изменился.
|
||
|
||
## 5. Ранний обработчик сигналов (запись 2, решения 3–8)
|
||
|
||
- [ ] 5.1 Команда `stop-at-start` в `driver.py` (решение 8): аргументы,
|
||
контейнеры по метке, поток событий, классы попыток, «кто остановил»,
|
||
PASS, уборка в `finally`. Плюс строка в докстринге драйвера.
|
||
Проверка:
|
||
- `/usr/bin/python3 -m py_compile .claude/skills/run-mtusi-messenger/driver.py`
|
||
— синтаксис 3.9;
|
||
- `python3 .claude/skills/run-mtusi-messenger/driver.py stop-at-start
|
||
--help`;
|
||
- `make lint` — код 0.
|
||
|
||
Commit 7.
|
||
- [ ] 5.2 «До» (сценарии `graceful-shutdown` на прежнем коде). Образ:
|
||
`git archive --format=tar HEAD | docker build -t
|
||
mtusi-messenger:stop-before -` — HEAD это commit 7, код приложения как
|
||
в `BASE`. ID образа — в журнал. Проверка хоста, затем `python3
|
||
.claude/skills/run-mtusi-messenger/driver.py stop-at-start --image
|
||
mtusi-messenger:stop-before > <scratchpad>/fix-known-issues/stop-before.log`.
|
||
Ожидается:
|
||
- код 1;
|
||
- попытки `import`: `docker stop` ≈ 10 с, код 137, остановки в
|
||
журнале нет, а «Uvicorn running on» появился уже после сигнала —
|
||
дефект воспроизведён;
|
||
- попытки `running` и `server-start`: код 0, остановил `uvicorn`.
|
||
- [ ] 5.3 Код (решения 3–5):
|
||
- новый `src/infra/early_stop.py`: только stdlib, `install()`,
|
||
`disarm()`, обработчик — запись по решению 5 и `os._exit(0)` в
|
||
`finally`; докстринг со ссылкой на design;
|
||
- `src/__main__.py` — по решению 3, импорты внутри `if __name__ ==
|
||
"__main__"`;
|
||
- `src/main.py`: `early_stop.disarm()` — первая строка `lifespan`,
|
||
комментарий зачем.
|
||
|
||
Проверка:
|
||
- `grep -nE "^(import|from) " src/infra/early_stop.py` — только
|
||
stdlib;
|
||
- `.venv/bin/python -c "import src.infra.early_stop"` — код 0;
|
||
- `make lint` — код 0.
|
||
- [ ] 5.4 `scripts/rolling-update.sh`, `remove_new` (решение 7):
|
||
- слот есть → `maint` → `docker stop --timeout 10` с временем и кодом
|
||
выхода → `docker rm -f` → адрес ушёл → `ready`;
|
||
- слота нет → `docker rm -f`;
|
||
- строка `removed new …` в формате решения 7;
|
||
- комментарий без ссылки на `KNOWN_ISSUES.md`.
|
||
|
||
Проверка: `sh -n scripts/rolling-update.sh`; `git diff` — только
|
||
`remove_new` и комментарии.
|
||
- [ ] 5.5 `make lint`, `make check`, commit 8. Хэш — в журнал.
|
||
- [ ] 5.6 Консоль на commit 8 (решение 6, сценарий «Ctrl+C в консоли во
|
||
время старта»), порт 18089 свободен (`lsof -nP -iTCP:18089
|
||
-sTCP:LISTEN` пусто):
|
||
- SIGTERM на импорте:
|
||
|
||
```sh
|
||
APP__RUN_MODE=console APP__PORT=18089 .venv/bin/python -m src > <scratchpad>/fix-known-issues/console-term.log 2>&1 & pid=$!; sleep 0.3; kill -TERM $pid; wait $pid; echo "exit=$?"
|
||
```
|
||
|
||
Ожидается `exit=0`. В журнале одна строка JSON «Stopped API before
|
||
startup» с `signal` `SIGTERM`, `level` `info`, `timestamp`,
|
||
`instance_id`, traceback нет.
|
||
- То же с `kill -INT` — `exit=0`, `signal` `SIGINT`.
|
||
- После готовности: тот же запуск, ожидание `curl -sf
|
||
http://127.0.0.1:18089/health/live`, затем `kill -TERM $pid` и
|
||
`wait`. Ожидается `exit=0`: «Shutting down», «Stopped API»,
|
||
«Finished server process», записи «before startup» нет.
|
||
- Reload (`D=.claude/skills/run-mtusi-messenger/driver.py`): `python3
|
||
$D start` (порт 18080), `touch src/main.py`, через 3 с в
|
||
`/tmp/mtusi-api-18080.log` — «Reloading», `python3 $D status` —
|
||
`ready: True`, `python3 $D stop`. `git status --porcelain` пуст.
|
||
- [ ] 5.7 Новый код на рабочий стенд без простоя:
|
||
- до замены — ID и `.Image` реплик (`docker compose ps -q api`,
|
||
`docker inspect -f '{{.Image}}'`);
|
||
- `python3 tests/load.py --duration 45 --concurrency 4 >
|
||
<scratchpad>/fix-known-issues/load-rollout.log 2>&1 &`, затем `make
|
||
rolling_update > <scratchpad>/fix-known-issues/rollout.log 2>&1`,
|
||
затем ожидание нагрузки.
|
||
|
||
Проверка:
|
||
- код скрипта 0, две строки `removed old … (stop Ns, exit 0)`;
|
||
- `failed_requests` 0 в отчёте `tests/load.py`;
|
||
- `make lb_stats` — две реплики `UP`;
|
||
- реплики с новыми ID на одном новом `.Image`;
|
||
- в журнале новых реплик — обычный старт.
|
||
- [ ] 5.8 Ветка сбоя `rolling-update.sh` (решение 7):
|
||
- `ROLLOUT_READY_TIMEOUT=1 make rolling_update`: код 1, строки
|
||
`removing new replica … that is not ready` и `removed new … (no
|
||
slot: docker rm -f)` или `(slot api-N: stop Ns, exit 0)`;
|
||
- `ROLLOUT_READY_TIMEOUT=2 make rolling_update` — ради пути со
|
||
слотом. Записать, какой путь сработал. Если замена успела
|
||
завершиться (код 0) — это тоже результат;
|
||
- после каждого запуска: `make lb_stats` — две реплики `UP`; `docker
|
||
compose exec -T haproxy bash -c 'exec 3<>/dev/tcp/127.0.0.1/9999 &&
|
||
echo "show servers state api" >&3 && cat <&3'` — у слотов
|
||
`srv_admin_state` 0 или 32, без флагов 1 и 8.
|
||
- [ ] 5.9 «После». Проверка хоста, затем `python3
|
||
.claude/skills/run-mtusi-messenger/driver.py stop-at-start --image
|
||
mtusi-messenger:lab3 > <scratchpad>/fix-known-issues/stop-after.log`.
|
||
ID образа равен `.Image` реплик рабочего стенда. Ожидается:
|
||
- код 0, PASS;
|
||
- попытки `import`: остановил `early`, `docker stop` ≤ 1 с, код 0;
|
||
- хотя бы одна `server-start`: остановил `uvicorn`, ≤ 1 с, код 0. Ни
|
||
одной — повтор с `--server-start 10`;
|
||
- `running`: остановил `uvicorn`, код 0.
|
||
- [ ] 5.10 Регрессия консоли: `lsof -nP -iTCP:18080 -sTCP:LISTEN` пусто,
|
||
затем `python3 .claude/skills/run-mtusi-messenger/driver.py all`.
|
||
Ожидается: `FAILED: none` у `flow`, `PASS` у smoke, все тесты прошли,
|
||
тесты реплик пропущены с причиной, код 0.
|
||
- [ ] 5.11 Уборка: `docker image rm mtusi-messenger:stop-before`; `docker
|
||
ps -a --filter label=mtusi.stop-at-start -q` пусто.
|
||
|
||
## 6. Доказательства исключений сверки (запись 1, решения 1, 2)
|
||
|
||
- [ ] 6.1 Команды `cache-check` и `auth-storage` в `driver.py` (решение
|
||
1), строки в докстринге. Проверка:
|
||
- `/usr/bin/python3 -m py_compile .claude/skills/run-mtusi-messenger/driver.py`;
|
||
- `make lint` — код 0;
|
||
- пробный запуск обеих против рабочего стенда (`--port 8080`): код 0,
|
||
в выводе нет токена, пароля и хэшей.
|
||
|
||
Commit 9.
|
||
- [ ] 6.2 `make test_isolated > <scratchpad>/fix-known-issues/test-isolated.log
|
||
2>&1` при работающем рабочем стенде. Ожидается код 0, 4 теста реплик
|
||
пропущены с причиной. Сразу после — 6.3: ключи тестового прогона
|
||
нужны в Valkey.
|
||
- [ ] 6.3 Снятие доказательств, ничего другого на стенде не идёт:
|
||
- `python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080
|
||
cache-check > <scratchpad>/fix-known-issues/cache-check.log`. Код
|
||
0. Ожидается (решение 1, шаги 5–8): чтений `chats` 1, hits +49,
|
||
промахов +1; 60 ответов 200 (50 в окне счётчиков, 10 — для срока);
|
||
TTL ≤ настроенного и чтениями не продлевается; ≥ 2 `X-Instance-Id`;
|
||
ключи обоих префиксов > 0;
|
||
- `python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080
|
||
auth-storage > <scratchpad>/fix-known-issues/auth-storage.log`. Код
|
||
0, факты решения 1.
|
||
|
||
Проверка секретов: `grep -nE '/Users/|Bearer |\$argon2id\$[^ ]*\$[A-Za-z0-9+/]{8,}'`
|
||
по обоим журналам — пусто.
|
||
- [ ] 6.4 Сверка ссылок (решение 2):
|
||
- `missing_evidence` в `student-tests/spec_coverage.py`;
|
||
- два теста в `student-tests/test_coverage.py`;
|
||
- тексты `check` пяти исключений называют команды.
|
||
|
||
`make lint`, commit 10. Красная проверка на нём, до файлов
|
||
доказательств (сценарий «Ссылка на отсутствующий файл»): `uv run
|
||
pytest student-tests/test_coverage.py`. Тест на настоящих исключениях
|
||
падает и называет пять сценариев и два пути, остальные проходят.
|
||
Вывод — в журнал.
|
||
- [ ] 6.5 `evidence/cache/hits.md` и `evidence/auth/passwords-and-tokens.md`
|
||
по образцу файлов лабы 2:
|
||
- шапка: спеки и сценарии, change, дата, commit (код команд —
|
||
commit 9, приложения — commit 8), стенд (LB, две реплики, лимиты),
|
||
хост, команда;
|
||
- разделы с выводом команд; у `hits.md` — ещё строка `make
|
||
test_isolated` (итог и время);
|
||
- вывод.
|
||
|
||
Проверка: `uv run pytest student-tests/test_coverage.py` — зелёный;
|
||
grep секретов из 6.3 по обоим файлам — пусто.
|
||
- [ ] 6.6 `make student_test` через LB — все прошли (на 2 больше, чем
|
||
до change: 131 → 133), строка сверки покрытия с прежними числами
|
||
(137 / 125 / 12). Commit 11: оба файла.
|
||
|
||
## 7. Регрессия на итоговом коде
|
||
|
||
- [ ] 7.1 Статика:
|
||
- `make lint`, `make check`, `make validate PYTHON=.venv/bin/python`;
|
||
- `uv run python bench/scaling.py --selftest`, `uv run python
|
||
bench/resources.py --selftest`, однострочник 2.2;
|
||
- `sh -n scripts/rolling-update.sh`.
|
||
|
||
Все — код 0.
|
||
- [ ] 7.2 `make test` — `PASS`; `make instances` — `instances: 2`.
|
||
- [ ] 7.3 `make student_test` через LB — все прошли, тесты реплик
|
||
выполнены, строка сверки покрытия.
|
||
- [ ] 7.4 `make test-persistence ACTION_SCRIPT=scripts/restart.sh` —
|
||
`PASS`; `StartedAt` LB, реплик, PostgreSQL и Valkey до и после —
|
||
новые, ID те же.
|
||
- [ ] 7.5 `make test-failover` по `evidence/tests/clean-clone-final.md`,
|
||
с `STOP_ONE_LOG`:
|
||
- `stop` для одной реплики, `make replicas`, сдвиг очереди одним
|
||
запросом, `stop` для другой;
|
||
- `make replicas`, затем `STOP_MODE=kill`.
|
||
|
||
Все `PASS`. ID остановленного контейнера = `TARGET_INSTANCE_ID`. Код
|
||
выхода: `Exited (0)` у `stop`, `Exited (137)` у `kill`. В конце `make
|
||
replicas`.
|
||
- [ ] 7.6 `make test_isolated` — код 0.
|
||
- [ ] 7.7 `make failure_checks` — код 0, сводка журнала PostgreSQL
|
||
`crash markers 0`.
|
||
- [ ] 7.8 Быстрые профили на итоговом коде. Проверка хоста (с `make
|
||
stop`), дерево чистое, затем цепочкой фоном:
|
||
|
||
```sh
|
||
nohup sh -c 'make bench_failover_quick && make bench_rollout_quick; echo "chain-exit=$?"' > <scratchpad>/fix-known-issues/quick-final.log 2>&1 &
|
||
```
|
||
|
||
Проверка:
|
||
- `chain-exit=0`;
|
||
- `failover` — 4 фазы, сверка записей сошлась;
|
||
- `rollout` — замена завершена, сверка сошлась, в
|
||
`raw/rollout-script.log` строки `removed old … exit 0`;
|
||
- у обеих меток `git.commit` = HEAD, `git.dirty` `false`,
|
||
`host_state.swapouts_delta` есть.
|
||
|
||
Затем `make run_docker`, `make lb_stats` — две реплики `UP`.
|
||
|
||
## 8. Документы и evidence проверок
|
||
|
||
- [ ] 8.1 `evidence/failover/stop-at-start.md`:
|
||
- шапка: сценарии `graceful-shutdown`, change, дата, commit «до» (7)
|
||
и «после» (8), ID образов, лимиты (1 CPU / 512 МиБ, без сети),
|
||
хост;
|
||
- вывод `stop-at-start` «до» (5.2) и «после» (5.9), с пояснением
|
||
классов;
|
||
- строки `rolling-update.sh` ветки сбоя (5.8) и коды выхода старых
|
||
реплик при замене (5.7);
|
||
- вывод: что исправлено и что осталось — окно 0.
|
||
- [ ] 8.2 `evidence/tests/fix-known-issues-checks.md`, в стиле
|
||
`rolling-update-checks.md`. Шапка — change, даты, хэши коммитов 1–11,
|
||
стенды, хост. Разделы:
|
||
- самопроверка `swapouts_delta` (2.2);
|
||
- сверка событий: прогон без помех (3.4), под шумом с частотой
|
||
`docker exec` (3.5), итоговый (3.7), `swapouts_delta` в паспортах;
|
||
- стенд отказов: красный (4.2) и зелёные (4.4) прогоны со сводкой
|
||
журнала, `HostConfig.Init`, `StartedAt` рабочего стенда;
|
||
- консоль (5.6, 5.10);
|
||
- замена под нагрузкой (5.7);
|
||
- красная и зелёная сверка ссылок (6.4, 6.5);
|
||
- регрессия (7.x);
|
||
- `git diff --stat <BASE> HEAD -- src Dockerfile docker-compose.yml
|
||
infra pyproject.toml uv.lock` — только `src/__main__.py`,
|
||
`src/main.py`, `src/infra/early_stop.py`.
|
||
- [ ] 8.3 `KNOWN_ISSUES.md`: пять записей удалить, шапку оставить, плюс
|
||
строка «Открытых записей нет: записи лабы 3 исправлены change
|
||
`fix-known-issues`.» Проверка: `grep -c '^## ' KNOWN_ISSUES.md` → 0.
|
||
- [ ] 8.4 Правила — факты, которые меняет change:
|
||
- `docker.md`, пункт `CMD`: сервер — PID 1, ранний обработчик до
|
||
импорта приложения, почему без `init` у `api`;
|
||
- `run-modes.md`: «Точка входа» (`src/__main__.py` → `early_stop` →
|
||
`src.main:main()`) и пункт SIGTERM — окна A–D и окно 0;
|
||
- `logging.md`: исключение для записи ранней остановки — JSON без
|
||
structlog, поля и почему; строка в таблице «Где логировать»;
|
||
- `infra.md`: пункт про `early_stop.py` — только stdlib, не клиент,
|
||
импортируется до приложения, `disarm()` зовёт lifespan;
|
||
- `balancer.md`, «Сбой на середине»: путь со слотом и без слота;
|
||
- `student-tests.md`:
|
||
- исключения ссылаются на существующие файлы, команды драйвера для
|
||
пересъёмки;
|
||
- стенд отказов: `init: true` у PostgreSQL и проверка журнала;
|
||
- `bench.md`: события фазы `failover` — поток по контейнеру цели;
|
||
`host_state.swapouts_delta` пишется и при 0.
|
||
|
||
Проверка: `grep -n "KNOWN_ISSUES" .claude/rules/*.md` — нет ссылок на
|
||
удалённые записи; каждое изменённое утверждение сверено с кодом.
|
||
- [ ] 8.5 `.claude/skills/run-mtusi-messenger/SKILL.md`: строки таблицы
|
||
команд и примеры для `stop-at-start`, `cache-check`, `auth-storage`.
|
||
Проверка: `python3 .claude/skills/run-mtusi-messenger/driver.py
|
||
--help` перечисляет их, описания совпадают.
|
||
- [ ] 8.6 `AGENTS.md`:
|
||
- вступление: change `fix-known-issues` в перечне и что он
|
||
исправил; число changes в архиве — по факту;
|
||
- таблица команд: `make failure_checks` — проверка журнала
|
||
PostgreSQL;
|
||
- карта кода: `src/__main__.py`, новый `src/infra/early_stop.py`,
|
||
`spec_coverage.py`, `run_failures.py`, `failures.compose.yml`,
|
||
`bench/run.py` (поток событий у `failover` тоже);
|
||
- карта evidence: `evidence/cache/` и `evidence/auth/` — новые
|
||
описания, `evidence/failover/` — `stop-at-start.md`,
|
||
`evidence/tests/` — файл проверок change;
|
||
- «Переход в следующую лабу»: доказательства исключений снимаются
|
||
заново (`make test_isolated` + `cache-check`, `auth-storage`, `make
|
||
test-persistence`, повтор после рестарта API), иначе сверка красная.
|
||
|
||
Проверка: `grep -n "early_stop\|fix-known-issues\|cache-check" AGENTS.md`
|
||
находит новые строки.
|
||
- [ ] 8.7 `REPORT.md`, свежий Read:
|
||
- шапка: `fix-known-issues` в списке «Сделано по changes». Абзац о
|
||
проверке из чистого clone — в 9.3;
|
||
- таблица доказательств — новые строки с командой, наблюдением и
|
||
файлом:
|
||
- остановка реплики во время старта (`stop-at-start.md`);
|
||
- исключения сверки на стенде лабы 3 (`hits.md`,
|
||
`passwords-and-tokens.md`);
|
||
- регрессия `fix-known-issues` (файл проверок).
|
||
|
||
В «Сверке с рубрикой» строку уровня 4 про SIGTERM дополнить;
|
||
- «Эксперименты и отказы»: в таблице ручных отказов строка «`docker
|
||
stop` стартующей реплики» с «до/после». Фразы о `swapouts_delta` со
|
||
ссылкой на `KNOWN_ISSUES.md` (абзац о проверке хоста, раздел «Цена
|
||
масштабирования») — «поле не записано, дефект паспорта исправлен
|
||
change `fix-known-issues`, метки не правились»;
|
||
- «Ограничения и следующие шаги»:
|
||
- «Известные дефекты» — открытых нет, что исправлено;
|
||
- окно 0 — ограничение;
|
||
- «Следующие шаги» без исправленных пунктов;
|
||
- пункт «SIGTERM во время старта реплики теряется» в «Поочерёдная
|
||
замена и миграции» — по решению 7;
|
||
- «Использование ИИ»: восьмой change, решение автора исправить записи
|
||
отдельным change (2026-10-13).
|
||
|
||
Проверка: `grep -n "не исправлены\|evidence лабы 2" REPORT.md` —
|
||
пусто; `grep -n "теряется" REPORT.md` — только про окно 0 (запуск
|
||
интерпретатора).
|
||
- [ ] 8.8 Файлы change: отметки задач из журнала в `tasks.md`; раздел
|
||
«Найдено в apply» в `design.md`, если было что найти.
|
||
- [ ] 8.9 Финал документов:
|
||
- `make lint`, `make check`, `openspec validate fix-known-issues
|
||
--strict` — код 0;
|
||
- grep секретов из 6.3 по новым и изменённым файлам `evidence/` —
|
||
пусто;
|
||
- commit 12.
|
||
|
||
Проверка: дерево чистое.
|
||
|
||
## 9. Итоговая проверка из чистого clone
|
||
|
||
- [ ] 9.1 По разделу `REPORT.md` «Запуск из чистого clone» и образцу
|
||
`evidence/tests/clean-clone-final.md`, на commit 12:
|
||
- рабочий стенд — `docker compose down -v`;
|
||
- `git clone --branch solution/bvt2301-safronov <репозиторий>
|
||
<scratchpad>/fix-known-issues/clean-clone`; `.env`, `config.toml`,
|
||
`.venv` в клоне нет;
|
||
- в клоне: `make env_setup`, `make run_docker`, `docker build
|
||
--no-cache --pull` под отдельным тегом (потом удалить), `make check`,
|
||
`uv sync`, `make validate PYTHON=.venv/bin/python`, `make test`,
|
||
`make instances` (`python3` и `/usr/bin/python3`), `make
|
||
test-persistence` со `StartedAt`, `make test-failover` для каждой
|
||
реплики и `kill`, `make student_test`, `make failure_checks` (со
|
||
сводкой журнала PostgreSQL), `make test_isolated`;
|
||
- уборка: `docker compose down -v` в клоне, хвостов `failures` и
|
||
`test-api` нет; в рабочем репозитории `make run_docker`, `make
|
||
lb_stats`, `make instances`.
|
||
|
||
Все команды — код 0 без правки файлов клона. Сбой — разбор: дефект
|
||
кода или инструкции правится commit и проверка повторяется.
|
||
- [ ] 9.2 `evidence/tests/clean-clone-final.md` — переписать на commit
|
||
12: дата, результаты, «Прошлая такая проверка (commit `dbb9150`) — в
|
||
истории этого файла». Пароли не выводить.
|
||
- [ ] 9.3 `REPORT.md`, свежий Read:
|
||
- шапка: проверенный из чистого clone commit и дата, что менялось
|
||
после него — только документы;
|
||
- строка таблицы доказательств «Итоговая проверка из чистого clone».
|
||
- [ ] 9.4 Финал:
|
||
- отметки 9.x в `tasks.md`;
|
||
- `openspec validate fix-known-issues --strict`;
|
||
- commit 13, дерево чистое;
|
||
- `graphify update .`.
|
||
|
||
Итог apply для основной сессии:
|
||
- хэши коммитов;
|
||
- числа «до/после»: `stop-at-start`, красный и зелёный
|
||
`failure_checks`, сверка событий;
|
||
- проверки хоста;
|
||
- расхождения, если были.
|