دليل تأليف مخطط المزود (مستقل)

هذا المستند يهدف إلى أن يكون شاملاً ومستقلاً. يمكنك رفع هذا الملف بمفرده لصياغة عقد مزود بوابة القرار بصيغة JSON، لكن الدقة لا تزال تعتمد على التحقق وتنفيذ المزود الخاص بك.

إذا كنت ستتذكر جملة واحدة فقط: بوابة القرار تقيم الأدلة. إنها لا تنفذ مهام عشوائية.

---

1) ما هو بوابة القرار (الهدف والنموذج الذهني)

قرار البوابة (DG) يجيب على سؤال واحد: “هل تم تنفيذ X؟”

يتم ذلك من خلال تقييم الأدلة مقابل الشروط، ودمج النتائج مع شجرة تقييم المتطلبات (RET)، واتخاذ القرار بشأن ما إذا كانت البوابة قد نجحت.

DG هو البيانات أولاً:

• الأدوات أو السكربتات أو الخدمات التي تعمل خارج DG.
• هذه الأدوات تصدر أدلة (JSON أو بايتات).
• يقوم DG بتقييم الأدلة بشكل حتمي.

خط أنابيب التقييم الأساسي

EvidenceQuery -> Provider -> EvidenceResult -> Comparator -> Tri-state
               -> RET -> Gate outcome

• نتائج ثلاثية الحالة هي true، false، أو unknown.
• الدليل المفقود أو خطأ المزود يؤدي إلى unknown (فشل مغلق).
• Comparator type mismatches may yield unknown or false/true depending on the قد تؤدي عدم تطابق نوع المقارنات إلى unknown أو false/true اعتمادًا على المقارن (انظر القسم 7).
• تمر البوابات فقط عندما يتم تقييم RET إلى true.

أوضاع جمع الأدلة

1. Provider-pulled evidence (live runs)
   • DG يتصل بمزود لجلب الأدلة.
2. Asserted evidence (precheck only)
   • المتصل يقدم الدليل مباشرة؛ لا يتم تغيير حالة التشغيل.
3. Audit submissions (scenario_submit)
   • مخزنة للتدقيق، لكنها لا تؤثر على التقييم.

يركز هذا الدليل على المزودين و عقود المزودين.

---

2) المعجم (المصطلحات الأساسية)

• المزود: مصدر بيانات يمكنه الإجابة على استفسارات الأدلة.
• Provider contract: A JSON document describing provider capabilities, عقد المزود: مستند JSON يصف قدرات المزود، المخططات، والمقارنات المسموح بها (هذا ما تقوم بتأليفه).
• Provider check: A single queryable capability exposed by a provider. تحقق من المزود: قدرة قابلة للاستعلام واحدة مكشوفة من قبل مزود. تتحقق المزودات داخل عقد المزود تحت checks.
• Scenario condition: A condition in a ScenarioSpec that references a شرط السيناريو: شرط في ScenarioSpec يشير إلى فحص مزود عبر query.check_id. لا تخلط بين هذين المفهومين.
• EvidenceQuery: { provider_id, check_id, params } المرسلة إلى مزود الخدمة.
• EvidenceResult: استجابة المزود مع value بالإضافة إلى تجزئة/مرساة اختيارية.
• المقارن: عامل يقارن الأدلة بالقيمة المتوقعة.
• RET: شجرة تقييم المتطلبات التي تجمع نتائج الشروط.
• Determinism: Classification of provider checks:
  • حتمي، يعتمد على الوقت، أو خارجي.

---

3) بروتوكول المزود (ما يفعله المزودون فعليًا)

يطبق المزودون أداة MCP واحدة تُسمى evidence_query ويعيدون EvidenceResult داخل استجابة الأداة.

شكل EvidenceQuery

{
  "provider_id": "string",
  "check_id": "string",
  "params": { "any": "json" }
}

• params اختياري. إذا كان موجودًا، يجب أن يتطابق مع params_schema الخاص بالتحقق.
• تتطلب معظم المزودات المدمجة أن تكون params كائن JSON.

