Record policy-run failures as durable, actionable events (Review Flow PR 1) (#7269)

# Description of Changes

PR 1 of the failure-notification work: a durable, team-scoped record of
**why a policy run failed**, surfaced in the portal with the triage
actions each failure allows.

Today a failed policy run is not quite invisible, but it is unusable:
the ledger marks the file `ERROR`, and the audit aspect keeps the
exception message and status code. Nothing classifies either one,
nothing surfaces them, and neither offers a next step. If the file came
from a folder, bucket or webhook there is also no user watching, so
nobody learns it never made it through. This adds the record and the
read surface; the remediation that acts on documents comes later (see
below).

## What this does

**A failure kind registry as data.** `FailureKind` describes what can go
wrong: a stable wire id, i18n keys, an English fallback, and four facets
the review surface needs (`Stage`, `Severity`, `Remedy`, `Scope`). It is
shaped like the existing `ExceptionUtils.ErrorCode` and *links* to that
vocabulary rather than replacing it.

**Classification off structured codes, not message matching.** Policy
steps dispatch over loopback HTTP, so a tool's 4xx arrives as a
`RestClientResponseException` whose body is the Problem Details document
carrying `errorCode`. `FailureClassifier` reads that. Anything
unrecognised becomes `UNKNOWN`, which is the point: every failed run
gets an addressable record from day one, and which kinds to promote next
is answered by production frequency rather than guesswork.

**Actions declared by a kind, implemented as beans.** A kind lists the
`FailureActionId`s it offers; behaviour lives in `FailureAction` beans
resolved by id — the idiom this codebase already uses for `InputSource`,
`PolicyOutputSink` and `PolicyTrigger`. A kind cannot be sent an action
it never declared (400), so an incoherent pairing is unreachable rather
than merely unrendered. A new kind ships as a registry entry plus copy:
no new endpoint, no UI change.

**Repeat folding.** Recording folds a genuine repeat into the existing
incident instead of inserting again, keyed on `(team_id, dedup_key)`.
That matters for a snapshot-mode source that re-lists every file on each
sweep: the same broken file is one incident, not one per sweep. Distinct
files keep distinct rows. The unique constraint is enforced by the
database, and a writer that loses the insert race folds into the
winner's row.

One granularity caveat worth naming: nothing populates `file_id` in this
PR, so every row has it NULL. A FILE-scoped kind therefore dedups on
`policy + run` rather than `policy + file`. That still yields one row
per document for the sources shipped here, because the folder, S3 and
webhook sources each start one run per file; it stops holding as soon as
a single run carries several documents, which is why editor-origin
reporting (item 3 below) populates `file_id`.

**No document identity is stored.** No file name, no content. `fileId`
is an opaque reference only the owner's own client can resolve locally.
`detail` keeps the raw message (the only diagnostic an `UNKNOWN` failure
has) with anything path- or filename-shaped stripped on the way in,
capped at 2,000 characters. `PolicyExecutor`'s type-mismatch message now
reports the *extension* rather than the filename, since that message
becomes the stored `detail`.

**Access.** Reads and triage are leader-only, gated exactly the way
`PolicyController` gates policy editing, with the single-user carve-out
when login is disabled. Every read and write is scoped to the caller's
own team from the authenticated principal — there is no team parameter
on the API.

Self-hosted needs no migration: the table is created from the entity by
`ddl-auto=update`, as with every other table.

## What this does not do yet

- **Actions are incident dispositions, not document dispositions.**
Acknowledge and Dismiss change how a failure is displayed and touch
nothing else — not the document, not the processed-file ledger, not the
run, not any output destination. That is what makes them safe to offer
against `UNKNOWN`, and why there is no Approve/Release yet.
- **Two kinds only.** `INPUT_PASSWORD_PROTECTED` and `UNKNOWN`.
Everything else classifies as `UNKNOWN` and shows its raw message.
- **Editor-origin failures are not reported.** Every row is `PROCESSOR`.
`FailureOrigin.EDITOR` and `API` exist in the enum but nothing writes
them.
- **The list is dev-only for now.** The section renders behind
`import.meta.env.DEV`, so it ships in no production bundle. The
endpoints are live and gated.
- **No retention or per-team cap** on `file_run_events`. Tracked
separately.
- **No suspend-and-prompt.** `PolicyInputRequiredException` and the
engine's `suspend()` exist but nothing throws it, so a run cannot pause
to ask for a password today.
- **SaaS needs a migration** in `Stirling-PDF-SaaS` (`CREATE TABLE IF
NOT EXISTS stirling_pdf.file_run_events`), per the convention documented
at `app/saas/src/main/resources/application-saas.properties:21`.

## What follows in later PRs

1. **Map the remaining error codes to specific kinds** — corrupted file,
OCR unavailable, output destination unreachable, entitlement refusals,
and so on — each with its own copy and its own action set, replacing
today's `UNKNOWN` catch-all with a named notification in the review UI.
2. **Real remediation actions** attached to those kinds: fix (supply a
password and resume), skip (drop this file, continue the batch), and
decline (reject an incoming file outright), acting on the held document
rather than only on the incident row. This is where the
suspend-and-prompt path gets wired.
3. **Editor-origin reporting**, so a failure a user hits in the editor
lands in the same queue as one from a bucket.
4. **The user-facing review surface**: notifications with a sticky
review section, per-file badges, and an export gate, with the dev-only
list here replaced by the real thing.

## How to test

Needs a SaaS or proprietary build with login enabled, and an account
that leads a team.

1. Create a policy in the Processor with any step (Auto-redact is fine)
and a source you can drop files into.
2. Upload two files that will fail it: **a password-protected PDF**, and
**a corrupted PDF** (truncate a valid one, or rename a `.csv` to
`.pdf`).
3. Let the policy run and fail on both.
4. Go to the portal's **Documents** view and scroll to **Failures** (dev
builds only).

