Files
crank/docs/execution-boundary.md
bsodfather 90e5357a08
CI / UI Checks (pull_request) Successful in 8s
CI / Rust Checks (pull_request) Successful in 21m42s
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
feat(epic4): продолжение ожидающей Task после ввода (Story 4.5)
Durable worker приостанавливает Task как input_required до dispatch, если
закреплённая схема требует отсутствующее поле; authorized schema-validated
update атомарно и с аудитом возобновляет тот же Task ровно один раз.
Replay/conflict/TTL безопасны, ожидание удерживает admission permit.
Additive schema v30: task_input_requests, fingerprint/version, TTL-индекс.
2026-10-30 16:24:12 +00:00

16 KiB
Raw Permalink 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 работы.

Безопасные повторы, отмена и 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 — это консервативное отклонение в безопасную сторону, а не забытый сценарий.

Продолжение Task через валидированный input (Story 4.5)

Отсутствующий обязательный input pinned-операции больше не превращается в ошибку после checkpoint: TaskWorkerHandler::prepare_attempt сверяет исполняемый input с native схемой pinned-версии и при MissingField возвращает типизированный PrepareAttempt::InputRequired. Само решение о недостающем обязательном поле принимает crank_runtime::missing_required_input (рядом с TaskAttemptAuthority), а application-слой только использует результат: runtime остаётся единственным местом execution-валидации (scripts/check-rust-boundaries.sh). Executor вызывает TaskStore::suspend_for_input до checkpoint_dispatch, поэтому в этой генерации гарантированно нет outbound side effect. Транзакция одной строкой Task проверяет owner/fence/version/attempts/lease/deadline, пишет task_input_requests (wait_id, ожидаемая версия, schema revision/format и fingerprint format version, immutable native snapshot, JSON-проекция, безопасный prompt code, missing-field paths, TTL), append-only task_input_audit и переводит working → input_required, снимая lease. Executing admission permit сохраняется: ожидание ограничено pinned absolute deadline и занимает уже выданную concurrency capacity, без второй reservation.

Ответ принимается внутренним TaskApplication::update_input (публичный MCP wire остаётся Story 4.7): principal выводит owner/scope, сервер валидирует input той же native snapshot, а PG-транзакция под row lock повторно проверяет key/workspace/agent/ status/expiry/scopes, wait_id, версию, generation и TTL по clock_timestamp(). Успех атомарно пишет continuation в существующий encrypted executable input, tasks.effective_input_fingerprint, receipt и audit и переводит input_required → working ровно один раз; acceptance fingerprint не меняется, поэтому исходный accept replay остаётся replay. Identical authorized replay возвращает сохранённый outcome без нового CAS/audit/dispatch, другой payload с тем же scoped update key — FingerprintConflict, другой key/устаревшая версия/чужой wait — StateConflict.

Продолжение подхватывает bounded claim по committed receipt и существующему executing permit (новый fence, без второго admission grant) и исполняет ту же pinned Task; следующий checkpoint пишет effective fingerprint, а исходный accept ID/version/scope/ support IDs сохраняются. Sweeper expire_input_waits вызывается на каждом poll, в том числе при заполненном local max_inflight, и под тем же row lock переводит просроченную Task в failed (input_ttl_expired) с audit, удаляя admission entry, без dispatch. Cancel ожидающей Task освобождает permit; update не оживляет уже failed/cancelled/expired Task. Secret input не попадает в request/receipt/audit/log: audit хранит только коды/версии/состояния, payload — только в шифрованном binding.

Ограничения этой генерации (осознанные, без обхода AC):

  • Продолжение возможно ровно один раз на генерацию. Если принятый update всё ещё не покрывает другое обязательное поле pinned-операции, Task завершается task_input_still_incomplete до dispatch, а не задаёт второй вопрос — консервативно и без side effect; повторный prompt после принятого ответа не входит в Story 4.5.
  • v30 выполняет one-shot backfill (update tasks set effective_input_fingerprint = input_fingerprint, затем set not null) и set not null под ACCESS EXCLUSIVE на tasks, хотя descriptor объявляет backfill: none. На текущем объёме это короткая блокировка; при деплое на большой tasks её длительность нужно учитывать в окне миграции (bounded/backfill-политика для таких таблиц — отдельное решение, не эта story).