M4: add durable named Save Points

A Save Point is a name for a story position, and restoring one is head
movement. That is the whole architecture, and it is what ADR 012 and
BUILD-MILESTONES' note on M4 asked 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 the user gets:

- Name the moment they are reading, keep playing, restart the app, and come
  back to it. Restoring moves the story back and deletes nothing: the later
  turns stay, Redo still walks forward into them, and writing something
  different is what starts a new line while the old one is kept.
- Rename, delete, and a list, in a Save Points panel beside the branch panel,
  with a Save Point button next to Undo and Redo. Both confirmations say what
  is *not* destroyed, because that is the part the screen cannot show.
- Save Points survive export and import.

What was deliberately not built:

- No second restore path. `head.move_to_node` is the only new movement: its
  depth half is M3's `head.move_to` unchanged, and its branch half is the
  single assignment `switch_branch` already makes. No head field is written
  in the checkpoint router, nothing reconstructs state, nothing prunes a
  memory, nothing copies or deletes a turn, and restore never forks — the
  first write below the restored head does, through `fork_if_behind_head`.
- No automatic cleanup. A Save Point behind the head, or naming a line the
  story left, is doing its job (STORY-BRANCH-SEMANTICS §19). The one removal
  is a cascade: deleting a branch takes its Save Points, as it takes its
  memories, because the story they named went with it.
- No new ADR. ADR 012 already decides the architecture, and a table is not a
  decision.

The one call the planning package did not already make: restore moves the
branch half of the head only when the coordinate is off the path being read.
Doing it unconditionally would quietly hand back an abandoned continuation
whenever a Save Point in a shared prefix was restored; never doing it would
make a Save Point on a departed line unrestorable, which contradicts §19.
TECHNICAL-DESIGN §8.8 records it.

Schema: a `checkpoints` table holding a name, an optional note and a
(branch, depth) coordinate — no copy of any story. `create_all` builds it as
it did `memories` and `branches`; migration 80 adds the index. No backfill,
because nobody had named a position before M4.

The coordinate is deliberately not an action id: one coordinate holds every
attempt at a turn and exactly one is live, so a coordinate follows a retry
where a row id would pin a take the story no longer tells.

Tests: 680 pass (638 before). 42 new in tests/test_save_points.py covering
D11-D14, I04, L03, E-series lineage and memory isolation after restore and
divergence, the edge cases, and an M3-database migration. One pre-existing
fixture in test_tree_migration.py needed `checkpoints` added to its drop
list — SQLite refuses to drop a table another table references.

Not verified: the browser. No session has had a usable one, so the Save
Point panel's DOM behaviour is unobserved — as M3's Redo control still is.
The twenty-step sequence was driven over HTTP against a live server with a
real process restart instead, and all seventeen checks pass. M4 is
implemented, not accepted: no review has been written.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PWU4gTfLYY6Qq9U7aa9Qw2
This commit is contained in:
JesseMarkowitz
2026-09-03 18:48:54 -04:00
co-authored by Claude Opus 5
parent 3c8e91f644
commit e08d49c3eb
20 changed files with 2272 additions and 26 deletions
+34
View File
@@ -314,6 +314,40 @@ def move_to(db: Session, adventure: models.Adventure, depth: int) -> None:
attempts.restore_state(adventure, node_at(db, adventure, depth))
def move_to_node(db: Session, adventure: models.Adventure, node: models.Action) -> bool:
"""Moves the head onto `node`, changing line only if it is not on this one.
M4 restores a Save Point through this, and it adds no restoring of its own:
the depth half is `move_to` unchanged, so the state, the transcript, the
assembled context and memory eligibility all arrive exactly as they do for
Undo and Redo. Returns whether the line had to change as well as the depth,
which is the one thing about a restore a caller cannot work out afterwards.
The head is two values, and the two halves move for different reasons. A
Save Point almost always names a position on the story being read — its own
line, or the shared prefix that line inherits — and then only the depth
moves. Leaving the branch alone is what makes the restored position keep the
continuation it has: after a divergence, restoring to the shared prefix must
put the reader back on the *new* line, where Redo walks into the turns they
are still writing, not into the future they left. Reaching for the Save
Point's own branch there would quietly hand back the abandoned story.
The other case is real and has to work. A Save Point survives divergence
(`STORY-BRANCH-SEMANTICS.md` §19), so one can name a position on a line the
story has since left, and no amount of depth movement reaches a branch this
path does not contain. The line then moves as well — one assignment, the
same one `switch_branch` makes — and the depth still moves through
`move_to`. Nothing is created: a restore never forks, whichever case it
takes. The first write below the restored head does, through
`fork_if_behind_head`, like every other write.
"""
switched = not lineage.path_of(db, adventure).uncapped().contains(node)
if switched:
adventure.head_branch_id = node.branch_id
move_to(db, adventure, node.depth)
return switched
def fork_if_behind_head(db: Session, adventure: models.Adventure) -> bool:
"""Gives the story a new branch when a write would displace a retained future.