scheduling

type AllocationResult struct {
	Allocations []OrderAllocation
	Uncovered   []UncoveredRequirement
}

type AppliedOverride struct {
	OverrideID string    `json:"override_id"`
	ItemID     string    `json:"item_id"`
	MonthStart time.Time `json:"month_start"`
	Before     float64   `json:"before"`
	After      float64   `json:"after"`
	TypeCode   string    `json:"adjustment"`
	ReasonCode string    `json:"reason"`
}

type AtRiskOrder struct {
	SalesOrderID     string  `json:"sales_order_id"`
	SalesOrderNumber string  `json:"sales_order_number"`
	ItemID           string  `json:"item_id"`
	SKU              string  `json:"sku"`
	Units            float64 `json:"units"`
	DueWeek          int     `json:"due_week"`
	// Reason is why the promise is at risk: `past_due` (the constraint stage needed to start before the horizon), `undated` (no commitment was ever recorded), or `short` (the plan projects less stock than the order needs in its week).
	Reason string `json:"reason"`
}

type BacklogBucket struct {
	// Label names the band; MinDaysLate and MaxDaysLate bound it, with MaxDaysLate zero meaning unbounded.
	Label       string
	MinDaysLate int
	MaxDaysLate int
	OrderCount  int
	Units       float64
}

type BatchMeasurement struct {
	BatchID          string
	ItemID           string
	SKU              string
	ScannedAt        time.Time
	Quantity         float64
	ProductionStepID string
	MachineID        string
	MachineName      string
	UnitCost         float64

	// LaborTimeValue is the production step's labor time in LaborTimeUnit per unit.
	LaborTimeValue float64
	LaborTimeUnit  string
	LaborRate      float64
	OverheadRate   float64

	// RunCreatedAt is when the production run was opened; paired with ScannedAt it gives the observed lead time for this batch.
	RunCreatedAt *time.Time
}

type Calendar struct {
	// OpenDays is indexed by ISO weekday, Monday at 0 through Sunday at 6.
	OpenDays [dayMaskLength]bool
	// Closures are dated shutdowns — holidays, shutdown weeks — keyed on the UTC-truncated date.
	Closures map[time.Time]struct{}
}

type Calendars struct {
	// Receive is the days the customer's dock accepts freight.
	Receive Calendar
	// Carrier is the days the carrier moves freight. Transit is counted in these.
	Carrier Calendar
	// Ship is the days the plant tenders freight.
	Ship Calendar
	// ShipCutoff is the local time freight has to be tendered by, as "15:00". Empty when the plant has not set one, in which case a ship-by date carries no time of day.
	ShipCutoff string
	// ShipLocation is the zone ShipCutoff is read in. Nil falls back to UTC.
	ShipLocation *time.Location
}

type Campaign struct {
	ItemID    string
	SKU       string
	MachineID string
	WeekIndex int
	Units     float64
	Lots      int
	// LotUnits is the granularity the campaign was sized at, carried onto the plan so releasing the week to the floor splits into exactly the lots that were planned.
	LotUnits float64
	// LotUnitID is what the lot is counted in — pairs for sock greige, eaches for armsleeve greige. Without it a 60 on the plan cannot be reconciled with a 60 on the floor.
	LotUnitID string
	RunHours  float64
}

type Changeover struct {
	// contains filtered or unexported fields
}

type ClassificationInput struct {
	ItemID string
	SKU    string

	// Monthly is the item's demand history, one entry per month with demand. Months with none may be absent; MonthsObserved is the window they were drawn from.
	Monthly        []float64
	MonthsObserved int
	// MonthsSinceLastSale is how long since anything sold. Negative means nothing ever has.
	MonthsSinceLastSale int

	AnnualDemand float64
	UnitCost     float64

	// TotalProductionLeadTimeWeeks is constraint plus finishing: how long from deciding to build to having sellable stock.
	TotalProductionLeadTimeWeeks float64

	Customers []CustomerDemand

	// CurrentPolicy is what the item is planned as today, so the recommendation can say whether anything would change.
	CurrentPolicy string
}

type Closure struct {
	Date time.Time
	Name string
}

type Commitment struct {
	ShipByDate   time.Time
	LeadTimeDays int
	Source       string
	// TransitDays is the carrier transit subtracted to get ShipByDate, nil when transit was unknown or did not apply.
	TransitDays *int
	// TransitSource names where TransitDays came from, empty when TransitDays is nil.
	TransitSource string
	// ShipByCutoffAt is ShipByDate at the plant's pickup cutoff, as an instant. The date alone says which day freight has to leave; this says by when, which is the deadline a shop floor actually works to. Nil when the ship calendar carries no cutoff.
	ShipByCutoffAt *time.Time
	// CalendarAdjustmentDays is how many days the receiving and shipping calendars pulled ShipByDate back beyond what transit alone accounted for. Zero when every date already landed on an open day, and the one number that answers "why the 24th and not the 27th".
	CalendarAdjustmentDays int
	// Steps is the ordered derivation, one entry per rule that touched the date. Built on the way through so a preview and the stamped commitment are produced by the same walk and cannot disagree about how a date was reached.
	Steps []CommitmentStep
}

