fix: validate image order and alt text updates

docs/API.md

@@ -207,3 +207,14 @@ 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.
+
+Image update payloads are strict:
+- `PATCH /api/v1/admin/images/:id/order` requires exactly `sortOrder`, an integer
+  from 0 through 2147483647 (the stored PostgreSQL integer range).
+- `PATCH /api/v1/admin/images/:id/alt-text` requires exactly `altText`, either
+  trimmed text up to 1,000 characters or explicit `null`. An empty string clears
+  the text; omission no longer implicitly clears it.
+
+Malformed, missing, mistyped, oversized, or extra fields return
+`400 VALIDATION_ERROR` without a persistence write. The service also enforces
+these constraints for non-HTTP callers. Existing ownership and CSRF checks apply.

docs/IMAGES.md

@@ -129,3 +129,11 @@ 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.
+
+## Image update validation
+
+Alt-text edits use the same trimmed 1,000-character limit as image creation.
+Explicit empty text or null may clear it; missing fields are invalid. The editor
+shows the limit, prevents typing past it, and flags oversized pre-existing drafts
+until corrected. Legacy absolute sort-order updates require a non-negative
+PostgreSQL integer; ordinary Move controls continue using the atomic move API.

docs/IMPLEMENTATION-STATUS.md

@@ -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 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.
+Verified locally: `npm test` passes 174 tests with no failures (24 domain, 81 application, and 69 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
 
@@ -177,14 +177,21 @@ Verified locally: `npm test` passes 171 tests with no failures (24 domain, 80 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.
 
-### Latest Vertical Slice: Atomic Image Reordering
+### 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.
+### Latest Vertical Slice: Image Update Validation
+
+- Legacy order updates require a non-negative PostgreSQL integer; alt-text updates require trimmed text up to 1,000 characters or explicit null. Missing/extra/mistyped fields are rejected before persistence.
+- Domain validation protects non-HTTP service callers as well. Authentication, CSRF and seller ownership remain unchanged.
+- The alt-text editor shows its limit, trims saved drafts, prevents oversized input and gives associated accessible feedback for oversized pre-existing text.
+- Validation: 174 API tests, 26 isolated integration tests, 11 web tests, production web build, Storybook build, and 32 Storybook suites / 128 tests. No migration required.
+
+Next bounded slice: server-derived upload dimensions. `docs/IMAGES.md` identifies that upload dimensions are still supplied by the client. Decode image metadata behind an injected image-inspection interface, enforce dimension limits on actual bytes, and test forged dimensions and malformed images through upload validation.
 
 ## Next Milestone