Merge branch 'main' into feature/policiesVisualiserComponent

Redesign policies to use typed mappings properly (#7017 )
# Description of Changes The Policies page and all the frontend logic for running Policies is not making use of the bidirectional type mappings that we now have to safely convert from frontend to backend param models and vice versa. This changes the way we track the types throughout so we use the mappings properly. Because of this, the Add Watermark settings in Policies now actually pre-populate with the defaults instead of with nothing like they previously did. <img width="791" height="725" alt="image" src="https://github.com/user-attachments/assets/cbdf4ae0-35af-4792-bf64-89216e48d304" />
2026-07-14 12:18:15 +01:00 · 2026-07-14 09:58:04 +00:00 · 2026-07-14 09:43:07 +00:00 · 2026-07-14 09:09:23 +00:00 · 2026-07-13 23:45:19 +01:00 · 2026-07-13 20:23:14 +01:00
904 changed files with 129228 additions and 18273 deletions
@@ -1,6 +1,6 @@
 # Maintainer: Stirling PDF Inc <contact@stirlingpdf.com>
 pkgname=stirling-pdf-desktop
-pkgver=2.14.1
+pkgver=2.14.2
 pkgrel=1
 pkgdesc="Locally hosted, web-based PDF manipulation tool (Tauri desktop app, official Stirling PDF Inc build)"
 arch=('x86_64')
@@ -1,6 +1,6 @@
 # Maintainer: Stirling PDF Inc <contact@stirlingpdf.com>
 pkgname=stirling-pdf-server-bin
-pkgver=2.14.1
+pkgver=2.14.2
 pkgrel=1
 pkgdesc="Locally hosted, web-based PDF manipulation tool (server JAR, prebuilt)"
 arch=('any')
@@ -1,12 +1,12 @@
 build: &build
  - build.gradle
-  - app/(common|core|proprietary)/build.gradle
+  - app/(common|core|proprietary|saas)/build.gradle
  - Taskfile.yml
  - .taskfiles/backend.yml

 openapi: &openapi
  - *build
-  - app/(common|core|proprietary)/src/main/java/**
+  - app/(common|core|proprietary|saas)/src/main/java/**

 docker-base: &docker-base
  - docker/base/Dockerfile
@@ -23,9 +23,9 @@ docker: &docker
  - *docker-base

 project: &project
-  - app/(common|core|proprietary)/src/(main|test)/java/**
+  - app/(common|core|proprietary|saas)/src/(main|test)/java/**
  - *build
-  - "app/(common|core|proprietary)/src/(main|test)/resources/**/!(messages_*.properties|*.md)*"
+  - "app/(common|core|proprietary|saas)/src/(main|test)/resources/**/!(messages_*.properties|*.md)*"
  - exampleYmlFiles/**
  - gradle/**
  - libs/**
@@ -82,7 +82,7 @@ tauri: &tauri
 # tool surfaces it generates models from.
 engine: &engine
  - engine/**
-  - app/(common|core|proprietary)/src/main/java/**
+  - app/(common|core|proprietary|saas)/src/main/java/**
  - .github/workflows/ai-engine.yml
  - Taskfile.yml
  - .taskfiles/engine.yml
@@ -63,6 +63,7 @@ labels:
    files:
      - 'app/core/src/main/resources/static/.*'
      - 'app/proprietary/src/main/resources/static/.*'
+      - 'app/saas/src/main/resources/static/.*'
      - 'frontend/**'
      - 'frontend/.*'
      - 'frontend/**/.*'
@@ -83,6 +84,7 @@ labels:
      - 'app/common/src/main/java/.*.java'
      - 'app/proprietary/src/main/java/.*.java'
      - 'app/core/src/main/java/.*.java'
+      - 'app/saas/src/main/java/.*.java'

  - label: 'Back End'
    files:
@@ -90,6 +92,9 @@ labels:
      - 'app/core/src/main/java/stirling/software/SPDF/controller/.*'
      - 'app/core/src/main/resources/settings.yml.template'
      - 'app/core/src/main/resources/application.properties'
+      - 'app/proprietary/src/main/resources/application-proprietary.properties'
+      - 'app/saas/src/main/resources/application-dev.properties'
+      - 'app/saas/src/main/resources/application-saas.properties'
      - 'app/core/src/main/resources/banner.txt'
      - 'app/core/src/main/resources/static/python/png_to_webp.py'
      - 'app/core/src/main/resources/static/python/split_photos.py'
@@ -153,6 +158,7 @@ labels:
      - 'app/common/src/test/.*'
      - 'app/proprietary/src/test/.*'
      - 'app/core/src/test/.*'
+      - 'app/saas/src/test/.*'
      - 'testing/.*'
      - '.github/workflows/scorecards.yml'
      - 'exampleYmlFiles/test_cicd.yml'
@@ -171,3 +177,4 @@ labels:
      - 'app/common/build.gradle'
      - 'app/proprietary/build.gradle'
      - 'app/core/build.gradle'
+      - 'app/saas/build.gradle'
@@ -256,7 +256,7 @@ jobs:

      - name: Build and push V2 image (Docker fork fallback)
        if: env.USE_DEPOT != 'true' && steps.check-image.outputs.exists == 'false'
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          context: .
          file: ./docker/embedded/Dockerfile
@@ -342,9 +342,70 @@ jobs:
          # Set port for output
          echo "v2_port=${V2_PORT}" >> $GITHUB_OUTPUT

+      # ---- Storybook preview (only when this PR touches stories/.storybook) ----
+      # Runs inside the same approved-contributor-gated deploy job, so it deploys
+      # under the exact same access rules as the app preview.
+      - name: Detect Storybook changes
+        id: sb-changes
+        uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        with:
+          list-files: json
+          filters: |
+            storybook:
+              - 'frontend/**/*.stories.@(ts|tsx|mdx)'
+              - 'frontend/**/*.mdx'
+              - 'frontend/.storybook/**'
+
+      - name: Set up Node.js for Storybook
+        if: steps.sb-changes.outputs.storybook == 'true'
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install Task for Storybook
+        if: steps.sb-changes.outputs.storybook == 'true'
+        uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
+
+      - name: Build and deploy Storybook
+        id: storybook
+        if: steps.sb-changes.outputs.storybook == 'true'
+        env:
+          VPS_HOST: ${{ secrets.NEW_VPS_HOST }}
+          VPS_USER: ${{ secrets.NEW_VPS_USERNAME }}
+        run: |
+          set -euo pipefail
+          # `prepare` generates the icon set stories import (not committed).
+          task frontend:prepare
+          task frontend:storybook:build
+          PR=${{ needs.check-pr.outputs.pr_number }}
+          # Served at the ROOT of its own port so Storybook's global MSW worker
+          # (/mockServiceWorker.js) resolves. Port = PR + 20000 (bijective, offset
+          # from the app preview's bare-PR-number port).
+          SB_PORT=$((PR + 20000))
+          DIR=/stirling/SB-PR-$PR
+          tar czf storybook.tgz -C frontend/storybook-static .
+          scp -i ../private.key -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+            storybook.tgz "$VPS_USER@$VPS_HOST:/tmp/storybook-$PR.tgz"
+          ssh -i ../private.key -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -T \
+            "$VPS_USER@$VPS_HOST" << ENDSSH
+            set -e
+            rm -rf "$DIR" && mkdir -p "$DIR"
+            tar xzf /tmp/storybook-$PR.tgz -C "$DIR"
+            rm -f /tmp/storybook-$PR.tgz
+            docker rm -f storybook-pr-$PR 2>/dev/null || true
+            docker run -d --name storybook-pr-$PR --restart unless-stopped \
+              -p $SB_PORT:80 -v "$DIR":/usr/share/nginx/html:ro nginx:alpine
+          ENDSSH
+          echo "url=http://$VPS_HOST:$SB_PORT/" >> "$GITHUB_OUTPUT"
+
      - name: Post V2 deployment URL to PR
        if: success()
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          SB_URL: ${{ steps.storybook.outputs.url }}
+          SB_FILES: ${{ steps.sb-changes.outputs.storybook_files }}
        with:
          github-token: ${{ steps.setup-bot.outputs.token }}
          script: |
@@ -376,11 +437,32 @@ jobs:
              ? `🧩 **Admin portal** included - try it at [${deploymentUrl}/portal](${deploymentUrl}/portal).\n\n`
              : ``;

+            // Storybook preview: only present when this PR changed stories/config.
+            const sbUrl = process.env.SB_URL;
+            let storybookNote = "";
+            if (sbUrl) {
+              const files = JSON.parse(process.env.SB_FILES || "[]");
+              const stories = files.filter((f) => /\.stories\.(ts|tsx|mdx)$/.test(f));
+              const config = files.filter((f) => f.startsWith("frontend/.storybook/"));
+              const shorten = (f) =>
+                f.replace(/^frontend\/editor\/src\//, "").replace(/^frontend\//, "");
+              const storyList = stories.map((f) => `- \`${shorten(f)}\``).join("\n");
+              const configList = config.map((f) => `- \`${shorten(f)}\``).join("\n");
+              const summary =
+                `${stories.length} stor${stories.length === 1 ? "y" : "ies"} changed` +
+                (config.length ? ` (+${config.length} config file${config.length === 1 ? "" : "s"})` : "");
+              storybookNote =
+                `📚 **Storybook:** [${sbUrl}](${sbUrl})\n\n` +
+                `<details>\n<summary>${summary}</summary>\n\n` +
+                (storyList ? `**Stories**\n${storyList}\n\n` : "") +
+                (configList ? `**Config**\n${configList}\n` : "") +
+                `</details>\n\n`;
+            }
+
            const commentBody = `## 🚀 V2 Auto-Deployment Complete!\n\n` +
-                              `Your V2 PR with embedded architecture has been deployed!\n\n` +
                              `🔗 **Direct Test URL (non-SSL)** [${deploymentUrl}](${deploymentUrl})\n\n` +
-                              `🔐 **Secure HTTPS URL**: unsupported currently\n\n` +
                              portalNote +
+                              storybookNote +
                              `_This deployment will be automatically cleaned up when the PR is closed._\n\n` +
                              `🔄 **Auto-deployed** for approved V2 contributors.`;

@@ -476,7 +558,11 @@ jobs:
            else
              echo "V2 PR directory not found, nothing to clean up"
            fi
-            
+
+            # Remove this PR's Storybook preview (container + files), if any.
+            docker rm -f storybook-pr-${{ github.event.pull_request.number }} 2>/dev/null || true
+            rm -rf /stirling/SB-PR-${{ github.event.pull_request.number }}
+
            # Clean up old unused images (older than 2 weeks) but keep recent ones for reuse
            docker image prune -af --filter "until=336h" --filter "label!=keep=true" || true

@@ -270,7 +270,7 @@ jobs:

      - name: Build and push PR-specific image (Docker fork fallback)
        if: env.USE_DEPOT != 'true'
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          context: .
          file: ./docker/embedded/Dockerfile
@@ -296,7 +296,7 @@ jobs:

      - name: Build and push engine image (Docker fork fallback)
        if: env.USE_DEPOT != 'true' && needs.check-comment.outputs.enable_prototypes == 'true'
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          context: ./engine
          file: ./engine/Dockerfile
@@ -47,7 +47,7 @@ jobs:
          distribution: "temurin"

      - name: Cache Gradle dependency artifacts
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.gradle/wrapper
@@ -29,7 +29,7 @@ jobs:
          distribution: "temurin"

      - name: Cache Gradle dependency artifacts
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.gradle/wrapper
@@ -34,7 +34,7 @@ jobs:
          distribution: "temurin"

      - name: Cache Gradle dependency artifacts
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.gradle/wrapper
@@ -51,7 +51,7 @@ jobs:
          distribution: "temurin"

      - name: Cache Gradle dependency artifacts
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.gradle/wrapper
@@ -37,7 +37,7 @@ jobs:
          distribution: temurin

      - name: Cache Gradle dependency artifacts
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.gradle/wrapper
@@ -121,7 +121,7 @@ jobs:

      - name: Build and push frontend image (Docker fork fallback)
        if: env.USE_DEPOT != 'true' && steps.check-frontend.outputs.exists == 'false'
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          context: .
          file: ./docker/frontend/Dockerfile
@@ -150,7 +150,7 @@ jobs:

      - name: Build and push backend image (Docker fork fallback)
        if: env.USE_DEPOT != 'true' && steps.check-backend.outputs.exists == 'false'
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          context: .
          file: ./docker/backend/Dockerfile
@@ -50,7 +50,7 @@ jobs:
          distribution: "temurin"

      - name: Cache Gradle dependency artifacts
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.gradle/wrapper
@@ -61,7 +61,7 @@ jobs:
          distribution: "temurin"

      - name: Cache Gradle dependencies
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.gradle/caches
@@ -510,6 +510,7 @@ jobs:
      # cargo output unsigned, so checking it produces false negatives.
      - name: Verify Windows Code Signature
        if: ${{ matrix.platform == 'windows-latest' && env.SM_API_KEY != '' && (github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.sign != 'false') || github.ref == 'refs/heads/V2-master') }}
+        timeout-minutes: 15
        shell: pwsh
        run: |
          $allSigned = $true
@@ -531,11 +532,26 @@ jobs:

          # Extract MSI and verify the inner exe (the file that actually gets installed).
          # This is the critical check - AV flags the installed exe at runtime.
+          # Use lessmsi, not `msiexec /a`: msiexec serializes on the global
+          # _MSIExecute mutex and hangs forever on hosted runners when another
+          # installer is busy. lessmsi reads MSI tables directly - no mutex, no service.
          $msi = $msiFiles[0].FullName
          $extractDir = Join-Path $env:RUNNER_TEMP "msi-verify"
          if (Test-Path $extractDir) { Remove-Item $extractDir -Recurse -Force }
-          $proc = Start-Process msiexec.exe -ArgumentList '/a', $msi, '/qn', "TARGETDIR=$extractDir" -Wait -PassThru -NoNewWindow
-          if ($proc.ExitCode -eq 0) {
+          New-Item -ItemType Directory -Force -Path $extractDir | Out-Null
+
+          choco install lessmsi -y --no-progress --limit-output | Out-Null
+
+          # Bound the extraction and kill on hang (defence in depth over timeout-minutes).
+          $proc = Start-Process lessmsi -ArgumentList 'x', "`"$msi`"", "`"$extractDir\`"" -PassThru -NoNewWindow
+          if (-not $proc.WaitForExit(120000)) {
+            try { $proc.Kill() } catch {}
+            Write-Host "[ERROR] MSI extraction timed out after 120s"
+            $allSigned = $false
+          } elseif ($proc.ExitCode -ne 0) {
+            Write-Host "[ERROR] Failed to extract MSI for verification (exit code: $($proc.ExitCode))"
+            $allSigned = $false
+          } else {
            $innerExe = Get-ChildItem -Path $extractDir -Filter "stirling-pdf.exe" -Recurse -File | Select-Object -First 1
            if ($innerExe) {
              $sig = Get-AuthenticodeSignature -FilePath $innerExe.FullName
@@ -548,9 +564,6 @@ jobs:
              Write-Host "[ERROR] Could not find stirling-pdf.exe inside MSI"
              $allSigned = $false
            }
-          } else {
-            Write-Host "[ERROR] Failed to extract MSI for verification (exit code: $($proc.ExitCode))"
-            $allSigned = $false
          }

          if (-not $allSigned) {
@@ -800,7 +813,11 @@ jobs:
        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0
        with:
          tag_name: v${{ needs.determine-matrix.outputs.version }}
-          generate_release_notes: true
+          # Don't regenerate/append notes on re-runs, and don't force this into the
+          # "Latest" slot - leave the release body and latest marker as they are.
+          generate_release_notes: false
+          append_body: false
+          make_latest: false
          fail_on_unmatched_files: true
          # Installers + updater payloads + manifest. .sig contents are embedded
          # in latest.json so the .sig files themselves are not uploaded.
@@ -85,7 +85,7 @@ jobs:

      - name: Build and push base image
        id: build-push-base
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          builder: ${{ steps.buildx.outputs.name }}
          context: docker/base
@@ -66,7 +66,7 @@ jobs:
          distribution: "temurin"

      - name: Cache Gradle dependencies
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.gradle/caches
@@ -145,7 +145,7 @@ jobs:
        id: build-push-latest
        # Empty-tag guard: build-push-action errors when asked to push with no tags.
        if: env.RUN_MAIN_APP == 'true' && steps.meta.outputs.tags != ''
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          builder: ${{ steps.buildx.outputs.name }}
          context: .
@@ -192,7 +192,7 @@ jobs:

      - name: Build and push Unified Dockerfile (fat variant)
        id: build-push-fat
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        if: env.RUN_MAIN_APP == 'true' && github.ref != 'refs/heads/main' && github.ref != 'refs/heads/testMain' && steps.meta-fat.outputs.tags != ''
        with:
          builder: ${{ steps.buildx.outputs.name }}
@@ -236,7 +236,7 @@ jobs:

      - name: Build and push Unified Dockerfile (ultra-lite variant)
        id: build-push-lite
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        if: env.RUN_MAIN_APP == 'true' && github.ref != 'refs/heads/main' && github.ref != 'refs/heads/testMain' && steps.meta-lite.outputs.tags != ''
        with:
          builder: ${{ steps.buildx.outputs.name }}
@@ -365,7 +365,7 @@ jobs:
      - name: Build and push unoserver image
        id: build-push-unoserver
        if: env.RUN_UNOSERVER == 'true' && steps.unoserverDecision.outputs.mode != 'skip'
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          builder: ${{ steps.buildx.outputs.name }}
          context: .
@@ -95,7 +95,7 @@ jobs:
          distribution: "temurin"

      - name: Cache Gradle dependency artifacts
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.gradle/wrapper
@@ -186,7 +186,7 @@ jobs:
      # (multi-platform + gha cache) against the published base image.
      - name: Build ${{ matrix.docker-rev }} (Docker fork fallback)
        if: env.USE_DEPOT != 'true' && inputs.docker-base-changed != 'true'
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          builder: ${{ steps.buildx.outputs.name }}
          context: .
@@ -259,7 +259,7 @@ jobs:

      - name: Build docker/unoserver/Dockerfile (Docker fork fallback)
        if: env.USE_DEPOT != 'true'
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          builder: ${{ steps.buildx.outputs.name }}
          context: .
@@ -95,7 +95,7 @@ jobs:

      - name: Build and push test image (Docker fork fallback)
        if: env.USE_DEPOT != 'true'
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          context: .
          file: ./docker/embedded/Dockerfile
@@ -0,0 +1,5 @@
+{
+  "ignoredFiles": [
+    "frontend/editor/src-tauri/icons/icon.png"
+  ]
+}
@@ -80,6 +80,12 @@ tasks:
      OPEN: '{{.OPEN | default ""}}'
    env:
      BACKEND_URL: '{{.BACKEND_URL}}'
+      # Dev-only browser-tab label so concurrent worktrees are distinguishable.
+      # Only the worktree folder basename (e.g. "wt1") is exposed — never the
+      # full path, hostname, or user. Consumed at dev-serve time by vite.config
+      # and dropped from production builds.
+      STIRLING_DEV_LABEL:
+        sh: basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
    cmds:
      - npx vite editor --mode {{.MODE}} --port {{.PORT}}{{if .OPEN}} --open{{end}}

@@ -453,6 +453,7 @@ The frontend is organized with a clear separation of concerns:

 - **CRITICAL**: Always update translations in `en-US` only - all other languages (including `en-GB`) are handled separately
 - Translation files are located in `frontend/editor/public/locales/`
+- After changing any translation file, run `task pre-commit:fix`

 ## Important Notes

@@ -246,6 +246,14 @@ public class ApplicationProperties {
         * and paused runs are kept regardless of age.
         */
        private int runExpiryMinutes = 30;
+
+        /**
+         * Whether a policy S3 source's custom endpoint may resolve to a loopback, link-local, or
+         * private address. Off by default so a user-supplied endpoint cannot be pointed at internal
+         * services (e.g. the cloud metadata address); enable for a self-hosted MinIO or other
+         * in-network object store.
+         */
+        private boolean allowPrivateS3Endpoints = false;
    }

    @Data
@@ -0,0 +1,56 @@
+package stirling.software.common.service;
+
+/**
+ * Thread-scoped correlation id for one automation run — a single pipeline, policy, or AI-workflow
+ * execution over its input file(s).
+ *
+ * <p>Automations dispatch each tool step as a separate internal loopback POST via {@link
+ * InternalApiClient}. The orchestrator opens a run scope around its dispatch loop; {@code
+ * InternalApiClient} reads {@link #current()} and stamps it on every sub-step request as {@link
+ * #RUN_ID_HEADER}. The SaaS PAYG interceptor uses that header so all sub-steps of ONE run group
+ * into a single charge, while two <em>separate</em> runs that happen to touch identical bytes stay
+ * distinct charges (the old content+time-window grouping merged them).
+ *
+ * <p>Sub-steps dispatch synchronously on the orchestrator's own thread (loopback {@code
+ * RestTemplate}), so this ThreadLocal is visible to {@code InternalApiClient}. The id then crosses
+ * to the receiving request thread via the HTTP header — never via this ThreadLocal.
+ *
+ * <p>No-op when the id is absent (a standalone tool call): the interceptor treats a missing run id
+ * as "its own charge", which is exactly what a one-off call should be.
+ */
+public final class AutomationRunContext {
+
+    /** Header carrying the run id on internal sub-step dispatches. */
+    public static final String RUN_ID_HEADER = "X-Stirling-Run-Id";
+
+    private static final ThreadLocal<String> CURRENT = new ThreadLocal<>();
+
+    private AutomationRunContext() {}
+
+    /**
+     * Opens a run scope on the current thread. Returns an {@link AutoCloseable} that restores the
+     * previously-active id (nesting-safe) — use in try-with-resources around the dispatch loop.
+     */
+    public static Scope open(String runId) {
+        String previous = CURRENT.get();
+        CURRENT.set(runId);
+        return () -> {
+            if (previous == null) {
+                CURRENT.remove();
+            } else {
+                CURRENT.set(previous);
+            }
+        };
+    }
+
+    /** The run id active on this thread, or {@code null} when not inside a run scope. */
+    public static String current() {
+        return CURRENT.get();
+    }
+
+    /** AutoCloseable whose {@link #close()} declares no checked exception. */
+    public interface Scope extends AutoCloseable {
+        @Override
+        void close();
+    }
+}
@@ -8,6 +8,7 @@ import java.nio.file.Files;
 import java.time.Duration;
 import java.util.regex.Pattern;

+import org.slf4j.MDC;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.core.env.Environment;
 import org.springframework.core.io.FileSystemResource;
@@ -60,6 +61,17 @@ public class InternalApiClient {
     */
    public static final String AUTOMATION_HEADER = "X-Stirling-Automation";

+    /**
+     * Header carrying the parent policy's name onto each sub-step dispatch, read from MDC key
+     * {@link #POLICY_NAME_MDC_KEY} (set by the policy runner on the worker thread). Lets the audit
+     * layer attribute a tool step to the policy that ran it, instead of showing it as a bare direct
+     * call.
+     */
+    public static final String POLICY_NAME_HEADER = "X-Stirling-Policy-Name";
+
+    /** MDC key the policy runner stamps with the running policy's name; forwarded as a header. */
+    public static final String POLICY_NAME_MDC_KEY = "auditPolicyName";
+
    private final ServletContext servletContext;
    private final UserServiceInterface userService;
    private final TempFileManager tempFileManager;
@@ -111,6 +123,27 @@ public class InternalApiClient {
        // step inside a policy run must bill as AUTOMATION, not AI). Set unconditionally because
        // every caller of this dispatcher is an automation surface by design.
        headers.add(AUTOMATION_HEADER, "true");
+        // Propagate the current automation run id (set by the orchestrator around its dispatch
+        // loop) so the PAYG interceptor groups every sub-step of this one run into a single charge,
+        // and never merges two separate runs that happen to touch identical bytes. Absent → the
+        // receiving call is treated as standalone. See AutomationRunContext.
+        String runId = AutomationRunContext.current();
+        if (runId != null && !runId.isEmpty()) {
+            headers.add(AutomationRunContext.RUN_ID_HEADER, runId);
+        }
+
+        // Forward the parent policy name (set in MDC by the policy runner) so the audited sub-step
+        // ties back to its policy. Single-line, length-capped: it becomes an HTTP header value.
+        String policyName = MDC.get(POLICY_NAME_MDC_KEY);
+        if (policyName != null && !policyName.isBlank()) {
+            String safe = policyName.replaceAll("[\\r\\n]", " ").trim();
+            if (safe.length() > 200) {
+                safe = safe.substring(0, 200);
+            }
+            if (!safe.isEmpty()) {
+                headers.add(POLICY_NAME_HEADER, safe);
+            }
+        }

        // A no-file ai/tools call (e.g. create-pdf-from-html-agent) sends only string params, so
        // without this RestTemplate would use urlencoded instead of the multipart the controller
@@ -7,6 +7,7 @@ import java.time.format.DateTimeFormatter;
 import java.util.Calendar;

 import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDDocumentInformation;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.stereotype.Service;
@@ -17,6 +18,9 @@ import stirling.software.common.model.PdfMetadata;
@Service
 public class PdfMetadataService {

+    /** ({@code {labels}}). Written by the classify-and-label tool. */
+    public static final String CLASSIFICATION_KEY = "StirlingPDFClassification";
+
    private final ApplicationProperties applicationProperties;
    private final String stirlingPDFLabel;
    private final UserServiceInterface userService;
@@ -177,4 +181,14 @@ public class PdfMetadataService {
        }
        pdf.getDocumentInformation().setAuthor(author);
    }
+
+    /**
+     * Write the document classifier's JSON result into the custom Info-dictionary field {@link
+     * #CLASSIFICATION_KEY}, leaving all other metadata untouched.
+     */
+    public void setClassificationMetadata(PDDocument pdf, String classificationJson) {
+        PDDocumentInformation info = pdf.getDocumentInformation();
+        info.setCustomMetadataValue(CLASSIFICATION_KEY, classificationJson);
+        pdf.setDocumentInformation(info);
+    }
 }
@@ -144,8 +144,10 @@ public class TempFileCleanupService {
        int directoriesDeletedCount = 0;
        for (Path directory : registry.getTempDirectories()) {
            try {
-                if (Files.exists(directory)) {
+                if (Files.exists(directory)
+                        && shouldDeleteRegisteredDirectory(directory, maxAgeMillis)) {
                    GeneralUtils.deleteDirectory(directory);
+                    registry.unregisterDirectory(directory);
                    directoriesDeletedCount++;
                    log.debug("Cleaned up temporary directory: {}", directory);
                }
@@ -275,6 +277,21 @@ public class TempFileCleanupService {
        return totalDeletedCount.get();
    }

+    private boolean shouldDeleteRegisteredDirectory(Path directory, long maxAgeMillis) {
+        if (maxAgeMillis <= 0) {
+            return true;
+        }
+
+        try {
+            long currentTime = System.currentTimeMillis();
+            long lastModified = Files.getLastModifiedTime(directory).toMillis();
+            return (currentTime - lastModified) > maxAgeMillis;
+        } catch (IOException e) {
+            log.debug("Could not check directory age, skipping cleanup: {}", directory, e);
+            return false;
+        }
+    }
+
    /** Get the system temp directory path based on configuration or system property. */
    private Path getSystemTempPath() {
        String systemTempDir =
@@ -57,12 +57,13 @@ public class RequestUriUtils {
            return true;
        }

-        // Admin portal SPA shell. Served publicly like the editor root so a direct
-        // nav / refresh to /portal loads the app (the JWT lives in localStorage, not
-        // a cookie, so the server can't authenticate the navigation itself). The
+        // Admin portal SPA shell (mounted at /processor — must match the frontend
+        // PORTAL_BASENAME). Served publicly like the editor root so a direct nav /
+        // refresh to /processor loads the app (the JWT lives in localStorage, not a
+        // cookie, so the server can't authenticate the navigation itself). The
        // portal gates access via its own auth gate + RequirePortalAccess, and its
        // data APIs stay protected, so serving the shell pre-auth is safe.
-        if (normalizedUri.equals("/portal") || normalizedUri.startsWith("/portal/")) {
+        if (normalizedUri.equals("/processor") || normalizedUri.startsWith("/processor/")) {
            return true;
        }

@@ -155,6 +155,7 @@ public class TempFileManager {
        if (directory != null && Files.isDirectory(directory)) {
            try {
                GeneralUtils.deleteDirectory(directory);
+                registry.unregisterDirectory(directory);
                log.debug("Deleted temp directory: {}", directory.toString());
            } catch (IOException e) {
                log.warn("Failed to delete temp directory: {}", directory.toString(), e);
@@ -85,6 +85,18 @@ public class TempFileRegistry {
        return directory;
    }

+    /**
+     * Unregister a temporary directory from the registry.
+     *
+     * @param directory The directory to unregister
+     */
+    public void unregisterDirectory(Path directory) {
+        if (directory != null) {
+            tempDirectories.remove(directory);
+            log.debug("Unregistered temp directory: {}", directory.toString());
+        }
+    }
+
    /**
     * Register a third-party temporary file that requires special handling.
     *
@@ -176,11 +176,13 @@ class TempFileCleanupServiceMoreTest {
    class ScheduledCleanup {

        @Test
-        @DisplayName("deletes registered temp directories and reports counts")
+        @DisplayName("deletes stale registered temp directories and reports counts")
        void deletesRegisteredDirectories() throws IOException {
            when(tempFileManager.cleanupOldTempFiles(anyLong())).thenReturn(2);
            Path regDir = Files.createDirectories(tempDir.resolve("registeredDir"));
            Files.createFile(regDir.resolve("inside.txt"));
+            Files.setLastModifiedTime(
+                    regDir, FileTime.fromMillis(System.currentTimeMillis() - 2L * 60 * 60 * 1000));
            Set<Path> dirs = new HashSet<>();
            dirs.add(regDir);
            when(registry.getTempDirectories()).thenReturn(dirs);
@@ -193,6 +195,22 @@ class TempFileCleanupServiceMoreTest {
            verify(tempFileManager).cleanupOldTempFiles(anyLong());
        }

+        @Test
+        @DisplayName("keeps a fresh registered temp directory")
+        void keepsFreshRegisteredDirectory() throws IOException {
+            when(tempFileManager.cleanupOldTempFiles(anyLong())).thenReturn(0);
+            Path regDir = Files.createDirectories(tempDir.resolve("freshRegisteredDir"));
+            Files.createFile(regDir.resolve("inside.txt"));
+            Set<Path> dirs = new HashSet<>();
+            dirs.add(regDir);
+            when(registry.getTempDirectories()).thenReturn(dirs);
+            lenient().when(registry.contains(any(File.class))).thenReturn(false);
+
+            withIsolatedUserHome(cleanupService::scheduledCleanup);
+
+            assertThat(Files.exists(regDir)).isTrue();
+        }
+
        @Test
        @DisplayName("skips a registered directory that no longer exists")
        void skipsMissingRegisteredDirectory() {
@@ -75,10 +75,10 @@ class RequestUriUtilsTest {

    @Test
    void testIsStaticResource_portalShell() {
-        // The admin portal SPA shell is served pre-auth so it's directly navigable.
-        assertTrue(RequestUriUtils.isStaticResource("/portal"));
-        assertTrue(RequestUriUtils.isStaticResource("/portal/users"));
-        assertTrue(RequestUriUtils.isStaticResource("/app", "/app/portal"));
+        // The admin portal SPA shell (/processor) is served pre-auth so it's directly navigable.
+        assertTrue(RequestUriUtils.isStaticResource("/processor"));
+        assertTrue(RequestUriUtils.isStaticResource("/processor/users"));
+        assertTrue(RequestUriUtils.isStaticResource("/app", "/app/processor"));
    }

    // --- isFrontendRoute tests ---
@@ -10,6 +10,7 @@ import java.util.List;
 import java.util.Locale;
 import java.util.Map;
 import java.util.Map.Entry;
+import java.util.UUID;

 import org.springframework.core.io.FileSystemResource;
 import org.springframework.core.io.Resource;
@@ -27,6 +28,7 @@ import stirling.software.SPDF.model.PipelineConfig;
 import stirling.software.SPDF.model.PipelineOperation;
 import stirling.software.SPDF.model.PipelineResult;
 import stirling.software.SPDF.service.ApiDocService;
+import stirling.software.common.service.AutomationRunContext;
 import stirling.software.common.service.InternalApiClient;
 import stirling.software.common.util.TempFileManager;
 import stirling.software.common.util.ZipExtractionUtils;
@@ -71,6 +73,17 @@ public class PipelineProcessor {

    PipelineResult runPipelineAgainstFiles(List<Resource> outputFiles, PipelineConfig config)
            throws Exception {
+        // One pipeline execution = one automation run. Scope a run id so every tool sub-step
+        // dispatched via InternalApiClient groups into a single charge on the SaaS billing side
+        // (see AutomationRunContext); pipeline steps run synchronously on this thread.
+        try (AutomationRunContext.Scope ignored =
+                AutomationRunContext.open(UUID.randomUUID().toString())) {
+            return runPipelineAgainstFilesInternal(outputFiles, config);
+        }
+    }
+
+    private PipelineResult runPipelineAgainstFilesInternal(
+            List<Resource> outputFiles, PipelineConfig config) throws Exception {
        PipelineResult result = new PipelineResult();

        ByteArrayOutputStream logStream = new ByteArrayOutputStream();
@@ -305,6 +305,23 @@ public class GetInfoOnPDF {
        }
    }

+    /**
+     * Info-dictionary keys exposed above via typed getters; any other key in the dictionary is
+     * surfaced as custom metadata (e.g. the classification policy's StirlingPDFClassification
+     * entry).
+     */
+    private static final java.util.Set<String> STANDARD_INFO_KEYS =
+            java.util.Set.of(
+                    "Title",
+                    "Author",
+                    "Subject",
+                    "Keywords",
+                    "Producer",
+                    "Creator",
+                    "CreationDate",
+                    "ModDate",
+                    "Trapped");
+
    private static ObjectNode extractMetadata(PDDocument document) {
        ObjectNode metadata = objectMapper.createObjectNode();

@@ -335,6 +352,18 @@ public class GetInfoOnPDF {
                if (modificationDate != null) {
                    metadata.put("ModificationDate", modificationDate);
                }
+
+                // Surface custom Info-dictionary entries (anything beyond the
+                // standard fields above) — e.g. StirlingPDFClassification
+                for (String key : info.getMetadataKeys()) {
+                    if (STANDARD_INFO_KEYS.contains(key)) {
+                        continue;
+                    }
+                    String value = info.getCustomMetadataValue(key);
+                    if (value != null && !value.isBlank()) {
+                        metadata.put(key, value);
+                    }
+                }
            }
        } catch (Exception e) {
            log.error("Error extracting metadata: {}", e.getMessage());
@@ -136,11 +136,17 @@ public class RedactController {
                            + "Users can provide text patterns to redact, with options for regex and whole word matching. "
                            + "Input:PDF Output:PDF Type:SISO")
    public ResponseEntity<Resource> redactPdf(@ModelAttribute RedactPdfRequest request) {
-        String[] listOfText = request.getListOfText().split("\n");
+        String rawListOfText = request.getListOfText();
        boolean useRegex = Boolean.TRUE.equals(request.getUseRegex());
        boolean wholeWordSearchBool = Boolean.TRUE.equals(request.getWholeWordSearch());

-        if (listOfText.length == 0 || (listOfText.length == 1 && listOfText[0].trim().isEmpty())) {
+        if (rawListOfText == null || rawListOfText.trim().isEmpty()) {
+            throw ExceptionUtils.createIllegalArgumentException(
+                    "error.redaction.no.patterns", "No text patterns provided for redaction");
+        }
+
+        String[] listOfText = rawListOfText.split("\n");
+        if (listOfText.length == 1 && listOfText[0].trim().isEmpty()) {
            throw ExceptionUtils.createIllegalArgumentException(
                    "error.redaction.no.patterns", "No text patterns provided for redaction");
        }
@@ -1,18 +1 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<svg xmlns="http://www.w3.org/2000/svg" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 24 24">
-        <symbol id="icon-redact-auto" viewBox="0 0 24 24">  <g id="Layer_2" data-name="Layer 2">
-    <g id="Layer_1-2" data-name="Layer 1">
-      <rect width="24" height="24" style="fill: none"/>
-      <g>
-        <path d="M17.541,15.64258a.91793.91793,0,0,1,.55469-.18555h1.1084a.91586.91586,0,0,1,.55469.18555,1.30889,1.30889,0,0,1,.40429.499,1.57206,1.57206,0,0,1,.15039.68457v5.47754H19.2041V20.21094H18.0957v2.09277H16.9873V16.82617a1.55843,1.55843,0,0,1,.15039-.68457A1.2979,1.2979,0,0,1,17.541,15.64258Zm1.66309,1.10547H18.0957v2.17187h1.1084Z" style="fill: currentColor"/>
-        <path d="M5.68653,22.30351a2.00588,2.00588,0,0,1-2-2v-16A1.92585,1.92585,0,0,1,4.274,2.891a1.92585,1.92585,0,0,1,1.4125-.5875h8l6,6v5.66931h-2V9.30351h-5v-5h-7v16h9.74021v2Z" style="fill: currentColor"/>
-        <rect x="7.69809" y="10.43189" width="4.33778" height="0.79501" style="fill: currentColor"/>
-        <rect x="7.69809" y="12.16889" width="7.31192" height="1.21288" style="fill: currentColor"/>
-        <rect x="7.69809" y="17.14555" width="7.31192" height="1.21288" style="fill: currentColor"/>
-        <rect x="7.69809" y="14.32375" width="7.31192" height="0.57517" style="fill: currentColor"/>
-        <rect x="7.69809" y="15.79848" width="5.25578" height="0.4475" style="fill: currentColor"/>
-      </g>
-    </g>
-  </g>
-    </symbol>
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" viewBox="0 0 24 24"><symbol id="icon-redact-auto" viewBox="0 0 24 24"><g id="Layer_2" data-name="Layer 2"><g id="Layer_1-2" data-name="Layer 1"><rect width="24" height="24" style="fill:none"/><g><path d="M17.541,15.64258a.91793.91793,0,0,1,.55469-.18555h1.1084a.91586.91586,0,0,1,.55469.18555,1.30889,1.30889,0,0,1,.40429.499,1.57206,1.57206,0,0,1,.15039.68457v5.47754H19.2041V20.21094H18.0957v2.09277H16.9873V16.82617a1.55843,1.55843,0,0,1,.15039-.68457A1.2979,1.2979,0,0,1,17.541,15.64258Zm1.66309,1.10547H18.0957v2.17187h1.1084Z" style="fill:currentColor"/><path d="M5.68653,22.30351a2.00588,2.00588,0,0,1-2-2v-16A1.92585,1.92585,0,0,1,4.274,2.891a1.92585,1.92585,0,0,1,1.4125-.5875h8l6,6v5.66931h-2V9.30351h-5v-5h-7v16h9.74021v2Z" style="fill:currentColor"/><rect width="4.338" height=".795" x="7.698" y="10.432" style="fill:currentColor"/><rect width="7.312" height="1.213" x="7.698" y="12.169" style="fill:currentColor"/><rect width="7.312" height="1.213" x="7.698" y="17.146" style="fill:currentColor"/><rect width="7.312" height=".575" x="7.698" y="14.324" style="fill:currentColor"/><rect width="5.256" height=".448" x="7.698" y="15.798" style="fill:currentColor"/></g></g></g></symbol></svg>
@@ -1,13 +1 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- Uploaded to: SVG Repo, www.svgrepo.com, Generator: SVG Repo Mixer Tools -->
-<svg width="800px" height="800px" viewBox="0 0 512 512" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
-    <title>rename</title>
-        <symbol id="icon-rename" viewBox="0 0 512 512">
-    <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
-        <g id="Combined-Shape" fill="currentColor" transform="translate(42.666667, 64.000000)">
-            <path d="M362.666667,1.42108547e-14 L362.666667,21.3333333 L320,21.333 L320,362.666 L362.666667,362.666667 L362.666667,384 L320,383.999 L320,384 L298.666667,384 L298.666,383.999 L256,384 L256,362.666667 L298.666,362.666 L298.666,21.333 L256,21.3333333 L256,1.42108547e-14 L362.666667,1.42108547e-14 Z M426.666667,64 L426.666667,320 L341.333333,320 L341.333333,277.333333 L384,277.333333 L384,106.666667 L341.333333,106.666667 L341.333333,64 L426.666667,64 Z M277.333333,64 L277.333333,320 L3.55271368e-14,320 L3.55271368e-14,64 L277.333333,64 Z M179.2,89.6 L149.333333,89.6 L149.333333,234.666667 C149.333333,248 148.5,256.333333 147.875,264.354167 L147.792993,265.422171 L147.792993,265.422171 L147.714003,266.48894 C147.417695,270.579012 147.2,274.696296 147.2,279.466667 L147.2,279.466667 L177.066667,279.466667 L177.066667,260.266667 C184.941497,273.926888 199.708077,282.130544 215.466667,281.6 C229.540046,281.805757 242.921593,275.508559 251.733333,264.533333 C263.162478,248.989677 269.832496,230.461848 270.933333,211.2 C270.933333,170.666667 249.6,142.933333 217.6,142.933333 C202.507405,142.999748 188.308689,150.099106 179.2,162.133333 L179.2,162.133333 L179.2,89.6 Z M119.466667,162.133333 C107.961824,149.843793 91.4322333,143.546807 74.6666667,145.066667 C57.6785115,144.485924 40.8138255,148.15216 25.6,155.733333 L25.6,155.733333 L34.1333333,177.066667 C45.3979052,171.147831 57.7246848,167.522308 70.4,166.4 C78.5613135,165.511423 86.6853595,168.371259 92.4903835,174.176283 C98.2954074,179.981307 101.155244,188.105353 100.266667,196.266667 L100.266667,196.266667 L100.266667,198.4 L78.9333333,198.4 C65.8181975,197.679203 52.705771,199.864608 40.5333333,204.8 C26.2806563,210.950309 17.6507691,225.621117 19.2,241.066667 C19.0625857,252.057651 23.6679763,262.574827 31.8381493,269.927982 C40.0083223,277.281138 50.9508304,280.757072 61.8666667,279.466667 C77.2795695,280.291768 92.2192911,274.001359 102.4,262.4 L102.4,262.4 L102.4,277.333333 L130.133333,277.333333 C128.292479,266.054406 127.577851,254.620365 128,243.2 L128,243.2 L128,204.8 C129.999138,190.023932 126.995128,175.003882 119.466667,162.133333 Z M98.1333333,213.333333 L98.1333333,238.933333 C92.082572,249.988391 80.836024,257.218314 68.2666667,258.133333 C63.0655139,258.520242 57.9538681,256.621996 54.2659359,252.934064 C50.5780036,249.246132 48.6797582,244.134486 49.0666667,238.933333 C49.0666667,224 59.7333333,215.466667 85.3333333,213.333333 L85.3333333,213.333333 L98.1333333,213.333333 Z M209.066667,166.4 C226.133333,166.4 238.933333,183.466667 238.933333,211.2 C238.933333,238.933333 228.266667,256 211.2,256 C197.298049,255.69869 184.825037,247.383349 179.2,234.666667 L179.2,234.666667 L179.2,187.733333 C185.154203,176.240507 196.263981,168.304951 209.066667,166.4 Z">
-</path>
-        </g>
-    </g>
-    </symbol>
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="800" height="800" version="1.1" viewBox="0 0 512 512"><title>rename</title><symbol id="icon-rename" viewBox="0 0 512 512"><g id="Page-1" fill="none" fill-rule="evenodd" stroke="none" stroke-width="1"><g id="Combined-Shape" fill="currentColor"><path d="M362.666667,1.42108547e-14 L362.666667,21.3333333 L320,21.333 L320,362.666 L362.666667,362.666667 L362.666667,384 L320,383.999 L320,384 L298.666667,384 L298.666,383.999 L256,384 L256,362.666667 L298.666,362.666 L298.666,21.333 L256,21.3333333 L256,1.42108547e-14 L362.666667,1.42108547e-14 Z M426.666667,64 L426.666667,320 L341.333333,320 L341.333333,277.333333 L384,277.333333 L384,106.666667 L341.333333,106.666667 L341.333333,64 L426.666667,64 Z M277.333333,64 L277.333333,320 L3.55271368e-14,320 L3.55271368e-14,64 L277.333333,64 Z M179.2,89.6 L149.333333,89.6 L149.333333,234.666667 C149.333333,248 148.5,256.333333 147.875,264.354167 L147.792993,265.422171 L147.792993,265.422171 L147.714003,266.48894 C147.417695,270.579012 147.2,274.696296 147.2,279.466667 L147.2,279.466667 L177.066667,279.466667 L177.066667,260.266667 C184.941497,273.926888 199.708077,282.130544 215.466667,281.6 C229.540046,281.805757 242.921593,275.508559 251.733333,264.533333 C263.162478,248.989677 269.832496,230.461848 270.933333,211.2 C270.933333,170.666667 249.6,142.933333 217.6,142.933333 C202.507405,142.999748 188.308689,150.099106 179.2,162.133333 L179.2,162.133333 L179.2,89.6 Z M119.466667,162.133333 C107.961824,149.843793 91.4322333,143.546807 74.6666667,145.066667 C57.6785115,144.485924 40.8138255,148.15216 25.6,155.733333 L25.6,155.733333 L34.1333333,177.066667 C45.3979052,171.147831 57.7246848,167.522308 70.4,166.4 C78.5613135,165.511423 86.6853595,168.371259 92.4903835,174.176283 C98.2954074,179.981307 101.155244,188.105353 100.266667,196.266667 L100.266667,196.266667 L100.266667,198.4 L78.9333333,198.4 C65.8181975,197.679203 52.705771,199.864608 40.5333333,204.8 C26.2806563,210.950309 17.6507691,225.621117 19.2,241.066667 C19.0625857,252.057651 23.6679763,262.574827 31.8381493,269.927982 C40.0083223,277.281138 50.9508304,280.757072 61.8666667,279.466667 C77.2795695,280.291768 92.2192911,274.001359 102.4,262.4 L102.4,262.4 L102.4,277.333333 L130.133333,277.333333 C128.292479,266.054406 127.577851,254.620365 128,243.2 L128,243.2 L128,204.8 C129.999138,190.023932 126.995128,175.003882 119.466667,162.133333 Z M98.1333333,213.333333 L98.1333333,238.933333 C92.082572,249.988391 80.836024,257.218314 68.2666667,258.133333 C63.0655139,258.520242 57.9538681,256.621996 54.2659359,252.934064 C50.5780036,249.246132 48.6797582,244.134486 49.0666667,238.933333 C49.0666667,224 59.7333333,215.466667 85.3333333,213.333333 L85.3333333,213.333333 L98.1333333,213.333333 Z M209.066667,166.4 C226.133333,166.4 238.933333,183.466667 238.933333,211.2 C238.933333,238.933333 228.266667,256 211.2,256 C197.298049,255.69869 184.825037,247.383349 179.2,234.666667 L179.2,234.666667 L179.2,187.733333 C185.154203,176.240507 196.263981,168.304951 209.066667,166.4 Z" transform="translate(42.666667, 64.000000)"/></g></g></symbol></svg>
@@ -299,6 +299,18 @@ class RedactControllerMoreTest {
            verify(pdfDocumentFactory, never()).load(any(MultipartFile.class));
        }

+        @Test
+        @DisplayName("null listOfText throws an illegal-argument error before any load")
+        void nullPatternsThrows() throws Exception {
+            RedactPdfRequest request = new RedactPdfRequest();
+            request.setFileInput(pdfFile(new byte[] {1, 2, 3}));
+            request.setListOfText(null);
+
+            assertThatThrownBy(() -> controller.redactPdf(request))
+                    .isInstanceOf(RuntimeException.class);
+            verify(pdfDocumentFactory, never()).load(any(MultipartFile.class));
+        }
+
        @Test
        @DisplayName("null file input is reported as a failure")
        void nullFileThrows() {
@@ -4,7 +4,9 @@ import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;

+import stirling.software.proprietary.access.service.DefaultPrincipalResolver;
 import stirling.software.proprietary.access.service.DefaultTeamLeadLookup;
+import stirling.software.proprietary.access.service.PrincipalResolver;
 import stirling.software.proprietary.access.service.TeamLeadLookup;

 /** Access-layer bean wiring. */
@@ -17,4 +19,11 @@ public class AccessConfig {
    TeamLeadLookup defaultTeamLeadLookup() {
        return new DefaultTeamLeadLookup();
    }
+
+    /** USER/TEAM projection unless another bean is defined (e.g. the saas resolver). */
+    @Bean
+    @ConditionalOnMissingBean(PrincipalResolver.class)
+    PrincipalResolver defaultPrincipalResolver() {
+        return new DefaultPrincipalResolver();
+    }
 }
@@ -25,7 +25,9 @@ import stirling.software.proprietary.access.model.PrincipalType;
 import stirling.software.proprietary.access.model.ResourceGrant;
 import stirling.software.proprietary.access.model.ResourceType;
 import stirling.software.proprietary.access.service.ResourceAccessService;
+import stirling.software.proprietary.security.database.repository.UserRepository;
 import stirling.software.proprietary.security.model.User;
+import stirling.software.proprietary.security.repository.TeamRepository;

 /** Admin endpoints to grant/revoke access to gated resources (the portal, integration configs). */
@RestController
@@ -36,6 +38,8 @@ import stirling.software.proprietary.security.model.User;
 public class ResourceGrantController {

    private final ResourceAccessService accessService;
+    private final UserRepository userRepository;
+    private final TeamRepository teamRepository;

    @GetMapping("/grants")
    public ResponseEntity<?> list(
@@ -45,6 +49,14 @@ public class ResourceGrantController {
        return ResponseEntity.ok(grants.stream().map(this::toDto).toList());
    }

+    @GetMapping("/grants/by-principal")
+    public ResponseEntity<?> listByPrincipal(
+            @RequestParam PrincipalType principalType, @RequestParam Long principalId) {
+        List<ResourceGrant> grants =
+                accessService.listGrantsForPrincipal(principalType, principalId);
+        return ResponseEntity.ok(grants.stream().map(this::toDto).toList());
+    }
+
    @PostMapping("/grants")
    public ResponseEntity<?> create(
            @RequestBody GrantRequest request, @AuthenticationPrincipal User admin) {
@@ -57,17 +69,26 @@ public class ResourceGrantController {
                                    "error",
                                    "resourceType, principalType and principalId are required"));
        }
+        // PORTAL is a singleton (empty resourceId); every other type must name a resource.
+        boolean portal = request.resourceType() == ResourceType.PORTAL;
+        if (!portal && (request.resourceId() == null || request.resourceId().isBlank())) {
+            return ResponseEntity.badRequest()
+                    .body(Map.of("error", "resourceId is required for " + request.resourceType()));
+        }
+        Long principalId = request.principalId();
+        String principalError = validatePrincipalExists(request.principalType(), principalId);
+        if (principalError != null) {
+            return ResponseEntity.badRequest().body(Map.of("error", principalError));
+        }
        AccessPermission permission =
                request.permission() == null ? AccessPermission.USE : request.permission();
-        // PORTAL is a singleton resource; its grants always target the whole type.
-        String resourceId =
-                request.resourceType() == ResourceType.PORTAL ? "" : request.resourceId();
+        String resourceId = portal ? "" : request.resourceId();
        ResourceGrant grant =
                accessService.grant(
                        request.resourceType(),
                        resourceId,
                        request.principalType(),
-                        request.principalId(),
+                        principalId,
                        permission,
                        admin);
        return ResponseEntity.ok(toDto(grant));
@@ -79,6 +100,14 @@ public class ResourceGrantController {
        return ResponseEntity.ok(Map.of("message", "Grant revoked"));
    }

+    // Rejects grants to nonexistent principals (dead rows otherwise).
+    private String validatePrincipalExists(PrincipalType type, Long id) {
+        return switch (type) {
+            case USER -> userRepository.existsById(id) ? null : "User " + id + " does not exist";
+            case TEAM -> teamRepository.existsById(id) ? null : "Team " + id + " does not exist";
+        };
+    }
+
    private Map<String, Object> toDto(ResourceGrant g) {
        Map<String, Object> m = new HashMap<>();
        m.put("id", g.getId());
@@ -54,4 +54,15 @@ public abstract class OwnedResource {
    public Long getOwnerTeamId() {
        return ownerTeam != null ? ownerTeam.getId() : null;
    }
+
+    /** Owner as a principal ref; null when server-owned (admin-only ownership). */
+    public PrincipalRef getOwnerRef() {
+        if (getOwnerUserId() != null) {
+            return PrincipalRef.user(getOwnerUserId());
+        }
+        if (getOwnerTeamId() != null) {
+            return PrincipalRef.team(getOwnerTeamId());
+        }
+        return null;
+    }
 }
@@ -0,0 +1,20 @@
+package stirling.software.proprietary.access.model;
+
+import java.util.Locale;
+
+/** A (type, id) principal pair; the atom grants and ownership are expressed in. */
+public record PrincipalRef(PrincipalType type, Long id) {
+
+    public static PrincipalRef user(Long id) {
+        return new PrincipalRef(PrincipalType.USER, id);
+    }
+
+    public static PrincipalRef team(Long id) {
+        return new PrincipalRef(PrincipalType.TEAM, id);
+    }
+
+    /** Canonical engine wire form, e.g. "user:12". */
+    public String token() {
+        return type.name().toLowerCase(Locale.ROOT) + ":" + id;
+    }
+}
@@ -1,6 +1,6 @@
 package stirling.software.proprietary.access.model;

-/** Who a {@link ResourceGrant} is granted to. Org-wide access is expressed via default policy. */
+/** Who a {@link ResourceGrant} is granted to. */
 public enum PrincipalType {
    USER,
    TEAM
@@ -3,11 +3,15 @@ package stirling.software.proprietary.access.repository;
 import java.util.List;

 import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
 import org.springframework.stereotype.Repository;

 import stirling.software.proprietary.access.model.PrincipalType;
 import stirling.software.proprietary.access.model.ResourceGrant;
 import stirling.software.proprietary.access.model.ResourceType;
+import stirling.software.proprietary.security.model.User;

@Repository
 public interface ResourceGrantRepository extends JpaRepository<ResourceGrant, Long> {
@@ -18,8 +22,20 @@ public interface ResourceGrantRepository extends JpaRepository<ResourceGrant, Lo
    List<ResourceGrant> findByResourceTypeAndPrincipalTypeAndPrincipalId(
            ResourceType resourceType, PrincipalType principalType, Long principalId);

+    /** All grants held by a principal, across resource types (for the manage-access view). */
+    List<ResourceGrant> findByPrincipalTypeAndPrincipalId(
+            PrincipalType principalType, Long principalId);
+
    void deleteByResourceTypeAndResourceId(ResourceType resourceType, String resourceId);

+    /** Removes every grant held by a principal; used when the user/team behind it is deleted. */
+    void deleteByPrincipalTypeAndPrincipalId(PrincipalType principalType, Long principalId);
+
+    // Detach issued grants so deleting the granting user does not hit the FK.
+    @Modifying
+    @Query("update ResourceGrant g set g.grantedBy = null where g.grantedBy = :user")
+    void clearGrantedBy(@Param("user") User user);
+
    boolean existsByResourceTypeAndResourceIdAndPrincipalTypeAndPrincipalId(
            ResourceType resourceType,
            String resourceId,
@@ -11,7 +11,12 @@ import stirling.software.proprietary.access.service.ResourceAccessService;
 import stirling.software.proprietary.security.model.User;
 import stirling.software.proprietary.security.service.UserService;

-/** {@code @PreAuthorize} bean for portal-access checks. Active in self-hosted and saas. */
+/**
+ * {@code @PreAuthorize} bean for portal-access checks. Active in self-hosted and saas. Convention:
+ * every portal-exclusive endpoint is gated with
+ * {@code @PreAuthorize("@resourceAccess.canUsePortal()")}; endpoints shared with the editor (e.g.
+ * the policies API) must NOT be.
+ */
@Component("resourceAccess")
@RequiredArgsConstructor
 public class ResourceAccessSecurity {
@@ -0,0 +1,32 @@
+package stirling.software.proprietary.access.service;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import stirling.software.proprietary.access.model.PrincipalRef;
+import stirling.software.proprietary.security.model.User;
+
+/**
+ * Self-hosted projection: the user and their team. One deployment = one org, so ORG_ALL is open.
+ */
+public class DefaultPrincipalResolver implements PrincipalResolver {
+
+    @Override
+    public Set<PrincipalRef> principalsOf(User user) {
+        if (user == null) {
+            return Set.of();
+        }
+        Set<PrincipalRef> principals = new HashSet<>();
+        principals.add(PrincipalRef.user(user.getId()));
+        if (user.getTeam() != null) {
+            principals.add(PrincipalRef.team(user.getTeam().getId()));
+        }
+        return principals;
+    }
+
+    // Self-hosted is a single deployment-wide org, so ORG_ALL admits every authenticated user.
+    @Override
+    public boolean allowsDeploymentWideAccess() {
+        return true;
+    }
+}
@@ -0,0 +1,33 @@
+package stirling.software.proprietary.access.service;
+
+import org.springframework.stereotype.Component;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.common.model.enumeration.TeamRole;
+import stirling.software.proprietary.security.model.User;
+import stirling.software.proprietary.security.repository.TeamMembershipRepository;
+
+/** Real lookup backed by team_memberships LEADER rows; wins over the no-op default bean. */
+@Component
+@RequiredArgsConstructor
+public class MembershipTeamLeadLookup implements TeamLeadLookup {
+
+    private final TeamMembershipRepository memberships;
+
+    @Override
+    public boolean isAnyTeamLeader(User user) {
+        return user != null
+                && user.getId() != null
+                && memberships.existsByUserIdAndRole(user.getId(), TeamRole.LEADER);
+    }
+
+    @Override
+    public boolean isLeaderOfTeam(User user, Long teamId) {
+        return user != null
+                && user.getId() != null
+                && teamId != null
+                && memberships.existsByTeamIdAndUserIdAndRole(
+                        teamId, user.getId(), TeamRole.LEADER);
+    }
+}
@@ -36,15 +36,19 @@ public class OwnershipService {
        return accessService.canUseResource(
                type,
                String.valueOf(resource.getId()),
-                resource.getOwnerUserId(),
+                resource.getOwnerRef(),
                resource.getDefaultAccess(),
                user);
    }

    /** Whether the user may manage the resource. */
    public boolean canManage(ResourceType type, OwnedResource resource, User user) {
+        // Disabled resources bypass grants for MANAGE too: admin/owner only.
+        if (!resource.isEnabled()) {
+            return isAdmin(user) || isOwner(resource, user);
+        }
        return accessService.canManageResource(
-                type, String.valueOf(resource.getId()), resource.getOwnerUserId(), user);
+                type, String.valueOf(resource.getId()), resource.getOwnerRef(), user);
    }

    /**
@@ -0,0 +1,28 @@
+package stirling.software.proprietary.access.service;
+
+import java.util.Set;
+import java.util.stream.Collectors;
+
+import stirling.software.proprietary.access.model.PrincipalRef;
+import stirling.software.proprietary.security.model.User;
+
+/** Projects a user onto the set of principals they act as. */
+public interface PrincipalResolver {
+
+    /** Every principal the user acts as; empty for a null user. */
+    Set<PrincipalRef> principalsOf(User user);
+
+    /**
+     * Whether this deployment treats every authenticated user as one org, so the {@code ORG_ALL}
+     * default policy admits anyone. Self-hosted: true. Multi-tenant saas: false, so an {@code
+     * ORG_ALL} resource can't leak across tenants. Defaults to false (deny) for safety.
+     */
+    default boolean allowsDeploymentWideAccess() {
+        return false;
+    }
+
+    /** Canonical wire tokens for the engine, e.g. "user:12". */
+    default Set<String> principalTokens(User user) {
+        return principalsOf(user).stream().map(PrincipalRef::token).collect(Collectors.toSet());
+    }
+}
@@ -14,6 +14,7 @@ import lombok.extern.slf4j.Slf4j;
 import stirling.software.common.model.enumeration.Role;
 import stirling.software.proprietary.access.model.AccessPermission;
 import stirling.software.proprietary.access.model.DefaultAccessPolicy;
+import stirling.software.proprietary.access.model.PrincipalRef;
 import stirling.software.proprietary.access.model.PrincipalType;
 import stirling.software.proprietary.access.model.ResourceGrant;
 import stirling.software.proprietary.access.model.ResourceType;
@@ -29,6 +30,7 @@ public class ResourceAccessService {

    private final ResourceGrantRepository grantRepository;
    private final TeamLeadLookup teamLeadLookup;
+    private final PrincipalResolver principalResolver;

    @Value("${security.portal.defaultAccess:ADMINS_AND_TEAM_LEADS}")
    private DefaultAccessPolicy portalDefaultPolicy;
@@ -44,28 +46,28 @@ public class ResourceAccessService {
    public boolean canUseResource(
            ResourceType type,
            String resourceId,
-            Long ownerUserId,
+            PrincipalRef owner,
            DefaultAccessPolicy defaultPolicy,
            User user) {
        if (user == null) {
            return false;
        }
-        if (isOwner(ownerUserId, user) || isAdmin(user)) {
+        if (isOwner(owner, user) || isAdmin(user)) {
            return true;
        }
        if (hasGrant(type, normalize(resourceId), user, AccessPermission.USE)) {
            return true;
        }
-        return matchesDefault(defaultPolicy, user);
+        return matchesDefault(defaultPolicy, owner, user);
    }

    /** Whether the user may manage (edit/delete/share) a resource. No default-policy fallback. */
    public boolean canManageResource(
-            ResourceType type, String resourceId, Long ownerUserId, User user) {
+            ResourceType type, String resourceId, PrincipalRef owner, User user) {
        if (user == null) {
            return false;
        }
-        if (isOwner(ownerUserId, user) || isAdmin(user)) {
+        if (isOwner(owner, user) || isAdmin(user)) {
            return true;
        }
        return hasGrant(type, normalize(resourceId), user, AccessPermission.MANAGE);
@@ -110,21 +112,22 @@ public class ResourceAccessService {
        return grantRepository.findByResourceTypeAndResourceId(type, normalize(resourceId));
    }

-    /** Resource ids of the given type that this user (or their team) holds any grant on. */
+    /** Every grant a principal holds, for the per-user/per-team manage-access view. */
+    public List<ResourceGrant> listGrantsForPrincipal(
+            PrincipalType principalType, Long principalId) {
+        return grantRepository.findByPrincipalTypeAndPrincipalId(principalType, principalId);
+    }
+
+    /** Resource ids of the given type that any of the user's principals holds a grant on. */
    public Set<String> grantedResourceIds(ResourceType type, User user) {
        if (user == null) {
            return Set.of();
        }
        Set<String> ids = new HashSet<>();
-        for (ResourceGrant g :
-                grantRepository.findByResourceTypeAndPrincipalTypeAndPrincipalId(
-                        type, PrincipalType.USER, user.getId())) {
-            ids.add(g.getResourceId());
-        }
-        if (user.getTeam() != null) {
+        for (PrincipalRef principal : principalResolver.principalsOf(user)) {
            for (ResourceGrant g :
                    grantRepository.findByResourceTypeAndPrincipalTypeAndPrincipalId(
-                            type, PrincipalType.TEAM, user.getTeam().getId())) {
+                            type, principal.type(), principal.id())) {
                ids.add(g.getResourceId());
            }
        }
@@ -135,18 +138,12 @@ public class ResourceAccessService {

    private boolean hasGrant(
            ResourceType type, String resourceId, User user, AccessPermission required) {
-        Long teamId = user.getTeam() != null ? user.getTeam().getId() : null;
+        Set<PrincipalRef> principals = principalResolver.principalsOf(user);
        for (ResourceGrant g : grantRepository.findByResourceTypeAndResourceId(type, resourceId)) {
            if (!permissionSatisfies(g.getPermission(), required)) {
                continue;
            }
-            if (g.getPrincipalType() == PrincipalType.USER
-                    && g.getPrincipalId().equals(user.getId())) {
-                return true;
-            }
-            if (g.getPrincipalType() == PrincipalType.TEAM
-                    && teamId != null
-                    && g.getPrincipalId().equals(teamId)) {
+            if (principals.contains(new PrincipalRef(g.getPrincipalType(), g.getPrincipalId()))) {
                return true;
            }
        }
@@ -161,20 +158,40 @@ public class ResourceAccessService {
        return held == AccessPermission.MANAGE;
    }

-    private boolean matchesDefault(DefaultAccessPolicy policy, User user) {
+    private boolean matchesDefault(DefaultAccessPolicy policy, PrincipalRef owner, User user) {
        if (policy == null) {
            return false;
        }
        return switch (policy) {
-            case ORG_ALL -> true;
-            // Admins already pass above; only team leads here.
-            case ADMINS_AND_TEAM_LEADS -> teamLeadLookup.isAnyTeamLeader(user);
+            // Deployment-wide only where the resolver treats everyone as one org; saas resolvers
+            // return false, so ORG_ALL cannot leak a tenant's resource to another tenant's users.
+            case ORG_ALL -> principalResolver.allowsDeploymentWideAccess();
+            // Admins already pass above; only team leads here, scoped to the owning team.
+            case ADMINS_AND_TEAM_LEADS -> matchesTeamLeadDefault(owner, user);
            case EXPLICIT_ONLY -> false;
        };
    }

-    private boolean isOwner(Long ownerUserId, User user) {
-        return ownerUserId != null && ownerUserId.equals(user.getId());
+    // Portal (no owner) admits any team lead; a team-owned resource admits only that team's
+    // leads; a user-owned resource admits no extra leads.
+    private boolean matchesTeamLeadDefault(PrincipalRef owner, User user) {
+        if (owner == null) {
+            return teamLeadLookup.isAnyTeamLeader(user);
+        }
+        return owner.type() == PrincipalType.TEAM
+                && owner.id() != null
+                && teamLeadLookup.isLeaderOfTeam(user, owner.id());
+    }
+
+    // Team owners are the owning team's leaders; plain members are not.
+    private boolean isOwner(PrincipalRef owner, User user) {
+        if (owner == null || owner.id() == null) {
+            return false;
+        }
+        return switch (owner.type()) {
+            case USER -> owner.id().equals(user.getId());
+            case TEAM -> teamLeadLookup.isLeaderOfTeam(user, owner.id());
+        };
    }

    private boolean isAdmin(User user) {
@@ -18,15 +18,26 @@ public class SecretMasker {
    // Cap recursion so a pathologically nested payload cannot overflow the stack.
    private static final int MAX_DEPTH = 32;

+    // Key-name substrings that mark a value sensitive. Over-masking a non-secret is
+    // safe; leaking a secret is not, so this errs broad - but a per-type schema
+    // whitelist would be a stronger boundary for free-form config (follow-up).
    private static final Set<String> SENSITIVE_HINTS =
            Set.of(
                    "secret",
                    "password",
+                    "passphrase",
+                    "pwd",
                    "token",
                    "apikey",
                    "accesskey",
                    "credential",
-                    "privatekey");
+                    "privatekey",
+                    "authorization",
+                    "cookie",
+                    "session",
+                    "connectionstring",
+                    "bearer",
+                    "signature");

    /** Replace sensitive values with the mask (recursively) for safe display. */
    public Map<String, Object> mask(Map<String, Object> config) {
@@ -73,18 +84,24 @@ public class SecretMasker {

    private Map<String, Object> merge(
            Map<String, Object> stored, Map<String, Object> incoming, int depth) {
-        Map<String, Object> out = new LinkedHashMap<>(stored);
+        // Replace semantics (PUT): the result is the incoming document, except a redacted secret
+        // keeps its stored value. Keys absent from incoming are dropped, so edits can remove them.
+        Map<String, Object> out = new LinkedHashMap<>();
        for (Map.Entry<String, Object> e : incoming.entrySet()) {
            String key = e.getKey();
            Object value = e.getValue();
            if (isSensitive(key)) {
-                if (!isRedacted(value, depth)) {
+                if (isRedacted(value, depth)) {
+                    if (stored.containsKey(key)) {
+                        out.put(key, stored.get(key)); // keep the stored secret
+                    }
+                } else {
                    out.put(key, value); // a real new secret replaces the stored one
                }
-                continue; // redacted (blank / mask) -> keep stored
+                continue;
            }
            if (depth < MAX_DEPTH
-                    && out.get(key) instanceof Map<?, ?> s
+                    && stored.get(key) instanceof Map<?, ?> s
                    && value instanceof Map<?, ?> i) {
                out.put(key, merge(castMap(s), castMap(i), depth + 1));
            } else {
@@ -142,6 +142,9 @@ public class AuditAspect {
            auditService.addTimingData(
                    auditData, startTime, resp, auditedAnnotation.level(), isHttpRequest);

+            // Merge controller-set policy context + the internal-automation marker onto the event.
+            auditService.addAutomationContext(auditData, req);
+
            // Resolve the event type based on annotation and context
            String httpMethod = null;
            String path = null;
@@ -0,0 +1,18 @@
+package stirling.software.proprietary.audit;
+
+/**
+ * Request-scoped keys a controller can set to enrich its own audit event with context the generic
+ * aspect can't infer from the HTTP request alone (e.g. the policy a pipeline run belongs to). The
+ * aspect copies these into the audit data in its {@code finally} block, after the controller body
+ * has run. See {@code AuditService#addAutomationContext}.
+ */
+public final class AuditContext {
+
+    /** Request attribute: the name of the policy/pipeline a run executes. */
+    public static final String REQ_ATTR_POLICY_NAME = "stirling.audit.policyName";
+
+    /** Request attribute: the ordered tool endpoint paths a run executes. */
+    public static final String REQ_ATTR_POLICY_STEPS = "stirling.audit.policySteps";
+
+    private AuditContext() {}
+}
@@ -205,6 +205,10 @@ public class ControllerAuditAspect {
                // Call auditService but with isHttpRequest=true to skip additional timing
                auditService.addTimingData(data, start, resp, level, true);

+                // Merge controller-set policy context + the internal-automation marker (set after
+                // the body ran, so it must happen here rather than with the pre-proceed HTTP data).
+                auditService.addAutomationContext(data, req);
+
                // Resolve the event type using the unified method
                AuditEventType eventType =
                        auditService.resolveEventType(
@@ -0,0 +1,136 @@
+package stirling.software.proprietary.classification;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnBooleanProperty;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
+
+import io.swagger.v3.oas.annotations.Hidden;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+import lombok.RequiredArgsConstructor;
+
+import stirling.software.common.model.ApplicationProperties;
+import stirling.software.common.service.UserServiceInterface;
+import stirling.software.proprietary.classification.model.ClassificationLabels;
+import stirling.software.proprietary.classification.model.LabelsValidator;
+import stirling.software.proprietary.classification.store.ClassificationLabelStore;
+import stirling.software.proprietary.classification.store.TeamLabelsEntity;
+import stirling.software.proprietary.policy.config.PolicyManagementAuthority;
+
+/**
+ * Read/write the team's classification label set — the flat vocabulary the document classifier runs
+ * against. Shared and team-scoped exactly like policies: every user reads their own team's labels,
+ * and only a user who may edit policies (a team leader on SaaS, the global admin self-hosted; see
+ * {@link PolicyManagementAuthority}) may change it — gated only when login is enabled, since
+ * single-user deployments trust the local operator. A team with no stored labels reads as {@code
+ * 204}; that team has no vocabulary, so its documents are not classified (there is no built-in
+ * default on the backend or the engine — the label data lives only in the frontend).
+ */
+@RestController
+@RequestMapping("/api/v1/classification/labels")
+@Hidden
+@RequiredArgsConstructor
+@Tag(name = "Classification", description = "Team-scoped document-classification labels")
+@ConditionalOnBooleanProperty(name = "policies.enabled")
+public class ClassificationLabelsController {
+
+    private final ClassificationLabelStore labelStore;
+    private final PolicyManagementAuthority policyManagementAuthority;
+    private final ApplicationProperties applicationProperties;
+    private final UserServiceInterface userService;
+
+    @GetMapping
+    @Operation(
+            summary = "Get the team's classification labels",
+            description =
+                    "Returns the caller's team label set, or 204 when the team has none (its"
+                            + " documents are then not classified).")
+    public ResponseEntity<ClassificationLabels> getTeamLabels() {
+        return labelStore
+                .findByTeam(currentTeamId())
+                .map(ResponseEntity::ok)
+                .orElseGet(() -> ResponseEntity.noContent().build());
+    }
+
+    @PutMapping(consumes = MediaType.APPLICATION_JSON_VALUE)
+    @Operation(
+            summary = "Save the team's classification labels",
+            description =
+                    "Validates and stores the label set for the caller's team, shared by everyone"
+                            + " on the team. Requires the policy-editor role for the team.")
+    public ResponseEntity<ClassificationLabels> saveTeamLabels(
+            @RequestBody ClassificationLabels labels) {
+        requireEditingAllowed();
+        validate(labels);
+        ClassificationLabels saved = labelStore.save(currentTeamId(), labels, currentUsername());
+        return ResponseEntity.ok(saved);
+    }
+
+    @DeleteMapping
+    @Operation(
+            summary = "Reset the team's classification labels",
+            description =
+                    "Removes the team's stored label set; its documents are then not classified"
+                            + " until labels are saved again. Requires the policy-editor role for the"
+                            + " team.")
+    public ResponseEntity<Void> resetTeamLabels() {
+        requireEditingAllowed();
+        labelStore.deleteByTeam(currentTeamId());
+        return ResponseEntity.noContent().build();
+    }
+
+    private static void validate(ClassificationLabels labels) {
+        try {
+            LabelsValidator.validate(labels);
+        } catch (IllegalArgumentException e) {
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, e.getMessage());
+        }
+    }
+
+    /**
+     * Editing the team labels requires the editor role for the caller's team — the same gate
+     * policies use (team leader on SaaS, global admin self-hosted). Single-user deployments (login
+     * disabled) have no such role, so they trust the local operator.
+     */
+    private void requireEditingAllowed() {
+        if (!applicationProperties.getSecurity().isEnableLogin()) {
+            return;
+        }
+        if (!policyManagementAuthority.canEditPolicies()) {
+            throw new ResponseStatusException(
+                    HttpStatus.FORBIDDEN,
+                    "The team classification labels may only be changed by a team leader");
+        }
+    }
+
+    /**
+     * The caller's team key. With login disabled the single operator owns the {@link
+     * TeamLabelsEntity#NO_TEAM} sentinel row; with login enabled a caller with no resolvable team
+     * is an error rather than being dropped into the shared sentinel bucket (which would let
+     * unteamed users read and overwrite each other's "team" labels).
+     */
+    private Long currentTeamId() {
+        Long teamId = policyManagementAuthority.currentUserTeamId();
+        if (teamId != null) {
+            return teamId;
+        }
+        if (!applicationProperties.getSecurity().isEnableLogin()) {
+            return TeamLabelsEntity.NO_TEAM;
+        }
+        throw new ResponseStatusException(
+                HttpStatus.UNAUTHORIZED, "Could not resolve the current user's team");
+    }
+
+    private String currentUsername() {
+        return userService == null ? null : userService.getCurrentUsername();
+    }
+}
@@ -0,0 +1,9 @@
+package stirling.software.proprietary.classification.model;
+
+/**
+ * One entry in the classification vocabulary. {@code id} is the label's stable identity (a slug,
+ * unique within a set): it is what the engine returns and what is stored on the document. {@code
+ * name} is the human display text the classifier model reasons over. {@code icon} is an optional
+ * presentational key (a Material Symbols name shown in the file sidebar); the engine never sees it.
+ */
+public record ClassificationLabel(String id, String name, String icon) {}
@@ -0,0 +1,16 @@
+package stirling.software.proprietary.classification.model;
+
+import java.util.List;
+
+/**
+ * A flat multi-label classification vocabulary — the set of labels a document may be assigned.
+ * Stored per team (admin-edited, shared by everyone on the team); the classifier runs against these
+ * label names. A team with no stored set has no vocabulary, so its documents are not classified —
+ * neither the backend nor the engine holds a default of its own.
+ */
+public record ClassificationLabels(List<ClassificationLabel> labels) {
+
+    public ClassificationLabels {
+        labels = labels == null ? List.of() : List.copyOf(labels);
+    }
+}
@@ -0,0 +1,71 @@
+package stirling.software.proprietary.classification.model;
+
+import java.util.HashSet;
+import java.util.Locale;
+import java.util.Set;
+import java.util.regex.Pattern;
+
+/**
+ * Structural validation for a user- or admin-supplied label set, run before it is stored so a
+ * malformed vocabulary can never reach the classifier. Mirrors the invariants the engine relies on:
+ * non-blank ids and names, each unique within the set (ids exactly, names case-insensitively).
+ */
+public final class LabelsValidator {
+
+    private LabelsValidator() {}
+
+    // Generous upper bounds so a legitimate label set is never blocked, but a single team or user
+    // can't store an unbounded blob that would bloat the row, balloon the classifier prompt, or
+    // exhaust memory on deserialize.
+    static final int MAX_LABELS = 500;
+    static final int MAX_TEXT_LENGTH = 128;
+
+    // Icon is a Material Symbols key (lowercase, digits, hyphens). Enforce the SHAPE server-side —
+    // the exact allowlist lives in the frontend — so a client bypassing the UI can't store
+    // arbitrary
+    // text that would render as garbage (or worse) in every teammate's sidebar.
+    private static final Pattern ICON_KEY = Pattern.compile("^[a-z0-9-]+$");
+
+    /**
+     * @throws IllegalArgumentException with a human-readable message when the label set is invalid.
+     */
+    public static void validate(ClassificationLabels labels) {
+        if (labels == null || labels.labels() == null) {
+            throw new IllegalArgumentException("Labels are required");
+        }
+        if (labels.labels().size() > MAX_LABELS) {
+            throw new IllegalArgumentException("Too many labels (max " + MAX_LABELS + ")");
+        }
+        Set<String> ids = new HashSet<>();
+        Set<String> names = new HashSet<>();
+        for (ClassificationLabel label : labels.labels()) {
+            requireText(label.id(), "Label id");
+            requireText(label.name(), "Label name");
+            if (label.icon() != null && !label.icon().isEmpty()) {
+                if (label.icon().length() > MAX_TEXT_LENGTH) {
+                    throw new IllegalArgumentException(
+                            "Label icon is too long (max " + MAX_TEXT_LENGTH + " characters)");
+                }
+                if (!ICON_KEY.matcher(label.icon()).matches()) {
+                    throw new IllegalArgumentException("Invalid label icon: " + label.icon());
+                }
+            }
+            if (!ids.add(label.id().trim())) {
+                throw new IllegalArgumentException("Duplicate label id: " + label.id());
+            }
+            if (!names.add(label.name().trim().toLowerCase(Locale.ROOT))) {
+                throw new IllegalArgumentException("Duplicate label name: " + label.name());
+            }
+        }
+    }
+
+    private static void requireText(String value, String field) {
+        if (value == null || value.isBlank()) {
+            throw new IllegalArgumentException(field + " must not be blank");
+        }
+        if (value.trim().length() > MAX_TEXT_LENGTH) {
+            throw new IllegalArgumentException(
+                    field + " is too long (max " + MAX_TEXT_LENGTH + " characters)");
+        }
+    }
+}
@@ -0,0 +1,22 @@
+package stirling.software.proprietary.classification.store;
+
+import java.util.Optional;
+
+import stirling.software.proprietary.classification.model.ClassificationLabels;
+
+/**
+ * Stores one {@link ClassificationLabels} set per team. A {@code null} teamId addresses the
+ * unteamed set (login disabled / no resolvable team), mirroring how the policy store treats a null
+ * team.
+ */
+public interface ClassificationLabelStore {
+
+    /** The team's stored labels, or empty when it has none (callers then skip classification). */
+    Optional<ClassificationLabels> findByTeam(Long teamId);
+
+    /** Create or replace the team's labels. Returns the stored value. */
+    ClassificationLabels save(Long teamId, ClassificationLabels labels, String updatedBy);
+
+    /** Remove the team's labels (reset to default). Returns whether a set existed. */
+    boolean deleteByTeam(Long teamId);
+}
@@ -0,0 +1,36 @@
+package stirling.software.proprietary.classification.store;
+
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.ConcurrentHashMap;
+
+import stirling.software.proprietary.classification.model.ClassificationLabels;
+
+/**
+ * In-memory {@link ClassificationLabelStore} for tests and any future no-database mode. {@link
+ * JpaClassificationLabelStore} is the runtime bean.
+ */
+public class InProcessClassificationLabelStore implements ClassificationLabelStore {
+
+    private final Map<Long, ClassificationLabels> byTeam = new ConcurrentHashMap<>();
+
+    @Override
+    public Optional<ClassificationLabels> findByTeam(Long teamId) {
+        return Optional.ofNullable(byTeam.get(key(teamId)));
+    }
+
+    @Override
+    public ClassificationLabels save(Long teamId, ClassificationLabels labels, String updatedBy) {
+        byTeam.put(key(teamId), labels);
+        return labels;
+    }
+
+    @Override
+    public boolean deleteByTeam(Long teamId) {
+        return byTeam.remove(key(teamId)) != null;
+    }
+
+    private static long key(Long teamId) {
+        return teamId == null ? TeamLabelsEntity.NO_TEAM : teamId;
+    }
+}
@@ -0,0 +1,76 @@
+package stirling.software.proprietary.classification.store;
+
+import java.time.Instant;
+import java.util.Optional;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnBooleanProperty;
+import org.springframework.stereotype.Service;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.proprietary.classification.model.ClassificationLabels;
+
+import tools.jackson.core.JacksonException;
+import tools.jackson.databind.ObjectMapper;
+
+/**
+ * Durable {@link ClassificationLabelStore} backed by JPA; the runtime store. Gated on {@code
+ * policies.enabled} — stored labels only matter when the Classification policy can run — so it
+ * shares the policy subsystem's on/off switch. Each label set is persisted as JSON via {@link
+ * TeamLabelsEntity}.
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+@ConditionalOnBooleanProperty(name = "policies.enabled")
+public class JpaClassificationLabelStore implements ClassificationLabelStore {
+
+    private final TeamLabelsRepository teamRepository;
+    private final ObjectMapper objectMapper;
+
+    @Override
+    public Optional<ClassificationLabels> findByTeam(Long teamId) {
+        return teamRepository
+                .findById(key(teamId))
+                .flatMap(entity -> parse(entity.getLabelsJson(), "team " + teamId));
+    }
+
+    @Override
+    public ClassificationLabels save(Long teamId, ClassificationLabels labels, String updatedBy) {
+        TeamLabelsEntity entity = new TeamLabelsEntity();
+        entity.setTeamId(key(teamId));
+        entity.setLabelsJson(objectMapper.writeValueAsString(labels));
+        entity.setUpdatedAt(Instant.now());
+        entity.setUpdatedBy(updatedBy);
+        teamRepository.save(entity);
+        return labels;
+    }
+
+    @Override
+    public boolean deleteByTeam(Long teamId) {
+        long id = key(teamId);
+        if (!teamRepository.existsById(id)) {
+            return false;
+        }
+        teamRepository.deleteById(id);
+        return true;
+    }
+
+    private Optional<ClassificationLabels> parse(String json, String owner) {
+        try {
+            return Optional.of(objectMapper.readValue(json, ClassificationLabels.class));
+        } catch (JacksonException e) {
+            // A stored label set that no longer parses (corruption / manual DB edit) must not break
+            // classification: drop it so the caller treats the team as having no labels (and skips
+            // classification) rather than surfacing a 500 on every upload.
+            log.warn("Discarding unparseable stored labels for {}: {}", owner, e.getMessage());
+            return Optional.empty();
+        }
+    }
+
+    /** Map the nullable team id onto the entity's non-null key (sentinel for the unteamed case). */
+    private static long key(Long teamId) {
+        return teamId == null ? TeamLabelsEntity.NO_TEAM : teamId;
+    }
+}
@@ -0,0 +1,47 @@
+package stirling.software.proprietary.classification.store;
+
+import java.io.Serializable;
+import java.time.Instant;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+/**
+ * JPA row for a team's classification labels — one row per team. The label set lives as JSON in
+ * {@code labelsJson} (authoritative on read). {@code teamId} is the natural key; the sentinel
+ * {@link #NO_TEAM} stands in for the unteamed (login-disabled / self-hosted single-team) case,
+ * since a primary key can't be null (policies store a nullable {@code team_id}, but this table is
+ * keyed one-per-team). Kept decoupled from the security entities — {@code teamId} is a plain value,
+ * not a foreign key — so classification can be enabled or disabled without touching them.
+ */
+@Entity
+@Table(name = "classification_labels")
+@NoArgsConstructor
+@Getter
+@Setter
+public class TeamLabelsEntity implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    /** Sentinel key for the unteamed label set (login disabled / no resolvable team). */
+    public static final long NO_TEAM = 0L;
+
+    @Id
+    @Column(name = "team_id")
+    private long teamId;
+
+    @Column(name = "labels_json", columnDefinition = "text")
+    private String labelsJson;
+
+    @Column(name = "updated_at")
+    private Instant updatedAt;
+
+    @Column(name = "updated_by")
+    private String updatedBy;
+}
@@ -0,0 +1,7 @@
+package stirling.software.proprietary.classification.store;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.stereotype.Repository;
+
+@Repository
+public interface TeamLabelsRepository extends JpaRepository<TeamLabelsEntity, Long> {}
@@ -133,29 +133,45 @@ public final class S3Clients {
     * storage.s3.allow-private-endpoints=true}.
     */
    static void validateEndpointHost(URI endpoint, boolean allowPrivate) {
+        validateEndpointHost(
+                endpoint,
+                allowPrivate,
+                "storage.s3.endpoint",
+                "set storage.s3.allow-private-endpoints=true to opt in"
+                        + " (e.g. for MinIO or in-cluster S3).");
+    }
+
+    /**
+     * The same private-address guard for S3 endpoints configured outside the {@code storage.s3.*}
+     * block (e.g. per-source policy config), with the setting named in messages supplied by the
+     * caller.
+     */
+    public static void validateEndpointHost(
+            URI endpoint, boolean allowPrivate, String settingName, String optInHint) {
        if (allowPrivate) {
            return;
        }
        String host = endpoint.getHost();
        if (host == null || host.isBlank()) {
-            throw new IllegalStateException("storage.s3.endpoint must include a host: " + endpoint);
+            throw new IllegalStateException(settingName + " must include a host: " + endpoint);
        }
        InetAddress[] addresses;
        try {
            addresses = InetAddress.getAllByName(host);
        } catch (UnknownHostException e) {
            throw new IllegalStateException(
-                    "Unable to resolve storage.s3.endpoint host '" + host + "'", e);
+                    "Unable to resolve " + settingName + " host '" + host + "'", e);
        }
        for (InetAddress address : addresses) {
            if (isPrivateOrLocal(address)) {
                throw new IllegalStateException(
-                        "storage.s3.endpoint host '"
+                        settingName
+                                + " host '"
                                + host
                                + "' resolves to private/link-local address "
                                + address.getHostAddress()
-                                + "; set storage.s3.allow-private-endpoints=true to opt in"
-                                + " (e.g. for MinIO or in-cluster S3).");
+                                + "; "
+                                + optInHint);
            }
        }
    }
@@ -0,0 +1,218 @@
+package stirling.software.proprietary.controller.api;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.core.io.Resource;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.multipart.MultipartFile;
+
+import io.github.pixee.security.Filenames;
+import io.swagger.v3.oas.annotations.Hidden;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.common.service.CustomPDFDocumentFactory;
+import stirling.software.common.service.PdfMetadataService;
+import stirling.software.common.service.UserServiceInterface;
+import stirling.software.common.util.TempFileManager;
+import stirling.software.common.util.WebResponseUtils;
+import stirling.software.proprietary.classification.model.ClassificationLabel;
+import stirling.software.proprietary.classification.store.ClassificationLabelStore;
+import stirling.software.proprietary.model.api.ai.AiPageText;
+import stirling.software.proprietary.policy.config.PolicyManagementAuthority;
+import stirling.software.proprietary.service.AiEngineClient;
+import stirling.software.proprietary.service.PdfContentExtractor;
+
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
+import tools.jackson.databind.node.ObjectNode;
+
+/**
+ * Dispatchable tool that classifies a PDF and writes the result into its metadata.
+ *
+ * <p>Runs as a Classification-policy pipeline step: it reads a bounded page window, asks the AI
+ * engine to classify the document against the caller's team label set, and stores the engine's JSON
+ * answer — minus the transport-only {@code outcome} field — in the custom Info-dictionary key
+ * {@link PdfMetadataService#CLASSIFICATION_KEY}. Returns the labelled PDF. Not intended for direct
+ * client use.
+ */
+@Slf4j
+@Hidden
+@RestController
+@RequestMapping("/api/v1/ai/tools")
+@Tag(name = "AI Tools", description = "Dispatchable AI-backed tools.")
+public class ClassifyLabelController {
+
+    /** Pages read from each end of the document — mirrors the engine's window. */
+    private static final int WINDOW_PAGES = 2;
+
+    private static final String CLASSIFY_ENDPOINT = "/api/v1/documents/classify";
+
+    private final CustomPDFDocumentFactory pdfDocumentFactory;
+    private final TempFileManager tempFileManager;
+    private final PdfContentExtractor pdfContentExtractor;
+    private final PdfMetadataService pdfMetadataService;
+    private final AiEngineClient aiEngineClient;
+    private final ObjectMapper objectMapper;
+    private final UserServiceInterface userService;
+
+    /**
+     * Present only when the policy subsystem is enabled ({@code policies.enabled}); the store and
+     * team authority are gated on it. Null otherwise, in which case there are no team labels to
+     * classify against and the document is passed through unlabelled.
+     */
+    private final ClassificationLabelStore labelStore;
+
+    private final PolicyManagementAuthority policyManagementAuthority;
+
+    public ClassifyLabelController(
+            CustomPDFDocumentFactory pdfDocumentFactory,
+            TempFileManager tempFileManager,
+            PdfContentExtractor pdfContentExtractor,
+            PdfMetadataService pdfMetadataService,
+            AiEngineClient aiEngineClient,
+            ObjectMapper objectMapper,
+            @Autowired(required = false) UserServiceInterface userService,
+            @Autowired(required = false) ClassificationLabelStore labelStore,
+            @Autowired(required = false) PolicyManagementAuthority policyManagementAuthority) {
+        this.pdfDocumentFactory = pdfDocumentFactory;
+        this.tempFileManager = tempFileManager;
+        this.pdfContentExtractor = pdfContentExtractor;
+        this.pdfMetadataService = pdfMetadataService;
+        this.aiEngineClient = aiEngineClient;
+        this.objectMapper = objectMapper;
+        this.userService = userService;
+        this.labelStore = labelStore;
+        this.policyManagementAuthority = policyManagementAuthority;
+    }
+
+    @PostMapping(value = "/classify-and-label", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @Operation(
+            summary = "Classify a PDF and label its metadata",
+            description =
+                    "Reads the first two and last two pages, classifies the document via the AI"
+                            + " engine, and stores the result in the StirlingPDFClassification"
+                            + " metadata field. Dispatched by the Classification policy; not"
+                            + " intended for direct client use.")
+    public ResponseEntity<Resource> classifyAndLabel(
+            @RequestParam("fileInput") MultipartFile fileInput) throws IOException {
+        try (PDDocument document = pdfDocumentFactory.load(fileInput, true)) {
+            String fileName = safeFileName(fileInput.getOriginalFilename());
+
+            List<EngineLabel> allowed = resolveAllowedLabels();
+            if (allowed.isEmpty()) {
+                // No vocabulary to classify against (the team stored no labels): pass the file
+                // through unlabelled rather than ask the engine to classify against nothing.
+                log.debug("[classify-and-label] {} has no team labels; skipping", fileName);
+                return WebResponseUtils.pdfDocToWebResponse(document, fileName, tempFileManager);
+            }
+
+            List<AiPageText> pages = extractWindow(document);
+            String requestBody =
+                    objectMapper.writeValueAsString(
+                            new ClassifyEngineRequest(fileName, pages, allowed));
+
+            String userId = userService != null ? userService.getCurrentUsername() : null;
+            String responseJson = aiEngineClient.post(CLASSIFY_ENDPOINT, requestBody, userId);
+
+            pdfMetadataService.setClassificationMetadata(document, toMetadataValue(responseJson));
+            log.debug("[classify-and-label] labelled {} ({} window pages)", fileName, pages.size());
+
+            return WebResponseUtils.pdfDocToWebResponse(document, fileName, tempFileManager);
+        }
+    }
+
+    private List<AiPageText> extractWindow(PDDocument document) throws IOException {
+        List<AiPageText> pages = new ArrayList<>();
+        for (int pageNumber : windowPageNumbers(document.getNumberOfPages(), WINDOW_PAGES)) {
+            String text = pdfContentExtractor.extractPageTextRaw(document, pageNumber);
+            if (text != null && !text.isBlank()) {
+                pages.add(new AiPageText(pageNumber, text));
+            }
+        }
+        return pages;
+    }
+
+    /** First and last {@code window} page numbers (1-based), de-duplicated and in order. */
+    static List<Integer> windowPageNumbers(int pageCount, int window) {
+        Set<Integer> numbers = new LinkedHashSet<>();
+        for (int page = 1; page <= Math.min(window, pageCount); page++) {
+            numbers.add(page);
+        }
+        for (int page = Math.max(1, pageCount - window + 1); page <= pageCount; page++) {
+            numbers.add(page);
+        }
+        return new ArrayList<>(numbers);
+    }
+
+    /** Drop the transport-only {@code outcome} discriminator; keep the rest verbatim. */
+    private String toMetadataValue(String engineResponseJson) {
+        JsonNode node = objectMapper.readTree(engineResponseJson);
+        if (node instanceof ObjectNode object) {
+            object.remove("outcome");
+        }
+        return objectMapper.writeValueAsString(node);
+    }
+
+    private static String safeFileName(String originalFilename) {
+        String name = Filenames.toSimpleFileName(originalFilename);
+        return (name == null || name.isBlank()) ? "classified.pdf" : name;
+    }
+
+    /**
+     * The allowed labels for the caller's team as {@code {id, name}} pairs, de-duplicated by id.
+     * The engine shows the model the names and returns the ids (icons are presentational and never
+     * sent). Returns an empty list — the caller then skips classification — when the policy
+     * subsystem is disabled (no store) or the team has no stored labels. The engine holds no
+     * default vocabulary of its own, so a team's stored labels are the only source.
+     */
+    private List<EngineLabel> resolveAllowedLabels() {
+        if (labelStore == null) {
+            return List.of();
+        }
+        Long teamId =
+                policyManagementAuthority == null
+                        ? null
+                        : policyManagementAuthority.currentUserTeamId();
+
+        Map<String, EngineLabel> byId = new LinkedHashMap<>();
+        labelStore.findByTeam(teamId).ifPresent(labels -> collectLabels(labels.labels(), byId));
+
+        return List.copyOf(byId.values());
+    }
+
+    private static void collectLabels(
+            List<ClassificationLabel> labels, Map<String, EngineLabel> into) {
+        for (ClassificationLabel label : labels) {
+            if (label.id() == null
+                    || label.id().isBlank()
+                    || label.name() == null
+                    || label.name().isBlank()) {
+                continue;
+            }
+            into.putIfAbsent(label.id(), new EngineLabel(label.id(), label.name()));
+        }
+    }
+
+    /** One allowed label sent to the engine: stable id + the name the model reasons over. */
+    private record EngineLabel(String id, String name) {}
+
+    /** Request body for the engine's {@code /api/v1/documents/classify} endpoint. */
+    private record ClassifyEngineRequest(
+            String fileName, List<AiPageText> pages, List<EngineLabel> labels) {}
+}
@@ -4,6 +4,7 @@ import java.time.Instant;
 import java.time.temporal.ChronoUnit;
 import java.util.List;

+import org.springframework.context.annotation.Profile;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -38,6 +39,9 @@ import stirling.software.proprietary.security.database.repository.UserRepository
@PreAuthorize("hasRole('ADMIN')")
@RequiredArgsConstructor
@EnterpriseEndpoint
+// Self-hosted only: counts are server-wide. On SaaS this endpoint is owned by the team-scoped
+// SaasFleetUsageController (@Profile("saas")) so one backend can't leak another tenant's usage.
+@Profile("!saas")
 public class FleetUsageController {

    private final PersistentAuditEventRepository auditRepository;
@@ -5,6 +5,7 @@ import static stirling.software.common.util.ProviderUtils.validateProvider;
 import java.time.Instant;
 import java.time.temporal.ChronoUnit;
 import java.util.*;
+import java.util.stream.Collectors;

 import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.http.ResponseEntity;
@@ -28,13 +29,16 @@ import stirling.software.common.model.ApplicationProperties.Security.OAUTH2.Clie
 import stirling.software.common.model.ApplicationProperties.Security.SAML2;
 import stirling.software.common.model.FileInfo;
 import stirling.software.common.model.enumeration.Role;
+import stirling.software.common.model.enumeration.TeamRole;
 import stirling.software.common.model.oauth2.GitHubProvider;
 import stirling.software.common.model.oauth2.GoogleProvider;
 import stirling.software.common.model.oauth2.KeycloakProvider;
+import stirling.software.proprietary.access.service.ResourceAccessService;
 import stirling.software.proprietary.audit.AuditEventType;
 import stirling.software.proprietary.audit.AuditLevel;
 import stirling.software.proprietary.config.AuditConfigurationProperties;
 import stirling.software.proprietary.model.Team;
+import stirling.software.proprietary.model.TeamMembership;
 import stirling.software.proprietary.model.dto.TeamWithUserCountDTO;
 import stirling.software.proprietary.repository.PersistentAuditEventRepository;
 import stirling.software.proprietary.security.config.EnterpriseEndpoint;
@@ -44,6 +48,7 @@ import stirling.software.proprietary.security.model.Authority;
 import stirling.software.proprietary.security.model.SessionEntity;
 import stirling.software.proprietary.security.model.User;
 import stirling.software.proprietary.security.model.dto.AdminUserSummary;
+import stirling.software.proprietary.security.repository.TeamMembershipRepository;
 import stirling.software.proprietary.security.repository.TeamRepository;
 import stirling.software.proprietary.security.saml2.CustomSaml2AuthenticatedPrincipal;
 import stirling.software.proprietary.security.service.DatabaseServiceInterface;
@@ -65,6 +70,7 @@ public class ProprietaryUIDataController {
    private final SessionPersistentRegistry sessionPersistentRegistry;
    private final UserRepository userRepository;
    private final TeamRepository teamRepository;
+    private final TeamMembershipRepository teamMembershipRepository;
    private final SessionRepository sessionRepository;
    private final DatabaseServiceInterface databaseService;
    private final boolean runningEE;
@@ -73,6 +79,7 @@ public class ProprietaryUIDataController {
    private final PersistentAuditEventRepository auditRepository;
    private final MfaService mfaService;
    private final LoginAttemptService loginAttemptService;
+    private final ResourceAccessService resourceAccessService;

    public ProprietaryUIDataController(
            ApplicationProperties applicationProperties,
@@ -80,6 +87,7 @@ public class ProprietaryUIDataController {
            SessionPersistentRegistry sessionPersistentRegistry,
            UserRepository userRepository,
            TeamRepository teamRepository,
+            TeamMembershipRepository teamMembershipRepository,
            SessionRepository sessionRepository,
            DatabaseServiceInterface databaseService,
            ObjectMapper objectMapper,
@@ -87,12 +95,14 @@ public class ProprietaryUIDataController {
            UserLicenseSettingsService licenseSettingsService,
            PersistentAuditEventRepository auditRepository,
            MfaService mfaService,
-            LoginAttemptService loginAttemptService) {
+            LoginAttemptService loginAttemptService,
+            ResourceAccessService resourceAccessService) {
        this.applicationProperties = applicationProperties;
        this.auditConfig = auditConfig;
        this.sessionPersistentRegistry = sessionPersistentRegistry;
        this.userRepository = userRepository;
        this.teamRepository = teamRepository;
+        this.teamMembershipRepository = teamMembershipRepository;
        this.sessionRepository = sessionRepository;
        this.databaseService = databaseService;
        this.objectMapper = objectMapper;
@@ -101,6 +111,7 @@ public class ProprietaryUIDataController {
        this.auditRepository = auditRepository;
        this.mfaService = mfaService;
        this.loginAttemptService = loginAttemptService;
+        this.resourceAccessService = resourceAccessService;
    }

    /**
@@ -370,8 +381,11 @@ public class ProprietaryUIDataController {
        boolean premiumEnabled = applicationProperties.getPremium().isEnabled();

        // Convert User entities to AdminUserSummary DTOs to exclude sensitive fields
+        Set<Long> leaderUserIds = leaderUserIds();
        List<AdminUserSummary> userSummaries =
-                sortedUsers.stream().map(this::convertUserToSummary).toList();
+                sortedUsers.stream()
+                        .map(user -> convertUserToSummary(user, leaderUserIds))
+                        .toList();

        AdminSettingsData data = new AdminSettingsData();
        data.setUsers(userSummaries);
@@ -390,6 +404,10 @@ public class ProprietaryUIDataController {
        data.setLicenseMaxUsers(licenseMaxUsers);
        data.setPremiumEnabled(premiumEnabled);
        data.setMailEnabled(applicationProperties.getMail().isEnabled());
+        // Email invites need the invites toggle AND SMTP on; matches the inviteUsers precondition.
+        data.setEmailInvitesEnabled(
+                applicationProperties.getMail().isEnableInvites()
+                        && applicationProperties.getMail().isEnabled());
        data.setUserSettings(userSettings);
        data.setLockedUsers(loginAttemptService.getAllBlockedUsers());

@@ -468,9 +486,18 @@ public class ProprietaryUIDataController {
            teamLastRequest.put(teamId, lastActivity);
        }

+        Map<Long, List<String>> teamOwners = new HashMap<>();
+        for (TeamMembership row :
+                teamMembershipRepository.findByRoleFetchingUserAndTeam(TeamRole.LEADER)) {
+            teamOwners
+                    .computeIfAbsent(row.getTeam().getId(), id -> new ArrayList<>())
+                    .add(row.getUser().getUsername());
+        }
+
        TeamsData data = new TeamsData();
        data.setTeamsWithCounts(teamsWithCounts);
        data.setTeamLastRequest(teamLastRequest);
+        data.setTeamOwners(teamOwners);

        return ResponseEntity.ok(data);
    }
@@ -510,11 +537,17 @@ public class ProprietaryUIDataController {
            userLastRequest.put(username, lastRequest);
        }

+        Set<Long> ownerUserIds =
+                teamMembershipRepository.findByTeamIdAndRole(id, TeamRole.LEADER).stream()
+                        .map(row -> row.getUser().getId())
+                        .collect(Collectors.toSet());
+
        TeamDetailsData data = new TeamDetailsData();
        data.setTeam(team);
        data.setTeamUsers(teamUsers);
        data.setAvailableUsers(availableUsers);
        data.setUserLastRequest(userLastRequest);
+        data.setOwnerUserIds(ownerUserIds);

        return ResponseEntity.ok(data);
    }
@@ -535,13 +568,24 @@ public class ProprietaryUIDataController {
        return ResponseEntity.ok(data);
    }

+    /** User ids holding a LEADER membership on any team. */
+    private Set<Long> leaderUserIds() {
+        return teamMembershipRepository.findByRoleFetchingUserAndTeam(TeamRole.LEADER).stream()
+                .map(row -> row.getUser().getId())
+                .collect(Collectors.toSet());
+    }
+
    /**
     * Convert User entity to AdminUserSummary DTO, excluding sensitive fields like password and
     * apiKey.
     */
-    private AdminUserSummary convertUserToSummary(User user) {
+    private AdminUserSummary convertUserToSummary(User user, Set<Long> leaderUserIds) {
        AdminUserSummary summary = new AdminUserSummary();
        summary.setId(user.getId());
+        summary.setTeamLead(leaderUserIds.contains(user.getId()));
+        // Authoritative portal access, same call /me uses, so the roster honors the configured
+        // policy instead of the frontend guessing from role/team-leadership.
+        summary.setPortalAccess(resourceAccessService.canAccessPortal(user));
        summary.setUsername(user.getUsername());
        summary.setEmail(user.getUsername()); // Use username as email for consistency
        summary.setRoleName(user.getRoleName());
@@ -609,6 +653,7 @@ public class ProprietaryUIDataController {
        private int licenseMaxUsers;
        private boolean premiumEnabled;
        private boolean mailEnabled;
+        private boolean emailInvitesEnabled;
        private Map<String, Map<String, String>> userSettings;
        private List<String> lockedUsers;
    }
@@ -629,6 +674,7 @@ public class ProprietaryUIDataController {
    public static class TeamsData {
        private List<TeamWithUserCountDTO> teamsWithCounts;
        private Map<Long, Date> teamLastRequest;
+        private Map<Long, List<String>> teamOwners;
    }

    @Data
@@ -637,6 +683,7 @@ public class ProprietaryUIDataController {
        private List<User> teamUsers;
        private List<User> availableUsers;
        private Map<String, Date> userLastRequest;
+        private Set<Long> ownerUserIds;
    }

    @Data
@@ -29,7 +29,9 @@ import stirling.software.proprietary.security.model.User;
@RestController
@RequestMapping("/api/v1/integrations")
@RequiredArgsConstructor
-@PreAuthorize("isAuthenticated()")
+// Portal-exclusive: server-side portal-access boundary, not just isAuthenticated. Per-config
+// ownership is still enforced in the service layer.
+@PreAuthorize("@resourceAccess.canUsePortal()")
@Tag(name = "Integrations", description = "Manage S3/MCP/API integration configurations")
 public class IntegrationConfigController {

@@ -1,12 +1,16 @@
 package stirling.software.proprietary.integration.crypto;

+import java.io.IOException;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.nio.file.attribute.PosixFilePermission;
+import java.nio.file.attribute.PosixFilePermissions;
 import java.security.GeneralSecurityException;
 import java.security.SecureRandom;
 import java.util.Arrays;
 import java.util.Base64;
+import java.util.EnumSet;

 import javax.crypto.Cipher;
 import javax.crypto.KeyGenerator;
@@ -74,7 +78,7 @@ public class CredentialEncryption {
            generator.init(256);
            SecretKey generated = generator.generateKey();
            Files.createDirectories(path.getParent());
-            Files.writeString(path, Base64.getEncoder().encodeToString(generated.getEncoded()));
+            writeOwnerOnly(path, Base64.getEncoder().encodeToString(generated.getEncoded()));
            log.warn(
                    "Generated a new credential encryption key at {}. Back this file up: losing it"
                            + " makes stored integration secrets unrecoverable.",
@@ -85,6 +89,25 @@ public class CredentialEncryption {
        }
    }

+    // The master key decrypts every stored integration secret, so create it 0600
+    // (owner-only) atomically. On non-POSIX filesystems (Windows) the config-dir
+    // ACL is the protection; we still create the file, just without POSIX perms.
+    private static void writeOwnerOnly(Path path, String content) throws IOException {
+        EnumSet<PosixFilePermission> ownerOnly =
+                EnumSet.of(PosixFilePermission.OWNER_READ, PosixFilePermission.OWNER_WRITE);
+        try {
+            Files.createFile(path, PosixFilePermissions.asFileAttribute(ownerOnly));
+        } catch (UnsupportedOperationException e) {
+            Files.createFile(path);
+        }
+        Files.writeString(path, content);
+        try {
+            Files.setPosixFilePermissions(path, ownerOnly);
+        } catch (UnsupportedOperationException ignored) {
+            // Non-POSIX filesystem: nothing to tighten here.
+        }
+    }
+
    public static String encrypt(String plaintext) {
        if (plaintext == null) {
            return null;
@@ -0,0 +1,31 @@
+package stirling.software.proprietary.integration.crypto;
+
+import jakarta.persistence.AttributeConverter;
+import jakarta.persistence.Converter;
+
+/**
+ * {@link EncryptedStringConverter} for columns that held plaintext before encryption shipped:
+ * writes are always encrypted, but a stored value that is not valid ciphertext is returned as-is,
+ * so pre-encryption rows keep loading and become encrypted on their next save. The discrimination
+ * is exact for JSON payloads, which can never be mistaken for ciphertext ('{' is not in the Base64
+ * alphabet). The trade-off is that a genuinely corrupted ciphertext surfaces as garbage to the
+ * caller's parser instead of failing here.
+ */
+@Converter
+public class LenientEncryptedStringConverter implements AttributeConverter<String, String> {
+
+    @Override
+    public String convertToDatabaseColumn(String attribute) {
+        return CredentialEncryption.encrypt(attribute);
+    }
+
+    @Override
+    public String convertToEntityAttribute(String dbData) {
+        try {
+            return CredentialEncryption.decrypt(dbData);
+        } catch (IllegalArgumentException | IllegalStateException e) {
+            // Not ciphertext: legacy plaintext from before encryption shipped.
+            return dbData;
+        }
+    }
+}
@@ -18,4 +18,13 @@ public interface IntegrationConfigRepository extends JpaRepository<IntegrationCo
    List<IntegrationConfig> findByOwnerTeam(Team ownerTeam);

    List<IntegrationConfig> findByScope(OwnerScope scope);
+
+    // Nested path: OwnedResource has a getOwnerTeamId() convenience getter but no such persistent
+    // attribute, so the plain "...OwnerTeamId" derivation resolves to a phantom property and throws
+    // UnknownPathException. The underscore forces the real ownerTeam.id association path.
+    boolean existsByOwnerTeam_Id(Long teamId);
+
+    void deleteByOwnerUser(User ownerUser);
+
+    void deleteByOwnerTeam_Id(Long teamId);
 }
@@ -16,6 +16,7 @@ import lombok.extern.slf4j.Slf4j;
 import stirling.software.proprietary.access.model.DefaultAccessPolicy;
 import stirling.software.proprietary.access.model.OwnerScope;
 import stirling.software.proprietary.access.model.ResourceType;
+import stirling.software.proprietary.access.repository.ResourceGrantRepository;
 import stirling.software.proprietary.access.service.OwnershipService;
 import stirling.software.proprietary.access.service.SecretMasker;
 import stirling.software.proprietary.integration.dto.IntegrationConfigRequest;
@@ -41,6 +42,11 @@ public class IntegrationConfigService {
    private final IntegrationConfigRepository repository;
    private final OwnershipService ownership;
    private final SecretMasker secretMasker;
+    private final ResourceGrantRepository grantRepository;
+    // Bean-discovered extension points: features that understand a type contribute its config
+    // schema and report what still references a config, without this module depending on them.
+    private final List<IntegrationConfigValidator> validators;
+    private final List<IntegrationConfigUsageCheck> usageChecks;

    // ---- commands ----

@@ -49,6 +55,13 @@ public class IntegrationConfigService {
        OwnerScope scope = request.scope() == null ? OwnerScope.USER : request.scope();
        IntegrationConfig cfg = new IntegrationConfig();
        cfg.setIntegrationType(require(request.integrationType(), "integrationType"));
+        // S3 is infrastructure, not self-serve: no personal S3 for regular users. TEAM/SERVER
+        // scopes are already restricted to admins/team owners by assignOwnership.
+        if (cfg.getIntegrationType() == IntegrationType.S3
+                && scope == OwnerScope.USER
+                && !ownership.isAdmin(currentUser)) {
+            throw forbidden("S3 connections can only be created by administrators or team owners");
+        }
        cfg.setName(require(request.name(), "name"));
        cfg.setEnabled(request.enabled() == null || request.enabled());
        cfg.setLocked(request.locked() != null && request.locked());
@@ -57,13 +70,21 @@ public class IntegrationConfigService {
                        ? DefaultAccessPolicy.EXPLICIT_ONLY
                        : request.defaultAccess());

+        // TEAM scope may omit the team id: default to the caller's own team so clients (the
+        // portal) need not know it. assignOwnership still enforces admin-or-leader of that team.
+        Long ownerTeamId = request.ownerTeamId();
+        if (ownerTeamId == null && scope == OwnerScope.TEAM && currentUser.getTeam() != null) {
+            ownerTeamId = currentUser.getTeam().getId();
+        }
        ownership.assignOwnership(
                cfg,
                scope,
-                request.ownerTeamId(),
+                ownerTeamId,
                currentUser,
                () -> lockedServerExists(cfg.getIntegrationType()));
-        cfg.setConfig(writeJson(secretMasker.sanitize(request.config())));
+        Map<String, Object> config = secretMasker.sanitize(request.config());
+        validateConfig(cfg.getIntegrationType(), config);
+        cfg.setConfig(writeJson(config));
        return repository.save(cfg);
    }

@@ -92,8 +113,10 @@ public class IntegrationConfigService {
            cfg.setDefaultAccess(request.defaultAccess());
        }
        if (request.config() != null) {
-            cfg.setConfig(
-                    writeJson(secretMasker.merge(readJson(cfg.getConfig()), request.config())));
+            Map<String, Object> merged =
+                    secretMasker.merge(readJson(cfg.getConfig()), request.config());
+            validateConfig(cfg.getIntegrationType(), merged);
+            cfg.setConfig(writeJson(merged));
        }
        return repository.save(cfg);
    }
@@ -104,6 +127,17 @@ public class IntegrationConfigService {
        if (!ownership.canManage(TYPE, cfg, currentUser)) {
            throw forbidden("You cannot manage this integration");
        }
+        // Refuse to pull a connection out from under whatever still references it.
+        List<String> usages =
+                usageChecks.stream()
+                        .flatMap(check -> check.usagesOf(cfg.getId()).stream())
+                        .toList();
+        if (!usages.isEmpty()) {
+            throw new ResponseStatusException(
+                    HttpStatus.CONFLICT, "Integration is in use by: " + String.join(", ", usages));
+        }
+        // Drop grants sharing this config so they do not dangle as dead rows.
+        grantRepository.deleteByResourceTypeAndResourceId(TYPE, String.valueOf(cfg.getId()));
        repository.delete(cfg);
    }

@@ -177,6 +211,19 @@ public class IntegrationConfigService {

    // ---- integration-specific glue ----

+    /** Runs every registered validator for the type; unknown types save free-form. */
+    private void validateConfig(IntegrationType type, Map<String, Object> config) {
+        for (IntegrationConfigValidator validator : validators) {
+            if (validator.type() == type) {
+                try {
+                    validator.validate(config == null ? Map.of() : config);
+                } catch (IllegalArgumentException e) {
+                    throw new ResponseStatusException(HttpStatus.BAD_REQUEST, e.getMessage());
+                }
+            }
+        }
+    }
+
    /** A non-admin can't create a personal config of a type an admin has locked at server scope. */
    private boolean lockedServerExists(IntegrationType type) {
        return repository.findByScope(OwnerScope.SERVER).stream()
@@ -0,0 +1,15 @@
+package stirling.software.proprietary.integration.service;
+
+import java.util.List;
+
+/**
+ * Reports what still references an integration config, so deletion can be refused instead of
+ * pulling a connection out from under a live consumer. Implementations are beans discovered by
+ * {@link IntegrationConfigService} (e.g. the policy subsystem reporting sources and pipelines that
+ * reference a connection).
+ */
+public interface IntegrationConfigUsageCheck {
+
+    /** Human-readable labels of everything still using the config; empty when unreferenced. */
+    List<String> usagesOf(long configId);
+}
@@ -0,0 +1,23 @@
+package stirling.software.proprietary.integration.service;
+
+import java.util.Map;
+
+import stirling.software.proprietary.integration.model.IntegrationType;
+
+/**
+ * Validates one integration type's config map at save time. Implementations are beans discovered by
+ * {@link IntegrationConfigService}, so the feature that understands a type (e.g. the policy S3
+ * backend) owns its schema without the integration module depending on it. Types with no registered
+ * validator save free-form.
+ */
+public interface IntegrationConfigValidator {
+
+    /** The type this validator understands. */
+    IntegrationType type();
+
+    /**
+     * Validates the config as it will be stored (secrets already sanitized/merged, so values are
+     * real, never the redaction mask). Throws {@link IllegalArgumentException} on bad config.
+     */
+    void validate(Map<String, Object> config);
+}
@@ -1,4 +1,4 @@
-package stirling.software.saas.model;
+package stirling.software.proprietary.model;

 import java.io.Serializable;
 import java.time.LocalDateTime;
@@ -15,7 +15,6 @@ import lombok.Setter;
 import lombok.ToString;

 import stirling.software.common.model.enumeration.TeamRole;
-import stirling.software.proprietary.model.Team;
 import stirling.software.proprietary.security.model.User;

 /**
@@ -21,4 +21,11 @@ public class AiWorkflowResultFile {

    @Schema(description = "MIME type of the file", example = "application/pdf")
    private String contentType;
+
+    @Schema(
+            description =
+                    "Index into the request's fileInputs that this output was derived from, or null"
+                            + " when it has no single source (e.g. a merge, or a generated file)."
+                            + " Lets the client replace that input in place as a new version.")
+    private Integer sourceIndex;
 }
@@ -17,6 +17,9 @@ public class InfraAuditSummary {
    @Schema(description = "Total events in the returned window", example = "40")
    private int totalEvents;

+    @Schema(description = "Policy-run events", example = "3")
+    private int policy;
+
    @Schema(description = "Processing-category events", example = "24")
    private int processing;

@@ -18,10 +18,13 @@ import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.ModelAttribute;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestPart;
 import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.context.request.RequestContextHolder;
+import org.springframework.web.context.request.ServletRequestAttributes;
 import org.springframework.web.multipart.MultipartFile;
 import org.springframework.web.server.ResponseStatusException;
 import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
@@ -31,6 +34,7 @@ import io.swagger.v3.oas.annotations.Hidden;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;

+import jakarta.servlet.http.HttpServletRequest;
 import jakarta.validation.Valid;

 import lombok.RequiredArgsConstructor;
@@ -41,13 +45,18 @@ import stirling.software.common.model.job.JobResponse;
 import stirling.software.common.service.JobOwnershipService;
 import stirling.software.common.util.TempFile;
 import stirling.software.common.util.TempFileManager;
+import stirling.software.proprietary.audit.AuditContext;
 import stirling.software.proprietary.policy.config.PolicyAccessGuard;
 import stirling.software.proprietary.policy.config.PolicyManagementAuthority;
 import stirling.software.proprietary.policy.engine.PolicyRunHandle;
 import stirling.software.proprietary.policy.engine.PolicyRunRegistry;
 import stirling.software.proprietary.policy.engine.PolicyRunner;
 import stirling.software.proprietary.policy.engine.PolicyValidator;
+import stirling.software.proprietary.policy.engine.SweepOutcome;
+import stirling.software.proprietary.policy.ledger.ProcessedLedger;
+import stirling.software.proprietary.policy.model.OutputSpec;
 import stirling.software.proprietary.policy.model.PipelineDefinition;
+import stirling.software.proprietary.policy.model.PipelineStep;
 import stirling.software.proprietary.policy.model.Policy;
 import stirling.software.proprietary.policy.model.PolicyInputs;
 import stirling.software.proprietary.policy.model.PolicyRun;
@@ -56,12 +65,15 @@ import stirling.software.proprietary.policy.model.PolicyRunView;
 import stirling.software.proprietary.policy.overview.PoliciesOverviewResponse;
 import stirling.software.proprietary.policy.overview.PolicyOverviewService;
 import stirling.software.proprietary.policy.progress.PolicyProgressListener;
+import stirling.software.proprietary.policy.source.EditorSource;
 import stirling.software.proprietary.policy.source.SourceAccessGuard;
+import stirling.software.proprietary.policy.source.SourceDocCounter;
 import stirling.software.proprietary.policy.source.SourceStore;
 import stirling.software.proprietary.policy.store.PolicyStore;
 import stirling.software.proprietary.policy.trigger.PolicyTrigger;
 import stirling.software.proprietary.policy.trigger.PolicyTriggerManager;
 import stirling.software.proprietary.policy.trigger.TriggerInfo;
+import stirling.software.proprietary.util.SecretMasker;

 /**
 * Policy CRUD plus pipeline runs (stored or ad-hoc). Runs are async: returns a run id, poll {@code
@@ -81,11 +93,13 @@ public class PolicyController {
    private final PolicyStore policyStore;
    private final SourceStore sourceStore;
    private final SourceAccessGuard sourceAccessGuard;
+    private final SourceDocCounter docCounter;
    private final PolicyValidator policyValidator;
    private final PolicyAccessGuard policyAccessGuard;
    private final PolicyManagementAuthority policyManagementAuthority;
    private final PolicyTriggerManager policyTriggerManager;
    private final PolicyOverviewService policyOverviewService;
+    private final ProcessedLedger processedLedger;
    private final List<PolicyTrigger> policyTriggers;
    private final ApplicationProperties applicationProperties;
    private final TempFileManager tempFileManager;
@@ -104,11 +118,14 @@ public class PolicyController {
            @RequestPart("json") PipelineDefinition definition,
            @Valid @ModelAttribute PolicyRunFiles files)
            throws IOException {
+        stampPolicyAudit(definition);
        requireRunnable(definition);
+        validateAdHocOutput(definition);
        PolicyInputs inputs = toInputs(files);
-        String runId =
-                policyRunner.runAdHoc(definition, inputs, PolicyProgressListener.NOOP).runId();
-        return ResponseEntity.accepted().body(new JobResponse<>(true, runId, null));
+        PolicyRunHandle handle =
+                policyRunner.runAdHoc(definition, inputs, PolicyProgressListener.NOOP);
+        recordEditorDocs(inputs);
+        return ResponseEntity.accepted().body(new JobResponse<>(true, handle.runId(), null));
    }

    @PostMapping(value = "/run/stream", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
@@ -122,7 +139,9 @@ public class PolicyController {
            @RequestPart("json") PipelineDefinition definition,
            @Valid @ModelAttribute PolicyRunFiles files)
            throws IOException {
+        stampPolicyAudit(definition);
        requireRunnable(definition);
+        validateAdHocOutput(definition);
        PolicyInputs inputs = toInputs(files);

        SseEmitter emitter =
@@ -130,6 +149,7 @@ public class PolicyController {
        emitter.onError(e -> log.warn("Policy run SSE emitter error", e));

        PolicyRunHandle handle = policyRunner.runAdHoc(definition, inputs, streamListener(emitter));
+        recordEditorDocs(inputs);
        // whenComplete runs on the worker thread after the run finishes, so the terminal event
        // never races the step events.
        handle.completion()
@@ -199,7 +219,7 @@ public class PolicyController {
                            + " assigned; returns the stored policy with its id.")
    public ResponseEntity<Policy> savePolicy(@RequestBody Policy policy) {
        requirePolicyEditingAllowed();
-        Policy owned = resolveOwnership(policy);
+        Policy owned = withStoredOutputSecrets(resolveOwnership(policy));
        requireAccessibleSources(owned);
        try {
            policyValidator.validate(owned);
@@ -210,7 +230,21 @@ public class PolicyController {
        // Re-sync trigger registrations now so a new/changed folder-watch policy starts being
        // watched immediately instead of after the next reconcile sweep.
        policyTriggerManager.notifyPoliciesChanged();
-        return ResponseEntity.ok(saved);
+        return ResponseEntity.ok(withMaskedOutputSecrets(saved));
+    }
+
+    @PutMapping("/order")
+    @Operation(
+            summary = "Set the team's policy run order",
+            description =
+                    "Persists the team-wide order policies run in, from the given ordered list of"
+                            + " policy ids (position → order). The per-trigger order shown in the UI"
+                            + " is this one sequence filtered by trigger. Team-leader/admin only;"
+                            + " ids outside the caller's team are ignored.")
+    public ResponseEntity<Void> reorderPolicies(@RequestBody List<String> orderedPolicyIds) {
+        requirePolicyEditingAllowed();
+        policyStore.reorder(policyAccessGuard.teamForNewPolicy(), orderedPolicyIds);
+        return ResponseEntity.noContent().build();
    }

    /**
@@ -265,6 +299,50 @@ public class PolicyController {
                teamId);
    }

+    /** Output secrets never leave the server: reads return the redaction sentinel instead. */
+    private static Policy withMaskedOutputSecrets(Policy policy) {
+        return withOutput(
+                policy,
+                new OutputSpec(
+                        policy.output().type(), SecretMasker.mask(policy.output().options())));
+    }
+
+    /**
+     * An edit that round-trips a masked read sends output secrets back as the sentinel; restore
+     * them from the stored policy so saving without re-typing keeps them (validation then runs
+     * against the real values).
+     */
+    private Policy withStoredOutputSecrets(Policy incoming) {
+        if (incoming.id() == null || incoming.id().isBlank()) {
+            return incoming;
+        }
+        return policyStore
+                .get(incoming.id())
+                .map(
+                        existing ->
+                                withOutput(
+                                        incoming,
+                                        new OutputSpec(
+                                                incoming.output().type(),
+                                                SecretMasker.restoreRedacted(
+                                                        incoming.output().options(),
+                                                        existing.output().options()))))
+                .orElse(incoming);
+    }
+
+    private static Policy withOutput(Policy policy, OutputSpec output) {
+        return new Policy(
+                policy.id(),
+                policy.name(),
+                policy.owner(),
+                policy.enabled(),
+                policy.trigger(),
+                policy.sourceIds(),
+                policy.steps(),
+                output,
+                policy.teamId());
+    }
+
    /**
     * Creating, editing, pausing/resuming, and deleting policies requires the editor role for the
     * caller's team — a team leader on SaaS (see {@link PolicyManagementAuthority}); the global
@@ -289,9 +367,14 @@ public class PolicyController {
    @GetMapping
    @Operation(
            summary = "List policies",
-            description = "Lists the policies belonging to the caller's team.")
+            description =
+                    "Lists the policies belonging to the caller's team. Secret-bearing output"
+                            + " options are returned as a redaction sentinel, never their stored"
+                            + " values.")
    public List<Policy> listPolicies() {
-        return policyAccessGuard.visibleFrom(policyStore);
+        return policyAccessGuard.visibleFrom(policyStore).stream()
+                .map(PolicyController::withMaskedOutputSecrets)
+                .toList();
    }

    @GetMapping("/overview")
@@ -320,11 +403,17 @@ public class PolicyController {
    }

    @GetMapping("/{policyId}")
-    @Operation(summary = "Get a policy by id")
+    @Operation(
+            summary = "Get a policy by id",
+            description =
+                    "Secret-bearing output options are returned as a redaction sentinel, never"
+                            + " their stored values; an edit that sends the sentinel back keeps"
+                            + " them.")
    public ResponseEntity<Policy> getPolicy(@PathVariable String policyId) {
        return policyStore
                .get(policyId)
                .filter(policyAccessGuard::canAccess)
+                .map(PolicyController::withMaskedOutputSecrets)
                .map(ResponseEntity::ok)
                .orElseGet(() -> ResponseEntity.notFound().build());
    }
@@ -337,6 +426,7 @@ public class PolicyController {
        boolean accessible =
                policyStore.get(policyId).filter(policyAccessGuard::canAccess).isPresent();
        if (accessible && policyStore.delete(policyId)) {
+            processedLedger.clearPolicy(policyId);
            // Cancel any now-orphaned folder watch promptly rather than leaving the WatchKey open
            // until the next reconcile sweep.
            policyTriggerManager.notifyPoliciesChanged();
@@ -345,6 +435,25 @@ public class PolicyController {
        return ResponseEntity.notFound().build();
    }

+    @DeleteMapping("/{policyId}/processed-history")
+    @Operation(
+            summary = "Clear a policy's processed-file history",
+            description =
+                    "Forgets which source files this policy has already processed, so its next"
+                            + " sweep reprocesses everything currently in its sources. Does not"
+                            + " touch the files themselves.")
+    public ResponseEntity<Void> clearProcessedHistory(@PathVariable String policyId) {
+        requirePolicyEditingAllowed();
+        // Scope to the caller's team: a policy in another team reads as not-found.
+        boolean accessible =
+                policyStore.get(policyId).filter(policyAccessGuard::canAccess).isPresent();
+        if (!accessible) {
+            return ResponseEntity.notFound().build();
+        }
+        processedLedger.clearPolicy(policyId);
+        return ResponseEntity.noContent().build();
+    }
+
    @PostMapping(value = "/{policyId}/run", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    @Operation(
            summary = "Run a stored policy",
@@ -364,6 +473,7 @@ public class PolicyController {
                                () ->
                                        new ResponseStatusException(
                                                HttpStatus.NOT_FOUND, "No policy: " + policyId));
+        stampPolicyAudit(policy.toDefinition());
        PolicyInputs inputs = toInputs(files);
        String runId = policyRunner.runWith(policy, inputs, PolicyProgressListener.NOOP).runId();
        return ResponseEntity.accepted().body(new JobResponse<>(true, runId, null));
@@ -375,9 +485,10 @@ public class PolicyController {
            description =
                    "Pulls the policy's configured sources and runs the pipeline now, regardless of"
                            + " the enabled flag (which only gates automatic triggering). Returns"
-                            + " the ids of the runs started; poll the run-status endpoint for each."
-                            + " Empty when the sources yielded no work to do.")
-    public ResponseEntity<List<String>> trigger(@PathVariable String policyId) {
+                            + " the ids of the runs started (poll the run-status endpoint for each)"
+                            + " plus what the sweep skipped - already-processed, parked-by-failure,"
+                            + " and in-flight counts - so an empty result explains itself.")
+    public ResponseEntity<SweepOutcome> trigger(@PathVariable String policyId) {
        Policy policy =
                policyStore
                        .get(policyId)
@@ -396,6 +507,60 @@ public class PolicyController {
        }
    }

+    /**
+     * Stamp this run's policy name and step endpoints onto the current request so the audit aspect
+     * can label the event as the policy it ran (rather than the generic {@code /run} endpoint) and
+     * record which tools it executed. No-op outside a web request.
+     */
+    private static void stampPolicyAudit(PipelineDefinition definition) {
+        if (definition == null
+                || !(RequestContextHolder.getRequestAttributes()
+                        instanceof ServletRequestAttributes attrs)) {
+            return;
+        }
+        HttpServletRequest request = attrs.getRequest();
+        if (definition.name() != null && !definition.name().isBlank()) {
+            request.setAttribute(AuditContext.REQ_ATTR_POLICY_NAME, definition.name());
+        }
+        List<String> steps =
+                definition.steps().stream()
+                        .map(PipelineStep::operation)
+                        .filter(op -> op != null && !op.isBlank())
+                        .toList();
+        if (!steps.isEmpty()) {
+            request.setAttribute(AuditContext.REQ_ATTR_POLICY_STEPS, steps);
+        }
+    }
+
+    /**
+     * Authorization-check an ad-hoc run's output while the caller's principal is present (this
+     * request thread). The worker thread that later delivers carries no security context, so an S3
+     * output's connection-access check would be skipped there; without this gate a caller could
+     * reference another tenant's connection by id and write to it (confused deputy). Stored
+     * policies are covered by save-time {@link PolicyValidator#validate} instead.
+     */
+    private void validateAdHocOutput(PipelineDefinition definition) {
+        if (definition.output() == null) {
+            return;
+        }
+        try {
+            policyValidator.validateOutput(definition.output());
+        } catch (IllegalArgumentException e) {
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, e.getMessage());
+        }
+    }
+
+    /**
+     * Ad-hoc runs (AI / one-off pipelines) are still editor activity, so their supplied documents
+     * feed the same virtual editor source as stored editor policies, counted against the caller's
+     * team. A run with no primary documents (generator pipeline) records nothing.
+     */
+    private void recordEditorDocs(PolicyInputs inputs) {
+        docCounter.record(
+                EditorSource.counterKey(sourceAccessGuard.currentTeamId()),
+                inputs.primary().size());
+    }
+
    /**
     * Turn the typed run files into engine {@link PolicyInputs}: the primary documents plus the
     * named supporting-file store, where each asset's {@code key} is the name a step references
@@ -21,7 +21,9 @@ import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;

 import stirling.software.common.model.job.ResultFile;
+import stirling.software.common.service.AutomationRunContext;
 import stirling.software.common.service.FileStorage;
+import stirling.software.common.service.InternalApiClient;
 import stirling.software.common.service.InternalApiTimeoutException;
 import stirling.software.common.service.JobOwnershipService;
 import stirling.software.common.service.JobQueue;
@@ -35,6 +37,7 @@ import stirling.software.proprietary.policy.model.Policy;
 import stirling.software.proprietary.policy.model.PolicyInputs;
 import stirling.software.proprietary.policy.model.PolicyRun;
 import stirling.software.proprietary.policy.model.WaitState;
+import stirling.software.proprietary.policy.output.OutputDelivery;
 import stirling.software.proprietary.policy.output.PolicyOutputSink;
 import stirling.software.proprietary.policy.progress.PolicyProgressListener;
 import stirling.software.proprietary.service.DownstreamEntitlementError;
@@ -147,6 +150,7 @@ public class PolicyEngine {
                        runAsPrincipal(
                                billingPrincipal,
                                fileOwner,
+                                definition.name(),
                                () -> runToCompletion(run, inputs, tracking, completion));

        // One admission unit per run; steps run synchronously within it, so this gates heavy work
@@ -198,58 +202,78 @@ public class PolicyEngine {
            PolicyProgressListener listener,
            CompletableFuture<PolicyRun> completion) {
        String runId = run.getRunId();
-        try {
-            run.markRunning();
-            PolicyExecutionResult result =
-                    stepExecutor.execute(run.getDefinition(), inputs, listener);
-            OutputSpec output = run.getDefinition().output();
-            List<ResultFile> outputs = sinkFor(output).deliver(runId, result.files(), output);
-            taskManager.setMultipleFileResults(runId, outputs);
-            taskManager.setComplete(runId);
-            run.complete(outputs);
-        } catch (PolicyInputRequiredException e) {
-            // Expected path: suspend rather than fail. Persist intermediates as fileIds so the run
-            // can resume after this worker thread is gone.
-            WaitState wait = suspend(e);
-            run.waitForInput(wait);
-            taskManager.addNote(runId, "Waiting for input: " + e.getMessage());
-        } catch (InternalApiTimeoutException e) {
-            String message = toolTimeoutMessage(e);
-            log.error(
-                    "Policy run {} timed out on {}: {}",
-                    runId,
-                    e.getEndpointPath(),
-                    e.getMessage());
-            run.fail(message);
-            taskManager.setError(runId, message);
-        } catch (RestClientResponseException e) {
-            // A downstream tool call returned an error status. When it's a structured entitlement
-            // response (401/402 with a JSON `error` sentinel), surface that code onto the run so
-            // the
-            // client can react — e.g. pop the usage-limit modal — instead of only seeing a generic
-            // failure. We don't interpret the code here (that would couple this module to the saas
-            // billing layer); we just pass it through for the client to map. Other statuses fall
-            // through to the generic failure below.
-            String code = DownstreamEntitlementError.extractCode(e);
-            if (code != null) {
-                log.info("Policy run {} blocked by downstream entitlement gate ({})", runId, code);
-                String message = "Usage limit reached";
-                run.failWithCode(message, code, DownstreamEntitlementError.extractSubscribed(e));
-                taskManager.setError(runId, message);
-            } else {
-                String message = "Policy run failed: " + e.getMessage();
-                log.error("Policy run {} failed (downstream HTTP error)", runId, e);
+        // One policy run = one automation run. Scope the run id on this worker thread (the async
+        // hop already happened) so every tool sub-step dispatched via InternalApiClient groups into
+        // a single charge, and two separate policy runs on the same document stay distinct charges.
+        try (AutomationRunContext.Scope runScope = AutomationRunContext.open(runId)) {
+            try {
+                run.markRunning();
+                PolicyExecutionResult result =
+                        stepExecutor.execute(run.getDefinition(), inputs, listener);
+                OutputSpec output = run.getDefinition().output();
+                List<ResultFile> outputs =
+                        sinkFor(output)
+                                .deliver(
+                                        new OutputDelivery(runId, run.getPolicyId()),
+                                        result.files(),
+                                        output);
+                taskManager.setMultipleFileResults(runId, outputs);
+                taskManager.setComplete(runId);
+                run.complete(outputs);
+            } catch (PolicyInputRequiredException e) {
+                // Expected path: suspend rather than fail. Persist intermediates as fileIds so the
+                // run
+                // can resume after this worker thread is gone.
+                WaitState wait = suspend(e);
+                run.waitForInput(wait);
+                taskManager.addNote(runId, "Waiting for input: " + e.getMessage());
+            } catch (InternalApiTimeoutException e) {
+                String message = toolTimeoutMessage(e);
+                log.error(
+                        "Policy run {} timed out on {}: {}",
+                        runId,
+                        e.getEndpointPath(),
+                        e.getMessage());
                run.fail(message);
                taskManager.setError(runId, message);
+            } catch (RestClientResponseException e) {
+                // A downstream tool call returned an error status. When it's a structured
+                // entitlement
+                // response (401/402 with a JSON `error` sentinel), surface that code onto the run
+                // so
+                // the
+                // client can react — e.g. pop the usage-limit modal — instead of only seeing a
+                // generic
+                // failure. We don't interpret the code here (that would couple this module to the
+                // saas
+                // billing layer); we just pass it through for the client to map. Other statuses
+                // fall
+                // through to the generic failure below.
+                String code = DownstreamEntitlementError.extractCode(e);
+                if (code != null) {
+                    log.info(
+                            "Policy run {} blocked by downstream entitlement gate ({})",
+                            runId,
+                            code);
+                    String message = "Usage limit reached";
+                    run.failWithCode(
+                            message, code, DownstreamEntitlementError.extractSubscribed(e));
+                    taskManager.setError(runId, message);
+                } else {
+                    String message = "Policy run failed: " + e.getMessage();
+                    log.error("Policy run {} failed (downstream HTTP error)", runId, e);
+                    run.fail(message);
+                    taskManager.setError(runId, message);
+                }
+            } catch (Exception e) {
+                String message = "Policy run failed: " + e.getMessage();
+                log.error("Policy run {} failed", runId, e);
+                run.fail(message);
+                taskManager.setError(runId, message);
+            } finally {
+                // Always resolve so stream/await callers unblock.
+                completion.complete(run);
            }
-        } catch (Exception e) {
-            String message = "Policy run failed: " + e.getMessage();
-            log.error("Policy run {} failed", runId, e);
-            run.fail(message);
-            taskManager.setError(runId, message);
-        } finally {
-            // Always resolve so stream/await callers unblock.
-            completion.complete(run);
        }
    }

@@ -355,18 +379,26 @@ public class PolicyEngine {
     * dispatch attributes (and charges) usage to that user. A null/blank principal runs as-is.
     * Restores the previous MDC value afterward (defensive — worker threads aren't pooled).
     */
-    private static void runAsPrincipal(String billingPrincipal, String fileOwner, Runnable body) {
+    private static void runAsPrincipal(
+            String billingPrincipal, String fileOwner, String policyName, Runnable body) {
        // Billing identity (MDC auditPrincipal) and output-file ownership (JobContext owner) are
        // set
        // independently: usage is charged to billingPrincipal, but stored output files are owned by
        // fileOwner — the user who triggered an org-wide policy — so they can fetch their results.
        // Either may be null (e.g. login disabled, or a trigger-fired run); each is applied only
-        // when present and restored afterward (defensive — worker threads aren't pooled).
+        // when present and restored afterward (defensive — worker threads aren't pooled). The
+        // policy
+        // name rides MDC too so each tool step's loopback dispatch (InternalApiClient) can forward
+        // it as a header, letting the audit tie the step back to its policy.
        String previousPrincipal = MDC.get(AUDIT_PRINCIPAL_MDC_KEY);
+        String previousPolicyName = MDC.get(InternalApiClient.POLICY_NAME_MDC_KEY);
        String previousOwner = JobContext.getOwner();
        if (billingPrincipal != null && !billingPrincipal.isBlank()) {
            MDC.put(AUDIT_PRINCIPAL_MDC_KEY, billingPrincipal);
        }
+        if (policyName != null && !policyName.isBlank()) {
+            MDC.put(InternalApiClient.POLICY_NAME_MDC_KEY, policyName);
+        }
        if (fileOwner != null && !fileOwner.isBlank()) {
            JobContext.setOwner(fileOwner);
        }
@@ -378,6 +410,11 @@ public class PolicyEngine {
            } else {
                MDC.remove(AUDIT_PRINCIPAL_MDC_KEY);
            }
+            if (previousPolicyName != null) {
+                MDC.put(InternalApiClient.POLICY_NAME_MDC_KEY, previousPolicyName);
+            } else {
+                MDC.remove(InternalApiClient.POLICY_NAME_MDC_KEY);
+            }
            JobContext.setOwner(previousOwner);
        }
    }
@@ -8,7 +8,11 @@ import tools.jackson.databind.JsonNode;

 /**
 * Result of a {@link PolicyExecutor} run. {@code files} are final temp files (not yet stored).
- * {@code report}/{@code reportTool} carry the last step's structured report and its operation, or
- * null if no step produced one.
+ * {@code origins} is parallel to {@code files}: each entry is the index into the original pipeline
+ * inputs that the output traces back to, or {@code null} when it has no single source (e.g. a merge
+ * combining several inputs, or a generated file). Callers use it to map an output back onto the
+ * file it came from. {@code report}/{@code reportTool} carry the last step's structured report and
+ * its operation, or null if no step produced one.
 */
-public record PolicyExecutionResult(List<Resource> files, JsonNode report, String reportTool) {}
+public record PolicyExecutionResult(
+        List<Resource> files, List<Integer> origins, JsonNode report, String reportTool) {}
@@ -58,6 +58,11 @@ public class PolicyExecutor {
    // payload the tool surfaced alongside or instead of a file.
    private record ToolResult(List<Resource> files, JsonNode report) {}

+    // A step's output files paired with each file's origin (the index into the original pipeline
+    // inputs it traces back to, or null when it has no single source). Origins compose across steps
+    // so the final result can be mapped back onto the files that entered the pipeline.
+    private record StepOutput(List<Resource> files, List<Integer> origins, JsonNode report) {}
+
    /**
     * Run every step in order, feeding each step's output into the next. Supporting files in {@code
     * inputs} bind to named file fields and never enter the document stream.
@@ -75,6 +80,12 @@ public class PolicyExecutor {

        List<Resource> currentFiles = inputs.primary();
        Map<String, List<Resource>> supportingFiles = inputs.supportingFiles();
+        // Seed each input with its own index as origin; steps carry these through so the final
+        // outputs can be traced back to the files that entered the pipeline.
+        List<Integer> currentOrigins = new ArrayList<>();
+        for (int k = 0; k < currentFiles.size(); k++) {
+            currentOrigins.add(k);
+        }
        // Last non-null report wins: the terminal step defines the output.
        JsonNode lastReport = null;
        String lastReportTool = null;
@@ -87,8 +98,10 @@ public class PolicyExecutor {
                        "Pipeline step " + (i + 1) + " has no operation");
            }
            listener.onStepStart(i + 1, steps.size(), operation);
-            ToolResult stepResult = executeStep(step, currentFiles, supportingFiles);
+            StepOutput stepResult =
+                    executeStep(step, currentFiles, currentOrigins, supportingFiles);
            currentFiles = stepResult.files();
+            currentOrigins = stepResult.origins();
            if (stepResult.report() != null) {
                lastReport = stepResult.report();
                lastReportTool = operation;
@@ -96,7 +109,7 @@ public class PolicyExecutor {
            listener.onStepComplete(i + 1, steps.size(), operation);
        }

-        return new PolicyExecutionResult(currentFiles, lastReport, lastReportTool);
+        return new PolicyExecutionResult(currentFiles, currentOrigins, lastReport, lastReportTool);
    }

    /**
@@ -104,32 +117,50 @@ public class PolicyExecutor {
     * responses are unpacked so each inner file is its own result (e.g. split). For per-file
     * dispatch the first non-null report wins.
     */
-    private ToolResult executeStep(
+    private StepOutput executeStep(
            PipelineStep step,
            List<Resource> inputFiles,
+            List<Integer> inputOrigins,
            Map<String, List<Resource>> supportingFiles)
            throws IOException {
        requireAcceptedTypes(step.operation(), inputFiles);
        List<Resource> files = new ArrayList<>();
+        List<Integer> origins = new ArrayList<>();
        JsonNode report = null;
        if (toolMetadataService.isMultiInput(step.operation())) {
+            // One call over all inputs. The outputs derive from a single input only when exactly
+            // one entered; otherwise (a genuine merge) there is no single source.
            ToolResult r = callEndpoint(step, inputFiles, supportingFiles);
-            files.addAll(r.files());
+            Integer origin = inputOrigins.size() == 1 ? inputOrigins.get(0) : null;
+            for (Resource file : r.files()) {
+                files.add(file);
+                origins.add(origin);
+            }
            report = r.report();
        } else if (inputFiles.isEmpty()) {
            ToolResult r = callEndpoint(step, List.of(), supportingFiles);
-            files.addAll(r.files());
+            for (Resource file : r.files()) {
+                files.add(file);
+                origins.add(null);
+            }
            report = r.report();
        } else {
-            for (Resource file : inputFiles) {
-                ToolResult r = callEndpoint(step, List.of(file), supportingFiles);
-                files.addAll(r.files());
+            // One call per file: every output of this call inherits that input's origin, so a 1:1
+            // op keeps its chain and a split (one input, many outputs) tags each output with the
+            // same source.
+            for (int k = 0; k < inputFiles.size(); k++) {
+                Integer origin = inputOrigins.get(k);
+                ToolResult r = callEndpoint(step, List.of(inputFiles.get(k)), supportingFiles);
+                for (Resource file : r.files()) {
+                    files.add(file);
+                    origins.add(origin);
+                }
                if (report == null) {
                    report = r.report();
                }
            }
        }
-        return new ToolResult(files, report);
+        return new StepOutput(files, origins, report);
    }

    /**
@@ -13,6 +13,7 @@ import lombok.extern.slf4j.Slf4j;

 import stirling.software.proprietary.policy.input.InputSource;
 import stirling.software.proprietary.policy.input.ResolvedInput;
+import stirling.software.proprietary.policy.ledger.ProcessedLedger;
 import stirling.software.proprietary.policy.model.InputSpec;
 import stirling.software.proprietary.policy.model.PipelineDefinition;
 import stirling.software.proprietary.policy.model.Policy;
@@ -20,6 +21,7 @@ import stirling.software.proprietary.policy.model.PolicyInputs;
 import stirling.software.proprietary.policy.model.PolicyRun;
 import stirling.software.proprietary.policy.model.PolicyRunStatus;
 import stirling.software.proprietary.policy.progress.PolicyProgressListener;
+import stirling.software.proprietary.policy.source.EditorSource;
 import stirling.software.proprietary.policy.source.Source;
 import stirling.software.proprietary.policy.source.SourceDocCounter;
 import stirling.software.proprietary.policy.source.SourceStore;
@@ -27,7 +29,8 @@ import stirling.software.proprietary.policy.source.SourceStore;
 /**
 * Turns a policy's referenced sources into runs: each {@code sourceId} is resolved live to its
 * persisted {@link Source}, then to an {@link InputSpec}. Triggers decide <em>when</em> and call
- * {@link #run(Policy)}; the controller uses the supplied-input and ad-hoc entry points.
+ * {@link #run(Policy)}; the controller uses the supplied-input and ad-hoc entry points. A {@link
+ * SweepKind#FULL} sweep also reconciles the processed-file ledger against what is present.
 */
@Slf4j
@Service
@@ -39,23 +42,35 @@ public class PolicyRunner {
    private final List<InputSource> inputSources;
    private final SourceStore sourceStore;
    private final SourceDocCounter docCounter;
+    private final ProcessedLedger processedLedger;
+
+    /** Full-listing sweep: resolve every source, then reconcile the ledger. */
+    public SweepOutcome run(Policy policy) {
+        return run(policy, SweepKind.FULL);
+    }

    /**
     * Trigger entry point. Pulls every referenced source; each yielded unit becomes its own run so
     * one failure does not affect the others. No sources means one run with no input (generator
     * pipeline). Missing or disabled sources are skipped so one broken reference does not stop the
-     * rest. Returns the ids of the runs it started (empty when sources yielded no work), so a
-     * manual trigger can report back which runs to follow.
+     * rest. Returns the ids of the runs it started plus what the sweep skipped, so a manual trigger
+     * can report which runs to follow or why nothing ran.
     */
-    public List<String> run(Policy policy) {
+    public SweepOutcome run(Policy policy, SweepKind sweep) {
+        long sweepStart = System.currentTimeMillis();
+        PolicySweep context = new PolicySweep(policy.id(), sweep, processedLedger);
+        List<String> runIds = new ArrayList<>();
        List<String> sourceIds = policy.sourceIds();
        if (sourceIds.isEmpty()) {
-            return List.of(startRun(policy, PolicyInputs.of(List.of()), unused -> {}));
+            // Generator pipeline: one run with no input. Still fall through to the cleanup
+            // below so rows recorded for its folder outputs are pruned like anything else,
+            // instead of accumulating until the policy is deleted.
+            runIds.add(startRun(policy, PolicyInputs.of(List.of()), unused -> {}));
        }
-        List<String> runIds = new ArrayList<>();
        for (String sourceId : sourceIds) {
            Source source = sourceStore.get(sourceId).orElse(null);
            if (source == null) {
+                // No veto: a deleted source's rows should age out via the cleanup below.
                log.warn("Policy {} references missing source {}; skipping", policy.id(), sourceId);
                continue;
            }
@@ -65,17 +80,35 @@ public class PolicyRunner {
                        sourceId,
                        source.name(),
                        policy.id());
+                // Veto: a paused source's files cannot be stamped, so they must not be pruned.
+                context.vetoCleanup();
                continue;
            }
-            runIds.addAll(pullAndRun(policy, sourceId, source.toInputSpec()));
+            runIds.addAll(pullAndRun(policy, sourceId, source.toInputSpec(), context));
        }
-        return runIds;
+        if (context.cleanupAllowed()) {
+            processedLedger.markSeen(policy.id(), context.presentIdentities());
+            int removed = processedLedger.deleteUnseen(policy.id(), sweepStart);
+            if (removed > 0) {
+                log.debug(
+                        "Pruned {} ledger row(s) for files no longer present (policy {})",
+                        removed,
+                        policy.id());
+            }
+        }
+        return context.outcome(runIds);
    }

-    /** Run a stored policy on caller-supplied files (e.g. manual upload), bypassing its sources. */
+    /**
+     * Run a stored policy on caller-supplied files (e.g. an editor upload), bypassing its sources.
+     * The supplied documents are still counted against the virtual {@link EditorSource}, scoped to
+     * the policy's team, so the Sources overview reports the whole team's editor throughput.
+     */
    public PolicyRunHandle runWith(
            Policy policy, PolicyInputs inputs, PolicyProgressListener listener) {
-        return policyEngine.runPolicy(policy, inputs, listener);
+        PolicyRunHandle handle = policyEngine.runPolicy(policy, inputs, listener);
+        docCounter.record(EditorSource.counterKey(policy.teamId()), inputs.primary().size());
+        return handle;
    }

    /** Run an ad-hoc pipeline with no stored policy (AI/Automate one-offs). */
@@ -86,26 +119,33 @@ public class PolicyRunner {

    /**
     * Resolves the source and starts a run per unit; records how many documents the source fed and
-     * returns the ids of the runs started.
+     * returns the ids of the runs started. Any source that could not be listed completely vetoes
+     * this sweep's ledger cleanup.
     */
-    private List<String> pullAndRun(Policy policy, String sourceId, InputSpec spec) {
+    private List<String> pullAndRun(
+            Policy policy, String sourceId, InputSpec spec, PolicySweep context) {
        InputSource source = sourceFor(spec);
        if (source == null) {
            log.warn(
                    "No input source for type '{}' (policy {}); skipping",
                    spec.type(),
                    policy.id());
+            context.vetoCleanup();
            return List.of();
        }
+        if (!source.listsExhaustively()) {
+            context.vetoCleanup();
+        }
        List<ResolvedInput> work;
        try {
-            work = source.resolve(spec);
+            work = source.resolve(spec, context);
        } catch (IOException | RuntimeException e) {
            log.warn(
                    "Failed to resolve source '{}' for policy {}: {}",
                    spec.type(),
                    policy.id(),
                    e.getMessage());
+            context.vetoCleanup();
            return List.of();
        }
        List<String> runIds = new ArrayList<>();
@@ -0,0 +1,117 @@
+package stirling.software.proprietary.policy.engine;
+
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.function.Supplier;
+
+import stirling.software.proprietary.policy.input.ResolveContext;
+import stirling.software.proprietary.policy.ledger.ClaimState;
+import stirling.software.proprietary.policy.ledger.ProcessedFileStatus;
+import stirling.software.proprietary.policy.ledger.ProcessedLedger;
+
+/**
+ * The {@link ResolveContext} for one policy sweep: scopes ledger calls to the policy, gathers the
+ * present-identity union across sources, prefetches claim state in bulk so per-file claims skip
+ * their row lookup, and vetoes presence cleanup when any source could not be listed completely
+ * (pruning would wrongly forget its files).
+ */
+final class PolicySweep implements ResolveContext {
+
+    private final String policyId;
+    private final SweepKind kind;
+    private final ProcessedLedger ledger;
+    private final Set<String> present = new HashSet<>();
+    // Claim states loaded in bulk at reportPresent; a claim outside the prefetch falls back to a
+    // single lookup. A stale entry cannot double-claim (the ledger re-checks every transition),
+    // it can only defer a file to the next sweep.
+    private final Map<String, ClaimState> prefetched = new HashMap<>();
+    private final Set<String> prefetchedIdentities = new HashSet<>();
+    private boolean cleanupVetoed;
+
+    PolicySweep(String policyId, SweepKind kind, ProcessedLedger ledger) {
+        this.policyId = policyId;
+        this.kind = kind;
+        this.ledger = ledger;
+    }
+
+    @Override
+    public synchronized boolean claim(String identity, String gate, Supplier<String> contentHash) {
+        ClaimState observed =
+                prefetchedIdentities.contains(identity)
+                        ? prefetched.get(identity)
+                        : ledger.statesFor(policyId, List.of(identity)).get(identity);
+        boolean claimed = ledger.claim(policyId, identity, gate, contentHash, observed);
+        if (claimed) {
+            // A nested source surfacing the same file later in this sweep sees it in flight
+            // without another lookup.
+            prefetchedIdentities.add(identity);
+            prefetched.put(identity, new ClaimState(ProcessedFileStatus.PROCESSING, gate, null));
+        }
+        return claimed;
+    }
+
+    @Override
+    public void settle(
+            String identity, String finalGate, String finalContentHash, boolean success) {
+        ledger.settle(policyId, identity, finalGate, finalContentHash, success);
+    }
+
+    @Override
+    public boolean allSettledDone(String identity) {
+        // Deliberately not policy-scoped: consume deletion needs every claimant's consensus.
+        return ledger.allSettledDone(identity);
+    }
+
+    @Override
+    public synchronized void reportPresent(Collection<String> identities) {
+        if (kind == SweepKind.FULL) {
+            present.addAll(identities);
+        }
+        prefetched.putAll(ledger.statesFor(policyId, identities));
+        prefetchedIdentities.addAll(identities);
+    }
+
+    synchronized void vetoCleanup() {
+        cleanupVetoed = true;
+    }
+
+    synchronized boolean cleanupAllowed() {
+        return kind == SweepKind.FULL && !cleanupVetoed;
+    }
+
+    synchronized Set<String> presentIdentities() {
+        return Set.copyOf(present);
+    }
+
+    /**
+     * Summarise the sweep from state already in hand (no extra ledger reads): the prefetched rows
+     * were loaded before claiming, and successful claims flipped their entries to PROCESSING, so
+     * what remains DONE or ERROR is exactly what this sweep skipped.
+     */
+    synchronized SweepOutcome outcome(List<String> runIds) {
+        int alreadyProcessed = 0;
+        int parked = 0;
+        int processing = 0;
+        for (String identity : present) {
+            ClaimState state = prefetched.get(identity);
+            if (state == null) {
+                continue;
+            }
+            switch (state.status()) {
+                case DONE -> alreadyProcessed++;
+                case ERROR -> parked++;
+                case PROCESSING, INTERRUPTED -> processing++;
+            }
+        }
+        return new SweepOutcome(
+                runIds,
+                present.size(),
+                alreadyProcessed,
+                parked,
+                Math.max(0, processing - runIds.size()));
+    }
+}
@@ -52,7 +52,19 @@ public class PolicyValidator {
            InputSpec spec = source.toInputSpec();
            inputSourceFor(spec).validate(spec);
        }
-        outputSinkFor(policy.output()).validate(policy.output());
+        validateOutput(policy.output());
+    }
+
+    /**
+     * Validate an output spec against its sink. Must be called on a request thread (caller's
+     * principal present) so an S3 output's connection is authorization-checked against the caller -
+     * ad-hoc runs are never persisted and so never hit {@link #validate(Policy)}, and the worker
+     * thread that later delivers has no principal, so this is their only access gate.
+     *
+     * @throws IllegalArgumentException if the type is unknown or the config is invalid/inaccessible
+     */
+    public void validateOutput(OutputSpec output) {
+        outputSinkFor(output).validate(output);
    }

    private PolicyTrigger triggerFor(TriggerConfig config) {
@@ -0,0 +1,10 @@
+package stirling.software.proprietary.policy.engine;
+
+/**
+ * How thorough a policy sweep is: {@link #FULL} (complete listing; also stamps presence and prunes
+ * the ledger) or {@link #LIGHT} (event-driven; claims only, cost proportional to what changed).
+ */
+public enum SweepKind {
+    FULL,
+    LIGHT
+}
@@ -0,0 +1,19 @@
+package stirling.software.proprietary.policy.engine;
+
+import java.util.List;
+
+/**
+ * What one policy sweep found and started, so a manual trigger can explain an empty result instead
+ * of a blanket "nothing to do": how many files the sources listed, how many were skipped because
+ * they are already processed at their current version, how many are parked by a failed run (not
+ * retried until they change or history is cleared), and how many are still in flight from an
+ * earlier sweep. Counts are zero for {@link SweepKind#LIGHT} sweeps, which do not take a full
+ * listing.
+ */
+public record SweepOutcome(
+        List<String> runIds, int filesListed, int alreadyProcessed, int parked, int inFlight) {
+
+    public SweepOutcome {
+        runIds = runIds == null ? List.of() : List.copyOf(runIds);
+    }
+}
@@ -1,12 +1,17 @@
 package stirling.software.proprietary.policy.input;

 import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.nio.file.FileVisitResult;
 import java.nio.file.Files;
+import java.nio.file.NoSuchFileException;
 import java.nio.file.Path;
-import java.nio.file.StandardCopyOption;
+import java.nio.file.SimpleFileVisitor;
+import java.nio.file.attribute.BasicFileAttributes;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
+import java.util.function.Supplier;
 import java.util.stream.Stream;

 import org.springframework.boot.autoconfigure.condition.ConditionalOnBooleanProperty;
@@ -19,17 +24,20 @@ import lombok.extern.slf4j.Slf4j;

 import stirling.software.common.util.FileReadinessChecker;
 import stirling.software.proprietary.policy.config.FolderAccessGuard;
+import stirling.software.proprietary.policy.ledger.FolderIdentities;
 import stirling.software.proprietary.policy.model.InputSpec;
 import stirling.software.proprietary.policy.model.PolicyInputs;

 /**
- * Reads input files from a directory; each ready file is its own unit of work so one failure does
- * not affect the others.
- *
- * <p>Mode option: "consume" (default) claims each file by moving it into {@code
- * .stirling/processing} then routes it to {@code .stirling/done} or {@code .stirling/error}, so
- * each file runs once; "snapshot" reads without moving, so every run sees the full set. Readiness
- * is checked first so files mid-write are skipped.
+ * Reads input files from a directory; each ready file is its own unit of work, claimed through the
+ * {@link ResolveContext} ledger rather than moved aside, so nothing accumulates in a work
+ * directory. Options: "mode" is "consume" (default: a processed file is removed once every policy
+ * that claimed it has settled successfully and it is still the version that ran; failures stay in
+ * place and are not retried until they change) or "snapshot" (stateless, every run sees the full
+ * set); "recursive" descends into subdirectories; "identity" is "stat" (default, any size/mtime
+ * change is a new version) or "hash" (content-verified, so a touch does not reprocess). Hidden
+ * files and directories, including the legacy {@code .stirling} work dir, are never picked up, and
+ * files mid-write are skipped by the readiness check.
 */
@Slf4j
@Service
@@ -38,11 +46,6 @@ import stirling.software.proprietary.policy.model.PolicyInputs;
 public class FolderInputSource implements InputSource {

    private static final String TYPE = FolderAccessGuard.FOLDER_TYPE;
-    // Bookkeeping lives under one hidden dir so the watched folder stays tidy.
-    private static final String WORK_SUBDIR = ".stirling";
-    private static final String PROCESSING_SUBDIR = "processing";
-    private static final String DONE_SUBDIR = "done";
-    private static final String ERROR_SUBDIR = "error";

    private final FileReadinessChecker readinessChecker;
    private final FolderAccessGuard accessGuard;
@@ -68,70 +71,195 @@ public class FolderInputSource implements InputSource {
    }

    @Override
-    public List<ResolvedInput> resolve(InputSpec spec) throws IOException {
+    public List<ResolvedInput> resolve(InputSpec spec, ResolveContext ctx) throws IOException {
        FolderConfig config = FolderConfig.from(spec.options());
        Path inputDir = accessGuard.requirePermitted(config.directory());
        if (!Files.isDirectory(inputDir)) {
-            log.debug("Folder input dir does not exist: {}", inputDir);
-            return List.of();
+            // Fail rather than return empty: an unmounted drive must read as "could not list",
+            // which vetoes the sweep's presence cleanup, not as "verifiably no files", which
+            // would wipe the policy's history and reprocess everything on remount.
+            throw new NoSuchFileException(
+                    inputDir.toString(), null, "input directory does not exist");
+        }
+        Path canonicalDir = FolderIdentities.canonicalDir(inputDir);
+        List<Path> present = listFiles(inputDir, config.recursive());
+
+        if (config.snapshot()) {
+            List<ResolvedInput> work = new ArrayList<>();
+            for (Path file : present) {
+                if (readinessChecker.isReady(file)) {
+                    work.add(ResolvedInput.of(PolicyInputs.of(List.of(fileResource(file)))));
+                }
+            }
+            return work;
        }

-        List<Path> ready = new ArrayList<>();
-        try (Stream<Path> entries = Files.list(inputDir)) {
-            entries.filter(Files::isRegularFile)
-                    .filter(readinessChecker::isReady)
-                    .forEach(ready::add);
-        }
+        ctx.reportPresent(
+                present.stream()
+                        .map(file -> FolderIdentities.identity(canonicalDir, inputDir, file))
+                        .toList());

        List<ResolvedInput> work = new ArrayList<>();
-        for (Path file : ready) {
-            if (config.snapshot()) {
-                work.add(ResolvedInput.of(PolicyInputs.of(List.of(fileResource(file)))));
-            } else {
-                Path claimed = claim(inputDir, file);
-                if (claimed == null) {
-                    continue; // another sweep/process grabbed it
-                }
-                work.add(
-                        new ResolvedInput(
-                                PolicyInputs.of(List.of(fileResource(claimed))),
-                                success -> route(inputDir, claimed, success)));
+        for (Path file : present) {
+            if (!readinessChecker.isReady(file)) {
+                continue;
            }
+            String identity = FolderIdentities.identity(canonicalDir, inputDir, file);
+            MemoizedContentHash contentHash =
+                    config.hashIdentity() ? new MemoizedContentHash(file) : null;
+            String gate;
+            boolean claimed;
+            try {
+                gate = FolderIdentities.statGate(file);
+                claimed = ctx.claim(identity, gate, contentHash);
+            } catch (IOException | UncheckedIOException e) {
+                log.debug("Could not read {} for its version: {}", file, e.getMessage());
+                continue; // vanished or unreadable mid-sweep; the next sweep sees the truth
+            }
+            if (!claimed) {
+                continue;
+            }
+            work.add(
+                    new ResolvedInput(
+                            PolicyInputs.of(List.of(fileResource(file))),
+                            success ->
+                                    completeConsumed(
+                                            ctx, identity, file, gate, contentHash, success)));
        }
        return work;
    }

-    // Atomic move into processing/: only one sweep can win the claim, the rest see the file gone.
-    private Path claim(Path inputDir, Path file) {
+    /**
+     * Settle at the version this run claimed - never a re-read, so a file replaced mid-run reads as
+     * a new unclaimed version next sweep instead of being marked processed. Then remove the input
+     * only when it is still the processed version (a mid-run replacement must survive) and every
+     * policy that claimed it has settled DONE, so co-watching policies all read the original and
+     * one failure parks the file for everyone. A failed run settles ERROR and never deletes; the
+     * DONE row of a file that could not be deleted still stops reprocessing.
+     */
+    private static void completeConsumed(
+            ResolveContext ctx,
+            String identity,
+            Path file,
+            String claimGate,
+            MemoizedContentHash contentHash,
+            boolean success) {
+        ctx.settle(identity, claimGate, claimedHash(file, claimGate, contentHash), success);
+        if (!success) {
+            return;
+        }
        try {
-            Path processingDir = workDir(inputDir, PROCESSING_SUBDIR);
-            Files.createDirectories(processingDir);
-            Path claimed = uniqueTarget(processingDir, file.getFileName().toString());
-            Files.move(file, claimed, StandardCopyOption.ATOMIC_MOVE);
-            return claimed;
+            if (FolderIdentities.statGate(file).equals(claimGate) && ctx.allSettledDone(identity)) {
+                Files.deleteIfExists(file);
+            }
+        } catch (NoSuchFileException alreadyGone) {
+            // Removed by the user or a co-watching policy's own consensus delete: nothing to do.
        } catch (IOException e) {
-            log.debug("Could not claim {}: {}", file, e.getMessage());
+            log.warn("Could not remove consumed input {}: {}", file, e.getMessage());
+        }
+    }
+
+    /**
+     * The claimed version's content hash: the value computed during the claim when the ledger
+     * consulted the verifier, else computed now while the file is still at the claimed gate (so the
+     * hash describes what actually ran), else null. Always null in stat mode.
+     */
+    private static String claimedHash(Path file, String claimGate, MemoizedContentHash hash) {
+        if (hash == null) {
            return null;
        }
+        String computed = hash.valueIfComputed();
+        if (computed != null) {
+            return computed;
+        }
+        try {
+            if (FolderIdentities.statGate(file).equals(claimGate)) {
+                return hash.get();
+            }
+        } catch (IOException | UncheckedIOException e) {
+            log.debug("Could not hash {} at settle: {}", file, e.getMessage());
+        }
+        return null;
    }

-    private void route(Path inputDir, Path claimed, boolean success) {
-        String subdir = success ? DONE_SUBDIR : ERROR_SUBDIR;
-        try {
-            Path destDir = workDir(inputDir, subdir);
-            Files.createDirectories(destDir);
-            Files.move(
-                    claimed,
-                    uniqueTarget(destDir, claimed.getFileName().toString()),
-                    StandardCopyOption.ATOMIC_MOVE);
-        } catch (IOException e) {
-            log.warn(
-                    "Could not move processed input {} to {}: {}", claimed, subdir, e.getMessage());
+    /** Lazy verification tier: invoked at most once by the ledger, retained for the settle. */
+    private static final class MemoizedContentHash implements Supplier<String> {
+
+        private final Path file;
+        private volatile String value;
+
+        private MemoizedContentHash(Path file) {
+            this.file = file;
+        }
+
+        @Override
+        public String get() {
+            if (value == null) {
+                try {
+                    value = FolderIdentities.contentHash(file);
+                } catch (IOException e) {
+                    throw new UncheckedIOException(e);
+                }
+            }
+            return value;
+        }
+
+        String valueIfComputed() {
+            return value;
        }
    }

-    private static Path workDir(Path inputDir, String subdir) {
-        return inputDir.resolve(WORK_SUBDIR).resolve(subdir);
+    /** Every non-hidden regular file in the source, readable or not. */
+    private static List<Path> listFiles(Path inputDir, boolean recursive) throws IOException {
+        List<Path> files = new ArrayList<>();
+        if (!recursive) {
+            try (Stream<Path> entries = Files.list(inputDir)) {
+                entries.filter(Files::isRegularFile)
+                        .filter(file -> !hidden(file))
+                        .forEach(files::add);
+            }
+            return files;
+        }
+        // Hidden subtrees are pruned wholesale; symlinked directories are not followed.
+        Files.walkFileTree(
+                inputDir,
+                new SimpleFileVisitor<>() {
+                    @Override
+                    public FileVisitResult preVisitDirectory(
+                            Path dir, BasicFileAttributes attributes) {
+                        if (!dir.equals(inputDir) && hidden(dir)) {
+                            return FileVisitResult.SKIP_SUBTREE;
+                        }
+                        return FileVisitResult.CONTINUE;
+                    }
+
+                    @Override
+                    public FileVisitResult visitFile(Path file, BasicFileAttributes attributes) {
+                        if (attributes.isRegularFile() && !hidden(file)) {
+                            files.add(file);
+                        }
+                        return FileVisitResult.CONTINUE;
+                    }
+
+                    @Override
+                    public FileVisitResult visitFileFailed(Path file, IOException e) {
+                        log.debug("Skipping unreadable entry {}: {}", file, e.getMessage());
+                        return FileVisitResult.CONTINUE;
+                    }
+                });
+        return files;
+    }
+
+    private static boolean hidden(Path path) {
+        Path name = path.getFileName();
+        if (name != null && name.toString().startsWith(".")) {
+            return true;
+        }
+        try {
+            return Files.isHidden(path);
+        } catch (IOException e) {
+            return false;
+        }
    }

    private static Resource fileResource(Path path) {
@@ -144,27 +272,15 @@ public class FolderInputSource implements InputSource {
        };
    }

-    private static Path uniqueTarget(Path dir, String filename) {
-        Path candidate = dir.resolve(filename);
-        if (!Files.exists(candidate)) {
-            return candidate;
-        }
-        int dot = filename.lastIndexOf('.');
-        String base = dot < 0 ? filename : filename.substring(0, dot);
-        String ext = dot < 0 ? "" : filename.substring(dot);
-        for (int n = 1; ; n++) {
-            Path next = dir.resolve(base + " (" + n + ")" + ext);
-            if (!Files.exists(next)) {
-                return next;
-            }
-        }
-    }
-
-    record FolderConfig(Path directory, boolean snapshot) {
+    record FolderConfig(Path directory, boolean snapshot, boolean recursive, boolean hashIdentity) {

        private static final String DIRECTORY_OPTION = "directory";
        private static final String MODE_OPTION = "mode";
        private static final String MODE_SNAPSHOT = "snapshot";
+        private static final String RECURSIVE_OPTION = "recursive";
+        private static final String IDENTITY_OPTION = "identity";
+        private static final String IDENTITY_STAT = "stat";
+        private static final String IDENTITY_HASH = "hash";

        static FolderConfig from(Map<String, Object> options) {
            Object directory = options.get(DIRECTORY_OPTION);
@@ -173,7 +289,17 @@ public class FolderInputSource implements InputSource {
            }
            Object mode = options.get(MODE_OPTION);
            boolean snapshot = mode != null && MODE_SNAPSHOT.equals(mode.toString());
-            return new FolderConfig(Path.of(directory.toString()), snapshot);
+            Object recursive = options.get(RECURSIVE_OPTION);
+            boolean recurse = recursive != null && Boolean.parseBoolean(recursive.toString());
+            Object identity = options.get(IDENTITY_OPTION);
+            boolean hash = identity != null && IDENTITY_HASH.equals(identity.toString());
+            if (identity != null
+                    && !IDENTITY_STAT.equals(identity.toString())
+                    && !IDENTITY_HASH.equals(identity.toString())) {
+                throw new IllegalArgumentException(
+                        "folder input 'identity' must be 'stat' or 'hash'");
+            }
+            return new FolderConfig(Path.of(directory.toString()), snapshot, recurse, hash);
        }
    }
 }
@@ -24,9 +24,21 @@ public interface InputSource {

    /**
     * Resolve the spec into zero or more units of work, each carrying one run's files and a
-     * completion hook. Empty list means nothing to run right now.
+     * completion hook. Empty list means nothing to run right now. Discovery is read-only - files
+     * stay where the user put them; "already processed" is tracked through {@code ctx} (claim on
+     * pickup, settle on completion, report what is present so stale ledger rows can be pruned).
     */
-    List<ResolvedInput> resolve(InputSpec spec) throws IOException;
+    List<ResolvedInput> resolve(InputSpec spec, ResolveContext ctx) throws IOException;
+
+    /**
+     * Whether {@link #resolve} observes everything in the source (a complete listing) rather than
+     * e.g. only what events surfaced. Presence cleanup of the ledger is skipped for the whole
+     * policy unless every enabled source says true - wrongly pruning history would reprocess a
+     * whole folder, while keeping a few stale rows costs nothing.
+     */
+    default boolean listsExhaustively() {
+        return true;
+    }

    /**
     * Filesystem dirs this source draws from, for the folder-watch trigger. Advisory: resolving is
@@ -0,0 +1,36 @@
+package stirling.software.proprietary.policy.input;
+
+import java.util.Collection;
+import java.util.function.Supplier;
+
+/**
+ * A source's policy-scoped window onto the processed-file ledger for one sweep. Thread-safe and
+ * valid for the lifetime of the work units the source issued ({@link #settle} fires from async run
+ * completions).
+ */
+public interface ResolveContext {
+
+    /**
+     * Atomically claim a file at its current version; true means this sweep runs it. A null {@code
+     * contentHash} makes any gate change a new version; a non-null supplier is invoked at most
+     * once, only on a gate mismatch, and a matching hash refreshes the stored gate instead of
+     * reprocessing. Supplier exceptions propagate.
+     */
+    boolean claim(String identity, String gate, Supplier<String> contentHash);
+
+    /** Record a claimed file's outcome at its final version ({@code finalContentHash} nullable). */
+    void settle(String identity, String finalGate, String finalContentHash, boolean success);
+
+    /**
+     * Whether every policy holding a ledger row for this identity has settled it DONE. Cross-policy
+     * by design: consume-mode deletion is a consensus of all claimants, so a shared input is
+     * removed only once nobody still needs it (in-flight, failed, and interrupted rows all veto).
+     */
+    boolean allSettledDone(String identity);
+
+    /**
+     * Report every identity present right now, readable or not; feeds presence cleanup of rows
+     * whose file is gone.
+     */
+    void reportPresent(Collection<String> identities);
+}
@@ -0,0 +1,287 @@
+package stirling.software.proprietary.policy.input;
+
+import java.io.FileNotFoundException;
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.ArrayList;
+import java.util.List;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnBooleanProperty;
+import org.springframework.core.io.AbstractResource;
+import org.springframework.core.io.Resource;
+import org.springframework.stereotype.Service;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.proprietary.policy.model.InputSpec;
+import stirling.software.proprietary.policy.model.PolicyInputs;
+import stirling.software.proprietary.policy.s3.S3Config;
+import stirling.software.proprietary.policy.s3.S3ConnectionPool;
+import stirling.software.proprietary.policy.s3.S3ConnectionResolver;
+import stirling.software.proprietary.policy.s3.S3Identities;
+
+import software.amazon.awssdk.core.exception.SdkException;
+import software.amazon.awssdk.services.s3.S3Client;
+import software.amazon.awssdk.services.s3.model.DeleteObjectRequest;
+import software.amazon.awssdk.services.s3.model.GetObjectRequest;
+import software.amazon.awssdk.services.s3.model.HeadObjectRequest;
+import software.amazon.awssdk.services.s3.model.HeadObjectResponse;
+import software.amazon.awssdk.services.s3.model.ListObjectsV2Request;
+import software.amazon.awssdk.services.s3.model.ListObjectsV2Response;
+import software.amazon.awssdk.services.s3.model.NoSuchKeyException;
+import software.amazon.awssdk.services.s3.model.S3Exception;
+import software.amazon.awssdk.services.s3.model.S3Object;
+
+/**
+ * Reads input files from an Amazon S3 (or S3-compatible) bucket; each listed object is its own unit
+ * of work, claimed through the {@link ResolveContext} ledger and tracked in place. Identity and
+ * version gate come from {@link S3Identities}, so the steady-state sweep never downloads content.
+ * Options: "connectionId" references the stored S3 connection (an {@code IntegrationConfig} owning
+ * bucket, region, endpoint, and credentials - resolved by {@link S3ConnectionResolver}); "prefix"
+ * (only keys starting with it are read) and "mode" are per-source, where mode is "consume"
+ * (default: a processed object is deleted once every policy that claimed it has settled
+ * successfully and it is still the version that ran; failures stay in place and are not retried
+ * until they change) or "snapshot" (stateless, every run sees the full set). Keys ending in "/"
+ * (folder placeholders) and keys with a dot-prefixed path segment are never picked up, mirroring
+ * the folder source's hidden-file rule.
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+@ConditionalOnBooleanProperty(name = "policies.enabled")
+public class S3InputSource implements InputSource {
+
+    private static final String TYPE = "s3";
+
+    private final S3ConnectionPool connectionPool;
+    private final S3ConnectionResolver connectionResolver;
+
+    @Override
+    public String type() {
+        return TYPE;
+    }
+
+    @Override
+    public boolean supports(InputSpec spec) {
+        return spec != null && TYPE.equals(spec.type());
+    }
+
+    /**
+     * Fails fast at save time: an unknown/disabled/unusable connection, bad config shape, a private
+     * endpoint without the operator opt-in, or a bucket the connection cannot list.
+     */
+    @Override
+    public void validate(InputSpec spec) {
+        S3Config config = connectionResolver.resolve(spec.options());
+        try {
+            connectionPool.clientFor(config).listObjectsV2(listRequest(config).maxKeys(1).build());
+        } catch (SdkException e) {
+            throw new IllegalArgumentException(
+                    "cannot access s3://"
+                            + config.bucket()
+                            + "/"
+                            + config.prefix()
+                            + ": "
+                            + e.getMessage(),
+                    e);
+        }
+    }
+
+    @Override
+    public List<ResolvedInput> resolve(InputSpec spec, ResolveContext ctx) throws IOException {
+        S3Config config = connectionResolver.resolve(spec.options());
+        S3Client client = connectionPool.clientFor(config);
+        // A listing failure propagates so the sweep reads it as "could not list" (which vetoes
+        // presence cleanup), never as "verifiably no objects".
+        List<S3Object> objects = listObjects(client, config);
+
+        if (config.snapshot()) {
+            return objects.stream()
+                    .map(
+                            object ->
+                                    ResolvedInput.of(
+                                            PolicyInputs.of(
+                                                    List.of(
+                                                            objectResource(
+                                                                    client, config, object)))))
+                    .toList();
+        }
+
+        ctx.reportPresent(
+                objects.stream()
+                        .map(object -> S3Identities.identity(config.bucket(), object.key()))
+                        .toList());
+
+        List<ResolvedInput> work = new ArrayList<>();
+        for (S3Object object : objects) {
+            String identity = S3Identities.identity(config.bucket(), object.key());
+            String gate = S3Identities.gate(object.eTag(), object.size(), object.lastModified());
+            if (!ctx.claim(identity, gate, null)) {
+                continue;
+            }
+            work.add(
+                    new ResolvedInput(
+                            PolicyInputs.of(List.of(objectResource(client, config, object))),
+                            success ->
+                                    completeConsumed(
+                                            ctx,
+                                            client,
+                                            config,
+                                            object.key(),
+                                            identity,
+                                            gate,
+                                            success)));
+        }
+        return work;
+    }
+
+    /**
+     * Settle at the version this run claimed, then remove the object only when it still carries
+     * that version and every policy that claimed it has settled DONE, mirroring the folder source's
+     * consensus delete. A failed run settles ERROR and never deletes; the DONE row of an object
+     * that could not be deleted still stops reprocessing.
+     */
+    private void completeConsumed(
+            ResolveContext ctx,
+            S3Client client,
+            S3Config config,
+            String key,
+            String identity,
+            String claimGate,
+            boolean success) {
+        ctx.settle(identity, claimGate, null, success);
+        if (!success) {
+            return;
+        }
+        try {
+            HeadObjectResponse head =
+                    client.headObject(
+                            HeadObjectRequest.builder().bucket(config.bucket()).key(key).build());
+            String currentGate =
+                    S3Identities.gate(head.eTag(), head.contentLength(), head.lastModified());
+            if (currentGate.equals(claimGate) && ctx.allSettledDone(identity)) {
+                client.deleteObject(
+                        DeleteObjectRequest.builder().bucket(config.bucket()).key(key).build());
+            }
+        } catch (NoSuchKeyException alreadyGone) {
+            // Removed by the user or a co-watching policy's own consensus delete: nothing to do.
+        } catch (S3Exception e) {
+            if (e.statusCode() == 404) {
+                return;
+            }
+            log.warn("Could not remove consumed S3 object {}: {}", identity, e.getMessage());
+        } catch (SdkException e) {
+            log.warn("Could not remove consumed S3 object {}: {}", identity, e.getMessage());
+        }
+    }
+
+    /** Every ingestible object under the configured prefix, across all listing pages. */
+    private static List<S3Object> listObjects(S3Client client, S3Config config) {
+        List<S3Object> objects = new ArrayList<>();
+        String continuationToken = null;
+        do {
+            ListObjectsV2Request.Builder request = listRequest(config);
+            if (continuationToken != null) {
+                request.continuationToken(continuationToken);
+            }
+            ListObjectsV2Response page = client.listObjectsV2(request.build());
+            for (S3Object object : page.contents()) {
+                if (ingestible(object)) {
+                    objects.add(object);
+                }
+            }
+            continuationToken = page.nextContinuationToken();
+        } while (continuationToken != null);
+        return objects;
+    }
+
+    private static ListObjectsV2Request.Builder listRequest(S3Config config) {
+        ListObjectsV2Request.Builder request =
+                ListObjectsV2Request.builder().bucket(config.bucket());
+        if (!config.prefix().isEmpty()) {
+            request.prefix(config.prefix());
+        }
+        return request;
+    }
+
+    /**
+     * Folder-placeholder keys (ending "/") and keys with a dot-prefixed segment are skipped, so a
+     * hidden convention (e.g. a future output sink's staging prefix) is never re-ingested.
+     */
+    private static boolean ingestible(S3Object object) {
+        String key = object.key();
+        if (key.isEmpty() || key.endsWith("/")) {
+            return false;
+        }
+        for (String segment : key.split("/")) {
+            if (segment.startsWith(".")) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    private static Resource objectResource(S3Client client, S3Config config, S3Object object) {
+        return new S3ObjectResource(client, config.bucket(), object);
+    }
+
+    /**
+     * Streams the object on demand, pinned to the ETag observed at listing time so a run never
+     * reads a different version than the sweep claimed (a swapped object fails the read with a
+     * precondition error and the new version is claimed by a later sweep).
+     */
+    private static final class S3ObjectResource extends AbstractResource {
+
+        private final S3Client client;
+        private final String bucket;
+        private final String key;
+        private final String eTag;
+        private final Long size;
+
+        private S3ObjectResource(S3Client client, String bucket, S3Object object) {
+            this.client = client;
+            this.bucket = bucket;
+            this.key = object.key();
+            this.eTag = object.eTag();
+            this.size = object.size();
+        }
+
+        @Override
+        public InputStream getInputStream() throws IOException {
+            GetObjectRequest.Builder request = GetObjectRequest.builder().bucket(bucket).key(key);
+            if (eTag != null && !eTag.isBlank()) {
+                request.ifMatch(eTag);
+            }
+            try {
+                return client.getObject(request.build());
+            } catch (NoSuchKeyException e) {
+                throw new FileNotFoundException(getDescription() + " no longer exists");
+            } catch (SdkException e) {
+                throw new IOException(
+                        "Could not read " + getDescription() + ": " + e.getMessage(), e);
+            }
+        }
+
+        /** Listed just now; readers get a precise error from {@link #getInputStream} instead. */
+        @Override
+        public boolean exists() {
+            return true;
+        }
+
+        @Override
+        public long contentLength() {
+            return size == null ? -1 : size;
+        }
+
+        @Override
+        public String getFilename() {
+            return key.substring(key.lastIndexOf('/') + 1);
+        }
+
+        @Override
+        public String getDescription() {
+            return "S3 object " + S3Identities.identity(bucket, key);
+        }
+    }
+}
@@ -0,0 +1,9 @@
+package stirling.software.proprietary.policy.ledger;
+
+/**
+ * A row's claim-relevant state as read by {@link ProcessedLedger#statesFor}: what a sweep observed
+ * before deciding a claim. May be stale by the time the claim runs; every ledger transition
+ * re-checks the observed state in its WHERE clause, so staleness defers a claim to a later sweep
+ * rather than double-running one.
+ */
+public record ClaimState(ProcessedFileStatus status, String gate, String contentHash) {}
@@ -0,0 +1,41 @@
+package stirling.software.proprietary.policy.ledger;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.attribute.BasicFileAttributes;
+
+import stirling.software.proprietary.billing.ContentHasher;
+
+/**
+ * The folder backend's identity and version scheme, shared by {@code FolderInputSource} and {@code
+ * FolderOutputSink} so outputs are recorded under exactly the identity the next scan derives.
+ * Directories are canonicalised with {@code toRealPath()} so symlinked aliases agree.
+ */
+public final class FolderIdentities {
+
+    private FolderIdentities() {}
+
+    /** Canonical form of a configured directory; resolves symlinks, so the dir must exist. */
+    public static Path canonicalDir(Path dir) throws IOException {
+        return dir.toRealPath();
+    }
+
+    /** Identity of {@code file} under {@code dir}: its path re-rooted onto the canonical dir. */
+    public static String identity(Path canonicalDir, Path dir, Path file) {
+        return canonicalDir.resolve(dir.relativize(file)).normalize().toString();
+    }
+
+    /** The cheap version gate: a change to content length or mtime means "look closer". */
+    public static String statGate(Path file) throws IOException {
+        BasicFileAttributes attributes = Files.readAttributes(file, BasicFileAttributes.class);
+        return attributes.size() + ":" + attributes.lastModifiedTime().toMillis();
+    }
+
+    /**
+     * The strong version token: distinguishes a real change from a touch, at the cost of a read.
+     */
+    public static String contentHash(Path file) throws IOException {
+        return ContentHasher.sha256(file);
+    }
+}
@@ -0,0 +1,19 @@
+package stirling.software.proprietary.policy.ledger;
+
+import java.nio.charset.StandardCharsets;
+
+import stirling.software.proprietary.billing.ContentHasher;
+
+/**
+ * Fixed-width key form of a source-owned identity, so any identity length fits the ledger's primary
+ * key. Backend-agnostic: every source type's identities are keyed through here, which is why this
+ * does not live with the folder backend's {@link FolderIdentities}.
+ */
+public final class IdentityHasher {
+
+    private IdentityHasher() {}
+
+    public static String identityHash(String identity) {
+        return ContentHasher.sha256(identity.getBytes(StandardCharsets.UTF_8));
+    }
+}
@@ -0,0 +1,229 @@
+package stirling.software.proprietary.policy.ledger;
+
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Objects;
+import java.util.function.Supplier;
+
+/**
+ * In-memory {@link ProcessedLedger} for tests and DB-less wiring; kept semantically identical to
+ * {@code JpaProcessedLedger} by the shared contract test.
+ */
+public class InProcessProcessedLedger implements ProcessedLedger {
+
+    private final Map<String, Map<String, Row>> rowsByPolicy = new HashMap<>();
+    private final Supplier<Long> nowMillis;
+
+    public InProcessProcessedLedger() {
+        this(System::currentTimeMillis);
+    }
+
+    public InProcessProcessedLedger(Supplier<Long> nowMillis) {
+        this.nowMillis = nowMillis;
+    }
+
+    @Override
+    public synchronized Map<String, ClaimState> statesFor(
+            String policyId, Collection<String> identities) {
+        Map<String, Row> rows = rowsByPolicy.getOrDefault(policyId, Map.of());
+        Map<String, ClaimState> states = new HashMap<>();
+        for (String identity : identities) {
+            Row row = rows.get(identity);
+            if (row != null) {
+                states.put(identity, new ClaimState(row.status, row.gate, row.contentHash));
+            }
+        }
+        return states;
+    }
+
+    // Single-lock store: the live row is never staler than any observed snapshot, so decide
+    // against it directly; the conditional updates of the JPA ledger yield the same outcomes.
+    @Override
+    public synchronized boolean claim(
+            String policyId,
+            String identity,
+            String gate,
+            Supplier<String> contentHash,
+            ClaimState observed) {
+        Map<String, Row> rows = rowsByPolicy.computeIfAbsent(policyId, key -> new HashMap<>());
+        long now = nowMillis.get();
+        Row row = rows.get(identity);
+        if (row == null) {
+            String hash = contentHash == null ? null : contentHash.get();
+            rows.put(identity, new Row(gate, hash, ProcessedFileStatus.PROCESSING, 1, now));
+            return true;
+        }
+        if (row.status == ProcessedFileStatus.PROCESSING) {
+            return false;
+        }
+        if (gate.equals(row.gate)) {
+            if (row.status == ProcessedFileStatus.INTERRUPTED && row.attempts < MAX_ATTEMPTS) {
+                row.status = ProcessedFileStatus.PROCESSING;
+                row.attempts++;
+                row.lastSeen = now;
+                return true;
+            }
+            return false;
+        }
+        if (contentHash == null) {
+            row.gate = gate;
+            row.contentHash = null;
+            row.status = ProcessedFileStatus.PROCESSING;
+            row.attempts = 1;
+            row.lastSeen = now;
+            return true;
+        }
+        String hash = contentHash.get();
+        if (Objects.equals(hash, row.contentHash)) {
+            if (row.status == ProcessedFileStatus.INTERRUPTED && row.attempts < MAX_ATTEMPTS) {
+                row.gate = gate;
+                row.status = ProcessedFileStatus.PROCESSING;
+                row.attempts++;
+                row.lastSeen = now;
+                return true;
+            }
+            if (row.status != ProcessedFileStatus.INTERRUPTED) {
+                row.gate = gate;
+                row.lastSeen = now;
+            }
+            return false;
+        }
+        row.gate = gate;
+        row.contentHash = hash;
+        row.status = ProcessedFileStatus.PROCESSING;
+        row.attempts = 1;
+        row.lastSeen = now;
+        return true;
+    }
+
+    @Override
+    public synchronized void settle(
+            String policyId,
+            String identity,
+            String finalGate,
+            String finalContentHash,
+            boolean success) {
+        upsertSettled(
+                policyId,
+                identity,
+                finalGate,
+                finalContentHash,
+                success ? ProcessedFileStatus.DONE : ProcessedFileStatus.ERROR);
+    }
+
+    @Override
+    public synchronized void recordOutput(
+            String policyId, String identity, String gate, String contentHash) {
+        upsertSettled(policyId, identity, gate, contentHash, ProcessedFileStatus.DONE);
+    }
+
+    @Override
+    public synchronized void forgetOutput(String policyId, String identity, String gate) {
+        Map<String, Row> rows = rowsByPolicy.get(policyId);
+        if (rows == null) {
+            return;
+        }
+        Row row = rows.get(identity);
+        if (row != null && row.status == ProcessedFileStatus.DONE && gate.equals(row.gate)) {
+            rows.remove(identity);
+        }
+    }
+
+    private void upsertSettled(
+            String policyId,
+            String identity,
+            String gate,
+            String contentHash,
+            ProcessedFileStatus status) {
+        Map<String, Row> rows = rowsByPolicy.computeIfAbsent(policyId, key -> new HashMap<>());
+        long now = nowMillis.get();
+        Row row = rows.get(identity);
+        if (row == null) {
+            rows.put(identity, new Row(gate, contentHash, status, 1, now));
+            return;
+        }
+        row.gate = gate;
+        row.contentHash = contentHash;
+        row.status = status;
+        row.lastSeen = now;
+    }
+
+    @Override
+    public synchronized boolean allSettledDone(String identity) {
+        for (Map<String, Row> rows : rowsByPolicy.values()) {
+            Row row = rows.get(identity);
+            if (row != null && row.status != ProcessedFileStatus.DONE) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    @Override
+    public synchronized void markSeen(String policyId, Collection<String> identities) {
+        Map<String, Row> rows = rowsByPolicy.get(policyId);
+        if (rows == null) {
+            return;
+        }
+        long now = nowMillis.get();
+        for (String identity : identities) {
+            Row row = rows.get(identity);
+            if (row != null) {
+                row.lastSeen = now;
+            }
+        }
+    }
+
+    @Override
+    public synchronized int deleteUnseen(String policyId, long seenSinceMillis) {
+        Map<String, Row> rows = rowsByPolicy.get(policyId);
+        if (rows == null) {
+            return 0;
+        }
+        int before = rows.size();
+        rows.values()
+                .removeIf(
+                        row ->
+                                row.lastSeen < seenSinceMillis
+                                        && row.status != ProcessedFileStatus.PROCESSING);
+        return before - rows.size();
+    }
+
+    @Override
+    public synchronized void clearPolicy(String policyId) {
+        rowsByPolicy.remove(policyId);
+    }
+
+    @Override
+    public synchronized void recoverInterrupted() {
+        for (Map<String, Row> rows : rowsByPolicy.values()) {
+            for (Row row : rows.values()) {
+                if (row.status == ProcessedFileStatus.PROCESSING) {
+                    row.status = ProcessedFileStatus.INTERRUPTED;
+                }
+            }
+        }
+    }
+
+    private static final class Row {
+        private String gate;
+        private String contentHash;
+        private ProcessedFileStatus status;
+        private int attempts;
+        private long lastSeen;
+
+        private Row(
+                String gate,
+                String contentHash,
+                ProcessedFileStatus status,
+                int attempts,
+                long lastSeen) {
+            this.gate = gate;
+            this.contentHash = contentHash;
+            this.status = status;
+            this.attempts = attempts;
+            this.lastSeen = lastSeen;
+        }
+    }
+}
@@ -0,0 +1,212 @@
+package stirling.software.proprietary.policy.ledger;
+
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Supplier;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnBooleanProperty;
+import org.springframework.boot.context.event.ApplicationReadyEvent;
+import org.springframework.context.event.EventListener;
+import org.springframework.dao.DataIntegrityViolationException;
+import org.springframework.stereotype.Service;
+
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Durable {@link ProcessedLedger}; the runtime bean. A fresh claim is a flushed insert so a
+ * concurrent winner surfaces as a constraint violation; every other transition is a conditional
+ * update that re-checks the observed state, so a lost race reports 0 rows and the caller skips.
+ * Boot recovery assumes the single node the folder-watch trigger assumes: runs live in memory, so
+ * after a restart every PROCESSING row is stale.
+ */
+@Slf4j
+@Service
+@ConditionalOnBooleanProperty(name = "policies.enabled")
+public class JpaProcessedLedger implements ProcessedLedger {
+
+    private static final int STAMP_CHUNK = 500;
+
+    private final ProcessedFileRepository repository;
+    private final Supplier<Long> nowMillis;
+
+    @Autowired
+    public JpaProcessedLedger(ProcessedFileRepository repository) {
+        this(repository, System::currentTimeMillis);
+    }
+
+    // Clock seam so tests can pin "now"; the runtime bean uses the wall clock above.
+    JpaProcessedLedger(ProcessedFileRepository repository, Supplier<Long> nowMillis) {
+        this.repository = repository;
+        this.nowMillis = nowMillis;
+    }
+
+    @Override
+    public Map<String, ClaimState> statesFor(String policyId, Collection<String> identities) {
+        if (identities.isEmpty()) {
+            return Map.of();
+        }
+        Map<String, String> identityByHash = new HashMap<>();
+        for (String identity : identities) {
+            identityByHash.put(IdentityHasher.identityHash(identity), identity);
+        }
+        Map<String, ClaimState> states = new HashMap<>();
+        List<String> hashes = List.copyOf(identityByHash.keySet());
+        for (int from = 0; from < hashes.size(); from += STAMP_CHUNK) {
+            List<ProcessedFileEntity> rows =
+                    repository.findByPolicyIdAndIdentityHashIn(
+                            policyId,
+                            hashes.subList(from, Math.min(from + STAMP_CHUNK, hashes.size())));
+            for (ProcessedFileEntity row : rows) {
+                states.put(
+                        identityByHash.get(row.getIdentityHash()),
+                        new ClaimState(row.getStatus(), row.getSignature(), row.getContentHash()));
+            }
+        }
+        return states;
+    }
+
+    @Override
+    public boolean claim(
+            String policyId,
+            String identity,
+            String gate,
+            Supplier<String> contentHash,
+            ClaimState observed) {
+        String identityHash = IdentityHasher.identityHash(identity);
+        long now = nowMillis.get();
+        if (observed == null) {
+            try {
+                repository.saveAndFlush(
+                        new ProcessedFileEntity(
+                                policyId,
+                                identityHash,
+                                identity,
+                                gate,
+                                contentHash == null ? null : contentHash.get(),
+                                ProcessedFileStatus.PROCESSING,
+                                now));
+                return true;
+            } catch (DataIntegrityViolationException concurrentClaim) {
+                return false;
+            }
+        }
+        if (observed.status() == ProcessedFileStatus.PROCESSING) {
+            return false;
+        }
+        if (gate.equals(observed.gate())) {
+            if (observed.status() == ProcessedFileStatus.INTERRUPTED) {
+                return repository.retryInterruptedAtGate(
+                                policyId, identityHash, gate, MAX_ATTEMPTS, now)
+                        > 0;
+            }
+            return false;
+        }
+        if (contentHash == null) {
+            return repository.reclaimAtNewGate(policyId, identityHash, gate, now) > 0;
+        }
+        String hash = contentHash.get();
+        if (hash.equals(observed.contentHash())) {
+            if (observed.status() == ProcessedFileStatus.INTERRUPTED) {
+                return repository.retryInterruptedSameContent(
+                                policyId, identityHash, gate, hash, MAX_ATTEMPTS, now)
+                        > 0;
+            }
+            repository.refreshGate(policyId, identityHash, gate, hash, now);
+            return false;
+        }
+        return repository.reclaimAtNewContent(policyId, identityHash, gate, hash, now) > 0;
+    }
+
+    @Override
+    public void settle(
+            String policyId,
+            String identity,
+            String finalGate,
+            String finalContentHash,
+            boolean success) {
+        upsertSettled(
+                policyId,
+                identity,
+                finalGate,
+                finalContentHash,
+                success ? ProcessedFileStatus.DONE : ProcessedFileStatus.ERROR);
+    }
+
+    @Override
+    public void recordOutput(String policyId, String identity, String gate, String contentHash) {
+        upsertSettled(policyId, identity, gate, contentHash, ProcessedFileStatus.DONE);
+    }
+
+    @Override
+    public void forgetOutput(String policyId, String identity, String gate) {
+        repository.deleteDoneAt(policyId, IdentityHasher.identityHash(identity), gate);
+    }
+
+    /**
+     * Settle-or-insert: the row may have been presence-cleaned mid-run, and an output row may be
+     * brand new.
+     */
+    private void upsertSettled(
+            String policyId,
+            String identity,
+            String gate,
+            String contentHash,
+            ProcessedFileStatus status) {
+        String identityHash = IdentityHasher.identityHash(identity);
+        long now = nowMillis.get();
+        if (repository.settle(policyId, identityHash, gate, contentHash, status, now) > 0) {
+            return;
+        }
+        try {
+            ProcessedFileEntity row =
+                    new ProcessedFileEntity(
+                            policyId, identityHash, identity, gate, contentHash, status, now);
+            repository.saveAndFlush(row);
+        } catch (DataIntegrityViolationException concurrentInsert) {
+            repository.settle(policyId, identityHash, gate, contentHash, status, now);
+        }
+    }
+
+    @Override
+    public boolean allSettledDone(String identity) {
+        return !repository.existsByIdentityHashAndStatusNot(
+                IdentityHasher.identityHash(identity), ProcessedFileStatus.DONE);
+    }
+
+    @Override
+    public void markSeen(String policyId, Collection<String> identities) {
+        if (identities.isEmpty()) {
+            return;
+        }
+        List<String> hashes = identities.stream().map(IdentityHasher::identityHash).toList();
+        long now = nowMillis.get();
+        for (int from = 0; from < hashes.size(); from += STAMP_CHUNK) {
+            repository.stampSeen(
+                    policyId,
+                    hashes.subList(from, Math.min(from + STAMP_CHUNK, hashes.size())),
+                    now);
+        }
+    }
+
+    @Override
+    public int deleteUnseen(String policyId, long seenSinceMillis) {
+        return repository.deleteUnseen(policyId, seenSinceMillis);
+    }
+
+    @Override
+    public void clearPolicy(String policyId) {
+        repository.deleteByPolicy(policyId);
+    }
+
+    @Override
+    @EventListener(ApplicationReadyEvent.class)
+    public void recoverInterrupted() {
+        int recovered = repository.markAllProcessingInterrupted(nowMillis.get());
+        if (recovered > 0) {
+            log.info("Recovered {} policy input file(s) interrupted by shutdown", recovered);
+        }
+    }
+}
@@ -0,0 +1,106 @@
+package stirling.software.proprietary.policy.ledger;
+
+import java.io.Serializable;
+
+import org.springframework.data.domain.Persistable;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.Id;
+import jakarta.persistence.IdClass;
+import jakarta.persistence.Index;
+import jakarta.persistence.Table;
+import jakarta.persistence.Transient;
+
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+/**
+ * One processed-file ledger row: the version a policy last settled a file at, and where it is in
+ * the claim lifecycle. Keyed by SHA-256 of the source-owned identity so any identity length fits a
+ * fixed-width index. {@code isNew} is always true: the entity is only saved for fresh inserts
+ * (everything else is a conditional update), so a lost insert race surfaces as a constraint
+ * violation rather than a silent merge.
+ */
+@Entity
+@Table(
+        name = "policy_processed_files",
+        indexes = {
+            // presence cleanup: delete this policy's rows unseen since the sweep began
+            @Index(name = "idx_processed_files_policy_seen", columnList = "policy_id, last_seen"),
+            // cross-policy deletion consensus: existsByIdentityHashAndStatusNot filters
+            // identity_hash on its own, so it cannot ride the (policy_id, identity_hash) PK
+            @Index(name = "idx_processed_files_identity", columnList = "identity_hash")
+        })
+@IdClass(ProcessedFileId.class)
+@NoArgsConstructor
+@Getter
+@Setter
+public class ProcessedFileEntity implements Serializable, Persistable<ProcessedFileId> {
+
+    private static final long serialVersionUID = 1L;
+
+    @Id
+    @Column(name = "policy_id")
+    private String policyId;
+
+    @Id
+    @Column(name = "identity_hash", length = 64)
+    private String identityHash;
+
+    @Column(name = "identity", length = 4096)
+    private String identity;
+
+    @Column(name = "signature")
+    private String signature;
+
+    @Column(name = "content_hash", length = 64)
+    private String contentHash;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "status", length = 16)
+    private ProcessedFileStatus status;
+
+    @Column(name = "attempts")
+    private int attempts;
+
+    @Column(name = "last_seen")
+    private long lastSeen;
+
+    @Column(name = "updated_at")
+    private long updatedAt;
+
+    public ProcessedFileEntity(
+            String policyId,
+            String identityHash,
+            String identity,
+            String signature,
+            String contentHash,
+            ProcessedFileStatus status,
+            long nowMillis) {
+        this.policyId = policyId;
+        this.identityHash = identityHash;
+        this.identity = identity;
+        this.signature = signature;
+        this.contentHash = contentHash;
+        this.status = status;
+        this.attempts = 1;
+        this.lastSeen = nowMillis;
+        this.updatedAt = nowMillis;
+    }
+
+    @Override
+    @Transient
+    public ProcessedFileId getId() {
+        return new ProcessedFileId(policyId, identityHash);
+    }
+
+    @Override
+    @Transient
+    public boolean isNew() {
+        return true;
+    }
+}
@@ -0,0 +1,37 @@
+package stirling.software.proprietary.policy.ledger;
+
+import java.io.Serializable;
+import java.util.Objects;
+
+/** Composite key for {@link ProcessedFileEntity}: one row per policy per file identity. */
+public class ProcessedFileId implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    private String policyId;
+    private String identityHash;
+
+    public ProcessedFileId() {}
+
+    public ProcessedFileId(String policyId, String identityHash) {
+        this.policyId = policyId;
+        this.identityHash = identityHash;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (!(o instanceof ProcessedFileId other)) {
+            return false;
+        }
+        return Objects.equals(policyId, other.policyId)
+                && Objects.equals(identityHash, other.identityHash);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(policyId, identityHash);
+    }
+}
@@ -0,0 +1,195 @@
+package stirling.software.proprietary.policy.ledger;
+
+import java.util.Collection;
+import java.util.List;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+import org.springframework.stereotype.Repository;
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * Conditional updates for the processed-file ledger: each claim variant re-checks in its WHERE
+ * clause the state it was decided against, so a racing claim loses cleanly with 0 rows updated.
+ * Transactional per call so the ledger can run them without an enclosing transaction.
+ */
+@Repository
+public interface ProcessedFileRepository
+        extends JpaRepository<ProcessedFileEntity, ProcessedFileId> {
+
+    /**
+     * Re-claim a settled row at a new gate without content verification; clears the stored hash,
+     * which described content this claim never checked.
+     */
+    @Modifying
+    @Transactional
+    @Query(
+            "update ProcessedFileEntity e set e.status ="
+                    + " stirling.software.proprietary.policy.ledger.ProcessedFileStatus.PROCESSING,"
+                    + " e.signature = :gate, e.contentHash = null, e.attempts = 1,"
+                    + " e.lastSeen = :now, e.updatedAt = :now"
+                    + " where e.policyId = :policyId and e.identityHash = :identityHash"
+                    + " and e.status <>"
+                    + " stirling.software.proprietary.policy.ledger.ProcessedFileStatus.PROCESSING"
+                    + " and e.signature <> :gate")
+    int reclaimAtNewGate(
+            @Param("policyId") String policyId,
+            @Param("identityHash") String identityHash,
+            @Param("gate") String gate,
+            @Param("now") long now);
+
+    /** Re-claim a settled row whose content verifiably changed (or was never hashed). */
+    @Modifying
+    @Transactional
+    @Query(
+            "update ProcessedFileEntity e set e.status ="
+                    + " stirling.software.proprietary.policy.ledger.ProcessedFileStatus.PROCESSING,"
+                    + " e.signature = :gate, e.contentHash = :contentHash, e.attempts = 1,"
+                    + " e.lastSeen = :now, e.updatedAt = :now"
+                    + " where e.policyId = :policyId and e.identityHash = :identityHash"
+                    + " and e.status <>"
+                    + " stirling.software.proprietary.policy.ledger.ProcessedFileStatus.PROCESSING"
+                    + " and (e.contentHash is null or e.contentHash <> :contentHash)")
+    int reclaimAtNewContent(
+            @Param("policyId") String policyId,
+            @Param("identityHash") String identityHash,
+            @Param("gate") String gate,
+            @Param("contentHash") String contentHash,
+            @Param("now") long now);
+
+    /** The gate moved but the content did not: track the new gate without changing status. */
+    @Modifying
+    @Transactional
+    @Query(
+            "update ProcessedFileEntity e set e.signature = :gate, e.lastSeen = :now,"
+                    + " e.updatedAt = :now"
+                    + " where e.policyId = :policyId and e.identityHash = :identityHash"
+                    + " and e.status <>"
+                    + " stirling.software.proprietary.policy.ledger.ProcessedFileStatus.PROCESSING"
+                    + " and e.contentHash = :contentHash and e.signature <> :gate")
+    int refreshGate(
+            @Param("policyId") String policyId,
+            @Param("identityHash") String identityHash,
+            @Param("gate") String gate,
+            @Param("contentHash") String contentHash,
+            @Param("now") long now);
+
+    /** Bounded retry of an INTERRUPTED row at the same gate. */
+    @Modifying
+    @Transactional
+    @Query(
+            "update ProcessedFileEntity e set e.status ="
+                    + " stirling.software.proprietary.policy.ledger.ProcessedFileStatus.PROCESSING,"
+                    + " e.attempts = e.attempts + 1, e.lastSeen = :now, e.updatedAt = :now"
+                    + " where e.policyId = :policyId and e.identityHash = :identityHash"
+                    + " and e.status ="
+                    + " stirling.software.proprietary.policy.ledger.ProcessedFileStatus.INTERRUPTED"
+                    + " and e.signature = :gate and e.attempts < :maxAttempts")
+    int retryInterruptedAtGate(
+            @Param("policyId") String policyId,
+            @Param("identityHash") String identityHash,
+            @Param("gate") String gate,
+            @Param("maxAttempts") int maxAttempts,
+            @Param("now") long now);
+
+    /** Bounded retry of an INTERRUPTED row whose gate moved but whose content is unchanged. */
+    @Modifying
+    @Transactional
+    @Query(
+            "update ProcessedFileEntity e set e.status ="
+                    + " stirling.software.proprietary.policy.ledger.ProcessedFileStatus.PROCESSING,"
+                    + " e.signature = :gate, e.attempts = e.attempts + 1, e.lastSeen = :now,"
+                    + " e.updatedAt = :now"
+                    + " where e.policyId = :policyId and e.identityHash = :identityHash"
+                    + " and e.status ="
+                    + " stirling.software.proprietary.policy.ledger.ProcessedFileStatus.INTERRUPTED"
+                    + " and e.contentHash = :contentHash and e.attempts < :maxAttempts")
+    int retryInterruptedSameContent(
+            @Param("policyId") String policyId,
+            @Param("identityHash") String identityHash,
+            @Param("gate") String gate,
+            @Param("contentHash") String contentHash,
+            @Param("maxAttempts") int maxAttempts,
+            @Param("now") long now);
+
+    /**
+     * Unconditional settle (only the claiming run settles a row); returns 0 when the row was
+     * removed mid-run so the caller re-inserts.
+     */
+    @Modifying
+    @Transactional
+    @Query(
+            "update ProcessedFileEntity e set e.status = :status, e.signature = :gate,"
+                    + " e.contentHash = :contentHash, e.lastSeen = :now, e.updatedAt = :now"
+                    + " where e.policyId = :policyId and e.identityHash = :identityHash")
+    int settle(
+            @Param("policyId") String policyId,
+            @Param("identityHash") String identityHash,
+            @Param("gate") String gate,
+            @Param("contentHash") String contentHash,
+            @Param("status") ProcessedFileStatus status,
+            @Param("now") long now);
+
+    /** Whether any policy's row at this identity is in a state other than {@code status}. */
+    boolean existsByIdentityHashAndStatusNot(String identityHash, ProcessedFileStatus status);
+
+    /** One policy's rows across a chunk of identity hashes, for a sweep's claim snapshot. */
+    List<ProcessedFileEntity> findByPolicyIdAndIdentityHashIn(
+            String policyId, Collection<String> identityHashes);
+
+    /**
+     * Remove an output record whose rename never landed, only while still settled exactly as
+     * recorded; a row a claim has since taken over is left alone.
+     */
+    @Modifying
+    @Transactional
+    @Query(
+            "delete from ProcessedFileEntity e where e.policyId = :policyId"
+                    + " and e.identityHash = :identityHash and e.signature = :gate"
+                    + " and e.status ="
+                    + " stirling.software.proprietary.policy.ledger.ProcessedFileStatus.DONE")
+    int deleteDoneAt(
+            @Param("policyId") String policyId,
+            @Param("identityHash") String identityHash,
+            @Param("gate") String gate);
+
+    /** Stamp presence for the given identities; chunked by the caller for very large folders. */
+    @Modifying
+    @Transactional
+    @Query(
+            "update ProcessedFileEntity e set e.lastSeen = :now"
+                    + " where e.policyId = :policyId and e.identityHash in :identityHashes")
+    int stampSeen(
+            @Param("policyId") String policyId,
+            @Param("identityHashes") Collection<String> identityHashes,
+            @Param("now") long now);
+
+    /**
+     * Presence cleanup: remove rows not stamped since the sweep began, keeping in-flight claims.
+     */
+    @Modifying
+    @Transactional
+    @Query(
+            "delete from ProcessedFileEntity e where e.policyId = :policyId"
+                    + " and e.lastSeen < :cutoff and e.status <>"
+                    + " stirling.software.proprietary.policy.ledger.ProcessedFileStatus.PROCESSING")
+    int deleteUnseen(@Param("policyId") String policyId, @Param("cutoff") long cutoff);
+
+    @Modifying
+    @Transactional
+    @Query("delete from ProcessedFileEntity e where e.policyId = :policyId")
+    int deleteByPolicy(@Param("policyId") String policyId);
+
+    /** Boot recovery: after a restart every PROCESSING row is stale (single node). */
+    @Modifying
+    @Transactional
+    @Query(
+            "update ProcessedFileEntity e set e.status ="
+                    + " stirling.software.proprietary.policy.ledger.ProcessedFileStatus.INTERRUPTED,"
+                    + " e.updatedAt = :now"
+                    + " where e.status ="
+                    + " stirling.software.proprietary.policy.ledger.ProcessedFileStatus.PROCESSING")
+    int markAllProcessingInterrupted(@Param("now") long now);
+}
@@ -0,0 +1,17 @@
+package stirling.software.proprietary.policy.ledger;
+
+/** Lifecycle of one {@code (policy, file)} ledger row. */
+public enum ProcessedFileStatus {
+
+    /** Claimed; a run is in flight. */
+    PROCESSING,
+
+    /** Run completed at this version. */
+    DONE,
+
+    /** Run failed; skipped until the file changes (clear-history is the manual retry). */
+    ERROR,
+
+    /** Was PROCESSING when the JVM died; retried a bounded number of times. */
+    INTERRUPTED
+}
--- a/Show More
+++ b/Show More