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

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

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

بنية نظام التسجيل

Audience: Engineers working across Recorder crates or integrating Recorder with أنظمة التحكم مثل Decision Gate.

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

  1. نظرة عامة تنفيذية
  2. العمارة الطبقية
  3. تدفق البيانات من البداية إلى النهاية
  4. حدود الثقة ووضع الأمان
  5. نموذج الحتمية
  6. نطاق التنفيذ الحالي
  7. مرجع متقاطع ملف بملف

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

المسجل هو طبقة بيانات لتسجيل الأدلة الحتمية. يقوم بالتقاط الأحداث غير المغلقة عند حدود المحولات، ويقوم بإغلاقها في مظروفات متسلسلة بالهاش، ويحتفظ بها في سجلات مقاطع قابلة للإضافة فقط، ويصدر حزم محمولة للتحقق غير المتصل.

النظام منظم كمساحة عمل Rust مع حدود صارمة للحزم: عقود أساسية، نموذج مظروف، تنسيق المسجل، خلفيات التخزين، واجهة SDK Rust مريحة، SDK جانبي تم إنشاؤه من قبل الطرف الأول بلغة Python، دلالات تكوين جانبي معيارية، عمليات CLI، وخدمة HTTP جانبية وقت التشغيل. F:Cargo.toml L9-L26

العمارة الطبقية

  1. Core contracts (recorder-core)
  2. Evidence model (recorder-envelope)
  3. Integration adapters (recorder-decision-gate-adapter, recorder-otel-adapter)
  4. Recording runtime (recorder)
  5. Persistence (recorder-store)
  6. Sidecar config authority (recorder-sidecar-config)
  7. Rust SDK facade (recorder-sdk)
  8. Generated sidecar SDK (recorder-client for Python)
  9. Operational surface (recorder-cli)
  10. سطح خدمة الشبكة (recorder-sidecar)
  1. توليد عقد الإسقاط (recorder-contract)

تدفق البيانات من البداية إلى النهاية

Adapter / CLI input
    -> Sidecar mutating route validation (tenant_id + recorder_id + idempotency key)
    -> IngestGateway bounded queue admission
    -> IngestWriterRuntime writer-native sealing + single-tx micro-batch commit
    -> Stream/global commit index assignment + idempotency + projection update
    -> BundleBuilder resolves selector + attachment closure + manifest
    -> Verifier runs 7 phases offline
    -> EvidenceProvider serves bundles/envelope queries to control-plane bridge

نقاط دخول التدفق الرئيسية:

حدود الثقة ووضع الأمان

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

يتم تحقيق الحتمية من خلال الجمع بين:

  • ترميز JCS القياسي للبيانات القابلة للتجزئة،
  • هياكل الترتيب الحتمية (BTreeMap، متجهات مرتبة)،
  • منطق التجزئة الثابتة والمحدد
  • التحقق القابل لإعادة التشغيل دون اتصال.

F:crates/recorder-envelope/src/encoding.rs L13-L31 F:crates/recorder/src/bundle_builder.rs L27-L30 F:crates/recorder/src/bundle_builder.rs L466-L477

نطاق التنفيذ الحالي

