devcontour-harness 0.0.0-stage → 0.1.0-alpha.12

package/docs/compatibility.md

@@ -0,0 +1,192 @@
+# Совместимость форматов
+
+Harness выделен из DevContour. Первая миграция DevContour на пакет **не
+переносит данные**: состояние остаётся в прежнем хранилище, а адаптер
+отображает существующие записи в нейтральные структуры в той же транзакции.
+Ниже — как устроен адаптер, что сохраняется байт-в-байт и что меняется
+намеренно.
+
+## Транзакции адаптера DevContour
+
+DevContour хранит состояние одним JSON-документом в SQLite (`node:sqlite`) —
+в центральной базе или распределённо по базам компонентов, присоединённым к
+coordinator. `Store.change(type, fn)` открывает `BEGIN IMMEDIATE` (вложенный
+`Store.atomic` — SAVEPOINT), читает документ, вызывает `fn`, записывает
+документ целиком и вставляет событие журнала с `data` = возвращённым `fn`
+значением (кроме `heartbeat`).
+
+Адаптер `ExecutionStore`:
+
+1. **Внешняя транзакция** — `Store.atomic` с ровно одной `Store.change(kind, …)`
+   внутри. Документ, прочитанный ею, — текущий документ транзакции;
+   `ExecutionView` и `put*` читают и пишут его объекты (`Task`, `Run`, поля
+   управления), `putLocal` — `Store.saveLocal` той же транзакции.
+2. **Вложенная транзакция** не вызывает второй `Store.change`: она работает с
+   тем же документом внутри `Store.atomic` (SAVEPOINT для локальных записей).
+   Перед ней адаптер снимает копию документа и **всего журнального буфера**
+   (нейтральные события и legacy-данные); при исключении восстанавливает их на
+   месте. Изменения вложенной и внешней сохраняются обе — прямой вложенный
+   `Store.change` этого не обеспечивает: внешний снимок перезаписал бы
+   внутреннее изменение.
+3. **Журнал.** Возвращённое движком значение в журнал не идёт. Адаптер
+   записывает в `data` события прежнюю форму данных этого типа (для типов,
+   чьи данные читают хост и его экраны: `scheduler.error` → `{error}` и т. д.)
+   **без полей `token` на любой глубине** и добавляет ключ `harnessEvents` —
+   нейтральные события транзакции по порядку.
+4. **Событие без изменения документа.** `Store.change` не пишет событие, если
+   документ не изменился (транзакция только с `emit` или только с локальной
+   записью и `emit`). Для этого DevContour получает аддитивный метод
+   `Store.appendEvent(type, data)` — вставка события в открытой транзакции тем
+   же путём, что у `Store.change` (central: `main.events`; component:
+   `components.event`), с ростом ревизии данных. Адаптер вызывает его, когда
+   `Store.change` события не записал, а у транзакции есть нейтральные
+   события. Изменения остальных методов `Store` не требуется.
+   Транзакции только локальных записей (`workflow.updated`, `usage.recorded`,
+   `checks.recorded`) и `base.moved` (проверка владения и сдвиг ref)
+   событий не создают: адаптер выполняет их как `Store.atomic` без
+   `Store.change`, как DevContour сейчас пишет учёт вызовов и очередь ведущего.
+5. **Курсор.** `seq` нейтрального события = `id события журнала × 1024 + индекс` (не больше 1024 событий на транзакцию — с запасом для графа из 500 поручений; больше — отказ транзакции).
+   `ExecutionStore.events(after)` строит `RunEvent` из `harnessEvents` строго
+   по возрастанию `seq`; события прежних версий без `harnessEvents` в
+   нейтральный поток не попадают и читаются хостом как раньше.
+6. Возврат Promise из `fn` отклоняется до записи.
+7. `heartbeat` — `Store.change('heartbeat', …)`: растёт только счётчик сроков,
+   события нет.
+8. Приёмка: CAS `git update-ref <target> <integration> <base>` выполняется
+   внутри внешней транзакции до фиксации (как сейчас `finish(…, publish)`).
+
+Свойства подтверждены пробой поверх baseline `Store` (с эмуляцией
+`appendEvent`): вложенное и внешнее изменения сохраняются; исключение
+вложенной откатывает её документ, события и legacy-данные; исключение
+внешней не оставляет ни изменений, ни события; транзакция только с событием
+и транзакция «локальная запись + событие» фиксируются и откатываются целиком;
+токенов в журнале нет; курсор отдаёт события по возрастанию и каждое проходит
+схему `RunEvent`; Promise отклоняется; `putLocal` различает владельцев.
+
+### Локальные записи
+
+`local_workflow(namespace, owner, key, data)` — та же таблица. `owner` —
+репозиторий-компонент или `@workspace`. У хранения по компонентам запись
+владельца-компонента живёт в базе компонента (`componentN.local_workflow`),
+`@workspace` — в coordinator. Адаптер не меняет правило размещения и
+проверяет запись схемой пространства при чтении и записи.
+
+| Пространство harness                                   | `namespace` DevContour        | Запись                                                                                                                              |
+| ------------------------------------------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `usage`                                                | `usage`                       | `CallRecord` ↔ `UsageRecord`                                                                                                        |
+| `check-suites`                                         | `check-suites`                | `CheckSuite` (корпус: случаи, версии, решения, принятия, отложенные принятия, операции подтверждения под владением, CAS `revision`) |
+| `workflow-jobs`                                        | `lead`                        | `WorkflowJob` (техническая очередь ведущего: предмет, автор, digest входа, этап, попытки, ремонты, владение, история)               |
+| `context-snapshots`, `run-keys`, `delivery`, `reviews` | новые                         | Новые записи; прежних данных нет                                                                                                    |
+| `contract-documents`                                   | — (`contracts` состояния)     | Документ контракта по digest; адаптер отдаёт его из контрактов DevContour (`checks`, `artifacts`) и не пишет отдельно               |
+| `spikes`                                               | `spikes`                      | `Spike` (эксперимент выполнимости: SHA, команда, seed, размеры, предел, исходы, пределы вывода, среда, digest)                      |
+| `reproductions`                                        | — (`reproductions` состояния) | `ReproductionRegistry` поручения ↔ `Reproduction[]` с `taskId`; адаптер группирует по задаче и сохраняет ограничение 500            |
+
+Прочие пространства DevContour (`contract-change`, `signals`,
+`projection`) — продуктовые; движок их не читает и не пишет.
+
+## Отображение записей
+
+| Нейтральная запись       | Запись DevContour                                                                                               | Правило                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WorkState`              | `Task` (поля исполнения)                                                                                        | `status`, `attempt`, `activeRunId`, `resultSha`, `failure`, `failureKind`, `failureFingerprint`, `approvedAt`, `approvedDigest`, `approvedScope`, `approval`, `hold`, `budgetBlock`, `checkVersion`, `recovery`, `recoveryHistory` — те же имена и формы. `graphId` — доска, в активной ревизии которой задача                                                                                                                                                    |
+| `WorkOrder`              | `Task` (поля постановки)                                                                                        | `description` → `goal`; `writePaths` (или область роли) → `writeScope`; `contracts` + `contractDigests` → `contracts[{id, digest}]`; `contextPacks` → `context`; `source` = `{connector: 'devcontour', ref: <taskId>, revision: <approvedDigest>}`. Продуктовые поля (`preparation`, `featureId`, `assignee`, `supersedes`, `finding`, `sharedCompletion`, `scope`) в поручение не входят и остаются в `Task`                                                     |
+| `AttemptState`           | `Run`                                                                                                           | Те же имена и формы, включая `context` (краткие pins), `consumers[].checked`, `partial`, `continuedFrom`, `dispatch`, `timings`; `taskId` ↔ `workId`; runtime `demo` ↔ `fixture` на границе (сохранённое значение не переписывается); `memory` остаётся полем `Run` хоста; `engineVersion`, `consumerVersion`, `contextSnapshot` — новые необязательные поля                                                                                                      |
+| `EvidenceRecord`         | `Evidence`                                                                                                      | Без изменений; аддитивные необязательные `reviewRound` и `findings[].id/status` ([review-protocol.md](review-protocol.md)) хранятся как есть, прежние записи читаются без них; строгие переходы находок — только для адаптера reviewer с необязательным `RuntimeCapabilities.reviewProtocol: 1` (`cliAdapter`), runtime-обёртки хоста без поля сохраняют приёмку alpha.5                                                                                          |
+| `ControlState`           | `paused`, `pauseReason`, `pausedAt`, `pauseOperation`, `pauseFailures`, `waits`, `appliedConfig`, `reconfigure` | Те же формы; `appliedConfig` ↔ `appliedPolicy`                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `ControllerLease`        | `leader`                                                                                                        | Без изменений                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `JointVerificationState` | `Verification`                                                                                                  | `manifest`, `manifestDigest`, `policyDigest`, `specDigest`, `impact`, `evidence`, `token`, `leaseUntil`, `status` — те же формы; `tasks` → `workIds` (снимок задач остаётся в `Verification`); `boards`, `productRelease` — поля хоста                                                                                                                                                                                                                            |
+| `CallRecord`             | `UsageRecord` (`local_workflow` `usage`)                                                                        | Те же поля; `taskId` ↔ `workId`, `boardId` ↔ `groupId`, `taskIds` ↔ `workIds`                                                                                                                                                                                                                                                                                                                                                                                     |
+| `ReviewRecord`           | — (у DevContour раундов в форме `ReviewRecord` нет)                                                             | Прежние `contractAttempts` в раунды **не** превращаются: в них нет digest предмета и признака того же вендора, а выдумывать их нельзя. Согласование контракта DevContour — утверждённая редакция контракта (`contracts[]` с её `digest` и `approvedAt`); движок получает его через порт `ExecutionHost.contracts` (`approved({id, digest})`), а не по раундам `reviews`. История `contractAttempts` остаётся продуктовой записью и читается DevContour как прежде |
+
+Адаптер записывает только поля нейтральной модели и сохраняет остальные поля
+записи хоста как есть; неизвестные поля не удаляются.
+
+## Основания, которые не пересчитываются
+
+Формулы digest записаны в принятой истории и receipts. Движок их не вычисляет —
+их даёт хост через `BasisProvider`:
+
+- digest постановки задачи (включает продуктовые поля), digest области
+  проверок, digest контракта по своей формуле закрепления;
+- digest политики задачи, включая прежний вариант для старых receipts.
+
+Формулы действующей версии проверок, основания реализации, seed свойства,
+digest манифеста свойств и ключа ресурса переносятся в пакет без изменения.
+Pins контекста DevContour сохраняют свой digest (`hostDigest` → `ContextPin.digest`);
+`sourceDigest` снимка считается harness отдельно.
+
+Standalone-хост использует `digestOf` (SHA-256 канонического JSON) от
+нейтральных структур; эти digests с digests DevContour не сравниваются.
+
+## Бюджеты
+
+| Область harness | DevContour                  |
+| --------------- | --------------------------- |
+| `work`          | задача                      |
+| `group`         | доска со всеми её ревизиями |
+| `total`         | workspace                   |
+
+`BudgetScopes` DevContour: `groupOf` — доска задачи в текущем графе,
+`members` — задачи всех ревизий доски, `legacy` — прежнее правило атрибуции
+(задача по попытке или предмету вызова, доска по текущему графу) для записей
+без закреплённых `taskId`/`boardId`/`taskIds`; результат закрепляется один
+раз. Расход остаётся за доской, на которой он сделан, при переносе задачи.
+Тариф выбирается по модели, о которой сообщил runtime (`RuntimeResponse.model`
+→ `CallRecord.model`), а не по модели из политики.
+
+## Reviewer
+
+Автор плана и контракта задаётся вызовом ревью (`--author`; у DevContour —
+`authorRuntime` задания ведущего, закреплённый за входом: повтор с другим
+автором отклоняется). Автор вне harness — `external`; его вендор не совпадает
+ни с одним runtime.
+
+Правило ревью кода роли собирается адаптером по прежней цепочке
+`role.reviewer` компонента → `repository.reviewer` → `config.reviewer`;
+одноимённые роли разных компонентов не схлопываются (политика строится на
+компонент). Прежнее требование «writer ≠ reviewer» — `different-vendor`.
+
+## Сохраняемые форматы
+
+| Что                                     | Правило                                                                                                              |
+| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| Состояние `version: 1`                  | Читается как есть; иная версия отклоняется до записи                                                                 |
+| Типы событий журнала                    | Прежние строки, см. `transactionKinds`                                                                               |
+| Ветки                                   | Целевая `devcontour/accepted` (в политике `refs/heads/devcontour/accepted`), ветки попыток `devcontour/run-<runId>`  |
+| Каталоги попыток                        | `worktrees/<runId>`, `worktrees/<runId>-integration`, `artifacts/<runId>/…`, `dependencies/<runId>/manifest.json`    |
+| Receipt среды                           | `environment.json` `version: 1`                                                                                      |
+| Отчёт свойств, договор проверки, корпус | `version: 1`                                                                                                         |
+| Владение репозиторием                   | `<git-common-dir>/devcontour-owner.json`                                                                             |
+| Ресурсы                                 | Отдельная база блокировок ресурсов `resources.sqlite`: блокировки устройств и портов, а не состояние исполнения      |
+| Probe ревьюера                          | MCP-сервер `devcontour_probe`, инструмент `run_check`; протокол — построчный JSON-RPC (stdio), журнал `probes.jsonl` |
+
+## Переменные окружения gates
+
+Gates, шаги подготовки и проверки потребителей получают переменные с
+историческим префиксом `DEVCONTOUR_`: `DEVCONTOUR_REPOSITORY_ID`,
+`DEVCONTOUR_RUN_ID`, `DEVCONTOUR_TASK_ID`, `DEVCONTOUR_PHASE`,
+`DEVCONTOUR_RESOURCES_JSON`, `DEVCONTOUR_DEPENDENCIES_JSON`,
+`DEVCONTOUR_COMPONENTS_JSON`, `DEVCONTOUR_REPORT_PATH`, `DEVCONTOUR_SEED`,
+`DEVCONTOUR_PROPERTY_REPORT`, `DEVCONTOUR_PROPERTIES`, `DEVCONTOUR_CORPUS`,
+`DEVCONTOUR_CASE`, `DEVCONTOUR_CASE_RESULT`, `DEVCONTOUR_MANIFEST_PATH`,
+`DEVCONTOUR_CHANGESET_ID`, `DEVCONTOUR_PROCESS_MARK`. Имена — часть договора
+проверок пользователей, а не связь с хостом; harness сохраняет их и задаёт
+`HARNESS_*` с теми же значениями. Оба пространства резервирует controller:
+политика не может задать переменные с этими префиксами.
+
+## Что меняется намеренно
+
+| Изменение                       | Следствие                                                                                                                                                                                                                                                             |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Версия движка в основании reuse | Попытка записывает `engineVersion` (и `consumerVersion`). Кандидат попытки другой версии движка повторно не используется: новая попытка заново проходит gates и ревью. Прежние попытки сохраняют своё основание; отсутствующая версия не выдумывается                 |
+| Reviewer задаётся правилом      | `different-vendor` по умолчанию; `same-vendor-allowed` включается явно                                                                                                                                                                                                |
+| Токены вне журнала              | Исправление утечки: прежде `run.claimed` и `run.recovered` записывали в журнал попытку целиком, с fencing-токеном. Новые события пишутся без токенов; при выдаче старых событий наружу (CLI, HTTP, RunEvent) токены удаляются. Историю базы физически не переписываем |
+| История находок ревью           | Reviewer называет состояние прежних находок; прежние попытки читаются без статусов; ревью кода ведёт историю находок поручения с ID controller, находки записей alpha.5 получают детерминированный ID (review-protocol.md)                                            |
+
+## Состояние standalone
+
+Standalone SQLite хранит документ `execution-document` (`stateVersion: 1`),
+события и локальные записи в одной базе и запись о версии писателя. Процесс
+другой версии с несовместимым форматом не открывает базу на запись. Матрица
+поддерживаемых переходов и порядок upgrade/rollback — в
+[docs/upgrade.md](upgrade.md).

package/docs/connectors.md

@@ -0,0 +1,323 @@
+# Коннектор задач: Relay v1 и Relay-2
+
+Коннектор подключает к harness внешнее хранилище задач: читает задачу,
+закрепляет её постановку, исполняет её обычным путём (ревью плана →
+согласование → изолированная попытка → gates → независимое ревью → приёмка в
+Git) и доставляет подтверждённый результат обратно в задачу. Это opt-in
+модуль `devcontour-harness/integrations/connector`: корень пакета и
+`./contracts` его не импортируют, адаптер backend загружается только для
+явно выбранного provider.
+
+Поддерживаются два независимых транспорта:
+
+| provider        | Backend                                     | Транспорт                                                                                             |
+| --------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `relay-v1-http` | Relay v1 (`/api/v1`, project-scoped routes) | HTTP, `src/integrations/relay-v1`                                                                     |
+| `relay-v2-cli`  | Relay-2                                     | subprocess CLI (`--format json`, явные `--config`/`--project`/`--actor`), `src/integrations/relay-v2` |
+
+Provider выбирается **только явно** в конфигурации — никогда по имени
+бинарника `relay`. Базы v1 и v2 не взаимозаменяемы, миграции истории нет.
+
+## Пользовательский путь
+
+Все шаги — команды CLI; TypeScript писать не нужно.
+
+```sh
+# 1. Настроить: connector.json (см. «Конфигурация») и policy.json harness.
+
+# 2. Проверить подключение, проект, capabilities и mapping — только чтение:
+#    ни мутаций, ни записи истории, ни создания состояния.
+npx harness source-check --source connector.json --policy policy.json --state ../state
+
+# 3. Прочитать и закрепить снимок задач: graph.json, context.json, manifest.json.
+npx harness source-snapshot --source connector.json --policy policy.json --state ../state --out ../snapshot
+
+# 4. Обычное согласование (approvalMode: operator) — по файлам снимка.
+npx harness review-plan --state ../state --policy policy.json --source connector.json \
+  --graph ../snapshot/graph.json --context ../snapshot/context.json --author external
+npx harness approve --state ../state --subject <graphId> --digest <graphDigest>
+#    С --source внешние предпосылки (зависимости, выполненные через этот
+#    коннектор) допускаются по решению источника (trusts) и доступности SHA в
+#    target ref — те же правила, что у run; без --source доверенных receipt нет.
+#    В approvalMode: agent ревью плана выполняется в шаге 5 автоматически.
+
+# 5. Запуск: задачи перечитываются, semantic digest сверяется с закреплённым
+#    снимком, eligibility проверяется — всё до любого вызова runtime.
+#    Принятый результат доставляется в исходную задачу.
+npx harness run --source connector.json --policy policy.json --state ../state
+
+# 6. Локальный и внешний статус: принято / доставлено / конфликт / неизвестный
+#    исход и независимое чтение получателя.
+npx harness source-status --source connector.json --state ../state
+
+# 7. Повтор или продолжение доставки — с тем же ключом операции; writer,
+#    reviewer, gates и Git не вызываются.
+npx harness source-deliver --source connector.json --state ../state [--work <workId>]
+
+# 8. Разбор неизвестного исхода или конфликта (см. «Восстановление»).
+npx harness source-reconcile --source connector.json --state ../state \
+  --operation <key> [--decision resend|adopt:<id>|recheck]
+```
+
+`<graphId>`, `<graphDigest>`, ключи операций и ID поручений выводят
+`source-snapshot` и `source-status` (JSON в stdout). Exit codes как у всего
+CLI: 0 — успех, 2 — неверный вход, 3 — отказ/блокировка (в том числе
+`uncertain`/`conflict` доставки и непройденная проверка), 4 — инфраструктура
+(backend недоступен).
+
+## Конфигурация
+
+```json
+{
+  "version": 1,
+  "provider": "relay-v1-http",
+  "relay": { "endpoint": "http://127.0.0.1:4700" },
+  "projectId": "AbCd1234",
+  "actor": "harness-controller",
+  "repository": { "id": "app" },
+  "tasks": [
+    {
+      "ref": "PRODUCT-3",
+      "role": "developer",
+      "writeScope": ["apps/api/src", "packages/sdk/src"],
+      "gates": ["unit"],
+      "criteria": [
+        { "title": "API returns displayName", "gate": "unit", "testId": "api.user.displayName" },
+        { "id": "Ab3dE6gH", "gate": "typecheck", "evidence": "gate" }
+      ],
+      "requiredDocuments": ["Spec"]
+    }
+  ],
+  "completion": { "mode": "complete", "historicalComment": false },
+  "eligibility": { "columns": ["ready", "in-progress"] },
+  "limits": {
+    "documents": 20,
+    "documentBytes": 262144,
+    "totalBytes": 4194304,
+    "taskBytes": 1048576,
+    "rereads": 3,
+    "leaseMs": 120000
+  },
+  "history": { "enabled": true, "client": "devcontour-harness" }
+}
+```
+
+| Поле                  | Смысл                                                                                                                                                                                                                                                                                                           |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider`            | `relay-v1-http` или `relay-v2-cli`; только явно                                                                                                                                                                                                                                                                 |
+| `relay`               | Настройки адаптера. v1: `endpoint` (+ `timeoutMs`, `maxResponseBytes`). v2: `binary`, `config` (относительно файла конфигурации), `project?` (workspace), `env?` (например `RELAY_HOME`, на macOS `DYLD_LIBRARY_PATH`), `timeoutMs`, `maxOutputBytes`, `build?`. `projectId`/`actor` берутся из верхнего уровня |
+| `projectId`           | Ожидаемая идентичность проекта backend; несовпадение блокирует чтение снимка и любые мутации                                                                                                                                                                                                                    |
+| `actor`               | Автор всех записей коннектора                                                                                                                                                                                                                                                                                   |
+| `stateDir`            | Каталог состояния коннектора (относительно файла); без него — `--state`                                                                                                                                                                                                                                         |
+| `repository`          | ID репозитория политики (и путь для сверки)                                                                                                                                                                                                                                                                     |
+| `tasks[]`             | Задачи: `ref` (постоянный ID или ключ), роль, `writeScope`, `gates`, сопоставление критериев, обязательные документы                                                                                                                                                                                            |
+| `tasks[].criteria[]`  | Критерий (`id` или точный `title`) → `gate` и `testId` JUnit; `evidence: "gate"` — достаточно прошедшего gate (явный выбор)                                                                                                                                                                                     |
+| `completion`          | `complete` — закрыть по правилам backend (по умолчанию в `done`); `review-only` — перевести в `review`/`column` и оставить человеку; `historicalComment` — при конфликте постановки записать явно исторический комментарий                                                                                      |
+| `eligibility.columns` | Колонки, из которых задача допускается к запуску (`done`/`cancelled` — никогда)                                                                                                                                                                                                                                 |
+| `limits`              | Пределы документов и постановки, число повторных чтений, срок владения доставкой                                                                                                                                                                                                                                |
+| `history`             | Запись истории работы (корневая и дочерние сессии)                                                                                                                                                                                                                                                              |
+
+### Идентичность и снимок
+
+- Идентичность задачи — `<provider>:<projectId>:<постоянный ID>`; ID поручения
+  и графа — хэш от неё. Одинаковые номера задач разных проектов/backend не
+  совпадают; смена cwd на worktree идентичность не меняет.
+- `SourceRef.revision` — **semantic digest** постановки: текст, определения
+  критериев (без отметок выполнения), зависимости, подзадачи, значимые
+  документы и digest mapping. Колонка, свой in-progress, комментарии, история
+  и отметки критериев в него не входят. CAS-ревизии backend, токены
+  согласованности чтения и идентичность сборки хранятся только в manifest
+  снимка (никогда в поле Git SHA).
+- Чтение — раундами по всем задачам; снимок принимается, когда два раунда
+  подряд совпали токенами и содержимым. Изменения — не больше `rereads`
+  повторов, затем явный отказ `NOT_READY`; ошибка сети/CLI — отказ, а не
+  пустая доска.
+- Обязательное содержимое (текст постановки, критерии, `requiredDocuments`)
+  не усекается: превышение предела блокирует запуск с причиной и пределом.
+  Дополнительные документы усекаются с явной отметкой в начале файла и в
+  manifest (`truncated`) либо опускаются с записью в `missing` снимка.
+- Eligibility проверяется отдельно от digest: `done`/`cancelled`, колонка вне
+  `eligibility.columns`, незавершённая зависимость, зависимость в `done` без
+  receipt этого коннектора. Колонка, в которую задачу перевела наша
+  подтверждённая доставка той же постановки, повтор не блокирует.
+- Статус `done` зависимости — не доказательство: предпосылка зависимой
+  задачи появляется только из receipt доставки этого коннектора (издатель —
+  ID коннектора, digest сверяется с его состоянием), и движок дополнительно
+  проверяет доступность result SHA в target ref.
+
+## Доставка: протокол и гарантии
+
+Ключ операции — `sha256(provider, projectId, workId, runId, resultDigest)`.
+
+1. **Intent до вызова.** Операция записывается в состояние коннектора до
+   первого внешнего вызова. Не удалось записать — мутация не отправляется.
+2. **Сверка перед мутацией.** Задача перечитывается: изменился semantic
+   digest или задача отменена/закрыта другим — `conflict`; результат остаётся
+   привязан к своему снимку и SHA, текущая задача не закрывается (по
+   `historicalComment` — один явно исторический комментарий).
+3. **Шаги**, каждый записан до и после вызова: комментарий с маркером
+   `<!-- devcontour-harness:op=<key>:step=<n> -->`; отметки сопоставленных
+   критериев с CAS; перемещение с CAS; закрытие истории. Критерий отмечается
+   только по mapping на прошедший в integration gate/testcase принятого
+   результата; ручные критерии, непрошедший testcase, незавершённые
+   подзадачи и зависимости оставляют задачу незавершённой.
+   Перед **каждым** неподтверждённым шагом (в том числе при продолжении
+   после обрыва или перезапуска) задача перечитывается: постановка обязана
+   совпасть со снимком результата, задача — не быть отменённой или закрытой
+   другим, а для нового CAS-шага текущая ревизия — равняться ревизии,
+   записанной после **нашего** предыдущего шага. Иначе — `conflict`, и
+   изменённая задача старым результатом не закрывается.
+4. **Неизвестный исход** (таймаут, обрыв ответа, падение процесса между
+   вызовом и записью итога) разбирается фактами получателя: комментарий — по
+   маркеру (ровно один — подтверждено); CAS-шаг — по состоянию и ревизии
+   (цель достигнута, ревизия ровно на 1 больше нашей и постановка та же —
+   подтверждено; цель достигнута, но ревизия или постановка ушли дальше —
+   `conflict`; ревизия прежняя — не применено; ревизия
+   сменилась без нашей записи — `conflict`). Ответ `conflict` получателя
+   никогда не лечится повтором старой команды по новой ревизии.
+5. **Подтверждённый отказ ≠ неизвестный исход.** Структурный отказ
+   получателя (`refused`; `conflict` для записи без CAS — комментария;
+   `unavailable` до отправки) означает, что мутации не было: шаг остаётся
+   `planned`, доставка — `failed` с причиной «подтверждённый отказ
+   получателя», повтор `source-deliver` безопасен (тот же маркер). Класс
+   ответа задаёт адаптер: 5xx/ненулевой exit без доказательства отката для
+   мутации адаптер сообщает как `uncertain`, и тогда действует п. 6.
+6. **`uncertain`.** Если исход доказать нельзя (0 маркеров после возможной
+   отправки, больше одного, read-back недоступен), операция получает
+   `uncertain` (событие `delivery.uncertain` с ключом операции), повторная
+   доставка ничего не отправляет до `source-reconcile`.
+7. **Receipt.** После подтверждения всех шагов сохраняется receipt (ID
+   комментария, критерии, колонка, ревизия, сессии истории); для принятого
+   результата — доверенный receipt для зависимых задач.
+
+Повторная доставка принятого результата не вызывает writer/reviewer, не
+запускает gates и не меняет Git. Частично выполненная доставка продолжается
+с первого неподтверждённого шага без повтора append-only записей.
+
+### Один владелец доставки
+
+Владение операцией — lease с токеном, сроком и fencing в SQLite состояния
+коннектора (`BEGIN IMMEDIATE`). Живой владелец продлевает lease и во время
+долгого вызова; второй процесс над тем же каталогом получает
+`CONTROLLER_BUSY` и ничего не отправляет. Упавшего владельца можно
+перехватить только после истечения срока, intent при этом не теряется;
+каждая запись проверяет lease в той же транзакции, поэтому процесс,
+потерявший владение, больше ничего не записывает. Срок `limits.leaseMs`
+должен превышать таймаут одного вызова транспорта.
+
+**Граница гарантии:** она действует только для процессов, разделяющих один
+каталог состояния коннектора. Независимые установки с разными каталогами
+состояния вне гарантии и могут доставить одну операцию дважды —
+`source-check` и `source-status` показывают это в `ownership`. Distributed
+lock в этой версии не реализован.
+
+### Что гарантируется, а что нет
+
+Доказывается тестами (`tests/connector-*.test.ts`, общий набор
+`connectorSuite`):
+
+- одна подтверждённая доставка — один комментарий с маркером, без повторных
+  эффектов критериев и истории, в том числе после перезапуска процесса;
+- обрыв до отправки — безопасный повтор; запись получателем без ответа —
+  read-back без дубля; ответ без сохранённого receipt — без новых мутаций;
+  отказ записи intent — без мутации;
+- неизвестный исход не объявляется успехом и не повторяется автоматически;
+- старая постановка не закрывает новую; чужое изменение между сверкой и CAS —
+  конфликт без повтора;
+- два процесса не отправляют одну операцию одновременно.
+
+**Не гарантируется:** distributed exactly-once — у получателя нет
+идемпотентности по `requestId` (Relay v1 явно её не обещает, у Relay-2 её
+нет), а Git и Relay не образуют общей транзакции. Неоднозначные случаи
+решает оператор.
+
+### Восстановление (`source-reconcile`)
+
+Сначала проверяются факты получателя; решение оператора нужно только там,
+где факты неоднозначны.
+
+| Ситуация                                                                            | Что видно                                   | Действие                                                                                                 |
+| ----------------------------------------------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Запись прошла, ответ потерян                                                        | маркер найден ровно один                    | `source-reconcile --operation <key>` — подтверждение по факту, доставка продолжается                     |
+| Read-back был недоступен                                                            | `uncertain`, причина «read-back недоступен» | повторить `source-reconcile` после восстановления доступа                                                |
+| Таймаут, маркера нет                                                                | 0 маркеров                                  | проверить получателя; если записи нет — `--decision resend` (тот же маркер)                              |
+| Несколько записей с маркером                                                        | N > 1                                       | выбрать одну: `--decision adopt:<commentId>`; первая найденная не выбирается автоматически               |
+| CAS-конфликт без изменения постановки (например, сдвиг ранга соседней задачей в v1) | `conflict`                                  | `--decision recheck`: постановка перечитывается, при совпадении digest шаг продолжается от новой ревизии |
+| Постановка изменилась                                                               | `conflict`, `matchesSnapshot: false`        | результат остаётся историческим; новый `source-snapshot` → согласование → `run --source`                 |
+
+## История работы
+
+При включённой истории (`history.enabled`):
+
+- до исполнения попытки (до вызова writer) — корневая сессия поручения с
+  intent, затем fork дочерней сессии попытки, attach и её intent. Ошибка
+  записи intent — отказ окружения: попытка не начинается;
+- отказ попытки — отмена дочерней сессии; доставка результата — checkpoint с
+  SHA и сводкой gates, завершение и приём дочерней, завершение корня (или
+  отмена при непринятом результате);
+- каждая запись несёт маркер; после перезапуска controller шаги разбираются
+  read-back (`findSessions`, `checkpoints`, ревизия сессии) — без дублей;
+  записи прерванной попытки только подтверждаются фактами и отменяются;
+- ревизия сессии и run backend — fencing: если сессию перехватил другой
+  владелец, устаревший run её не завершает (`conflict`);
+- ID сессии/run backend, sessionId runtime и lease token попытки — разные
+  значения; lease token и полный runtime log в историю не пишутся.
+
+## В Relay уходит
+
+Краткий итог: исход, проверяемые SHA (candidate, integration/result), target
+ref, сводка gates (без журналов), таблица критериев → gate/testcase →
+результат, semantic digest и CAS-ревизия снимка. Локальные пути заменяются
+пометкой (они не ссылки для другого компьютера), значения секретов политики
+маскируются, полный runtime log и вызовы инструментов не копируются.
+
+## Маскирование секретов
+
+Ошибки транспорта (тело ответа HTTP, stderr CLI) маскируются до того, как
+попадут в отчёт `source-check`, `source-status`, ошибки снимка, причины
+шагов и операций в состоянии коннектора, `lastError` доставки, отказ записи
+истории и вывод CLI. Маскируются значения секретов политики на любом уровне
+(`environment.secrets` политики, репозиториев и tool profiles — по
+окружению controller; для `source-snapshot` укажите `--policy`, иначе
+используется политика каталога состояния) и значения настроек provider с
+именем вида `*TOKEN*`, `*SECRET*`, `*PASSWORD*`, `*KEY*`.
+
+## Состояние коннектора
+
+`<stateDir>/connectors/<provider>-<hash(projectId)>.sqlite` — отдельная от
+`state.sqlite` база: снимки (manifest и digest), операции доставки (intent,
+шаги, receipt), lease, связи с историей. Это не состояние исполнения: оно
+остаётся единственным — в `state.sqlite` harness.
+
+## Библиотека и договор адаптера
+
+```ts
+import { openConnector } from 'devcontour-harness/integrations/connector';
+
+const connector = await openConnector('connector.json', { stateDir: '../state' });
+const h = Harness.open({ stateDir: '../state', policy, baseDir, hooks: connector.hooks() });
+await connector.snapshot('../snapshot');
+await connector.run(h, { author: 'external' });
+await connector.status(h);
+```
+
+Модуль адаптера (`src/integrations/<adapter>/index.ts`) экспортирует
+`createTransport(settings, options?)` и возвращает `RelayTransport`
+(`src/integrations/connector/transport.ts`). `settings` — объект `relay`
+конфигурации, дополненный `projectId` и `actor` верхнего уровня; для
+`relay-v2-cli` пути `binary` и `config` уже абсолютные (разрешены от каталога
+файла конфигурации). Неверные настройки — `HarnessError('INVALID_INPUT')`.
+
+### Общий набор проверки адаптера
+
+`src/integrations/connector/testing.ts` содержит подделку backend
+(`FakeRelayTransport`, fixture), обёртку точек отказа `faultyTransport` для
+любого транспорта, барьеры (`LocalBarrier`, `FileBarrier`) и общий набор
+`connectorSuite(backend)` — W02–W05, D01–D06, R04. Backend набора
+(`SuiteBackend`) создаёт изолированный проект (`project()`), даёт транспорт,
+действия «другого участника» (`admin`) и способ воссоздать транспорт в новом
+процессе (`worker: { kind: 'config' }` — через `createTransportFor`).
+Crash/restart и гонки выполняются в отдельных процессах
+(`testing-worker.ts`) над тем же каталогом состояния. <!-- repo-only -->Набор на подделке —
+`tests/connector-suite.test.ts`; на настоящих Relay v1/Relay-2 —
+`tests/integration/*.test.ts` (репозиторий harness).<!-- /repo-only -->