Review an inventory reservation workflow

Review exercise · TypeScript

Review brief

Advanced45 min

An order service is introducing durable inventory reservations. Requests for the same SKU may arrive concurrently, and clients retry timed-out calls using an idempotency key. Review the implementation and its tests for stock integrity, failure atomicity, and replay behavior.

Behavioral contract

A reservation succeeds when available stock is greater than or equal to the requested quantity; request quantities are positive integers validated before this service is called.
Concurrent reservations must never reduce a SKU below zero or confirm more units than exist.
The stock decrement and reservation insert are one atomic outcome. If insertion fails, stock must remain unchanged.
Request keys are scoped by account. Repeating a completed `(accountId, requestKey)` replays the original reservation without changing stock.
Concurrent uses of the same account-scoped request key must produce one reservation and one decrement; the durable claim cannot be a separate check before the transaction.
The production database supports transactions and a unique constraint on `(account_id, request_key)`; the implementation must use them without relying on sequential execution.

Review instructions

1Review only the changed code against the stock and idempotency contract.
2Trace both concurrent interleavings and failures between persistence operations.
3Prioritize no more than six findings and include test feedback only when it leaves required behavior unprotected.

Learning objectives

• Trace race windows in read-modify-write logic
• Review transaction boundaries under failure
• Require atomic idempotency claims for retries

src/inventory-reservation-types.tsTypeScript

@@ -0,0 +1,42 @@

1+export interface ReservationRequest {

2+ accountId: string;

3+ requestKey: string;

4+ warehouseId: string;

5+ sku: string;

6+ quantity: number;

7+}

9+export interface Reservation {

10+ id: string;

11+ accountId: string;

12+ requestKey: string;

13+ warehouseId: string;

14+ sku: string;

15+ quantity: number;

16+}

17+

18+export interface InventoryGateway {

19+ getAvailable(warehouseId: string, sku: string): Promise<number>;

20+ decrement(warehouseId: string, sku: string, quantity: number): Promise<void>;

21+}

22+

23+export interface ReservationRepository {

24+ findByRequestKey(accountId: string, requestKey: string): Promise<Reservation | null>;

25+ insert(reservation: Reservation): Promise<void>;

26+}

27+

28+export interface ReservationDependencies {

29+ ids: { next(): string };

30+ inventory: InventoryGateway;

31+ reservations: ReservationRepository;

32+}

33+

34+export class InsufficientStockError extends Error {

35+ constructor(

36+ readonly available: number,

37+ readonly requested: number,

38+ ) {

39+ super(`Requested ${requested} units, but only ${available} are available`);

40+ this.name = "InsufficientStockError";

41+ }

42+}

Reference solution

The findings below are ordered by priority.

Findings

1. Concurrent reservations can oversell the same stock

Location: src/inventory-reservation-service.ts:17-30 and src/sql-inventory-reservation-repositories.ts:15-27

Availability is read with one statement and decremented later with an unconditional update. Two requests can both observe enough stock and then both subtract, allowing available_quantity to become negative.

Perform a conditional decrement or lock the inventory row inside the same database transaction as the reservation. The database operation must ensure the requested quantity is still available at mutation time.

2. A reservation for exactly the available quantity is rejected

Location: src/inventory-reservation-service.ts:22-24

The <= comparison rejects when available equals request.quantity. The contract explicitly allows consuming the final units, so an in-stock order is incorrectly reported as unavailable.

Reject only when available stock is less than the requested quantity, while retaining the atomic protection needed for concurrent requests.

3. A failed reservation insert leaves the stock decrement committed

Location: src/inventory-reservation-service.ts:26-42

The inventory decrement completes before reservations.insert, with no shared transaction or compensation. A database error or uniqueness conflict during insertion consumes stock without creating a reservation.

Commit the conditional stock mutation and reservation row in one transaction. Any insert failure must roll back the stock change before the operation is reported as failed.

4. A completed request key decrements stock again before replaying its result

Location: src/inventory-reservation-service.ts:12-15,17-33

The lookup finds the prior reservation, but the service still checks and decrements inventory before returning it. A normal client retry therefore consumes stock again even though it receives the original reservation.

Return the stored successful result before any inventory mutation. A replay must have no additional stock or reservation side effects.

5. The idempotency lookup and claim are not atomic

Location: src/inventory-reservation-service.ts:12-15,26-41

Concurrent requests with the same account and request key can both observe no existing row, both decrement stock, and both attempt insertion. A uniqueness constraint may reject one insert, but it acts too late to provide a single atomic claim or prevent the earlier decrement.

Claim the account-scoped request key in the same transaction as the conditional stock mutation. A concurrent duplicate should wait for or replay the winning reservation without performing its own decrement.

6. The in-memory tests cannot exercise the transaction guarantees

Location: src/inventory-reservation-service.test.ts:6-49

The fake executes every operation synchronously and sequentially against arrays and one number. The only test is a happy path, so it cannot expose interleaved availability checks, concurrent duplicate keys, insert rollback, or the exact-stock boundary.

Keep fast unit coverage, but add database-backed tests that coordinate concurrent requests and force insertion failure, plus focused cases for exact stock and sequential idempotent replay.

Reasonable non-findings

Looking up request keys by both accountId and requestKey uses the required idempotency scope.
Parameter placeholders keep user-supplied identifiers out of the SQL text; dynamic SQL injection is not the issue here.
Returning zero when an inventory row is absent is compatible with treating a missing SKU as unavailable.
Positive integer quantity validation occurs before this service by contract, so its absence from this patch is not a finding.