@7n/llm-lib 2.14.15 → 2.14.16

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [2.14.16] - 2026-08-04
+
+### Fixed
+
+- Loader napi-аддона (`lib/internal/native.mjs`) у вихідному дереві репо (маркер `llm-lib/crates/llm-lib-napi/Cargo.toml`) резолвить локальну збірку `target/release|debug` ПЕРЕД опублікованим підпакетом `@7n/llm-lib-<platform>-<arch>` — раніше свіжий `cargo build -p llm-lib-napi` мовчки перекривався registry-бінарем із `node_modules`, і правки Rust-ядра не проявлялися. У встановленому пакеті порядок незмінний: підпакет лишається авторитетним джерелом
+
 ## [2.14.15] - 2026-08-04
 
 ### Fixed

package/lib/internal/docs/native.md

@@ -3,30 +3,50 @@ type: JS Module
 title: native.mjs
 resource: llm-lib/lib/internal/native.mjs
 docgen:
-  crc: 655cb048
-  model: openai-codex/gpt-5.5
-  tier: cloud-avg
-  score: 100
-  judgeModel: openai-codex/gpt-5.4-mini
+  crc: 35a583cb
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min
+  score: 70
 ---
 
 ## Огляд
 
-Файл підʼєднує 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.
-
-## Поведінка
-
-`loadNative` отримує шлях від `resolveNativeAddon`, завантажує знайдений native addon і повертає його exports споживачам `llm-lib`. Результат завантаження зберігається в памʼяті процесу, тому наступні звернення повторно використовують той самий addon без нового пошуку та відкриття файлу.
-
-`resolveNativeAddon` визначає джерело native addon за єдиним порядком пріоритетів: явний шлях із середовища для dev/CI/тестів, платформний npm-підпакет для підтримуваної платформи, локальні dev-збірки Rust/NAPI, а потім помилка з інструкцією для користувача. Це дає однакову поведінку для встановленого пакета, локальної розробки й тестових сценаріїв.
-
-Якщо платформа не входить до свідомо підтриманих у v1 комбінацій, JavaScript fallback не використовується: потік завершується hard error. Це фіксує межу підтримки native-ядра замість прихованої деградації поведінки.
+Loader napi-аддона `llm-lib` (Rust-ядро `llm-lib/crates/llm-lib-napi`
+→ `llm-lib`) — за зразком `mt/npm/lib/core/native.mjs`.
+
+Порядок пошуку (залежить від оточення — див. [`isSourceTree`]):
+  1. N_LLM_LIB_NATIVE_ADDON — явний override шляху до аддона (dev / CI / тести).
+  2. **Лише у вихідному дереві** (`<repoRoot>/llm-lib/crates/llm-lib-napi/Cargo.toml`
+     існує): локальна збірка `<repoRoot>/target/release|debug/` (сирий cdylib
+     з `cargo build -p llm-lib-napi`) та вивід `napi build` у
+     `llm-lib/crates/llm-lib-napi/`.
+  3. Platform-підпакет `@7n/llm-lib-<platform>-<arch>` (napi-артефакт
+     `llm-lib-napi.<triple>.node`).
+  4. Той самий fallback на локальну збірку поза вихідним деревом
+     (у продакшені поведінка така сама, як до фіксу).
+  5. Інакше — зрозуміла помилка з підказкою.
+
+ЧОМУ порядок різний (симетрично до `npm/scripts/lib/native.mjs`, фікс
+2026-08-03): у репо локальний `cargo build -p llm-lib-napi` мовчки
+перекривався опублікованим підпакетом із `node_modules` — правки Rust-ядра
+не проявлялися, а «фейли LLM-контуру» діагностувалися як помилки коду.
+У користувача ж підпакет — єдине авторитетне джерело (запінений lockstep до
+версії `@7n/llm-lib`), тож сторонній `target/` поруч не має його перебивати.
+
+Аддон завантажується через `process.dlopen` — працює і для `.node`, і для
+сирих cdylib (`.dylib`/`.so`). Результат кешується (одне завантаження на процес).
+Без JS-fallback на неоголошеній платформі — hard error, свідома межа v1
+(darwin-arm64, linux-x64), не регресія.
 
 ## Публічний API
 
 - resolveNativeAddon — Резолвить шлях до napi-аддона `llm-lib`.
 - loadNative — Кешований доступ до аддона (одне завантаження на процес).
 
