dabke 0.81.1 → 0.83.0

package/dist/schedule/definition.js

@@ -0,0 +1,659 @@
+/**
+ * Schedule definition, compilation, and solving.
+ *
+ * @module
+ */
+import { defineSemanticTimes } from "../cpsat/semantic-time.js";
+import { resolveDaysFromPeriod } from "../datetime.utils.js";
+import { ModelBuilder } from "../cpsat/model-builder.js";
+import { builtInCpsatRuleFactories } from "../cpsat/rules/registry.js";
+import { parseSolverResponse, resolveAssignments } from "../cpsat/response.js";
+import { calculateScheduleCost } from "../cpsat/cost.js";
+import { resolveAppliesTo } from "./rules.js";
+// ============================================================================
+// Schedule class
+// ============================================================================
+/**
+ * An immutable schedule definition.
+ *
+ * Created by {@link schedule}, composed via {@link Schedule.with},
+ * and solved via {@link Schedule.solve}.
+ *
+ * @category Schedule Definition
+ */
+export class Schedule {
+    #config;
+    /** @internal */
+    constructor(config) {
+        this.#config = config;
+    }
+    /** @internal Returns a defensive copy of the config for merging. */
+    _getConfig() {
+        return {
+            ...this.#config,
+            roleIds: [...this.#config.roleIds],
+            skillIds: [...this.#config.skillIds],
+            times: { ...this.#config.times },
+            coverage: [...this.#config.coverage],
+            shiftPatterns: [...this.#config.shiftPatterns],
+            rules: [...this.#config.rules],
+            ruleFactories: { ...this.#config.ruleFactories },
+            members: [...this.#config.members],
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Inspection
+    // --------------------------------------------------------------------------
+    /** Declared role IDs. */
+    get roleIds() {
+        return this.#config.roleIds;
+    }
+    /** Declared skill IDs. */
+    get skillIds() {
+        return this.#config.skillIds;
+    }
+    /** Names of declared semantic times. */
+    get timeNames() {
+        return Object.keys(this.#config.times);
+    }
+    /** Shift pattern IDs. */
+    get shiftPatternIds() {
+        return this.#config.shiftPatterns.map((sp) => sp.id);
+    }
+    /** Internal rule identifiers in kebab-case. */
+    get ruleNames() {
+        return this.#config.rules.map((r) => r._rule);
+    }
+    // --------------------------------------------------------------------------
+    // Composition
+    // --------------------------------------------------------------------------
+    /**
+     * Merges schedules or members onto this schedule, returning a new
+     * immutable `Schedule`. The original is untouched.
+     *
+     * Accepts any mix of `Schedule` instances and `SchedulingMember[]` arrays.
+     *
+     * Merge semantics (when merging schedules):
+     * - Roles: union (additive)
+     * - Skills: union (additive)
+     * - Times: additive; error on name collision
+     * - Coverage: additive
+     * - Shift patterns: additive; error on ID collision
+     * - Rules: additive
+     * - Members: additive; error on duplicate ID
+     *
+     * Validation runs eagerly: role/skill disjointness, coverage targets
+     * referencing declared roles/skills, member role references, etc.
+     */
+    with(...args) {
+        const merged = mergeConfig(this.#config, args);
+        return new Schedule(merged);
+    }
+    // --------------------------------------------------------------------------
+    // Solve / compile
+    // --------------------------------------------------------------------------
+    /**
+     * Compiles, validates, solves, and parses in one call.
+     *
+     * @param client - Solver client (e.g., `new HttpSolverClient(fetch, url)`)
+     * @param options - Date range and optional pinned assignments
+     */
+    async solve(client, options) {
+        const compiled = this.compile(options);
+        if (!compiled.canSolve) {
+            return {
+                status: "infeasible",
+                assignments: [],
+                validation: compiled.validation,
+            };
+        }
+        const response = await client.solve(compiled.request);
+        return buildSolveResult(response, compiled, this.#config);
+    }
+    /**
+     * Diagnostic escape hatch. Compiles the schedule without solving.
+     *
+     * @param options - Date range and optional pinned assignments
+     */
+    compile(options) {
+        if (options.pinned && options.pinned.length > 0) {
+            throw new Error("Pinned assignments are not yet supported.");
+        }
+        const modelConfig = resolveToModelConfig(this.#config, options);
+        const builder = new ModelBuilder(modelConfig);
+        const result = builder.compile();
+        return { ...result, builder };
+    }
+}
+// ============================================================================
+// schedule() factory
+// ============================================================================
+/**
+ * Create a schedule definition.
+ *
+ * Returns an immutable {@link Schedule} that can be composed via `.with()`
+ * and solved via `.solve()`.
+ *
+ * @example
+ * ```typescript
+ * const venue = schedule({
+ *   roleIds: ["waiter", "runner", "manager"],
+ *   skillIds: ["senior"],
+ *   times: {
+ *     lunch: time({ startTime: t(12), endTime: t(15) }),
+ *     dinner: time(
+ *       { startTime: t(17), endTime: t(21) },
+ *       { startTime: t(18), endTime: t(22), dayOfWeek: weekend },
+ *     ),
+ *   },
+ *   coverage: [
+ *     cover("lunch", "waiter", 2),
+ *     cover("dinner", "waiter", 4, { dayOfWeek: weekdays }),
+ *     cover("dinner", "waiter", 5, { dayOfWeek: weekend }),
+ *     cover("dinner", "manager", 1),
+ *   ],
+ *   shiftPatterns: [
+ *     shift("lunch_shift", t(11, 30), t(15)),
+ *     shift("evening", t(17), t(22)),
+ *   ],
+ *   rules: [
+ *     maxHoursPerDay(10),
+ *     maxHoursPerWeek(48),
+ *     minRestBetweenShifts(11),
+ *   ],
+ * });
+ * ```
+ *
+ * @category Schedule Definition
+ */
+export function schedule(config) {
+    const merged = buildMergedConfig(config);
+    validateConfig(merged);
+    return new Schedule(merged);
+}
+/**
+ * Create a partial schedule for composition via `.with()`.
+ *
+ * Unlike {@link schedule}, all fields are optional. Use this for
+ * schedules that layer rules, coverage, or other config onto a
+ * complete base schedule.
+ *
+ * @example
+ * ```typescript
+ * const companyPolicy = partialSchedule({
+ *   rules: [maxHoursPerWeek(40), minRestBetweenShifts(11)],
+ * });
+ *
+ * const ready = venue.with(companyPolicy, teamMembers);
+ * ```
+ *
+ * @category Schedule Definition
+ */
+export function partialSchedule(config) {
+    const merged = buildMergedConfig({
+        roleIds: [],
+        times: {},
+        coverage: [],
+        shiftPatterns: [],
+        ...config,
+    });
+    validateConfig(merged);
+    return new Schedule(merged);
+}
+// ============================================================================
+// Internal: Build merged config from user input
+// ============================================================================
+function buildMergedConfig(config) {
+    return {
+        roleIds: [...config.roleIds],
+        skillIds: [...(config.skillIds ?? [])],
+        times: { ...config.times },
+        coverage: [...config.coverage],
+        shiftPatterns: [...config.shiftPatterns],
+        rules: [...(config.rules ?? [])],
+        ruleFactories: config.ruleFactories ? { ...config.ruleFactories } : {},
+        members: [...(config.members ?? [])],
+        dayOfWeek: config.dayOfWeek,
+        weekStartsOn: config.weekStartsOn,
+    };
+}
+// ============================================================================
+// Internal: Validate merged config
+// ============================================================================
+function validateConfig(config) {
+    const roles = new Set(config.roleIds);
+    const skills = new Set(config.skillIds);
+    // Validate custom rule factories don't override built-in names
+    for (const name of Object.keys(config.ruleFactories)) {
+        if (name in builtInCpsatRuleFactories) {
+            throw new Error(`Custom rule factory "${name}" conflicts with a built-in rule. Choose a different name.`);
+        }
+    }
+    // Validate role/skill disjointness
+    for (const skill of skills) {
+        if (roles.has(skill)) {
+            throw new Error(`"${skill}" is declared as both a role and a skill. Roles and skills must be disjoint.`);
+        }
+    }
+    // Validate shift pattern role references
+    for (const sp of config.shiftPatterns) {
+        if (sp.roleIds) {
+            for (const role of sp.roleIds) {
+                if (!roles.has(role)) {
+                    throw new Error(`Shift pattern "${sp.id}" references unknown role "${role}". ` +
+                        `Declared roles: ${[...roles].join(", ")}`);
+                }
+            }
+        }
+    }
+    // Validate coverage entries
+    for (const entry of config.coverage) {
+        validateCoverageEntry(entry, roles, skills);
+    }
+    // Validate member references
+    const memberIds = new Set();
+    for (const member of config.members) {
+        if (memberIds.has(member.id)) {
+            throw new Error(`Duplicate member ID "${member.id}".`);
+        }
+        memberIds.add(member.id);
+        if (roles.has(member.id)) {
+            throw new Error(`Member ID "${member.id}" collides with a declared role name.`);
+        }
+        if (skills.has(member.id)) {
+            throw new Error(`Member ID "${member.id}" collides with a declared skill name.`);
+        }
+        for (const role of member.roleIds) {
+            if (!roles.has(role)) {
+                throw new Error(`Member "${member.id}" references unknown role "${role}". ` +
+                    `Declared roles: ${[...roles].join(", ")}`);
+            }
+        }
+        if (member.skillIds) {
+            for (const skill of member.skillIds) {
+                if (!skills.has(skill)) {
+                    throw new Error(`Member "${member.id}" references unknown skill "${skill}". ` +
+                        `Declared skills: ${[...skills].join(", ")}`);
+                }
+            }
+        }
+    }
+}
+function validateCoverageEntry(entry, roles, skills) {
+    const targets = Array.isArray(entry.target) ? entry.target : [entry.target];
+    if (Array.isArray(entry.target)) {
+        for (const target of targets) {
+            if (!roles.has(target)) {
+                throw new Error(`Coverage for "${entry.timeName}" references "${target}" in a role OR group, ` +
+                    `but it is not a declared role. Declared roles: ${[...roles].join(", ")}`);
+            }
+        }
+    }
+    else {
+        if (!roles.has(entry.target) && !skills.has(entry.target)) {
+            throw new Error(`Coverage for "${entry.timeName}" references unknown target "${entry.target}". ` +
+                `Declared roles: ${[...roles].join(", ")}. ` +
+                `Declared skills: ${[...skills].join(", ")}`);
+        }
+    }
+    if (entry.options.skillIds) {
+        for (const s of entry.options.skillIds) {
+            if (!skills.has(s)) {
+                throw new Error(`Coverage for "${entry.timeName}" uses skill filter "${s}" ` +
+                    `which is not a declared skill. Declared skills: ${[...skills].join(", ")}`);
+            }
+        }
+    }
+}
+// ============================================================================
+// Internal: Merge logic
+// ============================================================================
+function mergeConfig(base, args) {
+    const result = {
+        roleIds: [...base.roleIds],
+        skillIds: [...base.skillIds],
+        times: { ...base.times },
+        coverage: [...base.coverage],
+        shiftPatterns: [...base.shiftPatterns],
+        rules: [...base.rules],
+        ruleFactories: { ...base.ruleFactories },
+        members: [...base.members],
+        dayOfWeek: base.dayOfWeek,
+        weekStartsOn: base.weekStartsOn,
+    };
+    for (const arg of args) {
+        if (arg instanceof Schedule) {
+            mergeScheduleFragment(result, arg);
+        }
+        else if (Array.isArray(arg)) {
+            mergeMembers(result, arg);
+        }
+        else {
+            throw new Error(`Unexpected argument passed to .with(): expected Schedule or SchedulingMember[], got ${typeof arg}`);
+        }
+    }
+    // Validate the merged result
+    validateConfig(result);
+    return result;
+}
+function mergeScheduleFragment(result, s) {
+    const other = s._getConfig();
+    // dayOfWeek: error on conflict (semantics of union vs intersection are ambiguous)
+    if (other.dayOfWeek !== undefined) {
+        if (result.dayOfWeek !== undefined) {
+            const baseSet = new Set(result.dayOfWeek);
+            const same = result.dayOfWeek.length === other.dayOfWeek.length &&
+                other.dayOfWeek.every((d) => baseSet.has(d));
+            if (!same) {
+                throw new Error("Cannot merge schedules with different dayOfWeek filters. " +
+                    `Base has [${result.dayOfWeek.join(", ")}], ` +
+                    `incoming has [${other.dayOfWeek.join(", ")}].`);
+            }
+        }
+        else {
+            result.dayOfWeek = other.dayOfWeek;
+        }
+    }
+    // weekStartsOn: error on conflict (only one week boundary for weekly rules)
+    if (other.weekStartsOn !== undefined) {
+        if (result.weekStartsOn !== undefined && result.weekStartsOn !== other.weekStartsOn) {
+            throw new Error("Cannot merge schedules with different weekStartsOn values. " +
+                `Base has "${result.weekStartsOn}", incoming has "${other.weekStartsOn}".`);
+        }
+        result.weekStartsOn = other.weekStartsOn;
+    }
+    // Roles: union
+    for (const role of other.roleIds) {
+        if (!result.roleIds.includes(role)) {
+            result.roleIds.push(role);
+        }
+    }
+    // Skills: union
+    for (const skill of other.skillIds) {
+        if (!result.skillIds.includes(skill)) {
+            result.skillIds.push(skill);
+        }
+    }
+    // Times: additive, error on collision
+    for (const [name, entry] of Object.entries(other.times)) {
+        if (name in result.times) {
+            throw new Error(`Time name "${name}" already exists. Cannot merge schedules with colliding time names.`);
+        }
+        result.times[name] = entry;
+    }
+    // Coverage: additive
+    result.coverage.push(...other.coverage);
+    // Shift patterns: additive, error on ID collision
+    const existingIds = new Set(result.shiftPatterns.map((sp) => sp.id));
+    for (const sp of other.shiftPatterns) {
+        if (existingIds.has(sp.id)) {
+            throw new Error(`Shift pattern ID "${sp.id}" already exists. Cannot merge schedules with colliding shift pattern IDs.`);
+        }
+        result.shiftPatterns.push(sp);
+        existingIds.add(sp.id);
+    }
+    // Rules: additive
+    result.rules.push(...other.rules);
+    // Rule factories: merge, error on collision
+    for (const [name, factory] of Object.entries(other.ruleFactories)) {
+        if (name in result.ruleFactories && result.ruleFactories[name] !== factory) {
+            throw new Error(`Rule factory "${name}" already registered. Cannot merge schedules with colliding rule factories.`);
+        }
+        result.ruleFactories[name] = factory;
+    }
+    // Members: additive, error on duplicate ID
+    const existingMemberIds = new Set(result.members.map((m) => m.id));
+    for (const member of other.members) {
+        if (existingMemberIds.has(member.id)) {
+            throw new Error(`Duplicate member ID "${member.id}". Cannot merge schedules with colliding member IDs.`);
+        }
+        result.members.push(member);
+        existingMemberIds.add(member.id);
+    }
+}
+function mergeMembers(result, incoming) {
+    const existingIds = new Set(result.members.map((m) => m.id));
+    for (const member of incoming) {
+        if (existingIds.has(member.id)) {
+            throw new Error(`Duplicate member ID "${member.id}". Cannot merge members with colliding IDs.`);
+        }
+        result.members.push(member);
+        existingIds.add(member.id);
+    }
+}
+// ============================================================================
+// Internal: Resolve to ModelBuilderConfig
+// ============================================================================
+function resolveToModelConfig(config, options) {
+    const roles = new Set(config.roleIds);
+    const skills = new Set(config.skillIds);
+    const memberIds = new Set(config.members.map((m) => m.id));
+    // Build semantic time context
+    const semanticTimes = defineSemanticTimes(config.times);
+    // Convert coverage entries to semantic coverage requirements
+    const coverageReqs = buildCoverageRequirements(config.coverage, roles, skills);
+    // Resolve scheduling period with dayOfWeek filter
+    const schedulingPeriod = {
+        dateRange: options.dateRange,
+    };
+    const resolvedPeriod = applyDaysFilter(schedulingPeriod, config.dayOfWeek);
+    const days = resolveDaysFromPeriod(resolvedPeriod);
+    // Resolve coverage
+    const resolvedCoverage = semanticTimes.resolve(coverageReqs, days);
+    // Resolve rules
+    const allRules = [...config.rules];
+    // Validate pay data when cost rules are present
+    const costRuleNames = new Set([
+        "minimize-cost",
+        "day-cost-multiplier",
+        "day-cost-surcharge",
+        "time-cost-surcharge",
+        "overtime-weekly-multiplier",
+        "overtime-weekly-surcharge",
+        "overtime-daily-multiplier",
+        "overtime-daily-surcharge",
+        "overtime-tiered-multiplier",
+    ]);
+    const hasCostRules = allRules.some((r) => costRuleNames.has(r._rule));
+    if (hasCostRules) {
+        const missingPay = config.members.filter((m) => !m.pay).map((m) => m.id);
+        if (missingPay.length > 0) {
+            throw new Error(`Cost rules require pay data on all members. Missing pay: ${missingPay.join(", ")}`);
+        }
+    }
+    // Sort rules so minimize-cost compiles before modifier rules
+    const sortedRules = sortCostRulesFirst(allRules);
+    const ruleConfigs = resolveRules(sortedRules, roles, skills, memberIds);
+    return {
+        members: config.members,
+        shiftPatterns: config.shiftPatterns,
+        schedulingPeriod: resolvedPeriod,
+        coverage: resolvedCoverage,
+        ruleConfigs,
+        ruleFactories: Object.keys(config.ruleFactories).length > 0
+            ? { ...builtInCpsatRuleFactories, ...config.ruleFactories }
+            : undefined,
+        weekStartsOn: config.weekStartsOn,
+    };
+}
+// ============================================================================
+// Internal: Build SolveResult from solver response
+// ============================================================================
+function mapSolverStatus(solverStatus) {
+    switch (solverStatus) {
+        case "OPTIMAL":
+            return "optimal";
+        case "FEASIBLE":
+            return "feasible";
+        case "INFEASIBLE":
+            return "infeasible";
+        case "TIMEOUT":
+        case "ERROR":
+            return "no_solution";
+        default:
+            return "no_solution";
+    }
+}
+function buildSolveResult(response, compiled, config) {
+    const status = mapSolverStatus(response.status);
+    const parsed = parseSolverResponse(response);
+    // Run post-solve validation when a solution exists
+    if (parsed.assignments.length > 0 && (status === "optimal" || status === "feasible")) {
+        const resolved = resolveAssignments(parsed.assignments, compiled.builder.shiftPatterns);
+        compiled.builder.reporter.analyzeSolution(response);
+        compiled.builder.validateSolution(resolved);
+    }
+    const validation = compiled.builder.reporter.getValidation();
+    const result = {
+        status,
+        assignments: parsed.assignments,
+        validation,
+    };
+    // Compute cost breakdown when cost rules are present and a solution was found
+    if (parsed.assignments.length > 0 && (status === "optimal" || status === "feasible")) {
+        const hasCostRules = config.rules.some((r) => r._rule === "minimize-cost");
+        if (hasCostRules) {
+            result.cost = calculateScheduleCost(parsed.assignments, {
+                members: config.members,
+                shiftPatterns: config.shiftPatterns,
+                rules: compiled.builder.rules,
+            });
+        }
+    }
+    return result;
+}
+// ============================================================================
+// Internal: Coverage Translation
+// ============================================================================
+function buildCoverageRequirements(entries, roles, skills) {
+    return entries.map((entry) => {
+        // Variant form: produce a VariantCoverageRequirement
+        if (entry.variants) {
+            return buildVariantCoverageRequirement(entry, roles, skills);
+        }
+        // Simple form: produce a SemanticCoverageRequirement
+        const base = {
+            semanticTime: entry.timeName,
+            targetCount: entry.count,
+        };
+        if (entry.options.priority)
+            base.priority = entry.options.priority;
+        if (entry.options.dayOfWeek && entry.options.dayOfWeek.length > 0) {
+            base.dayOfWeek = entry.options.dayOfWeek;
+        }
+        if (entry.options.dates)
+            base.dates = entry.options.dates;
+        return buildSimpleCoverageTarget(entry, base, roles, skills);
+    });
+}
+/**
+ * Resolve the target (role/skill) for a simple coverage entry.
+ */
+function buildSimpleCoverageTarget(entry, base, roles, skills) {
+    if (Array.isArray(entry.target)) {
+        return {
+            ...base,
+            roleIds: entry.target,
+        };
+    }
+    const singleTarget = entry.target;
+    if (roles.has(singleTarget)) {
+        if (entry.options.skillIds) {
+            return {
+                ...base,
+                roleIds: [singleTarget],
+                skillIds: entry.options.skillIds,
+            };
+        }
+        return {
+            ...base,
+            roleIds: [singleTarget],
+        };
+    }
+    if (skills.has(singleTarget)) {
+        return {
+            ...base,
+            skillIds: [singleTarget],
+        };
+    }
+    throw new Error(`Coverage target "${singleTarget}" is not a declared role or skill.`);
+}
+/**
+ * Build a VariantCoverageRequirement from a variant-form CoverageEntry.
+ */
+function buildVariantCoverageRequirement(entry, roles, skills) {
+    const variants = entry.variants;
+    const resolveTarget = () => {
+        if (Array.isArray(entry.target)) {
+            return { roleIds: entry.target };
+        }
+        const singleTarget = entry.target;
+        if (roles.has(singleTarget)) {
+            return { roleIds: [singleTarget] };
+        }
+        if (skills.has(singleTarget)) {
+            return { skillIds: [singleTarget] };
+        }
+        throw new Error(`Coverage target "${singleTarget}" is not a declared role or skill.`);
+    };
+    return {
+        semanticTime: entry.timeName,
+        variants,
+        ...resolveTarget(),
+    };
+}
+// ============================================================================
+// Internal: Rule Translation
+// ============================================================================
+function resolveRules(rules, roles, skills, memberIds) {
+    const ctx = { roles, skills, memberIds };
+    return rules.map((rule) => {
+        // Rules with custom resolvers handle their own translation
+        if (rule._resolve) {
+            return rule._resolve(ctx);
+        }
+        // Default resolution: appliesTo → entity scope, dates → specificDates
+        const { _type, _rule, _resolve, appliesTo, dates, ...passthrough } = rule;
+        const entityScope = resolveAppliesTo(appliesTo, roles, skills, memberIds);
+        const resolvedDates = dates ? { specificDates: dates } : {};
+        return {
+            name: _rule,
+            ...passthrough,
+            ...entityScope,
+            ...resolvedDates,
+        };
+    });
+}
+// ============================================================================
+// Internal: Cost Rule Ordering
+// ============================================================================
+/**
+ * Sorts rules so that `minimize-cost` compiles before cost modifier rules.
+ *
+ * The `minimize-cost` rule must be compiled first because modifier rules
+ * (multipliers, surcharges) reference cost variables it creates.
+ * Non-cost rules retain their original relative order.
+ */
+function sortCostRulesFirst(rules) {
+    return rules.toSorted((a, b) => {
+        const aIsCostBase = a._rule === "minimize-cost" ? 0 : 1;
+        const bIsCostBase = b._rule === "minimize-cost" ? 0 : 1;
+        return aIsCostBase - bIsCostBase;
+    });
+}
+// ============================================================================
+// Internal: Scheduling Period Helpers
+// ============================================================================
+function applyDaysFilter(schedulingPeriod, dayOfWeek) {
+    if (!dayOfWeek || dayOfWeek.length === 0) {
+        return schedulingPeriod;
+    }
+    const existingDays = schedulingPeriod.dayOfWeek;
+    if (!existingDays || existingDays.length === 0) {
+        return { ...schedulingPeriod, dayOfWeek: [...dayOfWeek] };
+    }
+    const existingSet = new Set(existingDays);
+    const intersected = dayOfWeek.filter((day) => existingSet.has(day));
+    return { ...schedulingPeriod, dayOfWeek: intersected };
+}
+//# sourceMappingURL=definition.js.map