type CommitmentBasis struct {
	// PromisedAt is a promised *delivery* date. The order has to leave early enough for the carrier to cover the lane, so this is the only basis transit is subtracted from.
	PromisedAt *time.Time
	// LeadTimeOverrideDays is this order's own lead time in days, replacing whatever the customer chain would have resolved to.
	LeadTimeOverrideDays *int
	// ShipByOverrideDate pins the ship date itself, bypassing transit and the receiving calendar.
	ShipByOverrideDate *time.Time
}

type CommitmentStep struct {
	// Code names the rule that applied.
	Code string
	// Date is where the running date stood after this rule.
	Date time.Time
	// DaysMoved is how far this rule pulled the date back. Zero means the rule applied and changed nothing, which is worth reporting: it says the promised date was already a day the customer receives.
	DaysMoved int
	// Detail carries the rule's own parameter — the transit days counted, the cutoff time applied — for a caller rendering an explanation.
	Detail string
}

type CustomerDemand struct {
	CustomerAccountID string
	CustomerName      string
	Units             float64
	// LeadTimeDays is what this customer is committed to, resolved through the same chain an order is stamped from.
	LeadTimeDays int
	// FulfillmentPolicy is how this customer buys, when they say. Empty means they express no preference.
	FulfillmentPolicy string
}

type DeliveryBreakdown struct {
	Key   string
	Label string
	DeliveryPerformance
}

type DeliveryBreakdownKey struct {
	Key   string
	Label string
}

type DeliveryOutcome struct {
	SalesOrderID     string
	SalesOrderNumber string
	BuyerAccountID   string
	CustomerName     string

	// CustomerGroupID and SalesRepID are empty when the order carries no such association; a breakdown files those under "Unassigned" rather than dropping them.
	CustomerGroupID   string
	CustomerGroupName string
	SalesRepID        string

	// ProductLines is every distinct product line on the order. An order spanning two lines is counted under both, because a late order is late for every line on it.
	ProductLines []ProductLineRef

	ShipByDate time.Time
	IssuedAt   *time.Time
	// FirstShipAt is nil for an order that has not shipped at all.
	FirstShipAt *time.Time

	QuantityOrdered float64
	QuantityPacked  float64

	// CommittedLeadTimeDays is what was promised; zero when the order predates commitment tracking.
	CommittedLeadTimeDays int
	// CommitmentSource names which rule produced the ship-by date — an explicitly promised date, the customer's lead time, their group's, or the account default. Empty for an order stamped before the source was recorded.
	CommitmentSource string
}

type DeliveryPerformance struct {
	// PeriodStart is the first day of the bucket; zero for the overall summary.
	PeriodStart time.Time

	CommittedOrderCount int
	ShippedOrderCount   int
	OnTimeOrderCount    int
	OnTimeInFullCount   int
	LateOrderCount      int
	// NotYetShippedCount is orders due in this period that have not shipped at all. They count against on-time, because a promise not yet met is not a promise kept.
	NotYetShippedCount int

	// Ratios are nil rather than zero when nothing was due, so a quiet week does not render as total failure.
	OnTimePct       *float64
	OnTimeInFullPct *float64

	// AverageDaysLate is measured over late orders only; nil when none were late. Averaging over every order would dilute a real problem into a number that looks fine.
	AverageDaysLate *float64
	// AverageLeadTimeDays is how long shipped orders actually took, and AverageCommittedLeadTimeDays what they were promised. The gap between them is what a merchant renegotiates on.
	AverageLeadTimeDays          *float64
	AverageCommittedLeadTimeDays *float64
}

type DemandInput struct {
	AsOf         time.Time
	BasisCode    string
	ForecastZ    float64
	WeeksPerYear int
	// ForecastMonths is how far forward to project when using the seasonal-EMA basis.
	ForecastMonths int

	// MonthlyByItem is monthly demand per constraint item, already pooled from the finished goods that item becomes. Series need not be dense.
	MonthlyByItem map[string][]MonthlyDemand
	// DownstreamByItem is the per-finished-good series behind each constraint item, needed to compute the downstream sigma sum separately from the pooled one.
	DownstreamByItem map[string][]FinishedGood

	Overrides []DemandOverride
	// ItemsByProductLine resolves a product-line-scoped override onto items.
	ItemsByProductLine map[string][]string
}

type DemandOverride struct {
	ID          string
	ScopeCode   string
	ScopeRefID  string
	PeriodStart time.Time
	PeriodEnd   time.Time
	TypeCode    string
	Value       float64
	ReasonCode  string
	CreatedAt   time.Time
}

type DerivedLine struct {
	SourceLineID   string
	ProductionStep string
	DepartmentID   string
	ItemID         string
	SKU            string
	// WeekIndex is the constraint week plus the accumulated lead-time offset.
	WeekIndex int
	Quantity  float64
	// Depth is how many steps downstream of the constraint this work sits, which is what a readiness chip keys off. Zero is the constraint step itself.
	Depth int
}

