apatch — Agent Patch & Trace Analyzer 🚀🛡️

ИИ-агент сломал файл на 7-м шаге из 10? apatch применит ровно нужные шаги из лога — даже если файл с тех пор изменился.

apatch — это специализированный инструмент для надежного применения правок кода и документации ИИ-агентов (Cursor, Claude Code, Antigravity, Gemini), безопасного декомпозирования монолитов и ведения транзакционных баз знаний без context drift.

---

Что это решает? (Проблема Context Drift)

Представьте классическую ситуацию: вы работаете с ИИ-агентом. Он предлагает вам изменение в файле кода или документации. Но пока вы обсуждали детали или запускали тесты, в файл были внесены косметические изменения, добавлены комментарии, изменены отступы или перефразированы абзацы. Контекст «уплыл» (context drift).

Обычный инструмент замены (str_replace или git apply) выбросит ошибку «Строка не найдена».

apatch решает эту проблему с помощью многоуровневых алгоритмов сопоставления и стабильного непозиционного анкерования (Semantic ID Anchoring), позволяя хирургически применять изменения даже в уплывший контекст исходного кода и документации.

---

Главные фичи «из коробки»

💻 Для кода

• Транзакционный Matcher кода:
  • Level 1 (Exact): Буквальное посимвольное совпадение.
  • Level 2 (Whitespace-Fuzzy): Нечувствительный к пробелам, табам и пустым строкам поиск.
  • Level 3 (AST-Fuzzy): Синтаксическое сопоставление через грамматики tree-sitter. Находит узел по имени (метод класса в C++ или Python), при нескольких одноимённых узлах дизамбигуирует по охватывающему классу и схожести тела, и заменяет только тело функции, сохраняя сигнатуру родительского файла нетронутой. Если предложенная правка меняла сигнатуру — выводится предупреждение (тело-only замена). Из коробки: C++, Python, JavaScript, TypeScript, Rust, Go; опционально (extra languages): Java, C#, Ruby, PHP, Kotlin, Swift.
• Умная декомпозиция и дедупликация (apatch strip):
  • Вырезает логические блоки кода во внешние файлы с авторазрешением коллизий имен.
  • Генерирует отчет связей extraction_report.json.
  • Автоматически минимизирует зависимости: оставляет в parent_imports только те заголовки/импорты, которые реально используются в вырезанном коде, и очищает accessed_external_members от шума STL-контейнеров (типа size(), empty()).

📝 Для документов (Markdown)

• Непозиционный Matcher Документов:
  • Semantic ID Anchor: Автоматически находит стабильный тег якоря <!-- @sid:claim_N --> и полностью заменяет ассоциированный с ним логический блок, делая правки абсолютно устойчивыми к перефразированию, расширению или перемещению текста внутри файла.
  • Jaccard Similarity Fallback: Нечеткое сопоставление абзацев на основе пересечения слов (коэффициент Жаккара) при отсутствии маркерных тегов разметки.
• Авторазметка и компиляция (apatch compile): Автоматическая генерация стабильных семантических якорей и построение локальных графов знаний knowledge_map.json без внешних SaaS-зависимостей.

🛡️ Для всего (Общие механизмы)

