# Adventure Storyteller — Story Branch Semantics **Status:** v1.0 — behavior confirmed after Phase 0B **Purpose:** Define exactly how Undo, Redo, Retry, Edit, Restore, checkpoints, and abandoned history should behave. ## 1. Design Goal The user experience should remain simple. The user should not need to think in terms of Git branches, tree structures, or database lineage during normal storytelling. The primary controls should be: - Undo - Redo - Retry - Edit - Save Checkpoint - Restore Checkpoint Internally, however, the system should preserve enough history to make these operations safe, reversible, and state-consistent. The core rule is: > User-facing history should feel like normal Undo/Redo, while internal history may use branch-like lineage to avoid destructive edits. ## 2. User-Facing Philosophy ### 2.1 Branching is an implementation detail The normal UI should not require explicit actions such as: - Create Branch - Switch Branch - Merge Branch - Compare Branches Those concepts may exist internally. The user should instead see familiar operations. ### 2.2 Abandoned history is retained but disposable When the user goes backward and continues differently: - the original future should not be immediately deleted, - it should be marked as abandoned/disposable, - it should no longer appear as the active story, - it may be pruned later by a future cleanup feature, - it may optionally become recoverable through a future discarded-history screen. No automatic cleanup policy is required for v1. ### 2.3 Named checkpoints are intentionally durable A named checkpoint is different from ordinary undo history. Named checkpoints remain until explicitly deleted. ## 3. Definitions ### Active History The currently selected sequence of accepted turns from campaign root to the current head. ### Story Head The current endpoint of active history. ### Abandoned History Previously accepted turns that are no longer part of the active continuation because the user undid, restored, edited, or retried and then continued differently. ### Disposable History Abandoned history that is retained for safety/recovery but may be eligible for future cleanup. ### Named Checkpoint A durable user-created pointer to a specific accepted story position. ### Alternate Take A different narrator response to the same user input. ### Divergence The point where active story history begins following a different continuation than previously accepted history. ## 4. Undo Undo moves the active story head backward by one accepted story step. Example: ```text Turn 47 You enter the tavern. Turn 48 You accuse Mara of stealing the key. Turn 49 Mara draws a knife. ``` After one Undo: ```text Active head: Turn 48 Redo candidate: Turn 49 ``` After two Undos: ```text Active head: Turn 47 Redo candidate: Turn 48 ``` ## 5. Undo Depth Preferred behavior: > Unlimited Undo across retained campaign history. If the selected base architecture makes unlimited Undo substantially harder or unsafe, the minimum acceptable behavior is: > At least five consecutive Undo operations. Phase 0B demonstrated repeated non-destructive Undo well beyond the minimum five-step requirement. The selected head-cursor design should therefore support Undo across retained active-lineage history up to the root unless a later implementation defect forces a documented exception. ## 6. State Restoration on Undo Undo must restore more than visible transcript text. When moving the story head backward, the system must restore the corresponding: - authoritative narrative state, - current location, - entity states, - relationships, - facts, - active story threads, - scene state, - summary lineage, - memory lineage, - relevant prompt/retrieval lineage. The system must not leave current state from a later turn attached to an earlier transcript position. ## 7. Redo Redo moves forward along the previously active continuation after Undo. Example: ```text 47 -> 48 -> 49 ``` User undoes to 47: ```text Active: 47 Redo path: 48 -> 49 ``` Pressing Redo restores 48. Pressing Redo again restores 49. ## 8. Redo Invalidation Redo remains available only while the user has not created a new continuation. Example: ```text 47 -> 48A -> 49A ``` User undoes to 47 and then enters a new action: ```text 47 -> 48B ``` At that point: - 48B becomes active, - 48A -> 49A becomes abandoned/disposable history, - ordinary Redo should no longer move into 48A. The old history is retained internally but is no longer part of the standard Redo stack. ## 9. Retry Retry means: > Generate another narrator response to the same user input. Example: ```text User: I open the door. Take A: A dragon lunges through the doorway. ``` Retry: ```text Take B: The room beyond is dark and silent. ``` The user should be able to move among recent alternate takes before continuing. ## 10. Retry Selection Before the user continues the story, alternate narrator takes should remain selectable. Conceptually: ```text User action | +-- Take A +-- Take B +-- Take C ``` One take is selected as active. If the user continues from Take B: ```text User action | +-- Take A [inactive/disposable] +-- Take B [selected] | +-- next user turn +-- Take C [inactive/disposable] ``` Inactive takes should remain retained initially. ## 11. Retry vs Branch Retry should not be presented to the user as “creating a branch.” It is an alternate narrator attempt for the same user instruction. Internally, the implementation may represent retries as sibling turn nodes, alternate takes under one turn request, or another equivalent lineage mechanism. The physical representation is still provisional. ## 12. Retry of Older Narration If the user selects an older narrator response and retries it: - the system first returns to that story position, - the existing future becomes abandoned/disposable history, - the new narrator take becomes a new continuation candidate. The system must restore the state corresponding to the retry point before generating the new response. ## 13. Editing User Input The user should be able to edit an earlier user input. Semantics: > Editing an earlier user input is equivalent to returning to the parent story state and creating a new continuation using the edited input. Example: Original: ```text 47: Arrive at tavern 48: "I accuse Mara of taking the key." 49: Mara draws a knife. ``` User edits Turn 48 to: ```text "I quietly ask Mara whether she has seen the key." ``` Result: ```text 47 ├── 48A original accusation │ └── 49A knife response └── 48B edited question └── new narrator response ``` The old future is retained as disposable history. ## 14. Editing Narrator Output The user should be able to directly correct narrator prose. Example: Original: ```text Mara enters wearing a red cloak. ``` User changes it to: ```text Mara enters wearing a green cloak. ``` The edited narration becomes authoritative for the active continuation. ## 15. Effects of Narrator Edit Editing narrator output may affect structured state. Therefore the system must: 1. return to the state immediately before the edited narration, 2. treat the edited text as the accepted narrator output, 3. re-evaluate state changes implied by that output, 4. create a new active continuation, 5. retain the original narration/future as disposable history. The system must not simply replace visible text while leaving stale state behind. ## 16. Manual State / Canon Correction The user should be able to correct authoritative story state without rewriting prose. Example: > Mara never learned about the silver key. This should be available through an explicit operation such as: - Edit Story State - Edit Canon - Correct Fact Exact UI terminology is still open. ## 17. State Correction Semantics A manual correction should: - record the old value, - record the new value, - record that the source was a manual user correction, - record when the correction occurred, - affect future story context, - remain auditable. A manual correction should not silently rewrite historical transcript text. If historical consistency requires a deeper rewind, the UI may warn the user. ## 18. Checkpoints A checkpoint is a user-created durable save point. Example names: - Before entering Blackwood - Arrival at Ceres Station - Before confronting Mara - Before opening the vault A checkpoint points to a specific accepted story position. ## 19. Checkpoint Durability Named checkpoints remain until explicitly deleted. They should not be removed by: - Undo, - Redo, - Retry, - Edit, - Restore, - branch divergence, - ordinary history cleanup. ## 20. Checkpoint Restore Restoring a checkpoint: 1. moves the active story head to the checkpoint turn, 2. restores authoritative state for that turn, 3. restores corresponding scene state, 4. restores compatible summary/memory lineage, 5. prepares the story to continue from that position. Restore itself does not need to create a new branch immediately. The existing continuation remains the Redo/retained path until the user creates a different continuation; the first divergent write then creates the new continuation. The original later story remains retained as abandoned/disposable history. ## 21. Restore Does Not Delete Example: ```text Checkpoint: Before Fortress 100 -> 101 -> 102 -> 103 -> 104 ``` Restore checkpoint at 100 and continue: ```text 100 ├── 101A -> 102A -> 103A -> 104A [old/disposable] └── 101B -> 102B [active] ``` The UI does not need to show this tree during normal play. ## 22. Model Settings on Restore A checkpoint primarily preserves story position and state. It does not need to force restoration of the exact narrator model/settings used at the time. Every historical turn should separately preserve its original model/settings for auditability. When continuing after restore, the system should normally use the user's current configured model/settings. A future optional control may allow restoring historical model settings. ## 23. Checkpoint Renaming Checkpoint labels may be renamed. Renaming does not change the referenced story position. ## 24. Moving Checkpoints v1 should not casually allow an existing checkpoint to be moved to another turn. Preferred behavior: - rename checkpoint, or - delete checkpoint and create a new one. This keeps checkpoint meaning auditable. ## 25. Deleting Checkpoints Checkpoint deletion must be explicit. Deleting a checkpoint: - removes the named pointer, - does not delete the story turn, - does not delete story history. ## 26. Abandoned / Disposable History When a different continuation becomes active, the displaced future becomes conceptually: ```text abandoned = true disposable = true ``` Equivalent metadata may be used. The exact database representation is implementation-specific. ## 27. No Automatic Cleanup in Initial Version v1 should not automatically purge disposable history. Reasons: - text/state records are inexpensive, - early cleanup risks destroying useful recovery data, - branch/state correctness is easier to verify when history remains, - generated media will consume much more storage than text. Cleanup should be designed only after real usage shows it is necessary. ## 28. Future Cleanup A later cleanup feature may offer: - prune abandoned history older than N days, - prune abandoned history older than N turns, - prune all unprotected discarded paths, - retain paths referenced by checkpoints, - retain paths containing manually preserved alternates, - show estimated space savings before deletion. No specific cleanup policy is committed for v1. ## 29. Possible Future Discarded-History Recovery Screen A future feature may expose discarded/abandoned history. Possible uses: - recover a discarded continuation, - inspect earlier alternate takes, - restore something accidentally abandoned, - compare old and current story paths. This is a possible later feature, not a committed v1 requirement. ## 30. Active History Visibility Normal transcript display should show only: - the active history, - currently selected narrator take, - current story state. Discarded history should not clutter normal play. ## 31. History Integrity The system must never create a transcript/state mismatch such as: ```text Visible transcript says: Mara never saw the key. Structured state says: Mara knows about the key because of abandoned Turn 52. ``` Only active-lineage facts, memories, summaries, and state may influence the current continuation. ## 32. Summary Lineage Summaries are derived from specific story history. When the active story diverges: - summaries containing abandoned future turns must not be applied to the new continuation, - unaffected ancestral summaries may remain valid, - new summaries may be generated when required. The system should record source turn ranges or lineage for every summary. ## 33. Memory Lineage Retrieved story memory must respect active lineage. A memory from an abandoned future must not appear as something that happened in the active story. Example: Discarded path: ```text Mara reveals she is a spy. ``` New active path: ```text Mara has never revealed this. ``` The memory retriever must not feed: ```text Mara is known to be a spy. ``` to the narrator merely because that fact exists in an abandoned path. This is a critical correctness requirement. ## 34. Imported Knowledge Is Different Imported Canon / Reference / Inspiration files are not normally branch-specific. They remain available across branches unless the source is explicitly campaign-state-dependent or the user disables/removes the source. Story memories and story-derived facts, by contrast, must be lineage-aware. ## 35. Scene Lineage Scene snapshots must also follow active history. A scene from an abandoned future must not become the current scene after Undo or Restore. Generated media attached to an abandoned scene may remain stored, but it should no longer be treated as current-story media. ## 36. Prompt Provenance Every generated narrator take should preserve enough information to determine: - parent story position, - user input, - selected history, - current state, - summaries used, - memories used, - imported knowledge used, - model/settings, - resulting output. This remains true even for abandoned/disposable history until it is explicitly pruned. ## 36A. Export / Import Must Preserve the Active Head Non-destructive Undo means retained history may extend beyond the current active head. Export must therefore preserve both: - the retained history/branch graph, and - the exact active branch/head position. Import must reopen the campaign at that active head. It must not infer that the newest retained turn is current merely because later history still exists. Backward compatibility may treat the retained tip as the head only for older export formats that contain no explicit head coordinate. ## 37. Failure During Retry / Edit / Continue If generation fails: - the previously accepted active history remains valid, - no partial state mutation should be committed, - no successful prior take should be lost. The user should be able to retry generation. ## 38. Atomic Acceptance A newly generated continuation should become accepted only when the application can coherently commit: - narration, - lineage, - state changes, - scene update, - provenance. A failure in state extraction should not silently leave partially applied state. Exact failure-repair handling will be specified later. ## 39. User-Facing Control Summary ### Undo Move backward one accepted story step. ### Redo Move forward again, until a new continuation is created. ### Retry Generate another narrator response to the same user input. ### Edit User Input Return to that point and create a new continuation using edited input. ### Edit Narrator Output Replace the active narration through a new auditable continuation and re-evaluate state. ### Save Checkpoint Create a durable named pointer to the current story position. ### Restore Checkpoint Return to that state; later history becomes retained disposable history. ### Correct State / Canon Explicitly change an authoritative fact without rewriting transcript prose. ## 40. Not Required in v1 UI Do not require: - branch tree visualization, - manual branch creation, - merge, - cherry-pick, - branch comparison, - branch IDs, - discarded-history browser, - automatic branch cleanup. Internal lineage may still use branch/tree structures. ## 41. Minimum v1 Undo Requirement Acceptance requirement: - at least 5 consecutive Undo operations must be supported. Preferred: - unlimited Undo across retained history. Phase 0B demonstrated that the preferred behavior is practical in the selected base. The production implementation should retain that capability while enforcing the correct campaign-root floor. ## 42. Example: Simple Mistake Initial: ```text 10: Enter tavern 11: Accuse Mara 12: Mara becomes hostile ``` User Undo x2: ```text Active head = 10 ``` User enters: ```text I ask Mara privately whether she saw anyone near my room. ``` Result: ```text 10 ├── 11A Accuse Mara │ └── 12A Mara hostile └── 11B Ask privately └── 12B New narration ``` User sees only: ```text 10 -> 11B -> 12B ``` The A path is retained but disposable. ## 43. Example: Retry ```text User: I open the airlock door. Take A: A maintenance robot is waiting. Retry Take B: The corridor beyond is filled with smoke. ``` User selects Take B and continues. Take A remains retained/disposable. ## 44. Example: Named Checkpoint ```text Checkpoint: "Before entering the alien structure" Turn 220 ``` Story continues to Turn 245. User restores checkpoint and chooses another approach. Turns 221-245 remain retained/disposable. The checkpoint remains attached to Turn 220 until explicitly deleted. ## 45. Example: Manual Canon Correction Narrator incorrectly establishes: ```text The Persephone has an FTL drive. ``` Campaign canon says: ```text FTL does not exist. ``` User corrects state/canon. The correction should be recorded explicitly and future context must treat: ```text The Persephone has no FTL capability. ``` as authoritative. If desired, the user may also edit the narration, but that is a separate operation. ## 46. Phase 0B Findings Applied Phase 0B established the following implementation facts for the selected AI-DnD base: - shipped Undo was destructive and therefore did not satisfy this document, - alternate-take Retry and branch lineage were genuinely non-destructive, - a disposable spike demonstrated head-cursor Undo/Redo without deleting accepted turns, - writes below a moved-back head can fork through existing branch machinery, - branch-scoped memory isolation remained correct with real local embeddings, - practical repeated Undo across retained history worked beyond the minimum five-step requirement, - retry/add-take paths still need to be routed through the production fork-if-behind-head rule, - abandoned history still needs explicit disposable/inactive marking, - export/import must carry the active head coordinate or it silently redoes an undone story. These findings select an implementation direction; the disposable spike itself is not production code to merge unchanged. ## 47. Acceptance Criteria The final implementation must satisfy: - Undo restores transcript and state together by moving the active head, not deleting accepted turns. - At least five Undo steps are guaranteed; the selected architecture should support Undo across all retained active-lineage history up to the root. - Redo works until a new continuation is created. - Retry preserves alternate narrator takes. - Editing old user input creates a safe new continuation. - Editing narrator output re-evaluates state. - Named checkpoints remain until explicitly deleted. - Restoring a checkpoint does not delete later history. - Checkpoint restore may reuse the existing continuation until the first divergent write. - Abandoned history is retained and marked disposable. - No automatic abandoned-history cleanup is required in v1. - Abandoned history does not influence active summaries, memories, state, or prompts. - Manual state/canon corrections are auditable. - Export/import preserves the exact active head even when retained history exists after it. - Normal UI does not require branch management. - A future discarded-history recovery/cleanup screen remains possible without schema redesign. ## 48. Selected Implementation Model Use a simple linear user experience backed by retained lineage and a movable active head. ```text USER EXPERIENCE Undo Redo Retry Edit Save Point Restore ↓ INTERNAL MODEL Parent-linked retained history Alternate takes Active branch + active head Retained branch tip/future Typed state events + snapshots/cache Disposable abandoned history Lineage-aware summaries/memory Exported active-head coordinate ``` The selected AI-DnD base supplies most of the lineage infrastructure; production work replaces destructive Undo, adds Redo/checkpoints/disposable marking, and preserves the head through export/import.