dabke 0.83.0 → 0.84.0

package/dist/schedule/rules.d.ts

@@ -1,10 +1,65 @@
 /**
  * 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 { Priority, SoftPriority } from "../cpsat/types.js";
+import type { BuiltInCpsatRuleRegistry, CpsatRuleConfigEntryFor, CpsatRuleRegistry } from "../cpsat/rules/rules.types.js";
 import type { RecurringPeriod } from "../cpsat/rules/scope.types.js";
 /**
  * Scoping options shared by most rule functions.
@@ -13,6 +68,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.
  *
@@ -41,7 +103,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
  */
@@ -91,6 +154,60 @@ export interface AssignTogetherOptions {
     /** Defaults to `"MANDATORY"`. */
     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;
+}
 /**
  * Context passed to a rule's resolve function during compilation.
  *
@@ -103,9 +220,9 @@ export interface RuleResolveContext {
     readonly skills: ReadonlySet<string>;
     readonly memberIds: ReadonlySet<string>;
 }
-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
@@ -113,171 +230,341 @@ interface RuleEntryBase {
      * all other rules use the default resolver.
      */
     readonly _resolve?: (ctx: RuleResolveContext) => Record<string, unknown> & {
-        name: string;
+        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 PeriodLength = {
+    type: "weeks";
+    value: number;
+} | {
+    type: "months";
+    value: number;
+};
+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 declare function defineRule(name: string, fields: Record<string, unknown>, resolve?: (ctx: RuleResolveContext) => Record<string, unknown> & {
-    name: string;
-}): RuleEntry;
+export declare 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>>;
+/**
+ * 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 declare 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">>>;
 /**
  * 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 declare function maxHoursPerDay(hours: number, opts?: RuleOptions): RuleEntry;
+export declare function maxHoursPerDay(hours: number, opts?: RuleOptions): RuleEntry<"max-hours-day", {
+    hours: number;
+} & RuleOptions>;
 /**
  * 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 declare function maxHoursPerWeek(hours: number, opts?: RuleOptions): RuleEntry;
+export declare function maxHoursPerWeek(hours: number, opts?: RuleOptions): RuleEntry<"max-hours-week", {
+    hours: number;
+} & RuleOptions>;
 /**
  * Minimum hours when assigned on a day.
  *
- * @example
- * ```typescript
- * minHoursPerDay(4)
- * ```
- *
  * @category Rules
  */
-export declare function minHoursPerDay(hours: number, opts?: EntityOnlyRuleOptions): RuleEntry;
+export declare function minHoursPerDay(hours: number, opts?: EntityOnlyRuleOptions): RuleEntry<"min-hours-day", {
+    hours: number;
+} & EntityOnlyRuleOptions>;
 /**
  * Minimum hours per scheduling week.
  *
- * @example
- * ```typescript
- * minHoursPerWeek(20, { priority: "HIGH" })
- * ```
+ * @category Rules
+ */
+export declare function minHoursPerWeek(hours: number, opts?: EntityOnlyRuleOptions): RuleEntry<"min-hours-week", {
+    hours: number;
+} & EntityOnlyRuleOptions>;
+/**
+ * Caps assigned days per scheduling week.
+ *
+ * @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 declare function minHoursPerWeek(hours: number, opts?: EntityOnlyRuleOptions): RuleEntry;
+export declare function maxDaysPerWeek(days: number, opts?: RuleOptions): RuleEntry<"max-days-week", {
+    days: number;
+} & RuleOptions>;
 /**
- * Limits working days per scheduling week.
+ * Enforces a minimum number of assigned days per scheduling week.
  *
- * @example
- * ```typescript
- * maxDaysPerWeek(5)
- * maxDaysPerWeek(3, { appliesTo: "part-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 declare function maxDaysPerWeek(days: number, opts?: RuleOptions): RuleEntry;
+export declare function minDaysPerWeek(days: number, opts?: EntityOnlyRuleOptions): RuleEntry<"min-days-week", {
+    days: number;
+} & EntityOnlyRuleOptions>;
 /**
- * Minimum working days per scheduling week.
+ * Softly targets assigned days per scheduling week.
  *
- * @example
- * ```typescript
- * minDaysPerWeek(3, { priority: "HIGH" })
- * minDaysPerWeek(5, { appliesTo: "full-time" })
- * ```
+ * @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 declare function minDaysPerWeek(days: number, opts?: EntityOnlyRuleOptions): RuleEntry;
+export declare function targetDaysPerWeek(days: number, opts?: TargetDaysPerWeekOptions): RuleEntry<"target-days-week", {
+    days: number;
+} & TargetDaysPerWeekOptions>;
 /**
  * Maximum distinct shifts per day.
  *
- * @example
- * ```typescript
- * maxShiftsPerDay(1)
- * maxShiftsPerDay(2, { appliesTo: "student", dayOfWeek: weekend })
- * ```
+ * @category Rules
+ */
+export declare function maxShiftsPerDay(shifts: number, opts?: RuleOptions): RuleEntry<"max-shifts-day", {
+    shifts: number;
+} & RuleOptions>;
+/**
+ * Caps how many targeted assignments may overlap at the same time.
+ *
+ * @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 declare function maxShiftsPerDay(shifts: number, opts?: RuleOptions): RuleEntry;
+export declare function maxConcurrentAssignments(assignments: number, opts?: RuleOptions & {
+    startTime?: TimeOfDay;
+    endTime?: TimeOfDay;
+}): RuleEntry<"max-concurrent-assignments", {
+    assignments: number;
+} & MaxConcurrentAssignmentsOptions>;
 /**
- * Maximum consecutive working days.
+ * Softly targets the daily peak number of concurrent overlapping assignments.
  *
- * @example
- * ```typescript
- * maxConsecutiveDays(5)
- * ```
+ * @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 declare function maxConsecutiveDays(days: number, opts?: EntityOnlyRuleOptions): RuleEntry;
+export declare function targetPeakConcurrentAssignments(assignments: number, opts?: TargetPeakConcurrentAssignmentsOptions): RuleEntry<"target-peak-concurrent-assignments", {
+    assignments: number;
+} & TargetPeakConcurrentAssignmentsOptions>;
 /**
- * Once working, continue for at least this many consecutive days.
+ * Maximum consecutive assigned days.
  *
- * @example
- * ```typescript
- * minConsecutiveDays(2, { priority: "HIGH" })
- * ```
+ * @category Rules
+ */
+export declare function maxConsecutiveDays(days: number, opts?: EntityOnlyRuleOptions): RuleEntry<"max-consecutive-days", {
+    days: number;
+} & EntityOnlyRuleOptions>;
+/**
+ * Once working, continue for at least this many consecutive days.
  *
  * @category Rules
  */
-export declare function minConsecutiveDays(days: number, opts?: EntityOnlyRuleOptions): RuleEntry;
+export declare function minConsecutiveDays(days: number, opts?: EntityOnlyRuleOptions): RuleEntry<"min-consecutive-days", {
+    days: number;
+} & EntityOnlyRuleOptions>;
 /**
  * Minimum rest hours between shifts.
  *
- * @example
- * ```typescript
- * minRestBetweenShifts(10)
- * ```
+ * @category Rules
+ */
+export declare function minRestBetweenShifts(hours: number, opts?: EntityOnlyRuleOptions): RuleEntry<"min-rest-between-shifts", {
+    hours: number;
+} & EntityOnlyRuleOptions>;
+/**
+ * Nudge the solver toward scheduling targeted members.
+ *
+ * @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 declare function minRestBetweenShifts(hours: number, opts?: EntityOnlyRuleOptions): RuleEntry;
+export declare function preferAssignment(opts?: RuleOptions): RuleEntry<"assignment-priority", {
+    preference: "prefer";
+} & RuleOptions>;
 /**
- * Prefer (`"high"`) or avoid (`"low"`) assigning. Requires `appliesTo`.
+ * Nudge the solver away from scheduling targeted members.
  *
- * @example
- * ```typescript
- * preference("high", { appliesTo: "waiter" })
- * preference("low", { appliesTo: "student", dayOfWeek: weekdays })
- * ```
+ * @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 declare function preference(level: "high" | "low", opts?: Omit<RuleOptions, "priority">): RuleEntry;
+export declare function avoidAssignment(opts?: RuleOptions): RuleEntry<"assignment-priority", {
+    preference: "avoid";
+} & RuleOptions>;
 /**
- * Prefer assigning to shifts at a specific location. Requires `appliesTo`.
+ * Steer a multi-role member toward shifts tagged with a specific role.
  *
- * @example
- * ```typescript
- * preferLocation("terrace", { appliesTo: "alice" })
- * ```
+ * @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 declare function preferLocation(locationId: string, opts?: EntityOnlyRuleOptions): RuleEntry;
+export declare function preferRole(roleId: string, opts?: EntityOnlyRuleOptions): RuleEntry<"role-preference", {
+    roleId: string;
+} & EntityOnlyRuleOptions>;
+/**
+ * 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 declare function preferLocation(locationId: string, opts?: EntityOnlyRuleOptions): RuleEntry<"location-preference", {
+    locationId: string;
+} & EntityOnlyRuleOptions>;
 /**
  * Guarantees that targeted members appear on the schedule each week.
  *
@@ -292,48 +579,86 @@ export declare function preferLocation(locationId: string, opts?: EntityOnlyRule
  * 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 declare function mustAssign(opts?: {
     appliesTo?: string | string[];
-}): RuleEntry;
+}): RuleEntry<"must-assign", {
+    appliesTo?: string | string[];
+}>;
 /**
  * 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" } })
+ * @category Rules
+ */
+export declare function timeOff(opts: TimeOffOptions): TimeOffRuleEntry;
+/**
+ * Members work the same shifts on days they are both assigned.
  *
- * // Every weekend off
- * timeOff({ appliesTo: "mauro", dayOfWeek: weekend })
+ * @category Rules
+ */
+export declare function assignTogether(memberIds: [string, string, ...string[]], opts?: AssignTogetherOptions): AssignTogetherRuleEntry;
+/**
+ * Options for {@link maxDaysOfWeekPerPeriod} and {@link minDaysOfWeekPerPeriod}.
  *
- * // Wednesday afternoons off
- * timeOff({ appliesTo: "student", dayOfWeek: ["wednesday"], from: t(14) })
- * ```
+ * 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 declare function timeOff(opts: TimeOffOptions): RuleEntry;
+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;
+});
 /**
- * Members work the same shifts on days they are both assigned.
+ * Caps how many times a person works on specific days of the week within
+ * each period.
  *
- * @example
- * ```typescript
- * assignTogether(["alice", "bob"])
- * assignTogether(["alice", "bob", "charlie"], { priority: "HIGH" })
- * ```
+ * @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 declare function maxDaysOfWeekPerPeriod(days: number, dayOfWeek: readonly [DayOfWeek, ...DayOfWeek[]], opts: DaysOfWeekPerPeriodOptions): MaxDaysOfWeekPerPeriodRuleEntry;
+/**
+ * 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 declare function assignTogether(memberIds: [string, string, ...string[]], opts?: AssignTogetherOptions): RuleEntry;
+export declare function minDaysOfWeekPerPeriod(days: number, dayOfWeek: readonly [DayOfWeek, ...DayOfWeek[]], opts: DaysOfWeekPerPeriodOptions): MinDaysOfWeekPerPeriodRuleEntry;
 /**
  * Resolves an `appliesTo` value into entity scope fields.
  *