معمارية نظام Arxi

Audience: Engineers working across Arxi crates or integrating Arxi with الجمهور: المهندسون الذين يعملون عبر صناديق Arxi أو يدمجون Arxi مع أنظمة التحكم مثل Decision Gate.

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

نظرة عامة تنفيذية
العمارة الطبقية
تدفق البيانات من البداية إلى النهاية
حدود الثقة ووضع الأمان
نموذج الحتمية
نطاق التنفيذ الحالي
مرجع متقاطع ملف بملف

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

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

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

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

Core contracts (arxi-core)
- Identity newtypes, hash/signature abstractions, filters, schema versioning, and boundary error algebras. أنواع الهوية الجديدة، تجريدات التجزئة/التوقيع، المرشحات، إصدار المخطط، وجبر أخطاء الحدود. F:crates/arxi-core/src/lib.rs L53-L109
Evidence model (arxi-envelope)
- Envelope/segment/bundle types, canonical encoding functions, adapter and provider contracts, and verification result algebra. أنواع المغلفات/الشرائح/الحزم، وظائف الترميز القياسية، عقود المحولات والمزودين، وجبر نتائج التحقق. F:crates/arxi-envelope/src/lib.rs L53-L111
Integration adapters (arxi-decision-gate-adapter)
- First-party deterministic adapter implementing Decision Gate MCP/runpack transcript mapping, redaction/bounds policy, and runpack-integrity checks. محول حتمي من الطرف الأول ينفذ خريطة نقل Decision Gate MCP/runpack، سياسة الحذف/الحدود، وفحوصات سلامة runpack. F:crates/arxi-decision-gate-adapter/src/lib.rs L1-L40
Recording runtime (arxi-recorder)
- RecorderEngine, BundleBuilder, Verifier, local adapter, and provider implementation. مسجل المحرك، باني الحزمة، المدقق، المحول المحلي، وتنفيذ المزود. F:crates/arxi-recorder/src/lib.rs L34-L56
Persistence (arxi-store)
- Store traits with SQLite and in-memory implementations. تخزين السمات باستخدام SQLite وتنفيذات الذاكرة. F:crates/arxi-store/src/lib.rs L49-L71
Sidecar config authority (arxi-sidecar-config)
- Canonical sidecar config model, fail-closed runtime validation, and deterministic config projection helpers consumed by arxi-contract. نموذج تكوين الجانب الكنسي، والتحقق من صحة وقت التشغيل المغلق، و مساعدي إسقاط التكوين الحتمي المستخدمين بواسطة arxi-contract. F:crates/arxi-sidecar-config/src/lib.rs
Operational surface (arxi-cli)
- CLI command groups for segment lifecycle, recording, query, bundle, config validation, diagnostics, attachment-aware ingest, and Decision Gate fixture ingest, with handlers split into command and support helper modules. F:crates/arxi-cli/src/main.rs L137-L272 F:crates/arxi-cli/src/commands.rs L19-L29 مجموعات أوامر CLI لدورة حياة الشريحة، التسجيل، الاستعلام، الحزمة، التحقق من التكوين، التشخيص، الإدخال الواعي بالمرفقات، وإدخال أدوات Decision Gate، مع تقسيم المعالجات إلى وحدات أوامر ووحدات دعم مساعدة. F:crates/arxi-cli/src/main.rs L137-L272 F:crates/arxi-cli/src/commands.rs L19-L29 F:crates/arxi-cli/src/support.rs L19-L23
Network service surface (arxi-sidecar)
- Sidecar HTTP/JSON runtime with auth/bounds/idempotency middleware and recorder/store integration over Unix/TCP listeners, including explicit liveness/startup/readiness probes and enterprise-aware readiness modes. F:crates/arxi-sidecar/src/lib.rs L1-L41 وقت تشغيل Sidecar HTTP/JSON مع مصادقة/حدود/العمومية ودمج المسجل/المخزن عبر مستمعي Unix/TCP، بما في ذلك اختبارات الحية/بدء التشغيل/الجاهزية الصريحة وأنماط الجاهزية المدركة للمؤسسات. F:crates/arxi-sidecar/src/lib.rs L1-L41 F:crates/arxi-sidecar/src/server.rs L42-L247
Projection contract generation (arxi-contract)
- Deterministic artifact generation/check (Docs/generated/arxi/**) and manifest hash authority (index.json). توليد/تحقق من الأثر الحتمي (Docs/generated/arxi/**) و سلطة تجزئة البيان (index.json). F:crates/arxi-contract/src/lib.rs

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

Adapter / CLI input
    -> UnsealedEnvelope
    -> RecorderEngine computes content_hash + chain_hash + sequence
    -> EnvelopeStore append (chain continuity enforced)
    -> Segment lifecycle (open/seal, predecessor linkage)
    -> BundleBuilder resolves selector + attachment closure + manifest
    -> Verifier runs 7 phases offline
    -> EvidenceProvider serves bundles/envelope queries to control-plane bridge

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

Ingest path: RecorderEngine::record_envelope مسار الإدخال: RecorderEngine::record_envelope F:crates/arxi-recorder/src/engine.rs L207-L214
Segment lifecycle: open_segment, seal_segment دورة حياة المقطع: open_segment, seal_segment F:crates/arxi-recorder/src/engine.rs L280-L343
Bundle export path: BundleBuilder::build مسار تصدير الحزمة: BundleBuilder::build F:crates/arxi-recorder/src/bundle_builder.rs L129-L172
Offline verification path: Verifier::verify مسار التحقق غير المتصل: Verifier::verify F:crates/arxi-recorder/src/verifier.rs L95-L136

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

Adapter inputs are treated as untrusted and validated fail-closed before recorder append. يتم التعامل مع مدخلات المحول على أنها غير موثوقة ويتم التحقق منها بشكل مغلق قبل إضافة المسجل. F:crates/arxi-recorder/src/validation.rs L46-L83
Core identity constructors fail closed on blank/control-character strings, and KeyId enforces canonical lowercase SHA-256 hex shape. String-backed identity types now also enforce explicit max-length policies and constructor-validated serde deserialization. F:crates/arxi-core/src/identity.rs L31-L55 F:crates/arxi-core/src/identity.rs L37-L47 F:crates/arxi-core/src/identity.rs L516-L647
Envelope-layer attachment and segment constructors reject empty/blank/control text inputs for content_type and recorder_id, enforce max-length bounds, and validate serde deserialize boundaries through constructors. F:crates/arxi-envelope/src/attachment.rs L35-L44 F:crates/arxi-envelope/src/attachment.rs L79-L96 F:crates/arxi-envelope/src/segment.rs L42-L56 F:crates/arxi-envelope/src/segment.rs L91-L118
Store append enforces chain continuity and rejects writes to sealed segments. يفرض تخزين الإلحاق استمرارية السلسلة ويرفض الكتابات إلى القطاعات المختومة. F:crates/arxi-store/src/traits.rs L47-L66
Verifier and provider library boundaries enforce bounded-work fail-closed policies to protect embedding wrappers from unbounded in-memory workloads. F:crates/arxi-recorder/src/verifier.rs L73-L246 F:crates/arxi-recorder/src/evidence_provider.rs L52-L300
SQLite dispatch now uses bounded queue admission and deterministic saturation rejection rather than unbounded operation buffering. يستخدم توزيع SQLite الآن قبول قائمة محدودة ورفض تشبع حتمي بدلاً من تخزين العمليات غير المحدود. F:crates/arxi-store/src/sqlite/connection.rs L42-L136
Sidecar HTTP boundary enforces request identity, optional bearer-token auth with constant-time compare, protocol/header/body bounds, bounded queue and active concurrency gates, timeout fail-closed behavior, and persistent idempotency replay/conflict controls. Probe routes (/health, /startup, /ready) are explicitly exempt from those request gates so orchestration liveness/startup/readiness signals remain observable under stress. F:crates/arxi-sidecar/src/middleware/request_id.rs L15-L30 F:crates/arxi-sidecar/src/middleware/auth.rs L21-L84 F:crates/arxi-sidecar/src/middleware/bounds.rs L21-L172 F:crates/arxi-sidecar/src/idempotency.rs L20-L316
Sidecar container packaging is first-party in-repo and keeps the same fail-closed config + token-hardening model under distroless nonroot runtime and explicit UID/GID bind-mount mapping. F:docker/sidecar/Dockerfile F:docker/sidecar/docker-compose.yml F:docker/sidecar/config/sidecar.toml
Hash equality uses constant-time comparison in core, verifier, and stores. F:crates/arxi-core/src/hash.rs L102-L174 F:crates/arxi-recorder/src/verifier.rs L29-L52 F:crates/arxi-store/src/sqlite/envelope_ops.rs L62-L79

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

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

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

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

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

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

دورة حياة التسجيل المحلي الكامل والتحقق من الحزمة.
SQLite/تخزين في الذاكرة الخلفية.
العمليات المدفوعة بواسطة 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 متصل بتنفيذ محول الإنتاج.
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/arxi-decision-gate-adapter) with deterministic MCP/runpack mapping, runpack-integrity strict/anomaly policy handling, and transcript وحدة تكيف بوابة القرار (crates/arxi-decision-gate-adapter) مع تخطيط MCP/runpack الحتمي، ومعالجة سياسة النزاهة الصارمة/الانحراف، وضوابط حذف النص/الحدود.
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/open/record/query تدفق.
Sidecar readiness semantics now support fail-closed dependency modes: تدعم دلالات جاهزية Sidecar الآن أوضاع الاعتماد المغلقة عند الفشل: جاهزية التخزين فقط وجاهزية التخزين + التحكم المؤسسي.

الفجوات الحالية بعد النواة في سلوك النظام على المستوى:

لا يزال اختبار توسيع نظام الأداء/الضغط P2 مفتوحًا.
Sidecar release-grade perf/soak promotion remains opt-in via ترويج أداء/نقطة انطلاق إصدار Sidecar يبقى اختياريًا عبر ARXI_SIDECAR_PERF_GATE=1 ولا يزال يتطلب ضبط ملف CI.

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

Provider listing/fetch now uses stable bundle IDs and fetch-by-ID segment selectors. قائمة المزودين/جلب الآن تستخدم معرفات الحزم المستقرة ومحددات مقاطع الجلب حسب المعرف. F:crates/arxi-recorder/src/evidence_provider.rs L125-L229
Recorder verifier/provider now enforce explicit bounded-work policy and reject oversized workloads fail-closed at library boundaries. F:crates/arxi-recorder/src/verifier.rs L73-L246 F:crates/arxi-recorder/src/evidence_provider.rs L52-L300
SQLite operation dispatch now applies bounded queue backpressure with deterministic saturation failure behavior. عملية إرسال SQLite الآن تطبق ضغط الصفوف المحدود مع سلوك فشل تشبع محدد. F:crates/arxi-store/src/sqlite/connection.rs L42-L203
Contract generation now overlays inferred schemas with authoritative runtime constraints and fail-closes on missing constraint pointer targets. توليد العقود الآن ي overlay المخططات المستنتجة مع القيود الزمنية الموثوقة ويفشل في الإغلاق عند عدم وجود أهداف مؤشرات القيود. F:crates/arxi-contract/src/lib.rs L565-L742
Sidecar contract-generation/projection integration is now implemented with generated API artifacts (openapi/errors/enums/examples/compat) and fail-closed compatibility gates in CI orchestration. F:crates/arxi-contract/src/lib.rs F:scripts/ci/sidecar_contract_gates.py F:scripts/ci/generate_all.sh
Verifier phase 6 now executes trust-root signature checks with policy evaluation (skip warning only when no trust root is provided). المرحلة 6 من التحقق الآن تنفذ فحوصات توقيع الجذر الموثوق مع تقييم السياسة (تجاوز التحذير فقط عند عدم توفير جذر موثوق). F:crates/arxi-recorder/src/verifier.rs L509-L651
Startup read-back verification now executes from RecorderEngine::new when startup_verification_depth > 0. F:crates/arxi-recorder/src/engine.rs L154-L197 F:crates/arxi-recorder/src/engine.rs L380-L543

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

المنطقة	الملف	الملاحظات
حدود مساحة العمل	`Cargo.toml`	عضوية الحزمة وموقف التحذير.
العقود الأساسية	`crates/arxi-core/src/lib.rs`	البدائل والسمات المشتركة.
نموذج الظرف	`crates/arxi-envelope/src/lib.rs`	نموذج بيانات الأدلة والعقود.
وقت تشغيل المسجل	`crates/arxi-recorder/src/engine.rs`	استيعاب، تقدم السلسلة، دورة حياة المقطع.
الحزمة + المدقق	`crates/arxi-recorder/src/bundle_builder.rs`	حل المحدد وتجسيد الحزمة.
التحقق من الحزمة	`crates/arxi-recorder/src/verifier.rs`	تحقق غير متصل من 7 مراحل.
سمات التخزين	`crates/arxi-store/src/traits.rs`	ثوابت عقد الاستمرارية.
حدود قائمة SQLite	`crates/arxi-store/src/sqlite/connection.rs`	توزيع محدود من غير المتزامن إلى المتزامن وسلوك الفشل المغلق.
واجهة سطر الأوامر	`crates/arxi-cli/src/main.rs`, `crates/arxi-cli/src/commands.rs`, `crates/arxi-cli/src/support.rs`	هيكلية أوامر تشغيلية مقسمة عبر التوزيع، معالجات الأوامر، ومساعدات وقت التشغيل/الأدوات.
خدمة Sidecar	`crates/arxi-sidecar/src/lib.rs`, `crates/arxi-sidecar/src/server.rs`	وقت تشغيل HTTP، مجموعة الوسائط، ودورة حياة النقل.
إعدادات/أمان Sidecar	`crates/arxi-sidecar-config/src/config.rs`, `crates/arxi-sidecar-config/src/validation.rs`, `crates/arxi-sidecar/src/middleware/auth.rs`, `crates/arxi-sidecar/src/middleware/bounds.rs`, `crates/arxi-sidecar/src/idempotency.rs`	تحقق من إعدادات الفشل المغلق وسلطة الإسقاط بالإضافة إلى ضوابط المصادقة/الحدود الخاصة بـ Sidecar وسلوك الاستمرارية الدائم.
تعبئة حاوية Sidecar	`docker/sidecar/Dockerfile`, `docker/sidecar/docker-compose.yml`, `docker/sidecar/config/sidecar.toml`	ملف بناء/تشغيل حاوية من الطرف الأول متماشي مع ثوابت تحقق/أمان Sidecar.
مولد العقود	`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`	سلطة الأثر الناتج المحدد + فحوصات الانحراف.
اختبارات النظام	`system-tests/README.md`	عقد تحقق شامل.
محول Decision Gate	`crates/arxi-decision-gate-adapter/src/adapter.rs`	تنفيذ سياسة الإنتاج للتخطيط/التحرير/سلامة البيانات لاستيعاب Decision Gate.
اختبارات تكامل OpenClaw	`system-tests/tests/suites/integration_openclaw.rs`	تحقق من استيعاب المحول المدفوع بالترتيب لتوصيل سير العمل الخارجي.
بنية تكامل OpenClaw	Docs/architecture/arxi_openclaw_integration_architecture.md	عقد سياسة التخطيط والتحرير/الحمولة المحدودة بالإصدار.
اختبارات تكامل Decision Gate	`system-tests/tests/suites/integration_decision_gate.rs`	تحقق من تدفق استيعاب MCP المدفوع بالترتيب لتوصيل مستوى التحكم.
بنية تكامل Decision Gate	Docs/architecture/arxi_decision_gate_integration_architecture.md	تخطيط تدفق MCP بالإصدار، سياسة سلامة تدفق التشغيل، وعقد تحرير/حدود النص.