dabke 0.81.1 → 0.83.0

package/src/cpsat/rules/time-off.ts

@@ -12,6 +12,7 @@ import {
   parseTimeScope,
   resolveMembersFromScope,
   resolveActiveDaysFromScope,
+  ruleGroup,
 } from "./scope.types.js";
 
 const timeOfDaySchema = z.object({
@@ -108,6 +109,7 @@ export function createTimeOffRule(config: TimeOffConfig): CompilationRule {
 
   const entityScopeValue = parseEntityScope(parsed);
   const timeScopeValue = parseTimeScope(parsed);
+  const group = ruleGroup("time-off", "Time off", entityScopeValue, timeScopeValue);
 
   return {
     compile(builder) {
@@ -182,20 +184,22 @@ export function createTimeOffRule(config: TimeOffConfig): CompilationRule {
           if (violated) {
             reporter.reportRuleViolation({
               rule: "time-off",
-              reason: `Time-off request for ${emp.id} on ${day} could not be honored`,
+              message: `Time-off request for ${emp.id} on ${day} could not be honored`,
               context: {
                 memberIds: [emp.id],
                 days: [day],
               },
+              group,
             });
           } else {
             reporter.reportRulePassed({
               rule: "time-off",
-              description: `Time-off honored for ${emp.id} on ${day}`,
+              message: `Time-off honored for ${emp.id} on ${day}`,
               context: {
                 memberIds: [emp.id],
                 days: [day],
               },
+              group,
             });
           }
         }

package/src/cpsat/semantic-time.ts

@@ -2,7 +2,20 @@ import type { DayOfWeek, TimeOfDay } from "../types.js";
 import { toDayOfWeekUTC } from "../datetime.utils.js";
 import { parseDayString } from "./utils.js";
 import type { CoverageRequirement, Priority } from "./types.js";
-import { groupKey, type GroupKey } from "./validation.types.js";
+import { assertSafeKeySegment, type ValidationGroup } from "./validation.types.js";
+
+/** Validates and joins role/skill IDs into a key-safe segment. */
+function safeRoleOrSkills(roleIds?: readonly string[], skillIds?: readonly string[]): string {
+  if (roleIds && roleIds.length > 0) {
+    for (const r of roleIds) assertSafeKeySegment(r, "role ID");
+    return roleIds.join("/");
+  }
+  if (skillIds && skillIds.length > 0) {
+    for (const s of skillIds) assertSafeKeySegment(s, "skill ID");
+    return skillIds.join("+");
+  }
+  throw new Error("At least one role or skill is required");
+}
 
 /**
  * Base definition for a semantic time period.
@@ -25,7 +38,7 @@ export interface SemanticTimeDef {
  */
 export interface SemanticTimeVariant extends SemanticTimeDef {
   /** Restrict this entry to specific days of the week. */
-  dayOfWeek?: readonly DayOfWeek[];
+  dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]];
   /** Restrict this entry to specific dates (YYYY-MM-DD). */
   dates?: string[];
 }
@@ -44,15 +57,15 @@ interface SemanticCoverageRequirementBase<S extends string> {
   targetCount: number;
   priority?: Priority;
   /** Scope this requirement to specific days of the week */
-  dayOfWeek?: DayOfWeek[];
+  dayOfWeek?: [DayOfWeek, ...DayOfWeek[]];
   /** Scope this requirement to specific dates (YYYY-MM-DD) */
   dates?: string[];
   /**
-   * Override the auto-generated group key for validation reporting.
-   * If not provided, a key is auto-generated from the semantic time name,
+   * Override the auto-generated group for validation reporting.
+   * If not provided, a group is auto-generated from the semantic time name,
    * role/skills, and target count.
    */
-  groupKey?: GroupKey;
+  group?: ValidationGroup;
 }
 
 /**
@@ -62,14 +75,14 @@ interface RoleBasedSemanticCoverageRequirement<
   S extends string,
 > extends SemanticCoverageRequirementBase<S> {
   /**
-   * Roles that satisfy this coverage (OR logic).
+   * Role IDs that satisfy this coverage (OR logic).
    * Must have at least one role.
    */
-  roles: [string, ...string[]];
+  roleIds: [string, ...string[]];
   /**
-   * Additional skill filter (AND logic with roles).
+   * Additional skill ID filter (AND logic with roles).
    */
-  skills?: [string, ...string[]];
+  skillIds?: [string, ...string[]];
 }
 
 /**
@@ -78,12 +91,12 @@ interface RoleBasedSemanticCoverageRequirement<
 interface SkillBasedSemanticCoverageRequirement<
   S extends string,
 > extends SemanticCoverageRequirementBase<S> {
-  roles?: never;
+  roleIds?: never;
   /**
-   * Skills required (ALL required, AND logic).
+   * Skill IDs required (ALL required, AND logic).
    * Must have at least one skill.
    */
-  skills: [string, ...string[]];
+  skillIds: [string, ...string[]];
 }
 
 /**
@@ -91,14 +104,14 @@ interface SkillBasedSemanticCoverageRequirement<
  * Type-safe: S is constrained to known semantic time names.
  *
  * This is a discriminated union enforcing at compile time that at least
- * one of `roles` or `skills` must be provided.
+ * one of `roleIds` or `skillIds` must be provided.
  *
  * @remarks
  * **Fields:**
  * - `semanticTime` (required) — name of a defined semantic time
  * - `targetCount` (required) — how many people are needed
- * - `roles` — roles that satisfy this (OR logic); at least one of `roles`/`skills` required
- * - `skills` — skills required (AND logic); at least one of `roles`/`skills` required
+ * - `roleIds` — role IDs that satisfy this (OR logic); at least one of `roleIds`/`skillIds` required
+ * - `skillIds` — skill IDs required (AND logic); at least one of `roleIds`/`skillIds` required
  * - `dayOfWeek` — scope to specific days of the week (e.g. `["monday", "tuesday"]`)
  * - `dates` — scope to specific dates (`"YYYY-MM-DD"` strings)
  * - `priority` — `"MANDATORY"` | `"HIGH"` | `"MEDIUM"` | `"LOW"`
@@ -109,15 +122,15 @@ interface SkillBasedSemanticCoverageRequirement<
  *
  * @example Weekday vs weekend (mutually exclusive dayOfWeek)
  * ```typescript
- * { semanticTime: "day_shift", roles: ["nurse"], targetCount: 3,
+ * { semanticTime: "day_shift", roleIds: ["nurse"], targetCount: 3,
  *   dayOfWeek: ["monday", "tuesday", "wednesday", "thursday", "friday"] },
- * { semanticTime: "day_shift", roles: ["nurse"], targetCount: 2,
+ * { semanticTime: "day_shift", roleIds: ["nurse"], targetCount: 2,
  *   dayOfWeek: ["saturday", "sunday"] },
  * ```
  *
  * @example Skill-based coverage (any role with the skill)
  * ```typescript
- * { semanticTime: "night_shift", skills: ["charge_nurse"], targetCount: 1 },
+ * { semanticTime: "night_shift", skillIds: ["charge_nurse"], targetCount: 1 },
  * ```
  */
 export type SemanticCoverageRequirement<S extends string> =
@@ -134,11 +147,11 @@ interface ConcreteCoverageRequirementBase {
   targetCount: number;
   priority?: Priority;
   /**
-   * Override the auto-generated group key for validation reporting.
-   * If not provided, a key is auto-generated from the day, time range,
+   * Override the auto-generated group for validation reporting.
+   * If not provided, a group is auto-generated from the day, time range,
    * role/skills, and target count.
    */
-  groupKey?: GroupKey;
+  group?: ValidationGroup;
 }
 
 /**
@@ -146,26 +159,26 @@ interface ConcreteCoverageRequirementBase {
  */
 interface RoleBasedConcreteCoverageRequirement extends ConcreteCoverageRequirementBase {
   /**
-   * Roles that satisfy this coverage (OR logic).
+   * Role IDs that satisfy this coverage (OR logic).
    * Must have at least one role.
    */
-  roles: [string, ...string[]];
+  roleIds: [string, ...string[]];
   /**
-   * Additional skill filter (AND logic with roles).
+   * Additional skill ID filter (AND logic with roles).
    */
-  skills?: [string, ...string[]];
+  skillIds?: [string, ...string[]];
 }
 
 /**
  * Concrete coverage requiring specific skills only (any role).
  */
 interface SkillBasedConcreteCoverageRequirement extends ConcreteCoverageRequirementBase {
-  roles?: never;
+  roleIds?: never;
   /**
-   * Skills required (ALL required, AND logic).
+   * Skill IDs required (ALL required, AND logic).
    * Must have at least one skill.
    */
-  skills: [string, ...string[]];
+  skillIds: [string, ...string[]];
 }
 
 /**
@@ -173,7 +186,7 @@ interface SkillBasedConcreteCoverageRequirement extends ConcreteCoverageRequirem
  * Used for one-off requirements that don't fit a semantic time.
  *
  * This is a discriminated union enforcing at compile time that at least
- * one of `roles` or `skills` must be provided.
+ * one of `roleIds` or `skillIds` must be provided.
  */
 export type ConcreteCoverageRequirement =
   | RoleBasedConcreteCoverageRequirement
@@ -199,12 +212,14 @@ export type ConcreteCoverageRequirement =
  *   { count: 2, dates: ["2025-12-24"] },
  * )
  * ```
+ *
+ * @category Coverage
  */
 export interface CoverageVariant {
   /** Number of people needed. */
   count: number;
   /** Restrict this variant to specific days of the week. */
-  dayOfWeek?: readonly DayOfWeek[];
+  dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]];
   /** Restrict this variant to specific dates (YYYY-MM-DD). */
   dates?: string[];
   /** Defaults to `"MANDATORY"`. */
@@ -218,7 +233,7 @@ interface VariantCoverageRequirementBase<S extends string> {
   semanticTime: S;
   /** At least one variant is required. At most one may be unscoped (the default). */
   variants: [CoverageVariant, ...CoverageVariant[]];
-  groupKey?: GroupKey;
+  group?: ValidationGroup;
 }
 
 /**
@@ -227,8 +242,8 @@ interface VariantCoverageRequirementBase<S extends string> {
 interface RoleBasedVariantCoverageRequirement<
   S extends string,
 > extends VariantCoverageRequirementBase<S> {
-  roles: [string, ...string[]];
-  skills?: [string, ...string[]];
+  roleIds: [string, ...string[]];
+  skillIds?: [string, ...string[]];
 }
 
 /**
@@ -237,8 +252,8 @@ interface RoleBasedVariantCoverageRequirement<
 interface SkillBasedVariantCoverageRequirement<
   S extends string,
 > extends VariantCoverageRequirementBase<S> {
-  roles?: never;
-  skills: [string, ...string[]];
+  roleIds?: never;
+  skillIds: [string, ...string[]];
 }
 
 /**
@@ -254,7 +269,7 @@ interface SkillBasedVariantCoverageRequirement<
  * @example Decrease from default on a specific date
  * ```typescript
  * {
- *   semanticTime: "peak_hours", roles: ["agent"],
+ *   semanticTime: "peak_hours", roleIds: ["agent"],
  *   variants: [
  *     { count: 4 },                              // default
  *     { count: 2, dates: ["2025-12-24"] },        // Christmas Eve
@@ -341,10 +356,10 @@ export interface SemanticTimeContext<S extends string> {
  * });
  *
  * const coverage = times.coverage([
- *   { semanticTime: "day_shift", roles: ["nurse"], targetCount: 3 },
- *   { semanticTime: "morning_round", skills: ["charge_nurse"], targetCount: 1, priority: "MANDATORY" },
+ *   { semanticTime: "day_shift", roleIds: ["nurse"], targetCount: 3 },
+ *   { semanticTime: "morning_round", skillIds: ["charge_nurse"], targetCount: 1, priority: "MANDATORY" },
  *   // Type error: "evening" is not a defined semantic time
- *   // { semanticTime: "evening", roles: ["nurse"], targetCount: 2 },
+ *   // { semanticTime: "evening", roleIds: ["nurse"], targetCount: 2 },
  * ]);
  * ```
  *
@@ -361,9 +376,9 @@ export interface SemanticTimeContext<S extends string> {
  * @example Mixed semantic and concrete coverage
  * ```typescript
  * const coverage = times.coverage([
- *   { semanticTime: "day_shift", roles: ["nurse"], targetCount: 3 },
+ *   { semanticTime: "day_shift", roleIds: ["nurse"], targetCount: 3 },
  *   // One-off event requiring extra staff
- *   { day: "2026-01-14", startTime: { hours: 8 }, endTime: { hours: 12 }, roles: ["nurse"], targetCount: 5 },
+ *   { day: "2026-01-14", startTime: { hours: 8 }, endTime: { hours: 12 }, roleIds: ["nurse"], targetCount: 5 },
  * ]);
  * ```
  */
@@ -393,25 +408,25 @@ function buildCoverageRequirement(
   day: string,
   startTime: TimeOfDay,
   endTime: TimeOfDay,
-  roles: [string, ...string[]] | undefined,
-  skills: [string, ...string[]] | undefined,
+  roleIds: [string, ...string[]] | undefined,
+  skillIds: [string, ...string[]] | undefined,
   targetCount: number,
   priority: Priority,
-  gKey: GroupKey,
+  group: ValidationGroup,
 ): CoverageRequirement {
-  const base = { day, startTime, endTime, targetCount, priority, groupKey: gKey };
+  const base = { day, startTime, endTime, targetCount, priority, group };
 
-  if (roles && roles.length > 0) {
+  if (roleIds && roleIds.length > 0) {
     // Role-based (with optional skills)
-    return skills && skills.length > 0 ? { ...base, roles, skills } : { ...base, roles };
-  } else if (skills && skills.length > 0) {
+    return skillIds && skillIds.length > 0 ? { ...base, roleIds, skillIds } : { ...base, roleIds };
+  } else if (skillIds && skillIds.length > 0) {
     // Skill-only
-    return { ...base, skills };
+    return { ...base, skillIds };
   }
 
   // This shouldn't happen if input types are correct, but handle gracefully
   throw new Error(
-    `Coverage requirement for day "${day}" must have at least one of roles or skills`,
+    `Coverage requirement for day "${day}" must have at least one of roleIds or skillIds`,
   );
 }
 
@@ -431,17 +446,17 @@ function resolveSemanticCoverage<S extends string>(
     if (isConcreteCoverage(req)) {
       // Concrete requirement - pass through if day is in horizon
       if (daySet.has(req.day)) {
-        const autoGroupKey = generateConcreteGroupKey(req);
+        const defaultGroup = concreteCoverageGroup(req);
         result.push(
           buildCoverageRequirement(
             req.day,
             req.startTime,
             req.endTime,
-            req.roles,
-            req.skills,
+            req.roleIds,
+            req.skillIds,
             req.targetCount,
             req.priority ?? "MANDATORY",
-            req.groupKey ?? autoGroupKey,
+            req.group ?? defaultGroup,
           ),
         );
       }
@@ -452,7 +467,7 @@ function resolveSemanticCoverage<S extends string>(
         throw new Error(`Unknown semantic time: ${req.semanticTime}`);
       }
 
-      const autoGroupKey = generateVariantGroupKey(req);
+      const defaultGroup = variantCoverageGroup(req);
 
       for (const day of days) {
         const resolved = resolveTimeForDay(entry, day);
@@ -466,11 +481,11 @@ function resolveSemanticCoverage<S extends string>(
             day,
             resolved.startTime,
             resolved.endTime,
-            req.roles,
-            req.skills,
+            req.roleIds,
+            req.skillIds,
             variant.count,
             variant.priority ?? "MANDATORY",
-            req.groupKey ?? autoGroupKey,
+            req.group ?? defaultGroup,
           ),
         );
       }
@@ -481,7 +496,7 @@ function resolveSemanticCoverage<S extends string>(
         throw new Error(`Unknown semantic time: ${req.semanticTime}`);
       }
 
-      const autoGroupKey = generateSemanticGroupKey(req);
+      const defaultGroup = semanticCoverageGroup(req);
       const applicableDays = filterDays(days, req.dayOfWeek, req.dates);
 
       for (const day of applicableDays) {
@@ -492,11 +507,11 @@ function resolveSemanticCoverage<S extends string>(
               day,
               resolved.startTime,
               resolved.endTime,
-              req.roles,
-              req.skills,
+              req.roleIds,
+              req.skillIds,
               req.targetCount,
               req.priority ?? "MANDATORY",
-              req.groupKey ?? autoGroupKey,
+              req.group ?? defaultGroup,
             ),
           );
         }
@@ -507,33 +522,42 @@ function resolveSemanticCoverage<S extends string>(
   return result;
 }
 
-/**
- * Generates a human-readable group key for a semantic coverage requirement.
- * Format: "{count}x {role/skills} during {semanticTime}" with optional scope
- */
-function generateSemanticGroupKey<S extends string>(req: SemanticCoverageRequirement<S>): GroupKey {
-  const roleOrSkills = req.roles?.join("/") ?? req.skills?.join("+") ?? "staff";
-  const base = `${req.targetCount}x ${roleOrSkills} during ${req.semanticTime}`;
+/** Generates deterministic group for a semantic coverage requirement. */
+function semanticCoverageGroup<S extends string>(
+  req: SemanticCoverageRequirement<S>,
+): ValidationGroup {
+  assertSafeKeySegment(req.semanticTime, "semantic time name");
+  const roleOrSkills = safeRoleOrSkills(req.roleIds, req.skillIds);
+  const title = `${req.targetCount}x ${roleOrSkills} during ${req.semanticTime}`;
 
-  // Add scope qualifier if scoped to specific days
+  let scopeSuffix = "";
   if (req.dayOfWeek && req.dayOfWeek.length > 0 && req.dayOfWeek.length < 7) {
-    return groupKey(`${base} (${formatDaysScope(req.dayOfWeek)})`);
-  }
-  if (req.dates && req.dates.length > 0) {
-    return groupKey(`${base} (specific dates)`);
+    scopeSuffix = `:dow:${req.dayOfWeek.toSorted().join(",")}`;
+  } else if (req.dates && req.dates.length > 0) {
+    scopeSuffix = `:dates:${req.dates.toSorted().join(",")}`;
   }
 
-  return groupKey(base);
+  const key = `coverage:${req.semanticTime}:${roleOrSkills}:${req.targetCount}${scopeSuffix}`;
+  const titleSuffix =
+    scopeSuffix && req.dayOfWeek
+      ? ` (${formatDaysScope(req.dayOfWeek)})`
+      : scopeSuffix && req.dates
+        ? " (specific dates)"
+        : "";
+
+  return { key, title: `${title}${titleSuffix}` };
 }
 
-/**
- * Generates a human-readable group key for a variant coverage requirement.
- * Format: "{role/skills} during {semanticTime}" — shared across all days since
- * the count varies per variant.
- */
-function generateVariantGroupKey<S extends string>(req: VariantCoverageRequirement<S>): GroupKey {
-  const roleOrSkills = req.roles?.join("/") ?? req.skills?.join("+") ?? "staff";
-  return groupKey(`${roleOrSkills} during ${req.semanticTime}`);
+/** Generates deterministic group for a variant coverage requirement. */
+function variantCoverageGroup<S extends string>(
+  req: VariantCoverageRequirement<S>,
+): ValidationGroup {
+  assertSafeKeySegment(req.semanticTime, "semantic time name");
+  const roleOrSkills = safeRoleOrSkills(req.roleIds, req.skillIds);
+  return {
+    key: `coverage-variant:${req.semanticTime}:${roleOrSkills}`,
+    title: `${roleOrSkills} during ${req.semanticTime}`,
+  };
 }
 
 /**
@@ -569,14 +593,14 @@ function resolveVariantForDay(
   return dateMatch ?? dowMatch ?? defaultMatch;
 }
 
-/**
- * Generates a human-readable group key for a concrete coverage requirement.
- * Format: "{count}x {role/skills} on {day} {time}"
- */
-function generateConcreteGroupKey(req: ConcreteCoverageRequirement): GroupKey {
-  const roleOrSkills = req.roles?.join("/") ?? req.skills?.join("+") ?? "staff";
+/** Generates deterministic group for a concrete coverage requirement. */
+function concreteCoverageGroup(req: ConcreteCoverageRequirement): ValidationGroup {
+  const roleOrSkills = safeRoleOrSkills(req.roleIds, req.skillIds);
   const timeRange = `${formatTime(req.startTime)}-${formatTime(req.endTime)}`;
-  return groupKey(`${req.targetCount}x ${roleOrSkills} on ${req.day} ${timeRange}`);
+  return {
+    key: `coverage-concrete:${req.day}:${roleOrSkills}:${req.targetCount}:${timeRange}`,
+    title: `${req.targetCount}x ${roleOrSkills} on ${req.day} ${timeRange}`,
+  };
 }
 
 /**

package/src/cpsat/types.ts

@@ -1,9 +1,11 @@
 import type { TimeOfDay, DayOfWeek } from "../types.js";
 import type { SolverRequest, SolverTerm } from "../client.types.js";
-import type { GroupKey } from "./validation.types.js";
+import type { ValidationGroup } from "./validation.types.js";
 
 /**
  * Pay per hour in the caller's smallest currency unit (e.g., pence, cents).
+ *
+ * @category Supporting Types
  */
 export interface HourlyPay {
   /** Pay per hour in smallest currency unit. */
@@ -19,6 +21,8 @@ export interface HourlyPay {
  *
  * Note: overtime multiplier rules apply only to hourly members.
  * Overtime surcharge rules apply to all members regardless of pay type.
+ *
+ * @category Supporting Types
  */
 export interface SalariedPay {
   /** Annual salary in smallest currency unit. */
@@ -32,6 +36,8 @@ export interface SalariedPay {
  *
  * - `"LOW"`, `"MEDIUM"`, `"HIGH"`: soft constraints with increasing penalty for violations
  * - `"MANDATORY"`: hard constraint; the solver will not produce a solution that violates it
+ *
+ * @category Supporting Types
  */
 export type Priority = "LOW" | "MEDIUM" | "HIGH" | "MANDATORY";
 
@@ -40,14 +46,16 @@ export type Priority = "LOW" | "MEDIUM" | "HIGH" | "MANDATORY";
  *
  * Members are assigned to shift patterns by the solver based on
  * coverage requirements, rules, and constraints.
+ *
+ * @category Supporting Types
  */
 export interface SchedulingMember {
   /** Unique identifier for this member. Must not contain colons. */
   id: string;
-  /** Roles this member can fill (e.g. "nurse", "doctor"). */
-  roles: string[];
-  /** Skills this member has (e.g. "charge_nurse", "forklift"). */
-  skills?: string[];
+  /** Role IDs this member can fill (e.g. "nurse", "doctor"). */
+  roleIds: string[];
+  /** Skill IDs this member has (e.g. "charge_nurse", "forklift"). */
+  skillIds?: string[];
   /** Base pay. Required when cost rules are used. */
   pay?: HourlyPay | SalariedPay;
 }
@@ -67,9 +75,11 @@ export interface SchedulingMember {
  * @example
  * // Role-restricted shifts
  * const patterns: ShiftPattern[] = [
- *   { id: "ward_day", startTime: { hours: 7 }, endTime: { hours: 15 }, roles: ["nurse", "doctor"] },
- *   { id: "reception", startTime: { hours: 8 }, endTime: { hours: 16 }, roles: ["admin"] },
+ *   { id: "ward_day", startTime: { hours: 7 }, endTime: { hours: 15 }, roleIds: ["nurse", "doctor"] },
+ *   { id: "reception", startTime: { hours: 8 }, endTime: { hours: 16 }, roleIds: ["admin"] },
  * ];
+ *
+ * @category Supporting Types
  */
 export interface ShiftPattern {
   /**
@@ -79,7 +89,7 @@ export interface ShiftPattern {
   id: string;
 
   /**
-   * Restricts who can be assigned to this shift based on their roles.
+   * Restricts who can be assigned to this shift based on their role IDs.
    *
    * - If omitted: anyone can work this shift
    * - If provided: only team members whose roles overlap with this list can be assigned
@@ -88,7 +98,7 @@ export interface ShiftPattern {
    * Use it when different roles have different schedules (e.g., kitchen staff starts
    * earlier than floor staff).
    */
-  roles?: [string, ...string[]];
+  roleIds?: [string, ...string[]];
 
   /**
    * Restricts which days of the week this shift pattern can be used.
@@ -105,7 +115,7 @@ export interface ShiftPattern {
    * { id: "full_shift", startTime: t(9), endTime: t(18), dayOfWeek: ["monday", "tuesday", "wednesday", "thursday", "friday"] }
    * ```
    */
-  dayOfWeek?: DayOfWeek[];
+  dayOfWeek?: readonly [DayOfWeek, ...DayOfWeek[]];
 
   /**
    * Physical location where this shift takes place.
@@ -133,13 +143,13 @@ interface CoverageRequirementBase extends TimeInterval {
   targetCount: number;
   priority: Priority;
   /**
-   * Groups this requirement with others sharing the same key for validation reporting.
-   * When provided, all coverage constraints generated from this requirement will
-   * share the same groupKey, enabling meaningful aggregation in reports.
+   * Groups this requirement with others for validation reporting.
+   * All coverage constraints generated from this requirement will share the
+   * same group, enabling meaningful aggregation in reports.
    *
-   * If not provided, an auto-generated key will be used based on the coverage parameters.
+   * If not provided, an auto-generated group will be used based on the coverage parameters.
    */
-  groupKey?: GroupKey;
+  group?: ValidationGroup;
 }
 
 /**
@@ -149,16 +159,16 @@ interface CoverageRequirementBase extends TimeInterval {
  */
 interface RoleBasedCoverageRequirement extends CoverageRequirementBase {
   /**
-   * Roles that satisfy this coverage (OR logic).
+   * Role IDs that satisfy this coverage (OR logic).
    * A person matches if they have ANY of these roles.
    * Must have at least one role.
    */
-  roles: [string, ...string[]];
+  roleIds: [string, ...string[]];
   /**
-   * Additional skill filter (AND logic with roles).
+   * Additional skill ID filter (AND logic with roles).
    * If provided, team members must have ALL specified skills in addition to matching a role.
    */
-  skills?: [string, ...string[]];
+  skillIds?: [string, ...string[]];
 }
 
 /**
@@ -169,19 +179,19 @@ interface SkillBasedCoverageRequirement extends CoverageRequirementBase {
   /**
    * Must not be present for skill-based coverage.
    */
