Техническое задание: Обобщённый движок изменения YAML без потери данных для v0.2

Исторический документ из ревизии 61e75e9. План отражает работы, предложенные в этой ревизии, и не является актуальной инструкцией по реализации. Исходный документ.

1. Цель

Расширить закрытый движок изменений структурными операциями над отображениями и последовательностями, сохранив контракт отказа при неопределённости и побайтового сохранения данных.

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

2. Пробел в возможностях

Текущий движок ориентирован на relations, id, anchor и строковые скаляры. OKF v0.2 использует вложенные отображения и последовательности, логические и целочисленные значения, даты, дату со временем и поточные формы. Сейчас затрагиваемые узлы в поточной форме полностью отвергаются.

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

3. Закрытые базовые операции

Добавить:

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

Правила выбора:

• sources[] по id; запись без ID выбирается только по точному значению;
• verified[] по (by, at);
• parameters[] по name;
• вложенное отображение по уникальному скалярному ключу.

Произвольный путь по исходному YAML не должен становиться публичным API.

4. Контракт отказа при неопределённости

• Дубли затрагиваемых ключей или селекторов → Ambiguous.
• Происхождение из псевдонима или слияния → Ambiguous.
• Якорь, тег, сложный ключ или элементы оформления без определённой принадлежности → Unsupported.
• Недоказуемая принадлежность комментария → Unsupported.
• Изменение вложенной поточной формы разрешено только заменой всего значения.
• Незатрагиваемые YAML и Markdown остаются побайтово идентичными.
• При любой ошибке нет подготовленных изменений, записей, переименований или плана.

Добавить стабильные коды ошибок и позиции в исходном тексте, не выходящие за его границы.

5. Файлы

• mutation/presentation.go;
• mutation/yaml_resolver.go;
• mutation/presentation_errors.go;
• специализированные тесты, корпус с проверкой парсером и корпус для фаззинга.

6. Тесты

Все тесты следуют AAA.

• Вставка, обновление и удаление записей отображения.
• Блочные формы и замена всего значения в поточной форме.
• Нормализация отдельного отображения и списочной формы последовательности.
• Строки, логические и целочисленные значения, даты, дата со временем.
• LF/CRLF, комментарии, кавычки.
• Дубли ключей и селекторов, псевдонимы, слияния, якоря, теги, сложные ключи.
• Некорректный UTF-8, вложенная поточная форма, смешанные последовательности.
• Байты вызывающей стороны и исходного текста не изменяются.
• Байты вне диапазонов идентичны.
• Семантическая проекция после повторного разбора совпадает точно.
• Отказ содержит типизированную ошибку и позицию; публичный план отсутствует.
• Повторное применение желаемого состояния не создаёт различий.
• Фаззинг: отсутствие паник, диапазоны в пределах исходного текста, результат поддаётся разбору.
• Проверка гонок: параллельное планирование и изменение данных вызывающей стороной.

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

• Примеры поточной формы из исходной спецификации можно изменять заменой всей группы полей.
• Ни один существующий дайджест или семантический контракт операций со связями, перемещением и переименованием не изменился.
• Гарантии сохранения данных доказаны тестами свойств и фаззингом.
• go test -race ./mutation ./store проходит.

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

Публичные операции v0.2, семантическая миграция, среда исполнения и произвольный SetYAML, управляемый вызывающей стороной.