dabke 0.83.0 → 0.84.0

package/src/cpsat/rules/assigned-day.ts

@@ -0,0 +1,70 @@
+import type { SchedulingDay } from "../../types.js";
+import type { RuleArtifact } from "../rule-descriptor.js";
+import { boolVariable, hardConstraint, skipValidation } from "./artifacts.js";
+import { assignedDayVariableName } from "./variables.js";
+
+export function buildAssignedDayIndicator(params: {
+  memberId: string;
+  day: SchedulingDay;
+  assignmentVars: readonly string[];
+  variableName?: string;
+}): { assignedDayVar: string; artifacts: readonly RuleArtifact[] } {
+  const assignedDayVar =
+    params.variableName ?? assignedDayVariableName(params.memberId, params.day.iso);
+  const artifacts: RuleArtifact[] = [boolVariable(assignedDayVar)];
+
+  if (params.assignmentVars.length === 0) {
+    artifacts.push(
+      hardConstraint({
+        description: `${assignedDayVar} fixed to 0 on ${params.day.iso}`,
+        validation: skipValidation(
+          "scaffolding",
+          "No assignments exist for this member and day, so the derived assigned-day variable is fixed to zero.",
+        ),
+        context: { memberIds: [params.memberId], days: [params.day.iso] },
+        terms: [{ var: assignedDayVar, coeff: 1 }],
+        comparator: "==",
+        targetValue: 0,
+      }),
+    );
+    return { assignedDayVar, artifacts };
+  }
+
+  for (const assignVar of params.assignmentVars) {
+    artifacts.push(
+      hardConstraint({
+        description: `${assignedDayVar} covers ${assignVar}`,
+        validation: skipValidation(
+          "scaffolding",
+          "This derived assigned-day variable must turn on whenever one of the day's assignment variables is on.",
+        ),
+        context: { memberIds: [params.memberId], days: [params.day.iso] },
+        terms: [
+          { var: assignedDayVar, coeff: 1 },
+          { var: assignVar, coeff: -1 },
+        ],
+        comparator: ">=",
+        targetValue: 0,
+      }),
+    );
+  }
+
+  artifacts.push(
+    hardConstraint({
+      description: `${assignedDayVar} limited by assignments on ${params.day.iso}`,
+      validation: skipValidation(
+        "scaffolding",
+        "This derived assigned-day variable must stay off unless at least one assignment variable is on.",
+      ),
+      context: { memberIds: [params.memberId], days: [params.day.iso] },
+      terms: [
+        { var: assignedDayVar, coeff: 1 },
+        ...params.assignmentVars.map((varName) => ({ var: varName, coeff: -1 })),
+      ],
+      comparator: "<=",
+      targetValue: 0,
+    }),
+  );
+
+  return { assignedDayVar, artifacts };
+}

package/src/cpsat/rules/assignment-priority.ts

@@ -1,80 +1,76 @@
 import * as z from "zod";
-import type { CompilationRule } from "../model-builder.js";
-import { OBJECTIVE_WEIGHTS } from "../utils.js";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
+import { PREFERENCE_WEIGHTS } from "../utils.js";
 import {
+  PrioritySchema,
   entityScope,
-  timeScope,
   parseEntityScope,
   parseTimeScope,
-  resolveMembersFromScope,
   resolveActiveDaysFromScope,
+  resolveMembersFromScope,
+  timeScope,
 } from "./scope.types.js";
+import { skipValidation } from "./artifacts.js";
+import { assignmentVar } from "./variables.js";
+import { canAssignMemberToPattern, isPatternAvailableOnDay } from "./pattern-eligibility.js";
 