type Diagnostics struct {
	LevellingDiagnostics
	AppliedOverrides []AppliedOverride `json:"applied_overrides"`
	// ChangeoverSlopeMinutes is the calibrated minutes per additional input.
	ChangeoverSlopeMinutes float64 `json:"changeover_slope_minutes"`
	AverageInputsAdded     float64 `json:"average_inputs_added"`
	// ItemsWithoutRunRate never got a measured seconds-per-unit and cannot be scheduled; they are reported rather than silently dropped.
	ItemsWithoutRunRate []string `json:"items_without_run_rate"`
	ExcludedItemCount   int      `json:"excluded_item_count"`

	// FirmDemandUnits is the whole open order book expressed at the constraint. Zero means the plan is forecast-only.
	FirmDemandUnits float64 `json:"firm_demand_units"`
	// UndatedFirmOrderCount is how many open orders carry no ship-by commitment and were dated at the front of the horizon. A non-zero count means orders predating commitment tracking still need backfilling.
	UndatedFirmOrderCount int `json:"undated_firm_order_count"`
	// MakeToOrderItemCount is how many planned items are built only against the order book.
	MakeToOrderItemCount int `json:"make_to_order_item_count"`
	// AtRiskOrders are commitments this plan does not cover in time. This is the most actionable thing the solver produces: everything else describes what the plan does, and this says which promises it breaks.
	AtRiskOrders []AtRiskOrder `json:"at_risk_orders"`

	// ConstraintMachineCount is how many machines the constraint department contributed, and MeasuredBatchCount how much production history was found on them. A plan with machines but no history is empty for a reason a planner can act on — nothing has been scanned in the demand window — and saying so beats an empty grid.
	ConstraintMachineCount int `json:"constraint_machine_count"`
	MeasuredBatchCount     int `json:"measured_batch_count"`
	// MachinesWithoutStep have no production step, so their campaigns derive no downstream department work.
	MachinesWithoutStep int `json:"machines_without_step"`

	// Finishing is stage two's own account of itself: what it could not make, and why.
	Finishing FinishingDiagnostics `json:"finishing"`
	// FinishingMachineCount is how many machines the second stage was sized from. Zero means its capacity was estimated from the shift pattern alone.
	FinishingMachineCount int `json:"finishing_machine_count"`
	// FinishingCapacityIsEstimated says the plant has no machines outside the constraint department, so stage two was sized as a single notional resource rather than counted. A levelled plan against a guessed capacity is worth flagging as such.
	FinishingCapacityIsEstimated bool `json:"finishing_capacity_is_estimated"`
}

type ExplosionCampaign struct {
	LineID    string
	ItemID    string
	SKU       string
	MachineID string
	WeekIndex int
	Quantity  float64
	// StepID is where the campaign runs — the constraint step the walk starts from.
	StepID string
}

type ExplosionInput struct {
	// Campaigns are the constraint-level lines the plan already committed to.
	Campaigns []ExplosionCampaign
	Edges     []StepEdge
	Steps     map[string]StepInfo
	MaxDepth  int
}

type FinishedGood struct {
	ItemID        string
	SKU           string
	ProductLineID string
	Monthly       []MonthlyDemand
	OnHand        float64
}

type FinishedGoodDemand struct {
	ItemID        string
	SKU           string
	ProductLineID string
	AnnualDemand  float64
	SigmaWeekly   float64
	OnHand        float64
}

type FinishedPolicy struct {
	ItemID        string
	SKU           string
	GreigeItemID  string
	GreigeSKU     string
	ProductLineID string

	AnnualDemand float64
	WeeklyDemand float64
	SigmaWeekly  float64

	// Sized against the finishing lead time, not the knit lead time: this stock is replenished by finishing, not by the constraint.
	SafetyStock  float64
	ReorderPoint float64
	OnHand       float64
	WeeksOfCover float64
}

type FinishingDiagnostics struct {
	WeeklyCapacityHours float64   `json:"weekly_capacity_hours"`
	PlannedHoursByWeek  []float64 `json:"planned_hours_by_week"`
	// UtilisationByWeek is planned hours over capacity. Nil entries are impossible here — capacity is constant across the horizon — but a zero-capacity input yields zeroes rather than infinities.
	UtilisationByWeek []float64 `json:"utilisation_by_week"`
	// GreigeStarvedSKUs wanted building and had no greige to build from.
	GreigeStarvedSKUs []string `json:"greige_starved_skus"`
	// CapacityStarvedSKUs had greige and no hours.
	CapacityStarvedSKUs []string `json:"capacity_starved_skus"`
	// ItemsWithoutRunRate never got a measured finishing rate and cannot be levelled.
	ItemsWithoutRunRate []string `json:"items_without_run_rate"`
	// UnusedGreigeUnits is stage-one output the horizon never converts. A large number means the two stages are planned against different demand, which is worth surfacing rather than leaving as an unexplained pile of greige.
	UnusedGreigeUnits float64 `json:"unused_greige_units"`
	TotalPlannedUnits float64 `json:"total_planned_units"`
	LineCount         int     `json:"line_count"`
}

