dabke 0.82.0 → 0.84.0

package/dist/schedule/cost.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Cost optimization rules: minimize labor cost with modifiers.
+ *
+ *
+ * @example
+ * ```typescript
+ * rules: [
+ *   minimizeCost(),
+ *   dayMultiplier(1.5, { dayOfWeek: weekend }),
+ *   overtimeMultiplier({ after: 40, factor: 1.5 }),
+ *   dailyOvertimeSurcharge({ after: 8, amount: 500 }),
+ *   tieredOvertimeMultiplier([
+ *     { after: 40, factor: 1.5 },
+ *     { after: 48, factor: 2.0 },
+ *   ]),
+ * ]
+ * ```
+ *
+ * @module
+ */
+import type { DayOfWeek, TimeOfDay } from "../types.js";
+import type { OvertimeTier } from "../cpsat/rules/overtime-tiered-multiplier.js";
+import type { RecurringPeriod } from "../cpsat/rules/scope.types.js";
+import type { RuleEntry } from "./rules.js";
+/**
+ * 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[]];
+}
+/**
+ * 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
+ *
+ * @category Cost Optimization
+ */
+export declare function minimizeCost(opts?: CostRuleOptions): RuleEntry<"minimize-cost", CostRuleOptions>;
+/**
+ * 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
+ */
+export declare function dayMultiplier(factor: number, opts?: CostRuleOptions): RuleEntry<"day-cost-multiplier", {
+    factor: number;
+} & CostRuleOptions>;
+/**
+ * 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
+ */
+export declare function daySurcharge(amountPerHour: number, opts?: CostRuleOptions): RuleEntry<"day-cost-surcharge", {
+    amountPerHour: number;
+} & CostRuleOptions>;
+/**
+ * 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
+ */
+export declare function timeSurcharge(amountPerHour: number, window: {
+    from: TimeOfDay;
+    until: TimeOfDay;
+}, opts?: CostRuleOptions): RuleEntry<"time-cost-surcharge", {
+    amountPerHour: number;
+    window: {
+        from: TimeOfDay;
+        until: TimeOfDay;
+    };
+} & CostRuleOptions>;
+/**
+ * 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
+ */
+export declare function overtimeMultiplier(opts: {
+    after: number;
+    factor: number;
+} & CostRuleOptions): RuleEntry<"overtime-weekly-multiplier", {
+    after: number;
+    factor: number;
+} & CostRuleOptions>;
+/**
+ * Adds a flat surcharge per hour beyond a weekly threshold.
+ *
+ * @remarks
+ * The surcharge is independent of the member's base rate.
+ *
+ * @category Cost Optimization
+ */
+export declare function overtimeSurcharge(opts: {
+    after: number;
+    amount: number;
+} & CostRuleOptions): RuleEntry<"overtime-weekly-surcharge", {
+    after: number;
+    amount: number;
+} & CostRuleOptions>;
+/**
+ * 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
+ */
+export declare function dailyOvertimeMultiplier(opts: {
+    after: number;
+    factor: number;
+} & CostRuleOptions): RuleEntry<"overtime-daily-multiplier", {
+    after: number;
+    factor: number;
+} & CostRuleOptions>;
+/**
+ * Adds a flat surcharge per hour beyond a daily threshold.
+ *
+ * @remarks
+ * The surcharge is independent of the member's base rate.
+ *
+ * @category Cost Optimization
+ */
+export declare function dailyOvertimeSurcharge(opts: {
+    after: number;
+    amount: number;
+} & CostRuleOptions): RuleEntry<"overtime-daily-surcharge", {
+    after: number;
+    amount: number;
+} & CostRuleOptions>;
+/**
+ * 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
+ */
+export declare function tieredOvertimeMultiplier(tiers: [OvertimeTier, ...OvertimeTier[]], opts?: CostRuleOptions): RuleEntry<"overtime-tiered-multiplier", {
+    tiers: [OvertimeTier, ...OvertimeTier[]];
+} & CostRuleOptions>;
+//# sourceMappingURL=cost.d.ts.map