-const AssignmentPrioritySchema = z
+export const AssignmentPrioritySchema = z
   .object({
-    preference: z.union([z.literal("high"), z.literal("low")]),
+    preference: z.union([z.literal("prefer"), z.literal("avoid")]),
+    priority: PrioritySchema.optional(),
   })
   .and(entityScope(["members", "roles", "skills"]))
   .and(timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]));
 
 /**
- * Configuration for {@link createAssignmentPriorityRule}.
- *
- * - `preference` (required): `"high"` to prefer assigning or `"low"` to avoid assigning
- *
- * Entity scoping (at most one): `memberIds`, `roleIds`, `skillIds`
- * Time scoping (at most one, optional): `dateRange`, `specificDates`, `dayOfWeek`, `recurringPeriods`
+ * Configuration for {@link assignmentPriorityRuleDescriptor}.
  */
 export type AssignmentPriorityConfig = z.infer<typeof AssignmentPrioritySchema>;
 
 /**
- * Adds objective weight to prefer or avoid assigning team members.
- *
- * @param config - See {@link AssignmentPriorityConfig}
- * @example Prefer specific team members
- * ```ts
- * createAssignmentPriorityRule({
- *   memberIds: ["alice", "bob"],
- *   preference: "high",
- * });
- * ```
+ * Low-level descriptor for assignment priority rules.
  *
- * @example Avoid assigning students on weekdays
- * ```ts
- * createAssignmentPriorityRule({
- *   roleIds: ["student"],
- *   dayOfWeek: ["monday", "tuesday", "wednesday", "thursday", "friday"],
- *   preference: "low",
- * });
- * ```
+ * @category Rules
  */
-export function createAssignmentPriorityRule(config: AssignmentPriorityConfig): CompilationRule {
-  const parsed = AssignmentPrioritySchema.parse(config);
-  const { preference } = parsed;
-  const entityScopeValue = parseEntityScope(parsed);
-  const timeScopeValue = parseTimeScope(parsed);
-
-  return {
-    compile(b) {
-      const targetMembers = resolveMembersFromScope(entityScopeValue, b.members);
-      const activeDays = resolveActiveDaysFromScope(timeScopeValue, b.days);
-
-      if (targetMembers.length === 0 || activeDays.length === 0) return;
+export const assignmentPriorityRuleDescriptor = defineRuleDescriptor({
+  name: "assignment-priority",
+  schema: AssignmentPrioritySchema,
+  compile(config, ctx) {
+    const { preference } = config;
+    const priority = config.priority ?? "MANDATORY";
+    const entityScopeValue = parseEntityScope(config);
+    const timeScopeValue = parseTimeScope(config);
+    const targetMembers = resolveMembersFromScope(entityScopeValue, [...ctx.members]);
+    const activeDays = resolveActiveDaysFromScope(timeScopeValue, [...ctx.days]);
+    const baseWeight = PREFERENCE_WEIGHTS[priority as keyof typeof PREFERENCE_WEIGHTS] ?? 0;
+    if (targetMembers.length === 0 || activeDays.length === 0 || baseWeight === 0) {
+      return { rule: "assignment-priority", artifacts: [] };
+    }
 
-      const weight =
-        preference === "high"
-          ? -OBJECTIVE_WEIGHTS.ASSIGNMENT_PREFERENCE
-          : OBJECTIVE_WEIGHTS.ASSIGNMENT_PREFERENCE;
+    const weight = preference === "prefer" ? -baseWeight : baseWeight;
+    const terms = targetMembers.flatMap((member) =>
+      ctx.shiftPatterns.flatMap((pattern) => {
+        if (!canAssignMemberToPattern(member, pattern)) return [];
+        return activeDays
+          .filter((day) => isPatternAvailableOnDay(pattern, day))
+          .map((day) => ({ var: assignmentVar(member.id, pattern.id, day.iso), coeff: weight }));
+      }),
+    );
 
-      for (const member of targetMembers) {
-        for (const pattern of b.shiftPatterns) {
-          if (!b.canAssign(member, pattern)) continue;
-          for (const day of activeDays) {
-            if (!b.patternAvailableOnDay(pattern, day)) continue;
-            b.addPenalty(b.assignment(member.id, pattern.id, day), weight);
-          }
-        }
-      }
-    },
-  };
-}
+    return {
+      rule: "assignment-priority",
+      artifacts: [
+        {
+          kind: "objective",
+          terms,
+          validation: skipValidation(
+            "no-meaningful-feedback",
+            terms.length === 0
+              ? "Assignment priority produced no objective terms for the selected scope."
+              : "Preference rules influence the objective but do not emit validation feedback.",
+          ),
+        },
+      ],
+    };
+  },
+});

