feat(app): define trusted rewind branch flow

crates/nana-contracts/src/main.rs

@@ -6,15 +6,16 @@ use std::{
 use nana_domain::{
     AcquisitionMode, ActionSuggestion, AppInfo, BeatKind, CharacterCard, CharacterJudgmentRule,
     CharacterStyle, CheckDifficulty, CheckRecord, CheckResult, ClockState, DemoPackSummary,
-    HistoryNodeView, ItemAcquisition, ItemInstance, ItemMechanics, ItemPlacement, ItemSpec,
-    KnowledgeCertainty, KnowledgeRecord, Persona, PlayerItemView, PlayerKnowledgeView,
-    PlayerPromiseView, PlayerView, PlotEvent, PlotModule, PlotOutcome, PlotPressure,
-    PresentationBeat, PresentationCharacter, PresentationScene, PresentationSnapshot, Promise,
-    PromiseStatus, PromiseWeight, RelationshipAdjustment, RelationshipAxes, RelationshipBand,
-    RelationshipDimension, RelationshipState, RelationshipView, ResourceBundle, ResourceHeader,
-    ResourceId, ResourceKind, ResourceRef, RuntimeState, SkillValue, StateDelta, StateOp, Story,
-    StoryBinding, StoryNode, TurnFailure, TurnFailureCode, TurnIntent, TurnRequest, TurnResult,
-    ValidationCode, ValidationIssue, ValidationReport, VisualDirective, WorldBook, WorldBookEntry,
+    ForkBranchRequest, ForkBranchResult, HistoryNodeView, ItemAcquisition, ItemInstance,
+    ItemMechanics, ItemPlacement, ItemSpec, KnowledgeCertainty, KnowledgeRecord, Persona,
+    PlayerItemView, PlayerKnowledgeView, PlayerPromiseView, PlayerView, PlotEvent, PlotModule,
+    PlotOutcome, PlotPressure, PresentationBeat, PresentationCharacter, PresentationScene,
+    PresentationSnapshot, Promise, PromiseStatus, PromiseWeight, RelationshipAdjustment,
+    RelationshipAxes, RelationshipBand, RelationshipDimension, RelationshipState, RelationshipView,
+    ResourceBundle, ResourceHeader, ResourceId, ResourceKind, ResourceRef, RuntimeState,
+    SkillValue, StateDelta, StateOp, Story, StoryBinding, StoryNode, TurnFailure, TurnFailureCode,
+    TurnIntent, TurnRequest, TurnResult, ValidationCode, ValidationIssue, ValidationReport,
+    VisualDirective, WorldBook, WorldBookEntry,
 };
 use schemars::{JsonSchema, schema_for};
 use serde::Serialize;
@@ -71,6 +72,8 @@ fn generated_outputs(root: &Path) -> Result<GeneratedOutputs, Box<dyn std::error
     add_schema::<PlayerView>(&mut outputs, &schema_dir, "player-view")?;
     add_schema::<TurnRequest>(&mut outputs, &schema_dir, "turn-request")?;
     add_schema::<TurnResult>(&mut outputs, &schema_dir, "turn-result")?;
+    add_schema::<ForkBranchRequest>(&mut outputs, &schema_dir, "fork-branch-request")?;
+    add_schema::<ForkBranchResult>(&mut outputs, &schema_dir, "fork-branch-result")?;
     add_schema::<TurnFailure>(&mut outputs, &schema_dir, "turn-failure")?;
     add_schema::<AppInfo>(&mut outputs, &schema_dir, "app-info")?;
     add_schema::<DemoPackSummary>(&mut outputs, &schema_dir, "demo-pack-summary")?;
@@ -134,6 +137,8 @@ fn generated_outputs(root: &Path) -> Result<GeneratedOutputs, Box<dyn std::error
         TurnIntent::decl(),
         TurnRequest::decl(),
         TurnResult::decl(),
+        ForkBranchRequest::decl(),
+        ForkBranchResult::decl(),
         TurnFailureCode::decl(),
         TurnFailure::decl(),
         AppInfo::decl(),

crates/nana-domain/src/lib.rs

@@ -720,6 +720,31 @@ pub struct TurnRequest {
     pub input: String,
 }
 
+/// Requests a new playable branch rooted at an already committed story node.
+///
+/// The caller identifies the branch head it observed so the trusted runtime can
+/// reject a rewind racing with a newer turn. The new branch id is generated by
+/// the runtime from these trusted inputs and is never supplied by the UI or the
+/// model.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(rename_all = "camelCase")]
+pub struct ForkBranchRequest {
+    pub story_id: String,
+    pub current_branch_id: String,
+    pub expected_current_node_id: String,
+    pub source_node_id: String,
+    pub action_id: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(rename_all = "camelCase")]
+pub struct ForkBranchResult {
+    pub branch_id: String,
+    pub player_view: PlayerView,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema, TS)]
 #[serde(rename_all = "camelCase")]
 #[ts(rename_all = "camelCase")]