تم التنفيذ الآن:

  • دورة حياة التسجيل المحلي الكامل والتحقق من الحزمة.
  • SQLite/تخزين في الذاكرة الخلفية.
  • recorder-sdk single-crate facade for Rust consumers, including deterministic إعدادات البناء الافتراضية وموصل/مزود/وصول المتجر المباشر.
  • recorder-client Python SDK with generated contract constants, typed sync/async عملاء sidecar، واختبارات الوحدة/النظام.
  • العمليات المدفوعة بواسطة CLI والإخراج المحلي.
  • CLI attachment-aware recording (record-with-attachments) with bounded file تسجيل مدرك للمرفقات عبر واجهة سطر الأوامر (record-with-attachments) مع إدخالات ملفات محدودة ومرفقات مضمنة.
  • CLI Decision Gate fixture ingest command path wired to production adapter مسار أمر استيعاب جهاز قرار بوابة CLI متصل بتنفيذ محول الإنتاج.
  • CLI OTel fixture ingest command path wired to production adapter تنفيذ.
  • System-test harness with registry-driven coverage, including OpenClaw gateway/CLI mock-flow and Decision Gate runpack-flow adapter-ingest نظام اختبار الحزمة مع تغطية مدفوعة بالسجل، بما في ذلك OpenClaw بوابة/محاكاة CLI وتكامل اختبارات تدفق تشغيل Decision Gate.
  • CLI expansion system-tests for recorder-id shape validation parity, attachment-recording fail-closed boundaries, auto-seal duration/combined lifecycle behavior, query JSON pagination/limit guardrails, and Decision Gate نجاح/فشل صارم لمسارات ingest-fixture في CLI.
  • Production Decision Gate adapter crate (crates/recorder-decision-gate-adapter) with deterministic MCP/runpack mapping, runpack-integrity strict/anomaly policy handling, and transcript تحكمات الحذف/الحدود.
  • Production OTel adapter crate (crates/recorder-otel-adapter) with deterministic span/log mapping, strict identifier/time parsing, and bounded/redacted تحكم الحمولة.
  • OpenClaw integration harness mapping policy with deterministic sensitive-field سياسة رسم خرائط تكامل OpenClaw مع حذف الحقول الحساسة المحدد ومعالجة الحمولة المحدودة لاختبارات الاقتران المدفوعة بالمعدات.
  • Decision Gate integration system-tests wired to the production adapter crate, covering signed/unsigned lanes, root-hash and manifest-integrity mismatch نظام اختبارات تكامل Decision Gate متصل بصندوق محول الإنتاج، يغطي المسارات الموقعة وغير الموقعة، وسلوك الفشل المغلق في حالة عدم تطابق جذر الهاش وسلامة البيان، واستقرار إعادة التشغيل/الهاش الحتمي.
  • Sidecar Docker operator profile (docker/sidecar) and system-test coverage for Dockerfile/Compose hardening plus containerized probe/record/query تدفق.
  • Sidecar readiness semantics now support fail-closed dependency modes: تدعم دلالات جاهزية Sidecar الآن أوضاع الاعتماد المغلقة عند الفشل: جاهزية التخزين فقط وجاهزية التخزين + التحكم المؤسسي.

الوضع الحالي للأداء/الضغط:

  • P2 stress/performance system-test expansion is now implemented with deterministic artifact-first lanes: performance::stress_concurrent_append_query_sqlite, performance::performance_bundle_materialization_smoke, and sidecar_perf::sidecar_perf_smoke_generates_gate_report (regression lane), plus sidecar_capacity::sidecar_capacity_sweep_generates_report (مسار السعة).
  • CI now runs a profile matrix (test informational + release gated) on the pinned perf runner via scripts/ci/perf_matrix.py and enforces release thresholds/regression policy via scripts/ci/perf_gate.py and system-tests/perf_baselines/linux_x86_64_ci.json.
  • Sidecar ingest 10k target is defined only on the capacity lane metric max_sustainable_rps and is enforced only for pinned runner policy class (linux_x86_64_pinned); the regression lane remains a deterministic fixed إشارة مكافحة الانحدار للعبء العمل.
  • Sidecar perf throughput/latency lanes now run against persistent keep-alive HTTP client pools to avoid connection-churn distortion in write-path القياسات.
  • Bundle-path metric bundle_build_envelopes_per_sec remains a separate core مقياس تجسيد الحزمة وليس وكيل سعة الإدخال.

تم إغلاق العناصر المتعلقة بتقوية النظام على مستوى النظام مؤخرًا:

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