package/dist/schedule/cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../../src/schedule/cost.ts"],"names":[],"mappings":"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"}

package/dist/schedule/cost.js

@@ -0,0 +1,151 @@
+/**
+ * Cost optimization rules: minimize labor cost with modifiers.
+ *
+ *
+ * @example
+ * ```typescript
+ * rules: [
+ *   minimizeCost(),
+ *   dayMultiplier(1.5, { dayOfWeek: weekend }),
+ *   overtimeMultiplier({ after: 40, factor: 1.5 }),
+ *   dailyOvertimeSurcharge({ after: 8, amount: 500 }),
+ *   tieredOvertimeMultiplier([
+ *     { after: 40, factor: 1.5 },
+ *     { after: 48, factor: 2.0 },
+ *   ]),
+ * ]
+ * ```
+ *
+ * @module
+ */
+import { defineRule } from "./rules.js";
+// ============================================================================
+// Cost Rules
+// ============================================================================
+function makeCostRule(rule, fields) {
+    return defineRule(rule, fields);
+}
+/**
+ * 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
+ *
+ * @category Cost Optimization
+ */
+export function minimizeCost(opts) {
+    return makeCostRule("minimize-cost", { ...opts });
+}
+/**
+ * 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
+ */
+export function dayMultiplier(factor, opts) {
+    return makeCostRule("day-cost-multiplier", { factor, ...opts });
+}
+/**
+ * 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
+ */
+export function daySurcharge(amountPerHour, opts) {
+    return makeCostRule("day-cost-surcharge", { amountPerHour, ...opts });
+}
+/**
+ * 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
+ */
+export function timeSurcharge(amountPerHour, window, opts) {
+    return makeCostRule("time-cost-surcharge", { amountPerHour, window, ...opts });
+}
+/**
+ * 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
+ */
+export function overtimeMultiplier(opts) {
+    return makeCostRule("overtime-weekly-multiplier", { ...opts });
+}
+/**
+ * Adds a flat surcharge per hour beyond a weekly threshold.
+ *
+ * @remarks
+ * The surcharge is independent of the member's base rate.
+ *
+ * @category Cost Optimization
+ */
+export function overtimeSurcharge(opts) {
+    return makeCostRule("overtime-weekly-surcharge", { ...opts });
+}
+/**
+ * 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
+ */
+export function dailyOvertimeMultiplier(opts) {
+    return makeCostRule("overtime-daily-multiplier", { ...opts });
+}
+/**
+ * Adds a flat surcharge per hour beyond a daily threshold.
+ *
+ * @remarks
+ * The surcharge is independent of the member's base rate.
+ *
+ * @category Cost Optimization
+ */
+export function dailyOvertimeSurcharge(opts) {
+    return makeCostRule("overtime-daily-surcharge", { ...opts });
+}
+/**
+ * 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
+ */
+export function tieredOvertimeMultiplier(tiers, opts) {
+    return makeCostRule("overtime-tiered-multiplier", { tiers, ...opts });
+}
+//# sourceMappingURL=cost.js.map

package/dist/schedule/cost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.js","sourceRoot":"","sources":["../../src/schedule/cost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA2BxC,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E,SAAS,YAAY,CACnB,IAAU,EACV,MAAc;IAEd,OAAO,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,YAAY,CAAC,IAAsB;IACjD,OAAO,YAAY,CAAC,eAAe,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAc,EACd,IAAsB;IAEtB,OAAO,YAAY,CAAC,qBAAqB,EAAE,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,aAAqB,EACrB,IAAsB;IAEtB,OAAO,YAAY,CAAC,oBAAoB,EAAE,EAAE,aAAa,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAC3B,aAAqB,EACrB,MAA6C,EAC7C,IAAsB;IAKtB,OAAO,YAAY,CAAC,qBAAqB,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAyD;IAEzD,OAAO,YAAY,CAAC,4BAA4B,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAyD;IAEzD,OAAO,YAAY,CAAC,2BAA2B,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAyD;IAEzD,OAAO,YAAY,CAAC,2BAA2B,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAyD;IAEzD,OAAO,YAAY,CAAC,0BAA0B,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAwC,EACxC,IAAsB;IAKtB,OAAO,YAAY,CAAC,4BAA4B,EAAE,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AACxE,CAAC"}

