Four-tier queue priority scheme for prerender jobs (CS-11758)

[habdelra]

Queue job priority is a worker-reservation floor: a worker dequeues only jobs whose priority is at or above its configured minimum, oldest-first among those. A higher number therefore reserves a job to more (and to more-dedicated) worker pools. This PR introduces the four-tier scheme that lets prerender-html work ride the same queue as indexing without competing with it:

priority	job
10	any user-initiated job
9	user-initiated prerender-html
1	any system-initiated job
0	system-initiated prerender-html

The prerender-html tiers sit one notch below their initiator tier so a pool's floor can take in an initiator's plain jobs with or without its (orders-of-magnitude slower) HTML rendering work. No producer of the 9/0 tiers exists yet — those constants are reserved for the prerender-html job.

What this changes:

• systemInitiatedPriority moves from 0 to 1, and a publish that doesn't state a priority now lands on the system tier. The daily-credit-grant cron enqueue joins the system tier as well (it previously used an off-scale value).
• Two new constants, userInitiatedPrerenderHtmlPriority = 9 and systemInitiatedPrerenderHtmlPriority = 0.
• The worker fleet keeps its two categories. The high-priority pool floors at 9 instead of 10, so once a producer emits user-initiated prerender-html jobs, the pool that guarantees user-facing latency serves them too — and still never touches system-tier work. The all-priority pool continues to serve jobs of any priority number.

Behavior today is unchanged: the high-priority pool at floor 9 sees only priority-10 jobs until something emits 9s, all-priority workers continue to process everything (including jobs already sitting in the queue at the former system priority), and system jobs at 1 remain servable by every pool that could serve them before. No dequeue site filters on an exact priority value: the queue's claim query uses priority >=, and the indexing dashboard displays the number raw. The page pool's high-priority threshold (deployed at 5) still sits strictly between the system tiers (0/1) and the user tiers (9/10). No deployment configuration changes are needed.

Existing queue, coalescing, and endpoint tests cover the moved constant (the startup-indexing test asserts systemInitiatedPriority via the constant); floor mechanics are exercised by the worker-priority queue tests with explicit values on both sides.

[github-actions]

Preview deployments

• Host staging preview

• Host production preview

Host Test Results

    1 files  ±0      1 suites  ±0   2h 38m 5s ⏱️ + 1m 1s
3 376 tests ±0  3 361 ✅ ±0  15 💤 ±0  0 ❌ ±0 
3 395 runs  ±0  3 380 ✅ ±0  15 💤 ±0  0 ❌ ±0 

Results for commit de9a062. ± Comparison against earlier commit 2ea3ce8.

Realm Server Test Results

    1 files  ±0      1 suites  ±0   10m 2s ⏱️ +31s
1 674 tests ±0  1 674 ✅ ±0  0 💤 ±0  0 ❌ ±0 
1 753 runs  ±0  1 753 ✅ ±0  0 💤 ±0  0 ❌ ±0 

Results for commit de9a062. ± Comparison against earlier commit 2ea3ce8.

[Copilot]

Pull request overview

Introduces a four-tier job-priority scheme for the shared queue so prerender-html work can share infrastructure with indexing while remaining reservable to specific worker pools (via a dequeue “floor” rather than strict priority ordering).

Changes:

• Defines new queue priority tiers (10/9/1/0), moves systemInitiatedPriority from 0 → 1, and defaults unspecified publishes to the system tier.
• Updates worker pool floors so the “high priority” pool can serve future user-initiated prerender-html (>=9) while never touching system-tier work.
• Updates cron enqueue priority and refreshes documentation/comments to align with the new scheme.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
README.md	Updates local-dev docs to describe worker pools in terms of “regardless of priority” rather than “system vs user initiated”.
packages/runtime-common/worker.ts	Adjusts JobInfo comment to refer to tier constants in queue.ts rather than hardcoded numeric meanings.
packages/runtime-common/queue.ts	Adds four-tier priority constants, updates default publish priority, and documents the tier model.
packages/runtime-common/prerender-headers.ts	Updates priority-header docs (but still needs a small correction per comment).
packages/runtime-common/definition-lookup.ts	Updates docs to reference tier constants instead of hardcoded numbers.
packages/realm-server/worker-manager.ts	Switches worker minimum-priority floors to the new prerender-html tier constants; updates CLI help text.
packages/realm-server/lib/cron-scheduler.ts	Enqueues daily-credit-grant at systemInitiatedPriority.
packages/host/app/services/store.ts	Updates explanatory comments about priority propagation to avoid hardcoded “0/10” semantics.
docs/aws-operations.md	Refreshes operational runbook wording and fixes markdown table formatting.
.claude/skills/prerender-sizing/SKILL.md	Updates the prerender-sizing skill docs (mostly formatting + tier references).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.