dabke 0.82.0 → 0.84.0

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

@@ -1,27 +1,27 @@
 import * as z from "zod";
 import { DayOfWeekSchema } from "../../types.js";
-import type { CompilationRule, CostContribution } from "../model-builder.js";
-import type { ShiftPattern, SchedulingMember, Term } from "../types.js";
-import type { ShiftAssignment } from "../response.js";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
+import type { CostArtifact } from "../rule-descriptor.js";
 import { COST_CATEGORY } from "../cost.js";
 import {
-  timeOfDayToMinutes,
+  OBJECTIVE_WEIGHTS,
   normalizeEndMinutes,
   splitIntoWeeks,
+  timeOfDayToMinutes,
   unionMinutes,
-  OBJECTIVE_WEIGHTS,
 } from "../utils.js";
 import {
   entityScope,
-  timeScope,
   parseEntityScope,
   parseTimeScope,
-  resolveMembersFromScope,
   resolveActiveDaysFromScope,
+  resolveMembersFromScope,
+  timeScope,
 } from "./scope.types.js";
-import { getHourlyRate, patternDurationMinutes } from "./cost-utils.js";
+import { getHourlyRate } from "./cost-utils.js";
+import { patternDurationMinutes } from "./pattern-time.js";
 
-const OvertimeWeeklyMultiplierSchema = z
+export const OvertimeWeeklyMultiplierSchema = z
   .object({
     after: z.number().min(0),
     factor: z.number().min(1),
@@ -30,186 +30,194 @@ const OvertimeWeeklyMultiplierSchema = z
   .and(entityScope(["members", "roles", "skills"]))
   .and(timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]));
 
-/** Configuration for {@link createOvertimeWeeklyMultiplierRule}. */
+/** Configuration for {@link overtimeWeeklyMultiplierRuleDescriptor}. */
 export type OvertimeWeeklyMultiplierConfig = z.infer<typeof OvertimeWeeklyMultiplierSchema>;
 
 /**
- * Creates a weekly overtime rate multiplier rule.
+ * Low-level descriptor for the `overtime-weekly-multiplier` rule.
  *
- * Hours beyond the threshold per week are paid at `factor` times the base rate.
- * The base cost for all hours (including overtime at 1x) is already counted by
- * `minimizeCost()`. This rule adds only the extra portion (`factor - 1`).
+ * @remarks
+ * Weekly overtime windows align to `weekStartsOn`. This artifact always
+ * contributes to post-solve cost calculation and only affects optimization when
+ * `minimize-cost` is active.
  *
- * Auxiliary variables and constraints are always emitted (they define the overtime
- * structure). The penalty terms both contribute to the objective and tighten the
- * overtime variables via minimization.
+ * @category Rules
  */
