Jesse.Markowitz/interactive-story
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

M3: move the story's head instead of deleting its turns

Browse Source 
Undo deleted. It removed the trailing AI action and the player action in
front of it, pruned the memories covering them, and let the tip fall back
to whatever survived. That made it 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. Phase 0B demonstrated the
head-cursor alternative in a disposable spike; this is that concept as
production code.

backend/app/head.py is the whole of it. Three questions that used to be
one — where the story is being read, how far it is retained, and where it
opens — are now three functions, and every caller that moves the head or
asks about it goes through this module. The spike put the fork check in
the write path and left Retry and Add-take on the old one; sharing the
rules is what stops that divergence coming back.

lineage.Path now caps every entry at the head, so hiding the retained
future costs nothing at the call sites: the transcript, the context
builder, attempts.preceding and memory retrieval already funnelled
through path_of and narrow together. Path.uncapped() is the deliberate
exception, and only Redo and the fork check may use it. The memory bank
needs no pruning for the same reason — a memory carries the coordinate of
the node its block ends on, so one derived past the head falls outside
the capped clause and becomes retrievable again on Redo without having
been deleted and re-embedded.

Undo alone does not fork. Moving the head is not a decision to abandon
anything, since the user may be reading or about to Redo; the first write
below the head is where the story states which continuation it means. A
head already at the tip forks nothing, so a story that is never undone
forks exactly as often as it did before and the branch table does not
fill up with one branch per turn. Redo follows the lineage rather than
choosing among branches, which is what invalidates it after a divergence
with no flag to set or clear.

Migrations 78 and 79 give a branch superseded_at and superseded_depth.
Nothing reads them to decide behaviour — Redo is decided by the lineage,
so a stale or hand-edited value here cannot make the story wrong. They
exist so the cleanup and discarded-history features left to a later
version have something to select on, and so a divergence is observable in
a test.

Deleting an action no longer drags a moved-back head forward to the
recomputed tip, which would have silently redone the story. can_undo and
can_redo ride on AdventureOut and ActionPage because the client can work
out neither for itself: the campaign opening may be off the top of the
loaded window, and the retained future is never sent to it.

