devcontour-harness 0.1.0-alpha.13 → 0.1.0-alpha.18

package/lib/verification/gates-at.js

@@ -0,0 +1,173 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { HarnessError } from "../contracts/index.js";
+import { TaskFailure } from "../engine/failure.js";
+import { git } from "../environment/process.js";
+import { executionEnvironment, runSteps, withEnvironment } from "../environment/lifecycle.js";
+import { defaultResourceDatabase, withResources } from "../environment/resources.js";
+import { removeSnapshots, snapshotDependencies } from "./dependencies.js";
+import { runGate } from "./gates.js";
+import { explicitPrerequisites, orderedScope, standaloneScope } from "./gate-scope.js";
+/**
+ * Gates компонента на закреплённом SHA вне попытки — тем же исполнением, что
+ * integration поручения: отдельное рабочее дерево на SHA, снимки зависимостей
+ * компонента, ресурсы gates, lifecycle и prepare компонента, окружение фазы
+ * `integration`, песочница проверок и `runGate`. Каждое evidence (вида `test`,
+ * фазы `integration`, на этом SHA) записывается через `record` хоста до
+ * следующего gate. После gates дерево обязано остаться на SHA без изменений.
+ * Рабочее дерево и снимки убираются при любом исходе.
+ *
+ * Нужна приёмке набора поручений, когда часть gates профиля не исполнило ни
+ * одно поручение: суженные области задач — законная декомпозиция, а полный
+ * профиль проверяется один раз на итоговом SHA.
+ */
+export async function runGatesAt(ctx, input) {
+    const repo = ctx.policy.repositories.find((r) => r.id === input.repositoryId);
+    if (!repo)
+        throw new HarnessError('NOT_FOUND', 'Репозиторий не объявлен: ' + input.repositoryId);
+    if (!input.gates.length)
+        throw new HarnessError('INVALID_INPUT', 'Не названы gates проверки');
+    for (const gid of input.gates)
+        if (!repo.gates.some((g) => g.id === gid))
+            throw new HarnessError('NOT_FOUND', `Gate ${gid} не объявлен в ${repo.id}`);
+    // Та же область и тот же порядок, что исполнила бы попытка с областью из
+    // этих gates и их предпосылок (`standaloneScope`, `orderedScope`).
+    const gates = orderedScope(repo.gates, standaloneScope(repo.gates, input.gates));
+    const id = input.id ?? 'GA-' + randomUUID();
+    const path = ctx.repoPath(repo);
+    await git(path, 'cat-file', '-e', `${input.sha}^{commit}`).catch(() => {
+        throw new HarnessError('NOT_FOUND', `Commit ${input.sha} недоступен в ${repo.id}`);
+    });
+    const root = join(ctx.stateDir, 'gates-at', id);
+    const cwd = join(root, 'worktree');
+    const artifacts = join(root, 'artifacts');
+    const timeout = AbortSignal.timeout(ctx.policy.runTimeoutMs);
+    const signal = input.signal ? AbortSignal.any([input.signal, timeout]) : timeout;
+    const source = ctx.environment ?? process.env;
+    const evidence = [];
+    const failures = [];
+    const failed = new Set();
+    let snapshots = [];
+    let added = false;
+    await mkdir(root, { recursive: true });
+    try {
+        await withResources({
+            resources: ctx.policy.resources,
+            leaseMs: ctx.policy.leaseMs,
+            resourceDatabase: ctx.resourceDatabase ?? defaultResourceDatabase(),
+        }, [...new Set(gates.flatMap((g) => g.resources ?? []))], `${ctx.stateDir}:${id}`, signal, async (signal, resources) => {
+            const repos = {
+                repo: (rid) => {
+                    const found = ctx.policy.repositories.find((r) => r.id === rid);
+                    if (!found)
+                        throw new Error('Неизвестный репозиторий: ' + rid);
+                    return found;
+                },
+                path: (r) => ctx.repoPath(r),
+            };
+            if (repo.dependsOn.length)
+                snapshots = await snapshotDependencies({
+                    repos,
+                    repositoryId: repo.id,
+                    dir: join(root, 'dependencies'),
+                    artifacts,
+                    runId: id,
+                    policy: ctx.policy,
+                    environment: source,
+                    signal,
+                });
+            await git(path, 'worktree', 'add', '--detach', cwd, input.sha);
+            added = true;
+            const execution = executionEnvironment([ctx.policy.environment, repo.environment], {
+                DEVCONTOUR_REPOSITORY_ID: repo.id,
+                DEVCONTOUR_RUN_ID: id,
+                DEVCONTOUR_PHASE: 'integration',
+                DEVCONTOUR_RESOURCES_JSON: JSON.stringify(resources),
+                DEVCONTOUR_DEPENDENCIES_JSON: JSON.stringify(snapshots),
+                DEVCONTOUR_COMPONENTS_JSON: JSON.stringify({
+                    ...Object.fromEntries(snapshots.map((d) => [d.repositoryId, d.path])),
+                    [repo.id]: cwd,
+                }),
+            }, source);
+            const boundary = ctx.boundary();
+            await withEnvironment(repo.lifecycle ?? ctx.policy.lifecycle, cwd, join(artifacts, 'environment'), execution, signal, async () => {
+                await runSteps(repo.prepare, cwd, join(artifacts, 'prepare'), execution, signal);
+                for (const gate of gates) {
+                    // Пропускается только gate, чья явная предпосылка (`dependsOn`) не
+                    // прошла. Провал неявной (более ранний check gate в режиме
+                    // порядка массива) не скрывает исход тестов: исполняются и
+                    // названы оба.
+                    const blocked = explicitPrerequisites(repo.gates, gate.id).filter((g) => failed.has(g));
+                    if (blocked.length) {
+                        failed.add(gate.id);
+                        failures.push({
+                            gate: gate.id,
+                            message: 'не исполнен: не прошла предпосылка ' + blocked.join(', '),
+                        });
+                        continue;
+                    }
+                    try {
+                        await runGate({
+                            policy: ctx.policy,
+                            record: (e) => {
+                                const full = {
+                                    ...e,
+                                    id: randomUUID(),
+                                    runId: id,
+                                    createdAt: new Date().toISOString(),
+                                };
+                                input.record(full);
+                                evidence.push(full);
+                                return full;
+                            },
+                            cwd,
+                            sha: input.sha,
+                            phase: 'integration',
+                            gate,
+                            artifactDir: artifacts,
+                            signal,
+                            execution,
+                            boundary: {
+                                hidden: boundary.hidden,
+                                readable: [...boundary.readable, ...snapshots.map((d) => d.path)],
+                            },
+                            // Генеративный gate получает seed от этой проверки; договора
+                            // поручения у неё нет — прежний уровень отчёта свойств.
+                            ...(gate.property
+                                ? { property: { runId: id, contracts: {}, artifacts: [] } }
+                                : {}),
+                        });
+                    }
+                    catch (error) {
+                        // Провал gate записан (`record`); прочие ошибки — отказ проверки.
+                        if (!(error instanceof TaskFailure) || evidence.at(-1)?.gate !== gate.id)
+                            throw error;
+                        failed.add(gate.id);
+                        failures.push({ gate: gate.id, message: error.message });
+                    }
+                }
+            });
+            if ((await git(cwd, 'rev-parse', 'HEAD')) !== input.sha ||
+                (await git(cwd, 'status', '--porcelain', '--untracked-files=no')))
+                throw new Error('Проверка изменила проверяемый код');
+        });
+    }
+    finally {
+        if (added)
+            await git(path, 'worktree', 'remove', '--force', cwd).catch(() => undefined);
+        await removeSnapshots({
+            repo: (rid) => ctx.policy.repositories.find((r) => r.id === rid),
+            path: (r) => ctx.repoPath(r),
+        }, snapshots);
+        await rm(join(root, 'worktree'), { recursive: true, force: true }).catch(() => undefined);
+    }
+    return {
+        id,
+        sha: input.sha,
+        gates: gates.map((g) => g.id),
+        evidence,
+        ...(failures.length ? { failure: failures[0] } : {}),
+        failures,
+    };
+}

