وحدة بيانات 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 فهو مستند مقطوع.
  • يستطيع الـ decoder أن يتجاوز المستند كله دفعة واحدة بطول 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 الذي يجعل SOURCE في HEAD هو Target في BODY.
  • يقرأ الـ decoder HEAD من أوله ويفرز. Meta من HEAD. وSOURCE ذو Target 0 من HEAD، ويحفظ Edge Id الخاص به. وQUALIFIER الذي يجعل SOURCE المحفوظ هو Target من HEAD. وإذا جاء سجل غير ذلك: فإن كان HEAD فارغاً فقد حُذف BODY (يبدأ BODY من ذلك السجل)، وإلا فهو invalid لغياب BODY.
  • يستخدم HEAD وBODY فضاء أرقام واحداً لـ Edge Id. وهو فريد داخل المستند، ويُؤخذ من NEXT-LOCAL-ID كما في Edge الخاص بـ BODY. وإذا كان Origin في HEAD Edge هو LOCAL فيوضع تعريفه في BODY (نطاق LOCAL هو المستند كله).
  • يمكن أن يحتوي Meta في Payload سجلات Value. وValue المحتواة ليست سجلاً مستقلاً بل جزء من ذلك Meta.
  • نطاق الإعلان (فئة التعريف في Meta) هو ذلك المستند.

الإعلانات الأساسية

كلا الإعلانين لا يزيد على واحد. والشروط الآتية تحدد في أي مستند يجب وجودهما.

Metaالمعنىالمستند الذي يجب أن يوجد فيه
SPEC-VERSIONنسخة المواصفة المتَّبعة. تحدد كيف تُقرأ بقية السجلات. إذا كانت النسخة مجهولة رُفض أو حُذِّر. قيمته في مستند v1 هي 0x0001المستند المنشور. وإن غاب قُرئ بالنسخة التي يعرفها الـ decoder
DOC-IDمعرّف المستند نفسه. يجب وجوده للإشارة إلى هذا المستند وما فيه من خارجهمستند الإصدار في docs/<معرّف المستند>/ وcodecs/<معرّف Codec>/ تحت .well-known/geul/ (بما فيه مستند المواصفة). ولا يوضع في قائمة الإصدارات versions.geul ولا في مستند القوائم (issuers/)
  • لا يحمل SPEC-VERSION إلا عدداً صحيحاً واحداً ليقرأه decoder من أي نسخة (في v1 هو 1C51 0001). ولا يعتمد على رمز Value.
  • DOC-ID هو DOC-POINTER يشير إلى المستند نفسه (Issuer ومعرّف المستند والإصدار 0). ومعرّف المستند 4 WORD. ومستند Codec لا معرّف مستند له، فيستخدم CODEC-POINTER (Issuer ومعرّف Codec والإصدار 0). وتحجز كل Issuer معرّفَي المستند 0x0000000000000000 و0xFFFFFFFFFFFFFFFF (Issuer والنشر).
  • المستند الذي بلا DOC-ID مستند بلا اسم. ولا يمكن الإشارة إليه إلا بتجزئة المحتوى.

تجزئة المحتوى

تُحدَّد نسخة المستند الواحدة بـتجزئة المحتوى (بمنزلة معرّف الـ commit في git).

  • هي SHA-256 من السجل الفاتح (DOC-*) حتى ما قبل END مباشرة. 16 WORD.
  • يُستبعد من الحساب Meta من فئة التحقق (التوقيع وغيره، أي السجلات التي C >= 5 في القسم 15، أي w >= 0x1E50). ولهذا لا تنشأ حلقة إذا وُضع التوقيع داخل المستند.
  • عند الحساب يُستبدل طول DOC-* بالطول بعد استبعاد سجلات التحقق، ويُستبدل عرضه بأضيق عرض يلائم ذلك الطول. ولهذا تتساوى تجزئة المحتوى قبل إلحاق التوقيع وبعده.
  • لا تُسجَّل تجزئة المحتوى في المستند بل تُحسب. ولا تُكتب قيمةً إلا عند الإشارة إلى إصدار آخر (PARENT وغيره).
  • يدخل PARENT الموجود في المستند في الحساب أيضاً، فتصير تجزئة المحتوى سلسلة تجزئات تصل التاريخ كله.
  • لا يغيّر Meta الذي يُلحق لاحقاً من خارج المستند (كتعليق في مستودع منفصل) تجزئةَ المحتوى (كما في git notes).
  • النسخة الثنائية هي الأصل المعتمد للمستند. وتُحسب تجزئة المحتوى والتوقيع من النسخة الثنائية فقط.

الإصدار

