babylon.engine.systems.cross_border_commute

Cross-border commute classifier (Spec 063 T080 / T037).

Stateless rule that resolves a LODES destination identifier into one of three boundary categories:

1. In-study-area hex (NodeKind.HEX, the H3 cell ID)

2. Domestic out-of-study-area (NodeKind.EXTERNAL, “rest_of_usa”)

3. Canadian destination (NodeKind.EXTERNAL, “canada”)

Implements FR-023..FR-028 per data-model.md §1.4. Per research.md §4, the canonical LODES dataset does NOT include Canadian destinations; the Canadian branch fires only for synthetic test rows OR for rows produced by the Option B BorderCommuteSynthesisLoader when BTS + StatCan + WWE data is wired up.

The domestic_states constructor parameter is the single source of truth for what counts as US-domestic (per the F1 remediation in 2026-05-13 /speckit.analyze).

Classes

CrossBorderClassification(dest_kind, ...)	Resolved (kind, node_id) for one LODES destination identifier.
CrossBorderCommuteClassifier(*, ...)	Stateless classifier mapping LODES destination IDs to boundary categories.

class babylon.engine.systems.cross_border_commute.CrossBorderClassification(dest_kind, dest_node_id)

Bases: object

Resolved (kind, node_id) for one LODES destination identifier.

Parameters:

• dest_kind (NodeKind)

• dest_node_id (str)

dest_kind: NodeKind

dest_node_id: str

__init__(dest_kind, dest_node_id)

Parameters:

• dest_kind (NodeKind)

• dest_node_id (str)

Return type:

None

class babylon.engine.systems.cross_border_commute.CrossBorderCommuteClassifier(*, study_area_hexes, study_area_states, domestic_states)

Bases: object

Stateless classifier mapping LODES destination IDs to boundary categories.

See data-model.md §1.4 for the 4-rule classification:

1. If dest_id is an H3 res-7 cell in study_area_hexes → HEX.

2. Else if a 15-digit Census block with state-prefix in domestic_states → EXTERNAL/rest_of_usa.

3. Else if a 15-digit code with state-prefix NOT in domestic_states → EXTERNAL/canada.

4. Else (unrecognized format) → EXTERNAL/rest_of_usa, with one audit log entry per unique unmapped destination (FR-028).

Parameters:

• study_area_hexes (frozenset[str])

• study_area_states (frozenset[str])

• domestic_states (frozenset[str])

__init__(*, study_area_hexes, study_area_states, domestic_states)

Parameters:

• study_area_hexes (frozenset[str])

• study_area_states (frozenset[str])

• domestic_states (frozenset[str])

Return type:

None

classify(dest_id)

Resolve a LODES destination identifier to (kind, node_id).

Return type:

CrossBorderClassification

Parameters:

dest_id (str)