babylon.kernel.sim_clock

Deterministic simulation clock (Constitution III.7).

Maps a weekly tick to a canonical in-world datetime so timestamps are a pure function of tick, never of wall clock. Year mapping mirrors FR-013 (year = start_year + tick // 52 — see babylon.config.defines.cross_scale and the headless bridge, which uses the same 2010 epoch). Kept as a top-level leaf module so both the engine (event_bus/interceptor, which must not import the heavy babylon.models package) and babylon.models.events can import it without cycles.

Module Attributes

`SIM_EPOCH_YEAR`	FR-013 epoch year — tick 0 falls on Jan 1 of this year (UTC).
`WEEKS_PER_YEAR`	52 ticks per simulated year (FR-013).
`UNSET_TIMESTAMP`	Sentinel meaning "derive from tick" — frozen dataclass/model defaults cannot see sibling fields, so construction sites leave this in place and `__post_init__` / the before-validator replaces it.

Functions

sim_datetime(tick)

Return the deterministic in-world datetime for tick.

babylon.kernel.sim_clock.SIM_EPOCH_YEAR: Final[int] = 2010: FR-013 epoch year — tick 0 falls on Jan 1 of this year (UTC).

babylon.kernel.sim_clock.WEEKS_PER_YEAR: Final[int] = 52

52 ticks per simulated year (FR-013).

Type:: Weekly-tick calendar

babylon.kernel.sim_clock.UNSET_TIMESTAMP: Final[datetime] = datetime.datetime(1, 1, 1, 0, 0, tzinfo=datetime.timezone.utc): Sentinel meaning “derive from tick” — frozen dataclass/model defaults cannot see sibling fields, so construction sites leave this in place and __post_init__ / the before-validator replaces it.

babylon.kernel.sim_clock.sim_datetime(tick)[source]

Return the deterministic in-world datetime for tick.

The mapping is a pure function of tick (Constitution III.7): tick 0 is Jan 1 of SIM_EPOCH_YEAR (UTC); each tick advances one week, rolling the year every WEEKS_PER_YEAR ticks per FR-013.

Parameters:: tick (int) – Simulation tick (0-indexed, weekly).
Return type:: datetime
Returns:: Timezone-aware UTC datetime for the tick.
Raises:: ValueError – If tick is negative.

Example

>>> from babylon.kernel.sim_clock import sim_datetime
>>> sim_datetime(0).isoformat()
'2010-01-01T00:00:00+00:00'
>>> sim_datetime(52).year
2011