تدفق الأدلة + نموذج التنفيذ

نظرة سريعة

ما: كيف يقوم Decision Gate بتقييم الأدلة وإصدار القرارات لماذا: لفهم بالضبط ما يتم جلبه والتحقق منه ومقارنته من: المطورون، فرق الأمان، والمعماريون الذين يدمجون Decision Gate المتطلبات المسبقة: getting_started.md

جملة واحدة يجب أن تتذكرها

بوابة القرار تقيم الأدلة؛ ولا تنفذ المهام.

---

تدفق البيانات الأساسي

Trigger (scenario_next / scenario_trigger / precheck)
  |
  +-> Collect or accept evidence
  |     - Live run: call providers
  |     - Precheck: accept asserted payload
  |
  +-> Trust enforcement
  |     - Trust lane minimum (min_lane)
  |     - Signature policy (if required)
  |     - Anchor validation (if configured)
  |
  +-> Comparator evaluation -> TriState
  +-> RET evaluation -> Gate outcomes
  |
  +-> Decision
        - Live run: state mutation + runpack storage
        - Precheck: no state mutation

---

مصادر الأدلة

1) مقدمو الخدمة (التشغيل المباشر)

يستخرج مقدمو الخدمة أو يحسبون الأدلة ويعيدون EvidenceResult.

موفرو الخدمة المدمجون: time, env, json, http

المزودون الخارجيون: خوادم MCP يتم استدعاؤها عبر tools/call مع evidence_query.

2) الأدلة المؤكدة (التحقق المسبق)

التحقق المسبق لا يتصل بمقدمي الخدمة. العميل يقدم حمولة تكون:

1. تم التحقق منه مقابل شكل البيانات المسجل (JSON Schema).
2. تم تحويلها إلى قيم EvidenceResult المؤكدة.

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

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

---

تنفيذ الثقة

مسارات الثقة

• تم التحقق: الأدلة التي تم إرجاعها من قبل المزودين.
• تم التأكيد: الأدلة المقدمة عبر حمولة الفحص المسبق.

الحد الأدنى للمسار (min_lane)

تم تكوينه في decision-gate.toml:

[trust]
min_lane = "verified"   # or "asserted"

عندما min_lane = "verified"، يتم رفض الأدلة المؤكدة (تتحول الحالة إلى unknown).

Dev-permissive: min_lane يصبح asserted تلقائيًا، باستثناء مقدمي الخدمات المدرجين في dev.permissive_exempt_providers (تظل تلك صارمة).

تجاوزات لكل شرط ولكل بوابة

يمكنك رفع الحد الأدنى للمسار في مواصفات السيناريو:

{
  "condition_id": "tests_ok",
  "trust": { "min_lane": "verified" }
}

يمكن أن يؤدي الثقة على مستوى البوابة أيضًا إلى رفع المتطلبات. المتطلب الفعال هو الأكثر صرامة بين الأساس والتجاوزات.

التحقق من التوقيع

تم تكوينه عبر trust.default_policy:

[trust]
# Audit mode accepts unsigned evidence.
default_policy = "audit"

# Require signatures from key files:
# default_policy = { require_signature = { keys = ["/etc/decision-gate/keys/provider.pub"] } }

عندما يكون require_signature مفعلًا:

• EvidenceResult.signature.scheme يجب أن تكون "ed25519".
• signature.key_id يجب أن يتطابق مع إدخال مفتاح مُكون.
• يتم التحقق من التوقيع على JSON القياسي لـ evidence_hash.

إذا كان evidence_hash مفقودًا، يقوم Decision Gate بحسابه من قيمة الدليل. إذا كان evidence_hash موجودًا، يجب أن يتطابق مع الهاش القياسي لقيمة الدليل أو سيتم رفض استجابة المزود.

تحقق من الرابط

يتم تطبيق المراسي من خلال التكوين (ليس مواصفة السيناريو):

[anchors]
[[anchors.providers]]
provider_id = "json"
anchor_type = "file_path_rooted"
required_fields = ["root_id", "path"]

