dabke 0.78.0

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

@@ -0,0 +1,140 @@
+import * as z from "zod";
+import type { CompilationRule } from "../model-builder.js";
+import { priorityToPenalty } from "../utils.js";
+import { withScopes } from "./scoping.js";
+
+const MinConsecutiveDaysSchema = withScopes(
+  z.object({
+    days: z.number().min(0),
+    priority: z.union([
+      z.literal("LOW"),
+      z.literal("MEDIUM"),
+      z.literal("HIGH"),
+      z.literal("MANDATORY"),
+    ]),
+  }),
+  { entities: ["employees", "roles", "skills"], times: [] },
+);
+
+export type MinConsecutiveDaysConfig = z.infer<typeof MinConsecutiveDaysSchema>;
+
+/**
+ * Requires that once a person starts working, they continue for a minimum
+ * number of consecutive days.
+ *
+ * @example
+ * ```ts
+ * const rule = createMinConsecutiveDaysRule({
+ *   days: 3,
+ *   priority: "MANDATORY",
+ * });
+ * builder = new ModelBuilder({ ...config, rules: [rule] });
+ * ```
+ */
+export function createMinConsecutiveDaysRule(config: MinConsecutiveDaysConfig): CompilationRule {
+  const { days, priority, employeeIds } = MinConsecutiveDaysSchema.parse(config);
+
+  return {
+    compile(b) {
+      if (days <= 1) return;
+
+      const employees = employeeIds
+        ? b.employees.filter((e) => employeeIds.includes(e.id))
+        : b.employees;
+
+      for (const emp of employees) {
+        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(
+            [
+              { var: startVar, coeff: 1 },
+              { var: worksToday, coeff: -1 },
+            ],
+            "<=",
+            0,
+          );
+          if (worksYesterday) {
+            b.addLinear(
+              [
+                { var: startVar, coeff: 1 },
+                { var: worksYesterday, coeff: 1 },
+              ],
+              "<=",
+              1,
+            );
+            b.addLinear(
+              [
+                { var: startVar, coeff: 1 },
+                { var: worksYesterday, coeff: 1 },
+                { var: worksToday, coeff: -1 },
+              ],
+              ">=",
+              0,
+            );
+          } else {
+            b.addLinear(
+              [
+                { var: startVar, coeff: 1 },
+                { var: worksToday, 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 },
+          ];
+
+          if (priority === "MANDATORY") {
+            b.addLinear(terms, ">=", 0);
+          } else {
+            b.addSoftLinear(terms, ">=", 0, priorityToPenalty(priority));
+          }
+        }
+      }
+    },
+  };
+}

package/src/cpsat/rules/min-hours-day.ts

@@ -0,0 +1,69 @@
+import * as z from "zod";
+import type { CompilationRule } from "../model-builder.js";
+import type { Term } from "../types.js";
+import { priorityToPenalty } from "../utils.js";
+import { withScopes } from "./scoping.js";
+
+const MinHoursDaySchema = withScopes(
+  z.object({
+    hours: z.number().min(0),
+    priority: z.union([
+      z.literal("LOW"),
+      z.literal("MEDIUM"),
+      z.literal("HIGH"),
+      z.literal("MANDATORY"),
+    ]),
+  }),
+  { entities: ["employees", "roles", "skills"], times: [] },
+);
+
+export type MinHoursDayConfig = z.infer<typeof MinHoursDaySchema>;
+
+/**
+ * Ensures a person works at least a minimum number of hours per day.
+ *
+ * @example
+ * ```ts
+ * const rule = createMinHoursDayRule({
+ *   hours: 6,
+ *   priority: "MANDATORY",
+ * });
+ * builder = new ModelBuilder({ ...config, rules: [rule] });
+ * ```
+ */
+export function createMinHoursDayRule(config: MinHoursDayConfig): CompilationRule {
+  const { hours, priority, employeeIds } = MinHoursDaySchema.parse(config);
+  const minMinutes = hours * 60;
+
+  return {
+    compile(b) {
+      if (hours <= 0) return;
+
+      const employees = employeeIds
+        ? b.employees.filter((e) => employeeIds.includes(e.id))
+        : b.employees;
+
+      for (const emp of employees) {
+        for (const day of b.days) {
+          const terms: Term[] = [];
+          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: b.patternDuration(pattern.id),
+            });
+          }
+
+          if (terms.length === 0) continue;
+
+          if (priority === "MANDATORY") {
+            b.addLinear(terms, ">=", minMinutes);
+          } else {
+            b.addSoftLinear(terms, ">=", minMinutes, priorityToPenalty(priority));
+          }
+        }
+      }
+    },
+  };
+}

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

