@happyvertical/smrt-manufacturing 0.56.0 → 0.56.2

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-manufacturing",
-  "packageVersion": "0.56.0",
+  "packageVersion": "0.56.2",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "6b1d0d7aa92a0915ef0a174dcd6fcc19d2c8d2e6cdf97fdb524136fef90e9474",
-    "packageJson": "3aab7bc95c607df992d28bc990e18594862c873d55d9d29ada2c1c26a4c3ee6a",
+    "manifest": "a621b699202148426f5c9be1082537139be6c9e21ab37ef32b68408368ed0f62",
+    "packageJson": "b6d0801aa8c8ca080b6d928ccdac0977c01eb6349d6d1cb1534fb606f92475cf",
     "agents": "53bbb8d8dfd7e1dbd438a4ad1559be8cd1ad8ed46c726d5498d2dda5b3535054",
     "moduleDoc:agents/multilevel-and-runs.md": "544d519356801f3cb3beb9e6d49a3e0eec93fdddf3f56150cf3141f766f98c9d"
   },
@@ -63,7 +63,7 @@
     "smrt"
   ],
   "risks": [
-    "cross-package-refs:1",
+    "cross-package-refs:3",
     "sensitive-fields-excluded",
     "sti-inheritance"
   ],
@@ -109,30 +109,6 @@
         }
       ],
       "surfaces": [
-        {
-          "kind": "api",
-          "name": "billofmaterialses.findByProduct",
-          "operation": "findByProduct",
-          "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterialsCollection",
-          "path": "/billofmaterialses/findByProduct",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "billofmaterialses.findActiveForProduct",
-          "operation": "findActiveForProduct",
-          "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterialsCollection",
-          "path": "/billofmaterialses/findActiveForProduct",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "billofmaterialses.findByStatus",
-          "operation": "findByStatus",
-          "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterialsCollection",
-          "path": "/billofmaterialses/findByStatus",
-          "method": "POST"
-        },
         {
           "kind": "cli",
           "name": "billofmaterialscollection_findByProduct",
@@ -150,23 +126,28 @@
           "name": "billofmaterialscollection_findByStatus",
           "operation": "findByStatus",
           "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterialsCollection"
-        },
+        }
+      ],
+      "withheldSurfaces": [
         {
-          "kind": "mcp",
-          "name": "billofmaterialscollection_findbyproduct",
-          "operation": "findByProduct",
+          "kind": "api",
+          "operation": "findActiveForProduct",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterialsCollection"
         },
         {
-          "kind": "mcp",
-          "name": "billofmaterialscollection_findactiveforproduct",
-          "operation": "findActiveForProduct",
+          "kind": "api",
+          "operation": "findByProduct",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterialsCollection"
         },
         {
-          "kind": "mcp",
-          "name": "billofmaterialscollection_findbystatus",
+          "kind": "api",
           "operation": "findByStatus",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterialsCollection"
         }
       ],
@@ -208,22 +189,6 @@
         }
       ],
       "surfaces": [
-        {
-          "kind": "api",
-          "name": "bomlines.findByBom",
-          "operation": "findByBom",
-          "objectName": "@happyvertical/smrt-manufacturing:BomLineCollection",
-          "path": "/bomlines/findByBom",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "bomlines.findByComponent",
-          "operation": "findByComponent",
-          "objectName": "@happyvertical/smrt-manufacturing:BomLineCollection",
-          "path": "/bomlines/findByComponent",
-          "method": "POST"
-        },
         {
           "kind": "cli",
           "name": "bomlinecollection_findByBom",
@@ -235,17 +200,21 @@
           "name": "bomlinecollection_findByComponent",
           "operation": "findByComponent",
           "objectName": "@happyvertical/smrt-manufacturing:BomLineCollection"
-        },
+        }
+      ],
+      "withheldSurfaces": [
         {
-          "kind": "mcp",
-          "name": "bomlinecollection_findbybom",
+          "kind": "api",
           "operation": "findByBom",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-manufacturing:BomLineCollection"
         },
         {
-          "kind": "mcp",
-          "name": "bomlinecollection_findbycomponent",
+          "kind": "api",
           "operation": "findByComponent",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-manufacturing:BomLineCollection"
         }
       ],
@@ -286,45 +255,20 @@
           "returns": "Promise<Operation[]>"
         }
       ],
