@7n/rules 1.13.1 → 1.14.1

package/scripts/lib/ensure-tool.mjs

@@ -6,16 +6,24 @@
  *
  * Per-platform matrix: macOS → brew, Windows → scoop (fallback: GitHub Release), Linux → GitHub Release binary.
  * Бінарники кешуються у `~/.cache/@7n/rules/bin/` (Linux/Mac), `%LOCALAPPDATA%\@7n\cursor\bin\` (Win).
+ * Download завжди пишеться в унікальний per-call temp-каталог і публікується атомарним `renameSync` —
+ * паралельні install того самого тула (різні процеси/промиси) не тупцюють по спільному archive-шляху.
+ *
+ * `ensureTool` лишається синхронним — публічний API пакету (`@7n/rules/scripts/lib/ensure-tool.mjs`,
+ * реально споживається зовнішнім `plugins/ci-github`), сигнатуру не міняємо. `ensureToolAsync(toolId)` —
+ * async-варіант для parallel lane `detectAll()`: внутрішньопроцесний single-flight + міжпроцесний
+ * `withLock` навколо auto-install кроку (`docs/adr/260716-1354-…`).
  *
  * `ensureHkInstall(hkBin)` — реєструє git pre-commit hook через `hk install`; пропускається в CI.
  */
 import { spawnSync } from 'node:child_process'
-import { chmodSync, existsSync, mkdirSync, renameSync } from 'node:fs'
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, renameSync, rmSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { arch, env, platform } from 'node:process'
 
 import { resolveCmd } from '../utils/resolve-cmd.mjs'
+import { withLock } from '../utils/with-lock.mjs'
 
 /** Префікс `v` у git-тегу релізу (`v1.2.3` → `1.2.3`). */
 const TAG_V_PREFIX_RE = /^v/
@@ -189,39 +197,53 @@ function installFromGithub(toolId, entry, cacheDir) {
   const downloadUrl = `https://github.com/${entry.github}/releases/download/v${ver}/${assetName}`
 
   mkdirSync(cacheDir, { recursive: true })
