Bid price update

The most-rehearsed workflow on the platform

The bid price update is the canonical example we point every new tool at first. It captures the full pattern: AI proposes a change, Mike approves once, and the system fans the approved value out to every downstream surface that knows about that price. Nothing else writes back to NetSuite by hand.

It exists because bid prices live in four physical places at once — the NS pricing record, the D1 mirror, the original bid line row, and the regenerated bid PDF in R2 — plus the hub cache and the spec sheet. Before this workflow, those drifted apart and Mike spent his days reconciling them. Now there's exactly one approval moment and the fan-out is deterministic.

The contract is stored in workflow_definitions WHERE workflow_type='bid_price_update'. Risk level is 3 (medium). Expected duration is roughly 5 minutes end-to-end once Mike taps approve.

Trigger conditions

• A customer responds to a bid with a counter price and you want it on the record.
• Vendor cost moved and the bid line needs to follow (after margin check).
• USDA entitlement drawdown shifts the net cost on a barrel cheddar line.
• Mike negotiates a price on the phone and needs it reflected in NS + the next quote.
• Spec deviation review concluded the new pack/format justifies a price adjustment.

Driscoll requests $X on item Y for SY2026

The eleven beats

1. 01

   Mike or chat tool emits a proposed action

   An AI tool (most often propose_price_change) writes a row to proposed_actions with action_type='bid_price_update', the price delta, and a structured payload of the seven downstream targets it intends to touch.

   Writes proposed_actions

   Time ~200ms
2. 02

   Risk tier is calculated

   The trigger in 114_risk_level_trigger.sql evaluates the proposed action against the cumulative cap and assigns risk_level L1–L5. A single bid line under 5% movement lands at L3 and shows up in Mike's queue with a yellow band, not red.

   Writes proposed_actions.risk_level

   Time ~5ms (trigger)
3. 03

   Mike sees it in /proposed-actions.html

   The page polls every 10s. Mike sees the row with full context — current price, proposed price, customer, bid, spec, margin impact, and a side-by-side preview of the cascade targets. Single-decide or bulk-decide are both available.

   Reads proposed_actions, bid_lines, pricing_master

   Time Mike typically approves within 60min
4. 04

   Mike taps Approve — the atomic claim fires

   R560's atomic-claim fix: the approve endpoint does UPDATE proposed_actions SET status='approved', claimed_by='mike', claimed_at=? WHERE id=? AND status='pending'. The WHERE status='pending' clause prevents the double-approval race that bit us when Mike fat-fingered the bulk-decide button twice.

   Writes proposed_actions.status='approved'

   Invariant ADR-031 HITL discipline
5. 05

   NS pricing record is updated (push 1 of 7)

   A row is enqueued on NS_PUSH_QUEUE with the OAuth1 RESTlet payload. The push worker hits the customscript_gfs_platform_query RESTlet with the new price. NS is the system of record — this push is the load-bearing one. Retry policy is exponential, max 3 attempts.

   Writes NetSuite pricing record

   Time ~3–8s round trip

   Retry 3 attempts
6. 06

   D1 pricing_master mirrors the value (push 2)

   Parallel with the NS push, the D1 row in pricing_master is updated and a corresponding row appended to pricing_history with the prior value, new value, who, when, and the originating proposed_action_id. This is the audit trail for the next compliance review.

   Writes pricing_master, pricing_history

   Time ~80ms
7. 07

   bid_lines is updated (push 3)

   If the proposed action carried a bid_id, the matching row in bid_lines gets the new price and an updated_at stamp. This is what the bid lifecycle dashboard reads from, so this push is what makes the bid show its new number.

   Writes bid_lines

   Conditional only if bid_id present
8. 08

   Bid PDF is regenerated in R2 (push 4)

   The artifact regen pulls the new bid_lines, renders the bid response template via Browser Rendering, and stores it as bids//B5875_.pdf in R2. The hub link is updated to point at the new artifact key.

   Writes R2 bucket bids/

   Time ~6–10s

   Conditional only if bid is active
9. 09

   Hub KV cache is invalidated (push 5)

   The HUB_CACHE KV namespace gets a delete for any key referencing the affected bid_id, customer_id, or item_id. Next request renders fresh from D1. This is what guarantees customer-facing pages reflect the new price in < 60 seconds.

   Writes KV invalidations

   Time ~40ms
10. 10

    Spec sheet review flagged if >5% change (push 6)

    If abs(price_change_pct) > 0.05, a row is inserted into spec_review_queue so the spec sheet system can re-validate the pack/format/ingredient line still justifies the new price. This is a soft flag — it doesn't block the cascade.

    Writes spec_review_queue

    Conditional only if delta > 5%
11. 11

    Customer notification drafted + event emitted (push 7)

    A draft email is written to outbound_email_log with status='pending_review' — Mike still has to approve the send. An event price.changed is appended to the events ledger with the full payload so downstream subscribers (margin watcher, customer health) can react.

    Writes outbound_email_log, events

    Emits price.changed

What's different after the workflow runs

• NetSuite, D1 pricing_master, and bid_lines all show the new price.
• pricing_history has a fresh audit row stamped with Mike's approval.
• The hub's customer-facing bid page shows the new price within 60s.
• If >5% change, spec review is on someone's queue.
• A draft customer notification is waiting for Mike's second tap.
• An event in events lets margin and health watchers react asynchronously.

What can go wrong and how to recover

Adjacent workflows + diagrams

Code paths + invariants