-      "surfaces": [
-        {
-          "kind": "api",
-          "name": "operations.findByCode",
-          "operation": "findByCode",
-          "objectName": "@happyvertical/smrt-manufacturing:OperationCollection",
-          "path": "/operations/findByCode",
-          "method": "POST"
-        },
+      "surfaces": [],
+      "withheldSurfaces": [
         {
           "kind": "api",
-          "name": "operations.listOperations",
-          "operation": "listOperations",
-          "objectName": "@happyvertical/smrt-manufacturing:OperationCollection",
-          "path": "/operations/listOperations",
-          "method": "POST"
-        },
-        {
-          "kind": "cli",
-          "name": "operationcollection_findByCode",
-          "operation": "findByCode",
-          "objectName": "@happyvertical/smrt-manufacturing:OperationCollection"
-        },
-        {
-          "kind": "cli",
-          "name": "operationcollection_listOperations",
-          "operation": "listOperations",
-          "objectName": "@happyvertical/smrt-manufacturing:OperationCollection"
-        },
-        {
-          "kind": "mcp",
-          "name": "operationcollection_findbycode",
           "operation": "findByCode",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-manufacturing:OperationCollection"
         },
         {
-          "kind": "mcp",
-          "name": "operationcollection_listoperations",
+          "kind": "api",
           "operation": "listOperations",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-manufacturing:OperationCollection"
         }
       ],
@@ -365,45 +309,20 @@
           "returns": "Promise<ProductionRun[]>"
         }
       ],
-      "surfaces": [
+      "surfaces": [],
+      "withheldSurfaces": [
         {
           "kind": "api",
-          "name": "productionruns.findByBom",
-          "operation": "findByBom",
-          "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCollection",
-          "path": "/productionruns/findByBom",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "productionruns.findByStatus",
-          "operation": "findByStatus",
-          "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCollection",
-          "path": "/productionruns/findByStatus",
-          "method": "POST"
-        },
-        {
-          "kind": "cli",
-          "name": "productionruncollection_findByBom",
-          "operation": "findByBom",
-          "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCollection"
-        },
-        {
-          "kind": "cli",
-          "name": "productionruncollection_findByStatus",
-          "operation": "findByStatus",
-          "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCollection"
-        },
-        {
-          "kind": "mcp",
-          "name": "productionruncollection_findbybom",
           "operation": "findByBom",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCollection"
         },
         {
-          "kind": "mcp",
-          "name": "productionruncollection_findbystatus",
+          "kind": "api",
           "operation": "findByStatus",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCollection"
         }
       ],
@@ -435,25 +354,13 @@
           "returns": "Promise<ProductionRunCompletion[]>"
         }
       ],
-      "surfaces": [
+      "surfaces": [],
+      "withheldSurfaces": [
         {
           "kind": "api",
-          "name": "productionruncompletions.findByRun",
-          "operation": "findByRun",
-          "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletionCollection",
-          "path": "/productionruncompletions/findByRun",
-          "method": "POST"
-        },
-        {
-          "kind": "cli",
-          "name": "productionruncompletioncollection_findByRun",
-          "operation": "findByRun",
-          "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletionCollection"
-        },
-        {
-          "kind": "mcp",
-          "name": "productionruncompletioncollection_findbyrun",
           "operation": "findByRun",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletionCollection"
         }
       ],
@@ -495,22 +402,6 @@
         }
       ],
       "surfaces": [
-        {
-          "kind": "api",
-          "name": "routingsteps.findByBom",
-          "operation": "findByBom",
-          "objectName": "@happyvertical/smrt-manufacturing:RoutingStepCollection",
-          "path": "/routingsteps/findByBom",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "routingsteps.findByOperation",
-          "operation": "findByOperation",
-          "objectName": "@happyvertical/smrt-manufacturing:RoutingStepCollection",
-          "path": "/routingsteps/findByOperation",
-          "method": "POST"
-        },
         {
           "kind": "cli",
           "name": "routingstepcollection_findByBom",
@@ -522,17 +413,21 @@
           "name": "routingstepcollection_findByOperation",
           "operation": "findByOperation",
           "objectName": "@happyvertical/smrt-manufacturing:RoutingStepCollection"
-        },
+        }
+      ],
+      "withheldSurfaces": [
         {
-          "kind": "mcp",
-          "name": "routingstepcollection_findbybom",
+          "kind": "api",
           "operation": "findByBom",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-manufacturing:RoutingStepCollection"
         },
         {
-          "kind": "mcp",
-          "name": "routingstepcollection_findbyoperation",
+          "kind": "api",
           "operation": "findByOperation",
+          "code": "not-included",
+          "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-manufacturing:RoutingStepCollection"
         }
       ],
@@ -615,6 +510,22 @@
           "default": 0,
           "description": "The price in minor units (cents), for example 1999 for 19.99."
         },
+        {
+          "name": "defaultSalesTaxCodeId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-commerce:TaxCode",
+          "columnType": "UUID",
+          "description": "The tax code normally used when this product is sold."
+        },
+        {
+          "name": "defaultPurchaseTaxCodeId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-commerce:TaxCode",
+          "columnType": "UUID",
+          "description": "The tax code normally used when this product is purchased."
+        },
         {
           "name": "inStock",
           "type": "boolean",
@@ -659,6 +570,20 @@
         }
       ],
       "relationships": [
+        {
+          "name": "defaultSalesTaxCodeId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-commerce:TaxCode",
+          "columnType": "UUID"
+        },
+        {
+          "name": "defaultPurchaseTaxCodeId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-commerce:TaxCode",
+          "columnType": "UUID"
+        },
         {
           "name": "defaultOperationId",
           "type": "foreignKey",
@@ -870,6 +795,7 @@
         }
       ],
       "relationshipFeatures": [
+        "crossPackageRef",
         "foreignKey",
         "uuidColumns"
       ],
