Специфікації протоколів платформи
Каталог протоколів платформи повідомляє авторам SDK, агентам, операторам і стороннім інструментам, яка саме машиночитана специфікація визначає кожен публічний інтерфейс Durable Workflow.
Для автоматизації використовуйте машиночитаний каталог. Кожен доступний запис має стабільний ідентифікатор специфікації та публічну URL-адресу HTTPS, що веде безпосередньо до артефакту OpenAPI, AsyncAPI або JSON Schema.
Шляхи репозиторію, символи реалізації та тестові фікстури виключені з опублікованого каталогу й збережені лише для діагностики перевірок. Джерелом істини для споживачів є опубліковані специфікації.
Ідентичність і виявлення каталогу
Машинозчитуване авторитетне джерело опубліковано за адресою /platform-protocol-specs.json зі схемою durable-workflow.v2.platform-protocol-specs.catalog, версією 16.
Каталог також доступний через:
- публічний каталог JSON за адресою https://durable-workflow.github.io/platform-protocol-specs.json;
- platform_protocol_specs у GET /api/cluster/info окремого Server;
- цей посібник 2.0 для пояснень читачам.
URL-адреса JSON є джерелом істини каталогу для машинного використання. Server повторно публікує той самий каталог, щоб клієнти виявляли активні інтерфейси протоколів без припущень щодо структури репозиторію.
Ролі авторитетних джерел протоколу worker
Виявлення можливостей середовища виконання та перевірка відповідності використовують окремі авторитетні джерела протоколу. Обирайте рядок для свого завдання. Однакова мітка версії не робить версіоноване історичне джерело псевдонімом неверсіонованого авторитетного джерела Server.
| Роль | Поточний маркер | Авторитетне джерело |
|---|---|---|
| Поточний опублікований протокол Server | worker_protocol.version = 1.20 | Неверсіоновані дзеркала на основі Server: OpenAPI · AsyncAPI |
| Поточна ціль перевірки відповідності Workflow | Набір 47 перевіряє протокол 1.19 | Версіоновані тестові дані, прив’язані до digest: OpenAPI · AsyncAPI |
| Збережені історичні прив’язки відповідності | Прив’язки з позначкою historical для протоколів 1.13, 1.15, 1.16, 1.17, 1.18 | Незмінні записи джерел і digest у маніфесті відповідності |
Поля для споживачів
Кожен запис надає такий контракт:
| Поле | Значення |
|---|---|
| spec_id | Стабільний ідентифікатор протоколу Durable Workflow. Опубліковані документи містять відповідну ідентичність. |
| spec_url | Пряма публічна URL-адреса HTTPS машиночитаної специфікації. |
| format | openapi, json_schema або asyncapi. |
| status | Чи опублікований артефакт, розробляється або планується. |
| surface_family | Сімейство політики сумісності, що визначає інтерфейс. |
| authority_manifest | Маніфест виявлення, через який runtime оголошує інтерфейс. |
| owner_repo | Проєкт, відповідальний за специфікацію. |
| object_families | Назви публічних сімейств об’єктів та їхні проєкти-власники. |
| evolution_rule | Правило сумісності додаткових і несумісних змін. |
| breaking_change_release | Межа випуску, потрібна за цим правилом розвитку. |
Споживачі мають відкривати spec_url і звіряти ідентичність документа зі spec_id. Доступ до вихідного checkout не потрібен.
Доступні специфікації
Цей перелік формується з публічного каталогу JSON. Ідентичність специфікації, доступність, публічні посилання й власники сімейств об’єктів залишаються даними каталогу.
control_plane_api
- Ідентифікатор специфікації
durable-workflow.v2.control-plane-api- Публічна специфікація
- https://durable-workflow.github.io/platform-protocol-specs/control-plane-api.openapi.yaml
- Формат і стан
openapi·published- Контракт власника
durable-workflow/server
Сімейства об’єктів та контракти власників
control_plane_request_contract—durable-workflow/servercontrol_plane_response_envelope—durable-workflow/servercontrol_plane_operation_contract—durable-workflow/server
worker_protocol_api
- Ідентифікатор специфікації
durable-workflow.v2.worker-protocol-api- Публічна специфікація
- https://durable-workflow.github.io/platform-protocol-specs/worker-protocol-api.openapi.yaml
- Формат і стан
openapi·published- Контракт власника
durable-workflow/server
Сімейства об’єктів та контракти власників
worker_registration_request—durable-workflow/serverworker_deregistration_result—durable-workflow/serverworker_task_poll_request—durable-workflow/serverworker_task_result—durable-workflow/serverworker_query_task_poll_request—durable-workflow/serverworker_query_task_result—durable-workflow/serverexternal_task_input_contract—durable-workflow/serverexternal_task_result_contract—durable-workflow/server
worker_protocol_stream
- Ідентифікатор специфікації
durable-workflow.v2.worker-protocol-stream- Публічна специфікація
- https://durable-workflow.github.io/platform-protocol-specs/worker-protocol-stream.asyncapi.yaml
- Формат і стан
asyncapi·published- Контракт власника
durable-workflow/server
Сімейства об’єктів та контракти власників
worker_poll_stream—durable-workflow/serverworker_task_lease—durable-workflow/serverworker_task_heartbeat—durable-workflow/server
worker_sessions_runtime
- Ідентифікатор специфікації
durable-workflow.v2.worker-sessions-runtime- Публічна специфікація
- https://durable-workflow.github.io/platform-protocol-specs/worker-sessions-runtime.schema.json
- Формат і стан
json_schema·published- Контракт власника
durable-workflow/server
Сімейства об’єктів та контракти власників
worker_session_runtime_contract—durable-workflow/workflowworker_session_options—durable-workflow/workflowworker_session_lifecycle—durable-workflow/serverworker_session_visibility—durable-workflow/server
local_activity_runtime
- Ідентифікатор специфікації
durable-workflow.v2.local-activity-runtime- Публічна специфікація
- https://durable-workflow.github.io/platform-protocol-specs/local-activity-runtime.schema.json
- Формат і стан
json_schema·published- Контракт власника
durable-workflow/workflow
Сімейства об’єктів та контракти власників
local_activity_runtime_contract—durable-workflow/workflowlocal_activity_options—durable-workflow/workflowlocal_activity_history_markers—durable-workflow/workflowlocal_activity_visibility—durable-workflow/workflow
history_event_payloads
- Ідентифікатор специфікації
durable-workflow.v2.history-event-payloads- Публічна специфікація
- https://durable-workflow.github.io/platform-protocol-specs/history-event-payloads.schema.json
- Формат і стан
json_schema·published- Контракт власника
durable-workflow/workflow
Сімейства об’єктів та контракти власників
workflow_history_events—durable-workflow/workflowworkflow_schedule_history_events—durable-workflow/workflow
history_export_bundle
- Ідентифікатор специфікації
durable-workflow.v2.history-export-bundle- Публічна специфікація
- https://durable-workflow.github.io/platform-protocol-specs/history-export-bundle.schema.json
- Формат і стан
json_schema·published- Контракт власника
durable-workflow/workflow
Сімейства об’єктів та контракти власників
history_export_bundle—durable-workflow/workflow
replay_bundle
- Ідентифікатор специфікації
durable-workflow.v2.replay-bundle- Публічна специфікація
- https://durable-workflow.github.io/platform-protocol-specs/replay-bundle.schema.json
- Формат і стан
json_schema·published- Контракт власника
durable-workflow/workflow
Сімейства об’єктів та контракти власників
replay_bundle—durable-workflow/workflow
waterline_read_api
- Ідентифікатор специфікації
durable-workflow.v2.waterline-read-api- Публічна специфікація
- https://durable-workflow.github.io/platform-protocol-specs/waterline-read-api.openapi.yaml
- Формат і стан
openapi·published- Контракт власника
durable-workflow/waterline
Сімейства об’єктів та контракти власників
waterline_read_envelope—durable-workflow/waterlinewaterline_operator_action_envelope—durable-workflow/waterline
waterline_diagnostic_objects
- Ідентифікатор специфікації
durable-workflow.v2.waterline-diagnostic-objects- Публічна специфікація
- https://durable-workflow.github.io/platform-protocol-specs/waterline-diagnostic-objects.schema.json
- Формат і стан
json_schema·published- Контракт власника
durable-workflow/waterline
Сімейства об’єктів та контракти власників
waterline_run_detail—durable-workflow/waterlinewaterline_health_diagnostics—durable-workflow/waterlinewaterline_timeline_rows—durable-workflow/waterlinewaterline_lineage_edges—durable-workflow/waterline
repair_actionability_objects
- Ідентифікатор специфікації
durable-workflow.v2.repair-actionability-objects- Публічна специфікація
- https://durable-workflow.github.io/platform-protocol-specs/repair-actionability-objects.schema.json
- Формат і стан
json_schema·published- Контракт власника
durable-workflow/workflow
Сімейства об’єктів та контракти власників
task_repair_policy—durable-workflow/workflowtask_repair_candidates—durable-workflow/workflowoperator_queue_visibility—durable-workflow/workflowactionability—durable-workflow/waterlineagent_root_cause—durable-workflow/durable-workflow.github.ioagent_remediation—durable-workflow/durable-workflow.github.iosafe_mutation—durable-workflow/durable-workflow.github.io
cli_json_envelopes
- Ідентифікатор специфікації
durable-workflow.v2.cli-json-envelopes- Публічна специфікація
- https://durable-workflow.github.io/platform-protocol-specs/cli-json-envelopes.schema.json
- Формат і стан
json_schema·published- Контракт власника
durable-workflow/cli
Сімейства об’єктів та контракти власників
cli_output_schema_manifest—durable-workflow/clicli_command_output_schema—durable-workflow/cli
mcp_discovery
- Ідентифікатор специфікації
durable-workflow.v2.mcp-discovery- Публічна специфікація
- https://durable-workflow.github.io/platform-protocol-specs/mcp-discovery.schema.json
- Формат і стан
json_schema·published- Контракт власника
durable-workflow/durable-workflow.github.io
Сімейства об’єктів та контракти власників
mcp_tool_discovery—durable-workflow/durable-workflow.github.iollms_txt_discovery—durable-workflow/durable-workflow.github.io
mcp_tool_results
- Ідентифікатор специфікації
durable-workflow.v2.mcp-tool-results- Публічна специфікація
- https://durable-workflow.github.io/platform-protocol-specs/mcp-tool-results.schema.json
- Формат і стан
json_schema·published- Контракт власника
durable-workflow/durable-workflow.github.io
Сімейства об’єктів та контракти власників
mcp_tool_result_envelope—durable-workflow/durable-workflow.github.ioagent_root_cause—durable-workflow/durable-workflow.github.ioagent_remediation—durable-workflow/durable-workflow.github.iosafe_mutation—durable-workflow/durable-workflow.github.io
cluster_info_envelope
- Ідентифікатор специфікації
durable-workflow.v2.cluster-info-envelope- Публічна специфікація
- https://durable-workflow.github.io/platform-protocol-specs/cluster-info-envelope.schema.json
- Формат і стан
json_schema·published- Контракт власника
durable-workflow/server
Сімейства об’єктів та контракти власників
cluster_info_envelope—durable-workflow/serverclient_compatibility_manifest—durable-workflow/serversurface_stability_contract—durable-workflow/workflowplatform_protocol_specs_catalog—durable-workflow/workflowplatform_conformance_suite_manifest—durable-workflow/workflowsdk_neutrality_contract—durable-workflow/workflow
invocable_carrier_execution
- Ідентифікатор специфікації
durable-workflow.v2.invocable-carrier-execution- Публічна специфікація
- https://durable-workflow.github.io/platform-protocol-specs/invocable-carrier-execution.schema.json
- Формат і стан
json_schema·in_progress- Контракт власника
durable-workflow/server
Сімейства об’єктів та контракти власників
invocable_carrier_contract—durable-workflow/serverexternal_execution_surface_contract—durable-workflow/serverexternal_executor_config_contract—durable-workflow/server
Примітки runtime сеансів worker
Ця схема охоплює виявлення можливостей сеансів worker, конверти життєвого циклу, знімки спорідненості завдань і видимість оператора. Її стабільний ідентифікатор — durable-workflow.v2.worker-sessions-runtime.
Примітки runtime локальних activity
Ця схема охоплює виявлення можливостей локальних activity, знімки параметрів, маркери історії, семантику повторних спроб і видимість оператора. Її стабільний ідентифікатор — durable-workflow.v2.local-activity-runtime.
Примітки конверта cluster-info
Ця схема охоплює GET /api/cluster/info та вкладені маніфести виявлення, доступні через цей endpoint. Її стабільний ідентифікатор — durable-workflow.v2.cluster-info-envelope.
Формати
| Формат | Використання |
|---|---|
| OpenAPI 3.1 | Інтерфейси запиту/відповіді HTTP та JSON, де маршрути, методи, коди статусу й конверти є частиною контракту. |
| JSON Schema 2020-12 | Збережені записи, payload подій, конверти результатів, параметри runtime й пов’язані сімейства об’єктів. |
| AsyncAPI 2.6 або новіший | Семантика опитування, потоків, поновлення оренди, порядку й доставки. |
Рівні статусу
| Статус | Значення |
|---|---|
| published | Публічна машиночитана специфікація доступна за spec_url і придатна до прямого використання. |
| in_progress | Публічна специфікація доступна, але її покриття часткове. Перелічені поля й маршрути є нормативними. |
| planned | Запис має стабільну ідентичність каталогу, але ще не має придатної до використання специфікації. Заплановані записи не оголошують spec_url. |
Правила розвитку
additive_minor_breaking_major дозволяє додаткові зміни в мінорних випусках. Вилучення, перейменування, звуження типів і семантичні зміни потребують мажорного випуску й за можливості паралельного маршруту чи поля.
parallel_primitive_only визначає заморожені формати передавання. Несумісну форму потрібно вводити під новим типом події, типом команди або ідентифікатором схеми, зберігаючи декодування початкової форми.
experimental_any_release застосовується лише до явно експериментальних специфікацій і дозволяє зміну в будь-якому випуску.
Перевірка випуску
CI сайту документації забезпечує такі машинні перевірки:
| Перевірка | Що перевіряє CI |
|---|---|
| catalog_aligned_with_surface_families | Кожен запис посилається на оголошене публічне сімейство сумісності. |
| owner_repo_known | Власники записів і сімейств об’єктів використовують словник каталогу. |
| format_known | Кожен доступний артефакт розбирається як оголошений формат. |
| public_spec_references_resolve | Кожна доступна spec_url є HTTPS-адресою в публічному просторі специфікацій протоколів і веде до артефакту випуску, ідентичність якого відповідає spec_id. |
| repository_local_authority_fields_rejected | Опубліковані записи не містять локальних шляхів репозиторію, символів реалізації, посилань на тести або старих полів джерела істини. |
| workflow_package_mirror_aligned | Публічний каталог відповідає каталогу пакета Workflow, коли цей вхід випуску доступний. |
| server_owned_spec_mirrors_aligned | Опубліковані артефакти Server відповідають копіям репозиторію-власника, коли ці входи доступні. |
| diagnostic_provenance_complete | Дані походження лише для перевірки охоплюють кожен запис каталогу й сімейство об’єктів. |
| object_family_metadata_declared | Записи каталогу й опубліковані документи погоджені щодо назв сімейств об’єктів та власників. |
| rendered_retrieval_surfaces_aligned | Зібрана сторінка 2.0 і повні пакети отримання даних моделлю 2.0 показують ідентичність каталогу, публічну URL-адресу й власника сімейства об’єктів кожного доступного запису. |
| breaking_change_release_consistent_with_evolution_rule | Кожне значення випуску несумісної зміни відповідає правилу розвитку. |
| deliverable_specs_published | Кожен потрібний інтерфейс платформи має опубліковану специфікацію, придатну до розбору. |
Машинна перевірка завантажує публічний каталог JSON, перевіряє його словник і безпечні для споживача посилання, розбирає специфікації випуску, перевіряє метадані сімейств об’єктів та вбудованих схем і порівнює копії пакетів, коли вони доступні. Після створення сайту й пакетів для моделей семантична перевірка порівнює відображені значення каталогу з тим самим джерелом JSON. Текст пояснень і заголовків не входить до порівняння.
Коли контракт змінюється, оновлюйте разом каталог пакета Workflow, цю публічну копію JSON і відповідні опубліковані артефакти специфікацій. Людське рецензування підтверджує корисність пояснень, не роблячи їх машинним джерелом істини.
Перейдіть до набору перевірок відповідності платформи, щоб знайти активні фікстури з прив’язкою до байтів, які перевіряють ці специфікації протоколів. Історичні докази фікстур позначені окремо й не замінюють поточного джерела істини каталогу.