This is a checkpoint, not the finished milestone. 601 backend tests pass.
Five still assert the destructive contract — they count rows after an
undo and expect the story to be shorter — and need rewriting against the
new one; the world-state assertions inside them already pass. Export and
import do not yet carry the head coordinate, so a bundle still reopens at
the deepest node and can silently redo an undone story, which is the
Phase 0B finding this milestone exists to close. The browser has no Redo
control yet. None of the M3 acceptance coverage (D01-D10, E01-E04,
I01-I03, I07, L01-L02) is written.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QF5TcoB86QADgjHz1GZe8u
This commit is contained in:
JesseMarkowitz
2026-09-03 11:45:01 -04:00
co-authored by Claude Opus 5
parent 2fdd2547f0
commit 903fa7a74f
11 changed files with 534 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/app/routers/adventures/actions.py
+8
View File
@@ -81,6 +81,7 @@ def delete_action(
# This works like undo. The turn is deleted with all of its attempts,
# and whatever it produced is withdrawn. The marks are depths, and a
# depth does not move when an action before it is deleted.
was_at = adventure.head_depth
delete_turn(db, adventure, action)
db.flush()
db.expire(adventure, ["actions"])
@@ -88,6 +89,13 @@ def delete_action(
# middle leaves a gap in the depths, which is intended. See
# `_backfill_tree`.
tree.refresh_head(db, adventure)
# `refresh_head` recomputes the tip, which since M3 is not the head. A
# story sitting behind its retained tip must not be dragged forward to
# the tip by an unrelated delete — that would silently Redo it. Keep the
# head where the reader left it, unless the delete took the ground out
# from under it, in which case the new tip is as far as it can stay.
if was_at < adventure.head_depth:
adventure.head_depth = was_at
# The script state and the world state belong to the adventure, not to
# the node, so deleting the node does not take back what it did to
# them. Put them back to what the story now ends with, which is the
backend/app/routers/adventures/crud.py
+8 -1
View File
@@ -9,7 +9,9 @@ from sqlalchemy import func
from sqlalchemy.orm import Session
from sqlalchemy.orm.attributes import set_committed_value
from ... import attempts, images, limits, memorybank, models, schemas, tree, worldstate
from ... import (
attempts, head, images, limits, memorybank, models, schemas, tree, worldstate,
)
from ...database import get_db
from .deps import CurrentUser, current_adventure, router
@@ -239,6 +241,11 @@ def get_adventure(
set_committed_value(adventure, "actions", actions)
out = schemas.AdventureOut.model_validate(adventure)
out.action_count = total
# M3. Opening a story has to render its history controls correctly, and a
# campaign whose head sits behind the retained tip — undone and then closed —
# must come back with Redo available.
out.can_undo = head.can_undo(db, adventure)
out.can_redo = head.can_redo(db, adventure)
return out
backend/app/routers/adventures/nodes.py
+5 -1
View File
@@ -8,7 +8,7 @@ module in the package can import them.
from fastapi import HTTPException
from sqlalchemy.orm import Session, undefer
from ... import attempts, memorybank, models, tree
from ... import attempts, head, memorybank, models, tree
from ...context import cursors
from ...context import lineage
@@ -125,6 +125,10 @@ def stand_on(
newest is not None
and newest.branch_id == action.branch_id
and newest.depth == action.depth
# A turn the head rests on is still not a leaf while a retained future
# descends from it. `last_action` reads the capped path and cannot see
# that future, so switching in place here would strand it (M3).
and not head.behind_tip(db, adventure)
)
if at_the_tip:
# The story at this coordinate is about to change, so withdraw whatever
backend/app/routers/adventures/paging.py
+3 -1
View File
@@ -8,7 +8,7 @@ columns and apply the same numbering, so both live here.
from sqlalchemy import func
from sqlalchemy.orm import Session, load_only
from ... import models, schemas
from ... import head, models, schemas
from ...context import lineage
@@ -165,4 +165,6 @@ def current_window(db: Session, adventure: models.Adventure) -> schemas.ActionPa
],
total=total,
has_more=has_more,
can_undo=head.can_undo(db, adventure),
can_redo=head.can_redo(db, adventure),
)
backend/app/routers/adventures/takes.py
+114 -65
View File
@@ -11,7 +11,7 @@ from fastapi import Depends, HTTPException, Request
from fastapi.responses import StreamingResponse
from sqlalchemy.orm import Session
from ... import attempts, limits, memorybank, models, schemas, tree
from ... import attempts, head, limits, memorybank, models, schemas, tree
from ...context import cursors
from ...context import lineage
from ...database import get_db
@@ -19,8 +19,8 @@ from ...sse import SSE_HEADERS
from . import turns
from .deps import CurrentUser, current_adventure, router
from .nodes import delete_turn, last_action, stand_on
from .paging import action_window, annotate_takes, current_window
from .nodes import last_action, stand_on
from .paging import current_window
@router.post("/{adventure_id}/retry")
@@ -33,24 +33,44 @@ def retry_action(
):
"""Regenerates the last AI action and keeps the discarded attempt.
The attempt on screen stays as it was written. The shared script state and
world state roll 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.
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":
last_ai = newest
# 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, last_ai)
attempts.roll_back_before(db, adventure, newest)
db.commit()
db.refresh(adventure)
except BaseException:
@@ -137,6 +157,17 @@ def select_variant(
"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]
@@ -263,7 +294,15 @@ def add_take(
retry_of = None
try:
newest = last_action(adventure, db)
at_the_tip = newest is not None and newest.id == action.id
# `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.
@@ -274,7 +313,10 @@ def add_take(
# 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()
@@ -309,71 +351,78 @@ def undo_turn(
db: Session = Depends(get_db),
adventure: models.Adventure = Depends(current_adventure),
):
"""Deletes the last turn: the trailing AI action and its player action, if any.
"""Moves the story back one turn. Deletes nothing (M3).
The endpoint also rolls the shared `script_state` back to before that turn
ran, and it prunes any memory that summarized the removed actions. The turn
lock prevents an undo while a turn is still generating.
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:
# Only the last turn is removed, so fetch the two actions it can
# consist of rather than the whole story.
newest = (
db.query(models.Action)
.filter(
models.Action.adventure_id == adventure.id,
lineage.path_of(db, adventure).clause(models.Action),
)
.order_by(models.Action.depth.desc(), models.Action.id.desc())
.limit(2)
.all()
)
if not newest or newest[0].type == "start":
target = head.undo_target(db, adventure)
if target is None:
raise HTTPException(400, "Nothing to undo")
last = newest[0]
before_that = newest[1] if len(newest) > 1 else None
# Undo only what this branch owns. Everything before the fork is
# borrowed from an ancestor and is part of that ancestor's story too, so
# an undo here must never delete a turn out of another branch. The test
# reads the row's own branch rather than the fork depth, because the
# branch is what decides the case.
if last.branch_id != adventure.head_branch_id:
raise HTTPException(
400, "Nothing to undo on this branch — the turns before it "
"belong to the branch it was forked from.",
)
first_removed = last
if (last.type == "ai" and before_that is not None
and before_that.type in ("do", "say", "story")
and before_that.branch_id == adventure.head_branch_id):
first_removed = before_that
# The state the story returns to once the turn is gone, which is what
# the node before the earliest removed one left behind. Read it before
# the deletes, while those rows are still in the story.
restore_to = attempts.preceding(db, adventure, first_removed)
delete_turn(db, adventure, last)
if first_removed is not last:
delete_turn(db, adventure, first_removed)
attempts.restore_state(adventure, restore_to)
db.flush() # Apply the deletes before anything reads the story back.
db.expire(adventure, ["actions"])
# The tip moves back with the deleted rows.
tree.refresh_head(db, adventure)
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.
actions, total, has_more = action_window(db, adventure)
return schemas.ActionPage(
actions=[
schemas.ActionOut.model_validate(a)
for a in annotate_takes(db, adventure.id, actions)
],
total=total,
has_more=has_more,
)
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)
backend/app/routers/adventures/turns.py
+9 -1
View File
@@ -13,7 +13,7 @@ from fastapi.responses import StreamingResponse
from sqlalchemy.orm import Session
from ... import (
attempts, limits, memorybank, models, schemas, tree, worldstate,
attempts, head, limits, memorybank, models, schemas, tree, worldstate,
)
from ...context import build_context, cursors
from ...database import get_db
@@ -333,6 +333,14 @@ def create_action(
acquire_turn_lock(adventure_id)
try:
_move_to_after(db, adventure, payload.after_id)
# The first write below a moved-back head is where a divergence happens
# (M3). Undo alone does not fork — the user may be reading, or about to
# Redo — so this is the moment the story states which continuation it
# means. The displaced future keeps its rows on the branch being left.
# A head already at the tip, which is every ordinary turn, forks nothing.
if head.fork_if_behind_head(db, adventure):
db.commit()
db.refresh(adventure)
except BaseException:
_active_turns.discard(adventure_id)
raise