dabke 0.82.0 → 0.83.0

package/dist/schedule.d.ts

@@ -1,917 +0,0 @@
-/**
- * High-level schedule definition API.
- *
- * Small, composable factory functions that produce a complete scheduling
- * configuration. Designed for LLM code generation: each concept is a single
- * function call with per-call type safety.
- *
- * @example
- * ```typescript
- * import {
- *   schedule, t, time, cover, shift,
- *   maxHoursPerDay, maxHoursPerWeek, minRestBetweenShifts,
- *   weekdays, weekend,
- * } from "dabke";
- *
- * const venue = schedule({
- *   roleIds: ["cashier", "floor_lead", "stocker"],
- *   skillIds: ["keyholder"],
- *
- *   times: {
- *     opening: time({ startTime: t(8), endTime: t(10) }),
- *     peak_hours: time(
- *       { startTime: t(11), endTime: t(14) },
- *       { startTime: t(10), endTime: t(15), dayOfWeek: weekend },
- *     ),
- *     closing: time({ startTime: t(20), endTime: t(22) }),
- *   },
- *
- *   coverage: [
- *     cover("opening", "keyholder", 1),
- *     cover("peak_hours", "cashier", 3, { dayOfWeek: weekdays }),
- *     cover("peak_hours", "cashier", 5, { dayOfWeek: weekend }),
- *     cover("closing", "floor_lead", 1),
- *   ],
- *
- *   shiftPatterns: [
- *     shift("morning", t(8), t(14)),
- *     shift("afternoon", t(14), t(22)),
- *   ],
- *
- *   rules: [
- *     maxHoursPerDay(10),
- *     maxHoursPerWeek(48),
- *     minRestBetweenShifts(10),
- *   ],
- * });
- *
- * const result = await venue
- *   .with([
- *     { id: "alice", roleIds: ["cashier"], skillIds: ["keyholder"] },
- *   ])
- *   .solve(client, { dateRange: { start: "2025-03-03", end: "2025-03-09" } });
- * ```
- *
- * @module
- */
-import type { DayOfWeek, TimeOfDay } from "./types.js";
-import type { SemanticTimeVariant, SemanticTimeEntry, CoverageVariant } from "./cpsat/semantic-time.js";
-export type { CoverageVariant } from "./cpsat/semantic-time.js";
-import type { CompilationResult } from "./cpsat/model-builder.js";
-import { ModelBuilder } from "./cpsat/model-builder.js";
-import type { SchedulingMember, ShiftPattern, Priority } from "./cpsat/types.js";
-import type { CreateCpsatRuleFunction } from "./cpsat/rules/rules.types.js";
-import type { RecurringPeriod } from "./cpsat/rules/scope.types.js";
-import type { OvertimeTier } from "./cpsat/rules/overtime-tiered-multiplier.js";
-import type { SolverClient } from "./client.types.js";
-import type { ShiftAssignment } from "./cpsat/response.js";
-import type { ScheduleValidation } from "./cpsat/validation.types.js";
-import type { CostBreakdown } from "./cpsat/cost.js";
-/**
- * Creates a {@link TimeOfDay} value.
- *
- * @param hours - Hour component (0-23)
- * @param minutes - Minute component (0-59)
- *
- * @example Hours only
- * ```ts
- * t(9)   // { hours: 9, minutes: 0 }
- * ```
- *
- * @example Hours and minutes
- * ```ts
- * t(17, 30)  // { hours: 17, minutes: 30 }
- * ```
- *
- * @category Time Periods
- */
-export declare function t(hours: number, minutes?: number): TimeOfDay;
-/**
- * Monday through Friday.
- *
- * @category Time Periods
- */
-export declare const weekdays: readonly ["monday", "tuesday", "wednesday", "thursday", "friday"];
-/**
- * Saturday and Sunday.
- *
- * @category Time Periods
- */
-export declare const weekend: readonly ["saturday", "sunday"];
-/**
- * Define a named semantic time period.
- *
- * @remarks
- * Each entry has `startTime`/`endTime` and optional `dayOfWeek` or `dates`
- * scoping. Entries without scoping are the default.
- *
- * @example
- * ```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) }),
- * }
- * ```
- *
- * @privateRemarks
- * Resolution precedence: `dates` > `dayOfWeek` > default.
- *
- * @category Time Periods
- */
-export declare function time(...entries: [SemanticTimeVariant, ...SemanticTimeVariant[]]): SemanticTimeEntry;
-/**
- * Options for a {@link cover} call.
- *
- * @remarks
- * Day/date scoping controls which days this coverage entry applies to.
- * An entry without `dayOfWeek` or `dates` applies every day in the
- * scheduling period.
- *
- * @category Coverage
- */
-export interface CoverageOptions {
-    /** Additional skill ID filter (AND logic with the target role). */
-    skillIds?: [string, ...string[]];
-    /** Restrict to specific days of the week. */
-    dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]];
-    /** Restrict to specific dates (YYYY-MM-DD). */
-    dates?: string[];
-    /** Defaults to `"MANDATORY"`. */
-    priority?: Priority;
-}
-/**
- * A coverage entry returned by {@link cover}.
- *
- * @remarks
- * Carries the semantic time name and target type information for
- * compile-time validation by {@link schedule}. This is an opaque
- * token; pass it directly into the `coverage` array.
- */
-export interface CoverageEntry<T extends string = string, R extends string = string> {
-    /** @internal */ readonly _type: "coverage";
-    /** @internal */ readonly timeName: T;
-    /** @internal */ readonly target: R | R[];
-    /** @internal */ readonly count: number;
-    /** @internal */ readonly options: CoverageOptions;
-    /** @internal  When present, this entry uses variant-based resolution. */
-    readonly variants?: readonly CoverageVariant[];
-}
-/**
- * Defines a staffing requirement for a semantic time period.
- *
- * @remarks
- * Entries for the same time and role **stack additively**.
- * For weekday vs weekend staffing, use mutually exclusive `dayOfWeek`
- * on both entries.
- *
- * @param timeName - Name of a declared semantic time
- * @param target - Role name (string), array of role names (OR logic), or skill name
- * @param count - Number of people needed
- * @param opts - Options: `skillIds` (AND filter), `dayOfWeek`, `dates`, `priority`
- *
- * @example
- * ```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 }),
- * ]
- * ```
- *
- * @category Coverage
- */
-export declare function cover<T extends string, R extends string>(timeName: T, target: R | [R, ...R[]], count: number, opts?: CoverageOptions): CoverageEntry<T, R>;
-export declare function cover<T extends string, R extends string>(timeName: T, target: R | [R, ...R[]], ...variants: [CoverageVariant, ...CoverageVariant[]]): CoverageEntry<T, R>;
-/**
- * Define a shift pattern: a time slot available for employee assignment.
- *
- * @remarks
- * Each pattern repeats daily unless filtered by `dayOfWeek`.
- *
- * @example
- * ```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" }),
- * ]
- * ```
- *
- * @category Shift Patterns
- */
-export declare function shift(id: string, startTime: TimeOfDay, endTime: TimeOfDay, opts?: Pick<ShiftPattern, "roleIds" | "dayOfWeek" | "locationId">): ShiftPattern;
-/**
- * Scoping options shared by most rule functions.
- *
- * @remarks
- * 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., {@link maxConsecutiveDays}) ignore time scoping.
- *
- * @category Rules
- */
-export interface RuleOptions {
-    /** Who this rule applies to (role name, skill name, or member ID). */
-    appliesTo?: string | string[];
-    /** Restrict to specific days of the week. */
-    dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]];
-    /** Restrict to a date range. */
-    dateRange?: {
-        start: string;
-        end: string;
-    };
-    /** Restrict to specific dates (YYYY-MM-DD). */
-    dates?: string[];
-    /** Restrict to recurring calendar periods. */
-    recurringPeriods?: [RecurringPeriod, ...RecurringPeriod[]];
-    /** Defaults to `"MANDATORY"`. */
-    priority?: Priority;
-}
-/**
- * Options for rules that support entity scoping only (no time scoping).
- *
- * @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.
- *
- * @category Rules
- */
-export interface EntityOnlyRuleOptions {
-    /** Who this rule applies to (role name, skill name, or member ID). */
-    appliesTo?: string | string[];
-    /** Defaults to `"MANDATORY"`. */
-    priority?: Priority;
-}
-/**
- * Options for {@link timeOff}.
- *
- * @remarks
- * At least one time scoping field is required (`dayOfWeek`, `dateRange`,
- * `dates`, or `recurringPeriods`). Use `from`/`until` to block only part
- * of a day.
- *
- * @category Rules
- */
-export interface TimeOffOptions {
-    /** Who this rule applies to (role name, skill name, or member ID). */
-    appliesTo?: string | string[];
-    /** Off from this time until end of day. */
-    from?: TimeOfDay;
-    /** Off from start of day until this time. */
-    until?: TimeOfDay;
-    /** Restrict to specific days of the week. */
-    dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]];
-    /** Restrict to a date range. */
-    dateRange?: {
-        start: string;
-        end: string;
-    };
-    /** Restrict to specific dates (YYYY-MM-DD). */
-    dates?: string[];
-    /** Restrict to recurring calendar periods. */
-    recurringPeriods?: [RecurringPeriod, ...RecurringPeriod[]];
-    /** Defaults to `"MANDATORY"`. */
-    priority?: Priority;
-}
-/**
- * Options for {@link assignTogether}.
- *
- * @category Rules
- */
-export interface AssignTogetherOptions {
-    /** Defaults to `"MANDATORY"`. */
-    priority?: Priority;
-}
-/**
- * Options for cost rules.
- *
- * Cost rules are objective terms, not constraints. The `priority` field from
- * {@link RuleOptions} does not apply.
- *
- * @category Cost Optimization
- */
-export interface CostRuleOptions {
-    /** Who this rule applies to (role name, skill name, or member ID). */
-    appliesTo?: string | string[];
-    /** Restrict to specific days of the week. */
-    dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]];
-    /** Restrict to a date range. */
-    dateRange?: {
-        start: string;
-        end: string;
-    };
-    /** Restrict to specific dates (YYYY-MM-DD). */
-    dates?: string[];
-    /** Restrict to recurring calendar periods. */
-    recurringPeriods?: [RecurringPeriod, ...RecurringPeriod[]];
-}
-/**
- * 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.
- *
- * @category Rules
- */
-export interface RuleResolveContext {
-    readonly roles: ReadonlySet<string>;
-    readonly skills: ReadonlySet<string>;
-    readonly memberIds: ReadonlySet<string>;
-}
-interface RuleEntryBase {
-    readonly _type: "rule";
-    readonly _rule: string;
-    /**
-     * 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;
-    };
-}
-/**
- * An opaque rule entry returned by rule functions.
- *
- * @remarks
- * Pass these directly into the `rules` array of {@link ScheduleConfig}.
- * The internal fields are resolved during compilation.
- */
-export type RuleEntry = RuleEntryBase & Record<string, unknown>;
-/**
- * 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.
- *
- * @param name - Rule name. Must match a key in the rule factory 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.
- *
- * @category Rules
- */
-export declare function defineRule(name: string, fields: Record<string, unknown>, resolve?: (ctx: RuleResolveContext) => Record<string, unknown> & {
-    name: string;
-}): RuleEntry;
-/**
- * Limits hours per day.
- *
- * @example
- * ```typescript
- * maxHoursPerDay(10)
- * maxHoursPerDay(4, { appliesTo: "student", dayOfWeek: weekdays })
- * ```
- *
- * @category Rules
- */
-export declare function maxHoursPerDay(hours: number, opts?: RuleOptions): RuleEntry;
-/**
- * Limits hours per scheduling week.
- *
- * @example
- * ```typescript
- * maxHoursPerWeek(48)
- * maxHoursPerWeek(20, { appliesTo: "student" })
- * ```
- *
- * @category Rules
- */
-export declare function maxHoursPerWeek(hours: number, opts?: RuleOptions): RuleEntry;
-/**
- * Minimum hours when assigned on a day.
- *
- * @example
- * ```typescript
- * minHoursPerDay(4)
- * ```
- *
- * @category Rules
- */
-export declare function minHoursPerDay(hours: number, opts?: EntityOnlyRuleOptions): RuleEntry;
-/**
- * Minimum hours per scheduling week.
- *
- * @example
- * ```typescript
- * minHoursPerWeek(20, { priority: "HIGH" })
- * ```
- *
- * @category Rules
- */
-export declare function minHoursPerWeek(hours: number, opts?: EntityOnlyRuleOptions): RuleEntry;
-/**
- * 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;
-/**
- * Maximum consecutive working days.
- *
- * @example
- * ```typescript
- * maxConsecutiveDays(5)
- * ```
- *
- * @category Rules
- */
-export declare function maxConsecutiveDays(days: number, opts?: EntityOnlyRuleOptions): RuleEntry;
-/**
- * Once working, continue for at least this many consecutive days.
- *
- * @example
- * ```typescript
- * minConsecutiveDays(2, { priority: "HIGH" })
- * ```
- *
- * @category Rules
- */
-export declare function minConsecutiveDays(days: number, opts?: EntityOnlyRuleOptions): RuleEntry;
-/**
- * Minimum rest hours between shifts.
- *
- * @example
- * ```typescript
- * minRestBetweenShifts(10)
- * ```
- *
- * @category Rules
- */
-export declare function minRestBetweenShifts(hours: number, opts?: EntityOnlyRuleOptions): RuleEntry;
-/**
- * Prefer (`"high"`) or avoid (`"low"`) assigning. Requires `appliesTo`.
- *
- * @example
- * ```typescript
- * preference("high", { appliesTo: "waiter" })
- * preference("low", { appliesTo: "student", dayOfWeek: weekdays })
- * ```
- *
- * @category Rules
- */
-export declare function preference(level: "high" | "low", opts?: Omit<RuleOptions, "priority">): RuleEntry;
-/**
- * Prefer assigning to shifts at a specific location. Requires `appliesTo`.
- *
- * @example
- * ```typescript
- * preferLocation("terrace", { appliesTo: "alice" })
- * ```
- *
- * @category Rules
- */
-export declare function preferLocation(locationId: string, opts?: EntityOnlyRuleOptions): RuleEntry;
-/**
- * Tells the solver to minimize total labor cost.
- *
- * @remarks
- * 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
- *
- * @example
- * ```ts
- * minimizeCost()
- * ```
- *
- * @category Cost Optimization
- */
-export declare function minimizeCost(opts?: CostRuleOptions): RuleEntry;
-/**
- * Multiplies the base rate for assignments on specified days.
- *
- * @remarks
- * The base cost (1x) is already counted by {@link minimizeCost};
- * this rule adds only the extra portion above 1x.
- *
- * @category Cost Optimization
- *
- * @example Weekend multiplier
- * ```typescript
- * dayMultiplier(1.5, { dayOfWeek: weekend })
- * ```
- */
-export declare function dayMultiplier(factor: number, opts?: CostRuleOptions): RuleEntry;
-/**
- * Adds a flat extra amount per hour for assignments on specified days.
- *
- * @remarks
- * The surcharge is independent of the member's base rate.
- *
- * @category Cost Optimization
- *
- * @example Weekend surcharge
- * ```typescript
- * daySurcharge(500, { dayOfWeek: weekend })
- * ```
- */
-export declare function daySurcharge(amountPerHour: number, opts?: CostRuleOptions): RuleEntry;
-/**
- * Adds a flat surcharge per hour for the portion of a shift that overlaps a time-of-day window.
- *
- * @remarks
- * The window supports overnight spans (e.g., 22:00-06:00). The surcharge
- * is independent of the member's base rate.
- *
- * @param amountPerHour - Flat surcharge per hour in smallest currency unit
- * @param window - Time-of-day window
- * @param opts - Entity and time scoping
- *
- * @category Cost Optimization
- *
- * @example Night differential
- * ```typescript
- * timeSurcharge(200, { from: t(22), until: t(6) })
- * ```
- */
-export declare function timeSurcharge(amountPerHour: number, window: {
-    from: TimeOfDay;
-    until: TimeOfDay;
-}, opts?: CostRuleOptions): RuleEntry;
-/**
- * Applies a multiplier to hours beyond a weekly threshold.
- *
- * @remarks
- * Only the extra portion above 1x is added (the base cost is already
- * counted by {@link minimizeCost}).
- *
- * @category Cost Optimization
- *
- * @example
- * ```typescript
- * overtimeMultiplier({ after: 40, factor: 1.5 })
- * ```
- */
-export declare function overtimeMultiplier(opts: {
-    after: number;
-    factor: number;
-} & CostRuleOptions): RuleEntry;
-/**
- * Adds a flat surcharge per hour beyond a weekly threshold.
- *
- * @remarks
- * The surcharge is independent of the member's base rate.
- *
- * @category Cost Optimization
- *
- * @example
- * ```typescript
- * overtimeSurcharge({ after: 40, amount: 1000 })
- * ```
- */
-export declare function overtimeSurcharge(opts: {
-    after: number;
-    amount: number;
-} & CostRuleOptions): RuleEntry;
-/**
- * Applies a multiplier to hours beyond a daily threshold.
- *
- * @remarks
- * Only the extra portion above 1x is added (the base cost is already
- * counted by {@link minimizeCost}).
- *
- * @category Cost Optimization
- *
- * @example
- * ```typescript
- * dailyOvertimeMultiplier({ after: 8, factor: 1.5 })
- * ```
- */
-export declare function dailyOvertimeMultiplier(opts: {
-    after: number;
-    factor: number;
-} & CostRuleOptions): RuleEntry;
-/**
- * Adds a flat surcharge per hour beyond a daily threshold.
- *
- * @remarks
- * The surcharge is independent of the member's base rate.
- *
- * @category Cost Optimization
- *
- * @example
- * ```typescript
- * dailyOvertimeSurcharge({ after: 8, amount: 500 })
- * ```
- */
-export declare function dailyOvertimeSurcharge(opts: {
-    after: number;
-    amount: number;
-} & CostRuleOptions): RuleEntry;
-/**
- * Applies multiple overtime thresholds with increasing multipliers.
- *
- * @remarks
- * Each tier applies only to the hours between its threshold and the next.
- * Tiers must be sorted by threshold ascending.
- *
- * @category Cost Optimization
- *
- * @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 },
- * ])
- * ```
- */
-export declare function tieredOvertimeMultiplier(tiers: [OvertimeTier, ...OvertimeTier[]], opts?: CostRuleOptions): 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 declare function timeOff(opts: TimeOffOptions): RuleEntry;
-/**
- * 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 declare function assignTogether(memberIds: [string, string, ...string[]], opts?: AssignTogetherOptions): RuleEntry;
-/** A value that can be passed to {@link Schedule.with}. */
-type WithArg = Schedule | SchedulingMember[];
-/** Status of a solve attempt, using idiomatic lowercase TypeScript literals. */
-export type SolveStatus = "optimal" | "feasible" | "infeasible" | "no_solution";
-/**
- * Result of {@link Schedule.solve}.
- *
- * @category Schedule Definition
- */
-export interface SolveResult {
-    /** Outcome of the solve attempt. */
-    status: SolveStatus;
-    /** Shift assignments (empty when infeasible or no solution). */
-    assignments: ShiftAssignment[];
-    /** Validation diagnostics from compilation. */
-    validation: ScheduleValidation;
-    /** Cost breakdown (present when cost rules are used and a solution is found). */
-    cost?: CostBreakdown;
-}
-/**
- * Options for {@link Schedule.solve} and {@link Schedule.compile}.
- *
- * @category Schedule Definition
- */
-export interface SolveOptions {
-    /** The date range to schedule. */
-    dateRange: {
-        start: string;
-        end: string;
-    };
-    /**
-     * 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.
-     */
-    pinned?: ShiftAssignment[];
-}
-/**
- * Configuration for {@link schedule}.
- *
- * @remarks
- * 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 {@link cover} for details.
- *
- * `roleIds`, `times`, `coverage`, and `shiftPatterns` are required.
- * These four fields form the minimum solvable schedule.
- *
- * @category Schedule Definition
- */
-export interface ScheduleConfig<R extends readonly string[] = readonly string[], S extends readonly string[] = readonly string[], T extends Record<string, SemanticTimeEntry> = Record<string, SemanticTimeEntry>> {
-    /** Declared role IDs. */
-    roleIds: R;
-    /** Declared skill IDs. */
-    skillIds?: S;
-    /** Named semantic time periods. */
-    times: T;
-    /** Staffing requirements per time period (entries stack additively). */
-    coverage: CoverageEntry<keyof T & string, R[number] | NonNullable<S>[number]>[];
-    /** Available shift patterns. */
-    shiftPatterns: ShiftPattern[];
-    /** Scheduling rules and constraints. */
-    rules?: RuleEntry[];
-    /**
-     * Custom rule factories. Keys are rule names, values are functions
-     * that take a config object and return a {@link CompilationRule}.
-     * Built-in rule names cannot be overridden.
-     */
-    ruleFactories?: Record<string, CreateCpsatRuleFunction>;
-    /** Team members (typically added via `.with()` at runtime). */
-    members?: SchedulingMember[];
-    /** Days of the week the business operates (inclusion filter). */
-    dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]];
-    /** Which day starts the week for weekly rules. Defaults to `"monday"`. */
-    weekStartsOn?: DayOfWeek;
-}
-/** Internal representation of a fully merged schedule. */
-interface MergedScheduleConfig {
-    roleIds: string[];
-    skillIds: string[];
-    times: Record<string, SemanticTimeEntry>;
-    coverage: CoverageEntry[];
-    shiftPatterns: ShiftPattern[];
-    rules: RuleEntry[];
-    ruleFactories: Record<string, CreateCpsatRuleFunction>;
-    members: SchedulingMember[];
-    dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]];
-    weekStartsOn?: DayOfWeek;
-}
-/**
- * An immutable schedule definition.
- *
- * Created by {@link schedule}, composed via {@link Schedule.with},
- * and solved via {@link Schedule.solve}.
- *
- * @category Schedule Definition
- */
-export declare class Schedule {
-    #private;
-    /** @internal */
-    constructor(config: MergedScheduleConfig);
-    /** @internal Returns a defensive copy of the config for merging. */
-    _getConfig(): MergedScheduleConfig;
-    /** Declared role IDs. */
-    get roleIds(): readonly string[];
-    /** Declared skill IDs. */
-    get skillIds(): readonly string[];
-    /** Names of declared semantic times. */
-    get timeNames(): readonly string[];
-    /** Shift pattern IDs. */
-    get shiftPatternIds(): readonly string[];
-    /** Internal rule identifiers in kebab-case. */
-    get ruleNames(): readonly string[];
-    /**
-     * Merges schedules or members onto this schedule, returning a new
-     * immutable `Schedule`. The original is untouched.
-     *
-     * Accepts any mix of `Schedule` instances and `SchedulingMember[]` arrays.
-     *
-     * Merge semantics (when merging schedules):
-     * - Roles: union (additive)
-     * - Skills: union (additive)
-     * - Times: additive; error on name collision
-     * - Coverage: additive
-     * - Shift patterns: additive; error on ID collision
-     * - Rules: additive
-     * - Members: additive; error on duplicate ID
-     *
-     * Validation runs eagerly: role/skill disjointness, coverage targets
-     * referencing declared roles/skills, member role references, etc.
-     */
-    with(...args: WithArg[]): Schedule;
-    /**
-     * Compiles, validates, solves, and parses in one call.
-     *
-     * @param client - Solver client (e.g., `new HttpSolverClient(fetch, url)`)
-     * @param options - Date range and optional pinned assignments
-     */
-    solve(client: SolverClient, options: SolveOptions): Promise<SolveResult>;
-    /**
-     * Diagnostic escape hatch. Compiles the schedule without solving.
-     *
-     * @param options - Date range and optional pinned assignments
-     */
-    compile(options: SolveOptions): CompilationResult & {
-        builder: ModelBuilder;
-    };
-}
-/**
- * Create a schedule definition.
- *
- * Returns an immutable {@link Schedule} that can be composed via `.with()`
- * and solved via `.solve()`.
- *
- * @example
- * ```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),
- *   ],
- * });
- * ```
- *
- * @category Schedule Definition
- */
-export declare function schedule<const R extends readonly string[], const S extends readonly string[], const T extends Record<string, SemanticTimeEntry>>(config: ScheduleConfig<R, S, T>): Schedule;
-/**
- * Create a partial schedule for composition via `.with()`.
- *
- * Unlike {@link schedule}, all fields are optional. Use this for
- * schedules that layer rules, coverage, or other config onto a
- * complete base schedule.
- *
- * @example
- * ```typescript
- * const companyPolicy = partialSchedule({
- *   rules: [maxHoursPerWeek(40), minRestBetweenShifts(11)],
- * });
- *
- * const ready = venue.with(companyPolicy, teamMembers);
- * ```
- *
- * @category Schedule Definition
- */
-export declare function partialSchedule(config: Partial<ScheduleConfig>): Schedule;
-//# sourceMappingURL=schedule.d.ts.map