dabke 0.82.0 → 0.84.0

package/src/cpsat/rules/time-off.ts

@@ -1,26 +1,30 @@
 import * as z from "zod";
 import type { TimeOfDay } from "../../types.js";
-import type { CompilationRule, RuleValidationContext } from "../model-builder.js";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
+import type { RuleArtifact, RuleCompileContext } from "../rule-descriptor.js";
+import type { ValidationReporter } from "../validation-reporter.js";
 import type { ResolvedShiftAssignment } from "../response.js";
 import { normalizeEndMinutes, priorityToPenalty, timeOfDayToMinutes } from "../utils.js";
-import type { ValidationReporter } from "../validation-reporter.js";
 import {
   PrioritySchema,
   entityScope,
-  requiredTimeScope,
   parseEntityScope,
   parseTimeScope,
-  resolveMembersFromScope,
+  requiredTimeScope,
   resolveActiveDaysFromScope,
+  resolveMembersFromScope,
   ruleGroup,
 } from "./scope.types.js";
+import { assignmentVar } from "./variables.js";
+import { hardConstraint, reportValidation, softConstraint } from "./artifacts.js";
+import { canAssignMemberToPattern, isPatternAvailableOnDay } from "./pattern-eligibility.js";
 
 const timeOfDaySchema = z.object({
   hours: z.number().int().min(0).max(23),
   minutes: z.number().int().min(0).max(59),
 });
 
