@happyvertical/smrt-inventory 0.57.17 → 0.57.19

package/dist/smrt-knowledge.json

@@ -3,13 +3,13 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-inventory",
-  "packageVersion": "0.57.17",
+  "packageVersion": "0.57.19",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "89c77cddd4a5f37b270505d1831f7c1ac37a4d516840067fcf0eb8a8c3abafd9",
-    "packageJson": "3865e5594d72f0a47e83859abe79377a37e6f1dd418d326eb407df7121bb7ab3",
-    "agents": "382e62dd5529521207b202de207956f67fdce6c894b8964ef4e58c85a9397d0b"
+    "manifest": "1343851e1c7663a114c9aca154e324b3d8216db854b0fa9e032198e946457bc5",
+    "packageJson": "ec35515de64d1c1079fe24af8a7227b971100db3bb17e6350626cfb3f196483c",
+    "agents": "4e963e1bc75c7fbf383eb7d31ef6ac37bcfb08b73bd26871c70817997a3c1f29"
   },
   "exports": [
     ".",
@@ -54,7 +54,7 @@
     "warehouse"
   ],
   "risks": [
-    "cross-package-refs:1",
+    "cross-package-refs:8",
     "sensitive-fields-excluded"
   ],
   "objects": [
@@ -169,6 +169,192 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "LotCollection",
+      "qualifiedName": "@happyvertical/smrt-inventory:LotCollection",
+      "collection": "lots",
+      "tableName": "inventory_lots",
+      "packageName": "@happyvertical/smrt-inventory",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findByLotNumber"
+      ],
+      "methodSignatures": [
+        {
+          "name": "findByLotNumber",
+          "async": true,
+          "params": [
+            "lotNumber: string",
+            "options?: object"
+          ],
+          "returns": "Promise<Lot[]>"
+        }
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "findByLotNumber",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-inventory:LotCollection"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "LotCorrectionCollection",
+      "qualifiedName": "@happyvertical/smrt-inventory:LotCorrectionCollection",
+      "collection": "lotcorrections",
+      "tableName": "inventory_lot_corrections",
+      "packageName": "@happyvertical/smrt-inventory",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "LotDocumentCollection",
+      "qualifiedName": "@happyvertical/smrt-inventory:LotDocumentCollection",
+      "collection": "lotdocuments",
+      "tableName": "inventory_lot_documents",
+      "packageName": "@happyvertical/smrt-inventory",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "LotStockLevelCollection",
+      "qualifiedName": "@happyvertical/smrt-inventory:LotStockLevelCollection",
+      "collection": "lotstocklevels",
+      "tableName": "inventory_lot_stock_levels",
+      "packageName": "@happyvertical/smrt-inventory",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "getLevel",
+        "onHand"
+      ],
+      "methodSignatures": [
+        {
+          "name": "getLevel",
+          "async": true,
+          "params": [
+            "lotId: string",
+            "locationId: string",
+            "state?: StockState"
+          ],
+          "returns": "Promise<LotStockLevel | null>"
+        },
+        {
+          "name": "onHand",
+          "async": true,
+          "params": [
+            "lotId: string",
+            "state?: StockState"
+          ],
+          "returns": "Promise<number>"
+        }
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "getLevel",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-inventory:LotStockLevelCollection"
+        },
+        {
+          "kind": "api",
+          "operation": "onHand",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-inventory:LotStockLevelCollection"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "LotUsageCollection",
+      "qualifiedName": "@happyvertical/smrt-inventory:LotUsageCollection",
+      "collection": "lotusages",
+      "tableName": "inventory_lot_usages",
+      "packageName": "@happyvertical/smrt-inventory",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "findActiveForLot",
+        "findForConsumer"
+      ],
+      "methodSignatures": [
+        {
+          "name": "findActiveForLot",
+          "async": true,
+          "params": [
+            "lotId: string"
+          ],
+          "returns": "Promise<LotUsage[]>"
+        },
+        {
+          "name": "findForConsumer",
+          "async": true,
+          "params": [
+            "consumerType: string",
+            "consumerId: string",
+            "options?: object"
+          ],
+          "returns": "Promise<LotUsage[]>"
+        }
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "findActiveForLot",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-inventory:LotUsageCollection"
+        },
+        {
+          "kind": "api",
+          "operation": "findForConsumer",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-inventory:LotUsageCollection"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "StockLevelCollection",
       "qualifiedName": "@happyvertical/smrt-inventory:StockLevelCollection",
@@ -388,51 +574,946 @@
       "extends": "SmrtObject",
       "fields": [
         {
-          "name": "tenantId",
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "code",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "A short code for the place stock is kept, for example MAIN."
+        },
+        {
+          "name": "name",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "What you call the place, for example Main warehouse."
+        },
+        {
+          "name": "kind",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "warehouse",
+          "description": "What sort of place it is, for example a warehouse or a shop floor."
+        },
+        {
+          "name": "placeId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": ""
+        },
+        {
+          "name": "active",
+          "type": "boolean",
+          "required": false,
+          "columnType": "BOOLEAN",
+          "default": true
+        }
+      ],
+      "relationships": [],
+      "methods": [],
+      "tenant": {
+        "scoped": true,
+        "mode": "optional",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "code",
+        "tenant_id"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "inventorylocations.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-inventory:InventoryLocation",
+          "path": "/inventorylocations",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "inventorylocations.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-inventory:InventoryLocation",
+          "path": "/inventorylocations/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "inventorylocations.create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-inventory:InventoryLocation",
+          "path": "/inventorylocations",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "inventorylocations.update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-inventory:InventoryLocation",
+          "path": "/inventorylocations/[id]",
+          "method": "PATCH"
+        },
+        {
+          "kind": "cli",
+          "name": "inventorylocation_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-inventory:InventoryLocation"
+        },
+        {
+          "kind": "cli",
+          "name": "inventorylocation_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-inventory:InventoryLocation"
+        },
+        {
+          "kind": "cli",
+          "name": "inventorylocation_create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-inventory:InventoryLocation"
+        },
+        {
+          "kind": "cli",
+          "name": "inventorylocation_update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-inventory:InventoryLocation"
+        },
+        {
+          "kind": "cli",
+          "name": "inventorylocation_delete",
+          "operation": "delete",
+          "objectName": "@happyvertical/smrt-inventory:InventoryLocation"
+        },
+        {
+          "kind": "mcp",
+          "name": "inventorylocation_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-inventory:InventoryLocation"
+        },
+        {
+          "kind": "mcp",
+          "name": "inventorylocation_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-inventory:InventoryLocation"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "Lot",
+      "qualifiedName": "@happyvertical/smrt-inventory:Lot",
+      "collection": "lots",
+      "tableName": "inventory_lots",
+      "packageName": "@happyvertical/smrt-inventory",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "skuId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "description": "The item this lot is of, if catalogued."
+        },
+        {
+          "name": "kind",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "lot",
+          "description": "Whether this is a batch (lot) or a single unit (serial)."
+        },
+        {
+          "name": "lotNumber",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "default": "",
+          "constraints": {
+            "maxLength": 128
+          },
+          "description": "The batch code, supplier lot or serial number."
+        },
+        {
+          "name": "searchKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "",
+          "constraints": {
+            "maxLength": 160
+          },
+          "description": "The number in normal form, used for lookup."
+        },
+        {
+          "name": "identityKey",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "default": "",
+          "constraints": {
+            "maxLength": 160
+          },
+          "description": "Internal identity that keeps lots from being created twice."
+        },
+        {
+          "name": "uniqueNumber",
+          "type": "boolean",
+          "required": false,
+          "columnType": "BOOLEAN",
+          "default": false,
+          "description": "Whether the number must be unique for this item."
+        },
+        {
+          "name": "receivedQty",
+          "type": "decimal",
+          "required": false,
+          "columnType": "REAL",
+          "description": "How many came in on the receipt."
+        },
+        {
+          "name": "unit",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "The unit of measure."
+        },
+        {
+          "name": "sourceType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "What kind of record received this lot."
+        },
+        {
+          "name": "sourceId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "The record that received this lot."
+        },
+        {
+          "name": "attributes",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "description": "Anything else worth knowing about this lot, stored as JSON."
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "active",
+          "description": "Where the lot stands: active, quarantined, consumed or void."
+        },
+        {
+          "name": "receivedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "description": "When the lot was received."
+        },
+        {
+          "name": "receivedByProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        },
+        {
+          "name": "lastUsedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "receivedByProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "getAttributes",
+        "setAttributes"
+      ],
+      "methodSignatures": [
+        {
+          "name": "getAttributes",
+          "returns": "Record<string, unknown>"
+        },
+        {
+          "name": "setAttributes",
+          "params": [
+            "value: Record<string, unknown> | string"
+          ],
+          "returns": "void"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "optional",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "identity_key",
+        "tenant_id"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "lots.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-inventory:Lot",
+          "path": "/lots",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "lots.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-inventory:Lot",
+          "path": "/lots/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "cli",
+          "name": "lot_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-inventory:Lot"
+        },
+        {
+          "kind": "cli",
+          "name": "lot_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-inventory:Lot"
+        },
+        {
+          "kind": "mcp",
+          "name": "lot_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-inventory:Lot"
+        },
+        {
+          "kind": "mcp",
+          "name": "lot_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-inventory:Lot"
+        }
+      ],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "getAttributes",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-inventory:Lot"
+        },
+        {
+          "kind": "api",
+          "operation": "setAttributes",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-inventory:Lot"
+        }
+      ],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "LotCorrection",
+      "qualifiedName": "@happyvertical/smrt-inventory:LotCorrection",
+      "collection": "lotcorrections",
+      "tableName": "inventory_lot_corrections",
+      "packageName": "@happyvertical/smrt-inventory",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "lotId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Lot",
+          "columnType": "UUID"
+        },
+        {
+          "name": "kind",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "default": "attribute",
+          "description": "What was corrected."
+        },
+        {
+          "name": "field",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "Which attribute changed, if one did."
+        },
+        {
+          "name": "oldValue",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "description": "What it was."
+        },
+        {
+          "name": "newValue",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "description": "What it is now."
+        },
+        {
+          "name": "reason",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "constraints": {
+            "maxLength": 1000
+          },
+          "description": "Why it was corrected."
+        },
+        {
+          "name": "usageId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "documentId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "actorProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        },
+        {
+          "name": "correctedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "description": "When it was corrected."
+        }
+      ],
+      "relationships": [
+        {
+          "name": "lotId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Lot",
+          "columnType": "UUID"
+        },
+        {
+          "name": "actorProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [],
+      "tenant": {
+        "scoped": true,
+        "mode": "optional",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "id"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "lotcorrections.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-inventory:LotCorrection",
+          "path": "/lotcorrections",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "lotcorrections.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-inventory:LotCorrection",
+          "path": "/lotcorrections/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "cli",
+          "name": "lotcorrection_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-inventory:LotCorrection"
+        },
+        {
+          "kind": "cli",
+          "name": "lotcorrection_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-inventory:LotCorrection"
+        },
+        {
+          "kind": "mcp",
+          "name": "lotcorrection_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-inventory:LotCorrection"
+        },
+        {
+          "kind": "mcp",
+          "name": "lotcorrection_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-inventory:LotCorrection"
+        }
+      ],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "LotDocument",
+      "qualifiedName": "@happyvertical/smrt-inventory:LotDocument",
+      "collection": "lotdocuments",
+      "tableName": "inventory_lot_documents",
+      "packageName": "@happyvertical/smrt-inventory",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "lotId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Lot",
+          "columnType": "UUID"
+        },
+        {
+          "name": "assetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "role",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "certificate",
+          "description": "What the document is for, for example certificate."
+        },
+        {
+          "name": "attachedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "description": "When it was attached."
+        },
+        {
+          "name": "attachedByProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        },
+        {
+          "name": "detachedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "detachedByProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "lotId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Lot",
+          "columnType": "UUID"
+        },
+        {
+          "name": "assetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "attachedByProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        },
+        {
+          "name": "detachedByProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [],
+      "tenant": {
+        "scoped": true,
+        "mode": "optional",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "lotdocuments.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-inventory:LotDocument",
+          "path": "/lotdocuments",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "lotdocuments.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-inventory:LotDocument",
+          "path": "/lotdocuments/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "cli",
+          "name": "lotdocument_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-inventory:LotDocument"
+        },
+        {
+          "kind": "cli",
+          "name": "lotdocument_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-inventory:LotDocument"
+        },
+        {
+          "kind": "mcp",
+          "name": "lotdocument_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-inventory:LotDocument"
+        },
+        {
+          "kind": "mcp",
+          "name": "lotdocument_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-inventory:LotDocument"
+        }
+      ],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "LotStockLevel",
+      "qualifiedName": "@happyvertical/smrt-inventory:LotStockLevel",
+      "collection": "lotstocklevels",
+      "tableName": "inventory_lot_stock_levels",
+      "packageName": "@happyvertical/smrt-inventory",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "lotId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Lot",
+          "columnType": "UUID"
+        },
+        {
+          "name": "skuId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "The item the lot is of."
+        },
+        {
+          "name": "locationId",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "Where the lot is kept."
+        },
+        {
+          "name": "state",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "default": "available",
+          "description": "The state of this stock: available, allocated, wip, qc_hold or damaged."
+        },
+        {
+          "name": "qty",
+          "type": "decimal",
+          "required": false,
+          "columnType": "REAL",
+          "description": "How many are on hand."
+        }
+      ],
+      "relationships": [
+        {
+          "name": "lotId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Lot",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [],
+      "tenant": {
+        "scoped": true,
+        "mode": "optional",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "lot_id",
+        "location_id",
+        "state",
+        "tenant_id"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "lotstocklevels.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-inventory:LotStockLevel",
+          "path": "/lotstocklevels",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "lotstocklevels.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-inventory:LotStockLevel",
+          "path": "/lotstocklevels/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "cli",
+          "name": "lotstocklevel_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-inventory:LotStockLevel"
+        },
+        {
+          "kind": "cli",
+          "name": "lotstocklevel_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-inventory:LotStockLevel"
+        },
+        {
+          "kind": "mcp",
+          "name": "lotstocklevel_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-inventory:LotStockLevel"
+        },
+        {
+          "kind": "mcp",
+          "name": "lotstocklevel_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-inventory:LotStockLevel"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "LotUsage",
+      "qualifiedName": "@happyvertical/smrt-inventory:LotUsage",
+      "collection": "lotusages",
+      "tableName": "inventory_lot_usages",
+      "packageName": "@happyvertical/smrt-inventory",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "lotId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Lot",
+          "columnType": "UUID"
+        },
+        {
+          "name": "consumerType",
           "type": "text",
-          "required": false,
-          "columnType": "UUID"
+          "required": true,
+          "columnType": "TEXT",
+          "default": "",
+          "description": "What kind of record used the lot."
         },
         {
-          "name": "code",
+          "name": "consumerId",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
           "default": "",
-          "description": "A short code for the place stock is kept, for example MAIN."
+          "description": "The record that used the lot."
         },
         {
-          "name": "name",
+          "name": "qty",
+          "type": "decimal",
+          "required": false,
+          "columnType": "REAL",
+          "description": "How much was used."
+        },
+        {
+          "name": "unit",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
           "default": "",
-          "description": "What you call the place, for example Main warehouse."
+          "description": "The unit of measure."
         },
         {
-          "name": "kind",
+          "name": "status",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "warehouse",
-          "description": "What sort of place it is, for example a warehouse or a shop floor."
+          "default": "active",
+          "description": "Whether the link still stands: active or unlinked."
         },
         {
-          "name": "placeId",
+          "name": "linkedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP",
+          "description": "When the lot was linked."
+        },
+        {
+          "name": "linkedByProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        },
+        {
+          "name": "unlinkedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "unlinkedByProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        },
+        {
+          "name": "unlinkReason",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "description": "Why the link was removed."
         },
         {
-          "name": "active",
-          "type": "boolean",
+          "name": "movementId",
+          "type": "text",
           "required": false,
-          "columnType": "BOOLEAN",
-          "default": true
+          "columnType": "TEXT",
+          "description": "The stock movement for this use, if any."
+        }
+      ],
+      "relationships": [
+        {
+          "name": "lotId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Lot",
+          "columnType": "UUID"
+        },
+        {
+          "name": "linkedByProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        },
+        {
+          "name": "unlinkedByProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
         }
       ],
-      "relationships": [],
       "methods": [],
       "tenant": {
         "scoped": true,
@@ -440,86 +1521,55 @@
         "field": "tenantId"
       },
       "conflictColumns": [
-        "code",
-        "tenant_id"
+        "tenant_id",
+        "slug",
+        "context"
       ],
       "surfaces": [
         {
           "kind": "api",
-          "name": "inventorylocations.list",
+          "name": "lotusages.list",
           "operation": "list",
-          "objectName": "@happyvertical/smrt-inventory:InventoryLocation",
-          "path": "/inventorylocations",
+          "objectName": "@happyvertical/smrt-inventory:LotUsage",
+          "path": "/lotusages",
           "method": "GET"
         },
         {
           "kind": "api",
-          "name": "inventorylocations.get",
+          "name": "lotusages.get",
           "operation": "get",
-          "objectName": "@happyvertical/smrt-inventory:InventoryLocation",
-          "path": "/inventorylocations/[id]",
+          "objectName": "@happyvertical/smrt-inventory:LotUsage",
+          "path": "/lotusages/[id]",
           "method": "GET"
         },
-        {
-          "kind": "api",
-          "name": "inventorylocations.create",
-          "operation": "create",
-          "objectName": "@happyvertical/smrt-inventory:InventoryLocation",
-          "path": "/inventorylocations",
-          "method": "POST"
-        },
-        {
-          "kind": "api",
-          "name": "inventorylocations.update",
-          "operation": "update",
-          "objectName": "@happyvertical/smrt-inventory:InventoryLocation",
-          "path": "/inventorylocations/[id]",
-          "method": "PATCH"
-        },
         {
           "kind": "cli",
-          "name": "inventorylocation_list",
+          "name": "lotusage_list",
           "operation": "list",
-          "objectName": "@happyvertical/smrt-inventory:InventoryLocation"
+          "objectName": "@happyvertical/smrt-inventory:LotUsage"
         },
         {
           "kind": "cli",
-          "name": "inventorylocation_get",
+          "name": "lotusage_get",
           "operation": "get",
-          "objectName": "@happyvertical/smrt-inventory:InventoryLocation"
-        },
-        {
-          "kind": "cli",
-          "name": "inventorylocation_create",
-          "operation": "create",
-          "objectName": "@happyvertical/smrt-inventory:InventoryLocation"
-        },
-        {
-          "kind": "cli",
-          "name": "inventorylocation_update",
-          "operation": "update",
-          "objectName": "@happyvertical/smrt-inventory:InventoryLocation"
-        },
-        {
-          "kind": "cli",
-          "name": "inventorylocation_delete",
-          "operation": "delete",
-          "objectName": "@happyvertical/smrt-inventory:InventoryLocation"
+          "objectName": "@happyvertical/smrt-inventory:LotUsage"
         },
         {
           "kind": "mcp",
-          "name": "inventorylocation_list",
+          "name": "lotusage_list",
           "operation": "list",
-          "objectName": "@happyvertical/smrt-inventory:InventoryLocation"
+          "objectName": "@happyvertical/smrt-inventory:LotUsage"
         },
         {
           "kind": "mcp",
-          "name": "inventorylocation_get",
+          "name": "lotusage_get",
           "operation": "get",
-          "objectName": "@happyvertical/smrt-inventory:InventoryLocation"
+          "objectName": "@happyvertical/smrt-inventory:LotUsage"
         }
       ],
       "relationshipFeatures": [
+        "crossPackageRef",
+        "foreignKey",
         "uuidColumns"
       ],
       "tags": [],
@@ -674,6 +1724,13 @@
           "default": "",
           "description": "The place it moved at."
         },
+        {
+          "name": "lotId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "description": "The lot that moved, when tracked by lot."
+        },
         {
           "name": "fromState",
           "type": "text",
@@ -907,6 +1964,206 @@
       "operation": "get",
       "objectName": "@happyvertical/smrt-inventory:InventoryLocation"
     },
+    {
+      "kind": "api",
+      "name": "lots.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-inventory:Lot",
+      "path": "/lots",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "lots.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-inventory:Lot",
+      "path": "/lots/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "cli",
+      "name": "lot_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-inventory:Lot"
+    },
+    {
+      "kind": "cli",
+      "name": "lot_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-inventory:Lot"
+    },
+    {
+      "kind": "mcp",
+      "name": "lot_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-inventory:Lot"
+    },
+    {
+      "kind": "mcp",
+      "name": "lot_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-inventory:Lot"
+    },
+    {
+      "kind": "api",
+      "name": "lotcorrections.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-inventory:LotCorrection",
+      "path": "/lotcorrections",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "lotcorrections.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-inventory:LotCorrection",
+      "path": "/lotcorrections/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "cli",
+      "name": "lotcorrection_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-inventory:LotCorrection"
+    },
+    {
+      "kind": "cli",
+      "name": "lotcorrection_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-inventory:LotCorrection"
+    },
+    {
+      "kind": "mcp",
+      "name": "lotcorrection_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-inventory:LotCorrection"
+    },
+    {
+      "kind": "mcp",
+      "name": "lotcorrection_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-inventory:LotCorrection"
+    },
+    {
+      "kind": "api",
+      "name": "lotdocuments.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-inventory:LotDocument",
+      "path": "/lotdocuments",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "lotdocuments.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-inventory:LotDocument",
+      "path": "/lotdocuments/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "cli",
+      "name": "lotdocument_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-inventory:LotDocument"
+    },
+    {
+      "kind": "cli",
+      "name": "lotdocument_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-inventory:LotDocument"
+    },
+    {
+      "kind": "mcp",
+      "name": "lotdocument_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-inventory:LotDocument"
+    },
+    {
+      "kind": "mcp",
+      "name": "lotdocument_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-inventory:LotDocument"
+    },
+    {
+      "kind": "api",
+      "name": "lotstocklevels.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-inventory:LotStockLevel",
+      "path": "/lotstocklevels",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "lotstocklevels.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-inventory:LotStockLevel",
+      "path": "/lotstocklevels/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "cli",
+      "name": "lotstocklevel_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-inventory:LotStockLevel"
+    },
+    {
+      "kind": "cli",
+      "name": "lotstocklevel_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-inventory:LotStockLevel"
+    },
+    {
+      "kind": "mcp",
+      "name": "lotstocklevel_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-inventory:LotStockLevel"
+    },
+    {
+      "kind": "mcp",
+      "name": "lotstocklevel_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-inventory:LotStockLevel"
+    },
+    {
+      "kind": "api",
+      "name": "lotusages.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-inventory:LotUsage",
+      "path": "/lotusages",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "lotusages.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-inventory:LotUsage",
+      "path": "/lotusages/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "cli",
+      "name": "lotusage_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-inventory:LotUsage"
+    },
+    {
+      "kind": "cli",
+      "name": "lotusage_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-inventory:LotUsage"
+    },
+    {
+      "kind": "mcp",
+      "name": "lotusage_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-inventory:LotUsage"
+    },
+    {
+      "kind": "mcp",
+      "name": "lotusage_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-inventory:LotUsage"
+    },
     {
       "kind": "api",
       "name": "stocklevels.list",
@@ -990,14 +2247,14 @@
   ],
   "prompts": [],
   "relationshipsV2": {
-    "foreignKeyFields": 0,
-    "crossPackageRefFields": 1,
+    "foreignKeyFields": 4,
+    "crossPackageRefFields": 8,
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 14
+    "uuidColumns": 56
   },
-  "agentDoc": "# @happyvertical/smrt-inventory\n\nMulti-location stock tracking. Strictly industry-neutral — the same primitives serve apparel, furniture, automotive, CPG, electronics, and any other vertical that counts discrete units across locations.\n\n## Models\n\n| Model | Purpose |\n|---|---|\n| _(catalog shapes — `Product`, `Material`, `ProductVariant`, `Sku` — live in `@happyvertical/smrt-products`)_ | Sku is the smallest sellable / countable unit; its `attributes` JSON carries axis-value pins. ProductVariant is the per-product axis declaration. Import either from `@happyvertical/smrt-products` directly. |\n| `InventoryLocation` | Warehouse / factory / retail / in-transit / virtual. Open-ended `kind` string. Optional `placeId` references `@happyvertical/smrt-places`. `conflictColumns: ['code', 'tenant_id']`. |\n| `StockLevel` | Materialized `qty` for a `(skuId, locationId, state)` tuple. Upserted in place. **Mutated only by `StockService`.** States: `available`, `allocated`, `wip`, `qc_hold`, `damaged`. |\n| `StockMovement` | Append-only audit log. Every `StockService` mutation writes one (or two for `transfer`). `sourceType` + `sourceId` carry cross-package attribution. |\n\nAll three inventory models (`InventoryLocation`, `StockLevel`, `StockMovement`) use `@TenantScoped({ mode: 'optional' })` + nullable `tenantId` so they can be used either tenant-scoped or globally. The catalog shapes (`Product`, `Material`, `ProductVariant`, `Sku`) live in `@happyvertical/smrt-products` and carry their own tenant decoration there.\n\n## StockService — the only sanctioned way to mutate stock\n\n```typescript\nimport { createStockService } from '@happyvertical/smrt-inventory';\n\nconst service = await createStockService({ db });\nawait service.receive(skuId, locationId, qty, { sourceType, sourceId });\nawait service.reserve(skuId, locationId, qty, { sourceType, sourceId });\nawait service.release(skuId, locationId, qty, { sourceType, sourceId });\nawait service.fulfill(skuId, locationId, qty, { sourceType, sourceId });\nawait service.transfer(skuId, fromLocId, toLocId, qty, { sourceType, sourceId });\nawait service.adjust(skuId, locationId, delta, { sourceType, sourceId });\n```\n\n| Method | Behavior | Movement reason |\n|---|---|---|\n| `receive` | +qty available — purchase receipt, return, production produce | `receipt` |\n| `reserve` | available → allocated. Throws `InsufficientStockError` on overdraw | `reservation` |\n| `release` | allocated → available (order cancel) | `release` |\n| `fulfill` | -qty allocated. Stock leaves the building | `fulfillment` |\n| `transfer` | move stock between locations (writes two movements) | `transfer_out`, `transfer_in` |\n| `adjust` | signed delta — cycle counts and one-off corrections | `adjustment` |\n\nAll methods reject zero / negative / non-finite quantities except `adjust`, which accepts non-zero signed deltas. Negative deltas that would drive a state below zero throw `InsufficientStockError`.\n\n## Opt-in DispatchBus hooks\n\nOff by default. Wire them up explicitly in the application's `smrt.ts`:\n\n```typescript\nimport { installInventoryDispatchHandlers } from '@happyvertical/smrt-inventory';\n\nconst handlers = await installInventoryDispatchHandlers({\n  dispatchBus: bus,\n  db, // or stockService: existingService\n});\n```\n\nThis subscribes to:\n- `contract:created` → calls `service.reserve()` for every line inside one `stockService.withTransaction(...)`, attributed to `('Contract', payload.contractId)`\n- `fulfillment:shipped` → calls `service.fulfill()` for every line inside one `stockService.withTransaction(...)`, attributed to `('Fulfillment', payload.fulfillmentId)`\n\nBoth handlers are atomic across lines: a shortfall on line N rolls back lines 1..N-1 so the event is all-or-nothing. Without this guarantee, `DispatchBus` would only log the async handler error and a partially-reserved (or partially-fulfilled) contract would have no compensating event to fix it.\n\nPer-handler toggles: `installContractReserved`, `installFulfillmentShipped`. The `production_order:posted` hook is deliberately not installed here — it depends on the BOM model and ships in `@happyvertical/smrt-manufacturing` (issue #1250).\n\n## Schema migration (Phase 1 release)\n\nThe `Sku` model moved out of this package and into `@happyvertical/smrt-products`. Previously it lived in this package's `inventory_skus` table; it now lives in `product_skus` over there.\n\n**Upgrade procedure** for deployed consumers:\n\n1. **Let the framework create the destination table first.** Boot the new version once with `@happyvertical/smrt-products` registered in your `SmrtClassOptions`; the lazy `syncSchema` path will create `product_skus` with the right primary key, NOT NULL, UNIQUE (`code`, `tenant_id`), and indexes — they're derived from the `Sku` model decorators and would be stripped by a raw `CREATE TABLE AS SELECT`.\n\n2. **Idempotently copy rows across.** SQLite + Postgres:\n\n   ```sql\n   BEGIN;\n   INSERT INTO product_skus (\n     id, slug, context, created_at, updated_at,\n     tenant_id, product_id, code, barcode, name,\n     attributes, weight_grams, parent_sku_id, active\n   )\n   SELECT\n     id, slug, context, created_at, updated_at,\n     tenant_id, product_id, code, barcode, name,\n     attributes, weight_grams, parent_sku_id, active\n   FROM inventory_skus\n   WHERE NOT EXISTS (\n     SELECT 1 FROM product_skus p WHERE p.id = inventory_skus.id\n   );\n   COMMIT;\n   ```\n\n3. **Drop the legacy table** once you've verified row counts match:\n\n   ```sql\n   DROP TABLE IF EXISTS inventory_skus;\n   ```\n\n`StockLevel.skuId` and `StockMovement.skuId` carry plain string ids that still resolve to the same rows after the rename, so no inventory data has to move.\n\n## Gotchas\n\n- **Movements are append-only.** The materialized `StockLevel` row is derived state; the `StockMovement` ledger is the source of truth. Never let CRUD UIs expose update/delete on the movement table. If you find yourself wanting to \"fix\" a movement row, write a compensating `adjust()` call instead.\n- **Never call `StockLevel.create()` or `save()` directly.** Going around `StockService` silently desyncs the audit log and breaks cycle counts.\n- **Cross-industry constraint.** This package's vocabulary stays generic: `InventoryLocation`, `StockLevel`, `StockMovement`. Apparel-specific concepts (`Style`, `Makeup`, `Colorway`, fashion `Season`, tech-pack metadata) and their analogues in furniture / automotive / CPG live in the relevant template package, never here. PRs that introduce industry vocabulary should be rejected.\n- **Cross-package references are plain strings.** `skuId`, `placeId`, `sourceId` — all plain string ids, never `@foreignKey()`. Inventory's stock-motion logic only ever reads StockLevel/StockMovement; it doesn't follow `skuId` back to the catalog's Sku table, so the layering stays loose.\n- **`conflictColumns` include `tenant_id`** on `InventoryLocation` and `StockLevel`. NULL-matching semantics (`(code, NULL) IS NOT DISTINCT FROM (code, NULL)`) are handled by `@happyvertical/sql >= 0.74.0` natively, so two saves with the same `(code, NULL)` tuple correctly merge in place. Pass `nullsDistinct: true` at the sql layer to opt back into NULL-distinct semantics.\n- **Atomic per-method, transactional across composition.** Each `StockService` mutation (`receive` / `reserve` / `release` / `fulfill` / `transfer` / `adjust`) wraps every write in a single `db.transaction(...)` (via `@happyvertical/sql >= 0.74.0`). Partial failure rolls the whole call back — level writes and the matching `StockMovement` audit row commit together or not at all. `transfer` writes both legs (source decrement, destination increment, and both audit rows) inside one tx, so a failure mid-`transfer` is fully reverted.\n  Callers composing multiple `StockService` calls into one logical unit (e.g. consuming materials line-by-line for a production order) should wrap them in `await stockService.withTransaction(async (tx) => { ... })` — `tx` is a tx-bound `StockService` with the same public API; mutation calls inside the callback share one transaction and either all commit or all roll back.\n  If the underlying SQL adapter does not expose `transaction()` (extremely rare — all four built-in `@happyvertical/sql >= 0.74.0` adapters implement it), the service degrades to non-atomic serial writes and emits a one-time `console.warn`.\n- **Concurrent reservations: tightened, not bulletproof.** `@happyvertical/sql >= 0.74.0` serialises null-aware *upserts* via a per-key in-process lock (SQLite) or advisory lock (Postgres). That lock fixed the row-creation race (issue #1246) — two concurrent `create()` calls on the same conflict-column tuple no longer race the underlying `INSERT ... ON CONFLICT`. The first `StockLevel` row for a key is now created insert-only (#3204): a concurrent first write fails on the unique key and its transaction rolls back (retry it) instead of upserting over the winner's qty. It does NOT serialise the read-modify-write compound that `reserve` / `fulfill` / `transfer` / `adjust` perform on an existing row: each method reads the current level (`SELECT`), computes the new value in JS, then writes it back (`UPDATE` via `save()` on the loaded row). The whole compound is inside one `db.transaction(...)` from round-3, so the level write and audit row commit together — but two concurrent transactions on the same `(skuId, locationId)` can each see the same starting balance, compute the same decrement, and double-spend. Awaited (serial) calls always behave correctly. Use a job queue (e.g. `@happyvertical/smrt-jobs`) or your own mutex when you need hard atomicity across concurrent callers. The full fix is `SELECT ... FOR UPDATE` inside the same transaction (Postgres) or upgrading the journal mode (SQLite); deferred until we see a real high-contention workload that warrants it.\n\n## Source attribution\n\nEvery `StockMovement` carries `sourceType` + `sourceId` so downstream queries can reconstruct \"what caused this movement\". Conventions used by the built-in dispatch handlers:\n\n| sourceType | Emitter | Note |\n|---|---|---|\n| `Contract` | `smrt-commerce` `contract:created` | All reservation/release/fulfilment legs caused by a contract |\n| `Fulfillment` | `smrt-commerce` `fulfillment:shipped` | Outbound shipment |\n| `PurchaseOrder` | (your code) | Inbound receipt |\n| `CycleCount` | (your code) | Adjustments from physical counts |\n| `TransferOrder` | (your code) | Both legs of a transfer |\n| `ProductionOrder` | `smrt-manufacturing` (issue #1250) | Materials consumed + finished goods produced |\n\n## Replenishment and browser components\n\n`StockService.setReorderPolicy()` is the sanctioned metadata writer for nullable\n`StockLevel.reorderPoint` / `reorderQuantity` on the available SKU/location row.\nIt does not change quantity or emit a movement. `findBelowReorderPoint()` uses\npublic tenant-filtered collection reads and strict less-than semantics.\n`StockMutationOptions.actorProfileId` propagates to every movement, including\nboth transfer legs; null retains compatibility for automation. It is a qualified\ncross-package profile reference, not an authorization decision.\n\n`src/svelte/` exports data-driven components through `./svelte`. Server callers\nown authentication and persistence callbacks; never import backend models into\nthis entry or expose ledger mutations as CRUD. Package `typecheck` includes\nSvelte checks and `test` includes DOM component tests. See README for the public\nprops, service contracts, and additive schema upgrade requirements.\n",
+  "agentDoc": "# @happyvertical/smrt-inventory\n\nMulti-location stock tracking. Strictly industry-neutral — the same primitives serve apparel, furniture, automotive, CPG, electronics, and any other vertical that counts discrete units across locations.\n\n## Models\n\n| Model | Purpose |\n|---|---|\n| _(catalog shapes — `Product`, `Material`, `ProductVariant`, `Sku` — live in `@happyvertical/smrt-products`)_ | Sku is the smallest sellable / countable unit; its `attributes` JSON carries axis-value pins. ProductVariant is the per-product axis declaration. Import either from `@happyvertical/smrt-products` directly. |\n| `InventoryLocation` | Warehouse / factory / retail / in-transit / virtual. Open-ended `kind` string. Optional `placeId` references `@happyvertical/smrt-places`. `conflictColumns: ['code', 'tenant_id']`. |\n| `StockLevel` | Materialized `qty` for a `(skuId, locationId, state)` tuple. Upserted in place. **Mutated only by `StockService`.** States: `available`, `allocated`, `wip`, `qc_hold`, `damaged`. |\n| `StockMovement` | Append-only audit log. Every `StockService` mutation writes one (or two for `transfer`). `sourceType` + `sourceId` carry cross-package attribution. |\n\n| `Lot` | A traceable batch or serial (`inventory_lots`). `conflictColumns: ['identity_key','tenant_id']`, every create insert-only. **Written only by `LotService`.** |\n| `LotStockLevel` | Per-lot balance for `(lotId, locationId, state)` (`inventory_lot_stock_levels`). **Mutated only by `StockService`** when `lotId` is passed. |\n| `LotUsage` | A lot used by a consumer: the trace edge. Never deleted; `status: 'unlinked'` after a correction. `consumerType: 'Lot'` marks assembly lineage. |\n| `LotCorrection` | Append-only correction trail (`conflictColumns: ['id']`); reason mandatory. |\n| `LotDocument` | Asset attached to a lot (`assetId` is a cross-package ref); detached, never deleted. |\n\nAll inventory models (`InventoryLocation`, `StockLevel`, `StockMovement`, and the lot models) use `@TenantScoped({ mode: 'optional' })` + nullable `tenantId` so they can be used either tenant-scoped or globally. The catalog shapes (`Product`, `Material`, `ProductVariant`, `Sku`) live in `@happyvertical/smrt-products` and carry their own tenant decoration there.\n\n## StockService — the only sanctioned way to mutate stock\n\n```typescript\nimport { createStockService } from '@happyvertical/smrt-inventory';\n\nconst service = await createStockService({ db });\nawait service.receive(skuId, locationId, qty, { sourceType, sourceId });\nawait service.reserve(skuId, locationId, qty, { sourceType, sourceId });\nawait service.release(skuId, locationId, qty, { sourceType, sourceId });\nawait service.fulfill(skuId, locationId, qty, { sourceType, sourceId });\nawait service.transfer(skuId, fromLocId, toLocId, qty, { sourceType, sourceId });\nawait service.adjust(skuId, locationId, delta, { sourceType, sourceId });\n```\n\n| Method | Behavior | Movement reason |\n|---|---|---|\n| `receive` | +qty available — purchase receipt, return, production produce | `receipt` |\n| `reserve` | available → allocated. Throws `InsufficientStockError` on overdraw | `reservation` |\n| `release` | allocated → available (order cancel) | `release` |\n| `fulfill` | -qty allocated. Stock leaves the building | `fulfillment` |\n| `transfer` | move stock between locations (writes two movements) | `transfer_out`, `transfer_in` |\n| `adjust` | signed delta — cycle counts and one-off corrections | `adjustment` |\n\nAll methods reject zero / negative / non-finite quantities except `adjust`, which accepts non-zero signed deltas. Negative deltas that would drive a state below zero throw `InsufficientStockError`.\n\n## LotService — lots and serials (additive, #3459)\n\n`createLotService({ db })` (with `withTransaction`, same pattern as `StockService`) is the only writer of the lot tables. `receiveLot` records identity only and moves no stock; compose with `StockService` in one transaction via `createLotService({ db: tx.db })`. Passing `lotId` to a `StockService` mutation applies the same deltas to `LotStockLevel`, enforces non-negative at lot level (`InsufficientStockError.lotId`), validates the lot (`LotNotFoundError`, `LotMismatchError` when `lot.skuId` differs), and stamps `StockMovement.lotId`.\n\n- `Lot.identityKey` is the only DB-unique key: `u:<kind>:<sku>:<SEARCHKEY>` for unique lots and all serials (hashed if over 160 chars), `k:<idempotencyKey>` for idempotent receipts, else a random `r:` key. So a lot number repeats by default (one supplier lot, two receipts); `DuplicateLotError` only for unique ones.\n- Corrections (`correctLotNumber`, `correctAttributes`, `setStatus`, `unlinkUsage`, `detachDocument`) require a reason, are refused when nothing changes, and write a `LotCorrection`. They `save()` the lot so concurrent changes conflict on its revision; retry the loser.\n- `recordUsage` is idempotent per consumer; `exclusive` (default for serials) throws `LotInUseError` for a second consumer.\n- `traceForward(lotId)` / `traceBack(consumerType, consumerId)` follow `consumerType: 'Lot'` usages with a path-based cycle guard and `depth` (default 10).\n- `StockService` does not consult `lot.status`: callers decide what a quarantined or void lot may do. A repeated `idempotencyKey` returns the first lot even if the other fields differ; a repeated `recordUsage` for the same consumer returns the existing usage unchanged (its `qty` is ignored).\n- No authorization inside the package; callers authorize. Nothing assumes an id format, so a consumer's data migration may insert rows with its own ids.\n- Schema upgrade is additive: five new tables and one nullable column, `inventory_stock_movements.lot_id`. `StockLevel`'s unique key is unchanged. Runtime never creates schema: generate and apply the normal migration first (`smrt doctor --db`); no data copy is needed.\n\n## Opt-in DispatchBus hooks\n\nOff by default. Wire them up explicitly in the application's `smrt.ts`:\n\n```typescript\nimport { installInventoryDispatchHandlers } from '@happyvertical/smrt-inventory';\n\nconst handlers = await installInventoryDispatchHandlers({\n  dispatchBus: bus,\n  db, // or stockService: existingService\n});\n```\n\nThis subscribes to:\n- `contract:created` → calls `service.reserve()` for every line inside one `stockService.withTransaction(...)`, attributed to `('Contract', payload.contractId)`\n- `fulfillment:shipped` → calls `service.fulfill()` for every line inside one `stockService.withTransaction(...)`, attributed to `('Fulfillment', payload.fulfillmentId)`\n\nBoth handlers are atomic across lines: a shortfall on line N rolls back lines 1..N-1 so the event is all-or-nothing. Without this guarantee, `DispatchBus` would only log the async handler error and a partially-reserved (or partially-fulfilled) contract would have no compensating event to fix it.\n\nPer-handler toggles: `installContractReserved`, `installFulfillmentShipped`. The `production_order:posted` hook is deliberately not installed here — it depends on the BOM model and ships in `@happyvertical/smrt-manufacturing` (issue #1250).\n\n## Schema migration (Phase 1 release)\n\nThe `Sku` model moved out of this package and into `@happyvertical/smrt-products`. Previously it lived in this package's `inventory_skus` table; it now lives in `product_skus` over there.\n\n**Upgrade procedure** for deployed consumers:\n\n1. **Let the framework create the destination table first.** Boot the new version once with `@happyvertical/smrt-products` registered in your `SmrtClassOptions`; the lazy `syncSchema` path will create `product_skus` with the right primary key, NOT NULL, UNIQUE (`code`, `tenant_id`), and indexes — they're derived from the `Sku` model decorators and would be stripped by a raw `CREATE TABLE AS SELECT`.\n\n2. **Idempotently copy rows across.** SQLite + Postgres:\n\n   ```sql\n   BEGIN;\n   INSERT INTO product_skus (\n     id, slug, context, created_at, updated_at,\n     tenant_id, product_id, code, barcode, name,\n     attributes, weight_grams, parent_sku_id, active\n   )\n   SELECT\n     id, slug, context, created_at, updated_at,\n     tenant_id, product_id, code, barcode, name,\n     attributes, weight_grams, parent_sku_id, active\n   FROM inventory_skus\n   WHERE NOT EXISTS (\n     SELECT 1 FROM product_skus p WHERE p.id = inventory_skus.id\n   );\n   COMMIT;\n   ```\n\n3. **Drop the legacy table** once you've verified row counts match:\n\n   ```sql\n   DROP TABLE IF EXISTS inventory_skus;\n   ```\n\n`StockLevel.skuId` and `StockMovement.skuId` carry plain string ids that still resolve to the same rows after the rename, so no inventory data has to move.\n\n## Gotchas\n\n- **Movements are append-only.** The materialized `StockLevel` row is derived state; the `StockMovement` ledger is the source of truth. Never let CRUD UIs expose update/delete on the movement table. If you find yourself wanting to \"fix\" a movement row, write a compensating `adjust()` call instead.\n- **Never call `StockLevel.create()` or `save()` directly.** Going around `StockService` silently desyncs the audit log and breaks cycle counts.\n- **Cross-industry constraint.** This package's vocabulary stays generic: `InventoryLocation`, `StockLevel`, `StockMovement`. Apparel-specific concepts (`Style`, `Makeup`, `Colorway`, fashion `Season`, tech-pack metadata) and their analogues in furniture / automotive / CPG live in the relevant template package, never here. PRs that introduce industry vocabulary should be rejected.\n- **Cross-package references are plain strings.** `skuId`, `placeId`, `sourceId` — all plain string ids, never `@foreignKey()`. Inventory's stock-motion logic only ever reads StockLevel/StockMovement; it doesn't follow `skuId` back to the catalog's Sku table, so the layering stays loose.\n- **`conflictColumns` include `tenant_id`** on `InventoryLocation` and `StockLevel`. NULL-matching semantics (`(code, NULL) IS NOT DISTINCT FROM (code, NULL)`) are handled by `@happyvertical/sql >= 0.74.0` natively, so two saves with the same `(code, NULL)` tuple correctly merge in place. Pass `nullsDistinct: true` at the sql layer to opt back into NULL-distinct semantics.\n- **Atomic per-method, transactional across composition.** Each `StockService` mutation (`receive` / `reserve` / `release` / `fulfill` / `transfer` / `adjust`) wraps every write in a single `db.transaction(...)` (via `@happyvertical/sql >= 0.74.0`). Partial failure rolls the whole call back — level writes and the matching `StockMovement` audit row commit together or not at all. `transfer` writes both legs (source decrement, destination increment, and both audit rows) inside one tx, so a failure mid-`transfer` is fully reverted.\n  Callers composing multiple `StockService` calls into one logical unit (e.g. consuming materials line-by-line for a production order) should wrap them in `await stockService.withTransaction(async (tx) => { ... })` — `tx` is a tx-bound `StockService` with the same public API; mutation calls inside the callback share one transaction and either all commit or all roll back.\n  If the underlying SQL adapter does not expose `transaction()` (extremely rare — all four built-in `@happyvertical/sql >= 0.74.0` adapters implement it), the service degrades to non-atomic serial writes and emits a one-time `console.warn`.\n- **Concurrent reservations: tightened, not bulletproof.** `@happyvertical/sql >= 0.74.0` serialises null-aware *upserts* via a per-key in-process lock (SQLite) or advisory lock (Postgres). That lock fixed the row-creation race (issue #1246) — two concurrent `create()` calls on the same conflict-column tuple no longer race the underlying `INSERT ... ON CONFLICT`. The first `StockLevel` row for a key is now created insert-only (#3204): a concurrent first write fails on the unique key and its transaction rolls back (retry it) instead of upserting over the winner's qty. It does NOT serialise the read-modify-write compound that `reserve` / `fulfill` / `transfer` / `adjust` perform on an existing row: each method reads the current level (`SELECT`), computes the new value in JS, then writes it back (`UPDATE` via `save()` on the loaded row). The whole compound is inside one `db.transaction(...)` from round-3, so the level write and audit row commit together — but two concurrent transactions on the same `(skuId, locationId)` can each see the same starting balance, compute the same decrement, and double-spend. Awaited (serial) calls always behave correctly. Use a job queue (e.g. `@happyvertical/smrt-jobs`) or your own mutex when you need hard atomicity across concurrent callers. The full fix is `SELECT ... FOR UPDATE` inside the same transaction (Postgres) or upgrading the journal mode (SQLite); deferred until we see a real high-contention workload that warrants it.\n\n## Source attribution\n\nEvery `StockMovement` carries `sourceType` + `sourceId` so downstream queries can reconstruct \"what caused this movement\". Conventions used by the built-in dispatch handlers:\n\n| sourceType | Emitter | Note |\n|---|---|---|\n| `Contract` | `smrt-commerce` `contract:created` | All reservation/release/fulfilment legs caused by a contract |\n| `Fulfillment` | `smrt-commerce` `fulfillment:shipped` | Outbound shipment |\n| `PurchaseOrder` | (your code) | Inbound receipt |\n| `CycleCount` | (your code) | Adjustments from physical counts |\n| `TransferOrder` | (your code) | Both legs of a transfer |\n| `ProductionOrder` | `smrt-manufacturing` (issue #1250) | Materials consumed + finished goods produced |\n\n## Replenishment and browser components\n\n`StockService.setReorderPolicy()` is the sanctioned metadata writer for nullable\n`StockLevel.reorderPoint` / `reorderQuantity` on the available SKU/location row.\nIt does not change quantity or emit a movement. `findBelowReorderPoint()` uses\npublic tenant-filtered collection reads and strict less-than semantics.\n`StockMutationOptions.actorProfileId` propagates to every movement, including\nboth transfer legs; null retains compatibility for automation. It is a qualified\ncross-package profile reference, not an authorization decision.\n\n`src/svelte/` exports data-driven components through `./svelte`. Server callers\nown authentication and persistence callbacks; never import backend models into\nthis entry or expose ledger mutations as CRUD. Package `typecheck` includes\nSvelte checks and `test` includes DOM component tests. See README for the public\nprops, service contracts, and additive schema upgrade requirements.\n",
   "recipes": [
     {
       "id": "inventory.stock",