-export function createOvertimeWeeklyMultiplierRule(
-  config: OvertimeWeeklyMultiplierConfig,
-): CompilationRule {
-  const parsed = OvertimeWeeklyMultiplierSchema.parse(config);
-  const { after, factor, weekStartsOn } = parsed;
-  const entityScopeValue = parseEntityScope(parsed);
-  const timeScopeValue = parseTimeScope(parsed);
-  const thresholdMinutes = after * 60;
-  const extraFactor = factor - 1;
-  let resolvedWeekStartsOn = weekStartsOn ?? "monday";
-
-  return {
-    compile(b) {
-      resolvedWeekStartsOn = weekStartsOn ?? b.weekStartsOn;
-      if (extraFactor <= 0) return;
-
-      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);
-
-      const hasCostContext = b.costContext?.active === true;
-
-      for (const emp of targetMembers) {
-        const rate = getHourlyRate(emp);
-        if (rate === undefined) continue;
-
-        for (const [weekIdx, weekDays] of weeks.entries()) {
-          // Build total minutes expression and compute per-member week max
-          // using time-range union per day (accounts for no-overlap constraints)
-          let empWeekMaxMinutes = 0;
-          const terms: Term[] = [];
-          for (const day of weekDays) {
-            const dayRanges: Array<{ start: number; end: number }> = [];
-            for (const pattern of b.shiftPatterns) {
-              if (!b.canAssign(emp, pattern)) continue;
-              if (!b.patternAvailableOnDay(pattern, day)) continue;
-              const start = timeOfDayToMinutes(pattern.startTime);
-              dayRanges.push({
-                start,
-                end: normalizeEndMinutes(start, timeOfDayToMinutes(pattern.endTime)),
-              });
-              terms.push({
-                var: b.assignment(emp.id, pattern.id, day),
-                coeff: patternDurationMinutes(pattern),
-              });
+export const overtimeWeeklyMultiplierRuleDescriptor = defineRuleDescriptor({
+  name: "overtime-weekly-multiplier",
+  schema: OvertimeWeeklyMultiplierSchema,
+  compile(config) {
+    const { after, factor, weekStartsOn } = config;
+    const entityScopeValue = parseEntityScope(config);
+    const timeScopeValue = parseTimeScope(config);
+    const thresholdMinutes = after * 60;
+    const extraFactor = factor - 1;
+    let resolvedWeekStartsOn = weekStartsOn ?? "monday";
+
+    const costArtifact: CostArtifact = {
+      kind: "cost",
+      validation: {
+        strategy: "skip",
+        category: "no-meaningful-feedback",
+        rationale:
+          "Overtime cost artifacts influence optimization and post-solve accounting, not validation feedback.",
+      },
+      compileObjective(builder) {
+        resolvedWeekStartsOn = weekStartsOn ?? builder.weekStartsOn;
+        if (extraFactor <= 0) return;
+
+        const targetMembers = resolveMembersFromScope(entityScopeValue, builder.members);
+        const activeDays = resolveActiveDaysFromScope(timeScopeValue, builder.days);
+        if (targetMembers.length === 0 || activeDays.length === 0) return;
+
+        const weeks = splitIntoWeeks(activeDays, weekStartsOn ?? builder.weekStartsOn);
+        const hasCostContext = builder.costContext?.active === true;
+
+        for (const member of targetMembers) {
+          const rate = getHourlyRate(member);
+          if (rate === undefined) continue;
+
+          for (const [weekIndex, weekDays] of weeks.entries()) {
+            let memberWeekMaxMinutes = 0;
+            const terms = [] as Array<{ var: string; coeff: number }>;
+
+            for (const day of weekDays) {
+              const dayRanges: Array<{ start: number; end: number }> = [];
+              for (const pattern of builder.shiftPatterns) {
+                if (
+                  !builder.canAssign(member, pattern) ||
+                  !builder.patternAvailableOnDay(pattern, day)
+                ) {
+                  continue;
+                }
+                const start = timeOfDayToMinutes(pattern.startTime);
+                dayRanges.push({
+                  start,
+                  end: normalizeEndMinutes(start, timeOfDayToMinutes(pattern.endTime)),
+                });
+                terms.push({
+                  var: builder.assignment(member.id, pattern.id, day),
+                  coeff: patternDurationMinutes(pattern),
+                });
+              }
+              memberWeekMaxMinutes += unionMinutes(dayRanges);
             }
-            empWeekMaxMinutes += unionMinutes(dayRanges);
-          }
 
-          if (terms.length === 0) continue;
-
-          const maxOvertime = Math.max(0, empWeekMaxMinutes - thresholdMinutes);
-          if (maxOvertime === 0) continue;
-
-          // Create overtime variable: max(0, totalMinutes - threshold)
-          const overtimeVar = b.intVar(`overtime:mult:${emp.id}:w${weekIdx}`, 0, maxOvertime);
-
-          // overtimeVar >= totalMinutes - threshold
-          // => overtimeVar - totalMinutes >= -threshold
-          b.addLinear(
-            [
-              { var: overtimeVar, coeff: 1 },
-              ...terms.map((t) => ({ var: t.var, coeff: -t.coeff })),
-            ],
-            ">=",
-            -thresholdMinutes,
-          );
-
-          // Penalty tightens the variable via minimization.
-          // For int vars, coeff is per unit (minute). Scale so max overtime
-          // contribution is proportional to OBJECTIVE_WEIGHTS.COST.
-          if (rate > 0) {
-            const totalOvertimeCost = (rate * extraFactor * maxOvertime) / 60;
-            if (hasCostContext) {
-              const normalizedMax = totalOvertimeCost / b.costContext!.normalizationFactor;
-              b.addPenalty(overtimeVar, Math.max(1, Math.round(normalizedMax / maxOvertime)));
+            if (terms.length === 0) continue;
+            const maxOvertime = Math.max(0, memberWeekMaxMinutes - thresholdMinutes);
+            if (maxOvertime === 0) continue;
+
+            const overtimeVar = builder.intVar(
+              `overtime:mult:${member.id}:w${weekIndex}`,
+              0,
+              maxOvertime,
+            );
+            builder.addLinear(
+              [
+                { var: overtimeVar, coeff: 1 },
+                ...terms.map((term) => ({ var: term.var, coeff: -term.coeff })),
+              ],
+              ">=",
+              -thresholdMinutes,
+            );
+
+            if (rate > 0) {
+              const totalOvertimeCost = (rate * extraFactor * maxOvertime) / 60;
+              if (hasCostContext) {
+                const normalizedMax = totalOvertimeCost / builder.costContext!.normalizationFactor;
+                builder.addPenalty(
+                  overtimeVar,
+                  Math.max(1, Math.round(normalizedMax / maxOvertime)),
+                );
+              } else {
+                builder.addPenalty(
+                  overtimeVar,
+                  Math.max(1, Math.round(OBJECTIVE_WEIGHTS.COST / maxOvertime)),
+                );
+              }
             } else {
-              b.addPenalty(
-                overtimeVar,
-                Math.max(1, Math.round(OBJECTIVE_WEIGHTS.COST / maxOvertime)),
-              );
+              builder.addPenalty(overtimeVar, 1);
             }
-          } else {
-            b.addPenalty(overtimeVar, 1);
           }
         }
-      }
-    },
-
-    cost(
-      assignments: ShiftAssignment[],
-      members: ReadonlyArray<SchedulingMember>,
-      shiftPatterns: ReadonlyArray<ShiftPattern>,
-    ): CostContribution {
-      if (extraFactor <= 0) return { entries: [] };
-
-      const memberMap = new Map(members.map((e) => [e.id, e]));
-      const patternMap = new Map(shiftPatterns.map((p) => [p.id, p]));
-
-      const allDays = [...new Set(assignments.map((a) => a.day))].toSorted();
-      const activeDays = new Set(resolveActiveDaysFromScope(timeScopeValue, allDays));
-      const targetEmpIds = new Set(
-        resolveMembersFromScope(entityScopeValue, [...memberMap.values()]).map((e) => e.id),
-      );
-
-      // Group assignments by member and week
-      const activeDaysList = allDays.filter((d) => activeDays.has(d));
-      const weeks = splitIntoWeeks(activeDaysList, resolvedWeekStartsOn);
-
-      const entries: CostContribution["entries"] = [];
-
-      for (const weekDays of weeks) {
-        const weekDaySet = new Set(weekDays);
-
-        // Get per-member total minutes and per-day minutes this week
-        const empWeekData = new Map<
-          string,
-          { totalMinutes: number; dayMinutes: Map<string, number> }
-        >();
-
-        for (const a of assignments) {
-          if (!weekDaySet.has(a.day)) continue;
-          if (!activeDays.has(a.day)) continue;
-          if (!targetEmpIds.has(a.memberId)) continue;
-
-          const pattern = patternMap.get(a.shiftPatternId);
-          if (!pattern) continue;
-          const duration = patternDurationMinutes(pattern);
-
-          let data = empWeekData.get(a.memberId);
-          if (!data) {
-            data = { totalMinutes: 0, dayMinutes: new Map() };
-            empWeekData.set(a.memberId, data);
+      },
+      calculateCost(assignments, costContext) {
+        if (extraFactor <= 0) return { entries: [] };
+
+        const memberMap = new Map(costContext.members.map((member) => [member.id, member]));
+        const patternMap = new Map(
+          costContext.shiftPatterns.map((pattern) => [pattern.id, pattern]),
+        );
+        const activeDays = new Set(
+          resolveActiveDaysFromScope(timeScopeValue, [...costContext.days]).map((day) => day.iso),
+        );
+        const targetMemberIds = new Set(
+          resolveMembersFromScope(entityScopeValue, [...costContext.members]).map(
+            (member) => member.id,
+          ),
+        );
+        const activeDaysList = costContext.days.filter((day) => activeDays.has(day.iso));
+        const weeks = splitIntoWeeks(activeDaysList, resolvedWeekStartsOn);
+
+        const entries = [] as Array<{
+          memberId: string;
+          day: string;
+          category: string;
+          amount: number;
+        }>;
+        for (const weekDays of weeks) {
+          const weekDaySet = new Set(weekDays.map((day) => day.iso));
+          const memberWeekData = new Map<
+            string,
+            { totalMinutes: number; dayMinutes: Map<string, number> }
+          >();
+
+          for (const assignment of assignments) {
+            if (!weekDaySet.has(assignment.day) || !activeDays.has(assignment.day)) continue;
+            if (!targetMemberIds.has(assignment.memberId)) continue;
+            const pattern = patternMap.get(assignment.shiftPatternId);
+            if (!pattern) continue;
+            const duration = patternDurationMinutes(pattern);
+            let data = memberWeekData.get(assignment.memberId);
+            if (!data) {
+              data = { totalMinutes: 0, dayMinutes: new Map() };
+              memberWeekData.set(assignment.memberId, data);
+            }
+            data.totalMinutes += duration;
+            data.dayMinutes.set(
+              assignment.day,
+              (data.dayMinutes.get(assignment.day) ?? 0) + duration,
+            );
           }
-          data.totalMinutes += duration;
-          data.dayMinutes.set(a.day, (data.dayMinutes.get(a.day) ?? 0) + duration);
-        }
-
-        for (const [empId, data] of empWeekData) {
-          const overtimeMinutes = Math.max(0, data.totalMinutes - thresholdMinutes);
-          if (overtimeMinutes <= 0) continue;
 
-          const emp = memberMap.get(empId);
-          if (!emp) continue;
-          const rate = getHourlyRate(emp);
-          if (rate === undefined) continue;
-
-          const totalOvertimeCost = (rate * extraFactor * overtimeMinutes) / 60;
-
-          // Distribute overtime cost across the week's days proportionally
-          for (const [day, dayMinutes] of data.dayMinutes) {
-            const proportion = dayMinutes / data.totalMinutes;
-            entries.push({
-              memberId: empId,
-              day,
-              category: COST_CATEGORY.OVERTIME,
-              amount: totalOvertimeCost * proportion,
-            });
+          for (const [memberId, data] of memberWeekData) {
+            const overtimeMinutes = Math.max(0, data.totalMinutes - thresholdMinutes);
+            if (overtimeMinutes <= 0) continue;
+            const member = memberMap.get(memberId);
+            if (!member) continue;
+            const rate = getHourlyRate(member);
+            if (rate === undefined) continue;
+
+            const totalOvertimeCost = (rate * extraFactor * overtimeMinutes) / 60;
+            for (const [day, dayMinutes] of data.dayMinutes) {
+              const proportion = dayMinutes / data.totalMinutes;
+              entries.push({
+                memberId,
+                day,
+                category: COST_CATEGORY.OVERTIME,
+                amount: totalOvertimeCost * proportion,
+              });
+            }
           }
         }
-      }
 
-      return { entries };
-    },
-  };
-}
+        return { entries };
+      },
+    };
+
+    return {
+      rule: "overtime-weekly-multiplier",
+      artifacts: [costArtifact],
+    };
+  },
+});