-  const archivePath = join(cacheDir, assetName)
-
-  const dlResult = spawnSync(curlBin, ['-sSL', '-o', archivePath, downloadUrl], { encoding: 'utf8' })
-  if (dlResult.error) throw new Error(`Завантаження ${toolId} не вдалось: ${dlResult.error.message}`)
-  if (dlResult.status !== 0)
-    throw new Error(`curl exit ${dlResult.status} при завантаженні ${toolId}: ${(dlResult.stderr ?? '').slice(0, 300)}`)
-
-  // Сирий бінарник (archive: false) — завантажений файл і є бінарником: перейменовуємо у <toolId> + chmod.
-  if (entry.archive === false) {
-    const binPath = join(cacheDir, toolId)
-    renameSync(archivePath, binPath)
-    chmodSync(binPath, 0o755)
-    return binPath
-  }
+  // Унікальний per-call temp-каталог у тому ж cacheDir (той самий filesystem — атомарний renameSync
+  // наприкінці не впаде з EXDEV). Паралельні install-и того самого тула пишуть у різні temp-каталоги,
+  // не конфліктуючи один з одним; під фіксованим `<toolId>`-іменем публікується лише готовий бінарник.
+  const tmpDir = mkdtempSync(join(cacheDir, `.tmp-${toolId}-`))
+  try {
+    const archivePath = join(tmpDir, assetName)
 
-  // .tar.xz потребує -J замість -z
-  const isXz = assetName.endsWith('.tar.xz')
-  const tarFlags = isXz ? ['-xJf'] : ['-xzf']
-  const extractResult = spawnSync(tarBin, [...tarFlags, archivePath, '-C', cacheDir], { encoding: 'utf8' })
-  if (extractResult.error) throw new Error(`tar failed for ${toolId}: ${extractResult.error.message}`)
-  if (extractResult.status !== 0)
-    throw new Error(`tar exit ${extractResult.status} для ${toolId}: ${(extractResult.stderr ?? '').slice(0, 300)}`)
-
-  const binRelPath = entry.binFinder ? entry.binFinder(ver) : toolId
-  const binPath = join(cacheDir, binRelPath)
-  if (!existsSync(binPath)) {
-    throw new Error(`Бінарник ${toolId} не знайдено після розпакування: ${binPath}`)
-  }
+    const dlResult = spawnSync(curlBin, ['-sSL', '-o', archivePath, downloadUrl], { encoding: 'utf8' })
+    if (dlResult.error) throw new Error(`Завантаження ${toolId} не вдалось: ${dlResult.error.message}`)
+    if (dlResult.status !== 0) {
+      throw new Error(
+        `curl exit ${dlResult.status} при завантаженні ${toolId}: ${(dlResult.stderr ?? '').slice(0, 300)}`
+      )
+    }
+
+    const publishedBin = join(cacheDir, toolId)
+
+    // Сирий бінарник (archive: false) — завантажений файл і є бінарником: chmod + атомарна публікація.
+    if (entry.archive === false) {
+      chmodSync(archivePath, 0o755)
+      renameSync(archivePath, publishedBin)
+      return publishedBin
+    }
+
+    // .tar.xz потребує -J замість -z
+    const isXz = assetName.endsWith('.tar.xz')
+    const tarFlags = isXz ? ['-xJf'] : ['-xzf']
+    const extractResult = spawnSync(tarBin, [...tarFlags, archivePath, '-C', tmpDir], { encoding: 'utf8' })
+    if (extractResult.error) throw new Error(`tar failed for ${toolId}: ${extractResult.error.message}`)
+    if (extractResult.status !== 0) {
+      throw new Error(`tar exit ${extractResult.status} для ${toolId}: ${(extractResult.stderr ?? '').slice(0, 300)}`)
+    }
 
-  const rmBin = resolveCmd('rm')
-  if (rmBin) spawnSync(rmBin, [archivePath])
+    const binRelPath = entry.binFinder ? entry.binFinder(ver) : toolId
+    const extractedBin = join(tmpDir, binRelPath)
+    if (!existsSync(extractedBin)) {
+      throw new Error(`Бінарник ${toolId} не знайдено після розпакування: ${extractedBin}`)
+    }
 
-  return binPath
+    // Атомарна публікація під фіксованим flat-іменем — незалежно від вкладеної структури архіву
+    // (напр. shellcheck розпаковується у `shellcheck-v<ver>/shellcheck`), щоб наступний виклик
+    // `ensureTool` бачив кеш за тим самим шляхом, яким його перевіряє (`join(cacheDir, toolId)`).
+    renameSync(extractedBin, publishedBin)
+    return publishedBin
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true })
+  }
 }
 
 /**
@@ -334,6 +356,78 @@ export function ensureTool(toolId) {
   throw new Error(buildHint(toolId, entry))
 }
 
+/** Внутрішньопроцесний single-flight: конкурентні `ensureToolAsync(toolId)` в одному Node-процесі колапсують в один install. */
+const inFlightInstalls = new Map()
+
+/**
+ * Обгортає `autoInstall` міжпроцесним `withLock` — паралельні Node-процеси (різні CI-shard-и,
+ * кілька агентів на тій самій машині) чекають у черзі замість конкурентного запису в спільний
+ * cache/archive-шлях. Fingerprint-дедуп локу вимкнено (`getFingerprint: () => null`) — той
+ * механізм призначений для повторних CLI-команд на тому самому git-дереві, тут важлива лише
+ * взаємовиключність; після взяття локу перевіряємо кеш повторно (інший процес міг встановити,
+ * поки ми чекали).
+ * @param {string} toolId ключ у реєстрі TOOLS
+ * @param {ToolEntry} entry опис тула
+ * @param {string} cacheDir каталог кешу
+ * @returns {Promise<string>} абсолютний шлях до бінарника
+ */
+async function installWithCrossProcessLock(toolId, entry, cacheDir) {
+  let resultPath = null
+  await withLock(
+    `ensure-tool/${toolId}`,
+    () => {
+      const cachedBin = join(cacheDir, toolId)
+      resultPath = existsSync(cachedBin) ? cachedBin : autoInstall(toolId, entry, cacheDir)
+      return 0
+    },
+    { onWaitTimeout: 'fail', getFingerprint: () => null }
+  )
+  return resultPath
+}
+
+/**
+ * Async-варіант `ensureTool` для parallel lane `detectAll()` (ADR 260716-1354). `ensureTool`
+ * (sync) лишається незміненою — публічний API пакета; ця функція існує окремо, не заміняє її.
+ *
+ * Fast-paths (PATH, уже закешований бінарник) — ідентичні sync-версії. Auto-install — єдина
+ * гілка, що реально потребує async: обгорнута internal single-flight (`inFlightInstalls`) і
+ * cross-process `withLock`, щоб паралельні виклики того самого `toolId` (в одному процесі чи
+ * кількох) не тягнули install конкурентно.
+ * @param {string} toolId ключ у реєстрі TOOLS (`'hk'`, `'conftest'`, `'shellcheck'`, `'actionlint'`, `'dotenv-linter'`, `'opa'`, `'regal'`, `'hadolint'`, `'kubeconform'`, `'kubescape'`)
+ * @returns {Promise<string>} абсолютний шлях до бінарника
+ */
+export async function ensureToolAsync(toolId) {
+  const entry = TOOLS[toolId]
+  if (!entry) throw new Error(`ensureTool: невідомий тул '${toolId}'`)
+
+  // 1. PATH
+  const fromPath = resolveCmd(toolId)
+  if (fromPath) return fromPath
+
+  // 2. Кеш
+  const cacheDir = getCacheDir()
+  const cachedBin = join(cacheDir, toolId)
+  if (existsSync(cachedBin)) return cachedBin
+
+  // 3. Hard-fail (opt-out) — до single-flight, щоб не ставити зайвий запис у Map даремно
+  if (env['N_CURSOR_NO_AUTO_INSTALL']) throw new Error(buildHint(toolId, entry))
+
+  // 4. Авто-install: single-flight (in-process) + withLock (cross-process)
+  const inFlight = inFlightInstalls.get(toolId)
+  if (inFlight) return inFlight
+
+  const installPromise = installWithCrossProcessLock(toolId, entry, cacheDir)
+  inFlightInstalls.set(toolId, installPromise)
+  try {
+    // Єдиний реальний await у функції: коли installPromise усталиться (для ЦЬОГО, ініціюючого
+    // виклику — конкурентні виклики вище просто повернули той самий inFlight), приберемо запис
+    // з Map рівно один раз, незалежно від того, скільки викликів чекало на той самий проміс.
+    return await installPromise
+  } finally {
+    inFlightInstalls.delete(toolId)
+  }
+}
+
 /**
  * Реєструє git pre-commit hook через `hk install`.
  * Пропускається в CI (`process.env.CI`). Попереджає (не кидає) на помилку.

package/scripts/lib/lint-surface/blocking-inventory.mjs

@@ -0,0 +1,59 @@
+/**
+ * Інвентар concern-ів, чий detector ще НЕ доведений на async non-blocking шлях
+ * (ADR 260716-1354-внутрішній-паралелізм-lint-оркестратора). `detectAll()` виконує
+ * ці concern-и у serial lane (строго послідовно, ніколи не перекриваючись самі із
+ * собою) — не заявляємо паралелізм там, де detector все ще звертається до `spawnSync`/
+ * `execSync` (прямо або через спільний helper), бо це блокує event loop цілком і
+ * зробило б паралельний пул ілюзорним.
+ *
+ * Нова міграція (наступний shared helper на `spawnAsync`, за протоколом
+ * `runConftestBatch`/`runOxlintJson`): переведи helper → онови caller-и (`await`) →
+ * прибери відповідний запис звідси → розшир `docs/blocking-inventory-guard.test.mjs`
+ * (guard-тест сам перевірить, що жоден із них більше не викликає `spawnSync`/`execSync`).
+ */
+
+/**
+ * Concern-и з прямим `spawnSync`/`execSync` у власному `main.mjs` — кожен спавнить свій
+ * зовнішній тул напряму, ще не через `spawnAsync`.
+ */
+const DIRECT_SPAWN_CONCERNS = [
+  'text/run-dotenv-linter',
+  'text/oxfmt',
+  'text/cspell-fix',
+  'text/run-v8r',
+  'text/run-shellcheck',
+  'image-compress/check',
+  'php/phpcs',
+  'php/project',
+  'php/cs_fixer',
+  'js/jscpd_duplicates',
+  'k8s/manifests',
+  'style/lint',
+  'bun/licensee',
+  'python/ruff',
+  'python/project',
+  'python/mypy',
+  'security/scan',
+  'rust/check',
+  'rego/conftest_verify'
+]
+
+/**
+ * Concern-и, чий detector сам не викликає `spawnSync`/`execSync`, але делегує спільному
+ * helper-у, який його викликає: `docker/lib/docker-hadolint.mjs` (hadolint) і
+ * `rego/lib/run-external-tool.mjs` (regal/opa).
+ */
+const SHARED_HELPER_CONCERNS = ['docker/lint', 'rego/regal', 'rego/opa_check']
+
+/** Повний serial-lane список: `${ruleId}/${concernId}` — 19 прямих + 3 через shared helper = 22. */
+export const SERIAL_LANE_CONCERNS = new Set([...DIRECT_SPAWN_CONCERNS, ...SHARED_HELPER_CONCERNS])
+
+/**
+ * Чи concern лишається у serial lane `detectAll()` (недоведений non-blocking).
+ * @param {string} ruleId id правила
+ * @param {string} concernId id concern-а
+ * @returns {boolean} true — serial lane; false — parallel-safe
+ */
+export function isSerialLane(ruleId, concernId) {
+  return SERIAL_LANE_CONCERNS.has(`${ruleId}/${concernId}`)
+}

