babylon.engine.systems.phi_distribution

Imperial-rent Φ distribution to counties (Spec 062 T058 / FR-034 / FR-035).

For each external node carrying phi_year_inflow, the weekly slice is phi_year_inflow / 52. That slice is distributed across US counties weighted by the county’s exposure to that external node’s trading sector (BEA I-O imports × QCEW industry shares). For the MVP the exposure weights are passed in by the caller; downstream specs will compute them from the hydrated immutable_reference_bea_io and immutable_reference_qcew_employment tables.

Every transfer is recorded as a DRAIN_EDGE boundary register row from the external node to the receiving county (Constitution II.9 dyadic morphism + R2 hex-pair schema).

See also

specs/062-cross-scale-integration/spec.md FR-034 / FR-035. babylon.domain.economics.boundary_flow_register:

BoundaryFlowRegister.

Functions

distribute_phi_week_to_counties(*, ...[, ...])

Distribute one external node's weekly Φ across US counties.
babylon.engine.systems.phi_distribution.distribute_phi_week_to_counties(*, session_id, tick, external_node_id, phi_year_inflow, county_exposure, register, weeks_per_year=52.0)[source]

Distribute one external node’s weekly Φ across US counties.

The weekly Φ slice is phi_year_inflow / weeks_per_year per FR-035. Each county receives a share equal to its exposure weight (the weights MUST sum to 1.0; a non-unit sum is treated as a calling-side bug per Constitution III.1 — no silent renormalization).

Parameters:

  • session_id (UUID) – Owning session UUID for the boundary register rows.

  • tick (int) – Simulation tick (>=0).

  • external_node_id (str) – The source external node (e.g., “canada”).

  • phi_year_inflow (float) – Annual Φ inflow from this external node.

  • county_exposure (Mapping[str, float]) – {county_fips: weight} map; weights MUST sum to 1.

  • register (BoundaryFlowRegister) – BoundaryFlowRegister buffer to receive DRAIN_EDGE rows.

  • weeks_per_year (float) – Ticks per simulation year (default 52, matching GameDefines.timescale.weeks_per_year — spec-101 review minor: sourced from a single caller-supplied value rather than an independently-hardcoded literal in each consuming module).

Return type:

dict[str, float]

Returns:

{county_fips: phi_amount} showing the per-county weekly Φ.

Raises:

ValueError – If phi_year_inflow is negative, or if the exposure weights do not sum to 1 within 1e-9.

Example (Detroit-Windsor placeholder):

Canada has phi_year_inflow = 100_000_000 for 2010. Weekly slice is 1_923_076.92. Wayne County (26163) has exposure 0.6; Oakland (26125) has exposure 0.4. The auditor sums all three weekly slices on year-boundary tick 51 and asserts the total equals the annual figure to within ε.