Search keeps every locale's index in one Worker isolate, so docs content growth pushes /api/search over the Worker's memory limit (503, deploy rolled back) #393

What happened

#390 (ja PR 2 of 7 for #388, +11 ja pages) merged as 3bbc710. The post-deploy smoke check then failed twice, on main CI run 40862958838 and on its re-run. The failure card is #391.

• /api/search answered 503, Cloudflare's HTML error page, after 9–12 s. It failed for zh-Hant, de and fr on the first attempt, and for es, fr and the en nonce control on the re-run.
• Every page rendered.
• Both deploys rolled back, so the live site serves the docs(i18n): translate build/ and build/data/ into ja (#388, PR 1 of 7) #389 version.

On the previous run, 40861333382 for #389, all eight locales answered 200 in 3.6–5.3 s each. #392 reverts #390 so that main can deploy again.

Cause, measured

apps/docs/app/api/search/route.ts builds one Orama index per locale on that locale's first search (#301). It keeps each index in a module-level servers map that is never emptied, so one isolate holds as many indexes as locales it has served.

The measurement asked the built route under Node (next build at 3bbc710, then routeModule.userland.GET, --expose-gc), one ?query=permissions per locale in order. Heap is heapUsed after a forced GC.

• Index size. Each locale's index holds 30–40 MB. A Worker isolate has 128 MB, so two or three indexes and the rest of the app already fill it. That is why the 503s hit the second or third locale an isolate served.
• The prototype. One line, servers.clear() before a new build, keeps a single index. Heap levels off at about 86 MB.
• What is left. The remaining growth from 58 to 86 MB is the compiled page modules that page.data.load() imports for each locale. They stay in the module registry.
• Full ja coverage. With every missing ja page faked as a copy of the English, the one-index prototype levels off at about 94 MB.

Ask

Make /api/search fit the Worker with room to spare, now and after #388 brings ja to full coverage (79 more pages) and phase 3 adds further locales.

1. Bound the per-isolate index cache. A single entry is the measured minimum. Say what a locale switch then costs (measured 0.5–1.5 s per rebuild), and whether a second entry fits.
2. Look at what stays resident besides the index. The question is whether search can index without keeping every page module of every locale loaded. One option is structuredData written at build time to a per-locale JSON that the route reads, while keeping the /api/search server contract that Docs polish from the 2026-10-06 audit: muted-text contrast, the License table on phones, FAQ formatting, search ranking, glossary order, licence/license spelling #301 explains. Measure before and after.
3. Make the limit testable before deploy. Add a heap check to check-search-locales.mjs (or a sibling script) after the build. It asks every locale in turn, then fails above a budget that leaves headroom under 128 MB, such as 100 MB heapUsed after GC. A future content PR should then go red in CI, not after deploy.

Acceptance

• The heap table above, re-measured on the PR, levels off under the budget, both on main and with full ja coverage simulated.
• check-search-locales passes, with every locale's results unchanged and the Docs polish from the 2026-10-06 audit: muted-text contrast, the License table on phones, FAQ formatting, search ranking, glossary order, licence/license spelling #301 ranking still holding.
• After it lands, the post-deploy smoke check is green. Then docs(i18n): translate build/automation/ and build/interface/ into ja (#388, PR 2 of 7) #390's pages re-land (revert Revert #390 (ja build/automation and build/interface) so search fits the Worker again #392) and the smoke check stays green.