Wiki · Workflow companion

USDA lot drawdown commit

A USDA commodity lot is exhausted. Compute the weighted-average cost from the remaining lots, flag every open quote touching the commodity SKU for re-quote, push the new cost basis, and reconcile against the USDA program allocation.

Mixed · Some steps live, others stubbed
What this is

USDA lot drawdown commit

USDA commodity drawdown is the workflow that keeps weighted-average costing honest when a lot exhausts. The pricing of every assembly that uses the commodity (barrel cheddar, etc) depends on which lot we're drawing from — if a lot ends and we forget to recompute, every quote and pricing_master row sourced from that commodity is wrong.

The cascade re-bases the vendor_costs entry, recomputes the assembly_cost_rollup for every affected assembly, flags open quotes for re-quote, and updates the USDA program reconciliation status.

Risk level 4 (high) — because the cost basis touches active customer pricing.

When to use it

Trigger conditions

Heuristic

The cost_diff_reasonable precondition warns if the new lot's cost differs by >30% from the exhausted lot. This catches the most common data error: wrong lot mapped to wrong commodity.

Step-by-step what happens

The 4 beats

  1. 01

    INSERT new vendor_costs row

    INSERT into vendor_costs with the new weighted-average unit_cost and effective_from. The prior row remains (active=false implicit via effective_from ordering).

    Writes vendor_costs
    Time ~80ms
    Kind d1_write
    Status stub
  2. 02

    Recompute affected assemblies

    Call recompute_assembly_cost_rollup for each assembly whose BOM references the commodity sku. Rollups persist with fresh last_computed.

    Writes assembly_cost_rollup
    Time ~200ms per assembly
    Kind chat_tool
    Status stub
  3. 03

    Flag affected open quotes

    For each quote in (draft, proposed, sent) with a line on the commodity sku, stage flag_stale_quote in proposed_actions.

    Writes proposed_actions
    Time ~50ms per quote
    Kind stage_proposed_action
    Status real
    Note one_per affected quote
  4. 04

    USDA program reconciliation

    UPDATE usda_commodity_programs SET reconciliation_status='pending' for affected programs. Surfaces in the USDA reconciliation queue.

    Writes usda_commodity_programs
    Time ~80ms
    Kind d1_write
    Status stub
Outcomes

What's different after the workflow runs

New cost basis
Applied
≤ 10s
Assemblies
Recomputed
per BOM hit
Quotes
Flagged
in proposed_actions
USDA reconcile
Pending
queued
Failure modes

What can go wrong and how to recover

No next lot available

Precondition blocks: current_lots.length > 0. This means we have no commodity supply for the SKU. Manual escalation: USDA program manager to provision a new lot.

Cost differential >30%

Precondition warns. Likely a data error (wrong lot mapped). Mike verifies the lot assignment before approving.

Assembly recompute partial

Retry policy is 2 linear-backoff attempts. Persistent failures alert; manual POST /admin/assembly/recompute recovers.

No quotes affected

Sometimes a commodity drawdown happens with no open quotes. Cascade still completes; no flag rows stage.

Related

Adjacent workflows + diagrams

Flow diagramUSDA drawdown commit (contract + visual) GraphUSDA drawdown — archify graph UpstreamAssembly build review (triggers here) DownstreamVendor cost update (cascading pattern) DownstreamCustomer quote (re-quote path) SubstrateEvent ledger
For developers

Code paths + invariants

ConcernWhere
Workflow contractworkflow_definitions WHERE workflow_type='usda_drawdown_commit'
Lot tableusda_commodity_lots
Program tableusda_commodity_programs
Cost-basis patternweighted-average across active lots
Reflexion tagusda_drawdown,sku:<sku>
Risk level4
Expected duration~30 min
Triggerevent · sources=inventory_threshold_cron, manual_lot_close
// Weighted-average across remaining active lots const avg = currentLots.reduce( (sum, l) => sum + (l.remaining_qty * l.unit_cost), 0 ) / currentLots.reduce((sum, l) => sum + l.remaining_qty, 0); await db.run( "INSERT INTO vendor_costs (vendor_item_id, unit_cost, effective_from, source, status) " + "VALUES (?, ?, ?, 'usda_drawdown', 'active')", [vendor_item_id, avg, effective_from] );