شكل نتيجة الدليل (القيمة هي ما يصفه عقدك)

{
  "value": { "kind": "json|bytes", "value": "any" } | null,
  "lane": "verified|asserted",
  "error": { "code": "string", "message": "string", "details": "any|null" } | null,
  "evidence_hash": { "algorithm": "sha256", "value": "hex" } | null,
  "evidence_ref": { "uri": "string" } | null,
  "evidence_anchor": { "anchor_type": "string", "anchor_value": "string" } | null,
  "signature": { "scheme": "string", "key_id": "string", "signature": [0] } | null,
  "content_type": "string|null"
}

ملاحظات:

• جميع الحقول مطلوبة في المخطط؛ استخدم null عند الغياب.
• evidence_anchor.anchor_value is a string. If an anchor policy requires evidence_anchor.anchor_value هو سلسلة نصية. إذا كانت سياسة الربط تتطلب حقولًا، يجب أن تكون هذه السلسلة نصًا JSON قياسيًا لكائن (انظر القسم 9).
• signature.signature هو مصفوفة بايت (مصفوفة JSON من الأعداد الصحيحة 0-255).

يجب أن يصف عقد المزود params وشكل value المعاد هنا. لا تثق DG أبداً بالمزودين لتحديد نتائج البوابة.

---

4) ما هو عقد المزود (لماذا يوجد)

عقد المزود (عقد القدرة) هو نموذج الأدلة. يعلن:

• ما هي فحوصات المزود المتاحة (الأسماء + الوصف).
• المعلمات المطلوبة لكل فحص.
• مخططات النتائج لكل فحص.
• أي المقارنات مسموح بها لكل فحص.
• تصنيف الحتمية، المراسي، أنواع المحتوى، والأمثلة.

تستخدم DG العقد لـ:

• التحقق من شروط ScenarioSpec.
• فرض قوائم السماح للمقارنات لكل فحص.
• توليد أدوات ونماذج واجهة المستخدم.
• دعم اكتشاف LLMs وأدوات التأليف.

إذا كان عقد المزود خاطئًا أو غير مكتمل، سيكون تأليف السيناريو خاطئًا، وسيفشل التقييم مغلقًا.

---

5) عقد مزود JSON: المواصفات الكاملة

عقد هو كائن JSON واحد يحتوي على الحقول المطلوبة التالية. الحقول المميزة بأنها اختيارية يمكن أن تُحذف.

5.1 الحقول العليا (مطلوبة ما لم يُذكر خلاف ذلك)

• provider_id (string, required)

  • معرف ثابت مستخدم في EvidenceQuery.provider_id.
  • استخدم snake_case واحتفظ به مستقرًا.

• name (string, required)

  • اسم قابل للقراءة البشرية لواجهة المستخدم والأدوات.

• description (string, required)

  • ما هو مصدر الأدلة الذي يمثله هذا المزود.

• transport (string, required)

  • يجب أن تكون إما “mcp” (مقدمو الخدمة الخارجيون) أو “builtin” (المكونات المدمجة).
  • يجب أن تحدد عقود مزودي الخدمة الخارجيين النقل: “mcp” وإلا سيتم رفضها.

• notes (array of strings, required)

  • ملاحظات حرة للبشر و LLMs.
  • استخدم [] إذا لم تكن هناك ملاحظات.

• config_schema (JSON Schema, required)

  • مخطط لكتلة تكوين المزود في decision-gate.toml.
  • The contract schema accepts any JSON Schema value, but **Decision Gate tooling مخطط العقد يقبل أي قيمة من مخطط JSON، لكن أدوات بوابة القرار تفترض مخطط كائن. استخدم مخطط كائن مع additionalProperties: false.
  • If the provider has no config, use:

    { "type": "object", "additionalProperties": false, "properties": {} }
    

