Metadata-Version: 2.4
Name: apatch
Version: 0.8.42
Summary: Agent Patch & Trace Analyzer (apatch) - AST-Fuzzy matching & interactive agent patch reviewer
Author: Ed Cherednik
License-Expression: MIT
Keywords: ast,tree-sitter,patch,diff,llm,agent,refactor
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tree-sitter>=0.21.0
Requires-Dist: tree-sitter-cpp>=0.21.0
Requires-Dist: tree-sitter-python>=0.21.0
Requires-Dist: tree-sitter-javascript>=0.21.0
Requires-Dist: tree-sitter-typescript>=0.21.0
Requires-Dist: tree-sitter-rust>=0.21.0
Requires-Dist: tree-sitter-go>=0.21.0
Provides-Extra: trustchain
Requires-Dist: trustchain; extra == "trustchain"
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: languages
Requires-Dist: tree-sitter-java>=0.21.0; extra == "languages"
Requires-Dist: tree-sitter-c-sharp>=0.21.0; extra == "languages"
Requires-Dist: tree-sitter-ruby>=0.21.0; extra == "languages"
Requires-Dist: tree-sitter-php>=0.22.0; extra == "languages"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: wheel>=0.43; extra == "dev"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
Provides-Extra: platform
Requires-Dist: httpx>=0.27.0; extra == "platform"
Requires-Dist: cryptography>=42.0.0; extra == "platform"
Provides-Extra: mcp
Requires-Dist: mcp<2.0.0,>=1.0.0; extra == "mcp"
Dynamic: license-file

# 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](./docs/adr/ADR-001_Enterprise_Scale_Gaps.md). Опционально: `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](./docs/conformance.md).
* **Дифференциальный probe — `apatch probe` (RFP-005):** один примитив «возмути → пере-измерь → суди дельту против полярности», под который сведены три проверки качества гейта. `probe falsify` портит файлы, что охраняет требование, — verify **обязан** покраснеть (иначе это **ложный гейт**, не тестирующий охраняемое); `probe regress` — ни одного нового падения против записанного корпуса (baseline-aware); `probe ratify` — аттестованный гейт **всё ещё** зелёный (красный сейчас = протухшая аттестация). Универсально (`--verify` — любая shell-команда). См. [docs/probe.md](./docs/probe.md).
* **Реестр реальности — `apatch reality` (RFP-005):** инверсия источника истины — append-only леждер наблюдаемых фактов, которые проект обязан закрыть (`.apatch/reality.jsonl`); требования спеки их **дискорджат** (`## Rk … (discharges: REC-…)`). `apatch reality status` считает покрытие как «наблюдаемая реальность, закрытая зелёным гейтом», а `uncovered` — выводимый долг, не ручной ярлык. См. [docs/reality.md](./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](./docs/transparency-anchor.md).
* **Нормализация кодировок и переносов строк:** Автоматическое определение переносов строк (CRLF vs LF) и автодетект кодировок (UTF-8, CP1251, CP1252) при дисковых операциях с сохранением оригинальных параметров файлов.

---

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

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

> [!IMPORTANT]
> **TrustChain — это НЕ блокчейн.** У него нет распределенного консенсуса, майнеров, токенов или сети. Это локальный **подписанный хэш-чейн реестр (ledger)**, гарантирующий целостность и неизменяемость истории операций с помощью криптографии Ed25519.

### Встроенный 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](docs/RFP-020-three-views.md)):

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

```bash
# 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/RFP-020-three-views.md)).  
Плейбук агента: [docs/AGENTS.template.md](./docs/AGENTS.template.md) · индекс спек: [docs/specs/README.md](./docs/specs/README.md).

---

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

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

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

---

## Установка

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

### Установка в виртуальном окружении:
```bash
# Создать и активировать окружение
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](#быстрый-старт-executable-specs-10-м) выше.

### Типовой workflow (scan → plan → apply)
#### 1. Найти транскрипты агентов на машине
```bash
apatch scan                     # авто-поиск .jsonl: Cursor / Claude / Gemini / текущая папка
apatch scan --path ./logs --json --no-count   # быстрее: без подсчёта кандидатов
```
*Печатает таблицу свежих логов (mtime, источник, путь, число кандидатов). `--limit N`, `--no-cwd`, `--path` — доп. каталоги.*

#### 2. Просмотр кандидатов из лога
```bash
apatch view --logs transcript.jsonl
apatch view --logs transcript.jsonl --json --tool StrReplace
```
*Список шагов: файл, действие, размеры old/new. Фильтры: `--tool`, `--filter`, `--steps`, `--range`.*

#### 3. Сухой прогон: как лягут правки (без записи)
```bash
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-просмотром)
```bash
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-движок** для программируемых рефакторингов.

```bash
# Сгенерировать 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))

Готовые рецепты: **[docs/cookbook.md](./docs/cookbook.md)**.

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

```bash
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](./docs/orchestration.md)**.

#### 6. Автопилот с верификацией сборки/тестов
```bash
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 с тем, что и какой стратегией применилось.*

> [!WARNING]
> `--verify` и `--post-hook` выполняют переданную строку через **системный shell** (`shell=True`), а `[E] Edit` запускает `$EDITOR`. Запускайте только доверенные команды.
>
> **Verify gotchas:** сложный inline Python с кавычками или glob `**` часто ломается из-за shell-escaping — verify падает, apatch откатывает шаг, хотя патчи были корректны. Предпочитайте отдельный скрипт: `--verify "npm run build"`, `--verify "./scripts/check.sh"`, `--verify "pytest"`. При падении verify apatch печатает полный stdout/stderr.

#### 7. Восстановление исходного состояния
```bash
apatch rollback --target-dir .
```
Откатывает **файлы на диске** из `.apatch/backups/` и (если активен TrustChain) сбрасывает `HEAD` к checkpoint последней strip/apply-сессии.

#### 8. Разметка документации (`compile`)
```bash
apatch compile doc.md --out-dir ./extracted
```
*Разбивает Markdown на логические блоки, инжектирует `<!-- @sid:claim_N -->`, генерирует `knowledge_map.json`.*

#### 9. Декомпозиция монолита (`strip` / `phase run`)
```bash
# Пакетное вырезание + конвертация в 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.

> [!NOTE]
> Само вырезание блоков (`strip`) и генерация отчётов — общего назначения. А конвертер `--to-native` (модуль `apatch.native_converter`) **специфичен для рантайма O-Lang / Ed Organism** (он генерирует `register_native(...)` под `Interpreter::Value` и т.п.). Для других C++ кодовых баз используйте `strip` для извлечения, а интеграцию пишите под свой проект.

Подробнее: [docs/strip_guide.md](./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`.

Типовая цепочка для автономного агента:
```bash
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](./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](./docs/product-matrix.md).

При будущем публичном релизе 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-парсерами и живыми криптографическими цепочками.

```bash
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.*
