dabke 0.81.1 → 0.83.0

package/src/cpsat/rules/min-rest-between-shifts.ts

@@ -1,11 +1,14 @@
 import * as z from "zod";
-import type { CompilationRule } from "../model-builder.js";
-import { priorityToPenalty } from "../utils.js";
+import type { CompilationRule, RuleValidationContext } from "../model-builder.js";
+import type { ResolvedShiftAssignment } from "../response.js";
+import { normalizeEndMinutes, priorityToPenalty, timeOfDayToMinutes } from "../utils.js";
+import type { ValidationReporter } from "../validation-reporter.js";
 import {
   PrioritySchema,
   entityScope,
   parseEntityScope,
   resolveMembersFromScope,
+  ruleGroup,
 } from "./scope.types.js";
 
 const MinRestBetweenShiftsSchema = z
@@ -41,6 +44,11 @@ export function createMinRestBetweenShiftsRule(
   const scope = parseEntityScope(parsed);
   const { hours, priority } = parsed;
   const minMinutes = hours * 60;
+  const group = ruleGroup(
+    `min-rest-between-shifts:${hours}`,
+    `Min ${hours}h rest between shifts`,
+    scope,
+  );
 
   return {
     compile(b) {
@@ -121,5 +129,87 @@ export function createMinRestBetweenShiftsRule(
         }
       }
     },
+
+    validate(
+      assignments: ResolvedShiftAssignment[],
+      reporter: ValidationReporter,
+      context: RuleValidationContext,
+    ) {
+      if (priority === "MANDATORY") return;
+
+      const members = resolveMembersFromScope(scope, context.members);
+      if (members.length === 0) return;
+
+      const memberIds = new Set(members.map((m) => m.id));
+
+      // Group assignments by member, sort by day then start time
+      const byMember = new Map<string, ResolvedShiftAssignment[]>();
+      for (const a of assignments) {
+        if (!memberIds.has(a.memberId)) continue;
+        const list = byMember.get(a.memberId) ?? [];
+        list.push(a);
+        byMember.set(a.memberId, list);
+      }
+
+      for (const [memberId, memberAssignments] of byMember) {
+        const sorted = memberAssignments.toSorted((a, b) => {
+          if (a.day !== b.day) return a.day < b.day ? -1 : 1;
+          return timeOfDayToMinutes(a.startTime) - timeOfDayToMinutes(b.startTime);
+        });
+
+        let violated = false;
+        for (let i = 0; i < sorted.length - 1; i++) {
+          const current = sorted[i]!;
+          const next = sorted[i + 1]!;
+
+          const currentEndMin = timeOfDayToMinutes(current.endTime);
+          const normalizedEnd = normalizeEndMinutes(
+            timeOfDayToMinutes(current.startTime),
+            currentEndMin,
+          );
+          const nextStartMin = timeOfDayToMinutes(next.startTime);
+
+          // Calculate gap considering day boundaries
+          let gap: number;
+          if (current.day === next.day) {
+            gap = nextStartMin - normalizedEnd;
+          } else {
+            // Different days: account for the day boundary
+            const dayDiff = daysBetween(current.day, next.day);
+            gap = dayDiff * 24 * 60 - normalizedEnd + nextStartMin;
+          }
+
+          if (gap >= 0 && gap < minMinutes) {
+            reporter.reportRuleViolation({
+              rule: "min-rest-between-shifts",
+              message: `${memberId} has ${Math.round((gap / 60) * 10) / 10}h rest between shifts on ${current.day} and ${next.day}, need ${hours}h`,
+              context: { memberIds: [memberId], days: [current.day, next.day] },
+              shortfall: minMinutes - gap,
+              group,
+            });
+            violated = true;
+          }
+        }
+
+        if (!violated && sorted.length > 1) {
+          reporter.reportRulePassed({
+            rule: "min-rest-between-shifts",
+            message: `${memberId} has ${hours}h+ rest between all shifts`,
+            context: {
+              memberIds: [memberId],
+              days: [...new Set(sorted.map((a) => a.day))],
+            },
+            group,
+          });
+        }
+      }
+    },
   };
 }
