@tailor-platform/erp-kit 0.4.0 → 0.5.0

package/src/modules/coa-management/module.ts

@@ -1,5 +1,4 @@
 import { type TailorAnyDBField } from "@tailor-platform/sdk";
-import { type EmptyFields, type FieldsToInsertable } from "../../shared";
 import type { defineModule as defineOrganizationModule } from "../organization";
 import type { defineModule as definePrimitivesModule } from "../primitives";
 import type { TemplateProvider, AuditCommands } from "./command/createChartOfAccounts";
@@ -34,6 +33,7 @@ import {
 } from "./db/chartOfAccounts";
 import { createAccountGroupType, type CreateAccountGroupTypeParams } from "./db/accountGroup";
 import { createAccountType, type CreateAccountTypeParams } from "./db/account";
+import { type EmptyFields, type FieldsToInsertable } from "@tailor-platform/erp-kit/module";
 
 type OrganizationModule = ReturnType<typeof defineOrganizationModule>;
 type OrganizationDB = OrganizationModule["db"];

package/src/modules/coa-management/permissions.ts

@@ -1,3 +1,3 @@
-import { definePermissions } from "../../shared";
+import { definePermissions } from "@tailor-platform/erp-kit/module";
 
 export const { permissions, own, all } = definePermissions("coa-management", [] as const);

package/src/modules/coa-management/query/detectCircularReference.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { defineQuery } from "../../../shared";
 import { run } from "./detectCircularReference";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
 
 export const detectCircularReference = defineQuery(run);

package/src/modules/coa-management/query/detectCircularReference.ts

@@ -1,5 +1,5 @@
-import { ok, type ReadonlyDB } from "../../../shared";
 import type { DB } from "../generated/kysely-tailordb";