+## Сценарії використання
+
+- `llm-lib/tests/native.test.mjs` (resolveNativeAddon (порядок пошуку); resolveNativeAddon (вихідне дерево vs прод)) — N_LLM_LIB_NATIVE_ADDON має найвищий пріоритет; platform-підпакет: резолвиться @7n/llm-lib-<key> з napi-суфіксом; linux-x64 мапиться на суфікс linux-x64-gnu; dev-fallback: release-cdylib перемагає debug; dev-fallback: на linux шукається .so, а останній кандидат — вивід napi build; ще 6
+
 ## Гарантії поведінки
 
 - Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/lib/internal/native.mjs

@@ -2,14 +2,24 @@
  * Loader napi-аддона `llm-lib` (Rust-ядро `llm-lib/crates/llm-lib-napi`
  * → `llm-lib`) — за зразком `mt/npm/lib/core/native.mjs`.
  *
- * Порядок пошуку:
+ * Порядок пошуку (залежить від оточення — див. [`isSourceTree`]):
  *   1. N_LLM_LIB_NATIVE_ADDON — явний override шляху до аддона (dev / CI / тести).
- *   2. Platform-підпакет `@7n/llm-lib-<platform>-<arch>` (napi-артефакт
- *      `llm-lib-napi.<triple>.node`).
- *   3. Dev-fallback: `<repoRoot>/target/release|debug/` (сирий cdylib з
- *      `cargo build -p llm-lib-napi`) та вивід `napi build` у
+ *   2. **Лише у вихідному дереві** (`<repoRoot>/llm-lib/crates/llm-lib-napi/Cargo.toml`
+ *      існує): локальна збірка `<repoRoot>/target/release|debug/` (сирий cdylib
+ *      з `cargo build -p llm-lib-napi`) та вивід `napi build` у
  *      `llm-lib/crates/llm-lib-napi/`.
- *   4. Інакше — зрозуміла помилка з підказкою.
+ *   3. Platform-підпакет `@7n/llm-lib-<platform>-<arch>` (napi-артефакт
+ *      `llm-lib-napi.<triple>.node`).
+ *   4. Той самий fallback на локальну збірку поза вихідним деревом
+ *      (у продакшені поведінка така сама, як до фіксу).
+ *   5. Інакше — зрозуміла помилка з підказкою.
+ *
+ * ЧОМУ порядок різний (симетрично до `npm/scripts/lib/native.mjs`, фікс
+ * 2026-08-03): у репо локальний `cargo build -p llm-lib-napi` мовчки
+ * перекривався опублікованим підпакетом із `node_modules` — правки Rust-ядра
+ * не проявлялися, а «фейли LLM-контуру» діагностувалися як помилки коду.
+ * У користувача ж підпакет — єдине авторитетне джерело (запінений lockstep до
+ * версії `@7n/llm-lib`), тож сторонній `target/` поруч не має його перебивати.
  *
  * Аддон завантажується через `process.dlopen` — працює і для `.node`, і для
  * сирих cdylib (`.dylib`/`.so`). Результат кешується (одне завантаження на процес).
