Vendor cost update

The cascade that protects margin

A vendor cost update is rarely a single-row change. A 5% butter increase from Bongards moves the landed cost on every assembly that uses butter, which moves the margin band on every active bid line containing those assemblies, which may breach the 22% gross margin floor on customer-facing quotes. This workflow encodes that cascade so Mike sees the second- and third-order impact before he says yes.

The contract lives in workflow_definitions WHERE workflow_type='vendor_cost_review'. Trigger is typically event (a new vendor invoice or RESTlet poll detects a price change), risk level 3, expected duration 20 minutes including Mike's review of the impact report.

The thing this workflow gets right that a manual spreadsheet doesn't: it walks the BOM graph. If Bongards Salted Butter is an ingredient in Right Start Breakfast Burrito and that's a component of the SY2026 NYC DOE bid, the workflow shows you that chain in one view.

Trigger conditions

• Vendor sends a new price list (typically quarterly for ingredient vendors).
• CME trailing-week price moves the Bongards butter peg outside the band.
• USDA entitlement allocation changes the net cost on a barrel cheddar line.
• Mike negotiates a new contract price on a phone call.
• Reconciliation cron detects a posted bill price differs from the master cost.

Bongards raises butter price 5%

The four beats

1. 01

   Detect the change (auto)

   vendor_last_cost_change compares the incoming cost to vendor_costs.current_cost. If the delta exceeds the per-item tolerance (default 0.5%), a row is written to proposed_actions with action_type='vendor_cost_update'.

   Reads vendor_costs

   Time ~150ms
2. 02

   Simulate the impact (auto)

   simulate_cost_increase walks the BOM graph from bom_components, recomputes each affected assembly_cost_rollup in memory (no writes), and joins to bid_lines + quote_lines to identify margin breaches. A structured impact report is attached to the proposed action.

   Reads bom_components, assembly_cost_rollup, bid_lines, quote_lines, pricing_master

   Time ~800ms for typical 14-assembly fanout
3. 03

   Propose + approve (HITL)

   Mike sees the impact report in /proposed-actions.html: cost delta, list of affected assemblies, list of margin-breach bid lines, recommended follow-ups. He approves or rejects. R560 atomic claim applies — no double-approve race.

   Writes proposed_actions.status

   HITL step 2
4. 04

   Apply + recompute (auto)

   propose_bulk_cost_basis writes the new cost to vendor_costs, appends to vendor_cost_history, runs recompute_assembly_cost_rollup on each affected assembly, and emits one vendor.cost_changed event plus an assembly.cost_recomputed event per assembly. Bid-line and quote-line flags are written to margin_breach_queue for follow-up workflows.

   Writes vendor_costs, vendor_cost_history, assembly_cost_rollup, margin_breach_queue, events

   Emits vendor.cost_changed

   Time ~3s for typical fanout

What's different after the workflow runs

• vendor_costs reflects the new price; vendor_cost_history has the audit row.
• Every dependent row in assembly_cost_rollup shows the new landed cost.
• Margin-breach bid lines and quotes are surfaced for Mike's next-day queue.
• Downstream subscribers (bid price update, customer quote) receive the event and can re-trigger.
• If Mike opts to push the cost back to NS, the vendor record update sibling workflow handles that.

What can go wrong and how to recover

Adjacent workflows + diagrams

Code paths + invariants