Merge pull request #38 from CurtisTechSolutions/feat/complete-replay-bundles

feat: include events and authorized reconstruction inputs in replay bundles

Author: nosam1998

README.md

@@ -77,3 +77,10 @@ event to the authorized player or spectator: private actions, reasoning, chance
 events, match seeds, and internal fork permissions are omitted when unauthorized.
 Own reasoning is available immediately; other reasoning in perfect-information
 games becomes available after completion.
+
+Full replay bundles include the game/version, normalized config, event revision,
+projected events (including reasoning and controls), and reconstructed per-turn
+observations. Authorized in-process omniscient exports also include the initial
+engine state and RNG seed, so custom starts and forked histories can be rebuilt
+exactly. The ordinary REST views omit those private inputs. Full responses have
+a 16 MiB budget; larger histories remain available through paginated events.

crates/apps/gfa-server/src/event_tests.rs

@@ -112,3 +112,51 @@ async fn event_http_pages_round_trip_across_restart_and_redact_internal_fork_met
     reopened.store.close().await;
     Ok(())
 }
+
+#[tokio::test]
+async fn replay_bundle_matches_paged_events_without_exposing_private_inputs(
+) -> Result<(), ServerError> {
+    let directory = tempfile::tempdir()?;
+    let app = fixture(&config(&directory)).await?;
+    let (_, created) = call(
+        &app.router,
+        "POST",
+        "/v1/matches",
+        json!({"game_id":"tictactoe","seed":42}),
+        None,
+    )
+    .await?;
+    let id = created["match_id"].as_str().ok_or("id")?;
+    call(
+        &app.router,
+        "POST",
+        &format!("/v1/matches/{id}/actions"),
+        json!({"seat":0,"turn":0,"action":"r2c2","reasoning":"Center"}),
+        None,
+    )
+    .await?;
+    let (_, replay) = call(
+        &app.router,
+        "GET",
+        &format!("/v1/matches/{id}/replay?seat=0"),
+        Value::Null,
+        None,
+    )
+    .await?;
+    let (_, page) = call(
+        &app.router,
+        "GET",
+        &format!("/v1/matches/{id}/events?seat=0"),
+        Value::Null,
+        None,
+    )
+    .await?;
+    assert_eq!(replay["game_id"], "tictactoe");
+    assert_eq!(replay["revision"], page["revision"]);
+    assert_eq!(replay["events"], page["events"]);
+    assert!(replay["config"].is_object());
+    assert!(replay.get("seed").is_none() && replay.get("initial_state").is_none());
+    assert!(replay["events"][0].get("initial_state").is_none());
+    app.store.close().await;
+    Ok(())
+}

crates/domain/gfa-api-types/src/events.rs

