\jkOdZddlmZddlZddlmZmZmZmZm Z m Z m Z ddl m Z ejeZGdde Zd dZd d Zdd  dd Zy)uReference attachment contract validator — D5 identity-level + Area #5 sidecar edition. spec: docs/superpowers/specs/2026-05-09-attached-reference-identity-contract-design.md §4.4 docs/superpowers/specs/2026-05-18-area-5-reference-phrase-phantom-guard-replacement-design.md (Area #5 v1) plan: docs/superpowers/plans/2026-05-09-attached-reference-identity-contract-implementation.md Task 3 docs/superpowers/plans/2026-05-18-area-5-reference-phrase-phantom-guard-replacement-implementation.md required_refs 의 (kind, id) 가 attached_meta 에 exact match 로 존재해야 통과. substring/text 매칭 폐기. P1 (label 추론 X) + P2 (fallback meta 위조 X). 핵심 contract (D5): - character_outlook required → attached_meta 에 ("character_outlook", id) exact 존재. base "character" / "character_state" 는 만족 X (close_framing 무관). - character required (FINDING 9 W2 Cat2 — base_id_required subject) → attached_meta 에 ("character", id) exact 존재. "character_outlook" 은 만족 X. (P8 Inc2-b: "character_state" 는 같은 캐릭터의 state-variant ref 이므로 sid prefix 일치 시 만족.) - background required + NOT close → attached_meta 에 ("background", bg_id) exact 존재 또는 ("background_prev_shot", chain_bg_lookup(bg_id)) lineage 일치. chain_bg_lookup(bg_id)=None 이면 lineage 확인 불가 = missing. - readiness_policy=block_if_missing + required_refs empty → drift fail-fast. - meta length mismatch → 즉시 fail-fast (invariant 1). - sidecar phantom guard (Area #5 v1): reference_phrase_kinds (per-variation, producer emit) 의 각 kind 가 attached_meta 의 kind set 과 strict exact compare. legacy prompt-prose classifier + window-based heuristic 폐기. step 4 의 close-framing background skip 은 보존하지만 step 6 은 strict (axis 분리). D2 strict extractor 그대로 보존 (사용자 binding G1) — `or {}` silent fallback 금지. ) annotationsN)AnyCallableDictListOptionalSetTuple)AppErrorc$eZdZdZdfd ZxZS)RefContractErroruRequired ref 미첨부 또는 from-the-reference guard 위반 — generate 차단. HTTP 422 (validation error). caller 가 retry 1 회 (var_t2i rebuild) 또는 propagate. c*t|d|dy)Nzref_contract.violationi)codemessage status_code)super__init__)selfdetail __class__s U/Users/manta/Documents/Projects/TheRoad-I1/backend/app/core/ref_contract_validator.pyrzRefContractError.__init__.s )  )rstr)__name__ __module__ __qualname____doc__r __classcell__)rs@rr r (s   rr cb|Dchc]\}}| c}}tfd|DScc}}w)uYattached_meta set 안에 지정 kind 가 하나라도 있는지 (D5 §4.4 phantom guard).c3&K|]}|v yw)N).0kindattached_kindss r z!_meta_has_kind..>s8%$t~%%s)any) attached_setkindsk_r$s @r_meta_has_kindr+;s1$01LDAqaL1N 8%8 882s +c |iSt|tr|siSi}|jD]\}}t|ts$t dt |j d|t|ts't d|dt |j d||D]9}t|trt d|dt |j d|t|||<|St|trg|siSi}t|D]P\}}t|ts't d|dt |j d||jd }|jd }t|tr|s't d|d t |j d|t|tr|s't d|d t |j d||jd } t| ts't d|dt | j d| | dk7rt d|d| |j|gj|S|St dt |j d|)urequired_refs canonical normalization — manifest list shape ↔ dict shape. Two accepted shapes (D2): - manifest canonical (list of dicts): [{"kind": "character_outlook", "id": "C01O02", "policy": "required"}, ...] - legacy dict: {"character_outlook": ["C01O02"], "background": ["L01"]} Returns dict[kind, list[id]]. 빈/None → {}. Iter1+iter2 BLOCKING (Codex review): malformed input 은 silent drop 금지 — explicit []/{}/None 은 허용하되, wrong type / list item non-dict / kind|id 누락 / dict value non-list / id non-string / policy drift 는 RefContractError fail-fast (silent fallback 회로 차단, 사용자 binding G1). z:required_refs malformed: dict key must be str (kind), got =z-required_refs malformed: dict value for kind=z must be list, got z2required_refs malformed: dict value list for kind=z must contain str ids, got z#required_refs malformed: list item[z] must be dict, got r#idz$] 'kind' must be non-empty str, got z"] 'id' must be non-empty str, got policyz9] 'policy' must be str (only 'required' is allowed), got requiredz<] 'policy' must be exactly 'required' (producer drift), got z3required_refs malformed: must be list or dict, got ) isinstancedictitemsrr typerlist enumerateget setdefaultappend) raw normalizedr)ventryidxitemr#ridr/s r_normalize_required_refsrAAs  { #tI+- IIKDAqa%&7++,AaU4a&&CA5I$$(G$4$4#5Qqe=!%-* !u%#E{334AeY@!GJqM% &#tI "3ICdD)&9#?:../q:88F#D((4.CdC(&9#?--1$Z-@-@,A4(Lc3's&9#?--1#Y-?-?,@#JXXh'Ffc*&9#?<0016*> #&9#?CCI*N  ! !$ + 2 23 7=(>  Cy!!"!C7 , r)chain_bg_lookupc t|t|k7r$tdt|dt|d|i}d}nt|ts$tdt |j d|d|vr td|j d} | td t| ts$td t | j d| d | vr td | j d } | td t| }| j d}t|} |j dgD]M} d| f| vr | jdddtfd| Dr4td| dt| d|j dgD]#} d| f| vs td| dt| d|j dgD]8df| vr tfd| Drtddt| d|sddl m }ddlm}td | D}td!| D}|j d"gD]j}d"|f| vr |r |r|r||nd}|rd#|f| vr%|j!|xsd$r|d%d&d$|gd'|d()td*|d+|d,|d-t| |d.k(r$t|j#s td/| td0t|t$s$td1t |j d|d2}|D]}||vrtd3|d4|d5|dk(r&t'| d6std7|d8t| |d"k(r&t'| d9std7|d:t| |dk(sut'| d;rtd7|d.sW %1 " " /1c" /Q"h. /%>Azrequired character_outlook u missing — attached=ul (base 'character' ref 는 충족 X; 같은 캐릭터의 'character_state' 만 immobilized 대체로 충족)propzrequired prop z* (Tier 3 strict subset violation, Patch A) characterc3K|]8\}}|dk(xr*t|txr|jdddk(:ywrKrN)r"r)r<char_ids rr%z)validate_attached_refs..sW %1 " " .1c" .Q"g- .%rQzrequired character u< (base_id_required subject base ref 미첨부, FINDING 9 W2))BG_ID_RE)StaleUpstreamErrorc3vK|]1\}}|dk(xr#t|txr|jd3yw) backgroundz space_set_bg:Nr1r startswithr"r)r<s rr%z)validate_attached_refs..?s>% $1   V*Q"4 Vo9V V$79c3vK|]1\}}|dk(xr#t|txr|jd3yw)rYzoutdoor_canon:NrZr\s rr%z)validate_attached_refs..Gs?& $1   W*Q"4 WFV9W W$r]rYbackground_prev_shotbackground_renderu%(unknown — validator fallback path)zvalidator detected D6 bg_id u[ missing from attached_meta (preflight bypass) — POST /steps/background_render?mode=force)upstreamexpected_bg_catalog_hashobserved_bg_catalog_hashmissing_in_render remediationzrequired background z( missing (expected exact ('background', z) or ('background_prev_shot', u)) — attached=block_if_missingzGrpc drift: readiness_policy=block_if_missing but required_refs is emptyumreference_phrase_kinds missing — producer (scene_detail v26) emit required, no silent fallback (Area #5 v1)z4reference_phrase_kinds malformed: must be list, got )rSrYrRz+reference_phrase_kinds invalid enum value: z (allowed: ))rSrGrLz%reference_phrase_kinds declares kind=u- but no character meta attached — attached=)rYr_u% but no background meta — attached=)rRu but no prop meta — attached=)lenr r1r2r4rr7rAsetrOr&sortedapp.core.bg_state_vocabrVapp.core.errorsrWmatchvaluesr5r+)rpc labeled_refs attached_metapromptis_close_framingrBreference_phrase_kindsr0 readiness asset_reqraw_required_refsr'cidprop_idrVrW_space_set_bg_attached_outdoor_canon_attachedbg_id required_loc_ALLOWED_KINDSr#rPrUs @@rvalidate_attached_refsrscJ <C ..1#l2C1DE /00G I   {)+#' #t$"3DI4F4F3GqP  s *"@ GG01  "S )T*"I//0)@  ) +"I &MM/:  $"= ,,=>MM"45 ),]);L||/4  % 5 99S!$Q'  %   )#1|,-., -  5,<<+ G L 0"  ,"<012<= ,(<< R0  !\ 1   %   !'-|,-.J K  1"  56"%% $% " #&& $& #  \\,3Ee$ 4%&6E?51$L!7 F, V~~ekr*(0-T-/',g6ui@78  #&ui0227;,,8+;<"<013 54D&&s8??3D/E U  % 8   ,d 3./889;Q:T V  9N& ~ %"=dXF+,A/  ; ~ O( #7x@..4\.B-CE  <  @) #7x@%%+L%9$:<  6>.y"I"7x@"<013 +'r)r'zSet[Tuple[str, str]]r(zTuple[str, ...]returnbool)r:rrzDict[str, List[str]])rpzOptional[Dict[str, Any]]rqzList[Tuple[str, bytes]]rrzList[Tuple[str, str]]rsrrtrrBz(Optional[Callable[[str], Optional[str]]]ruz List[str]rNone)r __future__rloggingtypingrrrrrr r rmr getLoggerrloggerr r+rArr!rrrs8#BBB$   8 $  x  &9 QvAEE !E)E)E  E  E>E&E Er