diff --git a/agent-test/README.md b/agent-test/README.md new file mode 100644 index 0000000..0a451d3 --- /dev/null +++ b/agent-test/README.md @@ -0,0 +1,35 @@ +# agent-test 환경 기준 + +이 디렉터리는 RARA의 환경별 실행 기준과 도메인별 smoke profile을 둔다. + +## 기본 환경 + +- 사용자가 환경을 별도로 지정하지 않으면 기본 테스트 환경은 원격 `dev`다. +- `dev`의 기준 runner는 `ssh toki@toki-labs.com`이며, 목표 checkout은 + `/Users/toki/agent-work/rara-dev`다. +- `local`은 현재 checkout에서 빠르게 수행하는 source 단위 검증이나 사용자가 + 명시적으로 local을 요청한 경우에만 사용한다. +- 원격 checkout이 없거나 현재 변경과 동기화되지 않았으면 local 결과로 원격 + evidence를 대신하지 않고 setup/sync 차단 사유를 보고한다. + +## 환경 구조 + +- 환경 공통값과 프리플라이트는 `agent-test//rules.md`에 둔다. +- 반복해서 읽어야 하는 runner, checkout, port 상태는 + `agent-test//inventory.yaml`에 둔다. +- 도메인별 검증 기준은 `agent-test//-smoke.md`에 둔다. +- secret, token, password, private key, 개인 endpoint 원문은 기록하지 않는다. + +## 현재 환경 + +- `dev`: 원격 Mac runner를 사용하는 기본 테스트 환경 +- `local`: 현재 host의 빠른 source/build 검증 환경 + +## 포트 선택 기준 + +- workspace root의 포트 원장 `.workspace-ops/docs/ports.md`에서 project-owned + 슬롯과 shared IOP field 포트를 먼저 확인한다. +- RARA `dev`는 2026-07-18 충돌 점검 당시 미배정이던 `70` 슬롯을 전용으로 + 배정해 사용한다. +- 실행 직전에는 원격 runner의 실제 listen 상태를 다시 확인한다. 문서에 기록된 + 점검 결과는 영구적인 port lock으로 간주하지 않는다. diff --git a/agent-test/dev/control-plane-smoke.md b/agent-test/dev/control-plane-smoke.md new file mode 100644 index 0000000..ddd07cd --- /dev/null +++ b/agent-test/dev/control-plane-smoke.md @@ -0,0 +1,92 @@ +--- +test_env: dev +test_profile: control-plane-smoke +domain: control-plane +verification_type: smoke +last_rule_updated_at: 2026-07-18 +--- + +# control-plane-smoke dev 테스트 + +## 읽기 조건 + +- control-plane 코드, 제어 상태 스키마·쿼리, 실행 진입점을 원격 환경에서 검증할 때 + +## 적용 범위 + +- `apps/control-plane/`, `packages/go/controlplane/`, `db/migrations/`, `db/queries/` + +## 분류 + +- domain: control-plane +- verification_type: smoke +- scope: 원격 runner의 수명주기 API, 제어 상태, PostgreSQL readiness 검증 + +## 환경 + +- host: `ssh toki@toki-labs.com` +- repo root: `/Users/toki/agent-work/rara-dev` +- port: Control Plane `127.0.0.1:18070`, PostgreSQL host publish 후보 `127.0.0.1:15470` +- runtime: Go 1.26 +- package manager: Go modules +- docker: login shell의 Docker Desktop/Engine 27.4.0, 실행 전 daemon 재확인 +- external service: readiness와 상태 API 검증에는 PostgreSQL 필요 +- model endpoint: 해당 없음 +- credential: database credential 원문은 문서와 출력에 남기지 않는다. + +## 명령 + +- setup: `make setup` +- lint: 변경한 Go 파일의 `gofmt` 상태와 diff 확인 +- unit: `go test ./packages/go/controlplane/... ./packages/go/database/...` +- smoke: `go build -o /tmp/rara-control-plane ./apps/control-plane/cmd/control-plane` +- service: PostgreSQL 준비 후 `RARA_LISTEN=127.0.0.1:18070`과 주입된 + `RARA_DATABASE_URL`로 binary를 실행하고 `/healthz`, `/readyz`, `/v1/status` 확인 +- e2e: 현재 baseline 없음 +- model: 해당 없음 +- full-cycle: `make test && make build` + +## 필수 검증 + +- 원격 checkout의 HEAD가 검증 대상 source와 일치한다. +- control-plane과 database package 테스트가 통과한다. +- control-plane binary가 원격 runner에서 빌드된다. +- DB 원본 변경 시 `make sqlc` 후 생성물 diff와 CI의 sqlc diff 기준을 확인한다. +- PostgreSQL이 준비된 경우 `18070`에서 health, readiness, status 응답을 확인한다. + +## 보조 검증 + +- `lsof -nP -iTCP:18070 -sTCP:LISTEN`으로 시작 전 충돌과 종료 후 반환을 확인한다. +- PostgreSQL host publish가 필요하면 `15470` 점유 여부를 별도로 확인한다. + +## 판정 기준 + +- source identity가 일치하고 테스트·빌드가 exit code 0으로 종료한다. +- service smoke를 수행한 경우 health와 readiness가 성공하고 `/v1/status`가 응답한다. +- PostgreSQL 미준비 시 source test/build 통과와 service smoke 차단을 구분해 보고한다. + +## 기준 출력 예시 + +```text +ok git.toki-labs.com/toki/rara/packages/go/... +``` + +## 차단 기준 + +- 원격 checkout 부재·source 불일치, Go 1.26 부재, `18070` 점유 +- service smoke에 필요한 PostgreSQL 또는 안전한 database credential 주입 부재 + +## 보고 항목 + +- 원격 branch/HEAD: +- 실행한 명령: +- 성공한 검증: +- 실패/차단된 검증: +- 생략 사유: +- 남은 위험: + +## 금지 사항 + +- local test 결과를 원격 service evidence로 보고하지 않는다. +- 운영 secret이나 개인 database URL을 문서와 로그에 남기지 않는다. +- 생성된 sqlc 파일을 직접 고쳐 테스트를 통과시키지 않는다. diff --git a/agent-test/dev/inventory.yaml b/agent-test/dev/inventory.yaml new file mode 100644 index 0000000..61a4202 --- /dev/null +++ b/agent-test/dev/inventory.yaml @@ -0,0 +1,87 @@ +test_env: dev +profile: remote-mac-runner +last_updated_at: "2026-07-18" + +source: + remote_runner: + ssh: toki@toki-labs.com + os: macOS + arch: arm64 + repo_root: /Users/toki/agent-work/rara-dev + checkout_status: provisioning_required + observed_at: "2026-07-18" + sync: + target_ref: exact_commit_under_test + remote_dirty_policy: discard_after_identity_review + require_local_remote_identity_match: true + +runtime: + go_required: "1.26" + go_observed_login_shell: "1.26.3" + python_required: "3.12" + python_observed_command: python3.12 + python_observed_version: "3.12.9" + default_python3_observed_version: "3.14.6" + login_shell_required_for_tool_path: true + docker_cli_observation: available_in_login_shell + docker_client_version: "27.4.0" + docker_engine_version: "27.4.0" + postgres_status: not_verified + model_endpoint: not_configured + +ports: + allocation_basis: workspace_70_slot_assigned_to_rara_after_collision_check_2026_07_18 + recheck_before_use: true + control_plane_http: + host: 127.0.0.1 + port: 18070 + rag_api_http: + host: 127.0.0.1 + port: 18071 + go_worker_http: + host: 127.0.0.1 + port: 18072 + python_executor_grpc: + host: 127.0.0.1 + port: 19070 + postgres_host_publish: + host: 127.0.0.1 + port: 15470 + container_port: 5432 + publish_only_when_required: true + reserved: + frontend: 13070 + cache: 16370 + metrics_diagnostics: + - 19170 + - 19171 + - 19172 + +compose_candidate: + status: not_implemented + project_name: rara-dev-agent + network: rara-dev-agent-net + subnet_candidate: 10.89.7.0/24 + subnet_collision_observed: false + subnet_observed_at: "2026-07-18" + subnet_recheck_before_create: true + +services: + control_plane: + config: configs/control-plane.yaml + listen_override: 127.0.0.1:18070 + health_url: http://127.0.0.1:18070/healthz + readiness_url: http://127.0.0.1:18070/readyz + rag_api: + config: configs/rag-api.yaml + listen_override: 127.0.0.1:18071 + health_url: http://127.0.0.1:18071/healthz + readiness_url: http://127.0.0.1:18071/readyz + go_worker: + config: configs/worker.yaml + listen_override: 127.0.0.1:18072 + health_url: http://127.0.0.1:18072/healthz + readiness_url: http://127.0.0.1:18072/readyz + python_executor: + listen_host: 127.0.0.1 + listen_port: 19070 diff --git a/agent-test/dev/platform-common-smoke.md b/agent-test/dev/platform-common-smoke.md new file mode 100644 index 0000000..c9c09e9 --- /dev/null +++ b/agent-test/dev/platform-common-smoke.md @@ -0,0 +1,98 @@ +--- +test_env: dev +test_profile: platform-common-smoke +domain: platform-common +verification_type: smoke +last_rule_updated_at: 2026-07-18 +--- + +# platform-common-smoke dev 테스트 + +## 읽기 조건 + +- 설정, database, HTTP lifecycle, observability, artifact store, integration port 또는 + 배포 구성을 원격 환경에서 검증할 때 + +## 적용 범위 + +- `packages/go/artifact/`, `packages/go/config/`, `packages/go/database/`, + `packages/go/httpserver/`, `packages/go/integration/`, + `packages/go/observability/`, `configs/`, `deploy/` + +## 분류 + +- domain: platform-common +- verification_type: smoke +- scope: 원격 runner의 공통 adapter, 포트 override, 서비스 조립 검증 + +## 환경 + +- host: `ssh toki@toki-labs.com` +- repo root: `/Users/toki/agent-work/rara-dev` +- port: HTTP `18070-18072`, Python gRPC `19070`, PostgreSQL host publish 후보 `15470` +- runtime: macOS arm64, Go 1.26, Python 3.12 +- package manager: Go modules, Python venv/pip +- docker: login shell의 Docker Desktop/Engine 27.4.0, 일반 비대화형 PATH에는 없음 +- external service: service readiness와 database adapter 통합 검증에는 PostgreSQL 필요 +- model endpoint: 기본값 없음 +- credential: secret/token/API key 원문은 문서와 출력에 남기지 않는다. + +## 명령 + +- setup: `make setup` +- lint: 변경한 Go 파일의 `gofmt` 상태와 Python Ruff 검사 확인 +- unit: `go test ./packages/go/artifact/... ./packages/go/config/... ./packages/go/database/... ./packages/go/httpserver/... ./packages/go/integration/... ./packages/go/observability/...` +- smoke: `make build` +- e2e: PostgreSQL과 dev service override가 준비된 경우 세 Go service의 health/readiness 확인 +- model: integration provider가 명시적으로 준비된 경우에만 수행 +- full-cycle: `make test && make build` + +## 필수 검증 + +- 원격 checkout의 HEAD가 검증 대상 source와 일치한다. +- 변경된 공통 Go package 테스트가 통과하고 세 Go service가 모두 빌드된다. +- 원격 실행 시 local 기본 포트 대신 `18070-18072`, `19070`, 필요 시 `15470`을 사용한다. +- 설정·배포·로그·trace에 secret 원문이 포함되지 않았는지 확인한다. +- Docker/PostgreSQL 부재 시 integration 검증을 통과로 간주하지 않는다. + +## 보조 검증 + +- `lsof`로 `13070`, `18070-18072`, `15470`, `16370`, `19070`, + `19170-19172` 전체를 확인해 `70` 슬롯 부분 충돌을 탐지한다. +- container runtime이 준비되면 PostgreSQL은 host `15470`에서 container `5432`로 + publish하고 service readiness를 확인한다. +- artifact filesystem root가 runner의 허용된 작업 경로 밖으로 벗어나지 않는지 확인한다. + +## 판정 기준 + +- source identity가 일치하고 테스트와 전체 build가 exit code 0으로 종료한다. +- dev port override가 IOP shared `18080-18099`, `19080`, `19090`을 사용하지 않는다. +- 실행한 integration만 근거와 함께 통과로 보고하고 미준비 dependency는 차단으로 남긴다. + +## 기준 출력 예시 + +```text +ok git.toki-labs.com/toki/rara/packages/go/... +``` + +## 차단 기준 + +- 원격 checkout 부재·source 불일치, 필수 runtime 부재, dev port 점유 +- database 통합 검증에 필요한 PostgreSQL 부재 +- config override 없이 local 포트를 shared remote host에 publish하려는 경우 + +## 보고 항목 + +- 원격 branch/HEAD: +- 실행한 명령: +- 성공한 검증: +- 실패/차단된 검증: +- 생략 사유: +- 남은 위험: + +## 금지 사항 + +- local 기본 포트 `18080-18082`, `19090`, `5432`를 shared remote runner에 + 그대로 publish하지 않는다. +- 운영 secret이나 개인 endpoint를 config 또는 테스트 문서에 기록하지 않는다. +- 공통 adapter 테스트를 특정 plane의 정책 검증으로 대체하지 않는다. diff --git a/agent-test/dev/rag-data-plane-smoke.md b/agent-test/dev/rag-data-plane-smoke.md new file mode 100644 index 0000000..438aea4 --- /dev/null +++ b/agent-test/dev/rag-data-plane-smoke.md @@ -0,0 +1,92 @@ +--- +test_env: dev +test_profile: rag-data-plane-smoke +domain: rag-data-plane +verification_type: smoke +last_rule_updated_at: 2026-07-18 +--- + +# rag-data-plane-smoke dev 테스트 + +## 읽기 조건 + +- retrieve·answer handler, release resolver, engine port, OpenAPI 또는 rag-api를 + 원격 환경에서 검증할 때 + +## 적용 범위 + +- `apps/rag-api/`, `packages/go/rag/`, `api/openapi/` + +## 분류 + +- domain: rag-data-plane +- verification_type: smoke +- scope: 원격 runner의 retrieve·answer 계약과 rag-api readiness 검증 + +## 환경 + +- host: `ssh toki@toki-labs.com` +- repo root: `/Users/toki/agent-work/rara-dev` +- port: RAG API `127.0.0.1:18071`, PostgreSQL host publish 후보 `127.0.0.1:15470` +- runtime: Go 1.26 +- package manager: Go modules +- docker: login shell의 Docker Desktop/Engine 27.4.0, 실행 전 daemon 재확인 +- external service: readiness·실제 retrieve/answer에는 PostgreSQL과 승인된 integration 필요 +- model endpoint: 기본값 없음 +- credential: integration/database credential 원문은 문서와 출력에 남기지 않는다. + +## 명령 + +- setup: `make setup` +- lint: 변경한 Go 파일의 `gofmt` 상태와 diff 확인 +- unit: `go test ./packages/go/rag/...` +- smoke: `go build -o /tmp/rara-rag-api ./apps/rag-api/cmd/rag-api` +- service: PostgreSQL 준비 후 `RARA_LISTEN=127.0.0.1:18071`과 주입된 + `RARA_DATABASE_URL`로 binary를 실행하고 `/healthz`, `/readyz` 확인 +- e2e: integration이 명시적으로 준비된 경우에만 `/v1/retrieve`, `/v1/answer` + JSON·SSE 계약 확인 +- model: 승인된 generation provider가 있을 때만 수행 +- full-cycle: `make test && make build` + +## 필수 검증 + +- 원격 checkout의 HEAD가 검증 대상 source와 일치한다. +- RAG handler와 resolver 테스트가 통과하고 rag-api binary가 빌드된다. +- 공개 요청·응답 변경 시 OpenAPI와 JSON/SSE 오류 의미가 일치한다. +- PostgreSQL이 준비된 경우 `18071`에서 health와 readiness를 확인한다. + +## 보조 검증 + +- `lsof -nP -iTCP:18071 -sTCP:LISTEN`으로 시작 전 충돌과 종료 후 반환을 확인한다. +- 준비된 non-production integration이 있을 때 retrieve와 answer 실제 응답을 확인한다. + +## 판정 기준 + +- source identity가 일치하고 테스트·빌드가 exit code 0으로 종료한다. +- service smoke를 수행한 경우 health와 readiness가 성공한다. +- 실제 integration이 없으면 handler 단위 테스트와 unavailable 동작까지만 통과로 보고한다. + +## 기준 출력 예시 + +```text +ok git.toki-labs.com/toki/rara/packages/go/rag +``` + +## 차단 기준 + +- 원격 checkout 부재·source 불일치, Go 1.26 부재, `18071` 점유 +- readiness에 필요한 PostgreSQL 또는 실제 통합 smoke에 필요한 integration 부재 + +## 보고 항목 + +- 원격 branch/HEAD: +- 실행한 명령: +- 성공한 검증: +- 실패/차단된 검증: +- 생략 사유: +- 남은 위험: + +## 금지 사항 + +- local test 결과나 unavailable engine을 실제 원격 retrieve·answer 성공으로 보고하지 않는다. +- secret, token, 개인 endpoint 원문을 기록하지 않는다. diff --git a/agent-test/dev/rules.md b/agent-test/dev/rules.md new file mode 100644 index 0000000..884cbc7 --- /dev/null +++ b/agent-test/dev/rules.md @@ -0,0 +1,127 @@ +--- +test_env: dev +last_rule_updated_at: 2026-07-18 +--- + +# dev 테스트 규칙 + +**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.** +**dev는 RARA의 기본 테스트 환경이며 local host가 아니라 원격 Mac runner를 기준으로 한다.** + +## 공통 규칙 + +- 사용자가 테스트 환경을 별도로 지정하지 않으면 이 `dev` 환경을 기본 기준으로 삼는다. +- local 검증은 원격 프리플라이트와 source 동기화를 대신하지 않는다. +- 작업 완료 검증은 변경 범위에 맞는 도메인 profile을 선택한다. +- 필수 검증을 실행하지 못하면 차단 사유로 보고한다. +- 최종 보고에는 원격 source identity, 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다. +- secret, token, password, private key, 개인 endpoint 원문은 tracked 파일이나 + shell 출력에 남기지 않는다. +- 원격 서비스는 기본적으로 runner loopback에 bind한다. 외부 공개 검증이 명시된 + 경우에만 별도 접근 경계와 방화벽 상태를 확인한다. + +## 기본 환경 + +- host: `ssh toki@toki-labs.com` 표준 원격 Mac runner +- repo root: 목표 checkout `/Users/toki/agent-work/rara-dev` +- checkout 상태: 2026-07-18 점검 시 아직 없음. 최초 원격 검증 전 생성이 필요하다. +- sync 기준: 검증할 exact source commit을 origin에서 fetch한 뒤 clean checkout하고, + local 변경과 원격 HEAD가 동일한지 확인한다. +- runtime: macOS arm64. 2026-07-18 login shell에서 Go 1.26.3과 + Python 3.12.9(`python3.12`)를 확인했다. +- package manager: Go modules, Python venv/pip +- docker: login shell의 Docker Desktop/Engine 27.4.0을 사용한다. 일반 비대화형 + SSH PATH에는 Go와 Docker가 없으므로 원격 명령은 login shell 또는 검증된 explicit + PATH로 실행한다. +- external service: readiness·통합 smoke에는 PostgreSQL이 필요하며, 준비되지 않으면 + source test/build까지만 수행하고 통합 검증은 차단으로 보고한다. +- model endpoint: 기본값 없음. adaptation/model 통합 검증 시 별도 승인된 endpoint가 필요하다. +- credential: secret/token/API key 원문은 문서에 기록하지 않는다. + +## 포트 매핑 + +2026-07-18 기준 workspace 원장에 기존 `70` 슬롯 배정이 없고, 원격 runner의 아래 +후보 포트가 listen 중이 아님을 확인한 뒤 RARA `dev` 전용으로 배정했다. 실행 직전 +동일 검사를 반복한다. + +| 용도 | local 호환값 | dev 원격값 | bind 기준 | +|---|---:|---:|---| +| Control Plane HTTP | `18080` | `18070` | `127.0.0.1:18070` | +| RAG API HTTP | `18081` | `18071` | `127.0.0.1:18071` | +| Go Worker HTTP | `18082` | `18072` | `127.0.0.1:18072` | +| Python Executor gRPC | `19090` | `19070` | `127.0.0.1:19070` | +| PostgreSQL host publish | `5432` | `15470` | `127.0.0.1:15470 -> 5432` | +| Frontend reserve | 해당 없음 | `13070` reserved | 현재 RARA runtime에 없음 | +| Cache reserve | 해당 없음 | `16370` reserved | 현재 RARA runtime에 없음 | +| Metrics / diagnostics reserve | 해당 없음 | `19170-19172` reserved | 현재 RARA runtime에 없음 | + +- `18080-18099`와 `19080/19090`은 IOP shared field/runtime baseline이므로 RARA + 원격 dev 서비스에 재사용하지 않는다. +- repo의 `configs/*.yaml` 기본 listen 값은 local 호환값이다. 원격 dev에서는 + `RARA_LISTEN`과 `RARA_PYTHON_LISTEN_PORT`로 위 dev 값을 명시한다. +- PostgreSQL host publish가 필요하지 않으면 `15470`을 열지 않고 service와 DB를 + 전용 network 또는 loopback으로만 연결한다. + +## 런타임 프로필 + +- source validation: 원격 checkout에서 `make test && make build`를 기본 완료 검증으로 사용한다. +- service smoke: PostgreSQL이 준비된 경우 Control Plane `18070`, RAG API `18071`, + Go Worker `18072`를 각각 dev override로 실행하고 health/readiness를 확인한다. +- Python executor smoke: `RARA_PYTHON_LISTEN_HOST=127.0.0.1`과 + `RARA_PYTHON_LISTEN_PORT=19070`을 사용한다. +- compose candidate: 향후 remote compose를 추가할 경우 + `COMPOSE_PROJECT_NAME=rara-dev-agent`, network `rara-dev-agent-net`, + subnet `10.89.7.0/24`, PostgreSQL host publish `15470`을 기준으로 한다. + 2026-07-18 기존 remote Docker network와 subnet이 겹치지 않음을 확인했지만, + 현재 compose에는 dev override와 network 정의가 없으므로 실제 구성으로 간주하지 않는다. +- artifact: runner-local filesystem artifact root를 사용하며 공개 artifact HTTP 포트는 없다. + +## 프리플라이트 + +- 원격 검증 전 runner 접속, `/Users/toki/agent-work/rara-dev` 존재 여부, branch, + HEAD, dirty 상태, local 변경과 source 동기화 여부를 확인한다. +- login shell에서 `go version`, `python3.12 --version`, `docker version`, 필요한 + tool/version, `.venv`의 Python identity를 확인한다. 기본 `python3`은 2026-07-18 + 기준 3.14.6이므로 Python 3.12 venv라고 추정하지 않는다. +- `13070`, `18070-18072`, `15470`, `16370`, `19070`, `19170-19172`가 다른 + process에 점유되지 않았는지 확인한다. 미사용 후보까지 함께 확인해 `70` 슬롯의 + 부분 재사용을 방지한다. +- service smoke 전 config path, `RARA_LISTEN`, `RARA_DATABASE_URL`, + artifact root, process identity를 확인한다. +- Docker daemon과 PostgreSQL container가 실제로 준비되지 않았으면 설치 상태만으로 + 통합 검증 가능하다고 추정하지 않고 integration blocker로 보고한다. +- checkout 부재, source 불일치, stale binary, port 점유, runtime version 불일치는 + setup/sync/rebuild 후 해소하거나 차단 사유로 보고한다. + +## 노드/서비스 인벤토리 위치 + +- machine-readable runner·port 기준: `agent-test/dev/inventory.yaml` +- Control Plane 기준: `agent-test/dev/control-plane-smoke.md` +- RAG API 기준: `agent-test/dev/rag-data-plane-smoke.md` +- Go/Python worker 기준: `agent-test/dev/workflow-execution-smoke.md` +- 공통 config·database·artifact·배포 기준: `agent-test/dev/platform-common-smoke.md` + +## 반복 테스트 기준 + +- 원격 evidence는 current source와 동일한 remote checkout에서만 수집한다. +- source test/build와 PostgreSQL 의존 service smoke를 구분해 보고한다. +- 여러 RARA 서비스를 동시에 실행할 때 각 프로세스에 다른 `RARA_LISTEN`을 명시한다. +- test 종료 후 장기 runtime으로 승인되지 않은 프로세스는 정리하고, 포트가 반환됐는지 확인한다. +- secret이 포함될 수 있는 database URL과 외부 endpoint는 값 대신 주입 여부만 보고한다. + +## 라우팅 + +- control-plane / smoke / 수명주기 API와 제어 상태 원격 검증: + `agent-test/dev/control-plane-smoke.md` +- rag-data-plane / smoke / retrieve·answer 계약 원격 검증: + `agent-test/dev/rag-data-plane-smoke.md` +- workflow-execution / smoke / Go worker와 Python executor 원격 검증: + `agent-test/dev/workflow-execution-smoke.md` +- platform-common / smoke / config·database·artifact·배포 원격 검증: + `agent-test/dev/platform-common-smoke.md` + +## 라우팅 규칙 + +- 여러 항목이 맞으면 모두 읽는다. +- 도메인 매핑이나 domain rule이 있으면 각 도메인의 `-smoke`를 baseline으로 둔다. +- 도메인/검증 시나리오별 문서는 다른 테스트 문서로 라우팅하지 않는다. diff --git a/agent-test/dev/workflow-execution-smoke.md b/agent-test/dev/workflow-execution-smoke.md new file mode 100644 index 0000000..46c8f74 --- /dev/null +++ b/agent-test/dev/workflow-execution-smoke.md @@ -0,0 +1,99 @@ +--- +test_env: dev +test_profile: workflow-execution-smoke +domain: workflow-execution +verification_type: smoke +last_rule_updated_at: 2026-07-18 +--- + +# workflow-execution-smoke dev 테스트 + +## 읽기 조건 + +- Go worker, executor registry, Python executor 또는 Protobuf 실행 계약을 원격 + 환경에서 검증할 때 + +## 적용 범위 + +- `apps/worker/`, `packages/go/workflow/`, `packages/python/`, `api/proto/`, + `gen/go/rara/v1/` + +## 분류 + +- domain: workflow-execution +- verification_type: smoke +- scope: 원격 runner의 Go worker와 Python gRPC executor 검증 + +## 환경 + +- host: `ssh toki@toki-labs.com` +- repo root: `/Users/toki/agent-work/rara-dev` +- port: Go Worker `127.0.0.1:18072`, Python Executor gRPC `127.0.0.1:19070` +- runtime: Go 1.26, Python 3.12 +- package manager: Go modules, Python venv/pip +- docker: login shell의 Docker Desktop/Engine 27.4.0, PostgreSQL 통합 검증 전 daemon 재확인 +- external service: Go worker 상태 전이 검증에는 PostgreSQL 필요 +- model endpoint: 기본값 없음. adaptation 모델 검증은 별도 승인된 endpoint 필요 +- credential: database/model credential 원문은 문서와 출력에 남기지 않는다. + +## 명령 + +- setup: `make setup` +- lint: `.venv/bin/ruff format --check packages/python/src packages/python/tests && .venv/bin/ruff check packages/python/src packages/python/tests` +- unit: `go test ./packages/go/workflow/... && PYTHONPATH=packages/python/src .venv/bin/python -m pytest packages/python/tests` +- smoke: `go build -o /tmp/rara-worker ./apps/worker/cmd/worker` +- service: PostgreSQL 준비 후 Go worker는 `RARA_LISTEN=127.0.0.1:18072`, + Python executor는 `RARA_PYTHON_LISTEN_HOST=127.0.0.1` + `RARA_PYTHON_LISTEN_PORT=19070`으로 실행 +- e2e: PostgreSQL과 executor가 준비된 경우 ping step의 lease와 terminal 상태 확인 +- model: ML dependency와 승인된 endpoint가 준비된 경우에만 수행 +- full-cycle: `make test && make build` + +## 필수 검증 + +- 원격 checkout의 HEAD가 검증 대상 source와 일치한다. +- Go workflow와 Python executor 테스트, Ruff 검사가 통과한다. +- Go worker binary가 빌드된다. +- Protobuf 변경 시 `make proto` 후 Go/Python 생성물과 호환성 영향을 확인한다. +- service smoke 시 `18072`와 `19070`이 각각 의도한 프로세스에만 점유된다. + +## 보조 검증 + +- `lsof -nP -iTCP:18072 -sTCP:LISTEN`과 + `lsof -nP -iTCP:19070 -sTCP:LISTEN`으로 충돌과 종료 후 반환을 확인한다. +- PostgreSQL을 준비한 경우 step lease·성공·실패·재시도 상태 전이를 확인한다. + +## 판정 기준 + +- source identity가 일치하고 Go/Python 테스트, Ruff, worker 빌드가 exit code 0으로 종료한다. +- service smoke를 수행한 경우 Go worker health/readiness와 Python gRPC capability + 응답을 확인한다. +- PostgreSQL·ML dependency가 없으면 source 검증과 통합 차단을 구분해 보고한다. + +## 기준 출력 예시 + +```text +ok git.toki-labs.com/toki/rara/packages/go/workflow +``` + +## 차단 기준 + +- 원격 checkout 부재·source 불일치, Go 1.26/Python 3.12/`.venv` 부재 +- `18072` 또는 `19070` 점유 +- 상태 전이 검증에 필요한 PostgreSQL 또는 모델 검증에 필요한 ML dependency 부재 + +## 보고 항목 + +- 원격 branch/HEAD: +- 실행한 명령: +- 성공한 검증: +- 실패/차단된 검증: +- 생략 사유: +- 남은 위험: + +## 금지 사항 + +- local test 결과를 원격 worker/executor evidence로 보고하지 않는다. +- 생성된 Protobuf 파일을 직접 수정하지 않는다. +- ML dependency가 없는 환경에서 adaptation 모델 실행이 검증됐다고 보고하지 않는다. +- secret, token, 개인 endpoint 원문을 기록하지 않는다.