@@ -0,0 +1,77 @@
+import * as z from "zod";
+import { DayOfWeekSchema } from "../../types.js";
+import type { CompilationRule } from "../model-builder.js";
+import type { Term } from "../types.js";
+import { priorityToPenalty, splitIntoWeeks } from "../utils.js";
+import { withScopes } from "./scoping.js";
+
+const MinHoursWeekSchema = withScopes(
+  z.object({
+    hours: z.number().min(0),
+    priority: z.union([
+      z.literal("LOW"),
+      z.literal("MEDIUM"),
+      z.literal("HIGH"),
+      z.literal("MANDATORY"),
+    ]),
+    // Optional override; defaults to ModelBuilder.weekStartsOn
+    weekStartsOn: DayOfWeekSchema.optional(),
+  }),
+  { entities: ["employees", "roles", "skills"], times: [] },
+);
+
+export type MinHoursWeekConfig = z.infer<typeof MinHoursWeekSchema>;
+
+/**
+ * Enforces a minimum total number of hours per scheduling week.
+ *
+ * @example
+ * ```ts
+ * const rule = createMinHoursWeekRule({
+ *   hours: 30,
+ *   priority: "HIGH",
+ * });
+ * builder = new ModelBuilder({ ...config, rules: [rule] });
+ * ```
+ */
+export function createMinHoursWeekRule(config: MinHoursWeekConfig): CompilationRule {
+  const parsed = MinHoursWeekSchema.parse(config);
+  const { hours, priority, employeeIds } = parsed;
+  const minMinutes = hours * 60;
+
+  return {
+    compile(b) {
+      if (hours <= 0) return;
+
+      const employees = employeeIds
+        ? b.employees.filter((e) => employeeIds.includes(e.id))
+        : b.employees;
+
+      const weeks = splitIntoWeeks(b.days, parsed.weekStartsOn ?? b.weekStartsOn);
+
+      for (const emp of employees) {
+        for (const weekDays of weeks) {
+          const terms: Term[] = [];
+          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: b.patternDuration(pattern.id),
+              });
+            }
+          }
+
+          if (terms.length === 0) continue;
+
+          if (priority === "MANDATORY") {
+            b.addLinear(terms, ">=", minMinutes);
+          } else {
+            b.addSoftLinear(terms, ">=", minMinutes, priorityToPenalty(priority));
+          }
+        }
+      }
+    },
+  };
+}

package/src/cpsat/rules/min-rest-between-shifts.ts

