dabke 0.82.0 → 0.84.0

package/src/cpsat/rules/target-peak-concurrent-assignments.ts

@@ -0,0 +1,212 @@
+import * as z from "zod";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
+import { targetPeakPriorityToPenalty } from "../utils.js";
+import {
+  boolVariable,
+  hardConstraint,
+  intVariable,
+  reportValidation,
+  skipValidation,
+  softConstraint,
+} from "./artifacts.js";
+import {
+  buildConcurrentAssignmentSegments,
+  collectConcurrentAssignmentIntervals,
+  resolveConcurrentWindow,
+} from "./concurrent-intervals.js";
+import {
+  entityScope,
+  parseEntityScope,
+  parseTimeScope,
+  resolveActiveDaysFromScope,
+  resolveMembersFromScope,
+  ruleGroup,
+  SoftPrioritySchema,
+  timeScope,
+} from "./scope.types.js";
+
+export const TargetPeakConcurrentAssignmentsSchema = z
+  .object({
+    assignments: z.number().int().min(0),
+    priority: SoftPrioritySchema.default("HIGH"),
+  })
+  .and(entityScope(["members", "roles", "skills"]))
+  .and(timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]));
+
+/**
+ * Configuration for {@link targetPeakConcurrentAssignmentsRuleDescriptor}.
+ */
+export type TargetPeakConcurrentAssignmentsConfig = z.infer<
+  typeof TargetPeakConcurrentAssignmentsSchema
+>;
+
+/** @internal */
+export const TARGET_PEAK_CONCURRENT_ASSIGNMENTS_OBJECTIVE_STAGE_ID =
+  "__dabke_target_peak_concurrent_assignments__";
+
+/**
+ * Low-level descriptor for the `target-peak-concurrent-assignments` rule.
+ *
+ * @remarks
+ * Softly targets the daily peak number of concurrent targeted assignments
+ * within the scoped day set. This is not a lower bound across the whole day.
+ * Use {@link import("../../schedule/coverage.js").cover} for whole-window
+ * minimum staffing, and pair this rule with
+ * {@link import("./max-concurrent-assignments.js").maxConcurrentAssignmentsRuleDescriptor}
+ * when the same value is also a hard capacity cap.
+ *
+ * @category Rules
+ */
+export const targetPeakConcurrentAssignmentsRuleDescriptor = defineRuleDescriptor({
+  name: "target-peak-concurrent-assignments",
+  schema: TargetPeakConcurrentAssignmentsSchema,
+  compile(config, ctx) {
+    const { assignments, priority } = config;
+    if (assignments === 0) {
+      return { rule: "target-peak-concurrent-assignments", artifacts: [] };
+    }
+
+    const entityScopeValue = parseEntityScope(config);
+    const timeScopeValue = parseTimeScope(config);
+    const targetMembers = resolveMembersFromScope(entityScopeValue, [...ctx.members]);
+    const activeDays = resolveActiveDaysFromScope(timeScopeValue, [...ctx.days]);
+
+    if (activeDays.length === 0) {
+      return { rule: "target-peak-concurrent-assignments", artifacts: [] };
+    }
+
+    const group = ruleGroup(
+      `target-peak-concurrent-assignments:${assignments}`,
+      `Target peak ${assignments} concurrent assignment${assignments === 1 ? "" : "s"}`,
+      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);
+      const segments = buildConcurrentAssignmentSegments(intervals, window.start, window.end);
+      const dayKey = `${group.key}:${day.iso}`;
+      const shortfallVar = `${dayKey}:shortfall`;
+
+      if (segments.length === 0) {
+        return [
+          intVariable(shortfallVar, 0, assignments),
+          hardConstraint({
+            group,
+            description: `Fix peak-target shortfall to ${assignments} on ${day.iso} because no eligible assignments exist`,
+            context: dayContext,
+            validation: skipValidation(
+              "scaffolding",
+              "Peak-target shortfall is fixed when no eligible assignments can contribute to the daily peak.",
+            ),
+            terms: [{ var: shortfallVar, coeff: 1 }],
+            comparator: "==",
+            targetValue: assignments,
+          }),
+          softConstraint({
+            stage: TARGET_PEAK_CONCURRENT_ASSIGNMENTS_OBJECTIVE_STAGE_ID,
+            group,
+            description: `Target peak ${assignments} concurrent assignment${assignments === 1 ? "" : "s"} on ${day.iso}`,
+            context: dayContext,
+            validation: reportValidation(),
+            terms: [{ var: shortfallVar, coeff: 1 }],
+            comparator: "<=",
+            targetValue: 0,
+            penalty: targetPeakPriorityToPenalty(priority),
+            constraintId: `${dayKey}:shortfall`,
+          }),
+        ];
+      }
+
+      const witnessVars = segments.map((segment) => ({
+        segmentStart: segment.start,
+        name: `${dayKey}:${segment.start}:witness`,
+      }));
+
+      const helperArtifacts = [
+        intVariable(shortfallVar, 0, assignments),
+        ...witnessVars.map(({ name }) => boolVariable(name)),
+        hardConstraint({
+          group,
+          description: `Select exactly one peak segment witness on ${day.iso}`,
+          context: dayContext,
+          validation: skipValidation(
+            "scaffolding",
+            "Peak-target witness selection is an internal helper for day-level peak targeting.",
+          ),
+          terms: witnessVars.map(({ name }) => ({ var: name, coeff: 1 })),
+          comparator: "==",
+          targetValue: 1,
+        }),
+      ];
+
+      const linkageArtifacts = segments.map((segment) => {
+        const witnessVar = witnessVars.find(
+          (witness) => witness.segmentStart === segment.start,
+        )?.name;
+        if (!witnessVar) {
+          throw new Error(
+            `Missing peak-target witness variable for segment ${segment.start} on ${day.iso}`,
+          );
+        }
+
+        return hardConstraint({
+          group,
+          description: `Link peak-target shortfall to segment ${formatTimeRange(segment.start, segment.end)} on ${day.iso}`,
+          context: dayContext,
+          validation: skipValidation(
+            "scaffolding",
+            "Peak-target segment linkage is an internal helper that selects the best segment on a day.",
+          ),
+          terms: [
+            ...segment.varNames.map((varName) => ({ var: varName, coeff: 1 })),
+            { var: witnessVar, coeff: -assignments },
+            { var: shortfallVar, coeff: 1 },
+          ],
+          comparator: ">=",
+          targetValue: 0,
+        });
+      });
+
+      const shortfallArtifact = softConstraint({
+        stage: TARGET_PEAK_CONCURRENT_ASSIGNMENTS_OBJECTIVE_STAGE_ID,
+        group,
+        description: `Target peak ${assignments} concurrent assignment${assignments === 1 ? "" : "s"} on ${day.iso}`,
+        context: dayContext,
+        validation: reportValidation(),
+        terms: [{ var: shortfallVar, coeff: 1 }],
+        comparator: "<=",
+        targetValue: 0,
+        penalty: targetPeakPriorityToPenalty(priority),
+        constraintId: `${dayKey}:shortfall`,
+      });
+
+      const dayArtifacts: Array<
+        | (typeof helperArtifacts)[number]
+        | (typeof linkageArtifacts)[number]
+        | typeof shortfallArtifact
+      > = [];
+      dayArtifacts.push(...helperArtifacts, ...linkageArtifacts, shortfallArtifact);
+      return dayArtifacts;
+    });
+
+    return {
+      rule: "target-peak-concurrent-assignments",
+      artifacts,
+    };
+  },
+});
+
+function formatTimeRange(startMinutes: number, endMinutes: number): string {
+  return `${formatClockMinutes(startMinutes)}-${formatClockMinutes(endMinutes)}`;
+}
+
+function formatClockMinutes(totalMinutes: number): string {
+  const minutesPerDay = 24 * 60;
+  const normalized = ((totalMinutes % minutesPerDay) + minutesPerDay) % minutesPerDay;
+  const hours = Math.floor(normalized / 60);
+  const minutes = normalized % 60;
+  return `${String(hours).padStart(2, "0")}:${String(minutes).padStart(2, "0")}`;
+}

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

