# STATE MODEL — где лежит состояние Tachyon

Сводка по всем персистентным и оперативным состояниям: что где хранится, какой
срок жизни, кто владеет и что происходит при потере. Документация = фактический
код; расхождение — баг этого документа.

Три класса по времени жизни:

- **tmpfs (`/var/run`)** — оперативное, теряется при перезагрузке намеренно;
- **overlay/flash (`/etc`, `/usr/lib`)** — конфигурация и эталон;
- **в памяти процесса** — не переживает рестарт.

---

## 1. Конфигурация и эталон (flash)

| Путь | Что | Владелец |
|---|---|---|
| `/etc/config/tachyon` | основной UCI, **chmod 600** | `config/validator.uc` |
| `/etc/tachyon/state/known_good/` | эталон Last Known Good | `service/known_good.uc` |
| `/etc/tachyon/smart_detect_seen.json` | домены, уже проверенные Smart Detect | `service/watchdog.uc` |
| `/etc/tachyon/rag_index.json` | пользовательский индекс RAG (перекрывает встроенный) | `diagnostics/rag.uc` |
| `/etc/tachyon/keys/tachyon-release.pub` | публичный ключ релиза | сборка |
| `/usr/lib/tachyon/rag_index.json` | встроенный индекс RAG | `tools/rag_build_index.sh` |

### Почему `chmod 600`

`/etc/config/tachyon` содержит `telegram.bot_token` и `agent_api_token`.
`package_postinst` ставит 600 и `chown root:root` при каждой установке —
права не должны «разъезжаться» после обновления.

### Last Known Good

```
/etc/tachyon/state/known_good/
  manifest.json      версия, время промоушена, причина, sha256, ядро, метрики
  config             атомарная копия /etc/config/tachyon
  history.json       кольцо событий смены состояния
  last_failed_config конфиг, сохранённый перед откатом (для посмертного анализа)
```

Отдельное наблюдение и окно: `/var/run/tachyon/observation_state.json` (tmpfs).
Если активный конфиг уже совпадает с LKG, окно не взводится — иначе система
каждые 60 секунд «наблюдала бы» саму себя.

**Loop guard:** откат отклоняется, если активный конфиг по хешу уже совпадает с
LKG. Без этого два отказа подряд превращались бы в бесконечное перекатывание
конфигурации туда-обратно.

---

## 2. Оперативное состояние (tmpfs)

Каталог по умолчанию `/var/run/tachyon` (переопределяется
`TACHYON_RUNTIME_STATE_DIR`).

| Файл | Что | Потеря означает |
|---|---|---|
| `events.jsonl` | кольцо событий | теряется история диагностики |
| `observation_state.json` | окно наблюдения | окно наблюдения начнётся заново |
| `smart_detect` стрики | подтверждение двух замеров | +1 цикл подтверждения |
| `section-cache/*.json` | нормализованные ссылки и urltest-группы | пересобирается из подписок |
| `dns-failover.json` | позиция резолвера | сброс на основной DNS |
| `selector_state.json` | выбранный узел в группе | сброс на первый рабочий |
| `emergency_state.json` (+ `/tmp`) | аварийный режим | сброс флага |
| `tx/<tx_id>/` | снапшоты незавершённых транзакций | откат придётся делать вручную |

### Почему tmpfs

Всё это — производное состояние, которое дешевле пересоздать, чем
восстанавливать, и всё это упирается в RAM устройства с 128 МБ. Исключение —
`tx/`: там снапшоты, и их **нельзя** терять до `COMMIT`, иначе откат
невозможен (см. `TRANSACTION_ENGINE.md`, раздел «Снапшоты»).

`events.jsonl` и `emergency_state.json` дублируются в `/tmp` на случай
read-only `/var/run` — без фолбэка диагностика и аварийный флаг молча
переставали бы работать.

### Межпроцессная видимость

Почти всё это читается **разными процессами** (`/usr/bin/tachyon` из UI,
watchdog-воркер, Telegram-бот). Отсюда два правила:

- запись атомарна (tmp + `mv`), иначе параллельный читатель увидит обрезанный JSON;
- чтение кэшируется по `boot_id` + `starttime` процесса, а не по времени
  (через `core/process.uc`) — иначе PID recycling отдаёт устаревший кэш.

---

## 3. Состояние в памяти процесса

| Место | Что | Почему не на диске |
|---|---|---|
| watchdog: `smart_detect_streaks` | первый неудачный замер по домену | потеря стоит одного цикла подтверждения; запись на flash не окупается |
| watchdog: `trace_hosts` | имя хоста по trace-id соединения | нужно только на время жизни соединения (секунды) |
| event_controller: `dns_consecutive_fails`, `*_history` | стрики сбоев и история задержек | переживать рестарт не нужно: наблюдение, а не результат |
| job: стек компенсаций | откат текущей операции | живёт вместе с воркером; на диске держится в state-файле задачи |

Общий принцип: **на flash попадает только то, что дорого пересоздать**
(эталонный конфиг, список проверенных доменов) **или то, что переживает
перезагрузку осмысленно** (конфиг). Всё остальное — производное.

`trace_hosts` дополнительно ограничен по размеру (`TRACE_HOSTS_MAX` = 256) и
по времени жизни (`TRACE_HOST_TTL` = 300 с): иначе связка «вспомнили имена всех
соединений роутера» превратилась бы в утечку памяти на долгом аптайме.

---

## 4. Идентичность процесса

Отдельный слой, который стоит понимать вместе с состоянием.

```ucode
{ pid, starttime, boot_id }
```

`starttime` — поле 22 в `/proc/<pid>/stat`, `boot_id` — `/proc/sys/kernel/random/boot_id`.

Любая проверка «жив ли процесс» обязана использовать тройку, а не `pid`.
Пользовательский PID переиспользуется: без `starttime` вчерашняя задача
выглядит живой сегодня. Это касается задач, транзакций, ядер, демонов-секций и
воркеров.

---

## 5. Карта «кто что читает»

| Состояние | Пишет | Читает |
|---|---|---|
| `observation_state.json` | watchdog | watchdog, UI |
| `known_good/manifest.json` | `known_good.uc` | reconciler, watchdog, UI, AI Doctor |
| `section-cache/` | `tachyon_core/generator_outbounds.uc` | UI-дашборд, генератор |
| `smart_detect_seen.json` | watchdog | watchdog |
| `selector_state.json` | UI, Telegram | генераторы, Clash-эмуляция |
| `dns-failover.json` | `tachyon_core/dns_failover.uc` | watchdog, UI |
| `events.jsonl` | шина | UI, `eventClient`, support bundle, AI Doctor |
| `tx/<id>/` | `core/transaction.uc` | `transaction.uc recover`, watchdog |

---

## 6. Связанные документы

- `TRANSACTION_ENGINE.md` — снапшоты, откат, компенсации
- `JOB_ENGINE.md` — state-файл задачи, heartbeat, кооперативная отмена
- `EVENTS.md` — кольцевой журнал и санитизация секретов
- `RECONCILER.md` — сверка желаемого и фактического состояния
