interactive-story/backend/app/routers/adventures/takes.py

"""Retries, takes, and the attempts that pile up at one coordinate.

Retry first deleted the AI action and generated a replacement. A later version
kept the row and appended each attempt to a JSON list on it. Now every attempt is
its own node on the same branch at the same depth, and exactly one of them is
`live`. `app/attempts.py` owns the group and its invariants. The endpoints here
only query it.
"""

from fastapi import Depends, HTTPException, Request
from fastapi.responses import StreamingResponse
from sqlalchemy.orm import Session

from ... import attempts, head, limits, memorybank, models, schemas, tree
from ...context import cursors
from ...context import lineage
from ...database import get_db
from ...sse import SSE_HEADERS

from . import turns
from .deps import CurrentUser, current_adventure, router
from .nodes import last_action, stand_on
from .paging import current_window


@router.post("/{adventure_id}/retry")
def retry_action(
    adventure_id: int,
    request: Request,
    db: Session = Depends(get_db),
    user: models.User = CurrentUser,
    adventure: models.Adventure = Depends(current_adventure),
):
    """Regenerates the last AI action and keeps the discarded attempt.

    The attempt on screen stays as it was written. The world state rolls back to
    what the node before it left behind, and the new attempt is stored as a
    sibling at the same coordinate. No text the AI wrote is rewritten or deleted.

    M3 added the one case that cannot be a sibling. Retrying the turn the head
    rests on while a retained future still descends from it would leave that
    future hanging off a take that is no longer live — the story after it was
    written to continue the old text. So a retry from behind the tip takes a
    branch instead, exactly as `add_take` does for a turn the story has moved
    past. It is the same operation reached from a different button.
    """
    turns.acquire_turn_lock(adventure_id)
    last_ai = None
    try:
        newest = last_action(adventure, db)
        if newest is not None and newest.type == "ai":
            # Read this before anything moves, and note it is *not*
            # `fork_if_behind_head`: this fork leaves the path just in front of
            # the turn being retried rather than at the head, so the new take
            # lands at the same depth under the same parent.
            diverging = head.behind_tip(db, adventure)
            if diverging:
                departed = lineage.branch_of(db, adventure)
                tree.branch_at(db, adventure, (newest.depth or 0) - 1)
                if departed is not None:
                    head.mark_superseded(departed, (newest.depth or 0) - 1)
            else:
                # Only a sibling attempt names the node it replaces. A branched
                # take is a fresh node at the same coordinate, so `generate_turn`
                # places it through the tree rather than through `add_attempt`.
                last_ai = newest
            # Roll the state back to before this AI turn's hooks ran, so that
            # regenerating starts from a clean state rather than applying output
            # mutations on top of the attempt being replaced. If the preceding
            # node has no snapshot, which happens for a pre-SP4 row that the
            # migration could not derive one for, this call does nothing and
            # leaves the state as it is.
            attempts.roll_back_before(db, adventure, newest)
            db.commit()
            db.refresh(adventure)
    except BaseException:
        turns._active_turns.discard(adventure_id)
        raise
    return StreamingResponse(
        turns.with_turn_lock(
            adventure_id,
            turns.generate_turn(adventure, db, user, retry_of=last_ai),
        ),
        media_type="text/event-stream",
        headers=SSE_HEADERS,
    )


@router.get(
    "/{adventure_id}/actions/{action_id}/variants",
    response_model=list[schemas.VariantOut],
)
def list_variants(
    adventure_id: int,
    action_id: int,
    db: Session = Depends(get_db),
    adventure: models.Adventure = Depends(current_adventure),
):
    """Returns every attempt made for one AI turn.

    The client fetches these on demand, because the adventure payload carries
    only the counts. That keeps old narration out of every page load.

    You can address the turn by any of its attempts, not only the live one.
    Switching changes which row the story tells, and a client that holds an id it
    received a moment ago still has to be able to ask about the same turn.
    """
    action = db.get(models.Action, action_id)
    if action is None or action.adventure_id != adventure_id:
        raise HTTPException(404, "Action not found")
    rows = attempts.group(db, action)
    if len(rows) < 2:
        return []  # Never retried, so the turn has one attempt.
    return [
        schemas.VariantOut(
            id=row.id,
            index=i,
            text=row.text,
            reasoning=row.reasoning,
            branch_id=row.branch_id,
            created_at=row.created_at.isoformat() if row.created_at else None,
            active=row.live,
        )
        for i, row in enumerate(rows)
    ]


