babylon.engine.services

Service container for dependency injection.

This module provides a ServiceContainer dataclass that aggregates all dependencies needed by the simulation engine, enabling clean injection for testing and configuration.

Sprint 3: Central Committee (Dependency Injection) Paradox Refactor: Added GameDefines for centralized coefficients. Spec 008: Added metrics field for dependency-injected telemetry.

Classes

`EconomicsFallbackTally`([...])	Loud observability for economics-calculator fallbacks (C.8 / spec 2.R).
`ServiceContainer`(config, database, ...[, ...])	Container for all simulation services.

class babylon.engine.services.EconomicsFallbackTally(national_params_observations=0, melt_calculator_wired=False, basket_calculator_wired=False, gamma_calculator_wired=False, melt_unavailable=0, gamma_basket_calculator_none=0, gamma_iii_calculator_none=0, gamma_iii_returned_none=0)[source]

Bases: object

Loud observability for economics-calculator fallbacks (C.8 / spec 2.R).

TickDynamicsSystem substitutes a hardcoded coefficient whenever an economics calculator is unwired (None) or returns no data. Historically these substitutions were silent — a fully-unwired run reported gamma_III = 0.33 forever with no trace of why. This tally records each fallback and the wired-vs-None status of every calculator so the run manifest can attest whether gamma was genuinely computed or merely defaulted.

Pure instrumentation: recording a fallback NEVER changes a computed value. The caller selects the fallback constant first, then calls record_*.

A fresh tally is created per ServiceContainer (default_factory), so counters are scoped to a single run and safe across processes/tests.

Parameters:

national_params_observations (int)
melt_calculator_wired (bool)
basket_calculator_wired (bool)
gamma_calculator_wired (bool)
melt_unavailable (int)
gamma_basket_calculator_none (int)
gamma_iii_calculator_none (int)
gamma_iii_returned_none (int)

national_params_observations: int = 0: How many times _compute_national_params ran (year boundaries seen).

melt_calculator_wired: bool = False: Wired-vs-None status of each calculator (snapshot; last observation wins).

basket_calculator_wired: bool = False

gamma_calculator_wired: bool = False

melt_unavailable: int = 0: Per-fallback counters.

gamma_basket_calculator_none: int = 0

gamma_iii_calculator_none: int = 0

gamma_iii_returned_none: int = 0

observe_wiring(*, melt, basket, gamma)[source]

Record calculator wired-vs-None status for this observation.

Parameters:

melt (bool) – Whether melt_calculator is wired (not None).
basket (bool) – Whether basket_calculator is wired (not None).
gamma (bool) – Whether gamma_calculator is wired (not None).

Return type:

None

record_melt_unavailable()[source]

Count a MELT-unavailable early return (calculator wired but no data).

Return type:: None

record_gamma_basket_calculator_none()[source]

Count a gamma_basket fallback taken because the calculator is None.

Return type:: None

record_gamma_iii_calculator_none()[source]

Count a gamma_III fallback taken because the calculator is None.

Return type:: None

record_gamma_iii_returned_none()[source]

Count a gamma_III fallback taken because a wired calculator returned no data.

Return type:: None

to_dict()[source]

Serialize to a manifest-ready dict (stable key order).

Return type:: dict[str, int | bool]
Returns:: Dict of counter/status fields for the manifest economics_fallbacks block.

__init__(national_params_observations=0, melt_calculator_wired=False, basket_calculator_wired=False, gamma_calculator_wired=False, melt_unavailable=0, gamma_basket_calculator_none=0, gamma_iii_calculator_none=0, gamma_iii_returned_none=0)

Parameters:

national_params_observations (int)
melt_calculator_wired (bool)
basket_calculator_wired (bool)
gamma_calculator_wired (bool)
melt_unavailable (int)
gamma_basket_calculator_none (int)
gamma_iii_calculator_none (int)
gamma_iii_returned_none (int)

Return type:

None

class babylon.engine.services.ServiceContainer(config, database, event_bus, formulas, defines, metrics, field_registry=None, opposition_registry=None, reserve_army_data_source=None, dispossession_data_source=None, productivity_data_source=None, melt_calculator=None, basket_calculator=None, gamma_calculator=None, capital_calculator=None, throughput_calculator=None, transition_engine=None, tensor_registry=None, economics_fallbacks=<factory>, community_hypergraph=None, turnover_profile_source=None, inventory_data_source=None, depreciation_data_source=None, hex_grid=None, persistence=None, tracer=None, boundary_register=None, auditor=None, distribution_calculator=None, interest_calculator=None, credit_cycle_detector=None, fictitious_capital_calculator=None, rent_calculator=None, housing_calculator=None, counter_tendency_calculator=None, value_basis_converter=None, financial_crisis_assessor=None, z1_source=None, housing_data_source=None, periphery_labor_source=None, final_demand_source=None, industry_county_allocator=None, production_chain_calculator=None, bea_industries=None)[source]

