feat(workflow): orchestrate resumable dataflow handoffs

src/govoplan_workflow/backend/schemas.py

@@ -225,3 +225,99 @@ class WorkflowDefinitionActivateRequest(BaseModel):
 class WorkflowDefinitionDeleteResponse(BaseModel):
     deleted: bool
     definition_id: str
+
+
+WorkflowInstanceStatus = Literal[
+    "running",
+    "waiting",
+    "completed",
+    "failed",
+    "cancelled",
+]
+WorkflowStepStatus = Literal[
+    "running",
+    "waiting",
+    "completed",
+    "failed",
+    "cancelled",
+    "superseded",
+]
+
+
+class WorkflowInstanceStartRequest(BaseModel):
+    idempotency_key: str = Field(min_length=1, max_length=255)
+    input: dict[str, Any] = Field(default_factory=dict)
+    correlation_id: str | None = Field(default=None, max_length=128)
+
+
+class WorkflowStepActionRequest(BaseModel):
+    action: Literal[
+        "complete",
+        "approve",
+        "changes",
+        "reject",
+        "resume",
+        "retry",
+        "cancel",
+    ]
+    output: dict[str, Any] = Field(default_factory=dict)
+    evidence: list[str] = Field(default_factory=list, max_length=100)
+    comment: str | None = Field(default=None, max_length=4_000)
+
+
+class WorkflowInstanceStepResponse(BaseModel):
+    id: str
+    sequence: int
+    node_id: str
+    node_type: str
+    status: WorkflowStepStatus
+    attempt: int
+    input: dict[str, Any]
+    output: dict[str, Any]
+    handoff: dict[str, Any]
+    external_ref: str | None
+    started_at: datetime | None
+    finished_at: datetime | None
+    error: str | None
+    completed_by: str | None
+    created_at: datetime
+    updated_at: datetime
+
+
+class WorkflowInstanceEventResponse(BaseModel):
+    id: str
+    sequence: int
+    step_id: str | None
+    kind: str
+    actor_id: str | None
+    payload: dict[str, Any]
+    created_at: datetime
+
+
+class WorkflowInstanceResponse(BaseModel):
+    id: str
+    definition_id: str
+    definition_name: str
+    definition_revision: int
+    definition_hash: str
+    status: WorkflowInstanceStatus
+    idempotency_key: str
+    correlation_id: str | None
+    current_step_id: str | None
+    input: dict[str, Any]
+    context: dict[str, Any]
+    output: dict[str, Any]
+    started_at: datetime
+    finished_at: datetime | None
+    cancellation_requested_at: datetime | None
+    error: str | None
+    created_by: str | None
+    created_at: datetime
+    updated_at: datetime
+    steps: list[WorkflowInstanceStepResponse]
+    events: list[WorkflowInstanceEventResponse]
+    replayed: bool = False
+
+
+class WorkflowInstanceListResponse(BaseModel):
+    instances: list[WorkflowInstanceResponse]