devcontour-harness 0.1.0-alpha.24 → 0.1.0-alpha.25

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.
package/README.md CHANGED
@@ -5,7 +5,7 @@ Headless-движок исполнения инженерных поручени
5
5
  интеграция с принятой веткой через compare-and-swap и машинный результат с SHA
6
6
  и доказательствами.
7
7
 
8
- > Статус: `0.1.0-alpha.24` — предварительный выпуск (alpha). Договоры
8
+ > Статус: `0.1.0-alpha.25` — предварительный выпуск (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.24 # точная версия
31
+ npm install --save-exact devcontour-harness@0.1.0-alpha.25 # точная версия
32
32
  # или: npm install --save-exact devcontour-harness@alpha # текущая alpha
33
33
  npx harness --version
34
34
  ```
@@ -123,6 +123,14 @@ PASS» нет. Адаптеры хоста реализуют порты `Execut
123
123
  `devcontour-harness/schemas/<имя>.schema.json`. Декларации используют типы
124
124
  Node.js: TypeScript-потребителю нужен `@types/node` (или `skipLibCheck`).
125
125
 
126
+ ## Выпуск 0.1.0-alpha.25
127
+
128
+ Native reviewer получает явное `previous: []` при пустой истории находок;
129
+ валидный JUnit сохраняется и при ненулевом коде gate. Хост может закрепить
130
+ границу бюджета успешно принятого цикла совместной проверки без сброса
131
+ попыток новым ID или сменой политики. Подробно —
132
+ [заметки выпуска](docs/release-notes/0.1.0-alpha.25.md).
133
+
126
134
  ## Выпуск 0.1.0-alpha.24
127
135
 
128
136
  Диагностика корня рабочих деревьев ничего не создаёт; новые корни и их
@@ -373,6 +381,33 @@ npm run check # lint, typecheck, схемы, сборка, тесты,
373
381
  npm run format:check
374
382
  ```
375
383
 
384
+ Три уровня проверки — от итерации над исправлением до выпуска:
385
+
386
+ | Уровень | Команда | Что запускает |
387
+ | --------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------- |
388
+ | На каждое исправление | `npm run test:affected [-- --base <ref>]` | тест-файлы, в статическое замыкание которых входит изменённый файл |
389
+ | Быстрый | `npm run test:fast` | весь suite без медленного яруса (тесты дольше ~60 с) |
390
+ | Полный release check | `npm run check` | lint, typecheck, схемы, сборка, весь suite с полным размером оракулов, проверка архива |
391
+
392
+ - `test:affected` сравнивает с merge-base с `master` (или с `--base`) и
393
+ учитывает индекс, рабочее дерево и неотслеживаемые файлы. Замыкание идёт
394
+ от `tests/*.test.ts` по относительным путям (`import`, `import()`,
395
+ `new URL(…)`) через helpers и `src/`; barrel-модули уточняются по
396
+ импортированным именам. Изменение вне `src/` и `tests/*.test.ts`
397
+ (package.json, tsconfig, scripts, helpers и fixtures тестов, profiles,
398
+ schemas, docs), удалённый или недостижимый файл `src/` — весь suite.
399
+ Выбор и причина печатаются перед запуском. `npm run check:fast` —
400
+ статические шаги и `test:affected`.
401
+ - Медленный ярус — список `slowTests` в `scripts/test.mjs` (начала имён
402
+ тестов). `npm test` и `npm run check` выполняют его, как и раньше.
403
+ - Оракул H1 (`tests/explain-differential.test.ts`) сохраняет 100
404
+ детерминированных случаев в обычном, выборочном и полном прогоне
405
+ (`DIFF_N` переопределяет); быстрый ярус явно исключает этот тест.
406
+ - Статические шаги `npm run check` (lint, typecheck, schemas:check) идут
407
+ параллельно; сборка, тесты и проверка архива — после них, по очереди.
408
+ - Все режимы запускают тесты одинаково: отдельный процесс на файл, tsx, не
409
+ более четырёх файлов одновременно.
410
+
376
411
  Тесты используют настоящие временные Git-репозитории, SQLite и fixture
377
412
  executables CLI codex/claude; живые модели не вызываются. Результаты
378
413
  fixture-тестов не являются проверкой качества моделей.
@@ -167,6 +167,19 @@ runtime-граф пакета.
167
167
  (`BasisProvider.jointPolicyDigest/jointSpecDigest`); продуктовые условия
168
168
  каждой записи — `HostGuards.joint`. `jointResult(workIds, id)` оценивает
169
169
  указанную проверку.
170
+ - **Бюджет принятого цикла.** Без дополнения хоста `maxAttempts` ограничивает
171
+ всю историю одного набора поручений. Хост может передать через
172
+ `BasisProvider.jointBudgetCheckpoints` принятые им успешные проверки и
173
+ неизменяемые снимки IDs завершённых проверок на момент принятия. Движок
174
+ проверяет каждую границу: успешная проверка и весь непустой снимок должны
175
+ существовать, принадлежать тому же набору и быть завершены; снимок включает
176
+ саму принятую проверку, без повторов. Вне объединения этих снимков все
177
+ следующие проверки набора разделяют общий предел. Один PASS без принятия,
178
+ новый ID набора хоста, смена политики или постановки бюджет не закрывают.
179
+ Хост отвечает за доверенную локальную acceptance и сохранение снимка;
180
+ активные проверки в него не входят. Hook выполняется внутри транзакции
181
+ начала: ошибка откатывает всю запись. Снимки бюджета не заменяют gates,
182
+ доказательства на SHA или основание оптимизации `affected`.
170
183
  - **Расход ревью плана.** Вызов о графе закрепляет за расходом группу и
171
184
  поручения из входного графа — и до его регистрации; повтор после
172
185
  исчерпания бюджета поручения или группы отклоняется до вызова.
@@ -0,0 +1,33 @@
1
+ # devcontour-harness 0.1.0-alpha.25
2
+
3
+ Уточнение запроса ревью, сохранение отчётов упавших проверок и необязательная
4
+ граница бюджета принятых циклов для хостов. Форматы состояния и политики,
5
+ обязательные gates, fencing и привязка доказательств к SHA не меняются.
6
+
7
+ ## Изменения
8
+
9
+ - **Пустая история находок.** Native reviewer явно получает требование
10
+ `previous: []`, если controller ещё не выдавал находок. Ошибки прежних
11
+ попыток и наблюдения gates остаются диагностическим контекстом; их нельзя
12
+ превращать в ссылки на придуманные ID. Строгая проверка ответа и повтор
13
+ после ошибки протокола сохраняются.
14
+ - **Отчёт при ненулевом коде.** Читаемый валидный JUnit сохраняется рядом с
15
+ логом gate и при ненулевом коде команды, с прежней проверкой границ пути
16
+ и маскированием секретов. Отчёт не превращает отказ в успех и не меняет
17
+ класс настоящего отказа песочницы.
18
+ - **Бюджет принятого цикла.** Опциональный
19
+ `BasisProvider.jointBudgetCheckpoints` сообщает успешно принятые хостом
20
+ проверки и неизменяемые снимки IDs завершённых проверок на момент принятия.
21
+ Движок проверяет границы и считает все последующие попытки того же набора
22
+ вне объединения снимков. Новый ID набора, политика или постановка бюджет
23
+ не закрывают; одного PASS без принятия недостаточно. Без hook действует
24
+ прежний предел всей истории набора. Хост отвечает за доверенную локальную
25
+ acceptance и сохранение снимка; активные проверки в снимок не входят.
26
+
27
+ ## Обновление
28
+
29
+ Пакет alpha.24 остаётся неизменным. Перед обновлением остановите writers и
30
+ сохраните копию состояния. Активные попытки и совместные проверки закреплены
31
+ за начавшей их версией движка: новая версия их не продолжает. Преобразование
32
+ состояния не требуется. Новые сведения о продуктовой acceptance хранит хост;
33
+ hook не выдаёт перенесённую историю за локальный запуск проверок.
@@ -295,6 +295,13 @@ export interface ResultSink {
295
295
  result: RunResult;
296
296
  }): Promise<DeliveryOutcome>;
297
297
  }
298
+ /** Принятая доверенным хостом граница завершённого цикла совместной проверки. */
299
+ export interface JointBudgetCheckpoint {
300
+ /** Успешная проверка, которую хост действительно принял. */
301
+ readonly verificationId: string;
302
+ /** Неизменяемый снимок завершённых проверок при принятии, включая verificationId. */
303
+ readonly settledVerificationIds: readonly string[];
304
+ }
298
305
  /**
299
306
  * Основания согласования и попыток. Формулы digest — договор хоста:
300
307
  * DevContour вычисляет их по сохранённым формулам (они включают поля
@@ -326,6 +333,16 @@ export interface BasisProvider {
326
333
  * сверяется; при начале проверки её ещё нет.
327
334
  */
328
335
  jointSpecDigest?(workIds: string[], view: ExecutionView, verificationId?: string): string;
336
+ /**
337
+ * Принятые хостом циклы проверки этого набора. Только доверенная локальная
338
+ * acceptance закрывает их бюджет: один passed без принятия недостаточен.
339
+ * Снимки фиксируются при acceptance и не расширяются при чтении. Все
340
+ * последующие проверки набора разделяют бюджет вне объединения снимков,
341
+ * независимо от ID набора хоста, политики, постановки и порядка истории.
342
+ * Без hook сохраняется предел всей истории sameWorks. Вызывается внутри
343
+ * транзакции jointStart; исключение откатывает начало проверки.
344
+ */
345
+ jointBudgetCheckpoints?(workIds: string[], view: ExecutionView): readonly JointBudgetCheckpoint[];
329
346
  /**
330
347
  * Основание эпизода разбора по свойству (постановка и контракты поручения)
331
348
  * по формуле хоста; без неё — формула harness (`episodeBasis`). Хост с
@@ -11,7 +11,7 @@ import { contractDocuments, corpusBindingHolds, effectiveChecks, episodeBasis, o
11
11
  import { afterFailure, afterSuccess, blocksClaim, closeIfBasisChanged, } from "./property-recovery.js";
12
12
  import { REQUIREMENT_GATE } from "../verification/requirements.js";
13
13
  import { pinnedCorpus, propertyProofProblem } from "../verification/acceptance.js";
14
- import { jointImpact, jointPolicyDigest, jointSpecDigest, publicJoint, sameWorks, } from "../verification/joint.js";
14
+ import { jointImpact, jointPolicyDigest, jointSpecDigest, publicJoint, sameWorks, jointBudgetAttempts, } from "../verification/joint.js";
15
15
  /** Префикс причины неудавшегося продления: первая причина не затирается следствиями. */
16
16
  export const HEARTBEAT_FAILED = 'Продление владения не удалось';
17
17
  const iso = (ms) => new Date(ms).toISOString();
@@ -2070,7 +2070,9 @@ export class Engine {
2070
2070
  payload: { verificationId: v.id, status: 'failed', error },
2071
2071
  });
