Reference Necessity Design

1. 결론

지금 문제는 "엔티티를 많이 뽑는다" 자체가 아니다. 연속 에피소드에서는 다음 회차에 중요해질 수 있으므로, 엔티티 catalog는 넓게 보존해야 한다. 실제 결함은 catalog 보존, episode별 사용량 판단, 참조 이미지 생성, scene T2I attach가 한 흐름 안에서 섞여 있다는 점이다.

2. 현재 구조

2.1 순서 문제

현재 entity_all_character, entity_all_prop, entity_filter, entity_detail, entity_t2i는 shot_selection보다 앞에 있다. 따라서 최종 이미지화할 shot을 모르는 상태에서 엔티티 count와 필터가 결정된다.

entity_all_*        order 8-13
entity_merge        order 13.5
entity_relation     order 13.6
entity_filter       order 13.7
entity_detail       order 14
entity_t2i          order 15
shot_selection      order 15.5
scene_detail        order 21.70
shot_dependency_t2i order 21.71

2.2 참조 이미지 결정이 섞인 위치

2.3 현재 attach 규칙

• 캐릭터 composite: T2I prompt의 C01O02 패턴이 있으면 composite reference attach.
• base character: required_refs(kind="character")가 있으면 bare C## reference attach.
• prop: 텍스트에 P##가 있다는 이유만으로 attach하지 않는다. required_refs(kind="prop")가 단일 SOT다.
• background: 별도의 background/floor-plan/chain-bg 경로가 있고 이 문서의 1차 범위는 아니다.

3. 최신 E2E 데이터에서 확인된 증거

대상 프로젝트 76212b49-bf96-45fb-8c56-cd8d8ae02dda, 에피소드 f44339e6-1bd1-4d10-8a8f-2e30e5a1d36d의 checkpoint/DB를 읽어 확인한 결과다.

4. 목표 구조

4.1 세 개의 개념을 분리

4.2 상태 모델

catalog_only
  프로젝트 사전에만 존재. 이번 에피소드 이미지 참조 없음.

text_only
  이번 에피소드 selected shot에 등장하지만 자연어 묘사로 충분.

reference_required
  selected-shot policy와 scene_detail/card가 ID/ref 사용을 요구.
  characters/nonhuman subjects: visible_shot_count >= 2 또는 required_ref_count >= 1.
  props: final gate는 required_ref_count >= 1.

reference_generated
  실제 ImageAsset reference가 생성되어 scene image stage에서 attach 가능.

human_deferred_note (optional)
  다음 에피소드 중요도 가능성 같은 미래 판단. deterministic 계산 결과가 아니라
  운영자/LLM 보조 메모이며 reference 생성 게이트로 직접 쓰지 않는다.

4.2.1 Catalog noise와 recurring 후보 구분

4.3 다음 에피소드 대비

다음 에피소드에서 어떤 인물의 출현수가 늘어나면 catalog에 이미 존재하므로 새로 발견할 필요가 없다. 단지 그 에피소드의 usage 집계가 올라가고, policy가 text_only에서 reference_required로 승격된다. 이때 처음으로 참조 이미지를 생성한다.

5. 이미지 참조 vs 텍스트 설명 결정 시점

한 번에 결정하면 안 된다. 두 단계가 필요하다.

5.1 결정 규칙 초안

6. 건드려야 할 코드와 프롬프트

6.1 코드

6.2 프롬프트

7. 단계별 구현 계획

Phase 0 - 관찰 및 안전망 차집합 감사

동작 변경 없이 현재 프로젝트/에피소드에 대해 usage matrix를 산출한다. 목적은 threshold와 예외를 실제 데이터로 정하고, broad union 안전망을 걷어도 되는지 검증하는 것이다.

입력:
- entity_all shot_count
- entity_filter kept/removed
- scene_detail.visible_entities
- render_prompt_card.required_refs
- t2i_prompt ID occurrence
- ImageAsset reference rows
- EntityEpisodeLink.t2i_appearance_count

출력:
- entity_reference_usage_report.json
- table: catalog_hint_count vs selected_shot_count vs visible_shot_count
         vs prompt_id_count vs required_ref_count vs generated_refs
- safety_diff:
    broad_required_union =
      scene_director.present
      ∪ shot_validator.character_ids
      ∪ shot_director.visible_entity_ids
      ∪ scene_detail.visible_entities
      ∪ scene_detail.required_refs
    required_refs_only = scene_detail.required_refs
    audit_set = broad_required_union - required_refs_only

안전 게이트:
- audit_set의 각 character/prop이 실제 selected-shot T2I 미사용인지 확인한다.
- audit_set 안에 실제 prompt ID 사용 또는 attached ref 필요성이 있으면 Phase 1/2 진입 금지.
- audit_set에서 실제 T2I 사용 엔티티가 발견되면 required_refs SOT gap 이다.
  fallback은 broad union 유지가 아니라 required_refs 보강이다.
- gap 집합이 크거나 root가 깊으면 bundle 진입을 중단하고 required_refs 정확성을 먼저 재점검한다.
- 이 게이트 통과 후에만 broad union 안전망을 reference generation에서 제거한다.

Phase 1 - ref_image_gen 과생성 차단

