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

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 (103) hide show
  1. package/README.md +50 -14
  2. package/docs/architecture.md +64 -0
  3. package/docs/compatibility.md +15 -14
  4. package/docs/contracts.md +380 -26
  5. package/docs/release-notes/0.1.0-alpha.30.md +40 -0
  6. package/docs/release-notes/0.1.0-alpha.31.md +44 -0
  7. package/docs/review-probes.md +17 -17
  8. package/docs/upgrade.md +137 -0
  9. package/lib/agents/cli-adapter.js +1 -0
  10. package/lib/agents/review-probe.d.ts +1 -0
  11. package/lib/agents/review-probe.js +20 -0
  12. package/lib/cli.js +79 -1
  13. package/lib/contracts/cli.d.ts +2216 -15
  14. package/lib/contracts/cli.js +171 -4
  15. package/lib/contracts/diagnosis.d.ts +2 -1
  16. package/lib/contracts/diagnosis.js +1 -0
  17. package/lib/contracts/events.d.ts +1052 -4
  18. package/lib/contracts/events.js +94 -1
  19. package/lib/contracts/execution.d.ts +112 -1
  20. package/lib/contracts/execution.js +38 -0
  21. package/lib/contracts/handoff.d.ts +694 -0
  22. package/lib/contracts/handoff.js +291 -0
  23. package/lib/contracts/index.d.ts +2 -0
  24. package/lib/contracts/index.js +2 -0
  25. package/lib/contracts/policy.d.ts +27 -1
  26. package/lib/contracts/policy.js +38 -2
  27. package/lib/contracts/ports.d.ts +5 -1
  28. package/lib/contracts/published.d.ts +1398 -2
  29. package/lib/contracts/published.js +4 -0
  30. package/lib/contracts/repair-policy.js +5 -0
  31. package/lib/contracts/report.d.ts +1151 -0
  32. package/lib/contracts/report.js +401 -0
  33. package/lib/control/harness.d.ts +486 -7
  34. package/lib/control/harness.js +86 -1
  35. package/lib/control/recovery.d.ts +1 -1
  36. package/lib/control/report-file.d.ts +19 -0
  37. package/lib/control/report-file.js +85 -0
  38. package/lib/control/report.d.ts +9 -0
  39. package/lib/control/report.js +27 -0
  40. package/lib/engine/engine.d.ts +20 -8
  41. package/lib/engine/engine.js +73 -7
  42. package/lib/engine/joint-runner.d.ts +6 -0
  43. package/lib/engine/joint-runner.js +20 -4
  44. package/lib/engine/property-recovery.js +1 -0
  45. package/lib/engine/reuse.js +1 -0
  46. package/lib/engine/runner.d.ts +8 -0
  47. package/lib/engine/runner.js +121 -13
  48. package/lib/engine/stall-sweep.d.ts +137 -0
  49. package/lib/engine/stall-sweep.js +393 -0
  50. package/lib/environment/activity.d.ts +34 -0
  51. package/lib/environment/activity.js +55 -0
  52. package/lib/environment/dependency-network.d.ts +42 -0
  53. package/lib/environment/dependency-network.js +413 -0
  54. package/lib/environment/lifecycle.d.ts +3 -1
  55. package/lib/environment/lifecycle.js +23 -4
  56. package/lib/environment/process.d.ts +12 -1
  57. package/lib/environment/process.js +52 -0
  58. package/lib/environment/redaction.d.ts +2 -0
  59. package/lib/environment/redaction.js +19 -0
  60. package/lib/explain/state.d.ts +38 -0
  61. package/lib/explain/state.js +31 -11
  62. package/lib/handoff/index.d.ts +2 -0
  63. package/lib/handoff/index.js +3 -0
  64. package/lib/handoff/markdown.d.ts +6 -0
  65. package/lib/handoff/markdown.js +153 -0
  66. package/lib/handoff/pack.d.ts +49 -0
  67. package/lib/handoff/pack.js +492 -0
  68. package/lib/index.d.ts +4 -1
  69. package/lib/index.js +3 -0
  70. package/lib/integrations/connector/redact.d.ts +2 -13
  71. package/lib/integrations/connector/redact.js +2 -21
  72. package/lib/projections/attempt.d.ts +129 -0
  73. package/lib/projections/attempt.js +78 -0
  74. package/lib/projections/index.d.ts +2 -1
  75. package/lib/projections/index.js +2 -1
  76. package/lib/projections/stop.d.ts +30 -1
  77. package/lib/projections/stop.js +59 -24
  78. package/lib/report/compute.d.ts +72 -0
  79. package/lib/report/compute.js +1220 -0
  80. package/lib/report/document.d.ts +27 -0
  81. package/lib/report/document.js +206 -0
  82. package/lib/report/format.d.ts +23 -0
  83. package/lib/report/format.js +53 -0
  84. package/lib/report/html.d.ts +7 -0
  85. package/lib/report/html.js +109 -0
  86. package/lib/report/index.d.ts +4 -0
  87. package/lib/report/index.js +7 -0
  88. package/lib/report/markdown.d.ts +7 -0
  89. package/lib/report/markdown.js +112 -0
  90. package/lib/storage/document.d.ts +28 -6
  91. package/lib/storage/sqlite.d.ts +21 -0
  92. package/lib/storage/sqlite.js +70 -7
  93. package/lib/verification/gates-at.d.ts +11 -1
  94. package/lib/verification/gates-at.js +28 -2
  95. package/lib/verification/gates.d.ts +9 -1
  96. package/lib/verification/gates.js +20 -0
  97. package/package.json +5 -1
  98. package/schemas/execution-document.schema.json +68 -0
  99. package/schemas/execution-policy.schema.json +32 -0
  100. package/schemas/handoff-pack.schema.json +1424 -0
  101. package/schemas/run-event.schema.json +455 -0
  102. package/schemas/stop-diagnosis.schema.json +1 -0
  103. package/schemas/value-report.schema.json +2542 -0