• Парсинг логов ИИ-агентов (Ingestor): Автоматически выгружает кандидатов на правки из сырых .jsonl логов Cursor, Anthropic, Antigravity и стандартного Gemini API; распознаёт вложенные unified-diff и envelope apply_patch (V4A) в полях diff / input / patch.
• Обнаружение транскриптов (apatch scan): Ищет свежие .jsonl в ~/.cursor, ~/.claude, ~/.gemini и текущей папке — не нужно вручную копировать путь из IDE.
• Сухой прогон (apatch plan): Показывает, как каждая правка ляжет на диск (путь, стратегия, confidence, предупреждения) без записи файлов.
• Умные пути (apatch.resolver): Общий модуль resolve_smart_path — каскад из 4 уровней (exact → relative → strip prefix → recursive basename) с защитой от path traversal; одинаковая логика для scan, plan и apply. Session-scoped PathIndex (git ls-files или один pruned walk) ускоряет batch plan/apply на больших деревьях — см. ADR-001. Опционально: APATCH_PATH_BACKEND=fd|watchman|git|walk.
• Enterprise scale: APATCH_AST_WINDOW_BYTES / APATCH_AST_FULL_PARSE_MAX — windowed AST на больших файлах; apatch plan --json --workers N — параллельный dry-run.
• Транзакции шагов (Step-Level Transactions): Полная атомарность многофайловых шагов рефакторинга. Перед началом шага бэкапятся все файлы. В случае падения сборки или тестов выполняется автоматический откат всего шага.
• Интеграция с крипто-реестром TrustChain: Автоматическая фиксация каждого успешного шага в неизменяемом журнале.
• Символьная привязка аттестаций (RFP-032): дрейф требования считается по границам символов (функции/классы, tree-sitter), а не по хэшу всего файла — правка одной функции не роняет требования, завязанные на другие символы того же файла (apatch/symbol_anchor.py). Слепое пятно — кросс-файловые ссылки — закрывает RFP-033 (ниже).
• Непрерывный конформанс (RFP-035): стоячий contract-gate — apatch conformance gate классифицирует весь контракт разом (conformant / drifted / stale / unproven) и ловит спеки, аттестованные однажды и тихо протухшие. Блокирует только на живом красном verify (drifted), не на несвежей подписи (stale) — без ложных тревог. Opt-in (.apatch/conformance.json), scoped-прогоны (--spec SPEC-X), статический enrollment без рекурсии (--no-live), baseline-aware, ledger-free блокировка в CI (--ci-safe); что блокировать — выбор проекта. Доменный ярлык вроде conformance: true и само наличие SPEC не являются enrollment или доказательством: registration, live bucket и evidence qualification отчётно разделяются. См. docs/conformance.md.
• Дифференциальный probe — apatch probe (RFP-005): один примитив «возмути → пере-измерь → суди дельту против полярности», под который сведены три проверки качества гейта. probe falsify портит файлы, что охраняет требование, — verify обязан покраснеть (иначе это ложный гейт, не тестирующий охраняемое); probe regress — ни одного нового падения против записанного корпуса (baseline-aware); probe ratify — аттестованный гейт всё ещё зелёный (красный сейчас = протухшая аттестация). Универсально (--verify — любая shell-команда). См. docs/probe.md.
• Реестр реальности — apatch reality (RFP-005): инверсия источника истины — append-only леждер наблюдаемых фактов, которые проект обязан закрыть (.apatch/reality.jsonl); требования спеки их дискорджат (## Rk … (discharges: REC-…)). apatch reality status считает покрытие как «наблюдаемая реальность, закрытая зелёным гейтом», а uncovered — выводимый долг, не ручной ярлык. См. docs/reality.md.
• Скаффолд спеки из контракта — apatch spec scaffold --from-contract (RFP-023): authoring-инверсия проверки покрытия — из ## Acceptance-таблицы RFP генерит скелет SPEC.md (по требованию на строку + traceability-гейт), contract-complete by construction (0 gaps). Заполняешь (verify:), а не пишешь чеклист руками. Также MCP apatch_spec_scaffold.
• Кросс-файловый refactor-impact — apatch scip impact (RFP-033): при рефакторинге символа показывает, какие аттестованные требования ссылаются на него из других файлов — слепое пятно символьных якорей. Граф ссылок строится нативно из Python AST, без внешних зависимостей (.scip-индекс точнее, если есть). Advisory — никогда не блок и не stale. Также MCP apatch_scip.
• Transparency anchor — governance, проверяемый в CI (A35-E): локальный ledger доказывает governance только на машине, где он шёл; CI его не видит. Каждая governed-операция анкорится во внешний append-only лог (trust-chain.ai), op_id попадает в runtime .apatch/inclusion.jsonl, а проверенный subset публикуется в source-controlled manifests/apatch-inclusion.jsonl. CI-job transparency-anchor проверяет этот manifest против публичного Merkle-корня — без приватных зависимостей. Это первый гейт, который реально доказывает governance в CI (а не «обещает»). Сертификат агента авто-продлевается. См. docs/transparency-anchor.md.
• Нормализация кодировок и переносов строк: Автоматическое определение переносов строк (CRLF vs LF) и автодетект кодировок (UTF-8, CP1251, CP1252) при дисковых операциях с сохранением оригинальных параметров файлов.

---

🛡️ Что такое TrustChain и как это работает?

TrustChain — это локальный криптографический фреймворк сквозного аудита разработки (разработка Ed Cherednik).

Встроенный bootstrap без внешних зависимостей (Zero-Dependency)

Для работы криптографического аудита в apatch вам не требуется отдельно устанавливать TrustChain. apatch имеет встроенный Python-модуль резервного копирования и генерации структуры хэш-чейна:

• Если в вашей системе нет утилиты tc, apatch автоматически инициализирует криптографический реестр во временных файлах структуры .trustchain/ (папки objects/, refs/, HEAD, config.json), подписывая транзакции штатными средствами Python.
• Если CLI tc установлен в вашей системе, apatch автоматически интегрируется с ним, вызывая глобальные команды tc checkpoint и tc commit.

Автоинициализация

Вам не нужно вручную инициализировать аудит в каждом проекте. При первом запуске apatch автоматически ищет папку .trustchain/ вверх по дереву папок. Если она не найдена — утилита сама выполнит tc init в корне вашего репозитория.

Режимы: audit vs enforce

Проверка: apatch doctor --json → поле trustchain.mode:

mode	Когда	Поведение
audit_pending	Нет .trustchain/	Ledger создастся при первом apply/strip
audit	Ledger есть, enforcement выкл	Checkpoint + commit; провал подписи не откатывает apply
enforce	.apatch/enforcement.json	Пошаговая нотаризация, rollback, no_trustchain запрещён

Включить strict: apatch init-consumer --with-enforcement.

---

Быстрый старт: executable specs (~10 мин)

Один data layer (project_status_workspace, MCP apatch_project_status) — три представления для разных ролей (RFP-020):

Роль	Вопрос	Команда
Developer	Что сломано / заблокировано?	apatch status · --json
Architect	Где конфликты спек?	apatch report --html
Manager	Мы в графике?	apatch report --format md

# 1. Scaffold consumer (sandbox + enforcement — для governed apply)
apatch init-consumer --target-dir . --with-sandbox --with-enforcement

# 2. Диагностика окружения
apatch doctor

# 3. Executable spec: lint → dry-run → run (inline requirements или manifest)
apatch spec lint --spec SPEC-YOUR-1
apatch spec run --spec SPEC-YOUR-1 --dry-run
# apatch spec run --spec SPEC-YOUR-1   # resume / MCP: apatch_spec_run

# 4. Три представления одного DTO
apatch status
apatch spec list
apatch report --html --out .apatch/report.html
apatch report --format md --locale ru --out -

TrustChain фиксирует кто / когда / что attested — substrate для attribution (RFP-020 §3).
Плейбук агента: docs/AGENTS.template.md · индекс спек: docs/specs/README.md.

---

Документация

Полная навигация по ролям (пользователь / агент / разработчик): docs/README.md

Нужно	Документ
Консоль — что делать (i/l/p/a/v)	docs/console-guide.md
Руководитель / ИБ — без кода	docs/for-leaders.md
Доменная модель (Session / Invariant)	docs/domain.md
Грамматика команд	docs/grammar.md
Security one-pager (enterprise)	docs/security-one-pager.md
Рецепты CLI	docs/cookbook.md
Непрерывный конформанс (contract-gate)	docs/conformance.md
Transparency anchor — governance проверяемый в CI (A35-E)	docs/transparency-anchor.md
ИИ-агент в проекте	docs/AGENTS.template.md
MCP (15 default / 123 full) · CHANGELOG	docs/mcp_setup.md · runtime invariants · RFP-020 three views · specs index
Локальный MCP roaming по sibling-репозиториям	safe local workspace roaming · agent onboarding
WorkAssets / Наработки	for engineers · for directors · overview · privacy/IP · data access · portability · consent/retention
TrustChain collaborative work	onboarding and operations · RFP-043 · executable SPEC
Write sandbox	docs/sandbox.md
Оркестрация (arch, db, pipeline)	docs/orchestration.md
Strip / декомпозиция	docs/strip_guide.md
Профили стека	docs/profiles/

---

Установка

Системные требования

• Python: 3.9–3.13 рекомендуется; 3.14 поддерживается, но при установленном пакете trustchain + langchain-core возможны предупреждения от LangChain (Pydantic v1). apatch их подавляет; долгосрочно — lazy-import в trustchain.integrations.
• ОС: macOS или Linux.

Установка в виртуальном окружении:

# Создать и активировать окружение
python3 -m venv .venv
source .venv/bin/activate

# Базовая установка (C++, Python, JS/TS, Rust, Go — в core)
pip install -e .

# Опциональные extras (по необходимости)
pip install -e ".[dev]"        # pytest для разработки
pip install -e ".[yaml]"       # YAML-манифесты для strip/phase
pip install -e ".[languages]"  # Java, C#, Ruby, PHP — AST-fuzzy (ленивая загрузка)
pip install -e ".[trustchain]" # полный CLI tc (без него apatch всё равно bootstrap'ит .trustchain/)

Extra	Назначение
(core)	click, rich, tree-sitter: cpp, python, javascript, typescript, rust, go
dev	pytest, pytest-asyncio
yaml	pyyaml — манифесты strip / phase run и structure-aware match для *.yaml mappings
languages	tree-sitter-java, tree-sitter-c-sharp, tree-sitter-ruby, tree-sitter-php
trustchain	пакет trustchain + CLI tc (опционально; встроенный fallback есть)

Replay транскриптов IDE

Вторичный путь — когда нет governed SPEC. Для продуктового workflow начните с быстрого старта executable specs выше.

Типовой workflow (scan → plan → apply)

1. Найти транскрипты агентов на машине

apatch scan                     # авто-поиск .jsonl: Cursor / Claude / Gemini / текущая папка
apatch scan --path ./logs --json --no-count   # быстрее: без подсчёта кандидатов

Печатает таблицу свежих логов (mtime, источник, путь, число кандидатов). --limit N, --no-cwd, --path — доп. каталоги.

2. Просмотр кандидатов из лога

apatch view --logs transcript.jsonl
apatch view --logs transcript.jsonl --json --tool StrReplace

Список шагов: файл, действие, размеры old/new. Фильтры: --tool, --filter, --steps, --range.

3. Сухой прогон: как лягут правки (без записи)

apatch plan --logs transcript.jsonl --target-dir . --diff
apatch plan --logs transcript.jsonl --target-dir . --json

Для каждого кандидата: resolved_path, strategy, confidence (0..1), would_apply, warnings, опционально diff. Те же фильтры, что у view/apply. Для Elastic/OpenSearch mappings при drift по whitespace или порядку ключей strategy будет json-semantic (JSON и YAML).

4. Интерактивное применение правок (TUI с diff-просмотром)

apatch apply --logs transcript.jsonl --target-dir .

В процессе применения:

• [A] Apply — применить правку (в TUI видны strategy, confidence и предупреждения AST-fuzzy).
• [S] Skip — пропустить шаг.
• [E] Edit — открыть фрагмент в $EDITOR, скорректировать и применить.

5. Programmatic batch refactoring (JSONL как вход)

apatch apply принимает любой JSONL с полями TargetContent / ReplacementContent — не только транскрипты Cursor/Claude. Это полноценный транзакционный batch-движок для программируемых рефакторингов.

# Сгенерировать JSONL (скриптом или вручную)
python3 -c '
import json
p = {"step_index": 1, "tool_calls": [{"name": "replace_file_content", "arguments": {
    "TargetFile": "app/models.py",
    "TargetContent": "old_pattern",
    "ReplacementContent": "new_pattern",
    "AllowMultiple": True
}}]}
print(json.dumps(p))
' > patches.jsonl

apatch plan --logs patches.jsonl --target-dir . --diff
apatch apply --logs patches.jsonl --target-dir . --all -y \
  --verify "pytest" --verify-deferred --report report.json

• AllowMultiple: true в JSONL или CLI --all — замена каждого вхождения (token-rename / pattern replace).
• Альтернатива (replace по glob): apatch generate --find ... --replace ... --glob '**/*.py' --out patches.jsonl
• Новые файлы + правки + права файла: apatch generate-batch --needles needles.json --out patches.jsonl — action: create | replace | delete | rename | chmod (cookbook)

Готовые рецепты: docs/cookbook.md.

5b. Оркестрация изменений (архитектура, БД, impact)

apatch impact UserModel --json              # что затронет правка
apatch arch check --json                  # manifests/arch-rules.yaml
apatch db check --profile sqlalchemy --json # модели без миграции?
apatch db revision --profile sqlalchemy -m "msg" --dry-run
apatch db safety --profile sqlalchemy --json
apatch db run --manifest manifests/db-refactor.json --dry-run

apatch apply --logs patches.jsonl -y --budget medium   # лимит объёма правок (R49)
apatch refactor run --manifest manifests/refactor-bundle.example.json --dry-run
apatch verify semantic --json                         # routes/OpenAPI не исчезли
apatch pipeline run --manifest manifests/engineering-pipeline.example.json --dry-run
apatch index build && apatch index query UserModel
apatch trustchain history --query ADR-000
apatch init-consumer --with-arch-rules   # arch rules + pipeline template in manifests/

Оркестрация: docs/orchestration.md.

6. Автопилот с верификацией сборки/тестов

apatch apply --logs transcript.jsonl --target-dir . --yes --verify "pytest"

# Безопасный batch: применять только дрейфанувшие правки и только при высокой уверенности,
# с машинно-читаемым отчётом сессии
apatch apply --logs transcript.jsonl --target-dir . --yes \
  --only-drifted --min-confidence 0.85 --report apatch_report.json

Если на каком-то шаге тесты упадут, apatch мгновенно выполнит атомарный откат этого шага. --only-drifted пропускает точные совпадения (там помощь не нужна), --min-confidence не даёт автопилоту молча применять низкоуверенные fuzzy-совпадения, а --report пишет JSON с тем, что и какой стратегией применилось.

7. Восстановление исходного состояния

apatch rollback --target-dir .

Откатывает файлы на диске из .apatch/backups/ и (если активен TrustChain) сбрасывает HEAD к checkpoint последней strip/apply-сессии.

8. Разметка документации (compile)

apatch compile doc.md --out-dir ./extracted

Разбивает Markdown на логические блоки, инжектирует <!-- @sid:claim_N -->, генерирует knowledge_map.json.

9. Декомпозиция монолита (strip / phase run)

# Пакетное вырезание + конвертация в native_eval_*.cpp
apatch phase run \
  --manifest manifests/eval_visitor_strips_phase12.json \
  --file src/frontend/interpreter/eval_visitor.cpp \
  --native-out-dir src/frontend/interpreter \
  --out-dir extracted \
  --verify "cmake --build build --target olang_interpreter_core"

# STRICT: при blockers конвертера — exit 1 + откат исходника и артефактов
apatch strip --file eval_visitor.cpp --manifest manifests/phase.json \
  --native-out-dir interpreter/ --out-dir extracted --to-native auto --strict

Checkpoint apatch = тот же apatch_strip_<timestamp> в .apatch/backups/ + TrustChain ref + подпись SHA-256 файлов в ledger. Откат checkpoint всегда восстанавливает диск и HEAD.

Подробнее: docs/strip_guide.md.

Машинный вывод (--json) для агентов и CI

Команда	Формат
scan --json	[{path, source, mtime, modified, size, candidate_count}, ...]
view --json	[{step_index, tool_name, target_file, action_type, source_format, old_len, new_len, replace_all}, ...]
plan --json	[{step_index, resolved_path, strategy, confidence, would_apply, warnings, diff}, ...]
apply --report FILE	{target_dir, dry_run, checkpoint, applied, skipped, entries:[{outcome, strategy, confidence, warnings, ...}]}

Шкала confidence: exact/create/delete → 1.0; whitespace-fuzzy → 0.85; semantic-sid → 0.95; document-fuzzy → 0.7; ast-fuzzy → схожесть тел (или fallback 0.6–0.8); failed → 0.0.

Типовая цепочка для автономного агента:

apatch scan --json --limit 5 | jq '.[0].path' -r   # взять свежий лог
apatch plan --logs "$(…)" --target-dir . --json    # оценить риск
apatch apply --logs "$(…)" --target-dir . --yes \
  --only-drifted --min-confidence 0.85 --report /tmp/apatch_report.json

---

Лицензия

APatch Studio — один продукт с двумя планируемыми редакциями: APatch Studio OSS и APatch Studio Pro. Сейчас ни одна из них публично не выпущена: текущий репозиторий и runtime 0.8.36 остаются private/unreleased.

LICENSE и package metadata фиксируют выбранные MIT-условия для будущего публичного артефакта APatch Studio OSS, но сами по себе не являются публикацией. APatch Studio Pro будет распространяться на коммерческих условиях; Pro-only services, managed infrastructure and separately identified assets не получают MIT-лицензию автоматически.

Personal / Workspace extensions сохраняют выбранные их авторами условия из manifest; использование стабильного out-of-process контракта не передаёт APatch право собственности, публикации или обучения на их коде и данных. Core, MCP, CLI, Companion и remote broker являются компонентами APatch Studio, а не отдельными продуктами. Каноническая граница редакций зафиксирована в product matrix.

При будущем публичном релизе MIT будет относиться только к first-party software, явно включённому в release artifact APatch Studio OSS. Отдельно обозначенные внешние материалы, включая docs/ct_ckba_036_2017, не входят в Python wheel/sdist и не получают MIT-лицензию автоматически; их происхождение и право распространения должны быть оформлены до включения в публичный release artifact.

---

Тесты

Проект содержит 299+ интеграционных тестов, написанных без использования моков — все проверки работают с реальным синтаксическим деревом tree-sitter, файловой системой, Markdown CST-парсерами и живыми криптографическими цепочками.

pip install -e ".[dev]"
python -m pytest tests/

Тестовый модуль	Что проверяет
test_discovery.py	scan: поиск .jsonl, подсчёт кандидатов, --json, изолированный HOME (без сканирования реального ~/.cursor).
test_plan.py	plan --json: exact/fail, would_apply, отсутствие записи на диск.
test_filters.py	--only-drifted, --min-confidence, --report через TUI batch-режим.
test_ingestor.py	Парсинг логов Cursor/Gemini/Anthropic, unified-diff и apply_patch (V4A) envelope.
test_features.py	Пошаговые транзакции, автодетект CP1251 и CRLF, --verify / --verify-deferred, CREATE/DELETE.
test_matcher.py	Exact / whitespace-fuzzy / AST-fuzzy, дизамбигуация overload, MatchResult.evaluate, предупреждение о смене сигнатуры, Java (если установлен languages).
test_semantic.py	Markdown SID-якоря, semantic-sid, Jaccard document-fuzzy, compile CLI.
test_strip.py	Вырезание блоков, parent_imports, extraction_report.json, манифесты, native-конвертер.
test_strip_rollback.py	Транзакционный откат strip + TrustChain HEAD.
test_trustchain.py	Чекпоинты, signed коммиты, автоинициализация .trustchain/.
test_tui.py	TUI, ручное редактирование, path traversal.

---

Разработано Ed Cherednik, 2026.