CI / UI Checks (pull_request) Successful in 8s
CI / Rust Checks (pull_request) Successful in 20m46s
CI / Rust Feature Validation (pull_request) Skipped
CI / Frontend E2E (pull_request) Skipped
CI / Community Image Smoke (pull_request) Skipped
CI / Required Checks (pull_request) Successful in 1s
CI / Deploy (pull_request) Skipped
Durable per-outbound attempt до отправки запроса, bounded retry/read, server-owned verified writes, честный cancel/unknown, deadline/fencing, additive schema v29. Staged renames task.rs/tasks.rs разложены на модули. Includes disclosed cosmetic parity exception: единственная правка вне принятой дельты — удалена лишняя пустая строка в конце scripts/ci-story-checks.sh (EOF blank line); story-код не менялся.
111 lines
12 KiB
Markdown
111 lines
12 KiB
Markdown
# Единая граница выполнения REST Operation
|
||
|
||
Admin Draft Test и MCP `tools/call` используют один путь:
|
||
|
||
`RuntimeExecutionRequest → crank-runtime → ProtocolAdapter → crank-adapter-rest`.
|
||
|
||
До mapping и сетевого dispatch envelope фиксирует workspace, origin, точную
|
||
Operation/version, Agent для immutable snapshot, authorization, resolved auth,
|
||
correlation context и монотонный deadline. Runtime не создаёт fallback Request ID
|
||
или Trace ID. `admin_draft` не принимает Agent ID, а `agent_snapshot` требует его.
|
||
|
||
## Результат и ошибки
|
||
|
||
Успешный результат — нормализованный JSON output. Ошибка один раз преобразуется
|
||
в закрытый `ExecutionFailure`: `error_code`, `stage`, `retryability`,
|
||
`outcome_certainty`, безопасные Request/Trace IDs и ограниченный typed context.
|
||
Admin и MCP лишь проецируют этот descriptor в свои wire-ответы.
|
||
|
||
`retryability` принимает `never`, `safe`, `after_delay`, `manual_reconcile` или
|
||
`requires_confirmation`. При timeout/transport cancellation после возможного
|
||
dispatch возвращается `manual_reconcile + outcome_unknown`; автоматически
|
||
повторять такой вызов нельзя. HTTP/MCP status и текст ошибки не меняют это решение.
|
||
|
||
Raw URL, upstream body/headers, parser/Reqwest/SQLx error и секреты не входят в
|
||
ответ или Invocation History. Resolved auth и confirmation token имеют redacted
|
||
`Debug` и не сериализуются как execution envelope.
|
||
|
||
## История и совместимость
|
||
|
||
Migration v5 (`execution-outcome-v5`) добавляет nullable поля exact Operation
|
||
version, stage, stable error code, retryability и certainty. Для legacy v4 строк
|
||
они остаются `NULL`; значения не фабрикуются. Новые Admin/MCP записи сохраняют
|
||
их вместе с Request ID и Trace ID независимо от telemetry sampling.
|
||
|
||
Пути Admin API, MCP methods и успешные response fields не изменены. Поля ошибки
|
||
добавлены обратно совместимо. Outbound DNS/redirect/retry/SSRF policy принадлежит
|
||
Story 1.9 и этой границей не считается завершённой.
|
||
|
||
## Durable background Task (Story 4.2)
|
||
|
||
Принятие фоновой работы идёт через `TaskApplication → crank-runtime::TaskService →
|
||
TaskStore`. PostgreSQL-реализация выполняет одну транзакцию: Task, dispatch intent
|
||
(`execution_admission_entries.task_id`) и queue slot коммитятся вместе, и только
|
||
после commit выдаётся ack с Task ID/поддержкой Request/Trace/parent TraceContext.
|
||
Повтор того же полного scoped key возвращает сохранённую Task, другой canonical
|
||
input fingerprint — типизированный конфликт; явная другая published-версия при том
|
||
же ключе не перезакрепляет уже принятую работу. Owner-скоуп (workspace, Agent/admin,
|
||
authorization scope) входит в каждый read; чужой Task неотличим от отсутствующего.
|
||
|
||
Границы этой story: публичный MCP wire Tasks/capabilities/activation остаётся
|
||
Story 4.7, worker/leases/recovery реализованы в Story 4.3 (ниже). Существующий
|
||
`tools/call` сохраняет synchronous/unsupported поведение; durable acceptance не
|
||
запускает ephemeral execution и не рекламирует клиенту background capability.
|
||
|
||
## Исполнение durable Task (Story 4.3)
|
||
|
||
`mcp-server` запускает fenced worker в том же процессе: bounded claim через
|
||
PostgreSQL `FOR UPDATE SKIP LOCKED` над reserved dispatch intent, lease owner/expiry
|
||
и monotonic fence; Valkey не является источником истины и может только ускорять
|
||
wake-up. Claim использует уже принятый shared admission из Story 4.1
|
||
(`lock_admission_in_tx` по controller-строке `*` + `grant_next_task` с его
|
||
scoped-лимитами, bounded queue и weighted fairness cursor) и не добавляет второго
|
||
scheduler'а: 4.3-дельта лишь fencing/lease-поля и CAS-предикаты поверх того же
|
||
grant, поэтому принятые fairness-инварианты 4.1 сохраняются. Progress, renewal,
|
||
dispatch checkpoint и terminal outcome пишутся только через CAS по текущему
|
||
owner/fence/expiry. До сетевого вызова worker повторно проверяет публикацию и
|
||
точную версию capability, активный Platform API key/scope, approval policy и
|
||
deadline; невалидная работа завершается без dispatch. Attempt ID и dispatch
|
||
checkpoint коммитятся атомарно до outbound; после checkpoint потеря lease означает
|
||
uncertain outcome и Task переходит в `outcome_unknown` без автоматического retry.
|
||
Исполняемый input берётся только из зашифрованного Task payload через
|
||
`TaskService::executable_input` (redacted projection никогда не исполняется).
|
||
Parent TraceContext сохраняется с acceptance; durable attempt span продолжает его,
|
||
а каждая adapter-попытка (включая retry существующих GET/verified-idempotent write)
|
||
получает собственный child span `adapter_attempt` с тем же durable Attempt ID и
|
||
номером попытки, поэтому retry не сливается с первым attempt в трассе, а любой
|
||
такой span сопоставим с `tasks.current_attempt_id`; синтетический attempt id
|
||
остаётся только у синхронного tools/call, где durable попытки нет. Скан PostgreSQL авторитетен:
|
||
crash до checkpoint возвращает Task в queue по истечении lease (recovery ≤60s).
|
||
|
||
Graceful shutdown является процессным, а не только worker-локальным: сигнал
|
||
SIGTERM/ctrl-c одновременно прекращает новые claims и запускает HTTP graceful
|
||
drain (worker не ждёт завершения долгого соединения), активные attempts
|
||
checkpoint-ятся/дренируются в пределах 30s, а ошибочное завершение HTTP-сервера
|
||
также останавливает worker. Уже поставленные в queue Tasks не теряются. Остаётся
|
||
узкое окно между durable checkpoint и созданием sealed dispatch permit: если stop
|
||
приходит именно туда, Task финализируется как failed(`shutdown_before_dispatch`),
|
||
не отправляя запрос; это доказано регрессией, которая детерминированно
|
||
задерживает checkpoint в его собственной транзакции, проверяет отсутствие вызова
|
||
adapter и сохранность ещё queued работы.
|
||
|
||
## Безопасные повторы, отмена и outcome_unknown (Story 4.4)
|
||
|
||
До каждого outbound — отдельная durable-попытка в таблице `task_attempts` (attempt_id, ordinal, owner/fence, input fingerprint, digest upstream-ключа, pinned retry snapshot) в одной транзакции с инкрементом бюджета и версии Task; несостоявшийся commit = ноль вызовов.
|
||
|
||
После каждой попытки — одна атомарная resolution; только текущая попытка/владелец/версия, иначе StateConflict; история попыток после закрытия неизменна.
|
||
|
||
Bounded retry только для read и для write с server-owned verified-idempotency evidence; клиентский key/header сам по себе не даёт write-retry; бюджет/backoff/абсолютный deadline пинятся при приёме и не меняются новой публикацией/рестартом.
|
||
|
||
Стабильный upstream-ключ доставляется тем же `prepare_idempotency`, но синхронный coordination guard одного `tools/call` на durable-пути не применяется: авторитет повтора — PG-попытка Task, иначе неоднозначный первый ответ заблокировал бы разрешённый bounded retry. В историю попытки пишется только digest ключа, не значение и не заголовки.
|
||
|
||
Cancel до checkpoint -> cancelled и ноль outbound (сериализуется с claim и checkpoint на одной строке Task); после checkpoint (в т.ч. verified write) -> non-terminal outcome_unknown, без retry и без обещания rollback; подтверждённый результат, выигравший CAS раньше, неизменяем.
|
||
|
||
Отмена в окне backoff между попытками и отказ перед следующей попыткой (истёкший deadline, отклонённая authority, shutdown/детерминированная ошибка до отправки) не стирают уже записанную неопределённость: если последняя закрытая **отправленная** (`phase=dispatched`) попытка Task имеет certainty=unknown, Task закрывается non-terminal `outcome_unknown` (cancel -> код `cancelled_after_dispatch`, отказ/резолюция -> код отказа и phase прошлой попытки), а `cancelled`/`failed` выдаются только когда ни одна попытка не отправлялась. Закрытая known-попытка с `phase=before_dispatch` (request вообще не уходил) такую неопределённость не перекрывает — аудит-строка остаётся known/before_dispatch, но Task не становится терминальным `failed`.
|
||
|
||
Deadline/lease loss: read/safe-retry -> одна bounded new attempt (fence растёт, stale worker fenced), иначе outcome_unknown; сохранённый outcome_unknown обычными finish/cancel/retry не выводится (reconciliation — Story 4.6, вне scope).
|
||
|
||
Миграция v29 additive; legacy Task получает max_attempts=1.
|
||
|
||
Отмена после dispatch для read тоже даёт non-terminal `outcome_unknown`: в pinned snapshot Task'а нет read/write-класса, а выводить его из текущей публикации означало бы менять уже принятый snapshot. ARC-различие «read -> failed(`cancellation_after_dispatch`)» поэтому осознанно отложено до reconciliation Story 4.6 — это консервативное отклонение в безопасную сторону, а не забытый сценарий.
|