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

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 (65) hide show
  1. package/README.md +30 -2
  2. package/docs/architecture.md +64 -0
  3. package/docs/compatibility.md +15 -14
  4. package/docs/contracts.md +244 -26
  5. package/docs/release-notes/0.1.0-alpha.30.md +40 -0
  6. package/docs/review-probes.md +17 -17
  7. package/docs/upgrade.md +93 -0
  8. package/lib/agents/review-probe.d.ts +1 -0
  9. package/lib/agents/review-probe.js +20 -0
  10. package/lib/cli.js +57 -1
  11. package/lib/contracts/cli.d.ts +1150 -22
  12. package/lib/contracts/cli.js +129 -4
  13. package/lib/contracts/events.d.ts +642 -3
  14. package/lib/contracts/events.js +48 -0
  15. package/lib/contracts/index.d.ts +1 -0
  16. package/lib/contracts/index.js +1 -0
  17. package/lib/contracts/ports.d.ts +5 -1
  18. package/lib/contracts/published.d.ts +559 -2
  19. package/lib/contracts/published.js +2 -0
  20. package/lib/contracts/report.d.ts +1149 -0
  21. package/lib/contracts/report.js +401 -0
  22. package/lib/control/harness.d.ts +454 -1
  23. package/lib/control/harness.js +83 -1
  24. package/lib/control/report-file.d.ts +19 -0
  25. package/lib/control/report-file.js +85 -0
  26. package/lib/control/report.d.ts +9 -0
  27. package/lib/control/report.js +27 -0
  28. package/lib/engine/engine.d.ts +5 -1
  29. package/lib/engine/engine.js +49 -7
  30. package/lib/engine/runner.js +5 -2
  31. package/lib/environment/dependency-network.d.ts +42 -0
  32. package/lib/environment/dependency-network.js +413 -0
  33. package/lib/environment/lifecycle.d.ts +3 -1
  34. package/lib/environment/lifecycle.js +22 -4
  35. package/lib/environment/process.d.ts +5 -0
  36. package/lib/environment/process.js +38 -0
  37. package/lib/explain/state.d.ts +38 -0
  38. package/lib/explain/state.js +19 -11
  39. package/lib/index.d.ts +2 -0
  40. package/lib/index.js +2 -0
  41. package/lib/projections/attempt.d.ts +101 -0
  42. package/lib/projections/attempt.js +64 -0
  43. package/lib/projections/index.d.ts +2 -1
  44. package/lib/projections/index.js +2 -1
  45. package/lib/projections/stop.d.ts +19 -0
  46. package/lib/projections/stop.js +33 -27
  47. package/lib/report/compute.d.ts +72 -0
  48. package/lib/report/compute.js +1219 -0
  49. package/lib/report/document.d.ts +27 -0
  50. package/lib/report/document.js +206 -0
  51. package/lib/report/format.d.ts +23 -0
  52. package/lib/report/format.js +53 -0
  53. package/lib/report/html.d.ts +7 -0
  54. package/lib/report/html.js +109 -0
  55. package/lib/report/index.d.ts +4 -0
  56. package/lib/report/index.js +7 -0
  57. package/lib/report/markdown.d.ts +7 -0
  58. package/lib/report/markdown.js +112 -0
  59. package/lib/storage/sqlite.d.ts +19 -0
  60. package/lib/storage/sqlite.js +61 -6
  61. package/lib/verification/gates.d.ts +6 -0
  62. package/lib/verification/gates.js +15 -0
  63. package/package.json +5 -1
  64. package/schemas/run-event.schema.json +95 -0
  65. package/schemas/value-report.schema.json +2541 -0