+
+/** Compute day difference from YYYY-MM-DD strings. */
+function daysBetween(day1: string, day2: string): number {
+  const d1 = new Date(`${day1}T00:00:00Z`);
+  const d2 = new Date(`${day2}T00:00:00Z`);
+  return Math.round((d2.getTime() - d1.getTime()) / (24 * 60 * 60 * 1000));
+}

package/src/cpsat/rules/minimize-cost.ts

@@ -4,12 +4,7 @@ import type { CompilationRule, CostContribution } from "../model-builder.js";
 import type { ShiftPattern, SchedulingMember } from "../types.js";
 import type { ShiftAssignment } from "../response.js";
 import { COST_CATEGORY } from "../cost.js";
-import {
-  OBJECTIVE_WEIGHTS,
-  timeOfDayToMinutes,
-  normalizeEndMinutes,
-  splitIntoWeeks,
-} from "../utils.js";
+import { OBJECTIVE_WEIGHTS, splitIntoWeeks } from "../utils.js";
 import {
   entityScope,
   timeScope,
@@ -18,6 +13,7 @@ import {
   resolveMembersFromScope,
   resolveActiveDaysFromScope,
 } from "./scope.types.js";
+import { getHourlyRate, getSalariedPay, patternDurationMinutes } from "./cost-utils.js";
 
 const MinimizeCostSchema = entityScope(["members", "roles", "skills"]).and(
   timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]),
