An ant colony has a routine. So does a collection truck.

1 Phase per ping — derive_phase_per_ping()

The enriched ping already carries the flags we need (at_depot, in_landfill, route_id, speed_mph). Phase derivation is a 4-rule priority cascade:

1. at_depot = true → depot (overrides everything — start/end-of-shift dwell)
2. in_landfill = true → landfill (truck is tipping)
3. route_id not null AND speed_mph ≤ slow_mph_max → collection
4. otherwise → windshield (travel time)

Implementation is one numpy np.full(len, "windshield") + 3 boolean masks. No loops, no Python-level row iteration. Millions of pings classify in milliseconds.

2 Gap-and-island → segments

Adjacent rows sharing the same phase (and route_id, for collection phases) collapse into one segment. Classic SQL pattern done in pandas:

effective_key = where(is_collection, phase + "|" + route_id, phase)
boundaries = effective_key[1:] != effective_key[:-1]
segment_id = boundaries.cumsum()

The route_id is part of the key only for collection segments. A truck driving down route A then B then back to A produces three collection segments, not one — we want per-route attribution. Windshield phases ignore route_id (the truck is just moving; the route polygons it passes through aren’t meaningful).

3 Mileage — haversine, cumulative, optional inflation

For each segment, sum the great-circle distance between consecutive pings:

haversine(lat1, lon1, lat2, lon2)   # great-circle, miles
miles = sum(haversine(p_i, p_{i+1}) for i in segment)
miles *= (1 + config.mileage_inflation_pct)

• Haversine — accurate to ~0.5% at this scale. No reprojection cost; numpy-vectorized over all ping-pairs in a segment at once.
• Cumulative — sum of pairwise distances reflects what the truck drove; displacement (first-to-last) would zero out for any loop.
• Inflation knob — straight-line GPS mileage systematically undercounts real road-network distance by 5–15% because trucks follow streets (which curve) while the line cuts corners. mileage_inflation_pct defaults to 0.0 (honest straight-line). Set to 0.08 for an 8% road-network approximation. Never silently inflate; let the operator opt in.

Higher accuracy would require a road network (OpenStreetMap, OSM). That’s a future release; for now the inflation knob calibrates against whatever ground-truth dataset the operator can produce.

4 Load numbers — the workday backbone

Walk the timeline chronologically. Bookend depot segments get load_number = NaN. The first active segment after depot_departure starts load 1. After every dump, look ahead: if any future segment is a collection or dump, this is a new load. If the next active segment is depot_arrival, the truck is going home; that windshield stays in the current load.

DEPOT_DEPARTURE     load=NaN
windshield          load=1   (going to first route)
collection (A)      load=1
dump                load=1   (load 1 complete)
windshield          load=2   (more work ahead, going to next route)
collection (B)      load=2
dump                load=2   (load 2 complete)
windshield          load=2   (going home — no future work)
DEPOT_ARRIVAL       load=NaN

5 Choreography violations — the operational payoff

The timeline is descriptive. The violations are what make it useful:

• loaded_depot_return (severity high) — day ended on a collection segment without a closing dump. Truck went home loaded.
• loaded_depot_departure (severity high) — day started with a dump before any collection. Truck started loaded from yesterday.
• overrun_loads (severity medium) — more than 3 loads. Review for shift overrun.
• mid_load_route_switch (severity low) — a single load touched multiple route_ids. Could be HTC parcels off the main route, or could indicate routing inefficiency.

This is the analytical payoff of the segment abstraction. A pile of GPS pings is just dots; a load-organized timeline is a workday; flagged violations are a review queue.

6 Driver + output layout — build_all_segments()

build_all_segments(
    enriched_path="enriched/2026-01-18/815001.parquet",
    out_root="segments/",
)
# writes:
#   segments/timeline/2026-01-18/815001.parquet
#   segments/violations/2026-01-18/815001.parquet

One enriched vehicle-day in, two parquets out. Loop over the L7 master index and you get the whole fleet’s timeline in one batch.

7 Tests + commit

26 tests covering the haversine math, phase derivation cascade, gap-and-island grouping, load numbering edge cases, mileage inflation, and every violation type. All synthetic data — no DuckDB, no network. The whole suite runs in under 2 seconds.

pip install -e ".[dev,geotab,postgres]"
ruff check .
pytest -q
git add . && git commit -m "Lesson 9: segments — load-organized timeline + violations"
git push origin main