@7n/llm-lib 2.8.7 → 2.9.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [2.9.0] - 2026-07-25
+
+### Added
+
+- acp: публічний session-API (create_session/prompt/cancel, стрім SessionEvent, зовнішній permission-responder, опційний post-session config-крок для Pi); one_shot_acp — фасад над session
+- acp: пресети агентів — AcpAgentKind::Pi (npx -y pi-acp), тір-мапи Codex (CODEX_CONFIG luna/terra/sol), Cursor (--model з ефорт-суфіксами), Pi (post-session provider/modelId), UI-лейбли; one_shot_acp_with_tier
+- napi/JS: oneShotAcp(kind, prompt, cwd, {tier}) з kind 'pi', getAcpPresets(), oneShotLocalCloud (Тип 2a, модуль ./local-cloud); model-tiers.mjs: resolveModel — napi-делегація в tiers.rs
+- llm_lib::batch — емуляція Типу 2b (submit → progress → results, чанк 35/конкурентність 2, помилка item не валить batch); napi submitBatch з ThreadsafeFunction-прогресом; JS-модуль ./batch
+
+### Changed
+
+- acp: транспортний шар spawn/init/session виділено в acp/transport.rs (build_acp_args: env-префікси + extra-args), one_shot_acp — тонкий фасад без зміни поведінки
+- Rust-крейти перейменовано: llm-cascade → llm-lib, llm-cascade-napi → llm-lib-napi, CascadeError → LlmError; napi-артефакти llm-lib-napi.`triple`.node; git-споживачам — dependency-alias llm-cascade = { package = "llm-lib" }
+
+### Fixed
+
+- Виправлено profile генерації тестів для survived Stryker-мутантів
+
+## [2.8.8] - 2026-07-24
+
+### Changed
+
+- doc_comments rollout: header-JSDoc у vitest.config
+
 ## [2.8.7] - 2026-07-23
 
 ### Changed

package/lib/acp.mjs

@@ -1,28 +1,36 @@
 /**
- * ACP (Agent Client Protocol, Zed) — доступ до `cursor`/`codex` через
+ * ACP (Agent Client Protocol, Zed) — доступ до `cursor`/`codex`/`pi` через
  * особисту підписку (вже залогінений локально CLI), не API-ключ.
  *
- * Тонкий JS-клієнт до Rust-крейта `llm_cascade::acp` через napi FFI
- * in-process (`llm-lib/crates/llm-cascade-napi`) — жодного власного
+ * Тонкий JS-клієнт до Rust-крейта `llm_lib::acp` через napi FFI
+ * in-process (`llm-lib/crates/llm-lib-napi`) — жодного власного
  * ACP JSON-RPC/`ClientSideConnection` тут; уся протокольна логіка (спавн
- * агента, `session/prompt`, автоапрув `session/request_permission`) живе
- * в Rust, разом з watchdog-поведінкою на мертвий/незапущений дочірній процес.
+ * агента, `session/prompt`, автоапрув `session/request_permission`,
+ * тір→env/args/post-session-config резолвінг) живе в Rust, разом з
+ * watchdog-поведінкою на мертвий/незапущений дочірній процес.
  *
- * `claude` тут немає — Rust-крейт моделює лише `cursor`/`codex`
+ * `claude` тут немає — Rust-крейт моделює лише `cursor`/`codex`/`pi`
  * (`AcpAgentKind`); deprecated `claude`-раннер лишається окремим
  * JS-шимом у `@7n/rules` (`npm/scripts/lib/acp-runner.mjs`).
  */
 import { loadNative } from './internal/native.mjs'
 
 /**
- * Один виклик через ACP-агента з особистою підпискою.
- * @param {'cursor' | 'codex'} kind провайдер
+ * Один виклик через ACP-агента з особистою підпискою. `tier` (задача T5,
+ * рішення И) — опційний абстрактний тир (`min`/`avg`/`max`): якщо заданий,
+ * Rust сам резолвить tier→env/args/post-session-config з пресету агента
+ * (`one_shot_acp_with_tier`) — жодного JS-хелпера "пресет→env" тут немає.
+ * Без `tier` — стара поведінка (модель = персональний конфіг CLI на машині).
+ * @param {'cursor' | 'codex' | 'pi'} kind провайдер
  * @param {string} prompt промпт
  * @param {string} cwd робочий каталог сесії агента (каталог проєкту-викликача)
- * @param {{ native?: { oneShotAcp: (kind: string, prompt: string, cwd: string) => Promise<string> } }} [deps] інжект для тестів
+ * @param {{
+ *   tier?: 'min' | 'avg' | 'max',
+ *   native?: { oneShotAcp: (kind: string, prompt: string, cwd: string, tier?: string) => Promise<string> }
+ * }} [options] тир + інжект `native` для тестів (той самий 4-й аргумент, що й раніше — сумісність зі старим `{ native }`-викликом збережена)
  * @returns {Promise<string>} повний текст відповіді до кінця ходу
  */