-const TimeOffSchema = z
+export const TimeOffSchema = z
   .object({
     priority: PrioritySchema,
     startTime: timeOfDaySchema.optional(),
@@ -40,173 +44,143 @@ const TimeOffSchema = z
   );
 
 /**
- * Configuration for {@link createTimeOffRule}.
- *
- * - `priority` (required): how strictly the solver enforces this rule
- * - `startTime` (optional): start of the time-off window within each day; must be paired with `endTime`
- * - `endTime` (optional): end of the time-off window within each day; must be paired with `startTime`
- *
- * Entity scoping (at most one):
- * - `memberIds`: restrict to specific members
- * - `roleIds`: restrict to members with matching roles
- * - `skillIds`: restrict to members with matching skills
- *
- * Time scoping (exactly one required):
- * - `dateRange`: contiguous date range
- * - `specificDates`: specific dates
- * - `dayOfWeek`: days of the week
- * - `recurringPeriods`: recurring calendar periods
+ * Configuration for {@link timeOffRuleDescriptor}.
  */
 export type TimeOffConfig = z.infer<typeof TimeOffSchema>;
 
 /**
- * Blocks or penalizes assignments during specified time periods.
+ * Low-level descriptor for the `time-off` rule.
  *
- * Supports entity scoping (people, roles, skills) and time scoping
- * (date ranges, specific dates, days of week, recurring periods).
- * Optionally supports partial-day time-off with startTime/endTime.
- *
- * @param config - See {@link TimeOffConfig}
- * @example Full day vacation
- * ```ts
- * createTimeOffRule({
- *   memberIds: ["alice"],
- *   dateRange: { start: "2024-02-01", end: "2024-02-05" },
- *   priority: "MANDATORY",
- * });
- * ```
- *
- * @example Every Wednesday afternoon off for students
- * ```ts
- * createTimeOffRule({
- *   roleIds: ["student"],
- *   dayOfWeek: ["wednesday"],
- *   startTime: { hours: 14, minutes: 0 },
- *   endTime: { hours: 23, minutes: 59 },
- *   priority: "MANDATORY",
- * });
- * ```
- *
- * @example Specific date, partial day
- * ```ts
- * createTimeOffRule({
- *   memberIds: ["bob"],
- *   specificDates: ["2024-03-15"],
- *   startTime: { hours: 16, minutes: 0 },
- *   endTime: { hours: 23, minutes: 59 },
- *   priority: "MANDATORY",
- * });
- * ```
+ * @category Rules
  */
-export function createTimeOffRule(config: TimeOffConfig): CompilationRule {
-  const parsed = TimeOffSchema.parse(config);
-  const { priority, startTime, endTime } = parsed;
-
-  const fullDayStart: TimeOfDay = { hours: 0, minutes: 0 };
-  const fullDayEnd: TimeOfDay = { hours: 23, minutes: 59 };
-  const timeWindowStart = startTime ?? fullDayStart;
-  const timeWindowEnd = endTime ?? fullDayEnd;
-
-  const entityScopeValue = parseEntityScope(parsed);
-  const timeScopeValue = parseTimeScope(parsed);
-  const group = ruleGroup("time-off", "Time off", entityScopeValue, timeScopeValue);
-
-  return {
-    compile(builder) {
-      const targetMembers = resolveMembersFromScope(entityScopeValue, builder.members);
-      if (targetMembers.length === 0) return;
-
-      const activeDays = resolveActiveDaysFromScope(timeScopeValue, builder.days);
-      if (activeDays.length === 0) return;
-
-      for (const emp of targetMembers) {
-        for (const day of activeDays) {
-          // Report exclusion for coverage analysis (MANDATORY only)
-          if (priority === "MANDATORY") {
-            builder.reporter.excludeFromCoverage({
-              memberId: emp.id,
-              day,
-              startTime: timeWindowStart,
-              endTime: timeWindowEnd,
-            });
-          }
-
-          for (const pattern of builder.shiftPatterns) {
-            if (!builder.canAssign(emp, pattern)) continue;
-            if (!builder.patternAvailableOnDay(pattern, day)) continue;
-
-            if (startTime && endTime) {
-              if (!shiftOverlapsTimeWindow(pattern, startTime, endTime)) {
-                continue;
-              }
-            }
-
-            const assignVar = builder.assignment(emp.id, pattern.id, day);
-
-            if (priority === "MANDATORY") {
-              builder.addLinear([{ var: assignVar, coeff: 1 }], "==", 0);
-            } else {
-              builder.addSoftLinear(
-                [{ var: assignVar, coeff: 1 }],
-                "<=",
-                0,
-                priorityToPenalty(priority),
-              );
-            }
-          }
-        }
-      }
-    },
-
-    validate(
-      assignments: ResolvedShiftAssignment[],
-      reporter: ValidationReporter,
-      context: RuleValidationContext,
-    ) {
-      // MANDATORY time-off is a hard constraint - can't be violated
-      if (priority === "MANDATORY") return;
-
-      const targetMembers = resolveMembersFromScope(entityScopeValue, context.members);
-      if (targetMembers.length === 0) return;
-
-      const activeDays = resolveActiveDaysFromScope(timeScopeValue, context.days);
-      if (activeDays.length === 0) return;
-
-      for (const emp of targetMembers) {
-        for (const day of activeDays) {
-          const violated = assignments.some(
-            (a) =>
-              a.memberId === emp.id &&
-              a.day === day &&
-              assignmentOverlapsTimeWindow(a, timeWindowStart, timeWindowEnd),
-          );
-
-          if (violated) {
-            reporter.reportRuleViolation({
-              rule: "time-off",
-              message: `Time-off request for ${emp.id} on ${day} could not be honored`,
-              context: {
-                memberIds: [emp.id],
-                days: [day],
-              },
+export const timeOffRuleDescriptor = defineRuleDescriptor({
+  name: "time-off",
+  schema: TimeOffSchema,
+  compile(config, ctx) {
+    const { priority, startTime, endTime } = config;
+    const fullDayStart: TimeOfDay = { hours: 0, minutes: 0 };
+    const fullDayEnd: TimeOfDay = { hours: 23, minutes: 59 };
+    const timeWindowStart = startTime ?? fullDayStart;
+    const timeWindowEnd = endTime ?? fullDayEnd;
+
+    const entityScopeValue = parseEntityScope(config);
+    const timeScopeValue = parseTimeScope(config);
+    const group = ruleGroup("time-off", "Time off", entityScopeValue, timeScopeValue);
+    const targetMembers = resolveMembersFromScope(entityScopeValue, [...ctx.members]);
+    const activeDays = resolveActiveDaysFromScope(timeScopeValue, [...ctx.days]);
+    const timeWindowKey = formatTimeWindowKey(timeWindowStart, timeWindowEnd);
+
+    const constraintArtifacts: RuleArtifact[] = [];
+    for (const member of targetMembers) {
+      for (const day of activeDays) {
+        const overlappingVars = ctx.shiftPatterns
+          .filter(
+            (pattern) =>
+              canAssignMemberToPattern(member, pattern) &&
+              isPatternAvailableOnDay(pattern, day) &&
+              shiftOverlapsTimeWindow(pattern, timeWindowStart, timeWindowEnd),
+          )
+          .map((pattern) => assignmentVar(member.id, pattern.id, day.iso));
+
+        if (overlappingVars.length === 0) continue;
+
+        const description = buildTimeOffDescription(
+          member.id,
+          day.iso,
+          timeWindowStart,
+          timeWindowEnd,
+        );
+        const context = { memberIds: [member.id], days: [day.iso] };
+        const constraintId = `time-off:${group.key}:${member.id}:${day.iso}:${timeWindowKey}`;
+        const terms = overlappingVars.map((varName) => ({ var: varName, coeff: 1 }));
+
+        if (priority === "MANDATORY") {
+          constraintArtifacts.push({
+            kind: "coverage-exclusion",
+            group,
+            memberId: member.id,
+            day: day.iso,
+            startTime: timeWindowStart,
+            endTime: timeWindowEnd,
+          });
+          constraintArtifacts.push(
+            hardConstraint({
               group,
-            });
-          } else {
-            reporter.reportRulePassed({
-              rule: "time-off",
-              message: `Time-off honored for ${emp.id} on ${day}`,
-              context: {
-                memberIds: [emp.id],
-                days: [day],
-              },
+              description,
+              context,
+              validation: reportValidation(constraintId),
+              terms,
+              comparator: "<=",
+              targetValue: 0,
+            }),
+          );
+        } else {
+          constraintArtifacts.push(
+            softConstraint({
               group,
-            });
-          }
+              description,
+              context,
+              validation: reportValidation(),
+              terms,
+              comparator: "<=",
+              targetValue: 0,
+              penalty: priorityToPenalty(priority),
+              constraintId,
+            }),
+          );
         }
       }
-    },
-  };
-}
+    }
+
+    const postSolveValidator =
+      priority === "MANDATORY"
+        ? []
+        : [
+            {
+              kind: "post-solve-feedback" as const,
+              run(
+                assignments: readonly ResolvedShiftAssignment[],
+                reporter: ValidationReporter,
+                validationContext: RuleCompileContext,
+              ) {
+                const validatorMembers = resolveMembersFromScope(entityScopeValue, [
+                  ...validationContext.members,
+                ]);
+                const validatorDays = resolveActiveDaysFromScope(timeScopeValue, [
+                  ...validationContext.days,
+                ]);
+
+                for (const member of validatorMembers) {
+                  for (const day of validatorDays) {
+                    const violated = assignments.some(
+                      (assignment) =>
+                        assignment.memberId === member.id &&
+                        assignment.day === day.iso &&
+                        assignmentOverlapsTimeWindow(assignment, timeWindowStart, timeWindowEnd),
+                    );
+
+                    if (violated) {
+                      continue;
+                    }
+
+                    reporter.reportRulePassed({
+                      rule: "time-off",
+                      message: `Time-off honored for ${member.id} on ${day.iso}`,
+                      context: { memberIds: [member.id], days: [day.iso] },
+                      group,
+                    });
+                  }
+                }
+              },
+            },
+          ];
+
+    return {
+      rule: "time-off",
+      artifacts: [...constraintArtifacts, ...postSolveValidator],
+    };
+  },
+});
 
 function shiftOverlapsTimeWindow(
   pattern: { startTime: TimeOfDay; endTime: TimeOfDay },
@@ -223,7 +197,7 @@ function shiftOverlapsTimeWindow(
 }
 
 function assignmentOverlapsTimeWindow(
-  assignment: ResolvedShiftAssignment,
+  assignment: { startTime: TimeOfDay; endTime: TimeOfDay },
   windowStart: TimeOfDay,
   windowEnd: TimeOfDay,
 ): boolean {
@@ -235,3 +209,20 @@ function assignmentOverlapsTimeWindow(
 
   return Math.max(assignStart, winStart) < Math.min(assignEnd, winEnd);
 }
+
+function buildTimeOffDescription(
+  memberId: string,
+  dayIso: string,
+  windowStart: TimeOfDay,
+  windowEnd: TimeOfDay,
+): string {
+  return `Time off for ${memberId} on ${dayIso} (${formatTimeWindowKey(windowStart, windowEnd)})`;
+}
+
+function formatTimeWindowKey(windowStart: TimeOfDay, windowEnd: TimeOfDay): string {
+  return `${formatTimeOfDay(windowStart)}-${formatTimeOfDay(windowEnd)}`;
+}
+
+function formatTimeOfDay(time: TimeOfDay): string {
+  return `${time.hours.toString().padStart(2, "0")}:${time.minutes.toString().padStart(2, "0")}`;
+}

package/src/cpsat/rules/variables.ts

@@ -0,0 +1,11 @@
+export function assignmentVar(memberId: string, patternId: string, dayIso: string): string {
+  return `assign:${memberId}:${patternId}:${dayIso}`;
+}
+
+export function assignedDayVariableName(memberId: string, dayIso: string): string {
+  return `assigned_day_${memberId}_${dayIso}`;
+}
+
+export function assignedDayStartVariableName(memberId: string, dayIso: string): string {
+  return `assigned_day_start_${memberId}_${dayIso}`;
+}

package/src/cpsat/rules.ts

@@ -1,27 +1,53 @@
+/**
+ * Low-level CP-SAT rule descriptor and registry APIs.
+ *
+ * @remarks
+ * These exports are intended for advanced consumers building custom rule
+ * registries or integrating directly with the descriptor layer underneath the
+ * high-level {@link schedule} helpers.
+ *
+ * Rules are the feedback unit. Validation groups summarize rule outcomes for
+ * presentation, while individual solver constraints remain implementation
+ * details. Descriptor compilation therefore emits artifacts that make the
+ * validation story explicit: reported constraints, pre-solve feedback,
+ * post-solve validators, cost contributions, and explicit skip strategies for
+ * scaffolding or artifacts with no meaningful validation feedback.
+ *
+ * @module
+ */
+
 export {
-  createAssignTogetherRule,
-  createAssignmentPriorityRule,
-  createLocationPreferenceRule,
-  createMaxConsecutiveDaysRule,
-  createMaxHoursDayRule,
-  createMaxHoursWeekRule,
-  createMinConsecutiveDaysRule,
-  createMinHoursDayRule,
-  createMinHoursWeekRule,
-  createMinRestBetweenShiftsRule,
-  createTimeOffRule,
+  assignTogetherRuleDescriptor,
+  assignmentPriorityRuleDescriptor,
+  locationPreferenceRuleDescriptor,
+  maxConcurrentAssignmentsRuleDescriptor,
+  maxConsecutiveDaysRuleDescriptor,
+  maxHoursDayRuleDescriptor,
+  maxHoursWeekRuleDescriptor,
+  minConsecutiveDaysRuleDescriptor,
+  minHoursDayRuleDescriptor,
+  minHoursWeekRuleDescriptor,
+  minRestBetweenShiftsRuleDescriptor,
+  targetDaysWeekRuleDescriptor,
+  targetPeakConcurrentAssignmentsRuleDescriptor,
+  timeOffRuleDescriptor,
 } from "./rules/index.js";
 
-export { builtInCpsatRuleFactories, createCpsatRuleFactory } from "./rules/registry.js";
+export {
+  assertValidCpsatRuleRegistry,
+  builtInCpsatRuleRegistry,
+  createCpsatRuleRegistry,
+} from "./rules/registry.js";
 
 export type {
+  AnyCpsatRuleConfigEntry,
+  BuiltInCpsatRuleConfigRegistry,
+  BuiltInCpsatRuleRegistry,
+  CpsatRuleConfigByName,
+  CpsatRuleConfigEntry,
+  CpsatRuleConfigEntryFor,
   CpsatRuleName,
   CpsatRuleRegistry,
-  CpsatRuleFactories,
-  BuiltInCpsatRuleFactories,
-  CpsatRuleRegistryFromFactories,
-  CreateCpsatRuleFunction,
-  CpsatRuleConfigEntry,
 } from "./rules/rules.types.js";
 
 export { buildCpsatRules, getMemberIdsForScope, resolveRuleScopes } from "./rules/resolver.js";

package/src/cpsat/semantic-time.ts

@@ -1,6 +1,4 @@
-import type { DayOfWeek, TimeOfDay } from "../types.js";
-import { toDayOfWeekUTC } from "../datetime.utils.js";
-import { parseDayString } from "./utils.js";
+import type { DateString, DayOfWeek, SchedulingDay, TimeOfDay } from "../types.js";
 import type { CoverageRequirement, Priority } from "./types.js";
 import { assertSafeKeySegment, type ValidationGroup } from "./validation.types.js";
 
@@ -40,7 +38,7 @@ export interface SemanticTimeVariant extends SemanticTimeDef {
   /** Restrict this entry to specific days of the week. */
   dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]];
   /** Restrict this entry to specific dates (YYYY-MM-DD). */
-  dates?: string[];
+  dates?: DateString[];
 }
 
 /**
@@ -59,7 +57,7 @@ interface SemanticCoverageRequirementBase<S extends string> {
   /** Scope this requirement to specific days of the week */
   dayOfWeek?: [DayOfWeek, ...DayOfWeek[]];
   /** Scope this requirement to specific dates (YYYY-MM-DD) */
-  dates?: string[];
+  dates?: DateString[];
   /**
    * Override the auto-generated group for validation reporting.
    * If not provided, a group is auto-generated from the semantic time name,
@@ -141,7 +139,7 @@ export type SemanticCoverageRequirement<S extends string> =
  * Base fields shared by concrete coverage requirement variants.
  */
 interface ConcreteCoverageRequirementBase {
-  day: string;
+  day: DateString;
   startTime: TimeOfDay;
   endTime: TimeOfDay;
   targetCount: number;
@@ -199,6 +197,7 @@ export type ConcreteCoverageRequirement =
 /**
  * A day-specific count within a variant {@link cover} call.
  *
+ * @remarks
  * Each variant specifies a count and optional day/date scope. During
  * resolution, the most specific matching variant wins for each day
  * (`dates` > `dayOfWeek` > default), mirroring {@link SemanticTimeVariant}.
@@ -221,7 +220,7 @@ export interface CoverageVariant {
   /** Restrict this variant to specific days of the week. */
   dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]];
   /** Restrict this variant to specific dates (YYYY-MM-DD). */
-  dates?: string[];
+  dates?: DateString[];
   /** Defaults to `"MANDATORY"`. */
   priority?: Priority;
 }
@@ -337,7 +336,7 @@ export interface SemanticTimeContext<S extends string> {
    * Resolve all coverage requirements to concrete CoverageRequirement[]
    * for the given days in the scheduling horizon.
    */
-  resolve(reqs: MixedCoverageRequirement<S>[], days: string[]): CoverageRequirement[];
+  resolve(reqs: MixedCoverageRequirement<S>[], days: SchedulingDay[]): CoverageRequirement[];
 }
 
 /**
@@ -394,7 +393,7 @@ export function defineSemanticTimes<const T extends Record<string, SemanticTimeE
       return reqs;
     },
 
-    resolve(reqs: MixedCoverageRequirement<S>[], days: string[]): CoverageRequirement[] {
+    resolve(reqs: MixedCoverageRequirement<S>[], days: SchedulingDay[]): CoverageRequirement[] {
       return resolveSemanticCoverage(defs, reqs, days);
     },
   };
@@ -405,7 +404,7 @@ export function defineSemanticTimes<const T extends Record<string, SemanticTimeE
  * Handles the discriminated union by checking which variant to construct.
  */
 function buildCoverageRequirement(
-  day: string,
+  day: DateString,
   startTime: TimeOfDay,
   endTime: TimeOfDay,
   roleIds: [string, ...string[]] | undefined,
@@ -417,14 +416,11 @@ function buildCoverageRequirement(
   const base = { day, startTime, endTime, targetCount, priority, group };
 
   if (roleIds && roleIds.length > 0) {
-    // Role-based (with optional skills)
     return skillIds && skillIds.length > 0 ? { ...base, roleIds, skillIds } : { ...base, roleIds };
   } else if (skillIds && skillIds.length > 0) {
-    // Skill-only
     return { ...base, skillIds };
   }
 
-  // This shouldn't happen if input types are correct, but handle gracefully
   throw new Error(
     `Coverage requirement for day "${day}" must have at least one of roleIds or skillIds`,
   );
@@ -437,15 +433,15 @@ function buildCoverageRequirement(
 function resolveSemanticCoverage<S extends string>(
   defs: Record<S, SemanticTimeEntry>,
   reqs: MixedCoverageRequirement<S>[],
-  days: string[],
+  days: SchedulingDay[],
 ): CoverageRequirement[] {
   const result: CoverageRequirement[] = [];
-  const daySet = new Set(days);
+  const dayIsoSet = new Set(days.map((d) => d.iso));
 
   for (const req of reqs) {
     if (isConcreteCoverage(req)) {
       // Concrete requirement - pass through if day is in horizon
-      if (daySet.has(req.day)) {
+      if (dayIsoSet.has(req.day)) {
         const defaultGroup = concreteCoverageGroup(req);
         result.push(
           buildCoverageRequirement(
@@ -478,7 +474,7 @@ function resolveSemanticCoverage<S extends string>(
 
         result.push(
           buildCoverageRequirement(
-            day,
+            day.iso,
             resolved.startTime,
             resolved.endTime,
             req.roleIds,
@@ -504,7 +500,7 @@ function resolveSemanticCoverage<S extends string>(
         if (resolved) {
           result.push(
             buildCoverageRequirement(
-              day,
+              day.iso,
               resolved.startTime,
               resolved.endTime,
               req.roleIds,
@@ -568,21 +564,18 @@ function variantCoverageGroup<S extends string>(
  */
 function resolveVariantForDay(
   variants: readonly CoverageVariant[],
-  day: string,
+  day: SchedulingDay,
 ): CoverageVariant | null {
-  const date = parseDayString(day);
-  const dayOfWeek = toDayOfWeekUTC(date);
-
   let dateMatch: CoverageVariant | null = null;
   let dowMatch: CoverageVariant | null = null;
   let defaultMatch: CoverageVariant | null = null;
 
   for (const variant of variants) {
-    if (variant.dates && variant.dates.includes(day)) {
+    if (variant.dates && variant.dates.includes(day.iso)) {
       dateMatch = variant;
       break;
     }
-    if (variant.dayOfWeek && variant.dayOfWeek.includes(dayOfWeek)) {
+    if (variant.dayOfWeek && variant.dayOfWeek.includes(day.dayOfWeek)) {
       dowMatch = variant;
     }
     if (!variant.dates && !variant.dayOfWeek) {
@@ -607,8 +600,9 @@ function concreteCoverageGroup(req: ConcreteCoverageRequirement): ValidationGrou
  * Formats days of week for display in group keys.
  */
 function formatDaysScope(days: DayOfWeek[]): string {
-  if (days.length === 0) return "";
-  if (days.length === 1) return days[0]!;
+  const first = days[0];
+  if (!first) return "";
+  if (days.length === 1) return first;
 
   // Check for common patterns
   const weekdays = ["monday", "tuesday", "wednesday", "thursday", "friday"];
@@ -640,20 +634,18 @@ function formatTime(time: TimeOfDay): string {
  * Filter days based on optional day-of-week and specific date constraints.
  */
 function filterDays(
-  allDays: string[],
+  allDays: SchedulingDay[],
   dayOfWeek?: DayOfWeek[],
   specificDates?: string[],
-): string[] {
+): SchedulingDay[] {
   let result = allDays;
 
   if (specificDates && specificDates.length > 0) {
-    // If specific dates are provided, use only those (intersection with allDays)
     const dateSet = new Set(specificDates);
-    result = result.filter((d) => dateSet.has(d));
+    result = result.filter((d) => dateSet.has(d.iso));
   } else if (dayOfWeek && dayOfWeek.length > 0) {
-    // Filter by day of week
     const daySet = new Set(dayOfWeek);
-    result = result.filter((d) => daySet.has(toDayOfWeekUTC(parseDayString(d))));
+    result = result.filter((d) => daySet.has(d.dayOfWeek));
   }
 
   return result;
@@ -663,26 +655,21 @@ function filterDays(
  * Resolve the time definition for a specific day.
  * Returns the most specific match: date-specific > day-of-week > default.
  */
-function resolveTimeForDay(entry: SemanticTimeEntry, day: string): SemanticTimeDef | null {
-  // Simple definition - applies to all days
+function resolveTimeForDay(entry: SemanticTimeEntry, day: SchedulingDay): SemanticTimeDef | null {
   if (!Array.isArray(entry)) {
     return entry;
   }
 
-  const date = parseDayString(day);
-  const dayOfWeek = toDayOfWeekUTC(date);
-
-  // Find best match: date-specific first, then day-of-week, then default
   let dateMatch: SemanticTimeVariant | null = null;
   let dowMatch: SemanticTimeVariant | null = null;
   let defaultMatch: SemanticTimeVariant | null = null;
 
   for (const variant of entry) {
-    if (variant.dates && variant.dates.includes(day)) {
+    if (variant.dates && variant.dates.includes(day.iso)) {
       dateMatch = variant;
-      break; // Date-specific is most specific
+      break;
     }
-    if (variant.dayOfWeek && variant.dayOfWeek.includes(dayOfWeek)) {
+    if (variant.dayOfWeek && variant.dayOfWeek.includes(day.dayOfWeek)) {
       dowMatch = variant;
     }
     if (!variant.dates && !variant.dayOfWeek) {
@@ -690,6 +677,5 @@ function resolveTimeForDay(entry: SemanticTimeEntry, day: string): SemanticTimeD
     }
   }
 
-  const match = dateMatch ?? dowMatch ?? defaultMatch;
-  return match ?? null;
+  return dateMatch ?? dowMatch ?? defaultMatch ?? null;
 }