بعد قصيدة ريتشارد بروتيغان، ومع إيماءة لمقال داريو أمودي حول إمكانات الذكاء الاصطناعي.

ملخص​

الأنظمة المستقلة (Autonomous Systems) أصبحت أكثر قدرة — ولكن أصعب في الفهم.

أنظمة التعلم الآلي (Machine Learning Systems) يمكنها اليوم أن ترى، وتصنّف، وتتنبأ، وتحسّن الأداء في مجالات كانت سابقًا تعتمد على البشر فقط. لكن كلما زادت القدرة، تقل غالبًا قابلية التفسير (Interpretability) — أي قدرتنا على فهم لماذا اتخذ النظام قرارًا معينًا.

في البيئات الحساسة للسلامة (Safety-Critical Environments)، هذا يخلق مشكلة خطيرة:
الأنظمة قد تتصرف أسرع مما يستطيع الإنسان فهم سبب تصرفها.

تقدم هذه المقالة مفهوم آلات السمات (Trait Machines) — وهو نموذج لوصف سلوك الأنظمة بطريقة واضحة وقابلة للفحص، دون التخلي عن قوة التعلم الآلي.

آلات السمات تجمع بين:

1. منطق آلة الحالة (State Machine Semantics) — طريقة منظمة لوصف حالات النظام وانتقالاته
2. حراس قيود حتمية (Deterministic Constraint Guards) — شروط أمان واضحة يجب أن تتحقق قبل التنفيذ
3. سمات سلوكية تركيبية (Composable Behavioral Traits) — وحدات سلوك يمكن تركيبها معًا بسهولة
4. تعلم آلي داخل حدود أمان (Machine Learning inside Safety Envelopes)

الفكرة الأساسية بسيطة لكنها قوية:

المواصفة (Specification) هي النظام نفسه.

أي أن التعريف المكتوب هو الذي يحدد السلوك، ويتأكد من صحته، ويولد كود التنفيذ أثناء التشغيل.

I. المشكلة التي قبلناها بصمت​

الأنظمة الذكية الحديثة مبنية على مقايضة لا نتحدث عنها كثيرًا:

كلما أصبح النظام أذكى، أصبح أصعب في الشرح.

في الماضي، كان هذا مقبولًا لأن الأنظمة كانت صغيرة وتحت سيطرة البشر.

لكن اليوم، الأنظمة المستقلة تدخل العالم الحقيقي:

المستشفيات. الطرق. المنازل. المصانع. المدارس.

في هذه الأماكن، الأداء الجيد وحده لا يكفي.
يجب أن يكون السلوك مفهومًا أثناء حدوثه (Real-Time) — وليس بعد وقوع المشكلة.

اليوم، عند فشل نظام ذكي، غالبًا نقوم بـ:

• إعادة تدريب النموذج (Model Retraining)
• إضافة بيانات (More Data)
• تعديل العتبات (Threshold Tuning)
• ثم نأمل ألا يتكرر الخطأ

هذا يسمى إصلاح إحصائي (Statistical Recovery)، وليس فهم السبب الحقيقي.

آلات السمات تحاول إعادة التركيز إلى الفهم المنطقي الحتمي (Deterministic Reasoning).

II. أهداف التصميم​

تم تصميم آلات السمات لتحقيق خمس نقاط أساسية:

وضوح السلوك (Behavioral Legibility)​

يجب أن نستطيع قراءة سلوك النظام مثل قراءة منطق واضح.

قابلية التركيب (Composable Semantics)​

يمكن بناء النظام من وحدات سلوك صغيرة يمكن اختبارها لوحدها.

فرض السلامة الحتمية (Deterministic Safety Enforcement)​

كل فعل يجب أن يمر عبر شروط أمان واضحة قبل التنفيذ.

تطابق المواصفة مع التشغيل (Specification–Runtime Equivalence)​

ما نكتبه كمواصفة يجب أن يتحول مباشرة إلى سلوك حقيقي أثناء التشغيل.

التوافق مع التعلم (Learning Compatibility)​

نستطيع استخدام التعلم الآلي — لكن داخل حدود واضحة.

III. نموذج آلة السمات (Trait Machine Model)​

آلة السمة هي نوع من آلة الحالة المقيدة (Constrained State Machine).

تتكون من خمسة عناصر:

هذه الفكرة ليست جديدة.
آلات الحالة موجودة منذ عقود.

الجديد هنا هو طريقة التركيب، وإظهار السلوك بشكل واضح للإنسان.

السمات كعقود قدرة (Capability Contracts)​

السمات (Traits) هي وحدات سلوك يمكن ملاحظتها.

يمكنها:

• إضافة قدرة جديدة
• إضافة قيود أمان
• تنظيم السلوك

السلامة هنا ليست طبقة منفصلة.
بل مكتوبة بنفس لغة السلوك نفسه.

مثال: سمة السلامة​

trait ObstacleStop -> Robot

@interaction

initial: patrolling

patrolling -- OBSTACLE_DETECTED --> stopped
when (< @payload.distance 0.5)
do (set motors "off")
   (emit STOPPED { reason: "obstacle too close" })

stopped -- CLEAR --> patrolling
do (set motors "on")

المثال صغير عمدًا.

الأنظمة الصغيرة أسهل في الفهم. الأنظمة المفهومة أسهل في التصحيح. والأنظمة القابلة للتصحيح أكثر أمانًا.

IV. التركيب على مستوى الكيان (Entity Level Composition)

orbital InspectionUnit

entity InspectionRobot [runtime]

position : string
scanResult : string

trait Movement -> InspectionRobot
trait Rotation -> InspectionRobot
trait Scanning -> InspectionRobot
trait ZoneEnforcement -> InspectionRobot

التركيب هنا مسطح (Flat Composition).

يمكنك رؤية سلوك النظام بالكامل دون تتبع شجرة معقدة من التنفيذ. وهذا مهم للتدقيق (Auditability).

V. التعلم داخل القيود (Learning Inside Constraints)

آلات السمات لا تلغي التعلم الآلي. بل تضعه داخل حدود واضحة.

خطوات التنفيذ:

النموذج يقترح فعلًا

النظام يحسب إشارات التحقق

الحراس (Guards) يقررون السماح أو الرفض

يتم تنفيذ الأفعال المسموح بها فقط

مثال: ملاحة متعلمة لكنها مقيدة

trait LearnedNavigation -> Robot

@interaction

initial: idle

idle -- NAVIGATE_TO --> navigating
when (and
      (= @payload.isCollisionFree true)
      (= @payload.speedWithinLimit true)
      (= @payload.avoidsRestricted true))
do (set currentPath @payload.proposedPath)

idle -- NAVIGATE_TO --> idle
when (not (and
           (= @payload.isCollisionFree true)
           (= @payload.speedWithinLimit true)
           (= @payload.avoidsRestricted true)))
do (emit PATH_REJECTED)

هنا:

النموذج يتعلم. لكن الحدود ثابتة وواضحة.

VI. وضوح التشغيل (Runtime Transparency)

النظام ينتج سجلات تنفيذ واضحة (Structured Execution Logs):

14:03:22 State: patrolling
14:03:22 Event: OBSTACLE_DETECTED { distance: 0.3m, type: "person" }
14:03:22 Guard: (< @entity.distance 0.5) → TRUE
14:03:22 Transition: patrolling --> stopping
14:03:22 Effect: (stop motors)

كل قرار يمكن تفسيره منطقيًا.

مثال: حارس سلامة في الرعاية الصحية

when (and
      (<= @payload.appliedForce @entity.forceTolerance)
      (= @payload.verbalConfirmation true)
      (= @entity.emergencyStopAccessible true))

هذا مثال على هندسة سلامة تشغيلية (Operational Safety Engineering)، وليس فلسفة نظرية.

VII. التحقق قبل التشغيل (Static Validation)

يمكن للنظام اكتشاف مشاكل قبل التشغيل (Compile-Time):

حالات لا يمكن الوصول لها

أحداث غير معالجة

أخطاء ربط

حالات توقف (Deadlocks)

هذا ينقل الأخطاء من وقت التشغيل إلى وقت البناء.

