dabke 0.83.0 → 0.84.0

package/src/schedule/rules.ts

@@ -1,12 +1,71 @@
 /**
  * Scheduling rules: constraints, preferences, and time-off.
  *
+ * Rules answer "what schedules are allowed or preferred?". Use
+ * {@link cover} for lower-bound demand, then use rules for caps, limits, rest
+ * periods, time off, fairness, and other constraints on assignments.
+ *
+ * @example
+ * ```typescript
+ * rules: [
+ *   // Hour and day limits
+ *   maxHoursPerDay(10),
+ *   maxHoursPerWeek(48),
+ *   maxHoursPerWeek(20, { appliesTo: "part-time" }),
+ *   maxDaysPerWeek(5, { priority: "HIGH" }),
+ *   targetDaysPerWeek(4, { appliesTo: "full-time", priority: "HIGH" }),
+ *   minDaysPerWeek(4, { appliesTo: "full-time", priority: "HIGH" }),
+ *   maxShiftsPerDay(1),
+ *   maxConcurrentAssignments(5, { appliesTo: "chair_stylist" }),
+ *   targetPeakConcurrentAssignments(5, { appliesTo: "chair_stylist", dayOfWeek: ["thursday"], priority: "HIGH" }),
+ *   minRestBetweenShifts(11),
+ *
+ *   // Staffing obligations and preferences
+ *   mustAssign({ appliesTo: ["diana", "yavuz"] }),
+ *   timeOff({ appliesTo: "alice", dateRange: { start: "2024-02-01", end: "2024-02-05" } }),
+ *   timeOff({ appliesTo: "student", dayOfWeek: ["wednesday"], from: t(14) }),
+ *   preferAssignment({ appliesTo: "waiter" }),
+ *   avoidAssignment({ appliesTo: "student", dayOfWeek: weekdays }),
+ *   assignTogether(["alice", "bob"]),
+ * ]
+ * ```
+ *
+ * Custom rules can stay type-safe too:
+ *
+ * ```typescript
+ * const debugRuleRegistry = createCpsatRuleRegistry({
+ *   debug: defineRuleDescriptor({
+ *     name: "debug",
+ *     schema: z.object({ flag: z.boolean() }),
+ *     compile() {
+ *       return { rule: "debug", artifacts: [] };
+ *     },
+ *   }),
+ * });
+ *
+ * const defineDebugRule = defineRuleFor(debugRuleRegistry);
+ *
+ * schedule({
+ *   roleIds: ["waiter"],
+ *   times: { lunch: time({ startTime: t(12), endTime: t(15) }) },
+ *   coverage: [cover("lunch", "waiter", 1)],
+ *   shiftPatterns: [shift("lunch", t(12), t(15))],
+ *   ruleRegistry: debugRuleRegistry,
+ *   rules: [defineDebugRule("debug", { flag: true })],
+ * });
+ * ```
+ *
  * @module
  */
 
 import type { DayOfWeek, TimeOfDay } from "../types.js";
-import type { Priority } from "../cpsat/types.js";
-import type { CpsatRuleName, CpsatRuleConfigEntry } from "../cpsat/rules/rules.types.js";
+import type { Priority, SoftPriority } from "../cpsat/types.js";
+import type {
+  BuiltInCpsatRuleRegistry,
+  CpsatRuleConfigEntryFor,
+  CpsatRuleName,
+  CpsatRuleRegistry,
+} from "../cpsat/rules/rules.types.js";
 import type { RecurringPeriod } from "../cpsat/rules/scope.types.js";
 
 // ============================================================================
@@ -20,6 +79,13 @@ import type { RecurringPeriod } from "../cpsat/rules/scope.types.js";
  * Default priority is `MANDATORY`. Use `appliesTo` to scope to a
  * role, skill, or member ID. Use time scoping options (`dayOfWeek`,
  * `dateRange`, `dates`) to limit when the rule applies.
+ * Scope answers where a rule is evaluated. It does not change the rule's core
+ * meaning. For example, `maxDaysPerWeek(4, { dayOfWeek: ["monday"] })` is still
+ * a day-cap concept, just scoped to matching scheduling days. Priority is just
+ * as important as scope: scope decides where a rule applies, and priority decides how hard the solver should enforce it. Use
+ * `"MANDATORY"` for requirements the schedule cannot violate, and softer
+ * priorities for things the requirements describe as preferred, ideal, or
+ * "where possible".
  * Not all rules support all scoping options. Entity-only rules
  * (e.g., {@link maxConsecutiveDays}) ignore time scoping.
  *
@@ -46,7 +112,8 @@ export interface RuleOptions {
  * @remarks
  * Used by rules whose semantics are inherently per-day or per-week
  * (e.g., {@link minHoursPerDay}, {@link maxConsecutiveDays}) and cannot
- * be meaningfully restricted to a date range or day of week.
+ * be meaningfully restricted to a date range or day of week. `priority`
+ * still controls whether the rule is a hard requirement or a softer target.
  *
  * @category Rules
  */
@@ -96,6 +163,63 @@ export interface AssignTogetherOptions {
   priority?: Priority;
 }
 
+/**
+ * Options for {@link maxConcurrentAssignments}.
+ *
+ * @remarks
+ * Use this when the business has a hard productive cap that is independent from
+ * its coverage floor, for example when only a fixed number of assignments can
+ * overlap productively at once. Omit `startTime`/`endTime` to cap concurrent
+ * assignments across the full day. Provide both together to limit concurrency
+ * only within a specific time window.
+ *
+ * @category Rules
+ */
+export interface MaxConcurrentAssignmentsOptions extends RuleOptions {
+  /** Optional start of the capped time window. */
+  startTime?: TimeOfDay;
+  /** Optional end of the capped time window. */
+  endTime?: TimeOfDay;
+}
+
+/**
+ * Options for {@link targetDaysPerWeek}.
+ *
+ * @remarks
+ * Use this for stated weekly patterns like "works a 4-day week" when that
+ * pattern should remain flexible. This is soft-only by design. Pair it with
+ * {@link maxDaysPerWeek} when the same number is also a hard cap, and use
+ * {@link minDaysPerWeek} only when the requirements explicitly require a minimum.
+ *
+ * @category Rules
+ */
+export interface TargetDaysPerWeekOptions extends Omit<EntityOnlyRuleOptions, "priority"> {
+  /** Soft only. Defaults to `"HIGH"`. */
+  priority?: SoftPriority;
+}
+
+/**
+ * Options for {@link targetPeakConcurrentAssignments}.
+ *
+ * @remarks
+ * Use this when the business wants to hit a peak concurrency target within a
+ * day, without making that target a lower bound across the whole day. This is
+ * soft-only by design. Unlike {@link cover}, this helper does not establish a
+ * minimum that must hold throughout a semantic time. Instead it shifts the
+ * solution toward reaching the desired peak within the scoped days. Use
+ * {@link cover} for a whole-window minimum, and pair
+ * this helper with
+ * {@link maxConcurrentAssignments} when the same number is also a hard cap.
+ * This is useful for language like "fill all 5 chairs on peak days" or
+ * "ideally reach full capacity during the busy point".
+ *
+ * @category Rules
+ */
+export interface TargetPeakConcurrentAssignmentsOptions extends Omit<RuleOptions, "priority"> {
+  /** Soft only. Defaults to `"HIGH"`. */
+  priority?: SoftPriority;
+}
+
 // ============================================================================
 // Rule Entry
 // ============================================================================
@@ -114,54 +238,177 @@ export interface RuleResolveContext {
 }
 
 // Internal rule entry type
-interface RuleEntryBase {
+interface RuleEntryBase<Name extends string = string> {
   readonly _type: "rule";
-  readonly _rule: string;
+  readonly _rule: Name;
   /**
    * Optional custom resolver. When present, `resolveRules()` calls this
    * instead of the default translation path. Built-in rules that need
    * special field mapping (e.g., `timeOff`, `assignTogether`) attach one;
    * all other rules use the default resolver.
    */
-  readonly _resolve?: (ctx: RuleResolveContext) => Record<string, unknown> & { name: string };
+  readonly _resolve?: (ctx: RuleResolveContext) => Record<string, unknown> & { name: Name };
 }
 
 /**
- * An opaque rule entry returned by rule functions.
+ * A typed rule entry returned by rule helpers and {@link defineRule}.
  *
  * @remarks
- * Pass these directly into the `rules` array of {@link ScheduleConfig}.
- * The internal fields are resolved during compilation.
+ * Pass these directly into the `rules` array of {@link ScheduleConfig}. The
+ * internal fields are resolved during compilation.
+ *
+ * @category Rules
  */
-export type RuleEntry = RuleEntryBase & Record<string, unknown>;
+export type RuleEntry<
+  Name extends string = string,
+  Fields extends object = Record<string, unknown>,
+> = RuleEntryBase<Name> & Fields & Record<string, unknown>;
+
+type TypedRuleEntryFor<Registry extends CpsatRuleRegistry> = {
+  [K in keyof Registry & string]: RuleEntry<
+    K,
+    Omit<CpsatRuleConfigEntryFor<Pick<Registry, K>>, "name">
+  >;
+}[keyof Registry & string];
 
+/**
+ * A rule entry accepted by {@link ScheduleConfig.rules}.
+ *
+ * @remarks
+ * Built-in rule helpers return entries that are always valid. Custom rules created
+ * via {@link defineRule} are checked against the active rule registry when passed
+ * to {@link schedule} or {@link partialSchedule}. For registry-bound authoring,
+ * prefer {@link defineRuleFor}.
+ *
+ * @category Rules
+ */
+export type ScheduleRuleEntry<TRuleRegistry extends CpsatRuleRegistry = BuiltInCpsatRuleRegistry> =
+  TypedRuleEntryFor<TRuleRegistry>;
+
+type SanitizedRuleFields<Fields extends object> = Omit<Fields, "_type" | "_rule">;
+type BuiltInResolvedRuleConfig<Name extends CpsatRuleName> = CpsatRuleConfigEntryFor<
+  Pick<BuiltInCpsatRuleRegistry, Name>
+>;
+type PeriodLength = { type: "weeks"; value: number } | { type: "months"; value: number };
+type ResolvedEntityScope = {
+  memberIds?: [string, ...string[]];
+  roleIds?: [string, ...string[]];
+  skillIds?: [string, ...string[]];
+};
+type ResolvedTimeOffRuleConfig = {
+  name: "time-off";
+  priority: Priority;
+  dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]];
+  dateRange?: { start: string; end: string };
+  specificDates?: string[];
+  recurringPeriods?: [RecurringPeriod, ...RecurringPeriod[]];
+  startTime?: TimeOfDay;
+  endTime?: TimeOfDay;
+} & ResolvedEntityScope;
+type ResolvedDaysOfWeekPerPeriodRuleConfig<
+  Name extends "max-days-of-week-per-period" | "min-days-of-week-per-period",
+> = {
+  name: Name;
+  days: number;
+  dayOfWeek: readonly [DayOfWeek, ...DayOfWeek[]];
+  period: PeriodLength;
+  priority: Priority;
+} & ResolvedEntityScope;
+type TimeOffRuleEntry = RuleEntry<"time-off", TimeOffOptions>;
+type AssignTogetherRuleEntry = RuleEntry<
+  "assign-together",
+  { members: [string, string, ...string[]] } & AssignTogetherOptions
+>;
+type DaysOfWeekPerPeriodRuleFields = {
+  days: number;
+  dayOfWeek: readonly [DayOfWeek, ...DayOfWeek[]];
+  period: PeriodLength;
+  appliesTo?: string | string[];
+  priority?: Priority;
+};
+type MaxDaysOfWeekPerPeriodRuleEntry = RuleEntry<
+  "max-days-of-week-per-period",
+  DaysOfWeekPerPeriodRuleFields
+>;
+type MinDaysOfWeekPerPeriodRuleEntry = RuleEntry<
+  "min-days-of-week-per-period",
+  DaysOfWeekPerPeriodRuleFields
+>;
 /**
  * Creates a rule entry for use in {@link ScheduleConfig.rules}.
  *
- * Built-in rules use the helpers (`maxHoursPerDay`, `timeOff`, etc.).
- * Custom rules can use `defineRule` to create entries that plug into the
- * same resolution and compilation pipeline.
+ * Built-in rules use the helpers (`maxHoursPerDay`, `timeOff`, etc.). Custom
+ * rules can use `defineRule` to create entries that plug into the same
+ * resolution and compilation pipeline.
  *
- * @param name - Rule name. Must match a key in the rule factory registry.
+ * @remarks
+ * The returned entry always preserves its rule name and fields. To validate custom
+ * rules at the point of creation, use {@link defineRuleFor} to bind `defineRule`
+ * to a specific registry.
+ *
+ * @param name - Rule name. Must match a key in the active rule registry.
  * @param fields - Rule-specific configuration fields.
  * @param resolve - Optional custom resolver. When omitted, the default
  *   resolution applies: `appliesTo` is mapped to `roleIds`/`skillIds`/`memberIds`,
  *   `dates` is renamed to `specificDates`, and all other fields pass through.
  */
-export function defineRule(
-  name: string,
-  fields: Record<string, unknown>,
-  resolve?: (ctx: RuleResolveContext) => Record<string, unknown> & { name: string },
-): RuleEntry {
-  const { _type: _, _rule: __, ...safeFields } = fields;
-  const entry: RuleEntry = { _type: "rule", _rule: name, ...safeFields };
+export function defineRule<const Name extends string, const Fields extends object>(
+  name: Name,
+  fields: Fields,
+  resolve?: (ctx: RuleResolveContext) => Record<string, unknown> & { name: Name },
+): RuleEntry<Name, SanitizedRuleFields<Fields>>;
+export function defineRule<const Name extends string, const Fields extends object>(
+  name: Name,
+  fields: Fields,
+  resolve?: (ctx: RuleResolveContext) => Record<string, unknown> & { name: Name },
+): RuleEntry<Name, SanitizedRuleFields<Fields>> {
+  const safeFields = { ...fields } as SanitizedRuleFields<Fields> & {
+    _type?: unknown;
+    _rule?: unknown;
+  };
+  delete safeFields._type;
+  delete safeFields._rule;
+
+  const entry: RuleEntry<Name, SanitizedRuleFields<Fields>> = {
+    _type: "rule",
+    _rule: name,
+    ...safeFields,
+  };
   if (resolve) {
     Object.defineProperty(entry, "_resolve", { value: resolve, enumerable: false });
   }
   return entry;
 }
 
-function makeRule(rule: CpsatRuleName, fields: Record<string, unknown>): RuleEntry {
+/**
+ * Creates a registry-bound `defineRule` helper.
+ *
+ * @remarks
+ * Use this when authoring custom rules directly and you want immediate
+ * compile-time validation of the rule name and config fields against a specific
+ * rule registry.
+ *
+ * @category Rules
+ */
+export function defineRuleFor<TRuleRegistry extends CpsatRuleRegistry>(
+  ruleRegistry: TRuleRegistry,
+): <const Name extends keyof TRuleRegistry & string>(
+  name: Name,
+  fields: Omit<CpsatRuleConfigEntryFor<Pick<TRuleRegistry, Name>>, "name">,
+  resolve?: (ctx: RuleResolveContext) => CpsatRuleConfigEntryFor<Pick<TRuleRegistry, Name>>,
+) => RuleEntry<
+  Name,
+  SanitizedRuleFields<Omit<CpsatRuleConfigEntryFor<Pick<TRuleRegistry, Name>>, "name">>
+> {
+  void ruleRegistry;
+
+  return (name, fields, resolve) => defineRule(name, fields, resolve);
+}
+
+function makeRule<const Name extends CpsatRuleName, const Fields extends object>(
+  rule: Name,
+  fields: Fields,
+): RuleEntry<Name, SanitizedRuleFields<Fields>> {
   return defineRule(rule, fields);
 }
 
@@ -172,174 +419,326 @@ function makeRule(rule: CpsatRuleName, fields: Record<string, unknown>): RuleEnt
 /**
  * Limits hours per day.
  *
- * @example
- * ```typescript
- * maxHoursPerDay(10)
- * maxHoursPerDay(4, { appliesTo: "student", dayOfWeek: weekdays })
- * ```
+ * @remarks
+ * Use this when the requirements or operating constraints explicitly impose a
+ * daily hours cap. Do not infer it just from the chosen shift pattern lengths.
  *
  * @category Rules
  */
-export function maxHoursPerDay(hours: number, opts?: RuleOptions): RuleEntry {
+export function maxHoursPerDay(
+  hours: number,
+  opts?: RuleOptions,
+): RuleEntry<"max-hours-day", { hours: number } & RuleOptions> {
   return makeRule("max-hours-day", { hours, ...opts });
 }
 
 /**
  * Limits hours per scheduling week.
  *
- * @example
- * ```typescript
- * maxHoursPerWeek(48)
- * maxHoursPerWeek(20, { appliesTo: "student" })
- * ```
+ * @remarks
+ * Use this when the requirements or operating constraints explicitly impose a
+ * weekly hours cap. Do not infer it just from a stated working pattern such
+ * as "4-day week" unless the requirements also make the hour limit explicit.
  *
  * @category Rules
  */
-export function maxHoursPerWeek(hours: number, opts?: RuleOptions): RuleEntry {
+export function maxHoursPerWeek(
+  hours: number,
+  opts?: RuleOptions,
+): RuleEntry<"max-hours-week", { hours: number } & RuleOptions> {
   return makeRule("max-hours-week", { hours, ...opts });
 }
 
 /**
  * Minimum hours when assigned on a day.
  *
- * @example
- * ```typescript
- * minHoursPerDay(4)
- * ```
- *
  * @category Rules
  */
-export function minHoursPerDay(hours: number, opts?: EntityOnlyRuleOptions): RuleEntry {
+export function minHoursPerDay(
+  hours: number,
+  opts?: EntityOnlyRuleOptions,
+): RuleEntry<"min-hours-day", { hours: number } & EntityOnlyRuleOptions> {
   return makeRule("min-hours-day", { hours, ...opts });
 }
 
 /**
  * Minimum hours per scheduling week.
  *
- * @example
- * ```typescript
- * minHoursPerWeek(20, { priority: "HIGH" })
- * ```
- *
  * @category Rules
  */
-export function minHoursPerWeek(hours: number, opts?: EntityOnlyRuleOptions): RuleEntry {
+export function minHoursPerWeek(
+  hours: number,
+  opts?: EntityOnlyRuleOptions,
+): RuleEntry<"min-hours-week", { hours: number } & EntityOnlyRuleOptions> {
   return makeRule("min-hours-week", { hours, ...opts });
 }
 
 /**
- * Limits working days per scheduling week.
+ * Caps assigned days per scheduling week.
  *
- * @example
- * ```typescript
- * maxDaysPerWeek(5)
- * maxDaysPerWeek(3, { appliesTo: "part-time" })
- * ```
+ * @remarks
+ * Use this when the requirements explicitly impose a weekly day cap. If the same
+ * number is the normal weekly pattern rather than just a hard limit, pair it
+ * with {@link targetDaysPerWeek}.
  *
  * @category Rules
  */
-export function maxDaysPerWeek(days: number, opts?: RuleOptions): RuleEntry {
+export function maxDaysPerWeek(
+  days: number,
+  opts?: RuleOptions,
+): RuleEntry<"max-days-week", { days: number } & RuleOptions> {
   return makeRule("max-days-week", { days, ...opts });
 }
 
 /**
- * Minimum working days per scheduling week.
+ * Enforces a minimum number of assigned days per scheduling week.
  *
- * @example
- * ```typescript
- * minDaysPerWeek(3, { priority: "HIGH" })
- * minDaysPerWeek(5, { appliesTo: "full-time" })
- * ```
+ * @remarks
+ * Use this when the requirements explicitly require a weekly minimum. Language like
+ * "works a 4-day week" often implies a hard cap via {@link maxDaysPerWeek}
+ * and possibly a softer target via {@link targetDaysPerWeek}, not a mandatory
+ * weekly minimum for every member.
  *
  * @category Rules
  */
-export function minDaysPerWeek(days: number, opts?: EntityOnlyRuleOptions): RuleEntry {
+export function minDaysPerWeek(
+  days: number,
+  opts?: EntityOnlyRuleOptions,
+): RuleEntry<"min-days-week", { days: number } & EntityOnlyRuleOptions> {
   return makeRule("min-days-week", { days, ...opts });
 }
 
 /**
- * Maximum distinct shifts per day.
+ * Softly targets assigned days per scheduling week.
  *
- * @example
- * ```typescript
- * maxShiftsPerDay(1)
- * maxShiftsPerDay(2, { appliesTo: "student", dayOfWeek: weekend })
- * ```
+ * @remarks
+ * Use this for stated working patterns like "works a 4-day week" when the
+ * pattern should remain the norm but can flex around holidays, time off, or
+ * other tradeoffs. Deviations in either direction are penalized, so working
+ * fewer days or more days than the target both count as misses. Pair it with
+ * {@link maxDaysPerWeek} when the same number is also a hard cap, and use
+ * {@link minDaysPerWeek} only when the requirements explicitly require a minimum.
+ *
+ * @param days - Target number of assigned days per scheduling week.
+ * @param opts - Optional entity scope and soft priority.
  *
  * @category Rules
  */
-export function maxShiftsPerDay(shifts: number, opts?: RuleOptions): RuleEntry {
+export function targetDaysPerWeek(
+  days: number,
+  opts?: TargetDaysPerWeekOptions,
+): RuleEntry<"target-days-week", { days: number } & TargetDaysPerWeekOptions> {
+  return makeRule("target-days-week", { days, ...opts });
+}
+
+/**
+ * Maximum distinct shifts per day.
+ *
+ * @category Rules
+ */
+export function maxShiftsPerDay(
+  shifts: number,
+  opts?: RuleOptions,
+): RuleEntry<"max-shifts-day", { shifts: number } & RuleOptions> {
   return makeRule("max-shifts-day", { shifts, ...opts });
 }
 
 /**
- * Maximum consecutive working days.
+ * Caps how many targeted assignments may overlap at the same time.
  *
- * @example
- * ```typescript
- * maxConsecutiveDays(5)
- * ```
+ * @remarks
+ * Use this for hard productive capacity limits that should stay separate from
+ * the minimum staffing requirement expressed by {@link cover}. Pair a
+ * lower-bound `cover(...)` with `maxConcurrentAssignments(...)` when the
+ * business needs both demand and capacity modeled explicitly.
+ *
+ * On days with staggered opening and closing shifts, keep lower-bound coverage
+ * scoped to the windows that truly need minimum staffing. Do not turn a total
+ * daily headcount target into a whole-day lower-bound `cover(...)` unless the
+ * business explicitly requires that many people in every overlapping bucket.
+ *
+ * Unlike {@link maxShiftsPerDay}, this limits simultaneous overlap, not total
+ * assignments on a day.
+ *
+ * @param assignments - Maximum number of concurrent overlapping assignments.
+ * @param opts - Optional scope and time-window settings.
+ *
+ * @category Rules
+ */
+export function maxConcurrentAssignments(
+  assignments: number,
+  opts?: RuleOptions & {
+    startTime?: TimeOfDay;
+    endTime?: TimeOfDay;
+  },
+): RuleEntry<
+  "max-concurrent-assignments",
+  { assignments: number } & MaxConcurrentAssignmentsOptions
+> {
+  return makeRule("max-concurrent-assignments", { assignments, ...opts });
+}
+
+/**
+ * Softly targets the daily peak number of concurrent overlapping assignments.
+ *
+ * @remarks
+ * Use this when the business wants to hit full productive occupancy at the
+ * busy point of a day, but does not mean that same number must be present
+ * throughout the full span. This is not a whole-day lower bound. Pair it with
+ * {@link cover} for edge minima and with
+ * {@link maxConcurrentAssignments} when the same value is also a hard cap.
+ * Prefer this over a whole-day `cover(...)` when the brief means "reach the
+ * peak" rather than "maintain this minimum throughout the day".
+ *
+ * This is a rule-level peak target, not a variant of {@link cover}. Do not
+ * introduce a synthetic semantic time just to attach a whole-window
+ * `cover(...)` when the requirement is really about the day's peak.
+ *
+ * @param assignments - Target peak number of concurrent overlapping assignments.
+ * @param opts - Optional scope and soft priority.
  *
  * @category Rules
  */
-export function maxConsecutiveDays(days: number, opts?: EntityOnlyRuleOptions): RuleEntry {
+export function targetPeakConcurrentAssignments(
+  assignments: number,
+  opts?: TargetPeakConcurrentAssignmentsOptions,
+): RuleEntry<
+  "target-peak-concurrent-assignments",
+  { assignments: number } & TargetPeakConcurrentAssignmentsOptions
+> {
+  return makeRule("target-peak-concurrent-assignments", { assignments, ...opts });
+}
+
+/**
+ * Maximum consecutive assigned days.
+ *
+ * @category Rules
+ */
+export function maxConsecutiveDays(
+  days: number,
+  opts?: EntityOnlyRuleOptions,
+): RuleEntry<"max-consecutive-days", { days: number } & EntityOnlyRuleOptions> {
   return makeRule("max-consecutive-days", { days, ...opts });
 }
 
 /**
  * Once working, continue for at least this many consecutive days.
  *
- * @example
- * ```typescript
- * minConsecutiveDays(2, { priority: "HIGH" })
- * ```
- *
  * @category Rules
  */
-export function minConsecutiveDays(days: number, opts?: EntityOnlyRuleOptions): RuleEntry {
+export function minConsecutiveDays(
+  days: number,
+  opts?: EntityOnlyRuleOptions,
+): RuleEntry<"min-consecutive-days", { days: number } & EntityOnlyRuleOptions> {
   return makeRule("min-consecutive-days", { days, ...opts });
 }
 
 /**
  * Minimum rest hours between shifts.
  *
- * @example
- * ```typescript
- * minRestBetweenShifts(10)
- * ```
- *
  * @category Rules
  */
-export function minRestBetweenShifts(hours: number, opts?: EntityOnlyRuleOptions): RuleEntry {
+export function minRestBetweenShifts(
+  hours: number,
+  opts?: EntityOnlyRuleOptions,
+): RuleEntry<"min-rest-between-shifts", { hours: number } & EntityOnlyRuleOptions> {
   return makeRule("min-rest-between-shifts", { hours, ...opts });
 }
 
 /**
- * Prefer (`"high"`) or avoid (`"low"`) assigning. Requires `appliesTo`.
+ * Nudge the solver toward scheduling targeted members.
  *
- * @example
- * ```typescript
- * preference("high", { appliesTo: "waiter" })
- * preference("low", { appliesTo: "student", dayOfWeek: weekdays })
- * ```
+ * @remarks
+ * Soft constraint. The solver adds a bonus for each assignment of the
+ * targeted members, making them more likely to appear on the schedule.
+ * Use `priority` to control how strong the nudge is; higher priority
+ * means a larger bonus. Even at `"MANDATORY"` strength the solver can
+ * still leave a member unassigned if hard constraints prevent it.
+ *
+ * Opposite of {@link avoidAssignment}. Both map to the same underlying
+ * `assignment-priority` rule with different directions.
+ *
+ * @param opts - See {@link RuleOptions}
  *
  * @category Rules
  */
-export function preference(level: "high" | "low", opts?: Omit<RuleOptions, "priority">): RuleEntry {
-  return makeRule("assignment-priority", { preference: level, ...opts });
+export function preferAssignment(
+  opts?: RuleOptions,
+): RuleEntry<"assignment-priority", { preference: "prefer" } & RuleOptions> {
+  return makeRule("assignment-priority", { preference: "prefer", ...opts });
 }
 
 /**
- * Prefer assigning to shifts at a specific location. Requires `appliesTo`.
+ * Nudge the solver away from scheduling targeted members.
  *
- * @example
- * ```typescript
- * preferLocation("terrace", { appliesTo: "alice" })
- * ```
+ * @remarks
+ * Soft constraint. The solver adds a penalty for each assignment of the
+ * targeted members, making them less likely to appear on the schedule.
+ * The member is still assigned when coverage requires it; the penalty
+ * only matters when the solver has a choice.
+ *
+ * Opposite of {@link preferAssignment}. Both map to the same underlying
+ * `assignment-priority` rule with different directions.
+ *
+ * @param opts - See {@link RuleOptions}
+ *
+ * @category Rules
+ */
+export function avoidAssignment(
+  opts?: RuleOptions,
+): RuleEntry<"assignment-priority", { preference: "avoid" } & RuleOptions> {
+  return makeRule("assignment-priority", { preference: "avoid", ...opts });
+}
+
+/**
+ * Steer a multi-role member toward shifts tagged with a specific role.
+ *
+ * @remarks
+ * Penalizes assignment to shift patterns whose `roleIds` do not include
+ * the preferred role. The member is still assigned to other roles when
+ * coverage requires it; the penalty only matters when the solver has a
+ * choice. Shift patterns without any `roleIds` (open to all) are also
+ * penalized since they are not explicitly tagged with the preferred role.
+ *
+ * The targeted members must actually hold the preferred role in their
+ * `roleIds`. If none of them do, compilation reports an error because
+ * the rule would silently penalize all their assignments (the opposite
+ * of the intent).
+ *
+ * Typical use case: a waiter who can cover kitchen pass shifts in a
+ * pinch. Give the member both roles (`roleIds: ["waiter", "pass"]`)
+ * and use `preferRole("waiter", ...)` so the solver keeps them on the
+ * floor unless the pass team is short-staffed.
+ *
+ * @param roleId - The role to prefer
+ * @param opts - See {@link EntityOnlyRuleOptions}
+ *
+ * @category Rules
+ */
+export function preferRole(
+  roleId: string,
+  opts?: EntityOnlyRuleOptions,
+): RuleEntry<"role-preference", { roleId: string } & EntityOnlyRuleOptions> {
+  return makeRule("role-preference", { roleId, ...opts });
+}
+
+/**
+ * Steer a member toward shifts at a specific location.
+ *
+ * @remarks
+ * Penalizes assignment to shift patterns whose `locationId` does not
+ * match the preferred location. The member is still assigned elsewhere
+ * when coverage requires it.
+ *
+ * @param locationId - The location to prefer
+ * @param opts - See {@link EntityOnlyRuleOptions}
  *
  * @category Rules
  */
-export function preferLocation(locationId: string, opts?: EntityOnlyRuleOptions): RuleEntry {
+export function preferLocation(
+  locationId: string,
+  opts?: EntityOnlyRuleOptions,
+): RuleEntry<"location-preference", { locationId: string } & EntityOnlyRuleOptions> {
   return makeRule("location-preference", { locationId, ...opts });
 }
 
@@ -357,15 +756,11 @@ export function preferLocation(locationId: string, opts?: EntityOnlyRuleOptions)
  * messaging from {@link minDaysPerWeek}. Priority is not configurable;
  * the rule name communicates the intent.
  *
- * @example
- * ```typescript
- * mustAssign({ appliesTo: "diana" })
- * mustAssign({ appliesTo: ["diana", "yavuz"] })
- * ```
- *
  * @category Rules
  */
-export function mustAssign(opts?: { appliesTo?: string | string[] }): RuleEntry {
+export function mustAssign(opts?: {
+  appliesTo?: string | string[];
+}): RuleEntry<"must-assign", { appliesTo?: string | string[] }> {
   return makeRule("must-assign", { ...opts });
 }
 
@@ -377,21 +772,9 @@ export function mustAssign(opts?: { appliesTo?: string | string[] }): RuleEntry
  * Block assignments during specified periods.
  * Requires at least one time scope (`dayOfWeek`, `dateRange`, `dates`, or `from`/`until`).
  *
- * @example
- * ```typescript
- * // Full days off
- * timeOff({ appliesTo: "alice", dateRange: { start: "2024-02-01", end: "2024-02-05" } })
- *
- * // Every weekend off
- * timeOff({ appliesTo: "mauro", dayOfWeek: weekend })
- *
- * // Wednesday afternoons off
- * timeOff({ appliesTo: "student", dayOfWeek: ["wednesday"], from: t(14) })
- * ```
- *
  * @category Rules
  */
-export function timeOff(opts: TimeOffOptions): RuleEntry {
+export function timeOff(opts: TimeOffOptions): TimeOffRuleEntry {
   const { from, until, ...rest } = opts;
   return defineRule("time-off", { from, until, ...rest }, (ctx) => {
     if (!rest.dayOfWeek && !rest.dateRange && !rest.dates && !rest.recurringPeriods) {
@@ -400,7 +783,7 @@ export function timeOff(opts: TimeOffOptions): RuleEntry {
       );
     }
 
-    const { appliesTo, dates, ...passthrough } = rest;
+    const { appliesTo, dates, priority, ...passthrough } = rest;
     const entityScope = resolveAppliesTo(appliesTo, ctx.roles, ctx.skills, ctx.memberIds);
     const resolvedDates = dates ? { specificDates: dates } : {};
 
@@ -416,31 +799,28 @@ export function timeOff(opts: TimeOffOptions): RuleEntry {
       partialDay.endTime = until;
     }
 
-    return {
+    const resolved = {
       name: "time-off",
+      priority: priority ?? "MANDATORY",
       ...passthrough,
       ...entityScope,
       ...resolvedDates,
       ...partialDay,
-    } as CpsatRuleConfigEntry;
+    } satisfies ResolvedTimeOffRuleConfig;
+
+    return resolved;
   });
 }
 
 /**
  * Members work the same shifts on days they are both assigned.
  *
- * @example
- * ```typescript
- * assignTogether(["alice", "bob"])
- * assignTogether(["alice", "bob", "charlie"], { priority: "HIGH" })
- * ```
- *
  * @category Rules
  */
 export function assignTogether(
   memberIds: [string, string, ...string[]],
   opts?: AssignTogetherOptions,
-): RuleEntry {
+): AssignTogetherRuleEntry {
   return defineRule("assign-together", { members: memberIds, ...opts }, (ctx) => {
     for (const member of memberIds) {
       if (!ctx.memberIds.has(member)) {
@@ -450,14 +830,133 @@ export function assignTogether(
         );
       }
     }
-    return {
+    const resolved = {
       name: "assign-together",
       groupMemberIds: memberIds,
-      ...opts,
-    } as CpsatRuleConfigEntry;
+      priority: opts?.priority ?? "MANDATORY",
+    } satisfies BuiltInResolvedRuleConfig<"assign-together">;
+
+    return resolved;
   });
 }
 
+// ============================================================================
+// Period-Based Day-of-Week Rules
+// ============================================================================
+
+/**
+ * Options for {@link maxDaysOfWeekPerPeriod} and {@link minDaysOfWeekPerPeriod}.
+ *
+ * Exactly one of `weeks` or `months` must be provided to define the
+ * repeating period. Week periods align to `weekStartsOn`. Month periods
+ * align to calendar month boundaries.
+ *
+ * @category Rules
+ */
+export type DaysOfWeekPerPeriodOptions = {
+  /** Scope to role, skill, or member ID. */
+  appliesTo?: string | string[];
+  /** Default `MANDATORY`. */
+  priority?: Priority;
+} & ({ weeks: number; months?: never } | { months: number; weeks?: never });
+
+/**
+ * Caps how many times a person works on specific days of the week within
+ * each period.
+ *
+ * @remarks
+ * The scheduling window is divided into non-overlapping chunks of the
+ * configured period length. Within each chunk, only days matching the
+ * `dayOfWeek` filter are counted. The constraint bounds that count.
+ *
+ * @param days - Maximum number of matching days allowed per period.
+ * @param dayOfWeek - Which days of the week count toward the limit.
+ * @param opts - Period length and optional scoping.
+ *
+ * @category Rules
+ */
+export function maxDaysOfWeekPerPeriod(
+  days: number,
+  dayOfWeek: readonly [DayOfWeek, ...DayOfWeek[]],
+  opts: DaysOfWeekPerPeriodOptions,
+): MaxDaysOfWeekPerPeriodRuleEntry {
+  const { appliesTo, priority, ...periodOpts } = opts;
+  const period =
+    "weeks" in periodOpts && periodOpts.weeks != null
+      ? { type: "weeks" as const, value: periodOpts.weeks }
+      : { type: "months" as const, value: (periodOpts as { months: number }).months };
+
+  return defineRule(
+    "max-days-of-week-per-period",
+    { days, dayOfWeek: [...dayOfWeek], period, appliesTo, priority },
+    (ctx) => {
+      const entityScope = resolveAppliesTo(appliesTo, ctx.roles, ctx.skills, ctx.memberIds);
+      const resolved = {
+        name: "max-days-of-week-per-period",
+        days,
+        dayOfWeek: [...dayOfWeek],
+        period,
+        priority: priority ?? "MANDATORY",
+        ...entityScope,
+      } satisfies ResolvedDaysOfWeekPerPeriodRuleConfig<"max-days-of-week-per-period">;
+
+      return resolved;
+    },
+  );
+}
+
+/**
+ * Enforces a minimum number of times a person works on specific days of the
+ * week within each period.
+ *
+ * @remarks
+ * The scheduling window is divided into non-overlapping chunks of the
+ * configured period length. Within each chunk, only days matching the
+ * `dayOfWeek` filter are counted. The constraint ensures the count meets
+ * the minimum.
+ *
+ * When the scheduling window does not align evenly with the period
+ * boundaries, the last chunk may contain fewer matching days than the
+ * minimum. A MANDATORY priority will make the model infeasible in that
+ * case. Use a soft priority (HIGH, MEDIUM, LOW) if partial periods at
+ * the edges of the window are expected.
+ *
+ * @param days - Minimum number of matching days required per period.
+ * @param dayOfWeek - Which days of the week count toward the limit.
+ * @param opts - Period length and optional scoping.
+ *
+ * @category Rules
+ */
+export function minDaysOfWeekPerPeriod(
+  days: number,
+  dayOfWeek: readonly [DayOfWeek, ...DayOfWeek[]],
+  opts: DaysOfWeekPerPeriodOptions,
+): MinDaysOfWeekPerPeriodRuleEntry {
+  const { appliesTo, priority, ...periodOpts } = opts;
+  const period =
+    "weeks" in periodOpts && periodOpts.weeks != null
+      ? { type: "weeks" as const, value: periodOpts.weeks }
+      : { type: "months" as const, value: (periodOpts as { months: number }).months };
+
+  return defineRule(
+    "min-days-of-week-per-period",
+    { days, dayOfWeek: [...dayOfWeek], period, appliesTo, priority },
+    (ctx) => {
+      const entityScope = resolveAppliesTo(appliesTo, ctx.roles, ctx.skills, ctx.memberIds);
+      const resolved = {
+        name: "min-days-of-week-per-period",
+        days,
+        dayOfWeek: [...dayOfWeek],
+        period,
+        priority: priority ?? "MANDATORY",
+        ...entityScope,
+      } satisfies ResolvedDaysOfWeekPerPeriodRuleConfig<"min-days-of-week-per-period">;
+
+      return resolved;
+    },
+  );
+}
+
 // ============================================================================
 // Internal: appliesTo resolution (shared with definition.ts)
 // ============================================================================