dabke 0.78.0

package/src/testing/solver-container.ts

@@ -0,0 +1,172 @@
+/**
+ * Test utility for starting and managing the solver Docker container.
+ *
+ * This module provides a Node.js-compatible way to spin up the solver container
+ * for integration tests. It handles:
+ * - Building the Docker image (once per process)
+ * - Starting containers on dynamic ports
+ * - Health checking before returning
+ * - Cleanup on stop
+ *
+ * @example
+ * ```typescript
+ * import { startSolverContainer } from "dabke/testing";
+ *
+ * const solver = await startSolverContainer();
+ * // solver.client is ready to use
+ * const response = await solver.client.solve(request);
+ * solver.stop();
+ * ```
+ */
+
+import { spawnSync } from "node:child_process";
+import { createServer } from "node:net";
+import { resolve } from "node:path";
+import { fileURLToPath, URL as NodeURL } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+import { HttpSolverClient } from "../client.js";
+
+const __dirname = fileURLToPath(new NodeURL(".", import.meta.url));
+// src/testing/ -> src/ -> package root -> solver/
+const defaultSolverDir = resolve(__dirname, "..", "..", "solver");
+
+let imageBuilt = false;
+
+const allocatePort = (): Promise<number> =>
+  new Promise((resolvePort, reject) => {
+    const server = createServer();
+    server.unref();
+    server.on("error", (err) => {
+      server.close();
+      reject(err);
+    });
+    server.listen(0, () => {
+      const address = server.address();
+      if (typeof address === "object" && address) {
+        const { port } = address;
+        server.close(() => resolvePort(port));
+      } else {
+        server.close(() => reject(new Error("Could not allocate port")));
+      }
+    });
+  });
+
+export interface SolverContainerOptions {
+  /** Port to expose the solver on. If not provided, a random available port is allocated. */
+  port?: number;
+  /** Directory containing the solver Dockerfile. Defaults to the solver/ directory in the package. */
+  solverDir?: string;
+  /** Docker image tag to use. Defaults to "dabke-solver:test". */
+  imageTag?: string;
+  /** Skip building the image (assume it already exists). */
+  skipBuild?: boolean;
+}
+
+export interface SolverContainer {
+  /** The port the solver is running on. */
+  port: number;
+  /** Pre-configured HTTP client for the solver. */
+  client: HttpSolverClient;
+  /** Stop and remove the container. */
+  stop: () => void;
+  /** Check if the solver is still healthy. Throws if not. */
+  ensureHealthy: () => Promise<void>;
+}
+
+const ensureSolverImage = (solverDir: string, imageTag: string) => {
+  if (imageBuilt) return;
+
+  const buildResult = spawnSync("docker", ["build", "-t", imageTag, "."], {
+    cwd: solverDir,
+    stdio: "inherit",
+  });
+
+  if (buildResult.error) {
+    throw new Error(`Docker build spawn error: ${buildResult.error.message}`);
+  }
+  if (buildResult.status !== 0) {
+    throw new Error(`Docker build failed with status ${buildResult.status}`);
+  }
+
+  imageBuilt = true;
+};
+
+/**
+ * Start a solver container for testing.
+ *
+ * Builds the Docker image if needed, starts a container on an available port,
+ * waits for the health endpoint to respond, and returns a client.
+ */
+export const startSolverContainer = async (
+  options: SolverContainerOptions = {},
+): Promise<SolverContainer> => {
+  const {
+    port,
+    solverDir = defaultSolverDir,
+    imageTag = "dabke-solver:test",
+    skipBuild = false,
+  } = options;
+
+  if (!skipBuild) {
+    ensureSolverImage(solverDir, imageTag);
+  }
+
+  const resolvedPort = port ?? (await allocatePort());
+
+  const runResult = spawnSync("docker", [
+    "run",
+    "-d",
+    "--rm",
+    "-p",
+    `${resolvedPort}:8080`,
+    imageTag,
+  ]);
+
+  if (runResult.error) {
+    throw new Error(`Docker run spawn error: ${runResult.error.message}`);
+  }
+  if (runResult.status !== 0) {
+    throw new Error(`Docker run failed: ${runResult.stderr?.toString()}`);
+  }
+
+  const containerId = runResult.stdout.toString().trim();
+
+  const client = new HttpSolverClient(fetch, `http://localhost:${resolvedPort}`);
+
+  // Wait for container to be healthy (up to 30 seconds)
+  /* oxlint-disable no-await-in-loop -- Retry loop requires sequential attempts */
+  let attempts = 0;
+  while (attempts < 60) {
+    try {
+      await client.health?.();
+      break;
+    } catch {
+      attempts += 1;
+      await delay(500);
+    }
+  }
+  /* oxlint-enable no-await-in-loop */
+
+  if (attempts >= 60) {
+    // Clean up the container if health check never succeeded
+    spawnSync("docker", ["rm", "-f", containerId], { stdio: "ignore" });
+    throw new Error("Solver container failed to become healthy after 30 seconds");
+  }
+
+  return {
+    port: resolvedPort,
+    client,
+    stop: () => {
+      spawnSync("docker", ["rm", "-f", containerId], { stdio: "ignore" });
+    },
+    async ensureHealthy() {
+      try {
+        await client.health?.();
+      } catch (err) {
+        throw new Error(
+          `Solver container health check failed. Container may have crashed. Error: ${err}`,
+        );
+      }
+    },
+  };
+};

