dabke 0.83.0 → 0.84.0

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

@@ -1,101 +1,122 @@
 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 { defineRuleDescriptor } from "../rule-descriptor.js";
+import type { CostArtifact } from "../rule-descriptor.js";
 import { COST_CATEGORY } from "../cost.js";
 import {
   entityScope,
-  timeScope,
   parseEntityScope,
   parseTimeScope,
-  resolveMembersFromScope,
   resolveActiveDaysFromScope,
+  resolveMembersFromScope,
+  timeScope,
 } from "./scope.types.js";
-import { patternDurationMinutes } from "./cost-utils.js";
+import { patternDurationMinutes } from "./pattern-time.js";
 
-const DayCostSurchargeSchema = z
+export const DayCostSurchargeSchema = z
   .object({
     amountPerHour: z.number().min(0),
   })
   .and(entityScope(["members", "roles", "skills"]))
   .and(timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]));
 
-/** Configuration for {@link createDayCostSurchargeRule}. */
+/** Configuration for {@link dayCostSurchargeRuleDescriptor}. */
 export type DayCostSurchargeConfig = z.infer<typeof DayCostSurchargeSchema>;
 
 /**
- * Creates a day-based flat surcharge rule.
+ * Low-level descriptor for the `day-cost-surcharge` rule.
  *
- * Adds a flat extra amount per hour for assignments on matching days,
- * independent of the member's base rate.
+ * @remarks
+ * This artifact always contributes to post-solve cost calculation. It only adds
+ * solver objective terms when `minimize-cost` is active.
  *
- * When `minimizeCost()` is not present, no solver terms are emitted,
- * but the `cost()` method still contributes to post-solve calculation.
+ * @category Rules
  */
-export function createDayCostSurchargeRule(config: DayCostSurchargeConfig): CompilationRule {
-  const parsed = DayCostSurchargeSchema.parse(config);
-  const { amountPerHour } = parsed;
-  const entityScopeValue = parseEntityScope(parsed);
-  const timeScopeValue = parseTimeScope(parsed);
+export const dayCostSurchargeRuleDescriptor = defineRuleDescriptor({
+  name: "day-cost-surcharge",
+  schema: DayCostSurchargeSchema,
+  compile(config) {
+    const { amountPerHour } = config;
+    const entityScopeValue = parseEntityScope(config);
+    const timeScopeValue = parseTimeScope(config);
 
-  return {
-    compile(b) {
-      if (!b.costContext?.active) return;
-      if (amountPerHour <= 0) return;
+    const validation = {
+      strategy: "skip" as const,
+      category: "no-meaningful-feedback" as const,
+      rationale:
+        amountPerHour <= 0
+          ? "A zero surcharge does not change optimization or cost accounting."
+          : "Day cost surcharges only affect optimization when minimize-cost is active.",
+    };
 
-      const targetMembers = resolveMembersFromScope(entityScopeValue, b.members);
-      const activeDays = resolveActiveDaysFromScope(timeScopeValue, b.days);
+    const costArtifact: CostArtifact = {
+      kind: "cost",
+      validation,
+      compileObjective(builder) {
+        if (!builder.costContext?.active || amountPerHour <= 0) return;
 
-      if (targetMembers.length === 0 || activeDays.length === 0) return;
+        const targetMembers = resolveMembersFromScope(entityScopeValue, builder.members);
+        const activeDays = resolveActiveDaysFromScope(timeScopeValue, builder.days);
+        if (targetMembers.length === 0 || activeDays.length === 0) return;
 
-      const { normalizationFactor } = b.costContext;
-
-      for (const emp of targetMembers) {
-        for (const pattern of b.shiftPatterns) {
-          if (!b.canAssign(emp, pattern)) continue;
-          for (const day of activeDays) {
-            if (!b.patternAvailableOnDay(pattern, day)) continue;
-            const duration = patternDurationMinutes(pattern);
-            const surcharge = (amountPerHour * duration) / 60;
-            const normalizedPenalty = surcharge / normalizationFactor;
-            b.addPenalty(b.assignment(emp.id, pattern.id, day), Math.max(1, normalizedPenalty));
+        const { normalizationFactor } = builder.costContext;
+        for (const member of targetMembers) {
+          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 surcharge = (amountPerHour * duration) / 60;
+              const normalizedPenalty = surcharge / normalizationFactor;
+              builder.addPenalty(
+                builder.assignment(member.id, pattern.id, day),
+                Math.max(1, normalizedPenalty),
+              );
+            }
           }
         }
-      }
-    },
-
-    cost(
-      assignments: ShiftAssignment[],
-      members: ReadonlyArray<SchedulingMember>,
-      shiftPatterns: ReadonlyArray<ShiftPattern>,
-    ): CostContribution {
-      if (amountPerHour <= 0) return { entries: [] };
+      },
+      calculateCost(assignments, costContext) {
+        if (amountPerHour <= 0) return { entries: [] };
 
-      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, [...members]).map((e) => e.id),
-      );
+        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: CostContribution["entries"] = [];
+        const entries = [] as Array<{
+          memberId: string;
+          day: string;
+          category: string;
+          amount: number;
+        }>;
+        for (const assignment of assignments) {
+          if (!activeDays.has(assignment.day) || !targetMemberIds.has(assignment.memberId))
+            continue;
+          const pattern = patternMap.get(assignment.shiftPatternId);
+          if (!pattern) continue;
+          const duration = patternDurationMinutes(pattern);
+          entries.push({
+            memberId: assignment.memberId,
+            day: assignment.day,
+            category: COST_CATEGORY.PREMIUM,
+            amount: (amountPerHour * duration) / 60,
+          });
+        }
 
-      for (const a of assignments) {
-        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);
-        const amount = (amountPerHour * duration) / 60;
-        entries.push({
-          memberId: a.memberId,
-          day: a.day,
-          category: COST_CATEGORY.PREMIUM,
-          amount,
-        });
-      }
+        return { entries };
+      },
+    };
 
-      return { entries };
-    },
-  };
-}
+    return {
+      rule: "day-cost-surcharge",
+      artifacts: [costArtifact],
+    };
+  },
+});