package/scripts/lib/lint-surface/docs/blocking-inventory.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: blocking-inventory.mjs
+resource: npm/scripts/lib/lint-surface/blocking-inventory.mjs
+docgen:
+  crc: 2e0e8624
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Інвентар concern-ів для `ADR 260716-1354-внутрішній-паралелізм-lint-оркестратора`, чиї detector-и ще не доведені до async non-blocking шляху. `SERIAL_LANE_CONCERNS` і `isSerialLane` фіксують, що `detectAll` виконує ці concern-и в serial lane — строго послідовно, без перекриття між собою. Тут не можна заявляти паралелізм для detector-ів, які ще викликають `spawnSync`/`execSync` напряму або через shared helper, бо це блокує event loop і робить паралельний пул ілюзорним. Міграція йде за інваріантом: helper → caller-и (`await`) → прибрати відповідний запис звідси → розширити `docs/blocking-inventory-guard.test.mjs`; guard-тест має підтвердити, що жоден із цих concern-ів більше не викликає `spawnSync`/`execSync`.
+
+## Поведінка
+
+- `SERIAL_LANE_CONCERNS` — перелік concern-ів, які `detectAll` тримає в serial lane, бо їхній detector ще не доведено до non-blocking шляху; сюди свідомо не включені вже переведені на async/`spawnAsync` concern-и.
+- `isSerialLane` — визначає, чи належить вказаний concern до serial lane, щоб оркестратор не оголошував паралельність там, де ще є blocking-виклики напряму або через shared helper.
+
+## Публічний API
+
+- SERIAL_LANE_CONCERNS — Повний перелік serial-lane concern-ів у форматі `${ruleId}/${concernId}`: 19 напряму заданих і 3, що додаються через shared helper; разом 22.
+- isSerialLane — Визначає, чи concern має лишатися в serial lane для `detectAll`, коли non-blocking ще не доведено.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/lint-surface/docs/index.md