-  roles?: never;
+  roleIds?: never;
   /**
-   * Skills required to satisfy this coverage (ALL required, AND logic).
+   * Skill IDs required to satisfy this coverage (ALL required, AND logic).
    * Must have at least one skill.
    */
-  skills: [string, ...string[]];
+  skillIds: [string, ...string[]];
 }
 
 /**
  * Defines staffing needs for a specific time period.
  *
  * This is a discriminated union that enforces at compile time that at least
- * one of `roles` or `skills` must be provided:
+ * one of `roleIds` or `skillIds` must be provided:
  *
  * - Role-based: `{ roles: ["waiter"], ... }` - anyone with ANY of these roles (OR logic)
  * - Role + skill: `{ roles: ["waiter"], skills: ["senior"], ... }` - role AND skills
@@ -189,19 +199,19 @@ interface SkillBasedCoverageRequirement extends CoverageRequirementBase {
  *
  * @example
  * // Need 2 waiters during lunch (role-based)
- * { day: "2024-01-01", startTime: { hours: 11 }, endTime: { hours: 14 }, roles: ["waiter"], targetCount: 2, priority: "MANDATORY" }
+ * { day: "2024-01-01", startTime: { hours: 11 }, endTime: { hours: 14 }, roleIds: ["waiter"], targetCount: 2, priority: "MANDATORY" }
  *
  * @example
  * // Need 1 manager OR supervisor during service (OR logic on roles)
- * { day: "2024-01-01", startTime: { hours: 11 }, endTime: { hours: 22 }, roles: ["manager", "supervisor"], targetCount: 1, priority: "MANDATORY" }
+ * { day: "2024-01-01", startTime: { hours: 11 }, endTime: { hours: 22 }, roleIds: ["manager", "supervisor"], targetCount: 1, priority: "MANDATORY" }
  *
  * @example
  * // Need 1 keyholder for opening (skill-only, any role)
- * { day: "2024-01-01", startTime: { hours: 6 }, endTime: { hours: 8 }, skills: ["keyholder"], targetCount: 1, priority: "MANDATORY" }
+ * { day: "2024-01-01", startTime: { hours: 6 }, endTime: { hours: 8 }, skillIds: ["keyholder"], targetCount: 1, priority: "MANDATORY" }
  *
  * @example
  * // Need 1 senior waiter for training shift (role + skill filter)
- * { day: "2024-01-01", startTime: { hours: 9 }, endTime: { hours: 17 }, roles: ["waiter"], skills: ["senior"], targetCount: 1, priority: "HIGH" }
+ * { day: "2024-01-01", startTime: { hours: 9 }, endTime: { hours: 17 }, roleIds: ["waiter"], skillIds: ["senior"], targetCount: 1, priority: "HIGH" }
  */
 export type CoverageRequirement = RoleBasedCoverageRequirement | SkillBasedCoverageRequirement;