5474312
diff --git a/‎app/saas/src/main/java/stirling/software/saas/payg/charge/ChargeContext.java‎
Lines changed: 26 additions & 0 deletions b/‎app/saas/src/main/java/stirling/software/saas/payg/charge/ChargeContext.java‎
Lines changed: 26 additions & 0 deletions
diff --git a/‎app/saas/src/main/java/stirling/software/saas/payg/charge/ChargeOutcome.java‎
Lines changed: 19 additions & 0 deletions b/‎app/saas/src/main/java/stirling/software/saas/payg/charge/ChargeOutcome.java‎
Lines changed: 19 additions & 0 deletions
diff --git a/‎app/saas/src/main/java/stirling/software/saas/payg/charge/JobChargeService.java‎
Lines changed: 143 additions & 0 deletions b/‎app/saas/src/main/java/stirling/software/saas/payg/charge/JobChargeService.java‎
Lines changed: 143 additions & 0 deletions
diff --git a/‎app/saas/src/main/java/stirling/software/saas/payg/charge/JobInput.java‎
Lines changed: 24 additions & 0 deletions b/‎app/saas/src/main/java/stirling/software/saas/payg/charge/JobInput.java‎
Lines changed: 24 additions & 0 deletions
diff --git a/‎app/saas/src/main/java/stirling/software/saas/payg/job/JobContext.java‎
Lines changed: 37 additions & 0 deletions b/‎app/saas/src/main/java/stirling/software/saas/payg/job/JobContext.java‎
Lines changed: 37 additions & 0 deletions
@@ -0,0 +1,26 @@
+package stirling.software.saas.payg.charge;
+
+import stirling.software.saas.payg.model.JobSource;
+import stirling.software.saas.payg.model.ProcessType;
+
+/**
+ * Per-call context for {@link JobChargeService#openProcess}. Carries the caller's identity and what
+ * kind of process this is. Does NOT carry policy fields — the charge service resolves the effective
+ * policy from {@code PricingPolicyService} so a stale snapshot from the caller can't desync from
+ * the live policy.
+ */
+public record ChargeContext(
+        Long ownerUserId, Long ownerTeamId, JobSource source, ProcessType processType) {
+
+    public ChargeContext {
+        if (ownerUserId == null) {
+            throw new IllegalArgumentException("ownerUserId is required");
+        }
+        if (source == null) {
+            throw new IllegalArgumentException("source is required");
+        }
+        if (processType == null) {
+            throw new IllegalArgumentException("processType is required");
+        }
+    }
+}
@@ -0,0 +1,19 @@
+package stirling.software.saas.payg.charge;
+
+import java.util.UUID;
+
+/**
+ * Result of {@link JobChargeService#openProcess}. {@code processId} is the job the caller's tool
+ * call belongs to (newly opened or joined). {@code units} is what would have been debited had the
+ * call been in PAYG (live) mode — for OPENED, the actual classification × policy units; for JOINED,
+ * always 0 since the parent process already paid.
+ */
+public record ChargeOutcome(UUID processId, int units, Disposition disposition) {
+
+    public enum Disposition {
+        /** Started a new process; {@code units} reflects the would-be charge. */
+        OPENED,
+        /** Joined an existing process within window; no incremental charge. */
+        JOINED
+    }
+}
@@ -0,0 +1,143 @@
+package stirling.software.saas.payg.charge;
+
+import java.io.IOException;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Objects;
+
+import org.springframework.context.annotation.Profile;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.web.multipart.MultipartFile;
+
+import lombok.extern.slf4j.Slf4j;
+
+import stirling.software.saas.payg.docs.DocumentClassifier;
+import stirling.software.saas.payg.docs.DocumentMetrics;
+import stirling.software.saas.payg.job.JobContext;
+import stirling.software.saas.payg.job.JobService;
+import stirling.software.saas.payg.job.JoinOrOpenResult;
+import stirling.software.saas.payg.model.JobSource;
+import stirling.software.saas.payg.policy.PricingPolicy;
+import stirling.software.saas.payg.policy.PricingPolicyService;
+import stirling.software.saas.payg.repository.PaygShadowChargeRepository;
+import stirling.software.saas.payg.shadow.PaygShadowCharge;
+
+/**
+ * Orchestrates a tool call's open-process decision: look up the team's effective policy, resolve
+ * the step-limit ceiling for this caller surface, delegate the join-or-open decision to {@link
+ * JobService}, and — when a new process opens — compute the would-be charge and record a {@link
+ * PaygShadowCharge} row for comparison against the legacy engine.
+ *
+ * <p>Shadow mode only: this service never debits the wallet ledger or posts a Stripe meter event.
+ * The real-charging path lives in a separate follow-up and reuses the same orchestration — only the
+ * side-effect (shadow row vs ledger entry + Stripe call) differs.
+ *
+ * <p>The {@code legacyCreditsCharged} field on the shadow row is set to {@code 0} here. When the
+ * legacy {@code CreditService} is wired to call this service (separate PR), the legacy debit amount
+ * becomes available and {@code diffPct} can be computed against it; until then the shadow row
+ * captures the PAYG units only.
+ */
+@Service
+@Profile("saas")
+@Slf4j
+public class JobChargeService {
+
+    private final JobService jobService;
+    private final PricingPolicyService policyService;
+    private final DocumentClassifier classifier;
+    private final PaygShadowChargeRepository shadowRepository;
+
+    public JobChargeService(
+            JobService jobService,
+            PricingPolicyService policyService,
+            DocumentClassifier classifier,
+            PaygShadowChargeRepository shadowRepository) {
+        this.jobService = Objects.requireNonNull(jobService, "jobService");
+        this.policyService = Objects.requireNonNull(policyService, "policyService");
+        this.classifier = Objects.requireNonNull(classifier, "classifier");
+        this.shadowRepository = Objects.requireNonNull(shadowRepository, "shadowRepository");
+    }
+
+    /**
+     * Open a process (or join an existing one) for this tool call. Side effects: persists a {@code
+     * ProcessingJob} row plus input signatures, and — on OPENED — writes a {@code
+     * payg_shadow_charge} row carrying the would-be PAYG units.
+     */
+    @Transactional
+    public ChargeOutcome openProcess(ChargeContext ctx, List<JobInput> inputs) throws IOException {
+        Objects.requireNonNull(ctx, "ctx");
+        Objects.requireNonNull(inputs, "inputs");
+        if (inputs.isEmpty()) {
+            throw new IllegalArgumentException("inputs must not be empty");
+        }
+
+        PricingPolicy policy = policyService.getEffectivePolicy(ctx.ownerTeamId());
+        int stepLimit = resolveStepLimit(policy, ctx.source());
+
+        JobContext jobCtx =
+                new JobContext(
+                        ctx.ownerUserId(),
+                        ctx.ownerTeamId(),
+                        ctx.source(),
+                        ctx.processType(),
+                        policy.getId(),
+                        stepLimit);
+
+        List<Path> paths = inputs.stream().map(JobInput::path).toList();
+        JoinOrOpenResult result = jobService.joinOrOpen(jobCtx, paths);
+
+        if (result.disposition() == JoinOrOpenResult.Disposition.JOINED) {
+            return new ChargeOutcome(result.job().getId(), 0, ChargeOutcome.Disposition.JOINED);
+        }
+
+        int units = computeUnits(inputs, policy);
+        result.job().setDocUnits(units);
+
+        recordShadowRow(ctx, result.job().getId(), policy.getId(), units);
+
+        return new ChargeOutcome(result.job().getId(), units, ChargeOutcome.Disposition.OPENED);
+    }
+
+    private int resolveStepLimit(PricingPolicy policy, JobSource source) {
+        Integer fromPolicy =
+                policy.getStepLimits() == null ? null : policy.getStepLimits().get(source);
+        if (fromPolicy != null && fromPolicy > 0) {
+            return fromPolicy;
+        }
+        // Defensive default — every JobSource should have an entry per the V12 seed, but a
+        // hand-edited policy could be missing one. Fall back to the smallest documented limit
+        // (10 — WEB/API/DESKTOP_APP default) so an admin slip-up never spawns unbounded chains.
+        log.debug(
+                "PricingPolicy {} missing stepLimit for source={}; using fallback of 10.",
+                policy.getId(),
+                source);
+        return 10;
+    }
+
+    private int computeUnits(List<JobInput> inputs, PricingPolicy policy) {
+        List<MultipartFile> multiparts = inputs.stream().map(JobInput::multipart).toList();
+        DocumentMetrics metrics =
+                multiparts.size() == 1
+                        ? classifier.classify(multiparts.get(0), policy)
+                        : classifier.classify(multiparts, policy);
+        // Apply the policy-level minChargeUnits floor per design § 3.4. The classifier returns
+        // raw docUnits with a "non-empty input → ≥1" floor; the charge formula's
+        // max(min_charge_units, docUnits) layers on top.
+        return Math.max(policy.getMinChargeUnits(), metrics.docUnits());
+    }
+
+    private void recordShadowRow(
+            ChargeContext ctx, java.util.UUID jobId, Long policyId, int units) {
+        PaygShadowCharge row = new PaygShadowCharge();
+        row.setTeamId(ctx.ownerTeamId());
+        row.setJobId(jobId);
+        row.setPolicyId(policyId);
+        row.setPaygUnits(units);
+        // No legacy comparison yet — wired when the shadow path is connected to the legacy
+        // CreditService in the follow-up PR. Until then, diff stays at 0.
+        row.setLegacyCreditsCharged(0);
+        row.setDiffPct(0);
+        shadowRepository.save(row);
+    }
+}
@@ -0,0 +1,24 @@
+package stirling.software.saas.payg.charge;
+
+import java.nio.file.Path;
+
+import org.springframework.web.multipart.MultipartFile;
+
+/**
+ * One input file to a tool call, materialised. {@code path} is the on-disk copy the lineage
+ * detector hashes; {@code multipart} carries the size + content-type metadata the classifier needs.
+ * The pair is constructed by the ingress filter (PR-I7a filter) which materialises the request body
+ * exactly once. Tests construct it from a fixture file plus a {@code MockMultipartFile} wrapping
+ * the same bytes.
+ */
+public record JobInput(MultipartFile multipart, Path path) {
+
+    public JobInput {
+        if (multipart == null) {
+            throw new IllegalArgumentException("multipart is required");
+        }
+        if (path == null) {
+            throw new IllegalArgumentException("path is required");
+        }
+    }
+}
@@ -0,0 +1,37 @@
+package stirling.software.saas.payg.job;
+
+import stirling.software.saas.payg.model.JobSource;
+import stirling.software.saas.payg.model.ProcessType;
+
+/**
+ * Input to {@link JobService#joinOrOpen}: who owns the request, what process shape it is, which
+ * policy version applies, and the step-limit ceiling derived from that policy for this caller
+ * surface. {@code stepLimit} is resolved by the caller (typically {@code JobChargeService}) rather
+ * than re-fetched here so the service stays free of policy-lookup concerns.
+ */
+public record JobContext(
+        Long ownerUserId,
+        Long ownerTeamId,
+        JobSource source,
+        ProcessType processType,
+        Long policyId,
+        int stepLimit) {
+
+    public JobContext {
+        if (ownerUserId == null) {
+            throw new IllegalArgumentException("ownerUserId is required");
+        }
+        if (source == null) {
+            throw new IllegalArgumentException("source is required");
+        }
+        if (processType == null) {
+            throw new IllegalArgumentException("processType is required");
+        }
+        if (policyId == null) {
+            throw new IllegalArgumentException("policyId is required");
+        }
+        if (stepLimit <= 0) {
+            throw new IllegalArgumentException("stepLimit must be > 0");
+        }
+    }
+}