feat(verify): backup verification, SLA checker, alerts, health, events, metrics

Verify backup (STORAGE, CONTENT, TEST_RESTORE with a MEMORY scratch target), the
scheduled backupCheckSla, every alert of the spec table with stable dedupe keys, a
reflective adapter for the Alerts qbit producer SPI, the health indicator, ESB events
and the Prometheus text.

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

.circleci/config.yml

@@ -1,14 +1,71 @@
 version: 2.1
-setup: true
+
 orbs:
-  qqq-orb: kingsrook/qqq-orb@0.8
+   qqq-orb: kingsrook/qqq-orb@0.6.8
+
+commands:
+   configure-package-install:
+      steps:
+         - run:
+              name: Keep package installation unattended
+              command: |
+                 # These build machines are discarded after the job.
+                 sudo install -d /etc/needrestart/conf.d
+                 printf '%s\n' '$nrconf{restart} = "l";' | sudo tee /etc/needrestart/conf.d/99-qqq-ci.conf >/dev/null
+
 workflows:
-  setup:
-    jobs:
-    - qqq-orb/generate_pipeline:
-        orb_version: '0.8'
-        filters:
-          branches:
-            ignore: automation/qbit-rc-pending
-          tags:
-            only: /v.*/
+   test_only:
+      jobs:
+         - qqq-orb/mvn_test_only:
+              pre-steps:
+                 - configure-package-install
+              context: [qqq-maven-registry-credentials]
+              filters:
+                 branches:
+                    ignore: /(develop|release\/.*|hotfix\/.*)/
+
+   publish_snapshot:
+      jobs:
+         - qqq-orb/mvn_publish:
+              pre-steps:
+                 - configure-package-install
+              context: [qqq-maven-registry-credentials]
+              branch_type: snapshot
+              filters:
+                 branches:
+                    only: [develop]
+
+   publish_release_candidate:
+      jobs:
+         - qqq-orb/mvn_publish:
+              pre-steps:
+                 - configure-package-install
+              context: [qqq-maven-registry-credentials]
+              branch_type: release_candidate
+              filters:
+                 branches:
+                    only: [/release\/.*/]
+
+   publish_release:
+      jobs:
+         - qqq-orb/mvn_publish:
+              pre-steps:
+                 - configure-package-install
+              context: [qqq-maven-registry-credentials]
+              branch_type: release
+              filters:
+                 branches:
+                    ignore: /.*/
+                 tags:
+                    only: [/^v\d+\.\d+\.\d+$/]
+
+   publish_hotfix_release:
+      jobs:
+         - qqq-orb/mvn_publish:
+              pre-steps:
+                 - configure-package-install
+              context: [qqq-maven-registry-credentials]
+              branch_type: hotfix
+              filters:
+                 branches:
+                    only: [/hotfix\/.*/]

.gitea/workflows/qrun-release.yaml

@@ -1,25 +0,0 @@
-# Standard QRun release caller (v2, thin contract): every push and manual dispatch delegates to the protected qrun-release-v1 channel. Do not edit per repository.
-name: qrun-release
-on:
-  push: {}
-  workflow_dispatch: {}
-permissions:
-  contents: read
-  actions: read
-jobs:
-  release:
-    uses: self:KofTwentyTwo/platform-ci/.gitea/workflows/java-docker.yaml@qrun-release-v1
-    with:
-      runner: linux-small
-      docker-runner: container-build
-      browsers: true
-      browser-runner: browser-build
-  postpublish:
-    if: ${{ needs.release.outputs.capture == 'true' }}
-    needs: release
-    permissions:
-      contents: write
-      actions: write
-    uses: self:KofTwentyTwo/platform-ci/.gitea/workflows/qrun-source-version.yaml@qrun-release-v1
-    with:
-      runner: linux-small

.github/workflows/codeql.yml

@@ -1,23 +0,0 @@
-name: CodeQL
-'on':
-  push:
-    branches:
-    - main
-    - develop
-    - release/**
-    - hotfix/**
-  pull_request: {}
-  schedule:
-  - cron: 41 16 * * 0
-  workflow_dispatch: {}
-permissions:
-  contents: read
-  actions: read
-  security-events: write
-  packages: read
-concurrency:
-  group: codeql-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-jobs:
-  analyze:
-    uses: QRun-IO/qqq-orb/.github/workflows/qbit-codeql.yml@c288a8864fe9054f68410e1d78f5863aea4c4d22

.qqq-ci.yml

@@ -1,16 +0,0 @@
-profile: qbit
-orb_version: '0.8'
-default_branch: develop
-java_version: '21'
-browsers: true
-api_checks: false
-docs_only: false
-release_on_main: false
-release_tag_policy: v-prefix
-test_branch_policy: non-release-no-hotfix
-publish:
-  snapshot: true
-  release_candidate: true
-  release: true
-  hotfix: true
-  asciidoc: false

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

@@ -18,16 +18,23 @@ 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;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
 
 
 /*******************************************************************************
- ** Host-facing configuration for the Backups QBit.
+ ** Configuration of the Backups qbit.
  **
- ** Tables are named backups_<name> (lowercase snake_case, backend name equal
- ** to the table name); permissions are backups.<action>.
+ ** Storage is resolved through a function from a bucket alias (the value of
+ ** backups_plan.storageBucketAlias) to a BackupStorage.  The production resolver
+ ** is backed by qbit-object-storage; tests and local development use the
+ ** in-memory implementation.  No credential is ever held here or in a table.
  *******************************************************************************/
 public class BackupsQBitConfig implements QBitConfig
 {
@@ -35,6 +42,24 @@ public class BackupsQBitConfig implements QBitConfig
    public static final String PERMISSION_BASE_NAME = "backups";
 
    private String backendName;
+   private String appName  = "backups";
+   private String appLabel = "Backups";
+   private String parentAppName;
+   private String schedulerName;
+   private String instanceName;
+
+   private Integer maxConcurrentRuns       = 1;
+   private Integer slaCheckIntervalSeconds = 300;
+   private Boolean openWhenAnonymous       = false;
+   private Boolean prometheusEndpoint      = false;
+
+   private Function<String, BackupStorage> storageResolver;
+
+   private Integer                          fileReverifyDays  = 30;
+   private Function<String, ArtifactTransform> artifactTransformResolver;
+   private ScratchTarget                    scratchTarget;
+   private Predicate<String>                planOwnerValidator;
+   private String                           esbDestinationName;
 
 
 
@@ -89,4 +114,319 @@ public class BackupsQBitConfig implements QBitConfig
       return (this);
    }
 
