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/head.py
+304
View File
@@ -0,0 +1,304 @@
"""M3: where the story is being read, and what moving that point costs.
Undo used to delete. It removed the trailing nodes, let `tree.refresh_head`
recompute the tip from what survived, and the story was wherever the rows ended.
That made the head a derived value and made Redo impossible, because the turns it
would have moved forward into were gone.
The head is now a stored position that can sit behind the retained tip. Nothing
is deleted, so three things that used to be the same question are now three
different ones:
* **the active head** — `adventure.head_branch_id` and `adventure.head_depth`,
the end of the story being told. Every read of the story stops here, because
`lineage.Path` caps every entry at it.
* **the retained tip** — the deepest live node still on the lineage. Redo walks
toward it. It is read through `Path.uncapped()`, and only this module and the
divergence check may look at it.
* **the opening** — the shallowest node on the story, which is the floor Undo
may not pass.
Everything that moves the head or asks a question about it lives here, so the
turn engine, Retry, Add-take, Undo, Redo and Edit share one set of rules rather
than four similar ones. The Phase 0B spike put the fork check in the write path
and left Retry and Add-take on the old one, which is exactly the divergence this
module exists to prevent.
The state that belongs to a position is not recomputed. Every node carries the
world state it left behind (`attempts.snapshot_outcome`), so moving the head is a
row lookup plus `attempts.restore_state`, at any distance, in either direction.
"""
from sqlalchemy.orm import Session, undefer
from . import attempts, models, tree
from .context import lineage
# The kinds of node a player writes. An undo or a redo steps over a whole turn,
# which is one of these followed by the reply to it, so both ends need to agree
# on what "a player's half of a turn" is.
PLAYER_TYPES = ("do", "say", "story", "continue")
# ------------------------------------------------------------------ reading
def opening_depth(db: Session, adventure: models.Adventure) -> int | None:
"""Returns the depth of the first node of the story, or None if there is none.
This is Undo's floor. The Phase 0B spike moved the head to -1 and rendered an
empty transcript, because its guard tested for a node of type `start` and an
adventure opened with a player-written `story` action has none. Asking the
path for its shallowest node needs no such special case: whatever the opening
is called, it is the node with the smallest depth, and the story keeps it.
The read is uncapped. The opening does not move when the head does, and
capping would make the floor depend on where the head already is.
"""
return (
db.query(models.Action.depth)
.filter(
models.Action.adventure_id == adventure.id,
lineage.path_of(db, adventure).uncapped().clause(models.Action),
)
.order_by(models.Action.depth.asc(), models.Action.id.asc())
.limit(1)
.scalar()
)
def retained_tip(db: Session, adventure: models.Adventure) -> int | None:
"""Returns the depth of the deepest live node still retained on this lineage.
This is what the head would be if the story had never been undone, and it is
what Redo can reach. It is not the head, and no read of the story may use it.
"""
return (
db.query(models.Action.depth)
.filter(
models.Action.adventure_id == adventure.id,
lineage.path_of(db, adventure).uncapped().clause(models.Action),
)
.order_by(models.Action.depth.desc(), models.Action.id.desc())
.limit(1)
.scalar()
)
def behind_tip(db: Session, adventure: models.Adventure) -> bool:
"""Returns whether retained story sits past the head.
This one predicate answers every "does this write need to fork?" question in
the application. It is true exactly when the user has undone and not redone,
which is the only situation in which writing can displace an accepted future.
It is also what makes "is this turn the tip?" answerable again. Retry,
Add-take and `stand_on` each decide between amending a turn in place and
giving it a branch, and each used to ask `last_action`, which reads the
*capped* path and therefore reports the node at the head as the newest one.
Under a moved-back head that answer is wrong in the dangerous direction: it
says a turn with an accepted future is a leaf, and amending it in place would
leave that future descending from a take that is no longer live.
"""
tip = retained_tip(db, adventure)
return tip is not None and tip > adventure.head_depth
def node_at(
db: Session, adventure: models.Adventure, depth: int
) -> models.Action | None:
"""Returns the live node at `depth` on the retained lineage, outcome loaded.
The read is uncapped on purpose: Redo asks for a node it is about to move the
head onto, which is by definition past the head at the time of asking. The
outcome columns are undeferred because the only reason to fetch this row is
to restore the state it left behind.
"""
return (
db.query(models.Action)
.filter(
models.Action.adventure_id == adventure.id,
lineage.path_of(db, adventure).uncapped().clause(models.Action),
models.Action.depth == depth,
)
.options(
undefer(models.Action.state_after),
undefer(models.Action.world_state_after),
)
.order_by(models.Action.id)
.first()
)
def redo_target(db: Session, adventure: models.Adventure) -> int | None:
"""Returns the depth the head moves to on Redo, or None if there is nowhere.
Redo steps over a whole turn, the same unit Undo steps back over, so a
player's action and the reply to it move together. Landing between them would
show the story an input with no answer and would leave the next Undo undoing
half a turn.
The walk is along the retained lineage, which is what makes Redo follow the
continuation that was active rather than choosing among branches. After a
divergence the new branch *is* the lineage, and the displaced future is no
longer on it, so this returns None without having to know that a divergence
happened. That is `STORY-BRANCH-SEMANTICS.md` §8 falling out of the lineage
rather than being enforced by a flag.
"""
ahead = (
db.query(models.Action)
.filter(
models.Action.adventure_id == adventure.id,
lineage.path_of(db, adventure).uncapped().clause(models.Action),
models.Action.depth > adventure.head_depth,
)
.order_by(models.Action.depth.asc(), models.Action.id.asc())
.limit(2)
.all()
)
if not ahead:
return None
first = ahead[0]
if (
first.type in PLAYER_TYPES
and len(ahead) > 1
and ahead[1].type == "ai"
and ahead[1].depth == (first.depth or 0) + 1
):
return ahead[1].depth
return first.depth
def can_redo(db: Session, adventure: models.Adventure) -> bool:
"""Returns whether an ordinary Redo is available from where the head is."""
return redo_target(db, adventure) is not None
def undo_target(
db: Session, adventure: models.Adventure
) -> tuple[int, models.Action] | None:
"""Returns where Undo moves the head, and the first node it steps back over.
None means there is nothing to undo, which is either an empty story or a head
already resting on the opening. The caller turns that into a 400; this
function does not raise, so that the same question can be asked without
committing to undoing.
A turn is the player's node plus the reply to it, and both move together for
the reason given in `redo_target`. The player half is only claimed when it is
directly in front of the reply, so a bare `continue`, which writes no player
node, steps back over the reply alone.
"""
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:
return None
last = newest[0]
first_stepped = last
before = newest[1] if len(newest) > 1 else None
if (
last.type == "ai"
and before is not None
and before.type in PLAYER_TYPES
and before.depth == (last.depth or 0) - 1
):
first_stepped = before
floor = opening_depth(db, adventure)
if first_stepped.depth is None or floor is None:
return None
if first_stepped.depth <= floor:
# Stepping back over this turn would hide the opening of the campaign,
# which is the pre-campaign state `STORY-BRANCH-SEMANTICS.md` §4 stops
# at. The floor is the opening node itself rather than depth -1, so an
# adventure that opens on a player-written `story` action stops in the
# same place as one that opens on a `start` node.
return None
return first_stepped.depth - 1, first_stepped
def can_undo(db: Session, adventure: models.Adventure) -> bool:
"""Returns whether an ordinary Undo is available from where the head is."""
return undo_target(db, adventure) is not None
# ------------------------------------------------------------------ writing
def move_to(db: Session, adventure: models.Adventure, depth: int) -> None:
"""Moves the active head to `depth` and restores the state recorded there.
This is the whole of Undo and Redo. Nothing is deleted, nothing is
recomputed, and the direction of travel does not matter: the node at the
destination carries the world state it left behind, so arriving from in front
of it and arriving from behind it restore the same value.
A destination with no node — the head resting one step in front of the
opening — leaves the live state alone, which is `attempts.restore_state`'s
rule for a missing snapshot and the reason it is not this function's job to
invent an empty one.
"""
adventure.head_depth = depth
attempts.restore_state(adventure, node_at(db, adventure, depth))
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.
Returns whether a branch was created, which is what a caller reports as a
divergence.
Called before every write that continues the story, and it does nothing on
the ordinary path where the head is already at the tip. That is the property
worth keeping: a story that is never undone forks exactly as often as it did
before M3, so the branch table does not fill up with one branch per turn.
Undo alone must not fork. Moving the head is not a decision to abandon
anything — the user may be reading, or about to Redo. Only the first write
below the head states which continuation they mean, which is
`STORY-BRANCH-SEMANTICS.md` §8 and §20 and what makes Redo survive an Undo.
`tree.branch_at` leaves the departed branch exactly as it is: its nodes stay
live, at their depths, on their branch. The new branch inherits the story up
to the head and owns everything written from here, so the displaced future
remains reachable through the branch it was written on.
"""
if not behind_tip(db, adventure):
return False
departed = lineage.branch_of(db, adventure)
at_depth = adventure.head_depth
tree.branch_at(db, adventure, at_depth)
if departed is not None:
mark_superseded(departed, at_depth)
return True
def mark_superseded(branch: models.Branch, depth: int) -> None:
"""Records that this branch's story past `depth` was displaced.
`DATA-MODEL.md` §5 gives a branch a disposition of active, retained or
disposable. This is that disposition, stored as the fact that produced it
rather than as a word: the depth the story left at, and when. A branch with
no `superseded_at` is active; one with a value has retained history past that
depth which no active head is reading.
Nothing in the application reads these columns to make a decision, and that
is deliberate. Redo is decided by the lineage, not by a flag, so a stale or
hand-edited value here cannot make the story wrong. They exist so that the
cleanup and discarded-history features `STORY-BRANCH-SEMANTICS.md` §28 and
§29 leave to a later version have something to select on, and so that a
divergence is observable in a test.
The shallowest departure wins. A branch left at depth 9 and later left again
at depth 4 has retained history from 4 onward, and recording the later, deeper
value would understate what was displaced.
"""
if branch.superseded_depth is None or depth < branch.superseded_depth:
branch.superseded_depth = depth
if branch.superseded_at is None:
branch.superseded_at = models.utcnow()