+import { ok, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
 
 export interface DetectCircularReferenceInput {
   groupId: string;

package/src/modules/coa-management/query/getAccount.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { defineQuery } from "../../../shared";
 import { run } from "./getAccount";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
 
 export const getAccount = defineQuery(run);

package/src/modules/coa-management/query/getAccount.ts

@@ -1,5 +1,5 @@
-import { ok, type ReadonlyDB } from "../../../shared";
 import type { DB } from "../generated/kysely-tailordb";
+import { ok, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
 
 export type GetAccountInput = { id: string } | { chartOfAccountsId: string; code: string };
 

package/src/modules/coa-management/query/getAccountGroup.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { defineQuery } from "../../../shared";
 import { run } from "./getAccountGroup";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
 
 export const getAccountGroup = defineQuery(run);

package/src/modules/coa-management/query/getAccountGroup.ts

@@ -1,5 +1,5 @@
-import { ok, type ReadonlyDB } from "../../../shared";
 import type { DB } from "../generated/kysely-tailordb";
+import { ok, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
 
 export type GetAccountGroupInput = { id: string } | { chartOfAccountsId: string; code: string };
 

package/src/modules/coa-management/query/getChartOfAccounts.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { defineQuery } from "../../../shared";
 import { run } from "./getChartOfAccounts";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
 
 export const getChartOfAccounts = defineQuery(run);

package/src/modules/coa-management/query/getChartOfAccounts.ts

@@ -1,6 +1,6 @@
-import { ok, type ReadonlyDB } from "../../../shared";
 import type { ChartOfAccountsStatus } from "../generated/enums";
 import type { DB } from "../generated/kysely-tailordb";
+import { ok, type ReadonlyDB } from "@tailor-platform/erp-kit/module";
 
 export type GetChartOfAccountsInput = { id: string } | { companyId: string; status?: string };
 

package/src/modules/coa-management/query/listAccountGroups.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { defineQuery } from "../../../shared";
 import { run } from "./listAccountGroups";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
 
 export const listAccountGroups = defineQuery(run);

package/src/modules/coa-management/query/listAccountGroups.ts

@@ -1,11 +1,11 @@
+import type { DB } from "../generated/kysely-tailordb";
 import {
   ok,
   type ReadonlyDB,
   type PaginationInput,
   buildPaginatedResult,
   DEFAULT_PAGE_SIZE,
-} from "../../../shared";
-import type { DB } from "../generated/kysely-tailordb";
+} from "@tailor-platform/erp-kit/module";
 
 type AccountGroupOrderByField = "code" | "name" | "sortOrder" | "createdAt";
 

package/src/modules/coa-management/query/listAccounts.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { defineQuery } from "../../../shared";
 import { run } from "./listAccounts";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
 
 export const listAccounts = defineQuery(run);

package/src/modules/coa-management/query/listAccounts.ts

@@ -1,12 +1,12 @@
+import type { AccountAccountType, AccountClassification, AccountStatus } from "../generated/enums";
+import type { DB } from "../generated/kysely-tailordb";
 import {
   ok,
   type ReadonlyDB,
   type PaginationInput,
   buildPaginatedResult,
   DEFAULT_PAGE_SIZE,
-} from "../../../shared";
-import type { AccountAccountType, AccountClassification, AccountStatus } from "../generated/enums";
-import type { DB } from "../generated/kysely-tailordb";
+} from "@tailor-platform/erp-kit/module";
 
 type AccountOrderByField =
   | "code"

package/src/modules/coa-management/query/listUnassignedAccounts.generated.ts

@@ -1,5 +1,5 @@
 // @generated — do not edit
-import { defineQuery } from "../../../shared";
 import { run } from "./listUnassignedAccounts";
+import { defineQuery } from "@tailor-platform/erp-kit/module";
 
 export const listUnassignedAccounts = defineQuery(run);

package/src/modules/coa-management/query/listUnassignedAccounts.ts

@@ -1,11 +1,11 @@
+import type { DB } from "../generated/kysely-tailordb";
 import {
   ok,
   type ReadonlyDB,
   type PaginationInput,
   buildPaginatedResult,
   DEFAULT_PAGE_SIZE,
-} from "../../../shared";
-import type { DB } from "../generated/kysely-tailordb";
+} from "@tailor-platform/erp-kit/module";
 
 type UnassignedAccountOrderByField = "code" | "name" | "createdAt";
 

package/src/modules/inventory/README.md

@@ -0,0 +1,65 @@
+# README
+
+## Overview
+
+The Inventory module manages physical stock tracking across warehouses and storage locations. It provides real-time visibility into on-hand quantities, records all stock movements (receipts, issues, transfers, adjustments), and supports lot/batch and serial number traceability. The module also handles inventory valuation, physical inventory counts, and scrap disposal.
+
+Inventory operates at the Item level (from item-management) and tracks stock within Warehouses and StorageLocations that the module owns. Organization's Site entity represents the physical facility; Inventory's Warehouse represents the operational storage structure within a Site.
+
+## Key Features
+
+- **Warehouse Management**: Define warehouses and storage locations (zones, bins) within organizational sites
+- **Stock Tracking**: Real-time on-hand, reserved, incoming, and blocked quantities per item per location
+- **Stock Movement**: Record goods receipts, goods issues, and internal transfers with full audit trail
+- **Inventory Adjustment**: Manual corrections for discrepancies, damage, and shrinkage
+- **Lot and Batch Tracking**: Lot/batch-level traceability with expiration date management
+- **Serial Number Tracking**: Individual item tracking by unique serial number across lifecycle
+- **Inventory Valuation**: Cost calculation using FIFO, weighted average, or standard cost methods
+- **Inventory Count**: Physical inventory counts and cycle counts with variance review and approval
+- **Scrap Management**: Record and track disposal of damaged, expired, or defective stock
+
+## Module Scope
+
+### In Scope
+
+- Warehouse and storage location (zone/bin) definition and management
+- Real-time stock level tracking per item per location (on-hand, reserved, incoming, blocked)
+- Stock movement recording: goods receipt, goods issue, internal transfer
+- Inventory adjustment with reason codes
+- Lot/batch assignment, tracking, and expiration date management
+- Serial number assignment and lifecycle tracking
+- Inventory valuation method configuration (FIFO, weighted average, standard cost)
+- Cost-per-unit tracking and valuation amount calculation
+- Physical inventory count and cycle count workflows
+- Scrap/disposal recording with quantity and valuation impact
+
+### Out of Scope
+
+- Purchase order lifecycle management (purchasing module)
+- Sales order and fulfillment workflows (sales module)
+- Automated reorder point and replenishment rules (purchasing module)
+- Pick/pack/ship multi-step fulfillment (warehouse operations / sales module)
+- Putaway rules and automated storage location assignment
+- Removal strategies — automated FIFO/FEFO/LIFO picking rules
+- Demand forecasting and planning
+- Drop-shipping and cross-docking
+- Landed cost allocation (purchasing / accounting module)
+- Journal entry posting to general ledger (accounting module)
+- Barcode scanning device integration (application layer)
+- Shipping carrier integration (application layer)
+
+### Scope Decision Rationale
+
+Inventory owns **physical stock state** — where items are, how many exist, and what they cost. This is separated from purchasing (which owns the procurement lifecycle) and sales (which owns the fulfillment lifecycle) because stock tracking follows its own business rules and update patterns.
+
+Warehouse and StorageLocation are owned by this module (not organization) because they represent operational storage structures with inventory-specific attributes (capacity, storage conditions, bin types). Organization's Site represents the physical facility identity and address; Warehouse adds the storage layout within that facility.
+
+Lot/batch and serial number tracking live here (not in item-management) because they are inventory-layer concepts — they track "which specific instances" of an item exist, not "what the item is." Item-management explicitly defers these concerns to the inventory module.
+
+Inventory valuation is included because cost-per-unit is intrinsically tied to stock movements (receipt costs, adjustment impacts). However, posting journal entries to the general ledger is excluded — that responsibility belongs to a future accounting module. Inventory will emit valuation events for downstream consumption.
+
+## Module Dependencies
+
+- [item-management](../item-management/README.md) — Item entity as the primary trackable unit (itemId/SKU)
+- [organization](../organization/README.md) — Company for multi-company scoping, Site for warehouse location
+- [primitives](../primitives/README.md) — Unit of Measure for stock quantities, Currency for valuation amounts

package/src/modules/inventory/command/approveCountLine.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./approveCountLine";
+import { defineCommand } from "@tailor-platform/erp-kit/module";
+
+export const approveCountLine = defineCommand(permissions.approveCountLine, run);

package/src/modules/inventory/command/approveCountLine.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { CountLineNotFoundError, CountLineNotPendingError } from "../lib/errors.generated";
+import { basePendingCountLine, baseApprovedCountLine } from "../testing/fixtures";
+import { run } from "./approveCountLine";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("approveCountLine", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["inventory:approveCountLine"],
+  };
+
+  it("returns error when not found", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined); // line not found
+
+    const result = await run(db, { countLineId: "nonexistent" }, ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CountLineNotFoundError);
+    }
+  });
+
+  it("returns error when not pending", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseApprovedCountLine); // already APPROVED
+
+    const result = await run(db, { countLineId: "count-line-2" }, ctx);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CountLineNotPendingError);
+    }
+  });
+
+  it("approves line", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const approvedLine = { ...basePendingCountLine, status: "APPROVED" };
+
+    spies.select.mockReturnValueOnce(basePendingCountLine); // line lookup
+    spies.update.mockReturnValue(approvedLine);
+    spies.insert.mockReturnValue({ id: "adjustment-new" }); // adjustment created
+
+    const result = await run(db, { countLineId: "count-line-1" }, ctx);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.countLine.status).toBe("APPROVED");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+
+  it("generates adjustment for non-zero variance", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    // basePendingCountLine has variance: -2
+    const approvedLine = { ...basePendingCountLine, status: "APPROVED" };
+
+    spies.select.mockReturnValueOnce(basePendingCountLine);
+    spies.update.mockReturnValue(approvedLine);
+    spies.insert.mockReturnValue({ id: "adjustment-new" });
+
+    const result = await run(db, { countLineId: "count-line-1" }, ctx);
+    expect(result.ok).toBe(true);
+    expect(spies.insert).toHaveBeenCalled();
+    expect(spies.values).toHaveBeenCalledWith(
+      expect.objectContaining({
+        reasonCode: "inventory-count",
+        quantityDelta: -2,
+      }),
+    );
+  });
+
+  it("zero variance approved without adjustment", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const zeroVarianceLine = { ...basePendingCountLine, variance: 0 };
+    const approvedLine = { ...zeroVarianceLine, status: "APPROVED" };
+
+    spies.select.mockReturnValueOnce(zeroVarianceLine);
+    spies.update.mockReturnValue(approvedLine);
+
+    const result = await run(db, { countLineId: "count-line-1" }, ctx);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.countLine.status).toBe("APPROVED");
+    }
+    // No insert should have been called for adjustment
+    expect(spies.insert).not.toHaveBeenCalled();
+  });
+});

