Русское издание для чтения. Нормативным источником остаётся оригинал на английском, сверенный с ревизией
61e75e9aa9a8719dfb480bf1f5226553b3a21d70. Перевод не вводит новую редакцию спецификации.
okf-backfill extract -repo PATH -base REF -head REF -out events.json фиксирует обе ссылки как идентификаторы коммитов и выводит события в причинном порядке. По умолчанию обработка слияний следует по первым родителям и сравнивает каждый коммит слияния с его первым родителем. Чтобы включить коммиты боковых веток, укажите -first-parent=false; событие слияния всё равно сравнивается с первым родителем, поэтому анализ должен устранять повторные изменения. Git — единственная внешняя исполняемая программа. Текст коммитов и пути передаются как данные и никогда не подставляются в командную оболочку.
Каждое событие содержит статистику всех изменённых файлов, явную причину пропуска сгенерированных файлов или файлов фиксации зависимостей, число байтов и SHA-256 полного diff включённых файлов, а также ограниченный префикс diff, не обрывающий символы UTF-8. diff_bytes и diff_sha256 описывают полный diff включённых файлов до сокращения для отображения. diff_truncated равно true, если в отображаемом diff отсутствует хотя бы один байт полного diff: из-за ограничения числа байтов или обрезки до границы UTF-8. Содержимое пропущенных файлов никогда не попадает в префикс diff. Анализ для каждого события сверяет число отображаемых байтов с diff_bytes и diff_truncated. Если diff полный, он также сверяет diff_sha256 с отображаемым diff. Для усечённого события полные байты анализу недоступны, поэтому такое сравнение хеша выполнить нельзя.
Переименования сохраняют оба пути и статус; удаления — удалённый путь; двоичные файлы — маркер двоичных данных Git и null вместо количества строк. Диапазоны свыше 100 000 событий, коммиты свыше 10 000 изменённых файлов и метаданные Git свыше 32 МиБ отклоняются с явной ошибкой ограничения, без частичного манифеста. Усечённый префикс служит доказательством только для видимых строк; при ссылке на такое событие аналитик обязан выставить evidence_incomplete. Извлечение не выводит решения, не проверяет реализацию и не читает локальную историю чатов.
Аналитик читает events.json и записывает analysis.json по schemas/analysis.schema.json. Для каждого включённого события требуется одно решение: considered с идентификаторами кандидатов или rejected с причиной. Кандидат называет устойчивую сущность в concept_id, формулирует её текущее утверждение в body и ссылается на точные хеши события и diff. У одной сущности может быть несколько состояний-кандидатов. Последующее состояние указывает идентификаторы предыдущих кандидатов в supersedes и содержит датированную запись истории. В документы выводится только конечное текущее состояние. Если причинность или текущее состояние неясны, выставляется unresolved_conflict; модуль записи пропускает все состояния этого концепта и сообщает о конфликте для проверки человеком. Намерение из текста коммита не доказывает завершение работы. Перед утверждением о поведении программы аналитик должен изучить код или другие свидетельства.
Интеграции Go реализуют backfill.Analyzer, используя собственную модель или поставщика проверки. RunAnalyzer передаёт зафиксированный манифест и проверяет возвращённый анализ. В интерфейсе нет метода записи в набор документов; публикацию выполняет единственный модуль записи.
okf-backfill plan -events events.json -analysis analysis.json -bundle DIR
-out plan.json проверяет манифест и предложение, затем возвращает предлагаемые черновики документов, не изменяя набор. okf-backfill apply использует те же входные данные и дополнительно -plan plan.json -checkpoint checkpoint.json -out report.json. Сохраняйте зафиксированный план для повторных попыток. Единственный модуль записи использует проверки ревизии хранилища, ключи идемпотентности, квитанции и устойчивое восстановление. Прерванный запуск можно повторить с теми же входными данными и контрольной точкой. Модуль записи проверяет хеши зафиксированного манифеста, анализа и плана, а также записанный prompt_version. Он не может изучить текст инструкции аналитика или обнаружить изменение файла схемы без соответствующего изменения сведений о происхождении. При изменении инструкции или семантики схемы оркестратор должен повысить prompt_version, заново создать analysis.json и plan.json и начать новый проверенный запуск вместо повторного использования старой контрольной точки. Изменение ссылок Git, содержимого событий или анализа тоже требует нового плана.
Отчёт о покрытии показывает, что для каждого извлечённого события принято решение. Он не измеряет истинность утверждений. Перед использованием восстановленного черновика проверьте его утверждения и цитаты по текущему коду; протокол не требует отменённого запуска модели из задачи 011. Использование токенов и стоимость записываются только при наличии измеренных значений, предоставленных аналитиком.
Хранилище публикует все активные концепты и корневой индекс одной журналируемой транзакцией. План, содержащий только неразрешённые конфликты, не имеет концептов для публикации; изучите отчёт о покрытии и разрешите конфликты до применения. CLI выбирает профиль моментов времени исходной спецификации, поскольку время коммитов Git имеет формат даты и времени RFC3339. Вложенные идентификаторы концептов создают и обновляют индексы своих каталогов в той же транзакции. Читатели файловой системы, не использующие рекомендательную блокировку корня хранилища, могут наблюдать промежуточную замену файлов; согласованные читатели хранилища видят восстановленный снимок до или после транзакции.