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

package/README.md

@@ -5,7 +5,7 @@ Headless-движок исполнения инженерных поручени
 интеграция с принятой веткой через compare-and-swap и машинный результат с SHA
 и доказательствами.
 
-> Статус: `0.1.0-alpha.13` — предварительный выпуск (alpha). Договоры
+> Статус: `0.1.0-alpha.16` — предварительный выпуск (alpha). Договоры
 > `v1alpha1` могут измениться между alpha-версиями; закрепляйте точную версию.
 > Файл → ревью плана → кандидат → интеграция → принятие → результат JSON, с
 > ограниченным восстановлением, повторным использованием кандидата, бюджетами,
@@ -28,7 +28,7 @@ Headless-движок исполнения инженерных поручени
 Из npm — точная версия (воспроизводимо) или последняя alpha по тегу:
 
 ```sh
-npm install --save-exact devcontour-harness@0.1.0-alpha.13   # точная версия
+npm install --save-exact devcontour-harness@0.1.0-alpha.16   # точная версия
 # или: npm install --save-exact devcontour-harness@alpha     # текущая alpha
 npx harness --version
 ```
@@ -123,6 +123,36 @@ PASS» нет. Адаптеры хоста реализуют порты `Execut
 `devcontour-harness/schemas/<имя>.schema.json`. Декларации используют типы
 Node.js: TypeScript-потребителю нужен `@types/node` (или `skipLibCheck`).
 
+## Выпуск 0.1.0-alpha.16
+
+Отказ по файлу эталонного набора — только по строковому литералу, без ложных
+отказов на комментариях и похожих именах; reviewer контракта видит минимумы
+семейств. Подробно — [заметки выпуска](docs/release-notes/0.1.0-alpha.16.md);
+alpha.14 и alpha.15 — локальные выпуски, в npm не публиковались.
+
+## Выпуск 0.1.0-alpha.15
+
+Эталонные наборы защищены от подгонки. Подробно —
+[заметки выпуска](docs/release-notes/0.1.0-alpha.15.md); alpha.14 — локальный
+выпуск, в npm не публиковался.
+
+- Writer и reviewer кода знают файлы эталонных наборов; кандидат, чей
+  изменённый файл называет файл набора, отклоняется до gates.
+- `crossChecks[].artifacts`: закреплённый скрипт или журнал сверки эталона.
+- Обязательство, которое поручение выбрать не может, отклоняется сразу; ID
+  testcase node:test (`test.<имя>`) описан и подсказан в отказе.
+
+## Выпуск 0.1.0-alpha.14
+
+Проверка по закреплённым эталонным наборам. Подробно —
+[заметки выпуска](docs/release-notes/0.1.0-alpha.14.md).
+
+- `verification: "reference"` в договоре проверки: обещание проверяется
+  наборами ответов независимого эталона, закреплёнными артефактами контракта;
+  gate без генератора подтверждает отчётом свою долю входов и семейств.
+- `obligations[].gates`: обязательство исполняют несколько gates.
+- Reviewer контракта видит пределы наборов (`gaps`) и сверку эталона.
+
 ## Выпуск 0.1.0-alpha.13
 
 Controller mode для задач Relay и установка без лишних вопросов. Подробно —

package/docs/architecture.md

@@ -267,6 +267,12 @@ runtime-граф пакета.
   и файлы, не совпадающие с целевой веткой, отклоняются до вызова reviewer.
   Поручение включает механизм полем `properties`; свойства, которых нет в его
   договорах или которые исполняет не генеративный gate, не согласуются.
+  Обязательство может назвать несколько gates (`gates`) и способ
+  `reference`: сверку с закреплёнными эталонными наборами вместо генератора.
+  Gate эталонных наборов получает путь отчёта свойств и без `property` и
+  обязан подтвердить свою долю входов и семейств; пределы наборов (`gaps`)
+  reviewer контракта видит отдельно
+  ([договор](contracts.md#способы-исполнения-обязательства-property-и-reference)).
   Генеративный gate получает seed controller (`DEVCONTOUR_SEED`, свой у
   попытки, фазы и gate), селектор свойств и закреплённый корпус; отчёт
   свойств читается при любом исходе из каталога вне worktree. Gate проходит,

package/docs/contracts.md

@@ -182,6 +182,106 @@ Git blob в репозитории `repositoryId`); `checks` — договор
 корпуса. Прошедший ревью документ хранится по digest (`contract-documents`):
 из него движок строит манифест генеративного gate поручения.
 
+#### Способы исполнения обязательства: `property` и `reference`
+
+Обязательство исполняют его gates: `obligations[].gates` (1–10 ID) или, без
+поля, `checks.gate`. Способ — `verification`:
+
+- `property` (поле не указано) — генеративная проверка, как прежде: каждый gate
+  обязательства генеративный (`gate.property`), отчёт свойств каждого
+  подтверждает полное покрытие обязательства (`coverage.minCases` и
+  семейства), корпус пополняет только gate договора;
+- `reference` — сверка с закреплёнными эталонными наборами. Ответы
+  независимого эталона (точный решатель, полный перебор, таблица DP)
+  получены заранее, сверены с другим способом и закреплены артефактами
+  контракта; gate сверяет с ними реализацию. Генератор не нужен, поэтому gate
+  может быть обычным test-gate без `property`.
+
+`reference` описывает:
+
+| Поле                                                            | Смысл                                                                                                                                                 |
+| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `oracle.description`, `oracle.limits`                           | эталон, его версия и пределы (время решения, что исключено из наборов)                                                                                |
+| `crossChecks[]` `{family, against, matches, total, artifacts?}` | сверка эталона с другим способом на семействе входов; `matches < total` — отказ; `artifacts` — закреплённый скрипт или журнал, воспроизводящий сверку |
+| `sets[]` `{gate, artifacts, minCases, families}`                | набор: gate, файлы набора (артефакты контракта), доля входов и семейств этого gate                                                                    |
+| `gaps`                                                          | чего наборы не доказывают: обобщение за пределы входов, классы вне наборов                                                                            |
+
+Структурные правила (`declarationProblems`, до вызова модели): у каждого gate
+обязательства есть набор, gate набора — среди gates обязательства, файлы
+наборов — артефакты контракта, сумма `sets[].minCases` не меньше
+`coverage.minCases`, сумма долей каждого семейства покрытия не меньше его
+`minCases`, семейства набора объявлены в покрытии и не превышают минимум
+набора, сверка эталона без расхождений, файлы сверки (`crossChecks[].artifacts`)
+— артефакты контракта; корпус у эталонного обязательства не включается.
+Требование генеративного gate к `reference` не применяется; остальные
+правила (`method`, бюджеты, spike) те же. Обязательство `property` любого
+обещания (и `invariant`, и `functional`) на gate без `property` отклоняется:
+поручение такое свойство выбрать не может (`orderPropertyProblems`), и
+договор был бы мёртвым.
+
+Доказательство — тот же отчёт свойств. Для gate, которому манифест поручения
+назначает эталонное свойство, controller задаёт путь отчёта
+(`DEVCONTOUR_PROPERTY_REPORT`) и селектор (`DEVCONTOUR_PROPERTIES`) и без
+`gate.property`. Запись манифеста эталонного свойства — доля этого gate:
+сумма `minCases` и семейств его наборов и `reference.artifacts` (файлы
+наборов); поле есть только у эталонных свойств, так что digest прежних
+манифестов не меняется. Gate проходит, только если отчёт называет свойство
+со статусом `passed`, числом проверенных входов и семейств не меньше доли и
+testcase с тем же ID в JUnit; зелёный JUnit и код 0 без отчёта — отказ
+(«Проверка по эталонным наборам не отчиталась»). Приёмка требует решающую
+запись обеих фаз с манифестом от каждого gate обязательства. Файлы наборов —
+артефакты контракта, поэтому попытка не может их изменить (защищённые пути).
+
+Reviewer контракта получает эталонные обязательства отдельно (`referenceNote`):
+эталон, сверку, наборы и `gaps`. Обещание, которое опирается только на
+`gaps`, без другого способа (генеративного свойства, инварианта,
+аналитического основания), — блокирующая находка. Сверка без `artifacts` —
+непроверенное утверждение автора, и reviewer оценивает её так.
+
+Ответы наборов лежат в рабочем дереве, поэтому реализация могла бы читать их
+или повторять их ответы и проходить каждый набор. Защита в два слоя:
+writer и reviewer кода получают список файлов наборов (`referenceSetFiles`,
+`referenceCodeNote`), и для reviewer чтение файлов наборов из кода
+реализации, вшитые ответы или особые случаи для входов наборов — блокирующая
+находка; controller отклоняет кандидата (`scope-violation`, до gates), если
+изменённый файл называет файл набора внутри строкового литерала (`'…'`,
+`"…"`, `` `…` ``): имя файла набора целым токеном — по краям нет буквы,
+цифры, `_`, `-` или `.`, так что путь и `../имя` совпадают, а `data.json` с
+набором `a.json` или `testcases.json` с `cases.json` — нет (`setFileReference`).
+Комментарии `//` и `/* */` и файлы без кода (`.md`, `.txt`, `.rst`, `.adoc`,
+каталог `docs/`) не проверяются. Тесты исполнителя, которые не артефакты
+контракта, проверяются тем же правилом: через них ответы тоже можно подать
+реализации. Остаточный риск: имя, собранное во время исполнения
+(`` `${name}-golden.json` ``), копия ответов без имени файла и обобщение,
+подогнанное под входы, механически не ловятся — их ловит ревью кода; строка
+кода, которая законно называет набор (не артефакт контракта), отклоняется.
+
+Пределы проверки долей: controller сверяет, что доли наборов покрывают
+общий минимум и минимумы семейств и что gate отчитался своей долей, но не
+сравнивает доли с размером файлов набора (сколько входов в нём на самом деле)
+и не проверяет, что входы различны. Reviewer контракта видит минимумы
+обязательства и семейств рядом с наборами (`referenceNote`) и оценивает это
+сам.
+
+#### ID testcase и отчёта
+
+Свойство, `testId` отчёта и testcase JUnit — один ID. ID testcase — это
+`classname.name` (без `classname` — `name`). Генератор отчёта задаёт
+`classname` по-своему: node:test (`--test-reporter=junit`) всегда пишет
+`classname="test"`, и тест `test('knapsack-optimal', …)` получает ID
+`test.knapsack-optimal` — таким должен быть и property ID; JUnit-отчёт
+собственного checker (как `harness.mjs` в примерах) пишет только `name`, и ID
+совпадает с именем. Если testcase с ID свойства нет, а есть
+`<classname>.<ID>`, отказ называет найденный ID.
+
+Совместимость: поля `gates`, `verification`, `reference` необязательны, договор
+без них разбирается, проверяется и даёт тот же манифест, digest и основание
+корпуса (`suiteBasis` включает новые поля, только когда они объявлены;
+`gates`, равные gate договора, — то же основание, что без поля, а digest
+документа контракта при этом другой).
+Версия договора остаётся `version: 1`; прежние версии harness договор с
+новыми полями отклоняют строгой схемой.
+
 ## Модель исполнения
 
 Схемы в `execution.ts` — то, что `ExecutionStore` хранит транзакционно:

package/docs/quickstart.md

@@ -13,7 +13,7 @@
 ```sh
 mkdir harness-demo && cd harness-demo
 npm init -y >/dev/null
-npm install --save-exact devcontour-harness@0.1.0-alpha.13
+npm install --save-exact devcontour-harness@0.1.0-alpha.16
 npx harness --version
 npx harness doctor
 ```

package/docs/release-notes/0.1.0-alpha.14.md

@@ -0,0 +1,69 @@
+# devcontour-harness 0.1.0-alpha.14
+
+> Локальный выпуск: в npm не публиковался. Его изменения вошли в
+> [0.1.0-alpha.15](0.1.0-alpha.15.md).
+
+Проверка по закреплённым эталонным наборам в договоре проверки и несколько
+gates у одного обязательства. Gates, `maxAttempts`, бюджеты попыток и
+повторов, правила находок, изоляция, принятие target ref и генеративная
+проверка (`property`) не менялись.
+
+## Что нового
+
+- **`verification: "reference"`.** Вычислительное обещание (оптимальность,
+  полнота, точность, производительность) можно проверить не генератором, а
+  наборами ответов независимого эталона, посчитанными заранее и закреплёнными
+  артефактами контракта. Обязательство описывает эталон и его пределы
+  (`oracle`), сверку эталона с другим способом (`crossChecks`: семейство,
+  способ, совпало из всего), наборы (`sets`: gate, файлы, доля входов и
+  семейств) и то, чего наборы не доказывают (`gaps`). Gate такого
+  обязательства — обычный test-gate без `property`
+  ([договор](../contracts.md#способы-исполнения-обязательства-property-и-reference)).
+- **`obligations[].gates`.** Обязательство называет свои gates (1–10); без
+  поля его исполняет `checks.gate`, как раньше. Генеративное обязательство
+  проверяет полное покрытие на каждом своём gate; эталонное — долю наборов
+  каждого gate.
+- **Доказательство доли.** Gate, которому манифест поручения назначает
+  эталонное свойство, получает путь отчёта свойств и селектор и без
+  `gate.property`. Отчёт обязан назвать свойство со статусом `passed` и
+  числом проверенных входов и семейств не меньше доли этого gate, JUnit —
+  testcase с тем же ID; зелёный JUnit и код 0 без отчёта — отказ gate.
+  Приёмка требует запись с манифестом от каждого gate обязательства.
+- **Структурные отказы до вызова модели:** gate обязательства без набора,
+  набор чужого gate, файл набора не среди артефактов контракта, доли наборов
+  меньше общего минимума или минимума семейства, семейство набора не из
+  покрытия, сверка эталона с расхождениями, корпус у эталонного
+  обязательства, корпус генеративного обязательства не на gate договора.
+- **Reviewer контракта** получает эталонные обязательства отдельно: эталон,
+  сверку, наборы и `gaps` (`referenceNote`). Обещание, которое опирается
+  только на `gaps`, — блокирующая находка.
+- Самопроверка исполнителя запускает и gates эталонных наборов.
+
+## Изменения договора
+
+Добавления в `checkDeclarationSchema`: `obligations[].gates`,
+`obligations[].verification` (`property` | `reference`) и
+`obligations[].reference`; в `CheckManifest.properties[]` — `reference`
+(только у эталонных свойств). Новые экспорты: `obligationGates`,
+`isReference`, `referenceNote`, `expectsReference`, `referenceSchema`. Без
+новых полей разбор, отказы, манифест, его digest и основание корпуса
+(`suiteBasis`) те же, что в alpha.13. Сообщение «… не генеративный (нет
+property)» теперь называется для каждого gate генеративного обязательства.
+
+## Совместимость
+
+Формат состояния тот же. Договор с новыми полями alpha.13 и раньше не
+принимают (строгая схема): состояние с таким контрактом откатывается только
+через копию. Обновление и откат — по [upgrade](../upgrade.md).
+
+## Проверка выпуска
+
+`npm run check` (lint, typecheck, schemas, build, весь набор тестов, package
+smoke из установленного архива) на macOS arm64, Node.js 24.3.
+`tests/reference.test.ts`: структурные отказы и принятый договор на gates без
+генератора, манифест доли gate, прежние манифест и основание корпуса
+договора без новых полей, согласование поручения, подсказка reviewer,
+самопроверка; на fixture runtime — два gate эталонных наборов доводят
+поручение до приёмки, недобор входов при зелёном JUnit и коде 0, отсутствие
+отчёта и расхождение с эталоном — отказ gate. Каждая новая проверка падает на
+своём мутанте реализации. Живые модели не вызывались.

package/docs/release-notes/0.1.0-alpha.15.md

@@ -0,0 +1,62 @@
+# devcontour-harness 0.1.0-alpha.15
+
+> Локальный выпуск: в npm не публиковался. Его изменения вошли в
+> [0.1.0-alpha.16](0.1.0-alpha.16.md).
+
+Защита эталонной проверки от подгонки под наборы, закреплённые файлы сверки
+эталона и ID testcase node:test. Включает всё из
+[0.1.0-alpha.14](0.1.0-alpha.14.md): alpha.14 — локальный выпуск, в npm не
+публиковался; первая публикуемая версия с эталонными наборами — alpha.15.
+Gates, `maxAttempts`, бюджеты попыток и повторов, правила находок, изоляция,
+принятие target ref и формат состояния не менялись.
+
+## Что нового
+
+- **Ответы наборов не подсказка реализации.** Writer и reviewer кода получают
+  список файлов эталонных наборов поручения. Для reviewer чтение их из кода
+  реализации, вшитые ответы и особые случаи для входов наборов — блокирующая
+  находка. Controller отклоняет кандидата до gates (`scope-violation`
+  «Реализация ссылается на файлы эталонных наборов»), если изменённый файл
+  содержит путь или имя файла набора. Имя, собранное во время исполнения, и
+  копия ответов без имени файла механически не ловятся — их ловит ревью кода
+  ([договор](../contracts.md#способы-исполнения-обязательства-property-и-reference)).
+- **`crossChecks[].artifacts`.** Сверка эталона может ссылаться на
+  закреплённый скрипт или журнал, который её воспроизводит; файлы обязаны
+  быть артефактами контракта. Reviewer контракта оценивает сверку без них
+  как непроверенное утверждение автора.
+- **Мёртвые обязательства.** Обязательство `property` любого обещания на
+  gate без `property` отклоняется до вызова модели: поручение его выбрать не
+  может. Прежде так отклонялись только вычислительные обещания.
+- **ID testcase.** Отказ «testcase X отсутствует в JUnit» называет найденный
+  `<classname>.X` (node:test пишет `classname="test"`, и ID свойства для него
+  — `test.<имя теста>`); правило описано в
+  [договоре](../contracts.md#id-testcase-и-отчёта).
+- Сообщение отказа gate, где генеративные и эталонные свойства вместе:
+  «Проверка свойств и эталонных наборов …».
+- `gates` обязательства, равные `checks.gate`, дают то же основание корпуса,
+  что и без поля.
+
+## Изменения договора
+
+Добавления: `reference.crossChecks[].artifacts` (1–10 путей), экспорты
+`referenceSetFiles` и `referenceCodeNote`. Изменение отказа: обязательство
+`property` с необязательным обещанием (`functional`, `invariant`, `other`) на
+gate без `property` теперь — структурный отказ договора (текст «… не
+генеративный (нет property) — поручение не сможет выбрать это свойство; …»;
+у вычислительных обещаний текст тоже дополнен). Договор без новых полей даёт
+тот же манифест, digest и основание корпуса.
+
+## Совместимость
+
+Формат состояния тот же. Договор с новыми полями alpha.13 и раньше не
+принимают (строгая схема). Обновление и откат — по [upgrade](../upgrade.md).
+
+## Проверка выпуска
+
+`npm run check` на macOS arm64, Node.js 24.3. `tests/reference.test.ts`
+(14 тестов): к проверкам alpha.14 добавлены отказ кандидата, читающего файл
+набора, список наборов в запросах writer и reviewer, testcase с другим ID,
+настоящий JUnit node:test (`test.<имя>`), файлы сверки, мёртвое
+обязательство-инвариант, основание корпуса при `gates` равных gate договора.
+Каждая новая проверка падает на своём мутанте (29 из 29). Живые модели не
+вызывались.

package/docs/release-notes/0.1.0-alpha.16.md

@@ -0,0 +1,36 @@
+# devcontour-harness 0.1.0-alpha.16
+
+Проверка файлов эталонных наборов без ложных отказов. Включает всё из
+[0.1.0-alpha.15](0.1.0-alpha.15.md) и [0.1.0-alpha.14](0.1.0-alpha.14.md):
+обе — локальные выпуски, в npm не публиковались; первая публикуемая версия с
+эталонными наборами — alpha.16. Gates, `maxAttempts`, бюджеты попыток и
+повторов, правила находок, изоляция, принятие target ref и формат состояния
+не менялись.
+
+## Что нового
+
+- **Отказ по файлу набора — только по строковому литералу.** В alpha.15
+  кандидат отклонялся, если изменённый файл где угодно содержал путь или имя
+  файла набора: комментарий, свой тест исполнителя, `data.json` при наборе
+  `a.json`. Теперь имя файла набора должно стоять целым токеном внутри
+  строкового литерала (`'…'`, `"…"`, `` `…` ``); комментарии `//` и `/* */` и
+  файлы без кода (`.md`, `.txt`, `.rst`, `.adoc`, `docs/`) не проверяются.
+  Тесты исполнителя проверяются тем же правилом. Ложный отказ тратил попытку.
+- **Reviewer контракта видит минимумы.** `referenceNote` показывает общий
+  минимум обязательства, минимумы семейств и доли семейств каждого набора.
+  Сравнения долей с фактическим размером файлов набора нет — это описано в
+  [договоре](../contracts.md#способы-исполнения-обязательства-property-и-reference).
+- Новый экспорт `setFileReference(path, text, sets)`.
+
+## Совместимость
+
+Формат состояния и договор те же, что в alpha.15. Обновление и откат — по
+[upgrade](../upgrade.md).
+
+## Проверка выпуска
+
+`npm run check` на macOS arm64, Node.js 24.3. `tests/reference.test.ts`
+(15 тестов): комментарий, текст, свой тест без литерала, похожие имена и
+непарная кавычка — без отказа; литеральный путь, `'golden-a.json'`, путь в
+шаблоне, `../имя` и импорт из теста исполнителя — отказ. 36 из 36 мутантов
+реализации обнаружены. Живые модели не вызывались.

package/docs/upgrade.md

@@ -21,20 +21,21 @@
 
 ## Матрица форматов
 
-| Состояние, записанное…                                                         | Читает 0.1.0-alpha.1     | Читает 0.1.0-alpha.2     | Читает 0.1.0-alpha.6    | Читает 0.1.0-alpha.7 | Читает 0.1.0-alpha.8 | Читает 0.1.0-alpha.9 | Читает 0.1.0-alpha.10 | Читает 0.1.0-alpha.11 | Читает 0.1.0-alpha.12 | Читает 0.1.0-alpha.13 | Пишет поверх | Примечание                                                                                                                                                                                 |
-| ------------------------------------------------------------------------------ | ------------------------ | ------------------------ | ----------------------- | -------------------- | -------------------- | -------------------- | --------------------- | --------------------- | --------------------- | --------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| standalone `stateVersion: 1` версией alpha.1                                   | да                       | да                       | да                      | да                   | да                   | да                   | да                    | да                    | да                    | да                    | да           | одна база SQLite: документ, события, локальные записи                                                                                                                                      |
-| хост, центральная база                                                         | да (через адаптер)       | да (через адаптер)       | да (через адаптер)      | да (через адаптер)   | да (через адаптер)   | да (через адаптер)   | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да           | данные не переносятся; новые поля необязательны                                                                                                                                            |
-| хост, базы компонентов                                                         | да (через адаптер)       | да (через адаптер)       | да (через адаптер)      | да (через адаптер)   | да (через адаптер)   | да (через адаптер)   | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да           | нужна копия всех баз при остановленных writers                                                                                                                                             |
-| alpha.2 после штатной остановки controller                                     | да                       | да                       | да                      | да                   | да                   | да                   | да                    | да                    | да                    | да                    | да           | роль controller снята — нового поля в состоянии нет                                                                                                                                        |
-| alpha.2 с живой или брошенной ролью controller                                 | **нет**, отказ до записи | да                       | да                      | да                   | да                   | да                   | да                    | да                    | да                    | да                    | —            | роль хранит `engineVersion`; строгая схема alpha.1 его не знает → откат через копию                                                                                                        |
-| alpha.4 с совместной проверкой                                                 | **нет**, отказ до записи | **нет**, отказ до записи | да                      | да                   | да                   | да                   | да                    | да                    | да                    | да                    | —            | проверка хранит `engineVersion`; прежние версии его не знают → откат через копию                                                                                                           |
-| alpha.6 standalone с записями ревью нового протокола или доставкой `uncertain` | **нет**, отказ до записи | **нет**, отказ до записи | да                      | да                   | да                   | да                   | да                    | да                    | да                    | да                    | —            | `reviewRound`, `findings[].id/status`, статус доставки `uncertain`; alpha.4/alpha.5 отказывают `STATE_VERSION_UNSUPPORTED` до записи → откат через копию                                   |
-| alpha.6, хост DevContour (адаптер alpha.4)                                     | —                        | —                        | да (через адаптер)      | да (через адаптер)   | да (через адаптер)   | да (через адаптер)   | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да           | адаптер DevContour alpha.4 открывает такое состояние без отказа и пишет роль controller и события; новые поля сохраняются → для отката всё равно копия                                     |
-| alpha.7 с новым `inspection` ревью кода                                        | не проверялось           | не проверялось           | **нет** (строгая схема) | да                   | да                   | да                   | да                    | да                    | да                    | да                    | —            | новые значения `source`, `exitCode: null`, `origins`/`context`/`excluded`; строгая схема alpha.6 их не принимает, поведение прежних версий при открытии не проверялось → откат через копию |
-| неизвестная `stateVersion`                                                     | нет, отказ до записи     | нет, отказ до записи     | нет, отказ до записи    | нет, отказ до записи | нет, отказ до записи | нет, отказ до записи | нет, отказ до записи  | нет, отказ до записи  | нет, отказ до записи  | нет, отказ до записи  | нет          | `STATE_VERSION_UNSUPPORTED`, exit 4                                                                                                                                                        |
-
-Столбец alpha.2 относится и к alpha.3; alpha.4 и alpha.5 читают все строки, кроме неизвестной `stateVersion` и строк alpha.6 с новыми полями (standalone — отказ до записи) и строки alpha.7. alpha.8, alpha.9, alpha.10, alpha.11, alpha.12 и alpha.13 формат состояния не меняют и читают всё, что читает alpha.7. Каждая следующая версия добавляет сюда свой столбец. Отказ неизвестного
+| Состояние, записанное…                                                         | Читает 0.1.0-alpha.1     | Читает 0.1.0-alpha.2     | Читает 0.1.0-alpha.6    | Читает 0.1.0-alpha.7    | Читает 0.1.0-alpha.8    | Читает 0.1.0-alpha.9    | Читает 0.1.0-alpha.10   | Читает 0.1.0-alpha.11   | Читает 0.1.0-alpha.12   | Читает 0.1.0-alpha.13   | Читает 0.1.0-alpha.14 | Читает 0.1.0-alpha.15 | Читает 0.1.0-alpha.16 | Пишет поверх | Примечание                                                                                                                                                                                 |
+| ------------------------------------------------------------------------------ | ------------------------ | ------------------------ | ----------------------- | ----------------------- | ----------------------- | ----------------------- | ----------------------- | ----------------------- | ----------------------- | ----------------------- | --------------------- | --------------------- | --------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| standalone `stateVersion: 1` версией alpha.1                                   | да                       | да                       | да                      | да                      | да                      | да                      | да                      | да                      | да                      | да                      | да                    | да                    | да                    | да           | одна база SQLite: документ, события, локальные записи                                                                                                                                      |
+| хост, центральная база                                                         | да (через адаптер)       | да (через адаптер)       | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да           | данные не переносятся; новые поля необязательны                                                                                                                                            |
+| хост, базы компонентов                                                         | да (через адаптер)       | да (через адаптер)       | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да           | нужна копия всех баз при остановленных writers                                                                                                                                             |
+| alpha.2 после штатной остановки controller                                     | да                       | да                       | да                      | да                      | да                      | да                      | да                      | да                      | да                      | да                      | да                    | да                    | да                    | да           | роль controller снята — нового поля в состоянии нет                                                                                                                                        |
+| alpha.2 с живой или брошенной ролью controller                                 | **нет**, отказ до записи | да                       | да                      | да                      | да                      | да                      | да                      | да                      | да                      | да                      | да                    | да                    | да                    | —            | роль хранит `engineVersion`; строгая схема alpha.1 его не знает → откат через копию                                                                                                        |
+| alpha.4 с совместной проверкой                                                 | **нет**, отказ до записи | **нет**, отказ до записи | да                      | да                      | да                      | да                      | да                      | да                      | да                      | да                      | да                    | да                    | да                    | —            | проверка хранит `engineVersion`; прежние версии его не знают → откат через копию                                                                                                           |
+| alpha.6 standalone с записями ревью нового протокола или доставкой `uncertain` | **нет**, отказ до записи | **нет**, отказ до записи | да                      | да                      | да                      | да                      | да                      | да                      | да                      | да                      | да                    | да                    | да                    | —            | `reviewRound`, `findings[].id/status`, статус доставки `uncertain`; alpha.4/alpha.5 отказывают `STATE_VERSION_UNSUPPORTED` до записи → откат через копию                                   |
+| alpha.6, хост DevContour (адаптер alpha.4)                                     | —                        | —                        | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)      | да (через адаптер)    | да (через адаптер)    | да (через адаптер)    | да           | адаптер DevContour alpha.4 открывает такое состояние без отказа и пишет роль controller и события; новые поля сохраняются → для отката всё равно копия                                     |
+| alpha.7 с новым `inspection` ревью кода                                        | не проверялось           | не проверялось           | **нет** (строгая схема) | да                      | да                      | да                      | да                      | да                      | да                      | да                      | да                    | да                    | да                    | —            | новые значения `source`, `exitCode: null`, `origins`/`context`/`excluded`; строгая схема alpha.6 их не принимает, поведение прежних версий при открытии не проверялось → откат через копию |
+| alpha.14 с договором проверки `reference` или `gates` обязательства            | не проверялось           | не проверялось           | не проверялось          | **нет** (строгая схема) | **нет** (строгая схема) | **нет** (строгая схема) | **нет** (строгая схема) | **нет** (строгая схема) | **нет** (строгая схема) | **нет** (строгая схема) | да                    | да                    | да                    | —            | контракт хранится строгой схемой (`contract-documents`): прежние версии новых полей `gates`, `verification`, `reference` не знают → откат через копию                                      |
+| неизвестная `stateVersion`                                                     | нет, отказ до записи     | нет, отказ до записи     | нет, отказ до записи    | нет, отказ до записи    | нет, отказ до записи    | нет, отказ до записи    | нет, отказ до записи    | нет, отказ до записи    | нет, отказ до записи    | нет, отказ до записи    | нет, отказ до записи  | нет, отказ до записи  | нет, отказ до записи  | нет          | `STATE_VERSION_UNSUPPORTED`, exit 4                                                                                                                                                        |
+
+Столбец alpha.2 относится и к alpha.3; alpha.4 и alpha.5 читают все строки, кроме неизвестной `stateVersion` и строк alpha.6 с новыми полями (standalone — отказ до записи) и строки alpha.7. alpha.8, alpha.9, alpha.10, alpha.11, alpha.12 и alpha.13 формат состояния не меняют и читают всё, что читает alpha.7; alpha.14 и alpha.15 (локальные, не опубликованы) и alpha.16 читают всё, что читает alpha.13, и добавляют необязательные поля договора проверки (строка alpha.14). Каждая следующая версия добавляет сюда свой столбец. Отказ неизвестного
 формата до записи проверяют тесты совместимости пакета
 <!-- repo-only -->(`tests/compatibility.test.ts`)<!-- /repo-only -->.
 

package/lib/contracts/checks.d.ts

@@ -2,6 +2,41 @@ import { z } from 'zod';
 export declare const promiseKinds: readonly ["functional", "accuracy", "optimality", "completeness", "performance", "invariant", "other"];
 /** Вычислительные обещания: без независимого способа проверки их не утверждают. */
 export declare const strongPromises: ReadonlySet<string>;
+/**
+ * Проверка по закреплённым эталонным наборам (`verification: 'reference'`).
+ *
+ * Ответы независимого эталона (решатель, полный перебор, таблица DP)
+ * получены заранее, сверены с другим способом на семействах входов и
+ * закреплены артефактами контракта. Gate сверяет реализацию с наборами и
+ * отчитывается тем же отчётом свойств: число проверенных входов по свойству
+ * и по семействам. Каждый набор принадлежит одному gate: его минимум и
+ * минимумы семейств — доля этого gate в покрытии обязательства. Обобщения за
+ * пределы наборов такой способ не доказывает — это называет `gaps`.
+ */
+export declare const referenceSchema: z.ZodObject<{
+    oracle: z.ZodObject<{
+        description: z.ZodString;
+        limits: z.ZodString;
+    }, z.core.$strict>;
+    crossChecks: z.ZodArray<z.ZodObject<{
+        family: z.ZodString;
+        against: z.ZodString;
+        matches: z.ZodNumber;
+        total: z.ZodNumber;
+        artifacts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    sets: z.ZodArray<z.ZodObject<{
+        gate: z.ZodString;
+        artifacts: z.ZodArray<z.ZodString>;
+        minCases: z.ZodNumber;
+        families: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            minCases: z.ZodNumber;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    gaps: z.ZodString;
+}, z.core.$strict>;
+export type ReferenceVerification = z.infer<typeof referenceSchema>;
 export declare const obligationSchema: z.ZodObject<{
     property: z.ZodString;
     requirements: z.ZodArray<z.ZodString>;
@@ -63,6 +98,34 @@ export declare const obligationSchema: z.ZodObject<{
             environment: z.ZodString;
         }, z.core.$strict>>;
     }, z.core.$strict>;
+    gates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    verification: z.ZodOptional<z.ZodEnum<{
+        property: "property";
+        reference: "reference";
+    }>>;
+    reference: z.ZodOptional<z.ZodObject<{
+        oracle: z.ZodObject<{
+            description: z.ZodString;
+            limits: z.ZodString;
+        }, z.core.$strict>;
+        crossChecks: z.ZodArray<z.ZodObject<{
+            family: z.ZodString;
+            against: z.ZodString;
+            matches: z.ZodNumber;
+            total: z.ZodNumber;
+            artifacts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        sets: z.ZodArray<z.ZodObject<{
+            gate: z.ZodString;
+            artifacts: z.ZodArray<z.ZodString>;
+            minCases: z.ZodNumber;
+            families: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                minCases: z.ZodNumber;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+        gaps: z.ZodString;
+    }, z.core.$strict>>;
     hard: z.ZodDefault<z.ZodBoolean>;
     feasibility: z.ZodOptional<z.ZodObject<{
         spike: z.ZodString;
@@ -134,6 +197,34 @@ export declare const checkDeclarationSchema: z.ZodObject<{
                 environment: z.ZodString;
             }, z.core.$strict>>;
         }, z.core.$strict>;
+        gates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        verification: z.ZodOptional<z.ZodEnum<{
+            property: "property";
+            reference: "reference";
+        }>>;
+        reference: z.ZodOptional<z.ZodObject<{
+            oracle: z.ZodObject<{
+                description: z.ZodString;
+                limits: z.ZodString;
+            }, z.core.$strict>;
+            crossChecks: z.ZodArray<z.ZodObject<{
+                family: z.ZodString;
+                against: z.ZodString;
+                matches: z.ZodNumber;
+                total: z.ZodNumber;
+                artifacts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
+            sets: z.ZodArray<z.ZodObject<{
+                gate: z.ZodString;
+                artifacts: z.ZodArray<z.ZodString>;
+                minCases: z.ZodNumber;
+                families: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    minCases: z.ZodNumber;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>>;
+            gaps: z.ZodString;
+        }, z.core.$strict>>;
         hard: z.ZodDefault<z.ZodBoolean>;
         feasibility: z.ZodOptional<z.ZodObject<{
             spike: z.ZodString;
@@ -233,6 +324,34 @@ export declare const contractDocumentSchema: z.ZodObject<{
                     environment: z.ZodString;
                 }, z.core.$strict>>;
             }, z.core.$strict>;
+            gates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            verification: z.ZodOptional<z.ZodEnum<{
+                property: "property";
+                reference: "reference";
+            }>>;
+            reference: z.ZodOptional<z.ZodObject<{
+                oracle: z.ZodObject<{
+                    description: z.ZodString;
+                    limits: z.ZodString;
+                }, z.core.$strict>;
+                crossChecks: z.ZodArray<z.ZodObject<{
+                    family: z.ZodString;
+                    against: z.ZodString;
+                    matches: z.ZodNumber;
+                    total: z.ZodNumber;
+                    artifacts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                }, z.core.$strict>>;
+                sets: z.ZodArray<z.ZodObject<{
+                    gate: z.ZodString;
+                    artifacts: z.ZodArray<z.ZodString>;
+                    minCases: z.ZodNumber;
+                    families: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        minCases: z.ZodNumber;
+                    }, z.core.$strict>>>;
+                }, z.core.$strict>>;
+                gaps: z.ZodString;
+            }, z.core.$strict>>;
             hard: z.ZodDefault<z.ZodBoolean>;
             feasibility: z.ZodOptional<z.ZodObject<{
                 spike: z.ZodString;