dabke 0.82.0 → 0.84.0

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

@@ -1,25 +1,25 @@
 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 OvertimeTierSchema = z.object({
   after: z.number().min(0),
@@ -33,7 +33,7 @@ const OvertimeTierSchema = z.object({
  */
 export type OvertimeTier = z.infer<typeof OvertimeTierSchema>;
 
-const OvertimeTieredMultiplierSchema = z
+export const OvertimeTieredMultiplierSchema = z
   .object({
     tiers: z.array(OvertimeTierSchema).nonempty(),
     weekStartsOn: DayOfWeekSchema.optional(),
@@ -41,276 +41,257 @@ const OvertimeTieredMultiplierSchema = z
   .and(entityScope(["members", "roles", "skills"]))
   .and(timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]));
 
-/** Configuration for {@link createOvertimeTieredMultiplierRule}. */
+/** Configuration for {@link overtimeTieredMultiplierRuleDescriptor}. */
 export type OvertimeTieredMultiplierConfig = z.infer<typeof OvertimeTieredMultiplierSchema>;
 
-/**
- * Creates a multi-threshold weekly overtime multiplier rule.
- *
- * Each tier applies only to the hours between its threshold and the next.
- * Tiers are sorted by threshold ascending internally.
- *
- * @example
- * ```typescript
- * // Hours 0-40: base rate
- * // Hours 40-48: 1.5x
- * // Hours 48+: 2.0x
- * tieredOvertimeMultiplier([
- *   { after: 40, factor: 1.5 },
- *   { after: 48, factor: 2.0 },
- * ])
- * ```
- */
-export function createOvertimeTieredMultiplierRule(
-  config: OvertimeTieredMultiplierConfig,
-): CompilationRule {
-  const parsed = OvertimeTieredMultiplierSchema.parse(config);
-  const { weekStartsOn } = parsed;
-  const entityScopeValue = parseEntityScope(parsed);
-  const timeScopeValue = parseTimeScope(parsed);
-
-  // Sort tiers by threshold ascending
-  const tiers = parsed.tiers.toSorted((a, b) => a.after - b.after);
-
-  // Filter out tiers with factor <= 1 (no extra cost)
-  const effectiveTiers = tiers.filter((t) => t.factor > 1);
-  let resolvedWeekStartsOn = weekStartsOn ?? "monday";
-
-  return {
-    compile(b) {
-      resolvedWeekStartsOn = weekStartsOn ?? b.weekStartsOn;
-      if (effectiveTiers.length === 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),
-              });
-            }
-            empWeekMaxMinutes += unionMinutes(dayRanges);
-          }
-
-          if (terms.length === 0) continue;
+export const overtimeTieredMultiplierRuleDescriptor = defineRuleDescriptor({
+  name: "overtime-tiered-multiplier",
+  schema: OvertimeTieredMultiplierSchema,
+  compile(config) {
+    const { weekStartsOn } = config;
+    const entityScopeValue = parseEntityScope(config);
+    const timeScopeValue = parseTimeScope(config);
+    const tiers = config.tiers.toSorted((left, right) => left.after - right.after);
+    const effectiveTiers = tiers.filter((tier) => tier.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 (effectiveTiers.length === 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;
 
-          // Create a tierVar for each tier: max(0, totalMinutes - threshold)
-          const tierVars: string[] = [];
-          for (const [tierIdx, tier] of effectiveTiers.entries()) {
-            const thresholdMinutes = tier.after * 60;
-            const maxOvertime = Math.max(0, empWeekMaxMinutes - thresholdMinutes);
-            if (maxOvertime === 0) {
-              // Tiers are sorted ascending, so all subsequent tiers are also unreachable.
-              tierVars.push("");
-              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);
             }
 
-            const tierVar = b.intVar(
-              `overtime:tiered:${emp.id}:w${weekIdx}:t${tierIdx}`,
-              0,
-              maxOvertime,
-            );
-            tierVars.push(tierVar);
-
-            // tierVar >= totalMinutes - threshold
-            b.addLinear(
-              [{ var: tierVar, coeff: 1 }, ...terms.map((t) => ({ var: t.var, coeff: -t.coeff }))],
-              ">=",
-              -thresholdMinutes,
-            );
-          }
-
-          // Compute per-tier-only hours and add penalties.
-          // tierOnly_i = tierVar_i - tierVar_{i+1} for non-last tiers.
-          // For the last tier, tierOnly = tierVar_last.
-          for (let i = 0; i < effectiveTiers.length; i++) {
-            const tierVar = tierVars[i];
-            if (!tierVar) continue; // Tier unreachable
+            if (terms.length === 0) continue;
 
-            const tier = effectiveTiers[i]!;
-            const extraFactor = tier.factor - 1;
-
-            const nextTierVar = i + 1 < effectiveTiers.length ? tierVars[i + 1] : undefined;
+            const tierVars: string[] = [];
+            for (const [tierIndex, tier] of effectiveTiers.entries()) {
+              const thresholdMinutes = tier.after * 60;
+              const maxOvertime = Math.max(0, memberWeekMaxMinutes - thresholdMinutes);
+              if (maxOvertime === 0) {
+                tierVars.push("");
+                continue;
+              }
 
-            if (nextTierVar) {
-              // Create tierOnly_i = tierVar_i - tierVar_{i+1}
-              const maxTierOnly = (effectiveTiers[i + 1]!.after - tier.after) * 60;
-              const tierOnlyVar = b.intVar(
-                `overtime:tiered-only:${emp.id}:w${weekIdx}:t${i}`,
+              const tierVar = builder.intVar(
+                `overtime:tiered:${member.id}:w${weekIndex}:t${tierIndex}`,
                 0,
-                Math.max(0, maxTierOnly),
+                maxOvertime,
               );
-
-              // tierOnlyVar == tierVar - nextTierVar
-              b.addLinear(
+              tierVars.push(tierVar);
+              builder.addLinear(
                 [
-                  { var: tierOnlyVar, coeff: 1 },
-                  { var: tierVar, coeff: -1 },
-                  { var: nextTierVar, coeff: 1 },
+                  { var: tierVar, coeff: 1 },
+                  ...terms.map((term) => ({ var: term.var, coeff: -term.coeff })),
                 ],
-                "==",
-                0,
+                ">=",
+                -thresholdMinutes,
               );
+            }
 
-              if (rate > 0) {
-                const totalTierCost = (rate * extraFactor * Math.max(1, maxTierOnly)) / 60;
-                if (hasCostContext) {
-                  const normalizedMax = totalTierCost / b.costContext!.normalizationFactor;
-                  b.addPenalty(
-                    tierOnlyVar,
-                    Math.max(1, Math.round(normalizedMax / Math.max(1, maxTierOnly))),
-                  );
+            for (let index = 0; index < effectiveTiers.length; index++) {
+              const tierVar = tierVars[index];
+              if (!tierVar) continue;
+
+              const tier = effectiveTiers[index]!;
+              const extraFactor = tier.factor - 1;
+              const nextTierVar =
+                index + 1 < effectiveTiers.length ? tierVars[index + 1] : undefined;
+
+              if (nextTierVar) {
+                const maxTierOnly = (effectiveTiers[index + 1]!.after - tier.after) * 60;
+                const tierOnlyVar = builder.intVar(
+                  `overtime:tiered-only:${member.id}:w${weekIndex}:t${index}`,
+                  0,
+                  Math.max(0, maxTierOnly),
+                );
+                builder.addLinear(
+                  [
+                    { var: tierOnlyVar, coeff: 1 },
+                    { var: tierVar, coeff: -1 },
+                    { var: nextTierVar, coeff: 1 },
+                  ],
+                  "==",
+                  0,
+                );
+
+                if (rate > 0) {
+                  const totalTierCost = (rate * extraFactor * Math.max(1, maxTierOnly)) / 60;
+                  if (hasCostContext) {
+                    const normalizedMax = totalTierCost / builder.costContext!.normalizationFactor;
+                    builder.addPenalty(
+                      tierOnlyVar,
+                      Math.max(1, Math.round(normalizedMax / Math.max(1, maxTierOnly))),
+                    );
+                  } else {
+                    builder.addPenalty(
+                      tierOnlyVar,
+                      Math.max(1, Math.round(OBJECTIVE_WEIGHTS.COST / Math.max(1, maxTierOnly))),
+                    );
+                  }
                 } else {
-                  b.addPenalty(
-                    tierOnlyVar,
-                    Math.max(1, Math.round(OBJECTIVE_WEIGHTS.COST / Math.max(1, maxTierOnly))),
-                  );
+                  builder.addPenalty(tierOnlyVar, 1);
                 }
               } else {
-                b.addPenalty(tierOnlyVar, 1);
-              }
-            } else {
-              // Last tier: penalty directly on tierVar
-              const maxOvertimeLast = Math.max(1, empWeekMaxMinutes - tier.after * 60);
-              if (rate > 0) {
-                const totalTierCost = (rate * extraFactor * maxOvertimeLast) / 60;
-                if (hasCostContext) {
-                  const normalizedMax = totalTierCost / b.costContext!.normalizationFactor;
-                  b.addPenalty(tierVar, Math.max(1, Math.round(normalizedMax / maxOvertimeLast)));
+                const maxOvertimeLast = Math.max(1, memberWeekMaxMinutes - tier.after * 60);
+                if (rate > 0) {
+                  const totalTierCost = (rate * extraFactor * maxOvertimeLast) / 60;
+                  if (hasCostContext) {
+                    const normalizedMax = totalTierCost / builder.costContext!.normalizationFactor;
+                    builder.addPenalty(
+                      tierVar,
+                      Math.max(1, Math.round(normalizedMax / maxOvertimeLast)),
+                    );
+                  } else {
+                    builder.addPenalty(
+                      tierVar,
+                      Math.max(1, Math.round(OBJECTIVE_WEIGHTS.COST / maxOvertimeLast)),
+                    );
+                  }
                 } else {
-                  b.addPenalty(
-                    tierVar,
-                    Math.max(1, Math.round(OBJECTIVE_WEIGHTS.COST / maxOvertimeLast)),
-                  );
+                  builder.addPenalty(tierVar, 1);
                 }
-              } else {
-                b.addPenalty(tierVar, 1);
               }
             }
           }
         }
-      }
-    },
-
-    cost(
-      assignments: ShiftAssignment[],
-      members: ReadonlyArray<SchedulingMember>,
-      shiftPatterns: ReadonlyArray<ShiftPattern>,
-    ): CostContribution {
-      if (effectiveTiers.length === 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),
-      );
-
-      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);
-
-        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);
-          }
-          data.totalMinutes += duration;
-          data.dayMinutes.set(a.day, (data.dayMinutes.get(a.day) ?? 0) + duration);
-        }
-
-        for (const [empId, data] of empWeekData) {
-          const emp = memberMap.get(empId);
-          if (!emp) continue;
-          const rate = getHourlyRate(emp);
-          if (rate === undefined) continue;
-
-          // Compute total overtime cost across all tiers
-          let totalOvertimeCost = 0;
-
-          for (let i = 0; i < effectiveTiers.length; i++) {
-            const tier = effectiveTiers[i]!;
-            const thresholdMinutes = tier.after * 60;
-            const extraFactor = tier.factor - 1;
-
-            const overtimeAboveThreshold = Math.max(0, data.totalMinutes - thresholdMinutes);
-            if (overtimeAboveThreshold <= 0) continue;
-
-            // Minutes in this tier only (capped by next tier's threshold)
-            const nextThreshold = effectiveTiers[i + 1]
-              ? effectiveTiers[i + 1]!.after * 60
-              : Infinity;
-            const tierMinutes = Math.min(
-              overtimeAboveThreshold,
-              nextThreshold === Infinity
-                ? overtimeAboveThreshold
-                : nextThreshold - thresholdMinutes,
+      },
+      calculateCost(assignments, costContext) {
+        if (effectiveTiers.length === 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,
             );
-
-            totalOvertimeCost += (rate * extraFactor * tierMinutes) / 60;
           }
 
-          if (totalOvertimeCost <= 0) continue;
+          for (const [memberId, data] of memberWeekData) {
+            const member = memberMap.get(memberId);
+            if (!member) continue;
+            const rate = getHourlyRate(member);
+            if (rate === undefined) continue;
+
+            let totalOvertimeCost = 0;
+            for (let index = 0; index < effectiveTiers.length; index++) {
+              const tier = effectiveTiers[index]!;
+              const thresholdMinutes = tier.after * 60;
+              const extraFactor = tier.factor - 1;
+              const overtimeAboveThreshold = Math.max(0, data.totalMinutes - thresholdMinutes);
+              if (overtimeAboveThreshold <= 0) continue;
+
+              const nextThreshold = effectiveTiers[index + 1]
+                ? effectiveTiers[index + 1]!.after * 60
+                : Infinity;
+              const tierMinutes = Math.min(
+                overtimeAboveThreshold,
+                nextThreshold === Infinity
+                  ? overtimeAboveThreshold
+                  : nextThreshold - thresholdMinutes,
+              );
+              totalOvertimeCost += (rate * extraFactor * tierMinutes) / 60;
+            }
 
-          // Distribute proportionally across days
-          for (const [day, dayMinutes] of data.dayMinutes) {
-            const proportion = dayMinutes / data.totalMinutes;
-            entries.push({
-              memberId: empId,
-              day,
-              category: COST_CATEGORY.OVERTIME,
-              amount: totalOvertimeCost * proportion,
-            });
+            if (totalOvertimeCost <= 0) continue;
+            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-tiered-multiplier",
+      artifacts: [costArtifact],
+    };
+  },
+});