"""The terminal result of a batch clarify, shared by every registry that holds one. A batch (``clarify`` server request with question ids) is answered per question with ``clarify.lock`` and ends one of four ways: the last lock, a closing response frame, a timeout, or an interrupt/cancel. Main's TUI sidecar (``tui_gateway/server_requests.py``) and the session owner (``gateway/session_server_requests.py``) both settle batches; each used to compute ``{answers, outcome}`` itself and they drifted. Both call :func:`settle_batch`, so the model is told the same thing on every surface. """ from __future__ import annotations OUTCOMES = ("submitted", "timed_out", "cancelled") def settle_batch(locked: dict, frame_result=None, *, ended: str | None = None) -> dict: """``{answers, outcome}`` for a batch whose locks so far are *locked*. - ``ended`` (``"timed_out"`` / ``"cancelled"``): the wait ended with no frame (timeout, interrupt, a ``cancel()``), or ``"submitted"`` for the last lock. The locked answers stand. - Otherwise *frame_result* is the closing frame's ``result``. A dict with an ``answers`` dict lays those answers over the locks (the frame wins per question) and keeps the frame's own outcome when it names a known one (main's classic CLI reports ``timed_out``), else ``submitted``. Anything else (Ink Esc / Desktop Skip send ``{}``; an error frame gives ``None``) is a cancel-all: locks kept, ``cancelled``. """ if ended is not None: return {"answers": dict(locked), "outcome": ended if ended in OUTCOMES else "cancelled"} if isinstance(frame_result, dict) and isinstance(frame_result.get("answers"), dict): outcome = frame_result.get("outcome") return {**frame_result, "answers": {**locked, **frame_result["answers"]}, "outcome": outcome if outcome in OUTCOMES else "submitted"} return {"answers": dict(locked), "outcome": "cancelled"}