createRealm: enqueue exactly one priority-10 index job (CS-11157)

[habdelra]

Summary

Fixes the "realm creation hangs during deploy-triggered reindex storms" shape from CS-11157.

Realm creation now enqueues exactly one from-scratch-index job for the new realm, at userInitiatedPriority, so a backed-up queue of system-priority indexing work (e.g. a deploy-triggered reindex storm) does not stall the HTTP create-realm request.

Stacked on #4846 (the server.ts refactor) because the change lands in the extracted handlers/create-realm.ts.

How

Thread a new fromScratchIndexPriority option from the realm-creation handler through the mount pipeline so the realm's own #startup produces the single canonical job at the chosen priority:

createRealm
  → reconciler.lookupOrMount(url, { fromScratchIndexPriority: userInitiatedPriority })
    → ensureMounted(row, opts)
      → realm.start(opts)
        → #startup(opts)
          → realmIndexUpdater.fullIndex(
              opts.fromScratchIndexPriority ?? this.#fromScratchIndexPriority
            )
            → publishFullIndex(priority)   // .then() updates
                                            // #stats / #ignoreData /
                                            // #ignoreDataVersion

The option defaults to this.#fromScratchIndexPriority (currently systemInitiatedPriority) at every layer, so callers that don't pass it — boot-time pinned-realm mount, lazy-mount on first request — keep their existing behaviour.

prepareRealmFromRow (in main.ts) publishes the realm into realms[] + virtualNetwork synchronously, before realm.start() runs. So a worker _mtimes fetch that races the mount resolves via the existing mount in findOrMountRealm and never re-enters the lazy-mount path — no duplicate enqueue is possible from inside this server-instance during the mount window.

Regression test

realm-lifecycle-test.ts tightens the POST /_create-realm assertion from "at least one priority-10 job exists" to exactly one job, at userInitiatedPriority. With the previous shape (explicit enqueue at 10 + implicit enqueue at 0 via realm.start(), intended to coalesce), a worker claim landing between the two enqueues would have produced two rows and failed this assertion.

Files

• packages/runtime-common/realm.ts — start() / #startup() accept { fromScratchIndexPriority?: number }
• packages/realm-server/lib/realm-registry-reconciler.ts — lookupOrMount / ensureMounted pass the option through
• packages/realm-server/handlers/create-realm.ts — passes fromScratchIndexPriority: userInitiatedPriority to lookupOrMount; drops the deps it no longer needs (queue)
• packages/realm-server/routes.ts — drops queue from the CreateRealmDeps bag
• packages/realm-server/tests/server-endpoints/realm-lifecycle-test.ts — tightened assertion

Out of scope

handlers/handle-publish-realm.ts follows the same pattern (explicit enqueueReindexRealmJob followed by reconciler.lookupOrMount that re-enqueues via realm.start). Same fix would apply; deferred to a follow-up since this PR is scoped to realm creation per the ticket.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b62b6e8e0a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR aims to prevent duplicate from-scratch indexing jobs during realm creation by allowing startup indexing to be skipped when createRealm has already enqueued a high-priority job.

Changes:

• Adds a skipFromScratchIndex option through realm startup and reconciler mounting.
• Updates createRealm to enqueue one priority-10 index job, mount with startup indexing skipped, and await that job.
• Tightens lifecycle test expectations to exactly one user-priority from-scratch job.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
packages/runtime-common/realm.ts	Adds startup option to skip automatic from-scratch indexing.
packages/realm-server/lib/realm-registry-reconciler.ts	Threads mount options from lookup through realm startup.
packages/realm-server/handlers/create-realm.ts	Changes realm creation to enqueue and await a single explicit indexing job.
packages/realm-server/tests/server-endpoints/realm-lifecycle-test.ts	Updates regression assertion for exactly one high-priority job.

---

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

[github-actions]

Host Test Results

    1 files      1 suites   3h 25m 5s ⏱️
2 659 tests 2 644 ✅ 15 💤 0 ❌
5 262 runs  5 232 ✅ 30 💤 0 ❌

Results for commit 392ea9d.

Realm Server Test Results

    1 files  ±    0      1 suites  +1   9m 21s ⏱️ + 9m 21s
1 377 tests +1 377  1 377 ✅ +1 377  0 💤 ±0  0 ❌ ±0 
1 458 runs  +1 458  1 458 ✅ +1 458  0 💤 ±0  0 ❌ ±0 

Results for commit 392ea9d. ± Comparison against earlier commit acd64ac.