| Пункт | Значение |
|---|---|
| Имя | TRANSFORMED-BY (BIND документа спецификации TRANSFORMED-BY) |
| TAG ID | 0x1D4L |
| Codec ID | 0x00001D40 |
| Документ спецификации | 0x00000000/codecs/0x00001D40/ (цель DECLARE 1D40) |
| Раздел | 14 1110 (Meta), смещение в разделе C = 20 |
| Kind | Meta · класс: родословная |
| TAG WORD | 0001 1101 0100 LLLL (000K KKKC CCCC LLLL) |
| Описание в индексе | Способ преобразования. Инструмент, правила, версия |
| Сторона Hugo | meta/lineage/transformed-by.md |
Поля (документ спецификации)
Порядок FIELD в документе — это порядок полей Payload (Документ спецификации Codec).
| Порядок | Поле (BIND) | FIELD | Ширина | Принимаемый формат (CODEC) | ENUM |
|---|---|---|---|---|---|
| 1 | tool | #2 | запись | любая запись (кроме маркера места) | |
| 2 | version | #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.
- Инструмент из документа инструментов geul.org: EXTERNAL-ISSUER (
- 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.
- Если формат объектов репозитория git — SHA-256, это SHA-256-DIGEST (
- Version обязателен. Запись об инструменте с неизвестной версией исходного кода не может служить основанием для воспроизведения. Если инструмент вне системы контроля версий, используется SHA-256 дистрибутива (SHA-256-DIGEST).
- Version указывает на закоммиченный исходный код. Для документа, созданного из рабочего дерева с незакоммиченными изменениями, ID этого коммита не ставится (рекомендуется, чтобы инструмент отказывался выполняться).
- Если инструмент опирается на код вне репозитория (например, локальную библиотеку, подключённую через Go
replace), этот код тоже записывается отдельным TRANSFORMED-BY. Одного ID коммита инструмента недостаточно, чтобы определить этот код. - Инструмент, который лишь без потерь переносит источник (например, загружает дамп в БД в исходном виде), содержимое документа не определяет, поэтому не записывается. Загрузка с потерями меняет документ, поэтому записывается как инструмент.
- Документ спецификации geul.org (
0x1D40) записывается как два поля-записи: Tool (ширина 0, любой Reference, поэтому CODEC нет) и Version (ширина 0, CODEC07C0,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