Expect two rows:

- **Password-protected document** — classified from `E004`, with the
kind's own labels **"I'll unlock this"** and **"Skip this file"** rather
than generic wording.
- **Unrecognised failure** — the corrupted file, classified `UNKNOWN`
(`E001` is not claimed by a kind yet), showing its raw message with
generic **Acknowledge** / **Dismiss**.

Neither row contains a file name anywhere, including in the raw message.
Press **Show raw JSON** to read exactly what the server returned. Acting
on a row transitions it and comes back with both buttons disabled and a
reason.

Re-running the same batch increments the occurrence count on the
existing rows rather than adding new ones; two *different*
password-protected files produce two separate rows.

---

## Checklist

### General

- [ ] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [ ] I have read the [Stirling-PDF Developer
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md)
(if applicable)
- [ ] I have read the [How to add new languages to
Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md)
(if applicable)
- [ ] I have performed a self-review of my own code
- [ ] My changes generate no new warnings

### Documentation

- [ ] I have updated relevant docs on [Stirling-PDF's doc
repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/)
(if functionality has heavily changed)
- [ ] I have read the section [Add New Translation
Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags)
(for new translation tags only)

### Translations (if applicable)

- [ ] I ran
[`scripts/counter_translation.py`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docs/counter_translation.md)

### UI Changes (if applicable)

- [ ] Screenshots or videos demonstrating the UI changes are attached
(e.g., as comments or direct attachments in the PR)

### Testing (if applicable)

- [ ] I have run `task check` to verify linters, typechecks, and tests
pass

Author: EthanHealy01

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

@@ -0,0 +1,39 @@
+package stirling.software.proprietary.failure;
+
+import java.util.List;
+import java.util.Map;
+
+import org.springframework.stereotype.Component;
+
+import lombok.RequiredArgsConstructor;
+
+/**
+ * "Seen, and I own it." Moves {@code NEW} to {@code ACKNOWLEDGED} so the row stops counting as
+ * unread while staying in the open list. Touches only the status, not the document, ledger or run.
+ *
+ * <p>Re-acknowledging is a no-op that keeps the original actor and timestamp, so the first person
+ * to pick it up stays credited.
+ */
+@Component
+@RequiredArgsConstructor
+public class AcknowledgeAction implements FailureAction {
+
+    private final FileRunEventStore store;
+
+    @Override
+    public FailureActionId id() {
+        return FailureActionId.ACKNOWLEDGE;
+    }
+
+    @Override
+    public FileRunEvent execute(FileRunEvent event, Map<String, String> inputs, String actor) {
+        // Guarded on NEW so a racing acknowledger cannot re-stamp the row, and so re-acknowledging
+        // returns the first actor's row rather than taking their credit.
+        return store.applyStatusOnce(
+                event.id(),
+                event.teamId(),
+                FileRunEventStatus.ACKNOWLEDGED,
+                actor,
+                List.of(FileRunEventStatus.NEW));
+    }
+}

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