package/src/modules/inventory/command/approveCountLine.ts

@@ -0,0 +1,68 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import { CountLineNotFoundError, CountLineNotPendingError } from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface ApproveCountLineInput {
+  countLineId: string;
+}
+
+/**
+ * Function: approveCountLine
+ *
+ * Approves a count line variance, transitioning it from PENDING to APPROVED.
+ * When variance is non-zero, generates an inventory adjustment with reason "inventory-count".
+ */
+export async function run(db: Transaction, input: ApproveCountLineInput, _ctx: CommandContext) {
+  const { countLineId } = input;
+
+  // 1. Fetch count line
+  const countLine = await db
+    .selectFrom("InventoryCountLine")
+    .selectAll()
+    .where("id", "=", countLineId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!countLine) {
+    return err(new CountLineNotFoundError(countLineId));
+  }
+
+  // 2. Validate status
+  if (countLine.status !== "PENDING") {
+    return err(new CountLineNotPendingError(countLineId));
+  }
+
+  // 3. Approve the line
+  const updatedLine = await db
+    .updateTable("InventoryCountLine")
+    .set({
+      status: "APPROVED",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", countLineId)
+    .returningAll()
+    .executeTakeFirst();
+
+  // 4. Generate adjustment if variance is non-zero
+  if (countLine.variance !== 0 && countLine.variance !== null) {
+    await db
+      .insertInto("InventoryAdjustment")
+      .values({
+        adjustmentType: "CORRECTION",
+        itemId: countLine.itemId,
+        storageLocationId: countLine.storageLocationId,
+        quantityDelta: countLine.variance,
+        reasonCode: "inventory-count",
+        status: "APPROVED",
+        inventoryCountId: countLine.inventoryCountId,
+        lotId: null,
+        serialNumberId: null,
+        createdAt: new Date(),
+        updatedAt: null,
+      })
+      .returningAll()
+      .executeTakeFirst();
+  }
+
+  return ok({ countLine: updatedLine! });
+}

package/src/modules/inventory/command/approveInventoryAdjustment.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./approveInventoryAdjustment";
+import { defineCommand } from "@tailor-platform/erp-kit/module";
+
+export const approveInventoryAdjustment = defineCommand(permissions.approveInventoryAdjustment, run);

package/src/modules/inventory/command/approveInventoryAdjustment.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AdjustmentNotFoundError,
+  AdjustmentNotPendingApprovalError,
+} from "../lib/errors.generated";
+import { basePendingApprovalAdjustment, baseDraftAdjustment } from "../testing/fixtures";
+import { run } from "./approveInventoryAdjustment";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("approveInventoryAdjustment", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["inventory:approveInventoryAdjustment"],
+  };
+
+  it("returns error when not found", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "nonexistent" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(AdjustmentNotFoundError);
+    }
+  });
+
+  it("returns error when not pending", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseDraftAdjustment);
+
+    const result = await run(db, { id: "adjustment-1" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(AdjustmentNotPendingApprovalError);
+    }
+  });
+
+  it("approves adjustment", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updated = { ...basePendingApprovalAdjustment, status: "APPROVED" };
+    spies.select.mockReturnValueOnce(basePendingApprovalAdjustment);
+    spies.update.mockReturnValue(updated);
+
+    const result = await run(db, { id: "adjustment-2" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.adjustment.status).toBe("APPROVED");
+    }
+    expect(spies.update).toHaveBeenCalled();
+  });
+});

