5.6 KiB
5.6 KiB
SDD: 내구성 있는 Workflow Runtime
위치
- Milestone: Milestone 문서
- Phase: PHASE.md
상태
[승인됨]
SDD 잠금
- 상태: 해제
- 사용자 리뷰: 없음
- 잠금 항목:
- 없음
문제 / 비목표
- 문제: 현재 step queue는 기본 lease와 retry만 제공하며 heartbeat, parent 집계, crash recovery와 Go/Python executor 상호운용이 장시간 작업을 안전하게 닫을 수준으로 완성되지 않았다.
- 비목표:
- 범용 DAG 편집기
- 외부 workflow 엔진의 전체 기능 복제
- RAG 평가와 release 승격 정책 소유
Source of Truth
| 영역 | 기준 | 메모 |
|---|---|---|
| Roadmap | Milestone 문서 | 상태와 완료 범위 원장 |
| Code | Executor Protobuf | 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
- 입력:
workflow_run_id,step_run_id,idempotency_key: 실행 identityexecutor_kind,kind,attempt,deadline: routing과 실행 제한input,input_artifacts: 불변 step 입력
- 출력:
ProgressEvent: sequence가 증가하는 accepted·running·progress·terminal eventJobResult: output과 artifact manifestJobError: 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
- Milestone 기능 Task와 Acceptance Scenario가 일치한다.
- Evidence Map이 code-review/complete.log에서 검증 가능하다.
- executor 계약 원문은 Protobuf 링크로 참조했다.
- 사용자 리뷰가 필요한 항목이 없다.
사용자 리뷰 이력
- 없음
작업 컨텍스트
- 표준선: PostgreSQL lease queue, at-least-once execution, idempotent side effects, terminal progress event
- 후속 SDD: 수집과 Dataset 수명주기