dabke 0.81.1 → 0.83.0

package/CHANGELOG.md

@@ -5,6 +5,64 @@ All notable changes to this project will be documented in this file.
 This changelog was generated from the git history of the project when it was
 named `scheduling-core`, prior to the rename to `dabke` in v0.78.0.
 
+## 0.83.0 (2026-03-21)
+
+### Breaking Changes
+
+- Remove `./llms` export path and `llms.txt` from the package. The LLM reference
+  is now generated externally via `generate:reference`.
+
+### Features
+
+- Add `maxDaysPerWeek(days, opts?)` and `minDaysPerWeek(days, opts?)` rule functions
+  to constrain the number of distinct working days per member per scheduling week.
+- Add `mustAssign(opts?)` rule for staffing obligations. Guarantees targeted members
+  appear on the schedule each week; defaults to HIGH priority so the schedule still
+  generates when a member cannot be placed.
+
+### Improvements
+
+- Split `schedule.ts` into focused modules under `src/schedule/` (public API unchanged).
+- Add `NoInfer` on coverage entry types so role/skill references are checked against
+  declared roles and skills at compile time.
+- Update devDependencies (@types/node ^25.0.0, commander ^14.0.3).
+- Publish workflow now includes changelog text in GitHub releases.
+
+## 0.82.0 (2026-02-23)
+
+### Breaking Changes
+
+- **Replace `defineSchedule` with `schedule`/`with`/`compile`/`solve` API**: the
+  `defineSchedule()` function, `ScheduleDefinition`, and `RuntimeArgs` are removed.
+  Use `schedule()` to create an immutable `Schedule`, compose data with `.with()`,
+  and execute via `.compile()` or `.solve()`.
+- **Rename `roles`/`skills` back to `roleIds`/`skillIds`**: all public type fields and
+  function options (`SchedulingMember`, `ShiftPattern`, coverage types, `ScheduleConfig`)
+  revert to `roleIds`/`skillIds` for unambiguous signaling to LLM consumers.
+- **Redesign validation message architecture**: `ValidationGroup` now uses deterministic
+  structural keys (e.g. `rule:max-hours-week:40:roles:nurse`) instead of counter-based
+  IDs. Validation items use a unified `message` field replacing `reason`/`description`.
+  `ValidationSummary.title` replaces `description`.
+- **Trim public API surface** (102 to 86 exports): remove internal types
+  (`ValidationReporter`, `ValidationContext`, `CostContext`, `ModelBuilderOptions`,
+  `CoverageRequirement`, `CpsatRuleRegistry`, `DateTime`), legacy validation, and
+  unused datetime utilities.
+- **`SolveResult` status** uses lowercase strings: `optimal`, `feasible`, `infeasible`,
+  `no_solution`.
+
+### Improvements
+
+- `solve()` runs post-solve validation automatically; `SolveResult.validation` includes
+  soft constraint violations.
+- `ScheduleConfig` requires `times`, `coverage`, `shiftPatterns`; `partialSchedule()`
+  allows partial configs for composition via `.with()`.
+- Eager validation in `.with()` for role/skill disjointness and member references.
+- All `dayOfWeek` fields typed as `readonly [DayOfWeek, ...DayOfWeek[]]` consistently.
+- Add constraint IDs, group keys, and `trackConstraint()` to all soft rules for
+  post-solve verification.
+- Add `@category` TSDoc tags to all public exports for structured documentation.
+- Restructure docs reference nav with automated category-driven generation.
+
 ## 0.81.1 (2026-02-20)
 
 ### Documentation

package/README.md

@@ -10,7 +10,7 @@ Define teams, shifts, coverage, and rules declaratively. dabke compiles them int
 
 ```typescript
 import {
-  defineSchedule,
+  schedule,
   t,
   time,
   cover,
@@ -23,8 +23,8 @@ import {
   weekend,
 } from "dabke";
 
-const schedule = defineSchedule({
-  roles: ["barista", "server"],
+const venue = schedule({
+  roleIds: ["barista", "server"],
 
   // Times: WHEN you need people (named periods for coverage + rules)
   times: {
@@ -75,31 +75,39 @@ docker pull christianklotz/dabke-solver
 docker run -p 8080:8080 christianklotz/dabke-solver
 ```
 
