Oj7UdZddlmZddlZddlmZmZmZmZm Z m Z ddl m Z m Z mZdZdZdZd Zd Zd ZefZd Zd ZdZeefZe fde fde e fdiZded<GddeZd3dZd4dZd5dZ dd d6dZ!d7dZ"dZ#dZ$e#e$fZ%d8dZ&d9d Z' d:d!Z(d"d# d;d$Z) dd)Z.d?d*Z/ d@d+Z0d"d# dAd,Z1 dBd-Z2Gd.d/eZ3dCd0Z4dDd1Z5dEd2Z6y)Fu`location_part` 참조 **묶음** — 맥락 + 상세. ★inert. 유료 0. ## 무엇인가 사용자 확정 (2026-08-31): 「1960년대 이발소 해서 하나로 검색 조사해야 해 … 아님 **둘을 찾아서 참조 두 개 이상으로** … 참조 이미지 여러 개로 해도 돼!」 `location_part` 하나가 **논리 멤버 둘**을 갖는다 — 맥락(context) 그 장소 — 「1960년대 이발소」 상세(detail) 그 부분 — 「이발소 회전 간판」 **같은 사진이면 한 장으로 합치고**, 다르면 둘 다 기존 `background` 자리에 붙인다. ★합쳐도 **논리 멤버 둘의 처분·신원·계보는 따로 남는다**. ## 세 가지를 고쳤다 (Codex 재현 2026-08-31) ①하류 SOT 가 뒤집혀 있었다 — raw `status` 를 봤다. 정본은 **`outcome`**(`selected` | `reference_unavailable`)이고 raw status 는 **감사용**이다. `outcome` 이 없거나 모르는 값이면 **조용히 건너뛰지 않고 선다** — 그러면 `selected` 의무가 사라진다. ②exact 열쇠에 **실제 획득 신원**이 빠졌다. `grounding:LP01:detail` 만으로는 **옛 자산**이 신원 바뀐 새 의무를 **만족시킨다**(재현됨). ③「같은 bytes 면 합친다」가 **구현이 없었다.** 같은 사진을 넣으면 2장이 나오고 역할 차례도 뒤집혔다. ## 왜 새 슬롯을 안 만드나 야외 직행 경로가 **이미** 사진+지도 두 장을 같은 `background` kind 로 넣는다. 그 모양을 그대로 쓴다 — 네 평행 목록에 **덧붙인다**. ★실측: **맥락·상세는 기존 배경판을 대신하지 못한다**(안 붙이면 `StaleUpstreamError`). 그래서 이것은 **더하는** 설계다. ## 아직 안 쓰인다 `app/` 어디서도 부르지 않는다. D 원자적 cutover 에서 general scene 경로가 **RPC sidecar 가 있을 때만** 이것을 부른다. ) annotationsN)AnyDictListOptionalSequenceTuple)PURPOSE_CONTEXTPURPOSE_DETAILPURPOSESz2.202609020800 backgroundref_kindref_rolecharacter_outlookoutfit_ref_explicit groundingselectedreference_unavailablebackground_generalgrounding_part_detail_refgrounding_context_detail_refzDict[Tuple[str, ...], str]ROLE_BY_PURPOSESceZdZdZy)BundleContractErroruC묶음이 계약을 어겼다. ★조용히 넘어가지 않는다.N__name__ __module__ __qualname____doc__e/Users/manta/Documents/Projects/TheRoad-I1/backend/app/modules/pipeline/grounding_reference_bundle.pyrrhsMr!rct|Dchc] }t|c}}|D]}|tvs td|dt|s tdt |Scc}w)uG쓰임들의 **정본 차례**. ★집합을 결정적으로 만든다.u모르는 쓰임 u — u쓰임이 없다)sortedstrr rtuple)purposespgots r" _purposes_keyr*lsj (+(Q#a&(+ ,C  H %(9!eH:&NO O !"455 : ,sAct|jdxsdj}|tvrt d|dtd|S)u멤버의 **처분**. ★없거나 모르는 값이면 **선다**. ★★★조용히 건너뛰면 `selected` 의무가 사라진다 (Codex 재현 2026-08-31). 앞 판은 raw `status` 를 봤고, `outcome` 이 비면 「아닌가 보다」로 지나갔다. outcomeu 처분이 다 — uX 중 하나여야 한다. (raw status 는 감사용이고 의무를 정하지 않는다))r%getstripOUTCOMESr)mr)s r" _outcome_ofr3ws\ aeeI$" % + + -C (!y 3M NO O Jr!ctj}|D]<}|jt|j d|jd>|j ddS)Nzutf-8)hashlibsha256updater%encode hexdigest)partshr(s r"_foldr>sRA  Qw'(  ;;=" r!r )covered_final_idsc t|tr t|gn!t|Dchc] }t|c}}|Dcgc]}|js|}}|s t dt|Dchc]+}t|xsdjs!t|-c}}|s t dt |}t|Dchc]+}t|xsdjs!t|-c}xs t |}tddj|ddj|dt|dt| Scc}wcc}wcc}wcc}w)u`attached_meta` 에 실을 값. ★**출처·쓰임·신원·덮는 의무**를 다 나른다. ★★★신원이 빠지면 **옛 자산이 새 의무를 만족시킨다** (Codex 재현) — 획득 계약이 바뀌어 다시 사야 하는데 옛 사진이 붙어 있으면 통과했다. Args: subject_final_id: 이 참조의 **주인**. 부모 장소 맥락이면 `L01`, 그 장소 부분 상세면 `LP01` 이다. covered_final_ids: 이 한 장이 **덮는 의무들**. 부모 장소 맥락 한 장이 형제 `LP01`·`LP02` 의 맥락 의무를 같이 덮는다 — 그때 여기에 둘 다 적힌다. ★★앞 판은 `subject_final_id` 밖에 없어서 형제마다 **같은 사진을 따로** 넣게 되어 있었다 (Codex BLOCK · 09-01): 모델에 같은 사진이 중복되고 참조 장수 상한도 낭비한다. ★비면 주인 자신만 덮는다. `subject_final_id` 가 비었다r-uJ획득 신원이 없다 — 무엇으로 샀는지가 값에 안 실린다:+) isinstancer%r$r0rr*set SOURCE_PREFIXjoinr>) subject_final_idr'member_identitiesr?xsubjectsidspscovs r" meta_valuerOsV*.4%&'-=>-=SV-=>? $18aqwwy8H1 !"DEE "3L"3Qs17|7I7I7K#a&"3L MC ! XZ Z x B "3L"3Qs17|7I7I7K#a&"3L"M #CoQsxx12!CHHRL>Szl!E#J< )*?1M Ms)EEE5"E E "E$0 E$ct|xsdjd}t|dk7s |dtk7ry t |djd}|djdt ||d |d d S#t $rYywxYw) u`attached_meta` 값을 되읽는다. 조사 것이 아니면 `None`. ★이름을 해석하지 않는다 — **우리가 만든 값**의 모양만 읽는다. r-rBrNrC)subject_final_idsr' identity_fold covered_fold)r%splitlenrFr*rlist)valuer<rMs r"parse_meta_valuer]s    " "3 'E 5zQ%(m3 58>>#. /"'q!4$r("1XuQx AA sB B  B assetfilect|jdxsdj}|tvrt d|dtd|t k(r>t|jdxsdj}|s t d||dSt|jd xsdj}|s t d ||d S) u:멤버 하나의 **좌표**. ★갈래를 명시로 받는다. {"source": "asset", "asset_id": ""} ← DB/service 가 읽는다 {"source": "file", "path": "<정본 경로>"} ← 파일에서 읽는다. ★asset_id 를 **주장 안 한다** ★`ref_image_map` 의 열쇠는 **참조 map key** 지 ImageAsset UUID 가 아니다 (실측). 그것을 쓰려면 `ref_map_key` 로 **따로** 부른다 — `asset_id` 라고 부르면 읽지 않은 UUID 가 계보로 남는다. sourcer-u좌표 갈래가 r.uN 중 하나여야 한다. `asset_id or path` 로 모호하게 두지 않는다asset_idu+`source=asset` 인데 `asset_id` 가 없다)rarbpathu&`source=file` 인데 `path` 가 없다)rarc)r%r/r0SOURCESr SOURCE_ASSET)r2srcvs r" coordinate_ofrhs aeeHo# $ * * ,C '!wiy9C CD D l j!'R ( . . 0%&ST T1-- AEE&M R &&(A !"JKK1 %%r!ct|jdxsdt|jdxs|jdxsdfS)Nrar-rbrc)r%r/)cs r" _coord_keyrksD h%2 & j!8QUU6]8b 9 ;;r!c2i}|D]}t|}t|jdxsd}|s tdt|jdxsd}t |g|jddu}|t k7s|rt|jdxsd}|st|d|d t|jd xsdj }|st|d|d t|} t|jtxst} t|jtxsdxsd} | tvr | d |d |n| d |} |j| g|gggggg| | d } | d| k7rt|d| dd| | dj|| dj| | dj|| dj|| djd|jdxs|fD|jdr | djt|d|jdsa| djt|dg}g}t|D]n} || }t |d}tt!|d}t#|||d|d}|dxst$j|} | td|dtt$t|dDcic]}t'||c}j)}|j|t+|| ||d |Dcgc]\}}| c}}dj-tt!|dxsdtt!|dtt!|dtt!|d|d d! |j|d |fq||fScc}wcc}}w)"ut논리 멤버들 → **붙일 자리들** + **정확히 붙어야 하는 짝**. ★★★**bytes 를 안 받는다** — CP 는 JSON 이라 bytes 를 못 담는다. durable sidecar 는 **좌표**(`source`+`asset_id|path`)와 `content_sha256` 을 적고, 소비하는 쪽이 읽어 **해시를 확인**한다. ★★★**같은 사진이면 한 장**으로 합치되 — 합쳐도 **논리 멤버 둘의 좌표·신원·계보를 전부 보존**한다 (Codex 재현 2026-08-31: 앞 판은 `setdefault` 가 **첫 좌표만** 잡아 둘째 자산 계보를 잃었고, `plan_bundle(AB) != plan_bundle(BA)` 였다). ★서로 다른 좌표가 **같은 sha** 를 말하면 둘 다 남기고, **어느 것으로 읽을지는 결정적으로** 고른다(`coordinates[0]`). 읽은 뒤 해시를 확인하므로 거짓 주장은 그때 걸린다. rHr-rApurpose not_attachedNmember_identity/u! 에 `member_identity` 가 없다content_sha256ub 가 `selected` 인데 `content_sha256` 이 없다 — 사진이 맞는지 확인할 길이 없다) rVrq coordinatesr'rIlabelsparent_final_idsr?rrru5 의 역할이 같은 자리 안에서 갈린다 — z vs rVrsr'rIr?c3nK|]-}t|xsdjs!t|/yw)r-N)r%r0).0rJs r" zplan_bundle..8s-)P5q#ag2,:L:L:NCF5s"55coverslabelrtparent_final_idru)rHr'rIr?u쓰임 조합 u! 에 맞는 역할이 없다 — u · r) rVr'rolerOrqrsrzrIrur?r)r3r%r/rr*OUTCOME_SELECTEDr0rhMEMBER_KIND_KEY BUNDLE_KINDMEMBER_ROLE_KEYSINGLE_SUBJECT_KINDS setdefaultappendextendr$rErOrrkitemsr[rG)membersby_hashr2r,lprmdeliberately_noneidentshacoordkindr|keyslotplanrequiredsrMrKvalrjcoords_ks r" plan_bundlers"*,G a. )*0b 1%&HI IaeeI&,"-wi EE.1= & &*; AEE+,23%$ay ABD D!%%()/R0668%$ay!BBC Ca 155)8[9155)/R08D..vbTu-7;fF3%4H !!#!#s2Bbr$ (    t #%$K #&d4(45 5 !((, ]""5) Z( !((/ !(()PUU8_55)P P 55> N ! !#aj/ 2 55" # # $ + +C2C0D,E FGJ"$D&(Hg CL 1Z= )#a 3456(R+,-@+A+,-@+AC }8 0 4 4R 8 <% $E*+,./ / "#M"24"2Q$A)"2449EG= !)tBx 01+126%"aA62[[AhK(8!9:@b!'A.A,B(C!D &s1-?+@'A B!'A.A,B(C!D*    :,-?@ >!4 3s #P , Pr-)wherect|}d}t|D]j} t| jdxsd} | s&tdj | dd| ddt | jd xsd } d } i} g}t | D]\}}||\}}|s)tdj | dd| dd |d tj|j}|| k7r/tdj | dd| dd|d| d|d |jt|xsi|dk(s|t|xsi} } | J|jdt | jdxsd | f|jdt | jdxst| df|jd| d| dt| dt| dt| dt| jdxsdt| d| d t| || d }| jdrt| d|d<|r||d<|jd||dz }m|S)u`plan_bundle` 이 낸 **좌표**로 사진을 읽어 네 목록에 **덧붙인다**. Args: load_bytes: `(coordinate) -> (bytes, resolved)`. ★반환이 **bytes 만이면 안 된다** — 그러면 읽지도 않은 자산 UUID 가 계보로 남는다. ★★★**좌표를 전부 읽어 전부 확인한다** (Codex 재현 2026-08-31). 앞 판은 `coordinates[0]` 만 확인하면서 metadata 에는 **좌표 전부**를 계보로 적었다 — 둘째 좌표가 **다른 사진인데 같은 해시를 주장**해도 통과하고 그 경로가 계보로 남았다. 즉 **확인하지 않은 자산이 계보**가 됐다. 읽는 것은 **무료**이므로 전부 읽고, 하나라도 없거나 해시가 다르면 **provider 앞에서 선다**. 쓸 것은 **첫 좌표**로 결정적으로 고른다. ★기존 것을 안 지운다. 차례는 `plan_bundle` 이 정한 정본을 지킨다. rrsr rCrVrpr'u 에 좌표가 없다rqr-Nu 의 사진을 못 읽었다 (u<) — 계보에 적을 좌표는 **전부** 읽혀야 한다u 의 좌표 u9 가 **다른 사진**을 가리킨다 — 적힌 해시 u · 읽은 것 u8. 확인 안 한 자산을 계보로 남기지 않는다rzrrOr|r?rI) pipeline_roler'rVgrounding_subject_idsr?rIrqrsverified_sourcesresolved_sourcerurrS)r[reversedr/rrGr% enumerater7r8r;rdictinsertr) labeled_refs attached_meta ref_rolesref_role_metadatar load_bytesrr)nr2rwant first_rawfirst_resolvedcheckedirjrawresolvedrmetas r"insert_bundle_refsres( t*C A c]aeeM*0b1%88A1234Aa m_DYZ\ \155)*0b1%) )+(*f%DAq&qMMC)xx"5 678!J-IsVXYY..%//1Cd{)xx"5 678!J- UVTWXKKO(RagUWXX NN4B/ 0Av,/hn"1E> &$$$AAEE'N$8b 99EFQQUU:%6%E+!F!"<!2 3AfI&vYQz]+!%a(;&::<신원>` 이라 다른 것과 안 겹친다. u조사가 고른 참조 u개가 안 붙었다: uS — 기존 배경판이나 클로즈업 면제가 이것을 대신하지 못한다N)r%rrZ)rrkrghavemissings r"assert_grounding_attachedrs*7 7ASVSV D 7,40HDAqq63q6"$.AAHG0!&s7|n4J7)T] ]^ ^ 80s B8B ct|}ttjthz}t |Dchc] }||vs| c}Scc}w)u이 묶음이 쓰는 역할 중 **아직 선언 안 된 것**. ★`REF_ROLE_VALUES` 는 **닫힌 목록**이라 모르는 역할이면 즉시 선다. D cutover 에서 이 목록이 **비어야** 켤 수 있다. )rErvalues OUTLOOK_ROLEr$)knownrusedrs r"undeclared_rolesrsK u:D &&( )\N :D d4datm1d4 554s AAgrounding_bundle_membersgrounding_required_attachmentscft|tsyt|vry|t}t|ts)t dtdt |j d|D]3}t|trt dt |j |Dcgc] }t|c}Scc}w)uNRPC 에서 묶음 멤버를 꺼낸다. ★**키가 없을 때만** `None`(옛 길). ★★★앞 판은 `rpc.get(...)` 이 `None` 을 주면 **키가 없는 것과 똑같이** 옛 길로 접었다 (Codex 재현 2026-08-31): `{members: None}` 이 조용히 통과했다. schema marker 에 쓴 것과 **같은 원칙**을 여기도 쓴다 — 키 없음 → `None`. 옛 CP 라 옛 길이 맞다 키 있고 목록 → 그 목록 (빈 목록은 **명시 「없음」**) 키 있는데 목록 아님 → **선다** (`None` 포함) N`%` 가 있는데 목록이 아니다: u4 — 모르는 것을 옛 것으로 읽지 않는다u멤버가 dict 가 아니다: )rDrRPC_MEMBERS_KEYr[rtyper)rpcr)rJs r"members_from_rpcrs c4 c! o C c4 ! ECy!!""V XY Y!T"%0a1A1A0BCE E! !SDGS !! !sB.c @t|tsyt|vry|t}t|ts(t dtdt |j g}|D]}t|trL|jt|jdxsdt|jdxsdf_t|ttfr:t|dk(r,|jt|dt|d ft d ||S) uaRPC 에 **적힌** 요구를 읽는다. ★**키가 없으면 `None`** — 「없음」과 다르다. ★★★앞 판은 `rpc.get(...) or []` 라 **키 없음**과 **명시 빈 목록**을 못 갈랐고, 잘못된 타입(`{}` 등)도 조용히 삼켰다 (Codex 재현). 그러면 만드는 쪽이 요구를 안 적었는데 「없다고 적었다」로 읽힌다. 키 없음 → `None` (만드는 쪽이 안 적었다) 키 있고 목록 → 그 목록 (빈 목록은 **명시 「요구 없음」**) 키 있는데 목록 아님 → **선다** Nrrrr-r\rRrrSu요구 모양이 이상하다: ) rDrRPC_REQUIRED_KEYr[rrrrr%r/r&rZ)rr)outrJs r"required_from_rpcrs c4 s"  C c4 ! !!FCy!!" $% %"$C  a  JJAEE&M/R0#aeeGn6J2KL M D%= )c!fk JJAaD 3qt9- .%(Gu&MN N  Jr!c*ddl}|Dcgc] }t|}} |j|dt |\}}||t <|D cgc] \}} || d c} }|t<|Scc}w#t$r}t d|d|d}~wwxYwcc} }w)u9**만드는 쪽**이 members 와 required 를 **한 번에** 적는다. ★원자적. ★★★canary 나 시험이 sidecar 를 **손으로 두 벌** 만들면, 그 둘이 어긋난 채로 굳는다 (Codex 2026-08-31). 그래서 **이 함수 하나**가 — ①JSON 으로 담을 수 있는 모양인지 본다 (bytes 가 섞이면 선다) ②`plan_bundle` 로 요구를 낸다 ③members 와 required 를 **같은 RPC 에 같이** 적는다 ★소비하는 쪽은 **이 함수를 안 부른다** — 읽고 대조만 한다. rNF) ensure_asciiu 멤버를 CP 에 못 담는다 (uE) — durable sidecar 는 bytes 가 아니라 **좌표**를 적는다)rr\)jsonrdumps TypeErrorrrrr) rrrrJr)exc_planrrrgs r" write_sidecarrs# $Gq47GC $: 3U + "#&OE8CAIJAa!4JC O % :!.se40 0169 :: Ks"A)A. B. B 7BB c t|}|yt|\}} t|} | tdtdt | t | k7r#tdt | dt | t |||||||S)uRPC 에 sidecar 가 **있을 때만** 붙인다. ★없으면 **아무것도 안 한다**. ★★★**요구를 쓰지 않는다** — 읽고 **대조만** 한다. 쓰면 SOT 가 아니게 되고, 조립이 이 호출을 빠뜨리면 쓰기도 같이 빠져 거짓 통과한다. 멤버 키 없음 → 0. 목록 한 글자도 안 바뀐다 멤버 키 있는데 목록 아님 → **선다** 멤버는 있는데 요구 키가 없음 → **선다** 요구가 다시 낸 것과 **다름** → **선다** 맞으면 → 좌표로 읽어 붙인다(해시 확인) rusidecar 는 있는데 `u{` 키가 **없다** — 만드는 쪽이 둘을 같이 적어야 한다(`write_sidecar`). 소비하는 쪽은 안 만든다uJ적힌 요구와 멤버에서 다시 낸 것이 **다르다**: 적힌 것 u · 다시 낸 것 )rr)rrrrrr$r) rrrrrrrrrexpected persisteds r"attach_from_rpcr4ss#G )ND(!#&I!%&6%780 01 1iF8,,! +,,?x@P?Q ST T lM9/)35 BBr!c8t|}|syt||y)uRPC 에 **적힌** 요구가 붙었나. ★조립·검사 **뒤에** 부른다. ★기존 `validate_attached_refs` 의 클로즈업·plate 면제와 **별개**다 — 조사가 고른 것은 그 면제로 대신 채워지지 않는다. N)rr)rrrs r"assert_from_rpcrUs!%H h 6r!ceZdZdZy)ReferenceCountRefuseduV참조 장수가 provider 가 받는 범위 밖이다. ★보내기 **전에** 선다.Nrr r!r"rrms`r!rct|dd}t|s!tt|jd|}t |t s!tdt|jt |S)uclient 에게 **직접 묻는다**. ★registry 를 베끼지 않는다. ★없으면 **선다** — 「아마 다 받겠지」로 지나가면 잘린 참조가 **그림에서만** 드러난다. reference_input_capabilityNuf 에 `reference_input_capability()` 가 없다 — 몇 장을 받는지 모르는 채로 안 보낸다u%능력 계약이 dict 가 아니다: )getattrcallablerrrrDr)clientfnr)s r" capability_ofrqs 5t >14 8Q#~~j)**W XZ Z ~!c"g+#~~j)*,rd:Uc   ~!c"g+#~~j)*,rd:J1#N7 78 8&~r!ct|jdxsdt|jdxsdt|jdd|jd|jddS) uD지문에 접을 것 — **provider class/model + 능력**. ★provider 를 바꾸면 같은 문안·같은 참조라도 **다른 산출**이다. 능력이 바뀌면 보낼 수 있는 장수가 달라진다. 둘 다 지문에 들어가야 옛 산출이 「지금 계약의 것」으로 통하지 않는다. rr-modelrTrr)rrrrr)r%r/bool)rs r"capability_lockrsi z28b9Z^^G,23!% NN2D 9"; nn\2 nn\2  r!)r' Sequence[str]returnzTuple[str, ...])r2Dict[str, Any]rr%)r<rrr%)r'rrIrr?rrr%)r\r%rzOptional[Dict[str, Any]])r2rrDict[str, str])rjrrzTuple[str, str])rSequence[Dict[str, Any]]rz2Tuple[List[Dict[str, Any]], List[Tuple[str, str]]])rrrrrrrrrrrrrr%rr)rSequence[Tuple[str, str]]rrrNone)rrrz List[str])rrrzOptional[List[Dict[str, Any]]])rrrzOptional[List[Tuple[str, str]]])rrrrrzList[Tuple[str, str]])rrrrrrrrrrrrrr%rr)rrrrrr)rrrr)rrrrrr)rrrr)7r __future__rr7typingrrrrrr +app.modules.pipeline.grounding_host_contextr r r BUNDLE_CONTRACT_VERSIONrr~r OUTLOOK_KINDrrrFr}OUTCOME_UNAVAILABLEr1r__annotations__ RuntimeErrorrr*r3r>rOr]re SOURCE_FILErdrhrkrrrrrrrrrrrrrrrr r!r"rs#%L#==CC+ # $ % - 1 2,2n%'E0,N,N 35"*"/"*"/"*9<"*J A$   %&6;zGz@68G "&G ;?G 5G $'G 03G =@G T^-F^#'^(6.-3"6>38M<@BB#B8<BB-0B9<BFIBB 7#< 7AE 70aLa$82r!