للمستند المسمّى (الذي له DOC-ID) إصدارات.

  • معرّف الإصدار عدد صحيح من 2 WORD يُرقَّم من 1 بترتيب النشر داخل مستند واحد. و0 تعني “عدم كتابة الإصدار” ويُعامل على أنه أحدث إصدار.
  • تخصص جهة النشر معرّف الإصدار عند النشر. أما التناظر بين معرّف الإصدار وتجزئة المحتوى فيوضع في قائمة الإصدارات الموقَّعة من جهة النشر (عنوان النشر وقائمة الإصدارات).
  • لا يُعاد نشر المحتوى نفسه. فإذا كانت تجزئة المحتوى موجودة فعلاً أُعيد معرّف إصدارها.
  • إذا استُنفدت الـ 2 WORD صدر المحتوى بمعرّف مستند جديد.
  • تكتب الإصدارات من v2 فصاعداً في HEAD القيمة PARENT (تجزئة محتوى الإصدار السابق مباشرة). ولأنها تدخل في تجزئة المحتوى تتصل الإصدارات بسلسلة تجزئات. ولا توضع في الإصدار الأول.

التنقيح

تُنقَّح مستندات GEUL كما تُنقَّح القوانين.

  • الإصدار ثابت لا يتغير. لا يُغيَّر الإصدار المنشور ولا يُحذف. والاستثناء الوحيد هو الحذف القانوني والحذف بحكم الوظيفة (TOMBSTONE).
  • لا يُمحى التاريخ. يصدر ما صُحِّح إصداراً جديداً، ولا يُكتب فوق الإصدار الأصلي (حفظ القانون القديم). ويصل الإصدار المعاد كتابته بالإصدار الأصلي عبر REPLACES.
  • لا توضع في المستند المؤشرات المتغيرة كـ branch وHEAD وreflog. بل تُدار خارج المستند (في المستودع أو الفهرس).
  • يجوز للإصدار الجديد استحداث التعريفات أو تنقيحها أو حذفها. ولا يَعِد بالتوافق مع الإصدار السابق. وتغيّر تعريف المصطلح نفسه تنقيح أيضاً (مثل: “البالغ” في القانون المدني الكوري من 20 سنة إلى 19 سنة، وموضوع جريمة الاغتصاب في القانون الجنائي الكوري من “المرأة” إلى “الشخص”).
  • LOCAL ID هوية تعبر الإصدارات (كرقم المادة). فالـ LOCAL ID نفسه يشير إلى الهدف نفسه وإن اختلفت الإصدارات.
    • الاستحداث: يُؤخذ LOCAL ID جديد. ولأن الـ ID لا معنى لترتيبه فلا حاجة إلى الإدراج بين الأرقام مثل “المادة X مكرر”. ويُؤخذ الرقم الجديد من 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). ومعلومات النفاذ مادتها.
  • تضييق التفسيرات والسوابق القضائية معنى المصطلح أو توسيعها له ليس تنقيحاً للمستند بل قاعدة حكم. أما إذا حُدد التفسير بالتشريع (مثل: استحداث تعريف “الأسبوع” في قانون معايير العمل) فهو تنقيح.
  • التخطيط الثنائي (wire) لـ Codec ولأرقام Codec لا يُنقَّح. لأن السجلات المرمَّزة برقم Codec تُقرأ دون تثبيت إصدار codebook. ولتغيير التخطيط يُخصَّص رقم جديد. ولا يُعاد استخدام رقم Codec المحذوف لصيغة أخرى.

تخزين الفروق diff

يُعرَّف الإصدار دائماً بالمستند كله (لقطة snapshot). والـ diff ليس إلا صيغة لتخزين تلك اللقطة أو إرسالها بحجم أقل.

  • لا يجوز تخزين مستند بالـ diff إلا إذا كان له DOC-ID وكان BODY كله Edge. ولا يوضع diff في قائمة الإصدارات versions.geul التي لا تضع DOC-ID، ولا في مستند القوائم (إصدار issuers/)، ولا في المستند المجهول الاسم.
  • مستند الـ diff مستند GEUL عادي، ويوضع في HEAD الخاص به DELTA-BASE (معرّف إصدار الأساس).
  • يُكتب الحذف بـ 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. يجب أن تساوي تجزئة محتوى الناتج تجزئةَ هذا الإصدار في قائمة الإصدارات. وإن اختلفت فهو invalid.
  • إعادة استخدام LOCAL ID محذوف في الـ diff invalid. ولا يُعاد استخدام Edge Id الخاص بـ HEAD Edge المحذوف أيضاً.
  • تجزئة المحتوى وقائمة الإصدارات والتوقيع كلها على أساس اللقطة المستعادة.