Multi-site planning

Multi-site planning adds two things to a roster: permission to work at a place and enough time to travel between places. It does not treat posts inside the same building as separate journeys.

Site, post, and home site

• A site is geographic.
• A post is a responsibility at one site.
• homeSiteId is a worker preference.
• A non-empty siteIds list is a hard permission boundary.

ts
await fivexer.roster.setTerms('worker_anna', {
  homeSiteId: 'site_north',
  siteIds: ['site_north', 'site_south'],
});

An empty siteIds list means all sites are allowed. It does not mean no sites. Use an explicit non-empty allow-list when access, induction, or contract scope limits where a person may work.

State travel time explicitly when it matters

ts
await fivexer.roster.updateSite('site_north', {
  travelMinutesTo: { site_south: 35 },
});

await fivexer.roster.updateSite('site_south', {
  travelMinutesTo: { site_north: 50 },
});

Travel matrices are asymmetric on purpose. The morning trip into a city and the evening trip out may differ. Resolution order is:

1. explicit origin-to-destination minutes;
2. coordinate distance estimated with travelSpeedKmh;
3. unknown.

Set travelSpeedKmh: null when you prefer unknown to an estimate. Unknown travel does not become zero and should remain visibly unknown in your UI.

How the solver uses location

For consecutive assignments at different sites, the hard travel-gap rule checks whether the interval between shifts is long enough for the known journey. The person timeline includes sibling contracts and history supplied from outside the period, so changing contract IDs cannot hide a cross-site collision.

The solver can also prefer home-site assignments as a soft objective. A preference may break a tie between legal plans; it cannot override qualification, permission, rest, or coverage.

How cover candidates are located

For urgent cover, a candidate’s origin is:

1. their nearest same-day assignment before the opening; otherwise
2. their home site; otherwise
3. unknown.

Candidate results include originSiteId, travelMinutes, distanceKm, and isHomeSite when those facts can be established. Present the origin alongside the distance: “35 minutes from South depot” is actionable in a way that “nearby” is not.

Practical setup checklist

1. Create every operational site.
2. Attach every post to the site where it is performed.
3. Add explicit travel minutes for common or time-sensitive journeys.
4. Add coordinates only where estimates are acceptable.
5. Record each worker’s home site and true site allow-list.
6. Keep past assignments or history available at period boundaries.
7. Test one known impossible cross-site succession and confirm lint blocks it.

Return to sites, posts, and shifts for coverage setup or time off and cover for the call-in workflow.