@happyvertical/smrt-manufacturing 0.30.0

package/dist/smrt-knowledge.json

@@ -0,0 +1,517 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-06-23T01:11:25.105Z",
+  "packageName": "@happyvertical/smrt-manufacturing",
+  "packageVersion": "0.30.0",
+  "sourceManifestPath": "dist/manifest.json",
+  "agentDocPath": "AGENTS.md",
+  "sourceHashes": {
+    "manifest": "c7139a33f23d351732a117c0a6fc3a8d0f49bc78a7833b795c1275a7d5f4b79f",
+    "packageJson": "ae801e6712daa107ee016fe85490a34323749ecf35794a8cc4f59ce25e050ccc",
+    "agents": "94d10408c859743730368f932f77e5602ebefb8fe9a8ac3178fa4b211e95ad29"
+  },
+  "exports": [
+    ".",
+    "./manifest",
+    "./manifest.json"
+  ],
+  "dependencies": {
+    "@happyvertical/logger": "catalog:",
+    "@happyvertical/smrt-core": "workspace:*",
+    "@happyvertical/smrt-inventory": "workspace:*",
+    "@happyvertical/smrt-tenancy": "workspace:*",
+    "@happyvertical/sql": "catalog:",
+    "@happyvertical/smrt-vitest": "workspace:*",
+    "@types/node": "25.0.9",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.17"
+  },
+  "smrtDependencies": [
+    "@happyvertical/smrt-core",
+    "@happyvertical/smrt-inventory",
+    "@happyvertical/smrt-tenancy",
+    "@happyvertical/smrt-vitest"
+  ],
+  "sdkDependencies": [
+    "@happyvertical/logger",
+    "@happyvertical/sql"
+  ],
+  "tags": [],
+  "risks": [],
+  "objects": [
+    {
+      "name": "BillOfMaterialsCollection",
+      "qualifiedName": "@happyvertical/smrt-manufacturing:BillOfMaterialsCollection",
+      "collection": "billofmaterialses",
+      "tableName": "manufacturing_boms",
+      "packageName": "@happyvertical/smrt-manufacturing",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findActiveForProduct",
+        "findByProduct",
+        "findByStatus"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "BomLineCollection",
+      "qualifiedName": "@happyvertical/smrt-manufacturing:BomLineCollection",
+      "collection": "bomlines",
+      "tableName": "manufacturing_bom_lines",
+      "packageName": "@happyvertical/smrt-manufacturing",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findByBom",
+        "findByComponent"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "BillOfMaterials",
+      "qualifiedName": "@happyvertical/smrt-manufacturing:BillOfMaterials",
+      "collection": "billofmaterialses",
+      "tableName": "manufacturing_boms",
+      "packageName": "@happyvertical/smrt-manufacturing",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "productId",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "version",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "effectiveDate",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "notes",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "currency",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "billofmaterialses.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials",
+          "path": "/billofmaterialses",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "billofmaterialses.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials",
+          "path": "/billofmaterialses/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "billofmaterialses.create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials",
+          "path": "/billofmaterialses",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "billofmaterialses.update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials",
+          "path": "/billofmaterialses/[id]",
+          "method": "PATCH"
+        },
+        {
+          "kind": "cli",
+          "name": "billofmaterials_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials"
+        },
+        {
+          "kind": "cli",
+          "name": "billofmaterials_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials"
+        },
+        {
+          "kind": "cli",
+          "name": "billofmaterials_create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials"
+        },
+        {
+          "kind": "cli",
+          "name": "billofmaterials_update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials"
+        },
+        {
+          "kind": "cli",
+          "name": "billofmaterials_delete",
+          "operation": "delete",
+          "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials"
+        },
+        {
+          "kind": "mcp",
+          "name": "billofmaterials_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials"
+        },
+        {
+          "kind": "mcp",
+          "name": "billofmaterials_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "BomLine",
+      "qualifiedName": "@happyvertical/smrt-manufacturing:BomLine",
+      "collection": "bomlines",
+      "tableName": "manufacturing_bom_lines",
+      "packageName": "@happyvertical/smrt-manufacturing",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "bomId",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "componentSkuId",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "qtyPerUnit",
+          "type": "decimal",
+          "required": false,
+          "columnType": "REAL"
+        },
+        {
+          "name": "uom",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "wastePercent",
+          "type": "decimal",
+          "required": false,
+          "columnType": "REAL"
+        },
+        {
+          "name": "notes",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "effectiveQtyPerUnit"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "bomlines.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-manufacturing:BomLine",
+          "path": "/bomlines",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "bomlines.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-manufacturing:BomLine",
+          "path": "/bomlines/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "bomlines.create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-manufacturing:BomLine",
+          "path": "/bomlines",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "bomlines.update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-manufacturing:BomLine",
+          "path": "/bomlines/[id]",
+          "method": "PATCH"
+        },
+        {
+          "kind": "cli",
+          "name": "bomline_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-manufacturing:BomLine"
+        },
+        {
+          "kind": "cli",
+          "name": "bomline_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-manufacturing:BomLine"
+        },
+        {
+          "kind": "cli",
+          "name": "bomline_create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-manufacturing:BomLine"
+        },
+        {
+          "kind": "cli",
+          "name": "bomline_update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-manufacturing:BomLine"
+        },
+        {
+          "kind": "cli",
+          "name": "bomline_delete",
+          "operation": "delete",
+          "objectName": "@happyvertical/smrt-manufacturing:BomLine"
+        },
+        {
+          "kind": "mcp",
+          "name": "bomline_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-manufacturing:BomLine"
+        },
+        {
+          "kind": "mcp",
+          "name": "bomline_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-manufacturing:BomLine"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    }
+  ],
+  "surfaces": [
+    {
+      "kind": "api",
+      "name": "billofmaterialses.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials",
+      "path": "/billofmaterialses",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "billofmaterialses.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials",
+      "path": "/billofmaterialses/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "billofmaterialses.create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials",
+      "path": "/billofmaterialses",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "billofmaterialses.update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials",
+      "path": "/billofmaterialses/[id]",
+      "method": "PATCH"
+    },
+    {
+      "kind": "cli",
+      "name": "billofmaterials_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials"
+    },
+    {
+      "kind": "cli",
+      "name": "billofmaterials_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials"
+    },
+    {
+      "kind": "cli",
+      "name": "billofmaterials_create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials"
+    },
+    {
+      "kind": "cli",
+      "name": "billofmaterials_update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials"
+    },
+    {
+      "kind": "cli",
+      "name": "billofmaterials_delete",
+      "operation": "delete",
+      "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials"
+    },
+    {
+      "kind": "mcp",
+      "name": "billofmaterials_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials"
+    },
+    {
+      "kind": "mcp",
+      "name": "billofmaterials_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-manufacturing:BillOfMaterials"
+    },
+    {
+      "kind": "api",
+      "name": "bomlines.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-manufacturing:BomLine",
+      "path": "/bomlines",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "bomlines.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-manufacturing:BomLine",
+      "path": "/bomlines/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "bomlines.create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-manufacturing:BomLine",
+      "path": "/bomlines",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "bomlines.update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-manufacturing:BomLine",
+      "path": "/bomlines/[id]",
+      "method": "PATCH"
+    },
+    {
+      "kind": "cli",
+      "name": "bomline_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-manufacturing:BomLine"
+    },
+    {
+      "kind": "cli",
+      "name": "bomline_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-manufacturing:BomLine"
+    },
+    {
+      "kind": "cli",
+      "name": "bomline_create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-manufacturing:BomLine"
+    },
+    {
+      "kind": "cli",
+      "name": "bomline_update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-manufacturing:BomLine"
+    },
+    {
+      "kind": "cli",
+      "name": "bomline_delete",
+      "operation": "delete",
+      "objectName": "@happyvertical/smrt-manufacturing:BomLine"
+    },
+    {
+      "kind": "mcp",
+      "name": "bomline_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-manufacturing:BomLine"
+    },
+    {
+      "kind": "mcp",
+      "name": "bomline_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-manufacturing:BomLine"
+    }
+  ],
+  "prompts": [],
+  "relationshipsV2": {
+    "foreignKeyFields": 0,
+    "crossPackageRefFields": 0,
+    "junctionCollections": 0,
+    "hierarchicalObjects": 0,
+    "polymorphicAssociations": 0,
+    "uuidColumns": 6
+  },
+  "agentDoc": "# @happyvertical/smrt-manufacturing\n\nBills of materials, cost rollup, and production-order operations. 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 works alongside the `ProductionOrder` Contract STI subtype already shipped in `@happyvertical/smrt-commerce`.\n\n## Models\n\n| Model | Purpose |\n|---|---|\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\nBoth models are `@TenantScoped({ mode: 'optional' })` with a nullable `tenantId` so they can be used either tenant-scoped or globally.\n\n`RoutingStep` (labor cost) is intentionally out of scope for v1 — see issue [#1245](https://github.com/happyvertical/smrt/issues/1245) for the planned follow-up.\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## 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()`. Keeps the dependency graph DAG-shaped and lets each upstream package evolve independently.\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.\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-tenancy` | Optional tenant scoping |\n| `@happyvertical/sql` | Database adapter |\n"
+}

