dabke 0.82.0 → 0.83.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 This changelog was generated from the git history of the project when it was
 named `scheduling-core`, prior to the rename to `dabke` in v0.78.0.
 
+## 0.83.0 (2026-03-21)
+
+### Breaking Changes
+
+- Remove `./llms` export path and `llms.txt` from the package. The LLM reference
+  is now generated externally via `generate:reference`.
+
+### Features
+
+- Add `maxDaysPerWeek(days, opts?)` and `minDaysPerWeek(days, opts?)` rule functions
+  to constrain the number of distinct working days per member per scheduling week.
+- Add `mustAssign(opts?)` rule for staffing obligations. Guarantees targeted members
+  appear on the schedule each week; defaults to HIGH priority so the schedule still
+  generates when a member cannot be placed.
+
+### Improvements
+
+- Split `schedule.ts` into focused modules under `src/schedule/` (public API unchanged).
+- Add `NoInfer` on coverage entry types so role/skill references are checked against
+  declared roles and skills at compile time.
+- Update devDependencies (@types/node ^25.0.0, commander ^14.0.3).
+- Publish workflow now includes changelog text in GitHub releases.
+
 ## 0.82.0 (2026-02-23)
 
 ### Breaking Changes

package/README.md

@@ -178,12 +178,15 @@ const ready = venue.with([
 
 ## LLM Integration
 
-dabke ships an `llms.txt` with complete API documentation for AI code generation:
+Generate per-section API reference docs from TSDoc:
 
-```typescript
-import { apiDocs } from "dabke/llms";
+```bash
+npm run generate:reference -- --outdir ./references
 ```
 
+This produces a `README.md` index, an `api.md` API surface listing,
+and one detail file per category (schedule, rules, coverage, etc.).
+
 ---
 
 ## Development

package/dist/cpsat/rules/index.d.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";

package/dist/cpsat/rules/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cpsat/rules/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,8BAA8B,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,kCAAkC,EAAE,MAAM,iCAAiC,CAAC;AACrF,OAAO,EAAE,iCAAiC,EAAE,MAAM,gCAAgC,CAAC;AACnF,OAAO,EAAE,iCAAiC,EAAE,MAAM,gCAAgC,CAAC;AACnF,OAAO,EAAE,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,EAAE,kCAAkC,EAAE,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cpsat/rules/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,8BAA8B,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,kCAAkC,EAAE,MAAM,iCAAiC,CAAC;AACrF,OAAO,EAAE,iCAAiC,EAAE,MAAM,gCAAgC,CAAC;AACnF,OAAO,EAAE,iCAAiC,EAAE,MAAM,gCAAgC,CAAC;AACnF,OAAO,EAAE,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,EAAE,kCAAkC,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/cpsat/rules/index.js

@@ -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";

package/dist/cpsat/rules/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cpsat/rules/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,8BAA8B,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,kCAAkC,EAAE,MAAM,iCAAiC,CAAC;AACrF,OAAO,EAAE,iCAAiC,EAAE,MAAM,gCAAgC,CAAC;AACnF,OAAO,EAAE,iCAAiC,EAAE,MAAM,gCAAgC,CAAC;AACnF,OAAO,EAAE,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,EAAE,kCAAkC,EAAE,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cpsat/rules/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,8BAA8B,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,kCAAkC,EAAE,MAAM,iCAAiC,CAAC;AACrF,OAAO,EAAE,iCAAiC,EAAE,MAAM,gCAAgC,CAAC;AACnF,OAAO,EAAE,iCAAiC,EAAE,MAAM,gCAAgC,CAAC;AACnF,OAAO,EAAE,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,EAAE,kCAAkC,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/cpsat/rules/max-days-week.d.ts

@@ -0,0 +1,44 @@
+import * as z from "zod";
+import type { CompilationRule } from "../model-builder.js";
+declare const MaxDaysWeekSchema: z.ZodIntersection<z.ZodIntersection<z.ZodObject<{
+    days: z.ZodNumber;
+    priority: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"LOW">, z.ZodLiteral<"MEDIUM">, z.ZodLiteral<"HIGH">, z.ZodLiteral<"MANDATORY">]>>;
+    weekStartsOn: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"monday">, z.ZodLiteral<"tuesday">, z.ZodLiteral<"wednesday">, z.ZodLiteral<"thursday">, z.ZodLiteral<"friday">, z.ZodLiteral<"saturday">, z.ZodLiteral<"sunday">]>>;
+}, z.core.$strip>, z.ZodType<import("./scope.types.js").EntityScopeType<"members" | "roles" | "skills">, unknown, z.core.$ZodTypeInternals<import("./scope.types.js").EntityScopeType<"members" | "roles" | "skills">, unknown>>>, z.ZodType<import("./scope.types.js").OptionalTimeScopeType<"dateRange" | "dayOfWeek" | "specificDates" | "recurring">, unknown, z.core.$ZodTypeInternals<import("./scope.types.js").OptionalTimeScopeType<"dateRange" | "dayOfWeek" | "specificDates" | "recurring">, unknown>>>;
+/**
+ * Configuration for {@link createMaxDaysWeekRule}.
+ *
+ * - `days` (required): maximum number of days allowed per scheduling week
+ * - `priority` (required): how strictly the solver enforces this rule
+ * - `weekStartsOn` (optional): which day starts the week; defaults to {@link ModelBuilder.weekStartsOn}
+ *
+ * Entity scoping (at most one): `memberIds`, `roleIds`, `skillIds`
+ * Time scoping (at most one, optional): `dateRange`, `specificDates`, `dayOfWeek`, `recurringPeriods`
+ */
+export type MaxDaysWeekConfig = z.infer<typeof MaxDaysWeekSchema>;
+/**
+ * Caps total number of days a person can work within each scheduling week.
+ *
+ * @remarks
+ * Creates a binary "works on day" variable for each member and day, then
+ * constrains the weekly sum. This counts distinct days, regardless of how
+ * many shifts are assigned on a single day.
+ *
+ * @param config - See {@link MaxDaysWeekConfig}
+ * @example Limit everyone to 5 days per week
+ * ```ts
+ * createMaxDaysWeekRule({ days: 5, priority: "MANDATORY" });
+ * ```
+ *
+ * @example Part-time staff limited to 3 days
+ * ```ts
+ * createMaxDaysWeekRule({
+ *   roleIds: ["part-time"],
+ *   days: 3,
+ *   priority: "HIGH",
+ * });
+ * ```
+ */
+export declare function createMaxDaysWeekRule(config: MaxDaysWeekConfig): CompilationRule;
+export {};
+//# sourceMappingURL=max-days-week.d.ts.map

package/dist/cpsat/rules/max-days-week.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"max-days-week.d.ts","sourceRoot":"","sources":["../../../src/cpsat/rules/max-days-week.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAoB3D,QAAA,MAAM,iBAAiB;;;;mfAEtB,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,iBAAiB,GAAG,eAAe,CAiFhF"}

package/dist/cpsat/rules/max-days-week.js

@@ -0,0 +1,95 @@
+import * as z from "zod";
+import { DayOfWeekSchema } from "../../types.js";
+import { priorityToPenalty, splitIntoWeeks } from "../utils.js";
+import { PrioritySchema, entityScope, timeScope, parseEntityScope, parseTimeScope, resolveMembersFromScope, resolveActiveDaysFromScope, ruleGroup, } from "./scope.types.js";
+const MaxDaysWeekBase = z.object({
+    days: z.number().int().min(0),
+    priority: PrioritySchema,
+    weekStartsOn: DayOfWeekSchema.optional(),
+});
+const MaxDaysWeekSchema = MaxDaysWeekBase.and(entityScope(["members", "roles", "skills"])).and(timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]));
+/**
+ * Caps total number of days a person can work within each scheduling week.
+ *
+ * @remarks
+ * Creates a binary "works on day" variable for each member and day, then
+ * constrains the weekly sum. This counts distinct days, regardless of how
+ * many shifts are assigned on a single day.
+ *
+ * @param config - See {@link MaxDaysWeekConfig}
+ * @example Limit everyone to 5 days per week
+ * ```ts
+ * createMaxDaysWeekRule({ days: 5, priority: "MANDATORY" });
+ * ```
+ *
+ * @example Part-time staff limited to 3 days
+ * ```ts
+ * createMaxDaysWeekRule({
+ *   roleIds: ["part-time"],
+ *   days: 3,
+ *   priority: "HIGH",
+ * });
+ * ```
+ */
+export function createMaxDaysWeekRule(config) {
+    const parsed = MaxDaysWeekSchema.parse(config);
+    const entityScopeValue = parseEntityScope(parsed);
+    const timeScopeValue = parseTimeScope(parsed);
+    const { days, priority, weekStartsOn } = parsed;
+    const group = ruleGroup(`max-days-week:${days}`, `Max ${days}d per week`, entityScopeValue, timeScopeValue);
+    return {
+        compile(b) {
+            const targetMembers = resolveMembersFromScope(entityScopeValue, b.members);
+            const activeDays = resolveActiveDaysFromScope(timeScopeValue, b.days);
+            if (targetMembers.length === 0 || activeDays.length === 0)
+                return;
+            const weeks = splitIntoWeeks(activeDays, weekStartsOn ?? b.weekStartsOn);
+            for (const emp of targetMembers) {
+                for (const weekDays of weeks) {
+                    const weekWorkVars = [];
+                    for (const day of weekDays) {
+                        const dayAssignments = b.shiftPatterns
+                            .filter((p) => b.canAssign(emp, p) && b.patternAvailableOnDay(p, day))
+                            .map((p) => b.assignment(emp.id, p.id, day));
+                        if (dayAssignments.length === 0)
+                            continue;
+                        const worksVar = b.boolVar(`works_day_${emp.id}_${day}`);
+                        weekWorkVars.push(worksVar);
+                        // worksVar >= each assignment (if any assignment is 1, worksVar must be 1)
+                        for (const assignVar of dayAssignments) {
+                            b.addLinear([
+                                { var: worksVar, coeff: 1 },
+                                { var: assignVar, coeff: -1 },
+                            ], ">=", 0);
+                        }
+                        // worksVar <= sum(assignments) (if no assignment is 1, worksVar must be 0)
+                        b.addLinear([{ var: worksVar, coeff: 1 }, ...dayAssignments.map((v) => ({ var: v, coeff: -1 }))], "<=", 0);
+                    }
+                    if (weekWorkVars.length === 0)
+                        continue;
+                    const weekLabel = weekDays[0];
+                    const constraintId = `max-days-week:${emp.id}:${weekLabel}`;
+                    const terms = weekWorkVars.map((v) => ({ var: v, coeff: 1 }));
+                    if (priority === "MANDATORY") {
+                        b.addLinear(terms, "<=", days);
+                    }
+                    else {
+                        b.addSoftLinear(terms, "<=", days, priorityToPenalty(priority), constraintId);
+                        b.reporter.trackConstraint({
+                            id: constraintId,
+                            type: "rule",
+                            rule: "max-days-week",
+                            description: `${emp.id} max ${days}d in week starting ${weekLabel}`,
+                            targetValue: days,
+                            comparator: "<=",
+                            day: weekLabel,
+                            context: { memberIds: [emp.id], days: weekDays },
+                            group,
+                        });
+                    }
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=max-days-week.js.map

package/dist/cpsat/rules/max-days-week.js.map

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

package/dist/cpsat/rules/min-days-week.d.ts

@@ -0,0 +1,34 @@
+import * as z from "zod";
+import type { CompilationRule } from "../model-builder.js";
+declare const MinDaysWeekSchema: z.ZodIntersection<z.ZodObject<{
+    days: z.ZodNumber;
+    priority: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"LOW">, z.ZodLiteral<"MEDIUM">, z.ZodLiteral<"HIGH">, z.ZodLiteral<"MANDATORY">]>>;
+    weekStartsOn: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"monday">, z.ZodLiteral<"tuesday">, z.ZodLiteral<"wednesday">, z.ZodLiteral<"thursday">, z.ZodLiteral<"friday">, z.ZodLiteral<"saturday">, z.ZodLiteral<"sunday">]>>;
+}, z.core.$strip>, z.ZodType<import("./scope.types.js").EntityScopeType<"members" | "roles" | "skills">, unknown, z.core.$ZodTypeInternals<import("./scope.types.js").EntityScopeType<"members" | "roles" | "skills">, unknown>>>;
+/**
+ * Configuration for {@link createMinDaysWeekRule}.
+ *
+ * - `days` (required): minimum number of days required per scheduling week
+ * - `priority` (required): how strictly the solver enforces this rule
+ * - `weekStartsOn` (optional): which day starts the week; defaults to {@link ModelBuilder.weekStartsOn}
+ *
+ * Entity scoping (at most one): `memberIds`, `roleIds`, `skillIds`
+ */
+export type MinDaysWeekConfig = z.infer<typeof MinDaysWeekSchema>;
+/**
+ * Enforces a minimum number of days a person must work per scheduling week.
+ *
+ * @remarks
+ * Creates a binary "works on day" variable for each member and day, then
+ * constrains the weekly sum. This counts distinct days, regardless of how
+ * many shifts are assigned on a single day.
+ *
+ * @param config - See {@link MinDaysWeekConfig}
+ * @example
+ * ```ts
+ * createMinDaysWeekRule({ days: 3, priority: "HIGH" });
+ * ```
+ */
+export declare function createMinDaysWeekRule(config: MinDaysWeekConfig): CompilationRule;
+export {};
+//# sourceMappingURL=min-days-week.d.ts.map

package/dist/cpsat/rules/min-days-week.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"min-days-week.d.ts","sourceRoot":"","sources":["../../../src/cpsat/rules/min-days-week.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAiB3D,QAAA,MAAM,iBAAiB;;;;iOAAmE,CAAC;AAE3F;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,iBAAiB,GAAG,eAAe,CAyEhF"}

package/dist/cpsat/rules/min-days-week.js

@@ -0,0 +1,84 @@
+import * as z from "zod";
+import { DayOfWeekSchema } from "../../types.js";
+import { priorityToPenalty, splitIntoWeeks } from "../utils.js";
+import { PrioritySchema, entityScope, parseEntityScope, resolveMembersFromScope, ruleGroup, } from "./scope.types.js";
+const MinDaysWeekBase = z.object({
+    days: z.number().int().min(0),
+    priority: PrioritySchema,
+    weekStartsOn: DayOfWeekSchema.optional(),
+});
+const MinDaysWeekSchema = MinDaysWeekBase.and(entityScope(["members", "roles", "skills"]));
+/**
+ * Enforces a minimum number of days a person must work per scheduling week.
+ *
+ * @remarks
+ * Creates a binary "works on day" variable for each member and day, then
+ * constrains the weekly sum. This counts distinct days, regardless of how
+ * many shifts are assigned on a single day.
+ *
+ * @param config - See {@link MinDaysWeekConfig}
+ * @example
+ * ```ts
+ * createMinDaysWeekRule({ days: 3, priority: "HIGH" });
+ * ```
+ */
+export function createMinDaysWeekRule(config) {
+    const parsed = MinDaysWeekSchema.parse(config);
+    const scope = parseEntityScope(parsed);
+    const { days, priority, weekStartsOn } = parsed;
+    const group = ruleGroup(`min-days-week:${days}`, `Min ${days}d per week`, scope);
+    return {
+        compile(b) {
+            if (days <= 0)
+                return;
+            const members = resolveMembersFromScope(scope, b.members);
+            const weeks = splitIntoWeeks(b.days, weekStartsOn ?? b.weekStartsOn);
+            for (const emp of members) {
+                for (const weekDays of weeks) {
+                    const weekWorkVars = [];
+                    for (const day of weekDays) {
+                        const dayAssignments = b.shiftPatterns
+                            .filter((p) => b.canAssign(emp, p) && b.patternAvailableOnDay(p, day))
+                            .map((p) => b.assignment(emp.id, p.id, day));
+                        if (dayAssignments.length === 0)
+                            continue;
+                        const worksVar = b.boolVar(`works_day_${emp.id}_${day}`);
+                        weekWorkVars.push(worksVar);
+                        // worksVar >= each assignment (if any assignment is 1, worksVar must be 1)
+                        for (const assignVar of dayAssignments) {
+                            b.addLinear([
+                                { var: worksVar, coeff: 1 },
+                                { var: assignVar, coeff: -1 },
+                            ], ">=", 0);
+                        }
+                        // worksVar <= sum(assignments) (if no assignment is 1, worksVar must be 0)
+                        b.addLinear([{ var: worksVar, coeff: 1 }, ...dayAssignments.map((v) => ({ var: v, coeff: -1 }))], "<=", 0);
+                    }
+                    if (weekWorkVars.length === 0)
+                        continue;
+                    const weekLabel = weekDays[0];
+                    const constraintId = `min-days-week:${emp.id}:${weekLabel}`;
+                    const terms = weekWorkVars.map((v) => ({ var: v, coeff: 1 }));
+                    if (priority === "MANDATORY") {
+                        b.addLinear(terms, ">=", days);
+                    }
+                    else {
+                        b.addSoftLinear(terms, ">=", days, priorityToPenalty(priority), constraintId);
+                        b.reporter.trackConstraint({
+                            id: constraintId,
+                            type: "rule",
+                            rule: "min-days-week",
+                            description: `${emp.id} min ${days}d in week starting ${weekLabel}`,
+                            targetValue: days,
+                            comparator: ">=",
+                            day: weekLabel,
+                            context: { memberIds: [emp.id], days: weekDays },
+                            group,
+                        });
+                    }
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=min-days-week.js.map

package/dist/cpsat/rules/min-days-week.js.map

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

package/dist/cpsat/rules/must-assign.d.ts

@@ -0,0 +1,49 @@
+import * as z from "zod";
+import type { CompilationRule } from "../model-builder.js";
+declare const MustAssignSchema: z.ZodIntersection<z.ZodObject<{
+    weekStartsOn: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"monday">, z.ZodLiteral<"tuesday">, z.ZodLiteral<"wednesday">, z.ZodLiteral<"thursday">, z.ZodLiteral<"friday">, z.ZodLiteral<"saturday">, z.ZodLiteral<"sunday">]>>;
+}, z.core.$strip>, z.ZodType<import("./scope.types.js").EntityScopeType<"members" | "roles" | "skills">, unknown, z.core.$ZodTypeInternals<import("./scope.types.js").EntityScopeType<"members" | "roles" | "skills">, unknown>>>;
+/**
+ * Configuration for {@link createMustAssignRule}.
+ *
+ * - `weekStartsOn` (optional): which day starts the week; defaults to
+ *   {@link ModelBuilder.weekStartsOn}
+ *
+ * Entity scoping (at most one): `memberIds`, `roleIds`, `skillIds`
+ */
+export type MustAssignConfig = z.infer<typeof MustAssignSchema>;
+/**
+ * Guarantees that targeted members appear on the schedule.
+ *
+ * @remarks
+ * Use this 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 compiles as a soft constraint (HIGH priority internally) so the
+ * schedule still generates when a member genuinely cannot be placed
+ * (e.g., full week of absences, no compatible shift patterns). Violations
+ * surface as validation warnings with distinct messaging from
+ * `min-days-week`.
+ *
+ * Unlike {@link createMinDaysWeekRule}, this rule communicates a staffing
+ * obligation rather than a scheduling preference. Validation messages
+ * reflect this: "Alice was not assigned (staffing obligation)" rather
+ * than "Alice worked 0 days, minimum was 1."
+ *
+ * @param config - See {@link MustAssignConfig}
+ *
+ * @example Ensure a salaried manager is always rostered
+ * ```ts
+ * createMustAssignRule({ memberIds: ["diana"] });
+ * ```
+ *
+ * @example Ensure all supervisors appear on the rota
+ * ```ts
+ * createMustAssignRule({ roleIds: ["supervisor"] });
+ * ```
+ */
+export declare function createMustAssignRule(config: MustAssignConfig): CompilationRule;
+export {};
+//# sourceMappingURL=must-assign.d.ts.map

package/dist/cpsat/rules/must-assign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"must-assign.d.ts","sourceRoot":"","sources":["../../../src/cpsat/rules/must-assign.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAa3D,QAAA,MAAM,gBAAgB;;iOAI6B,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,eAAe,CA4C9E"}

package/dist/cpsat/rules/must-assign.js

@@ -0,0 +1,86 @@
+import * as z from "zod";
+import { DayOfWeekSchema } from "../../types.js";
+import { priorityToPenalty, splitIntoWeeks } from "../utils.js";
+import { entityScope, parseEntityScope, resolveMembersFromScope, ruleGroup, } from "./scope.types.js";
+/** Internally always HIGH. Not user-configurable. */
+const MUST_ASSIGN_PENALTY = priorityToPenalty("HIGH");
+const MustAssignSchema = z
+    .object({
+    weekStartsOn: DayOfWeekSchema.optional(),
+})
+    .and(entityScope(["members", "roles", "skills"]));
+/**
+ * Guarantees that targeted members appear on the schedule.
+ *
+ * @remarks
+ * Use this 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 compiles as a soft constraint (HIGH priority internally) so the
+ * schedule still generates when a member genuinely cannot be placed
+ * (e.g., full week of absences, no compatible shift patterns). Violations
+ * surface as validation warnings with distinct messaging from
+ * `min-days-week`.
+ *
+ * Unlike {@link createMinDaysWeekRule}, this rule communicates a staffing
+ * obligation rather than a scheduling preference. Validation messages
+ * reflect this: "Alice was not assigned (staffing obligation)" rather
+ * than "Alice worked 0 days, minimum was 1."
+ *
+ * @param config - See {@link MustAssignConfig}
+ *
+ * @example Ensure a salaried manager is always rostered
+ * ```ts
+ * createMustAssignRule({ memberIds: ["diana"] });
+ * ```
+ *
+ * @example Ensure all supervisors appear on the rota
+ * ```ts
+ * createMustAssignRule({ roleIds: ["supervisor"] });
+ * ```
+ */
+export function createMustAssignRule(config) {
+    const parsed = MustAssignSchema.parse(config);
+    const scope = parseEntityScope(parsed);
+    const { weekStartsOn } = parsed;
+    const group = ruleGroup("must-assign", "Must assign", scope);
+    return {
+        compile(b) {
+            const members = resolveMembersFromScope(scope, b.members);
+            const weeks = splitIntoWeeks(b.days, weekStartsOn ?? b.weekStartsOn);
+            for (const emp of members) {
+                for (const weekDays of weeks) {
+                    const terms = [];
+                    for (const day of weekDays) {
+                        for (const pattern of b.shiftPatterns) {
+                            if (!b.canAssign(emp, pattern))
+                                continue;
+                            if (!b.patternAvailableOnDay(pattern, day))
+                                continue;
+                            terms.push({ var: b.assignment(emp.id, pattern.id, day), coeff: 1 });
+                        }
+                    }
+                    if (terms.length === 0)
+                        continue;
+                    const weekLabel = weekDays[0];
+                    const constraintId = `must-assign:${emp.id}:${weekLabel}`;
+                    b.addSoftLinear(terms, ">=", 1, MUST_ASSIGN_PENALTY, constraintId);
+                    b.reporter.trackConstraint({
+                        id: constraintId,
+                        type: "rule",
+                        rule: "must-assign",
+                        description: `${emp.id} not assigned in week starting ${weekLabel} (staffing obligation)`,
+                        targetValue: 1,
+                        comparator: ">=",
+                        day: weekLabel,
+                        context: { memberIds: [emp.id], days: weekDays },
+                        group,
+                    });
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=must-assign.js.map

package/dist/cpsat/rules/must-assign.js.map

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

package/dist/cpsat/rules/registry.d.ts

@@ -1,17 +1,20 @@
-import { createAssignTogetherRule, createAssignmentPriorityRule, createLocationPreferenceRule, createMaxConsecutiveDaysRule, createMaxHoursDayRule, createMaxHoursWeekRule, createMaxShiftsDayRule, createMinConsecutiveDaysRule, createMinHoursDayRule, createMinHoursWeekRule, createMinRestBetweenShiftsRule, createTimeOffRule, createMinimizeCostRule, createDayCostMultiplierRule, createDayCostSurchargeRule, createTimeCostSurchargeRule, createOvertimeWeeklyMultiplierRule, createOvertimeWeeklySurchargeRule, createOvertimeDailyMultiplierRule, createOvertimeDailySurchargeRule, createOvertimeTieredMultiplierRule } from "./index.js";
+import { createAssignTogetherRule, createAssignmentPriorityRule, createLocationPreferenceRule, createMaxConsecutiveDaysRule, createMaxDaysWeekRule, createMaxHoursDayRule, createMaxHoursWeekRule, createMaxShiftsDayRule, createMinConsecutiveDaysRule, createMinDaysWeekRule, createMinHoursDayRule, createMinHoursWeekRule, createMinRestBetweenShiftsRule, createMustAssignRule, createTimeOffRule, createMinimizeCostRule, createDayCostMultiplierRule, createDayCostSurchargeRule, createTimeCostSurchargeRule, createOvertimeWeeklyMultiplierRule, createOvertimeWeeklySurchargeRule, createOvertimeDailyMultiplierRule, createOvertimeDailySurchargeRule, createOvertimeTieredMultiplierRule } from "./index.js";
 import type { CpsatRuleFactories } from "./rules.types.js";
 export declare const builtInCpsatRuleFactories: {
     "assign-together": typeof createAssignTogetherRule;
     "assignment-priority": typeof createAssignmentPriorityRule;
     "location-preference": typeof createLocationPreferenceRule;
     "max-consecutive-days": typeof createMaxConsecutiveDaysRule;
+    "max-days-week": typeof createMaxDaysWeekRule;
     "max-hours-day": typeof createMaxHoursDayRule;
     "max-hours-week": typeof createMaxHoursWeekRule;
     "max-shifts-day": typeof createMaxShiftsDayRule;
     "min-consecutive-days": typeof createMinConsecutiveDaysRule;
+    "min-days-week": typeof createMinDaysWeekRule;
     "min-hours-day": typeof createMinHoursDayRule;
     "min-hours-week": typeof createMinHoursWeekRule;
     "min-rest-between-shifts": typeof createMinRestBetweenShiftsRule;
+    "must-assign": typeof createMustAssignRule;
     "time-off": typeof createTimeOffRule;
     "minimize-cost": typeof createMinimizeCostRule;
     "day-cost-multiplier": typeof createDayCostMultiplierRule;

package/dist/cpsat/rules/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/cpsat/rules/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,4BAA4B,EAC5B,4BAA4B,EAC5B,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,4BAA4B,EAC5B,qBAAqB,EACrB,sBAAsB,EACtB,8BAA8B,EAC9B,iBAAiB,EACjB,sBAAsB,EACtB,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,kCAAkC,EAClC,iCAAiC,EACjC,iCAAiC,EACjC,gCAAgC,EAChC,kCAAkC,EACnC,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAEV,kBAAkB,EAEnB,MAAM,kBAAkB,CAAC;AAE1B,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;CAsBD,CAAC;AAEtC;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,kBAAkB,EAAE,SAAS,EAAE,CAAC,GAAG,CAAC,CAUpF"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/cpsat/rules/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,4BAA4B,EAC5B,4BAA4B,EAC5B,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,4BAA4B,EAC5B,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,8BAA8B,EAC9B,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,kCAAkC,EAClC,iCAAiC,EACjC,iCAAiC,EACjC,gCAAgC,EAChC,kCAAkC,EACnC,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAEV,kBAAkB,EAEnB,MAAM,kBAAkB,CAAC;AAE1B,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;CAyBD,CAAC;AAEtC;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,kBAAkB,EAAE,SAAS,EAAE,CAAC,GAAG,CAAC,CAUpF"}

package/dist/cpsat/rules/registry.js

@@ -1,16 +1,19 @@
-import { createAssignTogetherRule, createAssignmentPriorityRule, createLocationPreferenceRule, createMaxConsecutiveDaysRule, createMaxHoursDayRule, createMaxHoursWeekRule, createMaxShiftsDayRule, createMinConsecutiveDaysRule, createMinHoursDayRule, createMinHoursWeekRule, createMinRestBetweenShiftsRule, createTimeOffRule, createMinimizeCostRule, createDayCostMultiplierRule, createDayCostSurchargeRule, createTimeCostSurchargeRule, createOvertimeWeeklyMultiplierRule, createOvertimeWeeklySurchargeRule, createOvertimeDailyMultiplierRule, createOvertimeDailySurchargeRule, createOvertimeTieredMultiplierRule, } from "./index.js";
+import { createAssignTogetherRule, createAssignmentPriorityRule, createLocationPreferenceRule, createMaxConsecutiveDaysRule, createMaxDaysWeekRule, createMaxHoursDayRule, createMaxHoursWeekRule, createMaxShiftsDayRule, createMinConsecutiveDaysRule, createMinDaysWeekRule, createMinHoursDayRule, createMinHoursWeekRule, createMinRestBetweenShiftsRule, createMustAssignRule, createTimeOffRule, createMinimizeCostRule, createDayCostMultiplierRule, createDayCostSurchargeRule, createTimeCostSurchargeRule, createOvertimeWeeklyMultiplierRule, createOvertimeWeeklySurchargeRule, createOvertimeDailyMultiplierRule, createOvertimeDailySurchargeRule, createOvertimeTieredMultiplierRule, } from "./index.js";
 export const builtInCpsatRuleFactories = {
     "assign-together": createAssignTogetherRule,
     "assignment-priority": createAssignmentPriorityRule,
     "location-preference": createLocationPreferenceRule,
     "max-consecutive-days": createMaxConsecutiveDaysRule,
+    "max-days-week": createMaxDaysWeekRule,
     "max-hours-day": createMaxHoursDayRule,
     "max-hours-week": createMaxHoursWeekRule,
     "max-shifts-day": createMaxShiftsDayRule,
     "min-consecutive-days": createMinConsecutiveDaysRule,
+    "min-days-week": createMinDaysWeekRule,
     "min-hours-day": createMinHoursDayRule,
     "min-hours-week": createMinHoursWeekRule,
     "min-rest-between-shifts": createMinRestBetweenShiftsRule,
+    "must-assign": createMustAssignRule,
     "time-off": createTimeOffRule,
     "minimize-cost": createMinimizeCostRule,
     "day-cost-multiplier": createDayCostMultiplierRule,

package/dist/cpsat/rules/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/cpsat/rules/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,4BAA4B,EAC5B,4BAA4B,EAC5B,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,4BAA4B,EAC5B,qBAAqB,EACrB,sBAAsB,EACtB,8BAA8B,EAC9B,iBAAiB,EACjB,sBAAsB,EACtB,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,kCAAkC,EAClC,iCAAiC,EACjC,iCAAiC,EACjC,gCAAgC,EAChC,kCAAkC,GACnC,MAAM,YAAY,CAAC;AAOpB,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,iBAAiB,EAAE,wBAAwB;IAC3C,qBAAqB,EAAE,4BAA4B;IACnD,qBAAqB,EAAE,4BAA4B;IACnD,sBAAsB,EAAE,4BAA4B;IACpD,eAAe,EAAE,qBAAqB;IACtC,gBAAgB,EAAE,sBAAsB;IACxC,gBAAgB,EAAE,sBAAsB;IACxC,sBAAsB,EAAE,4BAA4B;IACpD,eAAe,EAAE,qBAAqB;IACtC,gBAAgB,EAAE,sBAAsB;IACxC,yBAAyB,EAAE,8BAA8B;IACzD,UAAU,EAAE,iBAAiB;IAC7B,eAAe,EAAE,sBAAsB;IACvC,qBAAqB,EAAE,2BAA2B;IAClD,oBAAoB,EAAE,0BAA0B;IAChD,qBAAqB,EAAE,2BAA2B;IAClD,4BAA4B,EAAE,kCAAkC;IAChE,2BAA2B,EAAE,iCAAiC;IAC9D,2BAA2B,EAAE,iCAAiC;IAC9D,0BAA0B,EAAE,gCAAgC;IAC5D,4BAA4B,EAAE,kCAAkC;CAC7B,CAAC;AAEtC;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAA+B,SAAY;IAC/E,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,IACE,IAAI,IAAI,yBAAyB;YACjC,SAAS,CAAC,IAAI,CAAC,KAAK,yBAAyB,CAAC,IAAqB,CAAC,EACpE,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,yCAAyC,IAAI,qBAAqB,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/cpsat/rules/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,4BAA4B,EAC5B,4BAA4B,EAC5B,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,4BAA4B,EAC5B,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,8BAA8B,EAC9B,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,kCAAkC,EAClC,iCAAiC,EACjC,iCAAiC,EACjC,gCAAgC,EAChC,kCAAkC,GACnC,MAAM,YAAY,CAAC;AAOpB,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,iBAAiB,EAAE,wBAAwB;IAC3C,qBAAqB,EAAE,4BAA4B;IACnD,qBAAqB,EAAE,4BAA4B;IACnD,sBAAsB,EAAE,4BAA4B;IACpD,eAAe,EAAE,qBAAqB;IACtC,eAAe,EAAE,qBAAqB;IACtC,gBAAgB,EAAE,sBAAsB;IACxC,gBAAgB,EAAE,sBAAsB;IACxC,sBAAsB,EAAE,4BAA4B;IACpD,eAAe,EAAE,qBAAqB;IACtC,eAAe,EAAE,qBAAqB;IACtC,gBAAgB,EAAE,sBAAsB;IACxC,yBAAyB,EAAE,8BAA8B;IACzD,aAAa,EAAE,oBAAoB;IACnC,UAAU,EAAE,iBAAiB;IAC7B,eAAe,EAAE,sBAAsB;IACvC,qBAAqB,EAAE,2BAA2B;IAClD,oBAAoB,EAAE,0BAA0B;IAChD,qBAAqB,EAAE,2BAA2B;IAClD,4BAA4B,EAAE,kCAAkC;IAChE,2BAA2B,EAAE,iCAAiC;IAC9D,2BAA2B,EAAE,iCAAiC;IAC9D,0BAA0B,EAAE,gCAAgC;IAC5D,4BAA4B,EAAE,kCAAkC;CAC7B,CAAC;AAEtC;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAA+B,SAAY;IAC/E,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,IACE,IAAI,IAAI,yBAAyB;YACjC,SAAS,CAAC,IAAI,CAAC,KAAK,yBAAyB,CAAC,IAAqB,CAAC,EACpE,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,yCAAyC,IAAI,qBAAqB,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/cpsat/rules/rules.types.d.ts

@@ -5,13 +5,16 @@ export interface CpsatRuleRegistry {
     "assignment-priority": import("./assignment-priority.js").AssignmentPriorityConfig;
     "location-preference": import("./location-preference.js").LocationPreferenceConfig;
     "max-consecutive-days": import("./max-consecutive-days.js").MaxConsecutiveDaysConfig;
+    "max-days-week": import("./max-days-week.js").MaxDaysWeekConfig;
     "max-hours-day": import("./max-hours-day.js").MaxHoursDayConfig;
     "max-hours-week": import("./max-hours-week.js").MaxHoursWeekConfig;
     "max-shifts-day": import("./max-shifts-day.js").MaxShiftsDayConfig;
     "min-consecutive-days": import("./min-consecutive-days.js").MinConsecutiveDaysConfig;
+    "min-days-week": import("./min-days-week.js").MinDaysWeekConfig;
     "min-hours-day": import("./min-hours-day.js").MinHoursDayConfig;
     "min-hours-week": import("./min-hours-week.js").MinHoursWeekConfig;
     "min-rest-between-shifts": import("./min-rest-between-shifts.js").MinRestBetweenShiftsConfig;
+    "must-assign": import("./must-assign.js").MustAssignConfig;
     "time-off": import("./time-off.js").TimeOffConfig;
     "minimize-cost": import("./minimize-cost.js").MinimizeCostConfig;
     "day-cost-multiplier": import("./day-cost-multiplier.js").DayCostMultiplierConfig;