VIII. قيود الزمن الحقيقي (Real-Time Constraints)

الحراس يجب أن يكونوا:

حتميين (Deterministic)

سريعَي الحساب

غير معتمدين على حجم النظام الكامل

هذا يسمح بتحليل أسوأ زمن تنفيذ ممكن (Worst-Case Timing Analysis).

التعلم من رفض الحراس

مثال:

PATH_REJECTED → reason: restricted zone violation

هذه البيانات تساعد في تدريب النموذج.

IX. القراءة البشرية (Human Legibility)

الهدف ليس أن يفهمه أي شخص فورًا.

لكن يجب أن يكون:

قابل للفحص من خبراء السلامة

مفهوم لخبراء المجال

قابل للتدقيق من الجهات التنظيمية

قابل للتدريس

X. ما الذي لا تحله آلات السمات

لا تحل:

مشكلة المحاذاة (AI Alignment)

لا تستبدل التعلم الآلي

لا تلغي أخطاء البشر في كتابة المواصفات

لا تستبدل أنظمة الروبوتات الكاملة

هي طبقة مواصفة وسلامة فقط.

XI. المساهمات الأساسية المواصفة = التنفيذ

نفس المصدر يولد السلوك والتنفيذ.

السلامة والقدرة بنفس اللغة

لا يوجد فصل بين الاثنين.

توسيع دائرة الفهم

يمكن فهم المواصفة خارج مجتمع الطرق الرسمية (Formal Methods).

تمثيل قياسي (Canonical Representation)

{
  "from": "idle",
  "event": "NAVIGATE_TO",
  "to": "navigating",
  "guard": ["and",
    ["=", "@payload.isCollisionFree", true],
    ["=", "@payload.speedWithinLimit", true],
    ["=", "@payload.avoidsRestricted", true]
  ]
}

XII. التأثير الاستراتيجي

عندما تدخل الأنظمة الذكية العالم المادي، فإن وضوح السلوك يصبح بنية تحتية — وليس مجرد توثيق.

XIII. الخاتمة

آلات السمات تقترح فكرة بسيطة:

التعلم يعطي التكيف

السمات تعطي الحدود

المواصفة تعطي التنفيذ

السلوك يبقى مفهومًا

الهدف ليس جعل الأنظمة مثالية.

بل هدف عملي:

الأنظمة التي تعمل مع البشر يجب أن تكون مفهومة أثناء عملها.

ليس بعد الحادث. بل أثناء التشغيل.

الجميع يبني أنظمة RAG مع قواعد بيانات متجهة. لقد منحنا ذكاءنا الاصطناعي نظام ذاكرة مهيكل يفهم السياق بالفعل.

مشكلة RAG​

التوليد المُعزَّز بالاسترجاع (RAG) هو النهج المعياري لإعطاء وكلاء الذكاء الاصطناعي ذاكرة:

1. تلقي استعلام المستخدم: "كيف تعاملت مع المصادقة آخر مرة؟"
2. توليد متجه التضمين
3. البحث في قاعدة البيانات المتجهة عن متجهات مشابهة
4. حقن أعلى K نتيجة في الطلب
5. توليد الاستجابة

المشكلة؟ التشابه المتجهي لا يساوي الصلة السياقية.

عندما يفشل RAG​

السيناريو 1: السياق الزمني

• المستخدم: "ماذا فعلت يوم الثلاثاء الماضي؟"
• قاعدة البيانات المتجهة: تعثر على مستندات عن "العمل" و"اجتماعات الثلاثاء"
• الواقع: يريد المستخدم جلسته المحددة من قبل 5 أيام

السيناريو 2: مطابقة الـ Patterns

• المستخدم: "أرني جميع عروض القوائم التي بنيتها"
• قاعدة البيانات المتجهة: تعثر على مستندات تحتوي على "قائمة" و"عرض"
• الواقع: يريد المستخدم patterns الـ entity-table المستخدمة عبر الجلسات

السيناريو 3: الاستدلال السببي

• المستخدم: "لماذا فشل تطبيق المصادقة الخاص بي؟"
• قاعدة البيانات المتجهة: تعثر على مستندات عن المصادقة
• الواقع: يحتاج المستخدم سلسلة الخطأ ثم الإصلاح ثم النجاح

البحث المتجهي يجد نصاً مشابهاً. لكنه لا يفهم ما تسأل عنه بالفعل.

بديل الذاكرة الـ Orbital​

بدلاً من التضمينات المتجهة، يستخدم ذكاء Almadar الاصطناعي ذاكرة orbital (وحدة مدارية مهيكلة):

// الذاكرة مهيكلة كـ orbital schemas
interface MemoryOrbital {
  userPreferences: {
    namingConvention: 'PascalCase' | 'camelCase';
    preferredPatterns: string[];
    commonEntities: string[];
    validationStyle: 'strict' | 'minimal';
  };

  generationSessions: {
    threadId: string;
    prompt: string;
    skill: string;
    patterns: string[];
    entities: string[];
    success: boolean;
    createdAt: Date;
  }[];

  projectContext: {
    appId: string;
    existingEntities: string[];
    conventions: string[];
    domain: string;
  };
}

هذه ذاكرة كـ بيانات مهيكلة مع علاقات، وليست أجزاء نصية مع متجهات.

لماذا تصنع الـ Orbitals ذاكرة أفضل​

1. الـ State Transitions الزمنية​

بدلاً من مجرد الطوابع الزمنية، نلتقط الرحلة:

{
  "sessionId": "sess_123",
  "prompt": "Create Order entity",
  "timeline": [
    { "state": "generated", "timestamp": "2025-03-01T10:00:00Z" },
    { "state": "validation_failed", "timestamp": "2025-03-01T10:02:00Z", "errors": ["Missing INIT"] },
    { "state": "fixed", "timestamp": "2025-03-01T10:05:00Z" },
    { "state": "compiled", "timestamp": "2025-03-01T10:06:00Z" }
  ]
}

الآن يمكن للذكاء الاصطناعي الإجابة على:

• "ما الأخطاء التي أصلحتها الأسبوع الماضي؟" -- البحث عن transitions من validation_failed إلى fixed
• "ما معدل نجاحي؟" -- عد مسارات generated إلى compiled
• "أي الـ patterns تسبب أخطاء؟" -- ربط الـ patterns بحالات الفشل

2. الاستعلام المهيكل​

البحث في الجلسات بحقول فعلية:

// البحث عن جميع الجلسات الناجحة التي تستخدم pattern الـ entity-table
const sessions = await memoryManager.getUserGenerationHistory(userId, {
  filter: {
    success: true,
    patterns: { $contains: 'entity-table' }
  }
});

// البحث عن سياق المشروع
const context = await memoryManager.getProjectContext(appId);
// يُرجع: { existingEntities: ['Order', 'User'], conventions: [...] }

لا تضمينات. لا عتبات تشابه. مجرد استعلامات دقيقة.

3. ذاكرة قابلة للتركيب​

الـ orbitals تتركب مثل الـ orbitals العادية:

{
  "name": "UserMemory",
  "orbitals": [
    { "name": "PreferenceMemory", "entity": "UserPreference" },
    { "name": "GenerationMemory", "entity": "GenerationSession" },
    { "name": "ProjectMemory", "entity": "ProjectContext" }
  ],
  "listens": [
    { "event": "SESSION_COMPLETED", "triggers": "UPDATE_MEMORY" }
  ]
}

تحديثات الذاكرة هي أحداث تُطلق state transitions — تماماً مثل تطبيقات Almadar العادية.

كيف يعمل​

تسجيل جلسة​

// داخلي: نظام ذاكرة Almadar يسجل جلسات التوليد
const memoryManager = createMemoryManager(db);

// بعد إكمال جلسة توليد
await memoryManager.recordGeneration(userId, {
  threadId: 'thread_123',
  prompt: 'Create Order entity with validation',
  skill: 'kflow-orbitals',
  patterns: ['entity-form', 'validation-rules'],
  entities: ['Order', 'OrderItem'],
  success: true,
});