@@ -6,6 +6,7 @@ resource: npm/scripts/lib/lint-surface/
 
 | Файл                                                        | Тип       |
 | ----------------------------------------------------------- | --------- |
+| [blocking-inventory.mjs](blocking-inventory.md)             | JS Module |
 | [codegen-opa-wrapper.mjs](codegen-opa-wrapper.md)           | JS Module |
 | [collateral-veto.mjs](collateral-veto.md)                   | JS Module |
 | [default-worker.mjs](default-worker.md)                     | JS Module |
@@ -20,6 +21,7 @@ resource: npm/scripts/lib/lint-surface/
 | [render.mjs](render.md)                                     | JS Module |
 | [run-detectors.mjs](run-detectors.md)                       | JS Module |
 | [run-fix.mjs](run-fix.md)                                   | JS Module |
+| [scheduler.mjs](scheduler.md)                               | JS Module |
 | [snapshot.mjs](snapshot.md)                                 | JS Module |
 | [tier-sampling-bench.mjs](tier-sampling-bench.md)           | JS Module |
 | [tier-sampling-experiment.mjs](tier-sampling-experiment.md) | JS Module |

package/scripts/lib/lint-surface/docs/policy-lint-adapter.md

@@ -3,9 +3,8 @@ type: JS Module
 title: policy-lint-adapter.mjs
 resource: npm/scripts/lib/lint-surface/policy-lint-adapter.mjs
 docgen:
-  crc: facc5e07
+  crc: 1e527329
   model: openai-codex/gpt-5.5
-  tier: cloud-avg
   score: 80
   issues: internal-name:resolveTargetFiles,internal-name:runConftestBatch,judge:inaccurate:0.97
   judgeModel: openai-codex/gpt-5.4-mini
@@ -31,7 +30,7 @@ docgen:
 
 6. Для кожного target-файлу в template-режимі порівнює фактичний вміст із declarative template-очікуваннями: обовʼязковими фрагментами, заборонами та вимогами на наявність. Кожну невідповідність оформлює як `policy-template-mismatch`.
 
-7. Для Rego-перевірки запускає policy concern-а через conftest-поверхню та передає доступні template-дані як супровідний контекст, щоб зберегти поведінку існуючої policy-логіки.
+7. Для Rego-перевірки запускає policy concern-а через conftest-поверхню (`await runConftestBatch`, async), передаючи доступні template-дані як супровідний контекст і прокидаючи `ctx.signal` — щоб зберегти поведінку існуючої policy-логіки й водночас підтримати скасування у parallel lane `detectAll()`.
 
 8. Кожен deny-результат Rego оформлює як `policy-deny` із повідомленням policy та, якщо доступно, відносним шляхом до файла-порушника.
 

