Техническое задание: Семантические операции изменения для v0.2
Исторический документ из ревизии 61e75e9. План отражает работы, предложенные в этой ревизии, и не является актуальной инструкцией по реализации. Исходный документ.
1. Цель
Добавить идемпотентные предметные операции для стандартных групп полей OKF v0.2 поверх движка, сохраняющего данные без потерь. Не предоставлять вызывающей стороне обходной путь для произвольного изменения YAML.
Не публиковать произвольный SetYAML, yaml.Node или путь по исходным ключам.
3. Отдельное отображение и список verified
Одна запись о проверке может сохраняться как отдельное отображение.
При добавлении второго события отображение атомарно становится последовательностью.
Операция обеспечения наличия записи идемпотентна.
Удаление сохраняет допустимую форму и не теряет неизвестные вложенные ключи.
4. Канонический контракт хранилища
Каждая операция:
имеет отдельный канонический тег;
сериализует все поля с префиксом длины;
глубоко копирует срезы и отображения вызывающей стороны;
имеет детерминированный дайджест;
не меняет дайджесты старых операций.
Нужна запись об архитектурном решении (ADR): добавление тегов в формат ChangeSet v1 либо обоснованное повышение версии. Нельзя повышать версию формата «на всякий случай».
Не ограничивать store.ChangeSet.Actor соглашением об акторах v0.2: это субъект транзакции. Акторы документа валидируются внутри соответствующей операции.
5. Интеграция перемещений и путей
Расширить MoveConcept, чтобы он без потери данных переписывал статически разрешимые пути пакета в:
sources[].resource;
computation;
executor.resource;
attester.resource.
Внешние URL и дескрипторы области действия не менять. Неработающие и неразрешимые значения сохранять.
6. Контроль валидации
Сохранить последовательность:
Валидировать ChangeSet.
Применить операции к копии.
Загрузить итоговый пакет с подготовленными изменениями.
Запустить валидатор с учётом версии.
При блокирующей проблеме вернуть предварительный просмотр только с диагностикой.
Предварительная проверка операции проверяет актора, дату, селектор источника и уникальность параметров. Предупреждения строгого режима не блокируют обычную фиксацию, если не являются явным постусловием операции.
7. Файлы
store/change.go, types.go, result.go;
mutation/planner.go;
новые обработчики операций;
тесты канонизации, дайджестов и глубокого копирования;
тесты контракта предварительного просмотра.
8. Тесты
Все тесты следуют AAA.
Вставка, обновление и удаление каждой группы полей.
Отдельное отображение и списочная форма verified.
Общий интервал использования и интервалы отдельных источников.
Типизированные usage_count/required.
Встроенное вычисление и вычисление из файла.
Переписывание локальных путей, внешних URL и областей действия.
Сохранение неизвестных вложенных расширений.
Идемпотентность повторного применения.
Изменение среза вызывающей стороной не влияет на запрос или дайджест.
При дублировании селекторов и ключей операция отклоняется.
Отклонённый план не содержит подготовленных изменений, записей или переименований.
Существующие операции сохраняют точные канонические дайджесты.
go test -race ./mutation ./store.
9. Критерии приёмки
Все группы полей v0.2 имеют публичные операции задания желаемого состояния.
Неизвестные поля и комментарии вне затрагиваемых диапазонов сохранены.
Контракт аттестованного вычисления нельзя оставить обновлённым частично.
Существующие API и дайджесты сохраняют совместимость.
CLI/MCP могут создавать операции без исходного YAML.
10. Вне рамок задачи
Миграция устаревших данных, исполнение вычислений, связывание, квитанции и вердикты, среда исполнения проверяющей стороны и исполнение произвольных ресурсов.