Feature: Graph State Update Modes, Serialization, StateManager, and Time Travel
  As a developer
  I want graph states to support replace, merge, and append update modes, serialize to dict, checkpoint, and support time travel
  So that state management is consistent across persistence boundaries and supports audit trails

  Background:
    Given the state management system is available

  Scenario: GraphState replace update mode
    Given I have a GraphState instance
    And I have updates with replace mode
    When I update the state with REPLACE mode
    Then the state should be replaced completely
    And only valid attributes should be updated

  Scenario: GraphState merge update mode with dictionaries
    Given I have a GraphState with existing metadata
    And I have dictionary updates for merge mode
    When I update the state with MERGE mode
    Then dictionaries should be merged properly
    And existing values should be preserved

  Scenario: GraphState merge update mode with lists
    Given I have a GraphState with existing messages
    And I have list updates for merge mode
    When I update the state with MERGE mode
    Then lists should be extended properly
    And existing messages should be preserved

  Scenario: GraphState merge update mode with simple values
    Given I have a GraphState with simple values
    And I have simple value updates
    When I update the state with MERGE mode
    Then simple values should be replaced

  Scenario: GraphState append update mode with lists
    Given I have a GraphState with existing list data
    And I have new items to append
    When I update the state with APPEND mode
    Then items should be appended to lists
    And single items should be appended as well

  Scenario: GraphState to_dict conversion
    Given I have a GraphState with various data
    When I convert the state to dictionary
    Then all fields should be present in the dictionary
    And the dictionary should match expected structure

  Scenario: GraphState from_dict creation
    Given I have a state dictionary
    When I create a GraphState from the dictionary
    Then the GraphState should have correct field values
    And all data should be properly initialized

  Scenario: StateManager with checkpoint directory creation
    Given I specify a checkpoint directory path
    When I create a StateManager with checkpointing
    Then the checkpoint directory should be created
    And checkpointing should be enabled

  Scenario: StateManager time travel disabled
    Given I create a StateManager without time travel
    When I try to use time travel functionality
    Then time travel should return None
    And no history should be maintained

  Scenario: StateManager history trimming
    Given I have a StateManager with time travel enabled
    And I set a small max history size
    When I make many state updates
    Then the history should be trimmed to max size
    And older snapshots should be removed

  Scenario: StateManager checkpoint saving
    Given I have a StateManager with checkpointing enabled
    And I set a small checkpoint interval
    When I make multiple state updates
    Then checkpoints should be saved automatically
    And checkpoint files should be created

  Scenario: StateManager checkpoint loading
    Given I have a StateManager with a checkpoint file
    When I load the checkpoint
    Then the state should be restored from checkpoint
    And the update count should be restored
    And the state stream should emit the loaded state

  Scenario: StateManager latest checkpoint detection
    Given I have multiple checkpoint files
    When I get the latest checkpoint
    Then the most recent checkpoint should be returned
    And it should be based on file modification time

  Scenario: StateManager latest checkpoint with no files
    Given I have a checkpoint directory with no files
    When I get the latest checkpoint from empty directory
    Then None should be returned for latest checkpoint

  Scenario: StateManager time travel functionality
    Given I have a StateManager with time travel enabled
    And I have made several state updates
    When I travel back in time
    Then the state should revert to previous version
    And the state stream should emit the historical state

  Scenario: StateManager time travel beyond history
    Given I have a StateManager with limited history
    When I try to travel back more steps than available
    Then it should travel back to the earliest available state
    And time travel should not cause errors

  Scenario: StateManager get state observable
    Given I have a StateManager
    When I get the state observable
    Then it should return an RxPy observable
    And it should emit state changes

  Scenario: StateManager clear history
    Given I have a StateManager with some history
    When I clear the history
    Then the history should be empty
    And time travel should not be possible

  Scenario: StateManager reset functionality
    Given I have a StateManager with modified state
    When I reset the state manager
    Then the state should return to initial values
    And the update count should reset to zero
    And the history should be cleared
    And the state stream should emit the reset state

  Scenario: StateManager reset with custom initial state
    Given I have a StateManager
    And I have a custom initial state
    When I reset with the custom initial state
    Then the state should match the custom initial state
    And all counters should be reset