Merge branch 'fix/backup-chunked-storage' into release/v1.39.2

src/lib/openapi/routes/admin-backups.ts

@@ -139,7 +139,17 @@ const restoreJob = z
  */
 const undecryptableResponse = {
   description:
-    "The stored copy could not be opened: either the key that wrote it is no longer in `ENCRYPTION_KEYS` (a rotation that dropped the legacy entry too early), or the stored bytes are not the ones that were written (a stored piece missing, moved, altered, taken from another copy, or the copy cut short). Every piece is checked before any of the copy is read. `meta.errorCode` = `backup.payload.undecryptable`. Nothing was changed.",
+    "The stored copy could not be opened: either the key that wrote it is no longer in `ENCRYPTION_KEYS` (a rotation that dropped the legacy entry too early), or the stored bytes are not the ones that were written (a stored piece missing, moved, altered, taken from another copy, or the copy cut short), or the row holds both a single value and pieces, which only an older release writing to it after an upgrade produces. Every piece is checked before any of the copy is read. `meta.errorCode` = `backup.payload.undecryptable`. Nothing was changed.",
+  content: { "application/json": { schema: errorEnvelope } },
+};
+
+/**
+ * A copy replaced by a newer one (the weekly backup) while it was being
+ * opened or read. Not damage: the reader starts again on the new copy.
+ */
+const replacedResponse = {
+  description:
+    "The stored copy was replaced by a newer one while it was being read. `meta.errorCode` = `backup_changed`. Nothing was changed; start again to use the new copy.",
   content: { "application/json": { schema: errorEnvelope } },
 };
 
@@ -181,6 +191,7 @@ export const adminBackupPaths: NonNullable<ZodOpenApiObject["paths"]> = {
         },
         "403": adminOnlyResponse,
         "404": notFoundResponse,
+        "409": replacedResponse,
         "422": undecryptableResponse,
         "500": {
           description:
@@ -230,7 +241,7 @@ export const adminBackupPaths: NonNullable<ZodOpenApiObject["paths"]> = {
         "404": notFoundResponse,
         "409": {
           description:
-            "A restore of the same account is already queued or running (`meta.errorCode` = `backup.restore.active`, `meta.jobId` names it), or a request under the same `Idempotency-Key` is still in flight. Nothing was changed.",
+            "A restore of the same account is already queued or running (`meta.errorCode` = `backup.restore.active`, `meta.jobId` names it), the stored copy was replaced by a newer one while it was being checked (`meta.errorCode` = `backup_changed`), or a request under the same `Idempotency-Key` is still in flight. Nothing was changed.",
           content: { "application/json": { schema: errorEnvelope } },
         },
         "413": {