package/dist/schedule/coverage.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Coverage definitions: lower-bound staffing requirements per semantic time period.
+ *
+ * Coverage answers "what floor should apply throughout this scoped time, with
+ * the chosen priority?". It attaches sustained lower bounds to semantic times,
+ * whether those periods are
+ * explicit in the requirements or inferred to separate distinct business
+ * requirements. Coverage does not express caps, targets, fairness, or other
+ * assignment-shaping logic. Use rules for those concerns.
+ *
+ * @example
+ * ```typescript
+ * coverage: [
+ *   cover("lunch", "waiter", 2, { dayOfWeek: weekdays }),
+ *   cover("lunch", "waiter", 3, { dayOfWeek: weekend }),
+ *   cover("dinner", ["manager", "supervisor"], 1),
+ *   cover("opening", "keyholder", 1),
+ *
+ *   // Variant form: different counts by day
+ *   cover("peak_hours", "agent",
+ *     { count: 4 },
+ *     { count: 2, dates: ["2025-12-24"] },
+ *   ),
+ * ]
+ * ```
+ *
+ * @module
+ */
+import type { DateString, DayOfWeek } from "../types.js";
+import type { CoverageVariant } from "../cpsat/semantic-time.js";
+import type { Priority } from "../cpsat/types.js";
+export type { CoverageVariant } from "../cpsat/semantic-time.js";
+/**
+ * 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. Scope answers where the floor applies; it does not change
+ * the meaning of coverage itself. `priority` controls how hard the coverage floor is.
+ * Use it to distinguish language like "must keep 5 staffed on Saturdays"
+ * from "ideally keep 5 staffed on Mondays too" without changing the
+ * underlying coverage shape. `skillIds` is a hard filter, not a preference.
+ * Use it only when the required minimum truly needs those skills throughout
+ * the window. If a role or skill mix is preferred rather than required, model
+ * that with rules such as {@link preferAssignment} instead of skill-filtered
+ * coverage.
+ *
+ * @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?: DateString[];
+    /** 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
+ * Coverage always defines a lower bound that applies throughout the scoped
+ * semantic time, with strength controlled by `priority`. If the requirements
+ * also state an upper bound or productive
+ * cap, model that separately in `rules`, for example with
+ * {@link maxConcurrentAssignments}.
+ *
+ * Scope answers where the floor applies. Priority answers how strictly the
+ * solver should preserve that floor when trade-offs are necessary.
+ *
+ * Attach coverage to the narrowest semantic time that actually carries that
+ * minimum. Avoid layering a broad parent coverage window on top of narrower
+ * windows unless the same lower bound truly applies throughout the full span.
+ * If the requirements talk about hitting full occupancy at the busy point,
+ * prefer {@link targetPeakConcurrentAssignments} over turning that into a
+ * whole-window minimum. Do not infer a synthetic "peak" semantic time just to attach
+ * `cover(..., 5)` unless the requirements really define a sustained window
+ * that needs that minimum throughout.
+ *
+ * Overlapping entries for the same time and role produce independent
+ * constraints; the solver enforces the **max** count, not the sum.
+ * An unscoped entry acts as a floor that scoped entries cannot reduce.
+ * Use mutually exclusive scopes when different days need different coverage.
+ *
+ * @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`
+ *
+ * @category Coverage
+ */
+export declare function cover<T extends string, const R extends string>(timeName: T, target: R | [R, ...R[]], count: number, opts?: CoverageOptions): CoverageEntry<T, R>;
+export declare function cover<T extends string, const R extends string>(timeName: T, target: R | [R, ...R[]], ...variants: [CoverageVariant, ...CoverageVariant[]]): CoverageEntry<T, R>;
+//# sourceMappingURL=coverage.d.ts.map

