Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

34.0 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.

import { type Database, getCompanyTimeZone } from "@carbon/database";
import type { DB } from "@carbon/database/client";
import { getLogger } from "@carbon/logger";
import type { SupabaseClient } from "@supabase/supabase-js";
import type { Kysely } from "kysely";
import {
  AssemblyHandler,
  buildMakeMethodDependencies
} from "./assembly-handler.ts";
import type { BatchPlacement } from "./batch-scheduler.ts";
import {
  type BehindTargetOperation,
  composeBehindTarget
} from "./conflict-messages.ts";
import { buildScheduledOperations } from "./date-calculator.ts";
import {
  businessDay,
  msToInstantIso,
  toInstantIso,
  toInstantMs
} from "./date-utils.ts";
import {
  buildOperationDependencies,
  DependencyGraphImpl,
  dependenciesToRecords
} from "./dependency-manager.ts";
import { calculateDurationHours } from "./duration-calculator.ts";
import {
  type AvailabilityWindows,
  buildFiniteContext,
  loadAvailabilityWindows
} from "./finite-context.ts";
import {
  KyselyMasterDataProvider,
  type MasterDataProvider
} from "./master-data-provider.ts";
import { MaterialManager } from "./material-manager.ts";
import { calendarAdapters, computeNeedByDates } from "./need-by-calculator.ts";
import {
  applyPriorities,
  calculatePrioritiesByWorkCenter,
  committedDueDate,
  toOperationWithJobInfo
} from "./priority-calculator.ts";
import {
  dependencyEdgesEqual,
  type JobWrites,
  placementWrites
} from "./run-overlay.ts";
import type {
  AssemblyNode,
  BaseOperation,
  Job,
  JobOperationDependency,
  OperationWithJobInfo,
  ScheduledOperation,
  SchedulingOptions,
  SchedulingResult
} from "./types.ts";
import { capacityHoldingJobStatuses } from "./types.ts";
import {
  applyWorkCenterSelections,
  type FiniteSchedulingContext,
  WorkCenterSelector
} from "./work-center-selector.ts";

export { SCHEDULING_HORIZON_DAYS } from "./finite-context.ts";

const log = getLogger("planning", "schedule");

/**
 * Unified Scheduling Engine
 * Orchestrates all scheduling operations for both initial scheduling and rescheduling
 */
export class SchedulingEngine {
  private client: SupabaseClient<Database>;
  private db: Kysely<DB>;
  private jobId: string;
  private companyId: string;
  private userId: string;

  private job: Job | null = null;
  private operations: BaseOperation[] = [];
  private dependencies: JobOperationDependency[] = [];
  private scheduledOperations: Map<string, ScheduledOperation> = new Map();
  private affectedWorkCenters: Set<string> = new Set();
  private assemblyDepth: number = 0;
  private conflictsDetected: number = 0;
  private timezone: string = "UTC";

  private assemblyHandler: AssemblyHandler;
  private assemblyTree: Promise<AssemblyNode | null> | null = null;
  private allOperations: Promise<BaseOperation[]> | null = null;
  private workCenterSelector: WorkCenterSelector | null = null;
  private materialManager: MaterialManager;
  private reservationsWritten = 0;

