dabke 0.81.1 → 0.83.0

package/dist/types.d.ts

@@ -6,6 +6,8 @@
 import * as z from "zod";
 /**
  * Day of the week identifier.
+ *
+ * @category Supporting Types
  */
 export type DayOfWeek = "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday";
 /**
@@ -14,86 +16,13 @@ export type DayOfWeek = "monday" | "tuesday" | "wednesday" | "thursday" | "frida
  */
 export declare const DayOfWeekSchema: z.ZodUnion<readonly [z.ZodLiteral<"monday">, z.ZodLiteral<"tuesday">, z.ZodLiteral<"wednesday">, z.ZodLiteral<"thursday">, z.ZodLiteral<"friday">, z.ZodLiteral<"saturday">, z.ZodLiteral<"sunday">]>;
 /**
- * Time of day representation (hours and minutes, with optional seconds/nanos).
- *
- * Used for defining shift start/end times and semantic time boundaries.
- * Hours are in 24-hour format (0-23).
+ * Time of day (24-hour format).
  *
- * @example
- * ```typescript
- * { hours: 9, minutes: 0 }
- * { hours: 17, minutes: 30 }
- * ```
+ * @category Supporting Types
  */
 export interface TimeOfDay {
     hours: number;
     minutes: number;
-    seconds?: number;
-    nanos?: number;
-}
-/**
- * Calendar date representation (year, month, day).
- *
- * @example
- * ```typescript
- * const christmas: CalendarDate = {
- *   year: 2025,
- *   month: 12,
- *   day: 25
- * };
- * ```
- */
-export interface CalendarDate {
-    year: number;
-    month: number;
-    day: number;
-}
-/**
- * Time horizon defining the start and end dates for scheduling.
- *
- * Specifies the date range over which the schedule should be generated.
- * The range is inclusive of start date and exclusive of end date.
- *
- * @example
- * ```typescript
- * // One week schedule starting Monday, March 3, 2025
- * const horizon: TimeHorizon = {
- *   start: new Date('2025-03-03'),  // Monday
- *   end: new Date('2025-03-10')     // Following Monday (exclusive)
- * };
- * ```
- */
-export interface TimeHorizon {
-    start: Date;
-    end: Date;
-}
-export interface DateTimeComponents extends Partial<CalendarDate>, Partial<TimeOfDay> {
-}
-interface DateTimeWithUtcOffset extends DateTimeComponents {
-    utcOffset?: string;
-    timeZone?: never;
-}
-interface DateTimeWithTimeZone extends DateTimeComponents {
-    timeZone?: {
-        id: string;
-        version: string;
-    };
-    utcOffset?: never;
-}
-/**
- * Date and time representation supporting both UTC offset and timezone-aware formats.
- *
- * Can be specified either with a UTC offset (e.g., "-08:00") or with a timezone ID
- * (e.g., "America/Los_Angeles").
- */
-export type DateTime = DateTimeWithUtcOffset | DateTimeWithTimeZone;
-/**
- * Represents a time range with start and end DateTimes.
- * Used for checking overlaps and scheduling constraints.
- */
-export interface DateTimeRange {
-    start: DateTime;
-    end: DateTime;
 }
 /**
  * Defines a scheduling period as a date range with optional filters.
@@ -117,7 +46,15 @@ export interface DateTimeRange {
  * };
  * ```
  *
-
+ * @example Only specific dates within the range
+ * ```typescript
+ * const period: SchedulingPeriod = {
+ *   dateRange: { start: '2025-02-03', end: '2025-02-09' },
+ *   dates: ['2025-02-05', '2025-02-07'],
+ * };
+ * ```
+ *
+ * @category Supporting Types
  */
 export interface SchedulingPeriod {
     /**
@@ -132,12 +69,11 @@ export interface SchedulingPeriod {
      * Include only these days of the week.
      * If omitted, all days of the week are included.
      */
-    dayOfWeek?: DayOfWeek[];
+    dayOfWeek?: readonly DayOfWeek[];
     /**
      * Include only these specific dates (YYYY-MM-DD) within the range.
      * If omitted, all dates in the range are included (subject to dayOfWeek filter).
      */
     dates?: string[];
 }
