dabke 0.82.0 → 0.84.0

package/src/cpsat/types.ts

@@ -1,4 +1,4 @@
-import type { TimeOfDay, DayOfWeek } from "../types.js";
+import type { DateString, TimeOfDay, DayOfWeek } from "../types.js";
 import type { SolverRequest, SolverTerm } from "../client.types.js";
 import type { ValidationGroup } from "./validation.types.js";
 
@@ -15,11 +15,12 @@ export interface HourlyPay {
 /**
  * Annual salary with contracted weekly hours.
  *
+ * @remarks
  * The solver treats salaried members as having a fixed weekly cost
  * (`annual / 52`) that is incurred once they work any shift in a week.
  * Additional shifts within the same week have zero marginal cost.
  *
- * Note: overtime multiplier rules apply only to hourly members.
+ * Overtime multiplier rules apply only to hourly members.
  * Overtime surcharge rules apply to all members regardless of pay type.
  *
  * @category Supporting Types
@@ -34,12 +35,37 @@ export interface SalariedPay {
 /**
  * How strictly the solver enforces a rule.
  *
+ * @remarks
+ * Priority is part of the schedule design, not a cosmetic option. Use it to
+ * preserve the distinction between hard requirements and softer preferences
+ * from the requirements. In practice, words like "must", "at least", "needs", and
+ * "cannot" usually map to `"MANDATORY"`, while words like "ideally",
+ * "prefer", "mainly", and "where possible" usually map to a soft priority.
+ * The same coverage shape or rule scope can be modeled with different
+ * priorities when the business language is subtler than a pure hard limit.
+ *
  * - `"LOW"`, `"MEDIUM"`, `"HIGH"`: soft constraints with increasing penalty for violations
  * - `"MANDATORY"`: hard constraint; the solver will not produce a solution that violates it
  *
  * @category Supporting Types
  */
-export type Priority = "LOW" | "MEDIUM" | "HIGH" | "MANDATORY";
+export const PRIORITY_VALUES = ["LOW", "MEDIUM", "HIGH", "MANDATORY"] as const;
+
+/**
+ * The soft-only priority values.
+ *
+ * @category Supporting Types
+ */
+export const SOFT_PRIORITY_VALUES = ["LOW", "MEDIUM", "HIGH"] as const;
+
+export type Priority = (typeof PRIORITY_VALUES)[number];
+
+/**
+ * Soft-only priority values.
+ *
+ * @category Supporting Types
+ */
+export type SoftPriority = (typeof SOFT_PRIORITY_VALUES)[number];
 
 /**
  * A team member available for scheduling.
@@ -131,7 +157,7 @@ export interface ShiftPattern {
 }
 
 export interface TimeInterval {
-  day: string;
+  day: DateString;
   startTime: TimeOfDay;
   endTime: TimeOfDay;
 }
@@ -215,12 +241,35 @@ interface SkillBasedCoverageRequirement extends CoverageRequirementBase {
  */
 export type CoverageRequirement = RoleBasedCoverageRequirement | SkillBasedCoverageRequirement;
 
+/**
+ * Compile-time solve profile used by model builders.
+ *
+ * @category Model Builder
+ */
+export type ModelSolveStrategy =
+  | {
+      /** Build the normal optimized solver request. */
+      readonly type: "optimize";
+    }
+  | {
+      /** Build a hard-feasibility request that ignores objectives and soft constraints. */
+      readonly type: "feasibility-only";
+    };
+
 /** Optional settings for the model builder. */
 export interface ModelBuilderOptions {
   /** Which day starts the week for weekly rules. Defaults to "monday". */
   weekStartsOn?: DayOfWeek;
   /** Solver-level options (time limit, solution limit). */
   solverOptions?: SolverRequest["options"];
+  /** Compile-time solve profile. Defaults to optimized solving. */
+  strategy?: ModelSolveStrategy;
+  /**
+   * Internal objective stage order for staged solver requests.
+   *
+   * @internal
+   */
+  objectiveStageOrder?: readonly string[];
   /**
    * Bucket size used when translating coverage requirements into time-indexed constraints.
    * Smaller buckets are more accurate but increase the number of constraints.

package/src/cpsat/utils.ts

@@ -1,6 +1,5 @@
-import { DAY_OF_WEEK_MAP } from "../datetime.utils.js";
-import type { DayOfWeek, TimeOfDay } from "../types.js";
-import type { Priority } from "./types.js";
+import { DAY_OF_WEEK_INDEX, type DayOfWeek, type SchedulingDay, type TimeOfDay } from "../types.js";
+import type { Priority, SoftPriority } from "./types.js";
 
 export const MINUTES_PER_DAY = 24 * 60;
 
@@ -43,12 +42,17 @@ export const OBJECTIVE_WEIGHTS = {
 } as const;
 
 /**
- * Parse a day string (YYYY-MM-DD) to a UTC Date.
- * Used internally for day-of-week calculations and date comparisons.
+ * Maps {@link Priority} levels to penalty weights for preference rules.
+ *
+ * Used by `assignment-priority`, `location-preference`, and `role-preference`
+ * to scale the strength of their soft constraints.
  */
-export function parseDayString(day: string): Date {
-  return new Date(`${day}T00:00:00Z`);
-}
+export const PREFERENCE_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,
+};
 
 export function timeOfDayToMinutes(time: TimeOfDay): number {
   return time.hours * 60 + (time.minutes ?? 0);
@@ -70,6 +74,16 @@ export function priorityToPenalty(priority: Priority): number {
   return PRIORITY_PENALTIES[priority];
 }
 
+const TARGET_PEAK_PRIORITY_PENALTIES = {
+  LOW: OBJECTIVE_WEIGHTS.COST,
+  MEDIUM: OBJECTIVE_WEIGHTS.SHIFT_ACTIVE,
+  HIGH: OBJECTIVE_WEIGHTS.SHIFT_ACTIVE * 2.5,
+} as const satisfies Record<SoftPriority, number>;
+
+export function targetPeakPriorityToPenalty(priority: SoftPriority): number {
+  return TARGET_PEAK_PRIORITY_PENALTIES[priority];
+}
+
 /**
  * Computes the total duration of the union of time ranges.
  *
@@ -80,8 +94,10 @@ export function priorityToPenalty(priority: Priority): number {
 export function unionMinutes(ranges: ReadonlyArray<{ start: number; end: number }>): number {
   if (ranges.length === 0) return 0;
   const sorted = ranges.toSorted((a, b) => a.start - b.start);
+  const first = sorted[0];
+  if (!first) return 0;
   let total = 0;
-  let currentEnd = sorted[0]!.start;
+  let currentEnd = first.start;
   for (const r of sorted) {
     const effectiveStart = Math.max(r.start, currentEnd);
     if (effectiveStart < r.end) {
@@ -92,28 +108,84 @@ export function unionMinutes(ranges: ReadonlyArray<{ start: number; end: number
   return total;
 }
 
-export function splitIntoWeeks(days: string[], weekStartsOn: DayOfWeek): string[][] {
+/**
+ * Splits scheduling days into non-overlapping chunks of N calendar months.
+ *
+ * Days are grouped by their {@link SchedulingDay.yearMonth}, then consecutive
+ * months are merged into chunks of the requested size.
+ */
+export function splitIntoMonths(days: SchedulingDay[], monthsPerChunk: number): SchedulingDay[][] {
+  if (days.length === 0) return [];
+
+  const monthGroups = new Map<string, SchedulingDay[]>();
+  for (const day of days) {
+    let group = monthGroups.get(day.yearMonth);
+    if (!group) {
+      group = [];
+      monthGroups.set(day.yearMonth, group);
+    }
+    group.push(day);
+  }
+
+  const sortedKeys = [...monthGroups.keys()].toSorted();
+  const chunks: SchedulingDay[][] = [];
+
+  for (let i = 0; i < sortedKeys.length; i += monthsPerChunk) {
+    const chunkKeys = sortedKeys.slice(i, i + monthsPerChunk);
+    const chunk = chunkKeys.flatMap((key) => monthGroups.get(key)!);
+    if (chunk.length > 0) {
+      chunks.push(chunk);
+    }
+  }
+
+  return chunks;
+}
+
+/**
+ * Groups days into chunks of N weeks, aligned to weekStartsOn.
+ *
+ * Uses {@link splitIntoWeeks} internally, then merges consecutive weeks
+ * into larger chunks.
+ */
+export function groupWeekChunks(
+  days: SchedulingDay[],
+  weeksPerChunk: number,
+  weekStartsOn: DayOfWeek,
+): SchedulingDay[][] {
+  const weeks = splitIntoWeeks(days, weekStartsOn);
+  const chunks: SchedulingDay[][] = [];
+
+  for (let i = 0; i < weeks.length; i += weeksPerChunk) {
+    const chunk = weeks.slice(i, i + weeksPerChunk).flat();
+    if (chunk.length > 0) {
+      chunks.push(chunk);
+    }
+  }
+
+  return chunks;
+}
+
+export function splitIntoWeeks(days: SchedulingDay[], weekStartsOn: DayOfWeek): SchedulingDay[][] {
   if (days.length === 0) return [];
 
-  const weekStartIndex = DAY_OF_WEEK_MAP[weekStartsOn];
-  const result: string[][] = [];
-  let currentWeek: string[] = [];
-  let currentWeekStart: Date | null = null;
+  const weekStartIndex = DAY_OF_WEEK_INDEX[weekStartsOn];
+  const result: SchedulingDay[][] = [];
+  let currentWeek: SchedulingDay[] = [];
+  let currentWeekStartEpoch: number | null = null;
 
   for (const day of days) {
-    const date = parseDayString(day);
-    const isWeekStartDay = date.getUTCDay() === weekStartIndex;
+    const isWeekStartDay = DAY_OF_WEEK_INDEX[day.dayOfWeek] === weekStartIndex;
     const isNewWeek =
-      isWeekStartDay && currentWeekStart !== null && date.getTime() !== currentWeekStart.getTime();
+      isWeekStartDay && currentWeekStartEpoch !== null && day.epochDay !== currentWeekStartEpoch;
 
     if (isNewWeek) {
       result.push(currentWeek);
       currentWeek = [];
-      currentWeekStart = null;
+      currentWeekStartEpoch = null;
     }
 
-    if (currentWeekStart === null) {
-      currentWeekStart = date;
+    if (currentWeekStartEpoch === null) {
+      currentWeekStartEpoch = day.epochDay;
     }
     currentWeek.push(day);
   }

package/src/cpsat/validation-reporter.ts

@@ -1,4 +1,5 @@
 import type { SolverResponse } from "../client.types.js";
+import type { DateString } from "../types.js";
 import {
   type ScheduleError,
   type ScheduleViolation,
@@ -24,7 +25,7 @@ export interface ValidationReporter {
   reportRuleError(error: Omit<RuleError, "type" | "id">): void;
   reportSolverError(message: string): void;
 
-  // Violations (soft constraint issues)
+  // Violations (non-fatal feedback)
   reportCoverageViolation(violation: Omit<CoverageViolation, "type" | "id">): void;
   reportRuleViolation(violation: Omit<RuleViolation, "type" | "id">): void;
 
@@ -41,9 +42,17 @@ export interface ValidationReporter {
   getExclusions(): CoverageExclusion[];
 
   // Post-solve analysis
-  analyzeSolution(response: SolverResponse): void;
+  analyzeSolution(response: SolverResponse, options?: AnalyzeSolutionOptions): void;
 }
 
+export interface AnalyzeSolutionOptions {
+  /** Whether solver-reported soft constraint diagnostics should update validation. */
+  analyzeSoftConstraints?: boolean;
+}
+
+const MISSING_SOFT_CONSTRAINT_VIOLATIONS_ERROR =
+  "Solver response missing softConstraintViolations for tracked soft constraints.";
+
 /**
  * Generates a deterministic ID for a coverage-based validation item.
  * Format: {category}:coverage:{day}:{timeSlots}:{roles}:{skills}
@@ -91,19 +100,28 @@ export class ValidationReporterImpl implements ValidationReporter {
   #passed: SchedulePassed[] = [];
   #trackedConstraints = new Map<string, TrackedConstraint>();
   #exclusions: CoverageExclusion[] = [];
+  #validationIdCounts = new Map<string, number>();
   #solverErrorCount = 0;
 
+  #nextValidationId(baseId: string): string {
+    const count = (this.#validationIdCounts.get(baseId) ?? 0) + 1;
+    this.#validationIdCounts.set(baseId, count);
+    return count === 1 ? baseId : `${baseId}:${count}`;
+  }
+
   excludeFromCoverage(exclusion: CoverageExclusion): void {
     this.#exclusions.push(exclusion);
   }
 
   reportCoverageError(error: Omit<CoverageError, "type" | "id">): void {
-    const id = coverageId("error", error.day, error.timeSlots, error.roleIds, error.skillIds);
+    const id = this.#nextValidationId(
+      coverageId("error", error.day, error.timeSlots, error.roleIds, error.skillIds),
+    );
     this.#errors.push({ id, type: "coverage", ...error });
   }
 
   reportRuleError(error: Omit<RuleError, "type" | "id">): void {
-    const id = ruleId("error", error.rule, error.context);
+    const id = this.#nextValidationId(ruleId("error", error.rule, error.context));
     this.#errors.push({ id, type: "rule", ...error });
   }
 
@@ -114,28 +132,32 @@ export class ValidationReporterImpl implements ValidationReporter {
   }
 
   reportCoverageViolation(violation: Omit<CoverageViolation, "type" | "id">): void {
-    const id = coverageId(
-      "violation",
-      violation.day,
-      violation.timeSlots,
-      violation.roleIds,
-      violation.skillIds,
+    const id = this.#nextValidationId(
+      coverageId(
+        "violation",
+        violation.day,
+        violation.timeSlots,
+        violation.roleIds,
+        violation.skillIds,
+      ),
     );
     this.#violations.push({ id, type: "coverage", ...violation });
   }
 
   reportRuleViolation(violation: Omit<RuleViolation, "type" | "id">): void {
-    const id = ruleId("violation", violation.rule, violation.context);
+    const id = this.#nextValidationId(ruleId("violation", violation.rule, violation.context));
     this.#violations.push({ id, type: "rule", ...violation });
   }
 
   reportCoveragePassed(passed: Omit<CoveragePassed, "type" | "id">): void {
-    const id = coverageId("passed", passed.day, passed.timeSlots, passed.roleIds, passed.skillIds);
+    const id = this.#nextValidationId(
+      coverageId("passed", passed.day, passed.timeSlots, passed.roleIds, passed.skillIds),
+    );
     this.#passed.push({ id, type: "coverage", ...passed });
   }
 
   reportRulePassed(passed: Omit<RulePassed, "type" | "id">): void {
-    const id = ruleId("passed", passed.rule, passed.context);
+    const id = this.#nextValidationId(ruleId("passed", passed.rule, passed.context));
     this.#passed.push({ id, type: "rule", ...passed });
   }
 
@@ -163,10 +185,16 @@ export class ValidationReporterImpl implements ValidationReporter {
     return [...this.#trackedConstraints.values()];
   }
 
-  analyzeSolution(response: SolverResponse): void {
+  analyzeSolution(response: SolverResponse, options?: AnalyzeSolutionOptions): void {
     if (response.status !== "OPTIMAL" && response.status !== "FEASIBLE") {
       if (response.status === "INFEASIBLE") {
+        this.#reportHardConstraintConflicts(
+          (response.hardConstraintConflicts ?? []).map((conflict) => conflict.constraintId),
+        );
         this.reportSolverError(response.solutionInfo ?? "Schedule is infeasible");
+        if (response.error) {
+          this.reportSolverError(response.error);
+        }
       } else if (response.status === "TIMEOUT") {
         this.reportSolverError("Solver timed out");
       } else if (response.error) {
@@ -175,16 +203,33 @@ export class ValidationReporterImpl implements ValidationReporter {
       return;
     }
 
-    const solverViolations = response.softViolations ?? [];
+    const analyzeSoftConstraints = options?.analyzeSoftConstraints ?? true;
+
+    const hasTrackedSoftConstraints = [...this.#trackedConstraints.values()].some(
+      (constraint) => constraint.source === "soft",
+    );
+
+    if (
+      analyzeSoftConstraints &&
+      hasTrackedSoftConstraints &&
+      response.softConstraintViolations === undefined
+    ) {
+      throw new Error(MISSING_SOFT_CONSTRAINT_VIOLATIONS_ERROR);
+    }
+
+    const solverViolations = analyzeSoftConstraints
+      ? (response.softConstraintViolations ?? [])
+      : [];
 
     for (const violation of solverViolations) {
       const tracked = this.#trackedConstraints.get(violation.constraintId);
 
       if (tracked?.type === "coverage") {
+        if (!tracked.day) continue;
         const roles = tracked.roleIds?.join(", ") ?? "staff";
         const slot = tracked.timeSlot ?? "all day";
         this.reportCoverageViolation({
-          day: tracked.day ?? "",
+          day: tracked.day,
           timeSlots: tracked.timeSlot ? [tracked.timeSlot] : [],
           roleIds: tracked.roleIds,
           skillIds: tracked.skillIds,
@@ -216,11 +261,13 @@ export class ValidationReporterImpl implements ValidationReporter {
     // Mark tracked coverage constraints as passed if not violated
     const violatedIds = new Set(solverViolations.map((v) => v.constraintId));
     for (const tracked of this.#trackedConstraints.values()) {
+      if (!analyzeSoftConstraints && tracked.source === "soft") continue;
       if (violatedIds.has(tracked.id)) continue;
 
       if (tracked.type === "coverage") {
+        if (!tracked.day) continue;
         this.reportCoveragePassed({
-          day: tracked.day ?? "",
+          day: tracked.day,
           timeSlots: tracked.timeSlot ? [tracked.timeSlot] : [],
           roleIds: tracked.roleIds,
           skillIds: tracked.skillIds,
@@ -230,6 +277,110 @@ export class ValidationReporterImpl implements ValidationReporter {
       }
     }
   }
+
+  #reportHardConstraintConflicts(constraintIds: readonly string[]): void {
+    if (constraintIds.length === 0) {
+      return;
+    }
+
+    type CoverageGroup = {
+      day: DateString;
+      timeSlots: Set<string>;
+      roleIds?: string[];
+      skillIds?: readonly string[];
+      group?: TrackedConstraint["group"];
+      descriptions: string[];
+    };
+    type RuleGroup = {
+      rule: string;
+      days: Set<DateString>;
+      memberIds: Set<string>;
+      group?: TrackedConstraint["group"];
+      descriptions: string[];
+    };
+
+    const coverageGroups = new Map<string, CoverageGroup>();
+    const ruleGroups = new Map<string, RuleGroup>();
+
+    for (const constraintId of constraintIds) {
+      const tracked = this.#trackedConstraints.get(constraintId);
+      if (!tracked) continue;
+
+      if (tracked.type === "coverage") {
+        if (!tracked.day) continue;
+        const key = [
+          tracked.group?.key ?? tracked.id,
+          tracked.day,
+          tracked.roleIds?.join(",") ?? "_",
+          tracked.skillIds?.join(",") ?? "_",
+        ].join(":");
+        const existing = coverageGroups.get(key);
+        if (existing) {
+          if (tracked.timeSlot) existing.timeSlots.add(tracked.timeSlot);
+          existing.descriptions.push(tracked.description);
+          continue;
+        }
+        coverageGroups.set(key, {
+          day: tracked.day,
+          timeSlots: new Set(tracked.timeSlot ? [tracked.timeSlot] : []),
+          roleIds: tracked.roleIds,
+          skillIds: tracked.skillIds,
+          group: tracked.group,
+          descriptions: [tracked.description],
+        });
+        continue;
+      }
+
+      const key = tracked.group?.key ?? tracked.id;
+      const existing = ruleGroups.get(key);
+      if (existing) {
+        for (const day of tracked.context.days ?? []) existing.days.add(day);
+        for (const memberId of tracked.context.memberIds ?? []) existing.memberIds.add(memberId);
+        existing.descriptions.push(tracked.description);
+        continue;
+      }
+      ruleGroups.set(key, {
+        rule: tracked.rule ?? "unknown",
+        days: new Set(tracked.context.days ?? []),
+        memberIds: new Set(tracked.context.memberIds ?? []),
+        group: tracked.group,
+        descriptions: [tracked.description],
+      });
+    }
+
+    for (const coverage of coverageGroups.values()) {
+      const label = coverage.group?.title ?? coverage.descriptions[0] ?? "Coverage requirement";
+      this.reportCoverageError({
+        day: coverage.day,
+        timeSlots: [...coverage.timeSlots].toSorted(),
+        roleIds: coverage.roleIds,
+        skillIds: coverage.skillIds,
+        message: `${label} is part of a sufficient infeasible constraint set.`,
+        suggestions: [
+          "Relax this mandatory coverage requirement",
+          "Relax conflicting mandatory rules or add eligible team members",
+        ],
+        group: coverage.group,
+      });
+    }
+
+    for (const rule of ruleGroups.values()) {
+      const label = rule.group?.title ?? rule.descriptions[0] ?? rule.rule;
+      this.reportRuleError({
+        rule: rule.rule,
+        message: `${label} is part of a sufficient infeasible constraint set.`,
+        context: {
+          days: [...rule.days].toSorted(),
+          memberIds: [...rule.memberIds].toSorted(),
+        },
+        suggestions: [
+          "Relax this mandatory rule",
+          "Relax conflicting mandatory coverage requirements or add eligible team members",
+        ],
+        group: rule.group,
+      });
+    }
+  }
 }
 
 // =============================================================================
@@ -265,7 +416,7 @@ export function summarizeValidation(validation: ScheduleValidation): readonly Va
     {
       type: "coverage" | "rule";
       title: string;
-      days: Set<string>;
+      days: Set<DateString>;
       passedCount: number;
       violatedCount: number;
       errorCount: number;
@@ -280,7 +431,7 @@ export function summarizeValidation(validation: ScheduleValidation): readonly Va
       groups.set(key, {
         type: item.type,
         title,
-        days: new Set(),
+        days: new Set<DateString>(),
         passedCount: 0,
         violatedCount: 0,
         errorCount: 0,

package/src/cpsat/validation.types.ts

@@ -1,10 +1,10 @@
-import type { TimeOfDay } from "../types.js";
+import type { DateString, TimeOfDay } from "../types.js";
 
 /**
  * Context shared across validation results for grouping/display.
  */
 export interface ValidationContext {
-  days?: string[];
+  days?: DateString[];
   timeSlots?: string[];
   memberIds?: string[];
 }
@@ -60,7 +60,7 @@ export function assertSafeKeySegments(values: readonly string[], label: string):
 export interface CoverageError {
   readonly id: string;
   readonly type: "coverage";
-  readonly day: string;
+  readonly day: DateString;
   readonly timeSlots: readonly string[];
   readonly roleIds?: string[];
   readonly skillIds?: readonly string[];
@@ -88,13 +88,13 @@ export interface SolverError {
 export type ScheduleError = CoverageError | RuleError | SolverError;
 
 // =============================================================================
-// Violations - soft constraints not met, but schedule generated
+// Violations - non-fatal unmet requirements or preferences
 // =============================================================================
 
 export interface CoverageViolation {
   readonly id: string;
   readonly type: "coverage";
-  readonly day: string;
+  readonly day: DateString;
   readonly timeSlots: readonly string[];
   readonly roleIds?: string[];
   readonly skillIds?: readonly string[];
@@ -125,7 +125,7 @@ export type ScheduleViolation = CoverageViolation | RuleViolation;
 export interface CoveragePassed {
   readonly id: string;
   readonly type: "coverage";
-  readonly day: string;
+  readonly day: DateString;
   readonly timeSlots: readonly string[];
   readonly roleIds?: string[];
   readonly skillIds?: readonly string[];
@@ -148,7 +148,17 @@ export type SchedulePassed = CoveragePassed | RulePassed;
 // Complete validation result
 // =============================================================================
 
-/** @category Validation */
+/**
+ * Public validation feedback collected across pre-solve, solver-stage, and
+ * post-solve analysis.
+ *
+ * @remarks
+ * This is not a direct mirror of the raw solver response. Solver transport
+ * fields such as `softConstraintViolations` are translated into these
+ * phase-agnostic `errors`, `violations`, and `passed` items.
+ *
+ * @category Validation
+ */
 export interface ScheduleValidation {
   readonly errors: readonly ScheduleError[];
   readonly violations: readonly ScheduleViolation[];
@@ -171,7 +181,7 @@ export interface ValidationSummary {
   readonly type: "coverage" | "rule";
   /** Human-readable title for this group (e.g., "3x nurse during day_ward"). */
   readonly title: string;
-  readonly days: readonly string[];
+  readonly days: readonly DateString[];
   readonly status: "passed" | "partial" | "failed";
   readonly passedCount: number;
   readonly violatedCount: number;
@@ -185,12 +195,13 @@ export interface ValidationSummary {
 export interface TrackedConstraint {
   readonly id: string;
   readonly type: "coverage" | "rule";
+  readonly source?: "hard" | "soft";
   readonly rule?: string;
   /** Per-constraint description used to generate violation messages. */
   readonly description: string;
   readonly targetValue: number;
-  readonly comparator: "<=" | ">=";
-  readonly day?: string;
+  readonly comparator: "<=" | ">=" | "==";
+  readonly day?: DateString;
   readonly timeSlot?: string;
   readonly roleIds?: string[];
   readonly skillIds?: readonly string[];
@@ -204,7 +215,7 @@ export interface TrackedConstraint {
  */
 export interface CoverageExclusion {
   memberId: string;
-  day: string;
+  day: DateString;
   startTime?: TimeOfDay;
   endTime?: TimeOfDay;
 }