-Once you have a schedule definition, create a config with runtime data and solve:
+Once you have a schedule definition, add members and solve:
 
 ```typescript
-import { ModelBuilder, HttpSolverClient, parseSolverResponse, resolveAssignments } from "dabke";
-
-const config = schedule.createSchedulerConfig({
-  schedulingPeriod: {
+import { HttpSolverClient } from "dabke";
+
+const result = await venue
+  .with([
+    { id: "alice", roleIds: ["barista", "server"], pay: { hourlyRate: 1500 } },
+    { id: "bob", roleIds: ["barista"], pay: { hourlyRate: 1200 } },
+    { id: "carol", roleIds: ["barista", "server"], pay: { hourlyRate: 1400 } },
+    { id: "dave", roleIds: ["barista", "server"], pay: { hourlyRate: 1200 } },
+    { id: "eve", roleIds: ["barista", "server"], pay: { hourlyRate: 1300 } },
+  ])
+  .solve(new HttpSolverClient(fetch, "http://localhost:8080"), {
     dateRange: { start: "2026-02-09", end: "2026-02-15" },
-  },
-  members: [
-    { id: "alice", roles: ["barista", "server"], pay: { hourlyRate: 1500 } },
-    { id: "bob", roles: ["barista"], pay: { hourlyRate: 1200 } },
-    { id: "carol", roles: ["barista", "server"], pay: { hourlyRate: 1400 } },
-    { id: "dave", roles: ["barista", "server"], pay: { hourlyRate: 1200 } },
-    { id: "eve", roles: ["barista", "server"], pay: { hourlyRate: 1300 } },
-  ],
-});
+  });
 
-const builder = new ModelBuilder(config);
-const { request, canSolve } = builder.compile();
+console.log(result.status); // "optimal" | "feasible" | "infeasible" | "no_solution"
+console.log(result.assignments); // Shift assignments per member per day
+```
+
+Or compile and solve manually for more control:
 
-const solver = new HttpSolverClient(fetch, "http://localhost:8080");
-const response = await solver.solve(request);
-const result = parseSolverResponse(response);
-const shifts = resolveAssignments(result.assignments, config.shiftPatterns);
+```typescript
+const compiled = venue
+  .with([...members])
+  .compile({ dateRange: { start: "2026-02-09", end: "2026-02-15" } });
+
+if (compiled.canSolve) {
+  const solver = new HttpSolverClient(fetch, "http://localhost:8080");
+  const response = await solver.solve(compiled.request);
+  // ...
+}
 ```
 
 ---
@@ -122,7 +130,14 @@ maxHoursPerWeek(30, { appliesTo: "bob", priority: "MEDIUM" }),
 
 **Cost optimization.** Members declare `pay` as hourly or salaried. Cost rules (`minimizeCost`, `dayMultiplier`, `overtimeMultiplier`, `tieredOvertimeMultiplier`, etc.) tell the solver to minimize total labor cost, factoring in overtime, day premiums, and time-based surcharges.
 
-**Validation.** `ModelBuilder` reports coverage gaps and rule violations both pre-solve (via `compile()`) and post-solve (via `builder.reporter.analyzeSolution()`). Use `summarizeValidation()` for grouped reporting.
+**Composition with `.with()`.** Schedule definitions are immutable. Use `.with()` to merge other schedules or add members at runtime. Each `.with()` returns a new `Schedule` instance:
+
+```typescript
+const ready = venue.with([
+  { id: "alice", roleIds: ["barista"], pay: { hourlyRate: 1500 } },
+  { id: "bob", roleIds: ["barista"], pay: { hourlyRate: 1200 } },
+]);
+```
 
 ---
 
@@ -163,12 +178,15 @@ maxHoursPerWeek(30, { appliesTo: "bob", priority: "MEDIUM" }),
 
 ## LLM Integration
 
-dabke ships an `llms.txt` with complete API documentation for AI code generation:
+Generate per-section API reference docs from TSDoc:
 
