466 lines
42 KiB
Markdown
466 lines
42 KiB
Markdown
---
|
||
story_id: "1.8"
|
||
story_key: "1-8-rest-execution-boundary-errors"
|
||
requirement: "FR-2"
|
||
status: "done"
|
||
baseline_commit: "767428436d3a54e60809a727044dfcec48e1f1dd"
|
||
---
|
||
|
||
# Story 1.8: Унифицировать REST execution и boundary errors
|
||
|
||
Status: done
|
||
|
||
## Story
|
||
|
||
As an администратор или MCP-пользователь,
|
||
I want получать одинаковое и предсказуемое выполнение Operation через UI и MCP,
|
||
so that результат и классификация ошибки не зависят от входной точки.
|
||
|
||
## Strategic Intent
|
||
|
||
Story 1.8 закрепляет единственную синхронную execution boundary существующего REST → MCP продукта после immutable Operation lifecycle из Story 1.7. Сегодня Admin Test и MCP `tools/call` оба вызывают runtime, но собирают неполный `RuntimeExecutionRequest`, разрешают optional correlation/scope, отдельно резолвят auth и независимо преобразуют `RuntimeError` в несовпадающие коды, сообщения и retryability. Admin history также способен сохранить `error.to_string()`, содержащий внутренние детали.
|
||
|
||
Итоговый контракт: Admin Draft Test и MCP exact Published Tool создают один полностью scoped typed request, проходят один runtime/adapter pipeline и получают один внутренний normalized outcome. HTTP и MCP отвечают своими wire-формами, но сохраняют одинаковые stage, stable code, retryability, outcome certainty, Request ID и Trace ID. Никакая boundary не анализирует текст ошибки и не знает варианты `RestAdapterError`.
|
||
|
||
Story является обязательным predecessor для 1.9 outbound/SSRF hardening, 1.13 immutable Agent catalog, Epic 3 dynamic capabilities и Epic 4 Tasks. Она не реализует DNS/redirect/retry policy, background Tasks, новый MCP wire revision или History UI.
|
||
|
||
**Requirement:** FR-2
|
||
**Architecture:** AD-1, AD-2, AD-4, AD-9, AD-11, AD-15, AD-19, AD-21, AD-23; consistency conventions
|
||
**Applicable NFR:** NFR-P4, NFR-R1, NFR-S1, NFR-S2, NFR-S4, NFR-S7, NFR-S8, NFR-O1, NFR-O4, NFR-O5, NFR-C1, NFR-C4
|
||
**Primary risk/evidence:** E1-R-007 (score 9); E1-17, E1-18, E1-19.
|
||
|
||
## Acceptance Criteria
|
||
|
||
1. **Один обязательный typed execution envelope**
|
||
- Given Admin Test или MCP `tools/call`
|
||
- When application layer принимает выполнение
|
||
- Then она создаёт ровно один `RuntimeExecutionRequest` с typed `WorkspaceId`, origin (`admin_draft|agent_snapshot`), optional typed `AgentId` только по правилам origin, exact `OperationId/version`, authorization decision/resolved auth, input, monotonic deadline, canonical correlation, approval и idempotency context
|
||
- And production constructor не допускает отсутствующий workspace, operation/version, deadline или correlation и не генерирует fallback IDs внутри runtime
|
||
- And secret-bearing resolved auth, confirmation и idempotency material не реализуют раскрывающий `Debug`/`Display`/`Serialize`; fingerprint/context хранит только необходимые typed or redacted values
|
||
- And invalid/missing/incompatible scope отклоняется до mapping, adapter lookup и outbound dispatch.
|
||
|
||
2. **Единый pipeline без transport bypass**
|
||
- Given валидный execution envelope
|
||
- When начинается выполнение
|
||
- Then оба ingress проходят `RuntimeExecutionRequest → crank-runtime → ProtocolAdapter → crank-adapter-rest`
|
||
- And route/transport/service не вызывает REST client, SQLx persistence implementation или mapping/schema implementation напрямую
|
||
- And test-only convenience methods не остаются доступным production bypass.
|
||
|
||
3. **Admin исполняет только exact current saved Draft**
|
||
- Given active Operation и выбранная current Draft revision
|
||
- When Admin запускает Test
|
||
- Then application resolution из Story 1.7 фиксирует exact saved version до runtime admission и origin равен `admin_draft`
|
||
- And unsaved browser state, Published/archived/non-current/foreign version отклоняется до dispatch
|
||
- And выполнение не публикует Draft и не меняет Agent catalog.
|
||
|
||
4. **MCP исполняет только exact immutable Agent snapshot**
|
||
- Given авторизованный опубликованный Agent snapshot
|
||
- When клиент вызывает Tool
|
||
- Then tool resolution фиксирует exact Published Operation version из immutable binding и origin равен `agent_snapshot` с typed Agent ID
|
||
- And Draft, archived-new-binding, foreign Agent, непредоставленный Tool или capability вне snapshot получает safe not-found/denied без metadata leakage и без adapter call
|
||
- And existing pinned Agent behavior из Story 1.7 сохраняется.
|
||
|
||
5. **Один normalized success outcome**
|
||
- Given одинаковые exact Operation version, input, auth и deterministic upstream response
|
||
- When вызов выполнен через Admin и MCP
|
||
- Then schema validation, input mapping, request preparation, adapter execution, output mapping и output schema validation дают семантически одинаковый normalized output
|
||
- And HTTP Test DTO и MCP content/result являются только transport projections этого outcome
|
||
- And transport-specific envelope, status и localization не входят в runtime domain contract.
|
||
|
||
6. **Закрытая typed failure taxonomy**
|
||
- Given failure на `authorization|input_schema|input_mapping|request_preparation|admission|adapter|upstream|output_mapping|output_schema|mandatory_persistence|runtime`
|
||
- When failure покидает owning layer
|
||
- Then она преобразуется один раз в framework-free `ExecutionFailure` с closed `stage`, stable `error_code`, `retryability`, `outcome_certainty`, optional bounded safe context и correlation
|
||
- And HTTP/MCP/history/metrics используют этот descriptor, не повторяют match по `RuntimeError`/`RestAdapterError` и не выводят raw cause
|
||
- And unknown internal failure fail closed как `runtime_internal`, `retryability=never`, без произвольного текста.
|
||
|
||
7. **Фиксированная retryability/certainty семантика**
|
||
- Given typed failure
|
||
- When клиент или оператор решает, можно ли повторять
|
||
- Then retryability принимает только `never|safe|after_delay|manual_reconcile|requires_confirmation`, а certainty — `certain|outcome_unknown`
|
||
- And validation/auth/not-found/conflict являются `never`; overload/known pre-dispatch transport failure — `after_delay`; confirmation — `requires_confirmation`; ambiguous write/cancellation after dispatch — `manual_reconcile + outcome_unknown`
|
||
- And `outcome_unknown` никогда не превращается в recoverable/automatic retry по тексту, HTTP status или MCP transport status.
|
||
|
||
8. **Deadline, timeout и cancellation не дают ложный success**
|
||
- Given bounded monotonic deadline или cancellation
|
||
- When deadline истекает до dispatch, во время adapter wait либо после возможной отправки write
|
||
- Then runtime возвращает typed stage/certainty согласно фактически достигнутой dispatch boundary
|
||
- And cancelled idempotent execution завершает coordination state безопасно; cleanup failure не меняет внешний outcome и создаёт bounded operational incident
|
||
- And один upstream response/side effect не учитывается дважды.
|
||
|
||
9. **Persistence semantics честны**
|
||
- Given completed success/failure
|
||
- When Invocation History сохраняется
|
||
- Then новая запись сохраняет Request ID, Trace ID, source, exact Operation/version, stage, error code, retryability и outcome certainty независимо от sampling
|
||
- And schema evolution выполняется только append-only MigrationAuthority v5 с N/N-1 nullable compatibility; v1–v4 source/checksum не меняются
|
||
- And отказ обязательного pre-dispatch safety persistence блокирует dispatch, а отказ post-outcome diagnostic history сохраняет product outcome и создаёт typed History Loss incident (DC-08), не подменяя success на failure.
|
||
|
||
10. **Safe localized boundaries**
|
||
- Given normalized success/failure
|
||
- When формируется Admin Test или MCP response
|
||
- Then обе boundary возвращают stable `error_code`, stage, explicit retryability/certainty, bounded RU/EN message согласно выбранной locale и одинаковые safe Request/Trace IDs
|
||
- And raw upstream body, URL, headers, credential, SQLx/Reqwest/parser text, internal path и arbitrary payload отсутствуют в response, history message, logs, traces, metrics и evidence
|
||
- And существующие HTTP route paths, MCP method names/protocol negotiation и успешные response fields сохраняются; additive error fields документированы.
|
||
|
||
11. **Typed observability без cardinality regression**
|
||
- Given execution success или любая failure stage
|
||
- When записываются spans/metrics/history
|
||
- Then используются существующие typed `crank-trace` stages и `crank-metrics` outcome enums; Request/Trace/Object IDs не становятся labels
|
||
- And один execution создаёт согласованный terminal metric outcome, а Trace ID используется только как exemplar/trace field
|
||
- And redaction/preview остаются bounded valid UTF-8/JSON, включая oversized malformed upstream/error canaries.
|
||
|
||
12. **Паритет и архитектура доказаны executable gates**
|
||
- Given Story implementation
|
||
- When выполняются E1-17/E1-18/E1-19 suites
|
||
- Then table-driven matrix сравнивает Admin и MCP для success и всех stages по normalized output/code/stage/retryability/certainty/IDs и точному adapter call count
|
||
- And negative architecture fixtures ловят direct adapter/persistence call, alias, re-export и helper bypass
|
||
- And targeted suites, migration/SQLx checks, Capability Inventory, explicit Community scan, real REST→MCP smoke и `just verify` проходят без dependency/toolchain/public-success-wire changes.
|
||
|
||
## Frozen Execution Taxonomy
|
||
|
||
| Stage | Representative failures | Default retryability | Certainty |
|
||
| --- | --- | --- | --- |
|
||
| `authorization` | missing/foreign scope, revoked/missing profile/secret | `never` | `certain` |
|
||
| `input_schema` | input violates schema | `never` | `certain` |
|
||
| `input_mapping` | JSONPath/mapping failure | `never` | `certain` |
|
||
| `request_preparation` | malformed mapped header/path/query/body | `never` | `certain` |
|
||
| `admission` | concurrency/mandatory coordination unavailable | `after_delay` for overload/store outage; otherwise `never` | `certain` |
|
||
| `adapter` | unsupported protocol/config before dispatch | `never` | `certain` |
|
||
| `upstream` | status/transport/timeout | derived by typed dispatch evidence, never message text | `certain` or `outcome_unknown` |
|
||
| `output_mapping` | response mapping failure | `never` | `certain` |
|
||
| `output_schema` | mapped response violates schema | `never` | `certain` |
|
||
| `mandatory_persistence` | required safety record unavailable before acknowledgement | `after_delay` | `certain` |
|
||
| `runtime` | invariant/internal normalized failure | `never` | `certain` |
|
||
|
||
Additional non-error control outcomes such as `requires_confirmation`, idempotency `in_progress|conflict|outcome_unknown` remain explicit typed outcomes and map into the same retryability/certainty vocabulary. HTTP status and MCP `isError` are projections, not sources of truth.
|
||
|
||
### Frozen machine codes
|
||
|
||
`error_code` является closed enum, а не произвольной строкой. Минимальный v1 vocabulary:
|
||
|
||
| Stage/control | Stable codes |
|
||
| --- | --- |
|
||
| authorization | `authorization_denied`, `auth_profile_not_found`, `secret_not_found`, `secret_invalid` |
|
||
| input_schema | `input_schema_invalid` |
|
||
| input_mapping | `input_mapping_invalid` |
|
||
| request_preparation | `prepared_request_invalid` |
|
||
| admission | `execution_overloaded`, `safety_store_unavailable` |
|
||
| adapter | `protocol_unsupported`, `execution_mode_unsupported`, `adapter_configuration_invalid`, `outbound_target_rejected` |
|
||
| upstream | `upstream_auth_error`, `upstream_not_found`, `upstream_rate_limited`, `upstream_server_error`, `upstream_status_error`, `upstream_timeout`, `upstream_transport_error`, `upstream_response_too_large` |
|
||
| output_mapping | `output_mapping_invalid` |
|
||
| output_schema | `output_schema_invalid` |
|
||
| mandatory_persistence | `persistence_unavailable` |
|
||
| runtime | `runtime_internal` |
|
||
| control | `confirmation_required`, `confirmation_invalid`, `idempotency_in_progress`, `idempotency_conflict`, `idempotency_outcome_unknown` |
|
||
|
||
Новое значение требует изменения typed enum, exhaustive parity table, RU/EN catalog и versioned contract evidence в одном change. Story 1.9 может уточнить typed upstream/outbound causes, но не переименовывает опубликованные v1 codes.
|
||
|
||
## Tasks / Subtasks
|
||
|
||
- [x] Task 1 — Freeze RED parity oracle and current bypass inventory (AC: 1–12)
|
||
- [x] Add table-driven fixtures proving current Admin/MCP code/stage/recoverable mismatches, raw history error leakage and optional-context fallback.
|
||
- [x] Instrument fake adapter/store call counters; every pre-dispatch rejection asserts zero calls and every accepted execution asserts exactly one expected adapter call.
|
||
- [x] Record current public success DTO/MCP output snapshots and Story 1.7 exact Draft/Agent resolution invariants.
|
||
|
||
- [x] Task 2 — Introduce framework-free execution identity/outcome contract (AC: 1, 5–8, 10)
|
||
- [x] Add closed `ExecutionOrigin`, `ExecutionStage`, `ExecutionErrorCode`, `Retryability`, `OutcomeCertainty`, `ExecutionFailure` and normalized success/outcome types in the lowest framework-free owner (`crank-core`), with bounded safe context only.
|
||
- [x] Define exact serialization only where a durable/internal contract requires it; domain types remain distinct from HTTP/MCP DTOs.
|
||
- [x] Add exhaustive constructor/truth-table tests; forbid unknown stage/code or incompatible retryability/certainty combinations.
|
||
|
||
- [x] Task 3 — Make `RuntimeExecutionRequest` complete and non-optional (AC: 1–4, 8)
|
||
- [x] Require typed scope/origin/exact target, input, deadline, correlation, authorization, approval and idempotency context at construction.
|
||
- [x] Remove production fallback ID/context generation and convenience `execute_with_*` bypasses; migrate tests to an explicit fixture builder unavailable to production callers.
|
||
- [x] Validate origin invariants (`admin_draft` has no Agent; `agent_snapshot` requires Agent and immutable binding) before mapping/dispatch.
|
||
|
||
- [x] Task 4 — Centralize runtime stage and error normalization (AC: 5–8, 11)
|
||
- [x] Split oversized executor/error responsibilities into focused modules before crossing code-health ceilings; keep one terminal outcome recorder.
|
||
- [x] Normalize schema/mapping/preparation/admission/protocol/adapter/upstream/output errors once and retain internal source only for redacted diagnostics.
|
||
- [x] Add deadline/cancellation/dispatch-evidence seam and deterministic tests for before-dispatch, known-no-dispatch and ambiguous-after-dispatch cases.
|
||
|
||
- [x] Task 5 — Unify Admin Draft execution composition (AC: 1–3, 5, 9–10)
|
||
- [x] Preserve Story 1.7 exact current-Draft resolution and construct the full envelope after authorization/scope checks.
|
||
- [x] Replace local `runtime_error_code`/`runtime_test_failure` branching and raw `error.to_string()` history message with normalized outcome projection.
|
||
- [x] Keep Test route/success fields; add stable stage/retryability/certainty fields and localized safe failures with Request/Trace IDs.
|
||
- [x] Update the existing wizard Test result/error projection to localize the stable code in RU/EN, retain loading/recovery and safe ID copy behavior, and ignore stale operation/workspace responses; no new page or frontend framework.
|
||
|
||
- [x] Task 6 — Unify MCP snapshot and approved execution composition (AC: 1–5, 9–10)
|
||
- [x] Preserve exact immutable Agent binding resolution for direct and approved tool calls and construct the same full envelope.
|
||
- [x] Replace adapter-specific matching in `tool_error.rs`; MCP boundary projects only normalized execution outcome.
|
||
- [x] Keep protocol negotiation/JSON-RPC/`isError` semantics and confirmation flow compatible across supported MCP revisions.
|
||
|
||
- [x] Task 7 — Persist honest execution classification via migration v5 (AC: 7–9)
|
||
- [x] Add contiguous transactional exact-byte checksummed `execution_outcome_v5.sql`; never alter v1–v4.
|
||
- [x] Add nullable N-1 compatible fields/indexes/checks for exact operation version, stage, stable error code, retryability and certainty; legacy rows remain explicitly unknown rather than fabricated.
|
||
- [x] Update registry models/queries, version-aware schema fingerprint, SQLx metadata and fresh/v4→v5/replay/rollback/corruption tests.
|
||
|
||
- [x] Task 8 — Build Admin/MCP differential contract suite (AC: 3–12)
|
||
- [x] Cover success, every frozen stage, missing/foreign scope, timeout, cancellation, overload, confirmation, idempotency conflict/outcome-unknown and history loss.
|
||
- [x] Compare normalized semantic output plus code/stage/retryability/certainty/correlation; assert transport-only differences explicitly.
|
||
- [x] Add secret/body/URL/path canaries to response/history/log/trace/metric capture and concurrency isolation tests.
|
||
|
||
- [x] Task 9 — Harden architecture guardrails (AC: 2, 12)
|
||
- [x] Extend scanner to reject direct REST adapter/client or persistence execution from Admin/MCP routes/services and forbidden dependency/re-export/helper aliases.
|
||
- [x] Scan tracked plus explicit untracked Rust candidates, fail closed on symlinks/missing paths and add negative fixtures for each bypass spelling.
|
||
- [x] Preserve valid composition-root adapter construction and runtime→protocol-adapter dependency direction.
|
||
|
||
- [x] Task 10 — Docs, evidence and final qualification (AC: 10–12)
|
||
- [x] Update runtime/error/Admin/MCP/history/migration docs and RU/EN message catalog; document additive error fields and no automatic retry for unknown outcome.
|
||
- [x] Refresh Capability Inventory/baseline only after accepted evidence; do not claim 1.9 SSRF/retry hardening complete.
|
||
- [x] Run targeted/differential/PG/MCP suites, migration+SQLx/config/metrics/boundary checks, real authenticated product smoke, explicit Community scan and one final `just verify`.
|
||
|
||
### Review Findings
|
||
|
||
- [x] [Review][Patch] [High] Закрыть production bypass обязательного execution envelope: поля `RuntimeExecutionRequest` и raw `execute_request` не должны позволять обойти `try_new`/normalized outcome [`crates/crank-runtime/src/execution_request.rs`:14]
|
||
- [x] [Review][Patch] [High] Удалить отдельный Admin mapping-preview short circuit и выполнять mapping ровно один раз внутри canonical runtime pipeline [`apps/admin-api/src/service/operations.rs`:601]
|
||
- [x] [Review][Patch] [High] Передавать точную dispatch evidence и mutability во все REST failures, включая connect/DNS, status, invalid/oversized response и deadline [`crates/crank-adapter-rest/src/lib.rs`:62]
|
||
- [x] [Review][Patch] [High] Исправить idempotency lifecycle: pre-dispatch failure/cancellation освобождает reservation, а post-dispatch completion failure становится `manual_reconcile + outcome_unknown` [`crates/crank-runtime/src/executor.rs`:370]
|
||
- [x] [Review][Patch] [High] Не терять normalized outcome и correlation при отказе финального сохранения approved execution [`crates/crank-community-mcp/src/approval_execution.rs`:303]
|
||
- [x] [Review][Patch] [High] Убрать открытый MCP string taxonomy и проводить authorization/control failures через closed typed descriptor и history [`crates/crank-community-mcp/src/tool_error.rs`:69]
|
||
- [x] [Review][Patch] [High] Закрыть v5 error-code vocabulary и проверять точные определения constraints/index, а не только их имена [`crates/crank-registry/src/migrations/execution_outcome_v5.sql`:8]
|
||
- [x] [Review][Patch] [Medium] Запретить новым application writes сохранять Invocation History без exact version и полной execution classification, сохранив nullable только для legacy N-1 rows [`crates/crank-registry/src/postgres/observability.rs`:42]
|
||
- [x] [Review][Patch] [High] Расширить execution-boundary gate на raw runtime, adapter invocation, SQLx/persistence, mapping/schema, aliases/re-exports/helpers и весь MCP production subtree [`scripts/check-execution-boundaries.py`:11]
|
||
- [x] [Review][Patch] [High] Добавить реально исполняемую Admin/MCP differential matrix для success, всех frozen stages, call counts, IDs, history, redaction и concurrency; исправить ложные completion claims [`_bmad-output/implementation-artifacts/1-8-rest-execution-boundary-errors.md`:196]
|
||
- [x] [Review][Patch] [Medium] Провести выбранную RU/EN locale через обе boundary и исправить ошибочное размещение русских execution keys внутри английского UI-каталога [`apps/ui/js/i18n.js`:787]
|
||
- [x] [Review][Patch] [Medium] Добавить workspace/operation/generation guard для результата Wizard Test после каждого await [`apps/ui/js/wizard-live.js`:832]
|
||
- [x] [Review][Patch] [High] Восстановить typed confirmation challenge в Admin Test response и поддержать подтверждённый повтор без раскрытия token через Debug/logs [`apps/admin-api/src/error.rs`:529]
|
||
- [x] [Review][Patch] [Medium] Отличать недоступность PostgreSQL при auth resolution от повреждённого секрета и не классифицировать storage failure как `secret_invalid + never` [`crates/crank-community-mcp/src/app.rs`:995]
|
||
- [x] [Review][Patch] [High] Санитизировать и ограничивать Admin request preview до HTTP projection, исключив credential/header/body canaries [`apps/admin-api/src/service/operations.rs`:703]
|
||
- [x] [Review][Patch] [High] Удалить revealing `Debug`/`Serialize` у secret-bearing `PreparedRequest` либо отделить redacted domain type от adapter wire type [`crates/crank-core/src/ext/protocol.rs`:116]
|
||
- [x] [Review][Patch] [Medium] Сделать `ExecutionFailure` code-specific и bounded: запретить confirmation/retry metadata на несовместимых codes и ограничить token/TTL [`crates/crank-core/src/execution.rs`:441]
|
||
|
||
## Dev Notes
|
||
|
||
### Current Brownfield State and Confirmed Gaps
|
||
|
||
- `RuntimeExecutionRequest` currently holds only `operation`, `input`, optional resolved auth and optional request context. Workspace/origin/Agent/deadline/authorization decision are implicit; `RuntimeExecutor` can generate fallback IDs/context.
|
||
- Admin Test and both MCP direct/approved paths already call `execute_request`, which is the correct seam to strengthen. Do not create a second orchestrator.
|
||
- Admin resolves exact current Draft after Story 1.7; MCP resolves exact immutable published binding. Preserve these separate application-resolution rules, then converge only at the runtime envelope.
|
||
- Admin owns `runtime_error_code` plus `runtime_test_failure_*`; MCP owns another `runtime_error_code`, safe-message, recoverable and action matrix and directly matches `RestAdapterError`. Codes already diverge (`schema_error` vs `schema_validation_error`, `rest_error` vs status-specific upstream codes).
|
||
- `RuntimeError` wraps library-specific errors and does not encode stage, retryability, dispatch certainty or deadline/cancellation. Several Display implementations contain operation/secret IDs, URL/target or internal reasons; they are not boundary-safe.
|
||
- Admin failure history currently writes `error.to_string()` into `message`. This is a confirmed NFR-S2/O5 violation risk even when HTTP response is sanitized.
|
||
- Invocation History stores source/status/error_kind and correlation, but not exact operation version, stage, retryability or certainty. Migration v5 is required for honest persisted classification; old rows must remain nullable/unknown.
|
||
- Post-outcome history failure is intentionally non-fatal (DC-08) in Admin and MCP. Preserve external success and emit the existing bounded loss incident; do not make diagnostic persistence a hidden correctness dependency.
|
||
- REST adapter policy/security defects belong to Story 1.9. Story 1.8 may expose dispatch evidence and normalize errors but must not claim DNS/redirect/proxy/retry policy qualification.
|
||
|
||
### Architecture and Implementation Guardrails
|
||
|
||
- `crank-core` owns framework-free execution vocabulary/ports only; it must not import Tokio, Axum, SQLx, Reqwest, tracing or adapter error types.
|
||
- `crank-runtime` owns orchestration and typed normalization; it may call protocol adapters but never registry/Axum/SQLx. It must not persist history.
|
||
- Apps remain composition roots and own exact Draft/Agent resolution, auth-profile/secret resolution and transport projection. Routes do not call runtime/adapter directly.
|
||
- Boundary DTOs remain in Admin `dto.rs` and MCP transport/tool error owners. Do not serialize `RuntimeError` or expose source chains.
|
||
- Internal `ExecutionFailure` must carry stable bounded fields, never a raw `String` cause. Diagnostic source is logged only through existing redaction vocabulary.
|
||
- Use Story 1.5 `CorrelationContext`/typed IDs and Story 1.6 typed stages/metrics/exemplars. Never regenerate IDs in runtime or add object/error text labels.
|
||
- MigrationAuthority is the sole DDL owner. Add v5, update machine sequence/schema fingerprint/SQLx metadata, preserve N/N-1 reads and controlled migrator-only writes.
|
||
- Keep Rust 1.96.1/Edition 2024, current dependencies, Compose, Alpine UI, MCP revisions and Community boundary unchanged.
|
||
|
||
### File Map
|
||
|
||
**NEW expected**
|
||
|
||
- `crates/crank-core/src/execution.rs` — closed framework-free identity/outcome taxonomy.
|
||
- `crates/crank-runtime/src/execution_failure.rs` and/or focused executor stage/deadline module.
|
||
- `crates/crank-registry/src/migrations/execution_outcome_v5.sql`.
|
||
- `apps/admin-api/tests/integration/execution_parity.rs` or a shared cross-app contract fixture at the lowest reusable test owner.
|
||
- Focused boundary scanner fixtures/tests if existing scripts cannot express direct execution ownership safely.
|
||
- `docs/execution-contract.md` — canonical stage/code/retryability/certainty and Admin/MCP projection contract.
|
||
|
||
**UPDATE expected**
|
||
|
||
- Core: `crates/crank-core/src/{lib.rs,observability.rs,ext/protocol.rs}` only as required by the new contract.
|
||
- Runtime: `crates/crank-runtime/src/{lib.rs,error.rs,executor.rs,request_context.rs,model.rs}` and focused tests; split rather than grow `executor.rs` beyond its current debt ceiling.
|
||
- REST adapter: `crates/crank-adapter-rest/src/{error.rs,lib.rs,client.rs}` only for typed dispatch evidence/normalization seam; network policy changes remain 1.9.
|
||
- Admin: `apps/admin-api/src/{dto.rs,error.rs,service.rs}`, `src/service/operations.rs`, `src/routes/operations.rs`; integration common/lifecycle/operations tests.
|
||
- UI (only if the additive Test failure fields require presentation): `apps/ui/js/{wizard-live.js,i18n.js,api.js}` and the existing lifecycle/wizard Playwright specs; preserve all Story 1.7 stale/ETag behavior.
|
||
- MCP: `crates/crank-community-mcp/src/{app.rs,approval_execution.rs,tool_error.rs}`, invocation-history helper and integration/unit tests. Extract focused modules rather than grow `app.rs`.
|
||
- Registry: `crates/crank-registry/src/{model.rs,postgres/observability.rs,postgres/mod.rs}`, migration authority/schema guard/tests and generated `.sqlx/query-*.json`.
|
||
- Guardrails: `scripts/check-rust-module-boundaries.sh` and/or Python boundary checker plus unit fixtures; `justfile` only if a distinct executable gate is necessary.
|
||
- Docs/evidence: `docs/{execution-contract.md,admin-api.md,mcp-interface.md,observability.md,migrations.md,data-model.md,database-schema.md,capability-inventory.json}`, migration sequence schema and baseline artifacts.
|
||
- Local ignored: this Story, sprint status and `_bmad-output/project-context.md`; never force-add them as canonical evidence.
|
||
|
||
**Must not change**
|
||
|
||
- Migration v1/v2/v3/v4 source bytes/checksums or Story 1.7 immutable Operation semantics.
|
||
- Outbound allow/deny/DNS/redirect/proxy/retry implementation except the minimal typed evidence seam explicitly needed by this Story.
|
||
- Public successful Admin/MCP response semantics, protocol revision negotiation, dependency/toolchain versions or deployment topology.
|
||
|
||
### Testing Requirements and Commands
|
||
|
||
RED first: prove existing classification divergence and optional-scope bypass before production edits.
|
||
|
||
```bash
|
||
cargo test -p crank-core execution -- --test-threads=1
|
||
cargo test -p crank-runtime --all-targets -- --test-threads=1
|
||
cargo test -p crank-adapter-rest --all-targets -- --test-threads=1
|
||
cargo test -p admin-api --test integration execution_parity -- --test-threads=1
|
||
cargo test -p admin-api --test integration operation_lifecycle -- --test-threads=1
|
||
cargo test -p admin-api --test integration operations_agents -- --test-threads=1
|
||
cargo test -p crank-community-mcp --all-targets -- --test-threads=1
|
||
cargo test -p mcp-server --test integration -- --test-threads=1
|
||
cargo test -p crank-registry --test integration migrations -- --test-threads=1
|
||
cargo test -p crank-registry --test integration observability -- --test-threads=1
|
||
just migration-contract-check
|
||
just sqlx-check
|
||
just config-contract-check
|
||
just metrics-contract-check
|
||
just rust-boundaries
|
||
just capability-inventory-check
|
||
python3 -m unittest discover -s tests/unit
|
||
just authenticated-product-smoke http://localhost:3000
|
||
just verify
|
||
git diff --check
|
||
python3 scripts/check-community-scope.py --root . --files <every NEW/UPDATE tracked candidate>
|
||
```
|
||
|
||
Required assertions:
|
||
|
||
- Admin and MCP normalized outcomes match for all frozen stages; raw wire difference is explicitly projected and snapshot-tested.
|
||
- Every pre-dispatch failure observes adapter call count `0`; every accepted unary execution observes exactly `1`; cancellation/unknown tests record dispatch evidence deterministically without sleeps.
|
||
- Request/Trace IDs match ingress, runtime, captured upstream and history and remain distinct with telemetry sampling/export disabled.
|
||
- Foreign workspace/Agent/Tool probes return one non-disclosing outcome and do not access adapter/history rows of the foreign object.
|
||
- Canary credential, URL, body, parser, SQLx and host path never appears in boundary JSON/MCP content/history message/log/span/metric/evidence.
|
||
- v4→v5 preserves all rows, fresh/replay/rollback/corrupt states are deterministic, N-1 writer/read compatibility is explicit, and no old migration bytes change.
|
||
- No skipped/flaky/retry-promoted mandatory evidence.
|
||
|
||
### Previous Story Intelligence
|
||
|
||
- Story 1.7 now guarantees exact immutable Operation versions, current-Draft test resolution, ETag/CAS lifecycle and pinned Agent behavior. Reuse these facts; do not reimplement lifecycle checks inside runtime.
|
||
- Story 1.7 exposed why persisted diagnostic claims must be honest: legacy fields remain unknown rather than fabricated. Apply the same rule to new v5 classification columns.
|
||
- Story 1.5 provides canonical correlation independent of telemetry sampling; production runtime fallback ID generation is now an anti-pattern.
|
||
- Story 1.6 provides closed stage/outcome metrics and exemplars; extend typed registry only when truly necessary and never mirror the error code as an unbounded label.
|
||
- Story 1.4 requires exact-byte append-only migration authority and version-aware fingerprints. The next schema version is v5.
|
||
- Product owner deferred Reference Deployment performance qualification to Epic 8. Story 1.8 still adds deterministic local overhead/adapter-call regressions but makes no formal NFR-P4 release claim.
|
||
|
||
### Git Intelligence
|
||
|
||
- Current committed baseline `7674284` freezes Story 1.6. Story 1.7 implementation is present in the shared worktree and is a hard predecessor even though it has not been committed by this workflow.
|
||
- Preserve the full existing Story 1.7 diff and `.agents/`; do not reset, stage, commit, push, tag or deploy without explicit owner authorization.
|
||
- Recent patterns to reuse: framework-free typed contracts, closed enums, version-aware MigrationAuthority, SQLx offline metadata, table-driven parity/security tests and explicit Community scan.
|
||
|
||
### Latest Technical Notes
|
||
|
||
- No dependency upgrade or new external library is required. Use locked Rust 1.96.1, Axum 0.8, Tokio 1, SQLx 0.9, Reqwest 0.12 and existing internal abstractions.
|
||
- Tokio cancellation is drop-based; a future being dropped is not itself evidence whether a write reached the upstream. Preserve explicit dispatch evidence and idempotency outcome-unknown cleanup rather than inferring certainty from `JoinError` or message text.
|
||
- Reqwest timeout/transport errors do not universally prove that no bytes reached the peer. Classification must depend on known pipeline/dispatch state; ambiguous mutating calls require manual reconciliation.
|
||
|
||
### References
|
||
|
||
- [Source: `_bmad-output/planning-artifacts/epics.md` — Epic 1, Story 1.8, dependency waves]
|
||
- [Source: `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/prd.md` — FR-2; NFR-P4/R1/S1/S2/S4/S7/S8/O1/O4/O5/C1/C4]
|
||
- [Source: `_bmad-output/planning-artifacts/prds/prd-crank-2026-08-03/addendum.md` — Community and evidence decisions]
|
||
- [Source: `_bmad-output/planning-artifacts/architecture/architecture-crank-2026-08-03/ARCHITECTURE-SPINE.md` — AD-1/9/11/15/19/21/23 and conventions]
|
||
- [Source: `_bmad-output/planning-artifacts/implementation-readiness-report-2026-08-08.md` — FR-2 mapping and story-level NFR evidence requirement]
|
||
- [Source: `_bmad-output/test-artifacts/test-design-progress.md` — E1-R-007 and E1-17/E1-18/E1-19]
|
||
- [Source: `_bmad-output/implementation-artifacts/1-7-immutable-lifecycle-operation.md` — immutable Draft/Published/Agent handoff and owner performance decision]
|
||
- [Source: `_bmad-output/project-context.md` — execution, migration, redaction, testing and boundary rules]
|
||
|
||
## Dev Agent Record
|
||
|
||
### Agent Model Used
|
||
|
||
GPT-5.6 Codex
|
||
|
||
### Debug Log References
|
||
|
||
- `cargo check --workspace --all-targets` — pass.
|
||
- `cargo test -p crank-core --test execution` — 5/5 pass; closed 30-code taxonomy and origin invariants.
|
||
- `cargo test -p crank-runtime --all-targets -- --test-threads=1` — pass; deadline, dispatch certainty, idempotency, confirmation and adapter call-count coverage.
|
||
- `cargo test -p crank-registry --test integration migrations -- --test-threads=1` — 22/22 pass, including honest v4→v5 upgrade.
|
||
- `cargo test -p admin-api --test integration operations_agents -- --test-threads=1` — 7/7 pass.
|
||
- `cargo test -p crank-community-mcp --all-targets -- --test-threads=1` and MCP execution-stage suite — pass.
|
||
- `python3 -m unittest -v tests.unit.test_check_execution_boundaries` and `scripts/check-rust-module-boundaries.sh` — pass.
|
||
- `just sqlx-check`, `just verify-ui`, `git diff --check` — pass.
|
||
- Playwright `operation-lifecycle.spec.js`, `operations.spec.js`, `wizard.spec.js` — 14/14 pass on Chromium real stack.
|
||
- Authenticated product smoke on local split-port stack — pass through create, Draft Test, publish, Agent bind/publish, MCP list/call, edit/archive and pinned MCP call.
|
||
- Explicit Community scan — pass, 129 changed/new files scanned.
|
||
- Final `just verify` — pass, including tooling, inventory/baseline, scope, config/migration/metrics contracts, boundaries, code health, dependency audit, fmt, clippy and full workspace tests.
|
||
- Post-review `just sqlx-check` — pass; all workspace queries compile against refreshed offline metadata.
|
||
- Post-review Playwright `wizard.spec.js` + `operation-lifecycle.spec.js` — 12/12 pass on Chromium.
|
||
- Post-review differential suites: Admin unit 7/7, MCP unit 12/12, Runtime all targets 63/63 and REST adapter integration 10/10 pass.
|
||
|
||
### Completion Notes List
|
||
|
||
- Added a framework-free closed execution taxonomy and canonical success/failure descriptor shared by Admin and MCP.
|
||
- Replaced optional production execution context with a mandatory scoped `RuntimeExecutionRequest`; fallback IDs and production convenience bypasses were removed.
|
||
- Centralized all runtime/protocol error normalization, including typed dispatch evidence and distinct read-only versus mutating deadline semantics.
|
||
- Unified Admin current-Draft Test, direct MCP snapshot calls and approved MCP calls on `execute_outcome`; public success contracts remain compatible and errors gained additive typed fields.
|
||
- Added RU/EN UI localization for stable execution codes while preserving Story 1.7 stale-response and correlation behavior.
|
||
- Added append-only MigrationAuthority v5 and persisted exact operation version, stage, error code, retryability and certainty without fabricating legacy values.
|
||
- Added exhaustive Admin/MCP projection parity tests, redaction/call-count/deadline coverage and a fail-closed execution-boundary scanner.
|
||
- Split MCP request DTOs and migration v5/owned-relation helpers into focused modules to keep legacy files inside code-health ceilings.
|
||
- Updated execution, Admin, MCP, history, observability, data-model and migration documentation. Capability Inventory/baseline remained semantically unchanged because the existing FR-2 flows already point to the refreshed executable evidence; both validators passed.
|
||
- No dependency/toolchain upgrade, deployment-topology change, Story 1.9 outbound-policy claim, commit, push or deployment was performed.
|
||
- Adversarial review closed all 17 High/Medium findings: the envelope, mapping, dispatch certainty, idempotency, persistence, taxonomy, locale, redaction, confirmation, stale-response and executable boundary/parity contracts are now fail-closed and covered by regression tests.
|
||
|
||
### File List
|
||
|
||
- `_bmad-output/implementation-artifacts/1-8-rest-execution-boundary-errors.md`
|
||
- `_bmad-output/implementation-artifacts/sprint-status.yaml`
|
||
- `Cargo.lock`
|
||
- `apps/admin-api/Cargo.toml`
|
||
- `apps/admin-api/src/error.rs`
|
||
- `apps/admin-api/src/service/operations.rs`
|
||
- `apps/admin-api/tests/unit/error.rs`
|
||
- `apps/admin-api/tests/unit/execution_parity.rs`
|
||
- `apps/ui/js/i18n.js`
|
||
- `apps/ui/js/wizard-live.js`
|
||
- `crates/crank-adapter-rest/src/lib.rs`
|
||
- `crates/crank-adapter-rest/tests/integration/client.rs`
|
||
- `crates/crank-community-mcp/src/app.rs`
|
||
- `crates/crank-community-mcp/src/app/invocation_history.rs`
|
||
- `crates/crank-community-mcp/src/app/request.rs`
|
||
- `crates/crank-community-mcp/src/approval_execution.rs`
|
||
- `crates/crank-community-mcp/src/tool_error.rs`
|
||
- `crates/crank-community-mcp/src/app/tests.rs`
|
||
- `crates/crank-community-mcp/tests/unit/tool_error.rs`
|
||
- `crates/crank-core/src/execution.rs`
|
||
- `crates/crank-core/src/ext/protocol.rs`
|
||
- `crates/crank-core/src/lib.rs`
|
||
- `crates/crank-core/src/observability.rs`
|
||
- `crates/crank-core/tests/execution.rs`
|
||
- `crates/crank-registry/src/migrations.rs`
|
||
- `crates/crank-registry/src/migrations/authority.rs`
|
||
- `crates/crank-registry/src/migrations/execution_outcome_v5.rs`
|
||
- `crates/crank-registry/src/migrations/execution_outcome_v5.sql`
|
||
- `crates/crank-registry/src/migrations/owned_relations.rs`
|
||
- `crates/crank-registry/src/migrations/schema_guard.rs`
|
||
- `crates/crank-registry/src/model.rs`
|
||
- `crates/crank-registry/src/postgres/mod.rs`
|
||
- `crates/crank-registry/src/postgres/observability.rs`
|
||
- `crates/crank-registry/tests/integration/agents_usage.rs`
|
||
- `crates/crank-registry/tests/integration/common.rs`
|
||
- `crates/crank-registry/tests/integration/migrations.rs`
|
||
- `crates/crank-runtime/src/auth.rs`
|
||
- `crates/crank-runtime/src/error.rs`
|
||
- `crates/crank-runtime/src/execution_failure.rs`
|
||
- `crates/crank-runtime/src/execution_request.rs`
|
||
- `crates/crank-runtime/src/executor.rs`
|
||
- `crates/crank-runtime/src/lib.rs`
|
||
- `crates/crank-runtime/src/request_context.rs`
|
||
- `crates/crank-runtime/tests/integration.rs`
|
||
- `crates/crank-runtime/tests/integration/confirmation.rs`
|
||
- `crates/crank-runtime/tests/integration/idempotency.rs`
|
||
- `crates/crank-runtime/tests/product_metrics.rs`
|
||
- `crates/crank-runtime/tests/stages.rs`
|
||
- `crates/crank-runtime/tests/support/mod.rs`
|
||
- `docs/README.md`
|
||
- `docs/admin-api.md`
|
||
- `docs/data-model.md`
|
||
- `docs/database-schema.md`
|
||
- `docs/en/migrations.md`
|
||
- `docs/execution-boundary.md`
|
||
- `docs/mcp-interface.md`
|
||
- `docs/migrations.md`
|
||
- `docs/observability.md`
|
||
- `docs/schemas/migration-sequence.json`
|
||
- `scripts/README.md`
|
||
- `scripts/check-execution-boundaries.py`
|
||
- `scripts/check-rust-module-boundaries.sh`
|
||
- `tests/unit/test_check_execution_boundaries.py`
|
||
- `.sqlx/query-*.json` (offline metadata refreshed for affected invocation-history queries in the shared Story 1.7/1.8 worktree)
|
||
|
||
## Change Log
|
||
|
||
- 2026-08-14: Story 1.8 created with a complete typed execution envelope, normalized outcome/error taxonomy, Admin/MCP parity matrix, MigrationAuthority v5 evidence and strict boundary/security scope.
|
||
- 2026-08-15: Story 1.8 implemented and moved to review after full workspace, UI, PostgreSQL, migration, boundary, explicit scope and authenticated REST→MCP qualification passed.
|
||
- 2026-08-15: Adversarial code review fixed all 17 High/Medium findings; post-review workspace, SQLx, migration, boundary and targeted Chromium gates passed, and Story 1.8 moved to done.
|