• checks (array, required)

  • كل إدخال هو تعريف لفحص المزود.
  • قد تكون الـ array فارغة، ولكن في هذه الحالة لا يقدم المزود أي فحوصات قابلة للاستخدام.

5.2 تحقق من الحقول (جميعها مطلوبة)

كل إدخال في checks يحدد فحص مزود واحد.

• check_id (string)

  • معرف ثابت يستخدم في EvidenceQuery.check_id.
  • استخدم snake_case واحتفظ به مستقرًا.

• description (string)

  • صف ما يعنيه القيمة المعادة، وليس كيف يتم جلبها.

• determinism (string)

  • واحد من: حتمي، يعتمد على الوقت، خارجي.

• params_required (boolean)

  • صحيح إذا كان يجب توفير المعلمات؛ خطأ إذا كانت المعلمات اختيارية أو غير موجودة.

• params_schema (JSON Schema)

  • مخطط لـ EvidenceQuery.params.
  • استخدم مخطط كائن واضبط additionalProperties: false (موصى به).
  • If no params, use:

    { "type": "object", "additionalProperties": false, "properties": {} }
    

• result_schema (JSON Schema)

  • مخطط لقيمة الدليل (EvidenceResult.value.value).
  • استخدم أقرب مخطط ممكن.

• allowed_comparators (array of strings)

  • قائمة السماح لمقارنات هذا الفحص.
  • يجب أن تكون غير فارغة ومرتبة في الترتيب القياسي (انظر قائمة القسم 7).
  • يجب أن يكون متوافقًا مع result_schema وقواعد التحقق الصارمة.

• anchor_types (array of strings)

  • أنواع المراسي التي قد يصدرها هذا الفحص.
  • استخدم [] إذا لم يكن هناك أي شيء.

• content_types (array of strings)

  • أنواع MIME لـ EvidenceResult.content_type.
  • يمكن أن تكون فارغة ([]) لتعني “غير محدد”.
  • إذا كانت موجودة، استخدم أنواع MIME صالحة (مثل، application/json).

• examples (array of objects)

  • كل مثال هو { “description”: ”…”, “params”: { … }, “result”: … }.
  • يسمح المخطط بمصفوفة فارغة، ولكن يُوصى بشدة بتقديم أمثلة.

---

6) إرشادات مخطط JSON (المعلمات والنتائج)

يستخدم DG مخطط JSON (مسودة 2020-12) للتحقق من صحة المعلمات والنتائج. احتفظ بالمخططات دقيقة و بسيطة.

قواعد مخطط المعلمات (موصى به)

• استخدم type: "object".
• تعيين additionalProperties: false.
• أعلن عن required لكل حقل مطلوب.
• يفضل استخدام الأنواع والحدود الصريحة.

قواعد مخطط النتائج

• وصف قيمة الدليل الفعلية، وليس غلاف EvidenceResult.
• Use the narrowest possible type (boolean, integer, number, string, استخدم أضيق نوع ممكن (boolean, integer, number, string, array, object, أو null).
• If you need multiple types, use oneOf / anyOf. Strict validation إذا كنت بحاجة إلى أنواع متعددة، استخدم oneOf / anyOf. تتقاطع التحقق الصارم مع السماحات المقارنة عبر جميع المتغيرات.

نتائج البايتات (حالة خاصة)

إذا أعاد المزود EvidenceValue::Bytes، تتم مقارنة قيمة الدليل كبايت. المخطط الموصى به:

{
  "type": "array",
  "items": { "type": "integer", "minimum": 0, "maximum": 255 }
}

بالنسبة للأدلة البايتية، فقط equals و not_equals هما الصالحان في وقت التشغيل. قم بتقييد allowed_comparators وفقًا لذلك.

النتائج الديناميكية (مخرج الطوارئ)

إذا كان بإمكان الفحص إرجاع أشكال JSON عشوائية لا يمكن التعبير عنها، قم بتحديد مخطط النتيجة على أنه ديناميكي:

{
  "description": "Dynamic JSON result",
  "x-decision-gate": { "dynamic_type": true }
}

تسمح المخططات الديناميكية لجميع المقارنات في التحقق الصارم، ولكن لا تزال المقارنات lex/deep تتطلب علامات تكوين (انظر القسم 8).

---

7) دلالات المقارنات والتوافق