-```typescript
-import { apiDocs } from "dabke/llms";
+```bash
+npm run generate:reference -- --outdir ./references
 ```
 
+This produces a `README.md` index, an `api.md` API surface listing,
+and one detail file per category (schedule, rules, coverage, etc.).
+
 ---
 
 ## Development

package/dist/client.d.ts

@@ -1,14 +1,32 @@
-import { type FetcherLike, type SolverClient, type SolverRequest, type SolverResponse } from "./client.types.js";
+import { type FetcherLike, type SolverClient, type SolverRequest } from "./client.types.js";
 export type { SolverClient, SolverRequest, SolverResponse, SolverVariable, SolverConstraint, SolverTerm, SolverObjective, FetcherLike, } from "./client.types.js";
 /**
  * Generic HTTP client for the solver service.
+ *
+ * @category Solver
  */
 export declare class HttpSolverClient implements SolverClient {
     #private;
     constructor(fetcher: FetcherLike, baseUrl?: string);
     solve(request: SolverRequest, options?: {
         signal?: AbortSignal;
-    }): Promise<SolverResponse>;
+    }): Promise<{
+        status: "OPTIMAL" | "FEASIBLE" | "INFEASIBLE" | "TIMEOUT" | "ERROR";
+        values?: Record<string, number> | undefined;
+        statistics?: {
+            solveTimeMs?: number | undefined;
+            conflicts?: number | undefined;
+            branches?: number | undefined;
+        } | undefined;
+        error?: string | undefined;
+        solutionInfo?: string | undefined;
+        softViolations?: {
+            constraintId: string;
+            violationAmount: number;
+            targetValue: number;
+            actualValue: number;
+        }[] | undefined;
+    }>;
     health(): Promise<void>;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,YAAY,EACZ,aAAa,EACb,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,eAAe,EACf,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAS3B;;GAEG;AACH,qBAAa,gBAAiB,YAAW,YAAY;;gBAIvC,OAAO,EAAE,WAAW,EAAE,OAAO,GAAE,MAAgC;IAKrE,KAAK,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAqB1F,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ9B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAG5F,YAAY,EACV,YAAY,EACZ,aAAa,EACb,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,eAAe,EACf,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAS3B;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,YAAY;;gBAIvC,OAAO,EAAE,WAAW,EAAE,OAAO,GAAE,MAAgC;IAKrE,KAAK,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE;;;;;;;;;;;;;;;;;IAqBhE,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ9B"}

package/dist/client.js

@@ -1,3 +1,4 @@
+import { SolverResponseSchema } from "./client.schemas.js";
 const normalizeFetch = (fetcher) => {
     if (typeof fetcher === "function")
         return fetcher;
@@ -5,6 +6,8 @@ const normalizeFetch = (fetcher) => {
 };
 /**
  * Generic HTTP client for the solver service.
+ *
+ * @category Solver
  */
 export class HttpSolverClient {
     #fetch;
@@ -28,7 +31,7 @@ export class HttpSolverClient {
         if (!bodyText) {
             throw new Error("Solver returned an empty response");
         }
-        return JSON.parse(bodyText);
+        return SolverResponseSchema.parse(JSON.parse(bodyText));
     }
     async health() {
         const res = await this.#fetch(`${this.#baseUrl}/health`);

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAkBA,MAAM,cAAc,GAAG,CACrB,OAAoB,EAC8C,EAAE;IACpE,IAAI,OAAO,OAAO,KAAK,UAAU;QAAE,OAAO,OAAO,CAAC;IAClD,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACrC,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,OAAO,gBAAgB;IAC3B,MAAM,CAAiE;IACvE,QAAQ,CAAS;IAEjB,YAAY,OAAoB,EAAE,UAAkB,uBAAuB;QACzE,IAAI,CAAC,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QACtC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,OAAsB,EAAE,OAAkC;QACpE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,QAAQ,EAAE;YACtD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;YAC7B,MAAM,EAAE,OAAO,EAAE,MAAM;SACxB,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAClC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/C,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;QAC5D,CAAC;QAED,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvD,CAAC;QAED,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAmB,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,MAAM;QACV,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,SAAS,CAAC,CAAC;QACzD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAChD,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CAAC,mCAAmC,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAa3D,MAAM,cAAc,GAAG,CACrB,OAAoB,EAC8C,EAAE;IACpE,IAAI,OAAO,OAAO,KAAK,UAAU;QAAE,OAAO,OAAO,CAAC;IAClD,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACrC,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,OAAO,gBAAgB;IAC3B,MAAM,CAAiE;IACvE,QAAQ,CAAS;IAEjB,YAAY,OAAoB,EAAE,UAAkB,uBAAuB;QACzE,IAAI,CAAC,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QACtC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,OAAsB,EAAE,OAAkC;QACpE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,QAAQ,EAAE;YACtD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;YAC7B,MAAM,EAAE,OAAO,EAAE,MAAM;SACxB,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAClC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/C,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;QAC5D,CAAC;QAED,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvD,CAAC;QAED,OAAO,oBAAoB,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,MAAM;QACV,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,SAAS,CAAC,CAAC;QACzD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAChD,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CAAC,mCAAmC,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;CACF"}

package/dist/client.types.d.ts

@@ -64,6 +64,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>;
 /**
@@ -73,6 +75,7 @@ export type SolverStatus = z.infer<typeof SolverStatusSchema>;
  * - `violationAmount` (required): magnitude of the violation
  */
 export type SoftConstraintViolation = z.infer<typeof SoftConstraintViolationSchema>;
+/** Convenience constants for {@link SolverStatus} values. */
 export declare const SOLVER_STATUS: {
     readonly OPTIMAL: "OPTIMAL";
     readonly FEASIBLE: "FEASIBLE";
@@ -80,9 +83,15 @@ export declare const SOLVER_STATUS: {
     readonly TIMEOUT: "TIMEOUT";
     readonly ERROR: "ERROR";
 };
+/** 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;

package/dist/client.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.types.d.ts","sourceRoot":"","sources":["../src/client.types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EACV,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,6BAA6B,EAC9B,MAAM,qBAAqB,CAAC;AAM7B;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAMpF,eAAO,MAAM,aAAa;;;;;;CAMhB,CAAC;AAMX,MAAM,MAAM,WAAW,GACnB,OAAO,KAAK,GACZ;IACE,KAAK,EAAE,OAAO,KAAK,CAAC;CACrB,CAAC;AAEN,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3F,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B"}
+{"version":3,"file":"client.types.d.ts","sourceRoot":"","sources":["../src/client.types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EACV,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,6BAA6B,EAC9B,MAAM,qBAAqB,CAAC;AAM7B;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAMpF,6DAA6D;AAC7D,eAAO,MAAM,aAAa;;;;;;CAMhB,CAAC;AAMX,6DAA6D;AAC7D,MAAM,MAAM,WAAW,GACnB,OAAO,KAAK,GACZ;IACE,KAAK,EAAE,OAAO,KAAK,CAAC;CACrB,CAAC;AAEN;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3F,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B"}

package/dist/client.types.js

@@ -8,6 +8,7 @@
 // --------------------------------------------------------------------------
 // Status constants (for convenience)
 // --------------------------------------------------------------------------
+/** Convenience constants for {@link SolverStatus} values. */
 export const SOLVER_STATUS = {
     OPTIMAL: "OPTIMAL",
     FEASIBLE: "FEASIBLE",

package/dist/client.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.types.js","sourceRoot":"","sources":["../src/client.types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA4FH,6EAA6E;AAC7E,qCAAqC;AACrC,6EAA6E;AAE7E,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,UAAU;IACpB,UAAU,EAAE,YAAY;IACxB,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;CACN,CAAC"}
+{"version":3,"file":"client.types.js","sourceRoot":"","sources":["../src/client.types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA8FH,6EAA6E;AAC7E,qCAAqC;AACrC,6EAA6E;AAE7E,6DAA6D;AAC7D,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,UAAU;IACpB,UAAU,EAAE,YAAY;IACxB,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;CACN,CAAC"}

package/dist/cpsat/model-builder.d.ts

@@ -62,6 +62,11 @@ export interface CostEntry {
 export interface CostContribution {
     entries: CostEntry[];
 }
+/**
+ * Result of {@link ModelBuilder.compile}.
+ *
+ * @category Model Builder
+ */
 export interface CompilationResult {
     request: SolverRequest;
     validation: ScheduleValidation;
@@ -70,6 +75,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 = {
@@ -114,6 +121,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 declare class ModelBuilder {
     #private;

package/dist/cpsat/model-builder.d.ts.map

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

package/dist/cpsat/model-builder.js

@@ -6,6 +6,8 @@ import { ValidationReporterImpl } from "./validation-reporter.js";
 /**
  * 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 {
     members;
@@ -41,8 +43,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`);
             }
@@ -158,7 +160,7 @@ export class ModelBuilder {
         this.#objective.push({ var: varName, coeff: rounded });
     }
     membersWithRole(roleId) {
-        return this.members.filter((m) => m.roles.includes(roleId));
+        return this.members.filter((m) => m.roleIds.includes(roleId));
     }
     /**
      * Returns team members who can satisfy a coverage requirement.
@@ -170,15 +172,15 @@ export class ModelBuilder {
      */
     membersForCoverage(cov) {
         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;
                 }
             }
@@ -186,10 +188,10 @@ export class ModelBuilder {
         });
     }
     canAssign(member, pattern) {
-        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));
     }
     /**
      * Checks if a shift pattern can be used on a specific day.
@@ -304,12 +306,12 @@ 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 coverageLabel = cov.roles && cov.roles.length > 0
-                ? cov.roles.length === 1
-                    ? `role "${cov.roles[0]}"`
-                    : `role "${cov.roles.join(" or ")}"`
-                : `skills [${cov.skills?.join(", ")}]`;
+            const covKey = cov.roleIds?.join(",") ?? cov.skillIds?.join(",") ?? "unknown";
+            const coverageLabel = 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);
             if (eligibleMembers.length === 0) {
@@ -317,16 +319,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}`;
                     this.intVar(impossibleVar, 0, 0);
@@ -348,7 +350,7 @@ export class ModelBuilder {
                     recordBucketIssue(bucketIssues, {
                         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",
@@ -374,7 +376,7 @@ export class ModelBuilder {
                     recordBucketIssue(bucketIssues, {
                         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",
@@ -399,7 +401,7 @@ export class ModelBuilder {
                     recordBucketIssue(bucketIssues, {
                         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",
@@ -410,7 +412,7 @@ export class ModelBuilder {
                     recordBucketIssue(bucketIssues, {
                         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}`,
@@ -447,29 +449,29 @@ 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,
                 });
             }
             for (const issue of bucketIssues.values()) {
                 const ranges = bucketStartsToRanges(issue.bucketStarts, bucket, covEnd).map((range) => `${formatMinutes(range.start)}-${formatMinutes(range.end)}`);
                 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