gencow 0.1.252 → 0.1.253

package/core/index.js

@@ -4,6 +4,78 @@ function defineApi(api) {
 }
 
 // ../core/src/http-route.ts
+var discardedResponseSymbol = /* @__PURE__ */ Symbol.for("@gencow/core/http-route/discarded-response/v1");
+var discardedResponseCauseSymbol = /* @__PURE__ */ Symbol.for("@gencow/core/http-route/discarded-response-cause/v1");
+var outputValidationFailureSymbol = /* @__PURE__ */ Symbol.for("@gencow/core/http-route/output-validation-failure/v1");
+function getHttpRouteDiscardedResponse(value) {
+  if (!value || typeof value !== "object" && typeof value !== "function") return void 0;
+  try {
+    const descriptor = Object.getOwnPropertyDescriptor(value, discardedResponseSymbol);
+    const response = descriptor && "value" in descriptor ? descriptor.value : void 0;
+    return response instanceof Response ? response : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function getHttpRouteDiscardedResponseCause(value) {
+  if (!value || typeof value !== "object" && typeof value !== "function") return void 0;
+  try {
+    const descriptor = Object.getOwnPropertyDescriptor(value, discardedResponseCauseSymbol);
+    return descriptor && "value" in descriptor ? descriptor.value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function isHttpRouteOutputValidationFailure(value) {
+  if (!value || typeof value !== "object" && typeof value !== "function") return false;
+  try {
+    const descriptor = Object.getOwnPropertyDescriptor(value, outputValidationFailureSymbol);
+    return !!descriptor && "value" in descriptor && descriptor.value === true;
+  } catch {
+    return false;
+  }
+}
+function addDiscardedResponse(value, response) {
+  try {
+    Object.defineProperty(value, discardedResponseSymbol, {
+      configurable: false,
+      enumerable: false,
+      value: response,
+      writable: false
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function routeResultResponse(value) {
+  if (value instanceof Response) return value;
+  return value?.body instanceof Response ? value.body : void 0;
+}
+function markDroppedResponse(value, response) {
+  if (!response || routeResultResponse(value) === response) return value;
+  if (value && (typeof value === "object" || typeof value === "function")) {
+    addDiscardedResponse(value, response);
+  }
+  return value;
+}
+function markDiscardedResponseError(error, response) {
+  if (error && (typeof error === "object" || typeof error === "function")) {
+    if (addDiscardedResponse(error, response)) return error;
+  }
+  const wrapped = error instanceof HttpRouteOutputValidationError ? new HttpRouteOutputValidationError(error.message) : new Error("httpRoute output validation failed", { cause: error });
+  addDiscardedResponse(wrapped, response);
+  try {
+    Object.defineProperty(wrapped, discardedResponseCauseSymbol, {
+      configurable: false,
+      enumerable: false,
+      value: error,
+      writable: false
+    });
+  } catch {
+  }
+  return wrapped;
+}
 function hasStandardSchema(schema) {
   return !!schema && typeof schema === "object" && "~standard" in schema && !!schema["~standard"] && typeof schema["~standard"].validate === "function";
 }
@@ -65,10 +137,28 @@ async function buildInputFromRequest(method, req) {
 }
 async function maybeValidateRouteOutput(result, outputSchema) {
   if (!outputSchema) return result;
-  const isSuccessStatus = result?.status === void 0 || result.status < 400;
-  if (!isSuccessStatus) return result;
-  const validatedBody = await validateOutput(outputSchema, result?.body);
-  return { status: result?.status, headers: result?.headers, body: validatedBody };
+  const source = routeResultResponse(result);
+  try {
+    const isSuccessStatus = result instanceof Response ? result.status < 400 : result?.status === void 0 || result.status < 400;
+    if (!isSuccessStatus) return result;
+    const response = result instanceof Response ? result : void 0;
+    const validatedBody = await validateOutput(
+      outputSchema,
+      response ? response.body : result?.body
+    );
+    if (response) {
+      if (validatedBody === response.body) return result;
+      return markDroppedResponse(
+        { status: response.status, headers: response.headers, body: validatedBody },
+        source
+      );
+    }
+    const normalized = { status: result?.status, headers: result?.headers, body: validatedBody };
+    return markDroppedResponse(normalized, source);
+  } catch (error) {
+    if (source) throw markDiscardedResponseError(error, source);
+    throw error;
+  }
 }
 function composeRouteMiddlewares(middlewares, handler, inputSchema, outputSchema, inputValidationIndex, outputValidationIndex) {
   return async (initialContext, initialInput, request) => {
@@ -210,15 +300,7 @@ var HttpRouteBuilderImpl = class _HttpRouteBuilderImpl {
     const inputSchema = this.inputSchema;
     const outputSchema = this.outputSchema;
     const inputErrorMapper = this.inputErrorMapper;
-    const runRoute = composeRouteMiddlewares(
-      this.middlewares,
-      handler,
-      inputSchema,
-      outputSchema,
-      this.inputValidationIndex,
-      this.outputValidationIndex
-    );
-    const wrappedHandler = async (ctx, req) => {
+    const invokeRoute = async (ctx, req) => {
       let normalizedInput;
       try {
         normalizedInput = inputSchema ? await buildInputFromRequest(method, req) : void 0;
@@ -231,14 +313,37 @@ var HttpRouteBuilderImpl = class _HttpRouteBuilderImpl {
       }
       let result;
       try {
-        result = await runRoute(ctx, normalizedInput, req);
+        result = await composeRouteMiddlewares(
+          this.middlewares,
+          handler,
+          inputSchema,
+          outputSchema,
+          this.inputValidationIndex,
+          this.outputValidationIndex
+        )(ctx, normalizedInput, req);
       } catch (err) {
         if (err instanceof HttpRouteInputValidationError) {
           if (inputErrorMapper) return await inputErrorMapper(err.issues);
           return { status: 400, body: { error: err.message } };
         }
         if (err instanceof HttpRouteOutputValidationError) {
-          return { status: 500, body: { error: `Output validation failed: ${err.message}` } };
+          const discardedResponse = getHttpRouteDiscardedResponse(err);
+          const failure = {
+            status: 500,
+            body: {
+              error: discardedResponse ? "Output validation failed" : `Output validation failed: ${err.message}`
+            }
+          };
+          if (discardedResponse) {
+            addDiscardedResponse(failure, discardedResponse);
+            Object.defineProperty(failure, outputValidationFailureSymbol, {
+              configurable: false,
+              enumerable: false,
+              value: true,
+              writable: false
+            });
+          }
+          return failure;
         }
         throw err;
       }
@@ -248,7 +353,7 @@ var HttpRouteBuilderImpl = class _HttpRouteBuilderImpl {
       method,
       path: routePath,
       isPublic,
-      handler: wrappedHandler,
+      handler: invokeRoute,
       middlewares: [...this.middlewares],
       inputValidationIndex: this.inputValidationIndex,
       outputValidationIndex: this.outputValidationIndex,
@@ -1668,7 +1773,9 @@ async function validateWithSchema(schema, value, options) {
     }
     throw new GencowValidationError("Validation failed");
   }
-  throw new Error("procedure.query / procedure.mutation / procedure.internal only supports Standard Schema v1 validators");
+  throw new Error(
+    "procedure.query / procedure.mutation / procedure.internal only supports Standard Schema v1 validators"
+  );
 }
 function composeMiddlewares(middlewares, handler, inputSchema, outputSchema, inputValidationIndex, outputValidationIndex) {
   return async (initialContext, initialInput) => {
@@ -1798,14 +1905,14 @@ var GencowProcedureBuilderImpl = class _GencowProcedureBuilderImpl {
     if (!this.procedureName) {
       throw new Error("Procedure name is required. Call .name(...) before .handler(...)");
     }
-    const run = composeMiddlewares(
+    const run = (context, input) => composeMiddlewares(
       this.middlewares,
       handler,
       this.inputSchema,
       this.outputSchema,
       this.inputValidationIndex,
       this.outputValidationIndex
-    );
+    )(context, input);
     return {
       kind: this.kind,
       name: this.procedureName,
@@ -6148,6 +6255,8 @@ export {
   eqRlsContextColumn,
   filterTenantRuntimeEnvVars,
   formatBytes,
+  getHttpRouteDiscardedResponse,
+  getHttpRouteDiscardedResponseCause,
   getJobAdmissionStatus,
   getMinuteBucketStart,
   getMsUntilNextMinute,
@@ -6167,6 +6276,7 @@ export {
   hasMapSessionToContext,
   inferTableNameFromColumn,
   isCronJobsBuilder,
+  isHttpRouteOutputValidationFailure,
   isJobAdmissionError,
   isJobAdmissionKillSwitchActive,
   isReservedTenantRuntimeEnvKey,

package/docs/packaging.md

@@ -40,11 +40,15 @@ CLI workspace source tree.
 Build from a complete repository checkout; workspace dependencies are required:
 
 ```sh
-pnpm --dir packages/cli run build
+pnpm --dir packages/cli run build:with-deps
 ```
 
-The build script runs the prerequisite workspace builds declared in the CLI
-package scripts, then produces the package runtime artifacts. After the build,
+`build:with-deps` builds the CLI's workspace dependencies (`@gencow/server`,
+`@gencow/internal`, `@gencow/core`, and the rest of the CLI closure) once each in
+topological order, then produces the package runtime artifacts. It selects packages
+with the path selector `{.}...` rather than the name `gencow...`, because the root
+package is also named `gencow` and a name selector would build the whole workspace. The plain `build`
+script does not build dependencies; it expects their `dist/` output to exist. After the build,
 from `packages/cli`, create a local tarball without running package lifecycle
 hooks, inspect its file list, and run the package integrity check:
 

package/docs/troubleshooting.md

@@ -40,7 +40,7 @@ other work before handling arguments.
   selected client target. Use the command reference for documented output options;
   do not use subcommand `--help` as a syntax probe.
 - If the CLI package build reports a missing or incompatible artifact, rebuild
-  from the repository root with `pnpm --dir packages/cli run build`, then rerun
+  from the repository root with `pnpm --dir packages/cli run build:with-deps`, then rerun
   `node scripts/pre-publish-check.mjs` from `packages/cli`.
 - For dependency resolution problems, run `pnpm install` at the workspace root
   and use the package manager declared by the project lockfile.

package/lib/app-command.mjs

@@ -88,6 +88,32 @@ function formatPendingReasonLines(appRow) {
   };
 }
 
+// A legacy-owner wake failure keeps the incumbent serving state and carries platform-authored guidance
+// (retry condition, exact command). Render it instead of the generic "no deployment" text, which is wrong
+// for an app that already has a legacy deployment.
+function formatLegacyRedeployDetails(appRow) {
+  const pending = formatPendingReasonLines(appRow);
+  if (!pending || appRow?.runtimeRecoveryReason !== "legacy_runtime_preparation_required") return null;
+  const correlationId = appRow?.runtimeRecoveryCorrelationId;
+  return [
+    "  Recovery: the app runtime is a legacy build the Platform cannot re-verify; the incumbent serving state was preserved.",
+    "  Data/Deployment: unchanged; no data or serving state was changed.",
+    `  Code: ${appRow?.runtimeRecoveryErrorCode || "RUNTIME_CONVERGENCE_LEGACY_REDEPLOY_REQUIRED"}`,
+    pending.reason,
+    ...(correlationId ? [`  Correlation: ${correlationId}`] : []),
+    pending.retryable,
+    pending.next,
+  ].join("\n");
+}
+
+// Platform marks an idle legacy-owner app (no wake failure recorded yet) with disposition.legacyRuntimeOwner.
+const LEGACY_OWNER_REDEPLOY_DETAILS = [
+  "  Recovery: the app runtime is a legacy build the Platform cannot re-verify; the incumbent serving state was preserved.",
+  "  Data/Deployment: unchanged; no data or serving state was changed.",
+  "  Retryable: no; deploy a new revision to move the app to the supported runtime.",
+  "  Next command: gencow deploy --prod",
+].join("\n");
+
 export function formatRecoveryDispositionDetails(appRow) {
   // The accepted delete receipt remains the lifecycle authority while the app
   // is being removed. Do not replace it with unrelated recovery or support
@@ -95,7 +121,11 @@ export function formatRecoveryDispositionDetails(appRow) {
   if (appRow?.status === "deleting") return "";
   const disposition = appRow?.recoveryDisposition;
   if (disposition?.kind === "deploy_required") {
-    return "  Recovery: no deployment is available. Run `gencow deploy` from this project.\n  Retryable: no";
+    return (
+      formatLegacyRedeployDetails(appRow) ??
+      (disposition.legacyRuntimeOwner === true ? LEGACY_OWNER_REDEPLOY_DETAILS : null) ??
+      "  Recovery: no deployment is available. Run `gencow deploy` from this project.\n  Retryable: no"
+    );
   }
   if (disposition?.kind === "owner_memory_action_required") {
     return "  Recovery: inspect logs and memory usage, then deploy a fix or explicitly Resume.\n  Retryable: no automatic retry";

package/lib/backup-command.mjs

@@ -3,6 +3,7 @@ import { resolve } from "path";
 import { BOLD, CYAN, DIM, GREEN, RED, RESET, YELLOW, error, info, log, success } from "./output.mjs";
 import { platformFetch, requireCreds, rpcMutation, rpcQuery } from "./platform-client.mjs";
 import { readProjectMetadata } from "./project-context.mjs";
+import { formatRestoreFailure } from "./backup-restore-diagnostic.mjs";
 
 export function resolveBackupAppId(restArgs, gencowJson = null) {
   let appId = null;
@@ -85,6 +86,92 @@ export function parseBackupListOptions(restArgs) {
   return options;
 }
 
+// Public codes this renderer knows. Legacy BACKUP_CAPABILITY_NOT_READY rows are handled separately.
+const BACKUP_TYPED_CODES = new Set([
+  "BACKUP_ACCESS_RECONCILING",
+  "BACKUP_RLS_RESTRICTIVE_POLICY",
+  "BACKUP_RLS_SCOPE_UNAVAILABLE",
+  "BACKUP_CAPABILITY_ATTESTATION_INVALID",
+]);
+
+const BACKUP_PLATFORM_WAIT =
+  "No action is needed from you. Retry only after the backup access check reports ready; do not retry in a loop before then.";
+
+// One entry per preflight reason the platform can store. A reason missing here is dropped from the rendered
+// list, so it cannot reach the terminal under an unexplained code. Stored prose is never printed.
+const BACKUP_REASON_PRESENTATION = {
+  attestation_metadata_invalid: { owner: "platform", nextAction: `Platform must correct the backup reader attestation. ${BACKUP_PLATFORM_WAIT}` },
+  role_attestation_missing: { owner: "platform", nextAction: `Platform must correct the backup reader attestation. ${BACKUP_PLATFORM_WAIT}` },
+  backup_identity_mismatch: { owner: "platform", nextAction: `Platform must correct the backup reader attestation. ${BACKUP_PLATFORM_WAIT}` },
+  role_has_broad_cluster_privilege: { owner: "platform", nextAction: `Platform must correct the backup reader attestation. ${BACKUP_PLATFORM_WAIT}` },
+  rls_bypass_not_approved: { owner: "platform", nextAction: `Platform must correct the backup reader attestation. ${BACKUP_PLATFORM_WAIT}` },
+  relation_select_missing: { owner: "platform", nextAction: `Platform is restoring backup access. ${BACKUP_PLATFORM_WAIT}` },
+  relation_ownership_forbidden: { owner: "platform", nextAction: `Platform is restoring backup access. ${BACKUP_PLATFORM_WAIT}` },
+  sequence_defaults_mutation_forbidden: { owner: "platform", nextAction: `Platform is restoring backup access. ${BACKUP_PLATFORM_WAIT}` },
+  complete_rls_dump_not_proven: { owner: "platform", nextAction: `Platform is restoring backup access. ${BACKUP_PLATFORM_WAIT}` },
+  rls_restrictive_policy_applies: {
+    owner: "app",
+    nextAction:
+      "Add a new migration that limits the restrictive RLS policy so it no longer applies to the Gencow backup reader (do not edit applied migrations), run `gencow deploy` from your app workspace, then retry the backup.",
+  },
+  rls_dump_scope_unbound: { owner: "platform", nextAction: `Platform must bind the backup scope for this app. ${BACKUP_PLATFORM_WAIT}` },
+  rls_scope_changed: {
+    owner: "platform",
+    nextAction:
+      "This is a transient race. A single retry after the current backup attempt finishes is expected to succeed. If it fails again, Platform is restoring access; do not retry in a loop, and cite the Reference below.",
+  },
+};
+
+// Stored shape written by the platform: "CODE[ [reasons=a,b]]: prose". Only the code and reason tokens are read.
+const BACKUP_DIAGNOSIS_PATTERN = /^(BACKUP_[A-Z_]+)(?: \[reasons=([a-z_,]+)\])?: /u;
+
+function parseBackupDiagnosis(backup) {
+  if (backup.status !== "failed" || typeof backup.errorMessage !== "string") return null;
+  const match = BACKUP_DIAGNOSIS_PATTERN.exec(backup.errorMessage);
+  if (!match) return null;
+  const code = match[1];
+  // Legacy rows stored before the typed codes existed keep their original fixed rendering.
+  if (code === "BACKUP_CAPABILITY_NOT_READY") return { code, legacy: true };
+  if (!BACKUP_TYPED_CODES.has(code)) return null;
+  const reasons = [
+    ...new Set(
+      (match[2] ?? "")
+        .split(",")
+        .filter((token) => Object.prototype.hasOwnProperty.call(BACKUP_REASON_PRESENTATION, token)),
+    ),
+  ];
+  return reasons.length > 0 ? { code, reasons } : null;
+}
+
+function renderBackupDiagnosis(diagnosis, backupId) {
+  if (diagnosis.legacy) {
+    return [
+      "    BACKUP_CAPABILITY_NOT_READY: Backup preflight is not ready. The dump did not start; no data or serving state changed. Retry only after Platform confirms complete backup visibility and protected snapshot and authorization readiness for this app. Check the failed backup with `gencow backup list` from its app workspace.",
+    ];
+  }
+  const presentations = diagnosis.reasons.map((reason) => ({ reason, ...BACKUP_REASON_PRESENTATION[reason] }));
+  const appSteps = [...new Set(presentations.filter((p) => p.owner === "app").map((p) => p.nextAction))];
+  const platformReasons = presentations.filter((p) => p.owner === "platform").map((p) => p.reason);
+  const platformSteps = [...new Set(presentations.filter((p) => p.owner === "platform").map((p) => p.nextAction))];
+  const owners = [appSteps.length > 0 ? "App" : null, platformSteps.length > 0 ? "Platform" : null].filter(Boolean);
+  const lines = [
+    `    ${diagnosis.code}`,
+    `    Stage: preflight | State: unchanged (no data or serving state changed) | Owner: ${owners.join(" and ")}`,
+    `    Reasons: ${diagnosis.reasons.join(", ")}`,
+  ];
+  if (appSteps.length > 0 && platformSteps.length > 0) {
+    // Mixed refusal: the user acts on the app part only, and the Platform part is named as already in progress.
+    lines.push(`    Next (you): ${appSteps.join(" ")}`);
+    lines.push(
+      `    Platform part: Platform is restoring the Platform-owned reasons (${platformReasons.join(", ")}); no action is needed from you for them. ${platformSteps.join(" ")}`,
+    );
+  } else {
+    lines.push(`    Next: ${[...appSteps, ...platformSteps].join(" ")}`);
+  }
+  lines.push(`    Reference: backup #${backupId}`);
+  return lines;
+}
+
 function renderBackupHelp(logImpl = log, errorImpl = error, subCmd = null) {
   if (subCmd) errorImpl(`Unknown sub-command: ${subCmd}`);
   logImpl(`\n  ${BOLD}Usage:${RESET}`);
@@ -98,6 +185,10 @@ function renderBackupHelp(logImpl = log, errorImpl = error, subCmd = null) {
   logImpl(`    gencow backup download <id>       Download backup file (plan-dependent)\n`);
 }
 
+async function readErrorBody(response) {
+  return (await response.json?.().catch(() => ({}))) ?? {};
+}
+
 export function buildRestoreConfirmPrompt(sourceLabel, { includeStorageRisk = false } = {}) {
   const storageRisk = includeStorageRisk
     ? `\n  ${YELLOW}⚠ 백업 파일 복원은 DB만 교체하며 storage object/blob는 함께 이동하지 않습니다.${RESET}` +
@@ -201,16 +292,11 @@ export function createBackupCommand({
             logImpl(
               `  ${DIM}#${backup.id}${RESET}  ${statusColor}${backup.status.padEnd(10)}${RESET}  ${backup.type.padEnd(11)} ${formatBackupRetentionClass(backup).padEnd(14)} ${formatBackupSize(backup.fileSize).padStart(10)}  ${formatBackupDate(backup.createdAt)}  ${DIM}expires ${formatBackupExpiry(backup.expiresAt)}${RESET}${backup.note ? `  ${DIM}${backup.note}${RESET}` : ""}`,
             );
-            // Recognize the stable producer code, but never print legacy/raw
-            // errorMessage contents (which may contain SQL or credentials).
-            if (
-              backup.status === "failed" &&
-              typeof backup.errorMessage === "string" &&
-              backup.errorMessage.startsWith("BACKUP_CAPABILITY_NOT_READY:")
-            ) {
-              logImpl(
-                "    BACKUP_CAPABILITY_NOT_READY: Backup preflight is not ready. The dump did not start; no data or serving state changed. Retry only after Platform confirms complete backup visibility and protected snapshot and authorization readiness for this app. Check the failed backup with `gencow backup list` from its app workspace.",
-              );
+            // Recognize the stable producer code, but never print raw errorMessage contents
+            // (which may contain SQL or credentials).
+            const diagnosis = parseBackupDiagnosis(backup);
+            if (diagnosis) {
+              for (const line of renderBackupDiagnosis(diagnosis, backup.id)) logImpl(line);
             }
           }
         }
@@ -267,9 +353,7 @@ export function createBackupCommand({
         logImpl(`\n${BOLD}Restoring from backup #${backupId}...${RESET}\n`);
         const response = await rpcMutationImpl(creds, "backup.restore", { appName: appId, backupId });
         if (!response.ok) {
-          errorImpl(
-            `Restore failed: ${(await response.json().catch(() => ({}))).error || response.statusText}`,
-          );
+          errorImpl(formatRestoreFailure(await readErrorBody(response), response.statusText));
           return;
         }
         successImpl("Database restored. App restarted.");
@@ -306,9 +390,7 @@ export function createBackupCommand({
           body: form,
         });
         if (!response.ok) {
-          errorImpl(
-            `Restore failed: ${(await response.json?.().catch(() => ({}))).error || response.statusText}`,
-          );
+          errorImpl(formatRestoreFailure(await readErrorBody(response), response.statusText));
           return;
         }
         successImpl("Database restored from file. App restarted.");

package/lib/backup-restore-diagnostic.mjs

@@ -0,0 +1,185 @@
+// Renders the typed diagnostics of a failed `backup restore` / `backup restore-file` response.
+//
+// The server body is untrusted. Every field is re-validated here, and each one is dropped on its own when it
+// fails, so one bad value never hides the others. The headline prose is owned by this CLI, keyed by the public
+// code, and the server's `error` text is never printed on the typed path. A body without a known code keeps the
+// legacy `Restore failed: <error>` line, so old servers render exactly as before.
+
+const KNOWN_RESTORE_CODES = {
+  BACKUP_RESTORE_ARCHIVE_UNSUPPORTED_OBJECTS: "This backup contains objects Gencow cannot restore safely.",
+  BACKUP_RESTORE_ARCHIVE_UNREADABLE: "This file is not a readable Gencow or PostgreSQL custom-format backup.",
+  BACKUP_RESTORE_EXECUTION_FAILED: "The restore did not finish. The app database may be partially restored.",
+};
+
+const CODE_PATTERN = /^BACKUP_RESTORE_[A-Z_]{3,80}$/u;
+const STAGE_PATTERN = /^[a-z_]{3,40}$/u;
+const CORRELATION_ID_PATTERN = /^[A-Za-z0-9_-]{8,128}$/u;
+const RETRY_CONDITION_MAX_LENGTH = 300;
+const LEGACY_ERROR_MAX_LENGTH = 2000;
+const NEXT_COMMAND_MAX_LENGTH = 160;
+const UNSUPPORTED_OBJECT_SHOWN = 5;
+// Items past this input cap are never inspected, so they are counted as omitted.
+const UNSUPPORTED_OBJECT_INPUT_MAX = 20;
+const OBJECT_TYPE_PATTERN = /^[A-Za-z][A-Za-z ]{0,40}$/u;
+const OBJECT_NAME_PATTERN = /^[\p{L}\p{N}_ .$-]{1,128}$/u;
+// The only next commands the server sends. Anything else (flags, other subcommands, separators) is dropped and
+// replaced by the code default below, so the server never chooses an arbitrary command for the user.
+const ALLOWED_NEXT_COMMANDS = new Set([
+  "gencow backup list",
+  "gencow backup create",
+  "gencow backup restore <backupId>",
+  "gencow backup restore-file <path>",
+]);
+// Used when a known restore code arrives without a safe next command, so every failure shows a next step.
+const DEFAULT_NEXT_COMMAND_BY_CODE = {
+  BACKUP_RESTORE_ARCHIVE_UNSUPPORTED_OBJECTS: "gencow backup create",
+  BACKUP_RESTORE_ARCHIVE_UNREADABLE: "gencow backup restore-file <path>",
+  BACKUP_RESTORE_EXECUTION_FAILED: "gencow backup list",
+};
+// ANSI CSI, OSC and two-character escapes, then any remaining C0/C1 control character.
+const ANSI_ESCAPE_PATTERN = /\u001b(?:\[[0-?]*[ -/]*[@-~]|\][^\u0007]*(?:\u0007|\u001b\\)|[@-Z\\-_])/gu;
+const LINE_BREAK_PATTERN = /[\r\n\t]/gu;
+// Bidi embedding/override/isolate controls and zero-width characters can reorder or hide text in a terminal.
+const INVISIBLE_FORMAT_PATTERN = /[\u200B-\u200F\u202A-\u202E\u2066-\u2069]/gu;
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f-\u009f]/gu;
+// Secret-shaped text is dropped as a whole field, never shown masked.
+const SECRET_LIKE_PATTERNS = [/[A-Za-z0-9_-]{32,}/u, /\bBearer\s/iu, /\bpostgres(?:ql)?:\/\//iu];
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// Line breaks and tabs become spaces so that word breaks survive; other control and invisible characters go.
+function cleanPlainText(value) {
+  return value
+    .replace(ANSI_ESCAPE_PATTERN, "")
+    .replace(LINE_BREAK_PATTERN, " ")
+    .replace(INVISIBLE_FORMAT_PATTERN, "")
+    .replace(CONTROL_CHARACTER_PATTERN, "")
+    .trim();
+}
+
+// Oversized input is dropped rather than truncated, so a partial typed field is never shown as if complete.
+function cleanText(value, maxLength) {
+  if (typeof value !== "string" || value.length > maxLength) return undefined;
+  const cleaned = cleanPlainText(value);
+  return cleaned.length > 0 ? cleaned : undefined;
+}
+
+// The legacy message is free text with no contract, so it is cut to a bounded prefix and marked, not dropped.
+function cleanLegacyMessage(value) {
+  if (typeof value !== "string") return undefined;
+  const cleaned = cleanPlainText(value);
+  if (cleaned.length === 0) return undefined;
+  return cleaned.length > LEGACY_ERROR_MAX_LENGTH ? `${cleaned.slice(0, LEGACY_ERROR_MAX_LENGTH)}...` : cleaned;
+}
+
+function cleanRetryCondition(value) {
+  const cleaned = cleanText(value, RETRY_CONDITION_MAX_LENGTH);
+  if (cleaned === undefined || SECRET_LIKE_PATTERNS.some((pattern) => pattern.test(cleaned))) return undefined;
+  return cleaned;
+}
+
+function cleanNextCommand(value, safetyBackupId) {
+  // Exact match against the allowlist: the raw value must already be one of the known commands.
+  if (typeof value !== "string" || !ALLOWED_NEXT_COMMANDS.has(value)) return undefined;
+  // The safety-backup id is a validated integer, so the placeholder is filled with it. Nothing else is rewritten.
+  return safetyBackupId === undefined ? value : value.replace("<backupId>", String(safetyBackupId));
+}
+
+function readSafetyBackupId(body) {
+  const candidate = body.safetyBackupId ?? (isPlainObject(body.details) ? body.details.safetyBackupId : undefined);
+  return Number.isSafeInteger(candidate) && candidate > 0 ? candidate : undefined;
+}
+
+// Accepts the flat `unsupportedObjects` objects (restore-file) and the `details` strings (RPC restore).
+function formatUnsupportedObject(item) {
+  if (typeof item === "string") {
+    const text = cleanText(item, 200);
+    const [type, ...rest] = (text ?? "").split(" ");
+    const name = rest.join(" ");
+    return text !== undefined && OBJECT_TYPE_PATTERN.test(type) && OBJECT_NAME_PATTERN.test(name) ? text : undefined;
+  }
+  if (!isPlainObject(item)) return undefined;
+  const type = cleanText(item.type, 41);
+  const schema = cleanText(item.schema, 128);
+  const name = cleanText(item.name, 128);
+  if (!OBJECT_TYPE_PATTERN.test(type ?? "") || !OBJECT_NAME_PATTERN.test(schema ?? "") || !OBJECT_NAME_PATTERN.test(name ?? "")) {
+    return undefined;
+  }
+  return `${type} ${schema}.${name}`;
+}
+
+function readUnsupportedObjects(body) {
+  const raw = Array.isArray(body.unsupportedObjects)
+    ? body.unsupportedObjects
+    : isPlainObject(body.details) && Array.isArray(body.details.unsupportedObjects)
+      ? body.details.unsupportedObjects
+      : [];
+  const valid = raw
+    .slice(0, UNSUPPORTED_OBJECT_INPUT_MAX)
+    .map(formatUnsupportedObject)
+    .filter((entry) => entry !== undefined);
+  return {
+    valid: valid.length,
+    omitted: raw.length - valid.length,
+    shown: valid.slice(0, UNSUPPORTED_OBJECT_SHOWN),
+  };
+}
+
+function stateLine(stateChanged) {
+  if (stateChanged === false) return "unchanged (no data or serving state changed)";
+  if (stateChanged === true) return "changed (data or serving state changed)";
+  // Anything else, including a missing or unrecognized value, is treated as unknown: never as unchanged.
+  return "unknown (the app database may be partially changed; do not assume it is intact)";
+}
+
+function ownerLine(responsibility) {
+  if (responsibility === "user") return "you";
+  if (responsibility === "platform") return "Platform";
+  return undefined;
+}
+
+function formatTypedRestoreFailure(body) {
+  const code = body.code;
+  const stage = typeof body.failedStage === "string" && STAGE_PATTERN.test(body.failedStage) ? body.failedStage : undefined;
+  const correlationId =
+    typeof body.correlationId === "string" && CORRELATION_ID_PATTERN.test(body.correlationId)
+      ? body.correlationId
+      : undefined;
+  const safetyBackupId = readSafetyBackupId(body);
+  const retryCondition = cleanRetryCondition(body.retryPrecondition);
+  const nextCommand = cleanNextCommand(body.nextCommand, safetyBackupId) ?? DEFAULT_NEXT_COMMAND_BY_CODE[code];
+  const owner = ownerLine(body.responsibility);
+  const objects = readUnsupportedObjects(body);
+
+  const lines = [`Restore failed: ${KNOWN_RESTORE_CODES[code]}`, `Code: ${code}`];
+  if (stage) lines.push(`Stage: ${stage}`);
+  lines.push(`State: ${stateLine(body.stateChanged)}`);
+  if (owner) lines.push(`Owner: ${owner}`);
+  lines.push(`Retryable: ${typeof body.retryable === "boolean" ? (body.retryable ? "yes" : "no") : "unknown"}`);
+  if (retryCondition) lines.push(`Retry condition: ${retryCondition}`);
+  if (objects.valid + objects.omitted > 0) {
+    const omittedLabel = objects.omitted > 0 ? `, ${objects.omitted} omitted as unreadable` : "";
+    lines.push(`Unsupported objects (${objects.valid} valid${omittedLabel}):`);
+    for (const entry of objects.shown) lines.push(`  - ${entry}`);
+    const more = objects.valid - objects.shown.length;
+    if (more > 0) lines.push(`  ...and ${more} more (see the backup file)`);
+  }
+  lines.push(`Next command: ${nextCommand}`);
+  if (correlationId) lines.push(`Correlation ID: ${correlationId}`);
+  return lines.join("\n");
+}
+
+/**
+ * Message for a failed restore response. `body` is the parsed JSON error body (or {}), and `statusText` is the
+ * HTTP status text used when the body carries no usable legacy message.
+ */
+export function formatRestoreFailure(body, statusText) {
+  const safeBody = isPlainObject(body) ? body : {};
+  if (typeof safeBody.code === "string" && CODE_PATTERN.test(safeBody.code) && KNOWN_RESTORE_CODES[safeBody.code]) {
+    return formatTypedRestoreFailure(safeBody);
+  }
+  const legacy = cleanLegacyMessage(safeBody.error) ?? cleanText(statusText, 200);
+  return `Restore failed: ${legacy ?? "unknown error"}`;
+}