"""M4: Save Points — create, list, rename, delete, and restore. A Save Point is a durable named pointer to a story position and nothing else. It stores a coordinate, never a copy of any story, and restoring one moves the active head to that coordinate. That is the whole design, and it is what `BUILD-MILESTONES.md`'s note on M4 and ADR 012 ask for: M3 made the head a stored `(branch, depth)` and made arriving at one a row lookup plus a state restore, so a Save Point needs no restore machinery of its own. What is deliberately absent from this module, because a second copy of any of it would be the failure M4 is warned about: * no head fields are assigned here — `head.move_to_node` moves the head, and `head.move_to` under it restores the state, exactly as Undo and Redo do; * nothing reconstructs state, prunes a memory, copies a turn, or deletes one; * nothing forks. Restore is not a decision to abandon anything, so it creates no branch. The first write below the restored head forks, through the same `fork_if_behind_head` every other write goes through, and the displaced future stays retained (`STORY-BRANCH-SEMANTICS.md` §20). The user-facing word is "Save Point" and the internal one is `checkpoint` (`BROWSER-UX-SPEC.md` §23). Error strings here are read by a player, so they say Save Point. """ from dataclasses import dataclass from fastapi import Depends, HTTPException from sqlalchemy import and_, or_ from sqlalchemy.orm import Session from ... import head, models, schemas from ...context import lineage from ...database import get_db from . import turns from .deps import current_adventure, router from .paging import current_window def _node_at( db: Session, adventure: models.Adventure, branch_id: int, depth: int ) -> models.Action | None: """Returns the live turn a Save Point's coordinate names, or None. The lookup is by coordinate and is not scoped to any path. That is the point of it: a Save Point outlives the reader moving away, so the question it has to answer is "is this position still in this campaign's retained history", not "is it on the story being read now". Whether it is on the current path is a separate question, and `head.move_to_node` is what acts on the answer. `live` is what makes the coordinate follow a retry. One coordinate can hold several attempts at a turn, and a Save Point names the turn rather than the attempt, so it lands on whichever take the story currently tells. """ return ( db.query(models.Action) .filter( models.Action.adventure_id == adventure.id, models.Action.branch_id == branch_id, models.Action.depth == depth, models.Action.live.is_(True), ) .order_by(models.Action.id) .first() ) @dataclass(frozen=True) class _Coordinate: """The shape `lineage.Path` reads, without loading a story row. `Path.contains` asks three things of a node: its branch, its depth, and whether it is live. A coordinate already known to resolve has all three, so the membership question can be put to the coordinate itself. That keeps the single implementation of "is this on the path being read" in `lineage`, where M3 put it, while costing no query and no prose. """ branch_id: int depth: int live: bool = True def _live_coordinates( db: Session, adventure: models.Adventure, checkpoints: list[models.Checkpoint] ) -> set[tuple[int, int]]: """Returns which of these Save Points' coordinates still name a live turn. One query for the whole list, selecting two integer columns. This replaces a resolution per Save Point (M4 review §R B-1), which cost one query each and loaded whole `Action` entities — narration included — to answer a question that is only ever "does a row exist here". `paging.py` states the rule this now follows: a bulk read names the columns it needs, so a new column costs nothing until someone adds it to the list. The clause is an OR of exact `(branch, depth)` pairs rather than `branch IN (…) AND depth IN (…)`, which would match the cross product and report a Save Point as resolved because *some other* Save Point's depth exists on *this* one's branch. """ coordinates = {(c.branch_id, c.depth) for c in checkpoints} if not coordinates: return set() rows = ( db.query(models.Action.branch_id, models.Action.depth) .filter( models.Action.adventure_id == adventure.id, models.Action.live.is_(True), or_(*[ and_(models.Action.branch_id == branch, models.Action.depth == depth) for branch, depth in coordinates ]), ) .all() ) return {(branch, depth) for branch, depth in rows} def _render_all( db: Session, adventure: models.Adventure, checkpoints: list[models.Checkpoint] ) -> list[schemas.CheckpointOut]: """Reads Save Points out with the three facts the panel needs about them. Bounded work whatever the length of the list: one query for the coordinates and one lineage for the campaign, both computed before the loop. Rendering one Save Point and rendering fifty differ in Python, not in round trips. """ live = _live_coordinates(db, adventure, checkpoints) # The path is a property of the campaign, not of any Save Point, so it is # read once. Reading it per row was the other half of the N+1. path = lineage.path_of(db, adventure).uncapped() out = [] for checkpoint in checkpoints: coordinate = (checkpoint.branch_id, checkpoint.depth) resolved = coordinate in live rendered = schemas.CheckpointOut.model_validate(checkpoint) # The same `depth + 1` the branch list counts with, so a moment number # means the same thing in both places. rendered.turn = checkpoint.depth + 1 rendered.resolved = resolved rendered.on_path = resolved and path.contains( _Coordinate(checkpoint.branch_id, checkpoint.depth) ) out.append(rendered) return out def _rendered( db: Session, adventure: models.Adventure, checkpoint: models.Checkpoint ) -> schemas.CheckpointOut: """Reads one Save Point out, through the same path the list uses.""" return _render_all(db, adventure, [checkpoint])[0] def _get_or_404( db: Session, adventure: models.Adventure, checkpoint_id: int ) -> models.Checkpoint: """Resolves a Save Point id, refusing one that belongs to another campaign. The ownership check is the reason this is a function rather than a `db.get` at each call site. A Save Point names a position in one campaign's history, and a coordinate from another campaign would name a different story's turn — or, worse, resolve against this one by arithmetic coincidence. So the id is matched against this adventure, and a Save Point belonging to another is a 404 rather than a restore of the wrong story. """ checkpoint = db.get(models.Checkpoint, checkpoint_id) if checkpoint is None or checkpoint.adventure_id != adventure.id: raise HTTPException(404, "Save Point not found") return checkpoint def _clean_name(raw: str) -> str: """Returns the trimmed name, refusing one that is blank once trimmed.""" name = (raw or "").strip() if not name: raise HTTPException(400, "A Save Point needs a name.") return name @router.get("/{adventure_id}/checkpoints", response_model=list[schemas.CheckpointOut]) def list_checkpoints( db: Session = Depends(get_db), adventure: models.Adventure = Depends(current_adventure), ): """Returns the campaign's Save Points, newest first. Newest first rather than in story order, because story order is not something this list can honestly claim. Depths are positions along a path, and two Save Points on lines that parted company are not comparable by depth at all — ordering by it would draw a sequence that no reading of the story passes through. When they were made is a fact about all of them. """ rows = ( db.query(models.Checkpoint) .filter(models.Checkpoint.adventure_id == adventure.id) .order_by(models.Checkpoint.created_at.desc(), models.Checkpoint.id.desc()) .all() ) return _render_all(db, adventure, rows) @router.post( "/{adventure_id}/checkpoints", response_model=schemas.CheckpointOut, status_code=201, ) def create_checkpoint( adventure_id: int, payload: schemas.CheckpointCreate, db: Session = Depends(get_db), adventure: models.Adventure = Depends(current_adventure), ): """Names the position the story is currently being read at. The active head, not the retained tip. Creating a Save Point after two Undos saves the undone position, because that is where the reader is and the position they are looking at is the one they mean. The distinction only exists at all because M3 stopped Undo from deleting. The node at the head is resolved before the row is written, and its own branch is what gets stored — which is not always the branch being read. A head resting in a shared prefix sits on an ancestor's node, and the ancestor is the branch that still names that position after the reader has forked away from it. **Held under the campaign's turn lock** (M4 closeout, review §S C-5). "Save where I am" has to name one committed position, and the head is exactly what a turn in flight is about to move. Without the lock this endpoint could read `head_depth` while a turn was mid-commit and store a coordinate for a position the story had already left — a Save Point silently naming the wrong moment, which no later operation could detect. It is the same lock Undo, Redo and Restore take, for the same reason, and not a new mechanism. Rename and Delete deliberately do **not** take it: neither reads nor moves a story position, so there is nothing for a turn in flight to race them over. """ name = _clean_name(payload.name) turns.acquire_turn_lock(adventure_id) try: node = head.node_at(db, adventure, adventure.head_depth) if node is None: raise HTTPException(400, "There is no turn here to save yet.") checkpoint = models.Checkpoint( adventure_id=adventure.id, name=name, note=payload.note or "", branch_id=node.branch_id, depth=node.depth, ) db.add(checkpoint) db.commit() db.refresh(checkpoint) return _rendered(db, adventure, checkpoint) finally: turns._active_turns.discard(adventure_id) @router.patch( "/{adventure_id}/checkpoints/{checkpoint_id}", response_model=schemas.CheckpointOut, ) def rename_checkpoint( checkpoint_id: int, payload: schemas.CheckpointRename, db: Session = Depends(get_db), adventure: models.Adventure = Depends(current_adventure), ): """Changes a Save Point's label. Nothing else about it moves. Not the coordinate, not the head, not a row of story. A Save Point that has been renamed restores to exactly the position it did before, which is `STORY-BRANCH-SEMANTICS.md` §23. """ checkpoint = _get_or_404(db, adventure, checkpoint_id) if payload.name is not None: checkpoint.name = _clean_name(payload.name) if payload.note is not None: checkpoint.note = payload.note db.commit() db.refresh(checkpoint) return _rendered(db, adventure, checkpoint) @router.delete("/{adventure_id}/checkpoints/{checkpoint_id}", status_code=204) def delete_checkpoint( checkpoint_id: int, db: Session = Depends(get_db), adventure: models.Adventure = Depends(current_adventure), ): """Removes the named pointer, and only the pointer. The turn it named stays, its branch stays, the future past it stays, and the head does not move. This endpoint deletes one row of the `checkpoints` table. `STORY-BRANCH-SEMANTICS.md` §25. """ checkpoint = _get_or_404(db, adventure, checkpoint_id) db.delete(checkpoint) db.commit() return None @router.post( "/{adventure_id}/checkpoints/{checkpoint_id}/restore", response_model=schemas.ActionPage, ) def restore_checkpoint( adventure_id: int, checkpoint_id: int, db: Session = Depends(get_db), adventure: models.Adventure = Depends(current_adventure), ): """Returns the story to a Save Point, deleting nothing. Four steps, and the last one is not this module's code: resolve the coordinate, refuse it if it no longer names a live turn, hand it to `head.move_to_node`, and answer with the window the head now caps. The transcript, the world state, the assembled context and which memories can be retrieved all move together, because all four already read through the one path object the head caps — the same reason Undo needed no memory pruning. The turns past the restored position are retained, exactly as they are after an Undo, and ordinary Redo can still walk forward into them until the user writes something different. Restore does not fork; the first write below the head does. A coordinate that no longer resolves is refused rather than approximated. Moving the head to the nearest surviving turn would be the one outcome worse than doing nothing: a Save Point that silently means somewhere else. """ checkpoint = _get_or_404(db, adventure, checkpoint_id) turns.acquire_turn_lock(adventure_id) try: node = _node_at(db, adventure, checkpoint.branch_id, checkpoint.depth) if node is None: raise HTTPException( 409, "That Save Point's position is no longer part of this story.", ) head.move_to_node(db, adventure, node) adventure.updated_at = models.utcnow() db.commit() db.refresh(adventure) # A window, not the whole story, for the reason Undo gives: the client # replaces its transcript with this, and the transcript is a window. return current_window(db, adventure) finally: turns._active_turns.discard(adventure_id)