@porulle/core 0.1.0

package/dist/modules/inventory/repository/index.d.ts

@@ -0,0 +1,96 @@
+import type { TxContext } from "../../../kernel/database/tx-context.js";
+import type { DrizzleDatabase } from "../../../kernel/database/drizzle-db.js";
+import { warehouses, inventoryLevels, inventoryMovements } from "../schema.js";
+export type Warehouse = typeof warehouses.$inferSelect;
+export type WarehouseInsert = typeof warehouses.$inferInsert;
+export type InventoryLevel = typeof inventoryLevels.$inferSelect;
+export type InventoryLevelInsert = typeof inventoryLevels.$inferInsert;
+export type InventoryMovement = typeof inventoryMovements.$inferSelect;
+export type InventoryMovementInsert = typeof inventoryMovements.$inferInsert;
+/**
+ * InventoryRepository provides type-safe database operations for inventory entities.
+ *
+ * This repository manages warehouses, inventory levels, and inventory movements.
+ * All methods support an optional TxContext parameter for transaction participation.
+ */
+export declare class InventoryRepository {
+    private readonly db;
+    constructor(db: DrizzleDatabase);
+    private getDb;
+    private assertLevelOrg;
+    findWarehouseById(organizationId: string, id: string, ctx?: TxContext): Promise<Warehouse | undefined>;
+    findWarehouseByCode(orgId: string, code: string, ctx?: TxContext): Promise<Warehouse | undefined>;
+    findAllWarehouses(orgId: string, ctx?: TxContext): Promise<Warehouse[]>;
+    findActiveWarehouses(orgId: string, ctx?: TxContext): Promise<Warehouse[]>;
+    createWarehouse(data: WarehouseInsert, ctx?: TxContext): Promise<Warehouse>;
+    updateWarehouse(organizationId: string, id: string, data: Partial<Omit<WarehouseInsert, "id">>, ctx?: TxContext): Promise<Warehouse | undefined>;
+    deleteWarehouse(organizationId: string, id: string, ctx?: TxContext): Promise<boolean>;
+    findAllLevels(organizationId: string, ctx?: TxContext): Promise<InventoryLevel[]>;
+    findLevelById(organizationId: string, id: string, ctx?: TxContext): Promise<InventoryLevel | undefined>;
+    findLevelByKey(organizationId: string, entityId: string, warehouseId: string, variantId?: string | null, ctx?: TxContext): Promise<InventoryLevel | undefined>;
+    findLevelsByEntityId(organizationId: string, entityId: string, ctx?: TxContext): Promise<InventoryLevel[]>;
+    findLevelsByEntityAndVariant(organizationId: string, entityId: string, variantId?: string | null, ctx?: TxContext): Promise<InventoryLevel[]>;
+    findLevelsByWarehouseId(organizationId: string, warehouseId: string, ctx?: TxContext): Promise<InventoryLevel[]>;
+    createLevel(data: InventoryLevelInsert, ctx?: TxContext): Promise<InventoryLevel>;
+    updateLevel(organizationId: string, id: string, data: Partial<Omit<InventoryLevelInsert, "id">>, ctx?: TxContext): Promise<InventoryLevel | undefined>;
+    upsertLevel(organizationId: string, entityId: string, warehouseId: string, variantId: string | undefined, data: Omit<InventoryLevelInsert, "id" | "entityId" | "warehouseId" | "variantId" | "organizationId">, ctx?: TxContext): Promise<InventoryLevel>;
+    deleteLevel(organizationId: string, id: string, ctx?: TxContext): Promise<boolean>;
+    findMovementById(organizationId: string, id: string, ctx?: TxContext): Promise<InventoryMovement | undefined>;
+    findMovementsByEntityId(organizationId: string, entityId: string, ctx?: TxContext): Promise<InventoryMovement[]>;
+    findMovementsByReference(organizationId: string, referenceType: string, referenceId: string, ctx?: TxContext): Promise<InventoryMovement[]>;
+    createMovement(data: InventoryMovementInsert, ctx?: TxContext): Promise<InventoryMovement>;
+    /**
+     * Issues SELECT ... FOR UPDATE on the inventory_levels row matching
+     * the given entity, variant, and warehouse within the provided transaction.
+     *
+     * MUST be called inside an active transaction (ctx.tx must be set).
+     * Calling outside a transaction provides no locking guarantee.
+     *
+     * Uses isNull() for null variantId instead of eq() to generate correct
+     * SQL (IS NULL instead of = NULL).
+     */
+    findLevelForUpdate(organizationId: string, entityId: string, variantId: string | null, warehouseId: string, ctx: TxContext): Promise<InventoryLevel | undefined>;
+    /**
+     * Performs a read-modify-write under a row-level lock.
+     * This is the ONLY correct method for modifying quantityReserved
+     * in a concurrent environment. Must be called inside a transaction.
+     *
+     * The lock is held for the duration of the enclosing transaction,
+     * which is typically just the checkout reservation — microsecond-level.
+     */
+    reserveWithLock(organizationId: string, entityId: string, variantId: string | null, warehouseId: string, quantity: number, ctx: TxContext): Promise<{
+        ok: true;
+        level: InventoryLevel;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /**
+     * Performs a release under a row-level lock, mirroring reserveWithLock.
+     * Used by compensation chains to undo a reservation.
+     */
+    releaseWithLock(organizationId: string, entityId: string, variantId: string | null, warehouseId: string, quantity: number, ctx: TxContext): Promise<{
+        ok: true;
+        level: InventoryLevel;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /**
+     * Performs an atomic quantity adjust under a row-level lock.
+     * Uses SQL expressions for the increment so it is atomic even
+     * when multiple operations share a single database connection
+     * (e.g., PGlite test environments where SELECT FOR UPDATE
+     * cannot block across "transactions" on the same connection).
+     */
+    adjustWithLock(organizationId: string, entityId: string, variantId: string | null, warehouseId: string, adjustment: number, ctx: TxContext): Promise<{
+        ok: true;
+        level: InventoryLevel;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    getAvailableQuantity(organizationId: string, entityId: string, variantId?: string | null, ctx?: TxContext): Promise<number>;
+    getAvailableQuantities(organizationId: string, entityIds: string[], ctx?: TxContext): Promise<Record<string, number>>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/inventory/repository/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/modules/inventory/repository/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wCAAwC,CAAC;AACxE,OAAO,KAAK,EACV,eAAe,EAEhB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAG/E,MAAM,MAAM,SAAS,GAAG,OAAO,UAAU,CAAC,YAAY,CAAC;AACvD,MAAM,MAAM,eAAe,GAAG,OAAO,UAAU,CAAC,YAAY,CAAC;AAC7D,MAAM,MAAM,cAAc,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AACjE,MAAM,MAAM,oBAAoB,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,OAAO,kBAAkB,CAAC,YAAY,CAAC;AACvE,MAAM,MAAM,uBAAuB,GAAG,OAAO,kBAAkB,CAAC,YAAY,CAAC;AAE7E;;;;;GAKG;AACH,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,eAAe;IAEhD,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,cAAc;IAUhB,iBAAiB,CACrB,cAAc,EAAE,MAAM,EACtB,EAAE,EAAE,MAAM,EACV,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAW3B,mBAAmB,CACvB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAc3B,iBAAiB,CACrB,KAAK,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,SAAS,EAAE,CAAC;IAQjB,oBAAoB,CACxB,KAAK,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,SAAS,EAAE,CAAC;IAajB,eAAe,CACnB,IAAI,EAAE,eAAe,EACrB,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,SAAS,CAAC;IAMf,eAAe,CACnB,cAAc,EAAE,MAAM,EACtB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC,EAC1C,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAY3B,eAAe,CACnB,cAAc,EAAE,MAAM,EACtB,EAAE,EAAE,MAAM,EACV,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,OAAO,CAAC;IAeb,aAAa,CACjB,cAAc,EAAE,MAAM,EACtB,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,cAAc,EAAE,CAAC;IAQtB,aAAa,CACjB,cAAc,EAAE,MAAM,EACtB,EAAE,EAAE,MAAM,EACV,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAchC,cAAc,CAClB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,EACzB,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAwBhC,oBAAoB,CACxB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,cAAc,EAAE,CAAC;IAatB,4BAA4B,CAChC,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,EACzB,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,cAAc,EAAE,CAAC;IAuBtB,uBAAuB,CAC3B,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,EACnB,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,cAAc,EAAE,CAAC;IAatB,WAAW,CACf,IAAI,EAAE,oBAAoB,EAC1B,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,cAAc,CAAC;IAMpB,WAAW,CACf,cAAc,EAAE,MAAM,EACtB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE,IAAI,CAAC,CAAC,EAC/C,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAmBhC,WAAW,CACf,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,IAAI,EAAE,IAAI,CACR,oBAAoB,EACpB,IAAI,GAAG,UAAU,GAAG,aAAa,GAAG,WAAW,GAAG,gBAAgB,CACnE,EACD,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,cAAc,CAAC;IA6BpB,WAAW,CACf,cAAc,EAAE,MAAM,EACtB,EAAE,EAAE,MAAM,EACV,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,OAAO,CAAC;IAkBb,gBAAgB,CACpB,cAAc,EAAE,MAAM,EACtB,EAAE,EAAE,MAAM,EACV,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IAcnC,uBAAuB,CAC3B,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAazB,wBAAwB,CAC5B,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,EACnB,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAczB,cAAc,CAClB,IAAI,EAAE,uBAAuB,EAC7B,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,iBAAiB,CAAC;IAU7B;;;;;;;;;OASG;IACG,kBAAkB,CACtB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,SAAS,GACb,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAyBtC;;;;;;;OAOG;IACG,eAAe,CACnB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,SAAS,GACb,OAAO,CACR;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,cAAc,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CACpE;IA0CD;;;OAGG;IACG,eAAe,CACnB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,SAAS,GACb,OAAO,CACR;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,cAAc,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CACpE;IAkCD;;;;;;OAMG;IACG,cAAc,CAClB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,SAAS,GACb,OAAO,CACR;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,cAAc,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CACpE;IAsCK,oBAAoB,CACxB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,EACzB,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,MAAM,CAAC;IAaZ,sBAAsB,CAC1B,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EAAE,EACnB,GAAG,CAAC,EAAE,SAAS,GACd,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CA0BnC"}

package/dist/modules/inventory/repository/index.js

@@ -0,0 +1,361 @@
+import { eq, and, inArray, isNull, sql } from "drizzle-orm";
+import { CommerceValidationError } from "../../../kernel/errors.js";
+import { warehouses, inventoryLevels, inventoryMovements } from "../schema.js";
+/**
+ * InventoryRepository provides type-safe database operations for inventory entities.
+ *
+ * This repository manages warehouses, inventory levels, and inventory movements.
+ * All methods support an optional TxContext parameter for transaction participation.
+ */
+export class InventoryRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    getDb(ctx) {
+        return ctx?.tx ?? this.db;
+    }
+    assertLevelOrg(level, organizationId) {
+        if (level.organizationId !== organizationId) {
+            throw new CommerceValidationError("Inventory level organization mismatch.");
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Warehouses
+    // ─────────────────────────────────────────────────────────────────────────────
+    async findWarehouseById(organizationId, id, ctx) {
+        const db = this.getDb(ctx);
+        const rows = await db
+            .select()
+            .from(warehouses)
+            .where(and(eq(warehouses.id, id), eq(warehouses.organizationId, organizationId)));
+        return rows[0];
+    }
+    async findWarehouseByCode(orgId, code, ctx) {
+        const db = this.getDb(ctx);
+        const rows = await db
+            .select()
+            .from(warehouses)
+            .where(and(eq(warehouses.organizationId, orgId), eq(warehouses.code, code)));
+        return rows[0];
+    }
+    async findAllWarehouses(orgId, ctx) {
+        const db = this.getDb(ctx);
+        return db
+            .select()
+            .from(warehouses)
+            .where(eq(warehouses.organizationId, orgId));
+    }
+    async findActiveWarehouses(orgId, ctx) {
+        const db = this.getDb(ctx);
+        return db
+            .select()
+            .from(warehouses)
+            .where(and(eq(warehouses.organizationId, orgId), eq(warehouses.isActive, true)));
+    }
+    async createWarehouse(data, ctx) {
+        const db = this.getDb(ctx);
+        const rows = await db.insert(warehouses).values(data).returning();
+        return rows[0];
+    }
+    async updateWarehouse(organizationId, id, data, ctx) {
+        const db = this.getDb(ctx);
+        const rows = await db
+            .update(warehouses)
+            .set(data)
+            .where(and(eq(warehouses.id, id), eq(warehouses.organizationId, organizationId)))
+            .returning();
+        return rows[0];
+    }
+    async deleteWarehouse(organizationId, id, ctx) {
+        const db = this.getDb(ctx);
+        const result = await db
+            .delete(warehouses)
+            .where(and(eq(warehouses.id, id), eq(warehouses.organizationId, organizationId)))
+            .returning();
+        return result.length > 0;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Inventory Levels
+    // ─────────────────────────────────────────────────────────────────────────────
+    async findAllLevels(organizationId, ctx) {
+        const db = this.getDb(ctx);
+        return db
+            .select()
+            .from(inventoryLevels)
+            .where(eq(inventoryLevels.organizationId, organizationId));
+    }
+    async findLevelById(organizationId, id, ctx) {
+        const db = this.getDb(ctx);
+        const rows = await db
+            .select()
+            .from(inventoryLevels)
+            .where(and(eq(inventoryLevels.id, id), eq(inventoryLevels.organizationId, organizationId)));
+        return rows[0];
+    }
+    async findLevelByKey(organizationId, entityId, warehouseId, variantId, ctx) {
+        const db = this.getDb(ctx);
+        const conditions = [
+            eq(inventoryLevels.organizationId, organizationId),
+            eq(inventoryLevels.entityId, entityId),
+            eq(inventoryLevels.warehouseId, warehouseId),
+        ];
+        // Only add variantId condition when it's a real string value — never pass null to eq()
+        if (variantId != null) {
+            conditions.push(eq(inventoryLevels.variantId, variantId));
+        }
+        const rows = await db
+            .select()
+            .from(inventoryLevels)
+            .where(and(...conditions));
+        // Post-filter for exact variantId match (handles SQL NULL correctly)
+        const level = rows.find((r) => r.variantId === (variantId ?? null));
+        if (level)
+            this.assertLevelOrg(level, organizationId);
+        return level;
+    }
+    async findLevelsByEntityId(organizationId, entityId, ctx) {
+        const db = this.getDb(ctx);
+        return db
+            .select()
+            .from(inventoryLevels)
+            .where(and(eq(inventoryLevels.entityId, entityId), eq(inventoryLevels.organizationId, organizationId)));
+    }
+    async findLevelsByEntityAndVariant(organizationId, entityId, variantId, ctx) {
+        const db = this.getDb(ctx);
+        const conditions = [
+            eq(inventoryLevels.organizationId, organizationId),
+            eq(inventoryLevels.entityId, entityId),
+        ];
+        // Only add variantId condition when it's a real string value — never pass null to eq()
+        if (variantId != null) {
+            conditions.push(eq(inventoryLevels.variantId, variantId));
+        }
+        const rows = await db
+            .select()
+            .from(inventoryLevels)
+            .where(and(...conditions));
+        // Post-filter for exact variantId match (handles SQL NULL correctly in JS)
+        return rows.filter((r) => variantId == null ? r.variantId === null : r.variantId === variantId);
+    }
+    async findLevelsByWarehouseId(organizationId, warehouseId, ctx) {
+        const db = this.getDb(ctx);
+        return db
+            .select()
+            .from(inventoryLevels)
+            .where(and(eq(inventoryLevels.warehouseId, warehouseId), eq(inventoryLevels.organizationId, organizationId)));
+    }
+    async createLevel(data, ctx) {
+        const db = this.getDb(ctx);
+        const rows = await db.insert(inventoryLevels).values(data).returning();
+        return rows[0];
+    }
+    async updateLevel(organizationId, id, data, ctx) {
+        const db = this.getDb(ctx);
+        const rows = await db
+            .update(inventoryLevels)
+            .set({
+            ...data,
+            updatedAt: new Date(),
+            version: sql `${inventoryLevels.version} + 1`,
+        })
+            .where(and(eq(inventoryLevels.id, id), eq(inventoryLevels.organizationId, organizationId)))
+            .returning();
+        return rows[0];
+    }
+    async upsertLevel(organizationId, entityId, warehouseId, variantId, data, ctx) {
+        const existing = await this.findLevelByKey(organizationId, entityId, warehouseId, variantId, ctx);
+        if (existing) {
+            const updated = await this.updateLevel(organizationId, existing.id, data, ctx);
+            return updated;
+        }
+        return this.createLevel({
+            ...data,
+            organizationId,
+            entityId,
+            warehouseId,
+            ...(variantId !== undefined ? { variantId } : {}),
+        }, ctx);
+    }
+    async deleteLevel(organizationId, id, ctx) {
+        const db = this.getDb(ctx);
+        const result = await db
+            .delete(inventoryLevels)
+            .where(and(eq(inventoryLevels.id, id), eq(inventoryLevels.organizationId, organizationId)))
+            .returning();
+        return result.length > 0;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Inventory Movements
+    // ─────────────────────────────────────────────────────────────────────────────
+    async findMovementById(organizationId, id, ctx) {
+        const db = this.getDb(ctx);
+        const rows = await db
+            .select()
+            .from(inventoryMovements)
+            .where(and(eq(inventoryMovements.id, id), eq(inventoryMovements.organizationId, organizationId)));
+        return rows[0];
+    }
+    async findMovementsByEntityId(organizationId, entityId, ctx) {
+        const db = this.getDb(ctx);
+        return db
+            .select()
+            .from(inventoryMovements)
+            .where(and(eq(inventoryMovements.entityId, entityId), eq(inventoryMovements.organizationId, organizationId)));
+    }
+    async findMovementsByReference(organizationId, referenceType, referenceId, ctx) {
+        const db = this.getDb(ctx);
+        return db
+            .select()
+            .from(inventoryMovements)
+            .where(and(eq(inventoryMovements.organizationId, organizationId), eq(inventoryMovements.referenceType, referenceType), eq(inventoryMovements.referenceId, referenceId)));
+    }
+    async createMovement(data, ctx) {
+        const db = this.getDb(ctx);
+        const rows = await db.insert(inventoryMovements).values(data).returning();
+        return rows[0];
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Concurrency-Safe Operations (SELECT FOR UPDATE)
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Issues SELECT ... FOR UPDATE on the inventory_levels row matching
+     * the given entity, variant, and warehouse within the provided transaction.
+     *
+     * MUST be called inside an active transaction (ctx.tx must be set).
+     * Calling outside a transaction provides no locking guarantee.
+     *
+     * Uses isNull() for null variantId instead of eq() to generate correct
+     * SQL (IS NULL instead of = NULL).
+     */
+    async findLevelForUpdate(organizationId, entityId, variantId, warehouseId, ctx) {
+        const db = this.getDb(ctx);
+        const conditions = [
+            eq(inventoryLevels.organizationId, organizationId),
+            eq(inventoryLevels.entityId, entityId),
+            eq(inventoryLevels.warehouseId, warehouseId),
+            variantId != null
+                ? eq(inventoryLevels.variantId, variantId)
+                : isNull(inventoryLevels.variantId),
+        ];
+        // Use raw SQL for FOR UPDATE since Drizzle's .for() may not be available
+        // on all query builder paths. This is the most portable approach.
+        const rows = await db
+            .select()
+            .from(inventoryLevels)
+            .where(and(...conditions))
+            .for("update");
+        const level = rows[0];
+        if (level)
+            this.assertLevelOrg(level, organizationId);
+        return level;
+    }
+    /**
+     * Performs a read-modify-write under a row-level lock.
+     * This is the ONLY correct method for modifying quantityReserved
+     * in a concurrent environment. Must be called inside a transaction.
+     *
+     * The lock is held for the duration of the enclosing transaction,
+     * which is typically just the checkout reservation — microsecond-level.
+     */
+    async reserveWithLock(organizationId, entityId, variantId, warehouseId, quantity, ctx) {
+        const level = await this.findLevelForUpdate(organizationId, entityId, variantId, warehouseId, ctx);
+        if (!level) {
+            return {
+                ok: false,
+                reason: "No inventory record found for this entity.",
+            };
+        }
+        const available = level.quantityOnHand - level.quantityReserved;
+        if (available < quantity) {
+            return {
+                ok: false,
+                reason: `Insufficient stock. Available: ${available}, requested: ${quantity}.`,
+            };
+        }
+        const updated = await this.getDb(ctx)
+            .update(inventoryLevels)
+            .set({
+            quantityReserved: level.quantityReserved + quantity,
+            updatedAt: new Date(),
+            version: level.version + 1,
+        })
+            .where(and(eq(inventoryLevels.id, level.id), eq(inventoryLevels.organizationId, organizationId)))
+            .returning();
+        return { ok: true, level: updated[0] };
+    }
+    /**
+     * Performs a release under a row-level lock, mirroring reserveWithLock.
+     * Used by compensation chains to undo a reservation.
+     */
+    async releaseWithLock(organizationId, entityId, variantId, warehouseId, quantity, ctx) {
+        const level = await this.findLevelForUpdate(organizationId, entityId, variantId, warehouseId, ctx);
+        if (!level) {
+            return {
+                ok: false,
+                reason: "No inventory record found for this entity.",
+            };
+        }
+        const updated = await this.getDb(ctx)
+            .update(inventoryLevels)
+            .set({
+            quantityReserved: Math.max(0, level.quantityReserved - quantity),
+            updatedAt: new Date(),
+            version: level.version + 1,
+        })
+            .where(and(eq(inventoryLevels.id, level.id), eq(inventoryLevels.organizationId, organizationId)))
+            .returning();
+        return { ok: true, level: updated[0] };
+    }
+    /**
+     * Performs an atomic quantity adjust under a row-level lock.
+     * Uses SQL expressions for the increment so it is atomic even
+     * when multiple operations share a single database connection
+     * (e.g., PGlite test environments where SELECT FOR UPDATE
+     * cannot block across "transactions" on the same connection).
+     */
+    async adjustWithLock(organizationId, entityId, variantId, warehouseId, adjustment, ctx) {
+        const level = await this.findLevelForUpdate(organizationId, entityId, variantId, warehouseId, ctx);
+        if (!level) {
+            return {
+                ok: false,
+                reason: "No inventory record found for this entity.",
+            };
+        }
+        const updated = await this.getDb(ctx)
+            .update(inventoryLevels)
+            .set({
+            quantityOnHand: sql `GREATEST(0, ${inventoryLevels.quantityOnHand} + ${adjustment})`,
+            updatedAt: new Date(),
+            version: sql `${inventoryLevels.version} + 1`,
+        })
+            .where(and(eq(inventoryLevels.id, level.id), eq(inventoryLevels.organizationId, organizationId)))
+            .returning();
+        return { ok: true, level: updated[0] };
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Aggregate Queries
+    // ─────────────────────────────────────────────────────────────────────────────
+    async getAvailableQuantity(organizationId, entityId, variantId, ctx) {
+        const levels = await this.findLevelsByEntityAndVariant(organizationId, entityId, variantId, ctx);
+        return levels.reduce((sum, level) => sum + (level.quantityOnHand - level.quantityReserved), 0);
+    }
+    async getAvailableQuantities(organizationId, entityIds, ctx) {
+        if (entityIds.length === 0)
+            return {};
+        const db = this.getDb(ctx);
+        const rows = await db
+            .select()
+            .from(inventoryLevels)
+            .where(and(eq(inventoryLevels.organizationId, organizationId), inArray(inventoryLevels.entityId, entityIds)));
+        const result = {};
+        for (const id of entityIds) {
+            result[id] = 0;
+        }
+        for (const row of rows) {
+            const available = row.quantityOnHand - row.quantityReserved;
+            result[row.entityId] = (result[row.entityId] ?? 0) + available;
+        }
+        return result;
+    }
+}