Русское издание для чтения. Нормативным источником остаётся оригинал на английском, сверенный с ревизией 61e75e9aa9a8719dfb480bf1f5226553b3a21d70. Перевод не вводит новую редакцию спецификации.

ADR 0002: добавление меток семантических операций в формат ChangeSet v1

• Статус: принято
• Дата: 2026-07-29

Контекст

Формат store.ChangeSet v1 задаёт каноническую оболочку запроса, используемую для вычисления хеша запроса, привязки журнала, повторного воспроизведения квитанций и идемпотентности. OKF v0.2 добавляет специализированные семантические операции, сохраняя протокол транзакций и смысл существующих операций и предусловий.

Если изменить версию формата только из-за добавления вариантов в закрытое объединение операций, существующие хеши запросов станут недействительными, а каждой реализации хранилища понадобится второй декодер оболочки, хотя отдельного контракта передачи данных не появится.

Решение

Версия формата ChangeSet остаётся 1. Новым видам операций назначаются уникальные канонические метки в нижнем регистре внутри существующего поля операции с префиксом длины:

• set_generated
• ensure_verification
• remove_verification
• put_source
• remove_source
• set_usage_window
• set_lifecycle
• put_attested_computation
• set_bundle_version
• migrate_v01_to_v02

Метки назначаются один раз и никогда не используются повторно для другого смысла. Все следующие за меткой поля кодируются существующими детерминированными примитивами v1: беззнаковыми значениями длины фиксированной ширины, строками или байтами с префиксом длины, явными битами присутствия и списками, в которых порядок значим.

Оболочка v1 сохраняет следующие поля:

1. маркер домена;
2. версия формата;
3. идентификатор набора изменений;
4. субъект транзакции;
5. базовая ревизия;
6. количество операций и сами операции;
7. количество предусловий и сами предусловия.

Публичное объединение типов в Go принимает только документированные конкретные значения, не являющиеся указателями. Указатели, типизированные значения nil и неизвестные варианты отклоняются до проверки или канонической обработки. Декодер или адаптер, встретив неизвестную каноническую метку, должен отклонить запрос как неподдерживаемый; пропускать, переинтерпретировать или выполнять его данные запрещено.

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

Канонические байты и хеши запросов всех операций и предусловий, существовавших до v0.2, сохраняются побайтно. Добавление метки изменяет только запросы, явно содержащие новую операцию. Поэтому ChangeSet v1 продолжает связывать предварительные планы, фиксацию изменений, журналы и квитанции единым протоколом.

Зафиксированные контрольные значения старого формата и тесты чувствительности к каждому полю операций служат исполняемыми проверками совместимости. Переименование или повторное использование метки, перестановка полей, неявное кодирование необязательного поля либо изменение старого примитива нарушают совместимость.

Когда повышать версию в будущем

Увеличивать ChangeSetFormatVersion следует только при необходимости хотя бы одного из следующих изменений:

• изменяются поля оболочки, их порядок или кодирование;
• изменяется смысл существующей метки или поля;
• существующей операции требуется несовместимая структура полей;
• неизвестные варианты становится можно пропускать либо появляется другое обрамление данных для совместимости с будущими версиями, отсутствующее в v1;
• изменяются правила канонической нормализации так, что это влияет на существующие хеши;
• расходятся правила привязки транзакций, журналов, квитанций или идемпотентности.

Будущая версия должна использовать новые эталонные значения и явный план миграции реализаций хранилища. Само по себе выделение ещё одной уникальной метки в закрытом объединении недостаточно для повышения версии формата.