البنية المعمارية

FactLane خدمة لمشاركة الحقائق بين وكلاء MCP. تدعم السجلات المخزنة اتخاذ القرار، لكنها لا تتقدّم على تعليمات المستخدم الحالية، أو حالة المستودع، أو مصدر حي ذي مرجعية موثوقة. ويفصل النظام بين حدود النقل، والتخويل، ودورة حياة الحقيقة، والتخزين.

مسار الطلب

Local MCP host / trusted launcher
  -> immutable host and write-context bindings
  -> stdio MCP gateway (five tools)
  -> scope, identity and authority checks
  -> memory adapter / bounded retrieval routing
  -> local embedding provider + SQLite-vec storage

يتلقى MemoryGateway العمليات الخمس: memory_search وmemory_get و memory_store وmemory_update وmemory_status. ويرفض وسائل النقل غير المدعومة وادعاءات هوية المضيف التي يقدّمها المستدعي. ويتولى MemoryAdapter التحقق من الطلبات، والحداثة، والأذونات، ومعالجة التناقضات، وميزانيات الاسترجاع، وسياسة المراجعات؛ بينما يختار TruthRouter سلوك البحث المحدود داخل المحوّل. وتوفّر الواجهة الخلفية اتصالات SQLite وأوليات SQLite-vec، من دون أن تتولى قرارات التخويل الخاصة بـFactLane.

تحوّل حدود الخادم العامة إخفاقات AdapterError المحكومة إلى شكل نتيجة MCP العادي مع status=BLOCKED وerror_code ثابت وmessage آمنة وresults فارغة وبيانات تدقيق موثوقة. يحدث هذا التحويل عند حدود الخادم العامة فقط؛ أما المستدعون المباشرون للبوابة/المحوّل فيستمرون في تلقي AdapterError، وتظل الاستثناءات غير المتوقعة أخطاء نقل MCP بدل إعادة تصنيفها باعتبارها نتائج محكومة.

يدعم الخادم stdio المحلي فقط. ويُعد Codex وHermes تكاملين مضيفين جرى اختبارهما، لكن مسار الإرسال ليس خاصًا بأي منهما. ويمكن لعميل آخر يدعم MCP عبر stdio ويُشغَّل بأمر أن يستخدم الملف التنفيذي نفسه؛ ولا يصبح بذلك تلقائيًا مضيفًا مؤهلًا على نحو منفصل. ولا تمثل هوية المشغّل تصديقًا تشفيريًا أو من نظام التشغيل.

النطاق والهوية الموثوقة

يعرّف العقد العام خمسة نطاقات:

النطاق	متطلب الهوية
GLOBAL_USER	لا توجد هوية مشروع/سير عمل.
PROJECT	project_id دقيق.
WORKFLOW	project_id وworkflow_id دقيقان.
TOOL_ENVIRONMENT	agent_id دقيق.
CROSS_PROJECT_WORKFLOW	يجب غياب كل مفاتيح هوية المشروع وworktree وسير العمل والوكيل.

عندما يزوّد المشغّل الموثوق هويات السياق الحالي، تُدخل البوابة القيم المفقودة المنطبقة لـPROJECT وWORKFLOW وTOOL_ENVIRONMENT. وتؤدي القيمة الصريحة المتعارضة إلى الفشل بالرمز BOUND_CONTEXT_IDENTITY_MISMATCH؛ ولا يُعاد كتابة الطلب الأصلي. ولا يرث GLOBAL_USER وCROSS_PROJECT_WORKFLOW الهويات المربوطة. ويُستخدم النطاق الأخير لقواعد سير العمل التي تنطبق عبر المشاريع، وليس لاستعلام يبحث في كل مشروع تباعًا.

المساهمات والتحقق والمراجعات

تبدأ العملية العادية باستخدام --write-profile read-only ما لم يمنح المشغّل ملف تعريف آخر. ويسمح delegated-candidate للوكيل بإرسال CANDIDATE محدود مع منشأ المصدر، وسياسة حداثة، ومفتاح idempotency. ولا يسمح لذلك الوكيل بإنشاء VALIDATED_CURRENT عبر ادعاء هوية متحقق داخل الطلب.

