loopx 0.4.8__py3-none-any.whl

loopx/control_plane/turn_driver/loop_controller.py

@@ -0,0 +1,669 @@
+"""Pure Turn Loop Controller transition contract.
+
+This module decides the next disposition of a governed loop from one validated
+Turn receipt plus a fresh quota/scheduler decision. It is a pure function: it
+never invokes a model, sleeps, mutates a host scheduler, writes state, or
+spends quota. `loopx turn run-once` remains the only delivery transaction;
+scheduler process management, host wake APIs, and operator presentation belong
+to later adapters (see the Turn Loop Controller plan in CONTRIBUTOR_TASKS).
+
+The transition output space is exactly six dispositions:
+``run_now | wait | user_action_required | repair | replan | terminal``.
+
+Input validity is enforced at the typed-input boundary, not encoded as a
+seventh disposition. ``decide_loop_disposition`` raises ``ValueError`` when a
+receipt, envelope, or budget cannot be proven against the shared Turn
+contracts, so the caller is responsible for feeding only validated, fresh
+inputs.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from enum import Enum
+from typing import Any
+
+from ..effect_program import SettlementStepKind
+from .driver import LoopXTurnRoute, _typed_route, selected_turn_todo
+from .transaction import (
+    LOOPX_TURN_EXECUTION_SCHEMA_VERSION,
+    LOOPX_TURN_RECEIPT_VALIDATION_SCHEMA_VERSION,
+    LoopXTurnResultKind,
+    require_loopx_turn_completion_outcome,
+)
+
+LOOP_CONTROLLER_DISPOSITION_SCHEMA_VERSION = "loop_turn_loop_disposition_v0"
+BOUNDED_TURN_BUDGET_SCHEMA_VERSION = "loop_bounded_turn_budget_v0"
+VALIDATED_TURN_RECEIPT_SCHEMA_VERSION = "loop_validated_turn_receipt_v0"
+
+# Material result kinds that prove a durable delivery effect and may therefore
+# drive a terminal or progress transition. They require a fully committed
+# transaction (all seven phases), not a validation-only intermediate.
+_MATERIAL_PROGRESS_KINDS = {
+    LoopXTurnResultKind.VALIDATED_COMPLETION,
+    LoopXTurnResultKind.VALIDATED_PROGRESS,
+}
+_MATERIAL_RECEIPT_ORDER = (
+    SettlementStepKind.VALIDATION.value,
+    SettlementStepKind.DURABLE_WRITEBACK.value,
+    SettlementStepKind.QUOTA_SPEND.value,
+)
+
+
+class LoopDisposition(str, Enum):
+    RUN_NOW = "run_now"
+    WAIT = "wait"
+    USER_ACTION_REQUIRED = "user_action_required"
+    REPAIR = "repair"
+    REPLAN = "replan"
+    TERMINAL = "terminal"
+
+
+def _mapping(value: Any) -> dict[str, Any]:
+    return dict(value) if isinstance(value, Mapping) else {}
+
+
+def _disposition(
+    disposition: LoopDisposition,
+    *,
+    reason: str,
+    lineage: Mapping[str, str] | None = None,
+    extra: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "schema_version": LOOP_CONTROLLER_DISPOSITION_SCHEMA_VERSION,
+        "disposition": disposition.value,
+        "reason": reason,
+        "spends_quota": False,
+        "launches_host": False,
+        "writes_state": False,
+    }
+    if lineage:
+        payload["lineage"] = dict(lineage)
+    if extra:
+        payload.update(dict(extra))
+    return payload
+
+
+def _decision_lineage(decision: Mapping[str, Any]) -> dict[str, str]:
+    selected_todo = selected_turn_todo(decision)
+    return {
+        "goal_id": str(decision.get("goal_id") or ""),
+        "agent_id": str(decision.get("agent_id") or ""),
+        "todo_id": str(selected_todo.get("todo_id") or ""),
+    }
+
+
+def _envelope_route(decision: Mapping[str, Any]) -> LoopXTurnRoute:
+    """Return the shared typed route for a fresh quota/scheduler decision.
+
+    Reuses the Turn plan driver's ``_typed_route`` contract, which requires a
+    matching action signature with non-empty equal hashes and an in-budget
+    compaction. A projected user action outranks delivery, so it is resolved
+    before the typed delivery route. Raises ``ValueError`` when the envelope
+    fails the shared contract instead of accepting a forged or truncated
+    decision.
+    """
+
+    route = _typed_route(decision)
+    if route is LoopXTurnRoute.CONTRACT_ERROR:
+        raise ValueError(
+            "quota decision failed the shared envelope contract "
+            "(schema, signature hashes, or compaction budget)"
+        )
+    user = _mapping(decision.get("user"))
+    if user.get("action_required") is True:
+        return LoopXTurnRoute.USER_ACTION_REQUIRED
+    return route
+
+
+def _route_to_disposition(route: LoopXTurnRoute) -> LoopDisposition:
+    return {
+        LoopXTurnRoute.READY_FOR_HOST: LoopDisposition.RUN_NOW,
+        LoopXTurnRoute.REPLAN_REQUIRED: LoopDisposition.REPLAN,
+        LoopXTurnRoute.REPAIR_REQUIRED: LoopDisposition.REPAIR,
+        LoopXTurnRoute.USER_ACTION_REQUIRED: LoopDisposition.USER_ACTION_REQUIRED,
+        LoopXTurnRoute.WAIT: LoopDisposition.WAIT,
+        LoopXTurnRoute.BLOCKED: LoopDisposition.WAIT,
+    }[route]
+
+
+class ValidatedTurnReceipt:
+    """A controller view qualified from one complete Turn execution.
+
+    Material results are admitted only when the public execution proves the
+    M7 typed settlement receipt sequence, one stable effect identity, durable
+    writeback and spend, and a completed scheduler handoff. Todo completion
+    additionally retains its durable continuation outcome so a local Todo
+    completion cannot be confused with Goal terminal closure.
+    """
+
+    __slots__ = (
+        "lineage",
+        "result_kind",
+        "settlement_effect_id",
+        "status",
+        "todo_completion",
+        "turn_key",
+    )
+
+    def __init__(
+        self,
+        *,
+        result_kind: LoopXTurnResultKind,
+        status: str,
+        lineage: Mapping[str, str],
+        turn_key: str | None,
+        settlement_effect_id: str | None = None,
+        todo_completion: Mapping[str, Any] | None = None,
+    ) -> None:
+        self.result_kind = result_kind
+        self.status = status
+        self.lineage = {
+            "goal_id": str(lineage.get("goal_id") or ""),
+            "agent_id": str(lineage.get("agent_id") or ""),
+            "todo_id": str(lineage.get("todo_id") or ""),
+        }
+        self.turn_key = turn_key
+        self.settlement_effect_id = settlement_effect_id
+        self.todo_completion = dict(todo_completion or {}) or None
+
+    @classmethod
+    def from_execution(
+        cls, execution_payload: Mapping[str, Any]
+    ) -> ValidatedTurnReceipt:
+        execution = _mapping(execution_payload)
+        if execution.get("schema_version") != LOOPX_TURN_EXECUTION_SCHEMA_VERSION:
+            raise ValueError(
+                "validated turn receipt requires schema_version="
+                f"{LOOPX_TURN_EXECUTION_SCHEMA_VERSION}"
+            )
+        receipt = _mapping(execution.get("receipt"))
+        if receipt.get("schema_version") != LOOPX_TURN_RECEIPT_VALIDATION_SCHEMA_VERSION:
+            raise ValueError(
+                "validated turn receipt requires schema_version="
+                f"{LOOPX_TURN_RECEIPT_VALIDATION_SCHEMA_VERSION}"
+            )
+        if receipt.get("ok") is not True:
+            raise ValueError("validated turn receipt requires ok=true")
+        raw_kind = receipt.get("result_kind")
+        try:
+            result_kind = LoopXTurnResultKind(str(raw_kind or ""))
+        except ValueError:
+            raise ValueError(
+                f"validated turn receipt has unsupported result_kind {raw_kind!r}"
+            ) from None
+        if execution.get("result_kind") != result_kind.value:
+            raise ValueError("execution result_kind does not match its receipt")
+        status = str(receipt.get("status") or "")
+        if result_kind in _MATERIAL_PROGRESS_KINDS and (
+            status != "committed" or execution.get("status") != "committed"
+        ):
+            raise ValueError(
+                f"material result {result_kind.value} requires a fully committed "
+                "Turn execution and receipt"
+            )
+        lineage = _mapping(receipt.get("lineage"))
+        if not all(lineage.get(k) for k in ("goal_id", "agent_id", "todo_id")):
+            raise ValueError(
+                "validated turn receipt is missing goal/agent/todo lineage"
+            )
+        turn_key = str(receipt.get("turn_key") or "") or None
+        if not turn_key:
+            raise ValueError("validated turn receipt is missing turn_key")
+        settlement_effect_id = str(receipt.get("settlement_effect_id") or "") or None
+        todo_completion = _mapping(execution.get("todo_completion"))
+        if result_kind in _MATERIAL_PROGRESS_KINDS:
+            settlement_effect_id = _qualified_material_effect_id(
+                execution,
+                expected_effect_id=settlement_effect_id,
+            )
+        if result_kind is LoopXTurnResultKind.VALIDATED_COMPLETION:
+            todo_completion = require_loopx_turn_completion_outcome(
+                todo_completion,
+                expected_todo_id=str(lineage["todo_id"]),
+            )
+        return cls(
+            result_kind=result_kind,
+            status=status,
+            lineage=lineage,
+            turn_key=turn_key,
+            settlement_effect_id=settlement_effect_id,
+            todo_completion=todo_completion,
+        )
+
+    def to_mapping(self) -> dict[str, Any]:
+        return {
+            "schema_version": VALIDATED_TURN_RECEIPT_SCHEMA_VERSION,
+            "result_kind": self.result_kind.value,
+            "status": self.status,
+            "lineage": dict(self.lineage),
+            "turn_key": self.turn_key,
+            "settlement_effect_id": self.settlement_effect_id,
+            **(
+                {"todo_completion": dict(self.todo_completion)}
+                if self.todo_completion
+                else {}
+            ),
+        }
+
+
+def _qualified_material_effect_id(
+    execution: Mapping[str, Any],
+    *,
+    expected_effect_id: str | None,
+) -> str:
+    settlement = _mapping(execution.get("settlement_result"))
+    if settlement.get("ok") is not True or settlement.get("failure") is not None:
+        raise ValueError("material Turn execution requires a successful settlement")
+    raw_receipts = settlement.get("receipts")
+    if not isinstance(raw_receipts, list):
+        raise TypeError("material Turn execution is missing settlement receipts")
+    receipts = [_mapping(item) for item in raw_receipts]
+    if [str(item.get("step_kind") or "") for item in receipts] != list(
+        _MATERIAL_RECEIPT_ORDER
+    ):
+        raise ValueError(
+            "material Turn execution requires ordered validation/writeback/spend receipts"
+        )
+    effect_ids = {str(item.get("effect_id") or "") for item in receipts}
+    if "" in effect_ids or len(effect_ids) != 1:
+        raise ValueError("material Turn settlement receipts must share one effect identity")
+    effect_id = next(iter(effect_ids))
+    if not expected_effect_id or expected_effect_id != effect_id:
+        raise ValueError(
+            "material Turn settlement identity does not match the transaction receipt"
+        )
+    if any(item.get("status") != "committed" for item in receipts):
+        raise ValueError("material Turn settlement receipts must be committed")
+    effects = _mapping(execution.get("effects"))
+    if effects.get("state_written") is not True or effects.get("quota_spent") is not True:
+        raise ValueError("material Turn execution is missing durable effect evidence")
+    scheduler = _mapping(execution.get("scheduler"))
+    if scheduler.get("completed") is not True:
+        raise ValueError("material Turn execution is missing completed scheduler handoff")
+    return effect_id
+
+
+class BoundedTurnBudget:
+    """A provider-neutral bounded Turn budget tied to one lineage.
+
+    Construction enforces strict integer domains (booleans are rejected) and a
+    sane range, so the transition never guesses an unbounded continuation.
+    """
+
+    __slots__ = ("completed_turns", "lineage", "max_turns")
+
+    def __init__(
+        self,
+        *,
+        lineage: Mapping[str, str],
+        max_turns: int,
+        completed_turns: int,
+    ) -> None:
+        if type(max_turns) is not int:
+            raise ValueError("bounded turn budget max_turns must be an int")
+        if type(completed_turns) is not int:
+            raise ValueError("bounded turn budget completed_turns must be an int")
+        if max_turns <= 0:
+            raise ValueError("bounded turn budget max_turns must be > 0")
+        if completed_turns < 0:
+            raise ValueError("bounded turn budget completed_turns must be >= 0")
+        if completed_turns > max_turns:
+            raise ValueError(
+                "bounded turn budget completed_turns must be <= max_turns"
+            )
+        self.lineage = {
+            "goal_id": str(lineage.get("goal_id") or ""),
+            "agent_id": str(lineage.get("agent_id") or ""),
+            "todo_id": str(lineage.get("todo_id") or ""),
+        }
+        if not all(self.lineage.values()):
+            raise ValueError("bounded turn budget is missing goal/agent/todo lineage")
+        self.max_turns = max_turns
+        self.completed_turns = completed_turns
+
+    def to_mapping(self) -> dict[str, Any]:
+        return {
+            "schema_version": BOUNDED_TURN_BUDGET_SCHEMA_VERSION,
+            "lineage": dict(self.lineage),
+            "max_turns": self.max_turns,
+            "completed_turns": self.completed_turns,
+        }
+
+    @property
+    def remaining(self) -> int:
+        return self.max_turns - self.completed_turns
+
+
+def _assert_goal_agent_match(
+    *,
+    receipt_lineage: Mapping[str, str],
+    decision_lineage: Mapping[str, str],
+) -> None:
+    for key in ("goal_id", "agent_id"):
+        if receipt_lineage.get(key) != decision_lineage.get(key):
+            raise ValueError(
+                "stale_receipt: receipt lineage does not match the fresh decision "
+                f"on {key} (receipt={receipt_lineage.get(key)!r}, "
+                f"decision={decision_lineage.get(key)!r})"
+            )
+
+
+def _assert_same_todo(
+    *,
+    receipt_lineage: Mapping[str, str],
+    decision_lineage: Mapping[str, str],
+) -> None:
+    if receipt_lineage.get("todo_id") != decision_lineage.get("todo_id"):
+        raise ValueError(
+            "stale_receipt: receipt Todo does not match the fresh decision "
+            f"(receipt={receipt_lineage.get('todo_id')!r}, "
+            f"decision={decision_lineage.get('todo_id')!r})"
+        )
+
+
+def _assert_budget_lineage_match(
+    *,
+    budget_lineage: Mapping[str, str],
+    decision_lineage: Mapping[str, str],
+) -> None:
+    for key in ("goal_id", "agent_id", "todo_id"):
+        if budget_lineage.get(key) != decision_lineage.get(key):
+            raise ValueError(
+                "stale_budget: budget lineage does not match the fresh decision "
+                f"on {key} (budget={budget_lineage.get(key)!r}, "
+                f"decision={decision_lineage.get(key)!r})"
+            )
+
+
+def _assert_predecessor_binding(
+    *,
+    receipt: ValidatedTurnReceipt,
+    predecessor_turn_key: str | None,
+) -> None:
+    """Prove the fresh envelope causally succeeds the receipt.
+
+    The outer adapter must bind the fresh decision to the receipt's
+    ``turn_key``. The causal assertion stays beside the envelope instead of
+    adding an unsigned field to ``loopx_turn_envelope_v0``.
+    """
+
+    predecessor = str(predecessor_turn_key or "")
+    if not predecessor:
+        raise ValueError(
+            "stale_receipt: continuation is missing predecessor_turn_key; "
+            "cannot prove causal succession from the receipt"
+        )
+    if predecessor != receipt.turn_key:
+        raise ValueError(
+            "stale_receipt: fresh decision predecessor_turn_key "
+            f"({predecessor!r}) does not match the receipt turn_key "
+            f"({receipt.turn_key!r})"
+        )
+
+
+def _completion_disposition(
+    *,
+    receipt: ValidatedTurnReceipt,
+    decision: Mapping[str, Any],
+    decision_lineage: Mapping[str, str],
+    route: LoopXTurnRoute,
+) -> dict[str, Any]:
+    completion = dict(receipt.todo_completion or {})
+    continuation = str(completion.get("continuation") or "")
+    if continuation == "no_followup":
+        if (
+            decision.get("effective_action") != "terminal_no_followup"
+            or decision.get("state") != "terminal_no_followup"
+        ):
+            raise ValueError(
+                "no_followup completion requires fresh terminal Goal frontier evidence"
+            )
+        return _disposition(
+            LoopDisposition.TERMINAL,
+            reason="durable no-follow-up and fresh Goal frontier prove terminal closure",
+            lineage=receipt.lineage,
+        )
+
+    selected_todo_id = str(decision_lineage.get("todo_id") or "")
+    if not selected_todo_id:
+        raise ValueError("Todo completion continuation requires a fresh selected Todo")
+    if continuation == "successor":
+        successor_ids = completion.get("successor_todo_ids")
+        if not isinstance(successor_ids, list) or selected_todo_id not in successor_ids:
+            raise ValueError(
+                "stale_receipt: fresh decision is not a declared completion successor"
+            )
+    elif continuation == "active_goal" and selected_todo_id == receipt.lineage["todo_id"]:
+        raise ValueError(
+            "stale_receipt: active Goal continuation reselected the completed Todo"
+        )
+
+    if route is LoopXTurnRoute.USER_ACTION_REQUIRED:
+        return _disposition(
+            LoopDisposition.USER_ACTION_REQUIRED,
+            reason="fresh decision projects a concrete user action after Todo completion",
+            lineage=decision_lineage,
+        )
+    disposition = _route_to_disposition(route)
+    if disposition is LoopDisposition.REPLAN:
+        return _replan_disposition(
+            reason="fresh decision requires replan after Todo completion",
+            decision_lineage=decision_lineage,
+        )
+    return _disposition(
+        disposition,
+        reason=(
+            "durable Todo completion continues through its declared successor"
+            if continuation == "successor"
+            else "durable Todo completion continues through the fresh Goal frontier"
+        ),
+        lineage=decision_lineage,
+    )
+
+
+def decide_loop_disposition(
+    *,
+    turn_receipt: ValidatedTurnReceipt | None,
+    quota_decision: Mapping[str, Any],
+    predecessor_turn_key: str | None = None,
+    bounded_turn_budget: BoundedTurnBudget | None = None,
+) -> dict[str, Any]:
+    """Decide the next loop disposition from one validated receipt and a fresh decision.
+
+    ``turn_receipt`` is a :class:`ValidatedTurnReceipt` (or ``None`` when no
+    prior Turn has committed). ``quota_decision`` is a fresh
+    ``loopx_turn_envelope_v0``. The outer adapter supplies a separate
+    ``predecessor_turn_key`` matching the receipt when one is present; this
+    keeps causal continuation out of the signed quota envelope schema.
+    ``bounded_turn_budget`` is required for ``validated_progress``.
+
+    The function is pure: it launches no host, writes no state, and spends no
+    quota. Invalid or stale input raises ``ValueError`` at the typed-input
+    boundary; the transition output space is always one of the six
+    :class:`LoopDisposition` values.
+    """
+
+    route = _envelope_route(quota_decision)
+    decision_lineage = _decision_lineage(quota_decision)
+    if not decision_lineage["goal_id"] or not decision_lineage["agent_id"]:
+        raise ValueError(
+            "fresh quota decision is missing goal/agent lineage"
+        )
+
+    if turn_receipt is None:
+        if str(quota_decision.get("effective_action") or "") == "terminal_no_followup":
+            if quota_decision.get("state") != "terminal_no_followup":
+                raise ValueError(
+                    "terminal no-follow-up requires fresh Goal frontier state"
+                )
+            return _disposition(
+                LoopDisposition.TERMINAL,
+                reason="fresh Goal frontier proves terminal no-follow-up",
+                lineage=decision_lineage,
+            )
+        disposition = _route_to_disposition(route)
+        if not decision_lineage["todo_id"] and disposition not in {
+            LoopDisposition.WAIT,
+            LoopDisposition.USER_ACTION_REQUIRED,
+        }:
+            raise ValueError("executable quota decision is missing selected Todo lineage")
+        if disposition is LoopDisposition.REPLAN:
+            return _replan_disposition(
+                reason="fresh decision requires replan",
+                decision_lineage=decision_lineage,
+            )
+        return _disposition(
+            disposition,
+            reason=_no_receipt_reason(disposition),
+            lineage=decision_lineage,
+        )
+
+    # Prove the envelope causally succeeds this exact receipt before any
+    # disposition is considered. This closes the stale-replay gap: an old
+    # receipt for the same todo cannot be replayed against a later envelope.
+    _assert_predecessor_binding(
+        receipt=turn_receipt,
+        predecessor_turn_key=predecessor_turn_key,
+    )
+    _assert_goal_agent_match(
+        receipt_lineage=turn_receipt.lineage,
+        decision_lineage=decision_lineage,
+    )
+
+    result_kind = turn_receipt.result_kind
+
+    if result_kind is LoopXTurnResultKind.VALIDATED_COMPLETION:
+        return _completion_disposition(
+            receipt=turn_receipt,
+            decision=quota_decision,
+            decision_lineage=decision_lineage,
+            route=route,
+        )
+
+    effective_lineage = dict(decision_lineage)
+    if decision_lineage["todo_id"]:
+        _assert_same_todo(
+            receipt_lineage=turn_receipt.lineage,
+            decision_lineage=decision_lineage,
+        )
+    elif (
+        result_kind is LoopXTurnResultKind.VALIDATED_PROGRESS
+        and route
+        not in {LoopXTurnRoute.USER_ACTION_REQUIRED, LoopXTurnRoute.WAIT}
+    ):
+        raise ValueError("receipt-backed executable decision is missing selected Todo lineage")
+    else:
+        # A valid user gate or quiet wait may intentionally have no runnable
+        # selected Todo. Preserve the committed predecessor lineage for that
+        # no-spend disposition instead of rejecting the envelope.
+        effective_lineage["todo_id"] = turn_receipt.lineage["todo_id"]
+
+    # Decision user action outranks every non-terminal disposition.
+    if route is LoopXTurnRoute.USER_ACTION_REQUIRED:
+        return _disposition(
+            LoopDisposition.USER_ACTION_REQUIRED,
+            reason="fresh decision projects a concrete user action",
+            lineage=effective_lineage,
+        )
+
+    if result_kind is LoopXTurnResultKind.VALIDATED_PROGRESS:
+        if bounded_turn_budget is None:
+            raise ValueError(
+                "validated progress cannot continue without a proven bounded turn budget"
+            )
+        _assert_budget_lineage_match(
+            budget_lineage=bounded_turn_budget.lineage,
+            decision_lineage=effective_lineage,
+        )
+        if bounded_turn_budget.remaining <= 0:
+            return _replan_disposition(
+                reason="bounded turn budget exhausted; replan before another Turn",
+                decision_lineage=effective_lineage,
+            )
+        disposition = _route_to_disposition(route)
+        if disposition is LoopDisposition.REPLAN:
+            return _replan_disposition(
+                reason="fresh decision requires replan after progress",
+                decision_lineage=effective_lineage,
+            )
+        return _disposition(
+            disposition,
+            reason=_progress_reason(disposition),
+            lineage=effective_lineage,
+        )
+
+    if result_kind is LoopXTurnResultKind.REPLAN_REQUIRED:
+        return _replan_disposition(
+            reason="turn receipt requires replan",
+            decision_lineage=effective_lineage,
+        )
+
+    if result_kind is LoopXTurnResultKind.REPAIR_REQUIRED:
+        return _disposition(
+            LoopDisposition.REPAIR,
+            reason="turn receipt requires repair",
+            lineage=effective_lineage,
+        )
+
+    if result_kind is LoopXTurnResultKind.USER_ACTION_REQUIRED:
+        return _disposition(
+            LoopDisposition.USER_ACTION_REQUIRED,
+            reason="turn receipt projects a concrete user action",
+            lineage=effective_lineage,
+        )
+
+    if result_kind is LoopXTurnResultKind.WAIT:
+        return _disposition(
+            LoopDisposition.WAIT,
+            reason="turn receipt is a typed no-spend wait",
+            lineage=effective_lineage,
+        )
+
+    # host_failure, validation_failed, writeback_failed, quota_spend_failed:
+    # the loop must not guess recovery on its own; hold for repair routing.
+    return _disposition(
+        LoopDisposition.REPAIR,
+        reason=(
+            f"turn receipt ended in {result_kind.value}; "
+            "route to repair before any successor turn"
+        ),
+        lineage=effective_lineage,
+    )
+
+
+def _no_receipt_reason(disposition: LoopDisposition) -> str:
+    return {
+        LoopDisposition.RUN_NOW: "no prior receipt and fresh decision allows delivery",
+        LoopDisposition.WAIT: "fresh decision is a quiet no-spend wait",
+        LoopDisposition.REPAIR: "fresh decision requires repair",
+        LoopDisposition.USER_ACTION_REQUIRED: "fresh decision projects a concrete user action",
+    }[disposition]
+
+
+def _progress_reason(disposition: LoopDisposition) -> str:
+    return {
+        LoopDisposition.RUN_NOW: "validated progress with fresh decision allowing the next turn",
+        LoopDisposition.WAIT: "validated progress but fresh decision does not allow the next turn yet",
+        LoopDisposition.REPAIR: "fresh decision requires repair after progress",
+        LoopDisposition.USER_ACTION_REQUIRED: "fresh decision projects a concrete user action",
+    }[disposition]
+
+
+def _replan_disposition(
+    *, reason: str, decision_lineage: Mapping[str, str]
+) -> dict[str, Any]:
+    return _disposition(
+        LoopDisposition.REPLAN,
+        reason=reason,
+        lineage=decision_lineage,
+        extra={
+            "replan_continuation": {
+                "requires_bounded_delta": True,
+                "delta_kinds": ["todo_delta", "vision_delta"],
+                "stale_todo_rerun_allowed": False,
+                "fresh_envelope_required": True,
+            }
+        },
+    )