Bases: object

Container for all simulation services.

Aggregates the six core services needed by the simulation, plus optional economics calculator services for tick dynamics (Feature 017):

Core:

config: Immutable simulation parameters
database: Database connection for persistence
event_bus: Publish/subscribe communication
formulas: Registry of mathematical formulas
defines: Centralized game coefficients (Paradox Refactor)
metrics: Telemetry collector for observability (Spec 008)

Field Topology (Feature 002, optional for backward compatibility):

field_registry: Contradiction field computation registry

Economics (Feature 017, all optional for backward compatibility):

melt_calculator: National MELT computation (Feature 013)
basket_calculator: Basket visibility computation (Feature 013)
gamma_calculator: Reproductive visibility computation (Feature 015)
capital_calculator: Capital stock computation (Feature 012)
throughput_calculator: Throughput position computation (Feature 014)
transition_engine: Class transition engine (Feature 016)
tensor_registry: Cached economic tensor data (Feature 011)

Example

>>> container = ServiceContainer.create()
>>> rent = container.formulas.get("imperial_rent")
>>> container.event_bus.publish(Event(...))
>>> with container.database.session() as session:
...     # do database work
>>> container.database.close()
>>> default_org = container.defines.DEFAULT_ORGANIZATION
>>> container.metrics.increment("ticks_processed")

Parameters:

config (SimulationConfig)
database (DatabaseProtocol)
event_bus (EventBus)
formulas (FormulaRegistry)
defines (GameDefines)
metrics (MetricsCollectorProtocol)
field_registry (Any)
opposition_registry (Any)
reserve_army_data_source (Any)
dispossession_data_source (Any)
productivity_data_source (Any)
melt_calculator (Any)
basket_calculator (Any)
gamma_calculator (Any)
capital_calculator (Any)
throughput_calculator (Any)
transition_engine (Any)
tensor_registry (Any)
economics_fallbacks (EconomicsFallbackTally)
community_hypergraph (Any)
turnover_profile_source (Any)
inventory_data_source (Any)
depreciation_data_source (Any)
hex_grid (Any)
persistence (Any)
tracer (Any)
boundary_register (Any)
auditor (Any)
distribution_calculator (Any)
interest_calculator (Any)
credit_cycle_detector (Any)
fictitious_capital_calculator (Any)
rent_calculator (Any)
housing_calculator (Any)
counter_tendency_calculator (Any)
value_basis_converter (Any)
financial_crisis_assessor (Any)
z1_source (Any)
housing_data_source (Any)
periphery_labor_source (Any)
final_demand_source (Any)
industry_county_allocator (Any)
production_chain_calculator (Any)
bea_industries (list[str] | None)

config: SimulationConfig

database: DatabaseProtocol

event_bus: EventBus

formulas: FormulaRegistry

defines: GameDefines

metrics: MetricsCollectorProtocol

field_registry: Any = None

opposition_registry: Any = None

reserve_army_data_source: Any = None

dispossession_data_source: Any = None

productivity_data_source: Any = None

melt_calculator: Any = None

basket_calculator: Any = None

gamma_calculator: Any = None

capital_calculator: Any = None

throughput_calculator: Any = None

transition_engine: Any = None

tensor_registry: Any = None

economics_fallbacks: EconomicsFallbackTally

community_hypergraph: Any = None

turnover_profile_source: Any = None

inventory_data_source: Any = None

depreciation_data_source: Any = None

hex_grid: Any = None

persistence: Any = None

tracer: Any = None

boundary_register: Any = None

auditor: Any = None

distribution_calculator: Any = None

interest_calculator: Any = None

credit_cycle_detector: Any = None

fictitious_capital_calculator: Any = None

rent_calculator: Any = None

housing_calculator: Any = None

counter_tendency_calculator: Any = None

value_basis_converter: Any = None

financial_crisis_assessor: Any = None

z1_source: Any = None

housing_data_source: Any = None

periphery_labor_source: Any = None

final_demand_source: Any = None

industry_county_allocator: Any = None

production_chain_calculator: Any = None

bea_industries: list[str] | None = None: The configured BEA Summary industry list — defines the alignment baseline for FR-006 (industry-list mismatch fail-fast). Set at scenario-load time; None until then (the Spec 057 pipeline falls back to graceful-degradation stub behavior when None per data-model.md ServiceContainer notes).

