dabke 0.82.0 → 0.84.0

package/src/cpsat/rules/min-consecutive-days.ts

@@ -1,5 +1,6 @@
 import * as z from "zod";
-import type { CompilationRule } from "../model-builder.js";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
+import type { RuleArtifact } from "../rule-descriptor.js";
 import { priorityToPenalty } from "../utils.js";
 import {
   PrioritySchema,
@@ -8,8 +9,18 @@ import {
   resolveMembersFromScope,
   ruleGroup,
 } from "./scope.types.js";
-
-const MinConsecutiveDaysSchema = z
+import { assignmentVarsForDay } from "./assignment-terms.js";
+import { assignedDayStartVariableName } from "./variables.js";
+import {
+  boolVariable,
+  hardConstraint,
+  reportValidation,
+  skipValidation,
+  softConstraint,
+} from "./artifacts.js";
+import { buildAssignedDayIndicator } from "./assigned-day.js";
+
+export const MinConsecutiveDaysSchema = z
   .object({
     days: z.number().min(0),
     priority: PrioritySchema,
@@ -17,143 +28,166 @@ const MinConsecutiveDaysSchema = z
   .and(entityScope(["members", "roles", "skills"]));
 
 /**
- * Configuration for {@link createMinConsecutiveDaysRule}.
- *
- * - `days` (required): minimum consecutive days required once a person starts working
- * - `priority` (required): how strictly the solver enforces this rule
- *
- * Entity scoping (at most one): `memberIds`, `roleIds`, `skillIds`
+ * Configuration for {@link minConsecutiveDaysRuleDescriptor}.
  */
 export type MinConsecutiveDaysConfig = z.infer<typeof MinConsecutiveDaysSchema>;
 
 /**
- * Requires that once a person starts working, they continue for a minimum
- * number of consecutive days.
+ * Low-level descriptor for the `min-consecutive-days` rule.
  *
- * @param config - See {@link MinConsecutiveDaysConfig}
- * @example
- * ```ts
- * createMinConsecutiveDaysRule({ days: 3, priority: "MANDATORY" });
- * ```
+ * @remarks
+ * Once an assignment streak starts, this rule requires it to continue for at
+ * least the configured number of assigned days.
+ *
+ * @category Rules
  */
-export function createMinConsecutiveDaysRule(config: MinConsecutiveDaysConfig): CompilationRule {
-  const parsed = MinConsecutiveDaysSchema.parse(config);
-  const scope = parseEntityScope(parsed);
-  const { days, priority } = parsed;
-  const group = ruleGroup(`min-consecutive-days:${days}`, `Min ${days} consecutive days`, scope);
-
-  return {
-    compile(b) {
-      if (days <= 1) return;
-
-      const members = resolveMembersFromScope(scope, b.members);
-
-      for (const emp of members) {
-        const worksByDay: string[] = [];
-
-        for (const day of b.days) {
-          const worksVar = b.boolVar(`works_${emp.id}_${day}`);
-          worksByDay.push(worksVar);
-
-          const dayAssignments = b.shiftPatterns
-            .filter((p) => b.canAssign(emp, p) && b.patternAvailableOnDay(p, day))
-            .map((p) => b.assignment(emp.id, p.id, day));
-
-          if (dayAssignments.length === 0) {
-            b.addLinear([{ var: worksVar, coeff: 1 }], "==", 0);
-          } else {
-            for (const assignVar of dayAssignments) {
-              b.addLinear(
-                [
-                  { var: worksVar, coeff: 1 },
-                  { var: assignVar, coeff: -1 },
-                ],
-                ">=",
-                0,
-              );
-            }
-            b.addLinear(
-              [{ var: worksVar, coeff: 1 }, ...dayAssignments.map((v) => ({ var: v, coeff: -1 }))],
-              "<=",
-              0,
-            );
-          }
-        }
-
-        for (let i = 0; i < b.days.length; i++) {
-          const dayLabel = b.days[i];
-          if (!dayLabel) continue;
-
-          const worksToday = worksByDay[i];
-          if (!worksToday) continue;
-          const worksYesterday = i > 0 ? worksByDay[i - 1] : undefined;
-          const startVar = b.boolVar(`work_start_${emp.id}_${dayLabel}`);
-
-          b.addLinear(
-            [
+export const minConsecutiveDaysRuleDescriptor = defineRuleDescriptor({
+  name: "min-consecutive-days",
+  schema: MinConsecutiveDaysSchema,
+  compile(config, ctx) {
+    const scope = parseEntityScope(config);
+    const { days, priority } = config;
+    const group = ruleGroup(`min-consecutive-days:${days}`, `Min ${days} consecutive days`, scope);
+    if (days <= 1) {
+      return { rule: "min-consecutive-days", artifacts: [] };
+    }
+
+    const members = resolveMembersFromScope(scope, [...ctx.members]);
+    const artifacts = members.flatMap((member) => {
+      const supportArtifacts = ctx.days.flatMap(
+        (day) =>
+          buildAssignedDayIndicator({
+            memberId: member.id,
+            day,
+            assignmentVars: assignmentVarsForDay(member, day, ctx.shiftPatterns),
+            variableName: `assigned_${member.id}_${day.iso}`,
+          }).artifacts,
+      );
+
+      const startArtifacts = ctx.days.flatMap((day, index) => {
+        const assignedToday = `assigned_${member.id}_${day.iso}`;
+        const assignedYesterday =
+          index > 0 ? `assigned_${member.id}_${ctx.days[index - 1]!.iso}` : undefined;
+        const startVar = assignedDayStartVariableName(member.id, day.iso);
+        const artifactsForDay: RuleArtifact[] = [boolVariable(startVar)];
+
+        artifactsForDay.push(
+          hardConstraint({
+            description: `${startVar} implies an assignment on ${day.iso}`,
+            validation: skipValidation(
+              "scaffolding",
+              "This helper variable only marks the start of an assignment streak when the member has an assignment that day.",
+            ),
+            context: { memberIds: [member.id], days: [day.iso] },
+            terms: [
               { var: startVar, coeff: 1 },
-              { var: worksToday, coeff: -1 },
+              { var: assignedToday, coeff: -1 },
             ],
-            "<=",
-            0,
-          );
-          if (worksYesterday) {
-            b.addLinear(
-              [
+            comparator: "<=",
+            targetValue: 0,
+          }),
+        );
+
+        if (assignedYesterday) {
+          artifactsForDay.push(
+            hardConstraint({
+              description: `${startVar} only when previous day is unassigned`,
+              validation: skipValidation(
+                "scaffolding",
+                "This helper variable must stay off when the previous day already belongs to the same assignment streak.",
+              ),
+              context: { memberIds: [member.id], days: [ctx.days[index - 1]!.iso, day.iso] },
+              terms: [
                 { var: startVar, coeff: 1 },
-                { var: worksYesterday, coeff: 1 },
+                { var: assignedYesterday, coeff: 1 },
               ],
-              "<=",
-              1,
-            );
-            b.addLinear(
-              [
+              comparator: "<=",
+              targetValue: 1,
+            }),
+          );
+          artifactsForDay.push(
+            hardConstraint({
+              description: `${startVar} activates on a new assignment streak`,
+              validation: skipValidation(
+                "scaffolding",
+                "This helper variable identifies new assignment streak boundaries for the consecutive-days window calculation.",
+              ),
+              context: { memberIds: [member.id], days: [ctx.days[index - 1]!.iso, day.iso] },
+              terms: [
                 { var: startVar, coeff: 1 },
-                { var: worksYesterday, coeff: 1 },
-                { var: worksToday, coeff: -1 },
+                { var: assignedYesterday, coeff: 1 },
+                { var: assignedToday, coeff: -1 },
               ],
-              ">=",
-              0,
-            );
-          } else {
-            b.addLinear(
-              [
+              comparator: ">=",
+              targetValue: 0,
+            }),
+          );
+        } else {
+          artifactsForDay.push(
+            hardConstraint({
+              description: `${startVar} matches first-day assignment state`,
+              validation: skipValidation(
+                "scaffolding",
+                "On the first day of the horizon, the helper variable matches whether a new streak starts that day.",
+              ),
+              context: { memberIds: [member.id], days: [day.iso] },
+              terms: [
                 { var: startVar, coeff: 1 },
-                { var: worksToday, coeff: -1 },
+                { var: assignedToday, coeff: -1 },
               ],
-              ">=",
-              0,
-            );
-          }
-
-          const window = worksByDay.slice(i, i + days).filter(Boolean) as string[];
-          if (window.length === 0) continue;
-
-          const terms = [
-            ...window.map((v) => ({ var: v, coeff: 1 })),
-            { var: startVar, coeff: -days },
-          ];
-
-          const constraintId = `min-consecutive-days:${emp.id}:${dayLabel}`;
-
-          if (priority === "MANDATORY") {
-            b.addLinear(terms, ">=", 0);
-          } else {
-            b.addSoftLinear(terms, ">=", 0, priorityToPenalty(priority), constraintId);
-            b.reporter.trackConstraint({
-              id: constraintId,
-              type: "rule",
-              rule: "min-consecutive-days",
-              description: `${emp.id} min ${days} consecutive days from ${dayLabel}`,
-              targetValue: 0,
               comparator: ">=",
-              day: dayLabel,
-              context: { memberIds: [emp.id], days: b.days.slice(i, i + days) },
-              group,
-            });
-          }
+              targetValue: 0,
+            }),
+          );
         }
-      }
-    },
-  };
-}
+
+        const windowDays = ctx.days.slice(index, index + days);
+        if (windowDays.length === 0) return artifactsForDay;
+
+        const description = `${member.id} min ${days} consecutive days from ${day.iso}`;
+        const context = { memberIds: [member.id], days: windowDays.map((entry) => entry.iso) };
+        const constraintId = `min-consecutive-days:${member.id}:${day.iso}`;
+        const terms = [
+          ...windowDays.map((windowDay) => ({
+            var: `assigned_${member.id}_${windowDay.iso}`,
+            coeff: 1,
+          })),
+          { var: startVar, coeff: -days },
+        ];
+
+        artifactsForDay.push(
+          priority === "MANDATORY"
+            ? hardConstraint({
+                group,
+                description,
+                context,
+                validation: reportValidation(constraintId),
+                terms,
+                comparator: ">=",
+                targetValue: 0,
+              })
+            : softConstraint({
+                group,
+                description,
+                context,
+                validation: reportValidation(),
+                terms,
+                comparator: ">=",
+                targetValue: 0,
+                penalty: priorityToPenalty(priority),
+                constraintId,
+              }),
+        );
+
+        return artifactsForDay;
+      });
+
+      return supportArtifacts.concat(startArtifacts);
+    });
+
+    return {
+      rule: "min-consecutive-days",
+      artifacts,
+    };
+  },
+});

package/src/cpsat/rules/min-days-of-week-per-period.ts

@@ -0,0 +1,144 @@
+import * as z from "zod";
+import { DayOfWeekSchema } from "../../types.js";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
+import type { RuleCompileContext } from "../rule-descriptor.js";
+import type { ValidationReporter } from "../validation-reporter.js";
+import { groupWeekChunks, priorityToPenalty, splitIntoMonths } from "../utils.js";
+import {
+  PrioritySchema,
+  entityScope,
+  parseEntityScope,
+  resolveMembersFromScope,
+  ruleGroup,
+} from "./scope.types.js";
+import { assignmentVarsForDay } from "./assignment-terms.js";
+import { hasAnyAssignablePattern } from "./pattern-eligibility.js";
+import { assignedDayVariableName } from "./variables.js";
+import { hardConstraint, reportValidation, softConstraint } from "./artifacts.js";
+import { buildAssignedDayIndicator } from "./assigned-day.js";
+
+const PeriodSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("weeks"), value: z.number().int().min(1) }),
+  z.object({ type: z.literal("months"), value: z.number().int().min(1) }),
+]);
+
+const MinDaysOfWeekPerPeriodBase = z.object({
+  days: z.number().int().min(0),
+  dayOfWeek: z.array(DayOfWeekSchema).nonempty(),
+  period: PeriodSchema,
+  priority: PrioritySchema,
+});
+
+export const MinDaysOfWeekPerPeriodSchema = MinDaysOfWeekPerPeriodBase.and(
+  entityScope(["members", "roles", "skills"]),
+);
+
+/**
+ * Configuration for {@link minDaysOfWeekPerPeriodRuleDescriptor}.
+ */
+export type MinDaysOfWeekPerPeriodConfig = z.infer<typeof MinDaysOfWeekPerPeriodSchema>;
+
+export const minDaysOfWeekPerPeriodRuleDescriptor = defineRuleDescriptor({
+  name: "min-days-of-week-per-period",
+  schema: MinDaysOfWeekPerPeriodSchema,
+  compile(config, ctx) {
+    const entityScopeValue = parseEntityScope(config);
+    const { days, dayOfWeek, period, priority } = config;
+    const dowLabel = dayOfWeek.toSorted().join(",");
+    const periodLabel = `${period.value}${period.type === "weeks" ? "w" : "m"}`;
+    const group = ruleGroup(
+      `min-days-of-week-per-period:${days}:${dowLabel}:${periodLabel}`,
+      `Min ${days} ${dowLabel} per ${period.value} ${period.type}`,
+      entityScopeValue,
+    );
+
+    const targetMembers = resolveMembersFromScope(entityScopeValue, [...ctx.members]);
+    const targetDows = new Set(dayOfWeek);
+    const chunks =
+      period.type === "weeks"
+        ? groupWeekChunks([...ctx.days], period.value, ctx.weekStartsOn)
+        : splitIntoMonths([...ctx.days], period.value);
+
+    const artifacts = targetMembers.flatMap((member) =>
+      chunks.flatMap((chunkDays) => {
+        const chunkStart = chunkDays[0];
+        if (!chunkStart) return [];
+
+        const matchingDays = chunkDays.filter((day) => targetDows.has(day.dayOfWeek));
+        if (matchingDays.length === 0) return [];
+
+        const supportArtifacts = matchingDays.flatMap(
+          (day) =>
+            buildAssignedDayIndicator({
+              memberId: member.id,
+              day,
+              assignmentVars: assignmentVarsForDay(member, day, ctx.shiftPatterns),
+            }).artifacts,
+        );
+
+        const assignedDayVars = matchingDays
+          .filter((day) => assignmentVarsForDay(member, day, ctx.shiftPatterns).length > 0)
+          .map((day) => assignedDayVariableName(member.id, day.iso));
+        if (assignedDayVars.length === 0) return supportArtifacts;
+
+        const description = `${member.id} min ${days} ${dowLabel} in period starting ${chunkStart.iso}`;
+        const context = { memberIds: [member.id], days: matchingDays.map((day) => day.iso) };
+        const constraintId = `min-days-of-week-per-period:${member.id}:${chunkStart.iso}`;
+        const terms = assignedDayVars.map((varName) => ({ var: varName, coeff: 1 }));
+
+        const finalArtifacts =
+          priority === "MANDATORY"
+            ? [
+                hardConstraint({
+                  group,
+                  description,
+                  context,
+                  validation: reportValidation(constraintId),
+                  terms,
+                  comparator: ">=",
+                  targetValue: days,
+                }),
+                {
+                  kind: "pre-solve-feedback" as const,
+                  run(_preSolveContext: RuleCompileContext, reporter: ValidationReporter) {
+                    const possibleDays = matchingDays.filter((day) =>
+                      hasAnyAssignablePattern(member, day, ctx.shiftPatterns),
+                    ).length;
+                    if (possibleDays >= days) return;
+                    reporter.reportRuleError({
+                      rule: "min-days-of-week-per-period",
+                      message: `${member.id} cannot reach ${days} ${dowLabel} assignments in the period starting ${chunkStart.iso}; only ${possibleDays} matching day${possibleDays === 1 ? " is" : "s are"} assignable.`,
+                      context,
+                      suggestions: [
+                        `Reduce the ${dowLabel} minimum in this period`,
+                        `Add more assignable ${dowLabel} shifts in the period starting ${chunkStart.iso}`,
+                      ],
+                      group,
+                    });
+                  },
+                },
+              ]
+            : [
+                softConstraint({
+                  group,
+                  description,
+                  context,
+                  validation: reportValidation(),
+                  terms,
+                  comparator: ">=",
+                  targetValue: days,
+                  penalty: priorityToPenalty(priority),
+                  constraintId,
+                }),
+              ];
+
+        return supportArtifacts.concat(finalArtifacts);
+      }),
+    );
+
+    return {
+      rule: "min-days-of-week-per-period",
+      artifacts,
+    };
+  },
+});

package/src/cpsat/rules/min-days-week.ts

@@ -0,0 +1,122 @@
+import * as z from "zod";
+import { DayOfWeekSchema } from "../../types.js";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
+import type { RuleCompileContext } from "../rule-descriptor.js";
+import type { ValidationReporter } from "../validation-reporter.js";
+import { priorityToPenalty, splitIntoWeeks } from "../utils.js";
+import {
+  PrioritySchema,
+  entityScope,
+  parseEntityScope,
+  resolveMembersFromScope,
+  ruleGroup,
+} from "./scope.types.js";
+import { assignmentVarsForDay } from "./assignment-terms.js";
+import { hasAnyAssignablePattern } from "./pattern-eligibility.js";
+import { assignedDayVariableName } from "./variables.js";
+import { hardConstraint, reportValidation, softConstraint } from "./artifacts.js";
+import { buildAssignedDayIndicator } from "./assigned-day.js";
+
+const MinDaysWeekBase = z.object({
+  days: z.number().int().min(0),
+  priority: PrioritySchema,
+  weekStartsOn: DayOfWeekSchema.optional(),
+});
+
+export const MinDaysWeekSchema = MinDaysWeekBase.and(entityScope(["members", "roles", "skills"]));
+
+/**
+ * Configuration for {@link minDaysWeekRuleDescriptor}.
+ */
+export type MinDaysWeekConfig = z.infer<typeof MinDaysWeekSchema>;
+
+export const minDaysWeekRuleDescriptor = defineRuleDescriptor({
+  name: "min-days-week",
+  schema: MinDaysWeekSchema,
+  compile(config, ctx) {
+    const scope = parseEntityScope(config);
+    const { days, priority, weekStartsOn } = config;
+    const group = ruleGroup(`min-days-week:${days}`, `Min ${days}d per week`, 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 supportArtifacts = weekDays.flatMap(
+          (day) =>
+            buildAssignedDayIndicator({
+              memberId: member.id,
+              day,
+              assignmentVars: assignmentVarsForDay(member, day, ctx.shiftPatterns),
+            }).artifacts,
+        );
+
+        const assignedDayVars = weekDays
+          .filter((day) => assignmentVarsForDay(member, day, ctx.shiftPatterns).length > 0)
+          .map((day) => assignedDayVariableName(member.id, day.iso));
+        if (assignedDayVars.length === 0) return supportArtifacts;
+
+        const description = `${member.id} min ${days}d in week starting ${weekStart.iso}`;
+        const context = { memberIds: [member.id], days: weekDays.map((day) => day.iso) };
+        const constraintId = `min-days-week:${member.id}:${weekStart.iso}`;
+        const terms = assignedDayVars.map((varName) => ({ var: varName, coeff: 1 }));
+
+        const finalArtifacts =
+          priority === "MANDATORY"
+            ? [
+                hardConstraint({
+                  group,
+                  description,
+                  context,
+                  validation: reportValidation(constraintId),
+                  terms,
+                  comparator: ">=",
+                  targetValue: days,
+                }),
+                {
+                  kind: "pre-solve-feedback" as const,
+                  run(_preSolveContext: RuleCompileContext, reporter: ValidationReporter) {
+                    const possibleDays = weekDays.filter((day) =>
+                      hasAnyAssignablePattern(member, day, ctx.shiftPatterns),
+                    ).length;
+                    if (possibleDays >= days) return;
+                    reporter.reportRuleError({
+                      rule: "min-days-week",
+                      message: `${member.id} cannot reach ${days} assigned days in week starting ${weekStart.iso}; only ${possibleDays} day${possibleDays === 1 ? " is" : "s are"} assignable.`,
+                      context,
+                      suggestions: [
+                        `Reduce the weekly day minimum for ${member.id}`,
+                        `Add more assignable days in the week starting ${weekStart.iso}`,
+                      ],
+                      group,
+                    });
+                  },
+                },
+              ]
+            : [
+                softConstraint({
+                  group,
+                  description,
+                  context,
+                  validation: reportValidation(),
+                  terms,
+                  comparator: ">=",
+                  targetValue: days,
+                  penalty: priorityToPenalty(priority),
+                  constraintId,
+                }),
+              ];
+
+        return supportArtifacts.concat(finalArtifacts);
+      }),
+    );
+
+    return {
+      rule: "min-days-week",
+      artifacts,
+    };
+  },
+});