Перевод для чтения человеком. Сверен с английским оригиналом ревизии 61e75e9 (на английском). Перевод не является новой редакцией нормативного контракта. Текущая английская страница.
Матрица сопоставляет зафиксированную спецификацию с интерфейсами реализации,
политикой диагностики и каноническими подтверждающими примерами. Она явно
различает требования исходной спецификации и строгую политику skosovsky/okf.
| Положение | Исполняемый контракт | Интерфейс реализации | Устойчивые диагностические сообщения / политика | Канонические подтверждающие примеры |
|---|---|---|---|---|
| §1 | OKF описывает переносимые файлы; библиотека никогда не исполняет вычисления, исполнителей или подтверждающих участников | Доступные только для чтения API bundle, validator, graph |
ABI выполнения и вердикт среды выполнения не выводятся автоматически | positive/appendix-a, positive/durability; контракт отложенного ABI |
| §2 | Набор остаётся обычными читаемыми человеком файлами; необязательные группы полей читаются независимо | Чтение метаданных и тела без потерь, декодирование/кодирование BYOT | Отсутствие необязательной группы не даёт диагностического сообщения | positive/minimal; тесты обратимого преобразования без потерь |
| §3 | Обычные файлы, видимые в ревизии, образуют набор; зарезервированные имена обрабатываются отдельно | bundle.Source, bundle.Load, детерминированные идентификаторы понятий |
Ошибка ввода-вывода прерывает операцию; ошибки разбора отдельных понятий собираются | positive/appendix-a, positive/canonical, positive/durability |
| §3.1 | Зарезервированные имена файлов не являются обычными понятиями | Сканер и валидаторы зарезервированных документов | Некорректный присутствующий index.md/log.md даёт базовый ERROR |
Старый набор отрицательных примеров и эталоны строгой проверки зарезервированных файлов |
| §4.1, §11.1–11.2 | Метаданные понятия разбираются; type — непустая строка YAML |
bundle.Document, типизированные/исходные метаданные, базовый профиль валидатора |
Базовый ERROR с кодом frontmatter_* или type_* и точным путём поля |
positive/minimal, строгий набор и неблагоприятные случаи |
| §4.1 | Неизвестные ключи, неизвестные непустые строковые типы и несвязанные повторяющиеся ключи автора сохраняются и читаются; повторяющиеся стандартные ключи остаются присутствующими, но типизированно неразрешёнными | API исходных узлов YAML, семантическое состояние значений и декодирование/кодирование BYOT | Неизвестные данные сами по себе не вызывают диагностику; типизированное чтение никогда не выбирает одно повторяющееся значение | positive/minimal, неблагоприятные случаи, общие тесты повторяющихся ключей |
| §§4.2–4.4 | Тело Markdown и необязательная привязка ресурса доступны для побайтового чтения | Document.Body, наблюдение путей с учётом поля |
Отсутствующая цель ресурса не является базовым несоответствием | Канонические случаи ресурсов и путей |
| Граница разборщика библиотеки | Определение принадлежности Markdown разборщиком принимает не более 16 MiB на полный документ или отдельно переданное тело | bundle.MaxMarkdownDocumentBytes, bundle.MaxMarkdownBodyBytes, методы принадлежности с Context |
Отмена проверяется перед некорректным UTF-8, который проверяется перед типизированной ErrMarkdownResourceLimit; отклонённые вызовы с Context не выдают частичный результат |
bundle/markdown_limit_contract_test.go, internal/markdownowner/markdown_limit_contract_test.go и validator/markdown_limit_validation_test.go |
| §5.1 | Источники и сигналы достоверности читаются только из скалярных значений с корректными тегами | Типизированное наблюдение источников и доступ к исходному YAML | Некорректные присутствующие формы и повторяющиеся идентификаторы источников дают строгий WARNING |
positive/appendix-a, строгий набор и неблагоприятные случаи |
| §5.1 | Привязка утверждений сопоставляет метки сносок в обычном тексте с идентификаторами источников | Document.Attributions на основе разборщика |
Отсутствующее или повторное сопоставление даёт строгий WARNING; маркеры во встроенном и многострочном коде игнорируются; точные сокращённые ссылки [^label] продолжают учитываться |
Приложение A, тесты принадлежности Markdown и набор совместимости |
| §5.2 | Корректное одиночное отображение verified эквивалентно последовательности из одного элемента |
Типизированное наблюдение проверок | Некорректные участник/дата/событие дают строгий WARNING и не повышают доверие |
positive/canonical/verified-{bare,list}.md, строгий набор |
| §5.3 | Уровень доверия выводится из корректных событий проверки и никогда не хранится | Вспомогательная функция доверия набора; проекция графа библиотеки | Отсутствие проверки допустимо | Каноническая матрица доверия |
| §§5.4–5.5, обе зафиксированные ревизии 0.2 | Только отсутствующий статус по умолчанию означает stable; date-3fcbb9f сравнивает календарные даты, а instant-0b87c52 — точные моменты со смещением; без опорного значения устаревание не оценивается |
Явный временной профиль, наблюдение жизненного цикла с учётом профиля и валидатор с переданным опорным значением; CLI/MCP никогда не используют системные часы по умолчанию | Некорректное присутствующее состояние жизненного цикла неразрешено и даёт строгий WARNING; достигнутая граница даёт предупреждение политики только при явном --as-of/as_of; старые даты не преобразуются в моменты автоматически |
Обе фиксации спецификации, тесты границ моментов и старые регрессионные тесты |
| §6.1 | Ссылки понятий принадлежат Markdown и относительны корню набора; проверка использует только захваченный снимок, поэтому проигнорированные символические ссылки и последующие изменения файловой системы не могут удовлетворить ссылку | Извлечение ссылок разборщиком и семантический индекс | Неработающие ссылки не являются базовыми ошибками; политика необязательных связей отдельна | Канонические ссылки, пример игнорируемой символической ссылки, тесты изменения снимка и принадлежности коду |
| §6.2 | URL, пути относительно корня и понятия сохраняются; неоднозначность области источника явно обозначается | API наблюдения путей с учётом поля | Нет требований соответствия о сети или существовании; неоднозначные описания источников не переписываются | Канонические файловые случаи и неблагоприятные случаи областей/путей |
| §6.3 | references/ — соглашение, а не зарезервированное пространство имён |
Обычный захват ресурсов набора | Особой диагностики соответствия нет | Дерево references приложения A |
| §7 | Строки участников классифицируются только при корректности; неизвестные пространства имён автора остаются открытыми | Типизированные функции участников происхождения и проверки | Некорректная форма участника даёт строгий WARNING; принудительного реестра нет |
Каноническая матрица human/process/agent |
| §8, §11.3 | Присутствующий index.md группирует ссылки под заголовками; начальный заголовок H1 и введение могут предшествовать заполненным группам |
Разборщик и валидатор зарезервированного индекса | Пустые группирующие разделы, некорректные списки ссылок и пустые перечни остаются базовым ERROR по пути body |
Тесты зарезервированных файлов и зафиксированный набор совместимости |
| §8, §11 | Корневой index.md может объявлять okf_version; неизвестные соседние ключи сохраняются согласно запрету потребителю отклонять неизвестные ключи в §11, хотя §8 описывает только стандартное поле автора |
Состояние объявления зарезервированного индекса и исходный YAML | Повторяющееся, некорректное или отсутствующее объявление в присутствующем корневом блоке метаданных — базовый ERROR; неизвестные соседние ключи сами по себе — нет |
Тесты расширений корня и объявлений; зафиксированный набор совместимости |
| §9, §11.3 | Присутствующий log.md имеет плоские группы дат от новых к старым; физические строки переноса одного пункта списка допустимы |
Общий механизм принадлежности Markdown, типизированный разборщик журнала и валидатор | Отдельные абзацы и вложенные списки остаются базовым ERROR по пути body; перенесённые строки не вызывают диагностики |
Тесты зарезервированных файлов и зафиксированный набор совместимости |
| §§10.1–10.2 | Только точный type: Attested Computation открывает типизированный контракт |
Типизированный метод получения вычисления | Некорректные присутствующие поля дают строгий WARNING, никогда базовый ERROR |
Приложение A, канонические встроенные и файловые случаи |
| §10.3 | Ровно один раздел H1 верхнего уровня содержит один закрытый непосредственный дочерний ограждённый блок или путь к файлу как вычисление; соседний текст допустим, вложенные блоки списков/цитат — конфликтующее содержимое примеров | Типизированное исследование вычислений разборщиком | Отсутствующие/некорректные/неоднозначные режимы дают строгий WARNING; заголовки внутри кода не считаются; вложенные кандидаты никогда не трактуются как отсутствие |
TestAttestedComputationStateIsExactTypeAndPayloadOwned, TestComputationSectionsRetainUnclosedAndMultipleFenceSpans, строгие неблагоприятные случаи Markdown |
| §§10.4–10.6 | Понятия ссылаются на вычисления; библиотека фиксирует определения, а не вердикты выполнения или подтверждения | Семантические ссылки и наблюдения графа | Нет выполнения квитанций или автоматического вывода вердикта | Приложение A и пример долговечности |
| §11 | Базовое соответствие исчерпывающее: только метаданные/тип/зарезервированная структура дают ошибки; повторяющийся type понятия присутствует, но неразрешён и остаётся базовой ошибкой |
Граница уровней важности валидатора и семантическое состояние повторов | Проверки семантических связей и явные утверждения селектора — отдельные результаты политики/API; остальные повторяющиеся стандартные группы дают строгие предупреждения | Эталонные наборы строгой диагностики и TestDuplicateTypeAndReservedVersionRemainBaseDiagnostics |
| §12 | Корневое объявление необязательно; любое каноническое неподдерживаемое объявление использует v0.2 в режиме максимально возможной совместимости и фиксированную публичную метку future-best-effort; явные селекторы задают обязательное условие; повторяющийся корневой okf_version присутствует, но неразрешён |
Общая грамматика/состояние версии и её определение | Некорректное или повторяющееся объявление — ERROR зарезервированного корня; конфликт — ошибка API; корректное неподдерживаемое исходное значение остаётся видимым |
TestVersionResolutionUnsupportedCanonicalMatrix, TestDuplicateTypeAndReservedVersionRemainBaseDiagnostics, TestV02CompatibilityCorpusPreservesFallbackPrecedenceAndBytes |
| §13.1 | timestamp и # Citations используются только при полном отсутствии замен |
Чтение эффективных происхождения/времени и помеченные старые наблюдения графа | Некорректная присутствующая замена отключает старое представление; только старое представление допустимо | Примеры объявленной/необъявленной v0.1 и смешанного происхождения |
| §13.2 | Дополнительные неизвестные поля остаются обратимо преобразуемыми | Доступ к исходному YAML/BYOT | Будущие дополнительные ключи не отклоняются | Примеры будущих версий и неблагоприятные случаи |
| Приложение A | Производные файлы прослеживаются до зафиксированного примера и объявленных преобразований | derivation.json и тест изменения контрольной суммы |
Изменение примеров требует явной причины преобразования и новых хешей | positive/appendix-a |
| Расширение библиотеки | YAML relations не входит в исходную v0.2 |
Наблюдения связей; явно включаемая политика расширения графа | Диагностика никогда не меняет соответствие исходной спецификации | Существующие примеры/тесты связей |
| Политика изменений библиотеки | Изменение сохраняет несвязанные повторяющиеся ключи YAML и отклоняет только повторяющийся путь или селектор, затронутый операцией | Механизм изменения представления без потерь и семантические операции v0.2 | duplicate_touched_key/неоднозначность селектора — ошибка операции, никогда ошибка чтения всего документа |
Общие тесты повторяющихся ключей при изменении |
| Профиль графа библиотеки | Словарь JSON-LD/RDF v0.2 принадлежит библиотеке и версионируется | Явный профиль проекции и контракт графа | Предикаты для неизвестного YAML не выдумываются | Приложение A, контракт графа и эталоны |
Коды диагностики и пути полей — устойчивый API. Диагностика новых групп использует
пути вроде sources[2].resource; вызывающий код не должен разбирать сообщения для человека.