type FinishingInput struct {
	Items  []FinishingItem
	Supply []FinishingSupply
	// GreigeOnHand is what is already knitted and waiting when the horizon opens. Without it the first weeks of every plan would read as starved while the greige store sat full.
	GreigeOnHand map[string]float64
	// WeeklyCapacityHours is the whole second stage's capacity in one week.
	WeeklyCapacityHours float64
	Settings            Settings
}

type FinishingItem struct {
	ItemID string
	SKU    string
	// GreigeItemID names the stage-one item this is made from. It is what ties the two schedules together: a finished SKU cannot be built in a week the greige it comes from has not arrived in.
	GreigeItemID  string
	GreigeSKU     string
	ProductLineID string

	// WeeklyDemand and OnHand are this SKU's own, not the family's. The pooled figures behind the knit plan cannot answer "is this colourway short", which is the whole question stage two exists to answer.
	WeeklyDemand float64
	OnHand       float64
	ReorderPoint float64
	SafetyStock  float64

	// SecondsPerUnit is the measured finishing run rate. Without one the SKU cannot be levelled, because there is no way to know what an hour of the department buys.
	SecondsPerUnit float64
	LotUnits       float64
	LotUnitID      string
	UnitID         string

	// GreigePerUnit is how much stage-one output one finished unit consumes. One unless a yield ratio says otherwise; a finishing loss makes it greater than one.
	GreigePerUnit float64

	// ProductionStepID and DepartmentID are where the SKU is made. The sweep does not decide with them — the second stage is one pool — but the plan line carries them so a department rollup needs no join.
	ProductionStepID string
	DepartmentID     string

	// FirmByWeek is the order book at this SKU, by the week it is owed.
	FirmByWeek    []float64
	IsMakeToOrder bool
}

type FinishingLine struct {
	ItemID       string
	SKU          string
	GreigeItemID string
	GreigeSKU    string
	WeekIndex    int

	Quantity  float64
	Lots      int
	LotUnits  float64
	LotUnitID string
	RunHours  float64
	// GreigeConsumed is what this line takes out of the stage-one buffer, which is what makes the two schedules reconcilable.
	GreigeConsumed float64
	// FirmUnits is how much of the week's draw was an order rather than a forecast, so a planner can see which lines are promises.
	FirmUnits float64

	// ProductionStepID and DepartmentID name where the work runs.
	ProductionStepID string
	DepartmentID     string

	ProjectedOnHandBefore float64
	ProjectedOnHandAfter  float64
}

type FinishingResult struct {
	Lines []FinishingLine
	// ProjectedOnHand[itemID][weekIndex] is the finished SKU's position at the end of that week.
	ProjectedOnHand map[string][]float64
	Diagnostics     FinishingDiagnostics
}

type FinishingStep struct {
	ProductionStepID string
	DepartmentID     string
}

type FinishingSupply struct {
	GreigeItemID string
	WeekIndex    int
	Quantity     float64
}

type FirmRequirement struct {
	// ItemID is the constraint item, not the finished good: the requirement has already been pooled onto whatever the plan actually builds.
	ItemID string
	// FinishedItemID is the finished good the order was placed for, kept so an at-risk order can name the SKU rather than the greige behind it.
	FinishedItemID string

	SalesOrderID     string
	SalesOrderNumber string
	SalesOrderLineID string

	// Units is the outstanding quantity in the constraint item's own unit.
	Units float64

	// ShipByWeek is the horizon week the finished good must exist in. Negative means the commitment is already behind the plan.
	ShipByWeek int
	// DueWeek is when the constraint stage must finish for the finishing lead time to still make ShipByWeek. Clamped at zero.
	DueWeek int

	// IsPastDue is set when the constraint stage would have had to start before the plan does. The clamp to week 0 hides that, so it is recorded rather than inferred from DueWeek.
	IsPastDue bool
	// IsUndated marks an order with no ship-by commitment, dated at the start of the horizon because it is issued and unshipped. Reported separately so a planner can tell a real promise from a guess.
	IsUndated bool
}

type FirmSchedule struct {
	// ByItemWeek[itemID][weekIndex] is the firm quantity due from the constraint stage in that week.
	ByItemWeek map[string][]float64
	// Requirements is the flat list, sorted, for diagnostics and at-risk reporting.
	Requirements []FirmRequirement
	// TotalUnits is the whole order book expressed at the constraint.
	TotalUnits float64
	// UndatedCount is how many requirements had no ship-by commitment.
	UndatedCount int
	// PastDueCount is how many needed the constraint stage to start before the horizon.
	PastDueCount int
}

type FulfillmentResolution struct {
	Policy string
	Source string
}