package/src/types.ts

@@ -0,0 +1,191 @@
+/**
+ * Core scheduling types for the CP-SAT solver.
+ *
+ * @packageDocumentation
+ */
+
+import * as z from "zod";
+
+// ============================================================================
+// Time Primitives
+// ============================================================================
+
+export type DayOfWeek =
+  | "monday"
+  | "tuesday"
+  | "wednesday"
+  | "thursday"
+  | "friday"
+  | "saturday"
+  | "sunday";
+
+/**
+ * Zod schema for {@link DayOfWeek}.
+ * Useful for rule configs that need to accept a day-of-week string.
+ */
+
+export const DayOfWeekSchema = z.union([
+  z.literal("monday"),
+  z.literal("tuesday"),
+  z.literal("wednesday"),
+  z.literal("thursday"),
+  z.literal("friday"),
+  z.literal("saturday"),
+  z.literal("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).
+ *
+ * @example
+ * ```typescript
+ * const morningStart: TimeOfDay = {
+ *   hours: 9,
+ *   minutes: 0
+ * };
+ *
+ * const afternoonEnd: TimeOfDay = {
+ *   hours: 17,
+ *   minutes: 30
+ * };
+ * ```
+ */
+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;
+}
+
+// ============================================================================
+// DateTime Types
+// ============================================================================
+
+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;
+}
+
+// ============================================================================
+// Scheduling Period
+// ============================================================================
+
+/**
+ * Defines a scheduling period either as a date range or specific dates.
+ *
+ * Use this to specify when scheduling should occur. This is more expressive
+ * than a simple list of days because it can filter by day-of-week.
+ *
+ * @example Date range with day-of-week filtering (restaurant closed Mon/Tue)
+ * ```typescript
+ * const period: SchedulingPeriod = {
+ *   dateRange: { start: '2025-02-03', end: '2025-02-09' },
+ *   daysOfWeek: ['wednesday', 'thursday', 'friday', 'saturday', 'sunday'],
+ * };
+ * ```
+ *
+ * @example Date range for all days
+ * ```typescript
+ * const period: SchedulingPeriod = {
+ *   dateRange: { start: '2025-02-03', end: '2025-02-09' },
+ * };
+ * ```
+ *
+ * @example Specific dates (non-contiguous or custom selection)
+ * ```typescript
+ * const period: SchedulingPeriod = {
+ *   specificDates: ['2025-02-05', '2025-02-07', '2025-02-10'],
+ * };
+ * ```
+ */
+export type SchedulingPeriod =
+  | {
+      /**
+       * A contiguous date range (start and end are inclusive).
+       * Dates should be in YYYY-MM-DD format.
+       */
+      dateRange: { start: string; end: string };
+      /**
+       * Optional filter to include only specific days of the week.
+       * If omitted, all days in the range are included.
+       */
+      daysOfWeek?: DayOfWeek[];
+      specificDates?: never;
+    }
+  | {
+      /**
+       * A list of specific dates to schedule.
+       * Dates should be in YYYY-MM-DD format.
+       */
+      specificDates: string[];
+      dateRange?: never;
+      daysOfWeek?: never;
+    };

package/src/validation.ts

@@ -0,0 +1,188 @@
+/**
+ * Validation utilities for scheduling configuration.
+ *
+ * These functions help catch configuration errors early, before the ModelBuilder
+ * attempts to compile the scheduling problem. This is especially useful when
+ * configuration is generated by an LLM, which may hallucinate role or skill names.
+ */
+
+import type { CoverageRequirement, SchedulingEmployee } from "./cpsat/types.js";
+
+/**
+ * Result of coverage role validation.
+ */
+export interface CoverageValidationResult {
+  valid: boolean;
+  /** Role IDs used in coverage that don't match any team member */
+  unknownRoles: string[];
+  /** Role IDs used in coverage that match team members */
+  knownRoles: string[];
+}
+
+/**
+ * Validates that all roleIds used in coverage requirements match the team.
+ *
+ * This catches a common LLM error where the model generates coverage requirements
+ * using role names that don't match any team member's roleIds. Without this validation,
+ * such mismatches would result in valid but semantically wrong schedules (e.g.,
+ * coverage requirements that no one can satisfy).
+ *
+ * @example
+ * ```typescript
+ * const employees = [
+ *   { id: "alice", roleIds: ["cashier"] },
+ *   { id: "bob", roleIds: ["stocker"] },
+ * ];
+ *
+ * const coverage = [
+ *   { roleId: "cashier", targetCount: 1, ... },  // OK
+ *   { roleId: "worker", targetCount: 1, ... },   // Unknown role!
+ * ];
+ *
+ * const result = validateCoverageRoles(coverage, employees);
+ * // result.valid = false
+ * // result.unknownRoles = ["worker"]
+ * // result.knownRoles = ["cashier"]
+ * ```
+ */
+export function validateCoverageRoles(
+  coverage: CoverageRequirement[],
+  employees: SchedulingEmployee[],
+): CoverageValidationResult {
+  const employeeRoles = new Set(employees.flatMap((e) => e.roleIds));
+  const coverageRoles = new Set(coverage.flatMap((c) => c.roleIds ?? []));
+
+  const unknownRoles: string[] = [];
+  const knownRoles: string[] = [];
+
+  for (const role of coverageRoles) {
+    if (employeeRoles.has(role)) {
+      knownRoles.push(role);
+    } else {
+      unknownRoles.push(role);
+    }
+  }
+
+  return {
+    valid: unknownRoles.length === 0,
+    unknownRoles: unknownRoles.toSorted(),
+    knownRoles: knownRoles.toSorted(),
+  };
+}
+
+/**
+ * Result of coverage skill validation.
+ */
+export interface SkillValidationResult {
+  valid: boolean;
+  /** Skill IDs used in coverage that don't match any team member */
+  unknownSkills: string[];
+  /** Skill IDs used in coverage that match team members */
+  knownSkills: string[];
+}
+
+/**
+ * Validates that all skillIds used in coverage requirements match the team.
+ *
+ * Similar to role validation, this catches LLM hallucinations where skill names
+ * in coverage don't match any team member's skillIds.
+ *
+ * @example
+ * ```typescript
+ * const employees = [
+ *   { id: "alice", roleIds: ["server"], skillIds: ["keyholder"] },
+ *   { id: "bob", roleIds: ["server"] },
+ * ];
+ *
+ * const coverage = [
+ *   { skillIds: ["keyholder"], targetCount: 1, ... },  // OK
+ *   { skillIds: ["manager"], targetCount: 1, ... },   // Unknown skill!
+ * ];
+ *
+ * const result = validateCoverageSkills(coverage, employees);
+ * // result.valid = false
+ * // result.unknownSkills = ["manager"]
+ * ```
+ */
+export function validateCoverageSkills(
+  coverage: CoverageRequirement[],
+  employees: SchedulingEmployee[],
+): SkillValidationResult {
+  const employeeSkills = new Set(employees.flatMap((e) => e.skillIds ?? []));
+  const coverageSkills = new Set(coverage.flatMap((c) => c.skillIds ?? []));
+
+  const unknownSkills: string[] = [];
+  const knownSkills: string[] = [];
+
+  for (const skill of coverageSkills) {
+    if (employeeSkills.has(skill)) {
+      knownSkills.push(skill);
+    } else {
+      unknownSkills.push(skill);
+    }
+  }
+
+  return {
+    valid: unknownSkills.length === 0,
+    unknownSkills: unknownSkills.toSorted(),
+    knownSkills: knownSkills.toSorted(),
+  };
+}
+
+/**
+ * Combined validation result for coverage requirements.
+ */
+export interface CoverageConfigValidationResult {
+  valid: boolean;
+  roles: CoverageValidationResult;
+  skills: SkillValidationResult;
+  /** Human-readable error messages */
+  errors: string[];
+}
+
+/**
+ * Validates coverage requirements against team roles and skills.
+ *
+ * This is the primary validation function to call before building a scheduling model.
+ * It checks both roles and skills, returning a combined result with error messages.
+ *
+ * @example
+ * ```typescript
+ * const result = validateCoverageConfig(coverage, employees);
+ * if (!result.valid) {
+ *   throw new Error(result.errors.join("; "));
+ * }
+ * ```
+ */
+export function validateCoverageConfig(
+  coverage: CoverageRequirement[],
+  employees: SchedulingEmployee[],
+): CoverageConfigValidationResult {
+  const roles = validateCoverageRoles(coverage, employees);
+  const skills = validateCoverageSkills(coverage, employees);
+
+  const errors: string[] = [];
+
+  if (!roles.valid) {
+    const availableRoles = [...new Set(employees.flatMap((e) => e.roleIds))].toSorted();
+    errors.push(
+      `Coverage uses unknown roles: ${roles.unknownRoles.join(", ")}. ` +
+        `Available roles: ${availableRoles.join(", ")}`,
+    );
+  }
+
+  if (!skills.valid) {
+    const availableSkills = [...new Set(employees.flatMap((e) => e.skillIds ?? []))].toSorted();
+    errors.push(
+      `Coverage uses unknown skills: ${skills.unknownSkills.join(", ")}. ` +
+        `Available skills: ${availableSkills.length > 0 ? availableSkills.join(", ") : "(none)"}`,
+    );
+  }
+
+  return {
+    valid: roles.valid && skills.valid,
+    roles,
+    skills,
+    errors,
+  };
+}