@@ -0,0 +1,32 @@
+package stirling.software.proprietary.failure;
+
+import java.util.Map;
+
+import org.springframework.stereotype.Component;
+
+import lombok.RequiredArgsConstructor;
+
+/**
+ * "No remediation will happen; close it." Terminal. Named Dismiss rather than Reject because it
+ * closes the incident, not the document: nothing is deleted or delivered, the ledger row is left
+ * alone, and a different file failing the same way still opens its own incident.
+ *
+ * <p>Recurrences of this exact failure fold onto the dismissed row, which is what makes "stop
+ * showing me this" hold for a source that re-lists the same failing file each sweep.
+ */
+@Component
+@RequiredArgsConstructor
+public class DismissAction implements FailureAction {
+
+    private final FileRunEventStore store;
+
+    @Override
+    public FailureActionId id() {
+        return FailureActionId.DISMISS;
+    }
+
+    @Override
+    public FileRunEvent execute(FileRunEvent event, Map<String, String> inputs, String actor) {
+        return store.applyStatus(event.id(), event.teamId(), FileRunEventStatus.DISMISSED, actor);
+    }
+}

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

@@ -0,0 +1,23 @@
+package stirling.software.proprietary.failure;
+
+import java.util.Map;
+
+/**
+ * The behaviour behind one {@link FailureActionId}. Implementations are Spring beans injected as a
+ * {@code List} and resolved by id, the pattern already used for {@code InputSource}, {@code
+ * PolicyOutputSink} and {@code PolicyTrigger}.
+ *
+ * <p>Keeping behaviour out of the registry keeps that pure data, so a new kind ships by declaring
+ * an action id that already has a handler.
+ */
+public interface FailureAction {
+
+    FailureActionId id();
+
+    /**
+     * Apply the action and return the updated event. {@code inputs} carries whatever the action
+     * declared it needs, which is nothing for the two that exist today. Implementations leave the
+     * document, ledger, run and output destinations alone unless that is the action's purpose.
+     */
+    FileRunEvent execute(FileRunEvent event, Map<String, String> inputs, String actor);
+}

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

@@ -0,0 +1,49 @@
+package stirling.software.proprietary.failure;
+
+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.
+ */
+@Getter
+public class FailureActionException extends RuntimeException {
+
+    public enum Reason {
+        /**
+         * No such event, it belongs to another team, or the caller's team did not resolve. One
+         * reason for all three, so the response does not vary with which it was. Unrelated to
+         * {@link FailureKind#UNKNOWN}, which is an unclassified failure rather than a refused
+         * action.
+         */
+        EVENT_NOT_FOUND,
+
+        /** The action id is not in the vocabulary at all, or has no registered handler. */
+        ACTION_NOT_RECOGNISED,
+
+        /**
+         * 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.
+         */
+        ACTION_NOT_DECLARED,
+
+        /** The event is already closed, so no further transition is possible. */
+        ALREADY_CLOSED
+    }
+
+    private final Reason reason;
+
+    public FailureActionException(Reason reason, String message) {
+        this(reason, message, null);
+    }
+
+    /** For a refusal that follows from a lower-level failure, so its stack is not dropped. */
+    public FailureActionException(Reason reason, String message, Throwable cause) {
+        super(message, cause);
+        this.reason = reason;
+    }
+}

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

@@ -0,0 +1,11 @@
+package stirling.software.proprietary.failure;
+
+/**
+ * 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.
+ */
+public enum FailureActionId {
+    ACKNOWLEDGE,
+    DISMISS
+}

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

@@ -0,0 +1,68 @@
+package stirling.software.proprietary.failure;
+
+import java.util.Arrays;
+import java.util.EnumMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+import org.springframework.stereotype.Service;
+
+import jakarta.annotation.PostConstruct;
+
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * 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.
+ */
+@Slf4j
+@Service
+public class FailureActionRegistry {
+
+    private final Map<FailureActionId, FailureAction> byId = new EnumMap<>(FailureActionId.class);
+
+    public FailureActionRegistry(List<FailureAction> actions) {
+        for (FailureAction action : actions) {
+            FailureAction clash = byId.put(action.id(), action);
+            if (clash != null) {
+                throw new IllegalStateException(
+                        "Two handlers registered for action "
+                                + action.id()
+                                + ": "
+                                + clash.getClass().getName()
+                                + " and "
+                                + action.getClass().getName());
+            }
+        }
+    }
+
+    /**
+     * 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.
+     */
+    @PostConstruct
+    void verifyEveryDeclaredActionHasAHandler() {
+        List<String> gaps =
+                Arrays.stream(FailureKind.values())
+                        .flatMap(
+                                kind ->
+                                        kind.getActions().stream()
+                                                .filter(action -> !byId.containsKey(action))
+                                                .map(action -> kind.getId() + " -> " + action))
+                        .toList();
+        if (!gaps.isEmpty()) {
+            throw new IllegalStateException(
+                    "Failure kinds declare actions with no registered handler: " + gaps);
+        }
+        log.debug(
+                "Failure action registry initialised with {} handler(s) for {} kind(s)",
+                byId.size(),
+                FailureKind.values().length);
+    }
+
+    public Optional<FailureAction> find(FailureActionId id) {
+        return Optional.ofNullable(byId.get(id));
+    }
+}

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