type ItemDemand struct {
	ItemID string

	// AnnualDemand is the forward-looking annual run rate the policy uses.
	AnnualDemand float64
	// TrailingAnnual is the last twelve complete months, for comparison.
	TrailingAnnual float64
	// SigmaWeeklyPooled is the pooled weekly standard deviation at the constraint. Pooled as sqrt(sum of squares) because one constraint item feeds many finished SKUs whose variability partially cancels.
	SigmaWeeklyPooled float64
	// FinishedGoods is the per-SKU detail behind the pooled figures above.
	FinishedGoods []FinishedGoodDemand
	// SigmaDownstreamSum is the plain sum of downstream sigmas, used for the finished goods buffer where the risk does not pool.
	SigmaDownstreamSum float64
	DownstreamCount    int
}

type ItemMeasurement struct {
	ItemID string
	SKU    string

	// SecondsPerUnit is the run rate: how long one unit occupies the constraint.
	SecondsPerUnit float64
	UnitCost       float64
	// OverheadRate is the production step's machine burden. Production labor is deliberately NOT included: a changeover is worked by a technician on the single machine, so setup cost uses the dedicated changeover labor rate from settings instead of the thin per-machine-hour production allocation. Including both would double-count labor and inflate EOQ.
	OverheadRate float64

	// LotCount is how many batches were produced; the script treats one batch as one lot regardless of its quantity, and so does this.
	LotCount int
	Quantity float64

	// EligibleMachineID is the set of machines that have actually run this item. Empty means unconstrained.
	EligibleMachineID map[string]bool

	// MeasuredLeadTimeWeeks is the mean observed run-open to scan time. Zero when no usable samples existed, in which case the settings default applies.
	MeasuredLeadTimeWeeks float64
	LeadTimeSampleCount   int

	ProductionStepID string
}

type ItemPolicy struct {
	ItemID string
	SKU    string
	// UnitID is what every quantity in this policy is counted in. A reorder point of 2,508 is uninterpretable without it, and the policy exists whether or not the item won a slot this horizon — so it carries its own unit rather than borrowing one from a campaign that may not exist.
	UnitID string

	AnnualDemand   float64
	WeeklyDemand   float64
	SecondsPerUnit float64
	UnitCost       float64

	SetupCost   float64
	HoldingCost float64
	EOQUnits    float64

	// Lead times, in weeks.
	ConstraintLeadTimeWeeks float64
	FinishLeadTimeWeeks     float64

	// Two-echelon safety stock. The buffer is pooled at the constraint item because one greige feeds many finished SKUs, so their variability partially cancels (sigma_pooled = sqrt(sum of squares), not the sum). Finished goods keep a smaller per-SKU buffer for service.
	SigmaWeeklyPooled     float64
	SigmaDownstreamSum    float64
	SafetyStockPrimary    float64
	SafetyStockDownstream float64

	ReorderPoint float64
	OrderUpTo    float64

	// FulfillmentPolicy is how this item is produced, and PolicySource which rule decided. A make-to-order item holds no buffer and is built only against the order book.
	FulfillmentPolicy string
	PolicySource      string
	// FirmDemandUnits is what the order book already owes over the horizon; ForecastDemandUnits is what the forecast projects for the same window. Split so a planner can see which drove a campaign.
	FirmDemandUnits     float64
	ForecastDemandUnits float64

	OnHandEchelon float64
	// OnHandGreige is the constraint stage on its own. The echelon figure is what the build decision is made against; this is what is actually in the greige store, which a pooled total cannot be decomposed back into.
	OnHandGreige float64
	// Greige-stage holding: the buffer plus half a campaign on average, and a whole campaign at the peak. Finished safety stock is held as finished goods and counted on the finished policies, so the two stages sum to network storage without double-counting.
	AverageGreigeInventory float64
	MaxGreigeInventory     float64
	WeeksOfCover           float64
	ABCClass               string
}

type LatenessBucket struct {
	Label       string
	MinDaysLate int
	MaxDaysLate int
	OrderCount  int
	// ShippedCount is how many of these have since shipped. The remainder are still owed, and are the same orders the backlog aging counts.
	ShippedCount int
	// Units is what was still unpacked across the band's orders.
	Units float64
}

type LeadTimeInput struct {
	// CustomerLeadTimeDays is the customer's own commitment, from account_relation.
	CustomerLeadTimeDays *int
	// ParentCustomerLeadTimeDays is the parent account's commitment, inherited by every child that has not set its own. One level: the parent's own parent is not consulted, matching how a child inherits its parent's prices.
	ParentCustomerLeadTimeDays *int
	// AccountGroupLeadTimeDays is inherited by every customer in the group that has not set its own.
	AccountGroupLeadTimeDays *int
	// AccountLeadTimeDays is the account-wide default, the last fallback.
	AccountLeadTimeDays *int
}