  /**
   * The single `now` for this run — captured ONCE by the caller and shared
   * across every job in a batch so the whole location schedules against one
   * clock (determinism: identical snapshot + identical now ⇒ identical
   * schedule). Never `Date.now()` inside the engine's placement path.
   * epoch-ms.
   */
  private now: number;
  /**
   * The engine writes nothing: run() leaves what it wants stored here, and the
   * caller persists it (or, for the expedite what-if, drops it).
   */
  private writes: JobWrites | null = null;
  /** Materials this run puts on an operation: material id → operation id. */
  private materialLinks = new Map<string, string>();
  private dependencyWrite: JobWrites["dependencies"] = null;
  private readyOperationIds: string[] = [];
  /**
   * Job ids whose live reservations to EXCLUDE from the snapshot — the whole
   * batch, so each run sees only non-batch reservations plus the in-run
   * placements of already-run batch jobs. Defaults to just this job.
   */
  private excludeJobIds: string[];
  private batchPlacements: Map<string, BatchPlacement> | null = null;
  /** Forecast finish (max placed end) — set after placement, persisted. */
  private projectedCompletionAt: string | null = null;
  /** True when this regen flipped the job from on-time (or unforecast) to late. */
  private newlyLate = false;
  /**
   * Backward need-by targets per operation id ("YYYY-MM-DD" | null), computed
   * by computeNeedBys() BEFORE placement and read by NOTHING in the placement
   * path — the location write diff-writes them to jobOperation.dueDate
   * (spec 2026-08-15 dual dates).
   */
  private needByByOperation: Map<string, string | null> = new Map();
  /**
   * Forward topological order of this job's operation ids — the need-by
   * pass's dependency graph read front-to-back (set by computeNeedBys, the
   * same DAG placement orders itself by). Reused by the behind-target
   * attribution so "first behind target" means first in the routing, not
   * first in map-insertion order.
   */
  private topologicalOrder: string[] = [];
  /**
   * The run's one availability-windows fetch, shared by the need-by pass and
   * the finite placement context so targets and forecasts run on the SAME
   * calendar physics (and the provider is read once, not twice).
   */
  private availabilityWindows: AvailabilityWindows | null = null;

  private provider: MasterDataProvider;

  constructor(
    options: SchedulingOptions & {
      client: SupabaseClient<Database>;
      db: Kysely<DB>;
      provider?: MasterDataProvider;
      /** Shared run clock (epoch-ms); defaults to a fresh clock if omitted. */
      now?: number;
      /** Batch job ids to exclude from the reservation snapshot. */
      excludeJobIds?: string[];
      /**
       * Pre-placed windows for RELEASED-batch member operations (from the
       * batch pre-pass in run-schedule). Members take the window verbatim;
       * their reservations are the pre-pass's coalesced batch rows.
       */
      batchPlacements?: Map<string, BatchPlacement> | null;
    }
  ) {
    this.client = options.client;
    this.db = options.db;
    this.jobId = options.jobId;
    this.companyId = options.companyId;
    this.userId = options.userId;
    this.now = options.now ?? Date.now();
    this.batchPlacements = options.batchPlacements ?? null;
    this.excludeJobIds =
      options.excludeJobIds && options.excludeJobIds.length > 0
        ? options.excludeJobIds
        : [this.jobId];

    this.provider =
      options.provider ??
      new KyselyMasterDataProvider(this.db, this.client, this.companyId);

    this.assemblyHandler = new AssemblyHandler(this.provider);
    this.materialManager = new MaterialManager(this.provider);
  }

  /**
   * Initialize the engine - load job, operations, and dependencies
   */
  async initialize(): Promise<void> {
    // Load job
    const job = await this.provider.getJob(this.jobId);

    if (!job) {
      throw new Error(`Job ${this.jobId} not found`);
    }

    this.job = job;

    // "Today" (conflict detection, fallback anchor) follows the job site's
    // wall clock — scheduling is operational, not ledger-scoped.
    this.timezone = job.locationId
      ? await this.provider.getLocationTimeZone(job.locationId)
      : await getCompanyTimeZone(this.db, this.companyId);

    // Initialize work center selector with location
    if (job.locationId) {
      this.workCenterSelector = new WorkCenterSelector(
        this.provider,
        job.locationId
      );
      await this.workCenterSelector.initialize();
    }

    // Load operations
    this.operations = await this.provider.getOperations(this.jobId);

    // Load existing dependencies as a starting point; createDependencies()
    // rebuilds the non-rework edges before placement.
    this.dependencies = await this.provider.getDependencies(this.jobId);

    // Initialize material manager
    await this.materialManager.initialize(this.jobId);

    // Assign operations to materials that don't have one.
    if (this.operations.length > 0) {
      const operationsByJobMakeMethodId = this.operations.reduce<
        Record<string, BaseOperation[]>
      >((acc, op) => {
        if (!acc[op.jobMakeMethodId!]) {
          acc[op.jobMakeMethodId!] = [];
        }
        acc[op.jobMakeMethodId!]!.push(op);
        return acc;
      }, {});

      const materialIds = this.materialManager.getMaterialIds();
      for (const link of this.materialManager.assignOperationsToMaterials(
        materialIds,
        operationsByJobMakeMethodId
      )) {
        this.materialLinks.set(link.materialId, link.operationId);
      }
    }

    // Build assembly tree and get depth
    const assemblyTree = await this.loadAssemblyTree();
    if (assemblyTree) {
      this.assemblyDepth = this.assemblyHandler.getAssemblyDepth(assemblyTree);
    }
  }