@@ -0,0 +1,121 @@
+import * as z from "zod";
+import type { CompilationRule } from "../model-builder.js";
+import { priorityToPenalty } from "../utils.js";
+import { withScopes } from "./scoping.js";
+
+export type MinRestBetweenShiftsConfig = z.infer<typeof MinRestBetweenShiftsSchema>;
+
+const MinRestBetweenShiftsSchema = withScopes(
+  z.object({
+    hours: z.number().min(0),
+    priority: z.union([
+      z.literal("LOW"),
+      z.literal("MEDIUM"),
+      z.literal("HIGH"),
+      z.literal("MANDATORY"),
+    ]),
+  }),
+  { entities: ["employees", "roles", "skills"], times: [] },
+);
+
+/**
+ * Enforces a minimum rest period between any two shifts a person works.
+ *
+ * @example
+ * ```ts
+ * const rule = createMinRestBetweenShiftsRule({
+ *   hours: 10,
+ *   priority: "MANDATORY",
+ * });
+ * builder = new ModelBuilder({ ...config, rules: [rule] });
+ * ```
+ */
+export function createMinRestBetweenShiftsRule(
+  config: MinRestBetweenShiftsConfig,
+): CompilationRule {
+  const { hours, priority, employeeIds } = MinRestBetweenShiftsSchema.parse(config);
+  const minMinutes = hours * 60;
+
+  return {
+    compile(b) {
+      const employees = employeeIds
+        ? b.employees.filter((e) => employeeIds.includes(e.id))
+        : b.employees;
+
+      for (const emp of employees) {
+        for (let i = 0; i < b.days.length; i++) {
+          const day1 = b.days[i];
+          if (!day1) continue;
+
+          const checkDays: string[] = [day1];
+          const nextDay = b.days[i + 1];
+          if (nextDay) checkDays.push(nextDay);
+
+          for (const pattern1 of b.shiftPatterns) {
+            if (!b.canAssign(emp, pattern1)) continue;
+            if (!b.patternAvailableOnDay(pattern1, day1)) continue;
+            const end1 = b.endMinutes(pattern1, day1);
+
+            for (const day2 of checkDays) {
+              if (!day2) continue;
+              for (const pattern2 of b.shiftPatterns) {
+                if (!b.canAssign(emp, pattern2)) continue;
+                if (!b.patternAvailableOnDay(pattern2, day2)) continue;
+                if (day1 === day2 && pattern1.id === pattern2.id) continue;
+
+                const start2 = b.startMinutes(pattern2, day2);
+                const gap = start2 - end1;
+
+                if (gap >= 0 && gap < minMinutes) {
+                  const var1 = b.assignment(emp.id, pattern1.id, day1);
+                  const var2 = b.assignment(emp.id, pattern2.id, day2);
+
+                  if (priority === "MANDATORY") {
+                    b.addLinear(
+                      [
+                        { var: var1, coeff: 1 },
+                        { var: var2, coeff: 1 },
+                      ],
+                      "<=",
+                      1,
+                    );
+                  } else {
+                    const conflictVar = b.boolVar(
+                      `rest_conflict_${emp.id}_${pattern1.id}_${day1}_${pattern2.id}_${day2}`,
+                    );
+                    b.addLinear(
+                      [
+                        { var: var1, coeff: 1 },
+                        { var: var2, coeff: 1 },
+                        { var: conflictVar, coeff: -1 },
+                      ],
+                      "<=",
+                      1,
+                    );
+                    b.addLinear(
+                      [
+                        { var: conflictVar, coeff: 1 },
+                        { var: var1, coeff: -1 },
+                      ],
+                      "<=",
+                      0,
+                    );
+                    b.addLinear(
+                      [
+                        { var: conflictVar, coeff: 1 },
+                        { var: var2, coeff: -1 },
+                      ],
+                      "<=",
+                      0,
+                    );
+                    b.addPenalty(conflictVar, priorityToPenalty(priority));
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+  };
+}

package/src/cpsat/rules/registry.ts

@@ -0,0 +1,49 @@
+import {
+  createAssignTogetherRule,
+  createEmployeeAssignmentPriorityRule,
+  createLocationPreferenceRule,
+  createMaxConsecutiveDaysRule,
+  createMaxHoursDayRule,
+  createMaxHoursWeekRule,
+  createMaxShiftsDayRule,
+  createMinConsecutiveDaysRule,
+  createMinHoursDayRule,
+  createMinHoursWeekRule,
+  createMinRestBetweenShiftsRule,
+  createTimeOffRule,
+} from "./index.js";
+import type {
+  BuiltInCpsatRuleFactories,
+  CpsatRuleFactories,
+  CpsatRuleName,
+} from "./rules.types.js";
+
+export const builtInCpsatRuleFactories: BuiltInCpsatRuleFactories = {
+  "assign-together": createAssignTogetherRule,
+  "employee-assignment-priority": createEmployeeAssignmentPriorityRule,
+  "location-preference": createLocationPreferenceRule,
+  "max-consecutive-days": createMaxConsecutiveDaysRule,
+  "max-hours-day": createMaxHoursDayRule,
+  "max-hours-week": createMaxHoursWeekRule,
+  "max-shifts-day": createMaxShiftsDayRule,
+  "min-consecutive-days": createMinConsecutiveDaysRule,
+  "min-hours-day": createMinHoursDayRule,
+  "min-hours-week": createMinHoursWeekRule,
+  "min-rest-between-shifts": createMinRestBetweenShiftsRule,
+  "time-off": createTimeOffRule,
+};
+
+/**
+ * Creates a rule factory map, preventing overriding built-in rules.
+ */
+export function createCpsatRuleFactory<F extends CpsatRuleFactories>(factories: F): F {
+  for (const name in factories) {
+    if (
+      name in builtInCpsatRuleFactories &&
+      factories[name] !== builtInCpsatRuleFactories[name as CpsatRuleName]
+    ) {
+      throw new Error(`Cannot override built-in CP-SAT rule "${name}" in custom factory`);
+    }
+  }
+  return factories;
+}

package/src/cpsat/rules/resolver.ts

@@ -0,0 +1,181 @@
+import type { SchedulingEmployee } from "../types.js";
+import {
+  normalizeScope,
+  specificity,
+  subtractIds,
+  timeScopeKey,
+  type EntityScope,
+  type RuleScope,
+} from "./scoping.js";
+import { builtInCpsatRuleFactories } from "./registry.js";
+import type {
+  CpsatRuleConfigEntry,
+  CpsatRuleFactories,
+  CpsatRuleName,
+  CpsatRuleRegistry,
+} from "./rules.types.js";
+import type { CompilationRule } from "../model-builder.js";
+
+type ResolvedRuleConfigEntry = {
+  name: CpsatRuleName;
+  config: CpsatRuleRegistry[CpsatRuleName];
+};
+
+type InternalEntry = {
+  index: number;
+  name: CpsatRuleName;
+  config: CpsatRuleRegistry[CpsatRuleName];
+  scope: RuleScope;
+};
+
+/**
+ * Gets the IDs that match an entity scope.
+ * All scope types are expanded to concrete IDs.
+ */
+export function getEmployeeIdsForScope(
+  entity: EntityScope,
+  employees: SchedulingEmployee[],
+): string[] {
+  switch (entity.type) {
+    case "employees":
+      // Filter to only IDs that exist in the team
+      const validIds = new Set(employees.map((e) => e.id));
+      return entity.employeeIds.filter((id) => validIds.has(id));
+
+    case "roles":
+      // Find team members that have any of the specified roles
+      return employees
+        .filter((e) => e.roleIds.some((r) => entity.roleIds.includes(r)))
+        .map((e) => e.id);
+
+    case "skills":
+      // Find team members that have any of the specified skills
+      return employees
+        .filter((e) => e.skillIds?.some((s) => entity.skillIds.includes(s)))
+        .map((e) => e.id);
+
+    case "global":
+    default:
+      return employees.map((e) => e.id);
+  }
+}
+
+/**
+ * Rules that don't use standard scoping and should pass through unchanged.
+ */
+const NON_SCOPED_RULES = new Set<string>(["assign-together"]);
+
+/**
+ * Resolves overlapping scopes so that more specific scopes override broader ones.
+ *
+ * Resolution rules:
+ * 1. Rules in NON_SCOPED_RULES pass through unchanged (they handle their own logic)
+ * 2. Rules with different time scopes coexist (different time windows don't compete)
+ * 3. Within the same time scope, rules are sorted by specificity (person > role > skill > global)
+ *    and then by insertion order (later wins for same specificity, i.e., last insert overrides)
+ * 4. More specific rules claim their IDs first; less specific rules get the remainder
+ * 5. All scope types (person, role, skill, global) are expanded to explicit IDs
+ */
+export function resolveRuleScopes(
+  entries: CpsatRuleConfigEntry[],
+  employees: SchedulingEmployee[],
+): ResolvedRuleConfigEntry[] {
+  const resolved: ResolvedRuleConfigEntry[] = [];
+  const scopedEntries: Array<{ entry: CpsatRuleConfigEntry; index: number }> = [];
+
+  // Separate rules that use scoping from those that don't
+  entries.forEach((entry, index) => {
+    if (NON_SCOPED_RULES.has(entry.name)) {
+      // Pass through unchanged
+      resolved.push({ name: entry.name, config: entry.config });
+    } else {
+      scopedEntries.push({ entry, index });
+    }
+  });
+
+  if (scopedEntries.length === 0) {
+    return resolved;
+  }
+
+  // Group scoped entries by (ruleName, timeScopeKey) - different time scopes don't compete
+  const grouped = new Map<string, InternalEntry[]>();
+  scopedEntries.forEach(({ entry, index }) => {
+    const scope = normalizeScope(entry.config as Parameters<typeof normalizeScope>[0], employees);
+    const timeKey = timeScopeKey(scope.time);
+    const groupKey = `${entry.name}::${timeKey}`;
+    const list = grouped.get(groupKey) ?? [];
+    list.push({ index, name: entry.name, config: entry.config, scope });
+    grouped.set(groupKey, list);
+  });
+
+  for (const group of grouped.values()) {
+    // Sort by specificity (descending), then by insertion order (descending, later wins)
+    const sorted = group
+      .map((g) => ({
+        ...g,
+        specificity: specificity(g.scope.entity),
+      }))
+      .toSorted((a, b) => {
+        if (b.specificity !== a.specificity) {
+          return b.specificity - a.specificity;
+        }
+        // Later insertion wins (higher index first)
+        return b.index - a.index;
+      });
+
+    // Track assigned IDs - all scope types participate in claiming
+    const assignedEmployees = new Set<string>();
+
+    for (const entry of sorted) {
+      const { entity } = entry.scope;
+
+      // Get IDs for this scope (expands role/skill to concrete IDs)
+      const targetIds = getEmployeeIdsForScope(entity, employees);
+
+      // Only claim IDs not already assigned to a more specific rule
+      const remaining = subtractIds(targetIds, assignedEmployees);
+      if (remaining.length === 0) continue;
+
+      // Claim these IDs
+      remaining.forEach((id) => assignedEmployees.add(id));
+
+      // Emit resolved config with explicit IDs
+      // Remove roleIds/skillIds since we've expanded them to employeeIds
+      const {
+        roleIds: _roleIds,
+        skillIds: _skillIds,
+        ...configWithoutEntityScope
+      } = entry.config as Record<string, unknown>;
+      resolved.push({
+        name: entry.name,
+        config: {
+          ...configWithoutEntityScope,
+          employeeIds: remaining,
+        } as CpsatRuleRegistry[CpsatRuleName],
+      });
+    }
+  }
+
+  return resolved;
+}
+
+/**
+ * Builds CompilationRule instances from named configs, applying scoping resolution.
+ */
+export function buildCpsatRules(
+  entries: CpsatRuleConfigEntry[],
+  employees: SchedulingEmployee[],
+  factories: CpsatRuleFactories = builtInCpsatRuleFactories,
+): CompilationRule[] {
+  if (entries.length === 0) return [];
+
+  const resolved = resolveRuleScopes(entries, employees);
+
+  return resolved.map((entry) => {
+    const factory = factories[entry.name];
+    if (!factory) {
+      throw new Error(`Unknown CP-SAT rule "${entry.name}"`);
+    }
+    return factory(entry.config as any);
+  });
+}

package/src/cpsat/rules/rules.types.ts

@@ -0,0 +1,41 @@
+import type { CompilationRule } from "../model-builder.js";
+
+export type CreateCpsatRuleFunction<TConfig = any> = (config: TConfig) => CompilationRule;
+
+// Registry of built-in rule names to their config types
+export interface CpsatRuleRegistry {
+  "assign-together": import("./assign-together.js").AssignTogetherConfig;
+  "employee-assignment-priority": import("./employee-assignment-priority.js").EmployeeAssignmentPriorityConfig;
+  "location-preference": import("./location-preference.js").LocationPreferenceConfig;
+  "max-consecutive-days": import("./max-consecutive-days.js").MaxConsecutiveDaysConfig;
+  "max-hours-day": import("./max-hours-day.js").MaxHoursDayConfig;
+  "max-hours-week": import("./max-hours-week.js").MaxHoursWeekConfig;
+  "max-shifts-day": import("./max-shifts-day.js").MaxShiftsDayConfig;
+  "min-consecutive-days": import("./min-consecutive-days.js").MinConsecutiveDaysConfig;
+  "min-hours-day": import("./min-hours-day.js").MinHoursDayConfig;
+  "min-hours-week": import("./min-hours-week.js").MinHoursWeekConfig;
+  "min-rest-between-shifts": import("./min-rest-between-shifts.js").MinRestBetweenShiftsConfig;
+  "time-off": import("./time-off.js").TimeOffConfig;
+}
+
+export type CpsatRuleName = keyof CpsatRuleRegistry;
+
+export type CpsatRuleFactories = {
+  [ruleName: string]: CreateCpsatRuleFunction<any>;
+};
+
+export type BuiltInCpsatRuleFactories = {
+  [K in CpsatRuleName]: CreateCpsatRuleFunction<CpsatRuleRegistry[K]>;
+};
+
+export type InferCpsatRuleConfig<T> =
+  T extends CreateCpsatRuleFunction<infer Config> ? Config : never;
+
+export type CpsatRuleRegistryFromFactories<F extends CpsatRuleFactories> = {
+  [K in keyof F]: InferCpsatRuleConfig<F[K]>;
+};
+
+export type CpsatRuleConfigEntry<K extends CpsatRuleName = CpsatRuleName> = {
+  name: K;
+  config: CpsatRuleRegistry[K];
+};