package/src/cpsat/rules/index.ts

@@ -1,24 +1,30 @@
-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";
-export { createDayCostSurchargeRule } from "./day-cost-surcharge.js";
-export { createTimeCostSurchargeRule } from "./time-cost-surcharge.js";
-export { createOvertimeWeeklyMultiplierRule } from "./overtime-weekly-multiplier.js";
-export { createOvertimeWeeklySurchargeRule } from "./overtime-weekly-surcharge.js";
-export { createOvertimeDailyMultiplierRule } from "./overtime-daily-multiplier.js";
-export { createOvertimeDailySurchargeRule } from "./overtime-daily-surcharge.js";
-export { createOvertimeTieredMultiplierRule } from "./overtime-tiered-multiplier.js";
+export { assignTogetherRuleDescriptor } from "./assign-together.js";
+export { assignmentPriorityRuleDescriptor } from "./assignment-priority.js";
+export { locationPreferenceRuleDescriptor } from "./location-preference.js";
+export { rolePreferenceRuleDescriptor } from "./role-preference.js";
+export { maxConcurrentAssignmentsRuleDescriptor } from "./max-concurrent-assignments.js";
+export { targetPeakConcurrentAssignmentsRuleDescriptor } from "./target-peak-concurrent-assignments.js";
+export { targetDaysWeekRuleDescriptor } from "./target-days-week.js";
+export { maxConsecutiveDaysRuleDescriptor } from "./max-consecutive-days.js";
+export { maxDaysWeekRuleDescriptor } from "./max-days-week.js";
+export { maxHoursDayRuleDescriptor } from "./max-hours-day.js";
+export { maxHoursWeekRuleDescriptor } from "./max-hours-week.js";
+export { maxShiftsDayRuleDescriptor } from "./max-shifts-day.js";
+export { minConsecutiveDaysRuleDescriptor } from "./min-consecutive-days.js";
+export { minDaysWeekRuleDescriptor } from "./min-days-week.js";
+export { minHoursDayRuleDescriptor } from "./min-hours-day.js";
+export { minHoursWeekRuleDescriptor } from "./min-hours-week.js";
+export { minRestBetweenShiftsRuleDescriptor } from "./min-rest-between-shifts.js";
+export { mustAssignRuleDescriptor } from "./must-assign.js";
+export { timeOffRuleDescriptor } from "./time-off.js";
+export { minimizeCostRuleDescriptor } from "./minimize-cost.js";
+export { dayCostMultiplierRuleDescriptor } from "./day-cost-multiplier.js";
+export { dayCostSurchargeRuleDescriptor } from "./day-cost-surcharge.js";
+export { timeCostSurchargeRuleDescriptor } from "./time-cost-surcharge.js";
+export { overtimeWeeklyMultiplierRuleDescriptor } from "./overtime-weekly-multiplier.js";
+export { overtimeWeeklySurchargeRuleDescriptor } from "./overtime-weekly-surcharge.js";
+export { overtimeDailyMultiplierRuleDescriptor } from "./overtime-daily-multiplier.js";
+export { overtimeDailySurchargeRuleDescriptor } from "./overtime-daily-surcharge.js";
+export { overtimeTieredMultiplierRuleDescriptor } from "./overtime-tiered-multiplier.js";
+export { maxDaysOfWeekPerPeriodRuleDescriptor } from "./max-days-of-week-per-period.js";
+export { minDaysOfWeekPerPeriodRuleDescriptor } from "./min-days-of-week-per-period.js";

