dabke 0.82.0 → 0.84.0

package/src/datetime.utils.ts

@@ -1,50 +1,46 @@
-import type { DayOfWeek, SchedulingPeriod } from "./types.js";
-
-export const DAY_OF_WEEK_MAP: Record<DayOfWeek, number> = {
-  sunday: 0, // JavaScript Date week starts on Sunday
-  monday: 1,
-  tuesday: 2,
-  wednesday: 3,
-  thursday: 4,
-  friday: 5,
-  saturday: 6,
-};
-
-const DAY_NAMES = [
-  "sunday",
-  "monday",
-  "tuesday",
-  "wednesday",
-  "thursday",
-  "friday",
-  "saturday",
-] as const;
+import {
+  DAY_NAMES,
+  type DateString,
+  type DayOfWeek,
+  type SchedulingDay,
+  type SchedulingPeriod,
+} from "./types.js";
 
 /**
- * Helper to get the day of week name from a Date (UTC).
- * Use this when working with date strings like "2026-01-10" that are timezone-agnostic.
+ * Builds a {@link SchedulingDay} from an existing UTC `Date`, avoiding a
+ * redundant `new Date()` call. Used internally by {@link resolveDaysFromPeriod}
+ * where the loop already maintains a `Date` cursor.
  */
-export function toDayOfWeekUTC(date: Date): DayOfWeek {
-  // getUTCDay() always returns 0-6
-  return DAY_NAMES[date.getUTCDay()] as DayOfWeek;
+function schedulingDayFromDate(date: Date, iso: DateString): SchedulingDay {
+  const dayOfWeek = DAY_NAMES[date.getUTCDay()]!;
+  const month = date.getUTCMonth() + 1;
+  const dayOfMonth = date.getUTCDate();
+  return {
+    iso,
+    dayOfWeek,
+    month,
+    dayOfMonth,
+    yearMonth: iso.slice(0, 7),
+    epochDay: Math.floor(date.getTime() / 86_400_000),
+  };
 }
 
 /**
- * Computes the list of day strings (YYYY-MM-DD) from a SchedulingPeriod.
+ * Computes the list of {@link SchedulingDay} values from a {@link SchedulingPeriod}.
  *
  * Generates all days between start and end (inclusive), applying optional
  * dayOfWeek and dates filters. Filters compose: a day must pass all
  * specified filters to be included.
  *
  * @param period - The scheduling period specification
- * @returns Array of day strings in YYYY-MM-DD format, sorted chronologically
+ * @returns Array of scheduling days, sorted chronologically
  *
  * @example All days in range
  * ```typescript
  * const days = resolveDaysFromPeriod({
  *   dateRange: { start: '2025-02-03', end: '2025-02-05' },
  * });
- * // Returns: ['2025-02-03', '2025-02-04', '2025-02-05']
+ * // Returns days for 2025-02-03, 2025-02-04, 2025-02-05
  * ```
  *
  * @example Day-of-week filter
@@ -53,7 +49,7 @@ export function toDayOfWeekUTC(date: Date): DayOfWeek {
  *   dateRange: { start: '2025-02-03', end: '2025-02-09' },
  *   dayOfWeek: ['wednesday', 'friday'],
  * });
- * // Returns: ['2025-02-05', '2025-02-07']
+ * // Returns days for 2025-02-05, 2025-02-07
  * ```
  *
  * @example Specific dates filter
@@ -62,31 +58,36 @@ export function toDayOfWeekUTC(date: Date): DayOfWeek {
  *   dateRange: { start: '2025-02-03', end: '2025-02-10' },
  *   dates: ['2025-02-05', '2025-02-07'],
  * });
- * // Returns: ['2025-02-05', '2025-02-07']
+ * // Returns days for 2025-02-05, 2025-02-07
  * ```
  */
-export function resolveDaysFromPeriod(period: SchedulingPeriod): string[] {
+export function resolveDaysFromPeriod(period: SchedulingPeriod): SchedulingDay[] {
   const { dateRange, dayOfWeek, dates } = period;
-  const allowedDays = dayOfWeek ? new Set(dayOfWeek) : null;
-  const allowedDates = dates ? new Set(dates) : null;
+  const allowedDays: Set<DayOfWeek> | null = dayOfWeek ? new Set(dayOfWeek) : null;
+  const allowedDates: Set<string> | null = dates ? new Set(dates) : null;
 
   const startDate = new Date(`${dateRange.start}T00:00:00Z`);
   const endDate = new Date(`${dateRange.end}T00:00:00Z`);
-  const result: string[] = [];
+  const result: SchedulingDay[] = [];
 
-  const current = new Date(startDate);
-  while (current <= endDate) {
+  for (
+    let currentTime = startDate.getTime(), endTime = endDate.getTime();
+    currentTime <= endTime;
+    currentTime += 24 * 60 * 60 * 1000
+  ) {
+    const current = new Date(currentTime);
     const year = current.getUTCFullYear();
     const month = (current.getUTCMonth() + 1).toString().padStart(2, "0");
-    const day = current.getUTCDate().toString().padStart(2, "0");
-    const iso = `${year}-${month}-${day}`;
-    const dow = toDayOfWeekUTC(current);
+    const d = current.getUTCDate().toString().padStart(2, "0");
+    const iso = `${year}-${month}-${d}` as DateString;
+    const day = schedulingDayFromDate(current, iso);
 
-    if ((!allowedDays || allowedDays.has(dow)) && (!allowedDates || allowedDates.has(iso))) {
-      result.push(iso);
+    if (
+      (!allowedDays || allowedDays.has(day.dayOfWeek)) &&
+      (!allowedDates || allowedDates.has(iso))
+    ) {
+      result.push(day);
     }
-
-    current.setUTCDate(current.getUTCDate() + 1);
   }
 
   return result;

package/src/index.ts

@@ -1,5 +1,7 @@
 /**
- * @privateRemarks
+ * Scheduling library powered by constraint programming (CP-SAT).
+ *
+ * @remarks
  * ## Core Concepts
  *
  * **Schedule**: The primary API. Small, composable functions
@@ -34,9 +36,9 @@
 // Time primitives
 // ============================================================================
 
-export type { TimeOfDay, DayOfWeek, SchedulingPeriod } from "./types.js";
+export type { DateString, TimeOfDay, DayOfWeek, SchedulingDay, SchedulingPeriod } from "./types.js";
 
-export { DayOfWeekSchema } from "./types.js";
+export { schedulingDay, DAY_OF_WEEK_INDEX, DayOfWeekSchema } from "./types.js";
 
 // ============================================================================
 // Solver client
@@ -49,13 +51,27 @@ export type {
   SolverRequest,
   SolverResponse,
   SolverStatus,
-  SoftConstraintViolation,
+  SolverMode,
+  SolverDiagnosticMode,
+  SolverObjectiveStage,
+  SolverStageResult,
+  SolverSoftConstraintViolation,
+  SolverHardConstraintConflict,
   FetcherLike,
 } from "./client.types.js";
 
 export { SOLVER_STATUS } from "./client.types.js";
 
-export { SolverRequestSchema, SolverResponseSchema, SolverStatusSchema } from "./client.schemas.js";
+export {
+  SolverModeSchema,
+  SolverDiagnosticModeSchema,
+  SolverObjectiveStageSchema,
+  SolverRequestSchema,
+  SolverResponseSchema,
+  SolverStageResultSchema,
+  SolverStatusSchema,
+  SolverHardConstraintConflictSchema,
+} from "./client.schemas.js";
 
 // ============================================================================
 // Model builder
@@ -63,14 +79,27 @@ export { SolverRequestSchema, SolverResponseSchema, SolverStatusSchema } from ".
 
 export { ModelBuilder } from "./cpsat/model-builder.js";
 
+export type { ModelBuilderConfig, CompilationResult } from "./cpsat/model-builder.js";
+export type { ModelSolveStrategy } from "./cpsat/types.js";
+
+export { compileRuleDescriptor, defineRuleDescriptor } from "./cpsat/rule-descriptor.js";
+
 export type {
-  ModelBuilderConfig,
-  CompilationResult,
-  CompilationRule,
-  RuleValidationContext,
+  CostValidationStrategy,
+  HardConstraintValidationStrategy,
+  ObjectiveValidationStrategy,
+  ReportHardConstraintValidationStrategy,
+  ReportSoftConstraintValidationStrategy,
+  RuleDescriptor,
+  RuleCompileContext,
+  RuleArtifact,
+  SkipValidationStrategy,
+  SoftConstraintValidationStrategy,
+  CompiledRule,
+  ValidationSkipCategory,
   CostEntry,
   CostContribution,
-} from "./cpsat/model-builder.js";
+} from "./cpsat/rule-descriptor.js";
 
 // ============================================================================
 // Solver response parsing
@@ -92,10 +121,19 @@ export type { CostBreakdown, MemberCostDetail, CostCalculationConfig } from "./c
 // Rules (registry types)
 // ============================================================================
 
+export {
+  assertValidCpsatRuleRegistry,
+  builtInCpsatRuleRegistry,
+  createCpsatRuleRegistry,
+} from "./cpsat/rules/registry.js";
+
 export type {
+  BuiltInCpsatRuleConfigRegistry,
+  BuiltInCpsatRuleRegistry,
+  CpsatRuleConfigByName,
   CpsatRuleConfigEntry,
-  CpsatRuleFactories,
-  CreateCpsatRuleFunction,
+  CpsatRuleConfigEntryFor,
+  CpsatRuleRegistry,
 } from "./cpsat/rules/rules.types.js";
 
 export type { RecurringPeriod } from "./cpsat/rules/scope.types.js";
@@ -148,6 +186,7 @@ export { summarizeValidation } from "./cpsat/validation-reporter.js";
 
 export {
   schedule,
+  scheduleWithRuleRegistry,
   partialSchedule,
   Schedule,
   t,
@@ -158,15 +197,26 @@ export {
   maxHoursPerWeek,
   minHoursPerDay,
   minHoursPerWeek,
+  maxDaysPerWeek,
+  minDaysPerWeek,
+  targetDaysPerWeek,
   maxShiftsPerDay,
+  maxConcurrentAssignments,
+  targetPeakConcurrentAssignments,
   maxConsecutiveDays,
   minConsecutiveDays,
   minRestBetweenShifts,
-  preference,
+  mustAssign,
+  preferAssignment,
+  avoidAssignment,
+  preferRole,
   preferLocation,
   timeOff,
   assignTogether,
+  maxDaysOfWeekPerPeriod,
+  minDaysOfWeekPerPeriod,
   defineRule,
+  defineRuleFor,
   minimizeCost,
   dayMultiplier,
   daySurcharge,
@@ -178,7 +228,7 @@ export {
   tieredOvertimeMultiplier,
   weekdays,
   weekend,
-} from "./schedule.js";
+} from "./schedule/index.js";
 
 export type {
   CoverageEntry,
@@ -187,12 +237,19 @@ export type {
   RuleEntry,
   RuleResolveContext,
   RuleOptions,
+  ScheduleRuleEntry,
   EntityOnlyRuleOptions,
+  TargetDaysPerWeekOptions,
   TimeOffOptions,
   AssignTogetherOptions,
+  MaxConcurrentAssignmentsOptions,
+  TargetPeakConcurrentAssignmentsOptions,
+  DaysOfWeekPerPeriodOptions,
   CostRuleOptions,
   ScheduleConfig,
+  ScheduleWithRuleRegistryConfig,
   SolveResult,
   SolveStatus,
+  SolveStrategy,
   SolveOptions,
-} from "./schedule.js";
+} from "./schedule/index.js";

package/src/schedule/cost.ts

@@ -0,0 +1,221 @@
+/**
+ * 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";
+import { defineRule } from "./rules.js";
+
+// ============================================================================
+// Cost Rule Options
+// ============================================================================
+
+/**
+ * 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[]];
+}
+
+// ============================================================================
+// Cost Rules
+// ============================================================================
+
+function makeCostRule<const Name extends string, const Fields extends object>(
+  rule: Name,
+  fields: Fields,
+): RuleEntry<Name, Omit<Fields, "_type" | "_rule">> {
+  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?: CostRuleOptions): RuleEntry<"minimize-cost", CostRuleOptions> {
+  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: number,
+  opts?: CostRuleOptions,
+): RuleEntry<"day-cost-multiplier", { factor: number } & CostRuleOptions> {
+  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: number,
+  opts?: CostRuleOptions,
+): RuleEntry<"day-cost-surcharge", { amountPerHour: number } & CostRuleOptions> {
+  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: number,
+  window: { from: TimeOfDay; until: TimeOfDay },
+  opts?: CostRuleOptions,
+): RuleEntry<
+  "time-cost-surcharge",
+  { amountPerHour: number; window: { from: TimeOfDay; until: TimeOfDay } } & CostRuleOptions
+> {
+  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: { after: number; factor: number } & CostRuleOptions,
+): RuleEntry<"overtime-weekly-multiplier", { after: number; factor: number } & CostRuleOptions> {
+  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: { after: number; amount: number } & CostRuleOptions,
+): RuleEntry<"overtime-weekly-surcharge", { after: number; amount: number } & CostRuleOptions> {
+  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: { after: number; factor: number } & CostRuleOptions,
+): RuleEntry<"overtime-daily-multiplier", { after: number; factor: number } & CostRuleOptions> {
+  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: { after: number; amount: number } & CostRuleOptions,
+): RuleEntry<"overtime-daily-surcharge", { after: number; amount: number } & CostRuleOptions> {
+  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: [OvertimeTier, ...OvertimeTier[]],
+  opts?: CostRuleOptions,
+): RuleEntry<
+  "overtime-tiered-multiplier",
+  { tiers: [OvertimeTier, ...OvertimeTier[]] } & CostRuleOptions
+> {
+  return makeCostRule("overtime-tiered-multiplier", { tiers, ...opts });
+}

package/src/schedule/coverage.ts

@@ -0,0 +1,164 @@
+/**
+ * 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 function cover<T extends string, const R extends string>(
+  timeName: T,
+  target: R | [R, ...R[]],
+  count: number,
+  opts?: CoverageOptions,
+): CoverageEntry<T, R>;
+export function cover<T extends string, const R extends string>(
+  timeName: T,
+  target: R | [R, ...R[]],
+  ...variants: [CoverageVariant, ...CoverageVariant[]]
+): CoverageEntry<T, R>;
+export function cover<T extends string, R extends string>(
+  timeName: T,
+  target: R | [R, ...R[]],
+  countOrFirstVariant: number | CoverageVariant,
+  ...rest: unknown[]
+): CoverageEntry<T, R> {
+  if (typeof countOrFirstVariant === "number") {
+    // Simple form: cover(time, target, count, opts?)
+    return {
+      _type: "coverage",
+      timeName,
+      target,
+      count: countOrFirstVariant,
+      options: (rest[0] as CoverageOptions | undefined) ?? {},
+    };
+  }
+
+  // Variant form: cover(time, target, ...variants)
+  const variants = [countOrFirstVariant, ...(rest as CoverageVariant[])];
+
+  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,
+  };
+}