dabke 0.81.1 → 0.83.0

package/llms.txt

@@ -1,925 +0,0 @@
-# dabke
-
-> Scheduling library powered by constraint programming (CP-SAT)
-
-Define teams, shifts, coverage, and rules declaratively. dabke compiles
-them into a constraint model and solves for an optimized schedule.
-
-## Core Concepts
-
-**Schedule Definition**: The primary API. Small, composable functions
-(`time`, `cover`, `shift`, rule functions) produce a
-complete scheduling configuration via `defineSchedule`. Each concept
-is a single function call with full type safety.
-
-**Times vs Shift Patterns**: These are two distinct concepts.
-`times` are named time windows used to define and reference recurring
-periods: service hours, delivery windows, peak periods, weekly events
-like a fire drill. Times may overlap (e.g., "dinner" 18:00-22:00 and
-"happy_hour" 17:30-18:30). Coverage and rules reference these names.
-`shiftPatterns` define WHEN people CAN work (available time slots).
-The solver assigns people to shift patterns whose hours overlap with
-times to satisfy coverage. Not every shift pattern needs a
-corresponding time; create times only for periods you need to
-reference.
-
-**Rules**: Business requirements expressed as scheduling constraints.
-- Built-in rules: hours limits, time-off, rest periods, preferences, cost optimization
-- Scoping: apply rules globally, per person, per role, per skill, or per time period
-- Priority: `MANDATORY` (hard constraint) vs `LOW`/`MEDIUM`/`HIGH` (soft preferences)
-
-**Solving**: `ScheduleDefinition.createSchedulerConfig` merges the
-static definition with runtime data (members, scheduling period).
-`ModelBuilder` compiles the config into a solver request;
-`HttpSolverClient` sends it to the CP-SAT solver.
-
-**Example:**
-Define a schedule
-```typescript
-import {
-defineSchedule, t, time, cover, shift,
-maxHoursPerWeek, minRestBetweenShifts, timeOff,
-weekdays, weekend,
-} from "dabke";
-
-const schedule = defineSchedule({
-roles: ["nurse", "doctor"],
-skills: ["charge_nurse"],
-
-times: {
-morning_round: time({ startTime: t(7), endTime: t(9) }),
-day_ward: time({ startTime: t(7), endTime: t(15) }),
-night_ward: time({ startTime: t(23), endTime: t(7) }),
-},
-
-coverage: [
-cover("morning_round", "doctor", 1),
-cover("day_ward", "nurse", 3, { dayOfWeek: weekdays }),
-cover("day_ward", "nurse", 2, { dayOfWeek: weekend }),
-cover("night_ward", "nurse", 2),
-cover("night_ward", "charge_nurse", 1),
-],
-
-shiftPatterns: [
-shift("day", t(7), t(15)),
-shift("night", t(23), t(7)),
-],
-
-rules: [
-maxHoursPerWeek(40),
-minRestBetweenShifts(11),
-timeOff({ appliesTo: "alice", dayOfWeek: weekend }),
-],
-});
-```
-
-**Example:**
-Solve a schedule
-```typescript
-import { ModelBuilder, HttpSolverClient, parseSolverResponse } from "dabke";
-
-const config = schedule.createSchedulerConfig({
-schedulingPeriod: {
-dateRange: { start: "2026-02-09", end: "2026-02-15" },
-},
-members: [
-{ id: "alice", roles: ["nurse"], skills: ["charge_nurse"] },
-{ id: "bob", roles: ["nurse"] },
-{ id: "carol", roles: ["doctor"] },
-],
-});
-
-const builder = new ModelBuilder(config);
-const { request, canSolve, validation } = builder.compile();
-if (canSolve) {
-const client = new HttpSolverClient(fetch, "http://localhost:8080");
-const response = await client.solve(request);
-const result = parseSolverResponse(response);
-}
-```
-
----
-
-## Schedule Definition
-
-### `defineSchedule`
-
-Defines a complete schedule configuration.
-
-Validates the static config at call time (role/skill disjointness, coverage
-targets, shift pattern roles). Returns a `ScheduleDefinition` whose
-`createSchedulerConfig` method validates runtime data (member IDs,
-`appliesTo` resolution) and produces a `ModelBuilderConfig`.
-
-**Example:**
-```typescript
-import { defineSchedule, t, time, cover, shift, maxHoursPerDay } from "dabke";
-
-export default defineSchedule({
-  roles: ["agent", "supervisor"],
-  times: { peak: time({ startTime: t(9), endTime: t(17) }) },
-  coverage: [cover("peak", "agent", 4)],
-  shiftPatterns: [shift("day", t(9), t(17))],
-  rules: [maxHoursPerDay(8)],
-});
-```
-
-```ts
-defineSchedule(config: ScheduleConfig<R, S, T>): ScheduleDefinition
-```
-
-### `ScheduleDefinition`
-
-Result of `defineSchedule`.
-
-**Properties:**
-- `createSchedulerConfig: ModelBuilderConfig` — Produce a `ModelBuilderConfig` for the solver.
-- `roles: readonly string[]` — Declared role names.
-- `skills: readonly string[]` — Declared skill names.
-- `timeNames: readonly string[]` — Names of declared semantic times.
-- `shiftPatternIds: readonly string[]` — Shift pattern IDs.
-- `ruleNames: readonly string[]` — Internal rule identifiers in kebab-case (e.g., "max-hours-day", "time-off").
-
-### `RuntimeArgs`
-
-Runtime arguments passed to `ScheduleDefinition.createSchedulerConfig`.
-
-Separates data known at runtime (team roster, date range, ad-hoc rules)
-from the static schedule definition. Runtime rules are merged after the
-definition's own rules and undergo the same `appliesTo` resolution.
-
-**Properties:**
-- `schedulingPeriod: SchedulingPeriod` — The scheduling period (date range + optional filters).
-- `members: SchedulingMember[]` — Team members available for this scheduling run.
-- `runtimeRules?: RuleEntry[]` — Ad-hoc rules injected at runtime (e.g., vacation, holiday closures).
-
----
-
-## Time Periods
-
-### `t`
-
-Creates a `TimeOfDay` value.
-
-**Example:**
-Hours only
-```ts
-t(9)   // { hours: 9, minutes: 0 }
-```
-
-**Example:**
-Hours and minutes
-```ts
-t(17, 30)  // { hours: 17, minutes: 30 }
-```
-
-**Parameters:**
-- `hours: number` — Hour component (0-23)
-- `minutes: number` — Minute component (0-59)
-
-**Returns:** `TimeOfDay`
-
-### `time`
-
-Defines a named time window.
-
-A semantic time is any recurring period you need to reference:
-service hours, delivery windows, peak periods, weekly events. Times
-may overlap (e.g., "dinner" 18:00-22:00 and "happy_hour"
-17:30-18:30, or "lunch" 12:00-14:00 with "peak_lunch"
-13:00-13:30). Coverage and rules reference these names; each
-generates independent constraints.
-
-Every argument is a `SemanticTimeVariant` with `startTime`/`endTime`
-and optional `dayOfWeek`/`dates` scoping. An entry without scoping is the
-default (applies when no scoped entry matches). At most one default is
-allowed. If no default, the time only exists on the scoped days.
-
-Resolution precedence: `dates` > `dayOfWeek` > default.
-
-**Example:**
-Every day
-```typescript
-day_shift: time({ startTime: t(7), endTime: t(15) }),
-```
-
-**Example:**
-Default with weekend variant
-```typescript
-peak_hours: time(
-{ startTime: t(9), endTime: t(17) },
-{ startTime: t(10), endTime: t(15), dayOfWeek: weekend },
-),
-```
-
-**Example:**
-No default (specific days only)
-```typescript
-happy_hour: time(
-{ startTime: t(16), endTime: t(18), dayOfWeek: ["monday", "tuesday"] },
-{ startTime: t(17), endTime: t(19), dayOfWeek: ["friday"] },
-),
-```
-
-```ts
-time(entries: [SemanticTimeVariant, ...SemanticTimeVariant[]]): SemanticTimeEntry
-```
-
-### `weekdays`
-
-Monday through Friday.
-
-```typescript
-readonly DayOfWeek[]
-```
-
-### `weekend`
-
-Saturday and Sunday.
-
-```typescript
-readonly DayOfWeek[]
-```
-
----
-
-## Coverage
-
-### `cover`
-
-Defines a staffing requirement for a semantic time period.
-
-Two call forms are supported:
-
-**Simple form** `cover(time, target, count, opts?)` creates a single
-constraint. Use `dayOfWeek`/`dates` in `opts` to restrict which days
-it applies to.
-
-**Variant form** `cover(time, target, ...variants)` accepts one or more
-`CoverageVariant` entries with day-specific counts. For each
-scheduling day, exactly one variant is selected using the same
-precedence as `time`: `dates` > `dayOfWeek` > default (unscoped).
-At most one variant may be unscoped (the default). Days with no matching
-variant produce no coverage. See `CoverageVariant` for the entry
-shape.
-
-**Target resolution.** The `target` parameter is resolved against declared
-`roles` and `skills`:
-
-- Single string: matched against roles first, then skills.
-- Array of strings: OR logic (any of the listed roles).
-- With `skills` option (simple form only): role AND skill(s) filter.
-
-**Example:**
-Basic role coverage
-```ts
-cover("day_shift", "nurse", 3)
-```
-
-**Example:**
-OR logic (any of the listed roles)
-```ts
-cover("day_shift", ["manager", "team_lead"], 1)
-```
-
-**Example:**
-Skill-based coverage
-```ts
-cover("night_shift", "keyholder", 1)
-```
-
-**Example:**
-Role with skill filter (role AND skill)
-```ts
-cover("day_shift", "nurse", 1, { skills: ["charge_nurse"] })
-```
-
-**Example:**
-Day-of-week scoping (simple form)
-```ts
-cover("peak_hours", "cashier", 3, { dayOfWeek: weekdays }),
-cover("peak_hours", "cashier", 5, { dayOfWeek: weekend }),
-```
-
-**Example:**
-Default with date override (variant form)
-```ts
-cover("peak_hours", "agent",
-{ count: 4 },
-{ count: 2, dates: ["2025-12-24"] },
-)
-```
-
-**Example:**
-Weekday vs weekend with holiday override (variant form)
-```ts
-cover("peak_hours", "agent",
-{ count: 3, dayOfWeek: weekdays },
-{ count: 5, dayOfWeek: weekend },
-{ count: 8, dates: ["2025-12-31"] },
-)
-```
-
-**Parameters:**
-- `timeName: T` — Name of a declared semantic time
-- `target: R | [R, ...R[]]` — Role name, skill name, or array of role names (OR)
-- `count: number` — Number of people needed (simple form)
-- `opts?: CoverageOptions` — See `CoverageOptions` (simple form)
-
-**Returns:** `CoverageEntry<T, R>`
-
-### `CoverageOptions`
-
-Options for a `cover` call.
-
-Day/date scoping controls which days this coverage entry applies to.
-An entry without `dayOfWeek` or `dates` applies every day in the
-scheduling period.
-
-**Properties:**
-- `skills?: [string, ...string[]]` — Additional skill filter (AND logic with the target role).
-- `dayOfWeek?: readonly DayOfWeek[]` — Restrict to specific days of the week.
-- `dates?: string[]` — Restrict to specific dates (YYYY-MM-DD).
-- `priority?: Priority` — Defaults to `"MANDATORY"`.
-
-### `CoverageVariant`
-
-A day-specific count within a variant `cover` call.
-
-Each variant specifies a count and optional day/date scope. During
-resolution, the most specific matching variant wins for each day
-(`dates` > `dayOfWeek` > default), mirroring `SemanticTimeVariant`.
-At most one variant may be unscoped (the default).
-
-**Example:**
-```typescript
-// Default: 4 agents. Christmas Eve: 2.
-cover("peak_hours", "agent",
-  { count: 4 },
-  { count: 2, dates: ["2025-12-24"] },
-)
-```
-
-**Properties:**
-- `count: number` — Number of people needed.
-- `dayOfWeek?: readonly DayOfWeek[]` — Restrict this variant to specific days of the week.
-- `dates?: string[]` — Restrict this variant to specific dates (YYYY-MM-DD).
-- `priority?: Priority` — Defaults to `"MANDATORY"`.
-
----
-
-## Shift Patterns
-
-### `shift`
-
-Creates a `ShiftPattern` (time slot template).
-
-Shift patterns define when people can work: the concrete time slots
-the solver may assign members to. Each pattern repeats across all
-scheduling days unless filtered by `dayOfWeek` or `roles`.
-
-**Example:**
-```typescript
-shift("early", t(6), t(14)),
-shift("day", t(9), t(17)),
-shift("night", t(22), t(6), { roles: ["nurse", "doctor"] }),
-```
-
-```ts
-shift(id: string, startTime: TimeOfDay, endTime: TimeOfDay, opts?: Pick<ShiftPattern, "roles" | "dayOfWeek" | "locationId">): ShiftPattern
-```
-
----
-
-## Rules
-
-### `RuleOptions`
-
-Scoping options shared by most rule functions.
-
-Each rule function returns an opaque `RuleEntry` for the `rules`
-array. Most accept a `RuleOptions` parameter for scoping and priority.
-
-**Entity scoping.** `appliesTo` targets a role name, skill name, or
-member ID. It is resolved against declared roles first, then skills,
-then runtime member IDs. The namespaces are guaranteed disjoint by
-validation. Unscoped rules apply to all members.
-
-**Time scoping.** `dayOfWeek`, `dateRange`, `dates`, and
-`recurringPeriods` narrow when the rule is active. Unscoped rules
-apply to every day in the scheduling period.
-
-**Priority.** Defaults to `MANDATORY` (hard constraint the solver
-must satisfy). Use `LOW`, `MEDIUM`, or `HIGH` for soft preferences
-the solver may violate when necessary.
-
-**Properties:**
-- `appliesTo?: string | string[]` — Who this rule applies to (role name, skill name, or member ID).
-- `dayOfWeek?: readonly DayOfWeek[]` — Restrict to specific days of the week.
-- `dateRange?: { start: string; end: string }` — Restrict to a date range.
-- `dates?: string[]` — Restrict to specific dates (YYYY-MM-DD).
-- `recurringPeriods?: [RecurringPeriod, ...RecurringPeriod[]]` — Restrict to recurring calendar periods.
-- `priority?: Priority` — Defaults to `"MANDATORY"`.
-
-### `EntityOnlyRuleOptions`
-
-Options for rules that support entity scoping only (no time scoping).
-
-Used by rules whose semantics are inherently per-day or per-week
-(e.g., `minHoursPerDay`, `maxConsecutiveDays`) and cannot
-be meaningfully restricted to a date range or day of week.
-
-**Properties:**
-- `appliesTo?: string | string[]` — Who this rule applies to (role name, skill name, or member ID).
-- `priority?: Priority` — Defaults to `"MANDATORY"`.
-
-### `TimeOffOptions`
-
-Options for `timeOff`.
-
-At least one time scoping field is required (`dayOfWeek`, `dateRange`,
-`dates`, or `recurringPeriods`). Use `from`/`until` to block only part
-of a day.
-
-**Properties:**
-- `appliesTo?: string | string[]` — Who this rule applies to (role name, skill name, or member ID).
-- `from?: TimeOfDay` — Off from this time until end of day.
-- `until?: TimeOfDay` — Off from start of day until this time.
-- `dayOfWeek?: readonly DayOfWeek[]` — Restrict to specific days of the week.
-- `dateRange?: { start: string; end: string }` — Restrict to a date range.
-- `dates?: string[]` — Restrict to specific dates (YYYY-MM-DD).
-- `recurringPeriods?: [RecurringPeriod, ...RecurringPeriod[]]` — Restrict to recurring calendar periods.
-- `priority?: Priority` — Defaults to `"MANDATORY"`.
-
-### `CostRuleOptions`
-
-Options for cost rules.
-
-Cost rules are objective terms, not constraints. The `priority` field from
-`RuleOptions` does not apply.
-
-**Properties:**
-- `appliesTo?: string | string[]` — Who this rule applies to (role name, skill name, or member ID).
-- `dayOfWeek?: DayOfWeek[]` — Restrict to specific days of the week.
-- `dateRange?: { start: string; end: string }` — Restrict to a date range.
-- `dates?: string[]` — Restrict to specific dates (YYYY-MM-DD).
-- `recurringPeriods?: [RecurringPeriod, ...RecurringPeriod[]]` — Restrict to recurring calendar periods.
-
-### `maxHoursPerDay`
-
-Limits how many hours a person can work in a single day.
-
-**Example:**
-Global limit
-```ts
-maxHoursPerDay(10)
-```
-
-**Example:**
-Scoped to a role
-```ts
-maxHoursPerDay(6, { appliesTo: "student" })
-```
-
-```ts
-maxHoursPerDay(hours: number, opts?: RuleOptions): RuleEntry
-```
-
-### `maxHoursPerWeek`
-
-Caps total hours a person can work within each scheduling week.
-
-**Example:**
-Global cap
-```ts
-maxHoursPerWeek(48)
-```
-
-**Example:**
-Part-time cap for a skill group
-```ts
-maxHoursPerWeek(20, { appliesTo: "part_time" })
-```
-
-```ts
-maxHoursPerWeek(hours: number, opts?: RuleOptions): RuleEntry
-```
-
-### `minHoursPerDay`
-
-Ensures a person works at least a minimum number of hours per day when assigned.
-
-**Example:**
-```ts
-minHoursPerDay(4)
-```
-
-```ts
-minHoursPerDay(hours: number, opts?: EntityOnlyRuleOptions): RuleEntry
-```
-
-### `minHoursPerWeek`
-
-Enforces a minimum total number of hours per scheduling week.
-
-**Example:**
-Guaranteed minimum for full-time members
-```ts
-minHoursPerWeek(30, { appliesTo: "full_time" })
-```
-
-```ts
-minHoursPerWeek(hours: number, opts?: EntityOnlyRuleOptions): RuleEntry
-```
-
-### `maxShiftsPerDay`
-
-Limits how many shifts a person can work in a single day.
-
-**Example:**
-One shift per day
-```ts
-maxShiftsPerDay(1)
-```
-
-```ts
-maxShiftsPerDay(shifts: number, opts?: RuleOptions): RuleEntry
-```
-
-### `maxConsecutiveDays`
-
-Limits how many consecutive days a person can be assigned.
-
-**Example:**
-Five-day work week limit
-```ts
-maxConsecutiveDays(5)
-```
-
-```ts
-maxConsecutiveDays(days: number, opts?: EntityOnlyRuleOptions): RuleEntry
-```
-
-### `minConsecutiveDays`
-
-Requires a minimum stretch of consecutive working days once assigned.
-
-**Example:**
-```ts
-minConsecutiveDays(2)
-```
-
-```ts
-minConsecutiveDays(days: number, opts?: EntityOnlyRuleOptions): RuleEntry
-```
-
-### `minRestBetweenShifts`
-
-Enforces a minimum rest period between any two shifts a person works.
-
-**Example:**
-EU Working Time Directive (11 hours)
-```ts
-minRestBetweenShifts(11)
-```
-
-```ts
-minRestBetweenShifts(hours: number, opts?: EntityOnlyRuleOptions): RuleEntry
-```
-
-### `preference`
-
-Adds objective weight to prefer or avoid assigning team members.
-
-**Example:**
-Prefer assigning full-time staff
-```ts
-preference("high", { appliesTo: "full_time" })
-```
-
-**Example:**
-Avoid assigning a specific member on weekends
-```ts
-preference("low", { appliesTo: "alice", dayOfWeek: weekend })
-```
-
-**Parameters:**
-- `level: "high" | "low"` — `"high"` to prefer assigning, `"low"` to avoid
-- `opts?: Omit<RuleOptions, "priority">` — Entity and time scoping (no priority; preference is the priority mechanism)
-
-**Returns:** `RuleEntry`
-
-### `preferLocation`
-
-Prefers assigning a person to shift patterns at a specific location.
-
-**Example:**
-```ts
-preferLocation("north_wing", { appliesTo: "alice" })
-```
-
-```ts
-preferLocation(locationId: string, opts?: EntityOnlyRuleOptions): RuleEntry
-```
-
-### `timeOff`
-
-Blocks or penalizes assignments during specified time periods.
-
-At least one time scoping field is required (`dayOfWeek`, `dateRange`,
-`dates`, or `recurringPeriods`).
-
-Use `from` for "off from this time until end of day" and `until` for
-"off from start of day until this time."
-
-**Example:**
-```typescript
-timeOff({ appliesTo: "mauro", dayOfWeek: weekend }),
-timeOff({ appliesTo: "student", dayOfWeek: ["wednesday"], from: t(14) }),
-timeOff({ appliesTo: "alice", dateRange: { start: "2024-02-01", end: "2024-02-05" } }),
-```
-
-```ts
-timeOff(opts: TimeOffOptions): RuleEntry
-```
-
-### `assignTogether`
-
-Encourages or enforces that team members work the same shifts on a day.
-
-**Example:**
-```typescript
-assignTogether(["alice", "bob"], { priority: "HIGH" }),
-```
-
-```ts
-assignTogether(members: [string, string, ...string[]], opts?: AssignTogetherOptions): RuleEntry
-```
-
-### `minimizeCost`
-
-Tells the solver to minimize total labor cost.
-
-Without this rule, cost modifiers only affect post-solve calculation.
-When present, the solver actively prefers cheaper assignments.
-
-For hourly members, penalizes each assignment proportionally to cost.
-For salaried members, adds a fixed weekly salary cost when they have
-any assignment that week (zero marginal cost up to contracted hours).
-
-**Example:**
-```ts
-minimizeCost()
-```
-
-```ts
-minimizeCost(opts?: CostRuleOptions): RuleEntry
-```
-
-### `dayMultiplier`
-
-Multiplies the base rate for assignments on specified days.
-
-The base cost (1x) is already counted by `minimizeCost`;
-this rule adds only the extra portion above 1x.
-
-**Example:**
-Weekend multiplier
-```typescript
-dayMultiplier(1.5, { dayOfWeek: weekend })
-```
-
-```ts
-dayMultiplier(factor: number, opts?: CostRuleOptions): RuleEntry
-```
-
-### `daySurcharge`
-
-Adds a flat extra amount per hour for assignments on specified days.
-
-The surcharge is independent of the member's base rate.
-
-**Example:**
-Weekend surcharge
-```typescript
-daySurcharge(500, { dayOfWeek: weekend })
-```
-
-```ts
-daySurcharge(amountPerHour: number, opts?: CostRuleOptions): RuleEntry
-```
-
-### `timeSurcharge`
-
-Adds a flat surcharge per hour for the portion of a shift that overlaps a time-of-day window.
-
-The window supports overnight spans (e.g., 22:00-06:00). The surcharge
-is independent of the member's base rate.
-
-**Example:**
-Night differential
-```typescript
-timeSurcharge(200, { from: t(22), until: t(6) })
-```
-
-**Parameters:**
-- `amountPerHour: number` — Flat surcharge per hour in smallest currency unit
-- `window: { from: TimeOfDay; until: TimeOfDay }` — Time-of-day window
-- `opts?: CostRuleOptions` — Entity and time scoping
-
-**Returns:** `RuleEntry`
-
-### `overtimeMultiplier`
-
-Applies a multiplier to hours beyond a weekly threshold.
-
-Only the extra portion above 1x is added (the base cost is already
-counted by `minimizeCost`).
-
-**Example:**
-```typescript
-overtimeMultiplier({ after: 40, factor: 1.5 })
-```
-
-```ts
-overtimeMultiplier(opts: { after: number; factor: number } & CostRuleOptions): RuleEntry
-```
-
-### `overtimeSurcharge`
-
-Adds a flat surcharge per hour beyond a weekly threshold.
-
-The surcharge is independent of the member's base rate.
-
-**Example:**
-```typescript
-overtimeSurcharge({ after: 40, amount: 1000 })
-```
-
-```ts
-overtimeSurcharge(opts: { after: number; amount: number } & CostRuleOptions): RuleEntry
-```
-
-### `dailyOvertimeMultiplier`
-
-Applies a multiplier to hours beyond a daily threshold.
-
-Only the extra portion above 1x is added (the base cost is already
-counted by `minimizeCost`).
-
-**Example:**
-```typescript
-dailyOvertimeMultiplier({ after: 8, factor: 1.5 })
-```
-
-```ts
-dailyOvertimeMultiplier(opts: { after: number; factor: number } & CostRuleOptions): RuleEntry
-```
-
-### `dailyOvertimeSurcharge`
-
-Adds a flat surcharge per hour beyond a daily threshold.
-
-The surcharge is independent of the member's base rate.
-
-**Example:**
-```typescript
-dailyOvertimeSurcharge({ after: 8, amount: 500 })
-```
-
-```ts
-dailyOvertimeSurcharge(opts: { after: number; amount: number } & CostRuleOptions): RuleEntry
-```
-
-### `tieredOvertimeMultiplier`
-
-Applies multiple overtime thresholds with increasing multipliers.
-
-Each tier applies only to the hours between its threshold and the next.
-Tiers must be sorted by threshold ascending.
-
-**Example:**
-```typescript
-// Hours 0-40: base rate
-// Hours 40-48: 1.5x
-// Hours 48+: 2.0x
-tieredOvertimeMultiplier([
-  { after: 40, factor: 1.5 },
-  { after: 48, factor: 2.0 },
-])
-```
-
-```ts
-tieredOvertimeMultiplier(tiers: [OvertimeTier, ...OvertimeTier[]], opts?: CostRuleOptions): RuleEntry
-```
-
----
-
-## Supporting Types
-
-### `TimeOfDay`
-
-Time of day representation (hours and minutes, with optional seconds/nanos).
-
-Used for defining shift start/end times and semantic time boundaries.
-Hours are in 24-hour format (0-23).
-
-**Example:**
-```typescript
-{ hours: 9, minutes: 0 }
-{ hours: 17, minutes: 30 }
-```
-
-**Properties:**
-- `hours: number`
-- `minutes: number`
-- `seconds?: number`
-- `nanos?: number`
-
-### `DayOfWeek`
-
-Day of the week identifier.
-
-```typescript
-"monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday"
-```
-
-### `SchedulingPeriod`
-
-Defines a scheduling period as a date range with optional filters.
-
-The `dateRange` specifies the overall scheduling window. Use `dayOfWeek`
-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 (closed Mon/Tue)
-```typescript
-const period: SchedulingPeriod = {
-dateRange: { start: '2025-02-03', end: '2025-02-09' },
-dayOfWeek: ['wednesday', 'thursday', 'friday', 'saturday', 'sunday'],
-};
-```
-
-**Properties:**
-- `dateRange: { start: string; end: string }` — The overall scheduling window (start and end are inclusive).
-Dates should be in YYYY-MM-DD format.
-- `dayOfWeek?: DayOfWeek[]` — Include only these days of the week.
-If omitted, all days of the week are included.
-- `dates?: string[]` — Include only these specific dates (YYYY-MM-DD) within the range.
-If omitted, all dates in the range are included (subject to dayOfWeek filter).
-
-### `SchedulingMember`
-
-A team member available for scheduling.
-
-Members are assigned to shift patterns by the solver based on
-coverage requirements, rules, and constraints.
-
-**Properties:**
-- `id: string` — Unique identifier for this member. Must not contain colons.
-- `roles: string[]` — Roles this member can fill (e.g. "nurse", "doctor").
-- `skills?: string[]` — Skills this member has (e.g. "charge_nurse", "forklift").
-- `pay?: HourlyPay | SalariedPay` — Base pay. Required when cost rules are used.
-
-### `HourlyPay`
-
-Pay per hour in the caller's smallest currency unit (e.g., pence, cents).
-
-**Properties:**
-- `hourlyRate: number` — Pay per hour in smallest currency unit.
-
-### `SalariedPay`
-
-Annual salary with contracted weekly hours.
-
-The solver treats salaried members as having a fixed weekly cost
-(`annual / 52`) that is incurred once they work any shift in a week.
-Additional shifts within the same week have zero marginal cost.
-
-Note: overtime multiplier rules apply only to hourly members.
-Overtime surcharge rules apply to all members regardless of pay type.
-
-**Properties:**
-- `annual: number` — Annual salary in smallest currency unit.
-- `hoursPerWeek: number` — Contracted hours per week. Reserved for future overtime support.
-
-### `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"
-```
-