export type AdminBookingRoundRobinCandidate = { readonly adminUserId: string; readonly eligible: boolean; readonly absent: boolean; readonly activeBookingCount: number; readonly lastAssignedAt: Date | null; }; export type AdminBookingRoundRobinExclusion = { readonly adminUserId: string; readonly reason: "ineligible" | "absent" | "slot_unavailable"; }; export type AdminBookingRoundRobinSelection = { readonly selectedHostAdminUserId: string; readonly eligibleHostAdminUserIds: readonly string[]; readonly excludedHosts: readonly AdminBookingRoundRobinExclusion[]; readonly loadSnapshot: readonly { readonly adminUserId: string; readonly activeBookingCount: number; readonly lastAssignedAt: string | null; }[]; readonly selectionReason: | "manual_override" | "least_load" | "oldest_last_assignment" | "stable_id"; }; export function selectAdminBookingHost(input: { readonly candidates: readonly AdminBookingRoundRobinCandidate[]; readonly availableHostAdminUserIds: readonly string[]; readonly manualHostAdminUserId?: string | null; }): AdminBookingRoundRobinSelection { const available = new Set(input.availableHostAdminUserIds); const excludedHosts: AdminBookingRoundRobinExclusion[] = []; const eligible = input.candidates.filter((candidate) => { if (!candidate.eligible) { excludedHosts.push({ adminUserId: candidate.adminUserId, reason: "ineligible", }); return false; } if (candidate.absent) { excludedHosts.push({ adminUserId: candidate.adminUserId, reason: "absent", }); return false; } if (!available.has(candidate.adminUserId)) { excludedHosts.push({ adminUserId: candidate.adminUserId, reason: "slot_unavailable", }); return false; } return true; }); if (eligible.length === 0) { throw new AdminBookingRoundRobinError("no_eligible_host"); } const sorted = [...eligible].sort(compareCandidates); const manualHost = input.manualHostAdminUserId ? eligible.find( (candidate) => candidate.adminUserId === input.manualHostAdminUserId ) : null; if (input.manualHostAdminUserId && !manualHost) { throw new AdminBookingRoundRobinError("manual_host_unavailable"); } const selected = manualHost ?? sorted[0]; const selectionReason = manualHost ? "manual_override" : deriveSelectionReason(sorted); return Object.freeze({ selectedHostAdminUserId: selected.adminUserId, eligibleHostAdminUserIds: Object.freeze( eligible .map((candidate) => candidate.adminUserId) .sort((left, right) => left.localeCompare(right)) ), excludedHosts: Object.freeze( excludedHosts.sort((left, right) => left.adminUserId.localeCompare(right.adminUserId) ) ), loadSnapshot: Object.freeze( eligible .map((candidate) => Object.freeze({ adminUserId: candidate.adminUserId, activeBookingCount: candidate.activeBookingCount, lastAssignedAt: candidate.lastAssignedAt?.toISOString() ?? null, }) ) .sort((left, right) => left.adminUserId.localeCompare(right.adminUserId) ) ), selectionReason, }); } function compareCandidates( left: AdminBookingRoundRobinCandidate, right: AdminBookingRoundRobinCandidate ): number { const loadDelta = left.activeBookingCount - right.activeBookingCount; if (loadDelta !== 0) return loadDelta; const leftAssignedAt = left.lastAssignedAt?.getTime() ?? 0; const rightAssignedAt = right.lastAssignedAt?.getTime() ?? 0; const assignmentDelta = leftAssignedAt - rightAssignedAt; if (assignmentDelta !== 0) return assignmentDelta; return left.adminUserId.localeCompare(right.adminUserId); } function deriveSelectionReason( sorted: readonly AdminBookingRoundRobinCandidate[] ): AdminBookingRoundRobinSelection["selectionReason"] { const first = sorted[0]; const second = sorted[1]; if (!second || first.activeBookingCount !== second.activeBookingCount) { return "least_load"; } if ( (first.lastAssignedAt?.getTime() ?? 0) !== (second.lastAssignedAt?.getTime() ?? 0) ) { return "oldest_last_assignment"; } return "stable_id"; } export class AdminBookingRoundRobinError extends Error { readonly code: "no_eligible_host" | "manual_host_unavailable"; constructor(code: AdminBookingRoundRobinError["code"]) { super(code); this.name = "AdminBookingRoundRobinError"; this.code = code; } }