@7n/llm-lib 2.1.1 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [2.2.0] - 2026-07-11
+
+### Added
+
+- anchored-edit (Фаза A2): строгі hash-anchored read_anchored/edit_anchored tools, opts.anchoredEdits у runAgentFix (toolset-профіль без built-in read/edit), edit_anchored під write-guard veto/snapshot
+
 ## [2.1.1] - 2026-07-11
 
 ### Changed

package/lib/agent-fix.mjs

@@ -32,6 +32,7 @@
 
 import { env } from 'node:process'
 import { homedir } from 'node:os'
+import { createAnchoredTools } from './anchored-edit.mjs'
 import { getRegistry, resolveModelSpec } from './internal/registry.mjs'
 import { isLocalModel, thinkingLevelForTier } from './model-tiers.mjs'
 import { createWriteGuard, gitRoot } from './write-guard.mjs'
@@ -152,7 +153,7 @@ async function runVerifyLoop({ session, verify, verifyMax, timeoutMs, startedAt,
  *   єдині наявні файли, які дозволено редагувати (порожньо/відсутнє — без переліку).
  * @returns {string} промпт
  */
-export function buildFixPrompt({ ruleId, violation, ruleText, feedback, targetFiles }) {
+export function buildFixPrompt({ ruleId, violation, ruleText, feedback, targetFiles, anchoredEdits = false }) {
   const parts = [`Виправ порушення правила "${ruleId}" у цьому проєкті.`]
   if (ruleText) parts.push(`## Правило\n${ruleText}`)
   parts.push(`## Порушення\n${violation}`)
@@ -176,6 +177,13 @@ export function buildFixPrompt({ ruleId, violation, ruleText, feedback, targetFi
       'Після правок виклич `self_check`, щоб підтвердити, що порушення зникло. ' +
       'Редагуй лише потрібне, не чіпай стороннє.'
   )
+  if (anchoredEdits) {
+    parts.push(
+      'Наявні файли читай і редагуй ЛИШЕ через `read_anchored` → `edit_anchored` ' +
+        '(кожна правка = {anchor, line, newText} з якорями від read_anchored; ' +
+        'stale anchor = перечитай файл і повтори). `write` — лише для НОВИХ файлів.'
+    )
+  }
   return parts.join('\n\n')
 }
 
@@ -187,7 +195,17 @@ export function buildFixPrompt({ ruleId, violation, ruleText, feedback, targetFi
  *   selfCheck: (files: string[]) => Promise<{ ok: boolean, output: string }> | { ok: boolean, output: string } }} args параметри сесії.
  * @returns {Promise<object>} pi AgentSession
  */
-async function defaultCreateSession({ registry, model, thinkingLevel, cwd, factory, astContext, selfCheck, chain }) {
+async function defaultCreateSession({
+  registry,
+  model,
+  thinkingLevel,
+  cwd,
+  factory,
+  astContext,
+  selfCheck,
+  chain,
+  anchoredEdits = false
+}) {
   const { createAgentSession, SessionManager, DefaultResourceLoader, SettingsManager, defineTool } =
     await import('@earendil-works/pi-coding-agent')
   const agentDir = `${homedir()}/.pi/agent`
@@ -226,13 +244,23 @@ async function defaultCreateSession({ registry, model, thinkingLevel, cwd, facto
     })
   })
 
+  // A2: anchored-профіль заміняє built-in read/edit на строгі read_anchored/edit_anchored
+  // (write лишається для НОВИХ файлів, під тим самим write-guard).
+  let tools = ['read', 'grep', 'find', 'edit', 'write', 'ls', 'ast_facts', 'self_check']
+  const customTools = [astTool, checkTool]
+  if (anchoredEdits) {
+    const { readTool, editTool } = createAnchoredTools({ cwd, defineTool })
+    tools = ['grep', 'find', 'write', 'ls', 'ast_facts', 'self_check', 'read_anchored', 'edit_anchored']
+    customTools.push(readTool, editTool)
+  }
+
   const { session } = await createAgentSession({
     modelRegistry: registry,
     model,
     thinkingLevel,
     cwd,
-    tools: ['read', 'grep', 'find', 'edit', 'write', 'ls', 'ast_facts', 'self_check'],
-    customTools: [astTool, checkTool],
+    tools,
+    customTools,
     sessionManager: SessionManager.inMemory(),
     resourceLoader: loader
   })
@@ -250,6 +278,7 @@ async function defaultCreateSession({ registry, model, thinkingLevel, cwd, facto
  *   targetFiles?: string[],
  *   verify?: (args: { touchedFiles: string[] }) => Promise<{ ok: boolean, output?: string }> | { ok: boolean, output?: string },
  *   verifyMax?: number,
+ *   anchoredEdits?: boolean,
  *   deps?: { createSession?: (args: object) => Promise<object>, getRegistry?: () => Promise<object>,
  *            registry?: object, root?: string|null,
  *            astContext?: (path: string) => object,
@@ -270,6 +299,7 @@ export async function runAgentFix(ruleId, violation, cwd, opts = {}) {
     targetFiles,
     verify = null,
     verifyMax = VERIFY_MAX_DEFAULT,
+    anchoredEdits = false,
     deps = {}
   } = opts
   const createSession = deps.createSession ?? defaultCreateSession
@@ -328,6 +358,7 @@ export async function runAgentFix(ruleId, violation, cwd, opts = {}) {
       factory: guard.factory,
       astContext,
       selfCheck,
+      anchoredEdits,
       // Заголовки кореляції — лише локальним моделям (myllm стоїть тільки перед ними).
       chain: modelSpec && isLocalModel(modelSpec) ? chain : null
     })
@@ -376,7 +407,7 @@ export async function runAgentFix(ruleId, violation, cwd, opts = {}) {
     }
   })
 
-  const fixPrompt = buildFixPrompt({ ruleId, violation, ruleText, feedback, targetFiles })
+  const fixPrompt = buildFixPrompt({ ruleId, violation, ruleText, feedback, targetFiles, anchoredEdits })
   const pHash = promptHash(fixPrompt)
   const startedAt = clock()
   let error = null
@@ -439,6 +470,7 @@ export async function runAgentFix(ruleId, violation, cwd, opts = {}) {
     backstopHit,
     verifyAttempts: verifyAttempts.length,
     verifyOk: verifyAttempts.length > 0 ? verifyAttempts.at(-1).ok : null,
+    anchoredEdits,
     wallMs: clock() - startedAt,
     error,
     ...chain?.traceFields()

package/lib/anchored-edit.mjs

@@ -0,0 +1,198 @@
+/** @see ./docs/anchored-edit.md */
+
+/**
+ * Hash-anchored line-editing (Фаза A2 run-harness, дизайн 2026-07-11).
+ *
+ * Строга заміна built-in `read`/`edit` для fix-профілів: кожен рядок файлу має
+ * 3-символьний base36-якір від хешу вмісту; правка застосовується ЛИШЕ якщо якір
+ * збігається з поточним вмістом рядка. Жодного fuzzy-match, мовчазного переміщення
+ * чи автокорекції (клас collateral слабких моделей: переписаний файл, літеральний
+ * `\n\n`). Будь-який mismatch → структурована відмова `stale anchor` БЕЗ часткового
+ * застосування (атомарно на файл) — агенту лишається перечитати файл і повторити.
+ *
+ * Референс патерну — pi-hashline-edit-pro (вендоримо ідею, не пакет: рішення Б спеки
+ * pi-harness-mt-fix-graph). Хеш — `node:crypto` sha256-префікс (нуль нових залежностей;
+ * контекст не sensitive — якір лише детектує розбіжність вмісту рядка).
+ *
+ * Модуль pi-free: чисті функції над рядками + фабрика tool-дефініцій, якій caller
+ * (agent-fix) передає pi `defineTool` через lazy import. Запис на диск робить
+ * tool `edit_anchored` — він у WRITE_TOOLS write-guard, тож підлягає тому самому
+ * scope/denylist veto, pre-image snapshot і rollback, що й built-in `edit`/`write`.
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { isAbsolute, resolve } from 'node:path'
+
+/** Довжина якоря у base36-символах (36³ = 46656 значень — на рядок, не на файл). */
+const ANCHOR_LEN = 3
+
+/**
+ * Якір рядка: перші 3 base36-символи sha256 від вмісту рядка.
+ * Навмисно БЕЗ номера рядка у хеші: якір «прив'язаний до вмісту», а номер іде
+ * окремим полем правки — розбіжність будь-якого з двох означає stale-стан.
+ * @param {string} text вміст рядка (без завершального \n)
+ * @returns {string} 3-символьний base36-якір
+ */
+export function lineAnchor(text) {
+  const h = createHash('sha256').update(text, 'utf8').digest()
+  return (h.readUInt32BE(0) % 36 ** ANCHOR_LEN).toString(36).padStart(ANCHOR_LEN, '0')
+}
+
+/**
+ * Рендерить вміст файлу у anchored-форматі: `якір|номер|текст`, нумерація з 1.
+ * @param {string} content повний вміст файлу
+ * @param {{ from?: number, to?: number }} [range] діапазон рядків (включно, 1-based)
+ * @returns {string} anchored-подання (по рядку на кожен рядок діапазону)
+ */
+export function renderAnchored(content, { from = 1, to = Infinity } = {}) {
+  const lines = content.split('\n')
+  const out = []
+  for (let i = from; i <= Math.min(to, lines.length); i++) {
+    const text = lines[i - 1]
+    out.push(`${lineAnchor(text)}|${i}|${text}`)
+  }
+  return out.join('\n')
+}
+
+/**
+ * Атомарно застосовує anchored-правки до вмісту файлу.
+ *
+ * Валідація ПЕРЕД застосуванням: кожна правка перевіряється на (а) існування рядка,
+ * (б) збіг якоря з поточним вмістом. Хоч одна stale → нічого не застосовується.
+ * Семантика правки: `newText` — заміна рядка (може бути багаторядковим), `null` —
+ * видалення рядка. Дублікати номера рядка у списку правок — теж відмова (двозначно).
+ * @param {string} content поточний вміст файлу
+ * @param {Array<{ anchor: string, line: number, newText: string|null }>} edits правки
+ * @returns {{ ok: true, content: string } | { ok: false, stale: Array<{ line: number, reason: string }> }}
+ *   новий вміст або перелік розбіжностей (для структурованої відповіді агенту)
+ */
+export function applyAnchoredEdits(content, edits) {
+  const lines = content.split('\n')
+  const stale = []
+  const seen = new Set()
+  for (const e of edits) {
+    if (!Number.isSafeInteger(e.line) || e.line < 1 || e.line > lines.length) {
+      stale.push({ line: e.line, reason: `рядка ${e.line} не існує (у файлі ${lines.length})` })
+      continue
+    }
+    if (seen.has(e.line)) {
+      stale.push({ line: e.line, reason: `рядок ${e.line} правиться двічі в одному виклику` })
+      continue
+    }
+    seen.add(e.line)
+    const actual = lineAnchor(lines[e.line - 1])
+    if (e.anchor !== actual) {
+      stale.push({ line: e.line, reason: `stale anchor ${e.anchor} (актуальний ${actual}) — перечитай файл` })
+    }
+  }
+  if (stale.length > 0) return { ok: false, stale }
+
+  // Застосування знизу вгору — номери рядків вище не зсуваються.
+  const sorted = edits.toSorted((a, b) => b.line - a.line)
+  for (const e of sorted) {
+    if (e.newText === null) lines.splice(e.line - 1, 1)
+    else lines.splice(e.line - 1, 1, ...e.newText.split('\n'))
+  }
+  return { ok: true, content: lines.join('\n') }
+}
+
+/**
+ * Резолвить шлях tool-виклику відносно cwd сесії.
+ * @param {string} cwd робоча директорія сесії
+ * @param {string} raw шлях із tool-input
+ * @returns {string} абсолютний шлях
+ */
+function resolvePath(cwd, raw) {
+  return isAbsolute(raw) ? raw : resolve(cwd, raw)
+}
+
+/**
+ * Структурована текстова відмова tool-виклику (JSON-текст — слабкі моделі бачать
+ * точну причину і наступний крок).
+ * @param {object} payload обʼєкт з `error` (+ опційні деталі)
+ * @returns {{ content: Array<{ type: string, text: string }>, details: object }} tool-результат
+ */
+function toolFail(payload) {
+  return { content: [{ type: 'text', text: JSON.stringify(payload) }], details: {} }
+}
+
+/**
+ * Фабрика пари pi-tools `read_anchored`/`edit_anchored`.
+ *
+ * `defineTool` передається caller-ом (lazy pi-import в agent-fix) — модуль лишається
+ * pi-free. Обидва tools повертають результат текстом (JSON для помилок), щоб слабкі
+ * моделі бачили точну причину відмови і мали інструкцію наступного кроку.
+ * @param {{ cwd: string, defineTool: (def: object) => object,
+ *   fs?: { existsSync?: typeof existsSync, readFileSync?: typeof readFileSync, writeFileSync?: typeof writeFileSync } }} args
+ *   контекст: cwd сесії, pi defineTool, опційні fs-інжекції для тестів
+ * @returns {{ readTool: object, editTool: object }} tool-дефініції для customTools
+ */
+export function createAnchoredTools({ cwd, defineTool, fs = {} }) {
+  const exists = fs.existsSync ?? existsSync
+  const read = fs.readFileSync ?? readFileSync
+  const write = fs.writeFileSync ?? writeFileSync
+
+  const readTool = defineTool({
+    name: 'read_anchored',
+    label: 'Read (anchored)',
+    description:
+      'Read a file as anchored lines "anchor|lineNo|text". To edit an existing file you MUST read it with this tool first and use the returned anchors in edit_anchored.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'file path' },
+        from: { type: 'number', description: 'first line (1-based, optional)' },
+        to: { type: 'number', description: 'last line (inclusive, optional)' }
+      },
+      required: ['path']
+    },
+    execute: (_id, { path, from, to }) => {
+      const abs = resolvePath(cwd, path)
+      if (!exists(abs)) return toolFail({ error: `файл не існує: ${path}` })
+      const text = renderAnchored(read(abs, 'utf8'), { from: from ?? 1, to: to ?? Infinity })
+      return { content: [{ type: 'text', text }], details: {} }
+    }
+  })
+
+  const editTool = defineTool({
+    name: 'edit_anchored',
+    label: 'Edit (anchored)',
+    description:
+      'Strictly edit a file by anchored lines. Each edit = {anchor, line, newText}; newText replaces the whole line (may be multiline), null deletes the line. Anchors come from read_anchored. Any stale anchor rejects the WHOLE call — re-read the file and retry. No fuzzy matching.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'file path' },
+        edits: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              anchor: { type: 'string', description: '3-char anchor from read_anchored' },
+              line: { type: 'number', description: '1-based line number' },
+              newText: { type: ['string', 'null'], description: 'replacement text (null = delete line)' }
+            },
+            required: ['anchor', 'line']
+          }
+        }
+      },
+      required: ['path', 'edits']
+    },
+    execute: (_id, { path, edits }) => {
+      const abs = resolvePath(cwd, path)
+      if (!exists(abs)) return toolFail({ error: `файл не існує: ${path} — для нового файлу використовуй write` })
+      if (!Array.isArray(edits) || edits.length === 0) return toolFail({ error: 'edits порожній' })
+      const normalized = edits.map(e => ({ anchor: e.anchor, line: e.line, newText: e.newText ?? null }))
+      const res = applyAnchoredEdits(read(abs, 'utf8'), normalized)
+      if (!res.ok) return toolFail({ error: 'stale anchors — нічого не застосовано', stale: res.stale })
+      write(abs, res.content)
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ ok: true, applied: normalized.length }) }],
+        details: {}
+      }
+    }
+  })
+
+  return { readTool, editTool }
+}

