Arxi بوابة القرار أصل أساسي
Docs
أركسي دوكس

توثيق تسجيل الإثبات والأدلة المقاومة للتلاعب.

وثائق المنتجات الأخرى

عمارة توليد العقود والتوقعات Arxi

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

arxi-contract هو المولد/المدقق الحتمي القياسي لقطع أثر إسقاط Arxi. يقوم بإصدار مخرجات المخطط/العقد/المثال/المصطلحات/نصوص التلميحات تحت Docs/generated/arxi/ ويفرض فحوصات انحراف مغلقة عند الفشل.

توليد التلميحات أصبح الآن بيانات وصفية عالمية المستوى مع:

  1. بيان أدوات التلميحات المتوافقة مع الإصدارات السابقة (tooltips.json),
  2. كتالوج المصطلحات الغني (tooltips.catalog.json),
  3. pointer/token bindings for code blocks and JSON examples روابط المؤشر/التوكن لكتل الشيفرة وأمثلة JSON (tooltips.annotations.json),
  4. مصطلحات القاموس (glossary.md) التي تم إنشاؤها من نفس مصدر المصطلح.

سلطة الأثر

كود مولد موثوق:

  • crates/arxi-contract/src/lib.rs
  • crates/arxi-contract/src/sidecar_api.rs
  • crates/arxi-contract/src/sidecar_api/openapi.rs
  • crates/arxi-contract/src/sidecar_api/artifacts.rs
  • crates/arxi-contract/src/sidecar_api/specs/mod.rs

جذر مولد موثوق:

  • Docs/generated/arxi/

سلطة بيان الآلة:

index.json يتضمن إصدار العقد بالإضافة إلى بيانات التعريف الخاصة بـ SHA-256 لكل عنصر. عندما تكون عناصر واجهة برمجة التطبيقات الجانبية موجودة، يتم تطبيق بوابات التوافق من العناصر المولدة عبر scripts/ci/sidecar_contract_gates.py.

أوضاع المولدات

arxi-contract يدعم وضعين حتميين:

  1. GenerateMode::Generate
    • يعيد توليد العناصر ويعيد كتابة جذر الإخراج.
    • يزيل الملفات غير المتوقعة القديمة تحت جذر الإخراج.
    • Fails closed if output-root traversal encounters symlinks or unsupported يفشل الإغلاق إذا واجهت عملية التنقل عبر الجذر في المخرجات روابط رمزية أو أنواع إدخال نظام ملفات غير مدعومة.
  2. GenerateMode::Check
    • يفشل النظام عند فقدان الملفات، انحراف البايت، أو وجود ملفات غير متوقعة.
    • Fails closed if expected paths resolve through symlinked roots/components يفشل الإغلاق إذا كانت المسارات المتوقعة تحل من خلال الجذور/المكونات المرتبطة برموز أو ملفات غير عادية.

تكامل واجهة سطر الأوامر:

  • arxi contract generate
  • arxi contract check

نموذج الحتمية

تشمل عناصر التحكم في الحتمية:

  1. ترتيب مستقر للأصول عبر الخرائط/المجموعات المرتبة،
  2. ترميز JSON القياسي عبر JCS،
  3. تجزئة SHA-256 الصريحة لمدخلات البيان،
  4. مقارنة بايت وضع التحقق ضد الملفات الملتزمة.

إسقاط المخطط الواعي بالقيود

توليد المخطط هو على مرحلتين:

  1. استنتاج الشكل الهيكلي من عينات حتمية.
  2. تطبيق قيود المجال الموثوقة من خلال تراكب JSON-pointer.