+
+
+   /*******************************************************************************
+    ** Getter for appName
+    *******************************************************************************/
+   public String getAppName()
+   {
+      return (appName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for appName
+    *******************************************************************************/
+   public BackupsQBitConfig withAppName(String appName)
+   {
+      this.appName = appName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for appLabel
+    *******************************************************************************/
+   public String getAppLabel()
+   {
+      return (appLabel);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for appLabel
+    *******************************************************************************/
+   public BackupsQBitConfig withAppLabel(String appLabel)
+   {
+      this.appLabel = appLabel;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for parentAppName (for example "admin", so this is Admin, Backups).
+    *******************************************************************************/
+   public String getParentAppName()
+   {
+      return (parentAppName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for parentAppName
+    *******************************************************************************/
+   public BackupsQBitConfig withParentAppName(String parentAppName)
+   {
+      this.parentAppName = parentAppName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for schedulerName (the QQQ scheduler used for plan jobs and the SLA checker)
+    *******************************************************************************/
+   public String getSchedulerName()
+   {
+      return (schedulerName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for schedulerName
+    *******************************************************************************/
+   public BackupsQBitConfig withSchedulerName(String schedulerName)
+   {
+      this.schedulerName = schedulerName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for instanceName (used in object keys); defaults to the QInstance name
+    *******************************************************************************/
+   public String getInstanceName()
+   {
+      return (instanceName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for instanceName
+    *******************************************************************************/
+   public BackupsQBitConfig withInstanceName(String instanceName)
+   {
+      this.instanceName = instanceName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for maxConcurrentRuns
+    *******************************************************************************/
+   public Integer getMaxConcurrentRuns()
+   {
+      return (maxConcurrentRuns);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for maxConcurrentRuns
+    *******************************************************************************/
+   public BackupsQBitConfig withMaxConcurrentRuns(Integer maxConcurrentRuns)
+   {
+      this.maxConcurrentRuns = maxConcurrentRuns;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for slaCheckIntervalSeconds
+    *******************************************************************************/
+   public Integer getSlaCheckIntervalSeconds()
+   {
+      return (slaCheckIntervalSeconds);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for slaCheckIntervalSeconds
+    *******************************************************************************/
+   public BackupsQBitConfig withSlaCheckIntervalSeconds(Integer slaCheckIntervalSeconds)
+   {
+      this.slaCheckIntervalSeconds = slaCheckIntervalSeconds;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for openWhenAnonymous (local development only)
+    *******************************************************************************/
+   public Boolean getOpenWhenAnonymous()
+   {
+      return (openWhenAnonymous);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for openWhenAnonymous
+    *******************************************************************************/
+   public BackupsQBitConfig withOpenWhenAnonymous(Boolean openWhenAnonymous)
+   {
+      this.openWhenAnonymous = openWhenAnonymous;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for prometheusEndpoint
+    *******************************************************************************/
+   public Boolean getPrometheusEndpoint()
+   {
+      return (prometheusEndpoint);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for prometheusEndpoint
+    *******************************************************************************/
+   public BackupsQBitConfig withPrometheusEndpoint(Boolean prometheusEndpoint)
+   {
+      this.prometheusEndpoint = prometheusEndpoint;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for storageResolver
+    *******************************************************************************/
+   public Function<String, BackupStorage> getStorageResolver()
+   {
+      return (storageResolver);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for storageResolver: bucket alias to storage
+    *******************************************************************************/
+   public BackupsQBitConfig withStorageResolver(Function<String, BackupStorage> storageResolver)
+   {
+      this.storageResolver = storageResolver;
+      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

@@ -100,4 +100,62 @@ public class BackupsQBitProducer implements QBitMetaDataProducer<BackupsQBitConf
       return (qBitConfig != null);
    }
 
+
+
+   /*******************************************************************************
+    ** Build everything and add it to the instance: possible-value sources, joins,
+    ** tables, processes, widgets and the app.
+    *******************************************************************************/
+   @Override
+   public com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput produce(com.kingsrook.qqq.backend.core.model.metadata.QInstance qInstance) throws com.kingsrook.qqq.backend.core.exceptions.QException
+   {
+      java.util.List<String> errors = new java.util.ArrayList<>();
+      qBitConfig.validate(qInstance, errors);
+      if(!errors.isEmpty())
+      {
+         throw (new com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitConfigValidationException(qBitConfig, errors));
+      }
+      QBitMetaData qBit = getQBitMetaData();
+      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())
+      {
+         output.add(possibleValueSource);
+      }
+      for(var join : com.kingsrook.qbits.backups.model.BackupsTables.joins())
+      {
+         output.add(join);
+      }
+      java.util.List<com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData> tables = new java.util.ArrayList<>();
+      for(var table : com.kingsrook.qbits.backups.model.BackupsTables.tables(qBitConfig))
+      {
+         var customized = qBitConfig.getTableMetaDataCustomizer() == null ? table : qBitConfig.getTableMetaDataCustomizer().customizeMetaData(qInstance, table);
+         customized.setSourceQBitName(qBit.getName());
+         tables.add(customized);
+         output.add(customized);
+      }
+      for(var process : com.kingsrook.qbits.backups.processes.BackupsProcesses.processes())
+      {
+         process.setSourceQBitName(qBit.getName());
+         output.add(process);
+      }
+      for(var widget : com.kingsrook.qbits.backups.app.BackupsApp.widgets())
+      {
+         output.add(widget);
+      }
+      output.add(com.kingsrook.qbits.backups.app.BackupsApp.app(qBitConfig, tables));
+      output.addSelfToInstance(qInstance);
+      return (new com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput());
+   }
+
 }

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

@@ -0,0 +1,195 @@
+/*
+ * 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.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.function.Function;
+import com.kingsrook.qbits.backups.alerts.BackupAlertSink;
+import com.kingsrook.qbits.backups.alerts.NoOpBackupAlertSink;
+import com.kingsrook.qbits.backups.storage.BackupStorage;
+import com.kingsrook.qbits.backups.storage.BackupStorageException;
+
+
+/*******************************************************************************
+ ** Process-wide state of the installed qbit: the config, the clock, the alert
+ ** sink and the per-process permission map.  Static because QQQ instantiates
+ ** steps and permission checkers by class reference.
+ *******************************************************************************/
+public final class BackupsRuntime
+{
+   private static final Map<String, String> PROCESS_PERMISSIONS = new ConcurrentHashMap<>();
+
+   private static volatile BackupsQBitConfig config;
+   private static volatile Clock             clock           = Clock.systemUTC();
+   private static volatile BackupAlertSink   alertSink       = new NoOpBackupAlertSink();
+   private static volatile Function<String, String> environment = System::getenv;
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private BackupsRuntime()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Install the config (called by the producer).
+    *******************************************************************************/
+   public static void install(BackupsQBitConfig newConfig)
+   {
+      config = newConfig;
+   }
+
+
+
+   /*******************************************************************************
+    ** Forget everything (tests).
+    *******************************************************************************/
+   public static void reset()
+   {
+      config = null;
+      clock = Clock.systemUTC();
+      alertSink = new NoOpBackupAlertSink();
+      environment = System::getenv;
+      PROCESS_PERMISSIONS.clear();
+   }
+
+
+
+   /*******************************************************************************
+    ** The installed config, or null.
+    *******************************************************************************/
+   public static BackupsQBitConfig getConfig()
+   {
+      return (config);
+   }
+
+
+
+   /*******************************************************************************
+    ** Whether the qbit is installed.
+    *******************************************************************************/
+   public static boolean isInstalled()
+   {
+      return (config != null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Whether permissions are open on fully anonymous instances (local development).
+    *******************************************************************************/
+   public static boolean isOpenWhenAnonymous()
+   {
+      return (config != null && Boolean.TRUE.equals(config.getOpenWhenAnonymous()));
+   }
+
+
+
+   /*******************************************************************************
+    ** The clock (replaceable in tests).
+    *******************************************************************************/
+   public static Clock getClock()
+   {
+      return (clock);
+   }
+
+
+
+   /*******************************************************************************
+    ** Replace the clock.
+    *******************************************************************************/
+   public static void setClock(Clock newClock)
+   {
+      clock = newClock;
+   }
+
+
+
+   /*******************************************************************************
+    ** The alert sink.
+    *******************************************************************************/
+   public static BackupAlertSink getAlertSink()
+   {
+      return (alertSink);
+   }
+
+
+
+   /*******************************************************************************
+    ** Bind an alert sink (the Alerts qbit adapter, or a test double).
+    *******************************************************************************/
+   public static void setAlertSink(BackupAlertSink newSink)
+   {
+      alertSink = newSink == null ? new NoOpBackupAlertSink() : newSink;
+   }
+
+
+
+   /*******************************************************************************
+    ** Environment lookup (replaceable in tests).
+    *******************************************************************************/
+   public static Function<String, String> getEnvironment()
+   {
+      return (environment);
+   }
+
+
+
+   /*******************************************************************************
+    ** Replace the environment lookup.
+    *******************************************************************************/
+   public static void setEnvironment(Function<String, String> newEnvironment)
+   {
+      environment = newEnvironment;
+   }
+
+
+
+   /*******************************************************************************
+    ** The permission each qbit process needs, by process name.
+    *******************************************************************************/
+   public static Map<String, String> processPermissions()
+   {
+      return (PROCESS_PERMISSIONS);
+   }
+
+
+
+   /*******************************************************************************
+    ** Resolve the storage for a bucket alias.
+    *******************************************************************************/
+   public static BackupStorage storageFor(String bucketAlias)
+   {
+      if(config == null || config.getStorageResolver() == null)
+      {
+         throw (new BackupStorageException(BackupStorageException.Reason.UNSUPPORTED, "No storage resolver is configured for the Backups qbit"));
+      }
+      BackupStorage storage = config.getStorageResolver().apply(bucketAlias);
+      if(storage == null)
+      {
+         throw (new BackupStorageException(BackupStorageException.Reason.NOT_FOUND, "No storage bucket is configured with the alias: " + bucketAlias));
+      }
+      return (storage);
+   }
+}

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/BackupAlertSink.java

@@ -0,0 +1,65 @@
+/*
+ * 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;
+
+
+/*******************************************************************************
+ ** Where backups raises and resolves alerts.  The adapter for the Alerts qbit
+ ** producer SPI binds here when that qbit is installed; otherwise the no-op
+ ** sink is used and every condition is still visible on the Backups home and in
+ ** the tables.  An alert has a stable dedupe key; counts and links only, never
+ ** values, keys or presigned URLs.
+ *******************************************************************************/
+public interface BackupAlertSink
+{
+
+   /***************************************************************************
+    ** Raise (or refresh) an alert.
+    **
+    ** @param type alert type, e.g. backups.plan.missed
+    ** @param dedupeKey stable key, type plus plan or run
+    ** @param severity severity
+    ** @param title short title
+    ** @param detail counts and context only
+    ***************************************************************************/
+   void raise(String type, String dedupeKey, Severity severity, String title, Map<String, String> detail);
+
+
+   /***************************************************************************
+    ** Resolve an alert that was raised under the dedupe key.
+    ***************************************************************************/
+   void resolve(String type, String dedupeKey);
+
+
+   /***************************************************************************
+    ** Check in a heartbeat monitor: the plan ran successfully.
+    ***************************************************************************/
+   void heartbeat(String monitorKey, long expectedEverySeconds, long graceSeconds);
+
+
+
+   /***************************************************************************
+    ** Severities.
+    ***************************************************************************/
+   enum Severity
+   {
+      INFO, WARNING, ERROR, CRITICAL
+   }
+}

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/alerts/NoOpBackupAlertSink.java

@@ -0,0 +1,56 @@
+/*
+ * 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;
+
+
+/*******************************************************************************
+ ** The sink used when the Alerts qbit is not installed.
+ *******************************************************************************/
+public class NoOpBackupAlertSink implements BackupAlertSink
+{
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public void raise(String type, String dedupeKey, Severity severity, String title, Map<String, String> detail)
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public void resolve(String type, String dedupeKey)
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public void heartbeat(String monitorKey, long expectedEverySeconds, long graceSeconds)
+   {
+   }
+}

src/main/java/com/kingsrook/qbits/backups/app/BackupsApp.java

@@ -0,0 +1,152 @@
+/*
+ * 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.app;
+
+
+import java.util.List;
+import com.kingsrook.qbits.backups.BackupsQBitConfig;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qqq.backend.core.actions.dashboard.widgets.AbstractWidgetRenderer;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetInput;
+import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetOutput;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.RawHTML;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.WidgetType;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppSection;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** The Backups app (a sub-app under Admin when configured) and its widgets.  The
+ ** home is the single owner of backup data: every card is built from the qbit
+ ** tables, and each has an honest empty state.  The nav lists the main tables;
+ ** sub-tables appear as child lists on their parents.
+ *******************************************************************************/
+public final class BackupsApp
+{
+   public static final String HOME_WIDGET        = "backupsHome";
+   public static final String HEALTH_CARD_WIDGET = "backupsHealthCard";
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private BackupsApp()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** The widgets.
+    *******************************************************************************/
+   public static List<QWidgetMetaData> widgets()
+   {
+      return (List.of(
+         new QWidgetMetaData().withName(HOME_WIDGET).withLabel("Backups").withType(WidgetType.HTML.getType())
+            .withCodeReference(new QCodeReference(HomeRenderer.class)).withGridColumns(12).withIsCard(false).withPermissionRules(BackupsTables.permissionRules()),
+         new QWidgetMetaData().withName(HEALTH_CARD_WIDGET).withLabel("Backups").withType(WidgetType.HTML.getType())
+            .withCodeReference(new QCodeReference(HealthCardRenderer.class)).withGridColumns(12).withIsCard(true).withPermissionRules(BackupsTables.permissionRules())));
+   }
+
+
+
+   /*******************************************************************************
+    ** The app: the main tables only; sub-tables are relations on their parents.
+    *******************************************************************************/
+   public static QAppMetaData app(BackupsQBitConfig config, List<QTableMetaData> tables)
+   {
+      QAppMetaData app = new QAppMetaData()
+         .withName(config.getAppName())
+         .withLabel(config.getAppLabel())
+         .withIcon(new QIcon("backup"))
+         .withPermissionRules(BackupsTables.permissionRules())
+         .withWidgets(List.of(HOME_WIDGET))
+         .withSection(new QAppSection().withName("backups").withLabel("Backups").withIcon(new QIcon("backup"))
+            .withTables(List.of(BackupsTables.PLAN, BackupsTables.RUN)))
+         .withSection(new QAppSection().withName("recovery").withLabel("Restore and verify").withIcon(new QIcon("restore"))
+            .withTables(List.of(BackupsTables.RESTORE_RUN, BackupsTables.VERIFICATION)))
+         .withSection(new QAppSection().withName("files").withLabel("Files").withIcon(new QIcon("attach_file"))
+            .withTables(List.of(BackupsTables.FILE_OBJECT)));
+      if(config.getParentAppName() != null)
+      {
+         app.setParentAppName(config.getParentAppName());
+      }
+      for(QTableMetaData table : tables)
+      {
+         if(BackupsTables.NAV_TABLES.contains(table.getName()))
+         {
+            app.withChild(table);
+         }
+      }
+      return (app);
+   }
+
+
+
+   /*******************************************************************************
+    ** The home.
+    *******************************************************************************/
+   public static class HomeRenderer extends AbstractWidgetRenderer
+   {
+      /*******************************************************************************
+       ** Render.
+       *******************************************************************************/
+      @Override
+      public RenderWidgetOutput render(RenderWidgetInput input) throws QException
+      {
+         return (new RenderWidgetOutput(new RawHTML(null, BackupsHomeView.render(BackupsHomeData.load(), pathPrefix()))));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The status card for Admin, Health.
+    *******************************************************************************/
+   public static class HealthCardRenderer extends AbstractWidgetRenderer
+   {
+      /*******************************************************************************
+       ** Render.
+       *******************************************************************************/
+      @Override
+      public RenderWidgetOutput render(RenderWidgetInput input) throws QException
+      {
+         return (new RenderWidgetOutput(new RawHTML("Backups", BackupsHomeView.renderHealthCard(BackupsHomeData.load(), pathPrefix()))));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The path prefix of table and record links.
+    *******************************************************************************/
+   static String pathPrefix()
+   {
+      var config = com.kingsrook.qbits.backups.BackupsRuntime.getConfig();
+      if(config == null)
+      {
+         return ("/backups");
+      }
+      return (config.getParentAppName() != null ? "/" + config.getParentAppName() + "/" + config.getAppName() : "/" + config.getAppName());
+   }
+}

src/main/java/com/kingsrook/qbits/backups/app/BackupsHomeData.java

@@ -0,0 +1,255 @@
+/*
+ * 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.app;
+
+
+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 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.QFilterOrderBy;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** The data behind the Backups home: plan status, what needs attention, recent
+ ** activity and the size trend.  Everything is read from the qbit tables; nothing
+ ** is invented.  Home cards read the denormalized plan fields (slaStatus, last
+ ** success) that the processes and the SLA checker maintain.
+ *******************************************************************************/
+public class BackupsHomeData
+{
+   /** Plan statuses that need attention (the plan or its backups have a problem). */
+   public static final List<String> ATTENTION = List.of("LATE", "FAILING", "MISSING_IN_STORAGE", "UNVERIFIED", "ABANDONED", "OWNER_INVALID");
+
+   private final List<QRecord> plans;
+   private final List<QRecord> recentRuns;
+   private final List<QRecord> failedRuns;
+   private final List<QRecord> verifications;
+   private final List<QRecord> restores;
+   private final Instant       now;
+
+
+
+   /*******************************************************************************
+    ** Constructor.
+    *******************************************************************************/
+   BackupsHomeData(List<QRecord> plans, List<QRecord> recentRuns, List<QRecord> failedRuns, List<QRecord> verifications, List<QRecord> restores, Instant now)
+   {
+      this.plans = plans;
+      this.recentRuns = recentRuns;
+      this.failedRuns = failedRuns;
+      this.verifications = verifications;
+      this.restores = restores;
+      this.now = now;
+   }
+
+
+
+   /*******************************************************************************
+    ** Load from the tables.
+    *******************************************************************************/
+   public static BackupsHomeData load() throws QException
+   {
+      BackupCatalog catalog = new BackupCatalog();
+      Instant       now     = BackupsRuntime.getClock().instant();
+      List<QRecord> plans   = catalog.query(BackupsTables.PLAN, new QQueryFilter().withOrderBy(new QFilterOrderBy("name", true)));
+
+      QQueryFilter recent = new QQueryFilter().withOrderBy(new QFilterOrderBy("id", false));
+      recent.setLimit(200);
+      List<QRecord> runs = catalog.query(BackupsTables.RUN, recent);
+      List<QRecord> failed = new ArrayList<>();
+      Instant weekAgo = now.minus(Duration.ofDays(7));
+      for(QRecord run : runs)
+      {
+         Instant start = run.getValueInstant("startDate");
+         if(List.of("FAILED", "TIMED_OUT", "ABANDONED").contains(run.getValueString("status")) && (start == null || start.isAfter(weekAgo)))
+         {
+            failed.add(run);
+         }
+      }
+      QQueryFilter verificationFilter = new QQueryFilter().withOrderBy(new QFilterOrderBy("id", false));
+      verificationFilter.setLimit(100);
+      QQueryFilter restoreFilter = new QQueryFilter().withOrderBy(new QFilterOrderBy("id", false));
+      restoreFilter.setLimit(20);
+      return (new BackupsHomeData(plans, runs, failed, catalog.query(BackupsTables.VERIFICATION, verificationFilter),
+         catalog.query(BackupsTables.RESTORE_RUN, restoreFilter), now));
+   }
+
+
+
+   /*******************************************************************************
+    ** Plans.
+    *******************************************************************************/
+   public List<QRecord> plans()
+   {
+      return (plans);
+   }
+
+
+
+   /*******************************************************************************
+    ** Recent runs (newest first).
+    *******************************************************************************/
+   public List<QRecord> recentRuns()
+   {
+      return (recentRuns);
+   }
+
+
+
+   /*******************************************************************************
+    ** Runs that failed in the last 7 days.
+    *******************************************************************************/
+   public List<QRecord> failedRuns()
+   {
+      return (failedRuns);
+   }
+
+
+
+   /*******************************************************************************
+    ** Verifications (newest first).
+    *******************************************************************************/
+   public List<QRecord> verifications()
+   {
+      return (verifications);
+   }
+
+
+
+   /*******************************************************************************
+    ** Restores (newest first).
+    *******************************************************************************/
+   public List<QRecord> restores()
+   {
+      return (restores);
+   }
+
+
+
+   /*******************************************************************************
+    ** The time the data was loaded.
+    *******************************************************************************/
+   public Instant now()
+   {
+      return (now);
+   }
+
+
+
+   /*******************************************************************************
+    ** Plans that need attention.
+    *******************************************************************************/
+   public List<QRecord> plansNeedingAttention()
+   {
+      return (plans.stream().filter(p -> Boolean.TRUE.equals(p.getValueBoolean("isActive")) && ATTENTION.contains(p.getValueString("slaStatus"))).toList());
+   }
+
+
+
+   /*******************************************************************************
+    ** The overall state: NO_PLANS, ATTENTION or OK.
+    *******************************************************************************/
+   public String overallState()
+   {
+      if(plans.isEmpty())
+      {
+         return ("NO_PLANS");
+      }
+      return (plansNeedingAttention().isEmpty() && failedRuns.isEmpty() ? "OK" : "ATTENTION");
+   }
+
+
+
+   /*******************************************************************************
+    ** Hours since the last successful backup of a plan, or null when it has none.
+    *******************************************************************************/
+   public Long ageHours(QRecord plan)
+   {
+      Instant last = plan.getValueInstant("lastSuccessDate");
+      return (last == null ? null : Duration.between(last, now).toHours());
+   }
+
+
+
+   /*******************************************************************************
+    ** The latest test restore of a plan, or null.
+    *******************************************************************************/
+   public QRecord latestTestRestore(Integer planId)
+   {
+      for(QRecord verification : verifications)
+      {
+         if("TEST_RESTORE".equals(verification.getValueString("level")))
+         {
+            Integer runId = verification.getValueInteger("backupRunId");
+            for(QRecord run : recentRuns)
+            {
+               if(runId != null && runId.equals(run.getValueInteger("id")) && planId.equals(run.getValueInteger("backupPlanId")))
+               {
+                  return (verification);
+               }
+            }
+         }
+      }
+      return (null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Successful runs of a plan, oldest first, for the trend (bytes stored, rows, duration).
+    *******************************************************************************/
+   public List<QRecord> successfulRuns(Integer planId)
+   {
+      List<QRecord> rs = new ArrayList<>();
+      for(QRecord run : recentRuns)
+      {
+         if(planId.equals(run.getValueInteger("backupPlanId")) && run.getValueString("status") != null && run.getValueString("status").startsWith("SUCCEEDED"))
+         {
+            rs.add(0, run);
+         }
+      }
+      return (rs);
+   }
+
+
+
+   /*******************************************************************************
+    ** Runs kept per retention class for a plan (as classified by the last prune).
+    *******************************************************************************/
+   public Map<String, Integer> retentionCounts(Integer planId)
+   {
+      Map<String, Integer> counts = new LinkedHashMap<>();
+      for(QRecord run : recentRuns)
+      {
+         if(planId.equals(run.getValueInteger("backupPlanId")) && run.getValueString("status") != null && run.getValueString("status").startsWith("SUCCEEDED")
+            && run.getValue("prunedDate") == null)
+         {
+            counts.merge(run.getValueString("retentionClass") == null ? "UNCLASSIFIED" : run.getValueString("retentionClass"), 1, Integer::sum);
+         }
+      }
+      return (counts);
+   }
+}

src/main/java/com/kingsrook/qbits/backups/app/BackupsHomeView.java

@@ -0,0 +1,396 @@
+/*
+ * 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.app;
+
+
+import java.time.Instant;
+import java.time.ZoneOffset;
+import java.time.format.DateTimeFormatter;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Renders the Backups home: one card per concern, each with an honest empty
+ ** state.  Cards stack to one column on narrow screens, long names wrap, and
+ ** there are no tables and no inner horizontal scroll (definition lists and
+ ** lists only), so it reads at every width in light and dark mode (colors are
+ ** inherited, not set).
+ *******************************************************************************/
+public final class BackupsHomeView
+{
+   private static final DateTimeFormatter WHEN = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm 'UTC'").withZone(ZoneOffset.UTC);
+
+   private static final String GRID  = "display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,22rem),1fr));gap:1rem;";
+   private static final String CARD  = "border:1px solid rgba(127,127,127,.3);border-radius:8px;padding:1rem;min-width:0;overflow-wrap:anywhere;";
+   private static final String LIST  = "display:grid;grid-template-columns:minmax(7rem,auto) 1fr;gap:.25rem .75rem;margin:0 0 .75rem;font-size:.9rem;";
+   private static final String ITEMS = "margin:0 0 .75rem;padding-left:1.25rem;font-size:.9rem;";
+   private static final String MUTED = "opacity:.75;";
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private BackupsHomeView()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** The whole home; pathPrefix is the prefix of table and record links.
+    *******************************************************************************/
+   public static String render(BackupsHomeData data, String pathPrefix)
+   {
+      StringBuilder html = new StringBuilder("<div class=\"backups-home\" style=\"" + GRID + "\">");
+      planStatus(html, data, pathPrefix);
+      needsAttention(html, data, pathPrefix);
+      latestTestRestore(html, data, pathPrefix);
+      trend(html, data);
+      recentActivity(html, data, pathPrefix);
+      retention(html, data);
+      return (html.append("</div>").toString());
+   }
+
+
+
+   /*******************************************************************************
+    ** The one status card for Admin, Health.
+    *******************************************************************************/
+   public static String renderHealthCard(BackupsHomeData data, String pathPrefix)
+   {
+      String text = switch(data.overallState())
+      {
+         case "NO_PLANS" -> "No backup plans yet.";
+         case "ATTENTION" -> "Needs attention: see the Backups home.";
+         default -> "All backups are within their SLA.";
+      };
+      return ("<div style=\"" + CARD + "\"><strong>Backups</strong><p>" + esc(text) + "</p><a href=\"" + esc(pathPrefix) + "\">Open the Backups home</a></div>");
+   }
+
+
+
+   /*******************************************************************************
+    ** Plan status: last successful backup, age against the SLA, last run, verification.
+    *******************************************************************************/
+   private static void planStatus(StringBuilder html, BackupsHomeData data, String prefix)
+   {
+      open(html, "Plan status");
+      if(data.plans().isEmpty())
+      {
+         empty(html, "No backup plans yet. Create one from Backup plans, New.");
+      }
+      for(QRecord plan : data.plans())
+      {
+         Long   age = data.ageHours(plan);
+         Integer sla = plan.getValueInteger("slaHours");
+         html.append("<dl style=\"").append(LIST).append("\">");
+         html.append("<dt><strong>Plan</strong></dt><dd><a href=\"").append(esc(prefix + "/" + BackupsTables.PLAN + "/" + plan.getValue("id"))).append("\">")
+            .append(esc(plan.getValueString("name"))).append("</a>").append(Boolean.TRUE.equals(plan.getValueBoolean("isActive")) ? "" : " (not active)").append("</dd>");
+         row(html, "Status", label(plan.getValueString("slaStatus")));
+         row(html, "Last backup", plan.getValueInstant("lastSuccessDate") == null ? "No successful backup yet" : WHEN.format(plan.getValueInstant("lastSuccessDate")));
+         if(age != null && sla != null)
+         {
+            row(html, "Age against SLA", age + " h of " + sla + " h" + (age > sla ? " - late" : ""));
+         }
+         row(html, "Last verified", plan.getValueInstant("lastVerifiedDate") == null ? "Not verified yet" : WHEN.format(plan.getValueInstant("lastVerifiedDate")));
+         row(html, "Schedule", plan.getValueString("cronExpression") == null ? "Manual only" : plan.getValueString("cronExpression"));
+         if(plan.getValueString("objectLockMode") != null && !"NONE".equals(plan.getValueString("objectLockMode")))
+         {
+            row(html, "Object lock", plan.getValueString("objectLockMode") + ", " + plan.getValueInteger("objectLockDays") + " days");
+         }
+         html.append("</dl>");
+      }
+      link(html, prefix, BackupsTables.PLAN, "Backup plans");
+      close(html);
+   }
+
+
+
+   /*******************************************************************************
+    ** Needs attention.
+    *******************************************************************************/
+   private static void needsAttention(StringBuilder html, BackupsHomeData data, String prefix)
+   {
+      open(html, "Needs attention");
+      List<QRecord> plans = data.plansNeedingAttention();
+      if(data.plans().isEmpty())
+      {
+         empty(html, "Nothing to check yet: no plans.");
+      }
+      else if(plans.isEmpty() && data.failedRuns().isEmpty())
+      {
+         empty(html, "Nothing needs attention.");
+      }
+      else
+      {
+         html.append("<ul style=\"").append(ITEMS).append("\">");
+         for(QRecord plan : plans)
+         {
+            html.append("<li><a href=\"").append(esc(prefix + "/" + BackupsTables.PLAN + "/" + plan.getValue("id"))).append("\">").append(esc(plan.getValueString("name")))
+               .append("</a>: ").append(esc(label(plan.getValueString("slaStatus")))).append("</li>");
+         }
+         for(QRecord run : data.failedRuns())
+         {
+            html.append("<li><a href=\"").append(esc(prefix + "/" + BackupsTables.RUN + "/" + run.getValue("id"))).append("\">Run ").append(esc(run.getValueString("runKey")))
+               .append("</a> ").append(esc(label(run.getValueString("status")))).append("</li>");
+         }
+         html.append("</ul>");
+      }
+      link(html, prefix, BackupsTables.RUN, "All runs");
+      close(html);
+   }
+
+
+
+   /*******************************************************************************
+    ** Latest test restore per plan.
+    *******************************************************************************/
+   private static void latestTestRestore(StringBuilder html, BackupsHomeData data, String prefix)
+   {
+      open(html, "Latest test restore");
+      boolean any = false;
+      for(QRecord plan : data.plans())
+      {
+         QRecord v = data.latestTestRestore(plan.getValueInteger("id"));
+         if(v == null)
+         {
+            continue;
+         }
+         any = true;
+         html.append("<dl style=\"").append(LIST).append("\">");
+         row(html, "Plan", plan.getValueString("name"));
+         row(html, "Result", label(v.getValueString("status")));
+         row(html, "Compared", v.getValueInteger("tablesChecked") + " tables, " + v.getValueLong("rowsChecked") + " rows, " + v.getValueInteger("mismatches") + " mismatches");
+         row(html, "Scratch target", v.getValueString("scratchTarget") == null ? "Not recorded" : v.getValueString("scratchTarget"));
+         html.append("</dl>");
+      }
+      if(!any)
+      {
+         empty(html, "No test restore yet. Run Verify backup, Test restore on a run, or set a verify schedule on the plan.");
+      }
+      link(html, prefix, BackupsTables.VERIFICATION, "All verifications");
+      close(html);
+   }
+
+
+
+   /*******************************************************************************
+    ** Size and duration trend per plan, as numbers next to each other.
+    *******************************************************************************/
+   private static void trend(StringBuilder html, BackupsHomeData data)
+   {
+      open(html, "Size and duration trend");
+      boolean any = false;
+      for(QRecord plan : data.plans())
+      {
+         List<QRecord> runs = data.successfulRuns(plan.getValueInteger("id"));
+         if(runs.isEmpty())
+         {
+            continue;
+         }
+         any = true;
+         QRecord first = runs.get(0);
+         QRecord last  = runs.get(runs.size() - 1);
+         html.append("<dl style=\"").append(LIST).append("\">");
+         row(html, "Plan", plan.getValueString("name"));
+         row(html, "Successful runs", String.valueOf(runs.size()));
+         row(html, "Stored (first, latest)", bytes(first.getValueLong("bytesStored")) + ", " + bytes(last.getValueLong("bytesStored")));
+         row(html, "Rows (first, latest)", number(first.getValueLong("rowsTotal")) + ", " + number(last.getValueLong("rowsTotal")));
+         row(html, "Duration (latest)", last.getValueLong("durationMs") == null ? "Not recorded" : last.getValueLong("durationMs") / 1000 + " s");
+         html.append("</dl>");
+      }
+      if(!any)
+      {
+         empty(html, "Trends appear after the first successful run.");
+      }
+      close(html);
+   }
+
+
+
+   /*******************************************************************************
+    ** Recent activity: the last runs and restores.
+    *******************************************************************************/
+   private static void recentActivity(StringBuilder html, BackupsHomeData data, String prefix)
+   {
+      open(html, "Recent activity");
+      if(data.recentRuns().isEmpty() && data.restores().isEmpty() && data.verifications().isEmpty())
+      {
+         empty(html, "Nothing has run yet.");
+      }
+      else
+      {
+         html.append("<ul style=\"").append(ITEMS).append("\">");
+         data.recentRuns().stream().limit(6).forEach(run ->
+         {
+            Instant start = run.getValueInstant("startDate");
+            html.append("<li>Backup <a href=\"").append(esc(prefix + "/" + BackupsTables.RUN + "/" + run.getValue("id"))).append("\">").append(esc(run.getValueString("runKey")))
+               .append("</a>: ").append(esc(label(run.getValueString("status")))).append(start == null ? "" : ", " + WHEN.format(start)).append("</li>");
+         });
+         data.restores().stream().limit(2).forEach(restore -> html.append("<li>Restore <a href=\"").append(esc(prefix + "/" + BackupsTables.RESTORE_RUN + "/" + restore.getValue("id")))
+            .append("\">#").append(esc(String.valueOf(restore.getValue("id")))).append("</a>: ").append(esc(label(restore.getValueString("status")))).append("</li>"));
+         data.verifications().stream().limit(2).forEach(v -> html.append("<li>Verify <a href=\"").append(esc(prefix + "/" + BackupsTables.VERIFICATION + "/" + v.getValue("id")))
+            .append("\">").append(esc(label(v.getValueString("level")))).append("</a>: ").append(esc(label(v.getValueString("status")))).append("</li>"));
+         html.append("</ul>");
+      }
+      link(html, prefix, BackupsTables.RUN, "All runs");
+      close(html);
+   }
+
+
+
+   /*******************************************************************************
+    ** Retention: runs kept per class and the oldest restorable point.
+    *******************************************************************************/
+   private static void retention(StringBuilder html, BackupsHomeData data)
+   {
+      open(html, "Retention");
+      boolean any = false;
+      for(QRecord plan : data.plans())
+      {
+         Map<String, Integer> counts = data.retentionCounts(plan.getValueInteger("id"));
+         if(counts.isEmpty())
+         {
+            continue;
+         }
+         any = true;
+         html.append("<dl style=\"").append(LIST).append("\">");
+         row(html, "Plan", plan.getValueString("name"));
+         row(html, "Kept", counts.entrySet().stream().map(e -> e.getValue() + " " + label(e.getKey()).toLowerCase()).reduce((a, b) -> a + ", " + b).orElse(""));
+         List<QRecord> runs = data.successfulRuns(plan.getValueInteger("id"));
+         Instant oldest = runs.isEmpty() ? null : runs.get(0).getValueInstant("startDate");
+         row(html, "Oldest restorable", oldest == null ? "Not known" : WHEN.format(oldest));
+         html.append("</dl>");
+      }
+      if(!any)
+      {
+         empty(html, "Retention starts once runs exist.");
+      }
+      close(html);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static void open(StringBuilder html, String title)
+   {
+      html.append("<section style=\"").append(CARD).append("\"><h3 style=\"margin:0 0 .75rem;font-size:1rem;\">").append(esc(title)).append("</h3>");
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static void close(StringBuilder html)
+   {
+      html.append("</section>");
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static void empty(StringBuilder html, String text)
+   {
+      html.append("<p style=\"").append(MUTED).append("margin:0 0 .75rem;\">").append(esc(text)).append("</p>");
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static void row(StringBuilder html, String name, String value)
+   {
+      html.append("<dt style=\"").append(MUTED).append("\">").append(esc(name)).append("</dt><dd style=\"margin:0;\">").append(esc(value == null ? "" : value)).append("</dd>");
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static void link(StringBuilder html, String prefix, String table, String text)
+   {
+      html.append("<a href=\"").append(esc(prefix + "/" + table)).append("\">").append(esc(text)).append("</a>");
+   }
+
+
+
+   /*******************************************************************************
+    ** SOME_STATUS to Some status.
+    *******************************************************************************/
+   static String label(String status)
+   {
+      if(status == null || status.isEmpty())
+      {
+         return ("Unknown");
+      }
+      String s = status.replace('_', ' ').toLowerCase();
+      return (Character.toUpperCase(s.charAt(0)) + s.substring(1));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   static String bytes(Long value)
+   {
+      if(value == null)
+      {
+         return ("Not recorded");
+      }
+      double v = value;
+      String[] units = { "B", "KB", "MB", "GB", "TB" };
+      int      i     = 0;
+      while(v >= 1024 && i < units.length - 1)
+      {
+         v /= 1024;
+         i++;
+      }
+      return (i == 0 ? String.format("%d B", value) : String.format("%.1f %s", v, units[i]));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   static String number(Long value)
+   {
+      return (value == null ? "Not recorded" : String.format("%,d", value));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   static String esc(String s)
+   {
+      return (s == null ? "" : s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;").replace("\"", "&quot;"));
+   }
+}

src/main/java/com/kingsrook/qbits/backups/codec/ArtifactTransform.java

@@ -0,0 +1,86 @@
+/*
+ * 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.codec;
+
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+
+
+/*******************************************************************************
+ ** A reversible transform applied to the bytes of an artifact after compression,
+ ** before they reach storage.  The only implementation is client-side encryption
+ ** (the streaming cipher of the QQQ crypto package); IDENTITY is the default.
+ *******************************************************************************/
+public interface ArtifactTransform
+{
+   /** No transform. */
+   ArtifactTransform IDENTITY = new ArtifactTransform()
+   {
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public OutputStream wrap(OutputStream out)
+      {
+         return (out);
+      }
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public InputStream unwrap(InputStream in)
+      {
+         return (in);
+      }
+   };
+
+
+
+   /***************************************************************************
+    ** Wrap the stream going to storage.
+    ***************************************************************************/
+   OutputStream wrap(OutputStream out) throws IOException;
+
+
+   /***************************************************************************
+    ** Wrap a stream read from storage, to undo the transform.
+    ***************************************************************************/
+   InputStream unwrap(InputStream in) throws IOException;
+
+
+   /***************************************************************************
+    ** Whether this transform encrypts.
+    ***************************************************************************/
+   default boolean encrypts()
+   {
+      return (false);
+   }
+
+
+   /***************************************************************************
+    ** File name suffix added to artifact keys, e.g. ".tink".
+    ***************************************************************************/
+   default String keySuffix()
+   {
+      return ("");
+   }
+}

src/main/java/com/kingsrook/qbits/backups/codec/CsvRowCodec.java

@@ -0,0 +1,277 @@
+/*
+ * 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.codec;
+
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.TreeSet;
+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.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** The CSV row format (spec 8.3): RFC 4180, UTF-8 without a BOM, a header of
+ ** field names, and the same canonical value text as JSONL.  Null is written as
+ ** \N (unquoted) so it can be told from the empty string; a string that is
+ ** literally \N is quoted.  A multi-line value is one record in a quoted field,
+ ** so the codec works on records (a record may span lines): encode() returns a
+ ** text that may contain embedded newlines, and the part writer appends one
+ ** newline after each.
+ *******************************************************************************/
+public class CsvRowCodec implements RowCodec
+{
+   public static final String NULL_TOKEN = "\\N";
+
+   private final QTableMetaData table;
+   private final List<String>   fieldNames;
+
+
+
+   /*******************************************************************************
+    ** Constructor.
+    *******************************************************************************/
+   public CsvRowCodec(QTableMetaData table, java.util.Collection<String> excludedFields)
+   {
+      this.table = table;
+      TreeSet<String> names = new TreeSet<>(table.getFields().keySet());
+      if(excludedFields != null)
+      {
+         names.removeAll(excludedFields);
+      }
+      this.fieldNames = new ArrayList<>(names);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public List<String> getFieldNames()
+   {
+      return (fieldNames);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public String header()
+   {
+      return (String.join(",", fieldNames.stream().map(CsvRowCodec::quoteIfNeeded).toList()));
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public String encode(QRecord record)
+   {
+      StringBuilder sb = new StringBuilder();
+      for(int i = 0; i < fieldNames.size(); i++)
+      {
+         if(i > 0)
+         {
+            sb.append(',');
+         }
+         String       name  = fieldNames.get(i);
+         Serializable value = record.getValue(name);
+         if(value == null)
+         {
+            sb.append(NULL_TOKEN);
+         }
+         else
+         {
+            String text = FieldValueCodec.toCanonicalText(table.getField(name).getType(), value);
+            sb.append(NULL_TOKEN.equals(text) ? "\"" + text + "\"" : quoteIfNeeded(text));
+         }
+      }
+      return (sb.toString());
+   }
+
+
+
+   /*******************************************************************************
+    ** Parse one CSV record (as returned by CsvRecordReader, header excluded) to a record.
+    ** The line may contain embedded newlines inside quoted fields.
+    *******************************************************************************/
+   @Override
+   public QRecord decode(String line) throws QException
+   {
+      List<String> cells = splitCells(line);
+      return (toRecord(cells, fieldNames));
+   }
+
+
+
+   /*******************************************************************************
+    ** Build a record from already-split cells and the header names.
+    *******************************************************************************/
+   public QRecord toRecord(List<String> cells, List<String> header) throws QException
+   {
+      if(cells.size() != header.size())
+      {
+         throw (new QException("CSV row has " + cells.size() + " cells but the header has " + header.size() + " for table " + table.getName()));
+      }
+      Map<String, Serializable> values = new LinkedHashMap<>();
+      for(int i = 0; i < header.size(); i++)
+      {
+         String         cell  = cells.get(i);
+         QFieldMetaData field = table.getFields().get(header.get(i));
+         if(cell == null)
+         {
+            values.put(header.get(i), null);
+         }
+         else if(field == null)
+         {
+            values.put(header.get(i), cell);
+         }
+         else
+         {
+            values.put(header.get(i), FieldValueCodec.fromCanonicalText(field.getType(), cell));
+         }
+      }
+      QRecord record = new QRecord();
+      record.setTableName(table.getName());
+      record.setValues(values);
+      return (record);
+   }
+
+
+
+   /*******************************************************************************
+    ** Quote a cell when it contains a comma, quote, CR or LF (or is empty after
+    ** being a header, which never happens), doubling embedded quotes.
+    *******************************************************************************/
+   static String quoteIfNeeded(String s)
+   {
+      if(s.indexOf(',') >= 0 || s.indexOf('"') >= 0 || s.indexOf('\n') >= 0 || s.indexOf('\r') >= 0)
+      {
+         return ("\"" + s.replace("\"", "\"\"") + "\"");
+      }
+      return (s);
+   }
+
+
+
+   /*******************************************************************************
+    ** Split one CSV record into cells.  Returns null for an unquoted \N cell (a null).
+    *******************************************************************************/
+   public static List<String> splitCells(String line)
+   {
+      List<String>  cells  = new ArrayList<>();
+      StringBuilder cell   = new StringBuilder();
+      boolean       quoted = false;
+      boolean       wasQuoted = false;
+      for(int i = 0; i < line.length(); i++)
+      {
+         char c = line.charAt(i);
+         if(quoted)
+         {
+            if(c == '"')
+            {
+               if(i + 1 < line.length() && line.charAt(i + 1) == '"')
+               {
+                  cell.append('"');
+                  i++;
+               }
+               else
+               {
+                  quoted = false;
+               }
+            }
+            else
+            {
+               cell.append(c);
+            }
+         }
+         else if(c == '"')
+         {
+            quoted = true;
+            wasQuoted = true;
+         }
+         else if(c == ',')
+         {
+            cells.add(finishCell(cell, wasQuoted));
+            cell = new StringBuilder();
+            wasQuoted = false;
+         }
+         else
+         {
+            cell.append(c);
+         }
+      }
+      cells.add(finishCell(cell, wasQuoted));
+      return (cells);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static String finishCell(StringBuilder cell, boolean wasQuoted)
+   {
+      String s = cell.toString();
+      return (!wasQuoted && NULL_TOKEN.equals(s) ? null : s);
+   }
+
+
+
+   /*******************************************************************************
+    ** Split a whole CSV text into records, honoring newlines inside quoted fields.
+    *******************************************************************************/
+   public static List<String> splitRecords(String text)
+   {
+      List<String>  records = new ArrayList<>();
+      StringBuilder current = new StringBuilder();
+      boolean       quoted  = false;
+      for(int i = 0; i < text.length(); i++)
+      {
+         char c = text.charAt(i);
+         if(c == '"')
+         {
+            quoted = !quoted;
+            current.append(c);
+         }
+         else if(c == '\n' && !quoted)
+         {
+            records.add(current.toString());
+            current = new StringBuilder();
+         }
+         else
+         {
+            current.append(c);
+         }
+      }
+      if(current.length() > 0)
+      {
+         records.add(current.toString());
+      }
+      return (records);
+   }
+}

src/main/java/com/kingsrook/qbits/backups/codec/FieldValueCodec.java

@@ -0,0 +1,172 @@
+/*
+ * 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.codec;
+
+
+import java.io.Serializable;
+import java.math.BigDecimal;
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.LocalTime;
+import java.time.ZoneOffset;
+import java.time.format.DateTimeFormatter;
+import java.util.Base64;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.utils.ValueUtils;
+
+
+/*******************************************************************************
+ ** The canonical, lossless text encoding of a field value, by QFieldType
+ ** (spec 8.2).  The same canonical text is used by JSONL and CSV, so a value
+ ** means the same thing in both, and by the content hash.
+ **
+ **  STRING, TEXT, HTML, PASSWORD: string
+ **  INTEGER, LONG: number
+ **  DECIMAL: string (BigDecimal.toPlainString), so there is no float rounding
+ **  BOOLEAN: true or false
+ **  DATE: yyyy-MM-dd
+ **  TIME: HH:mm:ss, with .SSSSSS only when there are fractional seconds
+ **  DATE_TIME: an ISO-8601 instant in UTC, with .SSSSSS only when there are fractional seconds
+ **  BLOB: base64
+ *******************************************************************************/
+public final class FieldValueCodec
+{
+   private static final DateTimeFormatter TIME_FORMAT          = DateTimeFormatter.ofPattern("HH:mm:ss");
+   private static final DateTimeFormatter TIME_FORMAT_MICROS   = DateTimeFormatter.ofPattern("HH:mm:ss.SSSSSS");
+   private static final DateTimeFormatter INSTANT_FORMAT       = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss'Z'").withZone(ZoneOffset.UTC);
+   private static final DateTimeFormatter INSTANT_FORMAT_MICRO = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'").withZone(ZoneOffset.UTC);
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private FieldValueCodec()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Whether the canonical JSON form of a type is a bare number or boolean (not quoted).
+    *******************************************************************************/
+   public static boolean isBareJson(QFieldType type)
+   {
+      return (type == QFieldType.INTEGER || type == QFieldType.LONG || type == QFieldType.BOOLEAN);
+   }
+
+
+
+   /*******************************************************************************
+    ** The canonical text of a non-null value.
+    *******************************************************************************/
+   public static String toCanonicalText(QFieldType type, Serializable value)
+   {
+      switch(type)
+      {
+         case INTEGER, LONG:
+            return (String.valueOf(ValueUtils.getValueAsLong(value)));
+         case DECIMAL:
+            return (ValueUtils.getValueAsBigDecimal(value).toPlainString());
+         case BOOLEAN:
+            return (String.valueOf(ValueUtils.getValueAsBoolean(value)));
+         case DATE:
+            return (ValueUtils.getValueAsLocalDate(value).toString());
+         case TIME:
+         {
+            LocalTime time = ValueUtils.getValueAsLocalTime(value);
+            return (time.getNano() == 0 ? TIME_FORMAT.format(time) : TIME_FORMAT_MICROS.format(time));
+         }
+         case DATE_TIME:
+         {
+            Instant instant = ValueUtils.getValueAsInstant(value);
+            return (instant.getNano() == 0 ? INSTANT_FORMAT.format(instant) : INSTANT_FORMAT_MICRO.format(instant));
+         }
+         case BLOB:
+            return (Base64.getEncoder().encodeToString(blobBytes(value)));
+         default:
+            return (String.valueOf(value));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static byte[] blobBytes(Serializable value)
+   {
+      if(value instanceof byte[] bytes)
+      {
+         return (bytes);
+      }
+      return (String.valueOf(value).getBytes(java.nio.charset.StandardCharsets.UTF_8));
+   }
+
+
+
+   /*******************************************************************************
+    ** Parse canonical text back to a Java value.
+    *******************************************************************************/
+   public static Serializable fromCanonicalText(QFieldType type, String text)
+   {
+      if(text == null)
+      {
+         return (null);
+      }
+      switch(type)
+      {
+         case INTEGER:
+            return (Integer.valueOf(text));
+         case LONG:
+            return (Long.valueOf(text));
+         case DECIMAL:
+            return (new BigDecimal(text));
+         case BOOLEAN:
+            return (Boolean.valueOf(text));
+         case DATE:
+            return (LocalDate.parse(text));
+         case TIME:
+            return (LocalTime.parse(text));
+         case DATE_TIME:
+            return (Instant.parse(text));
+         case BLOB:
+            return (Base64.getDecoder().decode(text));
+         default:
+            return (text);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Convert a parsed JSON value to a Java value.
+    *******************************************************************************/
+   public static Serializable fromJson(QFieldType type, JsonNode node)
+   {
+      if(node == null || node.isNull())
+      {
+         return (null);
+      }
+      if(type == QFieldType.BOOLEAN)
+      {
+         return (node.asBoolean());
+      }
+      return (fromCanonicalText(type, node.isNumber() ? node.asText() : node.textValue()));
+   }
+}

src/main/java/com/kingsrook/qbits/backups/codec/HashingOutputStream.java

@@ -0,0 +1,147 @@
+/*
+ * 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.codec;
+
+
+import java.io.FilterOutputStream;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.util.HexFormat;
+
+
+/*******************************************************************************
+ ** An output stream that counts and SHA-256 hashes the bytes passing through.
+ ** Closing it closes the stream underneath.  The hash is available after close()
+ ** (or any time, as the hash of the bytes so far).
+ *******************************************************************************/
+public class HashingOutputStream extends FilterOutputStream
+{
+   private final MessageDigest digest;
+   private long                count = 0;
+   private String              hex;
+
+
+
+   /*******************************************************************************
+    ** Constructor.
+    *******************************************************************************/
+   public HashingOutputStream(OutputStream out)
+   {
+      super(out);
+      this.digest = newSha256();
+   }
+
+
+
+   /*******************************************************************************
+    ** A new SHA-256 digest.
+    *******************************************************************************/
+   public static MessageDigest newSha256()
+   {
+      try
+      {
+         return (MessageDigest.getInstance("SHA-256"));
+      }
+      catch(NoSuchAlgorithmException e)
+      {
+         throw (new IllegalStateException("SHA-256 is not available", e));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Hex of a digest result.
+    *******************************************************************************/
+   public static String hex(byte[] bytes)
+   {
+      return (HexFormat.of().formatHex(bytes));
+   }
+
+
+
+   /*******************************************************************************
+    ** SHA-256 of a byte array, as hex.
+    *******************************************************************************/
+   public static String sha256Hex(byte[] bytes)
+   {
+      return (hex(newSha256().digest(bytes)));
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public void write(int b) throws IOException
+   {
+      out.write(b);
+      digest.update((byte) b);
+      count++;
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public void write(byte[] b, int off, int len) throws IOException
+   {
+      out.write(b, off, len);
+      digest.update(b, off, len);
+      count += len;
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public void close() throws IOException
+   {
+      super.close();
+      if(hex == null)
+      {
+         hex = hex(digest.digest());
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The SHA-256 (hex) of everything written; valid after close().
+    *******************************************************************************/
+   public String getSha256()
+   {
+      return (hex);
+   }
+
+
+
+   /*******************************************************************************
+    ** The number of bytes written.
+    *******************************************************************************/
+   public long getCount()
+   {
+      return (count);
+   }
+}

src/main/java/com/kingsrook/qbits/backups/codec/JsonlRowCodec.java

@@ -0,0 +1,200 @@
+/*
+ * 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.codec;
+
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.TreeSet;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+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.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** The JSON Lines row format (spec 8.2): one JSON object per line, keys are field
+ ** names (sorted), values are the raw canonical encodings, never display values.
+ ** The text of a line is canonical, so the same rows always give the same bytes
+ ** (which is what the rowsHash is computed over).
+ *******************************************************************************/
+public class JsonlRowCodec implements RowCodec
+{
+   private static final ObjectMapper MAPPER = new ObjectMapper();
+
+   private final QTableMetaData   table;
+   private final List<String>     fieldNames;
+
+
+
+   /*******************************************************************************
+    ** Constructor.  The fields are the table fields, minus any excluded, sorted by name.
+    *******************************************************************************/
+   public JsonlRowCodec(QTableMetaData table, java.util.Collection<String> excludedFields)
+   {
+      this.table = table;
+      TreeSet<String> names = new TreeSet<>(table.getFields().keySet());
+      if(excludedFields != null)
+      {
+         names.removeAll(excludedFields);
+      }
+      this.fieldNames = new ArrayList<>(names);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public List<String> getFieldNames()
+   {
+      return (fieldNames);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public String header()
+   {
+      return (null);
+   }
+
+
+
+   /*******************************************************************************
+    ** The canonical line (no trailing newline) for a record.
+    *******************************************************************************/
+   @Override
+   public String encode(QRecord record)
+   {
+      StringBuilder sb    = new StringBuilder("{");
+      boolean       first = true;
+      for(String name : fieldNames)
+      {
+         QFieldType type  = table.getField(name).getType();
+         Serializable value = record.getValue(name);
+         if(!first)
+         {
+            sb.append(',');
+         }
+         first = false;
+         appendString(sb, name);
+         sb.append(':');
+         if(value == null)
+         {
+            sb.append("null");
+         }
+         else
+         {
+            String text = FieldValueCodec.toCanonicalText(type, value);
+            if(FieldValueCodec.isBareJson(type))
+            {
+               sb.append(text);
+            }
+            else
+            {
+               appendString(sb, text);
+            }
+         }
+      }
+      return (sb.append('}').toString());
+   }
+
+
+
+   /*******************************************************************************
+    ** Parse one line into a record.  Unknown keys are kept as strings so that
+    ** restore can report them as unmapped.
+    *******************************************************************************/
+   @Override
+   public QRecord decode(String line) throws QException
+   {
+      try
+      {
+         JsonNode              node   = MAPPER.readTree(line);
+         Map<String, Serializable> values = new LinkedHashMap<>();
+         for(var it = node.fields(); it.hasNext(); )
+         {
+            var            entry = it.next();
+            QFieldMetaData field = table.getFields().get(entry.getKey());
+            if(field == null)
+            {
+               values.put(entry.getKey(), entry.getValue().isNull() ? null : entry.getValue().asText());
+            }
+            else
+            {
+               values.put(entry.getKey(), FieldValueCodec.fromJson(field.getType(), entry.getValue()));
+            }
+         }
+         QRecord record = new QRecord();
+         record.setTableName(table.getName());
+         record.setValues(values);
+         return (record);
+      }
+      catch(Exception e)
+      {
+         throw (new QException("Could not read a backup row for table " + table.getName() + ": " + e.getMessage()));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Append a JSON string with escapes.  Control characters, quotes and backslashes
+    ** are escaped; everything else (including non-ASCII) is written as is, in UTF-8.
+    *******************************************************************************/
+   static void appendString(StringBuilder sb, String s)
+   {
+      sb.append('"');
+      for(int i = 0; i < s.length(); i++)
+      {
+         char c = s.charAt(i);
+         switch(c)
+         {
+            case '"' -> sb.append("\\\"");
+            case '\\' -> sb.append("\\\\");
+            case '\n' -> sb.append("\\n");
+            case '\r' -> sb.append("\\r");
+            case '\t' -> sb.append("\\t");
+            case '\b' -> sb.append("\\b");
+            case '\f' -> sb.append("\\f");
+            default ->
+            {
+               if(c < 0x20)
+               {
+                  sb.append(String.format("\\u%04x", (int) c));
+               }
+               else
+               {
+                  sb.append(c);
+               }
+            }
+         }
+      }
+      sb.append('"');
+   }
+}

src/main/java/com/kingsrook/qbits/backups/codec/RowCodec.java

@@ -0,0 +1,53 @@
+/*
+ * 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.codec;
+
+
+import java.util.List;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Encodes a record to one line of text, and decodes it back.
+ *******************************************************************************/
+public interface RowCodec
+{
+
+   /***************************************************************************
+    ** The field names written, in order.
+    ***************************************************************************/
+   List<String> getFieldNames();
+
+
+   /***************************************************************************
+    ** A header line to write at the start of each part, or null.
+    ***************************************************************************/
+   String header();
+
+
+   /***************************************************************************
+    ** One line, without the trailing newline.
+    ***************************************************************************/
+   String encode(QRecord record);
+
+
+   /***************************************************************************
+    ** Read one line back into a record.
+    ***************************************************************************/
+   QRecord decode(String line) throws QException;
+}

src/main/java/com/kingsrook/qbits/backups/codec/TableArtifactWriter.java

@@ -0,0 +1,274 @@
+/*
+ * 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.codec;
+
+
+import java.io.Closeable;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+import java.util.zip.GZIPOutputStream;
+import com.kingsrook.qbits.backups.storage.BackupStorage;
+import com.kingsrook.qbits.backups.storage.WriteOptions;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** Streams the rows of one table into numbered parts in storage.  Each row goes
+ ** through the row codec, then (per part) into a hash of the raw bytes, gzip,
+ ** the artifact transform (encryption) and a hash of the stored bytes, and out
+ ** through BackupStorage.openWrite.  Memory is O(row); nothing touches a temp disk.
+ **
+ ** Whatever the output format, a canonical JSONL hash of every row (in the order
+ ** written, which is primary key order) is kept: that is the rowsHash a verifier
+ ** recomputes (spec 8.2), independent of compression, encryption and part sizes.
+ *******************************************************************************/
+public class TableArtifactWriter implements Closeable
+{
+   private final BackupStorage     storage;
+   private final String            keyPrefix;
+   private final QTableMetaData    table;
+   private final RowCodec          codec;
+   private final JsonlRowCodec     canonical;
+   private final boolean           csv;
+   private final boolean           gzip;
+   private final long              targetPartBytes;
+   private final long              maxRowsPerPart;
+   private final ArtifactTransform transform;
+   private final String            runKey;
+
+   private final MessageDigest rowsDigest = HashingOutputStream.newSha256();
+   private final List<PartResult> parts   = new ArrayList<>();
+
+   private int                 partNumber = 0;
+   private PartState           current;
+   private long                totalRows  = 0;
+   private String              firstKeyOfTable;
+   private String              lastKeyOfTable;
+
+
+
+   /***************************************************************************
+    ** The outcome of one written part.
+    ***************************************************************************/
+   public record PartResult(int partNumber, String key, long rows, long bytesRaw, long bytesStored, String sha256Raw, String sha256Stored,
+                            String firstKey, String lastKey, boolean encrypted, String format, String compression)
+   {
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   private static class PartState
+   {
+      String               key;
+      HashingOutputStream  raw;
+      HashingOutputStream  stored;
+      long                 rows;
+      String               firstKey;
+      String               lastKey;
+   }
+
+
+
+   /*******************************************************************************
+    ** Constructor.
+    **
+    ** @param keyPrefix the key prefix of the table directory, ending in a slash
+    ** @param format JSONL or CSV
+    ** @param compression GZIP or NONE
+    *******************************************************************************/
+   public TableArtifactWriter(BackupStorage storage, String keyPrefix, QTableMetaData table, Collection<String> excludedFields, String format,
+                              String compression, long targetPartBytes, long maxRowsPerPart, ArtifactTransform transform, String runKey)
+   {
+      this.storage = storage;
+      this.keyPrefix = keyPrefix;
+      this.table = table;
+      this.csv = "CSV".equals(format);
+      this.canonical = new JsonlRowCodec(table, excludedFields);
+      this.codec = csv ? new CsvRowCodec(table, excludedFields) : canonical;
+      this.gzip = "GZIP".equals(compression);
+      this.targetPartBytes = targetPartBytes;
+      this.maxRowsPerPart = maxRowsPerPart;
+      this.transform = transform == null ? ArtifactTransform.IDENTITY : transform;
+      this.runKey = runKey;
+
+      if(!gzip && !"NONE".equals(compression))
+      {
+         throw (new IllegalArgumentException("Unsupported compression: " + compression));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Write one record.
+    *******************************************************************************/
+   public void write(QRecord record) throws IOException
+   {
+      if(current == null)
+      {
+         openPart();
+      }
+
+      String       pk   = String.valueOf(record.getValue(table.getPrimaryKeyField()));
+      byte[]       line = (codec.encode(record) + "\n").getBytes(StandardCharsets.UTF_8);
+      current.raw.write(line);
+      if(current.firstKey == null)
+      {
+         current.firstKey = pk;
+      }
+      current.lastKey = pk;
+      current.rows++;
+      totalRows++;
+      if(firstKeyOfTable == null)
+      {
+         firstKeyOfTable = pk;
+      }
+      lastKeyOfTable = pk;
+
+      rowsDigest.update((canonical.encode(record) + "\n").getBytes(StandardCharsets.UTF_8));
+
+      if(current.raw.getCount() >= targetPartBytes || current.rows >= maxRowsPerPart)
+      {
+         closePart();
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Finish: close the last part (writing an empty part if there were no rows at all).
+    *******************************************************************************/
+   public List<PartResult> finish() throws IOException
+   {
+      if(current == null && parts.isEmpty())
+      {
+         openPart();
+      }
+      if(current != null)
+      {
+         closePart();
+      }
+      return (parts);
+   }
+
+
+
+   /*******************************************************************************
+    ** The canonical content hash of all rows written, as sha256:hex.  Valid after finish().
+    *******************************************************************************/
+   public String rowsHash()
+   {
+      return ("sha256:" + HashingOutputStream.hex(rowsDigest.digest()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Total rows written.
+    *******************************************************************************/
+   public long getTotalRows()
+   {
+      return (totalRows);
+   }
+
+
+
+   /*******************************************************************************
+    ** First primary key written.
+    *******************************************************************************/
+   public String getFirstKey()
+   {
+      return (firstKeyOfTable);
+   }
+
+
+
+   /*******************************************************************************
+    ** Last primary key written.
+    *******************************************************************************/
+   public String getLastKey()
+   {
+      return (lastKeyOfTable);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public void close() throws IOException
+   {
+      if(current != null)
+      {
+         // an abandoned part is never committed to storage
+         current.raw.close();
+         current = null;
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void openPart() throws IOException
+   {
+      partNumber++;
+      current = new PartState();
+      String extension = csv ? "csv" : "jsonl";
+      current.key = keyPrefix + String.format("part-%05d.%s%s%s", partNumber, extension, gzip ? ".gz" : "", transform.keySuffix());
+
+      WriteOptions options = WriteOptions.create().withContentType("application/octet-stream")
+         .withMetadata("qqq-backup-run", runKey)
+         .withMetadata("qqq-backup-table", table.getName());
+      OutputStream toStorage = storage.openWrite(current.key, options);
+      current.stored = new HashingOutputStream(toStorage);
+      OutputStream transformed = transform.wrap(current.stored);
+      OutputStream compressed  = gzip ? new GZIPOutputStream(transformed) : transformed;
+      current.raw = new HashingOutputStream(compressed);
+
+      String header = codec.header();
+      if(header != null)
+      {
+         current.raw.write((header + "\n").getBytes(StandardCharsets.UTF_8));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void closePart() throws IOException
+   {
+      current.raw.close();
+      parts.add(new PartResult(partNumber, current.key, current.rows, current.raw.getCount(), current.stored.getCount(),
+         current.raw.getSha256(), current.stored.getSha256(), current.firstKey, current.lastKey, transform.encrypts(),
+         csv ? "CSV" : "JSONL", gzip ? "GZIP" : "NONE"));
+      current = null;
+   }
+}

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/files/FileCopier.java

@@ -0,0 +1,223 @@
+/*
+ * 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.files;
+
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.util.Optional;
+import java.util.function.Function;
+import com.kingsrook.qbits.backups.codec.ArtifactTransform;
+import com.kingsrook.qbits.backups.codec.HashingOutputStream;
+import com.kingsrook.qbits.backups.storage.BackupStorage;
+import com.kingsrook.qbits.backups.storage.StoredObjectInfo;
+import com.kingsrook.qbits.backups.storage.WriteOptions;
+
+
+/*******************************************************************************
+ ** Makes sure each file that a record references is in the content-addressed
+ ** store (spec 8.5), and says what it did.
+ **
+ ** For each reference: head the source (missing is reported, never silently
+ ** skipped); find its SHA-256 (known from the reference provider, else the object
+ ** is read once and hashed); if the store already has that hash the file is
+ ** DEDUPLICATED and nothing is copied; otherwise it is copied (server-side when
+ ** the source and the destination are the same storage and the plan does not
+ ** encrypt, else streamed through the transform) and the hash observed while
+ ** copying must equal the hash the key was derived from.  If the source changed
+ ** in between, the file is hashed again and copied once more.
+ *******************************************************************************/
+public class FileCopier
+{
+   public static final String COPIED         = "COPIED";
+   public static final String DEDUPLICATED   = "DEDUPLICATED";
+   public static final String MISSING        = "MISSING";
+   public static final String REFERENCE_ONLY = "REFERENCE_ONLY";
+
+   private final Function<String, BackupStorage> sourceResolver;
+   private final String                          destinationAlias;
+   private final BackupStorage                   destination;
+   private final String                          casPrefix;
+   private final ArtifactTransform               transform;
+   private final FileStoreRegistry               registry;
+   private final boolean                         referenceOnly;
+   private final String                          runKey;
+
+
+
+   /***************************************************************************
+    ** The catalog side of the file store: which hashes are already stored.
+    ***************************************************************************/
+   public interface FileStoreRegistry
+   {
+      /***************************************************************************
+       ** Whether the store knows this hash (and the object is expected to be there).
+       ***************************************************************************/
+      boolean isKnown(String sha256);
+
+
+      /***************************************************************************
+       ** Record a newly stored file.
+       ***************************************************************************/
+      void register(String sha256, long sizeBytes, String contentType, String casKey, boolean encrypted);
+   }
+
+
+
+   /***************************************************************************
+    ** One line of the per-run file index.
+    **
+    ** @param tableName the referencing table
+    ** @param recordKey the referencing record primary key
+    ** @param field the referencing field
+    ** @param sourceBucketAlias where the file was
+    ** @param sourceKey the source key
+    ** @param sha256 content hash (null when missing or reference-only without a known hash)
+    ** @param size size in bytes (-1 when unknown)
+    ** @param status COPIED, DEDUPLICATED, MISSING or REFERENCE_ONLY
+    ** @param casKey the content-addressed key in the destination, if stored
+    ***************************************************************************/
+   public record IndexEntry(String tableName, String recordKey, String field, String sourceBucketAlias, String sourceKey,
+                            String sha256, long size, String status, String casKey)
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Constructor.
+    **
+    ** @param casPrefix prefix of the store, ending in a slash, e.g. qqq-backups/app/_files/sha256/
+    *******************************************************************************/
+   public FileCopier(Function<String, BackupStorage> sourceResolver, String destinationAlias, BackupStorage destination, String casPrefix,
+                     ArtifactTransform transform, FileStoreRegistry registry, boolean referenceOnly, String runKey)
+   {
+      this.sourceResolver = sourceResolver;
+      this.destinationAlias = destinationAlias;
+      this.destination = destination;
+      this.casPrefix = casPrefix;
+      this.transform = transform == null ? ArtifactTransform.IDENTITY : transform;
+      this.registry = registry;
+      this.referenceOnly = referenceOnly;
+      this.runKey = runKey;
+   }
+
+
+
+   /*******************************************************************************
+    ** The content-addressed key for a hash: prefix/ab/cd/sha256.
+    *******************************************************************************/
+   public static String casKey(String casPrefix, String sha256)
+   {
+      return (casPrefix + sha256.substring(0, 2) + "/" + sha256.substring(2, 4) + "/" + sha256);
+   }
+
+
+
+   /*******************************************************************************
+    ** Process one reference.
+    *******************************************************************************/
+   public IndexEntry process(FileReference ref) throws IOException
+   {
+      BackupStorage source = sourceResolver.apply(ref.bucketAlias());
+      Optional<StoredObjectInfo> head = source == null ? Optional.empty() : source.head(ref.key());
+      if(head.isEmpty())
+      {
+         return (entry(ref, null, -1, MISSING, null));
+      }
+      long size = head.get().size();
+
+      if(referenceOnly)
+      {
+         return (entry(ref, ref.knownSha256(), size, REFERENCE_ONLY, null));
+      }
+
+      String sha = ref.knownSha256() != null ? ref.knownSha256() : hashOf(source, ref.key());
+      for(int attempt = 0; attempt < 2; attempt++)
+      {
+         String key = casKey(casPrefix, sha);
+         if(registry.isKnown(sha) && destination.head(key).isPresent())
+         {
+            return (entry(ref, sha, size, DEDUPLICATED, key));
+         }
+
+         String observed = copy(source, ref, key);
+         if(observed == null || observed.equals(sha))
+         {
+            registry.register(sha, size, ref.contentType(), key, transform.encrypts());
+            return (entry(ref, sha, size, COPIED, key));
+         }
+         // the source changed while it was being copied: the object we wrote is under the wrong key
+         destination.deletePermanent(key);
+         sha = observed;
+      }
+      throw (new IOException("The file " + ref.key() + " kept changing while it was being copied"));
+   }
+
+
+
+   /*******************************************************************************
+    ** Copy the file to the store; returns the hash observed while streaming, or null
+    ** for a server-side copy (which cannot observe the bytes).
+    *******************************************************************************/
+   private String copy(BackupStorage source, FileReference ref, String key) throws IOException
+   {
+      if(source == destination && !transform.encrypts())
+      {
+         destination.copy(ref.key(), key);
+         return (null);
+      }
+
+      WriteOptions options = WriteOptions.create().withContentType(ref.contentType() == null ? "application/octet-stream" : ref.contentType())
+         .withMetadata("qqq-backup-run", runKey);
+      try(InputStream in = source.openRead(ref.key());
+          HashingOutputStream plain = new HashingOutputStream(transform.wrap(destination.openWrite(key, options))))
+      {
+         in.transferTo(plain);
+         plain.flush();
+         plain.close();
+         return (plain.getSha256());
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Read an object once, to find its SHA-256.
+    *******************************************************************************/
+   private String hashOf(BackupStorage source, String key) throws IOException
+   {
+      try(InputStream in = source.openRead(key);
+          HashingOutputStream sink = new HashingOutputStream(OutputStream.nullOutputStream()))
+      {
+         in.transferTo(sink);
+         sink.close();
+         return (sink.getSha256());
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private IndexEntry entry(FileReference ref, String sha, long size, String status, String casKey)
+   {
+      return (new IndexEntry(ref.tableName(), ref.recordKey(), ref.field(), ref.bucketAlias(), ref.key(), sha, size, status, casKey));
+   }
+}

src/main/java/com/kingsrook/qbits/backups/files/FileReference.java

@@ -0,0 +1,33 @@
+/*
+ * 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.files;
+
+
+/*******************************************************************************
+ ** A reference from a record field to a file in object storage.
+ **
+ ** @param tableName the referencing table
+ ** @param recordKey the referencing record primary key (as text)
+ ** @param field the referencing field
+ ** @param bucketAlias the storage bucket alias the file lives in
+ ** @param key the object key
+ ** @param knownSha256 the content hash when the reference provider knows it (a content-addressed key or a stored checksum), else null
+ ** @param contentType the content type when known, else null
+ *******************************************************************************/
+public record FileReference(String tableName, String recordKey, String field, String bucketAlias, String key, String knownSha256, String contentType)
+{
+}

src/main/java/com/kingsrook/qbits/backups/files/FileReferenceProvider.java

@@ -0,0 +1,72 @@
+/*
+ * 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.files;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qbits.backups.scope.BackupTableMetaData;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** Finds the files a record references.  Apps declare their file references once
+ ** (the object-storage qbit StorageReferenceProvider registrations, which an
+ ** adapter exposes here); the default provider reads the fileReferenceFields of
+ ** the table BackupTableMetaData.
+ *******************************************************************************/
+public interface FileReferenceProvider
+{
+
+   /***************************************************************************
+    ** The files this record references (empty when none).
+    ***************************************************************************/
+   List<FileReference> referencesIn(QTableMetaData table, QRecord record);
+
+
+
+   /***************************************************************************
+    ** Reads BackupTableMetaData.fileReferenceFields: each named field holds a key
+    ** in the table fileBucketAlias bucket.
+    ***************************************************************************/
+   class FromTableMetaData implements FileReferenceProvider
+   {
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public List<FileReference> referencesIn(QTableMetaData table, QRecord record)
+      {
+         BackupTableMetaData meta = BackupTableMetaData.of(table);
+         if(meta == null || meta.getFileReferenceFields().isEmpty())
+         {
+            return (List.of());
+         }
+         List<FileReference> rs = new ArrayList<>();
+         for(String field : meta.getFileReferenceFields())
+         {
+            String key = record.getValueString(field);
+            if(key != null && !key.isBlank())
+            {
+               rs.add(new FileReference(table.getName(), String.valueOf(record.getValue(table.getPrimaryKeyField())), field, meta.getFileBucketAlias(), key, null, null));
+            }
+         }
+         return (rs);
+      }
+   }
+}

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/manifest/BackupManifest.java

@@ -0,0 +1,219 @@
+/*
+ * 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.manifest;
+
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.List;
+import java.util.Map;
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
+
+
+/*******************************************************************************
+ ** The self-describing manifest of a run (spec 8.7), written LAST: it is the
+ ** commit marker.  A run without a manifest did not complete.  It holds no
+ ** secrets: only key references and fingerprints, never key material.
+ **
+ ** Unknown properties are ignored when reading, so a newer manifest is still
+ ** readable by an older qbit (and by the offline tools).
+ *******************************************************************************/
+@JsonIgnoreProperties(ignoreUnknown = true)
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public record BackupManifest(
+   int manifestVersion,
+   String runKey,
+   PlanInfo plan,
+   InstanceInfo instance,
+   String startedAt,
+   String finishedAt,
+   String requestedBy,
+   String securityScope,
+   ConsistencyInfo consistency,
+   EncryptionInfo encryption,
+   List<TableEntry> tables,
+   List<String> restoreOrder,
+   FilesInfo files,
+   List<String> warnings,
+   Totals totals)
+{
+   public static final int CURRENT_VERSION = 1;
+
+   private static final ObjectMapper MAPPER = new ObjectMapper().enable(SerializationFeature.INDENT_OUTPUT);
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @JsonIgnoreProperties(ignoreUnknown = true)
+   @JsonInclude(JsonInclude.Include.NON_NULL)
+   public record PlanInfo(String planKey, String name, Map<String, java.io.Serializable> settings)
+   {
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @JsonIgnoreProperties(ignoreUnknown = true)
+   @JsonInclude(JsonInclude.Include.NON_NULL)
+   public record InstanceInfo(String name, String appVersion, String qqqVersion, List<Map<String, String>> qbits)
+   {
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @JsonIgnoreProperties(ignoreUnknown = true)
+   @JsonInclude(JsonInclude.Include.NON_NULL)
+   public record ConsistencyInfo(String achieved, List<Map<String, String>> perBackend)
+   {
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @JsonIgnoreProperties(ignoreUnknown = true)
+   @JsonInclude(JsonInclude.Include.NON_NULL)
+   public record EncryptionInfo(String mode, String scheme, String keyRef, String keyFingerprint)
+   {
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @JsonIgnoreProperties(ignoreUnknown = true)
+   @JsonInclude(JsonInclude.Include.NON_NULL)
+   public record ExcludedField(String name, String reason)
+   {
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @JsonIgnoreProperties(ignoreUnknown = true)
+   @JsonInclude(JsonInclude.Include.NON_NULL)
+   public record Part(String key, long rows, long bytesRaw, long bytesStored, String sha256Stored, String sha256Raw, String format, String compression, boolean encrypted)
+   {
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @JsonIgnoreProperties(ignoreUnknown = true)
+   @JsonInclude(JsonInclude.Include.NON_NULL)
+   public record TableEntry(
+      String name,
+      String role,
+      String backend,
+      String primaryKey,
+      String fingerprint,
+      Map<String, Object> schema,
+      String filter,
+      List<ExcludedField> excludedFields,
+      long rowCount,
+      String rowsHash,
+      Map<String, String> keyRange,
+      List<Part> parts,
+      String consistency)
+   {
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @JsonIgnoreProperties(ignoreUnknown = true)
+   @JsonInclude(JsonInclude.Include.NON_NULL)
+   public record FilesInfo(String policy, List<String> indexKeys, long objects, long bytes, long missing)
+   {
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   @JsonIgnoreProperties(ignoreUnknown = true)
+   @JsonInclude(JsonInclude.Include.NON_NULL)
+   public record Totals(int tables, long rows, long bytesStored)
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** The manifest as pretty JSON bytes.
+    *******************************************************************************/
+   public byte[] toJsonBytes()
+   {
+      try
+      {
+         return (MAPPER.writeValueAsBytes(this));
+      }
+      catch(IOException e)
+      {
+         throw (new IllegalStateException("Could not write the manifest", e));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Read a manifest.
+    *******************************************************************************/
+   public static BackupManifest read(InputStream in) throws IOException
+   {
+      return (MAPPER.readValue(in, BackupManifest.class));
+   }
+
+
+
+   /*******************************************************************************
+    ** Read a manifest from bytes.
+    *******************************************************************************/
+   public static BackupManifest read(byte[] bytes) throws IOException
+   {
+      return (MAPPER.readValue(bytes, BackupManifest.class));
+   }
+
+
+
+   /*******************************************************************************
+    ** The table entry with a name, or null.
+    *******************************************************************************/
+   public TableEntry table(String name)
+   {
+      return (tables == null ? null : tables.stream().filter(t -> t.name().equals(name)).findFirst().orElse(null));
+   }
+}

src/main/java/com/kingsrook/qbits/backups/manifest/TableFingerprints.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.manifest;
+
+
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.TreeMap;
+import com.kingsrook.qbits.backups.codec.HashingOutputStream;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.Association;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.UniqueKey;
+
+
+/*******************************************************************************
+ ** A stable schema descriptor and SHA-256 fingerprint of a table (spec 5.5).
+ **
+ ** This is an internal stand-in for the QQQ core TableSchemaFingerprint (core PR
+ ** feature/schema-fingerprint).  When that ships in the next 4.1.x RC, this class
+ ** delegates to it and the descriptor below is kept only for reading old manifests.
+ ** Labels, adornments and help text are excluded, so cosmetic changes do not count.
+ *******************************************************************************/
+public final class TableFingerprints
+{
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private TableFingerprints()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** The descriptor of a table (sorted fields; plain maps and lists, so it is also
+    ** what goes in the manifest schema).
+    *******************************************************************************/
+   public static Map<String, Object> descriptor(QTableMetaData table, String backendType)
+   {
+      Map<String, Object> d = new LinkedHashMap<>();
+      d.put("name", table.getName());
+      d.put("primaryKey", table.getPrimaryKeyField());
+      d.put("backendType", backendType);
+
+      Map<String, Object> fields = new TreeMap<>();
+      for(QFieldMetaData field : new TreeMap<>(table.getFields()).values())
+      {
+         Map<String, Object> f = new LinkedHashMap<>();
+         f.put("type", field.getType().name());
+         f.put("required", field.getIsRequired());
+         f.put("maxLength", field.getMaxLength());
+         f.put("pvs", field.getPossibleValueSourceName());
+         f.put("heavy", field.getIsHeavy());
+         f.put("sensitive", field.getIsSensitive());
+         fields.put(field.getName(), f);
+      }
+      d.put("fields", fields);
+
+      List<String> uniqueKeys = new ArrayList<>();
+      if(table.getUniqueKeys() != null)
+      {
+         for(UniqueKey key : table.getUniqueKeys())
+         {
+            uniqueKeys.add(String.join("+", key.getFieldNames().stream().sorted().toList()));
+         }
+      }
+      uniqueKeys.sort(String::compareTo);
+      d.put("uniqueKeys", uniqueKeys);
+
+      List<String> associations = new ArrayList<>();
+      if(table.getAssociations() != null)
+      {
+         for(Association association : table.getAssociations())
+         {
+            associations.add(association.getName() + "->" + association.getAssociatedTableName());
+         }
+      }
+      associations.sort(String::compareTo);
+      d.put("associations", associations);
+      return (d);
+   }
+
+
+
+   /*******************************************************************************
+    ** The fingerprint of a table: sha256:hex of the canonical descriptor.
+    *******************************************************************************/
+   public static String of(QTableMetaData table, String backendType)
+   {
+      return (fingerprintOf(descriptor(table, backendType)));
+   }
+
+
+
+   /*******************************************************************************
+    ** The fingerprint of a descriptor (maps sorted by key at every level, no whitespace).
+    *******************************************************************************/
+   public static String fingerprintOf(Map<String, Object> descriptor)
+   {
+      StringBuilder sb = new StringBuilder();
+      canonical(descriptor, sb);
+      return ("sha256:" + HashingOutputStream.sha256Hex(sb.toString().getBytes(StandardCharsets.UTF_8)));
+   }
+
+
+
+   /*******************************************************************************
+    ** The fingerprint of a whole instance's tables: a hash of the table fingerprints.
+    *******************************************************************************/
+   public static String combine(List<String> tableFingerprints)
+   {
+      return ("sha256:" + HashingOutputStream.sha256Hex(String.join("\n", tableFingerprints).getBytes(StandardCharsets.UTF_8)));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @SuppressWarnings("unchecked")
+   private static void canonical(Object o, StringBuilder sb)
+   {
+      if(o == null)
+      {
+         sb.append("null");
+      }
+      else if(o instanceof Map<?, ?> map)
+      {
+         sb.append('{');
+         boolean first = true;
+         for(Map.Entry<String, Object> e : new TreeMap<>((Map<String, Object>) map).entrySet())
+         {
+            if(!first)
+            {
+               sb.append(',');
+            }
+            first = false;
+            sb.append('"').append(e.getKey()).append("\":");
+            canonical(e.getValue(), sb);
+         }
+         sb.append('}');
+      }
+      else if(o instanceof List<?> list)
+      {
+         sb.append('[');
+         for(int i = 0; i < list.size(); i++)
+         {
+            if(i > 0)
+            {
+               sb.append(',');
+            }
+            canonical(list.get(i), sb);
+         }
+         sb.append(']');
+      }
+      else if(o instanceof Number || o instanceof Boolean)
+      {
+         sb.append(o);
+      }
+      else
+      {
+         sb.append('"').append(String.valueOf(o).replace("\\", "\\\\").replace("\"", "\\\"")).append('"');
+      }
+   }
+}

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

@@ -0,0 +1,573 @@
+/*
+ * 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.model;
+
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.backups.BackupsQBitConfig;
+import com.kingsrook.qbits.backups.permissions.BackupsPermissionChecker;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+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.joins.JoinOn;
+import com.kingsrook.qqq.backend.core.model.metadata.joins.JoinType;
+import com.kingsrook.qqq.backend.core.model.metadata.joins.QJoinMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
+import com.kingsrook.qqq.backend.core.model.metadata.permissions.PermissionLevel;
+import com.kingsrook.qqq.backend.core.model.metadata.permissions.QPermissionRules;
+import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValue;
+import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource;
+import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSourceType;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.UniqueKey;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.Association;
+import com.kingsrook.qqq.backend.core.utils.StringUtils;
+
+
+/*******************************************************************************
+ ** The qbit tables (design spec section 4).  All are standard visible QQQ
+ ** tables, prefixed backups_, in lowercase snake_case.  Tables written by
+ ** processes are read-only in the UI.  No table ever holds a key, password or
+ ** credential: only references such as a key name or a bucket alias.
+ *******************************************************************************/
+public final class BackupsTables
+{
+   public static final String PLAN              = "backups_plan";
+   public static final String PLAN_SCOPE        = "backups_plan_scope";
+   public static final String RUN               = "backups_run";
+   public static final String ARTIFACT          = "backups_artifact";
+   public static final String VERIFICATION      = "backups_verification";
+   public static final String RESTORE_RUN       = "backups_restore_run";
+   public static final String RESTORE_RUN_TABLE = "backups_restore_run_table";
+   public static final String FILE_OBJECT       = "backups_file_object";
+   public static final String ID_MAP            = "backups_id_map";
+
+   /** Tables that only processes write (read-only in the UI; no delete). */
+   public static final List<String> PROCESS_WRITTEN = List.of(RUN, ARTIFACT, VERIFICATION, RESTORE_RUN, RESTORE_RUN_TABLE, FILE_OBJECT, ID_MAP);
+
+   /** The tables shown in the nav (sub-tables appear as relations on their parents). */
+   public static final List<String> NAV_TABLES = List.of(PLAN, RUN, RESTORE_RUN, VERIFICATION, FILE_OBJECT);
+
+   public static final List<String> ALL = List.of(PLAN, PLAN_SCOPE, RUN, ARTIFACT, VERIFICATION, RESTORE_RUN, RESTORE_RUN_TABLE, FILE_OBJECT, ID_MAP);
+
+   public static final String PVS_PREFIX = "backups_";
+
+   private static final Map<String, List<String>> ENUMS = new LinkedHashMap<>();
+
+   static
+   {
+      ENUMS.put("scope_type", List.of("INSTANCE", "APPS", "QBITS", "TABLES"));
+      ENUMS.put("table_role", List.of("DATA", "AUDIT", "DERIVED", "EPHEMERAL", "SECRET", "BACKUPS", "EXTERNAL"));
+      ENUMS.put("scope_action", List.of("INCLUDE", "EXCLUDE"));
+      ENUMS.put("selector_type", List.of("TABLE", "APP", "QBIT", "ROLE"));
+      ENUMS.put("format", List.of("JSONL", "CSV", "JSONL_AND_CSV", "PARQUET"));
+      ENUMS.put("compression", List.of("GZIP", "ZSTD", "NONE"));
+      ENUMS.put("encryption_mode", List.of("NONE", "CLIENT_AES256_GCM"));
+      ENUMS.put("sensitive_policy", List.of("EXCLUDE", "INCLUDE_ENCRYPTED_ONLY", "INCLUDE"));
+      ENUMS.put("heavy_policy", List.of("INLINE", "SEPARATE_OBJECTS", "EXCLUDE"));
+      ENUMS.put("file_policy", List.of("COPY", "REFERENCE_ONLY"));
+      ENUMS.put("file_missing_policy", List.of("WARN", "FAIL"));
+      ENUMS.put("consistency", List.of("SNAPSHOT_REQUIRED", "SNAPSHOT_PREFERRED", "PER_TABLE"));
+      ENUMS.put("consistency_achieved", List.of("INSTANCE_SNAPSHOT", "BACKEND_SNAPSHOT", "PER_TABLE", "BEST_EFFORT"));
+      ENUMS.put("incremental_mode", List.of("FULL", "CHANGED_SINCE_LAST"));
+      ENUMS.put("native_dump", List.of("NONE", "PG_DUMP_CUSTOM"));
+      ENUMS.put("lock_mode", List.of("NONE", "GOVERNANCE", "COMPLIANCE"));
+      ENUMS.put("sla_status", List.of("OK", "LATE", "FAILING", "MISSING_IN_STORAGE", "UNVERIFIED", "ABANDONED", "OWNER_INVALID", "UNKNOWN"));
+      ENUMS.put("run_trigger", List.of("SCHEDULED", "MANUAL", "PRE_RESTORE", "RESUME", "IMPORTED"));
+      ENUMS.put("run_status", List.of("QUEUED", "RUNNING", "SUCCEEDED", "SUCCEEDED_WITH_WARNINGS", "FAILED", "TIMED_OUT", "CANCELLED", "ABANDONED"));
+      ENUMS.put("retention_class", List.of("DAILY", "WEEKLY", "MONTHLY", "YEARLY", "NONE"));
+      ENUMS.put("verification_status", List.of("UNVERIFIED", "STORAGE_OK", "CONTENT_OK", "TEST_RESTORE_OK", "FAILED"));
+      ENUMS.put("artifact_type", List.of("TABLE_DATA", "TABLE_BLOBS", "FILE_OBJECTS_INDEX", "NATIVE_DUMP", "MANIFEST", "CHECKSUMS"));
+      ENUMS.put("artifact_status", List.of("WRITING", "COMPLETE", "FAILED"));
+      ENUMS.put("verify_level", List.of("STORAGE", "CONTENT", "TEST_RESTORE"));
+      ENUMS.put("verify_result", List.of("PASSED", "PASSED_WITH_WARNINGS", "FAILED", "RUNNING", "ERROR"));
+      ENUMS.put("restore_status", List.of("PREVIEWED", "QUEUED", "RUNNING", "SUCCEEDED", "SUCCEEDED_WITH_WARNINGS", "FAILED", "CANCELLED"));
+      ENUMS.put("restore_mode", List.of("INSERT_NEW", "UPSERT", "REPLACE"));
+      ENUMS.put("id_strategy", List.of("PRESERVE", "REMAP_NEW_IDS"));
+      ENUMS.put("schema_status", List.of("MATCH", "COMPATIBLE", "MISMATCH"));
+   }
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private BackupsTables()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** The name of the possible value source for an enum key.
+    *******************************************************************************/
+   public static String pvs(String enumKey)
+   {
+      return (PVS_PREFIX + enumKey);
+   }
+
+
+
+   /*******************************************************************************
+    ** The values of an enum, by key.
+    *******************************************************************************/
+   public static List<String> enumValues(String enumKey)
+   {
+      return (ENUMS.get(enumKey));
+   }
+
+
+
+   /*******************************************************************************
+    ** Permission rules shared by every qbit table, app, widget and process.
+    *******************************************************************************/
+   public static QPermissionRules permissionRules()
+   {
+      return (new QPermissionRules()
+         .withLevel(PermissionLevel.HAS_ACCESS_PERMISSION)
+         .withPermissionBaseName(BackupsQBitConfig.PERMISSION_BASE_NAME)
+         .withCustomPermissionChecker(new QCodeReference(BackupsPermissionChecker.class)));
+   }
+
+
+
+   /*******************************************************************************
+    ** The possible-value sources: enums and table references.
+    *******************************************************************************/
+   public static List<QPossibleValueSource> possibleValueSources()
+   {
+      List<QPossibleValueSource> rs = new ArrayList<>();
+      for(Map.Entry<String, List<String>> entry : ENUMS.entrySet())
+      {
+         List<QPossibleValue<?>> values = new ArrayList<>();
+         for(String value : entry.getValue())
+         {
+            values.add(new QPossibleValue<>(value, StringUtils.allCapsToMixedCase(value)));
+         }
+         rs.add(new QPossibleValueSource().withName(pvs(entry.getKey())).withType(QPossibleValueSourceType.ENUM).withEnumValues(values));
+      }
+      rs.add(QPossibleValueSource.newForTable(PLAN));
+      rs.add(QPossibleValueSource.newForTable(RUN));
+      rs.add(QPossibleValueSource.newForTable(RESTORE_RUN));
+      return (rs);
+   }
+
+
+
+   /*******************************************************************************
+    ** The joins that back the parent-to-child associations (child lists on parents).
+    *******************************************************************************/
+   public static List<QJoinMetaData> joins()
+   {
+      return (List.of(
+         oneToMany("backupsPlanScopeJoinPlan", PLAN, PLAN_SCOPE, "backupPlanId"),
+         oneToMany("backupsArtifactJoinRun", RUN, ARTIFACT, "backupRunId"),
+         oneToMany("backupsVerificationJoinRun", RUN, VERIFICATION, "backupRunId"),
+         oneToMany("backupsRestoreRunJoinRun", RUN, RESTORE_RUN, "sourceBackupRunId"),
+         oneToMany("backupsRunJoinPlan", PLAN, RUN, "backupPlanId"),
+         oneToMany("backupsRestoreRunTableJoinRestoreRun", RESTORE_RUN, RESTORE_RUN_TABLE, "backupRestoreRunId")));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static QJoinMetaData oneToMany(String name, String parent, String child, String childField)
+   {
+      return (new QJoinMetaData().withName(name).withType(JoinType.ONE_TO_MANY).withLeftTable(parent).withRightTable(child).withJoinOn(new JoinOn("id", childField)));
+   }
+
+
+
+   /*******************************************************************************
+    ** All tables.
+    *******************************************************************************/
+   public static List<QTableMetaData> tables(BackupsQBitConfig config)
+   {
+      return (List.of(plan(config), planScope(config), run(config), artifact(config), verification(config),
+         restoreRun(config), restoreRunTable(config), fileObject(config), idMap(config)));
+   }
+
+
+
+   /*******************************************************************************
+    ** A table with the common id/createDate/modifyDate fields.
+    *******************************************************************************/
+   private static QTableMetaData base(BackupsQBitConfig config, String name, String label, String icon)
+   {
+      return (new QTableMetaData()
+         .withName(name)
+         .withLabel(label)
+         .withIcon(new QIcon(icon))
+         .withBackendName(config.getBackendName())
+         .withPrimaryKeyField("id")
+         .withPermissionRules(permissionRules())
+         .withField(new QFieldMetaData("id", QFieldType.INTEGER).withIsEditable(false))
+         .withField(new QFieldMetaData("createDate", QFieldType.DATE_TIME).withIsEditable(false))
+         .withField(new QFieldMetaData("modifyDate", QFieldType.DATE_TIME).withIsEditable(false)));
+   }
+
+
+
+   /*******************************************************************************
+    ** A read-only field.
+    *******************************************************************************/
+   private static QFieldMetaData ro(String name, QFieldType type)
+   {
+      return (new QFieldMetaData(name, type).withIsEditable(false));
+   }
+
+
+
+   /*******************************************************************************
+    ** A read-only field backed by an enum possible value source.
+    *******************************************************************************/
+   private static QFieldMetaData roEnum(String name, String enumKey)
+   {
+      return (ro(name, QFieldType.STRING).withPossibleValueSourceName(pvs(enumKey)));
+   }
+
+
+
+   /*******************************************************************************
+    ** An editable enum field with a default.
+    *******************************************************************************/
+   private static QFieldMetaData enumField(String name, String enumKey, String defaultValue)
+   {
+      QFieldMetaData field = new QFieldMetaData(name, QFieldType.STRING).withPossibleValueSourceName(pvs(enumKey));
+      if(defaultValue != null)
+      {
+         field.withDefaultValue(defaultValue);
+      }
+      return (field);
+   }
+
+
+
+   /*******************************************************************************
+    ** A read-only integer count.
+    *******************************************************************************/
+   private static QFieldMetaData roInt(String name)
+   {
+      return (ro(name, QFieldType.INTEGER));
+   }
+
+
+
+   /*******************************************************************************
+    ** A read-only long (byte counts, millis).
+    *******************************************************************************/
+   private static QFieldMetaData roLong(String name)
+   {
+      return (ro(name, QFieldType.LONG));
+   }
+
+
+
+   /*******************************************************************************
+    ** backups_plan: what, how, where, when and how long (spec 4.1).
+    *******************************************************************************/
+   static QTableMetaData plan(BackupsQBitConfig config)
+   {
+      return (base(config, PLAN, "Backup Plan", "backup")
+         .withRecordLabelFormatAndFields("%s", "name")
+         .withUniqueKey(new UniqueKey("name"))
+         .withUniqueKey(new UniqueKey("planKey"))
+         .withAssociation(new Association().withName("scopes").withAssociatedTableName(PLAN_SCOPE).withJoinName("backupsPlanScopeJoinPlan"))
+         .withField(new QFieldMetaData("name", QFieldType.STRING).withIsRequired(true).withMaxLength(100))
+         .withField(new QFieldMetaData("description", QFieldType.TEXT))
+         .withField(new QFieldMetaData("planKey", QFieldType.STRING).withIsRequired(true).withMaxLength(60))
+         .withField(new QFieldMetaData("isActive", QFieldType.BOOLEAN).withDefaultValue(true))
+         .withField(enumField("scopeType", "scope_type", "INSTANCE").withIsRequired(true))
+         .withField(new QFieldMetaData("includeRoles", QFieldType.STRING).withDefaultValue("DATA,AUDIT").withMaxLength(100))
+         .withField(new QFieldMetaData("storageBucketAlias", QFieldType.STRING).withIsRequired(true).withMaxLength(100))
+         .withField(new QFieldMetaData("pruneBucketAlias", QFieldType.STRING).withMaxLength(100))
+         .withField(new QFieldMetaData("prefix", QFieldType.STRING).withMaxLength(255))
+         .withField(new QFieldMetaData("critical", QFieldType.BOOLEAN).withDefaultValue(false))
+         .withField(enumField("format", "format", "JSONL"))
+         .withField(enumField("compression", "compression", "GZIP"))
+         .withField(enumField("encryptionMode", "encryption_mode", "NONE"))
+         .withField(new QFieldMetaData("encryptionKeyRef", QFieldType.STRING).withMaxLength(100))
+         .withField(enumField("sensitiveFieldPolicy", "sensitive_policy", "EXCLUDE"))
+         .withField(enumField("heavyFieldPolicy", "heavy_policy", "INLINE"))
+         .withField(enumField("fileObjectPolicy", "file_policy", "COPY"))
+         .withField(enumField("fileMissingPolicy", "file_missing_policy", "WARN"))
+         .withField(enumField("consistency", "consistency", "SNAPSHOT_PREFERRED"))
+         .withField(new QFieldMetaData("useReadReplica", QFieldType.BOOLEAN).withDefaultValue(false))
+         .withField(enumField("incrementalMode", "incremental_mode", "FULL"))
+         .withField(enumField("nativeDump", "native_dump", "NONE"))
+         .withField(new QFieldMetaData("cronExpression", QFieldType.STRING).withMaxLength(100))
+         .withField(new QFieldMetaData("cronTimeZoneId", QFieldType.STRING).withMaxLength(60))
+         .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))
+         .withField(new QFieldMetaData("retainWeekly", QFieldType.INTEGER).withDefaultValue(4))
+         .withField(new QFieldMetaData("retainMonthly", QFieldType.INTEGER).withDefaultValue(12))
+         .withField(new QFieldMetaData("retainYearly", QFieldType.INTEGER).withDefaultValue(0))
+         .withField(new QFieldMetaData("retainMinimum", QFieldType.INTEGER).withDefaultValue(3))
+         .withField(enumField("objectLockMode", "lock_mode", "NONE"))
+         .withField(new QFieldMetaData("objectLockDays", QFieldType.INTEGER))
+         .withField(new QFieldMetaData("maxDurationMinutes", QFieldType.INTEGER).withDefaultValue(240))
+         .withField(new QFieldMetaData("pageSize", QFieldType.INTEGER).withDefaultValue(5000))
+         .withField(new QFieldMetaData("targetPartBytes", QFieldType.LONG).withDefaultValue(268435456L))
+         .withField(new QFieldMetaData("ownerUserId", QFieldType.STRING).withMaxLength(100))
+         .withField(ro("lastRunId", QFieldType.INTEGER).withPossibleValueSourceName(RUN))
+         .withField(ro("lastSuccessRunId", QFieldType.INTEGER).withPossibleValueSourceName(RUN))
+         .withField(ro("lastSuccessDate", QFieldType.DATE_TIME))
+         .withField(ro("lastVerifiedRunId", QFieldType.INTEGER).withPossibleValueSourceName(RUN))
+         .withField(ro("lastVerifiedDate", QFieldType.DATE_TIME))
+         .withField(roEnum("slaStatus", "sla_status")));
+   }
+
+
+
+   /*******************************************************************************
+    ** backups_plan_scope: one row per inclusion or exclusion (spec 4.2).
+    *******************************************************************************/
+   static QTableMetaData planScope(BackupsQBitConfig config)
+   {
+      return (base(config, PLAN_SCOPE, "Backup Plan Scope", "filter_list")
+         .withRecordLabelFormatAndFields("%s %s %s", "action", "selectorType", "selectorValue")
+         .withField(new QFieldMetaData("backupPlanId", QFieldType.INTEGER).withIsRequired(true).withPossibleValueSourceName(PLAN))
+         .withField(enumField("action", "scope_action", "INCLUDE").withIsRequired(true))
+         .withField(enumField("selectorType", "selector_type", "TABLE").withIsRequired(true))
+         .withField(new QFieldMetaData("selectorValue", QFieldType.STRING).withIsRequired(true).withMaxLength(200))
+         .withField(new QFieldMetaData("filterJson", QFieldType.TEXT))
+         .withField(new QFieldMetaData("includeAssociatedChildren", QFieldType.BOOLEAN).withDefaultValue(true))
+         .withField(new QFieldMetaData("fieldExclusions", QFieldType.STRING).withMaxLength(1000)));
+   }
+
+
+
+   /*******************************************************************************
+    ** backups_run: one execution of a plan, or an ad-hoc export (spec 4.3).
+    *******************************************************************************/
+   static QTableMetaData run(BackupsQBitConfig config)
+   {
+      return (base(config, RUN, "Backup Run", "history")
+         .withRecordLabelFormatAndFields("%s", "runKey")
+         .withUniqueKey(new UniqueKey("runKey"))
+         .withAssociation(new Association().withName("artifacts").withAssociatedTableName(ARTIFACT).withJoinName("backupsArtifactJoinRun"))
+         .withAssociation(new Association().withName("verifications").withAssociatedTableName(VERIFICATION).withJoinName("backupsVerificationJoinRun"))
+         .withField(ro("backupPlanId", QFieldType.INTEGER).withPossibleValueSourceName(PLAN))
+         .withField(ro("runKey", QFieldType.STRING))
+         .withField(roEnum("trigger", "run_trigger"))
+         .withField(ro("requestedByUserId", QFieldType.STRING))
+         .withField(roEnum("status", "run_status"))
+         .withField(ro("startDate", QFieldType.DATE_TIME))
+         .withField(ro("endDate", QFieldType.DATE_TIME))
+         .withField(roLong("durationMs"))
+         .withField(ro("heartbeatDate", QFieldType.DATE_TIME))
+         .withField(roInt("tablesPlanned"))
+         .withField(roInt("tablesDone"))
+         .withField(roLong("rowsTotal"))
+         .withField(roLong("bytesRaw"))
+         .withField(roLong("bytesStored"))
+         .withField(roInt("filesReferenced"))
+         .withField(roInt("filesCopied"))
+         .withField(roInt("filesDeduplicated"))
+         .withField(roInt("filesMissing"))
+         .withField(roLong("fileBytesCopied"))
+         .withField(roLong("fileBytesReferenced"))
+         .withField(roEnum("consistencyAchieved", "consistency_achieved"))
+         .withField(ro("snapshotId", QFieldType.STRING))
+         .withField(ro("storageBucketAlias", QFieldType.STRING))
+         .withField(ro("runPrefix", QFieldType.STRING))
+         .withField(ro("manifestKey", QFieldType.STRING))
+         .withField(ro("manifestSha256", QFieldType.STRING))
+         .withField(ro("qqqVersion", QFieldType.STRING))
+         .withField(ro("appVersion", QFieldType.STRING))
+         .withField(ro("instanceName", QFieldType.STRING))
+         .withField(ro("schemaFingerprint", QFieldType.STRING))
+         .withField(ro("securityScope", QFieldType.STRING))
+         .withField(ro("encryptionKeyRef", QFieldType.STRING))
+         .withField(ro("encryptionKeyFingerprint", QFieldType.STRING))
+         .withField(roEnum("retentionClass", "retention_class"))
+         .withField(ro("lockedUntil", QFieldType.DATE_TIME))
+         .withField(ro("prunedDate", QFieldType.DATE_TIME))
+         .withField(ro("prunedByUserId", QFieldType.STRING))
+         .withField(roEnum("verificationStatus", "verification_status"))
+         .withField(roInt("warningCount"))
+         .withField(ro("errorMessage", QFieldType.TEXT))
+         .withField(ro("errorDetail", QFieldType.TEXT)));
+   }
+
+
+
+   /*******************************************************************************
+    ** backups_artifact: one stored object or part (spec 4.4).
+    *******************************************************************************/
+   static QTableMetaData artifact(BackupsQBitConfig config)
+   {
+      return (base(config, ARTIFACT, "Backup Artifact", "inventory_2")
+         .withRecordLabelFormatAndFields("%s", "objectKey")
+         .withField(ro("backupRunId", QFieldType.INTEGER).withPossibleValueSourceName(RUN))
+         .withField(roEnum("artifactType", "artifact_type"))
+         .withField(ro("tableName", QFieldType.STRING))
+         .withField(roInt("partNumber"))
+         .withField(ro("objectKey", QFieldType.STRING))
+         .withField(ro("format", QFieldType.STRING))
+         .withField(ro("compression", QFieldType.STRING))
+         .withField(ro("encrypted", QFieldType.BOOLEAN))
+         .withField(roLong("rowCount"))
+         .withField(roLong("bytesRaw"))
+         .withField(roLong("bytesStored"))
+         .withField(ro("sha256Stored", QFieldType.STRING))
+         .withField(ro("sha256Raw", QFieldType.STRING))
+         .withField(ro("rowsHash", QFieldType.STRING))
+         .withField(ro("firstKey", QFieldType.STRING))
+         .withField(ro("lastKey", QFieldType.STRING))
+         .withField(ro("tableFingerprint", QFieldType.STRING))
+         .withField(roEnum("status", "artifact_status"))
+         .withField(ro("storageVersionId", QFieldType.STRING)));
+   }
+
+
+
+   /*******************************************************************************
+    ** backups_verification: the result of a verify (spec 4.5).
+    *******************************************************************************/
+   static QTableMetaData verification(BackupsQBitConfig config)
+   {
+      return (base(config, VERIFICATION, "Backup Verification", "verified")
+         .withRecordLabelFormatAndFields("%s %s", "level", "status")
+         .withField(ro("backupRunId", QFieldType.INTEGER).withPossibleValueSourceName(RUN))
+         .withField(roEnum("level", "verify_level"))
+         .withField(roEnum("trigger", "run_trigger"))
+         .withField(ro("requestedByUserId", QFieldType.STRING))
+         .withField(ro("startDate", QFieldType.DATE_TIME))
+         .withField(ro("endDate", QFieldType.DATE_TIME))
+         .withField(roEnum("status", "verify_result"))
+         .withField(roInt("tablesChecked"))
+         .withField(roLong("rowsChecked"))
+         .withField(roInt("mismatches"))
+         .withField(ro("scratchTarget", QFieldType.STRING))
+         .withField(ro("detailJson", QFieldType.TEXT)));
+   }
+
+
+
+   /*******************************************************************************
+    ** backups_restore_run: one restore (spec 4.6).
+    *******************************************************************************/
+   static QTableMetaData restoreRun(BackupsQBitConfig config)
+   {
+      return (base(config, RESTORE_RUN, "Backup Restore", "restore")
+         .withRecordLabelFormatAndFields("Restore %s", "id")
+         .withAssociation(new Association().withName("tables").withAssociatedTableName(RESTORE_RUN_TABLE).withJoinName("backupsRestoreRunTableJoinRestoreRun"))
+         .withField(ro("sourceBackupRunId", QFieldType.INTEGER).withPossibleValueSourceName(RUN))
+         .withField(ro("requestedByUserId", QFieldType.STRING))
+         .withField(ro("startDate", QFieldType.DATE_TIME))
+         .withField(ro("endDate", QFieldType.DATE_TIME))
+         .withField(roEnum("status", "restore_status"))
+         .withField(roEnum("mode", "restore_mode"))
+         .withField(roEnum("idStrategy", "id_strategy"))
+         .withField(ro("matchOn", QFieldType.STRING))
+         .withField(ro("targetInstanceName", QFieldType.STRING))
+         .withField(ro("scopeSummary", QFieldType.TEXT))
+         .withField(ro("preRestoreBackupRunId", QFieldType.INTEGER).withPossibleValueSourceName(RUN))
+         .withField(roLong("rowsInserted"))
+         .withField(roLong("rowsUpdated"))
+         .withField(roLong("rowsUnchanged"))
+         .withField(roLong("rowsDeleted"))
+         .withField(roLong("rowsSkipped"))
+         .withField(roLong("rowsErrored"))
+         .withField(roInt("filesRestored"))
+         .withField(roInt("filesAlreadyPresent"))
+         .withField(roInt("filesConflicting"))
+         .withField(roInt("filesMissingFromBackup"))
+         .withField(roLong("fileBytesRestored"))
+         .withField(roInt("sequencesResynced"))
+         .withField(ro("automationsSuppressed", QFieldType.BOOLEAN))
+         .withField(ro("esbSuppressed", QFieldType.BOOLEAN))
+         .withField(ro("confirmationText", QFieldType.STRING))
+         .withField(ro("errorMessage", QFieldType.TEXT)));
+   }
+
+
+
+   /*******************************************************************************
+    ** backups_restore_run_table: per-table restore results (spec 4.7).
+    *******************************************************************************/
+   static QTableMetaData restoreRunTable(BackupsQBitConfig config)
+   {
+      return (base(config, RESTORE_RUN_TABLE, "Backup Restore Table", "table_rows")
+         .withRecordLabelFormatAndFields("%s", "tableName")
+         .withField(ro("backupRestoreRunId", QFieldType.INTEGER).withPossibleValueSourceName(RESTORE_RUN))
+         .withField(ro("tableName", QFieldType.STRING))
+         .withField(ro("targetTableName", QFieldType.STRING))
+         .withField(roLong("rowsInserted"))
+         .withField(roLong("rowsUpdated"))
+         .withField(roLong("rowsUnchanged"))
+         .withField(roLong("rowsDeleted"))
+         .withField(roLong("rowsSkipped"))
+         .withField(roLong("rowsErrored"))
+         .withField(roEnum("schemaStatus", "schema_status"))
+         .withField(ro("unmappedFields", QFieldType.STRING))
+         .withField(ro("sequenceResynced", QFieldType.BOOLEAN))
+         .withField(ro("status", QFieldType.STRING)));
+   }
+
+
+
+   /*******************************************************************************
+    ** backups_file_object: the content-addressed file store (spec 4.8).
+    *******************************************************************************/
+   static QTableMetaData fileObject(BackupsQBitConfig config)
+   {
+      return (base(config, FILE_OBJECT, "Backup File", "attach_file")
+         .withRecordLabelFormatAndFields("%s", "sha256")
+         .withUniqueKey(new UniqueKey("sha256"))
+         .withField(ro("sha256", QFieldType.STRING))
+         .withField(roLong("sizeBytes"))
+         .withField(ro("contentType", QFieldType.STRING))
+         .withField(ro("storageBucketAlias", QFieldType.STRING))
+         .withField(ro("objectKey", QFieldType.STRING))
+         .withField(ro("encrypted", QFieldType.BOOLEAN))
+         .withField(ro("encryptionKeyFingerprint", QFieldType.STRING))
+         .withField(ro("firstRunId", QFieldType.INTEGER).withPossibleValueSourceName(RUN))
+         .withField(ro("lastReferencedRunId", QFieldType.INTEGER).withPossibleValueSourceName(RUN))
+         .withField(roInt("referenceCount"))
+         .withField(ro("lastVerifiedDate", QFieldType.DATE_TIME))
+         .withField(ro("lastVerifyStatus", QFieldType.STRING))
+         .withField(ro("lockedUntil", QFieldType.DATE_TIME))
+         .withField(ro("deletedDate", QFieldType.DATE_TIME)));
+   }
+
+
+
+   /*******************************************************************************
+    ** backups_id_map: transient old-to-new ids for REMAP_NEW_IDS restores (spec 4.9).
+    *******************************************************************************/
+   static QTableMetaData idMap(BackupsQBitConfig config)
+   {
+      return (base(config, ID_MAP, "Backup ID Map", "swap_horiz")
+         .withRecordLabelFormatAndFields("%s %s", "tableName", "oldId")
+         .withField(ro("restoreRunId", QFieldType.INTEGER).withPossibleValueSourceName(RESTORE_RUN))
+         .withField(ro("tableName", QFieldType.STRING))
+         .withField(ro("oldId", QFieldType.STRING))
+         .withField(ro("newId", QFieldType.STRING)));
+   }
+}

src/main/java/com/kingsrook/qbits/backups/permissions/BackupsPermissionChecker.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.permissions;
+
+
+import java.util.Map;
+import com.kingsrook.qbits.backups.BackupsRuntime;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qqq.backend.core.actions.permissions.CustomPermissionChecker;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
+import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
+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.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.metadata.QAuthenticationType;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.permissions.MetaDataWithPermissionRules;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
+
+
+/*******************************************************************************
+ ** Permission rules for every qbit table, app, widget and process (spec 11.4):
+ ** view reads everything; plans are edited with backups.admin; the tables that
+ ** processes write are read-only in the UI; each process names its permission.
+ *******************************************************************************/
+public class BackupsPermissionChecker implements CustomPermissionChecker
+{
+   /*******************************************************************************
+    ** Check, throwing when denied.
+    *******************************************************************************/
+   @Override
+   public void checkPermissionsThrowing(AbstractActionInput actionInput, MetaDataWithPermissionRules metaData) throws QPermissionDeniedException
+   {
+      String needed = required(actionInput, metaData);
+      if(needed == null)
+      {
+         throw (new QPermissionDeniedException("This Backups table is written only by the Backups qbit."));
+      }
+      if(!has(needed))
+      {
+         throw (new QPermissionDeniedException("This needs the " + needed + " permission."));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The permission an action needs, or null when nobody may do it.
+    *******************************************************************************/
+   static String required(AbstractActionInput actionInput, MetaDataWithPermissionRules metaData)
+   {
+      boolean write = actionInput instanceof InsertInput || actionInput instanceof UpdateInput || actionInput instanceof DeleteInput;
+      if(metaData instanceof QTableMetaData table)
+      {
+         if(!write)
+         {
+            return (BackupsPermissions.VIEW);
+         }
+         return (BackupsTables.PROCESS_WRITTEN.contains(table.getName()) ? null : BackupsPermissions.ADMIN);
+      }
+      if(metaData instanceof QProcessMetaData process)
+      {
+         Map<String, String> byProcess = BackupsRuntime.processPermissions();
+         return (byProcess.getOrDefault(process.getName(), BackupsPermissions.ADMIN));
+      }
+      return (BackupsPermissions.VIEW);
+   }
+
+
+
+   /*******************************************************************************
+    ** Whether the current session holds a permission (or the instance is fully
+    ** anonymous and the config allows that, for local development).
+    *******************************************************************************/
+   public static boolean has(String permission)
+   {
+      QInstance instance = QContext.getQInstance();
+      QSession  session  = QContext.getQSession();
+      if(session != null && session.hasPermission(permission))
+      {
+         return (true);
+      }
+      return (BackupsRuntime.isOpenWhenAnonymous() && instance != null && instance.getAuthentication() != null
+         && QAuthenticationType.FULLY_ANONYMOUS.equals(instance.getAuthentication().getType()));
+   }
+}

src/main/java/com/kingsrook/qbits/backups/permissions/BackupsPermissions.java

@@ -0,0 +1,42 @@
+/*
+ * 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.permissions;
+
+
+/*******************************************************************************
+ ** Permission names (design spec section 11.4).
+ *******************************************************************************/
+public final class BackupsPermissions
+{
+   /** The app, every backups table (read-only), the home. */
+   public static final String VIEW    = "backups.view";
+   /** Run backup now, back up records, verify, cancel and resume. */
+   public static final String RUN     = "backups.run";
+   /** Restore (insert-new and upsert), download, cancel restore. */
+   public static final String RESTORE = "backups.restore";
+   /** Edit plans, prune, replace restores, import catalog, test destination. */
+   public static final String ADMIN   = "backups.admin";
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private BackupsPermissions()
+   {
+   }
+}

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

@@ -0,0 +1,264 @@
+/*
+ * 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.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.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.ScopeResolver;
+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.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 qbit processes (spec 9).  Each is a standard streamed ETL with the standard
+ ** Review and Result summary lines; none is in the nav; labels are plain.  They
+ ** appear as record actions on the table that has the records they act on.
+ *******************************************************************************/
+public final class BackupsProcesses
+{
+   public static final String RUN_PLAN = "backupRunPlan";
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private BackupsProcesses()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** All processes.
+    *******************************************************************************/
+   public static List<QProcessMetaData> processes()
+   {
+      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());
+      return (processes);
+   }
+
+
+
+   /*******************************************************************************
+    ** Record the permission a process needs.
+    *******************************************************************************/
+   public static QProcessMetaData permission(QProcessMetaData process, String permission)
+   {
+      BackupsRuntime.processPermissions().put(process.getName(), permission);
+      return (process);
+   }
+
+
+
+   /*******************************************************************************
+    ** A standard streamed ETL process with full validation (Review is the dry run).
+    *******************************************************************************/
+   public static QProcessMetaData etl(String name, String label, String table, 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_PREVIEW_MESSAGE, preview);
+      QProcessMetaData process = StreamedETLWithFrontendProcess.defineProcessMetaData(ExtractViaQueryStep.class, transform, load, values);
+      process.setName(name);
+      process.setLabel(label);
+      process.setTableName(table);
+      process.setPermissionRules(BackupsTables.permissionRules());
+      return (process);
+   }
+
+
+
+   /*******************************************************************************
+    ** A summary line with future (Review) and past (Result) wording.
+    *******************************************************************************/
+   public static ProcessSummaryLine line(Status status, String singularFuture, String pluralFuture, String singularPast, String pluralPast)
+   {
+      ProcessSummaryLine line = new ProcessSummaryLine(status, 0, null);
+      line.setSingularFutureMessage(singularFuture);
+      line.setPluralFutureMessage(pluralFuture);
+      line.setSingularPastMessage(singularPast);
+      line.setPluralPastMessage(pluralPast);
+      return (line);
+   }
+
+
+
+   /*******************************************************************************
+    ** Run backup now, review: what each selected plan will back up.
+    *******************************************************************************/
+   public static class RunPlanTransform extends AbstractTransformStep implements ProcessSummaryProviderInterface
+   {
+      private final ProcessSummaryLine plans    = line(Status.OK, "plan will run", "plans will run", "plan was run", "plans were run");
+      private final ProcessSummaryLine tables   = line(Status.INFO, "table will be backed up", "tables will be backed up", "table was backed up", "tables were backed up");
+      private final ProcessSummaryLine excluded = line(Status.INFO, "table is left out by its role or scope", "tables are left out by their role or scope",
+         "table was left out by its role or scope", "tables were left out by their role or scope");
+      private final ProcessSummaryLine inactive = line(Status.WARNING, "plan is not active (it can still be run by hand)", "plans are not active (they can still be run by hand)",
+         "plan was not active", "plans were not active");
+      private final ProcessSummaryLine invalid  = line(Status.ERROR, "plan cannot run", "plans cannot run", "plan could not run", "plans could not run");
+      private final List<String>       samples  = new ArrayList<>();
+
+
+
+      /*******************************************************************************
+       ** Resolve each plan scope without writing anything.
+       *******************************************************************************/
+      @Override
+      public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         for(QRecord plan : input.getRecords())
+         {
+            try
+            {
+               String alias = plan.getValueString("storageBucketAlias");
+               if(alias == null)
+               {
+                  throw (new QException("no storage bucket alias"));
+               }
+               BackupsRuntime.storageFor(alias);
+               ScopeResolver.ResolvedScope scope = BackupRunFactory.resolveScope(plan);
+               plans.incrementCountAndAddPrimaryKey(plan.getValue("id"));
+               tables.incrementCount(scope.tables().size());
+               excluded.incrementCount(scope.excluded().size());
+               if(!Boolean.TRUE.equals(plan.getValueBoolean("isActive")))
+               {
+                  inactive.incrementCountAndAddPrimaryKey(plan.getValue("id"));
+               }
+               for(ScopeResolver.ResolvedTable table : scope.tables().stream().limit(5).toList())
+               {
+                  samples.add(table.name());
+               }
+               output.getRecords().add(plan);
+            }
+            catch(Exception e)
+            {
+               invalid.incrementCountAndAddPrimaryKey(plan.getValue("id"));
+               invalid.setMessageSuffix(": " + e.getMessage());
+            }
+         }
+      }
+
+
+
+      /*******************************************************************************
+       ** Review lines.
+       *******************************************************************************/
+      @Override
+      public ArrayList<ProcessSummaryLineInterface> getProcessSummary(RunBackendStepOutput output, boolean isForResultScreen)
+      {
+         ArrayList<ProcessSummaryLineInterface> lines = new ArrayList<>();
+         plans.addSelfToListIfAnyCount(lines);
+         tables.addSelfToListIfAnyCount(lines);
+         excluded.addSelfToListIfAnyCount(lines);
+         inactive.addSelfToListIfAnyCount(lines);
+         invalid.addSelfToListIfAnyCount(lines);
+         return (lines);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Run backup now, execute: run the engine for each plan.
+    *******************************************************************************/
+   public static class RunPlanLoad extends AbstractLoadStep implements ProcessSummaryProviderInterface
+   {
+      private final ProcessSummaryLine succeeded = line(Status.OK, "backup will succeed", "backups succeeded", "backup succeeded", "backups succeeded");
+      private final ProcessSummaryLine warnings  = line(Status.WARNING, "backup finished with warnings", "backups finished with warnings",
+         "backup finished with warnings", "backups finished with warnings");
+      private final ProcessSummaryLine failed    = line(Status.ERROR, "backup failed", "backups failed", "backup failed", "backups failed");
+      private final ProcessSummaryLine rows      = line(Status.INFO, "row was written", "rows were written", "row was written", "rows were written");
+      private final ProcessSummaryLine files     = line(Status.INFO, "referenced file was copied or already stored", "referenced files were copied or already stored",
+         "referenced file was copied or already stored", "referenced files were copied or already stored");
+      private final List<BackupRunResult> results = new ArrayList<>();
+
+
+
+      /*******************************************************************************
+       ** Run the plans.
+       *******************************************************************************/
+      @Override
+      public void runOnePage(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+      {
+         for(QRecord plan : input.getRecords())
+         {
+            BackupRunRequest request = BackupRunFactory.forPlan(plan, "MANUAL");
+            BackupRunResult  result  = new BackupEngine().execute(request);
+            results.add(result);
+            switch(result.getStatus())
+            {
+               case "SUCCEEDED" -> succeeded.incrementCountAndAddPrimaryKey(result.getRunId());
+               case "SUCCEEDED_WITH_WARNINGS" -> warnings.incrementCountAndAddPrimaryKey(result.getRunId());
+               default ->
+               {
+                  failed.incrementCountAndAddPrimaryKey(result.getRunId());
+                  failed.setMessageSuffix(result.getErrorMessage() == null ? null : ": " + result.getErrorMessage());
+               }
+            }
+            rows.incrementCount((int) Math.min(Integer.MAX_VALUE, result.getRows()));
+            files.incrementCount(result.getFilesCopied() + result.getFilesDeduplicated());
+            output.getRecords().add(plan);
+         }
+      }
+
+
+
+      /*******************************************************************************
+       ** Result lines, with the run in the primary keys so it links to the run.
+       *******************************************************************************/
+      @Override
+      public ArrayList<ProcessSummaryLineInterface> getProcessSummary(RunBackendStepOutput output, boolean isForResultScreen)
+      {
+         ArrayList<ProcessSummaryLineInterface> lines = new ArrayList<>();
+         succeeded.addSelfToListIfAnyCount(lines);
+         warnings.addSelfToListIfAnyCount(lines);
+         failed.addSelfToListIfAnyCount(lines);
+         rows.addSelfToListIfAnyCount(lines);
+         files.addSelfToListIfAnyCount(lines);
+         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/run/BackupCatalog.java

@@ -0,0 +1,254 @@
+/*
+ * 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.run;
+
+
+import java.io.Serializable;
+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.kingsrook.qbits.backups.files.FileCopier;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+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.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;
+
+
+/*******************************************************************************
+ ** Reads and writes the qbit own tables (the catalog) through the standard QQQ
+ ** actions.  Every table is a normal, visible QQQ table; this class only wraps
+ ** the calls the processes make, under a permission bypass (the callers have
+ ** already checked backups.* permissions).
+ *******************************************************************************/
+public class BackupCatalog
+{
+
+   /*******************************************************************************
+    ** Insert one row, returning its id.
+    *******************************************************************************/
+   public Integer insert(String table, Map<String, Serializable> values) throws QException
+   {
+      QRecord record = new QRecord();
+      record.setValues(new LinkedHashMap<>(values));
+      InsertInput input = new InsertInput(table);
+      input.setRecords(List.of(record));
+      input.withPermissionBypass("backups catalog");
+      List<QRecord> rs = new InsertAction().execute(input).getRecords();
+      if(rs.get(0).getErrors() != null && !rs.get(0).getErrors().isEmpty())
+      {
+         throw (new QException("Could not write to " + table + ": " + rs.get(0).getErrors().get(0).getMessage()));
+      }
+      return (rs.get(0).getValueInteger("id"));
+   }
+
+
+
+   /*******************************************************************************
+    ** Update some fields of one row.
+    *******************************************************************************/
+   public void update(String table, Integer id, Map<String, Serializable> values) throws QException
+   {
+      Map<String, Serializable> all = new LinkedHashMap<>(values);
+      all.put("id", id);
+      QRecord record = new QRecord();
+      record.setValues(all);
+      UpdateInput input = new UpdateInput(table);
+      input.setRecords(List.of(record));
+      input.withPermissionBypass("backups catalog");
+      List<QRecord> rs = new UpdateAction().execute(input).getRecords();
+      if(rs.get(0).getErrors() != null && !rs.get(0).getErrors().isEmpty())
+      {
+         throw (new QException("Could not update " + table + " " + id + ": " + rs.get(0).getErrors().get(0).getMessage()));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** One row by id.
+    *******************************************************************************/
+   public Optional<QRecord> get(String table, Integer id) throws QException
+   {
+      return (query(table, new QQueryFilter(new QFilterCriteria("id", QCriteriaOperator.EQUALS, id))).stream().findFirst());
+   }
+
+
+
+   /*******************************************************************************
+    ** Query a table (catalog tables are small; no paging).
+    *******************************************************************************/
+   public List<QRecord> query(String table, QQueryFilter filter) throws QException
+   {
+      QueryInput input = new QueryInput(table);
+      input.setFilter(filter);
+      input.withPermissionBypass("backups catalog");
+      return (new QueryAction().execute(input).getRecords());
+   }
+
+
+
+   /*******************************************************************************
+    ** Query by one equals criterion, newest first by id.
+    *******************************************************************************/
+   public List<QRecord> where(String table, String field, Serializable value) throws QException
+   {
+      return (query(table, new QQueryFilter(new QFilterCriteria(field, QCriteriaOperator.EQUALS, value)).withOrderBy(new QFilterOrderBy("id", false))));
+   }
+
+
+
+   /*******************************************************************************
+    ** Insert one artifact row.
+    *******************************************************************************/
+   public Integer insertArtifact(Integer runId, String type, String tableName, Integer partNumber, String objectKey, String format, String compression,
+                                 boolean encrypted, long rows, long bytesRaw, long bytesStored, String sha256Stored, String sha256Raw, String rowsHash,
+                                 String firstKey, String lastKey, String tableFingerprint) throws QException
+   {
+      Map<String, Serializable> v = new LinkedHashMap<>();
+      v.put("backupRunId", runId);
+      v.put("artifactType", type);
+      v.put("tableName", tableName);
+      v.put("partNumber", partNumber);
+      v.put("objectKey", objectKey);
+      v.put("format", format);
+      v.put("compression", compression);
+      v.put("encrypted", encrypted);
+      v.put("rowCount", rows);
+      v.put("bytesRaw", bytesRaw);
+      v.put("bytesStored", bytesStored);
+      v.put("sha256Stored", sha256Stored);
+      v.put("sha256Raw", sha256Raw);
+      v.put("rowsHash", rowsHash);
+      v.put("firstKey", firstKey);
+      v.put("lastKey", lastKey);
+      v.put("tableFingerprint", tableFingerprint);
+      v.put("status", "COMPLETE");
+      return (insert(BackupsTables.ARTIFACT, v));
+   }
+
+
+
+   /*******************************************************************************
+    ** The file store registry over backups_file_object: known hashes are those with
+    ** a live (not deleted) row.
+    *******************************************************************************/
+   public FileCopier.FileStoreRegistry fileStoreRegistry(String bucketAlias, Integer runId, String keyFingerprint)
+   {
+      return (new FileCopier.FileStoreRegistry()
+      {
+         /*******************************************************************************
+          ** {@inheritDoc}
+          *******************************************************************************/
+         @Override
+         public boolean isKnown(String sha256)
+         {
+            try
+            {
+               return (existing(sha256).isPresent());
+            }
+            catch(QException e)
+            {
+               throw (new IllegalStateException("Could not look up a stored file: " + e.getMessage(), e));
+            }
+         }
+
+
+
+         /*******************************************************************************
+          ** {@inheritDoc}
+          *******************************************************************************/
+         @Override
+         public void register(String sha256, long sizeBytes, String contentType, String casKey, boolean encrypted)
+         {
+            try
+            {
+               Optional<QRecord> existing = existing(sha256);
+               if(existing.isPresent())
+               {
+                  return;
+               }
+               List<QRecord> deleted = where(BackupsTables.FILE_OBJECT, "sha256", sha256);
+               Map<String, Serializable> v = new LinkedHashMap<>();
+               v.put("sha256", sha256);
+               v.put("sizeBytes", sizeBytes);
+               v.put("contentType", contentType);
+               v.put("storageBucketAlias", bucketAlias);
+               v.put("objectKey", casKey);
+               v.put("encrypted", encrypted);
+               v.put("encryptionKeyFingerprint", keyFingerprint);
+               v.put("firstRunId", runId);
+               v.put("lastReferencedRunId", runId);
+               v.put("referenceCount", 0);
+               v.put("deletedDate", null);
+               if(deleted.isEmpty())
+               {
+                  insert(BackupsTables.FILE_OBJECT, v);
+               }
+               else
+               {
+                  update(BackupsTables.FILE_OBJECT, deleted.get(0).getValueInteger("id"), v);
+               }
+            }
+            catch(QException e)
+            {
+               throw (new IllegalStateException("Could not record a stored file: " + e.getMessage(), e));
+            }
+         }
+
+
+
+         /*******************************************************************************
+          **
+          *******************************************************************************/
+         private Optional<QRecord> existing(String sha256) throws QException
+         {
+            return (where(BackupsTables.FILE_OBJECT, "sha256", sha256).stream().filter(r -> r.getValue("deletedDate") == null).findFirst());
+         }
+      });
+   }
+
+
+
+   /*******************************************************************************
+    ** The runs that are RUNNING for a plan, with a heartbeat newer than the cutoff.
+    *******************************************************************************/
+   public List<QRecord> liveRunsForPlan(Integer planId, Instant heartbeatCutoff) throws QException
+   {
+      List<QRecord> live = new ArrayList<>();
+      for(QRecord run : where(BackupsTables.RUN, "backupPlanId", planId))
+      {
+         Instant heartbeat = run.getValueInstant("heartbeatDate");
+         if("RUNNING".equals(run.getValueString("status")) && heartbeat != null && heartbeat.isAfter(heartbeatCutoff))
+         {
+            live.add(run);
+         }
+      }
+      return (live);
+   }
+}

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

@@ -0,0 +1,770 @@
+/*
+ * 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.run;
+
+
+import java.io.IOException;
+import java.io.OutputStream;
+import java.io.Serializable;
+import java.nio.charset.StandardCharsets;
+import java.time.Instant;
+import java.time.ZoneOffset;
+import java.time.format.DateTimeFormatter;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+import java.util.function.Function;
+import java.util.zip.GZIPOutputStream;
+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;
+import com.kingsrook.qbits.backups.files.FileReferenceProvider;
+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.scope.ScopeResolver;
+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.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.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
+
+
+/*******************************************************************************
+ ** Executes one backup run (spec 8 and 9.2).
+ **
+ ** The order is the contract: the run row is created RUNNING; every table is
+ ** streamed in primary key order into numbered parts (with their SHA-256 and the
+ ** rowsHash); the files the rows reference are copied into the deduplicated
+ ** content-addressed store; checksums.sha256 is written; and the manifest is
+ ** written LAST, then checked with a head.  A run with no manifest did not
+ ** complete.  The run row is updated every page (heartbeat), and a failure marks
+ ** the run FAILED with a scrubbed message (never row values).
+ *******************************************************************************/
+public class BackupEngine
+{
+   private static final QLogger LOG = QLogger.getLogger(BackupEngine.class);
+
+   private static final ObjectMapper MAPPER = new ObjectMapper();
+
+   private static final DateTimeFormatter RUN_KEY_FORMAT = DateTimeFormatter.ofPattern("yyyyMMdd'T'HHmmss'Z'").withZone(ZoneOffset.UTC);
+   private static final DateTimeFormatter DATE_PATH      = DateTimeFormatter.ofPattern("yyyy/MM/dd").withZone(ZoneOffset.UTC);
+
+   private static final long MAX_ROWS_PER_PART = 1_000_000L;
+
+   private final BackupCatalog catalog = new BackupCatalog();
+
+
+
+   /*******************************************************************************
+    ** Run a backup.  Never throws for a backup failure: the result carries the
+    ** status and message (and the run row is FAILED).
+    *******************************************************************************/
+   public BackupRunResult execute(BackupRunRequest request)
+   {
+      BackupRunResult result  = new BackupRunResult();
+      Instant         started = request.getClock().instant();
+      String          runKey  = RUN_KEY_FORMAT.format(started) + "-" + UUID.randomUUID().toString().substring(0, 4);
+      String          planPrefix = request.getSettings().string("prefix", "qqq-backups");
+      String          instancePrefix = trimSlashes(planPrefix) + "/" + request.getInstanceName() + "/";
+      String          runPrefix  = instancePrefix + request.getSettings().planKey() + "/" + DATE_PATH.format(started) + "/" + runKey + "/";
+      result.setRunKey(runKey);
+      result.setRunPrefix(runPrefix);
+
+      try
+      {
+         Map<String, Serializable> runValues = new LinkedHashMap<>();
+         runValues.put("backupPlanId", request.getSettings().getPlanId());
+         runValues.put("runKey", runKey);
+         runValues.put("trigger", request.getTrigger());
+         runValues.put("requestedByUserId", request.getRequestedBy());
+         runValues.put("status", "RUNNING");
+         runValues.put("startDate", started);
+         runValues.put("heartbeatDate", started);
+         runValues.put("tablesPlanned", request.getScope().tables().size());
+         runValues.put("storageBucketAlias", request.getBucketAlias());
+         runValues.put("runPrefix", runPrefix);
+         runValues.put("instanceName", request.getInstanceName());
+         runValues.put("appVersion", request.getAppVersion());
+         runValues.put("securityScope", request.getSecurityScope());
+         runValues.put("encryptionKeyRef", request.getEncryptionKeyRef());
+         runValues.put("encryptionKeyFingerprint", request.getEncryptionKeyFingerprint());
+         runValues.put("verificationStatus", "UNVERIFIED");
+         result.setRunId(catalog.insert(BackupsTables.RUN, runValues));
+      }
+      catch(Exception e)
+      {
+         result.setStatus("FAILED");
+         result.setErrorMessage("Could not create the run record: " + e.getMessage());
+         return (result);
+      }
+
+      try
+      {
+         doRun(request, result, runPrefix, instancePrefix, started);
+      }
+      catch(CancelledException e)
+      {
+         finish(request, result, "CANCELLED", "Cancelled", started);
+      }
+      catch(TimedOutException e)
+      {
+         finish(request, result, "TIMED_OUT", e.getMessage(), started);
+      }
+      catch(Exception e)
+      {
+         LOG.warn("Backup run failed", e, logPair("runKey", runKey));
+         finish(request, result, "FAILED", scrub(e), started);
+      }
+      return (result);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void doRun(BackupRunRequest request, BackupRunResult result, String runPrefix, String instancePrefix, Instant started) throws Exception
+   {
+      QInstance        qInstance = QContext.getQInstance();
+      BackupStorage    storage   = request.getStorage();
+      var              settings  = request.getSettings();
+      String           format    = settings.format();
+      String           compression = settings.compression();
+      boolean          copyFiles = "COPY".equals(settings.fileObjectPolicy());
+      long             maxMillis = settings.integer("maxDurationMinutes", 240) * 60_000L;
+
+      if("ZSTD".equals(compression) || "PARQUET".equals(format))
+      {
+         throw (new IllegalStateException("The " + ("ZSTD".equals(compression) ? "ZSTD compression" : "PARQUET format") + " is not available yet; use GZIP and JSONL or CSV."));
+      }
+      String sensitivePolicy = settings.string("sensitiveFieldPolicy", "EXCLUDE");
+      if("INCLUDE_ENCRYPTED_ONLY".equals(sensitivePolicy) && !request.getTransform().encrypts())
+      {
+         throw (new IllegalStateException("The sensitive field policy INCLUDE_ENCRYPTED_ONLY requires client-side encryption."));
+      }
+      String consistency = consistencyFor(settings.string("consistency", "SNAPSHOT_PREFERRED"), result);
+
+      Function<String, BackupStorage> sourceResolver = request.getSourceResolver() != null ? request.getSourceResolver() : alias -> storage;
+      FileCopier copier = new FileCopier(sourceResolver, request.getBucketAlias(), storage, instancePrefix + "_files/sha256/", request.getTransform(),
+         catalog.fileStoreRegistry(request.getBucketAlias(), result.getRunId(), request.getEncryptionKeyFingerprint()), !copyFiles, result.getRunKey());
+
+      List<BackupManifest.TableEntry> manifestTables = new ArrayList<>();
+      List<String>                    checksums      = new ArrayList<>();
+      List<String>                    fingerprints   = new ArrayList<>();
+      FileIndexWriter                 indexWriter    = null;
+      long                            rows           = 0;
+      long                            bytesStored    = 0;
+      long                            bytesRaw       = 0;
+      int                             done           = 0;
+      int                             referenced     = 0;
+      int                             copied         = 0;
+      int                             deduplicated   = 0;
+      int                             missing        = 0;
+      long                            fileBytes      = 0;
+      long                            fileBytesRef   = 0;
+
+      try
+      {
+         for(ScopeResolver.ResolvedTable resolved : request.getScope().tables())
+         {
+            QTableMetaData table = qInstance.getTable(resolved.name());
+            String         backendType = qInstance.getBackend(table.getBackendName()) == null ? null : qInstance.getBackend(table.getBackendName()).getBackendType();
+
+            List<BackupManifest.ExcludedField> excluded = excludedFields(table, resolved, sensitivePolicy, settings.string("heavyFieldPolicy", "INLINE"));
+            List<String> excludedNames = excluded.stream().map(BackupManifest.ExcludedField::name).toList();
+
+            List<TableArtifactWriter> writers = new ArrayList<>();
+            String tablePrefix = runPrefix + "tables/" + table.getName() + "/";
+            for(String f : "JSONL_AND_CSV".equals(format) ? List.of("JSONL", "CSV") : List.of("CSV".equals(format) ? "CSV" : "JSONL"))
+            {
+               writers.add(new TableArtifactWriter(storage, tablePrefix, table, excludedNames, f, compression, settings.targetPartBytes(), MAX_ROWS_PER_PART,
+                  request.getTransform(), result.getRunKey()));
+            }
+
+            List<FileReference> references = new ArrayList<>();
+            long[]              counter    = { 0 };
+            Instant             deadline   = started.plusMillis(maxMillis);
+            Throwable[]         writeError = { null };
+
+            request.getReader().read(table, resolved.filterJson(), null, settings.pageSize(), null, record ->
+            {
+               try
+               {
+                  for(TableArtifactWriter writer : writers)
+                  {
+                     writer.write(record);
+                  }
+               }
+               catch(IOException e)
+               {
+                  throw (new IllegalStateException("Could not write a row of " + table.getName() + ": " + e.getMessage(), e));
+               }
+               if(copyFiles || "REFERENCE_ONLY".equals(settings.fileObjectPolicy()))
+               {
+                  for(FileReferenceProvider provider : request.getFileProviders())
+                  {
+                     references.addAll(provider.referencesIn(table, record));
+                  }
+               }
+               counter[0]++;
+               if(counter[0] % settings.pageSize() == 0)
+               {
+                  heartbeat(request, result, deadline, table.getName(), counter[0]);
+               }
+            });
+
+            String       rowsHash = null;
+            List<BackupManifest.Part> parts = new ArrayList<>();
+            String fingerprint = TableFingerprints.of(table, backendType);
+            fingerprints.add(fingerprint);
+            for(TableArtifactWriter writer : writers)
+            {
+               List<TableArtifactWriter.PartResult> results = writer.finish();
+               rowsHash = writer.rowsHash();
+               for(TableArtifactWriter.PartResult part : results)
+               {
+                  String relative = part.key().substring(runPrefix.length());
+                  parts.add(new BackupManifest.Part(relative, part.rows(), part.bytesRaw(), part.bytesStored(), part.sha256Stored(), part.sha256Raw(), part.format(), part.compression(), part.encrypted()));
+                  checksums.add(part.sha256Stored() + "  " + relative);
+                  bytesStored += part.bytesStored();
+                  bytesRaw += part.bytesRaw();
+                  catalog.insertArtifact(result.getRunId(), "TABLE_DATA", table.getName(), part.partNumber(), relative, part.format(), part.compression(),
+                     part.encrypted(), part.rows(), part.bytesRaw(), part.bytesStored(), part.sha256Stored(), part.sha256Raw(),
+                     part.partNumber() == results.size() ? rowsHash : null, part.firstKey(), part.lastKey(), fingerprint);
+               }
+            }
+            rows += counter[0];
+
+            for(FileReference ref : references)
+            {
+               if(indexWriter == null)
+               {
+                  indexWriter = new FileIndexWriter(storage, runPrefix + "files/index-00001.jsonl.gz", result.getRunKey());
+               }
+               FileCopier.IndexEntry entry = copier.process(ref);
+               indexWriter.write(entry);
+               referenced++;
+               switch(entry.status())
+               {
+                  case FileCopier.COPIED ->
+                  {
+                     copied++;
+                     fileBytes += entry.size();
+                  }
+                  case FileCopier.DEDUPLICATED -> deduplicated++;
+                  case FileCopier.MISSING -> missing++;
+                  default -> fileBytesRef += Math.max(0, entry.size());
+               }
+               if(request.getCancelRequested().getAsBoolean())
+               {
+                  throw (new CancelledException());
+               }
+            }
+
+            Map<String, String> keyRange = new LinkedHashMap<>();
+            keyRange.put("min", writers.get(0).getFirstKey());
+            keyRange.put("max", writers.get(0).getLastKey());
+            manifestTables.add(new BackupManifest.TableEntry(table.getName(), resolved.role().name(), table.getBackendName(), table.getPrimaryKeyField(),
+               fingerprint, TableFingerprints.descriptor(table, backendType), resolved.filterJson(), excluded, counter[0], rowsHash, keyRange, parts, consistency));
+            done++;
+            catalogProgress(result, done, rows, bytesRaw, bytesStored);
+            if(request.getCancelRequested().getAsBoolean())
+            {
+               throw (new CancelledException());
+            }
+         }
+      }
+      finally
+      {
+         if(indexWriter != null)
+         {
+            indexWriter.close();
+         }
+      }
+
+      List<String> indexKeys = new ArrayList<>();
+      if(indexWriter != null)
+      {
+         indexKeys.add("files/index-00001.jsonl.gz");
+         checksums.add(indexWriter.sha256Stored() + "  files/index-00001.jsonl.gz");
+         catalog.insertArtifact(result.getRunId(), "FILE_OBJECTS_INDEX", null, 1, "files/index-00001.jsonl.gz", "JSONL", "GZIP", request.getTransform().encrypts(),
+            indexWriter.rows(), indexWriter.bytesRaw(), indexWriter.bytesStored(), indexWriter.sha256Stored(), indexWriter.sha256Raw(), null, null, null, null);
+         bytesStored += indexWriter.bytesStored();
+      }
+
+      if(missing > 0)
+      {
+         if("FAIL".equals(settings.string("fileMissingPolicy", "WARN")))
+         {
+            throw (new IllegalStateException(missing + " referenced files are missing at the source"));
+         }
+         result.getWarnings().add(missing + " referenced files were missing at the source");
+      }
+
+      /////////////////////////////////////////////////////////
+      // checksums, then the manifest LAST (the commit mark) //
+      /////////////////////////////////////////////////////////
+      byte[] checksumBytes = (String.join("\n", checksums) + "\n").getBytes(StandardCharsets.UTF_8);
+      putBytes(storage, runPrefix + "checksums.sha256", checksumBytes, result.getRunKey());
+      catalog.insertArtifact(result.getRunId(), "CHECKSUMS", null, 1, "checksums.sha256", "TEXT", "NONE", false, checksums.size(), checksumBytes.length,
+         checksumBytes.length, HashingOutputStream.sha256Hex(checksumBytes), HashingOutputStream.sha256Hex(checksumBytes), null, null, null, null);
+
+      Instant finished = request.getClock().instant();
+      List<String> order = request.getScope().names();
+      BackupManifest manifest = new BackupManifest(BackupManifest.CURRENT_VERSION, result.getRunKey(),
+         new BackupManifest.PlanInfo(settings.planKey(), request.getPlanName(), settings.manifestSettings()),
+         new BackupManifest.InstanceInfo(request.getInstanceName(), request.getAppVersion(), qqqVersion(), List.of()),
+         started.toString(), finished.toString(), request.getRequestedBy(), request.getSecurityScope(),
+         new BackupManifest.ConsistencyInfo(result.getConsistencyAchieved(), List.of()),
+         request.getTransform().encrypts()
+            ? new BackupManifest.EncryptionInfo("CLIENT_AES256_GCM", "tink-streaming-aead-AES256_GCM_HKDF_1MB", request.getEncryptionKeyRef(), request.getEncryptionKeyFingerprint())
+            : new BackupManifest.EncryptionInfo("NONE", null, null, null),
+         manifestTables, order,
+         new BackupManifest.FilesInfo(settings.fileObjectPolicy(), indexKeys, copied + deduplicated, fileBytes + fileBytesRef, missing),
+         result.getWarnings(),
+         new BackupManifest.Totals(manifestTables.size(), rows, bytesStored));
+      byte[] manifestBytes = manifest.toJsonBytes();
+      String manifestKey   = runPrefix + "manifest.json";
+      putBytes(storage, manifestKey, manifestBytes, result.getRunKey());
+      if(storage.head(manifestKey).isEmpty())
+      {
+         throw (new IllegalStateException("The manifest was written but is not visible in the bucket"));
+      }
+      catalog.insertArtifact(result.getRunId(), "MANIFEST", null, 1, "manifest.json", "JSON", "NONE", false, manifestTables.size(), manifestBytes.length,
+         manifestBytes.length, HashingOutputStream.sha256Hex(manifestBytes), HashingOutputStream.sha256Hex(manifestBytes), null, null, null, null);
+
+      result.setManifestKey(manifestKey);
+      result.setManifestSha256(HashingOutputStream.sha256Hex(manifestBytes));
+      result.setTables(manifestTables.size());
+      result.setRows(rows);
+      result.setBytesRaw(bytesRaw);
+      result.setBytesStored(bytesStored);
+      result.setFilesReferenced(referenced);
+      result.setFilesCopied(copied);
+      result.setFilesDeduplicated(deduplicated);
+      result.setFilesMissing(missing);
+      result.setFileBytesCopied(fileBytes);
+
+      Map<String, Serializable> extra = new LinkedHashMap<>();
+      extra.put("manifestKey", manifestKey);
+      extra.put("manifestSha256", result.getManifestSha256());
+      extra.put("schemaFingerprint", TableFingerprints.combine(fingerprints));
+      extra.put("qqqVersion", qqqVersion());
+      extra.put("consistencyAchieved", result.getConsistencyAchieved());
+      extra.put("filesReferenced", referenced);
+      extra.put("filesCopied", copied);
+      extra.put("filesDeduplicated", deduplicated);
+      extra.put("filesMissing", missing);
+      extra.put("fileBytesCopied", fileBytes);
+      extra.put("fileBytesReferenced", fileBytesRef);
+      extra.put("tablesDone", manifestTables.size());
+      extra.put("rowsTotal", rows);
+      extra.put("bytesRaw", bytesRaw);
+      extra.put("bytesStored", bytesStored);
+      extra.put("warningCount", result.getWarnings().size());
+      finishWith(request, result, result.getWarnings().isEmpty() ? "SUCCEEDED" : "SUCCEEDED_WITH_WARNINGS", null, started, extra);
+   }
+
+
+
+   /*******************************************************************************
+    ** Work out the consistency achieved.  Until the core consistent-read hook ships
+    ** (QQQ core PR feature/consistent-read-transactions, next 4.1.x RC), no backend
+    ** reports a snapshot, so: SNAPSHOT_REQUIRED fails before writing anything,
+    ** SNAPSHOT_PREFERRED records BEST_EFFORT with a warning, PER_TABLE records PER_TABLE.
+    *******************************************************************************/
+   private String consistencyFor(String requested, BackupRunResult result)
+   {
+      switch(requested)
+      {
+         case "SNAPSHOT_REQUIRED":
+            throw (new IllegalStateException("The plan requires a consistent snapshot, which this version of QQQ cannot open yet. Use SNAPSHOT_PREFERRED or PER_TABLE."));
+         case "PER_TABLE":
+            result.setConsistencyAchieved("PER_TABLE");
+            return ("PER_TABLE");
+         default:
+            result.setConsistencyAchieved("BEST_EFFORT");
+            result.getWarnings().add("No consistent snapshot was available: every table was read on its own (BEST_EFFORT)");
+            return ("BEST_EFFORT");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The fields left out of a table, by policy.  The primary key is never left out.
+    *******************************************************************************/
+   private List<BackupManifest.ExcludedField> excludedFields(QTableMetaData table, ScopeResolver.ResolvedTable resolved, String sensitivePolicy, String heavyPolicy)
+   {
+      Map<String, String> out = new LinkedHashMap<>();
+      for(QFieldMetaData field : table.getFields().values())
+      {
+         if(field.getName().equals(table.getPrimaryKeyField()))
+         {
+            continue;
+         }
+         if("EXCLUDE".equals(sensitivePolicy) && (field.getIsSensitive() || field.getType() == QFieldType.PASSWORD))
+         {
+            out.put(field.getName(), "SENSITIVE_POLICY");
+         }
+         else if("EXCLUDE".equals(heavyPolicy) && field.getIsHeavy())
+         {
+            out.put(field.getName(), "HEAVY_POLICY");
+         }
+      }
+      for(String name : resolved.excludedFields())
+      {
+         if(table.getFields().containsKey(name) && !name.equals(table.getPrimaryKeyField()))
+         {
+            out.put(name, "SCOPE");
+         }
+      }
+      return (out.entrySet().stream().map(e -> new BackupManifest.ExcludedField(e.getKey(), e.getValue())).toList());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void heartbeat(BackupRunRequest request, BackupRunResult result, Instant deadline, String tableName, long rowsSoFar)
+   {
+      Instant now = request.getClock().instant();
+      if(request.getCancelRequested().getAsBoolean())
+      {
+         throw (new CancelledException());
+      }
+      if(now.isAfter(deadline))
+      {
+         throw (new TimedOutException("The run exceeded its maximum duration"));
+      }
+      try
+      {
+         catalog.update(BackupsTables.RUN, result.getRunId(), Map.of("heartbeatDate", now));
+      }
+      catch(Exception e)
+      {
+         LOG.warn("Could not record a heartbeat", e);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void catalogProgress(BackupRunResult result, int done, long rows, long bytesRaw, long bytesStored)
+   {
+      try
+      {
+         Map<String, Serializable> v = new LinkedHashMap<>();
+         v.put("tablesDone", done);
+         v.put("rowsTotal", rows);
+         v.put("bytesRaw", bytesRaw);
+         v.put("bytesStored", bytesStored);
+         catalog.update(BackupsTables.RUN, result.getRunId(), v);
+      }
+      catch(Exception e)
+      {
+         LOG.warn("Could not record progress", e);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void finish(BackupRunRequest request, BackupRunResult result, String status, String message, Instant started)
+   {
+      try
+      {
+         finishWith(request, result, status, message, started, new LinkedHashMap<>());
+      }
+      catch(Exception e)
+      {
+         LOG.warn("Could not finish the run record", e);
+         result.setStatus(status);
+         result.setErrorMessage(message);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void finishWith(BackupRunRequest request, BackupRunResult result, String status, String message, Instant started, Map<String, Serializable> extra) throws Exception
+   {
+      Instant end = request.getClock().instant();
+      Map<String, Serializable> v = new LinkedHashMap<>(extra);
+      v.put("status", status);
+      v.put("endDate", end);
+      v.put("durationMs", end.toEpochMilli() - started.toEpochMilli());
+      v.put("heartbeatDate", end);
+      v.put("errorMessage", message);
+      v.put("warningCount", result.getWarnings().size());
+      catalog.update(BackupsTables.RUN, result.getRunId(), v);
+      result.setStatus(status);
+      result.setErrorMessage(message);
+      signal(request, result, status, message);
+   }
+
+
+
+   /*******************************************************************************
+    ** Update the plan denormalized fields, check in the heartbeat, and raise or resolve alerts.
+    *******************************************************************************/
+   private void signal(BackupRunRequest request, BackupRunResult result, String status, String message) throws Exception
+   {
+      Integer planId = request.getSettings().getPlanId();
+      if(planId == null)
+      {
+         return;
+      }
+      boolean ok = "SUCCEEDED".equals(status) || "SUCCEEDED_WITH_WARNINGS".equals(status);
+      Map<String, Serializable> plan = new LinkedHashMap<>();
+      plan.put("lastRunId", result.getRunId());
+      if(ok)
+      {
+         plan.put("lastSuccessRunId", result.getRunId());
+         plan.put("lastSuccessDate", request.getClock().instant());
+         plan.put("slaStatus", "OK");
+      }
+      catalog.update(BackupsTables.PLAN, planId, plan);
+
+      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);
+         sink.heartbeat("backups.plan:" + planKey, request.getSettings().integer("slaHours", 26) * 3600L, 0L);
+         if(result.getFilesMissing() > 0)
+         {
+            sink.raise("backups.files.missing", "backups.files.missing:" + planKey, BackupAlertSink.Severity.WARNING, "Referenced files are missing",
+               Map.of("plan", planKey, "missing", String.valueOf(result.getFilesMissing()), "run", result.getRunKey()));
+         }
+         else
+         {
+            sink.resolve("backups.files.missing", "backups.files.missing:" + planKey);
+         }
+      }
+      else if(!"CANCELLED".equals(status))
+      {
+         sink.raise("backups.run.failed", "backups.run.failed:" + planKey, BackupAlertSink.Severity.WARNING, "A backup run failed",
+            Map.of("plan", planKey, "status", status, "run", result.getRunKey()));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** A message safe to store: the exception type and message, never row values (the
+    ** engine never puts values in messages), truncated.
+    *******************************************************************************/
+   private static String scrub(Exception e)
+   {
+      String message = e.getClass().getSimpleName() + ": " + e.getMessage();
+      return (message.length() > 2000 ? message.substring(0, 2000) : message);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static void putBytes(BackupStorage storage, String key, byte[] bytes, String runKey) throws IOException
+   {
+      try(OutputStream out = storage.openWrite(key, WriteOptions.create().withMetadata("qqq-backup-run", runKey)))
+      {
+         out.write(bytes);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static String trimSlashes(String s)
+   {
+      String r = s;
+      while(r.startsWith("/"))
+      {
+         r = r.substring(1);
+      }
+      while(r.endsWith("/"))
+      {
+         r = r.substring(0, r.length() - 1);
+      }
+      return (r);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   static String qqqVersion()
+   {
+      String v = QInstance.class.getPackage().getImplementationVersion();
+      return (v == null ? "unknown" : v);
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   static class CancelledException extends RuntimeException
+   {
+   }
+
+
+
+   /***************************************************************************
+    **
+    ***************************************************************************/
+   static class TimedOutException extends RuntimeException
+   {
+      /*******************************************************************************
+       ** Constructor.
+       *******************************************************************************/
+      TimedOutException(String message)
+      {
+         super(message);
+      }
+   }
+
+
+
+   /***************************************************************************
+    ** The per-run file index, written as it goes: one JSON line per reference.
+    ***************************************************************************/
+   static class FileIndexWriter
+   {
+      private final HashingOutputStream raw;
+      private final HashingOutputStream stored;
+      private long                      rows = 0;
+
+
+
+      /*******************************************************************************
+       ** Constructor.
+       *******************************************************************************/
+      FileIndexWriter(BackupStorage storage, String key, String runKey) throws IOException
+      {
+         stored = new HashingOutputStream(storage.openWrite(key, WriteOptions.create().withMetadata("qqq-backup-run", runKey)));
+         raw = new HashingOutputStream(new GZIPOutputStream(stored));
+      }
+
+
+
+      /*******************************************************************************
+       ** Write one entry.
+       *******************************************************************************/
+      void write(FileCopier.IndexEntry entry) throws IOException
+      {
+         Map<String, Object> line = new LinkedHashMap<>();
+         line.put("table", entry.tableName());
+         line.put("recordKey", entry.recordKey());
+         line.put("field", entry.field());
+         line.put("sourceBucket", entry.sourceBucketAlias());
+         line.put("sourceKey", entry.sourceKey());
+         line.put("sha256", entry.sha256());
+         line.put("size", entry.size());
+         line.put("status", entry.status());
+         line.put("casKey", entry.casKey());
+         raw.write((MAPPER.writeValueAsString(line) + "\n").getBytes(StandardCharsets.UTF_8));
+         rows++;
+      }
+
+
+
+      /*******************************************************************************
+       ** Close the stream.
+       *******************************************************************************/
+      void close() throws IOException
+      {
+         raw.close();
+      }
+
+
+
+      /*******************************************************************************
+       ** Rows written.
+       *******************************************************************************/
+      long rows()
+      {
+         return (rows);
+      }
+
+
+
+      /*******************************************************************************
+       ** Raw byte count.
+       *******************************************************************************/
+      long bytesRaw()
+      {
+         return (raw.getCount());
+      }
+
+
+
+      /*******************************************************************************
+       ** Stored byte count.
+       *******************************************************************************/
+      long bytesStored()
+      {
+         return (stored.getCount());
+      }
+
+
+
+      /*******************************************************************************
+       ** Raw hash.
+       *******************************************************************************/
+      String sha256Raw()
+      {
+         return (raw.getSha256());
+      }
+
+
+
+      /*******************************************************************************
+       ** Stored hash.
+       *******************************************************************************/
+      String sha256Stored()
+      {
+         return (stored.getSha256());
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/backups/run/BackupRunFactory.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.run;
+
+
+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.scope.PlanSettings;
+import com.kingsrook.qbits.backups.scope.ScopeResolver;
+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.session.QSession;
+
+
+/*******************************************************************************
+ ** Builds the BackupRunRequest for a plan record: loads the scope rows, resolves
+ ** the tables, and picks the storage by the plan bucket alias.
+ *******************************************************************************/
+public final class BackupRunFactory
+{
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private BackupRunFactory()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** The scope rules of a plan.
+    *******************************************************************************/
+   public static List<ScopeResolver.ScopeRule> scopeRules(Integer planId) throws QException
+   {
+      List<ScopeResolver.ScopeRule> rules = new ArrayList<>();
+      for(QRecord row : new BackupCatalog().where(BackupsTables.PLAN_SCOPE, "backupPlanId", planId))
+      {
+         rules.add(new ScopeResolver.ScopeRule("INCLUDE".equals(row.getValueString("action")), row.getValueString("selectorType"), row.getValueString("selectorValue"),
+            row.getValueString("filterJson"), !Boolean.FALSE.equals(row.getValueBoolean("includeAssociatedChildren")), row.getValueString("fieldExclusions")));
+      }
+      return (rules);
+   }
+
+
+
+   /*******************************************************************************
+    ** Resolve the scope of a plan record.
+    *******************************************************************************/
+   public static ScopeResolver.ResolvedScope resolveScope(QRecord plan) throws QException
+   {
+      return (new ScopeResolver(QContext.getQInstance()).resolve(PlanSettings.of(plan), scopeRules(plan.getValueInteger("id"))));
+   }
+
+
+
+   /*******************************************************************************
+    ** The request to run a plan.
+    *******************************************************************************/
+   public static BackupRunRequest forPlan(QRecord plan, String trigger) throws QException
+   {
+      BackupsQBitConfig config   = BackupsRuntime.getConfig();
+      PlanSettings      settings = PlanSettings.of(plan);
+      QSession          session  = QContext.getQSession();
+      String            user     = session == null || session.getUser() == null ? "system:scheduler" : session.getUser().getIdReference();
+
+      return (new BackupRunRequest()
+         .withSettings(settings)
+         .withScope(resolveScope(plan))
+         .withTrigger(trigger)
+         .withRequestedBy("SCHEDULED".equals(trigger) ? "system:scheduler" : user)
+         .withSecurityScope("SCHEDULED".equals(trigger) ? "FULL" : "FULL")
+         .withBucketAlias(settings.string("storageBucketAlias", null))
+         .withStorage(BackupsRuntime.storageFor(settings.string("storageBucketAlias", null)))
+         .withSourceResolver(BackupsRuntime::storageFor)
+         .withInstanceName(config.getInstanceName() != null ? config.getInstanceName() : "qqq")
+         .withPlanName(plan.getValueString("name"))
+         .withClock(BackupsRuntime.getClock()));
+   }
+}

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

@@ -0,0 +1,413 @@
+/*
+ * 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.run;
+
+
+import java.time.Clock;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.function.BooleanSupplier;
+import com.kingsrook.qbits.backups.codec.ArtifactTransform;
+import com.kingsrook.qbits.backups.files.FileReferenceProvider;
+import com.kingsrook.qbits.backups.scope.PlanSettings;
+import com.kingsrook.qbits.backups.scope.ScopeResolver;
+import com.kingsrook.qbits.backups.storage.BackupStorage;
+
+
+/*******************************************************************************
+ ** Everything a backup run needs, resolved by the caller (the process step, the
+ ** scheduler or a test).
+ *******************************************************************************/
+public class BackupRunRequest
+{
+   private PlanSettings               settings;
+   private ScopeResolver.ResolvedScope scope;
+   private String                     trigger         = "MANUAL";
+   private String                     requestedBy     = "system";
+   private String                     securityScope   = "FULL";
+   private BackupStorage              storage;
+   private String                     bucketAlias;
+   private String                     instanceName    = "qqq";
+   private String                     appVersion;
+   private String                     planName;
+   private ArtifactTransform          transform       = ArtifactTransform.IDENTITY;
+   private String                     encryptionKeyRef;
+   private String                     encryptionKeyFingerprint;
+   private List<FileReferenceProvider> fileProviders   = new ArrayList<>(List.of(new FileReferenceProvider.FromTableMetaData()));
+   private TableReader                reader          = new TableReader.Keyset();
+   private Clock                      clock           = Clock.systemUTC();
+   private BooleanSupplier            cancelRequested = () -> false;
+   private java.util.function.Function<String, BackupStorage> sourceResolver;
+
+
+
+   /*******************************************************************************
+    ** Getter for settings
+    *******************************************************************************/
+   public PlanSettings getSettings()
+   {
+      return (settings);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for settings
+    *******************************************************************************/
+   public BackupRunRequest withSettings(PlanSettings settings)
+   {
+      this.settings = settings;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for scope
+    *******************************************************************************/
+   public ScopeResolver.ResolvedScope getScope()
+   {
+      return (scope);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for scope
+    *******************************************************************************/
+   public BackupRunRequest withScope(ScopeResolver.ResolvedScope scope)
+   {
+      this.scope = scope;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for trigger
+    *******************************************************************************/
+   public String getTrigger()
+   {
+      return (trigger);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for trigger
+    *******************************************************************************/
+   public BackupRunRequest withTrigger(String trigger)
+   {
+      this.trigger = trigger;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for requestedBy
+    *******************************************************************************/
+   public String getRequestedBy()
+   {
+      return (requestedBy);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for requestedBy
+    *******************************************************************************/
+   public BackupRunRequest withRequestedBy(String requestedBy)
+   {
+      this.requestedBy = requestedBy;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for securityScope (FULL, or USER when the run saw only what a user may see)
+    *******************************************************************************/
+   public String getSecurityScope()
+   {
+      return (securityScope);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for securityScope
+    *******************************************************************************/
+   public BackupRunRequest withSecurityScope(String securityScope)
+   {
+      this.securityScope = securityScope;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for storage
+    *******************************************************************************/
+   public BackupStorage getStorage()
+   {
+      return (storage);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for storage
+    *******************************************************************************/
+   public BackupRunRequest withStorage(BackupStorage storage)
+   {
+      this.storage = storage;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for bucketAlias
+    *******************************************************************************/
+   public String getBucketAlias()
+   {
+      return (bucketAlias);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for bucketAlias
+    *******************************************************************************/
+   public BackupRunRequest withBucketAlias(String bucketAlias)
+   {
+      this.bucketAlias = bucketAlias;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for instanceName
+    *******************************************************************************/
+   public String getInstanceName()
+   {
+      return (instanceName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for instanceName
+    *******************************************************************************/
+   public BackupRunRequest withInstanceName(String instanceName)
+   {
+      this.instanceName = instanceName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for appVersion
+    *******************************************************************************/
+   public String getAppVersion()
+   {
+      return (appVersion);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for appVersion
+    *******************************************************************************/
+   public BackupRunRequest withAppVersion(String appVersion)
+   {
+      this.appVersion = appVersion;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for planName
+    *******************************************************************************/
+   public String getPlanName()
+   {
+      return (planName);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for planName
+    *******************************************************************************/
+   public BackupRunRequest withPlanName(String planName)
+   {
+      this.planName = planName;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for transform
+    *******************************************************************************/
+   public ArtifactTransform getTransform()
+   {
+      return (transform);
+   }
+
+
+
+   /*******************************************************************************
+    ** Set the artifact transform (encryption) with the key reference and fingerprint to record.
+    *******************************************************************************/
+   public BackupRunRequest withTransform(ArtifactTransform transform, String keyRef, String keyFingerprint)
+   {
+      this.transform = transform;
+      this.encryptionKeyRef = keyRef;
+      this.encryptionKeyFingerprint = keyFingerprint;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for encryptionKeyRef
+    *******************************************************************************/
+   public String getEncryptionKeyRef()
+   {
+      return (encryptionKeyRef);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for encryptionKeyFingerprint
+    *******************************************************************************/
+   public String getEncryptionKeyFingerprint()
+   {
+      return (encryptionKeyFingerprint);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for fileProviders
+    *******************************************************************************/
+   public List<FileReferenceProvider> getFileProviders()
+   {
+      return (fileProviders);
+   }
+
+
+
+   /*******************************************************************************
+    ** Add a file reference provider.
+    *******************************************************************************/
+   public BackupRunRequest withFileProvider(FileReferenceProvider provider)
+   {
+      this.fileProviders.add(provider);
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for reader
+    *******************************************************************************/
+   public TableReader getReader()
+   {
+      return (reader);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for reader
+    *******************************************************************************/
+   public BackupRunRequest withReader(TableReader reader)
+   {
+      this.reader = reader;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for clock
+    *******************************************************************************/
+   public Clock getClock()
+   {
+      return (clock);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for clock
+    *******************************************************************************/
+   public BackupRunRequest withClock(Clock clock)
+   {
+      this.clock = clock;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for cancelRequested
+    *******************************************************************************/
+   public BooleanSupplier getCancelRequested()
+   {
+      return (cancelRequested);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for cancelRequested
+    *******************************************************************************/
+   public BackupRunRequest withCancelRequested(BooleanSupplier cancelRequested)
+   {
+      this.cancelRequested = cancelRequested;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for sourceResolver (bucket alias of the referencing files to storage); defaults to the plan storage
+    *******************************************************************************/
+   public java.util.function.Function<String, BackupStorage> getSourceResolver()
+   {
+      return (sourceResolver);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for sourceResolver
+    *******************************************************************************/
+   public BackupRunRequest withSourceResolver(java.util.function.Function<String, BackupStorage> sourceResolver)
+   {
+      this.sourceResolver = sourceResolver;
+      return (this);
+   }
+}

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

@@ -0,0 +1,407 @@
+/*
+ * 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.run;
+
+
+import java.util.ArrayList;
+import java.util.List;
+
+
+/*******************************************************************************
+ ** What a backup run did.
+ *******************************************************************************/
+public class BackupRunResult
+{
+   private Integer      runId;
+   private String       runKey;
+   private String       runPrefix;
+   private String       status;
+   private String       manifestKey;
+   private String       manifestSha256;
+   private String       consistencyAchieved;
+   private int          tables;
+   private long         rows;
+   private long         bytesStored;
+   private long         bytesRaw;
+   private int          filesReferenced;
+   private int          filesCopied;
+   private int          filesDeduplicated;
+   private int          filesMissing;
+   private long         fileBytesCopied;
+   private String       errorMessage;
+   private List<String> warnings = new ArrayList<>();
+
+
+
+   /*******************************************************************************
+    ** Whether the run produced a usable backup (has a manifest).
+    *******************************************************************************/
+   public boolean isUsable()
+   {
+      return (manifestKey != null && ("SUCCEEDED".equals(status) || "SUCCEEDED_WITH_WARNINGS".equals(status)));
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for runId
+    *******************************************************************************/
+   public Integer getRunId()
+   {
+      return (runId);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for runId
+    *******************************************************************************/
+   public void setRunId(Integer runId)
+   {
+      this.runId = runId;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for runKey
+    *******************************************************************************/
+   public String getRunKey()
+   {
+      return (runKey);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for runKey
+    *******************************************************************************/
+   public void setRunKey(String runKey)
+   {
+      this.runKey = runKey;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for runPrefix
+    *******************************************************************************/
+   public String getRunPrefix()
+   {
+      return (runPrefix);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for runPrefix
+    *******************************************************************************/
+   public void setRunPrefix(String runPrefix)
+   {
+      this.runPrefix = runPrefix;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for status
+    *******************************************************************************/
+   public String getStatus()
+   {
+      return (status);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for status
+    *******************************************************************************/
+   public void setStatus(String status)
+   {
+      this.status = status;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for manifestKey
+    *******************************************************************************/
+   public String getManifestKey()
+   {
+      return (manifestKey);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for manifestKey
+    *******************************************************************************/
+   public void setManifestKey(String manifestKey)
+   {
+      this.manifestKey = manifestKey;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for manifestSha256
+    *******************************************************************************/
+   public String getManifestSha256()
+   {
+      return (manifestSha256);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for manifestSha256
+    *******************************************************************************/
+   public void setManifestSha256(String manifestSha256)
+   {
+      this.manifestSha256 = manifestSha256;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for consistencyAchieved
+    *******************************************************************************/
+   public String getConsistencyAchieved()
+   {
+      return (consistencyAchieved);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for consistencyAchieved
+    *******************************************************************************/
+   public void setConsistencyAchieved(String consistencyAchieved)
+   {
+      this.consistencyAchieved = consistencyAchieved;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for tables
+    *******************************************************************************/
+   public int getTables()
+   {
+      return (tables);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for tables
+    *******************************************************************************/
+   public void setTables(int tables)
+   {
+      this.tables = tables;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for rows
+    *******************************************************************************/
+   public long getRows()
+   {
+      return (rows);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for rows
+    *******************************************************************************/
+   public void setRows(long rows)
+   {
+      this.rows = rows;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for bytesStored
+    *******************************************************************************/
+   public long getBytesStored()
+   {
+      return (bytesStored);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for bytesStored
+    *******************************************************************************/
+   public void setBytesStored(long bytesStored)
+   {
+      this.bytesStored = bytesStored;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for bytesRaw
+    *******************************************************************************/
+   public long getBytesRaw()
+   {
+      return (bytesRaw);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for bytesRaw
+    *******************************************************************************/
+   public void setBytesRaw(long bytesRaw)
+   {
+      this.bytesRaw = bytesRaw;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for filesReferenced
+    *******************************************************************************/
+   public int getFilesReferenced()
+   {
+      return (filesReferenced);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for filesReferenced
+    *******************************************************************************/
+   public void setFilesReferenced(int filesReferenced)
+   {
+      this.filesReferenced = filesReferenced;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for filesCopied
+    *******************************************************************************/
+   public int getFilesCopied()
+   {
+      return (filesCopied);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for filesCopied
+    *******************************************************************************/
+   public void setFilesCopied(int filesCopied)
+   {
+      this.filesCopied = filesCopied;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for filesDeduplicated
+    *******************************************************************************/
+   public int getFilesDeduplicated()
+   {
+      return (filesDeduplicated);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for filesDeduplicated
+    *******************************************************************************/
+   public void setFilesDeduplicated(int filesDeduplicated)
+   {
+      this.filesDeduplicated = filesDeduplicated;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for filesMissing
+    *******************************************************************************/
+   public int getFilesMissing()
+   {
+      return (filesMissing);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for filesMissing
+    *******************************************************************************/
+   public void setFilesMissing(int filesMissing)
+   {
+      this.filesMissing = filesMissing;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for fileBytesCopied
+    *******************************************************************************/
+   public long getFileBytesCopied()
+   {
+      return (fileBytesCopied);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for fileBytesCopied
+    *******************************************************************************/
+   public void setFileBytesCopied(long fileBytesCopied)
+   {
+      this.fileBytesCopied = fileBytesCopied;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for errorMessage
+    *******************************************************************************/
+   public String getErrorMessage()
+   {
+      return (errorMessage);
+   }
+
+
+
+   /*******************************************************************************
+    ** Setter for errorMessage
+    *******************************************************************************/
+   public void setErrorMessage(String errorMessage)
+   {
+      this.errorMessage = errorMessage;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for warnings
+    *******************************************************************************/
+   public List<String> getWarnings()
+   {
+      return (warnings);
+   }
+}

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

@@ -0,0 +1,128 @@
+/*
+ * 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.run;
+
+
+import java.io.Serializable;
+import java.util.List;
+import java.util.function.Consumer;
+import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+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.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.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.utils.JsonUtils;
+
+
+/*******************************************************************************
+ ** Reads the rows of one table in primary key order, in keyset pages (WHERE pk >
+ ** lastKey ORDER BY pk LIMIT n), so the cost stays flat with depth and a read can
+ ** resume from a key.  A read raw: hidden fields, passwords and heavy fields are
+ ** returned as stored, and possible values are not translated.
+ **
+ ** This is an internal stand-in for the QQQ core KeysetPager and QueryInput
+ ** withRawRead (core PR feature/keyset-pager-raw-read); the run engine only
+ ** depends on this interface, so it is swapped when that ships in the next RC.
+ *******************************************************************************/
+public interface TableReader
+{
+
+   /***************************************************************************
+    ** Read every row of the table matching the optional filter, after startAfterKey
+    ** (exclusive, null for the beginning), calling the sink for each in key order.
+    ***************************************************************************/
+   void read(QTableMetaData table, String filterJson, Serializable startAfterKey, int pageSize, QBackendTransaction transaction, Consumer<QRecord> sink) throws QException;
+
+
+   /***************************************************************************
+    ** The default implementation over QueryAction.
+    ***************************************************************************/
+   class Keyset implements TableReader
+   {
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      private static QQueryFilter parseFilter(String filterJson) throws QException
+      {
+         try
+         {
+            return (filterJson == null || filterJson.isBlank() ? null : JsonUtils.toObject(filterJson, QQueryFilter.class));
+         }
+         catch(java.io.IOException e)
+         {
+            throw (new QException("Could not read a scope filter: " + e.getMessage()));
+         }
+      }
+
+
+
+      /*******************************************************************************
+       ** {@inheritDoc}
+       *******************************************************************************/
+      @Override
+      public void read(QTableMetaData table, String filterJson, Serializable startAfterKey, int pageSize, QBackendTransaction transaction, Consumer<QRecord> sink) throws QException
+      {
+         String       pk      = table.getPrimaryKeyField();
+         Serializable lastKey = startAfterKey;
+         QQueryFilter user    = parseFilter(filterJson);
+
+         while(true)
+         {
+            QQueryFilter filter = new QQueryFilter();
+            if(lastKey != null)
+            {
+               filter.addCriteria(new QFilterCriteria(pk, QCriteriaOperator.GREATER_THAN, List.of(lastKey)));
+            }
+            if(user != null)
+            {
+               filter.addSubFilter(user);
+            }
+            filter.withOrderBy(new QFilterOrderBy(pk, true));
+            filter.setLimit(pageSize);
+
+            QueryInput queryInput = new QueryInput(table.getName());
+            queryInput.setFilter(filter);
+            queryInput.setShouldOmitHiddenFields(false);
+            queryInput.setShouldMaskPasswords(false);
+            queryInput.setShouldFetchHeavyFields(true);
+            queryInput.setShouldTranslatePossibleValues(false);
+            queryInput.setShouldGenerateDisplayValues(false);
+            if(transaction != null)
+            {
+               queryInput.setTransaction(transaction);
+            }
+            queryInput.withPermissionBypass("backups run");
+
+            List<QRecord> page = new QueryAction().execute(queryInput).getRecords();
+            for(QRecord record : page)
+            {
+               sink.accept(record);
+               lastKey = record.getValue(pk);
+            }
+            if(page.size() < pageSize)
+            {
+               return;
+            }
+         }
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/backups/scope/BackupTableMetaData.java

@@ -0,0 +1,147 @@
+/*
+ * 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.scope;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QSupplementalTableMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** Supplemental table meta-data: the backup role of a table, and the fields
+ ** that reference files in object storage (when the app does not register them
+ ** through the object-storage reference providers).
+ *******************************************************************************/
+public class BackupTableMetaData extends QSupplementalTableMetaData
+{
+   public static final String TYPE = "backups";
+
+   private TableRole    role;
+   private List<String> fileReferenceFields = new ArrayList<>();
+   private String       fileBucketAlias;
+
+
+
+   /*******************************************************************************
+    ** The BackupTableMetaData on a table, or null.
+    *******************************************************************************/
+   public static BackupTableMetaData of(QTableMetaData table)
+   {
+      return (table == null ? null : QSupplementalTableMetaData.of(table, TYPE));
+   }
+
+
+
+   /*******************************************************************************
+    ** The BackupTableMetaData on a table, adding an empty one if needed.
+    *******************************************************************************/
+   public static BackupTableMetaData ofOrWithNew(QTableMetaData table)
+   {
+      return (QSupplementalTableMetaData.ofOrWithNew(table, TYPE, BackupTableMetaData::new));
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public String getType()
+   {
+      return (TYPE);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   protected QSupplementalTableMetaData finishClone(QSupplementalTableMetaData abstractClone)
+   {
+      BackupTableMetaData clone = (BackupTableMetaData) abstractClone;
+      clone.role = this.role;
+      clone.fileReferenceFields = new ArrayList<>(this.fileReferenceFields);
+      clone.fileBucketAlias = this.fileBucketAlias;
+      return (clone);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for role
+    *******************************************************************************/
+   public TableRole getRole()
+   {
+      return (role);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for role
+    *******************************************************************************/
+   public BackupTableMetaData withRole(TableRole role)
+   {
+      this.role = role;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for fileReferenceFields (fields holding a storage key in the source bucket)
+    *******************************************************************************/
+   public List<String> getFileReferenceFields()
+   {
+      return (fileReferenceFields);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for fileReferenceFields
+    *******************************************************************************/
+   public BackupTableMetaData withFileReferenceFields(List<String> fileReferenceFields)
+   {
+      this.fileReferenceFields = fileReferenceFields;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for fileBucketAlias (the bucket the fileReferenceFields keys live in)
+    *******************************************************************************/
+   public String getFileBucketAlias()
+   {
+      return (fileBucketAlias);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for fileBucketAlias
+    *******************************************************************************/
+   public BackupTableMetaData withFileBucketAlias(String fileBucketAlias)
+   {
+      this.fileBucketAlias = fileBucketAlias;
+      return (this);
+   }
+}

src/main/java/com/kingsrook/qbits/backups/scope/PlanSettings.java

@@ -0,0 +1,229 @@
+/*
+ * 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.scope;
+
+
+import java.io.Serializable;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.utils.ValueUtils;
+
+
+/*******************************************************************************
+ ** The settings of a backup plan (a backups_plan record), with the defaults of
+ ** spec 4.1 applied for anything not set.  Ad-hoc exports (no plan row) build one
+ ** with the static factory and the with() method.
+ *******************************************************************************/
+public class PlanSettings
+{
+   private final Map<String, Serializable> values = new LinkedHashMap<>();
+
+   private Integer planId;
+
+
+
+   /*******************************************************************************
+    ** From a plan record.
+    *******************************************************************************/
+   public static PlanSettings of(QRecord plan)
+   {
+      PlanSettings settings = new PlanSettings();
+      if(plan != null)
+      {
+         settings.planId = plan.getValueInteger("id");
+         settings.values.putAll(plan.getValues());
+      }
+      return (settings);
+   }
+
+
+
+   /*******************************************************************************
+    ** An ad-hoc (no plan row) settings object with all defaults.
+    *******************************************************************************/
+   public static PlanSettings adHoc()
+   {
+      return (new PlanSettings());
+   }
+
+
+
+   /*******************************************************************************
+    ** Set one value (fluent).
+    *******************************************************************************/
+   public PlanSettings with(String name, Serializable value)
+   {
+      values.put(name, value);
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** The plan id, or null for an ad-hoc run.
+    *******************************************************************************/
+   public Integer getPlanId()
+   {
+      return (planId);
+   }
+
+
+
+   /*******************************************************************************
+    ** A string setting.
+    *******************************************************************************/
+   public String string(String name, String defaultValue)
+   {
+      String value = ValueUtils.getValueAsString(values.get(name));
+      return (value == null || value.isEmpty() ? defaultValue : value);
+   }
+
+
+
+   /*******************************************************************************
+    ** An integer setting.
+    *******************************************************************************/
+   public Integer integer(String name, Integer defaultValue)
+   {
+      Integer value = ValueUtils.getValueAsInteger(values.get(name));
+      return (value == null ? defaultValue : value);
+   }
+
+
+
+   /*******************************************************************************
+    ** A long setting.
+    *******************************************************************************/
+   public Long longValue(String name, Long defaultValue)
+   {
+      Long value = ValueUtils.getValueAsLong(values.get(name));
+      return (value == null ? defaultValue : value);
+   }
+
+
+
+   /*******************************************************************************
+    ** A boolean setting.
+    *******************************************************************************/
+   public boolean bool(String name, boolean defaultValue)
+   {
+      Boolean value = ValueUtils.getValueAsBoolean(values.get(name));
+      return (value == null ? defaultValue : value);
+   }
+
+
+
+   /*******************************************************************************
+    ** The roles a plan includes by default (comma separated).
+    *******************************************************************************/
+   public List<TableRole> includeRoles()
+   {
+      String csv = string("includeRoles", "DATA,AUDIT");
+      return (java.util.Arrays.stream(csv.split(",")).map(String::trim).filter(s -> !s.isEmpty()).map(TableRole::valueOf).toList());
+   }
+
+
+
+   /*******************************************************************************
+    ** The plan key (slug used in object keys).
+    *******************************************************************************/
+   public String planKey()
+   {
+      return (string("planKey", "adhoc"));
+   }
+
+
+
+   /*******************************************************************************
+    ** The scope type.
+    *******************************************************************************/
+   public String scopeType()
+   {
+      return (string("scopeType", "INSTANCE"));
+   }
+
+
+
+   /*******************************************************************************
+    ** The format.
+    *******************************************************************************/
+   public String format()
+   {
+      return (string("format", "JSONL"));
+   }
+
+
+
+   /*******************************************************************************
+    ** The compression.
+    *******************************************************************************/
+   public String compression()
+   {
+      return (string("compression", "GZIP"));
+   }
+
+
+
+   /*******************************************************************************
+    ** The file object policy: COPY (default) or REFERENCE_ONLY.
+    *******************************************************************************/
+   public String fileObjectPolicy()
+   {
+      return (string("fileObjectPolicy", "COPY"));
+   }
+
+
+
+   /*******************************************************************************
+    ** The page size.
+    *******************************************************************************/
+   public int pageSize()
+   {
+      return (integer("pageSize", 5000));
+   }
+
+
+
+   /*******************************************************************************
+    ** Target part size in bytes.
+    *******************************************************************************/
+   public long targetPartBytes()
+   {
+      return (longValue("targetPartBytes", 268435456L));
+   }
+
+
+
+   /*******************************************************************************
+    ** The settings as a map (for the manifest; contains no secrets by design).
+    *******************************************************************************/
+   public Map<String, Serializable> manifestSettings()
+   {
+      Map<String, Serializable> map = new LinkedHashMap<>();
+      for(String key : List.of("scopeType", "includeRoles", "format", "compression", "encryptionMode", "sensitiveFieldPolicy", "heavyFieldPolicy",
+         "fileObjectPolicy", "fileMissingPolicy", "consistency", "incrementalMode", "pageSize", "targetPartBytes"))
+      {
+         if(values.get(key) != null)
+         {
+            map.put(key, values.get(key));
+         }
+      }
+      return (map);
+   }
+}

src/main/java/com/kingsrook/qbits/backups/scope/ScopeResolver.java

@@ -0,0 +1,448 @@
+/*
+ * 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.scope;
+
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.TreeMap;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.joins.JoinType;
+import com.kingsrook.qqq.backend.core.model.metadata.joins.QJoinMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppChildMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource;
+import com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSourceType;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.Association;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** Turns a plan (scope type, included roles, scope rows) into the ordered list of
+ ** tables a run will back up (spec 4.2).
+ **
+ ** Resolution: start from the scope type and roles, apply the INCLUDE rows, then
+ ** the EXCLUDE rows, add associated children, and drop SECRET and BACKUPS tables.
+ ** Tables are ordered parents first, using associations, joins and table-backed
+ ** possible values.  Every table that was left out is reported with its reason.
+ *******************************************************************************/
+public class ScopeResolver
+{
+   private final QInstance qInstance;
+
+
+
+   /*******************************************************************************
+    ** Constructor.
+    *******************************************************************************/
+   public ScopeResolver(QInstance qInstance)
+   {
+      this.qInstance = qInstance;
+   }
+
+
+
+   /***************************************************************************
+    ** One scope row.
+    **
+    ** @param include true for INCLUDE, false for EXCLUDE
+    ** @param selectorType TABLE, APP, QBIT or ROLE
+    ** @param selectorValue the table, app, qbit or role
+    ** @param filterJson optional QQueryFilter json (TABLE only)
+    ** @param includeAssociatedChildren also include tables reachable through associations
+    ** @param fieldExclusions comma separated field names to leave out
+    ***************************************************************************/
+   public record ScopeRule(boolean include, String selectorType, String selectorValue, String filterJson, boolean includeAssociatedChildren, String fieldExclusions)
+   {
+   }
+
+
+
+   /***************************************************************************
+    ** One table that will be backed up.
+    ***************************************************************************/
+   public record ResolvedTable(String name, TableRole role, String filterJson, List<String> excludedFields)
+   {
+   }
+
+
+
+   /***************************************************************************
+    ** A table that was left out, and why.
+    ***************************************************************************/
+   public record ExcludedTable(String name, String reason)
+   {
+   }
+
+
+
+   /***************************************************************************
+    ** The outcome of resolving a scope.
+    **
+    ** @param tables the tables, parents first
+    ** @param excluded tables left out, by reason
+    ** @param cyclic tables that could not be ordered (reference cycle), in name order at the end
+    ***************************************************************************/
+   public record ResolvedScope(List<ResolvedTable> tables, List<ExcludedTable> excluded, List<String> cyclic)
+   {
+      /*******************************************************************************
+       ** The table names, in restore order.
+       *******************************************************************************/
+      public List<String> names()
+      {
+         return (tables.stream().map(ResolvedTable::name).toList());
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Resolve a scope.
+    *******************************************************************************/
+   public ResolvedScope resolve(PlanSettings settings, List<ScopeRule> rules)
+   {
+      List<TableRole> roles = settings.includeRoles();
+
+      Set<String>         selected  = new LinkedHashSet<>();
+      Set<String>         explicit  = new LinkedHashSet<>();
+      Map<String, String> filters   = new LinkedHashMap<>();
+      Map<String, String> fieldsOut = new LinkedHashMap<>();
+      Set<String>         expandChildrenFor = new LinkedHashSet<>();
+
+      if("INSTANCE".equals(settings.scopeType()))
+      {
+         for(QTableMetaData table : sortedTables())
+         {
+            if(roles.contains(TableRoles.roleOf(qInstance, table)))
+            {
+               selected.add(table.getName());
+            }
+         }
+      }
+
+      for(ScopeRule rule : rules)
+      {
+         if(!rule.include())
+         {
+            continue;
+         }
+         for(String name : tablesFor(rule, roles))
+         {
+            selected.add(name);
+            if("TABLE".equals(rule.selectorType()))
+            {
+               explicit.add(name);
+               if(rule.filterJson() != null && !rule.filterJson().isBlank())
+               {
+                  filters.put(name, rule.filterJson());
+               }
+               if(rule.fieldExclusions() != null && !rule.fieldExclusions().isBlank())
+               {
+                  fieldsOut.put(name, rule.fieldExclusions());
+               }
+            }
+            if(rule.includeAssociatedChildren())
+            {
+               expandChildrenFor.add(name);
+            }
+         }
+      }
+
+      for(ScopeRule rule : rules)
+      {
+         if(rule.include())
+         {
+            continue;
+         }
+         for(String name : tablesFor(rule, List.of(TableRole.values())))
+         {
+            selected.remove(name);
+            explicit.remove(name);
+         }
+      }
+
+      for(String name : new ArrayList<>(expandChildrenFor))
+      {
+         addAssociatedChildren(name, selected);
+      }
+
+      List<ExcludedTable> excluded = new ArrayList<>();
+      List<String>        kept     = new ArrayList<>();
+      for(String name : selected)
+      {
+         QTableMetaData table = qInstance.getTable(name);
+         if(table == null)
+         {
+            excluded.add(new ExcludedTable(name, "NOT_FOUND"));
+            continue;
+         }
+         TableRole role = TableRoles.roleOf(qInstance, table);
+         if(role == TableRole.SECRET)
+         {
+            excluded.add(new ExcludedTable(name, "SECRET"));
+         }
+         else if(role == TableRole.BACKUPS)
+         {
+            excluded.add(new ExcludedTable(name, "BACKUPS"));
+         }
+         else if((role == TableRole.EPHEMERAL || role == TableRole.DERIVED || role == TableRole.EXTERNAL) && !explicit.contains(name) && !roles.contains(role))
+         {
+            excluded.add(new ExcludedTable(name, role.name()));
+         }
+         else
+         {
+            kept.add(name);
+         }
+      }
+
+      List<String> cyclic  = new ArrayList<>();
+      List<String> ordered = order(kept, cyclic);
+
+      List<ResolvedTable> tables = new ArrayList<>();
+      for(String name : ordered)
+      {
+         List<String> out = new ArrayList<>();
+         if(fieldsOut.get(name) != null)
+         {
+            for(String field : fieldsOut.get(name).split(","))
+            {
+               if(!field.isBlank())
+               {
+                  out.add(field.trim());
+               }
+            }
+         }
+         tables.add(new ResolvedTable(name, TableRoles.roleOf(qInstance, qInstance.getTable(name)), filters.get(name), out));
+      }
+      return (new ResolvedScope(tables, excluded, cyclic));
+   }
+
+
+
+   /*******************************************************************************
+    ** The tables a rule selects.
+    *******************************************************************************/
+   private Collection<String> tablesFor(ScopeRule rule, List<TableRole> rolesForExpansion)
+   {
+      Set<String> names = new LinkedHashSet<>();
+      switch(rule.selectorType())
+      {
+         case "TABLE" -> names.add(rule.selectorValue());
+         case "ROLE" ->
+         {
+            TableRole role = TableRole.valueOf(rule.selectorValue());
+            for(QTableMetaData table : sortedTables())
+            {
+               if(TableRoles.roleOf(qInstance, table) == role)
+               {
+                  names.add(table.getName());
+               }
+            }
+         }
+         case "QBIT" ->
+         {
+            for(QTableMetaData table : sortedTables())
+            {
+               if(rule.selectorValue().equals(table.getSourceQBitName()) && rolesForExpansion.contains(TableRoles.roleOf(qInstance, table)))
+               {
+                  names.add(table.getName());
+               }
+            }
+         }
+         case "APP" ->
+         {
+            QAppMetaData app = qInstance.getApp(rule.selectorValue());
+            if(app != null)
+            {
+               Set<String> inApp = new LinkedHashSet<>();
+               collectAppTables(app, inApp, new LinkedHashSet<>());
+               for(String name : inApp)
+               {
+                  QTableMetaData table = qInstance.getTable(name);
+                  if(table != null && rolesForExpansion.contains(TableRoles.roleOf(qInstance, table)))
+                  {
+                     names.add(name);
+                  }
+               }
+            }
+         }
+         default ->
+         {
+         }
+      }
+      return (names);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void collectAppTables(QAppMetaData app, Set<String> tables, Set<String> seenApps)
+   {
+      if(!seenApps.add(app.getName()))
+      {
+         return;
+      }
+      for(QAppChildMetaData child : app.getChildren() == null ? List.<QAppChildMetaData>of() : app.getChildren())
+      {
+         if(child instanceof QAppMetaData childApp)
+         {
+            collectAppTables(childApp, tables, seenApps);
+         }
+         else if(child instanceof QTableMetaData table)
+         {
+            tables.add(table.getName());
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private void addAssociatedChildren(String name, Set<String> selected)
+   {
+      QTableMetaData table = qInstance.getTable(name);
+      if(table == null || table.getAssociations() == null)
+      {
+         return;
+      }
+      for(Association association : table.getAssociations())
+      {
+         if(selected.add(association.getAssociatedTableName()))
+         {
+            addAssociatedChildren(association.getAssociatedTableName(), selected);
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private List<QTableMetaData> sortedTables()
+   {
+      return (new ArrayList<>(new TreeMap<>(qInstance.getTables()).values()));
+   }
+
+
+
+   /*******************************************************************************
+    ** The tables that must be restored before the given table (its parents).
+    *******************************************************************************/
+   Set<String> parentsOf(String name, Set<String> universe)
+   {
+      Set<String>    parents = new LinkedHashSet<>();
+      QTableMetaData table   = qInstance.getTable(name);
+
+      for(QTableMetaData other : qInstance.getTables().values())
+      {
+         if(other.getAssociations() != null)
+         {
+            for(Association association : other.getAssociations())
+            {
+               if(name.equals(association.getAssociatedTableName()))
+               {
+                  parents.add(other.getName());
+               }
+            }
+         }
+      }
+
+      for(QJoinMetaData join : qInstance.getJoins().values())
+      {
+         if(join.getType() == JoinType.MANY_TO_ONE && name.equals(join.getLeftTable()))
+         {
+            parents.add(join.getRightTable());
+         }
+         else if(join.getType() == JoinType.ONE_TO_MANY && name.equals(join.getRightTable()))
+         {
+            parents.add(join.getLeftTable());
+         }
+      }
+
+      for(QFieldMetaData field : table.getFields().values())
+      {
+         if(field.getPossibleValueSourceName() != null)
+         {
+            QPossibleValueSource pvs = qInstance.getPossibleValueSource(field.getPossibleValueSourceName());
+            if(pvs != null && pvs.getType() == QPossibleValueSourceType.TABLE && pvs.getTableName() != null)
+            {
+               parents.add(pvs.getTableName());
+            }
+         }
+      }
+
+      parents.remove(name);
+      parents.retainAll(universe);
+      return (parents);
+   }
+
+
+
+   /*******************************************************************************
+    ** Topological order, parents first, stable by name.  Tables in a reference cycle
+    ** are appended in name order and reported through the cyclic list.
+    *******************************************************************************/
+   List<String> order(List<String> names, List<String> cyclic)
+   {
+      Set<String>              universe  = new LinkedHashSet<>(names);
+      Map<String, Set<String>> remaining = new TreeMap<>();
+      for(String name : names)
+      {
+         remaining.put(name, parentsOf(name, universe));
+      }
+
+      List<String> ordered = new ArrayList<>();
+      while(!remaining.isEmpty())
+      {
+         List<String> ready = new ArrayList<>();
+         for(Map.Entry<String, Set<String>> entry : remaining.entrySet())
+         {
+            if(entry.getValue().isEmpty())
+            {
+               ready.add(entry.getKey());
+            }
+         }
+         if(ready.isEmpty())
+         {
+            cyclic.addAll(remaining.keySet());
+            ordered.addAll(remaining.keySet());
+            break;
+         }
+         for(String name : ready)
+         {
+            ordered.add(name);
+            remaining.remove(name);
+         }
+         for(Set<String> parents : remaining.values())
+         {
+            parents.removeAll(ready);
+         }
+      }
+      return (ordered);
+   }
+}

src/main/java/com/kingsrook/qbits/backups/scope/TableRole.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.scope;
+
+
+/*******************************************************************************
+ ** What a table is for, as far as backups are concerned (spec 3.2).  Plans select
+ ** tables by role.
+ *******************************************************************************/
+public enum TableRole
+{
+   /** Business data (included by default). */
+   DATA,
+   /** Audit tables (included by default, configurable). */
+   AUDIT,
+   /** Rebuildable from other data: search indexes, rollups, caches. Excluded by default. */
+   DERIVED,
+   /** Sessions, idempotency keys, scheduler internals. Excluded by default. */
+   EPHEMERAL,
+   /** Tokens, salts, credentials. NEVER backed up, even when selected explicitly. */
+   SECRET,
+   /** The tables of this qbit: the catalog is rebuilt from manifests. */
+   BACKUPS,
+   /** Tables backed by another system (API). Excluded by default; selectable. */
+   EXTERNAL
+}

src/main/java/com/kingsrook/qbits/backups/scope/TableRoles.java

@@ -0,0 +1,130 @@
+/*
+ * 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.scope;
+
+
+import java.util.Set;
+import com.kingsrook.qbits.backups.BackupsQBitConfig;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+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.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** Works out the backup role of a table: the declared role when there is one,
+ ** else inferred by the rules of spec 3.2.
+ *******************************************************************************/
+public final class TableRoles
+{
+   private static final Set<String> AUDIT_TABLES = Set.of("audit", "auditTable", "auditUser", "auditDetail");
+
+   private static final String[] SECRET_NAME_HINTS = { "refreshToken", "RefreshToken", "oauthToken", "OAuthToken", "apiKey" };
+
+   private static final String[] EPHEMERAL_NAME_PREFIXES = { "qrtz_" };
+   private static final String[] EPHEMERAL_NAME_PARTS    = { "Session", "Idempotency", "RedirectState", "AsyncJob" };
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private TableRoles()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** The role of a table.
+    *******************************************************************************/
+   public static TableRole roleOf(QInstance qInstance, QTableMetaData table)
+   {
+      BackupTableMetaData declared = BackupTableMetaData.of(table);
+      if(declared != null && declared.getRole() != null)
+      {
+         return (declared.getRole());
+      }
+
+      String name = table.getName();
+      if(name.startsWith(BackupsQBitConfig.TABLE_NAME_PREFIX))
+      {
+         return (TableRole.BACKUPS);
+      }
+      for(String hint : SECRET_NAME_HINTS)
+      {
+         if(name.contains(hint))
+         {
+            return (TableRole.SECRET);
+         }
+      }
+      if(isHiddenWithSecretFields(table))
+      {
+         return (TableRole.SECRET);
+      }
+      if(AUDIT_TABLES.contains(name))
+      {
+         return (TableRole.AUDIT);
+      }
+      if(table.getCacheOf() != null)
+      {
+         return (TableRole.DERIVED);
+      }
+      for(String prefix : EPHEMERAL_NAME_PREFIXES)
+      {
+         if(name.startsWith(prefix))
+         {
+            return (TableRole.EPHEMERAL);
+         }
+      }
+      for(String part : EPHEMERAL_NAME_PARTS)
+      {
+         if(name.contains(part) || name.toLowerCase().contains(part.toLowerCase()))
+         {
+            return (TableRole.EPHEMERAL);
+         }
+      }
+      if(qInstance != null && table.getBackendName() != null && qInstance.getBackend(table.getBackendName()) != null
+         && "api".equalsIgnoreCase(qInstance.getBackend(table.getBackendName()).getBackendType()))
+      {
+         return (TableRole.EXTERNAL);
+      }
+      return (TableRole.DATA);
+   }
+
+
+
+   /*******************************************************************************
+    ** A table that is hidden and has a password or sensitive field (other than the
+    ** keys and dates) is treated as a table of secrets.
+    *******************************************************************************/
+   static boolean isHiddenWithSecretFields(QTableMetaData table)
+   {
+      if(!table.getIsHidden())
+      {
+         return (false);
+      }
+      for(QFieldMetaData field : table.getFields().values())
+      {
+         if(field.getType() == QFieldType.PASSWORD || field.getIsSensitive())
+         {
+            return (true);
+         }
+      }
+      return (false);
+   }
+}

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/storage/BackupStorage.java

@@ -0,0 +1,107 @@
+/*
+ * 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.storage;
+
+
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.time.Duration;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+
+
+/*******************************************************************************
+ ** The narrow storage API that the Backups qbit needs.  It mirrors the
+ ** qbit-object-storage bucket API (put, get, head, list, copy, delete, presign),
+ ** so the production implementation is a thin adapter over a StorageBucket, and
+ ** tests use InMemoryBackupStorage.  Keys are relative to the bucket.
+ **
+ ** All methods throw BackupStorageException (a RuntimeException) on failure.
+ *******************************************************************************/
+public interface BackupStorage
+{
+
+   /***************************************************************************
+    ** Open a stream to write an object of unknown length.  The object becomes
+    ** visible when the stream is closed successfully.
+    ***************************************************************************/
+   OutputStream openWrite(String key, WriteOptions options);
+
+
+   /***************************************************************************
+    ** Open a stream over an object.
+    ***************************************************************************/
+   InputStream openRead(String key);
+
+
+   /***************************************************************************
+    ** Existence and size.
+    ***************************************************************************/
+   Optional<StoredObjectInfo> head(String key);
+
+
+   /***************************************************************************
+    ** All objects with the given key prefix (recursive, in key order).
+    ***************************************************************************/
+   List<StoredObjectInfo> list(String prefix);
+
+
+   /***************************************************************************
+    ** Server-side copy within the same bucket (or connection).
+    ***************************************************************************/
+   void copy(String sourceKey, String destinationKey);
+
+
+   /***************************************************************************
+    ** Permanently delete an object, every version.  Object-locked objects are
+    ** not deleted (DeleteResult.LOCKED); a missing object is NOT_FOUND.
+    ***************************************************************************/
+   DeleteResult deletePermanent(String key);
+
+
+   /***************************************************************************
+    ** A time-limited download link.
+    ***************************************************************************/
+   String presignGet(String key, Duration ttl, String downloadName);
+
+
+   /***************************************************************************
+    ** What the bucket can do (object lock, server-side copy, ...).
+    ***************************************************************************/
+   Set<StorageCapability> capabilities();
+
+
+
+   /***************************************************************************
+    ** Result of a permanent delete.
+    ***************************************************************************/
+   enum DeleteResult
+   {
+      DELETED, NOT_FOUND, LOCKED
+   }
+
+
+
+   /***************************************************************************
+    ** Capabilities, as probed by the storage qbit.
+    ***************************************************************************/
+   enum StorageCapability
+   {
+      OBJECT_LOCK, VERSIONING, SERVER_SIDE_COPY, MULTIPART
+   }
+}

src/main/java/com/kingsrook/qbits/backups/storage/BackupStorageException.java

@@ -0,0 +1,69 @@
+/*
+ * 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.storage;
+
+
+/*******************************************************************************
+ ** A storage failure, with a reason that mirrors the StorageException reasons
+ ** of the object-storage qbit.
+ *******************************************************************************/
+public class BackupStorageException extends RuntimeException
+{
+   private final Reason reason;
+
+
+
+   /*******************************************************************************
+    ** Constructor.
+    *******************************************************************************/
+   public BackupStorageException(Reason reason, String message)
+   {
+      super(message);
+      this.reason = reason;
+   }
+
+
+
+   /*******************************************************************************
+    ** Constructor with a cause.
+    *******************************************************************************/
+   public BackupStorageException(Reason reason, String message, Throwable cause)
+   {
+      super(message, cause);
+      this.reason = reason;
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for reason
+    *******************************************************************************/
+   public Reason getReason()
+   {
+      return (reason);
+   }
+
+
+
+   /***************************************************************************
+    ** Failure reasons.
+    ***************************************************************************/
+   public enum Reason
+   {
+      NOT_FOUND, ACCESS_DENIED, UNSUPPORTED, PRECONDITION_FAILED, THROTTLED, PROVIDER_ERROR
+   }
+}

src/main/java/com/kingsrook/qbits/backups/storage/InMemoryBackupStorage.java

@@ -0,0 +1,300 @@
+/*
+ * 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.storage;
+
+
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.time.Clock;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.EnumSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+import java.util.TreeMap;
+import java.util.function.Predicate;
+
+
+/*******************************************************************************
+ ** A BackupStorage held in memory.  It is the test implementation and a
+ ** stand-in for local development.  It supports object lock, and has hooks for
+ ** failure injection (a predicate over keys that makes a write fail).
+ *******************************************************************************/
+public class InMemoryBackupStorage implements BackupStorage
+{
+   private final TreeMap<String, Entry> objects = new TreeMap<>();
+
+   private Clock                  clock = Clock.systemUTC();
+   private Predicate<String>      failWritesFor;
+   private Set<StorageCapability> capabilities = EnumSet.of(StorageCapability.OBJECT_LOCK, StorageCapability.SERVER_SIDE_COPY, StorageCapability.MULTIPART);
+
+   private record Entry(byte[] bytes, Map<String, String> metadata, Instant lastModified, Instant lockedUntil)
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Use a fixed clock (for object lock and last modified in tests).
+    *******************************************************************************/
+   public InMemoryBackupStorage withClock(Clock clock)
+   {
+      this.clock = clock;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Make writes of matching keys fail with a provider error (failure injection).
+    *******************************************************************************/
+   public InMemoryBackupStorage withFailWritesFor(Predicate<String> failWritesFor)
+   {
+      this.failWritesFor = failWritesFor;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Set the capabilities this storage reports.
+    *******************************************************************************/
+   public InMemoryBackupStorage withCapabilities(Set<StorageCapability> capabilities)
+   {
+      this.capabilities = capabilities;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Test helper: remove everything.
+    *******************************************************************************/
+   public synchronized void clear()
+   {
+      objects.clear();
+      failWritesFor = null;
+   }
+
+
+
+   /*******************************************************************************
+    ** Test helper: put bytes directly.
+    *******************************************************************************/
+   public synchronized void putBytes(String key, byte[] bytes)
+   {
+      objects.put(key, new Entry(bytes, new LinkedHashMap<>(), clock.instant(), null));
+   }
+
+
+
+   /*******************************************************************************
+    ** Test helper: read bytes directly.
+    *******************************************************************************/
+   public synchronized byte[] getBytes(String key)
+   {
+      Entry entry = objects.get(key);
+      return (entry == null ? null : entry.bytes());
+   }
+
+
+
+   /*******************************************************************************
+    ** Test helper: remove an object ignoring any lock (simulating an out-of-band delete).
+    *******************************************************************************/
+   public synchronized void removeIgnoringLock(String key)
+   {
+      objects.remove(key);
+   }
+
+
+
+   /*******************************************************************************
+    ** Test helper: replace an object bytes (simulating corruption).
+    *******************************************************************************/
+   public synchronized void corrupt(String key, byte[] bytes)
+   {
+      Entry old = objects.get(key);
+      objects.put(key, new Entry(bytes, old == null ? new LinkedHashMap<>() : old.metadata(), clock.instant(), old == null ? null : old.lockedUntil()));
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public OutputStream openWrite(String key, WriteOptions options)
+   {
+      if(failWritesFor != null && failWritesFor.test(key))
+      {
+         throw (new BackupStorageException(BackupStorageException.Reason.PROVIDER_ERROR, "injected write failure for " + key));
+      }
+      if(options.getObjectLockMode() != null && !capabilities.contains(StorageCapability.OBJECT_LOCK))
+      {
+         throw (new BackupStorageException(BackupStorageException.Reason.UNSUPPORTED, "object lock is not supported"));
+      }
+
+      return (new ByteArrayOutputStream()
+      {
+         private boolean closed = false;
+
+
+
+         /*******************************************************************************
+          ** commit on close
+          *******************************************************************************/
+         @Override
+         public void close() throws IOException
+         {
+            super.close();
+            if(!closed)
+            {
+               closed = true;
+               synchronized(InMemoryBackupStorage.this)
+               {
+                  objects.put(key, new Entry(toByteArray(), new LinkedHashMap<>(options.getMetadata()), clock.instant(), options.getRetainUntil()));
+               }
+            }
+         }
+      });
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public synchronized InputStream openRead(String key)
+   {
+      Entry entry = objects.get(key);
+      if(entry == null)
+      {
+         throw (new BackupStorageException(BackupStorageException.Reason.NOT_FOUND, "no such object: " + key));
+      }
+      return (new ByteArrayInputStream(entry.bytes()));
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public synchronized Optional<StoredObjectInfo> head(String key)
+   {
+      Entry entry = objects.get(key);
+      return (entry == null ? Optional.empty() : Optional.of(info(key, entry)));
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public synchronized List<StoredObjectInfo> list(String prefix)
+   {
+      List<StoredObjectInfo> rs = new ArrayList<>();
+      for(Map.Entry<String, Entry> e : objects.tailMap(prefix == null ? "" : prefix).entrySet())
+      {
+         if(prefix != null && !e.getKey().startsWith(prefix))
+         {
+            break;
+         }
+         rs.add(info(e.getKey(), e.getValue()));
+      }
+      return (rs);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public synchronized void copy(String sourceKey, String destinationKey)
+   {
+      Entry entry = objects.get(sourceKey);
+      if(entry == null)
+      {
+         throw (new BackupStorageException(BackupStorageException.Reason.NOT_FOUND, "no such object: " + sourceKey));
+      }
+      objects.put(destinationKey, new Entry(entry.bytes(), entry.metadata(), clock.instant(), null));
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public synchronized DeleteResult deletePermanent(String key)
+   {
+      Entry entry = objects.get(key);
+      if(entry == null)
+      {
+         return (DeleteResult.NOT_FOUND);
+      }
+      if(entry.lockedUntil() != null && entry.lockedUntil().isAfter(clock.instant()))
+      {
+         return (DeleteResult.LOCKED);
+      }
+      objects.remove(key);
+      return (DeleteResult.DELETED);
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public String presignGet(String key, Duration ttl, String downloadName)
+   {
+      return ("memory://" + key + "?ttl=" + ttl.toSeconds());
+   }
+
+
+
+   /*******************************************************************************
+    ** {@inheritDoc}
+    *******************************************************************************/
+   @Override
+   public Set<StorageCapability> capabilities()
+   {
+      return (capabilities);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private StoredObjectInfo info(String key, Entry entry)
+   {
+      return (new StoredObjectInfo(key, entry.bytes().length, entry.lastModified(), entry.metadata(), entry.lockedUntil()));
+   }
+}

src/main/java/com/kingsrook/qbits/backups/storage/StoredObjectInfo.java

@@ -0,0 +1,35 @@
+/*
+ * 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.storage;
+
+
+import java.time.Instant;
+import java.util.Map;
+
+
+/*******************************************************************************
+ ** What the bucket says about one object.
+ **
+ ** @param key key relative to the bucket
+ ** @param size size in bytes
+ ** @param lastModified last modified instant (may be null)
+ ** @param metadata user metadata
+ ** @param lockedUntil object-lock retain-until, or null
+ *******************************************************************************/
+public record StoredObjectInfo(String key, long size, Instant lastModified, Map<String, String> metadata, Instant lockedUntil)
+{
+}

src/main/java/com/kingsrook/qbits/backups/storage/WriteOptions.java

@@ -0,0 +1,118 @@
+/*
+ * 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.storage;
+
+
+import java.time.Instant;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+
+/*******************************************************************************
+ ** Options for writing one object.
+ *******************************************************************************/
+public class WriteOptions
+{
+   private String              contentType = "application/octet-stream";
+   private Map<String, String> metadata    = new LinkedHashMap<>();
+   private String              objectLockMode;
+   private Instant             retainUntil;
+
+
+
+   /*******************************************************************************
+    ** Start with defaults.
+    *******************************************************************************/
+   public static WriteOptions create()
+   {
+      return (new WriteOptions());
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for contentType
+    *******************************************************************************/
+   public String getContentType()
+   {
+      return (contentType);
+   }
+
+
+
+   /*******************************************************************************
+    ** Fluent setter for contentType
+    *******************************************************************************/
+   public WriteOptions withContentType(String contentType)
+   {
+      this.contentType = contentType;
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for metadata (user metadata, which describes the object even without the catalog)
+    *******************************************************************************/
+   public Map<String, String> getMetadata()
+   {
+      return (metadata);
+   }
+
+
+
+   /*******************************************************************************
+    ** Add one metadata entry.
+    *******************************************************************************/
+   public WriteOptions withMetadata(String key, String value)
+   {
+      this.metadata.put(key, value);
+      return (this);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for objectLockMode (GOVERNANCE or COMPLIANCE), null for none
+    *******************************************************************************/
+   public String getObjectLockMode()
+   {
+      return (objectLockMode);
+   }
+
+
+
+   /*******************************************************************************
+    ** Getter for retainUntil
+    *******************************************************************************/
+   public Instant getRetainUntil()
+   {
+      return (retainUntil);
+   }
+
+
+
+   /*******************************************************************************
+    ** Request an object lock on the written object.
+    *******************************************************************************/
+   public WriteOptions withObjectLock(String mode, Instant retainUntil)
+   {
+      this.objectLockMode = mode;
+      this.retainUntil = retainUntil;
+      return (this);
+   }
+}

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/BackupsTestUtils.java

@@ -0,0 +1,168 @@
+/*
+ * 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.Serializable;
+import java.math.BigDecimal;
+import java.time.Instant;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.backups.scope.BackupTableMetaData;
+import com.kingsrook.qbits.backups.storage.BackupStorage;
+import com.kingsrook.qbits.backups.storage.InMemoryBackupStorage;
+import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.instances.QInstanceValidator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+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.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
+import com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryBackendModule;
+import com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryRecordStore;
+
+
+/*******************************************************************************
+ ** Test fixtures: an instance on the memory backend with the Backups qbit and a
+ ** small blog app (authors, posts with a media file key, an ephemeral table).
+ *******************************************************************************/
+public final class BackupsTestUtils
+{
+   public static final String BACKEND = "memory";
+
+   public static final InMemoryBackupStorage BACKUPS = new InMemoryBackupStorage();
+   public static final InMemoryBackupStorage MEDIA   = new InMemoryBackupStorage();
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private BackupsTestUtils()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Build the instance, install the qbit, and initialize the context.
+    *******************************************************************************/
+   public static QInstance init() throws Exception
+   {
+      BackupsRuntime.reset();
+      MemoryRecordStore.getInstance().reset();
+      BACKUPS.clear();
+      MEDIA.clear();
+
+      QInstance qInstance = new QInstance();
+      qInstance.withInstanceDefaultAuthentication(new com.kingsrook.qqq.backend.core.model.metadata.authentication.QAuthenticationMetaData().withType(com.kingsrook.qqq.backend.core.model.metadata.QAuthenticationType.FULLY_ANONYMOUS).withName("anon"));
+      qInstance.addBackend(new QBackendMetaData().withName(BACKEND).withBackendType(MemoryBackendModule.class));
+
+      qInstance.addTable(new QTableMetaData().withName("author").withBackendName(BACKEND).withPrimaryKeyField("id")
+         .withField(new QFieldMetaData("id", QFieldType.INTEGER))
+         .withField(new QFieldMetaData("name", QFieldType.STRING))
+         .withField(new QFieldMetaData("bio", QFieldType.TEXT)));
+
+      qInstance.addTable(new QTableMetaData().withName("blogPost").withBackendName(BACKEND).withPrimaryKeyField("id")
+         .withField(new QFieldMetaData("id", QFieldType.INTEGER))
+         .withField(new QFieldMetaData("authorId", QFieldType.INTEGER).withPossibleValueSourceName("author"))
+         .withField(new QFieldMetaData("title", QFieldType.STRING))
+         .withField(new QFieldMetaData("body", QFieldType.TEXT))
+         .withField(new QFieldMetaData("price", QFieldType.DECIMAL))
+         .withField(new QFieldMetaData("published", QFieldType.BOOLEAN))
+         .withField(new QFieldMetaData("publishedOn", QFieldType.DATE))
+         .withField(new QFieldMetaData("createDate", QFieldType.DATE_TIME))
+         .withField(new QFieldMetaData("mediaKey", QFieldType.STRING))
+         .withField(new QFieldMetaData("secretNote", QFieldType.STRING).withIsSensitive(true))
+         .withSupplementalMetaData(new BackupTableMetaData().withFileReferenceFields(List.of("mediaKey")).withFileBucketAlias("media")));
+      qInstance.addPossibleValueSource(com.kingsrook.qqq.backend.core.model.metadata.possiblevalues.QPossibleValueSource.newForTable("author"));
+
+      qInstance.addTable(new QTableMetaData().withName("userSession").withBackendName(BACKEND).withPrimaryKeyField("id")
+         .withField(new QFieldMetaData("id", QFieldType.INTEGER))
+         .withField(new QFieldMetaData("token", QFieldType.STRING)));
+
+      Map<String, BackupStorage> buckets = Map.of("backups", BACKUPS, "media", MEDIA);
+      BackupsQBitConfig config = new BackupsQBitConfig().withBackendName(BACKEND).withInstanceName("testapp").withStorageResolver(buckets::get).withOpenWhenAnonymous(true);
+      new BackupsQBitProducer().withQBitConfig(config).withNamespace("backups").produce(qInstance);
+
+      new QInstanceValidator().validate(qInstance);
+      QContext.init(qInstance, new QSession());
+      return (qInstance);
+   }
+
+
+
+   /*******************************************************************************
+    ** Insert rows into a table.
+    *******************************************************************************/
+   public static void insert(String table, List<Map<String, Serializable>> rows) throws QException
+   {
+      InsertInput input = new InsertInput(table);
+      input.setRecords(rows.stream().map(r ->
+      {
+         QRecord record = new QRecord();
+         record.setValues(new LinkedHashMap<>(r));
+         return (record);
+      }).toList());
+      new InsertAction().execute(input);
+   }
+
+
+
+   /*******************************************************************************
+    ** The standard blog data: 3 authors, and the posts, some with media.
+    *******************************************************************************/
+   public static void loadBlog(int posts) throws Exception
+   {
+      insert("author", List.of(
+         Map.of("id", 1, "name", "Ada", "bio", "Line one\nLine two, with \"quotes\" and unicode é中"),
+         Map.of("id", 2, "name", "Grace", "bio", ""),
+         Map.of("id", 3, "name", "Linus")));
+      List<Map<String, Serializable>> rows = new java.util.ArrayList<>();
+      for(int i = 1; i <= posts; i++)
+      {
+         Map<String, Serializable> row = new LinkedHashMap<>();
+         row.put("id", i);
+         row.put("authorId", 1 + (i % 3));
+         row.put("title", "Post " + i);
+         row.put("body", "Body of " + i + ", with a comma");
+         row.put("price", new BigDecimal("12.3400").add(BigDecimal.valueOf(i)));
+         row.put("published", i % 2 == 0);
+         row.put("publishedOn", java.time.LocalDate.of(2026, 1, 1).plusDays(i));
+         row.put("createDate", Instant.parse("2026-10-12T02:00:00.123456Z").plusSeconds(i));
+         row.put("secretNote", "do-not-leak-" + i);
+         if(i % 2 == 1)
+         {
+            String key = "media/photo-" + (i % 3) + ".jpg";
+            row.put("mediaKey", key);
+            if(MEDIA.getBytes(key) == null)
+            {
+               MEDIA.putBytes(key, ("photo bytes " + (i % 3)).getBytes());
+            }
+         }
+         rows.add(row);
+      }
+      insert("blogPost", rows);
+      insert("userSession", List.of(Map.of("id", 1, "token", "tok")));
+   }
+}

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/run/BackupEngineTest.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.run;
+
+
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+import java.util.Map;
+import java.util.zip.GZIPInputStream;
+import com.kingsrook.qbits.backups.BackupsTestUtils;
+import com.kingsrook.qbits.backups.manifest.BackupManifest;
+import com.kingsrook.qbits.backups.model.BackupsTables;
+import com.kingsrook.qbits.backups.scope.PlanSettings;
+import com.kingsrook.qbits.backups.scope.ScopeResolver;
+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 org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** End to end tests of a backup run on the memory backend: layout, manifest last,
+ ** canonical rows, policies, file copy and deduplication, failure handling.
+ *******************************************************************************/
+class BackupEngineTest
+{
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @BeforeEach
+   void setUp() throws Exception
+   {
+      BackupsTestUtils.init();
+      BackupsTestUtils.loadBlog(7);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private QRecord plan(Map<String, java.io.Serializable> overrides) throws Exception
+   {
+      Map<String, java.io.Serializable> values = new java.util.LinkedHashMap<>(Map.of("name", "Nightly", "planKey", "nightly", "isActive", true,
+         "scopeType", "INSTANCE", "storageBucketAlias", "backups", "slaHours", 26));
+      values.putAll(overrides);
+      Integer id = new BackupCatalog().insert(BackupsTables.PLAN, values);
+      return (new BackupCatalog().get(BackupsTables.PLAN, id).orElseThrow());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private BackupRunResult run(QRecord plan) throws Exception
+   {
+      return (new BackupEngine().execute(BackupRunFactory.forPlan(plan, "MANUAL")));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   static String gunzip(byte[] bytes) throws IOException
+   {
+      return (new String(new GZIPInputStream(new ByteArrayInputStream(bytes)).readAllBytes(), StandardCharsets.UTF_8));
+   }
+
+
+
+   /*******************************************************************************
+    ** A nightly run writes parts, checksums and the manifest LAST, and the manifest
+    ** matches the rows and the stored bytes.
+    *******************************************************************************/
+   @Test
+   void testRunWritesManifestAndParts() throws Exception
+   {
+      BackupRunResult result = run(plan(Map.of()));
+      assertThat(result.getStatus()).isEqualTo("SUCCEEDED_WITH_WARNINGS");
+      assertThat(result.getWarnings()).anyMatch(w -> w.contains("BEST_EFFORT"));
+      assertThat(result.isUsable()).isTrue();
+
+      BackupManifest manifest = BackupManifest.read(BackupsTestUtils.BACKUPS.getBytes(result.getManifestKey()));
+      assertThat(manifest.runKey()).isEqualTo(result.getRunKey());
+      assertThat(manifest.restoreOrder()).containsSubsequence("author", "blogPost");
+      assertThat(manifest.table("userSession")).as("ephemeral tables are not backed up").isNull();
+      assertThat(manifest.table("backups_plan")).as("the qbit own tables are not backed up").isNull();
+
+      BackupManifest.TableEntry posts = manifest.table("blogPost");
+      assertThat(posts.rowCount()).isEqualTo(7);
+      assertThat(posts.excludedFields()).extracting(BackupManifest.ExcludedField::name).containsExactly("secretNote");
+      assertThat(posts.fingerprint()).startsWith("sha256:");
+
+      BackupManifest.Part part = posts.parts().get(0);
+      byte[] stored = BackupsTestUtils.BACKUPS.getBytes(result.getRunPrefix() + part.key());
+      assertThat(com.kingsrook.qbits.backups.codec.HashingOutputStream.sha256Hex(stored)).isEqualTo(part.sha256Stored());
+      String text = gunzip(stored);
+      assertThat(text.split("\n")).hasSize(7);
+      assertThat(text).doesNotContain("do-not-leak").doesNotContain("secretNote");
+      assertThat(text.split("\n")[0]).startsWith("{\"authorId\":2,\"body\":\"Body of 1, with a comma\",\"createDate\":\"20").contains(",\"id\":1,\"mediaKey\":\"media/photo-1.jpg\",\"price\":\"13.3400\"");
+      assertThat(text).contains("\"price\":\"13.3400\"").contains("\"publishedOn\":\"2026-01-02\"");
+      assertThat(com.kingsrook.qbits.backups.codec.HashingOutputStream.sha256Hex(text.getBytes(StandardCharsets.UTF_8))).isEqualTo(part.sha256Raw());
+
+      String checksums = new String(BackupsTestUtils.BACKUPS.getBytes(result.getRunPrefix() + "checksums.sha256"), StandardCharsets.UTF_8);
+      assertThat(checksums).contains(part.sha256Stored() + "  " + part.key());
+
+      QRecord run = new BackupCatalog().get(BackupsTables.RUN, result.getRunId()).orElseThrow();
+      assertThat(run.getValueString("status")).isEqualTo("SUCCEEDED_WITH_WARNINGS");
+      assertThat(run.getValueString("manifestKey")).isEqualTo(result.getManifestKey());
+      assertThat(run.getValueLong("rowsTotal")).isEqualTo(10L);
+      assertThat(new BackupCatalog().where(BackupsTables.ARTIFACT, "backupRunId", result.getRunId())).hasSizeGreaterThanOrEqualTo(4);
+
+      QRecord plan = new BackupCatalog().where(BackupsTables.PLAN, "planKey", "nightly").get(0);
+      assertThat(plan.getValueInteger("lastSuccessRunId")).isEqualTo(result.getRunId());
+      assertThat(plan.getValueString("slaStatus")).isEqualTo("OK");
+   }
+
+
+
+   /*******************************************************************************
+    ** Referenced files are copied into the content-addressed store; the second run
+    ** copies nothing new (deduplicated), and rows referencing the same bytes share one object.
+    *******************************************************************************/
+   @Test
+   void testFilesAreCopiedThenDeduplicated() throws Exception
+   {
+      QRecord         plan  = plan(Map.of());
+      BackupRunResult first = run(plan);
+      assertThat(first.getFilesReferenced()).isEqualTo(4);
+      assertThat(first.getFilesCopied()).isEqualTo(3);
+      assertThat(first.getFilesDeduplicated()).isEqualTo(1);
+      assertThat(first.getFilesMissing()).isZero();
+
+      List<QRecord> fileObjects = new BackupCatalog().query(BackupsTables.FILE_OBJECT, new com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter());
+      assertThat(fileObjects).hasSize(3);
+      for(QRecord fileObject : fileObjects)
+      {
+         byte[] stored = BackupsTestUtils.BACKUPS.getBytes(fileObject.getValueString("objectKey"));
+         assertThat(com.kingsrook.qbits.backups.codec.HashingOutputStream.sha256Hex(stored)).isEqualTo(fileObject.getValueString("sha256"));
+         assertThat(fileObject.getValueString("objectKey")).contains("/_files/sha256/" + fileObject.getValueString("sha256").substring(0, 2) + "/");
+      }
+
+      BackupRunResult second = run(plan);
+      assertThat(second.getFilesCopied()).isZero();
+      assertThat(second.getFilesDeduplicated()).isEqualTo(4);
+      assertThat(new BackupCatalog().query(BackupsTables.FILE_OBJECT, new com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter())).hasSize(3);
+
+      String index = gunzip(BackupsTestUtils.BACKUPS.getBytes(first.getRunPrefix() + "files/index-00001.jsonl.gz"));
+      assertThat(index.split("\n")).hasSize(4);
+      assertThat(index).contains("\"status\":\"COPIED\"").contains("\"status\":\"DEDUPLICATED\"");
+   }
+
+
+
+   /*******************************************************************************
+    ** REFERENCE_ONLY records the key and size without copying; a missing source is
+    ** listed and (under WARN) the run ends with warnings.
+    *******************************************************************************/
+   @Test
+   void testReferenceOnlyAndMissingFiles() throws Exception
+   {
+      BackupRunResult refOnly = run(plan(Map.of("fileObjectPolicy", "REFERENCE_ONLY")));
+      assertThat(refOnly.getFilesCopied()).isZero();
+      assertThat(new BackupCatalog().query(BackupsTables.FILE_OBJECT, new com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter())).isEmpty();
+      assertThat(gunzip(BackupsTestUtils.BACKUPS.getBytes(refOnly.getRunPrefix() + "files/index-00001.jsonl.gz"))).contains("REFERENCE_ONLY");
+
+      BackupsTestUtils.MEDIA.removeIgnoringLock("media/photo-1.jpg");
+      BackupRunResult missing = run(new BackupCatalog().where(BackupsTables.PLAN, "planKey", "nightly").get(0));
+      assertThat(missing.getFilesMissing()).isGreaterThan(0);
+      assertThat(missing.getWarnings()).anyMatch(w -> w.contains("missing"));
+      assertThat(missing.getStatus()).isEqualTo("SUCCEEDED_WITH_WARNINGS");
+   }
+
+
+
+   /*******************************************************************************
+    ** A storage failure mid-run leaves the run FAILED with no manifest (so it is
+    ** not usable and the checker treats the prefix as debris).
+    *******************************************************************************/
+   @Test
+   void testStorageFailureLeavesNoManifest() throws Exception
+   {
+      BackupsTestUtils.BACKUPS.withFailWritesFor(key -> key.contains("/tables/blogPost/"));
+      try
+      {
+         BackupRunResult result = run(plan(Map.of()));
+         assertThat(result.getStatus()).isEqualTo("FAILED");
+         assertThat(result.isUsable()).isFalse();
+         assertThat(result.getErrorMessage()).contains("injected write failure");
+         assertThat(BackupsTestUtils.BACKUPS.list(result.getRunPrefix() + "manifest.json")).isEmpty();
+         assertThat(new BackupCatalog().get(BackupsTables.RUN, result.getRunId()).orElseThrow().getValueString("status")).isEqualTo("FAILED");
+      }
+      finally
+      {
+         BackupsTestUtils.BACKUPS.withFailWritesFor(null);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Required snapshots fail before anything is written (no backend can open one yet).
+    *******************************************************************************/
+   @Test
+   void testSnapshotRequiredFailsBeforeWriting() throws Exception
+   {
+      BackupRunResult result = run(plan(Map.of("consistency", "SNAPSHOT_REQUIRED")));
+      assertThat(result.getStatus()).isEqualTo("FAILED");
+      assertThat(BackupsTestUtils.BACKUPS.list("")).isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** CSV (and gzip) output, a page size smaller than the table (keyset paging), part
+    ** rotation by rows, and the rowsHash staying the same whatever the format.
+    *******************************************************************************/
+   @Test
+   void testCsvAndPaging() throws Exception
+   {
+      BackupRunResult jsonl = run(plan(Map.of("pageSize", 2)));
+      BackupRunResult csv   = run(plan(Map.of("name", "Csv", "planKey", "csv", "format", "CSV", "pageSize", 3)));
+
+      BackupManifest jm = BackupManifest.read(BackupsTestUtils.BACKUPS.getBytes(jsonl.getManifestKey()));
+      BackupManifest cm = BackupManifest.read(BackupsTestUtils.BACKUPS.getBytes(csv.getManifestKey()));
+      assertThat(cm.table("blogPost").rowsHash()).isEqualTo(jm.table("blogPost").rowsHash());
+      assertThat(cm.table("blogPost").parts().get(0).key()).endsWith(".csv.gz");
+
+      String text = gunzip(BackupsTestUtils.BACKUPS.getBytes(csv.getRunPrefix() + cm.table("blogPost").parts().get(0).key()));
+      List<String> records = com.kingsrook.qbits.backups.codec.CsvRowCodec.splitRecords(text);
+      assertThat(records).hasSize(8);
+      assertThat(records.get(0)).startsWith("authorId,body,createDate");
+      String authors = gunzip(BackupsTestUtils.BACKUPS.getBytes(csv.getRunPrefix() + cm.table("author").parts().get(0).key()));
+      assertThat(com.kingsrook.qbits.backups.codec.CsvRowCodec.splitRecords(authors)).hasSize(4);
+      assertThat(authors).contains("\\N").contains("\"Line one\nLine two, with \"\"quotes\"\"");
+   }
+
+
+
+   /*******************************************************************************
+    ** Scope: explicit tables with a filter and field exclusions, and SECRET never included.
+    *******************************************************************************/
+   @Test
+   void testScopeRulesFilterAndExclusions() throws Exception
+   {
+      QRecord plan = plan(Map.of("scopeType", "TABLES"));
+      new BackupCatalog().insert(BackupsTables.PLAN_SCOPE, Map.of("backupPlanId", plan.getValueInteger("id"), "action", "INCLUDE", "selectorType", "TABLE",
+         "selectorValue", "blogPost", "filterJson", "{\"criteria\":[{\"fieldName\":\"published\",\"operator\":\"EQUALS\",\"values\":[true]}]}",
+         "includeAssociatedChildren", false, "fieldExclusions", "body"));
+      BackupRunResult result = run(plan);
+      BackupManifest  m      = BackupManifest.read(BackupsTestUtils.BACKUPS.getBytes(result.getManifestKey()));
+      assertThat(m.tables()).extracting(BackupManifest.TableEntry::name).containsExactly("blogPost");
+      assertThat(m.table("blogPost").rowCount()).isEqualTo(3);
+      assertThat(m.table("blogPost").excludedFields()).extracting(BackupManifest.ExcludedField::name).contains("body", "secretNote");
+      assertThat(gunzip(BackupsTestUtils.BACKUPS.getBytes(result.getRunPrefix() + m.table("blogPost").parts().get(0).key()))).doesNotContain("\"body\"");
+
+      ScopeResolver.ResolvedScope scope = new ScopeResolver(QContext.getQInstance()).resolve(PlanSettings.adHoc().with("scopeType", "TABLES"),
+         List.of(new ScopeResolver.ScopeRule(true, "TABLE", "backups_plan", null, false, null)));
+      assertThat(scope.tables()).isEmpty();
+      assertThat(scope.excluded()).extracting(ScopeResolver.ExcludedTable::reason).containsExactly("BACKUPS");
+   }
+}

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());
+   }
+}