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

"""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 fastapi import Depends, HTTPException
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()
    )


def _rendered(
    db: Session, adventure: models.Adventure, checkpoint: models.Checkpoint
) -> schemas.CheckpointOut:
    """Reads one Save Point out with the three facts the panel needs about it."""
    node = _node_at(db, adventure, checkpoint.branch_id, checkpoint.depth)
    out = schemas.CheckpointOut.model_validate(checkpoint)
    # The same `depth + 1` the branch list counts with, so "turn 42" means the
    # same thing in both places.
    out.turn = checkpoint.depth + 1
    out.resolved = node is not None
    out.on_path = node is not None and lineage.path_of(db, adventure).uncapped().contains(node)
    return out


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 [_rendered(db, adventure, row) for row in rows]


@router.post(
    "/{adventure_id}/checkpoints",
    response_model=schemas.CheckpointOut,
    status_code=201,
)
def create_checkpoint(
    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.
    """
    name = _clean_name(payload.name)
    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)


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