package/src/cpsat/rules/location-preference.ts

@@ -1,15 +1,16 @@
 import * as z from "zod";
-import type { CompilationRule } from "../model-builder.js";
-import type { Priority } from "../types.js";
-import { OBJECTIVE_WEIGHTS } from "../utils.js";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
+import { PREFERENCE_WEIGHTS } from "../utils.js";
 import {
   PrioritySchema,
   entityScope,
   parseEntityScope,
   resolveMembersFromScope,
 } from "./scope.types.js";
+import { assignmentVar } from "./variables.js";
+import { canAssignMemberToPattern, isPatternAvailableOnDay } from "./pattern-eligibility.js";
 
-const LocationPreferenceSchema = z
+export const LocationPreferenceSchema = z
   .object({
     locationId: z.string(),
     priority: PrioritySchema,
@@ -17,59 +18,53 @@ const LocationPreferenceSchema = z
   .and(entityScope(["members", "roles", "skills"]));
 
 /**
- * Configuration for {@link createLocationPreferenceRule}.
- *
- * - `locationId` (required): the location ID to prefer for matching shift patterns
- * - `priority` (required): how strongly to prefer this location
- *
- * Entity scoping (at most one): `memberIds`, `roleIds`, `skillIds`
+ * Configuration for {@link locationPreferenceRuleDescriptor}.
  */
 export type LocationPreferenceConfig = z.infer<typeof LocationPreferenceSchema>;
 
-const PRIORITY_WEIGHTS: Record<Priority, number> = {
-  LOW: OBJECTIVE_WEIGHTS.FAIRNESS,
-  MEDIUM: OBJECTIVE_WEIGHTS.ASSIGNMENT_PREFERENCE,
-  HIGH: OBJECTIVE_WEIGHTS.ASSIGNMENT_PREFERENCE * 2.5,
-  MANDATORY: OBJECTIVE_WEIGHTS.ASSIGNMENT_PREFERENCE * 5,
-};
-
 /**
- * Prefers assigning a person to shift patterns matching a specific location.
+ * Low-level descriptor for location preference rules.
  *
- * @param config - See {@link LocationPreferenceConfig}
- * @example
- * ```ts
- * createLocationPreferenceRule({
- *   locationId: "terrace",
- *   priority: "HIGH",
- *   memberIds: ["alice"],
- * });
- * ```
+ * @category Rules
  */
-export function createLocationPreferenceRule(config: LocationPreferenceConfig): CompilationRule {
-  const parsed = LocationPreferenceSchema.parse(config);
-  const scope = parseEntityScope(parsed);
-  const { locationId } = parsed;
-  const weight = PRIORITY_WEIGHTS[parsed.priority] ?? 0;
-
-  return {
-    compile(b) {
-      if (weight === 0) return;
-
-      const members = resolveMembersFromScope(scope, b.members);
+export const locationPreferenceRuleDescriptor = defineRuleDescriptor({
+  name: "location-preference",
+  schema: LocationPreferenceSchema,
+  compile(config, ctx) {
+    const scope = parseEntityScope(config);
+    const { locationId } = config;
+    const weight = PREFERENCE_WEIGHTS[config.priority as keyof typeof PREFERENCE_WEIGHTS] ?? 0;
+    if (weight === 0) {
+      return { rule: "location-preference", artifacts: [] };
+    }
 
-      for (const emp of members) {
-        for (const pattern of b.shiftPatterns) {
-          if (!b.canAssign(emp, pattern)) continue;
-          const isPreferred = pattern.locationId === locationId;
-          if (isPreferred) continue;
+    const members = resolveMembersFromScope(scope, [...ctx.members]);
+    const terms = members.flatMap((member) =>
+      ctx.shiftPatterns.flatMap((pattern) => {
+        if (!canAssignMemberToPattern(member, pattern)) return [];
+        if (pattern.locationId === locationId) return [];
+        return ctx.days
+          .filter((day) => isPatternAvailableOnDay(pattern, day))
+          .map((day) => ({ var: assignmentVar(member.id, pattern.id, day.iso), coeff: weight }));
+      }),
+    );
 
-          for (const day of b.days) {
-            if (!b.patternAvailableOnDay(pattern, day)) continue;
-            b.addPenalty(b.assignment(emp.id, pattern.id, day), weight);
-          }
-        }
-      }
-    },
-  };
-}
+    return {
+      rule: "location-preference",
+      artifacts: [
+        {
+          kind: "objective",
+          terms,
+          validation: {
+            strategy: "skip",
+            category: "no-meaningful-feedback",
+            rationale:
+              terms.length === 0
+                ? `Location preference for "${locationId}" produced no objective terms.`
+                : "Preference rules influence the objective but do not emit validation feedback.",
+          },
+        },
+      ],
+    };
+  },
+});

package/src/cpsat/rules/max-concurrent-assignments.ts

@@ -0,0 +1,170 @@
+import * as z from "zod";
+import type { TimeOfDay } from "../../types.js";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
+import {
+  MINUTES_PER_DAY,
+  normalizeEndMinutes,
+  priorityToPenalty,
+  timeOfDayToMinutes,
+} from "../utils.js";
+import {
+  PrioritySchema,
+  entityScope,
+  parseEntityScope,
+  parseTimeScope,
+  resolveActiveDaysFromScope,
+  resolveMembersFromScope,
+  ruleGroup,
+  timeScope,
+} from "./scope.types.js";
+import { hardConstraint, reportValidation, softConstraint } from "./artifacts.js";
+import {
+  buildConcurrentAssignmentSegments,
+  collectConcurrentAssignmentIntervals,
+  resolveConcurrentWindow,
+} from "./concurrent-intervals.js";
+
+const timeOfDaySchema = z.object({
+  hours: z.number().int().min(0).max(23),
+  minutes: z.number().int().min(0).max(59),
+});
+
+export const MaxConcurrentAssignmentsSchema = z
+  .object({
+    assignments: z.number().int().min(0),
+    priority: PrioritySchema,
+    startTime: timeOfDaySchema.optional(),
+    endTime: timeOfDaySchema.optional(),
+  })
+  .and(entityScope(["members", "roles", "skills"]))
+  .and(timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]))
+  .refine(
+    (config) => {
+      const hasStartTime = config.startTime !== undefined;
+      const hasEndTime = config.endTime !== undefined;
+      return hasStartTime === hasEndTime;
+    },
+    {
+      message:
+        "Both startTime and endTime must be provided together for partial day concurrent-assignment caps",
+    },
+  );
+
+/**
+ * Configuration for {@link maxConcurrentAssignmentsRuleDescriptor}.
+ */
+export type MaxConcurrentAssignmentsConfig = z.infer<typeof MaxConcurrentAssignmentsSchema>;
+
+/**
+ * Low-level descriptor for the `max-concurrent-assignments` rule.
+ *
+ * @remarks
+ * Caps how many targeted members may be assigned at the same time. Use it for
+ * physical capacity constraints that should remain independent from coverage
+ * floors. Unlike {@link import("./max-shifts-day.js").maxShiftsDayRuleDescriptor},
+ * this counts concurrent overlap, not total assignments on a day.
+ *
+ * @category Rules
+ */
+export const maxConcurrentAssignmentsRuleDescriptor = defineRuleDescriptor({
+  name: "max-concurrent-assignments",
+  schema: MaxConcurrentAssignmentsSchema,
+  compile(config, ctx) {
+    const { assignments, priority, startTime, endTime } = config;
+    const entityScopeValue = parseEntityScope(config);
+    const timeScopeValue = parseTimeScope(config);
+    const targetMembers = resolveMembersFromScope(entityScopeValue, [...ctx.members]);
+    const activeDays = resolveActiveDaysFromScope(timeScopeValue, [...ctx.days]);
+
+    if (targetMembers.length === 0 || activeDays.length === 0) {
+      return { rule: "max-concurrent-assignments", artifacts: [] };
+    }
+
+    const windowStart = startTime ? timeOfDayToMinutes(startTime) : undefined;
+    const windowEnd =
+      startTime && endTime
+        ? normalizeEndMinutes(windowStart ?? 0, timeOfDayToMinutes(endTime))
+        : undefined;
+    const windowKey = buildWindowKey(startTime, endTime);
+    const windowLabel = buildWindowLabel(startTime, endTime);
+    const group = ruleGroup(
+      `max-concurrent-assignments:${assignments}:${windowKey}`,
+      `Max ${assignments} concurrent assignment${assignments === 1 ? "" : "s"}${windowLabel}`,
+      entityScopeValue,
+      timeScopeValue,
+    );
+
+    const artifacts = activeDays.flatMap((day) => {
+      const dayContext = { days: [day.iso], memberIds: targetMembers.map((member) => member.id) };
+      const intervals = collectConcurrentAssignmentIntervals(day, targetMembers, ctx.shiftPatterns);
+      const window = resolveConcurrentWindow(intervals, windowStart, windowEnd);
+      const segments = buildConcurrentAssignmentSegments(intervals, window.start, window.end);
+
+      return segments.flatMap((segment) => {
+        const description = `Max ${assignments} concurrent assignment${assignments === 1 ? "" : "s"} on ${day.iso} (${formatTimeRange(segment.start, segment.end)})`;
+        const constraintId = `${group.key}:${day.iso}:${segment.start}`;
+        const linearTerms = segment.varNames.map((varName) => ({ var: varName, coeff: 1 }));
+
+        return [
+          priority === "MANDATORY"
+            ? hardConstraint({
+                group,
+                description,
+                context: dayContext,
+                validation: reportValidation(constraintId),
+                terms: linearTerms,
+                comparator: "<=",
+                targetValue: assignments,
+              })
+            : softConstraint({
+                group,
+                description,
+                context: dayContext,
+                validation: reportValidation(),
+                terms: linearTerms,
+                comparator: "<=",
+                targetValue: assignments,
+                penalty: priorityToPenalty(priority),
+                constraintId,
+              }),
+        ];
+      });
+    });
+
+    return {
+      rule: "max-concurrent-assignments",
+      artifacts,
+    };
+  },
+});
+
+function buildWindowKey(startTime?: TimeOfDay, endTime?: TimeOfDay): string {
+  if (!startTime || !endTime) {
+    return "all-day";
+  }
+
+  return `${formatTimeKey(startTime)}-${formatTimeKey(endTime)}`;
+}
+
+function buildWindowLabel(startTime?: TimeOfDay, endTime?: TimeOfDay): string {
+  if (!startTime || !endTime) {
+    return "";
+  }
+
+  return ` (${formatTimeKey(startTime)}-${formatTimeKey(endTime)})`;
+}
+
+function formatTimeRange(startMinutes: number, endMinutes: number): string {
+  return `${formatClockMinutes(startMinutes)}-${formatClockMinutes(endMinutes)}`;
+}
+
+function formatTimeKey(time: TimeOfDay): string {
+  return `${String(time.hours).padStart(2, "0")}:${String(time.minutes ?? 0).padStart(2, "0")}`;
+}
+
+function formatClockMinutes(totalMinutes: number): string {
+  const normalized = ((totalMinutes % MINUTES_PER_DAY) + MINUTES_PER_DAY) % MINUTES_PER_DAY;
+  const hours = Math.floor(normalized / 60);
+  const minutes = normalized % 60;
+  return `${String(hours).padStart(2, "0")}:${String(minutes).padStart(2, "0")}`;
+}