// تحديث تفضيلات المستخدم بناءً على الـ patterns المستخدمة
await memoryManager.updateUserPreferences(userId, {
  preferredPatterns: ['entity-form', 'validation-rules'],
  commonEntities: ['Order', 'OrderItem'],
});

// تحديث سياق المشروع
await memoryManager.updateProjectContext(appId, {
  existingEntities: ['Order', 'OrderItem'],
  conventions: ['use-entity-table-for-lists'],
});

استخدام الذاكرة في التوليد​

// داخلي: عندما يبدأ الوكيل، يتم تحميل الذاكرة تلقائياً
const agent = createAgent({
  skill: 'kflow-orbitals',
  userId: 'user_123',
  appId: 'app_456',
});

// سياق الذاكرة يُحقن تلقائياً في طلب النظام

يتلقى الذكاء الاصطناعي:

## سياق المستخدم

### تفضيلات المستخدم
- التسمية المفضلة: PascalCase
- الـ patterns المفضلة: entity-form, validation-rules
- الـ entities شائعة الاستخدام: Order, OrderItem

### سياق المشروع
- المشروع: منصة تجارة إلكترونية
- الـ entities الموجودة: Order, OrderItem
- اصطلاحات المشروع: use-entity-table-for-lists

لا حاجة للاسترجاع — السياق المناسب موجود بالفعل.

تشبيه واقعي: السجلات الطبية مقابل محرك البحث​

نهج قاعدة البيانات المتجهة = بحث جوجل:

• البحث: "مشاكل القلب"
• النتيجة: ملايين النتائج عن القلوب
• المشكلة: عامة جداً، ليست عن قلبك أنت

نهج الذاكرة الـ orbital = سجلك الطبي:

• الاستعلام: رقم المريض 12345
• النتيجة: تاريخ كامل، أدوية، حساسيات، تشخيصات سابقة
• الميزة: مهيكل، دقيق، شخصي

عندما يعالجك طبيبك، لا يبحث في جوجل عن "أعراض القلب". إنه ينظر في سجلك المهيكل.

المقارنة: RAG مقابل الذاكرة الـ Orbital​

الـ Schema الخاص بذاكرة الـ Orbital​

هذا هو هيكل الذاكرة الفعلي:

{
  "name": "AgentMemory",
  "version": "1.0.0",
  "orbitals": [
    {
      "name": "UserPreferenceMemory",
      "entity": {
        "name": "UserPreference",
        "fields": [
          { "name": "userId", "type": "string", "required": true },
          { "name": "namingConvention", "type": "enum", "values": ["PascalCase", "camelCase", "snake_case"] },
          { "name": "preferredPatterns", "type": "array", "items": { "type": "string" } },
          { "name": "commonEntities", "type": "array", "items": { "type": "string" } },
          { "name": "confidence", "type": "number", "default": 0.5 }
        ]
      }
    },
    {
      "name": "GenerationHistoryMemory",
      "entity": {
        "name": "GenerationSession",
        "fields": [
          { "name": "threadId", "type": "string", "required": true },
          { "name": "prompt", "type": "string", "required": true },
          { "name": "skill", "type": "string", "required": true },
          { "name": "patterns", "type": "array", "items": { "type": "string" } },
          { "name": "entities", "type": "array", "items": { "type": "string" } },
          { "name": "success", "type": "boolean" },
          { "name": "createdAt", "type": "timestamp" }
        ]
      }
    }
  ]
}

الذاكرة هي orbital schema. تستخدم نفس الـ patterns كأي تطبيق آخر.

جرّبها: ابنِ وكيلاً واعياً بالذاكرة​

// داخلي: وكيل الذكاء الاصطناعي في Almadar يستخدم ذاكرة مهيكلة
// (هكذا يعمل من الداخل — ليس واجهة برمجية عامة)

const memoryManager = createMemoryManager(db);

// الوكيل يُنشأ مع إمكانية الوصول للذاكرة
const agent = createAgent({
  skill: 'kflow-orbitals',
  workDir: '/workspace',
  userId: 'user_123',
  appId: 'app_456',
});

// الوكيل الآن لديه وصول إلى:
// - الـ patterns المفضلة للمستخدم
// - الـ entities المُولَّدة سابقاً
// - اصطلاحات المشروع
// - النهج الناجحة/الفاشلة السابقة

const result = await agent.run({
  input: 'Create a Product entity',
});

// بعد الإكمال، تُزامَن بيانات الجلسة مع الذاكرة تلقائياً
// التسجيل: ما تم توليده، أي الـ patterns استُخدمت، النجاح/الفشل

الخلاصة​

تعتبر قواعد البيانات المتجهة رائعة لإيجاد نص مشابه. لكن وكلاء الذكاء الاصطناعي يحتاجون فهماً مهيكلاً:

• ما الـ patterns التي يفضلها هذا المستخدم؟
• ما الـ entities الموجودة في هذا المشروع؟
• ما الذي نجح من قبل وما الذي فشل؟
• كيف أصلحنا الأخطاء السابقة؟

الذاكرة الـ orbital توفر هذا الهيكل. ليست قاعدة بيانات — إنها تمثيل معرفي يتطابق مع طريقة تفكير Almadar حول التطبيقات.

لأن أفضل نظام ذاكرة ليس الذي يعثر على كلمات مشابهة. إنه الذي يفهم السياق.

التالي: البحث الوكيلي: تعليم الذكاء الاصطناعي التذكر كالإنسان.

هل سبق أن فتحت نافذة منبثقة ولم تستطع إغلاقها؟ هذه دائرة مكسورة. لقد جعلنا بناء مثل هذه الأشياء مستحيلاً.

مشكلة المستخدم العالق​

لنفترض أنك تستخدم تطبيقاً. تنقر على "فتح الإعدادات." تظهر نافذة منبثقة. تنقر على زر X. لا شيء يحدث. تضغط Escape. لا شيء. تنقر خارج النافذة. ولا يزال لا شيء يحدث.

أنت عالق.

يحدث هذا بسبب:

1. النافذة المنبثقة فُتحت عبر حالة داخلية (setIsOpen(true))
2. زر الإغلاق يُفعّل setIsOpen(false)
3. لكن إذا كان هناك خطأ برمجي، فإن الحالة لا تتحدث
4. أو الأسوأ من ذلك — زر الإغلاق لم يُوصَّل أصلاً

في Almadar، هذا مستحيل معمارياً.

مبدأ الـ Closed Circuit (الدائرة المغلقة)​

كل تفاعل مع الواجهة يجب أن يُكمل دائرة كاملة عائداً إلى الـ state machine (نظام يدير سلوك البرنامج عبر حالات محددة).

┌────────────────────────────────────────────────────────────────┐
│                                                                │
│   User Click ──► Event Bus ──► State Machine ──► UI Update     │
│       ▲                                              │         │
│       └──────────────────────────────────────────────┘         │
│                                                                │
└────────────────────────────────────────────────────────────────┘

لا توجد اختصارات. لا تغييرات مباشرة للحالة. كل إجراء يتدفق عبر الدائرة.

كيف يعمل في Almadar​

1. المستخدم يطلق حدثاً​

عندما تنقر على زر:

// ❌ NOT this:
onClick={() => setIsModalOpen(false)}

// ✅ This:
onClick={() => eventBus.emit('UI:CLOSE')}

لا يعرف المكوّن ما سيحدث بعد ذلك. إنه يرسل الحدث فقط.

2. الـ Event Bus يوجّه إلى الـ State Machine​

يستقبل الـ event bus (ناقل الأحداث) الحدث UI:CLOSE ويوجّهه إلى state machine الـ trait النشطة.

3. الـ State Machine تعالج​

{
  "from": "modalOpen",
  "to": "browsing",
  "event": "CLOSE",
  "effects": [
    ["render-ui", "modal", null],
    ["render-ui", "main", { "type": "page-header", ... }]
  ]
}

الـ state machine:

1. تنتقل من modalOpen إلى browsing
2. تُفرغ خانة النافذة المنبثقة
3. تُصيّر المحتوى الرئيسي

4. الواجهة تتحدث​

يعاد تصيير المكوّن بناءً على الحالة الجديدة. تختفي النافذة المنبثقة لأن الـ state machine حددت ذلك.

