# SDD: 내구성 있는 Workflow Runtime

## 위치

- Milestone: [Milestone 문서](../../../phase/workflow-automation/milestones/durable-workflow-runtime.md)
- Phase: [PHASE.md](../../../phase/workflow-automation/PHASE.md)

## 상태

[승인됨]

## SDD 잠금

- 상태: 해제
- 사용자 리뷰: 없음
- 잠금 항목:
  - 없음

## 문제 / 비목표

- 문제: 현재 step queue는 기본 lease와 retry만 제공하며 heartbeat, parent 집계, crash recovery와 Go/Python executor 상호운용이 장시간 작업을 안전하게 닫을 수준으로 완성되지 않았다.
- 비목표:
  - 범용 DAG 편집기
  - 외부 workflow 엔진의 전체 기능 복제
  - RAG 평가와 release 승격 정책 소유

## Source of Truth

| 영역 | 기준 | 메모 |
|------|------|------|
| Roadmap | [Milestone 문서](../../../phase/workflow-automation/milestones/durable-workflow-runtime.md) | 상태와 완료 범위 원장 |
| Code | [Executor Protobuf](../../../../api/proto/rara/v1/executor.proto) | Go/Python 실행 wire contract |
| External Provider | 없음 | PostgreSQL과 executor가 내부 source of truth를 사용한다 |
| User Decision | 없음 | at-least-once와 idempotent side effect 방향이 확정되어 있다 |

## State Machine

| 상태 | 진입 조건 | 다음 상태 | 근거 |
|------|-----------|-----------|------|
| pending | step이 생성되고 dependency가 충족됨 | leased, cancelled | queue row |
| leased | worker가 만료 시간과 owner를 획득함 | running, retryable_failed, terminal_failed, cancelled | lease mutation |
| running | owner가 실행 시작을 확정함 | succeeded, retryable_failed, terminal_failed, cancelled | progress event |
| retryable_failed | 재시도 가능하고 attempt가 남음 | leased, cancelled | retry policy |
| succeeded | 결과와 artifact가 영속화됨 | 없음 | terminal event |
| terminal_failed | 재시도 불가 또는 attempt 소진 | 없음 | terminal event |
| cancelled | 취소가 확정되고 executor가 종료됨 | 없음 | cancel event |

## Interface Contract

- 계약 원문: [Executor Protobuf](../../../../api/proto/rara/v1/executor.proto)
- 입력:
  - `workflow_run_id`, `step_run_id`, `idempotency_key`: 실행 identity
  - `executor_kind`, `kind`, `attempt`, `deadline`: routing과 실행 제한
  - `input`, `input_artifacts`: 불변 step 입력
- 출력:
  - `ProgressEvent`: sequence가 증가하는 accepted·running·progress·terminal event
  - `JobResult`: output과 artifact manifest
  - `JobError`: stable code, retryable과 details
- 금지:
  - 유효 lease owner가 아닌 worker가 상태나 결과를 갱신하지 않는다.
  - terminal 상태에서 비terminal 상태로 되돌리지 않는다.
  - job payload와 progress에 secret 원문을 넣지 않는다.

## Acceptance Scenarios

| ID | Milestone Task | Given | When | Then |
|----|----------------|-------|------|------|
| S01 | `run-state` | 여러 step을 가진 workflow run | step terminal 상태가 반영됨 | parent run이 허용된 집계 상태로만 전이한다 |
| S02 | `lease-heartbeat` | 경쟁 worker와 짧은 lease | lease·heartbeat·expiry 실행 | 한 owner만 완료하고 만료 lease는 회수된다 |
| S03 | `retry-idempotency` | retryable error와 동일 idempotency key | 재실행 | attempt와 backoff가 증가하고 side effect는 중복되지 않는다 |
| S04 | `cancel-timeout` | leased·running Go/Python job | cancel 또는 deadline | executor와 DB 상태가 cancelled 또는 terminal failure로 닫힌다 |
| S05 | `executor-routing` | capability가 다른 Go·Python executor | job routing | 호환 executor만 수락하고 나머지는 실행 전 거부한다 |
| S06 | `progress-artifacts` | sequence event와 artifact 결과 | event 반영 | 순서·terminal·lineage가 영속 상태에 보존된다 |
| S07 | `restart-smoke` | 실행 중 worker crash | lease expiry 뒤 worker restart | orphan step을 회수하고 완료·실패 결과가 유실되지 않는다 |

## Evidence Map

| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
|----------|-------------------|------------------|---------------------------|
| S01 | run·step state transition test | `agent-task/m-durable-workflow-runtime/...` | `run-state` transition matrix |
| S02 | concurrent lease와 heartbeat integration test | `agent-task/m-durable-workflow-runtime/...` | `lease-heartbeat` single-owner evidence |
| S03 | retry·idempotency fault injection | `agent-task/m-durable-workflow-runtime/...` | `retry-idempotency` no-duplicate evidence |
| S04 | Go·Python cancel·deadline smoke | `agent-task/m-durable-workflow-runtime/...` | `cancel-timeout` terminal evidence |
| S05 | capability routing matrix | `agent-task/m-durable-workflow-runtime/...` | `executor-routing` accept·reject evidence |
| S06 | progress ordering과 artifact lineage test | `agent-task/m-durable-workflow-runtime/...` | `progress-artifacts` persistence evidence |
| S07 | PostgreSQL·worker restart field smoke | `agent-task/m-durable-workflow-runtime/...` | `restart-smoke` recovery evidence |

## Cross-repo Dependencies

- 없음

## Drift Check

- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
- [x] executor 계약 원문은 Protobuf 링크로 참조했다.
- [x] 사용자 리뷰가 필요한 항목이 없다.

## 사용자 리뷰 이력

- 없음

## 작업 컨텍스트

- 표준선: PostgreSQL lease queue, at-least-once execution, idempotent side effects, terminal progress event
- 후속 SDD: [수집과 Dataset 수명주기](../../knowledge-lifecycle/ingestion-and-dataset-lifecycle/SDD.md)