iCode-TUI 0.29.1__py3-none-any.whl

chrys/service/context/compaction/summaries.py

@@ -0,0 +1,319 @@
+# Copyright (c) Microsoft. All rights reserved.
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+# Contains code adapted from Microsoft Agent Framework (MIT License; see NOTICE).
+
+"""Compaction summary rendering and summary annotations."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from chrys.foundation.trajectory.ids import new_analytics_id
+from chrys.foundation.trajectory.metadata import ensure_analytics_item_id, read_analytics_item_id
+from chrys.kernel import (
+    EXCLUDED_KEY,
+    GROUP_ANNOTATION_KEY,
+    SUMMARIZED_BY_SUMMARY_ID_KEY,
+    SUMMARY_OF_GROUP_IDS_KEY,
+    SUMMARY_OF_MESSAGE_IDS_KEY,
+    TOOL_CALL_CONTENT_TYPES,
+    TOOL_RESULT_CONTENT_TYPES,
+    Content,
+    Message,
+    annotate_message_groups,
+    annotate_token_counts,
+    set_excluded,
+)
+from chrys.kernel.compaction import _has_reasoning
+from chrys.kernel.exchanges import (
+    EmptyIdPolicy,
+    LiveAccessor,
+    NoneIdPolicy,
+    PairingPolicy,
+    iter_exchanges,
+    pair_results,
+)
+
+from .events import _REASON_COMPACTION, _REASON_REMOVAL, CachedSummary
+from .groups import _group_start_indices, _tool_call_name, _tool_result_text
+
+if TYPE_CHECKING:
+    from chrys.kernel import TokenizerProtocol
+
+    from .exclusions import ExclusionLedger
+
+_log = logging.getLogger(__name__)
+
+
+def _make_summary_message(
+    summary_text: str, summary_id: str, original_ids: list[str], group_id: str, *, item_id: str | None = None
+) -> Message:
+    """Create a compaction summary message."""
+    message = Message(
+        role="assistant",
+        contents=[summary_text],
+        message_id=summary_id,
+        additional_properties={
+            GROUP_ANNOTATION_KEY: {
+                SUMMARY_OF_MESSAGE_IDS_KEY: original_ids,
+                SUMMARY_OF_GROUP_IDS_KEY: [group_id],
+            },
+        },
+    )
+    # The summary replaces the group in every later request, so it needs its
+    # analytics identity now — not at the save that ends the turn.
+    ensure_analytics_item_id(message.additional_properties, item_id=item_id)
+    return message
+
+
+_RESULT_SUMMARY_MAX = 100
+"""Max characters for individual tool result text in compaction summaries."""
+
+_ARGS_SUMMARY_MAX = 200
+"""Max characters for tool call arguments in compaction summaries."""
+
+_SUMMARY_TOTAL_MAX = 4096
+"""Max characters for the complete tool-call compaction summary."""
+
+_SUMMARY_TRUNCATION_MARKER = "... [truncated]"
+
+
+_PAIRING_CONTENT_TYPES = TOOL_CALL_CONTENT_TYPES | TOOL_RESULT_CONTENT_TYPES
+_SUMMARY_REPRESENTABLE_CONTENT_TYPES = frozenset({"text", "text_reasoning", "usage"})
+_SUMMARY_PAIRING_POLICY = PairingPolicy(
+    call_types=TOOL_CALL_CONTENT_TYPES,
+    include_informational_calls=True,
+    result_types=TOOL_RESULT_CONTENT_TYPES,
+    none_id=NoneIdPolicy.POSITIONAL,
+    empty_id=EmptyIdPolicy.POSITIONAL,
+    malformed_id="stringify",
+)
+
+
+def _is_fused_narration(message: Message) -> bool:
+    """Whether the message is a narration member of a fused tool-call group.
+
+    Exchange fusion absorbs non-call assistant siblings between a call and
+    its results into the tool-call group; members carrying no call, result,
+    or reasoning content are wire-legal on their own, outside the group's
+    projection-atomicity set. Reasoning-bearing members are NOT narration:
+    a reasoning item must never outlive its exchange."""
+    return (
+        message.role == "assistant"
+        and not _has_reasoning(message)
+        and not any(content.type in _PAIRING_CONTENT_TYPES for content in message.contents)
+    )
+
+
+def _narration_survives_summary(message: Message) -> bool:
+    """Whether a narration member must stay on the wire when its group is
+    summarized: the text summary cannot represent contents like images, so
+    excluding such a member would silently drop them."""
+    return _is_fused_narration(message) and any(
+        content.type not in _SUMMARY_REPRESENTABLE_CONTENT_TYPES for content in message.contents
+    )
+
+
+def _build_summary(group_msgs: list[Message]) -> str | None:
+    """Build a compact summary preserving call args but trimming results."""
+    paired_calls: dict[tuple[int, int], Content] = {}
+    accessor = LiveAccessor()
+    for exchange in iter_exchanges(group_msgs, accessor):
+        pairing = pair_results(group_msgs, exchange, accessor, _SUMMARY_PAIRING_POLICY)
+        assignments = [assignment for values in pairing.truthy_assignments.values() for assignment in values] + [
+            assignment for values in pairing.falsy_assignments.values() for assignment in values
+        ]
+        for call_occurrence, result_occurrence in assignments:
+            if result_occurrence is None:
+                continue
+            paired_calls[(result_occurrence.message_index, result_occurrence.content_index)] = group_msgs[
+                call_occurrence.message_index
+            ].contents[call_occurrence.content_index]
+
+    # Collect results and absorbed narration with function context, in
+    # transcript order \u2014 a fused group may carry assistant text between a
+    # call and its results, and excluding the group must not drop that text.
+    tool_parts: list[str] = []
+    for message_index, msg in enumerate(group_msgs):
+        for content_index, content in enumerate(msg.contents):
+            if content.type in TOOL_RESULT_CONTENT_TYPES:
+                call = paired_calls.get((message_index, content_index))
+                result_text = _tool_result_text(content) or "completed"
+                if len(result_text) > _RESULT_SUMMARY_MAX:
+                    result_text = f"{result_text[:_RESULT_SUMMARY_MAX]}... ({len(result_text)} chars)"
+                name = _tool_call_name(call) if call is not None else None
+                arguments = _summary_call_arguments(call) if call is not None else None
+                args_str = _format_summary_arguments(arguments)
+                call_str = f"{name}({args_str})" if args_str else name
+                tool_parts.append(f"{call_str or 'tool'} \u2192 {result_text}")
+            elif msg.role == "assistant" and content.type == "text" and content.text and content.text.strip():
+                narration = content.text.strip()
+                if len(narration) > _RESULT_SUMMARY_MAX:
+                    narration = f"{narration[:_RESULT_SUMMARY_MAX]}... ({len(narration)} chars)"
+                tool_parts.append(f'assistant: "{narration}"')
+
+    if not tool_parts:
+        return None
+    summary_label = "; ".join(tool_parts)
+    prefix = "[Tool call: "
+    suffix = "]"
+    summary_text = f"{prefix}{summary_label}{suffix}"
+    if len(summary_text) <= _SUMMARY_TOTAL_MAX:
+        return summary_text
+    allowed_label_chars = _SUMMARY_TOTAL_MAX - len(prefix) - len(suffix) - len(_SUMMARY_TRUNCATION_MARKER)
+    truncated_label = summary_label[:allowed_label_chars].rstrip()
+    return f"{prefix}{truncated_label}{_SUMMARY_TRUNCATION_MARKER}{suffix}"
+
+
+def _summary_call_arguments(content: Content) -> Any:
+    """Return field-aware arguments for every canonical call variant."""
+    if content.type == "code_interpreter_tool_call":
+        code = "".join(item.text or "" for item in content.inputs or [] if item.type == "text")
+        return {"code": code} if code else None
+    if content.type == "image_generation_tool_call":
+        return {"image_id": content.image_id} if content.image_id else None
+    if content.type == "shell_tool_call":
+        arguments: dict[str, Any] = {}
+        if content.commands is not None:
+            arguments["commands"] = content.commands
+        if content.timeout_ms is not None:
+            arguments["timeout_ms"] = content.timeout_ms
+        if content.max_output_length is not None:
+            arguments["max_output_length"] = content.max_output_length
+        return arguments or None
+    return content.arguments
+
+
+def _format_summary_arguments(arguments: Any) -> str:
+    if not arguments:
+        return ""
+    if isinstance(arguments, dict):
+        parts = []
+        for key, value in arguments.items():
+            value_str = f'"{value}"' if isinstance(value, str) else str(value)
+            parts.append(f"{key}={value_str}")
+        args_str = ", ".join(parts)
+    else:
+        args_str = str(arguments)
+    if len(args_str) > _ARGS_SUMMARY_MAX:
+        return f"{args_str[:_ARGS_SUMMARY_MAX]}..."
+    return args_str
+
+
+def _set_summarized(message: Message, summary_id: str) -> None:
+    """Mark a message as summarized by a given summary ID.
+
+    Creates a **new** dict for the ``_group`` annotation to avoid mutating
+    a dict that may be shared with another Message: shallow-copying
+    ``additional_properties`` via ``dict()`` retains nested annotation aliases.
+    """
+    existing: dict[str, Any] = message.additional_properties.get(GROUP_ANNOTATION_KEY, {})
+    annotation = dict(existing) if isinstance(existing, dict) else {}
+    annotation[SUMMARIZED_BY_SUMMARY_ID_KEY] = summary_id
+    message.additional_properties[GROUP_ANNOTATION_KEY] = annotation
+
+
+def _compact_group(
+    messages: list[Message],
+    group_id: str,
+    group_msgs: list[Message],
+    *,
+    ledger: ExclusionLedger,
+    tokenizer: TokenizerProtocol,
+) -> list[str] | None:
+    """Compact one tool-call group and update its ledger cache."""
+    if (
+        not group_msgs
+        or group_id in ledger._removed_group_ids
+        or any(msg.additional_properties.get(EXCLUDED_KEY, False) for msg in group_msgs)
+    ):
+        return None
+
+    kept_ids = {id(msg) for msg in group_msgs if _narration_survives_summary(msg)}
+    replaced_msgs = [msg for msg in group_msgs if id(msg) not in kept_ids]
+
+    summary_text = _build_summary(replaced_msgs)
+    if summary_text is None:
+        return None
+    # Group IDs are positional wire-view labels and may be reused next turn.
+    # The original-to-summary relationship needs its own occurrence identity.
+    item_id = new_analytics_id()
+    summary_id = f"tool_summary_{item_id}"
+    original_ids = [m.message_id for m in replaced_msgs if m.message_id]
+
+    tool_names = [
+        tool_name for msg in replaced_msgs for content in msg.contents if (tool_name := _tool_call_name(content))
+    ]
+
+    # Mark the replaced originals as excluded.  Narration members the text
+    # summary cannot represent (images and other non-text content) stay on
+    # the wire: they are not pairing carriers, so the group still projects
+    # atomically without them.
+    any_changed = False
+    for msg in replaced_msgs:
+        _set_summarized(msg, summary_id)
+        any_changed = set_excluded(msg, excluded=True, reason=_REASON_COMPACTION) or any_changed
+
+    if not any_changed:
+        return None
+
+    summary_message = _make_summary_message(summary_text, summary_id, original_ids, group_id, item_id=item_id)
+    # Cache the occurrence identity too: message_id may be rewritten each pass.
+    ledger._summary_cache[summary_id] = CachedSummary(
+        summary_text=summary_text,
+        original_ids=original_ids,
+        group_id=group_id,
+        item_id=item_id,
+        message=summary_message,
+    )
+
+    starts = _group_start_indices(messages)
+    insertion_index = starts.get(group_id, 0)
+    messages.insert(insertion_index, summary_message)
+
+    annotate_message_groups(messages, from_index=insertion_index, force_reannotate=False)
+    annotate_token_counts(messages, tokenizer=tokenizer, from_index=insertion_index)
+
+    return tool_names
+
+
+def _remove_group(
+    messages: list[Message],
+    group_id: str,
+    group_msgs: list[Message],
+    *,
+    ledger: ExclusionLedger,
+) -> list[str] | None:
+    """Remove one tool-call group and update its ledger state."""
+    if not group_msgs:
+        return None
+
+    tool_names = [
+        tool_name for msg in group_msgs for content in msg.contents if (tool_name := _tool_call_name(content))
+    ]
+
+    any_changed = False
+    for msg in group_msgs:
+        if _is_fused_narration(msg):
+            continue
+        any_changed = set_excluded(msg, excluded=True, reason=_REASON_REMOVAL) or any_changed
+
+    summary_ids: set[str] = set()
+    for msg in group_msgs:
+        annotation = msg.additional_properties.get(GROUP_ANNOTATION_KEY)
+        if isinstance(annotation, dict) and isinstance(sid := annotation.get(SUMMARIZED_BY_SUMMARY_ID_KEY), str):
+            summary_ids.add(sid)
+    for msg in messages:
+        item_id = read_analytics_item_id(msg.additional_properties)
+        if item_id is not None and f"tool_summary_{item_id}" in summary_ids:
+            any_changed = set_excluded(msg, excluded=True, reason=_REASON_REMOVAL) or any_changed
+
+    if not any_changed:
+        return None
+
+    for summary_id in summary_ids:
+        ledger._summary_cache.pop(summary_id, None)
+    ledger._removed_group_ids.add(group_id)
+
+    return tool_names

chrys/service/context/compaction/turns.py

@@ -0,0 +1,375 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Turn resolution over live wire messages and provider state."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from chrys.foundation.models.history_markers import HistoryMarkerKind
+from chrys.foundation.models.turns import opens_turn, turn_slices
+from chrys.kernel import EXCLUDED_KEY, Message
+from chrys.service.context.providers.history import TURN_INDEX_KEY
+
+_log = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Turn resolution (§3.2 of the turn-boundary unification plan)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class TurnSpan:
+    """One resolved turn over the wire list.  Snapshot-scoped indices."""
+
+    start: int
+    """Wire index of the span's first message."""
+
+    end: int
+    """Wire index one past the span's last message."""
+
+    absolute_number: int
+    """State-backed absolute turn number (event cosmetics only)."""
+
+    state_boundary: int | None
+    """Provider-state index of the span's start-boundary message.
+
+    ``None`` when the boundary message is absent from state — for the
+    current span that is the Phase 3 clamp's protect-nothing signal: the
+    input is stored only after the run, and inputs are stored before
+    outputs, so state then holds no current-turn work at all.
+    """
+
+
+@dataclass(frozen=True)
+class ResolvedTurns:
+    """Snapshot-scoped turn resolution over the live wire + provider state.
+
+    Valid only until the next wire/state mutation: Phase 1 inserts summary
+    messages into the wire list and every Phase 3 fold replaces
+    ``state["messages"]`` outright, shifting all later indices.  Re-resolve
+    after a mutation; never cache a result across one.
+    """
+
+    spans: list[TurnSpan]
+    """Real turns, oldest first; the last span is the current turn."""
+
+    degraded: bool
+    """True when the current marker region holds no real opener and the
+    current span was synthesized from the region (§3.2 rule 4)."""
+
+    synthetic_opener_idx: int | None
+    """Wire index of the first user message inside a degraded region (the
+    prompt-visible "opener" is synthetic); ``None`` for an assistant/tool-
+    only degraded region, and always ``None`` in strict mode."""
+
+    region_start: int
+    """Wire index where the current marker region starts."""
+
+    @property
+    def current(self) -> TurnSpan | None:
+        """The current turn's span (the last one), or ``None``."""
+        return self.spans[-1] if self.spans else None
+
+    @property
+    def previous(self) -> list[TurnSpan]:
+        """All completed turns' spans, oldest first."""
+        return self.spans[:-1]
+
+
+def _state_correspondence(messages: list[Message], state_messages: list[Message]) -> dict[int, int]:
+    """Map wire index → provider-state index.
+
+    Membership is by identity first, in two tiers.  Wrapper identity hits
+    when the wire list holds the state objects themselves (legacy callers,
+    state-side projections).  The kernel wire, however, hands every layer
+    per-call message VIEWS — fresh wrapper + fresh contents list — so the
+    second tier matches on the tuple of shared content-object ids, which is
+    exact to the same degree: content objects live in exactly one message
+    (the transcript's no-duplicate invariant), and a view carries the state
+    original's objects.  Empty-contents messages carry no identity evidence
+    and skip the tier.  The third tier matches wrappers REBUILT with fresh
+    contents but the original's ``additional_properties`` dict — the
+    sanctioned write-through channel, kept by the reminder middleware's
+    enriched user messages and the LAST_WORDS refresh.  Without it a
+    stored opener that is also the last user message (a child continuing
+    from its own history) drops out of the history segment and the turn
+    resolves to nothing.  The dict must belong to exactly one state message
+    and the roles must agree.  The ``message_id`` fallback serves only wire
+    messages with no identity hit anywhere in state (streaming finalizers
+    rebuild current-turn messages into fresh objects, contents included)
+    and is guarded: built EXCLUDING excluded and marker state messages and
+    requiring role agreement — a bare id match is not safe because
+    response aggregation reuses sequential ids across runs and
+    ``_dedup_message_ids`` runs only over the wire list, so a pre-marker
+    EXCLUDED state message can hold the same id as a visible current-turn
+    message.  Later state copies win: rebuilt wire objects twin with the
+    newest state occurrence of their id.
+    """
+    by_identity = {id(m): i for i, m in enumerate(state_messages)}
+    by_content_identity: dict[tuple[int, ...], int] = {}
+    by_properties_identity: dict[int, int] = {}
+    shared_properties: set[int] = set()
+    for s, m in enumerate(state_messages):
+        if m.contents:
+            by_content_identity[tuple(id(c) for c in m.contents)] = s
+        properties_key = id(m.additional_properties)
+        if properties_key in by_properties_identity:
+            shared_properties.add(properties_key)
+        by_properties_identity[properties_key] = s
+    for properties_key in shared_properties:
+        del by_properties_identity[properties_key]
+    mapping: dict[int, int] = {}
+    unmatched: list[int] = []
+    for w, msg in enumerate(messages):
+        s = by_identity.get(id(msg))
+        if s is None and msg.contents:
+            s = by_content_identity.get(tuple(id(c) for c in msg.contents))
+        if s is None:
+            s = by_properties_identity.get(id(msg.additional_properties))
+            if s is not None and state_messages[s].role != msg.role:
+                s = None
+        if s is None:
+            unmatched.append(w)
+        else:
+            mapping[w] = s
+    if not unmatched:
+        return mapping
+
+    fallback: dict[tuple[str, str], int] = {}
+    for s, msg in enumerate(state_messages):
+        mid = msg.message_id
+        if not mid:
+            continue
+        props = msg.additional_properties
+        if props.get(EXCLUDED_KEY, False) or HistoryMarkerKind.KEY in props:
+            continue
+        fallback[(mid, msg.role)] = s
+    engaged = False
+    for w in unmatched:
+        mid = messages[w].message_id
+        if not mid:
+            continue
+        s = fallback.get((mid, messages[w].role))
+        if s is not None:
+            mapping[w] = s
+            engaged = True
+    if engaged:
+        _log.debug("turn resolver: message_id fallback engaged for wire-state correspondence")
+    return mapping
+
+
+def _last_healthy_turn_marker(state_messages: list[Message]) -> tuple[int | None, int]:
+    """Return ``(state index, _turn int)`` of the last HEALTHY turn marker.
+
+    A marker cluster (the contiguous run of ``_chrys_kind`` messages ending
+    at a TURN marker) containing ANY ``HistoryMarkerKind.STATUS_MARKERS``
+    member does not close a completed turn: a crash-terminated turn is an
+    interrupted CURRENT task, not a completed exchange.  Walk back to the
+    newest turn marker whose cluster carries no status marker.  Returns
+    ``(None, 0)`` when no healthy marker exists; the int is ``0`` when the
+    healthy marker carries no usable ``_turn``.
+    """
+    i = len(state_messages) - 1
+    while i >= 0:
+        props = state_messages[i].additional_properties
+        if props.get(HistoryMarkerKind.KEY) != HistoryMarkerKind.TURN:
+            i -= 1
+            continue
+        healthy = True
+        j = i
+        while j >= 0:
+            kind = state_messages[j].additional_properties.get(HistoryMarkerKind.KEY)
+            if not kind:
+                break
+            if kind in HistoryMarkerKind.STATUS_MARKERS:
+                healthy = False
+            j -= 1
+        if healthy:
+            turn_int = props.get(TURN_INDEX_KEY)
+            return i, turn_int if isinstance(turn_int, int) else 0
+        i = j
+    return None, 0
+
+
+def _folded_turn_seed(state: dict[str, Any] | None) -> int:
+    """Return the highest turn number preserved only in compressed blocks.
+
+    Phase 3 / force compression folds up to a marker INCLUSIVE, so folded
+    turns' markers no longer live in active state; their numbers survive in
+    ``compressed_msgs[*].turn_range``.  Skips the ``(0, 0)`` no-marker
+    sentinel.
+    """
+    if state is None:
+        return 0
+    blocks = state.get("compressed_msgs")
+    if not isinstance(blocks, list):
+        return 0
+    seed = 0
+    for block in blocks:
+        turn_range = getattr(block, "turn_range", None)
+        if turn_range is None and isinstance(block, dict):
+            turn_range = block.get("turn_range")
+        if not isinstance(turn_range, tuple | list) or len(turn_range) != 2:
+            continue
+        low, high = turn_range
+        if (low, high) == (0, 0) or not isinstance(high, int):
+            continue
+        seed = max(seed, high)
+    return seed
+
+
+def _resolve_turns(messages: list[Message], state: dict[str, Any] | None) -> ResolvedTurns:
+    """Resolve real turns over the live wire list + provider state (§3.2).
+
+    Strict when the current marker region holds a real opener; degraded
+    (current span = the whole region) when the region is non-empty with no
+    opener but holds a user message or follows completed strict turns; the
+    empty result only for histories that never held user input.  The marker
+    boundary comes from the provider state (where markers live) and is
+    PROJECTED into the wire list via the identity-first correspondence —
+    compaction receives the marker-less wire view, so a wire-side marker
+    scan can never see one.  EXCLUDED wire messages are invisible to the
+    scan: a mid-call fold (Step 0 / P3) excludes a completed turn in place,
+    and its opener must not keep opening a turn the state no longer holds.
+    """
+    state_messages: list[Message] = []
+    if state is not None:
+        raw = state.get("messages")
+        if isinstance(raw, list):
+            state_messages = raw
+
+    correspondence = _state_correspondence(messages, state_messages) if state_messages else {}
+
+    # Rule 1a — history segment.  Spans are confined to it in both strict
+    # and degraded modes: non-history providers can emit user-role messages
+    # into the request prefix, and unclipped slicing would let such a prefix
+    # message open a "turn", handing provider context to P1/P2 and
+    # mis-anchoring P4's prior-turn boundary.
+    if correspondence:
+        history_start = min(correspondence)
+    elif state_messages:
+        # State exists but none of it is on the wire (service-side context
+        # skips local history): the only session content is the in-flight
+        # input tail — anchor at its opener (or first user message for a
+        # flagged-only tail) so a provider prefix can never open a turn.
+        last_opener = None
+        first_user = None
+        for i, msg in enumerate(messages):
+            if opens_turn(msg):
+                last_opener = i
+            if first_user is None and msg.role == "user":
+                first_user = i
+        if last_opener is not None:
+            history_start = last_opener
+        elif first_user is not None:
+            history_start = first_user
+        else:
+            history_start = len(messages)
+    else:
+        # No provider state (fresh session or unbound strategy): the whole
+        # wire is the segment, matching pre-resolver behavior.
+        history_start = 0
+
+    # Rule 1b — marker region, from the state-side scan projected into the
+    # wire: just after the last wire message belonging to the completed-
+    # turns set (state messages at/before the last HEALTHY turn marker).
+    marker_idx, healthy_turn_int = _last_healthy_turn_marker(state_messages)
+    if marker_idx is None:
+        region_start = history_start
+    else:
+        completed_wire = [w for w, s in correspondence.items() if s <= marker_idx]
+        region_start = max(completed_wire) + 1 if completed_wire else history_start
+
+    # Slice over VISIBLE messages only: Step-0 compressions and P3 folds
+    # exclude wire messages in place mid-call, and a folded opener must not
+    # reopen a turn that no longer exists in provider state (the provider
+    # filters excluded messages from the wire before the next request, so
+    # mid-call exclusion is the only way one reaches the resolver).  Spans
+    # keep raw wire indices — each span runs to the next span's start, so
+    # interleaved excluded messages stay inside a span and the phases'
+    # exclusion-aware group collection sees contiguous ranges.
+    segment = messages[history_start:]
+    visible_idx = [i for i, m in enumerate(segment) if not m.additional_properties.get(EXCLUDED_KEY, False)]
+    visible_slices = turn_slices([segment[i] for i in visible_idx])
+    slices: list[tuple[int, int]] = []
+    for k, (s, _e) in enumerate(visible_slices):
+        start = visible_idx[s] + history_start
+        end = visible_idx[visible_slices[k + 1][0]] + history_start if k + 1 < len(visible_slices) else len(messages)
+        slices.append((start, end))
+
+    region = messages[region_start:]
+    region_visible = [m for m in region if not m.additional_properties.get(EXCLUDED_KEY, False)]
+    degraded = False
+    synthetic_opener_idx: int | None = None
+    if not region_visible or any(opens_turn(m) for m in region_visible):
+        # Rules 2 + 3 — strict: current turn = the last slice.
+        final_slices = slices
+    elif any(m.role == "user" for m in region_visible) or slices:
+        # Rule 4 — degraded: the current span is the whole region (its
+        # assistant/tool work precedes any synthetic opener and P4 only
+        # collects groups from the span start); previous turns are the
+        # strict slices clipped at the region boundary (only the last one
+        # can straddle it, and clipping is correct precisely because the
+        # boundary cluster is healthy).
+        degraded = True
+        final_slices = [(s, min(e, region_start)) for s, e in slices if s < region_start]
+        final_slices.append((region_start, len(messages)))
+        synthetic_opener_idx = next(
+            (
+                region_start + i
+                for i, m in enumerate(region)
+                if m.role == "user" and not m.additional_properties.get(EXCLUDED_KEY, False)
+            ),
+            None,
+        )
+        _log.debug(
+            "turn resolver: degraded region at wire index %d (synthetic opener: %s)",
+            region_start,
+            synthetic_opener_idx,
+        )
+    else:
+        # Rule 5 — no user message anywhere: today's no-op early return.
+        return ResolvedTurns(spans=[], degraded=False, synthetic_opener_idx=None, region_start=region_start)
+
+    # Absolute numbering.  Completed spans read the first state turn marker
+    # after their opener; the current span is max(last healthy active
+    # marker, folded seed) + 1 — NOT turn_counter + 1, which counts an
+    # unstripped crash cluster's aborted turn while the resolver refuses to
+    # close it.  The resolver wins on divergence.  The previous-span count
+    # keeps enumeration coherent when state carries no numbering at all
+    # (unbound strategy) or a healthy marker lost its ``_turn`` int.
+    seed = _folded_turn_seed(state)
+    current_number = max(healthy_turn_int, seed, len(final_slices) - 1) + 1
+    state_turn_markers = [
+        (i, m.additional_properties.get(TURN_INDEX_KEY))
+        for i, m in enumerate(state_messages)
+        if m.additional_properties.get(HistoryMarkerKind.KEY) == HistoryMarkerKind.TURN
+    ]
+
+    spans: list[TurnSpan] = []
+    last = len(final_slices) - 1
+    for k, (start, end) in enumerate(final_slices):
+        state_boundary = correspondence.get(start)
+        if k == last:
+            number = current_number
+        else:
+            number = None
+            if state_boundary is not None:
+                for m_idx, turn_int in state_turn_markers:
+                    if m_idx > state_boundary and isinstance(turn_int, int):
+                        number = turn_int
+                        break
+            if number is None:
+                number = seed + k + 1
+                _log.debug("turn resolver: enumerated fallback number %d for span %d", number, k)
+        spans.append(TurnSpan(start=start, end=end, absolute_number=number, state_boundary=state_boundary))
+
+    return ResolvedTurns(
+        spans=spans,
+        degraded=degraded,
+        synthetic_opener_idx=synthetic_opener_idx,
+        region_start=region_start,
+    )