dabke 0.82.0 → 0.83.0

package/llms.txt

@@ -1,758 +0,0 @@
-# dabke
-
-> Scheduling library powered by constraint programming (CP-SAT)
-
----
-
-## Schedule Definition
-
-### `SolveResult`
-
-Result of `Schedule.solve`.
-
-**Properties:**
-- `status: SolveStatus` — Outcome of the solve attempt.
-- `assignments: ShiftAssignment[]` — Shift assignments (empty when infeasible or no solution).
-- `validation: ScheduleValidation` — Validation diagnostics from compilation.
-- `cost?: CostBreakdown` — Cost breakdown (present when cost rules are used and a solution is found).
-
-### `SolveOptions`
-
-Options for `Schedule.solve` and `Schedule.compile`.
-
-**Properties:**
-- `dateRange: { start: string; end: string }` — The date range to schedule.
-- `pinned?: ShiftAssignment[]` — Fixed assignments from a prior solve (e.g., rolling schedule).
-These are injected as fixed variables in the solver.
-
-Not yet implemented. Providing pinned assignments throws an error.
-
-### `ScheduleConfig`
-
-Configuration for `schedule`.
-
-Coverage entries for the same semantic time and target stack additively.
-An unscoped entry applies every day; adding a weekend-only entry on top
-doubles the count on those days. Use mutually exclusive `dayOfWeek` on
-both entries to avoid stacking. See `cover` for details.
-
-`roleIds`, `times`, `coverage`, and `shiftPatterns` are required.
-These four fields form the minimum solvable schedule.
-
-**Properties:**
-- `roleIds: R` — Declared role IDs.
-- `skillIds?: S` — Declared skill IDs.
-- `times: T` — Named semantic time periods.
-- `coverage: CoverageEntry<keyof T & string, R[number] | NonNullable<S>[number]>[]` — Staffing requirements per time period (entries stack additively).
-- `shiftPatterns: ShiftPattern[]` — Available shift patterns.
-- `rules?: RuleEntry[]` — Scheduling rules and constraints.
-- `ruleFactories?: Record<string, CreateCpsatRuleFunction>` — Custom rule factories. Keys are rule names, values are functions
-that take a config object and return a `CompilationRule`.
-Built-in rule names cannot be overridden.
-- `members?: SchedulingMember[]` — Team members (typically added via `.with()` at runtime).
-- `dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]]` — Days of the week the business operates (inclusion filter).
-- `weekStartsOn?: DayOfWeek` — Which day starts the week for weekly rules. Defaults to `"monday"`.
-
-### `schedule`
-
-Create a schedule definition.
-
-Returns an immutable `Schedule` that can be composed via `.with()`
-and solved via `.solve()`.
-
-```typescript
-const venue = schedule({
-  roleIds: ["waiter", "runner", "manager"],
-  skillIds: ["senior"],
-  times: {
-    lunch: time({ startTime: t(12), endTime: t(15) }),
-    dinner: time(
-      { startTime: t(17), endTime: t(21) },
-      { startTime: t(18), endTime: t(22), dayOfWeek: weekend },
-    ),
-  },
-  coverage: [
-    cover("lunch", "waiter", 2),
-    cover("dinner", "waiter", 4, { dayOfWeek: weekdays }),
-    cover("dinner", "waiter", 5, { dayOfWeek: weekend }),
-    cover("dinner", "manager", 1),
-  ],
-  shiftPatterns: [
-    shift("lunch_shift", t(11, 30), t(15)),
-    shift("evening", t(17), t(22)),
-  ],
-  rules: [
-    maxHoursPerDay(10),
-    maxHoursPerWeek(48),
-    minRestBetweenShifts(11),
-  ],
-});
-```
-
-### `partialSchedule`
-
-Create a partial schedule for composition via `.with()`.
-
-Unlike `schedule`, all fields are optional. Use this for
-schedules that layer rules, coverage, or other config onto a
-complete base schedule.
-
-```typescript
-const companyPolicy = partialSchedule({
-  rules: [maxHoursPerWeek(40), minRestBetweenShifts(11)],
-});
-
-const ready = venue.with(companyPolicy, teamMembers);
-```
-
----
-
-## Time Periods
-
-### `t`
-
-Creates a `TimeOfDay` value.
-
-Hours only
-```ts
-t(9)   // { hours: 9, minutes: 0 }
-```
-
-**Parameters:**
-- `hours: number` — Hour component (0-23)
-- `minutes: number` — Minute component (0-59)
-
-**Returns:** `TimeOfDay`
-
-### `weekdays`
-
-Monday through Friday.
-
-```typescript
-readonly ["monday", "tuesday", "wednesday", "thursday", "friday"]
-```
-
-### `weekend`
-
-Saturday and Sunday.
-
-```typescript
-readonly ["saturday", "sunday"]
-```
-
-### `time`
-
-Define a named semantic time period.
-
-Each entry has `startTime`/`endTime` and optional `dayOfWeek` or `dates`
-scoping. Entries without scoping are the default.
-
-```typescript
-times: {
-  // Simple: same times every day
-  lunch: time({ startTime: t(12), endTime: t(15) }),
-
-  // Variants: different times on weekends
-  dinner: time(
-    { startTime: t(17), endTime: t(21) },
-    { startTime: t(18), endTime: t(22), dayOfWeek: weekend },
-  ),
-
-  // Point-in-time window (keyholder at opening)
-  opening: time({ startTime: t(8, 30), endTime: t(9) }),
-}
-```
-
----
-
-## Coverage
-
-### `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).
-
-```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, ...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"`.
-
-### `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:**
-- `skillIds?: [string, ...string[]]` — Additional skill ID filter (AND logic with the target role).
-- `dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]]` — Restrict to specific days of the week.
-- `dates?: string[]` — Restrict to specific dates (YYYY-MM-DD).
-- `priority?: Priority` — Defaults to `"MANDATORY"`.
-
-### `cover`
-
-Defines a staffing requirement for a semantic time period.
-
-Entries for the same time and role **stack additively**.
-For weekday vs weekend staffing, use mutually exclusive `dayOfWeek`
-on both entries.
-
-```typescript
-coverage: [
-  // 2 waiters during lunch
-  cover("lunch", "waiter", 2),
-
-  // 1 manager OR supervisor during dinner
-  cover("dinner", ["manager", "supervisor"], 1),
-
-  // 1 person with keyholder skill at opening
-  cover("opening", "keyholder", 1),
-
-  // 1 senior waiter (role + skill AND)
-  cover("lunch", "waiter", 1, { skillIds: ["senior"] }),
-
-  // Different counts by day (mutually exclusive dayOfWeek!)
-  cover("lunch", "waiter", 2, { dayOfWeek: weekdays }),
-  cover("lunch", "waiter", 3, { dayOfWeek: weekend }),
-]
-```
-
-**Parameters:**
-- `timeName: T` — Name of a declared semantic time
-- `target: R | [R, ...R[]]` — Role name (string), array of role names (OR logic), or skill name
-- `count: number` — Number of people needed
-- `opts?: CoverageOptions` — Options: `skillIds` (AND filter), `dayOfWeek`, `dates`, `priority`
-
-**Returns:** `CoverageEntry<T, R>`
-
----
-
-## Shift Patterns
-
-### `shift`
-
-Define a shift pattern: a time slot available for employee assignment.
-
-Each pattern repeats daily unless filtered by `dayOfWeek`.
-
-```typescript
-shiftPatterns: [
-  shift("morning", t(11, 30), t(15)),
-  shift("evening", t(17), t(22)),
-
-  // Role-restricted shift
-  shift("kitchen", t(6), t(14), { roleIds: ["chef", "prep_cook"] }),
-
-  // Day-restricted shift
-  shift("saturday_short", t(9), t(14), { dayOfWeek: ["saturday"] }),
-
-  // Location-specific shift
-  shift("terrace_lunch", t(12), t(16), { locationId: "terrace" }),
-]
-```
-
----
-
-## Rules
-
-### `RecurringPeriod`
-
-Recurring calendar period for time scoping.
-
-**Properties:**
-- `name: string`
-- `startMonth: number`
-- `startDay: number`
-- `endMonth: number`
-- `endDay: number`
-
-### `RuleOptions`
-
-Scoping options shared by most rule functions.
-
-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.
-Not all rules support all scoping options. Entity-only rules
-(e.g., `maxConsecutiveDays`) ignore time scoping.
-
-**Properties:**
-- `appliesTo?: string | string[]` — Who this rule applies to (role name, skill name, or member ID).
-- `dayOfWeek?: readonly [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.
-- `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, ...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"`.
-
-### `AssignTogetherOptions`
-
-Options for `assignTogether`.
-
-**Properties:**
-- `priority?: Priority` — Defaults to `"MANDATORY"`.
-
-### `RuleResolveContext`
-
-Context passed to a rule's resolve function during compilation.
-
-Contains the declared roles, skills, and member IDs so the resolver
-can translate user-facing fields (like `appliesTo`) into internal
-scoping fields.
-
-**Properties:**
-- `roles: ReadonlySet<string>`
-- `skills: ReadonlySet<string>`
-- `memberIds: ReadonlySet<string>`
-
-### `defineRule`
-
-Creates a rule entry for use in `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.
-
-**Parameters:**
-- `name: string` — Rule name. Must match a key in the rule factory registry.
-- `fields: Record<string, unknown>` — Rule-specific configuration fields.
-- `resolve?: (ctx: RuleResolveContext) => Record<string, unknown> & { name: string }` — 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.
-
-**Returns:** `RuleEntry`
-
-### `maxHoursPerDay`
-
-Limits hours per day.
-
-```typescript
-maxHoursPerDay(10)
-maxHoursPerDay(4, { appliesTo: "student", dayOfWeek: weekdays })
-```
-
-### `maxHoursPerWeek`
-
-Limits hours per scheduling week.
-
-```typescript
-maxHoursPerWeek(48)
-maxHoursPerWeek(20, { appliesTo: "student" })
-```
-
-### `minHoursPerDay`
-
-Minimum hours when assigned on a day.
-
-```typescript
-minHoursPerDay(4)
-```
-
-### `minHoursPerWeek`
-
-Minimum hours per scheduling week.
-
-```typescript
-minHoursPerWeek(20, { priority: "HIGH" })
-```
-
-### `maxShiftsPerDay`
-
-Maximum distinct shifts per day.
-
-```typescript
-maxShiftsPerDay(1)
-maxShiftsPerDay(2, { appliesTo: "student", dayOfWeek: weekend })
-```
-
-### `maxConsecutiveDays`
-
-Maximum consecutive working days.
-
-```typescript
-maxConsecutiveDays(5)
-```
-
-### `minConsecutiveDays`
-
-Once working, continue for at least this many consecutive days.
-
-```typescript
-minConsecutiveDays(2, { priority: "HIGH" })
-```
-
-### `minRestBetweenShifts`
-
-Minimum rest hours between shifts.
-
-```typescript
-minRestBetweenShifts(10)
-```
-
-### `preference`
-
-Prefer (`"high"`) or avoid (`"low"`) assigning. Requires `appliesTo`.
-
-```typescript
-preference("high", { appliesTo: "waiter" })
-preference("low", { appliesTo: "student", dayOfWeek: weekdays })
-```
-
-### `preferLocation`
-
-Prefer assigning to shifts at a specific location. Requires `appliesTo`.
-
-```typescript
-preferLocation("terrace", { appliesTo: "alice" })
-```
-
-### `timeOff`
-
-Block assignments during specified periods.
-Requires at least one time scope (`dayOfWeek`, `dateRange`, `dates`, or `from`/`until`).
-
-```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) })
-```
-
-### `assignTogether`
-
-Members work the same shifts on days they are both assigned.
-
-```typescript
-assignTogether(["alice", "bob"])
-assignTogether(["alice", "bob", "charlie"], { priority: "HIGH" })
-```
-
----
-
-## Cost Optimization
-
-### `OvertimeTier`
-
-A single tier in a tiered overtime configuration.
-
-```typescript
-{ after: number; factor: number; }
-```
-
-### `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?: readonly [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.
-
-### `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).
-
-Cost modifiers adjust the calculation:
-- `dayMultiplier(factor, opts?)` - multiply base rate on specific days
-- `daySurcharge(amount, opts?)` - flat extra per hour on specific days
-- `timeSurcharge(amount, window, opts?)` - flat extra per hour during a time window
-- `overtimeMultiplier({ after, factor }, opts?)` - weekly overtime multiplier
-- `overtimeSurcharge({ after, amount }, opts?)` - weekly overtime surcharge
-- `dailyOvertimeMultiplier({ after, factor }, opts?)` - daily overtime multiplier
-- `dailyOvertimeSurcharge({ after, amount }, opts?)` - daily overtime surcharge
-- `tieredOvertimeMultiplier(tiers, opts?)` - multiple overtime thresholds
-
-```ts
-minimizeCost()
-```
-
-### `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.
-
-Weekend multiplier
-```typescript
-dayMultiplier(1.5, { dayOfWeek: weekend })
-```
-
-### `daySurcharge`
-
-Adds a flat extra amount per hour for assignments on specified days.
-
-The surcharge is independent of the member's base rate.
-
-Weekend surcharge
-```typescript
-daySurcharge(500, { dayOfWeek: weekend })
-```
-
-### `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.
-
-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`).
-
-```typescript
-overtimeMultiplier({ after: 40, factor: 1.5 })
-```
-
-### `overtimeSurcharge`
-
-Adds a flat surcharge per hour beyond a weekly threshold.
-
-The surcharge is independent of the member's base rate.
-
-```typescript
-overtimeSurcharge({ after: 40, amount: 1000 })
-```
-
-### `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`).
-
-```typescript
-dailyOvertimeMultiplier({ after: 8, factor: 1.5 })
-```
-
-### `dailyOvertimeSurcharge`
-
-Adds a flat surcharge per hour beyond a daily threshold.
-
-The surcharge is independent of the member's base rate.
-
-```typescript
-dailyOvertimeSurcharge({ after: 8, amount: 500 })
-```
-
-### `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.
-
-```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 },
-])
-```
-
----
-
-## Supporting Types
-
-### `DayOfWeek`
-
-Day of the week identifier.
-
-```typescript
-"monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday"
-```
-
-### `TimeOfDay`
-
-Time of day (24-hour format).
-
-**Properties:**
-- `hours: number`
-- `minutes: number`
-
-### `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.
-
-All days in a week
-```typescript
-const period: SchedulingPeriod = {
-dateRange: { start: '2025-02-03', end: '2025-02-09' },
-};
-```
-
-**Properties:**
-- `dateRange: { start: string; end: string }` — The overall scheduling window (start and end are inclusive).
-Dates should be in YYYY-MM-DD format.
-- `dayOfWeek?: readonly 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).
-
-### `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"
-```
-
-### `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.
-- `roleIds: string[]` — Role IDs this member can fill (e.g. "nurse", "doctor").
-- `skillIds?: string[]` — Skill IDs this member has (e.g. "charge_nurse", "forklift").
-- `pay?: HourlyPay | SalariedPay` — Base pay. Required when cost rules are used.
-
-### `ShiftPattern`
-
-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.
-
-// Simple setup: one shift type, anyone can work it
-const patterns: ShiftPattern[] = [
-  { id: "day", startTime: { hours: 9 }, endTime: { hours: 17 } }
-];
-
-**Properties:**
-- `id: string` — Unique identifier for this shift pattern.
-Used in assignments and rule configurations.
-- `roleIds?: [string, ...string[]]` — Restricts who can be assigned to this shift based on their role IDs.
-
-- If omitted: anyone can work this shift
-- If provided: only team members whose roles overlap with this list can be assigned
-
-Most venues have the same shifts for everyone and don't need this.
-Use it when different roles have different schedules (e.g., kitchen staff starts
-earlier than floor staff).
-- `dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]]` — Restricts which days of the week this shift pattern can be used.
-
-- If omitted: shift can be used on any day
-- If provided: shift can only be assigned on the specified days
-
-```typescript
-// Saturday-only short shift
-{ id: "saturday_shift", startTime: t(9), endTime: t(14), dayOfWeek: ["saturday"] }
-
-// Weekday-only full shift
-{ id: "full_shift", startTime: t(9), endTime: t(18), dayOfWeek: ["monday", "tuesday", "wednesday", "thursday", "friday"] }
-```
-- `locationId?: string` — 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)
-