المقارنات تحول الأدلة إلى نتائج ثلاثية الحالة. بالنسبة للمقارنات التي تتطلب expected، فإن عدم وجود expected يؤدي إلى unknown.

قائمة المقارنات (ترتيب قياسي)

• يساوي
• لا_تساوي
• أكبر من
• أكبر من أو يساوي
• أقل من
• أقل من أو يساوي
• lex_greater_than
• lex_greater_than_or_equal
• lex_less_than
• lex_less_than_or_equal
• يحتوي على
• in_set
• عميق_يساوي
• deep_not_equals
• يوجد
• لا_يوجد

استخدم هذا الترتيب عند تأليف allowed_comparators.

دلالات وقت التشغيل (جوهر بوابة القرار)

• equals / not_equals: JSON equality. Numbers are compared as decimals يساوي / لا يساوي: مساواة JSON. يتم مقارنة الأرقام كأرقام عشرية (10 == 10.0). تعود عدم تطابق الأنواع بـ false / true على التوالي.
• greater_than / less_than (and _or_equal):
  • ترتيب رقمي لأرقام JSON.
  • Temporal ordering for strings that parse as RFC3339 date-time or date-only ترتيب زمني للسلاسل التي يتم تحليلها كـ RFC3339 تاريخ-وقت أو تاريخ فقط (YYYY-MM-DD) على كلا الجانبين. خلاف ذلك غير معروف.
• lex_*: ترتيب معجمي للسلاسل فقط؛ وإلا unknown.
• contains:
  • سلاسل: احتواء الجزء الفرعي.
  • Arrays: evidence array contains all elements of the expected array المصفوفات: تحتوي مصفوفة الأدلة على جميع عناصر المصفوفة المتوقعة (عضوية فقط، وليس عدادات متعددة المجموعات).
• in_set:
  • يجب أن يكون المتوقّع مصفوفة.
  • يجب أن تكون الأدلة عددية (ليست كائن/مصفوفة). العضوية تستخدم مساواة JSON.
• exists / not_exists:
  • تجاهل المتوقع.
  • تحقق فقط مما إذا كانت EvidenceResult.value موجودة.
  • تعتبر JSON null موجودة.
• deep_equals / deep_not_equals:
  • فقط للمصفوفات أو الكائنات؛ وإلا غير معروف.

توافق التحقق الصارم (افتراضي في decision-gate-mcp)

بوابة القرار MCP تقوم بإجراء تحقق صارم من المقارنات/الأنواع بشكل افتراضي. يجب أن يكون لمقارن ScenarioSpec:

1. أن تكون موجودة في قائمة allowed_comparators لعقد المزود.
2. أن يُسمح به من خلال تصنيف نوع مخطط النتيجة.
3. تمكينه بواسطة التكوين (عائلات lex/deep معطلة بشكل افتراضي).

بدلات حسب نوع مخطط النتائج (التحقق الصارم):

• boolean

  • مسموح: equals, not_equals, in_set, exists, not_exists

• integer / number

  • Allowed: equals, not_equals, greater_than, greater_than_or_equal, مسموح: equals، not_equals، greater_than، greater_than_or_equal، less_than، less_than_or_equal، in_set، exists، not_exists

• string (no format)

  • مسموح: equals, not_equals, contains, in_set, exists, not_exists
  • الاشتراك: lex_* (انظر القسم 8)

• string with format: "date" or format: "date-time"

  • Allowed: equals, not_equals, greater_than, greater_than_or_equal, مسموح: equals، not_equals، greater_than، greater_than_or_equal، less_than، less_than_or_equal، in_set، exists، not_exists

• string with format: "uuid"

  • مسموح: equals, not_equals, in_set, exists, not_exists

