Aji XUdZddlZddlZddlZddlmZddlmZddlm Z m Z m Z m Z m Z mZejeZeZeZeeeeefed<defdZe d Z d+d eded ed e efd Zeej9j:j:j:j:dz dz Zddlm Z e dd ededefdZ!d edededefdZ"dZ#dddZ$dddd ededed e ede ee ff dZ% d,d eded e edefdZ& d,d eded e ede ee ffd Z'd ede efd!Z(d edede efd"Z)de*fd#Z+d eded ed$eddf d%Z, d-d eded&edee ee ee effd'Z- d.d eded&ed e ede ef d(Z.d/d edede ee ffd)Z/d/d edede efd*Z0y)0u프롬프트 로더 — DB 우선, 파일 fallback. 1. DB에서 module+name+is_active=true 조회 2. 없으면 파일에서 최신 버전 로드 3. 새 프롬프트 저장 시 DB + 파일 동시 저장 ## Version pack semantics (problems.md #6) Module 디렉토리는 여러 version 디렉토리를 가질 수 있고 (예: ``shot_extract/ 9.x``, ``shot_extract/10.x``, ``shot_extract/11.x``), 각 version 안에 stem 파일이 들어 있다. 이 로더는 stem 별로 ``_version_sort_key`` 기준 가장 최신 version 디렉토리를 독립적으로 탐색하므로, **같은 module 안에서 stem 이 서로 다른 version 에서 로드될 수 있다** (e.g. ``system.md`` 는 v11, ``schema.json`` 은 v10 — 각자가 자기 stem 을 가진 가장 최신 version 우선). 이 동작은 backward-compat 으로 유지하되 다음 두 단계 가시화/강제 layer 를 제공한다. 1. **observability** (default): 같은 module 안에서 stem 들의 effective version 이 일치하지 않으면 ``logger.warning`` (process 당 1회) + ``get_effective _source`` response 의 ``module_pack.drift`` 에 stem→version 매핑 노출. 2. **opt-in strict** (``PROMPT_VERSION_PACK_STRICT=true``): module 의 가장 최신 version 디렉토리 안에 stem 이 없으면 ``RuntimeError`` 발생. 운영자가 prompt 정리 후 default 로 전환하기 위한 toggle. strict 모드 적용 boundary (review I3/I4): - **module 디렉토리 자체가 없으면** strict 가 raise 하지 않고 기존 ``FileNotFoundError`` 가 caller 에서 발생한다 (typo 등은 strict 와 별개 경로로 진단). 같은 module 의 stem-version 정렬에만 적용. - **db= 인자로 DB row 가 hit 되면** ``_load_from_file`` 자체를 호출하지 않으므로 strict 검증이 우회된다. 거의 모든 caller 가 file-only (db 미전달) 이지만 ``location_floor_plan_step`` 등 db-aware caller 는 stale DB row 가 stem 을 살리는 시나리오에서는 strict toggle 영향을 받지 않는다. N)Path)Lock)AnyDictListLiteralOptionalTuple _DRIFT_WARNEDnamec|jdd} t|dt|dkDr|dfSdfS#ttf$rd|fcYSwxYw)u버전 디렉토리 정렬 키 — '12.202603271830' → (12, '202603271830'). Primary segment 는 numeric, secondary 는 lexical 비교. 본 프로젝트 컨벤션 (`버전.YYYYMMDDHHmm`, 12-digit timestamp) 에서는 secondary 길이가 고정이라 lexical 정렬이 시간 순서와 일치한다. **주의 — 비표준 secondary 형식 시 lexical drift 재발**: - ``9.99`` vs ``9.100`` 형식은 secondary lexical 비교에서 ``"99" > "100"`` (잘못된 정렬). 본 프로젝트는 12-digit timestamp 만 사용하므로 안전. - 다른 secondary 형식 (예: dotted semver `9.1.2`) 도입 시 추가 numeric cast 필요. .r)splitintlen ValueError IndexError)r partss O/Users/manta/Documents/Projects/TheRoad-I1/backend/app/modules/prompt_loader.py_version_sort_keyr2s` JJsA EE!H 3u:>uQxBBrBB  #4ys 88A A)rAND schema_json IS NOT NULLmodule where_extraversioncRddlm}d|} |j||||dj}|sy|"|Dcgc]}|j |k(s|}}|sy|jdd|dS#t$r" |j #t$rYwxYwwxYwcc}w) uFprompt_template 중 (module, name, is_active=true) + extra where 매칭 row 들을 모두 가져와 ``_version_sort_key`` 기준 최댓값 row 반환. 없으면 None. SQL ``ORDER BY version DESC`` 는 lexical 이라 ``9.x`` > ``10.x`` 로 잘못된 정렬이 가능 (problems.md #7). Python in-memory 정렬로 numeric-aware. where_extra: ``_AllowedWhereExtra`` 닫힌 enum 으로 좁힘 — 신규 절을 추가 하려면 enum 에 명시 필요 (정적 보호). 직접 concat 방식이라 user-supplied 값을 받지 못하게 type-level 차단. W19A versioned-load (review §3.6): ``version`` 이 주어지면 그 version 과 정확히 일치하는 row 만 후보로 두고 sort. 없으면 None (latest 로 silent fallback 하지 않음 — caller 의 명시적 pin 을 깨지 않기 위해). r)textzSSELECT * FROM prompt_template WHERE module = :m AND name = :n AND is_active = true )mnNc,t|jSN)rr)rs rz+_select_latest_active_row..~s-aii8Tkeyreverse) sqlalchemyrexecutefetchall Exceptionrollbackrsort) dbrr rrsql_textsqlrowsr#s r_select_latest_active_rowr3Is*, @ -  zz(3-vD)ABKKM& 84a199#748II8$IG 7N3   KKM     *9s:)A6B$B$6 B!BB! BB!BB!prompts_base) lru_cache@)maxsizeresolvedreturnc ddl}t|z |z }|jr!td|j dDng}|st |d||j }|D]}|jt|j|jd|jd|j|j |jj|jddS) u해석된 프롬프트 팩 디렉토리의 파일 bytes 해시 16 hex (#77 공용). 버전 '문자열' 스탬프는 셀렉터 상수·해석 코드·서버 메모리 중 어느 층이 낡아도 안 움직인다 — 이 해시는 **이 프로세스가 실제 로드하는 디렉토리의 bytes** 를 지문에 접는다(2026-08-08 최종 스틸 253/311 재사용 사고의 수정을 multiroll_judge 전용에서 모든 팩 공용으로 승격). 팩 디렉토리는 불변 관례(덮어쓰기 금지·새 버전 디렉토리)라 프로세스 수명 동안 캐시한다. 부재·빈 디렉토리는 fail-closed — 없는 팩을 빈 해시로 접으면 "팩이 사라져도 지문이 안 움직이는" 같은 부류의 구멍이 다시 생긴다. rNc3BK|]}|js|ywr")is_file).0ps r z(pack_dir_content_hash..s>!!))+As*u. 팩 디렉토리가 없거나 비어 있다: utf-8)hashlib PROMPTS_BASEis_dirsortedrglobrsha256updatestr relative_toencode read_bytesdigest hexdigest)rr9rErootfileshr?s rpack_dir_content_hashrUs & 8 +D >tzz#> >#% hDTF KM MA  Q]]4()009:   /6689 ;;=" r%stemcddl}t|z |z |dz }|jst|d||j |j j ddS)u해석된 팩 디렉토리 안 **한 스템 파일**의 bytes 해시 16 hex. (2026-08-13 Codex R2): 소비 범위가 스템 하나인 절을 디렉토리 전체 해시로 지문에 접으면, 무관한 동거 스템 개정·selector 이동까지 전량 유료 재생성을 일으킨다 — 그 스템 bytes 만 접는다. 부재=fail-closed (pack_dir_content_hash 와 같은 이유). rN.mdu 팩 스템이 없다: rD)rErFr=rrJrOrQ)rr9rVrEr?s rpack_stem_content_hashrYsfv(dV3<7A 99;F8#:1#>?? >>!,,. ) 3 3 5cr ::r%rrX.json)promptschema)rr/kindc ddl}|tvrtdttd|d}d}d}i} |} |h t ||||dk(rdnd|} | N|dk(r | j n | j }|/|jd }d }d t| d di} t| d |} |t|} |8t|z |z || z }|jr|jnd}|}n&t||| \}}}||jnd}||j!d j#}|d}dt%|i} |} |||t'd|d|d|d|d|dndd t(||||| | |j+|j-dd|dk(rt/j0|d S|d S#t$r$} tjd|||| Yd} ~ 8d} ~ wwxYw)u#실효 source 하나를 **content + provenance 와 함께** 돌려준다 (GROUNDING-V2 §8). 왜 필요한가 — ``load_prompt`` / ``load_schema`` 는 각자 따로 source 를 고르고, ``pack_dir_content_hash`` 는 **파일 디렉토리 bytes 만** 해시한다. 그래서 같은 version 의 활성 DB row 가 생기면 **실제 prompt 는 바뀌는데 지문은 안 움직인다**. 이 함수는 loader 와 지문이 **같은 반환값 하나**를 소비하게 해서 그 구멍을 막는다. ``kind`` 가 ``.md``/``.json`` 과 ``content``/``schema_json`` 중 무엇을 고를지 정한다. ``locator`` 는 **어느 DB row · 어느 파일**인지를 남긴다. ★``raw_content_hash`` 는 **로드한 원본 source bytes** 의 해시다 — ``.strip()`` 이나 파싱 **전**이다. 파일 팩은 ``published_packs`` 래칫도 같은 bytes 를 해시하므로 두 값이 어긋나면 「팩이 바뀌었다」를 두 도구가 다르게 말하게 된다. provider 에 실제로 나간 payload 는 prompt 의 ``.format(**kwargs)`` 뒤 · schema 의 재직렬화 뒤라 **원리상 다르다** — 그쪽은 호출부가 ``payload_hash`` 로 따로 남긴다. 둘을 한 칸으로 합치면 format 인자가 바뀌어도 지문이 안 움직인다. Returns: { "contract_version": int, "kind": "prompt" | "schema", "module": str, "stem": str, "source": "db" | "file", "locator": {"db_row_id": ...} | {"file_path": ...}, "version": str | None, "raw_content_hash": str, # sha256 앞 16 hex "content": str | dict, # prompt=text, schema=parsed } Raises: FileNotFoundError: 어느 source 에서도 못 찾음. ValueError: kind 가 enum 밖. rNz'resolve_effective: kind must be one of z, got r\rrrrrBr/ db_row_ididrz7resolve_effective DB lookup failed (%s/%s, kind=%s): %sextfile file_pathz!resolve_effective: no source for /z (kind=z , version=z, db=yesno)rD) contract_versionr]rrVsourcelocatorrraw_content_hashcontent)rE _KIND_EXTrrHr3 schema_jsonrnrNgetattrr,loggerwarningrFexistsrO_resolve_stem_in_packdecodestriprLFileNotFoundError"RESOLVE_EFFECTIVE_CONTRACT_VERSIONrJrQjsonloads)rrVr]rr/rEraw raw_bytesrkrlresolved_versionrowexcrcfpath found_version _versionss rresolve_effectivershR 95fY6G5Hth WY YC!%I F G&- ~ +FD=AX=M9SUC )-)9coos{{? # 7 3I!F*GCt,DEG'.sIw'G$ {o   6)G3senDE.3lln((*$I#M.CFDVY.Z +E=).3.?((*TI  ""7+113C ?F"CJ/G,  {i'6>/xq?F*WKubnURV4WWX Z  ?##NN95??A#2F&*h&64::c?  =@  9  NNIdC   sA'F// G8GGc 6d}|r t||||}|r |j}|t |||}|"t d|d|| d|dzdz|r|jd i|S|S#t$r"}tj d|||Yd}~pd}~wwxYw) u프롬프트 텍스트 로드 (DB 우선, 파일 fallback). Args: module: 모듈명 (scene_extractor_v2, outlook_extractor 등) name: 파일명 stem (system, turn_scene_detail 등) db: SQLAlchemy session (없으면 파일만 사용) version: pack 디렉토리 / DB row version 정확히 일치하는 source 만 허용. None 이면 기존 latest-pack 동작 (numeric desc) 유지. W19A 가 floor_plan_prompt 의 v5↔v6 selector 를 안전하게 분기하기 위해 도입 (review §3.6). 다른 module 은 caller 가 version 을 전달하지 않는 한 동작 변경 없음. **kwargs: 프롬프트 텍스트의 format 변수 Returns: 포맷된 프롬프트 텍스트 N)rz!DB prompt load failed (%s/%s): %szPrompt not found: rf (version=rir)r3rnr,rrrs_load_from_filerxformat)rr r/rkwargsrnrrs r load_promptr+s,G  S+BgNC++ !&$@ $ 0*1*=G9A& G  CE G  (.>7>> #F #:7: S NN>c R R SsA-- B6BBcn|r> t|||d|}|r+|jrtj|jSt||d|}|rtj|Std|d|| d |d zd z#t$r"}t j d|||Yd}~nd}~wwxYw) u{JSON 스키마 로드 (DB 우선, 파일 fallback). Args: module: 모듈명 name: 스키마 파일명 stem (extract_schema 등, .json 확장자 제외) version: pack 디렉토리 / DB row version 정확히 일치하는 source 만 허용. None 이면 기존 latest-pack 동작 유지. ``load_prompt`` 와 동일한 의미. rr_z!DB schema load failed (%s/%s): %sNrZ)rcrzSchema not found: rfrrir) r3rprzr{r,rrrsrrx)rr r/rrrrns r load_schemarYs   S+FD9C szz#//22 fdIGzz'""  VHAdV,&-&9Zy " C ?A C  S NN>c R R SsA?ct|z }t|Dcgc]}||z |dz jr|c}Scc}w)u이 스템 파일을 **실제로 가진** 판 목록 (`_list_module_versions` 정렬 그대로). 부르는 쪽이 판 번호를 제 코드에 다시 적지 않게 하려고 있다 — 같은 목록을 두 자리에 적으면 한쪽만 고쳐진다. rX)rFrrt)rrVrvs rpack_versions_with_stemrsS &J,V4 94!QD6-557 4 99 9s"<ctjjd}| |jj dvS ddlm}tt|ddS#t$rYywxYw)upversion pack strict 모드 평가 (review I1). 우선순위: ``PROMPT_VERSION_PACK_STRICT`` ENV (있으면 그대로 사용) → ``settings.prompt_version_pack_strict`` (Pydantic, .env 자동 로드). ENV 직접 평가 분기는 import-cycle/legacy 호환을 위해 보존한다 — 운영자 instant-toggle (export 후 reload 없이) 도 가능. PROMPT_VERSION_PACK_STRICT)1truergonr)settingsprompt_version_pack_strictF) osenvirongetrwlowerapp.core.configrboolrqr,)r|rs r_is_version_pack_strictrsf **..5 6C yy{  "&@@@,GH&BEJKK sA A+*A+latest_versionc|||f}t5|tvr dddytj|dddtj d||||y#1swY#xYw)uS동일 (module, stem, version) 조합에 대해 process 당 1회만 warning 발행.NzPrompt version pack drift: module=%s stem=%s loaded_from=%s (latest_in_module=%s). To enforce single-pack semantics, set PROMPT_VERSION_PACK_STRICT=true and align stem files within the latest version directory.)_DRIFT_WARNED_LOCKr addrrrs)rrVrrr's r_emit_pack_drift_warningrsb 4 !C  -     #  NN  g~   s AAArcct|z }|jsddgfSt|}|D]%}||z ||z }|js |||fcSdd|fS)ustem 파일을 numeric-desc version 순회로 찾고 (path, found_version, all_versions) 반환. - found_version 이 ``all_versions[0]`` (latest) 와 다르면 drift 후보. - strict 모드면 latest 에 stem 없을 때 caller 가 RuntimeError 발생시킨다. N)rFrtr)rr rcrversionsverrs rrurusv&J    T2~$V,HS dVC5>1 <<>#x' ' x r%c |Dt|z |z ||z }|jsy|jdjSt |||\}}}|'t r|rt d||d|d|dd y|r|dnd}|r;||k7r6t rt d||d |d |d |d t||||||jdjS)uF파일에서 stem 의 최신 매칭 version 을 읽어 반환. 같은 module 안에서 stem 이 서로 다른 version 에서 로드될 수 있다 (backward-compat). drift 시 logger.warning + ``module_pack.drift`` 가시화. ``PROMPT_VERSION_PACK_STRICT`` 가 truthy 면 latest pack 에 stem 이 없을 때 RuntimeError 를 raise 하여 운영자가 prompt 정리 후 single-pack 으로 전환할 수 있게 한다. W19A versioned-load (review §3.6): ``version`` 이 주어지면 그 pack 디렉토리 안에서만 stem 을 찾고, 없으면 None 반환. latest 로 silent fallback 하지 않는다 (caller 의 명시적 pin 을 깨지 않음). 이 모드는 strict drift 검사를 적용하지 않는다 — 명시적 version 선택은 운영자가 이미 pack 을 알고 있다는 신호. NrB)encodingrbz"Prompt version pack strict: stem 'z&' not found in any version of module 'z'. Latest pack='rzh'. Add the stem to the latest version directory or unset PROMPT_VERSION_PACK_STRICT to use lenient mode.z' missing in latest pack 'z ' of module 'z' (resolved from 'zh' under lenient mode). Add the stem to the latest version directory or unset PROMPT_VERSION_PACK_STRICT.)rFrt read_textrwrur RuntimeErrorr)rr rcrr found_verr latest_vers rrrs<(v%/TF3%.@||~06688!6vt!ME9h } " $4TF3%@&&,X-=hqk]KBB   (!dJi:- " $4TF3%@# M&:;II  !D6#JO ??G? , 2 2 44r%c d}d}|@ t|||}|r0t|dd|jdtt|ddd}g}t|z }|jr> t|}|D]-} || z |dz } | js| t| d}n|d dd } n| d |d ndd } nddd } |d dd } nddd } |r|dnd} t|duxr| duxr|jd| k7}||||d| | d|| t|ddS#t$r"}t j d|||Yd}~d}~wwxYw#t$r"}t j d |||Yd}~d}~wwxYw)u``load_prompt`` 가 실제로 사용할 source 의 provenance 표시 (problems.md #8). admin UI 가 prompt_template DB row 만 보고 active prompt 판단하던 문제를 해소하기 위한 effective view. **caller 별 db 전달 여부에 따라 winner 가 다르므로 두 mode 를 동시에 표시** — db-aware caller (db 전달, 예: location _floor_plan_step) 와 file-only caller (db 미 전달, 예: scene_extractor_v2, background_master_plan 등 대부분의 pipeline module). Returns: { "module": str, "name": str, "candidates": { "db": {"id", "version", "is_active", "has_schema"} | None, "file": {"version", "path"} | None, }, "effective": { "with_db": {"winner": "db"|"file"|None, "fallback_reason": ...}, "without_db": {"winner": "file"|None, "fallback_reason": ...}, }, "module_pack": { "versions": [str], # numeric desc 정렬, 모든 version 디렉토리 "latest": str | None, "strict_enabled": bool, # PROMPT_VERSION_PACK_STRICT 평가 결과 "stem_drift": bool, # file_candidate.version != latest 면 True }, } winner 결정: - with_db: DB 후보 존재 → "db", 없으면 file → "file", 둘 다 없으면 None - without_db: DB 무시, file 만 — file → "file", 없으면 None ``module_pack`` (problems.md #6) 는 admin UI 가 stem-version drift 와 strict toggle 상태를 한눈에 볼 수 있게 한다. 이 view 는 ``.md`` 파일 후보만 고려하므로, schema (``.json``) drift 는 별도 ``get_effective_schema_source`` 로 확인한다. NraTrp)rar is_active has_schemaz-DB prompt effective lookup failed (%s/%s): %srX)rpathz/File prompt effective lookup failed (%s/%s): %sr/)winnerfallback_reasonrd no_db_sessionno_active_db_rowno_filerr)r/rd)with_db without_db)rlateststrict_enabled stem_drift)rr candidates effective module_pack) r3rqrrr,rrrsrFrtrrLrr)rr r/ db_candidatefile_candidaterr pack_versionsrrrrr pack_latestrs rget_effective_sourcer sJ.2L/3N ~ +B=C!#tT2"{{!%"&wsM4'H"I    "M&J 1&9M$"S(dV3<7<<>#& #E &N%!d;  #24*BT  "i@! &4@ $C &3-"Kd" 9 t # 9   y )[ 8J" $ &!57$   a  NN?s   &  NNA64QT   s5?D#+EE D>D99D> E, E''E,c|r t|||}|r |jS t |}|r|dSdS#t$r"}tj d|||Yd}~:d}~wwxYw)u현재 활성 버전 반환.uBprompt_template DB lookup failed for %s/%s: %s — 파일 fallbackNr)r3rr,rrrsr)rr r/rrrs rget_active_versionrsu  t+B=C{{" %V,H"8A;,,  t NN_agimor s s ts4 AAA)rN)NN)rX)rXNr")1__doc__rzloggingrpathlibr threadingrtypingrrrrr r getLogger__name__rrrsetr tuplerL__annotations__r_AllowedWhereExtrar3__file__resolveparentrF functoolsr6rUrYryrorrrrrrrrrurrrrr%rrsL!F  <<   8 $V+.5 s5c3'(0C(>?')! 6 6 6$ 6 c] 6t N##**1188   2#: ;3 ;# ;S ;S ; &'" 0 " j j j  j c] j #s(^j` ! +; +; +;c] +;  +;b ! $ $ $c] $  #s(^ $N#$s),9C9s9tCy9$ %(:= &(-   !$  8D>8C=$s) 34 ,! 05 05 05 05c] 05 c] 05fttCtT#s(^tn -s -# -8C= -r%