Единица данных GEUL — один документ (DOC). Один файл (.geul, медиатип application/vnd.geul) — один документ.

Структура

DOC-*            ← открывает документ (общая длина)
  Meta …         ← HEAD: записи о документе
  SOURCE …       ←   (происхождение всего документа и его QUALIFIER)
BODY             ← завершает HEAD и открывает BODY
  Reference, Value, Edge …
END              ← закрывает документ
ЗаписьTAGЗначение
DOC-1WORD1C01 + 1 WORDОткрывает документ, задавая общую длину в 1 WORD
DOC-2WORD1C12 + 2 WORDОбщая длина в 2 WORD
DOC-4WORD1C24 + 4 WORDОбщая длина в 4 WORD
BODY1C301 WORD. Завершает HEAD и начинает BODY
END1C401 WORD. Закрывает документ
  • Значение DOC-* — общее число WORD от начала открывающей записи до конца END. Используется самая узкая ширина, в которую значение помещается.
  • END обязателен. Если позиция END не совпадает с длиной DOC-*, документ отвергается. Если ввод закончился без END, документ усечён.
  • Декодер может пропустить весь документ целиком по длине DOC-*.
  • Открыть документ без известной длины нельзя. Данные реального времени, конец которых заранее неизвестен, режутся на единицы известной длины и передаются несколькими документами.
  • Если HEAD пуст, BODY опускается. Документ без записей BODY — это целиком BODY. BODY ставится один раз. Если в HEAD есть хотя бы одна запись (Meta или HEAD Edge), BODY ставится.
  • Документы не вкладываются. На другой документ указывают через IMPORT или Reference-указатель.

HEAD и BODY

  • В HEAD ставятся только Meta и HEAD Edge. Все они — описание документа, который их содержит.
    • Meta: структура, определения, происхождение, родословная, проверка, политика, IMPORT документа.
    • HEAD Edge: Edge основания SOURCE, фиксирующий источник всего документа (Target 0), и QUALIFIER с этим SOURCE в качестве Target (хеш оригинала, время получения, диапазон оригинала и т. п.). QUALIFIER ставится после этого SOURCE.
  • В BODY ставятся только Reference, Value и Edge. Происхождение отдельной записи пишется Edge основания SOURCE внутри BODY, а другие основания, например достоверность, — QUALIFIER, присоединённым к этой записи. SOURCE с Target 0 и QUALIFIER, у которого Target — HEAD SOURCE, в BODY ставить нельзя.
  • Декодер читает HEAD с начала и разделяет записи. Meta — это HEAD. SOURCE с Target 0 — это HEAD, и его Edge Id запоминается. QUALIFIER с запомненным SOURCE в качестве Target — это HEAD. Если приходит любая другая запись, то при пустом HEAD BODY опущен (BODY начинается с этой записи), иначе документ недействителен из-за пропущенного BODY.
  • Edge Id у HEAD и BODY — одно пространство номеров. Он уникален в пределах документа и, как у Edge в BODY, берётся из NEXT-LOCAL-ID. Если Origin у HEAD Edge — LOCAL, его определение ставится в BODY (областью LOCAL является весь документ).
  • Meta может содержать в Payload записи Value. Содержащееся Value — не самостоятельная запись, а часть этого Meta.
  • Область действия объявлений (Meta класса «объявление») — этот документ.

Базовые объявления

Обоих объявлений не больше одного. В каком документе они обязательны, определяют условия ниже.

