# Execution Flow Audit

## 활성 파이프라인

현재 문제의 핵심 실행 경로는 legacy `background_chain_render`가 아니라 활성 `background_render`와 `scene_image_pipeline`이다.

```mermaid
flowchart LR
    A[world_guide] --> B[floor_plan_render]
    B --> C[background_render]
    C --> D[scene_detail]
    D --> E[shot_dependency_t2i]
    E --> F[t2i_review]
    F --> G[scene_image_pipeline]
    H[ref_image_gen] --> G
    C --> G
```

실제 scene generation에서 쓰이는 입력은 크게 세 종류다.

| 입력 | 생산자 | 소비자 | 주요 위험 |
| --- | --- | --- | --- |
| chain background | `background_render` | `scene_checkpoint_loaders`, `scene_generation_coordinator` | checkpoint raw path, 설정 토글 불일치 |
| entity reference | `ref_image_gen` | `scene_reference_service`, prompt builder | ID 계약 충돌, low-frequency skip |
| selected still/prompt | `scene_detail`, `shot_dependency_t2i` | `scene_image_pipeline` | prompt 내 reference id 누락, selected만 생성 |

## StepRunner Lifecycle

```mermaid
sequenceDiagram
    participant Caller as StepExecutionService
    participant Runner as StepRunner
    participant Step as PipelineStep
    participant DB as step_run/ImageAsset
    participant FS as Checkpoint/Files

    Caller->>Runner: run(step, mode)
    Runner->>FS: load checkpoint
    Runner->>Runner: resume/force/hash checks
    Runner->>Step: run()
    Step->>FS: write images/checkpoint
    Step->>DB: register ImageAsset / update step_run
    Runner->>Step: verify_completion only if final_status=completed
    Runner->>DB: save final status
```

중요한 점은 `verify_completion()`이 step별 override가 있을 때만 실질적인 검증을 한다는 점이다. `background_render`에는 현재 chain_bg 검증이 존재하지만, `scene_image_pipeline`에는 동일 수준의 exit verify override가 없다. 따라서 scene 이미지 primary 누락이 있어도 base verify는 통과 가능하다.

## scene_image_pipeline Force Failure Path

가장 위험한 재발 경로다.

```mermaid
sequenceDiagram
    participant User as Force 실행
    participant Step as SceneImagePipelineStep
    participant DB as ImageAsset(scene)
    participant Svc as SceneImageService
    participant Gen as Image Generation

    User->>Step: mode=force
    Step->>DB: selected still 기존 primary is_primary=false
    Step->>Step: scene checkpoint 삭제
    Step->>Svc: generate_images()
    Svc->>Gen: batch image generation
    Gen-->>Svc: 실패/None/empty result
    Svc-->>Step: 일부 또는 전체 미생성
    Step->>DB: selected primary count 조회
    Note over DB: 새 primary가 없으면 0개 상태 가능
    Step-->>User: 실패 또는 partial이어야 하나 검증 부재 시 상태 왜곡 가능
```

이 경로의 문제는 “삭제 후 생성” 순서다. 새 이미지가 성공적으로 저장되고 primary 등록이 완료된 뒤 기존 primary를 교체해야 원자성이 유지된다. 현재 구조는 force 초기에 기존 primary를 먼저 해제한다.

## Background Render Flow

```mermaid
flowchart TD
    Plan[background_master_plan] --> Prompt[background_prompt]
    Floor[floor_plan ImageAsset] --> Prompt
    Prompt --> Gen[image generation]
    Gen --> PNG[chain_bg PNG files]
    Gen --> Manifest[background_render manifest]
    PNG --> Register[_register_image_assets]
    Register --> DB[(ImageAsset chain_bg)]
    DB --> Verify[background_render.verify_completion]
    Manifest --> SceneLoad[load_background_chain_bg_map]
    SceneLoad --> ScenePrompt[scene prompt background refs]
```

현재 코드 기준으로 `background_render`는 DB sync 실패를 raise하고, `verify_completion()`에서 expected chain_bg와 DB row/file 존재를 확인한다. 과거 `variant_label` 길이와 silent catch 사고는 이 영역에서 발생했으나 현재 DB/코드 기준 직접 재현 조건은 줄었다.

단, scene prompt에 background가 들어가는 경로는 DB `ImageAsset(chain_bg)`만 보는 것이 아니다. `scene_checkpoint_loaders.py`가 background checkpoint/manifest를 읽어 map을 만들고, `scene_generation_coordinator.py`가 이 map을 prompt reference로 주입한다. 그래서 “chain_bg DB 등록 실패”와 “scene prompt에 background ref가 안 들어감”은 항상 같은 원인이 아니다.

## Deprecated / Orphan 경로 주의

| 경로 | 상태 | 분석 시 주의 |
| --- | --- | --- |
| `background_chain_render` | manifest disabled/deprecated | 예전 사고 패턴 참고용. 현재 기본 실행 원인으로 단정하면 안 됨 |
| Gemini/experiment scripts | 실험/비교군 | prompt/chain 설계 검토 대상일 수 있으나 main pipeline DB 사고와 직접 연결 아님 |
| old floor plan / set design scripts | 별도 pipeline | 파일명 유사성 때문에 원인 오인 가능 |

## 핵심 검증 공백

| 검증 대상 | 현재 상태 | 영향 |
| --- | --- | --- |
| `background_render` chain_bg DB/file | step override 있음 | 과거보다 안전 |
| `scene_image_pipeline` selected still primary/file | step override 없음 | scene primary 0개 사고 재발 가능 |
| checkpoint raw relative path | 일부 loader에서 직접 Path 처리 | cwd 변경 시 누락/empty map 가능 |
| prompt reference IDs | prompt 계약 충돌 존재 | entity reference 누락 가능 |