dabke 0.83.0 → 0.84.0

package/dist/cpsat/model-builder.js

@@ -1,8 +1,10 @@
-import { resolveDaysFromPeriod, toDayOfWeekUTC } from "../datetime.utils.js";
-import { MINUTES_PER_DAY, normalizeEndMinutes, OBJECTIVE_WEIGHTS, parseDayString, priorityToPenalty, timeOfDayToMinutes, } from "./utils.js";
+import { resolveDaysFromPeriod } from "../datetime.utils.js";
+import { MINUTES_PER_DAY, normalizeEndMinutes, OBJECTIVE_WEIGHTS, priorityToPenalty, timeOfDayToMinutes, } from "./utils.js";
 import { buildCpsatRules } from "./rules/resolver.js";
-import { builtInCpsatRuleFactories } from "./rules/registry.js";
+import { builtInCpsatRuleRegistry } from "./rules/registry.js";
+import { TARGET_PEAK_CONCURRENT_ASSIGNMENTS_OBJECTIVE_STAGE_ID } from "./rules/target-peak-concurrent-assignments.js";
 import { ValidationReporterImpl } from "./validation-reporter.js";
+const UNSTAGED_OBJECTIVE_STAGE_ID = "__dabke_unstaged__";
 /**
  * Compilation context that creates variables, constraints, and objectives
  * and emits a `SolverRequest` for the Python CP-SAT solver service.
@@ -17,6 +19,7 @@ export class ModelBuilder {
     rules;
     weekStartsOn;
     options;
+    strategy;
     coverageBucketMinutes;
     reporter;
     fairDistribution;
@@ -25,21 +28,38 @@ export class ModelBuilder {
     #variables = new Map();
     #constraints = [];
     #objective = [];
+    #objectiveStageTerms = new Map();
+    #referencedObjectiveStages = new Set();
+    #objectiveStageOrder;
     #dayIndex = new Map();
+    #dayByIso = new Map();
     #shiftPatternMap = new Map();
     #builtRequest;
     #builtCompilation;
+    #compiledArtifacts = [];
+    #postSolveValidators = [];
+    #costArtifacts = [];
     constructor(config) {
         // Validate IDs don't contain the separator character
         for (const member of config.members) {
             if (member.id.includes(":")) {
                 throw new Error(`Member ID "${member.id}" cannot contain colons`);
             }
+            for (const roleId of member.roleIds) {
+                if (roleId.includes(":")) {
+                    throw new Error(`Role ID "${roleId}" cannot contain colons`);
+                }
+            }
         }
         for (const pattern of config.shiftPatterns) {
             if (pattern.id.includes(":")) {
                 throw new Error(`Shift pattern ID "${pattern.id}" cannot contain colons`);
             }
+            for (const roleId of pattern.roleIds ?? []) {
+                if (roleId.includes(":")) {
+                    throw new Error(`Role ID "${roleId}" cannot contain colons`);
+                }
+            }
         }
         // Validate coverage requirements have at least roles or skills
         for (const cov of config.coverage) {
@@ -48,22 +68,41 @@ export class ModelBuilder {
             if (!hasRoles && !hasSkills) {
                 throw new Error(`Coverage requirement for day "${cov.day}" must have at least one of roles or skills`);
             }
+            for (const roleId of cov.roleIds ?? []) {
+                if (roleId.includes(":")) {
+                    throw new Error(`Role ID "${roleId}" cannot contain colons`);
+                }
+            }
         }
         this.members = config.members;
         this.shiftPatterns = config.shiftPatterns;
         this.days = resolveDaysFromPeriod(config.schedulingPeriod);
         this.coverage = config.coverage;
+        const ruleCompileContext = {
+            members: this.members,
+            shiftPatterns: this.shiftPatterns,
+            days: this.days,
+            weekStartsOn: config.weekStartsOn ?? "monday",
+            coverageBucketMinutes: config.coverageBucketMinutes ?? 15,
+        };
         const compiledRuleConfigs = config.ruleConfigs
-            ? buildCpsatRules(config.ruleConfigs, this.members, config.ruleFactories ?? builtInCpsatRuleFactories)
+            ? buildCpsatRules(config.ruleConfigs, this.members, ruleCompileContext, config.ruleRegistry ?? builtInCpsatRuleRegistry)
             : [];
         this.rules = [...compiledRuleConfigs, ...(config.rules ?? [])];
         this.weekStartsOn = config.weekStartsOn ?? "monday";
         this.options = config.solverOptions;
+        this.strategy = resolveModelSolveStrategy(config.strategy);
+        this.#objectiveStageOrder =
+            config.objectiveStageOrder === undefined ? undefined : [...config.objectiveStageOrder];
         this.coverageBucketMinutes = config.coverageBucketMinutes ?? 15;
         this.reporter = config.reporter ?? new ValidationReporterImpl();
         this.fairDistribution = config.fairDistribution ?? true;
-        this.days.forEach((day, idx) => this.#dayIndex.set(day, idx));
+        this.days.forEach((day, idx) => {
+            this.#dayIndex.set(day.iso, idx);
+            this.#dayByIso.set(day.iso, day);
+        });
         this.shiftPatterns.forEach((pattern) => this.#shiftPatternMap.set(pattern.id, pattern));
+        this.#compiledArtifacts = this.rules.flatMap((rule) => rule.artifacts.map((artifact) => ({ rule: rule.rule, artifact })));
     }
     boolVar(name) {
         const existing = this.#variables.get(name);
@@ -88,16 +127,40 @@ export class ModelBuilder {
         return name;
     }
     shiftActive(patternId, day) {
-        return this.boolVar(`shift:${patternId}:${day}`);
+        return this.boolVar(`shift:${patternId}:${day.iso}`);
     }
+    /**
+     * Returns the aggregate shift assignment variable for a member, pattern, and day.
+     *
+     * @remarks
+     * This variable means "the member works this shift pattern on this day". It is
+     * the presence literal for optional interval variables and the common variable
+     * used by shift-level rules, objectives, and skill-only coverage. Role-specific
+     * assignments are modeled separately and linked to this aggregate variable when
+     * a concrete role choice is available.
+     */
     assignment(memberId, patternId, day) {
-        return this.boolVar(`assign:${memberId}:${patternId}:${day}`);
+        return this.boolVar(`assign:${memberId}:${patternId}:${day.iso}`);
     }