المنطقةالملفالملاحظات
حدود مساحة العملCargo.tomlعضوية الحزمة وموقف lint.
العقود الأساسيةcrates/recorder-core/src/lib.rsالبدائل والمميزات المشتركة.
نموذج الظرفcrates/recorder-envelope/src/lib.rsنموذج بيانات الأدلة والعقود.
وقت تشغيل المسجلcrates/recorder/src/engine.rsاستيعاب، تقدم السلسلة، دورة حياة المقطع.
واجهة SDK لـ Rustcrates/recorder-sdk/src/lib.rs, crates/recorder-sdk/src/builder.rsواجهة بناء مريحة وموحدة للمسجل/المزود لمستهلكي Rust.
واجهة SDK لـ Pythonsdk/python/src/recorder_client/client.py, sdk/python/src/recorder_client/client_common.py, sdk/python/src/recorder_client/sync_client.py, sdk/python/src/recorder_client/async_client.py, sdk/python/src/recorder_client/models.py, sdk/python/src/recorder_client/errors.pyواجهة عميل جانبي متزامن/غير متزامن مدفوعة بالعقود المولدة مع تحقق صارم من الفشل المغلق ورسم خرائط الأخطاء المخصصة.
الحزمة + المدققcrates/recorder/src/bundle_builder.rsحل المحدد وتجسيد الحزمة.
تحقق الحزمةcrates/recorder/src/verifier.rsتحقق غير متصل من 7 مراحل.
ميزات التخزينcrates/recorder-store/src/traits.rsثوابت عقد الاستمرارية.
حدود قائمة SQLitecrates/recorder-store/src/sqlite/connection.rsسلوك الفشل المغلق في التوزيع غير المتزامن إلى المتزامن والتشبع.
واجهة CLIcrates/recorder-cli/src/main.rs, crates/recorder-cli/src/commands.rs, crates/recorder-cli/src/support.rsهيكلية أوامر تشغيلية مقسمة عبر التوزيع، ومعالجات الأوامر، ومساعدي التشغيل/الأدوات.
خدمة الجانبيcrates/recorder-sidecar/src/lib.rs, crates/recorder-sidecar/src/server.rsوقت تشغيل HTTP، كومة الوسائط، ودورة حياة النقل.
تكوين/أمان الجانبيcrates/recorder-sidecar-config/src/config.rs, crates/recorder-sidecar-config/src/validation.rs, crates/recorder-sidecar/src/middleware/auth.rs, crates/recorder-sidecar/src/middleware/bounds.rs, crates/recorder-sidecar/src/ingest.rsتحقق من تكوين الفشل المغلق وسلطة الإسقاط بالإضافة إلى ضوابط المصادقة/الحدود للجانبي وسلوك عدم تكرار الاستيعاب للكاتب الواحد.
تعبئة حاوية الجانبيdocker/sidecar/Dockerfile, docker/sidecar/docker-compose.yml, docker/sidecar/config/sidecar.toml, crates/recorder-sidecar/src/bin/docker_bootstrap.rsملف تعريف بناء/تشغيل الحاوية من الطرف الأول متماشي مع ثوابت تحقق/أمان الجانبي، بما في ذلك تمهيد رمز المصدر السري في مسار وقت تشغيل tmpfs المقوى.
مولد العقودcrates/recorder-contract/src/lib.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سلطة الأثر المولد الحتمي + تحقق من الانجراف.
اختبارات النظامsystem-tests/README.mdعقد تحقق من النهاية إلى النهاية.
محول بوابة القرارcrates/recorder-decision-gate-adapter/src/adapter.rsتنفيذ سياسة التعيين/التحرير/السلامة لإدخال بوابة القرار.
محول OTelcrates/recorder-otel-adapter/src/adapter.rsتنفيذ سياسة التعيين/التحرير/الحدود لإدخال JSON لـ OTel.
اختبارات تكامل OpenClawsystem-tests/tests/suites/integration_openclaw.rsتحقق من إدخال المحول المدفوع بالترتيب لربط سير العمل الخارجي.
بنية تكامل OpenClawDocs/architecture/recorder_openclaw_integration_architecture.mdعقد سياسة التعيين والإلغاء/الحمولة المحدودة بالإصدار.
اختبارات تكامل بوابة القرارsystem-tests/tests/suites/integration_decision_gate.rsتحقق من تدفق تشغيل MCP المدفوع بالترتيب لإدخال ربط مستوى التحكم.
بنية تكامل بوابة القرارDocs/architecture/recorder_decision_gate_integration_architecture.mdعقد تعيين تدفق MCP بالإصدار، سياسة سلامة تشغيل، وإلغاء/حدود النص.
بنية تكامل OTelDocs/architecture/recorder_otel_integration_architecture.mdعقد تعيين JSON لـ OTel بالإصدار، معرفات/أنواع أحداث حتمية، وتوصيلات إدخال الجانبي/CLI.