Техническое задание: Транзакционная миграция OKF v0.1 → v0.2

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

1. Цель

Добавить детерминированный план миграции с предварительным просмотром и применением для двух несовместимых изменений v0.2:

• timestamp → generated;
• # Citations → sources + сноски с ключами.

Зависимости: task10.md, task11.md, task13.md, task14.md, task17.md.

2. Общий контракт

• Предварительный просмотр по умолчанию доступен только для чтения.
• Применение требует точной базовой ревизии и дайджеста плана.
• Весь пакет изменяется одной транзакцией; частичная миграция запрещена.
• Неизвестные метаданные в начале документа, содержимое документа и ресурсы сохраняются.
• Корневой okf_version меняется последним, после валидации по целевой версии v0.2.
• Повторный идентичный запуск ничего не меняет либо является идемпотентным повтором.

3. Миграция timestamp

Создавать generated только с явно заданным generated.by. Не использовать ChangeSet.Actor как неявного производителя.

Варианты:

• generated отсутствует, timestamp присутствует → скопировать в generated.at;
• оба отсутствуют → нужны явные значения; никакого time.Now();
• эквивалентный generated уже существует → без изменений;
• конфликт timestamp/generated.at → блокирующая проблема, если нет явной политики;
• политика удаления устаревшего поля: preserve или remove_after_copy;
• дублирующиеся узлы, узлы слияния или узлы с неоднозначной принадлежностью комментариев → отказ.

4. Миграция цитирований

Нельзя угадывать происхождение данных или привязку утверждений к источникам по смыслу.

Входные данные должны содержать явное соответствие между устаревшей записью и стабильным ID источника.

Поддержать:

• [1] [Title](https://github.com/skosovsky/okf/blob/61e75e9/docs/development/v0.2/tasks/URL);
• форму маркированного списка с URL из исходной спецификации;
• явные ID, заголовок и ресурс;
• замену только доказанных числовых маркеров;
• создание определений сносок с ключами;
• удаление # Citations только после успешного сопоставления всех записей.

Отклонять операцию при:

• нескольких разделах Citations;
• дублировании номеров или меток;
• неразрешимой записи или маркере утверждения;
• конфликтующем определении сноски;
• неоднозначной принадлежности Markdown.

Не генерировать title/author/usage/last_modified/verified/status/stale_after.

5. Сбор данных из Markdown

Добавить определение принадлежности на основе парсера для:

• диапазонов разделов;
• записей цитирования;
• ссылок на сноски и их определений;
• коллизий нормализованных меток;
• заголовка # Computation и ограждённого блока кода.

Ограждённый и встроенный код, а также исходный HTML остаются непрозрачными. Не менять глобально существующую конфигурацию парсера MoveConcept.

6. Граница миграции Attested Computation

Не разбивать повествовательный документ автоматически и не превращать SQL в обычном тексте в Attested Computation.

Разрешить только явный план создания или перемещения:

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

7. Тесты

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

• Каноническое приложение v0.1 → v0.2.
• Пробный запуск оставляет байты неизменными.
• Политики и конфликты timestamp, валидация акторов.
• URL и пути цитирований, явное сопоставление.
• Несколько разделов, дубли ID, маркеры в коде и исходном HTML.
• CRLF/LF, комментарии, YAML в поточной форме.
• Один некорректный файл приводит к отсутствию записей.
• Конфликт ревизий, несовпадение плана, параллельная запись.
• Сбой и восстановление оставляют только исходное или итоговое состояние.
• Повторная миграция ничего не меняет.
• Побайтовое сохранение источников, содержимого документа и неизвестных расширений.
• Валидация по целевой версии v0.2 проходит.

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

• Безопасные случаи мигрируются транзакционно и без потери данных.
• Неоднозначные случаи возвращают блокирующие проблемы или действия для ручного выполнения.
• Проверка, доверие, свежесть данных и актор не выводятся по предположению.
• Корневая версия не меняется до полной предварительной проверки.
• CLI/MCP используют один планировщик.
• Проверки гонок, восстановления и весь набор тестов проходят.

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

Переписывание с помощью LLM, семантическое сопоставление утверждений, автоматическое разделение SQL, среда исполнения, ABI аттестации и загрузка по сети.