عمليات الإصدار: التثبيت والترقية والتراجع وإعادة التحقق

يحدد دليل التشغيل هذا الإجراء العام للمشغّل لاستخدام إصدار محدد من FactLane ولتخطيط الانتقالات اللاحقة بين الإصدارات. تتكون هوية الإصدار من الوسم ذي الإصدار مع الـ commit/tree المتحقق منهما، والقيم المسجلة لملخصات artifacts المنشورة لذلك الوسم. ولصيانة الإصدارات، يشترط هذا الدليل ألا تُعاد توجيه الوسوم المنشورة بصمت وألا تُستبدل الأصول المنشورة لجعل وثائق لاحقة تتفق مع bytes مختلفة. يمكن لأذونات المنصة تقنيًا تعديل هذه الكائنات، لذلك تحقّق من الهويات بدلًا من الثقة في الاسم وحده. وقد يتلقى فرع main تغييرات في الوثائق أو التطوير بعد الإصدار، ولذلك يجب ألا يُستخدم بديلًا عن هوية إصدار تاريخية.

عقد هوية الإصدار

لكل إصدار رسمي، سجّل كل ما يلي قبل التثبيت أو الترقية:

• الإصدار والوسم annotated tag؛
• الـ commit وGit tree اللذان يصل إليهما ذلك الوسم؛
• أسماء wheel وsource distribution المنشورة وملخصات SHA-256 الخاصة بها؛
• متطلبات Python وSQLite المرتبط؛
• Public Contract Revision ومجموعة أدوات MCP العامة الدقيقة؛
• أي متطلبات لترحيل البيانات/schema وعقد التراجع الخاص بها؛
• الحدود أو قيود التأهيل الخاصة بالإصدار.

لا تستنتج التوافق من رقم الإصدار وحده. توافق الحزمة، وتوافق وقت التشغيل، وتوافق قاعدة البيانات/schema هي ادعاءات منفصلة.

Manifest الخاص بـ FactLane v0.1.3

v0.1.3 هو أول إصدار إنتاج رسمي من FactLane. وهويته المنشورة هي:

العنصر	هوية v0.1.3
Annotated tag	v0.1.3
Tag object	d922fcceae7cfbfda239666182e61a5a58278809
Release commit	59173b7d9fa3af924c373176411882caa04a6c1d
Release tree	93db940802432b6f9ca2f5513916fd2b84c6393a
Wheel	factlane-0.1.3-py3-none-any.whl
Wheel SHA-256	daf145cd7754b7c46a0f18ad49cc8872291094c8ac84621fce3cec091f90072a
Source distribution	factlane-0.1.3.tar.gz
Source distribution SHA-256	81de371ec23d17109f9267750fed80cd6492cee245681d72630da6868f3cd16b
Python	>=3.11
Linked SQLite	>=3.42.0
Public Contract Revision	2
Public MCP tools	memory_search, memory_get, memory_store, memory_update, memory_status

أصول الإصدار منشورة في GitHub Release for v0.1.3. تحقّق من bytes التي نزّلتها بمقارنتها بالملخصات أعلاه قبل التثبيت.

حدود دعم v0.1.3

بالنسبة إلى v0.1.3، يتمثل الملف المدعوم الموثق في MCP محلي من نوع stdio يُشغَّل بالأوامر، وPython 3.11+، وSQLite مرتبط 3.42.0+، وتضمينات Ollama محلية مدعومة، وعقد التخزين/الاستعادة المحلي الموثق على POSIX.

لا يثبت الإصدار جودة دلالية لكل اللغات، ولا سلوكًا اعتباطيًا لعملاء MCP أو نظام الملفات، ولا مقياس نشر اعتباطيًا. تظل الصلة الدلالية للعربية/المحتوى مختلط اللغات خاصة بعبء العمل. وقد اختُبر استنفاد سعة SQLite بصورة حتمية وسلوك القراءة فقط بسبب الأذونات؛ أما حالة kernel ENOSPC حقيقية وmount EROFS حقيقي فلم تُختبرا.

