Доменная модель OKF v0.2 в bundle

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

1. Цель

Сделать bundle доменным слоем чтения для происхождения данных, доверия, жизненного цикла, Attested Computation, атрибуции по ключу и связанных ресурсов. Сохранить соответствие с минимальными ограничениями, BYOT и обратную запись неизвестных ключей без потерь.

Зависимость: task09.md.

2. Текущие пробелы

• bundle.OKFVersion == "0.1".
• Типизированные методы доступа покрывают старый timestamp, но не группы полей v0.2.
• Новые стандартные ключи считаются расширениями.
• Document.Citations() понимает только позиционные # Citations.
• Bundle.Load не сохраняет ресурсы .sql/.py, не являющиеся Markdown.
• Общий семантический индекс подресурсов считает sources[].id фрагментом.
• Расширение relations не исключает стандартные группы полей v0.2.

3. Публичная модель

Добавить небольшие открытые модели чтения:

• Generation;
• Verification;
• UsageWindow;
• ProvenanceSource (Source уже занят интерфейсом хранилища);
• TrustTier;
• константы жизненного цикла;
• ComputationParameter;
• ExecutorContract;
• AttesterContract;
• AttestedComputationContract.

Участник, среда выполнения, тип параметра и имена полей квитанции остаются открытыми строками. Не вводить закрытые реестры или перечисления.

Добавить методы доступа:

• Sources, общий и действующий UsageWindow;
• Generated, Verifications;
• вычисляемый TrustTier;
• исходный и действующий Status;
• StaleAfter и вспомогательную функцию с явной опорной датой;
• AttestedComputation;
• действующее время изменения содержимого.

Одиночное отображение verified нормализуется в срез из одного элемента без изменения исходного YAML.

4. BYOT и контракт сохранения без потерь

• Get, Set, YAMLNode остаются определяющими источниками данных.
• Добавить обобщённую функцию декодирования и кодирования для структур вызывающей стороны.
• Не вводить монолитную FrontmatterSchema.
• Методы доступа возвращают копии и не делят изменяемые срезы или отображения с вызывающей стороной.
• Типизированное чтение не меняет стиль узлов, комментарии, порядок ключей и вложенные расширения.
• Стандартные ключи v0.2 и старый timestamp исключаются из ExtensionKeys; relations остаётся расширением проекта.

5. Атрибуция

Добавить ссылки и определения сносок и Document.Attributions():

• ключ сопоставления — sources[].id;
• порядок источников не имеет значения;
• маркеры и определения в блоках кода и встроенном коде игнорируются;
• неизвестные и повторяющиеся ID остаются видимыми и не отфильтровываются молча;
• текстовое определение сноски не заменяет структурированный источник;
• старый API Citation сохраняется.

6. Ресурсы bundle и значения путей

• Load сохраняет все обычные файлы, видимые в ревизии.
• MarkdownFiles() сохраняет прежнюю семантику.
• Добавить Files()/AssetFiles() с защитными копиями.
• ReadFile() читает сохранённые .sql, .py, .json без повторного ввода-вывода.
• Сохранить контракт безопасности: запрет следования по ссылкам, правила для специальных файлов и .okf.
• Добавить разрешение URL, путей относительно bundle и относительных путей.
• Описание области не считать локальным путём.

7. Коллизия семантических расширений

• sources[].id не является concept#fragment.
• Отображения стандартных групп полей не становятся неявными источниками связей.
• Повторяющиеся ID источников не создают duplicate_fragment.
• Настоящие подресурсы расширений производителя продолжают индексироваться.

8. Соответствие и совместимость

Не расширять Document.ValidateConformance(): обязательное требование — только разбираемые метаданные и непустая строка type.

• Необязательная группа полей может отсутствовать.
• Некорректная необязательная группа не мешает Bundle.Load.
• Timestamp() сохранить как устаревший метод доступа к старому формату.
• generated.at имеет приоритет; некорректный присутствующий generated не должен молча переключать чтение на timestamp.
• Никакой миграции при чтении или сериализации.

9. Файлы

• bundle/doc.go;
• bundle/frontmatter.go, новый frontmatter_v02.go;
• bundle/document.go;
• bundle/links.go или новый attribution.go;
• bundle/bundle.go;
• bundle/semantic_index.go;
• bundle/relations.go;
• тесты пакетов и канонические тестовые данные.

10. Тесты

Все тесты — AAA.

• Полное приложение A.
• verified в виде одиночного отображения и списка.
• Все уровни доверия.
• Отсутствующий статус → stable.
• Граница устаревания today == stale_after.
• Присутствующий generated без at не переключается на резервное поле.
• Общее окно использования и окна отдельных источников.
• Неизвестные и некорректные вложенные структуры не вызывают панику и не исчезают.
• Сноски: изменение порядка, повторы, неизвестные ID, определения и код.
• Разбор → типизированное чтение → сериализация сохраняет неизвестные байты и семантику.
• sources[].id не появляется в индексах подресурсов и связей.
• .sql/.py сохраняются и видимы в ревизии.
• Существующие тесты v0.1 не дают регрессий.

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

• bundle.OKFVersion == "0.2".
• SDK читает все поля §§5 и 10 без ручного обхода YAML.
• BYOT и обратная запись неизвестных расширений без потерь подтверждены.
• Ресурсы доступны из неизменяемого загруженного bundle.
• Старый API остаётся рабочим.
• go test ./bundle и go test ./... проходят.

12. Вне рамок задачи

Выполнение, привязка параметров, квитанции и вердикты среды выполнения, ABI и песочница attester, кеширование и автоматическая миграция.