package/dist/schedule/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/schedule/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,YAAY,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEjE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;IACjC,6CAA6C;IAC7C,SAAS,CAAC,EAAE,SAAS,CAAC,SAAS,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;IACjD,+CAA+C;IAC/C,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM;IACjF,gBAAgB,CAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC5C,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IACtC,gBAAgB,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;IAC1C,gBAAgB,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACxC,gBAAgB,CAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IACnD,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,MAAM,EAC5D,QAAQ,EAAE,CAAC,EACX,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,EACvB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,eAAe,GACrB,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACvB,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,MAAM,EAC5D,QAAQ,EAAE,CAAC,EACX,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,EACvB,GAAG,QAAQ,EAAE,CAAC,eAAe,EAAE,GAAG,eAAe,EAAE,CAAC,GACnD,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC"}

package/dist/schedule/coverage.js

@@ -0,0 +1,56 @@
+/**
+ * Coverage definitions: lower-bound staffing requirements per semantic time period.
+ *
+ * Coverage answers "what floor should apply throughout this scoped time, with
+ * the chosen priority?". It attaches sustained lower bounds to semantic times,
+ * whether those periods are
+ * explicit in the requirements or inferred to separate distinct business
+ * requirements. Coverage does not express caps, targets, fairness, or other
+ * assignment-shaping logic. Use rules for those concerns.
+ *
+ * @example
+ * ```typescript
+ * coverage: [
+ *   cover("lunch", "waiter", 2, { dayOfWeek: weekdays }),
+ *   cover("lunch", "waiter", 3, { dayOfWeek: weekend }),
+ *   cover("dinner", ["manager", "supervisor"], 1),
+ *   cover("opening", "keyholder", 1),
+ *
+ *   // Variant form: different counts by day
+ *   cover("peak_hours", "agent",
+ *     { count: 4 },
+ *     { count: 2, dates: ["2025-12-24"] },
+ *   ),
+ * ]
+ * ```
+ *
+ * @module
+ */
+export function cover(timeName, target, countOrFirstVariant, ...rest) {
+    if (typeof countOrFirstVariant === "number") {
+        // Simple form: cover(time, target, count, opts?)
+        return {
+            _type: "coverage",
+            timeName,
+            target,
+            count: countOrFirstVariant,
+            options: rest[0] ?? {},
+        };
+    }
+    // Variant form: cover(time, target, ...variants)
+    const variants = [countOrFirstVariant, ...rest];
+    const defaults = variants.filter((v) => !v.dayOfWeek && !v.dates);
+    if (defaults.length > 1) {
+        throw new Error("cover() accepts at most one default variant (without dayOfWeek or dates). " +
+            `Found ${defaults.length} default variants.`);
+    }
+    return {
+        _type: "coverage",
+        timeName,
+        target,
+        count: 0,
+        options: {},
+        variants,
+    };
+}
+//# sourceMappingURL=coverage.js.map

package/dist/schedule/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../../src/schedule/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAoGH,MAAM,UAAU,KAAK,CACnB,QAAW,EACX,MAAuB,EACvB,mBAA6C,EAC7C,GAAG,IAAe;IAElB,IAAI,OAAO,mBAAmB,KAAK,QAAQ,EAAE,CAAC;QAC5C,iDAAiD;QACjD,OAAO;YACL,KAAK,EAAE,UAAU;YACjB,QAAQ;YACR,MAAM;YACN,KAAK,EAAE,mBAAmB;YAC1B,OAAO,EAAG,IAAI,CAAC,CAAC,CAAiC,IAAI,EAAE;SACxD,CAAC;IACJ,CAAC;IAED,iDAAiD;IACjD,MAAM,QAAQ,GAAG,CAAC,mBAAmB,EAAE,GAAI,IAA0B,CAAC,CAAC;IAEvE,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAClE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,4EAA4E;YAC1E,SAAS,QAAQ,CAAC,MAAM,oBAAoB,CAC/C,CAAC;IACJ,CAAC;IAED,OAAO;QACL,KAAK,EAAE,UAAU;QACjB,QAAQ;QACR,MAAM;QACN,KAAK,EAAE,CAAC;QACR,OAAO,EAAE,EAAE;QACX,QAAQ;KACT,CAAC;AACJ,CAAC"}