֓j UdZddlmZddlZddlZddlZddlZddlmZm Z ddl m Z ddl m Z ddlmZmZmZdZd Zd Zd ZdZd Zd ZdZej4dZej4dZej4dZeZdZ dZ!d@dZ"Gdde#e Z$dZ%e&e$jNe$jPe$jRhZ*e&e$jVe$jXe$jZe$j\hZ/e&e$jZe$j\hZ0e&e$jZe$j\e$jNe$jRhZ1e$jVe&e$jXe$jZe$jPe$jRhe$jXe&e$jZe$jPe$jRhe$jZe&e$j\e$jPhe$j\e&e$jNe$jPhiZ2de3d<dAdZ4edGddZ5edGdd Z6dBd!Z7dBd"Z8dCd#Z9dCd$Z:dDd%Z;d&d' dEd(Z dHd+Z? dId,Z@dJd-ZAdKd.ZBdLd/ZCdMd0ZDdNd1ZEdMd2ZFdCd3ZGdOd4ZHdPd5ZIdQd6ZJ dRd7ZKdd8 dSd9ZL dTd:ZM dTd;ZNdMd<ZO dUd=ZPd>ZQ dVd?ZRy)Wup검색 후보 라운드 journal — 순번 예약과 상태 전이의 단일 권위 (A4). 재실행이 후보 파일을 덮어쓰던 것보다 큰 문제는 **계보 소급 변조**였다. form_ref 자산이 그룹당 한 row 였고 그 `file_path` 를 계속 갱신했으므로, 재검색 한 번이 과거 씨드의 입력 간선을 다른 이미지로 바꾼다. 그래서 라운드 디렉터리와 선택 자산 UUID 를 **불변**으로 두고, 그 예약·전이를 이 모듈이 단독으로 소유한다. ★step CP 는 journal 이 될 수 없다. force 는 `_execute` **전에** `clear_checkpoint()` 로 CP 를 지우고(`step_runner.py:1194`), `save_checkpoint` 는 `_execute` 가 **끝난 뒤**에 불린다 (`_execute_and_finalize` 7단계 중 (6)). 그래서 실행 중에 durable 한 저장소가 따로 필요하다. CP 는 최종 소비 projection 일 뿐이다. 저장 구조 — **상태를 둘이 중복 소유하지 않는다**: /rounds/index.json 순번 예약 + manifest 경로만 /rounds/rNNN/manifest.json ★그 라운드 상태의 유일한 SOT index 와 manifest 가 어긋나거나, index 가 깨졌거나, registry 에 없는 라운드 디렉터리가 있으면 **디렉터리 스캔으로 복원하지 않고 fail-closed** 한다. 부분 실패의 잔재를 정답으로 승격시키지 않기 위해서다. 동시성 — 현재 StepRunner 의 단일 claim 이 allocator 직렬화 전제다. 한 그룹에 두 실행이 동시에 들어오는 구조가 생기면 이 모듈에 락이 필요하다. 계획 = docs/superpowers/plans/2026-08-02-a4-round-immutable-candidate-store.md ) annotationsN) dataclassfield)Enum)Path)AnyDictListroundlegacy legacy_flatroundsz index.jsonz manifest.jsonz ^r(\d{3,})$z^cand_(\d+)\.png$z^[0-9a-f]{64}$)ref_pack_versiontarget_policy_version) statusform_ref_asset_id form_ref_pathform_ref_sha256round_id path_kindround_contract_versionrrgroup_fingerprintct|tt|tk7ryt|tt|tk7ry||k(S)u값과 **타입 계약**을 함께 본다. ★`True == 1` 이라 순수 값 비교는 bool 을 정수로 받아들인다 — 결속과 exact 대조가 둘 다 뚫린다(실측). F) isinstanceboolfloat)abs Z/Users/manta/Documents/Projects/TheRoad-I1/backend/app/modules/pipeline/form_ref_rounds.py typed_equalr!is? !TjD11!Uz!U33 6Mc(eZdZdZdZdZdZdZdZdZ y) RoundStateopened candidatesselected asset_bound finalized abandonedresolved_no_refN) __name__ __module__ __qualname__OPENED CANDIDATESSELECTED ASSET_BOUND FINALIZED ABANDONEDRESOLVED_NO_REFr"r r$r$vs' FJHKII (Or"r$ generativezDict[RoundState, frozenset]_ALLOWED_TRANSITIONSc$ddlm}|||d)Nr)AppErrori)codemessage status_code)app.core.errorsr:)r;r<r:s r _failr?s( g3 ??r"T)frozenceZdZUded<ded<ded<ded<ded<ee Zd ed <ee Zd ed <ddZddZ e ddZ y)Roundstrrr$stateinput_fpintcontract_versionpreallocated_asset_id)default_factoryDict[str, str] provenanceDict[str, Any]resultcr|jtvxr$|j|k(xr|jtk(S)u이어갈 수 있는가 — 지문과 계약이 **exact 일치**할 때만. 어긋난 라운드를 이어가면 다른 입력의 산출이 한 라운드에 섞인다. )rD OPEN_STATESrErGROUND_STORAGE_CONTRACT_VERSIONselfrEs r is_resumablezRound.is_resumables< JJ+ % H ) H%%)GG r"c|jtjtjfvxr;|j|k(xr*|j t k(xrt|jS)u유료 호출 없이 CP 로 다시 투영할 수 있는 끝난 라운드인가. ★두 종착이 여기 들어온다. `FINALIZED` 는 **자산이 있는** 완료고, `RESOLVED_NO_REF` 는 **자산이 없는** 확정이다. 투영하는 쪽이 `has_reference` 로 갈라 봐야 한다 — 안 가르면 없는 자산을 검증하러 간다. ) rDr$r3r5rErGrPrrMrQs r is_reusable_finalizedzRound.is_reusable_finalizeds^ JJ://1K1KL L " ) "%%)GG "T[[!  r"c<|jtjk7S)u3이 라운드가 **사진 자산을 남겼는가.**)rDr$r5)rRs r has_referencezRound.has_referenceszzZ7777r"N)rErCreturnr)rXr) r,r-r.__annotations__rdictrKrMrSrUpropertyrWr6r"r rBrBs^M M "'t!.bad0s 1dV2cU3CDr"rzstatus=u (사진 없는 확정은  여야 한다))rrr=u/ (사진 없는 확정에 사진 칸이 있다))rrrr1 (비어 있지 않은 문자열이어야 한다)rzresult.round_contract_versionrrrr;Noku) (저장된 산출은 'ok' 여야 한다)rzform_ref_path=rzform_ref_sha256=u' (64자리 소문자 hex 여야 한다)rz path_kind=u (완료 산출은 u*완료 산출에 투영 필드가 없다: )rrCrXNone) r$r5getNO_REF_RESULT_STATUSrrrrC _SHA256_REmatchr3ROUND_PATH_KINDROUND_CP_PROJECTION_KEYS)rMrDrrkeyshakmissings ` r _validate_result_shaper&shE *** ::h #7 7 '&**X.12,,@+C?T ULCzz#se1VZZ_/0EEFM5C C1se1VZZ_//`ab5 6::67d8; =  zz(t# gfjj*--V WX O4 5 nVZZ8; <= **& 'C c3 z'7'7'< sg%L MN $$$ zz+/1 jK034!!0 3? D E1VZZ_- 3%qC++\] ^1vzz23$4793F2Qavoq2GF 8 BCGs  I  I c t|}|jsyt|jD]T}|j rt j |js3|j|vsBtdd|d|dVy)u_registry 에 없는 라운드 디렉터리를 주워 담지 않는다. ★index 가 아예 없을 때도 검사한다 — manifest 를 쓰고 index 를 쓰기 전에 끊긴 상태가 정확히 그 모양이고, 그때 "라운드 없음"으로 답하면 다음 실행이 같은 번호를 다시 열어 예약 UUID 를 갈아치운다. Nround_registry_mismatchz registry(u%) 에 없는 라운드 디렉터리: u( — 스캔으로 복원하지 않는다) reexistssortediterdiris_dir _ROUND_ID_RErr|r?)rdknownidx_path rounds_dirchilds r _assert_no_stray_round_dirsr`sY'J     **,-||~\%7%7 %C  ::U " )H:%J5'R67 8 .r"c t|}|jst|t|tgdSt |d}t |tstd|dt|jd|dd}|tk7rtd|d|d td |jd }t |tstd|d t}|D]}t |tstd|d ||xsijd}t |trtj|std|d|||vrtd|d|td|dt }|xsijd} | |k7rtd|d|d| d|d |j#|t||||S)uregistry 를 읽고 디스크와의 정합을 확인한다. ★깨졌거나 어긋나면 **디렉터리 스캔으로 복원하지 않는다.** 부분 실패 잔재를 세면 이미 예약된 번호를 다시 내주게 된다. )rrrGrround_index_corruptru: root 가 dict 가 아니다rGru$: 지원하지 않는 저장 계약 u (현재 )ru : rounds 가 목록이 아니다u': rounds 원소가 dict 가 아니다: ru: 잘못된 round_id u: round_id 중복 / manifest_pathru 의 경로가 u 이다 (기대 )rhrrsetrPrrrZr?rrlistrCrrrbrmadd) rdrindex idx_contractentriesrentryrid want_pathgot_paths r read_indexrus 9%H ??  $ISUXN$B  x&; |nM78; <ii!G gt $ #z1Q%RS EE%& 'JEeYO Q{ +#s#<+=+=c+B 'H:5J3')R S %< 'H:5Gw)O P''qQ~.>? KR$$_5 y 'Jb_XLA&M, -  #+, J Lr"c|tj|j}|rt|j dSdS)uU라운드 번호의 **수치** 순번. 문자열 비교는 r1000 이후 뒤집힌다.)rrrrFgroup) round_objms r _round_seqrs19--.A3qwwqz?'R'r"cg}|jdxsgD]V}tj|jdxsd}|s.|jt |j dXd|rt |dzdSddS)uZ★열린 partial 라운드도 이미 예약된 번호이므로 반드시 카운트한다.rrrr03d)rrrappendrFrmax)rusedrrs r _next_round_idrs D8$**   uyy4: ; KKAGGAJ (+$D A c2 33Ac2 33r"ct||}|jstd|dt|d}t |||S)umanifest 를 읽고 **shape 과 identity 까지** 확인한다. ★identity 검증이 없으면 manifest 의 `round_id` 만 바꿔도 그 값이 그대로 권위가 된다(실측: r001 의 manifest 에 r999 를 적자 `resolve_round` 가 디스크에 없는 r999 를 정상 반환했고, 그 상태는 **유료 `_run_group` 을 탄 뒤에야** manifest missing 으로 죽었다). round_manifest_missingu 가 없다rrrr)rnrr?rparse_manifest)rdrrdatas r load_roundrsG )X .D ;;= &4& (<= d!9 :D $ ==r"c Pt|tstd|d|jd}||k7rtd|d|d|d t |d}|jd }t|tr|std|d |jd } ttjt|}t||k7rtd|d||jd}|t|tstd|dt|jd|d} | tk7rtd|d| dtd|jdt} | turtd|dt| tstd|d| t| tt k7r+td|dt#| dt#t dt D])} t%| | rtd|d| d| | d+t| } |t&vr |std|d |j(d!d|jd|fd"|jd"|fd#|jd#| fg} |tj*tj,fvr#| j/d$|jd$|ft D](} | j/| |j| | | f*| D]+\}}}t1||rtd%|d&|d|d'|d(-t3|||)t5|||| || t|xsi*S#t t f$rtd|d wxYw#t ttf$rtd|d |wxYw)+u'manifest dict 를 검증하고 `Round` 로 만든다. ★**읽기와 쓰기가 같은 validator 를 쓴다.** 쓰고 나서 읽으며 검증하면, 잘못된 산출이 이미 durable 해진 뒤에 오류가 난다 — 실측: bad sha 로 전이를 요청하자 오류는 났지만 `state='selected'` 와 그 sha 가 영속됐고, 이어지는 재개도 같은 오류로 막혀 **그 라운드가 영구 재개 불능**이 됐다. 그러면 "실패면 라운드를 열어 두고 이어간다"는 계약과 정반대가 된다. ru&: manifest root 가 dict 가 아니다r round_manifest_identity_mismatchu: manifest 가 u 이라고 말한다 (기대 u+) — 그 값을 권위로 삼지 않는다rDu: 알 수 없는 staterEu:: input_fp 가 비어 있지 않은 문자열이 아니다rHu0: preallocated_asset_id 가 UUID 가 아니다: u:: preallocated_asset_id 가 canonical UUID 가 아니다: rMu: result 가 dict 가 아니다rG)rr#round_manifest_unsupported_contractu: 저장 계약 u$ 은 지원하지 않는다 (현재 rrKu: provenance header 가 없다u%: provenance 가 dict 가 아니다: u: provenance 키가 u 다 (정확히 rz : provenance.rrruM 인데 산출이 없다 — 그 상태는 산출 없이 존재할 수 없다rrrround_manifest_header_mismatchu : 산출의 u 이 header 의 u7 과 다르다 — 같은 라운드의 것이 아니다)rDrrrDrErGrHrKrM)rrZr?rr$KeyErrorrrCuuidUUIDAttributeError TypeErrorrrPMISSINGrPROVENANCE_KEYSrrRESULT_REQUIRED_STATESrr2r3rr!rrB)rrrgot_idrDrEraw_uuid asset_uuidrMrGraw_provrrKbindingsrgotwants r rrs; dD ! &<= ? XXj !F  0ofZ/L GI J4=)xx #H h $H &PQ Sxx/0H3x=12  8} " &P  XXh F *VT": &4&0O(PQ!$((+=">T(:<99 3&'7&8978; < xx g.H7 &4&0N(OP h % &;H<H J 8}O,, &*6(+;*<="?34OE FXc]+ *F-uAhsm->?EF G hJ && *F"U[[M*01 2J/ : &**-@"A8 L % ZZ0 13C E  Z++Z-A-AB B OO$fjj1D&E #C OOS&**S/:c?C D# ( E3sD)6l5'3'9I$RKLM !) vU> )(FLb! o j ! &4&0F(GH   2 &FxlS U s M'M> M;>'N%ct|}|jdxsgDchc]}|xsijd}}||vrtd|dt||Scc}w)u**registry 에 등록된** 라운드만 읽는다. ★`load_round` 를 직접 부르면 `index.json` 을 우회한다 — registry 가 깨졌거나 그 라운드가 등록돼 있지 않아도 manifest 만으로 통과한다(실측: index.json 을 깨뜨린 뒤에도 CP 재사용 검증이 통과했다). journal 이 단일 권위라면 registry 정합이 먼저다. rrround_not_registeredu) 가 registry 에 등록돼 있지 않다)rrr?r)rdrrers r load_registered_roundrBst y !E1681D1J1J L1J1ag2]]: &1JE Lu $ CD F i ** MsA ct||S)uW그 라운드의 후보 사진이 사는 곳. **라운드 밖으로 새지 않는다.**)rkrjs r candidate_dirrRs i **r"c$t||}|jsyg}|jD]M}tj |j }|s%|j t|jdO|rt|dzSdS)uc그 라운드에서 다음 후보 파일이 쓸 번호. ★라운드 **번호** 예약과 달리 이쪽은 디렉터리를 본다 — 층이 다르다. 라운드 번호는 journal 이 소유하는 전역 순번이라 스캔으로 복원하면 이미 예약된 번호를 다시 내주지만, 후보 번호는 **그 라운드 디렉터리 안에서만** 의미가 있고 거기 있는 파일이 곧 사실이다. 이 값이 없으면 실패로 열린 채 남은 라운드를 다음 재개가 이어갈 때 1번부터 다시 써서 **그 라운드의 이전 후보를 덮어쓴다.** r) rrr_CAND_RErr|rrFrr)rdrdrrrs r next_candidate_indexrWsu i*A 88: D NN5:: & KKAGGAJ (#CIM))r"ct|}|jdxsgDcgc]}t||dc}Scc}w)Nrr)rrr)rdrrs r list_roundsrmsM y !Eii)/R/ 2/ y!J- 0/ 22 2s<ct|Dcgc]}|jtvs|}}t|dkDrt ddt|d|r|dSdScc}w)u@살아 있는 라운드 — 있으면 하나뿐이어야 한다.rround_multiple_open열린 라운드가 4개다 — 어느 쪽이 권위인지 알 수 없다rN)rrDrOlenr?)rdrlives r find_open_roundr ssi"9- H-!K1GA-D H 4y1} !"3t9+-a b d47$$ Is AAclt|}t|}|1tdd|jd|jj dt |}|tjj |tttjt|d}t||t||t!t|||t#|j%dxsg}|j'|t(d|dt*d t!t-|t|d t/||S) uk새 라운드를 열고 **자산 UUID까지 미리 채번**해 durable 하게 남긴다. ★UUID 를 여기서 박아 두지 않으면, 같은 라운드를 이어가는 재개가 자산을 또 INSERT 한다. 미리 정해 두면 어느 저장소가 먼저 끊겨도 재개가 같은 UUID 로 수렴하고, 불일치는 검증에서 드러난다. round_already_openu#이미 열린 라운드가 있다: z (u!) — 닫고 나서 새로 연다)rrDrErGrHrKrrr)rrr)rr r?rrDrrr$r/rPrCruuid4rZrrnrrrrrbrmrhr)rdrErKrr rrrs r open_roundr}s+ y !E 9 %D  1$--4::CSCSBTU* + ,e$H""((:!$TZZ\!2:& G7X&y(;=~i:GD599X&,"-G NN+,AhZq8HI {9-:0 i **r"rMc t||}|jtvr&td|d|jjdt j |jt}||vrFtd|d|jjd|jdtd|Dd | t|n |j}|tvr|std |d|jd |j|j|j|j|jt|j |d }t#||}t%||| t'||t||S)uK상태 전이 — 종료된 라운드는 더 쓸 수 없다. ``result`` 를 주면 상태와 **한 번의 원자 쓰기**로 함께 확정한다. 상태와 산출을 따로 쓰면 "FINALIZED 인데 result 가 없는" 창이 생기고, 그 창에서 끊기면 재개가 완료 라운드를 재사용할 수 없다. round_immutableu 는 u' 로 닫혔다 — 이후 쓰기 금지round_illegal_transitionru → u% 는 허용되지 않는다 (가능: c34K|]}|jywrar).0ss r z#transition_round..s/w!aggwsrround_result_missingu% 는 저장된 산출을 요구한다rr)rrDTERMINAL_STATESr?rr8r frozensetrrZrMrrrErGrHrKrnrr) rdr new_staterMcurrentallowed effectivermpaths r transition_roundr smH-G}}' jgmm1122Y Z \#&&w}}ikBG  &j7==../uY__4EF//w//0 3 4 !' 2V I**9 $ "Y__--RS U$$$$#44!(!>!>7--.G 9h /E7XE:ug& i **r"c~t|tr|std|dt||tj |S)ug**사진 없이** 라운드를 닫는다 — 생성이 곧 정본인 대상. ★자산을 묶지 않는다. 가짜 자산을 만들어 `FINALIZED` 로 보내면 재투영이 없는 파일을 검증하러 가고, 그 검증을 느슨하게 하면 진짜 자산이 사라진 것도 못 잡는다. 그래서 **다른 종착**으로 닫는다. ru<: 판정 없이 사진 없는 확정으로 닫을 수 없다r)rrZr?r r$r5rdrrMs r resolve_round_without_referencer#sC fd #6 $ VW Y Ix1K1K#) ++r"c~t|tr|std|dt||tj |S)uD라운드를 닫는다. 이후 bytes·manifest·asset 전부 불변.ru(: 최종 산출 없이 닫을 수 없다r)rrZr?r r$r3r"s r finalize_roundr%sC fd #6 $ BC E Ix1E1E#) ++r"c8t||tjS)uL라운드를 버린다. 번호는 소비된 채 남는다(재사용 금지).)r r$r4rjs r abandon_roundr's Ix1E1E FFr"ct|}|Dcgc]}|jtvs|}}t|dkDrt ddt|d|r5|D]}t ||j tt|||dS|rQ|d}|j|r t|dSt ||j tt|||dS|Dcgc]}|j|s|}}|rt|t } t| d Stt|||dScc}wcc}w) ud이번 실행이 쓸 라운드를 정한다 (계획 §2.3 행렬의 단일 구현). | 상황 | 동작 | |---|---| | explicit force | 열린 라운드를 ABANDONED 로 닫고 **반드시 새 라운드** | | resume · 지문 exact 일치 | 그 라운드를 이어간다 | | resume · drift | ABANDONED → 새 라운드 (번호는 소비된 채 남는다) | | FINALIZED 인데 최종 CP 만 없음 | **유료 0콜**로 그 라운드를 재투영 | ★마지막 행이 없으면 `_execute` 종료 후 `save_checkpoint` 직전 crash 가 유료 전체 재실행으로 바뀐다. rrrr)rErKFr)rE)rT) rrDrOr r?r'rr]rrSrUrr) rdrEforcerKrrr rr)latests r resolve_roundr+sX  #F 8v!K!7AvD 8 4y1} #$SYK/cd f A )QZZ 0 y8", ./46 6 q'     2"7E2 2i!1!12 y8", ./46 6#QFqa&=&=x&=&PFIQYJ/vt,, 9xJG PP9 9,RsD8D8#D=;D=zVuuid5(NAMESPACE_URL, theroad:structure_form_ref:project:episode:group:location:sha256)cddl}|r|r|r|r|s tdt|j|jd|d|d|d|d| S)u^투영한 형태 참조의 자산 id — 입력이 같으면 항상 같다(재개 idempotent).rNufprojected_asset_id: 다섯 칸이 전부 있어야 한다 — 빈 값으로 id 를 만들지 않는다ztheroad:structure_form_ref::)rrrCuuid5 NAMESPACE_URL) project_id episode_idgroup_id location_idsha256_uuids r projected_asset_idr63su :({vBC C u{{5..8 Aj\QRS[R\\]^i]jjklrkstv wwr")rrrrrXr)r;rCr<rCrXr)rdrrXr)rdrrrCrXr)rrrrLrXr) rrrrrrCr;rCrXrF)rrr;rCrXrL)rrrXr)rMrLrDr$rrrXr)rdrrrrrrXr)rdrrXrL)rz'Round'rXrF)rrLrXrC)rdrrrCrXrB)rrrrCrrrXrB)rdrrrCrXrF)rdrrXz List[Round])rdrrXz Round | None)rdrrErCrKrJrXrB) rdrrrCrr$rMzDict[str, Any] | NonerXrB)rdrrrCrMrLrXrB) rdrrErCr)rrKrJrXr]) r0rCr1rCr2rCr3rCr4rCrXrC)Sr_ __future__rr}rrer dataclassesrrenumrpathlibrtypingrr r rPrLEGACY_ROUND_IDLEGACY_PATH_KINDLEGACY_CONTRACT_VERSIONrbrgrmcompilerrrobjectrrrr!rCr$rrr3r4r5rr/r0r1r2rO BOUND_STATESrr8rYr?rBr]rerhrkrnrrrrrrrrrrrrrrrr rr r#r%r'r+PROJECTED_ASSET_ID_RULEr6r6r"r rDs8# (""2"#   rzz.) 2::* + RZZ) *  (@   (d ($$*.. 0J0JLMz,,// *--z/E/EFG #//1E1E $yz22J4H4H"""$%9Z11""&$% 4 4$67Ij22'45 51  @  $-8-8-8` $-0-< 4  8; :7D!%7D*.7Dt8*.8378*6r( 4 >rj + + *,2 %*+)*+.3*+^(,/+/+"/+/9/+$/+ /+d + +" +/= +  + ++"+/=+ +G .P.P"%.P.2.P.P.Phsw$'w14w9<wr"