rara/agent-ops/rules/project/domain/control-plane/rules.md

domain	last_rule_review_commit	last_rule_updated_at
control-plane	null	2026-07-18

control-plane

목적 / 책임

RARA의 핵심 수명주기 상태를 소유한다. 프로젝트, knowledge base, dataset, artifact lineage, workflow, evaluation, release, schedule의 관리와 명시적 승격·롤백 경계를 정의한다.

포함 경로

• apps/control-plane/ — 제어 플레인 프로세스 조립과 실행 진입점
• apps/client/ — 향후 제어 플레인 운영 UI를 위한 예약 경로
• packages/go/controlplane/ — 수명주기 관리 HTTP handler
• db/migrations/ — 제어 상태와 lineage의 PostgreSQL 스키마 원본
• db/queries/ — 제어 상태를 다루는 sqlc 쿼리 원본

제외 경로

• packages/go/rag/ — 게시된 release를 소비하는 온라인 RAG 데이터 플레인
• packages/go/workflow/, packages/python/ — 제어 플레인이 만든 작업을 실행하는 worker
• packages/go/database/dbgen/ — sqlc가 생성하는 공통 persistence adapter

주요 구성 요소

• controlplane.Register — 제어 플레인 HTTP route 등록
• db/migrations/00001_initial.sql — 프로젝트·knowledge·workflow·release·trace 등 제어 상태 스키마
• db/queries/*.sql — sqlc 입력이 되는 상태 조회·변경 쿼리

유지할 패턴

• release promotion은 명시적으로 수행하고 production index는 불변 artifact로 취급한다.
• 후보 artifact를 만든 뒤 승격하며 source 삭제와 ACL 변경을 lineage로 추적한다.
• 스키마와 쿼리를 변경한 뒤 make sqlc로 Go adapter를 재생성한다.
• integration 설정에는 secret 원문 대신 secret reference만 저장한다.

다른 도메인과의 경계

• rag-data-plane: control-plane은 release와 policy를 게시하고, rag-data-plane은 해당 식별자와 정책을 해석해 온라인 요청을 처리한다.
• workflow-execution: control-plane은 workflow/job 상태를 소유하고, worker는 lease된 step의 실행과 결과 보고를 담당한다.
• platform-common: 데이터베이스 연결과 공통 HTTP/관측성 구현은 platform-common adapter를 사용한다.

금지 사항

• PostgreSQL을 기본 retrieval backend나 대형 artifact 저장소로 사용하지 않는다.
• 생성된 packages/go/database/dbgen/ 파일을 직접 수정하지 않는다.
• 특정 retrieval, model, artifact 제품을 수명주기 모델에 하드코딩하지 않는다.