@@ -26,29 +22,6 @@ const MinimizeCostSchema = entityScope(["members", "roles", "skills"]).and(
 /** Configuration for {@link createMinimizeCostRule}. */
 export type MinimizeCostConfig = z.infer<typeof MinimizeCostSchema>;
 
-/** Returns the hourly rate for a member, or undefined if not hourly. */
-function getHourlyRate(member: SchedulingMember): number | undefined {
-  if (!member.pay) return undefined;
-  if ("hourlyRate" in member.pay) return member.pay.hourlyRate;
-  return undefined;
-}
-
-/** Returns salaried pay info, or undefined if not salaried. */
-function getSalariedPay(
-  member: SchedulingMember,
-): { annual: number; hoursPerWeek: number } | undefined {
-  if (!member.pay) return undefined;
-  if ("annual" in member.pay) return member.pay;
-  return undefined;
-}
-
-/** Computes shift duration in minutes from a pattern. */
-function patternDurationMinutes(pattern: ShiftPattern): number {
-  const start = timeOfDayToMinutes(pattern.startTime);
-  const end = normalizeEndMinutes(start, timeOfDayToMinutes(pattern.endTime));
-  return end - start;
-}
-
 /**
  * Creates the minimize-cost rule.
  *

package/src/cpsat/rules/must-assign.ts

@@ -0,0 +1,108 @@
+import * as z from "zod";
+import { DayOfWeekSchema } from "../../types.js";
+import type { CompilationRule } from "../model-builder.js";
+import type { Term } from "../types.js";
+import { priorityToPenalty, splitIntoWeeks } from "../utils.js";
+import {
+  entityScope,
+  parseEntityScope,
+  resolveMembersFromScope,
+  ruleGroup,
+} from "./scope.types.js";
+
+/** Internally always HIGH. Not user-configurable. */
+const MUST_ASSIGN_PENALTY = priorityToPenalty("HIGH");
+
+const MustAssignSchema = z
+  .object({
+    weekStartsOn: DayOfWeekSchema.optional(),
+  })
+  .and(entityScope(["members", "roles", "skills"]));
+
+/**
+ * Configuration for {@link createMustAssignRule}.
+ *
+ * - `weekStartsOn` (optional): which day starts the week; defaults to
+ *   {@link ModelBuilder.weekStartsOn}
+ *
+ * Entity scoping (at most one): `memberIds`, `roleIds`, `skillIds`
+ */
+export type MustAssignConfig = z.infer<typeof MustAssignSchema>;
+
+/**
+ * Guarantees that targeted members appear on the schedule.
+ *
+ * @remarks
+ * Use this for staffing obligations: salaried employees who are paid
+ * regardless of whether they work, or contracted staff who must be
+ * rostered. The solver ensures each targeted member has at least one
+ * assignment per scheduling week.
+ *
+ * Always compiles as a soft constraint (HIGH priority internally) so the
+ * schedule still generates when a member genuinely cannot be placed
+ * (e.g., full week of absences, no compatible shift patterns). Violations
+ * surface as validation warnings with distinct messaging from
+ * `min-days-week`.
+ *
+ * Unlike {@link createMinDaysWeekRule}, this rule communicates a staffing
+ * obligation rather than a scheduling preference. Validation messages
+ * reflect this: "Alice was not assigned (staffing obligation)" rather
+ * than "Alice worked 0 days, minimum was 1."
+ *
+ * @param config - See {@link MustAssignConfig}
+ *
+ * @example Ensure a salaried manager is always rostered
+ * ```ts
+ * createMustAssignRule({ memberIds: ["diana"] });
+ * ```
+ *
+ * @example Ensure all supervisors appear on the rota
+ * ```ts
+ * createMustAssignRule({ roleIds: ["supervisor"] });
+ * ```
+ */
+export function createMustAssignRule(config: MustAssignConfig): CompilationRule {
+  const parsed = MustAssignSchema.parse(config);
+  const scope = parseEntityScope(parsed);
+  const { weekStartsOn } = parsed;
+  const group = ruleGroup("must-assign", "Must assign", scope);
+
+  return {
+    compile(b) {
+      const members = resolveMembersFromScope(scope, b.members);
+      const weeks = splitIntoWeeks(b.days, weekStartsOn ?? b.weekStartsOn);
+
+      for (const emp of members) {
+        for (const weekDays of weeks) {
+          const terms: Term[] = [];
+
+          for (const day of weekDays) {
+            for (const pattern of b.shiftPatterns) {
+              if (!b.canAssign(emp, pattern)) continue;
+              if (!b.patternAvailableOnDay(pattern, day)) continue;
+              terms.push({ var: b.assignment(emp.id, pattern.id, day), coeff: 1 });
+            }
+          }
+
+          if (terms.length === 0) continue;
+
+          const weekLabel = weekDays[0]!;
+          const constraintId = `must-assign:${emp.id}:${weekLabel}`;
+
+          b.addSoftLinear(terms, ">=", 1, MUST_ASSIGN_PENALTY, constraintId);
+          b.reporter.trackConstraint({
+            id: constraintId,
+            type: "rule",
+            rule: "must-assign",
+            description: `${emp.id} not assigned in week starting ${weekLabel} (staffing obligation)`,
+            targetValue: 1,
+            comparator: ">=",
+            day: weekLabel,
+            context: { memberIds: [emp.id], days: weekDays },
+            group,
+          });
+        }
+      }
+    },
+  };
+}

package/src/cpsat/rules/overtime-daily-multiplier.ts

@@ -17,6 +17,7 @@ import {
   resolveMembersFromScope,
   resolveActiveDaysFromScope,
 } from "./scope.types.js";
+import { getHourlyRate, patternDurationMinutes } from "./cost-utils.js";
 
 const OvertimeDailyMultiplierSchema = z
   .object({
@@ -29,18 +30,6 @@ const OvertimeDailyMultiplierSchema = z
 /** Configuration for {@link createOvertimeDailyMultiplierRule}. */
 export type OvertimeDailyMultiplierConfig = z.infer<typeof OvertimeDailyMultiplierSchema>;
 
-function getHourlyRate(emp: SchedulingMember): number | undefined {
-  if (!emp.pay) return undefined;
-  if ("hourlyRate" in emp.pay) return emp.pay.hourlyRate;
-  return undefined;
-}
-
-function patternDurationMinutes(pattern: ShiftPattern): number {
-  const start = timeOfDayToMinutes(pattern.startTime);
-  const end = normalizeEndMinutes(start, timeOfDayToMinutes(pattern.endTime));
-  return end - start;
-}
-
 /**
  * Creates a daily overtime rate multiplier rule.
  *

package/src/cpsat/rules/overtime-daily-surcharge.ts

@@ -17,6 +17,7 @@ import {
   resolveMembersFromScope,
   resolveActiveDaysFromScope,
 } from "./scope.types.js";
+import { patternDurationMinutes } from "./cost-utils.js";
 
 const OvertimeDailySurchargeSchema = z
   .object({
@@ -29,12 +30,6 @@ const OvertimeDailySurchargeSchema = z
 /** Configuration for {@link createOvertimeDailySurchargeRule}. */
 export type OvertimeDailySurchargeConfig = z.infer<typeof OvertimeDailySurchargeSchema>;
 
-function patternDurationMinutes(pattern: ShiftPattern): number {
-  const start = timeOfDayToMinutes(pattern.startTime);
-  const end = normalizeEndMinutes(start, timeOfDayToMinutes(pattern.endTime));
-  return end - start;
-}
-
 /**
  * Creates a daily overtime flat surcharge rule.
  *

package/src/cpsat/rules/overtime-tiered-multiplier.ts

@@ -19,13 +19,18 @@ import {
   resolveMembersFromScope,
   resolveActiveDaysFromScope,
 } from "./scope.types.js";
+import { getHourlyRate, patternDurationMinutes } from "./cost-utils.js";
 
 const OvertimeTierSchema = z.object({
   after: z.number().min(0),
   factor: z.number().min(1),
 });
 
-/** A single tier in a tiered overtime configuration. */
+/**
+ * A single tier in a tiered overtime configuration.
+ *
+ * @category Cost Optimization
+ */
 export type OvertimeTier = z.infer<typeof OvertimeTierSchema>;
 
 const OvertimeTieredMultiplierSchema = z
@@ -39,18 +44,6 @@ const OvertimeTieredMultiplierSchema = z
 /** Configuration for {@link createOvertimeTieredMultiplierRule}. */
 export type OvertimeTieredMultiplierConfig = z.infer<typeof OvertimeTieredMultiplierSchema>;
 
-function getHourlyRate(emp: SchedulingMember): number | undefined {
-  if (!emp.pay) return undefined;
-  if ("hourlyRate" in emp.pay) return emp.pay.hourlyRate;
-  return undefined;
-}
-
-function patternDurationMinutes(pattern: ShiftPattern): number {
-  const start = timeOfDayToMinutes(pattern.startTime);
-  const end = normalizeEndMinutes(start, timeOfDayToMinutes(pattern.endTime));
-  return end - start;
-}
-
 /**
  * Creates a multi-threshold weekly overtime multiplier rule.
  *

package/src/cpsat/rules/overtime-weekly-multiplier.ts

@@ -19,6 +19,7 @@ import {
   resolveMembersFromScope,
   resolveActiveDaysFromScope,
 } from "./scope.types.js";
+import { getHourlyRate, patternDurationMinutes } from "./cost-utils.js";
 
 const OvertimeWeeklyMultiplierSchema = z
   .object({
@@ -32,18 +33,6 @@ const OvertimeWeeklyMultiplierSchema = z
 /** Configuration for {@link createOvertimeWeeklyMultiplierRule}. */
 export type OvertimeWeeklyMultiplierConfig = z.infer<typeof OvertimeWeeklyMultiplierSchema>;
 
-function getHourlyRate(emp: SchedulingMember): number | undefined {
-  if (!emp.pay) return undefined;
-  if ("hourlyRate" in emp.pay) return emp.pay.hourlyRate;
-  return undefined;
-}
-
-function patternDurationMinutes(pattern: ShiftPattern): number {
-  const start = timeOfDayToMinutes(pattern.startTime);
-  const end = normalizeEndMinutes(start, timeOfDayToMinutes(pattern.endTime));
-  return end - start;
-}
-
 /**
  * Creates a weekly overtime rate multiplier rule.
  *

package/src/cpsat/rules/overtime-weekly-surcharge.ts

@@ -19,6 +19,7 @@ import {
   resolveMembersFromScope,
   resolveActiveDaysFromScope,
 } from "./scope.types.js";
+import { patternDurationMinutes } from "./cost-utils.js";
 
 const OvertimeWeeklySurchargeSchema = z
   .object({
@@ -32,12 +33,6 @@ const OvertimeWeeklySurchargeSchema = z
 /** Configuration for {@link createOvertimeWeeklySurchargeRule}. */
 export type OvertimeWeeklySurchargeConfig = z.infer<typeof OvertimeWeeklySurchargeSchema>;
 
-function patternDurationMinutes(pattern: ShiftPattern): number {
-  const start = timeOfDayToMinutes(pattern.startTime);
-  const end = normalizeEndMinutes(start, timeOfDayToMinutes(pattern.endTime));
-  return end - start;
-}
-
 /**
  * Creates a weekly overtime flat surcharge rule.
  *

package/src/cpsat/rules/registry.ts

@@ -3,13 +3,16 @@ import {
   createAssignmentPriorityRule,
   createLocationPreferenceRule,
   createMaxConsecutiveDaysRule,
+  createMaxDaysWeekRule,
   createMaxHoursDayRule,
   createMaxHoursWeekRule,
   createMaxShiftsDayRule,
   createMinConsecutiveDaysRule,
+  createMinDaysWeekRule,
   createMinHoursDayRule,
   createMinHoursWeekRule,
   createMinRestBetweenShiftsRule,
+  createMustAssignRule,
   createTimeOffRule,
   createMinimizeCostRule,
   createDayCostMultiplierRule,
@@ -27,18 +30,21 @@ import type {
   CpsatRuleName,
 } from "./rules.types.js";
 
-export const builtInCpsatRuleFactories: BuiltInCpsatRuleFactories = {
+export const builtInCpsatRuleFactories = {
   "assign-together": createAssignTogetherRule,
   "assignment-priority": createAssignmentPriorityRule,
   "location-preference": createLocationPreferenceRule,
   "max-consecutive-days": createMaxConsecutiveDaysRule,
+  "max-days-week": createMaxDaysWeekRule,
   "max-hours-day": createMaxHoursDayRule,
   "max-hours-week": createMaxHoursWeekRule,
   "max-shifts-day": createMaxShiftsDayRule,
   "min-consecutive-days": createMinConsecutiveDaysRule,
+  "min-days-week": createMinDaysWeekRule,
   "min-hours-day": createMinHoursDayRule,
   "min-hours-week": createMinHoursWeekRule,
   "min-rest-between-shifts": createMinRestBetweenShiftsRule,
+  "must-assign": createMustAssignRule,
   "time-off": createTimeOffRule,
   "minimize-cost": createMinimizeCostRule,
   "day-cost-multiplier": createDayCostMultiplierRule,
@@ -49,7 +55,7 @@ export const builtInCpsatRuleFactories: BuiltInCpsatRuleFactories = {
   "overtime-daily-multiplier": createOvertimeDailyMultiplierRule,
   "overtime-daily-surcharge": createOvertimeDailySurchargeRule,
   "overtime-tiered-multiplier": createOvertimeTieredMultiplierRule,
-};
+} satisfies BuiltInCpsatRuleFactories;
 
 /**
  * Creates a rule factory map, preventing overriding built-in rules.

package/src/cpsat/rules/resolver.ts

@@ -45,11 +45,11 @@ export function getMemberIdsForScope(
     }
     case "roles":
       return members
-        .filter((e) => e.roles.some((r) => entity.roleIds.includes(r)))
+        .filter((e) => e.roleIds.some((r) => entity.roleIds.includes(r)))
         .map((e) => e.id);
     case "skills":
       return members
-        .filter((e) => e.skills?.some((s) => entity.skillIds.includes(s)))
+        .filter((e) => e.skillIds?.some((s) => entity.skillIds.includes(s)))
         .map((e) => e.id);
     case "global":
     default:

package/src/cpsat/rules/rules.types.ts

@@ -8,13 +8,16 @@ export interface CpsatRuleRegistry {
   "assignment-priority": import("./assignment-priority.js").AssignmentPriorityConfig;
   "location-preference": import("./location-preference.js").LocationPreferenceConfig;
   "max-consecutive-days": import("./max-consecutive-days.js").MaxConsecutiveDaysConfig;
+  "max-days-week": import("./max-days-week.js").MaxDaysWeekConfig;
   "max-hours-day": import("./max-hours-day.js").MaxHoursDayConfig;
   "max-hours-week": import("./max-hours-week.js").MaxHoursWeekConfig;
   "max-shifts-day": import("./max-shifts-day.js").MaxShiftsDayConfig;
   "min-consecutive-days": import("./min-consecutive-days.js").MinConsecutiveDaysConfig;
+  "min-days-week": import("./min-days-week.js").MinDaysWeekConfig;
   "min-hours-day": import("./min-hours-day.js").MinHoursDayConfig;
   "min-hours-week": import("./min-hours-week.js").MinHoursWeekConfig;
   "min-rest-between-shifts": import("./min-rest-between-shifts.js").MinRestBetweenShiftsConfig;
+  "must-assign": import("./must-assign.js").MustAssignConfig;
   "time-off": import("./time-off.js").TimeOffConfig;
   "minimize-cost": import("./minimize-cost.js").MinimizeCostConfig;
   "day-cost-multiplier": import("./day-cost-multiplier.js").DayCostMultiplierConfig;

package/src/cpsat/rules/scope.types.ts

@@ -35,8 +35,10 @@
 
 import * as z from "zod";
 import { DayOfWeekSchema, type DayOfWeek } from "../../types.js";
+import { toDayOfWeekUTC } from "../../datetime.utils.js";
 import type { SchedulingMember } from "../types.js";
 import { parseDayString } from "../utils.js";
+import { assertSafeKeySegments, type ValidationGroup } from "../validation.types.js";
 
 // ============================================================================
 // Priority
@@ -85,7 +87,11 @@ type InactiveEntityFields = {
 
 type NonEmptyArray<T> = [T, ...T[]];
 
-/** Recurring calendar period for time scoping. */
+/**
+ * Recurring calendar period for time scoping.
+ *
+ * @category Supporting Types
+ */
 export interface RecurringPeriod {
   name: string;
   startMonth: number;
@@ -470,9 +476,9 @@ export function resolveMembersFromScope(
       return members.filter((e) => idSet.has(e.id));
     }
     case "roles":
-      return members.filter((e) => e.roles.some((r) => scope.roleIds.includes(r)));
+      return members.filter((e) => e.roleIds.some((r) => scope.roleIds.includes(r)));
     case "skills":
-      return members.filter((e) => e.skills?.some((s) => scope.skillIds.includes(s)));
+      return members.filter((e) => e.skillIds?.some((s) => scope.skillIds.includes(s)));
     case "global":
     default:
       return members;
@@ -494,8 +500,7 @@ export function resolveActiveDaysFromScope(scope: ParsedTimeScope, allDays: stri
       const targetDays = new Set(scope.days);
       return allDays.filter((day) => {
         const date = parseDayString(day);
-        const dayName = getDayOfWeekName(date.getUTCDay());
-        return targetDays.has(dayName);
+        return targetDays.has(toDayOfWeekUTC(date));
       });
     }
     case "recurring":
@@ -512,21 +517,6 @@ export function resolveActiveDaysFromScope(scope: ParsedTimeScope, allDays: stri
 // Internal Helpers
 // ============================================================================
 
-type DayName = "sunday" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday";
-
-function getDayOfWeekName(dayIndex: number): DayName {
-  const names: Record<number, DayName> = {
-    0: "sunday",
-    1: "monday",
-    2: "tuesday",
-    3: "wednesday",
-    4: "thursday",
-    5: "friday",
-    6: "saturday",
-  };
-  return names[dayIndex % 7] ?? "sunday";
-}
-
 function isDateInRecurringPeriod(
   month: number,
   dayOfMonth: number,
@@ -546,3 +536,66 @@ function isDateInRecurringPeriod(
     return true;
   }
 }
+
+/**
+ * Creates a validation group for a rule with a deterministic structural key.
+ *
+ * The key encodes the rule name (including parameters), entity scope, and
+ * time scope so that identical configurations always produce the same group.
+ *
+ * @param rule - Rule name with parameters, e.g. `"max-hours-week:40"`
+ * @param title - Human-readable label, e.g. `"Max 40h per week"`
+ * @param entity - Parsed entity scope (members, roles, skills, or global)
+ * @param time - Parsed time scope (optional)
+ */
+export function ruleGroup(
+  rule: string,
+  title: string,
+  entity: ParsedEntityScope,
+  time?: ParsedTimeScope,
+): ValidationGroup {
+  let key = `rule:${rule}`;
+
+  switch (entity.type) {
+    case "global":
+      break;
+    case "members":
+      assertSafeKeySegments(entity.memberIds, "member ID");
+      key += `:members:${entity.memberIds.toSorted().join(",")}`;
+      break;
+    case "roles":
+      assertSafeKeySegments(entity.roleIds, "role ID");
+      key += `:roles:${entity.roleIds.toSorted().join(",")}`;
+      break;
+    case "skills":
+      assertSafeKeySegments(entity.skillIds, "skill ID");
+      key += `:skills:${entity.skillIds.toSorted().join(",")}`;
+      break;
+  }
+
+  if (time && time.type !== "none") {
+    switch (time.type) {
+      case "dateRange":
+        key += `:range:${time.start}..${time.end}`;
+        break;
+      case "specificDates":
+        key += `:dates:${time.dates.toSorted().join(",")}`;
+        break;
+      case "dayOfWeek":
+        key += `:dow:${time.days.toSorted().join(",")}`;
+        break;
+      case "recurring":
+        assertSafeKeySegments(
+          time.periods.map((p) => p.name),
+          "recurring period name",
+        );
+        key += `:recurring:${time.periods
+          .map((p) => p.name)
+          .toSorted()
+          .join(",")}`;
+        break;
+    }
+  }
+
+  return { key, title };
+}

package/src/cpsat/rules/time-cost-surcharge.ts

@@ -3,6 +3,7 @@ import type { CompilationRule, CostContribution } from "../model-builder.js";
 import type { ShiftPattern, SchedulingMember } from "../types.js";
 import type { TimeOfDay } from "../../types.js";
 import type { ShiftAssignment } from "../response.js";
+import { COST_CATEGORY } from "../cost.js";
 import { timeOfDayToMinutes, normalizeEndMinutes, MINUTES_PER_DAY } from "../utils.js";
 import {
   entityScope,
@@ -158,7 +159,7 @@ export function createTimeCostSurchargeRule(config: TimeCostSurchargeConfig): Co
         entries.push({
           memberId: a.memberId,
           day: a.day,
-          category: "premium",
+          category: COST_CATEGORY.PREMIUM,
           amount,
         });
       }