Merge pull request #18 from QRun-IO/fix/audit-quota-rotation

fix(scheduling): rotate audit requests across the daily quota

README.md

@@ -72,6 +72,10 @@ Tier, Scope, Source, Strategy, Metric, Comparator and Severity use dropdowns wit
 
 The changelog's changeset 10 seeds 13 reference budgets (Google's "good" thresholds and the Lighthouse category bands); nothing else is seeded. The target table is filled by Sync pages from sitemap, and the lab, finding, report, field, regression, change and comparison tables are filled by the qbit as it runs (empty is a normal start). Every table's help (`help/qbit-web-performance.yaml`, shown on the table screen) says how its rows get created, and the Setup card on the home shows what still needs doing. Budgets with source RUM are not evaluated yet (no real-user source is wired); LAB and CRUX budgets are.
 
+## Scheduled audit quota
+
+Set `withMaxRunsPerDay(300)` in the host configuration to reserve headroom below the default 500-run cap. Key-page schedules, full audits and manually queued runs share that daily allowance in the configured time zone. Scheduled requests prioritize page/device pairs never queued before, then those queued least recently. Quota-skipped rows do not advance that rotation, so large sitemaps continue through the remaining pairs on later days instead of repeatedly testing the first pages. Existing queued/running pairs still merge; manual selection keeps its requested order.
+
 ## In-app help
 
 The QBit registers [`help/qbit-web-performance.yaml`](src/main/resources/help/qbit-web-performance.yaml) with QQQ help bundles (RC.7 or later). Registration is metadata-only; core skips startup synchronization when the host has no `helpContent` table. App and table empty-state help remains available without Help installed.

src/main/java/com/kingsrook/qbits/webperf/processes/ScheduledSteps.java

@@ -209,7 +209,8 @@ public final class ScheduledSteps
       try
       {
          WebPerfService           service = WebPerfRuntime.forInput(input).service();
-         WebPerfService.QueuePlan plan    = service.enqueue(service.requestsFor(service.enabledTargets(keyOnly), "SCHEDULE", reason, Instant.now()), Instant.now());
+         Instant                  now     = Instant.now();
+         WebPerfService.QueuePlan plan    = service.enqueue(service.scheduledRequests(keyOnly, reason, now), now);
          LOG.info("Web performance tests queued", logPair("reason", reason), logPair("queued", plan.queue().size()), logPair("merged", plan.merged().size()),
             logPair("overCap", plan.overQuota().size()));
       }

src/main/java/com/kingsrook/qbits/webperf/service/WebPerfService.java

@@ -31,6 +31,8 @@ import java.time.Duration;
 import java.time.Instant;
 import java.time.ZoneId;
 import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.HashMap;
 import java.util.HashSet;
 import java.util.HexFormat;
 import java.util.LinkedHashMap;
@@ -448,6 +450,32 @@ public class WebPerfService
 
 
 
