objectstate.snapshot_model

Snapshot and Timeline dataclasses for git-like time-travel history.

This module provides typed data structures for the ObjectStateRegistry’s time-travel system, replacing the tuple-based implementation.

Design Philosophy: Correct by Construction - No Optional fields for required data - Immutable snapshots (frozen dataclass) - UUID-based identity for snapshots - Direct attribute access (no getattr fallbacks)

Classes

Snapshot(id, timestamp, label, ...)	Immutable snapshot of ALL ObjectStates at a point in time.
StateSnapshot(saved_resolved, live_resolved, ...)	Immutable snapshot of a single ObjectState's data.
Timeline(name, head_id, base_id, created_at, ...)	Named branch of history - analogous to a git branch.

class objectstate.snapshot_model.StateSnapshot(saved_resolved: Dict, live_resolved: Dict, parameters: Dict, saved_parameters: Dict, provenance: Dict, meta: Dict = <factory>)

Immutable snapshot of a single ObjectState’s data.

Captures the resolved values, parameters, and provenance at a point in time. No object references - data only for serializability.

saved_resolved: Dict

live_resolved: Dict

parameters: Dict

saved_parameters: Dict

provenance: Dict

meta: Dict

__init__(saved_resolved: Dict, live_resolved: Dict, parameters: Dict, saved_parameters: Dict, provenance: Dict, meta: Dict = <factory>) → None

class objectstate.snapshot_model.Snapshot(id: str, timestamp: float, label: str, triggering_scope: str | None, parent_id: str | None, all_states: Dict[str, StateSnapshot])

Immutable snapshot of ALL ObjectStates at a point in time.

Analogous to a git commit - captures the entire system state.

id: str

timestamp: float

label: str

triggering_scope: str | None

parent_id: str | None

all_states: Dict[str, StateSnapshot]

classmethod create(label: str, all_states: Dict[str, StateSnapshot], triggering_scope: str | None = None, parent_id: str | None = None) → Snapshot

Create a new snapshot with auto-generated ID and timestamp.

to_dict() → Dict

Export to JSON-serializable dict.

classmethod from_dict(data: Dict) → Snapshot

Import from dict (e.g., loaded from JSON).

__init__(id: str, timestamp: float, label: str, triggering_scope: str | None, parent_id: str | None, all_states: Dict[str, StateSnapshot]) → None

class objectstate.snapshot_model.Timeline(name: str, head_id: str, base_id: str, created_at: float = <factory>, description: str = '')

Named branch of history - analogous to a git branch.

Points to a head snapshot and tracks its base (branch point).

name: str

head_id: str

base_id: str

created_at: float

description: str = ''

to_dict() → Dict

Export to JSON-serializable dict.

classmethod from_dict(data: Dict) → Timeline

Import from dict.

__init__(name: str, head_id: str, base_id: str, created_at: float = <factory>, description: str = '') → None