package/scripts/lib/lint-surface/docs/run-detectors.md

@@ -3,7 +3,7 @@ type: JS Module
 title: run-detectors.mjs
 resource: npm/scripts/lib/lint-surface/run-detectors.mjs
 docgen:
-  crc: e8a0ec47
+  crc: 631fa41c
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.98
@@ -21,6 +21,8 @@ DEFAULT_RULES_DIR визначає шлях до стандартної дире
 buildDetectPlan створює впорядкований план прогону лінтера, збираючи всі відповідні концерни та визначаючи область їх сканування.
 detectAll виконує прохід лінтера у режим детекції, збираючи всі виявлені порушення та повертаючи код виходу.
 
+**Внутрішній паралелізм (ADR 260716-1354-внутрішній-паралелізм-lint-оркестратора).** `detectAll` читає `N_RULES_LINT_CONCURRENCY` (дефолт `1` — production-паралелізм ще не пройшов benchmark-gates ADR): за замовчуванням план виконується повністю послідовно (`detectPlanSequentially`), спостережувано ідентично до-ADR поведінці. При `concurrency > 1` план ділиться на два лейни через `blocking-inventory.mjs` (`isSerialLane`) і виконується через `scheduler.mjs` (`runPlanConcurrently`, `detectPlanConcurrently`): parallel lane — доведені non-blocking concern-и, bounded pool до `concurrency`; serial lane — решта, строго послідовно. Перший `DetectorError` (будь-який лейн) зупиняє нові старти, `AbortController` сигналізує вже запущеним async-детекторам (`ctx.signal`), а вже завершені concern-и лишаються в результаті — `exitCode 2` пріоритетний над частковими violations. Фінальний масив violations завжди стабільно сортується за `(ruleId, concernId, file, data.line, reason)` — незалежно від порядку завершення (`sortViolations`), навіть при `concurrency=1`.
+
 ## Публічний API
 
 * DEFAULT_RULES_DIR — Містить набір стандартних правил для перевірок.

package/scripts/lib/lint-surface/docs/scheduler.md

@@ -0,0 +1,39 @@
+---
+type: JS Module
+title: scheduler.mjs
+resource: npm/scripts/lib/lint-surface/scheduler.mjs
+docgen:
+  crc: e909628f
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Bounded two-lane concurrent scheduler для `detectAll`, який активується лише коли `concurrency > 1`; за `concurrency === 1` `detectAll` лишається на повністю послідовному шляху, спостережувано ідентичному до-ADR поведінці, і цей scheduler там навіть не викликається. Має два лейни: **serial lane** з власним sequential runner і mutex-ефектом, де items ніколи не перекриваються самі з собою, та **parallel lane** з bounded pool до `concurrency` слотів. Обидва лейни навмисно виконуються конкурентно один з одним: для serial-lane це лише структурна конкурентність, бо його blocking `spawnSync` все одно заморожує event loop, а parallel-lane отримує реальну вигоду від одночасного очікування кількох `spawnAsync`-викликів. Перша помилка від `runItem` зупиняє нові старти в обох лейнах, `controller.abort` сигналізує вже запущеним async-детекторам, і функція чекає завершення всіх уже стартованих items; кожен `runOne` ловить власну помилку, тож зовнішній `Promise.all` не відхиляється назовні.
+
+## Поведінка
+
+1. `runPlanConcurrently` розділяє вхідний план на два потоки виконання: serial і parallel, щоб паралельно обслуговувати незалежні елементи та не перекривати послідовні між собою.
+
+2. `runPlanConcurrently` запускає serial-потік як суворо послідовний прогін, а parallel-потік — як обмежений пул із максимальною кількістю одночасних активних елементів, визначеною рівнем concurrency.
+
+3. `runPlanConcurrently` збирає результат кожного реально стартованого елемента в порядку завершення, а не в початковому порядку плану.
+
+4. `runPlanConcurrently` сприймає першу помилку як інфраструктурну: зупиняє старт нових елементів у обох потоках і надсилає сигнал скасування вже запущеним асинхронним виконавцям.
+
+5. `runPlanConcurrently` не перериває зовнішнє виконання аварійним винятком: усі вже стартовані елементи дочікуються завершення, а помилки фіксуються в результатах і повертаються разом із першим інфраструктурним збоєм.
+
+6. `runPlanConcurrently` повертає пару: список фактично виконаних елементів із їхнім підсумком або причиною скасування, та першу помилку, якщо вона була; якщо збоїв не було, помилка дорівнює null.
+
+## Публічний API
+
+- runPlanConcurrently — зупиняє запуск нових items після кидка, абортує `signal`; `results` містить лише реально запущені items у порядку завершення; `infraError` фіксує першу помилку `runItem` або лишається `null`, якщо все завершилось успішно
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/scripts/lib/lint-surface/docs/types.md

