Address PR review: trim comments, split checkout components, metering fixes

- Trim verbose/AI-style comments across account-link metering files
- Split checkout status views into CheckoutFinalizing/CheckoutActivationSlow
- Dedup: 5-min workflow-window parity with cloud (last_metered_at + window prop)
- Gate: deplete spend cap by local unsynced usage for capped subscriptions too
- DRY per-category mapping via BillingCategory EnumMap
- Meter hot path: hash during temp-file write (DigestOutputStream); load sync state once

Author: ConnorYoh

app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkClient.java

@@ -38,9 +38,8 @@
  *       /api/v1/instance/revoke-self}).
  * </ul>
  *
- * <p>Uses {@code java.net.http.HttpClient} (the established self-hosted outbound pattern, see
- * {@code AiEngineClient}). The base URL + client are injectable so tests can stub the SaaS
- * endpoint.
+ * <p>Uses {@code java.net.http.HttpClient} (the established self-hosted outbound pattern; see
+ * {@code AiEngineClient}); base URL + client are injectable so tests can stub SaaS.
  */
 @Slf4j
 @Service
@@ -94,11 +93,9 @@ public int status() {
     }
 
     /**
-     * Authoritative deny (401/403) from the entitlement endpoint — the device credential is revoked
-     * or invalid. Distinct from a transport/server failure (which returns {@code null} and fails
-     * open): the cache must BLOCK billable work on this rather than serve a stale entitled
-     * snapshot. Unchecked so it propagates cleanly through {@link #fetchEntitlement}'s transport
-     * try/catch.
+     * Authoritative deny (401/403) — the device credential is revoked or invalid. Unlike a
+     * transport/server failure (which returns {@code null} and fails open), the cache must BLOCK on
+     * this. Unchecked so it propagates through {@link #fetchEntitlement}'s transport try/catch.
      */
     public static final class RevokedException extends RuntimeException {
         private final int status;
@@ -150,11 +147,9 @@ public RegisterResult register(String supabaseJwt, String instanceName) throws I
     }
 
     /**
-     * Revokes this instance's own credential on the SaaS side ({@code POST
-     * /api/v1/instance/revoke-self}), authenticated by the device credential — a credential is
-     * allowed to revoke its own identity. Best-effort: returns {@code false} if SaaS is unreachable
-     * or rejects the call, so the caller (local unlink) can still clear locally and log the orphan
-     * row for follow-up. Idempotent on SaaS (already-revoked → still 204).
+     * Revokes this instance's own credential on the SaaS side, authenticated by that credential.
+     * Best-effort: returns {@code false} if SaaS is unreachable or rejects, so the caller (local
+     * unlink) can still clear locally and log the orphan for follow-up. Idempotent on SaaS.
      */
     public boolean revokeSelf(String deviceId, String deviceSecret) {
         try {
@@ -227,14 +222,11 @@ public InstanceEntitlement fetchEntitlement(String deviceId, String deviceSecret
     }
 
     /**
-     * Reports the current period's cumulative per-category units to {@code POST
-     * /api/v1/instance/sync} and returns the fresh entitlement in the same reply — one round-trip
-     * both reports usage and refreshes the gate. SaaS bills the delta against its own last-seen
-     * cumulative, so reporting the same totals twice charges nothing (idempotent).
-     *
-     * <p>Same three outcomes as {@link #fetchEntitlement}: 2xx → parsed snapshot; 401/403 → {@link
-     * RevokedException}; transport / other non-2xx / malformed body → {@code null} (caller must not
-     * advance its last-synced markers, so the usage retries on the next sync).
+     * Reports the period's cumulative per-category units to {@code POST /api/v1/instance/sync} and
+     * returns the fresh entitlement in the same reply — one round-trip both reports and refreshes.
+     * SaaS bills the delta against its last-seen cumulative, so resending the same totals is
+     * idempotent. Same three outcomes as {@link #fetchEntitlement}; on {@code null} the caller must
+     * not advance its last-synced markers so the usage retries next sync.
      */
     public InstanceEntitlement reportUsage(
             String deviceId,
@@ -248,8 +240,7 @@ public InstanceEntitlement reportUsage(
         try {
             ObjectNode root = mapper.createObjectNode();
             root.put("syncSeq", syncSeq);
-            // periodStart as an explicit ISO-8601 string so it round-trips to the SaaS
-            // LocalDateTime regardless of the mapper's time-module config.
+            // Explicit ISO-8601 string so it round-trips regardless of the mapper's time config.
             root.put("periodStart", periodStart.toString());
             ObjectNode units = root.putObject("cumulativeUnits");
             units.put("api", apiUnits);

app/proprietary/src/main/java/stirling/software/proprietary/accountlink/AccountLinkProperties.java

@@ -1,5 +1,7 @@
 package stirling.software.proprietary.accountlink;
 
+import java.time.Duration;
+
 import org.springframework.boot.context.properties.ConfigurationProperties;
 import org.springframework.stereotype.Component;
 
@@ -62,5 +64,13 @@ public static class Metering {
          * Block billable work after this many days with no successful sync (fail-open → closed).
          */
         private int graceDays = 3;
+
+        /**
+         * Dedup window for identical input sets. A re-run of the same inputs within this window is
+         * treated as workflow chaining and not re-charged; the same inputs run again after it are
+         * billed afresh. Mirrors the cloud's {@code payg.lineage.workflow-window} so the same op
+         * costs the same on the instance and in the cloud.
+         */
+        private Duration workflowWindow = Duration.ofMinutes(5);
     }
 }

app/proprietary/src/main/java/stirling/software/proprietary/accountlink/EntitlementCache.java

@@ -12,18 +12,13 @@
 import lombok.extern.slf4j.Slf4j;
 
 /**
- * Caches the linked team's entitlement so the request-time gate does not call the SaaS backend on
- * every billable request. Single-slot (one instance = one linked team), TTL-based.
+ * Caches the linked team's entitlement so the request-time gate needn't call SaaS on every billable
+ * request. Single-slot (one instance = one linked team), TTL-based.
  *
- * <p>Fail-open friendly for TRANSPORT failures: {@link #current()} returns the freshest snapshot it
- * has, even if a refresh just failed; it returns {@link Optional#empty()} only when nothing has
- * ever been fetched <i>and</i> the latest refresh failed (the gate treats empty as "unknown →
- * allow").
- *
- * <p>But an AUTHORITATIVE deny (revoked/invalid credential → {@link
- * AccountLinkClient.RevokedException}) is NOT a transport failure: the snapshot is replaced with a
- * {@link EntitlementState#REVOKED} blocked entitlement so the gate stops billable work immediately
- * rather than serving a stale entitled snapshot.
+ * <p>A transport failure fails open — {@link #current()} keeps serving the freshest snapshot it has
+ * and returns {@link Optional#empty()} ("unknown → allow") only when nothing was ever fetched. An
+ * authoritative deny ({@link AccountLinkClient.RevokedException}) does not: the snapshot is
+ * replaced with a {@link EntitlementState#REVOKED} entitlement so the gate blocks immediately.
  */
 @Slf4j
 @Service
@@ -63,9 +58,8 @@ public EntitlementCache(
      * not linked or the SaaS side is unreachable and we have no prior snapshot.
      */
     public Optional<InstanceEntitlement> current() {
-        // Single-flight: when stale, exactly one thread refreshes (blocking on the SaaS
-        // call) while concurrent callers serve the last snapshot — no thundering herd of
-        // synchronous round-trips on the billable hot path. Safe because the gate fails open.
+        // Single-flight: when stale, exactly one thread refreshes while concurrent callers serve
+        // the last snapshot — no thundering herd of round-trips on the billable hot path.
         if (isStale(snapshot) && refreshing.compareAndSet(false, true)) {
             try {
                 refresh();
@@ -77,16 +71,15 @@ public Optional<InstanceEntitlement> current() {
     }
 
     private boolean isStale(Snapshot snap) {
-        // fetchedAt is the last *attempt* time (stamped on success AND failure), so a failed
-        // fetch backs off for a full TTL instead of every billable request re-triggering a
-        // blocking round-trip against a dead/slow SaaS endpoint.
+        // fetchedAt is the last *attempt* time (stamped on success and failure), so a failed fetch
+        // backs off a full TTL instead of every request re-triggering a round-trip to a dead SaaS.
         return Duration.between(snap.fetchedAt(), Instant.now()).compareTo(ttl) >= 0;
     }
 
     /**
-     * Pulls a fresh snapshot. Keeps the previous entitlement on a TRANSPORT failure (fail-open) but
-     * still stamps the attempt time so re-fetches throttle to the TTL; on an AUTHORITATIVE deny
-     * (revoked credential) replaces it with a blocked snapshot so the gate stops billable work.
+     * Pulls a fresh snapshot. On a transport failure keeps the previous entitlement but stamps the
+     * attempt time so re-fetches throttle to the TTL; on an authoritative deny replaces it with a
+     * blocked snapshot.
      */
     void refresh() {
         Optional<DeviceCredential> cred = credentialStore.get();
@@ -101,15 +94,15 @@ void refresh() {
             if (fresh != null) {
                 snapshot = new Snapshot(fresh, Instant.now());
             } else {
-                // Unreachable / server error: keep the last known entitlement (may be null) but
-                // stamp the attempt so we don't hammer SaaS; the gate fails open in the meantime.
+                // Unreachable / server error: keep the last known entitlement but stamp the attempt
+                // so we don't hammer SaaS; the gate fails open meanwhile.
                 log.debug(
                         "Entitlement refresh failed; reusing last known snapshot, backing off a TTL");
                 snapshot = new Snapshot(snapshot.entitlement(), Instant.now());
             }
         } catch (AccountLinkClient.RevokedException e) {
-            // Authoritative deny — credential revoked/invalid. Do NOT fail open: block immediately
-            // rather than serving the stale entitled snapshot until the next unlink.
+            // Authoritative deny — block immediately rather than serving the stale entitled
+            // snapshot.
             log.info(
                     "Entitlement denied (HTTP {}); blocking billable work for the revoked credential",
                     e.status());
@@ -123,8 +116,8 @@ public void invalidate() {
     }
 
     /**
-     * Seeds the cache with an entitlement obtained out-of-band — the daily usage sync gets a fresh
-     * snapshot back in its reply, so adopting it here saves a redundant fetch. No-op on null.
+     * Seeds the cache with an entitlement obtained out-of-band (the sync reply carries a fresh
+     * one), saving a redundant fetch. No-op on null.
      */
     public void accept(InstanceEntitlement fresh) {
         if (fresh != null) {

app/proprietary/src/main/java/stirling/software/proprietary/accountlink/InstanceEntitlementGate.java

@@ -64,27 +64,30 @@ public GateDecision evaluate(boolean billable) {
         Optional<InstanceEntitlement> entitlement =
                 linked ? entitlementCache.current() : Optional.empty();
         boolean graceExpired = linked && entitlement.isEmpty() && isGraceExpired();
-        // For an unsubscribed team the one-time free grant is the ceiling, and it depletes in real
-        // time as billable work accrues locally between daily syncs. Subtract the not-yet-synced
-        // local usage from the last-synced free balance so the gate stops AT the grant, rather than
-        // running until the next sync charges the backlog and only then flips. Subscribed teams
-        // bill
-        // past the grant (their gate is the money cap), so this doesn't apply to them — pass 0.
+        // Deplete the applicable ceiling — free grant (unsubscribed) or spend cap (capped
+        // subscription) — by local usage not yet synced, so the gate stops in real time instead of
+        // overshooting until the next sync. An uncapped subscription has no ceiling to deplete → 0.
         long pendingUnsynced =
-                entitlement.map(e -> !e.subscribed()).orElse(false)
+                entitlement.map(InstanceEntitlementGate::depletesCeiling).orElse(false)
                         ? localUsageService.currentPeriodUnsynced().totalUnsyncedUnits()
                         : 0L;
         return decide(true, true, linked, entitlement, graceExpired, pendingUnsynced);
     }
 
+    /** Whether local unsynced usage pushes against a real ceiling (free grant or a spend cap). */
+    private static boolean depletesCeiling(InstanceEntitlement e) {
+        return !e.subscribed() || e.periodCapUnits() != null;
+    }
+
     /**
      * Pure decision function — no Spring, no I/O. {@code entitlement} empty means "unknown"
      * (unreachable): when linked, that fails open unless {@code graceExpired} (the metering grace
      * window elapsed with no authoritative contact), in which case it blocks.
      *
-     * @param pendingUnsyncedUnits billable units accrued locally since the last sync — subtracted
-     *     from an unsubscribed team's free balance so the grant depletes in real time (0 for
-     *     subscribed / unknown-entitlement cases, where it has no effect).
+     * @param pendingUnsyncedUnits billable units accrued locally since the last sync — depletes the
+     *     free grant (unsubscribed) or the spend cap (capped subscription) in real time so the gate
+     *     stops without waiting for the next sync (0 for uncapped-subscribed / unknown-entitlement
+     *     cases, where it has no effect).
      */
     public static GateDecision decide(
             boolean flagEnabled,
@@ -103,10 +106,9 @@ public static GateDecision decide(
             return GateDecision.block(GateDecision.Reason.NOT_LINKED);
         }
         if (entitlement.isEmpty()) {
-            // Linked but entitlement source unreachable. Normally fail open (never hard-block on
-            // our
-            // inability to reach billing) — but once the grace window has expired, block so the
-            // fail-open can't grant unbounded free/unbilled billable work indefinitely.
+            // Linked but entitlement unreachable: fail open, unless the grace window has expired
+            // (so
+            // the fail-open can't grant unbounded unbilled work forever).
             return graceExpired
                     ? GateDecision.block(GateDecision.Reason.GRACE_EXPIRED)
                     : GateDecision.allow(GateDecision.Reason.FAIL_OPEN);
@@ -122,11 +124,9 @@ public static GateDecision decide(
     }
 
     /**
-     * True when metering is on and SaaS has been unreachable past the grace window — i.e. it's been
-     * {@code graceDays} since the last authoritative contact. The reference is the last successful
-     * daily sync (persisted, survives restart), falling back to the link time for a never-synced
-     * instance. {@code graceDays <= 0} disables the backstop; metering off never blocks (nothing
-     * accrues, so a stale sync must not gate manual-free or pre-metering work).
+     * True when metering is on and it's been {@code graceDays} since the last authoritative contact
+     * (last successful sync, or link time if never synced). {@code graceDays <= 0} or metering off
+     * disables the backstop.
      */
     private boolean isGraceExpired() {
         AccountLinkProperties.Metering metering = properties.getMetering();
@@ -158,13 +158,17 @@ private static boolean entitled(InstanceEntitlement e, long pendingUnsyncedUnits
             return false;
         }
         if (e.subscribed()) {
-            // Subscribed: allowed unless a period cap is set and exceeded.
-            return e.periodCapUnits() == null || e.periodSpendUnits() < e.periodCapUnits();
+            if (e.periodCapUnits() == null) {
+                return true; // uncapped subscription
+            }
+            // Project the cap the way the grant is projected: synced paid spend plus the paid part
+            // of local usage not yet synced (free grant is consumed first, so only the excess
+            // bills) — stops at the cap in real time instead of overshooting until the next sync.
+            long pendingPaid = Math.max(0, pendingUnsyncedUnits - e.freeRemainingUnits());
+            return e.periodSpendUnits() + pendingPaid < e.periodCapUnits();
         }
-        // Unsubscribed: the free pool must cover both what SaaS has already charged (already netted
-        // out of freeRemainingUnits) and the local usage accrued since the last sync but not yet
-        // reported. Depleting by the pending delta stops the (grant+1)-th unit here in real time,
-        // instead of allowing it until a sync reconciles and the gate belatedly flips.
+        // Unsubscribed: free pool must cover SaaS-charged usage (in freeRemainingUnits) plus local
+        // usage not yet synced — deplete by the pending delta so we stop at the grant in real time.
         return e.freeRemainingUnits() - pendingUnsyncedUnits > 0;
     }
 }