-export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAMzB;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,UAAU,GACV,QAAQ,GACR,UAAU,GACV,QAAQ,CAAC;AAEb;;;GAGG;AAEH,eAAO,MAAM,eAAe,uMAQ1B,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,IAAI,CAAC;IACZ,GAAG,EAAE,IAAI,CAAC;CACX;AAMD,MAAM,WAAW,kBAAmB,SAAQ,OAAO,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC;CAAG;AAExF,UAAU,qBAAsB,SAAQ,kBAAkB;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,KAAK,CAAC;CAClB;AAED,UAAU,oBAAqB,SAAQ,kBAAkB;IACvD,QAAQ,CAAC,EAAE;QACT,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,SAAS,CAAC,EAAE,KAAK,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,qBAAqB,GAAG,oBAAoB,CAAC;AAEpE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,QAAQ,CAAC;IAChB,GAAG,EAAE,QAAQ,CAAC;CACf;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC;IACxB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAMzB;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,UAAU,GACV,QAAQ,GACR,UAAU,GACV,QAAQ,CAAC;AAEb;;;GAGG;AACH,eAAO,MAAM,eAAe,uMAQ1B,CAAC;AAEH;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB"}

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAkBzB;;;GAGG;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC;IACrC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACnB,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IACpB,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;IACtB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IACrB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACnB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IACrB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;CACpB,CAAC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAoBzB;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC;IACrC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACnB,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IACpB,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;IACtB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IACrB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACnB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IACrB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;CACpB,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dabke",
-  "version": "0.81.1",
+  "version": "0.83.0",
   "description": "Scheduling library powered by constraint programming (CP-SAT)",
   "keywords": [
     "constraint-programming",
@@ -26,7 +26,6 @@
     "CHANGELOG.md",
     "dist",
     "LICENSE",
-    "llms.txt",
     "README.md",
     "solver",
     "src"
@@ -40,10 +39,6 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./llms": {
-      "types": "./dist/llms.d.ts",
-      "default": "./dist/llms.js"
-    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "default": "./dist/testing/index.js"
@@ -59,14 +54,14 @@
     "test:unit:watch": "vitest --watch --project=unit",
     "test:integration": "[ -f .env ] && { set -a; source .env; set +a; } && vitest run --project=integration",
     "test:integration:watch": "[ -f .env ] && { set -a; source .env; set +a; } && vitest --watch --project=integration",
-    "generate:llmstxt": "tsx scripts/generate-llmstxt.ts && oxfmt --write llms.txt src/llms.ts"
+    "generate:reference": "tsx scripts/generate-reference.ts"
   },
   "dependencies": {
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
-    "commander": "^14.0.2",
+    "@types/node": "^25.0.0",
+    "commander": "^14.0.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },

package/solver/src/solver/app.py

@@ -18,7 +18,7 @@ async def health() -> dict[str, str]:
     return {"status": "ok", "service": "scheduler-solver"}
 
 
-@app.post("/solve", response_model=SolverResponse)
+@app.post("/solve", response_model=SolverResponse, response_model_exclude_unset=True)
 async def solve(request: SolverRequest) -> SolverResponse:
     """Solve a scheduling model described by primitive constraints."""
     return solve_request(request)

package/solver/src/solver/solver.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Iterable, Optional
+from typing import Iterable
 
 from ortools.sat.python import cp_model
 
@@ -74,7 +74,7 @@ def _expression_range(terms: list[Term], bounds: dict[str, _VariableBounds]) ->
     return min_expr, max_expr
 
 
-def _sum_expr(exprs: list[cp_model.LinearExpr]) -> Optional[cp_model.LinearExpr]:
+def _sum_expr(exprs: list[cp_model.LinearExpr]) -> cp_model.LinearExpr | None:
     if not exprs:
         return None
     total = exprs[0]
@@ -319,9 +319,10 @@ def solve_request(request: SolverRequest) -> SolverResponse:
         status_text = status_map.get(int(status), "ERROR")
 
         if status not in (cp_model.OPTIMAL, cp_model.FEASIBLE):
+            solution_info = solver.response_proto.solution_info
             return SolverResponse(
                 status=status_text,
-                solutionInfo=solver.response_proto.solution_info or None,
+                **({"solutionInfo": solution_info} if solution_info else {}),
             )
 
         statistics: dict[str, int | float] = {
@@ -349,11 +350,13 @@ def solve_request(request: SolverRequest) -> SolverResponse:
                 )
             )
 
