devcontour-harness 0.1.0-alpha.31 → 0.1.0-alpha.34

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/README.md +22 -3
  2. package/docs/architecture.md +12 -0
  3. package/docs/compatibility.md +21 -18
  4. package/docs/contracts.md +135 -13
  5. package/docs/release-notes/0.1.0-alpha.32.md +33 -0
  6. package/docs/release-notes/0.1.0-alpha.33.md +29 -0
  7. package/docs/release-notes/0.1.0-alpha.34.md +32 -0
  8. package/docs/upgrade.md +137 -0
  9. package/lib/cli.js +2 -2
  10. package/lib/contracts/cli.d.ts +295 -5
  11. package/lib/contracts/events.d.ts +350 -4
  12. package/lib/contracts/events.js +63 -2
  13. package/lib/contracts/failure.d.ts +6 -1
  14. package/lib/contracts/failure.js +5 -1
  15. package/lib/contracts/handoff.d.ts +8 -0
  16. package/lib/contracts/handoff.js +17 -3
  17. package/lib/contracts/published.d.ts +177 -3
  18. package/lib/contracts/report.d.ts +116 -2
  19. package/lib/contracts/report.js +61 -3
  20. package/lib/control/base-move.d.ts +7 -2
  21. package/lib/control/base-move.js +14 -1
  22. package/lib/control/harness.d.ts +44 -8
  23. package/lib/control/harness.js +8 -96
  24. package/lib/control/status.d.ts +235 -0
  25. package/lib/control/status.js +101 -0
  26. package/lib/engine/budget.d.ts +78 -0
  27. package/lib/engine/budget.js +13 -2
  28. package/lib/engine/classify.d.ts +14 -1
  29. package/lib/engine/classify.js +34 -0
  30. package/lib/engine/engine.d.ts +17 -5
  31. package/lib/engine/engine.js +75 -5
  32. package/lib/engine/runner.js +4 -5
  33. package/lib/environment/isolation.d.ts +67 -3
  34. package/lib/environment/isolation.js +148 -5
  35. package/lib/environment/lifecycle.js +1 -1
  36. package/lib/explain/state.d.ts +25 -4
  37. package/lib/explain/state.js +29 -0
  38. package/lib/handoff/index.d.ts +1 -1
  39. package/lib/handoff/markdown.js +4 -2
  40. package/lib/handoff/pack.d.ts +38 -8
  41. package/lib/handoff/pack.js +57 -18
  42. package/lib/index.d.ts +18 -3
  43. package/lib/index.js +18 -2
  44. package/lib/integrations/connector/testing.js +1 -1
  45. package/lib/projections/next.d.ts +3 -1
  46. package/lib/projections/next.js +4 -1
  47. package/lib/projections/stop.d.ts +11 -0
  48. package/lib/projections/stop.js +44 -15
  49. package/lib/report/compute.js +228 -21
  50. package/lib/report/document.js +31 -7
  51. package/lib/verification/gates.js +20 -4
  52. package/package.json +1 -1
  53. package/schemas/handoff-pack.schema.json +6 -0
  54. package/schemas/run-event.schema.json +319 -0
  55. package/schemas/value-report.schema.json +235 -3
package/README.md CHANGED
@@ -5,7 +5,7 @@ Headless-движок исполнения инженерных поручени
5
5
  интеграция с принятой веткой через compare-and-swap и машинный результат с SHA
6
6
  и доказательствами.
7
7
 
8
- > Статус: `0.1.0-alpha.31` — предварительный выпуск (alpha). Договоры
8
+ > Статус: `0.1.0-alpha.34` — предварительный выпуск (alpha). Договоры
9
9
  > `v1alpha1` могут измениться между alpha-версиями; закрепляйте точную версию.
10
10
  > Файл → ревью плана → кандидат → интеграция → принятие → результат JSON, с
11
11
  > ограниченным восстановлением, повторным использованием кандидата, бюджетами,
@@ -28,7 +28,7 @@ Headless-движок исполнения инженерных поручени
28
28
  Из npm — точная версия (воспроизводимо) или последняя alpha по тегу:
29
29
 
30
30
  ```sh
31
- npm install --save-exact devcontour-harness@0.1.0-alpha.31 # точная версия
31
+ npm install --save-exact devcontour-harness@0.1.0-alpha.34 # точная версия
32
32
  # или: npm install --save-exact devcontour-harness@alpha # текущая alpha
33
33
  npx harness --version
34
34
  ```
@@ -129,7 +129,8 @@ codes: 0 успех, 2 неверный вход, 3 отказ/блокиров
129
129
  каталог в отчёт не попадают; `--no-titles` убирает и заголовки. Тот же
130
130
  каталог — те же байты: момент отчёта — последняя метка времени в данных.
131
131
  Хост строит тот же отчёт из своего хранилища: `valueReport` из
