dabke 0.81.0 → 0.82.0

package/CHANGELOG.md

@@ -5,6 +5,47 @@ 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.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
+
+- Rewrite README for the v2 `defineSchedule` API with a verified cafe scheduling example.
+
 ## 0.81.0 (2026-02-19)
 
 ### Breaking Changes

package/README.md

@@ -4,378 +4,202 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![CI](https://github.com/christianklotz/dabke/actions/workflows/ci.yml/badge.svg)](https://github.com/christianklotz/dabke/actions/workflows/ci.yml)
 
-Scheduling library powered by constraint programming (CP-SAT).
+TypeScript scheduling library powered by constraint programming.
 
-Define your team, shifts, coverage, and rules — dabke turns them into an optimized schedule.
+Define teams, shifts, coverage, and rules declaratively. dabke compiles them into a CP-SAT model and solves for an optimized schedule.
 
 ```typescript
-import { ModelBuilder, HttpSolverClient } from "dabke";
+import {
+  schedule,
+  t,
+  time,
+  cover,
+  shift,
+  maxHoursPerWeek,
+  minRestBetweenShifts,
+  timeOff,
+  minimizeCost,
+  weekdays,
+  weekend,
+} from "dabke";
+
+const venue = schedule({
+  roleIds: ["barista", "server"],
+
+  // Times: WHEN you need people (named periods for coverage + rules)
+  times: {
+    breakfast: time({ startTime: t(7), endTime: t(10) }),
+    lunch_rush: time(
+      { startTime: t(11, 30), endTime: t(14) },
+      { startTime: t(11), endTime: t(15), dayOfWeek: weekend },
+    ),
+    closing: time({ startTime: t(20), endTime: t(22) }),
+  },
 
-const builder = new ModelBuilder({
-  employees: [
-    { id: "alice", roleIds: ["server"] },
-    { id: "bob", roleIds: ["server"] },
+  // Coverage: HOW MANY people you need during each time
+  coverage: [
+    cover("breakfast", "barista", 1),
+    cover("lunch_rush", "barista", 2, { dayOfWeek: weekdays }),
+    cover("lunch_rush", "barista", 3, { dayOfWeek: weekend }),
+    cover("lunch_rush", "server", 1),
+    cover("closing", "server", 1),
   ],
+
+  // Shifts: WHEN people CAN work (the actual time slots)
+  // An opener covers breakfast + lunch; a closer covers lunch + closing
   shiftPatterns: [
-    { id: "morning", startTime: { hours: 8 }, endTime: { hours: 16 } },
-    { id: "evening", startTime: { hours: 16 }, endTime: { hours: 23 } },
-  ],
-  coverage: [
-    {
-      day: "2026-02-09",
-      startTime: { hours: 8 },
-      endTime: { hours: 16 },
-      roleIds: ["server"],
-      targetCount: 1,
-      priority: "MANDATORY",
-    },
-    {
-      day: "2026-02-09",
-      startTime: { hours: 16 },
-      endTime: { hours: 23 },
-      roleIds: ["server"],
-      targetCount: 1,
-      priority: "MANDATORY",
-    },
+    shift("opener", t(6), t(14)),
+    shift("mid", t(10), t(18)),
+    shift("closer", t(14), t(22)),
   ],
-  schedulingPeriod: {
-    dateRange: { start: "2026-02-09", end: "2026-02-09" },
-  },
-  ruleConfigs: [
-    { name: "max-hours-day", config: { hours: 8, priority: "MANDATORY" } },
-    { name: "min-rest-between-shifts", config: { hours: 10, priority: "MANDATORY" } },
+
+  rules: [
+    maxHoursPerWeek(40),
+    minRestBetweenShifts(11),
+    timeOff({ appliesTo: "alice", dayOfWeek: weekend }),
+    minimizeCost(),
   ],
 });
-
-const { request } = builder.compile();
-const solver = new HttpSolverClient(fetch, "http://localhost:8080");
-const response = await solver.solve(request);
 ```
 
-## Why dabke?
-
-Staff scheduling with constraint programming is dominated by Python ([OR-Tools](https://developers.google.com/optimization)) and Java ([Timefold](https://timefold.ai/)). If you're building in TypeScript, your options have been: call a Python service and figure out the model yourself, or write scheduling heuristics by hand.
-
-dabke gives you a **TypeScript-native API** for expressing scheduling problems declaratively — employees, shifts, coverage requirements, and rules — and compiles them into a CP-SAT model solved by OR-Tools. You describe _what_ you need, not _how_ to solve it.
-
-**Key differences from rolling your own:**
-
-- **Declarative rules** — express constraints like "max 8 hours/day" or "11 hours rest between shifts" as config, not code
-- **Semantic time** — define named periods ("lunch_rush", "closing") that vary by day of week
-- **Soft and hard constraints** — some rules are mandatory, others are preferences the solver optimizes for
-- **Scoped rules** — apply constraints globally, per person, per role, per skill, or during specific time periods
-- **Validation** — detailed reporting on coverage gaps and rule violations before and after solving
-
-## Install
+## Quick Start
 
 ```bash
 npm install dabke
 ```
 
-## Quick Start
-
-### 1. Start the solver
-
-dabke compiles scheduling problems into a constraint model. You need a CP-SAT solver to solve it. A ready-to-use solver is included:
+dabke compiles scheduling problems into a constraint model. You need a CP-SAT solver to find the solution:
 
 ```bash
-# Pull the solver image
 docker pull christianklotz/dabke-solver
-
-# Start it
 docker run -p 8080:8080 christianklotz/dabke-solver
 ```
 
-Or build from source:
-
-```bash
-cd node_modules/dabke/solver
-docker build -t dabke-solver .
-docker run -p 8080:8080 dabke-solver
-```
-
-### 2. Build and solve a schedule
+Once you have a schedule definition, add members and solve:
 
 ```typescript
-import { ModelBuilder, HttpSolverClient, parseSolverResponse, resolveAssignments } from "dabke";
-
-// Define team
-const employees = [
-  { id: "alice", roleIds: ["server"] },
-  { id: "bob", roleIds: ["server"] },
-];
-
-// Define shift patterns
-const shiftPatterns = [
-  { id: "morning", startTime: { hours: 8 }, endTime: { hours: 16 } },
-  { id: "evening", startTime: { hours: 16 }, endTime: { hours: 23 } },
-];
-
-// Define coverage requirements
-const coverage = [
-  {
-    day: "2026-02-09",
-    startTime: { hours: 8 },
-    endTime: { hours: 16 },
-    roleIds: ["server"] as [string],
-    targetCount: 1,
-    priority: "MANDATORY" as const,
-  },
-  {
-    day: "2026-02-09",
-    startTime: { hours: 16 },
-    endTime: { hours: 23 },
-    roleIds: ["server"] as [string],
-    targetCount: 1,
-    priority: "MANDATORY" as const,
-  },
-];
-
-// Build the model
-const builder = new ModelBuilder({
-  employees,
-  shiftPatterns,
-  coverage,
-  schedulingPeriod: {
-    dateRange: { start: "2026-02-09", end: "2026-02-09" },
-  },
-  ruleConfigs: [
-    { name: "max-hours-day", config: { hours: 8, priority: "MANDATORY" } },
-    { name: "min-rest-between-shifts", config: { hours: 10, priority: "MANDATORY" } },
-  ],
-});
+import { HttpSolverClient } from "dabke";
 
-const { request, canSolve, validation } = builder.compile();
+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" },
+  });
 
-if (!canSolve) {
-  console.error("Cannot solve:", validation.errors);
-  process.exit(1);
-}
-
-// Solve
-const solver = new HttpSolverClient(fetch, "http://localhost:8080");
-const response = await solver.solve(request);
-const result = parseSolverResponse(response);
-
-if (result.status === "OPTIMAL" || result.status === "FEASIBLE") {
-  const shifts = resolveAssignments(result.assignments, shiftPatterns);
-  for (const shift of shifts) {
-    console.log(
-      `${shift.employeeId}: ${shift.day} ${shift.startTime.hours}:00–${shift.endTime.hours}:00`,
-    );
-  }
-}
+console.log(result.status); // "optimal" | "feasible" | "infeasible" | "no_solution"
+console.log(result.assignments); // Shift assignments per member per day
 ```
 
-## Semantic Time
-
-Define named time periods that can vary by day, then write coverage requirements in business terms:
+Or compile and solve manually for more control:
 
 ```typescript
-import { defineSemanticTimes } from "dabke";
-
-const times = defineSemanticTimes({
-  lunch: [
-    {
-      startTime: { hours: 11, minutes: 30 },
-      endTime: { hours: 14 },
-      dayOfWeek: ["monday", "tuesday", "wednesday", "thursday", "friday"],
-    },
-    {
-      startTime: { hours: 12 },
-      endTime: { hours: 15 },
-      dayOfWeek: ["saturday", "sunday"],
-    },
-  ],
-  closing: { startTime: { hours: 21 }, endTime: { hours: 23 } },
-});
-
-const coverage = times.coverage([
-  { semanticTime: "lunch", roleIds: ["server"], targetCount: 3, priority: "MANDATORY" },
-  { semanticTime: "closing", roleIds: ["server"], targetCount: 1, priority: "HIGH" },
-]);
-
-// Resolve against actual scheduling days
-const days = ["2026-02-09", "2026-02-10", "2026-02-11"];
-const resolved = times.resolve(coverage, days);
+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);
+  // ...
+}
 ```
 
-## Built-in Rules
+---
 
-| Rule                           | Description                               |
-| ------------------------------ | ----------------------------------------- |
-| `max-hours-day`                | Max hours per person per day              |
-| `max-hours-week`               | Max hours per person per week             |
-| `min-hours-day`                | Min hours per person per day              |
-| `min-hours-week`               | Min hours per person per week             |
-| `max-shifts-day`               | Max shift assignments per day             |
-| `max-consecutive-days`         | Max consecutive working days              |
-| `min-consecutive-days`         | Min consecutive working days              |
-| `min-rest-between-shifts`      | Min rest hours between shifts             |
-| `time-off`                     | Block assignments during periods          |
-| `employee-assignment-priority` | Prefer or avoid assigning team members    |
-| `assign-together`              | Keep team members on the same shifts      |
-| `location-preference`          | Prefer team members at specific locations |
+## Key Concepts
 
-All rules support scoping by person, role, skill, and time period (date ranges, days of week, recurring periods).
+**Times vs shift patterns.** These are two distinct things. Times are named periods you need coverage for ("breakfast", "lunch_rush"). Shift patterns are the time slots people actually work ("opener 6-14", "closer 14-22"). They don't need to match. The solver assigns members to shift patterns whose hours overlap with times to satisfy coverage.
 
-### Scoping Example
+**Coverage.** How many people with which roles you need during each time. Coverage can vary by day of week or specific dates using scoping options or the variant form of `cover()`.
 
-```typescript
-// Students can work max 4 hours on weekdays
-{
-  name: "max-hours-day",
-  config: {
-    roleIds: ["student"],
-    hours: 4,
-    dayOfWeek: ["monday", "tuesday", "wednesday", "thursday", "friday"],
-    priority: "MANDATORY",
-  },
-}
-
-// Alice has time off next week
-{
-  name: "time-off",
-  config: {
-    employeeIds: ["alice"],
-    dateRange: { start: "2026-02-09", end: "2026-02-13" },
-    priority: "MANDATORY",
-  },
-}
-```
+**Rules.** Business constraints expressed as function calls. Rules with `priority: "MANDATORY"` (the default) are hard constraints the solver will never violate. Rules with `LOW`, `MEDIUM`, or `HIGH` priority are soft preferences the solver optimizes across.
 
-### Soft vs. Hard Constraints
-
-Rules with `priority: "MANDATORY"` are hard constraints — the solver will not violate them. Rules with `LOW`, `MEDIUM`, or `HIGH` priority are soft constraints — the solver tries to satisfy them but will trade them off against each other to find the best overall schedule.
+**Scoping.** Every rule accepts `appliesTo` (a role, skill, or member ID), plus time scoping (`dayOfWeek`, `dateRange`, `dates`, `recurringPeriods`) to target when and who:
 
 ```typescript
-// Hard: legally required rest period
-{ name: "min-rest-between-shifts", config: { hours: 11, priority: "MANDATORY" } }
-
-// Soft: prefer to keep Bob under 30 hours/week
-{ name: "max-hours-week", config: { employeeIds: ["bob"], hours: 30, weekStartsOn: "monday", priority: "MEDIUM" } }
+maxHoursPerDay(8, { appliesTo: "barista", dayOfWeek: weekdays }),
+timeOff({ appliesTo: "alice", dateRange: { start: "2026-02-09", end: "2026-02-13" } }),
+maxHoursPerWeek(30, { appliesTo: "bob", priority: "MEDIUM" }),
 ```
 
-## Validation
+**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.
 
-dabke validates schedules and reports coverage gaps and rule violations:
+**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
-import { ValidationReporterImpl, summarizeValidation } from "dabke";
-
-const reporter = new ValidationReporterImpl();
-const builder = new ModelBuilder({ ...config, reporter });
-const { request, validation, canSolve } = builder.compile();
-
-// Pre-solve validation
-if (!canSolve) {
-  for (const error of validation.errors) {
-    console.error(error.reason);
-  }
-}
+const ready = venue.with([
+  { id: "alice", roleIds: ["barista"], pay: { hourlyRate: 1500 } },
+  { id: "bob", roleIds: ["barista"], pay: { hourlyRate: 1200 } },
+]);
+```
 
-// Post-solve validation (after solving)
-reporter.analyzeSolution(response);
-const results = reporter.getValidation();
-const summaries = summarizeValidation(results);
+---
 
-for (const s of summaries) {
-  console.log(
-    `${s.description}: ${s.status} (${s.passedCount}/${s.passedCount + s.violatedCount})`,
-  );
-}
-```
+## Rules
 
-## Custom Rules
+### Scheduling
 
-dabke's rule system is extensible. You can create custom rules that integrate with the model builder:
+| Function                   | Description                          |
+| -------------------------- | ------------------------------------ |
+| `maxHoursPerDay(hours)`    | Max hours per person per day         |
+| `maxHoursPerWeek(hours)`   | Max hours per person per week        |
+| `minHoursPerDay(hours)`    | Min hours per person per day         |
+| `minHoursPerWeek(hours)`   | Min hours per person per week        |
+| `maxShiftsPerDay(n)`       | Max shift assignments per day        |
+| `maxConsecutiveDays(n)`    | Max consecutive working days         |
+| `minConsecutiveDays(n)`    | Min consecutive working days         |
+| `minRestBetweenShifts(h)`  | Min rest hours between shifts        |
+| `timeOff(opts)`            | Block assignments during periods     |
+| `preference(level, opts)`  | Prefer or avoid assigning members    |
+| `preferLocation(id, opts)` | Prefer members at specific locations |
+| `assignTogether(opts)`     | Keep members on the same shifts      |
 
-```typescript
-import { createCpsatRuleFactory, type CompilationRule } from "dabke";
-
-function createNoSundayWorkRule(config: { priority: "MANDATORY" | "HIGH" }): CompilationRule {
-  return {
-    compile(b) {
-      for (const emp of b.employees) {
-        for (const day of b.days) {
-          const date = new Date(`${day}T00:00:00Z`);
-          if (date.getUTCDay() !== 0) continue; // Sunday = 0
-          for (const pattern of b.shiftPatterns) {
-            if (!b.canAssign(emp, pattern)) continue;
-            b.addLinear([{ var: b.assignment(emp.id, pattern.id, day), coeff: 1 }], "<=", 0);
-          }
-        }
-      }
-    },
-  };
-}
+### Cost
 
-const customRules = createCpsatRuleFactory({
-  "no-sunday-work": createNoSundayWorkRule,
-});
-```
+| Function                                 | Description                              |
+| ---------------------------------------- | ---------------------------------------- |
+| `minimizeCost()`                         | Minimize total labor cost                |
+| `dayMultiplier(factor, opts?)`           | Pay multiplier for specific days         |
+| `daySurcharge(amount, opts?)`            | Flat surcharge per hour on specific days |
+| `timeSurcharge(amount, window, opts?)`   | Surcharge during a time-of-day window    |
+| `overtimeMultiplier(opts)`               | Weekly overtime pay multiplier           |
+| `overtimeSurcharge(opts)`                | Weekly overtime flat surcharge           |
+| `dailyOvertimeMultiplier(opts)`          | Daily overtime pay multiplier            |
+| `dailyOvertimeSurcharge(opts)`           | Daily overtime flat surcharge            |
+| `tieredOvertimeMultiplier(tiers, opts?)` | Graduated overtime rates                 |
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide on writing custom rules.
+---
 
 ## LLM Integration
 
-dabke ships an `llms.txt` file with complete API documentation, designed for AI code generation:
+dabke ships an `llms.txt` with complete API documentation for AI code generation:
 
 ```typescript
 import { apiDocs } from "dabke/llms";
-
-// Pass to your LLM as context for generating scheduling code
 ```
 
-Or read the file directly:
-
-```bash
-cat node_modules/dabke/llms.txt
-```
+---
 
 ## Development
 
-### Running tests
-
-Unit tests have no external dependencies:
-
-```bash
-npm run test:unit
-```
-
-Integration tests require Docker to run the solver container:
+Unit tests (no dependencies): `npm run test:unit`
 
-```bash
-# Ensure Docker is running, then:
-npm run test:integration
-```
+Integration tests (requires Docker): `npm run test:integration`
 
-The integration test harness (`startSolverContainer`) builds and starts a Docker container from `solver/Dockerfile` automatically. It binds to port 18080 by default — make sure no other container is using that port.
-
-To run both unit and integration tests:
-
-```bash
-npm test          # runs typecheck + unit tests only
-npm run test:integration   # solver integration tests (requires Docker)
-```
-
-### Test utilities
-
-dabke exports test helpers for writing your own integration tests:
+The test harness builds and starts a solver container from `solver/Dockerfile` automatically.
 
 ```typescript
 import { startSolverContainer } from "dabke/testing";
-
 const solver = await startSolverContainer();
-const response = await solver.client.solve(request);
-solver.stop();
 ```
 
-This builds the solver Docker image, starts a container, waits for the health check, and returns a pre-configured `HttpSolverClient`.
-
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, how to add rules, and contribution guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add rules and contribute.
 
 ## License
 

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;