Merge branch 'fix/backup-rotation-and-deletion' into release/v1.39.3

# Conflicts:
#	docs/api/openapi.yaml
#	src/lib/jobs/apple-health-import-worker.ts

src/lib/openapi/error-codes.ts

@@ -69,6 +69,8 @@ export const ERROR_CODE_CATALOGUE: Readonly<Record<string, readonly string[]>> =
       "auth.token.invalid",
     ],
     backup: [
+      "backup.foreign_reference",
+      "backup.key.missing",
       "backup.payload.undecryptable",
       "backup.restore.active",
       "backup.section.missing",
@@ -185,7 +187,7 @@ export const ERROR_CODE_CATALOGUE: Readonly<Record<string, readonly string[]>> =
       "illness.episode.parent-not-found",
       "illness.insights.invalid",
     ],
-    import: ["import.write_failed"],
+    import: ["import.apple_health.busy", "import.write_failed"],
     ingest: ["ingest.rate_limited"],
     insights: [
       "insights.generate.budgetExceeded",

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

@@ -86,15 +86,16 @@ const restoreFailure = z
   .object({
     code: z.string().meta({
       description:
-        "Stable reason: `backup_not_found`, `backup_changed`, `backup.payload.undecryptable`, `schema_invalid`, `incompatible_schema_version`, `owner_mismatch`, `owner_not_found`, `backup.section.missing`, `document_ciphertext_missing`, `time_budget`, `transaction_failed`, `interrupted`, `not_started`, `enqueue_failed`, `failed_after_commit`, `unexpected`. Every code but `failed_after_commit` means the account was not changed.",
+        "Stable reason: `backup_not_found`, `backup_changed`, `backup.payload.undecryptable`, `schema_invalid`, `incompatible_schema_version`, `owner_mismatch`, `owner_not_found`, `backup.section.missing`, `document_ciphertext_missing`, `backup.key.missing`, `backup.foreign_reference`, `time_budget`, `transaction_failed`, `interrupted`, `not_started`, `enqueue_failed`, `failed_after_commit`, `unexpected`. Every code but `failed_after_commit` means the account was not changed.",
     }),
     message: z.string(),
     sections: z.array(z.string()).optional(),
+    keyIds: z.array(z.string()).optional(),
   })
   .meta({
     id: "AdminBackupRestoreFailure",
     description:
-      "Why the restore did not happen, in a sentence an operator can act on. `sections` names the missing sections for `backup.section.missing`.",
+      "Why the restore did not happen, in a sentence an operator can act on. `sections` names the missing sections for `backup.section.missing`; `keyIds` names the encryption key ids the file needs and this server cannot open it with, for `backup.key.missing`.",
   });
 
 const restoreJob = z

src/lib/openapi/routes/import.ts

@@ -324,6 +324,11 @@ export const importPaths: NonNullable<ZodOpenApiObject["paths"]> = {
           content: { "application/json": { schema: errorEnvelope } },
         },
         ...stdResponses,
+        "409": {
+          description:
+            "An import for this account is already queued or running, and these bytes are not the ones it carries (the same bytes resolve to that job as a 202). `meta.errorCode` is `import.apple_health.busy` and `meta.jobId` names the running job; poll it, then upload again. The upload was discarded.",
+          content: { "application/json": { schema: errorEnvelope } },
+        },
         "422": {
           description:
             "The multipart body could not be streamed to disk — no `file` part, a malformed boundary, or the size cap tripped mid-stream. The message names the failure.",
@@ -335,7 +340,7 @@ export const importPaths: NonNullable<ZodOpenApiObject["paths"]> = {
         },
         "503": {
           description:
-            "No background worker is bound to this process, so the job cannot be queued. The upload was staged and is discarded; retry once a worker is running.",
+            "No background worker is bound to this process, or the queue did not accept the job, so nothing will run it. The staged upload is discarded (and a created job is marked failed); retry once a worker is running.",
           content: { "application/json": { schema: errorEnvelope } },
         },
       },