@router.post(
    "/{adventure_id}/actions/{action_id}/variant", response_model=schemas.ActionOut
)
def select_variant(
    adventure_id: int,
    action_id: int,
    payload: schemas.VariantSelect,
    db: Session = Depends(get_db),
    adventure: models.Adventure = Depends(current_adventure),
):
    """Makes an earlier attempt live again and restores the state it produced.

    The restored state covers both the script state and the world state.

    Only the last action can be switched. The turns after an older action were
    written to continue the text that is currently active, so replacing that text
    would leave the story contradicting itself. The attempts of earlier turns
    stay readable through `list_variants`.
    """
    action = db.get(models.Action, action_id)
    if action is None or action.adventure_id != adventure_id:
        raise HTTPException(404, "Action not found")
    rows = attempts.group(db, action)
    if not 0 <= payload.index < len(rows) or len(rows) < 2:
        raise HTTPException(400, "No such attempt for this action")
    newest = last_action(adventure, db)
    if newest is None or newest.depth != action.depth or newest.branch_id != action.branch_id:
        raise HTTPException(
            400,
            "Only the latest message can be switched — the story has already "
            "continued from this one.",
        )
    if head.behind_tip(db, adventure):
        # The head is behind the retained tip, so this turn reads as the newest
        # one but still has an accepted future descending from it. Switching the
        # live take in place would leave that future continuing text the story
        # no longer tells. Forking is the operation that does this safely, and
        # `/fork` is where it lives.
        raise HTTPException(
            400,
            "This turn has a later story that was undone but kept. Redo first, "
            "or use another take to start a new line from here.",
        )
    turns.acquire_turn_lock(adventure_id)
    try:
        chosen = rows[payload.index]
        if not chosen.live:
            # The story at this coordinate is about to change, so withdraw
            # anything derived from the previous text. A retry does the same
            # thing for the same reason.
            memorybank.forget_node(db, adventure, chosen)
            cursors.rewind_all(adventure, chosen.branch_id, (chosen.depth or 0) - 1)
        attempts.make_live(db, adventure, chosen)
        adventure.updated_at = models.utcnow()
        db.commit()
        db.refresh(chosen)
        # Return the row that is now in the story, which is a different row
        # from the one the request addressed. An attempt is a node, so choosing
        # one moves the story onto it rather than rewriting a row.
        return chosen
    finally:
        turns._active_turns.discard(adventure_id)


@router.post(
    "/{adventure_id}/actions/{action_id}/fork", response_model=schemas.ActionPage
)
def fork_from_attempt(
    adventure_id: int,
    action_id: int,
    db: Session = Depends(get_db),
    adventure: models.Adventure = Depends(current_adventure),
):
    """Continues the story from this attempt, forking a branch if one is needed.

    There are three cases, and the first two do not fork:

    * The attempt is already the one the story tells, so there is nothing to do.
    * Its turn is the tip, so the attempts are still leaves that nothing was
      built on. The endpoint switches, as `/variant` does, and creates no branch.
    * The story has moved past its turn, so the endpoint forks. The attempt gets
      a branch of its own, and the line it leaves keeps every turn it has.
    """
    action = db.get(models.Action, action_id)
    if action is None or action.adventure_id != adventure_id:
        raise HTTPException(404, "Action not found")
    # Check this before checking the shape of the turn, because a fork leaves
    # the promoted attempt alone on its branch. A client that repeats the call,
    # after a double click or a retried request, has to get the same answer
    # rather than an error saying the turn it just forked has nothing to fork
    # to.
    if action.live:
        # A live node already holds what its coordinate says, so there is no
        # attempt here to promote. On the path being read this call does
        # nothing, and it has to stay that way, so that a repeated call after a
        # double click or a retried request gets the same answer. Off the path
        # the node belongs to another line's story, and moving there is a branch
        # switch.
        #
        # The membership test covers the whole lineage, not `head_branch_id`. A
        # head borrows its ancestors' turns, so a live node on an ancestor is
        # already being read. Forking it would move the live row off the parent
        # and promote a sibling in its place, which rewrites the story on a
        # branch nobody asked about and on this one, which borrows that depth.
        if lineage.path_of(db, adventure).contains(action):
            return current_window(db, adventure)
        raise HTTPException(
            400,
            "That take is already the story on another branch. Switch to that "
            "branch to read it.",
        )
    if len(attempts.group(db, action)) < 2:
        raise HTTPException(
            400, "This turn has only one take, so there is nothing to fork to."
        )
    turns.acquire_turn_lock(adventure_id)
    try:
        stand_on(db, adventure, action)
        adventure.updated_at = models.utcnow()
        db.commit()
        db.refresh(adventure)
        return current_window(db, adventure)
    finally:
        turns._active_turns.discard(adventure_id)


