babylon.engine.observers.balkanization_projections

Spec-070 observability projections (T115-T116, FR-036 / FR-037 / FR-051).

Read-only, deterministic snapshots of Sovereign + Territory state for downstream UI consumption (spec-042 / spec-085). The projections never mutate the graph and never depend on the order they are called.

Per FR-051: SovereignProjection.projected_habitability extrapolates current metabolic_impact over horizon_ticks (default 20 from BalkanizationDefines) assuming no policy change.

Functions

observe_sovereign(graph, sovereign_id[, ...])

Return a frozen projection of sovereign_id's state, or None when the Sovereign is absent.

observe_territory(graph, territory_id)

Return a frozen projection of territory_id's claim state.

Classes

SovereignProjection(**data)

Read-only snapshot of a Sovereign's state + 20-tick projection of its claimed-territory habitability under the current policy.

TerritoryProjection(**data)

Read-only snapshot of a Territory's claim/influence state.
class babylon.engine.observers.balkanization_projections.SovereignProjection(**data)[source]

Bases: BaseModel

Read-only snapshot of a Sovereign’s state + 20-tick projection of its claimed-territory habitability under the current policy.

Parameters:
model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

sovereign_id: str
name: str
sovereignty_type: str
legitimacy: float
ruling_faction_id: str | None
extraction_policy: ExtractionPolicy
metabolic_impact: float
claimed_territory_count: int
projected_habitability: float
class babylon.engine.observers.balkanization_projections.TerritoryProjection(**data)[source]

Bases: BaseModel

Read-only snapshot of a Territory’s claim/influence state.

Parameters:

  • territory_id (str)

  • habitability (float)

  • effective_sovereign_id (str | None)

  • effective_control_level (float)

  • is_dual_power (bool)

  • claimant_count (int)

  • influencer_count (int)

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

territory_id: str
habitability: float
effective_sovereign_id: str | None
effective_control_level: float
is_dual_power: bool
claimant_count: int
influencer_count: int
babylon.engine.observers.balkanization_projections.observe_sovereign(graph, sovereign_id, horizon_ticks=None, defines=None)[source]

Return a frozen projection of sovereign_id’s state, or None when the Sovereign is absent.

Parameters:

  • graph (GraphProtocol) – GraphProtocol exposing get_node() + query_sovereign_claims().

  • sovereign_id (str) – Target Sovereign node ID.

  • horizon_ticks (int | None) – Optional override for the projection horizon. Defaults to BalkanizationDefines.projected_habitability_horizon_ticks.

  • defines (BalkanizationDefines | None) – Optional override defines.

Return type:

SovereignProjection | None

babylon.engine.observers.balkanization_projections.observe_territory(graph, territory_id)[source]

Return a frozen projection of territory_id’s claim state.

Return type:

TerritoryProjection | None

Parameters: