dabke 0.78.2 → 0.80.0

package/llms.txt

@@ -4,7 +4,7 @@
 
 Scheduling library powered by constraint programming (CP-SAT).
 
-Define teams, shifts, coverage, and rules — dabke turns them
+Define teams, shifts, coverage, and rules. dabke turns them
 into an optimized schedule.
 
 ## Core Concepts
@@ -109,6 +109,47 @@ Used for checking overlaps and scheduling constraints.
 - `start: DateTimeWithUtcOffset | DateTimeWithTimeZone`
 - `end: DateTimeWithUtcOffset | DateTimeWithTimeZone`
 
+### SchedulingPeriod
+Defines a scheduling period as a date range with optional filters.
+
+The `dateRange` specifies the overall scheduling window. Use `daysOfWeek`
+and/or `dates` to narrow which days within the range are included.
+Filters compose: a day must pass all specified filters to be included.
+
+**Example:**
+All days in a week
+```typescript
+const period: SchedulingPeriod = {
+dateRange: { start: '2025-02-03', end: '2025-02-09' },
+};
+```
+
+**Example:**
+Only specific days of the week (restaurant closed Mon/Tue)
+```typescript
+const period: SchedulingPeriod = {
+dateRange: { start: '2025-02-03', end: '2025-02-09' },
+daysOfWeek: ['wednesday', 'thursday', 'friday', 'saturday', 'sunday'],
+};
+```
+
+**Example:**
+Only specific dates within the range
+```typescript
+const period: SchedulingPeriod = {
+dateRange: { start: '2025-02-03', end: '2025-02-09' },
+dates: ['2025-02-05', '2025-02-07'],
+};
+```
+
+**Properties:**
+- `dateRange: { start: string; end: string; }` - The overall scheduling window (start and end are inclusive).
+Dates should be in YYYY-MM-DD format.
+- `daysOfWeek?: DayOfWeek[] | undefined` - Include only these days of the week.
+If omitted, all days of the week are included.
+- `dates?: string[] | undefined` - Include only these specific dates (YYYY-MM-DD) within the range.
+If omitted, all dates in the range are included (subject to daysOfWeek filter).
+
 ### SolverClient
 **Properties:**
 - `solve: (request: SolverRequest, options?: { signal?: AbortSignal; }) => Promise<SolverResponse>`
