@happyvertical/smrt-inventory 0.55.7 → 0.55.8

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-inventory",
-  "packageVersion": "0.55.7",
+  "packageVersion": "0.55.8",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "fa6c2f8a2c8fb641766bde2fc197dca46734e94f529367641de3529e8cd4b6bc",
-    "packageJson": "5155a0dd22f82447970100cadd4aadf5b588c314152435a3c071e2a511c85e2f",
+    "manifest": "0b483c113fd2ef2605aed68aedf1a8239eee1d799f5a58f2b312ee5342f80d51",
+    "packageJson": "27ff7d0f4fc0e7c44180ababd234960407ec0056fa7195537be93d1d566857a4",
     "agents": "f1e6618e492c2726dee29c3e3fb203c03a64de184c7992407a1025b12618625d"
   },
   "exports": [
@@ -552,21 +552,24 @@
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "A short code for the place stock is kept, for example MAIN."
         },
         {
           "name": "name",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What you call the place, for example Main warehouse."
         },
         {
           "name": "kind",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "warehouse"
+          "default": "warehouse",
+          "description": "What sort of place it is, for example a warehouse or a shop floor."
         },
         {
           "name": "placeId",
@@ -695,27 +698,31 @@
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The item being counted."
         },
         {
           "name": "locationId",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "Where the stock is kept."
         },
         {
           "name": "state",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": "available"
+          "default": "available",
+          "description": "The state of this stock: available, allocated, wip, qc_hold or damaged."
         },
         {
           "name": "qty",
           "type": "decimal",
           "required": false,
-          "columnType": "REAL"
+          "columnType": "REAL",
+          "description": "How many are on hand."
         },
         {
           "name": "reorderPoint",
@@ -810,39 +817,45 @@
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The item that moved."
         },
         {
           "name": "locationId",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The place it moved at."
         },
         {
           "name": "fromState",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "What it was before, for example available or damaged."
         },
         {
           "name": "toState",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "What it became."
         },
         {
           "name": "qty",
           "type": "decimal",
           "required": false,
-          "columnType": "REAL"
+          "columnType": "REAL",
+          "description": "How many moved."
         },
         {
           "name": "reasonCode",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": "adjustment"
+          "default": "adjustment",
+          "description": "Why it moved, for example adjustment, sale or return."
         },
         {
           "name": "sourceType",
@@ -870,13 +883,15 @@
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "Anything worth remembering about this movement."
         },
         {
           "name": "occurredAt",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "When it happened."
         }
       ],
       "relationships": [
@@ -1392,5 +1407,117 @@
     "polymorphicAssociations": 0,
     "uuidColumns": 14
   },
-  "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`. 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\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`. 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",
+      "className": "StockRecipe",
+      "label": "Inventory",
+      "summary": "Keep count of how many of each product you have.",
+      "synonyms": [
+        "stock",
+        "quantity",
+        "on hand"
+      ],
+      "models": [
+        "@happyvertical/smrt-inventory:StockLevel",
+        "@happyvertical/smrt-inventory:InventoryLocation",
+        "@happyvertical/smrt-inventory:StockMovement"
+      ],
+      "nav": [
+        {
+          "label": "Stock levels",
+          "model": "@happyvertical/smrt-inventory:StockLevel",
+          "icon": "archive",
+          "description": "How much of each item you have on hand right now.",
+          "noun": "stock entry"
+        },
+        {
+          "label": "Locations",
+          "model": "@happyvertical/smrt-inventory:InventoryLocation",
+          "icon": "home",
+          "description": "The places you keep stock, like shelves, rooms or vans."
+        },
+        {
+          "label": "Stock movements",
+          "model": "@happyvertical/smrt-inventory:StockMovement",
+          "icon": "truck",
+          "description": "Every time stock came in, went out or moved."
+        }
+      ],
+      "requires": [],
+      "requiresAny": [
+        [
+          "products.simple",
+          "products.clothing"
+        ]
+      ],
+      "section": {
+        "id": "catalog",
+        "label": "Catalog",
+        "icon": "package",
+        "description": "Products, ingredients and the stock you hold."
+      },
+      "options": {
+        "@happyvertical/smrt-inventory:StockLevel": {
+          "fields": {
+            "reorderPoint": {
+              "visibility": "hidden"
+            },
+            "reorderQuantity": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-inventory:InventoryLocation": {
+          "fields": {
+            "placeId": {
+              "visibility": "hidden"
+            },
+            "active": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-inventory:StockMovement": {
+          "fields": {
+            "sourceType": {
+              "visibility": "hidden"
+            },
+            "sourceId": {
+              "visibility": "hidden"
+            },
+            "actorProfileId": {
+              "visibility": "hidden"
+            }
+          }
+        }
+      },
+      "help": {
+        "markdown": "## Overview\n\nInventory keeps count of how many of each product you have. Each count is a\nstock level: an item, the place it is kept and how many are on hand. Stock can\nsit in more than one place, and every change is recorded as a stock movement so\nthere is a trail.\n\n## Tasks\n\n### Count what you have\n\n1. Create a stock level for the item and the place it is kept.\n2. Set **{field:qty}** to how many you have on hand.\n3. Set **{field:state}** if the stock is not available to sell, for example\n   allocated or on quality hold.\n\n### Correct a count\n\n1. Find the stock level for the item.\n2. Set **{field:qty}** to what you really have. Record why as a stock movement.\n\n### Keep stock in more than one place\n\n1. Add a location with a **{field:code}** and a **{field:name}**, and say what\n   sort it is in **{field:kind}**.\n2. Create stock levels against that location.\n",
+        "fieldRefs": [
+          "code",
+          "kind",
+          "name",
+          "qty",
+          "state"
+        ]
+      },
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "Needs a server because its package depends on @happyvertical/smrt-tenancy, which do not build for a browser (#3624)."
+        ]
+      }
+    }
+  ],
+  "browser": {
+    "status": "server-only",
+    "issues": [
+      "#3624"
+    ],
+    "via": [
+      "@happyvertical/smrt-tenancy"
+    ]
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-inventory",
-  "version": "0.55.7",
+  "version": "0.55.8",
   "description": "Multi-location stock tracking for the SMRT framework — Sku, InventoryLocation, StockLevel, StockMovement, and a stock-mutation service",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,14 +24,14 @@
     }
   },
   "dependencies": {
-    "@happyvertical/logger": "^0.102.5",
-    "@happyvertical/smrt-core": "0.55.7",
-    "@happyvertical/smrt-tenancy": "0.55.7",
-    "@happyvertical/sql": "^0.102.5",
-    "@happyvertical/smrt-ui": "0.55.7"
+    "@happyvertical/logger": "^0.103.1",
+    "@happyvertical/smrt-core": "0.55.8",
+    "@happyvertical/smrt-tenancy": "0.55.8",
+    "@happyvertical/sql": "^0.103.1",
+    "@happyvertical/smrt-ui": "0.55.8"
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.55.7",
+    "@happyvertical/smrt-vitest": "0.55.8",
     "@types/node": "24.13.6",
     "typescript": "6.0.3",
     "vite": "8.1.4",