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

Dated trail · spot stale claims

Dated trail of when this doc was last touched, what changed, and what to look at if it feels stale.

The machine-readable spec

Canonical fields, table names, endpoint signatures. What code should match, what tests should assert. workflow_type · vendor_cost_update · risk_level · 3.

Inputs (required + optional)

D1 tables written

Endpoints called

Events fired

It broke at 2am — what now

Different from "how do I use this." This is the page Mike pulls up when something is wrong: logs to check, recovery steps, who to escalate to.

Logs to check

• workflow_run_log · top-level run audit
• workflow_step_log · per-step trace
• workflow_verify_results · post-window verify outcomes
• cron_locks · stuck cron lock detection
• events · workflow.completed / workflow.failed event trail
• reflexion_log · per-run narrative (if reflexion_enabled)
• npx wrangler tail · live Worker logs

Kill switch · emergency stop

If this workflow is misbehaving in a high-impact way (creating bad proposed_actions in volume, pushing wrong things to NS), flip a kill switch:

• kill:ns_writes · stops every NS push platform-wide
• kill:proposed_apply · stops HITL approvals from executing fan-out
• kill:high_risk_ops · stops risk_level >= 4 fan-out

See kill-switches-state-machine.html for the full state machine + recovery procedure.

Escalation

Primary: Mike Levine (single-admin) · mikelevine@globalfoodsolutions.co. For prolonged outage during business hours, notify warehouse lead + accounting lead so they can defer dependent work.

What's not done · what's uncertain

What's not done, what's uncertain, what we punted. Captured so it survives context switches and doesn't die in someone's head.

• STUB
  ns_push kind unwired — vendor cost not written back to NS

  We update D1 vendor_costs but don't push to NS vendor record. Mike updates NS manually today.

• OPEN
  Should cost increase auto-suggest a bid_price_update?

  Today it just fires event and emits margin_watchlist. Auto-staging a bid_price_update proposed_action would be aggressive — Mike's call.

• DEFER
  Multi-vendor lowest-cost re-ranking

  When a vendor raises cost, we should re-rank which vendor is cheapest for that item. Today purely manual.

• DECISION
  Currency / exchange-rate handling for international vendors

  Today all costs assumed USD. A few vendors quote CAD — no FX conversion in place.