-export function runAcpAgent(kind, prompt, cwd, deps = {}) {
-  const native = deps.native ?? loadNative()
-  return native.oneShotAcp(kind, prompt, cwd)
+export function runAcpAgent(kind, prompt, cwd, { tier, native } = {}) {
+  const nativeImpl = native ?? loadNative()
+  return nativeImpl.oneShotAcp(kind, prompt, cwd, tier)
 }

package/lib/agent-fix.mjs

@@ -150,34 +150,61 @@ async function runVerifyLoop({ session, verify, verifyMax, timeoutMs, startedAt,
  * правкою (хардкод значення, симуляція поведінки) — промпт явно це забороняє, а
  * verdict-veto consumer-а (re-check) відхиляє такі правки поза target-файлами.
  * @param {{ ruleId: string, violation: string, ruleText?: string, feedback?: object,
- *   targetFiles?: string[] }} args параметри промпта; `targetFiles` — файли порушення,
- *   єдині наявні файли, які дозволено редагувати (порожньо/відсутнє — без переліку).
+ *   targetFiles?: string[], sourceFiles?: string[], editMode?: 'generic'|'test-generation' }} args параметри промпта.
+ *   У generic-режимі `targetFiles` — єдині наявні файли, які дозволено редагувати.
+ *   `test-generation` відділяє read-only source-контекст від test-файлів, які агент
+ *   може знайти, створити або змінити.
  * @returns {string} промпт
  */
-export function buildFixPrompt({ ruleId, violation, ruleText, feedback, targetFiles, anchoredEdits = false }) {
+export function buildFixPrompt({
+  ruleId,
+  violation,
+  ruleText,
+  feedback,
+  targetFiles,
+  sourceFiles,
+  editMode = 'generic',
+  anchoredEdits = false
+}) {
   const parts = [`Виправ порушення правила "${ruleId}" у цьому проєкті.`]
   if (ruleText) parts.push(`## Правило\n${ruleText}`)
   parts.push(`## Порушення\n${violation}`)
-  if (Array.isArray(targetFiles) && targetFiles.length > 0) {
+  if (editMode === 'generic' && Array.isArray(targetFiles) && targetFiles.length > 0) {
     parts.push(
       '## Target-файли (єдині наявні файли, які дозволено редагувати)\n' + targetFiles.map(f => `- ${f}`).join('\n')
     )
   }
+  if (editMode === 'test-generation' && Array.isArray(sourceFiles) && sourceFiles.length > 0) {
+    parts.push('## Source-файли (лише для читання)\n' + sourceFiles.map(f => `- ${f}`).join('\n'))
+  }
   if (feedback?.previousError) {
     parts.push(`## Попередня спроба не спрацювала\n${feedback.previousError}\nСпробуй інший підхід.`)
   }
-  parts.push(
-    '## Обмеження (обовʼязкові)\n' +
-      'Дозволені ЛИШЕ механічні зміни, що прямо усувають наведене порушення правила:\n' +
-      '- НЕ змінюй бізнес-логіку і поведінку коду.\n' +
-      '- НЕ хардкодь значення замість викликів функцій чи обчислень.\n' +
-      '- НЕ симулюй і не заглушуй поведінку (stub/mock/"simulate").\n' +
-      '- НЕ редагуй наявні файли поза порушенням; нові файли створюй лише якщо цього прямо вимагає правило.\n' +
-      'Якщо порушення не усувається механічною правкою — зупинись, нічого не змінюючи.',
-    'Перед редагуванням JS/TS-файлу спершу виклич `ast_facts` на ньому. ' +
-      'Після правок виклич `self_check`, щоб підтвердити, що порушення зникло. ' +
-      'Редагуй лише потрібне, не чіпай стороннє.'
-  )
+  if (editMode === 'test-generation') {
+    parts.push(
+      '## Обмеження test-generation (обовʼязкові)\n' +
+        '- Source-файли — лише контекст для читання; НЕ редагуй production source або його поведінку.\n' +
+        '- Знайди, створи або зміни лише повʼязані `*.test.*` / `*.spec.*` файли, зокрема у test-каталогах.\n' +
+        '- Для ізоляції unit-тесту дозволені звичайні Vitest mock/stub, якщо вони не змінюють production-код.\n' +
+        '- Новий тест мусить перевіряти поведінку, що вбиває описаний мутант; не маскуй його ignore/exclude.\n' +
+        'Якщо неможливо написати коректний тест без зміни production source — зупинись, нічого не змінюючи.',
+      'Перед редагуванням JS/TS test-файлу спершу прочитай потрібний контекст. ' +
+        'Після правок виклич `self_check` і запусти релевантні Vitest-тести. Редагуй лише потрібні test-файли.'
+    )
+  } else {
+    parts.push(
+      '## Обмеження (обовʼязкові)\n' +
+        'Дозволені ЛИШЕ механічні зміни, що прямо усувають наведене порушення правила:\n' +
+        '- НЕ змінюй бізнес-логіку і поведінку коду.\n' +
+        '- НЕ хардкодь значення замість викликів функцій чи обчислень.\n' +
+        '- НЕ симулюй і не заглушуй поведінку (stub/mock/"simulate").\n' +
+        '- НЕ редагуй наявні файли поза порушенням; нові файли створюй лише якщо цього прямо вимагає правило.\n' +
+        'Якщо порушення не усувається механічною правкою — зупинись, нічого не змінюючи.',
+      'Перед редагуванням JS/TS-файлу спершу виклич `ast_facts` на ньому. ' +
+        'Після правок виклич `self_check`, щоб підтвердити, що порушення зникло. ' +
+        'Редагуй лише потрібне, не чіпай стороннє.'
+    )
+  }
   if (anchoredEdits) {
     parts.push(
       'Наявні файли читай і редагуй ЛИШЕ через `read_anchored` → `edit_anchored` ' +
@@ -283,7 +310,7 @@ async function defaultCreateSession({
  * @param {{
  *   model: string, tier?: string, feedback?: object, caller?: string, timeoutMs?: number, ruleText?: string,
  *   chain?: object,
- *   targetFiles?: string[],
+ *   targetFiles?: string[], sourceFiles?: string[], editMode?: 'generic'|'test-generation',
  *   verify?: (args: { touchedFiles: string[] }) => Promise<{ ok: boolean, output?: string }> | { ok: boolean, output?: string },
  *   verifyMax?: number,
  *   anchoredEdits?: boolean,
@@ -306,6 +333,8 @@ export async function runAgentFix(ruleId, violation, cwd, opts = {}) {
     ruleText,
     chain = null,
     targetFiles,
+    sourceFiles,
+    editMode = 'generic',
     verify = null,
     verifyMax = VERIFY_MAX_DEFAULT,
     anchoredEdits = false,
@@ -418,7 +447,16 @@ export async function runAgentFix(ruleId, violation, cwd, opts = {}) {
     }
   })
 
-  const fixPrompt = buildFixPrompt({ ruleId, violation, ruleText, feedback, targetFiles, anchoredEdits })
+  const fixPrompt = buildFixPrompt({
+    ruleId,
+    violation,
+    ruleText,
+    feedback,
+    targetFiles,
+    sourceFiles,
+    editMode,
+    anchoredEdits
+  })
   const pHash = promptHash(fixPrompt)
   const startedAt = clock()
   let error = null
@@ -458,6 +496,9 @@ export async function runAgentFix(ruleId, violation, cwd, opts = {}) {
     stepUsage.output += t.usage?.output ?? 0
     stepUsage.totalTokens += t.usage?.totalTokens ?? 0
   }
+  // Повна відповідь без tool-call і записів — окремо позначаємо: usage не є
+  // єдиним критерієм, бо деякі провайдери його не віддають.
+  const emptyCompletion = toolCallCount === 0 && touchedFiles.length === 0
   chain?.note({ model: modelSpec, usage: stepUsage, error })
   trace({
     caller,
@@ -478,6 +519,8 @@ export async function runAgentFix(ruleId, violation, cwd, opts = {}) {
     turnCount,
     toolCallCount,
     touchedFiles,
+    usage: stepUsage,
+    emptyCompletion,
     backstopHit,
     verifyAttempts: verifyAttempts.length,
     verifyOk: verifyAttempts.length > 0 ? verifyAttempts.at(-1).ok : null,
@@ -494,9 +537,11 @@ export async function runAgentFix(ruleId, violation, cwd, opts = {}) {
     model: modelSpec,
     promptHash: pHash,
     prompt: fixPrompt,
-    output: { touchedFiles, edits: guard.state.editLog },
+    output: { touchedFiles, edits: guard.state.editLog, emptyCompletion },
     usage: stepUsage,
     error
   })
+  telemetry.emptyCompletion = emptyCompletion
+  telemetry.usage = stepUsage
   return { applied: touchedFiles.length > 0, touchedFiles, telemetry, error, rollback: guard.rollback }
 }

package/lib/batch.mjs

@@ -0,0 +1,72 @@
+/**
+ * Тип 2b (OpenAI-сумісний API, batch) — **лише емуляція** у v1 (рішення Р,
+ * задача T6): чанкований конкурентний прогін через Тип 2a
+ * (`llm_lib::local_cloud`) під інтерфейсом `submit → progress → results` —
+ * той самий інтерфейс, яким говорив би й справжній OpenAI Batch API
+ * (`/v1/batches`, v2), якому локальний omlx (перший споживач) не має.
+ *
+ * Тонкий JS-клієнт до Rust-крейта `llm_lib::batch` через napi FFI
+ * in-process (`llm-lib/crates/llm-lib-napi`) — жодного власного чанкінгу
+ * тут (анти-приклад, якого це узагальнює: `mlmail/use-summary.js` чанкує
+ * переклади проти omlx вручну, з вистражданими лімітами).
+ */
+import { loadNative } from './internal/native.mjs'
+
+/**
+ * Один item вхідного batch-у.
+ * @typedef {{ customId: string, prompt: string, system?: string }} BatchItem
+ */
+
+/**
+ * Результат одного item — рівно одне з `ok`/`error` заповнене.
+ * @typedef {{ customId: string, ok?: string, error?: string }} BatchResult
+ */
+
+/**
+ * Емуляція batch-виклику Типу 2b. `modelSpecOrTier` — той самий контракт,
+ * що й у [`oneShotLocalCloud`] з `local-cloud.mjs`: явний
+ * `"provider/model-id"` або абстрактний тир (`min`/`avg`/`max`).
+ * @param {string} modelSpecOrTier `"provider/model-id"` або `'min'|'avg'|'max'`
+ * @param {BatchItem[]} items вхідні items (`customId` — унікальний у межах виклику)
+ * @param {{
+ *   localProviders?: Record<string, { baseUrl: string, apiKey?: string | null }>,
+ *   system?: string,
+ *   chunkSize?: number,
+ *   concurrency?: number,
+ *   onProgress?: (completed: number, total: number) => void,
+ *   native?: {
+ *     submitBatch: (
+ *       modelSpecOrTier: string,
+ *       items: Array<{ customId: string, prompt: string, system?: string }>,
+ *       options?: object,
+ *       config?: object,
+ *       onProgress?: (completed: number, total: number) => void
+ *     ) => Promise<BatchResult[]>
+ *   }
+ * }} [options] конфіг локальних провайдерів, ліміти чанка/конкурентності, progress-колбек, інжект `native` для тестів
+ * @returns {Promise<BatchResult[]>} результати в тому самому порядку, що й вхідні `items`
+ */
+export function submitBatch(
+  modelSpecOrTier,
+  items,
+  { localProviders, system, chunkSize, concurrency, onProgress, native } = {}
+) {
+  const nativeImpl = native ?? loadNative()
+  return nativeImpl.submitBatch(
+    modelSpecOrTier,
+    items.map(item => ({
+      customId: item.customId,
+      prompt: item.prompt,
+      system: item.system ?? undefined
+    })),
+    {
+      localProviders: localProviders ?? undefined,
+      system: system ?? undefined
+    },
+    {
+      chunkSize: chunkSize ?? undefined,
+      concurrency: concurrency ?? undefined
+    },
+    onProgress ?? undefined
+  )
+}

package/lib/docs/acp.md

@@ -3,29 +3,33 @@ type: JS Module
 title: acp.mjs
 resource: llm-lib/lib/acp.mjs
 docgen:
-  crc: 5c32e90c
+  crc: 587f1966
   model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
   score: 100
-  issues: judge:inaccurate:0.97
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Файл надає тонкий JS-доступ до `cursor` або `codex` через публічну `runAcpAgent`, покладаючись на вже авторизовану локальну CLI-сесію без API-ключів. Уся ACP-логіка живе в нативному Rust-шарі `llm_cascade::acp`, який викликається in-process через `napi FFI` у `llm-lib/crates/llm-cascade-napi`; тут немає власного `ClientSideConnection` чи JSON-RPC. Саме Rust запускає агента, обробляє `session/prompt`, автоматично погоджує `session/request_permission` і стежить за живістю дочірнього процесу. Крейт підтримує лише `cursor`/`codex`; `claude`-runner лишається окремим JS-шимом у `@7n/rules` (`npm/scripts/lib/acp-runner.mjs`).
+Публічна точка входу `runAcpAgent` для запуску ACP-агента `cursor`, `codex` або `pi` через локально залогінений CLI без API-ключа. Це тонкий JS-міст до `llm_lib::acp` у `llm-lib/crates/llm-lib-napi`, без власної ACP JSON-RPC чи `ClientSideConnection` логіки; протокольна поведінка, `session/prompt`, `session/request_permission`, `tier→env/args/post-session-config` resolving і watchdog на мертвий або незапущений дочірній процес зосереджені в Rust. `AcpAgentKind` охоплює лише `cursor`/`codex`/`pi`; `claude` тут відсутній, а deprecated `claude`-runner лишається окремим JS-шимом у `@7n/rules` (`npm/scripts/lib/acp-runner.mjs`).
 
 ## Поведінка
 
-1. `runAcpAgent` запускає один ACP-хід для `cursor` або `codex` через вже авторизовану локальну CLI-сесію, без API-ключів.
-2. Вона звертається до нативного Rust-шару `llm_cascade::acp`, який бере на себе весь протокол взаємодії: старт агента, обмін `session/prompt`, автоапрув запитів на дозвіл і контроль живості дочірнього процесу.
-3. Вона передає робочий каталог поточного проєкту як контекст сесії, щоб агент працював у межах каталогу викликача.
-4. Вона повертає повний текст відповіді агента за один хід.
-5. Вона не виконує власну протокольну логіку, не працює з `claude`, і не покладається на `ClientSideConnection`; підтримка `claude` живе окремо в JS-шимі `npm/scripts/lib/acp-runner.mjs`.
+1. `runAcpAgent` запускає один запит до ACP-агента з особистою підпискою для `cursor`, `codex` або `pi` у межах поточного робочого каталогу.
+2. Якщо задано `tier`, передає цю абстракцію в нативний шар, щоб далі саме Rust визначив відповідні параметри сесії для вибраного агента.
+3. Якщо `tier` не задано, використовує стандартну поведінку персонально залогіненого CLI без окремого вибору рівня.
+4. Для виконання звертається до нативної реалізації в процесі, яка вже містить протокольну логіку, запуск сесії та обробку дозволів; цей файл не реалізує власний ACP-обмін і не працює з `claude`.
+5. Повертає повний текст відповіді агента після завершення одного ходу.
 
 ## Публічний API
 
-- runAcpAgent — запускає один запит через ACP-агента з власною підпискою
+- runAcpAgent — Один виклик через ACP-агента з особистою підпискою. `tier` (задача T5,
+рішення И) — опційний абстрактний тир (`min`/`avg`/`max`): якщо заданий,
+Rust сам резолвить tier→env/args/post-session-config з пресету агента
+(`one_shot_acp_with_tier`) — жодного JS-хелпера "пресет→env" тут немає.
+Без `tier` — стара поведінка (модель = персональний конфіг CLI на машині).
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/lib/docs/agent-fix.md

@@ -3,32 +3,26 @@ type: JS Module
 title: agent-fix.mjs
 resource: llm-lib/lib/agent-fix.mjs
 docgen:
-  crc: 83a189d4
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: 907ba309
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 55
+  issues: no-overview,short-behavior,best-of-2:retry-lost
 ---
 
-## Огляд
-
-Модуль ініціює процес виправлення порушень правил. Він створює відповідний промпт для агента через функцію `buildFixPrompt` та запускає цикл взаємодії з агентом за допомогою `runAgentFix`. Процес працює з механізмом перехоплення помилок (fail-safe), гарантуючи відсутність винятків на виході.
-
-## Поведінка
-
-Поведінка:
-buildFixPrompt готує текстовий промпт, що містить інструкції для агента щодо виправлення порушення правила.
-runAgentFix виконує повний агентний цикл для спроби виправлення порушення правила, включаючи взаємодію з інструментами, застосування патча та фіксацію телеметрії.
-Виклик сесії огорнутий timeout-гонкою: `opts.timeoutMs` (дефолт 300s, коли consumer не передав значення) на спрацюванні abort-ить сесію і повертає помилку `fix timeout …` — зависла LLM-сесія (напр. мертва SSE) не блокує виклик назавжди.
-
-Web-профіль (опційний `opts.webTools`, Фаза A3): додає read-only tools `web_search`/`web_fetch` (див. web-tools.md; SSRF-guard, ліміти розміру) — для правил із зовнішнім знанням на cloud-тирах; прапорець у трейсі, дефолт вимкнено.
-
-Anchored-профіль (опційний `opts.anchoredEdits`, Фаза A2): toolset сесії заміняє built-in `read`/`edit` на строгі `read_anchored`/`edit_anchored` (див. anchored-edit.md; `write` лишається для нових файлів, під тим самим write-guard), а промпт отримує інструкцію anchored-циклу. Прапорець фіксується у трейсі (`anchoredEdits`) для A/B-аналізу; дефолт вимкнено.
-
-Evidence-гейт (опційний `opts.verify`, Фаза A1 run-harness): після prompt-у модуль сам запускає canonical-перевірку consumer-а; провал інʼєктиться фідбеком у ту саму сесію — до `opts.verifyMax` додаткових ітерацій (дефолт 2), у межах того самого `timeoutMs` (залишок бюджету < 5s — чесна зупинка без ітерації). Гейт структурний: заяви агента про успіх не важать, джерелом правди лишається зовнішня перевірка. Помилка самої перевірки — інфраструктурна: ітерації не витрачаються, повертається `error` з префіксом `verify:`. Без `verify` — поведінка попередня (один прохід). Спроби фіксуються у `telemetry.verifyAttempts` і у trace (`verifyAttempts`, `verifyOk`).
-
 ## Публічний API
 
-buildFixPrompt — формує інструкцію для виправлення проблеми, включаючи відповідне правило, описане порушення, опційний перелік target-файлів (єдині наявні файли, які дозволено редагувати) та можливий відгук з попередньої невдалої спроби; містить обовʼязковий блок обмежень semantic-collateral guard (лише механічні зміни: без зміни бізнес-логіки, без хардкоду значень, без симуляції поведінки — spec pi-migration §12, addendum 2026-07-05) і директиву щодо кроків перед редагуванням та самоперевірки.
-buildVerifyFeedbackPrompt — формує фідбек-повідомлення verify-ітерації: точний вивід canonical-перевірки + нагадування обмежень semantic-collateral guard.
-runAgentFix — виконує єдину спробу виправлення коду з боку агента для заданого правила, використовуючи вказані параметри (модель, рівень, зворотний зв'язок, verify-гейт, тощо) та ін'єкції для тестування.
+- buildVerifyFeedbackPrompt — Будує фідбек-prompt verify-ітерації: точний вивід canonical-перевірки + нагадування
+обмежень (той самий semantic-collateral guard, що й у buildFixPrompt).
+- buildFixPrompt — Будує fix-промпт для рунга: правило + порушення + (опц.) target-файли + (опц.) feedback
+попереднього провалу + жорсткий блок обмежень (лише механічні зміни) + інструкція
+«ast_facts перед edit, self_check після».
+
+Блок обмежень — перший шар semantic-collateral guard (спека pi-migration §12,
+addendum 2026-07-05): слабкі локальні моделі схильні «виправляти» правило семантичною
+правкою (хардкод значення, симуляція поведінки) — промпт явно це забороняє, а
+verdict-veto consumer-а (re-check) відхиляє такі правки поза target-файлами.
+- runAgentFix — Проводить ОДНУ агентну fix-спробу (рунг) для правила.
 
 ## Гарантії поведінки
 

package/lib/docs/batch.md

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: batch.mjs
+resource: llm-lib/lib/batch.mjs
+docgen:
+  crc: 4412e8c2
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Тонкий JS-клієнт до `llm_lib::batch` у `llm-lib/crates/llm-lib-napi`, який через in-process `napi FFI` лише емулює Type 2b у v1: під одним `submit → progress → results` інтерфейсом він прокидає batch-запит у `llm_lib::local_cloud` і повертає результат як сумісний OpenAI Batch API-контракт для майбутнього `/v1/batches`. Єдина публічна точка входу — `submitBatch`. Це узагальнення анти-прикладу на кшталт `mlmail/use-summary.js`, де чанкінг доводиться робити вручну під обмеження провайдера.
+
+## Поведінка
+
+1. `submitBatch` приймає batch-запит для Type 2b і передає його в native-реалізацію, щоб отримати той самий бізнес-інтерфейс `submit → progress → results`, який очікується від batch-потоку поверх локальних провайдерів.
+2. `submitBatch` зберігає порядок вхідних items у результатах, щоб кожен результат можна було зіставити з початковим `customId`.
+3. `submitBatch` нормалізує вхідні items перед передачею далі: бере `customId` і `prompt` як є, а відсутній `system` не підміняє значенням.
+4. `submitBatch` передає конфіг локальних провайдерів, загальний `system`, а також ліміти chunking і concurrency у native-шар, щоб контроль виконання залишався в реалізації batch-крейта.
+5. `submitBatch` підтримує `onProgress`, щоб викликати повідомлення про хід виконання під час обробки batch-у.
+6. `submitBatch` дозволяє підмінити native-реалізацію для тестів, не змінюючи зовнішню поведінку публічного API.
+
+## Публічний API
+
+- submitBatch — Емуляція batch-виклику Типу 2b. `modelSpecOrTier` — той самий контракт,
+що й у [`oneShotLocalCloud`] з `local-cloud.mjs`: явний
+`"provider/model-id"` або абстрактний тир (`min`/`avg`/`max`).
+
+## Гарантії поведінки
+
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/lib/docs/index.md

@@ -10,10 +10,12 @@ resource: llm-lib/lib/
 | [agent-fix.mjs](agent-fix.md)             | JS Module |
 | [agent-skill.mjs](agent-skill.md)         | JS Module |
 | [anchored-edit.mjs](anchored-edit.md)     | JS Module |
+| [batch.mjs](batch.md)                     | JS Module |
 | [body-capture.mjs](body-capture.md)       | JS Module |
 | [chain.mjs](chain.md)                     | JS Module |
 | [chains-report.mjs](chains-report.md)     | JS Module |
 | [harness.mjs](harness.md)                 | JS Module |
+| [local-cloud.mjs](local-cloud.md)         | JS Module |
 | [model-tiers.mjs](model-tiers.md)         | JS Module |
 | [one-shot.mjs](one-shot.md)               | JS Module |
 | [prompt-budget.mjs](prompt-budget.md)     | JS Module |

package/lib/docs/local-cloud.md

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: local-cloud.mjs
+resource: llm-lib/lib/local-cloud.mjs
+docgen:
+  crc: fc09aee2
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Надає Node-доступ до одного OpenAI-сумісного запиту `chat/completions` для локального або хмарного провайдера через спільний Rust-шар. `oneShotLocalCloud` існує як тонкий JS-вхід до `llm_lib::local_cloud` через `napi FFI in-process` у `llm-lib/crates/llm-lib-napi`, щоб визначення моделей, конфігурація локальних провайдерів і HTTP-взаємодія залишалися в єдиній реалізації без окремого клієнта в JS і без агентського циклу.
+
+## Поведінка
+
+1. `oneShotLocalCloud` приймає запит на один OpenAI-сумісний chat-виклик для локального або хмарного провайдера без агентського циклу.
+2. Визначає цільову модель як явну специфікацію провайдера або як абстрактний тир, щоб використовувати спільне правило резолву моделей із Rust-шару.
+3. Передає текст користувача, optional system-повідомлення та конфігурацію локальних провайдерів до in-process Rust-клієнта через napi FFI.
+4. Делегує HTTP-взаємодію з OpenAI-compatible ендпоінтом Rust-реалізації, щоб у JS-шарі не виникало окремого клієнта й розрізненого читання `settings.json`.
+5. Повертає текст відповіді моделі як результат одного синхронного за сценарієм запиту.
+
+## Публічний API
+
+- oneShotLocalCloud — Один chat-виклик Типу 2a. `modelSpecOrTier` — або явний `"provider/model-id"`,
+або абстрактний тир (`min`/`avg`/`max`, рішення К), що резолвиться в Rust
+через ту саму [`llm_lib::resolve_model`], що й `resolveModel` з
+`model-tiers.mjs`.
+
+## Гарантії поведінки
+
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/lib/docs/model-tiers.md

@@ -3,39 +3,61 @@ type: JS Module
 title: model-tiers.mjs
 resource: llm-lib/lib/model-tiers.mjs
 docgen:
-  crc: ba67ab5c
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: 13970c1f
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 100
+  issues: judge-refine:kept-original,judge:inaccurate:0.97
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Цей модуль відповідає за тир-політику моделей: env-параметри для локальних (`LOCAL_MIN` по `LOCAL_MAX`) та хмарних (`CLOUD_MIN` по `CLOUD_MAX`) моделей, каскадну резолюцію тиру в специфікатор (`resolveModel`), визначення рівня мислення за rung-тиром (`thinkingLevelForTier`) і розбір специфікаторів (`parseModelId`). Модуль повністю substrate-free і pure; доступ до pi ModelRegistry живе окремо в internal-модулі [registry](../internal/docs/registry.md).
+Модуль централізує вибір і нормалізацію LLM-моделей для local та cloud tier значень. Він дає спільну точку для розбору і форматування model spec, визначення локальності моделі та зіставлення tier із рівнем thinking.
 
 ## Поведінка
 
-Поведінка:
-LOCAL_MIN — надає конфігураційне значення для мінімальної локальної моделі.
-LOCAL_AVG — надає конфігураційне значення для середньої локальної моделі.
-LOCAL_MAX — надає конфігураційне значення для максимальної локальної моделі.
-CLOUD_MIN — надає конфігураційне значення для мінімальної хмарної моделі.
-CLOUD_AVG — надає конфігураційне значення для середньої хмарної моделі.
-CLOUD_MAX — надає конфігураційне значення для максимальної хмарної моделі.
-resolveModel — визначає шлях до моделі на основі вибраного рівня (min, avg, max) за каскадною політикою.
-thinkingLevelForTier — визначає відповідний дискретний рівень мислення залежно від rung-тиру моделі.
-parseModelId — розбиває специфікатор моделі у форматі `"provider/model-id"` на окремі частини.
+Модуль задає спільну env-політику вибору моделей через LOCAL_MIN, LOCAL_AVG, LOCAL_MAX, CLOUD_MIN, CLOUD_AVG і CLOUD_MAX. Ці значення є вхідним станом для подальшого резолву та класифікації: порожнє значення означає, що відповідний tier не заданий явно.
+
+resolveModel приймає абстрактний tier і повертає фактичний model spec у форматі pi. Вибір делегується нативному шару, щоб JavaScript-споживачі отримували той самий каскад, що й Rust-частина. Якщо каскад не знаходить явної моделі, результатом стає порожній рядок, який залишає вибір дефолтної моделі нижчому шару.
+
+parseModelId і formatModelSpec підтримують єдиний формат обміну між конфігурацією, результатами resolveModel і pi-моделями. parseModelId відкидає некоректні або неповні model spec, а formatModelSpec перетворює фактично вибрану pi-модель назад у той самий текстовий формат для подальшого порівняння чи логування.
+
+isLocalModel використовує спільні LOCAL_* значення та список локальних провайдерів з оточення, щоб визначити, чи фактично вибрана або явно задана модель є локальною. Для цього результат resolveModel або formatModelSpec може бути переданий у isLocalModel після нормалізації через спільний формат.
+
+thinkingLevelForTier працює з rung-рівнями escalation-ланцюжка й повертає дискретний рівень thinking для виконання запиту. Це рішення незалежне від env-конфігурації моделей, але використовується поруч із resolveModel у потоках, де одночасно обираються модельний tier і інтенсивність міркування.
+
+Файл не виконує власних операцій запису у ФС чи БД; результати передаються назовні як значення для споживачів LLM-шару. Імпортовані модулі не аналізувались.
 
 ## Публічний API
 
-LOCAL_MIN — Забезпечує швидке виконання моделей без використання хмарних сервісів.
-LOCAL_AVG — Надає середні можливості локальних моделей для виконання завдань.
-LOCAL_MAX — Дозволяє використовувати найпотужніші доступні локальні моделі.
-CLOUD_MIN — Забезпечує мінімальний рівень продуктивності від хмарних моделей, вимагає підключення через `pi auth`.
-CLOUD_AVG — Використовує середній за можливостями хмарний двигун.
-CLOUD_MAX — Дозволяє отримати максимальну якість від хмарних моделей.
-resolveModel — Визначає найкращу модель для виконання, обираючи між локальними та хмарними варіантами залежно від запитуваного рівня (`min`, `avg`, `max`).
-thinkingLevelForTier — Призначає відповідний рівень обробки (`low`, `medium`, `high`) на основі обраного рівня моделі для коректної роботи з пам'яттю та ресурсами.
-parseModelId — Розбирає загальний рядок ідентифікатора моделі у дві частини: назву постачальника та його ідентифікатор.
+- LOCAL_MIN — Швидкий локальний inference. Напр.: omlx/gemma-4-e4b-it-OptiQ-4bit
+- LOCAL_AVG — Середній локальний.
+- LOCAL_MAX — Максимальний локальний.
+- CLOUD_MIN — Мінімальний хмарний (потрібен ключ у pi auth). Напр.: openai/gpt-5.4-mini
+- CLOUD_AVG — Середній хмарний. Напр.: openai/gpt-5.4
+- CLOUD_MAX — Максимальний хмарний. Напр.: openai/gpt-5.5
+- resolveModel — Каскадне розв'язання абстрактного тиру в `"provider/model-id"` —
+napi-делегація в `llm_lib::resolve_model` (задача T5, рішення Е): та сама
+логіка, що й Rust-каскад у `tiers.rs`:
+  'min' → LOCAL_MIN → LOCAL_AVG → LOCAL_MAX → CLOUD_MIN
+  'avg' → LOCAL_AVG → LOCAL_MAX → CLOUD_AVG
+  'max' → LOCAL_MAX → CLOUD_MAX
+Тир валідується тут (не в Rust) — щоб зберегти контракт `TypeError` для
+невідомого тиру без потреби мапити помилку з napi-боку.
+- thinkingLevelForTier — `thinkingLevel` за rung-тиром fix-драбини: слабка локальна — `low`,
+cloud-min — `medium`, cloud-avg — `high`, cloud-max (experiment-only tier,
+не в production ladder) — `xhigh`.
+- parseModelId — Розбирає `"provider/model-id"` у пару. Перший `/` — роздільник (model-id може
+містити власні `/`). Порожній провайдер чи id → `null` (malformed).
+- formatModelSpec — Форматує pi `Model`-об'єкт (`{provider, id}`) назад у `"provider/model-id"`.
+Інверсія {@link parseModelId} — застосовується до фактично резолвленої
+pi-моделі (`session.model`), коли consumer лишив `modelSpec` порожнім і pi
+сам вибрав дефолт (локальний чи хмарний).
+- isLocalModel — Чи model-spec вказує на локальну модель: збіг з одним із LOCAL_* тирів
+АБО провайдер з `N_LLM_LOCAL_PROVIDERS` (дефолт `omlx`). Використовується
+для local/cloud-агрегатів ланцюжків і рішення про chain-заголовки.
 
 ## Гарантії поведінки
 
-- (специфічних машинно-виведених гарантій немає)
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/lib/internal/docs/native.md

@@ -3,28 +3,31 @@ type: JS Module
 title: native.mjs
 resource: llm-lib/lib/internal/native.mjs
 docgen:
-  crc: 205418d5
+  crc: 655cb048
   model: openai-codex/gpt-5.5
+  tier: cloud-avg
   score: 100
-  issues: judge:inaccurate:0.98
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Файл знаходить і завантажує native-аддон `llm-cascade`, щоб JavaScript-код використовував Rust-ядро через napi-артефакт. `resolveNativeAddon` визначає шлях за єдиним порядком: явний override `N_LLM_LIB_NATIVE_ADDON`, platform-підпакет `@7n/llm-lib-<platform>-<arch>` з артефактом `llm-cascade-napi.<triple>.node`, dev-fallback у `target/release|debug/` після `cargo build -p llm-cascade-napi` або вивід у `llm-lib/crates/llm-cascade-napi/`. `loadNative` завантажує знайдений аддон через `process.dlopen` і кешує результат у межах процесу. На непідтриманих платформах запуск зупиняється зрозумілою помилкою без JS-fallback.
+Файл підʼєднує Rust/NAPI native addon для `llm-lib` і є єдиною точкою вибору джерела: явний override через `N_LLM_LIB_NATIVE_ADDON`, платформний npm-пакет `@7n/llm-lib-<platform>-<arch>` з артефактом `llm-lib-napi.<triple>.node` або локальна dev-збірка. Публічні API `resolveNativeAddon` і `loadNative` потрібні, щоб споживачі отримували native exports з однаковою поведінкою в інсталяції, CI, тестах і локальній розробці. Завантаження виконується через `process.dlopen`, тому підтримуються і `.node`, і сирі cdylib (`.dylib`/`.so`); результат кешується як одне завантаження на процес. Непідтримані платформи завершуються зрозумілою помилкою без прихованого JS fallback.
 
 ## Поведінка
 
-- `resolveNativeAddon` визначає шлях до native-аддона `llm-cascade`: спершу бере явний override, далі шукає platform-підпакет, потім локальні dev-збірки; для непідтриманої або незібраної платформи завершується зрозумілою помилкою без JS-fallback.
-- `loadNative` завантажує native-аддон один раз за процес і повертає закешовані exports для повторних викликів.
+`loadNative` отримує шлях від `resolveNativeAddon`, завантажує знайдений native addon і повертає його exports споживачам `llm-lib`. Результат завантаження зберігається в памʼяті процесу, тому наступні звернення повторно використовують той самий addon без нового пошуку та відкриття файлу.
+
+`resolveNativeAddon` визначає джерело native addon за єдиним порядком пріоритетів: явний шлях із середовища для dev/CI/тестів, платформний npm-підпакет для підтримуваної платформи, локальні dev-збірки Rust/NAPI, а потім помилка з інструкцією для користувача. Це дає однакову поведінку для встановленого пакета, локальної розробки й тестових сценаріїв.
+
+Якщо платформа не входить до свідомо підтриманих у v1 комбінацій, JavaScript fallback не використовується: потік завершується hard error. Це фіксує межу підтримки native-ядра замість прихованої деградації поведінки.
 
 ## Публічний API
 
-- resolveNativeAddon — знаходить файл native addon `llm-cascade` для поточного середовища або тестових підмін.
-- loadNative — повертає native addon із кешу, щоб завантажувати його лише один раз за час роботи процесу.
+- resolveNativeAddon — Резолвить шлях до napi-аддона `llm-lib`.
+- loadNative — Кешований доступ до аддона (одне завантаження на процес).
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.
 - Кешує результати в межах одного прогону.

package/lib/internal/native.mjs

@@ -1,14 +1,14 @@
 /**
- * Loader napi-аддона `llm-cascade` (Rust-ядро `llm-lib/crates/llm-cascade-napi`
- * → `llm-cascade`) — за зразком `mt/npm/lib/core/native.mjs`.
+ * Loader napi-аддона `llm-lib` (Rust-ядро `llm-lib/crates/llm-lib-napi`
+ * → `llm-lib`) — за зразком `mt/npm/lib/core/native.mjs`.
  *
  * Порядок пошуку:
  *   1. N_LLM_LIB_NATIVE_ADDON — явний override шляху до аддона (dev / CI / тести).
  *   2. Platform-підпакет `@7n/llm-lib-<platform>-<arch>` (napi-артефакт
- *      `llm-cascade-napi.<triple>.node`).
+ *      `llm-lib-napi.<triple>.node`).
  *   3. Dev-fallback: `<repoRoot>/target/release|debug/` (сирий cdylib з
- *      `cargo build -p llm-cascade-napi`) та вивід `napi build` у
- *      `llm-lib/crates/llm-cascade-napi/`.
+ *      `cargo build -p llm-lib-napi`) та вивід `napi build` у
+ *      `llm-lib/crates/llm-lib-napi/`.
  *   4. Інакше — зрозуміла помилка з підказкою.
  *
  * Аддон завантажується через `process.dlopen` — працює і для `.node`, і для
@@ -48,16 +48,16 @@ function dlopenAddon(p) {
 }
 
 /**
- * Ім'я cdylib-файлу для платформи (вивід `cargo build -p llm-cascade-napi`).
+ * Ім'я cdylib-файлу для платформи (вивід `cargo build -p llm-lib-napi`).
  * @param {string} platform process.platform
  * @returns {string} ім'я бібліотеки
  */
 function cdylibName(platform) {
-  return platform === 'darwin' ? 'libllm_cascade_napi.dylib' : 'libllm_cascade_napi.so'
+  return platform === 'darwin' ? 'libllm_lib_napi.dylib' : 'libllm_lib_napi.so'
 }
 
 /**
- * Резолвить шлях до napi-аддона `llm-cascade`.
+ * Резолвить шлях до napi-аддона `llm-lib`.
  * @param {{
  *   env?: Record<string, string | undefined>,
  *   platform?: string,
@@ -86,7 +86,7 @@ export function resolveNativeAddon(deps = {}) {
   // 2. Platform-підпакет.
   if (suffix) {
     try {
-      return requireResolve(`@7n/llm-lib-${key}/llm-cascade-napi.${suffix}.node`)
+      return requireResolve(`@7n/llm-lib-${key}/llm-lib-napi.${suffix}.node`)
     } catch {
       // не встановлено — пробуємо dev-fallback
     }
@@ -97,7 +97,7 @@ export function resolveNativeAddon(deps = {}) {
     join(repoRoot, 'target', profile, cdylibName(platform))
   )
   if (suffix) {
-    candidates.push(join(repoRoot, 'llm-lib', 'crates', 'llm-cascade-napi', `llm-cascade-napi.${suffix}.node`))
+    candidates.push(join(repoRoot, 'llm-lib', 'crates', 'llm-lib-napi', `llm-lib-napi.${suffix}.node`))
   }
   for (const candidate of candidates) {
     if (exists(candidate)) return candidate
@@ -105,9 +105,9 @@ export function resolveNativeAddon(deps = {}) {
 
   // 4. Помилка з підказкою.
   throw new Error(
-    `llm-cascade native addon: немає збірки для "${key}". ` +
+    `llm-lib native addon: немає збірки для "${key}". ` +
       `Постав N_LLM_LIB_NATIVE_ADDON=/шлях/до/аддона, додай підпакет @7n/llm-lib-${key}, ` +
-      `або збери локально: cargo build --release -p llm-cascade-napi`
+      `або збери локально: cargo build --release -p llm-lib-napi`
   )
 }
 

package/lib/local-cloud.mjs

@@ -0,0 +1,33 @@
+/**
+ * Тип 2a (OpenAI-сумісний API, sync) для Node — прямий HTTP до OpenAI-compatible
+ * ендпоінта (`chat/completions`): локальні провайдери (напр. omlx) і хмарні
+ * (стандартна автентифікація провайдера) — без агентського циклу.
+ *
+ * Тонкий JS-клієнт до Rust-крейта `llm_lib::local_cloud` через napi FFI
+ * in-process (`llm-lib/crates/llm-lib-napi`) — жодного власного HTTP-клієнта
+ * тут (анти-приклад, якого це уникає: `mlmail` читає `~/.omlx/settings.json`
+ * і б'є в ендпоінт напряму замість спільної точки, задача T5/рішення Н).
+ */
+import { loadNative } from './internal/native.mjs'
+
+/**
+ * Один chat-виклик Типу 2a. `modelSpecOrTier` — або явний `"provider/model-id"`,
+ * або абстрактний тир (`min`/`avg`/`max`, рішення К), що резолвиться в Rust
+ * через ту саму [`llm_lib::resolve_model`], що й `resolveModel` з
+ * `model-tiers.mjs`.
+ * @param {string} modelSpecOrTier `"provider/model-id"` або `'min'|'avg'|'max'`
+ * @param {string} prompt user-репліка
+ * @param {{
+ *   localProviders?: Record<string, { baseUrl: string, apiKey?: string | null }>,
+ *   system?: string,
+ *   native?: { oneShotLocalCloud: (modelSpecOrTier: string, prompt: string, options?: object) => Promise<string> }
+ * }} [options] конфіг локальних провайдерів (`omlx` тощо), system-репліка, інжект `native` для тестів
+ * @returns {Promise<string>} текст відповіді моделі
+ */
+export function oneShotLocalCloud(modelSpecOrTier, prompt, { localProviders, system, native } = {}) {
+  const nativeImpl = native ?? loadNative()
+  return nativeImpl.oneShotLocalCloud(modelSpecOrTier, prompt, {
+    localProviders: localProviders ?? undefined,
+    system: system ?? undefined
+  })
+}

package/lib/model-tiers.mjs

@@ -3,9 +3,12 @@
 /**
  * Тир-конфіг моделей для LLM-шару (@7n/llm-lib) і його consumers.
  *
- * Тири — політика споживача (які env-моделі = який тир); резолвінг у Model-обʼєкт
- * substrate-у живе окремо в [internal/registry] — цей модуль substrate-free і
- * повністю pure, юніт-тестується без pi.
+ * Каскадне розв'язання тиру ({@link resolveModel}) — задача T5, рішення Е
+ * (ОНОВЛЕНЕ 2026-07-24): канон живе в Rust-крейті `llm_lib::tiers`
+ * (`llm-lib/crates/llm-lib/src/tiers.rs`), тут — тонка napi-делегація
+ * (`internal/native.mjs`), жодного власного каскаду. Інші утиліти модуля
+ * (парсинг spec, класифікація local/cloud, thinkingLevel) не мають
+ * Rust-відповідника — лишаються pure JS, substrate-free.
  *
  * Формат значень env — `"provider/model-id"` (pi-формат), напр.:
  *   N_LOCAL_MIN_MODEL=omlx/gemma-4-e4b-it-OptiQ-4bit
@@ -14,6 +17,7 @@
  */
 
 import { env } from 'node:process'
+import { loadNative } from './internal/native.mjs'
 
 // ── Тири (env-політика) ──────────────────────────────────────────────────────
 
@@ -30,20 +34,29 @@ export const CLOUD_AVG = env.N_CLOUD_AVG_MODEL ?? ''
 /** Максимальний хмарний. Напр.: openai/gpt-5.5 */
 export const CLOUD_MAX = env.N_CLOUD_MAX_MODEL ?? ''
 
+/** Валідні тири — та сама множина, що й `parse_tier` у napi-крейті. */
+const KNOWN_TIERS = new Set(['min', 'avg', 'max'])
+
 /**
- * Каскадне розв'язання абстрактного тиру в `"provider/model-id"`:
+ * Каскадне розв'язання абстрактного тиру в `"provider/model-id"` —
+ * napi-делегація в `llm_lib::resolve_model` (задача T5, рішення Е): та сама
+ * логіка, що й Rust-каскад у `tiers.rs`:
  *   'min' → LOCAL_MIN → LOCAL_AVG → LOCAL_MAX → CLOUD_MIN
  *   'avg' → LOCAL_AVG → LOCAL_MAX → CLOUD_AVG
  *   'max' → LOCAL_MAX → CLOUD_MAX
+ * Тир валідується тут (не в Rust) — щоб зберегти контракт `TypeError` для
+ * невідомого тиру без потреби мапити помилку з napi-боку.
  * @param {'min'|'avg'|'max'} tier тир
+ * @param {{ native?: { resolveModel: (tier: string) => string | null } }} [deps] інжект `native` для тестів
  * @returns {string} `"provider/model-id"` або `''` (дефолт провайдера substrate)
  * @throws {TypeError} якщо tier невідомий
  */
-export function resolveModel(tier) {
-  if (tier === 'min') return LOCAL_MIN || LOCAL_AVG || LOCAL_MAX || CLOUD_MIN
-  if (tier === 'avg') return LOCAL_AVG || LOCAL_MAX || CLOUD_AVG
-  if (tier === 'max') return LOCAL_MAX || CLOUD_MAX
-  throw new TypeError(`resolveModel: unknown tier "${tier}". Use 'min', 'avg', or 'max'.`)
+export function resolveModel(tier, deps = {}) {
+  if (!KNOWN_TIERS.has(tier)) {
+    throw new TypeError(`resolveModel: unknown tier "${tier}". Use 'min', 'avg', or 'max'.`)
+  }
+  const native = deps.native ?? loadNative()
+  return native.resolveModel(tier) ?? ''
 }
 
 // ── Escalation-rung → thinkingLevel ──────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/llm-lib",
-  "version": "2.8.7",
+  "version": "2.9.0",
   "description": "Тонкий шар роботи з LLM (локальні omlx + хмарні провайдери) поверх pi: model tiers, one-shot, agentic-раннери, write-guard, trace, telemetry, prompt-budget",
   "keywords": [
     "nitra",
@@ -37,6 +37,8 @@
     "./web-tools": "./lib/web-tools.mjs",
     "./model-tiers": "./lib/model-tiers.mjs",
     "./acp": "./lib/acp.mjs",
+    "./local-cloud": "./lib/local-cloud.mjs",
+    "./batch": "./lib/batch.mjs",
     "./chain": "./lib/chain.mjs",
     "./chains-report": "./lib/chains-report.mjs",
     "./one-shot": "./lib/one-shot.mjs",
@@ -53,8 +55,8 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@7n/llm-lib-darwin-arm64": "2.8.7",
-    "@7n/llm-lib-linux-x64": "2.8.7"
+    "@7n/llm-lib-darwin-arm64": "2.9.0",
+    "@7n/llm-lib-linux-x64": "2.9.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "~0.80.10",