babylon.engine.history.models

Pydantic models for the History Stack system.

These models provide: - CheckpointMetadata: Context for saved checkpoints (timestamp, tick, description) - Checkpoint: Full state bundle (metadata + WorldState + SimulationConfig) - HistoryEntry: Single state snapshot for the history stack - HistoryStack: Immutable stack of history entries with undo/redo support - CheckpointConfig: Configuration for auto-checkpointing

All models are frozen (immutable) for functional transformation patterns. The state is pure data; transformations create new instances.

Sprint A: History Stack models for Phase 3 persistence layer.

Classes

`Checkpoint`(**data)	Complete checkpoint bundle for save/load.
`CheckpointConfig`(**data)	Configuration for auto-checkpointing behavior.
`CheckpointMetadata`(**data)	Metadata for a saved checkpoint.
`HistoryEntry`(**data)	Single entry in the history stack.
`HistoryStack`(**data)	Immutable history stack for undo/redo operations.

class babylon.engine.history.models.CheckpointMetadata(**data)[source]

Bases: BaseModel

Metadata for a saved checkpoint.

Captures context about when and why a checkpoint was created. Used for checkpoint listing and identification.

Parameters:

created_at (datetime)
tick (Annotated[int, Ge(ge=0)])
description (str)
version (str)

created_at: UTC timestamp when the checkpoint was created.

tick: The simulation tick at checkpoint time.

description: Optional human-readable description of the checkpoint.

version: Schema version for compatibility checking.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

created_at: datetime

tick: int

description: str

version: str

class babylon.engine.history.models.Checkpoint(**data)[source]

Bases: BaseModel

Complete checkpoint bundle for save/load.

Contains everything needed to fully restore simulation state: - Metadata for identification and context - WorldState with all entities and relationships - SimulationConfig with all formula coefficients

Parameters:

metadata (CheckpointMetadata)
state (WorldState)
config (SimulationConfig)

metadata: Checkpoint identification and context.

state: The WorldState snapshot.

config: The SimulationConfig active at checkpoint time.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

metadata: CheckpointMetadata

state: WorldState

config: SimulationConfig

class babylon.engine.history.models.HistoryEntry(**data)[source]

Bases: BaseModel

Single entry in the history stack.

Represents one state snapshot with its tick number. Used by the history stack for undo/redo operations.

Parameters:

tick (int)
state (WorldState)

tick: The simulation tick for this state.

state: The WorldState snapshot.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

tick: int

state: WorldState

class babylon.engine.history.models.HistoryStack(**data)[source]

Bases: BaseModel

Immutable history stack for undo/redo operations.

Maintains a list of history entries with a current position indicator. All operations return new HistoryStack instances (functional pattern).

The stack supports: - Linear timeline (push after undo truncates future) - Protected ticks that survive pruning - Configurable maximum depth

Parameters:

entries (list[HistoryEntry])
current_index (int)
max_depth (Annotated[int, Gt(gt=0)])
protected_ticks (frozenset[int])

entries: List of history entries (oldest first).

current_index: Index of current state (-1 if empty).

max_depth: Maximum number of entries to retain.

protected_ticks: Tick numbers that cannot be pruned.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

entries: list[HistoryEntry]

current_index: int

max_depth: int

protected_ticks: frozenset[int]

class babylon.engine.history.models.CheckpointConfig(**data)[source]

Bases: BaseModel

Configuration for auto-checkpointing behavior.

Controls when and where checkpoints are automatically created.

Parameters:

enabled (bool)
interval (Annotated[int, Gt(gt=0)])
checkpoint_dir (str)
max_checkpoints (Annotated[int, Ge(ge=0)])

enabled: Whether auto-checkpointing is enabled.

interval: Number of ticks between auto-checkpoints.

checkpoint_dir: Directory path for checkpoint files.

max_checkpoints: Maximum checkpoints to retain (0 = unlimited).

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

enabled: bool

interval: int

checkpoint_dir: str

max_checkpoints: int