2072
2072
  }
2073
- const previous = tx.verifications().filter((v) => sameWorks(v.workIds, input.workIds));
2073
+ const previous = jointBudgetAttempts(tx, input.workIds, this.host.basis.jointBudgetCheckpoints
2074
+ ? this.host.basis.jointBudgetCheckpoints([...input.workIds], tx)
2075
+ : []);
2074
2076
  if (previous.length >= this.policy.maxAttempts)
2075
2077
  throw new HarnessError('ATTEMPTS_EXHAUSTED', 'Исчерпан предел совместных проверок этого набора');
2076
2078
  const works = input.workIds.map((id) => tx.work(id));
@@ -24,8 +24,12 @@ export const CLOSED_FINDINGS_HEADER = 'Closed or withdrawn review findings (hist
24
24
  * writer — открытые находки, которые нужно устранить.
25
25
  */
26
26
  export function findingsText(history, review) {
27
- if (!history?.findings.length)
27
+ if (!history)
28
28
  return '';
29
+ if (!history.findings.length)
30
+ return review
31
+ ? 'There are no controller-issued review findings. Return `previous` as exactly []. Historical attempt errors and gate observations are not review findings: do not invent or compute ids for them.'
32
+ : '';
29
33
  const open = history.findings.filter((f) => f.status === 'open');
30
34
  const closed = history.findings.filter((f) => f.status !== 'open');
31
35
  const brief = (f) => ({
@@ -108,7 +112,9 @@ export function prompt(input) {
108
112
  JSON.stringify(attempt.dependencies)
109
113
  : '',
110
114
  'Gates that prove this work: ' + JSON.stringify(input.gates),
111
- 'Previous attempts, with the findings each review left. Address every finding that is still open first and say what you changed for it: ' +
115
+ (review && input.findings
116
+ ? 'Historical attempt errors and gate observations (diagnostic context only). Only controller-issued ids in the review findings sections below may appear in `previous`; do not derive ids from this history: '
117
+ : 'Previous attempts, with the findings each review left. Address every finding that is still open first and say what you changed for it: ') +
112
118
  JSON.stringify(previousAttempts(input.history, attempt.id)),
113
119
  findingsText(input.findings, !!review),
114
120
  !review && attempt.continuedFrom?.applied
@@ -537,6 +537,16 @@ export async function runGate(run) {
537
537
  if (result.timedOut || signal.aborted)
538
538
  throw new Error('Проверка прервана или превысила timeout');
539
539
  if (result.code !== 0) {
540
+ // Сохраняем валидный отчёт и при отказе команды, до классификации
541
+ // песочницы: после очистки worktree иначе остаётся только хвост лога.
542
+ const counts = reportPath
543
+ ? await readReport(reportPath, cwd, redact).catch(() => undefined)
544
+ : undefined;
545
+ if (counts) {
546
+ manifest = counts;
547
+ await mkdir(artifactDir, { recursive: true });
548
+ await writeFile(join(artifactDir, `${gate.id}.xml`), redact(counts.xml));
549
+ }
540
550
  const blocked = run.policy.isolation.mode === 'os'
541
551
  ? sandboxBlockedHosts(result.stdout + '\n' + result.stderr, run.policy.isolation.domains)
542
552
  : [];
@@ -560,11 +570,6 @@ export async function runGate(run) {
560
570
  (denied.length > 3 ? ` и ещё ${denied.length - 3}` : '') +
561
571
  `. Код выхода ${result.code}: ${diagnostic(result.stderr, result.stdout, redact)}`);
562
572
  }
563
- const counts = reportPath
564
- ? await readReport(reportPath, cwd, redact).catch(() => undefined)
565
- : undefined;
566
- if (counts)
567
- manifest = counts;
568
573
  throw new Error([
569
574
  `Код выхода ${result.code}`,
570
575
  counts?.failures ? `упали ${failedCases(counts)}` : '',
@@ -1,4 +1,4 @@
1
- import { type ExecutionPolicy, type ExecutionView, type JointVerification, type JointVerificationState } from '../contracts/index.ts';
1
+ import { type ExecutionPolicy, type ExecutionView, type JointVerification, type JointVerificationState, type JointBudgetCheckpoint } from '../contracts/index.ts';
2
2
  /**
3
3
  * Совместная проверка закреплённой комбинации SHA репозиториев.
4
4
  *
@@ -16,6 +16,125 @@ export declare function jointPolicyDigest(policy: ExecutionPolicy): string;
16
16
  export declare function jointSpecDigest(view: ExecutionView, workIds: string[]): string;
17
17
  /** Один и тот же набор поручений — один предмет проверки, независимо от порядка. */
18
18
  export declare const sameWorks: (a: string[], b: string[]) => boolean;
19
+ /** Незакрытые принятием попытки; checkpoints доверенного хоста проверяются целиком. */
20
+ export declare function jointBudgetAttempts(view: ExecutionView, workIds: string[], checkpoints: readonly JointBudgetCheckpoint[]): ({
21
+ status: "active";
22
+ apiVersion: "devcontour-harness/v1alpha1";
23
+ id: string;
24
+ startedAt: string;
25
+ policyDigest: string;
26
+ specDigest: string;
27
+ workIds: string[];
28
+ evidence: {
29
+ gate: string;
30
+ passed: boolean;
31
+ command: string[];
32
+ exitCode: number;
33
+ log: string;
34
+ digest: string;
35
+ summary: string;
36
+ artifacts: {
37
+ path: string;
38
+ digest: string;
39
+ }[];
40
+ durationMs?: number | undefined;
41
+ }[];
42
+ token: string;
43
+ leaseUntil: number;
44
+ manifest?: Record<string, {
45
+ sha: string;
46
+ tree: string;
47
+ }> | undefined;
48
+ manifestDigest?: string | undefined;
49
+ impact?: {
50
+ changed: string[];
51
+ affected: string[];
52
+ gateIds: string[];
53
+ mode: "all" | "affected";
54
+ reason: string;
55
+ baseline?: string | undefined;
56
+ } | undefined;
57
+ engineVersion?: string | undefined;
58
+ } | {
59
+ status: "failed";
60
+ finishedAt: string;
61
+ error: string;
62
+ apiVersion: "devcontour-harness/v1alpha1";
63
+ id: string;
64
+ startedAt: string;
65
+ policyDigest: string;
66
+ specDigest: string;
67
+ workIds: string[];
68
+ evidence: {
69
+ gate: string;
70
+ passed: boolean;
71
+ command: string[];
72
+ exitCode: number;
73
+ log: string;
74
+ digest: string;
75
+ summary: string;
76
+ artifacts: {
77
+ path: string;
78
+ digest: string;
79
+ }[];
80
+ durationMs?: number | undefined;
81
+ }[];
82
+ token: string;
83
+ leaseUntil: number;
84
+ manifest?: Record<string, {
85
+ sha: string;
86
+ tree: string;
87
+ }> | undefined;
88
+ manifestDigest?: string | undefined;
89
+ impact?: {
90
+ changed: string[];
91
+ affected: string[];
92
+ gateIds: string[];
93
+ mode: "all" | "affected";
94
+ reason: string;
95
+ baseline?: string | undefined;
96
+ } | undefined;
97
+ engineVersion?: string | undefined;
98
+ } | {
99
+ status: "passed";
100
+ finishedAt: string;
101
+ manifest: Record<string, {
102
+ sha: string;
103
+ tree: string;
104
+ }>;
105
+ manifestDigest: string;
106
+ apiVersion: "devcontour-harness/v1alpha1";
107
+ id: string;
108
+ startedAt: string;
109
+ policyDigest: string;
110
+ specDigest: string;
111
+ workIds: string[];
112
+ evidence: {
113
+ gate: string;
114
+ passed: boolean;
115
+ command: string[];
116
+ exitCode: number;
117
+ log: string;
118
+ digest: string;
119
+ summary: string;
120
+ artifacts: {
121
+ path: string;
122
+ digest: string;
123
+ }[];
124
+ durationMs?: number | undefined;
125
+ }[];
126
+ token: string;
127
+ leaseUntil: number;
128
+ impact?: {
129
+ changed: string[];
130
+ affected: string[];
131
+ gateIds: string[];
132
+ mode: "all" | "affected";
133
+ reason: string;
134
+ baseline?: string | undefined;
135
+ } | undefined;
136
+ engineVersion?: string | undefined;
137
+ })[];
19
138
  /** Gates совместной проверки в порядке их зависимостей. */
20
139
  export declare function orderedWorkspaceGates(gates: ExecutionPolicy['workspaceGates']): ({
21
140
  kind: "test";
@@ -1,4 +1,4 @@
1
- import { digestOf, } from "../contracts/index.js";
1
+ import { digestOf, HarnessError, } from "../contracts/index.js";
2
2
  /**
3
3
  * Совместная проверка закреплённой комбинации SHA репозиториев.
4
4
  *
@@ -38,6 +38,43 @@ export function jointSpecDigest(view, workIds) {
38
38
  }
39
39
  /** Один и тот же набор поручений — один предмет проверки, независимо от порядка. */
40
40
  export const sameWorks = (a, b) => JSON.stringify([...a].sort()) === JSON.stringify([...b].sort());
41
+ /** Незакрытые принятием попытки; checkpoints доверенного хоста проверяются целиком. */
42
+ export function jointBudgetAttempts(view, workIds, checkpoints) {
43
+ const invalid = () => {
44
+ throw new HarnessError('INVALID_INPUT', 'Невалидная принятая граница бюджета совместных проверок');
45
+ };
46
+ if (!Array.isArray(checkpoints))
47
+ invalid();
48
+ const settled = new Set();
49
+ const anchors = new Set();
50
+ for (const checkpoint of checkpoints) {
51
+ if (!checkpoint ||
52
+ typeof checkpoint.verificationId !== 'string' ||
53
+ !checkpoint.verificationId.length ||
54
+ !Array.isArray(checkpoint.settledVerificationIds))
55
+ invalid();
56
+ const { verificationId, settledVerificationIds: ids } = checkpoint;
57
+ const anchor = view.verification(verificationId);
58
+ if (anchors.has(verificationId) ||
59
+ !anchor ||
60
+ anchor.status !== 'passed' ||
61
+ !sameWorks(anchor.workIds, workIds) ||
62
+ !ids.length ||
63
+ new Set(ids).size !== ids.length ||
64
+ !ids.includes(verificationId))
65
+ invalid();
66
+ anchors.add(verificationId);
67
+ for (const id of ids) {
68
+ if (typeof id !== 'string' || !id.length)
69
+ invalid();
70
+ const v = view.verification(id);
71
+ if (!v || (v.status !== 'passed' && v.status !== 'failed') || !sameWorks(v.workIds, workIds))
72
+ invalid();
73
+ settled.add(id);
74
+ }
75
+ }
76
+ return view.verifications().filter((v) => sameWorks(v.workIds, workIds) && !settled.has(v.id));
77
+ }
41
78
  /** Gates совместной проверки в порядке их зависимостей. */
42
79
  export function orderedWorkspaceGates(gates) {
43
80
  const byId = new Map(gates.map((g) => [g.id, g]));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "devcontour-harness",
3
- "version": "0.1.0-alpha.24",
3
+ "version": "0.1.0-alpha.25",
4
4
  "description": "Headless execution harness: work graph, isolated attempts, gates, independent reviews and accepted results.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -82,9 +82,12 @@
82
82
  "schemas:check": "node --import tsx scripts/build-schemas.ts --check",
83
83
  "lint": "eslint .",
84
84
  "test": "node scripts/test.mjs",
85
+ "test:fast": "node scripts/test.mjs --fast",
86
+ "test:affected": "node scripts/test.mjs --affected",
85
87
  "test:integration": "node --import tsx --test --test-concurrency=1 --test-timeout=1800000 tests/integration/*.test.ts",
86
88
  "test:package": "npm run build && node scripts/smoke-package.mjs",
87
- "check": "npm run lint && npm run typecheck && npm run schemas:check && npm run build && npm test && node scripts/smoke-package.mjs",
89
+ "check": "node scripts/static-checks.mjs && npm run build && node scripts/test.mjs --release && node scripts/smoke-package.mjs",
90
+ "check:fast": "node scripts/static-checks.mjs && node scripts/test.mjs --affected",
88
91
  "format": "prettier --write .",
89
92
  "format:check": "prettier --check .",
90
93
  "check:install": "node scripts/install-check.mjs"