feat: reorder inventory images atomically

docs/API.md

@@ -197,3 +197,13 @@ Seller contact removal uses the same explicit-empty-string convention:
 whitespace-only strings clear the contact. Omitted contact fields retain their
 saved values. `null` is not a settings input. Public listing/product detail DTOs
 return `null` for empty or absent contacts, so no contact link is rendered.
+
+`POST /api/v1/admin/images/:id/move` accepts exactly `{ "direction": "up" }`
+or `{ "direction": "down" }`. Authentication and session CSRF validation are
+required; ownership comes from the authenticated Seller. The server selects the
+adjacent image within the same physical Inventory Item and commits all resulting
+positions atomically. At the first/last position the corresponding move is a
+successful no-op. Missing/unowned images return `404 IMAGE_NOT_FOUND`; invalid
+bodies return `400 VALIDATION_ERROR`. The response uses the existing admin image
+DTO. The legacy absolute `/order` endpoint remains available, but UI moves use
+this new operation exclusively.

docs/IMAGES.md

@@ -119,3 +119,13 @@ retain the last loaded gallery but disable mutations until an explicit reload
 succeeds. Failed initial loads show a reload action instead of an empty manager.
 Reload restores keyboard focus to the manager or the retry control. Pending
 operations block conflicting writes and uploads, including drag-and-drop.
+
+## Atomic adjacent moves
+
+Move up/down uses one server operation. The repository locks the owning Inventory
+Item and its images, selects current order by `sortOrder`, `createdAt`, then `id`,
+and uses the domain move rule to choose the new order. An actual move assigns
+contiguous zero-based positions, resolving tied legacy/upload positions, within
+one PostgreSQL transaction. Any failure rolls back all changes. Concurrent moves
+within one item serialize; primary selection and image metadata are unchanged.
+Boundary moves are no-ops. No database migration is required.

docs/IMPLEMENTATION-STATUS.md

@@ -1,6 +1,6 @@
 # Implementation Status
 
-Last updated: 2026-09-10
+Last updated: 2026-09-11
 
 ## Resume Here
 
@@ -120,7 +120,7 @@ docker context use orbstack
 | HTTP | Product and inventory creation, validation, authentication/recovery, CSRF, rate limiting, and session management |
 | Integration | PostgreSQL catalog/session/audit/password recovery persistence and Redis-shared login throttling |
 
-Verified locally: `npm test` passes 167 tests with no failures (23 domain, 79 application, and 65 HTTP); worker tests, web tests, web build, Storybook build, Storybook interaction/accessibility checks, integration tests, and authenticated E2E workflows also pass when their required local services and credentials are available.
+Verified locally: `npm test` passes 171 tests with no failures (24 domain, 80 application, and 67 HTTP); worker tests, web tests, web build, Storybook build, Storybook interaction/accessibility checks, integration tests, and authenticated E2E workflows also pass when their required local services and credentials are available.
 
 ### Public Seller Description
 
@@ -169,7 +169,7 @@ Verified locally: `npm test` passes 167 tests with no failures (23 domain, 79 ap
 - Storybook covers populated/empty/loading/error states, load retries, create/delete recovery, invalid JSON, pending disabled states, mobile retry and dark-theme recovery.
 - Validation: 167 API tests, 11 web tests, production web build, Storybook build, and 32 Storybook suites / 113 tests. Frontend-only change; API and persistence unchanged.
 
-### Latest Vertical Slice: Image Manager Error Recovery
+### Image Manager Error Recovery
 
 - Loaded images and alt-text drafts survive action failures and refreshes. Initial-load errors offer Reload; refresh errors retain the gallery with writes disabled until reload succeeds.
 - Every action reconciles metadata even on failure, exposing partial multi-upload/reorder success without replaying mutations. Pending actions block overlapping writes and file drops.
@@ -177,7 +177,14 @@ Verified locally: `npm test` passes 167 tests with no failures (23 domain, 79 ap
 - Dark-theme coverage also fixed destructive-button contrast by separating its solid background token from error-text color.
 - Validation: 167 API tests, 11 web tests, production web build, Storybook build, and 32 Storybook suites / 124 tests. No API or persistence changes.
 
-Next bounded slice: atomic image reordering. Move up/down currently sends two separate order updates; failure between them can leave a partial reorder. Add a seller-scoped API operation that updates both positions transactionally, connect the controls to it, and verify rollback and ownership with integration tests.
+### Latest Vertical Slice: Atomic Image Reordering
+
+- Move up/down now calls a single authenticated, CSRF-protected `POST /api/v1/admin/images/:id/move` operation. The server derives the adjacent image from current persisted order.
+- The repository locks the owning Inventory Item and its images, applies the domain move rule, and commits contiguous positions in one transaction. Ties are resolved deterministically; boundary moves are no-ops; primary state is preserved.
+- Tests cover invalid requests, ownership, CSRF, missing images, boundary moves, tied positions, rollback after the first write, concurrent moves, and UI success/failure recovery.
+- Validation: 171 API tests, 26 isolated PostgreSQL/Redis integration tests, 11 web tests, production web build, Storybook build, and 32 Storybook suites / 126 tests. No migration required.
+
+Next bounded slice: image mutation payload validation. The legacy absolute-order and alt-text endpoints currently pass unchecked request fields into the service. Add strict schemas and domain validation for these updates, provide clear UI validation feedback, and test malformed/oversized requests without changing valid image workflows.
 
 ## Next Milestone