package/src/modules/inventory/command/approveInventoryAdjustment.ts

@@ -0,0 +1,50 @@
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AdjustmentNotFoundError,
+  AdjustmentNotPendingApprovalError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface ApproveInventoryAdjustmentInput {
+  id: string;
+}
+
+/**
+ * Function: approveInventoryAdjustment
+ *
+ * Approves a pending inventory adjustment, transitioning it from PENDING_APPROVAL to APPROVED status.
+ */
+export async function run(
+  db: Transaction,
+  input: ApproveInventoryAdjustmentInput,
+  _ctx: CommandContext,
+) {
+  const { id } = input;
+
+  // 1. Fetch adjustment
+  const adjustment = await db
+    .selectFrom("InventoryAdjustment")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!adjustment) {
+    return err(new AdjustmentNotFoundError(id));
+  }
+
+  // 2. Validate status is PENDING_APPROVAL
+  if (adjustment.status !== "PENDING_APPROVAL") {
+    return err(new AdjustmentNotPendingApprovalError(id));
+  }
+
+  // 3. Update status to APPROVED
+  const updated = await db
+    .updateTable("InventoryAdjustment")
+    .set({ status: "APPROVED", updatedAt: new Date() })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ adjustment: updated! });
+}

package/src/modules/inventory/command/assignSerialNumber.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./assignSerialNumber";
+import { defineCommand } from "@tailor-platform/erp-kit/module";
+
+export const assignSerialNumber = defineCommand(permissions.assignSerialNumber, run);

