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

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

control-plane

목적 / 책임

RARA의 핵심 수명주기 상태 모델과 PostgreSQL 영속 계약을 소유한다. 프로젝트, knowledge base, dataset, artifact lineage, workflow, evaluation, release, schedule의 상태와 명시적 승격 경계를 정의한다.

포함 경로

• apps/control-plane/ — 제어 플레인 프로세스 조립과 실행 진입점
• apps/client/ — 향후 제어 플레인 운영 UI를 위한 예약 경로
• packages/go/controlplane/ — 제어 플레인 HTTP surface
• 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 — 현재 제어 플레인 경계와 버전을 노출하는 /v1/status route 등록
• db/migrations/00001_initial.sql — 프로젝트, integration, knowledge, artifact, workflow, evaluation, release, RAG trace 스키마
• db/queries/*.sql — project·knowledge·workflow·trace 상태를 다루는 sqlc 쿼리 원본

유지할 패턴

• release는 candidate, active, retired, failed 상태와 alias별 단일 active 제약을 유지한다.
• artifact는 content hash와 lineage를 보존하고 dataset/release가 artifact identity를 참조하게 한다.
• 스키마와 쿼리를 변경한 뒤 make sqlc로 Go adapter를 재생성한다.
• integration 설정에는 secret 원문 대신 secret reference만 저장한다.

다른 도메인과의 경계

• rag-data-plane: control-plane은 release와 policy의 영속 상태를 소유하고, rag-data-plane은 active release 식별자와 정책을 읽어 온라인 요청을 처리한다.
• 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 제품을 수명주기 모델에 하드코딩하지 않는다.