  /**
   * The job's assembly tree and its full operation list are read once per
   * run: nothing in a run changes the method structure or which operations
   * exist, and each read was a round trip per phase per job.
   */
  private loadAssemblyTree(): Promise<AssemblyNode | null> {
    this.assemblyTree ??= this.assemblyHandler.buildAssemblyTree(this.jobId);
    return this.assemblyTree;
  }

  private loadAllOperations(): Promise<BaseOperation[]> {
    this.allOperations ??= this.provider.getOperations(this.jobId, {
      includeDone: true
    });
    return this.allOperations;
  }

  /**
   * Create operation dependencies based on assembly structure.
   * Loads ALL operations (including Done) to build the complete DAG.
   */
  async createDependencies(): Promise<void> {
    // Load all operations for dependency building (not just active ones)
    const allOperations = await this.loadAllOperations();

    // Build assembly tree
    const assemblyTree = await this.loadAssemblyTree();
    if (!assemblyTree) {
      log.warning("No assembly tree found for job", { jobId: this.jobId });
      return;
    }

    // Get all jobMakeMethodIds
    const makeMethodIds =
      this.assemblyHandler.getAllJobMakeMethodIds(assemblyTree);

    // Get job materials for linking
    const jobMaterials =
      await this.provider.getMaterialsWithMakeMethod(makeMethodIds);

    // Build map from make method to operation
    const jobMakeMethodToOperationId: Record<string, string | null> = {};
    for (const m of jobMaterials) {
      if (m.jobMaterialMakeMethodId) {
        // A material this run put on an operation is not stored yet.
        jobMakeMethodToOperationId[m.jobMaterialMakeMethodId] =
          m.jobOperationId ??
          (m.id ? this.materialLinks.get(m.id) : undefined) ??
          null;
      }
    }

    // Group non-rework operations by jobMakeMethodId
    const operationsByMethod = new Map<string, BaseOperation[]>();
    for (const op of allOperations) {
      if (op.jobMakeMethodId && !op.reworkId) {
        if (!operationsByMethod.has(op.jobMakeMethodId)) {
          operationsByMethod.set(op.jobMakeMethodId, []);
        }
        operationsByMethod.get(op.jobMakeMethodId)!.push(op);
      }
    }

    // Build make method dependencies
    const makeMethodDeps = buildMakeMethodDependencies(assemblyTree);

    // Build operation dependencies
    const allDependencies = new Map<string, Set<string>>();

    // Initialize all non-rework operations
    for (const op of allOperations) {
      if (op.id && !op.reworkId) {
        allDependencies.set(op.id, new Set());
      }
    }

    // Process each make method's operations
    for (const methodDep of makeMethodDeps) {
      const methodOps = operationsByMethod.get(methodDep.id) ?? [];

      // Get last operation of this method
      const sortedOps = [...methodOps].sort(
        (a, b) => (a.order ?? 0) - (b.order ?? 0)
      );
      const lastOperation = sortedOps[sortedOps.length - 1];

      // If this method has a parent, link last op to parent's consuming operation
      if (methodDep.id && methodDep.parentId !== null) {
        let parentOperation = jobMakeMethodToOperationId[methodDep.id];

        // If no specific operation was set, default to the first operation of the parent
        if (!parentOperation && methodDep.parentId) {
          const parentOps = operationsByMethod.get(methodDep.parentId) ?? [];
          const sortedParentOps = [...parentOps].sort(
            (a, b) => (a.order ?? 0) - (b.order ?? 0)
          );
          parentOperation = sortedParentOps[0]?.id ?? null;
        }

        if (parentOperation && lastOperation?.id) {
          const deps = allDependencies.get(parentOperation);
          if (deps) {
            deps.add(lastOperation.id);
          }
        }
      }

      // Build dependencies within this method (handling "With Previous")
      const methodDeps = buildOperationDependencies(methodOps);
      for (const [opId, deps] of methodDeps) {
        const existing = allDependencies.get(opId);
        if (existing) {
          for (const depId of deps) {
            existing.add(depId);
          }
        }
      }
    }

    const reworkOpIds = allOperations
      .filter((op) => op.reworkId)
      .map((op) => op.id!);

    const records = dependenciesToRecords(
      allDependencies,
      this.jobId,
      this.companyId
    );

    // The non-rework edges are rebuilt only when they differ from the stored
    // ones: a routing changes far less often than its schedule does.
    const reworkOps = new Set(reworkOpIds);
    const storedEdges = this.dependencies.filter(
      (d) => !reworkOps.has(d.operationId) && !reworkOps.has(d.dependsOnId)
    );
    this.dependencyWrite = dependencyEdgesEqual(storedEdges, records)
      ? null
      : {
          reworkOpIds,
          edges: records.map((r) => ({
            operationId: r.operationId,
            dependsOnId: r.dependsOnId
          }))
        };

    // Unblock dependency-free operations to Ready. Two guards keep this from
    // RE-OPENING work that is already finished or in flight:
    //
    //  1. Only OPEN jobs. A terminal job (Completed/Closed/Cancelled) or a
    //     pre-release Draft/Planned job is never re-opened by a regen. Open
    //     work is `capacityHoldingJobStatuses`; the batch loader already
    //     filters to these, so this is defense-in-depth for any direct caller.
    //  2. Only resettable operation statuses. Never overwrite an operation
    //     that is Done/Canceled (finished) or In Progress/Paused (running) —
    //     only Ready/Waiting/Todo become Ready. Without this, a first op that
    //     an operator already completed was flipped back to Ready, and because
    //     `is_last_job_operation` requires EVERY op Done, the finished job
    //     could then never auto-complete (it sat stuck as open work).
    const jobIsOpen =
      this.job?.status != null &&
      (capacityHoldingJobStatuses as readonly string[]).includes(
        this.job.status
      );
    if (jobIsOpen) {
      const resettable = new Set(
        allOperations
          .filter(
            (op) =>
              !["Ready", "Done", "Canceled", "In Progress", "Paused"].includes(
                op.status ?? ""
              )
          )
          .map((op) => op.id)
      );
      this.readyOperationIds = [...allDependencies]
        .filter(([opId, deps]) => deps.size === 0 && resettable.has(opId))
        .map(([opId]) => opId);
    }

    // Store dependencies for date calculation (non-rework edges rebuilt above)
    this.dependencies = records.map((r) => ({
      operationId: r.operationId,
      dependsOnId: r.dependsOnId,
      jobId: r.jobId
    }));

    // Append rework dependency edges so rework ops are correctly scheduled
    if (reworkOpIds.length > 0) {
      const reworkDeps = await this.provider.getReworkDependencies(
        this.jobId,
        reworkOpIds
      );

      for (const d of reworkDeps) {
        this.dependencies.push(d);
      }
    }
  }

