---
type: JS Module
title: orchestrator.mjs
resource: npm/scripts/lib/fix/orchestrator.mjs
docgen:
  crc: d327ab6d
  model: omlx/gemma-4-e4b-it-OptiQ-4bit
  score: 100
---

Модуль керує процесом валідації та виправлення конформності правил. Він перевіряє правила, застосовує детермінований механізм (T0), а нерозв'язані порушення проводить по **драбині ескалації моделей**: локальна min-модель → той самий локальний тир із feedback → хмарна min → хмарна avg. Кожен крок драбини логується для подальшого аналізу. Функція `runOrchestratorCli` запускає процес.

## Поведінка

1. `runOrchestratorCli` виконує початкову перевірку правил. Якщо порушень немає — успіх.
2. Один прохід детермінованого фіксу (T0) зменшує набір порушень без LLM.
3. `buildLadder` будує драбину з доступних тирів (`N_LOCAL_MIN_MODEL`, `N_CLOUD_MIN_MODEL`, `N_CLOUD_AVG_MODEL`); незадані тири відсіюються. Якщо драбина порожня — процес завершується з ознакою нерозв'язаних порушень.
4. `escalateRule` проводить кожне правило по драбині до першого зеленого re-check:
   - рунг `local-min` — перший прохід без feedback;
   - рунг `local-min-retry` — той самий локальний тир, але з feedback попереднього рунга (попередні зміни + залишковий violation);
   - рунги `cloud-min` / `cloud-avg` — хмарні моделі (через pi), теж із feedback.
   Кожен рунг має per-tier `timeoutMs`: локальні **fail-fast** (`N_LOCAL_FIX_TIMEOUT_MS`, дефолт 45s — не палити стіну 120s на повільному локальному inference), хмарні — повний (`N_CLOUD_FIX_TIMEOUT_MS`, дефолт 120s).
5. Достроковий вихід драбини: systemic-помилка локального тиру пропускає рунги тієї ж моделі; відсутній API-ключ на хмарному обриває драбину; хмарний транспортний збій (pi таймаут/spawn) обриває драбину, щоб не палити avg-бюджет на ту саму стіну; вичерпаний avg-кеп пропускає avg-рунг (із записом у лог).
6. Після обробки всіх правил — фінальна перевірка. Усі чисті → успіх; інакше — ознака нерозв'язаних.

## Публічний API

- `buildLadder({ localMin, cloudMin, cloudAvg })` — будує драбину рунгів із наявних тирів.
- `escalateRule(rule, cwd, deps)` — проводить одне правило по драбині; повертає `{ resolved, avgUsed }`. Залежності (`worker`, `check`, `clock`) інжектовні для тестів.
- `parseOrchestratorArgs(args)` — парсить `--max-avg N` (кеп на хмарні avg-виклики) і фільтр правил.
- `runOrchestratorCli(args, cwd)` — точка входу; повертає `0` (усе чисто) або `1` (нерозв'язані).

## Гарантії поведінки

- Кожен рунг драбини дописується в escalation-лог (`escalation-log.mjs`): модель, чи виклик удався, чи правило стало зеленим, залишковий violation і само-аналіз моделі.
- Звертається до мережі лише на хмарних рунгах драбини (через pi).
