Уточнить DSH, плагины, roadmap и контракты исполнения

designDocument/api/runs-api.md

@@ -13,14 +13,14 @@
 | POST /v1/runs/{id}/cancel | reason? | 202 Run | Идемпотентная команда; terminal run → 409 |
 | POST /v1/runs/{id}/retry | acknowledgedExternalEffects:boolean | 202 новый Run | parentRunId, новый ключ, проверка policy |
 | POST /v1/runs/{id}/responses | responseId, inputRequestId, value | 202 Run | Только waiting_input; схема ответа и права |
-| POST /v1/schedules | agentId, cron, timezone, overlapPolicy | 201 Schedule | operator; cron и timezone валидируются |
-| PATCH /v1/schedules/{id} | cron?, timezone?, enabled?, overlapPolicy?; If-Match | 200 Schedule | 412 conflict |
+| POST /v1/schedules | agentId, agentRevision, cron, timezone, overlapPolicy, misfirePolicy? | 201 Schedule | operator; cron и timezone валидируются |
+| PATCH /v1/schedules/{id} | agentRevision?, cron?, timezone?, enabled?, overlapPolicy?, misfirePolicy?; If-Match | 200 Schedule | 412 conflict |
 | GET /v1/schedules | cursor, limit | 200 Page<Schedule> | Tenant-scoped |
 | DELETE /v1/schedules/{id} | If-Match | 204 | Останавливает будущие, не текущие Run |
 
 Run: id, tenantId, agentId, agentRevisionId, status, specDigest, createdAt, startedAt?, finishedAt?, attemptCount, parentRunId?, error?, resultManifest?, inputRequest?. Полный spec доступен только субъектам с run:read-config; обычный status не содержит конфигурацию.
 
-Schedule: id, tenantId, agentId, cron, timezone, overlapPolicy (skip/queue), enabled, nextRunAt, revision. Каждое срабатывание фиксирует текущую ревизию агента; уже созданный Run не меняется при обновлении агента. Cron интерпретируется как пять полей (минута, час, день месяца, месяц, день недели); шаг менее минуты не поддерживается.
+Schedule: id, tenantId, agentId, agentRevisionId, cron, timezone, overlapPolicy (skip/queue), misfirePolicy (skip/coalesce), enabled, nextRunAt, revision. Расписание закрепляет agentRevisionId при создании. Новая ревизия применяется только явным PATCH расписания; уже созданные Run не меняются. Cron интерпретируется как пять полей (минута, час, день месяца, месяц, день недели); шаг менее минуты не поддерживается.
 
 Limits: cpuMillis, memoryBytes, timeoutSeconds, outputBytes. Пользователь может запросить меньше предела policy; превышение даёт 422, а не скрытое повышение прав. Input — JSON по input schema template. PoolId не даёт доступ к чужому пулу.
 
@@ -31,3 +31,13 @@ Limits: cpuMillis, memoryBytes, timeoutSeconds, outputBytes. Пользоват
 ```
 
 Отмена не гарантирует отмену уже совершённого внешнего действия. Reconcile технического статуса выполняет сервис исполнения; пользовательский запрос не переписывает состояние Runner произвольно.
+
+## Семантика расписаний
+
+GET /v1/schedules/{id} возвращает Schedule. POST /v1/schedules/preview принимает cron, timezone, from, count (1–10) и возвращает {occurrences:[UTC timestamp], warnings:[]}; сохранения не выполняет. Pause — PATCH enabled=false, resume — PATCH enabled=true; оба требуют If-Match. Возобновление не догоняет периоды явной паузы.
+
+Cron: пять полей; день недели 0–6 (0 — воскресенье); если day-of-month и day-of-week ограничены одновременно, применяется OR. DST: несуществующее локальное время пропускается, двойное — первое вхождение. Обновление tzdata пересчитывает только будущие occurrences; версия tzdata записывается в аудит. Первый релиз не поддерживает jitter и интервалы меньше минуты.
+
+Skip отбрасывает occurrence, если у расписания есть нетерминальный Run. Queue допускает один активный и максимум один ожидающий Run; лишние occurrences объединяются с ожидающим. При простое misfirePolicy=coalesce (default) выбирает последний пропущенный occurrence, skip не создаёт Run. Уникальность (scheduleId, scheduledAt) гарантируется БД. Проверка overlap и создание Run выполняются под блокировкой строки Schedule в одной транзакции. Ручные Run не учитываются в overlap, но учитываются в квотах tenant.
+
+Отзыв доступа к агенту/connection, блокировка пакета и архивирование агента останавливают расписание с reason, не создавая бесконечную череду failed Run. Любой запуск повторно проверяет права владельца расписания. Локальное расписание требует работающего daemon; перенос в облако отключает прежнего владельца до включения нового.