devcontour-harness 0.0.0-stage → 0.1.0-alpha.11

package/lib/contracts/published.js

@@ -0,0 +1,40 @@
+import { workGraphSchema, workOrderSchema } from "./work.js";
+import { executionPolicySchema } from "./policy.js";
+import { contextSnapshotSchema } from "./context.js";
+import { jointVerificationSchema, resultEnvelopeSchema, runResultSchema } from "./result.js";
+import { runEventSchema } from "./events.js";
+import { reviewRecordSchema } from "./review.js";
+import { executionDocumentSchema } from "./execution.js";
+import { contractDocumentSchema } from "./checks.js";
+import { stackProfileSchema } from "./profiles.js";
+import { projectManifestSchema } from "./project.js";
+import { stopDiagnosisSchema } from "./diagnosis.js";
+import { planDraftSchema } from "./planning.js";
+/**
+ * Схемы, публикуемые как JSON Schema (`schemas/<имя>.schema.json`).
+ *
+ * JSON Schema выражает всё, что относится к одному значению: типы,
+ * обязательность, закрытость объектов, пределы, регулярные выражения путей
+ * и refs, варианты исходов. Связи *между* значениями — граф без циклов и
+ * неизвестных зависимостей, согласованность политики, связь поручений с
+ * политикой, совпадение содержимого контекста с digests — проверяют
+ * `graphIssues`, `policyIssues`, `crossIssues`, `contextIssues` и CLI
+ * `harness validate`; JSON Schema их не заменяет.
+ */
+export const publishedSchemas = {
+    'work-order': workOrderSchema,
+    'work-graph': workGraphSchema,
+    'execution-policy': executionPolicySchema,
+    'context-snapshot': contextSnapshotSchema,
+    'contract-document': contractDocumentSchema,
+    'run-result': runResultSchema,
+    'result-envelope': resultEnvelopeSchema,
+    'run-event': runEventSchema,
+    'review-record': reviewRecordSchema,
+    'joint-verification': jointVerificationSchema,
+    'execution-document': executionDocumentSchema,
+    'stack-profile': stackProfileSchema,
+    'project-manifest': projectManifestSchema,
+    'stop-diagnosis': stopDiagnosisSchema,
+    'plan-draft': planDraftSchema,
+};

package/lib/contracts/repair-policy.d.ts

@@ -0,0 +1,31 @@
+import type { FailureKind } from './execution.ts';
+export interface RepairRule {
+    /** `retry` — новая попытка той же задачи; `stop` — звать человека. */
+    action: 'retry' | 'stop';
+    /**
+     * Сколько раз один и тот же отпечаток разрешено чинить автоматически.
+     * Исчерпан — гипотез больше нет, и цикл останавливается с этой причиной.
+     */
+    repeats: number;
+    /** Причина, которую увидит человек, когда цикл остановится. */
+    explain: string;
+    /**
+     * Отказ повторится на любой задаче, а не только на этой: выдача
+     * останавливается целиком, иначе очередь переберёт задачи одну за другой и
+     * сожжёт бюджет попыток каждой на одной и той же внешней причине.
+     *
+     * Этим же свойством причина снимается: починив её, восстановление убирает
+     * свою запись из списка блокировок, а выдача возвращается, только когда не
+     * осталось ни одной. Решать это по тексту сообщения нельзя — замечание
+     * ревью про «401 Unauthorized» в разрабатываемом приложении так становилось
+     * отказом провайдера и останавливало работу насовсем.
+     */
+    blocksQueue?: boolean;
+}
+/**
+ * Что разрешено делать с каждым классом. Таблица намеренно узкая: повтор и
+ * остановка. Повтор безопасен, потому что прошлый отказ и замечания ревью
+ * попадают в подсказку следующей попытки, а бюджет попыток задачи не растёт —
+ * сброс бюджета остаётся действием человека.
+ */
+export declare const repairPolicy: Record<FailureKind, RepairRule>;

package/lib/contracts/repair-policy.js