-    addLinear(terms, op, rhs) {
-        this.#constraints.push({ type: "linear", terms, op, rhs });
+    /** Returns the role-specific assignment variable for a concrete role choice. */
+    #roleAssignment(memberId, patternId, roleId, day) {
+        return this.boolVar(`assign_role:${memberId}:${patternId}:${roleId}:${day.iso}`);
     }
-    addSoftLinear(terms, op, rhs, penalty, id) {
-        this.#constraints.push({ type: "soft_linear", terms, op, rhs, penalty, id });
+    addLinear(terms, op, rhs, id) {
+        const constraint = id === undefined
+            ? { type: "linear", terms, op, rhs }
+            : { type: "linear", terms, op, rhs, id };
+        this.#constraints.push(constraint);
+    }
+    addSoftLinear(terms, op, rhs, penalty, id, stage) {
+        if (!this.#isOptimizing()) {
+            return;
+        }
+        this.#markObjectiveStageReference(stage);
+        const constraint = stage === undefined
+            ? { type: "soft_linear", terms, op, rhs, penalty, id }
+            : { type: "soft_linear", terms, op, rhs, penalty, id, stage };
+        this.#constraints.push(constraint);
     }
     addExactlyOne(vars) {
         if (vars.length === 0)
@@ -153,11 +216,25 @@ export class ModelBuilder {
         this.#constraints.push({ type: "no_overlap", intervals });
     }
     addPenalty(varName, weight) {
+        this.#addPenalty(varName, weight);
+    }
+    #addPenalty(varName, weight, stage) {
+        if (!this.#isOptimizing()) {
+            return;
+        }
+        this.#markObjectiveStageReference(stage);
         // CP-SAT requires integer coefficients. Round to nearest integer.
         const rounded = Math.round(weight);
         if (rounded === 0)
             return;
-        this.#objective.push({ var: varName, coeff: rounded });
+        const term = { var: varName, coeff: rounded };
+        if (stage !== undefined) {
+            const stageTerms = this.#objectiveStageTerms.get(stage) ?? [];
+            stageTerms.push(term);
+            this.#objectiveStageTerms.set(stage, stageTerms);
+            return;
+        }
+        this.#objective.push(term);
     }
     membersWithRole(roleId) {
         return this.members.filter((m) => m.roleIds.includes(roleId));
@@ -193,19 +270,44 @@ export class ModelBuilder {
         }
         return pattern.roleIds.some((role) => member.roleIds.includes(role));
     }
+    #assignableRoleIds(member, pattern) {
+        const patternRoleIds = pattern.roleIds;
+        const roles = patternRoleIds && patternRoleIds.length > 0
+            ? member.roleIds.filter((roleId) => patternRoleIds.includes(roleId))
+            : member.roleIds;
+        return [...new Set(roles)];
+    }
+    /**
+     * Returns the variables that can satisfy one coverage bucket for this member and pattern.
+     *
+     * Role coverage uses role-specific variables so a single shift assignment fills
+     * one concrete role. Skill-only coverage has no role to choose, so it uses the
+     * aggregate assignment variable directly.
+     */
+    #coverageRoleAssignmentVars(member, pattern, cov, day) {
+        if (!cov.roleIds || cov.roleIds.length === 0) {
+            return [this.assignment(member.id, pattern.id, day)];
+        }
+        const assignableRoles = this.#assignableRoleIds(member, pattern);
+        const coverageRoles = assignableRoles.filter((roleId) => cov.roleIds.includes(roleId));
+        return coverageRoles.map((roleId) => this.#roleAssignment(member.id, pattern.id, roleId, day));
+    }
+    #canCoverCoverage(member, pattern, cov) {
+        const assignableRoles = this.#assignableRoleIds(member, pattern);
+        if (cov.roleIds && cov.roleIds.length > 0) {
+            return assignableRoles.some((roleId) => cov.roleIds.includes(roleId));
+        }
+        return true;
+    }
     /**
      * Checks if a shift pattern can be used on a specific day.
      * Returns false if the pattern has dayOfWeek restrictions that exclude this day.
      */
     patternAvailableOnDay(pattern, day) {
-        // If pattern has no day restrictions, it's available every day
         if (!pattern.dayOfWeek || pattern.dayOfWeek.length === 0) {
             return true;
         }
-        // Check if this day's day-of-week is in the allowed list
-        const date = parseDayString(day);
-        const dow = toDayOfWeekUTC(date);
-        return pattern.dayOfWeek.includes(dow);
+        return pattern.dayOfWeek.includes(day.dayOfWeek);
     }
     patternDuration(patternId) {
         const pattern = this.#shiftPatternMap.get(patternId);
@@ -216,11 +318,11 @@ export class ModelBuilder {
         return end - start;
     }
     startMinutes(pattern, day) {
-        const base = this.#dayOffset(day);
+        const base = this.#dayOffset(day.iso);
         return base + timeOfDayToMinutes(pattern.startTime);
     }
     endMinutes(pattern, day) {
-        const base = this.#dayOffset(day);
+        const base = this.#dayOffset(day.iso);
         const startOffset = timeOfDayToMinutes(pattern.startTime);
         const endOffset = normalizeEndMinutes(startOffset, timeOfDayToMinutes(pattern.endTime));
         return base + endOffset;
@@ -229,12 +331,33 @@ export class ModelBuilder {
         if (this.#builtCompilation) {
             return this.#builtCompilation;
         }
-        // 0. Apply all rules first (they may report exclusions and add constraints)
-        for (const rule of this.rules) {
-            rule.compile(this);
-        }
-        // Build exclusion lookup from reporter (populated by rules during compile)
+        this.#runRulePrechecks();
+        this.#applyRuleArtifacts();
+        // Build exclusion lookup from rule artifacts for coverage feasibility analysis.
         const mandatoryExclusions = buildExclusionLookup(this.reporter.getExclusions());
+        // Link concrete role choices to the aggregate assignment used by intervals and
+        // shift-level rules. This is the CP-SAT channeling pattern: exactly one role
+        // literal is true iff the aggregate assignment is true. Role-less members on
+        // unrestricted shifts deliberately skip this link; skill-only coverage uses
+        // the aggregate variable directly because there is no role decision to report.
+        for (const emp of this.members) {
+            for (const pattern of this.shiftPatterns) {
+                if (!this.canAssign(emp, pattern))
+                    continue;
+                for (const day of this.days) {
+                    if (!this.patternAvailableOnDay(pattern, day))
+                        continue;
+                    const assignmentVar = this.assignment(emp.id, pattern.id, day);
+                    const roleTerms = this.#assignableRoleIds(emp, pattern).map((roleId) => ({
+                        var: this.#roleAssignment(emp.id, pattern.id, roleId, day),
+                        coeff: 1,
+                    }));
+                    if (roleTerms.length === 0)
+                        continue;
+                    this.addLinear([...roleTerms, { var: assignmentVar, coeff: -1 }], "==", 0);
+                }
+            }
+        }
         // 1. Assignment implies shift is active
         for (const emp of this.members) {
             for (const pattern of this.shiftPatterns) {
@@ -261,7 +384,7 @@ export class ModelBuilder {
                     const start = this.startMinutes(pattern, day);
                     const end = this.endMinutes(pattern, day);
                     const size = end - start;
-                    const intervalName = `interval:${emp.id}:${pattern.id}:${day}`;
+                    const intervalName = `interval:${emp.id}:${pattern.id}:${day.iso}`;
                     this.intervalVar(intervalName, start, end, size, presenceVar);
                     empIntervals.push(intervalName);
                 }
@@ -304,6 +427,9 @@ export class ModelBuilder {
             patternsByBucketStart.set(bucketStart, patterns);
         }
         for (const cov of this.coverage) {
+            const covDay = this.#dayByIso.get(cov.day);
+            if (!covDay)
+                continue;
             const covStart = timeOfDayToMinutes(cov.startTime);
             const covEnd = normalizeEndMinutes(covStart, timeOfDayToMinutes(cov.endTime));
             const covKey = cov.roleIds?.join(",") ?? cov.skillIds?.join(",") ?? "unknown";
@@ -345,7 +471,7 @@ export class ModelBuilder {
                 const lookupBucketStart = bucketStart % MINUTES_PER_DAY;
                 // Get patterns that overlap this time bucket, then filter by day availability
                 const allPatterns = patternsByBucketStart.get(lookupBucketStart) ?? [];
-                const patterns = allPatterns.filter((p) => this.patternAvailableOnDay(p, cov.day));
+                const patterns = allPatterns.filter((p) => this.patternAvailableOnDay(p, covDay));
                 if (patterns.length === 0) {
                     recordBucketIssue(bucketIssues, {
                         key: "no_patterns",
@@ -368,6 +494,8 @@ export class ModelBuilder {
                     for (const pattern of patterns) {
                         if (!this.canAssign(emp, pattern))
                             continue;
+                        if (!this.#canCoverCoverage(emp, pattern, cov))
+                            continue;
                         assignableMembers.add(emp.id);
                         break;
                     }
@@ -425,7 +553,9 @@ export class ModelBuilder {
                     for (const emp of eligibleMembers) {
                         if (!this.canAssign(emp, pattern))
                             continue;
-                        coveringVarsSet.add(this.assignment(emp.id, pattern.id, cov.day));
+                        for (const roleAssignment of this.#coverageRoleAssignmentVars(emp, pattern, cov, covDay)) {
+                            coveringVarsSet.add(roleAssignment);
+                        }
                     }
                 }
                 const coveringVars = [...coveringVarsSet];
@@ -435,28 +565,31 @@ export class ModelBuilder {
                 const terms = coveringVars.map((v) => ({ var: v, coeff: 1 }));
                 const constraintId = `coverage:${covKey}:${cov.day}:${bucketStart}`;
                 if (cov.priority === "MANDATORY") {
-                    this.addLinear(terms, ">=", cov.targetCount);
+                    this.addLinear(terms, ">=", cov.targetCount, constraintId);
                 }
-                else {
+                else if (this.#isOptimizing()) {
                     this.addSoftLinear(terms, ">=", cov.targetCount, priorityToPenalty(cov.priority), constraintId);
                 }
-                // Track all coverage constraints (mandatory and soft) for post-solve reporting
-                this.reporter.trackConstraint({
-                    id: constraintId,
-                    type: "coverage",
-                    description: `${cov.targetCount}x ${covKey} on ${cov.day} at ${formatMinutes(bucketStart)}`,
-                    targetValue: cov.targetCount,
-                    comparator: ">=",
-                    day: cov.day,
-                    timeSlot: formatMinutes(bucketStart),
-                    roleIds: cov.roleIds,
-                    skillIds: cov.skillIds,
-                    context: {
-                        days: [cov.day],
-                        memberIds: eligibleMembers.map((e) => e.id),
-                    },
-                    group: cov.group,
-                });
+                // Track coverage constraints that can produce post-solve feedback.
+                if (cov.priority === "MANDATORY" || this.#isOptimizing()) {
+                    this.reporter.trackConstraint({
+                        id: constraintId,
+                        type: "coverage",
+                        source: cov.priority === "MANDATORY" ? "hard" : "soft",
+                        description: `${cov.targetCount}x ${covKey} on ${cov.day} at ${formatMinutes(bucketStart)}`,
+                        targetValue: cov.targetCount,
+                        comparator: ">=",
+                        day: cov.day,
+                        timeSlot: formatMinutes(bucketStart),
+                        roleIds: cov.roleIds,
+                        skillIds: cov.skillIds,
+                        context: {
+                            days: [cov.day],
+                            memberIds: eligibleMembers.map((e) => e.id),
+                        },
+                        group: cov.group,
+                    });
+                }
             }
             for (const issue of bucketIssues.values()) {
                 const ranges = bucketStartsToRanges(issue.bucketStarts, bucket, covEnd).map((range) => `${formatMinutes(range.start)}-${formatMinutes(range.end)}`);
@@ -474,10 +607,22 @@ export class ModelBuilder {
                         group: cov.group,
                     });
                 }
-                // Note: soft coverage warnings are tracked via trackConstraint and reported post-solve
+                // Note: optimized solves report soft coverage post-solve via tracked constraints.
             }
         }
-        // 3. Default objective: shift minimization with optional fair distribution
+        if (this.#isOptimizing()) {
+            this.#addDefaultObjective();
+        }
+        this.#builtRequest = this.#buildRequest();
+        this.#builtCompilation = {
+            request: this.#builtRequest,
+            validation: this.reporter.getValidation(),
+            canSolve: !this.reporter.hasErrors(),
+        };
+        return this.#builtCompilation;
+    }
+    #addDefaultObjective() {
+        // Default objective: shift minimization with optional fair distribution
         //
         // The objective has three components (see OBJECTIVE_WEIGHTS in utils.ts):
         // a) Minimize number of active shift patterns (SHIFT_ACTIVE=1000)
@@ -538,13 +683,6 @@ export class ModelBuilder {
                 }
             }
         }
-        this.#builtRequest = this.#buildRequest();
-        this.#builtCompilation = {
-            request: this.#builtRequest,
-            validation: this.reporter.getValidation(),
-            canSolve: !this.reporter.hasErrors(),
-        };
-        return this.#builtCompilation;
     }
     /**
      * Run post-solve validation on all rules.
@@ -555,12 +693,160 @@ export class ModelBuilder {
             members: this.members,
             days: this.days,
             shiftPatterns: this.shiftPatterns,
+            weekStartsOn: this.weekStartsOn,
+        };
+        for (const validator of this.#postSolveValidators) {
+            validator.run(assignments, this.reporter, context);
+        }
+    }
+    calculateCost(assignments) {
+        const context = {
+            members: this.members,
+            days: this.days,
+            shiftPatterns: this.shiftPatterns,
+            weekStartsOn: this.weekStartsOn,
+        };
+        const entries = this.#costArtifacts.flatMap((artifact) => artifact.calculateCost ? [...artifact.calculateCost(assignments, context).entries] : []);
+        return { entries };
+    }
+    #runRulePrechecks() {
+        const context = {
+            members: this.members,
+            days: this.days,
+            shiftPatterns: this.shiftPatterns,
+            weekStartsOn: this.weekStartsOn,
         };
         for (const rule of this.rules) {
-            rule.validate?.(assignments, this.reporter, context);
+            const hasHardConstraint = rule.artifacts.some((artifact) => artifact.kind === "hard-constraint");
+            const shouldRunPrechecks = this.#isOptimizing() || hasHardConstraint;
+            if (!shouldRunPrechecks)
+                continue;
+            for (const artifact of rule.artifacts) {
+                if (artifact.kind === "pre-solve-feedback") {
+                    artifact.run(context, this.reporter);
+                }
+            }
+        }
+    }
+    #applyRuleArtifacts() {
+        this.#postSolveValidators = [];
+        this.#costArtifacts = [];
+        for (const { rule, artifact } of this.#compiledArtifacts) {
+            switch (artifact.kind) {
+                case "variable": {
+                    if (artifact.variable.type === "bool") {
+                        this.boolVar(artifact.variable.name);
+                    }
+                    else {
+                        this.intVar(artifact.variable.name, artifact.variable.min, artifact.variable.max);
+                    }
+                    break;
+                }
+                case "hard-constraint": {
+                    const constraintId = artifact.validation.strategy === "report" ? artifact.validation.id : undefined;
+                    this.addLinear([...artifact.terms], artifact.comparator, artifact.targetValue, constraintId);
+                    this.#reportHardConstraint(rule, artifact);
+                    break;
+                }
+                case "soft-constraint": {
+                    if (!this.#isOptimizing()) {
+                        break;
+                    }
+                    const solverConstraintId = artifact.validation.strategy === "report" ? artifact.constraintId : undefined;
+                    this.addSoftLinear([...artifact.terms], artifact.comparator, artifact.targetValue, artifact.penalty, solverConstraintId, artifact.stage);
+                    this.#reportSoftConstraint(rule, artifact);
+                    break;
+                }
+                case "objective": {
+                    if (!this.#isOptimizing()) {
+                        break;
+                    }
+                    this.#markObjectiveStageReference(artifact.stage);
+                    for (const term of artifact.terms) {
+                        this.#addPenalty(term.var, term.coeff, artifact.stage);
+                    }
+                    break;
+                }
+                case "coverage-exclusion": {
+                    this.reporter.excludeFromCoverage({
+                        memberId: artifact.memberId,
+                        day: artifact.day,
+                        startTime: artifact.startTime,
+                        endTime: artifact.endTime,
+                    });
+                    break;
+                }
+                case "pre-solve-feedback": {
+                    break;
+                }
+                case "post-solve-feedback": {
+                    if (!this.#isOptimizing()) {
+                        break;
+                    }
+                    this.#postSolveValidators.push(artifact);
+                    break;
+                }
+                case "cost": {
+                    if (!this.#isOptimizing()) {
+                        break;
+                    }
+                    artifact.compileObjective?.(this);
+                    this.#costArtifacts.push(artifact);
+                    break;
+                }
+            }
         }
     }
+    #reportHardConstraint(rule, artifact) {
+        if (artifact.validation.strategy !== "report") {
+            return;
+        }
+        this.reporter.trackConstraint({
+            id: artifact.validation.id,
+            type: "rule",
+            source: "hard",
+            rule,
+            description: artifact.description,
+            targetValue: artifact.targetValue,
+            comparator: artifact.comparator,
+            context: artifact.context,
+            group: artifact.group,
+        });
+    }
+    #reportSoftConstraint(rule, artifact) {
+        if (artifact.validation.strategy !== "report") {
+            return;
+        }
+        this.reporter.trackConstraint({
+            id: artifact.constraintId,
+            type: "rule",
+            source: "soft",
+            rule,
+            description: artifact.description,
+            targetValue: artifact.targetValue,
+            comparator: artifact.comparator,
+            context: artifact.context,
+            group: artifact.group,
+        });
+    }
     #buildRequest() {
+        if (!this.#isOptimizing()) {
+            return {
+                variables: Array.from(this.#variables.values()),
+                constraints: this.#constraints,
+                mode: "satisfy",
+                options: this.#satisfyOptions(),
+            };
+        }
+        const objectiveStageOrder = this.#resolveObjectiveStageOrder();
+        if (objectiveStageOrder) {
+            return {
+                variables: Array.from(this.#variables.values()),
+                constraints: this.#constraintsForStagedRequest(),
+                objectiveStages: this.#buildObjectiveStages(objectiveStageOrder),
+                options: this.options,
+            };
+        }
         return {
             variables: Array.from(this.#variables.values()),
             constraints: this.#constraints,
@@ -568,6 +854,102 @@ export class ModelBuilder {
             options: this.options,
         };
     }
+    #markObjectiveStageReference(stage) {
+        if (stage === undefined) {
+            return;
+        }
+        this.#referencedObjectiveStages.add(stage);
+    }
+    #isOptimizing() {
+        return this.strategy.type === "optimize";
+    }
+    #satisfyOptions() {
+        return {
+            ...this.options,
+            solutionLimit: this.options?.solutionLimit ?? 1,
+        };
+    }
+    #resolveObjectiveStageOrder() {
+        const referencedStages = [...this.#referencedObjectiveStages];
+        if (referencedStages.length === 0) {
+            return undefined;
+        }
+        this.#validateReferencedObjectiveStages(referencedStages);
+        if (this.options?.solutionLimit === 1) {
+            throw new Error("ModelBuilder objectiveStageOrder cannot be used with solverOptions.solutionLimit=1.");
+        }
+        const stageOrder = this.#objectiveStageOrder;
+        if (stageOrder === undefined) {
+            if (referencedStages.length === 1) {
+                return [referencedStages[0]];
+            }
+            throw new Error(`Multiple objective stages were referenced (${referencedStages.join(", ")}); provide ModelBuilder objectiveStageOrder explicitly.`);
+        }
+        if (referencedStages.includes(TARGET_PEAK_CONCURRENT_ASSIGNMENTS_OBJECTIVE_STAGE_ID)) {
+            throw new Error("targetPeakConcurrentAssignments cannot be combined with ModelBuilder objectiveStageOrder until the multi-stage objective API is public.");
+        }
+        if (stageOrder.length === 0) {
+            throw new Error("ModelBuilder objectiveStageOrder cannot be empty when provided.");
+        }
+        const declaredStages = new Set();
+        for (const stage of stageOrder) {
+            if (stage.trim() === "") {
+                throw new Error("ModelBuilder objectiveStageOrder cannot contain an empty stage id.");
+            }
+            if (stage === UNSTAGED_OBJECTIVE_STAGE_ID) {
+                throw new Error(`ModelBuilder objectiveStageOrder cannot contain reserved stage id "${UNSTAGED_OBJECTIVE_STAGE_ID}".`);
+            }
+            if (declaredStages.has(stage)) {
+                throw new Error(`Duplicate objective stage id "${stage}" in objectiveStageOrder.`);
+            }
+            declaredStages.add(stage);
+        }
+        const allowedStages = new Set(declaredStages);
+        allowedStages.add(UNSTAGED_OBJECTIVE_STAGE_ID);
+        for (const stage of referencedStages) {
+            if (stage === UNSTAGED_OBJECTIVE_STAGE_ID) {
+                throw new Error(`Rule artifacts cannot use reserved objective stage id "${UNSTAGED_OBJECTIVE_STAGE_ID}".`);
+            }
+            if (!allowedStages.has(stage)) {
+                throw new Error(`Objective stage "${stage}" is not declared in ModelBuilder objectiveStageOrder.`);
+            }
+        }
+        return stageOrder;
+    }
+    #validateReferencedObjectiveStages(referencedStages) {
+        for (const stage of referencedStages) {
+            if (stage.trim() === "") {
+                throw new Error("Rule artifacts cannot use an empty objective stage id.");
+            }
+            if (stage === UNSTAGED_OBJECTIVE_STAGE_ID) {
+                throw new Error(`Rule artifacts cannot use reserved objective stage id "${UNSTAGED_OBJECTIVE_STAGE_ID}".`);
+            }
+        }
+    }
+    #constraintsForStagedRequest() {
+        return this.#constraints.map((constraint) => {
+            if (constraint.type !== "soft_linear" || constraint.stage !== undefined) {
+                return constraint;
+            }
+            return { ...constraint, stage: UNSTAGED_OBJECTIVE_STAGE_ID };
+        });
+    }
+    #buildObjectiveStages(objectiveStageOrder) {
+        const stages = objectiveStageOrder.map((id) => ({
+            id,
+            sense: "minimize",
+            terms: this.#objectiveStageTerms.get(id) ?? [],
+        }));
+        const hasTailSoftConstraint = this.#constraints.some((constraint) => constraint.type === "soft_linear" && constraint.stage === undefined);
+        if (this.#objective.length > 0 || hasTailSoftConstraint) {
+            stages.push({
+                id: UNSTAGED_OBJECTIVE_STAGE_ID,
+                sense: "minimize",
+                terms: this.#objective,
+            });
+        }
+        return stages;
+    }
     #dayOffset(day) {
         const idx = this.#dayIndex.get(day);
         if (idx === undefined) {
@@ -576,6 +958,19 @@ export class ModelBuilder {
         return idx * MINUTES_PER_DAY;
     }
 }
+function resolveModelSolveStrategy(strategy) {
+    if (strategy === undefined) {
+        return { type: "optimize" };
+    }
+    if (typeof strategy !== "object" || strategy === null || !("type" in strategy)) {
+        throw new Error("ModelBuilder strategy must be an object with a type field.");
+    }
+    const strategyType = strategy.type;
+    if (strategyType === "optimize" || strategyType === "feasibility-only") {
+        return { type: strategyType };
+    }
+    throw new Error(`Unknown ModelBuilder strategy "${String(strategyType)}".`);
+}
 function recordBucketIssue(bucketIssues, issue, bucketStart) {
     const existing = bucketIssues.get(issue.key);
     if (existing) {