babylon.engine.scenarios

Engine scenarios package — Scenario ABC + 6 ported builders.

ADR-006.1 / Spec 059 US4. Replaces the historical engine/scenarios.py single-file module with a package that holds:

  • The Scenario ABC + auto-registry (in base).

  • 6 thin subclass files that delegate to the legacy free-function builders for byte-equality with the pre-Bundle-2 baseline (SC-007).

  • Backward-compat shims for the legacy free-function names (create_*_scenario) so existing call sites continue to resolve.

  • The legacy implementations under _legacy / _legacy_wayne (kept as module-private attribute sources; do not import directly from outside the package).

  • The 2 utilities (get_multiverse_scenarios, apply_scenario) and 5 private helpers from the legacy module are re-exported here so existing from babylon.engine.scenarios import … call sites continue to work.

Per research.md D3, only the 6 builder functions are migrated to Scenario subclasses; the 2 utilities are not migrated and remain as free functions on this module.

class babylon.engine.scenarios.Scenario[source]

Bases: ABC

Abstract base for scenario builders.

Subclasses MUST set name (ClassVar str) and description (ClassVar str), and implement build(). They auto-register via __init_subclass__().

Optional build_territories / build_classes / build_relationships methods are provided for the new-style composition pattern; subclasses MAY use them with a custom build() that calls them, or override build() directly (the pattern used by Bundle 2’s port of the 6 legacy builders).

name: ClassVar[str]
description: ClassVar[str] = ''
abstractmethod build(*args, **kwargs)[source]

Build the scenario and return (state, config, defines).

Return type:

tuple[WorldState, SimulationConfig, GameDefines]

Parameters:
build_territories()[source]

Optional: territory builder for composition pattern.

Return type:

dict[str, Any]

build_classes()[source]

Optional: social-class builder for composition pattern.

Return type:

dict[str, Any]

build_relationships()[source]

Optional: relationship builder for composition pattern.

Return type:

dict[str, Any]

classmethod __init_subclass__(**kwargs)[source]

Auto-register subclass in _SCENARIO_REGISTRY keyed on cls.name.

Raises:

ValueError – When two subclasses share the same name (collision detection at import time, per US4 acceptance #2).

Return type:

None

Parameters:

kwargs (Any)

babylon.engine.scenarios.get_scenario(name)[source]

Look up a Scenario subclass by name.

Return type:

type[Scenario]

Parameters:

name (str)

babylon.engine.scenarios.list_scenarios()[source]

Return the names of all registered scenarios, sorted.

Return type:

list[str]

class babylon.engine.scenarios.TwoNodeScenario[source]

Bases: Scenario

Scenario port: delegates to _legacy.create_two_node_scenario.

name: ClassVar[str] = 'two_node'
description: ClassVar[str] = 'Minimal 2-node scenario for unit testing the engine pipeline.'
build(*args, **kwargs)[source]

Delegate to the legacy free-function builder for byte-equality (SC-007).

Return type:

tuple[WorldState, SimulationConfig, GameDefines]

Parameters:

  • args (Any)

  • kwargs (Any)

class babylon.engine.scenarios.HighTensionScenario[source]

Bases: Scenario

Scenario port: delegates to _legacy.create_high_tension_scenario.

name: ClassVar[str] = 'high_tension'
description: ClassVar[str] = 'High-tension scenario with elevated repression and exploitation.'
build(*args, **kwargs)[source]

Delegate to the legacy free-function builder for byte-equality (SC-007).

Return type:

tuple[WorldState, SimulationConfig, GameDefines]

Parameters:

  • args (Any)

  • kwargs (Any)

class babylon.engine.scenarios.LaborAristocracyScenario[source]

Bases: Scenario

Scenario port: delegates to _legacy.create_labor_aristocracy_scenario.

name: ClassVar[str] = 'labor_aristocracy'
description: ClassVar[str] = 'Labor-aristocracy scenario emphasising W_c > V_c (imperial pacification).'
build(*args, **kwargs)[source]

Delegate to the legacy free-function builder for byte-equality (SC-007).

Return type:

tuple[WorldState, SimulationConfig, GameDefines]

Parameters:

  • args (Any)

  • kwargs (Any)

class babylon.engine.scenarios.ImperialCircuitScenario[source]

Bases: Scenario

Scenario port: delegates to _legacy.create_imperial_circuit_scenario.

name: ClassVar[str] = 'imperial_circuit'
description: ClassVar[str] = 'Workhorse imperial-circuit scenario (default for sim:trace + tools).'
build(*args, **kwargs)[source]

Delegate to the legacy free-function builder for byte-equality (SC-007).

Return type:

tuple[WorldState, SimulationConfig, GameDefines]

Parameters:

  • args (Any)

  • kwargs (Any)

class babylon.engine.scenarios.USScenario[source]

Bases: Scenario

Scenario port: delegates to _legacy.create_us_scenario.

name: ClassVar[str] = 'us'
description: ClassVar[str] = 'Nationwide US scenario built on H3 hex grid + federal county data.'
build(*args, **kwargs)[source]

Delegate to the legacy free-function builder for byte-equality (SC-007).

Return type:

tuple[WorldState, SimulationConfig, GameDefines]

Parameters:

  • args (Any)

  • kwargs (Any)

class babylon.engine.scenarios.WayneCountyScenario[source]

Bases: Scenario

Scenario port: delegates to _legacy_wayne.create_wayne_county_scenario.

name: ClassVar[str] = 'wayne_county'
description: ClassVar[str] = 'Wayne County (Detroit) tri-county acceptance scenario.'
build(*args, **kwargs)[source]

Delegate to the legacy free-function builder for byte-equality (SC-007).

Return type:

tuple[WorldState, SimulationConfig, GameDefines]

Parameters:

  • args (Any)

  • kwargs (Any)

babylon.engine.scenarios.create_two_node_scenario(worker_wealth=0.5, owner_wealth=0.5, extraction_efficiency=0.8, repression_level=0.5, worker_organization=0.1, worker_ideology=0.0)[source]

Create the minimal viable dialectic: one worker, one owner, one exploitation edge.

This is the two-node scenario from the Phase 1 blueprint, now ready for Phase 2 simulation. It models the fundamental class relationship: - Worker produces value (source of exploitation edge) - Owner extracts imperial rent (target of exploitation edge) - Tension accumulates on the edge

Parameters:

  • worker_wealth (float) – Initial wealth for periphery worker (default 0.5)

  • owner_wealth (float) – Initial wealth for core owner (default 0.5)

  • extraction_efficiency (float) – Alpha in imperial rent formula (default 0.8)

  • repression_level (float) – State violence capacity (default 0.5)

  • worker_organization (float) – Worker class cohesion (default 0.1)

  • worker_ideology (float) – Worker ideology, -1=revolutionary to +1=reactionary (default 0.0)

Return type:

tuple[WorldState, SimulationConfig, GameDefines]

Returns:

Tuple of (WorldState, SimulationConfig, GameDefines) ready for step() function.

Example

>>> state, config, defines = create_two_node_scenario()
>>> for _ in range(100):
...     state = step(state, config)
>>> print(f"Worker wealth after 100 ticks: {state.entities['C001'].wealth}")
babylon.engine.scenarios.create_high_tension_scenario()[source]

Create a scenario with high initial tension.

Worker is poor, owner is rich, tension is already elevated. Useful for testing phase transitions and rupture conditions.

Return type:

tuple[WorldState, SimulationConfig, GameDefines]

Returns:

Tuple of (WorldState, SimulationConfig, GameDefines) near rupture point.

babylon.engine.scenarios.create_labor_aristocracy_scenario()[source]

Create a scenario with a labor aristocracy (Wc > Vc).

Worker receives more than they produce, enabled by imperial rent from elsewhere. Tests consciousness decay mechanics.

Return type:

tuple[WorldState, SimulationConfig, GameDefines]

Returns:

Tuple of (WorldState, SimulationConfig, GameDefines) with labor aristocracy.

babylon.engine.scenarios.create_imperial_circuit_scenario(periphery_wealth=0.6, core_wealth=0.9, comprador_cut=0.90, imperial_rent_pool=100.0, extraction_efficiency=0.8, repression_level=0.5, solidarity_strength=0.0)[source]

Create the 4-node Imperial Circuit scenario.

This scenario fixes the “Robin Hood” bug in create_two_node_scenario() where super-wages incorrectly flow to periphery workers. In MLM-TW theory, super-wages should only go to the Labor Aristocracy (core workers), NOT periphery workers.

Topology:

        graph LR
    Pw["P_w (Periphery Workers)"] -->|EXPLOITATION| Pc["P_c (Comprador)"]
    Pc -->|TRIBUTE| Cb["C_b (Core Bourgeoisie)"]
    Cb -->|WAGES| Cw["C_w (Labor Aristocracy)"]
    Cb -->|CLIENT_STATE| Pc
    Pw -.->|"SOLIDARITY (0.0)"| Cw

Value Flow:

  1. EXPLOITATION: P_w -> P_c (imperial rent extraction from workers)

  2. TRIBUTE: P_c -> C_b (comprador sends tribute, keeps comprador_cut)

  3. WAGES: C_b -> C_w (super-wages to labor aristocracy, NOT periphery!)

  4. CLIENT_STATE: C_b -> P_c (subsidy to stabilize client state)

  5. SOLIDARITY: P_w -> C_w (potential internationalism, starts at 0)

Parameters:

  • periphery_wealth (float) – Initial wealth for periphery worker P001 (default 0.1)

  • core_wealth (float) – Initial wealth for core bourgeoisie C001 (default 0.9)

  • comprador_cut (float) – Fraction comprador keeps from extracted value (default 0.90)

  • imperial_rent_pool (float) – Initial imperial rent pool (default 100.0)

  • extraction_efficiency (float) – Alpha in imperial rent formula (default 0.8)

  • repression_level (float) – Base repression level (default 0.5)

  • solidarity_strength (float) – Initial solidarity between P_w and C_w (default 0.0). When > 0, wage crisis routes to class consciousness (revolutionary). When = 0, wage crisis routes to national identity (fascist).

Return type:

tuple[WorldState, SimulationConfig, GameDefines]

Returns:

Tuple of (WorldState, SimulationConfig, GameDefines) ready for step() function.

Example

>>> state, config, defines = create_imperial_circuit_scenario()
>>> # Verify wages go to labor aristocracy, not periphery
>>> wages_edges = [r for r in state.relationships if r.edge_type == EdgeType.WAGES]
>>> assert state.entities[wages_edges[0].target_id].role == SocialRole.LABOR_ARISTOCRACY
babylon.engine.scenarios.create_us_scenario(extraction_efficiency=0.8, repression_level=0.5, solidarity_strength=0.0)[source]

Create a full CONUS hex scenario with ~1100 H3 territories.

Generates H3 resolution-3 hexagonal tiles covering the continental US. Each hex has geographic-derived economic properties (population, rent, biocapacity, sector type) computed from proximity to 20 metro centroids.

Reuses the standard 6-class imperial circuit entities (4 active + 2 dormant) and 5 core relationship edges, adding TENANCY edges connecting classes to territory clusters based on class role.

Parameters:

  • extraction_efficiency (float) – Alpha in imperial rent formula (default 0.8).

  • repression_level (float) – Base repression level (default 0.5).

  • solidarity_strength (float) – Initial solidarity P_w->C_w (default 0.0).

Return type:

tuple[WorldState, SimulationConfig, GameDefines]

Returns:

Tuple of (WorldState, SimulationConfig, GameDefines).

babylon.engine.scenarios.create_wayne_county_scenario(extraction_efficiency=0.8, repression_level=0.6)[source]

Create the Wayne County Organizer scenario.

A single-player strategy game centered on Wayne County, Michigan. The player controls a small political organization trying to build power in one of America’s most class-stratified counties.

Parameters:

  • extraction_efficiency (float) – Alpha in imperial rent formula (default 0.8).

  • repression_level (float) – Base repression (default 0.6 — Detroit is heavily policed).

Return type:

tuple[WorldState, SimulationConfig, GameDefines]

Returns:

Tuple of (WorldState, SimulationConfig, GameDefines).

babylon.engine.scenarios.apply_scenario(state, config, defines, scenario)[source]

Apply scenario modifiers to WorldState, SimulationConfig, and GameDefines.

This function transforms a base (state, config, defines) triple into a counterfactual scenario by applying the three modifiers:

  1. superwage_multiplier: Passed to GameDefines.economy.superwage_multiplier. - PPP Model: Affects worker effective wealth via PPP calculation. - Paradox Refactor: Game math lives in GameDefines, not SimulationConfig. - economic.py reads from services.defines.economy.superwage_multiplier.

  2. solidarity_index: Sets solidarity_strength on all SOLIDARITY edges. - Does not affect EXPLOITATION or other edge types.

  3. repression_capacity: Updates repression_faced on all SocialClass entities AND repression_level in SimulationConfig.

Parameters:

  • state (WorldState) – Base WorldState to modify (not mutated)

  • config (SimulationConfig) – Base SimulationConfig to modify (not mutated)

  • defines (GameDefines) – Base GameDefines to modify (not mutated)

  • scenario (ScenarioConfig) – ScenarioConfig with modifier values

Return type:

tuple[WorldState, SimulationConfig, GameDefines]

Returns:

Tuple of (new_state, new_config, new_defines) with scenario modifiers applied.

Example

>>> state, config, defines = create_two_node_scenario()
>>> scenario = ScenarioConfig(name="test", superwage_multiplier=1.5)
>>> new_state, new_config, new_defines = apply_scenario(state, config, defines, scenario)
>>> new_defines.economy.superwage_multiplier  # Will be 1.5 (for PPP calculation)
babylon.engine.scenarios.get_multiverse_scenarios()[source]

Generate 2^3 = 8 permutations of High/Low scenario values.

This implements the Multiverse Protocol: running deterministic simulations across parameter space to prove mathematical divergence.

Parameter ranges:

  • superwage_multiplier: 0.3 (Low) or 1.5 (High)

  • solidarity_index: 0.2 (Low) or 0.8 (High)

  • repression_capacity: 0.2 (Low) or 0.8 (High)

Expected outcomes:

  • High SW + Low Solidarity + High Repression -> Low P(S|R) (Stable for Capital)

  • Low SW + High Solidarity + Low Repression -> High P(S|R) (Revolution likely)

Return type:

list[ScenarioConfig]

Returns:

List of 8 ScenarioConfig objects covering all permutations.

Example

>>> scenarios = get_multiverse_scenarios()
>>> for s in scenarios:
...     print(f"{s.name}: sw={s.superwage_multiplier}, sol={s.solidarity_index}")

Modules

base

Scenario ABC + auto-registry — ADR-006.1 / Spec 059 US4.

high_tension

High-tension scenario with elevated repression and exploitation.

imperial_circuit

Workhorse imperial-circuit scenario (default for sim:trace + tools).

labor_aristocracy

Labor-aristocracy scenario emphasising W_c > V_c (imperial pacification).

two_node

Minimal 2-node scenario for unit testing the engine pipeline.

us

Nationwide US scenario built on H3 hex grid + federal county data.

wayne_county

Wayne County (Detroit) tri-county acceptance scenario.