-ǚj:ndZddlmZddlZddlZddlZddlmZmZm Z m Z m Z ddl m Z mZddlmZddlmZej*eZdZd Zd Zd Zd Zd Zd ZdZGdde Z!Gdde"Z#Gdde Z$ddZ%d dZ&d!dZ'd"dZ(d#dZ) d$dZ* d%dZ+d&dZ,d'dZ-d'dZ.y)(u-엔티티 신원 계약 — `short_id` 발급과 수명 상태를 **한 곳**에서 정한다. ## 왜 이 모듈이 있나 2026-09-04 실측(골목 끝 `da049582`, 3화). 화마다 `short_id` 를 **위치 기준으로 `01` 부터** 다시 매기고 있었다 (`entity_steps._assign_short_ids`, `outlook_steps`). `entity_canon` 의 유일성은 `(project_id, short_id)` 라 2화의 `C01` 이 1화의 `C01` **행을 찾아 덮었다** — 1화 CP C01=민수 2·3화 CP C01=정임 지금 DB C01=정임 1화 CP O01=남색작업복 3화 CP O01=감색차장제복 → DB O01 은 이름이 「감색차장제복」인데 붙어 있는 참조 이미지는 **1화가 만든 남색작업복**이다. 그림과 이름이 갈렸다. 그래서 번호는 **모델도 스텝도 아니고 프로젝트 장부가 소유한다.** 한 번 쓴 번호는 다시 안 나온다. ## 이 모듈이 지키는 것 - 발급은 `project_short_id_counter` 의 **줄지 않는 값**에서 나온다. - 첫 값(seed)은 DB 최대값**만으로는 안 된다** — 이미 지워진 번호를 다시 발급하게 된다(실측: 1화 `O03 회색외투` 는 DB 에 없지만 1화 체크포인트에는 살아 있다). **살아 있는 모든 에피소드 체크포인트**까지 같이 본다. - `O00` 은 Null Outlook **예약값**이다. 발급기는 절대 내지 않는다. - 상한은 999 다. 소비자 정규식 20여 곳이 ``[CLPO]\d{2,3}`` 로 세 자리까지만 받는다. 넓히는 것은 별도 범위이고, 여기서는 **넘기 전에 선다.** ) annotationsN)AnyDictIterableListOptional)or_text)Session) OWNER_PREFIXO00iactiveorphanedshelved)short_id outlook_idceZdZdZy)SeedUnreadableu_seed 를 정할 근거(체크포인트)를 못 읽었다. ★낮은 seed 로 가면 안 된다.N__name__ __module__ __qualname____doc__N/Users/manta/Documents/Projects/TheRoad-I1/backend/app/core/entity_identity.pyrrGsirrceZdZdZy)ShortIdBadValueu[앞 단계가 준 `short_id` 가 계약 밖이다. ★그대로 믿으면 남을 덮는다.NrrrrrrKserrceZdZdZy)ShortIdExhaustedu\발급 가능한 번호를 다 썼다. ★조용히 넘어가면 남의 번호를 덮는다.Nrrrrr!r!Osfrr!c tj|}|td|t|cxkr tks!nt |d|dtdtd||dS)uM`("character", 7)` → `"C07"`. 100 부터는 자연히 세 자리가 된다.모르는 갈래: u 번호 u 은 발급 범위 밖이다 (~u). 소비자 정규식이 세 자리까지만 받으므로 여기서 선다 — 넓히려면 그 정규식들을 먼저 고쳐야 한다.02d)r get ValueError SHORT_ID_MIN SHORT_ID_MAXr!)ownernumprefixs rformat_short_idr-Ss   e $F ~-eY788 C /< /gXcU#~Q|n-j kl lXc#Y rcZddlm}|t|xsd}|y|\}}||k(r|SdS)u`("character", "C07")` → `7`. 그 갈래의 것이 아니면 `None`. ★`split_final_id` 를 쓴다 — 접두표가 prefix-free 가 아니라서 (`L` 과 `LP`) 직접 자르면 `LP01` 을 `L` 것으로 읽는다. r)split_final_idN).app.modules.pipeline.grounding_entity_contractr/str)r*rr/got got_ownerr+s rparse_short_idr5`s> N X^, -C {NIsu$3.$.rct|trQ|jD]=\}}|tvr$t|tr|r|j |2t ||?yt|tr|D]}t ||yy)uDJSON 을 훑어 `short_id`/`outlook_id` **키의 값**만 모은다.N) isinstancedictitems_SHORT_ID_KEYSr2append_walk_short_idslist)nodeoutkvs rr<r<osm$JJLDAqN"z!S'9a 1 3' ! D$ A As # rc ddlm}tj|j|z dz dz }|j syd}g}|j dD]g} tj|jd}g}t|jd||D]} t|| } | t!|| }i|r t#d t%|d |d |d d |S#t$r|jt|YwxYw)u/살아 있는 **모든 에피소드 체크포인트**에서 그 갈래의 최대 번호. ★없으면 0. 읽다 깨진 파일은 건너뛰되 **조용히 넘어가지 않는다** — 못 읽은 파일이 있으면 그만큼 seed 가 낮아져 남의 번호를 다시 발급할 수 있다. r)settings checkpointsepisodesz*/*/manifest.jsonzutf-8)encodingdataNu살아 있는 체크포인트 u개를 못 읽어 `uw` 번호 seed 를 못 정한다 — 낮은 seed 로 발급하면 이미 쓴 번호를 다시 낸다. 먼저 고쳐라: )app.core.configrCpathlibPath projects_diris_dirglobjsonloads read_text Exceptionr;r2r<r&r5maxrlen) project_idr*rCrootbest unreadablemfrGfoundsidr+s rcheckpoint_high_waterr\|s ) <<-- . ;m Kj XD ;;= DJii+, ::bllGl<=D(%0C ,C4~-,S_,==PQVPWX!!+BQ 0 23 3 K#    c"g &  s%C###D D c|jtdd|ij}d}|D]\}t||}|t ||}!|S)uJ`entity_canon` 에 이미 있는 그 갈래의 최대 번호. 없으면 0.zRSELECT short_id FROM entity_canon WHERE project_id = :pid AND short_id IS NOT NULLpidr)executesql_textfetchallr5rS)dbrUr*rowsrWr[r+s r db_high_waterrdsh ::h ; z %HJ  DUC( ?tS>D Krc  |dkrgS|tvrtd|tt|||t ||}|j t d|||d|j t d||||dj}|td|d|d t|d}||z d z}|tkDrt|d td |d |dt||d zDcgc]}t||c}Scc}w)u2그 갈래의 다음 번호 `count` 개를 **원자적으로** 발급한다. ★조회와 발급이 따로면 동시에 도는 둘이 같은 번호를 받는다. 한 문장으로 올리고 그 반환값을 쓴다 — 락을 따로 잡지 않아도 PostgreSQL 이 이 행을 직렬화한다. ★첫 호출에서 seed 를 넣는다. seed = max(DB, 살아 있는 체크포인트). 둘이 나란히 seed 를 넣어도 `ON CONFLICT DO NOTHING` 으로 하나만 들어가고, 둘이 같은 값을 계산했으므로 결과가 같다. rr#zINSERT INTO project_short_id_counter (project_id, owner, high_water) VALUES (:pid, :owner, :seed) ON CONFLICT (project_id, owner) DO NOTHING)r^r*seedzUPDATE project_short_id_counter SET high_water = GREATEST(high_water, :seed) + :count WHERE project_id = :pid AND owner = :owner RETURNING high_water)r^r*rfcountu*short_id 장부를 못 올렸다 (project=z, owner=)ru 번호가 u 를 넘는다 (요청 u 개, 끝 u^). 소비자 정규식이 세 자리까지만 받는다 — 넓히는 것은 별도 범위다.)r r'rSrdr\r_r`fetchone RuntimeErrorintr)r!ranger-) rbrUr*rgrfrowendstartns rreserve_short_idsrqsW z  L -eY788 }RU3$Z7 9DJJx RE48: **X  E4%H  J KS(*   {8 HUGST UW W c!f+C %K!OE \g[.EeWIVYUZ[j kl l05UC!G/D E/D!OE1 %/D EE Es+Dc t|}i}t|D]\}}t|jdxsdj }|s5|t k(rt d|d|dt||} | t d|d|d|d t| cxkr tksnt d|d td td||vrt d|d ||d |d|||<|Dcgc]1}t|jdxsdj r0|3} }| r.t| t|||t| D] \}}||d< |Scc}w)u`short_id` 가 **없는** 것에만 프로젝트 번호를 채운다. ★이미 있는 것은 건드리지 않는다 — 앞 화에서 물려받은 신원이다. rr0u 예약값 u. 이 일반 신원으로 들어왔다 (자리 rh`u` 는 `u"` 의 신원이 아니다 (자리 u0) — 갈래가 섞였거나 형식이 틀렸다u` 가 발급 범위 밖이다 (r$u'` 를 두 줄이 갖고 있다 (자리 ·uC) — 한 판 안에서 신원이 겹치면 뒤가 앞을 덮는다) r= enumerater2r&stripNULL_OUTLOOK_SHORT_IDrr5r(r)ziprqrT) rbrUr*entitiesrcseenier[r+needs rassign_short_idsr~s >D D$1!%% #)r*002  ' '!SE!OPQsRSTV VUC( ;!C5w&HL=>? ?3|3!C57 ~Q|nTUVX X $;!C5?S {"QCPPQR RS ' ( Ht!3quuZ'8'>B#?#E#E#GAtD H $ 1"j%T STFAsAjMU K Is %1EEcddlm}|j|jj |j |k(|j |k(|jtk7j}|Dcgc]}|d c}Scc}w)u**이 화에서 살아 있는** canon id — 보류(`shelved`)를 뺀 것. ★★★이것이 「이 화에 무엇이 나오나」의 **정본**이다. 소비자마다 링크를 직접 읽으면 보류 제외가 한 곳만 붙고 나머지는 샌다 — 실측 2026-09-04: 이 화 링크를 읽는 자리가 **21곳**인데 거르는 곳은 **1곳**이었다. ★쓰는 쪽(sync 서비스)은 이것을 **안 쓴다.** 그쪽은 보류 링크도 봐야 `active` 로 되살릴 수 있다. r)EntityEpisodeLink) app.models.projectrquerycanon_idfilterrU episode_idpresence_statusPRESENCE_SHELVEDall)rbrUrrrcrs ractive_episode_canon_idsrs|5 88%.. / 6 6$$ 2$$ 2))-==  ce   $QAaD$  s0 A?cddlm}|j|j|j|k(|j |k(j }|r|S|j|j|j|k(|j jdj }|sgStt|||}|Dcgc] }|j|vr|j|vr|"c}Scc}w)u**이 화의** 인물↔아웃룩 배정 행. ★★★`character_outlook` 은 2026-09-04 (alembic 014) 전까지 화 범위가 없었다. 그래서 같은 인물이 1화에 O01, 2화에 O02 를 입으면 **2화가 둘 다** 생성·검증·프롬프트 재료로 봤고, 한 화의 `O00` 이 다른 화 판단까지 오염시켰다 (Codex BLOCK 2026-09-04). ## legacy(`episode_id IS NULL`) 를 어떻게 다루나 ★★앞 판은 exact 와 **모든 NULL 행을 OR 로 무조건 합쳤다.** 그런데 014 는 기존 행을 전부 NULL 로 남긴다 — 그러면 손상 복구 대상인 **다중 화 legacy 프로젝트에서 과거 옷과 `O00` 이 모든 화로 다시 들어온다.** 고치려던 것이 그대로 돌아오는 셈이다 (Codex BLOCK 2026-09-04 재지적). 그래서 계약을 좁힌다 — 이 화의 exact 행이 **하나라도** 있으면 → **exact 만** 하나도 없으면 → NULL 행 중 **이 화의 active 링크 양 끝** (인물·아웃룩 **둘 다**)에 걸린 것만 ★양 끝을 요구하는 까닭: 한쪽만 걸린 행은 「이 화의 배정」이라고 볼 근거가 없다. 모호하면 넓히지 않는다. r)CharacterOutlookN) rrrrrUrris_setr character_idr)rbrUrrexactlegacyrrs repisode_outlook_rowsrs04 HH% & - -##z1##z1  ce   XX& ' . .##z1##''- ce   )"j*E FF Dv!~~'ALLF,B v DD Ds%C/cnt|||Dcgc]}|j|jfc}Scc}w)u>`(character_id, outlook_id)` 쌍 — 위와 **같은 범위**.)rrr)rbrUrrs repisode_outlook_pairsrDsC*"j*E GE^^Q\\ *E GG Gs2)r*r2r+rkreturnr2)r*r2rr2rz Optional[int])r>rr? List[str]rNone)rUr2r*r2rrk)rb OrmSessionrUr2r*r2rrk) rbrrUr2r*r2rgrkrr) rbrrUr2r*r2ryzIterable[Dict]rz List[Dict])rUr2rr2rr)rUr2rr2rz List[Any])/r __future__rrOloggingrJtypingrrrrr sqlalchemyr r r`sqlalchemy.ormr rr1r getLoggerrloggerrwr(r)CANON_STATUS_ACTIVECANON_STATUS_ORPHANEDPRESENCE_ACTIVErr:rjrr'rr!r-r5r<r\rdrqr~rrrrrrrs)6# 66,0G   8 $   " ,j\jfjfg|g   / $"J *F*F #*F,/*F8;*F*FZ%% #%,/%;I%%P ()DXGr