type LevellingDiagnostics struct {
	// EOQCappedSKUs had their economic lot size reduced to fit one machine-week, meaning shorter and more frequent campaigns than the policy would prefer.
	EOQCappedSKUs []string `json:"eoq_capped_skus"`
	// UnschedulableSKUs cannot fit even a single minimum lot into a machine-week. They are never scheduled, so expect stockouts.
	UnschedulableSKUs []string `json:"unschedulable_skus"`
	// CapacityStarvedSKUs are below their reorder point but never won a slot in the horizon. This is the honest signal that the plant is short of capacity.
	CapacityStarvedSKUs []string `json:"capacity_starved_skus"`
}

type LevellingItem struct {
	Policy            ItemPolicy
	EligibleMachineID map[string]bool
	// LotUnits is the rounding granularity for this item (a doff, a pallet).
	LotUnits float64
	// LotUnitID is what that granularity is counted in.
	LotUnitID string
	// FirmByWeek is the dated order book for this item, indexed by week. Nil when nothing is on order, which is the case the plan behaved as before this existed.
	FirmByWeek []float64
}

type LevellingResult struct {
	Campaigns   []Campaign
	Diagnostics LevellingDiagnostics
	// ProjectedOnHand[itemID][weekIndex] is the position at the END of that week, after that week's campaigns land and that week's demand is drawn down.
	ProjectedOnHand map[string][]float64
}

type LotDefault struct {
	Quantity float64
	UnitID   string
	// Source explains which rule produced this lot, so a plan can say why it is knitting in sixties. Values: item_override, product_line, downstream_product_line, account_default.
	Source string
	// ProductLineID is the line the convention came from, empty for the account default.
	ProductLineID string
}

type LotResolutionInput struct {
	// ItemOverrides are per-item lot sizes set by hand. They carry no unit — an override changes how big a lot is, not what it is counted in.
	ItemOverrides map[string]float64
	// ProductLineByItem maps an item to the line it sells under. Intermediate items — greige — are absent, which is what makes downstream inheritance necessary.
	ProductLineByItem map[string]string
	// LotByProductLine is the configured convention per line.
	LotByProductLine map[string]ProductLineLot
	// DownstreamByItem is what each planned item becomes, used to inherit a lot for greige that has no product line of its own.
	DownstreamByItem map[string][]FinishedGood
	// AccountLotUnits is the account-wide fallback size.
	AccountLotUnits float64
	// UnitByItem is each item's own counting unit, used for the account fallback where there is no product line to take a unit from.
	UnitByItem map[string]string
}

type Machine struct {
	ID   string
	Name string
}

type MonthlyDemand struct {
	MonthStart time.Time
	Quantity   float64
}

type OpenOrderLine struct {
	SalesOrderID     string
	SalesOrderNumber string
	// SalesOrderLineID is the line the quantity is owed against, which is what a shipment is measured against later.
	SalesOrderLineID string
	// FinishedItemID is the item the order was placed for.
	FinishedItemID string
	// ConstraintItemID is the item in the plan that produces it. Empty means nothing planned produces this order, and the line is dropped.
	ConstraintItemID string
	// Units is already scaled into the constraint item's unit by the caller, the same way pooled historical demand is.
	Units float64
	// ShipByDate is nil for an order issued before commitments were tracked.
	ShipByDate *time.Time
}

type OrderAllocation struct {
	ItemID string
	// CampaignWeek and CampaignMachineID identify the campaign; the caller maps them back onto the line it wrote.
	CampaignWeek      int
	CampaignMachineID string

	SalesOrderID     string
	SalesOrderNumber string
	SalesOrderLineID string
	Units            float64
}

type PinnedCampaign struct {
	ItemID    string
	MachineID string
	WeekIndex int
	Units     float64
}

type PolicyInput struct {
	ItemID string
	SKU    string

	AnnualDemand   float64
	SecondsPerUnit float64
	UnitCost       float64

	// OverheadRate is the step's machine burden. Setup cost adds the dedicated changeover labor rate from settings on top; production labor is excluded.
	OverheadRate float64

	// MeasuredLeadTimeWeeks is the observed constraint-step lead time; zero means unmeasured, in which case the settings default applies.
	MeasuredLeadTimeWeeks float64

	SigmaWeeklyPooled  float64
	SigmaDownstreamSum float64
	OnHandEchelon      float64
	OnHandGreige       float64

	// FulfillmentPolicy decides whether this item carries a statistical buffer at all. Empty means make-to-stock, so a caller that has not adopted policies gets the behaviour it had before they existed.
	FulfillmentPolicy string
	PolicySource      string
	// FirmDemandUnits and ForecastDemandUnits are carried through onto the policy for reporting; neither changes the arithmetic.
	FirmDemandUnits     float64
	ForecastDemandUnits float64
}

type PolicyResolutionInput struct {
	// ItemOverrides are explicit per-item policies.
	ItemOverrides map[string]string
	// ProductLineByItem maps an item to the line it sells under. Intermediate items are absent.
	ProductLineByItem map[string]string
	// PolicyByProductLine is the default configured on each line.
	PolicyByProductLine map[string]string
	// AccountDefault is the last resort; empty means make-to-stock.
	AccountDefault string
	// DownstreamByItem is what each planned item becomes, so an intermediate can inherit the policy of the finished goods it turns into.
	DownstreamByItem map[string][]FinishedGood
}

