"""
History rectifier — manages slot reservation and message insertion ordering.
Ensures a bot's response appears at the correct logical position in history
even when talker messages arrive during LLM generation.
"""

import logging
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from fellowship.core.session import Session, Message

logger = logging.getLogger(__name__)


class HistoryRectifier:
    def __init__(self, session: "Session") -> None:
        self.session = session

    def reserve_slot(self, sender: str, turn: int) -> int:
        """
        Append a placeholder Message (content=None) to history.
        Returns the index of the reserved slot.
        Called immediately before an LLM call is dispatched.
        """
        raise NotImplementedError

    def fill_slot(self, index: int, content: str, tokens: int) -> None:
        """
        Fill the reserved slot at the given index with the completed response.
        Called when the LLM call returns.
        """
        raise NotImplementedError

    def insert_after_slot(self, slot_index: int, message: "Message") -> None:
        """
        Insert a talker message after the given slot index.
        Called when a talker message arrives while a slot is reserved.
        Subsequent messages increment their positions accordingly.
        """
        raise NotImplementedError