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

M4: close out Save Points, with browser verification

Browse Source 
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
2026-09-04 06:34:56 -04:00
co-authored by Claude Opus 5
parent 279a871a77
commit 62a997f364
23 changed files with 1818 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files
frontend/src/BranchMap.jsx
+19 -6
View File
@@ -1,6 +1,6 @@
import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
import { createPortal } from 'react-dom'
import { CORNER, PAD, ROW_H, branchLabel, headLineage, layoutTree, momentTicks } from './branches'
import { CORNER, PAD, ROW_H, branchLabel, headLineage, layoutTree, momentTicks, savePointsUnder } from './branches'
// The story tree, drawn.
//
@@ -108,6 +108,9 @@ export function BranchMap({ branches, busyId, onSwitch, onRename, onDelete, onCl
// would throw away the only copy of it.
const save = async () => { if (await onRename(selected, renameText)) setRenameText(null) }
const drop = async () => { if (await onDelete(selected)) setConfirming(false) }
// Save Points naming a moment on the selected branch, or on anything forked
// from it, keep it alive — the server refuses to delete them along with it.
const protecting = selected ? savePointsUnder(branches, selected.id) : 0
return createPortal(
<div className="modal-overlay branch-map-overlay" onClick={onClose}>
@@ -239,7 +242,13 @@ export function BranchMap({ branches, busyId, onSwitch, onRename, onDelete, onCl
{confirming ? (
<div className="branch-confirm">
<span>Delete this branch and everything forked from it?</span>
{/* The same wording the list gives, because the same deletion
is reachable from both views and a rule that held in one of
them would not be a rule. */}
<span>
Delete this branch and everything forked from it? The story on
other paths, and every Save Point, is unaffected.
</span>
<button type="button" className="danger" disabled={busy} onClick={drop}>
Delete
</button>
@@ -265,10 +274,14 @@ export function BranchMap({ branches, busyId, onSwitch, onRename, onDelete, onCl
the head stands on is offered, and says why it cannot go. */}
{!isRoot && (
<button type="button" className="danger"
disabled={busy || isLoadBearing}
title={isLoadBearing
? 'The line you are reading is built on this one. Switch away first.'
: undefined}
disabled={busy || isLoadBearing || protecting > 0}
title={
isLoadBearing
? 'The line you are reading is built on this one. Switch away first.'
: protecting > 0
? `${protecting === 1 ? 'A Save Point is' : `${protecting} Save Points are`} saved on this line or one forked from it. Delete ${protecting === 1 ? 'it' : 'them'} first — deleting a Save Point deletes no story.`
: undefined
}
onClick={() => setConfirming(true)}>Delete</button>
)}
</div>
frontend/src/branches.js
+35
View File
@@ -61,6 +61,41 @@ export function headLineage(branches) {
return out
}
// How many Save Points would go if this branch were deleted.
//
// Deleting a branch deletes everything forked from it, and a Save Point names a
// position on a line, so the Save Points on the whole doomed subtree go too.
// The count is summed over that subtree rather than over the one branch — a
// warning that said "1 Save Point" while three disappeared would be worse than
// no warning at all.
//
// Computed here because the panel already holds every branch and its parent,
// so the answer costs a walk rather than an endpoint. The server remains the
// authority on what is actually deleted; this only lets the button say so
// before it is pressed, the same division `headLineage` already uses.
export function savePointsUnder(branches, rootId) {
const children = new Map()
for (const b of branches) {
const key = b.parent_branch_id
if (!children.has(key)) children.set(key, [])
children.get(key).push(b)
}
const byId = new Map(branches.map((b) => [b.id, b]))
const seen = new Set()
const stack = [rootId]
let total = 0
while (stack.length) {
const id = stack.pop()
// The guard is against a cycle, which the schema forbids and a walk should
// still never hang on.
if (seen.has(id)) continue
seen.add(id)
total += byId.get(id)?.save_points ?? 0
for (const child of children.get(id) ?? []) stack.push(child.id)
}
return total
}
// ---------- Map geometry ----------
export const ROW_H = 64 // one branch, name above the lane and meta below
frontend/src/pages/Play/panels/BranchPanel.jsx
+26 -6
View File
@@ -11,7 +11,7 @@
import { useEffect, useState } from 'react'
import { api } from '../../../api'
import { BranchMap } from '../../../BranchMap'
import { branchLabel, headLineage, orderBranches } from '../../../branches'
import { branchLabel, headLineage, orderBranches, savePointsUnder } from '../../../branches'
function BranchPanel({ advId, refreshKey, onSwitched, onTreeChanged, onError }) {
const [branches, setBranches] = useState(null)
@@ -88,6 +88,12 @@ function BranchPanel({ advId, refreshKey, onSwitched, onTreeChanged, onError })
// was forked from. The button said nothing about that and answered
// with a toast; it now says so before it is pressed.
const loadBearing = lineage.has(branch.id)
// A Save Point naming a moment on this branch, or on anything forked
// from it, keeps the branch alive: named moments last until the user
// deletes them, so the server refuses the deletion rather than taking
// them with it. Counted over the subtree, because deleting a branch
// takes its descendants.
const protecting = savePointsUnder(branches, branch.id)
return (
<div key={branch.id} className={`branch-row ${branch.is_head ? 'here' : ''}`}
style={{ marginLeft: indent * 12 }}>
@@ -117,11 +123,20 @@ function BranchPanel({ advId, refreshKey, onSwitched, onTreeChanged, onError })
{branch.own_actions} of its own
{branch.parent_branch_id !== null && ` · forked at moment ${branch.fork_depth + 1}`}
{` · ends at ${branch.depth + 1}`}
{protecting > 0 &&
` · ${protecting === 1 ? '1 Save Point' : `${protecting} Save Points`} kept here`}
</div>
{isConfirming ? (
<div className="branch-confirm">
<span>Delete this branch and everything forked from it?</span>
{/* Only reachable when no Save Point points into this
subtree — the button is disabled otherwise, and the server
refuses regardless. So this says what the deletion costs
without hedging about Save Points that cannot be at risk. */}
<span>
Delete this branch and everything forked from it? The story
on other paths, and every Save Point, is unaffected.
</span>
<button type="button" className="danger" disabled={busy}
onClick={() => remove(branch)}>Delete</button>
<button type="button" onClick={() => setConfirming(null)}>Keep</button>
@@ -145,10 +160,15 @@ function BranchPanel({ advId, refreshKey, onSwitched, onTreeChanged, onError })
{/* The root holds the turns every other branch borrows, and
the server refuses it — so it is not offered. */}
{branch.parent_branch_id !== null && (
<button type="button" className="danger" disabled={busy || loadBearing}
title={loadBearing
? 'The line you are reading is built on this one. Switch away first.'
: undefined}
<button type="button" className="danger"
disabled={busy || loadBearing || protecting > 0}
title={
loadBearing
? 'The line you are reading is built on this one. Switch away first.'
: protecting > 0
? `${protecting === 1 ? 'A Save Point is' : `${protecting} Save Points are`} saved on this line or one forked from it. Delete ${protecting === 1 ? 'it' : 'them'} first — deleting a Save Point deletes no story.`
: undefined
}
onClick={() => setConfirming(branch.id)}>Delete</button>
)}
</div>