# SDD: LoRA와 QLoRA 실행

## 위치

- Milestone: [Milestone 문서](../../../phase/selective-adaptation/milestones/lora-qlora-execution.md)
- Phase: [PHASE.md](../../../phase/selective-adaptation/PHASE.md)

## 상태

[초안]

## SDD 잠금

- 상태: 잠금
- 사용자 리뷰: [요청됨](USER_REVIEW.md)
- 잠금 항목:
  - [D01] 첫 지원 base model family와 배포 대상 우선순위

## 문제 / 비목표

- 문제: 검증된 training dataset에서 선택적으로 LoRA·QLoRA를 실행하려면 compute·framework capability, checkpoint·cancel, artifact identity와 평가 후 승격 계약이 필요하다.
- 비목표:
  - base model full fine-tuning
  - 실시간 online learning
  - GPU scheduler·model registry 제품 자체 구현

## Source of Truth

| 영역 | 기준 | 메모 |
|------|------|------|
| Roadmap | [Milestone 문서](../../../phase/selective-adaptation/milestones/lora-qlora-execution.md) | adaptation 범위와 선택적 실행 원칙 |
| Dataset | [훈련 Dataset 정제 SDD](../training-dataset-curation/SDD.md) | 불변 training dataset release |
| Runtime | [내구성 있는 Workflow Runtime SDD](../../workflow-automation/durable-workflow-runtime/SDD.md) | lease, checkpoint, cancel과 artifact |
| User Decision | [USER_REVIEW.md](USER_REVIEW.md) | 첫 지원 model family와 배포 대상 |

## State Machine

| 상태 | 진입 조건 | 다음 상태 | 근거 |
|------|-----------|-----------|------|
| pending | dataset·recipe·capability preflight가 통과함 | running, rejected, cancelled | training job |
| running | executor가 lease와 compute를 확보함 | checkpointed, evaluating, failed, cancelled | progress event |
| checkpointed | 재개 가능한 checkpoint가 게시됨 | running, failed, cancelled | checkpoint manifest |
| evaluating | 최종 adapter artifact가 생성됨 | promotable, rejected, failed | evaluation result |
| promotable | required gate를 통과함 | promoted, expired | promotion decision |
| promoted | 명시적 adapter alias 전환이 성공함 | rolled_back | audit event |
| rolled_back | 이전 adapter가 다시 active가 됨 | 없음 | rollback event |

## Interface Contract

- 입력: base model identity, training dataset release, versioned recipe, seed, resource limit와 executor capability
- 출력: progress·usage, checkpoint, adapter manifest, evaluation evidence와 promotion decision
- 금지:
  - capability preflight 실패 job을 실행하지 않는다.
  - cancelled·failed job의 불완전 artifact를 promotable로 만들지 않는다.
  - evaluation 없이 adapter alias를 변경하지 않는다.

## Acceptance Scenarios

| ID | Milestone Task | Given | When | Then |
|----|----------------|-------|------|------|
| S01 | `preflight-capability` | model·precision·quantization·memory 요구 | job 수락 | 호환 executor만 수락하고 불일치는 거부한다 |
| S02 | `training-job` | dataset·recipe·seed | LoRA·QLoRA 실행 | progress·usage와 재현 identity가 남는다 |
| S03 | `checkpoint-cancel` | 실행 중 checkpoint·cancel·failure | 상태 전이 | 안전한 terminal state와 재개 가능한 artifact가 구분된다 |
| S04 | `adapter-manifest` | 학습 완료 adapter | manifest 생성 | base model·dataset·recipe·library·hash가 고정된다 |
| S05 | `adaptation-evaluation` | baseline과 candidate adapter | 동일 suite 실행 | 비교 metric과 required gate가 생성된다 |
| S06 | `adapter-promotion` | gate 통과·실패 adapter | promotion·rollback | 통과 후보만 명시적으로 승격하고 이전 버전으로 복구한다 |

## Evidence Map

| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
|----------|-------------------|------------------|---------------------------|
| S01 | executor capability matrix | `agent-task/m-lora-qlora-execution/...` | `preflight-capability` evidence |
| S02 | deterministic small training smoke | `agent-task/m-lora-qlora-execution/...` | `training-job` artifact·usage |
| S03 | checkpoint·cancel fault injection | `agent-task/m-lora-qlora-execution/...` | `checkpoint-cancel` transition evidence |
| S04 | manifest schema·hash test | `agent-task/m-lora-qlora-execution/...` | `adapter-manifest` evidence |
| S05 | baseline comparison run | `agent-task/m-lora-qlora-execution/...` | `adaptation-evaluation` metrics |
| S06 | promotion·rollback integration test | `agent-task/m-lora-qlora-execution/...` | `adapter-promotion` audit |

## Cross-repo Dependencies

- 없음

## Drift Check

- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
- [x] adaptation을 기본 RAG 경로와 분리했다.
- [ ] 사용자 결정 [D01]이 해결되었다.

## 사용자 리뷰 이력

- [USER_REVIEW.md](USER_REVIEW.md) 요청 중

## 작업 컨텍스트

- 표준선: optional adaptation, capability preflight, immutable manifest, evaluation-before-promotion
- Milestone은 `[스케치]`이며 [D01]과 승격 조건이 해소될 때까지 구현 잠금 상태를 유지한다.