dabke 0.83.0 → 0.84.0

package/dist/schedule/cost.d.ts

@@ -1,6 +1,21 @@
 /**
  * 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";
@@ -51,14 +66,9 @@ export interface CostRuleOptions {
  * - `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;
+export declare function minimizeCost(opts?: CostRuleOptions): RuleEntry<"minimize-cost", CostRuleOptions>;
 /**
  * Multiplies the base rate for assignments on specified days.
  *
@@ -67,13 +77,10 @@ export declare function minimizeCost(opts?: CostRuleOptions): RuleEntry;
  * 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;
+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.
  *
@@ -81,13 +88,10 @@ export declare function dayMultiplier(factor: number, opts?: CostRuleOptions): R
  * 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;
+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.
  *
@@ -100,16 +104,17 @@ export declare function daySurcharge(amountPerHour: number, opts?: CostRuleOptio
  * @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;
+}, opts?: CostRuleOptions): RuleEntry<"time-cost-surcharge", {
+    amountPerHour: number;
+    window: {
+        from: TimeOfDay;
+        until: TimeOfDay;
+    };
+} & CostRuleOptions>;
 /**
  * Applies a multiplier to hours beyond a weekly threshold.
  *
@@ -118,16 +123,14 @@ export declare function timeSurcharge(amountPerHour: number, window: {
  * 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;
+} & CostRuleOptions): RuleEntry<"overtime-weekly-multiplier", {
+    after: number;
+    factor: number;
+} & CostRuleOptions>;
 /**
  * Adds a flat surcharge per hour beyond a weekly threshold.
  *
@@ -135,16 +138,14 @@ export declare function overtimeMultiplier(opts: {
  * 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;
+} & CostRuleOptions): RuleEntry<"overtime-weekly-surcharge", {
+    after: number;
+    amount: number;
+} & CostRuleOptions>;
 /**
  * Applies a multiplier to hours beyond a daily threshold.
  *
@@ -153,16 +154,14 @@ export declare function overtimeSurcharge(opts: {
  * 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;
+} & CostRuleOptions): RuleEntry<"overtime-daily-multiplier", {
+    after: number;
+    factor: number;
+} & CostRuleOptions>;
 /**
  * Adds a flat surcharge per hour beyond a daily threshold.
  *
@@ -170,16 +169,14 @@ export declare function dailyOvertimeMultiplier(opts: {
  * 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;
+} & CostRuleOptions): RuleEntry<"overtime-daily-surcharge", {
+    after: number;
+    amount: number;
+} & CostRuleOptions>;
 /**
  * Applies multiple overtime thresholds with increasing multipliers.
  *
@@ -188,17 +185,8 @@ export declare function dailyOvertimeSurcharge(opts: {
  * 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;
+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

@@ -1 +1 @@
-{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../../src/schedule/cost.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8CAA8C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAO5C;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9B,6CAA6C;IAC7C,SAAS,CAAC,EAAE,SAAS,CAAC,SAAS,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;IACjD,gCAAgC;IAChC,SAAS,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,8CAA8C;IAC9C,gBAAgB,CAAC,EAAE,CAAC,eAAe,EAAE,GAAG,eAAe,EAAE,CAAC,CAAC;CAC5D;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,eAAe,GAAG,SAAS,CAE9D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,SAAS,CAE/E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,SAAS,CAErF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAC3B,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,EAC7C,IAAI,CAAC,EAAE,eAAe,GACrB,SAAS,CAEX;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,eAAe,GACxD,SAAS,CAEX;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,eAAe,GACxD,SAAS,CAEX;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,eAAe,GACxD,SAAS,CAEX;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,eAAe,GACxD,SAAS,CAEX;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,CAAC,YAAY,EAAE,GAAG,YAAY,EAAE,CAAC,EACxC,IAAI,CAAC,EAAE,eAAe,GACrB,SAAS,CAEX"}
+{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../../src/schedule/cost.ts"],"names":[],"mappings":"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"}

package/dist/schedule/cost.js

@@ -1,6 +1,21 @@
 /**
  * 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";
@@ -31,11 +46,6 @@ function makeCostRule(rule, fields) {
  * - `dailyOvertimeSurcharge({ after, amount }, opts?)` - daily overtime surcharge
  * - `tieredOvertimeMultiplier(tiers, opts?)` - multiple overtime thresholds
  *
- * @example
- * ```ts
- * minimizeCost()
- * ```
- *
  * @category Cost Optimization
  */
 export function minimizeCost(opts) {
@@ -49,11 +59,6 @@ export function minimizeCost(opts) {
  * this rule adds only the extra portion above 1x.
  *
  * @category Cost Optimization
- *
- * @example Weekend multiplier
- * ```typescript
- * dayMultiplier(1.5, { dayOfWeek: weekend })
- * ```
  */
 export function dayMultiplier(factor, opts) {
     return makeCostRule("day-cost-multiplier", { factor, ...opts });
@@ -65,11 +70,6 @@ export function dayMultiplier(factor, opts) {
  * The surcharge is independent of the member's base rate.
  *
  * @category Cost Optimization
- *
- * @example Weekend surcharge
- * ```typescript
- * daySurcharge(500, { dayOfWeek: weekend })
- * ```
  */
 export function daySurcharge(amountPerHour, opts) {
     return makeCostRule("day-cost-surcharge", { amountPerHour, ...opts });
@@ -86,11 +86,6 @@ export function daySurcharge(amountPerHour, opts) {
  * @param opts - Entity and time scoping
  *
  * @category Cost Optimization
- *
- * @example Night differential
- * ```typescript
- * timeSurcharge(200, { from: t(22), until: t(6) })
- * ```
  */
 export function timeSurcharge(amountPerHour, window, opts) {
     return makeCostRule("time-cost-surcharge", { amountPerHour, window, ...opts });
@@ -103,11 +98,6 @@ export function timeSurcharge(amountPerHour, window, opts) {
  * counted by {@link minimizeCost}).
  *
  * @category Cost Optimization
- *
- * @example
- * ```typescript
- * overtimeMultiplier({ after: 40, factor: 1.5 })
- * ```
  */
 export function overtimeMultiplier(opts) {
     return makeCostRule("overtime-weekly-multiplier", { ...opts });
@@ -119,11 +109,6 @@ export function overtimeMultiplier(opts) {
  * The surcharge is independent of the member's base rate.
  *
  * @category Cost Optimization
- *
- * @example
- * ```typescript
- * overtimeSurcharge({ after: 40, amount: 1000 })
- * ```
  */
 export function overtimeSurcharge(opts) {
     return makeCostRule("overtime-weekly-surcharge", { ...opts });
@@ -136,11 +121,6 @@ export function overtimeSurcharge(opts) {
  * counted by {@link minimizeCost}).
  *
  * @category Cost Optimization
- *
- * @example
- * ```typescript
- * dailyOvertimeMultiplier({ after: 8, factor: 1.5 })
- * ```
  */
 export function dailyOvertimeMultiplier(opts) {
     return makeCostRule("overtime-daily-multiplier", { ...opts });
@@ -152,11 +132,6 @@ export function dailyOvertimeMultiplier(opts) {
  * The surcharge is independent of the member's base rate.
  *
  * @category Cost Optimization
- *
- * @example
- * ```typescript
- * dailyOvertimeSurcharge({ after: 8, amount: 500 })
- * ```
  */
 export function dailyOvertimeSurcharge(opts) {
     return makeCostRule("overtime-daily-surcharge", { ...opts });
@@ -169,17 +144,6 @@ export function dailyOvertimeSurcharge(opts) {
  * 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 function tieredOvertimeMultiplier(tiers, opts) {
     return makeCostRule("overtime-tiered-multiplier", { tiers, ...opts });

package/dist/schedule/cost.js.map

@@ -1 +1 @@
-{"version":3,"file":"cost.js","sourceRoot":"","sources":["../../src/schedule/cost.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA2BxC,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E,SAAS,YAAY,CAAC,IAAY,EAAE,MAA+B;IACjE,OAAO,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,YAAY,CAAC,IAAsB;IACjD,OAAO,YAAY,CAAC,eAAe,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,IAAsB;IAClE,OAAO,YAAY,CAAC,qBAAqB,EAAE,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,aAAqB,EAAE,IAAsB;IACxE,OAAO,YAAY,CAAC,oBAAoB,EAAE,EAAE,aAAa,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa,CAC3B,aAAqB,EACrB,MAA6C,EAC7C,IAAsB;IAEtB,OAAO,YAAY,CAAC,qBAAqB,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAyD;IAEzD,OAAO,YAAY,CAAC,4BAA4B,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAyD;IAEzD,OAAO,YAAY,CAAC,2BAA2B,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAyD;IAEzD,OAAO,YAAY,CAAC,2BAA2B,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAyD;IAEzD,OAAO,YAAY,CAAC,0BAA0B,EAAE,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAwC,EACxC,IAAsB;IAEtB,OAAO,YAAY,CAAC,4BAA4B,EAAE,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;AACxE,CAAC"}
+{"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

@@ -1,9 +1,32 @@
 /**
- * Coverage definitions: staffing requirements per semantic time period.
+ * 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 { DayOfWeek } from "../types.js";
+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";
@@ -13,7 +36,15 @@ export type { CoverageVariant } from "../cpsat/semantic-time.js";
  * @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.
+ * 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
  */
@@ -23,7 +54,7 @@ export interface CoverageOptions {
     /** Restrict to specific days of the week. */
     dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]];
     /** Restrict to specific dates (YYYY-MM-DD). */
-    dates?: string[];
+    dates?: DateString[];
     /** Defaults to `"MANDATORY"`. */
     priority?: Priority;
 }
@@ -48,36 +79,34 @@ export interface CoverageEntry<T extends string = string, R extends string = str
  * 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.
+ * 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`
  *
- * @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, const R extends string>(timeName: T, target: R | [R, ...R[]], count: number, opts?: CoverageOptions): CoverageEntry<T, R>;

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

@@ -1 +1 @@
-{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/schedule/coverage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,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;;;;;;;;;GASG;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,MAAM,EAAE,CAAC;IACjB,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;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"}
+{"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

@@ -1,5 +1,28 @@
 /**
- * Coverage definitions: staffing requirements per semantic time period.
+ * 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
  */

package/dist/schedule/coverage.js.map

@@ -1 +1 @@
-{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../../src/schedule/coverage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA8FH,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"}
+{"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"}