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

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

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

توليد عقد المسجل وهندسة الإسقاط

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

recorder-contract هو المولد/المتحقق الحتمي القياسي لقطع أثر عرض المسجل. يقوم بإصدار مخرجات المخطط/العقد/المثال/المصطلحات/أداة التلميح تحت Docs/generated/recorder/، بما في ذلك الآن قطع أثر عرض SDK تحت Docs/generated/recorder/sdk/، ويطبق فحوصات انحراف مغلقة عند الفشل.

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

  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/recorder-contract/src/lib.rs
  • crates/recorder-contract/src/contract_generation.rs
  • crates/recorder-contract/src/contract_generation_artifacts.rs
  • crates/recorder-contract/src/contract_generation_schema.rs
  • crates/recorder-contract/src/contract_generation_samples.rs
  • crates/recorder-contract/src/contract_generation_sdk_types.rs
  • crates/recorder-contract/src/contract_generation_sdk_sidecar.rs
  • crates/recorder-contract/src/contract_generation_sdk_vectors.rs
  • crates/recorder-contract/src/sidecar_api.rs
  • crates/recorder-contract/src/sidecar_api/openapi.rs
  • crates/recorder-contract/src/sidecar_api/artifacts.rs
  • crates/recorder-contract/src/sidecar_api/specs/mod.rs
  • crates/recorder-contract/src/tooltips.rs
  • crates/recorder-contract/src/tooltips_base_terms.rs
  • crates/recorder-contract/src/tooltips_builders.rs

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

  • Docs/generated/recorder/

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

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

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

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

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

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

  • توليد عقد المسجل
  • فحص عقد المسجل

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

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

  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. contracts/integrations/decision_gate.mapping.json
  8. contracts/integrations/otel.mapping.json
  9. glossary.md
  10. tooltips.json
  11. tooltips.catalog.json
  12. tooltips.annotations.json
  13. examples/envelope.json
  14. examples/segment.json
  15. examples/bundle.json
  16. apis/sidecar.openapi.json
  17. apis/sidecar.errors.json
  18. apis/sidecar.enums.json
  19. apis/sidecar.examples.json
  20. apis/sidecar.compat.json
  21. config/sidecar.schema.json
  22. config/sidecar.compat.json
  23. config/sidecar.example.toml
  24. config/sidecar.md
  25. sdk/types.json
  26. sdk/methods.json
  27. sdk/test_vectors.json
  28. sdk/manifest.json

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

اختبارات وحدة recorder-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. اتساق تكوين الأداة الجانبية (رابط المخطط/التوافق/المثال/المستندات).
  13. sidecar OpenAPI component typing strength for Bundle and VerificationVerdict (عقود كائنات غير فضفاضة وصديقة للمولد).
  14. إصدار مكونات SDK وإدراج البيان (types/methods/test_vectors/manifest).
  15. يتطلب إعلان البرنامج النصي لبيان SDK وتناسق سجل اللغة المستهدفة.
  16. SDK type projection hardening (field-level constraints + OpenAPI component bindings) and SDK method projection hardening (request/response schema refs, error/enum contract linkage, auth/idempotency metadata) for موارد المحول/المزود/الجانب.
  17. تغطية طرق SDK / متجهات الاختبار لواجهات المستخدم الأساسية لمحول / مزود / جانب السيارة.
  18. Integration mapping contract drift checks for Decision Gate and OTel تم إنشاء العناصر الناتجة مقابل ثوابت وقت تشغيل المحول.
  19. Sidecar media-type contract drift checks ensuring runtime policy-derived request media allowlists are projected consistently in OpenAPI and قطع التوافق.

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

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

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

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

  • scripts/ci/generate_all.sh

السلوك:

  1. generate: regenerate contract artifacts + regenerate Python SDK contract constants (sdk/python/generate.sh) + run sidecar contract gates + تجديد وثائق تغطية الاختبار.
  2. check: run contract drift check + Python SDK drift/unit/system gates (sdk/python/check.sh, sdk/python/test.sh) + sidecar contract gates + docs drift check (fail closed).
  3. Optional perf matrix mode: if RECORDER_PERF_MATRIX=1 (or legacy RECORDER_SIDECAR_PERF_GATE=1), execute debug/test + release perf suites via scripts/ci/perf_matrix.py and enforce release gate policy via scripts/ci/perf_gate.py مقابل عقود الخط الأساسي الملتزم بها.

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

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

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

  • Docs/roadmap/recorder_generated_contract_sync_and_glossary_policy.md

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