@@ -3,7 +3,7 @@ type: JS Module
 title: types.mjs
 resource: npm/scripts/lib/lint-surface/types.mjs
 docgen:
-  crc: 4120f280
+  crc: 5f1d3eca
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 
@@ -13,7 +13,7 @@ docgen:
 
 ## Поведінка
 
-1. Контекст для перевірки визначається через абсолютний шлях до коріня репозиторію, унікальний ідентифікатор правила та ідентифікатор concern-а. Додатково може вказуватися абсолютний шлях до каталогу concern-а або відносний перелік файлів для пофайлового запуску.
+1. Контекст для перевірки визначається через абсолютний шлях до коріня репозиторію, унікальний ідентифікатор правила та ідентифікатор concern-а. Додатково може вказуватися абсолютний шлях до каталогу concern-а або відносний перелік файлів для пофайлового запуску, а також опційний `AbortSignal` — заповнюється лише в parallel lane `detectAll()` (`N_RULES_LINT_CONCURRENCY>1`), async-детектори прокидають його у свої `spawnAsync`-виклики, щоб перерватись при infrastructure-помилці іншого concern-а.
 2. Detector створює результат перевірки, який містить перелік виявлених порушень або технічних діагностик.
 3. Кожне порушення фіксується за унікальною комбінацією `ruleId`, `concernId` та стабільного коду причини. Для порушення вказується описовий текст, а також опціональні метадані, специфічні для concern-а.
 4. T0-патерн визначає, чи застосовний для групи порушень. Якщо патерн ідемпотентний та самодостатній, він може автоматично ініціювати виправлення без детального аналізу кожного порушення.

package/scripts/lib/lint-surface/policy-lint-adapter.mjs

@@ -43,7 +43,7 @@ function toRel(abs, cwd) {
  * @returns {Promise<LintResult>} Уніфікований результат лінту зі списком violations.
  */
 export async function evaluatePolicyConcern(ctx, cfg) {
-  const { cwd, ruleId, concernId } = ctx
+  const { cwd, ruleId, concernId, signal } = ctx
   /** @type {LintViolation[]} */
   const violations = []
   /**
@@ -90,13 +90,14 @@ export async function evaluatePolicyConcern(ctx, cfg) {
   // Rego
   const namespace = `${ruleId.replaceAll('-', '_')}.${concernId}`
   const templateData = await resolveConcernTemplateData(cfg.policyDir, { files: cfg.files })
-  const denies = runConftestBatch({
+  const denies = await runConftestBatch({
     policyDirRel: `${ruleId}/${concernId}`,
     // Абсолютний шлях теки concern-а — правило може жити поза вбудованим rules/ ядра (плагін).
     policyDirAbs: cfg.policyDir,
     namespace,
     files,
-    templateData
+    templateData,
+    signal
   })
   for (const d of denies) add('policy-deny', d.message, d.filename ? toRel(d.filename, cwd) : undefined)
   return { violations }

package/scripts/lib/lint-surface/run-detectors.mjs

@@ -10,6 +10,7 @@
  * @typedef {{ ruleId: string, concern: ConcernMeta }} LintEntry
  */
 import { dirname, join } from 'node:path'
+import { env } from 'node:process'
 import { fileURLToPath } from 'node:url'
 
 import picomatch from 'picomatch'
@@ -18,9 +19,11 @@ import { listConcerns } from '../concern-meta.mjs'
 import { collectChangedFilesSince, resolveChangedBase } from '../changed-files.mjs'
 import { readNRulesConfigLite, isRuleEnabled } from '../read-n-rules-config-lite.mjs'
 import { getActiveCapabilities, resolvePlugins } from '../resolve-plugins.mjs'
+import { isSerialLane } from './blocking-inventory.mjs'
 import { runConcernDetector, DetectorError } from './detect.mjs'
 import { renderViolations, renderDiagnostics } from './render.mjs'
 import { createProgressReporter } from './progress.mjs'
+import { runPlanConcurrently } from './scheduler.mjs'
 
 // Цей файл: npm/scripts/lib/lint-surface/run-detectors.mjs → PACKAGE_ROOT = npm (4 dirname угору).
 export const DEFAULT_RULES_DIR = join(dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url))))), 'rules')
@@ -295,6 +298,129 @@ async function buildPlan({ byRule, full, rules, explicitFiles, cwd }) {
   return buildDeltaPlan(byRule, enabledSet, changed)
 }
 
