dabke 0.81.1 → 0.83.0

package/src/cpsat/utils.ts

@@ -59,19 +59,15 @@ export function normalizeEndMinutes(startMinutes: number, endMinutes: number): n
   return endMinutes < startMinutes ? endMinutes + MINUTES_PER_DAY : endMinutes;
 }
 
+const PRIORITY_PENALTIES = {
+  LOW: 1,
+  MEDIUM: 10,
+  HIGH: 25,
+  MANDATORY: 0,
+} as const satisfies Record<Priority, number>;
+
 export function priorityToPenalty(priority: Priority): number {
-  switch (priority) {
-    case "HIGH":
-      return 25;
-    case "MEDIUM":
-      return 10;
-    case "LOW":
-      return 1;
-    case "MANDATORY":
-      return 0;
-    default:
-      return 0;
-  }
+  return PRIORITY_PENALTIES[priority];
 }
 
 /**

package/src/cpsat/validation-reporter.ts

@@ -1,6 +1,5 @@
 import type { SolverResponse } from "../client.types.js";
 import {
-  groupKey,
   type ScheduleError,
   type ScheduleViolation,
   type SchedulePassed,
@@ -14,7 +13,6 @@ import {
   type RulePassed,
   type CoverageExclusion,
   type ValidationSummary,
-  type GroupKey,
 } from "./validation.types.js";
 
 export interface ValidationReporter {
@@ -24,7 +22,7 @@ export interface ValidationReporter {
   // Errors (block generation)
   reportCoverageError(error: Omit<CoverageError, "type" | "id">): void;
   reportRuleError(error: Omit<RuleError, "type" | "id">): void;
-  reportSolverError(reason: string): void;
+  reportSolverError(message: string): void;
 
   // Violations (soft constraint issues)
   reportCoverageViolation(violation: Omit<CoverageViolation, "type" | "id">): void;
@@ -54,16 +52,16 @@ function coverageId(
   category: "error" | "violation" | "passed",
   day: string,
   timeSlots: readonly string[],
-  roles?: readonly string[],
-  skills?: readonly string[],
+  roleIds?: readonly string[],
+  skillIds?: readonly string[],
 ): string {
   const parts = [
     category,
     "coverage",
     day,
     [...timeSlots].toSorted().join(",") || "_",
-    roles && roles.length > 0 ? [...roles].toSorted().join(",") : "_",
-    skills ? [...skills].toSorted().join(",") : "_",
+    roleIds && roleIds.length > 0 ? [...roleIds].toSorted().join(",") : "_",
+    skillIds ? [...skillIds].toSorted().join(",") : "_",
   ];
   return parts.join(":");
 }
@@ -100,7 +98,7 @@ export class ValidationReporterImpl implements ValidationReporter {
   }
 
   reportCoverageError(error: Omit<CoverageError, "type" | "id">): void {
-    const id = coverageId("error", error.day, error.timeSlots, error.roles, error.skills);
+    const id = coverageId("error", error.day, error.timeSlots, error.roleIds, error.skillIds);
     this.#errors.push({ id, type: "coverage", ...error });
   }
 
@@ -109,10 +107,10 @@ export class ValidationReporterImpl implements ValidationReporter {
     this.#errors.push({ id, type: "rule", ...error });
   }
 
-  reportSolverError(reason: string): void {
+  reportSolverError(message: string): void {
     this.#solverErrorCount++;
     const id = `error:solver:${this.#solverErrorCount}`;
-    this.#errors.push({ id, type: "solver", reason });
+    this.#errors.push({ id, type: "solver", message });
   }
 
   reportCoverageViolation(violation: Omit<CoverageViolation, "type" | "id">): void {
@@ -120,8 +118,8 @@ export class ValidationReporterImpl implements ValidationReporter {
       "violation",
       violation.day,
       violation.timeSlots,
-      violation.roles,
-      violation.skills,
+      violation.roleIds,
+      violation.skillIds,
     );
     this.#violations.push({ id, type: "coverage", ...violation });
   }
@@ -132,7 +130,7 @@ export class ValidationReporterImpl implements ValidationReporter {
   }
 
   reportCoveragePassed(passed: Omit<CoveragePassed, "type" | "id">): void {
-    const id = coverageId("passed", passed.day, passed.timeSlots, passed.roles, passed.skills);
+    const id = coverageId("passed", passed.day, passed.timeSlots, passed.roleIds, passed.skillIds);
     this.#passed.push({ id, type: "coverage", ...passed });
   }
 
@@ -183,31 +181,33 @@ export class ValidationReporterImpl implements ValidationReporter {
       const tracked = this.#trackedConstraints.get(violation.constraintId);
 
       if (tracked?.type === "coverage") {
+        const roles = tracked.roleIds?.join(", ") ?? "staff";
+        const slot = tracked.timeSlot ?? "all day";
         this.reportCoverageViolation({
           day: tracked.day ?? "",
           timeSlots: tracked.timeSlot ? [tracked.timeSlot] : [],
-          roles: tracked.roles,
-          skills: tracked.skills,
+          roleIds: tracked.roleIds,
+          skillIds: tracked.skillIds,
           targetCount: violation.targetValue,
           actualCount: violation.actualValue,
           shortfall: violation.violationAmount,
-          groupKey: tracked.groupKey,
+          message: `${roles} on ${tracked.day} (${slot}): ${violation.actualValue} assigned, need ${violation.targetValue}`,
+          group: tracked.group,
         });
       } else if (tracked?.type === "rule") {
         const isShortfall = tracked.comparator === ">=";
         this.reportRuleViolation({
           rule: tracked.rule ?? "unknown",
-          reason: `${tracked.description}: needed ${violation.targetValue}, got ${violation.actualValue}`,
+          message: `${tracked.description}: needed ${violation.targetValue}, got ${violation.actualValue}`,
           context: tracked.context,
           shortfall: isShortfall ? violation.violationAmount : undefined,
           overflow: !isShortfall ? violation.violationAmount : undefined,
-          groupKey: tracked.groupKey,
+          group: tracked.group,
         });
       } else {
-        // Unknown constraint - create generic rule violation
         this.reportRuleViolation({
           rule: "unknown",
-          reason: `Constraint ${violation.constraintId} violated by ${violation.violationAmount}`,
+          message: `Constraint ${violation.constraintId} violated by ${violation.violationAmount}`,
           context: {},
         });
       }
@@ -222,10 +222,10 @@ export class ValidationReporterImpl implements ValidationReporter {
         this.reportCoveragePassed({
           day: tracked.day ?? "",
           timeSlots: tracked.timeSlot ? [tracked.timeSlot] : [],
-          roles: tracked.roles,
-          skills: tracked.skills,
-          description: tracked.description,
-          groupKey: tracked.groupKey,
+          roleIds: tracked.roleIds,
+          skillIds: tracked.skillIds,
+          message: tracked.description,
+          group: tracked.group,
         });
       }
     }
@@ -233,23 +233,26 @@ export class ValidationReporterImpl implements ValidationReporter {
 }
 
 // =============================================================================
-// Validation Summary - pure function for aggregation
+// Validation Summary
 // =============================================================================
 
 type ValidationItem = ScheduleError | ScheduleViolation | SchedulePassed;
 
 /**
- * Aggregates validation items by their groupKey into summaries.
- * This is a pure function that doesn't modify the input.
+ * Aggregates validation items by their group into summaries.
  *
- * Items without a groupKey are grouped by their ID (ungrouped).
+ * Items sharing the same `group.key` are merged into a single summary.
+ * The title comes from the first item's `group.title`; for ungrouped items
+ * the item's `message` is used instead.
+ *
+ * @category Validation
  *
  * @example
  * ```typescript
- * const validation = reporter.getValidation();
  * const summaries = summarizeValidation(validation);
  * // summaries[0] = {
- * //   groupKey: "2x waiter during lunch",
+ * //   groupKey: "coverage:day_ward:nurse:3:dow:monday,tuesday,...",
+ * //   title: "3x nurse during day_ward (weekdays)",
  * //   status: "passed",
  * //   passedCount: 180,
  * //   days: ["2026-02-02", "2026-02-03", ...]
@@ -258,10 +261,10 @@ type ValidationItem = ScheduleError | ScheduleViolation | SchedulePassed;
  */
 export function summarizeValidation(validation: ScheduleValidation): readonly ValidationSummary[] {
   const groups = new Map<
-    GroupKey,
+    string,
     {
       type: "coverage" | "rule";
-      items: ValidationItem[];
+      title: string;
       days: Set<string>;
       passedCount: number;
       violatedCount: number;
@@ -269,11 +272,14 @@ export function summarizeValidation(validation: ScheduleValidation): readonly Va
     }
   >();
 
-  const getOrCreateGroup = (key: GroupKey, type: "coverage" | "rule") => {
+  const getOrCreateStats = (item: Exclude<ValidationItem, { type: "solver" }>) => {
+    const key = ("group" in item && item.group?.key) || `ungrouped:${item.id}`;
+    const title = ("group" in item && item.group?.title) || item.message;
+
     if (!groups.has(key)) {
       groups.set(key, {
-        type,
-        items: [],
+        type: item.type,
+        title,
         days: new Set(),
         passedCount: 0,
         violatedCount: 0,
@@ -283,41 +289,31 @@ export function summarizeValidation(validation: ScheduleValidation): readonly Va
     return groups.get(key)!;
   };
 
-  // Group passed items
   for (const item of validation.passed) {
-    const key = item.groupKey ?? groupKey(`ungrouped:${item.id}`);
-    const group = getOrCreateGroup(key, item.type);
-    group.items.push(item);
-    group.passedCount++;
+    const stats = getOrCreateStats(item);
+    stats.passedCount++;
     if (item.type === "coverage" && item.day) {
-      group.days.add(item.day);
+      stats.days.add(item.day);
     }
   }
 
-  // Group violations
   for (const item of validation.violations) {
-    const key = item.groupKey ?? groupKey(`ungrouped:${item.id}`);
-    const group = getOrCreateGroup(key, item.type);
-    group.items.push(item);
-    group.violatedCount++;
+    const stats = getOrCreateStats(item);
+    stats.violatedCount++;
     if (item.type === "coverage" && item.day) {
-      group.days.add(item.day);
+      stats.days.add(item.day);
     }
   }
 
-  // Group errors (except solver errors which don't have groupKey)
   for (const item of validation.errors) {
     if (item.type === "solver") continue;
-    const key = item.groupKey ?? groupKey(`ungrouped:${item.id}`);
-    const group = getOrCreateGroup(key, item.type);
-    group.items.push(item);
-    group.errorCount++;
+    const stats = getOrCreateStats(item);
+    stats.errorCount++;
     if (item.type === "coverage" && item.day) {
-      group.days.add(item.day);
+      stats.days.add(item.day);
     }
   }
 
-  // Build summaries
   const summaries: ValidationSummary[] = [];
   for (const [key, group] of groups) {
     const status: ValidationSummary["status"] =
@@ -326,7 +322,7 @@ export function summarizeValidation(validation: ScheduleValidation): readonly Va
     summaries.push({
       groupKey: key,
       type: group.type,
-      description: inferDescription(key, group.items),
+      title: group.title,
       days: [...group.days].toSorted(),
       status,
       passedCount: group.passedCount,
@@ -337,30 +333,3 @@ export function summarizeValidation(validation: ScheduleValidation): readonly Va
 
   return summaries;
 }
-
-/**
- * Infers a human-readable description from the groupKey or items.
- */
-function inferDescription(key: GroupKey, items: ValidationItem[]): string {
-  // If the key looks like a human-readable description, use it
-  if (!key.startsWith("ungrouped:")) {
-    return key;
-  }
-
-  // Try to infer from the first item with a description
-  for (const item of items) {
-    if ("description" in item && item.description) {
-      // Extract the meaningful part (e.g., "2x waiter" from "2x waiter on 2026-02-03 at 09:00")
-      const match = item.description.match(/^(\d+x \w+)/);
-      if (match?.[1]) {
-        return match[1];
-      }
-      return item.description;
-    }
-    if ("reason" in item && item.reason) {
-      return item.reason;
-    }
-  }
-
-  return key;
-}

package/src/cpsat/validation.types.ts

@@ -1,38 +1,56 @@
 import type { TimeOfDay } from "../types.js";
 
-// =============================================================================
-// Group Key - for aggregating related validation items
-// =============================================================================
-
-declare const GroupKeyBrand: unique symbol;
-
 /**
- * Branded type for validation group keys.
- * Groups related validation items that originated from the same instruction.
+ * Context shared across validation results for grouping/display.
  */
-export type GroupKey = string & { readonly [GroupKeyBrand]: never };
+export interface ValidationContext {
+  days?: string[];
+  timeSlots?: string[];
+  memberIds?: string[];
+}
+
+// =============================================================================
+// Validation Group
+// =============================================================================
 
 /**
- * Creates a GroupKey from a description string.
- * Use this to create keys that group related validation items together.
+ * Groups related validation items under a deterministic, structural key.
+ *
+ * The `key` is derived from the rule/coverage structure (e.g.,
+ * `"rule:max-hours-week:40:roles:nurse"`), ensuring that identical
+ * configurations always produce the same key. The `title` is the
+ * human-readable label shown in summaries.
  *
- * @example
- * ```typescript
- * const key = groupKey("2x waiter during lunch");
- * coverage.groupKey = key;
- * ```
+ * Rule authors create groups via {@link ruleGroup} in `scope.types.ts`;
+ * coverage groups are produced by the semantic-time resolver.
  */
-export function groupKey(description: string): GroupKey {
-  return description as GroupKey;
+export interface ValidationGroup {
+  /** Deterministic key derived from rule/coverage structure. */
+  readonly key: string;
+  /** Human-readable label for summaries (e.g., "Max 40h per week"). */
+  readonly title: string;
 }
 
+// =============================================================================
+// Key safety helpers
+// =============================================================================
+
+const KEY_DELIMITERS = /[,:/+]/;
+
 /**
- * Context shared across validation results for grouping/display.
+ * Throws if a value contains characters used as key delimiters.
+ * Call before interpolating user-provided IDs into group keys.
  */
-export interface ValidationContext {
-  days?: string[];
-  timeSlots?: string[];
-  memberIds?: string[];
+export function assertSafeKeySegment(value: string, label: string): void {
+  if (KEY_DELIMITERS.test(value)) {
+    throw new Error(`${label} "${value}" contains reserved delimiter characters (: , / +)`);
+  }
+}
+
+export function assertSafeKeySegments(values: readonly string[], label: string): void {
+  for (const v of values) {
+    assertSafeKeySegment(v, label);
+  }
 }
 
 // =============================================================================
@@ -44,27 +62,27 @@ export interface CoverageError {
   readonly type: "coverage";
   readonly day: string;
   readonly timeSlots: readonly string[];
-  readonly roles?: string[];
-  readonly skills?: readonly string[];
-  readonly reason: string;
+  readonly roleIds?: string[];
+  readonly skillIds?: readonly string[];
+  readonly message: string;
   readonly suggestions?: readonly string[];
-  readonly groupKey?: GroupKey;
+  readonly group?: ValidationGroup;
 }
 
 export interface RuleError {
   readonly id: string;
   readonly type: "rule";
   readonly rule: string;
-  readonly reason: string;
+  readonly message: string;
   readonly context: ValidationContext;
   readonly suggestions?: readonly string[];
-  readonly groupKey?: GroupKey;
+  readonly group?: ValidationGroup;
 }
 
 export interface SolverError {
   readonly id: string;
   readonly type: "solver";
-  readonly reason: string;
+  readonly message: string;
 }
 
 export type ScheduleError = CoverageError | RuleError | SolverError;
@@ -78,23 +96,24 @@ export interface CoverageViolation {
   readonly type: "coverage";
   readonly day: string;
   readonly timeSlots: readonly string[];
-  readonly roles?: string[];
-  readonly skills?: readonly string[];
+  readonly roleIds?: string[];
+  readonly skillIds?: readonly string[];
   readonly targetCount: number;
   readonly actualCount: number;
   readonly shortfall: number;
-  readonly groupKey?: GroupKey;
+  readonly message: string;
+  readonly group?: ValidationGroup;
 }
 
 export interface RuleViolation {
   readonly id: string;
   readonly type: "rule";
   readonly rule: string;
-  readonly reason: string;
+  readonly message: string;
   readonly context: ValidationContext;
   readonly shortfall?: number;
   readonly overflow?: number;
-  readonly groupKey?: GroupKey;
+  readonly group?: ValidationGroup;
 }
 
 export type ScheduleViolation = CoverageViolation | RuleViolation;
@@ -108,19 +127,19 @@ export interface CoveragePassed {
   readonly type: "coverage";
   readonly day: string;
   readonly timeSlots: readonly string[];
-  readonly roles?: string[];
-  readonly skills?: readonly string[];
-  readonly description: string;
-  readonly groupKey?: GroupKey;
+  readonly roleIds?: string[];
+  readonly skillIds?: readonly string[];
+  readonly message: string;
+  readonly group?: ValidationGroup;
 }
 
 export interface RulePassed {
   readonly id: string;
   readonly type: "rule";
   readonly rule: string;
-  readonly description: string;
+  readonly message: string;
   readonly context: ValidationContext;
-  readonly groupKey?: GroupKey;
+  readonly group?: ValidationGroup;
 }
 
 export type SchedulePassed = CoveragePassed | RulePassed;
@@ -129,6 +148,7 @@ export type SchedulePassed = CoveragePassed | RulePassed;
 // Complete validation result
 // =============================================================================
 
+/** @category Validation */
 export interface ScheduleValidation {
   readonly errors: readonly ScheduleError[];
   readonly violations: readonly ScheduleViolation[];
@@ -141,12 +161,16 @@ export interface ScheduleValidation {
 
 /**
  * Summary of validation items grouped by their source instruction.
- * Use `summarizeValidation()` to create these from a ScheduleValidation.
+ * Use `summarizeValidation()` to create these from a `ScheduleValidation`.
+ *
+ * @category Validation
  */
 export interface ValidationSummary {
-  readonly groupKey: GroupKey;
+  /** Deterministic group key derived from rule/coverage structure. */
+  readonly groupKey: string;
   readonly type: "coverage" | "rule";
-  readonly description: string;
+  /** Human-readable title for this group (e.g., "3x nurse during day_ward"). */
+  readonly title: string;
   readonly days: readonly string[];
   readonly status: "passed" | "partial" | "failed";
   readonly passedCount: number;
@@ -162,15 +186,16 @@ export interface TrackedConstraint {
   readonly id: string;
   readonly type: "coverage" | "rule";
   readonly rule?: string;
+  /** Per-constraint description used to generate violation messages. */
   readonly description: string;
   readonly targetValue: number;
   readonly comparator: "<=" | ">=";
   readonly day?: string;
   readonly timeSlot?: string;
-  readonly roles?: string[];
-  readonly skills?: readonly string[];
+  readonly roleIds?: string[];
+  readonly skillIds?: readonly string[];
   readonly context: ValidationContext;
-  readonly groupKey?: GroupKey;
+  readonly group?: ValidationGroup;
 }
 
 /**