ПунктЗначение
ИмяTRANSFORMED-BY (BIND документа спецификации TRANSFORMED-BY)
TAG ID0x1D4L
Codec ID0x00001D40
Документ спецификации0x00000000/codecs/0x00001D40/ (цель DECLARE 1D40)
Раздел14 1110 (Meta), смещение в разделе C = 20
KindMeta · класс: родословная
TAG WORD0001 1101 0100 LLLL (000K KKKC CCCC LLLL)
Описание в индексеСпособ преобразования. Инструмент, правила, версия
Сторона Hugometa/lineage/transformed-by.md

Поля (документ спецификации)

Порядок FIELD в документе — это порядок полей Payload (Документ спецификации Codec).

ПорядокПоле (BIND)FIELDШиринаПринимаемый формат (CODEC)ENUM
1tool#2записьлюбая запись (кроме маркера места)
2version#3запись07C0 SHA-256-DIGEST, 07D0 SHA1-DIGEST

Указывает способ, которым другое представление было преобразовано в этот документ (например, конвертер Викиданных, кодировщик естественного языка). Tool — чем преобразовано, Version — из какого исходного кода этого инструмента. Только при наличии обоих можно воспроизвести тот же документ из того же входа.

Раскладка

TAG WORD          0001 1101 0100 LLLL      Codec 0x1D4L
[Length — расширяющий TAG]
Tool              1 запись Reference (инструмент, правила преобразования)
Version           1 запись Value (SHA-256-DIGEST или SHA1-DIGEST)
  • Codec: Meta 0x1D4L, класс родословной
  • Payload: встроенный Reference (инструмент) + встроенный Value (дайджест версии исходного кода)
  • Количество: может быть несколько (по одному на инструмент)

Интерпретация и валидность

  • Tool — ровно одна полная запись Reference. Можно использовать любой Reference, указывающий на инструмент.
    • Инструмент из документа инструментов geul.org: EXTERNAL-ISSUER (0x00000000, ID документа 0x0001xxxx xxxxxxxx, его LOCAL). Один инструмент — один документ (документ определения терминов Issuer).
    • Если Codec описан документом GEUL, на этот документ Codec указывает CODEC-POINTER.
  • Version — ровно одна полная запись Value, ID объекта системы контроля версий для исходного кода Tool. В случае git это полный ID объекта коммита.
    • Если формат объектов репозитория git — SHA-256, это SHA-256-DIGEST (0x07CL, 16 WORD), если SHA-1 — SHA1-DIGEST (0x07DL, 10 WORD). Формат репозитория проверяется командой git rev-parse --show-object-format.
    • Сокращённые ID (например, 2bd496f) не используются. Value дайджеста не допускает усечённых значений.
    • Не записывается как hex-текст (UTF8-TEXT). То же значение занимает 22 WORD (бинарное 11) для SHA-1 и 34 WORD (бинарное 18) для SHA-256.
  • Version обязателен. Запись об инструменте с неизвестной версией исходного кода не может служить основанием для воспроизведения. Если инструмент вне системы контроля версий, используется SHA-256 дистрибутива (SHA-256-DIGEST).
  • Version указывает на закоммиченный исходный код. Для документа, созданного из рабочего дерева с незакоммиченными изменениями, ID этого коммита не ставится (рекомендуется, чтобы инструмент отказывался выполняться).
  • Если инструмент опирается на код вне репозитория (например, локальную библиотеку, подключённую через Go replace), этот код тоже записывается отдельным TRANSFORMED-BY. Одного ID коммита инструмента недостаточно, чтобы определить этот код.
  • Инструмент, который лишь без потерь переносит источник (например, загружает дамп в БД в исходном виде), содержимое документа не определяет, поэтому не записывается. Загрузка с потерями меняет документ, поэтому записывается как инструмент.
  • Документ спецификации geul.org (0x1D40) записывается как два поля-записи: Tool (ширина 0, любой Reference, поэтому CODEC нет) и Version (ширина 0, CODEC 07C0, 07D0).

Длина

всего = 1 + N_len + N_tool + N_version WORD
  • Курсор после чтения всех последних записей должен точно совпадать с концом Meta.
  • Если Tool — EXTERNAL-ISSUER-2WORD (8 WORD), а Version — SHA1-DIGEST (11 WORD), то всего 1 + 1 + 8 + 11 = 21 WORD, используется расширенная длина. Для SHA-256-DIGEST (18 WORD) всего 28 WORD.

Пример

Ненормативный пример. Инструмент — LOCAL 2 документа инструментов geul.org 0x0001000000000001 (02F7 0000 0000 0001 0000 0000 0001 0002), исходный код — коммит ddc0719974a32aaa7b422ee84221a9721085ce4c (SHA-1).

1D4E 0015
02F7 0000 0000 0001 0000 0000 0001 0002
07DA DDC0 7199 74A3 2AAA 7B42 2EE8 4221 A972 1085 CE4C

Открытые проблемы

  • Стоит ли изменить версию в GENERATED-BY таким же образом (обязательный дайджест или другой формат). Версия модели не является ID коммита.

Связанные страницы

Исходный текст документа спецификации

Документ спецификации 0x00000000/codecs/0x00001D40/latest.geul, прочитанный командой geul show (16-ричные значения в верхнем регистре).

SPEC-VERSION 0x0001
DOC-ID 0x04260000000000001D4000000000
BODY
#1 DECLARE 0x1D40
#2 FIELD #1 record
#3 FIELD #1 record
#4 BIND #1 "TRANSFORMED-BY"
#5 BIND #2 "tool"
#6 BIND #3 "version"
#7 CODEC #3 0x07C0
#8 CODEC #3 0x07D0