babylon.engine.invariants

Invariant protocol and concrete invariants for the simulation engine.

Spec 040, Discipline 1: Invariants as First-Class Objects.

Every invariant in the constitution becomes an object implementing the Invariant protocol. Systems declare which invariants they preserve, and the test harness checks them automatically via Hypothesis.

Usage:

from babylon.engine.invariants import NonNegativeWealth, Invariant

class VolumeOneProduction:
    invariants: ClassVar[list[Invariant]] = [NonNegativeWealth()]

    def step(self, state: WorldState) -> Result[WorldState, TransitionError]:
        ...

Classes

`HeatNonNegativity`()	Territory heat fields must be >= 0 everywhere.
`Invariant`(args, *kwargs)	Protocol for simulation invariants.
`InvariantResult`(passed[, msg])	Outcome of an invariant check.
`NonNegativeWealth`()	No entity has negative wealth after a system step.

class babylon.engine.invariants.InvariantResult(passed, msg='')[source]

Bases: object

Outcome of an invariant check.

Use factory methods InvariantResult.ok() and InvariantResult.violated(msg) rather than constructing directly.

Parameters:

passed (bool)
msg (str)

passed: True if the invariant holds, False if violated.

msg: Descriptive message (empty on success, diagnosis on failure).

passed: bool

msg: str = ''

property ok: bool: Whether the invariant check passed.

classmethod success()[source]

Create a passing result.

Return type:: InvariantResult
Returns:: InvariantResult with passed=True.

classmethod violated(msg)[source]

Create a failing result with a diagnosis message.

Parameters:: msg (str) – Description of the invariant violation.
Return type:: InvariantResult
Returns:: InvariantResult with passed=False.

__init__(passed, msg='')

Parameters:

passed (bool)
msg (str)

Return type:

None

class babylon.engine.invariants.Invariant(*args, **kwargs)[source]

Bases: Protocol

Protocol for simulation invariants.

Every constitution invariant becomes an object implementing this protocol. Systems declare which invariants they preserve via a class-level list. The test harness runs declared invariants on (pre, post) state pairs.

property name: str: Unique identifier for this invariant.

check(pre, post)[source]

Verify the invariant holds between pre and post states.

Parameters:

pre (WorldState) – WorldState before system step.
post (WorldState) – WorldState after system step.

Return type:

InvariantResult

Returns:

InvariantResult indicating pass or violation.

__init__(*args, **kwargs)

class babylon.engine.invariants.NonNegativeWealth[source]

Bases: object

No entity has negative wealth after a system step.

This invariant checks all social_class entities in the post-state and fails if any have wealth < 0.

property name: str: Invariant identifier.

check(_pre, post)[source]

Check that no entity wealth is negative.

Parameters:

_pre (WorldState) – WorldState before step (unused for this invariant).
post (WorldState) – WorldState after step.

Return type:

InvariantResult

Returns:

InvariantResult — violated if any entity has wealth < 0.

class babylon.engine.invariants.HeatNonNegativity[source]

Bases: object

Territory heat fields must be >= 0 everywhere.

Heat represents state repressive attention. Negative heat is physically meaningless.

property name: str: Invariant identifier.

check(_pre, post)[source]

Check that no territory has negative heat.

Parameters:

_pre (WorldState) – WorldState before step (unused for this invariant).
post (WorldState) – WorldState after step.

Return type:

InvariantResult

Returns:

InvariantResult — violated if any territory has heat < 0.