v0.1.3 هو أيضًا أول إصدار رسمي. لا يوجد إصدار إنتاج رسمي أقدم يستطيع FactLane تسميته هدف تراجع إنتاجي مدعومًا. وقدرة مثبت الحزم على استبدال إصدار بآخر ليست دليلًا على أن وقت تشغيل أقدم يمكنه فتح قاعدة بيانات عدّلها إصدار أحدث بأمان.

تثبيت إصدار دقيق

الخيار A: versioned source checkout

استخدم وسم الإصدار ذي النسخة، وتحقق من commit/tree الخاصين به، بدل الاعتماد على فرع main المتحرك:

git clone --branch v0.1.3 --depth 1 https://github.com/Habib1001-m/factlane.git
cd factlane

test "$(git rev-parse HEAD)" = "59173b7d9fa3af924c373176411882caa04a6c1d"
test "$(git rev-parse 'HEAD^{tree}')" = "93db940802432b6f9ca2f5513916fd2b84c6393a"

uv sync --frozen
uv run python -c 'import sqlite3; print(sqlite3.sqlite_version)'
uv run factlane --help
uv run factlane --help-tools

الخيار B: wheel المنشورة

نزّل wheel الخاصة بالإصدار، وتحقق منها، ثم ثبّتها في بيئة جديدة:

curl -fLO https://github.com/Habib1001-m/factlane/releases/download/v0.1.3/factlane-0.1.3-py3-none-any.whl
printf '%s  %s\n' \
  'daf145cd7754b7c46a0f18ad49cc8872291094c8ac84621fce3cec091f90072a' \
  'factlane-0.1.3-py3-none-any.whl' | sha256sum -c -

python3.11 -m venv .venv
.venv/bin/python -m pip install ./factlane-0.1.3-py3-none-any.whl
.venv/bin/python -m pip check
.venv/bin/factlane --help
.venv/bin/factlane --help-tools

تحتوي wheel على اعتماد Git مثبت على mcp-memory-service؛ ولذلك يحتاج التثبيت الجديد عبر الإنترنت إلى الوصول إلى مراجعة GitHub المثبتة تلك ما لم يكن الاعتماد متاحًا بالفعل عبر cache أو mirror يتحكم فيه المشغّل. تسجل wheel متطلبات FactLane المباشرة، لكن قد يحل مثبت جديد إصدارات أحدث متوافقة من الاعتمادات transitive مقارنة بالبيئة التي يلتقطها lockfile في المستودع. عندما تكون إعادة تشغيل الاعتمادات بدقة مهمة، استخدم source checkout الموسوم مع uv sync --frozen وملف uv.lock المحفوظ معه.

يُعد source distribution أيضًا سطح clean-install مدعومًا بعد التحقق من SHA-256 الخاص به:

curl -fLO https://github.com/Habib1001-m/factlane/releases/download/v0.1.3/factlane-0.1.3.tar.gz
printf '%s  %s\n' \
  '81de371ec23d17109f9267750fed80cd6492cee245681d72630da6868f3cd16b' \
  'factlane-0.1.3.tar.gz' | sha256sum -c -

python3.11 -m venv .venv
.venv/bin/python -m pip install ./factlane-0.1.3.tar.gz

تُشحن Skill المحمولة using-factlane مع الحزمة، لكن تثبيت الحزمة لا يسجل Skill لدى مضيف MCP تلقائيًا.

إجراء الترقية للإصدارات اللاحقة

عامل كل انتقال بين إصدارين باعتباره واحدًا من ثلاث فئات تغيير مختلفة قبل تنفيذ أي عمل:

1. Package/runtime only — تتغير حزمة Python أو الاعتمادات أو الوثائق أو إعداد تشغيل المضيف، بينما يظل تنسيق قاعدة البيانات الحالي متوافقًا بصورة صريحة.
2. Data/schema migration — يغير الإصدار الجديد schema المخزنة أو دلالات البيانات ويوفر إجراء ترحيل صريحًا.
3. Compatibility not established — لا ينص الإصدار على إمكانية استخدام قاعدة بيانات موجودة مع وقت التشغيل الجديد. لا تستنتج مسار ترحيل.