• enum (scalar values only)

  • مسموح: equals, not_equals, in_set, exists, not_exists

• array with scalar items

  • مسموح: contains، exists، not_exists
  • الاشتراك: deep_equals, deep_not_equals (انظر القسم 8)

• array with complex items

  • مسموح: exists, not_exists
  • الاشتراك: deep_equals, deep_not_equals

• object

  • مسموح: exists, not_exists
  • الاشتراك: deep_equals, deep_not_equals

• null

  • مسموح: equals, not_equals, exists, not_exists

• dynamic (x-decision-gate.dynamic_type: true)

  • مسموح: جميع المقارنات (وفقًا لعلامات التكوين)

إذا تم تعطيل التحقق الصارم (validation.strict = false مع validation.allow_permissive = true)، يتم تخطي فحوصات توافق المخطط، ولكن لا تزال دلالات المقارنات في وقت التشغيل سارية.

---

8) مقارنات الاشتراك (ليكس وديب)

مقارنات المساواة المعجمية والعميقة هي اختيارية في التحقق الصارم للأنماط غير الديناميكية وتتطلب خطوتين:

1. Enable in decision-gate.toml:

   • validation.enable_lexicographic = true
   • validation.enable_deep_equals = true

2. إعلان خيارات الاشتراك في مخطط النتائج (للمخططات غير الديناميكية):

"result_schema": {
  "type": "string",
  "x-decision-gate": {
    "allowed_comparators": ["lex_greater_than", "lex_less_than"]
  }
}

قواعد إضافية:

• The comparator must also appear in the provider contract’s يجب أن يظهر المقارن أيضًا في قائمة allowed_comparators في عقد المزود.
• If x-decision-gate.allowed_comparators is present, every comparator إذا كانت x-decision-gate.allowed_comparators موجودة، يجب أن يتم إدراج كل المقارنات المستخدمة في السيناريوهات هناك.
• For dynamic schemas (dynamic_type: true), schema opt-in is not required, بالنسبة للمخططات الديناميكية (dynamic_type: true)، لا يتطلب الاشتراك في المخطط، ولكن لا تزال علامات التكوين سارية.

---

9) بيانات التعريف للأدلة: المراسي وأنواع المحتوى

تعلن العقود عن بيانات الأدلة التي يمكن لمزود الخدمة إصدارها.

• anchor_types: Strings describing anchor kinds (for audit or external references). Examples: file_path_rooted, url, receipt_id, log_offset. anchor_types: سلاسل تصف أنواع المراسي (لأغراض التدقيق أو المراجع الخارجية). أمثلة: file_path_rooted, url, receipt_id, log_offset. استخدم [] إذا لم يتم إصدار أي مراسي.

• content_types: MIME types of the evidence value. Examples:

  • application/json
  • text/plain
  • تطبيق/بايت-تدفق

يجب أن تتطابق قيم EvidenceResult.content_type مع هذه القائمة عند وجودها. قائمة فارغة تعني “غير محدد” (تعامل السياسات معها كحرف بدل).

ملاحظة قيمة الربط: EvidenceResult.evidence_anchor.anchor_value هو سلسلة نصية. إذا قمت بتكوين سياسة ربط تتطلب حقولًا، يجب أن تكون هذه السلسلة نص JSON قياسي لكائن واحد يحتوي على حقول قياسية. بالنسبة للربط القائم على الملفات، يستخدم file_path_rooted حقول root_id و path القياسية (مسارات نسبية فقط).

---

10) تصنيف الحتمية (كن صادقًا)

• حتمي: الناتج يعتمد فقط على المدخلات والحالة الداخلية.
• time_dependent: الناتج يعتمد على الوقت، ولكنه حتمي بالنظر إلى الوقت.
• خارجي: الناتج يعتمد على الحالة الخارجية (الشبكة، قاعدة البيانات، واجهات برمجة التطبيقات).

يتم استخدام هذا التصنيف لأغراض التدقيق والتفكير الثقة. لا تقم بتسمية خاطئة.

