update domain rules and README

README.md

@@ -1,80 +1,78 @@
 # RARA
 
-RARA is an internal, storage-agnostic platform for operating the complete RAG
-lifecycle and promoting verified data into optional LoRA/QLoRA workflows.
+RARA는 저장소와 모델 제품에 종속되지 않고 RAG 전체 수명주기를 운영하기 위한 내부
+플랫폼이다. 검증된 데이터를 선택적으로 LoRA/QLoRA workflow로 연결하는 경계까지
+포함한다.
 
-RARA owns the logical RAG contract end to end:
+RARA가 다루는 논리적 수명주기는 다음과 같다.
 
-- source synchronization and normalization
-- versioned datasets and artifact lineage
-- retrieval, reranking, context assembly, and answer generation
-- evaluation, release promotion, and rollback
-- training-candidate curation and adaptation execution
+- source 동기화와 정규화
+- versioned dataset과 artifact lineage
+- retrieval, reranking, context 조립, 답변 생성
+- 평가, release 승격, rollback
+- 학습 후보 선별과 adaptation 실행
 
-Physical retrieval stores, artifact stores, model providers, and executors stay
-replaceable behind capability-aware integrations.
+실제 retrieval store, artifact store, model provider, executor는
+capability-aware integration 뒤에서 교체할 수 있도록 분리한다.
 
-## Repository layout
+## 현재 상태
 
-```text
-apps/
-  control-plane/   Go lifecycle and management API
-  rag-api/         Go online retrieve/answer data plane
-  worker/          Go workflow step worker
-  client/          reserved for the operations UI
-api/
-  openapi/         public HTTP API contract
-  proto/           internal Go/Python executor contract
-packages/
-  go/              shared Go packages
-  python/          Python adaptation worker
-db/
-  migrations/      PostgreSQL schema migrations
-  queries/         sqlc queries
-configs/           service configuration examples
-deploy/            local deployment assets
-```
+현재 저장소는 플랫폼 scaffold 단계다. Control Plane, 온라인 RAG API, Go workflow
+worker, Python executor의 실행 기준선과 계약·데이터베이스·관측성 골격을 제공한다.
+실제 retrieval backend, model provider, source connector, production workflow는
+하드코딩하지 않고 versioned integration으로 확장한다.
 
-## Baseline
+기술 기준선은 Go 1.26, Python 3.12, PostgreSQL 18, OpenAPI 3.1,
+Protobuf/gRPC, HTTP/JSON, SSE다.
 
-- Go 1.26
-- Python 3.12
-- PostgreSQL 18
-- Protobuf for internal executor contracts
-- HTTP/JSON and SSE for the public RAG API
+PostgreSQL은 필수 control-state 및 lineage 저장소다. 기본 RAG retrieval backend로
+사용하지 않으며 SQLite fallback도 제공하지 않는다.
 
-PostgreSQL is the required control-state database. It is not the default RAG
-retrieval backend and there is no SQLite fallback.
+## 빠른 시작
 
-## Development
+로컬 개발에는 Go 1.26, Python 3.12, `protoc`, Make가 필요하다. PostgreSQL을
+컨테이너로 실행하려면 Docker Compose도 필요하다.
 
-The local prerequisites are Go, Python, and `protoc`. `make setup` installs
-version-pinned Go code-generation tools under `.tools/` and creates `.venv/`.
-
-Bootstrap the Python environment and generate contracts:
+Python 개발 환경과 version-pinned code generation 도구를 준비하고 생성물을
+동기화한다.
 
 ```sh
 make setup
 ```
 
-Run checks and build the three Go services:
-
-```sh
-make test
-make build
-```
-
-Start PostgreSQL when a container runtime is available:
+로컬 PostgreSQL을 시작하고 migration을 적용한다.
 
 ```sh
 make db-up
 make migrate-up
 ```
 
-The current workspace may instead use an external PostgreSQL instance through
-`RARA_DATABASE_URL`.
+테스트를 실행하고 세 Go 서비스를 빌드한다.
 
