@7n/rules 1.83.3 → 1.85.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [1.85.0] - 2026-08-05
+
+### Added
+
+- Контракт плагінів `n-rules:plugin` — мінор `3.1.0`: новий host-імпорт `exec-tool`
+(`run-tool` плюс `cwd`, накладені змінні середовища й двобічний scratch-обмін
+файлами) і слот `scratch-dir@1` на чинному `host-context`. Зміна additive:
+плагін, зібраний під v3.0, лінкується й працює без повторної збірки.
+
+Резолв тулів у `manifest.tools` навчився схем (рішення В спеки v3.1):
+`path:<name>` резолвиться по PATH замість github-релізу; відсутність схеми —
+як було (`pinned:`).
+
+Перший концерн на новій поверхні — `bun/licensee`: детекція ліцензій
+npm-залежностей переїхала з JS у wasm-компонент `lang-js/wasm-concerns`
+(T0-фікс лишається JS). Спавнений тул виконується з правами хоста, поза
+wasm-пісочницею — межа довіри плагіна це його пін, не пісочниця.
+
+### Fixed
+
+- регенерує `.cursor/rules/n-rust.mdc` (дрейф із каноном після #392) і піднімає `KNOWN_PLUGIN_RANGES['@7n/rules-lang-rust']` до `^0.16` слідом за релізом плагіна
+
+## [1.84.0] - 2026-08-05
+
+### Changed
+
+- `k8s/manifests` — перший зріз порту в `rules-core` плюс полагоджений дефект канону. Портовано два з чотирьох шарів `lint()`: rego-контур (`runAllK8sRego` — усі девʼять namespace-ів, класифікатор fix-підказок, гілка `--data`/`templateData` у `conftest`) і чотири самодостатні cross-file перевірки (`assertNoForbiddenK8sDevPaths`, `validateSvcYamlAndSvcHlPairs`, `validateKustomizationPathRefsExistOnDisk`, `validateKustomizationIncludesSvcHlWithSvc`, `validateConfigMapNameMatchesDeployment`). Сам концерн у `NATIVE_CONCERNS` **не** заведено — він неподільний для диспатчу і зайде туди разом із рештою шарів, тож поведінка лінту незмінна.
+
+**Зміна поведінки:** звірка `metadata.name` ConfigMap із Deployment (`k8s/base/configmap.yaml`) більше не спирається на «перший `kind: Deployment` за порядком `readdir`». Обхід файлів каталогу став відсортованим (детермінований на будь-якій файловій системі — раніше macOS і Linux-раннер CI могли давати різний вислід), і серед **усіх** Deployment каталогу беруться лише ті, що посилаються рівно на один ConfigMap. Наслідок — fail-closed: каталог, де перший Deployment ConfigMap не вживає, раніше мовчки випадав із перевірки, тепер перевіряється. Репозиторії з одним Deployment на каталог змін не побачать.
+
 ## [1.83.3] - 2026-08-05
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.83.3",
+  "version": "1.85.0",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",
@@ -83,9 +83,9 @@
     "zod": "^4.4.3"
   },
   "optionalDependencies": {
-    "@7n/rules-darwin-arm64": "1.83.1",
-    "@7n/rules-linux-x64": "1.83.1",
-    "@7n/rules-win32-x64": "1.83.1",
+    "@7n/rules-darwin-arm64": "1.84.0",
+    "@7n/rules-linux-x64": "1.84.0",
+    "@7n/rules-win32-x64": "1.84.0",
     "@earendil-works/pi-ai": "0.80.10",
     "@earendil-works/pi-coding-agent": "0.80.10"
   },

package/rules/k8s/manifests/main.mjs