+/**
+ * Виконує один item плану: будує ctx, прогонить detector, оновлює progress. Спільний
+ * крок для послідовного і конкурентного (`N_RULES_LINT_CONCURRENCY>1`) шляхів `detectAll` —
+ * єдина точка, де щось може кинути `DetectorError` (чи іншу помилку), тож caller (sequential
+ * for-loop чи `runPlanConcurrently`) вирішує, як саме зупинити прогін.
+ * @param {PlanItem} planItem один item плану (`{ entry, files }`).
+ * @param {object} runOpts опції прогону.
+ * @param {string} runOpts.cwd робоча директорія прогону.
+ * @param {boolean} runOpts.verbose докладний лог прогону.
+ * @param {import('./progress.mjs').ProgressReporter|null} runOpts.progress reporter прогресу (може бути відсутній).
+ * @param {(s: string) => void} runOpts.log функція логування.
+ * @param {AbortSignal} [runOpts.signal] сигнал скасування — лише в конкурентному шляху.
+ * @returns {Promise<{ entry: LintEntry, violations: LintViolation[] }>} entry і зібрані violations.
+ */
+async function runPlanItem({ entry, files }, { cwd, verbose, progress, log, signal }) {
+  /** @type {LintContext} */
+  const ctx = { cwd, ruleId: entry.ruleId, concernId: entry.concern.name, files, verbose, signal }
+  const key = `${entry.ruleId}/${entry.concern.name}`
+  progress?.concernStart(key)
+  if (verbose) {
+    const countStr = files === undefined ? 'весь репо' : `${files.length} файл(ів)`
+    log(`  🔍 ${key}  [${entry.concern.lint.scope}]  → ${countStr}\n`)
+  }
+  const result = await runConcernDetector(entry.concern, ctx)
+  progress?.detectSnapshot(key, result.violations.length)
+  progress?.concernDone(key)
+  if (verbose && result.diagnostics && result.diagnostics.length > 0) {
+    log(renderDiagnostics(result.diagnostics))
+  }
+  return { entry, violations: result.violations }
+}
+
+/**
+ * @typedef {{ violations: LintViolation[], ran: LintEntry[], infraMessage: string|null }} PlanRunResult
+ */
+
+/**
+ * Послідовний прохід плану — незмінна поведінка до-ADR 260716-1354 (`N_RULES_LINT_CONCURRENCY<=1`,
+ * дефолт). Перший `DetectorError` негайно зупиняє прогін (`infraMessage`); будь-яка інша помилка
+ * прокидається далі (несподівана помилка самого раннера, не detector-контракту).
+ * @param {PlanItem[]} plan впорядкований план прогону.
+ * @param {{ cwd: string, verbose: boolean, progress: import('./progress.mjs').ProgressReporter|null, log: (s: string) => void }} runOpts опції прогону.
+ * @returns {Promise<PlanRunResult>} зібрані violations, виконані entries, повідомлення інфра-помилки.
+ */
+async function detectPlanSequentially(plan, runOpts) {
+  /** @type {LintViolation[]} */
+  const violations = []
+  /** @type {LintEntry[]} */
+  const ran = []
+  for (const item of plan) {
+    let outcome
+    try {
+      outcome = await runPlanItem(item, runOpts)
+    } catch (error) {
+      if (error instanceof DetectorError) return { violations, ran, infraMessage: error.message }
+      throw error
+    }
+    ran.push(outcome.entry)
+    violations.push(...outcome.violations)
+  }
+  return { violations, ran, infraMessage: null }
+}
+
+/**
+ * Bounded two-lane прохід плану (`N_RULES_LINT_CONCURRENCY>1`, experimental — ADR 260716-1354).
+ * Parallel lane — concern-и, доведені non-blocking (`blocking-inventory.mjs`), bounded pool до
+ * `concurrency`; serial lane — решта, строго послідовно. Перший `DetectorError` зупиняє нові
+ * старти в обох лейнах (`scheduler.mjs`); уже завершені concern-и лишаються в результаті.
+ * @param {PlanItem[]} plan впорядкований план прогону.
+ * @param {{ cwd: string, verbose: boolean, progress: import('./progress.mjs').ProgressReporter|null, log: (s: string) => void, concurrency: number }} runOpts опції прогону.
+ * @returns {Promise<PlanRunResult>} зібрані violations, виконані entries, повідомлення інфра-помилки.
+ */
+async function detectPlanConcurrently(plan, { cwd, verbose, progress, log, concurrency }) {
+  const { results, infraError } = await runPlanConcurrently(plan, {
+    concurrency,
+    isSerial: item => isSerialLane(item.entry.ruleId, item.entry.concern.name),
+    runItem: (item, signal) => runPlanItem(item, { cwd, verbose, progress, log, signal })
+  })
+
+  if (infraError !== null && !(infraError instanceof DetectorError)) throw infraError
+
+  /** @type {LintViolation[]} */
+  const violations = []
+  /** @type {LintEntry[]} */
+  const ran = []
+  for (const { result } of results) {
+    if (!result) continue
+    ran.push(result.entry)
+    violations.push(...result.violations)
+  }
+  return { violations, ran, infraMessage: infraError?.message ?? null }
+}
+
+/**
+ * `data.line` детектора (не top-level поле `LintViolation` — лише деякі detector-и
+ * кладуть номер рядка в `data`, напр. `js/eslint`). Відсутність → 0 (перед усіма
+ * реальними номерами рядків), щоб сортування лишалось стабільним і передбачуваним.
+ * @param {LintViolation} v порушення.
+ * @returns {number} номер рядка або 0.
+ */
+function violationLine(v) {
+  const line = v.data && typeof v.data === 'object' ? v.data.line : undefined
+  return typeof line === 'number' ? line : 0
+}
+
+/**
+ * Стабільне сортування за `(ruleId, concernId, file, line, reason)` — незалежно від порядку
+ * завершення concern-ів (важливо для конкурентного шляху; послідовний шлях сьогодні лише
+ * конкатенував violations у порядку виконання, без сортування за file/line/reason).
+ * @param {LintViolation[]} violations вхідний масив (не мутується).
+ * @returns {LintViolation[]} новий, стабільно сортований масив.
+ */
+function sortViolations(violations) {
+  return violations.toSorted(
+    (a, b) =>
+      a.ruleId.localeCompare(b.ruleId) ||
+      a.concernId.localeCompare(b.concernId) ||
+      (a.file ?? '').localeCompare(b.file ?? '') ||
+      violationLine(a) - violationLine(b) ||
+      a.reason.localeCompare(b.reason)
+  )
+}
+
 /**
  * Запускає detect-only прохід. Повертає всі violations і похідний exitCode.
  * @param {object} opts опції прогону.
@@ -339,43 +465,28 @@ export async function detectAll(opts) {
       : null
   const log = progress ? progress.log : baseLog
 
-  /** @type {LintViolation[]} */
-  const allViolations = []
-  /** @type {LintEntry[]} */
-  const ran = []
+  // Default 1 — production-паралелізм ще не пройшов benchmark-gates ADR 260716-1354;
+  // >1 лишається experimental override.
+  const concurrency = Math.max(1, Number(env['N_RULES_LINT_CONCURRENCY']) || 1)
+  const runOpts = { cwd, verbose, progress, log }
 