-Run services after PostgreSQL is migrated:
+```sh
+make test
+make build
+```
+
+## 주요 명령
+
+| 목적 | 명령 | 비고 |
+|------|------|------|
+| 전체 로컬 검증 | `make all` | setup, format, test, build 순서로 실행 |
+| 개발 환경 및 생성물 준비 | `make setup` | `.tools/`, `.venv/` 준비 후 Protobuf와 sqlc 생성 |
+| Protobuf와 sqlc 생성 | `make generate` | `make proto`, `make sqlc` 실행 |
+| 코드 format/lint | `make fmt` | Go `gofmt`, Python Ruff format 및 autofix |
+| 전체 테스트 | `make test` | Go와 Python 테스트 실행 |
+| Go 테스트 | `make test-go` | `go test ./...` |
+| Python 테스트 | `make test-python` | pytest 실행 |
+| Go 서비스 빌드 | `make build` | 결과물을 `bin/`에 생성 |
+| PostgreSQL 시작/종료 | `make db-up` / `make db-down` | `deploy/compose.yaml` 사용 |
+| migration 적용/되돌리기 | `make migrate-up` / `make migrate-down` | Goose 사용 |
+| migration 상태 확인 | `make migrate-status` | 기본 `DATABASE_URL` 사용 |
+
+## 서비스 실행
+
+PostgreSQL migration과 `make build`가 끝나면 Go 서비스를 실행할 수 있다.
 
 ```sh
 bin/rara-control-plane --config configs/control-plane.yaml
@@ -82,18 +80,89 @@ bin/rara-rag-api --config configs/rag-api.yaml
 bin/rara-worker --config configs/worker.yaml
 ```
 
-The Python executor starts with:
+Python executor는 `make setup` 후 다음 명령으로 실행한다.
 
 ```sh
 .venv/bin/rara-python-worker
 ```
 
-ML dependencies are optional. Install
-`packages/python[training]` or `packages/python[training,quantized]` only on
-hosts that execute adaptation jobs.
+ML dependency는 선택 사항이다. adaptation job을 실행하는 호스트에만
+`packages/python[training]` 또는 `packages/python[training,quantized]` extra를
+설치한다.
 
-## Status
+## 구조
 