---

11) سير العمل الشامل للتأليف (البشر أو نماذج اللغة الكبيرة)

الخطوة 1: جمع المدخلات المطلوبة

يجب أن يكون لديك كل ما يلي لكل فحص مزود:

• تحقق من الاسم والوصف (ماذا تعني النتيجة).
• تصنيف الحتمية.
• مخطط المعلمات (مخطط JSON أو قائمة كاملة بالمعلمات مع الأنواع/المطلوبة).
• مخطط النتيجة (مخطط JSON لقيمة الدليل).
• المقارنات المسموح بها (أو السماح للمؤلف باشتقاقها بدقة).
• على الأقل مثال واحد من مجموعة معلمات + نتيجة (موصى به).
• أنواع المراسي وأنواع المحتوى (أو “لا شيء” صريح).

الخطوة 2: ربط المدخلات بحقول العقد

• تحويل الأسماء إلى معرفات ثابتة بتنسيق snake_case.
• ترجمة أنواع الطلبات إلى params_schema.
• ترجمة قيم الاستجابة إلى result_schema.
• اختر قوائم السماح للمقارنات من القسم 7 وقواعد التحقق الصارمة.

الخطوة 3: التحقق داخليًا

• تأكد من أن params_schema و result_schema هما مخططات JSON صالحة.
• تأكد من أن allowed_comparators غير فارغ وفي ترتيب قياسي.
• تأكد من أن قوائم المقارنات متوافقة مع قواعد التحقق الصارمة.
• تأكد من أن الأمثلة (إذا تم تقديمها) تتطابق مع المخططات.
• تأكد من أن content_types و anchor_types دقيقة.

الخطوة 4: إنتاج JSON النهائي

• إخراج JSON فقط.
• تجنب استخدام Markdown في الناتج النهائي.

---

12) ورقة عمل استيعاب المزود (نموذج)

انسخ/الصق واملأ هذا قبل تأليف العقد:

Provider
- provider_id:
- name:
- description:
- transport: mcp | builtin
- config_schema (JSON Schema):
- notes (required; use [] if none):

Checks (repeat per check)
- name:
- description (what the value means):
- determinism: deterministic | time_dependent | external
- params_required: true | false
- params_schema (JSON Schema):
- result_schema (JSON Schema):
- allowed_comparators (if known):
- anchor_types (array or empty):
- content_types (array; can be empty):
- examples (recommended):
  - description:
  - params:
  - result:

إذا كان أي حقل مفقودًا، فلا تخمن. اطلبه بشكل صريح.

---

13) موجه تأليف LLM (صارم، مستقل)

استخدم هذا الطلب كما هو مع LLM، جنبًا إلى جنب مع ورقة العمل المكتملة وأي تعريفات OpenAPI أو نوع. تم تصميم هذا الطلب لمنع الهلوسة وإجبار الأسئلة الصريحة عندما تكون المعلومات مفقودة.

You are generating a Decision Gate provider contract JSON.

Rules:
- Output JSON only (no markdown).
- Do not assume missing information. If any required field is missing or
  ambiguous, output a JSON object with a single key "questions" containing an
  array of clarifying questions, then stop.
- Use this exact contract shape:
  provider_id, name, description, transport, config_schema, notes, checks.
- Each check must include:
  check_id, description, determinism, params_required, params_schema, result_schema,
  allowed_comparators, anchor_types, content_types, examples.
- allowed_comparators must be non-empty and in canonical order.
- Comparators must be compatible with strict validation rules for the result_schema.
- If you include lex_* or deep_* comparators and the result_schema is not dynamic,
  also add result_schema.x-decision-gate.allowed_comparators.
- Note that server config must enable lex/deep comparator families for them to be used.
- Provide at least one example per check unless explicitly told to omit.

Inputs:
- Provider worksheet:
- OpenAPI/DTO schemas (if any):
- Example requests/responses (if any):

Return the final contract JSON.

---