How Versioned Provider-Ranking Policies Work

Hard constraints determine which providers qualify. Ranking policies determine the order in which they are presented.

The distinction matters: a ranking policy must never exclude providers. It can only score them.

Weights

A policy assigns a point value to each preference signal:

{
  "weights": {
    "preferredLanguage":  20,
    "preferredDayPart":   15,
    "earliestAvailable":  30,
    "providerContinuity": 20,
    "workloadBalance":    10,
    "preferredLocation":   5
  },
  "tieBreakers": ["earliest_start", "provider_id"]
}

A provider that speaks the preferred language gets +20 points. A provider in the preferred day-part gets +15 points. These signals are cumulative.

Tie-breaking

Tie-breaking is deterministic. When two options have the same score:

Earliest start time wins
If still tied, lowest current workload wins
If still tied, provider ID (alphabetical) wins

This guarantees that the same resolution request always returns options in the same order for the same policy version.

Policy versioning

Every time a policy is activated, an immutable version snapshot is created. Every resolution records:

policyId — the policy used
policyVersion — the version at activation time
providerGraphVersion — the provider network state at resolution time

This makes every past resolution auditable and reproducible.

Activating a new policy version does not change past resolutions. Historical data remains tied to the policy version that was active at the time.

Simulate before activating

Before activating a policy, simulate it against candidate data:

POST /api/v2/ranking-policies/{policyId}/simulate

The response shows how each candidate would be ranked under the new policy — without committing anything.

Rollback

Roll back by activating a previous policy version. Since versions are immutable, the previous behavior is exactly reproducible.

Per-organization policies

Each organization in a multi-tenant platform can have its own ranking policy. A behavioral health organization might weight continuity heavily; a same-day urgent-care platform might weight earliest-available more.