Files
crank/docs/execution-boundary.md
T
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

163 lines
16 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 работы.
## Безопасные повторы, отмена и 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).