package/src/cpsat/rules/assignment-terms.ts

@@ -0,0 +1,43 @@
+import type { SchedulingDay } from "../../types.js";
+import type { SchedulingMember, ShiftPattern, Term } from "../types.js";
+import { canAssignMemberToPattern, isPatternAvailableOnDay } from "./pattern-eligibility.js";
+import { assignmentVar } from "./variables.js";
+
+export function assignmentVarsForDay(
+  member: SchedulingMember,
+  day: SchedulingDay,
+  shiftPatterns: readonly ShiftPattern[],
+): string[] {
+  return shiftPatterns
+    .filter(
+      (pattern) =>
+        canAssignMemberToPattern(member, pattern) && isPatternAvailableOnDay(pattern, day),
+    )
+    .map((pattern) => assignmentVar(member.id, pattern.id, day.iso));
+}
+
+export function assignmentTermsForDay(
+  member: SchedulingMember,
+  day: SchedulingDay,
+  shiftPatterns: readonly ShiftPattern[],
+  coeffForPattern: (pattern: ShiftPattern) => number,
+): Term[] {
+  return shiftPatterns
+    .filter(
+      (pattern) =>
+        canAssignMemberToPattern(member, pattern) && isPatternAvailableOnDay(pattern, day),
+    )
+    .map((pattern) => ({
+      var: assignmentVar(member.id, pattern.id, day.iso),
+      coeff: coeffForPattern(pattern),
+    }));
+}
+
+export function assignmentTermsForDays(
+  member: SchedulingMember,
+  days: readonly SchedulingDay[],
+  shiftPatterns: readonly ShiftPattern[],
+  coeffForPattern: (pattern: ShiftPattern) => number,
+): Term[] {
+  return days.flatMap((day) => assignmentTermsForDay(member, day, shiftPatterns, coeffForPattern));
+}

package/src/cpsat/rules/concurrent-intervals.ts