قائمة التحقق قبل الترقية

قبل تبديل نشر قيد التشغيل:

1. سجّل الإصدار الحالي، وهوية المصدر/artifact الدقيقة، وإصدار Python، وإصدار SQLite المرتبط، وembedding profile، وإعداد تشغيل المضيف.
2. اقرأ ملاحظات الإصدار المستهدف ودليل التشغيل هذا. حدّد هل الانتقال package-only أم يتضمن data/schema migration صريحًا.
3. احتفظ بوقت التشغيل الحالي أو source checkout حتى يظل التراجع على مستوى الحزمة ممكنًا ميكانيكيًا.
4. أنشئ نسخة احتياطية يملكها المشغّل وتحقق منها لأي قاعدة بيانات تهم حالتها. وتظل سياسات الاحتفاظ بالنسخ الاحتياطية وإجراءات الاستعادة من مسؤوليات النشر.
5. حدّد هدف التراجع قبل تغيير البيانات. إذا لم يوثق الإصدار هدف تراجع متوافقًا، فاعتبر التراجع عن البيانات غير مدعوم.
6. أوقف FactLane أو أدخله في حالة quiesce قبل أي إجراء خاص بالإصدار ينص على أن الوصول الحصري إلى قاعدة البيانات مطلوب.

ثبّت الهدف بجوار وقت التشغيل الحالي

فضّل بيئة افتراضية جديدة أو source checkout منفصلًا ذا إصدار بدل تعديل البيئة النشطة في مكانها. تحقق أولًا من ملخص artifact الهدف أو tag/commit/tree، ثم ثبّت باستخدام مسار الاعتماد المعلن لذلك الإصدار. ولإعادة تشغيل lockfile بدقة، استخدم source checkout ذا الإصدار وملف uv.lock المحفوظ معه.

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

إعادة التحقق بعد التثبيت أو الترقية

قبل تمكين الكتابات، تحقق من الإصدار كما هو مثبت:

1. أكّد إصدار الحزمة والاعتمادات:

   python -c 'from importlib.metadata import version; print(version("factlane"))'
   python -m pip check

2. أكّد وقت تشغيل SQLite المرتبط من المفسر نفسه:

   python -c 'import sqlite3; print(sqlite3.sqlite_version)'

3. افحص مرجع الأدوات العامة دون اتصال:

   factlane --help-tools

   بالنسبة إلى v0.1.3، يجب أن يبلغ هذا عن Public Contract Revision 2 وعن الأدوات الخمس الواردة في manifest الإصدار أعلاه تحديدًا.

4. أكّد bytes الخاصة بـ Skill المحمولة لسطح التثبيت. بالنسبة إلى tagged source checkout، تحقق من النسخة المصدرية المتتبعة:

   sha256sum skills/using-factlane/SKILL.md

   وبالنسبة إلى تثبيت wheel أو source distribution داخل .venv المستخدمة في الأمثلة أعلاه، تحقق من ملف البيانات المثبت:

   sha256sum .venv/share/factlane/skills/using-factlane/SKILL.md

   بالنسبة إلى v0.1.3، يجب أن ينتج أي من المسارين المنطبقين hash بالقيمة 1c28bc370af0dd89499f8121fb7b611afb4c83773207ce546136abd8018f3e24. ويحافظ source checkout المتزامن باستخدام uv sync --frozen على Skill الموثوقة في شجرة المصدر ولا يحتاج إلى نسخ ملف البيانات ذلك تحت بادئة البيئة الافتراضية.

5. شغّل مضيف stdio المهيأ في write profile المقصود وتأكد من أن اكتشاف الأدوات يطابق عقد الإصدار. ظهور الأداة لا يمنح سلطة كتابة.

6. عند التحقق من مسار نشر جديد، فضّل قاعدة بيانات disposable لاختبارات smoke. وإذا كان الإصدار يتضمن data/schema migration، فنفّذ فحوص السلامة والترحيل الخاصة بالإصدار قبل استئناف الخدمة العادية.