الترقية عملية memory_update مستقلة: يستخدم متحقق موثوق REVERIFY، والمراجعة المتوقعة، والمعرّف الدقيق expected_record_id الخاص بـCandidate (المرشّح). ويحافظ عقد التخزين v2 على contribution_origin منفصلًا عن التحقق ويصونه أثناء الترقية. ويُسجّل المتحقق بصورة منفصلة؛ ولا يُعاد كتابة سجل أقدم بصمت كما لو أن المتحقق هو من ساهم به. كما يحافظ REVERIFY على هوية التناقض: تظل الحقيقة، والنطاق، ونوع الذاكرة، والموضوع هي الذاكرة المنطقية نفسها. ويجب أن تطابق التأكيدات الحاملة للهوية السجل القائم؛ أما إعادة التصنيف الدلالي فتستخدم REPLACE.

تستخدم تغييرات المراجعة compare-and-swap داخل المعاملة. ويتلقى الكاتب المستقل الذي يعمل على مراجعة متقادمة VERSION_CONFLICT. وعند ترقية Candidate، تجري فحوص النطاق الدقيق، والذاكرة المنطقية، والسجل الأب، والمراجعة، ودورة الحياة، والتناقض داخل معاملة SQLite نفسها. وتُحسم الطلبات المكررة أو المعاد إرسالها وفق قواعد idempotency المحكومة؛ ومفتاح idempotency القادم من طلب أكثر امتيازًا ليس رمز تخويل.

يحظر عقد التخزين v2 أيضًا على كتّاب legacy القدامى إدخال سجلات المحوّل أو تحديثها أو حذفها عبر اتصال SQLite خام غير موثوق. ولمسار الصيانة الموثوق حد تخويل منفصل؛ وهذا لا يجعل عمليات SQL المباشرة الاعتباطية جزءًا من الواجهة العامة. وبما أن تخويل الكاتب دالة SQLite محلية للاتصال، فإن الاتصال الخام غير المسجل يُرفض عند حل الدالة مع no such function: factlane_contract_v2_writer؛ ولا يصل التنفيذ إلى نص RAISE الخاص بالـtrigger الدائم في ذلك الاتصال، لكن التغيير يظل يفشل في وضع مغلق.

الاسترجاع والسجل التاريخي

يسمح استرجاع CURRENT فقط بحقائق VALIDATED_CURRENT المؤهلة داخل النطاق الدقيق. وفي البحث بالكلمات المفتاحية، يسبق مرشح دورة الحياة حدود SQL. أما في البحث الدلالي، فتقيّد sqlite-vec KNN معرّفات الصفوف المؤهلة **داخل استعلام المتجه قبل k **. وإلا فقد تملأ مرشّحات Candidate غير المتحقق منها والأقرب دلاليًا النتائج العليا وتحجب حقيقة متحقَّقًا منها لكنها أبعد.

بعد اجتياز مرشّحات CURRENT الدلالية/الهجينة فحوص دورة الحياة والحداثة، يختار المحوّل أعلى المرشّحات ترتيبًا من مصادر منشأ مخزنة مختلفة قبل ملء الخانات المتبقية بمرشّحات من مصادر مكررة. ويقلل ذلك ازدحام المصدر نفسه من دون تغيير الدرجات المخزنة: تُحفظ أفضل نتيجة مؤهلة، وتُصدر المجموعة المختارة بترتيب الملاءمة الأصلي. وبعد أفضل نتيجة، يمكن لذلك أن يضع مصدرًا لم يظهر بعد في خانة تسبق نتيجة أعلى درجة من المصدر نفسه؛ وهذه مفاضلة تنوع مقصودة وليست إعادة كتابة للدرجات. ويتجاوز الاسترجاع Exact وkeyword-only وREVIEW_HISTORY خطوة التنوع هذه.

يعرض REVIEW_HISTORY المراجعات السابقة ومرشّحات Candidate للفحص الصريح. ويمكن للضغط الذري أن يحتفظ بسجل تاريخي من دون متجهه الأصلي. وإذا أصبح السجل الدلالي أو الهجين غير مكتمل نتيجة لذلك، فتبلغ النتيجة عن degradation=HISTORY_SEMANTIC_PARTIAL. وعندما يتجاوز الناتج أيضًا ميزانية النتائج، يحافظ budget.truncated=true على إشارة الاقتطاع المستقلة؛ أما الاقتطاع العادي الناتج عن الميزانية وحدها فيبلغ عن BUDGET_EXCEEDED.