type ProductLineLot struct {
	ProductLineID string
	Quantity      float64
	UnitID        string
}

type ProductLineRef struct {
	ID   string
	Name string
}

type Recommendation struct {
	ItemID string
	SKU    string

	CurrentPolicy     string
	RecommendedPolicy string
	// Reason is the rule that decided. Exactly one, because the rules are ordered and the first match wins — listing every rule that happened to agree would obscure which one actually drove it.
	Reason string

	// The measurements behind the verdict, reported so a planner can disagree with the rule rather than only with the answer.
	AverageDemandInterval  float64
	CoefficientOfVariation float64
	TopCustomerSharePct    float64
	TopCustomerName        string
	// DemandWeightedLeadTimeDays is what customers are promised on average, weighted by how much they buy.
	DemandWeightedLeadTimeDays float64
	AnnualCOGS                 float64
	MonthsSinceLastSale        int
}

type RecommendationThresholds struct {
	// DormantMonths is how long without a sale before an item counts as dead.
	DormantMonths int
	// ConcentrationPct is the share of demand one customer must hold to count as the only customer.
	ConcentrationPct float64
	// ADIThreshold and CV2Threshold are the Syntetos-Boylan cut points separating smooth demand from lumpy.
	ADIThreshold float64
	CV2Threshold float64
	// SlowMoverCOGS is the annual cost of goods below which an item is a slow mover.
	SlowMoverCOGS float64
	// HighValueUnitCost is the unit cost above which holding stock is expensive.
	HighValueUnitCost float64
}

type Settings struct {
	// Horizon
	HorizonWeeks int `json:"horizon_weeks"` // HORIZON_WEEKS = 13
	FrozenWeeks  int `json:"frozen_weeks"`
	// WeekStartDay is the weekday a horizon week begins on, 0 = Sunday through 6 = Saturday.
	WeekStartDay int `json:"week_start_day"`

	// Capacity
	ShiftsPerDay        int     `json:"shifts_per_day"`        // SHIFTS = 2
	HoursPerShift       float64 `json:"hours_per_shift"`       // HOURS_PER_SHIFT = 7
	WorkDaysPerWeek     int     `json:"work_days_per_week"`    // WORK_DAYS_WK = 5
	WeeksPerYear        int     `json:"weeks_per_year"`        // WEEKS_YR = 52
	CapacityHeadroomPct float64 `json:"capacity_headroom_pct"` // the 0.9 headroom reserved for changeover
	DefaultLotUnits     float64 `json:"default_lot_units"`     // AVG_DOFF = 60

	// Changeover
	ChangeoverAvgMinutes float64 `json:"changeover_avg_minutes"` // CO_AVG_MIN = 30
	ChangeoverMinMinutes float64 `json:"changeover_min_minutes"` // CO_MIN_MIN = 15
	ChangeoverMaxMinutes float64 `json:"changeover_max_minutes"` // CO_MAX_MIN = 90
	ChangeoverLaborRate  float64 `json:"changeover_labor_rate"`  // CHANGEOVER_LABOR_RATE = 20

	// Inventory policy
	HoldingRatePct                 float64 `json:"holding_rate_pct"`                   // HOLDING_RATE_PCT = 0.25
	ServiceLevelZ                  float64 `json:"service_level_z"`                    // SERVICE_Z = 1.645
	FinishLeadTimeWeeks            float64 `json:"finish_lead_time_weeks"`             // FINISH_LT_WEEKS = 6
	DefaultConstraintLeadTimeWeeks float64 `json:"default_constraint_lead_time_weeks"` // KNIT_LT_WEEKS_DEFAULT = 1.3
	MaxWeeksSupply                 float64 `json:"max_weeks_supply"`                   // MAX_WEEKS_SUPPLY = 12
	MaxFlowDepth                   int     `json:"max_flow_depth"`                     // MAX_FLOW_DEPTH = 10

	// Fulfillment commitments
	//
	// DefaultCustomerLeadTimeDays is the last fallback in the ship-by chain, behind the customer and its account group. It lives with the planning assumptions because it is what a make-to-order promise is measured against: the date it produces has to be the same date the plan is solved to.
	DefaultCustomerLeadTimeDays int `json:"default_customer_lead_time_days"`
}

