chore: target QQQ 4.1.0-RC.15 (UI API 1.6.0)

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

CHANGELOG.md

@@ -5,11 +5,14 @@ All notable changes to this project are documented here. The format follows Keep
 ## [0.1.0] - Unreleased
 
 ### Fixed
+- Audit noise: every monitor run (lease claim, then run result) and every reminder check wrote a "Record was Edited" audit (about 7,000 `alerts_monitor` and 1,800 `alerts_alert` audits in 6 hours on one production host, most with no field details). Engine updates that touch only bookkeeping fields (`RuntimeFields`: monitor `claimedBy`, `claimedUntil`, `lastRunAt`, `nextRunAt`, `lastStatus`, `lastValue`, `lastError`, `lastElapsedMs`, `consecutiveFailures`, `conditionSince`; alert `timedNotificationCheckedAt`, `lastNotifiedAt`, `recordRefCount`) are written with `omitDmlAudit`. Configuration edits, raises and alert state changes are audited as before, as are UI and API edits of any field.
+- Read the QBit metadata version from the Maven-filtered artifact version so release builds report their release version.
 - Record-view child lists (e.g. a notification's Recipients) failed with "Error in JSON Serialization": the child table's meta-data includes the qbit config, and `AlertsQBitConfig.getRuntime()` points at a runtime that points back at the config, so Jackson recursed to its 1000-level nesting limit. `getRuntime()` and `getAudienceResolver()` are now `@JsonIgnore`, as in the other qbits' configs. A regression test renders and serializes every child-list widget.
 
 ### Added
+- Ship the full host-neutral Alerts help bundle through QQQ 4.1.0-RC.7 core registration, replacing the temporary loader. Cover owned tables, fields, actions, jobs, widgets and possible-value sources with a bundle coverage gate; support HOST overrides and hosts without help tables.
 - Starter defaults changelog `alerts-defaults.changelog.sql` (insert-only, guarded): the `in-app` and `email` channels and the `alerts` and `other` groups, equal to what the runtime creates on first use. Tested through real Liquibase on H2.
-- Help for the Alerts app and every `alerts_*` table (`help/qbit-alerts.yaml`, STAND-IN core#1198): what the table is for and how its rows get created, shown when it is empty.
+- Help for the Alerts app and every `alerts_*` table (`help/qbit-alerts.yaml`): what the table is for and how its rows get created, shown when it is empty.
 - A Setup card first on the Alerts home (alerts admins): each configuration table, its state and the next step.
 - `AlertsTablesGuardrailTest`: every table is used by runtime code, seeded or listed as starting empty with a reason, and has help.
 
@@ -47,6 +50,7 @@ All notable changes to this project are documented here. The format follows Keep
 - Apply reminders and escalation (#27, part 2): a minute-based hidden job sends due reminders, advances ordered USER/TEAM/CHANNEL escalation steps, and caps final-step repeats. Acknowledgement, snooze, resolution and mutes stop both; reopening restarts escalation. Delivery, events and progress commit together, with a persisted same-minute checkpoint.
 - Add admin escalation policy and step tables, child step lists, and type/group policy links in guarded Liquibase changesets 23–26. Type policies override group policies. CRITICAL reminders default to 60 minutes; explicit zero turns them off.
 - Keep EXPIRED reserved and remove it from selectable resolution values because the design specifies no expiration rule.
+- Per-notification email opt-in via recipient email status `REQUESTED`: immediate delivery without a standing category preference. It still honours the category email minimum severity, the user pause (SECURITY bypasses) and quiet hours (held until they end, for up to a day), is skipped when no address is known, and is never emailed for ALERT notifications.
 - Optional external channels:
   - Slack (an Incoming Webhook, Block Kit)
   - Microsoft Teams (a Workflows webhook, an Adaptive Card)

README.md

@@ -83,7 +83,7 @@ Grant `getNotificationAdminPermissionNames()` to authors. Viewers' permissions i
 
 **Upgrading from 0.1.0-RC.1:** changeset 16 renames the delivery log `alerts_notification` to `alerts_delivery`, and changeset 17 drops `alerts_inbox_item` (bell state only). Both are guarded, so a fresh schema and an RC.1 schema both end up the same.
 
-The UI routes are published as the `alerts` extension (`1.0.0`, established prefix `/alerts`), with
+The UI routes are published as the `alerts` extension (`1.2.0`, established prefix `/alerts`), with
 [the OpenAPI fragment](src/main/resources/openapi/qqq-v1/alerts.yaml) and a contract test.
 See [UI API and webhook migration](docs/UI-API.md) for operation IDs and the complete Next handoff.
 Summary `inboxHref`, item/alert `actions`, and panel `follow.available` are additive. Existing
@@ -280,6 +280,23 @@ assigned automatically. The Resolve action continues to record MANUAL.
 - **Alertmanager sink:** open alerts are sent with an `endsAt` a week out, not re-posted.
 - **Not built yet:** Micrometer metrics, mirrored lock columns and a configurable table namespace. These are the rest of design phases P4 to P6.
 
+## In-app help
+
+The producer registers [`help/qbit-alerts.yaml`](src/main/resources/help/qbit-alerts.yaml)
+with QQQ's help-bundle registry. It covers the Alerts app, tables and fields,
+actions, scheduled jobs, widgets and possible-value sources. QQQ syncs the bundle
+when the host installs the help-content tables; registration is harmless without them.
+
+Hosts can override individual entries by registering their own bundle with
+`layer: HOST`, using the same entry `key` and `role` (default `ALL_SCREENS`).
+Register it with `HelpBundles.register(qInstance, "help/my-host.yaml")`. Host
+bundles take precedence over this `QBIT` bundle, and edits made by users remain protected.
+
+`AlertsTablesGuardrailTest` runs `HelpBundleAssertions` against the produced instance
+to check owned-object coverage, summary length and live references. It also requires
+widget and possible-value-source help and preserves the table empty-state guidance.
+When releasing, keep the bundle's literal version aligned with the POM's revision.
+
 ## Build
 
 ```bash

docs/UI-API.md

@@ -1,7 +1,7 @@
 # Alerts UI API and webhook migration
 
-The qbit targets QQQ **4.1.0-RC.6** (pending release). `AlertsQBitProducer` registers the
-`alerts` `MiddlewareSpecExtension`, version `1.1.0`, with the established `/alerts` prefix.
+The qbit targets QQQ **4.1.0-RC.15**, UI API **1.6.0**. `AlertsQBitProducer` registers the
+`alerts` `MiddlewareSpecExtension`, version `1.2.0`, with the established `/alerts` prefix.
 `withRegisterRoutes(false)` opts out of both the extension and webhook registration.
 The six JSON specs extend `AbstractJsonEndpointSpec`; existing `AlertsApi` logic continues
 to enforce caller permissions, recipient ownership and alert visibility.
@@ -20,11 +20,21 @@ discovers the `alerts` extension so clients need not infer installation from an
 | GET | `/qqq/v1/alerts/record-panel` | `alertsRecordPanel` |
 
 All existing query parameters, selector precedence, paging defaults and clamps, status
-codes, JSON content-type requirements, and response keys remain. IDs refer to recipient
+codes, JSON content-type requirements, and success response keys remain. IDs refer to recipient
 rows for inbox operations; legacy `alertId` selectors remain accepted. `all:true` applies
 only to read/dismiss. Items in a summary omit `body`; page items and banners include it.
 Nullable fields remain serialized as JSON null.
 
+## UI API extension changes
+
+UI API extension alerts 1.2.0 (requires QQQ 4.1.0-RC.15, UI API 1.6.0): operationIds,
+standard error responses with BasicErrorResponseV1, and extension tags. The six existing
+operationIds are preserved. Errors retain their HTTP statuses and now include `error`,
+`code`, `message`, and `traceId` (with `fieldErrors` when applicable). `AlertsErrorV1`
+remains in components with a deprecation description for compatibility. The core upgrade
+also retires the expired Slack shim: capable providers now receive notification
+idempotency keys; providers without that capability keep recipient-row deduplication.
+
 ## Next handoff: additive payload fields
 
 - Summary adds nullable `preferencesSection`: the user Preferences section name (`notifications`) or null when not registered. Clients can use `/qqq/v1/preferences/{name}` for notification settings.
@@ -127,12 +137,15 @@ The supplied Next `main` checkout still has no alerts client; the
 
 ## Verification
 
-Use the Maven wrapper with the released QQQ 4.1.0-RC.7 artifacts already installed locally:
+Use the Maven wrapper offline against the locally installed migration build:
 
 ```sh
-./mvnw -o -q verify
+./mvnw -o verify -Dqqq.snapshot.version=4.1.99-SNAPSHOT -Denforcer.skipRules=requireReleaseDeps
 ```
 
 Regenerate intentionally with `-Dtest=AlertsApiContractTest -Dalerts.openapi.update=true test`
 (with `-o` for an offline build). Normal tests compare the fragment without rewriting it.
 Checkstyle uses `checkstyle/config.xml` and the repository's existing short Apache headers.
+
+The Enforcer switch skips only the release-dependency rule for the local SNAPSHOT;
+omit it and the version override when building against the released RC.12 BOM.

pom.xml

@@ -153,7 +153,36 @@
    </dependencies>
 
    <build>
+      <resources>
+         <!-- help bundles carry the artifact version (QQQ help bundle provenance) -->
+         <resource>
+            <directory>src/main/resources</directory>
+            <filtering>true</filtering>
+            <includes>
+               <include>help/*.yaml</include>
+               <include>qbit-alerts.properties</include>
+            </includes>
+         </resource>
+         <resource>
+            <directory>src/main/resources</directory>
+            <filtering>false</filtering>
+            <excludes>
+               <exclude>help/*.yaml</exclude>
+               <exclude>qbit-alerts.properties</exclude>
+            </excludes>
+         </resource>
+      </resources>
       <plugins>
+         <!-- the artifact version, for the help bundle version test -->
+         <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <configuration>
+               <systemPropertyVariables combine.children="append">
+                  <qbit.artifactVersion>${project.version}</qbit.artifactVersion>
+               </systemPropertyVariables>
+            </configuration>
+         </plugin>
          <plugin>
             <groupId>org.apache.maven.plugins</groupId>
             <artifactId>maven-checkstyle-plugin</artifactId>
@@ -231,14 +260,14 @@
    <profiles>
       <!-- Built against qqq 4.1 (QBitMetaDataProducer). Until qbit-build-parent  -->
       <!-- imports the released 4.1 BOM, this profile is active by default and     -->
-      <!-- imports qqq-bom-pom 4.1.0-RC.6 ahead of the parent's 4.0.0 BOM.         -->
+      <!-- imports qqq-bom-pom 4.1.0-RC.15 ahead of the parent's 4.0.0 BOM.         -->
       <profile>
          <id>qqq-snapshot</id>
          <activation>
             <activeByDefault>true</activeByDefault>
          </activation>
          <properties>
-            <qqq.snapshot.version>4.1.0-RC.7</qqq.snapshot.version>
+            <qqq.snapshot.version>4.1.0-RC.15</qqq.snapshot.version>
          </properties>
          <dependencyManagement>
             <dependencies>

src/main/java/com/kingsrook/qbits/alerts/AlertsPreferences.java

@@ -17,6 +17,8 @@
 package com.kingsrook.qbits.alerts;
 
 
+import java.io.Serializable;
+import java.util.List;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 import com.kingsrook.qbits.alerts.engine.AlertsDb;
@@ -26,7 +28,12 @@ import com.kingsrook.qbits.alerts.model.AlertsPossibleValues.ScopeType;
 import com.kingsrook.qbits.alerts.model.AlertsPossibleValues.SubscriberType;
 import com.kingsrook.qbits.alerts.model.AlertsSubscription;
 import com.kingsrook.qbits.alerts.model.AlertsUserPreference;
+import com.kingsrook.qqq.backend.core.actions.tables.DeleteAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.session.QSession;
 
@@ -42,6 +49,9 @@ import com.kingsrook.qqq.backend.core.model.session.QSession;
  *******************************************************************************/
 public final class AlertsPreferences
 {
+   /** marks the bootstrap rule's subscription (createdByUserId). */
+   static final String BOOTSTRAP_CREATOR = "alerts (bootstrap rule)";
+
    private static final Set<String> ENSURED = ConcurrentHashMap.newKeySet();
 
 
@@ -69,36 +79,72 @@ public final class AlertsPreferences
 
       boolean admin    = session.hasPermission(AlertsQBitConfig.PERMISSION_ADMIN);
       String  fullName = session.getUser() == null ? null : session.getUser().getFullName();
-      runtime.asSystem(() ->
-      {
-         if(AlertsDb.first(AlertsUserPreference.TABLE_NAME, AlertsDb.eq("userId", userId)) == null)
-         {
-            AlertsDb.insert(AlertsUserPreference.TABLE_NAME, new QRecord()
-               .withValue("userId", userId)
-               .withValue("userLabel", fullName == null ? userId : fullName)
-               .withValue("inAppEnabled", true)
-               .withValue("emailEnabled", true)
-               .withValue("quietBypassSeverity", "CRITICAL")
-               .withValue("digestHour", 8));
-         }
 
-         if(admin && runtime.getConfig().getBootstrapMinSeverity() != null && AlertsDb.first(AlertsSubscription.TABLE_NAME, AlertsDb.eq("userId", userId)) == null)
+      ////////////////////////////////////////////////////////////////////////////
+      // A page load fires the home widgets and the bell together, so first     //
+      // calls for one user race. Serialize them in this JVM; across replicas,  //
+      // the clean-up below keeps one bootstrap subscription (the lowest id).   //
+      ////////////////////////////////////////////////////////////////////////////
+      synchronized(AlertsPreferences.class)
+      {
+         if(ENSURED.contains(userId))
          {
-            QRecord inApp = runtime.getChannels().defaultChannel(ChannelType.IN_APP);
-            AlertsDb.insert(AlertsSubscription.TABLE_NAME, new QRecord()
-               .withValue("subscriberType", SubscriberType.USER.name())
-               .withValue("userId", userId)
-               .withValue("scopeType", ScopeType.ALL.name())
-               .withValue("minSeverity", runtime.getConfig().getBootstrapMinSeverity().name())
-               .withValue("events", "RAISED,ESCALATED,REMINDER,RESOLVED")
-               .withValue("deliveryMode", DeliveryMode.IMMEDIATE.name())
-               .withValue("channelOverrideIds", String.valueOf(inApp.getValue("id")))
-               .withValue("enabled", true)
-               .withValue("createdByUserId", "alerts (bootstrap rule)"));
+            return;
          }
-         return (null);
-      });
-      ENSURED.add(userId);
+         runtime.asSystem(() ->
+         {
+            if(AlertsDb.first(AlertsUserPreference.TABLE_NAME, AlertsDb.eq("userId", userId)) == null)
+            {
+               AlertsDb.insert(AlertsUserPreference.TABLE_NAME, new QRecord()
+                  .withValue("userId", userId)
+                  .withValue("userLabel", fullName == null ? userId : fullName)
+                  .withValue("inAppEnabled", true)
+                  .withValue("emailEnabled", true)
+                  .withValue("quietBypassSeverity", "CRITICAL")
+                  .withValue("digestHour", 8));
+            }
+
+            if(admin && runtime.getConfig().getBootstrapMinSeverity() != null && AlertsDb.first(AlertsSubscription.TABLE_NAME, AlertsDb.eq("userId", userId)) == null)
+            {
+               QRecord inApp = runtime.getChannels().defaultChannel(ChannelType.IN_APP);
+               AlertsDb.insert(AlertsSubscription.TABLE_NAME, new QRecord()
+                  .withValue("subscriberType", SubscriberType.USER.name())
+                  .withValue("userId", userId)
+                  .withValue("scopeType", ScopeType.ALL.name())
+                  .withValue("minSeverity", runtime.getConfig().getBootstrapMinSeverity().name())
+                  .withValue("events", "RAISED,ESCALATED,REMINDER,RESOLVED")
+                  .withValue("deliveryMode", DeliveryMode.IMMEDIATE.name())
+                  .withValue("channelOverrideIds", String.valueOf(inApp.getValue("id")))
+                  .withValue("enabled", true)
+                  .withValue("createdByUserId", BOOTSTRAP_CREATOR));
+            }
+
+            removeDuplicateBootstrapSubscriptions(userId);
+            return (null);
+         });
+         ENSURED.add(userId);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Keep only the first bootstrap subscription of a user. Two replicas can
+    ** each see no subscription and insert one; every later first call (and the
+    ** losers' own calls) delete the extra copies, so the user is not notified
+    ** twice per alert. Subscriptions a person made are never touched.
+    *******************************************************************************/
+   static void removeDuplicateBootstrapSubscriptions(String userId) throws QException
+   {
+      List<QRecord> bootstrap = AlertsDb.query(AlertsSubscription.TABLE_NAME, AlertsDb.eq("userId", userId)
+         .withCriteria("createdByUserId", QCriteriaOperator.EQUALS, BOOTSTRAP_CREATOR)
+         .withOrderBy(new QFilterOrderBy("id")));
+      if(bootstrap.size() < 2)
+      {
+         return;
+      }
+      List<Serializable> extra = bootstrap.subList(1, bootstrap.size()).stream().map(r -> (Serializable) r.getValue("id")).toList();
+      new DeleteAction().execute(new DeleteInput(AlertsSubscription.TABLE_NAME).withPrimaryKeys(extra).withTransaction(QContext.getQBackendTransaction()));
    }
 
 

src/main/java/com/kingsrook/qbits/alerts/AlertsQBitProducer.java

@@ -17,14 +17,16 @@
 package com.kingsrook.qbits.alerts;
 
 
+import java.io.IOException;
+import java.io.InputStream;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Properties;
 import com.kingsrook.qbits.alerts.delivery.DeliveryWorker;
 import com.kingsrook.qbits.alerts.engine.AlertsProcessListener;
 import com.kingsrook.qbits.alerts.engine.AlertsSinkAdapter;
 import com.kingsrook.qbits.alerts.engine.MonitorEvaluator;
 import com.kingsrook.qbits.alerts.engine.QbitAlertsSink;
-import com.kingsrook.qbits.alerts.metadata.AlertsHelp;
 import com.kingsrook.qbits.alerts.metadata.AlertsTableMetaDataHelper;
 import com.kingsrook.qbits.alerts.model.AlertsChannel;
 import com.kingsrook.qbits.alerts.model.AlertsMonitor;
@@ -38,6 +40,7 @@ import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.help.bundles.HelpBundles;
 import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaDataProducer;
 import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
@@ -66,7 +69,7 @@ public class AlertsQBitProducer implements QBitMetaDataProducer<AlertsQBitConfig
 
    public static final String GROUP_ID    = "com.kingsrook.qbits";
    public static final String ARTIFACT_ID = "qbit-alerts";
-   public static final String VERSION     = "0.1.0";
+   public static final String VERSION     = loadVersion();
 
    private static final String JAVALIN_CLASS = "com.kingsrook.qqq.middleware.javalin.QJavalinMetaData";
 
@@ -75,6 +78,34 @@ public class AlertsQBitProducer implements QBitMetaDataProducer<AlertsQBitConfig
 
 
 
+   /*******************************************************************************
+    ** Read the artifact version from the Maven-filtered resource.
+    *******************************************************************************/
+   private static String loadVersion()
+   {
+      try(InputStream inputStream = AlertsQBitProducer.class.getClassLoader().getResourceAsStream("qbit-alerts.properties"))
+      {
+         if(inputStream == null)
+         {
+            throw (new IllegalStateException("Missing qbit-alerts.properties; build with Maven to generate the artifact version"));
+         }
+         Properties properties = new Properties();
+         properties.load(inputStream);
+         String version = properties.getProperty("version");
+         if(version == null || version.isBlank() || version.contains("${"))
+         {
+            throw (new IllegalStateException("Missing or invalid version in qbit-alerts.properties; build with Maven resource filtering enabled"));
+         }
+         return (version);
+      }
+      catch(IOException e)
+      {
+         throw (new IllegalStateException("Could not read artifact version from qbit-alerts.properties", e));
+      }
+   }
+
+
+
    /*******************************************************************************
     ** Fluent setter for the config.
     *******************************************************************************/
@@ -174,7 +205,8 @@ public class AlertsQBitProducer implements QBitMetaDataProducer<AlertsQBitConfig
 
       MetaDataProducerMultiOutput output = QBitMetaDataProducer.super.produce(qInstance);
       output.addSelfToInstance(qInstance);
-      AlertsHelp.apply(qInstance);
+      // Registration is metadata-only; core guards startup sync when helpContent is absent.
+      HelpBundles.register(qInstance, "help/qbit-alerts.yaml");
       return (new MetaDataProducerMultiOutput());
    }
 

src/main/java/com/kingsrook/qbits/alerts/AlertsRuntime.java

@@ -144,7 +144,7 @@ public class AlertsRuntime
    public <R> R asSystem(SystemWork<R> work) throws QException
    {
       Object[] result = new Object[1];
-      QContext.withTemporaryContext(new CapturedContext(qInstance, AlertsSecurity.systemSession()), () ->
+      QContext.withTemporaryContext(new CapturedContext(qInstance, AlertsSecurity.systemSession(qInstance)), () ->
       {
          result[0] = work.run();
       });

src/main/java/com/kingsrook/qbits/alerts/AlertsSecurity.java

@@ -278,7 +278,19 @@ public final class AlertsSecurity
     *******************************************************************************/
    public static QSystemUserSession systemSession()
    {
-      QSystemUserSession session = new QSystemUserSession();
+      return (systemSession(QContext.getQInstance()));
+   }
+
+
+
+   /*******************************************************************************
+    ** A system-user session for this instance, holding the alerts all-access
+    ** keys.  Background threads (the alerts sink, schedulers) have no QContext
+    ** yet, so they must pass the instance in.
+    *******************************************************************************/
+   public static QSystemUserSession systemSession(QInstance qInstance)
+   {
+      QSystemUserSession session = new QSystemUserSession(qInstance);
       session.withSecurityKeyValue(KEY_USER_ALL_ACCESS, true);
       session.withSecurityKeyValue(KEY_PERMISSION_ALL, true);
       session.withSecurityKeyValue(KEY_READABLE_TABLE_ALL, true);

src/main/java/com/kingsrook/qbits/alerts/api/AlertsJsonSpec.java

@@ -23,6 +23,7 @@ import com.kingsrook.qqq.backend.core.exceptions.QBadRequestException;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.middleware.javalin.specs.BasicResponse;
 import com.kingsrook.qqq.middleware.javalin.specs.extensions.AbstractJsonEndpointSpec;
+import com.kingsrook.qqq.middleware.javalin.specs.v1.responses.BasicErrorResponseV1;
 import com.kingsrook.qqq.openapi.model.Method;
 import io.javalin.http.Context;
 import io.javalin.http.HttpStatus;
@@ -79,10 +80,10 @@ abstract class AlertsJsonSpec extends AbstractJsonEndpointSpec
    @Override
    public List<BasicResponse> defineAdditionalBasicResponses()
    {
-      return (List.of(new BasicResponse(HttpStatus.BAD_REQUEST, "Invalid input", "AlertsErrorV1"),
-         new BasicResponse(HttpStatus.UNAUTHORIZED, "Sign in required", "AlertsErrorV1"),
-         new BasicResponse(HttpStatus.FORBIDDEN, "Permission denied", "AlertsErrorV1"),
-         new BasicResponse(HttpStatus.NOT_FOUND, "Not found", "AlertsErrorV1")));
+      return (List.of(new BasicResponse(HttpStatus.BAD_REQUEST, "Invalid input", BasicErrorResponseV1.class.getSimpleName()),
+         new BasicResponse(HttpStatus.UNAUTHORIZED, "Sign in required", BasicErrorResponseV1.class.getSimpleName()),
+         new BasicResponse(HttpStatus.FORBIDDEN, "Permission denied", BasicErrorResponseV1.class.getSimpleName()),
+         new BasicResponse(HttpStatus.NOT_FOUND, "Not found", BasicErrorResponseV1.class.getSimpleName())));
    }
 
 

src/main/java/com/kingsrook/qbits/alerts/api/AlertsSchemas.java

@@ -300,7 +300,7 @@ public final class AlertsSchemas
       @Override
       public Schema toSchema()
       {
-         return (new Schema().withType(Type.OBJECT).withDescription("Framework error response.").withProperties(new TreeMap<>(Map.ofEntries(
+         return (new Schema().withType(Type.OBJECT).withDescription("Deprecated since 1.2.0: errors use BasicErrorResponseV1.").withProperties(new TreeMap<>(Map.ofEntries(
             Map.entry("error", new Schema().withType(Type.STRING).withNullable(true))))));
       }
    }

src/main/java/com/kingsrook/qbits/alerts/api/AlertsUiApi.java

@@ -52,7 +52,7 @@ public final class AlertsUiApi
    public static MiddlewareSpecExtension extension()
    {
       return (new MiddlewareSpecExtension().withName("alerts").withPathPrefix("/alerts")
-         .withSemanticVersion("1.1.0").withDescription("Alerts inbox and record panel")
+         .withSemanticVersion("1.2.0").withDescription("Alerts inbox and record panel")
          .withSpec(InboxSummarySpec.class).withSpec(InboxSpec.class)
          .withSpec(InboxReadSpec.class).withSpec(InboxUnreadSpec.class)
          .withSpec(InboxDismissSpec.class).withSpec(RecordPanelSpec.class));

src/main/java/com/kingsrook/qbits/alerts/engine/AlertsDb.java

@@ -40,7 +40,8 @@ import com.kingsrook.qqq.backend.core.utils.CollectionUtils;
 /*******************************************************************************
  ** Small helpers over QQQ's table actions, for the engine. They run in
  ** whatever context the caller set up (the engine uses the system user), so
- ** customizers, audits and ESB listeners apply as for any other write.
+ ** customizers, audits and ESB listeners apply as for any other write, except
+ ** that bookkeeping-only updates (RuntimeFields) are not record-audited.
  *******************************************************************************/
 public final class AlertsDb
 {
@@ -114,11 +115,14 @@ public final class AlertsDb
 
 
    /*******************************************************************************
-    ** Update one row (it must carry its id); throws on an error.
+    ** Update one row (it must carry its id); throws on an error. An update of
+    ** engine bookkeeping fields only (RuntimeFields) is not record-audited.
     *******************************************************************************/
    public static QRecord update(String tableName, QRecord record) throws QException
    {
-      List<QRecord> updated = UpdateAction.executeForRecords(new UpdateInput(tableName).withRecord(record).withTransaction(QContext.getQBackendTransaction()));
+      UpdateInput   input   = new UpdateInput(tableName).withRecord(record).withTransaction(QContext.getQBackendTransaction())
+         .withOmitDmlAudit(RuntimeFields.onlyRuntime(tableName, record));
+      List<QRecord> updated = UpdateAction.executeForRecords(input);
       QRecord       result  = updated.get(0);
       throwIfErrors(tableName, result);
       return (result);

src/main/java/com/kingsrook/qbits/alerts/engine/RuntimeFields.java

@@ -0,0 +1,76 @@
+/*
+ * 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.alerts.engine;
+
+
+import java.util.Map;
+import java.util.Set;
+import com.kingsrook.qbits.alerts.model.AlertsAlert;
+import com.kingsrook.qbits.alerts.model.AlertsMonitor;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Engine bookkeeping columns: evaluation leases, run results and notification
+ ** timers that change on every scheduler pass. An update that touches only
+ ** these (plus the primary key and modifyDate) is not record-audited; the core
+ ** FIELD audit would otherwise write an audit row per monitor run and per
+ ** reminder check. Any update that also changes a configuration or alert-state
+ ** field (status, severity, acknowledgement, assignment, a monitor's settings)
+ ** is audited in full, as before. Run history lives in the run fields
+ ** themselves; alert raises, transitions and notifications have their own
+ ** event and delivery tables.
+ *******************************************************************************/
+public final class RuntimeFields
+{
+   private static final Set<String> ALWAYS = Set.of("id", "modifyDate");
+
+   private static final Map<String, Set<String>> BY_TABLE = Map.of(
+      AlertsMonitor.TABLE_NAME, Set.of("claimedBy", "claimedUntil", "lastRunAt", "nextRunAt", "lastStatus", "lastValue", "lastError",
+         "lastElapsedMs", "consecutiveFailures", "conditionSince"),
+      AlertsAlert.TABLE_NAME, Set.of("timedNotificationCheckedAt", "lastNotifiedAt", "recordRefCount"));
+
+
+
+   /*******************************************************************************
+    ** Constants only.
+    *******************************************************************************/
+   private RuntimeFields()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** The bookkeeping fields of a table (empty when it has none).
+    *******************************************************************************/
+   public static Set<String> of(String tableName)
+   {
+      return (BY_TABLE.getOrDefault(tableName, Set.of()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Whether an update record carries nothing but bookkeeping fields.
+    *******************************************************************************/
+   public static boolean onlyRuntime(String tableName, QRecord update)
+   {
+      Set<String> runtime = of(tableName);
+      return (!runtime.isEmpty() && update.getValues().keySet().stream().allMatch(field -> runtime.contains(field) || ALWAYS.contains(field)));
+   }
+}

src/main/java/com/kingsrook/qbits/alerts/metadata/AlertsHelp.java

@@ -1,127 +0,0 @@
-/*
- * 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.alerts.metadata;
-
-
-import java.io.IOException;
-import java.io.InputStream;
-import java.util.LinkedHashMap;
-import java.util.Map;
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
-import com.kingsrook.qbits.alerts.AlertsQBitConfig;
-import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
-import com.kingsrook.qqq.backend.core.model.metadata.help.QHelpContent;
-import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
-import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
-
-
-/*******************************************************************************
- ** Applies help/qbit-alerts.yaml (the QQQ help-bundle format) to the
- ** Alerts app and its alerts_* tables: what each table is for and how
- ** its rows get created, shown on the table screen and when it is empty.
- ** STAND-IN(core=QRun-IO/qqq#1198, removeBy=4.1.0-RC.8): replace with HelpBundles.register once the pinned
- ** QQQ release includes it; the bundle file stays the same.
- *******************************************************************************/
-public final class AlertsHelp
-{
-   public static final String RESOURCE = "/help/qbit-alerts.yaml";
-   public static final String SLOT     = "help";
-
-
-
-   /*******************************************************************************
-    ** Utility class.
-    *******************************************************************************/
-   private AlertsHelp()
-   {
-   }
-
-
-
-   /*******************************************************************************
-    ** The bundle's entries by key, validated (fails startup if malformed).
-    *******************************************************************************/
-   public static Map<String, JsonNode> entries() throws QException
-   {
-      try(InputStream stream = AlertsHelp.class.getResourceAsStream(RESOURCE))
-      {
-         if(stream == null)
-         {
-            throw (new IOException("missing resource"));
-         }
-         JsonNode bundle = new ObjectMapper(new YAMLFactory()).readTree(stream);
-         if(!"qbit-alerts".equals(bundle.path("bundle").asText()) || !"QBIT".equals(bundle.path("layer").asText()))
-         {
-            throw (new IOException("invalid bundle header"));
-         }
-         Map<String, JsonNode> entries = new LinkedHashMap<>();
-         for(JsonNode entry : bundle.path("entries"))
-         {
-            String key     = entry.path("key").asText();
-            String summary = entry.path("summary").asText();
-            if(key.isBlank() || summary.isBlank() || summary.length() > 120 || entry.path("content").asText().isBlank() || entries.put(key, entry) != null)
-            {
-               throw (new IOException("invalid or duplicate entry: " + key));
-            }
-         }
-         return (entries);
-      }
-      catch(IOException | RuntimeException e)
-      {
-         throw (new QException("Could not load " + RESOURCE, e));
-      }
-   }
-
-
-
-   /*******************************************************************************
-    ** Apply the help to the app and every alerts_* table in the instance.
-    ** A host's own help on a table is kept (the bundle only fills the slot).
-    *******************************************************************************/
-   public static void apply(QInstance qInstance) throws QException
-   {
-      Map<String, JsonNode> entries = entries();
-      for(QTableMetaData table : qInstance.getTables().values())
-      {
-         JsonNode entry = entries.get("table:" + table.getName() + ";slot:" + SLOT);
-         if(entry != null && (table.getHelpContent() == null || !table.getHelpContent().containsKey(SLOT)))
-         {
-            table.withHelpContent(SLOT, content(entry));
-         }
-      }
-      QAppMetaData app = qInstance.getApp(AlertsQBitConfig.APP_NAME);
-      JsonNode     appEntry = entries.get("app:" + AlertsQBitConfig.APP_NAME + ";slot:" + SLOT);
-      if(app != null && appEntry != null && (app.getHelpContent() == null || !app.getHelpContent().containsKey(SLOT)))
-      {
-         app.withHelpContent(SLOT, content(appEntry));
-      }
-   }
-
-
-
-   /*******************************************************************************
-    ** Summary as the first paragraph, then the content, as markdown.
-    *******************************************************************************/
-   static QHelpContent content(JsonNode entry)
-   {
-      return (new QHelpContent().withContentAsMarkdown(entry.path("summary").asText().strip() + "\n\n" + entry.path("content").asText().strip()));
-   }
-
-}

src/main/java/com/kingsrook/qbits/alerts/model/AlertsPossibleValues.java

@@ -290,7 +290,7 @@ public final class AlertsPossibleValues
     *******************************************************************************/
    public enum EmailStatus
    {
-      NONE, PENDING, SENT, DIGESTED, SKIPPED, FAILED
+      NONE, PENDING, REQUESTED, SENT, DIGESTED, SKIPPED, FAILED
    }
 
 

src/main/java/com/kingsrook/qbits/alerts/notifications/NotificationEmailer.java

@@ -29,11 +29,14 @@ import java.util.HashMap;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
 import com.kingsrook.qbits.alerts.AlertsQBitConfig;
 import com.kingsrook.qbits.alerts.AlertsRuntime;
 import com.kingsrook.qbits.alerts.delivery.AlertRedactor;
 import com.kingsrook.qbits.alerts.email.AlertsEmail;
 import com.kingsrook.qbits.alerts.email.AlertsEmailSender;
+import com.kingsrook.qbits.alerts.engine.AlertTiming;
 import com.kingsrook.qbits.alerts.engine.AlertsDb;
 import com.kingsrook.qbits.alerts.metadata.AlertsProcessesMetaDataProducer;
 import com.kingsrook.qbits.alerts.model.AlertsNotification;
@@ -43,6 +46,7 @@ import com.kingsrook.qbits.alerts.model.AlertsPossibleValues.EmailMode;
 import com.kingsrook.qbits.alerts.model.AlertsPossibleValues.EmailStatus;
 import com.kingsrook.qbits.alerts.model.AlertsUserPreference;
 import com.kingsrook.qqq.backend.core.actions.messaging.SendMessageAction;
+import com.kingsrook.qqq.backend.core.alerts.AlertSeverity;
 import com.kingsrook.qqq.backend.core.alerts.NotificationCategory;
 import com.kingsrook.qqq.backend.core.alerts.NotificationSeverity;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
@@ -67,6 +71,11 @@ import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
  ** - IMMEDIATE: one email per notification at or above the minimum severity;
  ** - DAILY_DIGEST: one email at the user's digest hour (in their time zone,
  **   from My Alert Settings) listing the day's unread notifications.
+ ** A recipient with email status REQUESTED (a per-notification opt-in, e.g. by
+ ** a job) is emailed immediately without a standing category preference. It
+ ** still honours the category's email minimum severity when one is set, the
+ ** user's pause (SECURITY bypasses) and quiet hours (held, not dropped), is
+ ** skipped without a known address, and is only eligible for a day.
  ** Sent through qbit-email when it is produced in the instance (one message
  ** per recipient; templates alerts_notification and alerts_digest,
  ** NOTIFICATION), else through core SendMessageAction. Inert without either
@@ -137,12 +146,19 @@ public class NotificationEmailer
          {
             preferences.computeIfAbsent(preference.getValueString("userId"), k -> new HashMap<>()).put(preference.getValueString("category"), preference);
          }
-         if(preferences.isEmpty())
+
+         QQueryFilter eligible = new QQueryFilter().withBooleanOperator(QQueryFilter.BooleanOperator.OR)
+            .withSubFilter(new QQueryFilter()
+               .withCriteria("emailStatus", QCriteriaOperator.EQUALS, EmailStatus.REQUESTED.name())
+               .withCriteria("deliveredAt", QCriteriaOperator.GREATER_THAN_OR_EQUALS, now.minus(1, ChronoUnit.DAYS)));
+         if(!preferences.isEmpty())
          {
-            return (new Result(0, 0, 0, 0));
+            eligible.withSubFilter(new QQueryFilter()
+               .withCriteria("userId", QCriteriaOperator.IN, new ArrayList<>(preferences.keySet()))
+               .withCriteria("emailStatus", QCriteriaOperator.IN, List.of(EmailStatus.NONE.name(), EmailStatus.PENDING.name())));
          }
 
-         Map<String, QRecord> settings = userSettings(preferences.keySet());
+         Map<String, QRecord> settings = new HashMap<>();
          int sent = 0;
          int skipped = 0;
          int failed = 0;
@@ -151,8 +167,7 @@ public class NotificationEmailer
          while(true)
          {
             List<QRecord> recipients = AlertsDb.query(AlertsNotificationRecipient.TABLE_NAME, new QQueryFilter()
-               .withCriteria("userId", QCriteriaOperator.IN, new ArrayList<>(preferences.keySet()))
-               .withCriteria("emailStatus", QCriteriaOperator.IN, List.of(EmailStatus.NONE.name(), EmailStatus.PENDING.name()))
+               .withSubFilter(eligible)
                .withCriteria("id", QCriteriaOperator.GREATER_THAN, afterId)
                .withOrderBy(new QFilterOrderBy("id", true)).withLimit(SCAN));
             if(recipients.isEmpty())
@@ -161,25 +176,43 @@ public class NotificationEmailer
             }
             afterId = recipients.get(recipients.size() - 1).getValueInteger("id");
             Map<Integer, QRecord> notifications = notifications(recipients, now);
+            Set<String> pageUsers = recipients.stream().map(recipient -> recipient.getValueString("userId")).collect(Collectors.toSet());
+            settings.putAll(userSettings(pageUsers));
+            Map<String, Map<String, QRecord>> requestedPreferences = new HashMap<>();
+            for(QRecord preference : AlertsDb.query(AlertsNotificationPreference.TABLE_NAME, new QQueryFilter()
+               .withCriteria("userId", QCriteriaOperator.IN, new ArrayList<>(pageUsers))))
+            {
+               requestedPreferences.computeIfAbsent(preference.getValueString("userId"), k -> new HashMap<>()).put(preference.getValueString("category"), preference);
+            }
             for(QRecord recipient : recipients)
             {
                QRecord notification = notifications.get(recipient.getValueInteger("notificationId"));
                String  userId       = recipient.getValueString("userId");
-               QRecord preference   = notification == null ? null : preferences.get(userId).get(notification.getValueString("category"));
-               if(notification == null || preference == null || NotificationCategory.ALERT.name().equals(notification.getValueString("category"))
-                  || !atLeast(notification.getValueString("severity"), preference.getValueString("emailMinSeverity")))
+               boolean requested    = EmailStatus.REQUESTED.name().equals(recipient.getValueString("emailStatus"));
+               String  category     = notification == null ? null : notification.getValueString("category");
+               QRecord preference   = category == null ? null : (requested ? requestedPreferences : preferences).getOrDefault(userId, Map.of()).get(category);
+               QRecord setting      = settings.get(userId);
+               if(notification == null || NotificationCategory.ALERT.name().equals(category)
+                  || (requested ? (!StringUtils.hasContent(address(setting)) || (preference != null && StringUtils.hasContent(preference.getValueString("emailMinSeverity"))
+                  && !atLeast(notification.getValueString("severity"), preference.getValueString("emailMinSeverity"))))
+                  : (preference == null || !atLeast(notification.getValueString("severity"), preference.getValueString("emailMinSeverity")))))
                {
                   mark(recipient, EmailStatus.SKIPPED, null);
                   skipped++;
                }
-               else if(!NotificationCategory.SECURITY.name().equals(notification.getValueString("category"))
-                  && settings.get(userId) != null && settings.get(userId).getValueInstant("pausedUntil") != null
-                  && settings.get(userId).getValueInstant("pausedUntil").isAfter(now))
+               else if(!NotificationCategory.SECURITY.name().equals(category)
+                  && setting != null && setting.getValueInstant("pausedUntil") != null
+                  && setting.getValueInstant("pausedUntil").isAfter(now))
                {
                   // Leave the recipient pending so a later run can deliver it.
                   skipped++;
                }
-               else if(EmailMode.IMMEDIATE.name().equals(preference.getValueString("emailMode")))
+               else if(requested && AlertTiming.isQuiet(setting, AlertSeverity.fromLabel(notification.getValueString("severity"), AlertSeverity.WARNING), now))
+               {
+                  // Quiet hours hold a requested email; it stays REQUESTED until the window ends or it ages out.
+                  skipped++;
+               }
+               else if(requested || EmailMode.IMMEDIATE.name().equals(preference.getValueString("emailMode")))
                {
                   EmailStatus status = sendImmediate(address(settings.get(userId)), notification);
                   mark(recipient, status, status == EmailStatus.SENT ? now : null);

src/main/java/com/kingsrook/qbits/alerts/notifications/NotificationSlackSender.java

@@ -47,6 +47,7 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperat
 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;
+import com.kingsrook.qqq.backend.core.modules.messaging.MessagingProviderCapability;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
 import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
 
@@ -232,9 +233,8 @@ public class NotificationSlackSender
     ** when the provider says the user can't be reached (no Slack connection),
     ** with no retry; FAILED for anything else.
     **
-    ** STAND-IN(core=QRun-IO/qqq#1194, removeBy=4.1.0-RC.8): RC.6 SendMessageInput has no
-    ** idempotency key (notify:<notificationId>:<userId>:slack), so the
-    ** recipient row's slackStatus is what prevents a resend.
+    ** Pass the notification idempotency key when the provider supports it.
+    ** The recipient row's slackStatus also prevents a resend.
     *******************************************************************************/
    private SlackStatus sendExternal(String userId, String subject, List<QRecord> items, Integer notificationId)
    {
@@ -258,6 +258,7 @@ public class NotificationSlackSender
       {
          new SendMessageAction().execute(new SendMessageInput()
             .withMessagingProviderName(runtime.getConfig().getSlackProviderName())
+            .withIdempotencyKey(SendMessageAction.capabilities(runtime.getConfig().getSlackProviderName()).contains(MessagingProviderCapability.IDEMPOTENCY) ? key : null)
             .withTo(new Party().withAddress("user:" + userId))
             .withSubject(subject)
             .withContentList(List.of(new Content().withContentRole(ContentRole.Default.DEFAULT).withBody(text.toString().stripTrailing()))));

src/main/resources/openapi/qqq-v1/alerts.yaml

@@ -16,7 +16,7 @@ components:
           type: "string"
       type: "object"
     AlertsErrorV1:
-      description: "Framework error response."
+      description: "Deprecated since 1.2.0: errors use BasicErrorResponseV1."
       properties:
         error:
           nullable: true
@@ -212,17 +212,89 @@ components:
             type: "integer"
           type: "array"
       type: "object"
+    BasicErrorResponseV1:
+      description: "The error body of every UI API operation (core and extensions)."
+      properties:
+        error:
+          description: "The error message (the same as message; kept for clients of\
+            \ UI API 1.0 to 1.5)."
+          type: "string"
+        code:
+          description: "A stable, machine-readable code. Well-known values: BAD_REQUEST\
+            \ (400), UNAUTHENTICATED (401),\nPERMISSION_DENIED (403), NOT_FOUND (404),\
+            \ CONFLICT (409), RATE_LIMITED (429), INTERNAL_ERROR (500),\nERROR (other).\
+            \ Extensions may add codes; treat an unknown code by the HTTP status.\
+            \ Since 1.6.0."
+          type: "string"
+        message:
+          description: "A message to show the user. Since 1.6.0."
+          type: "string"
+        fieldErrors:
+          description: "Errors about particular request fields, when known. Since\
+            \ 1.6.0."
+          items:
+            properties:
+              field:
+                description: "The field (or parameter) name."
+                type: "string"
+              message:
+                description: "The error about that field."
+                type: "string"
+              code:
+                description: "An optional machine-readable code, e.g. REQUIRED, TOO_LONG,\
+                  \ PATTERN."
+                type: "string"
+            type: "object"
+          type: "array"
+        traceId:
+          description: "Identifies this request in the server logs (also the X-QQQ-Trace-Id\
+            \ response header); quote it when reporting a problem. Since 1.6.0."
+          type: "string"
+      type: "object"
   securitySchemes:
     sessionUuidCookie:
+      description: "The session cookie set by POST /qqq/v1/manageSession (web clients)."
       in: "cookie"
       name: "sessionUUID"
       type: "apiKey"
+    bearerAuth:
+      bearerFormat: "JWT or session UUID"
+      description: "`Authorization: Bearer <token>`, where the token is either\n-\
+        \ an OAuth2 access token (a signed JWT) issued by the app's identity provider\
+        \ to the app's client,\n  or to its native client (`values.nativeClientId`\
+        \ in GET /qqq/v1/metaData/authentication), for\n  example from the device-authorization\
+        \ grant or auth-code + PKCE. It is verified against the\n  provider's keys\
+        \ (issuer, audience, expiry, signature) and gives the same user and permissions\n\
+        \  as signing in on the web. When it expires (401), refresh it at the provider\
+        \ and retry; or\n- a session UUID returned by POST /qqq/v1/manageSession,\
+        \ which the server keeps refreshed."
+      scheme: "bearer"
+      type: "http"
+    oauth2:
+      description: "The app's OAuth2 / OpenID Connect provider. The real endpoints\
+        \ come from the provider's discovery\ndocument: `{values.baseUrl}.well-known/openid-configuration`,\
+        \ with values from\nGET /qqq/v1/metaData/authentication. Native clients use\
+        \ `values.nativeClientId` (a public client)\nwith auth-code + PKCE (loopback\
+        \ or custom-scheme redirect URI registered at the provider) or the\ndevice-authorization\
+        \ grant (`device_authorization_endpoint`, RFC 8628), then send the access\
+        \ token\nas `Authorization: Bearer`."
+      flows:
+        authorizationCode:
+          authorizationUrl: "/authorize"
+          scopes:
+            email: "Email address"
+            offline_access: "A refresh token, to renew the access token without signing\
+              \ in again"
+            openid: "OpenID Connect sign-in"
+            profile: "Name, username and groups (permissions come from the groups)"
+          tokenUrl: "/token"
+      type: "oauth2"
 info:
   contact:
     email: "contact@kingsrook.com"
   description: "Alerts inbox and record panel"
   title: "QQQ Middleware API extension: alerts"
-  version: "1.1.0"
+  version: "1.2.0"
 openapi: "3.0.3"
 paths:
   /qqq/v1/alerts/inbox/summary:
@@ -234,25 +306,25 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Invalid input"
         401:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Sign in required"
         403:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Permission denied"
         404:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Not found"
         200:
           content:
@@ -260,10 +332,31 @@ paths:
               schema:
                 $ref: "#/components/schemas/AlertsInboxSummaryV1"
           description: "Successful Response"
+        409:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Conflict with the current state, e.g. an edit conflict or\
+            \ an invalid transition (code CONFLICT)."
+        429:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Too many requests (code RATE_LIMITED); retry later."
       security:
       - sessionUuidCookie:
         - "N/A"
+      - bearerAuth:
+        - "N/A"
+      - oauth2:
+        - "openid"
+        - "profile"
+        - "email"
       summary: "Read the bell summary"
+      tags:
+      - "alerts"
   /qqq/v1/alerts/inbox:
     get:
       description: "Uses the signed-in caller's permissions and record visibility."
@@ -304,25 +397,25 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Invalid input"
         401:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Sign in required"
         403:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Permission denied"
         404:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Not found"
         200:
           content:
@@ -330,10 +423,31 @@ paths:
               schema:
                 $ref: "#/components/schemas/AlertsInboxPageV1"
           description: "Successful Response"
+        409:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Conflict with the current state, e.g. an edit conflict or\
+            \ an invalid transition (code CONFLICT)."
+        429:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Too many requests (code RATE_LIMITED); retry later."
       security:
       - sessionUuidCookie:
         - "N/A"
+      - bearerAuth:
+        - "N/A"
+      - oauth2:
+        - "openid"
+        - "profile"
+        - "email"
       summary: "Page the notification inbox"
+      tags:
+      - "alerts"
   /qqq/v1/alerts/inbox/read:
     post:
       description: "Uses the signed-in caller's permissions and record visibility."
@@ -349,25 +463,25 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Invalid input"
         401:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Sign in required"
         403:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Permission denied"
         404:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Not found"
         200:
           content:
@@ -375,10 +489,31 @@ paths:
               schema:
                 $ref: "#/components/schemas/AlertsMutationResultV1"
           description: "Successful Response"
+        409:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Conflict with the current state, e.g. an edit conflict or\
+            \ an invalid transition (code CONFLICT)."
+        429:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Too many requests (code RATE_LIMITED); retry later."
       security:
       - sessionUuidCookie:
         - "N/A"
+      - bearerAuth:
+        - "N/A"
+      - oauth2:
+        - "openid"
+        - "profile"
+        - "email"
       summary: "Mark own notifications read"
+      tags:
+      - "alerts"
   /qqq/v1/alerts/inbox/unread:
     post:
       description: "Uses the signed-in caller's permissions and record visibility."
@@ -394,25 +529,25 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Invalid input"
         401:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Sign in required"
         403:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Permission denied"
         404:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Not found"
         200:
           content:
@@ -420,10 +555,31 @@ paths:
               schema:
                 $ref: "#/components/schemas/AlertsMutationResultV1"
           description: "Successful Response"
+        409:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Conflict with the current state, e.g. an edit conflict or\
+            \ an invalid transition (code CONFLICT)."
+        429:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Too many requests (code RATE_LIMITED); retry later."
       security:
       - sessionUuidCookie:
         - "N/A"
+      - bearerAuth:
+        - "N/A"
+      - oauth2:
+        - "openid"
+        - "profile"
+        - "email"
       summary: "Mark own notifications unread"
+      tags:
+      - "alerts"
   /qqq/v1/alerts/inbox/dismiss:
     post:
       description: "Uses the signed-in caller's permissions and record visibility."
@@ -439,25 +595,25 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Invalid input"
         401:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Sign in required"
         403:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Permission denied"
         404:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Not found"
         200:
           content:
@@ -465,10 +621,31 @@ paths:
               schema:
                 $ref: "#/components/schemas/AlertsMutationResultV1"
           description: "Successful Response"
+        409:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Conflict with the current state, e.g. an edit conflict or\
+            \ an invalid transition (code CONFLICT)."
+        429:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Too many requests (code RATE_LIMITED); retry later."
       security:
       - sessionUuidCookie:
         - "N/A"
+      - bearerAuth:
+        - "N/A"
+      - oauth2:
+        - "openid"
+        - "profile"
+        - "email"
       summary: "Dismiss own notifications"
+      tags:
+      - "alerts"
   /qqq/v1/alerts/record-panel:
     get:
       description: "Uses the signed-in caller's permissions and record visibility."
@@ -491,25 +668,25 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Invalid input"
         401:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Sign in required"
         403:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Permission denied"
         404:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AlertsErrorV1"
+                $ref: "#/components/schemas/BasicErrorResponseV1"
           description: "Not found"
         200:
           content:
@@ -517,7 +694,34 @@ paths:
               schema:
                 $ref: "#/components/schemas/AlertsRecordPanelV1"
           description: "Successful Response"
+        409:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Conflict with the current state, e.g. an edit conflict or\
+            \ an invalid transition (code CONFLICT)."
+        429:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Too many requests (code RATE_LIMITED); retry later."
       security:
       - sessionUuidCookie:
         - "N/A"
+      - bearerAuth:
+        - "N/A"
+      - oauth2:
+        - "openid"
+        - "profile"
+        - "email"
       summary: "Read visible alerts for a record"
+      tags:
+      - "alerts"
+servers:
+- description: "The QQQ server that serves this document (paths include /qqq/v1)."
+  url: "/"
+tags:
+- description: "Operations of the alerts extension."
+  name: "alerts"

src/main/resources/qbit-alerts.properties

@@ -0,0 +1 @@
+version=${project.version}

src/test/java/com/kingsrook/qbits/alerts/AlertsApiContractTest.java

@@ -51,12 +51,12 @@ class AlertsApiContractTest extends BaseAlertsTest
       assertThat(UiApiContract.check(generated, Files.readString(path), null, 1,
          "mvnw.cmd -Dtest=AlertsApiContractTest -Dalerts.openapi.update=true test")).isEmpty();
       var model = version.generateExtensionOpenAPIModel("qqq", extension);
-      assertThat(model.getComponents().getSchemas().keySet()).allMatch(name -> name.startsWith("Alerts"));
+      assertThat(model.getComponents().getSchemas().keySet()).allMatch(name -> name.startsWith("Alerts") || name.equals("BasicErrorResponseV1"));
       assertThat(model.getPaths().keySet()).containsExactlyInAnyOrder(
          "/qqq/v1/alerts/inbox/summary", "/qqq/v1/alerts/inbox", "/qqq/v1/alerts/inbox/read",
          "/qqq/v1/alerts/inbox/unread", "/qqq/v1/alerts/inbox/dismiss", "/qqq/v1/alerts/record-panel");
       assertThat(extension.getSpecs()).hasSize(6);
-      assertThat(extension.getSemanticVersion()).isEqualTo("1.1.0");
+      assertThat(extension.getSemanticVersion()).isEqualTo("1.2.0");
       assertThat(generated).contains("alertsInboxSummary", "alertsInboxRead", "alertsInboxUnread", "alertsInboxDismiss", "alertsRecordPanel", "inboxHref", "preferencesSection", "actions", "follow");
       assertThat(generated).doesNotContain("/watch", "/ingest/", "/hooks/");
    }

src/test/java/com/kingsrook/qbits/alerts/AlertsApiHttpTest.java

@@ -224,7 +224,12 @@ class AlertsApiHttpTest extends BaseAlertsTest
       assertThat(request("POST", base + "/record-panel/watch", "{}", ADMIN, null).statusCode()).isEqualTo(404);
       HttpResponse<String> invalidJson = request("POST", base + "/inbox/read", "not json", ADMIN, null);
       assertThat(invalidJson.statusCode()).isEqualTo(400);
-      assertThat(invalidJson.body()).contains("The request body is not valid JSON.");
+      Map<String, Object> error = JsonUtils.toObject(invalidJson.body(), Map.class);
+      assertThat(error).containsKeys("error", "code", "message", "traceId")
+         .containsEntry("message", "The request body is not valid JSON.");
+      assertThat(error.get("error")).isEqualTo(error.get("message"));
+      assertThat(error.get("code")).isNotNull();
+      assertThat((String) error.get("traceId")).isNotBlank();
       assertThat(request("POST", base + "/inbox/read", null, ADMIN, null).statusCode()).isEqualTo(400);
       assertThat(request("GET", base + "/inbox/summary", null, "nobody", null).statusCode()).isEqualTo(403);
       assertThat(request("GET", base + "/record-panel?tableName=widget&recordId=1", null, OUTSIDER, null).statusCode()).isEqualTo(403);

src/test/java/com/kingsrook/qbits/alerts/AlertsQBitProducerTest.java

@@ -64,6 +64,8 @@ class AlertsQBitProducerTest extends BaseAlertsTest
    void testProduce()
    {
       assertThat(qInstance.getQBits()).hasSize(1);
+      assertThat(System.getProperty("qbit.artifactVersion")).isNotBlank().isEqualTo(AlertsQBitProducer.VERSION);
+      assertThat(qInstance.getQBits().values().iterator().next().getVersion()).isEqualTo(System.getProperty("qbit.artifactVersion"));
       assertThat(qInstance.getQBits().values().iterator().next().getArtifactId()).isEqualTo(AlertsQBitProducer.ARTIFACT_ID);
       assertThat(AlertsRuntime.find(qInstance)).isSameAs(runtime);
       assertThat(AlertsRuntime.find(new QInstance())).isNull();

src/test/java/com/kingsrook/qbits/alerts/AlertsSystemSessionTest.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.alerts;
+
+
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.logging.QCollectingLogger;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.session.QSystemUserSession;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** Background threads (the alerts sink, schedulers) run engine work through
+ ** asSystem with no QContext of their own; the system session must be built
+ ** from the runtime instance, not from the (empty) context.
+ *******************************************************************************/
+class AlertsSystemSessionTest extends BaseAlertsTest
+{
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Test
+   void asSystemWithoutContextUsesTheRuntimeInstance() throws Exception
+   {
+      QContext.clear();
+      QCollectingLogger collectingLogger = QLogger.activateCollectingLoggerForClass(QSystemUserSession.class);
+      try
+      {
+         Boolean systemUser = runtime.asSystem(() -> QContext.getQInstance() != null && AlertsSecurity.isSystemUser());
+         assertThat(systemUser).isTrue();
+         assertThat(collectingLogger.getCollectedMessages())
+            .noneMatch(m -> m.getMessage().contains("QInstance was not supplied"));
+      }
+      finally
+      {
+         QLogger.deactivateCollectingLoggerForClass(QSystemUserSession.class);
+      }
+   }
+}

src/test/java/com/kingsrook/qbits/alerts/AlertsTablesGuardrailTest.java

@@ -26,9 +26,10 @@ import java.util.Map;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 import java.util.stream.Stream;
-import com.kingsrook.qbits.alerts.metadata.AlertsHelp;
-import com.kingsrook.qqq.backend.core.model.metadata.help.QHelpContent;
+import com.kingsrook.qbits.alerts.metadata.AlertsProcessesMetaDataProducer;
+import com.kingsrook.qqq.backend.core.model.metadata.help.bundles.HelpBundles;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.testing.HelpBundleAssertions;
 import org.junit.jupiter.api.Test;
 import static org.assertj.core.api.Assertions.assertThat;
 
@@ -58,7 +59,7 @@ class AlertsTablesGuardrailTest extends BaseAlertsTest
       Map.entry("alerts_event", "runtime: the alert timeline"),
       Map.entry("alerts_subscription", "people's own choices; the first alerts admin gets one by the bootstrap rule (AlertsPreferences)"),
       Map.entry("alerts_user_preference", "user content: created per person on their first visit (AlertsPreferences)"),
-      Map.entry("alerts_team", "the host's own people (kof22 seeds its team)"),
+      Map.entry("alerts_team", "the host's own people"),
       Map.entry("alerts_team_member", "the host's own people"),
       Map.entry("alerts_mute", "user content: maintenance windows and mutes people create"),
       Map.entry("alerts_delivery", "runtime log: every delivery attempt"),
@@ -122,31 +123,44 @@ class AlertsTablesGuardrailTest extends BaseAlertsTest
    @Test
    void everyTableHasEmptyStateHelp() throws Exception
    {
-      assertThat(AlertsHelp.entries()).allSatisfy((key, entry) -> assertThat(entry.path("summary").asText().length()).as(key).isLessThanOrEqualTo(120));
+      // Core adds bulk CRUD processes during validation; the qbit owns its declared actions and jobs.
+      var processes = AlertsProcessesMetaDataProducer.buildProcesses(config).stream().map(process -> process.getName()).toList();
+      HelpBundleAssertions.forInstance(qInstance)
+         .bundles("help/qbit-alerts.yaml")
+         .owning(target -> "process".equals(target.kind()) ? processes.contains(target.name()) : target.name().startsWith("alerts"))
+         .assertComplete();
+      var entries = HelpBundles.of(qInstance).getBundles().get(0).getEntries();
+      // Core's gate does not yet require widget and possible-value-source help.
+      var keys = entries.stream().map(entry -> entry.getKey()).toList();
+      qInstance.getWidgets().keySet().stream().filter(name -> name.startsWith("alerts"))
+         .forEach(name -> assertThat(keys).contains("widget:" + name + ";slot:help"));
+      qInstance.getPossibleValueSources().keySet().stream().filter(name -> name.startsWith("alerts"))
+         .forEach(name -> assertThat(keys).contains("possibleValueSource:" + name + ";slot:help"));
       for(String table : alertsTables())
       {
-         List<QHelpContent> help = qInstance.getTable(table).getHelpContent() == null ? null : qInstance.getTable(table).getHelpContent().get(AlertsHelp.SLOT);
-         assertThat(help).as(table + " table help").isNotEmpty();
-         assertThat(help.get(0).getContent()).as(table + " help says how rows get created").contains("How rows get created");
+         assertThat(entries).anySatisfy(entry ->
+         {
+            assertThat(entry.getKey()).isEqualTo("table:" + table + ";slot:help");
+            assertThat(entry.getContent()).contains("How rows get created");
+         });
       }
-      assertThat(qInstance.getApp(AlertsQBitConfig.APP_NAME).getHelpContent()).containsKey(AlertsHelp.SLOT);
-      assertThat(AlertsHelp.entries().keySet()).allMatch(key -> !key.startsWith("table:") || qInstance.getTable(key.substring(6, key.indexOf(';'))) != null,
-         "help names only real tables");
    }
 
 
 
    /*******************************************************************************
-    ** A host's own help on a table is kept; the bundle fills only empty slots.
+    ** Bundle registration needs no help table; core safely skips startup sync.
     *******************************************************************************/
    @Test
-   void hostHelpIsNotOverridden() throws Exception
+   void hostWithoutHelpTableIsSupported()
    {
-      QTableMetaData table = qInstance.getTable("alerts_channel");
-      table.getHelpContent().remove(AlertsHelp.SLOT);
-      table.withHelpContent(AlertsHelp.SLOT, new QHelpContent().withContentAsMarkdown("host text"));
-      AlertsHelp.apply(qInstance);
-      assertThat(table.getHelpContent().get(AlertsHelp.SLOT)).singleElement().matches(c -> "host text".equals(c.getContent()));
+      assertThat(qInstance.getTable("helpContent")).isNull();
+      assertThat(HelpBundles.of(qInstance).getBundles()).singleElement().satisfies(bundle ->
+      {
+         assertThat(bundle.getId()).isEqualTo("qbit-alerts");
+         assertThat(bundle.getVersion()).as("the help bundle carries the artifact and producer version").isEqualTo(System.getProperty("qbit.artifactVersion")).isEqualTo(AlertsQBitProducer.VERSION);
+      });
+      HelpBundles.syncOnStartup(qInstance);
    }
 
 

src/test/java/com/kingsrook/qbits/alerts/engine/RoutingAndDeliveryTest.java

@@ -135,6 +135,76 @@ class RoutingAndDeliveryTest extends BaseAlertsTest
 
 
 
+   /*******************************************************************************
+    ** First calls for one user race (the home widgets and the bell load
+    ** together): only one bootstrap subscription is created.
+    *******************************************************************************/
+   @Test
+   void testConcurrentFirstCallsBootstrapOnce() throws Exception
+   {
+      com.kingsrook.qqq.backend.core.context.CapturedContext context = QContext.capture();
+      java.util.concurrent.ExecutorService pool = java.util.concurrent.Executors.newFixedThreadPool(4);
+      try
+      {
+         java.util.concurrent.CountDownLatch start = new java.util.concurrent.CountDownLatch(1);
+         List<java.util.concurrent.Future<Object>> futures = new java.util.ArrayList<>();
+         for(int i = 0; i < 4; i++)
+         {
+            futures.add(pool.submit(() ->
+            {
+               QContext.init(context);
+               start.await();
+               AlertsPreferences.ensure(runtime, QContext.getQSession());
+               return (null);
+            }));
+         }
+         start.countDown();
+         for(java.util.concurrent.Future<Object> future : futures)
+         {
+            future.get();
+         }
+      }
+      finally
+      {
+         pool.shutdownNow();
+      }
+      assertThat(all(AlertsSubscription.TABLE_NAME)).hasSize(1);
+      assertThat(all(AlertsUserPreference.TABLE_NAME)).hasSize(1);
+   }
+
+
+
+   /*******************************************************************************
+    ** Another replica raced and left a second bootstrap subscription: the next
+    ** first call keeps the oldest and leaves a person's own subscriptions alone.
+    *******************************************************************************/
+   @Test
+   void testDuplicateBootstrapSubscriptionsAreRemoved() throws Exception
+   {
+      for(String creator : List.of("alerts (bootstrap rule)", "alerts (bootstrap rule)", ADMIN))
+      {
+         runtime.asSystem(() -> AlertsDb.insert(AlertsSubscription.TABLE_NAME, new QRecord()
+            .withValue("subscriberType", "USER")
+            .withValue("userId", ADMIN)
+            .withValue("scopeType", "ALL")
+            .withValue("minSeverity", "ERROR")
+            .withValue("events", "RAISED")
+            .withValue("deliveryMode", "IMMEDIATE")
+            .withValue("enabled", true)
+            .withValue("createdByUserId", creator)));
+      }
+      List<QRecord> before = all(AlertsSubscription.TABLE_NAME);
+      assertThat(before).hasSize(3);
+
+      AlertsPreferences.ensure(runtime, QContext.getQSession());
+
+      List<QRecord> after = all(AlertsSubscription.TABLE_NAME);
+      assertThat(after).hasSize(2);
+      assertThat(after).extracting(r -> r.getValueInteger("id")).containsExactlyInAnyOrder(before.get(0).getValueInteger("id"), before.get(2).getValueInteger("id"));
+   }
+
+
+
    /*******************************************************************************
     ** No subscriptions: nobody is notified. The bootstrap rule gives admins an
     ** in-app subscription to ERROR and worse on first visit.

src/test/java/com/kingsrook/qbits/alerts/engine/RuntimeFieldsAuditTest.java

@@ -0,0 +1,166 @@
+/*
+ * 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.alerts.engine;
+
+
+import java.sql.Connection;
+import java.sql.Statement;
+import java.time.Instant;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.alerts.BaseAlertsTest;
+import com.kingsrook.qbits.alerts.model.AlertsAlert;
+import com.kingsrook.qbits.alerts.model.AlertsMonitor;
+import com.kingsrook.qbits.alerts.model.AlertsType;
+import com.kingsrook.qqq.backend.core.alerts.AlertSeverity;
+import com.kingsrook.qqq.backend.core.alerts.AlertsInstanceMetaData;
+import com.kingsrook.qqq.backend.core.alerts.QAlertTypeMetaData;
+import com.kingsrook.qqq.backend.core.instances.QInstanceEnricher;
+import com.kingsrook.qqq.backend.core.model.audits.AuditsMetaDataProvider;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.utils.JsonUtils;
+import com.kingsrook.qqq.backend.module.rdbms.jdbc.ConnectionManager;
+import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSBackendMetaData;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** Engine bookkeeping writes (monitor leases and run results, alert reminder
+ ** and notification timers) create no audit rows; configuration edits and
+ ** alert state changes still do.
+ *******************************************************************************/
+class RuntimeFieldsAuditTest extends BaseAlertsTest
+{
+   static final String TYPE = "test.widget.broken";
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Override
+   protected void customizeInstance(QInstance qInstance)
+   {
+      AlertsInstanceMetaData.ofOrWithNew(qInstance)
+         .withAlertType(new QAlertTypeMetaData().withName(TYPE).withLabel("Widget broken").withGroupName("widgets").withSubjectTableName(WIDGET).withDefaultSeverity(AlertSeverity.WARNING));
+   }
+
+
+
+   /*******************************************************************************
+    ** Core audit tables on the test backend.
+    *******************************************************************************/
+   @BeforeEach
+   void auditTables() throws Exception
+   {
+      new AuditsMetaDataProvider().defineAll(qInstance, BACKEND_NAME, null);
+      new QInstanceEnricher(qInstance).enrich();
+      try(Connection connection = ConnectionManager.getConnection((RDBMSBackendMetaData) qInstance.getBackend(BACKEND_NAME)); Statement statement = connection.createStatement())
+      {
+         for(String table : List.of("auditDetail", "audit", "auditUser", "auditTable"))
+         {
+            statement.execute("DROP TABLE IF EXISTS " + table);
+         }
+         statement.execute("CREATE TABLE auditUser (id INTEGER AUTO_INCREMENT PRIMARY KEY, name VARCHAR(200), createDate TIMESTAMP, modifyDate TIMESTAMP)");
+         statement.execute("CREATE TABLE auditTable (id INTEGER AUTO_INCREMENT PRIMARY KEY, name VARCHAR(200), label VARCHAR(200), createDate TIMESTAMP, modifyDate TIMESTAMP)");
+         statement.execute("CREATE TABLE audit (id BIGINT AUTO_INCREMENT PRIMARY KEY, auditTableId INTEGER, auditUserId INTEGER, recordId INTEGER, message VARCHAR(250), timestamp TIMESTAMP)");
+         statement.execute("CREATE TABLE auditDetail (id BIGINT AUTO_INCREMENT PRIMARY KEY, auditId BIGINT, message VARCHAR(250), fieldName VARCHAR(100), oldValue VARCHAR(250), newValue VARCHAR(250))");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Edited-record audits for one table.
+    *******************************************************************************/
+   private List<QRecord> edits(String tableName) throws Exception
+   {
+      List<QRecord> tables = where("auditTable", AlertsDb.eq("name", tableName));
+      if(tables.isEmpty())
+      {
+         return (List.of());
+      }
+      return (where("audit", AlertsDb.eq("auditTableId", tables.get(0).getValue("id")).withCriteria("message", com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator.EQUALS, "Record was Edited")));
+   }
+
+
+
+   /*******************************************************************************
+    ** Changed field names of one table's edit audits.
+    *******************************************************************************/
+   private List<String> editedFields(String tableName) throws Exception
+   {
+      List<Object> ids = edits(tableName).stream().map(r -> r.getValue("id")).map(Object.class::cast).toList();
+      return (all("auditDetail").stream().filter(d -> ids.contains(d.getValue("auditId"))).map(d -> d.getValueString("fieldName")).toList());
+   }
+
+
+
+   /*******************************************************************************
+    ** The classifier: bookkeeping only, or not.
+    *******************************************************************************/
+   @Test
+   void classifiesBookkeepingOnlyUpdates()
+   {
+      assertThat(RuntimeFields.onlyRuntime(AlertsMonitor.TABLE_NAME, new QRecord().withValue("id", 1).withValue("claimedBy", "x").withValue("claimedUntil", Instant.now()))).isTrue();
+      assertThat(RuntimeFields.onlyRuntime(AlertsMonitor.TABLE_NAME, new QRecord().withValue("id", 1).withValue("lastRunAt", Instant.now()).withValue("enabled", false))).isFalse();
+      assertThat(RuntimeFields.onlyRuntime(AlertsAlert.TABLE_NAME, new QRecord().withValue("id", 1).withValue("timedNotificationCheckedAt", Instant.now()))).isTrue();
+      assertThat(RuntimeFields.onlyRuntime(AlertsAlert.TABLE_NAME, new QRecord().withValue("id", 1).withValue("status", "ACKNOWLEDGED"))).isFalse();
+      assertThat(RuntimeFields.onlyRuntime(WIDGET, new QRecord().withValue("id", 1).withValue("checkedAt", Instant.now()))).isFalse();
+   }
+
+
+
+   /*******************************************************************************
+    ** Evaluations and reminder checks write no monitor or alert edit audits;
+    ** an admin edit and an acknowledgement do.
+    *******************************************************************************/
+   @Test
+   void evaluationsAreNotAuditedButEditsAndTransitionsAre() throws Exception
+   {
+      insertWidgets("BROKEN", "OK");
+      runtime.getTypeSync().syncIfNeeded();
+      QRecord type = runtime.asSystem(() -> AlertsDb.first(AlertsType.TABLE_NAME, AlertsDb.eq("name", TYPE)));
+      Integer monitorId = runtime.asSystem(() -> AlertsDb.insert(AlertsMonitor.TABLE_NAME, new QRecord()
+         .withValue("name", "Broken widgets").withValue("alertTypeId", type.getValue("id")).withValue("kind", "TABLE_QUERY").withValue("enabled", true)
+         .withValue("definition", JsonUtils.toJson(Map.of("tableName", WIDGET, "filter", Map.of("criteria", List.of(Map.of("fieldName", "status", "operator", "EQUALS", "values", List.of("BROKEN")))))))
+         .withValue("perRecord", false).withValue("scheduleSeconds", 60).withValue("forMinutes", 0).withValue("consecutiveFailures", 0)).getValueInteger("id"));
+
+      for(int run = 0; run < 3; run++)
+      {
+         runtime.getEvaluator().evaluateDue();
+         new EscalationAndReminder(runtime).runDue();
+         clock.advance(java.time.Duration.ofMinutes(2));
+      }
+      assertThat(runtime.asSystem(() -> AlertsDb.byId(AlertsMonitor.TABLE_NAME, monitorId)).getValueInstant("lastRunAt")).isNotNull();
+      assertThat(edits(AlertsMonitor.TABLE_NAME)).as("monitor runs are bookkeeping").isEmpty();
+      assertThat(editedFields(AlertsAlert.TABLE_NAME)).as("reminder checks and ref counts are bookkeeping")
+         .doesNotContain("timedNotificationCheckedAt", "recordRefCount", "lastNotifiedAt");
+
+      runtime.asSystem(() -> AlertsDb.update(AlertsMonitor.TABLE_NAME, new QRecord().withValue("id", monitorId).withValue("name", "Broken widgets (renamed)")));
+      runtime.asSystem(() -> AlertsDb.update(AlertsMonitor.TABLE_NAME, new QRecord().withValue("id", monitorId).withValue("enabled", false).withValue("nextRunAt", null)));
+      assertThat(edits(AlertsMonitor.TABLE_NAME)).hasSize(2);
+      assertThat(editedFields(AlertsMonitor.TABLE_NAME)).contains("name", "enabled");
+
+      QRecord alert = where(AlertsAlert.TABLE_NAME, AlertsDb.eq("monitorId", monitorId)).get(0);
+      runtime.getEngine().acknowledge(alert.getValueInteger("id"), ADMIN);
+      assertThat(editedFields(AlertsAlert.TABLE_NAME)).contains("status");
+   }
+}

src/test/java/com/kingsrook/qbits/alerts/notifications/NotificationEmailAndNoticesTest.java

@@ -172,6 +172,232 @@ class NotificationEmailAndNoticesTest extends BaseAlertsTest
 
 
 
+   /*******************************************************************************
+    ** A requested email does not require a standing category preference.
+    *******************************************************************************/
+   @Test
+   void testRequestedWithoutPreference() throws Exception
+   {
+      addressOnly();
+      requested("JOB");
+      assertThat(new NotificationEmailer(runtime).run().sent()).isEqualTo(1);
+      assertThat(emailStatus("viewer-1")).isEqualTo("SENT");
+      assertThat(new NotificationEmailer(runtime).run().sent()).isZero();
+      assertThat(SENT).hasSize(1);
+   }
+
+
+
+   /*******************************************************************************
+    ** An explicit request and an immediate preference still send only once.
+    *******************************************************************************/
+   @Test
+   void testRequestedWithImmediatePreference() throws Exception
+   {
+      emailSettings("viewer-1", "JOB", "IMMEDIATE", "INFO");
+      requested("JOB");
+      assertThat(new NotificationEmailer(runtime).run().sent()).isEqualTo(1);
+      assertThat(new NotificationEmailer(runtime).run().sent()).isZero();
+      assertThat(SENT).hasSize(1);
+   }
+
+
+
+   /*******************************************************************************
+    ** A request overrides digest timing (not the category's minimum severity).
+    *******************************************************************************/
+   @Test
+   void testRequestedWithDigestPreference() throws Exception
+   {
+      emailSettings("viewer-1", "JOB", "DAILY_DIGEST", "INFO");
+      requested("JOB");
+      NotificationEmailer.Result result = new NotificationEmailer(runtime).run();
+      assertThat(result.sent()).isEqualTo(1);
+      assertThat(result.digests()).isZero();
+      assertThat(SENT).hasSize(1);
+   }
+
+
+
+   /*******************************************************************************
+    ** Knowing an address alone does not opt a notification into email.
+    *******************************************************************************/
+   @Test
+   void testNotRequestedWithoutPreference() throws Exception
+   {
+      addressOnly();
+      runtime.getNotifications().notify(new NotificationSignal("Done").withCategory(NotificationCategory.JOB)
+         .withAudience(NotificationAudience.user("viewer-1")));
+      assertThat(new NotificationEmailer(runtime).run().sent()).isZero();
+      assertThat(emailStatus("viewer-1")).isEqualTo("NONE");
+      assertThat(SENT).isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** Missing addresses are skipped rather than counted as delivery failures.
+    *******************************************************************************/
+   @Test
+   void testRequestedWithoutAddress() throws Exception
+   {
+      requested("JOB");
+      NotificationEmailer.Result result = new NotificationEmailer(runtime).run();
+      assertThat(result.skipped()).isEqualTo(1);
+      assertThat(result.failed()).isZero();
+      assertThat(emailStatus("viewer-1")).isEqualTo("SKIPPED");
+      assertThat(SENT).isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** Alert subscriptions own alert emails, even with an explicit request.
+    *******************************************************************************/
+   @Test
+   void testRequestedAlertNeverEmailed() throws Exception
+   {
+      emailSettings("viewer-1", "ALERT", "IMMEDIATE", "INFO");
+      requested("ALERT");
+      assertThat(new NotificationEmailer(runtime).run().skipped()).isEqualTo(1);
+      assertThat(emailStatus("viewer-1")).isEqualTo("SKIPPED");
+      assertThat(SENT).isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** Requests older than the delivery window are not emailed.
+    *******************************************************************************/
+   @Test
+   void testRequestedOutsideDeliveryWindow() throws Exception
+   {
+      addressOnly();
+      requested("JOB");
+      clock.set(clock.instant().plusSeconds(86401));
+      assertThat(new NotificationEmailer(runtime).run().sent()).isZero();
+      assertThat(emailStatus("viewer-1")).isEqualTo("REQUESTED");
+      assertThat(SENT).isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** Provider failures remain terminal and do not cause repeated sends.
+    *******************************************************************************/
+   @Test
+   void testRequestedDeliveryFailure() throws Exception
+   {
+      addressOnly();
+      requested("JOB");
+      runtime.getConfig().withMessagingProviderName("missing-provider");
+      NotificationEmailer.Result result = new NotificationEmailer(runtime).run();
+      assertThat(result.failed()).isEqualTo(1);
+      assertThat(emailStatus("viewer-1")).isEqualTo("FAILED");
+      assertThat(new NotificationEmailer(runtime).run().failed()).isZero();
+      assertThat(SENT).isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** A request still honours the category's email minimum severity.
+    *******************************************************************************/
+   @Test
+   void testRequestedBelowMinSeverity() throws Exception
+   {
+      emailSettings("viewer-1", "JOB", "OFF", "ERROR");
+      requested("JOB");
+      NotificationEmailer.Result result = new NotificationEmailer(runtime).run();
+      assertThat(result.skipped()).isEqualTo(1);
+      assertThat(emailStatus("viewer-1")).isEqualTo("SKIPPED");
+      assertThat(SENT).isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** A user's pause or quiet hours hold a requested email until they end.
+    *******************************************************************************/
+   @Test
+   void testRequestedHeldByPauseAndQuietHours() throws Exception
+   {
+      clock.set(Instant.parse("2026-10-12T12:00:00Z"));
+      addressOnly();
+      requested("JOB");
+      setUserPreference(new QRecord().withValue("pausedUntil", clock.instant().plusSeconds(3600)));
+      assertThat(new NotificationEmailer(runtime).run().sent()).isZero();
+      assertThat(emailStatus("viewer-1")).isEqualTo("REQUESTED");
+
+      clock.set(Instant.parse("2026-10-12T13:30:00Z"));
+      setUserPreference(new QRecord().withValue("timeZone", "UTC").withValue("quietHoursStart", "13:00").withValue("quietHoursEnd", "14:00"));
+      assertThat(new NotificationEmailer(runtime).run().sent()).isZero();
+      assertThat(emailStatus("viewer-1")).isEqualTo("REQUESTED");
+
+      clock.set(Instant.parse("2026-10-12T14:00:00Z"));
+      assertThat(new NotificationEmailer(runtime).run().sent()).isEqualTo(1);
+      assertThat(emailStatus("viewer-1")).isEqualTo("SENT");
+      assertThat(SENT).hasSize(1);
+   }
+
+
+
+   /*******************************************************************************
+    ** A pause does not hold a requested SECURITY email.
+    *******************************************************************************/
+   @Test
+   void testRequestedSecurityBypassesPause() throws Exception
+   {
+      addressOnly();
+      requested("SECURITY");
+      setUserPreference(new QRecord().withValue("pausedUntil", clock.instant().plusSeconds(3600)));
+      assertThat(new NotificationEmailer(runtime).run().sent()).isEqualTo(1);
+   }
+
+
+
+   /*******************************************************************************
+    ** Update the user's alert settings row.
+    *******************************************************************************/
+   private void setUserPreference(QRecord values) throws QException
+   {
+      runtime.asSystem(() ->
+      {
+         QRecord setting = AlertsDb.first(AlertsUserPreference.TABLE_NAME, AlertsDb.eq("userId", "viewer-1"));
+         return (AlertsDb.update(AlertsUserPreference.TABLE_NAME, values.withValue("id", setting.getValue("id"))));
+      });
+   }
+
+
+
+   /*******************************************************************************
+    ** Store an address without opting into any category.
+    *******************************************************************************/
+   private void addressOnly() throws QException
+   {
+      runtime.asSystem(() -> AlertsDb.insert(AlertsUserPreference.TABLE_NAME,
+         new QRecord().withValue("userId", "viewer-1").withValue("emailAddress", "viewer-1@example.com")));
+   }
+
+
+
+   /*******************************************************************************
+    ** Set up a recipient explicitly requesting email for worker tests.
+    *******************************************************************************/
+   private void requested(String category) throws QException
+   {
+      Integer id = runtime.getNotifications().notify(new NotificationSignal("Done").withCategory(NotificationCategory.valueOf(category))
+         .withAudience(NotificationAudience.user("viewer-1")));
+      runtime.asSystem(() ->
+      {
+         QRecord recipient = AlertsDb.first(AlertsNotificationRecipient.TABLE_NAME, AlertsDb.eq("notificationId", id));
+         return (AlertsDb.update(AlertsNotificationRecipient.TABLE_NAME,
+            new QRecord().withValue("id", recipient.getValue("id")).withValue("emailStatus", "REQUESTED")));
+      });
+   }
+
+
+
    /*******************************************************************************
     ** The daily digest waits for the user's hour, then lists the unread ones.
     *******************************************************************************/

src/test/java/com/kingsrook/qbits/alerts/notifications/NotificationSlackTest.java

@@ -21,6 +21,7 @@ package com.kingsrook.qbits.alerts.notifications;
 import java.time.Duration;
 import java.time.Instant;
 import java.util.List;
+import java.util.Set;
 import java.util.concurrent.CopyOnWriteArrayList;
 import com.kingsrook.qbits.alerts.AlertsPreferences;
 import com.kingsrook.qbits.alerts.AlertsQBitConfig;
@@ -42,6 +43,7 @@ import com.kingsrook.qqq.backend.core.model.actions.messaging.SendMessageInput;
 import com.kingsrook.qqq.backend.core.model.actions.messaging.SendMessageOutput;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.metadata.messaging.QMessagingProviderMetaData;
+import com.kingsrook.qqq.backend.core.modules.messaging.MessagingProviderCapability;
 import com.kingsrook.qqq.backend.core.modules.messaging.MessagingProviderInterface;
 import com.kingsrook.qqq.backend.core.modules.messaging.QMessagingProviderDispatcher;
 import org.junit.jupiter.api.Test;
@@ -57,6 +59,7 @@ class NotificationSlackTest extends BaseAlertsTest
    static final List<SendMessageInput> SENT = new CopyOnWriteArrayList<>();
 
    static volatile String failureMode = "NONE";
+   static boolean idempotency;
 
 
 
@@ -76,6 +79,17 @@ class NotificationSlackTest extends BaseAlertsTest
 
 
 
+      /*******************************************************************************
+       ** Advertise optional provider deduplication.
+       *******************************************************************************/
+      @Override
+      public Set<MessagingProviderCapability> getCapabilities()
+      {
+         return (idempotency ? Set.of(MessagingProviderCapability.IDEMPOTENCY) : Set.of());
+      }
+
+
+
       /*******************************************************************************
        **
        *******************************************************************************/
@@ -107,6 +121,7 @@ class NotificationSlackTest extends BaseAlertsTest
       qInstance.addMessagingProvider(new QMessagingProviderMetaData().withName("slack").withType("alerts-slack-capture"));
       SENT.clear();
       failureMode = "NONE";
+      idempotency = false;
    }
 
 
@@ -187,6 +202,7 @@ class NotificationSlackTest extends BaseAlertsTest
          assertThat(message.getMessagingProviderName()).isEqualTo("slack");
          assertThat(message.getTo().getAddress()).isEqualTo("user:viewer-1");
          assertThat(message.getSubject()).isEqualTo("Export failed");
+         assertThat(message.getIdempotencyKey()).isNull();
          assertThat(text(message)).contains("Export failed").contains("Disk full").contains("https://admin.example.com/app/widget");
       });
       assertThat(slackStatus("viewer-1")).isEqualTo("SENT");
@@ -200,6 +216,22 @@ class NotificationSlackTest extends BaseAlertsTest
 
 
 
+   /*******************************************************************************
+    ** Capable providers receive a stable key for immediate notifications.
+    *******************************************************************************/
+   @Test
+   void testIdempotencyKey() throws Exception
+   {
+      idempotency = true;
+      slackSettings("viewer-1", "JOB", "IMMEDIATE", "WARNING", null);
+      notifyJob("Export failed", NotificationSeverity.WARNING, "viewer-1");
+      assertThat(new NotificationSlackSender(runtime).run().sent()).isEqualTo(1);
+      assertThat(SENT).singleElement().satisfies(message ->
+         assertThat(message.getIdempotencyKey()).matches("notify:[0-9]+:viewer-1:slack"));
+   }
+
+
+
    /*******************************************************************************
     ** A category muted in-app gets no recipient row, so no Slack message.
     *******************************************************************************/