@@ -0,0 +1,77 @@
+// Таблица восстановления без node:* — её читают и движок, и чистые проекции
+// (`devcontour-harness/projections`, доступные браузеру).
+/**
+ * Что разрешено делать с каждым классом. Таблица намеренно узкая: повтор и
+ * остановка. Повтор безопасен, потому что прошлый отказ и замечания ревью
+ * попадают в подсказку следующей попытки, а бюджет попыток задачи не растёт —
+ * сброс бюджета остаётся действием человека.
+ */
+export const repairPolicy = {
+    'provider-auth': {
+        action: 'stop',
+        repeats: 0,
+        blocksQueue: true,
+        explain: 'Провайдер отказал: нет кредитов, исчерпан лимит сессии или частоты, либо runtime не авторизован. Это вне контура: очередь стоит до устранения или сброса лимита, повтор сейчас потратил бы бюджет впустую.',
+    },
+    environment: {
+        action: 'retry',
+        repeats: 1,
+        blocksQueue: true,
+        explain: 'Окружение не дало исполнителю работать. Однократный повтор оправдан: обрыв чаще всего разовый. Второй такой же отказ — неисправность окружения, её устраняет человек.',
+    },
+    timeout: {
+        action: 'retry',
+        repeats: 1,
+        explain: 'Попытка исчерпала время. Второй такой же исход означает, что задача не помещается в отведённый предел: её нужно разделить или поднять предел осознанно.',
+    },
+    'stale-base': {
+        action: 'stop',
+        repeats: 0,
+        explain: 'База прогонов отстала от рабочей ветки. Перенос базы меняет то, что увидят все исполнители, и выполняется отдельной командой base-update при остановленной очереди.',
+    },
+    'empty-result': {
+        action: 'retry',
+        repeats: 1,
+        explain: 'Исполнитель отчитался о выполнении, не изменив ни файла. Повтор получает этот отказ в подсказке; второй такой же означает, что задача поставлена неверно или невыполнима в своей области.',
+    },
+    'scope-violation': {
+        action: 'retry',
+        repeats: 1,
+        explain: 'Изменения вышли за область задачи или роли. Повтор получает точный список; второй такой же означает, что область задачи не соответствует работе.',
+    },
+    gate: {
+        action: 'retry',
+        repeats: 2,
+        explain: 'Настроенная проверка не прошла. Повторы получают вывод проверки; когда один и тот же провал держится, у исполнителя нет новой гипотезы.',
+    },
+    review: {
+        action: 'retry',
+        repeats: 2,
+        explain: 'Независимое ревью отклонило результат. Повторы получают замечания адресно; одно и то же замечание трижды означает, что исполнитель его не понимает.',
+    },
+    'review-protocol': {
+        action: 'stop',
+        repeats: 0,
+        explain: 'Ответ reviewer нарушил протокол ревью (схема или переходы находок), и разрешённые повторы reviewer исчерпаны. Это не замечание к коду: новая реализация writer ничего не исправит. Причина и путь поля — в результате; продолжение — решение человека.',
+    },
+    merge: {
+        action: 'retry',
+        repeats: 1,
+        explain: 'Слияние с веткой интеграции не сошлось. Повтор ответвляется от нового состояния базы; второй такой же конфликт разбирает человек.',
+    },
+    budget: {
+        action: 'stop',
+        repeats: 0,
+        explain: 'Бюджет расходов или времени исчерпан либо не определён (есть вызовы с неизвестной стоимостью). Повтор потратил бы ещё; продолжить можно, только осознанно подняв предел в конфигурации или задав политику для неизвестной цены.',
+    },
+    cancelled: {
+        action: 'stop',
+        repeats: 0,
+        explain: 'Работа остановлена человеком. Отмена не превращается в повтор.',
+    },
+    unknown: {
+        action: 'stop',
+        repeats: 0,
+        explain: 'Класс отказа не определён. Автоматическое восстановление вслепую дороже и опаснее остановки.',
+    },
+};