Percolation Theory & Phase Transitions
======================================

Babylon uses **percolation theory** from statistical physics to model
revolutionary phase transitions. The TopologyMonitor observes the
solidarity network, detecting when atomized movements "condense" into
organized revolutionary forces.

Theoretical Foundation
----------------------

Percolation theory studies how connected clusters form in networks.
Applied to revolutionary movements:

- **Sites** = Social classes (nodes)
- **Bonds** = SOLIDARITY edges
- **Percolation** = Giant component spans majority of network

When a network percolates, information (consciousness) can flow across
the entire system—the movement achieves coordination capacity.

Phase States
------------

The solidarity network exists in one of **four phase states** (4-phase model):

.. list-table:: Movement Phase States
   :header-rows: 1
   :widths: 15 30 55

   * - State
     - Network Property
     - Political Meaning
   * - **Gaseous**
     - Percolation < 0.1
     - Atomized leftism; no coordination capacity
   * - **Transitional**
     - 0.1 <= percolation < 0.5
     - Emerging clusters; vulnerable to disruption
   * - **Liquid**
     - Percolation >= 0.5, cadre_density < 0.5
     - Mass movement; broad but lacks cadre discipline
   * - **Solid**
     - Percolation >= 0.5, cadre_density >= 0.5
     - Vanguard Party; iron discipline achieved

The Percolation Threshold
-------------------------

The **percolation threshold** (p_c) is the critical point where the
network transitions from gaseous to liquid:

.. math::

   p_c = \frac{L_{max}}{N} = 0.5

Where:

- :math:`L_{max}` = Size of largest connected component
- :math:`N` = Total number of social_class nodes

When the percolation ratio crosses 0.5, a **phase transition** occurs.

.. mermaid::

   xychart-beta
       title "Percolation Ratio Over Time"
       x-axis "Time (ticks)" [0, 10, 20, 30, 40, 50]
       y-axis "p(t)" 0 --> 1
       line [0.05, 0.15, 0.25, 0.40, 0.52, 0.75, 0.95]

The chart shows the phase transition: below 0.5 is GASEOUS (atomized),
above 0.5 is LIQUID (connected solidarity network).

Key Metrics
-----------

The TopologyMonitor tracks several metrics:

**num_components**
   Number of disconnected subgraphs. Higher = more atomized.

**max_component_size (L_max)**
   Size of the largest connected component—the organizational core.

**percolation_ratio**
   L_max / N. Below 0.5 = gaseous/transitional; above 0.5 = liquid/solid.

**potential_liquidity**
   Count of SOLIDARITY edges > 0.1 strength (sympathizers).

**actual_liquidity**
   Count of SOLIDARITY edges > 0.5 strength (cadre).

**cadre_density** (Sprint 3.3)
   Ratio of actual_liquidity / potential_liquidity.
   Distinguishes **liquid** (< 0.5) from **solid** (>= 0.5).
   Measures the discipline and commitment level of the movement.

The Fascist Bifurcation
-----------------------

The most important insight encoded in the topology system:

   *Agitation without solidarity produces fascism, not revolution.*

When wages fall (crisis conditions), the system generates "agitation energy"
that must route somewhere. The solidarity graph determines where:

**With solidarity infrastructure** (σ > 0)
   Agitation channels into class consciousness. Workers correctly identify
   capital as the enemy. Revolutionary drift.

**Without solidarity infrastructure** (σ = 0)
   Agitation channels into national identity. Workers blame foreigners,
   immigrants, the "other." Fascist drift.

.. math::

   B(\dot{W}, \sigma) = \begin{cases}
   +\kappa|\dot{W}| \cdot \sigma & \text{if } \sigma > 0 \text{ (revolution)} \\
   -\kappa|\dot{W}| & \text{if } \sigma = 0 \text{ (fascism)}
   \end{cases}

Where κ = 2.25 (Kahneman-Tversky loss aversion coefficient).

**Historical Comparison:**

- **Russia 1917**: Solidarity infrastructure existed (Bolshevik party, soviets)
  → Revolution succeeded
- **Germany 1933**: Working class atomized (SPD/KPD split, no united front)
  → Fascism won

This is a **cusp catastrophe** in Thom's classification—two stable equilibria
separated by a bifurcation surface in the (wage_change, solidarity) parameter
space.

The Liquidity Gap
-----------------

The ratio of potential to actual liquidity measures movement depth:

.. math::

   \text{Liquidity Gap} = \frac{\text{potential}}{\text{actual}}

.. list-table:: Liquidity Interpretation
   :header-rows: 1
   :widths: 30 70

   * - Gap Value
     - Interpretation
   * - Gap ≈ 1
     - Deep organization; sympathizers are committed
   * - Gap > 2
     - **Brittle movement**; broad but lacks discipline
   * - actual = 0
     - No cadre; purely sympathizer network

A brittle movement (high potential, low actual) is vulnerable to
targeted repression—removing key organizers collapses the network.

Resilience Testing: Sword of Damocles
-------------------------------------

The **Sword of Damocles** test simulates state repression:

1. Remove 20% of nodes (random purge)
2. Check if giant component survives at 40% of original size
3. If not, movement is **fragile**

