OKF v0.2: базовый контракт и план миграции

Исторический документ. План сохранён из ревизии исходника 61e75e9 и не является текущим руководством по реализации. Исходный документ.

1. Цель

Зафиксировать исполняемый контракт поддержки Open Knowledge Format v0.2 до изменения публичных API. Эта задача — корневая зависимость для остальных задач миграции.

Источники истины:

• исходная спецификация okf/SPEC.md, коммит 3fcbb9f828c2f23d109c855ee403c3a4c81f3a96;
• нормативные разделы §§1–13;
• приложение A как канонический сквозной пример.

Нельзя ориентироваться только на текущую ветку main: воспроизводимая сборка и тесты должны ссылаться на зафиксированную ревизию спецификации.

2. Контракт версий

Поддерживаемые версии:

• 0.1 — чтение и валидация старого формата, источник для миграции;
• 0.2 — текущий контракт чтения и записи по умолчанию;
• неизвестная будущая версия — чтение по мере возможностей без отказа только из-за значения okf_version.

Правила определения версии:

1. Явно указанная поддерживаемая версия okf_version в корневом index.md задаёт контракт.
2. При отсутствии объявления действующая версия — 0.2, но разрешены резервные правила для старого формата из §13.
3. Потребитель v0.2 читает неизвестную версию по мере возможностей и сохраняет её как объявленную версию.
4. Явный селектор API/CLI — это утверждение. Конфликт с объявлением версии не должен молча менять семантику.

Модель определения версии должна различать:

• объявленную версию;
• действующую версию;
• источник: declared, default, explicit, future-best-effort;
• совместимость: нативная, со старым форматом или по мере возможностей.

Версия модуля Go, бинарного файла CLI и пакета плагина — не okf_version.

3. Матрица соответствия

Создать версионируемую матрицу: пункт спецификации → реализация → диагностика → тесты.

Обязательные ошибки [ERROR] остаются ограничены §11:

• разбираемый Markdown в UTF-8 и YAML-метаданные для концептов;
• непустая строка type;
• структура зарезервированных файлов index.md и log.md.

Необязательные группы полей v0.2 не становятся обязательными требованиями:

• sources, usage_window;
• generated, verified;
• status, stale_after;
• поля вычислений.

Некорректная присутствующая группа проверяется на уровне строгих проверок и политик и не должна мешать загрузке с минимальными ограничениями. Неизвестные ключи, типы и среды выполнения остаются доступными для чтения.

4. Контракт старого формата

Поддержать два резервных правила без скрытой миграции:

• timestamp используется только при полном отсутствии generated;
• # Citations читается только при отсутствии sources.

Представление в старом формате само по себе не нарушает соответствие. Чтение, fmt, index и операции с графом не должны переписывать документы v0.1.

Миграция должна быть отдельной операцией предпросмотра и применения с явно указанным участником и сопоставлением источников.

5. Реестр неоднозначностей

Зафиксировать решения политики инструментов отдельно от исходной спецификации:

• sources[].author ссылается на соглашение об участниках, но примеры исходной спецификации используют неописанный team:*; проверять как непустую строку;
• грамматика и уникальность sources[].id не определены; уникальность — строгая политика инструментария для безопасного сопоставления атрибуций;
• sources[].resource может быть описанием области, а не путём или URI;
• часовой пояс для today >= stale_after не определён; инструменты принимают явно заданную опорную дату, значение по умолчанию для CLI описывается отдельно;
• usage_count — не оценка;
• для runtime и типов параметров нет реестра;
• требования к executor/attester слабее требования к runtime и остаются рекомендациями строгого режима;
• для одновременного происхождения в старом формате и v0.2 исходная спецификация не задаёт правил приоритета и устранения дублей;
• YAML relations — расширение skosovsky/okf, не часть исходной спецификации v0.2.

Каждое решение должно быть одинаково отражено в bundle, validator, CLI, MCP, тестовых данных и документации.

6. Канонические тестовые данные

Добавить один общий набор:

• минимальный концепт v0.2 только с type;
• полное приложение A;
• Attested Computation со встроенным кодом и кодом в файле;
• verified в виде одиночного отображения и списка;
• v0.1 с объявленной версией и без неё;
• смешанный старый формат и v0.2;
• неизвестная будущая версия;
• некорректные структуры для состязательных проверок и неизвестные расширения.

Переиспользовать данные в тестах пакетов, сквозных тестах CLI/MCP и примерах документации.

7. Отложенный ABI

Явно исключить:

• среду выполнения executor;
• реализацию привязки параметров;
• формат передачи квитанций и вердиктов;
• ABI, переносимость и песочницу attester;
• кеширование аттестаций;
• выполнение содержимого bundle.

store.CommitReceipt не связан с executor.receipt.

8. Критерии приёмки

• Контракт и реестр неоднозначностей зафиксированы в версионируемой документации.
• Есть матрица соответствия по пунктам и канонический набор тестовых данных.
• Все зависимые задачи ссылаются на одинаковую политику версий.
• Резервные правила v0.1 и чтение будущих версий по мере возможностей покрыты тестами.
• Ни одна задача не выдумывает отложенный ABI среды выполнения.
• go test ./... и git diff --check проходят после добавления набора данных для проверки контракта.

9. Граф зависимостей

Порядок:

1. Эта задача.
2. bundle.
3. Параллельно: validator, graph, механизм изменений, защитные ограничения хранилища.
4. Операции изменения и миграция.
5. CLI и MCP.
6. Навыки, документация и итоговая проверка соответствия на всех интерфейсах.