@@ -132,10 +173,10 @@ daysOfWeek: ['wednesday', 'thursday', 'friday', 'saturday', 'sunday'],
 ```
 
 **Properties:**
-- `employees: SchedulingEmployee[]`
-- `shiftPatterns: ShiftPattern[]`
-- `schedulingPeriod: { dateRange: { start: string; end: string; }; daysOfWeek?: DayOfWeek[]; specificDates?: never; } | { specificDates: string[]; dateRange?: never; daysOfWeek?: never; }` - Defines when scheduling should occur. Can specify either a date range
-(with optional day-of-week filtering) or a list of specific dates.
+- `employees: SchedulingEmployee[]` - Team members available for scheduling.
+- `shiftPatterns: ShiftPattern[]` - Available shift patterns (time slots) that employees can be assigned to.
+- `schedulingPeriod: SchedulingPeriod` - Defines when scheduling should occur as a date range with optional
+`daysOfWeek` and `dates` filters that compose to narrow which days are included.
 - `coverage: CoverageRequirement[]`
 - `rules?: CompilationRule[] | undefined` - Pre-compiled rules; use this for custom rules that are not part of the registry.
 - `ruleConfigs?: CpsatRuleConfigEntry[] | undefined` - Named rule configurations that will be compiled using the provided rule factories.
@@ -149,9 +190,15 @@ daysOfWeek: ['wednesday', 'thursday', 'friday', 'saturday', 'sunday'],
 - `canSolve: boolean`
 
 ### CompilationRule
+A rule that adds constraints or objectives to the solver model.
+
+Rules implement `compile` to emit solver constraints during model building,
+and optionally `validate` to check the solution after solving.
+Use the `create*Rule` functions to create built-in rules.
+
 **Properties:**
-- `compile: (builder: ModelBuilder) => void`
-- `validate?: ((assignments: ResolvedShiftAssignment[], reporter: ValidationReporter, context: RuleValidationContext) => void) | undefined`
+- `compile: (builder: ModelBuilder) => void` - Emit constraints and objectives into the model builder.
+- `validate?: ((assignments: ResolvedShiftAssignment[], reporter: ValidationReporter, context: RuleValidationContext) => void) | undefined` - Validate the solved schedule and report violations.
 
 ### RuleValidationContext
 Context provided to rules during post-solve validation.
@@ -162,52 +209,62 @@ Context provided to rules during post-solve validation.
 - `shiftPatterns: ShiftPattern[]`
 
 ### ShiftAssignment
-A shift assignment extracted from the solver response.
+A raw assignment from the solver: which employee works which shift on which day.
 
 **Properties:**
-- `employeeId: string`
-- `shiftPatternId: string`
-- `day: string`
+- `employeeId: string` - The assigned employee's ID.
+- `shiftPatternId: string` - The shift pattern this employee is assigned to.
+- `day: string` - The date of the assignment (YYYY-MM-DD).
 
 ### ResolvedShiftAssignment
 A shift assignment with resolved times.
 
 **Properties:**
-- `employeeId: string`
-- `day: string`
-- `startTime: TimeOfDay`
-- `endTime: TimeOfDay`
+- `employeeId: string` - The assigned employee's ID.
+- `day: string` - The date of the assignment (YYYY-MM-DD).
+- `startTime: TimeOfDay` - When the shift starts.
+- `endTime: TimeOfDay` - When the shift ends.
 
 ### SolverResult
 Parsed solver result with assignments and metadata.
 
 **Properties:**
-- `status: "OPTIMAL" | "FEASIBLE" | "INFEASIBLE" | "TIMEOUT" | "ERROR"`
-- `assignments: ShiftAssignment[]`
-- `statistics?: { solveTimeMs?: number | undefined; conflicts?: number | undefined; branches?: number | undefined; } | undefined`
-- `error?: string | undefined`
+- `status: "OPTIMAL" | "FEASIBLE" | "INFEASIBLE" | "TIMEOUT" | "ERROR"` - The solver outcome: OPTIMAL, FEASIBLE, INFEASIBLE, TIMEOUT, or ERROR.
+- `assignments: ShiftAssignment[]` - The shift assignments extracted from the solution.
+- `statistics?: { solveTimeMs?: number | undefined; conflicts?: number | undefined; branches?: number | undefined; } | undefined` - Solver performance statistics (branches, conflicts, solve time).
+- `error?: string | undefined` - Error message if the solver returned an error status.
+
+### RecurringPeriod
+Recurring calendar period for time scoping.
+
+**Properties:**
+- `name: string`
+- `startMonth: number`
+- `startDay: number`
+- `endMonth: number`
+- `endDay: number`
 
 ### CpsatRuleRegistry
 **Properties:**
 - `"assign-together": { groupEmployeeIds: [string, string, ...string[]]; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; }`
-- `"employee-assignment-priority": { preference: "high" | "low"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }`
-- `"location-preference": { locationId: string; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
-- `"max-consecutive-days": { days: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
-- `"max-hours-day": { hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }`
-- `"max-hours-week": { hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; weekStartsOn?: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" | undefined; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }`
-- `"max-shifts-day": { shifts: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }`
-- `"min-consecutive-days": { days: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
-- `"min-hours-day": { hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
-- `"min-hours-week": { hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; weekStartsOn?: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" | undefined; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
-- `"min-rest-between-shifts": { hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
-- `"time-off": { priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; startTime?: { hours: number; minutes: number; } | undefined; endTime?: { hours: number; minutes: number; } | undefined; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }`
+- `"employee-assignment-priority": ({ preference: "high" | "low"; } & EntityScopeType<"employees" | "roles" | "skills">) & OptionalTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">`
+- `"location-preference": { locationId: string; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">`
+- `"max-consecutive-days": { days: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">`
+- `"max-hours-day": ({ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">) & OptionalTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">`
+- `"max-hours-week": ({ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; weekStartsOn?: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" | undefined; } & EntityScopeType<"employees" | "roles" | "skills">) & OptionalTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">`
+- `"max-shifts-day": ({ shifts: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">) & OptionalTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">`
+- `"min-consecutive-days": { days: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">`
+- `"min-hours-day": { hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">`
+- `"min-hours-week": { hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; weekStartsOn?: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" | undefined; } & EntityScopeType<"employees" | "roles" | "skills">`
+- `"min-rest-between-shifts": { hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">`
+- `"time-off": ({ priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; startTime?: { hours: number; minutes: number; } | undefined; endTime?: { hours: number; minutes: number; } | undefined; } & EntityScopeType<"employees" | "roles" | "skills">) & RequiredTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">`
 
 ### SemanticTimeDef
 Base definition for a semantic time period.
 
 **Properties:**
-- `startTime: TimeOfDay`
-- `endTime: TimeOfDay`
+- `startTime: TimeOfDay` - When this time period starts.
+- `endTime: TimeOfDay` - When this time period ends.
 
 ### SemanticTimeVariant
 Variant of a semantic time that applies to specific days or dates.
@@ -227,13 +284,18 @@ Accepts both semantic references and concrete one-off requirements.
 for the given days in the scheduling horizon.
 
 ### SchedulingEmployee
+A team member available for scheduling.
+
+Employees are assigned to shift patterns by the solver based on
+coverage requirements, rules, and constraints.
+
 **Properties:**
-- `id: string`
-- `roleIds: string[]`
-- `skillIds?: string[] | undefined`
+- `id: string` - Unique identifier for this employee. Must not contain colons.
+- `roleIds: string[]` - Roles this employee can fill (e.g. "waiter", "chef").
+- `skillIds?: string[] | undefined` - Skills this employee has (e.g. "senior", "trainer").
 
 ### ShiftPattern
-A shift pattern defines WHEN people can work — the time slots available for assignment.
+A shift pattern defines WHEN people can work: the time slots available for assignment.
 
 Shift patterns are templates that repeat across all scheduling days. The solver assigns
 team members to these patterns based on coverage requirements and constraints.
@@ -277,8 +339,8 @@ earlier than floor staff).
 ```
 - `locationId?: string | undefined` - Physical location where this shift takes place.
 Used for multi-location scheduling and location-based constraints.
-- `startTime: TimeOfDay` - When the shift starts (e.g., { hours: 9, minutes: 0 } for 9:00 AM)
-- `endTime: TimeOfDay` - When the shift ends (e.g., { hours: 17, minutes: 30 } for 5:30 PM)
+- `startTime: TimeOfDay` - When the shift starts (e.g., `{ hours: 9, minutes: 0 }` for 9:00 AM)
+- `endTime: TimeOfDay` - When the shift ends (e.g., `{ hours: 17, minutes: 30 }` for 5:30 PM)
 
 ### TimeInterval
 **Properties:**
@@ -287,9 +349,11 @@ Used for multi-location scheduling and location-based constraints.
 - `endTime: TimeOfDay`
 
 ### ModelBuilderOptions
+Optional settings for the model builder.
+
 **Properties:**
-- `weekStartsOn?: DayOfWeek | undefined`
-- `solverOptions?: { timeLimitSeconds?: number | undefined; solutionLimit?: number | undefined; } | undefined`
+- `weekStartsOn?: DayOfWeek | undefined` - Which day starts the week for weekly rules. Defaults to "monday".
+- `solverOptions?: { timeLimitSeconds?: number | undefined; solutionLimit?: number | undefined; } | undefined` - Solver-level options (time limit, solution limit).
 - `coverageBucketMinutes?: number | undefined` - Bucket size used when translating coverage requirements into time-indexed constraints.
 Smaller buckets are more accurate but increase the number of constraints.
 - `fairDistribution?: boolean | undefined` - Whether to enable fair distribution of shifts across team members.
@@ -299,7 +363,7 @@ any single person works, ensuring work is distributed evenly. Each person
 works between floor(total/n) and ceil(total/n) shifts.
 
 Disable this if you want other rules (like employee-assignment-priority)
-to have full control over shift distribution.
+to have full control over shift distribution. Defaults to true.
 
 ### ValidationReporter
 **Properties:**
@@ -467,6 +531,25 @@ Combined validation result for coverage requirements.
 - `skills: SkillValidationResult`
 - `errors: string[]` - Human-readable error messages
 
+### EntityScopeInput
+Input shape accepted by {@link parseEntityScope}.
+
+**Properties:**
+- `employeeIds?: string[] | undefined`
+- `roleIds?: string[] | undefined`
+- `skillIds?: string[] | undefined`
+- `unknown: any`
+
+### TimeScopeInput
+Input shape accepted by {@link parseTimeScope}.
+
+**Properties:**
+- `dateRange?: { start: string; end: string; } | undefined`
+- `specificDates?: string[] | undefined`
+- `dayOfWeek?: DayOfWeek[] | undefined`
+- `recurringPeriods?: RecurringPeriod[] | undefined`
+- `unknown: any`
+
 ## Type Aliases
 
 ### DayOfWeek
@@ -486,85 +569,99 @@ DateTimeWithUtcOffset | DateTimeWithTimeZone
 ```
 
 
-### SchedulingPeriod
-Defines a scheduling period either as a date range or specific dates.
-
-Use this to specify when scheduling should occur. This is more expressive
-than a simple list of days because it can filter by day-of-week.
-
-**Example:**
-Date range with day-of-week filtering (restaurant closed Mon/Tue)
-```typescript
-const period: SchedulingPeriod = {
-dateRange: { start: '2025-02-03', end: '2025-02-09' },
-daysOfWeek: ['wednesday', 'thursday', 'friday', 'saturday', 'sunday'],
-};
-```
-
-**Example:**
-Date range for all days
-```typescript
-const period: SchedulingPeriod = {
-dateRange: { start: '2025-02-03', end: '2025-02-09' },
-};
-```
-
-**Example:**
-Specific dates (non-contiguous or custom selection)
-```typescript
-const period: SchedulingPeriod = {
-specificDates: ['2025-02-05', '2025-02-07', '2025-02-10'],
-};
-```
-
-```typescript
-{ dateRange: { start: string; end: string; }; daysOfWeek?: DayOfWeek[]; specificDates?: never; } | { specificDates: string[]; dateRange?: never; daysOfWeek?: never; }
-```
+### SolverRequest
+The full request payload sent to the CP-SAT solver service.
 
+- `variables` (required): all decision variables
+- `constraints` (required): all constraints
+- `objective` (optional): optimization objective
+- `timeoutSeconds` (optional): solver time limit
 
-### SolverRequest
 ```typescript
 { variables: ({ type: "bool"; name: string; } | { type: "int"; name: string; min: number; max: number; } | { type: "interval"; name: string; start: number; end: number; size: number; presenceVar?: string | undefined; })[]; constraints: ({ type: "linear"; terms: { var: string; coeff: number; }[]; op: "<=" | ">=" | "=="; rhs: number; } | { type: "soft_linear"; terms: { var: string; coeff: number; }[]; op: "<=" | ">="; rhs: number; penalty: number; id?: string | undefined; } | { type: "exactly_one"; vars: string[]; } | { type: "at_most_one"; vars: string[]; } | { type: "implication"; if: string; then: string; } | { type: "bool_or"; vars: string[]; } | { type: "bool_and"; vars: string[]; } | { type: "no_overlap"; intervals: string[]; })[]; objective?: { sense: "minimize" | "maximize"; terms: { var: string; coeff: number; }[]; } | undefined; options?: { timeLimitSeconds?: number | undefined; solutionLimit?: number | undefined; } | undefined; }
 ```
 
 
 ### SolverResponse
+The response payload returned by the CP-SAT solver service.
+
+- `status` (required): solve outcome (see {@link SolverStatus})
+- `values` (optional): variable assignments when a solution is found
+- `statistics` (optional): solve time, conflicts, branches
+- `softViolations` (optional): which soft constraints were violated
+- `error` (optional): error message on failure
+- `solutionInfo` (optional): solver diagnostic info
+
 ```typescript
 { status: "OPTIMAL" | "FEASIBLE" | "INFEASIBLE" | "TIMEOUT" | "ERROR"; values?: Record<string, number> | undefined; statistics?: { solveTimeMs?: number | undefined; conflicts?: number | undefined; branches?: number | undefined; } | undefined; error?: string | undefined; solutionInfo?: string | undefined; softViolations?: { constraintId: string; violationAmount: number; targetValue: number; actualValue: number; }[] | undefined; }
 ```
 
 
 ### SolverVariable
+A decision variable in the CP-SAT model.
+
+- `name` (required): unique variable identifier
+- `lb` (required): lower bound
+- `ub` (required): upper bound
+- `isBoolean` (optional): whether this is a boolean variable
+- `isInterval` (optional): whether this is an interval variable
+- `start`, `end`, `size`, `presenceVar` (optional): interval variable fields
+
 ```typescript
 { type: "bool"; name: string; } | { type: "int"; name: string; min: number; max: number; } | { type: "interval"; name: string; start: number; end: number; size: number; presenceVar?: string | undefined; }
 ```
 
 
 ### SolverConstraint
+A constraint in the CP-SAT model.
+
+- `name` (required): constraint identifier
+- `type` (required): constraint kind (e.g. "linear", "bool_and", "no_overlap")
+- Additional fields vary by constraint type
+
 ```typescript
 { type: "linear"; terms: { var: string; coeff: number; }[]; op: "<=" | ">=" | "=="; rhs: number; } | { type: "soft_linear"; terms: { var: string; coeff: number; }[]; op: "<=" | ">="; rhs: number; penalty: number; id?: string | undefined; } | { type: "exactly_one"; vars: string[]; } | { type: "at_most_one"; vars: string[]; } | { type: "implication"; if: string; then: string; } | { type: "bool_or"; vars: string[]; } | { type: "bool_and"; vars: string[]; } | { type: "no_overlap"; intervals: string[]; }
 ```
 
 
 ### SolverTerm
+A single linear term in a constraint or objective.
+
+- `var` (required): variable name
+- `coeff` (required): integer coefficient
+
 ```typescript
 { var: string; coeff: number; }
 ```
 
 
 ### SolverObjective
+An optimization objective for the solver.
+
+- `terms` (required): linear terms to minimize/maximize
+- `minimize` (required): whether to minimize (true) or maximize (false)
+
 ```typescript
 { sense: "minimize" | "maximize"; terms: { var: string; coeff: number; }[]; }
 ```
 
 
 ### SolverStatus
+Solver outcome status.
+
+One of `"OPTIMAL"`, `"FEASIBLE"`, `"INFEASIBLE"`, `"TIMEOUT"`, or `"ERROR"`.
+
 ```typescript
 "OPTIMAL" | "FEASIBLE" | "INFEASIBLE" | "TIMEOUT" | "ERROR"
 ```
 
 
 ### SoftConstraintViolation
+A soft constraint violation reported by the solver.
+
+- `constraintId` (required): which soft constraint was violated
+- `violationAmount` (required): magnitude of the violation
+
 ```typescript
 { constraintId: string; violationAmount: number; targetValue: number; actualValue: number; }
 ```
@@ -576,75 +673,214 @@ specificDates: ['2025-02-05', '2025-02-07', '2025-02-10'],
 ```
 
 
+### EntityScopeType
+Entity scope type for a subset of entity keys (at most one).
+
+```typescript
+ExclusiveOne<ActiveEntityFields, InactiveEntityFields, K> | MergeValues<Pick<InactiveEntityFields, K>>
+```
+
+
+### OptionalTimeScopeType
+Time scope type for a subset of time keys (at most one, optional).
+
+```typescript
+ExclusiveOne<ActiveTimeFields, InactiveTimeFields, K> | MergeValues<Pick<InactiveTimeFields, K>>
+```
+
+
+### RequiredTimeScopeType
+Time scope type for a subset of time keys (exactly one, required).
+
+```typescript
+{ [K in K]: ActiveTimeFields[K] & MergeValues<Pick<InactiveTimeFields, Exclude<K, K>>>; }[K]
+```
+
+
+### ParsedEntityScope
+Parsed entity scope from a flat config.
+Used internally by scope resolution functions.
+
+```typescript
+{ type: "global"; } | { type: "employees"; employeeIds: string[]; } | { type: "roles"; roleIds: string[]; } | { type: "skills"; skillIds: string[]; }
+```
+
+
+### ParsedTimeScope
+Parsed time scope from a flat config.
+Used internally by scope resolution functions.
+
+```typescript
+{ type: "none"; } | { type: "dateRange"; start: string; end: string; } | { type: "specificDates"; dates: string[]; } | { type: "dayOfWeek"; days: DayOfWeek[]; } | { type: "recurring"; periods: RecurringPeriod[]; }
+```
+
+
 ### AssignTogetherConfig
+Configuration for {@link createAssignTogetherRule}.
+
+- `groupEmployeeIds` (required): employee IDs to assign together (at least two, must be unique)
+- `priority` (required): how strictly the solver enforces this rule
+
 ```typescript
 { groupEmployeeIds: [string, string, ...string[]]; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; }
 ```
 
 
 ### EmployeeAssignmentPriorityConfig
+Configuration for {@link createEmployeeAssignmentPriorityRule}.
+
+- `preference` (required): `"high"` to prefer assigning or `"low"` to avoid assigning
+
+Entity scoping (at most one): `employeeIds`, `roleIds`, `skillIds`
+Time scoping (at most one, optional): `dateRange`, `specificDates`, `dayOfWeek`, `recurringPeriods`
+
 ```typescript
-{ preference: "high" | "low"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }
+({ preference: "high" | "low"; } & EntityScopeType<"employees" | "roles" | "skills">) & OptionalTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">
 ```
 
 
 ### LocationPreferenceConfig
+Configuration for {@link createLocationPreferenceRule}.
+
+- `locationId` (required): the location ID to prefer for matching shift patterns
+- `priority` (required): how strongly to prefer this location
+
+Entity scoping (at most one): `employeeIds`, `roleIds`, `skillIds`
+
 ```typescript
-{ locationId: string; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }
+{ locationId: string; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">
 ```
 
 
 ### MaxConsecutiveDaysConfig
+Configuration for {@link createMaxConsecutiveDaysRule}.
+
+- `days` (required): maximum consecutive days allowed
+- `priority` (required): how strictly the solver enforces this rule
+
+Entity scoping (at most one): `employeeIds`, `roleIds`, `skillIds`
+
 ```typescript
-{ days: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }
+{ days: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">
 ```
 
 
 ### MaxHoursDayConfig
+Configuration for {@link createMaxHoursDayRule}.
+
+- `hours` (required): maximum hours allowed per day
+- `priority` (required): how strictly the solver enforces this rule
+
+Entity scoping (at most one): `employeeIds`, `roleIds`, `skillIds`
+Time scoping (at most one, optional): `dateRange`, `specificDates`, `dayOfWeek`, `recurringPeriods`
+
 ```typescript
-{ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }
+({ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">) & OptionalTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">
 ```
 
 
 ### MaxHoursWeekConfig
+Configuration for {@link createMaxHoursWeekRule}.
+
+- `hours` (required): maximum hours 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): `employeeIds`, `roleIds`, `skillIds`
+Time scoping (at most one, optional): `dateRange`, `specificDates`, `dayOfWeek`, `recurringPeriods`
+
 ```typescript
-{ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; weekStartsOn?: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" | undefined; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }
+({ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; weekStartsOn?: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" | undefined; } & EntityScopeType<"employees" | "roles" | "skills">) & OptionalTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">
 ```
 
 
 ### MaxShiftsDayConfig
+Configuration for {@link createMaxShiftsDayRule}.
+
+- `shifts` (required): maximum number of shifts per day (at least 1)
+- `priority` (required): how strictly the solver enforces this rule
+
+Entity scoping (at most one): `employeeIds`, `roleIds`, `skillIds`
+Time scoping (at most one, optional): `dateRange`, `specificDates`, `dayOfWeek`, `recurringPeriods`
+
 ```typescript
-{ shifts: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }
+({ shifts: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">) & OptionalTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">
 ```
 
 
 ### MinConsecutiveDaysConfig
+Configuration for {@link createMinConsecutiveDaysRule}.
+
+- `days` (required): minimum consecutive days required once a person starts working
+- `priority` (required): how strictly the solver enforces this rule
+
+Entity scoping (at most one): `employeeIds`, `roleIds`, `skillIds`
+
 ```typescript
-{ days: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }
+{ days: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">
 ```
 
 
 ### MinHoursDayConfig
+Configuration for {@link createMinHoursDayRule}.
+
+- `hours` (required): minimum hours required per day when scheduled
+- `priority` (required): how strictly the solver enforces this rule
+
+Entity scoping (at most one): `employeeIds`, `roleIds`, `skillIds`
+
 ```typescript
-{ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }
+{ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">
 ```
 
 
 ### MinHoursWeekConfig
+Configuration for {@link createMinHoursWeekRule}.
+
+- `hours` (required): minimum hours 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): `employeeIds`, `roleIds`, `skillIds`
+
 ```typescript
-{ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; weekStartsOn?: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" | undefined; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }
+{ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; weekStartsOn?: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" | undefined; } & EntityScopeType<"employees" | "roles" | "skills">
 ```
 
 
 ### MinRestBetweenShiftsConfig
+Configuration for {@link createMinRestBetweenShiftsRule}.
+
+- `hours` (required): minimum rest hours required between consecutive shifts
+- `priority` (required): how strictly the solver enforces this rule
+
+Entity scoping (at most one): `employeeIds`, `roleIds`, `skillIds`
+
 ```typescript
-{ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }
+{ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">
 ```
 
 
 ### TimeOffConfig
+Configuration for {@link createTimeOffRule}.
+
+- `priority` (required): how strictly the solver enforces this rule
+- `startTime` (optional): start of the time-off window within each day; must be paired with `endTime`
+- `endTime` (optional): end of the time-off window within each day; must be paired with `startTime`
+
+Entity scoping (at most one):
+- `employeeIds`: restrict to specific employees
+- `roleIds`: restrict to employees with matching roles
+- `skillIds`: restrict to employees with matching skills
+
+Time scoping (exactly one required):
+- `dateRange`: contiguous date range
+- `specificDates`: specific dates
+- `dayOfWeek`: days of the week
+- `recurringPeriods`: recurring calendar periods
+
 ```typescript
-{ priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; startTime?: { hours: number; minutes: number; } | undefined; endTime?: { hours: number; minutes: number; } | undefined; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }
+({ priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; startTime?: { hours: number; minutes: number; } | undefined; endTime?: { hours: number; minutes: number; } | undefined; } & EntityScopeType<"employees" | "roles" | "skills">) & RequiredTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">
 ```
 
 
@@ -763,6 +999,11 @@ RoleBasedCoverageRequirement | SkillBasedCoverageRequirement
 
 
 ### Priority
+How strictly the solver enforces a rule.
+
+- `"LOW"`, `"MEDIUM"`, `"HIGH"`: soft constraints with increasing penalty for violations
+- `"MANDATORY"`: hard constraint; the solver will not produce a solution that violates it
+
 ```typescript
 "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"
 ```
@@ -795,6 +1036,42 @@ string & { readonly [GroupKeyBrand]: never; }
 ```
 
 
+### EntityKey
+```typescript
+"employees" | "roles" | "skills"
+```
+
+
+### TimeKey
+```typescript
+"dateRange" | "specificDates" | "dayOfWeek" | "recurring"
+```
+
+
+### ExclusiveOne
+Exactly one of the specified keys must be present.
+The active key's field is required; all others are `?: never`.
+
+**Example:**
+ExclusiveOne<ActiveEntityFields, InactiveEntityFields, "employees" | "roles">
+=
+  | { employeeIds: [string, ...string[]]; roleIds?: never }
+  | { roleIds: [string, ...string[]]; employeeIds?: never }
+
+```typescript
+{ [K in Keys]: Active[K] & MergeValues<Pick<Inactive, Exclude<Keys, K>>>; }[Keys]
+```
+
+
+### MaybeOne
+At most one of the specified keys may be present (or none).
+Same as {@link ExclusiveOne} plus the case where all fields are `?: never`.
+
+```typescript
+ExclusiveOne<Active, Inactive, Keys> | MergeValues<Pick<Inactive, Keys>>
+```
+
+
 ### InferCpsatRuleConfig
 ```typescript
 T extends CreateCpsatRuleFunction<infer Config> ? Config : never
@@ -1014,41 +1291,41 @@ daysBetween(new Date('2025-01-01'), new Date('2025-01-05')); // 4
 ### resolveDaysFromPeriod
 Computes the list of day strings (YYYY-MM-DD) from a SchedulingPeriod.
 
-For date ranges, generates all days between start and end (inclusive),
-optionally filtering to specific days of the week.
-
-For specific dates, returns the dates as-is (sorted).
+Generates all days between start and end (inclusive), applying optional
+daysOfWeek and dates filters. Filters compose: a day must pass all
+specified filters to be included.
 
 **Example:**
-Date range with day-of-week filter
+All days in range
 ```typescript
 const days = resolveDaysFromPeriod({
-dateRange: { start: '2025-02-03', end: '2025-02-09' },
-daysOfWeek: ['wednesday', 'friday'],
+dateRange: { start: '2025-02-03', end: '2025-02-05' },
 });
-// Returns: ['2025-02-05', '2025-02-07'] (Wed and Fri only)
+// Returns: ['2025-02-03', '2025-02-04', '2025-02-05']
 ```
 
 **Example:**
-Date range without filter
+Day-of-week filter
 ```typescript
 const days = resolveDaysFromPeriod({
-dateRange: { start: '2025-02-03', end: '2025-02-05' },
+dateRange: { start: '2025-02-03', end: '2025-02-09' },
+daysOfWeek: ['wednesday', 'friday'],
 });
-// Returns: ['2025-02-03', '2025-02-04', '2025-02-05']
+// Returns: ['2025-02-05', '2025-02-07']
 ```
 
 **Example:**
-Specific dates
+Specific dates filter
 ```typescript
 const days = resolveDaysFromPeriod({
-specificDates: ['2025-02-07', '2025-02-03', '2025-02-10'],
+dateRange: { start: '2025-02-03', end: '2025-02-10' },
+dates: ['2025-02-05', '2025-02-07'],
 });
-// Returns: ['2025-02-03', '2025-02-07', '2025-02-10'] (sorted)
+// Returns: ['2025-02-05', '2025-02-07']
 ```
 
 **Parameters:**
-- `period: { dateRange: { start: string; end: string; }; daysOfWeek?: DayOfWeek[]; specificDates?: never; } | { specificDates: string[]; dateRange?: never; daysOfWeek?: never; }`
+- `period: SchedulingPeriod`
 
 **Returns:** `string[]`
 
@@ -1122,9 +1399,6 @@ builder = new ModelBuilder({ ...config, rules: [rule] });
 ### createEmployeeAssignmentPriorityRule
 Adds objective weight to prefer or avoid assigning team members.
 
-Supports entity scoping (people, roles, skills) and time scoping
-(date ranges, specific dates, days of week, recurring periods).
-
 **Example:**
 Prefer specific team members
 ```ts
@@ -1144,18 +1418,8 @@ preference: "low",
 });
 ```
 
-**Example:**
-Prefer experienced staff on weekends
-```ts
-createEmployeeAssignmentPriorityRule({
-skillIds: ["senior"],
-dayOfWeek: ["saturday", "sunday"],
-preference: "high",
-});
-```
-
 **Parameters:**
-- `config: { preference: "high" | "low"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }`
+- `config: ({ preference: "high" | "low"; } & EntityScopeType<"employees" | "roles" | "skills">) & OptionalTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">`
 
 **Returns:** `CompilationRule`
 
@@ -1165,16 +1429,15 @@ Prefers assigning a person to shift patterns matching a specific location.
 
 **Example:**
 ```ts
-const rule = createLocationPreferenceRule({
+createLocationPreferenceRule({
   locationId: "terrace",
   priority: "HIGH",
   employeeIds: ["alice"],
 });
-builder = new ModelBuilder({ ...config, rules: [rule] });
 ```
 
 **Parameters:**
-- `config: { locationId: string; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
+- `config: { locationId: string; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">`
 
 **Returns:** `CompilationRule`
 
@@ -1184,15 +1447,11 @@ Limits how many consecutive days a person can be assigned.
 
 **Example:**
 ```ts
-const rule = createMaxConsecutiveDaysRule({
-  days: 5,
-  priority: "MANDATORY",
-});
-builder = new ModelBuilder({ ...config, rules: [rule] });
+createMaxConsecutiveDaysRule({ days: 5, priority: "MANDATORY" });
 ```
 
 **Parameters:**
-- `config: { days: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
+- `config: { days: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">`
 
 **Returns:** `CompilationRule`
 
@@ -1200,9 +1459,6 @@ builder = new ModelBuilder({ ...config, rules: [rule] });
 ### createMaxHoursDayRule
 Limits how many hours a person can work in a single day.
 
-Supports entity scoping (people, roles, skills) and time scoping
-(date ranges, specific dates, days of week, recurring periods).
-
 **Example:**
 Limit everyone to 8 hours per day
 ```ts
@@ -1224,7 +1480,7 @@ priority: "MANDATORY",
 ```
 
 **Parameters:**
-- `config: { hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }`
+- `config: ({ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">) & OptionalTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">`
 
 **Returns:** `CompilationRule`
 
@@ -1232,17 +1488,10 @@ priority: "MANDATORY",
 ### createMaxHoursWeekRule
 Caps total hours a person can work within each scheduling week.
 
-Supports entity scoping (people, roles, skills) and time scoping
-(date ranges, specific dates, days of week, recurring periods).
-Time scoping filters which days within each week count toward the limit.
-
 **Example:**
 Limit everyone to 40 hours per week
 ```ts
-createMaxHoursWeekRule({
-hours: 40,
-priority: "HIGH",
-});
+createMaxHoursWeekRule({ hours: 40, priority: "HIGH" });
 ```
 
 **Example:**
@@ -1253,14 +1502,13 @@ roleIds: ["student"],
 hours: 20,
 recurringPeriods: [
 { name: "fall-term", startMonth: 9, startDay: 1, endMonth: 12, endDay: 15 },
-{ name: "spring-term", startMonth: 1, startDay: 15, endMonth: 5, endDay: 31 },
 ],
 priority: "MANDATORY",
 });
 ```
 
 **Parameters:**
-- `config: { hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; weekStartsOn?: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" | undefined; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }`
+- `config: ({ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; weekStartsOn?: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" | undefined; } & EntityScopeType<"employees" | "roles" | "skills">) & OptionalTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">`
 
 **Returns:** `CompilationRule`
 
@@ -1268,14 +1516,11 @@ priority: "MANDATORY",
 ### createMaxShiftsDayRule
 Limits how many shifts a person can work in a single day.
 
-This rule controls the maximum number of distinct shift assignments per day,
+Controls the maximum number of distinct shift assignments per day,
 regardless of shift duration. For limiting total hours worked, use `max-hours-day`.
 
-Supports entity scoping (people, roles, skills) and time scoping
-(date ranges, specific dates, days of week, recurring periods).
-
 **Example:**
-Limit to one shift per day (common for most schedules)
+Limit to one shift per day
 ```ts
 createMaxShiftsDayRule({
 shifts: 1,
@@ -1283,16 +1528,6 @@ priority: "MANDATORY",
 });
 ```
 
-**Example:**
-Allow up to two shifts per day for part-time workers
-```ts
-createMaxShiftsDayRule({
-roleIds: ["part-time"],
-shifts: 2,
-priority: "HIGH",
-});
-```
-
 **Example:**
 Students can work 2 shifts on weekends only
 ```ts
@@ -1305,7 +1540,7 @@ priority: "MANDATORY",
 ```
 
 **Parameters:**
-- `config: { shifts: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }`
+- `config: ({ shifts: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">) & OptionalTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">`
 
 **Returns:** `CompilationRule`
 
@@ -1316,15 +1551,11 @@ number of consecutive days.
 
 **Example:**
 ```ts
-const rule = createMinConsecutiveDaysRule({
-  days: 3,
-  priority: "MANDATORY",
-});
-builder = new ModelBuilder({ ...config, rules: [rule] });
+createMinConsecutiveDaysRule({ days: 3, priority: "MANDATORY" });
 ```
 
 **Parameters:**
-- `config: { days: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
+- `config: { days: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">`
 
 **Returns:** `CompilationRule`
 
@@ -1334,15 +1565,11 @@ Ensures a person works at least a minimum number of hours per day.
 
 **Example:**
 ```ts
-const rule = createMinHoursDayRule({
-  hours: 6,
-  priority: "MANDATORY",
-});
-builder = new ModelBuilder({ ...config, rules: [rule] });
+createMinHoursDayRule({ hours: 6, priority: "MANDATORY" });
 ```
 
 **Parameters:**
-- `config: { hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
+- `config: { hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">`
 
 **Returns:** `CompilationRule`
 
@@ -1352,15 +1579,11 @@ Enforces a minimum total number of hours per scheduling week.
 
 **Example:**
 ```ts
-const rule = createMinHoursWeekRule({
-  hours: 30,
-  priority: "HIGH",
-});
-builder = new ModelBuilder({ ...config, rules: [rule] });
+createMinHoursWeekRule({ hours: 30, priority: "HIGH" });
 ```
 
 **Parameters:**
-- `config: { hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; weekStartsOn?: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" | undefined; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
+- `config: { hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; weekStartsOn?: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" | undefined; } & EntityScopeType<"employees" | "roles" | "skills">`
 
 **Returns:** `CompilationRule`
 
@@ -1370,15 +1593,11 @@ Enforces a minimum rest period between any two shifts a person works.
 
 **Example:**
 ```ts
-const rule = createMinRestBetweenShiftsRule({
-  hours: 10,
-  priority: "MANDATORY",
-});
-builder = new ModelBuilder({ ...config, rules: [rule] });
+createMinRestBetweenShiftsRule({ hours: 10, priority: "MANDATORY" });
 ```
 
 **Parameters:**
-- `config: { hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
+- `config: { hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">`
 
 **Returns:** `CompilationRule`
 
@@ -1425,7 +1644,7 @@ priority: "MANDATORY",
 ```
 
 **Parameters:**
-- `config: { priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; startTime?: { hours: number; minutes: number; } | undefined; endTime?: { hours: number; minutes: number; } | undefined; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }`
+- `config: ({ priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; startTime?: { hours: number; minutes: number; } | undefined; endTime?: { hours: number; minutes: number; } | undefined; } & EntityScopeType<"employees" | "roles" | "skills">) & RequiredTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">`
 
 **Returns:** `CompilationRule`
 
@@ -1666,6 +1885,98 @@ Always includes range start. Sorted ascending.
 **Returns:** `number[]`
 
 
+### entityScope
+Creates a Zod schema for optional entity scoping (at most one of the
+specified entity variants).
+
+The returned schema accepts flat fields (`employeeIds`, `roleIds`, `skillIds`)
+but the TypeScript type enforces mutual exclusivity via `?: never`.
+
+**Example:**
+```ts
+// Supports all entity scopes
+entityScope(["employees", "roles", "skills"])
+
+// Only employee scoping
+entityScope(["employees"])
+```
+
+**Parameters:**
+- `keys: K`
+
+**Returns:** `z.ZodType<EntityScopeType<K[number]>, unknown, z.core.$ZodTypeInternals<EntityScopeType<K[number]>, unknown>>`
+
+
+### timeScope
+Creates a Zod schema for optional time scoping (at most one of the
+specified time variants, or none).
+
+**Example:**
+```ts
+// Supports all time scopes, all optional
+timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"])
+```
+
+**Parameters:**
+- `keys: K`
+
+**Returns:** `z.ZodType<OptionalTimeScopeType<K[number]>, unknown, z.core.$ZodTypeInternals<OptionalTimeScopeType<K[number]>, unknown>>`
+
+
+### requiredTimeScope
+Creates a Zod schema for required time scoping (exactly one of the
+specified time variants must be present).
+
+**Example:**
+```ts
+// Exactly one time scope required (for time-off)
+requiredTimeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"])
+```
+
+**Parameters:**
+- `keys: K`
+
+**Returns:** `z.ZodType<RequiredTimeScopeType<K[number]>, unknown, z.core.$ZodTypeInternals<RequiredTimeScopeType<K[number]>, unknown>>`
+
+
+### parseEntityScope
+Extracts the entity scope from a parsed flat config.
+
+**Parameters:**
+- `config: EntityScopeInput`
+
+**Returns:** `{ type: "global"; } | { type: "employees"; employeeIds: string[]; } | { type: "roles"; roleIds: string[]; } | { type: "skills"; skillIds: string[]; }`
+
+
+### parseTimeScope
+Extracts the time scope from a parsed flat config.
+
+**Parameters:**
+- `config: TimeScopeInput`
+
+**Returns:** `{ type: "none"; } | { type: "dateRange"; start: string; end: string; } | { type: "specificDates"; dates: string[]; } | { type: "dayOfWeek"; days: DayOfWeek[]; } | { type: "recurring"; periods: RecurringPeriod[]; }`
+
+
+### resolveEmployeesFromScope
+Resolves which employees a rule applies to based on entity scope.
+
+**Parameters:**
+- `scope: { type: "global"; } | { type: "employees"; employeeIds: string[]; } | { type: "roles"; roleIds: string[]; } | { type: "skills"; skillIds: string[]; }`
+- `employees: SchedulingEmployee[]`
+
+**Returns:** `SchedulingEmployee[]`
+
+
+### resolveActiveDaysFromScope
+Resolves which days a rule applies to based on time scope.
+
+**Parameters:**
+- `scope: { type: "none"; } | { type: "dateRange"; start: string; end: string; } | { type: "specificDates"; dates: string[]; } | { type: "dayOfWeek"; days: DayOfWeek[]; } | { type: "recurring"; periods: RecurringPeriod[]; }`
+- `allDays: string[]`
+
+**Returns:** `string[]`
+
+
 ### parseDayString
 Parse a day string (YYYY-MM-DD) to a UTC Date.
 Used internally for day-of-week calculations and date comparisons.
@@ -1747,6 +2058,10 @@ Useful for rule configs that need to accept a day-of-week string.
 **Type:** `z.ZodObject<{ status: z.ZodEnum<{ OPTIMAL: "OPTIMAL"; FEASIBLE: "FEASIBLE"; INFEASIBLE: "INFEASIBLE"; TIMEOUT: "TIMEOUT"; ERROR: "ERROR"; }>; values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>; statistics: z.ZodOptional<z.ZodObject<{ solveTimeMs: z.ZodOptional<z.ZodNumber>; conflicts: z.ZodOptional<z.ZodNumber>; branches: z.ZodOptional<z.ZodNumber>; }, z.core.$strip>>; error: z.ZodOptional<z.ZodString>; solutionInfo: z.ZodOptional<z.ZodString>; softViolations: z.ZodOptional<z.ZodArray<z.ZodObject<{ constraintId: z.ZodString; violationAmount: z.ZodNumber; targetValue: z.ZodNumber; actualValue: z.ZodNumber; }, z.core.$strip>>>; }, z.core.$strip>`
 
 
+### SolverStatusSchema
+**Type:** `z.ZodEnum<{ OPTIMAL: "OPTIMAL"; FEASIBLE: "FEASIBLE"; INFEASIBLE: "INFEASIBLE"; TIMEOUT: "TIMEOUT"; ERROR: "ERROR"; }>`
+
+
 ### builtInCpsatRuleFactories
 **Type:** `[Complex type: __type]`
 
@@ -1767,7 +2082,7 @@ Weight hierarchy (highest to lowest priority):
 **Example:**
 Using weights in a custom rule
 ```ts
-import { OBJECTIVE_WEIGHTS } from "feasible";
+import { OBJECTIVE_WEIGHTS } from "dabke";
 
 // Prefer senior staff with same weight as employee-assignment-priority
 b.addPenalty(assignment, -OBJECTIVE_WEIGHTS.ASSIGNMENT_PREFERENCE);
@@ -1847,10 +2162,6 @@ b.addPenalty(assignment, -2 * OBJECTIVE_WEIGHTS.ASSIGNMENT_PREFERENCE);
 **Type:** `z.ZodObject<{ timeLimitSeconds: z.ZodOptional<z.ZodNumber>; solutionLimit: z.ZodOptional<z.ZodNumber>; }, z.core.$strip>`
 
 
-### SolverStatusSchema
-**Type:** `z.ZodEnum<{ OPTIMAL: "OPTIMAL"; FEASIBLE: "FEASIBLE"; INFEASIBLE: "INFEASIBLE"; TIMEOUT: "TIMEOUT"; ERROR: "ERROR"; }>`
-
-
 ### SolverStatisticsSchema
 **Type:** `z.ZodObject<{ solveTimeMs: z.ZodOptional<z.ZodNumber>; conflicts: z.ZodOptional<z.ZodNumber>; branches: z.ZodOptional<z.ZodNumber>; }, z.core.$strip>`
 
@@ -1892,9 +2203,6 @@ builder = new ModelBuilder({ ...config, rules: [rule] });
 
 Adds objective weight to prefer or avoid assigning team members.
 
-Supports entity scoping (people, roles, skills) and time scoping
-(date ranges, specific dates, days of week, recurring periods).
-
 **Example:**
 Prefer specific team members
 ```ts
@@ -1914,17 +2222,7 @@ preference: "low",
 });
 ```
 
-**Example:**
-Prefer experienced staff on weekends
-```ts
-createEmployeeAssignmentPriorityRule({
-skillIds: ["senior"],
-dayOfWeek: ["saturday", "sunday"],
-preference: "high",
-});
-```
-
-**Config:** `{ preference: "high" | "low"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }`
+**Config:** `({ preference: "high" | "low"; } & EntityScopeType<"employees" | "roles" | "skills">) & OptionalTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">`
 
 ### location-preference
 
@@ -1934,15 +2232,14 @@ Prefers assigning a person to shift patterns matching a specific location.
 
 **Example:**
 ```ts
-const rule = createLocationPreferenceRule({
+createLocationPreferenceRule({
   locationId: "terrace",
   priority: "HIGH",
   employeeIds: ["alice"],
 });
-builder = new ModelBuilder({ ...config, rules: [rule] });
 ```
 
-**Config:** `{ locationId: string; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
+**Config:** `{ locationId: string; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">`
 
 ### max-consecutive-days
 
@@ -1952,14 +2249,10 @@ Limits how many consecutive days a person can be assigned.
 
 **Example:**
 ```ts
-const rule = createMaxConsecutiveDaysRule({
-  days: 5,
-  priority: "MANDATORY",
-});
-builder = new ModelBuilder({ ...config, rules: [rule] });
+createMaxConsecutiveDaysRule({ days: 5, priority: "MANDATORY" });
 ```
 
-**Config:** `{ days: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
+**Config:** `{ days: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">`
 
 ### max-hours-day
 
@@ -1967,9 +2260,6 @@ builder = new ModelBuilder({ ...config, rules: [rule] });
 
 Limits how many hours a person can work in a single day.
 
-Supports entity scoping (people, roles, skills) and time scoping
-(date ranges, specific dates, days of week, recurring periods).
-
 **Example:**
 Limit everyone to 8 hours per day
 ```ts
@@ -1990,7 +2280,7 @@ priority: "MANDATORY",
 });
 ```
 
-**Config:** `{ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }`
+**Config:** `({ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">) & OptionalTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">`
 
 ### max-hours-week
 
@@ -1998,17 +2288,10 @@ priority: "MANDATORY",
 
 Caps total hours a person can work within each scheduling week.
 
-Supports entity scoping (people, roles, skills) and time scoping
-(date ranges, specific dates, days of week, recurring periods).
-Time scoping filters which days within each week count toward the limit.
-
 **Example:**
 Limit everyone to 40 hours per week
 ```ts
-createMaxHoursWeekRule({
-hours: 40,
-priority: "HIGH",
-});
+createMaxHoursWeekRule({ hours: 40, priority: "HIGH" });
 ```
 
 **Example:**
@@ -2019,13 +2302,12 @@ roleIds: ["student"],
 hours: 20,
 recurringPeriods: [
 { name: "fall-term", startMonth: 9, startDay: 1, endMonth: 12, endDay: 15 },
-{ name: "spring-term", startMonth: 1, startDay: 15, endMonth: 5, endDay: 31 },
 ],
 priority: "MANDATORY",
 });
 ```
 
-**Config:** `{ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; weekStartsOn?: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" | undefined; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }`
+**Config:** `({ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; weekStartsOn?: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" | undefined; } & EntityScopeType<"employees" | "roles" | "skills">) & OptionalTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">`
 
 ### max-shifts-day
 
@@ -2033,14 +2315,11 @@ priority: "MANDATORY",
 
 Limits how many shifts a person can work in a single day.
 
-This rule controls the maximum number of distinct shift assignments per day,
+Controls the maximum number of distinct shift assignments per day,
 regardless of shift duration. For limiting total hours worked, use `max-hours-day`.
 
-Supports entity scoping (people, roles, skills) and time scoping
-(date ranges, specific dates, days of week, recurring periods).
-
 **Example:**
-Limit to one shift per day (common for most schedules)
+Limit to one shift per day
 ```ts
 createMaxShiftsDayRule({
 shifts: 1,
@@ -2048,16 +2327,6 @@ priority: "MANDATORY",
 });
 ```
 
-**Example:**
-Allow up to two shifts per day for part-time workers
-```ts
-createMaxShiftsDayRule({
-roleIds: ["part-time"],
-shifts: 2,
-priority: "HIGH",
-});
-```
-
 **Example:**
 Students can work 2 shifts on weekends only
 ```ts
@@ -2069,7 +2338,7 @@ priority: "MANDATORY",
 });
 ```
 
-**Config:** `{ shifts: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }`
+**Config:** `({ shifts: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">) & OptionalTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">`
 
 ### min-consecutive-days
 
@@ -2080,14 +2349,10 @@ number of consecutive days.
 
 **Example:**
 ```ts
-const rule = createMinConsecutiveDaysRule({
-  days: 3,
-  priority: "MANDATORY",
-});
-builder = new ModelBuilder({ ...config, rules: [rule] });
+createMinConsecutiveDaysRule({ days: 3, priority: "MANDATORY" });
 ```
 
-**Config:** `{ days: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
+**Config:** `{ days: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">`
 
 ### min-hours-day
 
@@ -2097,14 +2362,10 @@ Ensures a person works at least a minimum number of hours per day.
 
 **Example:**
 ```ts
-const rule = createMinHoursDayRule({
-  hours: 6,
-  priority: "MANDATORY",
-});
-builder = new ModelBuilder({ ...config, rules: [rule] });
+createMinHoursDayRule({ hours: 6, priority: "MANDATORY" });
 ```
 
-**Config:** `{ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
+**Config:** `{ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">`
 
 ### min-hours-week
 
@@ -2114,14 +2375,10 @@ Enforces a minimum total number of hours per scheduling week.
 
 **Example:**
 ```ts
-const rule = createMinHoursWeekRule({
-  hours: 30,
-  priority: "HIGH",
-});
-builder = new ModelBuilder({ ...config, rules: [rule] });
+createMinHoursWeekRule({ hours: 30, priority: "HIGH" });
 ```
 
-**Config:** `{ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; weekStartsOn?: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" | undefined; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
+**Config:** `{ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; weekStartsOn?: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" | undefined; } & EntityScopeType<"employees" | "roles" | "skills">`
 
 ### min-rest-between-shifts
 
@@ -2131,14 +2388,10 @@ Enforces a minimum rest period between any two shifts a person works.
 
 **Example:**
 ```ts
-const rule = createMinRestBetweenShiftsRule({
-  hours: 10,
-  priority: "MANDATORY",
-});
-builder = new ModelBuilder({ ...config, rules: [rule] });
+createMinRestBetweenShiftsRule({ hours: 10, priority: "MANDATORY" });
 ```
 
-**Config:** `{ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; }`
+**Config:** `{ hours: number; priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; } & EntityScopeType<"employees" | "roles" | "skills">`
 
 ### time-off
 
@@ -2184,5 +2437,5 @@ priority: "MANDATORY",
 });
 ```
 
-**Config:** `{ priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; startTime?: { hours: number; minutes: number; } | undefined; endTime?: { hours: number; minutes: number; } | undefined; employeeIds?: string[] | undefined; roleIds?: string[] | undefined; skillIds?: string[] | undefined; dateRange?: { start: string; end: string; } | undefined; specificDates?: string[] | undefined; dayOfWeek?: ("monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday")[] | undefined; recurringPeriods?: { name: string; startMonth: number; startDay: number; endMonth: number; endDay: number; }[] | undefined; }`
+**Config:** `({ priority: "LOW" | "MEDIUM" | "HIGH" | "MANDATORY"; startTime?: { hours: number; minutes: number; } | undefined; endTime?: { hours: number; minutes: number; } | undefined; } & EntityScopeType<"employees" | "roles" | "skills">) & RequiredTimeScopeType<"dateRange" | "specificDates" | "dayOfWeek" | "recurring">`