package/src/modules/inventory/command/assignSerialNumber.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ItemNotFoundError,
+  StorageLocationNotFoundError,
+  DuplicateSerialNumberError,
+} from "../lib/errors.generated";
+import { baseAvailableSerial, baseZone } from "../testing/fixtures";
+import { run } from "./assignSerialNumber";
+import { ok } from "@tailor-platform/erp-kit/module";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+describe("assignSerialNumber", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["inventory:assignSerialNumber"],
+  };
+
+  const mockGetItemFound = {
+    getItem: () => Promise.resolve(ok({ item: { id: "item-1" } })),
+  };
+
+  const mockGetItemNotFound = {
+    getItem: () => Promise.resolve(ok({ item: null })),
+  };
+
+  it("returns error when item not found", async () => {
+    const { db } = createMockDb<Transaction>();
+
+    const result = await run(
+      db,
+      { serialNumber: "SN-001", itemId: "nonexistent", storageLocationId: "location-1" },
+      ctx,
+      mockGetItemNotFound,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ItemNotFoundError);
+    }
+  });
+
+  it("returns error when location not found", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined); // location not found
+
+    const result = await run(
+      db,
+      { serialNumber: "SN-001", itemId: "item-1", storageLocationId: "nonexistent" },
+      ctx,
+      mockGetItemFound,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(StorageLocationNotFoundError);
+    }
+  });
+
+  it("returns error when serial already exists for item", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseZone) // location found
+      .mockReturnValueOnce(baseAvailableSerial); // duplicate serial found
+
+    const result = await run(
+      db,
+      { serialNumber: "SN-001", itemId: "item-1", storageLocationId: "location-1" },
+      ctx,
+      mockGetItemFound,
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(DuplicateSerialNumberError);
+    }
+  });
+
+  it("assigns serial in AVAILABLE state", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdSerial = {
+      ...baseAvailableSerial,
+      id: "new-serial-id",
+      serialNumber: "SN-NEW",
+    };
+    spies.select
+      .mockReturnValueOnce(baseZone) // location found
+      .mockReturnValueOnce(undefined); // no duplicate
+    spies.insert.mockReturnValue(createdSerial);
+
+    const result = await run(
+      db,
+      { serialNumber: "SN-NEW", itemId: "item-1", storageLocationId: "location-1" },
+      ctx,
+      mockGetItemFound,
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.serialNumber.serialNumber).toBe("SN-NEW");
+      expect(result.value.serialNumber.status).toBe("AVAILABLE");
+    }
+    expect(spies.insert).toHaveBeenCalled();
+  });
+
+  it("allows same serial number for different items", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdSerial = {
+      ...baseAvailableSerial,
+      id: "new-serial-id",
+      serialNumber: "SN-001",
+      itemId: "item-2",
+    };
+    spies.select
+      .mockReturnValueOnce(baseZone) // location found
+      .mockReturnValueOnce(undefined); // no duplicate for item-2
+    spies.insert.mockReturnValue(createdSerial);
+
+    const mockGetItem2 = {
+      getItem: () => Promise.resolve(ok({ item: { id: "item-2" } })),
+    };
+
+    const result = await run(
+      db,
+      { serialNumber: "SN-001", itemId: "item-2", storageLocationId: "location-1" },
+      ctx,
+      mockGetItem2,
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.serialNumber.serialNumber).toBe("SN-001");
+      expect(result.value.serialNumber.itemId).toBe("item-2");
+    }
+    expect(spies.insert).toHaveBeenCalled();
+  });
+});