@@ -0,0 +1,93 @@
+import type { SchedulingDay } from "../../types.js";
+import type { SchedulingMember, ShiftPattern } from "../types.js";
+import { MINUTES_PER_DAY, normalizeEndMinutes, timeOfDayToMinutes } from "../utils.js";
+import { canAssignMemberToPattern, isPatternAvailableOnDay } from "./pattern-eligibility.js";
+import { assignmentVar } from "./variables.js";
+
+export interface ConcurrentAssignmentInterval {
+  readonly start: number;
+  readonly end: number;
+  readonly varName: string;
+}
+
+export interface ConcurrentAssignmentSegment {
+  readonly start: number;
+  readonly end: number;
+  readonly varNames: readonly string[];
+}
+
+export function collectConcurrentAssignmentIntervals(
+  day: SchedulingDay,
+  targetMembers: readonly SchedulingMember[],
+  shiftPatterns: readonly ShiftPattern[],
+): ConcurrentAssignmentInterval[] {
+  const intervals: ConcurrentAssignmentInterval[] = [];
+
+  for (const pattern of shiftPatterns) {
+    if (!isPatternAvailableOnDay(pattern, day)) continue;
+
+    const start = timeOfDayToMinutes(pattern.startTime);
+    const end = normalizeEndMinutes(start, timeOfDayToMinutes(pattern.endTime));
+
+    for (const member of targetMembers) {
+      if (!canAssignMemberToPattern(member, pattern)) continue;
+      intervals.push({
+        start,
+        end,
+        varName: assignmentVar(member.id, pattern.id, day.iso),
+      });
+    }
+  }
+
+  return intervals;
+}
+
+export function resolveConcurrentWindow(
+  intervals: readonly ConcurrentAssignmentInterval[],
+  startMinutes?: number,
+  endMinutes?: number,
+): { start: number; end: number } {
+  const start = startMinutes ?? 0;
+  if (endMinutes !== undefined) {
+    return { start, end: endMinutes };
+  }
+
+  const latestEnd = intervals.reduce((maxEnd, interval) => Math.max(maxEnd, interval.end), 0);
+  return { start, end: Math.max(MINUTES_PER_DAY, latestEnd) };
+}
+
+export function buildConcurrentAssignmentSegments(
+  intervals: readonly ConcurrentAssignmentInterval[],
+  windowStart: number,
+  windowEnd: number,
+): ConcurrentAssignmentSegment[] {
+  const boundaries = new Set<number>([windowStart, windowEnd]);
+
+  for (const interval of intervals) {
+    const start = Math.max(interval.start, windowStart);
+    const end = Math.min(interval.end, windowEnd);
+    if (start >= end) continue;
+
+    boundaries.add(start);
+    boundaries.add(end);
+  }
+
+  const sortedBoundaries = [...boundaries].toSorted((left, right) => left - right);
+  const segments: ConcurrentAssignmentSegment[] = [];
+
+  for (let index = 0; index < sortedBoundaries.length - 1; index++) {
+    const start = sortedBoundaries[index];
+    const end = sortedBoundaries[index + 1];
+    if (start === undefined || end === undefined || start >= end) continue;
+
+    const varNames = intervals
+      .filter((interval) => interval.start < end && interval.end > start)
+      .map((interval) => interval.varName);
+
+    if (varNames.length === 0) continue;
+
+    segments.push({ start, end, varNames });
+  }
+
+  return segments;
+}

package/src/cpsat/rules/cost-utils.ts

@@ -1,5 +1,4 @@
-import type { SchedulingMember, ShiftPattern } from "../types.js";
-import { timeOfDayToMinutes, normalizeEndMinutes } from "../utils.js";
+import type { SchedulingMember } from "../types.js";
 
 /** Returns the hourly rate for a member, or undefined if not hourly. */
 export function getHourlyRate(member: SchedulingMember): number | undefined {
@@ -16,10 +15,3 @@ export function getSalariedPay(
   if ("annual" in member.pay) return member.pay;
   return undefined;
 }
-
-/** Computes shift duration in minutes from a pattern. */
-export function patternDurationMinutes(pattern: ShiftPattern): number {
-  const start = timeOfDayToMinutes(pattern.startTime);
-  const end = normalizeEndMinutes(start, timeOfDayToMinutes(pattern.endTime));
-  return end - start;
-}

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

@@ -1,113 +1,133 @@
 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 { getHourlyRate, patternDurationMinutes } from "./cost-utils.js";
+import { getHourlyRate } from "./cost-utils.js";
+import { patternDurationMinutes } from "./pattern-time.js";
 
-const DayCostMultiplierSchema = z
+export const DayCostMultiplierSchema = z
   .object({
     factor: z.number().min(1),
   })
   .and(entityScope(["members", "roles", "skills"]))
   .and(timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]));
 
