"""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)