ItemValue
NameDELTA-BASE (spec document BIND DELTA-BASE)
TAG ID0x1DBL
Codec ID0x00001DB0
Spec document0x00000000/codecs/0x00001DB0/ (DECLARE target 1DB0)
Section14 1110 (Meta), offset within section C = 11
KindMeta · class: lineage
TAG WORD0001 1101 1011 LLLL (000K KKKC CCCC LLLL)
Index descriptionThis version file is a diff against a base version (2 WORD version ID) of the same document (git packfile delta)
Hugo sidemeta/lineage/delta-base.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
1version#2raw value 2 WORD0620 UNSIGNED-INTEGER

A marker that this version file is not a snapshot but a diff against a base version of the same document (delta in a git packfile). The version itself is still defined as a snapshot. The content hash, the version list, and signatures are all based on the snapshot restored by applying the diff (diff storage).

Layout

TAG WORD          0001 1101 1011 LLLL      Codec 0x1DBL
Version ID        2 WORD unsigned (base version of the same document)
  • Codec: Meta 0x1DBL, lineage class
  • Payload: 2 WORD version ID (raw value)
  • Count: at most one

Interpretation and validity

  • Use it only on documents that have a DOC-ID. The version list versions.geul, list documents (versions of issuers/), and unnamed documents, which carry no DOC-ID, have no diff.
  • The base version is a published version of the same DOC-ID and precedes this version. 0 (no version) is invalid.
  • The content hash of the restored snapshot must equal the hash of this version in the version list (PUBLICATION). If it differs, this diff is invalid. So the resulting hash is not written separately inside the diff.
  • Only a document whose BODY records are all Edges (records with an Edge Id) can be kept as a diff, because the diff unit is the LOCAL ID (Edge Id).
  • The snapshot restoration rules follow diff storage. Deletion is carried by DELTA-REMOVE.
  • There is no separate addition or revision marker. If the Edge Id in the diff BODY exists in the base, it is a revision; if not, an addition. An addition receives its number from NEXT-LOCAL-ID of the version list. Reusing a deleted LOCAL ID is invalid (revision).

Example

A diff against base version 3:

1DB2 0000 0003
  • TAG 1DB2 (Meta 0x1DBL, LLLL=0010, 3 WORD), version ID 0000 0003.

Open issues

  1. Snapshot interval: how many versions apart to keep a full snapshot (diff chain length versus restoration cost).
  2. Whether to restrict the base version to the immediately preceding version.
  3. Where to store diff files: in the version file slot (<version ID>.geul), and the relation to the content-hash address <Issuer>/hashes/ (hashes/ is looked up by the content hash of the snapshot).

Spec document source

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

SPEC-VERSION 0x0001
DOC-ID 0x04260000000000001DB000000000
BODY
#1 DECLARE 0x1DB0
#2 FIELD #1 0x0002
#3 BIND #1 "DELTA-BASE"
#4 BIND #2 "version"
#5 CODEC #2 0x0620