  /**
   * Build the working operation map (durations, pins). Placement dates start
   * null and are filled by forward-ASAP placement in selectWorkCenters();
   * a pinned op keeps only its stored dueDate — the need-by target it owns
   * (spec 2026-08-15 dual dates). The backward need-by pass (computeNeedBys)
   * runs separately and never feeds placement. Conflicts are counted after
   * placement, not here.
   */
  async calculateDates(): Promise<void> {
    this.scheduledOperations = buildScheduledOperations(this.operations);
  }

  /**
   * The ONE availability-windows fetch for this run — work-center windows
   * (selection candidates + current assignments) plus the location's default
   * calendar — memoized so the backward need-by pass and buildFiniteContext
   * share the same load instead of reading the provider twice.
   */
  private async loadAvailabilityWindows(): Promise<AvailabilityWindows> {
    if (this.availabilityWindows) {
      return this.availabilityWindows;
    }
    this.availabilityWindows = await loadAvailabilityWindows({
      provider: this.provider,
      workCenterSelector: this.workCenterSelector,
      operations: Array.from(this.scheduledOperations.values()),
      locationId: this.job?.locationId ?? null,
      now: this.now
    });
    return this.availabilityWindows;
  }

  /**
   * Backward need-by pass (spec 2026-08-15 dual dates): demand-anchored
   * targets walked back from the job's due date on the same calendar physics
   * as placement (shared windows fetch). The result is persisted to
   * jobOperation.dueDate by the location write and read by NOTHING in the
   * placement path — targets are outputs, never constraints.
   */
  private async computeNeedBys(): Promise<void> {
    this.needByByOperation = new Map();
    this.topologicalOrder = [];
    const operations = Array.from(this.scheduledOperations.values());
    if (operations.length === 0) {
      return;
    }

    const { workCenterAvailability, locationDefaultWindows } =
      await this.loadAvailabilityWindows();
    const { calendarHoursPerDay, workingDayTest } = calendarAdapters(
      workCenterAvailability,
      locationDefaultWindows,
      this.job?.timezone ?? "UTC"
    );

    // The graph only reads operation ids — strip the ScheduledOperation-only
    // fields (BaseOperation's optional priority vs the scheduled null).
    const graph = new DependencyGraphImpl(
      operations.map((op) => ({
        id: op.id,
        jobId: op.jobId,
        processId: op.processId
      })),
      this.dependencies
    );

    // Keep the graph's forward order for the behind-target attribution — the
    // one topological order the engine already owns; never invent a new sort.
    this.topologicalOrder = graph.topologicalSort("forward");

    this.needByByOperation = computeNeedByDates({
      operations,
      graph,
      jobDueDate: this.job ? committedDueDate(this.job) : null,
      calendarHoursPerDay,
      workingDayTest
    });
  }