@@ -57,7 +67,59 @@ function cdylibName(platform) {
 }
 
 /**
- * Резолвить шлях до napi-аддона `llm-lib`.
+ * Чи запущено loader із вихідного дерева репо (dev-машина або CI), а не з
+ * встановленого пакета `@7n/llm-lib`. Маркер — `llm-lib/crates/llm-lib-napi/Cargo.toml`
+ * поруч із `repoRoot`: у репо він закомічений завжди, а `files` пакета
+ * (`bin`, `lib`, …) `crates/` не відвантажує — у проді маркера немає.
+ * @param {string} repoRoot корінь, від якого рахуються кандидати
+ * @param {(p: string) => boolean} exists перевірка існування (ін'єкція для тестів)
+ * @returns {boolean} true — вихідне дерево репо
+ */
+function isSourceTree(repoRoot, exists) {
+  return exists(join(repoRoot, 'llm-lib', 'crates', 'llm-lib-napi', 'Cargo.toml'))
+}
+
+/**
+ * Кандидати локальної збірки: сирий cdylib з `cargo build -p llm-lib-napi`
+ * (release перед debug) і вивід `napi build` у `llm-lib/crates/llm-lib-napi/`.
+ * @param {string} repoRoot корінь, від якого рахуються шляхи
+ * @param {string} platform process.platform
+ * @param {string|undefined} suffix napi-суфікс платформи
+ * @returns {string[]} шляхи кандидатів у порядку пріоритету
+ */
+function localBuildCandidates(repoRoot, platform, suffix) {
+  const candidates = Array.from(['release', 'debug'], profile =>
+    join(repoRoot, 'target', profile, cdylibName(platform))
+  )
+  if (suffix) {
+    candidates.push(join(repoRoot, 'llm-lib', 'crates', 'llm-lib-napi', `llm-lib-napi.${suffix}.node`))
+  }
+  return candidates
+}
+
+/**
+ * Помилка «немає збірки» з підказкою і причиною останньої невдачі.
+ * @param {string} key `${platform}-${arch}`
+ * @param {string} lastError текст останньої помилки dlopen (може бути порожнім)
+ * @returns {Error} готова помилка
+ */
+function missingAddonError(key, lastError) {
+  const tail = lastError ? ` Остання спроба — ${lastError}.` : ''
+  return new Error(
+    `llm-lib native addon: немає збірки для "${key}". ` +
+      `Постав N_LLM_LIB_NATIVE_ADDON=/шлях/до/аддона, додай підпакет @7n/llm-lib-${key}, ` +
+      `або збери локально: cargo build --release -p llm-lib-napi.${tail}`
+  )
+}
+
+/**
+ * Ланцюг кандидатів аддона в порядку пріоритету.
+ *
+ * Повертає СПИСОК, а не один шлях, свідомо: `existsSync` — не доказ, що аддон
+ * завантажиться (файл може бути з іншої платформи, побитий, або `existsSync`
+ * підмінений моком у тесті, що не має до аддона стосунку — саме так
+ * `gen-tests.test.mjs` валив увесь контур). Остаточний вибір робить
+ * [`loadNative`], пробуючи кандидатів по черзі.
  * @param {{
  *   env?: Record<string, string | undefined>,
  *   platform?: string,
@@ -66,9 +128,9 @@ function cdylibName(platform) {
  *   requireResolve?: (id: string) => string,
  *   repoRoot?: string
  * }} [deps] ін'єкції для тестів
- * @returns {string} шлях до файлу аддона
+ * @returns {string[]} шляхи в порядку пріоритету (може бути порожнім)
  */