+   /*******************************************************************************
+    ** Scheduled requests, least recently queued page/strategy first. Quota skips
+    ** do not advance the rotation; never-tested pairs precede historical runs.
+    ** Manual requests keep the caller's ordering.
+    **
+    ** @param keyOnly only KEY pages
+    ** @param reason schedule description
+    ** @param now earliest start
+    ** @return requests ordered fairly across daily quota boundaries
+    ** @throws SQLException on a history read failure
+    *******************************************************************************/
+   public List<RunRequest> scheduledRequests(boolean keyOnly, String reason, Instant now) throws SQLException
+   {
+      List<RunRequest> requests = requestsFor(enabledTargets(keyOnly), "SCHEDULE", reason, now);
+      Map<String, Instant> lastQueued = new HashMap<>();
+      for(Map<String, Object> row : store.query("SELECT r.target_id, r.strategy, MAX(r.queued_at) AS last_queued FROM {lab_run} r JOIN {target} t ON t.id = r.target_id WHERE t.site_key = ? AND r.status <> 'SKIPPED_QUOTA' GROUP BY r.target_id, r.strategy", siteKey()))
+      {
+         lastQueued.put(WebPerfStore.asLong(row.get("target_id")) + "|" + row.get("strategy"), (Instant) row.get("last_queued"));
+      }
+      requests.sort(Comparator.comparing(request -> lastQueued.get(request.targetId() + "|" + request.strategy()),
+         Comparator.nullsFirst(Comparator.naturalOrder())));
+      return (requests);
+   }
+
+
+
    /*******************************************************************************
     ** Enabled pages, optionally only the KEY tier.
     **

src/test/java/com/kingsrook/qbits/webperf/WebPerfP1Test.java

@@ -271,6 +271,73 @@ class WebPerfP1Test
 
 
 
+   /*******************************************************************************
+    ** An odd daily cap rotates individual device strategies, not just pages.
+    ** Skipped rows and repeated scheduling must not starve the remaining pairs.
+    *******************************************************************************/
+   @Test
+   void scheduledQuotaRotatesPagesAndStrategies() throws Exception
+   {
+      config.withMaxRunsPerDay(3);
+      Instant dayOne = Instant.parse("2026-10-19T12:00:00Z");
+      WebPerfService service = service();
+      service.applySync(service.planSync(sitemap), dayOne);
+      WebPerfService.QueuePlan first = service.enqueue(service.scheduledRequests(false, "audit", dayOne), dayOne);
+      assertEquals(3, first.queue().size());
+      assertEquals(3, first.overQuota().size());
+      assertEquals(0, service.enqueue(service.scheduledRequests(false, "audit", dayOne), dayOne).queue().size());
+      store().update("UPDATE {lab_run} SET status = 'SUCCEEDED' WHERE status = 'QUEUED'");
+
+      Instant dayTwo = dayOne.plusSeconds(86400);
+      WebPerfService.QueuePlan second = service.enqueue(service.scheduledRequests(false, "audit", dayTwo), dayTwo);
+      assertEquals(3, second.queue().size());
+      List<String> firstPairs = first.queue().stream().map(run -> run.targetId() + "|" + run.strategy()).toList();
+      assertThat(second.queue().stream().map(run -> run.targetId() + "|" + run.strategy()).toList())
+         .doesNotContainAnyElementsOf(firstPairs);
+      assertEquals(6, store().query("SELECT DISTINCT target_id, strategy FROM {lab_run} WHERE status <> 'SKIPPED_QUOTA'").size());
+      assertThat(service.scheduledRequests(true, "key pages", dayTwo)).hasSize(2)
+         .allSatisfy(run -> assertEquals(SITE + "/", run.url()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Manual and key-page runs consume the same allowance as the full audit.
+    ** Persisted history rotates the remaining pairs after a service restart.
+    *******************************************************************************/
+   @Test
+   void scheduledQuotaSharesAllowanceAndSurvivesRestart() throws Exception
+   {
+      config.withMaxRunsPerDay(3);
+      Instant day = Instant.parse("2026-10-19T12:00:00Z");
+      WebPerfService service = service();
+      service.applySync(service.planSync(sitemap), day);
+      List<WebPerfService.RunRequest> manual = service.requestsFor(service.enabledTargets(false), "MANUAL", "selected page", day);
+      assertEquals(1, service.enqueue(List.of(manual.get(3)), day).queue().size());
+      assertEquals(2, service.enqueue(service.scheduledRequests(true, "key pages", day), day).queue().size());
+      assertEquals(0, service.enqueue(service.scheduledRequests(false, "audit", day), day).queue().size());
+      store().update("UPDATE {lab_run} SET status = 'SUCCEEDED' WHERE status = 'QUEUED'");
+
+      List<String> rotated = new ArrayList<>();
+      for(int nextDay = 1; nextDay <= 3; nextDay++)
+      {
+         Instant now = day.plusSeconds(86400L * nextDay);
+         WebPerfService restarted = new WebPerfService(new WebPerfRuntime(config), store());
+         assertEquals(2, restarted.enqueue(restarted.scheduledRequests(true, "key pages", now), now).queue().size());
+         WebPerfService.QueuePlan audit = restarted.enqueue(restarted.scheduledRequests(false, "audit", now), now);
+         assertEquals(1, audit.queue().size());
+         assertEquals(2, audit.merged().size());
+         WebPerfService.RunRequest queued = audit.queue().get(0);
+         assertThat(queued.url()).isNotEqualTo(SITE + "/");
+         rotated.add(queued.targetId() + "|" + queued.strategy());
+         store().update("UPDATE {lab_run} SET status = 'SUCCEEDED' WHERE status = 'QUEUED'");
+      }
+      assertThat(rotated).doesNotHaveDuplicates();
+      assertEquals(6, store().query("SELECT DISTINCT target_id, strategy FROM {lab_run} WHERE status <> 'SKIPPED_QUOTA'").size());
+   }
+
+
+
    /*******************************************************************************
     ** The Setup card reports pages, budgets, the lab runner and field data from
     ** the runtime's own resolution, with the next step for each.