توافق التخزين وبيئة التشغيل

يستخدم FactLane واجهة خلفية مثبتة الإصدار من mcp-memory-service لآليات SQLite/SQLite-vec القابلة لإعادة الاستخدام، وقفل الاتصال، ومحاولات إعادة محدودة عند busy، وتهيئة WAL، والأوليات المتعلقة بالاتصال. ويتولى FactLane دلالات المخطط/المعاملات والتخويل على المستوى الأعلى. ولا يفترض أن إصدار Python يثبت دعم ميزات SQLite.

يجب أن تكون بيئة تشغيل SQLite المرتبطة 3.42.0+. ويرفض SQLiteVecEngine.open() بيئة تشغيل أقدم قبل إنشاء قاعدة البيانات أو فتحها، مع BACKEND_COMPATIBILITY_MISMATCH. ويغطي هذا الحد الأدنى سلوك IN للصفوف المؤهلة في sqlite-vec وميزة FTS5 secure-delete المطلوبة لاستعادة الذاكرة الحساسة. كما ينفذ ذلك المشغّل فحص ميزات مستقلًا قبل التغيير.

تستخدم استدعاءات التضمين عقد EmbeddingProvider. والمزوّد المضمّن حاليًا هو Ollama عبر loopback HTTP؛ وتفشل فحوص بصمة النموذج، والإمكانات، والأبعاد، وحجم الإدخال في وضع مغلق. وتُنقل استدعاءات المزوّد التي قد تحجب التنفيذ خارج asyncio event loop. ولا يوجد مزوّد cloud embedding مضمّن ولا fallback خارجي تلقائي. راجع سياسة البيئة لملفات التعريف المضمّنة والمتطلبات الدقيقة.

الصيانة واستعادة الحوادث

يوفّر memory_status ملاحظات محدودة وللقراءة فقط عن السعة والاحتفاظ. وتضغط الصيانة اليدوية المواد المستبدلة المؤهلة عبر مسار ذري مع الحفاظ على المرجعية الحالية والسجل المنطقي. وهي ليست retention daemon تلقائيًا، ولا وسيلة نسخ احتياطي كاملة، ولا عملية محو للمحتوى الحساس.

تعيش استعادة حوادث الذاكرة الحساسة داخل مشغّل محلي موثوق، خارج MemoryGateway وأدوات MCP الخمس. وتتطلب تخويلًا صريحًا، وربطًا دقيقًا للهدف/قاعدة البيانات، وسكونًا للصيانة، ومخططًا وانتشارًا معروفين، وSQLite مدعومًا وإمكانات FTS5 متحقَّقًا منها. ويؤدي الإخفاق قبل الالتزام (commit) إلى التراجع (rollback)؛ أما فشل الإحكام (sealing) بعد الالتزام فيترك حاجزًا دائمًا (interlock) مقيمًا داخل قاعدة البيانات يمنع بدء وقت التشغيل العادي عبر إعادة تشغيل العمليات إلى أن تكتمل الاستعادة المتحقَّق منها. ولا يثبت التطهير المحلي المحو من النسخ الخارجية أو الوسائط المادية. راجع الأمان.

الاستبعاد بين وقت التشغيل والاستعادة تعاوني ومستقل عن العملية على مضيفي POSIX المدعومين: تحل مثيلات SQLiteVecEngine العادية مسار قاعدة البيانات مرة واحدة، وتحصل على shared advisory flock على inode الخاص بقاعدة البيانات قبل تهيئة الـbackend، وتحتفظ به إلى أن يثبت إغلاق الـbackend. وتحصل الاستعادة على exclusive inode lock المقابل قبل أول فحص للسكون. وأثناء sealing تقفل أيضًا inode الخاص بالبديل المنقح قبل os.replace()، ثم تحتفظ بقفل inode القديم المتقاعد وقفل inode الجديد المرقّى طوال postflight الذي يملكه المشغّل. ولذلك تتقارب hard-link aliases على هوية kernel lock نفسها، ولا تكشف الترقية أبدًا inode بديلًا غير مقفل. ويتلقى أي ربط جديد لوقت التشغيل أثناء الاستعادة MAINTENANCE_IN_PROGRESS. ويستخدم محرك postflight الخاص بالمشغّل capability داخلية ودقيقة لـinode مشتقة من exclusive lease التي ما تزال حية.