__init__(config, database, event_bus, formulas, defines, metrics, field_registry=None, opposition_registry=None, reserve_army_data_source=None, dispossession_data_source=None, productivity_data_source=None, melt_calculator=None, basket_calculator=None, gamma_calculator=None, capital_calculator=None, throughput_calculator=None, transition_engine=None, tensor_registry=None, economics_fallbacks=<factory>, community_hypergraph=None, turnover_profile_source=None, inventory_data_source=None, depreciation_data_source=None, hex_grid=None, persistence=None, tracer=None, boundary_register=None, auditor=None, distribution_calculator=None, interest_calculator=None, credit_cycle_detector=None, fictitious_capital_calculator=None, rent_calculator=None, housing_calculator=None, counter_tendency_calculator=None, value_basis_converter=None, financial_crisis_assessor=None, z1_source=None, housing_data_source=None, periphery_labor_source=None, final_demand_source=None, industry_county_allocator=None, production_chain_calculator=None, bea_industries=None)

Parameters:

config (SimulationConfig)
database (DatabaseProtocol)
event_bus (EventBus)
formulas (FormulaRegistry)
defines (GameDefines)
metrics (MetricsCollectorProtocol)
field_registry (Any)
opposition_registry (Any)
reserve_army_data_source (Any)
dispossession_data_source (Any)
productivity_data_source (Any)
melt_calculator (Any)
basket_calculator (Any)
gamma_calculator (Any)
capital_calculator (Any)
throughput_calculator (Any)
transition_engine (Any)
tensor_registry (Any)
economics_fallbacks (EconomicsFallbackTally)
community_hypergraph (Any)
turnover_profile_source (Any)
inventory_data_source (Any)
depreciation_data_source (Any)
hex_grid (Any)
persistence (Any)
tracer (Any)
boundary_register (Any)
auditor (Any)
distribution_calculator (Any)
interest_calculator (Any)
credit_cycle_detector (Any)
fictitious_capital_calculator (Any)
rent_calculator (Any)
housing_calculator (Any)
counter_tendency_calculator (Any)
value_basis_converter (Any)
financial_crisis_assessor (Any)
z1_source (Any)
housing_data_source (Any)
periphery_labor_source (Any)
final_demand_source (Any)
industry_county_allocator (Any)
production_chain_calculator (Any)
bea_industries (list[str] | None)

Return type:

None

classmethod create(config=None, defines=None, metrics=None, *, hex_grid=None, persistence=None, tracer=None, reserve_army_data_source=None, dispossession_data_source=None, productivity_data_source=None, field_registry=None, opposition_registry=None, melt_calculator=None, basket_calculator=None, gamma_calculator=None, capital_calculator=None, throughput_calculator=None, transition_engine=None, tensor_registry=None, community_hypergraph=None, turnover_profile_source=None, inventory_data_source=None, depreciation_data_source=None, distribution_calculator=None, interest_calculator=None, credit_cycle_detector=None, fictitious_capital_calculator=None, rent_calculator=None, housing_calculator=None, counter_tendency_calculator=None, value_basis_converter=None, financial_crisis_assessor=None, z1_source=None, housing_data_source=None, periphery_labor_source=None, final_demand_source=None, industry_county_allocator=None, production_chain_calculator=None, bea_industries=None)[source]

Factory method to create a fully-initialized container.

Creates all services with sensible defaults. Uses in-memory SQLite for database isolation in tests.

Parameters:

config (SimulationConfig | None) – Optional custom config. If None, uses default SimulationConfig.
defines (GameDefines | None) – Optional custom defines. If None, uses default GameDefines.
metrics (MetricsCollectorProtocol | None) – Optional custom metrics collector. If None, creates a new MetricsCollector instance. Pass a mock for testing.
field_registry (Any) – Optional FieldRegistry for contradiction fields (Feature 002).
melt_calculator (Any) – Optional MELTCalculator (Feature 013).
basket_calculator (Any) – Optional BasketVisibilityCalculator (Feature 013).
gamma_calculator (Any) – Optional GammaIIICalculator (Feature 015).
capital_calculator (Any) – Optional CapitalStockCalculator (Feature 012).
throughput_calculator (Any) – Optional ThroughputCalculator (Feature 014).
transition_engine (Any) – Optional ClassTransitionEngine (Feature 016).
tensor_registry (Any) – Optional TensorRegistry for cached tensor data (Feature 011).
community_hypergraph (Any) – Optional XGI Hypergraph for community membership (Feature 022).
hex_grid (Any)
persistence (Any)
tracer (Any)
reserve_army_data_source (Any)
dispossession_data_source (Any)
productivity_data_source (Any)
opposition_registry (Any)
turnover_profile_source (Any)
inventory_data_source (Any)
depreciation_data_source (Any)
distribution_calculator (Any)
interest_calculator (Any)
credit_cycle_detector (Any)
fictitious_capital_calculator (Any)
rent_calculator (Any)
housing_calculator (Any)
counter_tendency_calculator (Any)
value_basis_converter (Any)
financial_crisis_assessor (Any)
z1_source (Any)
housing_data_source (Any)
periphery_labor_source (Any)
final_demand_source (Any)
industry_county_allocator (Any)
production_chain_calculator (Any)
bea_industries (list[str] | None)

Return type:

ServiceContainer

Returns:

ServiceContainer with all services initialized