dabke 0.83.0 → 0.84.0

package/dist/schedule/shift-patterns.js

@@ -9,23 +9,6 @@
  * @remarks
  * Each pattern repeats daily unless filtered by `dayOfWeek`.
  *
- * @example
- * ```typescript
- * shiftPatterns: [
- *   shift("morning", t(11, 30), t(15)),
- *   shift("evening", t(17), t(22)),
- *
- *   // Role-restricted shift
- *   shift("kitchen", t(6), t(14), { roleIds: ["chef", "prep_cook"] }),
- *
- *   // Day-restricted shift
- *   shift("saturday_short", t(9), t(14), { dayOfWeek: ["saturday"] }),
- *
- *   // Location-specific shift
- *   shift("terrace_lunch", t(12), t(16), { locationId: "terrace" }),
- * ]
- * ```
- *
  * @category Shift Patterns
  */
 export function shift(id, startTime, endTime, opts) {

package/dist/schedule/shift-patterns.js.map

@@ -1 +1 @@
-{"version":3,"file":"shift-patterns.js","sourceRoot":"","sources":["../../src/schedule/shift-patterns.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,KAAK,CACnB,EAAU,EACV,SAAoB,EACpB,OAAkB,EAClB,IAAiE;IAEjE,MAAM,OAAO,GAAiB,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IACzD,IAAI,IAAI,EAAE,OAAO;QAAE,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAClD,IAAI,IAAI,EAAE,SAAS;QAAE,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IACxD,IAAI,IAAI,EAAE,UAAU;QAAE,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;IAC3D,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"shift-patterns.js","sourceRoot":"","sources":["../../src/schedule/shift-patterns.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;;;;;;GAOG;AACH,MAAM,UAAU,KAAK,CACnB,EAAU,EACV,SAAoB,EACpB,OAAkB,EAClB,IAAiE;IAEjE,MAAM,OAAO,GAAiB,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IACzD,IAAI,IAAI,EAAE,OAAO;QAAE,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAClD,IAAI,IAAI,EAAE,SAAS;QAAE,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IACxD,IAAI,IAAI,EAAE,UAAU;QAAE,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;IAC3D,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/schedule/time-periods.d.ts

@@ -1,5 +1,26 @@
 /**
- * Time period primitives: day constants and time constructors.
+ * Time period primitives: day constants and semantic time constructors.
+ *
+ * Semantic times are business-relevant scheduling periods used to group
+ * coverage and rules. Some come directly from the requirements, for example opening,
+ * lunch, or closing. Others are inferred from the requirements so different
+ * parts of a day can carry different coverage floors or constraints.
+ *
+ * An unscoped `time(...)` entry applies every day in the scheduling period.
+ * Names are descriptive only, they do not scope a time to a day. If a time is
+ * day-specific, add `dayOfWeek` or `dates` explicitly.
+ *
+ * @example
+ * ```typescript
+ * times: {
+ *   lunch: time({ startTime: t(12), endTime: t(15) }),
+ *   dinner: time(
+ *     { startTime: t(17), endTime: t(21) },
+ *     { startTime: t(18), endTime: t(22), dayOfWeek: weekend },
+ *   ),
+ *   thursday_open: time({ startTime: t(10), endTime: t(11), dayOfWeek: ["thursday"] }),
+ * }
+ * ```
  *
  * @module
  */
@@ -11,16 +32,6 @@ import type { SemanticTimeVariant, SemanticTimeEntry } from "../cpsat/semantic-t
  * @param hours - Hour component (0-23)
  * @param minutes - Minute component (0-59)
  *
- * @example Hours only
- * ```ts
- * t(9)   // { hours: 9, minutes: 0 }
- * ```
- *
- * @example Hours and minutes
- * ```ts
- * t(17, 30)  // { hours: 17, minutes: 30 }
- * ```
- *
  * @category Time Periods
  */
 export declare function t(hours: number, minutes?: number): TimeOfDay;
@@ -41,24 +52,23 @@ export declare const weekend: readonly ["saturday", "sunday"];
  *
  * @remarks
  * Each entry has `startTime`/`endTime` and optional `dayOfWeek` or `dates`
- * scoping. Entries without scoping are the default.
- *
- * @example
- * ```typescript
- * times: {
- *   // Simple: same times every day
- *   lunch: time({ startTime: t(12), endTime: t(15) }),
+ * scoping. Entries without scoping are the default and apply every day in the
+ * scheduling period. The surrounding object key is only a name, it does not
+ * add scope. For example, `thursday_open: time({ startTime: ..., endTime: ... })`
+ * still applies on Monday, Tuesday, and every other scheduling day unless you
+ * add `dayOfWeek: ["thursday"]`.
  *
- *   // Variants: different times on weekends
- *   dinner: time(
- *     { startTime: t(17), endTime: t(21) },
- *     { startTime: t(18), endTime: t(22), dayOfWeek: weekend },
- *   ),
+ * Use semantic times to represent business periods, not shift patterns. Some
+ * periods have explicit boundaries in the requirements. Others are inferred so
+ * related coverage and rules can attach to the correct part of the day. Choose
+ * the simplest set of semantic times that preserves the business distinctions
+ * you need.
  *
- *   // Point-in-time window (keyholder at opening)
- *   opening: time({ startTime: t(8, 30), endTime: t(9) }),
- * }
- * ```
+ * Avoid adding a broad all-day semantic time when narrower windows already
+ * describe the day's distinct requirements. If opening, core trading, and
+ * closing each need different coverage, model those windows directly instead
+ * of layering an extra whole-day period on top unless the lower bound truly
+ * applies for the full span.
  *
  * @privateRemarks
  * Resolution precedence: `dates` > `dayOfWeek` > default.

package/dist/schedule/time-periods.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"time-periods.d.ts","sourceRoot":"","sources":["../../src/schedule/time-periods.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAa,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAEV,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,SAAS,CAEvD;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,mEAMoC,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,OAAO,iCAGnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,IAAI,CAClB,GAAG,OAAO,EAAE,CAAC,mBAAmB,EAAE,GAAG,mBAAmB,EAAE,CAAC,GAC1D,iBAAiB,CAoBnB"}
+{"version":3,"file":"time-periods.d.ts","sourceRoot":"","sources":["../../src/schedule/time-periods.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAa,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAEV,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;GAOG;AACH,wBAAgB,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,SAAS,CAEvD;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,mEAMoC,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,OAAO,iCAGnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,IAAI,CAClB,GAAG,OAAO,EAAE,CAAC,mBAAmB,EAAE,GAAG,mBAAmB,EAAE,CAAC,GAC1D,iBAAiB,CAoBnB"}

package/dist/schedule/time-periods.js

@@ -1,5 +1,26 @@
 /**
- * Time period primitives: day constants and time constructors.
+ * Time period primitives: day constants and semantic time constructors.
+ *
+ * Semantic times are business-relevant scheduling periods used to group
+ * coverage and rules. Some come directly from the requirements, for example opening,
+ * lunch, or closing. Others are inferred from the requirements so different
+ * parts of a day can carry different coverage floors or constraints.
+ *
+ * An unscoped `time(...)` entry applies every day in the scheduling period.
+ * Names are descriptive only, they do not scope a time to a day. If a time is
+ * day-specific, add `dayOfWeek` or `dates` explicitly.
+ *
+ * @example
+ * ```typescript
+ * times: {
+ *   lunch: time({ startTime: t(12), endTime: t(15) }),
+ *   dinner: time(
+ *     { startTime: t(17), endTime: t(21) },
+ *     { startTime: t(18), endTime: t(22), dayOfWeek: weekend },
+ *   ),
+ *   thursday_open: time({ startTime: t(10), endTime: t(11), dayOfWeek: ["thursday"] }),
+ * }
+ * ```
  *
  * @module
  */
@@ -9,16 +30,6 @@
  * @param hours - Hour component (0-23)
  * @param minutes - Minute component (0-59)
  *
- * @example Hours only
- * ```ts
- * t(9)   // { hours: 9, minutes: 0 }
- * ```
- *
- * @example Hours and minutes
- * ```ts
- * t(17, 30)  // { hours: 17, minutes: 30 }
- * ```
- *
  * @category Time Periods
  */
 export function t(hours, minutes = 0) {
@@ -47,24 +58,23 @@ export const weekend = ["saturday", "sunday"];
  *
  * @remarks
  * Each entry has `startTime`/`endTime` and optional `dayOfWeek` or `dates`
- * scoping. Entries without scoping are the default.
- *
- * @example
- * ```typescript
- * times: {
- *   // Simple: same times every day
- *   lunch: time({ startTime: t(12), endTime: t(15) }),
+ * scoping. Entries without scoping are the default and apply every day in the
+ * scheduling period. The surrounding object key is only a name, it does not
+ * add scope. For example, `thursday_open: time({ startTime: ..., endTime: ... })`
+ * still applies on Monday, Tuesday, and every other scheduling day unless you
+ * add `dayOfWeek: ["thursday"]`.
  *
- *   // Variants: different times on weekends
- *   dinner: time(
- *     { startTime: t(17), endTime: t(21) },
- *     { startTime: t(18), endTime: t(22), dayOfWeek: weekend },
- *   ),
+ * Use semantic times to represent business periods, not shift patterns. Some
+ * periods have explicit boundaries in the requirements. Others are inferred so
+ * related coverage and rules can attach to the correct part of the day. Choose
+ * the simplest set of semantic times that preserves the business distinctions
+ * you need.
  *
- *   // Point-in-time window (keyholder at opening)
- *   opening: time({ startTime: t(8, 30), endTime: t(9) }),
- * }
- * ```
+ * Avoid adding a broad all-day semantic time when narrower windows already
+ * describe the day's distinct requirements. If opening, core trading, and
+ * closing each need different coverage, model those windows directly instead
+ * of layering an extra whole-day period on top unless the lower bound truly
+ * applies for the full span.
  *
  * @privateRemarks
  * Resolution precedence: `dates` > `dayOfWeek` > default.

package/dist/schedule/time-periods.js.map

@@ -1 +1 @@
-{"version":3,"file":"time-periods.js","sourceRoot":"","sources":["../../src/schedule/time-periods.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,CAAC,CAAC,KAAa,EAAE,OAAO,GAAG,CAAC;IAC1C,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,QAAQ;IACR,SAAS;IACT,WAAW;IACX,UAAU;IACV,QAAQ;CAC+C,CAAC;AAE1D;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,UAAU,EAAE,QAAQ,CAG3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,IAAI,CAClB,GAAG,OAAwD;IAE3D,4DAA4D;IAC5D,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACjE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,yEAAyE;YACvE,SAAS,QAAQ,CAAC,MAAM,mBAAmB,CAC9C,CAAC;IACJ,CAAC;IAED,uDAAuD;IACvD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;QACvE,OAAO;YACL,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;YAC/B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO;SACF,CAAC;IAC9B,CAAC;IAED,2EAA2E;IAC3E,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"time-periods.js","sourceRoot":"","sources":["../../src/schedule/time-periods.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AASH;;;;;;;GAOG;AACH,MAAM,UAAU,CAAC,CAAC,KAAa,EAAE,OAAO,GAAG,CAAC;IAC1C,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,QAAQ;IACR,SAAS;IACT,WAAW;IACX,UAAU;IACV,QAAQ;CAC+C,CAAC;AAE1D;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,UAAU,EAAE,QAAQ,CAG3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,IAAI,CAClB,GAAG,OAAwD;IAE3D,4DAA4D;IAC5D,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACjE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,yEAAyE;YACvE,SAAS,QAAQ,CAAC,MAAM,mBAAmB,CAC9C,CAAC;IACJ,CAAC;IAED,uDAAuD;IACvD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;QACvE,OAAO;YACL,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;YAC/B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO;SACF,CAAC;IAC9B,CAAC;IAED,2EAA2E;IAC3E,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;AAC1D,CAAC"}

package/dist/types.d.ts

@@ -24,6 +24,70 @@ export interface TimeOfDay {
     hours: number;
     minutes: number;
 }
+/**
+ * A date string in ISO 8601 calendar date format (YYYY-MM-DD).
+ *
+ * Template literal type that rejects arbitrary strings at compile time.
+ * Use this wherever a raw date string is expected in scheduling APIs.
+ *
+ * @category Supporting Types
+ */
+export type DateString = `${number}-${number}-${number}`;
+/**
+ * Checks whether a string matches the {@link DateString} YYYY-MM-DD format.
+ *
+ * @remarks
+ * This validates string shape only. It does not guarantee that the value is a
+ * semantically valid calendar date.
+ *
+ * @param value - String to test
+ *
+ * @category Supporting Types
+ */
+export declare function isDateString(value: string): value is DateString;
+/**
+ * A calendar day with pre-computed date components.
+ *
+ * Constructed once from a YYYY-MM-DD string via {@link schedulingDay}, then
+ * passed by reference. Replaces raw `string` day representations throughout
+ * the solver so downstream code never needs to parse dates.
+ *
+ * @category Supporting Types
+ */
+export interface SchedulingDay {
+    /** The canonical YYYY-MM-DD string. */
+    readonly iso: DateString;
+    /** Day of week (monday, tuesday, ...). */
+    readonly dayOfWeek: DayOfWeek;
+    /** 1-indexed month (1 = January, 12 = December). */
+    readonly month: number;
+    /** 1-indexed day of the month. */
+    readonly dayOfMonth: number;
+    /** Year-month key for grouping ("YYYY-MM"). */
+    readonly yearMonth: string;
+    /** Integer days since Unix epoch (1970-01-01 = 0). Useful for date arithmetic. */
+    readonly epochDay: number;
+}
+export declare const DAY_NAMES: readonly DayOfWeek[];
+declare const DAY_OF_WEEK_INDEX: Record<DayOfWeek, number>;
+/**
+ * Creates a {@link SchedulingDay} from a YYYY-MM-DD string.
+ *
+ * Parses the date once in UTC and pre-computes all fields so that no
+ * downstream code ever needs to construct a `Date` object.
+ *
+ * @param iso - Date string in YYYY-MM-DD format
+ *
+ * @category Supporting Types
+ */
+export declare function schedulingDay(iso: DateString): SchedulingDay;
+/**
+ * Maps {@link DayOfWeek} names to JavaScript `Date.getUTCDay()` indices
+ * (0 = Sunday, 6 = Saturday).
+ *
+ * @category Supporting Types
+ */
+export { DAY_OF_WEEK_INDEX };
 /**
  * Defines a scheduling period as a date range with optional filters.
  *
@@ -62,8 +126,8 @@ export interface SchedulingPeriod {
      * Dates should be in YYYY-MM-DD format.
      */
     dateRange: {
-        start: string;
-        end: string;
+        start: DateString;
+        end: DateString;
     };
     /**
      * Include only these days of the week.
@@ -74,6 +138,6 @@ export interface SchedulingPeriod {
      * Include only these specific dates (YYYY-MM-DD) within the range.
      * If omitted, all dates in the range are included (subject to dayOfWeek filter).
      */
-    dates?: string[];
+    dates?: DateString[];
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAMzB;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,UAAU,GACV,QAAQ,GACR,UAAU,GACV,QAAQ,CAAC;AAEb;;;GAGG;AACH,eAAO,MAAM,eAAe,uMAQ1B,CAAC;AAEH;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAMzB;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,UAAU,GACV,QAAQ,GACR,UAAU,GACV,QAAQ,CAAC;AAEb;;;GAGG;AACH,eAAO,MAAM,eAAe,uMAQ1B,CAAC;AAEH;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,GAAG,MAAM,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC;AAIzD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,SAAS,EAAE,SAAS,SAAS,EAQzC,CAAC;AAEF,QAAA,MAAM,iBAAiB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAQhD,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG,aAAa,CAa5D;AAED;;;;;GAKG;AACH,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAM7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,EAAE;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,GAAG,EAAE,UAAU,CAAA;KAAE,CAAC;IAClD;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;CACtB"}

package/dist/types.js

@@ -17,4 +17,68 @@ export const DayOfWeekSchema = z.union([
     z.literal("saturday"),
     z.literal("sunday"),
 ]);
+const DATE_STRING_RE = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * Checks whether a string matches the {@link DateString} YYYY-MM-DD format.
+ *
+ * @remarks
+ * This validates string shape only. It does not guarantee that the value is a
+ * semantically valid calendar date.
+ *
+ * @param value - String to test
+ *
+ * @category Supporting Types
+ */
+export function isDateString(value) {
+    return DATE_STRING_RE.test(value);
+}
+export const DAY_NAMES = [
+    "sunday",
+    "monday",
+    "tuesday",
+    "wednesday",
+    "thursday",
+    "friday",
+    "saturday",
+];
+const DAY_OF_WEEK_INDEX = {
+    sunday: 0,
+    monday: 1,
+    tuesday: 2,
+    wednesday: 3,
+    thursday: 4,
+    friday: 5,
+    saturday: 6,
+};
+/**
+ * Creates a {@link SchedulingDay} from a YYYY-MM-DD string.
+ *
+ * Parses the date once in UTC and pre-computes all fields so that no
+ * downstream code ever needs to construct a `Date` object.
+ *
+ * @param iso - Date string in YYYY-MM-DD format
+ *
+ * @category Supporting Types
+ */
+export function schedulingDay(iso) {
+    const date = new Date(`${iso}T00:00:00Z`);
+    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),
+    };
+}
+/**
+ * Maps {@link DayOfWeek} names to JavaScript `Date.getUTCDay()` indices
+ * (0 = Sunday, 6 = Saturday).
+ *
+ * @category Supporting Types
+ */
+export { DAY_OF_WEEK_INDEX };
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAoBzB;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC;IACrC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACnB,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IACpB,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;IACtB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IACrB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACnB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IACrB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;CACpB,CAAC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAoBzB;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC;IACrC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACnB,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IACpB,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;IACtB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IACrB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACnB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IACrB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;CACpB,CAAC,CAAC;AA0BH,MAAM,cAAc,GAAG,qBAAqB,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACpC,CAAC;AA8BD,MAAM,CAAC,MAAM,SAAS,GAAyB;IAC7C,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,WAAW;IACX,UAAU;IACV,QAAQ;IACR,UAAU;CACX,CAAC;AAEF,MAAM,iBAAiB,GAA8B;IACnD,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,CAAC;IACT,OAAO,EAAE,CAAC;IACV,SAAS,EAAE,CAAC;IACZ,QAAQ,EAAE,CAAC;IACX,MAAM,EAAE,CAAC;IACT,QAAQ,EAAE,CAAC;CACZ,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,GAAe;IAC3C,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,GAAG,GAAG,YAAY,CAAC,CAAC;IAC1C,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,CAAE,CAAC;IAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IACrC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;IACrC,OAAO;QACL,GAAG;QACH,SAAS;QACT,KAAK;QACL,UAAU;QACV,SAAS,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;QAC1B,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,UAAU,CAAC;KAClD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dabke",
-  "version": "0.83.0",
+  "version": "0.84.0",
   "description": "Scheduling library powered by constraint programming (CP-SAT)",
   "keywords": [
     "constraint-programming",
@@ -52,18 +52,17 @@
     "test": "npm run typecheck && npm run test:unit",
     "test:unit": "vitest run --project=unit",
     "test:unit:watch": "vitest --watch --project=unit",
-    "test:integration": "[ -f .env ] && { set -a; source .env; set +a; } && vitest run --project=integration",
-    "test:integration:watch": "[ -f .env ] && { set -a; source .env; set +a; } && vitest --watch --project=integration",
-    "generate:reference": "tsx scripts/generate-reference.ts"
+    "test:integration": "vitest run --project=integration",
+    "test:integration:watch": "vitest --watch --project=integration"
   },
   "dependencies": {
-    "zod": "^4.3.6"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.0.0",
-    "commander": "^14.0.3",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "@types/node": "^25.9.1",
+    "commander": "^15.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
   },
   "engines": {
     "node": ">=20"

package/solver/src/solver/models.py

@@ -5,6 +5,11 @@ from typing import Literal
 from pydantic import BaseModel, Field, ConfigDict
 
 
+SolverMode = Literal["optimize", "satisfy"]
+SolverStatus = Literal["OPTIMAL", "FEASIBLE", "INFEASIBLE", "TIMEOUT", "ERROR"]
+DiagnosticMode = Literal["none", "hard"]
+
+
 class Variable(BaseModel):
     """Decision variable.
 
@@ -65,6 +70,7 @@ class Constraint(BaseModel):
     if_: str | None = Field(default=None, alias="if")
     then: str | None = None
     id: str | None = None
+    stage: str | None = None
 
 
 class Objective(BaseModel):
@@ -76,6 +82,12 @@ class Objective(BaseModel):
     terms: list[Term]
 
 
+class SolverObjectiveStage(Objective):
+    """A named objective stage for lexicographic solving."""
+
+    id: str
+
+
 class Options(BaseModel):
     """Solver tuning options."""
 
@@ -83,6 +95,7 @@ class Options(BaseModel):
 
     timeLimitSeconds: float = 60.0
     solutionLimit: int | None = None  # Only solutionLimit=1 is supported (stops after first feasible solution)
+    diagnostics: DiagnosticMode = "none"
 
 
 class SolverRequest(BaseModel):
@@ -93,11 +106,25 @@ class SolverRequest(BaseModel):
     variables: list[Variable]
     constraints: list[Constraint]
     objective: Objective | None = None
+    objectiveStages: list[SolverObjectiveStage] | None = None
+    mode: SolverMode | None = None
     options: Options | None = None
 
 
-class SoftConstraintViolation(BaseModel):
-    """A soft constraint violation in the solver output."""
+class SolverStageResult(BaseModel):
+    """Metadata for one objective stage solve."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    status: SolverStatus
+    objectiveValue: float | None = None
+    bestObjectiveBound: float | None = None
+    solveTimeMs: int
+
+
+class SolverSoftConstraintViolation(BaseModel):
+    """A raw solver-stage soft constraint violation."""
 
     model_config = ConfigDict(extra="forbid")
 
@@ -107,14 +134,24 @@ class SoftConstraintViolation(BaseModel):
     actualValue: int
 
 
+class SolverHardConstraintConflict(BaseModel):
+    """A hard constraint included in a sufficient infeasible constraint set."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    constraintId: str
+
+
 class SolverResponse(BaseModel):
     """Response payload produced by the solver service."""
 
     model_config = ConfigDict(extra="forbid")
 
-    status: Literal["OPTIMAL", "FEASIBLE", "INFEASIBLE", "TIMEOUT", "ERROR"]
+    status: SolverStatus
     values: dict[str, int] | None = None
     statistics: dict[str, int | float] | None = None
     error: str | None = None
     solutionInfo: str | None = None
-    softViolations: list[SoftConstraintViolation] | None = None
+    hardConstraintConflicts: list[SolverHardConstraintConflict] | None = None
+    softConstraintViolations: list[SolverSoftConstraintViolation] | None = None
+    stageResults: list[SolverStageResult] | None = None