dabke 0.82.0 → 0.83.0

package/dist/schedule/rules.js

@@ -0,0 +1,352 @@
+/**
+ * Scheduling rules: constraints, preferences, and time-off.
+ *
+ * @module
+ */
+/**
+ * Creates a rule entry for use in {@link ScheduleConfig.rules}.
+ *
+ * Built-in rules use the helpers (`maxHoursPerDay`, `timeOff`, etc.).
+ * Custom rules can use `defineRule` to create entries that plug into the
+ * same resolution and compilation pipeline.
+ *
+ * @param name - Rule name. Must match a key in the rule factory registry.
+ * @param fields - Rule-specific configuration fields.
+ * @param resolve - Optional custom resolver. When omitted, the default
+ *   resolution applies: `appliesTo` is mapped to `roleIds`/`skillIds`/`memberIds`,
+ *   `dates` is renamed to `specificDates`, and all other fields pass through.
+ */
+export function defineRule(name, fields, resolve) {
+    const { _type: _, _rule: __, ...safeFields } = fields;
+    const entry = { _type: "rule", _rule: name, ...safeFields };
+    if (resolve) {
+        Object.defineProperty(entry, "_resolve", { value: resolve, enumerable: false });
+    }
+    return entry;
+}
+function makeRule(rule, fields) {
+    return defineRule(rule, fields);
+}
+// ============================================================================
+// Constraint Rules
+// ============================================================================
+/**
+ * Limits hours per day.
+ *
+ * @example
+ * ```typescript
+ * maxHoursPerDay(10)
+ * maxHoursPerDay(4, { appliesTo: "student", dayOfWeek: weekdays })
+ * ```
+ *
+ * @category Rules
+ */
+export function maxHoursPerDay(hours, opts) {
+    return makeRule("max-hours-day", { hours, ...opts });
+}
+/**
+ * Limits hours per scheduling week.
+ *
+ * @example
+ * ```typescript
+ * maxHoursPerWeek(48)
+ * maxHoursPerWeek(20, { appliesTo: "student" })
+ * ```
+ *
+ * @category Rules
+ */
+export function maxHoursPerWeek(hours, opts) {
+    return makeRule("max-hours-week", { hours, ...opts });
+}
+/**
+ * Minimum hours when assigned on a day.
+ *
+ * @example
+ * ```typescript
+ * minHoursPerDay(4)
+ * ```
+ *
+ * @category Rules
+ */
+export function minHoursPerDay(hours, opts) {
+    return makeRule("min-hours-day", { hours, ...opts });
+}
+/**
+ * Minimum hours per scheduling week.
+ *
+ * @example
+ * ```typescript
+ * minHoursPerWeek(20, { priority: "HIGH" })
+ * ```
+ *
+ * @category Rules
+ */
+export function minHoursPerWeek(hours, opts) {
+    return makeRule("min-hours-week", { hours, ...opts });
+}
+/**
+ * Limits working days per scheduling week.
+ *
+ * @example
+ * ```typescript
+ * maxDaysPerWeek(5)
+ * maxDaysPerWeek(3, { appliesTo: "part-time" })
+ * ```
+ *
+ * @category Rules
+ */
+export function maxDaysPerWeek(days, opts) {
+    return makeRule("max-days-week", { days, ...opts });
+}
+/**
+ * Minimum working days per scheduling week.
+ *
+ * @example
+ * ```typescript
+ * minDaysPerWeek(3, { priority: "HIGH" })
+ * minDaysPerWeek(5, { appliesTo: "full-time" })
+ * ```
+ *
+ * @category Rules
+ */
+export function minDaysPerWeek(days, opts) {
+    return makeRule("min-days-week", { days, ...opts });
+}
+/**
+ * Maximum distinct shifts per day.
+ *
+ * @example
+ * ```typescript
+ * maxShiftsPerDay(1)
+ * maxShiftsPerDay(2, { appliesTo: "student", dayOfWeek: weekend })
+ * ```
+ *
+ * @category Rules
+ */
+export function maxShiftsPerDay(shifts, opts) {
+    return makeRule("max-shifts-day", { shifts, ...opts });
+}
+/**
+ * Maximum consecutive working days.
+ *
+ * @example
+ * ```typescript
+ * maxConsecutiveDays(5)
+ * ```
+ *
+ * @category Rules
+ */
+export function maxConsecutiveDays(days, opts) {
+    return makeRule("max-consecutive-days", { days, ...opts });
+}
+/**
+ * Once working, continue for at least this many consecutive days.
+ *
+ * @example
+ * ```typescript
+ * minConsecutiveDays(2, { priority: "HIGH" })
+ * ```
+ *
+ * @category Rules
+ */
+export function minConsecutiveDays(days, opts) {
+    return makeRule("min-consecutive-days", { days, ...opts });
+}
+/**
+ * Minimum rest hours between shifts.
+ *
+ * @example
+ * ```typescript
+ * minRestBetweenShifts(10)
+ * ```
+ *
+ * @category Rules
+ */
+export function minRestBetweenShifts(hours, opts) {
+    return makeRule("min-rest-between-shifts", { hours, ...opts });
+}
+/**
+ * Prefer (`"high"`) or avoid (`"low"`) assigning. Requires `appliesTo`.
+ *
+ * @example
+ * ```typescript
+ * preference("high", { appliesTo: "waiter" })
+ * preference("low", { appliesTo: "student", dayOfWeek: weekdays })
+ * ```
+ *
+ * @category Rules
+ */
+export function preference(level, opts) {
+    return makeRule("assignment-priority", { preference: level, ...opts });
+}
+/**
+ * Prefer assigning to shifts at a specific location. Requires `appliesTo`.
+ *
+ * @example
+ * ```typescript
+ * preferLocation("terrace", { appliesTo: "alice" })
+ * ```
+ *
+ * @category Rules
+ */
+export function preferLocation(locationId, opts) {
+    return makeRule("location-preference", { locationId, ...opts });
+}
+/**
+ * Guarantees that targeted members appear on the schedule each week.
+ *
+ * @remarks
+ * Use for staffing obligations: salaried employees who are paid regardless
+ * of whether they work, or contracted staff who must be rostered. The solver
+ * ensures each targeted member has at least one assignment per scheduling week.
+ *
+ * Always a soft constraint (HIGH priority internally). The schedule still
+ * generates when a member genuinely cannot be placed (e.g., full week of
+ * absences). Violations surface as validation warnings with distinct
+ * messaging from {@link minDaysPerWeek}. Priority is not configurable;
+ * the rule name communicates the intent.
+ *
+ * @example
+ * ```typescript
+ * mustAssign({ appliesTo: "diana" })
+ * mustAssign({ appliesTo: ["diana", "yavuz"] })
+ * ```
+ *
+ * @category Rules
+ */
+export function mustAssign(opts) {
+    return makeRule("must-assign", { ...opts });
+}
+// ============================================================================
+// Special Rules (custom resolvers)
+// ============================================================================
+/**
+ * Block assignments during specified periods.
+ * Requires at least one time scope (`dayOfWeek`, `dateRange`, `dates`, or `from`/`until`).
+ *
+ * @example
+ * ```typescript
+ * // Full days off
+ * timeOff({ appliesTo: "alice", dateRange: { start: "2024-02-01", end: "2024-02-05" } })
+ *
+ * // Every weekend off
+ * timeOff({ appliesTo: "mauro", dayOfWeek: weekend })
+ *
+ * // Wednesday afternoons off
+ * timeOff({ appliesTo: "student", dayOfWeek: ["wednesday"], from: t(14) })
+ * ```
+ *
+ * @category Rules
+ */
+export function timeOff(opts) {
+    const { from, until, ...rest } = opts;
+    return defineRule("time-off", { from, until, ...rest }, (ctx) => {
+        if (!rest.dayOfWeek && !rest.dateRange && !rest.dates && !rest.recurringPeriods) {
+            throw new Error("timeOff() requires at least one time scope (dayOfWeek, dateRange, dates, or recurringPeriods).");
+        }
+        const { appliesTo, dates, ...passthrough } = rest;
+        const entityScope = resolveAppliesTo(appliesTo, ctx.roles, ctx.skills, ctx.memberIds);
+        const resolvedDates = dates ? { specificDates: dates } : {};
+        const partialDay = {};
+        if (from && until) {
+            partialDay.startTime = from;
+            partialDay.endTime = until;
+        }
+        else if (from) {
+            partialDay.startTime = from;
+            partialDay.endTime = { hours: 23, minutes: 59 };
+        }
+        else if (until) {
+            partialDay.startTime = { hours: 0, minutes: 0 };
+            partialDay.endTime = until;
+        }
+        return {
+            name: "time-off",
+            ...passthrough,
+            ...entityScope,
+            ...resolvedDates,
+            ...partialDay,
+        };
+    });
+}
+/**
+ * Members work the same shifts on days they are both assigned.
+ *
+ * @example
+ * ```typescript
+ * assignTogether(["alice", "bob"])
+ * assignTogether(["alice", "bob", "charlie"], { priority: "HIGH" })
+ * ```
+ *
+ * @category Rules
+ */
+export function assignTogether(memberIds, opts) {
+    return defineRule("assign-together", { members: memberIds, ...opts }, (ctx) => {
+        for (const member of memberIds) {
+            if (!ctx.memberIds.has(member)) {
+                throw new Error(`assignTogether references unknown member "${member}". ` +
+                    `Known member IDs: ${[...ctx.memberIds].join(", ")}`);
+            }
+        }
+        return {
+            name: "assign-together",
+            groupMemberIds: memberIds,
+            ...opts,
+        };
+    });
+}
+// ============================================================================
+// Internal: appliesTo resolution (shared with definition.ts)
+// ============================================================================
+/**
+ * Resolves an `appliesTo` value into entity scope fields.
+ *
+ * Each target string is checked against roles, skills, then member IDs.
+ * If all targets resolve to the same namespace, they are combined into one
+ * scope field. If they span namespaces, an error is thrown; the caller
+ * should use separate rule entries instead.
+ *
+ * @internal
+ */
+export function resolveAppliesTo(appliesTo, roles, skills, memberIds) {
+    if (!appliesTo)
+        return {};
+    const targets = Array.isArray(appliesTo) ? appliesTo : [appliesTo];
+    if (targets.length === 0)
+        return {};
+    const resolvedRoles = [];
+    const resolvedSkills = [];
+    const resolvedMembers = [];
+    for (const target of targets) {
+        if (roles.has(target)) {
+            resolvedRoles.push(target);
+        }
+        else if (skills.has(target)) {
+            resolvedSkills.push(target);
+        }
+        else if (memberIds.has(target)) {
+            resolvedMembers.push(target);
+        }
+        else {
+            throw new Error(`appliesTo target "${target}" is not a declared role, skill, or member ID.`);
+        }
+    }
+    // Count how many namespaces were used
+    const namespacesUsed = [resolvedRoles, resolvedSkills, resolvedMembers].filter((arr) => arr.length > 0).length;
+    if (namespacesUsed > 1) {
+        throw new Error(`appliesTo targets span multiple namespaces (roles: [${resolvedRoles.join(", ")}], ` +
+            `skills: [${resolvedSkills.join(", ")}], members: [${resolvedMembers.join(", ")}]). ` +
+            `Use separate rule entries for each namespace.`);
+    }
+    if (resolvedRoles.length > 0) {
+        return { roleIds: resolvedRoles };
+    }
+    if (resolvedSkills.length > 0) {
+        return { skillIds: resolvedSkills };
+    }
+    if (resolvedMembers.length > 0) {
+        return { memberIds: resolvedMembers };
+    }
+    return {};
+}
+//# sourceMappingURL=rules.js.map