تشمل تراكبات القيود:

  1. سياسات شكل نص UUID صارمة لجميع حقول الهوية،
  2. قيود السلسلة المعادية والطول الأقصى لحقول المعرف/النص،
  3. سياسة تعبير منتظم صارمة لنوع الحدث وحدود الطول،
  4. سياسة تعبير منتظم صارمة لـ key_id (^[0-9a-f]{64}$)،
  5. قيود مصفوفة بايت ذات طول ثابت لحقول التجزئة / التوقيع،
  6. تمثيلات صريحة قابلة للاحتواء للحقول الاختيارية،
  7. full BundleSelector algebra projection (BySegment, BySegments, ByTrace, ByTimeRange, ByEnvelopeIds, ByFilter, recursive إسقاط الجبر الكامل لـ BundleSelector (BySegment, BySegments, ByTrace, ByTimeRange, ByEnvelopeIds, ByFilter, Composite التكراري) عبر المخطط $defs.

تفشل الإسقاطات المغلقة إذا كانت مسارات المؤشر المتوقعة مفقودة أثناء تطبيق القيود.

مجموعة العناصر المنتجة

الملفات الصادرة الحالية v1:

  1. index.json
  2. schemas/envelope.schema.json
  3. schemas/segment.schema.json
  4. schemas/bundle.schema.json
  5. contracts/adapter.json
  6. contracts/provider.json
  7. glossary.md
  8. tooltips.json
  9. tooltips.catalog.json
  10. tooltips.annotations.json
  11. examples/envelope.json
  12. examples/segment.json
  13. examples/bundle.json
  14. apis/sidecar.openapi.json
  15. apis/sidecar.errors.json
  16. apis/sidecar.enums.json
  17. apis/sidecar.examples.json
  18. apis/sidecar.compat.json
  19. config/sidecar.schema.json
  20. config/sidecar.compat.json
  21. config/sidecar.example.toml
  22. config/sidecar.md

التوافق والتحقق

اختبارات وحدة arxi-contract تتحقق من:

  1. حتمية التوليد المتكرر،
  2. اتساق تجزئة البيان/بايت الملف،
  3. أمثلة مولدة تتحقق من صحة المخططات المولدة،
  4. يتضمن كتالوج التلميحات جميع أسماء طرق عقود الموصل/المزود،
  5. تغطية المصطلحات الأساسية المطلوبة على مستوى عالمي،
  6. مؤشرات كتالوج التلميحات تحل ضد العناصر الناتجة عن JSON،
  7. روابط توضيح التلميحات تشير فقط إلى مفاتيح المصطلحات المعرفة،
  8. schema/runtime invariance for key_id, hostile text fields, and identifier عدم تغير المخطط/وقت التشغيل لـ key_id، حقول النص العدائية، وقيود الطول الأقصى للمعرف.
  9. إصدار عنصر sidecar وإدراج البيان.
  10. تناسق سجل أخطاء sidecar وقاعدة التوافق.
  11. تناسق عقد عدم التكرار لواجهة OpenAPI/compat في sidecar.
  12. اتساق تكوين الأداة الجانبية (رابط المخطط/التوافق/المثال/المستندات).

arxi-contract اختبارات سلامة المسار المخصصة تتحقق من:

  1. وضع التوليد يرفض جذور المخرجات المرتبطة بالرموز.
  2. وضع التوليد يرفض المسارات الفرعية المرتبطة بالرموز تحت جذر الإخراج،
  3. تحقق من وضع التقارير عن انحراف البايت للقطع المعدلة،
  4. وضع التحقق يرفض ملفات الأرتيفكت المتوقعة المرتبطة بالرموز.

التنسيق والتكامل المستمر

نقطة دخول تنسيق الأوامر الواحدة:

  • scripts/ci/generate_all.sh

السلوك:

  1. generate: regenerate contract artifacts + run sidecar contract gates + generate: إعادة توليد مكونات العقد + تشغيل بوابات العقد الجانبية + إعادة توليد وثائق تغطية الاختبار.
  2. check: run contract drift check + sidecar contract gates + docs drift check: تشغيل فحص انحراف العقد + بوابات عقد الجانبي + فحص انحراف الوثائق (فشل مغلق).
  3. Optional release mode: if ARXI_SIDECAR_PERF_GATE=1, enforce sidecar SLO metrics via scripts/ci/sidecar_perf_gate.py against generated perf report وضع الإصدار الاختياري: إذا كان ARXI_SIDECAR_PERF_GATE=1، فرض مقاييس SLO الخاصة بالسايدكار عبر scripts/ci/sidecar_perf_gate.py ضد تقارير الأداء الناتجة.

تعمل سير العمل في CI على تنفيذ ذلك في بوابات الجودة المطلوبة.

حدود تسليم الإسقاط

سياسة نقل موقع الويب/i18n وملكية المصطلحات:

  • Docs/roadmap/arxi_generated_contract_sync_and_glossary_policy.md

هذا يحدد متطلبات وجود الملف، والتحقق من التجزئة، واستقرار المسار، وملكية المصطلحات/الأدلة من مصدر واحد.