@happyvertical/smrt-manufacturing 0.57.34 → 0.57.35

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-manufacturing",
-  "packageVersion": "0.57.34",
+  "packageVersion": "0.57.35",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "7633fe751d3d69c6a69649d986f3489e5909a1a5b739ac6477a7d4911d2f5fb9",
-    "packageJson": "77c1fd1edf2ae9570f7ec59f21635ec45ebffe4fb17b81bc30425f6bb1aa66e9",
+    "manifest": "7d5d0a17b1b1cd075cd19b14cd1c9b09ebb8283bd663fc19e135de0fdeafec2f",
+    "packageJson": "0254c9ddadb3748487ebb0b67f397a89091651d945b426cc069168cf00ba57d8",
     "agents": "53bbb8d8dfd7e1dbd438a4ad1559be8cd1ad8ed46c726d5498d2dda5b3535054",
     "moduleDoc:agents/multilevel-and-runs.md": "544d519356801f3cb3beb9e6d49a3e0eec93fdddf3f56150cf3141f766f98c9d"
   },
@@ -553,21 +553,24 @@
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "About how many minutes it takes to make one."
         },
         {
           "name": "defaultOperationId",
           "type": "foreignKey",
           "required": false,
           "related": "Operation",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The kind of work usually booked to this assembly."
         },
         {
           "name": "partReference",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "Your own drawing or part number for this assembly."
         }
       ],
       "relationships": [
@@ -822,34 +825,39 @@
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The assembly this list of parts is for."
         },
         {
           "name": "version",
           "type": "integer",
           "required": true,
           "columnType": "INTEGER",
-          "default": 1
+          "default": 1,
+          "description": "The revision number, so you can change a list and keep the old one."
         },
         {
           "name": "effectiveDate",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "The day this list starts to be used."
         },
         {
           "name": "status",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": "draft"
+          "default": "draft",
+          "description": "Whether this list is a draft, in use or retired."
         },
         {
           "name": "notes",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "Anything people making it should know."
         },
         {
           "name": "currency",
@@ -972,27 +980,31 @@
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The list of parts this line belongs to."
         },
         {
           "name": "componentSkuId",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The part that goes into the assembly."
         },
         {
           "name": "qtyPerUnit",
           "type": "decimal",
           "required": false,
-          "columnType": "REAL"
+          "columnType": "REAL",
+          "description": "How much of this part goes into one unit."
         },
         {
           "name": "uom",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "each"
+          "default": "each",
+          "description": "What the amount is counted in, such as each or kilograms."
         },
         {
           "name": "wastePercent",
@@ -1145,21 +1157,24 @@
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "A short code for this kind of work."
         },
         {
           "name": "name",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What this kind of work is called, such as cutting."
         },
         {
           "name": "category",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "A group to sort similar work together."
         },
         {
           "name": "isActive",
@@ -1272,26 +1287,30 @@
           "type": "foreignKey",
           "required": true,
           "related": "BillOfMaterials",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The list of parts this run makes from."
         },
         {
           "name": "targetQty",
           "type": "decimal",
           "required": false,
-          "columnType": "REAL"
+          "columnType": "REAL",
+          "description": "How many you plan to make."
         },
         {
           "name": "completedQty",
           "type": "decimal",
           "required": false,
-          "columnType": "REAL"
+          "columnType": "REAL",
+          "description": "How many have been finished so far."
         },
         {
           "name": "status",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": "planned"
+          "default": "planned",
+          "description": "Whether the run is planned, under way, done or cancelled."
         }
       ],
       "relationships": [
@@ -1399,19 +1418,22 @@
           "type": "foreignKey",
           "required": true,
           "related": "ProductionRun",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The production run this batch belongs to."
         },
         {
           "name": "qty",
           "type": "decimal",
           "required": false,
-          "columnType": "REAL"
+          "columnType": "REAL",
+          "description": "How many were finished in this batch."
         },
         {
           "name": "completedAt",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "When this batch was finished."
         }
       ],
       "relationships": [
@@ -1502,27 +1524,31 @@
           "type": "foreignKey",
           "required": true,
           "related": "BillOfMaterials",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The list of parts this step is part of."
         },
         {
           "name": "operationId",
           "type": "foreignKey",
           "required": true,
           "related": "Operation",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The kind of work done in this step."
         },
         {
           "name": "sequence",
           "type": "integer",
           "required": true,
           "columnType": "INTEGER",
-          "default": 1
+          "default": 1,
+          "description": "The order of this step, starting at 1."
         },
         {
           "name": "estimatedMinutes",
           "type": "decimal",
           "required": false,
-          "columnType": "REAL"
+          "columnType": "REAL",
+          "description": "About how many minutes this step takes."
         },
         {
           "name": "notes",
@@ -2124,6 +2150,342 @@
       "content": "# Multi-level walks and production runs\n\nDetail for `services/structure-walk.ts`, the multi-level forms of `BomService`, and `ProductionRunService`. Orientation and gotchas stay in the package [AGENTS.md](../AGENTS.md).\n\n## Multi-level walks (sub-assemblies)\n\nEvery `BomService` method takes `{ levels }` (`1` by default: the single-level behaviour, unchanged; a number up to `MAX_EXPLOSION_DEPTH` = 32; or `'all'`). The walk is `services/structure-walk.ts`, shared by all of them: resolve each line through `AssemblyService.resolveComponent` (in the top bill's tenant), open an assembly's active bill while `levels` allows, stop at materials, bought items, missing components and assemblies without an active bill.\n\n| Method | Multi-level behaviour |\n|---|---|\n| `explode(bomId, qty, { levels })` | Gross: every line depth first with `level`, `path` (bills from the top), `totalQty` (waste compounds: a child is the parent line's quantity times its own effective quantity), `buildable`, `expanded`; `totals` sums the lines not opened per SKU (first unit kept, as before). |\n| `planRequirements(bomId, qty, { levels })` | Net: per line, `available` stock not yet allocated to an earlier line and `short`; a short buildable sub-assembly is opened for the shortfall only. Lines short and not opened are `shortages`, each at its own level. Facts only: no make-or-buy policy. |\n| `explodeRequirements` / `canProduce` | `explode().totals` / the plan's shortages (`level`, `path`, `uom`, `buildable` added). |\n| `computeMaterialCost` | An opened sub-assembly is costed from its bill (`subBomId`, nested `components`); a missing price below marks it. A sub-assembly bill in another currency is not added: its line is priced through the resolver. |\n| `computeLabourEstimate` | Adds each opened sub-assembly's routing times its units per top unit (`subAssemblies`); `steps` stays the top routing. Minutes always count; cost from a bill in another currency does not, and sets `hasMissingRates`. |\n\nSafety: a loop already in stored data (written around the save-time refusal) fails with `BomStructureCycleError` (a `BomCycleError`) naming it; `'all'` past 32 levels or a walk past `MAX_EXPLOSION_LINES` (10,000, counted per use of a shared sub-assembly) fails with `BomExplosionLimitError`. Stock in a plan is summed across locations, as in `canProduce`, counting only the top bill's tenant's rows and global ones (like the lines the walk reads), whatever tenant context is active.\n\n## Production runs\n\n`ProductionRunService` (`createRun({ bomId } | { productId }, targetQty)`, `start`, `recordCompletion`, `finish`, `cancel`, `setTarget`, `get`, `listCompletions`). Every write is one transaction that saves the run row first; the revision-guarded save locks it, and a concurrent writer's conflict reruns its whole transaction (up to 10 attempts), so concurrent completions all count and never pass the target. The service refuses an adapter without `transaction()`; it never falls back to step-by-step writes.\n\n- Tenant: every structure read goes through `src/tenant-scope.ts`: list reads run in `withTenantGlobalRead` for the owning tenant (its rows plus global rows; a tenant context alone would hide global rows, no context would show every tenant's) and keep own-or-global rows. Routing and operations in `computeLabourEstimate`, and the top bill itself under a tenant context, are read the same way. `createRun` reads the active tenant's bills and global ones (no context: global bills only, by `productId` or `bomId`). The run takes its bill's tenant; a completion takes the run's; stock legs run inside `withTenant(run.tenantId)`, so the bill's lines and the levels read and written are that tenant's whatever the caller's context. `ProductionService` consumes only a bill's own tenant's lines and global ones (a global bill: global lines only), for every caller; a global run's stock legs run in the caller's context.\n- A completion moves no stock unless asked. With `consume` / `produce` it calls `ProductionService` (`runProduction` for both) on the transaction's stock service, stamping movements `sourceType: 'ProductionRunCompletion'` with the completion id; a shortfall rolls the completion back. Consumption is the run's bill's own lines: a sub-assembly is taken from stock, and building it is its own run.\n- Quantities are kept to `QUANTITY_DECIMALS` (6) places, never compared with a tolerance. A run's target, completed quantity and each report are summed and compared as whole millionths, exactly; a run accepts quantities up to `MAX_QUANTITY` (999,999,999, so every value has at most 15 significant digits and survives a double exactly) and refuses one that rounds to zero. A plan's `short` is rounded with `roundQuantity`.\n- Reaching the target marks the run `done`; `finish` closes it short; `cancel` keeps its completions; `setTarget` cannot go below what is done.\n- Why not commerce `ProductionOrder`: that is a `Contract` (terms, money, customer or vendor, a contract status flow), owned by `smrt-commerce`, which this package does not depend on. A run is the shop-floor record of building; one order may need several runs, and make-to-stock needs none. An application that has both links them.\n- Deliberately absent (nothing here would use them): a link to an order, who did the work, a location on the run (passed per call, as in `ProductionService`).\n"
     }
   ],