MetaЗначениеДокумент, где обязательно
SPEC-VERSIONРедакция спецификации, которой следует документ. Определяет, как читать остальные записи. Если редакция неизвестна, документ отвергается или выдаётся предупреждение. У документа v1 значение 0x0001Опубликованный документ. Если нет, декодер читает по известной ему редакции
DOC-IDИдентификатор самого документа. Нужен, чтобы указывать на этот документ и его объекты извнеВерсионный документ в docs/<ID документа>/ и codecs/<Codec ID>/ под .well-known/geul/ (включая документы спецификации). В список версий versions.geul и документы-списки (issuers/) не ставится
  • SPEC-VERSION содержит только одно целое, чтобы его мог прочитать декодер любой редакции (в v1 — 1C51 0001). Он не опирается на код Value.
  • DOC-ID — DOC-POINTER (Issuer, ID документа, версия 0), указывающий на сам документ. ID документа — 4 WORD. У документа Codec нет ID документа, поэтому используется CODEC-POINTER (Issuer, Codec ID, версия 0). Каждый Issuer резервирует ID документа 0x0000000000000000 и 0xFFFFFFFFFFFFFFFF (Issuer и публикация).
  • Документ без DOC-ID — безымянный. На него можно указать только по хешу содержимого.

Хеш содержимого

Один экземпляр документа указывается хешем содержимого (роль такая же, как у ID коммита в git).

  • Это SHA-256 от открывающей записи (DOC-*) до записи непосредственно перед END. 16 WORD.
  • Meta класса проверки (подписи и т. п.; в разделе 15 записи с C >= 5, то есть w >= 0x1E50) исключаются из вычисления. Поэтому размещение подписи внутри документа не создаёт цикла.
  • При вычислении длина DOC-* заменяется длиной без записей проверки, а ширина — самой узкой, подходящей для этой длины. Поэтому хеш содержимого до и после добавления подписи одинаков.
  • Хеш содержимого не записывается в документ, а вычисляется. Его значением пишут только при указании на другую версию (PARENT и др.).
  • PARENT внутри документа тоже входит в вычисление, поэтому хеш содержимого образует цепочку хешей всей истории.
  • Meta, добавленные позже вне документа (например, аннотации в отдельном хранилище), хеш содержимого не меняют (как git notes).
  • Каноническая форма документа — бинарная. Хеш содержимого и подпись вычисляются только по бинарной форме.

Версия

Именованный документ (документ с DOC-ID) имеет версии.

  • ID версии — 2-WORD целое, нумеруемое с 1 в порядке публикации внутри одного документа. 0 означает «версия не указана» и обрабатывается как последняя версия.
  • ID версии назначает публикующая сторона при публикации. Соответствие ID версии и хеша содержимого хранится в списке версий, подписанном публикующей стороной (Адрес публикации и список версий).
  • Одно и то же содержимое повторно не публикуется. Если такой хеш содержимого уже есть, возвращается его ID версии.
  • Когда 2 WORD исчерпаны, документ выпускается под новым ID документа.
  • Версии v2 и далее записывают в HEAD PARENT (хеш содержимого предыдущей версии). Он входит в хеш содержимого, поэтому версии связываются цепочкой хешей. В первую версию он не ставится.

Редакция

