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

package/lib/storage/document.d.ts

@@ -211,7 +211,7 @@ export declare class DocumentView {
         activeRunId?: string | undefined;
         resultSha?: string | undefined;
         failure?: string | undefined;
-        failureKind?: "gate" | "unknown" | "review" | "environment" | "cancelled" | "timeout" | "provider-auth" | "stale-base" | "empty-result" | "scope-violation" | "review-protocol" | "merge" | "budget" | undefined;
+        failureKind?: "gate" | "unknown" | "review" | "environment" | "cancelled" | "timeout" | "provider-auth" | "stale-base" | "empty-result" | "unfinished" | "scope-violation" | "review-protocol" | "merge" | "budget" | "needs-lead" | undefined;
         failureFingerprint?: string | undefined;
         approvedAt?: string | undefined;
         approvedDigest?: string | undefined;
@@ -311,6 +311,7 @@ export declare class DocumentView {
             retryRun?: string | undefined;
             reason?: string | undefined;
         }[] | undefined;
+        neutralFailures?: number | undefined;
     } | undefined;
     works(graphId?: string): {
         id: string;
@@ -358,7 +359,7 @@ export declare class DocumentView {
         activeRunId?: string | undefined;
         resultSha?: string | undefined;
         failure?: string | undefined;
-        failureKind?: "gate" | "unknown" | "review" | "environment" | "cancelled" | "timeout" | "provider-auth" | "stale-base" | "empty-result" | "scope-violation" | "review-protocol" | "merge" | "budget" | undefined;
+        failureKind?: "gate" | "unknown" | "review" | "environment" | "cancelled" | "timeout" | "provider-auth" | "stale-base" | "empty-result" | "unfinished" | "scope-violation" | "review-protocol" | "merge" | "budget" | "needs-lead" | undefined;
         failureFingerprint?: string | undefined;
         approvedAt?: string | undefined;
         approvedDigest?: string | undefined;
@@ -458,6 +459,7 @@ export declare class DocumentView {
             retryRun?: string | undefined;
             reason?: string | undefined;
         }[] | undefined;
+        neutralFailures?: number | undefined;
     }[];
     attempt(id: string): {
         id: string;
@@ -519,7 +521,7 @@ export declare class DocumentView {
                 excluded?: {
                     runId: string;
                     status: string | null;
-                    reason: "not-started" | "legacy-unconfirmed" | "foreign-scope" | "unknown-status" | "unfinished" | "abandoned";
+                    reason: "unfinished" | "not-started" | "legacy-unconfirmed" | "foreign-scope" | "unknown-status" | "abandoned";
                 }[] | undefined;
                 excludedTotal?: number | undefined;
                 invalid?: number | undefined;
@@ -613,6 +615,19 @@ export declare class DocumentView {
                 coverage?: string[] | undefined;
             } | undefined;
             checks?: string | undefined;
+            alreadySatisfied?: {
+                gates: string[];
+                evidence: string;
+                basis?: {
+                    kind: "contract";
+                    gates: string[];
+                } | {
+                    kind: "dependency";
+                    workId: string;
+                    sha: string;
+                    paths: string[];
+                } | undefined;
+            } | undefined;
         }[];
         model?: string | undefined;
         reviewerModel?: string | undefined;
@@ -625,7 +640,7 @@ export declare class DocumentView {
         integrationSha?: string | undefined;
         error?: string | undefined;
         blocked?: boolean | undefined;
-        failureKind?: "gate" | "unknown" | "review" | "environment" | "cancelled" | "timeout" | "provider-auth" | "stale-base" | "empty-result" | "scope-violation" | "review-protocol" | "merge" | "budget" | undefined;
+        failureKind?: "gate" | "unknown" | "review" | "environment" | "cancelled" | "timeout" | "provider-auth" | "stale-base" | "empty-result" | "unfinished" | "scope-violation" | "review-protocol" | "merge" | "budget" | "needs-lead" | undefined;
         failureFingerprint?: string | undefined;
         requiredGates?: string[] | undefined;
         consumers?: {
@@ -691,6 +706,12 @@ export declare class DocumentView {
         }[] | undefined;
         properties?: string[] | undefined;
         unboundProperties?: string[] | undefined;
+        interrupted?: "shutdown" | undefined;
+        inputClasses?: string[] | undefined;
+        classified?: {
+            property: string;
+            inputClass: string;
+        }[] | undefined;
         episodeBasis?: string | undefined;
         implementationBasis?: string | undefined;
         reusedFrom?: {
@@ -709,7 +730,7 @@ export declare class DocumentView {
             kind: "candidate" | "unfinished";
             applied: boolean;
             files: string[];
-            reason?: "gate" | "unknown" | "review" | "environment" | "cancelled" | "timeout" | "provider-auth" | "stale-base" | "empty-result" | "scope-violation" | "review-protocol" | "merge" | "budget" | undefined;
+            reason?: "gate" | "unknown" | "review" | "environment" | "cancelled" | "timeout" | "provider-auth" | "stale-base" | "empty-result" | "unfinished" | "scope-violation" | "review-protocol" | "merge" | "budget" | "needs-lead" | undefined;
             respecified?: boolean | undefined;
         } | undefined;
         callsRecorded?: true | undefined;
@@ -810,7 +831,7 @@ export declare class DocumentView {
                 excluded?: {
                     runId: string;
                     status: string | null;
-                    reason: "not-started" | "legacy-unconfirmed" | "foreign-scope" | "unknown-status" | "unfinished" | "abandoned";
+                    reason: "unfinished" | "not-started" | "legacy-unconfirmed" | "foreign-scope" | "unknown-status" | "abandoned";
                 }[] | undefined;
                 excludedTotal?: number | undefined;
                 invalid?: number | undefined;
@@ -904,6 +925,19 @@ export declare class DocumentView {
                 coverage?: string[] | undefined;
             } | undefined;
             checks?: string | undefined;
+            alreadySatisfied?: {
+                gates: string[];
+                evidence: string;
+                basis?: {
+                    kind: "contract";
+                    gates: string[];
+                } | {
+                    kind: "dependency";
+                    workId: string;
+                    sha: string;
+                    paths: string[];
+                } | undefined;
+            } | undefined;
         }[];
         model?: string | undefined;
         reviewerModel?: string | undefined;
@@ -916,7 +950,7 @@ export declare class DocumentView {
         integrationSha?: string | undefined;
         error?: string | undefined;
         blocked?: boolean | undefined;
-        failureKind?: "gate" | "unknown" | "review" | "environment" | "cancelled" | "timeout" | "provider-auth" | "stale-base" | "empty-result" | "scope-violation" | "review-protocol" | "merge" | "budget" | undefined;
+        failureKind?: "gate" | "unknown" | "review" | "environment" | "cancelled" | "timeout" | "provider-auth" | "stale-base" | "empty-result" | "unfinished" | "scope-violation" | "review-protocol" | "merge" | "budget" | "needs-lead" | undefined;
         failureFingerprint?: string | undefined;
         requiredGates?: string[] | undefined;
         consumers?: {
@@ -982,6 +1016,12 @@ export declare class DocumentView {
         }[] | undefined;
         properties?: string[] | undefined;
         unboundProperties?: string[] | undefined;
+        interrupted?: "shutdown" | undefined;
+        inputClasses?: string[] | undefined;
+        classified?: {
+            property: string;
+            inputClass: string;
+        }[] | undefined;
         episodeBasis?: string | undefined;
         implementationBasis?: string | undefined;
         reusedFrom?: {
@@ -1000,7 +1040,7 @@ export declare class DocumentView {
             kind: "candidate" | "unfinished";
             applied: boolean;
             files: string[];
-            reason?: "gate" | "unknown" | "review" | "environment" | "cancelled" | "timeout" | "provider-auth" | "stale-base" | "empty-result" | "scope-violation" | "review-protocol" | "merge" | "budget" | undefined;
+            reason?: "gate" | "unknown" | "review" | "environment" | "cancelled" | "timeout" | "provider-auth" | "stale-base" | "empty-result" | "unfinished" | "scope-violation" | "review-protocol" | "merge" | "budget" | "needs-lead" | undefined;
             respecified?: boolean | undefined;
         } | undefined;
         callsRecorded?: true | undefined;

package/lib/verification/acceptance.js

@@ -20,7 +20,8 @@ export function propertyGates(order, contracts) {
         const found = obligationOf(contracts, id);
         if (!found)
             return { problem: `свойство ${id} не объявлено в договорах поручения` };
-        byGate.set(found.gate, [...(byGate.get(found.gate) ?? []), id]);
+        for (const gate of found.gates)
+            byGate.set(gate, [...(byGate.get(gate) ?? []), id]);
     }
     return { byGate };
 }

package/lib/verification/already-satisfied.d.ts

@@ -0,0 +1,44 @@
+import type { AlreadySatisfied, ContractDocument, EvidenceRecord, GatePolicy } from '../contracts/index.ts';
+/** Gates договоров проверки поручения. */
+export declare const contractCheckGates: (contracts: ContractDocument[]) => string[];
+/**
+ * Механическое основание считать работу поручения уже сделанной без изменений.
+ * `contract` — договор проверки поручения: его gates в области задачи, и
+ * reviewer на них сослался. `dependency` — зависимость поручения своим
+ * кандидатом (`sha`) изменила файлы его области записи (`paths`): работу
+ * сделала она. Записывает controller, а не reviewer.
+ */
+export type AlreadySatisfiedBasis = NonNullable<NonNullable<EvidenceRecord['alreadySatisfied']>['basis']>;
+declare const within: (path: string, prefixes: string[]) => boolean;
+export interface AlreadySatisfiedInput {
+    /** Gates области задачи (исполненные попыткой). */
+    scope: Pick<GatePolicy, 'id' | 'kind'>[];
+    /** Gates договоров проверки поручения (все, а не только в области). */
+    contractGates: string[];
+    writeScope: string[];
+    dependsOn: string[];
+    claim: AlreadySatisfied | undefined;
+    /** Основание по зависимости, найденное controller (или записанное им). */
+    dependency?: Extract<AlreadySatisfiedBasis, {
+        kind: 'dependency';
+    }>;
+}
+export type AlreadySatisfiedVerdict = {
+    ok: true;
+    basis: AlreadySatisfiedBasis;
+} | {
+    ok: false;
+    kind: 'empty-result' | 'needs-lead';
+    problem: string;
+};
+/**
+ * Правило «приёмка уже выполнена» — одно для ревью попытки и для
+ * `engine.finish`. Подтверждение reviewer необходимо, но не достаточно:
+ * зелёный общий gate на базе не доказывает, что новая работа есть (её тестов
+ * ещё нет). Достаточно одного из механических оснований: договор проверки
+ * поручения, все gates которого в области задачи и названы reviewer, или
+ * зависимость, изменившая область записи поручения. Без основания — решение
+ * ведущего (`needs-lead`), а не `done`.
+ */
+export declare function alreadySatisfiedVerdict(input: AlreadySatisfiedInput): AlreadySatisfiedVerdict;
+export { within as withinWriteScope };

package/lib/verification/already-satisfied.js

@@ -0,0 +1,49 @@
+import { obligationGates } from "./checks.js";
+/** Gates договоров проверки поручения. */
+export const contractCheckGates = (contracts) => contracts.flatMap((c) => c.checks ? c.checks.obligations.flatMap((o) => obligationGates(c.checks, o)) : []);
+const within = (path, prefixes) => prefixes.some((p) => p === '.' || path === p || path.startsWith(p.endsWith('/') ? p : p + '/'));
+/**
+ * Правило «приёмка уже выполнена» — одно для ревью попытки и для
+ * `engine.finish`. Подтверждение reviewer необходимо, но не достаточно:
+ * зелёный общий gate на базе не доказывает, что новая работа есть (её тестов
+ * ещё нет). Достаточно одного из механических оснований: договор проверки
+ * поручения, все gates которого в области задачи и названы reviewer, или
+ * зависимость, изменившая область записи поручения. Без основания — решение
+ * ведущего (`needs-lead`), а не `done`.
+ */
+export function alreadySatisfiedVerdict(input) {
+    const empty = (problem) => ({
+        ok: false,
+        kind: 'empty-result',
+        problem,
+    });
+    const lead = (problem) => ({ ok: false, kind: 'needs-lead', problem });
+    const { claim } = input;
+    if (!claim)
+        return empty('ответ не содержит alreadySatisfied');
+    if (claim.evidence.replace(/\s+/g, '').length < 20)
+        return empty('основание alreadySatisfied.evidence короче 20 знаков');
+    const scope = new Set(input.scope.map((g) => g.id));
+    const outside = claim.gates.filter((g) => !scope.has(g));
+    if (outside.length)
+        return empty('названы gates вне области задачи: ' + outside.join(', '));
+    if (!claim.gates.some((id) => input.scope.some((g) => g.id === id && g.kind === 'test')))
+        return empty('не назван ни один test gate');
+    const contract = [...new Set(input.contractGates)];
+    const unscoped = contract.filter((g) => !scope.has(g));
+    if (unscoped.length)
+        return lead('проверки договора поручения вне области задачи: ' + unscoped.join(', '));
+    const missing = contract.filter((g) => !claim.gates.includes(g));
+    if (missing.length)
+        return empty('не названы проверки договора поручения: ' + missing.join(', '));
+    if (contract.length)
+        return { ok: true, basis: { kind: 'contract', gates: contract } };
+    const d = input.dependency;
+    if (d &&
+        input.dependsOn.includes(d.workId) &&
+        d.paths.length > 0 &&
+        d.paths.every((p) => within(p, input.writeScope)))
+        return { ok: true, basis: d };
+    return lead('нет механического основания: у поручения нет договора проверки, и ни одна его зависимость не меняла его область записи');
+}
+export { within as withinWriteScope };

package/lib/verification/checks.d.ts

@@ -8,9 +8,30 @@ import type { CheckManifest } from './property.ts';
 export declare function contractDocuments(order: Pick<WorkOrder, 'contracts'>, view: ExecutionView): ContractDocument[];
 type Declared = {
     contract: ContractDocument;
+    /** Первый gate обязательства (у обязательства без `gates` — gate договора). */
     gate: string;
+    gates: string[];
     obligation: Obligation;
 };
+/** Gates обязательства: свои `gates` или gate договора. */
+export declare function obligationGates(declaration: Pick<CheckDeclaration, 'gate'>, o: Obligation): string[];
+/** Обязательство проверяется закреплёнными эталонными наборами. */
+export declare const isReference: (o: Obligation) => boolean;
+/**
+ * Файлы эталонных наборов договоров поручения (в репозитории `repositoryId`).
+ * Ответы наборов лежат в рабочем дереве: реализация, которая читает их или
+ * повторяет их ответы, прошла бы каждый набор, ничего не решив.
+ */
+export declare function referenceSetFiles(contracts: ContractDocument[], repositoryId?: string): string[];
+/**
+ * Какой файл набора называет изменённый файл: имя файла набора (и, значит,
+ * его путь) целым токеном внутри строкового литерала. Комментарии и файлы без кода не
+ * считаются — упоминание набора в них ничего не читает. Имя, собранное во
+ * время исполнения, так не видно: это остаётся ревью кода.
+ */
+export declare function setFileReference(path: string, text: string, sets: string[]): string | undefined;
+/** Подсказка writer или reviewer кода о файлах эталонных наборов; пусто — их нет. */
+export declare function referenceCodeNote(files: string[], review: boolean): string;
 /** Основание случаев корпуса: закреплённые файлы, gate и смысл обязательств. */
 export declare function suiteBasis(contract: ContractDocument): string;
 /**
@@ -38,6 +59,13 @@ export declare function declarationProblems(declaration: CheckDeclaration, conte
         digest: string;
     } | undefined;
 }): string[];
+/**
+ * Подсказка reviewer контракта об эталонных обязательствах: что наборы
+ * доказывают, чего — нет (`gaps`), чем сверен эталон. Пустая строка — таких
+ * обязательств нет. Reviewer видит пределы способа рядом с самим договором,
+ * а не выводит их из длинного описания.
+ */
+export declare function referenceNote(declaration: CheckDeclaration | undefined): string;
 /**
  * Свойства, объявленные поручением, существуют в его договорах и исполняются
  * его генеративными gates. Поручение без `properties` — прежний уровень.