package/lib/docs/agent-fix.md

@@ -3,7 +3,7 @@ type: JS Module
 title: agent-fix.mjs
 resource: llm-lib/lib/agent-fix.mjs
 docgen:
-  crc: 0f2be7f8
+  crc: 730809af
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 
@@ -18,6 +18,8 @@ buildFixPrompt готує текстовий промпт, що містить
 runAgentFix виконує повний агентний цикл для спроби виправлення порушення правила, включаючи взаємодію з інструментами, застосування патча та фіксацію телеметрії.
 Виклик сесії огорнутий timeout-гонкою: `opts.timeoutMs` (дефолт 300s, коли consumer не передав значення) на спрацюванні abort-ить сесію і повертає помилку `fix timeout …` — зависла LLM-сесія (напр. мертва SSE) не блокує виклик назавжди.
 
+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

package/lib/docs/anchored-edit.md

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: anchored-edit.mjs
+resource: llm-lib/lib/anchored-edit.mjs
+docgen:
+  crc: 6ac40e43
+---
+
+## Огляд
+
+Строге hash-anchored редагування рядків (Фаза A2 run-harness): заміна built-in `read`/`edit` для fix-профілів. Кожен рядок файлу отримує 3-символьний base36-якір від sha256 вмісту; правка застосовується лише при точному збігу якоря з поточним станом рядка. Мета — прибрати collateral слабких моделей (переписаний файл, літеральний `\n\n`): жодного fuzzy-match, мовчазного переміщення чи автокорекції. Референс патерну — pi-hashline-edit-pro (вендориться ідея, не пакет).
+
+## Поведінка
+
+Рендер (`renderAnchored`) віддає рядки у форматі `якір|номер|текст` (нумерація з 1, опційний діапазон включно). Застосування (`applyAnchoredEdits`) атомарне на файл: усі правки спершу валідуються (існування рядка, збіг якоря, відсутність дублю номера) — хоч одна розбіжність означає повну відмову з переліком `stale`-причин, файл не змінюється. Валідні правки застосовуються знизу вгору, тож номери рядків у пакеті правок не зсуваються; `newText` заміняє рядок (може бути багаторядковим), `null` — видаляє.
+
+Tool-фабрика (`createAnchoredTools`) створює пару pi-tools: `read_anchored` (файл або діапазон в anchored-форматі; неіснуючий файл — структурована помилка) і `edit_anchored` (правки `{anchor, line, newText}`; stale → JSON-відмова з інструкцією перечитати файл; для нових файлів чесно відсилає до `write`). `defineTool` передається caller-ом — модуль лишається pi-free; fs-операції інжектовані для тестів.
+
+## Публічний API
+
+lineAnchor — 3-символьний base36-якір від sha256 вмісту рядка (детермінований, чутливий до будь-якої зміни тексту).
+renderAnchored — anchored-подання вмісту файлу для читання агентом.
+applyAnchoredEdits — атомарне застосування пакету правок або структурована відмова `{ok:false, stale:[…]}`.
+createAnchoredTools — фабрика tool-дефініцій `read_anchored`/`edit_anchored` для customTools pi-сесії.
+
+## Де використовується
+
+`agent-fix.mjs`: `opts.anchoredEdits` перемикає toolset сесії (built-in `read`/`edit` прибираються, `write` лишається для нових файлів). `edit_anchored` внесений у WRITE_TOOLS write-guard — той самий scope/denylist veto, pre-image snapshot і rollback, що й у built-in write-tools. Opt-in у cursor: env `N_LLM_FIX_ANCHORED` (default-worker).
+
+## Гарантії поведінки
+
+- Атомарність на файл: часткове застосування пакету правок неможливе.
+- Якір прив'язаний лише до вмісту рядка; номер рядка звіряється окремо — розбіжність будь-якого з двох дає відмову.
+- Чисті функції не торкаються диска; запис робить лише `edit_anchored` (під write-guard).

