dabke 0.82.0 → 0.84.0

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

@@ -1,223 +1,210 @@
 import type * as z from "zod";
-import type { DayOfWeek } from "../../types.js";
-import type { CompilationRule, CostContribution } from "../model-builder.js";
-import type { ShiftPattern, SchedulingMember } from "../types.js";
-import type { ShiftAssignment } from "../response.js";
+import type { DateString, DayOfWeek } from "../../types.js";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
+import type { CostArtifact } from "../rule-descriptor.js";
 import { COST_CATEGORY } from "../cost.js";
 import { OBJECTIVE_WEIGHTS, splitIntoWeeks } from "../utils.js";
 import {
   entityScope,
-  timeScope,
   parseEntityScope,
   parseTimeScope,
-  resolveMembersFromScope,
   resolveActiveDaysFromScope,
+  resolveMembersFromScope,
+  timeScope,
 } from "./scope.types.js";
-import { getHourlyRate, getSalariedPay, patternDurationMinutes } from "./cost-utils.js";
+import { getHourlyRate, getSalariedPay } from "./cost-utils.js";
+import { patternDurationMinutes } from "./pattern-time.js";
 
 const MinimizeCostSchema = entityScope(["members", "roles", "skills"]).and(
   timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]),
 );
 
-/** Configuration for {@link createMinimizeCostRule}. */
+/** Configuration for {@link minimizeCostRuleDescriptor}. */
 export type MinimizeCostConfig = z.infer<typeof MinimizeCostSchema>;
 