package/lib/verification/gates.d.ts

@@ -128,6 +128,11 @@ export declare function sandboxBlockedHosts(output: string, allowed: string[]):
  * запущенного проверкой reviewer, — иначе probe мог бы прочитать cache там,
  * где gate исполняет тесты заново.
  */
+/**
+ * Переменная пути отчёта свойств. Ту же и только её выставляет и probe
+ * reviewer (путь — в его scratch): проверка видит одно имя в обоих запусках.
+ */
+export declare const propertyReportEnv = "DEVCONTOUR_PROPERTY_REPORT";
 export declare function freshnessEnv(kind: GatePolicy['kind'], env: NodeJS.ProcessEnv): Record<string, string>;
 /** Что нужно для запуска gate попытки. */
 export interface GateRun {

package/lib/verification/gates.js

@@ -9,7 +9,7 @@ import { command, git } from "../environment/process.js";
 import { isolation, isolatedCommand, isolationSupport } from "../environment/isolation.js";
 import { TaskFailure } from "../engine/failure.js";
 import { redactDeep } from "../environment/redaction.js";
-import { manifestDigest, propertyCoverage, propertyFailure, propertySeed, readPropertyReport, } from "./property.js";
+import { expectsReference, manifestDigest, propertyCoverage, propertyFailure, propertySeed, readPropertyReport, } from "./property.js";
 /** Длинное имя testcase заменяется хешем, а не обрезается: обрезка дала бы ложные совпадения. */
 export const TEST_ID_LIMIT = 1000;
 export function portableTest(test) {
@@ -374,6 +374,11 @@ export function sandboxBlockedHosts(output, allowed) {
  * запущенного проверкой reviewer, — иначе probe мог бы прочитать cache там,
  * где gate исполняет тесты заново.
  */
+/**
+ * Переменная пути отчёта свойств. Ту же и только её выставляет и probe
+ * reviewer (путь — в его scratch): проверка видит одно имя в обоих запусках.
+ */
+export const propertyReportEnv = 'DEVCONTOUR_PROPERTY_REPORT';
 export function freshnessEnv(kind, env) {
     return kind === 'test'
         ? { TURBO_FORCE: 'true', GOFLAGS: [env.GOFLAGS, '-count=1'].filter(Boolean).join(' ') }
@@ -402,7 +407,17 @@ export async function runGate(run) {
     // тогда, когда проверка зависла и не успела ничего записать. Отчёт свойств
     // лежит в каталоге controller вне worktree: проверка пишет внутрь него, но
     // заменить сам каталог на ссылку наружу не может.
-    const property = gate.property && run.property ? run.property : undefined;
+    // Эталонная проверка поручения отчитывается тем же отчётом свойств и
+    // получает его путь и селектор и у gate без генератора.
+    const property = run.property && (gate.property || expectsReference(run.property.expected))
+        ? run.property
+        : undefined;
+    const reference = expectsReference(run.property?.expected);
+    const label = !gate.property
+        ? 'Проверка по эталонным наборам'
+        : reference
+            ? 'Проверка свойств и эталонных наборов'
+            : 'Генеративная проверка';
     const propertyDir = property
         ? await realpath(await mkdtemp(join(tmpdir(), 'harness-property-')))
         : undefined;
@@ -423,7 +438,7 @@ export async function runGate(run) {
     const propertyEnv = propertyPath
         ? {
             DEVCONTOUR_SEED: String(seed),
-            DEVCONTOUR_PROPERTY_REPORT: propertyPath,
+            [propertyReportEnv]: propertyPath,
             ...(expected
                 ? { DEVCONTOUR_PROPERTIES: expected.properties.map((p) => p.id).join(',') }
                 : {}),
@@ -563,13 +578,13 @@ export async function runGate(run) {
         }
         else if (coverage.length) {
             passed = false;
-            summary = join2('Генеративная проверка не подтвердила покрытие: ' + coverage.join('; '));
+            summary = join2(`${label} не подтвердила покрытие: ` + coverage.join('; '));
         }
         else if (passed && read.problem) {
             // Прошедшая команда без отчёта не доказывает свойство: зелёный код
             // выхода был у неё и до реализации.
             passed = false;
-            summary = `Генеративная проверка не отчиталась: ${read.problem}`;
+            summary = `${label} не отчиталась: ${read.problem}`;
         }
         propertyEvidence = {
             seed,

package/lib/verification/property.d.ts

@@ -31,6 +31,13 @@ export interface CheckManifest {
             id: string;
             minCases: number;
         }[];
+        /**
+         * Эталонная проверка: доля gate в наборах и их закреплённые файлы. Поле
+         * есть только у эталонных свойств — digest прежних манифестов прежний.
+         */
+        reference?: {
+            artifacts: string[];
+        };
     }[];
     corpus?: {
         digest: string;
@@ -40,6 +47,8 @@ export interface CheckManifest {
         }[];
     };
 }
+/** Манифест ожидает эталонной проверки: путь отчёта нужен и gate без генератора. */
+export declare const expectsReference: (manifest: CheckManifest | undefined) => boolean;
 /** Свидетельство выполнения корпуса: hash отсортированных строк `id:pass|fail`. */
 export declare function corpusWitness(cases: {
     id: string;

package/lib/verification/property.js

@@ -42,6 +42,8 @@ export function propertyFailure(report) {
                     : ''));
     return [...own, ...corpus].join('; ');
 }
+/** Манифест ожидает эталонной проверки: путь отчёта нужен и gate без генератора. */
+export const expectsReference = (manifest) => !!manifest?.properties.some((p) => p.reference);
 /** Свидетельство выполнения корпуса: hash отсортированных строк `id:pass|fail`. */
 export function corpusWitness(cases) {
     return createHash('sha256')
@@ -138,8 +140,15 @@ export function propertyCoverage(report, manifest, junit) {
             for (const id of required) {
                 const found = junit.cases.filter((c) => !c.opaque && c.id === id);
                 const p = entry(id);
-                if (!found.length)
-                    problems.push(`testcase ${id} отсутствует в JUnit`);
+                if (!found.length) {
+                    // ID testcase — `classname.name`: node:test пишет classname="test",
+                    // и свойство `x` там видно как `test.x`. Подсказка называет его.
+                    const near = junit.cases.find((c) => !c.opaque && c.id.endsWith('.' + id));
+                    problems.push(`testcase ${id} отсутствует в JUnit` +
+                        (near
+                            ? ` (есть ${near.id}: ID testcase — classname.name, property ID должен совпадать с ним)`
+                            : ''));
+                }
                 else if (found.length > 1)
                     problems.push(`testcase ${id} встречается ${found.length} раза`);
                 else if (p?.status === 'passed' && found[0].status !== 'passed')

package/lib/verification/self-check.js

@@ -1,20 +1,20 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { obligationOf } from "./checks.js";
+import { isReference, obligationOf } from "./checks.js";
 export async function writeSelfCheck(input) {
     const gates = new Map();
     for (const id of input.order.properties ?? []) {
         const found = obligationOf(input.contracts, id);
-        const gate = found && input.gates.find((g) => g.id === found.gate && g.property);
-        if (!gate)
-            continue;
-        const entry = gates.get(gate.id) ?? {
-            command: gate.command,
-            ...(gate.cwd ? { cwd: gate.cwd } : {}),
-            properties: [],
-        };
-        entry.properties.push(id);
-        gates.set(gate.id, entry);
+        // Gate эталонных наборов отчитывается тем же отчётом свойств.
+        for (const gate of input.gates.filter((g) => found?.gates.includes(g.id) && (g.property || isReference(found.obligation)))) {
+            const entry = gates.get(gate.id) ?? {
+                command: gate.command,
+                ...(gate.cwd ? { cwd: gate.cwd } : {}),
+                properties: [],
+            };
+            entry.properties.push(id);
+            gates.set(gate.id, entry);
+        }
     }
     if (!gates.size)
         return undefined;
@@ -35,7 +35,7 @@ export async function writeSelfCheck(input) {
         ...(corpus ? { corpus } : {}),
         cases: input.corpus?.cases ?? 0,
         seed: input.seed,
-        properties: [...gates.values()].flatMap((g) => g.properties),
+        properties: [...new Set([...gates.values()].flatMap((g) => g.properties))],
     };
 }
 /** Строка запроса исполнителю о самопроверке. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devcontour-harness",
-  "version": "0.1.0-alpha.13",
+  "version": "0.1.0-alpha.18",
   "description": "Headless execution harness: work graph, isolated attempts, gates, independent reviews and accepted results.",
   "type": "module",
   "license": "MIT",

package/schemas/contract-document.schema.json

@@ -306,6 +306,167 @@
                 ],
                 "additionalProperties": false
               },
+              "gates": {
+                "minItems": 1,
+                "maxItems": 10,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^[A-Za-z0-9_-]{1,80}$"
+                }
+              },
+              "verification": {
+                "type": "string",
+                "enum": [
+                  "property",
+                  "reference"
+                ]
+              },
+              "reference": {
+                "type": "object",
+                "properties": {
+                  "oracle": {
+                    "type": "object",
+                    "properties": {
+                      "description": {
+                        "type": "string",
+                        "minLength": 3,
+                        "maxLength": 2000
+                      },
+                      "limits": {
+                        "type": "string",
+                        "minLength": 3,
+                        "maxLength": 2000
+                      }
+                    },
+                    "required": [
+                      "description",
+                      "limits"
+                    ],
+                    "additionalProperties": false
+                  },
+                  "crossChecks": {
+                    "minItems": 1,
+                    "maxItems": 10,
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "family": {
+                          "type": "string",
+                          "minLength": 3,
+                          "maxLength": 200
+                        },
+                        "against": {
+                          "type": "string",
+                          "minLength": 3,
+                          "maxLength": 500
+                        },
+                        "matches": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 100000000
+                        },
+                        "total": {
+                          "type": "integer",
+                          "minimum": 1,
+                          "maximum": 100000000
+                        },
+                        "artifacts": {
+                          "minItems": 1,
+                          "maxItems": 10,
+                          "type": "array",
+                          "items": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 500,
+                            "pattern": "^(?!\\/)(?!.*[\\\\:*?\\[\\]\\x00])(?!(?:.*\\/)?\\.{1,2}(?:\\/|$))(?=.{1,500}$).+$"
+                          }
+                        }
+                      },
+                      "required": [
+                        "family",
+                        "against",
+                        "matches",
+                        "total"
+                      ],
+                      "additionalProperties": false
+                    }
+                  },
+                  "sets": {
+                    "minItems": 1,
+                    "maxItems": 20,
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "gate": {
+                          "type": "string",
+                          "pattern": "^[A-Za-z0-9_-]{1,80}$"
+                        },
+                        "artifacts": {
+                          "minItems": 1,
+                          "maxItems": 10,
+                          "type": "array",
+                          "items": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 500,
+                            "pattern": "^(?!\\/)(?!.*[\\\\:*?\\[\\]\\x00])(?!(?:.*\\/)?\\.{1,2}(?:\\/|$))(?=.{1,500}$).+$"
+                          }
+                        },
+                        "minCases": {
+                          "type": "integer",
+                          "minimum": 1,
+                          "maximum": 1000000
+                        },
+                        "families": {
+                          "default": [],
+                          "maxItems": 20,
+                          "type": "array",
+                          "items": {
+                            "type": "object",
+                            "properties": {
+                              "id": {
+                                "type": "string",
+                                "pattern": "^[A-Za-z0-9_-]{1,80}$"
+                              },
+                              "minCases": {
+                                "type": "integer",
+                                "minimum": 1,
+                                "maximum": 1000000
+                              }
+                            },
+                            "required": [
+                              "id",
+                              "minCases"
+                            ],
+                            "additionalProperties": false
+                          }
+                        }
+                      },
+                      "required": [
+                        "gate",
+                        "artifacts",
+                        "minCases"
+                      ],
+                      "additionalProperties": false
+                    }
+                  },
+                  "gaps": {
+                    "type": "string",
+                    "minLength": 3,
+                    "maxLength": 2000
+                  }
+                },
+                "required": [
+                  "oracle",
+                  "crossChecks",
+                  "sets",
+                  "gaps"
+                ],
+                "additionalProperties": false
+              },
               "hard": {
                 "default": false,
                 "type": "boolean"