132
- `devcontour-harness/report`. Подробно — [ValueReport](docs/contracts.md#valuereport).
132
+ `devcontour-harness/report`, файл отчёта — `writeReportFile` из корня пакета.
133
+ Подробно — [ValueReport](docs/contracts.md#valuereport).
133
134
 
134
135
  ## Библиотека
135
136
 
@@ -147,6 +148,24 @@ PASS» нет. Адаптеры хоста реализуют порты `Execut
147
148
  `devcontour-harness/schemas/<имя>.schema.json`. Декларации используют типы
148
149
  Node.js: TypeScript-потребителю нужен `@types/node` (или `skipLibCheck`).
149
150
 
151
+ ## Выпуск 0.1.0-alpha.34
152
+
153
+ События повторов, отмен, сдвигов базы и причин отказа среды; отчёт об
154
+ эффекте различает ручные и автоматические действия. Подробно —
155
+ [заметки выпуска](docs/release-notes/0.1.0-alpha.34.md).
156
+
157
+ ## Выпуск 0.1.0-alpha.33
158
+
159
+ Пакет передачи и `explain` без ложных решений по отменённым работам и без
160
+ повтора расхода ревью плана у каждого поручения. Подробно —
161
+ [заметки выпуска](docs/release-notes/0.1.0-alpha.33.md).
162
+
163
+ ## Выпуск 0.1.0-alpha.32
164
+
165
+ Пакет передачи контекста для хоста без экземпляра `Harness` и под его предел
166
+ ответа, экспорт `policySecrets` и `writeReportFile`, песочница при глубоком
167
+ TMPDIR. Подробно — [заметки выпуска](docs/release-notes/0.1.0-alpha.32.md).
168
+
150
169
  ## Выпуск 0.1.0-alpha.31
151
170
 
152
171
  Controller сам замечает зависшие попытки и проверки (`stallSweep`, отказ
@@ -648,6 +648,18 @@ executable. Live smoke — отдельный opt-in с явно заданны
648
648
  вложенные `.git` на любой глубине тоже закрыты (на Linux — только
649
649
  существующий файл `.git`). Дерево больше предела перечисления — отказ
650
650
  проверки классом `environment`, а не молча урезанные запреты.
651
+ Свои unix-сокеты srt создаёт во временном каталоге своего процесса, а путь
652
+ сокета ограничен (`sun_path`: 104 байта на macOS, 108 на Linux). Если путь
653
+ в TMPDIR процесса не укладывается, srt получает свой каталог под `/tmp`
654
+ (`dc-srt-<pid>-*`, `mkdtemp`, `0700`), который удаляется после проверки;
655
+ каталоги, брошенные упавшим controller (свои, ни каталог, ни записи прямо
656
+ в нём не менялись дольше суток, процесс создателя завершён), убираются при
657
+ создании нового — через переименование в `.dc-srt-rm-*` и повторную
658
+ проверку. Свежая запись внутри держит каталог: srt переживает controller,
659
+ убитый SIGKILL, а контейнер с общим `/tmp` не видит создателя из другого
660
+ пространства pid. Команде внутри
661
+ по-прежнему передаётся её scratch. Не создаётся и этот каталог — отказ
662
+ проверки классом `environment` с TMPDIR в тексте до запуска команды.
651
663
  - **Сверка защищённых путей.** Запреты песочницы проверяют только путь
652
664
  операции: каталог, собранный в `node_modules` и перенесённый в дерево
653
665
  проекта, ими не закрыт. До и после каждого gate и вокруг работы исполнителя
@@ -42,9 +42,11 @@ coordinator. `Store.change(type, fn)` открывает `BEGIN IMMEDIATE` (вл
42
42
  `Store.change` события не записал, а у транзакции есть нейтральные
43
43
  события. Изменения остальных методов `Store` не требуется.
44
44
  Транзакции только локальных записей (`workflow.updated`, `usage.recorded`,
45
- `checks.recorded`) и `base.moved` (проверка владения и сдвиг ref)
46
- событий не создают: адаптер выполняет их как `Store.atomic` без
47
- `Store.change`, как DevContour сейчас пишет учёт вызовов и очередь ведущего.
45
+ `checks.recorded`) событий не создают: адаптер выполняет их как
46
+ `Store.atomic` без `Store.change`, как DevContour сейчас пишет учёт вызовов
47
+ и очередь ведущего. `base.moved` (проверка владения и сдвиг ref) записей не
48
+ меняет, но пишет событие `base.moved`: адаптер добавляет его
49
+ `Store.appendEvent`, как любое нейтральное событие без изменения документа.
48
50
  5. **Курсор.** `seq` нейтрального события = `id события журнала × 1024 + индекс` (не больше 1024 событий на транзакцию — с запасом для графа из 500 поручений; больше — отказ транзакции).
49
51
  `ExecutionStore.events(after)` строит `RunEvent` из `harnessEvents` строго
50
52
  по возрастанию `seq`; события прежних версий без `harnessEvents` в
@@ -148,21 +150,22 @@ Standalone-хост использует `digestOf` (SHA-256 каноничес
148
150
 
149
151
  ## Сохраняемые форматы
150
152
 
151
- | Что | Правило |
152
- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
153
- | Состояние `version: 1` | Читается как есть; иная версия отклоняется до записи |
154
- | Типы событий журнала | Прежние строки, см. `transactionKinds` |
155
- | События стадий | Тип `attempt.stage` (не выпущено): границы стадий попытки: `started` и не больше одного `finished` на замер `AttemptState.timings` (стадия утратившей владение попытки остаётся открытой); документ состояния и digest политики прежние. Тип, которого читатель не знает, читается как `{type: 'unknown', original}` без нагрузки. Версии до этой событие разбирают строго: после отката ниже неё `events` отказывает на странице с ним (upgrade.md) |
156
- | Ветки | Целевая `devcontour/accepted` (в политике `refs/heads/devcontour/accepted`), ветки попыток `devcontour/run-<runId>` |
157
- | Каталоги попыток | `worktrees/<runId>`, `worktrees/<runId>-integration`, `artifacts/<runId>/…`, `dependencies/<runId>/manifest.json`; при каталоге состояния внутри репозитория деревья и снимки — под корнем вне дерева `<checkoutRoot>/<repositoryId>/…` (alpha.23) |
158
- | Receipt среды | `environment.json` `version: 1` |
159
- | Отчёт свойств, договор проверки, корпус | `version: 1` |
160
- | Хранилище зависимостей | Необязательное `repositories[].dependencyStore`: без поля политика, её digest и каталоги прежние. Каталог `dependency-store` закрыт профилю codex для всех установок, как и другие служебные каталоги; seed другого формата не используется ни как попадание, ни как основа сборки: он пересобирается и вытесняется |
161
- | Artifacts gates | Необязательное `repositories[].gates[].artifacts`: без поля политика и её digest прежние. Поле `artifactFiles` в evidence gate и в записи совместной проверки необязательно: прежние записи читаются как есть |
162
- | Владение репозиторием | `<git-common-dir>/devcontour-owner.json` |
163
- | Ресурсы | Отдельная база блокировок ресурсов `resources.sqlite`: блокировки устройств и портов, а не состояние исполнения. Таблица `seed_pins` создаётся только при первом обращении хранилища зависимостей |
164
- | Снимок коннектора | Поля `proof` и `baseline` manifest необязательны: прежние записи читаются как есть. Без `baseline` в конфигурации ревизия, graph digest и context digest те же, что в прежних версиях |
165
- | Probe ревьюера | MCP-сервер `devcontour_probe`, инструмент `run_check`; протокол — построчный JSON-RPC (stdio), журнал `probes.jsonl` |
153
+ | Что | Правило |
154
+ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
155
+ | Состояние `version: 1` | Читается как есть; иная версия отклоняется до записи |
156
+ | Типы событий журнала | Прежние строки, см. `transactionKinds` |
157
+ | События стадий | Тип `attempt.stage` (не выпущено): границы стадий попытки: `started` и не больше одного `finished` на замер `AttemptState.timings` (стадия утратившей владение попытки остаётся открытой); документ состояния и digest политики прежние. Тип, которого читатель не знает, читается как `{type: 'unknown', original}` без нагрузки. Версии до этой событие разбирают строго: после отката ниже неё `events` отказывает на странице с ним (upgrade.md) |
158
+ | События вмешательств и причин отказа | Типы `work.retried`, `work.cancelled`, `base.moved`, `attempt.diagnosed` (не выпущено): актёр повтора, отмены и сдвига базы, причина отказа окружения; пишутся в транзакции изменения. Документ состояния и digest политики прежние. Версии с терпимым чтением (alpha.30 и новее) читают их как `{type: 'unknown', original}`; ниже — `events` отказывает на странице с ними (upgrade.md). Перечни `cause` и `by` строгие: новое значение в будущей версии — изменение договора, и эта версия отклонит такое событие при чтении (известный тип с нарушенной нагрузкой), поэтому новое значение добавляется только вместе с новым типом события или с изменением правила чтения |
159
+ | Ветки | Целевая `devcontour/accepted` (в политике `refs/heads/devcontour/accepted`), ветки попыток `devcontour/run-<runId>` |
160
+ | Каталоги попыток | `worktrees/<runId>`, `worktrees/<runId>-integration`, `artifacts/<runId>/…`, `dependencies/<runId>/manifest.json`; при каталоге состояния внутри репозитория деревья и снимки — под корнем вне дерева `<checkoutRoot>/<repositoryId>/…` (alpha.23) |
161
+ | Receipt среды | `environment.json` `version: 1` |
162
+ | Отчёт свойств, договор проверки, корпус | `version: 1` |
163
+ | Хранилище зависимостей | Необязательное `repositories[].dependencyStore`: без поля политика, её digest и каталоги прежние. Каталог `dependency-store` закрыт профилю codex для всех установок, как и другие служебные каталоги; seed другого формата не используется ни как попадание, ни как основа сборки: он пересобирается и вытесняется |
164
+ | Artifacts gates | Необязательное `repositories[].gates[].artifacts`: без поля политика и её digest прежние. Поле `artifactFiles` в evidence gate и в записи совместной проверки необязательно: прежние записи читаются как есть |
165
+ | Владение репозиторием | `<git-common-dir>/devcontour-owner.json` |
166
+ | Ресурсы | Отдельная база блокировок ресурсов `resources.sqlite`: блокировки устройств и портов, а не состояние исполнения. Таблица `seed_pins` создаётся только при первом обращении хранилища зависимостей |
167
+ | Снимок коннектора | Поля `proof` и `baseline` manifest необязательны: прежние записи читаются как есть. Без `baseline` в конфигурации ревизия, graph digest и context digest те же, что в прежних версиях |
168
+ | Probe ревьюера | MCP-сервер `devcontour_probe`, инструмент `run_check`; протокол — построчный JSON-RPC (stdio), журнал `probes.jsonl` |
166
169
 
167
170
  ## Переменные окружения gates
168
171
 
package/docs/contracts.md CHANGED
@@ -687,6 +687,46 @@ fencing; само состояние между переходами не пер
687
687
  'stop'|'report', snapshot?}`; `joint.liveness` — то же с `verificationId`; `action` и `snapshot` — только у `stalled` (см. «Зависшие
688
688
  попытки»).
689
689
 
690
+ `work.retried` — поручение возвращено в очередь `engine.retry`: `{by:
691
+ 'operator'|'recovery'|'host', reset, spent?, reasonLength?}`. `by` — третий
692
+ аргумент `retry(workId, reset?, by?)`: CLI `retry` передаёт `operator`,
693
+ восстановление очереди (`repair`, эпизод по свойству) — `recovery`, хост без
694
+ актёра — `host` (по умолчанию). `reset` — сброс исчерпанного предела; `spent` —
695
+ засчитанные попытки до сброса (сброс обнуляет `WorkState.attempt`),
696
+ `reasonLength` — длина причины сброса; текста причины в событии нет. Повтор
697
+ без изменения (поручение уже в очереди) и отказ повтора событий не создают.
698
+
699
+ `work.cancelled` — поручение отменено: `{by: 'operator'|'host'|'graph',
700
+ hadAttempt}`. `engine.cancel(workId, reason?, by?)` (CLI `cancel` — `operator`,
701
+ по умолчанию `host`); `graph` — новая редакция графа убрала поручение.
702
+ `hadAttempt` — отменена и активная попытка: её `attempt.cancelled` идёт в той
703
+ же транзакции перед `work.cancelled`, у которого тогда те же `runId` и
704
+ `attempt`. Повторная отмена отменённого событий не создаёт.
705
+
706
+ `base.moved` — сдвиг ref базы `fencedRefMove(store, fence, timeoutMs?, by?)`:
707
+ `{by: 'operator'|'controller'|'host'}` (по умолчанию `host`), одно событие на
708
+ репозиторий, в той же транзакции, что проверка владения и `git update-ref`.
709
+ Отказ проверки или Git (CAS) отменяет и событие. `moveBase` без `move` событий
710
+ не пишет: у него нет хранилища.
711
+
712
+ `attempt.diagnosed` — причина отказа попытки: `{failureKind, cause, counted}`,
713
+ конверт несёт `graphId`, `workId`, `runId`, `attempt`. Пишется сразу за
714
+ `attempt.failed` (и `attempt.expired`) в той же транзакции под fencing.
715
+ `cause` (`environmentCauses`): `sandbox-launch`, `sandbox-network`,
716
+ `sandbox-filesystem`, `sandbox-policy`, `dependency-network` — ставит gate в
717
+ точке обнаружения (`TaskFailure.diagnosis`); `transport`, `preflight`
718
+ (`BlockedError` до работы), `provider-auth`, `provider-limit`, `stalled`,
719
+ `shutdown` (прерывание штатной остановкой), `lease-expired` — по классу отказа
720
+ и его признакам; `other` — отказ окружения без известной причины; `none` —
721
+ отказ не окружения. Хост, вызывающий `engine.fail`, может передать
722
+ `options.cause`; движок приводит её к классу (у отказа не окружения — всегда
723
+ `none`). `counted` — отказ засчитан в предел попыток (`maxAttempts`): не
724
+ засчитаны отказы до работы (`blocked`), окружения и провайдера, истёкшее
725
+ владение и прерывание остановкой; зависание (`stalled`) засчитано. Отчёт
726
+ считает попытки засчитанными по тому же правилу. Отказ до работы с классом
727
+ не окружения получает причину `preflight`. Текста отказа в событии
728
+ нет.
729
+
690
730
  `finished` может не прийти: поздний finish владельца, утратившего срок,
691
731
  отклоняется (runner его не повторяет), упавший процесс его не пишет, а `adopt`
692
732
  и recovery открытые замеры прежнего владельца не закрывают. Такая стадия
@@ -726,7 +766,7 @@ original}` (исходный тип, не длиннее 200 символов;
726
766
  (`joint.started`, `joint.finished`). `config.started`, `config.reconfigure-*`
727
767
  и `config.reconfigured` меняют применённую политику и запрос операции
728
768
  (`policy.applied`, `policy.reconfigure`). `base.moved` — проверка владения
729
- операцией и CAS-сдвиг ref базы; записей и событий не создаёт.
769
+ операцией и CAS-сдвиг ref базы; записей не создаёт, событие — `base.moved`.
730
770
 
731
771
  ### ValueReport
732
772
 
@@ -749,7 +789,14 @@ original}` (исходный тип, не длиннее 200 символов;
749
789
  внешних ссылок (CSP `default-src 'none'; style-src 'unsafe-inline'; img-src
750
790
  data:`), светлая и тёмная схема по `prefers-color-scheme`, таблицы
751
791
  прокручиваются на ширине телефона, столбики недель (inline SVG) — от 3
752
- активных недель. Модуль `devcontour-harness/report` без `node:*` и без zod.
792
+ активных недель. Модуль `devcontour-harness/report` без `node:*` и без zod. Запись
793
+ файла отчёта (`report --out`) — `writeReportFile(out, stateDir, text)` из
794
+ корня пакета (не из `./report`: она использует `node:fs`): текст пишется во
795
+ временный файл каталога цели и переименовывается поверх цели, без записи
796
+ сквозь symlink и жёсткие ссылки; цель внутри каталога состояния, symlink,
797
+ не обычный файл или файл с `nlink > 1` — `PATH_CONFLICT`, недоступный
798
+ каталог — `INVALID_INPUT`; права прежнего файла сохраняются, новый —
799
+ `REPORT_FILE_MODE` (`0600`).
753
800
 
754
801
  **Детерминизм.** Тот же вход и параметры — те же байты JSON, Markdown и HTML
755
802
  при любом порядке входных массивов, часах и часовом поясе. `asOf` по
@@ -803,15 +850,48 @@ lower`). `firstPassRaw` — попытка вообще одна.
803
850
  иначе `lower` («≥»); без единой известной цены при неизвестных —
804
851
  `unknown` (`value: null`), не `$0`. Расход отклонённых попыток
805
852
  (`cost.rejected`) и расход отказов окружения (`environment.neutral`) —
806
- одна и та же атрибуция по всем завершённым попыткам окна.
853
+ одна и та же атрибуция по всем завершённым попыткам окна. `environment.neutral`
854
+ — вся корзина `environment`, включая зависания (`stalled`), хотя они
855
+ засчитаны в предел попыток.
856
+ - Пробел записи определяется по порядку журнала (`seq`), а не по времени:
857
+ `at` события — часы записи, время попытки — часы движка.
807
858
  - Действия человека — только записи с актёром-человеком: решения recovery
808
- с источником `operator`. Удержания (`work.held`) и отмены попыток актёра
809
- не называют (удерживают и операции хоста, например смена контракта): они
810
- показаны отдельно (`holds`, `cancelledAttempts`) и в действия человека не
811
- входят. Повторы, сбросы, отмена без попытки и сдвиг базы пока не
812
- записываются: `withAction` — нижняя граница, «без действий человека»
813
- (`withoutAction`) пока не измеримо (`value: null`, `bound: unknown`),
814
- `retries`/`resets`/`baseMoves` — `null`.
859
+ с источником `operator`, повторы и отмены с `by: operator` (`work.retried`,
860
+ `work.cancelled`). Удержания (`work.held`) актёра не называют (удерживают и
861
+ операции хоста, например смена контракта): они показаны отдельно (`holds`)
862
+ и в действия человека не входят; так же `cancelledAttempts` — отменённые
863
+ попытки по записям попыток. Повторы восстановлением (`recovery`), сдвиги
864
+ базы controller и отмены новой редакцией графа — автоматические.
865
+ - Вмешательства по событиям (`actions.recorded`): числа в окне по актёрам —
866
+ повторы, сбросы, отмены (и отмены без активной попытки), сдвиги базы.
867
+ Запись начинается с первого события версии, которая их пишет
868
+ (`work.retried`, `work.cancelled`, `base.moved`, `attempt.diagnosed`;
869
+ `recorded.from`); раньше него действие могло быть, но не записано. Нет ни
870
+ одного такого события в журнале — `recorded: null`, `withAction` — нижняя
871
+ граница, «без действий человека» (`withoutAction`) не измеримо (`value:
872
+ null`, `bound: unknown`). С записью: `recorded.bound: lower`, если в окне
873
+ есть попытки, события или принятые поручения раньше `from` или пробел записи
874
+ (`gaps`: новая попытка после отказа или отмены без `work.retried` и без новой
875
+ редакции графа между ними — работала версия без этих событий, например
876
+ после отката и повторного обновления), иначе `exact`. Пробел, не оставивший
877
+ такой попытки, не обнаруживается — это постоянное ограничение. Суммы
878
+ `retries`/`resets` — только при `bound: exact`, иначе `null` (числа по
879
+ актёрам с границей — в `recorded`). Сдвиги базы — всегда нижняя граница
880
+ (`baseMovesBound: lower`, сумма `baseMoves` всегда `null`): перенос вне
881
+ `fencedRefMove` (`moveBase` без `move`) не пишется; к поручениям они не
882
+ относятся.
883
+ - Поручение «без действий человека» известно, если оно начато не раньше
884
+ `from` (начало — согласование первой попытки `wait.approvedAt`, иначе
885
+ `WorkState.approvedAt`, иначе начало первой попытки), без пробела записи,
886
+ и у него нет действий без актёра: повтора или отмены хостом (`host`) и
887
+ удержания (`work.held` — его ставят и человек, и операции хоста). Прочие
888
+ принятые без действия оператора идут в `unknown` обеих мер (`bound:
889
+ lower`).
890
+ - Подпричины окружения (`environment.causes`): отказы окружения окна по
891
+ `attempt.diagnosed` своей попытки — строки `{cause, count, counted}` (по
892
+ убыванию числа); отказ без события (записан раньше) — `undiagnosed`, тогда
893
+ `bound: lower`. Нет ни одного `attempt.diagnosed` в журнале — `causes:
894
+ null`.
815
895
  - Отказы окружения (`environment.share`) — среди классифицированных; если
816
896
  есть отказы только в gates подготовки (`setupCheckFailures`), доля —
817
897
  нижняя граница («at least», «M more may be environment»).
@@ -844,7 +924,7 @@ HTML ≤ 1 МБ. Усечение отмечено флагом и ограни
844
924
 
845
925
  ### HandoffPack
846
926
 
847
- Пакет передачи контекста (`harness handoff`, `handoffPack(harness, options)`
927
+ Пакет передачи контекста (`harness handoff`, `handoffPack(source, options)`
848
928
  и `handoffMarkdown(pack)` из корня пакета; `handoffVersion: 1`,
849
929
  `handoffPackSchema`, `schemas/handoff-pack.schema.json`). Ведущий агент хоста,
850
930
  который ведёт доску через много попыток, начинает новую сессию с пакета, а не
@@ -866,6 +946,16 @@ HTML ≤ 1 МБ. Усечение отмечено флагом и ограни
866
946
  `next` — кто и что делает (по диагнозу `explain`; стадия и свойство — по
867
947
  `nextAction`);
868
948
  - `stops` — диагнозы `explain` без проб runtime, кроме `action: none`.
949
+ Отменённая работа (и упавшая с классом `cancelled`) — остановка
950
+ (`CANCELLED`, lead `replan-dependents`), только пока от неё прямо зависит
951
+ незавершённая работа (не `done` и не `cancelled`); ждущую через
952
+ отменённую же промежуточную ведёт диагноз той. Без таких работ у
953
+ отменённой действия нет (`action: none`): в общий `explain` и пакет она не
954
+ входит, explain этой работы (`--work`) её показывает. Упавшая отменой
955
+ открыта, а движок её не повторяет: без ждущих — решение человека (user
956
+ `user-decision`: `harness retry` или отмена), шаг `nextAction` —
957
+ `cancelled`. Любая отмена в группе останавливает её автоматическое
958
+ восстановление: диагноз упавшей сестры называет отменённую работу.
869
959
  Остановка выдачи общей паузой очереди — одна запись с `queue: true` без
870
960
  `workId`; одинаковые остановки на выдаче у разных поручений тоже
871
961
  свёрнуты; `works` — первые 20 затронутых, `worksCount` — сколько всего.
@@ -874,7 +964,14 @@ HTML ≤ 1 МБ. Усечение отмечено флагом и ограни
874
964
  `failureKind`, код (`stopCodeOf`), текст ошибки и текущий статус
875
965
  поручения (`workStatus`);
876
966
  - `budgets` — общий бюджет и бюджеты групп (с `--graph` — только его
877
- группа), бюджеты поручений — только с расходом или не в пределах:
967
+ группа), бюджеты поручений — только с расходом или не в пределах и со
968
+ своими вызовами (попытки, вызовы о поручении). Вызов о группе (ревью и
969
+ проверка плана) засчитывается целиком бюджету каждого её открытого
970
+ поручения (так действует ограничение поручения), но в строках группы и
971
+ `total` — один раз; поручение, весь расход которого — такие вызовы, не
972
+ перечисляется (`truncated.budgetsShared`), если только его строка не
973
+ держит выдачу (превышена или не определена при `onUnknown: stop`): тогда
974
+ она показана как ограничение поручения. Строка бюджета:
878
975
  сообщено (`reportedUsd`) и оценено (`estimatedUsd`) против предела, время,
879
976
  `complete` и причины неполноты (вызовы без стоимости, незавершённые,
880
977
  брошенные, попытки без учёта); при неполном расходе сумма — нижняя граница
@@ -900,13 +997,38 @@ escape-последовательностей терминала (ANSI CSI, OSC)
900
997
  остановки, строки бюджетов» (`truncated.bySize`), отказа по размеру нет.
901
998
  Сколько записей каждого списка не вошло — `truncated`; бюджеты поручений в
902
999
  пределах и без расхода не показываются намеренно и считаются отдельно
903
- (`budgetsWithin`), усечённые и отброшенные намерения — `intentions` и
1000
+ (`budgetsWithin`), как и бюджеты поручений только с расходом вызовов о
1001
+ группе (`budgetsShared`), усечённые и отброшенные намерения — `intentions` и
904
1002
  `intentionsDropped`. Тексты из хранилища маскируются по значениям секретов
905
1003
  политики из окружения читающего процесса (`policySecrets`, как у
906
1004
  коннектора): секрет, которого в этом окружении нет, маска не знает —
907
1005
  библиотеке можно передать свою `redact`. Fencing-токены в пакет не
908
1006
  попадают.
909
1007
 
1008
+ **Хост.** Источник пакета — `HandoffSource`: `{ engine, policy, workflows }`,
1009
+ где `engine` — `Engine` над хранилищем хоста, `policy` — его
1010
+ `ExecutionPolicy`, `workflows` — `list()` заданий (пакет и диагнозы берут
1011
+ задания `kind: "graph"`) и `continues(job, view, { reconfigureApplies })`,
1012
+ продолжит ли очередь задание сама. `Harness` удовлетворяет типу структурно;
1013
+ хост со своим движком передаёт свой адаптер заданий без экземпляра
1014
+ `Harness`. Состояние доски над тем же источником — `statusOf(source,
1015
+ graphId?, { detail })` (`Harness.status` — та же функция).
1016
+
1017
+ Параметры `handoffPack`: `graphId`, `intentions`, `redact`, а также
1018
+ `maxBytes` — предел хоста в байтах UTF-8, целое от `HANDOFF_MIN_BYTES`
1019
+ (4 КБ) до `HANDOFF_MAX_BYTES` (по умолчанию), иначе `INVALID_INPUT`; порядок
1020
+ отбрасывания и счётчики `truncated` те же, что у предела по умолчанию, а
1021
+ `bySize` значит «записи отброшены ради предела», а не «пакет уложился».
1022
+ Сводка, очередь, идущие попытки, задания и `next` не отбрасываются, поэтому
1023
+ уложиться не гарантируется: размер результата хост проверяет сам.
1024
+ `HANDOFF_MIN_BYTES` — нижняя граница, ниже которой не помещается даже обычный
1025
+ минимальный пакет, а не гарантия. `measure` — что укладывается в предел: `json` (по умолчанию) —
1026
+ сериализованный пакет; `markdown` — и JSON, и `handoffMarkdown(pack)`
1027
+ (Markdown бывает длиннее JSON: «|» в ячейке экранируется). Свой раздел
1028
+ Markdown хост учитывает, уменьшая `maxBytes`. Маску из секретов политики и
1029
+ своих значений хост составляет из `policySecrets(policy, env?)`,
1030
+ `redactor` и `composeRedactors` корня пакета.
1031
+
910
1032
  Весь пакет — один снимок хранилища: `handoffPack` выполняет status,
911
1033
  диагнозы и чтение заданий графов внутри одного `read`
912
1034
  (`SqliteExecutionStore.read` вложенным чтением использует снимок внешнего,
@@ -0,0 +1,33 @@
1
+ # devcontour-harness 0.1.0-alpha.32
2
+
3
+ Хост строит пакет передачи контекста над своим движком без экземпляра
4
+ `Harness` и под свой предел ответа, а проверки в песочнице стартуют и при
5
+ глубоком TMPDIR. Форматы состояния, политики, событий и `HandoffPack`
6
+ прежние.
7
+
8
+ ## Изменения
9
+
10
+ - **Пакет передачи для хоста.** `handoffPack(source, options)` принимает
11
+ `HandoffSource` (`{ engine, policy, workflows }`); `Harness` ему
12
+ удовлетворяет. `statusOf(source, graphId?, { detail })` — состояние доски
13
+ над движком и политикой. Параметры `maxBytes` (от 4096 байт до 256 КБ) и
14
+ `measure` (`json` | `markdown`) подгоняют пакет тем же порядком
15
+ отбрасывания под меньший предел; `truncated.bySize` значит «записи
16
+ отброшены», размер результата хост проверяет сам.
17
+ - **Экспорты из корня пакета.** `policySecrets` (секреты политики для маски
18
+ хоста), `writeReportFile`, `REPORT_FILE_MODE`, `ReportFileIo` (запись
19
+ отчёта, как у `harness report --out`), `HANDOFF_MIN_BYTES`.
20
+ `devcontour-harness/report` по-прежнему без `node:*`.
21
+ - **Песочница при глубоком TMPDIR.** Когда путь unix-сокета sandbox-runtime
22
+ не помещается в предел ОС (104 байта на macOS, 108 на Linux), srt получает
23
+ короткий каталог `/tmp/dc-srt-<pid>-*` с правами `0700`, который
24
+ удаляется после проверки. Брошенные каталоги этого пользователя, где ничего
25
+ не менялось больше суток и создателя нет, убираются при создании нового.
26
+ Если короткий каталог недоступен — отказ среды с TMPDIR в тексте. Раньше
27
+ проверка падала с `listen EINVAL` и не считалась отказом среды.
28
+ - Строка Markdown об урезании пакета — «Пакет урезан по пределу размера».
29
+
30
+ ## Обновление
31
+
32
+ Пакет alpha.31 остаётся неизменным. Состояние и политика не меняются, откат
33
+ копии не требует. Подробнее — `docs/upgrade.md`.
@@ -0,0 +1,29 @@
1
+ # devcontour-harness 0.1.0-alpha.33
2
+
3
+ Пакет передачи и `explain` на долгой истории больше не начинают с ложных
4
+ решений: отменённая работа — решение ведущего, только пока от неё ждёт
5
+ незавершённая работа, а расход ревью плана не повторяется строкой у каждого
6
+ поручения. Форматы состояния, политики и событий прежние; `handoffVersion` — 1.
7
+
8
+ ## Изменения
9
+
10
+ - **Отменённые без ждущих.** `CANCELLED` → `replan-dependents` только при
11
+ прямо зависящей незавершённой работе, сообщение называет ждущих. Без них
12
+ отменённая работа в общий `explain` и в `stops`/`next` пакета не входит;
13
+ `explain --work` показывает её с `action: none`.
14
+ - **Упавшая с классом `cancelled`.** Движок её не повторяет, поэтому без
15
+ ждущих это решение человека: `harness retry` или отмена (`user-decision`,
16
+ `nextAction` — шаг `cancelled`), а не «повтор в пределах бюджета».
17
+ - **Группа без восстановления из-за отмены.** Диагноз упавшей работы называет
18
+ отменённую, из-за которой движок не восстанавливает группу.
19
+ - **Бюджеты в пакете передачи.** Вызов о группе (ревью и проверка плана)
20
+ по-прежнему засчитывается бюджету каждого открытого поручения группы, но
21
+ строки поручений, весь расход которых — такие вызовы и которые выдачу не
22
+ держат, в пакет не входят; их число — `truncated.budgetsShared` (по
23
+ умолчанию 0). Блокирующие строки остаются.
24
+
25
+ ## Обновление
26
+
27
+ Пакет alpha.32 остаётся неизменным. Состояние не меняется, откат копии не
28
+ требует. Внешний валидатор со строгой прежней схемой пакета передачи
29
+ обновляется вместе с harness. Подробнее — `docs/upgrade.md`.
@@ -0,0 +1,32 @@
1
+ # devcontour-harness 0.1.0-alpha.34
2
+
3
+ Отчёт об эффекте различает, кто действовал: повторы, сбросы, отмены и
4
+ сдвиги базы записываются событиями с исполнителем, а отказы среды — с
5
+ причиной. Неизвестное по-прежнему не показывается нулём. `stateVersion`,
6
+ `policyVersion` и `reportVersion` прежние.
7
+
8
+ ## Изменения
9
+
10
+ - **События вмешательств.** `work.retried {by, reset, spent?, reasonLength?}`
11
+ (оператор, восстановление или хост; текст причины не хранится),
12
+ `work.cancelled {by, hadAttempt}`, `base.moved {by}` — в той же транзакции
13
+ и под тем же fencing, что и изменение. `retry`, `cancel` и `fencedRefMove`
14
+ принимают необязательного исполнителя; CLI передаёт `operator`.
15
+ - **Причина отказа.** `attempt.diagnosed {failureKind, cause, counted}` сразу
16
+ после `attempt.failed` или `attempt.expired`: запуск, сеть или файлы
17
+ песочницы, сеть зависимостей, авторизация или лимит провайдера, транспорт,
18
+ предварительная проверка, истёкшая аренда, зависание, остановка.
19
+ - **Отчёт.** Ручные и автоматические действия считаются раздельно с начала
20
+ записи событий; задача, к которой прикасались хост без исполнителя или
21
+ пауза, — «неизвестно». Сдвиги базы — всегда нижняя граница. Пропуск записи
22
+ (новая попытка без события повтора) отчёт находит по порядку журнала и
23
+ показывает окно нижней границей. Причины отказов среды — строками, без
24
+ причины — числом. Попытка с исходом `stalled` теперь засчитывается, как в
25
+ движке.
26
+
27
+ ## Обновление
28
+
29
+ Пакет alpha.33 остаётся неизменным. Новые события прежние версии с alpha.30
30
+ читают как `unknown`; ниже — откат вместе с копией состояния. Строгий
31
+ внешний валидатор отчёта обновляется вместе с harness. Подробнее —
32
+ `docs/upgrade.md`.