-/** Configuration for {@link createDayCostMultiplierRule}. */
+/** Configuration for {@link dayCostMultiplierRuleDescriptor}. */
 export type DayCostMultiplierConfig = z.infer<typeof DayCostMultiplierSchema>;
 
 /**
- * Creates a day-based rate multiplier rule.
+ * Low-level descriptor for the `day-cost-multiplier` rule.
  *
- * Multiplies the base rate for assignments on matching days. The extra cost
- * above 1x is added as a penalty term (the base 1x is handled by `minimizeCost()`).
+ * @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 createDayCostMultiplierRule(config: DayCostMultiplierConfig): CompilationRule {
-  const parsed = DayCostMultiplierSchema.parse(config);
-  const { factor } = parsed;
-  const entityScopeValue = parseEntityScope(parsed);
-  const timeScopeValue = parseTimeScope(parsed);
+export const dayCostMultiplierRuleDescriptor = defineRuleDescriptor({
+  name: "day-cost-multiplier",
+  schema: DayCostMultiplierSchema,
+  compile(config) {
+    const { factor } = config;
+    const entityScopeValue = parseEntityScope(config);
+    const timeScopeValue = parseTimeScope(config);
 
-  return {
-    compile(b) {
-      if (!b.costContext?.active) return;
-      if (factor <= 1) return;
+    const validation = {
+      strategy: "skip" as const,
+      category: "no-meaningful-feedback" as const,
+      rationale:
+        factor <= 1
+          ? "A 1x multiplier does not change optimization or cost accounting."
+          : "Day cost multipliers 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 || factor <= 1) 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;
-      const extraFactor = factor - 1;
+        const { normalizationFactor } = builder.costContext;
+        const extraFactor = factor - 1;
 
-      for (const emp of targetMembers) {
-        const rate = getHourlyRate(emp);
-        if (rate === undefined) continue;
-
-        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 extraCost = (rate * extraFactor * duration) / 60;
-            const normalizedPenalty = extraCost / normalizationFactor;
-            b.addPenalty(b.assignment(emp.id, pattern.id, day), Math.max(1, normalizedPenalty));
+        for (const member of targetMembers) {
+          const rate = getHourlyRate(member);
+          if (rate === undefined) continue;
+          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 extraCost = (rate * extraFactor * duration) / 60;
+              const normalizedPenalty = extraCost / 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 (factor <= 1) return { entries: [] };
+      },
+      calculateCost(assignments, costContext) {
+        if (factor <= 1) return { entries: [] };
 
-      const empMap = new Map(members.map((e) => [e.id, e]));
-      const patternMap = new Map(shiftPatterns.map((p) => [p.id, p]));
+        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 extraFactor = factor - 1;
 
-      // Resolve which days this rule applies to from assignments
-      const allDays = [...new Set(assignments.map((a) => a.day))].toSorted();
-      const activeDays = new Set(resolveActiveDaysFromScope(timeScopeValue, allDays));
-      const targetEmpIds = new Set(
-        resolveMembersFromScope(entityScopeValue, [...empMap.values()]).map((e) => e.id),
-      );
-
-      const entries: CostContribution["entries"] = [];
-      const extraFactor = factor - 1;
+        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 member = memberMap.get(assignment.memberId);
+          if (!member) continue;
+          const rate = getHourlyRate(member);
+          if (rate === undefined) 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: (rate * extraFactor * duration) / 60,
+          });
+        }
 
-      for (const a of assignments) {
-        if (!activeDays.has(a.day)) continue;
-        if (!targetEmpIds.has(a.memberId)) continue;
-        const emp = empMap.get(a.memberId);
-        if (!emp) continue;
-        const rate = getHourlyRate(emp);
-        if (rate === undefined) continue;
-        const pattern = patternMap.get(a.shiftPatternId);
-        if (!pattern) continue;
-        const duration = patternDurationMinutes(pattern);
-        const amount = (rate * extraFactor * duration) / 60;
-        entries.push({
-          memberId: a.memberId,
-          day: a.day,
-          category: COST_CATEGORY.PREMIUM,
-          amount,
-        });
-      }
+        return { entries };
+      },
+    };
 
-      return { entries };
-    },
-  };
-}
+    return {
+      rule: "day-cost-multiplier",
+      artifacts: [costArtifact],
+    };
+  },
+});