rara/agent-ops/rules/project/domain/workflow-execution/rules.md

domain	last_rule_review_commit	last_rule_updated_at
workflow-execution	d4546ecbfd	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와 추적 문서에 기록하지 않는다.