لماذا هذا يمنع حالات العلق​

1. الأحداث يجب أن تملك transitions​

إذا عرّفت زراً بحدث:

{
  "type": "page-header",
  "actions": [{ "label": "Open", "event": "OPEN_MODAL" }]
}

المُتحقق يتطلب transition (انتقال بين حالتين) مطابقاً:

{
  "from": "browsing",
  "to": "modalOpen",
  "event": "OPEN_MODAL"
  // ✅ Required transition exists
}

إذا نسيت:

✗ Error: CIRCUIT_ORPHAN_EVENT
  Action 'Open' emits event 'OPEN_MODAL' which has no transition handler

2. خانات التراكب يجب أن تملك مخارج​

إذا صيّرت إلى modal أو drawer، يتطلب المُتحقق مخرجاً:

{
  "from": "browsing",
  "to": "modalOpen",
  "event": "OPEN_MODAL",
  "effects": [
    ["render-ui", "modal", { "type": "form-section", ... }]
  ]
}

يجب أن يكون هناك:

{
  "from": "modalOpen",
  "to": "browsing",
  "event": "CLOSE"
  // ✅ Required exit transition
}

إذا نسيت:

✗ Error: CIRCUIT_NO_OVERLAY_EXIT
  State 'modalOpen' renders to 'modal' slot but has no exit transition.
  Users will be stuck in this overlay.

3. أغلفة الخانات تتعامل مع مخارج الطوارئ​

حتى لو نسيت زر إغلاق، فإن غلاف الخانة ينقذك:

// ModalSlot.tsx (auto-generated wrapper)
const handleClose = () => {
  eventBus.emit('UI:CLOSE');
  eventBus.emit('UI:CANCEL');
};

return (
  <Modal
    isOpen={Boolean(children)}
    onClose={handleClose}  // Escape key, overlay click, X button
  >
    {children}
  </Modal>
);

يرسل الغلاف الحدث. تتعامل الـ state machine معه. تكتمل الدائرة.

تشبيه واقعي: إشارات المرور​

إشارات المرور تتبع closed circuit:

Red ──(timer)──► Green ──(timer)──► Yellow ──(timer)──► Red

لا يوجد "قفز من الأحمر إلى الأخضر فوراً" أو "علق على الأصفر." الدائرة مغلقة — كل حالة لها transitions محددة.

الآن تخيل إشارة مرور معطلة:

• عالقة على الأحمر -- ازدحام مروري
• عالقة على الأخضر -- حوادث
• transitions عشوائية -- فوضى

يشبه متحقق Almadar مهندس مرور يتحقق من:

• كل ضوء له transitions
• لا حالات مستحيلة
• أوضاع الطوارئ معرّفة

مثال: نافذة منبثقة لا يمكن أن تتعطل​

إليك تطبيق نافذة منبثقة مستحيل أن تعلق فيها:

{
  "states": [
    { "name": "browsing", "isInitial": true },
    { "name": "modalOpen" }
  ],
  "events": [
    { "key": "OPEN_MODAL", "name": "Open Modal" },
    { "key": "CLOSE", "name": "Close" },
    { "key": "SAVE", "name": "Save" }
  ],
  "transitions": [
    {
      "from": "browsing",
      "to": "browsing",
      "event": "INIT",
      "effects": [
        ["render-ui", "main", {
          "type": "page-header",
          "title": "Tasks",
          "actions": [{ "label": "New Task", "event": "OPEN_MODAL" }]
        }]
      ]
    },
    {
      "from": "browsing",
      "to": "modalOpen",
      "event": "OPEN_MODAL",
      "effects": [
        ["render-ui", "modal", {
          "type": "form-section",
          "entity": "Task",
          "fields": ["title", "status"],
          "submitEvent": "SAVE",
          "cancelEvent": "CLOSE"
        }]
      ]
    },
    {
      "from": "modalOpen",
      "to": "browsing",
      "event": "CLOSE",
      "effects": [
        ["render-ui", "modal", null],
        ["emit", "INIT"]
      ]
    },
    {
      "from": "modalOpen",
      "to": "browsing",
      "event": "SAVE",
      "effects": [
        ["persist", "create", "Task", "@payload.data"],
        ["render-ui", "modal", null],
        ["emit", "INIT"]
      ]
    }
  ]
}

ثلاث طرق للخروج من النافذة المنبثقة:

1. انقر "إلغاء" -- يُطلق حدث CLOSE
2. انقر "حفظ" -- يُطلق حدث SAVE
3. اضغط Escape أو انقر على التراكب -- ModalSlot يُرسل UI:CLOSE

تنتقل الثلاثة عائدة إلى browsing وتُفرغ النافذة المنبثقة.

التسلسل الهرمي للخانات​

الخانات المختلفة لها متطلبات عودة مختلفة:

لماذا هذه الهندسة مهمة​

للمستخدمين​

• لن يعلقوا في النوافذ المنبثقة أبداً
• سلوك متسق عبر التطبيقات
• patterns واجهة متوقعة

للمطورين​

• الأخطاء تُلتقط وقت التصريف
• لا حاجة لتوصيل معالجات الإغلاق يدوياً
• تغييرات الحالة قابلة للتتبع

للفرق​

• الـ schema = التوثيق
• سهولة مراجعة تدفقات الحالة
• التأهيل أسرع

جرّبه: ابنِ نافذة منبثقة لا تتعطل​

أنشئ ملف modal-demo.orb:

{
  "name": "ModalDemo",
  "orbitals": [{
    "name": "Demo",
    "entity": { "name": "Item", "fields": [{ "name": "name", "type": "string" }] },
    "traits": [{
      "name": "DemoTrait",
      "linkedEntity": "Item",
      "stateMachine": {
        "states": [
          { "name": "main", "isInitial": true },
          { "name": "modalOpen" }
        ],
        "events": [
          { "key": "INIT", "name": "Initialize" },
          { "key": "OPEN", "name": "Open" },
          { "key": "CLOSE", "name": "Close" }
        ],
        "transitions": [
          {
            "from": "main",
            "to": "main",
            "event": "INIT",
            "effects": [
              ["render-ui", "main", {
                "type": "page-header",
                "title": "Demo",
                "actions": [{ "label": "Open Modal", "event": "OPEN" }]
              }]
            ]
          },
          {
            "from": "main",
            "to": "modalOpen",
            "event": "OPEN",
            "effects": [
              ["render-ui", "modal", { "type": "page-header", "title": "I'm a Modal!" }]
            ]
          },
          {
            "from": "modalOpen",
            "to": "main",
            "event": "CLOSE",
            "effects": [
              ["render-ui", "modal", null],
              ["emit", "INIT"]
            ]
          }
        ]
      }
    }],
    "pages": [{ "name": "DemoPage", "path": "/", "traits": [{ "ref": "DemoTrait" }] }]
  }]
}

صرّف وجرّب:

orbital validate modal-demo.orb  # Will fail without CLOSE transition
orbital compile modal-demo.orb --shell typescript

جرّب إزالة transition الـ CLOSE والتحقق مرة أخرى. الـ compiler لن يسمح لك بإنشاء دائرة مكسورة.

الخلاصة​

الـ closed circuit pattern ليس مجرد فكرة جيدة — إنه مفروض من الـ compiler (المُصرِّف).

في Almadar:

• كل إجراء في الواجهة يُرسل حدثاً
• كل حدث له transition
• كل تراكب له مخرج
• لا يعلق المستخدمون أبداً

لأن أفضل طريقة لمنع الأخطاء ليست الاختبار — بل جعل كتابتها مستحيلة.

تعرّف على المزيد حول الـ state machines في Almadar.

يُشغّل compiler Almadar أكثر من 50 قاعدة validation (تحقق من صحة البنية والمنطق) عبر 12 وحدة قبل توليد سطر واحد من الكود. يكتشف stuck overlays (طبقات عالقة لا يستطيع المستخدم إغلاقها)، وorphan events (أحداث يتيمة بلا معالج)، وunreachable states (حالات لا يمكن الوصول إليها)، والدوائر المكسورة — أخطاء عادةً ما تنجو حتى تصل إلى الإنتاج.