@@ -0,0 +1,109 @@
+package stirling.software.proprietary.failure;
+
+import java.util.List;
+
+import org.springframework.stereotype.Service;
+import org.springframework.web.client.RestClientResponseException;
+
+import jakarta.annotation.PostConstruct;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.util.ExceptionUtils;
+
+import tools.jackson.core.JacksonException;
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
+
+/**
+ * Maps a thrown failure onto a {@link FailureKind}. A tool's 4xx arrives as a {@link
+ * RestClientResponseException} whose body is the Problem Details document carrying {@code
+ * errorCode}, so this matches on codes rather than exception messages.
+ *
+ * <p>Anything unrecognised becomes {@link FailureKind#UNKNOWN}, so every failed run still gets a
+ * record.
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class FailureClassifier {
+
+    /** Set by {@code GlobalExceptionHandler#createProblemDetailResponse}. */
+    private static final String ERROR_CODE_PROPERTY = "errorCode";
+
+    /**
+     * Depth bound on the cause chain. The JDK forbids self-causation but not a longer cycle (A
+     * caused by B caused by A), which an unbounded walk would spin on. Real chains are a handful
+     * deep.
+     */
+    private static final int MAX_CAUSE_DEPTH = 16;
+
+    private final ObjectMapper objectMapper;
+
+    /**
+     * Refuse to start on an ambiguous registry: two kinds claiming one code would make {@link
+     * #classify} depend on declaration order. Checked here because this is what resolves codes to
+     * kinds, and at boot so the message names the codes rather than arriving as a class-init error.
+     */
+    @PostConstruct
+    void verifyNoErrorCodeIsClaimedTwice() {
+        List<String> duplicates = FailureKind.duplicateErrorCodes();
+        if (!duplicates.isEmpty()) {
+            throw new IllegalStateException(
+                    "Error codes claimed by more than one failure kind: " + duplicates);
+        }
+    }
+
+    /** Never null, never throws. A classifier that can fail would lose the failure it describes. */
+    public FailureKind classify(Throwable throwable) {
+        Throwable current = throwable;
+        for (int depth = 0; current != null && depth < MAX_CAUSE_DEPTH; depth++) {
+            FailureKind resolved = classifyOne(current);
+            if (resolved != FailureKind.UNKNOWN) {
+                return resolved;
+            }
+            Throwable cause = current.getCause();
+            current = cause == current ? null : cause;
+        }
+        return FailureKind.UNKNOWN;
+    }
+
+    private FailureKind classifyOne(Throwable throwable) {
+        // A tool step's 4xx/5xx: the Problem Details body names the error code.
+        if (throwable instanceof RestClientResponseException responseException) {
+            String code = errorCodeFromBody(responseException);
+            if (code != null) {
+                return FailureKind.byErrorCode(code).orElse(FailureKind.UNKNOWN);
+            }
+        }
+        // Thrown in-process (not over loopback): the exception carries its own code.
+        if (throwable instanceof ExceptionUtils.ErrorCodeProvider provider) {
+            return FailureKind.byErrorCode(provider.getErrorCode()).orElse(FailureKind.UNKNOWN);
+        }
+        return FailureKind.UNKNOWN;
+    }
+
+    /**
+     * Pull {@code errorCode} from a Problem Details body, or null when the body is absent, not
+     * JSON, or has no such property (an entitlement sentinel has {@code error} instead).
+     */
+    private String errorCodeFromBody(RestClientResponseException exception) {
+        String body = exception.getResponseBodyAsString();
+        if (body == null || body.isBlank()) {
+            return null;
+        }
+        try {
+            JsonNode root = objectMapper.readTree(body);
+            JsonNode code = root.get(ERROR_CODE_PROPERTY);
+            if (code == null || !code.isTextual()) {
+                return null;
+            }
+            String text = code.asString();
+            return text.isBlank() ? null : text;
+        } catch (JacksonException e) {
+            log.debug("Downstream error body was not JSON; classifying as UNKNOWN");
+            return null;
+        }
+    }
+}