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

91 lines
7.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Единая граница выполнения 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 работы.