NS assembly build flow

The Pillar 4 build — cost, capacity, consumption

The NS assembly build flow is the operational sibling of the work order lifecycle. Where the WO lifecycle tracks what NS records, the assembly build flow tracks what the platform decides before NS records anything — BOM resolution, cost rollup against current vendor costs, capacity check, and HITL authorization when the cost surface is about to move significantly.

It runs every time a build request hits the system — from an operator, a WO, or a sales-driven backorder. The first six steps happen before NS posts a build; the last four are the consumption + creation + refresh tail.

Diagram: ns-assembly-build-flow.html. One STUB: labor capacity check — there is no formal capacity calendar table yet, so the check is currently a hand-wave that returns true unless inventory is short.

Trigger conditions

• Operator manually requests N units of an assembly via NS UI.
• Open work order requires components staged for a release.
• Sales order requires assembled stock not on the shelf.
• Pillar 4 annual roll triggers a rebuild of cost rollups for all assemblies.
• Vendor cost moved — flow runs in re-cost mode (no actual build) to refresh assembly_cost_rollup.

Build 200 cases of Melt Mates — cheese cost moved

The ten beats

1. 01

   Build request — manual, WO, or SO-driven

   An operator, an open work order, or a customer order requiring assembled stock fires a build request. The source is recorded for downstream tracing.

   Source operator / WO / SO
2. 02

   BOM resolution

   Pull assembly_bom rows for the assembly_id. Validate every line_key exists in items master, has a current cost, and has on-hand availability. Missing or zero-cost lines abort the request with an actionable error.

   Reads assembly_bom, items, inventory_balance
3. 03

   Cost rollup — Pillar 4 logic

   Refresh assembly_cost_rollup by summing raw component cost, packaging, labor estimate, overhead allocation, and freight per pillar 4 cost-surface logic. Bongards, Cardinal, and Ace Endico items pick up their special formulas (CME trailing week, USDA drawdown, etc.).

   Writes assembly_cost_rollup

   Computes drift_pct_vs_prior
4. 04

   Capacity check — STUB

   Confirm labor hours available and components in inventory. Components check is real (reads inventory_balance). STUB: labor capacity is not formally tracked — there's no capacity_calendar table, so the check returns true unless a hard inventory short forces a queue. This is acceptable today because we run a single shift, but it won't scale beyond two production lines.

   STUB labor capacity calendar

   Real inventory shortfall check
5. 05

   HITL authorization — $5K or 8% gate

   If rollup_cost > $5,000 OR drift_pct_vs_prior > 0.08, a row is staged in proposed_actions with action_type='assembly_build_review', risk_level 3. Mike approves at /proposed-actions.html. Below threshold, the build proceeds without HITL.

   HITL risk_level 3

   Writes proposed_actions
6. 06

   Component consumption — debit inventory

   Debit inventory_balance per BOM line for the build qty. NS posts a workorderissue (or inventoryadjustment for non-WO builds). D1 mirrors negative-qty rows in transaction_lines.

   Writes workorderissue, inventory_balance--
7. 07

   Build operation — the physical build

   The floor produces the assembly. System-side this is the NS build transaction record that links consumption (step 6) to creation (step 8). The transaction id is the durable cross-reference.

   Writes NS build transaction
8. 08

   Assembly created — credit inventory

   Credit inventory_balance for the assembly item at the production location. The assembly is now allocatable for the triggering SO or for general sale.

   Writes inventory_balance++
9. 09

   Spec sheet refresh — if claims changed

   If claims, allergens, or pack format changed in the BOM since the last spec render, regenerate via the spec-sheet-pipeline workflow. Otherwise skip. Driven by a content hash on the BOM spec-relevant fields.

   Conditional hash-changed only

   Writes R2 spec-sheets/
10. 10

    Cost recalc — final actuals

    assembly_cost_rollup re-runs with the final actuals from steps 6 & 8. drift_pct_vs_prior surfaces on the item entity page and the admin-dashboard cost-surface tile. The new value becomes the baseline for the next build.

    Writes assembly_cost_rollup

    Surfaces /item/<code>, admin-dashboard

What's different after the build

• FG inventory reflects the new build; components decremented.
• Cost rollup carries the new component costs forward.
• Spec sheet regenerated if BOM claims drifted.
• Drift signal feeds the cost-surface tile and any vendor cost watchers.

What can go wrong

Adjacent flows + diagrams

Code paths + invariants