// AK-P16b · appointment lifecycle state machine (PURE, M06 A.5 / M129). The allowed // transitions are validated here so the service + tests share one source of truth. // // scheduled ──mark_held──▶ held // scheduled ──mark_no_show──▶ no_show // scheduled ──cancel──▶ cancelled // scheduled ──reschedule──▶ rescheduled (a successor appointment is created) // scheduled ──reassign──▶ scheduled (provider changes, status unchanged) // Terminal states (held/cancelled/no_show/rescheduled) accept no further action. export type AppointmentStatus = "scheduled" | "held" | "cancelled" | "no_show" | "rescheduled"; export type LifecycleAction = "mark_held" | "mark_no_show" | "cancel" | "reschedule" | "reassign"; const ALLOWED_FROM: Record = { mark_held: ["scheduled"], mark_no_show: ["scheduled"], cancel: ["scheduled"], reschedule: ["scheduled"], reassign: ["scheduled"], }; /** The status an action moves the appointment to, or null when it is unchanged. */ const STATUS_AFTER: Record = { mark_held: "held", mark_no_show: "no_show", cancel: "cancelled", reschedule: "rescheduled", reassign: null, }; export class BookingTransitionError extends Error { readonly code = "invalid_transition"; readonly from: AppointmentStatus; readonly action: LifecycleAction; constructor(from: AppointmentStatus, action: LifecycleAction) { super(`invalid_transition:${from}:${action}`); this.name = "BookingTransitionError"; this.from = from; this.action = action; } } /** True when `action` is allowed from `status`. */ export function canTransition(status: AppointmentStatus, action: LifecycleAction): boolean { return ALLOWED_FROM[action].includes(status); } /** Throw BookingTransitionError unless `action` is allowed from `status`. */ export function assertTransition(status: AppointmentStatus, action: LifecycleAction): void { if (!canTransition(status, action)) { throw new BookingTransitionError(status, action); } } /** The resulting status for an action (null = unchanged, e.g. reassign). */ export function statusAfter(action: LifecycleAction): AppointmentStatus | null { return STATUS_AFTER[action]; } /** Whether the action sends a customer-facing email (M06 Block I/D). */ export function notifiesCustomer(action: LifecycleAction): boolean { return action === "cancel" || action === "reschedule" || action === "reassign"; }