dabke 0.83.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

@@ -1,7 +1,6 @@
 import * as z from "zod";
 import { DayOfWeekSchema } from "../../types.js";
-import type { CompilationRule } from "../model-builder.js";
-import type { Term } from "../types.js";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
 import { priorityToPenalty, splitIntoWeeks } from "../utils.js";
 import {
   entityScope,
@@ -9,100 +8,64 @@ import {
   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");
 
-const MustAssignSchema = z
+export 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`
+ * Configuration for {@link mustAssignRuleDescriptor}.
  */
 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);
+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);
 
-      for (const emp of members) {
-        for (const weekDays of weeks) {
-          const terms: Term[] = [];
+    const artifacts = members.flatMap((member) =>
+      weeks.flatMap((weekDays) => {
+        const weekStart = weekDays[0];
+        if (!weekStart) return [];
 
-          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 });
-            }
-          }
+        const terms = assignmentTermsForDays(member, weekDays, ctx.shiftPatterns, () => 1);
+        if (terms.length === 0) return [];
 
-          if (terms.length === 0) continue;
+        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}`;
 
-          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 },
+        return [
+          softConstraint({
             group,
-          });
-        }
-      }
-    },
-  };
-}
+            description,
+            context,
+            validation: reportValidation(),
+            terms,
+            comparator: ">=",
+            targetValue: 1,
+            penalty: MUST_ASSIGN_PENALTY,
+            constraintId,
+          }),
+        ];
+      }),
+    );
+
+    return {
+      rule: "must-assign",
+      artifacts,
+    };
+  },
+});