package/dist/schedule/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../src/schedule/rules.ts"],"names":[],"mappings":"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"}

package/dist/schedule/shift-patterns.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shift pattern definitions: time slots available for employee assignment.
+ *
+ * @module
+ */
+import type { TimeOfDay } from "../types.js";
+import type { ShiftPattern } from "../cpsat/types.js";
+/**
+ * Define a shift pattern: a time slot available for employee assignment.
+ *
+ * @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 declare function shift(id: string, startTime: TimeOfDay, endTime: TimeOfDay, opts?: Pick<ShiftPattern, "roleIds" | "dayOfWeek" | "locationId">): ShiftPattern;
+//# sourceMappingURL=shift-patterns.d.ts.map

package/dist/schedule/shift-patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shift-patterns.d.ts","sourceRoot":"","sources":["../../src/schedule/shift-patterns.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,KAAK,CACnB,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,SAAS,EAClB,IAAI,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,WAAW,GAAG,YAAY,CAAC,GAChE,YAAY,CAMd"}

package/dist/schedule/shift-patterns.js

@@ -0,0 +1,41 @@
+/**
+ * Shift pattern definitions: time slots available for employee assignment.
+ *
+ * @module
+ */
+/**
+ * Define a shift pattern: a time slot available for employee assignment.
+ *
+ * @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) {
+    const pattern = { id, startTime, endTime };
+    if (opts?.roleIds)
+        pattern.roleIds = opts.roleIds;
+    if (opts?.dayOfWeek)
+        pattern.dayOfWeek = opts.dayOfWeek;
+    if (opts?.locationId)
+        pattern.locationId = opts.locationId;
+    return pattern;
+}
+//# sourceMappingURL=shift-patterns.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,69 @@
+/**
+ * Time period primitives: day constants and time constructors.
+ *
+ * @module
+ */
+import type { TimeOfDay } from "../types.js";
+import type { SemanticTimeVariant, SemanticTimeEntry } from "../cpsat/semantic-time.js";
+/**
+ * Creates a {@link TimeOfDay} value.
+ *
+ * @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;
+/**
+ * Monday through Friday.
+ *
+ * @category Time Periods
+ */
+export declare const weekdays: readonly ["monday", "tuesday", "wednesday", "thursday", "friday"];
+/**
+ * Saturday and Sunday.
+ *
+ * @category Time Periods
+ */
+export declare const weekend: readonly ["saturday", "sunday"];
+/**
+ * Define a named semantic time period.
+ *
+ * @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) }),
+ *
+ *   // Variants: different times on weekends
+ *   dinner: time(
+ *     { startTime: t(17), endTime: t(21) },
+ *     { startTime: t(18), endTime: t(22), dayOfWeek: weekend },
+ *   ),
+ *
+ *   // Point-in-time window (keyholder at opening)
+ *   opening: time({ startTime: t(8, 30), endTime: t(9) }),
+ * }
+ * ```
+ *
+ * @privateRemarks
+ * Resolution precedence: `dates` > `dayOfWeek` > default.
+ *
+ * @category Time Periods
+ */
+export declare function time(...entries: [SemanticTimeVariant, ...SemanticTimeVariant[]]): SemanticTimeEntry;
+//# sourceMappingURL=time-periods.d.ts.map

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

