dabke 0.83.0 → 0.84.0

package/src/cpsat/response.ts

@@ -1,6 +1,6 @@
 import type { SolverResponse } from "../client.types.js";
 import type { ShiftPattern } from "./types.js";
-import type { TimeOfDay } from "../types.js";
+import { isDateString, type DateString, type TimeOfDay } from "../types.js";
 
 /**
  * A raw assignment from the solver: which member works which shift on which day.
@@ -12,8 +12,10 @@ export interface ShiftAssignment {
   memberId: string;
   /** The shift pattern this member is assigned to. */
   shiftPatternId: string;
+  /** The concrete role this member is filling for the assignment. */
+  roleId?: string;
   /** The date of the assignment (YYYY-MM-DD). */
-  day: string;
+  day: DateString;
 }
 
 /**
@@ -24,8 +26,10 @@ export interface ShiftAssignment {
 export interface ResolvedShiftAssignment {
   /** The assigned member's ID. */
   memberId: string;
+  /** The concrete role this member is filling for the assignment. */
+  roleId?: string;
   /** The date of the assignment (YYYY-MM-DD). */
-  day: string;
+  day: DateString;
   /** When the shift starts. */
   startTime: TimeOfDay;
   /** When the shift ends. */
@@ -51,12 +55,20 @@ export interface SolverResult {
 /**
  * Extracts shift assignments from solver response.
  *
- * Parses variable names matching the pattern `assign:${memberId}:${patternId}:${day}`
- * and returns assignments where the variable value is 1 (true).
+ * Parses role-specific variable names matching the pattern
+ * `assign_role:${memberId}:${patternId}:${roleId}:${day}` and aggregate
+ * assignment variable names matching `assign:${memberId}:${patternId}:${day}`.
  *
  * @remarks
- * IDs are validated by ModelBuilder to not contain colons,
- * ensuring unambiguous parsing.
+ * The model uses aggregate assignment variables as the canonical shift presence
+ * literals for intervals, objectives, shift-level rules, and skill-only coverage.
+ * Role-specific variables are emitted when the solver also chooses a concrete
+ * role for that shift. When both variable shapes exist for the same member,
+ * pattern, and day, the role-specific assignment is returned so callers can see
+ * the selected role without receiving a duplicate aggregate assignment.
+ *
+ * IDs are validated by ModelBuilder to not contain colons, ensuring unambiguous
+ * parsing.
  *
  * @param response - The solver response containing variable values
  * @returns Parsed schedule result with assignments
@@ -85,22 +97,49 @@ export function parseSolverResponse(response: SolverResponse): SolverResult {
     };
   }
 
-  const assignments: ShiftAssignment[] = [];
+  const roleAssignments = new Map<string, ShiftAssignment>();
+  const aggregateAssignments = new Map<string, ShiftAssignment>();
 
   for (const [varName, value] of Object.entries(response.values ?? {})) {
     if (value !== 1) continue;
+
+    if (varName.startsWith("assign_role:")) {
+      const parts = varName.split(":");
+      if (parts.length !== 5) continue;
+
+      const [, memberId, shiftPatternId, roleId, day] = parts;
+      if (!memberId || !shiftPatternId || !roleId || !day) continue;
+      if (!isDateString(day)) continue;
+
+      roleAssignments.set(assignmentKey(memberId, shiftPatternId, day), {
+        memberId,
+        shiftPatternId,
+        roleId,
+        day,
+      });
+      continue;
+    }
+
     if (!varName.startsWith("assign:")) continue;
 
-    // Pattern: assign:${memberId}:${patternId}:${day}
-    // IDs are validated to not contain colons, so splitting is unambiguous.
     const parts = varName.split(":");
     if (parts.length !== 4) continue;
-
     const [, memberId, shiftPatternId, day] = parts;
     if (!memberId || !shiftPatternId || !day) continue;
-    if (!/^\d{4}-\d{2}-\d{2}$/.test(day)) continue;
+    if (!isDateString(day)) continue;
+
+    aggregateAssignments.set(assignmentKey(memberId, shiftPatternId, day), {
+      memberId,
+      shiftPatternId,
+      day,
+    });
+  }
 
-    assignments.push({ memberId, shiftPatternId, day });
+  const assignments = [...roleAssignments.values()];
+  for (const [key, assignment] of aggregateAssignments) {
+    if (!roleAssignments.has(key)) {
+      assignments.push(assignment);
+    }
   }
 
   return {
@@ -142,6 +181,7 @@ export function resolveAssignments(
 
       return {
         memberId: a.memberId,
+        ...(a.roleId ? { roleId: a.roleId } : {}),
         day: a.day,
         startTime: pattern.startTime,
         endTime: pattern.endTime,
@@ -149,3 +189,7 @@ export function resolveAssignments(
     })
     .filter((a): a is ResolvedShiftAssignment => a !== null);
 }
+
+function assignmentKey(memberId: string, shiftPatternId: string, day: DateString): string {
+  return `${memberId}:${shiftPatternId}:${day}`;
+}

package/src/cpsat/rule-descriptor.ts

@@ -0,0 +1,311 @@
+/**
+ * Rule descriptor contracts for CP-SAT compilation.
+ *
+ * @remarks
+ * Rules compile into declarative artifacts instead of mutating the solver
+ * builder directly. This keeps validation handling and backend lowering
+ * centralized. The user-facing feedback unit is the rule or validation group,
+ * not an individual solver constraint.
+ *
+ * @packageDocumentation
+ */
+
+import type { z } from "zod";
+import type { DateString, DayOfWeek, SchedulingDay, TimeOfDay } from "../types.js";
+import type { ModelBuilder } from "./model-builder.js";
+import type { ResolvedShiftAssignment, ShiftAssignment } from "./response.js";
+import type { SchedulingMember, ShiftPattern, Term } from "./types.js";
+import type { ValidationContext, ValidationGroup } from "./validation.types.js";
+import type { ValidationReporter } from "./validation-reporter.js";
+
+export type RuleMode =
+  | "hard-constraint"
+  | "soft-constraint"
+  | "objective"
+  | "coverage-exclusion"
+  | "pre-solve-feedback"
+  | "post-solve-feedback"
+  | "cost"
+  | "variable";
+
+/**
+ * Inputs available while compiling a rule descriptor.
+ *
+ * @remarks
+ * Descriptor compilation happens before the model builder applies artifacts, so
+ * rules receive normalized scheduling inputs and return declarative artifacts
+ * instead of mutating the builder directly.
+ *
+ * @category Rules
+ */
+export interface RuleCompileContext {
+  readonly members: readonly SchedulingMember[];
+  readonly shiftPatterns: readonly ShiftPattern[];
+  readonly days: readonly SchedulingDay[];
+  readonly weekStartsOn: DayOfWeek;
+  readonly coverageBucketMinutes?: number;
+}
+
+export type RulePreSolveFeedbackContext = RuleCompileContext;
+export type RulePostSolveFeedbackContext = RuleCompileContext;
+export type CostCalculationContext = RuleCompileContext;
+
+export type PreSolveFeedbackFn = (
+  ctx: RulePreSolveFeedbackContext,
+  reporter: ValidationReporter,
+) => void;
+
+export type PostSolveFeedbackFn = (
+  assignments: readonly ResolvedShiftAssignment[],
+  reporter: ValidationReporter,
+  ctx: RulePostSolveFeedbackContext,
+) => void;
+
+/**
+ * Structured opt-out categories for artifact-level validation reporting.
+ *
+ * @category Rules
+ */
+export type ValidationSkipCategory = "scaffolding" | "no-meaningful-feedback";
+
+/**
+ * Validation strategy that reports a hard constraint into the validation pipeline.
+ *
+ * @category Rules
+ */
+export interface ReportHardConstraintValidationStrategy {
+  readonly strategy: "report";
+  readonly id: string;
+}
+
+/**
+ * Validation strategy that reports a soft constraint into the validation pipeline.
+ *
+ * @remarks
+ * Soft constraints report using their artifact `constraintId`.
+ *
+ * @category Rules
+ */
+export interface ReportSoftConstraintValidationStrategy {
+  readonly strategy: "report";
+}
+
+/**
+ * Validation strategy that explicitly skips validation reporting for an artifact.
+ *
+ * @category Rules
+ */
+export interface SkipValidationStrategy {
+  readonly strategy: "skip";
+  readonly category: ValidationSkipCategory;
+  readonly rationale: string;
+}
+
+/**
+ * Validation strategy attached to hard constraints.
+ *
+ * @category Rules
+ */
+export type HardConstraintValidationStrategy =
+  | ReportHardConstraintValidationStrategy
+  | SkipValidationStrategy;
+
+/**
+ * Validation strategy attached to soft constraints.
+ *
+ * @category Rules
+ */
+export type SoftConstraintValidationStrategy =
+  | ReportSoftConstraintValidationStrategy
+  | SkipValidationStrategy;
+
+/**
+ * Validation strategy attached to objective artifacts.
+ *
+ * @category Rules
+ */
+export type ObjectiveValidationStrategy = SkipValidationStrategy;
+
+/**
+ * Validation strategy attached to cost artifacts.
+ *
+ * @category Rules
+ */
+export type CostValidationStrategy = SkipValidationStrategy;
+
+/**
+ * A compiled hard constraint emitted by a rule descriptor.
+ *
+ * @remarks
+ * Hard constraints are still implementation details. End-user feedback should
+ * normally be summarized at the rule or validation-group level. Artifact rule
+ * identity is inherited from the containing `CompiledRule`. Solver-stage
+ * reporting uses artifact-level validation strategies. Pre-solve feedback
+ * should be emitted via dedicated feedback artifacts.
+ *
+ * @category Rules
+ */
+export interface HardConstraintArtifact {
+  readonly kind: "hard-constraint";
+  readonly group?: ValidationGroup;
+  readonly validation: HardConstraintValidationStrategy;
+  readonly description: string;
+  readonly context: ValidationContext;
+  readonly terms: readonly Term[];
+  readonly comparator: "<=" | ">=" | "==";
+  readonly targetValue: number;
+}
+
+export interface SoftConstraintArtifact {
+  readonly kind: "soft-constraint";
+  readonly group?: ValidationGroup;
+  readonly validation: SoftConstraintValidationStrategy;
+  readonly description: string;
+  readonly context: ValidationContext;
+  readonly terms: readonly Term[];
+  readonly comparator: "<=" | ">=";
+  readonly targetValue: number;
+  readonly penalty: number;
+  readonly constraintId: string;
+  /** Optional objective stage ID used for staged solver requests. */
+  readonly stage?: string;
+}
+
+export interface ObjectiveArtifact {
+  readonly kind: "objective";
+  readonly group?: ValidationGroup;
+  readonly terms: readonly Term[];
+  readonly validation: ObjectiveValidationStrategy;
+  /** Optional objective stage ID used for staged solver requests. */
+  readonly stage?: string;
+}
+
+export interface CoverageExclusionArtifact {
+  readonly kind: "coverage-exclusion";
+  readonly group?: ValidationGroup;
+  readonly memberId: string;
+  readonly day: DateString;
+  readonly startTime?: TimeOfDay;
+  readonly endTime?: TimeOfDay;
+}
+
+export interface PreSolveFeedbackArtifact {
+  readonly kind: "pre-solve-feedback";
+  readonly run: PreSolveFeedbackFn;
+}
+
+export interface PostSolveFeedbackArtifact {
+  readonly kind: "post-solve-feedback";
+  readonly run: PostSolveFeedbackFn;
+}
+
+export interface CostEntry {
+  readonly memberId: string;
+  readonly day: string;
+  readonly category: string;
+  readonly amount: number;
+}
+
+export interface CostContribution {
+  readonly entries: readonly CostEntry[];
+}
+
+export interface CostArtifact {
+  readonly kind: "cost";
+  readonly compileObjective?: (builder: ModelBuilder) => void;
+  readonly calculateCost?: (
+    assignments: readonly ShiftAssignment[],
+    ctx: CostCalculationContext,
+  ) => CostContribution;
+  readonly validation: CostValidationStrategy;
+}
+
+export type VariableArtifact =
+  | {
+      readonly kind: "variable";
+      readonly variable: { type: "bool"; name: string };
+    }
+  | {
+      readonly kind: "variable";
+      readonly variable: { type: "int"; name: string; min: number; max: number };
+    };
+
+export type RuleArtifact =
+  | VariableArtifact
+  | HardConstraintArtifact
+  | SoftConstraintArtifact
+  | ObjectiveArtifact
+  | CoverageExclusionArtifact
+  | PreSolveFeedbackArtifact
+  | PostSolveFeedbackArtifact
+  | CostArtifact;
+
+export interface CompiledRule {
+  readonly rule: string;
+  readonly artifacts: readonly RuleArtifact[];
+}
+
+/**
+ * A low-level CP-SAT rule descriptor.
+ *
+ * @remarks
+ * Advanced consumers can register custom descriptors via
+ * {@link createCpsatRuleRegistry}. Each descriptor owns runtime validation via
+ * its Zod schema and compiles a parsed config into declarative rule artifacts.
+ *
+ * @category Rules
+ */
+export interface RuleDescriptor<Name extends string = string, Config = unknown> {
+  readonly name: Name;
+  readonly schema: z.ZodType<Config>;
+  compile(config: Config, ctx: RuleCompileContext): CompiledRule;
+}
+
+/**
+ * Defines a typed low-level CP-SAT rule descriptor.
+ *
+ * @remarks
+ * Use this for custom rules that should participate in the same descriptor and
+ * artifact pipeline as the built-in rules.
+ *
+ * @example
+ * ```ts
+ * const debugRuleDescriptor = defineRuleDescriptor({
+ *   name: "debug",
+ *   schema: z.object({ flag: z.boolean() }),
+ *   compile(config) {
+ *     return {
+ *       rule: "debug",
+ *       artifacts: config.flag ? [] : [],
+ *     };
+ *   },
+ * });
+ * ```
+ *
+ * @category Rules
+ */
+export function defineRuleDescriptor<Name extends string, Schema extends z.ZodTypeAny>(descriptor: {
+  readonly name: Name;
+  readonly schema: Schema;
+  compile(config: z.infer<Schema>, ctx: RuleCompileContext): CompiledRule;
+}): RuleDescriptor<Name, z.infer<Schema>> {
+  return descriptor as RuleDescriptor<Name, z.infer<Schema>>;
+}
+
+/**
+ * Parses raw config through a descriptor schema, then compiles it into artifacts.
+ *
+ * @remarks
+ * Schema parsing fails loudly. This helper does not recover from invalid JSON or
+ * invalid rule config.
+ *
+ * @category Rules
+ */
+export function compileRuleDescriptor<Name extends string, Config>(
+  descriptor: RuleDescriptor<Name, Config>,
+  rawConfig: unknown,
+  ctx: RuleCompileContext,
+): CompiledRule {
+  const config = descriptor.schema.parse(rawConfig);
+  return descriptor.compile(config, ctx);
+}

package/src/cpsat/rules/artifacts.ts

@@ -0,0 +1,56 @@
+import type {
+  HardConstraintArtifact,
+  ReportHardConstraintValidationStrategy,
+  ReportSoftConstraintValidationStrategy,
+  SkipValidationStrategy,
+  SoftConstraintArtifact,
+  ValidationSkipCategory,
+  VariableArtifact,
+} from "../rule-descriptor.js";
+
+export function boolVariable(name: string): VariableArtifact {
+  return {
+    kind: "variable",
+    variable: { type: "bool", name },
+  };
+}
+
+export function intVariable(name: string, min: number, max: number): VariableArtifact {
+  return {
+    kind: "variable",
+    variable: { type: "int", name, min, max },
+  };
+}
+
+export function reportValidation(id: string): ReportHardConstraintValidationStrategy;
+export function reportValidation(): ReportSoftConstraintValidationStrategy;
+export function reportValidation(
+  id?: string,
+): ReportHardConstraintValidationStrategy | ReportSoftConstraintValidationStrategy {
+  return id ? { strategy: "report", id } : { strategy: "report" };
+}
+
+export function skipValidation(
+  category: ValidationSkipCategory,
+  rationale: string,
+): SkipValidationStrategy {
+  return { strategy: "skip", category, rationale };
+}
+
+export function hardConstraint(
+  params: Omit<HardConstraintArtifact, "kind">,
+): HardConstraintArtifact {
+  return {
+    ...params,
+    kind: "hard-constraint",
+  } satisfies HardConstraintArtifact;
+}
+
+export function softConstraint(
+  params: Omit<SoftConstraintArtifact, "kind">,
+): SoftConstraintArtifact {
+  return {
+    ...params,
+    kind: "soft-constraint",
+  } satisfies SoftConstraintArtifact;
+}

package/src/cpsat/rules/assign-together.ts

@@ -1,9 +1,12 @@
 import * as z from "zod";
-import type { CompilationRule } from "../model-builder.js";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
 import { priorityToPenalty } from "../utils.js";
 import { PrioritySchema } from "./scope.types.js";
+import { assignmentVar } from "./variables.js";
+import { boolVariable, hardConstraint, reportValidation, skipValidation } from "./artifacts.js";
+import { canAssignMemberToPattern, isPatternAvailableOnDay } from "./pattern-eligibility.js";
 
-const AssignTogetherSchema = z.object({
+export const AssignTogetherSchema = z.object({
   groupMemberIds: z
     .tuple([z.string(), z.string()])
     .rest(z.string())
@@ -14,86 +17,118 @@ const AssignTogetherSchema = z.object({
 });
 
 /**
- * Configuration for {@link createAssignTogetherRule}.
- *
- * - `groupMemberIds` (required): member IDs to assign together (at least two, must be unique)
- * - `priority` (required): how strictly the solver enforces this rule
+ * Configuration for {@link assignTogetherRuleDescriptor}.
  */
 export type AssignTogetherConfig = z.infer<typeof AssignTogetherSchema>;
 
 /**
- * Encourages or enforces that team members in the group work the same shift patterns on a day.
- * For each pair of team members in the group, ensures they are assigned to the same shifts.
+ * Low-level descriptor for the `assign-together` rule.
+ *
+ * @remarks
+ * Register this in a custom rule registry when you need the descriptor API
+ * directly instead of the high-level {@link assignTogether} helper.
  *
- * @param config - See {@link AssignTogetherConfig}
- * @example
- * ```ts
- * const rule = createAssignTogetherRule({
- *   groupMemberIds: ["alice", "bob", "charlie"],
- *   priority: "HIGH",
- * });
- * builder = new ModelBuilder({ ...config, rules: [rule] });
- * ```
+ * @category Rules
  */
-export function createAssignTogetherRule(config: AssignTogetherConfig): CompilationRule {
-  const { groupMemberIds, priority } = AssignTogetherSchema.parse(config);
+export const assignTogetherRuleDescriptor = defineRuleDescriptor({
+  name: "assign-together",
+  schema: AssignTogetherSchema,
+  compile(config, ctx) {
+    const { groupMemberIds, priority } = config;
+    const targetMembers = groupMemberIds
+      .map((id: string) => ctx.members.find((member) => member.id === id))
+      .filter((member): member is NonNullable<typeof member> => member !== undefined);
 
-  return {
-    compile(b) {
-      const targetMembers = groupMemberIds
-        .map((id) => b.members.find((m) => m.id === id))
-        .filter((m): m is NonNullable<typeof m> => m !== undefined);
+    if (targetMembers.length < 2) {
+      return { rule: "assign-together", artifacts: [] };
+    }
 
-      if (targetMembers.length < 2) return;
+    const artifacts = targetMembers.flatMap((member, index) => {
+      const next = targetMembers[index + 1];
+      if (!next) return [];
 
-      for (let i = 0; i < targetMembers.length - 1; i++) {
-        const m1 = targetMembers[i]!;
-        const m2 = targetMembers[i + 1]!;
+      return ctx.shiftPatterns.flatMap((pattern) => {
+        if (
+          !canAssignMemberToPattern(member, pattern) ||
+          !canAssignMemberToPattern(next, pattern)
+        ) {
+          return [];
+        }
 
-        for (const pattern of b.shiftPatterns) {
-          const canAssign1 = b.canAssign(m1, pattern);
-          const canAssign2 = b.canAssign(m2, pattern);
-          if (!canAssign1 || !canAssign2) continue;
+        return ctx.days.flatMap((day) => {
+          if (!isPatternAvailableOnDay(pattern, day)) return [];
 
-          for (const day of b.days) {
-            if (!b.patternAvailableOnDay(pattern, day)) continue;
-            const var1 = b.assignment(m1.id, pattern.id, day);
-            const var2 = b.assignment(m2.id, pattern.id, day);
+          const var1 = assignmentVar(member.id, pattern.id, day.iso);
+          const var2 = assignmentVar(next.id, pattern.id, day.iso);
+          const description = `${member.id} and ${next.id} stay together on ${pattern.id} for ${day.iso}`;
+          const context = { memberIds: [member.id, next.id], days: [day.iso] };
+          const constraintId = `assign-together:${member.id}:${next.id}:${pattern.id}:${day.iso}`;
 
-            if (priority === "MANDATORY") {
-              b.addLinear(
-                [
+          if (priority === "MANDATORY") {
+            return [
+              hardConstraint({
+                description,
+                context,
+                validation: reportValidation(constraintId),
+                terms: [
                   { var: var1, coeff: 1 },
                   { var: var2, coeff: -1 },
                 ],
-                "==",
-                0,
-              );
-            } else {
-              const diffVar = b.boolVar(`together_diff_${m1.id}_${m2.id}_${pattern.id}_${day}`);
-              b.addLinear(
-                [
-                  { var: diffVar, coeff: 1 },
-                  { var: var1, coeff: -1 },
-                  { var: var2, coeff: 1 },
-                ],
-                ">=",
-                0,
-              );
-              b.addLinear(
-                [
-                  { var: diffVar, coeff: 1 },
-                  { var: var1, coeff: 1 },
-                  { var: var2, coeff: -1 },
-                ],
-                ">=",
-                0,
-              );
-              b.addPenalty(diffVar, priorityToPenalty(priority));
-            }
+                comparator: "==",
+                targetValue: 0,
+              }),
+            ];
           }
-        }
-      }
-    },
-  };
-}
+
+          const diffVar = `together_diff_${member.id}_${next.id}_${pattern.id}_${day.iso}`;
+          return [
+            boolVariable(diffVar),
+            hardConstraint({
+              description: `${diffVar} captures ${var1} without ${var2}`,
+              validation: skipValidation(
+                "scaffolding",
+                "This helper variable measures pair mismatch so a soft pairing preference can be optimized without surfacing helper-level feedback.",
+              ),
+              context,
+              terms: [
+                { var: diffVar, coeff: 1 },
+                { var: var1, coeff: -1 },
+                { var: var2, coeff: 1 },
+              ],
+              comparator: ">=",
+              targetValue: 0,
+            }),
+            hardConstraint({
+              description: `${diffVar} captures ${var2} without ${var1}`,
+              validation: skipValidation(
+                "scaffolding",
+                "This helper variable measures pair mismatch symmetrically so the objective can penalize either member being assigned alone.",
+              ),
+              context,
+              terms: [
+                { var: diffVar, coeff: 1 },
+                { var: var1, coeff: 1 },
+                { var: var2, coeff: -1 },
+              ],
+              comparator: ">=",
+              targetValue: 0,
+            }),
+            {
+              kind: "objective" as const,
+              terms: [{ var: diffVar, coeff: Math.max(1, priorityToPenalty(priority) * 5) }],
+              validation: skipValidation(
+                "no-meaningful-feedback",
+                "Pairing preferences influence the objective but do not emit validation feedback.",
+              ),
+            },
+          ];
+        });
+      });
+    });
+
+    return {
+      rule: "assign-together",
+      artifacts,
+    };
+  },
+});