@happyvertical/smrt-manufacturing 0.53.5 → 0.53.6

package/dist/smrt-knowledge.json

@@ -3,13 +3,14 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-manufacturing",
-  "packageVersion": "0.53.5",
+  "packageVersion": "0.53.6",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "c759bf5fb3f31d0d65da9b204e8d57a5b3c33210858c469d56b9835bccd551c2",
-    "packageJson": "e8b753814d42f7be3144fc1e6af8cbf038a00049e73a370dac674326e4396d24",
-    "agents": "8570930d07b32c59b20d9f4e69e5579395e6b8d2382b7303e17c36ba2e598097"
+    "manifest": "14da998a347684165c850751fd725040b4b68aef3ad189df41dd45f74b415dd9",
+    "packageJson": "deef24b4b78a758c9be6f5c83885f321c441f7cc580c4497fc02819ff92613c1",
+    "agents": "de169f8ea3f02692b4c6c05d8706b1b9dc7fae8373bc16e0eb5d364938a07bee",
+    "moduleDoc:agents/multilevel-and-runs.md": "544d519356801f3cb3beb9e6d49a3e0eec93fdddf3f56150cf3141f766f98c9d"
   },
   "exports": [
     ".",
@@ -334,6 +335,135 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "ProductionRunCollection",
+      "qualifiedName": "@happyvertical/smrt-manufacturing:ProductionRunCollection",
+      "collection": "productionruns",
+      "tableName": "manufacturing_production_runs",
+      "packageName": "@happyvertical/smrt-manufacturing",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findByBom",
+        "findByStatus"
+      ],
+      "methodSignatures": [
+        {
+          "name": "findByBom",
+          "async": true,
+          "params": [
+            "bomId: string"
+          ],
+          "returns": "Promise<ProductionRun[]>"
+        },
+        {
+          "name": "findByStatus",
+          "async": true,
+          "params": [
+            "status: ProductionRunStatus"
+          ],
+          "returns": "Promise<ProductionRun[]>"
+        }
+      ],
+      "surfaces": [
+        {
+          "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"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "ProductionRunCompletionCollection",
+      "qualifiedName": "@happyvertical/smrt-manufacturing:ProductionRunCompletionCollection",
+      "collection": "productionruncompletions",
+      "tableName": "manufacturing_production_run_completions",
+      "packageName": "@happyvertical/smrt-manufacturing",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findByRun"
+      ],
+      "methodSignatures": [
+        {
+          "name": "findByRun",
+          "async": true,
+          "params": [
+            "runId: string"
+          ],
+          "returns": "Promise<ProductionRunCompletion[]>"
+        }
+      ],
+      "surfaces": [
+        {
+          "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"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "RoutingStepCollection",
       "qualifiedName": "@happyvertical/smrt-manufacturing:RoutingStepCollection",
@@ -1192,6 +1322,236 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "ProductionRun",
+      "qualifiedName": "@happyvertical/smrt-manufacturing:ProductionRun",
+      "collection": "productionruns",
+      "tableName": "manufacturing_production_runs",
+      "packageName": "@happyvertical/smrt-manufacturing",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "bomId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "BillOfMaterials",
+          "columnType": "UUID"
+        },
+        {
+          "name": "targetQty",
+          "type": "decimal",
+          "required": false,
+          "columnType": "REAL"
+        },
+        {
+          "name": "completedQty",
+          "type": "decimal",
+          "required": false,
+          "columnType": "REAL"
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "default": "planned"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "bomId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "BillOfMaterials",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "remainingQty"
+      ],
+      "methodSignatures": [
+        {
+          "name": "remainingQty",
+          "returns": "number"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "optional",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "productionruns.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-manufacturing:ProductionRun",
+          "path": "/productionruns",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "productionruns.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-manufacturing:ProductionRun",
+          "path": "/productionruns/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "cli",
+          "name": "productionrun_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-manufacturing:ProductionRun"
+        },
+        {
+          "kind": "cli",
+          "name": "productionrun_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-manufacturing:ProductionRun"
+        },
+        {
+          "kind": "mcp",
+          "name": "productionrun_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-manufacturing:ProductionRun"
+        },
+        {
+          "kind": "mcp",
+          "name": "productionrun_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-manufacturing:ProductionRun"
+        }
+      ],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "remainingQty",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-manufacturing:ProductionRun"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "ProductionRunCompletion",
+      "qualifiedName": "@happyvertical/smrt-manufacturing:ProductionRunCompletion",
+      "collection": "productionruncompletions",
+      "tableName": "manufacturing_production_run_completions",
+      "packageName": "@happyvertical/smrt-manufacturing",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "runId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "ProductionRun",
+          "columnType": "UUID"
+        },
+        {
+          "name": "qty",
+          "type": "decimal",
+          "required": false,
+          "columnType": "REAL"
+        },
+        {
+          "name": "completedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "runId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "ProductionRun",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [],
+      "tenant": {
+        "scoped": true,
+        "mode": "optional",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "productionruncompletions.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletion",
+          "path": "/productionruncompletions",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "productionruncompletions.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletion",
+          "path": "/productionruncompletions/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "cli",
+          "name": "productionruncompletion_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletion"
+        },
+        {
+          "kind": "cli",
+          "name": "productionruncompletion_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletion"
+        },
+        {
+          "kind": "mcp",
+          "name": "productionruncompletion_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletion"
+        },
+        {
+          "kind": "mcp",
+          "name": "productionruncompletion_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletion"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "RoutingStep",
       "qualifiedName": "@happyvertical/smrt-manufacturing:RoutingStep",
@@ -1477,6 +1837,66 @@
       "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",
@@ -1815,6 +2235,86 @@
       "operation": "get",
       "objectName": "@happyvertical/smrt-manufacturing:Operation"
     },
+    {
+      "kind": "api",
+      "name": "productionruns.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-manufacturing:ProductionRun",
+      "path": "/productionruns",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "productionruns.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-manufacturing:ProductionRun",
+      "path": "/productionruns/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "cli",
+      "name": "productionrun_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-manufacturing:ProductionRun"
+    },
+    {
+      "kind": "cli",
+      "name": "productionrun_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-manufacturing:ProductionRun"
+    },
+    {
+      "kind": "mcp",
+      "name": "productionrun_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-manufacturing:ProductionRun"
+    },
+    {
+      "kind": "mcp",
+      "name": "productionrun_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-manufacturing:ProductionRun"
+    },
+    {
+      "kind": "api",
+      "name": "productionruncompletions.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletion",
+      "path": "/productionruncompletions",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "productionruncompletions.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletion",
+      "path": "/productionruncompletions/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "cli",
+      "name": "productionruncompletion_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletion"
+    },
+    {
+      "kind": "cli",
+      "name": "productionruncompletion_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletion"
+    },
+    {
+      "kind": "mcp",
+      "name": "productionruncompletion_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletion"
+    },
+    {
+      "kind": "mcp",
+      "name": "productionruncompletion_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-manufacturing:ProductionRunCompletion"
+    },
     {
       "kind": "api",
       "name": "routingsteps.list",
@@ -1876,12 +2376,19 @@
   ],
   "prompts": [],
   "relationshipsV2": {
-    "foreignKeyFields": 3,
+    "foreignKeyFields": 5,
     "crossPackageRefFields": 1,
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 25
+    "uuidColumns": 37
   },
-  "agentDoc": "# @happyvertical/smrt-manufacturing\n\nBills of materials, operations and routing, cost and labour rollup, 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| `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`), only that tenant's bills count, and `resolveComponent` reports another tenant's SKU, product or bill line as `missing` (global rows stay visible), 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## Svelte components (`./svelte`)\n\nProps-driven; the host loads and persists. `AssemblyList` (field policy drops hidden columns via `policyToVisibleColumnIds`), `AssemblyForm` (smrt-fields `ObjectForm` for `@happyvertical/smrt-manufacturing:Assembly`, so price and every other field follow the consumer's field policy), `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). Adapters: `toAssemblyView`, `toBomEditorLines`. 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\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'` + 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`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.** `productId`, `componentSkuId`, `bomId` (within this package) — all plain string ids, never `@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\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-fields` | `ObjectForm` and field-policy column visibility for the Svelte components |\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"
+  "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` (field policy drops hidden columns via `policyToVisibleColumnIds`), `AssemblyForm` (smrt-fields `ObjectForm` for `@happyvertical/smrt-manufacturing:Assembly`, so price and every other field follow the consumer's field policy), `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; rows from `toProductionRunView`), `RequirementsTree` (read-only `explode` / `planRequirements` result by level with totals; `toRequirementTree`, `toRequirementTotals`; internal `RequirementsTreeLevel`). Adapters: `toAssemblyView`, `toBomEditorLines`. 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-fields` | `ObjectForm` and field-policy column visibility for the Svelte components |\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": [
+    {
+      "path": "agents/multilevel-and-runs.md",
+      "module": "multilevel-and-runs",
+      "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"
+    }
+  ]
 }