PAYG rework: address code-review findings

- Gate the run-id header (#1): PaygChargeInterceptor now honours
  X-Stirling-Run-Id only when the internal-dispatch marker
  (X-Stirling-Automation) is also present. A raw external API call can no
  longer pin a constant run id to collapse separate same-content charges
  into one, which would defeat "charge per API call". InternalApiClient
  stamps both headers on every loopback sub-step, so legitimate automation
  is unaffected. Extracts hasAutomationHeader() (DRY across category/source
  determination) + two interceptor tests (honoured-with / ignored-without).

- Usage card cost (#3): show "avg per PDF" as a formatted currency amount
  (meter units x per-unit rate / input files) instead of raw units, matching
  the requested cents-per-PDF; omitted when the rate is unknown.

- Empty-state (#4): don't show "No processing yet" when there is unsynced
  instance-local (units-only) usage but zero synced PDFs.

- Style (#7): import AutomationRunContext / UUID instead of fully-qualified
  inline references in PipelineProcessor, PolicyEngine, AiWorkflowService.

- Refresh the now-stale PdfsProcessedCard class javadoc.

Author: ConnorYoh

app/core/src/main/java/stirling/software/SPDF/controller/api/pipeline/PipelineProcessor.java

@@ -10,6 +10,7 @@
 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.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;
@@ -74,9 +76,8 @@ PipelineResult runPipelineAgainstFiles(List<Resource> outputFiles, PipelineConfi
         // 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 (stirling.software.common.service.AutomationRunContext.Scope ignored =
-                stirling.software.common.service.AutomationRunContext.open(
-                        java.util.UUID.randomUUID().toString())) {
+        try (AutomationRunContext.Scope ignored =
+                AutomationRunContext.open(UUID.randomUUID().toString())) {
             return runPipelineAgainstFilesInternal(outputFiles, config);
         }
     }

app/proprietary/src/main/java/stirling/software/proprietary/policy/engine/PolicyEngine.java

@@ -21,6 +21,7 @@
 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.InternalApiTimeoutException;
 import stirling.software.common.service.JobOwnershipService;
@@ -202,8 +203,7 @@ private void runToCompletion(
         // 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 (stirling.software.common.service.AutomationRunContext.Scope runScope =
-                stirling.software.common.service.AutomationRunContext.open(runId)) {
+        try (AutomationRunContext.Scope runScope = AutomationRunContext.open(runId)) {
             try {
                 run.markRunning();
                 PolicyExecutionResult result =

app/proprietary/src/main/java/stirling/software/proprietary/service/AiWorkflowService.java

@@ -7,6 +7,7 @@
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.UUID;
 import java.util.stream.Collectors;
 
 import org.apache.commons.io.FilenameUtils;
@@ -27,6 +28,7 @@
 import lombok.extern.slf4j.Slf4j;
 
 import stirling.software.common.model.ApplicationProperties;
+import stirling.software.common.service.AutomationRunContext;
 import stirling.software.common.service.CustomPDFDocumentFactory;
 import stirling.software.common.service.FileStorage;
 import stirling.software.common.service.InternalApiTimeoutException;
@@ -159,9 +161,8 @@ public AiWorkflowResponse orchestrate(AiWorkflowRequest request, ProgressListene
         // One AI orchestration = one automation run. Scope a run id (on whichever thread runs
         // orchestrate — request thread for sync, stream-executor for streaming) so every tool
         // sub-step it dispatches via PolicyExecutor → InternalApiClient groups into one charge.
-        try (stirling.software.common.service.AutomationRunContext.Scope ignored =
-                stirling.software.common.service.AutomationRunContext.open(
-                        java.util.UUID.randomUUID().toString())) {
+        try (AutomationRunContext.Scope ignored =
+                AutomationRunContext.open(UUID.randomUUID().toString())) {
 
             // Key by opaque file id, not filename. Filenames aren't guaranteed unique across an
             // upload (users can rotate the same 'scan.pdf' twice), and the engine identifies files

app/saas/src/main/java/stirling/software/saas/payg/filter/PaygChargeInterceptor.java

@@ -285,10 +285,17 @@ private void doPreHandle(
         request.setAttribute(ATTR_INPUT_BYTES, totalInputBytes);
         request.setAttribute(ATTR_TOOL_ID, resolveToolId(request));
 
-        // Automation-run correlation id set by the orchestrator (pipeline / policy / AI-workflow)
-        // and propagated by InternalApiClient. Null for a direct one-off call → its own charge.
+        // Automation-run correlation id, honoured ONLY from an internal automation dispatch.
+        // InternalApiClient stamps X-Stirling-Automation on every loopback sub-step alongside the
+        // run id, so a genuine pipeline / policy / AI run always carries both. A raw external
+        // request that sets X-Stirling-Run-Id on its own is ignored (each such call stays its own
+        // charge): otherwise an API caller could pin a constant run id to collapse separate
+        // same-content calls into one charge, defeating "charge per API call". Null → standalone.
         String headerRunId = request.getHeader(AutomationRunContext.RUN_ID_HEADER);
-        String runId = (headerRunId != null && !headerRunId.isBlank()) ? headerRunId : null;
+        String runId =
+                (hasAutomationHeader(request) && headerRunId != null && !headerRunId.isBlank())
+                        ? headerRunId
+                        : null;
         ChargeContext ctx =
                 new ChargeContext(
                         currentUser.getId(),
@@ -504,9 +511,20 @@ private User resolveUser(Authentication auth) {
         }
     }
 
+    /**
+     * True when the request carries the internal-dispatch marker InternalApiClient stamps on every
+     * loopback sub-step ({@code X-Stirling-Automation: true}). This is the trust boundary for both
+     * the AUTOMATION billing category and for honouring {@code X-Stirling-Run-Id}: an external
+     * caller can't group charges via a run id without also declaring itself automation (which
+     * changes its own billing category).
+     */
+    private static boolean hasAutomationHeader(HttpServletRequest request) {
+        String header = request.getHeader(AUTOMATION_HEADER);
+        return header != null && "true".equalsIgnoreCase(header.trim());
+    }
+
     private static JobSource determineSource(HttpServletRequest request, Authentication auth) {
-        String automationHeader = request.getHeader(AUTOMATION_HEADER);
-        if (automationHeader != null && "true".equalsIgnoreCase(automationHeader.trim())) {
+        if (hasAutomationHeader(request)) {
             return JobSource.PIPELINE;
         }
         String desktopHeader = request.getHeader(DESKTOP_CLIENT_HEADER);
@@ -533,8 +551,7 @@ private static JobSource determineSource(HttpServletRequest request, Authenticat
      */
     private static BillingCategory determineCategory(
             HandlerMethod handler, HttpServletRequest request, Authentication auth) {
-        String automationHeader = request.getHeader(AUTOMATION_HEADER);
-        if (automationHeader != null && "true".equalsIgnoreCase(automationHeader.trim())) {
+        if (hasAutomationHeader(request)) {
             return BillingCategory.AUTOMATION;
         }
         RequiresFeature ann =

app/saas/src/test/java/stirling/software/saas/payg/filter/PaygChargeInterceptorTest.java

@@ -434,6 +434,52 @@ void preHandle_pipelineHeader_setsJobSourcePipeline() throws Exception {
                 .isEqualTo(stirling.software.saas.payg.model.JobSource.PIPELINE);
     }
 
+    @Test
+    void preHandle_runId_honouredOnlyWithAutomationHeader() throws Exception {
+        // An internal dispatch carries BOTH X-Stirling-Automation and X-Stirling-Run-Id, so the
+        // run id flows onto the ChargeContext (sub-steps of one run group into a single charge).
+        authenticateWithApiKey(makeUser(7L, 42L));
+        UUID jobId = UUID.randomUUID();
+        when(chargeService.openProcess(any(), anyList()))
+                .thenReturn(new ChargeOutcome(jobId, 1, ChargeOutcome.Disposition.OPENED));
+        org.mockito.ArgumentCaptor<stirling.software.saas.payg.charge.ChargeContext> ctxCaptor =
+                org.mockito.ArgumentCaptor.forClass(
+                        stirling.software.saas.payg.charge.ChargeContext.class);
+
+        MockMultipartHttpServletRequest req = newMultipart();
+        req.addFile(new MockMultipartFile("file", "x.pdf", "application/pdf", "abc".getBytes()));
+        req.addHeader("X-Stirling-Automation", "true");
+        req.addHeader("X-Stirling-Run-Id", "run-abc");
+
+        interceptor.preHandle(req, new MockHttpServletResponse(), handlerMethodForFakeController());
+
+        verify(chargeService).openProcess(ctxCaptor.capture(), anyList());
+        assertThat(ctxCaptor.getValue().runId()).isEqualTo("run-abc");
+    }
+
+    @Test
+    void preHandle_runIdWithoutAutomationHeader_isIgnored() throws Exception {
+        // A raw external API call that sets X-Stirling-Run-Id on its own must NOT be able to group
+        // charges — the run id is dropped so each call stays its own charge ("charge per API
+        // call").
+        authenticateWithApiKey(makeUser(7L, 42L));
+        UUID jobId = UUID.randomUUID();
+        when(chargeService.openProcess(any(), anyList()))
+                .thenReturn(new ChargeOutcome(jobId, 1, ChargeOutcome.Disposition.OPENED));
+        org.mockito.ArgumentCaptor<stirling.software.saas.payg.charge.ChargeContext> ctxCaptor =
+                org.mockito.ArgumentCaptor.forClass(
+                        stirling.software.saas.payg.charge.ChargeContext.class);
+
+        MockMultipartHttpServletRequest req = newMultipart();
+        req.addFile(new MockMultipartFile("file", "x.pdf", "application/pdf", "abc".getBytes()));
+        req.addHeader("X-Stirling-Run-Id", "run-spoofed");
+
+        interceptor.preHandle(req, new MockHttpServletResponse(), handlerMethodForFakeController());
+
+        verify(chargeService).openProcess(ctxCaptor.capture(), anyList());
+        assertThat(ctxCaptor.getValue().runId()).isNull();
+    }
+
     // --- BillingCategory categorisation + bypass fast-path -------------------------------------
 
     @Test

frontend/editor/public/locales/en-US/translation.toml

@@ -6483,7 +6483,8 @@ segmentApiLabel = "API"
 segmentAutomationDesc = "Automations & pipelines"
 segmentAutomationLabel = "Automation"
 sizeMultiplier = "{{formatted}} PDFs used a size multiplier"
-summary = "{{unique}} unique · {{units}} meter units · {{avg}} avg units/PDF"
+summary = "{{unique}} unique · {{units}} meter units · {{avg}} avg per PDF"
+summaryNoRate = "{{unique}} unique · {{units}} meter units"
 unit = "PDFs"
 
 [portal.billing.spendLimit]

frontend/editor/src/portal/components/billing/PdfsProcessedCard.tsx

@@ -1,19 +1,21 @@
 import { useTranslation } from "react-i18next";
 import { Card } from "@app/ui";
+import { formatMinor } from "@app/billing";
 import type { Wallet, WalletCategoryBreakdown } from "@portal/api/billing";
 import type { LocalUsage } from "@portal/api/link";
 
 /**
- * "PDFs processed this period" headline + a stacked split of where the metered
- * PDFs went. The split reuses the wallet's existing {@code categoryBreakdown}
- * (API / Agents / Automation — the same buckets the entitlement service tracks;
- * the "AI" bucket surfaces as "Agents" here). Real data only: the bar hides when
- * nothing metered has run yet.
+ * "PDFs processed this period" headline (the input-file count) plus a summary line
+ * separating that count from the size-scaled meter units, and a stacked split of
+ * where the PDFs went by category (API / Agents / Automation — the "AI" bucket
+ * surfaces as "Agents" here), driven by the wallet's per-category {@code categoryDocs}
+ * counts. Real data only: everything hides when nothing has run this period.
  *
- * <p>When a linked instance has accrued usage SaaS hasn't billed yet ({@code
- * unsynced}), it's folded into the headline + split so "current usage" reflects
- * work done since the last daily sync. The synced-vs-pending split is an internal
- * detail the customer doesn't need, so it's not surfaced — just the combined total.
+ * <p>Instance-local usage a linked instance has accrued but SaaS hasn't billed yet
+ * ({@code unsynced}) is units-only, so it folds into the meter-units figure (and the
+ * avg-per-PDF that derives from it) but NOT the PDF count or the per-category split,
+ * which reflect synced processing. The synced-vs-pending distinction is an internal
+ * detail, so only the combined unit total is surfaced.
  */
 const SEGMENTS: ReadonlyArray<{
   key: keyof WalletCategoryBreakdown;
@@ -70,7 +72,18 @@ export function PdfsProcessedCard({
   // API"); units are surfaced in the aggregate summary line, not per bucket.
   const perDocs: WalletCategoryBreakdown = wallet.categoryDocs;
   const totalDocs = perDocs.api + perDocs.ai + perDocs.automation;
-  const avgUnitsPerPdf = docs > 0 ? meterUnits / docs : 0;
+
+  // Average cost per PDF in minor currency units — meter units × the per-unit rate,
+  // spread over the input files processed. Shown only when the rate is known (free-tier
+  // and unknown-price snapshots omit the term rather than imply $0.00).
+  const rate = wallet.pricePerDocMinor;
+  const showAvgCost = docs > 0 && rate != null;
+  const avgCostMinor =
+    rate != null && docs > 0 ? (meterUnits / docs) * rate : 0;
+
+  // Something ran once there are either counted PDFs or metered units (instance-local
+  // unsynced usage is units-only, so it keeps the card out of the empty state).
+  const hasActivity = docs > 0 || meterUnits > 0;
 
   return (
     <Card padding="loose">
@@ -87,18 +100,27 @@ export function PdfsProcessedCard({
         </span>
       </div>
 
-      {docs > 0 ? (
+      {hasActivity ? (
         <>
           <p className="portal-billing__section-sub">
-            {t(
-              "portal.billing.pdfsProcessed.summary",
-              "{{unique}} unique · {{units}} meter units · {{avg}} avg units/PDF",
-              {
-                unique: uniquePdfs.toLocaleString(),
-                units: meterUnits.toLocaleString(),
-                avg: avgUnitsPerPdf.toFixed(1),
-              },
-            )}
+            {showAvgCost
+              ? t(
+                  "portal.billing.pdfsProcessed.summary",
+                  "{{unique}} unique · {{units}} meter units · {{avg}} avg per PDF",
+                  {
+                    unique: uniquePdfs.toLocaleString(),
+                    units: meterUnits.toLocaleString(),
+                    avg: formatMinor(avgCostMinor, wallet.currency),
+                  },
+                )
+              : t(
+                  "portal.billing.pdfsProcessed.summaryNoRate",
+                  "{{unique}} unique · {{units}} meter units",
+                  {
+                    unique: uniquePdfs.toLocaleString(),
+                    units: meterUnits.toLocaleString(),
+                  },
+                )}
           </p>
           {totalDocs > 0 ? (
             <>