fix(catalog): stop an admin edit reverting a reservation

[bgard68]

The bug

Every widget write went through one UpdateAsync that set every column from the caller's in-memory object — quantity_reserved included. Three handlers use the load-change-save shape, so each wrote back the stock it had read moments earlier:

admin loads widget            reserved 0
customer checks out           reserved 3
admin saves a name change     reserved written back as 0

The order still exists and still expects those goods, but the stock is on sale again. That is an oversell — the precise outcome the guarded reservation exists to prevent — reached with no attacker, by a manager fixing a typo during a busy minute, and silently. It defeated the invariant the rest of the inventory work depends on.

The fix

The write path is split by intent, so each caller touches only what it owns:

Method	Writes
UpdateDetailsAsync	name, description, image, price, listed
AdjustStockAsync	a signed delta to on-hand
ArchiveAsync	retirement

AdjustStockAsync does its arithmetic and both guards inside the statement, returning the resulting availability:

update widgets
   set quantity_on_hand = quantity_on_hand + @Delta, updated_at = @Now
 where id = @Id and archived_at is null
   and quantity_on_hand + @Delta >= 0
   and quantity_on_hand + @Delta >= quantity_reserved
returning quantity_on_hand - quantity_reserved

That also fixes a second lost update in the same shape: two concurrent restocks each computed a new total from a stale row, so one vanished. As deltas applied by the database, both land.

Two details worth flagging

The handler keeps its own checks in front of the write. They're advisory — the statement enforces — but they name the reason accurately: a restock that would go negative is a different mistake from one that would strand a reservation. Collapsing them into one message was a regression, and the existing tests caught it.

The in-memory fake copies fields onto the stored row rather than replacing the object. Swapping it wholesale reproduces the defect in miniature and would have let these tests pass over a broken repository.

Also here

ClockSkew set to 30 seconds. The default 5 minutes quietly turned a 15-minute access token into a 20-minute one.

Tests

Six integration tests against real PostgreSQL: an edit during a checkout keeps the reservation, an adjustment counts stock reserved in the gap, two adjustments both land, stock cannot go below reserved or below zero, and an archived widget refuses one.

• 489 backend, 234 frontend — all passing locally
• Build clean under -warnaserror; dotnet format clean

---

Generated by Claude Code