package/dist/types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Shared types and error classes for `@happyvertical/smrt-manufacturing`.
+ *
+ * Strictly industry-neutral. The same vocabulary serves apparel, furniture,
+ * automotive, CPG, electronics, food production, custom hardware, and any
+ * other vertical that builds finished goods from raw inputs by recipe.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Aggregate cost rollup returned by {@link BomService.computeMaterialCost}.
+ */
+export declare interface BomCostRollup {
+    /** BOM that was rolled up. */
+    bomId: string;
+    /** Total material cost per produced unit. */
+    totalCost: number;
+    /** ISO 4217 currency code. Defaults to `'USD'`. */
+    currency: string;
+    /** Per-line breakdown. Empty array when the BOM has no lines. */
+    lineBreakdown: BomLineCost[];
+    /**
+     * `true` when at least one line's unit cost could not be resolved.
+     * Callers should treat `totalCost` as a lower bound in that case.
+     */
+    hasMissingCosts: boolean;
+}
+
+/**
+ * Per-line cost breakdown returned by {@link BomService.computeMaterialCost}.
+ * Lets callers surface "here's where the $42 came from" UIs without
+ * recomputing on the client.
+ */
+export declare interface BomLineCost {
+    /**
+     * Plain string reference to a component SKU id. The `Sku` model
+     * itself lives in `@happyvertical/smrt-products`; inventory only
+     * tracks stock motion against that id.
+     */
+    componentSkuId: string;
+    /** Quantity per produced unit (pre-waste). */
+    qtyPerUnit: number;
+    /** Waste percent applied to this line (`0` if none). */
+    wastePercent: number;
+    /** Effective quantity used per produced unit, including waste. */
+    effectiveQty: number;
+    /** Latest known unit cost, or `0` if unavailable. */
+    unitCost: number;
+    /** Effective unit-cost contribution to the rolled-up total. */
+    lineCost: number;
+    /** Unit of measure as declared on the line (`'yards'`, `'each'`, ...). */
+    uom: string;
+    /**
+     * `true` when the unit cost could not be resolved from upstream
+     * `smrt-products`. The line still contributes `0` to the total; the
+     * flag lets UIs warn the user that the cost rollup is incomplete.
+     */
+    costUnavailable: boolean;
+}
+
+/**
+ * Thrown when a service operation needs to resolve a BOM by id but the row
+ * does not exist. Carries the requested id so callers can surface a
+ * meaningful message.
+ */
+export declare class BomNotFoundError extends Error {
+    readonly bomId: string;
+    name: string;
+    constructor(bomId: string);
+}
+
+/**
+ * Lifecycle state of a {@link BillOfMaterials}.
+ *
+ * - `draft` — under construction; not yet released for production. Cost
+ *   rollups can still be computed, but the BOM should not yet be referenced
+ *   by a production order.
+ * - `active` — currently in use. New production orders should reference the
+ *   active BOM for a given product.
+ * - `superseded` — an older revision that has been replaced by a newer
+ *   `active` BOM. Historical production orders may still reference the
+ *   superseded row for audit, but no new orders should pick it up.
+ */
+export declare type BomStatus = 'draft' | 'active' | 'superseded';
+
+/**
+ * Result returned by {@link BomService.canProduce}.
+ *
+ * `ok: true` means every material requirement is currently covered by
+ * available stock; `ok: false` means at least one component is short.
+ */
+export declare type CanProduceResult = {
+    ok: true;
+    shortages: [];
+} | {
+    ok: false;
+    shortages: MaterialShortage[];
+};
+
+/**
+ * A single entry on a requirements explosion. Multiple BOM lines pointing
+ * at the same component SKU are summed.
+ */
+export declare interface MaterialRequirement {
+    /** Plain string reference to the required component {@link Sku}. */
+    componentSkuId: string;
+    /** Total quantity needed across the full production run (waste included). */
+    totalQty: number;
+    /** Unit of measure carried over from the originating BOM line(s). */
+    uom: string;
+}
+
+/**
+ * A single shortage discovered by {@link BomService.canProduce}.
+ */
+export declare interface MaterialShortage {
+    /** Plain string reference to the missing component {@link Sku}. */
+    componentSkuId: string;
+    /** Total quantity required for the requested production run. */
+    requested: number;
+    /** Available stock across all locations (`available` state). */
+    available: number;
+}
+
+/**
+ * Thrown when a production-order operation needs a BOM to plan against but
+ * no active BOM is currently registered for the production order's
+ * `productId`. The caller should either link a BOM by passing one in
+ * explicitly or activate one for the given product.
+ */
+export declare class NoActiveBomForProductError extends Error {
+    readonly productId: string;
+    name: string;
+    constructor(productId: string);
+}
+
+export { }