  /**
   * Build the finite-capacity context: live reservations, per-process ability
   * requirements, and qualified-operator availability. Work centers are
   * finite (capacity 1 — one operation at a time, gated by actual
   * reservations); ability-gated operations additionally wait for a
   * qualified person to be on shift and unreserved. Runs just before
   * selection so the rebuilt dependency DAG is final.
   */
  private async buildFiniteContext(): Promise<FiniteSchedulingContext | null> {
    if (!this.workCenterSelector) {
      return null;
    }
    const availability = await this.loadAvailabilityWindows();
    return buildFiniteContext({
      provider: this.provider,
      operations: Array.from(this.scheduledOperations.values()),
      dependencies: this.dependencies,
      availability,
      locationId: this.job?.locationId ?? null,
      timeZone: this.job?.timezone ?? "UTC",
      now: this.now,
      excludeJobIds: this.excludeJobIds
    });
  }

  /**
   * Select work centers for all operations
   */
  async selectWorkCenters(): Promise<void> {
    if (!this.workCenterSelector) {
      log.warning("Work center selector not initialized", {
        jobId: this.jobId
      });
      return;
    }

    const finiteContext = await this.buildFiniteContext();
    if (finiteContext) {
      this.workCenterSelector.setFiniteContext(finiteContext);
    }

    const operations = Array.from(this.scheduledOperations.values());
    const selections =
      await this.workCenterSelector.selectWorkCentersForOperations(operations, {
        jobDueDate: this.job ? committedDueDate(this.job) : null,
        batchPlacements: this.batchPlacements
      });

    // Apply selections (placed timestamps → factory-day date columns)
    this.scheduledOperations = applyWorkCenterSelections(
      this.scheduledOperations,
      selections,
      this.job?.timezone ?? "UTC"
    );

    // Track affected work centers
    for (const selection of selections.values()) {
      if (selection.workCenterId) {
        this.affectedWorkCenters.add(selection.workCenterId);
      }
    }

    // Projected completion = the latest finish across ALL of this run's
    // placements: selection.placedEnd covers regular, pinned, and
    // outside-processing ops (pins place normally now); the planned
    // reservations are a belt-and-braces union over the same placements.
    let maxEndMs: number | null = null;
    const bump = (ms: number) => {
      if (maxEndMs === null || ms > maxEndMs) maxEndMs = ms;
    };
    for (const selection of selections.values()) {
      if (selection.placedEnd) bump(toInstantMs(selection.placedEnd));
    }
    for (const p of this.workCenterSelector.getPlannedReservations()) {
      if (p.endAt > p.startAt) bump(p.endAt);
    }
    this.projectedCompletionAt =
      maxEndMs === null ? null : msToInstantIso(maxEndMs);

    // Recount conflicts — finite allocation may add or resolve them
    this.conflictsDetected = 0;
    for (const op of this.scheduledOperations.values()) {
      if (op.hasConflict) {
        this.conflictsDetected++;
      }
    }
  }

