مسجل أصل أساسي بوابة القرار
Docs
وثائق بوابة القرار

تقييم بوابة حتمي وقابل لإعادة التشغيل مع قرارات قابلة للتدقيق.

وثائق Asset Core

تكامل مزود بوابة القرار + بنية سجل القدرات

Audience: Engineers implementing provider integration or capability الجمهور: المهندسون الذين يقومون بتنفيذ تكامل المزود أو التحقق من القدرات للتحقق من الشروط واستعلامات الأدلة.

جدول المحتويات

  1. نظرة عامة تنفيذية
  2. تكوين المزود
  3. سجل القدرات
  4. عقود مقدمي الخدمات الخارجيين
  5. اتحاد مزودي الأدلة
  6. تنفيذ على مستوى الأداة
  7. قفل عقد REST/OpenAPI V3 المطبوع
  8. مرجع متقاطع ملف بملف

نظرة عامة تنفيذية

يدعم Decision Gate ثلاثة أنواع من المزودين:

  • المزودون المدمجون (مترجمون إلى الثنائي)
  • مزودو MCP الخارجيون (نقل stdio أو HTTP)
  • مقدمو الأنواع (قدرة مسبقة التجميع + قطع أثرية لملف وقت التشغيل)

عقود قدرات المزود هي المخطط المعتمد لمعلمات التحقق، والنتائج، والمقارنات المسموح بها. يقوم سجل القدرات بالتحقق من مواصفات السيناريو واستعلامات الأدلة قبل التقييم. تقوم فيدرالية الأدلة بتوجيه الاستعلامات إلى المزودين وتطبيق سياسات الثقة. F:crates/decision-gate-config/src/config.rs L1883-L1990 F:crates/decision-gate-mcp/src/capabilities.rs L229-L379 F:crates/decision-gate-mcp/src/evidence.rs L138-L210

تكوين المزود

تم تعريف تكوين المزود في ProviderConfig:

  • type: مضمن, mcp, أو محدد النوع
  • command / url: اختيار النقل لمزودي MCP
  • capabilities_path: مسار JSON للعقد (مطلوب لمزودي MCP/المحددين)
  • runtime_profile_path: مسار ملف تعريف وقت التشغيل بصيغة JSON (مطلوب لمزودي الخدمة من النوع المحدد)
  • typed_protocol: محدد بروتوكول وقت التشغيل المطبوع (openapi_http أو grpc)
  • auth.bearer_token: مصادقة موفر اختيارية
  • trust: تجاوز الثقة حسب المزود
  • allow_raw: خيار الكشف عن الأدلة الخام
  • timeouts: مهلات الاتصال وطلبات HTTP

تُعرّف عناصر التحكم في الاكتشاف في provider_discovery:

  • allowlist / denylist: تقييد العقود المقدمة التي يتم الكشف عنها
  • max_response_bytes: تحديد حجم استجابة الاكتشاف

