Files
crank/docs/execution-boundary.md
T
bsodfather f9f8c625d1
CI / UI Checks (pull_request) Successful in 15s
CI / Rust Checks (pull_request) Failing after 4m58s
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) Failing after 1s
CI / Deploy (pull_request) Skipped
feat(epic4): исполнять durable Task через PG lease/fence и восстанавливать после сбоев (Story 4.3)
mcp-server запускает сохранённые фоновые задачи: захват по PostgreSQL lease с
fence-токеном, зашифрованный input и повторная проверка доступа до сетевого
вызова, checkpoint с AttemptID до dispatch и восстановление только по PG.
Устаревший worker не может зафиксировать результат.

Добавлены миграции v26–v28 (V25 не меняется), guard их отсутствия в старой
схеме, метрики/трассы попыток (attempt_trace) и остановка до отправки запроса:
стоп в окне после checkpoint и до permit завершает задачу как
failed(shutdown_before_dispatch) без сетевых вызовов, соседние queued-задачи
остаются доступными. Retry-попытки получают отдельные дочерние spans с durable
current_attempt_id. Shared admission/fairness из Story 4.1 сохранены.

Проверки: durable_tasks 13/13, stages 11/11 (retry 5), runtime lib 47,
bin shutdown 1, registry tasks 16, admission 11, migrations 58 (независимая QA
и исходный runtime-прогон), точный exact-head CI остаётся обязательным.
2026-10-29 22:26:52 +00:00

7.5 KiB
Raw Blame History

Единая граница выполнения 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 работы.