  /**
   * Calculate priorities for all operations grouped by work center
   */
  /**
   * Per-work-center dispatch sequence = the forward-ASAP placement order
   * (reservation start ascending). One source of truth for what runs next.
   */
  async calculatePriorities(): Promise<void> {
    // Get all operations at affected work centers (not just from this job)
    const workCenterIds = Array.from(this.affectedWorkCenters);

    if (workCenterIds.length === 0) {
      // No work centers affected, just use job-level priorities
      const opsWithInfo: OperationWithJobInfo[] = [];
      for (const op of this.scheduledOperations.values()) {
        opsWithInfo.push(
          toOperationWithJobInfo(
            op,
            this.job?.priority ?? null,
            this.job?.deadlineType ?? null
          )
        );
      }

      const priorities = calculatePrioritiesByWorkCenter(opsWithInfo);
      this.scheduledOperations = applyPriorities(
        this.scheduledOperations,
        priorities
      );
      return;
    }

    // Get all active operations at affected work centers from OTHER jobs
    // (current job's operations aren't in DB yet with their new work centers)
    const allWcOps =
      await this.provider.getCrossJobOperationsAtWorkCenters(workCenterIds);

    // Build a set of operation IDs from the database query
    const dbOpIds = new Set(allWcOps.map((op) => op.id).filter(Boolean));

    // Dispatch-rule inputs: FIFO keys on createdAt, SPT/WSPT/CR/MinSlack on
    // durationHours — without them every rule silently degrades to the
    // legacy tie-break chain
    const toIsoOrNull = (value: Date | string | null | undefined) =>
      value ? toInstantIso(value) : null;

    // Start with operations from DB (other jobs at same work centers)
    const mergedOps: OperationWithJobInfo[] = allWcOps
      .filter((wcOp) => wcOp.id)
      .map((wcOp) => {
        const scheduled = this.scheduledOperations.get(wcOp.id!);
        if (scheduled) {
          // This is an operation from current job that was already in DB
          // (reschedule case) - use the newly calculated dates
          return {
            id: scheduled.id,
            dueDate: scheduled.dueDate ?? null,
            startDate: scheduled.startDate ?? null,
            priority: scheduled.priority,
            deadlineType: wcOp.deadlineType ?? "No Deadline",
            jobPriority: wcOp.jobPriority ?? 99,
            workCenterId: scheduled.workCenterId ?? null,
            durationHours: scheduled.durationHours ?? null,
            createdAt: toIsoOrNull(wcOp.createdAt),
            projectedCompletionAt: scheduled.projectedCompletionAt ?? null
          };
        }
        // Operation from another job - use DB data
        return {
          id: wcOp.id!,
          dueDate: wcOp.dueDate ?? null,
          startDate: wcOp.startDate ?? null,
          priority: wcOp.priority ?? 1,
          deadlineType: wcOp.deadlineType ?? "No Deadline",
          jobPriority: wcOp.jobPriority ?? 99,
          workCenterId: wcOp.workCenterId ?? null,
          durationHours: calculateDurationHours({
            jobId: "",
            processId: null,
            setupTime: wcOp.setupTime ?? undefined,
            setupUnit: wcOp.setupUnit ?? undefined,
            laborTime: wcOp.laborTime ?? undefined,
            laborUnit: wcOp.laborUnit ?? undefined,
            machineTime: wcOp.machineTime ?? undefined,
            machineUnit: wcOp.machineUnit ?? undefined,
            operationQuantity: wcOp.operationQuantity
          }),
          createdAt: toIsoOrNull(wcOp.createdAt),
          projectedCompletionAt: toIsoOrNull(wcOp.projectedCompletionAt)
        };
      });

    // Add current job's scheduled operations that aren't in DB yet
    // (their workCenterId was just assigned in memory)
    for (const op of this.scheduledOperations.values()) {
      if (!dbOpIds.has(op.id) && op.workCenterId) {
        mergedOps.push({
          id: op.id,
          dueDate: op.dueDate ?? null,
          startDate: op.startDate ?? null,
          priority: op.priority,
          deadlineType:
            op.deadlineType ?? this.job?.deadlineType ?? "No Deadline",
          jobPriority: this.job?.priority ?? 99,
          workCenterId: op.workCenterId,
          durationHours: op.durationHours ?? null,
          createdAt: toIsoOrNull(op.createdAt),
          projectedCompletionAt: op.projectedCompletionAt ?? null
        });
      }
    }

    // Calculate priorities
    const priorities = calculatePrioritiesByWorkCenter(mergedOps);

    // Apply to our scheduled operations
    this.scheduledOperations = applyPriorities(
      this.scheduledOperations,
      priorities
    );
  }