@@ -1,17 +1,16 @@
 import * as z from "zod";
-import type { CompilationRule, CostContribution } from "../model-builder.js";
-import type { ShiftPattern, SchedulingMember } from "../types.js";
 import type { TimeOfDay } 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, normalizeEndMinutes, MINUTES_PER_DAY } from "../utils.js";
+import { MINUTES_PER_DAY, normalizeEndMinutes, timeOfDayToMinutes } from "../utils.js";
 import {
   entityScope,
-  timeScope,
   parseEntityScope,
   parseTimeScope,
-  resolveMembersFromScope,
   resolveActiveDaysFromScope,
+  resolveMembersFromScope,
+  timeScope,
 } from "./scope.types.js";
 
 const TimeOfDaySchema = z.object({
@@ -19,7 +18,7 @@ const TimeOfDaySchema = z.object({
   minutes: z.number().int().min(0).max(59),
 });
 
-const TimeCostSurchargeSchema = z
+export const TimeCostSurchargeSchema = z
   .object({
     amountPerHour: z.number().min(0),
     window: z.object({
@@ -30,14 +29,112 @@ const TimeCostSurchargeSchema = z
   .and(entityScope(["members", "roles", "skills"]))
   .and(timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]));
 
-/** Configuration for {@link createTimeCostSurchargeRule}. */
+/** Configuration for {@link timeCostSurchargeRuleDescriptor}. */
 export type TimeCostSurchargeConfig = z.infer<typeof TimeCostSurchargeSchema>;
 
-/**
- * Computes the overlap in minutes between a shift and a time-of-day window.
- *
- * Handles overnight windows (e.g., 22:00-06:00) and overnight shifts.
- */
+export const timeCostSurchargeRuleDescriptor = defineRuleDescriptor({
+  name: "time-cost-surcharge",
+  schema: TimeCostSurchargeSchema,
+  compile(config) {
+    const { amountPerHour, window } = config;
+    const entityScopeValue = parseEntityScope(config);
+    const timeScopeValue = parseTimeScope(config);
+
+    const validation = {
+      strategy: "skip" as const,
+      category: "no-meaningful-feedback" as const,
+      rationale:
+        amountPerHour <= 0
+          ? "A zero time surcharge does not change optimization or cost accounting."
+          : "Time cost surcharges only affect optimization when minimize-cost is active.",
+    };
+
+    const costArtifact: CostArtifact = {
+      kind: "cost",
+      validation,
+      compileObjective(builder) {
+        if (!builder.costContext?.active || amountPerHour <= 0) return;
+
+        const targetMembers = resolveMembersFromScope(entityScopeValue, builder.members);
+        const activeDays = resolveActiveDaysFromScope(timeScopeValue, builder.days);
+        if (targetMembers.length === 0 || activeDays.length === 0) return;
+
+        const { normalizationFactor } = builder.costContext;
+        for (const member of targetMembers) {
+          for (const pattern of builder.shiftPatterns) {
+            if (!builder.canAssign(member, pattern)) continue;
+            const overlapMinutes = computeOverlapMinutes(
+              pattern.startTime,
+              pattern.endTime,
+              window.from,
+              window.until,
+            );
+            if (overlapMinutes <= 0) continue;
+            const surcharge = (amountPerHour * overlapMinutes) / 60;
+            const normalizedPenalty = surcharge / normalizationFactor;
+
+            for (const day of activeDays) {
+              if (!builder.patternAvailableOnDay(pattern, day)) continue;
+              builder.addPenalty(
+                builder.assignment(member.id, pattern.id, day),
+                Math.max(1, normalizedPenalty),
+              );
+            }
+          }
+        }
+      },
+      calculateCost(assignments, costContext) {
+        if (amountPerHour <= 0) return { entries: [] };
+
+        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 = [] 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 overlapMinutes = computeOverlapMinutes(
+            pattern.startTime,
+            pattern.endTime,
+            window.from,
+            window.until,
+          );
+          if (overlapMinutes <= 0) continue;
+          entries.push({
+            memberId: assignment.memberId,
+            day: assignment.day,
+            category: COST_CATEGORY.PREMIUM,
+            amount: (amountPerHour * overlapMinutes) / 60,
+          });
+        }
+
+        return { entries };
+      },
+    };
+
+    return {
+      rule: "time-cost-surcharge",
+      artifacts: [costArtifact],
+    };
+  },
+});
+
 function computeOverlapMinutes(
   shiftStart: TimeOfDay,
   shiftEnd: TimeOfDay,
@@ -49,24 +146,15 @@ function computeOverlapMinutes(
   const wFrom = timeOfDayToMinutes(windowFrom);
   const wUntil = timeOfDayToMinutes(windowUntil);
 
-  // Expand window: if overnight (e.g., 22:00-06:00), wUntil < wFrom
-  // Represent as two intervals or one extended interval
-  let totalOverlap = 0;
-
   if (wFrom < wUntil) {
-    // Normal window (e.g., 14:00-18:00)
-    totalOverlap = rangeOverlap(sStart, sEnd, wFrom, wUntil);
-  } else {
-    // Overnight window (e.g., 22:00-06:00)
-    // Split into [wFrom, MINUTES_PER_DAY) and [0, wUntil)
-    // But shift may also span overnight, so use extended ranges
-    totalOverlap += rangeOverlap(sStart, sEnd, wFrom, MINUTES_PER_DAY);
-    totalOverlap += rangeOverlap(sStart, sEnd, MINUTES_PER_DAY, MINUTES_PER_DAY + wUntil);
-    // Also check if shift overlaps [0, wUntil) in the same day
-    totalOverlap += rangeOverlap(sStart, sEnd, 0, wUntil);
+    return rangeOverlap(sStart, sEnd, wFrom, wUntil);
   }
 
-  return totalOverlap;
+  return (
+    rangeOverlap(sStart, sEnd, wFrom, MINUTES_PER_DAY) +
+    rangeOverlap(sStart, sEnd, MINUTES_PER_DAY, MINUTES_PER_DAY + wUntil) +
+    rangeOverlap(sStart, sEnd, 0, wUntil)
+  );
 }
 
 function rangeOverlap(aStart: number, aEnd: number, bStart: number, bEnd: number): number {
@@ -74,97 +162,3 @@ function rangeOverlap(aStart: number, aEnd: number, bStart: number, bEnd: number
   const end = Math.min(aEnd, bEnd);
   return Math.max(0, end - start);
 }
-
-/**
- * Creates a time-of-day surcharge rule (e.g., night differential).
- *
- * Adds a flat surcharge per hour for the portion of a shift that overlaps
- * a time-of-day window. Independent of the member's base rate.
- *
- * When `minimizeCost()` is not present, no solver terms are emitted,
- * but the `cost()` method still contributes to post-solve calculation.
- */
-export function createTimeCostSurchargeRule(config: TimeCostSurchargeConfig): CompilationRule {
-  const parsed = TimeCostSurchargeSchema.parse(config);
-  const { amountPerHour, window } = parsed;
-  const entityScopeValue = parseEntityScope(parsed);
-  const timeScopeValue = parseTimeScope(parsed);
-
-  return {
-    compile(b) {
-      if (!b.costContext?.active) return;
-      if (amountPerHour <= 0) return;
-
-      const targetMembers = resolveMembersFromScope(entityScopeValue, b.members);
-      const activeDays = resolveActiveDaysFromScope(timeScopeValue, b.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;
-
-          const overlapMinutes = computeOverlapMinutes(
-            pattern.startTime,
-            pattern.endTime,
-            window.from,
-            window.until,
-          );
-          if (overlapMinutes <= 0) continue;
-
-          const surcharge = (amountPerHour * overlapMinutes) / 60;
-          const normalizedPenalty = surcharge / normalizationFactor;
-
-          for (const day of activeDays) {
-            if (!b.patternAvailableOnDay(pattern, day)) continue;
-            b.addPenalty(b.assignment(emp.id, pattern.id, day), Math.max(1, normalizedPenalty));
-          }
-        }
-      }
-    },
-
-    cost(
-      assignments: ShiftAssignment[],
-      members: ReadonlyArray<SchedulingMember>,
-      shiftPatterns: ReadonlyArray<ShiftPattern>,
-    ): CostContribution {
-      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 entries: CostContribution["entries"] = [];
-
-      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 overlapMinutes = computeOverlapMinutes(
-          pattern.startTime,
-          pattern.endTime,
-          window.from,
-          window.until,
-        );
-        if (overlapMinutes <= 0) continue;
-
-        const amount = (amountPerHour * overlapMinutes) / 60;
-        entries.push({
-          memberId: a.memberId,
-          day: a.day,
-          category: COST_CATEGORY.PREMIUM,
-          amount,
-        });
-      }
-
-      return { entries };
-    },
-  };
-}