تفرض التحقق:

  • يجب على مزودي MCP تحديد command أو url و capabilities_path.
  • Typed providers must specify capabilities_path, runtime_profile_path, و typed_protocol.
  • allow_insecure_http مطلوب لروابط http://.
  • أسماء المزودين فريدة ومختصرة.
  • المعرفات المدمجة (time, env, json, http, rest) محجوزة؛ لا يمكن لمزودي MCP استخدامها.
  • Built-ins must use a reserved identifier and reject MCP-only fields (command, url, يجب أن تستخدم العناصر المدمجة معرفًا محجوزًا وترفض الحقول الخاصة بـ MCP فقط (command, url, allow_insecure_http, auth, capabilities_path).
  • يرفض مزودو MCP الحقول التي تحتوي على نصوص فقط (runtime_profile_path, typed_protocol).
  • Typed providers reject MCP-only fields (command, url, allow_insecure_http, auth) و config المدمجة.

F:crates/decision-gate-config/src/config.rs L1883-L1990

سجل القدرات

سجل القدرات يقوم بتحميل عقود المزودين وتجميع مخططات JSON لبيانات التحقق من المعلمات والنتائج. يقوم بالتحقق من:

  • مزود والتحقق من الوجود
  • وجود المعلمات المطلوبة
  • توافق مخطط المعلمات
  • التوافق مع مخطط القيمة المتوقعة
  • قوائم السماح للمقارنات
  • Anchor types declared by provider contracts (e.g., file_path_rooted for the أنواع المراسي المعلنة من قبل عقود المزودين (على سبيل المثال، file_path_rooted لمزود json المدمج)
  • رفض تكرار check_id (فشل مغلق؛ لا توجد دلالات الكتابة الصامتة)

F:crates/decision-gate-mcp/src/capabilities.rs L313-L379 F:crates/decision-gate-mcp/src/capabilities.rs L598-L636

تُستخدم استعلامات سجل القدرات من قِبَل أدوات تعريف السيناريو وأدوات استعلام الأدلة. F:crates/decision-gate-mcp/src/tools/router.rs L2029-L2050 F:crates/decision-gate-mcp/src/tools/router.rs L979-L1017

عقود مقدمي الخدمات الخارجيين

يجب على مقدمي الخدمات الخارجيين تقديم ملف JSON للعقد يتضمن ما يلي:

  • يتطابق مع معرف المزود المكون
  • Declares transport matching provider type:
    • مقدمو MCP: transport = "mcp"
    • مقدمو الخدمات المعتمدون: transport = "typed"
  • يحدد الفحوصات مع قوائم المقارنات المسموح بها

العقود محدودة الحجم ومتحققة من المسار؛ العقود غير الصالحة تفشل بشكل مغلق. بالنسبة لاستيرادات OpenAPI المخصصة، تحقق من أن allowed_comparators تم توليدها من مخطط نتيجة موحد باستخدام مصفوفة نوع المقارن الصارمة وترتيب المقارن القياسي. F:crates/decision-gate-mcp/src/capabilities.rs L533-L591 F:crates/decision-gate-typed/src/openapi/check_synthesis.rs L34-L109 F:crates/decision-gate-typed/src/openapi/comparator_derivation.rs L52-L114

اتحاد مزودي الأدلة

تجمع اتحاد الأدلة بين مقدمي الخدمات المدمجين ومقدمي خدمات MCP:

  • يتم تسجيل المكونات المدمجة عبر سجل المزود.
  • يتم إنشاء مزودي MCP باستخدام النقل عبر stdio أو HTTP.
  • Typed providers are instantiated from runtime profile artifacts and execute التحقق من التعريفات عبر مزود وقت التشغيل المحدد.
  • يرفض سجل المزودين التسجيلات المكررة لمنع التداخل الصامت.
  • Stdio provider processes are terminated on drop to avoid orphaned provider يتم إنهاء عمليات مزود Stdio عند الانسحاب لتجنب أوقات تشغيل المزود اليتيمة أثناء الإغلاق أو تفكيك الاختبار.
  • يتم تطبيق سياسات المزود (trust + allow_raw) لكل مزود.
  • Evidence results may include structured error metadata (code, message, قد تتضمن نتائج الأدلة بيانات وصفية للخطأ منظمة (code, message, details) لدعم حلقات الاسترداد الحتمية.
  • HTTP evidence providers enforce timeouts, disallow redirects, apply response size limits, fail closed on truncated bodies (Content-Length mismatch), pin DNS resolution per request, and deny private/link-local peers by default ما لم يتم الاشتراك صراحة.
  • The built-in REST provider reuses the same HTTP security controls and adds GET-only extraction checks (json_path, header) plus header/auth hygiene تنفيذ لأسماء الرؤوس المدارة من قبل المصادقة والمحجوزة.
  • The typed runtime provider applies the same hardened HTTP controls for openapi_http execution, enforces profile digest integrity, validates response status/content-type against profile policy, and emits deterministic تثبيتات باستخدام بيانات التعريف.
  • Typed lifecycle catalog semantics now exist in OSS compile tooling to support profile version registration, activation, rollback, and digest drift detection (decision-gate-typed), and OSS lifecycle tool plumbing is active via typed_providers_import, typed_providers_register, typed_providers_list, typed_providers_get, typed_providers_activate, و typed_providers_deprecate.
  • Typed runtime resolution now includes a resolver seam (TypedProfileResolver) keyed by (tenant_id, namespace_id, provider_id). Default OSS behavior resolves from scoped in-memory lifecycle state and falls back to static typed profile config entries. Resolver calls now snapshot the resolver handle before invocation so runtime لا يتم تنفيذ الحل أثناء الاحتفاظ بقفل المحلّل الداخلي.
  • Built-in REST runtime now includes policy evaluator seams (RestPolicyEvaluator) for egress host/scheme decisions and auth-scheme القرارات. تنكر مسارات العودة رموز الأسباب الحتمية.

F:crates/decision-gate-mcp/src/evidence.rs L138-L210 F:crates/decision-gate-mcp/src/evidence.rs L248-L266 F:crates/decision-gate-providers/src/http.rs L82-L239 F:crates/decision-gate-providers/src/rest.rs L124-L570 F:crates/decision-gate-typed/src/lifecycle.rs L1-L286

تطبيق سياسة الثقة (التحقق من التوقيع) يتم وفقًا لاستجابة المزود. F:crates/decision-gate-mcp/src/evidence.rs L636-L677

فرض مستوى الأداة

سلوك الأداة يفرض سياسة القدرة والإفصاح:

  • scenario_define يتحقق من المواصفات مقابل القدرات قبل التسجيل.
  • evidence_query يتحقق من صحة الاستعلامات ويطبق سياسة حذف الأدلة الخام.
  • evidence_query execution is offloaded to a blocking task to isolate evidence_query يتم تنفيذها في مهمة محجوزة لعزل مقدمي الخدمات المحجوزين (HTTP) عن وقت تشغيل MCP غير المتزامن.
  • provider_contract_get / provider_check_schema_get apply disclosure policy and provider_contract_get / provider_check_schema_get تطبق سياسة الإفصاح وتعيد عقود المزودين القياسية أو مخططات التحقق.
  • Typed lifecycle tools (typed_providers_import/register/list/get/activate/deprecate) require explicit tenant_id + namespace_id scope fields and provide deterministic scoped artifact registration, active-version selection, rollback-aware deprecation, digest drift status inspection, and bounded typed import/runtime security limits (timeout_ms, max_response_bytes, outbound_max_inflight, retry bounds, and allowlist cardinality). typed_providers_import requires an explicit credential_bindings field on every request ({} for unauthenticated imports) and explicit secured-scheme-to-credential_binding mappings for secured OpenAPI imports. يتطلب كل تخطيط مؤمن كل من بيانات تحديد الموقع وبيانات قيمة السلك.
  • Provider-scoped authz context now includes provider_id for typed lifecycle tools and evidence_query, enabling provider-level enterprise authorization سياسة في واجهة تفويض المستأجر.
  • Comparator allow-lists are enforced from provider contracts; json.path يتم تطبيق قوائم السماح للمقارنات من عقود المزود؛ json.path يكشف عن كامل مساحة سطح المقارنة لأدلة JSON الحتمية.

F:crates/decision-gate-mcp/src/tools/router.rs L1106-L1236 F:crates/decision-gate-mcp/src/tools/router.rs L1238-L1298 F:crates/decision-gate-mcp/src/tools/router.rs L3173-L3940 F:crates/decision-gate-mcp/src/tools/typed/lifecycle.rs L127-L210 F:crates/decision-gate-mcp/src/tools/typed/lifecycle.rs L213-L452 F:crates/decision-gate-mcp/src/tools/typed/lifecycle.rs L455-L544

قفل عقد Typed REST/OpenAPI V4

هذا القسم هو قفل قرار مستوى الهندسة لسلوك مزود REST/OpenAPI من نوع OSS. إنه مستقر عمدًا حتى لا تؤثر حركة خارطة الطريق/الأرشيف على العقدة النشطة.

استيراد قفل الحدود (OSS V4):

  • OpenAPI version policy accepts 3.0.x and 3.1.x; other versions fail مغلق.
  • External ref mode is local_file_only in OSS runtime behavior. Network ref تم تحليل مسارات التنفيذ لتصنيف السياسة ولكن تم رفضها.
  • Unsupported or ambiguous constructs must fail closed with deterministic بيانات التعريف الخاصة بتصنيف الخرائط/الإصلاح.
  • Unsupported taxonomy and remediation metadata are single-source and enum-backed (OpenapiUnsupportedCode + OpenapiImportErrorKind), not message-substring مقترن.
  • Unsupported taxonomy fixture parity is enforced by typed importer unit اختبارات العقد، حظر انحراف التركيب/التنفيذ في CI.

F:crates/decision-gate-typed/src/openapi/mod.rs L144-L301 F:crates/decision-gate-typed/src/openapi/refs.rs L22-L394 F:crates/decision-gate-typed/src/openapi/errors.rs L12-L212 F:crates/decision-gate-typed/src/openapi/errors.rs L447-L558 F:crates/decision-gate-typed/tests/openapi_unsupported_taxonomy_contract.rs L1-L105

توليف/قفل وقت التشغيل (OSS V4):

  • Projection-first synthesis is mandatory for JSON object/array-complex يجب أن تعلن المخططات عن x-decision-gate.projections.
  • OpenAPI import emits one check per declared projection entry per حالة/وسائط tuple؛ تم إزالة إدخال response_projection_mode القديم.
  • json_only media support remains default unless explicit overrides مقدمة.
  • Runtime request binding supports path, query, header, cookie, and أهداف body الاختيارية مع تعارض مغلق عند الفشل وفحوصات النظافة.
  • تظل عملية الاستخراج في وقت التشغيل مقيدة بحالة/نوع المحتوى وتفشل بشكل مغلق.
  • Runtime profile profile_version is hard-locked to typed-runtime-v4; older تم رفض إصدارات الملف الشخصي.
  • TypedOperationProfile always carries required operation-effective auth بدائل؛ التراجع عن مصادقة مستوى المزود ليس جزءًا من نموذج وقت التشغيل.

F:crates/decision-gate-typed/src/openapi/mod.rs L144-L248 F:crates/decision-gate-typed/src/openapi/check_synthesis.rs L34-L242 F:crates/decision-gate-typed/src/runtime_codegen.rs L42-L93 F:crates/decision-gate-providers/src/typed.rs L687-L799

قفل المصادقة + بيانات الاعتماد (OSS V4):

  • Effective security is resolved per operation:
    • operation.security تتجاوز security على المستوى الأعلى.
    • security: [] تعني عملية غير مصادق عليها.
    • كائن المتطلبات الفارغ ({}) يساهم في بديل غير مصادق عليه.
  • Supported requirement shapes:
    • متطلب واحد يحتوي على مخطط واحد مدعوم.
    • Multiple alternatives where each alternative contains exactly one supported مخطط.
  • Supported schemes remain http bearer/basic and apiKey in header|query|cookie.
  • Credential locators are explicit and scheme-locked:
    • secret://... يتم حله من خلال واجهة OSS السرية المشفرة المحلية.
    • env://... is development-only and disabled unless dev.allow_dev_env_credentials=true.
    • يتم رفض أسماء متغيرات البيئة العارية ومخططات الموقع غير المعروفة.
  • Credential values are canonical raw secrets; runtime applies explicit value_render metadata (identity or deterministic prefix) before header/query/cookie injection.
  • apiKey alternatives retain exact OpenAPI-derived name and location; no تُستخدم أسماء مفاتيح API الثابتة الاصطناعية أثناء وقت التشغيل.
  • Import requires an explicit credential_bindings field and explicit credential_binding mapping input for every referenced secured scheme; تخفق الحقول/الخرائط المفقودة في الإغلاق.
  • Unsupported security types/schemes and unsupported requirement shapes (oauth2, openIdConnect, unsupported http schemes, unsupported apiKey locations, multi-scheme AND, missing scheme refs, malformed security تفشل الكائنات) في الإغلاق المغلق مع تصنيف حتمي.

F:crates/decision-gate-typed/src/openapi/security_mapping.rs L11-L216 F:crates/decision-gate-typed/src/openapi/errors.rs L125-L155 F:crates/decision-gate-providers/src/typed.rs L789-L904 F:crates/decision-gate-mcp/src/tools/typed/lifecycle.rs L55-L163

مرونة الخروج + قفل الحدود (OSS V3):

  • Runtime security policy includes per-provider outbound inflight caps and bounded retry policy (max_attempts, initial_backoff_ms, max_backoff_ms).
  • Runtime retries are deterministic and limited to timeout/429/503, with دعم Retry-After المحدود عند ترميزه بالثواني.
  • استيراد/تسجيل يرفض حدود إعادة المحاولة/الحدود الخارجية غير الصحيحة.

F:crates/decision-gate-contract/src/types.rs L403-L439 F:crates/decision-gate-providers/src/typed.rs L448-L463 F:crates/decision-gate-providers/src/typed.rs L958-L980 F:crates/decision-gate-mcp/src/tools/typed/lifecycle.rs L586-L663

متطلبات التحكم في التغيير:

  • Any change to the above lock values requires same-change updates to:
    • هذا القسم،
    • أدوات التوافق مع OpenAPI (system-tests/tests/fixtures/openapi_compat/),
    • عقود سياسة/تقرير تغطية REST (system-tests/tests/fixtures/coverage/),
    • وتغيرات نموذج التهديد عندما تتوسع حدود الثقة.

مرجع متقاطع لكل ملف

المنطقةالملفالملاحظات
تكوين المزود + التحققcrates/decision-gate-config/src/config.rsنوع المزود، النقل، مسار العقد، أوقات الانتظار، السماح/الرفض للاكتشاف.
سجل القدراتcrates/decision-gate-mcp/src/capabilities.rsتحميل العقد، تجميع المخطط، التحقق.
اتحاد الأدلةcrates/decision-gate-mcp/src/evidence.rsسجل المزود + تنفيذ الثقة.
مزود وقت التشغيل المخصصcrates/decision-gate-providers/src/typed.rsتحميل ملف تعريف وقت التشغيل وتنفيذ التحقق المخصص.
IR المخصص + المحولاتcrates/decision-gate-typed/src/lib.rsأساس استيراد/توليد الكود المخصص غير المعتمد على البروتوكول.
كتالوج دورة الحياة المخصصةcrates/decision-gate-typed/src/lifecycle.rsإصدار ملف تعريف OSS، التفعيل/التراجع، وحالة انحراف التجزئة.
واجهة محول OpenAPIcrates/decision-gate-typed/src/adapter_openapi.rsإعادة تصدير التوافق لواجهة API لوحدة openapi.
تفاصيل محول OpenAPIcrates/decision-gate-typed/src/openapi/تقسيم الوحدة للخيارات/الأخطاء/التوافق/المراجع/المخطط/الأمان/التحقق/منطق المقارنات.
تنسيق أدوات دورة الحياة المخصصةcrates/decision-gate-mcp/src/tools/typed/lifecycle.rsتحليل استيراد/تسجيل/قائمة/الحصول/تفعيل/إهمال المخصص وتوصيل حالة دورة الحياة.
تكامل الأدواتcrates/decision-gate-mcp/src/tools/router.rsإرسال الأدوات، بوابات المصادقة/الإفصاح، وظرف المعالج غير المتزامن.