  /**
   * Assign unlinked materials to the first operation of their make method
   */
  async assignMaterials(): Promise<void> {
    // Load all operations (including Done) to find first ops correctly
    const allOperations = await this.loadAllOperations();

    // Build assembly tree
    const assemblyTree = await this.loadAssemblyTree();
    if (!assemblyTree) {
      return;
    }

    // Get all jobMakeMethodIds
    const makeMethodIds =
      this.assemblyHandler.getAllJobMakeMethodIds(assemblyTree);

    // Materials that still need assignment: the stored ones, less those
    // initialize() already put on an operation in this run.
    const materials = (
      await this.provider.getUnassignedMakeToOrderMaterials(makeMethodIds)
    ).filter((m) => !m.id || !this.materialLinks.has(m.id));

    // Group non-rework operations by jobMakeMethodId
    const operationsByMethod = new Map<string, BaseOperation[]>();
    for (const op of allOperations) {
      if (op.jobMakeMethodId && !op.reworkId) {
        if (!operationsByMethod.has(op.jobMakeMethodId)) {
          operationsByMethod.set(op.jobMakeMethodId, []);
        }
        operationsByMethod.get(op.jobMakeMethodId)!.push(op);
      }
    }

    // Assign first operation of each method to its materials
    for (const material of materials) {
      if (!material.jobMakeMethodId) continue;

      const methodOps = operationsByMethod.get(material.jobMakeMethodId) ?? [];
      const sortedOps = [...methodOps].sort(
        (a, b) => (a.order ?? 0) - (b.order ?? 0)
      );
      const firstOpId = sortedOps[0]?.id;
      if (!firstOpId || !material.id) continue;
      this.materialLinks.set(material.id, firstOpId);
    }
  }

  /**
   * Collect everything this run wants stored.
   */
  private buildWrites(): void {
    // Zero-duration operations (all times = 0) place a start === end slot,
    // which occupies no capacity and violates the endAt > startAt check.
    const planned = (
      this.workCenterSelector?.getPlannedReservations() ?? []
    ).filter((p) => p.endAt > p.startAt);

    // Newly-late = the job WAS on time (or unforecast) and its new projected
    // business day now exceeds the due date. Edge-triggered by construction, so
    // a second identical regen produces no entry. Jobs with no due date are
    // never late. Computed on the FACTORY calendar (location tz).
    const dueDate = this.job ? committedDueDate(this.job) : null;
    const tz = this.job?.timezone ?? "UTC";
    if (dueDate && this.projectedCompletionAt) {
      const priorProjected = this.job?.projectedCompletionAt ?? null;
      const newBusinessDay = businessDay(this.projectedCompletionAt, tz);
      const priorBusinessDay = priorProjected
        ? businessDay(priorProjected, tz)
        : null;
      const wasOnTime =
        priorBusinessDay === null || priorBusinessDay <= dueDate;
      this.newlyLate = wasOnTime && newBusinessDay > dueDate;
    } else {
      this.newlyLate = false;
    }

    const placements = placementWrites({
      scheduled: this.scheduledOperations.values(),
      originals: this.operations,
      needByByOperation: this.needByByOperation
    });

    this.writes = {
      jobId: this.jobId,
      jobStatus: this.job?.status ?? null,
      materialLinks: [...this.materialLinks].map(
        ([materialId, jobOperationId]) => ({ materialId, jobOperationId })
      ),
      dependencies: this.dependencyWrite,
      readyOperationIds: this.readyOperationIds,
      placements,
      reservations: planned,
      projectedCompletionAt: this.projectedCompletionAt
    };
    this.reservationsWritten = planned.length;
  }

