dabke 0.83.0 → 0.84.0

package/src/datetime.utils.ts

@@ -1,50 +1,46 @@
-import type { DayOfWeek, SchedulingPeriod } from "./types.js";
-
-export const DAY_OF_WEEK_MAP: Record<DayOfWeek, number> = {
-  sunday: 0, // JavaScript Date week starts on Sunday
-  monday: 1,
-  tuesday: 2,
-  wednesday: 3,
-  thursday: 4,
-  friday: 5,
-  saturday: 6,
-};
-
-const DAY_NAMES = [
-  "sunday",
-  "monday",
-  "tuesday",
-  "wednesday",
-  "thursday",
-  "friday",
-  "saturday",
-] as const;
+import {
+  DAY_NAMES,
+  type DateString,
+  type DayOfWeek,
+  type SchedulingDay,
+  type SchedulingPeriod,
+} from "./types.js";
 
 /**
- * Helper to get the day of week name from a Date (UTC).
- * Use this when working with date strings like "2026-01-10" that are timezone-agnostic.
+ * Builds a {@link SchedulingDay} from an existing UTC `Date`, avoiding a
+ * redundant `new Date()` call. Used internally by {@link resolveDaysFromPeriod}
+ * where the loop already maintains a `Date` cursor.
  */
-export function toDayOfWeekUTC(date: Date): DayOfWeek {
-  // getUTCDay() always returns 0-6
-  return DAY_NAMES[date.getUTCDay()] as DayOfWeek;
+function schedulingDayFromDate(date: Date, iso: DateString): SchedulingDay {
+  const dayOfWeek = DAY_NAMES[date.getUTCDay()]!;
+  const month = date.getUTCMonth() + 1;
+  const dayOfMonth = date.getUTCDate();
+  return {
+    iso,
+    dayOfWeek,
+    month,
+    dayOfMonth,
+    yearMonth: iso.slice(0, 7),
+    epochDay: Math.floor(date.getTime() / 86_400_000),
+  };
 }
 
 /**
- * Computes the list of day strings (YYYY-MM-DD) from a SchedulingPeriod.
+ * Computes the list of {@link SchedulingDay} values from a {@link SchedulingPeriod}.
  *
  * Generates all days between start and end (inclusive), applying optional
  * dayOfWeek and dates filters. Filters compose: a day must pass all
  * specified filters to be included.
  *
  * @param period - The scheduling period specification
- * @returns Array of day strings in YYYY-MM-DD format, sorted chronologically
+ * @returns Array of scheduling days, sorted chronologically
  *
  * @example All days in range
  * ```typescript
  * const days = resolveDaysFromPeriod({
  *   dateRange: { start: '2025-02-03', end: '2025-02-05' },
  * });
- * // Returns: ['2025-02-03', '2025-02-04', '2025-02-05']
+ * // Returns days for 2025-02-03, 2025-02-04, 2025-02-05
  * ```
  *
  * @example Day-of-week filter
@@ -53,7 +49,7 @@ export function toDayOfWeekUTC(date: Date): DayOfWeek {
  *   dateRange: { start: '2025-02-03', end: '2025-02-09' },
  *   dayOfWeek: ['wednesday', 'friday'],
  * });
- * // Returns: ['2025-02-05', '2025-02-07']
+ * // Returns days for 2025-02-05, 2025-02-07
  * ```
  *
  * @example Specific dates filter
@@ -62,31 +58,36 @@ export function toDayOfWeekUTC(date: Date): DayOfWeek {
  *   dateRange: { start: '2025-02-03', end: '2025-02-10' },
  *   dates: ['2025-02-05', '2025-02-07'],
  * });
- * // Returns: ['2025-02-05', '2025-02-07']
+ * // Returns days for 2025-02-05, 2025-02-07
  * ```
  */
-export function resolveDaysFromPeriod(period: SchedulingPeriod): string[] {
+export function resolveDaysFromPeriod(period: SchedulingPeriod): SchedulingDay[] {
   const { dateRange, dayOfWeek, dates } = period;
-  const allowedDays = dayOfWeek ? new Set(dayOfWeek) : null;
-  const allowedDates = dates ? new Set(dates) : null;
+  const allowedDays: Set<DayOfWeek> | null = dayOfWeek ? new Set(dayOfWeek) : null;
+  const allowedDates: Set<string> | null = dates ? new Set(dates) : null;
 
   const startDate = new Date(`${dateRange.start}T00:00:00Z`);
   const endDate = new Date(`${dateRange.end}T00:00:00Z`);
-  const result: string[] = [];
+  const result: SchedulingDay[] = [];
 
-  const current = new Date(startDate);
-  while (current <= endDate) {
+  for (
+    let currentTime = startDate.getTime(), endTime = endDate.getTime();
+    currentTime <= endTime;
+    currentTime += 24 * 60 * 60 * 1000
+  ) {
+    const current = new Date(currentTime);
     const year = current.getUTCFullYear();
     const month = (current.getUTCMonth() + 1).toString().padStart(2, "0");
-    const day = current.getUTCDate().toString().padStart(2, "0");
-    const iso = `${year}-${month}-${day}`;
-    const dow = toDayOfWeekUTC(current);
+    const d = current.getUTCDate().toString().padStart(2, "0");
+    const iso = `${year}-${month}-${d}` as DateString;
+    const day = schedulingDayFromDate(current, iso);
 
-    if ((!allowedDays || allowedDays.has(dow)) && (!allowedDates || allowedDates.has(iso))) {
-      result.push(iso);
+    if (
+      (!allowedDays || allowedDays.has(day.dayOfWeek)) &&
+      (!allowedDates || allowedDates.has(iso))
+    ) {
+      result.push(day);
     }
-
-    current.setUTCDate(current.getUTCDate() + 1);
   }
 
   return result;

package/src/index.ts

@@ -36,9 +36,9 @@
 // Time primitives
 // ============================================================================
 
-export type { TimeOfDay, DayOfWeek, SchedulingPeriod } from "./types.js";
+export type { DateString, TimeOfDay, DayOfWeek, SchedulingDay, SchedulingPeriod } from "./types.js";
 
-export { DayOfWeekSchema } from "./types.js";
+export { schedulingDay, DAY_OF_WEEK_INDEX, DayOfWeekSchema } from "./types.js";
 
 // ============================================================================
 // Solver client
@@ -51,13 +51,27 @@ export type {
   SolverRequest,
   SolverResponse,
   SolverStatus,
-  SoftConstraintViolation,
+  SolverMode,
+  SolverDiagnosticMode,
+  SolverObjectiveStage,
+  SolverStageResult,
+  SolverSoftConstraintViolation,
+  SolverHardConstraintConflict,
   FetcherLike,
 } from "./client.types.js";
 
 export { SOLVER_STATUS } from "./client.types.js";
 
-export { SolverRequestSchema, SolverResponseSchema, SolverStatusSchema } from "./client.schemas.js";
+export {
+  SolverModeSchema,
+  SolverDiagnosticModeSchema,
+  SolverObjectiveStageSchema,
+  SolverRequestSchema,
+  SolverResponseSchema,
+  SolverStageResultSchema,
+  SolverStatusSchema,
+  SolverHardConstraintConflictSchema,
+} from "./client.schemas.js";
 
 // ============================================================================
 // Model builder
@@ -65,14 +79,27 @@ export { SolverRequestSchema, SolverResponseSchema, SolverStatusSchema } from ".
 
 export { ModelBuilder } from "./cpsat/model-builder.js";
 
+export type { ModelBuilderConfig, CompilationResult } from "./cpsat/model-builder.js";
+export type { ModelSolveStrategy } from "./cpsat/types.js";
+
+export { compileRuleDescriptor, defineRuleDescriptor } from "./cpsat/rule-descriptor.js";
+
 export type {
-  ModelBuilderConfig,
-  CompilationResult,
-  CompilationRule,
-  RuleValidationContext,
+  CostValidationStrategy,
+  HardConstraintValidationStrategy,
+  ObjectiveValidationStrategy,
+  ReportHardConstraintValidationStrategy,
+  ReportSoftConstraintValidationStrategy,
+  RuleDescriptor,
+  RuleCompileContext,
+  RuleArtifact,
+  SkipValidationStrategy,
+  SoftConstraintValidationStrategy,
+  CompiledRule,
+  ValidationSkipCategory,
   CostEntry,
   CostContribution,
-} from "./cpsat/model-builder.js";
+} from "./cpsat/rule-descriptor.js";
 
 // ============================================================================
 // Solver response parsing
@@ -94,10 +121,19 @@ export type { CostBreakdown, MemberCostDetail, CostCalculationConfig } from "./c
 // Rules (registry types)
 // ============================================================================
 
+export {
+  assertValidCpsatRuleRegistry,
+  builtInCpsatRuleRegistry,
+  createCpsatRuleRegistry,
+} from "./cpsat/rules/registry.js";
+
 export type {
+  BuiltInCpsatRuleConfigRegistry,
+  BuiltInCpsatRuleRegistry,
+  CpsatRuleConfigByName,
   CpsatRuleConfigEntry,
-  CpsatRuleFactories,
-  CreateCpsatRuleFunction,
+  CpsatRuleConfigEntryFor,
+  CpsatRuleRegistry,
 } from "./cpsat/rules/rules.types.js";
 
 export type { RecurringPeriod } from "./cpsat/rules/scope.types.js";
@@ -150,6 +186,7 @@ export { summarizeValidation } from "./cpsat/validation-reporter.js";
 
 export {
   schedule,
+  scheduleWithRuleRegistry,
   partialSchedule,
   Schedule,
   t,
@@ -162,16 +199,24 @@ export {
   minHoursPerWeek,
   maxDaysPerWeek,
   minDaysPerWeek,
+  targetDaysPerWeek,
   maxShiftsPerDay,
+  maxConcurrentAssignments,
+  targetPeakConcurrentAssignments,
   maxConsecutiveDays,
   minConsecutiveDays,
   minRestBetweenShifts,
   mustAssign,
-  preference,
+  preferAssignment,
+  avoidAssignment,
+  preferRole,
   preferLocation,
   timeOff,
   assignTogether,
+  maxDaysOfWeekPerPeriod,
+  minDaysOfWeekPerPeriod,
   defineRule,
+  defineRuleFor,
   minimizeCost,
   dayMultiplier,
   daySurcharge,
@@ -192,12 +237,19 @@ export type {
   RuleEntry,
   RuleResolveContext,
   RuleOptions,
+  ScheduleRuleEntry,
   EntityOnlyRuleOptions,
+  TargetDaysPerWeekOptions,
   TimeOffOptions,
   AssignTogetherOptions,
+  MaxConcurrentAssignmentsOptions,
+  TargetPeakConcurrentAssignmentsOptions,
+  DaysOfWeekPerPeriodOptions,
   CostRuleOptions,
   ScheduleConfig,
+  ScheduleWithRuleRegistryConfig,
   SolveResult,
   SolveStatus,
+  SolveStrategy,
   SolveOptions,
 } from "./schedule/index.js";

package/src/schedule/cost.ts

@@ -1,6 +1,21 @@
 /**
  * Cost optimization rules: minimize labor cost with modifiers.
  *
+ *
+ * @example
+ * ```typescript
+ * rules: [
+ *   minimizeCost(),
+ *   dayMultiplier(1.5, { dayOfWeek: weekend }),
+ *   overtimeMultiplier({ after: 40, factor: 1.5 }),
+ *   dailyOvertimeSurcharge({ after: 8, amount: 500 }),
+ *   tieredOvertimeMultiplier([
+ *     { after: 40, factor: 1.5 },
+ *     { after: 48, factor: 2.0 },
+ *   ]),
+ * ]
+ * ```
+ *
  * @module
  */
 
@@ -39,7 +54,10 @@ export interface CostRuleOptions {
 // Cost Rules
 // ============================================================================
 
-function makeCostRule(rule: string, fields: Record<string, unknown>): RuleEntry {
+function makeCostRule<const Name extends string, const Fields extends object>(
+  rule: Name,
+  fields: Fields,
+): RuleEntry<Name, Omit<Fields, "_type" | "_rule">> {
   return defineRule(rule, fields);
 }
 
@@ -64,14 +82,9 @@ function makeCostRule(rule: string, fields: Record<string, unknown>): RuleEntry
  * - `dailyOvertimeSurcharge({ after, amount }, opts?)` - daily overtime surcharge
  * - `tieredOvertimeMultiplier(tiers, opts?)` - multiple overtime thresholds
  *
- * @example
- * ```ts
- * minimizeCost()
- * ```
- *
  * @category Cost Optimization
  */
-export function minimizeCost(opts?: CostRuleOptions): RuleEntry {
+export function minimizeCost(opts?: CostRuleOptions): RuleEntry<"minimize-cost", CostRuleOptions> {
   return makeCostRule("minimize-cost", { ...opts });
 }
 
@@ -83,13 +96,11 @@ export function minimizeCost(opts?: CostRuleOptions): RuleEntry {
  * this rule adds only the extra portion above 1x.
  *
  * @category Cost Optimization
- *
- * @example Weekend multiplier
- * ```typescript
- * dayMultiplier(1.5, { dayOfWeek: weekend })
- * ```
  */
-export function dayMultiplier(factor: number, opts?: CostRuleOptions): RuleEntry {
+export function dayMultiplier(
+  factor: number,
+  opts?: CostRuleOptions,
+): RuleEntry<"day-cost-multiplier", { factor: number } & CostRuleOptions> {
   return makeCostRule("day-cost-multiplier", { factor, ...opts });
 }
 
@@ -100,13 +111,11 @@ export function dayMultiplier(factor: number, opts?: CostRuleOptions): RuleEntry
  * The surcharge is independent of the member's base rate.
  *
  * @category Cost Optimization
- *
- * @example Weekend surcharge
- * ```typescript
- * daySurcharge(500, { dayOfWeek: weekend })
- * ```
  */
-export function daySurcharge(amountPerHour: number, opts?: CostRuleOptions): RuleEntry {
+export function daySurcharge(
+  amountPerHour: number,
+  opts?: CostRuleOptions,
+): RuleEntry<"day-cost-surcharge", { amountPerHour: number } & CostRuleOptions> {
   return makeCostRule("day-cost-surcharge", { amountPerHour, ...opts });
 }
 
@@ -122,17 +131,15 @@ export function daySurcharge(amountPerHour: number, opts?: CostRuleOptions): Rul
  * @param opts - Entity and time scoping
  *
  * @category Cost Optimization
- *
- * @example Night differential
- * ```typescript
- * timeSurcharge(200, { from: t(22), until: t(6) })
- * ```
  */
 export function timeSurcharge(
   amountPerHour: number,
   window: { from: TimeOfDay; until: TimeOfDay },
   opts?: CostRuleOptions,
-): RuleEntry {
+): RuleEntry<
+  "time-cost-surcharge",
+  { amountPerHour: number; window: { from: TimeOfDay; until: TimeOfDay } } & CostRuleOptions
+> {
   return makeCostRule("time-cost-surcharge", { amountPerHour, window, ...opts });
 }
 
@@ -144,15 +151,10 @@ export function timeSurcharge(
  * counted by {@link minimizeCost}).
  *
  * @category Cost Optimization
- *
- * @example
- * ```typescript
- * overtimeMultiplier({ after: 40, factor: 1.5 })
- * ```
  */
 export function overtimeMultiplier(
   opts: { after: number; factor: number } & CostRuleOptions,
-): RuleEntry {
+): RuleEntry<"overtime-weekly-multiplier", { after: number; factor: number } & CostRuleOptions> {
   return makeCostRule("overtime-weekly-multiplier", { ...opts });
 }
 
@@ -163,15 +165,10 @@ export function overtimeMultiplier(
  * The surcharge is independent of the member's base rate.
  *
  * @category Cost Optimization
- *
- * @example
- * ```typescript
- * overtimeSurcharge({ after: 40, amount: 1000 })
- * ```
  */
 export function overtimeSurcharge(
   opts: { after: number; amount: number } & CostRuleOptions,
-): RuleEntry {
+): RuleEntry<"overtime-weekly-surcharge", { after: number; amount: number } & CostRuleOptions> {
   return makeCostRule("overtime-weekly-surcharge", { ...opts });
 }
 
@@ -183,15 +180,10 @@ export function overtimeSurcharge(
  * counted by {@link minimizeCost}).
  *
  * @category Cost Optimization
- *
- * @example
- * ```typescript
- * dailyOvertimeMultiplier({ after: 8, factor: 1.5 })
- * ```
  */
 export function dailyOvertimeMultiplier(
   opts: { after: number; factor: number } & CostRuleOptions,
-): RuleEntry {
+): RuleEntry<"overtime-daily-multiplier", { after: number; factor: number } & CostRuleOptions> {
   return makeCostRule("overtime-daily-multiplier", { ...opts });
 }
 
@@ -202,15 +194,10 @@ export function dailyOvertimeMultiplier(
  * The surcharge is independent of the member's base rate.
  *
  * @category Cost Optimization
- *
- * @example
- * ```typescript
- * dailyOvertimeSurcharge({ after: 8, amount: 500 })
- * ```
  */
 export function dailyOvertimeSurcharge(
   opts: { after: number; amount: number } & CostRuleOptions,
-): RuleEntry {
+): RuleEntry<"overtime-daily-surcharge", { after: number; amount: number } & CostRuleOptions> {
   return makeCostRule("overtime-daily-surcharge", { ...opts });
 }
 
@@ -222,21 +209,13 @@ export function dailyOvertimeSurcharge(
  * Tiers must be sorted by threshold ascending.
  *
  * @category Cost Optimization
- *
- * @example
- * ```typescript
- * // Hours 0-40: base rate
- * // Hours 40-48: 1.5x
- * // Hours 48+: 2.0x
- * tieredOvertimeMultiplier([
- *   { after: 40, factor: 1.5 },
- *   { after: 48, factor: 2.0 },
- * ])
- * ```
  */
 export function tieredOvertimeMultiplier(
   tiers: [OvertimeTier, ...OvertimeTier[]],
   opts?: CostRuleOptions,
-): RuleEntry {
+): RuleEntry<
+  "overtime-tiered-multiplier",
+  { tiers: [OvertimeTier, ...OvertimeTier[]] } & CostRuleOptions
+> {
   return makeCostRule("overtime-tiered-multiplier", { tiers, ...opts });
 }

package/src/schedule/coverage.ts

@@ -1,10 +1,33 @@
 /**
- * Coverage definitions: staffing requirements per semantic time period.
+ * Coverage definitions: lower-bound staffing requirements per semantic time period.
+ *
+ * Coverage answers "what floor should apply throughout this scoped time, with
+ * the chosen priority?". It attaches sustained lower bounds to semantic times,
+ * whether those periods are
+ * explicit in the requirements or inferred to separate distinct business
+ * requirements. Coverage does not express caps, targets, fairness, or other
+ * assignment-shaping logic. Use rules for those concerns.
+ *
+ * @example
+ * ```typescript
+ * coverage: [
+ *   cover("lunch", "waiter", 2, { dayOfWeek: weekdays }),
+ *   cover("lunch", "waiter", 3, { dayOfWeek: weekend }),
+ *   cover("dinner", ["manager", "supervisor"], 1),
+ *   cover("opening", "keyholder", 1),
+ *
+ *   // Variant form: different counts by day
+ *   cover("peak_hours", "agent",
+ *     { count: 4 },
+ *     { count: 2, dates: ["2025-12-24"] },
+ *   ),
+ * ]
+ * ```
  *
  * @module
  */
 
-import type { DayOfWeek } from "../types.js";
+import type { DateString, DayOfWeek } from "../types.js";
 import type { CoverageVariant } from "../cpsat/semantic-time.js";
 import type { Priority } from "../cpsat/types.js";
 
@@ -16,7 +39,15 @@ export type { CoverageVariant } from "../cpsat/semantic-time.js";
  * @remarks
  * Day/date scoping controls which days this coverage entry applies to.
  * An entry without `dayOfWeek` or `dates` applies every day in the
- * scheduling period.
+ * scheduling period. Scope answers where the floor applies; it does not change
+ * the meaning of coverage itself. `priority` controls how hard the coverage floor is.
+ * Use it to distinguish language like "must keep 5 staffed on Saturdays"
+ * from "ideally keep 5 staffed on Mondays too" without changing the
+ * underlying coverage shape. `skillIds` is a hard filter, not a preference.
+ * Use it only when the required minimum truly needs those skills throughout
+ * the window. If a role or skill mix is preferred rather than required, model
+ * that with rules such as {@link preferAssignment} instead of skill-filtered
+ * coverage.
  *
  * @category Coverage
  */
@@ -26,7 +57,7 @@ export interface CoverageOptions {
   /** Restrict to specific days of the week. */
   dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]];
   /** Restrict to specific dates (YYYY-MM-DD). */
-  dates?: string[];
+  dates?: DateString[];
   /** Defaults to `"MANDATORY"`. */
   priority?: Priority;
 }
@@ -53,36 +84,34 @@ export interface CoverageEntry<T extends string = string, R extends string = str
  * Defines a staffing requirement for a semantic time period.
  *
  * @remarks
- * Entries for the same time and role **stack additively**.
- * For weekday vs weekend staffing, use mutually exclusive `dayOfWeek`
- * on both entries.
+ * Coverage always defines a lower bound that applies throughout the scoped
+ * semantic time, with strength controlled by `priority`. If the requirements
+ * also state an upper bound or productive
+ * cap, model that separately in `rules`, for example with
+ * {@link maxConcurrentAssignments}.
+ *
+ * Scope answers where the floor applies. Priority answers how strictly the
+ * solver should preserve that floor when trade-offs are necessary.
+ *
+ * Attach coverage to the narrowest semantic time that actually carries that
+ * minimum. Avoid layering a broad parent coverage window on top of narrower
+ * windows unless the same lower bound truly applies throughout the full span.
+ * If the requirements talk about hitting full occupancy at the busy point,
+ * prefer {@link targetPeakConcurrentAssignments} over turning that into a
+ * whole-window minimum. Do not infer a synthetic "peak" semantic time just to attach
+ * `cover(..., 5)` unless the requirements really define a sustained window
+ * that needs that minimum throughout.
+ *
+ * Overlapping entries for the same time and role produce independent
+ * constraints; the solver enforces the **max** count, not the sum.
+ * An unscoped entry acts as a floor that scoped entries cannot reduce.
+ * Use mutually exclusive scopes when different days need different coverage.
  *
  * @param timeName - Name of a declared semantic time
  * @param target - Role name (string), array of role names (OR logic), or skill name
  * @param count - Number of people needed
  * @param opts - Options: `skillIds` (AND filter), `dayOfWeek`, `dates`, `priority`
  *
- * @example
- * ```typescript
- * coverage: [
- *   // 2 waiters during lunch
- *   cover("lunch", "waiter", 2),
- *
- *   // 1 manager OR supervisor during dinner
- *   cover("dinner", ["manager", "supervisor"], 1),
- *
- *   // 1 person with keyholder skill at opening
- *   cover("opening", "keyholder", 1),
- *
- *   // 1 senior waiter (role + skill AND)
- *   cover("lunch", "waiter", 1, { skillIds: ["senior"] }),
- *
- *   // Different counts by day (mutually exclusive dayOfWeek!)
- *   cover("lunch", "waiter", 2, { dayOfWeek: weekdays }),
- *   cover("lunch", "waiter", 3, { dayOfWeek: weekend }),
- * ]
- * ```
- *
  * @category Coverage
  */
 export function cover<T extends string, const R extends string>(