@@ -635,7 +635,7 @@ async function validateOneKustomizationPathRefsExist(root, kustAbs, rootNorm, fa
  * @param {(msg: string) => void} fail callback для повідомлень про помилки
  * @returns {Promise<void>} результат
  */
-async function validateKustomizationPathRefsExistOnDisk(root, yamlFilesAbs, fail) {
+export async function validateKustomizationPathRefsExistOnDisk(root, yamlFilesAbs, fail) {
   const rootNorm = resolve(root)
   const kustFiles = yamlFilesAbs.filter(p => basename(p).toLowerCase() === 'kustomization.yaml')
   for (const kustAbs of kustFiles) {
@@ -724,7 +724,7 @@ async function validateOneKustomizationSvcHlWithSvc(root, kustAbs, fail) {
  * @param {(msg: string) => void} fail callback помилки
  * @returns {Promise<void>} результат
  */
-async function validateKustomizationIncludesSvcHlWithSvc(root, yamlFiles, fail) {
+export async function validateKustomizationIncludesSvcHlWithSvc(root, yamlFiles, fail) {
   const kustFiles = yamlFiles.filter(p => basename(p).toLowerCase() === 'kustomization.yaml')
   for (const kustAbs of kustFiles) {
     await validateOneKustomizationSvcHlWithSvc(root, kustAbs, fail)
@@ -2372,35 +2372,27 @@ async function tryReaddir(dirPath) {
 }
 
 /**
- * Читає YAML-файл і шукає перший документ із заданим `kind`.
- * @param {string} filePath абсолютний шлях до YAML-файлу
- * @param {string} kind очікуваний `kind`
- * @returns {Promise<Record<string, unknown> | null>} знайдений об'єкт або null
- */
-async function readFirstDocByKindFromFile(filePath, kind) {
-  const raw = await tryReadFileUtf8(filePath)
-  if (raw === undefined) return null
-  const docs = tryParseAllYamlDocs(raw)
-  if (docs === undefined) return null
-  return findFirstDocByKind(docs, kind)
-}
-
-/**
- * Знаходить перший документ **Deployment** серед YAML-файлів каталогу (для перевірки імені ConfigMap, js-run.mdc).
+ * Усі документи **Deployment** каталогу, у **відсортованому** порядку імен файлів.
+ * Сортування обов'язкове: без нього результат залежав би від порядку `readdir`,
+ * тобто від файлової системи (APFS впорядковує, ext4 — hash-порядок).
  * @param {string} dirPath абсолютний шлях до каталогу
- * @returns {Promise<Record<string, unknown> | null>} об'єкт Deployment або null
+ * @returns {Promise<Record<string, unknown>[]>} документи Deployment у детермінованому порядку
  */
-export async function findDeploymentDocInDir(dirPath) {
-  const entries = await tryReaddir(dirPath)
+async function collectDeploymentDocsInDir(dirPath) {
+  const dirEntries = await tryReaddir(dirPath)
+  const entries = dirEntries.filter(e => K8S_YAML_EXT_RE.test(e)).toSorted()
+  /**
+  @type {Record<string, unknown>[]}
+   */
+  const out = []
   for (const entry of entries) {
-    if (!K8S_YAML_EXT_RE.test(entry)) {
-      continue
-    }
-
-    const found = await readFirstDocByKindFromFile(join(dirPath, entry), 'Deployment')
-    if (found !== null) return found
+    const raw = await tryReadFileUtf8(join(dirPath, entry))
+    if (raw === undefined) continue
+    const docs = tryParseAllYamlDocs(raw)
+    if (docs === undefined) continue
+    out.push(...collectDocsByKind(docs, 'Deployment'))
   }
-  return null
+  return out
 }
 
 /**
@@ -3064,7 +3056,7 @@ async function validateOneSvcYamlHlPair(root, absSet, svcAbs, fail) {
  * @param {(msg: string) => void} fail callback помилки
  * @returns {Promise<void>} результат
  */
-async function validateSvcYamlAndSvcHlPairs(root, yamlFiles, fail) {
+export async function validateSvcYamlAndSvcHlPairs(root, yamlFiles, fail) {
   const absSet = new Set(yamlFiles)
   failIfSvcHlWithoutSiblingSvc(root, yamlFiles, absSet, fail)
   const svcFiles = yamlFiles.filter(p => basename(p).toLowerCase() === 'svc.yaml')
@@ -3374,7 +3366,7 @@ async function checkK8sYamlFile(abs, root, fail, pass) {
  * @param {(msg: string) => void} fail callback для реєстрації порушення
  * @returns {void} результат
  */
-function assertNoForbiddenK8sDevPaths(yamlFiles, root, fail) {
+export function assertNoForbiddenK8sDevPaths(yamlFiles, root, fail) {
   for (const abs of yamlFiles) {
     const rel = relative(root, abs).replaceAll('\\', '/')
     if (isForbiddenK8sDevPath(rel)) {
@@ -3409,6 +3401,31 @@ function extractFirstConfigMapName(raw) {
   return manifestMetadataName(cm)
 }
 
+/**
+ * Deployment каталогу, з яким має звірятись `metadata.name` ConfigMap.
+ *
+ * Раніше тут стояв `findDeploymentDocInDir` — «перший `kind: Deployment` за порядком
+ * `readdir`». Це давало два дефекти: недетермінізм (порядок ФС) і false negative —
+ * якщо першим траплявся Deployment без ConfigMap-рефа (або з двома), перевірка мовчки
+ * закривалась, хоча поруч стояв Deployment рівно з одним рефом. Тепер обхід
+ * детермінований (відсортований), і серед **усіх** Deployment каталогу беруться лише
+ * ті, що посилаються рівно на один ConfigMap.
+ * @param {string} dirPath каталог із `configmap.yaml`
+ * @param {string} cmName `metadata.name` ConfigMap
+ * @returns {Promise<{ matched: boolean, deployName: string } | null>} збіг, кандидат для повідомлення або null
+ */
+async function configMapOwnerDeployment(dirPath, cmName) {
+  let firstCandidate = null
+  for (const deployment of await collectDeploymentDocsInDir(dirPath)) {
+    if (collectDeploymentConfigMapRefs(deployment).size !== 1) continue
+    const deployName = manifestMetadataName(deployment)
+    if (deployName === null) continue
+    if (deployName === cmName) return { matched: true, deployName }
+    firstCandidate ??= deployName
+  }
+  return firstCandidate === null ? null : { matched: false, deployName: firstCandidate }
+}
+
 /**
  * Перевіряє один файл `configmap.yaml`: якщо поруч є Deployment з рівно одним ConfigMap-рефом,
  * `metadata.name` ConfigMap має збігатися з `metadata.name` Deployment.
@@ -3422,16 +3439,13 @@ async function validateSingleConfigMapNameMatch(cmAbs, rel, fail, passFn) {
   if (raw === undefined) return
   const cmName = extractFirstConfigMapName(raw)
   if (cmName === null) return
-  const deployment = await findDeploymentDocInDir(dirname(cmAbs))
-  if (deployment === null) return
-  const deployName = manifestMetadataName(deployment)
-  const cmRefs = collectDeploymentConfigMapRefs(deployment)
-  if (cmRefs.size !== 1 || typeof deployName !== 'string') return
-  if (cmName === deployName) {
+  const owner = await configMapOwnerDeployment(dirname(cmAbs), cmName)
+  if (owner === null) return
+  if (owner.matched) {
     passFn(`${rel}: metadata.name '${cmName}' збігається з Deployment (k8s.mdc)`)
   } else {
     fail(
-      `${rel}: metadata.name '${cmName}' має збігатися з назвою Deployment '${deployName}' — Deployment посилається рівно на один ConfigMap (k8s.mdc)`
+      `${rel}: metadata.name '${cmName}' має збігатися з назвою Deployment '${owner.deployName}' — Deployment посилається рівно на один ConfigMap (k8s.mdc)`
     )
   }
 }
@@ -3444,7 +3458,7 @@ async function validateSingleConfigMapNameMatch(cmAbs, rel, fail, passFn) {
  * @param {(msg: string) => void} fail callback при помилці
  * @param {(msg: string) => void} passFn callback при успіху
  */
-async function validateConfigMapNameMatchesDeployment(root, yamlFilesAbs, fail, passFn) {
+export async function validateConfigMapNameMatchesDeployment(root, yamlFilesAbs, fail, passFn) {
   const cmFiles = yamlFilesAbs.filter(abs => {
     const rel = relative(root, abs).replaceAll('\\', '/')
     return CONFIGMAP_BASE_PATH_RE.test(`/${rel}`) || rel === 'k8s/base/configmap.yaml'
@@ -6421,7 +6435,7 @@ function k8sRegoFixHint(ns, file, message) {
  * @param {(msg: string, hint?: unknown) => void} fail callback реєстрації порушення.
  * @returns {Promise<void>} результат
  */
-async function runAllK8sRego(root, yamlFiles, fail) {
+export async function runAllK8sRego(root, yamlFiles, fail) {
   const relOf = abs => relative(root, abs).replaceAll('\\', '/') || abs
 
   const allYaml = yamlFiles

package/schemas/v8r-catalog.json

@@ -208,7 +208,7 @@
     },
     {
       "name": "n-rules plugin manifest",
-      "description": "plugin.toml — маніфест wasm-плагіна n-rules:plugin@3.0.0 (crates/<guest>/plugin.toml); офіційної JSON Schema поки нема (schemars-схема rules_contract::manifest::Manifest ще не публікується як окремий файл), тому permissive any.json",
+      "description": "plugin.toml — маніфест wasm-плагіна n-rules:plugin@3.1.0 (crates/<guest>/plugin.toml); офіційної JSON Schema поки нема (schemars-схема rules_contract::manifest::Manifest ще не публікується як окремий файл), тому permissive any.json",
       "url": "any.json",
       "fileMatch": [
         "plugin.toml",

package/scripts/lib/lint-surface/wasm-plugins.mjs

@@ -7,7 +7,9 @@
  * (значення — НЕ голий рядок шляху, доккомент [`buildWasmConcernMap`] нижче).
  *
  * **Run-tool контур (задача N1, рішення Д спеки)**: `manifest.tools` —
- * задекларовані зовнішні tool-залежності плагіна (напр. `"shellcheck@^0.9"`).
+ * задекларовані зовнішні tool-залежності плагіна (напр. `"shellcheck@^0.9"`,
+ * `"path:bun"` — схеми резолву, рішення В спеки
+ * `docs/specs/2026-08-01-plugin-contract-v31-surfaces.md`, [`parseToolRef`]).
  * Для кожного запису резолвер кличе ensure-tool контур (`ensureToolAsync`,
  * `../ensure-tool.mjs`, injectable через `opts.ensureToolFn`) — будує мапу
  * «ім'я тула (без semver-суфікса декларації) → абсолютний шлях», яку
@@ -114,6 +116,7 @@ import { fileURLToPath } from 'node:url'
 
 import { ensureToolAsync } from '../ensure-tool.mjs'
 import { loadNative } from '../native.mjs'
+import { resolveCmd } from '../../utils/resolve-cmd.mjs'
 
 /**
  * Абсолютний шлях до `npm/wasm-plugins/` — тека, куди `build-wasm-plugins.mjs`
@@ -431,16 +434,39 @@ async function resolveEntryPath(entry, ctx) {
 }
 
 /**
- * Ім'я тула без semver-суфікса декларації (`"shellcheck@^0.9"` → `"shellcheck"`)
- * — той самий парсинг, що host-бік `ToolResolver::run`
- * (`crates/rules-plugin-host/src/tool_resolver.rs`, доккомент модуля
- * пояснює версійну політику — вона НЕ тут, ensure-tool ставить канонічну
- * закріплену версію).
+ * Схеми резолву тула в рядку `manifest.tools` (рішення В спеки
+ * `docs/specs/2026-08-01-plugin-contract-v31-surfaces.md`). Дзеркало
+ * Rust-боку (`rules_contract::validators::tool::ToolScheme`) — і саме
+ * ДЗЕРКАЛО, а не незалежний список: розбіжність означала б, що маніфест,
+ * прийнятий хостом, мовчки не резолвиться оркестрацією.
+ */
+const TOOL_SCHEMES = {
+  /** Github-реліз із закріпленою версією (`TOOLS` + `tool-pins.json`) — дефолт за відсутності схеми. */
+  PINNED: 'pinned',
+  /** Резолв по `PATH` (`bun`, `bunx` — ensure-tool не вміє і не має їх завантажувати). */
+  PATH: 'path'
+}
+
+/**
+ * Розбирає запис `manifest.tools` у `{ scheme, name }`: відрізає схему
+ * (якщо є), потім semver-суфікс декларації (`"path:bun@^1.2"` →
+ * `{ scheme: 'path', name: 'bun' }`). Порт
+ * `rules_contract::validators::tool::parse_tool_ref` — дзеркальний тест
+ * конвенції: `tests/wasm-plugins.test.mjs`.
+ *
+ * Невідома схема НЕ інтерпретується як частина імені: [`ensureDeclaredTools`]
+ * пропускає такий запис із warn, бо резолвити його однаково нема чим (та
+ * сама поведінка, що host-валідатор `validate_tool_ref`).
  * @param {string} declared запис із `manifest.tools`
- * @returns {string} ім'я тула
+ * @returns {{ scheme: string | null, name: string }} схема (`null` — невідома) й ім'я тула
  */
-function toolName(declared) {
-  return declared.split('@', 1)[0]
+function parseToolRef(declared) {
+  const separator = declared.indexOf(':')
+  if (separator === -1) return { scheme: TOOL_SCHEMES.PINNED, name: declared.split('@', 1)[0] }
+  const prefix = declared.slice(0, separator)
+  const rest = declared.slice(separator + 1)
+  if (prefix !== TOOL_SCHEMES.PINNED && prefix !== TOOL_SCHEMES.PATH) return { scheme: null, name: declared }
+  return { scheme: prefix, name: rest.split('@', 1)[0] }
 }
 
 /**
@@ -456,14 +482,26 @@ function toolName(declared) {
  * @param {string} pluginName ім'я плагіна (лише для diagnostics-повідомлень)
  * @param {string[]} declaredTools `manifest.tools` — рядки виду `"shellcheck@^0.9"`
  * @param {(toolId: string) => Promise<string>} ensureToolFn ін'єкція `ensureToolAsync` (тести підміняють)
+ * @param {(cmd: string) => string | null} resolveCmdFn ін'єкція `resolveCmd` для схеми `path:` (тести підміняють — інакше результат залежав би від PATH машини)
  * @returns {Promise<Record<string, string>>} ім'я тула (без semver-суфікса) → абсолютний шлях
  */
-async function ensureDeclaredTools(pluginName, declaredTools, ensureToolFn) {
+async function ensureDeclaredTools(pluginName, declaredTools, ensureToolFn, resolveCmdFn) {
   /** @type {Record<string, string>} */
   const toolPaths = {}
   for (const declared of declaredTools) {
-    const name = toolName(declared)
+    const { scheme, name } = parseToolRef(declared)
     try {
+      if (scheme === null)
+        throw new Error(`невідома схема резолву (відомі "${TOOL_SCHEMES.PINNED}:", "${TOOL_SCHEMES.PATH}:")`)
+      if (scheme === TOOL_SCHEMES.PATH) {
+        // `path:` НЕ йде в ensure-tool контур узагалі: той уміє лише
+        // github-релізи, а `bun`/`bunx` встановлює користувач. Відсутність —
+        // не помилка резолву плагіна, а звичайний skip одного тула.
+        const fromPath = resolveCmdFn(name)
+        if (!fromPath) throw new Error('не знайдено в PATH')
+        toolPaths[name] = fromPath
+        continue
+      }
       toolPaths[name] = await ensureToolFn(name)
     } catch (error) {
       console.warn(
@@ -484,7 +522,7 @@ async function ensureDeclaredTools(pluginName, declaredTools, ensureToolFn) {
  * запис у мапу для кожного `manifest.concerns`. Усі кроки — skip-not-crash
  * (доккомент модуля).
  * @param {string} cwd абсолютний корінь consumer-репо
- * @param {{fetchFn: typeof fetch, cacheDir: string, env: Record<string, string | undefined>, ensureToolFn: (toolId: string) => Promise<string>, nativeFn: typeof loadNative, builtinPinsDir: string}} ctx ін'єктовані залежності
+ * @param {{fetchFn: typeof fetch, cacheDir: string, env: Record<string, string | undefined>, ensureToolFn: (toolId: string) => Promise<string>, resolveCmdFn: (cmd: string) => string | null, nativeFn: typeof loadNative, builtinPinsDir: string}} ctx ін'єктовані залежності
  * @returns {Promise<Map<string, WasmConcernMapEntry>>} ключ концерну → `{ wasmPath, toolPaths }`
  */
 async function buildWasmConcernMap(cwd, ctx) {
@@ -500,7 +538,7 @@ async function buildWasmConcernMap(cwd, ctx) {
       console.warn(`⚠️ wasm-плагін "${entry.name}" пропущено: не вдалось завантажити (${error.message})`)
       continue
     }
-    const toolPaths = await ensureDeclaredTools(entry.name, manifest.tools ?? [], ctx.ensureToolFn)
+    const toolPaths = await ensureDeclaredTools(entry.name, manifest.tools ?? [], ctx.ensureToolFn, ctx.resolveCmdFn)
     // `manifest.concerns` — масив структурованих контрибуцій `{ key, scope, glob }`
     // (задача N2, передумова full-scope мосту, доккомент `wit/world.wit`
     // `record concern-contribution`), не голі рядки — мапа концернів індексується
@@ -521,9 +559,10 @@ async function buildWasmConcernMap(cwd, ctx) {
  * неминуче асинхронні; єдиний виклик-сайт (`detect.mjs`) вже `async`,
  * контракт виклику не ламається.
  * @param {string} cwd абсолютний корінь consumer-репо (звідки читається `.n-rules.json`)
- * @param {{fetchFn?: typeof fetch, cacheDir?: string, env?: Record<string, string | undefined>, ensureToolFn?: (toolId: string) => Promise<string>, nativeFn?: typeof loadNative, builtinPinsDir?: string}} [opts] ін'єкції для тестів:
+ * @param {{fetchFn?: typeof fetch, cacheDir?: string, env?: Record<string, string | undefined>, ensureToolFn?: (toolId: string) => Promise<string>, resolveCmdFn?: (cmd: string) => string | null, nativeFn?: typeof loadNative, builtinPinsDir?: string}} [opts] ін'єкції для тестів:
  *   `fetchFn` (дефолт — глобальний `fetch`), `cacheDir` (дефолт — `resolvePluginCacheDir`), `env` (дефолт — `process.env`),
- *   `ensureToolFn` (дефолт — `ensureToolAsync`), `nativeFn` (дефолт — `loadNative`, wiring-тести підміняють фейковим addon-ом),
+ *   `ensureToolFn` (дефолт — `ensureToolAsync`), `resolveCmdFn` (дефолт — `resolveCmd`; тести підміняють, бо інакше
+ *   `path:`-схема давала б різний `toolPaths` залежно від PATH машини), `nativeFn` (дефолт — `loadNative`, wiring-тести підміняють фейковим addon-ом),
  *   `builtinPinsDir` (дефолт — [`WASM_PLUGINS_DIR`], реальна `npm/wasm-plugins/`; тести ізолюють неіснуючим каталогом,
  *   щоб локальна wasm-збірка в робочому дереві не підмішувала builtin-контрибуції в контрольовані сценарії)
  * @returns {Promise<Map<string, WasmConcernMapEntry>>} ключ концерну (`ruleId/concernId`) → `{ wasmPath, toolPaths }`
@@ -536,6 +575,7 @@ export function resolveWasmConcernMap(cwd, opts = {}) {
     cacheDir: opts.cacheDir ?? resolvePluginCacheDir(env),
     env,
     ensureToolFn: opts.ensureToolFn ?? ensureToolAsync,
+    resolveCmdFn: opts.resolveCmdFn ?? resolveCmd,
     nativeFn: opts.nativeFn ?? loadNative,
     builtinPinsDir: opts.builtinPinsDir ?? WASM_PLUGINS_DIR
   }

package/scripts/lib/resolve-plugins.mjs

@@ -283,7 +283,7 @@ export const KNOWN_PLUGIN_RANGES = Object.freeze({
   '@7n/rules-ci-azure': '^2',
   '@7n/rules-lang-js': '^0.26',
   '@7n/rules-lang-python': '^0.12',
-  '@7n/rules-lang-rust': '^0.15',
+  '@7n/rules-lang-rust': '^0.16',
   '@7n/rules-lang-php': '^0.3'
 })
 

package/skills/wasm-plugin/SKILL.md

@@ -441,6 +441,49 @@ per-file: пиши `detect_whole_batch(files: &[SourceFile]) -> Vec<Diagnostic>`
     фейковий бінарник (shell-скрипт у tempdir) у `ToolResolver::new(map)`
     (зразок — `run_tool_reaches_resolved_fake_tool_binary`
     `crates/rules-plugin-host/tests/contract_test_kit.rs`).
+- **`exec-tool`** (зріз 5 контракту v3.1, спека
+  `docs/specs/2026-08-01-plugin-contract-v31-surfaces.md`, рішення А/Б/В/З) —
+  `run-tool` ПЛЮС виконавчий контекст. Бери його, якщо тулу потрібне бодай
+  щось із трьох:
+  - **`cwd`** (posix-relative від кореня репо; `none` — сам корінь). Без
+    нього процес успадковує cwd ХОСТ-процесу, який збігається з коренем репо
+    випадково. Обгортка, що читає `node_modules`/конфіги відносно себе, без
+    цього поля перевіряє не той каталог;
+  - **`env`** — пари НАКЛАДАЮТЬСЯ поверх успадкованого середовища, не
+    заміщують його;
+  - **scratch-обмін**: `scratch-in` хост матеріалізує у тимчасовому каталозі
+    ПЕРЕД спавном (вшиті в компонент конфіги/політики), `scratch-out` —
+    глоби файлів, які хост зчитує ПІСЛЯ виходу процесу (звіти тула).
+    Абсолютний шлях каталогу гість бере зі слоту `scratch-dir@1`
+    (`host-context`) і САМ кладе його в `args` — placeholder-підстановки в
+    аргументах контракт свідомо не має. Каталог живе РІВНО один
+    `detect`/`fix`-виклик, тож шлях не можна кешувати між викликами;
+    відсутній `scratch-out`-файл — не помилка, а «звіту немає».
+
+  Помилки — та сама форма, що в `run-tool`: `status: none` + людиночитний
+  `stderr`, ніколи не паніка. `exec-tool` виконує ВЖЕ зарезолвлений тул і
+  нічого не добуває — провізіонінг живе в окремій команді `tools ensure`.
+
+  **Схеми `manifest.tools`** (рішення В): `pinned:` (дефолт за відсутності
+  схеми — github-реліз із закріпленою версією) і `path:` (резолв по `PATH`:
+  `path:bun`, `path:bunx` — те, що ensure-tool завантажити не може й не має).
+
+  > **Trust boundary — прочитай ДО того, як напишеш перший `exec-tool`.**
+  > Спавнений тул виконується **з правами хоста, ПОЗА wasm-пісочницею**, і
+  > **МОЖЕ писати в репо**. Ані `fs_read`, ані `network` до нього не
+  > застосовуються: пісочниця обмежує wasm-код гостя, а не процес, який гість
+  > попросив запустити. Хост звужує лише ЯКИЙ бінарник (задекларований),
+  > ЗВІДКИ він стартує (`cwd` — безпечний repo-relative) і ЩО потрапляє у
+  > scratch (без `..`, з лімітами). Тобто **межа довіри плагіна — його пін
+  > (`url` + `sha256`), а не пісочниця**: ревʼю піна = ревʼю прав.
+  > Enforcement не додається свідомо (потрібен був би власний sandbox-шар
+  > навколо спавна на трьох ОС).
+
+  Живий зразок — `bun/licensee` (`crates/plugin-lang-js/src/lib.rs`, секція
+  «Зріз 5»); golden-тести з фейковим `bun` —
+  `crates/rules-plugin-host/tests/plugin_lang_js.rs`; повний контекст разом
+  (cwd + env + scratch) — `test/guest-exec-tool`
+  у `crates/test-plugin-guest`.
 - **`ci_artifacts`** (слот `ci.artifact@1`): типізовані записи
   `n-rules:slots` (`crates/rules-contract/src/slots/ci_artifact.rs`) —
   семантичні перевірки (safe-path, id-regex) живуть у