catalog는 그대로 두고, 참조 이미지 생성 보호 집합을 좁힌다. 단, 이 Phase는 Phase 2와 같은 branch에서 함께 검증한다.

• entity_protection._collect_required_entity_ids를 split한다.
• reference generation용 required set은 scene_detail.render_prompt_card.asset_requirements.required_refs만 사용한다.
• scene_director.present, shot_validator.character_ids, shot_director.visible_entity_ids, scene_detail.visible_entities는 reference generation 보호에서 제외한다.
• ref_low_freq_skip.json을 list가 아니라 reasoned object로 확장한다.

Phase 2 - scene_detail 전 policy overlay

"이미지를 넣을 것인지, 텍스트 설명만 넣을 것인지"를 scene_detail이 T2I prompt를 만들기 전에 결정한다.

episode_reference_policy:
  C08:
    mode: text_only
    reason: selected_shot_count=1, visible_shot_count=1, required_ref_count=0, no identity continuity dependency
  C01:
    mode: reference_required
    reason: protagonist, visible_shot_count high
  P10:
    mode: reference_required
    reason: prop required_refs count high, continuity-critical photo
  P11:
    mode: text_only
    reason: selected_shot_count=1, visible_shot_count=1, required_ref_count=0

• render_prompt_card는 이 overlay를 보고 text-only 대상의 required_refs를 만들지 않는다.
• scene_detail user prompt/card에는 text-only 대상이 ID가 아니라 일반 묘사로 들어가도록 한다.
• card hash/verify 경로는 overlay를 재계산하지 않고 동일 episode_reference_policy manifest를 읽어야 한다.
• prop은 two-timepoint 정책을 따른다. scene_detail 전에는 continuity-critical 휴리스틱으로 provisional 판정하고, scene_detail 이후 materialization 단계에서 required_ref_count로 최종 확정한다.

Phase 3 - DB/read model 및 UI 분리 (별도 branch)

Phase 0+1+2가 E2E에서 안정되면 UI와 DB projection에 명시적으로 노출한다. 이 단계는 read model/운영 표시 작업이므로 별도 branch로 분리한다.

• EntityCanon: 프로젝트 catalog 상태 표시.
• EntityEpisodeLink: episode usage, reference policy, generated status 표시.
• 요소 UI: "이번 에피소드 text-only", "reference required", "reference generated", "future note"를 구분.
• scene debug UI: lineage refs와 actual attached refs를 분리 표시.

8. 검증 계획

8.1 Unit / integration tests

8.2 E2E acceptance

• reference asset 수가 감소해야 한다. 특히 최종 selected-shot T2I 사용량 0인 character/prop의 reference는 생성되지 않아야 한다.
• scene_image_pipeline은 missing required ref 없이 완료되어야 한다.
• 한 컷 주변 인물은 ID 오염 없이 자연어 설명으로 렌더되어야 한다.
• 다음 에피소드에서 사용량이 증가한 기존 catalog entity는 새로 추출하지 않고 reference_required로 승격되어야 한다.

9. UI/운영 표시

사용자는 "요소가 존재한다"와 "참조 이미지가 쓰인다"를 구분해서 봐야 한다. 현재 UI가 대표 이미지 중심이면 저빈도 요소도 중요한 요소처럼 보이기 쉽다.

10. 확정된 결정

1. 캐릭터 recurring threshold: visible_shot_count >= 2 또는 required_ref_count >= 1이면 reference_required. 별도 주요 인물 하드코딩 보호는 두지 않는다. 주연은 count가 자연히 높아 threshold로 커버된다. 단 identity/transformation relation이 있고 그 변형이 selected shot에서 실제 쓰이면 기존 variant 보호를 유지한다.
2. 동물/비인간 subject: 캐릭터와 같은 규칙을 쓴다. entity_type만으로 prop처럼 취급하지 않는다. 동물은 정체성을 가진 depicted subject다. 예: 검은 맹견 2샷은 reference_required, 검은 고양이 1샷은 text_only.
3. prop: 최종 게이트는 required_ref_count >= 1이다. prop attach는 required_refs 단일 SOT이므로 visible이어도 required_ref가 없으면 reference 생성은 낭비다. 단 policy 결정은 scene_detail 이전이므로, prop은 사진/지도/표식류 + staging 2회 이상 같은 continuity-critical 휴리스틱으로 provisional 판정하고, materialization 단계에서 required_ref_count로 최종 확정한다.
4. Phase 0 audit 실패 fallback: broad_required_union - scene_detail.required_refs 차집합에서 실제 T2I 사용 엔티티가 발견되면 이는 required_refs SOT gap 이다. fallback은 required_refs 보강이며, broad union을 영구 crutch로 남기지 않는다. gap 집합이 크거나 root가 깊으면 bundle 진입을 중단하고 required_refs 정확성을 먼저 재점검한다.

11. Non-goals

• 이번 설계는 엔티티를 DB에서 삭제하는 작업이 아니다.
• 이번 설계는 background 일관성 전체를 해결하지 않는다. 배경은 별도 background catalog/usage 설계가 필요하다.
• 이번 설계는 image model 품질이나 포즈 문제를 직접 고치지 않는다.
• 이번 설계는 VLM 기반 판단을 요구하지 않는다.