-This repository currently contains the platform scaffold. Retrieval backends,
-model providers, source connectors, and production workflows are added as
-versioned integrations rather than hard-coded infrastructure.
+| 경로 | 역할 |
+|------|------|
+| `apps/control-plane/` | Go lifecycle 및 management API 진입점 |
+| `apps/rag-api/` | Go 온라인 retrieve/answer data plane 진입점 |
+| `apps/worker/` | Go workflow step worker 진입점 |
+| `apps/client/` | 향후 operations UI 영역 |
+| `api/openapi/` | 공개 HTTP/JSON 및 SSE 계약 |
+| `api/proto/` | Go/Python executor 사이의 내부 gRPC 계약 |
+| `packages/go/` | Go 도메인 로직, port, 공통 runtime adapter |
+| `packages/python/` | Python adaptation executor와 테스트 |
+| `db/migrations/`, `db/queries/` | PostgreSQL schema와 sqlc query 원본 |
+| `gen/` | Protobuf에서 생성된 Go 코드 |
+| `configs/` | 서비스별 로컬 설정 예시 |
+| `deploy/` | 로컬 PostgreSQL 및 container build 자산 |
+| `agent-ops/`, `agent-roadmap/` | 작업 규칙, skill, 제품 roadmap |
+
+## 구성과 환경 변수
+
+Go 서비스의 기본 설정은 `configs/*.yaml`에 있다. 공통 환경 변수는 YAML 값을
+override한다.
+
+| 이름 | 설명 | 필수 |
+|------|------|------|
+| `RARA_DATABASE_URL` | Go 서비스가 사용할 PostgreSQL URL | 아니요 |
+| `RARA_DATABASE_MAX_CONNECTIONS` | PostgreSQL 최대 connection 수 | 아니요 |
+| `RARA_DATABASE_MIN_CONNECTIONS` | PostgreSQL 최소 connection 수 | 아니요 |
+| `RARA_ARTIFACT_ROOT` | filesystem artifact root | 아니요 |
+| `RARA_LOG_LEVEL` | logging level | 아니요 |
+| `RARA_OTEL_ENDPOINT` | OpenTelemetry collector endpoint | 아니요 |
+| `RARA_LISTEN` | Go 서비스 listen address | 아니요 |
+| `RARA_WORKER_ID` | Go worker 식별자 | 아니요 |
+| `RARA_WORKER_EXECUTOR_KIND` | Go worker executor kind | 아니요 |
+| `RARA_WORKER_POLL_INTERVAL` | workflow polling 주기 | 아니요 |
+| `RARA_WORKER_LEASE_DURATION` | workflow lease 기간 | 아니요 |
+| `RARA_PYTHON_LISTEN_HOST` | Python executor listen host, 기본 `0.0.0.0` | 아니요 |
+| `RARA_PYTHON_LISTEN_PORT` | Python executor listen port, 기본 `19090` | 아니요 |
+
+Make migration target에 외부 PostgreSQL을 지정할 때는 `RARA_DATABASE_URL`이 아니라
+Make 변수 `DATABASE_URL`을 전달한다.
+
+```sh
+make migrate-up DATABASE_URL='postgres://user:password@host:5432/rara?sslmode=require'
+```
+
+## 개발 흐름
+
+- `api/proto/`와 `db/migrations/`, `db/queries/`를 생성 코드의 원본으로 취급한다.
+- `gen/go/`, `packages/python/src/rara/v1/*_pb2*.py`,
+  `packages/go/database/dbgen/`은 직접 수정하지 않고 `make proto` 또는 `make sqlc`로
+  갱신한다.
+- 공개 RAG handler 변경 시 `api/openapi/rara-v1.yaml`과 HTTP/JSON 및 SSE 동작을
+  함께 검토한다.
+- executor wire contract 변경 시 Protobuf 호환성을 유지하고 Go/Python 생성물을 함께
+  갱신한다.
+- 변경 후 기본 검증은 `make test`와 `make build`다.
+
+## 작업 맥락
+
+사람과 AI agent 모두 작업 전에 루트 [`AGENTS.md`](AGENTS.md)와 매칭되는
+[`domain rule`](agent-ops/rules/project/domain/)을 먼저 확인한다. 현재 제품 방향은
+공유 [`Roadmap`](agent-roadmap/ROADMAP.md)에서, 활성 Milestone 후보는 로컬
+`agent-roadmap/current.md`가 있을 때 해당 파일에서 확인한다. README에는 특정 작업
+위치를 고정하지 않는다.
+
+요청 범위를 넘어 플랫폼 경계를 확장하지 않는다. PostgreSQL에는 control state와
+lineage만 저장하고, 대형 artifact와 retrieval index는 integration port 뒤에 둔다.
+
+## 참고 문서
+
+- [Architecture](ARCHITECTURE.md)
+- [공개 RAG API 계약](api/openapi/rara-v1.yaml)
+- [내부 executor 계약](api/proto/rara/v1/executor.proto)
+- [프로젝트 작업 규칙](agent-ops/rules/project/rules.md)
+- [Roadmap](agent-roadmap/ROADMAP.md)

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

@@ -1,6 +1,6 @@
 ---
 domain: control-plane
-last_rule_review_commit: null
+last_rule_review_commit: d4546ecbfdd0e166b8c634092c0d7c5009618cea
 last_rule_updated_at: 2026-07-18
 ---
 
@@ -8,13 +8,13 @@ last_rule_updated_at: 2026-07-18
 
 ## 목적 / 책임
 
-RARA의 핵심 수명주기 상태를 소유한다. 프로젝트, knowledge base, dataset, artifact lineage, workflow, evaluation, release, schedule의 관리와 명시적 승격·롤백 경계를 정의한다.
+RARA의 핵심 수명주기 상태 모델과 PostgreSQL 영속 계약을 소유한다. 프로젝트, knowledge base, dataset, artifact lineage, workflow, evaluation, release, schedule의 상태와 명시적 승격 경계를 정의한다.
 
 ## 포함 경로
 
 - `apps/control-plane/` — 제어 플레인 프로세스 조립과 실행 진입점
 - `apps/client/` — 향후 제어 플레인 운영 UI를 위한 예약 경로
-- `packages/go/controlplane/` — 수명주기 관리 HTTP handler
+- `packages/go/controlplane/` — 제어 플레인 HTTP surface
 - `db/migrations/` — 제어 상태와 lineage의 PostgreSQL 스키마 원본
 - `db/queries/` — 제어 상태를 다루는 sqlc 쿼리 원본
 
@@ -26,20 +26,20 @@ RARA의 핵심 수명주기 상태를 소유한다. 프로젝트, knowledge base
 
 ## 주요 구성 요소
 
