babylon.engine.history.stack

Pure stack operations for the History Stack system.

All functions in this module are pure: - They take a HistoryStack as input - They return a new HistoryStack (and optionally a WorldState) - They never mutate their inputs

This enables functional transformation patterns:

new_stack = push_state(old_stack, state) new_stack, previous_state = undo(old_stack)

Sprint B: Stack operations for Phase 3 persistence layer.

Functions

get_current_state(history)	Get the state at the current position.
get_state_at_tick(history, tick)	Get the state for a specific tick.
protect_tick(history, tick)	Mark a tick as protected (cannot be pruned).
prune_history(history, keep_count)	Remove old entries, keeping the most recent ones.
push_state(history, state)	Add a new state to the history stack.
redo(history)	Move forward one state in history.
undo(history)	Move back one state in history.

babylon.engine.history.stack.push_state(history, state)

Add a new state to the history stack.

Behavior: - If current_index is not at the end, truncates future entries (linear timeline) - Enforces max_depth by pruning oldest non-protected entries - Returns new stack with state added

Parameters:

• history (HistoryStack) – The current history stack.

• state (WorldState) – The WorldState to add.

Return type:

HistoryStack

Returns:

New HistoryStack with the state added.

babylon.engine.history.stack.undo(history)

Move back one state in history.

Behavior: - Returns the previous state (one before current) - Preserves all entries for potential redo - Returns None if at start or empty

Parameters:

history (HistoryStack) – The current history stack.

Return type:

tuple[HistoryStack, WorldState | None]

Returns:

Tuple of (new stack, previous state or None).

babylon.engine.history.stack.redo(history)

Move forward one state in history.

Behavior: - Returns the next state (one after current) - Returns None if at end or empty

Parameters:

history (HistoryStack) – The current history stack.

Return type:

tuple[HistoryStack, WorldState | None]

Returns:

Tuple of (new stack, next state or None).

babylon.engine.history.stack.get_current_state(history)

Get the state at the current position.

Parameters:

history (HistoryStack) – The history stack.

Return type:

WorldState | None

Returns:

Current WorldState or None if stack is empty.

babylon.engine.history.stack.get_state_at_tick(history, tick)

Get the state for a specific tick.

Parameters:

• history (HistoryStack) – The history stack.

• tick (int) – The tick number to find.

Return type:

WorldState | None

Returns:

WorldState at that tick or None if not found.

babylon.engine.history.stack.prune_history(history, keep_count)

Remove old entries, keeping the most recent ones.

Behavior: - Keeps the most recent keep_count entries - Protected ticks are never pruned (even if that exceeds keep_count) - Adjusts current_index to point to the same tick

Parameters:

• history (HistoryStack) – The history stack.

• keep_count (int) – Number of recent entries to keep.

Return type:

HistoryStack

Returns:

New HistoryStack with pruned entries.

babylon.engine.history.stack.protect_tick(history, tick)

Mark a tick as protected (cannot be pruned).

Parameters:

• history (HistoryStack) – The history stack.

• tick (int) – The tick number to protect.

Return type:

HistoryStack

Returns:

New HistoryStack with the tick protected.