+        solution_info = solver.response_proto.solution_info
         return SolverResponse(
             status=status_text,
             values={name: int(solver.value(var)) for name, var in vars_map.items()},
             statistics=statistics,
-            softViolations=soft_violations if soft_violations else None,
+            **({"solutionInfo": solution_info} if solution_info else {}),
+            softViolations=soft_violations,
         )
     except Exception as exc:  # pragma: no cover - surfaced in response
         return SolverResponse(status="ERROR", error=str(exc))

package/src/client.ts

@@ -1,9 +1,5 @@
-import {
-  type FetcherLike,
-  type SolverClient,
-  type SolverRequest,
-  type SolverResponse,
-} from "./client.types.js";
+import { type FetcherLike, type SolverClient, type SolverRequest } from "./client.types.js";
+import { SolverResponseSchema } from "./client.schemas.js";
 
 export type {
   SolverClient,
@@ -25,6 +21,8 @@ const normalizeFetch = (
 
 /**
  * Generic HTTP client for the solver service.
+ *
+ * @category Solver
  */
 export class HttpSolverClient implements SolverClient {
   #fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
@@ -35,7 +33,7 @@ export class HttpSolverClient implements SolverClient {
     this.#baseUrl = baseUrl.replace(/\/$/, "");
   }
 
-  async solve(request: SolverRequest, options?: { signal?: AbortSignal }): Promise<SolverResponse> {
+  async solve(request: SolverRequest, options?: { signal?: AbortSignal }) {
     const res = await this.#fetch(`${this.#baseUrl}/solve`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
@@ -53,7 +51,7 @@ export class HttpSolverClient implements SolverClient {
       throw new Error("Solver returned an empty response");
     }
 
-    return JSON.parse(bodyText) as SolverResponse;
+    return SolverResponseSchema.parse(JSON.parse(bodyText));
   }
 
   async health(): Promise<void> {

package/src/client.types.ts

@@ -85,6 +85,8 @@ export type SolverResponse = z.infer<typeof SolverResponseSchema>;
  * Solver outcome status.
  *
  * One of `"OPTIMAL"`, `"FEASIBLE"`, `"INFEASIBLE"`, `"TIMEOUT"`, or `"ERROR"`.
+ *
+ * @category Solver
  */
 export type SolverStatus = z.infer<typeof SolverStatusSchema>;
 
@@ -100,6 +102,7 @@ export type SoftConstraintViolation = z.infer<typeof SoftConstraintViolationSche
 // Status constants (for convenience)
 // --------------------------------------------------------------------------
 
+/** Convenience constants for {@link SolverStatus} values. */
 export const SOLVER_STATUS = {
   OPTIMAL: "OPTIMAL",
   FEASIBLE: "FEASIBLE",
@@ -112,12 +115,18 @@ export const SOLVER_STATUS = {
 // Client interface
 // --------------------------------------------------------------------------
 
+/** A `fetch` function or an object with a `fetch` method. */
 export type FetcherLike =
   | typeof fetch
   | {
       fetch: typeof fetch;
     };
 
+/**
+ * Interface for sending solver requests and receiving responses.
+ *
+ * @category Solver
+ */
 export interface SolverClient {
   solve(request: SolverRequest, options?: { signal?: AbortSignal }): Promise<SolverResponse>;
   health?(): Promise<void>;

package/src/cpsat/model-builder.ts

@@ -94,6 +94,11 @@ export interface CostContribution {
   entries: CostEntry[];
 }
 
+/**
+ * Result of {@link ModelBuilder.compile}.
+ *
+ * @category Model Builder
+ */
 export interface CompilationResult {
   request: SolverRequest;
   validation: ScheduleValidation;
@@ -103,6 +108,8 @@ export interface CompilationResult {
 /**
  * Configuration for ModelBuilder.
  *
+ * @category Model Builder
+ *
  * @example Date range with day-of-week filtering (restaurant closed Mon/Tue)
  * ```typescript
  * const config: ModelBuilderConfig = {
@@ -148,6 +155,8 @@ export interface ModelBuilderConfig extends ModelBuilderOptions {
 /**
  * Compilation context that creates variables, constraints, and objectives
  * and emits a `SolverRequest` for the Python CP-SAT solver service.
+ *
+ * @category Model Builder
  */
 export class ModelBuilder {
   readonly members: SchedulingMember[];
@@ -187,8 +196,8 @@ export class ModelBuilder {
 
     // Validate coverage requirements have at least roles or skills
     for (const cov of config.coverage) {
-      const hasRoles = cov.roles !== undefined && cov.roles.length > 0;
-      const hasSkills = cov.skills !== undefined && cov.skills.length > 0;
+      const hasRoles = cov.roleIds !== undefined && cov.roleIds.length > 0;
+      const hasSkills = cov.skillIds !== undefined && cov.skillIds.length > 0;
       if (!hasRoles && !hasSkills) {
         throw new Error(
           `Coverage requirement for day "${cov.day}" must have at least one of roles or skills`,
@@ -332,7 +341,7 @@ export class ModelBuilder {
   }
 
   membersWithRole(roleId: string): SchedulingMember[] {
-    return this.members.filter((m) => m.roles.includes(roleId));
+    return this.members.filter((m) => m.roleIds.includes(roleId));
   }
 
   /**
@@ -345,15 +354,15 @@ export class ModelBuilder {
    */
   membersForCoverage(cov: CoverageRequirement): SchedulingMember[] {
     return this.members.filter((m) => {
-      if (cov.roles && cov.roles.length > 0) {
-        const hasMatchingRole = cov.roles.some((role) => m.roles.includes(role));
+      if (cov.roleIds && cov.roleIds.length > 0) {
+        const hasMatchingRole = cov.roleIds.some((role) => m.roleIds.includes(role));
         if (!hasMatchingRole) {
           return false;
         }
       }
-      if (cov.skills && cov.skills.length > 0) {
-        const memberSkills = m.skills ?? [];
-        if (!cov.skills.every((skill) => memberSkills.includes(skill))) {
+      if (cov.skillIds && cov.skillIds.length > 0) {
+        const memberSkills = m.skillIds ?? [];
+        if (!cov.skillIds.every((skill) => memberSkills.includes(skill))) {
           return false;
         }
       }
@@ -362,10 +371,10 @@ export class ModelBuilder {
   }
 
   canAssign(member: SchedulingMember, pattern: ShiftPattern): boolean {
-    if (!pattern.roles || pattern.roles.length === 0) {
+    if (!pattern.roleIds || pattern.roleIds.length === 0) {
       return true;
     }
-    return pattern.roles.some((role) => member.roles.includes(role));
+    return pattern.roleIds.some((role) => member.roleIds.includes(role));
   }
 
   /**
@@ -498,13 +507,13 @@ export class ModelBuilder {
     for (const cov of this.coverage) {
       const covStart = timeOfDayToMinutes(cov.startTime);
       const covEnd = normalizeEndMinutes(covStart, timeOfDayToMinutes(cov.endTime));
-      const covKey = cov.roles?.join(",") ?? cov.skills?.join(",") ?? "unknown";
+      const covKey = cov.roleIds?.join(",") ?? cov.skillIds?.join(",") ?? "unknown";
       const coverageLabel =
-        cov.roles && cov.roles.length > 0
-          ? cov.roles.length === 1
-            ? `role "${cov.roles[0]}"`
-            : `role "${cov.roles.join(" or ")}"`
-          : `skills [${cov.skills?.join(", ")}]`;
+        cov.roleIds && cov.roleIds.length > 0
+          ? cov.roleIds.length === 1
+            ? `role "${cov.roleIds[0]}"`
+            : `role "${cov.roleIds.join(" or ")}"`
+          : `skills [${cov.skillIds?.join(", ")}]`;
       const coverageWindow = formatTimeRange(covStart, covEnd);
 
       const eligibleMembers = this.membersForCoverage(cov);
@@ -513,16 +522,16 @@ export class ModelBuilder {
           this.reporter.reportCoverageError({
             day: cov.day,
             timeSlots: [coverageWindow],
-            roles: cov.roles,
-            skills: cov.skills,
-            reason: `Coverage for ${coverageLabel} on ${cov.day} (${coverageWindow}) cannot be met: no eligible team members available.`,
+            roleIds: cov.roleIds,
+            skillIds: cov.skillIds,
+            message: `Coverage for ${coverageLabel} on ${cov.day} (${coverageWindow}) cannot be met: no eligible team members available.`,
             suggestions: [
-              cov.roles && cov.roles.length > 0
-                ? `Add team members with role "${cov.roles.join(" or ")}"`
+              cov.roleIds && cov.roleIds.length > 0
+                ? `Add team members with role "${cov.roleIds.join(" or ")}"`
                 : "Add team members with the required skills",
               "Change the coverage requirement to match available team members",
             ],
-            groupKey: cov.groupKey,
+            group: cov.group,
           });
 
           const impossibleVar = `infeasible:coverage:${covKey}:${cov.day}`;
@@ -550,7 +559,7 @@ export class ModelBuilder {
             {
               key: "no_patterns",
               severity: cov.priority === "MANDATORY" ? "impossible" : "warning",
-              reason: "no shift patterns overlap this time",
+              message: "no shift patterns overlap this time",
               suggestions: [
                 "Add shift patterns that overlap this coverage window",
                 "Adjust the coverage window to match available shifts",
@@ -582,7 +591,7 @@ export class ModelBuilder {
             {
               key: "no_assignable",
               severity: cov.priority === "MANDATORY" ? "impossible" : "warning",
-              reason: "no eligible team members can work overlapping shift patterns",
+              message: "no eligible team members can work overlapping shift patterns",
               suggestions: [
                 "Adjust shift pattern role requirements",
                 "Add shift patterns that eligible team members can work",
@@ -616,7 +625,7 @@ export class ModelBuilder {
             {
               key: "mandatory_time_off",
               severity: cov.priority === "MANDATORY" ? "impossible" : "warning",
-              reason: "all eligible team members are on mandatory time off",
+              message: "all eligible team members are on mandatory time off",
               suggestions: [
                 "Adjust mandatory time-off requests",
                 "Add more team members with the required role or skills",
@@ -630,7 +639,7 @@ export class ModelBuilder {
             {
               key: `insufficient:${availableMembers.size}`,
               severity: cov.priority === "MANDATORY" ? "impossible" : "warning",
-              reason: `only ${availableMembers.size} team members available, need ${cov.targetCount}`,
+              message: `only ${availableMembers.size} team members available, need ${cov.targetCount}`,
               suggestions: [
                 "Add more team members with the required role or skills",
                 `Reduce coverage target to ${availableMembers.size}`,
@@ -679,13 +688,13 @@ export class ModelBuilder {
           comparator: ">=",
           day: cov.day,
           timeSlot: formatMinutes(bucketStart),
-          roles: cov.roles,
-          skills: cov.skills,
+          roleIds: cov.roleIds,
+          skillIds: cov.skillIds,
           context: {
             days: [cov.day],
             memberIds: eligibleMembers.map((e) => e.id),
           },
-          groupKey: cov.groupKey,
+          group: cov.group,
         });
       }
 
@@ -695,17 +704,17 @@ export class ModelBuilder {
         );
         if (ranges.length === 0) continue;
 
-        const reason = `Coverage for ${coverageLabel} on ${cov.day} (${ranges.join(", ")}) cannot be met: ${issue.reason}.`;
+        const message = `Coverage for ${coverageLabel} on ${cov.day} (${ranges.join(", ")}) cannot be met: ${issue.message}.`;
 
         if (issue.severity === "impossible") {
           this.reporter.reportCoverageError({
             day: cov.day,
             timeSlots: ranges,
-            roles: cov.roles,
-            skills: cov.skills,
-            reason,
+            roleIds: cov.roleIds,
+            skillIds: cov.skillIds,
+            message,
             suggestions: issue.suggestions,
-            groupKey: cov.groupKey,
+            group: cov.group,
           });
         }
         // Note: soft coverage warnings are tracked via trackConstraint and reported post-solve
@@ -824,7 +833,7 @@ export class ModelBuilder {
 type BucketIssueGroup = {
   key: string;
   severity: "impossible" | "warning";
-  reason: string;
+  message: string;
   suggestions: string[];
   bucketStarts: number[];
   values?: Record<string, number>;

package/src/cpsat/response.ts

@@ -2,7 +2,11 @@ import type { SolverResponse } from "../client.types.js";
 import type { ShiftPattern } from "./types.js";
 import type { TimeOfDay } from "../types.js";
 
-/** A raw assignment from the solver: which member works which shift on which day. */
+/**
+ * A raw assignment from the solver: which member works which shift on which day.
+ *
+ * @category Solver
+ */
 export interface ShiftAssignment {
   /** The assigned member's ID. */
   memberId: string;
@@ -14,6 +18,8 @@ export interface ShiftAssignment {
 
 /**
  * A shift assignment with resolved times.
+ *
+ * @category Solver
  */
 export interface ResolvedShiftAssignment {
   /** The assigned member's ID. */
@@ -28,6 +34,8 @@ export interface ResolvedShiftAssignment {
 
 /**
  * Parsed solver result with assignments and metadata.
+ *
+ * @category Solver
  */
 export interface SolverResult {
   /** The solver outcome: OPTIMAL, FEASIBLE, INFEASIBLE, TIMEOUT, or ERROR. */
@@ -53,6 +61,8 @@ export interface SolverResult {
  * @param response - The solver response containing variable values
  * @returns Parsed schedule result with assignments
  *
+ * @category Solver
+ *
  * @example
  * ```typescript
  * const response = await client.solve(request);
@@ -107,6 +117,8 @@ export function parseSolverResponse(response: SolverResponse): SolverResult {
  * @param shiftPatterns - The shift patterns used in the model
  * @returns Assignments with resolved start/end times
  *
+ * @category Solver
+ *
  * @example
  * ```typescript
  * const result = parseSolverResponse(response);

package/src/cpsat/rules/cost-utils.ts

@@ -0,0 +1,25 @@
+import type { SchedulingMember, ShiftPattern } from "../types.js";
+import { timeOfDayToMinutes, normalizeEndMinutes } from "../utils.js";
+
+/** Returns the hourly rate for a member, or undefined if not hourly. */
+export function getHourlyRate(member: SchedulingMember): number | undefined {
+  if (!member.pay) return undefined;
+  if ("hourlyRate" in member.pay) return member.pay.hourlyRate;
+  return undefined;
+}
+
+/** Returns salaried pay info, or undefined if not salaried. */
+export function getSalariedPay(
+  member: SchedulingMember,
+): { annual: number; hoursPerWeek: number } | undefined {
+  if (!member.pay) return undefined;
+  if ("annual" in member.pay) return member.pay;
+  return undefined;
+}
+
+/** Computes shift duration in minutes from a pattern. */
+export function patternDurationMinutes(pattern: ShiftPattern): number {
+  const start = timeOfDayToMinutes(pattern.startTime);
+  const end = normalizeEndMinutes(start, timeOfDayToMinutes(pattern.endTime));
+  return end - start;
+}

package/src/cpsat/rules/day-cost-multiplier.ts

@@ -2,7 +2,7 @@ import * as z from "zod";
 import type { CompilationRule, CostContribution } from "../model-builder.js";
 import type { ShiftPattern, SchedulingMember } from "../types.js";
 import type { ShiftAssignment } from "../response.js";
-import { timeOfDayToMinutes, normalizeEndMinutes } from "../utils.js";
+import { COST_CATEGORY } from "../cost.js";
 import {
   entityScope,
   timeScope,
@@ -11,6 +11,7 @@ import {
   resolveMembersFromScope,
   resolveActiveDaysFromScope,
 } from "./scope.types.js";
+import { getHourlyRate, patternDurationMinutes } from "./cost-utils.js";
 
 const DayCostMultiplierSchema = z
   .object({
@@ -22,18 +23,6 @@ const DayCostMultiplierSchema = z
 /** Configuration for {@link createDayCostMultiplierRule}. */
 export type DayCostMultiplierConfig = z.infer<typeof DayCostMultiplierSchema>;
 
-function getHourlyRate(emp: SchedulingMember): number | undefined {
-  if (!emp.pay) return undefined;
-  if ("hourlyRate" in emp.pay) return emp.pay.hourlyRate;
-  return undefined;
-}
-
-function patternDurationMinutes(pattern: ShiftPattern): number {
-  const start = timeOfDayToMinutes(pattern.startTime);
-  const end = normalizeEndMinutes(start, timeOfDayToMinutes(pattern.endTime));
-  return end - start;
-}
-
 /**
  * Creates a day-based rate multiplier rule.
  *
@@ -113,7 +102,7 @@ export function createDayCostMultiplierRule(config: DayCostMultiplierConfig): Co
         entries.push({
           memberId: a.memberId,
           day: a.day,
-          category: "premium",
+          category: COST_CATEGORY.PREMIUM,
           amount,
         });
       }