Документы GEUL изменяются, как законы.

  • Версия неизменна. Опубликованная версия не изменяется и не удаляется. Исключения — только удаление по закону и удаление по должностному решению (TOMBSTONE).
  • История не стирается. Исправленное выпускается новой версией, исходная версия не перезаписывается (сохранение прежнего закона). Переписанная версия связывается с исходной через REPLACES.
  • Изменяемые указатели вроде branch, HEAD, reflog в документе не ставятся. Они ведутся вне документа (в хранилище или индексе).
  • Новая версия может вводить, изменять и удалять определения. Совместимость с предыдущей версией не обещается. Изменение определения того же термина — тоже редакция (например, «совершеннолетие» в гражданском кодексе Кореи: 20 лет → 19 лет; объект изнасилования в уголовном кодексе: 「부녀」 («женщина») → 「사람」 («человек»)).
  • LOCAL ID — идентичность, переходящая через версии (как номер статьи). Один и тот же LOCAL ID в разных версиях указывает на один и тот же объект.
    • Введение: получается новый LOCAL ID. У ID нет смысла порядка, поэтому вставки вроде 「제X조의2」 («статья X-2») не нужны. Новый номер берётся из NEXT-LOCAL-ID списка версий (auto increment).
    • Изменение: меняется содержимое под тем же LOCAL ID.
    • Удаление: LOCAL ID исключается из новой версии. Удалённый ID повторно не используется.
    • Перенос, разделение, объединение: получается новый LOCAL ID, и к новой записи присоединяется QUALIFIER P1365 (replaces, значение — прежний LOCAL ID), связывающий прежний ID. Прежний ID повторно не используется, поэтому он указывает на эту запись в предыдущей версии.
  • Инструмент, заново создающий документ из исходного материала, тоже соблюдает это правило. Утверждениям, совпадающим с предыдущей версией, даётся тот же LOCAL ID, а новый номер получают только изменённые или новые. Нумеровать каждый раз заново с 1 нельзя.
  • Цитата определяет редакцию. Цитата с зафиксированной версией привязана к этой версии, цитата последней (версия 0) — к действующей версии на момент интерпретации. Документ о прошлых событиях цитирует версию, действовавшую в то время, фиксируя её.
  • Публикация и вступление в силу — разные вещи. Время публикации фиксирует список версий, срок действия — документ.
    • EFFECTIVE-FROM, EFFECTIVE-UNTIL: срок действия всей версии
    • QUALIFIER P580 (начало) и P582 (конец) на Edge статьи: когда у статей разные даты вступления в силу
  • Редакция, действующая в момент T, — это самая высокая версия, дата вступления в силу которой не позже T. Если есть QUALIFIER P580 и P582 по статьям, они имеют приоритет. Редакция, у которой истёк срок действия (EFFECTIVE-UNTIL), не действует.
  • Правила, определяющие, какую редакцию применять (переходные положения «применяется прежнее правило», выбор между законом времени деяния и более благоприятным для подсудимого новым законом), относятся к вердикту (TOULMIN). Сведения о вступлении в силу — материал для него.
  • Сужение или расширение толкования термина разъяснениями и судебными прецедентами — не редакция документа, а правило вердикта. Если толкование установлено законодательно (например, введение определения «1 недели» в Законе о трудовых стандартах Кореи), это редакция.
  • Бинарный (wire) макет Codec и номера Codec не пересматривается. Запись, закодированная номером Codec, читается без фиксации версии кодекбука. Чтобы изменить макет, назначается новый номер. Удалённый номер Codec для другого формата повторно не используется.

Хранение diff

Версия всегда определяется как документ целиком (снимок). diff — лишь формат, позволяющий хранить и передавать этот снимок компактнее.

  • В виде diff можно хранить только документ, у которого есть DOC-ID и все записи BODY — Edge. Для списка версий versions.geul, не содержащего DOC-ID, документов-списков (версий issuers/) и безымянных документов diff не заводится.
  • Документ diff — обычный документ GEUL, в HEAD которого ставится DELTA-BASE (ID базовой версии).
  • Удаление записывается DELTA-REMOVE (список удаляемых LOCAL ID), добавление и изменение — Edge в BODY. Отдельного признака добавления или изменения нет. Если Edge Id есть в базе — это изменение, если нет — добавление.
  • Восстановление снимка должно быть детерминированным (иначе хеш не сойдётся).
    1. Восстанавливается снимок базовой версии. Если база сама diff, она восстанавливается рекурсивно.
    2. HEAD целиком заменяется на HEAD из diff без DELTA-BASE и DELTA-REMOVE. HEAD Edge тоже заменяются вместе с ним (в DELTA-REMOVE не записываются).
    3. BODY сохраняет порядок базы. ID из DELTA-REMOVE удаляются, а если Edge Id из BODY diff есть в базе, запись заменяется на месте.
    4. Edge Id, которых нет в базе, добавляются в конец в том порядке, в котором они встретились в diff.
    5. Хеш содержимого результата должен совпасть с хешем этой версии в списке версий. Если нет, документ недействителен.
  • Повторное использование в diff удалённого LOCAL ID недействительно. Edge Id удалённого HEAD Edge тоже повторно не используется.
  • Хеш содержимого, список версий и подписи — всё считается по восстановленному снимку.