@router.post("/{adventure_id}/actions/{action_id}/takes")
def add_take(
    adventure_id: int,
    action_id: int,
    payload: schemas.TakeCreate,
    request: Request,
    db: Session = Depends(get_db),
    user: models.User = CurrentUser,
    adventure: models.Adventure = Depends(current_adventure),
):
    """Plays a turn again, whoever wrote it.

    This endpoint replaces two earlier operations. `retry` gave an AI turn
    another attempt, but only for the newest turn, and a player's own message had
    no attempts at all, so changing text you had typed meant overwriting it and
    losing the story it led to. Here an AI turn regenerates, a player turn takes
    the text you supply, and neither depends on where in the story it sits.

    The tip is the only case that needs no branch, and only for an AI turn,
    because nothing was played after it and its attempts are still leaves. A
    player turn is never at the tip, since the reply to it is, so a player turn
    that has been answered always takes a branch.

    A branch is needed here for the same reason `fork` needs one. The turn being
    replayed already has a story after it, and that story was written as a
    continuation of the old text. `branch_at` leaves the path just before this
    turn, so the new attempt is written at the same depth under the same parent,
    and the line it leaves is unchanged. No node below is copied.
    """
    limits.check_row_cap("actions", db, user, adventure=adventure)
    action = db.get(models.Action, action_id)
    if action is None or action.adventure_id != adventure_id:
        raise HTTPException(404, "Action not found")
    if action.type not in ("do", "say", "story", "continue", "ai"):
        # The opening is not a turn anyone played, so it has no second attempt.
        # Editing the scenario is what changes it.
        raise HTTPException(400, "The opening of a story has no other take.")
    if action.depth is None or not lineage.path_of(db, adventure).contains(action):
        raise HTTPException(400, "That turn is not on the story you are reading.")
    turns.acquire_turn_lock(adventure_id)
    retry_of = None
    try:
        newest = last_action(adventure, db)
        # `last_action` reads the capped path, so under a moved-back head it
        # reports the node at the head as the newest one. A turn with a retained
        # future is not a leaf, whatever the capped read says, so ask the head
        # module rather than trusting the depth comparison alone (M3).
        at_the_tip = (
            newest is not None
            and newest.id == action.id
            and not head.behind_tip(db, adventure)
        )
        if at_the_tip and action.type == "ai":
            # Nothing was played after it, so its attempts are still leaves and
            # a branch would serve no purpose. This is the `retry` path.
            retry_of = action
            attempts.roll_back_before(db, adventure, action)
        else:
            # The turn has a story after it, written as a continuation of the
            # text that is there now. The new attempt leaves the path just
            # before the turn, so that story keeps the attempt it was written
            # for.
            departed = lineage.branch_of(db, adventure)
            tree.branch_at(db, adventure, action.depth - 1)
            if departed is not None:
                head.mark_superseded(departed, action.depth - 1)
            attempts.roll_back_before(db, adventure, action)
        adventure.updated_at = models.utcnow()
        db.commit()
        db.refresh(adventure)
    except BaseException:
        turns._active_turns.discard(adventure_id)
        raise
    if action.type == "ai":
        # There is no player action to write. The action this turn answers is
        # already on the path, borrowed from the line being left.
        stream = turns.generate_turn(adventure, db, user, retry_of=retry_of)
    else:
        stream = turns.run_player_turn(
            adventure,
            db,
            schemas.ActionCreate(type=action.type, text=payload.text),
            user,
            # The client seeded its editor from the stored text, which already
            # carries the "> You ..." conventions.
            preformatted=True,
        )
    return StreamingResponse(
        turns.with_turn_lock(adventure_id, stream),
        media_type="text/event-stream",
        headers=SSE_HEADERS,
    )


