feat(failure): surface recorded failures in a notification bell

Failures have been durable and actionable since #7269 and reportable from
the editor since #7296, but the only way to see one was a dev-only list at
the bottom of the processor's Documents view. This puts them in front of
the person who can act.

An action is declared as data, not rendered by rules the client hard-codes.
A FailureKind offers each action with an audience (the file's owner, the
team's reviewer, or anyone who can see the row) and a slot, and the server
resolves both against who is reading. Ownership is derived per reader from
the row's actor rather than stored. So a new failure kind ships as a
registry entry plus copy, and needs no frontend change at all.

Which actions the server runs and which the client runs are now distinct:
FailureActionId carries an Execution facet, the registry only requires a
bean for a server action, and dispatching a client action is refused. Retry,
decrypt-and-retry, view file and view in processor are the client's; dismiss
stays the server's.

The client hides an action it cannot perform rather than showing it
disabled, and surfaces the server's reason as the row's note instead. A
greyed-out button that can never work reads as false hope, and a note says
the same thing honestly.

Notifications derive from failures on read rather than living in a table of
their own: one source today, and a table would need a write path, retention
and a per-user read model before it earned itself. Every id on the
notification endpoints is prefixed, so the bell can never hand a raw
failure id to a failure endpoint.

An attended policy run now records which document it was about, which is
what lets a repeat fold onto one incident instead of opening a new one per
upload, lets deleting the file clear its failure, and lets the owner open
the document from the row.

The failures list in the processor stays gated behind import.meta.env.DEV,
and the bell's "view in processor" action is gated the same way, so it
cannot point at a section that is not mounted. Both lift together when
failures get their own review screen.

The read scope itself is unchanged here: #7477 decides who may see which
row, and this commit only decides what each reader is offered about a row
they can already see.

Author: EthanHealy01

app/proprietary/src/main/java/stirling/software/proprietary/failure/FailureActionException.java

@@ -1,10 +1,13 @@
 package stirling.software.proprietary.failure;
 
+import org.springframework.http.HttpStatus;
+
 import lombok.Getter;
 
 /**
- * Why an action could not be dispatched. Carries a {@link Reason} rather than an HTTP status, so
- * the service stays web-agnostic and the controller owns the mapping.
+ * Why an action could not be dispatched. Thrown carrying a {@link Reason} rather than an HTTP
+ * status, so the service stays web-agnostic and only a controller ever reaches for {@link
+ * #statusOf}.
  */
 @Getter
 public class FailureActionException extends RuntimeException {
@@ -23,14 +26,17 @@ public enum Reason {
 
         /**
          * The action exists but this kind does not declare it, so an incoherent pairing (releasing
-         * a document whose destination is what failed) cannot be dispatched even by hand.
-         *
-         * <p>Unreachable today: both kinds declare both actions, so no request can trip this guard
-         * until a kind ships with a restricted action set. Declared now because the guard must
-         * exist before that kind does, not after.
+         * a document whose destination is what failed) cannot be dispatched even by hand. Reachable
+         * as of the kinds that stopped offering {@link FailureActionId#ACKNOWLEDGE}.
          */
         ACTION_NOT_DECLARED,
 
+        /**
+         * The kind offers it, but the client is what runs it (see {@link
+         * FailureActionId.Execution#CLIENT}), so it is refused rather than half-performed.
+         */
+        ACTION_NOT_DISPATCHABLE,
+
         /** The event is already closed, so no further transition is possible. */
         ALREADY_CLOSED
     }
@@ -46,4 +52,22 @@ public FailureActionException(Reason reason, String message, Throwable cause) {
         super(message, cause);
         this.reason = reason;
     }
+
+    /**
+     * The HTTP status each refusal reason answers with. Lives with the reasons it maps, so the two
+     * surfaces that dispatch actions, the failure queue and the notification bell, cannot drift
+     * apart and a client's error handling does not depend on which one it called.
+     *
+     * <p>A closed row is a conflict rather than a bad request: the request was well-formed and
+     * would have been valid a moment earlier. A missing row is a 404 whether it never existed,
+     * belongs to another team or is a colleague's, so trying does not confirm which.
+     */
+    public static HttpStatus statusOf(Reason reason) {
+        return switch (reason) {
+            case EVENT_NOT_FOUND -> HttpStatus.NOT_FOUND;
+            case ACTION_NOT_RECOGNISED, ACTION_NOT_DECLARED, ACTION_NOT_DISPATCHABLE ->
+                    HttpStatus.BAD_REQUEST;
+            case ALREADY_CLOSED -> HttpStatus.CONFLICT;
+        };
+    }
 }

app/proprietary/src/main/java/stirling/software/proprietary/failure/FailureActionId.java

@@ -1,11 +1,70 @@
 package stirling.software.proprietary.failure;
 
+import lombok.Getter;
+
 /**
- * The actions a {@link FailureKind} may declare. Both are incident dispositions: they change how
- * the event is shown and touch nothing else, which is what makes them valid for every kind
- * including {@link FailureKind#UNKNOWN}, and why there is no {@code APPROVE} yet.
+ * The actions a {@link FailureKind} may declare, and which side of the wire runs each one.
+ *
+ * <p>The dispositions are the server's: they change how the event is shown and touch nothing else,
+ * which is what makes them valid for every kind including {@link FailureKind#UNKNOWN}. Everything
+ * else is the client's, because the server holds an opaque id for the document and nothing more.
+ *
+ * <p>Client actions are still declared here rather than invented by each client, so the server
+ * keeps deciding what a kind offers, in what order and under what label.
  */
+@Getter
 public enum FailureActionId {
-    ACKNOWLEDGE,
-    DISMISS
+
+    /**
+     * "Seen, and I own it." No kind offers this any more, but rows shipped before that are already
+     * {@code ACKNOWLEDGED} and must stay readable and closable.
+     */
+    ACKNOWLEDGE(Execution.SERVER, "Acknowledge"),
+
+    /** "No remediation will happen; close it." See {@link DismissAction}. */
+    DISMISS(Execution.SERVER, "Dismiss"),
+
+    /** Run the failed operation again on the document the client still holds. */
+    RETRY(Execution.CLIENT, "Retry"),
+
+    /** Ask the owner for the password, unlock the document in their client, then retry. */
+    DECRYPT_AND_RETRY(Execution.CLIENT, "Decrypt and retry"),
+
+    /** Open the document this incident is about. Only its owner's client can resolve the id. */
+    VIEW_FILE(Execution.CLIENT, "View file"),
+
+    /** Open the run behind it, for whoever reviews the team rather than owns the document. */
+    VIEW_IN_PROCESSOR(Execution.CLIENT, "View in processor");
+
+    /**
+     * Which side of the wire runs the action. The dispatch endpoint refuses a {@code CLIENT} id, so
+     * "the client does this one" is enforced rather than merely documented.
+     */
+    public enum Execution {
+
+        /**
+         * Dispatchable, and {@link FailureActionRegistry} requires a {@link FailureAction} bean.
+         */
+        SERVER,
+
+        /**
+         * Declared and rendered, never dispatched: the server has neither the file nor the tool.
+         */
+        CLIENT
+    }
+
+    private final Execution execution;
+
+    /** English fallback, used when the client has no translation for the action's label key. */
+    private final String defaultLabel;
+
+    FailureActionId(Execution execution, String defaultLabel) {
+        this.execution = execution;
+        this.defaultLabel = defaultLabel;
+    }
+
+    /** Whether the server runs it itself, which is also whether it can be dispatched. */
+    public boolean runsOnServer() {
+        return execution == Execution.SERVER;
+    }
 }

app/proprietary/src/main/java/stirling/software/proprietary/failure/FailureActionRegistry.java

@@ -16,6 +16,9 @@
  * Resolves a {@link FailureActionId} to the bean that implements it. The startup check is the
  * point: because kinds declare action ids as data, one could name an action nobody implements,
  * which would otherwise show up as a button that 400s rather than as a failed boot.
+ *
+ * <p>Only {@link FailureActionId.Execution#SERVER} ids belong here. A client action has no bean by
+ * design, and a bean for one is refused outright because dispatch could never reach it.
  */
 @Slf4j
 @Service
@@ -25,6 +28,14 @@ public class FailureActionRegistry {
 
     public FailureActionRegistry(List<FailureAction> actions) {
         for (FailureAction action : actions) {
+            if (!action.id().runsOnServer()) {
+                throw new IllegalStateException(
+                        "Action "
+                                + action.id()
+                                + " is run by the client, so "
+                                + action.getClass().getName()
+                                + " could never be dispatched");
+            }
             FailureAction clash = byId.put(action.id(), action);
             if (clash != null) {
                 throw new IllegalStateException(
@@ -39,8 +50,8 @@ public FailureActionRegistry(List<FailureAction> actions) {
     }
 
     /**
-     * Fail fast if any kind declares an action with no handler, naming every gap rather than the
-     * first, so one boot tells you everything that is missing.
+     * Fail fast if any kind declares a server action with no handler, naming every gap rather than
+     * the first, so one boot tells you everything that is missing.
      */
     @PostConstruct
     void verifyEveryDeclaredActionHasAHandler() {
@@ -49,6 +60,7 @@ void verifyEveryDeclaredActionHasAHandler() {
                         .flatMap(
                                 kind ->
                                         kind.getActions().stream()
+                                                .filter(FailureActionId::runsOnServer)
                                                 .filter(action -> !byId.containsKey(action))
                                                 .map(action -> kind.getId() + " -> " + action))
                         .toList();

app/proprietary/src/main/java/stirling/software/proprietary/failure/FailureActionSlot.java

@@ -0,0 +1,21 @@
+package stirling.software.proprietary.failure;
+
+/**
+ * Where a kind would like one of its actions to sit: the thing that fixes it, a supporting action,
+ * or one folded away in a menu.
+ *
+ * <p>Intent, not layout. The client does the final promotion, because only it knows whether the
+ * document is still in its own file store, and a resolution it cannot run is worth less than a
+ * secondary action it can. Declaration order in {@link FailureKind} breaks a tie within a slot.
+ */
+public enum FailureActionSlot {
+
+    /** The action that resolves the failure. At most one per kind is worth declaring here. */
+    RESOLUTION,
+
+    /** Offered alongside the resolution, for a caller the resolution is not aimed at. */
+    SECONDARY,
+
+    /** Available but folded away: correct, rarely the next thing anyone wants to press. */
+    OVERFLOW
+}

app/proprietary/src/main/java/stirling/software/proprietary/failure/FailureAudience.java

@@ -0,0 +1,20 @@
+package stirling.software.proprietary.failure;
+
+/**
+ * Who an offered action is for. The read scope has already decided the caller may see the incident;
+ * this decides which of its actions are theirs to take.
+ *
+ * <p>The distinction is possession, not seniority: a reviewer clearing up after a colleague cannot
+ * supply that colleague's password or reach a document only their browser holds.
+ */
+public enum FailureAudience {
+
+    /** The person whose work failed, whose own client still holds the document. */
+    OWNER,
+
+    /** Anyone who triages the team's incidents, whoever hit them. */
+    TEAM_REVIEWER,
+
+    /** Everyone the incident is shown to at all. */
+    ANYONE_WHO_SEES
+}

app/proprietary/src/main/java/stirling/software/proprietary/failure/FailureKind.java

@@ -1,7 +1,15 @@
 package stirling.software.proprietary.failure;
 
-import static stirling.software.proprietary.failure.FailureActionId.ACKNOWLEDGE;
+import static stirling.software.proprietary.failure.FailureActionId.DECRYPT_AND_RETRY;
 import static stirling.software.proprietary.failure.FailureActionId.DISMISS;
+import static stirling.software.proprietary.failure.FailureActionId.RETRY;
+import static stirling.software.proprietary.failure.FailureActionId.VIEW_FILE;
+import static stirling.software.proprietary.failure.FailureActionId.VIEW_IN_PROCESSOR;
+import static stirling.software.proprietary.failure.FailureActionSlot.OVERFLOW;
+import static stirling.software.proprietary.failure.FailureActionSlot.SECONDARY;
+import static stirling.software.proprietary.failure.FailureAudience.ANYONE_WHO_SEES;
+import static stirling.software.proprietary.failure.FailureAudience.OWNER;
+import static stirling.software.proprietary.failure.FailureAudience.TEAM_REVIEWER;
 
 import java.util.Arrays;
 import java.util.HashMap;
@@ -20,13 +28,14 @@
  * The registry of failure kinds, described as data: a stable id, i18n keys and an English fallback
  * like {@code ExceptionUtils.ErrorCode}, plus the facets a review surface needs.
  *
- * <p>Actions are declared here but implemented in {@link FailureAction} beans resolved by id, so a
- * new kind ships as a registry entry plus copy. Two members today: {@link #UNKNOWN} gives every
- * failed run a record, and kinds get promoted out of it as production shows what occurs.
+ * <p>Actions are declared here but run elsewhere: a server action in a {@link FailureAction} bean
+ * resolved by id, a client action in the browser that holds the document. Either way a new kind
+ * ships as a registry entry plus copy. Two members today: {@link #UNKNOWN} gives every failed run a
+ * record, and kinds get promoted out of it as production shows what occurs.
  *
- * <p>A kind offers an acknowledgement only where there is something to acknowledge <em>doing</em>.
- * With nothing to fix, "seen it" and "clear it" are the same decision, so the row offers only the
- * one that clears it.
+ * <p>Each offer also says who it is for and where the kind wants it, because the same incident is
+ * read by the person who hit it and by whoever reviews after them: only the owner can supply a
+ * password, only a reviewer wants the run.
  */
 @Getter
 public enum FailureKind {
@@ -37,8 +46,13 @@ public enum FailureKind {
             FailureScope.FILE,
             errorCodes("E004"),
             fallback("This document is password-protected, so the pipeline could not read it."),
-            offer(ACKNOWLEDGE),
-            offer(DISMISS, "dismissSkipFile")),
+            // The password is the fix and only the owner has it, so everyone else is
+            // offered the run and a way to close the row.
+            resolution(DECRYPT_AND_RETRY, OWNER),
+            global(RETRY, OWNER, OVERFLOW),
+            global(VIEW_FILE, OWNER, OVERFLOW),
+            global(VIEW_IN_PROCESSOR, TEAM_REVIEWER, SECONDARY),
+            global(DISMISS, ANYONE_WHO_SEES, OVERFLOW)),
 
     UNKNOWN(
             FailureStage.INTERNAL,
@@ -47,7 +61,12 @@ public enum FailureKind {
             FailureScope.RUN,
             noErrorCodes(),
             fallback("This run failed for a reason Stirling does not yet recognise."),
-            offer(DISMISS));
+            // Nothing here is known to be fixable, so there is no resolution to declare. A plain
+            // retry is still worth offering: an unrecognised failure is often a one-off.
+            global(RETRY, OWNER, SECONDARY),
+            global(VIEW_IN_PROCESSOR, TEAM_REVIEWER, SECONDARY),
+            global(VIEW_FILE, OWNER, OVERFLOW),
+            global(DISMISS, ANYONE_WHO_SEES, OVERFLOW));
 
     private static final String KEY_PREFIX = "portal.failures.kind.";
     private static final String ACTION_KEY_PREFIX = "portal.failures.action.";
@@ -95,22 +114,52 @@ public enum FailureKind {
     }
 
     /**
-     * One action this kind offers, with the key to label it by. One ordered list rather than ids
-     * plus a parallel map of overrides, which could disagree with each other.
+     * One action this kind offers: who it is for, where it wants to sit, and the key to label it
+     * by. One ordered list rather than ids plus parallel maps of audiences, slots and label
+     * overrides, which could disagree with each other.
      *
      * @param labelKeySuffix key under {@code portal.failures.action.}, or null for the generic
      *     label
      */
-    private record Offer(FailureActionId id, String labelKeySuffix) {}
+    private record Offer(
+            FailureActionId id,
+            FailureAudience audience,
+            FailureActionSlot slot,
+            String labelKeySuffix) {}
 
-    /** An action labelled by this kind's own wording, where the generic label reads badly. */
-    private static Offer offer(FailureActionId id, String labelKeySuffix) {
-        return new Offer(id, labelKeySuffix);
+    /**
+     * The action that fixes this kind, for whoever can actually apply it. In the resolution slot by
+     * definition: a kind needing two of these would be two kinds.
+     */
+    private static Offer resolution(FailureActionId id, FailureAudience audience) {
+        return new Offer(id, audience, FailureActionSlot.RESOLUTION, null);
+    }
+
+    /** As {@link #resolution(FailureActionId, FailureAudience)}, with this kind's own wording. */
+    private static Offer resolution(
+            FailureActionId id, FailureAudience audience, String labelKeySuffix) {
+        return new Offer(id, audience, FailureActionSlot.RESOLUTION, labelKeySuffix);
+    }
+
+    /**
+     * An action that is not this kind's fix: the same offer any kind can make, placed where this
+     * kind wants it and labelled by the shared wording.
+     */
+    private static Offer global(
+            FailureActionId id, FailureAudience audience, FailureActionSlot slot) {
+        return new Offer(id, audience, slot, null);
     }
 
-    /** An action labelled by the shared wording for that action. */
-    private static Offer offer(FailureActionId id) {
-        return new Offer(id, null);
+    /**
+     * As {@link #global(FailureActionId, FailureAudience, FailureActionSlot)}, but labelled by this
+     * kind's own wording where the shared one reads badly.
+     */
+    private static Offer global(
+            FailureActionId id,
+            FailureAudience audience,
+            FailureActionSlot slot,
+            String labelKeySuffix) {
+        return new Offer(id, audience, slot, labelKeySuffix);
     }
 
     /**
@@ -149,6 +198,29 @@ public List<FailureActionId> getActions() {
         return offers.stream().map(Offer::id).toList();
     }
 
+    /**
+     * What this kind offers, in declaration order, each with its label and placement resolved. What
+     * a review surface reads, so it never has to ask three separate questions about one offer.
+     */
+    public List<OfferedAction> getOfferedActions() {
+        return offers.stream()
+                .map(
+                        offer ->
+                                new OfferedAction(
+                                        offer.id(),
+                                        labelKeyFor(offer.id()),
+                                        offer.audience(),
+                                        offer.slot()))
+                .toList();
+    }
+
+    /** One action as a kind declares it: what to call it, who it is for, where it wants to sit. */
+    public record OfferedAction(
+            FailureActionId id,
+            String labelKey,
+            FailureAudience audience,
+            FailureActionSlot slot) {}
+
     /** Whether this kind offers {@code action}. The dispatch guard: see {@code FailureActionId}. */
     public boolean declares(FailureActionId action) {
         return offers.stream().anyMatch(offer -> offer.id() == action);