babylon.engine.observers.session_recorder

SessionRecorder observer for persistent simulation state recording.

Implements SimulationObserver protocol to persist simulation state per tick via the RuntimePersistence protocol, enabling replay, debugging, and temporal queries (ADR030/032/033 + Feature 037).

The SessionRecorder creates a comprehensive black box recording: - Node history: Entity state snapshots at each tick - Edge history: Relationship state at each tick - Events: Simulation events (uprisings, crashes, etc.) - Tick log: RNG state and mutation summary for replay

Note

As of Feature 037, SessionRecorder delegates all persistence to the RuntimePersistence protocol. This means it works natively with PostgresRuntime (production) and can still be used with RuntimeDatabase (SQLite) for lightweight dev/test scenarios.

SQLite is treated as read-only for initialization; all new writes target PostgreSQL via RuntimePersistence.persist_tick.

Usage:

from babylon.persistence.postgres_runtime import PostgresRuntime
from babylon.engine.observers.session_recorder import SessionRecorder

with PostgresRuntime(pool) as pg:
    recorder = SessionRecorder(persistence=pg, session_id=session_id)
    simulation.attach_observer(recorder)
    simulation.run(max_ticks=100)

Classes

SessionRecorder(persistence, session_id[, ...])

Observer that persists simulation state via RuntimePersistence protocol.
class babylon.engine.observers.session_recorder.SessionRecorder(persistence, session_id, tracer=None)[source]

Bases: object

Observer that persists simulation state via RuntimePersistence protocol.

Implements SimulationObserver protocol (ADR030/032/033). Records tick-by-tick state snapshots to the configured RuntimePersistence backend, enabling:

  • Replay from any point using stored state

  • Temporal queries (“state at tick 500”, “diffs between ticks”)

  • Debugging via rich mutation logs

  • Post-hoc analysis without re-running simulation

When the backend implements PostgresRuntimeExtensions, extended subsystem state (graph metadata, community state, etc.) is also persisted.

Parameters:

  • persistence (RuntimePersistence)

  • session_id (UUID)

  • tracer (TraceCollector | None)

_persistence

Backend implementing RuntimePersistence.

_session_id

Session UUID for data scoping.

_tracer

Optional trace collector for execution tracing.

_started

Whether simulation has started (for lifecycle validation).

__init__(persistence, session_id, tracer=None)[source]

Initialize the session recorder.

Parameters:

  • persistence (RuntimePersistence) – Backend implementing RuntimePersistence protocol.

  • session_id (UUID) – Session UUID for data scoping.

  • tracer (TraceCollector | None) – Optional trace collector for execution tracing.

Return type:

None

property name: str

Return observer identifier.

on_simulation_start(initial_state, config)[source]

Called when simulation begins. Initializes recording metadata.

Parameters:
Return type:

None

on_tick(previous_state, new_state)[source]

Called after each tick completes. Records new state to database.

Parameters:

  • previous_state (WorldState) – WorldState before the tick (unused, for delta analysis).

  • new_state (WorldState) – WorldState after the tick.

Return type:

None

on_simulation_end(final_state)[source]

Called when simulation ends. Finalizes recording metadata.

Parameters:

final_state (WorldState) – The final WorldState when simulation ends.

Return type:

None