+  let planResult
   try {
-    for (const { entry, files } of plan) {
-      /** @type {LintContext} */
-      const ctx = { cwd, ruleId: entry.ruleId, concernId: entry.concern.name, files, verbose }
-      const key = `${entry.ruleId}/${entry.concern.name}`
-      progress?.concernStart(key)
-      if (verbose) {
-        const countStr = files === undefined ? 'весь репо' : `${files.length} файл(ів)`
-        log(`  🔍 ${key}  [${entry.concern.lint.scope}]  → ${countStr}\n`)
-      }
-      let result
-      try {
-        result = await runConcernDetector(entry.concern, ctx)
-      } catch (error) {
-        if (error instanceof DetectorError) {
-          log(`💥 ${error.message}\n`)
-          return { violations: allViolations, exitCode: 2, ran }
-        }
-        throw error
-      }
-      ran.push(entry)
-      allViolations.push(...result.violations)
-      progress?.detectSnapshot(key, result.violations.length)
-      progress?.concernDone(key)
-      if (verbose && result.diagnostics && result.diagnostics.length > 0) {
-        log(renderDiagnostics(result.diagnostics))
-      }
-    }
+    planResult = await (concurrency > 1
+      ? detectPlanConcurrently(plan, { ...runOpts, concurrency })
+      : detectPlanSequentially(plan, runOpts))
   } finally {
     progress?.stop()
   }
 
+  const { ran, infraMessage } = planResult
+  const allViolations = sortViolations(planResult.violations)
+
+  if (infraMessage !== null) {
+    log(`💥 ${infraMessage}\n`)
+    return { violations: allViolations, exitCode: 2, ran }
+  }
+
   if (allViolations.length > 0) baseLog(renderViolations(allViolations))
   return { violations: allViolations, exitCode: allViolations.length > 0 ? 1 : 0, ran }
 }