-- `controlplane.Register` — 제어 플레인 HTTP route 등록
-- `db/migrations/00001_initial.sql` — 프로젝트·knowledge·workflow·release·trace 등 제어 상태 스키마
-- `db/queries/*.sql` — sqlc 입력이 되는 상태 조회·변경 쿼리
+- `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 promotion은 명시적으로 수행하고 production index는 불변 artifact로 취급한다.
-- 후보 artifact를 만든 뒤 승격하며 source 삭제와 ACL 변경을 lineage로 추적한다.
+- 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은 해당 식별자와 정책을 해석해 온라인 요청을 처리한다.
+- **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를 사용한다.
 
@@ -48,4 +48,3 @@ RARA의 핵심 수명주기 상태를 소유한다. 프로젝트, knowledge base
 - PostgreSQL을 기본 retrieval backend나 대형 artifact 저장소로 사용하지 않는다.
 - 생성된 `packages/go/database/dbgen/` 파일을 직접 수정하지 않는다.
 - 특정 retrieval, model, artifact 제품을 수명주기 모델에 하드코딩하지 않는다.
-

agent-ops/rules/project/domain/platform-common/rules.md

@@ -1,6 +1,6 @@
 ---
 domain: platform-common
-last_rule_review_commit: null
+last_rule_review_commit: d4546ecbfdd0e166b8c634092c0d7c5009618cea
 last_rule_updated_at: 2026-07-18
 ---
 
@@ -30,16 +30,18 @@ last_rule_updated_at: 2026-07-18
 
 - `database.Store` — pgx pool과 생성된 sqlc query 접근점
 - `artifact.Store` / `artifact.Filesystem` — artifact 저장 port와 로컬 구현
-- `integration.Ports` — 외부 capability의 제품 중립 계약
+- `integration.Registry` / `integration.Factory` — manifest 이름으로 외부 integration factory를 조회·구성하는 계약
+- `integration.SourceConnector`, `RetrievalBackend`, `EmbeddingProvider`, `RerankProvider`, `GenerationProvider`, `SecretResolver` — 제품 중립 capability port
 - `httpserver.Start` — 공통 HTTP lifecycle
 - `observability.SetupTracing` — trace exporter 설정
 
 ## 유지할 패턴
 
 - 공통 패키지는 plane별 정책을 소유하지 않고 작은 port와 lifecycle adapter에 집중한다.
-- integration instance는 versioned capability와 secret reference로 구성한다.
+- integration manifest는 schema version과 capability를 노출하고 factory에는 config와 secret reference만 전달한다.
 - artifact URI와 content hash를 유지해 lineage를 추적할 수 있게 한다.
-- readiness는 실제 필수 dependency 상태를 반영하고 health와 구분한다.
+- filesystem artifact key는 configured root 밖으로 벗어나는 절대 경로와 traversal을 거부한다.
+- readiness는 각 앱이 주입한 필수 dependency 상태를 반영하고 health와 구분한다.
 - 설정 예시에는 로컬 기본값만 두며 운영 secret을 포함하지 않는다.
 
 ## 다른 도메인과의 경계
@@ -53,4 +55,3 @@ last_rule_updated_at: 2026-07-18
 - 공통 패키지에 control-plane, RAG, workflow의 유즈케이스 정책을 넣지 않는다.
 - integration port를 특정 vendor의 request/response 타입으로 노출하지 않는다.
 - config, log, trace, 예제 배포 파일에 secret이나 credential 원문을 남기지 않는다.
-

agent-ops/rules/project/domain/rag-data-plane/rules.md

@@ -1,6 +1,6 @@
 ---
 domain: rag-data-plane
-last_rule_review_commit: null
+last_rule_review_commit: d4546ecbfdd0e166b8c634092c0d7c5009618cea
 last_rule_updated_at: 2026-07-18
 ---
 
@@ -25,16 +25,17 @@ last_rule_updated_at: 2026-07-18
 ## 주요 구성 요소
 
 - `rag.Handler` — `/v1/retrieve`, `/v1/answer` 요청 검증과 응답 변환
-- `rag.ReleaseResolver` — project, knowledge base, alias로 활성 release 해석
+- `rag.PostgreSQLReleaseResolver` — project, knowledge base, alias로 PostgreSQL의 active release 해석
 - `rag.Engine` — retrieval과 generation 구현을 교체하기 위한 도메인 port
+- `rag.UnavailableEngine` — integration 미구성 상태를 503으로 노출하는 기본 engine
 - `api/openapi/rara-v1.yaml` — 공개 요청·응답 및 오류 스키마
 
 ## 유지할 패턴
 
-- 모든 온라인 요청은 knowledge base와 release alias를 해석하고 응답에 release identity를 포함한다.
+- 성공한 온라인 요청은 knowledge base와 release alias를 해석하고 응답에 release와 trace identity를 포함한다.
 - release alias가 없으면 `production`, `top_k`가 없으면 10을 사용하며 검증 범위는 OpenAPI와 handler가 일치해야 한다.
 - engine 구현은 capability-aware integration 뒤에 두고 handler가 특정 제품 SDK에 의존하지 않게 한다.
-- streaming 응답은 SSE event와 오류 의미를 비 streaming JSON 응답과 호환되게 유지한다.
+- `stream=true` 응답의 `completed`/`error` SSE event 집합을 변경할 때는 OpenAPI 설명과 handler를 함께 갱신한다.
 
 ## 다른 도메인과의 경계
 
@@ -47,4 +48,3 @@ last_rule_updated_at: 2026-07-18
 - 요청 시점에 candidate release를 암묵적으로 production으로 승격하지 않는다.
 - handler에 특정 vector store, reranker, model provider를 직접 결합하지 않는다.
 - 공개 handler 변경 시 OpenAPI와 JSON/SSE 오류 계약 검토를 생략하지 않는다.
-

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

@@ -1,6 +1,6 @@
 ---
 domain: workflow-execution
-last_rule_review_commit: null
+last_rule_review_commit: d4546ecbfdd0e166b8c634092c0d7c5009618cea
 last_rule_updated_at: 2026-07-18
 ---
 
@@ -8,7 +8,7 @@ last_rule_updated_at: 2026-07-18
 
 ## 목적 / 책임
 
-제어 플레인이 만든 workflow step을 lease하고 실행 상태를 보고한다. Go executor와 Python adaptation executor 사이의 버전 있는 실행 계약 및 취소·진행·결과 의미를 책임진다.
+Go worker가 제어 플레인의 workflow step을 lease해 in-process executor registry로 실행하고 결과 상태를 갱신한다. 별도 Python executor는 버전 있는 gRPC 계약으로 capability, streaming 진행, 취소와 결과 의미를 제공한다.
 
 ## 포함 경로
 
@@ -27,20 +27,21 @@ last_rule_updated_at: 2026-07-18
 ## 주요 구성 요소
 
 - `workflow.Worker` — 실행 가능한 step을 lease하고 executor 결과에 따라 상태 갱신
-- `workflow.Registry` — operation 이름과 Go executor 구현 연결
-- `ExecutorService` — Python capability 조회, streaming 실행, 취소 gRPC 서비스
+- `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 소유권과 재시도 의미를 보존한다.
-- executor operation과 capability는 명시적 이름과 버전으로 등록한다.
-- ML 라이브러리 실행과 LoRA/QLoRA adaptation은 Python executor가 담당하고 제어 상태는 PostgreSQL이 소유한다.
+- 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와 job의 영속 상태는 control-plane 소유이며 이 도메인은 lease된 실행과 결과만 처리한다.
+- **control-plane**: workflow와 step run의 영속 스키마는 control-plane 소유이며 이 도메인은 lease된 실행과 결과 갱신만 처리한다.
 - **rag-data-plane**: 온라인 요청 경로를 worker에서 처리하지 않고, workflow가 만든 artifact를 release 승격 뒤 소비하게 한다.
 - **platform-common**: database, config, observability, artifact와 integration port는 공통 adapter에 위임한다.
 
@@ -49,4 +50,3 @@ last_rule_updated_at: 2026-07-18
 - `gen/go/rara/v1/`과 `packages/python/src/rara/v1/*_pb2*.py`를 직접 수정하지 않는다.
 - lease 없이 step을 실행하거나 다른 worker 소유의 step 상태를 완료 처리하지 않는다.
 - secret 원문이나 제품별 credential을 job payload와 추적 문서에 기록하지 않는다.
-