إليك ما يكتشفه وكيف.

لماذا الـ validation أفضل من الاختبار​

يخبرك الاختبار: "هذا السيناريو المحدد يعمل."

يخبرك الـ validation: "لا يوجد سيناريو يمكن أن يكسره."

تعتبر الاختبارات عيّنات. ويعتبر الـ validation برهانًا. لا يتحقق compiler Almadar مما إذا كان تطبيقك يعمل في الحالات التي اختبرتها. بل يتحقق مما إذا كان تطبيقك يمكن أن يُكسر أصلًا.

وحدات الـ validation الـ 12​

يُشغّل الـ compiler الـ validators (وحدات التحقق) بالتسلسل، حيث يركز كل منها على جانب مختلف:

Schema → Entity → Trait → Effect → RenderUI → Slot →
S-Expression → Binding → Service → CrossOrbital → Icon → ClosedCircuit

لنستعرض أكثرها إثارة للاهتمام.

1. validator الـ entity​

يكتشف مشاكل نموذج البيانات قبل أن تصبح أخطاء وقت التشغيل.

أسماء حقول مكررة:

Error: ORB_E_DUPLICATE_FIELD
  Entity 'Task' has duplicate field name 'status'.
  Each field name must be unique within an entity.

أهداف علاقة غير صالحة:

Error: ORB_E_INVALID_RELATION
  Field 'assigneeId' references entity 'User' but no entity
  named 'User' exists in this schema.
  Available entities: Task, Project, Comment

أسماء حقول محجوزة:

Error: ORB_E_RESERVED_FIELD
  Field name 'id' is reserved and automatically generated.
  Remove this field from your entity definition.

2. validator الـ trait​

يضمن أن الـ state machines (آلات الحالة التي تدير سلوك البرنامج عبر حالات محددة) مُشكَّلة بشكل صحيح.

لا توجد حالة ابتدائية:

Error: ORB_T_NO_INITIAL_STATE
  Trait 'TaskInteraction' has no initial state.
  Add 'isInitial: true' to exactly one state.

unreachable states:

Error: ORB_T_UNREACHABLE_STATE
  State 'Archived' in trait 'TaskInteraction' has no incoming
  transitions. It can never be reached.
  Either add a transition to this state or remove it.

هذا أمر دقيق. تُعرّف حالة لكن تنسى إنشاء transition (انتقال بين حالتين) إليها. تكون الحالة موجودة في الـ schema (المخطط الذي يصف بنية التطبيق) بدون الـ validator، لكنها لا يمكن أن تُدخل أبدًا — dead code في الـ state machine الخاصة بك.

transitions مكررة:

Error: ORB_T_DUPLICATE_TRANSITION
  Trait 'TaskInteraction' has two transitions from 'Browsing'
  on event 'EDIT'. State machines must be deterministic.

3. validator الـ closed circuit​

الجوهرة المتوجة. يضمن أن كل تفاعل مستخدم يُكمل دائرة كاملة.

stuck overlays:

Error: CIRCUIT_NO_OVERLAY_EXIT
  State 'EditModal' renders to 'modal' slot but has no exit
  transition. Users will be stuck in this overlay.

  Fix: Add a transition from 'EditModal' with event 'CANCEL' or 'CLOSE'
  that includes the effect: ["render-ui", "modal", null]

هذا هو خطأ "النافذة المنبثقة التي لا تُغلق". تكتشفه عندما يبلغ عنه مستخدم في التطبيقات التقليدية. تكتشفه قبل أن يوجد الكود في Almadar.

orphan events:

Error: CIRCUIT_ORPHAN_EVENT
  Action 'Delete' in state 'Viewing' emits event 'DELETE'
  which has no transition handler in the current state.

  The button will render but clicking it will do nothing.

عرّفت زرًا بحدث، لكن لا transition يعالج ذلك الحدث في الحالة الحالية. سيُعرض الزر، وسينقر المستخدم عليه، ولن يحدث شيء. يكتشف الـ validator هذا في وقت الـ compilation.

فقدان الفتحة الرئيسية:

Error: CIRCUIT_NO_MAIN_RENDER
  State 'Browsing' has no render-ui effect targeting the 'main' slot.
  The page will be blank when entering this state.

عرّفت حالة لكن نسيت عرض أي شيء في فتحة واجهة المستخدم الرئيسية. سيرى المستخدمون صفحة فارغة.

4. validator الـ S-expressions​

يتحقق من أن الـ S-expressions (التعبيرات الرمزية المستخدمة في الـ guards والـ effects) مُشكَّلة بشكل صحيح.

عوامل غير معروفة:

Error: ORB_S_UNKNOWN_OPERATOR
  Unknown operator 'equals' in guard expression.
  Did you mean '='?
  Available comparison operators: =, !=, >, >=, <, <=

عدد وسائط خاطئ:

Error: ORB_S_WRONG_ARITY
  Operator 'and' expects 2+ arguments, got 1.
  Expression: ["and", ["=", "@entity.status", "active"]]

  'and' with a single argument is always equal to that argument.
  Did you mean to add another condition?

عدم تطابق الأنواع:

Error: ORB_S_TYPE_MISMATCH
  Operator '>' expects numeric arguments.
  Got: "@entity.name" (string) > 10 (number)

  You're comparing a string to a number. This will always
  evaluate to false.

5. validator الـ binding​

يضمن أن جميع مراجع البيانات تشير إلى حقول حقيقية.

جذر binding (ربط بيانات الـ schema بواجهة المستخدم) غير معروف:

Error: ORB_B_UNKNOWN_ROOT
  Unknown binding root '@result' in expression.
  Valid roots: @entity, @payload, @state, @now, @config, @user

حقل entity (الكيان الذي يمثّل نموذج البيانات) غير معروف:

Error: ORB_B_UNKNOWN_FIELD
  Binding '@entity.staus' references field 'staus' which doesn't
  exist on entity 'Task'.
  Did you mean 'status'?
  Available fields: title, description, status, priority

كشف الأخطاء الإملائية مع اقتراحات. @entity.staus → "هل تقصد status؟"

6. validator عبر الـ orbitals​

يضمن اكتمال اتصال الأحداث بين الـ orbitals (الوحدات المدارية التي يتألف منها التطبيق).

إطلاق بدون مستمع:

Error: ORB_X_ORPHAN_EMIT
  Trait 'OrderTrait' emits 'ORDER_COMPLETED' but no trait
  has a matching 'listens' declaration.

  Every emitted event must have at least one listener.
  Either add a listener or remove the emission.

يمنع هذا أحداث "أطلق وانسَ" — إطلاقات لا تذهب إلى أي مكان. سيكون هذا رسالة تُنشر في طابور بدون مستهلك في بنية الـ microservices (خدمات مصغرة مستقلة). يكتشفه الـ compiler في Almadar.

البنية two-pass​

تتطلب بعض عمليات الـ validation مراجع أمامية (forward references) لعناصر مُعرَّفة لاحقًا. يشير الـ entity أ إلى الـ entity ب، لكن ب مُعرَّف بعد أ. سيرفض validator بمسار واحد هذا.

يستخدم compiler Almadar نهج الـ two-pass:

المسار 1: الجمع

• جمع جميع أسماء الـ entities وأسماء الـ traits وأسماء الحالات وأسماء الأحداث
• بناء جدول رموز لكل ما هو موجود

المسار 2: الـ validation

• فحص جميع المراجع مقابل جدول الرموز
• تشغيل جميع وحدات الـ validation الـ 12
• الإبلاغ عن الأخطاء مع السياق والاقتراحات

يعني هذا أنه يمكنك تعريف الـ orbitals بأي ترتيب. يكتشف الـ compiler رسم التبعيات.

جودة الأخطاء: الفرق بين "خطأ" و"مساعدة"​

قارن خطأ compiler نموذجي:

Error: unexpected token at line 47, column 12

مع خطأ validation في Almadar:

Error: CIRCUIT_NO_OVERLAY_EXIT

  State 'EditModal' renders to 'modal' slot but has no exit transition.
  Users will be stuck in this overlay.

  Location: orbitals[0].traits[0].stateMachine.states[2]
  Schema: task-app.orb

  Fix: Add a transition from 'EditModal' with event 'CANCEL' or 'CLOSE'
  that includes the effect: ["render-ui", "modal", null]

  Example:
    {
      "from": "EditModal",
      "to": "Browsing",
      "event": "CANCEL",
      "effects": [["render-ui", "modal", null]]
    }

يتضمن كل خطأ:

• رمز الخطأ — قابل للبحث والتوثيق
• وصف مقروء — ما هو الخطأ
• الأثر — لماذا يهم (المستخدمون سيعلقون)
• الموقع — بالضبط أين في الـ schema
• الإصلاح — كيفية حله
• مثال — حل جاهز للنسخ واللصق

مبني بـ Rust: لماذا يهم ذلك​

الـ compiler مكتوب بـ Rust. يمنحنا هذا:

مطابقة patterns شاملة: يجبرنا compiler الـ Rust على معالجته في كل validator عندما نضيف نوع effect (تأثير يُنفَّذ عند الـ transition) جديد. لا يمكننا نسيان حالة — لن يُصرَّف.

أمان الذاكرة بدون جامع القمامة: يستعير الـ validator الـ schema بدون نسخه. يوفر هذا ذاكرة ووقتًا كبيرين لـ schema من 5,000 سطر.

سرعة الـ compilation: يستغرق الـ validation الكامل لـ schema كبير أقل من 50 مللي ثانية. تحصل على التغذية الراجعة أسرع مما يمكن لمحررك أن يتحدث.

التزامن الآمن: يمكن لوحدات الـ validation أن تعمل بالتوازي بدون تنافس على البيانات. يضمن نظام أنواع Rust هذا في وقت الـ compilation.

ما لا نتحقق منه (بعد)​

لا يعتبر الـ validator كلّي المعرفة. لا يتحقق حاليًا من:

• الصحة الدلالية للـ guards (شروط تمنع أو تسمح بالـ transition) — يعرف أن [">=", "@entity.amount", 0] صالح بنيويًا، لكنه لا يعرف ما إذا كان منطق الأعمال صحيحًا
• الآثار المترتبة على الأداء — state machine بـ 1,000 حالة صالحة لكنها قد تكون بطيئة
• جماليات الواجهة — جدولان يُعرضان في نفس الفتحة أمر صالح لكنه ربما قبيح

تعد هذه مجالات للتحسين المستقبلي. لكن تكتشف القواعد الخمسين+ التي لدينا اليوم الغالبية العظمى من الأخطاء التي تنجو حتى الإنتاج في التطبيقات التقليدية.

الخلاصة​

أفضل خطأ هو الذي لا يوجد أبدًا.

لا يتحقق compiler Almadar من البنية النحوية فقط. بل يتحقق من السببية (closed circuit — دائرة مغلقة تضمن اكتمال كل تفاعل)، والاكتمال (لا orphan events)، وقابلية الوصول (لا حالات ميتة)، والصحة (S-expressions آمنة الأنواع)، والاتساق (مطابقة الأحداث عبر الـ orbitals).

أكثر من 50 قاعدة. 12 وحدة. أقل من 50 مللي ثانية.

هذا ليس compiler. إنه مراجع كود لا ينام أبدًا، ولا يفوّت حالة أبدًا، ولا يوافق على كود معطوب أبدًا.

استكشف وثائق الـ compiler لمعرفة المزيد.

هذه ليست مجرد آلية لعب. إنها pattern (نمط معماري) في هندسة البرمجيات يحل الجدل بين الـ microservices (خدمات مصغرة مستقلة) والـ monolith (تطبيق متجانس في قاعدة كود واحدة).

مشكلة التركيب​

تعلق هندسة البرمجيات بين خيارين سيئين:

الـ monolith: كل شيء في قاعدة كود واحدة. سهل البناء، مستحيل التوسعة. يخاطر كل تغيير بكسر شيء غير متعلق.

الـ microservices: كل شيء في خدمته الخاصة. سهل التوسعة، مستحيل التنسيق. تتطلب كل ميزة تنظيم 5 خدمات و3 طوابير رسائل ودعاء.

يعامل كلا النهجين السلوك كمشكلة موقع: أين يعيش الكود؟

السؤال الحقيقي هو: كيف يتركب السلوك؟

دروس من تصميم الألعاب​

تُحدَّد شخصية اللاعب في إرم، لعبة أكشن RPG للزنزانات مبنية على Almadar، من خلال أي الـ orbitals (الوحدات المدارية التي تُركّب السلوك) يُجهّزها:

كل orbital هو state machine (آلة حالة تدير السلوك عبر حالات محددة) مكتفية ذاتيًا. لا يعرف الدفاع عن الترميم. ولا يعرف الاستكشاف عن التصنيع.

لكن عندما تُجهّزها معًا، يظهر emergent behavior (سلوك ناشئ من تركيب الأجزاء).

الـ resonance: التركيب يخلق الظهور​

تخلق الـ orbitals المتوافقة resonance (رنين — تأثيرات تآزرية بين الـ orbitals) عندما تُجهَّز في وقت واحد — effects لا يُعرّفها أي orbital بمفرده:

{
  "resonance": [
    {
      "requires": ["Defend", "Mend"],
      "effect": "Shield regeneration rate increased by 1.5x",
      "multiplier": { "shieldRegen": 1.5 }
    },
    {
      "requires": ["Disrupt", "Fabricate"],
      "effect": "Traps apply disruption debuffs",
      "multiplier": { "trapDamage": 1.3 }
    },
    {
      "requires": ["Archive", "Command"],
      "effect": "Allies receive enemy weakness intel",
      "multiplier": { "allyDamage": 1.2 }
    }
  ]
}

الرؤية الجوهرية: لا يتغير أي orbital. لا يملك الدفاع كودًا لـ "اعمل بشكل أفضل مع الترميم." يعتبر الـ resonance خاصية التركيبة، وليس الأفراد.

هذا بالضبط كيف يجب أن يعمل تركيب البرمجيات.

الـ pattern: تركيب الـ orbital​

تتواصل الـ orbitals في Almadar عبر الأحداث. يُصرّح كل orbital بما يُطلقه وما يستمع إليه:

{
  "name": "DefendOrbital",
  "traits": [{
    "name": "ShieldTrait",
    "emits": ["SHIELD_ACTIVATED", "SHIELD_DEPLETED"],
    "stateMachine": {
      "states": [
        { "name": "Ready", "isInitial": true },
        { "name": "Active" },
        { "name": "Cooldown" }
      ],
      "transitions": [
        {
          "from": "Ready",
          "to": "Active",
          "event": "ACTIVATE_SHIELD",
          "effects": [
            ["set", "@entity.shieldHp", "@entity.maxShieldHp"],
            ["emit", "SHIELD_ACTIVATED"]
          ]
        },
        {
          "from": "Active",
          "to": "Cooldown",
          "event": "SHIELD_BROKEN",
          "effects": [
            ["set", "@entity.shieldHp", 0],
            ["emit", "SHIELD_DEPLETED"]
          ]
        }
      ]
    }
  }]
}

{
  "name": "MendOrbital",
  "traits": [{
    "name": "HealTrait",
    "listens": [
      { "event": "SHIELD_DEPLETED", "triggers": "EMERGENCY_HEAL" }
    ],
    "stateMachine": {
      "transitions": [
        {
          "from": "Idle",
          "to": "Healing",
          "event": "EMERGENCY_HEAL",
          "effects": [
            ["set", "@entity.hp", ["+", "@entity.hp", ["*", "@entity.maxHp", 0.2]]]
          ]
        }
      ]
    }
  }]
}

يُطلق الدفاع SHIELD_DEPLETED. ويستمع الترميم إليه. يبدأ الشفاء تلقائيًا عندما يُكسر الدرع. لا يشير أي orbital إلى الآخر بالاسم. يتواصلان عبر الـ event bus (ناقل الأحداث الذي يربط الـ orbitals ببعضها).

يعني هذا:

• ترابط فضفاض — الدفاع يعمل بدون الترميم
• قابلية التركيب — أضف الترميم ويظهر سلوك جديد
• قابلية الـ validation (التحقق من صحة التوصيل) — الـ compiler (المُصرِّف) يتحقق أن كل emit له listen
• قابلية الاكتشاف — اقرأ تصريحات الأحداث لفهم التفاعلات

الآثار على هندسة البرمجيات​

يترجم هذا الـ pattern مباشرة إلى برمجيات الأعمال:

التجارة الإلكترونية: معالجة الطلبات​

OrderOrbital         PaymentOrbital         InventoryOrbital
    │                     │                      │
    ├─ emits:             ├─ listens:            ├─ listens:
    │  ORDER_PLACED       │  ORDER_PLACED        │  PAYMENT_CONFIRMED
    │                     │  → PROCESS_PAYMENT   │  → RESERVE_STOCK
    │                     │                      │
    │                     ├─ emits:              ├─ emits:
    │                     │  PAYMENT_CONFIRMED   │  STOCK_RESERVED
    │                     │  PAYMENT_FAILED      │  OUT_OF_STOCK

ثلاثة orbitals. كل منها مكتفٍ ذاتيًا. التركيب عبر الأحداث. يتحقق الـ compiler من اكتمال رسم الأحداث — لا تمر رسالة بدون معالجة.

قارن هذا بنسخة الـ microservices:

• ثلاث خدمات، ثلاث عمليات نشر، ثلاث قواعد بيانات
• طابور رسائل (Kafka/RabbitMQ) لربطها
• طوابير الرسائل الميتة للرسائل الفاشلة
• patterns الملحمة للمعاملات الموزعة
• مراقبة وتنبيهات لكل خدمة

تُصرَّف نسخة Almadar إلى نشر واحد بنفس البنية المدفوعة بالأحداث، لكن بدون أعباء البنية التحتية.

التعاون الجماعي: التطوير المتوازي​

يمكن للفرق العمل بالتوازي لأن الـ orbitals تتواصل فقط عبر الأحداث:

• يبني الفريق أ orbital الطلب
• يبني الفريق ب orbital الدفع
• يبني الفريق ج orbital المخزون

يتفقون على عقود الأحداث:

{
  "event": "ORDER_PLACED",
  "payload": {
    "orderId": "string",
    "items": "array",
    "total": "number"
  }
}

ثم يبنون بشكل مستقل. يتحقق الـ compiler من تطابق العقود عندما تُركَّب الـ orbitals.

الـ standard library: سلوكيات جاهزة​

يتضمن Almadar 11 سلوكًا في الـ standard library (المكتبة القياسية التي توفر سلوكيات جاهزة) تُدمج في أي مشروع:

استوردها في أي orbital:

{
  "uses": [{ "from": "std/Pagination", "as": "Paginate" }],
  "traits": [
    { "ref": "Paginate.traits.PaginationTrait" },
    { "ref": "TaskInteraction" }
  ]
}

تملك قائمة المهام الخاصة بك الآن ترقيم صفحات. بدون كتابة كود. مجرد تركيب.

لماذا تفهم الألعاب هذا بشكل صحيح​

فهمت الألعاب التركيب منذ الأزل. شخصية RPG هي تركيب من:

• الفئة (محارب، ساحر، متسلل)
• المعدات (سيف، درع، عصا)
• المهارات (كرة نار، شفاء، تسلل)
• التقويات/الإضعافات (مسموم، مبارك، مُسرَّع)

يعتبر كل منها سلوكًا مكتفيًا ذاتيًا. ويخلقون معًا شخصية فريدة ذات قدرات ناشئة.

يجب أن تعمل البرمجيات التجارية بنفس الطريقة:

• تعتبر الفاتورة تركيبًا من عمليات CRUD + الموافقة + توليد PDF + إشعار بالبريد الإلكتروني
• يعتبر المستخدم تركيبًا من المصادقة + الملف الشخصي + التفضيلات + سجل النشاط
• تعتبر لوحة المعلومات تركيبًا من المخططات + الفلاتر + التحديثات الفورية + التصدير

كل سلوك هو orbital. التركيب عبر الأحداث. يضمن الـ compiler صحة التوصيل.

الخلاصة​

يسأل الجدل بين الـ microservices والـ monolith السؤال الخاطئ. لا يكمن السؤال في أين يعيش السلوك. بل كيف يتركب السلوك.

تمنحك الـ orbitals:

• وحدات مكتفية ذاتيًا (كالـ microservices) — كل orbital يملك الـ state machine الخاصة به
• تركيب سهل (كالـ monolith) — استورد، ركِّب، صرِّف
• توصيل مُتحقق منه (لا يوفره أي منهما) — الـ compiler يتحقق من كل اتصال حدث
• emergent behavior (كالألعاب) — effects من الـ resonance بين التركيبات المتوافقة

لا تبدأ بـ "كم عدد الخدمات؟" في المرة القادمة التي تصمم فيها نظامًا. بل ابدأ بـ "ما السلوكيات التي أحتاجها، وكيف تتركب؟"

تعرف على المزيد حول الأحداث عبر الـ orbitals والـ standard library.

فخ الأعلام المنطقية​

إليك pattern (نمط تصميم متكرر) مألوفاً:

function UserProfile() {
  const [isLoading, setIsLoading] = useState(false);
  const [isError, setIsError] = useState(false);
  const [isEditing, setIsEditing] = useState(false);
  const [isSaving, setIsSaving] = useState(false);
  const [errorMessage, setErrorMessage] = useState('');

  const handleSave = async () => {
    setIsSaving(true);
    setIsError(false);
    try {
      await saveUser(user);
      setIsEditing(false);
    } catch (e) {
      setIsError(true);
      setErrorMessage(e.message);
    } finally {
      setIsSaving(false);
    }
  };

  // What combinations are valid?
  // isLoading=true, isError=true?
  // isEditing=true, isSaving=true?
  // Who knows!
}

هذا يخلق 2^n حالة ممكنة (32 تركيبة لـ 5 أعلام منطقية). معظمها غير صالح أو بلا معنى.

بديل الـ State Machine​

ماذا لو عرّفت الحالات الصالحة بشكل صريح؟

{
  "states": [
    { "name": "idle", "isInitial": true },
    { "name": "loading" },
    { "name": "editing" },
    { "name": "saving" },
    { "name": "error" }
  ],
  "events": ["FETCH", "EDIT", "SAVE", "SUCCESS", "ERROR", "CANCEL"],
  "transitions": [
    { "from": "idle", "to": "loading", "event": "FETCH" },
    { "from": "loading", "to": "idle", "event": "SUCCESS" },
    { "from": "loading", "to": "error", "event": "ERROR" },
    { "from": "idle", "to": "editing", "event": "EDIT" },
    { "from": "editing", "to": "saving", "event": "SAVE" },
    { "from": "saving", "to": "idle", "event": "SUCCESS" },
    { "from": "saving", "to": "error", "event": "ERROR" },
    { "from": "editing", "to": "idle", "event": "CANCEL" },
    { "from": "error", "to": "idle", "event": "CANCEL" }
  ]
}

الآن، هناك تحديداً 5 حالات و 9 transitions صالحة. لا تركيبات مستحيلة.

تصوّر الفرق​

الأعلام المنطقية: حالة متشابكة​

         isLoading=true
        /             \
isError=true?      isEditing=true?
      /                 \
     ?                   ?

أي تركيبة ممكنة الحدوث. الأخطاء تنشأ من حالات غير صالحة لم تفكر فيها.

الـ State Machine: رسم بياني موجّه​

                    ┌─────────┐
         ┌─────────►│  idle   │◄────────┐
         │          └────┬────┘         │
         │               │              │
    ERROR│          FETCH│         SUCCESS
         │               ▼              │
    ┌────┴───┐      ┌─────────┐        │
    │ error  │      │ loading │        │
    └───┬────┘      └────┬────┘        │
        ▲                │             │
        │           SUCCESS            │
        │                │             │
        │                ▼             │
        │           ┌─────────┐        │
        └───────────┤ editing ├────────┘
                    └────┬────┘
                         │ SAVE
                         ▼
                    ┌─────────┐
         ┌─────────│ saving  │─────────┐
         │         └─────────┘         │
    ERROR│                              │SUCCESS
         │                              │
         └──────────────────────────────┘