  /** What this run wants stored; available after run(). */
  getWrites(): JobWrites {
    if (!this.writes) throw new Error("getWrites() called before run()");
    return this.writes;
  }

  /**
   * Get the scheduling result
   */
  getResult(): SchedulingResult {
    return {
      success: true,
      operationsScheduled: this.scheduledOperations.size,
      conflictsDetected: this.conflictsDetected,
      workCentersAffected: Array.from(this.affectedWorkCenters),
      assemblyDepth: this.assemblyDepth,
      reservationsWritten: this.reservationsWritten
    };
  }

  /** Forecast finish (max placed end) after a run; null when no operations. */
  getProjectedCompletionAt(): string | null {
    return this.projectedCompletionAt;
  }

  /** True when this run flipped the job on-time (or unforecast) → late. */
  isNewlyLate(): boolean {
    return this.newlyLate;
  }

  getReadableJobId(): string | null {
    return this.job?.readableJobId ?? null;
  }

  getAssignee(): string | null {
    return this.job?.assignee ?? null;
  }

  /**
   * Job-level behind-target attribution (spec 2026-08-15 dual dates). Only
   * when the JOB's verdict is late — the same judgment buildWrites uses
   * for newly-late: projected finish past the due date on the FACTORY
   * calendar — walk the operations in topological order and name the first
   * one whose projected finish misses its backward need-by target. Purely
   * informational: it rides the job-level cause sentence and never sets
   * per-op conflicts (targets are outputs, not constraints).
   */
  private composeBehindTargetSentence(): string | null {
    const dueDate = this.job ? committedDueDate(this.job) : null;
    if (!dueDate || !this.projectedCompletionAt) return null;
    const tz = this.job?.timezone ?? "UTC";
    if (businessDay(this.projectedCompletionAt, tz) <= dueDate) return null;

    const operations: BehindTargetOperation[] = [];
    for (const opId of this.topologicalOrder) {
      const op = this.scheduledOperations.get(opId);
      if (!op) continue;
      operations.push({
        description: op.description ?? null,
        needBy: this.needByByOperation.get(opId) ?? null,
        projectedCompletionAt: op.projectedCompletionAt ?? null
      });
    }
    return composeBehindTarget(operations, tz);
  }

  /**
   * The binding-resource explanation for this job's timing — the first
   * conflict reason if any, else the first placement's schedule note. Feeds the
   * expedite "best case" bottleneck sentence. When the job's verdict is late,
   * the behind-target attribution ("First behind target: …") is appended so
   * the sentence also names WHERE the plan first falls behind its targets.
   */
  getCause(): string | null {
    let cause: string | null = null;
    for (const op of this.scheduledOperations.values()) {
      if (op.hasConflict && op.conflictReason) {
        cause = op.conflictReason;
        break;
      }
    }
    if (!cause) {
      for (const p of this.workCenterSelector?.getPlannedReservations() ?? []) {
        if (p.scheduleNote) {
          cause = p.scheduleNote;
          break;
        }
      }
    }
    const behindTarget = this.composeBehindTargetSentence();
    if (!behindTarget) return cause;
    return cause ? `${cause}. ${behindTarget}` : behindTarget;
  }

  /**
   * Run the full scheduling process. Nothing is written: the forecast is
   * computed in memory and the caller stores getWrites() — or does not (the
   * expedite what-if).
   */
  async run(): Promise<SchedulingResult> {
    await this.initialize();

    // Assign materials BEFORE creating dependencies
    // Dependencies require jobMaterial.jobOperationId to be set
    // to link subassembly operations to parent operations
    await this.assignMaterials();
    await this.createDependencies();

    await this.calculateDates();
    // Backward need-by targets BEFORE placement — shares the placement pass's
    // availability windows and influences it in no way (targets are outputs).
    await this.computeNeedBys();
    await this.selectWorkCenters();
    await this.calculatePriorities();

    this.buildWrites();

    return this.getResult();
  }
}