@router.post("/{adventure_id}/undo", response_model=schemas.ActionPage)
def undo_turn(
    adventure_id: int,
    db: Session = Depends(get_db),
    adventure: models.Adventure = Depends(current_adventure),
):
    """Moves the story back one turn. Deletes nothing (M3).

    This endpoint used to remove the trailing AI action and the player action in
    front of it, prune the memories that covered them, and let the tip fall back
    to whatever survived. Undoing was therefore the one operation in the
    application that destroyed accepted story, and it was why there was no Redo:
    the turns to move forward into no longer existed.

    Now it moves `adventure.head_depth`. The rows stay exactly where they are,
    still live, still on their branch, and `lineage.Path` stops every read at the
    head instead. The transcript, the assembled context, `attempts.preceding` and
    memory retrieval all narrow together, because all four already funnelled
    through the same path object.

    The memory bank needs no pruning for the same reason. A memory carries the
    coordinate of the node its block ends on, so a memory derived from a turn
    that is now past the head falls outside the capped clause and stops being
    retrievable — and becomes eligible again on Redo, without having been deleted
    and re-embedded. That is `STORY-BRANCH-SEMANTICS.md` §33 for free.

    The state comes back from the node the story now ends on, which recorded what
    it left behind when it played. See `head.move_to`.
    """
    turns.acquire_turn_lock(adventure_id)
    try:
        target = head.undo_target(db, adventure)
        if target is None:
            raise HTTPException(400, "Nothing to undo")
        depth, _first_stepped = target
        head.move_to(db, adventure, depth)
        adventure.updated_at = models.utcnow()
        db.commit()
        db.refresh(adventure)
        # Return the newest window rather than the whole story. The client
        # replaces its transcript with this response, and the transcript is a
        # window. Returning everything would defeat the paging on the action a
        # player is most likely to repeat several times in a row.
        return current_window(db, adventure)
    finally:
        turns._active_turns.discard(adventure_id)


@router.post("/{adventure_id}/redo", response_model=schemas.ActionPage)
def redo_turn(
    adventure_id: int,
    db: Session = Depends(get_db),
    adventure: models.Adventure = Depends(current_adventure),
):
    """Moves the story forward again into the continuation Undo stepped out of.

    Redo exists because Undo stopped deleting. It walks the head forward over one
    whole turn along the retained lineage, and restores the state that turn left
    behind.

    It follows the lineage rather than choosing among branches, which is what
    makes it invalidate itself correctly. Writing below a moved-back head forks,
    and from the new branch the displaced future is no longer on the lineage at
    all — so there is nothing ahead to walk into and this returns 400 without any
    flag having to be set or cleared. `STORY-BRANCH-SEMANTICS.md` §8.

    400 is also what a head already at the tip gets, which is the ordinary case
    for a story that has never been undone.
    """
    turns.acquire_turn_lock(adventure_id)
    try:
        depth = head.redo_target(db, adventure)
        if depth is None:
            raise HTTPException(400, "Nothing to redo")
        head.move_to(db, adventure, depth)
        adventure.updated_at = models.utcnow()
        db.commit()
        db.refresh(adventure)
        return current_window(db, adventure)
    finally:
        turns._active_turns.discard(adventure_id)