package/lib/docs/write-guard.md

@@ -3,7 +3,7 @@ type: JS Module
 title: write-guard.mjs
 resource: llm-lib/lib/write-guard.mjs
 docgen:
-  crc: b95012fc
+  crc: b5110048
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 
@@ -16,6 +16,7 @@ docgen:
 NEW_FILE позначає файл, якого до запису не існувало.
 gitRoot визначає кореневий каталог репозиторію Git, якщо він є.
 createWriteGuard створює механізм захисту записів до файлової системи, який перевіряє, чи запис знаходиться в межах кореневого каталогу Git, чи не стосується він директорій `.git` або ігнорованих файлів Git, і робить резервні копії файлів перед будь-якою зміною.
+Під veto/snapshot підпадають tool-виклики `edit`, `write` і `edit_anchored` (anchored-профіль Фази A2, див. anchored-edit.md) — кастомний anchored-tool проходить той самий контроль, що й built-in write-tools.
 
 ## Публічний API
 

package/lib/write-guard.mjs

@@ -27,8 +27,8 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'nod
 /** Sentinel pre-image для файлу, якого до запису не існувало (rollback = видалити). */
 export const NEW_FILE = Symbol('new-file')
 
-/** Tool-и, що пишуть на диск і підлягають veto. */
-const WRITE_TOOLS = new Set(['edit', 'write'])
+/** Tool-и, що пишуть на диск і підлягають veto (включно з anchored-варіантом A2). */
+const WRITE_TOOLS = new Set(['edit', 'write', 'edit_anchored'])
 
 /**
  * git-root для cwd (`git rev-parse --show-toplevel`) або null, якщо не git-репо.

package/package.json

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