+  "recipes": [
+    {
+      "id": "manufacturing.assemblies",
+      "className": "AssembliesRecipe",
+      "label": "Assemblies",
+      "summary": "Define what you make, what goes into it and the steps to make it.",
+      "synonyms": [
+        "bill of materials",
+        "bills of materials",
+        "bom",
+        "recipes",
+        "products you make",
+        "routing"
+      ],
+      "models": [
+        "@happyvertical/smrt-manufacturing:Assembly",
+        "@happyvertical/smrt-manufacturing:BillOfMaterials",
+        "@happyvertical/smrt-manufacturing:BomLine",
+        "@happyvertical/smrt-manufacturing:Operation",
+        "@happyvertical/smrt-manufacturing:RoutingStep"
+      ],
+      "nav": [
+        {
+          "label": "Assemblies",
+          "model": "@happyvertical/smrt-manufacturing:Assembly",
+          "icon": "package",
+          "description": "The things you make, each built from parts.",
+          "noun": "assembly"
+        },
+        {
+          "label": "Bills of materials",
+          "model": "@happyvertical/smrt-manufacturing:BillOfMaterials",
+          "icon": "fileText",
+          "description": "The list of parts and amounts that go into each assembly.",
+          "noun": "bill of materials"
+        },
+        {
+          "label": "Operations",
+          "model": "@happyvertical/smrt-manufacturing:Operation",
+          "icon": "wrench",
+          "description": "The kinds of work done to make something, like cutting."
+        }
+      ],
+      "requires": [],
+      "requiresAny": [
+        [
+          "products.simple",
+          "products.clothing"
+        ]
+      ],
+      "section": {
+        "id": "make",
+        "label": "Make",
+        "icon": "wrench",
+        "description": "Make what you sell from the parts you hold."
+      },
+      "options": {
+        "@happyvertical/smrt-manufacturing:Assembly": {
+          "fields": {
+            "name": {
+              "order": 1
+            },
+            "partReference": {
+              "order": 2
+            },
+            "description": {
+              "order": 3
+            },
+            "price": {
+              "order": 4
+            },
+            "estimatedLabourMinutes": {
+              "label": "Minutes to make one",
+              "order": 5
+            },
+            "defaultOperationId": {
+              "label": "Usual operation",
+              "order": 6
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            },
+            "productType": {
+              "visibility": "hidden"
+            },
+            "category": {
+              "visibility": "advanced"
+            },
+            "manufacturer": {
+              "visibility": "hidden"
+            },
+            "model": {
+              "visibility": "hidden"
+            },
+            "inStock": {
+              "visibility": "hidden",
+              "default": true
+            },
+            "specifications": {
+              "visibility": "hidden"
+            },
+            "tags": {
+              "visibility": "advanced"
+            },
+            "defaultSalesTaxCodeId": {
+              "visibility": "hidden"
+            },
+            "defaultPurchaseTaxCodeId": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-manufacturing:BillOfMaterials": {
+          "fields": {
+            "productId": {
+              "label": "Assembly",
+              "order": 1
+            },
+            "version": {
+              "order": 2
+            },
+            "status": {
+              "order": 3
+            },
+            "effectiveDate": {
+              "order": 4
+            },
+            "notes": {
+              "order": 5
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            },
+            "currency": {
+              "visibility": "advanced"
+            }
+          }
+        },
+        "@happyvertical/smrt-manufacturing:BomLine": {
+          "fields": {
+            "bomId": {
+              "label": "Bill of materials",
+              "order": 1
+            },
+            "componentSkuId": {
+              "label": "Part",
+              "order": 2
+            },
+            "qtyPerUnit": {
+              "label": "Amount per unit",
+              "order": 3
+            },
+            "uom": {
+              "label": "Unit of measure",
+              "order": 4
+            },
+            "wastePercent": {
+              "visibility": "advanced"
+            },
+            "notes": {
+              "visibility": "advanced"
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-manufacturing:Operation": {
+          "fields": {
+            "name": {
+              "order": 1
+            },
+            "code": {
+              "order": 2
+            },
+            "category": {
+              "order": 3
+            },
+            "isActive": {
+              "visibility": "advanced"
+            },
+            "requiredQualificationId": {
+              "visibility": "advanced"
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-manufacturing:RoutingStep": {
+          "fields": {
+            "bomId": {
+              "label": "Bill of materials",
+              "order": 1
+            },
+            "operationId": {
+              "label": "Operation",
+              "order": 2
+            },
+            "sequence": {
+              "label": "Step number",
+              "order": 3
+            },
+            "estimatedMinutes": {
+              "order": 4
+            },
+            "notes": {
+              "visibility": "advanced"
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            }
+          }
+        }
+      },
+      "help": {
+        "markdown": "## Overview\n\nAssemblies is where you describe what you make. An assembly is a product built\nfrom parts. Its bill of materials lists those parts and how much of each goes\ninto one unit, and its steps say which operations, such as cutting or painting,\nit passes through and how long each takes.\n\n## Tasks\n\n### Add something you make\n\n1. Open the list of assemblies and choose **New**.\n2. Give it a **{field:Assembly.name}** and your own **{field:Assembly.partReference}**, such as a drawing or part number.\n3. Note roughly how long one takes in **{field:Assembly.estimatedLabourMinutes}**.\n4. Save.\n\n### List what goes into it\n\n1. Open the bills of materials and choose **New**.\n2. Pick the **{field:BillOfMaterials.productId}** the list is for.\n3. Save, then add a line for each part.\n4. For each line pick the **{field:BomLine.componentSkuId}** and set the **{field:BomLine.qtyPerUnit}** that goes into one unit.\n\n### Change how something is made\n\n1. Create a new bill of materials with a higher **{field:BillOfMaterials.version}**.\n2. Set its **{field:BillOfMaterials.status}** to active when it is ready to use.\n3. Set the old version's **{field:BillOfMaterials.status}** to superseded so only one version is in use.\n4. The old version stays on file, so past runs still make sense.\n\n### See the kinds of work\n\nOperations are set up by the manufacturing service, not by hand in the app.\n\n1. Open the operations.\n2. Read each **{field:Operation.name}** and its short **{field:Operation.code}**.\n3. The steps of a bill of materials use these, each with its **{field:RoutingStep.estimatedMinutes}**.\n",
+        "fieldRefs": [
+          "Assembly.estimatedLabourMinutes",
+          "Assembly.name",
+          "Assembly.partReference",
+          "BillOfMaterials.productId",
+          "BillOfMaterials.status",
+          "BillOfMaterials.version",
+          "BomLine.componentSkuId",
+          "BomLine.qtyPerUnit",
+          "Operation.code",
+          "Operation.name",
+          "RoutingStep.estimatedMinutes"
+        ]
+      },
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "Needs a server because its package depends on @happyvertical/smrt-products, @happyvertical/smrt-tenancy, which do not build for a browser (#3616, #3624, #3626)."
+        ]
+      }
+    },
+    {
+      "id": "manufacturing.production",
+      "className": "ProductionRecipe",
+      "label": "Production",
+      "summary": "Plan how many to make, record what came out and see each run through to done.",
+      "synonyms": [
+        "production runs",
+        "work orders",
+        "manufacturing",
+        "batches",
+        "build orders"
+      ],
+      "models": [
+        "@happyvertical/smrt-manufacturing:ProductionRun",
+        "@happyvertical/smrt-manufacturing:ProductionRunCompletion"
+      ],
+      "nav": [
+        {
+          "label": "Production runs",
+          "model": "@happyvertical/smrt-manufacturing:ProductionRun",
+          "icon": "layers",
+          "description": "Each batch you plan to make, and how far along it is.",
+          "noun": "production run"
+        }
+      ],
+      "requires": [
+        "manufacturing.assemblies"
+      ],
+      "section": {
+        "id": "make",
+        "label": "Make",
+        "icon": "wrench",
+        "description": "Make what you sell from the parts you hold."
+      },
+      "options": {
+        "@happyvertical/smrt-manufacturing:ProductionRun": {
+          "fields": {
+            "bomId": {
+              "label": "Bill of materials",
+              "order": 1
+            },
+            "targetQty": {
+              "label": "How many to make",
+              "order": 2
+            },
+            "completedQty": {
+              "label": "How many made so far",
+              "locked": true,
+              "order": 3
+            },
+            "status": {
+              "locked": true,
+              "order": 4
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-manufacturing:ProductionRunCompletion": {
+          "fields": {
+            "runId": {
+              "label": "Production run",
+              "order": 1
+            },
+            "qty": {
+              "label": "How many finished",
+              "order": 2
+            },
+            "completedAt": {
+              "label": "Finished on",
+              "order": 3
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            }
+          }
+        }
+      },
+      "help": {
+        "markdown": "## Overview\n\nProduction is where you plan and follow what you make. A production run says\nhow many of an assembly you intend to make, using one of its bills of\nmaterials. As batches come off the line they are recorded against it, and the run\nkeeps count until it is done.\n\n## Tasks\n\nProduction runs and their finished batches are created and updated by the\nproduction service, not by hand in the app. Here you follow them.\n\n### Find a run\n\n1. Open the production runs.\n2. Check the **{field:ProductionRun.bomId}** it makes from and the **{field:ProductionRun.targetQty}** you want.\n\n### See how a run is going\n\nOpen the run and compare **{field:ProductionRun.completedQty}** with\n**{field:ProductionRun.targetQty}**. Its **{field:ProductionRun.status}** shows\nwhether it is planned, under way, finished or cancelled.\n\n### See what was finished\n\n1. Open the run's finished batches.\n2. Each one shows the **{field:ProductionRunCompletion.runId}** it belongs to and **{field:ProductionRunCompletion.qty}**, how many came out.\n",
+        "fieldRefs": [
+          "ProductionRun.bomId",
+          "ProductionRun.completedQty",
+          "ProductionRun.status",
+          "ProductionRun.targetQty",
+          "ProductionRunCompletion.qty",
+          "ProductionRunCompletion.runId"
+        ]
+      },
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "Needs a server because its package depends on @happyvertical/smrt-products, @happyvertical/smrt-tenancy, which do not build for a browser (#3616, #3624, #3626)."
+        ]
+      }
+    }
+  ],
   "browser": {
     "status": "server-only",
     "issues": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-manufacturing",
-  "version": "0.57.34",
+  "version": "0.57.35",
   "smrtJsdoc": "strict",
   "description": "Bills of materials, cost rollup, and production-order operations for the SMRT framework — strictly industry-neutral",
   "type": "module",
@@ -36,12 +36,12 @@
   },
   "dependencies": {
     "@happyvertical/logger": "^0.108.0",
-    "@happyvertical/smrt-core": "0.57.34",
-    "@happyvertical/smrt-inventory": "0.57.34",
-    "@happyvertical/smrt-products": "0.57.34",
-    "@happyvertical/smrt-tenancy": "0.57.34",
-    "@happyvertical/smrt-types": "0.57.34",
-    "@happyvertical/smrt-ui": "0.57.34",
+    "@happyvertical/smrt-core": "0.57.35",
+    "@happyvertical/smrt-inventory": "0.57.35",
+    "@happyvertical/smrt-products": "0.57.35",
+    "@happyvertical/smrt-tenancy": "0.57.35",
+    "@happyvertical/smrt-types": "0.57.35",
+    "@happyvertical/smrt-ui": "0.57.35",
     "@happyvertical/sql": "^0.108.0"
   },
   "peerDependencies": {
@@ -53,7 +53,7 @@
     }
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.57.34",
+    "@happyvertical/smrt-vitest": "0.57.35",
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.3.0",
     "@types/node": "24.13.6",