Opt private realms out of full reindex on startup

[habdelra]

Summary

• Default flip: only kind='bootstrap' realms (the CLI --path realms — base, catalog, skills) full-index on realm-server boot. kind='source' (user/private) and kind='published' realms now skip the boot reindex.
• A brand-new realm still builds its index on first boot — the isNewIndex branch in Realm.start() is independent of this flag, so first-time indexing of a private realm is unchanged.
• REALM_SERVER_FULL_INDEX_ON_STARTUP becomes a three-state override:

  value	behavior
  unset	bootstrap full-indexes; source / published skip (new default)
  true	all kinds full-index (matches prior behavior)
  false	no kind full-indexes (preserves the cached-index dev flow in scripts/import-cached-index.sh)

Why

On a developer machine, restarting the realm server triggered a from-scratch index of every private user realm under realms/, which is expensive and rarely what we want — the realm's existing index is still valid across a process restart. Bootstrap realms (base / catalog / skills) genuinely benefit from a from-scratch index on boot because platform code in those realms can change between boots, so they keep the eager behavior.

A kind='source' / kind='published' realm that genuinely needs a from-scratch index will still get one: either through isNewIndex (first boot of that realm's index) or via the dedicated /_full-reindex operator endpoint.

Compatibility notes

• Staging/prod post-deploy reindex is unaffected. That storm is driven by a separate CI hook → handle-post-deployment.ts:42 → full-reindex job, gated on a boxel-ui asset checksum change. It does not flow through fullIndexOnStartup. Flipping the startup default does not change post-deploy behavior; if an operator wants every realm to additionally reindex on every process restart in a deployed environment, set REALM_SERVER_FULL_INDEX_ON_STARTUP=true in the task definition.
• scripts/import-cached-index.sh flow preserved. That flow sets the env var to 'false', which now disables full-index for all kinds (including bootstrap), matching its prior effect.

Open question for review

I treated kind='published' as "private" (default off), grouping it with kind='source'. The user-facing definition of "public" in the original ask was "realms specified in the start script" — that's bootstrap, not published. Holler if kind='published' should be kept on the always-full-index path with bootstrap.

Test plan

• New unit tests packages/realm-server/tests/full-index-on-startup-test.ts cover the three-state resolution across all three realm kinds (12 cases, all passing).
• Clarified the existing packages/realm-server/tests/indexing-test.ts "newly-created realm full-indexes on first boot" test to explicitly document that it guards the isNewIndex branch — independent of fullIndexOnStartup — which is what guarantees a brand-new private realm still indexes on first boot after this flip.
• CI green.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d7057f4a6f

ℹ️ 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".

[github-actions]

Host Test Results

    1 files  ±0      1 suites  ±0   1h 30m 40s ⏱️ - 1m 56s
2 661 tests +2  2 646 ✅ +2  15 💤 ±0  0 ❌ ±0 
2 680 runs  +2  2 665 ✅ +2  15 💤 ±0  0 ❌ ±0 

Results for commit b271db1. ± Comparison against earlier commit d7057f4.

Realm Server Test Results

    1 files  ±0      1 suites  ±0   8m 36s ⏱️ -17s
1 395 tests ±0  1 395 ✅ ±0  0 💤 ±0  0 ❌ ±0 
1 479 runs  ±0  1 479 ✅ ±0  0 💤 ±0  0 ❌ ±0 

Results for commit b271db1. ± Comparison against earlier commit d7057f4.

[Copilot]

Pull request overview

Adjusts realm-server startup indexing behavior to avoid expensive from-scratch reindexing for user/private realms on process boot, while preserving eager indexing for bootstrap realms and keeping a three-state env override for operators/dev flows.

Changes:

• Introduces resolveFullIndexOnStartup(kind, envOverride) to compute per-realm startup full-index behavior from realm kind + REALM_SERVER_FULL_INDEX_ON_STARTUP.
• Updates realm-server boot to apply full-index-on-startup only for bootstrap realms by default, with 'true'/'false' overrides.
• Adds unit coverage for the three-state resolution and clarifies the existing “new realm indexes on first boot” test’s intent.

Reviewed changes

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

Show a summary per file

File	Description
packages/realm-server/main.ts	Switches startup full-index decision to per-realm resolution based on kind + env override; updates boot log field.
packages/realm-server/lib/full-index-on-startup.ts	New helper encapsulating three-state env override + kind-based default.
packages/realm-server/tests/full-index-on-startup-test.ts	New QUnit tests covering default/true/false/non-boolean env values across realm kinds.
packages/realm-server/tests/index.ts	Registers the new test file in the test suite list.
packages/realm-server/tests/indexing-test.ts	Renames and documents the “new realm full-indexes on first boot” test to clarify it guards isNewIndex.

---

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