@@ -0,0 +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"}

package/dist/schedule/time-periods.js

@@ -0,0 +1,91 @@
+/**
+ * Time period primitives: day constants and time constructors.
+ *
+ * @module
+ */
+/**
+ * Creates a {@link TimeOfDay} value.
+ *
+ * @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) {
+    return { hours, minutes };
+}
+/**
+ * Monday through Friday.
+ *
+ * @category Time Periods
+ */
+export const weekdays = [
+    "monday",
+    "tuesday",
+    "wednesday",
+    "thursday",
+    "friday",
+];
+/**
+ * Saturday and Sunday.
+ *
+ * @category Time Periods
+ */
+export const weekend = ["saturday", "sunday"];
+/**
+ * Define a named semantic time period.
+ *
+ * @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) }),
+ *
+ *   // Variants: different times on weekends
+ *   dinner: time(
+ *     { startTime: t(17), endTime: t(21) },
+ *     { startTime: t(18), endTime: t(22), dayOfWeek: weekend },
+ *   ),
+ *
+ *   // Point-in-time window (keyholder at opening)
+ *   opening: time({ startTime: t(8, 30), endTime: t(9) }),
+ * }
+ * ```
+ *
+ * @privateRemarks
+ * Resolution precedence: `dates` > `dayOfWeek` > default.
+ *
+ * @category Time Periods
+ */
+export function time(...entries) {
+    // Validate: at most one default (no dayOfWeek and no dates)
+    const defaults = entries.filter((e) => !e.dayOfWeek && !e.dates);
+    if (defaults.length > 1) {
+        throw new Error("time() accepts at most one default entry (without dayOfWeek or dates). " +
+            `Found ${defaults.length} default entries.`);
+    }
+    // Single entry without scoping: simple SemanticTimeDef
+    if (entries.length === 1 && !entries[0].dayOfWeek && !entries[0].dates) {
+        return {
+            startTime: entries[0].startTime,
+            endTime: entries[0].endTime,
+        };
+    }
+    // Multiple entries or scoped entries: shallow-copy to decouple from caller
+    return entries.map((entry) => Object.assign({}, entry));
+}
+//# sourceMappingURL=time-periods.js.map

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