package/README.md CHANGED
@@ -5,7 +5,7 @@ Headless-движок исполнения инженерных поручени
5
5
  интеграция с принятой веткой через compare-and-swap и машинный результат с SHA
6
6
  и доказательствами.
7
7
 
8
- > Статус: `0.1.0-alpha.29` — предварительный выпуск (alpha). Договоры
8
+ > Статус: `0.1.0-alpha.31` — предварительный выпуск (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.29 # точная версия
31
+ npm install --save-exact devcontour-harness@0.1.0-alpha.31 # точная версия
32
32
  # или: npm install --save-exact devcontour-harness@alpha # текущая alpha
33
33
  npx harness --version
34
34
  ```
@@ -90,24 +90,47 @@ git rev-parse refs/heads/harness/accepted # совпадает с data.result.
90
90
 
91
91
  ## Команды
92
92
 
93
- | Команда | Что делает |
94
- | -------------------------------------------- | -------------------------------------------------- |
95
- | `validate --graph F --policy F` | Проверка входов без моделей и записи |
96
- | `review-plan / review-contract … --author A` | Раунд технического ревью с историей находок |
97
- | `approve --state D --subject ID --digest H` | Согласование оператором (`approvalMode: operator`) |
98
- | `run --graph F --policy F --state D` | Регистрация, согласование и работа до простоя |
99
- | `status / events / result --state D` | Чтение без побочных эффектов |
100
- | `pause / resume / cancel / retry --state D` | Управление очередью и поручением |
101
- | `deliver --state D --work ID --sink file:D` | Повтор доставки без моделей и интеграции |
102
- | `worktree-cleanup --state D [--dry-run]` | Уборка деревьев завершённых попыток |
103
- | `profile --profile ID [--repository D]` | Разрешение профиля стека без команд проекта |
104
- | `doctor` | Версии, runtime, sandbox, совместимость состояния |
93
+ | Команда | Что делает |
94
+ | ----------------------------------------------- | -------------------------------------------------- |
95
+ | `validate --graph F --policy F` | Проверка входов без моделей и записи |
96
+ | `review-plan / review-contract … --author A` | Раунд технического ревью с историей находок |
97
+ | `approve --state D --subject ID --digest H` | Согласование оператором (`approvalMode: operator`) |
98
+ | `run --graph F --policy F --state D` | Регистрация, согласование и работа до простоя |
99
+ | `status / events / result --state D` | Чтение без побочных эффектов |
100
+ | `pause / resume / cancel / retry --state D` | Управление очередью и поручением |
101
+ | `deliver --state D --work ID --sink file:D` | Повтор доставки без моделей и интеграции |
102
+ | `worktree-cleanup --state D [--dry-run]` | Уборка деревьев завершённых попыток |
103
+ | `profile --profile ID [--repository D]` | Разрешение профиля стека без команд проекта |
104
+ | `doctor` | Версии, runtime, sandbox, совместимость состояния |
105
+ | `report --state D [--format md\|html]` | Отчёт об эффекте по данным проекта |
106
+ | `handoff --state D [--format md] [--intent T]…` | Пакет передачи контекста новой сессии агента |
105
107
 
106
108
  stdout — один JSON (`devcontour-harness/v1alpha1`), диагностика — stderr. Exit
107
109
  codes: 0 успех, 2 неверный вход, 3 отказ/блокировка, 4 инфраструктура.
108
110
  `HARNESS_CODEX_BIN` и `HARNESS_CLAUDE_BIN` подменяют исполняемые файлы runtime
109
111
  — например, fixture executable в тестах (это не живая модель).
110
112
 
113
+ ## Что вы увидите: отчёт
114
+
115
+ `harness report --state D --format html --out report.html` строит по
116
+ каталогу состояния один HTML-файл (или Markdown, или JSON в конверте): что
117
+ дал harness на этом проекте. Сводка — не больше пяти чисел с основанием:
118
+ сколько поручений принято и сколько с первой попытки, сколько вернули
119
+ проверки, ревью или правило области до слияния, срок от согласования до
120
+ приёмки, известный расход на принятое поручение и доля отказов окружения.
121
+ Дальше — разделы о дефектах, автономности, скорости, расходе, окружении,
122
+ неделях, таблица поручений и «Ограничения и неизвестное».
123
+
124
+ Отчёт показывает только наблюдения: счёт и длительности из записанного
125
+ состояния, без «сэкономленных часов» и сравнения «до и после». Неизвестное
126
+ не превращается в ноль («≥ $5.73», «unknown»); процент — от 20 в
127
+ знаменателе, медиана — от 5 значений, меньше трёх принятых поручений —
128
+ «недостаточно данных». Тексты prompt, находок и ошибок, токены и домашний
129
+ каталог в отчёт не попадают; `--no-titles` убирает и заголовки. Тот же
130
+ каталог — те же байты: момент отчёта — последняя метка времени в данных.
131
+ Хост строит тот же отчёт из своего хранилища: `valueReport` из
132
+ `devcontour-harness/report`. Подробно — [ValueReport](docs/contracts.md#valuereport).
133
+
111
134
  ## Библиотека
112
135
 
113
136
  ```js
@@ -124,6 +147,19 @@ PASS» нет. Адаптеры хоста реализуют порты `Execut
124
147
  `devcontour-harness/schemas/<имя>.schema.json`. Декларации используют типы
125
148
  Node.js: TypeScript-потребителю нужен `@types/node` (или `skipLibCheck`).
126
149
 
150
+ ## Выпуск 0.1.0-alpha.31
151
+
152
+ Controller сам замечает зависшие попытки и проверки (`stallSweep`, отказ
153
+ `stalled`), а `harness handoff` собирает пакет передачи контекста новой сессии
154
+ агента из хранилища.
155
+ Подробно — [заметки выпуска](docs/release-notes/0.1.0-alpha.31.md).
156
+
157
+ ## Выпуск 0.1.0-alpha.30
158
+
159
+ Отчёт об эффекте `harness report`, события стадий и `status --detail` для
160
+ наблюдения за попыткой, сетевые отказы установки зависимостей — отказ среды.
161
+ Подробно — [заметки выпуска](docs/release-notes/0.1.0-alpha.30.md).
162
+
127
163
  ## Выпуск 0.1.0-alpha.29
128
164
 
129
165
  Проверки под нагрузкой машины стартуют надёжно, а несостоявшийся старт песочницы
@@ -689,6 +689,70 @@ executable. Live smoke — отдельный opt-in с явно заданны
689
689
  каталогах: srt ищет его через `which` с таймаутом в секунду, и под
690
690
  нагрузкой машины такой поиск отказывал до запуска команды. Не найденный
691
691
  так shell по-прежнему ищет `which`.
692
+ - **Сеть и реестр при установке зависимостей.** Упавшая установка
693
+ зависимостей — класс `environment` с причиной `dependency-network`, а не
694
+ `gate`, только при всех условиях
695
+ <!-- repo-only -->(`src/environment/dependency-network.ts`)<!-- /repo-only -->:
696
+ - **Команда.** argv закреплён политикой (gate попытки или шаг `prepare`) и
697
+ сам является установкой: `npm install|i|ci|clean-install`, `pnpm
698
+ install|i|fetch`, `yarn [install]`, в том числе через `corepack` (и
699
+ `corepack pnpm@9`), по абсолютному пути и с `.cmd`. До подкоманды —
700
+ только известные опции; `--`, неизвестная опция без `=`, `npm run …`,
701
+ `npx`, `pnpm exec`, shell и собственные скрипты — не установка.
702
+ - **Входы как в базе.** Входы менеджера в проверяемом дереве совпадают с
703
+ базой попытки (`baseSha`): `.npmrc`, `.yarnrc`, `.yarnrc.yml`, pnpmfile,
704
+ `pnpm-workspace.yaml`, lockfiles, `.pnp.*` и все `.gitignore` — побайтно; в
705
+ каждом `package.json` — поля зависимостей, `overrides`, `resolutions`,
706
+ `pnpm`, `packageManager`, `workspaces` и скрипты установки. Файлы дерева
707
+ находит обход файловой системы, а не индекс git: манифест, скрытый
708
+ `.gitignore` или `.git/info/exclude`, менеджер всё равно найдёт по глобу
709
+ workspace. Обход не заходит в `node_modules`, `.git` и копию хранилища
710
+ зависимостей в корне (`.pnpm-store`), ссылки не разыменовывает; каждая
711
+ символическая ссылка дерева должна быть в базе с той же целью. Symlink
712
+ вместо файла, удаление или новый файл — расхождение. Без базы (проверка
713
+ потребителя, `runGatesAt`, lifecycle) классификации нет. На integration
714
+ сверка идёт с той же базой: правки целевой ветки после неё дают
715
+ расхождение, и отказ остаётся `gate`.
716
+ - **База не исполняет кода при установке.** Ни в одном `package.json` базы
717
+ нет скриптов установки (`preinstall`, `install`, `postinstall`,
718
+ `prepublish`, `prepare` и соседних, `dependencies`), нет pnpmfile и
719
+ `.pnp.*`, а `.npmrc`, `.yarnrc*` и `pnpm-workspace.yaml` не ссылаются на
720
+ код (`pnpmfile`, `node-options`, `script-shell`, `yarnPath`, `plugins` и
721
+ подобные). Такой скрипт базы мог бы исполнить исходник кандидата, и
722
+ выводу установки верить было бы нельзя.
723
+ - **Менеджер вышел сам** с кодом 1–127; выход по сигналу или без кода — не
724
+ его отчёт.
725
+ - **Отчёт в формате менеджера.** Заголовок ошибки pnpm (`ERR_PNPM_FETCH_403`,
726
+ `ECONNRESET` в узких пробелах), строка `npm error code …`, строка yarn
727
+ `error An unexpected error occurred: …`. Каждый названный код — сетевой:
728
+ HTTP 403, 407, 408, 429 или 5xx реестра, `FETCH_ERROR`, errno соединения,
729
+ TLS или сертификат. Каждая строка ошибки yarn несёт сетевую подпись. В
730
+ выводе нет признака ошибки проекта: lockfile, нет версии или пакета, 404,
731
+ peer-зависимости, упавший скрипт, целостность. Сетевые слова в выводе
732
+ скриптов, эхо команды npm и предупреждения повтора pnpm не засчитываются.
733
+
734
+ Сообщение начинается с `dependency-network:` и подписи — его показывают
735
+ `explain`, `result` и история попыток. Дальше отказ ведёт себя как любой
736
+ отказ окружения: попытку не тратит, ставит паузу `runtime`, повтор
737
+ восстановлением берёт того же кандидата и заново гоняет проверки, второй
738
+ одинаковый отказ останавливает работу, на поручение действует
739
+ `MAX_NEUTRAL_FAILURES`. Reviewer probe такого gate (с базой попытки) получает
740
+ `error`/`environment`.
741
+
742
+ Почему подделка не проходит. Отказ, причина которого в правке кандидата
743
+ (реестр в `.npmrc`, URL tarball, новый пакет, закрытый прокси, свой
744
+ pnpmfile или скрипт установки), — расхождение входов с базой, и он остаётся
745
+ `gate`: его видит и чинит следующая попытка, а очередь не встаёт. Напечатать
746
+ строки менеджера кандидат может только кодом, который менеджер исполняет при
747
+ установке, — его нет ни в базе, ни в дереве. Скрипт, убивший менеджер,
748
+ оставляет выход по сигналу. Остаётся настоящий отказ сети или реестра на
749
+ входах базы.
750
+
751
+ Отладчик менеджера (`SIGUSR1` открывает инспектор Node) кодом кандидата
752
+ не достижим: при совпадающих входах и базе без кода установки менеджер не
753
+ исполняет кода дерева. Поэтому `--disable-sigusr1` в `NODE_OPTIONS`
754
+ установки не добавляется — он менял бы окружение команды проекта.
755
+
692
756
  - **Корень рабочих деревьев.** При состоянии внутри репозитория checkout
693
757
  размещается в кэше пользователя вне дерева; хост может задать
694
758
  `checkoutRoot`. Корень не должен ни лежать внутри репозитория, состояния
@@ -148,20 +148,21 @@ Standalone-хост использует `digestOf` (SHA-256 каноничес
148
148
 
149
149
  ## Сохраняемые форматы
150
150
 
151
- | Что | Правило |
152
- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
153
- | Состояние `version: 1` | Читается как есть; иная версия отклоняется до записи |
154
- | Типы событий журнала | Прежние строки, см. `transactionKinds` |
155
- | Ветки | Целевая `devcontour/accepted` (в политике `refs/heads/devcontour/accepted`), ветки попыток `devcontour/run-<runId>` |
156
- | Каталоги попыток | `worktrees/<runId>`, `worktrees/<runId>-integration`, `artifacts/<runId>/…`, `dependencies/<runId>/manifest.json`; при каталоге состояния внутри репозитория деревья и снимки — под корнем вне дерева `<checkoutRoot>/<repositoryId>/…` (alpha.23) |
157
- | Receipt среды | `environment.json` `version: 1` |
158
- | Отчёт свойств, договор проверки, корпус | `version: 1` |
159
- | Хранилище зависимостей | Необязательное `repositories[].dependencyStore`: без поля политика, её digest и каталоги прежние. Каталог `dependency-store` закрыт профилю codex для всех установок, как и другие служебные каталоги; seed другого формата не используется ни как попадание, ни как основа сборки: он пересобирается и вытесняется |
160
- | Artifacts gates | Необязательное `repositories[].gates[].artifacts`: без поля политика и её digest прежние. Поле `artifactFiles` в evidence gate и в записи совместной проверки необязательно: прежние записи читаются как есть |
161
- | Владение репозиторием | `<git-common-dir>/devcontour-owner.json` |
162
- | Ресурсы | Отдельная база блокировок ресурсов `resources.sqlite`: блокировки устройств и портов, а не состояние исполнения. Таблица `seed_pins` создаётся только при первом обращении хранилища зависимостей |
163
- | Снимок коннектора | Поля `proof` и `baseline` manifest необязательны: прежние записи читаются как есть. Без `baseline` в конфигурации ревизия, graph digest и context digest те же, что в прежних версиях |
164
- | Probe ревьюера | MCP-сервер `devcontour_probe`, инструмент `run_check`; протокол — построчный JSON-RPC (stdio), журнал `probes.jsonl` |
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` |
165
166
 
166
167
  ## Переменные окружения gates
167
168