# TRANSACTION ENGINE — `core/transaction.uc`

Транзакционный движок: любая последовательность изменений (файлов, UCI,
состояния демонов) либо применяется целиком, либо откатывается целиком.
926 строк, экспортируется через `module_exports()`.

Документ описывает фактический код.

---

## 1. Зачем

Проблема, которую он решает, формулируется так: **как сделать набор изменений
обратимым, если часть из них необратима**. `rm` файла, `uci commit`, `systemctl
restart` — их нельзя «отменить», можно только восстановить заранее снятое
состояние.

Отсюда правило: перед мутацией снимается снапшот, после мутации регистрируется
компенсация, компенсации выполняются в обратном порядке.

---

## 2. Фазы

```
PLAN → PREFLIGHT → SNAPSHOT → MUTATE → VALIDATE → ACTIVATE → VERIFY → COMMIT
```

| Фаза | Что происходит | Откат |
|---|---|---|
| `PLAN` | описание намерения, ничего не меняется | — |
| `PREFLIGHT` | проверки ресурсов и предпосылок (через `core/preflight.uc`) | — |
| `SNAPSHOT` | снятие снапшотов того, что сейчас будет изменено | — |
| `MUTATE` | сами изменения | компенсации по ходу |
| `VALIDATE` | проверка результата | `ROLLBACK` |
| `ACTIVATE` | перезапуск сервиса / применение | `ROLLBACK` |
| `VERIFY` | проверка, что после активации всё живо | `ROLLBACK` + `VERIFY_ROLLBACK` |
| `COMMIT` | фиксация, снапшоты удаляются | — |

Путь отказа: `FAIL → ROLLBACK → VERIFY_ROLLBACK → ROLLED_BACK`, либо `FAILED`,
если откат сам не удался и систему пришлось оставить в промежуточном состоянии
(это фиксируется явно, а не прячется).

`SNAPSHOT` идёт **до** `MUTATE` — иначе снять было бы уже поздно.

---

## 3. Встроенные компенсаторы

| Компенсатор | Что восстанавливает |
|---|---|
| `restore_file` | содержимое файла **и права** (`chmod`) |
| `remove_file` | файл, созданный транзакцией (снапшота не было — значит и откатывать нечем, достаточно удалить) |
| `restore_uci` | состояние UCI + `uci revert` / `uci commit` |
| `command` | shell-команда отката |
| `callback` | in-memory замыкание |

`restore_uci` делает `revert` перед `commit`: без `revert` в staged-дереве
остаются изменения, которых не было в снапшоте.

---

## 4. LIFO-стек

Компенсации выполняются в строгом обратном порядке. Это не стилистика:
если изменили `A`, затем `B`, то откат обязан сначала вернуть `B` — откат `A`
может инвалидировать состояние, ещё не откаченное.

---

## 5. Снапшоты

Снапшоты файлов и UCI пишутся в `/var/run/tachyon/tx/<tx_id>/snapshots/`.

**Содержимое не буферизуется в памяти** — используется `cp -p`. На компактных
роутерах буферизация в RAM (а конфиг `tachyon-core` может занимать сотни КБ) давала бы
реальный OOM в процессе, который пытается *починить* систему.

`COMMIT` удаляет снапшоты: `/var/run` — tmpfs, и оставленные снапшоты съедали бы
RAM на устройстве с 128 МБ.

---

## 6. Привязка к process identity

Транзакция помнит, кто её начал: `pid` + `starttime` + `boot_id` (через
`core/process.uc`). `is_stale(tx)` отличает «воркер упал» от «воркер жив».

Двухуровневая устойчивость: движок работает и внутри процесса, и восстанавливается
из `tx.json` **после** падения — либо собственным `recover`, либо вызовом из
watchdog, либо извне через CLI. Транзакция, пережившая смерть владельца, всё
ещё должна быть откатана, иначе система остаётся в промежуточном состоянии
навсегда.

---

## 7. API

Два уровня, оба рабочие:

```ucode
// декларативно
transaction.run(name, steps, opts)

// пошагово
tx.step(phase, fn)
```

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

---

## 8. CLI

```
core/transaction.uc <selftest|list|query|rollback|gc>
```

`rollback` — ручной откат по id. Нужен, когда откат не сработал автоматически:
это последний ручной инструмент до `known_good`.

---

## 9. Интеграции

- **`core/preflight.uc`** — `preflight_validator(opts)` верифицирует ресурсы на
  фазе `PREFLIGHT`, отменяя транзакцию **до** любых мутаций при дефиците.
- **`core/jobs.uc`** — задачи регистрируют транзакционные изменения как компенсации
  в свой LIFO-стек.
- **`core/known_good.uc`** — хранит эталонный конфиг, к которому откатывается
  `reconciler` при неустранимом сбое.
- **`core/logging.uc`** — логирование с `subsystem: "core.transaction"`.

---

## 10. Тесты

`tests/transaction_engine.sh` — 13 проверок: константы фаз, валидация фаз,
счастливый путь, откат при сбое `validate` и `verify`, удаление созданных файлов,
строгий порядок LIFO, определение устаревания, `list`/`query` с фильтрами,
`gc`, CLI.