إذا لم يتمكن تنظيف postflight من إثبات إغلاق مقبض SQLite، بما في ذلك عند إلغاء المهمة، فتحتفظ الاستعادة بكل exclusive inode leases المملوكة للعملية في وضع fail-closed بدل إعادة فتح الخدمة العادية. ويحرر خروج العملية واصفات الملفات تلك؛ لكن حالة sealing غير المكتملة ما تزال تتطلب تسوية من المشغّل.

يقتصر ضمان الاستبعاد على أنظمة الملفات المحلية POSIX المدعومة ذات دلالات flock الموثوقة؛ ولا يمتد إلى Windows أو سلوك قفل الشبكة/FUSE غير المتحقق منه. وهو حد تعاوني لوقت تشغيل FactLane، وليس دفاعًا ضد استبدال ملفات اعتباطي ينفذه process خارجي ذو امتيازات، لذلك يظل إجراء جرد السكون/ الإيقاف الكامل المستقل جزءًا من الاستعادة.

حدود الإصدار والترحيل

حزمة/بيئة تشغيل Python وقاعدة البيانات الدائمة سطحا توافق مرتبطان لكن منفصلان. فتثبيت حزمة أحدث لا يرحّل قاعدة بيانات بحد ذاته، واستبدال الحزمة بنجاح لا يثبت أن بيئة تشغيل أقدم تستطيع إعادة فتح حالة لمسها إصدار أحدث بأمان. ويجب على أي إصدار يغيّر المخطط المخزن أو دلالات البيانات أن يوفّر عقد ترحيل صريحًا، وتحققًا بعد الترحيل، وأي مسار rollback/restore مدعوم.

v0.1.3 هو أول إصدار إنتاج رسمي، ولا يعرّف عقد خفض إصدار لبيانات الإنتاج عبر الإصدارات. ويعرّف دليل تشغيل عمليات الإصدار النسخة المنشورة من خلال هدف الوسم المسجّل، وشجرة Git، وبصمات العناصر المنشورة، ويشترط ألا تعيد الصيانة اللاحقة توجيه ذلك الوسم بصمت أو تستبدل أصوله لتطابق بايتات مختلفة. ويظل على المشغّلين التحقق من تلك الهويات لأن منصة الاستضافة قد تسمح تقنيًا بالتعديل. ولا تغيّر الوثائق أو تغييرات التطوير اللاحقة على main الهوية المسجلة لإصدار منشور بالفعل. ويوجد إجراء هوية الإصدار والانتقال الدقيق في عمليات الإصدار.

حدود التأهيل

FactLane 0.1.3 مؤهّل للإنتاج للتكوين المحلي الموثق: بيئة تشغيل Python المعبأة، وعقد التخزين SQLite/SQLite-vec المرتبط، وسطح MCP عبر stdio، وملف تعريف التضمين المحلي المدعوم، وتكاملات المضيف المحلي المضبوطة. واختبر التأهيل توافق النسخ الاحتياطي/الاستعادة، والتشغيل المتزامن المحدود، وrollback بعد crash/restart، والاسترجاع المستمد من الإنتاج، وسلوك سعة SQLite الذي يفشل في وضع مغلق.

ولا تثبت هذه الأدلة دعم كل عميل MCP، أو نظام ملفات اعتباطي، أو نمط استيعاب على نطاق إنتاجي، أو حملًا غير محدود المدة، أو كل مزيج لغات. ويقلل اختيار CURRENT الدلالي/الهجين المتنوع حسب المصدر إحدى آليات ازدحام المستندات المعروفة، لكن الملاءمة الدلالية — بما في ذلك ترتيب العربية/ اللغات المختلطة — تظل مرتبطة بعبء العمل. FactLane مخزن حقائق، وليس أرشيف محادثات أو زاحفًا للمستندات الخام.