---
domain: workflow-execution
last_rule_review_commit: d4546ecbfdd0e166b8c634092c0d7c5009618cea
last_rule_updated_at: 2026-07-18
---

# workflow-execution

## 목적 / 책임

Go worker가 제어 플레인의 workflow step을 lease해 in-process executor registry로 실행하고 결과 상태를 갱신한다. 별도 Python executor는 버전 있는 gRPC 계약으로 capability, streaming 진행, 취소와 결과 의미를 제공한다.

## 포함 경로

- `apps/worker/` — Go workflow worker 프로세스 조립과 실행 진입점
- `packages/go/workflow/` — step lease, executor registry, 재시도와 상태 전이
- `packages/python/` — Python gRPC executor와 adaptation 실행 구현
- `api/proto/` — Go/Python executor wire contract 원본
- `gen/go/rara/v1/` — Protobuf에서 생성된 Go 타입과 gRPC stub

## 제외 경로

- `packages/go/controlplane/`, `db/migrations/` — workflow 정의와 영속 상태의 소유권
- `packages/go/rag/` — 온라인 retrieve/answer 요청 처리
- `packages/go/integration/` — 제품 중립적인 외부 capability port

## 주요 구성 요소

- `workflow.Worker` — 실행 가능한 step을 lease하고 executor 결과에 따라 상태 갱신
- `workflow.Registry` — operation 이름과 in-process Go executor 구현 연결
- `rara_worker.server.ExecutorService` — Python capability 조회, streaming 실행, 취소 gRPC 서비스
- `api/proto/rara/v1/executor.proto` — job, progress, artifact, error 계약

## 유지할 패턴

- worker identity, lease duration, retry delay를 설정에서 읽고 lease 소유권과 재시도 의미를 보존한다.
- Go executor operation은 명시적 이름으로 registry에 등록하고, Python capability는 이름과 버전을 응답한다.
- Go worker의 상태 변경은 `leased_by`와 현재 step 상태 조건을 유지한다.
- Python executor는 `accepted`, `running`, `succeeded`/`failed`/`cancelled` event 순서와 구조화된 오류를 유지한다.
- Protobuf 변경은 기존 field number를 재사용하지 않고 Go/Python 생성물을 `make proto`로 함께 갱신한다.

## 다른 도메인과의 경계

- **control-plane**: workflow와 step run의 영속 스키마는 control-plane 소유이며 이 도메인은 lease된 실행과 결과 갱신만 처리한다.
- **rag-data-plane**: 온라인 요청 경로를 worker에서 처리하지 않고, workflow가 만든 artifact를 release 승격 뒤 소비하게 한다.
- **platform-common**: database, config, observability, artifact와 integration port는 공통 adapter에 위임한다.

## 금지 사항

- `gen/go/rara/v1/`과 `packages/python/src/rara/v1/*_pb2*.py`를 직접 수정하지 않는다.
- lease 없이 step을 실행하거나 다른 worker 소유의 step 상태를 완료 처리하지 않는다.
- secret 원문이나 제품별 credential을 job payload와 추적 문서에 기록하지 않는다.