-/**
- * Creates the minimize-cost rule.
- *
- * **Hourly members:** adds a penalty proportional to
- * `hourlyRate * shiftDurationMinutes / 60` for each assignment.
- *
- * **Salaried members:** zero marginal cost up to their contracted hours.
- * A boolean variable tracks whether the member has any assignment in a
- * given week. When active, their full weekly salary (`annual / 52`) is
- * added as a penalty. This causes the solver to load work onto salaried
- * members (who are "free" once activated) before hourly workers.
- *
- * Computes a normalization factor and stores it on the model builder's
- * `costContext` so modifier rules can use the same scale.
- */
-export function createMinimizeCostRule(config: MinimizeCostConfig): CompilationRule {
-  const parsed = MinimizeCostSchema.parse(config);
-  const entityScopeValue = parseEntityScope(parsed);
-  const timeScopeValue = parseTimeScope(parsed);
-
-  let resolvedWeekStartsOn: DayOfWeek = "monday";
-
-  return {
-    compile(b) {
-      resolvedWeekStartsOn = b.weekStartsOn;
-
-      const targetMembers = resolveMembersFromScope(entityScopeValue, b.members);
-      const activeDays = resolveActiveDaysFromScope(timeScopeValue, b.days);
-
-      if (targetMembers.length === 0 || activeDays.length === 0) return;
-
-      // Compute normalization factor: max raw cost of any single assignment
-      // (hourly) or weekly salary (salaried)
-      let maxRawCost = 0;
-      for (const member of targetMembers) {
-        const rate = getHourlyRate(member);
-        if (rate !== undefined) {
-          for (const pattern of b.shiftPatterns) {
-            if (!b.canAssign(member, pattern)) continue;
-            const duration = patternDurationMinutes(pattern);
-            const rawCost = (rate * duration) / 60;
-            if (rawCost > maxRawCost) maxRawCost = rawCost;
-          }
-        }
-        const salaried = getSalariedPay(member);
-        if (salaried !== undefined) {
-          const weeklyCost = salaried.annual / 52;
-          if (weeklyCost > maxRawCost) maxRawCost = weeklyCost;
-        }
-      }
-
-      if (maxRawCost === 0) return;
-
-      const normalizationFactor = maxRawCost / OBJECTIVE_WEIGHTS.COST;
-
-      b.costContext = {
-        normalizationFactor,
-        active: true,
-      };
-
-      // Add penalty terms for hourly members
-      for (const member of targetMembers) {
-        const rate = getHourlyRate(member);
-        if (rate !== undefined) {
-          for (const pattern of b.shiftPatterns) {
-            if (!b.canAssign(member, pattern)) continue;
-            for (const day of activeDays) {
-              if (!b.patternAvailableOnDay(pattern, day)) continue;
+export const minimizeCostRuleDescriptor = defineRuleDescriptor({
+  name: "minimize-cost",
+  schema: MinimizeCostSchema,
+  compile(config) {
+    const entityScopeValue = parseEntityScope(config);
+    const timeScopeValue = parseTimeScope(config);
+    let resolvedWeekStartsOn: DayOfWeek = "monday";
+
+    const costArtifact: CostArtifact = {
+      kind: "cost",
+      validation: {
+        strategy: "skip",
+        category: "no-meaningful-feedback",
+        rationale:
+          "Cost optimization influences the objective and contributes post-solve accounting, not validation feedback.",
+      },
+      compileObjective(builder) {
+        resolvedWeekStartsOn = builder.weekStartsOn;
+
+        const targetMembers = resolveMembersFromScope(entityScopeValue, builder.members);
+        const activeDays = resolveActiveDaysFromScope(timeScopeValue, builder.days);
+        if (targetMembers.length === 0 || activeDays.length === 0) return;
+
+        let maxRawCost = 0;
+        for (const member of targetMembers) {
+          const rate = getHourlyRate(member);
+          if (rate !== undefined) {
+            for (const pattern of builder.shiftPatterns) {
+              if (!builder.canAssign(member, pattern)) continue;
               const duration = patternDurationMinutes(pattern);
               const rawCost = (rate * duration) / 60;
-              const normalizedPenalty = rawCost / normalizationFactor;
-              b.addPenalty(
-                b.assignment(member.id, pattern.id, day),
-                Math.max(1, normalizedPenalty),
-              );
+              if (rawCost > maxRawCost) maxRawCost = rawCost;
             }
           }
-          continue;
+          const salaried = getSalariedPay(member);
+          if (salaried !== undefined) {
+            const weeklyCost = salaried.annual / 52;
+            if (weeklyCost > maxRawCost) maxRawCost = weeklyCost;
+          }
         }
 
-        // Salaried members: weekly fixed cost when active
-        const salaried = getSalariedPay(member);
-        if (salaried === undefined) continue;
-
-        const weeklyCost = salaried.annual / 52;
-        const normalizedWeeklyCost = weeklyCost / normalizationFactor;
-
-        const weeks = splitIntoWeeks(activeDays, b.weekStartsOn);
-
-        for (const [weekIdx, weekDays] of weeks.entries()) {
-          // Collect all assignment vars for this member this week
-          const weekAssignmentVars: string[] = [];
-          for (const day of weekDays) {
-            for (const pattern of b.shiftPatterns) {
-              if (!b.canAssign(member, pattern)) continue;
-              if (!b.patternAvailableOnDay(pattern, day)) continue;
-              weekAssignmentVars.push(b.assignment(member.id, pattern.id, day));
+        if (maxRawCost === 0) return;
+
+        const normalizationFactor = maxRawCost / OBJECTIVE_WEIGHTS.COST;
+        builder.costContext = {
+          normalizationFactor,
+          active: true,
+        };
+
+        for (const member of targetMembers) {
+          const rate = getHourlyRate(member);
+          if (rate !== undefined) {
+            for (const pattern of builder.shiftPatterns) {
+              if (!builder.canAssign(member, pattern)) continue;
+              for (const day of activeDays) {
+                if (!builder.patternAvailableOnDay(pattern, day)) continue;
+                const duration = patternDurationMinutes(pattern);
+                const rawCost = (rate * duration) / 60;
+                const normalizedPenalty = rawCost / normalizationFactor;
+                builder.addPenalty(
+                  builder.assignment(member.id, pattern.id, day),
+                  Math.max(1, normalizedPenalty),
+                );
+              }
             }
+            continue;
           }
 
-          if (weekAssignmentVars.length === 0) continue;
-
-          // Bool var: true if this salaried member works any shift this week
-          const activeVar = b.boolVar(`active:cost:${member.id}:w${weekIdx}`);
-
-          // If any assignment is true, activeVar must be true
-          // activeVar OR NOT(assignment_1) OR NOT(assignment_2) OR ...
-          // This is equivalent to: for each assignment, assignment => activeVar
-          for (const assignVar of weekAssignmentVars) {
-            b.addImplication(assignVar, activeVar);
-          }
+          const salaried = getSalariedPay(member);
+          if (salaried === undefined) continue;
 
-          b.addPenalty(activeVar, Math.max(1, Math.round(normalizedWeeklyCost)));
-        }
-      }
-    },
-
-    cost(
-      assignments: ShiftAssignment[],
-      members: ReadonlyArray<SchedulingMember>,
-      shiftPatterns: ReadonlyArray<ShiftPattern>,
-    ): CostContribution {
-      const memberMap = new Map(members.map((m) => [m.id, m]));
-      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 targetMemberIds = new Set(
-        resolveMembersFromScope(entityScopeValue, [...members]).map((m) => m.id),
-      );
-
-      const entries: CostContribution["entries"] = [];
-
-      // Track which salaried members are active per week for weekly cost
-      const salariedWeekActive = new Map<string, Set<string>>();
-
-      for (const a of assignments) {
-        if (!activeDays.has(a.day)) continue;
-        if (!targetMemberIds.has(a.memberId)) continue;
-        const member = memberMap.get(a.memberId);
-        if (!member) continue;
-
-        const pattern = patternMap.get(a.shiftPatternId);
-        if (!pattern) continue;
-        const duration = patternDurationMinutes(pattern);
-
-        const rate = getHourlyRate(member);
-        if (rate !== undefined) {
-          entries.push({
-            memberId: a.memberId,
-            day: a.day,
-            category: COST_CATEGORY.BASE,
-            amount: (rate * duration) / 60,
-          });
-          continue;
-        }
+          const weeklyCost = salaried.annual / 52;
+          const normalizedWeeklyCost = weeklyCost / normalizationFactor;
+          const weeks = splitIntoWeeks(activeDays, builder.weekStartsOn);
+
+          for (const [weekIndex, weekDays] of weeks.entries()) {
+            const weekAssignmentVars: string[] = [];
+            for (const day of weekDays) {
+              for (const pattern of builder.shiftPatterns) {
+                if (!builder.canAssign(member, pattern)) continue;
+                if (!builder.patternAvailableOnDay(pattern, day)) continue;
+                weekAssignmentVars.push(builder.assignment(member.id, pattern.id, day));
+              }
+            }
 
-        // Salaried: track weeks with assignments
-        const salaried = getSalariedPay(member);
-        if (salaried === undefined) continue;
+            if (weekAssignmentVars.length === 0) continue;
+
+            const activeVar = builder.boolVar(`active:cost:${member.id}:w${weekIndex}`);
+            for (const assignVar of weekAssignmentVars) {
+              builder.addLinear(
+                [
+                  { var: activeVar, coeff: 1 },
+                  { var: assignVar, coeff: -1 },
+                ],
+                ">=",
+                0,
+              );
+            }
 
-        let days = salariedWeekActive.get(a.memberId);
-        if (!days) {
-          days = new Set();
-          salariedWeekActive.set(a.memberId, days);
+            builder.addPenalty(activeVar, Math.max(1, Math.round(normalizedWeeklyCost)));
+          }
         }
-        days.add(a.day);
-      }
-
-      // Compute salaried costs: weekly salary distributed across active days
-      for (const [memberId, activeDaysSet] of salariedWeekActive) {
-        const member = memberMap.get(memberId);
-        if (!member) continue;
-        const salaried = getSalariedPay(member);
-        if (!salaried) continue;
-
-        const activeList = [...activeDaysSet].toSorted();
-        const weeks = splitIntoWeeks(activeList, resolvedWeekStartsOn);
-
-        for (const weekDays of weeks) {
-          if (weekDays.length === 0) continue;
-          const weeklyCost = salaried.annual / 52;
-          // Distribute evenly across days worked that week
-          const perDay = weeklyCost / weekDays.length;
-          for (const day of weekDays) {
+      },
+      calculateCost(assignments, costContext) {
+        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 entries: Array<{ memberId: string; day: string; category: string; amount: number }> =
+          [];
+        const salariedWeekActive = new Map<string, Set<DateString>>();
+
+        for (const assignment of assignments) {
+          if (!activeDays.has(assignment.day) || !targetMemberIds.has(assignment.memberId))
+            continue;
+          const member = memberMap.get(assignment.memberId);
+          if (!member) continue;
+          const pattern = patternMap.get(assignment.shiftPatternId);
+          if (!pattern) continue;
+          const duration = patternDurationMinutes(pattern);
+
+          const rate = getHourlyRate(member);
+          if (rate !== undefined) {
             entries.push({
-              memberId,
-              day,
+              memberId: assignment.memberId,
+              day: assignment.day,
               category: COST_CATEGORY.BASE,
-              amount: perDay,
+              amount: (rate * duration) / 60,
             });
+            continue;
           }
+
+          const salaried = getSalariedPay(member);
+          if (salaried === undefined) continue;
+          let memberDays = salariedWeekActive.get(assignment.memberId);
+          if (!memberDays) {
+            memberDays = new Set();
+            salariedWeekActive.set(assignment.memberId, memberDays);
+          }
+          memberDays.add(assignment.day);
         }
-      }
 
-      return { entries };
-    },
-  };
-}
+        for (const [memberId, activeDaysSet] of salariedWeekActive) {
+          const member = memberMap.get(memberId);
+          if (!member) continue;
+          const salaried = getSalariedPay(member);
+          if (!salaried) continue;
+
+          const activeDateSet = new Set(activeDaysSet);
+          const activeList = costContext.days.filter((day) => activeDateSet.has(day.iso));
+          const weeks = splitIntoWeeks(activeList, resolvedWeekStartsOn);
+
+          for (const weekDays of weeks) {
+            if (weekDays.length === 0) continue;
+            const weeklyCost = salaried.annual / 52;
+            const perDay = weeklyCost / weekDays.length;
+            for (const day of weekDays) {
+              entries.push({
+                memberId,
+                day: day.iso,
+                category: COST_CATEGORY.BASE,
+                amount: perDay,
+              });
+            }
+          }
+        }
+
+        return { entries };
+      },
+    };
+
+    return {
+      rule: "minimize-cost",
+      artifacts: [costArtifact],
+    };
+  },
+});

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

@@ -0,0 +1,71 @@
+import * as z from "zod";
+import { DayOfWeekSchema } from "../../types.js";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
+import { priorityToPenalty, splitIntoWeeks } from "../utils.js";
+import {
+  entityScope,
+  parseEntityScope,
+  resolveMembersFromScope,
+  ruleGroup,
+} from "./scope.types.js";
+import { assignmentTermsForDays } from "./assignment-terms.js";
+import { reportValidation, softConstraint } from "./artifacts.js";
+
+/** Internally always HIGH. Not user-configurable. */
+const MUST_ASSIGN_PENALTY = priorityToPenalty("HIGH");
+
+export const MustAssignSchema = z
+  .object({
+    weekStartsOn: DayOfWeekSchema.optional(),
+  })
+  .and(entityScope(["members", "roles", "skills"]));
+
+/**
+ * Configuration for {@link mustAssignRuleDescriptor}.
+ */
+export type MustAssignConfig = z.infer<typeof MustAssignSchema>;
+
+export const mustAssignRuleDescriptor = defineRuleDescriptor({
+  name: "must-assign",
+  schema: MustAssignSchema,
+  compile(config, ctx) {
+    const scope = parseEntityScope(config);
+    const { weekStartsOn } = config;
+    const group = ruleGroup("must-assign", "Must assign", scope);
+    const members = resolveMembersFromScope(scope, [...ctx.members]);
+    const weeks = splitIntoWeeks([...ctx.days], weekStartsOn ?? ctx.weekStartsOn);
+
+    const artifacts = members.flatMap((member) =>
+      weeks.flatMap((weekDays) => {
+        const weekStart = weekDays[0];
+        if (!weekStart) return [];
+
+        const terms = assignmentTermsForDays(member, weekDays, ctx.shiftPatterns, () => 1);
+        if (terms.length === 0) return [];
+
+        const description = `${member.id} not assigned in week starting ${weekStart.iso} (staffing obligation)`;
+        const context = { memberIds: [member.id], days: weekDays.map((day) => day.iso) };
+        const constraintId = `must-assign:${member.id}:${weekStart.iso}`;
+
+        return [
+          softConstraint({
+            group,
+            description,
+            context,
+            validation: reportValidation(),
+            terms,
+            comparator: ">=",
+            targetValue: 1,
+            penalty: MUST_ASSIGN_PENALTY,
+            constraintId,
+          }),
+        ];
+      }),
+    );
+
+    return {
+      rule: "must-assign",
+      artifacts,
+    };
+  },
+});