M4: close out Save Points, with browser verification
Closes M4. The review's three findings are fixed, the durability rule the specification always implied is now enforced, and M3's and M4's browser behaviour has been verified in a real browser for the first time. B-1 -- the Save Point list was an N+1 that loaded whole Action rows, narration included, to answer "does a row exist here". It is now one bulk two-column coordinate query plus one lineage: 53 SELECTs for 25 Save Points became 5, and the count no longer grows with the list. The clause is an OR of exact (branch, depth) pairs rather than two IN lists, because the cross product would report a Save Point resolved on the strength of another one's depth existing on this one's branch. A test builds exactly that trap. B-2 -- reclassified during closeout from "missing warning" to a behaviour defect, and fixed as one. STORY-BRANCH-SEMANTICS §19 says a named checkpoint remains until explicitly deleted, and §28 already required future cleanup to retain checkpoint-referenced paths; a cascade that silently removed Save Points with a branch violated both, and a warning would only have documented the violation. A branch a Save Point names can no longer be deleted. The request is refused with the offending Save Points named, the user deletes them explicitly -- which deletes no story -- and the branch then goes. The scope is the subtree, because deleting a branch takes its descendants. Both delete controls disable and explain. Recorded as a new §19.1; models.py, TECHNICAL-DESIGN §8.8 and DATA-MODEL §8 had all recorded the cascade as the rule and now record the refusal. An earlier pass in this same closeout had kept the cascade and added a warning. That was the wrong fix and its tests were replaced rather than left standing, since they pinned the defect. B-3 -- the D11/L03 automation never left one process, so it could not distinguish durable state from a live Python object. It now spawns real server processes, kills the first, and reads the campaign back with the second. C-5 -- creating a Save Point takes the campaign's turn lock. "Save where I am" has to name one committed position, and the head is what a turn in flight is about to move. Rename and Delete deliberately do not take it. The architecture is untouched: a Save Point is still name + note + (branch, depth), and restore is still coordinate -> head.move_to_node -> head.move_to -> attempts.restore_state. No second restore path, no state copied into a checkpoint, no fork on restore. Browser verification -- the first in this project, and it covers both milestones. Firefox 154.0.1 through geckodriver over the W3C WebDriver protocol, driving the rendered DOM: 47/47 checks, twice, on independent databases, no console errors. M3's Undo/Redo enable states, transcript movement, Retry and the take pager, divergence retiring Redo; M4's whole Save Point lifecycle, both confirmations, and the new branch-delete refusal including its recovery. No dependency was added: the WebDriver client is stdlib HTTP. No application defect was found by the browser. Four failures occurred, all in the harness -- a wrong SPA route, a wait comparing transcript length when the empty-story placeholder is longer than the first turn, a fixture deleting the branch it was reading, and a reload assertion that sampled once instead of waiting. The last was checked against the app before being called a harness bug. Tests: 698 backend pass (was 680), 60 M4, 94 M3 history, 66 export/ migrations, 93 security/local-only. Frontend lint and build clean, Docker build clean, loopback binding unchanged. No assertion weakened, no skip added. Planning: STORY-BRANCH-SEMANTICS §19.1 is the only behavioural change and it strengthens §19. V1-ACCEPTANCE-TESTS records D11-D14, I04, L03 and the E-series, keeping automated, live-runtime and browser evidence distinct, and weakens no pass condition. DATA-MODEL records the coordinate with the retry measurement that settles it. BROWSER-UX-SPEC rules for Moment over Turn. BUILD-MILESTONES marks M4 COMPLETE, closes M3's browser condition, and lists what M5 inherits. VERSION adds v2.6. No new ADR: ADR 005 already decides that history is preserved rather than overwritten, and §19.1 is that decision applied to checkpoint-referenced history. M4 is closed. M5 may now be briefed; it has not been started. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PWU4gTfLYY6Qq9U7aa9Qw2
This commit is contained in:
JesseMarkowitz
co-authored by
Claude Opus 5
Claude Opus 5
parent
279a871a77
commit
62a997f364
@@ -56,6 +56,19 @@ def list_branches(
|
||||
.group_by(models.Action.branch_id)
|
||||
.all()
|
||||
}
|
||||
# M4 closeout: how many Save Points name a position on each line. Deleting a
|
||||
# branch deletes them along with its story, and the panel has to be able to
|
||||
# say so before the button is pressed (review §R B-2). One grouped query for
|
||||
# the whole tree, like the one above it — never one per branch.
|
||||
save_points = {
|
||||
branch_id: count
|
||||
for branch_id, count in db.query(
|
||||
models.Checkpoint.branch_id, func.count(models.Checkpoint.id)
|
||||
)
|
||||
.filter(models.Checkpoint.adventure_id == adventure.id)
|
||||
.group_by(models.Checkpoint.branch_id)
|
||||
.all()
|
||||
}
|
||||
out = []
|
||||
for branch in branches:
|
||||
count, tip = owned.get(branch.id, (0, None))
|
||||
@@ -70,6 +83,7 @@ def list_branches(
|
||||
branch.fork_depth if branch.fork_depth is not None else tree.NO_DEPTH
|
||||
),
|
||||
own_actions=count,
|
||||
save_points=save_points.get(branch.id, 0),
|
||||
is_head=(branch.id == adventure.head_branch_id),
|
||||
name=branch.name,
|
||||
created_at=branch.created_at,
|
||||
@@ -151,15 +165,31 @@ def delete_branch(
|
||||
heavily retried adventure from growing without bound. That is why it ships
|
||||
with the view that first lets anyone create a fork rather than after it.
|
||||
|
||||
Two kinds of branch cannot be deleted. The root cannot, because it holds the
|
||||
turns every other branch borrows, so deleting it deletes the whole story. The
|
||||
branch currently being read cannot, and neither can any branch it was forked
|
||||
from, because the cascade would remove the head under the player and leave
|
||||
`head_branch_id` dangling. Switch branches first.
|
||||
Three kinds of branch cannot be deleted. The root cannot, because it holds
|
||||
the turns every other branch borrows, so deleting it deletes the whole story.
|
||||
The branch currently being read cannot, and neither can any branch it was
|
||||
forked from, because the cascade would remove the head under the player and
|
||||
leave `head_branch_id` dangling. Switch branches first.
|
||||
|
||||
The third is M4's: **a branch a Save Point names cannot be deleted while that
|
||||
Save Point exists.** `STORY-BRANCH-SEMANTICS.md` §19 says a named checkpoint
|
||||
remains until explicitly deleted, and §28 says a future cleanup feature must
|
||||
retain paths referenced by checkpoints. A cascade that removed Save Points
|
||||
along with a branch would break both, and would break them silently: the
|
||||
story the user asked to delete is the visible thing, and the named moments
|
||||
would go without ever being named in the request. So the deletion is refused,
|
||||
the Save Points are listed, and the user decides — delete the Save Point
|
||||
first, then the branch. Deleting a Save Point still deletes no story (§25),
|
||||
so the recovery costs nothing but a click.
|
||||
|
||||
The check covers the whole doomed subtree, not just this branch, because
|
||||
deleting a branch takes everything forked from it.
|
||||
|
||||
Nodes and memories are deleted by `ON DELETE CASCADE`, and descendants by the
|
||||
cascade on `branches.parent_branch_id`, so the delete is a single statement
|
||||
however deep the subtree is.
|
||||
however deep the subtree is. `checkpoints.branch_id` also carries a cascade,
|
||||
as referential integrity — a Save Point must never point at a branch that is
|
||||
gone — but the guard above means it does not fire through this endpoint.
|
||||
"""
|
||||
branch = get_branch_or_404(adventure, branch_id, db)
|
||||
if branch.parent_branch_id is None:
|
||||
@@ -178,6 +208,11 @@ def delete_branch(
|
||||
400, "You are reading this branch, or one forked from it. Switch to "
|
||||
"another branch first.",
|
||||
)
|
||||
# Refused before the lock is taken: this is a decision about the request, not
|
||||
# a race with a turn.
|
||||
protecting = _save_points_protecting(db, adventure, branch)
|
||||
if protecting:
|
||||
raise HTTPException(409, _protected_message(protecting))
|
||||
turns.acquire_turn_lock(adventure_id)
|
||||
try:
|
||||
# Collect the subtree before the delete, because afterwards there is no
|
||||
@@ -199,6 +234,55 @@ def delete_branch(
|
||||
finally:
|
||||
turns._active_turns.discard(adventure_id)
|
||||
|
||||
# How many Save Point names to spell out before the message starts summarising.
|
||||
# Enough to be actionable, few enough to stay a sentence.
|
||||
NAMED_IN_REFUSAL = 3
|
||||
|
||||
|
||||
def _save_points_protecting(
|
||||
db: Session, adventure: models.Adventure, branch: models.Branch
|
||||
) -> list[models.Checkpoint]:
|
||||
"""Returns the Save Points that deleting `branch` would destroy.
|
||||
|
||||
The whole subtree, because deleting a branch takes everything forked from
|
||||
it, and a check that looked only at this branch would let a Save Point on a
|
||||
child be deleted without a word.
|
||||
"""
|
||||
doomed = _branch_subtree(db, adventure, branch)
|
||||
return (
|
||||
db.query(models.Checkpoint)
|
||||
.filter(
|
||||
models.Checkpoint.adventure_id == adventure.id,
|
||||
models.Checkpoint.branch_id.in_(doomed),
|
||||
)
|
||||
.order_by(models.Checkpoint.created_at, models.Checkpoint.id)
|
||||
.all()
|
||||
)
|
||||
|
||||
|
||||
def _protected_message(protecting: list[models.Checkpoint]) -> str:
|
||||
"""Says which Save Points stand in the way, and what to do about it.
|
||||
|
||||
Named rather than counted, because "2 Save Points" leaves the user hunting
|
||||
for which ones. A long list is truncated so the message stays readable; the
|
||||
Save Points panel shows the rest.
|
||||
"""
|
||||
names = [f"“{c.name}”" for c in protecting[:NAMED_IN_REFUSAL]]
|
||||
listed = ", ".join(names)
|
||||
extra = len(protecting) - len(names)
|
||||
if extra > 0:
|
||||
listed += f" and {extra} more"
|
||||
subject = "a Save Point" if len(protecting) == 1 else "Save Points"
|
||||
return (
|
||||
f"This branch, or a branch forked from it, is where {subject} "
|
||||
f"{listed} {'is' if len(protecting) == 1 else 'are'} saved. Delete "
|
||||
f"{'that Save Point' if len(protecting) == 1 else 'those Save Points'} "
|
||||
f"first if you no longer need "
|
||||
f"{'it' if len(protecting) == 1 else 'them'}, then delete the branch. "
|
||||
f"Deleting a Save Point does not delete any story."
|
||||
)
|
||||
|
||||
|
||||
def _branch_subtree(
|
||||
db: Session, adventure: models.Adventure, root: models.Branch
|
||||
) -> set[int]:
|
||||
|
||||
Reference in New Issue
Block a user