"""번들 다리 (계획 2026-09-27 L6 §2.5 · D-L6-2 · D-L6-8 · D-L6-9). case 잠금 **안**에서 hook 이 부른다. 순서: 1. **백필** — `BackfillOptions(case=a/c, root=target.projects_dir, mirror_root=blob_mirror_root(), index_root=hub_index_root(), repo_root=target.repo_root, run_ids=frozenset({run_id}))` → `backfill_case(opts, target.context)`(wrap → 미러 → 번들 색인 → eval-wrap). `CaseReport.runs` 는 정확히 하나여야 한다(0 이면 `run_not_in_archive`). 부류 → 코드: wrap `written·reused·rewrapped_input_fields` → 번들 있음 · `frozen:` → `bundle_frozen:`(hub 는 `no_bundle`) · `error:` → `bundle_error:` · 번들 색인 `error:` → `bundle_index:`(계속) · eval-wrap `error:*` → `eval_wrap:`(계속 — 번들은 있다) · eval-wrap `skip:*`·`frozen:*` 는 정보 · `BackfillError` → `mirror_unadoptable`. 2. **재채점**(번들이 있을 때만) — lcs_diff 계열(D-L6-8: run.json 스냅샷 `config.evaluator_config.config.type`, 스냅샷이 없으면 run 디렉토리 평가 파일의 `poc_bundle.legacy_run.evaluator_family`)이면 `rescore_case(a, c, run_ids={run_id})`(case 모드 채택 규칙, D-L6-9) → `written|exists` 가 ok · `no_results` skip → `rescore_empty` · 그 밖 skip → `rescore_skip:` · 오류 → `rescore_error:`. 계열이 아니면 `not_proofread_family`(정보 — "이 평가기는 M2 채점 번들 생산자가 없다", Q-M2-1). 3. **색인** — `indexes.refresh`(lock·템플릿·텍스트 모드·추출기·색인 코드 키가 바뀌었을 때만, D-L6-7). 다리 결과는 하나의 `LegResult` 다. 실패가 여럿이면 **순서상 첫 실패**가 `code` 이고, 단계마다의 결과는 `detail` 에 모두 남는다 (상태 파일 §2.7): `{"backfill": run_entry, "rescore": {"status", "code"?, "bundle_id"?}, "indexes": <코드>}`. 번들이 있으면 실패여도 `detail.backfill.wrap` 이 남아 hook 이 `types.bundle_ready` 로 hub 다리를 돈다(D-L6-2). 색인 CLI 의 정합성 경고가 있으면 `index_warnings: <건수>`, 치운 옛 색인 디렉토리가 있으면 `index_removed: [<이름>…]` 를 더한다(리뷰 지적 2·4 — 줄 자체는 `indexes` 가 stderr 로 낸다). **단계 예외 봉쇄.** 재채점·색인 단계의 예기치 않은 예외는 그 단계만 `rescore_exception:`·`indexes_exception:` 실패로 강등한다(타입 이름만) — 백필이 만든 번들을 버리지 않고 hub 다리까지 가게. 백필 자체의 예외는 hook 이 `bundle_exception:` 으로 강등한다(번들 유무를 모른다). 원문·locals 는 싣지 않지만 **발생 위치**는 남긴다(리뷰 지적 5): 가장 안쪽 프레임의 `<파일 basename>:<줄>:<함수>` 를 `detail.exception_at.<단계>` 에(고객 데이터가 없는 코드 좌표), 트레이스백 전체는 이 모듈 로거에 (`hook` 과 같은 규칙 — 기본 DEBUG, `SOLAR_EVAL_HOOK_DEBUG=1` 이면 WARNING). `poc_bundle`·`solar_eval.rescore` 는 함수 안에서만 import 한다(D-L6-14). 출력·detail 에는 id·부류·코드만(고객 텍스트 없음). """ from __future__ import annotations import logging import traceback from collections.abc import Mapping from dataclasses import dataclass, field from pathlib import Path from typing import Any from solar_eval.hub_hook import indexes, optin, target from solar_eval.hub_hook.types import ( BUNDLE_ERROR_PREFIX, BUNDLE_FROZEN_PREFIX, BUNDLE_INDEX_FAILED_PREFIX, EVAL_WRAP_FAILED_PREFIX, MIRROR_UNADOPTABLE, NO_BUNDLE, NOT_PROOFREAD_FAMILY, PROOFREAD_EVALUATOR_TYPE, RESCORE_EMPTY, RESCORE_ERROR_PREFIX, RESCORE_NO_RESULTS, RESCORE_OK, RESCORE_SKIP_PREFIX, RUN_NOT_IN_ARCHIVE, STATUS_FAILED, STATUS_NOT_RUN, STATUS_SKIPPED, STEP_BACKFILL, STEP_INDEXES, STEP_RESCORE, WRAP_BUNDLE_READY, WRAP_ERROR_PREFIX, WRAP_FROZEN_PREFIX, LegResult, Target, exception_code, ) _RUN_JSON = "run.json" _LOG = logging.getLogger(__name__) # detail 키 `index_warnings`·`index_removed`·`exception_at`(리뷰 지적 2·4·5)는 코드 모양 문자열이라 이 모듈 최상위 상수로 두지 # 않는다(`test_types_home` — 코드 문자열은 `types.py` 한 곳). 쓰는 자리에 한 번씩만 적었다 — l6a-verify 가 `types.py` 로 옮긴다 # (계획 §2.5 구현 시 변경 메모). @dataclass(frozen=True) class _Backfilled: """백필 결과 — `entry` 는 보고서 `run_entry`(없으면 run 이 없거나 case 오류), `failures` 는 순서대로의 실패 코드.""" entry: Mapping[str, Any] | None run_id: str | None = None bundle_id: str | None = None failures: tuple[str, ...] = () @property def ready(self) -> bool: return self.entry is not None and self.entry.get("wrap") in WRAP_BUNDLE_READY @dataclass class _Steps: """다리 안 단계들의 결과 — 첫 실패와 그 hint 를 모은다.""" detail: dict[str, Any] = field(default_factory=dict) failures: list[str] = field(default_factory=list) hint: str | None = None def fail(self, code: str, hint: str | None = None) -> None: if not self.failures: self.hint = hint self.failures.append(code) def result(self) -> LegResult: if self.failures: return LegResult.failed(self.failures[0], self.hint, self.detail) return LegResult.ok(self.detail) def contain(self, step: str, exc: Exception) -> str: """단계 예외 → 코드(타입 이름만). 위치 좌표는 detail 에, 트레이스백은 로거로(모듈 설명 · 리뷰 지적 5).""" code = exception_code(step, exc) where = exception_location(exc) if where is not None: self.detail.setdefault("exception_at", {})[step] = where level = logging.WARNING if optin.hook_debug_requested() else logging.DEBUG _LOG.log(level, "Experiment Hub 훅 번들 다리 단계 예외 봉쇄 — %s", code, exc_info=exc) return code def exception_location(exc: BaseException) -> str | None: """가장 안쪽 프레임의 `<파일 basename>:<줄>:<함수>` — 메시지·locals 는 싣지 않는다(고객 데이터가 없는 코드 좌표만).""" frames = traceback.extract_tb(exc.__traceback__) if not frames: return None last = frames[-1] return f"{Path(last.filename).name}:{last.lineno}:{last.name}" def run_bundle_leg(target: Target, run_dir: Path, run_id: str) -> LegResult: """run 하나의 백필 → 재채점 → 색인(§2.5). 백필 예외는 hook 이 `bundle_exception:` 으로 강등한다.""" backfilled = _backfill(target, run_id) if backfilled.entry is None: return LegResult.failed(backfilled.failures[0]) steps = _Steps({STEP_BACKFILL: dict(backfilled.entry)}) for code in backfilled.failures: steps.fail(code) if backfilled.ready: _rescore_step(target, Path(run_dir), backfilled, steps) else: steps.detail[STEP_RESCORE] = {"status": STATUS_NOT_RUN, "code": NO_BUNDLE} _indexes_step(target, steps) return steps.result() def ensure_run_bundle(target: Target, run_id: str) -> tuple[LegResult, Path | None]: """백필 부분만(L6b `runs eval` 새 경로 ①) — 채택된 미러 run 번들 경로를 함께 돌려준다. 번들이 없으면 None. **전제: 호출자가 `lock.case_lock(target.account, target.case)` 를 쥔 채 부른다**(계획 §2.12 B4 "new_path (case 잠금 안)" · 리뷰 지적 6) — 백필은 미러·번들 색인 사이드카·eval-wrap 을 쓰므로 같은 case 의 훅과 겹치면 안 된다. 여기서 잠그지 않는 까닭: L6b 는 ①~⑤(번들 확인·채점·발행·hub·상태 파일)를 한 잠금 안에서 돈다 — `flock` 은 같은 프로세스라도 따로 연 기술자끼리 막으므로 안에서 다시 잡으면 자기 자신을 기다리다 한도에 걸린다. 판정 집합은 `run_bundle_leg` 와 같다(`WRAP_BUNDLE_READY`) — 훅에서 통과한 run 이 여기서 실패하지 않게(검토 F12). eval-wrap·번들 색인 실패는 `run_bundle_leg` 처럼 실패로 싣되 경로는 돌려준다(번들은 있다). """ backfilled = _backfill(target, run_id) if backfilled.entry is None: return LegResult.failed(backfilled.failures[0]), None detail = {STEP_BACKFILL: dict(backfilled.entry)} path = _mirror_bundle_path(target, backfilled.bundle_id) if backfilled.ready else None if backfilled.failures: return LegResult.failed(backfilled.failures[0], detail=detail), path return LegResult.ok(detail), path # ── 백필 ───────────────────────────────────────────────────────────────── def _backfill(target: Target, run_id: str) -> _Backfilled: """`backfill_case` 를 run 하나로. 충돌 검사는 PB 가 case 의 run 디렉토리 전부로 한다.""" from poc_bundle.backfill.report import run_entry from poc_bundle.backfill.runner import BackfillError, BackfillOptions, backfill_case from poc_bundle.home import blob_mirror_root, hub_index_root opts = BackfillOptions( case=target.case_ref, root=target.projects_dir, mirror_root=blob_mirror_root(), index_root=hub_index_root(), repo_root=target.repo_root, run_ids=frozenset({run_id}), ) try: report = backfill_case(opts, target.context) except BackfillError: return _Backfilled(None, failures=(MIRROR_UNADOPTABLE,)) if not report.runs: return _Backfilled(None, failures=(RUN_NOT_IN_ARCHIVE,)) if len(report.runs) != 1: raise RuntimeError(f"backfill returned {len(report.runs)} runs for one run directory") run = report.runs[0] return _Backfilled(run_entry(run), run.run_id, run.bundle_id, _backfill_failures(run)) def _backfill_failures(run: Any) -> tuple[str, ...]: """`RunReport` 부류 → 번들 다리 실패 코드(순서: 어댑터·wrap → 번들 색인 → eval-wrap).""" failures: list[str] = [] wrap_failure = _wrap_failure(run.adapter, run.wrap) if wrap_failure is not None: failures.append(wrap_failure) if isinstance(run.index, str) and run.index.startswith(WRAP_ERROR_PREFIX): failures.append(f"{BUNDLE_INDEX_FAILED_PREFIX}{run.index.removeprefix(WRAP_ERROR_PREFIX)}") if isinstance(run.eval_wrap, str) and run.eval_wrap.startswith(WRAP_ERROR_PREFIX): detail = run.error_code or run.eval_wrap.removeprefix(WRAP_ERROR_PREFIX) failures.append(f"{EVAL_WRAP_FAILED_PREFIX}{detail}") return tuple(failures) def _wrap_failure(adapter: str | None, wrap: str | None) -> str | None: """wrap 이 번들을 남기지 못했으면 그 코드. 어댑터가 막아 wrap 에 닿지 않았으면 어댑터 부류로.""" if wrap in WRAP_BUNDLE_READY: return None if isinstance(wrap, str) and wrap.startswith(WRAP_FROZEN_PREFIX): return f"{BUNDLE_FROZEN_PREFIX}{wrap.removeprefix(WRAP_FROZEN_PREFIX)}" stage = wrap if isinstance(wrap, str) else adapter if isinstance(stage, str) and stage.startswith(WRAP_ERROR_PREFIX): return f"{BUNDLE_ERROR_PREFIX}{stage.removeprefix(WRAP_ERROR_PREFIX)}" return f"{BUNDLE_ERROR_PREFIX}{stage or 'none'}" def _mirror_bundle_path(t: Target, bundle_id: str | None) -> Path | None: """미러의 `accounts///eval/bundles/`(있을 때만).""" from solar_eval.rescore.paths import BUNDLES_AREA, mirror_area_dir if not bundle_id: return None path = mirror_area_dir(None, t.account, t.case, BUNDLES_AREA) / bundle_id return path if path.is_dir() else None # ── 재채점 ─────────────────────────────────────────────────────────────── def _rescore_step(t: Target, run_dir: Path, backfilled: _Backfilled, steps: _Steps) -> None: try: if not is_proofread_family(run_dir): steps.detail[STEP_RESCORE] = {"status": STATUS_SKIPPED, "code": NOT_PROOFREAD_FAMILY} return status, code, bundle_id = _rescore(t, backfilled.run_id or run_dir.name) except Exception as exc: # 단계 경계 — 백필이 만든 번들로 hub 다리는 계속 간다(모듈 설명) status, code, bundle_id = STATUS_FAILED, steps.contain(STEP_RESCORE, exc), None entry: dict[str, Any] = {"status": status} if code is not None: entry["code"] = code if bundle_id is not None: entry["bundle_id"] = bundle_id steps.detail[STEP_RESCORE] = entry if status == STATUS_FAILED and code is not None: steps.fail(code) def is_proofread_family(run_dir: Path) -> bool: """재채점 대상인가(D-L6-8). 스냅샷 평가기 type 이 있으면 그것, 없으면 run 디렉토리 평가 파일의 계열(검토 F18). run.json·평가 파일을 못 읽으면 계열을 모르므로 대상이 아니다(`not_proofread_family` — wrap 이 그 run 을 이미 가른다). """ from poc_bundle.canonical import load_json_strict from poc_bundle.legacy_run import ( FAMILY_LCS, LegacyRunError, evaluator_family, read_eval_files, split_rounds, ) try: run_json = load_json_strict((Path(run_dir) / _RUN_JSON).read_bytes(), safe_integers=False) except (OSError, ValueError, RecursionError): return False if not isinstance(run_json, dict): return False kind = target.snapshot_evaluator_type(run_json) if kind is not None: return kind == PROOFREAD_EVALUATOR_TYPE try: evaluation, lines = read_eval_files(Path(run_dir)) except LegacyRunError: return False return evaluator_family(run_json, evaluation, split_rounds(evaluation, lines)) == FAMILY_LCS def _rescore(t: Target, run_id: str) -> tuple[str, str | None, str | None]: """`rescore_case(run_ids={run_id})` → (상태, 코드, 채점 번들 id). 상태는 `written|exists`(ok) 또는 `failed`.""" from poc_bundle.home import blob_mirror_root from solar_eval.rescore.case import rescore_case summary = rescore_case( t.account, t.case, mirror_root=blob_mirror_root(), repo_root=t.repo_root, run_ids=frozenset({run_id}), ) if summary.failures: return STATUS_FAILED, f"{RESCORE_ERROR_PREFIX}{summary.failures[0].code}", None if len(summary.outcomes) != 1: return STATUS_FAILED, RESCORE_EMPTY, None outcome = summary.outcomes[0] if outcome.status in RESCORE_OK: bundle_id = None if outcome.path is None else Path(outcome.path).name return outcome.status, None, bundle_id if outcome.code == RESCORE_NO_RESULTS: return STATUS_FAILED, RESCORE_EMPTY, None return STATUS_FAILED, f"{RESCORE_SKIP_PREFIX}{outcome.code}", None # ── 색인 ───────────────────────────────────────────────────────────────── def _indexes_step(t: Target, steps: _Steps) -> None: try: outcome = indexes.refresh(t) except Exception as exc: # 단계 경계 — 색인은 case 파생물이라 run 번들·hub 다리를 막지 않는다 code = steps.contain(STEP_INDEXES, exc) steps.detail[STEP_INDEXES] = f"{STATUS_FAILED}:{code}" steps.fail(code) return steps.detail[STEP_INDEXES] = outcome.code if outcome.warnings: steps.detail["index_warnings"] = len(outcome.warnings) if outcome.removed: steps.detail["index_removed"] = list(outcome.removed) if outcome.failed: steps.fail(outcome.code.removeprefix(f"{STATUS_FAILED}:"), outcome.reason) __all__ = ["ensure_run_bundle", "is_proofread_family", "run_bundle_leg"]