ItemValue
NameTRANSFORMED-BY (spec document BIND TRANSFORMED-BY)
TAG ID0x1D4L
Codec ID0x00001D40
Spec document0x00000000/codecs/0x00001D40/ (DECLARE target 1D40)
Section14 1110 (Meta), offset within section C = 4
KindMeta · class: lineage
TAG WORD0001 1101 0100 LLLL (000K KKKC CCCC LLLL)
Index descriptionConversion method. Tool, rules, version
Hugo sidemeta/lineage/transformed-by.md

Fields (spec document)

The order of FIELDs within the document is the order of Payload fields (Codec spec document).

OrderField (BIND)FIELDWidthAccepted form (CODEC)ENUM
1tool#2recordany record (except slot markers)
2version#3record07C0 SHA-256-DIGEST, 07D0 SHA1-DIGEST

Records how this document was converted from another representation (for example, a Wikidata converter, a natural-language encoder). Tool is what it was converted with; Version is which source of that tool it was converted with. Both are needed to reproduce the same document from the same input.

Layout

TAG WORD          0001 1101 0100 LLLL      Codec 0x1D4L
[Length extension TAG]
Tool              1 Reference record (conversion tool, rules)
Version           1 Value record (SHA-256-DIGEST or SHA1-DIGEST)
  • Codec: Meta 0x1D4L, lineage class
  • Payload: embedded Reference (tool) + embedded Value (source version digest)
  • Count: several allowed (one per tool)

Interpretation and validity

  • Tool is exactly one complete Reference record. Any Reference that points at a tool can be used.
    • A tool in a geul.org tool document: EXTERNAL-ISSUER (0x00000000, document ID 0x0001xxxx xxxxxxxx, its LOCAL). One document per tool (the term-definition document of the Issuer).
    • If the codec is a GEUL document, point at that codec document with CODEC-POINTER.
  • Version is exactly one complete Value record and is the version-control object ID of the Tool’s source. For git, it is the full commit object ID.
    • If the git repository’s object format is SHA-256, use SHA-256-DIGEST (0x07CL, 16 WORD); if SHA-1, SHA1-DIGEST (0x07DL, 10 WORD). Check the repository format with git rev-parse --show-object-format.
    • Do not use abbreviated IDs (such as 2bd496f). The digest Values do not allow truncated values.
    • Do not write it as hex text (UTF8-TEXT). The same value takes 22 WORD (11 binary) in SHA-1 and 34 WORD (18 binary) in SHA-256.
  • Version is required. A tool record with an unknown source version cannot serve as a basis for reproduction. For a tool outside version control, use the SHA-256 of the distributed artifact (SHA-256-DIGEST).
  • Version points at committed source. Do not write a commit ID for a document made from a working tree with uncommitted changes (it is recommended that the tool refuse to run).
  • If the tool depends on code outside the repository (for example, a local library pointed at by a Go replace), write that code separately with TRANSFORMED-BY. The tool’s commit ID alone does not fix that code.
  • A tool that only carries the source over losslessly (for example, one that loads a dump into a DB verbatim) does not determine the document content, so it is not written. A non-lossless load changes the document, so write it as a tool.
  • The geul.org spec document (0x1D40) writes this as a two-record-field spec: Tool (width 0, any Reference so no CODEC) and Version (width 0, CODEC 07C0, 07D0).

Length

Total = 1 + N_len + N_tool + N_version WORD
  • After reading the last record, the cursor must coincide exactly with the end of the Meta.
  • If Tool is EXTERNAL-ISSUER-2WORD (8 WORD) and Version is SHA1-DIGEST (11 WORD), the total is 1 + 1 + 8 + 11 = 21 WORD, using the extended length. With SHA-256-DIGEST (18 WORD) it is 28 WORD.

Example

A non-normative example. The tool is LOCAL 2 of the geul.org tool document 0x0001000000000001 (02F7 0000 0000 0001 0000 0000 0001 0002), and the source is commit ddc0719974a32aaa7b422ee84221a9721085ce4c (SHA-1).

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

Open issues

  • Whether to change the version of GENERATED-BY the same way (a required digest or another format). A model version is not a commit ID.

Related pages

Spec document source

The spec document 0x00000000/codecs/0x00001D40/latest.geul as read with geul show (hex in uppercase).

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