.. code-block:: python

   def check_resilience(graph, removal_rate=0.2, survival_threshold=0.4):
       """Check if movement survives targeted purge."""
       original_L_max = get_max_component_size(graph)

       # Simulate purge
       purged = remove_random_nodes(graph.copy(), removal_rate)
       post_purge_L_max = get_max_component_size(purged)

       is_resilient = post_purge_L_max >= original_L_max * survival_threshold
       return ResilienceResult(
           is_resilient=is_resilient,
           original_max_component=original_L_max,
           post_purge_max_component=post_purge_L_max
       )

**Network Topology Matters:**

.. mermaid::

   flowchart TB
       subgraph STAR["STAR TOPOLOGY (Fragile)"]
           S0((Hub)) --- S1((●))
           S0 --- S2((●))
           S0 --- S3((●))
           S0 --- S4((●))
       end
       subgraph MESH["MESH TOPOLOGY (Resilient)"]
           M1((●)) --- M2((●)) --- M3((●))
           M4((●)) --- M5((●)) --- M6((●))
           M7((●)) --- M8((●)) --- M9((●))
           M1 --- M4 --- M7
           M2 --- M5 --- M8
           M3 --- M6 --- M9
       end

**Star**: Remove center = Total collapse.
**Mesh**: Remove any node = Network survives.

Narrative Events
----------------

The TopologyMonitor generates narrative events at key thresholds:

.. list-table:: Narrative Triggers
   :header-rows: 1
   :widths: 35 65

   * - Condition
     - Narrative
   * - ``percolation < 0.1``
     - "STATE: Gaseous. Movement is atomized."
   * - ``percolation >= 0.5, cadre < 0.5``
     - "PHASE SHIFT: Liquid state. Mass movement formed but lacks discipline."
   * - ``percolation >= 0.5, cadre >= 0.5``
     - "PHASE SHIFT: Solid state. Vanguard Party crystallized."
   * - ``liquid -> solid`` transition
     - "CRYSTALLIZATION: Mass movement hardened into disciplined vanguard."
   * - ``potential > 2 × actual``
     - "WARNING: Movement is broad but brittle. Lacks cadre discipline."
   * - ``resilience = False``
     - "ALERT: Sword of Damocles active. A purge would destroy the movement."

The Bondi Algorithm Aesthetic
-----------------------------

Narrative output follows the **Bondi Algorithm** aesthetic—cold,
mechanical precision like a machine cataloging targets:

**Bad (emotional):**
   "The police are cracking down on protesters."

**Good (algorithmic):**
   "High-centrality nodes identified. Degree centrality > 0.4.
   Executing targeted removal. Network fragmentation imminent.
   Probability of survival: 12%."

The horror of state repression is amplified by clinical language.
The machine doesn't hate—it calculates.

Implementation
--------------

The TopologyMonitor implements the ``SimulationObserver`` protocol:

.. code-block:: python

   from babylon.engine import TopologyMonitor

   # Create monitor with resilience testing every 5 ticks
   monitor = TopologyMonitor(
       resilience_test_interval=5,
       resilience_removal_rate=0.2
   )

   # Use with Simulation
   simulation = Simulation(
       state=initial_state,
       config=config,
       observers=[monitor]
   )

   # Run simulation
   simulation.run(max_ticks=100)

   # Access history
   for snapshot in monitor.history:
       print(f"Tick {snapshot.tick}: percolation={snapshot.percolation_ratio:.2f}")

Data Models
-----------

**TopologySnapshot**

.. code-block:: python

   class TopologySnapshot(BaseModel):
       tick: int
       num_components: int
       max_component_size: int       # L_max
       total_nodes: int              # N
       percolation_ratio: Probability
       potential_liquidity: int
       actual_liquidity: int
       cadre_density: float          # actual/potential (Sprint 3.3)
       is_resilient: bool | None     # None if not tested this tick

**ResilienceResult**

.. code-block:: python

   class ResilienceResult(BaseModel):
       is_resilient: bool
       original_max_component: int
       post_purge_max_component: int
       removal_rate: float
       survival_threshold: float
       seed: int | None              # For reproducibility

Strategic Implications
----------------------

For revolutionary strategy in the simulation:

1. **Monitor percolation ratio**
   Below 0.5, the movement cannot coordinate. Above 0.5, collective
   action becomes possible.

2. **Build actual liquidity (transition from Liquid to Solid)**
   Sympathizer networks (potential) are insufficient. Cadre networks
   (actual) provide organizational depth. A **Liquid** mass movement
   can be dispersed; a **Solid** vanguard party maintains coherence.

3. **Avoid star topology**
   Distributed leadership survives purges. Charismatic-leader
   structures are fragile.

4. **Time the phase transition**
   Strike when condensation occurs—the moment of maximum coordination
   capacity before state response.

5. **Distinguish mass movement from vanguard (Sprint 3.3)**
   A Liquid state (percolation >= 0.5, cadre < 0.5) has numbers but
   lacks discipline. A Solid state (cadre >= 0.5) has both. The tragedy
   of many revolutions: they reached Liquid but never achieved Solid.

See Also
--------

- :doc:`/reference/topology` - API reference for topology functions
- :doc:`/concepts/imperial-rent` - Economic foundation (why consciousness emerges)
- :py:mod:`babylon.engine.topology_monitor` - Implementation details
- :py:mod:`babylon.systems.formulas` - Mathematical formulas