회기 연속성과 멀티 케이스 계약을 영속화

apps/api/app/session_evaluation_timeout.py

@@ -0,0 +1,58 @@
+"""deep-loop 평가의 실행 deadline과 HTTP transport deadline 계약."""
+
+from __future__ import annotations
+
+from .config import settings
+
+# 게이트웨이의 모델 생성 deadline 뒤에도 세션 초기화·요청 직렬화·응답 수신이 남는다.
+# 짧은 운영자 override는 빠르게 취소할 수 있도록 5초부터, 기본 300초에서는 30초까지만 준다.
+SESSION_EVALUATION_TRANSPORT_GRACE_MIN_SECONDS = 5.0
+SESSION_EVALUATION_TRANSPORT_GRACE_MAX_SECONDS = 30.0
+SESSION_EVALUATION_TRANSPORT_GRACE_RATIO = 0.10
+SESSION_EVALUATION_OUTER_GRACE_SECONDS = 5.0
+SESSION_EVALUATION_STALE_STABILITY_SECONDS = 5.0
+
+
+def session_evaluation_timeout_seconds() -> float:
+    """평가 엔진이 생성에 쓸 수 있는 의미상 deadline."""
+    configured = float(settings.session_evaluation_timeout or settings.engine_timeout)
+    return max(configured, 1.0)
+
+
+def session_evaluation_transport_timeout_seconds() -> float:
+    """HTTP 호출이 gateway의 생성 deadline보다 먼저 취소되지 않는 경계."""
+    generation_timeout = session_evaluation_timeout_seconds()
+    grace = min(
+        SESSION_EVALUATION_TRANSPORT_GRACE_MAX_SECONDS,
+        max(
+            SESSION_EVALUATION_TRANSPORT_GRACE_MIN_SECONDS,
+            generation_timeout * SESSION_EVALUATION_TRANSPORT_GRACE_RATIO,
+        ),
+    )
+    return generation_timeout + grace
+
+
+def session_evaluation_outer_timeout_seconds() -> float:
+    """background task가 생성 뒤 감사 원장 기록까지 기다리는 최종 deadline.
+
+    ``evaluate_session()``은 engine transport가 끝난 뒤에도 audit hook을 await한다.
+    그 hook은 durable DB에서는 ``db_command_timeout``까지 걸릴 수 있으므로,
+    transport grace만 더한 outer deadline으로 감싸면 정상 모델 결과를 timeout error로
+    잘못 저장할 수 있다. 결과 평가 원장 저장은 이 await 바깥에서 한 번 더 일어나며,
+    stale deadline이 그 별도 예산을 보유한다.
+    """
+    audit_persistence_timeout = max(float(settings.db_command_timeout), 1.0)
+    return (
+        session_evaluation_transport_timeout_seconds()
+        + audit_persistence_timeout
+        + SESSION_EVALUATION_OUTER_GRACE_SECONDS
+    )
+
+
+def session_evaluation_stale_after_seconds() -> float:
+    """실제 평가 task와 DB 저장이 모두 끝난 뒤에만 누락으로 판정하는 시점."""
+    return (
+        session_evaluation_outer_timeout_seconds()
+        + max(float(settings.db_command_timeout), 1.0)
+        + SESSION_EVALUATION_STALE_STABILITY_SECONDS
+    )