@@ -51,6 +51,9 @@ pub enum EventData {
         /// RNG seed, disclosed only to an explicitly authorized omniscient caller.
         #[serde(skip_serializing_if = "Option::is_none")]
         seed: Option<u64>,
+        /// Complete starting state, disclosed only to an authorized omniscient caller.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        initial_state: Option<Value>,
         /// Player assignments.
         seats: Vec<Seat>,
         /// Recorded assistance policy.

crates/domain/gfa-api-types/src/lib.rs

@@ -123,6 +123,21 @@ pub struct MoveResult {
 #[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
 pub struct Replay {
+    /// Registered game identifier needed to load this replay.
+    pub game_id: String,
+    /// Canonical public engine configuration.
+    pub config: Value,
+    /// Initial game RNG seed, available only to authorized omniscient callers.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub seed: Option<u64>,
+    /// Complete initial engine state, including a fork's local starting position.
+    /// Only authorized omniscient callers receive this field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub initial_state: Option<Value>,
+    /// Event count in this consistent replay snapshot.
+    pub revision: u64,
+    /// Viewer-scoped recorded facts, including controls and reasoning.
+    pub events: Vec<RecordedEvent>,
     /// Stable match identifier.
     pub match_id: String,
     /// Engine version used to reconstruct this replay.

crates/domain/gfa-service/src/events.rs

@@ -1,5 +1,5 @@
 //! Event projection is a domain operation shared by every transport.
-use crate::{error, replay, AppliedAction, GameService, MatchEvent};
+use crate::{error, replay, AppliedAction, GameService, MatchEvent, MatchRecord};
 use gfa_api_types::{ApiError, EventData, EventPage, EventsQuery, RecordedEvent};
 use gfa_core::{Information, Viewer};
 
@@ -30,12 +30,6 @@ impl GameService {
         }
         let record = self.record(id).await?;
         let rebuilt = replay::reconstruct(&self.registry, &record)?;
-        let origin = record.origin().ok_or_else(error::corrupt)?;
-        let initial = replay::initial(rebuilt.game.as_ref(), origin)?.project(
-            id,
-            rebuilt.game.as_ref(),
-            viewer,
-        )?;
         let start = match query.since {
             Some(sequence) if sequence < record.events.len() as u64 => sequence as usize + 1,
             Some(_) => {
@@ -50,55 +44,13 @@ impl GameService {
         let end = start
             .saturating_add(query.limit as usize)
             .min(record.events.len());
-        let perfect = rebuilt.game.spec().information == Information::Perfect;
-        let finished = rebuilt.current()?.ended();
-        let mut events = Vec::new();
-        for (offset, event) in record.events[start..end].iter().enumerate() {
-            let event = match event {
-                MatchEvent::MatchCreated(origin) => EventData::Created {
-                    game_id: origin.game_id.clone(),
-                    engine_version: origin.engine_version.clone(),
-                    config: rebuilt
-                        .game
-                        .normalize_config(&origin.config)
-                        .map_err(error::engine)?,
-                    seed: (viewer == Viewer::Omniscient).then_some(origin.seed),
-                    seats: crate::seats::assignments(origin, initial.returns.len()),
-                    assists: origin.assists.clone(),
-                    initial: Box::new(initial.clone()),
-                    at_ms: origin.created_at_ms,
-                },
-                MatchEvent::Action(action) => project_action(action, viewer, perfect, finished)?,
-                MatchEvent::ForkedFrom { source, .. } => EventData::ForkedFrom {
-                    source: source.clone(),
-                },
-                MatchEvent::Resigned { turn, seat, at_ms } => EventData::Resigned {
-                    turn: *turn,
-                    seat: *seat,
-                    at_ms: *at_ms,
-                },
-                MatchEvent::DrawOffered { turn, seat, at_ms } => EventData::DrawOffered {
-                    turn: *turn,
-                    seat: *seat,
-                    at_ms: *at_ms,
-                },
-                MatchEvent::MatchFinished {
-                    turn,
-                    returns,
-                    terminated,
-                    truncated,
-                } => EventData::Finished {
-                    turn: *turn,
-                    returns: returns.clone(),
-                    terminated: *terminated,
-                    truncated: *truncated,
-                },
-            };
-            events.push(RecordedEvent {
-                sequence: (start + offset) as u64,
-                event,
-            });
-        }
+        let events = project(
+            &record,
+            &rebuilt,
+            viewer,
+            start..end,
+            &mut ReplayBudget::default(),
+        )?;
         Ok(EventPage {
             match_id: id.into(),
             revision: record.events.len() as u64,
@@ -151,3 +103,107 @@ fn project_action(
         at_ms: action.accepted_at_ms,
     })
 }
+
+/// Bound the full bundle while paginated events remain available for large histories.
+pub(crate) struct ReplayBudget {
+    remaining: usize,
+}
+
+impl Default for ReplayBudget {
+    fn default() -> Self {
+        Self {
+            remaining: 16 * 1024 * 1024 - 4096,
+        }
+    }
+}
+
+impl ReplayBudget {
+    pub(crate) fn include(&mut self, value: &impl serde::Serialize) -> Result<(), ApiError> {
+        let size = serde_json::to_vec(value)
+            .map_err(|e| error::engine(e.into()))?
+            .len()
+            .saturating_add(2);
+        self.remaining = self.remaining.checked_sub(size).ok_or_else(|| {
+            ApiError::new(
+                "REPLAY_TOO_LARGE",
+                "Replay exceeds the 16 MiB response budget",
+                "Read paginated /events to export this history in bounded chunks.",
+            )
+        })?;
+        Ok(())
+    }
+}
+
+pub(crate) fn project(
+    record: &MatchRecord,
+    rebuilt: &replay::Reconstructed,
+    viewer: Viewer,
+    range: std::ops::Range<usize>,
+    budget: &mut ReplayBudget,
+) -> Result<Vec<RecordedEvent>, ApiError> {
+    let first = rebuilt.frames.first().ok_or_else(error::corrupt)?;
+    // Same-turn controls only change Frame metadata. The engine state at index
+    // zero remains the pristine start, so no second puzzle generation is needed.
+    let initial = replay::Frame {
+        state: first.state.clone(),
+        turn: 0,
+        terminated: false,
+        truncated: false,
+        outcome: None,
+        draw_offer: None,
+    }
+    .project(&record.id, rebuilt.game.as_ref(), viewer)?;
+    let perfect = rebuilt.game.spec().information == Information::Perfect;
+    let finished = rebuilt.current()?.ended();
+    let mut events = Vec::new();
+    for (offset, event) in record.events[range.clone()].iter().enumerate() {
+        let event = match event {
+            MatchEvent::MatchCreated(origin) => EventData::Created {
+                game_id: origin.game_id.clone(),
+                engine_version: origin.engine_version.clone(),
+                config: rebuilt
+                    .game
+                    .normalize_config(&origin.config)
+                    .map_err(error::engine)?,
+                seed: (viewer == Viewer::Omniscient).then_some(origin.seed),
+                initial_state: (viewer == Viewer::Omniscient).then(|| first.state.clone()),
+                seats: crate::seats::assignments(origin, initial.returns.len()),
+                assists: origin.assists.clone(),
+                initial: Box::new(initial.clone()),
+                at_ms: origin.created_at_ms,
+            },
+            MatchEvent::Action(action) => project_action(action, viewer, perfect, finished)?,
+            MatchEvent::ForkedFrom { source, .. } => EventData::ForkedFrom {
+                source: source.clone(),
+            },
+            MatchEvent::Resigned { turn, seat, at_ms } => EventData::Resigned {
+                turn: *turn,
+                seat: *seat,
+                at_ms: *at_ms,
+            },
+            MatchEvent::DrawOffered { turn, seat, at_ms } => EventData::DrawOffered {
+                turn: *turn,
+                seat: *seat,
+                at_ms: *at_ms,
+            },
+            MatchEvent::MatchFinished {
+                turn,
+                returns,
+                terminated,
+                truncated,
+            } => EventData::Finished {
+                turn: *turn,
+                returns: returns.clone(),
+                terminated: *terminated,
+                truncated: *truncated,
+            },
+        };
+        let projected = RecordedEvent {
+            sequence: (range.start + offset) as u64,
+            event,
+        };
+        budget.include(&projected)?;
+        events.push(projected);
+    }
+    Ok(events)
+}

crates/domain/gfa-service/src/service.rs

@@ -312,16 +312,51 @@ impl GameService {
     pub async fn get_replay(&self, id: &str, viewer: Viewer) -> Result<Replay, ApiError> {
         let record = self.record(id).await?;
         let replay = replay::reconstruct(&self.registry, &record)?;
-        let states = replay
-            .frames
-            .iter()
-            .map(|frame| frame.project(id, replay.game.as_ref(), viewer))
-            .collect::<Result<Vec<_>, _>>()?;
+        let origin = record.origin().ok_or_else(error::corrupt)?;
+        let config = replay
+            .game
+            .normalize_config(&origin.config)
+            .map_err(error::engine)?;
+        let mut budget = crate::events::ReplayBudget::default();
+        budget.include(&config)?;
+        let initial_state = if viewer == Viewer::Omniscient {
+            let state = replay
+                .frames
+                .first()
+                .ok_or_else(error::corrupt)?
+                .state
+                .clone();
+            budget.include(&state)?;
+            Some(state)
+        } else {
+            None
+        };
+        let mut states = Vec::new();
+        for frame in &replay.frames {
+            let state = frame.project(id, replay.game.as_ref(), viewer)?;
+            budget.include(&state)?;
+            states.push(state);
+        }
+        let events = crate::events::project(
+            &record,
+            &replay,
+            viewer,
+            0..record.events.len(),
+            &mut budget,
+        )?;
+        let ancestors = self.fork_ancestors(&record).await?;
+        budget.include(&ancestors)?;
         Ok(Replay {
+            game_id: origin.game_id.clone(),
+            config,
+            seed: (viewer == Viewer::Omniscient).then_some(origin.seed),
+            initial_state,
+            revision: record.events.len() as u64,
+            events,
             match_id: id.into(),
             engine_version: replay.game.spec().engine_version,
             states,
-            ancestors: self.fork_ancestors(&record).await?,
+            ancestors,
         })
     }