كل مسار صريح. الـ transitions غير الصالحة غير موجودة.

مثال واقعي: إرسال نموذج​

طريقة الأعلام المنطقية​

function ContactForm() {
  const [formData, setFormData] = useState({});
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [isSuccess, setIsSuccess] = useState(false);
  const [isError, setIsError] = useState(false);
  const [errorMessage, setErrorMessage] = useState('');

  const submit = async () => {
    setIsSubmitting(true);
    setIsError(false);
    setIsSuccess(false);

    try {
      await api.submit(formData);
      setIsSuccess(true);
    } catch (e) {
      setIsError(true);
      setErrorMessage(e.message);
    } finally {
      setIsSubmitting(false);
    }
  };

  // Bug: What if isSuccess and isError are both true?
  // Bug: Can I submit again while isSubmitting?
  // Bug: What clears isSuccess?
}

طريقة الـ State Machine​

{
  "states": [
    { "name": "editing", "isInitial": true },
    { "name": "validating" },
    { "name": "submitting" },
    { "name": "success", "isTerminal": true },
    { "name": "error" }
  ],
  "events": ["SUBMIT", "VALIDATED", "SUCCESS", "FAILURE", "RETRY", "EDIT"],
  "transitions": [
    {
      "from": "editing",
      "to": "validating",
      "event": "SUBMIT",
      "effects": [["validate", "@entity"]]
    },
    {
      "from": "validating",
      "to": "submitting",
      "event": "VALIDATED",
      "guard": ["=", "@validation.valid", true],
      "effects": [["call-service", "submitForm", "@entity"]]
    },
    {
      "from": "validating",
      "to": "editing",
      "event": "VALIDATED",
      "guard": ["=", "@validation.valid", false],
      "effects": [["set", "@state.errors", "@validation.errors"]]
    },
    {
      "from": "submitting",
      "to": "success",
      "event": "SUCCESS",
      "effects": [["render-ui", "main", { "type": "success-state" }]]
    },
    {
      "from": "submitting",
      "to": "error",
      "event": "FAILURE",
      "effects": [["set", "@state.error", "@payload.message"]]
    },
    {
      "from": "error",
      "to": "editing",
      "event": "RETRY"
    }
  ]
}

الفوائد:

• لا يمكن الإرسال أثناء الإرسال
• التحقق يحدث في حالته الخاصة
• الخطأ والنجاح متبادلا الاستبعاد
• مسارات واضحة لإعادة المحاولة

لماذا يتجنب المطورون الـ State Machines​

الخرافة 1: "معقدة جداً"​

الواقع: الأعلام المنطقية تبدو أبسط حتى يصبح لديك 5 منها أو أكثر. عندها تصبح مصفوفة التفاعلات غير مفهومة.

الخرافة 2: "للألعاب فقط"​

الواقع: مطورو الألعاب يستخدمون finite state machines (آلات حالة محدودة) لأنها تعمل. الواجهات تشبه الألعاب تماماً: إجراءات المستخدم تُفعّل تغييرات في الحالة.

الخرافة 3: "صعبة التغيير"​

الواقع: تغيير state machine يعني إضافة حالة أو transition. تغيير الأعلام المنطقية يعني البحث عبر سلاسل useEffect.

متى تستخدم State Machines​

Almadar يجعلها سهلة​

في Almadar، لا تُنفّذ الـ state machine — بل تصرح عنها:

{
  "traits": [{
    "name": "TaskManager",
    "linkedEntity": "Task",
    "stateMachine": {
      "states": [
        { "name": "browsing", "isInitial": true },
        { "name": "creating" },
        { "name": "editing" },
        { "name": "deleting" }
      ],
      "events": ["INIT", "CREATE", "EDIT", "DELETE", "SAVE", "CANCEL"],
      "transitions": [
        {
          "from": "browsing",
          "to": "browsing",
          "event": "INIT",
          "effects": [
            ["render-ui", "main", { "type": "entity-table", "entity": "Task" }]
          ]
        },
        {
          "from": "browsing",
          "to": "creating",
          "event": "CREATE",
          "effects": [
            ["render-ui", "modal", { "type": "form-section", ... }]
          ]
        },
        {
          "from": "creating",
          "to": "browsing",
          "event": "SAVE",
          "effects": [
            ["persist", "create", "Task", "@payload.data"],
            ["render-ui", "modal", null],
            ["emit", "INIT"]
          ]
        },
        {
          "from": "creating",
          "to": "browsing",
          "event": "CANCEL",
          "effects": [["render-ui", "modal", null]]
        }
      ]
    }
  }]
}

الـ compiler يولد:

• محرك الـ state machine
• أنواع TypeScript
• معالجات الأحداث
• binding الواجهة

أنت تعرّف فقط المنطق.

تشبيه واقعي: إشارات المرور (مرة أخرى)​

إشارات المرور هي الـ state machine النموذجية:

Red → Green → Yellow → Red

تخيل لو استخدمت إشارات المرور أعلاماً منطقية:

const [isRed, setIsRed] = useState(true);
const [isGreen, setIsGreen] = useState(false);
const [isYellow, setIsYellow] = useState(false);

// Bug: All could be true!
// Bug: All could be false!
// Bug: Green could turn directly to Red!

يستخدم مهندسو المرور state machines لأن الأرواح تعتمد على حالات متوقعة.

سلامة عقل مستخدميك تعتمد عليها أيضاً.

جرّبه: حوّل فوضى الأعلام المنطقية​

خذ هذا المكوّن المثقل بالأعلام المنطقية:

function Checkout() {
  const [isCartOpen, setIsCartOpen] = useState(false);
  const [isCheckingOut, setIsCheckingOut] = useState(false);
  const [isProcessing, setIsProcessing] = useState(false);
  const [isComplete, setIsComplete] = useState(false);
  const [hasError, setHasError] = useState(false);
  // ... nightmare of useEffect
}

وجرب تحويله إلى schema في Almadar:

{
  "states": [
    { "name": "browsing", "isInitial": true },
    { "name": "cartOpen" },
    { "name": "checkoutForm" },
    { "name": "processing" },
    { "name": "complete", "isTerminal": true },
    { "name": "error" }
  ],
  "events": ["VIEW_CART", "CHECKOUT", "SUBMIT", "SUCCESS", "FAILURE", "CLOSE", "RETRY"]
  // ... transitions
}

نسخة الـ state machine تحتوي على 6 حالات صريحة بدلاً من 32 تركيبة ممكنة من الأعلام المنطقية.

الخلاصة​

الـ finite state machines ليست تمارين أكاديمية — إنها أدوات عملية لإدارة التعقيد.

• 2-3 أعلام منطقية: ربما لا بأس بها
• 4 أعلام منطقية أو أكثر: فكّر في state machine
• تدفقات غير متزامنة: بالتأكيد استخدم state machine
• واجهات متعددة الخطوات: state machine أو لا شيء

Almadar يجعل الـ state machines الخيار الافتراضي، لا الاستثناء. لأن مستخدميك يستحقون برمجيات متوقعة.

هل أنت مستعد للتجربة؟ ابنِ state machine الأولى لك.

فوضى التفويض​

تتعامل معظم التطبيقات مع الصلاحيات بهذه الطريقة:

// في المكوّن
function ApproveButton({ order }) {
  const { user } = useAuth();

  const canApprove =
    user.roleLevel >= 5 &&
    !order.isFlagged &&
    order.amount > 0;

  return (
    <button disabled={!canApprove} onClick={handleApprove}>
      Approve
    </button>
  );
}

// في مسار الـ API
app.post('/api/orders/:id/approve', async (req, res) => {
  const { user } = req;
  const order = await Order.findById(req.params.id);

  // نفس المنطق، مكرر!
  if (user.roleLevel < 5) {
    return res.status(403).json({ error: 'Insufficient permissions' });
  }
  if (order.isFlagged) {
    return res.status(400).json({ error: 'Order is flagged' });
  }
  if (order.amount <= 0) {
    return res.status(400).json({ error: 'Invalid amount' });
  }

  // ... منطق الموافقة الفعلي
});