# RECONCILER — `service/reconciler.uc`

Движок сверки желаемого и фактического состояния с точечным ремонтом: чинит
расхождения **без перезапуска ядра и без разрыва активных соединений**, где это
возможно. 1213 строк, экспортируется через `module_exports()`.

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

---

## 1. Зачем

Watchdog historically реагировал на симптом и до цели: «DNS не работает» →
`/etc/init.d/tachyon reload`. Это работает, но дорого — рестарт рвёт соединения,
и если причина в одном демоне, весь стек встаёт зря.

Reconciler разделяет вопрос на три:

1. **что должно быть** — из UCI и активного движка;
2. **что есть** — опрос ядра, procd, ubus, nftables, PID-файлов;
3. **чем чинить** — минимальное действие, устраняющее конкретное расхождение.

---

## 2. Желаемое состояние

`get_desired_state()` строит декларативную модель **пяти подсистем**:

| Подсистема | Источник ожиданий |
|---|---|
| `engine` | `settings.engine` (`tachyon-core`) |
| `dns` | `settings.dns_*`, `nft`-перехват |
| `nftables` | сеты Tachyon, tproxy-правила, приоритетные цепочки |
| `routing` | `ip rule` / `ip route`, таблица `tachyon` |
| `daemons` | активные секции действий |

---

## 3. Фактическое состояние

`get_actual_state()` — опрос реальной системы:

- детект ядра (`tachyon-core`) **с защитой от PID recycling** через
  `core/process.uc`;
- dnsmasq, перехват DNS Tachyon, локальный резолвинг;
- наличие nft-таблицы `TachyonTable` и заполненность базовых
  сетов (`localv4`, `localv6`, `tachyon_subnets`, `tachyon_ports`,
  `tachyon_ip_ports`);
- `ip rule` по fwmark и маршруты;
- запущенность встроенных и вспомогательных сервисов (например, `fptn`, нативного `tailscale`, `torrserver`).

---

## 4. Движок расхождений

`diff_state()` возвращает типизированные расхождения с приоритетом
(`critical`, `high`, `medium`, `low`) и **привязкой к конкретному действию**:
`repair_dns`, `repair_nft_sets`, `repair_engine` и так далее.

Привязка к действию — то, что отличает reconciler от «просто перезапустить».
`plan()` без `apply()` показывает, что именно изменится, то есть работает как
встроенный dry-run.

---

## 5. Ремонт

| Действие | Что делает | Рвёт соединения? |
|---|---|---|
| `repair_dns` | перезапуск dnsmasq при падении, повторное применение редиректа, SIGHUP кэша | нет |
| `repair_nftables` | точечное пересоздание таблицы при сдутом fw4, дозаполнение сетов | нет |
| `repair_routing` | восстановление недостающих `ip rule` и маршрутов | нет |
| `repair_daemons` | изолированный перезапуск одного упавшего демона | нет |
| `repair_engine` | перезапуск только ядра | да |

`repair_dns` принципиально не трогает ядро `tachyon-core`: именно этот сценарий
(«DNS отвалился») раньше разрушал рабочую прокси-маршрутизацию целиком.

---

## 6. Порядок выполнения

```
engine → daemons → routing → nftables → dns
```

Порядок неочевиден и обязателен. Движок должен быть живым, прежде чем мы
чиним то, что он маршрутизирует; демоны — раньше правил, которые на них
ссылаются; маршруты — раньше nft, который в них помечает. Ремонт в обратном
порядке даёт вторую волну расхождений на каждом проходе.

---

## 7. Транзакции и события

Каждая фаза ремонта обёрнута в `core/transaction`, поэтому неудачный ремонт
откатывается, а не оставляет половину. Старт, успех и провал пишутся в журнал
событий:

`reconcile.drift_detected`, `reconcile.started`, `reconcile.repaired`,
`reconcile.failed`.

---

## 8. Реакция на события

`reconcile_event()` — прямая реакция на факты шины, без ожидания тика:

| Факт | Действие |
|---|---|
| `dns.down` | `repair_dns` |
| `nft.missing` | `repair_nftables` |
| `core.stopped` | `repair_engine` |
| `firewall.reloaded` | `repair_nftables` + `repair_routing` |

Реакция на событие дешевле реакции на тик: не ждём следующего опроса.

---

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

- при чистом плане — `known_good.check_observation()`, чтобы окно наблюдения
  продвигалось и эталонное состояние могло быть повышено;
- при неустранимом сбое ремонта `engine`, `nftables` или `routing` — откат к
  Last Known **до** аварийного режима.

---

## 10. CLI

```
tachyon reconciler <desired|actual|plan|status|apply [subsystem] [dry-run]|event <name> [dry-run]|selftest>
```

Алиасы: `reconcile`, `reconcile_plan`, `reconcile_status`.

`apply` без `dry-run` обязателен как отдельное действие: ремонт меняет
работающую систему, и «случайно применённый» план на `critical`-расхождении
обрывает соединения.

---

## 11. Тесты

`tests/reconciler.sh` — синтаксис, selftest (19 проверок), изоляция подсистем,
CLI dry-run, диспетчеризация событий.