@@ -75,14 +75,14 @@ To run a declared gate, call run_check with exactly {"gate":"domain"}, {"gate":"
75
75
 
76
76
  ## Статусы
77
77
 
78
- | `status` | `failure` | Смысл |
79
- | ------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80
- | `passed` | — | код 0 и (для gate с отчётом) свежий JUnit без failures и skips |
81
- | `failed` | — | код ≠ 0 или упали testcases: наблюдение о коде |
82
- | `failed` | `report` | код 0, но отчёт `missing`/`stale`/`corrupt`/`unsafe`: не прохождение и не находка в коде |
83
- | `error` | `environment` | путь отчёта зашит в argv, отказ записи (EPERM/EACCES) мимо `HARNESS_REPORT_PATH`, отказ scratch, сеть закрыта песочницей, нет песочницы, песочница не запустила команду |
84
- | `timeout`, `cancelled` | — | команда остановлена вместе с потомками |
85
- | `budget-exhausted`, `rejected` | — | команда не запускалась |
78
+ | `status` | `failure` | Смысл |
79
+ | ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
80
+ | `passed` | — | код 0 и (для gate с отчётом) свежий JUnit без failures и skips |
81
+ | `failed` | — | код ≠ 0 или упали testcases: наблюдение о коде |
82
+ | `failed` | `report` | код 0, но отчёт `missing`/`stale`/`corrupt`/`unsafe`: не прохождение и не находка в коде |
83
+ | `error` | `environment` | путь отчёта зашит в argv, отказ записи (EPERM/EACCES) мимо `HARNESS_REPORT_PATH`, отказ scratch, сеть закрыта песочницей, установка зависимостей упала на сети или реестре (`dependency-network`), нет песочницы, песочница не запустила команду |
84
+ | `timeout`, `cancelled` | — | команда остановлена вместе с потомками |
85
+ | `budget-exhausted`, `rejected` | — | команда не запускалась |
86
86
 
87
87
  Ошибка среды и ошибка отчёта — не находка в коде; находка, сославшаяся на запуск с
88
88
  `failure: environment`, не получает `observed`.
@@ -115,15 +115,15 @@ target ref.
115
115
  команду, когда весь stderr — только строки известного отказа запуска srt (`Error: Shell '…' not
116
116
  found in PATH`, `Failed to execute command: …`), даёт `error`/`environment`.
117
117
 
118
- | Событие | В `commands` |
119
- | ----------------------------------------------------------------------------------------- | ------------ |
120
- | Команда завершилась с любым кодом | да |
121
- | `timeout`/`cancelled` после старта (код `null`, частичный вывод) | да |
122
- | `error`/`environment` после старта (сеть закрыта песочницей, EPERM, сбой записи evidence) | да |
123
- | `failed`/`report`: код 0, JUnit отсутствует или испорчен | да |
124
- | Неизвестный gate, бюджет исчерпан, нет executable, отказ песочницы или scratch до старта | нет |
125
- | Вызов отменён до запуска (`cancelled`, команда не исполнялась) | нет |
126
- | Только резерв `start`, `abandoned`, битая строка, объект без формы исхода | нет |
118
+ | Событие | В `commands` |
119
+ | --------------------------------------------------------------------------------------------------------------- | ------------ |
120
+ | Команда завершилась с любым кодом | да |
121
+ | `timeout`/`cancelled` после старта (код `null`, частичный вывод) | да |
122
+ | `error`/`environment` после старта (сеть закрыта песочницей, `dependency-network`, EPERM, сбой записи evidence) | да |
123
+ | `failed`/`report`: код 0, JUnit отсутствует или испорчен | да |
124
+ | Неизвестный gate, бюджет исчерпан, нет executable, отказ песочницы или scratch до старта | нет |
125
+ | Вызов отменён до запуска (`cancelled`, команда не исполнялась) | нет |
126
+ | Только резерв `start`, `abandoned`, битая строка, объект без формы исхода | нет |
127
127
 
128
128
  Незасчитанные записи перечислены в `inspection.excluded` с причиной; полная диагностика — в
129
129
  `review.json.probes` и журнале.
package/docs/upgrade.md CHANGED
@@ -220,6 +220,99 @@ setgid или sticky — отказ (pnpm таких не создаёт). От
220
220
  версии, seeds и копии подходят обеим. Подробнее —
221
221
  [хранилище зависимостей](toolchains.md#хранилище-зависимостей).
222
222
 
223
+ ### alpha.30: события стадий
224
+
225
+ Форматы состояния (`stateVersion: 1`), политики и её digest прежние: в
226
+ документ состояния не добавлено ни одного поля. Новое в журнале и в CLI:
227
+
228
+ - **Терпимое чтение событий.** Событие типа, которого версия не знает
229
+ (записанное более новой версией), `events` и `ExecutionStore.events`
230
+ возвращают непрозрачным: конверт без нагрузки, `type: 'unknown'` и исходный
231
+ тип в `original` — а не обрывают список отказом. Писатель строгий: событие
232
+ `unknown` не записывается. Известный тип с нарушенной нагрузкой — по-прежнему
233
+ отказ. Хост, который сам разбирает сохранённые события, использует
234
+ `readRunEvent`. В TypeScript `RunEvent` теперь включает `UnknownRunEvent`:
235
+ код, читающий `payload` без сужения по `type`, перестаёт компилироваться —
236
+ сузить (`e.type !== 'unknown'` или конкретный тип) либо взять
237
+ `KnownRunEvent`. Тип `ExecutionStore.events()` прежний: хранилища хоста не
238
+ меняются.
239
+ - **Событие `attempt.stage`.** На каждую стадию попытки (замер
240
+ `AttemptState.timings`) — одно `started` и не больше одного `finished` с
241
+ `durationMs` и исходом, в той же транзакции под fencing, что и замер.
242
+ Стадия попытки, утратившей владение или упавшей, остаётся открытой; её
243
+ конец — событие конца попытки.
244
+ - **`status --detail`.** Поле `detail`: почему стоит выдача и активные
245
+ попытки — стадия и её длительность, владение и его свежесть, счёт gates.
246
+ Без флага ответ `status` прежний.
247
+
248
+ **Откат.** Прежние версии (alpha.29 и ниже) разбирают каждое событие строго:
249
+ терпимое чтение появляется только с этой версией. После отката ниже неё
250
+ `harness events` и чтение журнала хостом через прежний `ExecutionStore.events`
251
+ отказывают на первой странице, где есть `attempt.stage`; документ состояния,
252
+ `status`, `result` и работа очереди читаются как прежде. Рекомендуемый путь —
253
+ строка «Новая версия уже изменила формат» таблицы [«Откат»](#откат): остановить
254
+ writers и восстановить копию каталога состояния, снятую до обновления, вместе
255
+ с прежней версией пакета. Без копии прежняя версия продолжает работу очереди,
256
+ но журнал после первого `attempt.stage` ей не прочитать; удалять или
257
+ переписывать события ради неё нельзя.
258
+
259
+ ### alpha.30: отчёт об эффекте
260
+
261
+ Форматы состояния (`stateVersion: 1`), политики, событий и их схем прежние:
262
+ отчёт только читает. Новое — аддитивно:
263
+
264
+ - **`harness report`.** Отчёт по каталогу состояния: принятые поручения и
265
+ первая попытка, возвраты проверками и ревью, действия человека (нижняя
266
+ граница), срок от согласования до приёмки, расход (неизвестная цена —
267
+ «≥», а не ноль), отказы окружения, недели и ограничения. `--format
268
+ json|md|html`, `--out F`, окно `--since/--until`, `--as-of`, `--no-titles`.
269
+ База открывается только для чтения; `binding.json` не нужен.
270
+ - **Библиотека.** `devcontour-harness/report` (`valueReport`,
271
+ `reportMarkdown`, `reportHtml`; без `node:*`), в корне — те же функции,
272
+ `collectReportInput(store)` и `Harness.report()`.
273
+ - **Чтение без файлов.** `report` читает состояние однократно: база без
274
+ журнала открывается неизменяемой и в каталоге состояния не появляется
275
+ служебных `-wal`/`-shm`; если писатель начал работу во время чтения,
276
+ оно повторяется обычным открытием. Прочие читающие команды не менялись.
277
+ - **Схема.** `value-report` (`schemas/value-report.schema.json`,
278
+ `reportVersion: 1`) и данные `report` в `cliDataSchemas`.
279
+
280
+ Определения, правила малых выборок и приватности — [ValueReport](contracts.md#valuereport).
281
+ Отчёт строится из истории как она записана: попытки прежних версий без класса
282
+ отказа показаны `unclassified`, без `wait` — с запасным началом срока, без
283
+ учёта вызовов — с неизвестным расходом; история не переписывается.
284
+
285
+ **Откат.** Ниже этой версии команды `report` нет; состояние она не меняла,
286
+ поэтому откат пакета копии не требует.
287
+
288
+ ### alpha.30: сетевой отказ установки зависимостей
289
+
290
+ Форматы состояния и политики прежние; нового поля в состоянии нет. В
291
+ описании reviewer probe (`probe.json`) — необязательное поле `trustedBase`.
292
+ Установка зависимостей, упавшая на сети или реестре пакетов, теперь отказ
293
+ `environment`, а не `gate`; сообщение начинается с `dependency-network:`.
294
+ Условия:
295
+
296
+ - argv gate попытки или шага `prepare` сам вызывает `npm install|ci`, `pnpm
297
+ install|fetch` или `yarn install`;
298
+ - входы менеджера в дереве (`.npmrc`, `.yarnrc*`, pnpmfile, lockfiles, поля
299
+ зависимостей и скрипты установки `package.json`) совпадают с базой попытки;
300
+ - база не исполняет кода при установке;
301
+ - менеджер вышел сам с кодом 1–127;
302
+ - его отчёт называет только сетевые коды: HTTP 403/407/408/429/5xx реестра,
303
+ обрыв соединения, DNS, TLS.
304
+
305
+ Такой отказ не тратит попытку поручения и ставит паузу очереди `runtime`, как
306
+ любой отказ окружения. Повтор берёт того же кандидата, работу ограничивает
307
+ `MAX_NEUTRAL_FAILURES`. Отказ после правки кандидатом реестра, зависимостей
308
+ или скриптов установки, ошибки lockfile, 404, peer-зависимости и упавший скрипт
309
+ остаются `gate`. Прежде такой отказ gate давал класс `gate`, а шаг `prepare` —
310
+ `unknown`. Хосту, который считает «дефекты, найденные проверками» по
311
+ `failureKind`, новых действий не нужно: эти отказы уходят из счёта сами.
312
+ Правило — [архитектура](architecture.md#что-гарантируется). При откате
313
+ возвращается прежняя классификация; уже записанные попытки сохраняют свой
314
+ класс.
315
+
223
316
  ## Перед обновлением
224
317
 
225
318
  1. **Остановить записывающих.** Запретить новые выдачи (`harness pause`),
@@ -75,6 +75,7 @@ export declare const probeSpec: z.ZodObject<{
75
75
  }, z.core.$strict>>>;
76
76
  phase: z.ZodOptional<z.ZodString>;
77
77
  sha: z.ZodOptional<z.ZodString>;
78
+ trustedBase: z.ZodOptional<z.ZodString>;
78
79
  scope: z.ZodOptional<z.ZodObject<{
79
80
  attempt: z.ZodString;
80
81
  phase: z.ZodString;
@@ -8,6 +8,7 @@ import { createInterface } from 'node:readline';
8
8
  import { fileURLToPath } from 'node:url';
9
9
  import { z } from 'zod';
10
10
  import { idSchema, relativePathSchema, sha256, TaskFailure, } from "../contracts/index.js";
11
+ import { dependencyNetworkFailure, dependencyNetworkMessage, } from "../environment/dependency-network.js";
11
12
  import { osToolEnv } from "../environment/os-tools.js";
12
13
  import { redactor } from "../environment/redaction.js";
13
14
  import { completedCheck, freshnessEnv, propertyReportEnv, junitSummary, runCheck, sandboxBlockedHosts, } from "../verification/gates.js";
@@ -75,6 +76,8 @@ export const probeSpec = z.object({
75
76
  /** Фаза и SHA ревью: записываются в каждый запуск gate. */
76
77
  phase: z.string().optional(),
77
78
  sha: z.string().optional(),
79
+ /** SHA базы попытки: только с ним gate установки может стать `dependency-network`. */
80
+ trustedBase: z.string().optional(),
78
81
  /**
79
82
  * Вызов reviewer, которому принадлежит журнал: попытка harness, фаза, SHA
80
83
  * и номер вызова. Записывается в каждый исход — по нему итог ревью не
@@ -565,6 +568,15 @@ export class ReviewProbes {
565
568
  const blocked = this.spec.isolation.mode === 'os' && r.code !== 0
566
569
  ? sandboxBlockedHosts(output, this.spec.isolation.domains)
567
570
  : [];
571
+ const network = r.code !== 0 && !r.timedOut && !signal.aborted
572
+ ? await dependencyNetworkFailure({
573
+ argv: gate.command,
574
+ code: r.code,
575
+ output,
576
+ root,
577
+ ...(this.spec.trustedBase ? { base: this.spec.trustedBase } : {}),
578
+ })
579
+ : undefined;
568
580
  if (signal.aborted)
569
581
  outcome = {
570
582
  ...base,
@@ -595,6 +607,14 @@ export class ReviewProbes {
595
607
  failure: 'environment',
596
608
  note: `Песочница закрыла сеть к ${blocked.join(', ')} (нет в isolation.domains): ошибка среды, не находка в коде.`,
597
609
  };
610
+ else if (network)
611
+ outcome = {
612
+ ...base,
613
+ ...streams,
614
+ status: 'error',
615
+ failure: 'environment',
616
+ note: dependencyNetworkMessage(redact(network), 'Это ошибка среды, а не находка в коде.'),
617
+ };
598
618
  else if (r.code !== 0 && report?.status !== 'fresh' && writeDenied.test(output))
599
619
  // Отчёта нет, а проверка получила отказ записи: она писала мимо
600
620
  // HARNESS_REPORT_PATH — в дерево, которое здесь только для чтения.
package/lib/cli.js CHANGED
@@ -21,6 +21,10 @@ import { isSharedOperation, sharedOperations } from "./catalog/shared.js";
21
21
  import { harnessCapabilities } from "./catalog/harness.js";
22
22
  import { hostGitArgs } from "./environment/process.js";
23
23
  import { FileContextSource, FileResultSink, FileWorkSource } from "./connectors/files.js";
24
+ import { SqliteExecutionStore } from "./storage/sqlite.js";
25
+ import { collectReportInput } from "./control/report.js";
26
+ import { writeReportFile } from "./control/report-file.js";
27
+ import { valueReport, reportHtml, reportMarkdown } from "./report/index.js";
24
28
  const usage = `harness ${HARNESS_VERSION}
25
29
 
26
30
  Использование: harness <команда> [параметры]
@@ -211,6 +215,12 @@ const options = {
211
215
  contracts: { type: 'string' },
212
216
  requirements: { type: 'string', multiple: true },
213
217
  'dry-run': { type: 'boolean' },
218
+ detail: { type: 'boolean' },
219
+ since: { type: 'string' },
220
+ until: { type: 'string' },
221
+ 'as-of': { type: 'string' },
222
+ format: { type: 'string' },
223
+ 'no-titles': { type: 'boolean' },
214
224
  };
215
225
  /** Новые флаги H1 допустимы только у своих команд; прежние команды их не принимают. */
216
226
  const flagOwners = {
@@ -223,6 +233,12 @@ const flagOwners = {
223
233
  contracts: ['plan-request', 'plan-check'],
224
234
  requirements: ['plan-request'],
225
235
  'dry-run': ['worktree-cleanup'],
236
+ detail: ['status'],
237
+ since: ['report'],
238
+ until: ['report'],
239
+ 'as-of': ['report'],
240
+ format: ['report'],
241
+ 'no-titles': ['report'],
226
242
  };
227
243
  /** Явное человеческое представление успешного ответа (`--human`). */
228
244
  const presenters = {
@@ -272,6 +288,7 @@ const readText = (path, what) => {
272
288
  throw new HarnessError('INVALID_INPUT', `${what}: не прочитан ${path}: ${error.message}`);
273
289
  }
274
290
  };
291
+ const reportFormats = ['json', 'md', 'html'];
275
292
  async function run(argv) {
276
293
  const [name, ...rest] = argv;
277
294
  if (name === '--version' || name === 'version') {
@@ -430,7 +447,7 @@ async function run(argv) {
430
447
  const h = open(need('state'), binding(need('state')), 'state');
431
448
  try {
432
449
  if (command === 'status')
433
- return { command, data: h.status(v.graph) };
450
+ return { command, data: h.status(v.graph, { detail: Boolean(v.detail) }) };
434
451
  if (command === 'events')
435
452
  return { command, data: h.events(Number(v.after ?? 0), Number(v.limit ?? 100)) };
436
453
  return { command, data: h.result(need('work')) };
@@ -576,6 +593,42 @@ async function run(argv) {
576
593
  }),
577
594
  };
578
595
  }
596
+ case 'report': {
597
+ const state = need('state');
598
+ const format = (v.format ?? 'json');
599
+ if (!reportFormats.includes(format))
600
+ throw new HarnessError('INVALID_INPUT', '--format: ожидается json, md или html', [
601
+ { path: ['--format'], message: String(v.format) },
602
+ ]);
603
+ const file = join(resolve(state), 'state.sqlite');
604
+ if (!existsSync(file))
605
+ throw new HarnessError('NOT_FOUND', 'Каталог состояния не найден: ' + state);
606
+ // Однократное чтение без записи и без файлов в каталоге состояния
607
+ // (неизменяемое открытие с проверкой после чтения, `readOnce`).
608
+ const report = SqliteExecutionStore.readOnce(file, 'devcontour-harness@' + HARNESS_VERSION, (store) => valueReport(collectReportInput(store), {
609
+ ...optional('since', v.since),
610
+ ...optional('until', v.until),
611
+ ...optional('asOf', v['as-of']),
612
+ ...(v['no-titles'] ? { noTitles: true } : {}),
613
+ label: basename(resolve(state)),
614
+ stateDir: resolve(state),
615
+ harnessVersion: HARNESS_VERSION,
616
+ }));
617
+ if (format === 'json' && !v.out)
618
+ return { command, data: report };
619
+ const text = format === 'json'
620
+ ? JSON.stringify(report, null, 2) + '\n'
621
+ : format === 'md'
622
+ ? reportMarkdown(report)
623
+ : reportHtml(report);
624
+ if (!v.out)
625
+ return { command, data: report, text };
626
+ writeReportFile(v.out, state, text);
627
+ return {
628
+ command,
629
+ data: { out: v.out, format, bytes: Buffer.byteLength(text), asOf: report.window.asOf },
630
+ };
631
+ }
579
632
  case 'plan-request': {
580
633
  const b = loadPolicy(need('policy'));
581
634
  const first = b.policy.repositories[0]?.id ?? 'main';
@@ -658,6 +711,9 @@ try {
658
711
  const present = result.command !== 'version' ? presenters[result.command] : undefined;
659
712
  if (present && argv.includes('--human'))
660
713
  text = present(envelope.data);
714
+ // report --format md|html: проверенные данные печатаются текстом, без конверта.
715
+ if (result.text !== undefined)
716
+ text = result.text;
661
717
  }
662
718
  catch (error) {
663
719
  const known = error instanceof HarnessError