{
  "openapi": "3.1.0",
  "info": {
    "title": "واجهة مكتبة البرمجية",
    "version": "0.1.0",
    "summary": "مكتبة فيديو مستضافة ذاتيًا مع تفريغ نصي تلقائي وبحث دلالي وبث تكيّفي.",
    "description": "واجهة مكتبة البرمجية هي طبقة التحكم في مكتبة فيديو مستضافة ذاتيًا. تتيح\nالمكتبات والفيديوهات والنصوص المفرّغة والبحث ومهام المعالجة وجلسات البث\nوحالة المستخدم عبر واجهة JSON موحّدة.\n\n## الأعراف\n\n- **النقل.** HTTP/1.1 وHTTP/2 فوق TLS. تستخدم أجسام الطلبات والاستجابات بصيغة JSON\n  الترويسة `Content-Type: application/json; charset=utf-8`. تستخدم استجابات الأخطاء\n  الصيغة `application/problem+json` وفق [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457).\n- **المعرّفات.** معرّفات الموارد من نوع UUIDv4 ما لم يُذكر غير ذلك.\n  `Job.id` و`AudioTrack.id` أعداد صحيحة بطول 64 بت.\n- **الأوقات.** كل الطوابع الزمنية بصيغة RFC 3339 / ISO 8601 بتوقيت UTC (باللاحقة `Z`).\n  المُدد والإزاحات بالثواني كأعداد عشرية.\n- **الترقيم.** قائم على المؤشر. مرّر `limit` (الافتراضي 50، والحد الأقصى 200) والمؤشر\n  المعتم `cursor` المُعاد من الصفحة السابقة. غلاف الصفحة هو\n  `{ items: [...], next: \"<cursor>\" | null }`. ترمّز المؤشرات\n  `(updated_at DESC, id DESC)` وتتبدّل عند تغيّر إصدار المخطط.\n- **التكرار الآمن.** كل نقاط الوصول `POST /api/jobs/{id}/{action}` آمنة التكرار.\n  يمكن للعملاء ضبط `Idempotency-Key: <uuid>` في طلبات `POST` و`PATCH`، ويعيد\n  الخادم الاستجابة الأصلية طوال 24 ساعة.\n- **ربط الطلبات.** تحمل كل استجابة `X-Request-Id` (من نوع UUIDv7).\n  يمكن للعملاء تمرير `X-Request-Id` خاص بهم ليُنقل عبر السلسلة.\n- **حدود المعدّل.** الافتراضي: 600 طلب / دقيقة / مستخدم موثَّق، و6 000 /\n  دقيقة / عنوان IP. تتلقى الطلبات المتجاوزة `429 Too Many Requests` مع `Retry-After`\n  والترويسات `X-RateLimit-Limit` و`X-RateLimit-Remaining` و`X-RateLimit-Reset`.\n\n## المصادقة\n\nمساران متكافئان يستندان إلى الهوية نفسها:\n\n- **الويب** يستخدم ملفات تعريف ارتباط `httpOnly` يضبطها `POST /api/auth/login`. ويجب أن\n  تتضمن الطلبات المغيّرة للحالة أيضًا الترويسة `X-CSRF-Token` (قيمتها منسوخة من\n  ملف تعريف الارتباط `csrf_token`).\n- **الجوال / سطح المكتب / التلفاز** يستخدم JWT من نوع حامل (RS256، صالح 15 دقيقة) مع رمز (token)\n  تحديث معتم طويل الأمد. المفاتيح العامة متاحة في `/api/.well-known/jwks.json`.\n\nيمكن لعمليات التثبيت أحادية المستخدم تمرير رمز مشرف ثابت عبر `Authorization: Bearer`.\n\n## البث\n\nتُصدر نقاط الوصول `/api/sessions` عناوين URL موقّعة قصيرة العمر يرسلها العميل\nمباشرة إلى خدمة البث (على أصل منفصل). لا تمر البايتات أبدًا\nعبر الواجهة البرمجية.\n\n## WebSocket\n\nيُرقّي `GET /api/ws` الاتصال إلى تدفق أحداث متعدد القنوات. الرسائل أغلفة JSON\nبالشكل `{ type, data, at }`. يشترك العملاء بإرسال\n`{ type: \"subscribe\", channels: [\"jobs\", \"playback\", \"library\"] }` عند الاتصال.\n",
    "contact": {
      "name": "Maktaba",
      "url": "https://github.com/maktaba/maktaba"
    },
    "license": {
      "name": "AGPL-3.0",
      "identifier": "AGPL-3.0"
    }
  },
  "servers": [
    {
      "url": "https://{host}/api",
      "description": "الإنتاج",
      "variables": {
        "host": {
          "default": "maktaba.local",
          "description": "المضيف الذي يمكن الوصول فيه إلى خدمة الواجهة البرمجية."
        }
      }
    },
    {
      "url": "http://localhost:8080/api",
      "description": "التطوير المحلي"
    }
  ],
  "externalDocs": {
    "description": "مواصفة البنية",
    "url": "https://github.com/maktaba/maktaba/blob/main/specs/architecture.md"
  },
  "tags": [
    {
      "name": "Auth",
      "description": "تسجيل الدخول، وتحديث الرمز، ودورة حياة الجلسة.",
      "x-displayName": "المصادقة"
    },
    {
      "name": "Libraries",
      "description": "مجموعات مجلدات تتشارك الإعدادات وملف تعريف اللغة.",
      "x-displayName": "المكتبات"
    },
    {
      "name": "Videos",
      "description": "بيانات الفيديو الوصفية، وعناصر التحكم في المعالجة، ونافذة النص المفرّغ.",
      "x-displayName": "المقاطع"
    },
    {
      "name": "Search",
      "description": "بحث هجين (نصي كامل + دلالي) مع عوامل تصفية واستعلامات محفوظة.",
      "x-displayName": "البحث"
    },
    {
      "name": "Jobs",
      "description": "حالة مهام خط المعالجة والتحكم بالإيقاف المؤقت / الاستئناف / الإلغاء / إعادة المحاولة.",
      "x-displayName": "المهام"
    },
    {
      "name": "Queue",
      "description": "إحصاءات مجمّعة لطابور المهام.",
      "x-displayName": "طابور المهام"
    },
    {
      "name": "Collections",
      "description": "مجموعات فيديو ينسّقها المستخدم ومجموعات ذكية.",
      "x-displayName": "المجموعات"
    },
    {
      "name": "Tags",
      "description": "تصنيف الوسوم.",
      "x-displayName": "الوسوم"
    },
    {
      "name": "Speakers",
      "description": "تسميات المتحدثين المستخرجة من تمييز المتحدثين.",
      "x-displayName": "المتحدثون"
    },
    {
      "name": "Watch progress",
      "description": "موضع التشغيل وحالة الإكمال لكل مستخدم.",
      "x-displayName": "تقدّم المشاهدة"
    },
    {
      "name": "Sessions",
      "description": "دورة حياة جلسة البث (إصدار عناوين URL موقّعة، والإغلاق، والإمكانات).",
      "x-displayName": "الجلسات"
    },
    {
      "name": "Settings",
      "description": "إعدادات التطبيق العامة وإعدادات كل مستخدم.",
      "x-displayName": "الإعدادات"
    },
    {
      "name": "Devices",
      "description": "تسجيل الأجهزة للإشعارات الفورية.",
      "x-displayName": "الأجهزة"
    },
    {
      "name": "Recommendations",
      "description": "اقتراحات فيديو مخصّصة.",
      "x-displayName": "التوصيات"
    },
    {
      "name": "System",
      "description": "الصحة، والإصدار، والمقاييس. متاحة لوكلاء المراقبة.",
      "x-displayName": "النظام"
    },
    {
      "name": "WebSocket",
      "description": "قناة أحداث فورية (موثّقة هنا؛ البروتوكول هو WS).",
      "x-displayName": "البث الفوري (WebSocket)"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "cookieAuth": []
    }
  ],
  "paths": {
    "/auth/login": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "المصادقة باسم المستخدم وكلمة المرور",
        "description": "عند النجاح، يضبط ملفي تعريف الارتباط `auth` و`csrf_token` (للويب) **ويعيد**\nرمز وصول من نوع حامل + رمز تحديث في الجسم (للجوال والتلفاز). يستخدم العملاء\nما يحتاجون إليه منهما؛ إذ يُصدر الخادم كليهما دون شرط.\n",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginRequest"
              },
              "example": {
                "username": "admin",
                "password": "correct horse battery staple"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "تمّت المصادقة.",
            "headers": {
              "Set-Cookie": {
                "schema": {
                  "type": "string"
                },
                "description": "يضبط ملفي تعريف الارتباط `auth` (من نوع httpOnly وsecure) و`csrf_token` (قابل للقراءة)."
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTokenResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "login"
      }
    },
    "/auth/register": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "إنشاء حساب مستخدم جديد",
        "description": "معطّل في وضع المستخدم الواحد. عند تفعيله، يتطلب إما رمز مشرف\n(في وضع تعدد المستخدمين مع دعوات من المشرف فقط) أو تسجيلًا مفتوحًا إن كان مُعدًّا.\n",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "تم إنشاء الحساب.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTokenResponse"
                }
              }
            }
          },
          "403": {
            "description": "التسجيل معطّل.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "اسم المستخدم مأخوذ مسبقًا.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "register"
      }
    },
    "/auth/refresh": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "استبدال رمز تحديث برمز وصول جديد",
        "description": "رموز تحديث متناوبة؛ يُبطَل رمز التحديث السابق عند استخدامه.\nيرسل عملاء الويب رمز التحديث عبر ملف تعريف الارتباط `refresh_token`، ويرسل\nالعملاء الأصليون `{refresh_token}` في الجسم.\n",
        "security": [],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "refresh_token": {
                    "type": "string",
                    "description": "مطلوب للعملاء الأصليين."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "زوج رموز جديد.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTokenResponse"
                }
              }
            }
          },
          "401": {
            "description": "رمز التحديث غير صالح أو ملغى أو منتهي الصلاحية.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "refreshToken"
      }
    },
    "/auth/logout": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "إلغاء بيانات الاعتماد الحالية",
        "description": "يمسح ملفات تعريف ارتباط المصادقة ويلغي رمز التحديث من نوع حامل.",
        "responses": {
          "204": {
            "description": "تم تسجيل الخروج.",
            "headers": {
              "Set-Cookie": {
                "schema": {
                  "type": "string"
                },
                "description": "يمسح ملفات تعريف الارتباط `auth` و`csrf_token` و`refresh_token`."
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "logout"
      }
    },
    "/auth/me": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "إعادة المستخدم الموثَّق",
        "responses": {
          "200": {
            "description": "الملف الشخصي للمستخدم الموثَّق.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getCurrentUser"
      }
    },
    "/libraries": {
      "get": {
        "tags": [
          "Libraries"
        ],
        "summary": "سرد المكتبات",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "صفحة من المكتبات.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Library"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listLibraries"
      },
      "post": {
        "tags": [
          "Libraries"
        ],
        "summary": "إنشاء مكتبة",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LibraryCreate"
              },
              "example": {
                "name": "Lectures",
                "roots": [
                  "/mnt/media/lectures"
                ],
                "settings": {
                  "language": "ar",
                  "stt_profile": "default"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "تم إنشاء المكتبة.",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri-reference"
                },
                "description": "عنوان URL القانوني للمكتبة الجديدة."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Library"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "description": "الاسم مستخدم مسبقًا.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "createLibrary"
      }
    },
    "/libraries/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/LibraryId"
        }
      ],
      "get": {
        "tags": [
          "Libraries"
        ],
        "summary": "جلب مكتبة",
        "responses": {
          "200": {
            "description": "المكتبة.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Library"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getLibrary"
      },
      "patch": {
        "tags": [
          "Libraries"
        ],
        "summary": "تحديث مكتبة",
        "description": "تُدمج الإعدادات دمجًا عميقًا؛ مرّر `null` لمسح مفتاح.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LibraryUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "المكتبة بعد التحديث.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Library"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "updateLibrary"
      },
      "delete": {
        "tags": [
          "Libraries"
        ],
        "summary": "حذف مكتبة",
        "parameters": [
          {
            "in": "query",
            "name": "purge",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "عند `true`، يحذف ملفات الوسائط من القرص أيضًا."
          },
          {
            "in": "query",
            "name": "confirm",
            "schema": {
              "type": "string"
            },
            "description": "مطلوب عند `purge=true`. يجب أن يساوي معرّف المكتبة."
          }
        ],
        "responses": {
          "204": {
            "description": "تم الحذف."
          },
          "207": {
            "description": "حالات متعددة — تمّ الحذف المؤقت، وتعذّر حذف بعض الملفات.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "failed_paths": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "412": {
            "description": "رمز التأكيد مفقود أو خاطئ.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "deleteLibrary"
      }
    },
    "/libraries/{id}/scan": {
      "parameters": [
        {
          "$ref": "#/components/parameters/LibraryId"
        }
      ],
      "post": {
        "tags": [
          "Libraries"
        ],
        "summary": "إضافة مهمة فحص لمكتبة إلى طابور المهام",
        "description": "يعود فورًا بمعرّف مهمة الفحص؛ ويُنشر التقدم عبر WebSocket.",
        "responses": {
          "202": {
            "description": "أُضيف الفحص إلى الطابور.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "job_id"
                  ],
                  "properties": {
                    "job_id": {
                      "type": "integer",
                      "format": "int64"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "scanLibrary"
      }
    },
    "/libraries/{id}/stats": {
      "parameters": [
        {
          "$ref": "#/components/parameters/LibraryId"
        }
      ],
      "get": {
        "tags": [
          "Libraries"
        ],
        "summary": "إحصاءات مجمّعة لمكتبة",
        "responses": {
          "200": {
            "description": "إحصاءات المكتبة.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LibraryStats"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getLibraryStats"
      }
    },
    "/videos": {
      "get": {
        "tags": [
          "Videos"
        ],
        "summary": "سرد الفيديوهات",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "in": "query",
            "name": "library",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "uuid"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "in": "query",
            "name": "language",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 2,
                "maxLength": 5
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "in": "query",
            "name": "type",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": true,
            "description": "التصفية حسب `content_type` (مثل `lecture` و`film`)."
          },
          {
            "in": "query",
            "name": "tag",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "in": "query",
            "name": "q",
            "schema": {
              "type": "string",
              "maxLength": 256
            },
            "description": "بحث نصي كامل خفيف في العنوان + الوصف. استخدم `POST /search` للبحث الكامل."
          },
          {
            "in": "query",
            "name": "sort",
            "schema": {
              "type": "string",
              "enum": [
                "updated_at",
                "created_at",
                "title",
                "duration_sec",
                "relevance"
              ],
              "default": "created_at"
            },
            "description": "دون ترتيب محدد، الأحدث إضافةً أولًا (`created_at`)؛ ومع `q`، الترتيب `relevance` (العناوين التي تبدأ بـ `q`، ثم العناوين التي تحتويه، ثم الأوصاف فقط، وكلٌّ منها الأحدث إضافةً أولًا). الترتيب الذي يحدده المستدعي يتقدّم دائمًا؛ ويتطلب `relevance` وجود `q`."
          }
        ],
        "responses": {
          "200": {
            "description": "صفحة من الفيديوهات.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/VideoSummary"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "ترتيب أو عامل تصفية غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listVideos"
      }
    },
    "/videos/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/VideoId"
        }
      ],
      "get": {
        "tags": [
          "Videos"
        ],
        "summary": "جلب فيديو مع بياناته الوصفية الكاملة",
        "responses": {
          "200": {
            "description": "الفيديو.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VideoDetail"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getVideo"
      },
      "patch": {
        "tags": [
          "Videos"
        ],
        "summary": "تحديث حقول الفيديو القابلة للتعديل",
        "description": "حجم الجسم محدود بـ 8 KiB.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VideoUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "الفيديو بعد التحديث.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VideoDetail"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "413": {
            "description": "الجسم كبير جدًا.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "updateVideo"
      },
      "delete": {
        "tags": [
          "Videos"
        ],
        "summary": "حذف فيديو",
        "parameters": [
          {
            "in": "query",
            "name": "purge",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "in": "query",
            "name": "confirm",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "مطلوب عند `purge=true`؛ ويجب أن يساوي معرّف الفيديو."
          }
        ],
        "responses": {
          "204": {
            "description": "تم الحذف."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "412": {
            "description": "التأكيد مطلوب للحذف النهائي.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "deleteVideo"
      }
    },
    "/videos/{id}/process": {
      "parameters": [
        {
          "$ref": "#/components/parameters/VideoId"
        }
      ],
      "post": {
        "tags": [
          "Videos"
        ],
        "summary": "إضافة مرحلة معالجة واحدة لفيديو إلى طابور المهام",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "stage"
                ],
                "properties": {
                  "stage": {
                    "$ref": "#/components/schemas/JobStage"
                  },
                  "priority": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 999,
                    "default": 100
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "أُضيفت المهمة إلى الطابور (أو أُعيدت إن كانت موجودة مسبقًا).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "job_id",
                    "stage",
                    "state"
                  ],
                  "properties": {
                    "job_id": {
                      "type": "integer",
                      "format": "int64"
                    },
                    "stage": {
                      "$ref": "#/components/schemas/JobStage"
                    },
                    "state": {
                      "$ref": "#/components/schemas/JobState"
                    },
                    "note": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "لا يمكن إضافة `stage` إلى الطابور على مستوى الفيديو (مثل `scan`).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "processVideo"
      }
    },
    "/videos/{id}/reprocess": {
      "parameters": [
        {
          "$ref": "#/components/parameters/VideoId"
        }
      ],
      "post": {
        "tags": [
          "Videos"
        ],
        "summary": "إعادة ضبط الحالة وإعادة المعالجة من مرحلة معيّنة",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "from_stage"
                ],
                "properties": {
                  "from_stage": {
                    "$ref": "#/components/schemas/JobStage"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "أُضيفت المهام إلى الطابور.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "job_ids",
                    "from_stage",
                    "predecessor_state"
                  ],
                  "properties": {
                    "job_ids": {
                      "type": "array",
                      "items": {
                        "type": "integer",
                        "format": "int64"
                      }
                    },
                    "from_stage": {
                      "$ref": "#/components/schemas/JobStage"
                    },
                    "predecessor_state": {
                      "$ref": "#/components/schemas/VideoState"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "reprocessVideo"
      }
    },
    "/videos/{id}/segments": {
      "parameters": [
        {
          "$ref": "#/components/parameters/VideoId"
        }
      ],
      "get": {
        "tags": [
          "Videos"
        ],
        "summary": "قراءة نافذة من النص المفرّغ لفيديو",
        "parameters": [
          {
            "in": "query",
            "name": "from",
            "schema": {
              "type": "number",
              "format": "float",
              "default": 0
            },
            "description": "البداية، شاملة (بالثواني)."
          },
          {
            "in": "query",
            "name": "to",
            "schema": {
              "type": "number",
              "format": "float"
            },
            "description": "النهاية، غير شاملة (بالثواني). الافتراضي نهاية النص المفرّغ."
          },
          {
            "in": "query",
            "name": "words",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "عند `true`، يملأ `Segment.words` بتوقيت كل كلمة."
          },
          {
            "in": "query",
            "name": "include_superseded",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "تضمين المقاطع من النصوص المفرّغة المستبدَلة."
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "المقاطع ضمن `[from, to)`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SegmentWindow"
                }
              }
            }
          },
          "400": {
            "description": "نافذة زمنية أو استعلام غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listVideoSegments"
      }
    },
    "/videos/{id}/subtitles": {
      "parameters": [
        {
          "$ref": "#/components/parameters/VideoId"
        }
      ],
      "get": {
        "tags": [
          "Videos"
        ],
        "summary": "سرد مسارات الترجمات المصاحبة (عناوين URL موقّعة)",
        "parameters": [
          {
            "in": "header",
            "name": "Accept-Language",
            "schema": {
              "type": "string"
            },
            "description": "ترتيب اللغات المفضّلة؛ يحدد ترتيب النتيجة."
          }
        ],
        "responses": {
          "200": {
            "description": "مسارات الترجمات المصاحبة. عناوين URL موقّعة وقصيرة العمر.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Subtitle"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listVideoSubtitles"
      }
    },
    "/videos/{id}/chapters": {
      "parameters": [
        {
          "$ref": "#/components/parameters/VideoId"
        }
      ],
      "get": {
        "tags": [
          "Videos"
        ],
        "summary": "سرد فصول فيديو (مرتّبة حسب `seq`)",
        "responses": {
          "200": {
            "description": "الفصول.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Chapter"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listVideoChapters"
      }
    },
    "/videos/{id}/tags": {
      "parameters": [
        {
          "$ref": "#/components/parameters/VideoId"
        }
      ],
      "patch": {
        "tags": [
          "Tags"
        ],
        "summary": "إضافة وسوم إلى فيديو أو إزالتها منه",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "add": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 64
                    }
                  },
                  "remove": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "قائمة وسوم الفيديو بعد التحديث.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Tag"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "patchVideoTags"
      }
    },
    "/videos/{id}/pause": {
      "parameters": [
        {
          "$ref": "#/components/parameters/VideoId"
        }
      ],
      "post": {
        "tags": [
          "Jobs"
        ],
        "summary": "إيقاف كل مهمة نشطة لهذا الفيديو مؤقتًا",
        "responses": {
          "200": {
            "description": "عدد المهام المعلَّمة.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AffectedCount"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "pauseVideoJobs"
      }
    },
    "/videos/{id}/resume": {
      "parameters": [
        {
          "$ref": "#/components/parameters/VideoId"
        }
      ],
      "post": {
        "tags": [
          "Jobs"
        ],
        "summary": "استئناف كل مهمة موقوفة مؤقتًا لهذا الفيديو",
        "responses": {
          "200": {
            "description": "عدد المهام المستأنَفة.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AffectedCount"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "resumeVideoJobs"
      }
    },
    "/videos/{id}/cancel": {
      "parameters": [
        {
          "$ref": "#/components/parameters/VideoId"
        }
      ],
      "post": {
        "tags": [
          "Jobs"
        ],
        "summary": "إلغاء كل مهمة نشطة لهذا الفيديو",
        "responses": {
          "200": {
            "description": "عدد المهام الملغاة.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AffectedCount"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "cancelVideoJobs"
      }
    },
    "/videos/{id}/progress": {
      "parameters": [
        {
          "$ref": "#/components/parameters/VideoId"
        }
      ],
      "get": {
        "tags": [
          "Watch progress"
        ],
        "summary": "جلب حالة التشغيل للمستخدم الحالي وفيديو",
        "responses": {
          "200": {
            "description": "حالة التشغيل. تُعاد أصفار إن لم يشغّل المستخدم الفيديو بعد.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlaybackState"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getWatchProgress"
      },
      "put": {
        "tags": [
          "Watch progress"
        ],
        "summary": "إنشاء حالة التشغيل أو تحديثها للمستخدم الحالي وفيديو",
        "description": "يُخمَّد على الخادم (مرة واحدة في الثانية لكل مستخدم/فيديو). يُطلق `playback.completed`\nعند الانتقال `false → true`. مستثنى من حدود المعدّل لكل مستخدم.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlaybackStateInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "تم الاستلام.",
            "headers": {
              "Maktaba-Warning": {
                "schema": {
                  "type": "string"
                },
                "description": "يُضبط إن قُصّ `position_sec` إلى المدة."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlaybackState"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "updateWatchProgress"
      }
    },
    "/search": {
      "get": {
        "tags": [
          "Search"
        ],
        "summary": "بحث هجين في المكتبة",
        "description": "يجمع بين البحث النصي الكامل BM25 وتشابه المتجهات باستخدام دمج الرتب التبادلي.\nتحمل النتائج توقيت كل مرحلة ضمن `took_ms`. عندما تكون الخلفية الدلالية\nغير متصلة، تضبط الاستجابة `degraded=true` وتعود إلى البحث النصي الكامل وحده.\n",
        "parameters": [
          {
            "in": "query",
            "name": "q",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 1024
            }
          },
          {
            "in": "query",
            "name": "mode",
            "schema": {
              "type": "string",
              "enum": [
                "hybrid",
                "fts",
                "semantic"
              ],
              "default": "hybrid"
            }
          },
          {
            "in": "query",
            "name": "language",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 2,
                "maxLength": 5
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "in": "query",
            "name": "library",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "uuid"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "in": "query",
            "name": "tag",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "in": "query",
            "name": "speaker",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "نتائج البحث.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "استعلام غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "description": "الخلفية الدلالية غير متاحة وقد طُلب `mode=semantic`.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "searchByQuery"
      },
      "post": {
        "tags": [
          "Search"
        ],
        "summary": "بحث هجين بجسم طلب منظَّم",
        "description": "الدلالات نفسها كما في `GET /search`؛ ويُفضَّل شكل الجسم عندما تطول عوامل التصفية.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "نتائج البحث.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "استعلام غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "search"
      }
    },
    "/search/suggest": {
      "get": {
        "tags": [
          "Search"
        ],
        "summary": "اقتراحات الإكمال التلقائي",
        "parameters": [
          {
            "in": "query",
            "name": "q",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 64
            }
          }
        ],
        "responses": {
          "200": {
            "description": "حتى 10 اقتراحات مرتّبة حسب التكرار.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "suggestions"
                  ],
                  "properties": {
                    "suggestions": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "searchSuggest"
      }
    },
    "/search/save": {
      "post": {
        "tags": [
          "Search"
        ],
        "summary": "حفظ استعلام بحث للمستخدم الحالي",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SavedSearchInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "تم الحفظ.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SavedSearch"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "description": "يوجد بحث محفوظ بهذا الاسم مسبقًا لهذا المستخدم.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "saveSearch"
      }
    },
    "/search/saved": {
      "get": {
        "tags": [
          "Search"
        ],
        "summary": "سرد عمليات البحث المحفوظة للمستخدم الحالي",
        "responses": {
          "200": {
            "description": "عمليات البحث المحفوظة.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "items"
                  ],
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SavedSearch"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listSavedSearches"
      }
    },
    "/search/saved/{id}": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "delete": {
        "tags": [
          "Search"
        ],
        "summary": "حذف بحث محفوظ",
        "responses": {
          "204": {
            "description": "تم الحذف."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "deleteSavedSearch"
      }
    },
    "/jobs": {
      "get": {
        "tags": [
          "Jobs"
        ],
        "summary": "سرد مهام المعالجة",
        "parameters": [
          {
            "in": "query",
            "name": "state",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/JobState"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "in": "query",
            "name": "stage",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/JobStage"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "in": "query",
            "name": "video",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "صفحة من المهام.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Job"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listJobs"
      }
    },
    "/jobs/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/JobId"
        }
      ],
      "get": {
        "tags": [
          "Jobs"
        ],
        "summary": "جلب مهمة",
        "responses": {
          "200": {
            "description": "المهمة.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getJob"
      }
    },
    "/jobs/{id}/pause": {
      "parameters": [
        {
          "$ref": "#/components/parameters/JobId"
        }
      ],
      "post": {
        "tags": [
          "Jobs"
        ],
        "summary": "طلب إيقاف مؤقت سلس",
        "description": "آمن التكرار. مع `?force=true`، يقلب الحالة فورًا ويُسقط المقطع قيد المعالجة.",
        "parameters": [
          {
            "in": "query",
            "name": "force",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "المهمة (مع `pause_requested=true` أو `state=paused`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "المهمة في حالة نهائية.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "pauseJob"
      }
    },
    "/jobs/{id}/resume": {
      "parameters": [
        {
          "$ref": "#/components/parameters/JobId"
        }
      ],
      "post": {
        "tags": [
          "Jobs"
        ],
        "summary": "جعل مهمة موقوفة مؤقتًا قابلة للالتقاط من جديد",
        "responses": {
          "200": {
            "description": "المهمة.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "المهمة في حالة نهائية.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "resumeJob"
      }
    },
    "/jobs/{id}/cancel": {
      "parameters": [
        {
          "$ref": "#/components/parameters/JobId"
        }
      ],
      "post": {
        "tags": [
          "Jobs"
        ],
        "summary": "إلغاء مهمة",
        "description": "آمن التكرار. يضبط `cancel_requested`، أو ينقل `pending` → `cancelled` فورًا.",
        "responses": {
          "200": {
            "description": "المهمة.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "المهمة في حالة نهائية.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "cancelJob"
      }
    },
    "/jobs/{id}/retry": {
      "parameters": [
        {
          "$ref": "#/components/parameters/JobId"
        }
      ],
      "post": {
        "tags": [
          "Jobs"
        ],
        "summary": "إعادة مهمة فاشلة إلى `pending`",
        "responses": {
          "200": {
            "description": "المهمة.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "المهمة ليست في الحالة `failed`.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "retryJob"
      }
    },
    "/queue/stats": {
      "get": {
        "tags": [
          "Queue"
        ],
        "summary": "إحصاءات طابور المهام المجمّعة لكل مرحلة",
        "responses": {
          "200": {
            "description": "إحصاءات طابور المهام.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueueStats"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getQueueStats"
      }
    },
    "/collections": {
      "get": {
        "tags": [
          "Collections"
        ],
        "summary": "سرد المجموعات",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "صفحة من المجموعات.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Collection"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listCollections"
      },
      "post": {
        "tags": [
          "Collections"
        ],
        "summary": "إنشاء مجموعة (يدوية أو ذكية)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CollectionCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "تم إنشاء المجموعة.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Collection"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "createCollection"
      }
    },
    "/collections/{id}": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "tags": [
          "Collections"
        ],
        "summary": "جلب مجموعة",
        "responses": {
          "200": {
            "description": "المجموعة.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Collection"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getCollection"
      },
      "patch": {
        "tags": [
          "Collections"
        ],
        "summary": "تحديث مجموعة",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CollectionUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "المجموعة بعد التحديث.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Collection"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "updateCollection"
      },
      "delete": {
        "tags": [
          "Collections"
        ],
        "summary": "حذف مجموعة",
        "responses": {
          "204": {
            "description": "تم الحذف."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "deleteCollection"
      }
    },
    "/collections/{id}/videos": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "tags": [
          "Collections"
        ],
        "summary": "سرد الفيديوهات في مجموعة",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "صفحة من الفيديوهات.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/VideoSummary"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listCollectionVideos"
      },
      "post": {
        "tags": [
          "Collections"
        ],
        "summary": "إضافة فيديو إلى مجموعة",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "video_id"
                ],
                "properties": {
                  "video_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "position": {
                    "type": "integer",
                    "minimum": 0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "أُضيف الفيديو.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionItem"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "addCollectionVideo"
      }
    },
    "/collections/{id}/videos/{videoId}": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        {
          "in": "path",
          "name": "videoId",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "delete": {
        "tags": [
          "Collections"
        ],
        "summary": "إزالة فيديو من مجموعة",
        "responses": {
          "204": {
            "description": "تمّت الإزالة."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "removeCollectionVideo"
      }
    },
    "/tags": {
      "get": {
        "tags": [
          "Tags"
        ],
        "summary": "سرد الوسوم",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "in": "query",
            "name": "q",
            "schema": {
              "type": "string",
              "maxLength": 64
            },
            "description": "تصفية بجزء من النص."
          }
        ],
        "responses": {
          "200": {
            "description": "صفحة من الوسوم.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Tag"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listTags"
      },
      "post": {
        "tags": [
          "Tags"
        ],
        "summary": "إنشاء وسم",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 64
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "الوسم.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tag"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "description": "الوسم موجود مسبقًا.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "createTag"
      }
    },
    "/sessions": {
      "post": {
        "tags": [
          "Sessions"
        ],
        "summary": "إصدار جلسة بث",
        "description": "يعيد عنوان URL موقّعًا لملف البيان (HLS / DASH) أو عنوان URL مباشرًا. يمرّره العميل\nإلى مشغّله؛ وتقدّم خدمة البث البايتات، لا الواجهة البرمجية.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SessionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "تم إصدار الجلسة.",
            "headers": {
              "Maktaba-Warning": {
                "schema": {
                  "type": "string"
                },
                "description": "مثل `start-sec-clamped`."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Session"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "لا يمكن للمستخدم الوصول إلى هذا الفيديو.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          },
          "507": {
            "description": "المساحة الحرة على قرص خدمة البث أقل من أن تكفي لتجهيز الفيديو (تحويل ترميزه) (الرمز `insufficient_storage`).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "createSession"
      }
    },
    "/sessions/{id}": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "tags": [
          "Sessions"
        ],
        "summary": "جلب جلسة",
        "responses": {
          "200": {
            "description": "الجلسة.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Session"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getSession"
      },
      "delete": {
        "tags": [
          "Sessions"
        ],
        "summary": "إغلاق جلسة بث",
        "description": "يحرّر خانة محوّل الترميز ويلغي عنوان URL الموقّع.",
        "responses": {
          "204": {
            "description": "أُغلقت."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "closeSession"
      }
    },
    "/sessions/{id}/progress": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "post": {
        "tags": [
          "Sessions"
        ],
        "summary": "نبضة تقدّم الجلسة",
        "description": "يُخمَّد على الخادم (مرة واحدة في الثانية). ينسخ الموضع إلى `playback_state`.\nمستثنى من حدود المعدّل.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "position_sec"
                ],
                "properties": {
                  "position_sec": {
                    "type": "number",
                    "minimum": 0
                  },
                  "completed": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "مقبول.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accepted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "sessionProgressHeartbeat"
      }
    },
    "/sessions/capabilities": {
      "get": {
        "tags": [
          "Sessions"
        ],
        "summary": "إمكانات خادم البث",
        "description": "مخزّنة مؤقتًا 60 ثانية؛ وتُبطلها خدمة البث عند تغيّر ملف تعريف المرمِّز.",
        "responses": {
          "200": {
            "description": "الإمكانات.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamCapabilities"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getStreamCapabilities"
      }
    },
    "/settings": {
      "get": {
        "tags": [
          "Settings"
        ],
        "summary": "قراءة الإعدادات الفعّالة",
        "description": "يدمج القيم الافتراضية والملف ومتغيرات البيئة وقاعدة البيانات. لا تُعاد الأسرار أبدًا.",
        "responses": {
          "200": {
            "description": "الإعدادات.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Settings"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getSettings"
      },
      "put": {
        "tags": [
          "Settings"
        ],
        "summary": "استبدال طبقة الإعدادات المخزّنة في قاعدة البيانات",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SettingsInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "الإعدادات بعد التحديث (تُقرأ من جديد بعد الكتابة).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Settings"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "updateSettings"
      }
    },
    "/settings/stt-backends": {
      "get": {
        "tags": [
          "Settings"
        ],
        "summary": "تعداد خلفيات تحويل الكلام إلى نص المتاحة",
        "responses": {
          "200": {
            "description": "قائمة الخلفيات.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SttBackend"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listSttBackends"
      }
    },
    "/settings/stt-test": {
      "post": {
        "tags": [
          "Settings"
        ],
        "summary": "تجربة طلب تفريغ نصي على خلفية دون تنفيذ فعلي",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "backend"
                ],
                "properties": {
                  "backend": {
                    "type": "string"
                  },
                  "config": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "نتيجة الاختبار.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "latency_ms": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "testSttBackend"
      }
    },
    "/devices/register": {
      "post": {
        "tags": [
          "Devices"
        ],
        "summary": "تسجيل جهاز للإشعارات الفورية أو تدوير رمزه",
        "description": "آمن التكرار على `(user_id, platform, bundle_id)`. يعيد 201 عند أول\nتسجيل، و200 عند تدوير الرمز.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeviceRegisterInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "تم تحديث الجهاز (دُوِّر الرمز).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Device"
                }
              }
            }
          },
          "201": {
            "description": "تم تسجيل الجهاز.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Device"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "registerDevice"
      }
    },
    "/devices": {
      "get": {
        "tags": [
          "Devices"
        ],
        "summary": "سرد الأجهزة المسجّلة للمستخدم الحالي",
        "description": "تُحجب رموز الإشعارات الفورية في هذا العرض.",
        "responses": {
          "200": {
            "description": "الأجهزة.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "items"
                  ],
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Device"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listDevices"
      }
    },
    "/devices/{id}": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "delete": {
        "tags": [
          "Devices"
        ],
        "summary": "إلغاء جهاز مسجّل",
        "responses": {
          "204": {
            "description": "أُلغي."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "revokeDevice"
      }
    },
    "/recommendations": {
      "get": {
        "tags": [
          "Recommendations"
        ],
        "summary": "توصيات فيديو مخصّصة",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "in": "query",
            "name": "shelf",
            "schema": {
              "type": "string",
              "enum": [
                "continue_watching",
                "more_like_this",
                "recently_added",
                "trending"
              ]
            },
            "description": "عند ضبطه، يعيد رفًّا واحدًا فقط."
          }
        ],
        "responses": {
          "200": {
            "description": "التوصيات مجمّعة حسب الرف.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecommendationsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getRecommendations"
      }
    },
    "/ws": {
      "get": {
        "tags": [
          "WebSocket"
        ],
        "summary": "الترقية إلى تدفق الأحداث الفوري",
        "description": "ترقية HTTP/1.1 إلى WebSocket. موثّقة هنا لأدوات توليد العملاء\nالتي تريد معرفة وجود البروتوكول؛ وغلاف الرسالة موجود في\nقسم المخططات باسم `WsMessage`.\n\n### القنوات\n- `jobs` — حالة المهام وتقدّمها.\n- `playback` — الأحداث `playback.progress` و`playback.completed`.\n- `library` — الأحداث `library.updated` و`videos.state_changed`.\n- `system` — `profiles_changed` و`health_changed`.\n\n### الاشتراك\n```json\n{ \"type\": \"subscribe\", \"channels\": [\"jobs\", \"playback\"] }\n```\n\n### حدث نموذجي\n```json\n{\n  \"type\": \"jobs.progress\",\n  \"data\": { \"job_id\": 42, \"stage\": \"transcribe\", \"pct\": 0.18, \"eta_sec\": 612 },\n  \"at\": \"2026-05-05T13:21:04Z\"\n}\n```\n",
        "responses": {
          "101": {
            "description": "تبديل البروتوكولات (WebSocket)."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "connectWebSocket",
        "x-ws-message-schema": {
          "$ref": "#/components/schemas/WsMessage"
        },
        "requestBody": {
          "$ref": "#/components/requestBodies/WsClientMessage"
        }
      }
    },
    "/system/health": {
      "servers": [
        {
          "url": "https://{host}",
          "variables": {
            "host": {
              "default": "maktaba.local"
            }
          }
        }
      ],
      "get": {
        "tags": [
          "System"
        ],
        "summary": "فحص الحياة / الجاهزية",
        "description": "مركّبة على كلٍّ من `/health` (خارج جذر الواجهة البرمجية، لوكلاء المراقبة) و\n`/api/system/health`. تعيد 503 إن كان أي مكوّن مطلوب في الحالة `down`.\n",
        "security": [],
        "responses": {
          "200": {
            "description": "كل الاعتماديات سليمة أو متراجعة الأداء.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "description": "مكوّن مطلوب واحد على الأقل متوقف.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getHealth"
      }
    },
    "/system/version": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "تعريف البناء",
        "description": "مركّبة على كلٍّ من `/version` و`/api/system/version`.",
        "security": [],
        "responses": {
          "200": {
            "description": "البيانات الوصفية للإصدار.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Version"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getVersion"
      }
    },
    "/system/metrics": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "عرض مقاييس Prometheus (بصيغة نصية)",
        "description": "مركّبة على `/metrics` على مستمع منفصل (الافتراضي `127.0.0.1:9090`).\nعند ضبط `metrics_admin_token`، تتطلب `Authorization: Bearer`.\n",
        "security": [],
        "responses": {
          "200": {
            "description": "صيغة Prometheus النصية.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "رمز المقاييس مفقود أو غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getMetrics"
      }
    },
    "/speakers": {
      "get": {
        "tags": [
          "Speakers"
        ],
        "summary": "سرد المتحدثين",
        "operationId": "listSpeakers",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "in": "query",
            "name": "library",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "صفحة من المتحدثين.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Speaker"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/speakers/{id}": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "integer",
            "format": "int64"
          }
        }
      ],
      "patch": {
        "tags": [
          "Speakers"
        ],
        "summary": "إعادة تسمية متحدث",
        "operationId": "renameSpeaker",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "المتحدث بعد التحديث.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Speaker"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/speakers/merge": {
      "post": {
        "tags": [
          "Speakers"
        ],
        "summary": "دمج تسميتَي متحدثَين في تسمية واحدة",
        "operationId": "mergeSpeakers",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "keep",
                  "drop"
                ],
                "properties": {
                  "keep": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "drop": {
                    "type": "integer",
                    "format": "int64"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "نتيجة الدمج.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "kept": {
                      "$ref": "#/components/schemas/Speaker"
                    },
                    "reassigned_segments": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/queues": {
      "get": {
        "tags": [
          "Queue"
        ],
        "summary": "لقطة عامة لطوابير المهام",
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueuesSnapshot"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getQueuesSnapshot"
      }
    },
    "/queues/graph": {
      "get": {
        "tags": [
          "Queue"
        ],
        "summary": "مخطط المراحل ومجمّعات العمال",
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "stages": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/QueueStageInfo"
                      }
                    },
                    "pools": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WorkerPool"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getQueueGraph"
      }
    },
    "/queues/libraries": {
      "get": {
        "tags": [
          "Queue"
        ],
        "summary": "تقدّم طابور المهام لكل مكتبة (مخزّن مؤقتًا 5 ثوانٍ)",
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/LibraryQueueRow"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getQueueLibraries"
      }
    },
    "/queues/health": {
      "get": {
        "tags": [
          "Queue"
        ],
        "summary": "مقاييس الصحة عبر الزمن",
        "parameters": [
          {
            "name": "hours",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 168,
              "default": 6
            }
          }
        ],
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "series": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/HealthSeries"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getQueueHealth"
      }
    },
    "/queues/pause-all": {
      "post": {
        "tags": [
          "Queue"
        ],
        "summary": "إيقاف كل الطوابير مؤقتًا",
        "responses": {
          "204": {
            "description": "تم."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "للمشرف فقط.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "pauseAllQueues"
      }
    },
    "/queues/resume-all": {
      "post": {
        "tags": [
          "Queue"
        ],
        "summary": "استئناف كل الطوابير",
        "responses": {
          "204": {
            "description": "تم."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "للمشرف فقط.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "resumeAllQueues"
      }
    },
    "/queues/{stage}": {
      "parameters": [
        {
          "name": "stage",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "tags": [
          "Queue"
        ],
        "summary": "طابور واحد: المؤشرات الرئيسية، وما يعمل الآن، والتالي، والإخفاقات، والسجل",
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueueDetail"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getQueueDetail"
      },
      "patch": {
        "tags": [
          "Queue"
        ],
        "summary": "تفعيل طابور أو تعطيله أو ضبط وضع الكتابة فيه",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  },
                  "write_mode": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "apply",
                      "review"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueueStageInfo"
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "للمشرف فقط.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "المرحلة غير مُعدّة.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "patchQueue"
      }
    },
    "/queues/{stage}/rate": {
      "parameters": [
        {
          "name": "stage",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "tags": [
          "Queue"
        ],
        "summary": "المكتمل/الفاشل/المتخطّى لكل 10 دقائق",
        "parameters": [
          {
            "name": "hours",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 168,
              "default": 24
            }
          }
        ],
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bucket_sec": {
                      "type": "integer"
                    },
                    "points": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/QueueRatePoint"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getQueueRate"
      }
    },
    "/queues/{stage}/jobs": {
      "parameters": [
        {
          "name": "stage",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "tags": [
          "Queue"
        ],
        "summary": "مهام طابور (ترقيم بالمفاتيح، الأحدث أولًا)",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "حالات المهام مفصولة بفواصل."
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200,
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/QueueJobRef"
                      }
                    },
                    "next": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listQueueJobs"
      }
    },
    "/queues/{stage}/failures": {
      "parameters": [
        {
          "name": "stage",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "tags": [
          "Queue"
        ],
        "summary": "الإخفاقات المفتوحة مجمّعة حسب السبب",
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "groups": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FailureGroup"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getQueueFailures"
      }
    },
    "/queues/{stage}/pause": {
      "parameters": [
        {
          "name": "stage",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "Queue"
        ],
        "summary": "إيقاف طابور مؤقتًا (تكتمل المهام الجارية)",
        "parameters": [
          {
            "name": "interrupt",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "اطلب أيضًا من المراحل المتعاونة (transcribe) التوقف مؤقتًا أثناء التشغيل."
          }
        ],
        "responses": {
          "204": {
            "description": "تم."
          },
          "400": {
            "description": "طلب غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "للمشرف فقط.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "pauseQueue"
      }
    },
    "/queues/{stage}/resume": {
      "parameters": [
        {
          "name": "stage",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "Queue"
        ],
        "summary": "استئناف طابور",
        "responses": {
          "204": {
            "description": "تم."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "للمشرف فقط.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "resumeQueue"
      }
    },
    "/queues/{stage}/retry": {
      "parameters": [
        {
          "name": "stage",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "Queue"
        ],
        "summary": "إعادة محاولة إخفاقات سبب معيّن أو مهام محددة",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "يلزم أحد الحقلين cause أو job_ids.",
                "properties": {
                  "cause": {
                    "type": "string"
                  },
                  "job_ids": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enqueued": {
                      "type": "integer"
                    },
                    "coalesced": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "للمشرف فقط.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "retryQueueFailures"
      }
    },
    "/queues/{stage}/apply": {
      "parameters": [
        {
          "name": "stage",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "Queue"
        ],
        "summary": "تطبيق الكتابات الخارجية التي رُوجعت",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "job_ids": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    }
                  },
                  "all": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enqueued": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "للمشرف فقط.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "applyQueueReviews"
      }
    },
    "/pools": {
      "get": {
        "tags": [
          "Queue"
        ],
        "summary": "مجمّعات العمال",
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pools": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WorkerPool"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listPools"
      }
    },
    "/pools/{pool}": {
      "parameters": [
        {
          "name": "pool",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "put": {
        "tags": [
          "Queue"
        ],
        "summary": "تغيير حجم مجمّع",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "size"
                ],
                "properties": {
                  "size": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "minimum": 0,
                    "maximum": 64
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkerPool"
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "للمشرف فقط.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "putPool"
      }
    },
    "/queue/retrigger": {
      "post": {
        "tags": [
          "Queue"
        ],
        "summary": "إعادة إضافة العناصر إلى طوابير دخولها",
        "description": "يُضاف كل عنصر إلى الطابور عبر دالة SQL `processing_jobs_enqueue` في معاملة واحدة.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RetriggerRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RetriggerResponse"
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "للمشرف فقط.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "retriggerQueue"
      }
    },
    "/issues": {
      "get": {
        "tags": [
          "Queue"
        ],
        "summary": "كل المشكلات المفتوحة (الإخفاقات، وما ينتظر المراجعة، والمخطط القديم)",
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "groups": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FailureGroup"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listIssues"
      }
    },
    "/activity": {
      "get": {
        "tags": [
          "Queue"
        ],
        "summary": "سجل النشاط (`job_events`)",
        "parameters": [
          {
            "name": "stage",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "library_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "level",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "info",
              "enum": [
                "debug",
                "info",
                "warn",
                "error"
              ]
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 500,
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/QueueLogLine"
                      }
                    },
                    "next": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listActivity"
      }
    },
    "/jobs/{id}/events": {
      "parameters": [
        {
          "$ref": "#/components/parameters/JobId"
        }
      ],
      "get": {
        "tags": [
          "Queue"
        ],
        "summary": "سجل مهمة واحدة",
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/QueueLogLine"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listJobEvents"
      }
    },
    "/items/{kind}/{id}/history": {
      "parameters": [
        {
          "name": "kind",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "enum": [
              "video",
              "library",
              "series",
              "season",
              "catalog"
            ]
          }
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "tags": [
          "Queue"
        ],
        "summary": "تاريخ عنصر واحد عبر الطوابير",
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200,
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueueItemHistory"
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "getItemHistory"
      }
    },
    "/workers": {
      "get": {
        "tags": [
          "Queue"
        ],
        "summary": "العمال المسجّلون وهل هم متصلون",
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "workers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/QueueWorker"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listWorkers"
      }
    },
    "/extensions": {
      "get": {
        "tags": [
          "Queue"
        ],
        "summary": "الامتدادات الاختيارية (Plex وdizqueTV)",
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "extensions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ExtensionInfo"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "listExtensions"
      }
    },
    "/extensions/{name}": {
      "parameters": [
        {
          "name": "name",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "put": {
        "tags": [
          "Queue"
        ],
        "summary": "تفعيل امتداد أو تعطيله أو تحديث إعداداته (الأسرار للكتابة فقط)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  },
                  "settings": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExtensionInfo"
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "للمشرف فقط.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "putExtension"
      }
    },
    "/extensions/{name}/test": {
      "parameters": [
        {
          "name": "name",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "Queue"
        ],
        "summary": "اختبار اتصال امتداد (قائمة من الفحوص)",
        "description": "للمشرف فقط؛ يعمل على الخادم المنزلي. كل فحص يتضمن: `key` و`ok` و`optional` (تحذير عندما لا يكون `ok`) و`skipped` و`detail` و`code` و`latency_ms`. Plex: `reachable` و`token` و`server` و`livetv` و`maktaba_tuner` و`dizquetv_tuner` و`path_map`. dizqueTV: `reachable` و`channels` و`plex_servers`. Cloudflare Stream: راجع `/tv/remote/test`. تُدقَّق كل عملية تشغيل (`audit_log` `config/extension_test`).",
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    },
                    "checked_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "lines": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "ok": {
                            "type": "boolean"
                          },
                          "optional": {
                            "type": "boolean"
                          },
                          "skipped": {
                            "type": "boolean"
                          },
                          "detail": {
                            "type": "string"
                          },
                          "code": {
                            "type": "string"
                          },
                          "latency_ms": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "للمشرف فقط.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "testExtension"
      }
    },
    "/extensions/plex/signin": {
      "post": {
        "tags": [
          "Queue"
        ],
        "summary": "بدء \"تسجيل الدخول عبر Plex\" (ينشئ رمز PIN على plex.tv)",
        "description": "للمشرف فقط. افتح `auth_url` في نافذة متصفح، ثم استعلم دوريًا عبر `GET /extensions/plex/signin/{id}`.",
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "auth_url": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "للمشرف فقط.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "تعذّر الوصول إلى plex.tv"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "plexSignin"
      }
    },
    "/extensions/plex/signin/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "tags": [
          "Queue"
        ],
        "summary": "الاستعلام عن حالة تسجيل دخول Plex؛ وعند اكتماله، يسرد خوادم Plex التابعة للحساب (دون رموز)",
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "state": {
                      "type": "string",
                      "enum": [
                        "waiting",
                        "done"
                      ]
                    },
                    "servers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "uri": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "للمشرف فقط.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "description": "تعذّر الوصول إلى plex.tv"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "plexSigninStatus"
      }
    },
    "/extensions/plex/signin/{id}/use": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "tags": [
          "Queue"
        ],
        "summary": "حفظ خادم Plex المختار (عنوان URL ورمزه) في إعدادات امتداد plex",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "تم",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExtensionInfo"
                }
              }
            }
          },
          "400": {
            "description": "طلب غير صالح.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "للمشرف فقط.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "لم يكتمل تسجيل الدخول بعد"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "operationId": "plexSigninUse"
      }
    },
    "/ws/queues": {
      "get": {
        "tags": [
          "WebSocket"
        ],
        "summary": "تدفق لقطات طوابير المهام (Server-Sent Events)",
        "description": "تدفق SSE. يرسل لقطة `queues.snapshot` واحدة فورًا، ثم كل ثانيتين ما دام الاشتراك قائمًا. عابر: لا أسطر `id:` ولا إعادة تشغيل.",
        "responses": {
          "200": {
            "description": "بثّ أحداث (`text/event-stream`)",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "operationId": "streamQueues"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "رمز وصول RS256 (صالح 15 دقيقة). يمرّره عملاء الجوال / سطح المكتب / التلفاز بالشكل\n`Authorization: Bearer <token>`. وتتحقق خدمة البث من رمز JWT نفسه\nدون اتصال مقابل JWKS في `/.well-known/jwks.json`.\n"
      },
      "cookieAuth": {
        "type": "apiKey",
        "in": "cookie",
        "name": "auth",
        "description": "ملف تعريف ارتباط `httpOnly` و`secure` و`sameSite=lax` يضبطه `POST /auth/login`.\nويجب أن ترسل الطلبات المغيّرة للحالة أيضًا الترويسة `X-CSRF-Token`.\n"
      }
    },
    "parameters": {
      "Limit": {
        "in": "query",
        "name": "limit",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 50
        },
        "description": "حجم الصفحة (1–200، الافتراضي 50)."
      },
      "Cursor": {
        "in": "query",
        "name": "cursor",
        "schema": {
          "type": "string"
        },
        "description": "مؤشر ترقيم معتم من الحقل `next` في الصفحة السابقة."
      },
      "LibraryId": {
        "in": "path",
        "name": "id",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "معرّف المكتبة."
      },
      "VideoId": {
        "in": "path",
        "name": "id",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "معرّف الفيديو."
      },
      "JobId": {
        "in": "path",
        "name": "id",
        "required": true,
        "schema": {
          "type": "integer",
          "format": "int64"
        },
        "description": "معرّف المهمة (عدد صحيح بطول 64 بت)."
      }
    },
    "headers": {
      "X-Request-Id": {
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "معرّف ربط من نوع UUIDv7. يُعاد في كل استجابة."
      },
      "X-RateLimit-Limit": {
        "schema": {
          "type": "integer"
        },
        "description": "الطلبات المسموح بها في النافذة الحالية."
      },
      "X-RateLimit-Remaining": {
        "schema": {
          "type": "integer"
        },
        "description": "الطلبات المتبقية في النافذة الحالية."
      },
      "X-RateLimit-Reset": {
        "schema": {
          "type": "integer"
        },
        "description": "ثواني توقيت يونكس التي تُعاد عندها ضبط النافذة."
      },
      "Retry-After": {
        "schema": {
          "type": "integer"
        },
        "description": "عدد الثواني التي يجب انتظارها قبل إعادة المحاولة."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "بيانات الاعتماد مفقودة أو غير صالحة.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "NotFound": {
        "description": "المورد غير موجود.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "ValidationError": {
        "description": "فشل التحقق من جسم الطلب أو معاملاته.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/ProblemDetails"
                },
                {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FieldError"
                      }
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "RateLimited": {
        "description": "تم تجاوز حد المعدّل.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Reset": {
            "$ref": "#/components/headers/X-RateLimit-Reset"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Unavailable": {
        "description": "اعتمادية تابعة (خط المعالجة أو البث) غير متاحة.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "InternalError": {
        "description": "خطأ خادم غير معالَج.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      }
    },
    "schemas": {
      "ProblemDetails": {
        "type": "object",
        "description": "مستند مشكلة وفق RFC 9457.",
        "required": [
          "type",
          "title",
          "status",
          "request_id"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "معرّف ثابت للمشكلة (`https://maktaba.tv/problems/<slug>`).",
            "examples": [
              "https://maktaba.tv/problems/validation"
            ]
          },
          "title": {
            "type": "string",
            "description": "ملخص قصير مقروء للبشر."
          },
          "status": {
            "type": "integer",
            "minimum": 100,
            "maximum": 599
          },
          "detail": {
            "type": "string",
            "description": "شرح مقروء للبشر خاص بهذا الحدوث."
          },
          "instance": {
            "type": "string",
            "format": "uri-reference",
            "description": "معرّف URI للمورد الذي أنتج المشكلة."
          },
          "request_id": {
            "type": "string",
            "format": "uuid",
            "description": "معرّف ربط من نوع UUIDv7 (يطابق `X-Request-Id`)."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FieldError"
            },
            "description": "موجود عند إخفاقات التحقق."
          }
        }
      },
      "FieldError": {
        "type": "object",
        "required": [
          "field",
          "message"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "مسار منقّط إلى الحقل المخالف، مثل `roots[0]`."
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Page": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array"
          },
          "next": {
            "type": [
              "string",
              "null"
            ],
            "description": "مؤشر الصفحة التالية؛ `null` في الصفحة الأخيرة."
          }
        }
      },
      "AffectedCount": {
        "type": "object",
        "required": [
          "affected"
        ],
        "properties": {
          "affected": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "User": {
        "type": "object",
        "required": [
          "id",
          "username",
          "is_admin",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "username": {
            "type": "string"
          },
          "is_admin": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "LoginRequest": {
        "type": "object",
        "required": [
          "username",
          "password"
        ],
        "properties": {
          "username": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "password": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          }
        }
      },
      "RegisterRequest": {
        "type": "object",
        "required": [
          "username",
          "password"
        ],
        "properties": {
          "username": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "password": {
            "type": "string",
            "minLength": 8,
            "maxLength": 256
          },
          "invite_token": {
            "type": "string"
          }
        }
      },
      "AuthTokenResponse": {
        "type": "object",
        "required": [
          "user",
          "access_token",
          "token_type",
          "expires_in"
        ],
        "properties": {
          "user": {
            "$ref": "#/components/schemas/User"
          },
          "access_token": {
            "type": "string",
            "description": "رمز JWT قصير العمر (15 دقيقة)."
          },
          "refresh_token": {
            "type": "string",
            "description": "رمز معتم طويل الأمد. يُحذف لعملاء الويب (يُضبط عبر ملف تعريف ارتباط)."
          },
          "token_type": {
            "type": "string",
            "enum": [
              "Bearer"
            ]
          },
          "expires_in": {
            "type": "integer",
            "description": "مدة صلاحية `access_token` بالثواني.",
            "examples": [
              900
            ]
          }
        }
      },
      "Library": {
        "type": "object",
        "required": [
          "id",
          "name",
          "roots",
          "settings",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "roots": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "مسارات مطلقة في نظام الملفات."
          },
          "settings": {
            "type": "object",
            "additionalProperties": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "LibraryCreate": {
        "type": "object",
        "required": [
          "name",
          "roots"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "roots": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string"
            }
          },
          "settings": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "LibraryUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "roots": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "settings": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "LibraryStats": {
        "type": "object",
        "required": [
          "total_videos",
          "total_duration_sec",
          "by_state",
          "processed_pct",
          "by_language"
        ],
        "properties": {
          "total_videos": {
            "type": "integer"
          },
          "total_duration_sec": {
            "type": "number"
          },
          "processed_pct": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "by_state": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "by_language": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          }
        }
      },
      "VideoState": {
        "type": "string",
        "enum": [
          "discovered",
          "probed",
          "audio_extracted",
          "transcribed",
          "indexed",
          "ready",
          "failed"
        ]
      },
      "VideoSummary": {
        "type": "object",
        "required": [
          "id",
          "library_id",
          "title",
          "state",
          "playable",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "library_id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "detected_language": {
            "type": [
              "string",
              "null"
            ],
            "description": "رمز ISO 639-1."
          },
          "content_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "$ref": "#/components/schemas/VideoState"
          },
          "path": {
            "type": [
              "string",
              "null"
            ]
          },
          "playable": {
            "type": "boolean"
          },
          "duration_sec": {
            "type": [
              "number",
              "null"
            ]
          },
          "poster_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "VideoDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/VideoSummary"
          },
          {
            "type": "object",
            "properties": {
              "media_info": {
                "$ref": "#/components/schemas/MediaInfo"
              },
              "audio_tracks": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AudioTrack"
                }
              },
              "chapters": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Chapter"
                }
              },
              "tags": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Tag"
                }
              },
              "transcript_id": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uuid"
              },
              "playback_state": {
                "$ref": "#/components/schemas/PlaybackState"
              }
            }
          }
        ]
      },
      "VideoUpdate": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "maxLength": 512
          },
          "description": {
            "type": "string",
            "maxLength": 8192
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 64
            }
          },
          "content_type": {
            "type": "string"
          }
        }
      },
      "MediaInfo": {
        "type": "object",
        "properties": {
          "container": {
            "type": "string"
          },
          "video_codec": {
            "type": "string"
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "fps": {
            "type": "number"
          },
          "bitrate_kbps": {
            "type": "integer"
          },
          "has_subtitles": {
            "type": "boolean"
          },
          "duration_sec": {
            "type": "number"
          }
        }
      },
      "AudioTrack": {
        "type": "object",
        "required": [
          "id",
          "index"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "index": {
            "type": "integer"
          },
          "codec": {
            "type": "string"
          },
          "channels": {
            "type": "integer"
          },
          "sample_rate": {
            "type": "integer"
          },
          "language": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "is_default": {
            "type": "boolean"
          }
        }
      },
      "Segment": {
        "type": "object",
        "required": [
          "id",
          "seq",
          "start_sec",
          "end_sec",
          "text"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "seq": {
            "type": "integer"
          },
          "start_sec": {
            "type": "number"
          },
          "end_sec": {
            "type": "number"
          },
          "text": {
            "type": "string",
            "description": "معزول الاتجاه بالمحرفين U+2068 (FSI) وU+2069 (PDI)."
          },
          "speaker": {
            "type": [
              "string",
              "null"
            ]
          },
          "confidence": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 1
          },
          "words": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Word"
            }
          }
        }
      },
      "Word": {
        "type": "object",
        "required": [
          "seq",
          "start_sec",
          "end_sec",
          "text"
        ],
        "properties": {
          "seq": {
            "type": "integer"
          },
          "start_sec": {
            "type": "number"
          },
          "end_sec": {
            "type": "number"
          },
          "text": {
            "type": "string"
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        }
      },
      "SegmentWindow": {
        "type": "object",
        "required": [
          "items",
          "partial"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Segment"
            }
          },
          "next": {
            "type": [
              "string",
              "null"
            ]
          },
          "partial": {
            "type": "boolean",
            "description": "`true` عندما تبدأ النافذة بعد نهاية آخر مقطع."
          },
          "transcript_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          }
        }
      },
      "Subtitle": {
        "type": "object",
        "required": [
          "id",
          "language",
          "format",
          "source",
          "url",
          "expires_at"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "language": {
            "type": "string",
            "description": "رمز اللغة وفق ISO 639-1."
          },
          "format": {
            "type": "string",
            "enum": [
              "vtt",
              "srt",
              "ass",
              "embedded"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "auto",
              "external",
              "embedded"
            ]
          },
          "is_default": {
            "type": "boolean"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "عنوان URL موقّع على أصل البث."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Chapter": {
        "type": "object",
        "required": [
          "seq",
          "start_sec",
          "end_sec",
          "source"
        ],
        "properties": {
          "seq": {
            "type": "integer"
          },
          "start_sec": {
            "type": "number"
          },
          "end_sec": {
            "type": "number"
          },
          "title": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "embedded",
              "manual",
              "inferred"
            ]
          }
        }
      },
      "Tag": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "name": {
            "type": "string"
          }
        }
      },
      "Speaker": {
        "type": "object",
        "required": [
          "id",
          "library_id"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "library_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "JobStage": {
        "type": "string",
        "enum": [
          "scan",
          "probe",
          "extract",
          "transcribe",
          "subtitle_gen",
          "index",
          "thumbnail"
        ]
      },
      "JobState": {
        "type": "string",
        "enum": [
          "pending",
          "claimed",
          "running",
          "resuming",
          "paused",
          "done",
          "failed",
          "cancelled"
        ]
      },
      "Job": {
        "type": "object",
        "required": [
          "id",
          "video_id",
          "stage",
          "state",
          "priority",
          "attempts",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "video_id": {
            "type": "string",
            "format": "uuid"
          },
          "stage": {
            "$ref": "#/components/schemas/JobStage"
          },
          "state": {
            "$ref": "#/components/schemas/JobState"
          },
          "priority": {
            "type": "integer"
          },
          "attempts": {
            "type": "integer"
          },
          "pause_requested": {
            "type": "boolean"
          },
          "cancel_requested": {
            "type": "boolean"
          },
          "last_segment_end_sec": {
            "type": "number"
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          },
          "progress": {
            "$ref": "#/components/schemas/JobProgress"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "JobProgress": {
        "type": "object",
        "properties": {
          "pct": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "eta_sec": {
            "type": [
              "number",
              "null"
            ]
          },
          "rate": {
            "type": "number",
            "description": "وحدات خاصة بالمرحلة / ثانية."
          },
          "message": {
            "type": "string"
          }
        }
      },
      "QueueStats": {
        "type": "object",
        "required": [
          "by_stage",
          "total_pending",
          "oldest_job_age_sec"
        ],
        "properties": {
          "by_stage": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "total_pending": {
            "type": "integer"
          },
          "oldest_job_age_sec": {
            "type": "number"
          },
          "eta": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "تقدير الوقت المتبقي لكل مرحلة بالثواني."
          }
        }
      },
      "SearchRequest": {
        "type": "object",
        "required": [
          "q"
        ],
        "properties": {
          "q": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1024
          },
          "mode": {
            "type": "string",
            "enum": [
              "hybrid",
              "fts",
              "semantic"
            ],
            "default": "hybrid"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "default": 20
          },
          "offset": {
            "type": "integer",
            "minimum": 0
          },
          "cursor": {
            "type": "string"
          },
          "k": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50,
            "description": "حجم مجمّع المرشحين للدمج في الوضع الهجين."
          },
          "filters": {
            "$ref": "#/components/schemas/SearchFilters"
          }
        }
      },
      "SearchFilters": {
        "type": "object",
        "properties": {
          "language": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "library_id": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "speaker": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tag": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "duration_sec": {
            "type": "object",
            "properties": {
              "gte": {
                "type": "number"
              },
              "lte": {
                "type": "number"
              }
            }
          },
          "date": {
            "type": "object",
            "properties": {
              "gte": {
                "type": "string",
                "format": "date-time"
              },
              "lte": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      },
      "SearchHit": {
        "type": "object",
        "required": [
          "video_id",
          "score",
          "matches",
          "snippet"
        ],
        "properties": {
          "video_id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "score": {
            "type": "number"
          },
          "snippet": {
            "type": "string"
          },
          "matches": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchMatch"
            }
          }
        }
      },
      "SearchMatch": {
        "type": "object",
        "required": [
          "segment_id",
          "start_sec",
          "end_sec",
          "text"
        ],
        "properties": {
          "segment_id": {
            "type": "integer",
            "format": "int64"
          },
          "start_sec": {
            "type": "number"
          },
          "end_sec": {
            "type": "number"
          },
          "text": {
            "type": "string"
          },
          "speaker": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": [
          "hits",
          "total",
          "took_ms"
        ],
        "properties": {
          "hits": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchHit"
            }
          },
          "total": {
            "type": "integer"
          },
          "took_ms": {
            "type": "object",
            "required": [
              "total"
            ],
            "properties": {
              "fts": {
                "type": "integer"
              },
              "semantic": {
                "type": "integer"
              },
              "fusion": {
                "type": "integer"
              },
              "total": {
                "type": "integer"
              }
            }
          },
          "facets": {
            "$ref": "#/components/schemas/SearchFacets"
          },
          "degraded": {
            "type": "boolean",
            "description": "`true` عندما يعود الوضع الهجين إلى البحث النصي الكامل وحده."
          },
          "reason": {
            "type": "string"
          },
          "next": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "SearchFacets": {
        "type": "object",
        "properties": {
          "language": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FacetBucket"
            }
          },
          "library": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FacetBucket"
            }
          },
          "tag": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FacetBucket"
            }
          },
          "speaker": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FacetBucket"
            }
          }
        }
      },
      "FacetBucket": {
        "type": "object",
        "required": [
          "value",
          "count"
        ],
        "properties": {
          "value": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "SavedSearch": {
        "type": "object",
        "required": [
          "id",
          "name",
          "query",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "query": {
            "$ref": "#/components/schemas/SearchRequest"
          },
          "kind": {
            "type": "string",
            "enum": [
              "user",
              "smart_collection"
            ],
            "default": "user"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SavedSearchInput": {
        "type": "object",
        "required": [
          "name",
          "query"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "query": {
            "$ref": "#/components/schemas/SearchRequest"
          }
        }
      },
      "Collection": {
        "type": "object",
        "required": [
          "id",
          "name",
          "is_smart",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "is_smart": {
            "type": "boolean"
          },
          "smart_query": {
            "$ref": "#/components/schemas/SearchRequest"
          },
          "item_count": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CollectionCreate": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": {
            "type": "string",
            "maxLength": 1024
          },
          "is_smart": {
            "type": "boolean",
            "default": false
          },
          "smart_query": {
            "$ref": "#/components/schemas/SearchRequest"
          }
        }
      },
      "CollectionUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": {
            "type": "string",
            "maxLength": 1024
          },
          "smart_query": {
            "$ref": "#/components/schemas/SearchRequest"
          }
        }
      },
      "CollectionItem": {
        "type": "object",
        "required": [
          "collection_id",
          "video_id",
          "position"
        ],
        "properties": {
          "collection_id": {
            "type": "string",
            "format": "uuid"
          },
          "video_id": {
            "type": "string",
            "format": "uuid"
          },
          "position": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "PlaybackState": {
        "type": "object",
        "required": [
          "video_id",
          "position_sec",
          "completed",
          "updated_at"
        ],
        "properties": {
          "user_id": {
            "type": "string",
            "format": "uuid"
          },
          "video_id": {
            "type": "string",
            "format": "uuid"
          },
          "position_sec": {
            "type": "number",
            "minimum": 0
          },
          "completed": {
            "type": "boolean"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "source_session_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          }
        }
      },
      "PlaybackStateInput": {
        "type": "object",
        "required": [
          "position_sec"
        ],
        "properties": {
          "position_sec": {
            "type": "number",
            "minimum": 0
          },
          "completed": {
            "type": "boolean"
          }
        }
      },
      "SessionRequest": {
        "type": "object",
        "required": [
          "video_id"
        ],
        "properties": {
          "video_id": {
            "type": "string",
            "format": "uuid"
          },
          "client_profile": {
            "type": "string",
            "description": "تلميح لسُلّم المرمِّز (مثل `web` و`ios` و`tv-1080p`)."
          },
          "audio_track": {
            "type": "string",
            "description": "وسم لغة أو معرّف تدفق."
          },
          "subtitle_track": {
            "type": "string"
          },
          "start_sec": {
            "type": "number",
            "minimum": 0
          },
          "max_bitrate_kbps": {
            "type": "integer",
            "minimum": 100
          },
          "format": {
            "type": "string",
            "enum": [
              "hls",
              "dash",
              "direct"
            ]
          },
          "force_software": {
            "type": "boolean"
          },
          "force_transcode": {
            "type": "boolean"
          },
          "burn_subs": {
            "type": "boolean"
          },
          "accept_queue": {
            "type": "boolean"
          }
        }
      },
      "Session": {
        "type": "object",
        "required": [
          "session_id",
          "mode",
          "expires_at",
          "ladder",
          "current_rendition"
        ],
        "properties": {
          "session_id": {
            "type": "string",
            "format": "uuid"
          },
          "user_id": {
            "type": "string",
            "format": "uuid"
          },
          "video_id": {
            "type": "string",
            "format": "uuid"
          },
          "library_id": {
            "type": "string",
            "format": "uuid"
          },
          "mode": {
            "type": "string",
            "enum": [
              "direct",
              "remux",
              "transcode"
            ]
          },
          "manifest_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "direct_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "ladder": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Rung"
            }
          },
          "current_rendition": {
            "type": "string"
          },
          "duration_sec": {
            "type": "number",
            "description": "طول الفيديو في الفهرس (غائب عندما يكون غير معروف)."
          },
          "start_sec": {
            "type": "number",
            "description": "موضع بدء التدفق في الفيديو بالثواني (تحويل الترميز المفتوح عند `start_sec` يبدأ من هناك؛ وأوقاته هي أوقات الفيديو). غائب عند 0."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Rung": {
        "type": "object",
        "required": [
          "name",
          "kbps_cap",
          "width",
          "height",
          "codec"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "kbps_cap": {
            "type": "integer"
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "codec": {
            "type": "string"
          }
        }
      },
      "StreamCapabilities": {
        "type": "object",
        "required": [
          "codecs",
          "hwaccel",
          "max_bitrate_kbps",
          "supported_containers"
        ],
        "properties": {
          "codecs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "hwaccel": {
            "type": "string",
            "enum": [
              "videotoolbox",
              "vaapi",
              "nvenc",
              "qsv",
              "none"
            ]
          },
          "max_bitrate_kbps": {
            "type": "integer"
          },
          "supported_containers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "transcode_slots": {
            "type": "object",
            "properties": {
              "used": {
                "type": "integer"
              },
              "capacity": {
                "type": "integer"
              }
            }
          }
        }
      },
      "Settings": {
        "type": "object",
        "description": "الإعدادات الفعّالة (القيم الافتراضية ⊕ الملف ⊕ متغيرات البيئة ⊕ قاعدة البيانات). الأسرار محجوبة.",
        "additionalProperties": true,
        "properties": {
          "search": {
            "type": "object",
            "properties": {
              "fts_weight": {
                "type": "number"
              },
              "semantic_weight": {
                "type": "number"
              }
            }
          },
          "playback": {
            "type": "object",
            "properties": {
              "default_quality": {
                "type": "string"
              },
              "autoplay_next": {
                "type": "boolean"
              }
            }
          },
          "ui": {
            "type": "object",
            "properties": {
              "theme": {
                "type": "string",
                "enum": [
                  "light",
                  "dark",
                  "system"
                ]
              },
              "language": {
                "type": "string"
              }
            }
          }
        }
      },
      "SettingsInput": {
        "type": "object",
        "additionalProperties": true,
        "description": "الإعدادات المراد حفظها في طبقة قاعدة البيانات."
      },
      "SttBackend": {
        "type": "object",
        "required": [
          "name",
          "available"
        ],
        "properties": {
          "name": {
            "type": "string",
            "examples": [
              "whisper-mlx"
            ]
          },
          "available": {
            "type": "boolean"
          },
          "models": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cost_per_minute_usd": {
            "type": [
              "number",
              "null"
            ]
          },
          "notes": {
            "type": "string"
          }
        }
      },
      "Device": {
        "type": "object",
        "required": [
          "id",
          "platform",
          "bundle_id",
          "registered_at",
          "last_seen_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "platform": {
            "type": "string",
            "enum": [
              "ios",
              "android",
              "web"
            ]
          },
          "bundle_id": {
            "type": "string"
          },
          "push_token": {
            "type": [
              "string",
              "null"
            ],
            "description": "محجوب في استجابات السرد / الجلب؛ ولا يُعاد إلا عند التسجيل."
          },
          "app_version": {
            "type": "string"
          },
          "locale": {
            "type": "string"
          },
          "registered_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_seen_at": {
            "type": "string",
            "format": "date-time"
          },
          "revoked_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "DeviceRegisterInput": {
        "type": "object",
        "required": [
          "platform",
          "push_token",
          "bundle_id"
        ],
        "properties": {
          "platform": {
            "type": "string",
            "enum": [
              "ios",
              "android",
              "web"
            ]
          },
          "push_token": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096
          },
          "bundle_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "app_version": {
            "type": "string",
            "maxLength": 64
          },
          "locale": {
            "type": "string",
            "maxLength": 16
          }
        }
      },
      "Recommendation": {
        "type": "object",
        "required": [
          "video_id",
          "score",
          "reason"
        ],
        "properties": {
          "video_id": {
            "type": "string",
            "format": "uuid"
          },
          "score": {
            "type": "number"
          },
          "reason": {
            "type": "string",
            "examples": [
              "Because you watched X",
              "Recently added to Lectures"
            ]
          },
          "video": {
            "$ref": "#/components/schemas/VideoSummary"
          }
        }
      },
      "RecommendationsResponse": {
        "type": "object",
        "required": [
          "shelves"
        ],
        "properties": {
          "shelves": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "title",
                "items"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "examples": [
                    "continue_watching"
                  ]
                },
                "title": {
                  "type": "string"
                },
                "items": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Recommendation"
                  }
                }
              }
            }
          }
        }
      },
      "Health": {
        "type": "object",
        "required": [
          "status",
          "components",
          "checked_at"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "degraded",
              "down"
            ]
          },
          "components": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "required": [
                "status"
              ],
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "ok",
                    "degraded",
                    "down"
                  ]
                },
                "detail": {
                  "type": "string"
                },
                "latency_ms": {
                  "type": "number"
                }
              }
            }
          },
          "checked_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Version": {
        "type": "object",
        "required": [
          "version",
          "build_sha",
          "build_time",
          "go_version",
          "schema_revision"
        ],
        "properties": {
          "version": {
            "type": "string",
            "examples": [
              "0.1.0-rc.3"
            ]
          },
          "build_sha": {
            "type": "string"
          },
          "build_time": {
            "type": "string",
            "format": "date-time"
          },
          "go_version": {
            "type": "string"
          },
          "schema_revision": {
            "type": "integer"
          }
        }
      },
      "WsMessage": {
        "type": "object",
        "description": "غلاف كل رسالة WebSocket من الخادم إلى العميل.\nيتبع `type` الشكل `<channel>.<event>` (مثل `jobs.progress` و\n`playback.completed` و`library.updated`).\n",
        "required": [
          "type",
          "data",
          "at"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "subscribe",
              "unsubscribe",
              "jobs.new",
              "jobs.flag_set",
              "jobs.progress",
              "jobs.state_changed",
              "jobs.done",
              "playback.progress",
              "playback.completed",
              "library.updated",
              "videos.state_changed",
              "videos.new",
              "profiles_changed",
              "health_changed",
              "error"
            ]
          },
          "data": {
            "description": "حمولة خاصة بالحدث. راجع مخططات كل حدث أدناه.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/WsSubscribe"
              },
              {
                "$ref": "#/components/schemas/WsJobEvent"
              },
              {
                "$ref": "#/components/schemas/WsPlaybackEvent"
              },
              {
                "$ref": "#/components/schemas/WsLibraryEvent"
              },
              {
                "$ref": "#/components/schemas/WsVideoEvent"
              },
              {
                "$ref": "#/components/schemas/WsErrorEvent"
              }
            ]
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WsSubscribe": {
        "type": "object",
        "properties": {
          "channels": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "jobs",
                "playback",
                "library",
                "system"
              ]
            }
          }
        }
      },
      "WsJobEvent": {
        "type": "object",
        "required": [
          "job_id"
        ],
        "properties": {
          "job_id": {
            "type": "integer",
            "format": "int64"
          },
          "video_id": {
            "type": "string",
            "format": "uuid"
          },
          "stage": {
            "$ref": "#/components/schemas/JobStage"
          },
          "state": {
            "$ref": "#/components/schemas/JobState"
          },
          "progress": {
            "$ref": "#/components/schemas/JobProgress"
          },
          "error": {
            "type": "string"
          }
        }
      },
      "WsPlaybackEvent": {
        "type": "object",
        "required": [
          "video_id",
          "position_sec"
        ],
        "properties": {
          "user_id": {
            "type": "string",
            "format": "uuid"
          },
          "video_id": {
            "type": "string",
            "format": "uuid"
          },
          "session_id": {
            "type": "string",
            "format": "uuid"
          },
          "position_sec": {
            "type": "number"
          },
          "completed": {
            "type": "boolean"
          }
        }
      },
      "WsLibraryEvent": {
        "type": "object",
        "required": [
          "library_id"
        ],
        "properties": {
          "library_id": {
            "type": "string",
            "format": "uuid"
          },
          "change": {
            "type": "string",
            "enum": [
              "created",
              "updated",
              "deleted",
              "scan_started",
              "scan_finished"
            ]
          },
          "stats": {
            "$ref": "#/components/schemas/LibraryStats"
          }
        }
      },
      "WsVideoEvent": {
        "type": "object",
        "required": [
          "video_id",
          "state"
        ],
        "properties": {
          "video_id": {
            "type": "string",
            "format": "uuid"
          },
          "library_id": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "$ref": "#/components/schemas/VideoState"
          }
        }
      },
      "WsErrorEvent": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "QueueJobRef": {
        "type": "object",
        "description": "مهمة كما تظهر في عروض طوابير المهام (REST وSSE).",
        "required": [
          "id",
          "stage",
          "state",
          "subject_kind",
          "subject_id",
          "subject_label",
          "library_id",
          "priority",
          "attempts",
          "max_attempts",
          "outcome",
          "error_cause",
          "created_at",
          "started_at",
          "finished_at",
          "progress"
        ],
        "properties": {
          "id": {
            "type": "integer"
          },
          "stage": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "subject_kind": {
            "type": "string"
          },
          "subject_id": {
            "type": "string"
          },
          "subject_label": {
            "type": "string"
          },
          "library_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "priority": {
            "type": "integer"
          },
          "attempts": {
            "type": "integer"
          },
          "max_attempts": {
            "type": "integer"
          },
          "outcome": {
            "type": [
              "string",
              "null"
            ]
          },
          "error_cause": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "started_at": {
            "oneOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "finished_at": {
            "oneOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "progress": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          }
        }
      },
      "QueueEdge": {
        "type": "object",
        "description": "حافة واحدة من مخطط المراحل.",
        "required": [
          "to",
          "map",
          "when",
          "legacy"
        ],
        "properties": {
          "to": {
            "type": "string"
          },
          "map": {
            "type": "string"
          },
          "when": {
            "type": "string"
          },
          "legacy": {
            "type": "boolean"
          }
        }
      },
      "QueueStageInfo": {
        "type": "object",
        "description": "صف من `job_stages` مع الحقل المحسوب `fed_by`.",
        "required": [
          "stage",
          "label",
          "lane",
          "lane_order",
          "subject_kinds",
          "pool",
          "version",
          "legacy",
          "hidden",
          "external_write",
          "write_mode",
          "enabled",
          "disabled_reason",
          "paused",
          "paused_at",
          "paused_by",
          "debounce_sec",
          "edges",
          "may_request",
          "entry_for",
          "fed_by",
          "extension",
          "graph_synced_at"
        ],
        "properties": {
          "stage": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "lane": {
            "type": "string"
          },
          "lane_order": {
            "type": "integer"
          },
          "subject_kinds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pool": {
            "type": "string"
          },
          "version": {
            "type": "integer"
          },
          "legacy": {
            "type": "boolean"
          },
          "hidden": {
            "type": "boolean"
          },
          "external_write": {
            "type": "boolean"
          },
          "write_mode": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "disabled_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "paused": {
            "type": "boolean"
          },
          "paused_at": {
            "oneOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "paused_by": {
            "type": [
              "string",
              "null"
            ]
          },
          "debounce_sec": {
            "type": "integer"
          },
          "edges": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QueueEdge"
            }
          },
          "may_request": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "entry_for": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "fed_by": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "extension": {
            "type": [
              "string",
              "null"
            ]
          },
          "graph_synced_at": {
            "oneOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "WorkerPool": {
        "type": "object",
        "description": "مجمّع عمال مع الاستخدام الحي.",
        "required": [
          "pool",
          "label",
          "scope",
          "size",
          "effective_size",
          "busy",
          "stages",
          "updated_at",
          "updated_by"
        ],
        "properties": {
          "pool": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "scope": {
            "type": "string"
          },
          "size": {
            "type": [
              "integer",
              "null"
            ]
          },
          "effective_size": {
            "type": "integer"
          },
          "busy": {
            "type": "integer"
          },
          "stages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_by": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "QueueCounts": {
        "type": "object",
        "description": "عدّادات لكل مرحلة.",
        "required": [
          "pending",
          "ready",
          "running",
          "paused",
          "failed_open",
          "done_24h",
          "skipped_24h",
          "awaiting_review"
        ],
        "properties": {
          "pending": {
            "type": "integer"
          },
          "ready": {
            "type": "integer"
          },
          "running": {
            "type": "integer"
          },
          "paused": {
            "type": "integer"
          },
          "failed_open": {
            "type": "integer"
          },
          "done_24h": {
            "type": "integer"
          },
          "skipped_24h": {
            "type": "integer"
          },
          "awaiting_review": {
            "type": "integer"
          }
        }
      },
      "QueueSummary": {
        "type": "object",
        "description": "بيانات بطاقة كل مرحلة (المقياس، والمعدّل، والوقت المتبقي، وسبب الانتظار، وتغطية العمال).",
        "required": [
          "stage",
          "counts",
          "wave",
          "rate_per_min",
          "eta_sec",
          "oldest_waiting_sec",
          "waiting_reason",
          "running_jobs",
          "served_by",
          "served_workers",
          "no_worker",
          "extension"
        ],
        "properties": {
          "stage": {
            "type": "string"
          },
          "counts": {
            "$ref": "#/components/schemas/QueueCounts"
          },
          "wave": {
            "type": "object",
            "additionalProperties": true
          },
          "rate_per_min": {
            "type": "number"
          },
          "eta_sec": {
            "type": [
              "number",
              "null"
            ]
          },
          "oldest_waiting_sec": {
            "type": [
              "number",
              "null"
            ]
          },
          "waiting_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "running_jobs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QueueJobRef"
            }
          },
          "served_by": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "served_workers": {
            "type": "integer"
          },
          "no_worker": {
            "type": "boolean"
          },
          "extension": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "QueueFlow": {
        "type": "object",
        "description": "حركة الإطلاق بين مرحلتين.",
        "required": [
          "from",
          "to",
          "per_min"
        ],
        "properties": {
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          },
          "per_min": {
            "type": "number"
          }
        }
      },
      "QueueHealth": {
        "type": "object",
        "description": "شريط الصحة.",
        "required": [
          "nas",
          "cpu",
          "network",
          "backlog",
          "spark"
        ],
        "properties": {
          "nas": {
            "type": "object",
            "additionalProperties": true
          },
          "cpu": {
            "type": "object",
            "additionalProperties": true
          },
          "network": {
            "type": "object",
            "additionalProperties": true
          },
          "backlog": {
            "type": "object",
            "additionalProperties": true
          },
          "spark": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "QueuesSnapshot": {
        "type": "object",
        "description": "كل ما تحتاجه النظرة العامة؛ وهو أيضًا حمولة SSE `queues.snapshot`.",
        "required": [
          "at",
          "paused_all",
          "stages",
          "queues",
          "pools",
          "flows",
          "health",
          "issues_count"
        ],
        "properties": {
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "paused_all": {
            "type": "boolean"
          },
          "stages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QueueStageInfo"
            }
          },
          "queues": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QueueSummary"
            }
          },
          "pools": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WorkerPool"
            }
          },
          "flows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QueueFlow"
            }
          },
          "health": {
            "$ref": "#/components/schemas/QueueHealth"
          },
          "issues_count": {
            "type": "integer"
          }
        }
      },
      "QueueRatePoint": {
        "type": "object",
        "description": "دلو واحد مدته 10 دقائق.",
        "required": [
          "t",
          "done",
          "failed",
          "skipped",
          "nas_timeouts"
        ],
        "properties": {
          "t": {
            "type": "string",
            "format": "date-time"
          },
          "done": {
            "type": "integer"
          },
          "failed": {
            "type": "integer"
          },
          "skipped": {
            "type": "integer"
          },
          "nas_timeouts": {
            "type": "integer"
          }
        }
      },
      "QueueDetail": {
        "type": "object",
        "description": "صفحة طابور واحدة.",
        "required": [
          "info",
          "summary",
          "kpis",
          "running",
          "next_up",
          "failures",
          "log"
        ],
        "properties": {
          "info": {
            "$ref": "#/components/schemas/QueueStageInfo"
          },
          "summary": {
            "$ref": "#/components/schemas/QueueSummary"
          },
          "kpis": {
            "type": "object",
            "additionalProperties": true
          },
          "running": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QueueJobRef"
            }
          },
          "next_up": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QueueJobRef"
            }
          },
          "failures": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FailureGroup"
            }
          },
          "log": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QueueLogLine"
            }
          }
        }
      },
      "FailureGroup": {
        "type": "object",
        "description": "الإخفاقات المفتوحة لمرحلة مجمّعة حسب السبب الموحَّد (إضافة إلى `awaiting_review` و`stale_graph`).",
        "required": [
          "stage",
          "cause",
          "label",
          "count",
          "first_at",
          "last_at",
          "sample_message",
          "sample_subjects",
          "action"
        ],
        "properties": {
          "stage": {
            "type": "string"
          },
          "cause": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "first_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_at": {
            "type": "string",
            "format": "date-time"
          },
          "sample_message": {
            "type": "string"
          },
          "sample_subjects": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "action": {
            "type": "string"
          }
        }
      },
      "QueueLogLine": {
        "type": "object",
        "description": "صف واحد من `job_events`.",
        "required": [
          "id",
          "at",
          "job_id",
          "stage",
          "subject_kind",
          "subject_id",
          "subject_label",
          "level",
          "kind",
          "message",
          "data"
        ],
        "properties": {
          "id": {
            "type": "integer"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "job_id": {
            "type": "integer"
          },
          "stage": {
            "type": "string"
          },
          "subject_kind": {
            "type": "string"
          },
          "subject_id": {
            "type": "string"
          },
          "subject_label": {
            "type": "string"
          },
          "level": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          }
        }
      },
      "RetriggerRequest": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "maxItems": 5000,
            "items": {
              "type": "object",
              "required": [
                "subject_kind",
                "subject_id"
              ],
              "properties": {
                "subject_kind": {
                  "type": "string",
                  "enum": [
                    "video",
                    "library",
                    "series",
                    "season",
                    "catalog"
                  ]
                },
                "subject_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "stage": {
                  "type": "string"
                }
              }
            }
          },
          "mode": {
            "type": "string",
            "enum": [
              "queue",
              "force",
              "force_cascade"
            ],
            "default": "queue"
          },
          "priority": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000,
            "default": 50
          }
        }
      },
      "RetriggerResponse": {
        "type": "object",
        "required": [
          "results"
        ],
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "subject_kind": {
                  "type": "string"
                },
                "subject_id": {
                  "type": "string"
                },
                "stage": {
                  "type": "string"
                },
                "job_id": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "outcome": {
                  "type": "string",
                  "enum": [
                    "inserted",
                    "coalesced",
                    "rerun_requested",
                    "disabled",
                    "unknown_stage",
                    "invalid_subject"
                  ]
                }
              }
            }
          }
        }
      },
      "QueueItemHistory": {
        "type": "object",
        "description": "تاريخ عنصر واحد وخيارات إعادته إلى الطابور.",
        "required": [
          "subject",
          "kinds",
          "queues",
          "appears_in",
          "timeline",
          "next"
        ],
        "properties": {
          "subject": {
            "type": "object",
            "additionalProperties": true
          },
          "kinds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "queues": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "appears_in": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "timeline": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "next": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "LibraryQueueRow": {
        "type": "object",
        "description": "صف واحد من جدول المكتبات.",
        "required": [
          "library_id",
          "name",
          "videos",
          "seasons",
          "strip",
          "last_activity_at"
        ],
        "properties": {
          "library_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "videos": {
            "type": "integer"
          },
          "seasons": {
            "type": "integer"
          },
          "strip": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "last_activity_at": {
            "oneOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "HealthSeries": {
        "type": "object",
        "description": "مقياس صحة واحد عبر الزمن (`nas.open_ms_p95` و`cpu.pct` و`net.plex_ms` و`backlog.ready` و...).",
        "required": [
          "metric",
          "points"
        ],
        "properties": {
          "metric": {
            "type": "string"
          },
          "points": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "QueueWorker": {
        "type": "object",
        "description": "عامل مسجّل.",
        "required": [
          "worker_id",
          "host",
          "online",
          "last_seen_at",
          "serves",
          "serves_label",
          "pools",
          "started_at",
          "version"
        ],
        "properties": {
          "worker_id": {
            "type": "string"
          },
          "host": {
            "type": "string"
          },
          "online": {
            "type": "boolean"
          },
          "last_seen_at": {
            "type": "string",
            "format": "date-time"
          },
          "serves": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "serves_label": {
            "type": "string"
          },
          "pools": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "started_at": {
            "type": "string",
            "format": "date-time"
          },
          "version": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ExtensionInfo": {
        "type": "object",
        "description": "امتداد اختياري (Plex وdizqueTV). لا تُعاد الإعدادات السرية أبدًا.",
        "required": [
          "name",
          "label",
          "description",
          "version",
          "enabled",
          "configured",
          "settings_schema",
          "settings",
          "secrets_set"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "configured": {
            "type": "boolean"
          },
          "settings_schema": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "settings": {
            "type": "object",
            "additionalProperties": true
          },
          "secrets_set": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "requestBodies": {
      "WsClientMessage": {
        "description": "غلاف JSON يُرسل من العميل إلى الخادم عبر WebSocket. استخدم `subscribe` / `unsubscribe`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/WsMessage"
            }
          }
        }
      }
    }
  }
}