@@ -1701,30 +1627,6 @@
     }
   ],
   "surfaces": [
-    {
-      "kind": "api",
-      "name": "billofmaterialses.findByProduct",
-      "operation": "findByProduct",
-      "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterialsCollection",
-      "path": "/billofmaterialses/findByProduct",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "billofmaterialses.findActiveForProduct",
-      "operation": "findActiveForProduct",
-      "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterialsCollection",
-      "path": "/billofmaterialses/findActiveForProduct",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "billofmaterialses.findByStatus",
-      "operation": "findByStatus",
-      "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterialsCollection",
-      "path": "/billofmaterialses/findByStatus",
-      "method": "POST"
-    },
     {
       "kind": "cli",
       "name": "billofmaterialscollection_findByProduct",
@@ -1743,40 +1645,6 @@
       "operation": "findByStatus",
       "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterialsCollection"
     },
-    {
-      "kind": "mcp",
-      "name": "billofmaterialscollection_findbyproduct",
-      "operation": "findByProduct",
-      "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterialsCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "billofmaterialscollection_findactiveforproduct",
-      "operation": "findActiveForProduct",
-      "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterialsCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "billofmaterialscollection_findbystatus",
-      "operation": "findByStatus",
-      "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterialsCollection"
-    },
-    {
-      "kind": "api",
-      "name": "bomlines.findByBom",
-      "operation": "findByBom",
-      "objectName": "@happyvertical/smrt-manufacturing:BomLineCollection",
-      "path": "/bomlines/findByBom",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "bomlines.findByComponent",
-      "operation": "findByComponent",
-      "objectName": "@happyvertical/smrt-manufacturing:BomLineCollection",
-      "path": "/bomlines/findByComponent",
-      "method": "POST"
-    },
     {
       "kind": "cli",
       "name": "bomlinecollection_findByBom",
@@ -1789,134 +1657,6 @@
       "operation": "findByComponent",
       "objectName": "@happyvertical/smrt-manufacturing:BomLineCollection"
     },
-    {
-      "kind": "mcp",
-      "name": "bomlinecollection_findbybom",
-      "operation": "findByBom",
-      "objectName": "@happyvertical/smrt-manufacturing:BomLineCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "bomlinecollection_findbycomponent",
-      "operation": "findByComponent",
-      "objectName": "@happyvertical/smrt-manufacturing:BomLineCollection"
-    },
-    {
-      "kind": "api",
-      "name": "operations.findByCode",
-      "operation": "findByCode",
-      "objectName": "@happyvertical/smrt-manufacturing:OperationCollection",
-      "path": "/operations/findByCode",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "operations.listOperations",
-      "operation": "listOperations",
-      "objectName": "@happyvertical/smrt-manufacturing:OperationCollection",
-      "path": "/operations/listOperations",
-      "method": "POST"
-    },
-    {
-      "kind": "cli",
-      "name": "operationcollection_findByCode",
-      "operation": "findByCode",
-      "objectName": "@happyvertical/smrt-manufacturing:OperationCollection"
-    },
-    {
-      "kind": "cli",
-      "name": "operationcollection_listOperations",
-      "operation": "listOperations",
-      "objectName": "@happyvertical/smrt-manufacturing:OperationCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "operationcollection_findbycode",
-      "operation": "findByCode",
-      "objectName": "@happyvertical/smrt-manufacturing:OperationCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "operationcollection_listoperations",
-      "operation": "listOperations",
-      "objectName": "@happyvertical/smrt-manufacturing:OperationCollection"
-    },
-    {
-      "kind": "api",
-      "name": "productionruns.findByBom",
-      "operation": "findByBom",
-      "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCollection",
-      "path": "/productionruns/findByBom",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "productionruns.findByStatus",
-      "operation": "findByStatus",
-      "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCollection",
-      "path": "/productionruns/findByStatus",
-      "method": "POST"
-    },
-    {
-      "kind": "cli",
-      "name": "productionruncollection_findByBom",
-      "operation": "findByBom",
-      "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCollection"
-    },
-    {
-      "kind": "cli",
-      "name": "productionruncollection_findByStatus",
-      "operation": "findByStatus",
-      "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "productionruncollection_findbybom",
-      "operation": "findByBom",
-      "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "productionruncollection_findbystatus",
-      "operation": "findByStatus",
-      "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCollection"
-    },
-    {
-      "kind": "api",
-      "name": "productionruncompletions.findByRun",
-      "operation": "findByRun",
-      "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletionCollection",
-      "path": "/productionruncompletions/findByRun",
-      "method": "POST"
-    },
-    {
-      "kind": "cli",
-      "name": "productionruncompletioncollection_findByRun",
-      "operation": "findByRun",
-      "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletionCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "productionruncompletioncollection_findbyrun",
-      "operation": "findByRun",
-      "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletionCollection"
-    },
-    {
-      "kind": "api",
-      "name": "routingsteps.findByBom",
-      "operation": "findByBom",
-      "objectName": "@happyvertical/smrt-manufacturing:RoutingStepCollection",
-      "path": "/routingsteps/findByBom",
-      "method": "POST"
-    },
-    {
-      "kind": "api",
-      "name": "routingsteps.findByOperation",
-      "operation": "findByOperation",
-      "objectName": "@happyvertical/smrt-manufacturing:RoutingStepCollection",
-      "path": "/routingsteps/findByOperation",
-      "method": "POST"
-    },
     {
       "kind": "cli",
       "name": "routingstepcollection_findByBom",
@@ -1929,18 +1669,6 @@
       "operation": "findByOperation",
       "objectName": "@happyvertical/smrt-manufacturing:RoutingStepCollection"
     },
-    {
-      "kind": "mcp",
-      "name": "routingstepcollection_findbybom",
-      "operation": "findByBom",
-      "objectName": "@happyvertical/smrt-manufacturing:RoutingStepCollection"
-    },
-    {
-      "kind": "mcp",
-      "name": "routingstepcollection_findbyoperation",
-      "operation": "findByOperation",
-      "objectName": "@happyvertical/smrt-manufacturing:RoutingStepCollection"
-    },
     {
       "kind": "api",
       "name": "products.list",
@@ -2381,11 +2109,11 @@
   "prompts": [],
   "relationshipsV2": {
     "foreignKeyFields": 5,
-    "crossPackageRefFields": 1,
+    "crossPackageRefFields": 3,
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 37
+    "uuidColumns": 39
   },
   "agentDoc": "# @happyvertical/smrt-manufacturing\n\nBills of materials (multi-level through sub-assemblies), operations and routing, cost and labour rollup, production runs, and production-order stock movement. Strictly industry-neutral — the same primitives serve apparel, furniture, automotive, CPG, electronics, food production, custom hardware, and any vertical that builds finished goods from a recipe.\n\nSits on top of `@happyvertical/smrt-inventory` (stock) and `@happyvertical/smrt-products` (catalog: `Product`, `Material`, `Sku`), and works alongside the `ProductionOrder` Contract STI subtype already shipped in `@happyvertical/smrt-commerce`.\n\n## Models\n\n| Model | Purpose |\n|---|---|\n| `Assembly` | The product that is **made**, counterpart to `Material`. Cross-package STI subtype of `smrt-products` `Product` (`productType: 'assembly'`, `_meta_type: '@happyvertical/smrt-manufacturing:Assembly'`) in the shared `products` table. Own columns: `estimatedLabourMinutes` (integer, per unit; a save refuses anything but a whole number of minutes of zero or more), `defaultOperationId` (`@foreignKey(Operation)`, nullable, RESTRICT like `RoutingStep.operationId`: the operation work on it is booked to by default), `partReference` (the organization's drawing/part number). Name, price, tags come from `Product`; part number and stock from its `Sku` and inventory; structure from its bill; documents from `ProductAsset`. Exposure matches `Product` (REST list/get/create/update, MCP list/get), as the issue asks: unlike `Operation`, the assembly row has no service-owned invariant that generated writes could bypass. |\n| `BillOfMaterials` | Recipe for a finished product. `productId` (plain string) references the upstream `Product` or any STI subtype. Multiple revisions per product via `version` + `status` (`draft` / `active` / `superseded`). `conflictColumns: ['product_id', 'version', 'tenant_id']`. |\n| `BomLine` | One component on a BOM. `bomId` (FK), `componentSkuId` (plain string ref — the `Sku` model lives in `@happyvertical/smrt-products`; inventory tracks stock motion against the id), `qtyPerUnit`, `uom` (open-ended — `yards`, `each`, `grams`, `kg`, ...), `wastePercent`, `notes`. `conflictColumns: ['bom_id', 'component_sku_id', 'tenant_id']`. |\n| `Operation` | A kind of work (cut, weld, inspect), a managed list per tenant. `code` (unique per tenant; `conflictColumns: ['code', 'tenant_id']`, fixed once defined), `name`, `category`, `isActive` (retire/reinstate; never deleted, `delete()` throws), `requiredQualificationId` (nullable `@crossPackageRef('@happyvertical/smrt-human-resources:Qualification')`: metadata only, no dependency, unvalidated; an application reads it to gate who may start the operation). |\n| `ProductionRun` | A build against one bill, reported as it happens (\"25 to build, 12 done\"). `bomId` (`@foreignKey(BillOfMaterials)`, RESTRICT: pinned when created), `targetQty` and `completedQty` (decimal; completed is the sum of completions), `status` (`planned` / `in_progress` / `done` / `cancelled`). Generated list/get only; `ProductionRunService` owns writes. |\n| `ProductionRunCompletion` | One dated report on a run: `runId` (`@foreignKey(ProductionRun)`, CASCADE), `qty` (decimal, > 0), `completedAt`. Generated list/get only. |\n| `RoutingStep` | One operation in a BOM's optional routing. `bomId` (`@foreignKey(BillOfMaterials)`, CASCADE: a routing belongs to its bill), `operationId` (`@foreignKey(Operation)`, RESTRICT: operations are retired, never deleted), `sequence` (1..n, unique per bom), `estimatedMinutes` (decimal, per produced unit), `notes`. `conflictColumns: ['bom_id', 'sequence', 'tenant_id']`. |\n\nAll models are `@TenantScoped({ mode: 'optional' })` with a nullable `tenantId` so they can be used either tenant-scoped or globally.\n\n## Operations, routing and labour estimate\n\n- `OperationService` maintains the list (`define` rejects a duplicate code, including a retired one's; `rename`, `update`, `retire`, `reinstate`). `RoutingService.replaceRouting(bomId, steps)` swaps a bill's whole routing in one transaction and numbers it 1..n; a retired operation may stay on a routing that has it but cannot be newly added.\n- `BomService.computeLabourEstimate(bomId)` returns minutes and, only when the caller supplies `rateResolver` (hourly rate per `Operation`, mirroring `costResolver`), cost. No resolver means minutes only with `rateUnavailable` on each step. A bill with no routing returns an empty estimate; `computeMaterialCost` is unchanged.\n- `Operation` and `RoutingStep` expose generated list/get only; writes go through the services (generated create/update would upsert on a duplicate code or rename the code). `replaceRouting` saves the bill row inside its transaction (row lock) and retries on a revision conflict, so concurrent replacements serialize.\n- Deliberately absent: a default labour rate class (nothing here would use it; the resolver receives the whole `Operation` and can key on `code`/`category`), setup time, scheduling and work-centre capacity, and time recorded against an operation (that stays in `smrt-timesheets` or the application).\n- `./svelte` exports `OperationList` and `OperationForm` (props-driven; hosts persist through `OperationService`). Messages live in `src/svelte/i18n.ts`; component tests use the shared jsdom harness with axe assertions.\n- Tests: `operations-suite.ts` runs on SQLite (`operations.test.ts`) and PostgreSQL (`operations.optional.test.ts`, `pnpm test:postgres`; each test runs in its own tenant because PostgreSQL test data persists).\n\n## Assemblies — nesting lives in the bill\n\nA sub-assembly is a `BomLine` whose component SKU belongs to an `Assembly`; there is no children list on the model. `AssemblyService` is the one link from a line to what it names:\n\n| Method | Behavior |\n|---|---|\n| `resolveComponent(skuId, { tenantId? })` | `{ kind, sku, product, assembly, activeBom, buildable }`. `kind` is `assembly`, `material` (`Material`), `bought` (any other `Product`), or `missing` (unknown SKU, SKU with no product, or a non-UUID id; never throws). `activeBom` is the assembly's highest active bill, `null` when it has none; `buildable` is `assembly && activeBom`. Multi-level explosion (#3444) recurses on `activeBom` and stops at every other kind. |\n| `isAssembly(skuId)` | `resolveComponent(skuId).kind === 'assembly'`. |\n| `findActiveBom(productId, { tenantId? })` | Highest active bill. With `tenantId` (including `null`), that tenant's own bill, else a global one, and `resolveComponent` reads the SKU and product as that tenant's or global (through `tenant-scope.ts`, so a shared global component stays visible under a tenant context) and reports another tenant's as `missing`, whatever the tenant context; the cycle walk and `getBillStructure` pass the bill's own tenant, so a shared assembly resolves to the right tenant's bill on writes made without `withTenant()`. |\n| `getBillStructure(bomId)` | One level: the bill plus each line with its resolved component. Throws `BomNotFoundError`. |\n| `findCycle(productId, componentSkuIds)` | The path by which those components would make `productId` contain itself, following sub-assemblies' **active** bills only; `null` when none. |\n| `assertLineAcyclic(line)` / `assertBillAcyclic(bom)` | Throw `BomCycleError` (a `ValidationError`, code `MANUFACTURING_BOM_CYCLE`, `path` from the product back to itself). |\n\n**Cycle refusal runs in the models.** `BomLine.validateBeforeSave` checks every line save (draft bills too, so a loop is refused when written); `BillOfMaterials.validateBeforeSave` checks every save of an `active` bill (activation), including the lines of a stored bill with the same `(productId, version, tenantId)` that the save would upsert onto. The generated REST routes go through `save()`, so they refuse cycles as well. Not covered: re-pointing a `Sku.productId` (owned by `smrt-products`) and two concurrent saves that each close half of a loop.\n\n## Multi-level walks and production runs\n\nDetail: [agents/multilevel-and-runs.md](agents/multilevel-and-runs.md).\n\n- Every `BomService` method takes `{ levels }` (default `1`, unchanged; up to `MAX_EXPLOSION_DEPTH` = 32, or `'all'`). One walk (`services/structure-walk.ts`) serves `explode` (gross lines and totals), `planRequirements` (net of stock: available, short, what building a shortfall takes; facts, no make-or-buy policy), `canProduce`, cost and labour. A loop already in stored data fails with `BomStructureCycleError`; size limits with `BomExplosionLimitError`.\n- `ProductionRunService` writes `ProductionRun` / `ProductionRunCompletion` in one transaction per call, locking the run row through its revision-guarded save and retrying on a revision conflict; no adapter without `transaction()`. Stock moves only when the caller passes `consume` / `produce`.\n- A run is not commerce's `ProductionOrder` (a `Contract` with terms and money, in a package this one does not depend on); an application that has both links them.\n\n## Svelte components (`./svelte`)\n\nProps-driven; the host loads and persists. `AssemblyList` (a structural `policy` drops hidden columns), `AssemblyForm` (smrt-ui controls like `OperationForm`: `assembly`, `onsubmit(values, formData)`, `operations` for the default-operation picker, `showSkuCode` for a required part-number field (`values.skuCode`; host-reported messages through `errors.fields.skuCode`), `extraFields` snippet inside the form, a retired or unlisted current operation stays selected and marked, `hiddenFields`/`readonlyFields` for the reader's field policy; price is major units in the form and integer minor units in `onsubmit`; `validateAssemblyForm` mirrors the model's whole-minutes rule). `smrt-fields` is not a dependency: never add `ObjectForm`, `BomEditor` (add/edit/remove lines through host handlers; a sub-assembly shows whether it has its own bill and expands read-only through `loadBill`), `BomStructureTree` (the read-only nested view). `ProductionRunList` (progress, status, and with `oncomplete` a quantity field per open run; `onsettarget`/`onfinish`/`oncancel` each add their control only when given, finish and cancel behind a `ConfirmDialog`; rows from `toProductionRunView`), `RequirementsTree` (read-only `explode` / `planRequirements` result by level with totals; `toRequirementTree`, `toRequirementTotals`; internal `RequirementsTreeLevel`). Adapters: `toAssemblyView`, `toBomEditorLines`; the BOM and requirement adapters live in `src/views.ts` (no runtime imports, exported as `./views`, re-exported by `./svelte`: keep it component-free). Strings are under `manufacturing.` in `src/svelte/i18n.ts`; the package is strict for raw primitives, hardcoded strings and JSDoc.\n\n\n## BomService — planning helpers\n\n```typescript\nimport { BomService } from '@happyvertical/smrt-manufacturing';\n\nconst bom = await BomService.create({\n  db,\n  // Optional. Resolve unit cost for a component SKU.\n  // Without this, every line rolls up to $0 and `costUnavailable` is set.\n  costResolver: async (componentSkuId) => fetchLatestCost(componentSkuId),\n});\n\nconst rollup = await bom.computeMaterialCost(bomId);\n//   { totalCost, currency, lineBreakdown, hasMissingCosts }\n\nconst requirements = await bom.explodeRequirements(bomId, 100);\n//   [{ componentSkuId, totalQty, uom }, ...]\n\nconst check = await bom.canProduce(bomId, 100);\n//   { ok: true } | { ok: false, shortages: [...] }\n```\n\n| Method | Behavior |\n|---|---|\n| `computeMaterialCost(bomId)` | Walks every BomLine, applies waste (`qtyPerUnit * (1 + wastePercent / 100)`), resolves unit costs via the optional `costResolver`, returns per-line breakdown plus rolled-up total. Lines with no cost set `costUnavailable: true` and contribute `0`. |\n| `explodeRequirements(bomId, qty)` | Returns a \"shopping list\" of materials needed for `qty` units. Duplicates across lines are summed. Does NOT mutate stock. |\n| `canProduce(bomId, qty)` | Calls `explodeRequirements`, then sums `available` stock across every location per component, returns `{ ok: true }` if everything's covered, else `{ ok: false, shortages: [...] }`. |\n| `explode` / `planRequirements` | Multi-level walks; see \"Multi-level walks\" above. Each method above also takes `{ levels }`. |\n\n## ProductionService — consume / produce\n\n```typescript\nimport { ProductionService } from '@happyvertical/smrt-manufacturing';\n\nconst production = await ProductionService.create({ db });\n\n// Drain materials at the factory.\nconst consumed = await production.consumeMaterials(\n  { id: order.id, productId: order.productId, bomId: order.bomId },\n  { locationId: factory.id, qty: runQty },\n);\n\n// Receive finished goods.\nconst produced = await production.produceFinishedGoods(\n  { id: order.id, productId: order.productId },\n  { locationId: factory.id, qty: runQty, finishedSkuId: variant.id },\n);\n\n// Or run both in one transaction — see \"Joint atomicity\" below.\nconst { consumed, produced } = await production.runProduction(\n  { id: order.id, productId: order.productId, bomId: order.bomId },\n  {\n    consume: { locationId: factory.id, qty: runQty },\n    produce: { locationId: factory.id, qty: runQty, finishedSkuId: variant.id },\n  },\n);\n```\n\nAll three methods write through `StockService` and stamp every emitted `StockMovement` with `sourceType: 'ProductionOrder'` (override with the `sourceType` option, as `ProductionRunService` does) + the production order id so audit queries can roll them up later.\n\n### Joint atomicity — `runProduction` vs the two-call form\n\n`consumeMaterials` and `produceFinishedGoods` are each individually atomic, but calling them as two separate awaits is NOT jointly atomic — each opens its own `stockService.withTransaction(...)` scope. If something goes wrong between the two calls (process crash, transient adapter failure on the produce leg), you can land in a state where materials are deducted but no finished SKU receipt balances them. The audit ledger stays consistent within each call; what's missing is the cross-call invariant.\n\nWhen you need that invariant — typically make-to-stock flows where the factory step is invisible to the ledger — use `runProduction(order, { consume, produce })`. Both legs run inside one transaction; any failure (BOM shortage, adapter error, interceptor reject) rolls back both legs together.\n\nWhen NOT to use it: workflows where consume and produce represent a real wall-clock gap that downstream observers need to see (WIP dashboards, partial-run reporting, separate \"materials posted\" and \"production completed\" events on the dispatch bus). There, the two-call form is the right shape — each call is its own ledger event.\n\n### Location convention — explicit-arg design\n\nThe location where materials are consumed and finished goods are received is passed explicitly to `consumeMaterials` / `produceFinishedGoods`, not carried on the production order itself. Rationale:\n\n- The commerce `ProductionOrder` is a `Contract` STI subtype owned by `@happyvertical/smrt-commerce`. Adding an `originLocationId` field there would either need a schema change in commerce (cross-cutting) or a meta field that only manufacturing knows about (leaky).\n- Real shops often pick a location at run time (factory A is congested, route the run through factory B), so even if the order carried a default, the explicit-arg signature is the more flexible canonical form.\n- Callers that want a default can stash a `locationId` on their own production-order helper and pass it through.\n\n### Finished-SKU convention\n\nA `ProductionOrder` references a `productId`, but a `Product` typically has multiple SKUs (one per variant). The caller of `produceFinishedGoods` picks the concrete `finishedSkuId` because the multi-SKU mapping is application-specific (size run, finish mix, kit variant).\n\n## Opt-in DispatchBus hooks\n\nOff by default. Wire them up explicitly in the application's `smrt.ts`:\n\n```typescript\nimport { installManufacturingDispatchHandlers } from '@happyvertical/smrt-manufacturing';\n\nconst handlers = await installManufacturingDispatchHandlers({\n  dispatchBus: bus,\n  db,\n  // Default: subscribe to production_order:posted, call consumeMaterials.\n  installProductionPosted: true,\n  // Default: don't auto-produce. Set to true if your shop emits a\n  // separate production_order:completed event.\n  installProductionCompleted: false,\n  // Default: don't combine consume + produce on `posted`. Set to true\n  // for make-to-stock-instantly workflows where the factory step is\n  // invisible. Ignored when installProductionCompleted is true.\n  producedOnPosted: false,\n});\n```\n\nThis subscribes to:\n\n- `production_order:posted` → `production.consumeMaterials(...)`; when `producedOnPosted: true` the handler instead calls `production.runProduction(...)` so consume + produce share one transaction. Process crashes or adapter errors between the two legs can never leave materials deducted with no finished-goods receipt.\n- `production_order:completed` → `production.produceFinishedGoods(...)` (opt-in)\n\nThe companion handlers for `contract:created` (reserve) and `fulfillment:shipped` (fulfil) live in `@happyvertical/smrt-inventory` — wire both packages' installers from `smrt.ts` to get the full lifecycle.\n\n## Tests\n\n`multilevel-suite.ts` (rolled back on PostgreSQL) and `production-run-suite.ts` (base handle, per-test tenant, for real concurrent transactions) follow the same SQLite / `*.optional.test.ts` pattern. `src/__tests__/assembly-suite.ts` runs on SQLite (`assembly.test.ts`) and on PostgreSQL (`assembly.optional.test.ts`, skipped without `DATABASE_URL`; `pnpm test:postgres` and the PostgreSQL CI lane run it on a transaction-scoped handle). Component tests under `src/svelte/__tests__` use jsdom and assert axe.\n\n## Gotchas\n\n- **`computeMaterialCost` without a resolver returns `$0`.** That is deliberate — manufacturing does not assume any particular cost source. A real wiring will plug in `@happyvertical/smrt-products` `Material.costPerUnit`, or a rolling average from purchase-order history, or a vendor price book. The `costUnavailable` flag tells UIs to surface \"unknown cost\" rather than silently rolling up zeros.\n- **`explodeRequirements` does not call any stock APIs.** It is a planning helper. To check whether the materials are actually on hand, use `canProduce`. To actually deduct them, use `ProductionService.consumeMaterials`.\n- **`canProduce` sums available stock across every location.** The planning question is \"do we have it at all?\". The operational question of \"which warehouse do we pull from?\" is left to the caller of `consumeMaterials`, which targets a single `locationId` per call.\n- **`consumeMaterials` propagates `InsufficientStockError`.** If a line would drive `available` below zero, the underlying `StockService.adjust` throws. Pre-flight with `canProduce` before posting if you want to avoid partial-failure mid-run.\n- **`consumeMaterials` is atomic across BOM lines.** All per-line deductions and their audit rows run inside a single `stockService.withTransaction(...)` scope (powered by `@happyvertical/sql >= 0.74.0`'s native `db.transaction()`). An `InsufficientStockError` on line N+1 rolls back lines 1..N so production-order posting never leaves materials half-consumed. The recommended pre-flight (`BomService.canProduce(orderId, qty)`) is still useful when you'd rather know upfront than discover the shortfall mid-run, but a missed pre-flight no longer corrupts state.\n- **`consumeMaterials` + `produceFinishedGoods` are NOT jointly atomic.** Each opens its own transaction. A failure on the produce leg leaves materials deducted with no finished SKU receipt to balance it. Use `runProduction(order, { consume, produce })` when you need both legs to commit or roll back together.\n- **Cross-package references are plain strings.** `BillOfMaterials.productId`, `BomLine.componentSkuId` and `BomLine.bomId` are plain string ids (changing them to UUID references needs a migration window); the newer models (`RoutingStep`, `ProductionRun`, `ProductionRunCompletion`) reference this package's own models with `@foreignKey`. The package does depend on `smrt-products` (for `Assembly` and the resolve helper), but the bill schema does not couple to the catalog's table layout.\n- **`Assembly` fields are columns, not `Meta<T>`.** Unlike `Material`, its own fields are ordinary columns this package adds to `products` (filterable over REST). The PostgreSQL suite asserts they land there.\n- **`AssemblyCollection` lists exact `Assembly` rows.** An application subtype (e.g. one adding a customer) has its own `_meta_type`; read it through its own collection or `ProductCollection` (`resolveComponent` uses `instanceof Assembly`, so subtypes resolve as assemblies).\n- **`conflictColumns` include `tenant_id`** on both models. NULL-matching semantics are handled by `@happyvertical/sql >= 0.74.0`; two saves with the same `(product_id, version, NULL)` tuple merge in place.\n- **Lazy table creation.** Like everything else in SMRT, the `manufacturing_boms` and `manufacturing_bom_lines` tables are created on first DB op via `syncSchema`. Safe for SSR. A `BomLine` save now reads `product_skus` and `products` for the cycle check.\n- **Cross-industry constraint.** This package's vocabulary stays generic. Apparel-specific concepts (`Style`, `Makeup`, `Colorway`, `tech-pack`, fashion `Season`) and their analogues in furniture / automotive / CPG live in the relevant template package, never here. PRs that introduce industry vocabulary should be rejected.\n\n## Source attribution\n\nEvery emitted `StockMovement` carries `sourceType: 'ProductionOrder'` plus `sourceId: order.id` so downstream queries can reconstruct \"what caused this movement\". Reason codes used:\n\n| reasonCode | Emitter | Note |\n|---|---|---|\n| `production_consume` | `ProductionService.consumeMaterials` | One per BOM line per consume call |\n| `production_produce` | `ProductionService.produceFinishedGoods` | One per produce call |\n| either, with `sourceType: 'ProductionRunCompletion'` | `ProductionRunService.recordCompletion` | Only when the caller passes `consume` / `produce` |\n\nThese join cleanly with the standard inventory reason codes (`receipt`, `reservation`, `release`, `fulfillment`, `transfer_out`, `transfer_in`, `adjustment`) defined in `@happyvertical/smrt-inventory`.\n\n## Dependencies\n\n| Package | Purpose |\n|---|---|\n| `@happyvertical/smrt-core` | SmrtObject / SmrtCollection / DispatchBus |\n| `@happyvertical/smrt-inventory` | StockService, stock levels, movements (the `Sku` model itself lives in `@happyvertical/smrt-products`; inventory tracks stock motion against the id) |\n| `@happyvertical/smrt-products` | `Product` (the `Assembly` STI base), `Material`, `Sku` for the resolve helper and cycle check |\n| `@happyvertical/smrt-ui` / `smrt-types` | Svelte controls, i18n, module UI slots |\n| `@happyvertical/smrt-tenancy` | Optional tenant scoping |\n| `@happyvertical/sql` | Database adapter |\n",
   "moduleDocs": [