babylon.engine.errors

Transition error types for the simulation engine.

Spec 040, Discipline 2: Closed union of known failure modes.

TransitionError is a union of all modeled failure types that a system step can produce. These represent expected domain failures — negative capital, insufficient labor hours, missing organizations — not programmer errors.

Exceptions (assert, KeyError) remain for “this should be unreachable.” Result[WorldState, TransitionError] for “this is a modeled outcome.”

Module Attributes

TransitionError

Closed union of all modeled transition failures.

Classes

ConservationViolation(invariant_name, ...)

A conservation law was violated (defensive check before invariant harness).

InfeasibleMigration(node_id, from_territory, ...)

A migration between territories is not possible.

InsufficientLaborHours(node_id, required, ...)

A production plan requires more labor hours than available.

MissingOrganization(org_id)

An action references an organization that does not exist in state.

NegativeCapitalStock(node_id, field, value)

A node's capital stock went negative after a system step.
class babylon.engine.errors.NegativeCapitalStock(node_id, field, value)[source]

Bases: object

A node’s capital stock went negative after a system step.

Parameters:

  • node_id (str) – The entity that has negative capital.

  • field (str) – Which field went negative (e.g., "wealth").

  • value (float) – The negative value.

node_id: str
field: str
value: float
__init__(node_id, field, value)
Parameters:
Return type:

None

class babylon.engine.errors.InsufficientLaborHours(node_id, required, available)[source]

Bases: object

A production plan requires more labor hours than available.

Parameters:

  • node_id (str) – The entity that lacks labor hours.

  • required (float) – Hours needed for the production run.

  • available (float) – Hours actually available.

node_id: str
required: float
available: float
__init__(node_id, required, available)
Parameters:
Return type:

None

class babylon.engine.errors.MissingOrganization(org_id)[source]

Bases: object

An action references an organization that does not exist in state.

Parameters:

org_id (str) – The organization ID that was not found.

org_id: str
__init__(org_id)
Parameters:

org_id (str)

Return type:

None

class babylon.engine.errors.InfeasibleMigration(node_id, from_territory, to_territory, reason)[source]

Bases: object

A migration between territories is not possible.

Parameters:

  • node_id (str) – The entity attempting migration.

  • from_territory (str) – Source territory ID.

  • to_territory (str) – Target territory ID.

  • reason (str) – Why the migration is infeasible.

node_id: str
from_territory: str
to_territory: str
reason: str
__init__(node_id, from_territory, to_territory, reason)
Parameters:

  • node_id (str)

  • from_territory (str)

  • to_territory (str)

  • reason (str)

Return type:

None

class babylon.engine.errors.ConservationViolation(invariant_name, expected, actual, tolerance)[source]

Bases: object

A conservation law was violated (defensive check before invariant harness).

Parameters:

  • invariant_name (str) – Name of the conservation invariant.

  • expected (float) – Expected value (pre-step total or delta).

  • actual (float) – Actual value observed post-step.

  • tolerance (float) – The tolerance that was exceeded.

invariant_name: str
expected: float
actual: float
tolerance: float
__init__(invariant_name, expected, actual, tolerance)
Parameters:
Return type:

None

babylon.engine.errors.TransitionError = babylon.engine.errors.NegativeCapitalStock | babylon.engine.errors.InsufficientLaborHours | babylon.engine.errors.MissingOrganization | babylon.engine.errors.InfeasibleMigration | babylon.engine.errors.ConservationViolation

Closed union of all modeled transition failures.

Systems return Result[WorldState, TransitionError] to signal expected failures without raising exceptions.