dabke 0.81.1 → 0.83.0

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

@@ -2,7 +2,7 @@ import * as z from "zod";
 import type { CompilationRule, CostContribution } from "../model-builder.js";
 import type { ShiftPattern, SchedulingMember } from "../types.js";
 import type { ShiftAssignment } from "../response.js";
-import { timeOfDayToMinutes, normalizeEndMinutes } from "../utils.js";
+import { COST_CATEGORY } from "../cost.js";
 import {
   entityScope,
   timeScope,
@@ -11,6 +11,7 @@ import {
   resolveMembersFromScope,
   resolveActiveDaysFromScope,
 } from "./scope.types.js";
+import { patternDurationMinutes } from "./cost-utils.js";
 
 const DayCostSurchargeSchema = z
   .object({
@@ -22,12 +23,6 @@ const DayCostSurchargeSchema = z
 /** Configuration for {@link createDayCostSurchargeRule}. */
 export type DayCostSurchargeConfig = z.infer<typeof DayCostSurchargeSchema>;
 
-function patternDurationMinutes(pattern: ShiftPattern): number {
-  const start = timeOfDayToMinutes(pattern.startTime);
-  const end = normalizeEndMinutes(start, timeOfDayToMinutes(pattern.endTime));
-  return end - start;
-}
-
 /**
  * Creates a day-based flat surcharge rule.
  *
@@ -95,7 +90,7 @@ export function createDayCostSurchargeRule(config: DayCostSurchargeConfig): Comp
         entries.push({
           memberId: a.memberId,
           day: a.day,
-          category: "premium",
+          category: COST_CATEGORY.PREMIUM,
           amount,
         });
       }

package/src/cpsat/rules/index.ts

@@ -2,13 +2,16 @@ export { createAssignTogetherRule } from "./assign-together.js";
 export { createAssignmentPriorityRule } from "./assignment-priority.js";
 export { createLocationPreferenceRule } from "./location-preference.js";
 export { createMaxConsecutiveDaysRule } from "./max-consecutive-days.js";
+export { createMaxDaysWeekRule } from "./max-days-week.js";
 export { createMaxHoursDayRule } from "./max-hours-day.js";
 export { createMaxHoursWeekRule } from "./max-hours-week.js";
 export { createMaxShiftsDayRule } from "./max-shifts-day.js";
 export { createMinConsecutiveDaysRule } from "./min-consecutive-days.js";
+export { createMinDaysWeekRule } from "./min-days-week.js";
 export { createMinHoursDayRule } from "./min-hours-day.js";
 export { createMinHoursWeekRule } from "./min-hours-week.js";
 export { createMinRestBetweenShiftsRule } from "./min-rest-between-shifts.js";
+export { createMustAssignRule } from "./must-assign.js";
 export { createTimeOffRule } from "./time-off.js";
 export { createMinimizeCostRule } from "./minimize-cost.js";
 export { createDayCostMultiplierRule } from "./day-cost-multiplier.js";

package/src/cpsat/rules/max-consecutive-days.ts

@@ -6,6 +6,7 @@ import {
   entityScope,
   parseEntityScope,
   resolveMembersFromScope,
+  ruleGroup,
 } from "./scope.types.js";
 
 const MaxConsecutiveDaysSchema = z
@@ -39,6 +40,7 @@ export function createMaxConsecutiveDaysRule(config: MaxConsecutiveDaysConfig):
   const scope = parseEntityScope(parsed);
   const { days, priority } = parsed;
   const windowSize = days + 1;
+  const group = ruleGroup(`max-consecutive-days:${days}`, `Max ${days} consecutive days`, scope);
 
   return {
     compile(b) {
@@ -81,6 +83,9 @@ export function createMaxConsecutiveDaysRule(config: MaxConsecutiveDaysConfig):
             }
           }
 
+          const windowStart = windowDays[0]!;
+          const constraintId = `max-consecutive-days:${emp.id}:${windowStart}`;
+
           if (priority === "MANDATORY") {
             b.addLinear(
               worksDayVars.map((v) => ({ var: v, coeff: 1 })),
@@ -93,7 +98,19 @@ export function createMaxConsecutiveDaysRule(config: MaxConsecutiveDaysConfig):
               "<=",
               days,
               priorityToPenalty(priority),
+              constraintId,
             );
+            b.reporter.trackConstraint({
+              id: constraintId,
+              type: "rule",
+              rule: "max-consecutive-days",
+              description: `${emp.id} max ${days} consecutive days from ${windowStart}`,
+              targetValue: days,
+              comparator: "<=",
+              day: windowStart,
+              context: { memberIds: [emp.id], days: windowDays },
+              group,
+            });
           }
         }
       }

package/src/cpsat/rules/max-days-week.ts

@@ -0,0 +1,143 @@
+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 {
+  PrioritySchema,
+  entityScope,
+  timeScope,
+  parseEntityScope,
+  parseTimeScope,
+  resolveMembersFromScope,
+  resolveActiveDaysFromScope,
+  ruleGroup,
+} from "./scope.types.js";
+
+const MaxDaysWeekBase = z.object({
+  days: z.number().int().min(0),
+  priority: PrioritySchema,
+  weekStartsOn: DayOfWeekSchema.optional(),
+});
+
+const MaxDaysWeekSchema = MaxDaysWeekBase.and(entityScope(["members", "roles", "skills"])).and(
+  timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]),
+);
+
+/**
+ * Configuration for {@link createMaxDaysWeekRule}.
+ *
+ * - `days` (required): maximum number of days allowed per scheduling week
+ * - `priority` (required): how strictly the solver enforces this rule
+ * - `weekStartsOn` (optional): which day starts the week; defaults to {@link ModelBuilder.weekStartsOn}
+ *
+ * Entity scoping (at most one): `memberIds`, `roleIds`, `skillIds`
+ * Time scoping (at most one, optional): `dateRange`, `specificDates`, `dayOfWeek`, `recurringPeriods`
+ */
+export type MaxDaysWeekConfig = z.infer<typeof MaxDaysWeekSchema>;
+
+/**
+ * Caps total number of days a person can work within each scheduling week.
+ *
+ * @remarks
+ * Creates a binary "works on day" variable for each member and day, then
+ * constrains the weekly sum. This counts distinct days, regardless of how
+ * many shifts are assigned on a single day.
+ *
+ * @param config - See {@link MaxDaysWeekConfig}
+ * @example Limit everyone to 5 days per week
+ * ```ts
+ * createMaxDaysWeekRule({ days: 5, priority: "MANDATORY" });
+ * ```
+ *
+ * @example Part-time staff limited to 3 days
+ * ```ts
+ * createMaxDaysWeekRule({
+ *   roleIds: ["part-time"],
+ *   days: 3,
+ *   priority: "HIGH",
+ * });
+ * ```
+ */
+export function createMaxDaysWeekRule(config: MaxDaysWeekConfig): CompilationRule {
+  const parsed = MaxDaysWeekSchema.parse(config);
+  const entityScopeValue = parseEntityScope(parsed);
+  const timeScopeValue = parseTimeScope(parsed);
+  const { days, priority, weekStartsOn } = parsed;
+  const group = ruleGroup(
+    `max-days-week:${days}`,
+    `Max ${days}d per week`,
+    entityScopeValue,
+    timeScopeValue,
+  );
+
+  return {
+    compile(b) {
+      const targetMembers = resolveMembersFromScope(entityScopeValue, b.members);
+      const activeDays = resolveActiveDaysFromScope(timeScopeValue, b.days);
+
+      if (targetMembers.length === 0 || activeDays.length === 0) return;
+
+      const weeks = splitIntoWeeks(activeDays, weekStartsOn ?? b.weekStartsOn);
+
+      for (const emp of targetMembers) {
+        for (const weekDays of weeks) {
+          const weekWorkVars: string[] = [];
+
+          for (const day of weekDays) {
+            const dayAssignments = b.shiftPatterns
+              .filter((p) => b.canAssign(emp, p) && b.patternAvailableOnDay(p, day))
+              .map((p) => b.assignment(emp.id, p.id, day));
+
+            if (dayAssignments.length === 0) continue;
+
+            const worksVar = b.boolVar(`works_day_${emp.id}_${day}`);
+            weekWorkVars.push(worksVar);
+
+            // worksVar >= each assignment (if any assignment is 1, worksVar must be 1)
+            for (const assignVar of dayAssignments) {
+              b.addLinear(
+                [
+                  { var: worksVar, coeff: 1 },
+                  { var: assignVar, coeff: -1 },
+                ],
+                ">=",
+                0,
+              );
+            }
+
+            // worksVar <= sum(assignments) (if no assignment is 1, worksVar must be 0)
+            b.addLinear(
+              [{ var: worksVar, coeff: 1 }, ...dayAssignments.map((v) => ({ var: v, coeff: -1 }))],
+              "<=",
+              0,
+            );
+          }
+
+          if (weekWorkVars.length === 0) continue;
+
+          const weekLabel = weekDays[0]!;
+          const constraintId = `max-days-week:${emp.id}:${weekLabel}`;
+          const terms: Term[] = weekWorkVars.map((v) => ({ var: v, coeff: 1 }));
+
+          if (priority === "MANDATORY") {
+            b.addLinear(terms, "<=", days);
+          } else {
+            b.addSoftLinear(terms, "<=", days, priorityToPenalty(priority), constraintId);
+            b.reporter.trackConstraint({
+              id: constraintId,
+              type: "rule",
+              rule: "max-days-week",
+              description: `${emp.id} max ${days}d in week starting ${weekLabel}`,
+              targetValue: days,
+              comparator: "<=",
+              day: weekLabel,
+              context: { memberIds: [emp.id], days: weekDays },
+              group,
+            });
+          }
+        }
+      }
+    },
+  };
+}

package/src/cpsat/rules/max-hours-day.ts

@@ -10,6 +10,7 @@ import {
   parseTimeScope,
   resolveMembersFromScope,
   resolveActiveDaysFromScope,
+  ruleGroup,
 } from "./scope.types.js";
 
 const MaxHoursDaySchema = z
@@ -59,6 +60,12 @@ export function createMaxHoursDayRule(config: MaxHoursDayConfig): CompilationRul
   const timeScopeValue = parseTimeScope(parsed);
   const { hours, priority } = parsed;
   const maxMinutes = hours * 60;
+  const group = ruleGroup(
+    `max-hours-day:${hours}`,
+    `Max ${hours}h per day`,
+    entityScopeValue,
+    timeScopeValue,
+  );
 
   return {
     compile(b) {
@@ -81,10 +88,23 @@ export function createMaxHoursDayRule(config: MaxHoursDayConfig): CompilationRul
 
           if (terms.length === 0) continue;
 
+          const constraintId = `max-hours-day:${emp.id}:${day}`;
+
           if (priority === "MANDATORY") {
             b.addLinear(terms, "<=", maxMinutes);
           } else {
-            b.addSoftLinear(terms, "<=", maxMinutes, priorityToPenalty(priority));
+            b.addSoftLinear(terms, "<=", maxMinutes, priorityToPenalty(priority), constraintId);
+            b.reporter.trackConstraint({
+              id: constraintId,
+              type: "rule",
+              rule: "max-hours-day",
+              description: `${emp.id} max ${hours}h on ${day}`,
+              targetValue: maxMinutes,
+              comparator: "<=",
+              day,
+              context: { memberIds: [emp.id], days: [day] },
+              group,
+            });
           }
         }
       }

package/src/cpsat/rules/max-hours-week.ts

@@ -11,6 +11,7 @@ import {
   parseTimeScope,
   resolveMembersFromScope,
   resolveActiveDaysFromScope,
+  ruleGroup,
 } from "./scope.types.js";
 
 const MaxHoursWeekBase = z.object({
@@ -62,6 +63,12 @@ export function createMaxHoursWeekRule(config: MaxHoursWeekConfig): CompilationR
   const timeScopeValue = parseTimeScope(parsed);
   const { hours, priority, weekStartsOn } = parsed;
   const maxMinutes = hours * 60;
+  const group = ruleGroup(
+    `max-hours-week:${hours}`,
+    `Max ${hours}h per week`,
+    entityScopeValue,
+    timeScopeValue,
+  );
 
   return {
     compile(b) {
@@ -88,10 +95,24 @@ export function createMaxHoursWeekRule(config: MaxHoursWeekConfig): CompilationR
 
           if (terms.length === 0) continue;
 
+          const weekLabel = weekDays[0]!;
+          const constraintId = `max-hours-week:${emp.id}:${weekLabel}`;
+
           if (priority === "MANDATORY") {
             b.addLinear(terms, "<=", maxMinutes);
           } else {
-            b.addSoftLinear(terms, "<=", maxMinutes, priorityToPenalty(priority));
+            b.addSoftLinear(terms, "<=", maxMinutes, priorityToPenalty(priority), constraintId);
+            b.reporter.trackConstraint({
+              id: constraintId,
+              type: "rule",
+              rule: "max-hours-week",
+              description: `${emp.id} max ${hours}h in week starting ${weekLabel}`,
+              targetValue: maxMinutes,
+              comparator: "<=",
+              day: weekLabel,
+              context: { memberIds: [emp.id], days: weekDays },
+              group,
+            });
           }
         }
       }

package/src/cpsat/rules/max-shifts-day.ts

@@ -10,6 +10,7 @@ import {
   parseTimeScope,
   resolveMembersFromScope,
   resolveActiveDaysFromScope,
+  ruleGroup,
 } from "./scope.types.js";
 
 const MaxShiftsDaySchema = z
@@ -61,6 +62,12 @@ export function createMaxShiftsDayRule(config: MaxShiftsDayConfig): CompilationR
   const entityScopeValue = parseEntityScope(parsed);
   const timeScopeValue = parseTimeScope(parsed);
   const { shifts, priority } = parsed;
+  const group = ruleGroup(
+    `max-shifts-day:${shifts}`,
+    `Max ${shifts} shift${shifts === 1 ? "" : "s"} per day`,
+    entityScopeValue,
+    timeScopeValue,
+  );
 
   return {
     compile(b) {
@@ -83,10 +90,23 @@ export function createMaxShiftsDayRule(config: MaxShiftsDayConfig): CompilationR
 
           if (terms.length === 0) continue;
 
+          const constraintId = `max-shifts-day:${emp.id}:${day}`;
+
           if (priority === "MANDATORY") {
             b.addLinear(terms, "<=", shifts);
           } else {
-            b.addSoftLinear(terms, "<=", shifts, priorityToPenalty(priority));
+            b.addSoftLinear(terms, "<=", shifts, priorityToPenalty(priority), constraintId);
+            b.reporter.trackConstraint({
+              id: constraintId,
+              type: "rule",
+              rule: "max-shifts-day",
+              description: `${emp.id} max ${shifts} shift${shifts === 1 ? "" : "s"} on ${day}`,
+              targetValue: shifts,
+              comparator: "<=",
+              day,
+              context: { memberIds: [emp.id], days: [day] },
+              group,
+            });
           }
         }
       }

package/src/cpsat/rules/min-consecutive-days.ts

@@ -6,6 +6,7 @@ import {
   entityScope,
   parseEntityScope,
   resolveMembersFromScope,
+  ruleGroup,
 } from "./scope.types.js";
 
 const MinConsecutiveDaysSchema = z
@@ -39,6 +40,7 @@ export function createMinConsecutiveDaysRule(config: MinConsecutiveDaysConfig):
   const parsed = MinConsecutiveDaysSchema.parse(config);
   const scope = parseEntityScope(parsed);
   const { days, priority } = parsed;
+  const group = ruleGroup(`min-consecutive-days:${days}`, `Min ${days} consecutive days`, scope);
 
   return {
     compile(b) {
@@ -132,10 +134,23 @@ export function createMinConsecutiveDaysRule(config: MinConsecutiveDaysConfig):
             { var: startVar, coeff: -days },
           ];
 
+          const constraintId = `min-consecutive-days:${emp.id}:${dayLabel}`;
+
           if (priority === "MANDATORY") {
             b.addLinear(terms, ">=", 0);
           } else {
-            b.addSoftLinear(terms, ">=", 0, priorityToPenalty(priority));
+            b.addSoftLinear(terms, ">=", 0, priorityToPenalty(priority), constraintId);
+            b.reporter.trackConstraint({
+              id: constraintId,
+              type: "rule",
+              rule: "min-consecutive-days",
+              description: `${emp.id} min ${days} consecutive days from ${dayLabel}`,
+              targetValue: 0,
+              comparator: ">=",
+              day: dayLabel,
+              context: { memberIds: [emp.id], days: b.days.slice(i, i + days) },
+              group,
+            });
           }
         }
       }

package/src/cpsat/rules/min-days-week.ts

@@ -0,0 +1,120 @@
+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 {
+  PrioritySchema,
+  entityScope,
+  parseEntityScope,
+  resolveMembersFromScope,
+  ruleGroup,
+} from "./scope.types.js";
+
+const MinDaysWeekBase = z.object({
+  days: z.number().int().min(0),
+  priority: PrioritySchema,
+  weekStartsOn: DayOfWeekSchema.optional(),
+});
+
+const MinDaysWeekSchema = MinDaysWeekBase.and(entityScope(["members", "roles", "skills"]));
+
+/**
+ * Configuration for {@link createMinDaysWeekRule}.
+ *
+ * - `days` (required): minimum number of days required per scheduling week
+ * - `priority` (required): how strictly the solver enforces this rule
+ * - `weekStartsOn` (optional): which day starts the week; defaults to {@link ModelBuilder.weekStartsOn}
+ *
+ * Entity scoping (at most one): `memberIds`, `roleIds`, `skillIds`
+ */
+export type MinDaysWeekConfig = z.infer<typeof MinDaysWeekSchema>;
+
+/**
+ * Enforces a minimum number of days a person must work per scheduling week.
+ *
+ * @remarks
+ * Creates a binary "works on day" variable for each member and day, then
+ * constrains the weekly sum. This counts distinct days, regardless of how
+ * many shifts are assigned on a single day.
+ *
+ * @param config - See {@link MinDaysWeekConfig}
+ * @example
+ * ```ts
+ * createMinDaysWeekRule({ days: 3, priority: "HIGH" });
+ * ```
+ */
+export function createMinDaysWeekRule(config: MinDaysWeekConfig): CompilationRule {
+  const parsed = MinDaysWeekSchema.parse(config);
+  const scope = parseEntityScope(parsed);
+  const { days, priority, weekStartsOn } = parsed;
+  const group = ruleGroup(`min-days-week:${days}`, `Min ${days}d per week`, scope);
+
+  return {
+    compile(b) {
+      if (days <= 0) return;
+
+      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 weekWorkVars: string[] = [];
+
+          for (const day of weekDays) {
+            const dayAssignments = b.shiftPatterns
+              .filter((p) => b.canAssign(emp, p) && b.patternAvailableOnDay(p, day))
+              .map((p) => b.assignment(emp.id, p.id, day));
+
+            if (dayAssignments.length === 0) continue;
+
+            const worksVar = b.boolVar(`works_day_${emp.id}_${day}`);
+            weekWorkVars.push(worksVar);
+
+            // worksVar >= each assignment (if any assignment is 1, worksVar must be 1)
+            for (const assignVar of dayAssignments) {
+              b.addLinear(
+                [
+                  { var: worksVar, coeff: 1 },
+                  { var: assignVar, coeff: -1 },
+                ],
+                ">=",
+                0,
+              );
+            }
+
+            // worksVar <= sum(assignments) (if no assignment is 1, worksVar must be 0)
+            b.addLinear(
+              [{ var: worksVar, coeff: 1 }, ...dayAssignments.map((v) => ({ var: v, coeff: -1 }))],
+              "<=",
+              0,
+            );
+          }
+
+          if (weekWorkVars.length === 0) continue;
+
+          const weekLabel = weekDays[0]!;
+          const constraintId = `min-days-week:${emp.id}:${weekLabel}`;
+          const terms: Term[] = weekWorkVars.map((v) => ({ var: v, coeff: 1 }));
+
+          if (priority === "MANDATORY") {
+            b.addLinear(terms, ">=", days);
+          } else {
+            b.addSoftLinear(terms, ">=", days, priorityToPenalty(priority), constraintId);
+            b.reporter.trackConstraint({
+              id: constraintId,
+              type: "rule",
+              rule: "min-days-week",
+              description: `${emp.id} min ${days}d in week starting ${weekLabel}`,
+              targetValue: days,
+              comparator: ">=",
+              day: weekLabel,
+              context: { memberIds: [emp.id], days: weekDays },
+              group,
+            });
+          }
+        }
+      }
+    },
+  };
+}

package/src/cpsat/rules/min-hours-day.ts

@@ -7,6 +7,7 @@ import {
   entityScope,
   parseEntityScope,
   resolveMembersFromScope,
+  ruleGroup,
 } from "./scope.types.js";
 
 const MinHoursDaySchema = z
@@ -40,6 +41,7 @@ export function createMinHoursDayRule(config: MinHoursDayConfig): CompilationRul
   const scope = parseEntityScope(parsed);
   const { hours, priority } = parsed;
   const minMinutes = hours * 60;
+  const group = ruleGroup(`min-hours-day:${hours}`, `Min ${hours}h per day`, scope);
 
   return {
     compile(b) {
@@ -61,10 +63,23 @@ export function createMinHoursDayRule(config: MinHoursDayConfig): CompilationRul
 
           if (terms.length === 0) continue;
 
+          const constraintId = `min-hours-day:${emp.id}:${day}`;
+
           if (priority === "MANDATORY") {
             b.addLinear(terms, ">=", minMinutes);
           } else {
-            b.addSoftLinear(terms, ">=", minMinutes, priorityToPenalty(priority));
+            b.addSoftLinear(terms, ">=", minMinutes, priorityToPenalty(priority), constraintId);
+            b.reporter.trackConstraint({
+              id: constraintId,
+              type: "rule",
+              rule: "min-hours-day",
+              description: `${emp.id} min ${hours}h on ${day}`,
+              targetValue: minMinutes,
+              comparator: ">=",
+              day,
+              context: { memberIds: [emp.id], days: [day] },
+              group,
+            });
           }
         }
       }

package/src/cpsat/rules/min-hours-week.ts

@@ -8,6 +8,7 @@ import {
   entityScope,
   parseEntityScope,
   resolveMembersFromScope,
+  ruleGroup,
 } from "./scope.types.js";
 
 const MinHoursWeekBase = z.object({
@@ -43,6 +44,7 @@ export function createMinHoursWeekRule(config: MinHoursWeekConfig): CompilationR
   const scope = parseEntityScope(parsed);
   const { hours, priority, weekStartsOn } = parsed;
   const minMinutes = hours * 60;
+  const group = ruleGroup(`min-hours-week:${hours}`, `Min ${hours}h per week`, scope);
 
   return {
     compile(b) {
@@ -67,10 +69,24 @@ export function createMinHoursWeekRule(config: MinHoursWeekConfig): CompilationR
 
           if (terms.length === 0) continue;
 
+          const weekLabel = weekDays[0]!;
+          const constraintId = `min-hours-week:${emp.id}:${weekLabel}`;
+
           if (priority === "MANDATORY") {
             b.addLinear(terms, ">=", minMinutes);
           } else {
-            b.addSoftLinear(terms, ">=", minMinutes, priorityToPenalty(priority));
+            b.addSoftLinear(terms, ">=", minMinutes, priorityToPenalty(priority), constraintId);
+            b.reporter.trackConstraint({
+              id: constraintId,
+              type: "rule",
+              rule: "min-hours-week",
+              description: `${emp.id} min ${hours}h in week starting ${weekLabel}`,
+              targetValue: minMinutes,
+              comparator: ">=",
+              day: weekLabel,
+              context: { memberIds: [emp.id], days: weekDays },
+              group,
+            });
           }
         }
       }