shot_projection_card — production wiring brief

TheRoad Scene Lab · W21B-wave-4 · 2026-05-30 · Claude 초안 → Codex cross-review 합의 반영

DRAFT v0 DOC ONLY — 코드/DB/render 변경 0 design brief = why/schema SOT

1. Scope & non-goals

Scope: shot_projection_card를 production 파이프라인에 default-OFF로 끼워넣기 위한 step 등록 / config / manifest / contract delta / cache / acceptance matrix / rollout 순서.

• In: §2 변경 인벤토리, §3 step 등록 spec, §4 cache, §5 plan vNext delta, §6 background_prompt vNext, §7 scene_detail/I2I 소비, §8 edge, §9 acceptance matrix, §10 rollout.
• Non-goal: schema 재설계(design brief가 lock). 본 문서에서 schema 필드를 새로 만들지 않는다 — 기존 pack schema를 그대로 wiring한다.
• Non-goal: 좌표/grid 생성(사용자 핵심 제약, v8 Path-S 폐기). VLM은 서술/분류만.
• Non-goal: W21B-w3 reuse contract(render_action / reuse_target_bg_id / route_render_actions) 재정의.
• Non-goal: 시나리오-종속 lexicon / 글자·조사 패턴 매칭. leakage check는 self-defined internal token(정수 marker / 고정 enum literal / card_id)의 exact 누출 검사뿐(design brief §5.1).

2. Wiring anchor inventory (실측)

변경 대상 파일과 그 성격. order/flag는 backend/app/core/step_manifest.py·config.py grep 실측.

현 manifest 순서 (실측 order): floor_plan_prompt 19.61 → floor_plan_render 21.55 → overlay_payload 21.57 → base_location_dossier 21.58 → geometry_readback 21.59 → semantic_readback 21.591 default OFF → shot_projection_card 21.593 (신규) → shot_aware_bg_render_plan 21.595 → background_prompt 21.60 → background_render → scene_detail 21.70.

3. Step A 등록 spec — shot_projection_card

3.1 의존성 — hard dep vs optional gate (Codex 보강 #1)

3.2 fp-less BG (Codex 보강 #1)

3.3 버전 sync 의무

step의 SCHEMA_VERSION ↔ pack schema.json, PROMPT_VERSION ↔ pack dir(1.202605302212) 동기. semantic_readback_step이 manifest 주석에 명시한 sync 의무와 동일 패턴.

4. Cache / source_hash 구현

2-pass로 VLM 콜이 늘어나므로 cache가 필수다. active 21 전부가 아니라 변경된 FP/BG부터 재실행할 수 있어야 한다(design brief §6).

source_hashes = {
  fp_render_hash,            # detailed FP PNG
  substrate_hash,           # light_fp (or "not_available")
  overlay_hash,
  geometry_hash,
  semantic_hash,            # or "not_available"  (gate disabled 시)
  camera_rec_hash,
  shot_context_hash,        # ★ raw text 아님 = normalized (shot text/shot_guides/visible_entities)
  prompt_version, schema_version, model, provider
}
card_cache_key = hash(source_hashes + bg_id + shot_id)

5. Plan vNext (B) — contract delta · demote, NOT delete

shot_aware_bg_render_plan(21.595)는 카메라 결정에서 손 떼고 reference graph / reuse / render_action 전역 결정만 한다. 단 v0에서 기존 필드를 삭제하지 않는다.

5.1 추가 필드 (최소)

planner 주 역할 = reference graph / reuse / render_action + 어떤 card를 같은 plate로 묶을지 / anchor 선택. camera_decision은 demote된 audit/compat field.

6. background_prompt vNext (C) — consumer

7. scene_detail / I2I (D) — 같은 card 소비

BG와 최종 scene t2i가 같은 shot contract를 따르게 하는 정합 SOT 단계.

8. Edge cases

9. Fail-closed & acceptance matrix (path별, Codex 보강 #3)

10. Rollout sequence — commit boundary (Codex 보강 #4)

• land 순서: step+config OFF 먼저 → text-only dry(L05B09/L09B01, image 비용 0) → 소규모 E2E(2~4 BG cap, ≪$10) → multi-shot merge/anchor 검증.
• 각 commit은 default OFF라 production 동작 불변 — real VLM은 explicit force/cap에서만.
• untracked 보존: prior wave4 Phase A / semantic_readback / layout_plan 관련 modified·untracked는 이 wiring과 무관 → 건드리지 않음.

11. 시나리오 leakage 금지 증명

• 본 wiring은 특정 시나리오(옥탑방/마트/특정 prop·문구) 기반 rule 0 — config flag / manifest order / contract field만.
• leakage check는 self-defined internal token(정수 marker / 고정 enum literal / card_id)의 exact 누출 검사 — 한국어 자연어 의미를 substring/조사로 판단하지 않음(design brief §5.1, validator 5 fixture green 실증).
• L05/L09는 dry fixture일 뿐 rule의 일부가 아님.