@@ -0,0 +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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dabke",
-  "version": "0.82.0",
+  "version": "0.83.0",
   "description": "Scheduling library powered by constraint programming (CP-SAT)",
   "keywords": [
     "constraint-programming",
@@ -26,7 +26,6 @@
     "CHANGELOG.md",
     "dist",
     "LICENSE",
-    "llms.txt",
     "README.md",
     "solver",
     "src"
@@ -40,10 +39,6 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./llms": {
-      "types": "./dist/llms.d.ts",
-      "default": "./dist/llms.js"
-    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "default": "./dist/testing/index.js"
@@ -59,14 +54,14 @@
     "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:llmstxt": "tsx scripts/generate-llmstxt.ts && oxfmt --write llms.txt src/llms.ts"
+    "generate:reference": "tsx scripts/generate-reference.ts"
   },
   "dependencies": {
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
-    "commander": "^14.0.2",
+    "@types/node": "^25.0.0",
+    "commander": "^14.0.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },

package/src/cpsat/rules/index.ts

@@ -2,13 +2,16 @@ export { createAssignTogetherRule } from "./assign-together.js";
 export { createAssignmentPriorityRule } from "./assignment-priority.js";
 export { createLocationPreferenceRule } from "./location-preference.js";
 export { createMaxConsecutiveDaysRule } from "./max-consecutive-days.js";
+export { createMaxDaysWeekRule } from "./max-days-week.js";
 export { createMaxHoursDayRule } from "./max-hours-day.js";
 export { createMaxHoursWeekRule } from "./max-hours-week.js";
 export { createMaxShiftsDayRule } from "./max-shifts-day.js";
 export { createMinConsecutiveDaysRule } from "./min-consecutive-days.js";
+export { createMinDaysWeekRule } from "./min-days-week.js";
 export { createMinHoursDayRule } from "./min-hours-day.js";
 export { createMinHoursWeekRule } from "./min-hours-week.js";
 export { createMinRestBetweenShiftsRule } from "./min-rest-between-shifts.js";
+export { createMustAssignRule } from "./must-assign.js";
 export { createTimeOffRule } from "./time-off.js";
 export { createMinimizeCostRule } from "./minimize-cost.js";
 export { createDayCostMultiplierRule } from "./day-cost-multiplier.js";