rara/agent-roadmap/sdd/platform-foundation/control-plane-resource-api/SDD.md

SDD: Control Plane Resource API

위치

• Milestone: Milestone 문서
• Phase: PHASE.md

상태

[승인됨]

SDD 잠금

• 상태: 해제
• 사용자 리뷰: 없음
• 잠금 항목:
  • 없음

문제 / 비목표

• 문제: domain schema와 service scaffold는 있으나 운영 UI·CLI·worker가 공유할 project-scoped resource lifecycle, 오류, 페이지네이션과 동시성 계약이 없다.
• 비목표:
  • 외부 identity provider 연동과 세분화된 RBAC
  • online retrieve·answer data plane
  • UI 구현

Source of Truth

영역	기준	메모
Roadmap	Milestone 문서	관리 resource 범위와 project boundary
Code	Control Plane 앱	HTTP 진입점과 composition root
Schema	초기 제어 상태 스키마	project와 초기 resource identity
User Decision	없음	project-scoped 관리 경계를 초기 표준선으로 사용한다

State Machine

상태	진입 조건	다음 상태	근거
active	비활성화 가능한 구성 resource 생성과 validation이 성공함	disabled	resource revision
disabled	명시적 비활성화가 revision 조건과 함께 성공함	active	mutation audit

이 공통 상태는 source·knowledge base 같은 구성 resource에만 적용한다. dataset·workflow·evaluation·release의 세부 상태는 각 수명주기 SDD가 소유하며 공통 API가 임의로 합치지 않는다.

Interface Contract

• 계약 원문: api/openapi/에 versioned management API를 게시하고 구현 시 source of truth로 사용한다.
• 입력:
  • project_id: 모든 project-owned resource route와 query의 필수 scope. project 자체는 격리 root identity로 다룬다.
  • Idempotency-Key: 생성과 명령형 mutation의 replay identity
  • If-Match 또는 동등한 revision: optimistic concurrency 조건
  • cursor, filter와 bounded page size
• 출력:
  • stable resource identity, revision과 lifecycle state
  • opaque next cursor
  • stable error code, message, correlation identity와 retryability
• 금지:
  • project-owned resource에 project scope 없는 목록·변경 요청을 허용하지 않는다.
  • offset pagination을 공개 안정 계약으로 사용하지 않는다.
  • stale revision을 last-write-wins로 덮어쓰지 않는다.
  • 같은 idempotency key의 다른 payload를 성공 replay로 처리하지 않는다.

Acceptance Scenarios

ID	Milestone Task	Given	When	Then
S01	project-boundary	서로 다른 두 project와 resource	교차 project read·write	존재 여부를 누출하지 않고 거부한다
S02	resource-lifecycle	지원 resource 종류	create·get·list·update·disable	공통 identity·revision 의미로 동작한다
S03	api-consistency	여러 page와 stale revision	list·update	cursor는 안정적으로 이어지고 stale write는 conflict가 된다
S04	mutation-idempotency	동일 key의 동일·상이 payload	mutation replay	동일 payload는 같은 결과, 상이 payload는 conflict가 된다
S05	management-contract	관리 API schema	계약 게시	소비자가 versioned OpenAPI로 요청·오류를 생성·검증한다
S06	lifecycle-tests	resource와 project matrix	contract suite 실행	상태 전이와 cross-project negative case가 통과한다

Evidence Map

Scenario	Required Evidence	agent-task 연결	완료 Evidence 기대
S01	cross-project negative integration test	agent-task/m-control-plane-resource-api/...	project-boundary deny evidence
S02	resource lifecycle contract matrix	agent-task/m-control-plane-resource-api/...	resource-lifecycle API evidence
S03	cursor·stale revision test	agent-task/m-control-plane-resource-api/...	api-consistency pagination·conflict evidence
S04	idempotency replay·mismatch test	agent-task/m-control-plane-resource-api/...	mutation-idempotency replay evidence
S05	OpenAPI validation·compatibility check	agent-task/m-control-plane-resource-api/...	management-contract artifact
S06	lifecycle and isolation suite	agent-task/m-control-plane-resource-api/...	lifecycle-tests PASS evidence

Cross-repo Dependencies

• 없음

Drift Check

• Milestone 기능 Task와 Acceptance Scenario가 일치한다.
• Evidence Map이 code-review/complete.log에서 검증 가능하다.
• project boundary와 도메인별 lifecycle 책임을 분리했다.
• 사용자 리뷰가 필요한 항목이 없다.

사용자 리뷰 이력

• 없음

작업 컨텍스트

• 표준선: project-scoped identity, cursor pagination, optimistic concurrency, stable error, idempotent mutation
• 후속 SDD: 내구성 있는 Workflow Runtime, 수집과 Dataset 수명주기