إجراء التراجع

للتراجع معنيان مختلفان ويجب عدم الخلط بينهما.

التراجع عن package/runtime

إذا لم يحدث تغيير غير متوافق في data/schema، فأوقف وقت التشغيل الجديد وعد إلى البيئة السابقة المحفوظة أو source checkout ذي الإصدار. أعد التحقق من هوية الحزمة وSQLite المرتبط والعقد العام وإعداد المضيف قبل استئناف الخدمة.

بالنسبة إلى v0.1.3، لا يوجد إصدار إنتاج رسمي أقدم لاستخدامه هدف تراجع رسميًا. وقدرة مدير الحزم على استبدال إصدارات الحزمة المثبتة لا تنشئ مثل هذا الهدف ولا تثبت أن خفض إصدار قاعدة البيانات آمن.

التراجع عن data/schema

لا تشغّل مطلقًا binary أقدم من FactLane على قاعدة بيانات ربما رُحلت أو أصبحت غير متوافقة بسبب إصدار أحدث، ما لم يعلن الإصدار الأحدث صراحة أن downgrade آمن. يتطلب التراجع عن data/schema ترحيلًا عكسيًا خاصًا بالإصدار أو استعادة نسخة احتياطية متحقق منها من قبل الترقية، تحت وقت تشغيل موثق بأنه متوافق مع تلك النسخة الاحتياطية.

بالنسبة إلى v0.1.3، لا يُدّعى وجود عقد لترحيل بيانات الإنتاج عبر الإصدارات أو خفض الإصدار. إذا احتاج نشر ما إلى هذا المسار، فتحقق منه لذلك النشر قبل الاعتماد عليه.

قائمة تحقق مؤلف الإصدار للإصدارات المستقبلية

ينبغي أن يستخدم كل إصدار رسمي لاحق قائمة التحقق هذه:

1. قبل النشر، اذكر ملف Python/SQLite/runtime المطلوب وpublic contract revision/tool set الدقيقين.
2. صنّف الانتقال من كل إصدار رسمي سابق مدعوم على أنه package-only أو data/schema migration أو unsupported.
3. إذا وجدت تغييرات data/schema، فوثّق متطلبات النسخ الاحتياطي، والترحيل إلى الأمام، وفحوص السلامة بعد الترحيل، ومسار التراجع أو الاستعادة المدعوم قبل الإصدار.
4. جمّد release tree دقيقة واحدة؛ وابنِ wheel وsource distribution من تلك الشجرة؛ وتحقق من التثبيت النظيف وpackage metadata وتكافؤ runtime-source وتكافؤ Skill المحمولة.
5. أعد التحقق من مضيف MCP المهيأ ومجموعة الأدوات العامة الدقيقة قبل النشر.
6. انشر الوسم والأصول فقط بعد اجتياز بوابات الإصدار. لا تغيّر وسمًا منشورًا بالفعل ولا تستبدل أصوله لجعل وثائق لاحقة تتفق معه.
7. سجّل tag object وcommit وtree وأسماء artifacts وملخصات SHA-256 النهائية في manifest ذي الإصدار. وإذا لم يمكن معرفة هذه الهويات حتى النشر، فسجّلها في commit لاحق على main مخصص للوثائق فقط بدل تعديل released tag/tree.
8. رحّل إلى الأمام ادعاءات الدعم المدعومة بالأدلة فقط. لا يجوز توسيع ادعاءات الجودة الدلالية للعربية/المحتوى مختلط اللغات، أو kernel ENOSPC، أو EROFS الحقيقي، أو سلوك نظام الملفات، أو تغطية العملاء، أو حدود الحجم من دون دليل مباشر.
9. لا تُعد توجيه وسم إصدار سابق ولا تستبدل أصوله المنشورة. استمر في التحقق من الإصدارات التاريخية عبر commit/tree المسجلين وartifact digests. ولا يعيد تغيير صيانة للوثائق على main كتابة إصدار تاريخي.

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