Imported from CheolyongKim/hwalro (apps/simulation-service/src/main/java/com/hwalro/simulation/search/AGENTS.md). Install upstream with npx skills add CheolyongKim/hwalro --skill search. Copyright stays with the author.

배치 개선안 탐색(Layout Search) 지침

• 배치 개선안 탐색은 완료된 기준 시뮬레이션 하나를 입력으로 받아 배치 변경 후보를 생성한다.
• 실측 검증은 선택 사항이며 기본은 하지 않는다(StartStudyRequest.verify). 검증이 탐색 시간의 대부분을 차지하고, 어떤 배치를 실제로 돌려볼지는 사용자가 정하는 편이 자연스럽기 때문이다. 선택은 searches.budget JSON의 verify에 저장하며, 이 필드가 없는 기존 행은 "검증함"으로 읽는다.
  • 검증할 때: 동일 조건(동일 seed·인원·좌표·위험 구역·출구)의 실제 엔진 실행으로 검증한 뒤, 기준 대비 실측 개선이 확인된 후보(EVALUATED)를 우선 제시하고 실측 델타로 순위를 매긴다. 개선 미달(NOT_IMPROVED)과 검증 실패(FAILED) 후보도 사용자가 배치와 실측 결과를 비교할 수 있도록 별도 결과로 반환하되, 채택 가능한 개선안으로 취급하지 않는다.
  • 검증하지 않을 때: 후보를 QUEUED로 두고 그대로 제시하며, 엔진이 매긴 candidate_order를 순위로 쓴다. 실측 지표와 "엔진이 검증한 공식 지표"라는 표현은 노출하지 않는다. 2라운드는 실측으로 개선된 부모를 확장하는 단계이므로 1라운드만 돈다.
• 정상 종료된 검증 실행은 개선 여부와 관계없이 검증 때 받은 엔진 결과(타임라인·히트맵 청크 포함)를 재사용해 완료 상태의 실제 시뮬레이션을 즉시 생성하고 prepared_simulation_id로 연결한다. 이 시뮬레이션은 시뮬레이션 목록 최상위에는 나오지 않고, 반드시 기준 시뮬레이션 행 아래 답글로만 노출되며 결과 화면까지 열람할 수 있다. 엔진 실행 자체가 실패한 후보만 simulations 행을 만들지 않는다.
• 표시하는 모든 수치는 엔진 산출 공식 지표다. 프록시 점수(proxy_score)는 내부 랭킹 전용이며 API 응답에 포함하지 않는다.
• 검증 trial의 시뮬레이션 시간 상한은 기준 대피 시간에 abort-margin을 더한 값으로 제한한다. 이 상한 안에 전원 대피하지 못한 후보는 실패가 아니라 NOT_IMPROVED로 처리한다.
• 탐색은 장시간 백그라운드 작업이다. trial 결과는 끝나는 즉시 개별 트랜잭션으로 커밋하며, 탐색 전체를 하나의 트랜잭션으로 묶지 않는다.
• 서비스 재시작 시 RUNNING 후보는 한 번 더 시도한다. attempt_count < 2이면 후보를 QUEUED로 되돌리고 trial의 종료 표시를 지운 뒤 활성 탐색을 이어서 재개하고, 두 번째 중단이면 trial을 SERVICE_RESTARTED 실패로 정리하고 후보를 FAILED로 둔다. 재시도 한도를 넘긴 탐색은 hasExhaustedRecovery 판정으로 실패 종료한다.
• 후보 채택 시에만 layout_versions 행과 선택적으로 시뮬레이션 DRAFT를 만든다. 이때 DRAFT의 parent_simulation_id는 기준 시뮬레이션이고, layout_version_id는 새로 만든 채택 버전이라 부모와 다르다. simulations의 부모 FK가 parent_simulation_id 단일 참조인 이유다.
• 채택 가능한 후보 상태는 EVALUATED와 QUEUED다. 검증하지 않는 탐색에서는 사용자가 고른 후보를 직접 돌려보는 것이 흐름 자체이므로, 실측을 준비의 전제로 둘 수 없다.