type SolverInput struct {
	AccountID    string
	PlanningAsOf time.Time
	Settings     Settings

	Machines []Machine
	Batches  []BatchMeasurement

	// StepInputs maps a production step to the input items it consumes, which drives the changeover model.
	StepInputs map[string]map[string]bool

	// MonthlyByItem is demand pooled onto each constraint item from the finished goods it becomes; DownstreamByItem keeps the per-finished-good detail so the two safety-stock echelons can be computed separately and so each finished SKU's own target can be reported rather than only its contribution to the pool.
	MonthlyByItem    map[string][]MonthlyDemand
	DownstreamByItem map[string][]FinishedGood

	// OnHandByItem is echelon stock — the constraint item plus everything downstream of it — which is what the build decision is made against. GreigeOnHandByItem is the constraint stage on its own, which the echelon total cannot be decomposed back into once summed.
	OnHandByItem       map[string]float64
	GreigeOnHandByItem map[string]float64

	// MachinesWithoutStep is how many machines in the constraint department have no production step, and therefore derive no downstream work.
	MachinesWithoutStep int

	Overrides          []DemandOverride
	ItemsByProductLine map[string][]string

	// Fulfillment policy resolution. All empty means every item is make-to-stock, which is how the plan behaved before policies existed.
	ItemPolicyOverrides      map[string]string
	ProductLineByItem        map[string]string
	PolicyByProductLine      map[string]string
	DefaultFulfillmentPolicy string

	// OpenOrders is the order book the plan owes: outstanding quantities already pooled onto the constraint items that produce them. Empty means the plan is driven purely by forecast, which is how it behaved before the order book was read.
	OpenOrders []OpenOrderLine
	// HorizonStart is the first day of week 0, used to date the order book against the horizon.
	HorizonStart time.Time

	// ItemLotUnits overrides the default lot size for specific items.
	ItemLotUnits map[string]float64
	// LotDefaultByItem is the resolved lot each item is made in, size and unit together. Populated by the input load, which runs the whole precedence chain once.
	LotDefaultByItem map[string]LotDefault
	// ExcludedItemIDs are items the merchant has taken out of planning.
	ExcludedItemIDs map[string]bool

	// PinnedCampaigns are hand-edited campaigns already on the plan; the sweep plans around them rather than re-deriving them.
	PinnedCampaigns []PinnedCampaign

	DemandBasisCode string
	ForecastZ       float64
	ForecastMonths  int

	// Stage two: the rest of the factory. Empty means the plan stops at the constraint, which is how it behaved before the finishing stage existed.
	//
	// FinishingMachines is every machine outside the constraint department; their count is what the second stage's weekly capacity is derived from, so hiring a shift onto a new machine changes the plan the way it changes the plant.
	FinishingMachines []Machine
	// FinishingBatches is production history for the finished goods, measured anywhere outside the constraint department. It is where the second stage's run rates come from.
	FinishingBatches []BatchMeasurement
	// FinishingRateScaleByItem converts a finished good's measured seconds-per-unit into the unit the plan is denominated in — the greige's. A sock scanned in eaches and knitted in pairs finishes at twice its per-each rate per planned unit.
	FinishingRateScaleByItem map[string]float64
	// FinishingStepByItem is where each finished good is made, denormalized onto its plan line so a department rollup needs no join.
	FinishingStepByItem map[string]FinishingStep
	// FinishingLotByItem is the lot each finished good is made in. Absent means the SKU is planned unlotted.
	FinishingLotByItem map[string]LotDefault
}

type SolverOutput struct {
	SolverVersion string
	PlanningAsOf  time.Time

	Policies []ItemPolicy
	// FinishedPolicies is the per-finished-SKU decomposition of the pooled greige buffers in Policies. The two stages together are the whole inventory picture and do not overlap: greige holds its own buffer, finished goods hold theirs.
	FinishedPolicies []FinishedPolicy
	Campaigns        []Campaign
	// ProjectedOnHand[itemID][weekIndex] is the position at the end of that week.
	ProjectedOnHand map[string][]float64

	// Allocations say which campaign is building which order. Written alongside the plan so "what is this campaign for" and "is my order covered" are two readings of one answer.
	Allocations []OrderAllocation

	// FinishingLines are stage two: how many of which finished good to make from the knitted parts, week by week. Empty when the plant has no second stage configured.
	FinishingLines []FinishingLine
	// FinishingProjectedOnHand[itemID][weekIndex] is a finished SKU's own position at the end of that week, which the pooled greige projection cannot answer.
	FinishingProjectedOnHand map[string][]float64

	Diagnostics Diagnostics
}

type StepEdge struct {
	UpstreamStepID   string
	DownstreamStepID string
}

type StepInfo struct {
	StepID       string
	DepartmentID string
	Name         string
	// LeadTimeOffsetWeeks is how far after the constraint campaign this step runs. It is a whole number of weeks because a schedule is planned in weeks; sub-week precision here would imply a resolution the plan does not have.
	LeadTimeOffsetWeeks int
	// YieldRatio is units of this step's output per unit of its input. 1 means no gain or loss; 0.95 means a 5% loss at this step.
	YieldRatio float64
}

type Transit struct {
	Days   int
	Source string
}

type UncoveredRequirement struct {
	ItemID           string
	SalesOrderID     string
	SalesOrderNumber string
	DueWeek          int
	ShortUnits       float64
	// CoveredUnits is how much of it the plan does build, so a partly-covered order reads as partly covered rather than as a total miss.
	CoveredUnits float64
}