EvidenceResult.evidence_anchor.anchor_value يجب أن يكون سلسلة تحتوي على JSON قياسي يتم تحليله إلى كائن. يجب أن توجد الحقول المطلوبة ويجب أن تكون قياسية (سلسلة/رقم). تؤدي الانتهاكات إلى error.code = "anchor_invalid" وتصبح الحالة unknown. بالنسبة لـ file_path_rooted، يكون path نسبيًا لجذر المزود المُكون.

---

تقييم المقارنات

تنتج المقارنات نتائج TriState:

• صحيح
• خاطئ
• غير معروف

سلوكيات دقيقة مهمة (انظر condition_authoring.md):

• equals/not_equals تعيد false/true عند عدم تطابق النوع (ليس unknown).
• تعيد المقارنات (greater_than، إلخ) القيمة unknown ما لم تكن كلا الجانبين أرقامًا أو سلاسل تاريخ/وقت RFC3339.
• exists/not_exists اختبار وجود EvidenceResult.value؛ JSON null لا يزال يُعتبر exists.

---

تدفق التشغيل المباشر (scenario_next)

1. يوجد تشغيل (scenario_start).
2. scenario_next يتم استدعاؤه مع run_id، tenant_id، namespace_id، trigger_id، agent_id، و time.
3. يستدعي Decision Gate مقدمي الخدمة لكل حالة.
4. يتم تطبيق متطلبات الثقة.
5. تنتج المقارنات و RET نتائج البوابة.
6. يتم إرجاع DecisionRecord ويتم تحديث حالة التشغيل.

Output: NextResult { decision, packets, status } (لا توجد قيم للأدلة).

للفحص الأدلة وتفاصيل البوابة، استخدم runpack_export.

---

تدفق التحقق المسبق (التحقق المسبق)

1. يقوم العميل باستدعاء schemas_register لتسجيل شكل البيانات.
2. Client calls precheck with:
   • معرف_المستأجر، معرف_الفضاء
   • scenario_id أو inline spec
   • data_shape (معرف المخطط + الإصدار)
   • حمولة
3. يتم التحقق من صحة الحمولة مقابل المخطط.
4. يتم تحويل الحمولة إلى دليل مؤكد.
5. يتم تقييم البوابات دون تغيير حالة التشغيل.

Output: PrecheckToolResponse { decision, gate_evaluations }.

gate_evaluations يتضمن فقط حالة البوابة وأثر الحالة (بدون قيم الأدلة).

---

تقديمات التدقيق (scenario_submit)

scenario_submit يضيف سجل تقديم إلى حالة التشغيل دون التأثير على تقييم البوابة. كل تقديم يخزن تجزئة المحتوى وبيانات التعريف للتدقيق.

---

تفاعل المزود (MCP الخارجي)

تقوم بوابة القرار باستدعاء مزودي MCP الخارجيين باستخدام tools/call وأداة واحدة: evidence_query. إنها لا تعتمد على tools/list في وقت التشغيل؛ يتم تحميل قدرات المزود من capabilities_path في التكوين.

---

المفاهيم الخاطئة الشائعة (مصححة)

• “DG يدير الأدوات.” -> خطأ. DG يقيم الأدلة؛ الأدوات تعمل في مكان آخر.
• “Precheck returns evidence errors.” -> خطأ. إنه يعيد decision + gate_evaluations فقط.
• “استجابة scenario_next تتضمن الأدلة.” -> افتراضيًا خطأ. الطلبات المحلية فقط افتراضيًا تعود بتغذية trace، ولكن قيم الأدلة لا تزال تتطلب feedback: "evidence" (إذا كان مسموحًا) أو runpack_export/evidence_query.
• “سياسة الربط موجودة في السيناريو.” -> غير صحيح. تم تكوينها تحت [anchors].

---

معجم

EvidenceQuery: { provider_id, check_id, params }. EvidenceResult: { value, lane, error, evidence_hash, evidence_ref, evidence_anchor, signature, content_type }. Trust Lane: verified or asserted. Runpack: حزمة آثار التدقيق المكتوبة للتشغيل المباشر.