-export function resolveNativeAddon(deps = {}) {
+export function nativeAddonChain(deps = {}) {
   const env = deps.env ?? procEnv
   const platform = deps.platform ?? osPlatform
   const arch = deps.arch ?? osArch
@@ -76,50 +138,79 @@ export function resolveNativeAddon(deps = {}) {
   const requireResolve = deps.requireResolve ?? (id => require.resolve(id))
   const repoRoot = deps.repoRoot ?? REPO_ROOT
 
-  // 1. Явний override.
+  // Явний override — єдине джерело: якщо він заданий і не вантажиться,
+  // мовчазний відкат приховав би саме те, що просили перевірити.
   const override = env.N_LLM_LIB_NATIVE_ADDON
-  if (override) return override
+  if (override) return [override]
 
   const key = `${platform}-${arch}`
   const suffix = NAPI_SUFFIXES[key]
 
-  // 2. Platform-підпакет.
+  // Маркер вихідного дерева перевіряється ПЕРШИМ — саме він обирає порядок
+  // джерел, тож рахувати його після кандидатів було б плутаниною (і ламало б
+  // гейт на порядок звернень до fs).
+  const fromSource = isSourceTree(repoRoot, exists)
+  const local = localBuildCandidates(repoRoot, platform, suffix).filter(p => exists(p))
+
+  /** @type {string[]} */
+  let subpackage = []
   if (suffix) {
     try {
-      return requireResolve(`@7n/llm-lib-${key}/llm-lib-napi.${suffix}.node`)
+      subpackage = [requireResolve(`@7n/llm-lib-${key}/llm-lib-napi.${suffix}.node`)]
     } catch {
-      // не встановлено — пробуємо dev-fallback
+      // не встановлено — лишається лише локальна збірка
     }
   }
 
-  // 3. Dev-fallback: cargo-збірка (сирий cdylib) або вивід napi build.
-  const candidates = Array.from(['release', 'debug'], profile =>
-    join(repoRoot, 'target', profile, cdylibName(platform))
-  )
-  if (suffix) {
-    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
-  }
+  // Вихідне дерево (dev / CI цього репо): локальна збірка попереду, інакше
+  // свіжий `cargo build -p llm-lib-napi` мовчки перекривався б підпакетом.
+  // У проді порядок зворотний — підпакет запінений і авторитетний.
+  return fromSource ? [...local, ...subpackage] : [...subpackage, ...local]
+}
 
-  // 4. Помилка з підказкою.
-  throw new Error(
-    `llm-lib native addon: немає збірки для "${key}". ` +
-      `Постав N_LLM_LIB_NATIVE_ADDON=/шлях/до/аддона, додай підпакет @7n/llm-lib-${key}, ` +
-      `або збери локально: cargo build --release -p llm-lib-napi`
-  )
+/**
+ * Резолвить шлях до napi-аддона `llm-lib` — перший кандидат ланцюга
+ * [`nativeAddonChain`]. Фактичний вибір з урахуванням невдалих dlopen
+ * робить [`loadNative`].
+ * @param {Parameters<typeof nativeAddonChain>[0]} [deps] ін'єкції для тестів
+ * @returns {string} шлях до файлу аддона
+ */
+export function resolveNativeAddon(deps = {}) {
+  const chain = nativeAddonChain(deps)
+  if (chain.length === 0) {
+    const key = `${deps.platform ?? osPlatform}-${deps.arch ?? osArch}`
+    throw missingAddonError(key, '')
+  }
+  return chain[0]
 }
 
 /**
  * Кешований доступ до аддона (одне завантаження на процес).
- * @param {{ resolve?: () => string, dlopen?: (p: string) => Record<string, unknown> }} [deps] ін'єкції
+ * @param {{
+ *   resolve?: () => string,
+ *   resolveChain?: () => string[],
+ *   dlopen?: (p: string) => Record<string, unknown>
+ * }} [deps] ін'єкції
  * @returns {Record<string, unknown>} exports аддона (oneShotAcp, resolveModel, oneShotLocalCloud)
  */
 export function loadNative(deps = {}) {
   if (cached === null) {
-    const path = (deps.resolve ?? resolveNativeAddon)()
-    cached = (deps.dlopen ?? dlopenAddon)(path)
+    const dlopen = deps.dlopen ?? dlopenAddon
+    const chain = deps.resolve ? [deps.resolve()] : (deps.resolveChain ?? nativeAddonChain)()
+
+    /** @type {Record<string, unknown> | null} */
+    let addon = null
+    let lastError = ''
+    for (const candidate of chain) {
+      try {
+        addon = dlopen(candidate)
+        break
+      } catch (error) {
+        lastError = `${candidate}: ${error.message}`
+      }
+    }
+    if (addon === null) throw missingAddonError(`${osPlatform}-${osArch}`, lastError)
+    cached = addon
   }
   return cached
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/llm-lib",
-  "version": "2.14.15",
+  "version": "2.14.16",
   "description": "Тонкий шар роботи з LLM (локальні omlx + хмарні провайдери) поверх pi: model tiers, one-shot, agentic-раннери, write-guard, trace, telemetry, prompt-budget",
   "keywords": [
     "nitra",