Improve Workflow Run State-Transition APIs

[raylrui]

Summary

Resolve #175,
Couple with RP: OrcaBus/service-shared-resources#26 for verified permission.

This PR replaces the generic workflow-run state creation APIs with dedicated action endpoints for deprecating, resolving, and cancelling one or more workflow runs.

The target state is determined by the endpoint instead of a client-supplied status. This simplifies authorization with AWS Verified Permissions because permissions no longer depend on inspecting the request payload.

API Changes

New Endpoints

POST /api/v1/workflowrun/state/deprecate
POST /api/v1/workflowrun/state/resolve
POST /api/v1/workflowrun/state/cancel

All three endpoints accept the following request body:

{
  "workflowrunOrcabusIds": [
    "wfr.xxxxxxxxx",
    "wfr.yyyyyyyyy"
  ],
  "comment": "Reason for the transition"
}

Each endpoint supports one or more workflow-run OrcaBus IDs.

Validation Map Endpoint

The validation-map endpoint has moved so that it no longer requires a workflow-run ID:

GET /api/v1/workflowrun/state/get_states_transition_validation_map/

Removed Endpoints

The following endpoints are no longer available:

POST /api/v1/workflowrun/{orcabusId}/state/
POST /api/v1/workflowrun/state/batch-state-transition/
GET  /api/v1/workflowrun/{orcabusId}/state/get_states_transition_validation_map/

Transition Rules

Existing state-transition rules are preserved:

Target state	Allowed source state
DEPRECATED	SUCCEEDED
RESOLVED	FAILED
CANCELLED	Supported non-terminal states

Existing no-state and excluded-state behaviour remains unchanged.

State Creation and WRSC Events

The existing state creation and WRSC event flow remains intact:

• Each workflow run is validated independently.
• Each state is created inside an atomic transaction.
• create_state_and_emit_wrsc is called for every successful transition.
• If WRSC emission fails, the newly created state is rolled back.
• A failure for one workflow run does not prevent other workflow runs from being processed.
• Existing partial-success responses and failure reasons are preserved.

Response Example

{
  "createdCount": 1,
  "workflowrunOrcabusIds": [
    "wfr.xxxxxxxxx"
  ],
  "failedCount": 1,
  "failures": [
    {
      "workflowrunOrcabusId": "wfr.yyyyyyyyy",
      "reason": "INVALID_TRANSITION",
      "detail": "Invalid state transition."
    }
  ]
}

Response Statuses

Status	Description
201 Created	All requested transitions succeeded
207 Multi-Status	Some transitions succeeded and some failed
400 Bad Request	All failures were caused by missing workflow runs or invalid transitions
500 Internal Server Error	State creation failed
502 Bad Gateway	WRSC event emission failed

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Replaces generic workflow-run state creation with dedicated multi-run transition actions.

Changes:

• Adds deprecate, resolve, and cancel endpoints.
• Moves transition-map lookup to a non-nested route.
• Updates serializers and transition tests.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
app/workflow_manager/viewsets/state.py	Implements dedicated transition actions.
app/workflow_manager/urls/base.py	Registers the new routes.
app/workflow_manager/tests/test_state_viewset.py	Updates transition API tests.
app/workflow_manager/serializers/state.py	Defines shared request and response contracts.

Suppressed comments (2)

app/workflow_manager/viewsets/state.py:401

• This action's OpenAPI schema advertises only 201, but _state_transition also returns the contractually documented 207, 400, 500, and 502 responses. Generated Swagger clients therefore omit valid response shapes; document every status here, including the serializer-validation form of the 400 response.

    @extend_schema(
        request=StateTransitionRequestSerializer,
        responses={201: StateTransitionResponseSerializer},

app/workflow_manager/viewsets/state.py:411

• This action's OpenAPI schema advertises only 201, but _state_transition also returns the contractually documented 207, 400, 500, and 502 responses. Generated Swagger clients therefore omit valid response shapes; document every status here, including the serializer-validation form of the 400 response.

    @extend_schema(
        request=StateTransitionRequestSerializer,
        responses={201: StateTransitionResponseSerializer},

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[raylrui]

Frontend PR for this API migration.
v1: OrcaBus/orca-ui#291;
v2: OrcaBus/orca-ui-v2#42.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 11 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Suppressed comments (1)

infrastructure/stage/stack.ts:211

• This exact route protects only /resolve, while the optional-slash Django router and generated schema also expose /resolve/. The trailing-slash request is handled by the generic POST /{proxy+} route instead, so it skips the Verified Permissions authorizer and can bypass the admin-only resolution policy. Please protect both spellings or reject the unprotected one.

      routeKey: HttpRouteKey.with(`/api/${API_VERSION}/workflowrun/state/resolve`, HttpMethod.POST),

[raylrui]

FIY @victorskl @alexiswl ,

Workflow Run State-Transition APIs changed, include Validation Map Endpoint and batch State-Transition Endpoint.

No Database models changed.