feat: add support for maps with traffic

[diogodanielsoaresferreira]

Summary

Adds support for traffic-aware travel times in the maps model. Travel-time matrices can now be enriched with time-of-day traffic information using configurable time-frame bucketing strategies, enabling solver models to plan with realistic, traffic-sensitive routing.

Changes

New opt-in enrichment path for solver models whose travel times and distances vary with time of day. Existing LocationsAwareSolverModel + TravelTimeMatrixEnricher untouched.

• the usage of matrices with traffic is decided by the model based on which solver model is used (LocationsAndTrafficAwareSolverModel or LocationsAwareSolverModel); enricher supports both.
• new TimeframeBucketing interface + two impls: StaticDaypartBucketing (morning 00–12, midday 12–15, afternoon 15+) and SingleTimeframeBucketing (one key, used by Haversine).
• New MapService method taking an availability map: applies the bucketing, fans out one concurrent bundled call per timeframe, caches the composite.
• for now, getWaypoints still use a map with timeframe "static", which means that for models to use it, we always need the 3 timeframe maps + static one

[sonarqubecloud]

Quality Gate failed

Failed conditions
28.8% Coverage on New Code (required ≥ 70%)
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[rsynek]

To revive the open point from https://github.com/TimefoldAI/timefold-models-sdk/pull/975, let me copy here this summary:

model interface	traffic enabled	data fetched	how to fetch
LocationsAware	off	one matrix, no traffic	getTravelTimeTo(other)
LocationsAware	on	one matrix, traffic at default timeframe	getTravelTimeTo(other)
LocationsAndTrafficAware	on	N matrices with N timeframes	getTravelTimeTo(other, t)
LocationsAndTrafficAware	off	one matrix wrapped as 1 timeframe for the whole day	getTravelTimeTo(other, t)

I see a problem with the second row. We should still return N matrices with N timeframes. Opposed to row number 3, the matrices will be larger, as we cannot prune them by the location availabilities.

[rsynek]

Ad "for now, getWaypoints still use a map with timeframe "static", which means that for models to use it, we always need the 3 timeframe maps + static one".

Does it mean we use different routes for computing the travel time (assuming the traffic data leads to different routes) than we show in the waypoints?

Discussed separately:

• The current OSRM call for waypoints does not support any departure times.
• Waypoints are used only for visualizations (and occasionally for debugging).
• Customer rather use dedicated routing apps.
• For now, we update the waypoints endpoint description to clearly state waypoints are for illustration only and with traffic data enabled, the routes they show might not match the routes used for travel time and distance calculation.

[diogodanielsoaresferreira]

To revive the open point from TimefoldAI/timefold-models-sdk#975, let me copy here this summary:
model interface traffic enabled data fetched how to fetch
LocationsAware off one matrix, no traffic getTravelTimeTo(other)
LocationsAware on one matrix, traffic at default timeframe getTravelTimeTo(other)
LocationsAndTrafficAware on N matrices with N timeframes getTravelTimeTo(other, t)
LocationsAndTrafficAware off one matrix wrapped as 1 timeframe for the whole day getTravelTimeTo(other, t)

I see a problem with the second row. We should still return N matrices with N timeframes. Opposed to row number 3, the matrices will be larger, as we cannot prune them by the location availabilities.

Why do we want to do this? my idea was that the model interface would be a clear separation between using/not using timestamps: if using LocationsAndTrafficAware, a departure time would always have to be sent to getTravelTime; if not, a departure time could not be sent. If we want to allow to have LocationsAware with multiple matrices, then we will have to change that assumption.

So the new table would be something like this:

model interface	traffic enabled	data fetched	how to fetch
LocationsAware	off	one matrix, no traffic	getTravelTimeTo(other), getTravelTimeTo(other, t)
LocationsAware	on	N matrices with N timeframes (not pruned)	getTravelTimeTo(other), getTravelTimeTo(other, t)
LocationsAndTrafficAware	on	N matrices with N timeframes (pruned)	getTravelTimeTo(other), getTravelTimeTo(other, t)
LocationsAndTrafficAware	off	one matrix wrapped as 1 timeframe for the whole day	getTravelTimeTo(other), getTravelTimeTo(other, t)

• if traffic is enabled, we will always fetch NxN matrices
• clients can always fetch a travelTime using or not using departureTime: this will not fail, but it will accept everything silently and redirect to the correct matrix
• If only one matrix is available, getTravelTimeTo(other, t) will use that matrix
• If more than one matrix is available, getTravelTimeTo(other) will use some default matrix

@rsynek is this your idea?