feat(restore): restore, catalog import and download processes

backupRestore (Restore... on backups_run) and backupRestoreTable (Restore this table
on backups_artifact): inputs for tables, per-table filters, target table, mode
(INSERT_NEW, UPSERT, REPLACE), match key, id strategy (PRESERVE, REMAP_NEW_IDS with
backups_id_map and reference rewriting) and options. Review is a real dry run with
per-table summary lines (inserted, updated, unchanged, skipped, deleted, conflicts,
orphans, schema, sequences, files) and a masked sample diff. Execute takes the
pre-restore backup, writes in manifest order in page transactions behind a
RestoreWriter (core RestoreWriteFlag and resyncKeySequences selected reflectively),
restores files through the content-addressed store with a SHA-256 re-check, and
records backups_restore_run and backups_restore_run_table rows. Safety rails enforced
in the engine.

backupImportCatalog rebuilds backups_run and backups_artifact from the manifests under a
bucket alias and prefix (trigger IMPORTED). backupDownload issues audited presigned
links, ciphertext only.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

.circleci/config.yml

@@ -57,7 +57,7 @@ workflows:
                  branches:
                     ignore: /.*/
                  tags:
-                    only: [/v.*/]
+                    only: [/^v\d+\.\d+\.\d+$/]
 
    publish_hotfix_release:
       jobs:

pom.xml

@@ -72,6 +72,20 @@
          <artifactId>qqq-backend-core</artifactId>
       </dependency>
 
+      <!-- optional: the BackupsHealthIndicator (apps without qqq-middleware-health never load it) -->
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-middleware-health</artifactId>
+         <optional>true</optional>
+      </dependency>
+
+      <!-- optional: ESB events (apps without qqq-esb never load it) -->
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-esb</artifactId>
+         <optional>true</optional>
+      </dependency>
+
       <dependency>
          <groupId>org.junit.jupiter</groupId>
          <artifactId>junit-jupiter</artifactId>

src/main/java/com/kingsrook/qbits/backups/BackupsQBitConfig.java

@@ -19,6 +19,9 @@ package com.kingsrook.qbits.backups;
 
 import java.util.List;
 import java.util.function.Function;
+import java.util.function.Predicate;
+import com.kingsrook.qbits.backups.codec.ArtifactTransform;
+import com.kingsrook.qbits.backups.verify.ScratchTarget;
 import com.kingsrook.qbits.backups.storage.BackupStorage;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitConfig;
@@ -52,6 +55,12 @@ public class BackupsQBitConfig implements QBitConfig
 
    private Function<String, BackupStorage> storageResolver;
 
+   private Integer                          fileReverifyDays  = 30;
+   private Function<String, ArtifactTransform> artifactTransformResolver;
+   private ScratchTarget                    scratchTarget;
+   private Predicate<String>                planOwnerValidator;
+   private String                           esbDestinationName;
+
 
 
    /*******************************************************************************
@@ -315,4 +324,109 @@ public class BackupsQBitConfig implements QBitConfig
       return (this);
    }
 
+   /*******************************************************************************
+    ** Getter for fileReverifyDays: CONTENT verification skips file-store objects
+    ** verified more recently than this.
+    *******************************************************************************/
+   public Integer getFileReverifyDays()
+   {
+      return (fileReverifyDays);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for fileReverifyDays
+    *******************************************************************************/
+   public BackupsQBitConfig withFileReverifyDays(Integer fileReverifyDays)
+   {
+      this.fileReverifyDays = fileReverifyDays;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for artifactTransformResolver (the decrypt hook for verify)
+    *******************************************************************************/
+   public Function<String, ArtifactTransform> getArtifactTransformResolver()
+   {
+      return (artifactTransformResolver);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for artifactTransformResolver: encryption key reference (the name
+    ** of a key in a key provider) to the transform that decrypts what that key wrote.
+    *******************************************************************************/
+   public BackupsQBitConfig withArtifactTransformResolver(Function<String, ArtifactTransform> artifactTransformResolver)
+   {
+      this.artifactTransformResolver = artifactTransformResolver;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for scratchTarget (where TEST_RESTORE restores to; null means MEMORY)
+    *******************************************************************************/
+   public ScratchTarget getScratchTarget()
+   {
+      return (scratchTarget);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for scratchTarget
+    *******************************************************************************/
+   public BackupsQBitConfig withScratchTarget(ScratchTarget scratchTarget)
+   {
+      this.scratchTarget = scratchTarget;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for planOwnerValidator (true when the owner still exists and holds backups.admin)
+    *******************************************************************************/
+   public Predicate<String> getPlanOwnerValidator()
+   {
+      return (planOwnerValidator);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for planOwnerValidator: with none, plan owners are not checked.
+    *******************************************************************************/
+   public BackupsQBitConfig withPlanOwnerValidator(Predicate<String> planOwnerValidator)
+   {
+      this.planOwnerValidator = planOwnerValidator;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for esbDestinationName (ESB events are published here, when set)
+    *******************************************************************************/
+   public String getEsbDestinationName()
+   {
+      return (esbDestinationName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for esbDestinationName
+    *******************************************************************************/
+   public BackupsQBitConfig withEsbDestinationName(String esbDestinationName)
+   {
+      this.esbDestinationName = esbDestinationName;
+      return (this);
+   }
+
 }

src/main/java/com/kingsrook/qbits/backups/BackupsQBitProducer.java

@@ -119,6 +119,14 @@ public class BackupsQBitProducer implements QBitMetaDataProducer<BackupsQBitConf
       qInstance.addQBit(qBit);
       BackupsRuntime.install(qBitConfig);
 
+      ///////////////////////////////////////////////////////////////////////////////
+      // bind the Alerts qbit producer SPI when it is on the class path (optional) //
+      ///////////////////////////////////////////////////////////////////////////////
+      if(com.kingsrook.qbits.backups.alerts.AlertsQBitAlertSink.bindIfPresent())
+      {
+         new com.kingsrook.qbits.backups.alerts.AlertsQBitAlertSink().registerAlertTypes(qInstance);
+      }
+
       com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput output = new com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput();
       for(var possibleValueSource : com.kingsrook.qbits.backups.model.BackupsTables.possibleValueSources())
       {

src/main/java/com/kingsrook/qbits/backups/alerts/AlertsQBitAlertSink.java

@@ -0,0 +1,310 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.alerts;
+
+
+import java.lang.reflect.Method;
+import java.util.Map;
+import java.util.stream.Collectors;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+/*******************************************************************************
+ ** The BackupAlertSink adapter for the Alerts qbit producer SPI (QRun-IO/qqq
+ ** PR #1108, com.kingsrook.qqq.backend.core.alerts: QAlerts, AlertSignal,
+ ** AlertResolution, AlertSeverity, QAlertTypeMetaData; design spec
+ ** docs/specs/2026-10-12-qbit-alerts-design.md).
+ **
+ ** STAND-IN: the SPI is an open core PR and is not in QQQ 4.1.0-RC.4, so this
+ ** adapter is bound REFLECTIVELY and optionally.  It compiles against nothing in
+ ** the SPI; it looks the classes up by name, and every call is guarded:
+ ** <ul>
+ **    <li>no SPI classes on the class path: {@link #bindIfPresent()} binds nothing
+ **    and the sink stays the no-op;</li>
+ **    <li>the SPI is present but the instance has no alerts meta-data (the Alerts
+ **    qbit is not installed): every call is a no-op;</li>
+ **    <li>any reflective or SPI failure is logged once and swallowed, because an
+ **    alerting problem must never fail a backup.</li>
+ ** </ul>
+ ** Replace with a direct binding (QAlerts.raise and friends) when RC.5 ships.
+ **
+ ** Mapping: raise to QAlerts.raise(AlertSignal), resolve to QAlerts.resolve(type,
+ ** dedupKey, note), heartbeat to QAlerts.heartbeat(key).  The SPI has no per-plan
+ ** heartbeat registration (monitors are declared on the alert type), so the
+ ** expected interval and grace are not passed on; the SLA checker raises
+ ** backups.plan.missed itself, independent of any heartbeat (spec 10.4).
+ *******************************************************************************/
+public class AlertsQBitAlertSink implements BackupAlertSink
+{
+   private static final QLogger LOG = QLogger.getLogger(AlertsQBitAlertSink.class);
+
+   /** The package of the Alerts producer SPI in qqq-backend-core. */
+   public static final String DEFAULT_API_PACKAGE = "com.kingsrook.qqq.backend.core.alerts";
+
+   private final String apiPackage;
+
+   private boolean warned = false;
+
+   private Class<?> qAlerts;
+   private Class<?> alertSignal;
+   private Class<?> alertSeverity;
+   private Class<?> instanceMetaData;
+
+
+
+   /*******************************************************************************
+    ** Constructor for the real SPI package.
+    *******************************************************************************/
+   public AlertsQBitAlertSink()
+   {
+      this(DEFAULT_API_PACKAGE);
+   }
+
+
+
+   /*******************************************************************************
+    ** Constructor for another package (a test double of the SPI shape).
+    *******************************************************************************/
+   public AlertsQBitAlertSink(String apiPackage)
+   {
+      this.apiPackage = apiPackage;
+   }
+
+
+
+   /*******************************************************************************
+    ** Whether the SPI classes are on the class path.
+    *******************************************************************************/
+   public static boolean isPresent(String apiPackage)
+   {
+      try
+      {
+         Class.forName(apiPackage + ".QAlerts");
+         Class.forName(apiPackage + ".AlertSignal");
+         return (true);
+      }
+      catch(ClassNotFoundException | LinkageError e)
+      {
+         return (false);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Bind this adapter as the runtime's alert sink when the SPI is present and no
+    ** other sink was bound already.  Returns whether it bound.
+    *******************************************************************************/
+   public static boolean bindIfPresent()
+   {
+      if(!(BackupsRuntime.getAlertSink() instanceof NoOpBackupAlertSink) || !isPresent(DEFAULT_API_PACKAGE))
+      {
+         return (false);
+      }
+      BackupsRuntime.setAlertSink(new AlertsQBitAlertSink());
+      return (true);
+   }
+
+
+
+   /*******************************************************************************
+    ** Declare the backup alert types with the Alerts qbit (QAlertTypeMetaData), when
+    ** the SPI is present.  Returns how many were added.
+    *******************************************************************************/
+   public int registerAlertTypes(QInstance qInstance)
+   {
+      int added = 0;
+      try
+      {
+         Class<?> typeClass = Class.forName(apiPackage + ".QAlertTypeMetaData");
+         load();
+         for(BackupAlerts.AlertType alertType : BackupAlerts.alertTypes())
+         {
+            try
+            {
+               Object type = typeClass.getConstructor().newInstance();
+               typeClass.getMethod("withName", String.class).invoke(type, alertType.name());
+               typeClass.getMethod("withLabel", String.class).invoke(type, alertType.label());
+               typeClass.getMethod("withGroupName", String.class).invoke(type, "Backups");
+               typeClass.getMethod("withHowToFix", String.class).invoke(type, alertType.howToFix());
+               typeClass.getMethod("withDefaultSeverity", alertSeverity).invoke(type, severity(alertType.defaultSeverity()));
+               typeClass.getMethod("addSelfToInstance", QInstance.class).invoke(type, qInstance);
+               added++;
+            }
+            catch(ReflectiveOperationException | RuntimeException e)
+            {
+               warnOnce("Could not declare the alert type " + alertType.name(), e);
+            }
+         }
+      }
+      catch(ReflectiveOperationException | LinkageError e)
+      {
+         warnOnce("The alerts SPI is not available", e);
+      }
+      return (added);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public void raise(String type, String dedupeKey, Severity severity, String title, Map<String, String> detail)
+   {
+      if(!isAlertsQBitInstalled())
+      {
+         return;
+      }
+      try
+      {
+         Object signal = alertSignal.getConstructor(String.class).newInstance(type);
+         alertSignal.getMethod("setDedupKey", String.class).invoke(signal, dedupeKey);
+         alertSignal.getMethod("setSeverity", alertSeverity).invoke(signal, severity(severity));
+         alertSignal.getMethod("setTitle", String.class).invoke(signal, title);
+         if(detail != null && !detail.isEmpty())
+         {
+            alertSignal.getMethod("setSummary", String.class).invoke(signal, detail.entrySet().stream().map(e -> e.getKey() + "=" + e.getValue()).collect(Collectors.joining(", ")));
+            Method withAttribute = alertSignal.getMethod("withAttribute", String.class, String.class);
+            for(Map.Entry<String, String> entry : detail.entrySet())
+            {
+               withAttribute.invoke(signal, entry.getKey(), entry.getValue());
+            }
+         }
+         qAlerts.getMethod("raise", alertSignal).invoke(null, signal);
+      }
+      catch(ReflectiveOperationException | RuntimeException e)
+      {
+         warnOnce("Could not raise an alert", e);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public void resolve(String type, String dedupeKey)
+   {
+      if(!isAlertsQBitInstalled())
+      {
+         return;
+      }
+      try
+      {
+         qAlerts.getMethod("resolve", String.class, String.class, String.class).invoke(null, type, dedupeKey, "Cleared by the Backups qbit");
+      }
+      catch(ReflectiveOperationException | RuntimeException e)
+      {
+         warnOnce("Could not resolve an alert", e);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public void heartbeat(String monitorKey, long expectedEverySeconds, long graceSeconds)
+   {
+      if(!isAlertsQBitInstalled())
+      {
+         return;
+      }
+      try
+      {
+         qAlerts.getMethod("heartbeat", String.class).invoke(null, monitorKey);
+      }
+      catch(ReflectiveOperationException | RuntimeException e)
+      {
+         warnOnce("Could not check in a heartbeat", e);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The SPI classes load, and the instance has alerts meta-data (the Alerts qbit
+    ** is installed).  Checked on every call so the order qbits are produced in
+    ** does not matter.
+    *******************************************************************************/
+   boolean isAlertsQBitInstalled()
+   {
+      try
+      {
+         load();
+         QInstance qInstance = QContext.getQInstance();
+         if(qInstance == null)
+         {
+            return (false);
+         }
+         return (instanceMetaData.getMethod("of", QInstance.class).invoke(null, qInstance) != null);
+      }
+      catch(ReflectiveOperationException | RuntimeException | LinkageError e)
+      {
+         warnOnce("The alerts SPI is not usable", e);
+         return (false);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private synchronized void load() throws ClassNotFoundException
+   {
+      if(qAlerts == null)
+      {
+         qAlerts = Class.forName(apiPackage + ".QAlerts");
+         alertSignal = Class.forName(apiPackage + ".AlertSignal");
+         alertSeverity = Class.forName(apiPackage + ".AlertSeverity");
+         instanceMetaData = Class.forName(apiPackage + ".AlertsInstanceMetaData");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Map our severity to the SPI's enum constant of the same name.
+    *******************************************************************************/
+   @SuppressWarnings({ "unchecked", "rawtypes" })
+   private Object severity(Severity severity)
+   {
+      return (Enum.valueOf((Class<Enum>) alertSeverity, severity.name()));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void warnOnce(String message, Throwable t)
+   {
+      if(!warned)
+      {
+         warned = true;
+         LOG.warn(message + " (the Alerts qbit adapter will keep failing quietly)", t, logPair("apiPackage", apiPackage));
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/backups/alerts/BackupAlerts.java

@@ -0,0 +1,203 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.alerts;
+
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+
+
+/*******************************************************************************
+ ** Every alert the Backups qbit raises (design spec section 10.4), with stable
+ ** dedupe keys, and helpers that send them through the bound BackupAlertSink.
+ **
+ ** A dedupe key is the alert type plus a plan key (or a run key, or a plan key
+ ** and a verify level), so a repeated condition refreshes one alert and a cleared
+ ** condition resolves exactly that alert.  Details carry counts and names only:
+ ** never row values, object keys with secrets in them, or presigned URLs.
+ *******************************************************************************/
+public final class BackupAlerts
+{
+   public static final String PLAN_MISSED          = "backups.plan.missed";
+   public static final String RUN_FAILED           = "backups.run.failed";
+   public static final String RUN_MISSING          = "backups.run.missing_in_storage";
+   public static final String FILES_MISSING        = "backups.files.missing";
+   public static final String VERIFY_FAILED        = "backups.verify.failed";
+   public static final String VERIFY_OVERDUE       = "backups.verify.overdue";
+   public static final String PLAN_OWNER_INVALID   = "backups.plan.owner_invalid";
+   public static final String STORAGE_DEBRIS       = "backups.storage.debris";
+   public static final String RESTORE_COMPLETED    = "backups.restore.completed";
+
+   /** The prefix of the heartbeat monitor key of a plan. */
+   public static final String HEARTBEAT_PREFIX = "backups.plan:";
+
+
+
+   /***************************************************************************
+    ** A declared alert type, for the Alerts qbit's type registry.
+    **
+    ** @param name the alert type name
+    ** @param label a short label
+    ** @param defaultSeverity the severity when a signal does not say
+    ** @param howToFix one sentence for the person looking at the alert
+    ***************************************************************************/
+   public record AlertType(String name, String label, BackupAlertSink.Severity defaultSeverity, String howToFix)
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private BackupAlerts()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** The alert types of the spec table (section 10.4), in table order.
+    *******************************************************************************/
+   public static List<AlertType> alertTypes()
+   {
+      return (List.of(
+         new AlertType(PLAN_MISSED, "Backup did not run", BackupAlertSink.Severity.ERROR,
+            "Open the plan and its latest runs, check the schedule and the scheduler, then run the backup by hand."),
+         new AlertType(RUN_FAILED, "Backup run failed", BackupAlertSink.Severity.WARNING,
+            "Open the failed run for the error, fix the cause, and run the plan again."),
+         new AlertType(RUN_MISSING, "Backup is missing from storage", BackupAlertSink.Severity.CRITICAL,
+            "The catalog says the run succeeded but its manifest is gone from the bucket. Check the bucket, its lifecycle rules and the credentials, then run a new backup."),
+         new AlertType(FILES_MISSING, "Backed up files were missing at the source", BackupAlertSink.Severity.WARNING,
+            "Open the run's file index: records point at files that no longer exist."),
+         new AlertType(VERIFY_FAILED, "Backup verification failed", BackupAlertSink.Severity.ERROR,
+            "Open the verification for the mismatches. Treat the run as unusable and take a new backup."),
+         new AlertType(VERIFY_OVERDUE, "Backup verification is overdue", BackupAlertSink.Severity.WARNING,
+            "Run Verify backup on a recent run of the plan, or set a verify schedule on the plan."),
+         new AlertType(PLAN_OWNER_INVALID, "Backup plan owner is not valid", BackupAlertSink.Severity.WARNING,
+            "Set an owner who exists and holds backups.admin on the plan."),
+         new AlertType(STORAGE_DEBRIS, "Backup storage has debris or orphans", BackupAlertSink.Severity.INFO,
+            "Prune clears debris. Orphan prefixes can be imported into the catalog or deleted."),
+         new AlertType(RESTORE_COMPLETED, "A restore finished", BackupAlertSink.Severity.INFO,
+            "Nothing to fix unless the restore failed. Open the restore run.")));
+   }
+
+
+
+   /*******************************************************************************
+    ** The stable dedupe key for a type and an id (plan key, run key...).
+    *******************************************************************************/
+   public static String key(String type, String id)
+   {
+      return (type + ":" + id);
+   }
+
+
+
+   /*******************************************************************************
+    ** The dedupe key of a verify failure: it includes the level so a pass at a
+    ** higher level clears the lower failures, and a cheap pass never hides a
+    ** content failure.
+    *******************************************************************************/
+   public static String verifyKey(String planKey, String level)
+   {
+      return (VERIFY_FAILED + ":" + planKey + ":" + level);
+   }
+
+
+
+   /*******************************************************************************
+    ** Raise (or refresh) an alert.  Never throws: an alerting problem must not fail
+    ** a backup or a check.
+    *******************************************************************************/
+   public static void raise(String type, String id, BackupAlertSink.Severity severity, String title, String... detailPairs)
+   {
+      try
+      {
+         Map<String, String> detail = new LinkedHashMap<>();
+         for(int i = 0; i + 1 < detailPairs.length; i += 2)
+         {
+            detail.put(detailPairs[i], detailPairs[i + 1]);
+         }
+         BackupsRuntime.getAlertSink().raise(type, key(type, id), severity, title, detail);
+      }
+      catch(RuntimeException e)
+      {
+         // fire and forget
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Raise with an explicit dedupe key.
+    *******************************************************************************/
+   public static void raiseWithKey(String type, String dedupeKey, BackupAlertSink.Severity severity, String title, Map<String, String> detail)
+   {
+      try
+      {
+         BackupsRuntime.getAlertSink().raise(type, dedupeKey, severity, title, detail);
+      }
+      catch(RuntimeException e)
+      {
+         // fire and forget
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Resolve the alert of a type and id.  Never throws.
+    *******************************************************************************/
+   public static void resolve(String type, String id)
+   {
+      resolveKey(type, key(type, id));
+   }
+
+
+
+   /*******************************************************************************
+    ** Resolve an alert by its dedupe key.  Never throws.
+    *******************************************************************************/
+   public static void resolveKey(String type, String dedupeKey)
+   {
+      try
+      {
+         BackupsRuntime.getAlertSink().resolve(type, dedupeKey);
+      }
+      catch(RuntimeException e)
+      {
+         // fire and forget
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** A restore finished: an info alert, so restores are never silent (error when
+    ** it failed).  The Alerts qbit clears it after 7 days; nothing resolves it here.
+    *******************************************************************************/
+   public static void restoreCompleted(String restoreRunKey, String status, String planKey, long rowsRestored)
+   {
+      boolean failed = "FAILED".equals(status);
+      raise(RESTORE_COMPLETED, restoreRunKey, failed ? BackupAlertSink.Severity.ERROR : BackupAlertSink.Severity.INFO,
+         failed ? "A restore failed" : "A restore finished",
+         "restoreRun", restoreRunKey, "status", String.valueOf(status), "plan", String.valueOf(planKey), "rows", String.valueOf(rowsRestored));
+   }
+}

src/main/java/com/kingsrook/qbits/backups/events/BackupEvents.java

@@ -0,0 +1,146 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.events;
+
+
+import java.io.Serializable;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.function.BiConsumer;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+
+
+/*******************************************************************************
+ ** ESB events of the Backups qbit (design spec section 10.4): qqq.backups.run.succeeded,
+ ** qqq.backups.run.failed and qqq.backups.restore.completed.  They are for
+ ** integrations, not alerting, and are FIRE AND FORGET: a failed publish is logged
+ ** at most once and never fails a backup or a restore.
+ **
+ ** Events go out only when BackupsQBitConfig.esbDestinationName is set and the ESB
+ ** (qqq-esb, an optional dependency) is on the class path; otherwise publish() does
+ ** nothing.  A test, or an app with its own bus, can bind a publisher with
+ ** {@link #setPublisher}.
+ *******************************************************************************/
+public final class BackupEvents
+{
+   private static final QLogger LOG = QLogger.getLogger(BackupEvents.class);
+
+   public static final String RUN_SUCCEEDED     = "qqq.backups.run.succeeded";
+   public static final String RUN_FAILED        = "qqq.backups.run.failed";
+   public static final String RESTORE_COMPLETED = "qqq.backups.restore.completed";
+
+   private static volatile BiConsumer<String, Map<String, Serializable>> publisher;
+   private static volatile boolean                                       warned = false;
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private BackupEvents()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Bind a publisher (event type, data), or null to go back to the ESB default.
+    *******************************************************************************/
+   public static void setPublisher(BiConsumer<String, Map<String, Serializable>> newPublisher)
+   {
+      publisher = newPublisher;
+      warned = false;
+   }
+
+
+
+   /*******************************************************************************
+    ** A run finished.  Succeeded and warnings publish run.succeeded; failed, timed
+    ** out and abandoned publish run.failed; cancelled publishes nothing.
+    *******************************************************************************/
+   public static void runFinished(String planKey, String runKey, String status, long rows, long bytesStored)
+   {
+      String type;
+      if("SUCCEEDED".equals(status) || "SUCCEEDED_WITH_WARNINGS".equals(status))
+      {
+         type = RUN_SUCCEEDED;
+      }
+      else if("CANCELLED".equals(status))
+      {
+         return;
+      }
+      else
+      {
+         type = RUN_FAILED;
+      }
+      Map<String, Serializable> data = new LinkedHashMap<>();
+      data.put("plan", planKey);
+      data.put("run", runKey);
+      data.put("status", status);
+      data.put("rows", rows);
+      data.put("bytesStored", bytesStored);
+      publish(type, data);
+   }
+
+
+
+   /*******************************************************************************
+    ** A restore finished (any status).
+    *******************************************************************************/
+   public static void restoreCompleted(String restoreRunKey, String status, long rowsRestored)
+   {
+      Map<String, Serializable> data = new LinkedHashMap<>();
+      data.put("restoreRun", restoreRunKey);
+      data.put("status", status);
+      data.put("rows", rowsRestored);
+      publish(RESTORE_COMPLETED, data);
+   }
+
+
+
+   /*******************************************************************************
+    ** Publish an event.  Never throws.
+    *******************************************************************************/
+   public static void publish(String type, Map<String, Serializable> data)
+   {
+      try
+      {
+         BiConsumer<String, Map<String, Serializable>> bound = publisher;
+         if(bound != null)
+         {
+            bound.accept(type, data);
+            return;
+         }
+
+         String destination = BackupsRuntime.getConfig() == null ? null : BackupsRuntime.getConfig().getEsbDestinationName();
+         if(destination == null)
+         {
+            return;
+         }
+         EsbBackupEventPublisher.publish(destination, type, data);
+      }
+      catch(Exception | LinkageError e)
+      {
+         if(!warned)
+         {
+            warned = true;
+            LOG.warn("A backup event could not be published (events are best effort)", e);
+         }
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/backups/events/EsbBackupEventPublisher.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.events;
+
+
+import java.io.Serializable;
+import java.util.Map;
+import com.kingsrook.qqq.esb.publish.EsbPublishAction;
+import com.kingsrook.qqq.esb.publish.EsbPublishInput;
+
+
+/*******************************************************************************
+ ** Publishes a backup event on the QQQ ESB.  This is the only class that touches
+ ** qqq-esb (an optional dependency); BackupEvents calls it inside a guard that
+ ** swallows a missing class (NoClassDefFoundError), so apps without the ESB never
+ ** notice.
+ *******************************************************************************/
+final class EsbBackupEventPublisher
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private EsbBackupEventPublisher()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Publish one event to a destination.
+    *******************************************************************************/
+   static void publish(String destinationName, String type, Map<String, Serializable> data)
+   {
+      new EsbPublishAction().execute(new EsbPublishInput()
+         .withDestinationName(destinationName)
+         .withType(type)
+         .withSourcePath("/backups")
+         .withData(data));
+   }
+}

src/main/java/com/kingsrook/qbits/backups/health/BackupsHealthIndicator.java

@@ -0,0 +1,120 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.health;
+
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
+import com.kingsrook.qqq.middleware.health.HealthIndicator;
+import com.kingsrook.qqq.middleware.health.model.metadata.HealthCheckResult;
+import com.kingsrook.qqq.middleware.health.model.metadata.HealthStatus;
+
+
+/*******************************************************************************
+ ** The Backups health indicator (design spec section 10.4), for
+ ** qqq-middleware-health (an optional dependency: an app that does not have that
+ ** module never loads this class).  It reports DOWN if any active plan marked
+ ** critical is LATE, FAILING or MISSING_IN_STORAGE, and UP with details otherwise.
+ ** It reads the slaStatus the SLA checker maintains; it never touches storage, so
+ ** a health call is cheap.
+ **
+ ** It is OFF the liveness path by design.  Add it to the indicators of the
+ ** instance's health check (the readiness and monitoring view), and do not point a
+ ** Kubernetes liveness probe at a check that includes it: a backup problem must
+ ** never restart pods.
+ *******************************************************************************/
+public class BackupsHealthIndicator implements HealthIndicator
+{
+   public static final String NAME = "backups";
+
+   private static final Set<String> CRITICAL_STATUSES = Set.of("LATE", "FAILING", "MISSING_IN_STORAGE");
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public String getName()
+   {
+      return (NAME);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public HealthCheckResult check(QInstance qInstance) throws QException
+   {
+      long                started = System.currentTimeMillis();
+      boolean             ownsContext = QContext.getQInstance() == null;
+      if(ownsContext)
+      {
+         QContext.init(qInstance, new QSession());
+      }
+      try
+      {
+         List<QRecord> plans = new BackupCatalog().query(BackupsTables.PLAN, new QQueryFilter(new QFilterCriteria("isActive", QCriteriaOperator.EQUALS, true)));
+
+         List<String> criticalProblems = new ArrayList<>();
+         Map<String, Integer> byStatus = new LinkedHashMap<>();
+         for(QRecord plan : plans)
+         {
+            String status = plan.getValueString("slaStatus") == null ? "UNKNOWN" : plan.getValueString("slaStatus");
+            byStatus.merge(status, 1, Integer::sum);
+            if(Boolean.TRUE.equals(plan.getValueBoolean("critical")) && CRITICAL_STATUSES.contains(status))
+            {
+               criticalProblems.add(plan.getValueString("planKey") + ": " + status);
+            }
+         }
+
+         Map<String, Object> details = new LinkedHashMap<>();
+         details.put("activePlans", plans.size());
+         details.put("plansByStatus", byStatus);
+         if(!criticalProblems.isEmpty())
+         {
+            details.put("criticalPlansWithProblems", criticalProblems);
+         }
+         return (new HealthCheckResult()
+            .withStatus(criticalProblems.isEmpty() ? HealthStatus.UP : HealthStatus.DOWN)
+            .withDurationMs(System.currentTimeMillis() - started)
+            .withDetails(details));
+      }
+      finally
+      {
+         if(ownsContext)
+         {
+            QContext.clear();
+         }
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/backups/metrics/BackupsMetrics.java

@@ -0,0 +1,184 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.metrics;
+
+
+import java.time.Duration;
+import java.time.Instant;
+import java.util.List;
+import com.kingsrook.qbits.backups.BackupsQBitConfig;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** The optional Prometheus text for operators who already run Alertmanager (design
+ ** spec section 10.4), computed from the tables and cached for 60 seconds.  Gauges,
+ ** all labeled {instance_name, plan}:
+ ** <ul>
+ **    <li>qqq_backup_last_success_timestamp_seconds</li>
+ **    <li>qqq_backup_last_run_failed (1 when the latest finished run failed)</li>
+ **    <li>qqq_backup_sla_seconds</li>
+ **    <li>qqq_backup_last_verify_success_timestamp_seconds</li>
+ **    <li>qqq_backup_last_success_bytes</li>
+ ** </ul>
+ ** The rule worth having even alongside the Alerts qbit is
+ ** absent_over_time(qqq_backup_last_success_timestamp_seconds[30m]): the one signal
+ ** that still fires when the whole app, and so the Alerts qbit with it, is down.
+ **
+ ** ENDPOINT STUB: this class renders the text.  Serving it at GET /metrics/backups
+ ** (when BackupsQBitConfig.withPrometheusEndpoint(true)) is a route in
+ ** qqq-middleware-javalin, which this qbit does not depend on; the app's Javalin
+ ** route provider calls {@link #renderCached()}.  {@link #isEnabled()} says whether
+ ** the config asks for the endpoint.
+ *******************************************************************************/
+public final class BackupsMetrics
+{
+   public static final String ENDPOINT_PATH = "/metrics/backups";
+
+   private static final Duration CACHE = Duration.ofSeconds(60);
+
+   private static String  cachedText;
+   private static Instant cachedAt;
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private BackupsMetrics()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Whether the config asks for the endpoint.
+    *******************************************************************************/
+   public static boolean isEnabled()
+   {
+      BackupsQBitConfig config = BackupsRuntime.getConfig();
+      return (config != null && Boolean.TRUE.equals(config.getPrometheusEndpoint()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Forget the cached text (tests).
+    *******************************************************************************/
+   public static synchronized void resetCache()
+   {
+      cachedText = null;
+      cachedAt = null;
+   }
+
+
+
+   /*******************************************************************************
+    ** The text, from the cache when it is under 60 seconds old.
+    *******************************************************************************/
+   public static synchronized String renderCached() throws QException
+   {
+      Instant now = BackupsRuntime.getClock().instant();
+      if(cachedText == null || cachedAt == null || cachedAt.plus(CACHE).isBefore(now))
+      {
+         cachedText = render();
+         cachedAt = now;
+      }
+      return (cachedText);
+   }
+
+
+
+   /*******************************************************************************
+    ** Render the text format now.
+    *******************************************************************************/
+   public static String render() throws QException
+   {
+      BackupCatalog     catalog  = new BackupCatalog();
+      BackupsQBitConfig config   = BackupsRuntime.getConfig();
+      String            instance = config != null && config.getInstanceName() != null ? config.getInstanceName() : "qqq";
+
+      StringBuilder lastSuccess = header("qqq_backup_last_success_timestamp_seconds", "Unix time of the last successful backup run");
+      StringBuilder lastFailed  = header("qqq_backup_last_run_failed", "1 when the latest finished run of the plan failed");
+      StringBuilder sla         = header("qqq_backup_sla_seconds", "Maximum age of the last successful run before the plan is late");
+      StringBuilder lastVerify  = header("qqq_backup_last_verify_success_timestamp_seconds", "Unix time of the last passed content or test-restore verification");
+      StringBuilder lastBytes   = header("qqq_backup_last_success_bytes", "Bytes stored by the last successful run");
+
+      List<QRecord> plans = catalog.query(BackupsTables.PLAN, new QQueryFilter(new QFilterCriteria("isActive", QCriteriaOperator.EQUALS, true)));
+      for(QRecord plan : plans)
+      {
+         String labels = "{instance_name=\"" + escape(instance) + "\",plan=\"" + escape(plan.getValueString("planKey")) + "\"}";
+
+         if(plan.getValueInstant("lastSuccessDate") != null)
+         {
+            lastSuccess.append("qqq_backup_last_success_timestamp_seconds").append(labels).append(' ').append(plan.getValueInstant("lastSuccessDate").getEpochSecond()).append('\n');
+         }
+         List<QRecord> runs = catalog.where(BackupsTables.RUN, "backupPlanId", plan.getValueInteger("id"));
+         QRecord latest = runs.stream().filter(r -> List.of("SUCCEEDED", "SUCCEEDED_WITH_WARNINGS", "FAILED", "TIMED_OUT", "ABANDONED").contains(r.getValueString("status"))).findFirst().orElse(null);
+         if(latest != null)
+         {
+            boolean failed = List.of("FAILED", "TIMED_OUT", "ABANDONED").contains(latest.getValueString("status"));
+            lastFailed.append("qqq_backup_last_run_failed").append(labels).append(' ').append(failed ? 1 : 0).append('\n');
+         }
+         Integer slaHours = plan.getValueInteger("slaHours");
+         if(slaHours != null)
+         {
+            sla.append("qqq_backup_sla_seconds").append(labels).append(' ').append(slaHours * 3600L).append('\n');
+         }
+         if(plan.getValueInstant("lastVerifiedDate") != null)
+         {
+            lastVerify.append("qqq_backup_last_verify_success_timestamp_seconds").append(labels).append(' ').append(plan.getValueInstant("lastVerifiedDate").getEpochSecond()).append('\n');
+         }
+         if(plan.getValueInteger("lastSuccessRunId") != null)
+         {
+            QRecord run = catalog.get(BackupsTables.RUN, plan.getValueInteger("lastSuccessRunId")).orElse(null);
+            if(run != null && run.getValueLong("bytesStored") != null)
+            {
+               lastBytes.append("qqq_backup_last_success_bytes").append(labels).append(' ').append(run.getValueLong("bytesStored")).append('\n');
+            }
+         }
+      }
+      return (lastSuccess.toString() + lastFailed + sla + lastVerify + lastBytes);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static StringBuilder header(String name, String help)
+   {
+      return (new StringBuilder("# HELP ").append(name).append(' ').append(help).append('\n').append("# TYPE ").append(name).append(" gauge\n"));
+   }
+
+
+
+   /*******************************************************************************
+    ** Escape a label value for the text format.
+    *******************************************************************************/
+   static String escape(String value)
+   {
+      return (value == null ? "" : value.replace("\\", "\\\\").replace("\"", "\\\"").replace("\n", "\\n"));
+   }
+}

src/main/java/com/kingsrook/qbits/backups/model/BackupsTables.java

@@ -319,6 +319,7 @@ public final class BackupsTables
          .withField(roInt("scheduledJobId"))
          .withField(new QFieldMetaData("slaHours", QFieldType.INTEGER).withDefaultValue(26))
          .withField(new QFieldMetaData("verifySlaDays", QFieldType.INTEGER).withDefaultValue(8))
+         .withField(new QFieldMetaData("verifyFileSamplePercent", QFieldType.INTEGER).withDefaultValue(100))
          .withField(new QFieldMetaData("verifyCronExpression", QFieldType.STRING).withMaxLength(100))
          .withField(enumField("verifyLevel", "verify_level", "CONTENT"))
          .withField(new QFieldMetaData("retainDaily", QFieldType.INTEGER).withDefaultValue(7))

src/main/java/com/kingsrook/qbits/backups/processes/BackupsProcesses.java

@@ -73,6 +73,9 @@ public final class BackupsProcesses
       List<QProcessMetaData> processes = new ArrayList<>();
       processes.add(permission(etl(RUN_PLAN, "Run backup now", BackupsTables.PLAN, RunPlanTransform.class, RunPlanLoad.class,
          "This is a preview of what the backup will include. Nothing is written until you continue."), BackupsPermissions.RUN));
+      processes.addAll(VerifyProcesses.processes());
+      processes.addAll(RestoreProcesses.processes());
+      processes.addAll(CatalogProcesses.processes());
       return (processes);
    }
 

src/main/java/com/kingsrook/qbits/backups/processes/CatalogProcesses.java

@@ -0,0 +1,443 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.processes;
+
+
+import java.io.Serializable;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.permissions.BackupsPermissions;
+import com.kingsrook.qbits.backups.restore.CatalogImporter;
+import com.kingsrook.qbits.backups.restore.RestoreSummaries;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qbits.backups.storage.BackupStorage;
+import com.kingsrook.qqq.backend.core.actions.audits.AuditAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLine;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLineInterface;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.Status;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QComponentType;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendComponentMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractExtractStep;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractLoadStep;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractTransformStep;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.ExtractViaQueryStep;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.ProcessSummaryProviderInterface;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.StreamedETLWithFrontendProcess;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+/*******************************************************************************
+ ** The catalog and download processes (spec 9.6 and 9.7):  Import backups from
+ ** storage (a table action on backups_run) and Download (a record action on a run
+ ** or an artifact).  Standard streamed ETL, Review and Result summary lines.
+ *******************************************************************************/
+public final class CatalogProcesses
+{
+   public static final String IMPORT_CATALOG     = "backupImportCatalog";
+   public static final String DOWNLOAD           = "backupDownload";
+   public static final String DOWNLOAD_ARTIFACT  = "backupDownloadArtifact";
+
+   public static final Duration LINK_TTL = Duration.ofMinutes(15);
+
+   private static final QLogger LOG = QLogger.getLogger(CatalogProcesses.class);
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private CatalogProcesses()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** The processes defined here.
+    *******************************************************************************/
+   public static List<QProcessMetaData> processes()
+   {
+      List<QProcessMetaData> processes = new ArrayList<>();
+
+      QProcessMetaData importProcess = definition(IMPORT_CATALOG, "Import backups from storage", BackupsTables.RUN, ImportExtract.class, ImportTransform.class, ImportLoad.class,
+         "These are the backups found in storage that are not in the catalog yet. Nothing is written until you continue.");
+      importProcess.withStep(0, new QFrontendStepMetaData()
+         .withName("input")
+         .withLabel("Where are the backups?")
+         .withComponent(new QFrontendComponentMetaData().withType(QComponentType.EDIT_FORM))
+         .withFormField(new QFieldMetaData("bucketAlias", QFieldType.STRING).withLabel("Backup bucket alias").withIsRequired(true))
+         .withFormField(new QFieldMetaData("prefix", QFieldType.STRING).withLabel("Folder (prefix)").withDefaultValue("qqq-backups/")));
+      importProcess.setMinInputRecords(0);
+      processes.add(BackupsProcesses.permission(importProcess, BackupsPermissions.ADMIN));
+
+      processes.add(BackupsProcesses.permission(definition(DOWNLOAD, "Download", BackupsTables.RUN, ExtractViaQueryStep.class, DownloadTransform.class, DownloadLoad.class,
+         "These are the files you will get download links for. Nothing is changed."), BackupsPermissions.RESTORE));
+      processes.add(BackupsProcesses.permission(definition(DOWNLOAD_ARTIFACT, "Download", BackupsTables.ARTIFACT, ExtractViaQueryStep.class, DownloadTransform.class, DownloadLoad.class,
+         "These are the files you will get download links for. Nothing is changed."), BackupsPermissions.RESTORE));
+      return (processes);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static QProcessMetaData definition(String name, String label, String table, Class<? extends AbstractExtractStep> extract,
+                                              Class<? extends AbstractTransformStep> transform, Class<? extends AbstractLoadStep> load, String preview)
+   {
+      Map<String, Serializable> values = new HashMap<>();
+      values.put(StreamedETLWithFrontendProcess.FIELD_SOURCE_TABLE, table);
+      values.put(StreamedETLWithFrontendProcess.FIELD_DESTINATION_TABLE, table);
+      values.put(StreamedETLWithFrontendProcess.FIELD_SUPPORTS_FULL_VALIDATION, true);
+      values.put(StreamedETLWithFrontendProcess.FIELD_DO_FULL_VALIDATION, true);
+      values.put(StreamedETLWithFrontendProcess.FIELD_TRANSACTION_LEVEL, StreamedETLWithFrontendProcess.TRANSACTION_LEVEL_AUTO_COMMIT);
+      values.put(StreamedETLWithFrontendProcess.FIELD_PREVIEW_MESSAGE, preview);
+      QProcessMetaData process = StreamedETLWithFrontendProcess.defineProcessMetaData(extract, transform, load, values);
+      process.setName(name);
+      process.setLabel(label);
+      process.setTableName(table);
+      process.setPermissionRules(BackupsTables.permissionRules());
+      return (process);
+   }
+
+
+
+   /*******************************************************************************
+    ** Lists the manifests under the bucket alias and prefix; one record per manifest.
+    *******************************************************************************/
+   public static class ImportExtract extends AbstractExtractStep
+   {
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         String alias = input.getValueString("bucketAlias");
+         if(alias == null || alias.isBlank())
+         {
+            throw (new QUserFacingException("Choose the backup bucket alias to import from."));
+         }
+         BackupStorage storage = BackupsRuntime.storageFor(alias);
+         for(String key : new CatalogImporter().findManifestKeys(storage, input.getValueString("prefix")))
+         {
+            getRecordPipe().addRecord(new QRecord().withTableName(BackupsTables.RUN).withValue("manifestKey", key).withValue("storageBucketAlias", alias));
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Review: what each manifest is (new, already in the catalog, or damaged).
+    *******************************************************************************/
+   public static class ImportTransform extends AbstractTransformStep implements ProcessSummaryProviderInterface
+   {
+      private final ProcessSummaryLine found    = RestoreSummaries.line(Status.INFO, 0, "backup was found in storage", "backups were found in storage", "backup was found in storage", "backups were found in storage");
+      private final ProcessSummaryLine newRuns  = RestoreSummaries.line(Status.OK, 0, "backup will be added to the catalog", "backups will be added to the catalog", "backup was added to the catalog", "backups were added to the catalog");
+      private final ProcessSummaryLine existing = RestoreSummaries.line(Status.INFO, 0, "backup is already in the catalog (skipped)", "backups are already in the catalog (skipped)", "backup was already in the catalog", "backups were already in the catalog");
+      private final ProcessSummaryLine invalid  = RestoreSummaries.line(Status.ERROR, 0, "backup has a manifest or checksum problem and will be skipped", "backups have a manifest or checksum problem and will be skipped",
+         "backup had a manifest or checksum problem and was skipped", "backups had a manifest or checksum problem and were skipped");
+      private final ArrayList<String>  problems = new ArrayList<>();
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         for(QRecord record : input.getRecords())
+         {
+            BackupStorage storage = BackupsRuntime.storageFor(record.getValueString("storageBucketAlias"));
+            CatalogImporter.Inspection inspection = new CatalogImporter().inspect(storage, record.getValueString("manifestKey"));
+            found.incrementCount();
+            switch(inspection.status())
+            {
+               case CatalogImporter.Inspection.NEW ->
+               {
+                  newRuns.incrementCount();
+                  output.getRecords().add(record);
+               }
+               case CatalogImporter.Inspection.EXISTS -> existing.incrementCount();
+               default ->
+               {
+                  invalid.incrementCount();
+                  for(String problem : inspection.problems())
+                  {
+                     problems.add(inspection.manifestKey() + ": " + problem);
+                  }
+               }
+            }
+         }
+      }
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public ArrayList<ProcessSummaryLineInterface> getProcessSummary(RunBackendStepOutput output, boolean isForResultScreen)
+      {
+         ArrayList<ProcessSummaryLineInterface> lines = new ArrayList<>();
+         found.addSelfToListIfAnyCount(lines);
+         newRuns.addSelfToListIfAnyCount(lines);
+         existing.addSelfToListIfAnyCount(lines);
+         invalid.setBulletsOfText(problems);
+         invalid.addSelfToListIfAnyCount(lines);
+         return (lines);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Execute: create the run and artifact rows from each new manifest.
+    *******************************************************************************/
+   public static class ImportLoad extends AbstractLoadStep implements ProcessSummaryProviderInterface
+   {
+      private final ProcessSummaryLine imported = RestoreSummaries.line(Status.OK, 0, "backup will be added to the catalog", "backups will be added to the catalog", "backup was added to the catalog", "backups were added to the catalog");
+      private final ProcessSummaryLine skipped  = RestoreSummaries.line(Status.WARNING, 0, "backup was not added", "backups were not added", "backup was not added", "backups were not added");
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         CatalogImporter importer = new CatalogImporter();
+         for(QRecord record : input.getRecords())
+         {
+            String        alias   = record.getValueString("storageBucketAlias");
+            BackupStorage storage = BackupsRuntime.storageFor(alias);
+            CatalogImporter.Inspection inspection = importer.inspect(storage, record.getValueString("manifestKey"));
+            if(CatalogImporter.Inspection.NEW.equals(inspection.status()))
+            {
+               imported.incrementCountAndAddPrimaryKey(importer.importRun(alias, storage, inspection));
+            }
+            else
+            {
+               skipped.incrementCount();
+            }
+            output.getRecords().add(record);
+         }
+      }
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public ArrayList<ProcessSummaryLineInterface> getProcessSummary(RunBackendStepOutput output, boolean isForResultScreen)
+      {
+         ArrayList<ProcessSummaryLineInterface> lines = new ArrayList<>();
+         imported.addSelfToListIfAnyCount(lines);
+         skipped.addSelfToListIfAnyCount(lines);
+         return (lines);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** One object to link to.
+    *******************************************************************************/
+   record DownloadItem(String auditTable, Integer auditId, BackupStorage storage, String key, String downloadName, boolean encrypted, long size)
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** The objects the selected records ask for: for a run, all of its artifacts; for
+    ** an artifact, itself plus the manifest and checksums of its run.
+    *******************************************************************************/
+   static List<DownloadItem> items(List<QRecord> records) throws QException
+   {
+      BackupCatalog catalog = new BackupCatalog();
+      Map<String, DownloadItem> items = new LinkedHashMap<>();
+      for(QRecord record : records)
+      {
+         boolean   isArtifact = BackupsTables.ARTIFACT.equals(record.getTableName()) || record.getValue("artifactType") != null;
+         Integer   runId      = isArtifact ? record.getValueInteger("backupRunId") : record.getValueInteger("id");
+         QRecord   run        = catalog.get(BackupsTables.RUN, runId).orElseThrow(() -> new QUserFacingException("The backup run was not found."));
+         String    table      = isArtifact ? BackupsTables.ARTIFACT : BackupsTables.RUN;
+         BackupStorage storage = BackupsRuntime.storageFor(run.getValueString("storageBucketAlias"));
+
+         List<QRecord> artifacts = new ArrayList<>();
+         if(isArtifact)
+         {
+            artifacts.add(record);
+            for(QRecord other : catalog.where(BackupsTables.ARTIFACT, "backupRunId", runId))
+            {
+               if("MANIFEST".equals(other.getValueString("artifactType")) || "CHECKSUMS".equals(other.getValueString("artifactType")))
+               {
+                  artifacts.add(other);
+               }
+            }
+         }
+         else
+         {
+            artifacts.addAll(catalog.where(BackupsTables.ARTIFACT, "backupRunId", runId));
+         }
+
+         for(QRecord artifact : artifacts)
+         {
+            if(!"COMPLETE".equals(artifact.getValueString("status")))
+            {
+               continue;
+            }
+            String key = run.getValueString("runPrefix") + artifact.getValueString("objectKey");
+            String name = run.getValueString("runKey") + "-" + artifact.getValueString("objectKey").replace('/', '-');
+            items.putIfAbsent(key, new DownloadItem(table, isArtifact && artifact == record ? artifact.getValueInteger("id") : runId, storage, key, name,
+               Boolean.TRUE.equals(artifact.getValueBoolean("encrypted")), artifact.getValueLong("bytesStored") == null ? 0 : artifact.getValueLong("bytesStored")));
+         }
+      }
+      return (new ArrayList<>(items.values()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Review: what will be linked.
+    *******************************************************************************/
+   public static class DownloadTransform extends AbstractTransformStep implements ProcessSummaryProviderInterface
+   {
+      private final ProcessSummaryLine objects   = RestoreSummaries.line(Status.OK, 0, "file will get a download link", "files will get download links", "file got a download link", "files got download links");
+      private final ProcessSummaryLine encrypted = RestoreSummaries.line(Status.INFO, 0, "file is encrypted: you get the ciphertext only, and decrypt it with the command line tool",
+         "files are encrypted: you get the ciphertext only, and decrypt them with the command line tool", "file is encrypted (ciphertext only)", "files are encrypted (ciphertext only)");
+      private long bytes;
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         for(DownloadItem item : items(input.getRecords()))
+         {
+            objects.incrementCount();
+            bytes += item.size();
+            if(item.encrypted())
+            {
+               encrypted.incrementCount();
+            }
+         }
+         output.getRecords().addAll(input.getRecords());
+      }
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public ArrayList<ProcessSummaryLineInterface> getProcessSummary(RunBackendStepOutput output, boolean isForResultScreen)
+      {
+         ArrayList<ProcessSummaryLineInterface> lines = new ArrayList<>();
+         objects.addSelfToListIfAnyCount(lines);
+         encrypted.addSelfToListIfAnyCount(lines);
+         if(objects.getCount() != null && objects.getCount() > 0)
+         {
+            lines.add(RestoreSummaries.message(Status.INFO, "The links last " + LINK_TTL.toMinutes() + " minutes and the download is about " + bytes + " bytes. Each link is recorded in the audit."));
+         }
+         return (lines);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Execute: issue the presigned links (ciphertext only), each one audited.
+    *******************************************************************************/
+   public static class DownloadLoad extends AbstractLoadStep implements ProcessSummaryProviderInterface
+   {
+      private final ProcessSummaryLine issued = RestoreSummaries.line(Status.OK, 0, "download link was issued", "download links were issued", "download link was issued", "download links were issued");
+      private final ArrayList<String>  links  = new ArrayList<>();
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         String user = QContext.getQSession() == null || QContext.getQSession().getUser() == null ? "system" : QContext.getQSession().getUser().getIdReference();
+         for(DownloadItem item : items(input.getRecords()))
+         {
+            Instant expires = BackupsRuntime.getClock().instant().plus(LINK_TTL);
+            String  url     = item.storage().presignGet(item.key(), LINK_TTL, item.downloadName());
+            links.add(item.downloadName() + (item.encrypted() ? " (encrypted)" : "") + ": " + url);
+            issued.incrementCount();
+            LOG.info("Issued a backup download link", logPair("object", item.key()), logPair("user", user), logPair("expires", expires));
+            try
+            {
+               AuditAction.execute(item.auditTable(), item.auditId(), Map.of(), "Download link issued for " + item.key() + " to " + user + ", expires " + expires);
+            }
+            catch(RuntimeException e)
+            {
+               LOG.warn("Could not audit a download link", e, logPair("object", item.key()));
+            }
+         }
+         output.getRecords().addAll(input.getRecords());
+      }
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public ArrayList<ProcessSummaryLineInterface> getProcessSummary(RunBackendStepOutput output, boolean isForResultScreen)
+      {
+         ArrayList<ProcessSummaryLineInterface> lines = new ArrayList<>();
+         issued.setBulletsOfText(links);
+         issued.addSelfToListIfAnyCount(lines);
+         if(issued.getCount() != null && issued.getCount() > 0)
+         {
+            lines.add(RestoreSummaries.message(Status.INFO, "The links expire in " + LINK_TTL.toMinutes() + " minutes. Encrypted files download as ciphertext: use the command line tool to decrypt them."));
+         }
+         return (lines);
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/backups/processes/RestoreProcesses.java

@@ -0,0 +1,269 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.processes;
+
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.permissions.BackupsPermissions;
+import com.kingsrook.qbits.backups.restore.RestoreEngine;
+import com.kingsrook.qbits.backups.restore.RestoreOutcome;
+import com.kingsrook.qbits.backups.restore.RestoreRequest;
+import com.kingsrook.qbits.backups.restore.RestoreSummaries;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLineInterface;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QComponentType;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendComponentMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QFrontendStepMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractLoadStep;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractTransformStep;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.ExtractViaQueryStep;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.ProcessSummaryProviderInterface;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.StreamedETLWithFrontendProcess;
+
+
+/*******************************************************************************
+ ** The restore processes (spec 9.3): Restore... on a backup run, and Restore this
+ ** table on a backup artifact.  Both are the standard streamed ETL.  The first
+ ** screen takes the inputs; Review is a real dry run of the whole restore with the
+ ** per-table summary lines and a masked sample diff; Execute is the restore, and
+ ** Result shows what was done.  Neither is in the nav.
+ *******************************************************************************/
+public final class RestoreProcesses
+{
+   public static final String RESTORE       = "backupRestore";
+   public static final String RESTORE_TABLE = "backupRestoreTable";
+
+   public static final String STEP_INPUT = "input";
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private RestoreProcesses()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** The processes defined here.
+    *******************************************************************************/
+   public static List<QProcessMetaData> processes()
+   {
+      List<QProcessMetaData> processes = new ArrayList<>();
+      processes.add(BackupsProcesses.permission(restore(RESTORE, "Restore...", BackupsTables.RUN), BackupsPermissions.RESTORE));
+      processes.add(BackupsProcesses.permission(restore(RESTORE_TABLE, "Restore this table", BackupsTables.ARTIFACT), BackupsPermissions.RESTORE));
+      return (processes);
+   }
+
+
+
+   /*******************************************************************************
+    ** One restore process, sourced from the table whose records it is run on.
+    *******************************************************************************/
+   private static QProcessMetaData restore(String name, String label, String table)
+   {
+      Map<String, Serializable> values = new HashMap<>();
+      values.put(StreamedETLWithFrontendProcess.FIELD_SOURCE_TABLE, table);
+      values.put(StreamedETLWithFrontendProcess.FIELD_DESTINATION_TABLE, table);
+      values.put(StreamedETLWithFrontendProcess.FIELD_SUPPORTS_FULL_VALIDATION, true);
+      values.put(StreamedETLWithFrontendProcess.FIELD_DO_FULL_VALIDATION, true);
+      values.put(StreamedETLWithFrontendProcess.FIELD_TRANSACTION_LEVEL, StreamedETLWithFrontendProcess.TRANSACTION_LEVEL_AUTO_COMMIT);
+      values.put(StreamedETLWithFrontendProcess.FIELD_PREVIEW_MESSAGE, "This is what the restore will do. Nothing is written until you continue.");
+
+      QProcessMetaData process = StreamedETLWithFrontendProcess.defineProcessMetaData(ExtractViaQueryStep.class, RestoreTransform.class, RestoreLoad.class, values);
+      process.withStep(0, inputStep());
+      process.setName(name);
+      process.setLabel(label);
+      process.setTableName(table);
+      process.setPermissionRules(BackupsTables.permissionRules());
+      return (process);
+   }
+
+
+
+   /*******************************************************************************
+    ** The first screen: what to restore and how.
+    *******************************************************************************/
+   private static QFrontendStepMetaData inputStep()
+   {
+      return (new QFrontendStepMetaData()
+         .withName(STEP_INPUT)
+         .withLabel("Restore options")
+         .withComponent(new QFrontendComponentMetaData().withType(QComponentType.EDIT_FORM))
+         .withFormField(new QFieldMetaData("tables", QFieldType.STRING).withLabel("Tables (blank for every table in the backup)"))
+         .withFormField(new QFieldMetaData("tableFilters", QFieldType.TEXT).withLabel("Only these records (JSON: table name to filter, optional)"))
+         .withFormField(new QFieldMetaData("targetTable", QFieldType.STRING).withLabel("Restore into another table (optional, one table only)"))
+         .withFormField(new QFieldMetaData("mode", QFieldType.STRING).withLabel("Mode").withIsRequired(true).withDefaultValue(RestoreRequest.MODE_INSERT_NEW)
+            .withPossibleValueSourceName(BackupsTables.pvs("restore_mode")))
+         .withFormField(new QFieldMetaData("matchOn", QFieldType.STRING).withLabel("Match records on (PRIMARY_KEY, or a unique key's fields)").withDefaultValue(RestoreRequest.MATCH_PRIMARY_KEY))
+         .withFormField(new QFieldMetaData("idStrategy", QFieldType.STRING).withLabel("Ids").withIsRequired(true).withDefaultValue(RestoreRequest.IDS_PRESERVE)
+            .withPossibleValueSourceName(BackupsTables.pvs("id_strategy")))
+         .withFormField(new QFieldMetaData("suppressAutomations", QFieldType.BOOLEAN).withLabel("Do not trigger automations").withDefaultValue(true))
+         .withFormField(new QFieldMetaData("publishEvents", QFieldType.BOOLEAN).withLabel("Publish change events").withDefaultValue(false))
+         .withFormField(new QFieldMetaData("runCustomizers", QFieldType.BOOLEAN).withLabel("Run table customizers").withDefaultValue(false))
+         .withFormField(new QFieldMetaData("perRecordAudit", QFieldType.BOOLEAN).withLabel("Audit each record (otherwise one summary per table)").withDefaultValue(false))
+         .withFormField(new QFieldMetaData("restoreFiles", QFieldType.BOOLEAN).withLabel("Restore referenced files").withDefaultValue(true))
+         .withFormField(new QFieldMetaData("fileTargetBucketAlias", QFieldType.STRING).withLabel("Restore files to another bucket alias (optional)"))
+         .withFormField(new QFieldMetaData("fileTargetPrefix", QFieldType.STRING).withLabel("Restore files under this prefix (optional)"))
+         .withFormField(new QFieldMetaData("preRestoreBackup", QFieldType.BOOLEAN).withLabel("Back up the target first").withDefaultValue(true))
+         .withFormField(new QFieldMetaData("confirmationText", QFieldType.STRING).withLabel("Type the table name (or REPLACE <n> TABLES) to confirm a REPLACE")));
+   }
+
+
+
+   /*******************************************************************************
+    ** The backup runs the selected records belong to, with the tables chosen for each
+    ** (empty means the tables of the form).  Artifact records choose their own table.
+    *******************************************************************************/
+   static Map<Integer, Set<String>> sources(List<QRecord> records) throws QException
+   {
+      Map<Integer, Set<String>> sources = new LinkedHashMap<>();
+      for(QRecord record : records)
+      {
+         boolean artifact = BackupsTables.ARTIFACT.equals(record.getTableName()) || record.getValue("artifactType") != null;
+         if(artifact)
+         {
+            String table = record.getValueString("tableName");
+            if(table == null)
+            {
+               throw (new QUserFacingException("Only the data of a table can be restored: choose a table data artifact."));
+            }
+            sources.computeIfAbsent(record.getValueInteger("backupRunId"), k -> new LinkedHashSet<>()).add(table);
+         }
+         else
+         {
+            sources.computeIfAbsent(record.getValueInteger("id"), k -> new LinkedHashSet<>());
+         }
+      }
+      return (sources);
+   }
+
+
+
+   /*******************************************************************************
+    ** Review (preview, validate) is the dry run; execute only re-checks the rails.
+    *******************************************************************************/
+   public static class RestoreTransform extends AbstractTransformStep implements ProcessSummaryProviderInterface
+   {
+      private final List<RestoreOutcome> outcomes = new ArrayList<>();
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         boolean execute = StreamedETLWithFrontendProcess.STEP_NAME_EXECUTE.equals(input.getStepName());
+         RestoreEngine engine = new RestoreEngine();
+         for(Map.Entry<Integer, Set<String>> source : sources(input.getRecords()).entrySet())
+         {
+            RestoreRequest request = RestoreRequest.fromInput(input, source.getKey(), new ArrayList<>(source.getValue()));
+            if(execute)
+            {
+               RestoreEngine.Plan plan = engine.plan(request);
+               if(!plan.errors().isEmpty())
+               {
+                  throw (new QUserFacingException(String.join(" ", plan.errors())));
+               }
+            }
+            else
+            {
+               outcomes.add(engine.review(request));
+            }
+         }
+         output.getRecords().addAll(input.getRecords());
+      }
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public ArrayList<ProcessSummaryLineInterface> getProcessSummary(RunBackendStepOutput output, boolean isForResultScreen)
+      {
+         ArrayList<ProcessSummaryLineInterface> lines = new ArrayList<>();
+         for(RestoreOutcome outcome : outcomes)
+         {
+            lines.addAll(RestoreSummaries.lines(outcome, false));
+         }
+         return (lines);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Execute: the restore itself, one backup run at a time.
+    *******************************************************************************/
+   public static class RestoreLoad extends AbstractLoadStep implements ProcessSummaryProviderInterface
+   {
+      private final List<RestoreOutcome> outcomes = new ArrayList<>();
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         RestoreEngine engine = new RestoreEngine();
+         for(Map.Entry<Integer, Set<String>> source : sources(input.getRecords()).entrySet())
+         {
+            RestoreRequest request = RestoreRequest.fromInput(input, source.getKey(), new ArrayList<>(source.getValue()));
+            outcomes.add(engine.execute(request));
+         }
+         output.getRecords().addAll(input.getRecords());
+      }
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public ArrayList<ProcessSummaryLineInterface> getProcessSummary(RunBackendStepOutput output, boolean isForResultScreen)
+      {
+         ArrayList<ProcessSummaryLineInterface> lines = new ArrayList<>();
+         for(RestoreOutcome outcome : outcomes)
+         {
+            lines.addAll(RestoreSummaries.lines(outcome, true));
+         }
+         return (lines);
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/backups/processes/VerifyProcesses.java

@@ -0,0 +1,271 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.processes;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qbits.backups.BackupsQBitConfig;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.permissions.BackupsPermissions;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qbits.backups.sla.SlaChecker;
+import com.kingsrook.qbits.backups.verify.BackupVerifier;
+import com.kingsrook.qbits.backups.verify.VerificationOutcome;
+import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLine;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLineInterface;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.Status;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QBackendStepMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QStepMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.scheduleing.QScheduleMetaData;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractLoadStep;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.AbstractTransformStep;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.ProcessSummaryProviderInterface;
+import static com.kingsrook.qbits.backups.processes.BackupsProcesses.line;
+
+
+/*******************************************************************************
+ ** The verification and SLA processes (design spec section 10):
+ ** <ul>
+ **    <li>backupVerify: the record action "Verify backup" on backups_run, a standard
+ **    streamed ETL.  Review lists what will be checked (nothing is read); the run
+ **    does the STORAGE level and then, if that passes, the CONTENT level.  The input
+ **    value verifyLevel (STORAGE, CONTENT or TEST_RESTORE) picks how far to go;
+ **    CONTENT is the default and TEST_RESTORE is for the API and schedules.</li>
+ **    <li>backupCheckSla: the scheduled SLA check, every slaCheckIntervalSeconds on
+ **    the configured scheduler, independent of the backup trigger.  It is not in the
+ **    nav.</li>
+ ** </ul>
+ *******************************************************************************/
+public final class VerifyProcesses
+{
+   public static final String VERIFY    = "backupVerify";
+   public static final String CHECK_SLA = "backupCheckSla";
+
+   public static final String FIELD_VERIFY_LEVEL = "verifyLevel";
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private VerifyProcesses()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** The processes of this area.
+    *******************************************************************************/
+   public static List<QProcessMetaData> processes()
+   {
+      List<QProcessMetaData> processes = new ArrayList<>();
+      processes.add(BackupsProcesses.permission(BackupsProcesses.etl(VERIFY, "Verify backup", BackupsTables.RUN, VerifyTransform.class, VerifyLoad.class,
+         "This checks that the backup's objects are all in storage, then reads every byte back, decrypts and decodes it, and compares counts and hashes with the manifest. Nothing is changed in the backup."),
+         BackupsPermissions.RUN));
+      processes.add(checkSlaProcess(BackupsRuntime.getConfig()));
+      return (processes);
+   }
+
+
+
+   /*******************************************************************************
+    ** The SLA check process.  With a scheduler configured it is scheduled every
+    ** slaCheckIntervalSeconds.
+    *******************************************************************************/
+   public static QProcessMetaData checkSlaProcess(BackupsQBitConfig config)
+   {
+      QProcessMetaData process = new QProcessMetaData()
+         .withName(CHECK_SLA)
+         .withLabel("Check backup SLAs")
+         .withStepList(List.<QStepMetaData>of(new QBackendStepMetaData().withName("check").withCode(new QCodeReference(CheckSlaStep.class))));
+      process.setPermissionRules(BackupsTables.permissionRules());
+
+      if(config != null && config.getSchedulerName() != null && config.getSlaCheckIntervalSeconds() != null)
+      {
+         process.setSchedule(new QScheduleMetaData()
+            .withSchedulerName(config.getSchedulerName())
+            .withRepeatSeconds(config.getSlaCheckIntervalSeconds())
+            .withInitialDelaySeconds(30)
+            .withDescription("Backup SLA check (independent of the backup trigger)"));
+      }
+      return (BackupsProcesses.permission(process, BackupsPermissions.RUN));
+   }
+
+
+
+   /*******************************************************************************
+    ** The scheduled SLA check.
+    *******************************************************************************/
+   public static class CheckSlaStep implements BackendStep
+   {
+      /*******************************************************************************
+       ** Check every active plan.
+       *******************************************************************************/
+      @Override
+      public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         List<SlaChecker.PlanResult> results = new SlaChecker().checkAll();
+         long attention = results.stream().filter(r -> !SlaChecker.OK.equals(r.status()) && !SlaChecker.UNKNOWN.equals(r.status())).count();
+         output.addValue("plansChecked", results.size());
+         output.addValue("plansNeedingAttention", attention);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Verify backup, review: which runs can be verified and how much will be read.
+    *******************************************************************************/
+   public static class VerifyTransform extends AbstractTransformStep implements ProcessSummaryProviderInterface
+   {
+      private final ProcessSummaryLine runs     = line(Status.OK, "backup will be verified", "backups will be verified", "backup was verified", "backups were verified");
+      private final ProcessSummaryLine objects  = line(Status.INFO, "stored object will be checked", "stored objects will be checked", "stored object was checked", "stored objects were checked");
+      private final ProcessSummaryLine files    = line(Status.INFO, "referenced file will be checked", "referenced files will be checked", "referenced file was checked", "referenced files were checked");
+      private final ProcessSummaryLine noManifest = line(Status.ERROR, "backup has no manifest, so it is not usable and cannot be verified", "backups have no manifest, so they are not usable and cannot be verified",
+         "backup had no manifest", "backups had no manifest");
+      private final ProcessSummaryLine pruned   = line(Status.ERROR, "backup was pruned, so its objects are gone", "backups were pruned, so their objects are gone", "backup was pruned", "backups were pruned");
+      private final BackupCatalog      catalog  = new BackupCatalog();
+
+
+
+      /*******************************************************************************
+       ** Look at each run without reading any backup bytes.
+       *******************************************************************************/
+      @Override
+      public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         for(QRecord run : input.getRecords())
+         {
+            java.io.Serializable id = run.getValue("id");
+            if(run.getValueInstant("prunedDate") != null)
+            {
+               pruned.incrementCountAndAddPrimaryKey(id);
+            }
+            else if(run.getValueString("manifestKey") == null)
+            {
+               noManifest.incrementCountAndAddPrimaryKey(id);
+            }
+            else
+            {
+               runs.incrementCountAndAddPrimaryKey(id);
+               objects.incrementCount(catalog.where(BackupsTables.ARTIFACT, "backupRunId", run.getValueInteger("id")).size());
+               files.incrementCount(run.getValueInteger("filesReferenced") == null ? 0 : run.getValueInteger("filesReferenced"));
+               output.getRecords().add(run);
+            }
+         }
+      }
+
+
+
+      /*******************************************************************************
+       ** Review lines.
+       *******************************************************************************/
+      @Override
+      public ArrayList<ProcessSummaryLineInterface> getProcessSummary(RunBackendStepOutput output, boolean isForResultScreen)
+      {
+         ArrayList<ProcessSummaryLineInterface> lines = new ArrayList<>();
+         runs.addSelfToListIfAnyCount(lines);
+         objects.addSelfToListIfAnyCount(lines);
+         files.addSelfToListIfAnyCount(lines);
+         noManifest.addSelfToListIfAnyCount(lines);
+         pruned.addSelfToListIfAnyCount(lines);
+         return (lines);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Verify backup, execute: the storage level, then the content level.
+    *******************************************************************************/
+   public static class VerifyLoad extends AbstractLoadStep implements ProcessSummaryProviderInterface
+   {
+      private final ProcessSummaryLine passed   = line(Status.OK, "backup will pass verification", "backups passed verification", "backup passed verification", "backups passed verification");
+      private final ProcessSummaryLine warnings = line(Status.WARNING, "backup passed with warnings", "backups passed with warnings", "backup passed with warnings", "backups passed with warnings");
+      private final ProcessSummaryLine failed   = line(Status.ERROR, "backup failed verification", "backups failed verification", "backup failed verification", "backups failed verification");
+      private final ProcessSummaryLine errored  = line(Status.ERROR, "backup could not be verified", "backups could not be verified", "backup could not be verified", "backups could not be verified");
+      private final ProcessSummaryLine rows     = line(Status.INFO, "row was decoded and checked", "rows were decoded and checked", "row was decoded and checked", "rows were decoded and checked");
+      private final ProcessSummaryLine files    = line(Status.INFO, "file was checked", "files were checked", "file was checked", "files were checked");
+
+
+
+      /*******************************************************************************
+       ** Verify each run.
+       *******************************************************************************/
+      @Override
+      public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         String level = input.getValueString(FIELD_VERIFY_LEVEL) == null ? BackupVerifier.CONTENT : input.getValueString(FIELD_VERIFY_LEVEL);
+         String user  = QContext.getQSession() == null || QContext.getQSession().getUser() == null ? "system" : QContext.getQSession().getUser().getIdReference();
+         for(QRecord run : input.getRecords())
+         {
+            List<VerificationOutcome> outcomes = new BackupVerifier().verifyThrough(run.getValueInteger("id"), level, "MANUAL", user);
+            VerificationOutcome       last     = outcomes.get(outcomes.size() - 1);
+            switch(last.status())
+            {
+               case "PASSED" -> passed.incrementCountAndAddPrimaryKey(run.getValue("id"));
+               case "PASSED_WITH_WARNINGS" -> warnings.incrementCountAndAddPrimaryKey(run.getValue("id"));
+               case "ERROR" ->
+               {
+                  errored.incrementCountAndAddPrimaryKey(run.getValue("id"));
+                  errored.setMessageSuffix(last.messages().isEmpty() ? null : ": " + last.messages().get(0));
+               }
+               default ->
+               {
+                  failed.incrementCountAndAddPrimaryKey(run.getValue("id"));
+                  failed.setMessageSuffix(last.messages().isEmpty() ? null : ": " + last.messages().get(0));
+               }
+            }
+            for(VerificationOutcome outcome : outcomes)
+            {
+               rows.incrementCount((int) Math.min(Integer.MAX_VALUE, outcome.rowsChecked()));
+               files.incrementCount(outcome.filesChecked());
+            }
+            output.getRecords().add(run);
+         }
+      }
+
+
+
+      /*******************************************************************************
+       ** Result lines.
+       *******************************************************************************/
+      @Override
+      public ArrayList<ProcessSummaryLineInterface> getProcessSummary(RunBackendStepOutput output, boolean isForResultScreen)
+      {
+         ArrayList<ProcessSummaryLineInterface> lines = new ArrayList<>();
+         passed.addSelfToListIfAnyCount(lines);
+         warnings.addSelfToListIfAnyCount(lines);
+         failed.addSelfToListIfAnyCount(lines);
+         errored.addSelfToListIfAnyCount(lines);
+         rows.addSelfToListIfAnyCount(lines);
+         files.addSelfToListIfAnyCount(lines);
+         return (lines);
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/backups/restore/BackupSource.java

@@ -0,0 +1,359 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.restore;
+
+
+import java.io.BufferedReader;
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.io.OutputStream;
+import java.nio.charset.StandardCharsets;
+import java.security.DigestInputStream;
+import java.security.MessageDigest;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.function.Consumer;
+import java.util.function.Function;
+import java.util.zip.GZIPInputStream;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.codec.ArtifactTransform;
+import com.kingsrook.qbits.backups.codec.CsvRowCodec;
+import com.kingsrook.qbits.backups.codec.HashingOutputStream;
+import com.kingsrook.qbits.backups.codec.JsonlRowCodec;
+import com.kingsrook.qbits.backups.manifest.BackupManifest;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qbits.backups.storage.BackupStorage;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** A backup run opened for restore: the catalog row, its manifest (checked against
+ ** the manifest hash in the catalog), its storage, and readers for the rows and the
+ ** file index.  Every part is checked against the stored SHA-256 in the manifest as
+ ** it is read, so a damaged part fails the restore instead of restoring bad rows.
+ *******************************************************************************/
+public final class BackupSource
+{
+   private static final ObjectMapper MAPPER = new ObjectMapper();
+
+   /////////////////////////////////////////////////////////////////////////////////
+   // Supplies the transform that decrypts the parts of an encrypted run.  The    //
+   // default knows no keys, so restoring an encrypted run fails with a clear     //
+   // message until the crypto package (QQQ core PR 1107) provider is wired in.   //
+   /////////////////////////////////////////////////////////////////////////////////
+   private static volatile Function<BackupManifest.EncryptionInfo, ArtifactTransform> transformResolver = null;
+
+   private final QRecord          run;
+   private final BackupStorage    storage;
+   private final String           runPrefix;
+   private final BackupManifest   manifest;
+   private final ArtifactTransform transform;
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private BackupSource(QRecord run, BackupStorage storage, String runPrefix, BackupManifest manifest, ArtifactTransform transform)
+   {
+      this.run = run;
+      this.storage = storage;
+      this.runPrefix = runPrefix;
+      this.manifest = manifest;
+      this.transform = transform;
+   }
+
+
+
+   /*******************************************************************************
+    ** Install the resolver for the decrypting transform (null removes it).
+    *******************************************************************************/
+   public static void setTransformResolver(Function<BackupManifest.EncryptionInfo, ArtifactTransform> resolver)
+   {
+      transformResolver = resolver;
+   }
+
+
+
+   /*******************************************************************************
+    ** Open a run for restore.
+    *******************************************************************************/
+   public static BackupSource open(Integer runId) throws QException
+   {
+      QRecord run = new BackupCatalog().get(BackupsTables.RUN, runId).orElseThrow(() -> new QException("The backup run " + runId + " was not found"));
+      String  status = run.getValueString("status");
+      if(!"SUCCEEDED".equals(status) && !"SUCCEEDED_WITH_WARNINGS".equals(status))
+      {
+         throw (new QException("The backup run " + run.getValueString("runKey") + " did not complete (status " + status + "), so it cannot be restored"));
+      }
+      String manifestKey = run.getValueString("manifestKey");
+      if(manifestKey == null)
+      {
+         throw (new QException("The backup run " + run.getValueString("runKey") + " has no manifest"));
+      }
+
+      BackupStorage storage = BackupsRuntime.storageFor(run.getValueString("storageBucketAlias"));
+      try
+      {
+         byte[] bytes = readAll(storage.openRead(manifestKey));
+         String expected = run.getValueString("manifestSha256");
+         if(expected != null && !expected.equals(HashingOutputStream.sha256Hex(bytes)))
+         {
+            throw (new QException("The manifest of backup run " + run.getValueString("runKey") + " does not match its recorded checksum"));
+         }
+         BackupManifest manifest = BackupManifest.read(bytes);
+         String         runPrefix = run.getValueString("runPrefix");
+         if(runPrefix == null)
+         {
+            runPrefix = manifestKey.substring(0, manifestKey.length() - "manifest.json".length());
+         }
+         return (new BackupSource(run, storage, runPrefix, manifest, transformFor(manifest)));
+      }
+      catch(IOException | RuntimeException e)
+      {
+         throw (new QException("Could not read the manifest of backup run " + run.getValueString("runKey") + ": " + e.getMessage(), e));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static ArtifactTransform transformFor(BackupManifest manifest) throws QException
+   {
+      BackupManifest.EncryptionInfo encryption = manifest.encryption();
+      if(encryption == null || encryption.mode() == null || "NONE".equals(encryption.mode()))
+      {
+         return (ArtifactTransform.IDENTITY);
+      }
+      Function<BackupManifest.EncryptionInfo, ArtifactTransform> resolver = transformResolver;
+      ArtifactTransform resolved = resolver == null ? null : resolver.apply(encryption);
+      if(resolved == null)
+      {
+         throw (new QException("This backup is encrypted (key " + encryption.keyRef() + "), and no key provider is available to restore it"));
+      }
+      return (resolved);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   static byte[] readAll(InputStream in) throws IOException
+   {
+      try(in)
+      {
+         return (in.readAllBytes());
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The catalog row of the run.
+    *******************************************************************************/
+   public QRecord getRun()
+   {
+      return (run);
+   }
+
+
+
+   /*******************************************************************************
+    ** The manifest.
+    *******************************************************************************/
+   public BackupManifest getManifest()
+   {
+      return (manifest);
+   }
+
+
+
+   /*******************************************************************************
+    ** The storage the backup lives in.
+    *******************************************************************************/
+   public BackupStorage getStorage()
+   {
+      return (storage);
+   }
+
+
+
+   /*******************************************************************************
+    ** The transform that decrypts the stored parts (identity when not encrypted).
+    *******************************************************************************/
+   public ArtifactTransform getTransform()
+   {
+      return (transform);
+   }
+
+
+
+   /*******************************************************************************
+    ** The prefix of the run's objects.
+    *******************************************************************************/
+   public String getRunPrefix()
+   {
+      return (runPrefix);
+   }
+
+
+
+   /*******************************************************************************
+    ** Stream the rows of one table, decoding each with the target table's field types.
+    ** The sink may throw an unchecked exception to stop.
+    *******************************************************************************/
+   public void readRows(BackupManifest.TableEntry entry, QTableMetaData decodeTable, Consumer<QRecord> sink) throws QException
+   {
+      List<BackupManifest.Part> parts = new ArrayList<>();
+      for(BackupManifest.Part part : entry.parts())
+      {
+         if("JSONL".equals(part.format()))
+         {
+            parts.add(part);
+         }
+      }
+      if(parts.isEmpty())
+      {
+         parts.addAll(entry.parts());
+      }
+
+      for(BackupManifest.Part part : parts)
+      {
+         try
+         {
+            readPart(part, decodeTable, sink);
+         }
+         catch(IOException e)
+         {
+            throw (new QException("Could not read " + part.key() + " of the backup: " + e.getMessage(), e));
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void readPart(BackupManifest.Part part, QTableMetaData decodeTable, Consumer<QRecord> sink) throws IOException, QException
+   {
+      MessageDigest digest = HashingOutputStream.newSha256();
+      try(DigestInputStream stored = new DigestInputStream(storage.openRead(runPrefix + part.key()), digest))
+      {
+         InputStream plain = transform.unwrap(stored);
+         InputStream text  = "GZIP".equals(part.compression()) ? new GZIPInputStream(plain) : plain;
+
+         if("CSV".equals(part.format()))
+         {
+            String       all     = new String(text.readAllBytes(), StandardCharsets.UTF_8);
+            List<String> records = CsvRowCodec.splitRecords(all);
+            if(!records.isEmpty())
+            {
+               CsvRowCodec  codec  = new CsvRowCodec(decodeTable, null);
+               List<String> header = CsvRowCodec.splitCells(records.get(0));
+               for(int i = 1; i < records.size(); i++)
+               {
+                  sink.accept(codec.toRecord(CsvRowCodec.splitCells(records.get(i)), header));
+               }
+            }
+         }
+         else
+         {
+            JsonlRowCodec codec = new JsonlRowCodec(decodeTable, null);
+            BufferedReader reader = new BufferedReader(new InputStreamReader(text, StandardCharsets.UTF_8));
+            String line;
+            while((line = reader.readLine()) != null)
+            {
+               if(!line.isEmpty())
+               {
+                  sink.accept(codec.decode(line));
+               }
+            }
+         }
+
+         stored.transferTo(OutputStream.nullOutputStream());
+      }
+
+      String actual = HashingOutputStream.hex(digest.digest());
+      if(part.sha256Stored() != null && !part.sha256Stored().equals(actual))
+      {
+         throw (new IOException("checksum mismatch (the stored part is damaged or was changed)"));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The file index entries of the given tables, keyed by table, record key and field.
+    *******************************************************************************/
+   public Map<String, JsonNode> fileIndex(Set<String> tables) throws QException
+   {
+      Map<String, JsonNode> index = new HashMap<>();
+      if(manifest.files() == null || manifest.files().indexKeys() == null)
+      {
+         return (index);
+      }
+      for(String indexKey : manifest.files().indexKeys())
+      {
+         try(InputStream raw = storage.openRead(runPrefix + indexKey);
+             BufferedReader reader = new BufferedReader(new InputStreamReader(new GZIPInputStream(transform.unwrap(raw)), StandardCharsets.UTF_8)))
+         {
+            String line;
+            while((line = reader.readLine()) != null)
+            {
+               if(line.isEmpty())
+               {
+                  continue;
+               }
+               JsonNode node = MAPPER.readTree(new ByteArrayInputStream(line.getBytes(StandardCharsets.UTF_8)));
+               if(tables.contains(node.path("table").asText()))
+               {
+                  index.put(indexKeyOf(node.path("table").asText(), node.path("recordKey").asText(), node.path("field").asText()), node);
+               }
+            }
+         }
+         catch(IOException e)
+         {
+            throw (new QException("Could not read the file index " + indexKey + ": " + e.getMessage(), e));
+         }
+      }
+      return (index);
+   }
+
+
+
+   /*******************************************************************************
+    ** The lookup key of a file index entry.
+    *******************************************************************************/
+   public static String indexKeyOf(String table, String recordKey, String field)
+   {
+      return (table + "\u0001" + recordKey + "\u0001" + field);
+   }
+}

src/main/java/com/kingsrook/qbits/backups/restore/CatalogImporter.java

@@ -0,0 +1,362 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.restore;
+
+
+import java.io.IOException;
+import java.io.Serializable;
+import java.nio.charset.StandardCharsets;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import com.kingsrook.qbits.backups.codec.HashingOutputStream;
+import com.kingsrook.qbits.backups.manifest.BackupManifest;
+import com.kingsrook.qbits.backups.manifest.TableFingerprints;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qbits.backups.storage.BackupStorage;
+import com.kingsrook.qbits.backups.storage.StoredObjectInfo;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Rebuilds the catalog from storage (spec 9.6): every manifest is
+ ** self-describing, so after the database with the catalog is lost, the manifests
+ ** under a bucket alias and prefix are listed, validated, and turned back into
+ ** backups_run and backups_artifact rows (trigger IMPORTED).  The content
+ ** addressed file store is re-registered in backups_file_object so dedup keeps
+ ** working.  Importing is idempotent: a run already in the catalog is skipped.
+ **
+ ** Validation: the manifest must be readable and of a known version, its run key
+ ** must match its folder, checksums.sha256 must exist and agree with the manifest
+ ** for every part, and every part must exist with the recorded size.  The checksum
+ ** of the manifest itself is computed and stored on the run, so a later restore
+ ** detects a changed manifest.
+ *******************************************************************************/
+public class CatalogImporter
+{
+   private static final Pattern PART_NUMBER = Pattern.compile("part-(\\d+)");
+   private static final Pattern SHA_KEY     = Pattern.compile("^[0-9a-f]{64}$");
+
+   private final BackupCatalog catalog = new BackupCatalog();
+
+
+
+   /*******************************************************************************
+    ** What was found for one manifest.
+    *******************************************************************************/
+   public record Inspection(String manifestKey, String status, List<String> problems, BackupManifest manifest, String runPrefix, String manifestSha256)
+   {
+      public static final String NEW     = "NEW";
+      public static final String EXISTS  = "EXISTS";
+      public static final String INVALID = "INVALID";
+   }
+
+
+
+   /*******************************************************************************
+    ** The keys of every manifest under a prefix.
+    *******************************************************************************/
+   public List<String> findManifestKeys(BackupStorage storage, String prefix)
+   {
+      List<String> keys = new ArrayList<>();
+      for(StoredObjectInfo info : storage.list(prefix == null ? "" : prefix))
+      {
+         if(info.key().endsWith("/manifest.json"))
+         {
+            keys.add(info.key());
+         }
+      }
+      return (keys);
+   }
+
+
+
+   /*******************************************************************************
+    ** Read and validate one manifest, and say whether the catalog already has it.
+    *******************************************************************************/
+   public Inspection inspect(BackupStorage storage, String manifestKey) throws QException
+   {
+      String runPrefix = manifestKey.substring(0, manifestKey.length() - "manifest.json".length());
+      byte[] bytes;
+      BackupManifest manifest;
+      try
+      {
+         bytes = BackupSource.readAll(storage.openRead(manifestKey));
+         manifest = BackupManifest.read(bytes);
+      }
+      catch(IOException | RuntimeException e)
+      {
+         return (invalid(manifestKey, runPrefix, "The manifest cannot be read: " + e.getMessage()));
+      }
+
+      String sha = HashingOutputStream.sha256Hex(bytes);
+      List<String> problems = new ArrayList<>();
+      if(manifest.manifestVersion() > BackupManifest.CURRENT_VERSION)
+      {
+         problems.add("The manifest is version " + manifest.manifestVersion() + ", newer than this qbit understands");
+      }
+      String[] segments = runPrefix.split("/");
+      if(manifest.runKey() == null || segments.length == 0 || !manifest.runKey().equals(segments[segments.length - 1]))
+      {
+         problems.add("The manifest's run key does not match its folder");
+      }
+
+      if(!problems.isEmpty())
+      {
+         return (new Inspection(manifestKey, Inspection.INVALID, problems, manifest, runPrefix, sha));
+      }
+
+      if(!catalog.where(BackupsTables.RUN, "runKey", manifest.runKey()).isEmpty())
+      {
+         return (new Inspection(manifestKey, Inspection.EXISTS, List.of(), manifest, runPrefix, sha));
+      }
+
+      checkParts(storage, manifest, runPrefix, problems);
+      return (new Inspection(manifestKey, problems.isEmpty() ? Inspection.NEW : Inspection.INVALID, problems, manifest, runPrefix, sha));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private Inspection invalid(String manifestKey, String runPrefix, String problem)
+   {
+      return (new Inspection(manifestKey, Inspection.INVALID, List.of(problem), null, runPrefix, null));
+   }
+
+
+
+   /*******************************************************************************
+    ** Check checksums.sha256 against the manifest, and that each part exists.
+    *******************************************************************************/
+   private void checkParts(BackupStorage storage, BackupManifest manifest, String runPrefix, List<String> problems)
+   {
+      Map<String, String> checksums = readChecksums(storage, runPrefix);
+      if(checksums == null)
+      {
+         problems.add("checksums.sha256 is missing or unreadable");
+         return;
+      }
+
+      for(BackupManifest.TableEntry table : manifest.tables() == null ? List.<BackupManifest.TableEntry>of() : manifest.tables())
+      {
+         for(BackupManifest.Part part : table.parts())
+         {
+            String listed = checksums.get(part.key());
+            if(listed == null || !listed.equals(part.sha256Stored()))
+            {
+               problems.add("The checksum of " + part.key() + " does not match the manifest");
+            }
+            else if(storage.head(runPrefix + part.key()).map(StoredObjectInfo::size).orElse(-1L) != part.bytesStored())
+            {
+               problems.add("The part " + part.key() + " is missing or has the wrong size");
+            }
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Create the catalog rows of one valid manifest.  Returns the new run id.
+    *******************************************************************************/
+   public Integer importRun(String bucketAlias, BackupStorage storage, Inspection inspection) throws QException
+   {
+      BackupManifest manifest  = inspection.manifest();
+      String         runPrefix = inspection.runPrefix();
+      List<BackupManifest.TableEntry> tables = manifest.tables() == null ? List.of() : manifest.tables();
+
+      Instant started = parse(manifest.startedAt());
+      Instant ended   = parse(manifest.finishedAt());
+      Integer planId  = null;
+      if(manifest.plan() != null && manifest.plan().planKey() != null)
+      {
+         List<QRecord> plans = catalog.where(BackupsTables.PLAN, "planKey", manifest.plan().planKey());
+         planId = plans.isEmpty() ? null : plans.get(0).getValueInteger("id");
+      }
+
+      Map<String, Serializable> row = new LinkedHashMap<>();
+      row.put("backupPlanId", planId);
+      row.put("runKey", manifest.runKey());
+      row.put("trigger", "IMPORTED");
+      row.put("requestedByUserId", manifest.requestedBy());
+      row.put("status", manifest.warnings() == null || manifest.warnings().isEmpty() ? "SUCCEEDED" : "SUCCEEDED_WITH_WARNINGS");
+      row.put("startDate", started);
+      row.put("endDate", ended);
+      row.put("durationMs", started != null && ended != null ? ended.toEpochMilli() - started.toEpochMilli() : null);
+      row.put("tablesPlanned", tables.size());
+      row.put("tablesDone", tables.size());
+      row.put("rowsTotal", manifest.totals() == null ? null : manifest.totals().rows());
+      row.put("bytesStored", manifest.totals() == null ? null : manifest.totals().bytesStored());
+      row.put("consistencyAchieved", manifest.consistency() == null ? null : manifest.consistency().achieved());
+      row.put("storageBucketAlias", bucketAlias);
+      row.put("runPrefix", runPrefix);
+      row.put("manifestKey", inspection.manifestKey());
+      row.put("manifestSha256", inspection.manifestSha256());
+      row.put("securityScope", manifest.securityScope());
+      row.put("qqqVersion", manifest.instance() == null ? null : manifest.instance().qqqVersion());
+      row.put("appVersion", manifest.instance() == null ? null : manifest.instance().appVersion());
+      row.put("instanceName", manifest.instance() == null ? null : manifest.instance().name());
+      row.put("schemaFingerprint", TableFingerprints.combine(tables.stream().map(BackupManifest.TableEntry::fingerprint).toList()));
+      boolean encrypted = manifest.encryption() != null && manifest.encryption().mode() != null && !"NONE".equals(manifest.encryption().mode());
+      row.put("encryptionKeyRef", manifest.encryption() == null ? null : manifest.encryption().keyRef());
+      row.put("encryptionKeyFingerprint", manifest.encryption() == null ? null : manifest.encryption().keyFingerprint());
+      row.put("verificationStatus", "UNVERIFIED");
+      row.put("warningCount", manifest.warnings() == null ? 0 : manifest.warnings().size());
+      if(manifest.files() != null)
+      {
+         row.put("filesReferenced", (int) manifest.files().objects());
+         row.put("filesMissing", (int) manifest.files().missing());
+         row.put("fileBytesReferenced", manifest.files().bytes());
+      }
+      Integer runId = catalog.insert(BackupsTables.RUN, row);
+
+      Map<String, String> checksums = readChecksums(storage, runPrefix);
+      if(checksums == null)
+      {
+         checksums = new HashMap<>();
+      }
+      for(BackupManifest.TableEntry table : tables)
+      {
+         for(int i = 0; i < table.parts().size(); i++)
+         {
+            BackupManifest.Part part = table.parts().get(i);
+            Matcher matcher = PART_NUMBER.matcher(part.key());
+            int number = matcher.find() ? Integer.parseInt(matcher.group(1)) : i + 1;
+            boolean last = i == table.parts().size() - 1;
+            catalog.insertArtifact(runId, "TABLE_DATA", table.name(), number, part.key(), part.format(), part.compression(), part.encrypted(), part.rows(),
+               part.bytesRaw(), part.bytesStored(), part.sha256Stored(), part.sha256Raw(), last ? table.rowsHash() : null, null, null, table.fingerprint());
+         }
+      }
+      if(manifest.files() != null && manifest.files().indexKeys() != null)
+      {
+         int number = 1;
+         for(String key : manifest.files().indexKeys())
+         {
+            long size = storage.head(runPrefix + key).map(StoredObjectInfo::size).orElse(0L);
+            catalog.insertArtifact(runId, "FILE_OBJECTS_INDEX", null, number++, key, "JSONL", "GZIP", encrypted, 0, 0, size, checksums.get(key), null, null, null, null, null);
+         }
+      }
+      artifactOfKey(storage, runPrefix, "checksums.sha256", "CHECKSUMS", "TEXT", runId, null);
+      artifactOfKey(storage, runPrefix, "manifest.json", "MANIFEST", "JSON", runId, inspection.manifestSha256());
+
+      registerFileStore(bucketAlias, storage, runPrefix, runId, manifest, encrypted);
+      return (runId);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void artifactOfKey(BackupStorage storage, String runPrefix, String key, String type, String format, Integer runId, String knownSha) throws QException
+   {
+      long size = storage.head(runPrefix + key).map(StoredObjectInfo::size).orElse(0L);
+      String sha = knownSha;
+      if(sha == null)
+      {
+         try
+         {
+            sha = HashingOutputStream.sha256Hex(BackupSource.readAll(storage.openRead(runPrefix + key)));
+         }
+         catch(IOException | RuntimeException e)
+         {
+            sha = null;
+         }
+      }
+      catalog.insertArtifact(runId, type, null, 1, key, format, "NONE", false, 0, size, size, sha, sha, null, null, null, null);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private Map<String, String> readChecksums(BackupStorage storage, String runPrefix)
+   {
+      Map<String, String> checksums = new HashMap<>();
+      try
+      {
+         for(String line : new String(BackupSource.readAll(storage.openRead(runPrefix + "checksums.sha256")), StandardCharsets.UTF_8).split("\n"))
+         {
+            String[] parts = line.split("  ", 2);
+            if(parts.length == 2)
+            {
+               checksums.put(parts[1].trim(), parts[0].trim());
+            }
+         }
+      }
+      catch(IOException | RuntimeException e)
+      {
+         return (null);
+      }
+      return (checksums);
+   }
+
+
+
+   /*******************************************************************************
+    ** Re-register the content-addressed files of the instance, so the next backup
+    ** deduplicates against them again.
+    *******************************************************************************/
+   private void registerFileStore(String bucketAlias, BackupStorage storage, String runPrefix, Integer runId, BackupManifest manifest, boolean encrypted)
+   {
+      String[] segments = runPrefix.split("/");
+      if(segments.length < 6)
+      {
+         return;
+      }
+      String instancePrefix = String.join("/", java.util.Arrays.copyOf(segments, segments.length - 5)) + "/";
+      String fingerprint = manifest.encryption() == null ? null : manifest.encryption().keyFingerprint();
+      var registry = catalog.fileStoreRegistry(bucketAlias, runId, fingerprint);
+      for(StoredObjectInfo info : storage.list(instancePrefix + "_files/sha256/"))
+      {
+         String name = info.key().substring(info.key().lastIndexOf('/') + 1);
+         int dot = name.indexOf('.');
+         String sha = dot < 0 ? name : name.substring(0, dot);
+         if(SHA_KEY.matcher(sha).matches() && !registry.isKnown(sha))
+         {
+            registry.register(sha, info.size(), null, info.key(), encrypted);
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static Instant parse(String text)
+   {
+      try
+      {
+         return (text == null ? null : Instant.parse(text));
+      }
+      catch(RuntimeException e)
+      {
+         return (null);
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/backups/restore/RestoreEngine.java

@@ -0,0 +1,651 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.restore;
+
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.Serializable;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import com.kingsrook.qbits.backups.BackupsQBitConfig;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.codec.HashingOutputStream;
+import com.kingsrook.qbits.backups.manifest.BackupManifest;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.permissions.BackupsPermissionChecker;
+import com.kingsrook.qbits.backups.permissions.BackupsPermissions;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qbits.backups.run.BackupEngine;
+import com.kingsrook.qbits.backups.run.BackupRunFactory;
+import com.kingsrook.qbits.backups.run.BackupRunRequest;
+import com.kingsrook.qbits.backups.run.BackupRunResult;
+import com.kingsrook.qbits.backups.scope.PlanSettings;
+import com.kingsrook.qbits.backups.scope.ScopeResolver;
+import com.kingsrook.qbits.backups.scope.TableRole;
+import com.kingsrook.qbits.backups.scope.TableRoles;
+import com.kingsrook.qbits.backups.storage.BackupStorage;
+import com.kingsrook.qbits.backups.storage.WriteOptions;
+import com.kingsrook.qqq.backend.core.actions.audits.AuditAction;
+import com.kingsrook.qqq.backend.core.actions.tables.DeleteAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+/*******************************************************************************
+ ** Restores from a backup run (spec 9.3 to 9.5).  Two entry points share the same
+ ** table pass:  review() reads and compares without writing anything, and
+ ** execute() takes the pre-restore backup, writes in restore order, resyncs key
+ ** sequences, brings files back (re-hashing each against the index), writes one
+ ** summary audit per table, and records backups_restore_run and
+ ** backups_restore_run_table rows.
+ **
+ ** Safety rails (spec 9.4) are enforced here, not only in the screens:  the caller
+ ** needs backups.restore (REPLACE also backups.admin and the typed confirmation),
+ ** SECRET and BACKUPS tables are never restored, EPHEMERAL tables only when named,
+ ** and nothing restores while a backup of the same tables is running.
+ *******************************************************************************/
+public class RestoreEngine
+{
+   private static final QLogger LOG = QLogger.getLogger(RestoreEngine.class);
+
+   private static final long RUNNING_HEARTBEAT_MINUTES = 10;
+
+   private final BackupCatalog catalog = new BackupCatalog();
+
+
+
+   /*******************************************************************************
+    ** What a request resolves to: the source, the tables in restore order and the
+    ** table each is written to, with every rail violation as an error.
+    *******************************************************************************/
+   public record Plan(BackupSource source, List<String> order, Map<String, String> targets, List<String> errors, List<String> warnings, List<String> notes)
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Resolve a request and check every safety rail, without touching any data.
+    *******************************************************************************/
+   public Plan plan(RestoreRequest request)
+   {
+      List<String>        errors   = new ArrayList<>();
+      List<String>        warnings = new ArrayList<>();
+      List<String>        notes    = new ArrayList<>();
+      List<String>        order    = new ArrayList<>();
+      Map<String, String> targets  = new LinkedHashMap<>();
+      QInstance           instance = QContext.getQInstance();
+
+      if(!BackupsPermissionChecker.has(BackupsPermissions.RESTORE))
+      {
+         errors.add("Restoring needs the " + BackupsPermissions.RESTORE + " permission.");
+      }
+      boolean replace = RestoreRequest.MODE_REPLACE.equals(request.getMode());
+      if(!List.of(RestoreRequest.MODE_INSERT_NEW, RestoreRequest.MODE_UPSERT, RestoreRequest.MODE_REPLACE).contains(request.getMode()))
+      {
+         errors.add("Unknown restore mode " + request.getMode() + ".");
+      }
+      if(!List.of(RestoreRequest.IDS_PRESERVE, RestoreRequest.IDS_REMAP).contains(request.getIdStrategy()))
+      {
+         errors.add("Unknown id strategy " + request.getIdStrategy() + ".");
+      }
+      if(replace && !BackupsPermissionChecker.has(BackupsPermissions.ADMIN))
+      {
+         errors.add("A REPLACE restore needs the " + BackupsPermissions.ADMIN + " permission as well.");
+      }
+      if(replace && RestoreRequest.IDS_REMAP.equals(request.getIdStrategy()))
+      {
+         errors.add("REPLACE cannot be combined with new ids: use PRESERVE ids.");
+      }
+
+      BackupSource source = null;
+      try
+      {
+         source = BackupSource.open(request.getSourceRunId());
+      }
+      catch(QException e)
+      {
+         errors.add(e.getMessage());
+         return (new Plan(null, order, targets, errors, warnings, notes));
+      }
+
+      boolean explicit = !request.getTables().isEmpty();
+      List<String> names = new ArrayList<>();
+      if(explicit)
+      {
+         for(String name : request.getTables())
+         {
+            if(source.getManifest().table(name) == null)
+            {
+               errors.add("The table " + name + " is not in this backup.");
+            }
+            else
+            {
+               names.add(name);
+            }
+         }
+      }
+      else
+      {
+         source.getManifest().tables().forEach(t -> names.add(t.name()));
+      }
+
+      if(request.getTargetTable() != null && names.size() != 1)
+      {
+         errors.add("A target table can only be chosen when exactly one table is restored.");
+      }
+
+      for(String name : names)
+      {
+         String         targetName = request.getTargetTable() != null && names.size() == 1 ? request.getTargetTable() : name;
+         QTableMetaData target     = instance.getTable(targetName);
+         if(target == null)
+         {
+            errors.add("The table " + targetName + " does not exist in this instance.");
+            continue;
+         }
+         TableRole role = TableRoles.roleOf(instance, target);
+         if(role == TableRole.SECRET || role == TableRole.BACKUPS)
+         {
+            errors.add("The table " + targetName + " is a " + role + " table, and restores never touch those.");
+            continue;
+         }
+         if(role == TableRole.EPHEMERAL)
+         {
+            if(!explicit)
+            {
+               notes.add("The table " + targetName + " holds temporary data and is left out unless you choose it.");
+               continue;
+            }
+            warnings.add("The table " + targetName + " holds temporary data; you chose to restore it anyway.");
+         }
+         targets.put(name, targetName);
+      }
+
+      List<String> manifestOrder = source.getManifest().restoreOrder() == null ? List.of() : source.getManifest().restoreOrder();
+      for(String name : manifestOrder)
+      {
+         if(targets.containsKey(name))
+         {
+            order.add(name);
+         }
+      }
+      for(String name : targets.keySet())
+      {
+         if(!order.contains(name))
+         {
+            order.add(name);
+         }
+      }
+
+      if(order.isEmpty() && errors.isEmpty())
+      {
+         errors.add("There are no tables to restore.");
+      }
+
+      if(replace && errors.isEmpty())
+      {
+         String expected = RestoreRequest.expectedConfirmation(order);
+         if(request.getConfirmationText() == null || !expected.equals(request.getConfirmationText().trim()))
+         {
+            errors.add("To confirm a REPLACE, type " + expected + ".");
+         }
+      }
+
+      String running = runningBackupFor(order);
+      if(running != null)
+      {
+         errors.add(running);
+      }
+
+      return (new Plan(source, order, targets, errors, warnings, notes));
+   }
+
+
+
+   /*******************************************************************************
+    ** A message when a backup that covers any of these tables is running, else null.
+    *******************************************************************************/
+   private String runningBackupFor(List<String> tables)
+   {
+      try
+      {
+         Instant cutoff = BackupsRuntime.getClock().instant().minusSeconds(RUNNING_HEARTBEAT_MINUTES * 60);
+         for(QRecord run : catalog.where(BackupsTables.RUN, "status", "RUNNING"))
+         {
+            Instant heartbeat = run.getValueInstant("heartbeatDate");
+            if(heartbeat == null || !heartbeat.isAfter(cutoff))
+            {
+               continue;
+            }
+            if(coversAny(run, tables))
+            {
+               return ("A backup of these tables is running (" + run.getValueString("runKey") + "). Wait for it to finish, then restore.");
+            }
+         }
+         return (null);
+      }
+      catch(QException e)
+      {
+         return ("Could not check for running backups: " + e.getMessage());
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Whether a running backup covers any of the tables (a run without a plan is
+    ** assumed to).
+    *******************************************************************************/
+   private boolean coversAny(QRecord run, List<String> tables) throws QException
+   {
+      Integer planId = run.getValueInteger("backupPlanId");
+      if(planId == null)
+      {
+         return (true);
+      }
+      QRecord plan = catalog.get(BackupsTables.PLAN, planId).orElse(null);
+      if(plan == null)
+      {
+         return (true);
+      }
+      Set<String> covered = new HashSet<>(BackupRunFactory.resolveScope(plan).names());
+      return (tables.stream().anyMatch(covered::contains));
+   }
+
+
+
+   /*******************************************************************************
+    ** Review: everything the restore would do, with nothing written.
+    *******************************************************************************/
+   public RestoreOutcome review(RestoreRequest request) throws QException
+   {
+      Plan plan = plan(request);
+      if(!plan.errors().isEmpty())
+      {
+         RestoreOutcome outcome = new RestoreOutcome();
+         outcome.getErrors().addAll(plan.errors());
+         return (outcome);
+      }
+
+      RestoreOutcome outcome = new RestorePass(request, plan.source(), true, null, plan.order(), plan.targets()).run();
+      outcome.getWarnings().addAll(plan.warnings());
+      outcome.getNotes().addAll(plan.notes());
+      if(!request.getPreRestoreBackup())
+      {
+         outcome.getWarnings().add("The safety backup before the restore is turned off.");
+      }
+      if(RestoreRequest.IDS_PRESERVE.equals(request.getIdStrategy()) && outcome.sum(t -> t.getSequenceNeeded() ? 1 : 0) > 0 && !request.getWriter().canResyncSequences())
+      {
+         outcome.getWarnings().add("Key sequences cannot be resynced with this version of QQQ (it needs the sequence resync hook), so on databases with generated keys the next generated id may collide. Resync them after the restore.");
+      }
+      if(!request.getWriter().usesCoreRestoreFlag())
+      {
+         outcome.getNotes().add("This version of QQQ has no restore mode for writes, so rows are written with the standard actions: record security and validation apply, and modified dates may be set to now.");
+      }
+      return (outcome);
+   }
+
+
+
+   /*******************************************************************************
+    ** Execute the restore.  Throws when a rail refuses it; otherwise returns the
+    ** outcome (also recorded in the restore run rows).
+    *******************************************************************************/
+   public RestoreOutcome execute(RestoreRequest request) throws QException
+   {
+      Plan plan = plan(request);
+      if(!plan.errors().isEmpty())
+      {
+         throw (new QException(String.join(" ", plan.errors())));
+      }
+
+      BackupsQBitConfig config = BackupsRuntime.getConfig();
+      Instant           start  = BackupsRuntime.getClock().instant();
+
+      Map<String, Serializable> row = new LinkedHashMap<>();
+      row.put("sourceBackupRunId", request.getSourceRunId());
+      row.put("requestedByUserId", request.getRequestedBy());
+      row.put("startDate", start);
+      row.put("status", "RUNNING");
+      row.put("mode", request.getMode());
+      row.put("idStrategy", request.getIdStrategy());
+      row.put("matchOn", request.getMatchOn());
+      row.put("targetInstanceName", config.getInstanceName() != null ? config.getInstanceName() : "qqq");
+      row.put("scopeSummary", scopeSummary(request, plan));
+      row.put("automationsSuppressed", request.getSuppressAutomations());
+      row.put("esbSuppressed", !request.getPublishEvents());
+      row.put("confirmationText", RestoreRequest.MODE_REPLACE.equals(request.getMode()) ? request.getConfirmationText() : null);
+      Integer restoreRunId = catalog.insert(BackupsTables.RESTORE_RUN, row);
+
+      RestoreOutcome outcome = null;
+      try
+      {
+         Integer preRestoreRunId = null;
+         if(request.getPreRestoreBackup())
+         {
+            preRestoreRunId = preRestoreBackup(request, plan);
+            catalog.update(BackupsTables.RESTORE_RUN, restoreRunId, Map.of("preRestoreBackupRunId", preRestoreRunId));
+         }
+
+         RestorePass pass = new RestorePass(request, plan.source(), false, restoreRunId, plan.order(), plan.targets());
+         outcome = pass.run();
+         outcome.setRestoreRunId(restoreRunId);
+         outcome.setPreRestoreRunId(preRestoreRunId);
+         outcome.getWarnings().addAll(plan.warnings());
+         outcome.getNotes().addAll(plan.notes());
+
+         resyncSequences(request, plan, outcome);
+         restoreFiles(request, plan, pass, outcome, restoreRunId);
+         recordResults(request, plan, outcome, restoreRunId, start);
+         deleteIdMap(restoreRunId);
+         return (outcome);
+      }
+      catch(QException | RuntimeException e)
+      {
+         LOG.warn("Restore failed", e, logPair("restoreRunId", restoreRunId));
+         String message = e.getClass().getSimpleName() + ": " + e.getMessage();
+         try
+         {
+            Map<String, Serializable> failed = new LinkedHashMap<>();
+            failed.put("status", "FAILED");
+            failed.put("endDate", BackupsRuntime.getClock().instant());
+            failed.put("errorMessage", message.length() > 2000 ? message.substring(0, 2000) : message);
+            catalog.update(BackupsTables.RESTORE_RUN, restoreRunId, failed);
+         }
+         catch(QException inner)
+         {
+            LOG.warn("Could not record the failed restore", inner);
+         }
+         throw (e);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private String scopeSummary(RestoreRequest request, Plan plan)
+   {
+      StringBuilder sb = new StringBuilder(String.join(", ", plan.order()));
+      if(!request.getFilters().isEmpty())
+      {
+         sb.append(" | filters on ").append(String.join(", ", request.getFilters().keySet()));
+      }
+      if(request.getTargetTable() != null)
+      {
+         sb.append(" | into ").append(request.getTargetTable());
+      }
+      if(!request.getPreRestoreBackup())
+      {
+         sb.append(" | no pre-restore backup");
+      }
+      return (sb.toString());
+   }
+
+
+
+   /*******************************************************************************
+    ** Back up the target scope (with its files) before writing anything.
+    *******************************************************************************/
+   private Integer preRestoreBackup(RestoreRequest request, Plan plan) throws QException
+   {
+      BackupSource  source = plan.source();
+      BackupsQBitConfig config = BackupsRuntime.getConfig();
+      String        alias  = source.getRun().getValueString("storageBucketAlias");
+
+      PlanSettings settings = PlanSettings.adHoc().with("scopeType", "TABLES").with("planKey", "pre-restore");
+      Map<String, Serializable> original = source.getManifest().plan() == null ? Map.of() : source.getManifest().plan().settings();
+      for(String key : List.of("prefix", "format", "compression", "pageSize", "targetPartBytes", "fileObjectPolicy", "heavyFieldPolicy", "consistency"))
+      {
+         if(original != null && original.get(key) != null)
+         {
+            settings.with(key, original.get(key));
+         }
+      }
+      boolean encrypts = source.getTransform().encrypts();
+      if(encrypts)
+      {
+         settings.with("encryptionMode", "CLIENT_AES256_GCM").with("sensitiveFieldPolicy", "INCLUDE_ENCRYPTED_ONLY");
+      }
+
+      List<ScopeResolver.ScopeRule> rules = new ArrayList<>();
+      for(String name : plan.order())
+      {
+         rules.add(new ScopeResolver.ScopeRule(true, "TABLE", plan.targets().get(name), request.filterFor(name), false, null));
+      }
+
+      BackupRunRequest backup = new BackupRunRequest()
+         .withSettings(settings)
+         .withScope(new ScopeResolver(QContext.getQInstance()).resolve(settings, rules))
+         .withTrigger("PRE_RESTORE")
+         .withRequestedBy(request.getRequestedBy())
+         .withBucketAlias(alias)
+         .withStorage(source.getStorage())
+         .withSourceResolver(BackupsRuntime::storageFor)
+         .withInstanceName(config.getInstanceName() != null ? config.getInstanceName() : "qqq")
+         .withPlanName("Pre-restore backup")
+         .withClock(BackupsRuntime.getClock());
+      BackupManifest.EncryptionInfo encryption = source.getManifest().encryption();
+      backup.withTransform(source.getTransform(), encrypts && encryption != null ? encryption.keyRef() : null, encrypts && encryption != null ? encryption.keyFingerprint() : null);
+
+      BackupRunResult result = new BackupEngine().execute(backup);
+      if(!result.isUsable())
+      {
+         throw (new QException("The backup taken before the restore failed, so nothing was restored: " + result.getErrorMessage()));
+      }
+      return (result.getRunId());
+   }
+
+
+
+   /*******************************************************************************
+    ** Advance the key sequences of the tables written with their original ids.
+    *******************************************************************************/
+   private void resyncSequences(RestoreRequest request, Plan plan, RestoreOutcome outcome) throws QException
+   {
+      List<QTableMetaData> tables = new ArrayList<>();
+      for(RestoreOutcome.TableOutcome table : outcome.getTables().values())
+      {
+         if(table.getSequenceNeeded())
+         {
+            tables.add(QContext.getQInstance().getTable(table.getTargetName()));
+         }
+      }
+      if(tables.isEmpty())
+      {
+         return;
+      }
+      if(!request.getWriter().canResyncSequences())
+      {
+         outcome.getWarnings().add("Key sequences were not resynced: this version of QQQ has no resync hook.");
+         return;
+      }
+      List<String> resynced = request.getWriter().resyncSequences(tables);
+      outcome.setSequencesResynced(resynced.size());
+      for(RestoreOutcome.TableOutcome table : outcome.getTables().values())
+      {
+         table.setSequenceResynced(resynced.contains(table.getTargetName()));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Copy files back from the content-addressed store, re-hashing each against the
+    ** index.  A conflicting file (different content at the target) is only replaced
+    ** by a REPLACE restore.
+    *******************************************************************************/
+   private void restoreFiles(RestoreRequest request, Plan plan, RestorePass pass, RestoreOutcome outcome, Integer restoreRunId)
+   {
+      for(RestorePass.FileWork work : pass.getFileWork())
+      {
+         if(work.conflict() && !RestoreRequest.MODE_REPLACE.equals(request.getMode()))
+         {
+            continue;
+         }
+         RestoreOutcome.TableOutcome table = outcome.getTables().get(work.table());
+         try
+         {
+            copyFileBack(plan.source(), work, restoreRunId);
+            table.addFilesRestored(1);
+            table.addFileBytesRestored(Math.max(0, work.size()));
+         }
+         catch(IOException | RuntimeException e)
+         {
+            outcome.addFilesFailed(1);
+            table.getProblems().add("The file " + work.targetKey() + " was not restored: " + e.getMessage());
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Write one file to a temporary key, check its SHA-256 against the index, and
+    ** only then put it in place.
+    *******************************************************************************/
+   private void copyFileBack(BackupSource source, RestorePass.FileWork work, Integer restoreRunId) throws IOException
+   {
+      BackupStorage target = BackupsRuntime.storageFor(work.targetAlias());
+      String        temp   = work.targetKey() + ".qqq-restore-" + restoreRunId;
+
+      String observed;
+      try(InputStream in = source.getTransform().unwrap(source.getStorage().openRead(work.casKey()));
+          HashingOutputStream out = new HashingOutputStream(target.openWrite(temp, WriteOptions.create().withMetadata("qqq-restore-run", String.valueOf(restoreRunId)))))
+      {
+         in.transferTo(out);
+         out.close();
+         observed = out.getSha256();
+      }
+
+      if(!work.sha256().equals(observed))
+      {
+         target.deletePermanent(temp);
+         throw (new IOException("checksum mismatch after reading the stored copy"));
+      }
+      target.copy(temp, work.targetKey());
+      target.deletePermanent(temp);
+   }
+
+
+
+   /*******************************************************************************
+    ** One summary audit per table, the per-table rows, and the totals on the run.
+    *******************************************************************************/
+   private void recordResults(RestoreRequest request, Plan plan, RestoreOutcome outcome, Integer restoreRunId, Instant start) throws QException
+   {
+      String runKey = plan.source().getRun().getValueString("runKey");
+      for(RestoreOutcome.TableOutcome t : outcome.getTables().values())
+      {
+         Map<String, Serializable> row = new LinkedHashMap<>();
+         row.put("backupRestoreRunId", restoreRunId);
+         row.put("tableName", t.getName());
+         row.put("targetTableName", t.getTargetName());
+         row.put("rowsInserted", t.getInserted());
+         row.put("rowsUpdated", t.getUpdated());
+         row.put("rowsUnchanged", t.getUnchanged());
+         row.put("rowsDeleted", t.getDeleted());
+         row.put("rowsSkipped", t.getSkipped() + t.getConflicts());
+         row.put("rowsErrored", t.getErrored());
+         row.put("schemaStatus", t.getSchemaStatus());
+         row.put("unmappedFields", String.join(", ", t.getUnmappedFields()));
+         row.put("sequenceResynced", t.getSequenceResynced());
+         row.put("status", t.getStatus());
+         catalog.insert(BackupsTables.RESTORE_RUN_TABLE, row);
+
+         if(!"SKIPPED".equals(t.getStatus()))
+         {
+            summaryAudit(t, runKey, restoreRunId);
+         }
+      }
+
+      boolean warnings = outcome.sum(t -> t.getErrored()) > 0 || outcome.getFilesFailed() > 0 || !outcome.getWarnings().isEmpty()
+         || outcome.getTables().values().stream().anyMatch(t -> "SKIPPED".equals(t.getStatus()));
+
+      Map<String, Serializable> totals = new LinkedHashMap<>();
+      totals.put("status", warnings ? "SUCCEEDED_WITH_WARNINGS" : "SUCCEEDED");
+      totals.put("endDate", BackupsRuntime.getClock().instant());
+      totals.put("rowsInserted", outcome.sum(RestoreOutcome.TableOutcome::getInserted));
+      totals.put("rowsUpdated", outcome.sum(RestoreOutcome.TableOutcome::getUpdated));
+      totals.put("rowsUnchanged", outcome.sum(RestoreOutcome.TableOutcome::getUnchanged));
+      totals.put("rowsDeleted", outcome.sum(RestoreOutcome.TableOutcome::getDeleted));
+      totals.put("rowsSkipped", outcome.sum(t -> t.getSkipped() + t.getConflicts()));
+      totals.put("rowsErrored", outcome.sum(RestoreOutcome.TableOutcome::getErrored));
+      totals.put("filesRestored", (int) outcome.sum(t -> t.getFilesRestored()));
+      totals.put("filesAlreadyPresent", (int) outcome.sum(t -> t.getFilesPresent()));
+      totals.put("filesConflicting", (int) outcome.sum(t -> t.getFilesConflicting()));
+      totals.put("filesMissingFromBackup", (int) outcome.sum(t -> t.getFilesMissing()));
+      totals.put("fileBytesRestored", outcome.sum(RestoreOutcome.TableOutcome::getFileBytesRestored));
+      totals.put("sequencesResynced", outcome.getSequencesResynced());
+      catalog.update(BackupsTables.RESTORE_RUN, restoreRunId, totals);
+   }
+
+
+
+   /*******************************************************************************
+    ** The one audit entry for a table in a restore (replaces per-record audit).
+    *******************************************************************************/
+   private void summaryAudit(RestoreOutcome.TableOutcome t, String runKey, Integer restoreRunId)
+   {
+      try
+      {
+         AuditAction.execute(t.getTargetName(), null, Map.of(), "Restore " + restoreRunId + " from backup " + runKey + ": "
+            + t.getInserted() + " inserted, " + t.getUpdated() + " updated, " + t.getDeleted() + " deleted, " + t.getUnchanged() + " unchanged");
+      }
+      catch(RuntimeException e)
+      {
+         LOG.warn("Could not write the restore summary audit", e, logPair("table", t.getTargetName()));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The id map rows are only needed while the restore runs.
+    *******************************************************************************/
+   private void deleteIdMap(Integer restoreRunId)
+   {
+      try
+      {
+         DeleteInput input = new DeleteInput(BackupsTables.ID_MAP);
+         input.setQueryFilter(new QQueryFilter(new QFilterCriteria("restoreRunId", QCriteriaOperator.EQUALS, restoreRunId)));
+         input.withPermissionBypass("backups restore id map");
+         new DeleteAction().execute(input);
+      }
+      catch(QException | RuntimeException e)
+      {
+         LOG.warn("Could not clear the id map of a restore", e, logPair("restoreRunId", restoreRunId));
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/backups/restore/RestoreOutcome.java

@@ -0,0 +1,710 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.restore;
+
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+
+/*******************************************************************************
+ ** What a restore pass found (Review) or did (Execute): the per-table counts, the
+ ** schema comparison, the sample diffs and the file counts.  Review and Execute
+ ** share one algorithm, so the Review numbers are the numbers the restore produces.
+ ** Nothing here ever holds a sensitive value: sample diffs are masked when built.
+ *******************************************************************************/
+public class RestoreOutcome
+{
+   private final Map<String, TableOutcome> tables   = new LinkedHashMap<>();
+   private final List<String>              warnings = new ArrayList<>();
+   private final List<String>              errors   = new ArrayList<>();
+   private final List<String>              notes    = new ArrayList<>();
+
+   private Integer preRestoreRunId;
+   private Integer restoreRunId;
+   private int     sequencesResynced;
+   private int     filesFailed;
+
+
+
+   /*******************************************************************************
+    ** One changed record, as masked "field: old -> new" texts.
+    *******************************************************************************/
+   public record Sample(String key, List<String> changes)
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** The result for one table.
+    *******************************************************************************/
+   public static class TableOutcome
+   {
+      private final String name;
+      private final String targetName;
+
+      private String       status           = "PENDING";
+      private String       schemaStatus     = "MATCH";
+      private final List<String> schemaNotes = new ArrayList<>();
+      private final List<String> unmappedFields = new ArrayList<>();
+      private final List<String> unmappedReferences = new ArrayList<>();
+      private final List<String> problems   = new ArrayList<>();
+      private final List<Sample> samples    = new ArrayList<>();
+      private long         rows;
+      private long         inserted;
+      private long         updated;
+      private long         unchanged;
+      private long         skipped;
+      private long         deleted;
+      private long         conflicts;
+      private long         orphans;
+      private long         errored;
+      private boolean      sequenceNeeded;
+      private boolean      sequenceResynced;
+      private long         updatedSampleTotal;
+      private int          filesToRestore;
+      private int          filesPresent;
+      private int          filesConflicting;
+      private int          filesMissing;
+      private int          filesRestored;
+      private long         fileBytesRestored;
+
+
+
+      /*******************************************************************************
+       ** Constructor.
+       *******************************************************************************/
+      public TableOutcome(String name, String targetName)
+      {
+         this.name = name;
+         this.targetName = targetName;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for name (the table in the backup)
+       *******************************************************************************/
+      public String getName()
+      {
+         return (name);
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for targetName (the table written)
+       *******************************************************************************/
+      public String getTargetName()
+      {
+         return (targetName);
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for status
+       *******************************************************************************/
+      public String getStatus()
+      {
+         return (status);
+      }
+
+
+
+      /*******************************************************************************
+       ** Setter for status
+       *******************************************************************************/
+      public void setStatus(String status)
+      {
+         this.status = status;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for schemaStatus
+       *******************************************************************************/
+      public String getSchemaStatus()
+      {
+         return (schemaStatus);
+      }
+
+
+
+      /*******************************************************************************
+       ** Setter for schemaStatus
+       *******************************************************************************/
+      public void setSchemaStatus(String schemaStatus)
+      {
+         this.schemaStatus = schemaStatus;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for schemaNotes
+       *******************************************************************************/
+      public List<String> getSchemaNotes()
+      {
+         return (schemaNotes);
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for unmappedFields (in the backup, not in the target)
+       *******************************************************************************/
+      public List<String> getUnmappedFields()
+      {
+         return (unmappedFields);
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for unmappedReferences (id fields that metadata cannot trace)
+       *******************************************************************************/
+      public List<String> getUnmappedReferences()
+      {
+         return (unmappedReferences);
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for problems (error messages, never row values)
+       *******************************************************************************/
+      public List<String> getProblems()
+      {
+         return (problems);
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for samples
+       *******************************************************************************/
+      public List<Sample> getSamples()
+      {
+         return (samples);
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for rows
+       *******************************************************************************/
+      public long getRows()
+      {
+         return (rows);
+      }
+
+
+
+      /*******************************************************************************
+       ** Add rows read from the backup.
+       *******************************************************************************/
+      public void addRows(long n)
+      {
+         rows += n;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for inserted
+       *******************************************************************************/
+      public long getInserted()
+      {
+         return (inserted);
+      }
+
+
+
+      /*******************************************************************************
+       ** Add inserted
+       *******************************************************************************/
+      public void addInserted(long n)
+      {
+         inserted += n;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for updated
+       *******************************************************************************/
+      public long getUpdated()
+      {
+         return (updated);
+      }
+
+
+
+      /*******************************************************************************
+       ** Add updated
+       *******************************************************************************/
+      public void addUpdated(long n)
+      {
+         updated += n;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for unchanged
+       *******************************************************************************/
+      public long getUnchanged()
+      {
+         return (unchanged);
+      }
+
+
+
+      /*******************************************************************************
+       ** Add unchanged
+       *******************************************************************************/
+      public void addUnchanged(long n)
+      {
+         unchanged += n;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for skipped (INSERT_NEW rows that exist with different content)
+       *******************************************************************************/
+      public long getSkipped()
+      {
+         return (skipped);
+      }
+
+
+
+      /*******************************************************************************
+       ** Add skipped
+       *******************************************************************************/
+      public void addSkipped(long n)
+      {
+         skipped += n;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for deleted
+       *******************************************************************************/
+      public long getDeleted()
+      {
+         return (deleted);
+      }
+
+
+
+      /*******************************************************************************
+       ** Add deleted
+       *******************************************************************************/
+      public void addDeleted(long n)
+      {
+         deleted += n;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for conflicts (rows that collide on a unique key)
+       *******************************************************************************/
+      public long getConflicts()
+      {
+         return (conflicts);
+      }
+
+
+
+      /*******************************************************************************
+       ** Add conflicts
+       *******************************************************************************/
+      public void addConflicts(long n)
+      {
+         conflicts += n;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for orphans (rows whose parent is in neither the backup nor the target)
+       *******************************************************************************/
+      public long getOrphans()
+      {
+         return (orphans);
+      }
+
+
+
+      /*******************************************************************************
+       ** Add orphans
+       *******************************************************************************/
+      public void addOrphans(long n)
+      {
+         orphans += n;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for errored
+       *******************************************************************************/
+      public long getErrored()
+      {
+         return (errored);
+      }
+
+
+
+      /*******************************************************************************
+       ** Add errored
+       *******************************************************************************/
+      public void addErrored(long n)
+      {
+         errored += n;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for sequenceNeeded
+       *******************************************************************************/
+      public boolean getSequenceNeeded()
+      {
+         return (sequenceNeeded);
+      }
+
+
+
+      /*******************************************************************************
+       ** Setter for sequenceNeeded
+       *******************************************************************************/
+      public void setSequenceNeeded(boolean sequenceNeeded)
+      {
+         this.sequenceNeeded = sequenceNeeded;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for sequenceResynced
+       *******************************************************************************/
+      public boolean getSequenceResynced()
+      {
+         return (sequenceResynced);
+      }
+
+
+
+      /*******************************************************************************
+       ** Setter for sequenceResynced
+       *******************************************************************************/
+      public void setSequenceResynced(boolean sequenceResynced)
+      {
+         this.sequenceResynced = sequenceResynced;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for the number of updated records seen (the sample list is capped)
+       *******************************************************************************/
+      public long getUpdatedSampleTotal()
+      {
+         return (updatedSampleTotal);
+      }
+
+
+
+      /*******************************************************************************
+       ** Count one more changed record (sampled or not).
+       *******************************************************************************/
+      public void countChangedRecord()
+      {
+         updatedSampleTotal++;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for filesToRestore
+       *******************************************************************************/
+      public int getFilesToRestore()
+      {
+         return (filesToRestore);
+      }
+
+
+
+      /*******************************************************************************
+       ** Add filesToRestore
+       *******************************************************************************/
+      public void addFilesToRestore(int n)
+      {
+         filesToRestore += n;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for filesPresent
+       *******************************************************************************/
+      public int getFilesPresent()
+      {
+         return (filesPresent);
+      }
+
+
+
+      /*******************************************************************************
+       ** Add filesPresent
+       *******************************************************************************/
+      public void addFilesPresent(int n)
+      {
+         filesPresent += n;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for filesConflicting
+       *******************************************************************************/
+      public int getFilesConflicting()
+      {
+         return (filesConflicting);
+      }
+
+
+
+      /*******************************************************************************
+       ** Add filesConflicting
+       *******************************************************************************/
+      public void addFilesConflicting(int n)
+      {
+         filesConflicting += n;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for filesMissing (missing from the backup)
+       *******************************************************************************/
+      public int getFilesMissing()
+      {
+         return (filesMissing);
+      }
+
+
+
+      /*******************************************************************************
+       ** Add filesMissing
+       *******************************************************************************/
+      public void addFilesMissing(int n)
+      {
+         filesMissing += n;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for filesRestored
+       *******************************************************************************/
+      public int getFilesRestored()
+      {
+         return (filesRestored);
+      }
+
+
+
+      /*******************************************************************************
+       ** Add filesRestored
+       *******************************************************************************/
+      public void addFilesRestored(int n)
+      {
+         filesRestored += n;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for fileBytesRestored
+       *******************************************************************************/
+      public long getFileBytesRestored()
+      {
+         return (fileBytesRestored);
+      }
+
+
+
+      /*******************************************************************************
+       ** Add fileBytesRestored
+       *******************************************************************************/
+      public void addFileBytesRestored(long n)
+      {
+         fileBytesRestored += n;
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The outcome of one table, created on first use.
+    *******************************************************************************/
+   public TableOutcome table(String name, String targetName)
+   {
+      return (tables.computeIfAbsent(name, k -> new TableOutcome(name, targetName)));
+   }
+
+
+
+   /*******************************************************************************
+    ** The tables, in restore order.
+    *******************************************************************************/
+   public Map<String, TableOutcome> getTables()
+   {
+      return (tables);
+   }
+
+
+
+   /*******************************************************************************
+    ** Run-level warnings.
+    *******************************************************************************/
+   public List<String> getWarnings()
+   {
+      return (warnings);
+   }
+
+
+
+   /*******************************************************************************
+    ** Run-level errors (the restore does not run when there are any).
+    *******************************************************************************/
+   public List<String> getErrors()
+   {
+      return (errors);
+   }
+
+
+
+   /*******************************************************************************
+    ** Run-level informational notes.
+    *******************************************************************************/
+   public List<String> getNotes()
+   {
+      return (notes);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for preRestoreRunId
+    *******************************************************************************/
+   public Integer getPreRestoreRunId()
+   {
+      return (preRestoreRunId);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for preRestoreRunId
+    *******************************************************************************/
+   public void setPreRestoreRunId(Integer preRestoreRunId)
+   {
+      this.preRestoreRunId = preRestoreRunId;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for restoreRunId
+    *******************************************************************************/
+   public Integer getRestoreRunId()
+   {
+      return (restoreRunId);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for restoreRunId
+    *******************************************************************************/
+   public void setRestoreRunId(Integer restoreRunId)
+   {
+      this.restoreRunId = restoreRunId;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for sequencesResynced
+    *******************************************************************************/
+   public int getSequencesResynced()
+   {
+      return (sequencesResynced);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for sequencesResynced
+    *******************************************************************************/
+   public void setSequencesResynced(int sequencesResynced)
+   {
+      this.sequencesResynced = sequencesResynced;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for filesFailed
+    *******************************************************************************/
+   public int getFilesFailed()
+   {
+      return (filesFailed);
+   }
+
+
+
+   /*******************************************************************************
+    ** Add filesFailed
+    *******************************************************************************/
+   public void addFilesFailed(int n)
+   {
+      filesFailed += n;
+   }
+
+
+
+   /*******************************************************************************
+    ** A total over the tables.
+    *******************************************************************************/
+   public long sum(java.util.function.ToLongFunction<TableOutcome> getter)
+   {
+      return (tables.values().stream().mapToLong(getter).sum());
+   }
+}

src/main/java/com/kingsrook/qbits/backups/restore/RestoreRequest.java

@@ -0,0 +1,612 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.restore;
+
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.backups.files.FileReferenceProvider;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+
+
+/*******************************************************************************
+ ** Everything a restore needs to know (spec 9.3): the source run, the tables and
+ ** per-table filters, the target, the mode, how rows are matched, what happens to
+ ** ids, and the options.  Built from the first screen of the process.
+ *******************************************************************************/
+public class RestoreRequest
+{
+   public static final String MODE_INSERT_NEW = "INSERT_NEW";
+   public static final String MODE_UPSERT     = "UPSERT";
+   public static final String MODE_REPLACE    = "REPLACE";
+
+   public static final String IDS_PRESERVE = "PRESERVE";
+   public static final String IDS_REMAP    = "REMAP_NEW_IDS";
+
+   public static final String MATCH_PRIMARY_KEY = "PRIMARY_KEY";
+
+   private Integer             sourceRunId;
+   private List<String>        tables             = new ArrayList<>();
+   private Map<String, String> filters            = new LinkedHashMap<>();
+   private String              targetTable;
+   private String              mode               = MODE_INSERT_NEW;
+   private String              matchOn            = MATCH_PRIMARY_KEY;
+   private String              idStrategy         = IDS_PRESERVE;
+   private boolean             suppressAutomations = true;
+   private boolean             publishEvents      = false;
+   private boolean             runCustomizers     = false;
+   private boolean             perRecordAudit     = false;
+   private boolean             restoreFiles       = true;
+   private boolean             preRestoreBackup   = true;
+   private String              fileTargetBucketAlias;
+   private String              fileTargetPrefix;
+   private String              confirmationText;
+   private String              requestedBy        = "system";
+   private int                 pageSize           = 1000;
+   private List<FileReferenceProvider> fileProviders = new ArrayList<>(List.of(new FileReferenceProvider.FromTableMetaData()));
+   private RestoreWriter       writer             = new StandardRestoreWriter();
+
+
+
+   /*******************************************************************************
+    ** Build from the values of the first screen of the process.  The tables value is
+    ** a comma separated list (blank means every table in the backup); the filters
+    ** value is a JSON object of table name to query filter.
+    *******************************************************************************/
+   public static RestoreRequest fromInput(RunBackendStepInput input, Integer runId, List<String> forcedTables) throws com.kingsrook.qqq.backend.core.exceptions.QException
+   {
+      RestoreRequest request = new RestoreRequest();
+      request.sourceRunId = runId;
+      if(forcedTables != null && !forcedTables.isEmpty())
+      {
+         request.tables = new ArrayList<>(forcedTables);
+      }
+      else
+      {
+         request.tables = splitList(input.getValueString("tables"));
+      }
+      request.filters = parseFilters(input.getValueString("tableFilters"));
+      request.targetTable = blankToNull(input.getValueString("targetTable"));
+      request.mode = orDefault(input.getValueString("mode"), MODE_INSERT_NEW);
+      request.matchOn = orDefault(input.getValueString("matchOn"), MATCH_PRIMARY_KEY);
+      request.idStrategy = orDefault(input.getValueString("idStrategy"), IDS_PRESERVE);
+      request.suppressAutomations = bool(input, "suppressAutomations", true);
+      request.publishEvents = bool(input, "publishEvents", false);
+      request.runCustomizers = bool(input, "runCustomizers", false);
+      request.perRecordAudit = bool(input, "perRecordAudit", false);
+      request.restoreFiles = bool(input, "restoreFiles", true);
+      request.preRestoreBackup = bool(input, "preRestoreBackup", true);
+      request.fileTargetBucketAlias = blankToNull(input.getValueString("fileTargetBucketAlias"));
+      request.fileTargetPrefix = blankToNull(input.getValueString("fileTargetPrefix"));
+      request.confirmationText = input.getValueString("confirmationText");
+      com.kingsrook.qqq.backend.core.model.session.QSession session = com.kingsrook.qqq.backend.core.context.QContext.getQSession();
+      request.requestedBy = session == null || session.getUser() == null ? "system" : session.getUser().getIdReference();
+      return (request);
+   }
+
+
+
+   /*******************************************************************************
+    ** The text the user must type to confirm a REPLACE of these tables.
+    *******************************************************************************/
+   public static String expectedConfirmation(List<String> tables)
+   {
+      return (tables.size() == 1 ? tables.get(0) : "REPLACE " + tables.size() + " TABLES");
+   }
+
+
+
+   /*******************************************************************************
+    ** The filter json for a table, or null.
+    *******************************************************************************/
+   public String filterFor(String table)
+   {
+      return (filters.get(table));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static List<String> splitList(String text)
+   {
+      List<String> rs = new ArrayList<>();
+      if(StringUtils.hasContent(text))
+      {
+         for(String part : text.split(","))
+         {
+            if(!part.isBlank())
+            {
+               rs.add(part.trim());
+            }
+         }
+      }
+      return (rs);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static Map<String, String> parseFilters(String json) throws com.kingsrook.qqq.backend.core.exceptions.QException
+   {
+      Map<String, String> rs = new LinkedHashMap<>();
+      if(!StringUtils.hasContent(json))
+      {
+         return (rs);
+      }
+      try
+      {
+         com.fasterxml.jackson.databind.JsonNode node = new com.fasterxml.jackson.databind.ObjectMapper().readTree(json);
+         for(var it = node.fields(); it.hasNext(); )
+         {
+            var entry = it.next();
+            rs.put(entry.getKey(), entry.getValue().isTextual() ? entry.getValue().asText() : entry.getValue().toString());
+         }
+      }
+      catch(java.io.IOException e)
+      {
+         throw (new com.kingsrook.qqq.backend.core.exceptions.QException("The per-table filters are not valid JSON: " + e.getMessage()));
+      }
+      return (rs);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static boolean bool(RunBackendStepInput input, String name, boolean defaultValue)
+   {
+      Boolean value = input.getValueBoolean(name);
+      return (value == null ? defaultValue : value);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static String orDefault(String value, String defaultValue)
+   {
+      return (StringUtils.hasContent(value) ? value : defaultValue);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static String blankToNull(String value)
+   {
+      return (StringUtils.hasContent(value) ? value : null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for sourceRunId
+    *******************************************************************************/
+   public Integer getSourceRunId()
+   {
+      return (sourceRunId);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for sourceRunId
+    *******************************************************************************/
+   public RestoreRequest withSourceRunId(Integer sourceRunId)
+   {
+      this.sourceRunId = sourceRunId;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for tables (empty means every table in the backup)
+    *******************************************************************************/
+   public List<String> getTables()
+   {
+      return (tables);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for tables
+    *******************************************************************************/
+   public RestoreRequest withTables(List<String> tables)
+   {
+      this.tables = new ArrayList<>(tables);
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for filters
+    *******************************************************************************/
+   public Map<String, String> getFilters()
+   {
+      return (filters);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for one table filter (json of a QQueryFilter)
+    *******************************************************************************/
+   public RestoreRequest withFilter(String table, String filterJson)
+   {
+      this.filters.put(table, filterJson);
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for targetTable
+    *******************************************************************************/
+   public String getTargetTable()
+   {
+      return (targetTable);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for targetTable
+    *******************************************************************************/
+   public RestoreRequest withTargetTable(String targetTable)
+   {
+      this.targetTable = targetTable;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for mode
+    *******************************************************************************/
+   public String getMode()
+   {
+      return (mode);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for mode
+    *******************************************************************************/
+   public RestoreRequest withMode(String mode)
+   {
+      this.mode = mode;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for matchOn
+    *******************************************************************************/
+   public String getMatchOn()
+   {
+      return (matchOn);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for matchOn
+    *******************************************************************************/
+   public RestoreRequest withMatchOn(String matchOn)
+   {
+      this.matchOn = matchOn;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for idStrategy
+    *******************************************************************************/
+   public String getIdStrategy()
+   {
+      return (idStrategy);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for idStrategy
+    *******************************************************************************/
+   public RestoreRequest withIdStrategy(String idStrategy)
+   {
+      this.idStrategy = idStrategy;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for suppressAutomations
+    *******************************************************************************/
+   public boolean getSuppressAutomations()
+   {
+      return (suppressAutomations);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for suppressAutomations
+    *******************************************************************************/
+   public RestoreRequest withSuppressAutomations(boolean suppressAutomations)
+   {
+      this.suppressAutomations = suppressAutomations;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for publishEvents
+    *******************************************************************************/
+   public boolean getPublishEvents()
+   {
+      return (publishEvents);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for publishEvents
+    *******************************************************************************/
+   public RestoreRequest withPublishEvents(boolean publishEvents)
+   {
+      this.publishEvents = publishEvents;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for runCustomizers
+    *******************************************************************************/
+   public boolean getRunCustomizers()
+   {
+      return (runCustomizers);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for runCustomizers
+    *******************************************************************************/
+   public RestoreRequest withRunCustomizers(boolean runCustomizers)
+   {
+      this.runCustomizers = runCustomizers;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for perRecordAudit
+    *******************************************************************************/
+   public boolean getPerRecordAudit()
+   {
+      return (perRecordAudit);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for perRecordAudit
+    *******************************************************************************/
+   public RestoreRequest withPerRecordAudit(boolean perRecordAudit)
+   {
+      this.perRecordAudit = perRecordAudit;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for restoreFiles
+    *******************************************************************************/
+   public boolean getRestoreFiles()
+   {
+      return (restoreFiles);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for restoreFiles
+    *******************************************************************************/
+   public RestoreRequest withRestoreFiles(boolean restoreFiles)
+   {
+      this.restoreFiles = restoreFiles;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for preRestoreBackup
+    *******************************************************************************/
+   public boolean getPreRestoreBackup()
+   {
+      return (preRestoreBackup);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for preRestoreBackup
+    *******************************************************************************/
+   public RestoreRequest withPreRestoreBackup(boolean preRestoreBackup)
+   {
+      this.preRestoreBackup = preRestoreBackup;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for fileTargetBucketAlias
+    *******************************************************************************/
+   public String getFileTargetBucketAlias()
+   {
+      return (fileTargetBucketAlias);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for fileTargetBucketAlias
+    *******************************************************************************/
+   public RestoreRequest withFileTargetBucketAlias(String fileTargetBucketAlias)
+   {
+      this.fileTargetBucketAlias = fileTargetBucketAlias;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for fileTargetPrefix
+    *******************************************************************************/
+   public String getFileTargetPrefix()
+   {
+      return (fileTargetPrefix);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for fileTargetPrefix
+    *******************************************************************************/
+   public RestoreRequest withFileTargetPrefix(String fileTargetPrefix)
+   {
+      this.fileTargetPrefix = fileTargetPrefix;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for confirmationText
+    *******************************************************************************/
+   public String getConfirmationText()
+   {
+      return (confirmationText);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for confirmationText
+    *******************************************************************************/
+   public RestoreRequest withConfirmationText(String confirmationText)
+   {
+      this.confirmationText = confirmationText;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for requestedBy
+    *******************************************************************************/
+   public String getRequestedBy()
+   {
+      return (requestedBy);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for requestedBy
+    *******************************************************************************/
+   public RestoreRequest withRequestedBy(String requestedBy)
+   {
+      this.requestedBy = requestedBy;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for pageSize
+    *******************************************************************************/
+   public int getPageSize()
+   {
+      return (pageSize);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for pageSize
+    *******************************************************************************/
+   public RestoreRequest withPageSize(int pageSize)
+   {
+      this.pageSize = pageSize;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for fileProviders
+    *******************************************************************************/
+   public List<FileReferenceProvider> getFileProviders()
+   {
+      return (fileProviders);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for writer
+    *******************************************************************************/
+   public RestoreWriter getWriter()
+   {
+      return (writer);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for writer (tests, or a backend specific writer)
+    *******************************************************************************/
+   public RestoreRequest withWriter(RestoreWriter writer)
+   {
+      this.writer = writer;
+      return (this);
+   }
+}

src/main/java/com/kingsrook/qbits/backups/restore/RestoreSummaries.java

@@ -0,0 +1,222 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.restore;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLine;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLineInterface;
+import com.kingsrook.qqq.backend.core.model.actions.processes.Status;
+
+
+/*******************************************************************************
+ ** Turns a RestoreOutcome into the standard Review and Result summary lines
+ ** (spec 9.3).  One group of lines per table, in restore order.  Every line has
+ ** its future wording (Review) and its past wording (Result); sample diffs are
+ ** bullets on one line per table, with sensitive values already masked.
+ *******************************************************************************/
+public final class RestoreSummaries
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private RestoreSummaries()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** A line with all four wordings.
+    *******************************************************************************/
+   public static ProcessSummaryLine line(Status status, long count, String singularFuture, String pluralFuture, String singularPast, String pluralPast)
+   {
+      ProcessSummaryLine line = new ProcessSummaryLine(status, (int) Math.min(Integer.MAX_VALUE, count), null);
+      line.setSingularFutureMessage(singularFuture);
+      line.setPluralFutureMessage(pluralFuture);
+      line.setSingularPastMessage(singularPast);
+      line.setPluralPastMessage(pluralPast);
+      return (line);
+   }
+
+
+
+   /*******************************************************************************
+    ** A one-off message line (the same text before and after).
+    *******************************************************************************/
+   public static ProcessSummaryLine message(Status status, String text)
+   {
+      return (line(status, 1, text, text, text, text));
+   }
+
+
+
+   /*******************************************************************************
+    ** The lines of an outcome.
+    *******************************************************************************/
+   public static List<ProcessSummaryLineInterface> lines(RestoreOutcome outcome, boolean isResult)
+   {
+      List<ProcessSummaryLineInterface> lines = new ArrayList<>();
+
+      for(String error : outcome.getErrors())
+      {
+         lines.add(message(Status.ERROR, error));
+      }
+
+      for(RestoreOutcome.TableOutcome t : outcome.getTables().values())
+      {
+         tableLines(lines, t, isResult);
+      }
+
+      long sequences = outcome.sum(t -> t.getSequenceNeeded() ? 1 : 0);
+      if(sequences > 0 && !isResult)
+      {
+         lines.add(line(Status.INFO, sequences, "table will have its key sequence resynced", "tables will have their key sequences resynced",
+            "table had its key sequence resynced", "tables had their key sequences resynced"));
+      }
+      if(isResult && outcome.getSequencesResynced() > 0)
+      {
+         lines.add(line(Status.OK, outcome.getSequencesResynced(), "key sequence was resynced", "key sequences were resynced",
+            "key sequence was resynced", "key sequences were resynced"));
+      }
+      if(isResult && outcome.getPreRestoreRunId() != null)
+      {
+         lines.add(message(Status.INFO, "A backup of the target tables was taken first (backup run " + outcome.getPreRestoreRunId() + "), so this restore can be undone."));
+      }
+      if(isResult && outcome.getFilesFailed() > 0)
+      {
+         lines.add(line(Status.ERROR, outcome.getFilesFailed(), "file could not be restored", "files could not be restored", "file could not be restored", "files could not be restored"));
+      }
+
+      for(String warning : outcome.getWarnings())
+      {
+         lines.add(message(Status.WARNING, warning));
+      }
+      for(String note : outcome.getNotes())
+      {
+         lines.add(message(Status.INFO, note));
+      }
+      return (lines);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static void tableLines(List<ProcessSummaryLineInterface> lines, RestoreOutcome.TableOutcome t, boolean isResult)
+   {
+      String in = " " + t.getTargetName();
+
+      if("SKIPPED".equals(t.getStatus()))
+      {
+         lines.add(message(Status.ERROR, "The table " + t.getName() + " will not be restored: its schema does not fit the backup"));
+      }
+      for(String note : t.getSchemaNotes())
+      {
+         lines.add(message("MISMATCH".equals(t.getSchemaStatus()) ? Status.ERROR : Status.WARNING, "Schema of " + t.getName() + ": " + note));
+      }
+      for(String reference : t.getUnmappedReferences())
+      {
+         lines.add(message(Status.WARNING, "The field " + reference + " looks like a reference but cannot be traced, so it is not rewritten to the new ids"));
+      }
+
+      add(lines, line(Status.OK, t.getInserted(), "record will be inserted into" + in, "records will be inserted into" + in,
+         "record was inserted into" + in, "records were inserted into" + in));
+      add(lines, line(Status.OK, t.getUpdated(), "record will be updated in" + in, "records will be updated in" + in,
+         "record was updated in" + in, "records were updated in" + in));
+      add(lines, line(Status.INFO, t.getUnchanged(), "record is unchanged in" + in, "records are unchanged in" + in,
+         "record was already the same in" + in, "records were already the same in" + in));
+      add(lines, line(Status.INFO, t.getSkipped(), "record exists with different content and will be left alone in" + in,
+         "records exist with different content and will be left alone in" + in,
+         "record existed with different content and was left alone in" + in, "records existed with different content and were left alone in" + in));
+      add(lines, line(Status.WARNING, t.getDeleted(), "record will be deleted from" + in + " (REPLACE)", "records will be deleted from" + in + " (REPLACE)",
+         "record was deleted from" + in + " (REPLACE)", "records were deleted from" + in + " (REPLACE)"));
+      add(lines, line(Status.WARNING, t.getConflicts(), "record conflicts on a unique key in" + in + " and will be skipped",
+         "records conflict on a unique key in" + in + " and will be skipped",
+         "record conflicted on a unique key in" + in + " and was skipped", "records conflicted on a unique key in" + in + " and were skipped"));
+      add(lines, line(Status.WARNING, t.getOrphans(), "record in" + in + " references a parent that is missing from the backup and the target",
+         "records in" + in + " reference a parent that is missing from the backup and the target",
+         "record in" + in + " referenced a parent that is missing from the backup and the target",
+         "records in" + in + " referenced a parent that is missing from the backup and the target"));
+      if(isResult)
+      {
+         add(lines, line(Status.ERROR, t.getErrored(), "record could not be written to" + in, "records could not be written to" + in,
+            "record could not be written to" + in, "records could not be written to" + in));
+         for(String problem : t.getProblems())
+         {
+            lines.add(message(Status.ERROR, problem));
+         }
+      }
+
+      fileLines(lines, t, isResult);
+
+      if(!t.getSamples().isEmpty() && !isResult)
+      {
+         ProcessSummaryLine sample = line(Status.INFO, t.getSamples().size(),
+            "changed record in" + in + " (field: now -> from the backup; sensitive values are hidden)",
+            "changed records in" + in + " (field: now -> from the backup; sensitive values are hidden)", "", "");
+         ArrayList<String> bullets = new ArrayList<>();
+         for(RestoreOutcome.Sample s : t.getSamples())
+         {
+            bullets.add("#" + s.key() + "  " + String.join("; ", s.changes()));
+         }
+         sample.setBulletsOfText(bullets);
+         lines.add(sample);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static void fileLines(List<ProcessSummaryLineInterface> lines, RestoreOutcome.TableOutcome t, boolean isResult)
+   {
+      String in = " for" + " " + t.getTargetName();
+      if(isResult)
+      {
+         add(lines, line(Status.OK, t.getFilesRestored(), "file was restored" + in, "files were restored" + in, "file was restored" + in, "files were restored" + in));
+      }
+      else
+      {
+         add(lines, line(Status.OK, t.getFilesToRestore(), "file will be restored" + in, "files will be restored" + in, "file was restored" + in, "files were restored" + in));
+      }
+      add(lines, line(Status.INFO, t.getFilesPresent(), "file is already there with the same checksum" + in + " and is skipped",
+         "files are already there with the same checksum" + in + " and are skipped",
+         "file was already there with the same checksum" + in, "files were already there with the same checksum" + in));
+      add(lines, line(Status.WARNING, t.getFilesConflicting(), "file exists with different content" + in + " (kept, unless the mode is REPLACE)",
+         "files exist with different content" + in + " (kept, unless the mode is REPLACE)",
+         "file existed with different content" + in, "files existed with different content" + in));
+      add(lines, line(Status.WARNING, t.getFilesMissing(), "file is missing from the backup" + in, "files are missing from the backup" + in,
+         "file was missing from the backup" + in, "files were missing from the backup" + in));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static void add(List<ProcessSummaryLineInterface> lines, ProcessSummaryLine line)
+   {
+      if(line.getCount() != null && line.getCount() > 0)
+      {
+         lines.add(line);
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/backups/restore/RestoreWriter.java

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.restore;
+
+
+import java.io.Serializable;
+import java.util.Collection;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** How a restore writes (spec 5.3 and 5.4).  The default implementation uses the
+ ** plain Insert, Update and Delete actions, and selects the core RestoreWriteFlag
+ ** (QRun-IO/qqq#1111) and the core key-sequence resync (#1112) reflectively when the
+ ** running QQQ has them.  A backend specific writer can be supplied on the request.
+ **
+ ** Whatever the implementation, record security, field security, unique keys and
+ ** required-field validation still apply to every write.
+ *******************************************************************************/
+public interface RestoreWriter
+{
+   /*******************************************************************************
+    ** Insert records (restore mode).  Returns the output records, with any errors.
+    *******************************************************************************/
+   List<QRecord> insert(QTableMetaData table, List<QRecord> records, RestoreRequest options, QBackendTransaction transaction) throws QException;
+
+
+
+   /*******************************************************************************
+    ** Update records (restore mode).  Returns the output records, with any errors.
+    *******************************************************************************/
+   List<QRecord> update(QTableMetaData table, List<QRecord> records, RestoreRequest options, QBackendTransaction transaction) throws QException;
+
+
+
+   /*******************************************************************************
+    ** Delete records by primary key (REPLACE).  Returns the number deleted.
+    *******************************************************************************/
+   long delete(QTableMetaData table, List<Serializable> primaryKeys, RestoreRequest options, QBackendTransaction transaction) throws QException;
+
+
+
+   /*******************************************************************************
+    ** Whether the writes honor the core restore flag (so created and modified dates
+    ** are kept as supplied).
+    *******************************************************************************/
+   boolean usesCoreRestoreFlag();
+
+
+
+   /*******************************************************************************
+    ** Whether key sequences can be resynced on this QQQ (the core hook is present).
+    *******************************************************************************/
+   boolean canResyncSequences();
+
+
+
+   /*******************************************************************************
+    ** Resync key sequences after explicit-id inserts.  Returns the names of the tables
+    ** whose sequence was advanced.
+    *******************************************************************************/
+   List<String> resyncSequences(Collection<QTableMetaData> tables) throws QException;
+}

src/main/java/com/kingsrook/qbits/backups/restore/StandardRestoreWriter.java

@@ -0,0 +1,257 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.restore;
+
+
+import java.io.Serializable;
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
+import com.kingsrook.qqq.backend.core.actions.tables.DeleteAction;
+import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
+import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.tables.ActionFlag;
+import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteOutput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QBackendMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.modules.backend.QBackendModuleDispatcher;
+import com.kingsrook.qqq.backend.core.modules.backend.QBackendModuleInterface;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+/*******************************************************************************
+ ** The default RestoreWriter: the standard Insert, Update and Delete actions.
+ **
+ ** Stand-ins (replace with the core API when QQQ 4.1.0-RC.5 ships):
+ ** <ul>
+ ** <li>RestoreWriteFlag (QRun-IO/qqq#1111) is created reflectively when the class is
+ ** present.  Without it, the DML audit is omitted (a summary audit is written per
+ ** table instead), but created and modified dates may be set by the normal defaults.</li>
+ ** <li>resyncKeySequences (QRun-IO/qqq#1112) is called reflectively on the backend
+ ** module when it exists; otherwise it is a no-op that the Review reports.</li>
+ ** </ul>
+ *******************************************************************************/
+public class StandardRestoreWriter implements RestoreWriter
+{
+   private static final QLogger LOG = QLogger.getLogger(StandardRestoreWriter.class);
+
+   private static final String FLAG_CLASS = "com.kingsrook.qqq.backend.core.model.actions.tables.RestoreWriteFlag";
+
+   private static final Class<?> FLAG = lookup(FLAG_CLASS);
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static Class<?> lookup(String name)
+   {
+      try
+      {
+         return (Class.forName(name));
+      }
+      catch(ClassNotFoundException | LinkageError e)
+      {
+         return (null);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public List<QRecord> insert(QTableMetaData table, List<QRecord> records, RestoreRequest options, QBackendTransaction transaction) throws QException
+   {
+      InsertInput input = new InsertInput(table.getName());
+      input.setRecords(records);
+      input.setOmitDmlAudit(!options.getPerRecordAudit());
+      if(transaction != null)
+      {
+         input.setTransaction(transaction);
+      }
+      addFlag(options, input::withFlag);
+      return (new InsertAction().execute(input).getRecords());
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public List<QRecord> update(QTableMetaData table, List<QRecord> records, RestoreRequest options, QBackendTransaction transaction) throws QException
+   {
+      UpdateInput input = new UpdateInput(table.getName());
+      input.setRecords(records);
+      input.setOmitDmlAudit(!options.getPerRecordAudit());
+      if(transaction != null)
+      {
+         input.setTransaction(transaction);
+      }
+      addFlag(options, input::withFlag);
+      return (new UpdateAction().execute(input).getRecords());
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public long delete(QTableMetaData table, List<Serializable> primaryKeys, RestoreRequest options, QBackendTransaction transaction) throws QException
+   {
+      DeleteInput input = new DeleteInput(table.getName());
+      input.setPrimaryKeys(primaryKeys);
+      input.setOmitDmlAudit(!options.getPerRecordAudit());
+      if(transaction != null)
+      {
+         input.setTransaction(transaction);
+      }
+      addFlag(options, input::withFlag);
+      DeleteOutput output = new DeleteAction().execute(input);
+      if(output.getRecordsWithErrors() != null && !output.getRecordsWithErrors().isEmpty())
+      {
+         QRecord first = output.getRecordsWithErrors().get(0);
+         throw (new QException("Could not delete " + output.getRecordsWithErrors().size() + " records of " + table.getName() + ": "
+            + (first.getErrors().isEmpty() ? "unknown error" : first.getErrors().get(0).getMessage())));
+      }
+      return (output.getDeletedRecordCount());
+   }
+
+
+
+   /*******************************************************************************
+    ** Create the core flag (when the running QQQ has it) and hand it to the input.
+    *******************************************************************************/
+   private void addFlag(RestoreRequest options, java.util.function.Consumer<ActionFlag> sink) throws QException
+   {
+      if(FLAG == null)
+      {
+         return;
+      }
+      try
+      {
+         Object flag = FLAG.getDeclaredConstructor().newInstance();
+         FLAG.getMethod("withSuppressAutomations", boolean.class).invoke(flag, options.getSuppressAutomations());
+         FLAG.getMethod("withRunCustomizers", boolean.class).invoke(flag, options.getRunCustomizers());
+         FLAG.getMethod("withPerRecordAudit", boolean.class).invoke(flag, options.getPerRecordAudit());
+         FLAG.getMethod("withPublishEvents", boolean.class).invoke(flag, options.getPublishEvents());
+         sink.accept((ActionFlag) flag);
+      }
+      catch(ReflectiveOperationException | ClassCastException e)
+      {
+         throw (new QException("Could not use the core restore flag: " + e.getMessage(), e));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public boolean usesCoreRestoreFlag()
+   {
+      return (FLAG != null);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public boolean canResyncSequences()
+   {
+      return (resyncMethod() != null);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static Method resyncMethod()
+   {
+      try
+      {
+         return (QBackendModuleInterface.class.getMethod("resyncKeySequences", QBackendMetaData.class, Collection.class));
+      }
+      catch(NoSuchMethodException | LinkageError e)
+      {
+         return (null);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public List<String> resyncSequences(Collection<QTableMetaData> tables) throws QException
+   {
+      Method method = resyncMethod();
+      if(method == null)
+      {
+         return (List.of());
+      }
+
+      Map<String, List<QTableMetaData>> byBackend = new LinkedHashMap<>();
+      for(QTableMetaData table : tables)
+      {
+         byBackend.computeIfAbsent(table.getBackendName(), k -> new ArrayList<>()).add(table);
+      }
+
+      List<String> resynced = new ArrayList<>();
+      for(Map.Entry<String, List<QTableMetaData>> entry : byBackend.entrySet())
+      {
+         QBackendMetaData backend = QContext.getQInstance().getBackend(entry.getKey());
+         try
+         {
+            QBackendModuleInterface module = new QBackendModuleDispatcher().getQBackendModule(backend);
+            for(Object result : (List<?>) method.invoke(module, backend, entry.getValue()))
+            {
+               Object status = result.getClass().getMethod("getStatus").invoke(result);
+               if("RESYNCED".equals(String.valueOf(status)))
+               {
+                  resynced.add(String.valueOf(result.getClass().getMethod("getTableName").invoke(result)));
+               }
+            }
+         }
+         catch(ReflectiveOperationException e)
+         {
+            LOG.warn("Could not resync key sequences", e, logPair("backend", entry.getKey()));
+            throw (new QException("Could not resync key sequences on backend " + entry.getKey() + ": " + e.getMessage(), e));
+         }
+      }
+      return (resynced);
+   }
+}

src/main/java/com/kingsrook/qbits/backups/run/BackupEngine.java

@@ -35,6 +35,7 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 import com.kingsrook.qbits.backups.BackupsRuntime;
 import com.kingsrook.qbits.backups.alerts.BackupAlertSink;
 import com.kingsrook.qbits.backups.codec.HashingOutputStream;
+import com.kingsrook.qbits.backups.events.BackupEvents;
 import com.kingsrook.qbits.backups.codec.TableArtifactWriter;
 import com.kingsrook.qbits.backups.files.FileCopier;
 import com.kingsrook.qbits.backups.files.FileReference;
@@ -561,6 +562,7 @@ public class BackupEngine
 
       BackupAlertSink sink = BackupsRuntime.getAlertSink();
       String planKey = request.getSettings().planKey();
+      BackupEvents.runFinished(planKey, result.getRunKey(), status, result.getRows(), result.getBytesStored());
       if(ok)
       {
          sink.resolve("backups.run.failed", "backups.run.failed:" + planKey);

src/main/java/com/kingsrook/qbits/backups/sla/SlaChecker.java

@@ -0,0 +1,543 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.sla;
+
+
+import java.io.Serializable;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+import com.kingsrook.qbits.backups.BackupsQBitConfig;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.alerts.BackupAlertSink;
+import com.kingsrook.qbits.backups.alerts.BackupAlerts;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qbits.backups.storage.BackupStorage;
+import com.kingsrook.qbits.backups.storage.StoredObjectInfo;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+/*******************************************************************************
+ ** The SLA checker (design spec section 10.2): backupCheckSla.  A scheduled process
+ ** that is independent of the backup trigger, so a broken trigger cannot also
+ ** silence the check.  For each active plan it computes slaStatus:
+ ** <ul>
+ **    <li>MISSING_IN_STORAGE: the catalog says success but the manifest is gone
+ **    (a head on manifestKey, a positive answer cached for an hour);</li>
+ **    <li>FAILING: the last two finished runs failed;</li>
+ **    <li>ABANDONED: a RUNNING run has a heartbeat older than ten minutes (the run
+ **    is marked ABANDONED);</li>
+ **    <li>LATE: no success within slaHours;</li>
+ **    <li>OWNER_INVALID: the plan owner no longer validates (the configured
+ **    planOwnerValidator);</li>
+ **    <li>UNVERIFIED: no passed CONTENT or TEST_RESTORE verification within
+ **    verifySlaDays;</li>
+ **    <li>OK otherwise (UNKNOWN for a new plan that has not had time to run yet).</li>
+ ** </ul>
+ ** When several apply, the status shown is the first in that order; the alerts are
+ ** independent, one per condition.  Once a day it also lists each plan's prefix in
+ ** the bucket and reports orphans (run prefixes that are not in the catalog) and
+ ** debris (prefixes with no manifest older than 24 hours): look at the bucket, not
+ ** at the job.
+ *******************************************************************************/
+public class SlaChecker
+{
+   private static final QLogger LOG = QLogger.getLogger(SlaChecker.class);
+
+   public static final String OK                 = "OK";
+   public static final String LATE               = "LATE";
+   public static final String FAILING            = "FAILING";
+   public static final String MISSING_IN_STORAGE = "MISSING_IN_STORAGE";
+   public static final String UNVERIFIED         = "UNVERIFIED";
+   public static final String ABANDONED          = "ABANDONED";
+   public static final String OWNER_INVALID      = "OWNER_INVALID";
+   public static final String UNKNOWN            = "UNKNOWN";
+
+   /** A RUNNING run whose heartbeat is older than this is abandoned. */
+   public static final Duration STALE_HEARTBEAT = Duration.ofMinutes(10);
+
+   /** How long a successful manifest head is trusted. */
+   public static final Duration MANIFEST_CACHE = Duration.ofHours(1);
+
+   /** How often the bucket is listed for orphans and debris. */
+   public static final Duration BUCKET_AUDIT_INTERVAL = Duration.ofHours(24);
+
+   /** A prefix with no manifest older than this is debris. */
+   public static final Duration DEBRIS_AGE = Duration.ofHours(24);
+
+   private static final Set<String> FAILED_STATUSES   = Set.of("FAILED", "TIMED_OUT", "ABANDONED");
+   private static final Set<String> FINISHED_STATUSES = Set.of("SUCCEEDED", "SUCCEEDED_WITH_WARNINGS", "FAILED", "TIMED_OUT", "ABANDONED");
+
+   private static final Map<String, Instant> MANIFEST_OK_AT = new ConcurrentHashMap<>();
+   private static final Map<String, Instant> LAST_AUDIT_AT  = new ConcurrentHashMap<>();
+
+   private final BackupCatalog catalog = new BackupCatalog();
+
+
+
+   /***************************************************************************
+    ** The outcome of checking one plan.
+    **
+    ** @param planId the plan id
+    ** @param planKey the plan key
+    ** @param previousStatus slaStatus before the check
+    ** @param status slaStatus now
+    ** @param abandonedRuns runs marked ABANDONED by this check
+    ** @param orphans orphan run prefixes found by the bucket audit (-1 when the audit did not run)
+    ** @param debris debris prefixes found by the bucket audit (-1 when the audit did not run)
+    ***************************************************************************/
+   public record PlanResult(Integer planId, String planKey, String previousStatus, String status, int abandonedRuns, int orphans, int debris)
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Forget the cached manifest heads and bucket audit times (tests).
+    *******************************************************************************/
+   public static void resetCaches()
+   {
+      MANIFEST_OK_AT.clear();
+      LAST_AUDIT_AT.clear();
+   }
+
+
+
+   /*******************************************************************************
+    ** Check every active plan.
+    *******************************************************************************/
+   public List<PlanResult> checkAll() throws QException
+   {
+      List<PlanResult> results = new ArrayList<>();
+      for(QRecord plan : catalog.query(BackupsTables.PLAN, new QQueryFilter(new QFilterCriteria("isActive", QCriteriaOperator.EQUALS, true))))
+      {
+         try
+         {
+            results.add(check(plan));
+         }
+         catch(Exception e)
+         {
+            LOG.warn("The SLA check of a plan failed", e, logPair("plan", plan.getValueString("planKey")));
+         }
+      }
+      return (results);
+   }
+
+
+
+   /*******************************************************************************
+    ** Check one plan: mark stale runs, compute the status, update the plan, raise and
+    ** resolve alerts, and (once a day) audit its prefix in the bucket.
+    *******************************************************************************/
+   public PlanResult check(QRecord plan) throws QException
+   {
+      Instant now     = BackupsRuntime.getClock().instant();
+      Integer planId  = plan.getValueInteger("id");
+      String  planKey = plan.getValueString("planKey");
+      boolean critical = Boolean.TRUE.equals(plan.getValueBoolean("critical"));
+
+      List<QRecord> runs = catalog.where(BackupsTables.RUN, "backupPlanId", planId);
+
+      /////////////////////////////////////////////////////////////////////
+      // a RUNNING run that stopped reporting is abandoned (pod died etc) //
+      /////////////////////////////////////////////////////////////////////
+      int abandonedNow = 0;
+      for(QRecord run : runs)
+      {
+         if("RUNNING".equals(run.getValueString("status")))
+         {
+            Instant lastSeen = run.getValueInstant("heartbeatDate") != null ? run.getValueInstant("heartbeatDate") : run.getValueInstant("startDate");
+            if(lastSeen != null && lastSeen.isBefore(now.minus(STALE_HEARTBEAT)))
+            {
+               Map<String, Serializable> update = new LinkedHashMap<>();
+               update.put("status", "ABANDONED");
+               update.put("endDate", now);
+               update.put("errorMessage", "The run stopped reporting a heartbeat (the process or pod probably died); resume it or run the plan again");
+               catalog.update(BackupsTables.RUN, run.getValueInteger("id"), update);
+               abandonedNow++;
+            }
+         }
+      }
+      if(abandonedNow > 0)
+      {
+         runs = catalog.where(BackupsTables.RUN, "backupPlanId", planId);
+      }
+
+      List<QRecord> finished = runs.stream().filter(r -> FINISHED_STATUSES.contains(r.getValueString("status"))).toList();
+      boolean latestFailed   = !finished.isEmpty() && FAILED_STATUSES.contains(finished.get(0).getValueString("status"));
+      boolean failing        = finished.size() >= 2 && latestFailed && FAILED_STATUSES.contains(finished.get(1).getValueString("status"));
+      boolean abandoned      = abandonedNow > 0 || (!finished.isEmpty() && "ABANDONED".equals(finished.get(0).getValueString("status")));
+
+      boolean missing    = isManifestMissing(plan, now);
+      boolean late       = isLate(plan, now);
+      boolean ownerBad   = isOwnerInvalid(plan);
+      boolean unverified = isUnverified(plan, now);
+
+      String status;
+      if(missing)
+      {
+         status = MISSING_IN_STORAGE;
+      }
+      else if(failing)
+      {
+         status = FAILING;
+      }
+      else if(abandoned)
+      {
+         status = ABANDONED;
+      }
+      else if(late)
+      {
+         status = LATE;
+      }
+      else if(ownerBad)
+      {
+         status = OWNER_INVALID;
+      }
+      else if(unverified)
+      {
+         status = UNVERIFIED;
+      }
+      else if(plan.getValueInstant("lastSuccessDate") == null)
+      {
+         status = UNKNOWN;
+      }
+      else
+      {
+         status = OK;
+      }
+
+      String previous = plan.getValueString("slaStatus");
+      if(!status.equals(previous))
+      {
+         catalog.update(BackupsTables.PLAN, planId, Map.of("slaStatus", status));
+      }
+
+      signal(plan, planKey, critical, missing, late, ownerBad, unverified, latestFailed, failing, abandoned, finished.isEmpty() ? null : finished.get(0));
+
+      int[] audit = auditBucket(plan, planKey, runs, now);
+      return (new PlanResult(planId, planKey, previous, status, abandonedNow, audit[0], audit[1]));
+   }
+
+
+
+   /*******************************************************************************
+    ** Raise and resolve the plan's alerts, one per condition.
+    *******************************************************************************/
+   private void signal(QRecord plan, String planKey, boolean critical, boolean missing, boolean late, boolean ownerBad, boolean unverified,
+                       boolean latestFailed, boolean failing, boolean abandoned, QRecord latestFinished)
+   {
+      String name = plan.getValueString("name") == null ? planKey : plan.getValueString("name");
+
+      if(missing)
+      {
+         BackupAlerts.raise(BackupAlerts.RUN_MISSING, planKey, BackupAlertSink.Severity.CRITICAL, "The latest backup is missing from storage",
+            "plan", planKey, "planName", name);
+      }
+      else
+      {
+         BackupAlerts.resolve(BackupAlerts.RUN_MISSING, planKey);
+      }
+
+      if(late)
+      {
+         BackupAlerts.raise(BackupAlerts.PLAN_MISSED, planKey, critical ? BackupAlertSink.Severity.CRITICAL : BackupAlertSink.Severity.ERROR,
+            "A backup did not run in time", "plan", planKey, "planName", name, "slaHours", String.valueOf(slaHours(plan)));
+      }
+      else
+      {
+         BackupAlerts.resolve(BackupAlerts.PLAN_MISSED, planKey);
+      }
+
+      if(latestFailed || abandoned)
+      {
+         BackupAlerts.raise(BackupAlerts.RUN_FAILED, planKey, failing ? BackupAlertSink.Severity.ERROR : BackupAlertSink.Severity.WARNING,
+            failing ? "Backups have failed twice in a row" : "A backup run failed", "plan", planKey, "planName", name);
+      }
+      else if(latestFinished != null)
+      {
+         BackupAlerts.resolve(BackupAlerts.RUN_FAILED, planKey);
+      }
+
+      if(ownerBad)
+      {
+         BackupAlerts.raise(BackupAlerts.PLAN_OWNER_INVALID, planKey, BackupAlertSink.Severity.WARNING, "The backup plan owner is not valid",
+            "plan", planKey, "planName", name);
+      }
+      else
+      {
+         BackupAlerts.resolve(BackupAlerts.PLAN_OWNER_INVALID, planKey);
+      }
+
+      if(unverified)
+      {
+         BackupAlerts.raise(BackupAlerts.VERIFY_OVERDUE, planKey, BackupAlertSink.Severity.WARNING, "No backup has been verified recently",
+            "plan", planKey, "planName", name, "verifySlaDays", String.valueOf(plan.getValueInteger("verifySlaDays")));
+      }
+      else
+      {
+         BackupAlerts.resolve(BackupAlerts.VERIFY_OVERDUE, planKey);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The catalog says the last success exists; is its manifest still in the bucket?
+    ** A positive answer is trusted for an hour; a negative one is always re-checked.
+    ** A storage that cannot be reached does not mean the manifest is gone.
+    *******************************************************************************/
+   private boolean isManifestMissing(QRecord plan, Instant now) throws QException
+   {
+      Integer successId = plan.getValueInteger("lastSuccessRunId");
+      if(successId == null)
+      {
+         return (false);
+      }
+      QRecord run = catalog.get(BackupsTables.RUN, successId).orElse(null);
+      if(run == null || run.getValueString("manifestKey") == null || run.getValueString("storageBucketAlias") == null || run.getValueInstant("prunedDate") != null)
+      {
+         return (false);
+      }
+
+      String  cacheKey = run.getValueString("storageBucketAlias") + "|" + run.getValueString("manifestKey");
+      Instant okAt     = MANIFEST_OK_AT.get(cacheKey);
+      if(okAt != null && okAt.plus(MANIFEST_CACHE).isAfter(now))
+      {
+         return (false);
+      }
+
+      try
+      {
+         BackupStorage storage = BackupsRuntime.storageFor(run.getValueString("storageBucketAlias"));
+         if(storage.head(run.getValueString("manifestKey")).isPresent())
+         {
+            MANIFEST_OK_AT.put(cacheKey, now);
+            return (false);
+         }
+         MANIFEST_OK_AT.remove(cacheKey);
+         return (true);
+      }
+      catch(RuntimeException e)
+      {
+         LOG.warn("Could not check the manifest of the last backup", e, logPair("plan", plan.getValueString("planKey")));
+         return (false);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** No success within slaHours.  A manual-only plan (no cron) with no slaHours has
+    ** no SLA.  A new plan gets slaHours to run its first backup.
+    *******************************************************************************/
+   private boolean isLate(QRecord plan, Instant now)
+   {
+      Integer hours = slaHours(plan);
+      if(hours == null)
+      {
+         return (false);
+      }
+      Instant lastSuccess = plan.getValueInstant("lastSuccessDate");
+      Instant reference   = lastSuccess != null ? lastSuccess : plan.getValueInstant("createDate");
+      return (reference != null && reference.plus(Duration.ofHours(hours)).isBefore(now));
+   }
+
+
+
+   /*******************************************************************************
+    ** slaHours of a plan: its value, else 26 for a scheduled plan, else none.
+    *******************************************************************************/
+   private Integer slaHours(QRecord plan)
+   {
+      if(plan.getValueInteger("slaHours") != null)
+      {
+         return (plan.getValueInteger("slaHours"));
+      }
+      String cron = plan.getValueString("cronExpression");
+      return (cron != null && !cron.isBlank() ? 26 : null);
+   }
+
+
+
+   /*******************************************************************************
+    ** The plan has a successful backup but no passed CONTENT or TEST_RESTORE
+    ** verification within verifySlaDays.
+    *******************************************************************************/
+   private boolean isUnverified(QRecord plan, Instant now)
+   {
+      Integer days = plan.getValueInteger("verifySlaDays");
+      if(days == null || plan.getValueInstant("lastSuccessDate") == null)
+      {
+         return (false);
+      }
+      Instant reference = plan.getValueInstant("lastVerifiedDate") != null ? plan.getValueInstant("lastVerifiedDate") : plan.getValueInstant("createDate");
+      return (reference != null && reference.plus(Duration.ofDays(days)).isBefore(now));
+   }
+
+
+
+   /*******************************************************************************
+    ** The plan owner no longer validates.
+    *******************************************************************************/
+   private boolean isOwnerInvalid(QRecord plan)
+   {
+      BackupsQBitConfig config = BackupsRuntime.getConfig();
+      String            owner  = plan.getValueString("ownerUserId");
+      if(config == null || config.getPlanOwnerValidator() == null || owner == null || owner.isBlank())
+      {
+         return (false);
+      }
+      try
+      {
+         return (!config.getPlanOwnerValidator().test(owner));
+      }
+      catch(RuntimeException e)
+      {
+         LOG.warn("The plan owner validator failed", e, logPair("plan", plan.getValueString("planKey")));
+         return (false);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Once a day, list the plan's prefix in the bucket: orphans (run prefixes not in
+    ** the catalog) and debris (no manifest, older than 24 hours).  Returns
+    * {orphans, debris}, or {-1, -1} when it did not run.
+    *******************************************************************************/
+   private int[] auditBucket(QRecord plan, String planKey, List<QRecord> runs, Instant now)
+   {
+      String alias = plan.getValueString("storageBucketAlias");
+      if(alias == null)
+      {
+         return (new int[] { -1, -1 });
+      }
+      String  auditKey = alias + "|" + planKey;
+      Instant last     = LAST_AUDIT_AT.get(auditKey);
+      if(last != null && last.plus(BUCKET_AUDIT_INTERVAL).isAfter(now))
+      {
+         return (new int[] { -1, -1 });
+      }
+
+      try
+      {
+         BackupStorage storage    = BackupsRuntime.storageFor(alias);
+         String        planPrefix = planPrefix(plan, planKey);
+
+         Set<String> known  = new HashSet<>();
+         Set<String> active = new HashSet<>();
+         for(QRecord run : runs)
+         {
+            known.add(run.getValueString("runPrefix"));
+            if("RUNNING".equals(run.getValueString("status")) || "QUEUED".equals(run.getValueString("status")))
+            {
+               active.add(run.getValueString("runPrefix"));
+            }
+         }
+
+         Map<String, Boolean> hasManifest = new LinkedHashMap<>();
+         Map<String, Instant> newest      = new LinkedHashMap<>();
+         for(StoredObjectInfo object : storage.list(planPrefix))
+         {
+            String[] parts = object.key().substring(planPrefix.length()).split("/");
+            if(parts.length < 5)
+            {
+               continue;
+            }
+            String runPrefix = planPrefix + parts[0] + "/" + parts[1] + "/" + parts[2] + "/" + parts[3] + "/";
+            hasManifest.merge(runPrefix, "manifest.json".equals(parts[4]), Boolean::logicalOr);
+            if(object.lastModified() != null)
+            {
+               newest.merge(runPrefix, object.lastModified(), (a, b) -> a.isAfter(b) ? a : b);
+            }
+         }
+
+         int orphans = 0;
+         int debris  = 0;
+         for(Map.Entry<String, Boolean> entry : hasManifest.entrySet())
+         {
+            String runPrefix = entry.getKey();
+            if(active.contains(runPrefix))
+            {
+               continue;
+            }
+            if(!known.contains(runPrefix))
+            {
+               orphans++;
+            }
+            Instant modified = newest.get(runPrefix);
+            if(!entry.getValue() && modified != null && modified.plus(DEBRIS_AGE).isBefore(now))
+            {
+               debris++;
+            }
+         }
+
+         LAST_AUDIT_AT.put(auditKey, now);
+         if(orphans + debris > 0)
+         {
+            BackupAlerts.raise(BackupAlerts.STORAGE_DEBRIS, planKey, BackupAlertSink.Severity.INFO, "Backup storage has orphans or debris",
+               "plan", planKey, "orphans", String.valueOf(orphans), "debris", String.valueOf(debris));
+         }
+         else
+         {
+            BackupAlerts.resolve(BackupAlerts.STORAGE_DEBRIS, planKey);
+         }
+         return (new int[] { orphans, debris });
+      }
+      catch(RuntimeException e)
+      {
+         LOG.warn("The bucket audit failed", e, logPair("plan", planKey));
+         return (new int[] { -1, -1 });
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The prefix of a plan's runs in its bucket, the same way the backup engine
+    ** builds it: (plan prefix)/(instance name)/(planKey)/.
+    *******************************************************************************/
+   static String planPrefix(QRecord plan, String planKey)
+   {
+      BackupsQBitConfig config   = BackupsRuntime.getConfig();
+      String            instance = config != null && config.getInstanceName() != null ? config.getInstanceName() : "qqq";
+      String            prefix   = plan.getValueString("prefix") != null ? plan.getValueString("prefix") : "qqq-backups";
+      while(prefix.startsWith("/"))
+      {
+         prefix = prefix.substring(1);
+      }
+      while(prefix.endsWith("/"))
+      {
+         prefix = prefix.substring(0, prefix.length() - 1);
+      }
+      return (prefix + "/" + instance + "/" + planKey + "/");
+   }
+}

src/main/java/com/kingsrook/qbits/backups/verify/BackupVerifier.java

@@ -0,0 +1,630 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.verify;
+
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.io.Serializable;
+import java.security.DigestInputStream;
+import java.security.MessageDigest;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.kingsrook.qbits.backups.BackupsQBitConfig;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.alerts.BackupAlerts;
+import com.kingsrook.qbits.backups.alerts.BackupAlertSink;
+import com.kingsrook.qbits.backups.codec.ArtifactTransform;
+import com.kingsrook.qbits.backups.codec.HashingOutputStream;
+import com.kingsrook.qbits.backups.codec.JsonlRowCodec;
+import com.kingsrook.qbits.backups.manifest.BackupManifest;
+import com.kingsrook.qbits.backups.manifest.TableFingerprints;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qbits.backups.storage.BackupStorage;
+import com.kingsrook.qbits.backups.storage.BackupStorageException;
+import com.kingsrook.qbits.backups.storage.StoredObjectInfo;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+/*******************************************************************************
+ ** Verifies backup runs (design spec section 10.1).  Three levels, each a row in
+ ** backups_verification:
+ ** <ul>
+ **    <li>STORAGE: head every object of the run, including every file-store object
+ **    the run's file index references; sizes (and a provider checksum, where the
+ **    provider stores one) must match the manifest.</li>
+ **    <li>CONTENT: read every byte.  Each part is decrypted (the decrypt hook,
+ **    ArtifactTransform.unwrap), gunzipped and parsed row by row with the codec;
+ **    row counts, sha256Stored, sha256Raw and the table rowsHash are recomputed and
+ **    compared with the manifest.  Every referenced file-store object is decrypted
+ **    and re-hashed against its SHA-256 key, except those verified within
+ **    fileReverifyDays (backups_file_object.lastVerifiedDate).</li>
+ **    <li>TEST_RESTORE: see {@link TestRestoreVerifier}.</li>
+ ** </ul>
+ ** The result updates backups_run.verificationStatus and backups_plan.lastVerified*,
+ ** and a failure raises backups.verify.failed.  A mismatch is a FAILED verification;
+ ** a verification that could not run (storage unreachable, no key) is an ERROR.
+ *******************************************************************************/
+public class BackupVerifier
+{
+   private static final QLogger LOG = QLogger.getLogger(BackupVerifier.class);
+
+   private static final ObjectMapper MAPPER = new ObjectMapper();
+
+   public static final String STORAGE      = "STORAGE";
+   public static final String CONTENT      = "CONTENT";
+   public static final String TEST_RESTORE = "TEST_RESTORE";
+
+   /** The levels in order; each includes the ones before it when run through. */
+   public static final List<String> LEVELS = List.of(STORAGE, CONTENT, TEST_RESTORE);
+
+   private static final List<String> STATUS_RANK = List.of("UNVERIFIED", "STORAGE_OK", "CONTENT_OK", "TEST_RESTORE_OK");
+
+   private final BackupCatalog catalog = new BackupCatalog();
+
+
+
+   /*******************************************************************************
+    ** Verify a run at each level up to and including the given one, stopping at the
+    ** first level that does not pass.  Returns one outcome per level that ran.
+    *******************************************************************************/
+   public List<VerificationOutcome> verifyThrough(Integer runId, String maxLevel, String trigger, String requestedBy) throws QException
+   {
+      List<VerificationOutcome> outcomes = new ArrayList<>();
+      for(String level : LEVELS.subList(0, LEVELS.indexOf(maxLevel) + 1))
+      {
+         VerificationOutcome outcome = verify(runId, level, trigger, requestedBy);
+         outcomes.add(outcome);
+         if(!outcome.passed())
+         {
+            break;
+         }
+      }
+      return (outcomes);
+   }
+
+
+
+   /*******************************************************************************
+    ** Verify a run at one level.  Never throws for a backup problem: the outcome
+    ** carries the status and the first messages.
+    *******************************************************************************/
+   public VerificationOutcome verify(Integer runId, String level, String trigger, String requestedBy) throws QException
+   {
+      if(!LEVELS.contains(level))
+      {
+         throw (new QException("Unknown verification level: " + level));
+      }
+      QRecord run = catalog.get(BackupsTables.RUN, runId).orElseThrow(() -> new QException("No backup run with id " + runId));
+      QRecord plan = run.getValueInteger("backupPlanId") == null ? null : catalog.get(BackupsTables.PLAN, run.getValueInteger("backupPlanId")).orElse(null);
+
+      Instant started = BackupsRuntime.getClock().instant();
+      Map<String, Serializable> row = new LinkedHashMap<>();
+      row.put("backupRunId", runId);
+      row.put("level", level);
+      row.put("trigger", trigger);
+      row.put("requestedByUserId", requestedBy);
+      row.put("startDate", started);
+      row.put("status", "RUNNING");
+      Integer verificationId = catalog.insert(BackupsTables.VERIFICATION, row);
+
+      VerifyFindings findings = new VerifyFindings();
+      String         status;
+      String         scratch = null;
+      try
+      {
+         RunBundle bundle = RunBundle.load(run, plan, findings);
+         if(bundle != null)
+         {
+            switch(level)
+            {
+               case STORAGE -> storageLevel(bundle, findings);
+               case CONTENT -> contentLevel(bundle, findings);
+               default -> scratch = new TestRestoreVerifier().verify(bundle, findings);
+            }
+         }
+         status = findings.status();
+      }
+      catch(VerifyException | BackupStorageException | QException e)
+      {
+         status = "ERROR";
+         findings.mismatch("The verification could not be carried out: " + e.getMessage());
+      }
+      catch(RuntimeException e)
+      {
+         LOG.warn("Verification crashed", e, logPair("runId", runId), logPair("level", level));
+         status = "ERROR";
+         findings.mismatch("The verification crashed: " + e.getClass().getSimpleName() + ": " + e.getMessage());
+      }
+
+      Instant ended = BackupsRuntime.getClock().instant();
+      VerificationOutcome outcome = new VerificationOutcome(verificationId, runId, level, status, findings.tablesChecked, findings.rowsChecked, findings.mismatches,
+         findings.objectsChecked, findings.filesChecked, findings.filesSkipped, findings.messages(), scratch);
+
+      Map<String, Serializable> done = new LinkedHashMap<>();
+      done.put("endDate", ended);
+      done.put("status", status);
+      done.put("tablesChecked", findings.tablesChecked);
+      done.put("rowsChecked", findings.rowsChecked);
+      done.put("mismatches", findings.mismatches);
+      done.put("scratchTarget", scratch);
+      done.put("detailJson", detailJson(findings));
+      catalog.update(BackupsTables.VERIFICATION, verificationId, done);
+
+      applyOutcome(run, plan, outcome, ended);
+      return (outcome);
+   }
+
+
+
+   /*******************************************************************************
+    ** STORAGE level: head every object, including every file-store object.
+    *******************************************************************************/
+   void storageLevel(RunBundle bundle, VerifyFindings findings)
+   {
+      BackupManifest manifest = bundle.manifest();
+      BackupStorage  storage  = bundle.storage();
+      findings.tablesChecked = manifest.tables().size();
+      findings.objectsChecked++;
+
+      headOrMismatch(storage, bundle.runPrefix() + "checksums.sha256", "checksums.sha256", findings);
+
+      for(BackupManifest.TableEntry table : manifest.tables())
+      {
+         for(BackupManifest.Part part : table.parts() == null ? List.<BackupManifest.Part>of() : table.parts())
+         {
+            findings.objectsChecked++;
+            Optional<StoredObjectInfo> head = storage.head(bundle.runPrefix() + part.key());
+            if(head.isEmpty())
+            {
+               findings.mismatch("Missing object: " + part.key() + " (table " + table.name() + ")");
+               continue;
+            }
+            if(head.get().size() != part.bytesStored())
+            {
+               findings.mismatch("Size mismatch for " + part.key() + ": the manifest says " + part.bytesStored() + " bytes, the bucket has " + head.get().size());
+            }
+            String providerSha = head.get().metadata() == null ? null : head.get().metadata().get("sha256");
+            if(providerSha != null && !providerSha.equalsIgnoreCase(part.sha256Stored()))
+            {
+               findings.mismatch("Checksum mismatch for " + part.key() + ": the provider's stored SHA-256 differs from the manifest");
+            }
+         }
+      }
+
+      if(manifest.files() != null && manifest.files().indexKeys() != null)
+      {
+         for(String indexKey : manifest.files().indexKeys())
+         {
+            headOrMismatch(storage, bundle.runPrefix() + indexKey, indexKey, findings);
+         }
+      }
+
+      int missingFiles = 0;
+      for(RunBundle.FileIndexEntry entry : bundle.distinctStoredFiles(findings))
+      {
+         findings.objectsChecked++;
+         findings.filesChecked++;
+         Optional<StoredObjectInfo> head = storage.head(entry.casKey());
+         if(head.isEmpty())
+         {
+            missingFiles++;
+            findings.mismatch("File store object missing: sha256 " + entry.sha256() + " (referenced by " + entry.table() + ")");
+         }
+         else if(!bundle.isEncrypted() && entry.size() >= 0 && head.get().size() != entry.size())
+         {
+            findings.mismatch("File store object has the wrong size: sha256 " + entry.sha256() + " should be " + entry.size() + " bytes, the bucket has " + head.get().size());
+         }
+      }
+      findings.extra.put("filesMissingFromStore", missingFiles);
+   }
+
+
+
+   /*******************************************************************************
+    ** CONTENT level: decrypt, gunzip, parse, recount and re-hash everything.
+    *******************************************************************************/
+   void contentLevel(RunBundle bundle, VerifyFindings findings) throws QException
+   {
+      BackupManifest manifest  = bundle.manifest();
+      QInstance      qInstance = QContext.getQInstance();
+      findings.tablesChecked = manifest.tables().size();
+
+      checkChecksumsFile(bundle, findings);
+
+      for(BackupManifest.TableEntry entry : manifest.tables())
+      {
+         QTableMetaData table = qInstance.getTable(entry.name());
+         JsonlRowCodec  codec = null;
+         boolean        roundTrip = false;
+         if(table == null)
+         {
+            findings.warn("Table " + entry.name() + " no longer exists in this instance; its rows were checked as JSON, not with the codec");
+         }
+         else
+         {
+            List<String> excluded = entry.excludedFields() == null ? List.of() : entry.excludedFields().stream().map(BackupManifest.ExcludedField::name).toList();
+            codec = new JsonlRowCodec(table, excluded);
+            String backendType = qInstance.getBackend(table.getBackendName()) == null ? null : qInstance.getBackend(table.getBackendName()).getBackendType();
+            roundTrip = TableFingerprints.of(table, backendType).equals(entry.fingerprint());
+            if(!roundTrip)
+            {
+               findings.warn("Table " + entry.name() + " has changed since this backup; rows were parsed but not checked for an exact round trip");
+            }
+         }
+         verifyTable(bundle, entry, codec, roundTrip, findings);
+      }
+
+      verifyFiles(bundle, findings);
+   }
+
+
+
+   /*******************************************************************************
+    ** All parts of one table.
+    *******************************************************************************/
+   private void verifyTable(RunBundle bundle, BackupManifest.TableEntry entry, JsonlRowCodec codec, boolean roundTrip, VerifyFindings findings)
+   {
+      MessageDigest rowsDigest = HashingOutputStream.newSha256();
+      long          rows       = 0;
+      boolean       hasJsonl   = false;
+      int           partCount  = 0;
+      int           before     = findings.mismatches;
+
+      for(BackupManifest.Part part : entry.parts() == null ? List.<BackupManifest.Part>of() : entry.parts())
+      {
+         partCount++;
+         findings.objectsChecked++;
+         boolean jsonl = !"CSV".equals(part.format());
+         hasJsonl |= jsonl;
+         long[] parsedRows = { 0 };
+         try
+         {
+            PartScanner.Scan scan = PartScanner.scan(bundle, part, jsonl ? line ->
+            {
+               parsedRows[0]++;
+               rowsDigest.update((line + "\n").getBytes(java.nio.charset.StandardCharsets.UTF_8));
+               checkRow(entry.name(), part.key(), parsedRows[0], line, codec, roundTrip, findings);
+            } : null);
+
+            if(!scan.sha256Stored().equals(part.sha256Stored()))
+            {
+               findings.mismatch("Stored checksum mismatch for " + part.key() + ": the bytes in the bucket are not the bytes that were written (corrupted or replaced)");
+            }
+            if(!scan.sha256Raw().equals(part.sha256Raw()))
+            {
+               findings.mismatch("Content checksum mismatch for " + part.key() + ": the decoded content differs from what was written");
+            }
+            if(jsonl && scan.lines() != part.rows())
+            {
+               findings.mismatch("Row count mismatch for " + part.key() + ": the manifest says " + part.rows() + " rows, the part has " + scan.lines());
+            }
+            if(jsonl)
+            {
+               rows += scan.lines();
+            }
+         }
+         catch(IOException | RuntimeException e)
+         {
+            findings.mismatch("The part " + part.key() + " could not be read, decrypted or decompressed (" + e.getClass().getSimpleName() + (e.getMessage() == null ? "" : ": " + e.getMessage())
+               + "); it is corrupted, or the key is wrong");
+         }
+         catch(QException e)
+         {
+            findings.mismatch("The part " + part.key() + " could not be read: " + e.getMessage());
+         }
+      }
+
+      String actualHash = hasJsonl ? "sha256:" + HashingOutputStream.hex(rowsDigest.digest()) : null;
+      if(hasJsonl)
+      {
+         findings.rowsChecked += rows;
+         if(rows != entry.rowCount())
+         {
+            findings.mismatch("Row count mismatch for table " + entry.name() + ": the manifest says " + entry.rowCount() + ", the parts hold " + rows);
+         }
+         if(entry.rowsHash() != null && !entry.rowsHash().equals(actualHash))
+         {
+            findings.mismatch("Row content hash mismatch for table " + entry.name() + ": the rows are not the rows that were backed up");
+         }
+      }
+      else
+      {
+         findings.warn("Table " + entry.name() + " has only CSV parts; their bytes were hashed but rows were not recounted");
+      }
+
+      Map<String, Object> detail = new LinkedHashMap<>();
+      detail.put("table", entry.name());
+      detail.put("parts", partCount);
+      detail.put("expectedRows", entry.rowCount());
+      detail.put("actualRows", hasJsonl ? rows : null);
+      detail.put("expectedRowsHash", entry.rowsHash());
+      detail.put("actualRowsHash", actualHash);
+      detail.put("ok", findings.mismatches == before);
+      findings.tables.add(detail);
+   }
+
+
+
+   /*******************************************************************************
+    ** Parse one row with the codec (and check the exact round trip when the table
+    ** is unchanged).  Without a table, check only that it is a JSON object.
+    *******************************************************************************/
+   private void checkRow(String table, String partKey, long rowNumber, String line, JsonlRowCodec codec, boolean roundTrip, VerifyFindings findings) throws QException
+   {
+      try
+      {
+         if(codec == null)
+         {
+            if(!MAPPER.readTree(line).isObject())
+            {
+               throw (new QException("not a JSON object"));
+            }
+            return;
+         }
+         QRecord record = codec.decode(line);
+         if(roundTrip && !codec.encode(record).equals(line))
+         {
+            findings.mismatch("Row " + rowNumber + " of " + partKey + " does not survive a decode and encode round trip (table " + table + ")");
+         }
+      }
+      catch(IOException | QException e)
+      {
+         findings.mismatch("Row " + rowNumber + " of " + partKey + " cannot be parsed (table " + table + ")");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The checksums.sha256 file must list every part with its stored SHA-256.
+    *******************************************************************************/
+   private void checkChecksumsFile(RunBundle bundle, VerifyFindings findings)
+   {
+      String key = bundle.runPrefix() + "checksums.sha256";
+      findings.objectsChecked++;
+      try(InputStream in = bundle.storage().openRead(key))
+      {
+         String text = new String(in.readAllBytes(), java.nio.charset.StandardCharsets.UTF_8);
+         for(BackupManifest.TableEntry table : bundle.manifest().tables())
+         {
+            for(BackupManifest.Part part : table.parts() == null ? List.<BackupManifest.Part>of() : table.parts())
+            {
+               if(!text.contains(part.sha256Stored() + "  " + part.key()))
+               {
+                  findings.mismatch("checksums.sha256 does not list " + part.key() + " with the manifest's checksum");
+               }
+            }
+         }
+      }
+      catch(BackupStorageException e)
+      {
+         findings.mismatch("checksums.sha256 is missing from the bucket");
+      }
+      catch(IOException e)
+      {
+         findings.mismatch("checksums.sha256 cannot be read: " + e.getClass().getSimpleName());
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Re-hash every referenced file-store object against its SHA-256 key, skipping
+    ** those verified within fileReverifyDays.
+    *******************************************************************************/
+   private void verifyFiles(RunBundle bundle, VerifyFindings findings) throws QException
+   {
+      BackupsQBitConfig config   = BackupsRuntime.getConfig();
+      int               days     = config == null || config.getFileReverifyDays() == null ? 30 : config.getFileReverifyDays();
+      Instant           now      = BackupsRuntime.getClock().instant();
+      Instant           cutoff   = now.minus(Duration.ofDays(days));
+      int               failed   = 0;
+
+      for(RunBundle.FileIndexEntry entry : bundle.distinctStoredFiles(findings))
+      {
+         QRecord fileObject = catalog.where(BackupsTables.FILE_OBJECT, "sha256", entry.sha256()).stream().filter(r -> r.getValue("deletedDate") == null).findFirst().orElse(null);
+         if(fileObject != null && "PASSED".equals(fileObject.getValueString("lastVerifyStatus"))
+            && fileObject.getValueInstant("lastVerifiedDate") != null && fileObject.getValueInstant("lastVerifiedDate").isAfter(cutoff))
+         {
+            findings.filesSkipped++;
+            continue;
+         }
+
+         findings.filesChecked++;
+         findings.objectsChecked++;
+         boolean encrypted = fileObject != null ? Boolean.TRUE.equals(fileObject.getValueBoolean("encrypted")) : bundle.isEncrypted();
+         boolean ok        = false;
+         try
+         {
+            String actual = hashStoredFile(bundle, entry.casKey(), encrypted);
+            ok = actual.equals(entry.sha256());
+            if(!ok)
+            {
+               findings.mismatch("File store object sha256 " + entry.sha256() + " has the wrong content: re-hashing it gives " + actual);
+            }
+         }
+         catch(BackupStorageException e)
+         {
+            findings.mismatch("File store object missing: sha256 " + entry.sha256() + " (referenced by " + entry.table() + ")");
+         }
+         catch(IOException | RuntimeException e)
+         {
+            findings.mismatch("File store object sha256 " + entry.sha256() + " could not be read or decrypted (" + e.getClass().getSimpleName() + ")");
+         }
+
+         if(!ok)
+         {
+            failed++;
+         }
+         if(fileObject != null)
+         {
+            Map<String, Serializable> update = new LinkedHashMap<>();
+            update.put("lastVerifiedDate", now);
+            update.put("lastVerifyStatus", ok ? "PASSED" : "FAILED");
+            catalog.update(BackupsTables.FILE_OBJECT, fileObject.getValueInteger("id"), update);
+         }
+      }
+      findings.extra.put("filesFailed", failed);
+   }
+
+
+
+   /*******************************************************************************
+    ** SHA-256 of a stored file's plaintext (decrypted when it was encrypted).
+    *******************************************************************************/
+   static String hashStoredFile(RunBundle bundle, String key, boolean encrypted) throws IOException
+   {
+      return (hashObject(bundle.storage(), key, encrypted ? bundle.transform() : ArtifactTransform.IDENTITY));
+   }
+
+
+
+   /*******************************************************************************
+    ** SHA-256 of an object read through a transform.
+    *******************************************************************************/
+   static String hashObject(BackupStorage storage, String key, ArtifactTransform transform) throws IOException
+   {
+      MessageDigest digest = HashingOutputStream.newSha256();
+      try(InputStream raw = storage.openRead(key);
+          DigestInputStream plain = new DigestInputStream(transform.unwrap(raw), digest))
+      {
+         plain.transferTo(OutputStream.nullOutputStream());
+      }
+      return (HashingOutputStream.hex(digest.digest()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Head an object, recording a mismatch when it is missing.
+    *******************************************************************************/
+   private void headOrMismatch(BackupStorage storage, String key, String label, VerifyFindings findings)
+   {
+      findings.objectsChecked++;
+      if(storage.head(key).isEmpty())
+      {
+         findings.mismatch("Missing object: " + label);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The per-table detail and the messages, as JSON text.
+    *******************************************************************************/
+   private String detailJson(VerifyFindings findings)
+   {
+      Map<String, Object> detail = new LinkedHashMap<>();
+      detail.put("tables", findings.tables);
+      detail.put("mismatches", findings.mismatchMessages);
+      detail.put("warnings", findings.warnings);
+      detail.put("objectsChecked", findings.objectsChecked);
+      detail.put("filesChecked", findings.filesChecked);
+      detail.put("filesSkipped", findings.filesSkipped);
+      detail.putAll(findings.extra);
+      try
+      {
+         return (MAPPER.writeValueAsString(detail));
+      }
+      catch(IOException e)
+      {
+         return ("{}");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Update the run, the plan and the alerts from an outcome.
+    *******************************************************************************/
+   private void applyOutcome(QRecord run, QRecord plan, VerificationOutcome outcome, Instant when) throws QException
+   {
+      Integer runId    = run.getValueInteger("id");
+      String  current  = run.getValueString("verificationStatus");
+      String  newState = null;
+      if(outcome.passed())
+      {
+         String reached = switch(outcome.level())
+         {
+            case STORAGE -> "STORAGE_OK";
+            case CONTENT -> "CONTENT_OK";
+            default -> "TEST_RESTORE_OK";
+         };
+         boolean currentFailed = "FAILED".equals(current);
+         // a cheap pass never clears a failure found by a deeper level
+         if(!currentFailed || !STORAGE.equals(outcome.level()))
+         {
+            newState = !currentFailed && STATUS_RANK.indexOf(current) > STATUS_RANK.indexOf(reached) ? current : reached;
+         }
+      }
+      else
+      {
+         newState = "FAILED";
+      }
+      if(newState != null && !newState.equals(current))
+      {
+         catalog.update(BackupsTables.RUN, runId, Map.of("verificationStatus", newState));
+      }
+
+      if(plan == null)
+      {
+         return;
+      }
+      String planKey = plan.getValueString("planKey");
+      int    rank    = LEVELS.indexOf(outcome.level());
+      if(outcome.passed())
+      {
+         for(int i = 0; i <= rank; i++)
+         {
+            BackupAlerts.resolveKey(BackupAlerts.VERIFY_FAILED, BackupAlerts.verifyKey(planKey, LEVELS.get(i)));
+         }
+         if(rank >= LEVELS.indexOf(CONTENT))
+         {
+            Map<String, Serializable> planUpdate = new LinkedHashMap<>();
+            planUpdate.put("lastVerifiedRunId", runId);
+            planUpdate.put("lastVerifiedDate", when);
+            catalog.update(BackupsTables.PLAN, plan.getValueInteger("id"), planUpdate);
+            BackupAlerts.resolve(BackupAlerts.VERIFY_OVERDUE, planKey);
+         }
+      }
+      else
+      {
+         Map<String, String> detail = new LinkedHashMap<>();
+         detail.put("plan", planKey);
+         detail.put("run", run.getValueString("runKey"));
+         detail.put("level", outcome.level());
+         detail.put("mismatches", String.valueOf(outcome.mismatches()));
+         BackupAlerts.raiseWithKey(BackupAlerts.VERIFY_FAILED, BackupAlerts.verifyKey(planKey, outcome.level()), BackupAlertSink.Severity.ERROR,
+            "Backup verification failed (" + outcome.level() + ")", detail);
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/backups/verify/MemoryScratchTarget.java

@@ -0,0 +1,189 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.verify;
+
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Consumer;
+import com.kingsrook.qqq.backend.core.actions.tables.DeleteAction;
+import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QBackendMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryBackendModule;
+
+
+/*******************************************************************************
+ ** The MEMORY scratch target (design spec section 10.1): QQQ's memory backend.  It
+ ** proves the files and the codecs, not the database.  Each source table is cloned
+ ** into a temporary in-memory QTableMetaData (a different name, the memory backend,
+ ** no customizers, automation, behaviors, unique keys or associations) that is
+ ** registered in the instance for the length of the verification and removed by
+ ** drop().
+ *******************************************************************************/
+public class MemoryScratchTarget implements ScratchTarget
+{
+   public static final String BACKEND_NAME = "qqq_verify_memory";
+   public static final String TYPE         = "MEMORY";
+
+   private final Map<String, List<String>> tablesByRun = new LinkedHashMap<>();
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public String type()
+   {
+      return (TYPE);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public String describe(String runKey)
+   {
+      return ("memory:" + prefix(runKey));
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public synchronized ScratchTable create(QTableMetaData source, String runKey) throws QException
+   {
+      QInstance qInstance = QContext.getQInstance();
+      if(qInstance.getBackend(BACKEND_NAME) == null)
+      {
+         qInstance.addBackend(new QBackendMetaData().withName(BACKEND_NAME).withBackendType(MemoryBackendModule.class));
+      }
+
+      String         scratchName = prefix(runKey) + "_" + source.getName();
+      QTableMetaData clone       = source.clone();
+      clone.setName(scratchName);
+      clone.setBackendName(BACKEND_NAME);
+      clone.setBackendDetails(null);
+      clone.setAutomationDetails(null);
+      clone.setCustomizers(null);
+      clone.setUniqueKeys(null);
+      clone.setAssociations(new ArrayList<>());
+      clone.setRecordSecurityLocks(new ArrayList<>());
+      clone.setExposedJoins(new ArrayList<>());
+      clone.setSupplementalMetaData(null);
+      clone.setSourceQBitName(null);
+      clone.getFields().values().forEach(field -> field.setBehaviors(null));
+      qInstance.getTables().put(scratchName, clone);
+      tablesByRun.computeIfAbsent(runKey, k -> new ArrayList<>()).add(scratchName);
+
+      return (new ScratchTable()
+      {
+         /*******************************************************************************
+          ** {@inheritDoc}
+          *******************************************************************************/
+         @Override
+         public void insert(List<QRecord> records) throws QException
+         {
+            InsertInput input = new InsertInput(scratchName);
+            input.setRecords(records);
+            input.withPermissionBypass("backups verify scratch");
+            List<QRecord> inserted = new InsertAction().execute(input).getRecords();
+            for(QRecord record : inserted)
+            {
+               if(record.getErrors() != null && !record.getErrors().isEmpty())
+               {
+                  throw (new QException("A row could not be restored into the scratch table for " + source.getName() + ": " + record.getErrors().get(0).getMessage()));
+               }
+            }
+         }
+
+
+
+         /*******************************************************************************
+          ** {@inheritDoc}
+          *******************************************************************************/
+         @Override
+         public void readInPrimaryKeyOrder(int pageSize, Consumer<QRecord> consumer) throws QException
+         {
+            int skip = 0;
+            while(true)
+            {
+               QueryInput input = new QueryInput(scratchName);
+               input.setFilter(new QQueryFilter().withOrderBy(new QFilterOrderBy(source.getPrimaryKeyField(), true)).withSkip(skip).withLimit(pageSize));
+               input.withPermissionBypass("backups verify scratch");
+               List<QRecord> page = new QueryAction().execute(input).getRecords();
+               page.forEach(consumer);
+               if(page.size() < pageSize)
+               {
+                  return;
+               }
+               skip += pageSize;
+            }
+         }
+      });
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public synchronized void drop(String runKey) throws QException
+   {
+      List<String> names = tablesByRun.remove(runKey);
+      if(names == null)
+      {
+         return;
+      }
+      for(String name : names)
+      {
+         DeleteInput input = new DeleteInput(name);
+         input.setQueryFilter(new QQueryFilter());
+         input.withPermissionBypass("backups verify scratch");
+         new DeleteAction().execute(input);
+         QContext.getQInstance().getTables().remove(name);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The scratch name prefix of a run: qqq_verify_ plus the run key made safe.
+    *******************************************************************************/
+   static String prefix(String runKey)
+   {
+      return ("qqq_verify_" + runKey.replaceAll("[^A-Za-z0-9]", "_").toLowerCase());
+   }
+}

src/main/java/com/kingsrook/qbits/backups/verify/PartScanner.java

@@ -0,0 +1,116 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.verify;
+
+
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.io.OutputStream;
+import java.nio.charset.StandardCharsets;
+import java.security.DigestInputStream;
+import java.security.MessageDigest;
+import java.util.zip.GZIPInputStream;
+import com.kingsrook.qbits.backups.codec.HashingOutputStream;
+import com.kingsrook.qbits.backups.manifest.BackupManifest;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+
+
+/*******************************************************************************
+ ** Reads one stored part end to end the way a restore would: from storage,
+ ** through the decrypt hook, through gunzip, and hands each line to a consumer,
+ ** while hashing the stored bytes and the decoded bytes.
+ *******************************************************************************/
+final class PartScanner
+{
+   /***************************************************************************
+    ** What a scan saw.
+    **
+    ** @param lines the number of lines handed to the consumer (0 when none was given)
+    ** @param sha256Stored SHA-256 of the bytes in the bucket
+    ** @param sha256Raw SHA-256 of the bytes after decrypting and decompressing
+    ***************************************************************************/
+   record Scan(long lines, String sha256Stored, String sha256Raw)
+   {
+   }
+
+
+
+   /***************************************************************************
+    ** Receives each line of a part (no trailing newline).
+    ***************************************************************************/
+   @FunctionalInterface
+   interface LineConsumer
+   {
+      /***************************************************************************
+       ** One line.
+       ***************************************************************************/
+      void accept(String line) throws QException;
+   }
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private PartScanner()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Scan a part.  With no consumer the part is read to its end and hashed only (a
+    ** CSV part, where lines are not rows).
+    *******************************************************************************/
+   static Scan scan(RunBundle bundle, BackupManifest.Part part, LineConsumer consumer) throws IOException, QException
+   {
+      MessageDigest storedDigest = HashingOutputStream.newSha256();
+      MessageDigest rawDigest    = HashingOutputStream.newSha256();
+      long          lines        = 0;
+
+      try(InputStream fromStorage = bundle.storage().openRead(bundle.runPrefix() + part.key());
+          DigestInputStream stored = new DigestInputStream(fromStorage, storedDigest))
+      {
+         InputStream plain        = part.encrypted() ? bundle.transform().unwrap(stored) : stored;
+         InputStream decompressed = "GZIP".equals(part.compression()) ? new GZIPInputStream(plain) : plain;
+
+         try(DigestInputStream raw = new DigestInputStream(decompressed, rawDigest))
+         {
+            if(consumer == null)
+            {
+               raw.transferTo(OutputStream.nullOutputStream());
+            }
+            else
+            {
+               BufferedReader reader = new BufferedReader(new InputStreamReader(raw, StandardCharsets.UTF_8));
+               String         line;
+               while((line = reader.readLine()) != null)
+               {
+                  lines++;
+                  consumer.accept(line);
+               }
+            }
+            // anything after the decoded stream (a gzip trailer, padding) still counts toward the stored hash
+            stored.transferTo(OutputStream.nullOutputStream());
+         }
+      }
+
+      return (new Scan(lines, HashingOutputStream.hex(storedDigest.digest()), HashingOutputStream.hex(rawDigest.digest())));
+   }
+}

src/main/java/com/kingsrook/qbits/backups/verify/RdbmsSchemaScratchTarget.java

@@ -0,0 +1,102 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.verify;
+
+
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** The RDBMS_SCHEMA scratch target (design spec section 10.1): a configured scratch
+ ** backend whose dedicated database user may CREATE SCHEMA and DROP SCHEMA only for
+ ** qqq_verify_*.  The qbit creates qqq_verify_(runKey), builds each table there
+ ** from a DDL-only copy generated from QQQ metadata (columns by type, primary key,
+ ** unique keys), restores through a temporary in-memory QTableMetaData clone that
+ ** points at the scratch schema, and drops the schema.
+ **
+ ** STUB / TODO: this needs the restore agent's writer (the restore-mode insert,
+ ** QRun-IO/qqq PR #1111 RestoreWriteFlag, and the table writer built on it) and the
+ ** schema DDL generator.  Until those land, create() refuses with a clear message,
+ ** so a plan that selects this target fails its TEST_RESTORE verification with an
+ ** ERROR instead of silently passing.  Replace the body with the real
+ ** implementation when the restore writer is available.
+ *******************************************************************************/
+public class RdbmsSchemaScratchTarget implements ScratchTarget
+{
+   public static final String TYPE = "RDBMS_SCHEMA";
+
+   private final String backendName;
+
+
+
+   /*******************************************************************************
+    ** Constructor.
+    **
+    ** @param backendName the configured scratch RDBMS backend
+    *******************************************************************************/
+   public RdbmsSchemaScratchTarget(String backendName)
+   {
+      this.backendName = backendName;
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public String type()
+   {
+      return (TYPE);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public String describe(String runKey)
+   {
+      return (backendName + ":schema=qqq_verify_" + runKey.replaceAll("[^A-Za-z0-9]", "_").toLowerCase());
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public ScratchTable create(QTableMetaData source, String runKey) throws QException
+   {
+      // TODO: CREATE SCHEMA, generate the DDL-only table copy, and return a ScratchTable that restores
+      //  through the restore writer.  Needs the restore agent's writer.
+      throw (new QException("The RDBMS_SCHEMA scratch target is not implemented yet (it needs the restore writer); use the MEMORY scratch target."));
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public void drop(String runKey) throws QException
+   {
+      // TODO: DROP SCHEMA qqq_verify_(runKey) once create() is implemented.
+   }
+}

src/main/java/com/kingsrook/qbits/backups/verify/RunBundle.java

@@ -0,0 +1,367 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.verify;
+
+
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.io.BufferedReader;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.zip.GZIPInputStream;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.codec.ArtifactTransform;
+import com.kingsrook.qbits.backups.codec.HashingOutputStream;
+import com.kingsrook.qbits.backups.manifest.BackupManifest;
+import com.kingsrook.qbits.backups.storage.BackupStorage;
+import com.kingsrook.qbits.backups.storage.StoredObjectInfo;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Everything a verification needs to know about one run, loaded once: the run
+ ** row, its storage, its manifest (read and hashed), the transform that undoes
+ ** the plan's encryption, and (lazily) the file index.
+ *******************************************************************************/
+class RunBundle
+{
+   private static final ObjectMapper MAPPER = new ObjectMapper();
+
+   private final QRecord          run;
+   private final QRecord          plan;
+   private final BackupStorage    storage;
+   private final String           runPrefix;
+   private final BackupManifest   manifest;
+   private final ArtifactTransform transform;
+   private final boolean          encrypted;
+
+   private List<FileIndexEntry> fileIndex;
+
+
+
+   /***************************************************************************
+    ** One line of the per-run file index.
+    **
+    ** @param table the referencing table
+    ** @param recordKey the referencing record's primary key
+    ** @param field the referencing field
+    ** @param sha256 the content hash, null when not known
+    ** @param size the size in bytes, -1 when not known
+    ** @param status COPIED, DEDUPLICATED, MISSING or REFERENCE_ONLY
+    ** @param casKey the content-addressed key in the bucket, null when not stored
+    ***************************************************************************/
+   record FileIndexEntry(String table, String recordKey, String field, String sha256, long size, String status, String casKey)
+   {
+      /*******************************************************************************
+       ** Whether the file is in the file store (so it can be checked).
+       *******************************************************************************/
+      boolean isStored()
+      {
+         return (casKey != null && sha256 != null && ("COPIED".equals(status) || "DEDUPLICATED".equals(status)));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Constructor.
+    *******************************************************************************/
+   private RunBundle(QRecord run, QRecord plan, BackupStorage storage, String runPrefix, BackupManifest manifest, ArtifactTransform transform, boolean encrypted)
+   {
+      this.run = run;
+      this.plan = plan;
+      this.storage = storage;
+      this.runPrefix = runPrefix;
+      this.manifest = manifest;
+      this.transform = transform;
+      this.encrypted = encrypted;
+   }
+
+
+
+   /*******************************************************************************
+    ** Load a run.  Returns null, after recording a mismatch, when the run has no
+    ** readable manifest (so it is not usable and there is nothing more to check).
+    ** Throws VerifyException when the run cannot be examined at all.
+    *******************************************************************************/
+   static RunBundle load(QRecord run, QRecord plan, VerifyFindings findings)
+   {
+      String alias     = run.getValueString("storageBucketAlias");
+      String runPrefix = run.getValueString("runPrefix");
+      if(alias == null || runPrefix == null)
+      {
+         throw (new VerifyException("The run has no storage bucket or run prefix recorded"));
+      }
+      BackupStorage storage = BackupsRuntime.storageFor(alias);
+
+      String manifestKey = run.getValueString("manifestKey") != null ? run.getValueString("manifestKey") : runPrefix + "manifest.json";
+      Optional<StoredObjectInfo> head = storage.head(manifestKey);
+      if(head.isEmpty())
+      {
+         findings.mismatch("The manifest is missing from the bucket, so this backup is not usable");
+         return (null);
+      }
+
+      byte[] bytes;
+      try(InputStream in = storage.openRead(manifestKey))
+      {
+         bytes = in.readAllBytes();
+      }
+      catch(IOException e)
+      {
+         throw (new VerifyException("The manifest could not be read: " + e.getMessage(), e));
+      }
+
+      String sha = HashingOutputStream.sha256Hex(bytes);
+      if(run.getValueString("manifestSha256") != null && !run.getValueString("manifestSha256").equals(sha))
+      {
+         findings.mismatch("The manifest changed after it was written (its SHA-256 no longer matches the catalog)");
+      }
+
+      BackupManifest manifest;
+      try
+      {
+         manifest = BackupManifest.read(bytes);
+      }
+      catch(IOException e)
+      {
+         findings.mismatch("The manifest is not valid JSON: " + e.getMessage());
+         return (null);
+      }
+      if(manifest.tables() == null)
+      {
+         findings.mismatch("The manifest lists no tables section");
+         return (null);
+      }
+
+      boolean encrypted = manifest.encryption() != null && manifest.encryption().mode() != null && !"NONE".equals(manifest.encryption().mode());
+      ArtifactTransform transform = ArtifactTransform.IDENTITY;
+      if(encrypted)
+      {
+         String keyRef = manifest.encryption().keyRef();
+         var    config = BackupsRuntime.getConfig();
+         if(config == null || config.getArtifactTransformResolver() == null)
+         {
+            throw (new VerifyException("This backup is encrypted but no decrypt hook is configured (BackupsQBitConfig.withArtifactTransformResolver), so it cannot be verified"));
+         }
+         transform = config.getArtifactTransformResolver().apply(keyRef);
+         if(transform == null)
+         {
+            throw (new VerifyException("No key is available for the key reference " + keyRef + ", so this backup cannot be decrypted"));
+         }
+      }
+      return (new RunBundle(run, plan, storage, runPrefix, manifest, transform, encrypted));
+   }
+
+
+
+   /*******************************************************************************
+    ** The distinct stored files the run's file index references, in first-seen order
+    ** (one entry per hash).  Reads the index once.
+    *******************************************************************************/
+   synchronized List<FileIndexEntry> distinctStoredFiles(VerifyFindings findings)
+   {
+      if(fileIndex == null)
+      {
+         fileIndex = readIndex(findings);
+      }
+      Map<String, FileIndexEntry> bySha = new LinkedHashMap<>();
+      for(FileIndexEntry entry : fileIndex)
+      {
+         if(entry.isStored())
+         {
+            bySha.putIfAbsent(entry.sha256(), entry);
+         }
+      }
+      return (new ArrayList<>(bySha.values()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Every index entry, stored or not.
+    *******************************************************************************/
+   synchronized List<FileIndexEntry> allFileEntries(VerifyFindings findings)
+   {
+      if(fileIndex == null)
+      {
+         fileIndex = readIndex(findings);
+      }
+      return (fileIndex);
+   }
+
+
+
+   /*******************************************************************************
+    ** Read the file index objects.  The index is gzip JSON Lines; it is read as plain
+    ** gzip first and, if that is not readable and the plan encrypts, through the
+    ** decrypt hook.
+    *******************************************************************************/
+   private List<FileIndexEntry> readIndex(VerifyFindings findings)
+   {
+      List<FileIndexEntry> entries = new ArrayList<>();
+      if(manifest.files() == null || manifest.files().indexKeys() == null)
+      {
+         return (entries);
+      }
+      for(String relative : manifest.files().indexKeys())
+      {
+         String key = runPrefix + relative;
+         if(storage.head(key).isEmpty())
+         {
+            continue;
+         }
+         try
+         {
+            byte[] bytes;
+            try(InputStream in = storage.openRead(key))
+            {
+               bytes = in.readAllBytes();
+            }
+            try
+            {
+               parseIndex(new GZIPInputStream(new ByteArrayInputStream(bytes)), entries);
+            }
+            catch(IOException plainFailed)
+            {
+               if(!encrypted)
+               {
+                  throw (plainFailed);
+               }
+               entries.clear();
+               parseIndex(new GZIPInputStream(transform.unwrap(new ByteArrayInputStream(bytes))), entries);
+            }
+         }
+         catch(IOException e)
+         {
+            findings.mismatch("The file index " + relative + " cannot be read: " + e.getClass().getSimpleName());
+         }
+      }
+      return (entries);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void parseIndex(InputStream in, List<FileIndexEntry> entries) throws IOException
+   {
+      try(BufferedReader reader = new BufferedReader(new InputStreamReader(in, StandardCharsets.UTF_8)))
+      {
+         String line;
+         while((line = reader.readLine()) != null)
+         {
+            if(line.isBlank())
+            {
+               continue;
+            }
+            JsonNode node = MAPPER.readTree(line);
+            entries.add(new FileIndexEntry(text(node, "table"), text(node, "recordKey"), text(node, "field"), text(node, "sha256"),
+               node.hasNonNull("size") ? node.get("size").asLong() : -1L, text(node, "status"), text(node, "casKey")));
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static String text(JsonNode node, String name)
+   {
+      return (node.hasNonNull(name) ? node.get(name).asText() : null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for run
+    *******************************************************************************/
+   QRecord run()
+   {
+      return (run);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for plan (null for an ad-hoc run)
+    *******************************************************************************/
+   QRecord plan()
+   {
+      return (plan);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for storage
+    *******************************************************************************/
+   BackupStorage storage()
+   {
+      return (storage);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for runPrefix
+    *******************************************************************************/
+   String runPrefix()
+   {
+      return (runPrefix);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for manifest
+    *******************************************************************************/
+   BackupManifest manifest()
+   {
+      return (manifest);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for transform (the decrypt hook, or the identity)
+    *******************************************************************************/
+   ArtifactTransform transform()
+   {
+      return (transform);
+   }
+
+
+
+   /*******************************************************************************
+    ** Whether the run's artifacts are encrypted.
+    *******************************************************************************/
+   boolean isEncrypted()
+   {
+      return (encrypted);
+   }
+}

src/main/java/com/kingsrook/qbits/backups/verify/ScratchTable.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.verify;
+
+
+import java.util.List;
+import java.util.function.Consumer;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** One restored table inside a scratch target.
+ *******************************************************************************/
+public interface ScratchTable
+{
+   /***************************************************************************
+    ** Restore rows into the scratch table, preserving their primary keys.
+    ***************************************************************************/
+   void insert(List<QRecord> records) throws QException;
+
+
+   /***************************************************************************
+    ** Read every row back in primary key order, a page at a time.
+    ***************************************************************************/
+   void readInPrimaryKeyOrder(int pageSize, Consumer<QRecord> consumer) throws QException;
+}

src/main/java/com/kingsrook/qbits/backups/verify/ScratchTarget.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.verify;
+
+
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** Where a TEST_RESTORE verification restores to (design spec section 10.1).  The
+ ** target builds a scratch copy of each table from the source table's metadata,
+ ** takes the restored rows, reads them back in primary key order, and is dropped
+ ** afterwards.  Nothing a scratch target does may touch the real tables.
+ **
+ ** Implementations: MEMORY (MemoryScratchTarget, small apps and CI) and RDBMS_SCHEMA
+ ** (RdbmsSchemaScratchTarget, a stub until the restore agent's writer ships).
+ *******************************************************************************/
+public interface ScratchTarget
+{
+   /***************************************************************************
+    ** The target type: MEMORY, RDBMS_SCHEMA or SEPARATE_DATABASE.
+    ***************************************************************************/
+   String type();
+
+
+   /***************************************************************************
+    ** A description for backups_verification.scratchTarget, for example
+    ** "memory:qqq_verify_20261012t020000z_7f3a".
+    ***************************************************************************/
+   String describe(String runKey);
+
+
+   /***************************************************************************
+    ** Create the scratch copy of a table for a run.
+    ***************************************************************************/
+   ScratchTable create(QTableMetaData source, String runKey) throws QException;
+
+
+   /***************************************************************************
+    ** Drop everything created for the run.  Safe to call more than once.
+    ***************************************************************************/
+   void drop(String runKey) throws QException;
+}

src/main/java/com/kingsrook/qbits/backups/verify/TestRestoreVerifier.java

@@ -0,0 +1,282 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.verify;
+
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.codec.ArtifactTransform;
+import com.kingsrook.qbits.backups.codec.HashingOutputStream;
+import com.kingsrook.qbits.backups.codec.JsonlRowCodec;
+import com.kingsrook.qbits.backups.manifest.BackupManifest;
+import com.kingsrook.qbits.backups.storage.BackupStorage;
+import com.kingsrook.qbits.backups.storage.WriteOptions;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** TEST_RESTORE verification (design spec section 10.1): restore every table of the
+ ** run into a scratch target (MEMORY by default), read it back in primary key order,
+ ** and compare each table's row count and rowsHash with the manifest; restore the
+ ** run's files into the scratch prefix qqq-verify/(runKey)/ in the backup bucket,
+ ** re-hash each one, and check that every file reference of the index resolves to a
+ ** restored file.  Then drop the scratch tables and delete the scratch files, even
+ ** when something fails.
+ **
+ ** The scratch target is BackupsQBitConfig.getScratchTarget(); the MEMORY target
+ ** proves the files and the codecs, not the database.  RDBMS_SCHEMA is a stub until
+ ** the restore agent's writer ships (see RdbmsSchemaScratchTarget).  Sequence resync
+ ** is part of the real restore (spec 5.4) and not exercised by the MEMORY target.
+ *******************************************************************************/
+public class TestRestoreVerifier
+{
+   private static final int PAGE_SIZE = 1000;
+
+   public static final String SCRATCH_FILE_PREFIX = "qqq-verify/";
+
+
+
+   /*******************************************************************************
+    ** Run the test restore, recording what it finds.  Returns the scratch target
+    ** description for backups_verification.scratchTarget.
+    *******************************************************************************/
+   String verify(RunBundle bundle, VerifyFindings findings) throws QException
+   {
+      ScratchTarget target = BackupsRuntime.getConfig() != null && BackupsRuntime.getConfig().getScratchTarget() != null
+         ? BackupsRuntime.getConfig().getScratchTarget() : new MemoryScratchTarget();
+      String runKey  = bundle.manifest().runKey();
+      String scratch = target.describe(runKey);
+
+      List<String> scratchFileKeys = new ArrayList<>();
+      try
+      {
+         findings.tablesChecked = bundle.manifest().tables().size();
+         restoreTables(bundle, target, runKey, findings);
+         restoreFiles(bundle, runKey, scratchFileKeys, findings);
+      }
+      finally
+      {
+         try
+         {
+            target.drop(runKey);
+         }
+         finally
+         {
+            for(String key : scratchFileKeys)
+            {
+               bundle.storage().deletePermanent(key);
+            }
+         }
+      }
+      return (scratch);
+   }
+
+
+
+   /*******************************************************************************
+    ** Restore each table into the scratch target and compare it with the manifest.
+    *******************************************************************************/
+   private void restoreTables(RunBundle bundle, ScratchTarget target, String runKey, VerifyFindings findings) throws QException
+   {
+      BackupManifest manifest = bundle.manifest();
+      List<String>   order    = new ArrayList<>(manifest.restoreOrder() == null ? List.of() : manifest.restoreOrder());
+      for(BackupManifest.TableEntry entry : manifest.tables())
+      {
+         if(!order.contains(entry.name()))
+         {
+            order.add(entry.name());
+         }
+      }
+
+      for(String name : order)
+      {
+         BackupManifest.TableEntry entry = manifest.table(name);
+         if(entry == null)
+         {
+            continue;
+         }
+         QTableMetaData table = QContext.getQInstance().getTable(name);
+         if(table == null)
+         {
+            findings.mismatch("Table " + name + " no longer exists in this instance, so it cannot be test-restored");
+            continue;
+         }
+         boolean hasJsonl = entry.parts() != null && entry.parts().stream().anyMatch(p -> !"CSV".equals(p.format()));
+         if(!hasJsonl)
+         {
+            findings.warn("Table " + name + " has only CSV parts and was not test-restored");
+            continue;
+         }
+
+         List<String> excluded = entry.excludedFields() == null ? List.of() : entry.excludedFields().stream().map(BackupManifest.ExcludedField::name).toList();
+         JsonlRowCodec codec = new JsonlRowCodec(table, excluded);
+         ScratchTable  scratchTable = target.create(table, runKey);
+
+         int before = findings.mismatches;
+         restoreRows(bundle, entry, codec, scratchTable, findings);
+
+         MessageDigest digest = HashingOutputStream.newSha256();
+         long[]        count  = { 0 };
+         scratchTable.readInPrimaryKeyOrder(PAGE_SIZE, record ->
+         {
+            count[0]++;
+            digest.update((codec.encode(record) + "\n").getBytes(StandardCharsets.UTF_8));
+         });
+         String actualHash = "sha256:" + HashingOutputStream.hex(digest.digest());
+
+         if(count[0] != entry.rowCount())
+         {
+            findings.mismatch("Test restore of table " + name + " has " + count[0] + " rows, the manifest says " + entry.rowCount());
+         }
+         if(entry.rowsHash() != null && !entry.rowsHash().equals(actualHash))
+         {
+            findings.mismatch("Test restore of table " + name + " does not reproduce the backed up rows (row content hash differs)");
+         }
+         findings.rowsChecked += count[0];
+
+         Map<String, Object> detail = new LinkedHashMap<>();
+         detail.put("table", name);
+         detail.put("expectedRows", entry.rowCount());
+         detail.put("actualRows", count[0]);
+         detail.put("expectedRowsHash", entry.rowsHash());
+         detail.put("actualRowsHash", actualHash);
+         detail.put("ok", findings.mismatches == before);
+         findings.tables.add(detail);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Decode the JSONL parts of one table and insert them into the scratch table.
+    *******************************************************************************/
+   private void restoreRows(RunBundle bundle, BackupManifest.TableEntry entry, JsonlRowCodec codec, ScratchTable scratchTable, VerifyFindings findings) throws QException
+   {
+      for(BackupManifest.Part part : entry.parts())
+      {
+         if("CSV".equals(part.format()))
+         {
+            continue;
+         }
+         List<QRecord> batch = new ArrayList<>();
+         try
+         {
+            PartScanner.scan(bundle, part, line ->
+            {
+               batch.add(codec.decode(line));
+               if(batch.size() >= PAGE_SIZE)
+               {
+                  scratchTable.insert(new ArrayList<>(batch));
+                  batch.clear();
+               }
+            });
+            if(!batch.isEmpty())
+            {
+               scratchTable.insert(batch);
+            }
+         }
+         catch(IOException | RuntimeException e)
+         {
+            findings.mismatch("The part " + part.key() + " could not be restored (" + e.getClass().getSimpleName() + "); it is corrupted, or the key is wrong");
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Restore the run's files into the scratch prefix, re-hash each, and check that
+    ** every index reference resolves to a restored file.  verifyFileSamplePercent
+    ** (on the plan, default 100) limits how many files are restored.
+    *******************************************************************************/
+   private void restoreFiles(RunBundle bundle, String runKey, List<String> scratchFileKeys, VerifyFindings findings)
+   {
+      int percent = 100;
+      if(bundle.plan() != null && bundle.plan().getValueInteger("verifyFileSamplePercent") != null)
+      {
+         percent = Math.max(0, Math.min(100, bundle.plan().getValueInteger("verifyFileSamplePercent")));
+      }
+
+      BackupStorage storage  = bundle.storage();
+      String        prefix   = SCRATCH_FILE_PREFIX + runKey + "/";
+      Set<String>   restored = new LinkedHashSet<>();
+      int           sampled  = 0;
+      for(RunBundle.FileIndexEntry entry : bundle.distinctStoredFiles(findings))
+      {
+         if(Math.floorMod(entry.sha256().hashCode(), 100) >= percent)
+         {
+            continue;
+         }
+         sampled++;
+         String scratchKey = prefix + entry.sha256();
+         scratchFileKeys.add(scratchKey);
+         try
+         {
+            ArtifactTransform transform = bundle.isEncrypted() ? bundle.transform() : ArtifactTransform.IDENTITY;
+            String            written;
+            try(InputStream raw = storage.openRead(entry.casKey());
+                InputStream plain = transform.unwrap(raw);
+                HashingOutputStream out = new HashingOutputStream(storage.openWrite(scratchKey, WriteOptions.create())))
+            {
+               plain.transferTo(out);
+               out.close();
+               written = out.getSha256();
+            }
+            String reread = BackupVerifier.hashObject(storage, scratchKey, ArtifactTransform.IDENTITY);
+            if(written.equals(entry.sha256()) && reread.equals(entry.sha256()))
+            {
+               restored.add(entry.sha256());
+            }
+            else
+            {
+               findings.mismatch("Test restore of file sha256 " + entry.sha256() + " does not reproduce its content");
+            }
+         }
+         catch(IOException | RuntimeException e)
+         {
+            findings.mismatch("Test restore of file sha256 " + entry.sha256() + " failed (" + e.getClass().getSimpleName() + ")");
+         }
+      }
+
+      int unresolved = 0;
+      for(RunBundle.FileIndexEntry entry : bundle.allFileEntries(findings))
+      {
+         if(entry.isStored() && Math.floorMod(entry.sha256().hashCode(), 100) < percent && !restored.contains(entry.sha256()))
+         {
+            unresolved++;
+         }
+      }
+      if(unresolved > 0)
+      {
+         findings.mismatch(unresolved + " file references in the index do not resolve to a restored file");
+      }
+      findings.filesChecked += sampled;
+      findings.extra.put("filesRestored", restored.size());
+   }
+}

src/main/java/com/kingsrook/qbits/backups/verify/VerificationOutcome.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.verify;
+
+
+import java.util.List;
+
+
+/*******************************************************************************
+ ** The result of verifying one run at one level; also what was written to the
+ ** backups_verification row.
+ **
+ ** @param verificationId the backups_verification id
+ ** @param runId the backups_run id
+ ** @param level STORAGE, CONTENT or TEST_RESTORE
+ ** @param status PASSED, PASSED_WITH_WARNINGS, FAILED or ERROR
+ ** @param tablesChecked tables checked
+ ** @param rowsChecked rows decoded and counted
+ ** @param mismatches how many things did not match (the messages list is capped)
+ ** @param objectsChecked storage objects examined
+ ** @param filesChecked file-store objects examined (head, or read and re-hashed)
+ ** @param filesSkipped file-store objects skipped because they were verified recently
+ ** @param messages the first mismatches and warnings, in plain words
+ ** @param scratchTarget for TEST_RESTORE, the scratch target used
+ *******************************************************************************/
+public record VerificationOutcome(Integer verificationId, Integer runId, String level, String status, int tablesChecked, long rowsChecked, int mismatches,
+                                  int objectsChecked, int filesChecked, int filesSkipped, List<String> messages, String scratchTarget)
+{
+   /*******************************************************************************
+    ** Whether the verification passed (with or without warnings).
+    *******************************************************************************/
+   public boolean passed()
+   {
+      return ("PASSED".equals(status) || "PASSED_WITH_WARNINGS".equals(status));
+   }
+}

src/main/java/com/kingsrook/qbits/backups/verify/VerifyException.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.verify;
+
+
+/*******************************************************************************
+ ** A verification could not be carried out (as opposed to carried out and found
+ ** a mismatch): the storage is unreachable, there is no key to decrypt with.  The
+ ** verification ends with status ERROR.
+ *******************************************************************************/
+public class VerifyException extends RuntimeException
+{
+   /*******************************************************************************
+    ** Constructor.
+    *******************************************************************************/
+   public VerifyException(String message)
+   {
+      super(message);
+   }
+
+
+
+   /*******************************************************************************
+    ** Constructor.
+    *******************************************************************************/
+   public VerifyException(String message, Throwable cause)
+   {
+      super(message, cause);
+   }
+}

src/main/java/com/kingsrook/qbits/backups/verify/VerifyFindings.java

@@ -0,0 +1,99 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.verify;
+
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+
+/*******************************************************************************
+ ** What one verification found: counts, the first mismatches and warnings (capped,
+ ** so a ruined bucket does not write megabytes of messages), and per-table detail
+ ** for backups_verification.detailJson.  Messages never contain row values.
+ *******************************************************************************/
+class VerifyFindings
+{
+   static final int MAX_MESSAGES = 100;
+
+   final List<String>              mismatchMessages = new ArrayList<>();
+   final List<String>              warnings         = new ArrayList<>();
+   final List<Map<String, Object>> tables           = new ArrayList<>();
+   final Map<String, Object>       extra            = new LinkedHashMap<>();
+
+   int  mismatches;
+   int  tablesChecked;
+   long rowsChecked;
+   int  objectsChecked;
+   int  filesChecked;
+   int  filesSkipped;
+
+
+
+   /*******************************************************************************
+    ** Something did not match.
+    *******************************************************************************/
+   void mismatch(String message)
+   {
+      mismatches++;
+      if(mismatchMessages.size() < MAX_MESSAGES)
+      {
+         mismatchMessages.add(message);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Something worth knowing that is not a failure.
+    *******************************************************************************/
+   void warn(String message)
+   {
+      if(warnings.size() < MAX_MESSAGES)
+      {
+         warnings.add(message);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The mismatches, then the warnings.
+    *******************************************************************************/
+   List<String> messages()
+   {
+      List<String> all = new ArrayList<>(mismatchMessages);
+      all.addAll(warnings);
+      return (all);
+   }
+
+
+
+   /*******************************************************************************
+    ** PASSED, PASSED_WITH_WARNINGS or FAILED.
+    *******************************************************************************/
+   String status()
+   {
+      if(mismatches > 0)
+      {
+         return ("FAILED");
+      }
+      return (warnings.isEmpty() ? "PASSED" : "PASSED_WITH_WARNINGS");
+   }
+}

src/test/java/com/kingsrook/qbits/backups/MutableClock.java

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups;
+
+
+import java.time.Clock;
+import java.time.Duration;
+import java.time.Instant;
+import java.time.ZoneId;
+import java.time.ZoneOffset;
+
+
+/*******************************************************************************
+ ** A synthetic clock for tests: it stands still until it is advanced, so SLA
+ ** windows can be crossed without waiting.
+ *******************************************************************************/
+public class MutableClock extends Clock
+{
+   private Instant now;
+
+
+
+   /*******************************************************************************
+    ** Constructor.
+    *******************************************************************************/
+   public MutableClock(Instant start)
+   {
+      this.now = start;
+   }
+
+
+
+   /*******************************************************************************
+    ** Move the clock forward.
+    *******************************************************************************/
+   public synchronized MutableClock advance(Duration duration)
+   {
+      now = now.plus(duration);
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public ZoneId getZone()
+   {
+      return (ZoneOffset.UTC);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public Clock withZone(ZoneId zone)
+   {
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public synchronized Instant instant()
+   {
+      return (now);
+   }
+}

src/test/java/com/kingsrook/qbits/backups/RecordingAlertSink.java

@@ -0,0 +1,98 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups;
+
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.backups.alerts.BackupAlertSink;
+
+
+/*******************************************************************************
+ ** A test double for the alert sink: remembers every call, and which alerts are
+ ** currently open (raised and not resolved), by dedupe key.
+ *******************************************************************************/
+public class RecordingAlertSink implements BackupAlertSink
+{
+   /** One raise call. */
+   public record Raised(String type, String dedupeKey, Severity severity, String title, Map<String, String> detail)
+   {
+   }
+
+   public final List<Raised>           raises     = new ArrayList<>();
+   public final List<String>           resolves   = new ArrayList<>();
+   public final List<String>           heartbeats = new ArrayList<>();
+   public final Map<String, Raised>    open       = new LinkedHashMap<>();
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public void raise(String type, String dedupeKey, Severity severity, String title, Map<String, String> detail)
+   {
+      Raised raised = new Raised(type, dedupeKey, severity, title, detail);
+      raises.add(raised);
+      open.put(dedupeKey, raised);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public void resolve(String type, String dedupeKey)
+   {
+      resolves.add(dedupeKey);
+      open.remove(dedupeKey);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public void heartbeat(String monitorKey, long expectedEverySeconds, long graceSeconds)
+   {
+      heartbeats.add(monitorKey);
+   }
+
+
+
+   /*******************************************************************************
+    ** Whether an alert is open.
+    *******************************************************************************/
+   public boolean isOpen(String dedupeKey)
+   {
+      return (open.containsKey(dedupeKey));
+   }
+
+
+
+   /*******************************************************************************
+    ** The open alert, or null.
+    *******************************************************************************/
+   public Raised openAlert(String dedupeKey)
+   {
+      return (open.get(dedupeKey));
+   }
+}

src/test/java/com/kingsrook/qbits/backups/VerifyTestSupport.java

@@ -0,0 +1,263 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups;
+
+
+import java.io.FilterInputStream;
+import java.io.FilterOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.io.Serializable;
+import java.time.Instant;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import com.kingsrook.qbits.backups.codec.ArtifactTransform;
+import com.kingsrook.qbits.backups.events.BackupEvents;
+import com.kingsrook.qbits.backups.metrics.BackupsMetrics;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qbits.backups.run.BackupEngine;
+import com.kingsrook.qbits.backups.run.BackupRunFactory;
+import com.kingsrook.qbits.backups.run.BackupRunResult;
+import com.kingsrook.qbits.backups.sla.SlaChecker;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Shared setup for the verification, SLA, alert, health and event tests: the
+ ** blog instance, a synthetic clock, a recording alert sink, plans and runs.
+ *******************************************************************************/
+public final class VerifyTestSupport
+{
+   public static MutableClock       clock;
+   public static RecordingAlertSink sink;
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private VerifyTestSupport()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Fresh instance with posts, a synthetic clock starting now, and a recording sink.
+    *******************************************************************************/
+   public static void setUp(int posts) throws Exception
+   {
+      BackupsTestUtils.init();
+      BackupsTestUtils.loadBlog(posts);
+      SlaChecker.resetCaches();
+      BackupsMetrics.resetCache();
+      BackupEvents.setPublisher(null);
+      clock = new MutableClock(Instant.now());
+      sink = new RecordingAlertSink();
+      BackupsRuntime.setClock(clock);
+      BackupsRuntime.setAlertSink(sink);
+   }
+
+
+
+   /*******************************************************************************
+    ** Insert a nightly plan; overrides replace the defaults.
+    *******************************************************************************/
+   public static QRecord plan(Map<String, Serializable> overrides) throws Exception
+   {
+      Map<String, Serializable> values = new LinkedHashMap<>();
+      values.put("name", "Nightly");
+      values.put("planKey", "nightly");
+      values.put("isActive", true);
+      values.put("scopeType", "INSTANCE");
+      values.put("storageBucketAlias", "backups");
+      values.put("slaHours", 26);
+      values.put("verifySlaDays", 8);
+      values.putAll(overrides);
+      Integer id = new BackupCatalog().insert(BackupsTables.PLAN, values);
+      return (new BackupCatalog().get(BackupsTables.PLAN, id).orElseThrow());
+   }
+
+
+
+   /*******************************************************************************
+    ** The plan as it is now.
+    *******************************************************************************/
+   public static QRecord reload(QRecord plan) throws Exception
+   {
+      return (new BackupCatalog().get(BackupsTables.PLAN, plan.getValueInteger("id")).orElseThrow());
+   }
+
+
+
+   /*******************************************************************************
+    ** The run as it is now.
+    *******************************************************************************/
+   public static QRecord run(Integer runId) throws Exception
+   {
+      return (new BackupCatalog().get(BackupsTables.RUN, runId).orElseThrow());
+   }
+
+
+
+   /*******************************************************************************
+    ** Run the plan's backup.
+    *******************************************************************************/
+   public static BackupRunResult backup(QRecord plan) throws Exception
+   {
+      return (new BackupEngine().execute(BackupRunFactory.forPlan(plan, "MANUAL")));
+   }
+
+
+
+   /*******************************************************************************
+    ** Run the plan's backup encrypted with a transform.
+    *******************************************************************************/
+   public static BackupRunResult backupEncrypted(QRecord plan, ArtifactTransform transform, String keyRef) throws Exception
+   {
+      return (new BackupEngine().execute(BackupRunFactory.forPlan(plan, "MANUAL").withTransform(transform, keyRef, "fingerprint-" + keyRef)));
+   }
+
+
+
+   /*******************************************************************************
+    ** The part keys (relative to the run prefix) of a table in a run's manifest.
+    *******************************************************************************/
+   public static String firstPartKey(BackupRunResult result, String table) throws Exception
+   {
+      var manifest = com.kingsrook.qbits.backups.manifest.BackupManifest.read(BackupsTestUtils.BACKUPS.getBytes(result.getManifestKey()));
+      return (result.getRunPrefix() + manifest.table(table).parts().get(0).key());
+   }
+
+
+
+   /***************************************************************************
+    ** A toy "cipher" for tests: every byte is XORed with a key byte.  Different
+    ** key bytes stand in for "the wrong key".
+    ***************************************************************************/
+   public static class XorTransform implements ArtifactTransform
+   {
+      private final int key;
+
+
+
+      /*******************************************************************************
+       ** Constructor.
+       *******************************************************************************/
+      public XorTransform(int key)
+      {
+         this.key = key;
+      }
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public OutputStream wrap(OutputStream out)
+      {
+         return (new FilterOutputStream(out)
+         {
+            /*******************************************************************************
+             ** {@inheritDoc}
+             *******************************************************************************/
+            @Override
+            public void write(int b) throws IOException
+            {
+               out.write((b ^ key) & 0xFF);
+            }
+
+
+
+            /*******************************************************************************
+             ** {@inheritDoc}
+             *******************************************************************************/
+            @Override
+            public void write(byte[] b, int off, int len) throws IOException
+            {
+               for(int i = 0; i < len; i++)
+               {
+                  write(b[off + i]);
+               }
+            }
+         });
+      }
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public InputStream unwrap(InputStream in)
+      {
+         return (new FilterInputStream(in)
+         {
+            /*******************************************************************************
+             ** {@inheritDoc}
+             *******************************************************************************/
+            @Override
+            public int read() throws IOException
+            {
+               int b = super.read();
+               return (b < 0 ? b : (b ^ key) & 0xFF);
+            }
+
+
+
+            /*******************************************************************************
+             ** {@inheritDoc}
+             *******************************************************************************/
+            @Override
+            public int read(byte[] b, int off, int len) throws IOException
+            {
+               int n = super.read(b, off, len);
+               for(int i = 0; i < n; i++)
+               {
+                  b[off + i] = (byte) ((b[off + i] ^ key) & 0xFF);
+               }
+               return (n);
+            }
+         });
+      }
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public boolean encrypts()
+      {
+         return (true);
+      }
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public String keySuffix()
+      {
+         return (".xor");
+      }
+   }
+}

src/test/java/com/kingsrook/qbits/backups/alerts/AlertsQBitAlertSinkTest.java

@@ -0,0 +1,215 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.alerts;
+
+
+import java.time.Duration;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.VerifyTestSupport;
+import com.kingsrook.qbits.backups.alerts.fakeapi.AlertsInstanceMetaData;
+import com.kingsrook.qbits.backups.alerts.fakeapi.QAlertTypeMetaData;
+import com.kingsrook.qbits.backups.alerts.fakeapi.QAlerts;
+import com.kingsrook.qbits.backups.sla.SlaChecker;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** The Alerts qbit adapter, bound reflectively.  The SPI is not in QQQ 4.1.0-RC.4,
+ ** so these tests run it against a test double with the same shape as the real
+ ** com.kingsrook.qqq.backend.core.alerts package (QRun-IO/qqq PR #1108).
+ *******************************************************************************/
+class AlertsQBitAlertSinkTest
+{
+   private static final String FAKE_API = "com.kingsrook.qbits.backups.alerts.fakeapi";
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @BeforeEach
+   void setUp() throws Exception
+   {
+      VerifyTestSupport.setUp(3);
+      QAlerts.reset();
+      QAlertTypeMetaData.ADDED.clear();
+      AlertsInstanceMetaData.installed = true;
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @AfterEach
+   void tearDown()
+   {
+      AlertsInstanceMetaData.installed = false;
+      QAlerts.reset();
+   }
+
+
+
+   /*******************************************************************************
+    ** Raise, resolve and heartbeat reach the SPI with the stable dedupe key, the
+    ** severity mapped by name, and the detail as the summary and attributes.
+    *******************************************************************************/
+   @Test
+   void testRaiseResolveHeartbeat()
+   {
+      AlertsQBitAlertSink sink = new AlertsQBitAlertSink(FAKE_API);
+      Map<String, String> detail = new LinkedHashMap<>();
+      detail.put("plan", "nightly");
+      detail.put("slaHours", "26");
+
+      sink.raise("backups.plan.missed", "backups.plan.missed:nightly", BackupAlertSink.Severity.CRITICAL, "A backup did not run in time", detail);
+      sink.resolve("backups.plan.missed", "backups.plan.missed:nightly");
+      sink.heartbeat("backups.plan:nightly", 93600, 0);
+
+      assertThat(QAlerts.RAISED).hasSize(1);
+      var signal = QAlerts.RAISED.get(0);
+      assertThat(signal.alertTypeName).isEqualTo("backups.plan.missed");
+      assertThat(signal.dedupKey).isEqualTo("backups.plan.missed:nightly");
+      assertThat(signal.severity.name()).isEqualTo("CRITICAL");
+      assertThat(signal.title).isEqualTo("A backup did not run in time");
+      assertThat(signal.summary).isEqualTo("plan=nightly, slaHours=26");
+      assertThat(signal.attributes).containsEntry("plan", "nightly").containsEntry("slaHours", "26");
+      assertThat(QAlerts.RESOLVED).containsExactly("backups.plan.missed|backups.plan.missed:nightly|Cleared by the Backups qbit");
+      assertThat(QAlerts.HEARTBEATS).containsExactly("backups.plan:nightly");
+
+      sink.raise("backups.storage.debris", "k", BackupAlertSink.Severity.INFO, "no detail", null);
+      assertThat(QAlerts.RAISED.get(1).summary).isNull();
+   }
+
+
+
+   /*******************************************************************************
+    ** Without the Alerts qbit installed (no alerts meta-data on the instance) every
+    ** call is a no-op.
+    *******************************************************************************/
+   @Test
+   void testNoOpWithoutTheAlertsQBit()
+   {
+      AlertsInstanceMetaData.installed = false;
+      AlertsQBitAlertSink sink = new AlertsQBitAlertSink(FAKE_API);
+      sink.raise("t", "k", BackupAlertSink.Severity.INFO, "x", Map.of());
+      sink.resolve("t", "k");
+      sink.heartbeat("m", 1, 1);
+      assertThat(QAlerts.RAISED).isEmpty();
+      assertThat(QAlerts.RESOLVED).isEmpty();
+      assertThat(QAlerts.HEARTBEATS).isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** A broken or missing SPI never throws into the backup.
+    *******************************************************************************/
+   @Test
+   void testFailuresAreSwallowed()
+   {
+      AlertsQBitAlertSink missing = new AlertsQBitAlertSink("no.such.package");
+      missing.raise("t", "k", BackupAlertSink.Severity.INFO, "x", Map.of());
+      missing.resolve("t", "k");
+      missing.heartbeat("m", 1, 1);
+      assertThat(missing.registerAlertTypes(QContext.getQInstance())).isZero();
+
+      QAlerts.failWith = new IllegalStateException("alerts down");
+      AlertsQBitAlertSink broken = new AlertsQBitAlertSink(FAKE_API);
+      broken.raise("t", "k", BackupAlertSink.Severity.INFO, "x", Map.of());
+      broken.resolve("t", "k");
+      broken.heartbeat("m", 1, 1);
+      assertThat(QAlerts.RAISED).isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** The backup alert types are declared with the Alerts qbit.
+    *******************************************************************************/
+   @Test
+   void testRegisterAlertTypes()
+   {
+      int added = new AlertsQBitAlertSink(FAKE_API).registerAlertTypes(QContext.getQInstance());
+      assertThat(added).isEqualTo(BackupAlerts.alertTypes().size()).isEqualTo(9);
+      assertThat(QAlertTypeMetaData.ADDED).extracting(t -> t.name).containsExactly(
+         "backups.plan.missed", "backups.run.failed", "backups.run.missing_in_storage", "backups.files.missing", "backups.verify.failed",
+         "backups.verify.overdue", "backups.plan.owner_invalid", "backups.storage.debris", "backups.restore.completed");
+      assertThat(QAlertTypeMetaData.ADDED).allSatisfy(t ->
+      {
+         assertThat(t.groupName).isEqualTo("Backups");
+         assertThat(t.howToFix).isNotBlank();
+         assertThat(t.label).isNotBlank();
+      });
+      assertThat(QAlertTypeMetaData.ADDED.get(2).defaultSeverity.name()).isEqualTo("CRITICAL");
+   }
+
+
+
+   /*******************************************************************************
+    ** Detection: the SPI is present or not by class name; the real SPI is not in
+    ** RC.4, so nothing is bound by default there.
+    *******************************************************************************/
+   @Test
+   void testDetectionAndBinding()
+   {
+      assertThat(AlertsQBitAlertSink.isPresent(FAKE_API)).isTrue();
+      assertThat(AlertsQBitAlertSink.isPresent("no.such.package")).isFalse();
+
+      boolean realSpiPresent = AlertsQBitAlertSink.isPresent(AlertsQBitAlertSink.DEFAULT_API_PACKAGE);
+      assertThat(AlertsQBitAlertSink.bindIfPresent()).isEqualTo(realSpiPresent);
+      if(realSpiPresent)
+      {
+         assertThat(BackupsRuntime.getAlertSink()).isInstanceOf(AlertsQBitAlertSink.class);
+         assertThat(AlertsQBitAlertSink.bindIfPresent()).as("an already bound sink is not replaced").isFalse();
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** End to end: the SLA checker's alerts reach the Alerts qbit SPI and resolve.
+    *******************************************************************************/
+   @Test
+   void testSlaAlertsThroughTheAdapter() throws Exception
+   {
+      BackupsRuntime.setAlertSink(new AlertsQBitAlertSink(FAKE_API));
+      QRecord plan = VerifyTestSupport.plan(Map.of());
+      VerifyTestSupport.backup(plan);
+      assertThat(QAlerts.HEARTBEATS).contains("backups.plan:nightly");
+
+      VerifyTestSupport.clock.advance(Duration.ofHours(30));
+      new SlaChecker().check(VerifyTestSupport.reload(plan));
+      assertThat(QAlerts.RAISED).anySatisfy(s ->
+      {
+         assertThat(s.alertTypeName).isEqualTo("backups.plan.missed");
+         assertThat(s.dedupKey).isEqualTo("backups.plan.missed:nightly");
+         assertThat(s.severity.name()).isEqualTo("ERROR");
+      });
+
+      VerifyTestSupport.backup(plan);
+      new SlaChecker().check(VerifyTestSupport.reload(plan));
+      assertThat(QAlerts.RESOLVED).anyMatch(r -> r.startsWith("backups.plan.missed|backups.plan.missed:nightly|"));
+   }
+}

src/test/java/com/kingsrook/qbits/backups/alerts/BackupAlertsTest.java

@@ -0,0 +1,155 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.alerts;
+
+
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.RecordingAlertSink;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** The alert catalog and its helpers: the spec table, stable dedupe keys, and
+ ** helpers that never throw into the caller.
+ *******************************************************************************/
+class BackupAlertsTest
+{
+   private RecordingAlertSink sink;
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @BeforeEach
+   void setUp()
+   {
+      BackupsRuntime.reset();
+      sink = new RecordingAlertSink();
+      BackupsRuntime.setAlertSink(sink);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @AfterEach
+   void tearDown()
+   {
+      BackupsRuntime.reset();
+   }
+
+
+
+   /*******************************************************************************
+    ** Every alert of the spec table (section 10.4) is declared, once, with a default
+    ** severity and a way to fix it.
+    *******************************************************************************/
+   @Test
+   void testTheSpecTable()
+   {
+      Set<String> names = BackupAlerts.alertTypes().stream().map(BackupAlerts.AlertType::name).collect(Collectors.toSet());
+      assertThat(names).containsExactlyInAnyOrder("backups.plan.missed", "backups.run.failed", "backups.run.missing_in_storage", "backups.files.missing",
+         "backups.verify.failed", "backups.verify.overdue", "backups.plan.owner_invalid", "backups.storage.debris", "backups.restore.completed");
+      assertThat(BackupAlerts.alertTypes()).allSatisfy(t -> assertThat(t.howToFix()).isNotBlank());
+      assertThat(BackupAlerts.alertTypes().stream().filter(t -> t.name().equals(BackupAlerts.RUN_MISSING)).findFirst().orElseThrow().defaultSeverity())
+         .isEqualTo(BackupAlertSink.Severity.CRITICAL);
+   }
+
+
+
+   /*******************************************************************************
+    ** Dedupe keys are the type plus the plan (or plan and level), never a value.
+    *******************************************************************************/
+   @Test
+   void testStableKeys()
+   {
+      assertThat(BackupAlerts.key(BackupAlerts.PLAN_MISSED, "nightly")).isEqualTo("backups.plan.missed:nightly");
+      assertThat(BackupAlerts.verifyKey("nightly", "CONTENT")).isEqualTo("backups.verify.failed:nightly:CONTENT");
+
+      BackupAlerts.raise(BackupAlerts.FILES_MISSING, "nightly", BackupAlertSink.Severity.WARNING, "t", "missing", "3", "odd");
+      BackupAlerts.raise(BackupAlerts.FILES_MISSING, "nightly", BackupAlertSink.Severity.WARNING, "t", "missing", "4");
+      assertThat(sink.raises).hasSize(2).allSatisfy(r -> assertThat(r.dedupeKey()).isEqualTo("backups.files.missing:nightly"));
+      assertThat(sink.raises.get(0).detail()).containsExactly(Map.entry("missing", "3"));
+      assertThat(sink.open).hasSize(1);
+
+      BackupAlerts.resolve(BackupAlerts.FILES_MISSING, "nightly");
+      assertThat(sink.open).isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** A restore is never silent: info, or error when it failed.
+    *******************************************************************************/
+   @Test
+   void testRestoreCompleted()
+   {
+      BackupAlerts.restoreCompleted("20261012T030000Z-r1", "SUCCEEDED", "nightly", 42);
+      BackupAlerts.restoreCompleted("20261012T030000Z-r2", "FAILED", null, 0);
+      assertThat(sink.raises).extracting(RecordingAlertSink.Raised::severity).containsExactly(BackupAlertSink.Severity.INFO, BackupAlertSink.Severity.ERROR);
+      assertThat(sink.raises.get(0).detail()).containsEntry("rows", "42").containsEntry("plan", "nightly");
+      assertThat(sink.raises.get(0).type()).isEqualTo("backups.restore.completed");
+   }
+
+
+
+   /*******************************************************************************
+    ** A sink that throws never fails the caller.
+    *******************************************************************************/
+   @Test
+   void testASinkThatThrowsIsSwallowed()
+   {
+      BackupsRuntime.setAlertSink(new NoOpBackupAlertSink()
+      {
+         /*******************************************************************************
+          ** {@inheritDoc}
+          *******************************************************************************/
+         @Override
+         public void raise(String type, String dedupeKey, Severity severity, String title, Map<String, String> detail)
+         {
+            throw (new IllegalStateException("down"));
+         }
+
+
+
+         /*******************************************************************************
+          ** {@inheritDoc}
+          *******************************************************************************/
+         @Override
+         public void resolve(String type, String dedupeKey)
+         {
+            throw (new IllegalStateException("down"));
+         }
+      });
+      BackupAlerts.raise("t", "p", BackupAlertSink.Severity.INFO, "x");
+      BackupAlerts.raiseWithKey("t", "k", BackupAlertSink.Severity.INFO, "x", Map.of());
+      BackupAlerts.resolve("t", "p");
+      BackupAlerts.resolveKey("t", "k");
+
+      new NoOpBackupAlertSink().raise("t", "k", BackupAlertSink.Severity.INFO, "x", Map.of());
+      new NoOpBackupAlertSink().resolve("t", "k");
+      new NoOpBackupAlertSink().heartbeat("m", 1, 1);
+   }
+}

src/test/java/com/kingsrook/qbits/backups/alerts/fakeapi/AlertSeverity.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.alerts.fakeapi;
+
+
+/*******************************************************************************
+ ** Test double of the Alerts producer SPI (QRun-IO/qqq PR #1108): the same shape as
+ ** com.kingsrook.qqq.backend.core.alerts.AlertSeverity.
+ *******************************************************************************/
+public enum AlertSeverity
+{
+   INFO,
+   WARNING,
+   ERROR,
+   CRITICAL
+}

src/test/java/com/kingsrook/qbits/backups/alerts/fakeapi/AlertSignal.java

@@ -0,0 +1,96 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.alerts.fakeapi;
+
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+
+/*******************************************************************************
+ ** Test double of the Alerts producer SPI AlertSignal (only what the adapter uses).
+ *******************************************************************************/
+public class AlertSignal
+{
+   public final String              alertTypeName;
+   public       String              dedupKey;
+   public       AlertSeverity       severity;
+   public       String              title;
+   public       String              summary;
+   public final Map<String, String> attributes = new LinkedHashMap<>();
+
+
+
+   /*******************************************************************************
+    ** Constructor.
+    *******************************************************************************/
+   public AlertSignal(String alertTypeName)
+   {
+      this.alertTypeName = alertTypeName;
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter.
+    *******************************************************************************/
+   public void setDedupKey(String dedupKey)
+   {
+      this.dedupKey = dedupKey;
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter.
+    *******************************************************************************/
+   public void setSeverity(AlertSeverity severity)
+   {
+      this.severity = severity;
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter.
+    *******************************************************************************/
+   public void setTitle(String title)
+   {
+      this.title = title;
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter.
+    *******************************************************************************/
+   public void setSummary(String summary)
+   {
+      this.summary = summary;
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent attribute.
+    *******************************************************************************/
+   public AlertSignal withAttribute(String key, String value)
+   {
+      attributes.put(key, value);
+      return (this);
+   }
+}

src/test/java/com/kingsrook/qbits/backups/alerts/fakeapi/AlertsInstanceMetaData.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.alerts.fakeapi;
+
+
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+
+
+/*******************************************************************************
+ ** Test double of the Alerts producer SPI AlertsInstanceMetaData: of(instance) is
+ ** non-null only when a test says the Alerts qbit is installed.
+ *******************************************************************************/
+public class AlertsInstanceMetaData
+{
+   public static boolean installed = false;
+
+
+
+   /*******************************************************************************
+    ** The alerts meta-data of an instance, or null.
+    *******************************************************************************/
+   public static AlertsInstanceMetaData of(QInstance qInstance)
+   {
+      return (installed ? new AlertsInstanceMetaData() : null);
+   }
+}

src/test/java/com/kingsrook/qbits/backups/alerts/fakeapi/QAlertTypeMetaData.java

@@ -0,0 +1,103 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.alerts.fakeapi;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+
+
+/*******************************************************************************
+ ** Test double of the Alerts producer SPI QAlertTypeMetaData: records the types
+ ** added to an instance.
+ *******************************************************************************/
+public class QAlertTypeMetaData
+{
+   public static final List<QAlertTypeMetaData> ADDED = new ArrayList<>();
+
+   public String        name;
+   public String        label;
+   public String        groupName;
+   public String        howToFix;
+   public AlertSeverity defaultSeverity;
+
+
+
+   /*******************************************************************************
+    ** Fluent.
+    *******************************************************************************/
+   public QAlertTypeMetaData withName(String name)
+   {
+      this.name = name;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent.
+    *******************************************************************************/
+   public QAlertTypeMetaData withLabel(String label)
+   {
+      this.label = label;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent.
+    *******************************************************************************/
+   public QAlertTypeMetaData withGroupName(String groupName)
+   {
+      this.groupName = groupName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent.
+    *******************************************************************************/
+   public QAlertTypeMetaData withHowToFix(String howToFix)
+   {
+      this.howToFix = howToFix;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent.
+    *******************************************************************************/
+   public QAlertTypeMetaData withDefaultSeverity(AlertSeverity defaultSeverity)
+   {
+      this.defaultSeverity = defaultSeverity;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Add to the instance (recorded).
+    *******************************************************************************/
+   public void addSelfToInstance(QInstance qInstance)
+   {
+      ADDED.add(this);
+   }
+}

src/test/java/com/kingsrook/qbits/backups/alerts/fakeapi/QAlerts.java

@@ -0,0 +1,104 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.alerts.fakeapi;
+
+
+import java.util.ArrayList;
+import java.util.List;
+
+
+/*******************************************************************************
+ ** Test double of the Alerts producer SPI QAlerts: static calls that record what
+ ** they were given.
+ *******************************************************************************/
+public final class QAlerts
+{
+   public static final List<AlertSignal> RAISED     = new ArrayList<>();
+   public static final List<String>      RESOLVED   = new ArrayList<>();
+   public static final List<String>      HEARTBEATS = new ArrayList<>();
+
+   /** When set, every call throws it (the SPI is meant not to, but the adapter must survive). */
+   public static RuntimeException failWith;
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private QAlerts()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Forget everything.
+    *******************************************************************************/
+   public static void reset()
+   {
+      RAISED.clear();
+      RESOLVED.clear();
+      HEARTBEATS.clear();
+      failWith = null;
+   }
+
+
+
+   /*******************************************************************************
+    ** Raise.
+    *******************************************************************************/
+   public static void raise(AlertSignal signal)
+   {
+      maybeFail();
+      RAISED.add(signal);
+   }
+
+
+
+   /*******************************************************************************
+    ** Resolve.
+    *******************************************************************************/
+   public static void resolve(String alertTypeName, String dedupKey, String note)
+   {
+      maybeFail();
+      RESOLVED.add(alertTypeName + "|" + dedupKey + "|" + note);
+   }
+
+
+
+   /*******************************************************************************
+    ** Heartbeat.
+    *******************************************************************************/
+   public static void heartbeat(String heartbeatKey)
+   {
+      maybeFail();
+      HEARTBEATS.add(heartbeatKey);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static void maybeFail()
+   {
+      if(failWith != null)
+      {
+         throw (failWith);
+      }
+   }
+}

src/test/java/com/kingsrook/qbits/backups/events/BackupEventsTest.java

@@ -0,0 +1,137 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.events;
+
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.BackupsTestUtils;
+import com.kingsrook.qbits.backups.VerifyTestSupport;
+import com.kingsrook.qbits.backups.run.BackupRunResult;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** ESB events are fire and forget: published for run outcomes, never allowed to
+ ** fail a backup, and silent when no destination is configured.
+ *******************************************************************************/
+class BackupEventsTest
+{
+   private final List<String>                    types = new ArrayList<>();
+   private final List<Map<String, Serializable>> datas = new ArrayList<>();
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @BeforeEach
+   void setUp() throws Exception
+   {
+      VerifyTestSupport.setUp(3);
+      BackupEvents.setPublisher((type, data) ->
+      {
+         types.add(type);
+         datas.add(data);
+      });
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @AfterEach
+   void tearDown()
+   {
+      BackupEvents.setPublisher(null);
+   }
+
+
+
+   /*******************************************************************************
+    ** A successful run publishes run.succeeded; a failed one run.failed.
+    *******************************************************************************/
+   @Test
+   void testRunEvents() throws Exception
+   {
+      QRecord         plan   = VerifyTestSupport.plan(Map.of());
+      BackupRunResult result = VerifyTestSupport.backup(plan);
+      assertThat(types).containsExactly("qqq.backups.run.succeeded");
+      assertThat(datas.get(0)).containsEntry("plan", "nightly").containsEntry("run", result.getRunKey()).containsEntry("rows", result.getRows());
+
+      BackupsTestUtils.BACKUPS.withFailWritesFor(key -> key.contains("/tables/"));
+      VerifyTestSupport.backup(plan);
+      assertThat(types).containsExactly("qqq.backups.run.succeeded", "qqq.backups.run.failed");
+   }
+
+
+
+   /*******************************************************************************
+    ** Cancelled runs publish nothing; restores publish restore.completed.
+    *******************************************************************************/
+   @Test
+   void testCancelledAndRestore()
+   {
+      BackupEvents.runFinished("nightly", "r1", "CANCELLED", 0, 0);
+      BackupEvents.runFinished("nightly", "r2", "TIMED_OUT", 0, 0);
+      BackupEvents.restoreCompleted("rr1", "SUCCEEDED", 12);
+      assertThat(types).containsExactly("qqq.backups.run.failed", "qqq.backups.restore.completed");
+      assertThat(datas.get(1)).containsEntry("restoreRun", "rr1").containsEntry("rows", 12L);
+   }
+
+
+
+   /*******************************************************************************
+    ** A publisher that throws never fails the run.
+    *******************************************************************************/
+   @Test
+   void testPublishFailureNeverFailsTheBackup() throws Exception
+   {
+      BackupEvents.setPublisher((type, data) ->
+      {
+         throw (new IllegalStateException("bus down"));
+      });
+      BackupRunResult result = VerifyTestSupport.backup(VerifyTestSupport.plan(Map.of()));
+      assertThat(result.getStatus()).startsWith("SUCCEEDED");
+   }
+
+
+
+   /*******************************************************************************
+    ** With no destination configured nothing is published; with one, the ESB is
+    ** tried and a missing or unconfigured ESB is swallowed.
+    *******************************************************************************/
+   @Test
+   void testEsbDefault() throws Exception
+   {
+      BackupEvents.setPublisher(null);
+      BackupEvents.publish("qqq.backups.run.succeeded", Map.of());
+
+      BackupsRuntime.getConfig().withEsbDestinationName("backups-events");
+      BackupEvents.publish("qqq.backups.run.succeeded", Map.of("plan", "nightly"));
+      BackupEvents.publish("qqq.backups.run.succeeded", Map.of("plan", "nightly"));
+      assertThat(VerifyTestSupport.backup(VerifyTestSupport.plan(Map.of())).getStatus()).startsWith("SUCCEEDED");
+   }
+}

src/test/java/com/kingsrook/qbits/backups/health/BackupsHealthIndicatorTest.java

@@ -0,0 +1,119 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.health;
+
+
+import java.util.Map;
+import com.kingsrook.qbits.backups.VerifyTestSupport;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.middleware.health.model.metadata.HealthCheckResult;
+import com.kingsrook.qqq.middleware.health.model.metadata.HealthStatus;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** The health indicator: DOWN only when a critical, active plan is LATE, FAILING or
+ ** MISSING_IN_STORAGE.
+ *******************************************************************************/
+class BackupsHealthIndicatorTest
+{
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @BeforeEach
+   void setUp() throws Exception
+   {
+      VerifyTestSupport.setUp(3);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void setStatus(QRecord plan, String status) throws Exception
+   {
+      new BackupCatalog().update(BackupsTables.PLAN, plan.getValueInteger("id"), Map.of("slaStatus", status));
+   }
+
+
+
+   /*******************************************************************************
+    ** UP with details when nothing critical is wrong, including a non-critical plan
+    ** that is LATE; DOWN when a critical plan is LATE, FAILING or MISSING_IN_STORAGE.
+    *******************************************************************************/
+   @Test
+   void testUpAndDown() throws Exception
+   {
+      BackupsHealthIndicator indicator = new BackupsHealthIndicator();
+      assertThat(indicator.getName()).isEqualTo("backups");
+
+      HealthCheckResult empty = indicator.check(QContext.getQInstance());
+      assertThat(empty.getStatus()).isEqualTo(HealthStatus.UP);
+      assertThat(empty.getDetails()).containsEntry("activePlans", 0);
+
+      QRecord critical = VerifyTestSupport.plan(Map.of("critical", true));
+      QRecord ordinary = VerifyTestSupport.plan(Map.of("name", "Other", "planKey", "other"));
+      VerifyTestSupport.plan(Map.of("name", "Off", "planKey", "off", "isActive", false, "critical", true));
+
+      setStatus(critical, "OK");
+      setStatus(ordinary, "LATE");
+      HealthCheckResult up = indicator.check(QContext.getQInstance());
+      assertThat(up.getStatus()).isEqualTo(HealthStatus.UP);
+      assertThat(up.getDetails()).containsEntry("activePlans", 2).doesNotContainKey("criticalPlansWithProblems");
+      assertThat(up.getDurationMs()).isNotNull();
+
+      for(String status : new String[] { "LATE", "FAILING", "MISSING_IN_STORAGE" })
+      {
+         setStatus(critical, status);
+         HealthCheckResult down = indicator.check(QContext.getQInstance());
+         assertThat(down.getStatus()).as(status).isEqualTo(HealthStatus.DOWN);
+         assertThat(down.getDetails().get("criticalPlansWithProblems").toString()).contains("nightly: " + status);
+      }
+
+      setStatus(critical, "UNVERIFIED");
+      assertThat(indicator.check(QContext.getQInstance()).getStatus()).as("not verified is not down").isEqualTo(HealthStatus.UP);
+   }
+
+
+
+   /*******************************************************************************
+    ** On a thread with no QQQ context (a health request) the indicator makes its own
+    ** and cleans up.
+    *******************************************************************************/
+   @Test
+   void testWorksWithoutAContext() throws Exception
+   {
+      QInstance qInstance = QContext.getQInstance();
+      QContext.clear();
+      try
+      {
+         assertThat(new BackupsHealthIndicator().check(qInstance).getStatus()).isEqualTo(HealthStatus.UP);
+         assertThat(QContext.getQInstance()).isNull();
+      }
+      finally
+      {
+         QContext.init(qInstance, new com.kingsrook.qqq.backend.core.model.session.QSession());
+      }
+   }
+}

src/test/java/com/kingsrook/qbits/backups/metrics/BackupsMetricsTest.java

@@ -0,0 +1,99 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.metrics;
+
+
+import java.time.Duration;
+import java.util.Map;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.BackupsTestUtils;
+import com.kingsrook.qbits.backups.VerifyTestSupport;
+import com.kingsrook.qbits.backups.run.BackupRunResult;
+import com.kingsrook.qbits.backups.verify.BackupVerifier;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** The Prometheus text, computed from the tables.
+ *******************************************************************************/
+class BackupsMetricsTest
+{
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @BeforeEach
+   void setUp() throws Exception
+   {
+      VerifyTestSupport.setUp(3);
+   }
+
+
+
+   /*******************************************************************************
+    ** The five gauges, labeled with the instance and the plan, from real runs.
+    *******************************************************************************/
+   @Test
+   void testRender() throws Exception
+   {
+      QRecord         plan   = VerifyTestSupport.plan(Map.of());
+      BackupRunResult result = VerifyTestSupport.backup(plan);
+      new BackupVerifier().verify(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t");
+
+      String text   = BackupsMetrics.render();
+      String labels = "{instance_name=\"testapp\",plan=\"nightly\"}";
+      long   now    = VerifyTestSupport.clock.instant().getEpochSecond();
+      assertThat(text).contains("# TYPE qqq_backup_last_success_timestamp_seconds gauge")
+         .contains("qqq_backup_last_success_timestamp_seconds" + labels + " " + now + "\n")
+         .contains("qqq_backup_last_run_failed" + labels + " 0\n")
+         .contains("qqq_backup_sla_seconds" + labels + " 93600\n")
+         .contains("qqq_backup_last_verify_success_timestamp_seconds" + labels + " " + now + "\n")
+         .contains("qqq_backup_last_success_bytes" + labels + " ");
+
+      BackupsTestUtils.BACKUPS.withFailWritesFor(key -> key.contains("/tables/"));
+      VerifyTestSupport.backup(plan);
+      assertThat(BackupsMetrics.render()).contains("qqq_backup_last_run_failed" + labels + " 1\n");
+   }
+
+
+
+   /*******************************************************************************
+    ** Cached for 60 seconds; label values are escaped; the config flag is read.
+    *******************************************************************************/
+   @Test
+   void testCacheEscapeAndFlag() throws Exception
+   {
+      assertThat(BackupsMetrics.isEnabled()).isFalse();
+      BackupsRuntime.getConfig().withPrometheusEndpoint(true);
+      assertThat(BackupsMetrics.isEnabled()).isTrue();
+      assertThat(BackupsMetrics.ENDPOINT_PATH).isEqualTo("/metrics/backups");
+
+      String empty = BackupsMetrics.renderCached();
+      assertThat(empty).doesNotContain("{instance_name");
+
+      VerifyTestSupport.backup(VerifyTestSupport.plan(Map.of()));
+      VerifyTestSupport.clock.advance(Duration.ofSeconds(30));
+      assertThat(BackupsMetrics.renderCached()).as("cached").isEqualTo(empty);
+      VerifyTestSupport.clock.advance(Duration.ofSeconds(31));
+      assertThat(BackupsMetrics.renderCached()).contains("plan=\"nightly\"");
+
+      assertThat(BackupsMetrics.escape("a\"b\\c\nd")).isEqualTo("a\\\"b\\\\c\\nd");
+      assertThat(BackupsMetrics.escape(null)).isEmpty();
+   }
+}

src/test/java/com/kingsrook/qbits/backups/processes/VerifyProcessesTest.java

@@ -0,0 +1,207 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.processes;
+
+
+import java.io.Serializable;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.backups.BackupsQBitConfig;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.BackupsTestUtils;
+import com.kingsrook.qbits.backups.VerifyTestSupport;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.permissions.BackupsPermissions;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qbits.backups.run.BackupRunResult;
+import com.kingsrook.qqq.backend.core.actions.processes.RunProcessAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLine;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLineInterface;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessOutput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.Status;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.StreamedETLWithFrontendProcess;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** The Verify backup record action (a streamed ETL with Review and Result lines)
+ ** and the scheduled SLA check.
+ *******************************************************************************/
+class VerifyProcessesTest
+{
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @BeforeEach
+   void setUp() throws Exception
+   {
+      VerifyTestSupport.setUp(7);
+   }
+
+
+
+   /*******************************************************************************
+    ** Both processes are defined on the instance with the right permissions; neither
+    ** is in the nav, and the label is plain.
+    *******************************************************************************/
+   @Test
+   void testDefinitions()
+   {
+      QProcessMetaData verify = QContext.getQInstance().getProcess(VerifyProcesses.VERIFY);
+      assertThat(verify).isNotNull();
+      assertThat(verify.getLabel()).isEqualTo("Verify backup");
+      assertThat(verify.getTableName()).isEqualTo(BackupsTables.RUN);
+      assertThat(QContext.getQInstance().getProcess(VerifyProcesses.CHECK_SLA)).isNotNull();
+      assertThat(BackupsRuntime.processPermissions()).containsEntry("backupVerify", BackupsPermissions.RUN).containsEntry("backupCheckSla", BackupsPermissions.RUN);
+   }
+
+
+
+   /*******************************************************************************
+    ** The SLA check is scheduled every slaCheckIntervalSeconds when a scheduler is
+    ** configured, independent of any backup trigger; otherwise it is unscheduled.
+    *******************************************************************************/
+   @Test
+   void testSlaCheckSchedule()
+   {
+      assertThat(VerifyProcesses.checkSlaProcess(BackupsRuntime.getConfig()).getSchedule()).isNull();
+      assertThat(VerifyProcesses.checkSlaProcess(null).getSchedule()).isNull();
+
+      BackupsQBitConfig scheduled = new BackupsQBitConfig().withBackendName("memory").withSchedulerName("quartz").withSlaCheckIntervalSeconds(120);
+      QProcessMetaData  process   = VerifyProcesses.checkSlaProcess(scheduled);
+      assertThat(process.getSchedule().getSchedulerName()).isEqualTo("quartz");
+      assertThat(process.getSchedule().getRepeatSeconds()).isEqualTo(120);
+      assertThat(process.getSchedule().getCronExpression()).isNull();
+   }
+
+
+
+   /*******************************************************************************
+    ** The scheduled step checks every active plan.
+    *******************************************************************************/
+   @Test
+   void testCheckSlaStep() throws Exception
+   {
+      VerifyTestSupport.backup(VerifyTestSupport.plan(Map.of()));
+      VerifyTestSupport.plan(Map.of("name", "Late", "planKey", "late", "storageBucketAlias", "backups"));
+      VerifyTestSupport.clock.advance(java.time.Duration.ofHours(30));
+
+      RunProcessInput input = new RunProcessInput();
+      input.setProcessName(VerifyProcesses.CHECK_SLA);
+      input.setFrontendStepBehavior(RunProcessInput.FrontendStepBehavior.SKIP);
+      RunProcessOutput output = new RunProcessAction().execute(input);
+      assertThat(output.getException()).isEmpty();
+      assertThat(output.getValues()).containsEntry("plansChecked", 2).containsEntry("plansNeedingAttention", 2L);
+      assertThat(new BackupCatalog().where(BackupsTables.PLAN, "planKey", "late").get(0).getValueString("slaStatus")).isEqualTo("LATE");
+   }
+
+
+
+   /*******************************************************************************
+    ** Verify backup on a good run: Review lists what will be checked without reading
+    ** anything; the run passes, and the Result lines link back to the run.
+    *******************************************************************************/
+   @Test
+   void testVerifyGoodRun() throws Exception
+   {
+      BackupRunResult result = VerifyTestSupport.backup(VerifyTestSupport.plan(Map.of()));
+      assertThat(new BackupCatalog().where(BackupsTables.VERIFICATION, "backupRunId", result.getRunId())).isEmpty();
+
+      RunProcessInput  input  = input(result.getRunId());
+      RunProcessOutput output = new RunProcessAction().execute(input);
+      List<ProcessSummaryLineInterface> review = lines(output, StreamedETLWithFrontendProcess.FIELD_VALIDATION_SUMMARY);
+      assertThat(review).extracting(l -> ((ProcessSummaryLine) l).getStatus()).contains(Status.OK, Status.INFO);
+      assertThat(new BackupCatalog().where(BackupsTables.VERIFICATION, "backupRunId", result.getRunId())).as("Review reads nothing and writes nothing").isEmpty();
+
+      input.setStartAfterStep("review");
+      output = new RunProcessAction().execute(input);
+      assertThat(output.getException()).isEmpty();
+      List<ProcessSummaryLineInterface> summary = lines(output, StreamedETLWithFrontendProcess.FIELD_PROCESS_SUMMARY);
+      ProcessSummaryLine ok = (ProcessSummaryLine) summary.stream().filter(l -> ((ProcessSummaryLine) l).getStatus() == Status.OK).findFirst().orElseThrow();
+      assertThat(ok.getCount()).isEqualTo(1);
+      assertThat(ok.getPrimaryKeys()).containsExactly(result.getRunId());
+      assertThat(new BackupCatalog().where(BackupsTables.VERIFICATION, "backupRunId", result.getRunId())).hasSize(2);
+      assertThat(VerifyTestSupport.run(result.getRunId()).getValueString("verificationStatus")).isEqualTo("CONTENT_OK");
+   }
+
+
+
+   /*******************************************************************************
+    ** A corrupted run fails with the first mismatch in the Result line; a run with no
+    ** manifest is refused at Review.
+    *******************************************************************************/
+   @Test
+   void testVerifyBadRunsAndRefusals() throws Exception
+   {
+      BackupRunResult result = VerifyTestSupport.backup(VerifyTestSupport.plan(Map.of()));
+      String          key    = VerifyTestSupport.firstPartKey(result, "blogPost");
+      byte[]          bytes  = BackupsTestUtils.BACKUPS.getBytes(key).clone();
+      bytes[bytes.length / 2] ^= 0x55;
+      BackupsTestUtils.BACKUPS.corrupt(key, bytes);
+
+      Integer          noManifest = new BackupCatalog().insert(BackupsTables.RUN, new java.util.LinkedHashMap<>(Map.<String, Serializable>of("runKey", "x1", "status", "FAILED")));
+      Integer          pruned     = new BackupCatalog().insert(BackupsTables.RUN, new java.util.LinkedHashMap<>(Map.<String, Serializable>of("runKey", "x2", "status", "SUCCEEDED", "manifestKey", "m", "prunedDate", java.time.Instant.now())));
+
+      RunProcessInput input = input(result.getRunId(), noManifest, pruned);
+      input.addValue(VerifyProcesses.FIELD_VERIFY_LEVEL, "STORAGE");
+      RunProcessOutput output = new RunProcessAction().execute(input);
+      List<ProcessSummaryLineInterface> review = lines(output, StreamedETLWithFrontendProcess.FIELD_VALIDATION_SUMMARY);
+      assertThat(review.stream().filter(l -> ((ProcessSummaryLine) l).getStatus() == Status.ERROR)).hasSize(2);
+
+      input.addValue(VerifyProcesses.FIELD_VERIFY_LEVEL, "CONTENT");
+      input.setStartAfterStep("review");
+      output = new RunProcessAction().execute(input);
+      List<ProcessSummaryLineInterface> summary = lines(output, StreamedETLWithFrontendProcess.FIELD_PROCESS_SUMMARY);
+      ProcessSummaryLine failed = (ProcessSummaryLine) summary.stream().filter(l -> ((ProcessSummaryLine) l).getStatus() == Status.ERROR).findFirst().orElseThrow();
+      assertThat(failed.getCount()).isEqualTo(1);
+      assertThat(failed.getMessageSuffix()).contains("corrupted");
+      assertThat(VerifyTestSupport.run(result.getRunId()).getValueString("verificationStatus")).isEqualTo("FAILED");
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private RunProcessInput input(Integer... runIds)
+   {
+      RunProcessInput input = new RunProcessInput();
+      input.setProcessName(VerifyProcesses.VERIFY);
+      input.addValue(StreamedETLWithFrontendProcess.FIELD_DEFAULT_QUERY_FILTER, new QQueryFilter(new QFilterCriteria("id", QCriteriaOperator.IN, List.of((Serializable[]) runIds))));
+      return (input);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @SuppressWarnings("unchecked")
+   private List<ProcessSummaryLineInterface> lines(RunProcessOutput output, String field)
+   {
+      return ((List<ProcessSummaryLineInterface>) output.getValues().get(field));
+   }
+}

src/test/java/com/kingsrook/qbits/backups/restore/CatalogImportTest.java

@@ -0,0 +1,252 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.restore;
+
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.backups.BackupsTestUtils;
+import com.kingsrook.qbits.backups.codec.HashingOutputStream;
+import com.kingsrook.qbits.backups.manifest.BackupManifest;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qbits.backups.run.BackupRunResult;
+import com.kingsrook.qbits.backups.storage.StoredObjectInfo;
+import com.kingsrook.qqq.backend.core.actions.processes.RunProcessAction;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLine;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLineInterface;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessOutput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.Status;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.StreamedETLWithFrontendProcess;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** Import backups from storage (spec 9.6): the database with the catalog is gone,
+ ** a fresh instance imports the catalog from the manifests in storage and restores
+ ** from it, files included.
+ *******************************************************************************/
+class CatalogImportTest
+{
+   private String                originalPostsHash;
+   private BackupManifest        originalManifest;
+   private Map<String, byte[]>   snapshot;
+
+
+
+   /*******************************************************************************
+    ** Back up an instance, keep what is in the backup bucket, then start over: a fresh
+    ** instance (empty tables, empty catalog, empty media) that only has the bucket.
+    *******************************************************************************/
+   @BeforeEach
+   void setUp() throws Exception
+   {
+      BackupsTestUtils.init();
+      BackupsTestUtils.loadBlog(30);
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+      originalPostsHash = RestoreTestSupport.contentHash("blogPost");
+      originalManifest = RestoreTestSupport.manifest(run);
+
+      snapshot = new LinkedHashMap<>();
+      for(StoredObjectInfo info : BackupsTestUtils.BACKUPS.list(""))
+      {
+         snapshot.put(info.key(), BackupsTestUtils.BACKUPS.getBytes(info.key()));
+      }
+
+      BackupsTestUtils.init();
+      snapshot.forEach(BackupsTestUtils.BACKUPS::putBytes);
+      assertThat(new BackupCatalog().query(BackupsTables.RUN, new QQueryFilter())).as("a fresh catalog").isEmpty();
+      assertThat(RestoreTestSupport.rows("blogPost")).isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** The manifests are found, validated and imported (trigger IMPORTED), the content
+    ** addressed files are registered again, and importing twice changes nothing.
+    *******************************************************************************/
+   @Test
+   void testImportRebuildsTheCatalog() throws Exception
+   {
+      CatalogImporter importer = new CatalogImporter();
+      List<String>    keys     = importer.findManifestKeys(BackupsTestUtils.BACKUPS, "qqq-backups/");
+      assertThat(keys).hasSize(1);
+
+      CatalogImporter.Inspection inspection = importer.inspect(BackupsTestUtils.BACKUPS, keys.get(0));
+      assertThat(inspection.status()).isEqualTo(CatalogImporter.Inspection.NEW);
+      assertThat(inspection.manifestSha256()).isEqualTo(HashingOutputStream.sha256Hex(BackupsTestUtils.BACKUPS.getBytes(keys.get(0))));
+
+      Integer runId = importer.importRun("backups", BackupsTestUtils.BACKUPS, inspection);
+      QRecord run   = new BackupCatalog().get(BackupsTables.RUN, runId).orElseThrow();
+      assertThat(run.getValueString("trigger")).isEqualTo("IMPORTED");
+      assertThat(run.getValueString("runKey")).isEqualTo(originalManifest.runKey());
+      assertThat(run.getValueString("status")).isEqualTo("SUCCEEDED_WITH_WARNINGS");
+      assertThat(run.getValueString("manifestKey")).isEqualTo(keys.get(0));
+      assertThat(run.getValueString("manifestSha256")).isEqualTo(inspection.manifestSha256());
+      assertThat(run.getValueString("storageBucketAlias")).isEqualTo("backups");
+      assertThat(run.getValueString("instanceName")).isEqualTo("testapp");
+      assertThat(run.getValueLong("rowsTotal")).isEqualTo(originalManifest.totals().rows());
+      assertThat(run.getValueInteger("tablesPlanned")).isEqualTo(originalManifest.tables().size());
+      assertThat(run.getValueString("verificationStatus")).isEqualTo("UNVERIFIED");
+
+      List<QRecord> artifacts = new BackupCatalog().where(BackupsTables.ARTIFACT, "backupRunId", runId);
+      long parts = originalManifest.tables().stream().mapToLong(t -> t.parts().size()).sum();
+      assertThat(artifacts).hasSize((int) parts + 3);
+      assertThat(artifacts).extracting(a -> a.getValueString("artifactType")).contains("MANIFEST", "CHECKSUMS", "FILE_OBJECTS_INDEX", "TABLE_DATA");
+      QRecord posts = artifacts.stream().filter(a -> "blogPost".equals(a.getValueString("tableName"))).findFirst().orElseThrow();
+      assertThat(posts.getValueString("sha256Stored")).isEqualTo(originalManifest.table("blogPost").parts().get(0).sha256Stored());
+      assertThat(posts.getValueString("rowsHash")).isEqualTo(originalManifest.table("blogPost").rowsHash());
+
+      assertThat(new BackupCatalog().query(BackupsTables.FILE_OBJECT, new QQueryFilter())).as("the file store is registered again").hasSize(3);
+
+      assertThat(importer.inspect(BackupsTestUtils.BACKUPS, keys.get(0)).status()).isEqualTo(CatalogImporter.Inspection.EXISTS);
+      assertThat(new BackupCatalog().query(BackupsTables.RUN, new QQueryFilter())).hasSize(1);
+   }
+
+
+
+   /*******************************************************************************
+    ** The point of the catalog import: restore from the imported run into the fresh
+    ** instance and get the original rows (same hash) and the files (same checksum).
+    *******************************************************************************/
+   @Test
+   void testRestoreFromTheImportedCatalog() throws Exception
+   {
+      CatalogImporter importer = new CatalogImporter();
+      CatalogImporter.Inspection inspection = importer.inspect(BackupsTestUtils.BACKUPS, importer.findManifestKeys(BackupsTestUtils.BACKUPS, "qqq-backups/").get(0));
+      Integer runId = importer.importRun("backups", BackupsTestUtils.BACKUPS, inspection);
+
+      RestoreRequest request = new RestoreRequest().withSourceRunId(runId).withMode(RestoreRequest.MODE_INSERT_NEW).withRequestedBy("tester");
+      RestoreOutcome review = new RestoreEngine().review(request);
+      assertThat(review.getErrors()).isEmpty();
+      assertThat(review.getTables().get("author").getInserted()).isEqualTo(3);
+      assertThat(review.getTables().get("blogPost").getInserted()).isEqualTo(30);
+      assertThat(review.getTables().get("blogPost").getFilesToRestore()).isEqualTo(3);
+
+      RestoreOutcome outcome = new RestoreEngine().execute(request);
+      assertThat(outcome.getTables().get("blogPost").getInserted()).isEqualTo(30);
+      assertThat(outcome.getTables().get("blogPost").getFilesRestored()).isEqualTo(3);
+      assertThat(outcome.getFilesFailed()).isZero();
+
+      assertThat(RestoreTestSupport.rows("author")).hasSize(3);
+      assertThat(RestoreTestSupport.contentHash("blogPost")).isEqualTo(originalPostsHash);
+      for(int i = 0; i < 3; i++)
+      {
+         assertThat(new String(BackupsTestUtils.MEDIA.getBytes("media/photo-" + i + ".jpg"))).isEqualTo("photo bytes " + i);
+      }
+      assertThat(new BackupCatalog().where(BackupsTables.RESTORE_RUN, "sourceBackupRunId", runId)).hasSize(1);
+   }
+
+
+
+   /*******************************************************************************
+    ** A manifest whose parts are damaged is reported, not imported.
+    *******************************************************************************/
+   @Test
+   void testDamagedBackupsAreNotImported() throws Exception
+   {
+      CatalogImporter importer = new CatalogImporter();
+      String key = importer.findManifestKeys(BackupsTestUtils.BACKUPS, "qqq-backups/").get(0);
+      String partKey = key.substring(0, key.length() - "manifest.json".length()) + originalManifest.table("blogPost").parts().get(0).key();
+      BackupsTestUtils.BACKUPS.corrupt(partKey, new byte[] { 1, 2, 3 });
+
+      CatalogImporter.Inspection inspection = importer.inspect(BackupsTestUtils.BACKUPS, key);
+      assertThat(inspection.status()).isEqualTo(CatalogImporter.Inspection.INVALID);
+      assertThat(inspection.problems()).anyMatch(p -> p.contains("wrong size"));
+      assertThat(new BackupCatalog().query(BackupsTables.RUN, new QQueryFilter())).isEmpty();
+
+      BackupsTestUtils.BACKUPS.putBytes(key, "not a manifest".getBytes());
+      assertThat(importer.inspect(BackupsTestUtils.BACKUPS, key).problems()).anyMatch(p -> p.contains("cannot be read"));
+   }
+
+
+
+   /*******************************************************************************
+    ** Restore refuses a part that does not match its stored checksum.
+    *******************************************************************************/
+   @Test
+   void testRestoreRefusesADamagedPart() throws Exception
+   {
+      CatalogImporter importer = new CatalogImporter();
+      String key = importer.findManifestKeys(BackupsTestUtils.BACKUPS, "qqq-backups/").get(0);
+      Integer runId = importer.importRun("backups", BackupsTestUtils.BACKUPS, importer.inspect(BackupsTestUtils.BACKUPS, key));
+
+      String partKey = key.substring(0, key.length() - "manifest.json".length()) + originalManifest.table("author").parts().get(0).key();
+      byte[] same = BackupsTestUtils.BACKUPS.getBytes(partKey).clone();
+      same[same.length / 2] ^= 0x55;
+      BackupsTestUtils.BACKUPS.corrupt(partKey, same);
+
+      RestoreRequest request = new RestoreRequest().withSourceRunId(runId).withTables(List.of("author")).withMode(RestoreRequest.MODE_INSERT_NEW).withPreRestoreBackup(false);
+      assertThatThrownBy(() -> new RestoreEngine().execute(request)).hasMessageContaining("Could not read");
+      assertThat(RestoreTestSupport.rows("author")).isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** The import process: Review lists what will be added, Result says what was.
+    *******************************************************************************/
+   @Test
+   void testImportProcess() throws Exception
+   {
+      RunProcessInput input = new RunProcessInput();
+      input.setProcessName("backupImportCatalog");
+      input.addValue("bucketAlias", "backups");
+      input.addValue("prefix", "qqq-backups/");
+
+      RunProcessOutput output = new RunProcessAction().execute(input);
+      assertThat(output.getException()).isEmpty();
+      assertThat(output.getProcessState().getNextStepName()).isPresent().get().isEqualTo("input");
+      input.addValue("processUUID", output.getProcessUUID());
+
+      input.setStartAfterStep("input");
+      output = new RunProcessAction().execute(input);
+      assertThat(output.getException()).isEmpty();
+      List<ProcessSummaryLineInterface> review = RestoreProcessTest.lines(output, StreamedETLWithFrontendProcess.FIELD_VALIDATION_SUMMARY);
+      assertThat(RestoreTestSupport.line(review, false, "backup will be added to the catalog").getCount()).isEqualTo(1);
+      assertThat(new BackupCatalog().query(BackupsTables.RUN, new QQueryFilter())).as("Review writes nothing").isEmpty();
+
+      input.setStartAfterStep("review");
+      output = new RunProcessAction().execute(input);
+      assertThat(output.getException()).isEmpty();
+      List<ProcessSummaryLineInterface> result = RestoreProcessTest.lines(output, StreamedETLWithFrontendProcess.FIELD_PROCESS_SUMMARY);
+      ProcessSummaryLine imported = RestoreTestSupport.line(result, true, "backup was added to the catalog");
+      assertThat(imported.getCount()).isEqualTo(1);
+      assertThat(imported.getPrimaryKeys()).hasSize(1);
+      assertThat(new BackupCatalog().query(BackupsTables.RUN, new QQueryFilter())).hasSize(1);
+
+      RunProcessInput again = new RunProcessInput();
+      again.setProcessName("backupImportCatalog");
+      again.addValue("bucketAlias", "backups");
+      again.addValue("prefix", "qqq-backups/");
+      output = new RunProcessAction().execute(again);
+      again.addValue("processUUID", output.getProcessUUID());
+      again.setStartAfterStep("input");
+      output = new RunProcessAction().execute(again);
+      List<ProcessSummaryLineInterface> second = RestoreProcessTest.lines(output, StreamedETLWithFrontendProcess.FIELD_VALIDATION_SUMMARY);
+      assertThat(RestoreTestSupport.line(second, false, "already in the catalog").getCount()).isEqualTo(1);
+      assertThat(RestoreTestSupport.line(second, false, "will be added")).isNull();
+      assertThat(second.stream().map(l -> ((ProcessSummaryLine) l).getStatus())).doesNotContain(Status.ERROR);
+   }
+}

src/test/java/com/kingsrook/qbits/backups/restore/RestoreModesTest.java

@@ -0,0 +1,515 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.restore;
+
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.backups.BackupsTestUtils;
+import com.kingsrook.qbits.backups.codec.HashingOutputStream;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qbits.backups.run.BackupRunResult;
+import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
+import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLine;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLineInterface;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** End to end tests of restore (spec 13): back up 30 posts, then delete 10, edit
+ ** 10 and add 10; Review each mode and check the summary lines; restore and check
+ ** counts, hashes and files.
+ *******************************************************************************/
+class RestoreModesTest
+{
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @BeforeEach
+   void setUp() throws Exception
+   {
+      BackupsTestUtils.init();
+      BackupsTestUtils.loadBlog(30);
+   }
+
+
+
+   /*******************************************************************************
+    ** Review of each mode reports the counts the restore will produce, in the standard
+    ** summary lines, and writes nothing.
+    *******************************************************************************/
+   @Test
+   void testReviewEachMode() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+      RestoreTestSupport.mutate();
+      assertThat(RestoreTestSupport.rows("blogPost")).hasSize(30);
+
+      RestoreOutcome insertNew = new RestoreEngine().review(RestoreTestSupport.request(run, RestoreRequest.MODE_INSERT_NEW, "blogPost"));
+      RestoreOutcome.TableOutcome t = insertNew.getTables().get("blogPost");
+      assertThat(insertNew.getErrors()).isEmpty();
+      assertThat(t.getRows()).isEqualTo(30);
+      assertThat(t.getInserted()).isEqualTo(10);
+      assertThat(t.getUpdated()).isZero();
+      assertThat(t.getUnchanged()).isEqualTo(10);
+      assertThat(t.getSkipped()).isEqualTo(10);
+      assertThat(t.getDeleted()).isZero();
+      assertThat(t.getSchemaStatus()).isEqualTo("MATCH");
+      List<ProcessSummaryLineInterface> lines = RestoreSummaries.lines(insertNew, false);
+      assertThat(RestoreTestSupport.line(lines, false, "records will be inserted into blogPost").getCount()).isEqualTo(10);
+      assertThat(RestoreTestSupport.line(lines, false, "records are unchanged in blogPost").getCount()).isEqualTo(10);
+      assertThat(RestoreTestSupport.line(lines, false, "left alone in blogPost").getCount()).isEqualTo(10);
+      assertThat(RestoreTestSupport.line(lines, false, "key sequence")).isNotNull();
+
+      RestoreOutcome upsert = new RestoreEngine().review(RestoreTestSupport.request(run, RestoreRequest.MODE_UPSERT, "blogPost"));
+      t = upsert.getTables().get("blogPost");
+      assertThat(t.getInserted()).isEqualTo(10);
+      assertThat(t.getUpdated()).isEqualTo(10);
+      assertThat(t.getUnchanged()).isEqualTo(10);
+      assertThat(t.getSkipped()).isZero();
+      assertThat(t.getDeleted()).isZero();
+      lines = RestoreSummaries.lines(upsert, false);
+      assertThat(RestoreTestSupport.line(lines, false, "records will be updated in blogPost").getCount()).isEqualTo(10);
+      assertThat(t.getSamples()).hasSize(10);
+      assertThat(t.getSamples().get(0).changes()).contains("title: Edited 11 -> Post 11");
+
+      RestoreOutcome replace = new RestoreEngine().review(RestoreTestSupport.request(run, RestoreRequest.MODE_REPLACE, "blogPost").withConfirmationText("blogPost"));
+      assertThat(replace.getErrors()).isEmpty();
+      t = replace.getTables().get("blogPost");
+      assertThat(t.getDeleted()).isEqualTo(10);
+      assertThat(t.getInserted()).isEqualTo(10);
+      assertThat(t.getUpdated()).isEqualTo(10);
+      assertThat(t.getUnchanged()).isEqualTo(10);
+      ProcessSummaryLine deleted = RestoreTestSupport.line(RestoreSummaries.lines(replace, false), false, "will be deleted from blogPost (REPLACE)");
+      assertThat(deleted.getCount()).isEqualTo(10);
+
+      assertThat(RestoreTestSupport.rows("blogPost")).as("Review writes nothing").hasSize(30);
+      assertThat(new BackupCatalog().query(BackupsTables.RESTORE_RUN, new com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter())).isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** INSERT_NEW brings back the deleted rows and leaves edits and additions alone.
+    *******************************************************************************/
+   @Test
+   void testExecuteInsertNew() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+      RestoreTestSupport.mutate();
+
+      RestoreOutcome outcome = new RestoreEngine().execute(RestoreTestSupport.request(run, RestoreRequest.MODE_INSERT_NEW, "blogPost"));
+      assertThat(outcome.getTables().get("blogPost").getInserted()).isEqualTo(10);
+
+      List<QRecord> rows = RestoreTestSupport.rows("blogPost");
+      assertThat(rows).hasSize(40);
+      assertThat(rows.get(0).getValueString("title")).isEqualTo("Post 1");
+      assertThat(rows.stream().filter(r -> r.getValueInteger("id") == 15).findFirst().orElseThrow().getValueString("title")).isEqualTo("Edited 15");
+   }
+
+
+
+   /*******************************************************************************
+    ** UPSERT rolls edits back and restores deleted rows, keeps additions; the file that
+    ** was removed comes back with the right checksum, and a file with different content
+    ** is kept (a conflict).
+    *******************************************************************************/
+   @Test
+   void testExecuteUpsertWithFiles() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+      RestoreTestSupport.mutate();
+      String original1 = "photo bytes 1";
+      BackupsTestUtils.MEDIA.removeIgnoringLock("media/photo-1.jpg");
+      BackupsTestUtils.MEDIA.putBytes("media/photo-2.jpg", "tampered".getBytes());
+
+      RestoreOutcome review = new RestoreEngine().review(RestoreTestSupport.request(run, RestoreRequest.MODE_UPSERT, "blogPost"));
+      RestoreOutcome.TableOutcome rt = review.getTables().get("blogPost");
+      assertThat(rt.getFilesToRestore()).isEqualTo(1);
+      assertThat(rt.getFilesPresent()).isEqualTo(1);
+      assertThat(rt.getFilesConflicting()).isEqualTo(1);
+      assertThat(rt.getFilesMissing()).isZero();
+      assertThat(RestoreTestSupport.line(RestoreSummaries.lines(review, false), false, "different content for blogPost")).isNotNull();
+
+      RestoreOutcome outcome = new RestoreEngine().execute(RestoreTestSupport.request(run, RestoreRequest.MODE_UPSERT, "blogPost"));
+      RestoreOutcome.TableOutcome t = outcome.getTables().get("blogPost");
+      assertThat(t.getInserted()).isEqualTo(10);
+      assertThat(t.getUpdated()).isEqualTo(10);
+      assertThat(t.getFilesRestored()).isEqualTo(1);
+      assertThat(outcome.getFilesFailed()).isZero();
+
+      List<QRecord> rows = RestoreTestSupport.rows("blogPost");
+      assertThat(rows).hasSize(40);
+      assertThat(rows.stream().filter(r -> r.getValueInteger("id") == 15).findFirst().orElseThrow().getValueString("title")).isEqualTo("Post 15");
+
+      byte[] restored = BackupsTestUtils.MEDIA.getBytes("media/photo-1.jpg");
+      assertThat(new String(restored)).isEqualTo(original1);
+      assertThat(HashingOutputStream.sha256Hex(restored)).isEqualTo(HashingOutputStream.sha256Hex(original1.getBytes()));
+      assertThat(new String(BackupsTestUtils.MEDIA.getBytes("media/photo-2.jpg"))).as("a conflicting file is kept").isEqualTo("tampered");
+      assertThat(BackupsTestUtils.MEDIA.list("media/").stream().filter(o -> o.key().contains("qqq-restore"))).as("no temporary object is left").isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** REPLACE needs the typed confirmation, deletes what is not in the backup, takes a
+    ** pre-restore backup first, brings the table back to exactly the backed up rows
+    ** (same hash), overwrites a conflicting file, and records the run rows.
+    *******************************************************************************/
+   @Test
+   void testExecuteReplace() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+      String originalHash = RestoreTestSupport.contentHash("blogPost");
+      RestoreTestSupport.mutate();
+      assertThat(RestoreTestSupport.contentHash("blogPost")).isNotEqualTo(originalHash);
+      BackupsTestUtils.MEDIA.putBytes("media/photo-2.jpg", "tampered".getBytes());
+
+      RestoreRequest request = RestoreTestSupport.request(run, RestoreRequest.MODE_REPLACE, "blogPost");
+      assertThatThrownBy(() -> new RestoreEngine().execute(request)).hasMessageContaining("type blogPost");
+      assertThat(RestoreTestSupport.rows("blogPost")).hasSize(30);
+
+      RestoreOutcome outcome = new RestoreEngine().execute(request.withConfirmationText("blogPost"));
+      RestoreOutcome.TableOutcome t = outcome.getTables().get("blogPost");
+      assertThat(t.getDeleted()).isEqualTo(10);
+      assertThat(t.getInserted()).isEqualTo(10);
+      assertThat(t.getUpdated()).isEqualTo(10);
+
+      assertThat(RestoreTestSupport.rows("blogPost")).hasSize(30);
+      assertThat(RestoreTestSupport.contentHash("blogPost")).as("the rows are exactly the backed up rows again").isEqualTo(originalHash);
+      assertThat(new String(BackupsTestUtils.MEDIA.getBytes("media/photo-2.jpg"))).as("REPLACE overwrites a conflicting file").isEqualTo("photo bytes 2");
+
+      QRecord restoreRun = new BackupCatalog().get(BackupsTables.RESTORE_RUN, outcome.getRestoreRunId()).orElseThrow();
+      assertThat(restoreRun.getValueString("status")).isIn("SUCCEEDED", "SUCCEEDED_WITH_WARNINGS");
+      assertThat(restoreRun.getValueString("mode")).isEqualTo("REPLACE");
+      assertThat(restoreRun.getValueLong("rowsDeleted")).isEqualTo(10L);
+      assertThat(restoreRun.getValueLong("rowsInserted")).isEqualTo(10L);
+      assertThat(restoreRun.getValueInteger("filesRestored")).isEqualTo(1);
+      assertThat(restoreRun.getValueString("confirmationText")).isEqualTo("blogPost");
+      assertThat(restoreRun.getValueInteger("preRestoreBackupRunId")).isNotNull();
+      QRecord pre = new BackupCatalog().get(BackupsTables.RUN, restoreRun.getValueInteger("preRestoreBackupRunId")).orElseThrow();
+      assertThat(pre.getValueString("trigger")).isEqualTo("PRE_RESTORE");
+      assertThat(pre.getValueString("status")).startsWith("SUCCEEDED");
+      List<QRecord> tableRows = new BackupCatalog().where(BackupsTables.RESTORE_RUN_TABLE, "backupRestoreRunId", outcome.getRestoreRunId());
+      assertThat(tableRows).hasSize(1);
+      assertThat(tableRows.get(0).getValueString("tableName")).isEqualTo("blogPost");
+      assertThat(tableRows.get(0).getValueLong("rowsDeleted")).isEqualTo(10L);
+      assertThat(tableRows.get(0).getValueString("schemaStatus")).isEqualTo("MATCH");
+   }
+
+
+
+   /*******************************************************************************
+    ** Turning the pre-restore backup off is allowed and is recorded on the restore run.
+    *******************************************************************************/
+   @Test
+   void testPreRestoreBackupCanBeTurnedOff() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+      RestoreTestSupport.mutate();
+      RestoreOutcome outcome = new RestoreEngine().execute(RestoreTestSupport.request(run, RestoreRequest.MODE_INSERT_NEW, "blogPost").withPreRestoreBackup(false));
+      QRecord restoreRun = new BackupCatalog().get(BackupsTables.RESTORE_RUN, outcome.getRestoreRunId()).orElseThrow();
+      assertThat(restoreRun.getValueInteger("preRestoreBackupRunId")).isNull();
+      assertThat(restoreRun.getValueString("scopeSummary")).contains("no pre-restore backup");
+   }
+
+
+
+   /*******************************************************************************
+    ** REMAP_NEW_IDS lets the target assign ids and rewrites the references of later
+    ** tables through the map; the id map is cleared when the restore ends.
+    *******************************************************************************/
+   @Test
+   void testRemapNewIds() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+
+      RestoreRequest request = RestoreTestSupport.request(run, RestoreRequest.MODE_INSERT_NEW, "author", "blogPost").withIdStrategy(RestoreRequest.IDS_REMAP);
+      RestoreOutcome review = new RestoreEngine().review(request);
+      assertThat(review.getTables().get("author").getInserted()).isEqualTo(3);
+      assertThat(review.getTables().get("blogPost").getInserted()).isEqualTo(30);
+      assertThat(review.getTables().get("blogPost").getOrphans()).as("the parents are in the backup").isZero();
+
+      RestoreOutcome outcome = new RestoreEngine().execute(request);
+      assertThat(outcome.getTables().get("author").getInserted()).isEqualTo(3);
+
+      List<QRecord> authors = RestoreTestSupport.rows("author");
+      assertThat(authors).hasSize(6);
+      List<QRecord> posts = RestoreTestSupport.rows("blogPost");
+      assertThat(posts).hasSize(60);
+      QRecord newPost1 = posts.stream().filter(p -> p.getValueInteger("id") > 30 && "Post 1".equals(p.getValueString("title"))).findFirst().orElseThrow();
+      QRecord newAuthor = authors.stream().filter(a -> a.getValueInteger("id") == newPost1.getValueInteger("authorId")).findFirst().orElseThrow();
+      assertThat(newAuthor.getValueInteger("id")).as("the post points at a new author").isGreaterThan(3);
+      assertThat(newAuthor.getValueString("name")).as("old author 2 was Grace").isEqualTo("Grace");
+      assertThat(new BackupCatalog().query(BackupsTables.ID_MAP, new com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter())).isEmpty();
+      assertThat(new BackupCatalog().get(BackupsTables.RESTORE_RUN, outcome.getRestoreRunId()).orElseThrow().getValueString("idStrategy")).isEqualTo("REMAP_NEW_IDS");
+   }
+
+
+
+   /*******************************************************************************
+    ** REMAP with a unique key reuses rows that already exist (the target ids differ),
+    ** and the later tables point at the existing parents.
+    *******************************************************************************/
+   @Test
+   void testRemapMatchingOnAUniqueKey() throws Exception
+   {
+      RestoreTestSupport.uniqueKey("author", "name");
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+
+      com.kingsrook.qqq.backend.core.actions.tables.DeleteAction delete = new com.kingsrook.qqq.backend.core.actions.tables.DeleteAction();
+      for(String table : List.of("blogPost", "author"))
+      {
+         com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput input = new com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput(table);
+         List<Serializable> ids = new ArrayList<>();
+         for(QRecord row : RestoreTestSupport.rows(table))
+         {
+            ids.add(row.getValue("id"));
+         }
+         input.setPrimaryKeys(ids);
+         delete.execute(input);
+      }
+      BackupsTestUtils.insert("author", List.of(Map.of("id", 10, "name", "Linus"), Map.of("id", 20, "name", "Ada", "bio", "other bio"), Map.of("id", 30, "name", "Grace", "bio", "")));
+
+      RestoreRequest request = RestoreTestSupport.request(run, RestoreRequest.MODE_UPSERT, "author", "blogPost").withIdStrategy(RestoreRequest.IDS_REMAP).withMatchOn("name");
+      RestoreOutcome review = new RestoreEngine().review(request);
+      assertThat(review.getTables().get("author").getInserted()).isZero();
+      assertThat(review.getTables().get("author").getUpdated()).as("only Ada's bio differs").isEqualTo(1);
+      assertThat(review.getTables().get("author").getUnchanged()).isEqualTo(2);
+
+      new RestoreEngine().execute(request);
+      assertThat(RestoreTestSupport.rows("author")).hasSize(3);
+      assertThat(RestoreTestSupport.rows("author").stream().filter(a -> a.getValueInteger("id") == 20).findFirst().orElseThrow().getValueString("bio"))
+         .startsWith("Line one");
+      List<QRecord> posts = RestoreTestSupport.rows("blogPost");
+      assertThat(posts).hasSize(30);
+      QRecord post1 = posts.stream().filter(p -> "Post 1".equals(p.getValueString("title"))).findFirst().orElseThrow();
+      assertThat(post1.getValueInteger("authorId")).as("Post 1 belonged to Grace, who is now id 30").isEqualTo(30);
+   }
+
+
+
+   /*******************************************************************************
+    ** Unique-key conflicts and orphaned references are counted in Review.
+    *******************************************************************************/
+   @Test
+   void testConflictsAndOrphans() throws Exception
+   {
+      RestoreTestSupport.uniqueKey("author", "name");
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+
+      com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput input = new com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput("author");
+      input.setPrimaryKeys(List.of(1, 2));
+      new com.kingsrook.qqq.backend.core.actions.tables.DeleteAction().execute(input);
+      BackupsTestUtils.insert("author", List.of(Map.of("id", 5, "name", "Ada")));
+
+      RestoreOutcome authors = new RestoreEngine().review(RestoreTestSupport.request(run, RestoreRequest.MODE_INSERT_NEW, "author"));
+      RestoreOutcome.TableOutcome a = authors.getTables().get("author");
+      assertThat(a.getConflicts()).as("Ada id 1 collides with the existing Ada id 5").isEqualTo(1);
+      assertThat(a.getInserted()).as("Grace id 2 can come back").isEqualTo(1);
+      assertThat(a.getUnchanged()).isEqualTo(1);
+      assertThat(RestoreTestSupport.line(RestoreSummaries.lines(authors, false), false, "conflicts on a unique key")).isNotNull();
+
+      RestoreOutcome posts = new RestoreEngine().review(RestoreTestSupport.request(run, RestoreRequest.MODE_INSERT_NEW, "blogPost"));
+      assertThat(posts.getTables().get("blogPost").getOrphans()).as("posts of author 1 and 2: those ids are in neither the backup selection nor the target").isEqualTo(20);
+      assertThat(RestoreTestSupport.line(RestoreSummaries.lines(posts, false), false, "reference a parent that is missing")).isNotNull();
+   }
+
+
+
+   /*******************************************************************************
+    ** The schema is compared with the backup:  extra and removed fields are compatible
+    ** (the removed ones are skipped); a changed type blocks that table.
+    *******************************************************************************/
+   @Test
+   void testSchemaComparison() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+      RestoreTestSupport.mutate();
+
+      com.kingsrook.qqq.backend.core.context.QContext.getQInstance().getTable("author").getFields().remove("bio");
+      com.kingsrook.qqq.backend.core.context.QContext.getQInstance().getTable("blogPost").getField("price").setType(QFieldType.STRING);
+
+      RestoreOutcome review = new RestoreEngine().review(RestoreTestSupport.request(run, RestoreRequest.MODE_UPSERT, "author", "blogPost"));
+      RestoreOutcome.TableOutcome author = review.getTables().get("author");
+      assertThat(author.getSchemaStatus()).isEqualTo("COMPATIBLE");
+      assertThat(author.getUnmappedFields()).containsExactly("bio");
+      assertThat(RestoreTestSupport.line(RestoreSummaries.lines(review, false), false, "field bio is in the backup but not in the target and will be skipped")).isNotNull();
+
+      RestoreOutcome.TableOutcome posts = review.getTables().get("blogPost");
+      assertThat(posts.getSchemaStatus()).isEqualTo("MISMATCH");
+      assertThat(posts.getStatus()).isEqualTo("SKIPPED");
+      assertThat(posts.getInserted()).isZero();
+      assertThat(RestoreTestSupport.line(RestoreSummaries.lines(review, false), false, "changed type from DECIMAL to STRING").getStatus())
+         .isEqualTo(com.kingsrook.qqq.backend.core.model.actions.processes.Status.ERROR);
+
+      RestoreOutcome outcome = new RestoreEngine().execute(RestoreTestSupport.request(run, RestoreRequest.MODE_UPSERT, "author", "blogPost"));
+      assertThat(outcome.getTables().get("blogPost").getStatus()).isEqualTo("SKIPPED");
+      assertThat(RestoreTestSupport.rows("blogPost")).as("the incompatible table is left alone").hasSize(30);
+      List<QRecord> tableRows = new BackupCatalog().where(BackupsTables.RESTORE_RUN_TABLE, "backupRestoreRunId", outcome.getRestoreRunId());
+      assertThat(tableRows).extracting(r -> r.getValueString("schemaStatus")).containsExactlyInAnyOrder("COMPATIBLE", "MISMATCH");
+   }
+
+
+
+   /*******************************************************************************
+    ** Sensitive values are masked in the sample diff, even when they are in the backup.
+    *******************************************************************************/
+   @Test
+   void testSensitiveValuesAreNeverShown() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of("sensitiveFieldPolicy", "INCLUDE"));
+      UpdateInput update = new UpdateInput("blogPost");
+      update.setRecords(List.of(new QRecord().withValue("id", 1).withValue("secretNote", "brand-new-secret")));
+      new UpdateAction().execute(update);
+
+      RestoreOutcome review = new RestoreEngine().review(RestoreTestSupport.request(run, RestoreRequest.MODE_UPSERT, "blogPost"));
+      RestoreOutcome.TableOutcome t = review.getTables().get("blogPost");
+      assertThat(t.getUpdated()).isEqualTo(1);
+      assertThat(t.getSamples()).hasSize(1);
+      assertThat(t.getSamples().get(0).changes()).containsExactly("secretNote: ******** -> ********");
+
+      String everything = RestoreSummaries.lines(review, false).stream().map(l -> String.valueOf(((ProcessSummaryLine) l).getBulletsOfText())).reduce("", String::concat);
+      assertThat(everything).doesNotContain("brand-new-secret").doesNotContain("do-not-leak");
+   }
+
+
+
+   /*******************************************************************************
+    ** Per table filters restrict the restore to selected records.
+    *******************************************************************************/
+   @Test
+   void testFilteredRestore() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+      RestoreTestSupport.mutate();
+
+      RestoreRequest request = RestoreTestSupport.request(run, RestoreRequest.MODE_UPSERT, "blogPost")
+         .withFilter("blogPost", "{\"criteria\":[{\"fieldName\":\"id\",\"operator\":\"IN\",\"values\":[2,3,12]}]}");
+      RestoreOutcome outcome = new RestoreEngine().execute(request);
+      RestoreOutcome.TableOutcome t = outcome.getTables().get("blogPost");
+      assertThat(t.getRows()).isEqualTo(3);
+      assertThat(t.getInserted()).isEqualTo(2);
+      assertThat(t.getUpdated()).isEqualTo(1);
+      assertThat(RestoreTestSupport.rows("blogPost")).hasSize(32);
+   }
+
+
+
+   /*******************************************************************************
+    ** Writes go through the RestoreWriter in page transactions.
+    *******************************************************************************/
+   @Test
+   void testWritesUseThePluggableWriterInPageTransactions() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+      RestoreTestSupport.mutate();
+
+      List<String> calls = new ArrayList<>();
+      StandardRestoreWriter standard = new StandardRestoreWriter();
+      RestoreWriter recording = new RestoreWriter()
+      {
+         /*******************************************************************************
+          ** {@inheritDoc}
+          *******************************************************************************/
+         @Override
+         public List<QRecord> insert(com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData table, List<QRecord> records, RestoreRequest options, QBackendTransaction tx)
+            throws com.kingsrook.qqq.backend.core.exceptions.QException
+         {
+            calls.add("insert:" + records.size() + ":" + (tx != null));
+            return (standard.insert(table, records, options, tx));
+         }
+
+
+
+         /*******************************************************************************
+          ** {@inheritDoc}
+          *******************************************************************************/
+         @Override
+         public List<QRecord> update(com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData table, List<QRecord> records, RestoreRequest options, QBackendTransaction tx)
+            throws com.kingsrook.qqq.backend.core.exceptions.QException
+         {
+            calls.add("update:" + records.size() + ":" + (tx != null));
+            return (standard.update(table, records, options, tx));
+         }
+
+
+
+         /*******************************************************************************
+          ** {@inheritDoc}
+          *******************************************************************************/
+         @Override
+         public long delete(com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData table, List<Serializable> primaryKeys, RestoreRequest options, QBackendTransaction tx)
+            throws com.kingsrook.qqq.backend.core.exceptions.QException
+         {
+            return (standard.delete(table, primaryKeys, options, tx));
+         }
+
+
+
+         /*******************************************************************************
+          ** {@inheritDoc}
+          *******************************************************************************/
+         @Override
+         public boolean usesCoreRestoreFlag()
+         {
+            return (standard.usesCoreRestoreFlag());
+         }
+
+
+
+         /*******************************************************************************
+          ** {@inheritDoc}
+          *******************************************************************************/
+         @Override
+         public boolean canResyncSequences()
+         {
+            return (true);
+         }
+
+
+
+         /*******************************************************************************
+          ** {@inheritDoc}
+          *******************************************************************************/
+         @Override
+         public List<String> resyncSequences(java.util.Collection<com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData> tables)
+            throws com.kingsrook.qqq.backend.core.exceptions.QException
+         {
+            tables.forEach(t -> calls.add("resync:" + t.getName()));
+            return (tables.stream().map(com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData::getName).toList());
+         }
+      };
+
+      RestoreOutcome outcome = new RestoreEngine().execute(RestoreTestSupport.request(run, RestoreRequest.MODE_UPSERT, "blogPost").withWriter(recording).withPageSize(8));
+      assertThat(calls).contains("insert:8:true", "insert:2:true", "update:6:true", "update:4:true");
+      assertThat(calls).filteredOn(c -> !c.startsWith("resync")).allMatch(c -> c.endsWith(":true"));
+      assertThat(calls).as("the key sequence of the table that got its original ids is resynced, after the writes").endsWith("resync:blogPost");
+      assertThat(outcome.getSequencesResynced()).isEqualTo(1);
+      assertThat(new BackupCatalog().get(BackupsTables.RESTORE_RUN, outcome.getRestoreRunId()).orElseThrow().getValueInteger("sequencesResynced")).isEqualTo(1);
+   }
+}

src/test/java/com/kingsrook/qbits/backups/restore/RestoreProcessTest.java

@@ -0,0 +1,249 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.restore;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.backups.BackupsTestUtils;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qbits.backups.run.BackupRunResult;
+import com.kingsrook.qqq.backend.core.actions.processes.RunProcessAction;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLine;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLineInterface;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessOutput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.Status;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.processes.implementations.etl.streamedwithfrontend.StreamedETLWithFrontendProcess;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** The restore and download processes, run the way the frontend runs them: the
+ ** first screen, Review (the validation summary), Execute and Result.
+ *******************************************************************************/
+class RestoreProcessTest
+{
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @BeforeEach
+   void setUp() throws Exception
+   {
+      BackupsTestUtils.init();
+      BackupsTestUtils.loadBlog(30);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @SuppressWarnings("unchecked")
+   static List<ProcessSummaryLineInterface> lines(RunProcessOutput output, String field)
+   {
+      return (new ArrayList<>((List<ProcessSummaryLineInterface>) output.getValues().get(field)));
+   }
+
+
+
+   /*******************************************************************************
+    ** Restore... on a backup run: Review shows the per-table lines and a sample diff,
+    ** Execute restores, Result shows what was done.
+    *******************************************************************************/
+   @Test
+   void testRestoreProcessEndToEnd() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+      RestoreTestSupport.mutate();
+
+      RunProcessInput input = new RunProcessInput();
+      input.setProcessName("backupRestore");
+      input.addValue(StreamedETLWithFrontendProcess.FIELD_DEFAULT_QUERY_FILTER, new QQueryFilter(new QFilterCriteria("id", QCriteriaOperator.EQUALS, run.getRunId())));
+      input.addValue("tables", "blogPost");
+      input.addValue("mode", "UPSERT");
+
+      RunProcessOutput output = new RunProcessAction().execute(input);
+      assertThat(output.getException()).isEmpty();
+      assertThat(output.getProcessState().getNextStepName()).as("the first screen asks for the options").isPresent().get().isEqualTo("input");
+      input.addValue("processUUID", output.getProcessUUID());
+
+      input.setStartAfterStep("input");
+      output = new RunProcessAction().execute(input);
+      assertThat(output.getException()).isEmpty();
+      assertThat(output.getProcessState().getNextStepName()).isPresent().get().isEqualTo("review");
+
+      List<ProcessSummaryLineInterface> review = lines(output, StreamedETLWithFrontendProcess.FIELD_VALIDATION_SUMMARY);
+      assertThat(RestoreTestSupport.line(review, false, "records will be inserted into blogPost").getCount()).isEqualTo(10);
+      assertThat(RestoreTestSupport.line(review, false, "records will be updated in blogPost").getCount()).isEqualTo(10);
+      assertThat(RestoreTestSupport.line(review, false, "records are unchanged in blogPost").getCount()).isEqualTo(10);
+      ProcessSummaryLine sample = RestoreTestSupport.line(review, false, "changed records in blogPost");
+      assertThat(sample.getBulletsOfText()).hasSize(10);
+      assertThat(sample.getBulletsOfText().get(0)).contains("title: Edited 11 -> Post 11");
+      assertThat(RestoreTestSupport.rows("blogPost")).as("Review writes nothing").hasSize(30);
+
+      input.setStartAfterStep("review");
+      output = new RunProcessAction().execute(input);
+      assertThat(output.getException()).isEmpty();
+      assertThat(output.getProcessState().getNextStepName()).isPresent().get().isEqualTo("result");
+
+      List<ProcessSummaryLineInterface> result = lines(output, StreamedETLWithFrontendProcess.FIELD_PROCESS_SUMMARY);
+      assertThat(RestoreTestSupport.line(result, true, "records were inserted into blogPost").getCount()).isEqualTo(10);
+      assertThat(RestoreTestSupport.line(result, true, "records were updated in blogPost").getCount()).isEqualTo(10);
+      assertThat(RestoreTestSupport.line(result, true, "A backup of the target tables was taken first")).isNotNull();
+      assertThat(result.stream().map(l -> ((ProcessSummaryLine) l).getStatus())).doesNotContain(Status.ERROR);
+
+      assertThat(RestoreTestSupport.rows("blogPost")).hasSize(40);
+      assertThat(new BackupCatalog().where(BackupsTables.RESTORE_RUN, "sourceBackupRunId", run.getRunId())).hasSize(1);
+   }
+
+
+
+   /*******************************************************************************
+    ** Restore this table, on a table's data artifact, restores just that table.
+    *******************************************************************************/
+   @Test
+   void testRestoreThisTableOnAnArtifact() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+      RestoreTestSupport.mutate();
+      QRecord artifact = new BackupCatalog().where(BackupsTables.ARTIFACT, "backupRunId", run.getRunId()).stream()
+         .filter(a -> "blogPost".equals(a.getValueString("tableName"))).findFirst().orElseThrow();
+
+      RunProcessInput input = new RunProcessInput();
+      input.setProcessName("backupRestoreTable");
+      input.addValue(StreamedETLWithFrontendProcess.FIELD_DEFAULT_QUERY_FILTER, new QQueryFilter(new QFilterCriteria("id", QCriteriaOperator.EQUALS, artifact.getValueInteger("id"))));
+      input.addValue("mode", "INSERT_NEW");
+
+      RunProcessOutput output = new RunProcessAction().execute(input);
+      input.addValue("processUUID", output.getProcessUUID());
+      input.setStartAfterStep("input");
+      output = new RunProcessAction().execute(input);
+      assertThat(output.getException()).isEmpty();
+      assertThat(RestoreTestSupport.line(lines(output, StreamedETLWithFrontendProcess.FIELD_VALIDATION_SUMMARY), false, "records will be inserted into blogPost").getCount()).isEqualTo(10);
+      assertThat(RestoreTestSupport.line(lines(output, StreamedETLWithFrontendProcess.FIELD_VALIDATION_SUMMARY), false, "author")).as("only that table").isNull();
+
+      input.setStartAfterStep("review");
+      new RunProcessAction().execute(input);
+      assertThat(RestoreTestSupport.rows("blogPost")).hasSize(40);
+   }
+
+
+
+   /*******************************************************************************
+    ** The Review of a REPLACE without the typed confirmation is an error line, and
+    ** Execute refuses.
+    *******************************************************************************/
+   @Test
+   void testReplaceWithoutConfirmationIsRefused() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+      RestoreTestSupport.mutate();
+
+      RunProcessInput input = new RunProcessInput();
+      input.setProcessName("backupRestore");
+      input.addValue(StreamedETLWithFrontendProcess.FIELD_DEFAULT_QUERY_FILTER, new QQueryFilter(new QFilterCriteria("id", QCriteriaOperator.EQUALS, run.getRunId())));
+      input.addValue("tables", "blogPost");
+      input.addValue("mode", "REPLACE");
+
+      RunProcessOutput output = new RunProcessAction().execute(input);
+      input.addValue("processUUID", output.getProcessUUID());
+      input.setStartAfterStep("input");
+      output = new RunProcessAction().execute(input);
+      ProcessSummaryLine error = RestoreTestSupport.line(lines(output, StreamedETLWithFrontendProcess.FIELD_VALIDATION_SUMMARY), false, "To confirm a REPLACE, type blogPost");
+      assertThat(error).isNotNull();
+      assertThat(error.getStatus()).isEqualTo(Status.ERROR);
+
+      input.setStartAfterStep("review");
+      assertThatThrownBy(() -> new RunProcessAction().execute(input)).hasMessageContaining("To confirm a REPLACE, type blogPost");
+      assertThat(RestoreTestSupport.rows("blogPost")).hasSize(30);
+   }
+
+
+
+   /*******************************************************************************
+    ** Download: presigned links for the run's objects (ciphertext as stored), each one
+    ** a separate link, with the manifest and checksums among them.
+    *******************************************************************************/
+   @Test
+   void testDownloadIssuesLinks() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+      int artifacts = new BackupCatalog().where(BackupsTables.ARTIFACT, "backupRunId", run.getRunId()).size();
+
+      RunProcessInput input = new RunProcessInput();
+      input.setProcessName("backupDownload");
+      input.addValue(StreamedETLWithFrontendProcess.FIELD_DEFAULT_QUERY_FILTER, new QQueryFilter(new QFilterCriteria("id", QCriteriaOperator.EQUALS, run.getRunId())));
+
+      RunProcessOutput output = new RunProcessAction().execute(input);
+      assertThat(output.getException()).isEmpty();
+      input.addValue("processUUID", output.getProcessUUID());
+      if(output.getProcessState().getNextStepName().orElse("").equals("review"))
+      {
+         input.setStartAfterStep("review");
+      }
+      else
+      {
+         input.setStartAfterStep(output.getProcessState().getNextStepName().orElse(null));
+      }
+
+      List<ProcessSummaryLineInterface> review = lines(output, StreamedETLWithFrontendProcess.FIELD_VALIDATION_SUMMARY);
+      assertThat(RestoreTestSupport.line(review, false, "files will get download links").getCount()).isEqualTo(artifacts);
+
+      output = new RunProcessAction().execute(input);
+      assertThat(output.getException()).isEmpty();
+      ProcessSummaryLine issued = RestoreTestSupport.line(lines(output, StreamedETLWithFrontendProcess.FIELD_PROCESS_SUMMARY), true, "download links were issued");
+      assertThat(issued.getCount()).isEqualTo(artifacts);
+      assertThat(issued.getBulletsOfText()).hasSize(artifacts);
+      assertThat(issued.getBulletsOfText()).anyMatch(b -> b.contains("manifest.json") && b.contains("memory://") && b.contains("ttl=900"));
+      assertThat(issued.getBulletsOfText()).anyMatch(b -> b.contains("checksums.sha256"));
+   }
+
+
+
+   /*******************************************************************************
+    ** Download on one artifact links that artifact plus the manifest and checksums.
+    *******************************************************************************/
+   @Test
+   void testDownloadOfOneArtifact() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+      QRecord artifact = new BackupCatalog().where(BackupsTables.ARTIFACT, "backupRunId", run.getRunId()).stream()
+         .filter(a -> "blogPost".equals(a.getValueString("tableName"))).findFirst().orElseThrow();
+
+      RunProcessInput input = new RunProcessInput();
+      input.setProcessName("backupDownloadArtifact");
+      input.addValue(StreamedETLWithFrontendProcess.FIELD_DEFAULT_QUERY_FILTER, new QQueryFilter(new QFilterCriteria("id", QCriteriaOperator.EQUALS, artifact.getValueInteger("id"))));
+      RunProcessOutput output = new RunProcessAction().execute(input);
+      input.addValue("processUUID", output.getProcessUUID());
+      input.setStartAfterStep("review");
+      output = new RunProcessAction().execute(input);
+
+      ProcessSummaryLine issued = RestoreTestSupport.line(lines(output, StreamedETLWithFrontendProcess.FIELD_PROCESS_SUMMARY), true, "download links were issued");
+      assertThat(issued.getCount()).isEqualTo(3);
+      assertThat(issued.getBulletsOfText()).anyMatch(b -> b.contains("blogPost-part-00001"));
+   }
+}

src/test/java/com/kingsrook/qbits/backups/restore/RestoreSafetyTest.java

@@ -0,0 +1,190 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.restore;
+
+
+import java.io.Serializable;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.BackupsTestUtils;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qbits.backups.run.BackupRunResult;
+import com.kingsrook.qbits.backups.scope.BackupTableMetaData;
+import com.kingsrook.qbits.backups.scope.TableRole;
+import com.kingsrook.qqq.backend.core.actions.processes.RunProcessAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessInput;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** The safety rails of restore (spec 9.4) and who may run it (spec 11).
+ *******************************************************************************/
+class RestoreSafetyTest
+{
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @BeforeEach
+   void setUp() throws Exception
+   {
+      BackupsTestUtils.init();
+      BackupsTestUtils.loadBlog(12);
+   }
+
+
+
+   /*******************************************************************************
+    ** A restore is refused while a backup that covers the same tables is running.
+    *******************************************************************************/
+   @Test
+   void testRefusesWhileABackupOfTheSameTablesIsRunning() throws Exception
+   {
+      BackupRunResult run    = RestoreTestSupport.backup(Map.of());
+      Integer         planId = new BackupCatalog().where(BackupsTables.PLAN, "planKey", "nightly").get(0).getValueInteger("id");
+
+      Map<String, Serializable> live = new LinkedHashMap<>();
+      live.put("backupPlanId", planId);
+      live.put("runKey", "live-one");
+      live.put("status", "RUNNING");
+      live.put("startDate", BackupsRuntime.getClock().instant());
+      live.put("heartbeatDate", BackupsRuntime.getClock().instant());
+      Integer liveId = new BackupCatalog().insert(BackupsTables.RUN, live);
+
+      RestoreRequest request = RestoreTestSupport.request(run, RestoreRequest.MODE_INSERT_NEW, "blogPost");
+      assertThat(new RestoreEngine().plan(request).errors()).anyMatch(e -> e.contains("is running"));
+      assertThatThrownBy(() -> new RestoreEngine().execute(request)).hasMessageContaining("is running");
+      assertThat(new BackupCatalog().where(BackupsTables.RESTORE_RUN, "sourceBackupRunId", run.getRunId())).as("nothing was started").isEmpty();
+
+      new BackupCatalog().update(BackupsTables.RUN, liveId, Map.of("heartbeatDate", BackupsRuntime.getClock().instant().minusSeconds(3600)));
+      assertThat(new RestoreEngine().plan(request).errors()).as("a run with an old heartbeat is not running").isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** REPLACE needs the typed confirmation: the table name, or REPLACE n TABLES.
+    *******************************************************************************/
+   @Test
+   void testReplaceNeedsTheTypedConfirmation() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+
+      RestoreRequest one = RestoreTestSupport.request(run, RestoreRequest.MODE_REPLACE, "blogPost");
+      assertThat(new RestoreEngine().plan(one).errors()).anyMatch(e -> e.contains("type blogPost"));
+      assertThat(new RestoreEngine().plan(one.withConfirmationText("blogpost")).errors()).as("case matters").isNotEmpty();
+      assertThat(new RestoreEngine().plan(one.withConfirmationText("blogPost")).errors()).isEmpty();
+
+      RestoreRequest two = RestoreTestSupport.request(run, RestoreRequest.MODE_REPLACE, "author", "blogPost");
+      assertThat(new RestoreEngine().plan(two).errors()).anyMatch(e -> e.contains("REPLACE 2 TABLES"));
+      assertThat(new RestoreEngine().plan(two.withConfirmationText("REPLACE 2 TABLES")).errors()).isEmpty();
+
+      assertThat(new RestoreEngine().plan(RestoreTestSupport.request(run, RestoreRequest.MODE_REPLACE, "blogPost").withConfirmationText("blogPost")
+         .withIdStrategy(RestoreRequest.IDS_REMAP)).errors()).anyMatch(e -> e.contains("REPLACE cannot be combined with new ids"));
+   }
+
+
+
+   /*******************************************************************************
+    ** REPLACE also needs backups.admin, not just backups.restore.
+    *******************************************************************************/
+   @Test
+   void testReplaceNeedsAdmin() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+      BackupsRuntime.getConfig().withOpenWhenAnonymous(false);
+      RestoreRequest replace = RestoreTestSupport.request(run, RestoreRequest.MODE_REPLACE, "blogPost").withConfirmationText("blogPost");
+
+      QContext.setQSession(new QSession().withPermissions("backups.view", "backups.restore"));
+      assertThat(new RestoreEngine().plan(RestoreTestSupport.request(run, RestoreRequest.MODE_UPSERT, "blogPost")).errors()).isEmpty();
+      assertThat(new RestoreEngine().plan(replace).errors()).anyMatch(e -> e.contains("backups.admin"));
+
+      QContext.setQSession(new QSession().withPermissions("backups.view", "backups.restore", "backups.admin"));
+      assertThat(new RestoreEngine().plan(replace).errors()).isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** Restores never touch SECRET or backups tables, and temporary (EPHEMERAL) tables
+    ** only when they are named.
+    *******************************************************************************/
+   @Test
+   void testNeverRestoresSecretBackupsOrUnnamedEphemeralTables() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of("includeRoles", "DATA,AUDIT,EPHEMERAL"));
+      assertThat(RestoreTestSupport.manifest(run).table("userSession")).isNotNull();
+
+      RestoreEngine.Plan all = new RestoreEngine().plan(new RestoreRequest().withSourceRunId(run.getRunId()));
+      assertThat(all.errors()).isEmpty();
+      assertThat(all.order()).containsExactly("author", "blogPost");
+      assertThat(all.notes()).anyMatch(n -> n.contains("userSession") && n.contains("temporary"));
+
+      RestoreEngine.Plan named = new RestoreEngine().plan(new RestoreRequest().withSourceRunId(run.getRunId()).withTables(List.of("userSession")));
+      assertThat(named.order()).containsExactly("userSession");
+      assertThat(named.warnings()).anyMatch(w -> w.contains("temporary data"));
+
+      assertThat(new RestoreEngine().plan(new RestoreRequest().withSourceRunId(run.getRunId()).withTables(List.of("backups_plan"))).errors())
+         .anyMatch(e -> e.contains("not in this backup"));
+
+      BackupTableMetaData.ofOrWithNew(QContext.getQInstance().getTable("author")).withRole(TableRole.SECRET);
+      RestoreEngine.Plan secret = new RestoreEngine().plan(new RestoreRequest().withSourceRunId(run.getRunId()).withTables(List.of("author")));
+      assertThat(secret.errors()).anyMatch(e -> e.contains("SECRET") && e.contains("never touch"));
+   }
+
+
+
+   /*******************************************************************************
+    ** Security: without backups.restore nobody can run a restore, through the process
+    ** (the core permission check) or by calling the engine.  With the permission they can.
+    *******************************************************************************/
+   @Test
+   void testRestoreNeedsThePermission() throws Exception
+   {
+      BackupRunResult run = RestoreTestSupport.backup(Map.of());
+      RestoreTestSupport.mutate();
+      int rowsBefore = RestoreTestSupport.rows("blogPost").size();
+
+      BackupsRuntime.getConfig().withOpenWhenAnonymous(false);
+      QContext.getQInstance().setEnforcePermissionsInCoreActions(true);
+      QContext.setQSession(new QSession().withPermissions("backups.view", "backups.run"));
+
+      RunProcessInput input = new RunProcessInput();
+      input.setProcessName("backupRestore");
+      input.addValue("tables", "blogPost");
+      input.addValue("mode", "UPSERT");
+      assertThatThrownBy(() -> new RunProcessAction().execute(input)).isInstanceOf(QPermissionDeniedException.class).hasMessageContaining("backups.restore");
+
+      RestoreRequest request = RestoreTestSupport.request(run, RestoreRequest.MODE_UPSERT, "blogPost");
+      assertThatThrownBy(() -> new RestoreEngine().execute(request)).hasMessageContaining("backups.restore");
+      assertThat(new RestoreEngine().review(request).getErrors()).anyMatch(e -> e.contains("backups.restore"));
+
+      QContext.setQSession(new QSession());
+      assertThat(RestoreTestSupport.rows("blogPost")).as("nothing was written").hasSize(rowsBefore);
+
+      QContext.setQSession(new QSession().withPermissions("backups.view", "backups.restore"));
+      assertThat(new RestoreEngine().plan(request).errors()).isEmpty();
+   }
+}

src/test/java/com/kingsrook/qbits/backups/restore/RestoreTestSupport.java

@@ -0,0 +1,220 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.restore;
+
+
+import java.io.Serializable;
+import java.nio.charset.StandardCharsets;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.backups.BackupsTestUtils;
+import com.kingsrook.qbits.backups.codec.HashingOutputStream;
+import com.kingsrook.qbits.backups.codec.JsonlRowCodec;
+import com.kingsrook.qbits.backups.manifest.BackupManifest;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qbits.backups.run.BackupEngine;
+import com.kingsrook.qbits.backups.run.BackupRunFactory;
+import com.kingsrook.qbits.backups.run.BackupRunResult;
+import com.kingsrook.qqq.backend.core.actions.tables.DeleteAction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLine;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLineInterface;
+import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.UniqueKey;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** Helpers shared by the restore tests: take a backup, mutate the data the way
+ ** the spec's acceptance does (delete 10, edit 10, add 10), and read tables back.
+ *******************************************************************************/
+final class RestoreTestSupport
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private RestoreTestSupport()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Create the nightly plan (with overrides) and run it.
+    *******************************************************************************/
+   static BackupRunResult backup(Map<String, Serializable> overrides) throws Exception
+   {
+      Map<String, Serializable> values = new LinkedHashMap<>(Map.of("name", "Nightly", "planKey", "nightly", "isActive", true,
+         "scopeType", "INSTANCE", "storageBucketAlias", "backups", "slaHours", 26));
+      values.putAll(overrides);
+      BackupCatalog catalog = new BackupCatalog();
+      Integer       planId  = catalog.insert(BackupsTables.PLAN, values);
+      BackupRunResult result = new BackupEngine().execute(BackupRunFactory.forPlan(catalog.get(BackupsTables.PLAN, planId).orElseThrow(), "MANUAL"));
+      assertThat(result.isUsable()).as(result.getErrorMessage()).isTrue();
+      return (result);
+   }
+
+
+
+   /*******************************************************************************
+    ** Back up again with the existing nightly plan.
+    *******************************************************************************/
+   static BackupRunResult backupAgain() throws Exception
+   {
+      QRecord plan = new BackupCatalog().where(BackupsTables.PLAN, "planKey", "nightly").get(0);
+      BackupRunResult result = new BackupEngine().execute(BackupRunFactory.forPlan(plan, "MANUAL"));
+      assertThat(result.isUsable()).as(result.getErrorMessage()).isTrue();
+      return (result);
+   }
+
+
+
+   /*******************************************************************************
+    ** The manifest of a run.
+    *******************************************************************************/
+   static BackupManifest manifest(BackupRunResult result) throws Exception
+   {
+      return (BackupManifest.read(BackupsTestUtils.BACKUPS.getBytes(result.getManifestKey())));
+   }
+
+
+
+   /*******************************************************************************
+    ** Delete posts 1..10, edit posts 11..20 (title), add posts 31..40.
+    *******************************************************************************/
+   static void mutate() throws Exception
+   {
+      DeleteInput delete = new DeleteInput("blogPost");
+      List<Serializable> ids = new ArrayList<>();
+      for(int i = 1; i <= 10; i++)
+      {
+         ids.add(i);
+      }
+      delete.setPrimaryKeys(ids);
+      new DeleteAction().execute(delete);
+
+      List<QRecord> edits = new ArrayList<>();
+      for(int i = 11; i <= 20; i++)
+      {
+         edits.add(new QRecord().withValue("id", i).withValue("title", "Edited " + i));
+      }
+      UpdateInput update = new UpdateInput("blogPost");
+      update.setRecords(edits);
+      new UpdateAction().execute(update);
+
+      List<Map<String, Serializable>> added = new ArrayList<>();
+      for(int i = 31; i <= 40; i++)
+      {
+         Map<String, Serializable> row = new LinkedHashMap<>();
+         row.put("id", i);
+         row.put("authorId", 1);
+         row.put("title", "Added " + i);
+         row.put("createDate", Instant.parse("2026-10-13T00:00:00Z"));
+         added.add(row);
+      }
+      BackupsTestUtils.insert("blogPost", added);
+   }
+
+
+
+   /*******************************************************************************
+    ** All the rows of a table, by id.
+    *******************************************************************************/
+   static List<QRecord> rows(String table) throws QException
+   {
+      QueryInput input = new QueryInput(table);
+      input.setFilter(new QQueryFilter().withOrderBy(new QFilterOrderBy("id", true)));
+      return (new QueryAction().execute(input).getRecords());
+   }
+
+
+
+   /*******************************************************************************
+    ** A SHA-256 over the canonical rows of a table (by id), leaving out the sensitive
+    ** fields (they are not backed up) and, until the core restore flag ships, the created
+    ** and modified dates (without the flag the standard actions set them to now).
+    *******************************************************************************/
+   static String contentHash(String table) throws Exception
+   {
+      QTableMetaData meta = QContext.getQInstance().getTable(table);
+      List<String> left = new ArrayList<>();
+      meta.getFields().values().stream().filter(f -> f.getIsSensitive()).forEach(f -> left.add(f.getName()));
+      if(!new StandardRestoreWriter().usesCoreRestoreFlag())
+      {
+         left.addAll(List.of("createDate", "modifyDate"));
+      }
+      JsonlRowCodec codec = new JsonlRowCodec(meta, left);
+      StringBuilder sb    = new StringBuilder();
+      for(QRecord row : rows(table))
+      {
+         sb.append(codec.encode(row)).append('\n');
+      }
+      return (HashingOutputStream.sha256Hex(sb.toString().getBytes(StandardCharsets.UTF_8)));
+   }
+
+
+
+   /*******************************************************************************
+    ** A request over some tables, restoring from a run.
+    *******************************************************************************/
+   static RestoreRequest request(BackupRunResult run, String mode, String... tables)
+   {
+      return (new RestoreRequest().withSourceRunId(run.getRunId()).withMode(mode).withTables(List.of(tables)).withRequestedBy("tester"));
+   }
+
+
+
+   /*******************************************************************************
+    ** The summary line whose message contains the text.
+    *******************************************************************************/
+   static ProcessSummaryLine line(List<ProcessSummaryLineInterface> lines, boolean result, String text)
+   {
+      for(ProcessSummaryLineInterface line : lines)
+      {
+         ProcessSummaryLine candidate = (ProcessSummaryLine) line;
+         candidate.pickMessage(result);
+         if(candidate.getMessage() != null && candidate.getMessage().contains(text))
+         {
+            return (candidate);
+         }
+      }
+      return (null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Declare a unique key on a table of the fixture.
+    *******************************************************************************/
+   static void uniqueKey(String table, String... fields)
+   {
+      QContext.getQInstance().getTable(table).withUniqueKey(new UniqueKey(fields));
+   }
+}

src/test/java/com/kingsrook/qbits/backups/sla/SlaCheckerTest.java

@@ -0,0 +1,430 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.sla;
+
+
+import java.io.Serializable;
+import java.time.Clock;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.BackupsTestUtils;
+import com.kingsrook.qbits.backups.VerifyTestSupport;
+import com.kingsrook.qbits.backups.alerts.BackupAlertSink;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qbits.backups.run.BackupRunResult;
+import com.kingsrook.qbits.backups.verify.BackupVerifier;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static com.kingsrook.qbits.backups.VerifyTestSupport.backup;
+import static com.kingsrook.qbits.backups.VerifyTestSupport.clock;
+import static com.kingsrook.qbits.backups.VerifyTestSupport.plan;
+import static com.kingsrook.qbits.backups.VerifyTestSupport.reload;
+import static com.kingsrook.qbits.backups.VerifyTestSupport.sink;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** Every SLA state of the checker, driven by a synthetic clock, with the alerts it
+ ** raises and resolves recorded through a recording sink.
+ *******************************************************************************/
+class SlaCheckerTest
+{
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @BeforeEach
+   void setUp() throws Exception
+   {
+      VerifyTestSupport.setUp(7);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private SlaChecker.PlanResult check(QRecord plan) throws Exception
+   {
+      return (new SlaChecker().check(reload(plan)));
+   }
+
+
+
+   /*******************************************************************************
+    ** A new plan that has not run yet is UNKNOWN, then LATE once slaHours pass; a
+    ** manual-only plan with no slaHours never is.
+    *******************************************************************************/
+   @Test
+   void testNewPlanThenLate() throws Exception
+   {
+      QRecord plan = plan(Map.of("critical", true));
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.UNKNOWN);
+      assertThat(sink.open).isEmpty();
+
+      clock.advance(Duration.ofHours(27));
+      SlaChecker.PlanResult late = check(plan);
+      assertThat(late.status()).isEqualTo(SlaChecker.LATE);
+      assertThat(late.previousStatus()).isEqualTo(SlaChecker.UNKNOWN);
+      assertThat(reload(plan).getValueString("slaStatus")).isEqualTo("LATE");
+      BackupAlertsAssert.assertOpen("backups.plan.missed:nightly", BackupAlertSink.Severity.CRITICAL);
+
+   }
+
+
+
+   /*******************************************************************************
+    ** The plan.missed alert is error for an ordinary plan, critical for a critical
+    ** one, and resolves when the next run succeeds.
+    *******************************************************************************/
+   @Test
+   void testLateRaisesAndResolves() throws Exception
+   {
+      QRecord plan = plan(Map.of());
+      backup(plan);
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.OK);
+      assertThat(sink.open).isEmpty();
+
+      clock.advance(Duration.ofHours(27));
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.LATE);
+      BackupAlertsAssert.assertOpen("backups.plan.missed:nightly", BackupAlertSink.Severity.ERROR);
+      assertThat(sink.openAlert("backups.plan.missed:nightly").detail()).containsEntry("plan", "nightly").containsEntry("slaHours", "26");
+
+      backup(plan);
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.OK);
+      assertThat(sink.isOpen("backups.plan.missed:nightly")).isFalse();
+      assertThat(sink.heartbeats).contains("backups.plan:nightly");
+   }
+
+
+
+   /*******************************************************************************
+    ** A manual-only plan with no slaHours has no SLA; a scheduled one defaults to 26.
+    *******************************************************************************/
+   @Test
+   void testManualPlanHasNoSlaUnlessScheduled() throws Exception
+   {
+      QRecord manual = plan(Map.of("name", "Manual", "planKey", "manual"));
+      new BackupCatalog().update(BackupsTables.PLAN, manual.getValueInteger("id"), java.util.Collections.singletonMap("slaHours", null));
+      clock.advance(Duration.ofDays(3));
+      assertThat(check(manual).status()).isEqualTo(SlaChecker.UNKNOWN);
+
+      QRecord scheduled = plan(Map.of("name", "Sched", "planKey", "sched", "cronExpression", "0 0 2 * * ?"));
+      new BackupCatalog().update(BackupsTables.PLAN, scheduled.getValueInteger("id"), java.util.Collections.singletonMap("slaHours", null));
+      assertThat(check(scheduled).status()).isEqualTo(SlaChecker.LATE);
+   }
+
+
+
+   /*******************************************************************************
+    ** Two failed runs in a row are FAILING (error); one is only a warning; a later
+    ** success clears it.
+    *******************************************************************************/
+   @Test
+   void testFailingAfterTwoFailures() throws Exception
+   {
+      QRecord plan = plan(Map.of());
+      BackupsTestUtils.BACKUPS.withFailWritesFor(key -> key.contains("/tables/"));
+
+      assertThat(backup(plan).getStatus()).isEqualTo("FAILED");
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.UNKNOWN);
+      BackupAlertsAssert.assertOpen("backups.run.failed:nightly", BackupAlertSink.Severity.WARNING);
+
+      assertThat(backup(plan).getStatus()).isEqualTo("FAILED");
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.FAILING);
+      BackupAlertsAssert.assertOpen("backups.run.failed:nightly", BackupAlertSink.Severity.ERROR);
+
+      BackupsTestUtils.BACKUPS.withFailWritesFor(null);
+      assertThat(backup(plan).getStatus()).startsWith("SUCCEEDED");
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.OK);
+      assertThat(sink.isOpen("backups.run.failed:nightly")).isFalse();
+   }
+
+
+
+   /*******************************************************************************
+    ** A deleted manifest is MISSING_IN_STORAGE with a critical alert (a head, cached
+    ** for an hour); putting it back clears it.
+    *******************************************************************************/
+   @Test
+   void testDeletedManifestIsMissingInStorage() throws Exception
+   {
+      QRecord         plan   = plan(Map.of());
+      BackupRunResult result = backup(plan);
+      byte[]          bytes  = BackupsTestUtils.BACKUPS.getBytes(result.getManifestKey());
+
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.OK);
+      BackupsTestUtils.BACKUPS.removeIgnoringLock(result.getManifestKey());
+
+      clock.advance(Duration.ofMinutes(10));
+      assertThat(check(plan).status()).as("the earlier positive head is trusted for an hour").isEqualTo(SlaChecker.OK);
+
+      clock.advance(Duration.ofMinutes(55));
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.MISSING_IN_STORAGE);
+      BackupAlertsAssert.assertOpen("backups.run.missing_in_storage:nightly", BackupAlertSink.Severity.CRITICAL);
+      assertThat(check(plan).status()).as("a negative answer is never cached").isEqualTo(SlaChecker.MISSING_IN_STORAGE);
+
+      BackupsTestUtils.BACKUPS.putBytes(result.getManifestKey(), bytes);
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.OK);
+      assertThat(sink.isOpen("backups.run.missing_in_storage:nightly")).isFalse();
+   }
+
+
+
+   /*******************************************************************************
+    ** A RUNNING run whose heartbeat is older than ten minutes is marked ABANDONED
+    ** and the plan is ABANDONED; a fresh heartbeat is left alone.
+    *******************************************************************************/
+   @Test
+   void testStaleHeartbeatIsAbandoned() throws Exception
+   {
+      QRecord plan = plan(Map.of());
+      backup(plan);
+      Integer stale = runRow(plan, "20261012T000000Z-aaaa", "RUNNING", clock.instant());
+      clock.advance(Duration.ofMinutes(5));
+      Integer fresh = runRow(plan, "20261012T000500Z-bbbb", "RUNNING", clock.instant());
+
+      clock.advance(Duration.ofMinutes(6));
+      SlaChecker.PlanResult result = check(plan);
+      assertThat(result.abandonedRuns()).isEqualTo(1);
+      assertThat(new BackupCatalog().get(BackupsTables.RUN, stale).orElseThrow().getValueString("status")).isEqualTo("ABANDONED");
+      assertThat(new BackupCatalog().get(BackupsTables.RUN, stale).orElseThrow().getValueString("errorMessage")).contains("heartbeat");
+      assertThat(new BackupCatalog().get(BackupsTables.RUN, fresh).orElseThrow().getValueString("status")).isEqualTo("RUNNING");
+
+      assertThat(result.status()).isEqualTo(SlaChecker.ABANDONED);
+      BackupAlertsAssert.assertOpen("backups.run.failed:nightly", BackupAlertSink.Severity.WARNING);
+
+      new BackupCatalog().update(BackupsTables.RUN, fresh, java.util.Collections.singletonMap("status", "SUCCEEDED"));
+      backup(plan);
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.OK);
+      assertThat(sink.isOpen("backups.run.failed:nightly")).isFalse();
+   }
+
+
+
+   /*******************************************************************************
+    ** UNVERIFIED when no content verification has passed within verifySlaDays; a
+    ** passed verification clears it.
+    *******************************************************************************/
+   @Test
+   void testUnverifiedThenVerified() throws Exception
+   {
+      QRecord plan = plan(Map.of("slaHours", 24 * 30));
+      backup(plan);
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.OK);
+
+      clock.advance(Duration.ofDays(9));
+      BackupRunResult second = backup(plan);
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.UNVERIFIED);
+      BackupAlertsAssert.assertOpen("backups.verify.overdue:nightly", BackupAlertSink.Severity.WARNING);
+
+      new BackupVerifier().verifyThrough(second.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t");
+      assertThat(sink.isOpen("backups.verify.overdue:nightly")).isFalse();
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.OK);
+
+      clock.advance(Duration.ofDays(9));
+      backup(plan);
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.UNVERIFIED);
+   }
+
+
+
+   /*******************************************************************************
+    ** OWNER_INVALID when the configured validator rejects the plan owner.
+    *******************************************************************************/
+   @Test
+   void testOwnerInvalid() throws Exception
+   {
+      QRecord plan = plan(Map.of("ownerUserId", "bob"));
+      backup(plan);
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.OK);
+
+      BackupsRuntime.getConfig().withPlanOwnerValidator(owner -> false);
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.OWNER_INVALID);
+      BackupAlertsAssert.assertOpen("backups.plan.owner_invalid:nightly", BackupAlertSink.Severity.WARNING);
+
+      BackupsRuntime.getConfig().withPlanOwnerValidator(owner -> "bob".equals(owner));
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.OK);
+      assertThat(sink.isOpen("backups.plan.owner_invalid:nightly")).isFalse();
+
+      BackupsRuntime.getConfig().withPlanOwnerValidator(owner ->
+      {
+         throw (new IllegalStateException("directory down"));
+      });
+      assertThat(check(plan).status()).as("a validator that fails is not a verdict").isEqualTo(SlaChecker.OK);
+   }
+
+
+
+   /*******************************************************************************
+    ** Worst state first: MISSING_IN_STORAGE beats LATE.
+    *******************************************************************************/
+   @Test
+   void testPrecedence() throws Exception
+   {
+      QRecord         plan   = plan(Map.of());
+      BackupRunResult result = backup(plan);
+      BackupsTestUtils.BACKUPS.removeIgnoringLock(result.getManifestKey());
+      clock.advance(Duration.ofDays(2));
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.MISSING_IN_STORAGE);
+      assertThat(sink.isOpen("backups.plan.missed:nightly")).as("the alerts are independent of the status shown").isTrue();
+      assertThat(sink.isOpen("backups.run.missing_in_storage:nightly")).isTrue();
+   }
+
+
+
+   /*******************************************************************************
+    ** The daily bucket listing reports orphans and debris (no manifest older than 24h)
+    ** once a day, raises an info alert, and resolves it when the bucket is clean.
+    *******************************************************************************/
+   @Test
+   void testBucketAuditFindsOrphansAndDebris() throws Exception
+   {
+      QRecord plan = plan(Map.of());
+      backup(plan);
+
+      String debris = "qqq-backups/testapp/nightly/2026/09/01/20260901T020000Z-dead/tables/author/part-00001.jsonl.gz";
+      String orphan = "qqq-backups/testapp/nightly/2026/09/02/20260902T020000Z-beef/manifest.json";
+      BackupsTestUtils.BACKUPS.withClock(Clock.fixed(clock.instant().minus(Duration.ofDays(3)), java.time.ZoneOffset.UTC));
+      BackupsTestUtils.BACKUPS.putBytes(debris, new byte[] { 1 });
+      BackupsTestUtils.BACKUPS.putBytes(orphan, new byte[] { 2 });
+      BackupsTestUtils.BACKUPS.withClock(Clock.systemUTC());
+
+      SlaChecker.PlanResult first = check(plan);
+      assertThat(first.orphans()).isEqualTo(2);
+      assertThat(first.debris()).isEqualTo(1);
+      BackupAlertsAssert.assertOpen("backups.storage.debris:nightly", BackupAlertSink.Severity.INFO);
+      assertThat(sink.openAlert("backups.storage.debris:nightly").detail()).containsEntry("orphans", "2").containsEntry("debris", "1");
+
+      assertThat(check(plan).orphans()).as("listed once a day").isEqualTo(-1);
+
+      BackupsTestUtils.BACKUPS.removeIgnoringLock(debris);
+      BackupsTestUtils.BACKUPS.removeIgnoringLock(orphan);
+      clock.advance(Duration.ofHours(25));
+      SlaChecker.PlanResult clean = check(plan);
+      assertThat(clean.orphans()).isZero();
+      assertThat(clean.debris()).isZero();
+      assertThat(sink.isOpen("backups.storage.debris:nightly")).isFalse();
+   }
+
+
+
+   /*******************************************************************************
+    ** A run that is still going (RUNNING with a fresh heartbeat) is not debris, even
+    ** though its prefix has no manifest yet.
+    *******************************************************************************/
+   @Test
+   void testRunningPrefixIsNotDebris() throws Exception
+   {
+      QRecord plan = plan(Map.of());
+      backup(plan);
+      String prefix = "qqq-backups/testapp/nightly/2026/10/12/20261012T020000Z-cafe/";
+      BackupsTestUtils.BACKUPS.withClock(Clock.fixed(clock.instant().minus(Duration.ofDays(2)), java.time.ZoneOffset.UTC));
+      BackupsTestUtils.BACKUPS.putBytes(prefix + "tables/author/part-00001.jsonl.gz", new byte[] { 1 });
+      BackupsTestUtils.BACKUPS.withClock(Clock.systemUTC());
+      Map<String, Serializable> values = new LinkedHashMap<>();
+      values.put("backupPlanId", plan.getValueInteger("id"));
+      values.put("runKey", "20261012T020000Z-cafe");
+      values.put("status", "RUNNING");
+      values.put("startDate", clock.instant());
+      values.put("heartbeatDate", clock.instant());
+      values.put("runPrefix", prefix);
+      new BackupCatalog().insert(BackupsTables.RUN, values);
+
+      SlaChecker.PlanResult result = check(plan);
+      assertThat(result.debris()).isZero();
+      assertThat(result.orphans()).isZero();
+   }
+
+
+
+   /*******************************************************************************
+    ** checkAll covers only active plans, and survives a plan whose bucket is unknown.
+    *******************************************************************************/
+   @Test
+   void testCheckAllSkipsInactivePlansAndSurvivesBadBucket() throws Exception
+   {
+      plan(Map.of());
+      plan(Map.of("name", "Off", "planKey", "off", "isActive", false));
+      plan(Map.of("name", "Bad", "planKey", "bad", "storageBucketAlias", "no-such-bucket"));
+      clock.advance(Duration.ofHours(30));
+
+      List<SlaChecker.PlanResult> results = new SlaChecker().checkAll();
+      assertThat(results).extracting(SlaChecker.PlanResult::planKey).containsExactlyInAnyOrder("nightly", "bad");
+      assertThat(results).extracting(SlaChecker.PlanResult::status).containsOnly(SlaChecker.LATE);
+   }
+
+
+
+   /*******************************************************************************
+    ** Without a recorded success or storage the checks degrade quietly: a success
+    ** run with no manifest key, and a pruned run, are not "missing".
+    *******************************************************************************/
+   @Test
+   void testPrunedOrKeylessSuccessIsNotMissing() throws Exception
+   {
+      QRecord         plan   = plan(Map.of());
+      BackupRunResult result = backup(plan);
+      new BackupCatalog().update(BackupsTables.RUN, result.getRunId(), java.util.Collections.singletonMap("prunedDate", Instant.now()));
+      BackupsTestUtils.BACKUPS.removeIgnoringLock(result.getManifestKey());
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.OK);
+
+      new BackupCatalog().update(BackupsTables.RUN, result.getRunId(), java.util.Collections.singletonMap("manifestKey", null));
+      assertThat(check(plan).status()).isEqualTo(SlaChecker.OK);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private Integer runRow(QRecord plan, String runKey, String status, Instant heartbeat) throws Exception
+   {
+      Map<String, Serializable> values = new LinkedHashMap<>();
+      values.put("backupPlanId", plan.getValueInteger("id"));
+      values.put("runKey", runKey);
+      values.put("status", status);
+      values.put("startDate", heartbeat);
+      values.put("heartbeatDate", heartbeat);
+      values.put("runPrefix", "qqq-backups/testapp/nightly/2026/10/12/" + runKey + "/");
+      return (new BackupCatalog().insert(BackupsTables.RUN, values));
+   }
+
+
+
+   /***************************************************************************
+    ** Alert assertions over the recording sink.
+    ***************************************************************************/
+   private static final class BackupAlertsAssert
+   {
+      /*******************************************************************************
+       ** The alert is open at that severity.
+       *******************************************************************************/
+      static void assertOpen(String dedupeKey, BackupAlertSink.Severity severity)
+      {
+         assertThat(sink.isOpen(dedupeKey)).as("alert " + dedupeKey + " is open").isTrue();
+         assertThat(sink.openAlert(dedupeKey).severity()).isEqualTo(severity);
+         assertThat(sink.openAlert(dedupeKey).dedupeKey()).isEqualTo(dedupeKey);
+         assertThat(sink.openAlert(dedupeKey).type()).isEqualTo(dedupeKey.substring(0, dedupeKey.indexOf(':')));
+      }
+   }
+}

src/test/java/com/kingsrook/qbits/backups/verify/BackupVerifierTest.java

@@ -0,0 +1,594 @@
+/*
+ * Copyright 2026 Kingsrook, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.backups.verify;
+
+
+import java.io.ByteArrayOutputStream;
+import java.nio.charset.StandardCharsets;
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import java.util.zip.GZIPOutputStream;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.BackupsTestUtils;
+import com.kingsrook.qbits.backups.VerifyTestSupport;
+import com.kingsrook.qbits.backups.alerts.BackupAlerts;
+import com.kingsrook.qbits.backups.manifest.BackupManifest;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.run.BackupCatalog;
+import com.kingsrook.qbits.backups.run.BackupRunResult;
+import com.kingsrook.qbits.backups.storage.WriteOptions;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static com.kingsrook.qbits.backups.VerifyTestSupport.backup;
+import static com.kingsrook.qbits.backups.VerifyTestSupport.plan;
+import static com.kingsrook.qbits.backups.VerifyTestSupport.reload;
+import static com.kingsrook.qbits.backups.VerifyTestSupport.run;
+import static com.kingsrook.qbits.backups.VerifyTestSupport.sink;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** Verification at every level against the memory backend, including the failure
+ ** injection cases: a corrupted part, a deleted file-store object, a wrong
+ ** checksum, a missing manifest, and a wrong key.
+ *******************************************************************************/
+class BackupVerifierTest
+{
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @BeforeEach
+   void setUp() throws Exception
+   {
+      VerifyTestSupport.setUp(7);
+   }
+
+
+
+   /*******************************************************************************
+    ** A good run passes STORAGE then CONTENT; every table, row and file is checked,
+    ** the verification rows, the run status and the plan are updated.
+    *******************************************************************************/
+   @Test
+   void testStorageAndContentPass() throws Exception
+   {
+      QRecord         plan   = plan(Map.of());
+      BackupRunResult result = backup(plan);
+
+      List<VerificationOutcome> outcomes = new BackupVerifier().verifyThrough(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "tester");
+      assertThat(outcomes).extracting(VerificationOutcome::level).containsExactly("STORAGE", "CONTENT");
+      assertThat(outcomes).extracting(VerificationOutcome::status).containsExactly("PASSED", "PASSED");
+
+      VerificationOutcome content = outcomes.get(1);
+      assertThat(content.tablesChecked()).isEqualTo(2);
+      assertThat(content.rowsChecked()).isEqualTo(10);
+      assertThat(content.filesChecked()).isEqualTo(3);
+      assertThat(content.mismatches()).isZero();
+
+      List<QRecord> rows = new BackupCatalog().where(BackupsTables.VERIFICATION, "backupRunId", result.getRunId());
+      assertThat(rows).hasSize(2);
+      QRecord contentRow = rows.stream().filter(r -> "CONTENT".equals(r.getValueString("level"))).findFirst().orElseThrow();
+      assertThat(contentRow.getValueString("status")).isEqualTo("PASSED");
+      assertThat(contentRow.getValueLong("rowsChecked")).isEqualTo(10L);
+      assertThat(contentRow.getValueString("detailJson")).contains("\"table\":\"blogPost\"").contains("\"expectedRows\":7").contains("\"actualRows\":7").contains("\"ok\":true");
+
+      assertThat(run(result.getRunId()).getValueString("verificationStatus")).isEqualTo("CONTENT_OK");
+      QRecord reloaded = reload(plan);
+      assertThat(reloaded.getValueInteger("lastVerifiedRunId")).isEqualTo(result.getRunId());
+      assertThat(reloaded.getValueInstant("lastVerifiedDate")).isEqualTo(VerifyTestSupport.clock.instant());
+
+      assertThat(new BackupCatalog().query(BackupsTables.FILE_OBJECT, new com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter()))
+         .allSatisfy(f -> assertThat(f.getValueString("lastVerifyStatus")).isEqualTo("PASSED"));
+      assertThat(sink.open).isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** An unknown level is refused; an unknown run is refused.
+    *******************************************************************************/
+   @Test
+   void testBadArguments() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of()));
+      assertThatThrownBy(() -> new BackupVerifier().verify(result.getRunId(), "WHATEVER", "MANUAL", "t")).hasMessageContaining("Unknown verification level");
+      assertThatThrownBy(() -> new BackupVerifier().verify(99999, "STORAGE", "MANUAL", "t")).hasMessageContaining("No backup run");
+   }
+
+
+
+   /*******************************************************************************
+    ** A flipped byte in a part is caught by CONTENT with a clear message, the run is
+    ** marked FAILED, and an alert is raised; STORAGE (sizes only) still passes.
+    *******************************************************************************/
+   @Test
+   void testCorruptedPartFailsContent() throws Exception
+   {
+      QRecord         plan   = plan(Map.of());
+      BackupRunResult result = backup(plan);
+      String          key    = VerifyTestSupport.firstPartKey(result, "blogPost");
+      byte[]          bytes  = BackupsTestUtils.BACKUPS.getBytes(key).clone();
+      bytes[bytes.length / 2] ^= 0x55;
+      BackupsTestUtils.BACKUPS.corrupt(key, bytes);
+
+      List<VerificationOutcome> outcomes = new BackupVerifier().verifyThrough(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "tester");
+      assertThat(outcomes).extracting(VerificationOutcome::status).containsExactly("PASSED", "FAILED");
+      assertThat(outcomes.get(1).messages()).anyMatch(m -> m.contains("tables/blogPost/part-00001.jsonl.gz") && (m.contains("corrupted") || m.contains("checksum mismatch")));
+      assertThat(run(result.getRunId()).getValueString("verificationStatus")).isEqualTo("FAILED");
+      assertThat(reload(plan).getValueInstant("lastVerifiedDate")).isNull();
+
+      String key2 = BackupAlerts.verifyKey("nightly", "CONTENT");
+      assertThat(sink.isOpen(key2)).isTrue();
+      assertThat(sink.openAlert(key2).severity()).isEqualTo(com.kingsrook.qbits.backups.alerts.BackupAlertSink.Severity.ERROR);
+      assertThat(sink.openAlert(key2).type()).isEqualTo("backups.verify.failed");
+      assertThat(sink.openAlert(key2).detail()).containsEntry("plan", "nightly").containsEntry("level", "CONTENT").doesNotContainKey("key");
+
+      ///////////////////////////////////////////////////////////////////////////
+      // a later verification of a good run of the same plan resolves the alert //
+      ///////////////////////////////////////////////////////////////////////////
+      BackupRunResult good = backup(plan);
+      assertThat(new BackupVerifier().verifyThrough(good.getRunId(), BackupVerifier.CONTENT, "MANUAL", "tester")).extracting(VerificationOutcome::status).containsExactly("PASSED", "PASSED");
+      assertThat(sink.isOpen(key2)).isFalse();
+   }
+
+
+
+   /*******************************************************************************
+    ** A part that is valid gzip but whose bytes differ from what was written fails
+    ** the stored and content checksums, and the row content hash.
+    *******************************************************************************/
+   @Test
+   void testReplacedPartContentFails() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of()));
+      String          key    = VerifyTestSupport.firstPartKey(result, "blogPost");
+      String          text   = gunzip(BackupsTestUtils.BACKUPS.getBytes(key)).replace("Post 1", "Post X");
+      BackupsTestUtils.BACKUPS.putBytes(key, gzip(text));
+
+      VerificationOutcome outcome = new BackupVerifier().verify(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t");
+      assertThat(outcome.status()).isEqualTo("FAILED");
+      assertThat(outcome.messages()).anyMatch(m -> m.startsWith("Stored checksum mismatch")).anyMatch(m -> m.startsWith("Content checksum mismatch")).anyMatch(m -> m.startsWith("Row content hash mismatch"));
+   }
+
+
+
+   /*******************************************************************************
+    ** A truncated part fails the STORAGE size check.
+    *******************************************************************************/
+   @Test
+   void testTruncatedPartFailsStorage() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of()));
+      String          key    = VerifyTestSupport.firstPartKey(result, "blogPost");
+      byte[]          bytes  = BackupsTestUtils.BACKUPS.getBytes(key);
+      BackupsTestUtils.BACKUPS.corrupt(key, java.util.Arrays.copyOf(bytes, bytes.length - 5));
+
+      List<VerificationOutcome> outcomes = new BackupVerifier().verifyThrough(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t");
+      assertThat(outcomes).hasSize(1);
+      assertThat(outcomes.get(0).status()).isEqualTo("FAILED");
+      assertThat(outcomes.get(0).messages()).anyMatch(m -> m.startsWith("Size mismatch for") && m.contains("blogPost"));
+      assertThat(sink.isOpen(BackupAlerts.verifyKey("nightly", "STORAGE"))).isTrue();
+   }
+
+
+
+   /*******************************************************************************
+    ** A deleted part is a missing object at STORAGE level.
+    *******************************************************************************/
+   @Test
+   void testDeletedPartFailsStorage() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of()));
+      BackupsTestUtils.BACKUPS.removeIgnoringLock(VerifyTestSupport.firstPartKey(result, "author"));
+
+      VerificationOutcome outcome = new BackupVerifier().verify(result.getRunId(), BackupVerifier.STORAGE, "MANUAL", "t");
+      assertThat(outcome.status()).isEqualTo("FAILED");
+      assertThat(outcome.messages()).anyMatch(m -> m.startsWith("Missing object:") && m.contains("table author"));
+   }
+
+
+
+   /*******************************************************************************
+    ** A provider that stores SHA-256 checksums: a stored value that differs from the
+    ** manifest is a STORAGE mismatch.
+    *******************************************************************************/
+   @Test
+   void testProviderChecksumMismatchFailsStorage() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of()));
+      String          key    = VerifyTestSupport.firstPartKey(result, "author");
+      byte[]          bytes  = BackupsTestUtils.BACKUPS.getBytes(key);
+      try(var out = BackupsTestUtils.BACKUPS.openWrite(key, WriteOptions.create().withMetadata("sha256", "0000")))
+      {
+         out.write(bytes);
+      }
+      VerificationOutcome outcome = new BackupVerifier().verify(result.getRunId(), BackupVerifier.STORAGE, "MANUAL", "t");
+      assertThat(outcome.status()).isEqualTo("FAILED");
+      assertThat(outcome.messages()).anyMatch(m -> m.startsWith("Checksum mismatch for"));
+   }
+
+
+
+   /*******************************************************************************
+    ** A file-store object that was deleted fails STORAGE (head) and CONTENT.
+    *******************************************************************************/
+   @Test
+   void testDeletedFileObjectFails() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of()));
+      QRecord         file   = new BackupCatalog().query(BackupsTables.FILE_OBJECT, new com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter()).get(0);
+      BackupsTestUtils.BACKUPS.removeIgnoringLock(file.getValueString("objectKey"));
+
+      VerificationOutcome storage = new BackupVerifier().verify(result.getRunId(), BackupVerifier.STORAGE, "MANUAL", "t");
+      assertThat(storage.status()).isEqualTo("FAILED");
+      assertThat(storage.messages()).anyMatch(m -> m.startsWith("File store object missing: sha256 " + file.getValueString("sha256")));
+
+      VerificationOutcome content = new BackupVerifier().verify(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t");
+      assertThat(content.status()).isEqualTo("FAILED");
+      assertThat(content.messages()).anyMatch(m -> m.startsWith("File store object missing"));
+      assertThat(new BackupCatalog().get(BackupsTables.FILE_OBJECT, file.getValueInteger("id")).orElseThrow().getValueString("lastVerifyStatus")).isEqualTo("FAILED");
+   }
+
+
+
+   /*******************************************************************************
+    ** A file-store object with the right size but the wrong bytes (a wrong checksum)
+    ** fails CONTENT only.
+    *******************************************************************************/
+   @Test
+   void testWrongFileChecksumFailsContent() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of()));
+      QRecord         file   = new BackupCatalog().query(BackupsTables.FILE_OBJECT, new com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter()).get(0);
+      byte[]          bytes  = BackupsTestUtils.BACKUPS.getBytes(file.getValueString("objectKey")).clone();
+      bytes[0] ^= 0x01;
+      BackupsTestUtils.BACKUPS.corrupt(file.getValueString("objectKey"), bytes);
+
+      assertThat(new BackupVerifier().verify(result.getRunId(), BackupVerifier.STORAGE, "MANUAL", "t").status()).isEqualTo("PASSED");
+      VerificationOutcome content = new BackupVerifier().verify(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t");
+      assertThat(content.status()).isEqualTo("FAILED");
+      assertThat(content.messages()).anyMatch(m -> m.contains("has the wrong content") && m.contains(file.getValueString("sha256")));
+   }
+
+
+
+   /*******************************************************************************
+    ** A manifest that is gone: the run is not usable.
+    *******************************************************************************/
+   @Test
+   void testMissingManifest() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of()));
+      BackupsTestUtils.BACKUPS.removeIgnoringLock(result.getManifestKey());
+
+      VerificationOutcome outcome = new BackupVerifier().verify(result.getRunId(), BackupVerifier.STORAGE, "MANUAL", "t");
+      assertThat(outcome.status()).isEqualTo("FAILED");
+      assertThat(outcome.messages()).containsExactly("The manifest is missing from the bucket, so this backup is not usable");
+   }
+
+
+
+   /*******************************************************************************
+    ** A manifest that was changed after it was written (its hash no longer matches
+    ** the catalog) and one that is not JSON.
+    *******************************************************************************/
+   @Test
+   void testTamperedAndUnreadableManifest() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of()));
+      byte[]          bytes  = BackupsTestUtils.BACKUPS.getBytes(result.getManifestKey());
+      BackupsTestUtils.BACKUPS.putBytes(result.getManifestKey(), (new String(bytes, StandardCharsets.UTF_8) + " ").getBytes(StandardCharsets.UTF_8));
+      VerificationOutcome tampered = new BackupVerifier().verify(result.getRunId(), BackupVerifier.STORAGE, "MANUAL", "t");
+      assertThat(tampered.status()).isEqualTo("FAILED");
+      assertThat(tampered.messages()).anyMatch(m -> m.contains("manifest changed after it was written"));
+
+      BackupsTestUtils.BACKUPS.putBytes(result.getManifestKey(), "not json".getBytes(StandardCharsets.UTF_8));
+      VerificationOutcome garbage = new BackupVerifier().verify(result.getRunId(), BackupVerifier.STORAGE, "MANUAL", "t");
+      assertThat(garbage.status()).isEqualTo("FAILED");
+      assertThat(garbage.messages()).anyMatch(m -> m.contains("not valid JSON"));
+   }
+
+
+
+   /*******************************************************************************
+    ** A run with no recorded bucket cannot be examined at all: ERROR, not FAILED.
+    *******************************************************************************/
+   @Test
+   void testUnexaminableRunIsError() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of()));
+      new BackupCatalog().update(BackupsTables.RUN, result.getRunId(), java.util.Collections.singletonMap("storageBucketAlias", null));
+      VerificationOutcome outcome = new BackupVerifier().verify(result.getRunId(), BackupVerifier.STORAGE, "MANUAL", "t");
+      assertThat(outcome.status()).isEqualTo("ERROR");
+      assertThat(outcome.messages()).anyMatch(m -> m.contains("could not be carried out"));
+   }
+
+
+
+   /*******************************************************************************
+    ** Encrypted runs verify through the decrypt hook; a wrong key fails clearly; no
+    ** hook at all is an ERROR that says what to configure.
+    *******************************************************************************/
+   @Test
+   void testEncryptedRun() throws Exception
+   {
+      QRecord         plan   = plan(Map.of());
+      BackupRunResult result = VerifyTestSupport.backupEncrypted(plan, new VerifyTestSupport.XorTransform(0x5A), "kek-1");
+
+      assertThat(new BackupVerifier().verify(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t").status()).isEqualTo("ERROR");
+      assertThat(new BackupVerifier().verify(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t").messages()).anyMatch(m -> m.contains("no decrypt hook is configured"));
+
+      BackupsRuntime.getConfig().withArtifactTransformResolver(ref -> null);
+      assertThat(new BackupVerifier().verify(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t").messages()).anyMatch(m -> m.contains("No key is available for the key reference kek-1"));
+
+      BackupsRuntime.getConfig().withArtifactTransformResolver(ref -> new VerifyTestSupport.XorTransform(0x11));
+      VerificationOutcome wrongKey = new BackupVerifier().verify(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t");
+      assertThat(wrongKey.status()).isEqualTo("FAILED");
+      assertThat(wrongKey.messages()).anyMatch(m -> m.contains("corrupted, or the key is wrong"));
+
+      BackupsRuntime.getConfig().withArtifactTransformResolver(ref -> new VerifyTestSupport.XorTransform(0x5A));
+      List<VerificationOutcome> good = new BackupVerifier().verifyThrough(result.getRunId(), BackupVerifier.TEST_RESTORE, "MANUAL", "t");
+      assertThat(good).extracting(VerificationOutcome::status).containsExactly("PASSED", "PASSED", "PASSED");
+      assertThat(good.get(1).filesChecked()).isEqualTo(3);
+      assertThat(run(result.getRunId()).getValueString("verificationStatus")).isEqualTo("TEST_RESTORE_OK");
+   }
+
+
+
+   /*******************************************************************************
+    ** Files verified within fileReverifyDays are skipped; later they are checked again.
+    *******************************************************************************/
+   @Test
+   void testFileReverifyDaysBoundsTheWork() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of()));
+      assertThat(new BackupVerifier().verify(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t").filesChecked()).isEqualTo(3);
+
+      VerificationOutcome again = new BackupVerifier().verify(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t");
+      assertThat(again.filesChecked()).isZero();
+      assertThat(again.filesSkipped()).isEqualTo(3);
+
+      VerifyTestSupport.clock.advance(Duration.ofDays(31));
+      VerificationOutcome later = new BackupVerifier().verify(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t");
+      assertThat(later.filesChecked()).isEqualTo(3);
+      assertThat(later.filesSkipped()).isZero();
+   }
+
+
+
+   /*******************************************************************************
+    ** A cheap STORAGE pass does not clear a FAILED found by CONTENT, and never
+    ** downgrades a CONTENT_OK; a later CONTENT pass does clear the failure.
+    *******************************************************************************/
+   @Test
+   void testVerificationStatusRules() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of()));
+      new BackupVerifier().verify(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t");
+      assertThat(run(result.getRunId()).getValueString("verificationStatus")).isEqualTo("CONTENT_OK");
+      new BackupVerifier().verify(result.getRunId(), BackupVerifier.STORAGE, "MANUAL", "t");
+      assertThat(run(result.getRunId()).getValueString("verificationStatus")).isEqualTo("CONTENT_OK");
+
+      String key   = VerifyTestSupport.firstPartKey(result, "blogPost");
+      byte[] bytes = BackupsTestUtils.BACKUPS.getBytes(key).clone();
+      bytes[bytes.length / 2] ^= 0x55;
+      BackupsTestUtils.BACKUPS.corrupt(key, bytes);
+      new BackupVerifier().verify(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t");
+      assertThat(run(result.getRunId()).getValueString("verificationStatus")).isEqualTo("FAILED");
+      new BackupVerifier().verify(result.getRunId(), BackupVerifier.STORAGE, "MANUAL", "t");
+      assertThat(run(result.getRunId()).getValueString("verificationStatus")).isEqualTo("FAILED");
+   }
+
+
+
+   /*******************************************************************************
+    ** An ad-hoc run (no plan) verifies without touching a plan or raising plan alerts.
+    *******************************************************************************/
+   @Test
+   void testAdHocRunHasNoPlan() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of()));
+      new BackupCatalog().update(BackupsTables.RUN, result.getRunId(), java.util.Collections.singletonMap("backupPlanId", null));
+      assertThat(new BackupVerifier().verify(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t").status()).isEqualTo("PASSED");
+      assertThat(sink.raises).isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** A table that is no longer in the instance is checked as JSON with a warning; a
+    ** table whose schema changed is parsed without the exact round trip.
+    *******************************************************************************/
+   @Test
+   void testSchemaDriftIsAWarning() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of()));
+      QContext.getQInstance().getTable("blogPost").addField(new com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData("added", com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType.STRING));
+      QContext.getQInstance().getTables().remove("author");
+
+      VerificationOutcome outcome = new BackupVerifier().verify(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t");
+      assertThat(outcome.status()).isEqualTo("PASSED_WITH_WARNINGS");
+      assertThat(outcome.messages()).anyMatch(m -> m.contains("Table author no longer exists")).anyMatch(m -> m.contains("Table blogPost has changed since this backup"));
+      assertThat(outcome.passed()).isTrue();
+   }
+
+
+
+   /*******************************************************************************
+    ** CSV parts are hashed (stored and decoded bytes) but rows are not recounted.
+    *******************************************************************************/
+   @Test
+   void testCsvOnlyPlanIsHashedWithAWarning() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of("format", "CSV")));
+      assertThat(result.getStatus()).startsWith("SUCCEEDED");
+      VerificationOutcome outcome = new BackupVerifier().verify(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t");
+      assertThat(outcome.status()).isEqualTo("PASSED_WITH_WARNINGS");
+      assertThat(outcome.messages()).anyMatch(m -> m.contains("only CSV parts"));
+
+      BackupsTestUtils.BACKUPS.corrupt(VerifyTestSupport.firstPartKey(result, "author"), new byte[] { 1, 2, 3 });
+      assertThat(new BackupVerifier().verify(result.getRunId(), BackupVerifier.CONTENT, "MANUAL", "t").status()).isEqualTo("FAILED");
+   }
+
+
+
+   /*******************************************************************************
+    ** A good run test-restores into the memory scratch target: every table matches,
+    ** every file is restored and re-hashed, and the scratch tables and files are gone.
+    *******************************************************************************/
+   @Test
+   void testTestRestoreMemory() throws Exception
+   {
+      QRecord         plan   = plan(Map.of());
+      BackupRunResult result = backup(plan);
+
+      VerificationOutcome outcome = new BackupVerifier().verify(result.getRunId(), BackupVerifier.TEST_RESTORE, "MANUAL", "t");
+      assertThat(outcome.messages()).isEmpty();
+      assertThat(outcome.status()).isEqualTo("PASSED");
+      assertThat(outcome.rowsChecked()).isEqualTo(10);
+      assertThat(outcome.filesChecked()).isEqualTo(3);
+      assertThat(outcome.scratchTarget()).startsWith("memory:qqq_verify_");
+
+      assertThat(QContext.getQInstance().getTables().keySet()).noneMatch(n -> n.startsWith("qqq_verify_"));
+      assertThat(BackupsTestUtils.BACKUPS.list(TestRestoreVerifier.SCRATCH_FILE_PREFIX)).isEmpty();
+      QRecord row = new BackupCatalog().where(BackupsTables.VERIFICATION, "level", "TEST_RESTORE").get(0);
+      assertThat(row.getValueString("scratchTarget")).startsWith("memory:");
+      assertThat(row.getValueString("detailJson")).contains("\"filesRestored\":3");
+      assertThat(run(result.getRunId()).getValueString("verificationStatus")).isEqualTo("TEST_RESTORE_OK");
+      assertThat(reload(plan).getValueInteger("lastVerifiedRunId")).isEqualTo(result.getRunId());
+   }
+
+
+
+   /*******************************************************************************
+    ** Test restore catches rows that differ from the backed up rows, a missing
+    ** table, an unreadable part and a stored file that is not its hash.
+    *******************************************************************************/
+   @Test
+   void testTestRestoreCatchesProblems() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of()));
+      String          key    = VerifyTestSupport.firstPartKey(result, "blogPost");
+      byte[]          good   = BackupsTestUtils.BACKUPS.getBytes(key);
+
+      BackupsTestUtils.BACKUPS.putBytes(key, gzip(gunzip(good).replace("Post 1", "Post X")));
+      VerificationOutcome changed = new BackupVerifier().verify(result.getRunId(), BackupVerifier.TEST_RESTORE, "MANUAL", "t");
+      assertThat(changed.status()).isEqualTo("FAILED");
+      assertThat(changed.messages()).anyMatch(m -> m.contains("does not reproduce the backed up rows"));
+      assertThat(QContext.getQInstance().getTables().keySet()).noneMatch(n -> n.startsWith("qqq_verify_"));
+
+      BackupsTestUtils.BACKUPS.putBytes(key, new byte[] { 1, 2, 3 });
+      VerificationOutcome unreadable = new BackupVerifier().verify(result.getRunId(), BackupVerifier.TEST_RESTORE, "MANUAL", "t");
+      assertThat(unreadable.status()).isEqualTo("FAILED");
+      assertThat(unreadable.messages()).anyMatch(m -> m.contains("could not be restored"));
+      BackupsTestUtils.BACKUPS.putBytes(key, good);
+
+      QRecord file = new BackupCatalog().query(BackupsTables.FILE_OBJECT, new com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter()).get(0);
+      BackupsTestUtils.BACKUPS.corrupt(file.getValueString("objectKey"), "different bytes".getBytes(StandardCharsets.UTF_8));
+      VerificationOutcome badFile = new BackupVerifier().verify(result.getRunId(), BackupVerifier.TEST_RESTORE, "MANUAL", "t");
+      assertThat(badFile.status()).isEqualTo("FAILED");
+      assertThat(badFile.messages()).anyMatch(m -> m.startsWith("Test restore of file sha256")).anyMatch(m -> m.contains("do not resolve to a restored file"));
+      assertThat(BackupsTestUtils.BACKUPS.list(TestRestoreVerifier.SCRATCH_FILE_PREFIX)).isEmpty();
+
+      QContext.getQInstance().getTables().remove("author");
+      assertThat(new BackupVerifier().verify(result.getRunId(), BackupVerifier.TEST_RESTORE, "MANUAL", "t").messages()).anyMatch(m -> m.contains("Table author no longer exists"));
+   }
+
+
+
+   /*******************************************************************************
+    ** verifyFileSamplePercent 0 restores no files; CSV-only tables are skipped.
+    *******************************************************************************/
+   @Test
+   void testTestRestoreFileSampleAndCsv() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of("verifyFileSamplePercent", 0)));
+      VerificationOutcome outcome = new BackupVerifier().verify(result.getRunId(), BackupVerifier.TEST_RESTORE, "MANUAL", "t");
+      assertThat(outcome.status()).isEqualTo("PASSED");
+      assertThat(outcome.filesChecked()).isZero();
+
+      BackupRunResult csv = backup(VerifyTestSupport.plan(Map.of("name", "Csv", "planKey", "csv", "format", "CSV")));
+      VerificationOutcome csvOutcome = new BackupVerifier().verify(csv.getRunId(), BackupVerifier.TEST_RESTORE, "MANUAL", "t");
+      assertThat(csvOutcome.status()).isEqualTo("PASSED_WITH_WARNINGS");
+      assertThat(csvOutcome.messages()).anyMatch(m -> m.contains("only CSV parts and was not test-restored"));
+   }
+
+
+
+   /*******************************************************************************
+    ** The RDBMS_SCHEMA scratch target is a stub: it ends the verification with an
+    ** ERROR that says so, rather than passing.
+    *******************************************************************************/
+   @Test
+   void testRdbmsSchemaScratchTargetIsAStub() throws Exception
+   {
+      BackupsRuntime.getConfig().withScratchTarget(new RdbmsSchemaScratchTarget("scratchdb"));
+      BackupRunResult result = backup(plan(Map.of()));
+
+      VerificationOutcome outcome = new BackupVerifier().verify(result.getRunId(), BackupVerifier.TEST_RESTORE, "MANUAL", "t");
+      assertThat(outcome.status()).isEqualTo("ERROR");
+      assertThat(outcome.messages()).anyMatch(m -> m.contains("RDBMS_SCHEMA scratch target is not implemented yet"));
+
+      ScratchTarget target = BackupsRuntime.getConfig().getScratchTarget();
+      assertThat(target.type()).isEqualTo("RDBMS_SCHEMA");
+      assertThat(target.describe("2026-A")).isEqualTo("scratchdb:schema=qqq_verify_2026_a");
+      target.drop("2026-A");
+   }
+
+
+
+   /*******************************************************************************
+    ** The outcome of a verification that has not passed or failed reads sensibly.
+    *******************************************************************************/
+   @Test
+   void testManifestReadableByTheVerifier() throws Exception
+   {
+      BackupRunResult result = backup(plan(Map.of()));
+      BackupManifest  manifest = BackupManifest.read(BackupsTestUtils.BACKUPS.getBytes(result.getManifestKey()));
+      assertThat(manifest.tables()).hasSize(2);
+      assertThat(new VerificationOutcome(1, 2, "STORAGE", "ERROR", 0, 0, 1, 0, 0, 0, List.of(), null).passed()).isFalse();
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static String gunzip(byte[] bytes) throws Exception
+   {
+      return (new String(new java.util.zip.GZIPInputStream(new java.io.ByteArrayInputStream(bytes)).readAllBytes(), StandardCharsets.UTF_8));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static byte[] gzip(String text) throws Exception
+   {
+      ByteArrayOutputStream bytes = new ByteArrayOutputStream();
+      try(GZIPOutputStream out = new GZIPOutputStream(bytes))
+      {
+         out.write(text.getBytes(StandardCharsets.UTF_8));
+      }
+      return (bytes.toByteArray());
+   }
+}